Initial QuestionGraph library and documentation

scripts/deploy-dokku.ps1

@@ -0,0 +1,15 @@
+$ErrorActionPreference = 'Stop'
+$projectPath = Split-Path $PSScriptRoot -Parent
+$archiveName = 'questiongraph-' + [guid]::NewGuid().ToString('N') + '.tar'
+$archivePath = Join-Path ([System.IO.Path]::GetTempPath()) $archiveName
+$remotePath = '/tmp/' + $archiveName
+
+# Explicit inputs avoid uploading neighbouring repositories, secrets, or dependencies.
+tar -cf $archivePath -C $projectPath Dockerfile .dockerignore deploy src scripts tests package.json package-lock.json tsconfig.json vite.config.ts index.html README.md
+if ($LASTEXITCODE -ne 0) { throw 'Could not create deployment archive.' }
+scp $archivePath "root@peterstockings.com:$remotePath"
+if ($LASTEXITCODE -ne 0) { throw 'Could not upload deployment archive.' }
+ssh root@peterstockings.com "dokku git:from-archive questiongraph -- < $remotePath"
+if ($LASTEXITCODE -ne 0) { throw 'Dokku deployment failed. Check the build output.' }
+Write-Output 'Deployed: https://questiongraph.peterstockings.com'
+Write-Output "Deployment archive retained locally at $archivePath and remotely at $remotePath"

scripts/library-README.md

@@ -0,0 +1,51 @@
+# QuestionGraph library source
+
+This ZIP contains the actual lib directory, including its JSON Schema.
+It does not contain the demo, mock handlers, build tools, or node_modules.
+It is source code for a React + TypeScript application, not a prebuilt npm package.
+
+## Setup
+
+1. Copy lib into your application's src directory.
+2. Install runtime dependencies:
+
+   npm install react react-dom ajv@^8.20.0
+
+   Existing React applications usually already have react and react-dom.
+   Use React 18 or newer. For TypeScript, install the matching React type
+   packages and enable JSX, resolveJsonModule, and esModuleInterop.
+
+3. Import from the public entry point:
+
+   import { QuestionnaireRenderer } from "./lib";
+
+4. Pass your API-loaded questionnaire JSON as definition. Supply onSave,
+   onUpload (for file questions), and onSubmit using your own API client.
+
+   onSave(request) returns a promise resolving to { revision: number }.
+   onUpload(questionId, files) returns uploaded file references with
+   uploadId, name, size, and type.
+   onSubmit(answers, outcomes) returns a promise that rejects on failure.
+
+The compiler validates the questionnaire using the bundled JSON Schema.
+No separate schema URL is required. The backend must also validate submissions.
+
+## Styling
+
+Styles are not included in the lib directory. Supply your application styles
+for the renderer's shell, card, question-block, navigation, primary, secondary,
+message, error, and warning classes. Style disabled and focus states.
+The question-group fieldset is used for grouping and while saving; reset its
+border and padding if needed. Wrap the renderer in a questionnaire-pane element
+for its page-heading focus behavior.
+
+Use components to replace input controls, or renderField for full field layouts.
+Preserve the provided accessibility attributes and focus/blur callbacks.
+
+## Drafts
+
+Pass resumedDraft when mounting an existing draft. If using parseResumeDraft,
+preserve the validated server revision explicitly: the current parser defaults
+revision to zero. Remount to switch questionnaires or persistence modes.
+
+The archive is generated from the same library source as the documentation build.

scripts/library-download.mjs

@@ -0,0 +1,52 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { zipSync } from "fflate";
+
+export const archivePath = "downloads/questiongraph-library.zip";
+
+export async function createLibraryArchive(root) {
+  const files = {};
+  async function collect(directory, prefix) {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      const path = join(directory, entry.name);
+      const name = prefix + "/" + entry.name;
+      if (entry.isDirectory()) await collect(path, name);
+      else if (entry.isFile() && /\.(ts|tsx|json)$/.test(entry.name))
+        files[name] = new Uint8Array(await readFile(path));
+    }
+  }
+  await collect(join(root, "src/lib"), "questiongraph/lib");
+  files["questiongraph/README.md"] = new Uint8Array(await readFile(join(root, "scripts/library-README.md")));
+  return zipSync(files, { level: 6 });
+}
+
+// Build-time asset generation keeps the ZIP in sync with the shipped source.
+// Dev requests generate it afresh; no generated ZIP is committed.
+export function libraryDownload() {
+  let root;
+  let base;
+  return {
+    name: "questiongraph-library-download",
+    configResolved(config) { root = config.root; base = config.base; },
+    configureServer(server) {
+      server.middlewares.use(async (request, response, next) => {
+        const pathname = (request.url ?? "").split("?")[0];
+        if (pathname !== "/" + archivePath && pathname !== base + archivePath) return next();
+        if (request.method !== "GET" && request.method !== "HEAD") {
+          response.statusCode = 405; response.setHeader("Allow", "GET, HEAD"); response.end(); return;
+        }
+        try {
+          const archive = await createLibraryArchive(root);
+          response.setHeader("Content-Type", "application/zip");
+          response.setHeader("Content-Disposition", 'attachment; filename="questiongraph-library.zip"');
+          response.setHeader("Cache-Control", "no-store");
+          response.setHeader("Content-Length", archive.length);
+          response.end(request.method === "HEAD" ? undefined : Buffer.from(archive));
+        } catch (error) { next(error); }
+      });
+    },
+    async generateBundle() {
+      this.emitFile({ type: "asset", fileName: archivePath, source: await createLibraryArchive(root) });
+    },
+  };
+}