@jini-ai/admin 0.3.10 → 0.4.1

package/dist/react/entities/rules.d.ts

@@ -0,0 +1,179 @@
+import type { AdminEntityDescriptor, AdminEntityRelationField, AdminEntityRowData } from '../../core/ports/entities.js';
+import type { EntityRegistryPort } from './types.js';
+export declare const RELATION_OPTION_LIMIT = 100;
+export declare function resolveEntityPageSize({ raw }: {
+    readonly raw: string | null;
+}): number;
+/** Every `relation` field on a descriptor, narrowed so `target` is reachable. */
+export declare function relationFieldsOf({ descriptor }: {
+    readonly descriptor: AdminEntityDescriptor;
+}): readonly AdminEntityRelationField[];
+/** One relation target's options: what a picker offers, and what a list cell resolves against. */
+export interface RelationOptions {
+    /** Target rows as `{ id, title }`, in the target's own list order. */
+    readonly options: readonly {
+        readonly id: string;
+        readonly title: string;
+    }[];
+    /** `id` -> title, for O(1) cell rendering. */
+    readonly titles: Readonly<Record<string, string>>;
+    /** True when the target has more rows than {@link RELATION_OPTION_LIMIT} loaded here. */
+    readonly truncated: boolean;
+}
+/** Relation target name -> its loaded options. Keyed by TARGET, not by field, so two fields
+ *  pointing at the same entity share one load. */
+export type RelationIndex = Readonly<Record<string, RelationOptions>>;
+/**
+ * Loads the option set for every distinct relation target on `descriptor`.
+ *
+ * @param descriptor The entity whose relations need resolving.
+ * @param registry Host registry resolving a target's existing entity port.
+ * @returns One entry per distinct target. A target that does not resolve is simply absent, and the
+ *   screens then render the raw stored id marked as unresolved rather than a blank cell.
+ * @complexity One `list` call per distinct target, in parallel; O(targets × limit) rows held.
+ * @overallScore 100
+ */
+export declare function loadRelationIndex({ descriptor, registry }: {
+    readonly descriptor: AdminEntityDescriptor;
+    readonly registry: EntityRegistryPort;
+}): Promise<RelationIndex>;
+/**
+ * A row's human-readable title, or `null` when the descriptor's `titleField` does not resolve to a
+ * string on this row.
+ *
+ * Returns `null` rather than `String(value)` so a caller falls back to the id: a picker rendering
+ * the literal text `undefined` for every row is the exact symptom of a mistyped `titleField`, and
+ * `createAdminEntityRegistry` already rejects that at startup — this guards the remaining case,
+ * where the field is declared correctly and one row simply has no value for it.
+ *
+ * @complexity Time O(1).
+ * @overallScore 100
+ */
+export declare function readTitle({ row, titleField }: {
+    readonly row: AdminEntityRowData;
+    readonly titleField: string;
+}): string | null;
+/**
+ * The draft a "new" form starts from.
+ *
+ * Every declared field is present and absent-valued, so each control is controlled from the first
+ * render rather than switching from uncontrolled on the first keystroke.
+ *
+ * The one exception is a REQUIRED boolean, which starts `false`. A checkbox has no third state: an
+ * untouched one already means "no", so leaving it absent would block Save on a field the operator
+ * has, visibly, already answered — they would have to tick it and untick it to satisfy a
+ * requirement the unticked box was expressing all along. An OPTIONAL boolean stays absent, because
+ * there "unanswered" and "no" are genuinely different and only the descriptor's author knows which
+ * the row means.
+ *
+ * @complexity Time O(fields).
+ * @overallScore 100
+ */
+export declare function emptyDraft({ descriptor }: {
+    readonly descriptor: AdminEntityDescriptor;
+}): Record<string, unknown>;
+/**
+ * The draft an editor opens with: {@link emptyDraft}'s floor, with `row`'s declared values on top.
+ *
+ * Layered rather than `{ ...row }`, and that is the whole point. A row is not guaranteed to carry
+ * every declared field — an app that adds a `required` field to its descriptor has existing rows
+ * that predate it — and a draft built from the row alone inherits that gap. For a required BOOLEAN
+ * the consequence is {@link emptyDraft}'s trap arriving by the other door: the checkbox renders
+ * unticked, which already says "no", while Save stays blocked on "required and still empty" until
+ * the operator ticks and unticks it. The create path was fixed for this and the edit path was not,
+ * because they built their drafts in two different places.
+ *
+ * Only DECLARED fields are copied. A key the descriptor does not mention is invisible to every
+ * control on the screen, so carrying it into the draft would send a value back on save that nobody
+ * could see or edit — and `eraseEntityPort` reports it as an `undeclared-field` violation on the
+ * way in, so it is already known to be adapter drift rather than data.
+ *
+ * `id` is never copied: it is implicit on every row and `createAdminEntityRegistry` rejects any
+ * descriptor that declares it as a field.
+ *
+ * @param descriptor The entity being edited.
+ * @param row An existing row, or `null` when creating.
+ * @returns A draft with one entry per declared field.
+ * @complexity Time O(fields).
+ * @overallScore 100
+ */
+export declare function draftForRow({ descriptor, row }: {
+    readonly descriptor: AdminEntityDescriptor;
+    readonly row: AdminEntityRowData | null;
+}): Record<string, unknown>;
+/** Field names whose declared `required: true` is not satisfied by `draft`. */
+export declare function missingRequiredFields({ descriptor, draft }: {
+    readonly descriptor: AdminEntityDescriptor;
+    readonly draft: Record<string, unknown>;
+}): readonly string[];
+/** One draft entry that holds a value its declared kind does not accept. */
+export interface DraftFieldProblem {
+    readonly field: string;
+    /** Reads as "servings: is not an integer" — the port's own wording, not a second opinion. */
+    readonly detail: string;
+}
+/**
+ * Every draft entry whose value its declared kind would reject.
+ *
+ * Delegates to `describeAdminEntityFieldMismatch` — the SAME function `eraseEntityPort` uses to
+ * report adapter violations — rather than re-deciding here what an `integer` accepts. Two
+ * validators for one rule drift, and the drift is silent in the worst direction: the form saves a
+ * value the port then reports as a violation, so the write succeeds and the console blames the
+ * adapter for something the editor produced.
+ *
+ * The values this actually catches all come from `<input type="number">`, whose `step` constrains
+ * the spinner and not the parsed value: `1.5` typed into an `integer`, and `1e400` typed into a
+ * `real`, which becomes `Infinity` and then `null` the moment it meets `JSON.stringify`. Neither
+ * field kind appears in any descriptor the browser acceptance run renders, so neither has ever been
+ * seen to fail.
+ *
+ * Blank entries are skipped: an absent value is {@link missingRequiredFields}' business when the
+ * field is required, and legitimate when it is not.
+ *
+ * @complexity Time O(fields), plus the bounded JSON walk for each `json` field.
+ * @overallScore 100
+ */
+export declare function invalidDraftFields({ descriptor, draft }: {
+    readonly descriptor: AdminEntityDescriptor;
+    readonly draft: Record<string, unknown>;
+}): readonly DraftFieldProblem[];
+/**
+ * ISO-8601 -> the `YYYY-MM-DDTHH:mm:ss` an `<input type="datetime-local" step="1">` requires, read
+ * as UTC.
+ *
+ * Read and written as UTC on purpose, and labelled as such next to the control. Converting to the
+ * viewer's local zone would round-trip a stored instant through two conversions and shift it by the
+ * offset whenever the two disagree about DST — a bug that is invisible for anyone in UTC and
+ * corrupts timestamps for everyone else.
+ *
+ * Seconds are carried, not trimmed. The obvious `slice(0, 16)` matches the `datetime-local`
+ * default, and quietly rewrites `10:30:45Z` to `10:30:00Z` on the next Save of a row nobody meant
+ * to change the time of. Every timestamp in the dummy app is `00:00:00.000Z`, so the truncation is
+ * a no-op in the only data the acceptance run sees.
+ *
+ * @param value A stored field value, of any type.
+ * @returns The control's value, or `""` for anything not a parseable timestamp — which is what an
+ *   empty `datetime-local` shows anyway.
+ * @complexity Time O(1).
+ * @overallScore 100
+ */
+export declare function toDatetimeLocalValue({ value }: {
+    readonly value: unknown;
+}): string;
+/**
+ * The inverse: a `datetime-local` control's value -> a stored ISO-8601 instant, read as UTC.
+ *
+ * The `Z` is what makes it UTC — without it the string is parsed in the browser's local zone, which
+ * is the half of the round trip that silently shifts an instant for everyone not in UTC.
+ *
+ * @param raw The control's `value`, `YYYY-MM-DDTHH:mm` or `YYYY-MM-DDTHH:mm:ss`.
+ * @returns `undefined` for an empty control; the ISO instant otherwise; and `raw` UNCHANGED when it
+ *   will not parse — so `invalidDraftFields` reports it and Save is blocked, rather than this
+ *   throwing a `RangeError` through a render or silently discarding what the operator typed.
+ * @complexity Time O(1).
+ * @overallScore 100
+ */
+export declare function fromDatetimeLocalValue({ raw }: {
+    readonly raw: string;
+}): string | undefined;
+//# sourceMappingURL=rules.d.ts.map

