@panneau/core 4.1.0 → 5.0.0-alpha.0

package/README.md

@@ -0,0 +1,83 @@
+# @panneau/core
+
+The engine of Panneau: plugin registry, definition to forms and lists, form and list state, with React hooks. It renders no UI, and only relies on [`@panneau/protocol`](../protocol): data comes from the caller, or from [`@panneau/data`](../data).
+
+```tsx
+import { getItemValues, resolveForm, useForm, useResource } from '@panneau/core';
+
+function EditPage({ item, onSave }) {
+    const { resource } = useResource('pages');
+    const { fields, layout } = resolveForm(resource, { mode: 'update' });
+    const { form, values, errors, status, conflict } = useForm({
+        fields,
+        values: getItemValues(
+            item,
+            fields.map((field) => field.name),
+        ),
+        version: item.version,
+        locales: ['fr', 'en'],
+        onSubmit: (values, { version, changes }) => onSave(changes, version),
+    });
+    // Render `layout` with fields from the plugins; `form.setValue('title.fr', …)` on change.
+}
+```
+
+| Export          | Content                                                      |
+| --------------- | ------------------------------------------------------------ |
+| `@panneau/core` | Plugins, definition engine, form and list state, React hooks |
+
+## Plugins
+
+`definePlugin()` declares what a plugin adds, keyed by the names the definition uses: `fields`, `displays`, `listLayouts`, `actions` (handlers of `client` actions), `pages`, `widgets`, `components` (layout nodes), `locales` and `themes`.
+
+`PanneauProvider` takes plugins, the definition and a router. Nested providers add their plugins to those of their parent, and later plugins override earlier ones, so a project can replace a built-in field. `usePlugins()` returns the merged registry, and `loadMessages(registry, locale)` the merged messages of a locale.
+
+## Definition engine
+
+- **`resolveForm(resource, { mode, type })`**: the fields of the form and its layout. Field nodes that name unknown fields are dropped, and fields that no node references are appended at the end. `create` drops `updateOnly` fields; `update` makes `createOnly` fields read-only. `type` adds the fields of an item type.
+- **`resolveList(resource)`**: columns (label, display and sortability from their field), filters, sorts, default sort, layouts, page size, and the actions the user can run, by placement. Without columns, the list shows the item title and the next fields.
+- **Abilities:** `can(abilities, 'create')`, `isActionAllowedOn(action, item)`, `partitionByAction(action, items)`. Without abilities, everything is allowed and the backend decides; with abilities, only what is `true`.
+- **`useResource(id)`** resolves a resource of the provider's definition.
+
+## Forms
+
+`createForm(options)`, or `useForm(options)` in a component, manages:
+
+- **Values**, nested and localized, set by dot path (`form.setValue('title.fr', 'Accueil')`), and whether they changed (`dirty`).
+- **Client validation** with the portable rules (`checkValues()`): errors of a field show once it was blurred (`form.blur(path)`), and every error shows after a submit. Messages are English by default; `formatError` translates them.
+- **Server errors**, by dot path, from a `422`. They go away when their value changes.
+- **Visibility:** `selectVisible(state, field)` evaluates `visibleWhen`. Hidden fields are not validated.
+- **Submit:** `onSubmit(values, { version, changes, mode })`. When it returns an item, the form continues from it, with its new version. When it throws an error that carries problem details (the errors of `@panneau/data` do), a `412` puts the form in the `conflict` status with the current item. `form.resolveConflict('reload')` takes their version; `'overwrite'` submits the local changes again over it.
+
+Values live in a `FormStore`. The default one is local; a shared store (Yjs) can replace it without changing the fields. `useFormField(form, path)` gives the props of a controlled field.
+
+### Reading the state in components
+
+Components read the state they subscribed to (what `useForm()` returns, or `useSyncExternalStore(form.subscribe, form.getState)`) with pure selectors:
+
+| Selector                                   | Returns                                                                                             |
+| ------------------------------------------ | --------------------------------------------------------------------------------------------------- |
+| `selectValue(state, path)`                 | The value at a dot path                                                                             |
+| `selectErrors(state, path, { nested })`    | The errors at a path, and with `nested` those of the paths inside it (`title.fr` for `title`)       |
+| `selectErrorCount(state, paths)`           | The number of paths with errors within some paths, for counts on tabs and sections                  |
+| `selectVisible(state, target, parentPath)` | Whether a field or layout node is visible; conditions of nested fields are relative to `parentPath` |
+
+```tsx
+function TitleField({ form }: { form: Form }) {
+    const state = useSyncExternalStore(form.subscribe, form.getState, form.getState);
+    const errors = selectErrors(state, 'title', { nested: true });
+    // …
+}
+```
+
+The form's methods that read the state (`form.getValue()`, `form.getErrors()`, `form.countErrors()`, `form.isVisible()`) are **not React APIs**: the React Compiler memoizes calls by their arguments, and these arguments don't change when the state does, so the results go stale (the error of a field doesn't show after a blur). Use them outside of components: in event handlers, effects, tests or plain scripts.
+
+## Lists
+
+`createList(options)`, or `useList(options)`, manages:
+
+- **The query**: page, page size, sort, filters and search, with the list's defaults. Changing filters, search, sort or page size goes back to the first page.
+- **The selection**: some ids, kept across pages, or every item matching the query except some (`selectAllMatching()`). `getSelection()` returns the protocol's `Selection` for an action. Changing filters or search clears it.
+- **URL sync** through a `Router`: `getSearch()`, `setSearch()` and `subscribe()`. Only values that differ from the defaults are written, next to the other parameters. `createHistoryRouter()` uses `window.history`; `createMemoryRouter()` keeps it in memory. `useList()` uses the provider's router unless given one, or `router: null`.
+
+The package layout, scripts and API reports are explained in [`docs/packages.md`](../../docs/packages.md).

package/dist/definition/abilities.d.ts

@@ -0,0 +1,21 @@
+import type { Abilities, Action, ActionPlacement, Item } from '@panneau/protocol';
+/**
+ * Whether a set of abilities allows something. Without abilities (a backend that sends none),
+ * everything is allowed and the backend decides. With abilities, only what is `true` is allowed.
+ */
+export declare function can(abilities: Abilities | undefined, ability: string): boolean;
+/** Whether the current user can run an action on the resource (`abilities.run`). */
+export declare function canRunAction(action: Action): boolean;
+/**
+ * Whether an action is available on an item: the user can run it, and the item lists its id in
+ * its abilities. Links to show and edit are allowed unless the item says otherwise.
+ */
+export declare function isActionAllowedOn(action: Action, item: Item): boolean;
+/** Splits the items of a selection by whether an action is allowed on them. */
+export declare function partitionByAction(action: Action, items: readonly Item[]): {
+    allowed: Item[];
+    skipped: Item[];
+};
+/** Where an action appears when it doesn't say: rows and forms for items, the toolbar otherwise. */
+export declare function getActionPlacements(action: Action): ActionPlacement[];
+//# sourceMappingURL=abilities.d.ts.map

package/dist/definition/abilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abilities.d.ts","sourceRoot":"","sources":["../../src/definition/abilities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAElF;;;GAGG;AACH,wBAAgB,GAAG,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAE9E;AAED,oFAAoF;AACpF,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAQrE;AAED,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAC7B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,SAAS,IAAI,EAAE,GACvB;IAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAAC,OAAO,EAAE,IAAI,EAAE,CAAA;CAAE,CAKtC;AAED,oGAAoG;AACpG,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,EAAE,CAcrE"}

package/dist/definition/abilities.js

@@ -0,0 +1,47 @@
+//#region src/definition/abilities.ts
+/**
+* Whether a set of abilities allows something. Without abilities (a backend that sends none),
+* everything is allowed and the backend decides. With abilities, only what is `true` is allowed.
+*/
+function can(abilities, ability) {
+	return abilities === void 0 || abilities[ability] === true;
+}
+/** Whether the current user can run an action on the resource (`abilities.run`). */
+function canRunAction(action) {
+	return action.abilities?.run !== false;
+}
+/**
+* Whether an action is available on an item: the user can run it, and the item lists its id in
+* its abilities. Links to show and edit are allowed unless the item says otherwise.
+*/
+function isActionAllowedOn(action, item) {
+	if (!canRunAction(action)) return false;
+	if (action.kind === "link") return item.abilities[action.id] !== false;
+	return item.abilities[action.id] === true;
+}
+/** Splits the items of a selection by whether an action is allowed on them. */
+function partitionByAction(action, items) {
+	const allowed = [];
+	const skipped = [];
+	items.forEach((item) => (isActionAllowedOn(action, item) ? allowed : skipped).push(item));
+	return {
+		allowed,
+		skipped
+	};
+}
+/** Where an action appears when it doesn't say: rows and forms for items, the toolbar otherwise. */
+function getActionPlacements(action) {
+	if (action.placement !== void 0) return action.placement;
+	const placements = /* @__PURE__ */ new Set();
+	action.scope.forEach((scope) => {
+		if (scope === "item") {
+			placements.add("row");
+			placements.add("form");
+		} else placements.add("toolbar");
+	});
+	return [...placements];
+}
+//#endregion
+export { can, canRunAction, getActionPlacements, isActionAllowedOn, partitionByAction };
+
+//# sourceMappingURL=abilities.js.map

package/dist/definition/abilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abilities.js","names":[],"sources":["../../src/definition/abilities.ts"],"sourcesContent":["import type { Abilities, Action, ActionPlacement, Item } from '@panneau/protocol';\n\n/**\n * Whether a set of abilities allows something. Without abilities (a backend that sends none),\n * everything is allowed and the backend decides. With abilities, only what is `true` is allowed.\n */\nexport function can(abilities: Abilities | undefined, ability: string): boolean {\n    return abilities === undefined || abilities[ability] === true;\n}\n\n/** Whether the current user can run an action on the resource (`abilities.run`). */\nexport function canRunAction(action: Action): boolean {\n    return action.abilities?.run !== false;\n}\n\n/**\n * Whether an action is available on an item: the user can run it, and the item lists its id in\n * its abilities. Links to show and edit are allowed unless the item says otherwise.\n */\nexport function isActionAllowedOn(action: Action, item: Item): boolean {\n    if (!canRunAction(action)) {\n        return false;\n    }\n    if (action.kind === 'link') {\n        return item.abilities[action.id] !== false;\n    }\n    return item.abilities[action.id] === true;\n}\n\n/** Splits the items of a selection by whether an action is allowed on them. */\nexport function partitionByAction(\n    action: Action,\n    items: readonly Item[],\n): { allowed: Item[]; skipped: Item[] } {\n    const allowed: Item[] = [];\n    const skipped: Item[] = [];\n    items.forEach((item) => (isActionAllowedOn(action, item) ? allowed : skipped).push(item));\n    return { allowed, skipped };\n}\n\n/** Where an action appears when it doesn't say: rows and forms for items, the toolbar otherwise. */\nexport function getActionPlacements(action: Action): ActionPlacement[] {\n    if (action.placement !== undefined) {\n        return action.placement;\n    }\n    const placements = new Set<ActionPlacement>();\n    action.scope.forEach((scope) => {\n        if (scope === 'item') {\n            placements.add('row');\n            placements.add('form');\n        } else {\n            placements.add('toolbar');\n        }\n    });\n    return [...placements];\n}\n"],"mappings":";;;;;AAMA,SAAgB,IAAI,WAAkC,SAA0B;CAC5E,OAAO,cAAc,KAAA,KAAa,UAAU,aAAa;AAC7D;;AAGA,SAAgB,aAAa,QAAyB;CAClD,OAAO,OAAO,WAAW,QAAQ;AACrC;;;;;AAMA,SAAgB,kBAAkB,QAAgB,MAAqB;CACnE,IAAI,CAAC,aAAa,MAAM,GACpB,OAAO;CAEX,IAAI,OAAO,SAAS,QAChB,OAAO,KAAK,UAAU,OAAO,QAAQ;CAEzC,OAAO,KAAK,UAAU,OAAO,QAAQ;AACzC;;AAGA,SAAgB,kBACZ,QACA,OACoC;CACpC,MAAM,UAAkB,CAAA;CACxB,MAAM,UAAkB,CAAA;CACxB,MAAM,SAAS,UAAU,kBAAkB,QAAQ,IAAI,IAAI,UAAU,QAAA,CAAS,KAAK,IAAI,CAAC;CACxF,OAAO;EAAE;EAAS;CAAQ;AAC9B;;AAGA,SAAgB,oBAAoB,QAAmC;CACnE,IAAI,OAAO,cAAc,KAAA,GACrB,OAAO,OAAO;CAElB,MAAM,6BAAa,IAAI,IAAqB;CAC5C,OAAO,MAAM,SAAS,UAAU;EAC5B,IAAI,UAAU,QAAQ;GAClB,WAAW,IAAI,KAAK;GACpB,WAAW,IAAI,MAAM;EACzB,OACI,WAAW,IAAI,SAAS;CAEhC,CAAC;CACD,OAAO,CAAC,GAAG,UAAU;AACzB"}

package/dist/definition/form.d.ts

@@ -0,0 +1,31 @@
+import type { Field, LayoutNode, Resource } from '@panneau/protocol';
+/** Whether a form creates an item or updates one. */
+export type FormMode = 'create' | 'update';
+/** A form ready to render: its fields and a layout that references every one of them. */
+export interface ResolvedForm {
+    /** The fields of the form, in definition order. */
+    fields: Field[];
+    /** The fields, by name. */
+    fieldsByName: ReadonlyMap<string, Field>;
+    /**
+     * The layout tree. Field nodes that name an unknown field are removed, and fields that no
+     * node references are appended at the end, as `field` nodes.
+     */
+    layout: LayoutNode[];
+}
+export interface ResolveFormOptions {
+    /**
+     * `create` removes `updateOnly` fields; `update` makes `createOnly` fields read-only. Without a
+     * mode, every field is kept as is.
+     */
+    mode?: FormMode;
+    /** The type of the item, among the resource's `types`: its fields are added. */
+    type?: string;
+}
+/** Resolves fields and a layout into a form. */
+export declare function resolveFields(fields: readonly Field[], layout?: readonly LayoutNode[], { mode }?: Pick<ResolveFormOptions, 'mode'>): ResolvedForm;
+/** Resolves the form of a resource: its fields (plus those of the item's type) and its layout. */
+export declare function resolveForm(resource: Resource, options?: ResolveFormOptions): ResolvedForm;
+/** The field names a layout references, in order. */
+export declare function getLayoutFieldNames(layout: readonly LayoutNode[]): string[];
+//# sourceMappingURL=form.d.ts.map

package/dist/definition/form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form.d.ts","sourceRoot":"","sources":["../../src/definition/form.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAErE,qDAAqD;AACrD,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE3C,yFAAyF;AACzF,MAAM,WAAW,YAAY;IACzB,mDAAmD;IACnD,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,2BAA2B;IAC3B,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACzC;;;OAGG;IACH,MAAM,EAAE,UAAU,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IAC/B;;;OAGG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,gFAAgF;IAChF,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AA2BD,gDAAgD;AAChD,wBAAgB,aAAa,CACzB,MAAM,EAAE,SAAS,KAAK,EAAE,EACxB,MAAM,GAAE,SAAS,UAAU,EAAO,EAClC,EAAE,IAAI,EAAE,GAAE,IAAI,CAAC,kBAAkB,EAAE,MAAM,CAAM,GAChD,YAAY,CAiBd;AAED,kGAAkG;AAClG,wBAAgB,WAAW,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,GAAE,kBAAuB,GAAG,YAAY,CAM9F;AAED,qDAAqD;AACrD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,MAAM,EAAE,CAE3E"}

package/dist/definition/form.js

@@ -0,0 +1,54 @@
+//#region src/definition/form.ts
+function referencedNames(nodes, names = /* @__PURE__ */ new Set()) {
+	nodes.forEach((node) => {
+		if (node.type === "field" && node.name !== void 0) names.add(node.name);
+		referencedNames(node.children ?? [], names);
+	});
+	return names;
+}
+function pruneLayout(nodes, fields) {
+	return nodes.flatMap((node) => {
+		if (node.type === "field" && (node.name === void 0 || !fields.has(node.name))) return [];
+		if (node.children === void 0) return [node];
+		return [{
+			...node,
+			children: pruneLayout(node.children, fields)
+		}];
+	});
+}
+/** Resolves fields and a layout into a form. */
+function resolveFields(fields, layout = [], { mode } = {}) {
+	const resolved = fields.flatMap((field) => {
+		if (mode === "create" && field.updateOnly === true) return [];
+		if (mode === "update" && field.createOnly === true) return [{
+			...field,
+			readOnly: true
+		}];
+		return [field];
+	});
+	const fieldsByName = new Map(resolved.map((field) => [field.name, field]));
+	const pruned = pruneLayout(layout, fieldsByName);
+	const referenced = referencedNames(pruned);
+	const appended = resolved.filter((field) => !referenced.has(field.name)).map((field) => ({
+		type: "field",
+		name: field.name
+	}));
+	return {
+		fields: resolved,
+		fieldsByName,
+		layout: [...pruned, ...appended]
+	};
+}
+/** Resolves the form of a resource: its fields (plus those of the item's type) and its layout. */
+function resolveForm(resource, options = {}) {
+	const typeFields = options.type !== void 0 ? resource.types?.find((type) => type.id === options.type)?.fields ?? [] : [];
+	return resolveFields([...resource.fields, ...typeFields], resource.form?.layout ?? [], options);
+}
+/** The field names a layout references, in order. */
+function getLayoutFieldNames(layout) {
+	return [...referencedNames(layout)];
+}
+//#endregion
+export { getLayoutFieldNames, resolveFields, resolveForm };
+
+//# sourceMappingURL=form.js.map

package/dist/definition/form.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"form.js","names":[],"sources":["../../src/definition/form.ts"],"sourcesContent":["import type { Field, LayoutNode, Resource } from '@panneau/protocol';\n\n/** Whether a form creates an item or updates one. */\nexport type FormMode = 'create' | 'update';\n\n/** A form ready to render: its fields and a layout that references every one of them. */\nexport interface ResolvedForm {\n    /** The fields of the form, in definition order. */\n    fields: Field[];\n    /** The fields, by name. */\n    fieldsByName: ReadonlyMap<string, Field>;\n    /**\n     * The layout tree. Field nodes that name an unknown field are removed, and fields that no\n     * node references are appended at the end, as `field` nodes.\n     */\n    layout: LayoutNode[];\n}\n\nexport interface ResolveFormOptions {\n    /**\n     * `create` removes `updateOnly` fields; `update` makes `createOnly` fields read-only. Without a\n     * mode, every field is kept as is.\n     */\n    mode?: FormMode;\n    /** The type of the item, among the resource's `types`: its fields are added. */\n    type?: string;\n}\n\nfunction referencedNames(nodes: readonly LayoutNode[], names = new Set<string>()): Set<string> {\n    nodes.forEach((node) => {\n        if (node.type === 'field' && node.name !== undefined) {\n            names.add(node.name);\n        }\n        referencedNames(node.children ?? [], names);\n    });\n    return names;\n}\n\nfunction pruneLayout(\n    nodes: readonly LayoutNode[],\n    fields: ReadonlyMap<string, Field>,\n): LayoutNode[] {\n    return nodes.flatMap((node) => {\n        if (node.type === 'field' && (node.name === undefined || !fields.has(node.name))) {\n            return [];\n        }\n        if (node.children === undefined) {\n            return [node];\n        }\n        return [{ ...node, children: pruneLayout(node.children, fields) }];\n    });\n}\n\n/** Resolves fields and a layout into a form. */\nexport function resolveFields(\n    fields: readonly Field[],\n    layout: readonly LayoutNode[] = [],\n    { mode }: Pick<ResolveFormOptions, 'mode'> = {},\n): ResolvedForm {\n    const resolved = fields.flatMap((field) => {\n        if (mode === 'create' && field.updateOnly === true) {\n            return [];\n        }\n        if (mode === 'update' && field.createOnly === true) {\n            return [{ ...field, readOnly: true }];\n        }\n        return [field];\n    });\n    const fieldsByName = new Map(resolved.map((field) => [field.name, field]));\n    const pruned = pruneLayout(layout, fieldsByName);\n    const referenced = referencedNames(pruned);\n    const appended: LayoutNode[] = resolved\n        .filter((field) => !referenced.has(field.name))\n        .map((field) => ({ type: 'field', name: field.name }));\n    return { fields: resolved, fieldsByName, layout: [...pruned, ...appended] };\n}\n\n/** Resolves the form of a resource: its fields (plus those of the item's type) and its layout. */\nexport function resolveForm(resource: Resource, options: ResolveFormOptions = {}): ResolvedForm {\n    const typeFields =\n        options.type !== undefined\n            ? (resource.types?.find((type) => type.id === options.type)?.fields ?? [])\n            : [];\n    return resolveFields([...resource.fields, ...typeFields], resource.form?.layout ?? [], options);\n}\n\n/** The field names a layout references, in order. */\nexport function getLayoutFieldNames(layout: readonly LayoutNode[]): string[] {\n    return [...referencedNames(layout)];\n}\n"],"mappings":";AA4BA,SAAS,gBAAgB,OAA8B,wBAAQ,IAAI,IAAY,GAAgB;CAC3F,MAAM,SAAS,SAAS;EACpB,IAAI,KAAK,SAAS,WAAW,KAAK,SAAS,KAAA,GACvC,MAAM,IAAI,KAAK,IAAI;EAEvB,gBAAgB,KAAK,YAAY,CAAA,GAAI,KAAK;CAC9C,CAAC;CACD,OAAO;AACX;AAEA,SAAS,YACL,OACA,QACY;CACZ,OAAO,MAAM,SAAS,SAAS;EAC3B,IAAI,KAAK,SAAS,YAAY,KAAK,SAAS,KAAA,KAAa,CAAC,OAAO,IAAI,KAAK,IAAI,IAC1E,OAAO,CAAA;EAEX,IAAI,KAAK,aAAa,KAAA,GAClB,OAAO,CAAC,IAAI;EAEhB,OAAO,CAAC;GAAE,GAAG;GAAM,UAAU,YAAY,KAAK,UAAU,MAAM;EAAE,CAAC;CACrE,CAAC;AACL;;AAGA,SAAgB,cACZ,QACA,SAAgC,CAAA,GAChC,EAAE,SAA2C,CAAC,GAClC;CACZ,MAAM,WAAW,OAAO,SAAS,UAAU;EACvC,IAAI,SAAS,YAAY,MAAM,eAAe,MAC1C,OAAO,CAAA;EAEX,IAAI,SAAS,YAAY,MAAM,eAAe,MAC1C,OAAO,CAAC;GAAE,GAAG;GAAO,UAAU;EAAK,CAAC;EAExC,OAAO,CAAC,KAAK;CACjB,CAAC;CACD,MAAM,eAAe,IAAI,IAAI,SAAS,KAAK,UAAU,CAAC,MAAM,MAAM,KAAK,CAAC,CAAC;CACzE,MAAM,SAAS,YAAY,QAAQ,YAAY;CAC/C,MAAM,aAAa,gBAAgB,MAAM;CACzC,MAAM,WAAyB,SAC1B,QAAQ,UAAU,CAAC,WAAW,IAAI,MAAM,IAAI,CAAC,CAAC,CAC9C,KAAK,WAAW;EAAE,MAAM;EAAS,MAAM,MAAM;CAAK,EAAE;CACzD,OAAO;EAAE,QAAQ;EAAU;EAAc,QAAQ,CAAC,GAAG,QAAQ,GAAG,QAAQ;CAAE;AAC9E;;AAGA,SAAgB,YAAY,UAAoB,UAA8B,CAAC,GAAiB;CAC5F,MAAM,aACF,QAAQ,SAAS,KAAA,IACV,SAAS,OAAO,MAAM,SAAS,KAAK,OAAO,QAAQ,IAAI,CAAC,EAAE,UAAU,CAAA,IACrE,CAAA;CACV,OAAO,cAAc,CAAC,GAAG,SAAS,QAAQ,GAAG,UAAU,GAAG,SAAS,MAAM,UAAU,CAAA,GAAI,OAAO;AAClG;;AAGA,SAAgB,oBAAoB,QAAyC;CACzE,OAAO,CAAC,GAAG,gBAAgB,MAAM,CAAC;AACtC"}

