@peripheries/renderer 0.23.1 → 0.24.0

package/README.md

@@ -6,13 +6,13 @@ the same in each.
 
 | Entry | Holds |
 |---|---|
-| `@peripheries/renderer/core` | Framework-free: cells and thin-ref hydration, references and conditions, the data context, walks and state names, cell props, layout, document structure, bundle refs and resolution, the shared store, `loadPageData(page, source)`, validation, `DIAGNOSTICS` and `PAGE_RULES` |
+| `@peripheries/renderer/core` | Framework-free: cells and thin-ref hydration, references and conditions, the data context, walks and state names (`layerName`, the layer catalog `LAYER_ROLES`), cell props, layout, document structure, bundle refs and resolution, the shared store, `loadPageData(page, source)`, validation, `DIAGNOSTICS` and `PAGE_RULES` |
 | `@peripheries/renderer/catalog` | `checkCatalog`: what a component repo runs on the knowledge it emits. The only entry with a JSON Schema validator (ajv) |
 | `@peripheries/renderer/react` | `PageRenderer`, `CellView`, `StructureView`, the cell states, `useContainerSize`, `useFormsRuntime` and its `FormSlotProps` and `FormAnswer` |
 | `@peripheries/renderer/runtime` | What a page boots with: the import map and boot script, the shims, `installRuntime`, the store bundles import |
 | `@peripheries/renderer/theme` | The org theme pipeline: `parseTheme` (version 1 or 2 in, version 2 out, with diagnostics), `themeTokens` (semantic overrides derived in OKLCH), `themeCss` (the `theme` layer), `checkTheme` (WCAG contrast) |
 | `@peripheries/renderer/print` | The print pipeline, framework-free: `collectBlocks` (the page map), `paginate`, `buildPrintLayout` (the packer's decision as CSS), `buildPageStylesheet` (`@page` geometry and margin boxes), running headers, `@printPolicy` parsing, print lint, `resolveDocumentProfile`, region bindings, map staleness, and the `layout.structure[].print` writer |
-| `@peripheries/renderer/forms` | The forms runtime, framework-free: the steps overlay and its model, conditions, modes, navigation, progress, deep links, and the persistence port (`FormsPort`); the React hook is `useFormsRuntime` in `/react` |
+| `@peripheries/renderer/forms` | The forms runtime, framework-free: the steps overlay and its model, conditions, modes, navigation, progress, deep links, and the persistence port (`FormsPort`), and the form-section contract's type (`FormSection`, `FormContentBlock`); the React hook is `useFormsRuntime` in `/react` |
 | `@peripheries/renderer/testing` | The golden pages, synthetic fixtures, and sources that serve them |
 | `@peripheries/renderer/styles.css` | Page and cell containers, the responsive buckets, placeholders and notices, in the `renderer` layer |
 
@@ -77,6 +77,22 @@ bundle's `ThemeProvider` export.
 
 ## Versions
 
+- **0.24.0** (2026-10-20): one renderer batch (CX).
+  - **`layerName(system)` and `LAYER_ROLES`** in `/core`: a system's state name (its layer's role,
+    else a registered layer's own type, `question`, `answer`, …) from the layer catalog, which is
+    generated from `public.system_layer` (`npm run gen:layers`; CI checks it is current). A host
+    and BEA's preview resolve a page's state names alike. An unregistered type has no name.
+  - **`FormSection` and `FormContentBlock`** in `/forms`: a form section cell's `props.section`,
+    contract v1 (`contracts/form-section.schema.json`): the section node's `id`, its authored
+    `sectionId`, `title`, `description?`, `sectionType?`, its `questions` (`{ key, label, required,
+    definition }`, the definition the form-definition contract's question or null) and its
+    `content` blocks (the form-definition contract's content block). Static: visibility, answers
+    and totals stay runtime (`forms.*`, `FormAnswer`, unchanged). v1 is the target shape: the
+    component engine doesn't emit `props.section` yet; the cutover is in the stack's
+    `contracts/README.md`.
+  - **`FormQuestionDefinition`'s** `options`, `validation`, `description` and `helpText` may be
+    null, as the form-definition contract's question has them.
+
 - **0.23.1** (2026-10-15): the published files carry no comments and no
   source maps (declarations included); this README is the documentation.
   No API change.

package/dist/core.js

@@ -90,6 +90,22 @@ function buildDataContext(input) {
 	}
 	return ctx;
 }
+var LAYER_ROLES = {
+	"answer": null,
+	"appraisal-system": "appraisal",
+	"data-system": "data",
+	"edits": null,
+	"model-system": "model",
+	"organisation": null,
+	"process-system": "process",
+	"question": null,
+	"submission": null
+};
+function layerName(s) {
+	if (s.system_layer) return s.system_layer.role ?? s.system_type ?? null;
+	if (!s.system_type || !Object.hasOwn(LAYER_ROLES, s.system_type)) return null;
+	return LAYER_ROLES[s.system_type] ?? s.system_type;
+}
 async function resolveSystems(source, page) {
 	const systems = !page.process_id ? {} : source.graphSystems ? systemsFromGraphs(await source.graphSystems(page.process_id)) : systemsFromProcess(await source.processSystems?.(page.process_id));
 	if (!systems.eng_data) {
@@ -1116,4 +1132,4 @@ function manifestPageFrom(graphNodeId, data) {
 		}
 	};
 }
-export { CONTENT_FIELDS, CORE_SPECIFIER, DIAGNOSTICS, EACH, EACH_DEFAULT_AS, HYDRATED_CELL_FIELDS, LAYOUT_TYPES, MAIN, PAGE_DOCUMENT, PAGE_RULES, PAGING_VARIABLES, PUBLIC, RENDER_FUNCTIONS, RENDER_FUNCTIONS_AHEAD, RESERVED_LABELS, RESPONSIVE_BUCKETS, SECTION_KINDS, STORE_FIELDS, STORE_SCOPES, STRUCTURE_FIELDS, TOOL_OWNED_KEYS, UnsafeDocumentError, VARIABLE_NAMESPACES, WALK_DIRECTIONS, _clearBundleCache, actionBindingKey, actionProblems, actionReferences, assembleCellProps, attachSelectionSetters, attachViewStateSetters, buildDataContext, bundleScope, cellAttributes, cellContext, cellPlacementStyle, cellPropSources, cellResolutionContext, clearScope, collectDeclarations, collectDescriptors, collectScopeIds, collectStatic, createStackStore, declaredActions, deriveElementReferences, deriveSectionNumbering, deriveSectionReferences, descriptorShape, eachFormProblems, editTarget, hasRef, isComponentExport, isEach, loadBundle, loadBundles, loadBundlesSettled, loadPageData, loadScope, manifestPageFrom, mergeSectionReferences, mergeStates, nearestNames, needsWalk, nodePrintStyle, normalizeActionDeclaration, normalizeCell, normalizeRef, normalizeStructure, numberingFor, orderByVariable, pageBundleRefs, pageBundles, pageContainerStyle, pageContext, pageRuntimeFromValues, pageScopeKey, pageVariables, passesConditions, patchAt, prepareDocument, projectCellActions, projectCellData, projectLive, projectModule, projectScopeKey, projectSelections, projectViewState, queryKey, readField, readWalk, refKey, referencedLabels, referencesFor, resolveAction, resolveCell, resolveComponent, resolveDataSystem, resolveDeclarations, resolveDescriptorVariables, resolveReferences, resolveScopeId, resolveSystems, resolveWalkStart, rootCells, runtimeReady, saveScope, sectionAnchor, selectionIssues, selectionShape, settled, shallowEqualBundle, shapeAt, stateNames, stateValue, structureIssues, systemsFromGraphs, systemsFromProcess, tableOfContents, usesStructureLayout, validateCell, validateDescriptor, validateManifest, validatePage, variableLabels, variableReferences, walkKey, walkRequest };
+export { CONTENT_FIELDS, CORE_SPECIFIER, DIAGNOSTICS, EACH, EACH_DEFAULT_AS, HYDRATED_CELL_FIELDS, LAYER_ROLES, LAYOUT_TYPES, MAIN, PAGE_DOCUMENT, PAGE_RULES, PAGING_VARIABLES, PUBLIC, RENDER_FUNCTIONS, RENDER_FUNCTIONS_AHEAD, RESERVED_LABELS, RESPONSIVE_BUCKETS, SECTION_KINDS, STORE_FIELDS, STORE_SCOPES, STRUCTURE_FIELDS, TOOL_OWNED_KEYS, UnsafeDocumentError, VARIABLE_NAMESPACES, WALK_DIRECTIONS, _clearBundleCache, actionBindingKey, actionProblems, actionReferences, assembleCellProps, attachSelectionSetters, attachViewStateSetters, buildDataContext, bundleScope, cellAttributes, cellContext, cellPlacementStyle, cellPropSources, cellResolutionContext, clearScope, collectDeclarations, collectDescriptors, collectScopeIds, collectStatic, createStackStore, declaredActions, deriveElementReferences, deriveSectionNumbering, deriveSectionReferences, descriptorShape, eachFormProblems, editTarget, hasRef, isComponentExport, isEach, layerName, loadBundle, loadBundles, loadBundlesSettled, loadPageData, loadScope, manifestPageFrom, mergeSectionReferences, mergeStates, nearestNames, needsWalk, nodePrintStyle, normalizeActionDeclaration, normalizeCell, normalizeRef, normalizeStructure, numberingFor, orderByVariable, pageBundleRefs, pageBundles, pageContainerStyle, pageContext, pageRuntimeFromValues, pageScopeKey, pageVariables, passesConditions, patchAt, prepareDocument, projectCellActions, projectCellData, projectLive, projectModule, projectScopeKey, projectSelections, projectViewState, queryKey, readField, readWalk, refKey, referencedLabels, referencesFor, resolveAction, resolveCell, resolveComponent, resolveDataSystem, resolveDeclarations, resolveDescriptorVariables, resolveReferences, resolveScopeId, resolveSystems, resolveWalkStart, rootCells, runtimeReady, saveScope, sectionAnchor, selectionIssues, selectionShape, settled, shallowEqualBundle, shapeAt, stateNames, stateValue, structureIssues, systemsFromGraphs, systemsFromProcess, tableOfContents, usesStructureLayout, validateCell, validateDescriptor, validateManifest, validatePage, variableLabels, variableReferences, walkKey, walkRequest };

package/dist/react.js

@@ -662,7 +662,7 @@ function useFormsRuntime(o) {
 	const steps = useMemo(() => visibleSteps(o.model, values), [o.model, values]);
 	const [at, setAt] = useState(() => positionFromLink(visibleSteps(o.model, answeredOf(o.initial)), mode, o.link ?? {}));
 	const here = settle(steps, mode, at);
-	const readOnly = isReadOnlyStatus(status);
+	const readOnly = o.readOnly === true || isReadOnlyStatus(status);
 	const opts = useRef(o);
 	opts.current = o;
 	const expected = useRef(new Map(Object.entries(o.initial).map(([k, a]) => [k, a.stateId ?? null])));
@@ -713,7 +713,7 @@ function useFormsRuntime(o) {
 		return chain.current;
 	}, []);
 	const change = useCallback((key, value) => {
-		if (isReadOnlyStatus(status)) return;
+		if (readOnly) return;
 		setValues((v) => ({
 			...v,
 			[key]: value
@@ -721,7 +721,7 @@ function useFormsRuntime(o) {
 		pending.current.set(key, value);
 		if (timer.current) clearTimeout(timer.current);
 		timer.current = setTimeout(() => void flush(), FORM_SAVE_DEBOUNCE_MS);
-	}, [flush, status]);
+	}, [flush, readOnly]);
 	useEffect(() => {
 		const onLeave = () => void flush();
 		window.addEventListener("pagehide", onLeave);
@@ -841,7 +841,7 @@ function useFormsRuntime(o) {
 			refusal: refusals[q.key] ?? null,
 			inputId: answerInputId(q.key),
 			...port.upload ? { upload: async (file) => {
-				if (isReadOnlyStatus(status)) return {
+				if (readOnly) return {
 					ok: false,
 					refusal: words("FORM_NOT_OPEN")
 				};
@@ -919,7 +919,7 @@ function useFormsRuntime(o) {
 			run: () => void runSubmit(),
 			blocked: o.model.submitRequired === "block" && allMissing.length > 0
 		} : null,
-		reopen: status === "submitted" && o.model.submittable !== false ? {
+		reopen: status === "submitted" && !o.readOnly && o.model.submittable !== false ? {
 			label: "Edit answers",
 			run: () => void runReopen()
 		} : null,

package/dist/types/core/index.d.ts

@@ -1,6 +1,7 @@
 export { CONTENT_FIELDS, hasRef, HYDRATED_CELL_FIELDS, normalizeCell, resolveCell, rootCells, STORE_FIELDS, type CellSource, type ResolvedCell } from './cells.js';
 export { buildDataContext, collectDeclarations, collectDescriptors, collectStatic, readField, resolveDeclarations, type ResolvedDeclaration, type StateRead } from './data-context.js';
 export { mergeStates, needsWalk, readWalk, referencedLabels, RESERVED_LABELS, resolveWalkStart, stateNames, stateValue, systemsFromGraphs, systemsFromProcess, walkKey, walkRequest, type Diagnostic, type GraphSystem, type ProcessSystems, type RawWalk, type WalkBinding, type WalkRequest, type WalkStart, } from './graph.js';
+export { LAYER_ROLES, layerName, type LayerType } from './layers.js';
 export { loadPageData, resolveDataSystem, resolveSystems, type CellData, type CellWalk, type GraphSource, type NodeRecordRow, type PageRuntime, type PageScope, type QueryPage, type ReadContext, type StateRow } from './load-page.js';
 export { descriptorShape, orderByVariable, PAGING_VARIABLES, pageVariables, prepareDocument, queryKey, RENDER_FUNCTIONS, RENDER_FUNCTIONS_AHEAD, resolveDescriptorVariables, selectionShape, shapeAt, UnsafeDocumentError, validateDescriptor, VARIABLE_NAMESPACES, variableLabels, variableReferences, type PreparedDocument, type ResolvedVariables, type SelectionShape, } from './query.js';
 export { selectionIssues } from './selected.js';

package/dist/types/core/layers.d.ts

@@ -0,0 +1,8 @@
+import { LAYER_ROLES, type LayerType } from './layers.gen.js';
+export { LAYER_ROLES, type LayerType };
+export declare function layerName(s: {
+    system_type: string | null;
+    system_layer?: {
+        role: string | null;
+    } | null;
+}): string | null;

package/dist/types/core/layers.gen.d.ts

@@ -0,0 +1,12 @@
+export declare const LAYER_ROLES: {
+    readonly answer: null;
+    readonly "appraisal-system": "appraisal";
+    readonly "data-system": "data";
+    readonly edits: null;
+    readonly "model-system": "model";
+    readonly organisation: null;
+    readonly "process-system": "process";
+    readonly question: null;
+    readonly submission: null;
+};
+export type LayerType = keyof typeof LAYER_ROLES;

package/dist/types/forms/index.d.ts

@@ -1,3 +1,4 @@
 export { CONDITION_OPS, evaluateCondition, isConditionOp, normalizeCondition, normalizeOperator, type Condition, type ConditionClause, type ConditionOp } from './conditions.js';
 export { defaultMode, enterAdvances, fromPageSteps, goTo, goToQuestion, isReadOnlyStatus, linkTo, missing, move, positionFromLink, positionsOf, progress, questionsOf, settle, stepKind, visibleSteps, type DisplayMode, type FormChapter, type FormItem, type FormItemKind, type FormLink, type FormModel, type FormQuestion, type FormQuestionDefinition, type FormStep, type Position, type StepKind, type StepProgress, type SubmissionStatus, } from './model.js';
 export type { AnswerToSave, FileToUpload, FormsPort, FormsRefusal, FormsResult } from './port.js';
+export type { FormContentBlock, FormSection } from './section.js';

package/dist/types/forms/model.d.ts

@@ -10,10 +10,10 @@ export type FormQuestion = {
 };
 export type FormQuestionDefinition = {
     type: string;
-    options?: unknown[];
-    validation?: Record<string, unknown>;
-    description?: string;
-    helpText?: string;
+    options?: unknown[] | null;
+    validation?: Record<string, unknown> | null;
+    description?: string | null;
+    helpText?: string | null;
 };
 export type FormItemKind = 'question' | 'content' | 'document' | 'review' | 'upload' | 'other';
 export type FormItem = {

package/dist/types/forms/section.d.ts

@@ -0,0 +1,22 @@
+import type { Condition } from './conditions.js';
+import type { FormQuestionDefinition } from './model.js';
+export type FormContentBlock = {
+    id: string;
+    type: string;
+    when?: Condition | null;
+    [prop: string]: unknown;
+};
+export type FormSection = {
+    id: string;
+    sectionId: string;
+    title: string;
+    description?: string;
+    sectionType?: string;
+    questions: Array<{
+        key: string;
+        label: string;
+        required: boolean;
+        definition: FormQuestionDefinition | null;
+    }>;
+    content: FormContentBlock[];
+};

package/dist/types/react/use-forms-runtime.d.ts

@@ -114,6 +114,7 @@ export type FormsRuntimeOptions = {
         stateId?: string | null;
     }>;
     status: SubmissionStatus | null;
+    readOnly?: boolean;
     visited?: string[];
     link?: FormLink;
     phone?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peripheries/renderer",
-  "version": "0.23.1",
+  "version": "0.24.0",
   "description": "The one renderer for pages of federated component bundles: a framework-free core, a React renderer, the runtime a page boots with, and golden pages for testing.",
   "type": "module",
   "sideEffects": [