package/dist/react/entities/rules.js

@@ -0,0 +1,224 @@
+import { describeAdminEntityFieldMismatch } from '../../core/entities/rules.js';
+export const RELATION_OPTION_LIMIT = 100;
+export function resolveEntityPageSize({ raw }) {
+    const parsed = Number(raw);
+    return Number.isInteger(parsed) && parsed > 0 ? Math.min(parsed, 200) : 25;
+}
+/** Every `relation` field on a descriptor, narrowed so `target` is reachable. */
+export function relationFieldsOf({ descriptor }) {
+    return descriptor.fields.filter((field) => field.kind === "relation");
+}
+/**
+ * Loads the option set for every distinct relation target on `descriptor`.
+ *
+ * @param descriptor The entity whose relations need resolving.
+ * @param registry Host registry resolving a target's existing entity port.
+ * @returns One entry per distinct target. A target that does not resolve is simply absent, and the
+ *   screens then render the raw stored id marked as unresolved rather than a blank cell.
+ * @complexity One `list` call per distinct target, in parallel; O(targets × limit) rows held.
+ * @overallScore 100
+ */
+export async function loadRelationIndex({ descriptor, registry }) {
+    const targets = [...new Set(relationFieldsOf({ descriptor }).map((field) => field.target))];
+    const loaded = await Promise.all(targets.map(async (target) => {
+        const port = registry.getEntity({ name: target });
+        if (port === null)
+            return null;
+        const page = await port.list({ limit: RELATION_OPTION_LIMIT });
+        const { titleField } = port.descriptor;
+        const options = page.items.map((row) => ({
+            id: row.id,
+            title: readTitle({ row, titleField }) ?? row.id,
+        }));
+        const titles = Object.create(null);
+        for (const option of options)
+            titles[option.id] = option.title;
+        // Truncation is read from `nextCursor`, not from `total`: `total` is optional on the port,
+        // so an adapter that omits it would make every over-long target silently look complete.
+        return [target, { options, titles, truncated: page.nextCursor !== null }];
+    }));
+    return Object.fromEntries(loaded.filter((entry) => entry !== null));
+}
+/**
+ * A row's human-readable title, or `null` when the descriptor's `titleField` does not resolve to a
+ * string on this row.
+ *
+ * Returns `null` rather than `String(value)` so a caller falls back to the id: a picker rendering
+ * the literal text `undefined` for every row is the exact symptom of a mistyped `titleField`, and
+ * `createAdminEntityRegistry` already rejects that at startup — this guards the remaining case,
+ * where the field is declared correctly and one row simply has no value for it.
+ *
+ * @complexity Time O(1).
+ * @overallScore 100
+ */
+export function readTitle({ row, titleField }) {
+    const value = row[titleField];
+    return typeof value === "string" && value !== "" ? value : null;
+}
+/**
+ * The draft a "new" form starts from.
+ *
+ * Every declared field is present and absent-valued, so each control is controlled from the first
+ * render rather than switching from uncontrolled on the first keystroke.
+ *
+ * The one exception is a REQUIRED boolean, which starts `false`. A checkbox has no third state: an
+ * untouched one already means "no", so leaving it absent would block Save on a field the operator
+ * has, visibly, already answered — they would have to tick it and untick it to satisfy a
+ * requirement the unticked box was expressing all along. An OPTIONAL boolean stays absent, because
+ * there "unanswered" and "no" are genuinely different and only the descriptor's author knows which
+ * the row means.
+ *
+ * @complexity Time O(fields).
+ * @overallScore 100
+ */
+export function emptyDraft({ descriptor }) {
+    const draft = Object.create(null);
+    for (const field of descriptor.fields) {
+        draft[field.name] = field.kind === "boolean" && field.required === true ? false : undefined;
+    }
+    return draft;
+}
+/**
+ * The draft an editor opens with: {@link emptyDraft}'s floor, with `row`'s declared values on top.
+ *
+ * Layered rather than `{ ...row }`, and that is the whole point. A row is not guaranteed to carry
+ * every declared field — an app that adds a `required` field to its descriptor has existing rows
+ * that predate it — and a draft built from the row alone inherits that gap. For a required BOOLEAN
+ * the consequence is {@link emptyDraft}'s trap arriving by the other door: the checkbox renders
+ * unticked, which already says "no", while Save stays blocked on "required and still empty" until
+ * the operator ticks and unticks it. The create path was fixed for this and the edit path was not,
+ * because they built their drafts in two different places.
+ *
+ * Only DECLARED fields are copied. A key the descriptor does not mention is invisible to every
+ * control on the screen, so carrying it into the draft would send a value back on save that nobody
+ * could see or edit — and `eraseEntityPort` reports it as an `undeclared-field` violation on the
+ * way in, so it is already known to be adapter drift rather than data.
+ *
+ * `id` is never copied: it is implicit on every row and `createAdminEntityRegistry` rejects any
+ * descriptor that declares it as a field.
+ *
+ * @param descriptor The entity being edited.
+ * @param row An existing row, or `null` when creating.
+ * @returns A draft with one entry per declared field.
+ * @complexity Time O(fields).
+ * @overallScore 100
+ */
+export function draftForRow({ descriptor, row }) {
+    const draft = emptyDraft({ descriptor });
+    if (row === null)
+        return draft;
+    for (const field of descriptor.fields) {
+        // Skips `undefined` rather than spreading: an adapter that patches a row with an absent value
+        // leaves an OWN key holding `undefined`, and spreading that would overwrite the `false` floor a
+        // required boolean depends on.
+        const value = row[field.name];
+        if (value !== undefined)
+            draft[field.name] = value;
+    }
+    return draft;
+}
+/**
+ * Whether `value` reads as "the operator has not filled this in".
+ *
+ * `false` and `0` are deliberately NOT blank — they are answers, and a truthiness test that calls
+ * them empty is the single most reliable way to make a boolean or a numeric field unsaveable at its
+ * most ordinary value. `""` is blank for every kind whose control is a text box, but NOT for
+ * `json`, where the JSON string `""` is a legitimate stored value that is visibly on screen.
+ *
+ * @complexity Time O(1).
+ * @overallScore 100
+ */
+function isBlankDraftValue(field, value) {
+    if (value === undefined)
+        return true;
+    return field.kind !== "json" && value === "";
+}
+/** Field names whose declared `required: true` is not satisfied by `draft`. */
+export function missingRequiredFields({ descriptor, draft }) {
+    return descriptor.fields
+        .filter((field) => field.required === true)
+        .filter((field) => isBlankDraftValue(field, draft[field.name]))
+        .map((field) => field.name);
+}
+/**
+ * Every draft entry whose value its declared kind would reject.
+ *
+ * Delegates to `describeAdminEntityFieldMismatch` — the SAME function `eraseEntityPort` uses to
+ * report adapter violations — rather than re-deciding here what an `integer` accepts. Two
+ * validators for one rule drift, and the drift is silent in the worst direction: the form saves a
+ * value the port then reports as a violation, so the write succeeds and the console blames the
+ * adapter for something the editor produced.
+ *
+ * The values this actually catches all come from `<input type="number">`, whose `step` constrains
+ * the spinner and not the parsed value: `1.5` typed into an `integer`, and `1e400` typed into a
+ * `real`, which becomes `Infinity` and then `null` the moment it meets `JSON.stringify`. Neither
+ * field kind appears in any descriptor the browser acceptance run renders, so neither has ever been
+ * seen to fail.
+ *
+ * Blank entries are skipped: an absent value is {@link missingRequiredFields}' business when the
+ * field is required, and legitimate when it is not.
+ *
+ * @complexity Time O(fields), plus the bounded JSON walk for each `json` field.
+ * @overallScore 100
+ */
+export function invalidDraftFields({ descriptor, draft }) {
+    const problems = [];
+    for (const field of descriptor.fields) {
+        const value = draft[field.name];
+        if (isBlankDraftValue(field, value))
+            continue;
+        const detail = describeAdminEntityFieldMismatch(field, value);
+        if (detail !== null)
+            problems.push({ field: field.name, detail });
+    }
+    return problems;
+}
+/**
+ * ISO-8601 -> the `YYYY-MM-DDTHH:mm:ss` an `<input type="datetime-local" step="1">` requires, read
+ * as UTC.
+ *
+ * Read and written as UTC on purpose, and labelled as such next to the control. Converting to the
+ * viewer's local zone would round-trip a stored instant through two conversions and shift it by the
+ * offset whenever the two disagree about DST — a bug that is invisible for anyone in UTC and
+ * corrupts timestamps for everyone else.
+ *
+ * Seconds are carried, not trimmed. The obvious `slice(0, 16)` matches the `datetime-local`
+ * default, and quietly rewrites `10:30:45Z` to `10:30:00Z` on the next Save of a row nobody meant
+ * to change the time of. Every timestamp in the dummy app is `00:00:00.000Z`, so the truncation is
+ * a no-op in the only data the acceptance run sees.
+ *
+ * @param value A stored field value, of any type.
+ * @returns The control's value, or `""` for anything not a parseable timestamp — which is what an
+ *   empty `datetime-local` shows anyway.
+ * @complexity Time O(1).
+ * @overallScore 100
+ */
+export function toDatetimeLocalValue({ value }) {
+    if (typeof value !== "string" || value === "")
+        return "";
+    const parsed = new Date(value);
+    if (Number.isNaN(parsed.getTime()))
+        return "";
+    const iso = parsed.toISOString();
+    return iso.endsWith('.000Z') ? iso.slice(0, 19) : iso.slice(0, 23);
+}
+/**
+ * The inverse: a `datetime-local` control's value -> a stored ISO-8601 instant, read as UTC.
+ *
+ * The `Z` is what makes it UTC — without it the string is parsed in the browser's local zone, which
+ * is the half of the round trip that silently shifts an instant for everyone not in UTC.
+ *
+ * @param raw The control's `value`, `YYYY-MM-DDTHH:mm` or `YYYY-MM-DDTHH:mm:ss`.
+ * @returns `undefined` for an empty control; the ISO instant otherwise; and `raw` UNCHANGED when it
+ *   will not parse — so `invalidDraftFields` reports it and Save is blocked, rather than this
+ *   throwing a `RangeError` through a render or silently discarding what the operator typed.
+ * @complexity Time O(1).
+ * @overallScore 100
+ */
+export function fromDatetimeLocalValue({ raw }) {
+    if (raw === "")
+        return undefined;
+    const parsed = new Date(`${raw}Z`);
+    return Number.isNaN(parsed.getTime()) ? raw : parsed.toISOString();
+}
+//# sourceMappingURL=rules.js.map