package/dist/definition/list.d.ts

@@ -0,0 +1,44 @@
+import type { Action, ActionPlacement, Field, Filter, Resource } from '@panneau/protocol';
+/** A column ready to render. */
+export interface ResolvedColumn {
+    /** The column id: its `id`, or the name of its field. */
+    id: string;
+    /** The field shown, when the column shows one. */
+    field: Field | null;
+    label: string;
+    /** How the value is displayed: the column's display, the field's, or the field type. */
+    display: string | null;
+    sortable: boolean;
+    width?: number | string;
+    align?: 'start' | 'center' | 'end';
+}
+/** A list ready to render. */
+export interface ResolvedList {
+    columns: ResolvedColumn[];
+    filters: Filter[];
+    /** Fields the list can be sorted by. */
+    sorts: string[];
+    /** The default sort, as `sort` query values (`['-published_at', 'title']`). */
+    defaultSort: string[];
+    /** Whether the list can be searched (`q`). */
+    search: boolean;
+    /** List layouts, the first one being the default. */
+    layouts: string[];
+    perPage: number;
+    perPageOptions: number[];
+    /** Fields editable in the list. */
+    inlineEdit: string[];
+    /** Whether items can be selected: the list allows it and a selection action exists. */
+    selectable: boolean;
+    /** Actions the user can run, by placement. */
+    actions: Record<ActionPlacement, Action[]>;
+}
+export declare const DEFAULT_PER_PAGE = 20;
+/** Groups the actions the user can run by placement. */
+export declare function groupActions(actions: readonly Action[]): Record<ActionPlacement, Action[]>;
+/**
+ * Resolves the list of a resource. Without columns, it shows the item title and the next fields
+ * (up to four, skipping groups, repeaters and rich text).
+ */
+export declare function resolveList(resource: Resource): ResolvedList;
+//# sourceMappingURL=list.d.ts.map

