Initial QuestionGraph library and documentation

2026-09-13 12:59:36 +10:00
commit 0879a3e786
48 changed files with 7712 additions and 0 deletions
@@ -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.