package/dist/react/entities/types.d.ts

@@ -0,0 +1,45 @@
+import type { AdminErasedEntityPort } from '../../core/ports/entities.js';
+/** Resolves existing entity ports; replace the registry object when registrations change. */
+export interface EntityRegistryPort {
+    listEntities(args: Record<string, never>): readonly AdminErasedEntityPort[];
+    getEntity(args: {
+        readonly name: string;
+    }): AdminErasedEntityPort | null;
+}
+export type EntityTranslate = (args: {
+    readonly key: string;
+}) => string;
+export interface EntityRouteTarget {
+    readonly entity?: string;
+    readonly id?: string;
+    readonly view?: 'list' | 'detail' | 'edit' | 'create';
+}
+export interface EntityRoutesPort {
+    href(args: EntityRouteTarget): string;
+    navigate(args: EntityRouteTarget): void;
+}
+export interface EntityScreenDependencies {
+    readonly registry: EntityRegistryPort;
+    readonly translate: EntityTranslate;
+    readonly routes: EntityRoutesPort;
+}
+export interface EntityListProps extends EntityScreenDependencies {
+    readonly entityName: string;
+    readonly limitParam: string | null;
+}
+export interface EntityDetailProps extends EntityScreenDependencies {
+    readonly entityName: string;
+    readonly id: string;
+}
+export interface EntityEditProps extends EntityScreenDependencies {
+    readonly entityName: string;
+    /** Null creates a row. All string ids, including `new`, refer to saved rows. */
+    readonly id: string | null;
+}
+/** Stable source templates let host dictionaries translate copy before values are inserted. */
+export declare function entityText({ translate, key, values }: {
+    readonly translate: EntityTranslate;
+    readonly key: string;
+    readonly values: Readonly<Record<string, string | number>>;
+}): string;
+//# sourceMappingURL=types.d.ts.map