package/dist/definition/list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../src/definition/list.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,eAAe,EAAU,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAIlG,gCAAgC;AAChC,MAAM,WAAW,cAAc;IAC3B,yDAAyD;IACzD,EAAE,EAAE,MAAM,CAAC;IACX,kDAAkD;IAClD,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,wFAAwF;IACxF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;CACtC;AAED,8BAA8B;AAC9B,MAAM,WAAW,YAAY;IACzB,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,wCAAwC;IACxC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,+EAA+E;IAC/E,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,8CAA8C;IAC9C,MAAM,EAAE,OAAO,CAAC;IAChB,qDAAqD;IACrD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,mCAAmC;IACnC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,uFAAuF;IACvF,UAAU,EAAE,OAAO,CAAC;IACpB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC,eAAe,EAAE,MAAM,EAAE,CAAC,CAAC;CAC9C;AAMD,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAenC,wDAAwD;AACxD,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC,eAAe,EAAE,MAAM,EAAE,CAAC,CAM1F;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,QAAQ,GAAG,YAAY,CAwC5D"}

package/dist/definition/list.js

@@ -0,0 +1,70 @@
+import { canRunAction, getActionPlacements } from "./abilities.js";
+//#region src/definition/list.ts
+/** Fields shown when the list declares no columns. */
+var DEFAULT_COLUMN_COUNT = 4;
+var NON_COLUMN_TYPES = /* @__PURE__ */ new Set([
+	"group",
+	"repeater",
+	"richtext"
+]);
+var DEFAULT_PER_PAGE = 20;
+function columnsFromFields(resource) {
+	const title = resource.itemTitle;
+	const fields = resource.fields.filter((field) => !NON_COLUMN_TYPES.has(field.type));
+	return (title !== void 0 ? [...fields.filter((field) => field.name === title), ...fields.filter((field) => field.name !== title)] : fields).slice(0, DEFAULT_COLUMN_COUNT).map((field) => ({ field: field.name }));
+}
+/** Groups the actions the user can run by placement. */
+function groupActions(actions) {
+	const groups = {
+		row: [],
+		toolbar: [],
+		form: [],
+		menu: []
+	};
+	actions.filter(canRunAction).forEach((action) => {
+		getActionPlacements(action).forEach((placement) => groups[placement].push(action));
+	});
+	return groups;
+}
+/**
+* Resolves the list of a resource. Without columns, it shows the item title and the next fields
+* (up to four, skipping groups, repeaters and rich text).
+*/
+function resolveList(resource) {
+	const list = resource.list ?? {};
+	const fields = new Map(resource.fields.map((field) => [field.name, field]));
+	const sorts = list.sorts ?? [];
+	const columns = (list.columns ?? columnsFromFields(resource)).map((column) => {
+		const field = column.field !== void 0 ? fields.get(column.field) ?? null : null;
+		const id = column.id ?? column.field ?? "";
+		const resolved = {
+			id,
+			field,
+			label: column.label ?? field?.label ?? id,
+			display: column.display ?? field?.display ?? field?.type ?? null,
+			sortable: column.sortable ?? (column.field !== void 0 && sorts.includes(column.field))
+		};
+		if (column.width !== void 0) resolved.width = column.width;
+		if (column.align !== void 0) resolved.align = column.align;
+		return resolved;
+	});
+	const actions = groupActions(resource.actions ?? []);
+	const hasSelectionAction = (resource.actions ?? []).some((action) => action.scope.includes("selection") && canRunAction(action));
+	return {
+		columns,
+		filters: list.filters ?? [],
+		sorts,
+		defaultSort: (list.defaultSort ?? "").split(",").filter((part) => part !== ""),
+		search: list.search ?? false,
+		layouts: list.layouts ?? ["table"],
+		perPage: list.perPage ?? 20,
+		perPageOptions: list.perPageOptions ?? [],
+		inlineEdit: list.inlineEdit ?? [],
+		selectable: (list.selectable ?? true) && hasSelectionAction,
+		actions
+	};
+}
+//#endregion
+export { DEFAULT_PER_PAGE, groupActions, resolveList };
+
+//# sourceMappingURL=list.js.map

