@forming/react 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,86 @@
+Forming Source Available License 1.0
+
+Copyright (c) 2026 Forming contributors.
+
+1. Scope and definitions
+
+This license covers the Forming implementation, tools, examples and other
+original material supplied with this notice (the Software). Each copyright
+holder grants rights only to material they own or are authorized to license.
+Third-party components and material expressly offered under another license
+remain governed by those terms. See NOTICE.md and the attribution notices.
+
+An Internal Use is use by your employees or contractors solely for your own
+organization's operations. Customers and other external users are not internal
+users. A Commercial Product is a product or service sold, licensed for a fee,
+monetized through advertising, or offered to support a paid business offering,
+including its free tiers, trials and bundled features.
+
+2. Permission
+
+Subject to the conditions below, you may use, inspect, copy and modify the
+Software for personal, educational, noncommercial and Internal Use. Internal
+Use by a commercial business is permitted without payment.
+
+You may also use the Software on the backend of a Commercial Product to compile
+definitions, validate data or process results, provided that you do not offer
+the Software's capabilities as a service or use the Software in that product's
+external user interface as described in section 3.
+
+You may redistribute unmodified or modified copies without charge for uses
+permitted by this license. You must include this license and all applicable
+copyright, attribution and third-party notices. Identify changes you make.
+Recipients receive their rights from the applicable copyright holders under
+these same terms; you may not grant broader rights to the Software.
+
+3. Uses requiring separate written permission
+
+Without a separate written agreement from the applicable copyright holders,
+you may not, directly or through another party:
+
+(a) sell, rent, sublicense for a fee, or otherwise charge for copies of or
+access to the Software, including modified, rebranded or bundled versions;
+
+(b) offer the Software or its form authoring, rendering, compilation, validation
+or runtime capabilities to external users as a hosted, managed, API or other
+commercial service, including through a wrapper or a free tier of that service;
+
+(c) embed, distribute or otherwise use the Software to provide any part of a
+Commercial Product's external user interface, including ordinary rendered
+forms, widgets, editors, visual builders and white-label interfaces.
+
+These restrictions apply even if the Software is only one part of an offering
+or is not separately priced. They do not prohibit Internal Use or the backend
+integration expressly allowed in section 2. Charging for consulting, installation
+or support is allowed when the resulting use itself complies with this license.
+
+4. Your material and other rights
+
+You retain ownership of your independently authored form definitions, submitted
+data and other original output. This license does not require you to disclose
+your application's source code. Output that contains Software code remains
+subject to this license to the extent it contains that code. No trademark rights
+are granted. Rights not expressly granted are reserved.
+
+5. Termination
+
+Your permissions end if you violate this license. If you correct your first
+violation within 30 days of receiving written notice from a copyright holder,
+your permissions are restored. Further violations require express written
+reinstatement. Termination does not remove obligations that apply to copies
+already distributed.
+
+6. Warranty and liability
+
+TO THE EXTENT PERMITTED BY LAW, THE SOFTWARE IS PROVIDED "AS IS", WITHOUT
+WARRANTIES, INCLUDING MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. COPYRIGHT HOLDERS AND CONTRIBUTORS ARE NOT LIABLE FOR CLAIMS,
+DAMAGES OR OTHER LIABILITY ARISING FROM THE SOFTWARE OR ITS USE, WHETHER IN
+CONTRACT, TORT OR OTHERWISE.
+
+7. Additional permission
+
+Contact the project maintainers through the repository from which you obtained
+the Software to request a commercial agreement. An unanswered request does not
+grant permission. A separate written agreement controls only to the extent it
+expressly grants different rights.

package/NOTICE.md