package/dist/react/entities/types.js

@@ -0,0 +1,5 @@
+/** Stable source templates let host dictionaries translate copy before values are inserted. */
+export function entityText({ translate, key, values }) {
+    return translate({ key: key }).replace(/\{([\w]+)\}/g, (match, name) => Object.hasOwn(values, name) ? String(values[name]) : match);
+}
+//# sourceMappingURL=types.js.map

package/dist/react/entities/use-entity-edit.d.ts

@@ -0,0 +1,35 @@
+import type { AdminErasedEntityPort } from '../../core/ports/entities.js';
+import type { EntityEditProps } from './types.js';
+interface FormState {
+    readonly draft: Record<string, unknown>;
+    readonly jsonText: Readonly<Record<string, string>>;
+    readonly jsonErrors: Readonly<Record<string, boolean>>;
+}
+/** Called by the editor mounted for one entity/id pair. */
+export declare function useEntityEdit({ port, ...props }: EntityEditProps & {
+    readonly port: AdminErasedEntityPort;
+}): {
+    form: FormState | null;
+    read: {
+        readonly data: import("./use-entity-read.js").EntityLoadedRow | undefined;
+        readonly error: unknown;
+        readonly loading: boolean;
+    };
+    missing: readonly string[];
+    invalid: readonly import("./rules.js").DraftFieldProblem[];
+    canSave: boolean;
+    pending: "remove" | "save" | null;
+    failed: boolean;
+    setField: ({ name, value }: {
+        readonly name: string;
+        readonly value: unknown;
+    }) => void;
+    setJsonText: ({ name, text }: {
+        readonly name: string;
+        readonly text: string;
+    }) => void;
+    save: () => Promise<void>;
+    remove: () => Promise<void>;
+};
+export {};
+//# sourceMappingURL=use-entity-edit.d.ts.map