package/dist/definition/list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.js","names":[],"sources":["../../src/definition/list.ts"],"sourcesContent":["import type { Action, ActionPlacement, Column, Field, Filter, Resource } from '@panneau/protocol';\n\nimport { canRunAction, getActionPlacements } from './abilities';\n\n/** A column ready to render. */\nexport interface ResolvedColumn {\n    /** The column id: its `id`, or the name of its field. */\n    id: string;\n    /** The field shown, when the column shows one. */\n    field: Field | null;\n    label: string;\n    /** How the value is displayed: the column's display, the field's, or the field type. */\n    display: string | null;\n    sortable: boolean;\n    width?: number | string;\n    align?: 'start' | 'center' | 'end';\n}\n\n/** A list ready to render. */\nexport interface ResolvedList {\n    columns: ResolvedColumn[];\n    filters: Filter[];\n    /** Fields the list can be sorted by. */\n    sorts: string[];\n    /** The default sort, as `sort` query values (`['-published_at', 'title']`). */\n    defaultSort: string[];\n    /** Whether the list can be searched (`q`). */\n    search: boolean;\n    /** List layouts, the first one being the default. */\n    layouts: string[];\n    perPage: number;\n    perPageOptions: number[];\n    /** Fields editable in the list. */\n    inlineEdit: string[];\n    /** Whether items can be selected: the list allows it and a selection action exists. */\n    selectable: boolean;\n    /** Actions the user can run, by placement. */\n    actions: Record<ActionPlacement, Action[]>;\n}\n\n/** Fields shown when the list declares no columns. */\nconst DEFAULT_COLUMN_COUNT = 4;\nconst NON_COLUMN_TYPES = new Set(['group', 'repeater', 'richtext']);\n\nexport const DEFAULT_PER_PAGE = 20;\n\nfunction columnsFromFields(resource: Resource): Column[] {\n    const title = resource.itemTitle;\n    const fields = resource.fields.filter((field) => !NON_COLUMN_TYPES.has(field.type));\n    const ordered =\n        title !== undefined\n            ? [\n                  ...fields.filter((field) => field.name === title),\n                  ...fields.filter((field) => field.name !== title),\n              ]\n            : fields;\n    return ordered.slice(0, DEFAULT_COLUMN_COUNT).map((field) => ({ field: field.name }));\n}\n\n/** Groups the actions the user can run by placement. */\nexport function groupActions(actions: readonly Action[]): Record<ActionPlacement, Action[]> {\n    const groups: Record<ActionPlacement, Action[]> = { row: [], toolbar: [], form: [], menu: [] };\n    actions.filter(canRunAction).forEach((action) => {\n        getActionPlacements(action).forEach((placement) => groups[placement].push(action));\n    });\n    return groups;\n}\n\n/**\n * Resolves the list of a resource. Without columns, it shows the item title and the next fields\n * (up to four, skipping groups, repeaters and rich text).\n */\nexport function resolveList(resource: Resource): ResolvedList {\n    const list = resource.list ?? {};\n    const fields = new Map(resource.fields.map((field) => [field.name, field]));\n    const sorts = list.sorts ?? [];\n    const columns = (list.columns ?? columnsFromFields(resource)).map((column): ResolvedColumn => {\n        const field = column.field !== undefined ? (fields.get(column.field) ?? null) : null;\n        const id = column.id ?? column.field ?? '';\n        const resolved: ResolvedColumn = {\n            id,\n            field,\n            label: column.label ?? field?.label ?? id,\n            display: column.display ?? field?.display ?? field?.type ?? null,\n            sortable:\n                column.sortable ?? (column.field !== undefined && sorts.includes(column.field)),\n        };\n        if (column.width !== undefined) {\n            resolved.width = column.width;\n        }\n        if (column.align !== undefined) {\n            resolved.align = column.align;\n        }\n        return resolved;\n    });\n    const actions = groupActions(resource.actions ?? []);\n    const hasSelectionAction = (resource.actions ?? []).some(\n        (action) => action.scope.includes('selection') && canRunAction(action),\n    );\n    return {\n        columns,\n        filters: list.filters ?? [],\n        sorts,\n        defaultSort: (list.defaultSort ?? '').split(',').filter((part) => part !== ''),\n        search: list.search ?? false,\n        layouts: list.layouts ?? ['table'],\n        perPage: list.perPage ?? DEFAULT_PER_PAGE,\n        perPageOptions: list.perPageOptions ?? [],\n        inlineEdit: list.inlineEdit ?? [],\n        selectable: (list.selectable ?? true) && hasSelectionAction,\n        actions,\n    };\n}\n"],"mappings":";;;AAyCA,IAAM,uBAAuB;AAC7B,IAAM,mCAAmB,IAAI,IAAI;CAAC;CAAS;CAAY;AAAU,CAAC;AAElE,IAAa,mBAAmB;AAEhC,SAAS,kBAAkB,UAA8B;CACrD,MAAM,QAAQ,SAAS;CACvB,MAAM,SAAS,SAAS,OAAO,QAAQ,UAAU,CAAC,iBAAiB,IAAI,MAAM,IAAI,CAAC;CAQlF,QANI,UAAU,KAAA,IACJ,CACI,GAAG,OAAO,QAAQ,UAAU,MAAM,SAAS,KAAK,GAChD,GAAG,OAAO,QAAQ,UAAU,MAAM,SAAS,KAAK,CAAC,IAErD,OAAA,CACK,MAAM,GAAG,oBAAoB,CAAC,CAAC,KAAK,WAAW,EAAE,OAAO,MAAM,KAAK,EAAE;AACxF;;AAGA,SAAgB,aAAa,SAA+D;CACxF,MAAM,SAA4C;EAAE,KAAK,CAAA;EAAI,SAAS,CAAA;EAAI,MAAM,CAAA;EAAI,MAAM,CAAA;CAAG;CAC7F,QAAQ,OAAO,YAAY,CAAC,CAAC,SAAS,WAAW;EAC7C,oBAAoB,MAAM,CAAC,CAAC,SAAS,cAAc,OAAO,UAAU,CAAC,KAAK,MAAM,CAAC;CACrF,CAAC;CACD,OAAO;AACX;;;;;AAMA,SAAgB,YAAY,UAAkC;CAC1D,MAAM,OAAO,SAAS,QAAQ,CAAC;CAC/B,MAAM,SAAS,IAAI,IAAI,SAAS,OAAO,KAAK,UAAU,CAAC,MAAM,MAAM,KAAK,CAAC,CAAC;CAC1E,MAAM,QAAQ,KAAK,SAAS,CAAA;CAC5B,MAAM,WAAW,KAAK,WAAW,kBAAkB,QAAQ,EAAA,CAAG,KAAK,WAA2B;EAC1F,MAAM,QAAQ,OAAO,UAAU,KAAA,IAAa,OAAO,IAAI,OAAO,KAAK,KAAK,OAAQ;EAChF,MAAM,KAAK,OAAO,MAAM,OAAO,SAAS;EACxC,MAAM,WAA2B;GAC7B;GACA;GACA,OAAO,OAAO,SAAS,OAAO,SAAS;GACvC,SAAS,OAAO,WAAW,OAAO,WAAW,OAAO,QAAQ;GAC5D,UACI,OAAO,aAAa,OAAO,UAAU,KAAA,KAAa,MAAM,SAAS,OAAO,KAAK;EACrF;EACA,IAAI,OAAO,UAAU,KAAA,GACjB,SAAS,QAAQ,OAAO;EAE5B,IAAI,OAAO,UAAU,KAAA,GACjB,SAAS,QAAQ,OAAO;EAE5B,OAAO;CACX,CAAC;CACD,MAAM,UAAU,aAAa,SAAS,WAAW,CAAA,CAAE;CACnD,MAAM,sBAAsB,SAAS,WAAW,CAAA,EAAA,CAAI,MAC/C,WAAW,OAAO,MAAM,SAAS,WAAW,KAAK,aAAa,MAAM,CACzE;CACA,OAAO;EACH;EACA,SAAS,KAAK,WAAW,CAAA;EACzB;EACA,cAAc,KAAK,eAAe,GAAA,CAAI,MAAM,GAAG,CAAC,CAAC,QAAQ,SAAS,SAAS,EAAE;EAC7E,QAAQ,KAAK,UAAU;EACvB,SAAS,KAAK,WAAW,CAAC,OAAO;EACjC,SAAS,KAAK,WAAA;EACd,gBAAgB,KAAK,kBAAkB,CAAA;EACvC,YAAY,KAAK,cAAc,CAAA;EAC/B,aAAa,KAAK,cAAc,SAAS;EACzC;CACJ;AACJ"}