@@ -0,0 +1,18 @@
+# Licensing notices
+
+The Forming implementation is covered by the [Forming Source Available License](LICENSE).
+This license permits internal business use and commercial backend integration,
+but requires separate written permission for resale, commercial hosted Forming
+services and external UI use in commercial products. It is not an open-source
+license. The license text controls over this summary.
+
+The specifications and adapted specification text retain their existing
+[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) terms and attribution.
+See `core/ATTRIBUTION.md` and `website/ATTRIBUTION.md` in the source repository.
+The implementation license does not replace those rights or revoke rights
+granted under earlier licenses.
+
+Dependencies retain their own licenses. Rust dependency notices are collected
+under `tools/skills/notices/` in the source repository and included with packaged
+WASM distributions. JavaScript and Go dependency notices are supplied by their
+respective packages. Preserve applicable notices when redistributing bundles.

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+# Forming React renderer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Independent React/TypeScript development package. The Rust/WASM runtime remains the owner of validation, calculations, branching, provider freshness, row identity and Submit. This renderer is implemented and tested, but is not a published or launch-certified package.
+
+## Presentation plugins
+
+Presentation plugins are ordinary plugins with a `present` capability. Register them with `createExtensions(...)` alongside the rest and pass that registry as `<FormingForm extensions={plugins}>`. `choiceCards({identity, fields})` supplies selectable sections with headings and multiline text for local options, preserving native radio/checkbox behavior and exact values. Custom `present.choice` callbacks use the same presentation-only contract. See the [plugin API and example](../../extensions/README.md#selectable-sections-in-react).
+
+## Use
+
+`@forming/integrations` is a peer dependency: install it beside the renderer so your app, the renderer and any plugins share one copy of its exact-number `JsonNumber`. Until the packages are published, install packed tarballs (`npm pack` in this folder and in `core/hosts/javascript`); `npm run test:pack` checks that install in a fresh app outside this checkout.
+
+```sh
+npm install react react-dom ./forming-integrations-0.1.0-dev.1.tgz ./forming-react-0.1.0-dev.1.tgz
+```
+
+Build the sibling Rust/WASM project and provide its long-lived `FormRuntime` instance:
+
+```tsx
+import {createController, FormingForm} from '@forming/react';
+import '@forming/react/styles.css';
+
+const controller = createController(runtime);
+// Keep this controller stable for the lifetime of the runtime.
+<FormingForm controller={controller} />;
+```
+
+The optional stylesheet provides a scoped, responsive theme without styling the rest of your application. The default `presentation="embedded"` uses compact controls. Use `presentation="focused"` for larger questions, generous spacing and native radio/checkbox cards for up to eight local choices. Short local lists are native radios and checkboxes in both presentations: up to five single-choice options and yes/no questions (labelled Yes/No) in embedded mode, up to eight in focused mode, and consent (`mustBe true`) is a single “I accept” box. Multiple choice with up to eight local options is a checkbox list in both presentations, under a "Choose as many as you like" hint (`text.chooseMany`): a multi-select list box hides that several answers are allowed. Letter keys (A–H) pick choices in focused presentation only. Remote and longer option lists remain dropdowns. Switching presentation preserves answers and pending editor buffers.
+
+Focused mode follows your authored pages; it does not turn every field into a page or auto-advance after answering. Put questions inside `page` blocks with Next/Back actions when you want a step-by-step experience. Keyboard focus follows page navigation, without stealing focus on initial mount.
+
+For a one-question-at-a-time flow, put one question per `page`; a page that holds only `display` content (restricted Markdown) renders as a welcome or closing screen. Keyboard: Enter activates the page's Continue (or Submit), Cmd/Ctrl+Enter does so from a textarea, and A–H pick a focused-mode choice card (in the focused question, or anywhere on a page whose only card question it is). Letters typed into text controls stay text. Focused mode shows a "Press Enter ↵" hint on pointer devices. Blocked Next/Submit/Validate buttons stay activatable (`aria-disabled`) so the core can reveal what is missing; a page reached by Next shows no errors until the respondent tries to continue from it, and the error summary counts the current page only. Pages slide in the direction of travel.
+
+`detail="standard"` (default) shows respondent-facing controls only. `detail="exact"` adds the data-level controls: explicit Set to null, Use empty list, the portable date/time text beside the pickers and locale echoes of values that already read the same. In standard detail dates and times are edited with the pickers alone, unless saved text is something the pickers cannot show. Fields with `maxLength` show a counter (always for textareas, near the limit otherwise).
+
+Customize the theme on a parent element using CSS variables such as `--forming-primary`, `--forming-on-primary`, `--forming-surface`, `--forming-soft`, `--forming-ink`, `--forming-muted`, `--forming-border`, `--forming-error`, `--forming-error-background`, `--forming-success`, `--forming-radius`, `--forming-control-radius`, `--forming-font` and `--forming-width`. Hover, focus-ring, stronger-border and tinted shades are derived from these with `color-mix()`, so a handful of tokens re-themes every state. Layouts space their children with `gap` rather than per-field margins, and repeat items render as cards with an item header and icon tools (icon-only in narrow containers). For dark themes also set `--forming-color-scheme: dark` and suitable error/background colors. You can omit the stylesheet and style the renderer's data attributes yourself.
+
+Before freeing the runtime, call `controller.dispose()` and dispose connected hosts. A disposed controller ignores late editor cleanup and events, so component teardown cannot read freed WASM memory.
+
+For async providers, connect the [provider host](../../core/hosts/javascript/README.md) and pass its `dispatch` as createController's second argument. On host callbacks call `controller.refresh()`. The host remains responsible for save/submit transport and journal durability. The renderer never frees the runtime or starts network requests. Dispose hosts, persist unresolved obligations, then unmount/free according to the application's lifecycle.
+
+Supported views: text/textarea/password, exact numeric text buffers, boolean/enum choices, remote choices with search/lookup/loading/retry, explicit clear/null, object creation, repeated insertion/removal/move, readonly calculated values, page navigation, stack/columns/grid, field errors and action availability.
+
+Scalar arrays without choices now have accessible add/remove/reorder row editors, including nullable items and exact numeric buffers. Missing, null and empty arrays remain distinct. New incomplete rows stay local and block actions other than Reset; they cancel waiting Submit. Lists above 1,000 items and complex arrays fall back to lossless JSON editing without truncation. Local editor row keys are not runtime repeat identities.
+
+Date/time fields retain authoritative portable text and add native picker helpers (unless an explicit text/password/textarea view opts out). Datetimes require an explicit offset; helpers never infer a timezone or convert through JavaScript Date. Nanosecond fractions are preserved when editing dates/offsets and when the visible time fraction is unchanged. Helper labels participate in renderer translations. Full cross-browser/mobile/screen-reader acceptance remains a release gate.
+
+Conditional pages/layouts/displays consume the core's `validation.viewStates`; children inherit effective state through `fieldStates`. Display title/content are plain, translatable text, with authored line breaks retained. Hidden pages follow the runtime's selected route. Explicit field IDs remain opaque and include generated placement/row suffixes when present. Real-WASM DOM tests cover layout visibility/editability, retained answers, translated display safety and hidden-page navigation.
+
+File fields now render a native file picker, transient/verified status, removal, explicit retry and portable reselection notices. Supply the [upload host](../../core/hosts/javascript/uploads.md) as createController's third argument and its dispatch as the second. Handles go directly to that host, never into JSON answers or drafts. Selection is disabled without a host or ready inputs; file fields do not expose raw JSON, generic clear or null editors. The core owns verification, limits, answer commits and waiting Submit.
+
+For the [S3 extension](../../extensions/s3-upload/README.md), connect the adapter through the same upload host. The `onChange` callback refreshes asynchronous transfer and inspection results in the renderer:
+
+```tsx
+import {createS3UploadAdapter, provider} from '@forming/extension-s3-upload';
+import {connectUploads} from '@forming/integrations/uploads';
+import {createController, FormingForm, type Controller} from '@forming/react';
+
+let controller: Controller | undefined;
+const uploads = connectUploads(runtime, {
+  adapters: new Map([
+    [
+      provider,
+      createS3UploadAdapter({
+        prepare: request => backend.prepareUpload(request),
+        inspect: request => backend.inspectUpload(request),
+        release: request => backend.releaseUpload(request),
+      }),
+    ],
+  ]),
+  journal: durableUploadJournal,
+  onChange: () => controller?.refresh(),
+});
+controller = createController(runtime, uploads.dispatch, uploads);
+<FormingForm controller={controller} />;
+```
+
+The S3 renderer integration test covers selection, direct PUT, waiting Submit, verified status and removal/release using the real runtime and application transport doubles. The backend SDK's simpler registration API does not change the renderer's upload-host contract.
+
+All answer/schema/provider numbers use the shared lossless JSON decoder. Never round-trip them through ordinary JSON.parse/stringify. Numeric choice matching treats equivalent decimal spellings equally. Incomplete numeric/array buffers are not committed, cancel waiting Submit through `submit.cancel`, and block actions other than Reset; correcting/clearing the buffer releases that block. Already-issued requests cannot be undone. Buffers are transient, not drafts: Reset and fields becoming hidden/disabled/readonly discard their uncommitted editor text without altering stored answers. IME/mobile and all browser editing paths still need acceptance testing.
+
+Repeated React keys are runtime stable IDs, never array indexes. Validation state is joined by node ID. Labels, helper text, errors and translations are React text, never injected HTML. Field inputs have associated labels, required/invalid metadata and described errors. Locale lang/dir comes from the runtime; pass translated renderer-owned button/status copy through `text`. Keyboard, responsive layout and screen-reader audits remain launch gates.
+
+Catalog `renderer.<key>` messages now supply button/status and true/false copy, with explicit `text` props taking precedence. Projected provider rejection/error text is supported. IME composition holds text locally, blocks stale Submit and commits on composition end; reset/hide/disable clears composition state. URL/phone fields request appropriate mobile keyboards without native-input normalization. Grid/columns views wrap on narrow screens and fieldsets may shrink. DOM tests cover composition/reset and translated renderer copy; the website's opt-in Chromium smoke gate adds keyboard, accessible-name and mobile-containment evidence, not screen-reader or cross-browser certification.
+
+## Local checks
+
+From this package, run `rtk npm ci --ignore-scripts`, then `rtk npm run lint && rtk npm test`. The type check also compiles an integration using the S3 adapter, upload host and renderer without casts. Tests use real generated WASM bindings and a simulated DOM. Override `FORMING_WASM_BINDINGS` with an absolute path to test optimized bindings. These are not real-browser or production-backend tests.
+
+Dependencies are pinned in package-lock.json. Both this package and the local host package are private development packages. Real storage/durable recovery, custom fields/payments, production deployment, package publication and browser distribution remain pending.
+
+Presentation plugins can also register `present.decorations`, keyed by an owned
+annotation export. Each callback receives the visible field/display identity, its
+annotations and a `before` or `after` placement. It adds content without replacing
+the normal editor or changing answers. See [media](../../extensions/media/README.md).
+
+## Automatic npm publishing
+
+Publishes `@forming/react` from `.`.
+
+`.github/workflows/publish.yml` publishes the JavaScript package on pushes to
+`dev` (base version plus `-dev.<run>.<attempt>`, npm tag `dev`) and `main`
+(stable package.json version, npm tag `latest`). Bump package.json and its lockfile
+before another stable release. Manual runs support only these two branches.
+The workflow creates no commits, Git tags or GitHub releases.
+
+Set Actions variable `NPM_ACCESS` to `public` or `restricted`. Configure secret
+`NPM_TOKEN`, or npm trusted publishing for this repository and workflow
+`publish.yml` after the first publish. Private repositories publish with provenance
+disabled. Packages exclude tests, source directories, build scripts and source maps.
+
+
+### npm release dependencies
+
+Publishing uses npm packages, without private sibling checkouts or a
+FORMING_REPOS_TOKEN. Core CI publishes `@forming/wasm@0.1.0` and
+`@forming/integrations@0.1.0` first. The js-sdk repository then publishes
+`@forming/runtime@0.1.0`, followed by the React renderer and extensions.
+Approve any staged releases before publishing dependent packages.

package/dist/editors.d.ts

@@ -0,0 +1,71 @@
+import React from 'react';
+import { type JsonValue } from '@forming/integrations/lossless-json';
+export declare const editorText: {
+    item: string;
+    emptyList: string;
+    datePicker: string;
+    timePicker: string;
+    offset: string;
+    offsetHint: string;
+    listLimit: string;
+};
+export declare const MAX_LIST_ITEMS = 1000;
+declare const icons: {
+    close: string;
+    check: string;
+    plus: string;
+    up: string;
+    down: string;
+    trash: string;
+    none: string;
+};
+export declare function Icon({ name }: {
+    name: keyof typeof icons;
+}): React.JSX.Element;
+type Text = typeof editorText & {
+    add: string;
+    remove: string;
+    up: string;
+    down: string;
+    setNull: string;
+    nullValue: string;
+    choose: string;
+    trueValue: string;
+    falseValue: string;
+};
+export interface ScalarSchema {
+    type?: string | string[];
+    format?: string;
+}
+export declare function baseType(schema?: ScalarSchema): string | undefined;
+export declare function inputMode(schema: ScalarSchema): 'decimal' | 'email' | 'url' | 'tel' | undefined;
+export declare function ScalarListEditor({ id, value, schema, disabled, reset, text, describedBy, commit, invalid, exact, }: {
+    id: string;
+    value: JsonValue | undefined;
+    schema: ScalarSchema;
+    disabled: boolean;
+    reset: string;
+    text: Text;
+    describedBy: string;
+    commit(value: JsonValue[]): boolean;
+    invalid(value: boolean): void;
+    /** Show null and empty-list controls. Respondent-facing forms usually hide them. */
+    exact?: boolean;
+}): React.JSX.Element;
+/** True when the native pickers can show this saved text without losing or hiding anything. */
+export declare function pickerAccepts(value: string, format: string): boolean;
+export declare function TemporalPicker({ id, title, value, format, disabled, reset, text, describedBy, change, incomplete, standalone, }: {
+    id: string;
+    title: string;
+    value: string;
+    format: string;
+    disabled: boolean;
+    reset: string;
+    text: Text;
+    describedBy: string;
+    change(value: string): void;
+    incomplete(): void;
+    /** The pickers are the only editor: the field label names them and the wrapper takes the field id. */
+    standalone?: boolean;
+}): React.JSX.Element;
+export {};

package/dist/editors.js

@@ -0,0 +1,222 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { JsonNumber, stringifyJson } from '@forming/integrations/lossless-json';
+export const editorText = {
+    item: 'Item',
+    emptyList: 'Use empty list',
+    datePicker: 'Choose date',
+    timePicker: 'Choose time',
+    offset: 'UTC offset',
+    offsetHint: 'Z or +05:30',
+    listLimit: 'This list editor supports up to 1,000 items.',
+};
+export const MAX_LIST_ITEMS = 1000;
+// Decorative stroke icons. Buttons keep their accessible name in text, aria-label or title.
+const icons = {
+    close: 'M6 6l12 12M18 6L6 18',
+    check: 'M5 12.5l4.5 4.5L19 7',
+    plus: 'M12 5v14M5 12h14',
+    up: 'M12 19V5M6 11l6-6 6 6',
+    down: 'M12 5v14M18 13l-6 6-6-6',
+    trash: 'M4 7h16M10 11v6M14 11v6M6 7l1 12a2 2 0 0 0 2 2h6a2 2 0 0 0 2-2l1-12M9 7V4h6v3',
+    none: 'M12 3a9 9 0 1 0 0 18a9 9 0 1 0 0-18M5.6 18.4L18.4 5.6',
+};
+export function Icon({ name }) {
+    return (_jsx("svg", { "data-forming-icon": name, "aria-hidden": "true", focusable: "false", viewBox: "0 0 24 24", width: "16", height: "16", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", children: _jsx("path", { d: icons[name] }) }));
+}
+export function baseType(schema) {
+    return (Array.isArray(schema?.type) ? schema.type : [schema?.type]).find(type => type !== 'null');
+}
+export function inputMode(schema) {
+    if (['integer', 'number'].includes(baseType(schema) ?? ''))
+        return 'decimal';
+    if (schema.format === 'email')
+        return 'email';
+    if (schema.format === 'uri')
+        return 'url';
+    if (schema.format === 'forming-international-phone' || schema.format?.startsWith('forming-phone:'))
+        return 'tel';
+}
+const display = (value) => value === undefined || value === null ? '' : typeof value === 'string' ? value : stringifyJson(value);
+export function ScalarListEditor({ id, value, schema, disabled, reset, text, describedBy, commit, invalid, exact = true, }) {
+    const sequence = useRef(0);
+    const makeRows = () => (Array.isArray(value) ? value : []).map(value => ({
+        id: ++sequence.current,
+        raw: display(value),
+        value,
+        pending: false,
+        composing: false,
+    }));
+    const [rows, setRows] = useState(makeRows);
+    const stored = value === undefined ? 'missing' : stringifyJson(value);
+    const expected = useRef(stored);
+    const previous = useRef({ reset, disabled });
+    const focus = useRef(null);
+    const inputs = useRef(new Map());
+    const add = useRef(null);
+    const type = baseType(schema);
+    const nullable = exact && Array.isArray(schema.type) && schema.type.includes('null');
+    useEffect(() => {
+        const changed = previous.current.reset !== reset || previous.current.disabled !== disabled;
+        previous.current = { reset, disabled };
+        if (changed || stored !== expected.current) {
+            expected.current = stored;
+            focus.current = null;
+            setRows(makeRows());
+            invalid(false);
+        }
+    }, [stored, reset, disabled]);
+    useEffect(() => {
+        if (focus.current === 'add')
+            add.current?.focus();
+        else if (focus.current !== null)
+            inputs.current.get(focus.current)?.focus();
+        focus.current = null;
+    }, [rows]);
+    function publish(next) {
+        if (disabled)
+            return;
+        setRows(next);
+        if (next.some(row => row.pending || row.composing || row.value === undefined)) {
+            invalid(true);
+            return;
+        }
+        const values = next.map(row => row.value);
+        const serialized = stringifyJson(values);
+        // Own commits preserve editor keys and focus. External edits reset local drafts.
+        const before = expected.current;
+        expected.current = serialized;
+        if (commit(values))
+            invalid(false);
+        else {
+            expected.current = before;
+            invalid(true);
+        }
+    }
+    function update(rowId, raw, composing) {
+        publish(rows.map(row => {
+            if (row.id !== rowId)
+                return row;
+            const next = { ...row, raw, composing: composing ?? row.composing, pending: true };
+            if (next.composing)
+                return next;
+            try {
+                if (type === 'number' || type === 'integer')
+                    next.value = new JsonNumber(raw);
+                else if (type === 'boolean') {
+                    if (raw !== 'true' && raw !== 'false')
+                        return next;
+                    next.value = raw === 'true';
+                }
+                else
+                    next.value = raw;
+                next.pending = false;
+            }
+            catch {
+                /* Keep incomplete numeric spelling local, never submit its old value. */
+            }
+            return next;
+        }));
+    }
+    return (_jsxs("div", { "data-scalar-list": "", children: [rows.map((row, index) => {
+                const rowId = `${id}:entry:${row.id}`;
+                const label = `${text.item} ${index + 1}`;
+                const common = {
+                    id: rowId,
+                    disabled,
+                    'aria-describedby': describedBy,
+                    'aria-invalid': row.pending || row.composing,
+                };
+                return (_jsxs("div", { "data-list-item": "", children: [_jsx("label", { htmlFor: rowId, children: label }), type === 'boolean' ? (_jsxs("select", { ...common, ref: element => {
+                                if (element)
+                                    inputs.current.set(row.id, element);
+                                else
+                                    inputs.current.delete(row.id);
+                            }, value: row.pending ? '' : row.value === true ? 'true' : row.value === false ? 'false' : '', onChange: event => update(row.id, event.target.value), children: [_jsx("option", { value: "", children: text.choose }), _jsx("option", { value: "true", children: text.trueValue }), _jsx("option", { value: "false", children: text.falseValue })] })) : (_jsx("input", { ...common, type: "text", inputMode: inputMode(schema), value: row.raw, ref: element => {
+                                if (element)
+                                    inputs.current.set(row.id, element);
+                                else
+                                    inputs.current.delete(row.id);
+                            }, onChange: event => update(row.id, event.target.value), onCompositionStart: () => publish(rows.map(other => (other.id === row.id ? { ...other, composing: true } : other))), onCompositionEnd: event => update(row.id, event.currentTarget.value, false) })), exact && row.value === null && !row.pending && _jsx("span", { "data-forming-null": "", children: text.nullValue }), _jsxs("div", { "data-list-tools": "", children: [_jsx("button", { type: "button", disabled: disabled || index === 0, "aria-label": `${text.up}: ${label}`, title: text.up, onClick: () => {
+                                        const next = [...rows];
+                                        [next[index - 1], next[index]] = [next[index], next[index - 1]];
+                                        publish(next);
+                                    }, children: _jsx(Icon, { name: "up" }) }), _jsx("button", { type: "button", disabled: disabled || index === rows.length - 1, "aria-label": `${text.down}: ${label}`, title: text.down, onClick: () => {
+                                        const next = [...rows];
+                                        [next[index + 1], next[index]] = [next[index], next[index + 1]];
+                                        publish(next);
+                                    }, children: _jsx(Icon, { name: "down" }) }), nullable && (_jsx("button", { type: "button", disabled: disabled, "aria-label": `${text.setNull}: ${label}`, title: text.setNull, onClick: () => publish(rows.map(other => other.id === row.id ? { ...other, raw: '', value: null, pending: false, composing: false } : other)), children: _jsx(Icon, { name: "none" }) })), _jsx("button", { type: "button", "data-danger": "", disabled: disabled, "aria-label": `${text.remove}: ${label}`, title: text.remove, onClick: () => {
+                                        focus.current = rows[index + 1]?.id ?? rows[index - 1]?.id ?? 'add';
+                                        publish(rows.filter(other => other.id !== row.id));
+                                    }, children: _jsx(Icon, { name: "trash" }) })] })] }, row.id));
+            }), _jsxs("button", { ref: add, type: "button", "data-forming-add": "", disabled: disabled || rows.length >= MAX_LIST_ITEMS, onClick: () => {
+                    if (rows.length >= MAX_LIST_ITEMS)
+                        return;
+                    const id = ++sequence.current;
+                    focus.current = id;
+                    publish([...rows, { id, raw: '', value: undefined, pending: true, composing: false }]);
+                }, children: [_jsx(Icon, { name: "plus" }), text.add] }), rows.length >= MAX_LIST_ITEMS && _jsx("p", { role: "status", children: text.listLimit }), exact && (_jsx("button", { type: "button", "data-forming-tool": "", disabled: disabled, onClick: () => {
+                    focus.current = 'add';
+                    publish([]);
+                }, children: text.emptyList }))] }));
+}
+/** True when the native pickers can show this saved text without losing or hiding anything. */
+export function pickerAccepts(value, format) {
+    if (format === 'date')
+        return /^\d{4}-\d{2}-\d{2}$/.test(value);
+    if (format === 'forming-local-time')
+        return /^\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?$/.test(value);
+    return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/.test(value);
+}
+function parts(value, format) {
+    if (format === 'date')
+        return { date: value, time: '', offset: '' };
+    if (format === 'forming-local-time')
+        return { date: '', time: value, offset: '' };
+    const match = /^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?)(Z|[+-]\d{2}:\d{2})$/.exec(value);
+    return { date: match?.[1] ?? '', time: match?.[2] ?? '', offset: match?.[3] ?? '' };
+}
+// Native pickers are an editing aid. The portable text input remains authoritative:
+// no Date objects, timezone inference, or browser normalization of stored values.
+export function TemporalPicker({ id, title, value, format, disabled, reset, text, describedBy, change, incomplete, standalone = false, }) {
+    const [draft, setDraft] = useState(() => parts(value, format));
+    const [pending, setPending] = useState(false);
+    useEffect(() => {
+        setDraft(parts(value, format));
+        setPending(false);
+    }, [value, format, reset, disabled]);
+    function update(key, value) {
+        if (disabled)
+            return;
+        // Browsers expose milliseconds at most. Editing hours/minutes must not trim
+        // the unchanged fractional suffix of a nanosecond-precision stored time.
+        const fraction = /\.(\d{4,9})$/.exec(draft.time)?.[1];
+        const visibleFraction = /\.(\d{1,3})$/.exec(value)?.[1] ?? '';
+        if (key === 'time' &&
+            fraction &&
+            /^\d{2}:\d{2}(?::\d{2}(?:\.\d{1,3})?)?$/.test(value) &&
+            visibleFraction.padEnd(3, '0') === fraction.slice(0, 3)) {
+            const whole = value.replace(/\.\d+$/, '');
+            value = (whole.length === 5 ? whole + ':00' : whole) + '.' + fraction;
+        }
+        const next = { ...draft, [key]: value };
+        setDraft(next);
+        const dateValid = /^\d{4}-\d{2}-\d{2}$/.test(next.date);
+        const timeValid = /^\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?$/.test(next.time);
+        const offsetValid = /^(Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/.test(next.offset) && next.offset !== '-00:00';
+        const valid = format === 'date'
+            ? dateValid
+            : format === 'forming-local-time'
+                ? timeValid
+                : dateValid && timeValid && offsetValid;
+        setPending(!valid);
+        if (!valid) {
+            incomplete();
+            return;
+        }
+        const time = next.time.length === 5 ? `${next.time}:00` : next.time;
+        change(format === 'date' ? next.date : format === 'forming-local-time' ? time : `${next.date}T${time}${next.offset}`);
+    }
+    const common = { disabled, 'aria-invalid': pending, 'aria-describedby': describedBy };
+    return (_jsxs("div", { "data-temporal-picker": "", "data-standalone": standalone ? '' : undefined, id: standalone ? id : undefined, tabIndex: standalone ? -1 : undefined, style: { display: 'flex', flexWrap: 'wrap', gap: '0.5rem' }, children: [format !== 'forming-local-time' && (_jsxs("label", { htmlFor: `${id}:date`, children: [_jsx("span", { children: text.datePicker }), _jsx("input", { ...common, "aria-label": `${title}: ${text.datePicker}`, id: `${id}:date`, type: "date", min: "0001-01-01", max: "9999-12-31", value: draft.date, onChange: event => update('date', event.target.value) })] })), format !== 'date' && (_jsxs("label", { htmlFor: `${id}:time`, children: [_jsx("span", { children: text.timePicker }), _jsx("input", { ...common, "aria-label": `${title}: ${text.timePicker}`, id: `${id}:time`, type: "time", step: "any", value: draft.time.replace(/(\.\d{3})\d+$/, '$1'), onChange: event => update('time', event.target.value) })] })), format === 'date-time' && (_jsxs("label", { htmlFor: `${id}:offset`, children: [_jsx("span", { children: text.offset }), _jsx("input", { ...common, "aria-label": `${title}: ${text.offset}`, id: `${id}:offset`, type: "text", placeholder: text.offsetHint, value: draft.offset, onChange: event => update('offset', event.target.value) })] }))] }));
+}

package/dist/format.d.ts

@@ -0,0 +1,11 @@
+import { type JsonValue } from '@forming/integrations/lossless-json';
+type Schema = {
+    type?: string | string[];
+    format?: string;
+};
+export declare function formatNumber(raw: string, locale?: string): string | null;
+export declare function formatDate(text: string, locale?: string): string | null;
+export declare function formatTime(text: string, locale?: string): string | null;
+export declare function formatDateTime(text: string, locale?: string): string | null;
+export declare function localized(value: JsonValue | undefined, schema: Schema, locale?: string): string | null;
+export {};

package/dist/format.js

@@ -0,0 +1,97 @@
+import { JsonNumber } from '@forming/integrations/lossless-json';
+function locales(locale) {
+    try {
+        if (locale)
+            return Intl.getCanonicalLocales(locale)[0];
+    }
+    catch {
+        // Fall through to the browser default.
+    }
+    return undefined;
+}
+export function formatNumber(raw, locale) {
+    try {
+        // Intl.NumberFormat accepts decimal strings exactly (ES2023); older
+        // engines coerce to a double, so refuse when that would lose digits.
+        const formatter = new Intl.NumberFormat(locales(locale), { maximumFractionDigits: 20 });
+        const formatted = formatter.format(raw);
+        const digits = raw.replace(/^-|\.|e.*$/gi, '').replace(/^0+/, '');
+        return formatted
+            .replace(/[^0-9]/g, '')
+            .replace(/^0+/, '')
+            .endsWith(digits.replace(/0+$/, ''))
+            ? formatted
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function formatDate(text, locale) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(text);
+    if (!match)
+        return null;
+    const date = new Date(Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3])));
+    if (Number.isNaN(date.getTime()) || date.getUTCDate() !== Number(match[3]))
+        return null;
+    try {
+        return new Intl.DateTimeFormat(locales(locale), { dateStyle: 'long', timeZone: 'UTC' }).format(date);
+    }
+    catch {
+        return null;
+    }
+}
+export function formatTime(text, locale) {
+    const match = /^(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d+))?)?$/.exec(text);
+    if (!match)
+        return null;
+    const seconds = Number(match[3] ?? '0');
+    const date = new Date(Date.UTC(2000, 0, 1, Number(match[1]), Number(match[2]), seconds));
+    if (Number.isNaN(date.getTime()) || date.getUTCHours() !== Number(match[1]))
+        return null;
+    try {
+        const options = seconds || match[4] ? { timeStyle: 'medium', timeZone: 'UTC' } : { timeStyle: 'short', timeZone: 'UTC' };
+        const formatted = new Intl.DateTimeFormat(locales(locale), options).format(date);
+        return match[4] && /[1-9]/.test(match[4]) ? `${formatted} (.${match[4].replace(/0+$/, '')})` : formatted;
+    }
+    catch {
+        return null;
+    }
+}
+export function formatDateTime(text, locale) {
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})$/.test(text))
+        return null;
+    const date = new Date(text);
+    if (Number.isNaN(date.getTime()))
+        return null;
+    try {
+        return new Intl.DateTimeFormat(locales(locale), {
+            year: 'numeric',
+            month: 'short',
+            day: 'numeric',
+            hour: 'numeric',
+            minute: '2-digit',
+            timeZoneName: 'short',
+        }).format(date);
+    }
+    catch {
+        return null;
+    }
+}
+// Returns the localized rendering of a committed scalar, or null when the
+// value is not a formattable scalar of that schema.
+export function localized(value, schema, locale) {
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    const type = types.find(entry => entry !== 'null');
+    if (value instanceof JsonNumber && (type === 'number' || type === 'integer'))
+        return formatNumber(value.raw, locale);
+    if (typeof value !== 'string' || type !== 'string')
+        return null;
+    if (schema.format === 'date')
+        return formatDate(value, locale);
+    if (schema.format === 'forming-local-time')
+        return formatTime(value, locale);
+    if (schema.format === 'date-time')
+        return formatDateTime(value, locale);
+    return null;
+}