package/dist/react/entities/use-entity-edit.js

@@ -0,0 +1,98 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { draftForRow, invalidDraftFields, missingRequiredFields } from './rules.js';
+import { loadEntityRow, useEntityRead } from './use-entity-read.js';
+/** Called by the editor mounted for one entity/id pair. */
+export function useEntityEdit({ port, ...props }) {
+    const { entityName, id, registry, routes } = props;
+    const scope = useMemo(() => ({ port, registry, entityName, id }), [port, registry, entityName, id]);
+    const currentScope = useRef(scope);
+    currentScope.current = scope;
+    const mounted = useRef(true);
+    useEffect(() => { mounted.current = true; return () => { mounted.current = false; }; }, []);
+    const load = useCallback(() => loadEntityRow({ registry, entityName, id }), [registry, entityName, id, port]);
+    const read = useEntityRead({ load, scope });
+    const [formState, setFormState] = useState(null);
+    const [mutation, setMutation] = useState({ scope, kind: null, failed: false });
+    const busy = useRef(false);
+    let form = formState?.scope === scope ? formState.form : null;
+    if (read.data && form === null && (id === null || read.data.row !== null)) {
+        const draft = draftForRow({ descriptor: port.descriptor, row: read.data.row });
+        const jsonText = Object.create(null);
+        for (const field of port.descriptor.fields) {
+            if (field.kind === 'json')
+                jsonText[field.name] = draft[field.name] === undefined ? '' : JSON.stringify(draft[field.name], null, 2);
+        }
+        form = { draft, jsonText, jsonErrors: {} };
+        setFormState({ scope, form });
+    }
+    const draft = form?.draft ?? {};
+    const missing = missingRequiredFields({ descriptor: port.descriptor, draft });
+    const invalid = invalidDraftFields({ descriptor: port.descriptor, draft });
+    const pending = mutation.scope === scope ? mutation.kind : null;
+    const canSave = form !== null && missing.length === 0 && invalid.length === 0 &&
+        !Object.values(form.jsonErrors).some(Boolean) && pending === null;
+    function setField({ name, value }) {
+        if (!port.descriptor.fields.some((field) => field.name === name) || busy.current)
+            return;
+        setFormState((state) => state?.scope === scope ? { scope, form: { ...state.form, draft: { ...state.form.draft, [name]: value } } } : state);
+    }
+    function setJsonText({ name, text }) {
+        if (!port.descriptor.fields.some((field) => field.name === name && field.kind === 'json') || busy.current)
+            return;
+        let value;
+        let failed = false;
+        try {
+            value = text.trim() === '' ? undefined : JSON.parse(text);
+        }
+        catch {
+            failed = true;
+        }
+        setFormState((state) => state?.scope === scope ? {
+            scope,
+            form: {
+                draft: failed ? state.form.draft : { ...state.form.draft, [name]: value },
+                jsonText: { ...state.form.jsonText, [name]: text },
+                jsonErrors: { ...state.form.jsonErrors, [name]: failed },
+            },
+        } : state);
+    }
+    async function mutate({ kind }) {
+        if (busy.current || (kind === 'save' && !canSave) || (kind === 'remove' && (id === null || port.remove === undefined)))
+            return;
+        busy.current = true;
+        setMutation({ scope, kind, failed: false });
+        const active = () => mounted.current && currentScope.current === scope;
+        try {
+            if (kind === 'remove' && id !== null && port.remove) {
+                await port.remove(id);
+                if (active())
+                    routes.navigate({ entity: entityName });
+            }
+            else {
+                // A create omits blanks; an update carries explicit undefined to clear optional fields.
+                const saved = id === null
+                    ? await port.create(Object.fromEntries(Object.entries(draft).filter(([, value]) => value !== undefined)))
+                    : await port.update(id, draft);
+                if (active())
+                    routes.navigate({ entity: entityName, id: saved.id });
+            }
+            if (active())
+                setMutation({ scope, kind: null, failed: false });
+        }
+        catch {
+            if (active())
+                setMutation({ scope, kind: null, failed: true });
+        }
+        finally {
+            busy.current = false;
+        }
+    }
+    return {
+        form, read, missing, invalid, canSave, pending,
+        failed: mutation.scope === scope && mutation.failed,
+        setField, setJsonText,
+        save: () => mutate({ kind: 'save' }),
+        remove: () => mutate({ kind: 'remove' }),
+    };
+}
+//# sourceMappingURL=use-entity-edit.js.map