package/dist/definition/resource.d.ts

@@ -0,0 +1,21 @@
+import type { Definition, Resource } from '@panneau/protocol';
+import { type ResolveFormOptions, type ResolvedForm } from './form';
+import { type ResolvedList } from './list';
+/** What the current user can do with a resource as a whole. */
+export interface ResourceAbilities {
+    viewAny: boolean;
+    create: boolean;
+}
+/** A resource with its form, its list and its abilities resolved. */
+export interface ResolvedResource {
+    resource: Resource;
+    /** The form to create an item. Use `resolveForm()` for an update, or an item type. */
+    form: ResolvedForm;
+    list: ResolvedList;
+    abilities: ResourceAbilities;
+}
+/** Resolves a resource into its form, its list and its abilities. */
+export declare function resolveResource(resource: Resource, formOptions?: ResolveFormOptions): ResolvedResource;
+/** Finds a resource of a definition by id. */
+export declare function findResource(definition: Definition, id: string): Resource | undefined;
+//# sourceMappingURL=resource.d.ts.map

package/dist/definition/resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../../src/definition/resource.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAG9D,OAAO,EAAE,KAAK,kBAAkB,EAAE,KAAK,YAAY,EAAe,MAAM,QAAQ,CAAC;AACjF,OAAO,EAAE,KAAK,YAAY,EAAe,MAAM,QAAQ,CAAC;AAExD,+DAA+D;AAC/D,MAAM,WAAW,iBAAiB;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;CACnB;AAED,qEAAqE;AACrE,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,EAAE,QAAQ,CAAC;IACnB,sFAAsF;IACtF,IAAI,EAAE,YAAY,CAAC;IACnB,IAAI,EAAE,YAAY,CAAC;IACnB,SAAS,EAAE,iBAAiB,CAAC;CAChC;AAED,qEAAqE;AACrE,wBAAgB,eAAe,CAC3B,QAAQ,EAAE,QAAQ,EAClB,WAAW,GAAE,kBAAuC,GACrD,gBAAgB,CAUlB;AAED,8CAA8C;AAC9C,wBAAgB,YAAY,CAAC,UAAU,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAErF"}