package/dist/react/entities/use-entity-read.d.ts

@@ -0,0 +1,22 @@
+import type { AdminEntityRowData } from '../../core/ports/entities.js';
+import type { EntityRegistryPort } from './types.js';
+import { type RelationIndex } from './rules.js';
+/** Per-mount async state; stale results are discarded and reads never overwrite another route. */
+export declare function useEntityRead<T>({ load, scope }: {
+    readonly load: () => Promise<T>;
+    readonly scope: unknown;
+}): {
+    readonly data: T | undefined;
+    readonly error: unknown;
+    readonly loading: boolean;
+};
+export interface EntityLoadedRow {
+    readonly row: AdminEntityRowData | null;
+    readonly relations: RelationIndex;
+}
+export declare function loadEntityRow({ registry, entityName, id }: {
+    readonly registry: EntityRegistryPort;
+    readonly entityName: string;
+    readonly id: string | null;
+}): Promise<EntityLoadedRow>;
+//# sourceMappingURL=use-entity-read.d.ts.map

package/dist/react/entities/use-entity-read.js

@@ -0,0 +1,27 @@
+import { useEffect, useState } from 'react';
+import { loadRelationIndex } from './rules.js';
+/** Per-mount async state; stale results are discarded and reads never overwrite another route. */
+export function useEntityRead({ load, scope }) {
+    const [state, setState] = useState({ scope, load });
+    useEffect(() => {
+        let active = true;
+        setState({ scope, load });
+        Promise.resolve().then(load).then((data) => { if (active)
+            setState({ scope, load, data }); }, (error) => { if (active)
+            setState({ scope, load, error }); });
+        return () => { active = false; };
+    }, [load, scope]);
+    const current = state.scope === scope && state.load === load ? state : null;
+    return { data: current?.data, error: current?.error, loading: current === null || (!Object.hasOwn(current, 'data') && !Object.hasOwn(current, 'error')) };
+}
+export async function loadEntityRow({ registry, entityName, id }) {
+    const port = registry.getEntity({ name: entityName });
+    if (port === null)
+        return { row: null, relations: {} };
+    const [row, relations] = await Promise.all([
+        id === null ? Promise.resolve(null) : port.get(id),
+        loadRelationIndex({ descriptor: port.descriptor, registry }),
+    ]);
+    return { row, relations };
+}
+//# sourceMappingURL=use-entity-read.js.map

package/dist/react/hooks/use-nav-sections.d.ts

@@ -33,8 +33,12 @@ export declare const DEFAULT_NAV_SECTIONS_STORAGE_KEY = "jini-admin-nav-sections
 export type NavSectionState = Readonly<Record<string, boolean>>;
 export interface NavSections {
     /** `true` when the section should render its items. Any label with no stored preference is open. */
-    isOpen: (groupLabel: string) => boolean;
-    toggle: (groupLabel: string) => void;
+    isOpen: (requiredArgs: {
+        readonly groupLabel: string;
+    }) => boolean;
+    toggle: (requiredArgs: {
+        readonly groupLabel: string;
+    }) => void;
 }
 /**
  * @param storageKey `localStorage` key to persist under. Defaults to
@@ -46,5 +50,10 @@ export interface NavSections {
  * handful, fixed by the host's panel manifest, never user-variable.
  * @overallScore 100
  */
-export declare function useNavSections(storageKey?: string): NavSections;
+export declare function useNavSections({ storage, events }: {
+    readonly storage: Pick<Storage, 'getItem' | 'setItem'>;
+    readonly events: Pick<Window, 'addEventListener' | 'removeEventListener'>;
+}, { storageKey }?: {
+    readonly storageKey?: string;
+}): NavSections;
 //# sourceMappingURL=use-nav-sections.d.ts.map