package/dist/definition/resource.js

@@ -0,0 +1,24 @@
+import { can } from "./abilities.js";
+import { resolveForm } from "./form.js";
+import { resolveList } from "./list.js";
+//#region src/definition/resource.ts
+/** Resolves a resource into its form, its list and its abilities. */
+function resolveResource(resource, formOptions = { mode: "create" }) {
+	return {
+		resource,
+		form: resolveForm(resource, formOptions),
+		list: resolveList(resource),
+		abilities: {
+			viewAny: can(resource.abilities, "viewAny"),
+			create: can(resource.abilities, "create")
+		}
+	};
+}
+/** Finds a resource of a definition by id. */
+function findResource(definition, id) {
+	return definition.resources.find((resource) => resource.id === id);
+}
+//#endregion
+export { findResource, resolveResource };
+
+//# sourceMappingURL=resource.js.map

package/dist/definition/resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.js","names":[],"sources":["../../src/definition/resource.ts"],"sourcesContent":["import type { Definition, Resource } from '@panneau/protocol';\n\nimport { can } from './abilities';\nimport { type ResolveFormOptions, type ResolvedForm, resolveForm } from './form';\nimport { type ResolvedList, resolveList } from './list';\n\n/** What the current user can do with a resource as a whole. */\nexport interface ResourceAbilities {\n    viewAny: boolean;\n    create: boolean;\n}\n\n/** A resource with its form, its list and its abilities resolved. */\nexport interface ResolvedResource {\n    resource: Resource;\n    /** The form to create an item. Use `resolveForm()` for an update, or an item type. */\n    form: ResolvedForm;\n    list: ResolvedList;\n    abilities: ResourceAbilities;\n}\n\n/** Resolves a resource into its form, its list and its abilities. */\nexport function resolveResource(\n    resource: Resource,\n    formOptions: ResolveFormOptions = { mode: 'create' },\n): ResolvedResource {\n    return {\n        resource,\n        form: resolveForm(resource, formOptions),\n        list: resolveList(resource),\n        abilities: {\n            viewAny: can(resource.abilities, 'viewAny'),\n            create: can(resource.abilities, 'create'),\n        },\n    };\n}\n\n/** Finds a resource of a definition by id. */\nexport function findResource(definition: Definition, id: string): Resource | undefined {\n    return definition.resources.find((resource) => resource.id === id);\n}\n"],"mappings":";;;;;AAsBA,SAAgB,gBACZ,UACA,cAAkC,EAAE,MAAM,SAAS,GACnC;CAChB,OAAO;EACH;EACA,MAAM,YAAY,UAAU,WAAW;EACvC,MAAM,YAAY,QAAQ;EAC1B,WAAW;GACP,SAAS,IAAI,SAAS,WAAW,SAAS;GAC1C,QAAQ,IAAI,SAAS,WAAW,QAAQ;EAC5C;CACJ;AACJ;;AAGA,SAAgB,aAAa,YAAwB,IAAkC;CACnF,OAAO,WAAW,UAAU,MAAM,aAAa,SAAS,OAAO,EAAE;AACrE"}

package/dist/form/form.d.ts

@@ -0,0 +1,148 @@
+import { type Condition, type Field, type Item, type RuleFailure } from '@panneau/protocol';
+import type { FormMode } from '../definition/form';
+import { type Values } from '../values';
+import { type FormStore } from './store';
+/**
+ * - `idle`: nothing submitted yet, or after a reset;
+ * - `submitting`: waiting for `onSubmit`;
+ * - `submitted`: the last submit succeeded;
+ * - `invalid`: client validation or the server (`422`) found errors;
+ * - `conflict`: the item changed since the form's version (`412`), see `resolveConflict()`;
+ * - `error`: the last submit failed for another reason (network, `403`, `500`…), see `error`.
+ */
+export type FormStatus = 'idle' | 'submitting' | 'submitted' | 'invalid' | 'conflict' | 'error';
+export interface FormConflict {
+    /** The current version of the item, when the backend sent it. */
+    current: Item | null;
+}
+/** A snapshot of a form. A new object is created on every change. */
+export interface FormState {
+    values: Values;
+    /** The values the form started from, or was last saved with. `dirty` compares to them. */
+    initialValues: Values;
+    /** The version of the item the values were edited from, sent with the submit. */
+    version: string | null;
+    /** Whether the values differ from the initial values. */
+    dirty: boolean;
+    /**
+     * Errors shown, by dot path (`title.fr`): client errors of touched fields (all of them after a
+     * submit), then server errors. A server error goes away when its value changes.
+     */
+    errors: Record<string, string[]>;
+    /** Paths of the fields that lost focus at least once. */
+    touched: ReadonlySet<string>;
+    status: FormStatus;
+    /** With the `conflict` status: what the backend says is current. */
+    conflict: FormConflict | null;
+    /** With the `error` status: what `onSubmit` threw. */
+    error: unknown;
+    submitCount: number;
+}
+export interface SubmitContext {
+    mode: FormMode;
+    /** The version to send as `If-Match`. */
+    version: string | null;
+    /** The top-level values that differ from the initial values, for partial updates. */
+    changes: Values;
+}
+export type SubmitResult = {
+    status: 'submitted';
+    result: unknown;
+} | {
+    status: 'invalid';
+    errors: Record<string, string[]>;
+} | {
+    status: 'conflict';
+    current: Item | null;
+} | {
+    status: 'error';
+    error: unknown;
+};
+export interface FormOptions {
+    /** The fields of the form, as resolved by `resolveForm()`. */
+    fields: Field[];
+    /** Initial values. In `create` mode, fields without a value get their `default`. */
+    values?: Values;
+    /** The version of the item the values come from. */
+    version?: string | null;
+    /** Defaults to `update` when a version is given, `create` otherwise. */
+    mode?: FormMode;
+    /** Locales a `required` localized field must be filled in (all of them, usually). */
+    locales?: string[];
+    /** Where the values live. Defaults to a local store. */
+    store?: FormStore;
+    /** Message of a failed rule. Defaults to `formatRuleFailure()`. */
+    formatError?: (failure: RuleFailure, path: string) => string;
+    /**
+     * Saves the values. When it returns an item, the form continues from that item. When it
+     * throws an error that carries problem details (`getProblem()`), `422` errors are shown by
+     * path and `412` puts the form in the `conflict` status.
+     */
+    onSubmit?: (values: Values, context: SubmitContext) => unknown;
+}
+/** Form options that can change after the form is created. */
+export type UpdatableFormOptions = Pick<FormOptions, 'fields' | 'locales' | 'formatError' | 'onSubmit'>;
+export interface GetErrorsOptions {
+    /** Also return the errors of nested paths (`title.fr` for `title`). */
+    nested?: boolean;
+}
+/**
+ * A headless form: values, errors, visibility and submit. React components use `useForm()`.
+ *
+ * The methods that read the state (`getValue()`, `getErrors()`, `countErrors()`, `isVisible()`)
+ * are not React APIs: the React Compiler memoizes their calls by their arguments, so they return
+ * stale results in components. Components read the state they subscribed to with the selectors
+ * (`selectValue()`, `selectErrors()`, `selectErrorCount()`, `selectVisible()`).
+ */
+export interface Form {
+    getState(): FormState;
+    subscribe(listener: () => void): () => void;
+    /** Updates the options that can change between renders. */
+    setOptions(options: Partial<UpdatableFormOptions>): void;
+    /**
+     * The value at a dot path. Not a React API: components use `selectValue(state, path)` (see
+     * {@link Form}).
+     */
+    getValue(path: string): unknown;
+    setValue(path: string, value: unknown): void;
+    /** Marks a field as touched, which shows its client errors. */
+    blur(path: string): void;
+    /**
+     * Errors at a path. Not a React API: components use `selectErrors(state, path, options)` (see
+     * {@link Form}).
+     */
+    getErrors(path: string, options?: GetErrorsOptions): string[];
+    /**
+     * The number of paths with errors within the given paths, for counts on tabs and sections. Not
+     * a React API: components use `selectErrorCount(state, paths)` (see {@link Form}).
+     */
+    countErrors(paths: readonly string[]): number;
+    /**
+     * Whether a field or a layout node is visible, from its `visibleWhen`. For nested fields, pass
+     * the path of the object they belong to (`blocks.2`): conditions are relative to it. Not a
+     * React API: components use `selectVisible(state, target, parentPath)` (see {@link Form}).
+     */
+    isVisible(target: {
+        visibleWhen?: Condition | undefined;
+    }, parentPath?: string): boolean;
+    /** Checks every value with the portable rules and shows every error. Returns whether valid. */
+    validate(): boolean;
+    /** Shows server errors, by dot path. */
+    setServerErrors(errors: Record<string, string[]>): void;
+    /** Validates, then calls `onSubmit`. */
+    submit(): Promise<SubmitResult>;
+    /** Starts over from new values (or the initial ones), and a new version. */
+    reset(values?: Values, version?: string | null): void;
+    /**
+     * Leaves the `conflict` status:
+     *
+     * - `reload` drops the local changes and continues from the current item;
+     * - `overwrite` keeps the local changes and submits them again over the current version.
+     */
+    resolveConflict(choice: 'reload' | 'overwrite'): Promise<SubmitResult | null>;
+}
+/** Initial values of fields that have a `default` and no value. */
+export declare function getDefaultValues(fields: readonly Field[], values?: Values): Values;
+/** Creates a headless form. */
+export declare function createForm(options: FormOptions): Form;
+//# sourceMappingURL=form.d.ts.map

package/dist/form/form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form.d.ts","sourceRoot":"","sources":["../../src/form/form.ts"],"names":[],"mappings":"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"}