@jini-ai/admin 0.3.9 → 0.4.0

package/dist/react/components/RowMenu/RowMenu.hooks.js

@@ -7,7 +7,7 @@ const VIEWPORT_MARGIN = 8;
  * @param itemCount Length of the caller's item list — the only piece of `RowMenuProps` this state
  *   needs, for `ArrowUp`-to-last-item and wraparound navigation.
  */
-export function useRowMenu(itemCount) {
+export function useRowMenu({ itemCount, window, document }) {
     const [open, setOpen] = useState(false);
     const [position, setPosition] = useState(null);
     const [activeIndex, setActiveIndex] = useState(0);
@@ -59,7 +59,7 @@ export function useRowMenu(itemCount) {
             window.removeEventListener('scroll', reposition, true);
             window.removeEventListener('resize', reposition);
         };
-    }, [open]);
+    }, [open, window, document]);
     // Click-outside closes. Scoped to the open window only, same lifecycle discipline as
     // `ConfirmButton`'s armed-only document listeners — a closed, idle `RowMenu` costs nothing beyond
     // its trigger button even with many mounted per table.
@@ -75,7 +75,7 @@ export function useRowMenu(itemCount) {
         document.addEventListener('mousedown', onDocMouseDown);
         return () => document.removeEventListener('mousedown', onDocMouseDown);
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [open]);
+    }, [open, window, document]);
     // Keeps real DOM focus on the active item (roving focus via `tabIndex={-1}` on every item except
     // the active one) rather than only tracking `activeIndex` in state — arrow-key navigation needs
     // to move the browser's actual focus for a screen reader to announce it.
@@ -135,7 +135,7 @@ export function useRowMenu(itemCount) {
     /** Closes (returning focus to the trigger, same as Escape) and then fires the selected item's own
      *  callback — takes the callback directly rather than a whole `RowMenuItem` so this hook stays
      *  free of any dependency on that component-level type. */
-    function selectItem(onSelect) {
+    function selectItem({ onSelect }) {
         close(true);
         onSelect();
     }

package/dist/react/components/RowMenu/RowMenu.js

@@ -15,15 +15,15 @@ import { useRowMenu } from './RowMenu.hooks.js';
  * @complexity O(1).
  */
 function rowMenuAgentProps(handle, options) {
-    return handle === undefined ? {} : agentHandle(handle, options);
+    return handle === undefined ? {} : agentHandle({ handle }, options);
 }
 export function RowMenu({ useRowMenu: useRowMenuState = useRowMenu, agentHandle: baseHandle, ...props }) {
-    const { open, position, triggerRef, menuRef, itemRefs, onTriggerClick, onTriggerKeyDown, onMenuKeyDown, selectItem, } = useRowMenuState(props.items.length);
+    const { open, position, triggerRef, menuRef, itemRefs, onTriggerClick, onTriggerKeyDown, onMenuKeyDown, selectItem, } = useRowMenuState({ itemCount: props.items.length, window, document });
     // One base handle per item, positionally aligned with `props.items` — undefined (rather than an
     // empty array) when the caller published no `agentHandle` at all, so the render below can tell
     // "opted out" apart from "an empty item list" without a second flag.
     const itemHandles = baseHandle
-        ? buildAgentListHandles(`${baseHandle}-item`, props.items.map((item) => item.key))
+        ? buildAgentListHandles({ prefix: `${baseHandle}-item`, ids: props.items.map((item) => item.key) })
         : undefined;
     return (_jsxs(_Fragment, { children: [_jsx("button", { ref: triggerRef, type: "button", className: "row-menu-trigger", "aria-label": props.triggerLabel, "aria-haspopup": "menu", "aria-expanded": open, onClick: onTriggerClick, onKeyDown: onTriggerKeyDown, ...rowMenuAgentProps(baseHandle, { role: 'button', label: props.triggerLabel }), children: _jsxs("svg", { viewBox: "0 0 18 18", fill: "currentColor", "aria-hidden": "true", children: [_jsx("circle", { cx: "9", cy: "4.5", r: "1.5" }), _jsx("circle", { cx: "9", cy: "9", r: "1.5" }), _jsx("circle", { cx: "9", cy: "13.5", r: "1.5" })] }) }), open
                 ? createPortal(_jsx("div", { ref: menuRef, role: "menu", "aria-label": props.triggerLabel, className: `row-menu-popup${position?.placement === 'above' ? ' row-menu-popup-above' : ''}`, style: {
@@ -36,11 +36,11 @@ export function RowMenu({ useRowMenu: useRowMenuState = useRowMenu, agentHandle:
                         visibility: position ? 'visible' : 'hidden',
                         transform: position?.placement === 'above' ? 'translateY(-100%)' : undefined,
                     }, onKeyDown: onMenuKeyDown, children: props.items.map((item, index) => {
-                        const toneClass = toneClassName(resolveTone(item));
+                        const toneClass = toneClassName({ tone: resolveTone({}, item) });
                         return (_jsx("button", { ref: (el) => {
                                 itemRefs.current[index] = el;
-                            }, type: "button", role: "menuitem", tabIndex: -1, className: ['row-menu-item', toneClass].filter(Boolean).join(' '), onClick: () => selectItem(item.onSelect), ...rowMenuAgentProps(itemHandles?.[index], { role: 'button', label: item.label }), children: item.label }, item.key));
-                    }) }), document.body)
+                            }, type: "button", role: "menuitem", tabIndex: -1, className: ['row-menu-item', toneClass].filter(Boolean).join(' '), onClick: () => selectItem({ onSelect: item.onSelect }), ...rowMenuAgentProps(itemHandles?.[index], { role: 'button', label: item.label }), children: item.label }, item.key));
+                    }) }), props.portalContainer ?? document.body)
                 : null] }));
 }
 //# sourceMappingURL=RowMenu.js.map

package/dist/react/components/Sidebar.d.ts

@@ -72,7 +72,7 @@ export interface SidebarMobileHeaderProps {
  */
 declare function SidebarMobileHeader(props: SidebarMobileHeaderProps): import("react").JSX.Element;
 export interface SidebarNavProps {
-    /** From `/core`'s `buildNav(resolvePanels(panels, context))`. */
+    /** From `/core`'s `buildNav({ panels: resolvePanels({ panels }, context) })`. */
     groups: readonly AdminNavGroup[];
     /** Label on a `soon` item's badge. @default "Soon" */
     soonLabel?: ReactNode;

package/dist/react/components/Sidebar.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { Fragment, createContext, useContext, useEffect, useMemo, useRef, useState, } from 'react';
+import { Fragment, createContext, createElement, useContext, useEffect, useMemo, useRef, useState, } from 'react';
 import { createPortal } from 'react-dom';
 import { DEFAULT_ADMIN_BASE, adminHref } from '../../core/routing/rules.js';
 import { useNavSections } from '../hooks/use-nav-sections.js';
@@ -18,8 +18,96 @@ export function useSidebar() {
     }
     return value;
 }
+/**
+ * Shape elements `AdminNavEntry.icon` markup may use. A host draws its own glyphs as raw inner
+ * SVG (see that field's doc comment in `core/manifest/types.ts`), so this can't be a fixed set of
+ * named icons — but it also means the string reaching {@link Icon} was written by whoever owns the
+ * nav entry, which soon enough will be a descriptor rather than code. `g` is included so multi-path
+ * icons can group and transform their pieces together.
+ */
+const ICON_ALLOWED_TAGS = new Set(['path', 'circle', 'rect', 'line', 'polygon', 'polyline', 'ellipse', 'g']);
+/**
+ * Presentation attributes let through on an icon shape, mapped from their SVG/XML spelling to the
+ * camelCase prop name React expects. Anything not listed here — `style`, `href`/`xlink:href`, every
+ * `on*` handler — is dropped by {@link sanitizeIconNode} rather than passed through, so there is no
+ * allowlist gap to keep in sync with a separate denylist.
+ */
+const ICON_ALLOWED_ATTRS = {
+    d: 'd',
+    cx: 'cx',
+    cy: 'cy',
+    r: 'r',
+    rx: 'rx',
+    ry: 'ry',
+    x: 'x',
+    y: 'y',
+    width: 'width',
+    height: 'height',
+    x1: 'x1',
+    y1: 'y1',
+    x2: 'x2',
+    y2: 'y2',
+    points: 'points',
+    transform: 'transform',
+    fill: 'fill',
+    'fill-rule': 'fillRule',
+    opacity: 'opacity',
+    'stroke-width': 'strokeWidth',
+    'stroke-linecap': 'strokeLinecap',
+    'stroke-linejoin': 'strokeLinejoin',
+    'clip-rule': 'clipRule',
+};
+/**
+ * Rebuilds one parsed element as a React element, keeping only {@link ICON_ALLOWED_TAGS} /
+ * {@link ICON_ALLOWED_ATTRS}. This is what stands in for `dangerouslySetInnerHTML`: the browser's
+ * own parser does the tokenizing (far less error-prone than a hand-rolled regex over SVG/XML), and
+ * this function decides what survives the trip into React's tree — a `<script>`, a `<foreignObject>`
+ * carrying arbitrary HTML, an `<image>`/`<use>` reference, or an `onload=` attribute all fail to
+ * match anything on either allowlist and are simply not there afterward, whatever they contained.
+ */
+function sanitizeIconNode(node, key) {
+    const tag = node.tagName.toLowerCase();
+    if (!ICON_ALLOWED_TAGS.has(tag))
+        return null;
+    // `key` goes straight into the props object — `createElement` pulls it out as the element's
+    // reserved key rather than forwarding it to the DOM, the same as writing `key={key}` in JSX.
+    const props = { key };
+    for (const attr of Array.from(node.attributes)) {
+        const propName = ICON_ALLOWED_ATTRS[attr.name.toLowerCase()];
+        if (propName)
+            props[propName] = attr.value;
+    }
+    const children = Array.from(node.children)
+        .map((child, i) => sanitizeIconNode(child, i))
+        .filter((child) => child !== null);
+    return createElement(tag, props, children.length ? children : undefined);
+}
+// Reused across parses rather than constructed per render — `DOMParser` instances are stateless
+// and this runs once per icon render, but there is no reason to pay allocation cost for it twice.
+let iconMarkupParser;
+/**
+ * Parses one `AdminNavEntry.icon` string into a sanitized element list. Wrapping in a throwaway
+ * `<svg>` document (never attached to the page — this is markup parsing, not rendering) lets the
+ * browser's own XML parser validate structure for free: malformed markup surfaces as a
+ * `parsererror` node, which is treated the same as empty input — the row loses its icon, not its
+ * label or link.
+ */
+function parseIconMarkup(markup) {
+    if (!markup)
+        return [];
+    iconMarkupParser ??= new DOMParser();
+    const doc = iconMarkupParser.parseFromString(`<svg xmlns="http://www.w3.org/2000/svg">${markup}</svg>`, 'image/svg+xml');
+    if (doc.getElementsByTagName('parsererror').length > 0)
+        return [];
+    return Array.from(doc.documentElement.children)
+        .map((child, i) => sanitizeIconNode(child, i))
+        .filter((child) => child !== null);
+}
 function Icon(props) {
-    return (_jsx("svg", { viewBox: "0 0 18 18", fill: "none", stroke: "currentColor", strokeWidth: 1.5, dangerouslySetInnerHTML: { __html: props.markup } }));
+    // Re-parsing on every keystroke of an unrelated state update would be wasted work for a string
+    // that, in practice, never changes after the nav manifest is built.
+    const children = useMemo(() => parseIconMarkup(props.markup), [props.markup]);
+    return (_jsx("svg", { viewBox: "0 0 18 18", fill: "none", stroke: "currentColor", strokeWidth: 1.5, children: children }));
 }
 /**
  * Rail-mode tooltip, portaled to `document.body`.
@@ -39,8 +127,16 @@ function RailTooltip(props) {
         return null;
     return createPortal(_jsx("div", { className: "cms-tooltip-portal", style: { top: props.target.top, left: props.target.left }, role: "presentation", children: props.target.label }), document.body);
 }
+// Read the browser storage property only inside the hooks' best-effort get/set calls: the
+// property getter itself can throw in restricted embeds, before a hook can catch the failure.
+const sidebarStorage = {
+    getItem: (key) => localStorage.getItem(key),
+    setItem: (key, value) => localStorage.setItem(key, value),
+};
 function SidebarRoot(props) {
-    const rail = useSidebarRail(props.railStorageKey, props.railDefaultCollapsed);
+    const rail = useSidebarRail({ storage: sidebarStorage, events: window }, {
+        storageKey: props.railStorageKey, defaultCollapsed: props.railDefaultCollapsed,
+    });
     const [tooltip, setTooltip] = useState(null);
     const open = props.open ?? false;
     const base = props.base ?? DEFAULT_ADMIN_BASE;
@@ -102,7 +198,7 @@ function SidebarMobileHeader(props) {
 }
 function SidebarNav(props) {
     const { activeId, base, collapsed, railTooltipProps } = useSidebar();
-    const sections = useNavSections();
+    const sections = useNavSections({ storage: sidebarStorage, events: window });
     return (_jsx(_Fragment, { children: props.groups.map((group, gi) => {
             /**
              * Rail mode force-expands every section, deliberately. Collapsed to a rail the group
@@ -112,15 +208,15 @@ function SidebarNav(props) {
              * returns intact when the rail expands — this only overrides what is rendered.
              */
             const collapsible = Boolean(group.label) && !collapsed && (props.collapsibleGroups ?? []).includes(group.label);
-            const open = !collapsible || sections.isOpen(group.label);
+            const open = !collapsible || sections.isOpen({ groupLabel: group.label });
             const panelId = `cms-section-${(group.label ?? `top-${gi}`).toLowerCase().replace(/[^a-z0-9]+/g, '-')}`;
             return (_jsxs("div", { className: "cms-section", children: [group.label && collapsible ? (
                     // A real `<button>`, not a click-handled `<div>`: keyboard focus, Enter/Space
                     // activation, and the button role all come free, and `aria-expanded` only carries its
                     // meaning on an element that is actually a control.
-                    _jsxs("button", { type: "button", className: `cms-group cms-group-toggle${open ? '' : ' is-closed'}`, "aria-expanded": open, "aria-controls": panelId, onClick: () => sections.toggle(group.label), children: [_jsx("span", { children: group.label }), _jsx("svg", { className: "cms-group-chevron", viewBox: "0 0 18 18", fill: "none", "aria-hidden": "true", children: _jsx("path", { d: "M5 7l4 4 4-4", stroke: "currentColor", strokeWidth: "1.75", strokeLinecap: "round", strokeLinejoin: "round" }) })] })) : group.label ? (_jsx("div", { className: "cms-group", children: group.label })) : null, _jsx("div", { className: "cms-section-items", id: panelId, hidden: !open, children: group.items.map((item) => {
+                    _jsxs("button", { type: "button", className: `cms-group cms-group-toggle${open ? '' : ' is-closed'}`, "aria-expanded": open, "aria-controls": panelId, onClick: () => sections.toggle({ groupLabel: group.label }), children: [_jsx("span", { children: group.label }), _jsx("svg", { className: "cms-group-chevron", viewBox: "0 0 18 18", fill: "none", "aria-hidden": "true", children: _jsx("path", { d: "M5 7l4 4 4-4", stroke: "currentColor", strokeWidth: "1.75", strokeLinecap: "round", strokeLinejoin: "round" }) })] })) : group.label ? (_jsx("div", { className: "cms-group", children: group.label })) : null, _jsx("div", { className: "cms-section-items", id: panelId, hidden: !open, children: group.items.map((item) => {
                             const active = item.id === activeId;
-                            const href = adminHref(item.href, base);
+                            const href = adminHref({ routePath: item.href }, { base });
                             if (props.renderItem) {
                                 return _jsx(Fragment, { children: props.renderItem(item, { active, href, collapsed }) }, item.id);
                             }

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

@@ -0,0 +1,10 @@
+import type { AdminEntityField, AdminEntityRowData } from '../../core/ports/entities.js';
+import { type EntityTranslate } from './types.js';
+import type { RelationIndex } from './rules.js';
+export declare function EntityCell({ field, row, relations, translate }: {
+    readonly field: AdminEntityField;
+    readonly row: AdminEntityRowData;
+    readonly relations: RelationIndex;
+    readonly translate: EntityTranslate;
+}): import("react").JSX.Element;
+//# sourceMappingURL=EntityCell.d.ts.map

package/dist/react/entities/EntityCell.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { entityText } from './types.js';
+export function EntityCell({ field, row, relations, translate }) {
+    const value = row[field.name];
+    if (value === undefined || value === null)
+        return _jsx("span", { children: translate({ key: 'Empty' }) });
+    if (field.kind === 'relation') {
+        const id = String(value);
+        const title = relations[field.target]?.titles?.[id];
+        return title !== undefined ? _jsx("span", { children: title }) : _jsxs("span", { title: entityText({ translate, key: 'Unresolved {target}: {id}', values: { target: field.target, id } }), children: [id, " \u26A0"] });
+    }
+    if (field.kind === 'json')
+        return _jsx("code", { children: JSON.stringify(value) });
+    if (field.kind === 'boolean')
+        return _jsx("span", { children: translate({ key: value === true ? 'Yes' : 'No' }) });
+    return _jsx("span", { children: String(value) });
+}
+//# sourceMappingURL=EntityCell.js.map

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

@@ -0,0 +1,3 @@
+import type { EntityDetailProps } from './types.js';
+export declare function EntityDetail({ entityName, id, registry, translate, routes }: EntityDetailProps): import("react").JSX.Element;
+//# sourceMappingURL=EntityDetail.d.ts.map

package/dist/react/entities/EntityDetail.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useMemo } from 'react';
+import { EntityCell } from './EntityCell.js';
+import { loadEntityRow, useEntityRead } from './use-entity-read.js';
+import { readTitle } from './rules.js';
+export function EntityDetail({ entityName, id, registry, translate, routes }) {
+    const port = useMemo(() => registry.getEntity({ name: entityName }), [registry, entityName]);
+    const load = useCallback(() => loadEntityRow({ registry, entityName, id }), [registry, entityName, id, port]);
+    const result = useEntityRead({ load, scope: port });
+    if (port === null)
+        return _jsx("p", { role: "alert", children: translate({ key: 'Unknown entity' }) });
+    if (result.error)
+        return _jsx("p", { role: "alert", children: translate({ key: 'Unable to load row' }) });
+    if (result.loading || !result.data)
+        return _jsx("p", { role: "status", children: translate({ key: 'Loading' }) });
+    const { row, relations } = result.data;
+    if (row === null)
+        return _jsx("p", { role: "status", children: translate({ key: 'Row not found' }) });
+    return _jsxs("div", { className: "page", children: [_jsx("a", { href: routes.href({ entity: entityName }), children: translate({ key: port.descriptor.labelPlural }) }), _jsx("h1", { children: readTitle({ row, titleField: port.descriptor.titleField }) ?? row.id }), _jsx("dl", { children: port.descriptor.fields.map((field) => _jsxs("div", { children: [_jsx("dt", { children: translate({ key: field.label ?? field.name }) }), _jsx("dd", { children: _jsx(EntityCell, { field: field, row: row, relations: relations, translate: translate }) })] }, field.name)) }), _jsx("a", { href: routes.href({ entity: entityName, id, view: 'edit' }), children: translate({ key: 'Edit' }) })] });
+}
+//# sourceMappingURL=EntityDetail.js.map

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

@@ -0,0 +1,13 @@
+import type { EntityEditProps } from './types.js';
+/** Host entity editing uses the existing registry/ports and core draft validation.
+ * Required booleans default false, optional booleans remain unset, and invalid JSON blocks save
+ * while preserving textarea contents. Creates omit undefined; updates retain explicit undefined
+ * to clear fields, so the host transport must preserve that intent. Save/remove operations serialize
+ * within the mounted editor; stale reads and settlement after unmount cannot populate or navigate
+ * another screen. Relation targets load once each, bounded to 100 with truncation and raw-id fallback.
+ * Reads belong to each mount rather than a host query singleton. Navigation remount reloads data;
+ * live refresh and dirty-navigation prompts remain host responsibilities. Registry changes must
+ * replace the registry object; memoized per-entity ports can then refresh diagnostic wrappers.
+ */
+export declare function EntityEdit(props: EntityEditProps): import("react").JSX.Element;
+//# sourceMappingURL=EntityEdit.d.ts.map

package/dist/react/entities/EntityEdit.js

@@ -0,0 +1,45 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId, useMemo } from 'react';
+import { EntityField } from './EntityField.js';
+import { useEntityEdit } from './use-entity-edit.js';
+import { entityText } from './types.js';
+import { RELATION_OPTION_LIMIT } from './rules.js';
+function EntityEditor(props) {
+    const { port, translate, routes, entityName, id } = props;
+    const formId = useId();
+    const edit = useEntityEdit(props);
+    if (edit.read.error)
+        return _jsx("p", { role: "alert", children: translate({ key: 'Unable to load row' }) });
+    if (edit.read.loading || !edit.read.data)
+        return _jsx("p", { role: "status", children: translate({ key: 'Loading' }) });
+    if (id !== null && edit.read.data.row === null)
+        return _jsx("p", { role: "status", children: translate({ key: 'Row not found' }) });
+    if (!edit.form)
+        return _jsx("p", { role: "status", children: translate({ key: 'Loading' }) });
+    const busy = edit.pending !== null;
+    const truncated = Object.entries(edit.read.data.relations).filter(([, target]) => target.truncated).map(([name]) => name);
+    return _jsxs("form", { className: "page", onSubmit: (e) => { e.preventDefault(); void edit.save(); }, children: [_jsx("a", { href: routes.href({ entity: entityName }), children: translate({ key: port.descriptor.labelPlural }) }), _jsx("h1", { children: entityText({ translate, key: id === null ? 'New {entity}' : 'Edit {entity}', values: { entity: translate({ key: port.descriptor.labelSingular }) } }) }), edit.failed ? _jsx("p", { role: "alert", children: translate({ key: 'Operation failed' }) }) : null, port.descriptor.fields.map((field, index) => {
+                const inputId = `${formId}-${index}`;
+                const missing = edit.missing.includes(field.name);
+                const invalid = edit.invalid.some((problem) => problem.field === field.name);
+                const jsonError = edit.form?.jsonErrors[field.name] === true;
+                return _jsxs("div", { children: [_jsxs("label", { htmlFor: inputId, children: [translate({ key: field.label ?? field.name }), field.required ? ' *' : '', field.kind === 'datetime' ? ` (${translate({ key: 'UTC' })})` : ''] }), _jsx(EntityField, { inputId: inputId, field: field, value: edit.form?.draft[field.name], text: edit.form?.jsonText[field.name] ?? '', relations: edit.read.data.relations, translate: translate, disabled: busy, invalid: missing || invalid || jsonError, onChange: ({ value }) => edit.setField({ name: field.name, value }), onTextChange: ({ text }) => edit.setJsonText({ name: field.name, text }) }), missing ? _jsx("p", { children: translate({ key: 'Required' }) }) : null, invalid ? _jsx("p", { children: translate({ key: 'Invalid value' }) }) : null, jsonError ? _jsx("p", { role: "alert", children: translate({ key: 'Invalid JSON' }) }) : null] }, field.name);
+            }), truncated.length > 0 ? _jsx("p", { children: entityText({ translate, key: 'Related names limited to {limit} rows: {targets}', values: { limit: RELATION_OPTION_LIMIT, targets: truncated.join(', ') } }) }) : null, _jsx("button", { type: "submit", disabled: !edit.canSave, children: translate({ key: edit.pending === 'save' ? 'Saving' : 'Save' }) }), id !== null && port.remove ? _jsx("button", { type: "button", disabled: busy, onClick: () => { void edit.remove(); }, children: translate({ key: edit.pending === 'remove' ? 'Deleting' : 'Delete' }) }) : null] });
+}
+/** Host entity editing uses the existing registry/ports and core draft validation.
+ * Required booleans default false, optional booleans remain unset, and invalid JSON blocks save
+ * while preserving textarea contents. Creates omit undefined; updates retain explicit undefined
+ * to clear fields, so the host transport must preserve that intent. Save/remove operations serialize
+ * within the mounted editor; stale reads and settlement after unmount cannot populate or navigate
+ * another screen. Relation targets load once each, bounded to 100 with truncation and raw-id fallback.
+ * Reads belong to each mount rather than a host query singleton. Navigation remount reloads data;
+ * live refresh and dirty-navigation prompts remain host responsibilities. Registry changes must
+ * replace the registry object; memoized per-entity ports can then refresh diagnostic wrappers.
+ */
+export function EntityEdit(props) {
+    const port = useMemo(() => props.registry.getEntity({ name: props.entityName }), [props.registry, props.entityName]);
+    if (port === null)
+        return _jsx("p", { role: "alert", children: props.translate({ key: 'Unknown entity' }) });
+    return _jsx(EntityEditor, { ...props, port: port }, JSON.stringify([props.entityName, props.id]));
+}
+//# sourceMappingURL=EntityEdit.js.map

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

@@ -0,0 +1,20 @@
+import type { AdminEntityField } from '../../core/ports/entities.js';
+import type { EntityTranslate } from './types.js';
+import { type RelationIndex } from './rules.js';
+export declare function EntityField(props: {
+    readonly inputId: string;
+    readonly field: AdminEntityField;
+    readonly value: unknown;
+    readonly text: string;
+    readonly relations: RelationIndex;
+    readonly translate: EntityTranslate;
+    readonly disabled: boolean;
+    readonly invalid: boolean;
+    readonly onChange: (args: {
+        readonly value: unknown;
+    }) => void;
+    readonly onTextChange: (args: {
+        readonly text: string;
+    }) => void;
+}): import("react").JSX.Element;
+//# sourceMappingURL=EntityField.d.ts.map

package/dist/react/entities/EntityField.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Select } from '@jini-ai/ui/admin-widgets';
+import { fromDatetimeLocalValue, toDatetimeLocalValue } from './rules.js';
+export function EntityField(props) {
+    const { inputId, field, value, translate, disabled, invalid, onChange } = props;
+    const common = { id: inputId, disabled, 'aria-invalid': invalid };
+    switch (field.kind) {
+        case 'json': return _jsx("textarea", { ...common, value: props.text, onChange: (e) => props.onTextChange({ text: e.target.value }) });
+        case 'relation': {
+            const options = props.relations[field.target]?.options ?? [];
+            const selectedId = typeof value === 'string' ? value : '';
+            const missing = selectedId !== '' && !options.some((option) => option.id === selectedId);
+            return _jsx(Select, { id: inputId, disabled: disabled, value: selectedId, translate: (key) => translate({ key }), "aria-label": translate({ key: field.label ?? field.name }), options: [
+                    { value: '', label: translate({ key: 'No value' }) },
+                    ...(missing ? [{ value: selectedId, label: `${selectedId} (${translate({ key: 'Unresolved' })})` }] : []),
+                    ...options.map((option) => ({ value: option.id, label: option.title })),
+                ], onChange: (selected) => onChange({ value: selected === '' ? undefined : selected }) });
+        }
+        case 'boolean':
+            if (field.required)
+                return _jsx("input", { ...common, type: "checkbox", checked: value === true, onChange: (e) => onChange({ value: e.target.checked }) });
+            return _jsx(Select, { id: inputId, disabled: disabled, value: value === undefined ? '' : value === true ? 'true' : 'false', translate: (key) => translate({ key }), "aria-label": translate({ key: field.label ?? field.name }), options: [
+                    { value: '', label: translate({ key: 'No value' }) }, { value: 'true', label: translate({ key: 'Yes' }) }, { value: 'false', label: translate({ key: 'No' }) },
+                ], onChange: (selected) => onChange({ value: selected === '' ? undefined : selected === 'true' }) });
+        case 'datetime': return _jsx("input", { ...common, type: "datetime-local", step: "0.001", value: toDatetimeLocalValue({ value }), onChange: (e) => onChange({ value: fromDatetimeLocalValue({ raw: e.target.value }) }) });
+        case 'integer':
+        case 'real': return _jsx("input", { ...common, type: "number", step: field.kind === 'integer' ? '1' : 'any', value: typeof value === 'number' ? value : '', onChange: (e) => onChange({ value: e.target.value === '' ? undefined : Number(e.target.value) }) });
+        case 'text': return _jsx("input", { ...common, value: typeof value === 'string' ? value : '', onChange: (e) => onChange({ value: e.target.value === '' ? undefined : e.target.value }) });
+    }
+}
+//# sourceMappingURL=EntityField.js.map

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

@@ -0,0 +1,3 @@
+import type { EntityScreenDependencies } from './types.js';
+export declare function EntityIndex({ registry, routes, translate }: EntityScreenDependencies): import("react").JSX.Element;
+//# sourceMappingURL=EntityIndex.d.ts.map

package/dist/react/entities/EntityIndex.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { DataTable } from '../components/DataTable.js';
+export function EntityIndex({ registry, routes, translate }) {
+    return _jsxs("div", { className: "page", children: [_jsx("h1", { children: translate({ key: 'Data' }) }), _jsx(DataTable, { rows: [...registry.listEntities({})], rowKey: ({ descriptor }) => descriptor.name, empty: _jsx("p", { children: translate({ key: 'No entities registered' }) }), columns: [
+                    { key: 'name', header: translate({ key: 'Entity' }), cell: ({ descriptor }) => _jsx("a", { href: routes.href({ entity: descriptor.name }), children: translate({ key: descriptor.labelPlural }) }) },
+                    { key: 'key', header: translate({ key: 'Name' }), cell: ({ descriptor }) => _jsx("code", { children: descriptor.name }) },
+                    { key: 'fields', header: translate({ key: 'Fields' }), cell: ({ descriptor }) => descriptor.fields.length },
+                ] })] });
+}
+//# sourceMappingURL=EntityIndex.js.map

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

@@ -0,0 +1,7 @@
+import { type EntityListProps } from './types.js';
+/** Cursor history records actual returned page lengths; never sort a server-paginated page locally.
+ * Host translation, registry and navigation are injected, and this list uses the existing DataTable.
+ * Relation choices are bounded to 100, expose truncation and retain raw IDs for unresolved labels.
+ */
+export declare function EntityList(props: EntityListProps): import("react").JSX.Element;
+//# sourceMappingURL=EntityList.d.ts.map

package/dist/react/entities/EntityList.js

@@ -0,0 +1,52 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useMemo, useState } from 'react';
+import { DataTable } from '../components/DataTable.js';
+import { EntityCell } from './EntityCell.js';
+import { entityText } from './types.js';
+import { loadRelationIndex, resolveEntityPageSize, RELATION_OPTION_LIMIT } from './rules.js';
+import { useEntityRead } from './use-entity-read.js';
+/** Cursor history records actual returned page lengths; never sort a server-paginated page locally.
+ * Host translation, registry and navigation are injected, and this list uses the existing DataTable.
+ * Relation choices are bounded to 100, expose truncation and retain raw IDs for unresolved labels.
+ */
+export function EntityList(props) {
+    const { entityName, registry, translate, routes } = props;
+    const port = useMemo(() => registry.getEntity({ name: entityName }), [registry, entityName]);
+    const limit = resolveEntityPageSize({ raw: props.limitParam });
+    const token = JSON.stringify([entityName, limit]);
+    const [walk, setWalk] = useState({ token, port, entries: [{ cursor: null, offset: 0 }] });
+    if (walk.token !== token || walk.port !== port)
+        setWalk({ token, port, entries: [{ cursor: null, offset: 0 }] });
+    const entries = walk.token === token && walk.port === port ? walk.entries : [{ cursor: null, offset: 0 }];
+    const position = entries[entries.length - 1];
+    const load = useCallback(async () => {
+        if (port === null)
+            return null;
+        const [page, relations] = await Promise.all([
+            port.list(position.cursor === null ? { limit } : { limit, cursor: position.cursor }),
+            loadRelationIndex({ descriptor: port.descriptor, registry }),
+        ]);
+        return { page, relations };
+    }, [port, registry, limit, position.cursor]);
+    const result = useEntityRead({ load, scope: port });
+    if (port === null)
+        return _jsx("p", { role: "alert", children: translate({ key: 'Unknown entity' }) });
+    if (result.error)
+        return _jsx("p", { role: "alert", children: translate({ key: 'Unable to load rows' }) });
+    if (result.loading || !result.data)
+        return _jsx("p", { role: "status", children: translate({ key: 'Loading' }) });
+    const { page, relations } = result.data;
+    const descriptor = port.descriptor;
+    const truncated = Object.entries(relations).filter(([, options]) => options.truncated).map(([name]) => name);
+    return _jsxs("div", { className: "page", children: [_jsx("a", { href: routes.href({}), children: translate({ key: 'Data' }) }), _jsx("h1", { children: translate({ key: descriptor.labelPlural }) }), _jsx("a", { href: routes.href({ entity: entityName, view: 'create' }), children: entityText({ translate, key: 'New {entity}', values: { entity: translate({ key: descriptor.labelSingular }) } }) }), _jsx(DataTable, { rows: [...page.items], rowKey: (row) => row.id, empty: _jsx("p", { children: translate({ key: 'No rows' }) }), columns: descriptor.fields.map((field) => ({
+                    key: field.name, header: translate({ key: field.label ?? field.name }),
+                    // Sorting a server-cut page would misrepresent collection order.
+                    cell: (row) => field.name === descriptor.titleField
+                        ? _jsx("a", { href: routes.href({ entity: entityName, id: row.id }), children: _jsx(EntityCell, { field: field, row: row, relations: relations, translate: translate }) })
+                        : _jsx(EntityCell, { field: field, row: row, relations: relations, translate: translate }),
+                })) }), _jsx("p", { children: page.items.length === 0 ? translate({ key: 'No rows' }) : entityText({ translate, key: 'Showing {from}–{to}', values: { from: position.offset + 1, to: position.offset + page.items.length } }) }), _jsx("button", { type: "button", disabled: entries.length === 1, onClick: () => setWalk((current) => ({ ...current, entries: current.entries.slice(0, -1) })), children: translate({ key: 'Previous' }) }), _jsx("button", { type: "button", disabled: page.nextCursor === null, onClick: () => {
+                    if (page.nextCursor !== null)
+                        setWalk((current) => ({ ...current, entries: [...current.entries, { cursor: page.nextCursor, offset: position.offset + page.items.length }] }));
+                }, children: translate({ key: 'Next' }) }), truncated.length > 0 ? _jsx("p", { children: entityText({ translate, key: 'Related names limited to {limit} rows: {targets}', values: { limit: RELATION_OPTION_LIMIT, targets: truncated.join(', ') } }) }) : null] });
+}
+//# sourceMappingURL=EntityList.js.map

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

@@ -0,0 +1,26 @@
+import type { AdminNavEntry } from '../../core/manifest/types.js';
+import type { AdminShellPanel } from '../shell/types.js';
+import type { EntityRegistryPort, EntityRoutesPort, EntityTranslate } from './types.js';
+export interface EntityRouteDependencies {
+    readonly adminBase: string;
+    readonly panelId: string;
+    readonly navigate: (args: {
+        readonly routePath: string;
+    }) => void;
+}
+export declare function createEntityRoutes({ adminBase, panelId, navigate }: EntityRouteDependencies): EntityRoutesPort;
+/** Adds an existing shell contribution; no router, registry, or shell is installed by this slice.
+ * Host translate/registry/adminBase/panelId/navigation dependencies are explicit and agent access
+ * is opt-in. List/create/detail/edit routes encode names and IDs, including dot-segment protection;
+ * an ID equal to new is still a saved row, never the creation sentinel. Hosts adopting these routes
+ * own legacy bookmark migration. Select translation is adapted to its existing scalar callback ABI. */
+export declare function createEntityPanel(args: EntityRouteDependencies & {
+    readonly registry: EntityRegistryPort;
+    readonly translate: EntityTranslate;
+}, options?: {
+    readonly nav?: AdminNavEntry;
+    readonly agentReachable?: boolean;
+    readonly requires?: readonly string[];
+    readonly permissions?: readonly string[];
+}): AdminShellPanel;
+//# sourceMappingURL=contribution.d.ts.map

package/dist/react/entities/contribution.js

@@ -0,0 +1,78 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { EntityIndex } from './EntityIndex.js';
+import { EntityList } from './EntityList.js';
+import { EntityDetail } from './EntityDetail.js';
+import { EntityEdit } from './EntityEdit.js';
+function encodeSegment({ value }) {
+    if (value === '')
+        throw new Error('Entity route segments must be non-empty');
+    const encoded = encodeURIComponent(value).replace(/~/g, '%7E');
+    // Browsers normalize even percent-encoded dot segments. A marker prevents that normalization.
+    return value === '.' || value === '..' ? `~${encoded}` : encoded;
+}
+function decodeSegment({ value }) {
+    return value === '~.' || value === '~..' ? value.slice(1) : decodeURIComponent(value);
+}
+export function createEntityRoutes({ adminBase, panelId, navigate }) {
+    if (!/^[a-zA-Z0-9_-]+$/.test(panelId))
+        throw new Error('Entity panelId must be one URL segment');
+    if (!adminBase.startsWith('/') || adminBase.startsWith('//') || /[?#]/.test(adminBase))
+        throw new Error('Entity adminBase must be an absolute pathname');
+    const base = adminBase.replace(/\/+$/, '');
+    function routePath({ entity, id, view }) {
+        const root = `/${panelId}`;
+        if (entity === undefined)
+            return root;
+        const list = `${root}/${encodeSegment({ value: entity })}`;
+        if (view === 'create')
+            return `${list}/new`;
+        if (id === undefined)
+            return list;
+        return `${list}/row/${encodeSegment({ value: id })}${view === 'edit' ? '/edit' : ''}`;
+    }
+    return {
+        href: (args) => `${base}${routePath(args)}`,
+        navigate: (args) => navigate({ routePath: routePath(args) }),
+    };
+}
+/** Adds an existing shell contribution; no router, registry, or shell is installed by this slice.
+ * Host translate/registry/adminBase/panelId/navigation dependencies are explicit and agent access
+ * is opt-in. List/create/detail/edit routes encode names and IDs, including dot-segment protection;
+ * an ID equal to new is still a saved row, never the creation sentinel. Hosts adopting these routes
+ * own legacy bookmark migration. Select translation is adapted to its existing scalar callback ABI. */
+export function createEntityPanel(args, options = {}) {
+    const routes = createEntityRoutes(args);
+    const dependencies = { registry: args.registry, translate: args.translate, routes };
+    return {
+        id: args.panelId,
+        nav: options.nav ?? { label: args.translate({ key: 'Data' }) },
+        agentReachable: options.agentReachable ?? false,
+        ...(options.requires === undefined ? {} : { requires: options.requires }),
+        ...(options.permissions === undefined ? {} : { permissions: options.permissions }),
+        routes: [
+            { pattern: '/:entity', view: 'list' },
+            { pattern: '/:entity/new', view: 'create' },
+            { pattern: '/:entity/row/:id', view: 'detail' },
+            { pattern: '/:entity/row/:id/edit', view: 'edit' },
+        ],
+        render: ({ route }) => {
+            if (route.view === null)
+                return _jsx(EntityIndex, { ...dependencies });
+            let entityName;
+            let id;
+            try {
+                entityName = decodeSegment({ value: route.params.entity ?? '' });
+                id = decodeSegment({ value: route.params.id ?? '' });
+            }
+            catch {
+                return _jsx("p", { role: "alert", children: args.translate({ key: 'Invalid route' }) });
+            }
+            if (route.view === 'list')
+                return _jsx(EntityList, { ...dependencies, entityName: entityName, limitParam: route.query.get('limit') });
+            if (route.view === 'detail')
+                return _jsx(EntityDetail, { ...dependencies, entityName: entityName, id: id });
+            return _jsx(EntityEdit, { ...dependencies, entityName: entityName, id: route.view === 'create' ? null : id });
+        },
+    };
+}
+//# sourceMappingURL=contribution.js.map

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

@@ -0,0 +1,10 @@
+export { EntityIndex } from './EntityIndex.js';
+export { EntityList } from './EntityList.js';
+export { EntityDetail } from './EntityDetail.js';
+export { EntityEdit } from './EntityEdit.js';
+export { createEntityPanel, createEntityRoutes } from './contribution.js';
+export type { EntityRouteDependencies } from './contribution.js';
+export type { EntityRegistryPort, EntityTranslate, EntityRoutesPort, EntityRouteTarget, EntityScreenDependencies, EntityListProps, EntityDetailProps, EntityEditProps, } from './types.js';
+export { RELATION_OPTION_LIMIT, resolveEntityPageSize, relationFieldsOf, loadRelationIndex, readTitle, emptyDraft, draftForRow, missingRequiredFields, invalidDraftFields, toDatetimeLocalValue, fromDatetimeLocalValue, } from './rules.js';
+export type { RelationOptions, RelationIndex, DraftFieldProblem } from './rules.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/react/entities/index.js

@@ -0,0 +1,7 @@
+export { EntityIndex } from './EntityIndex.js';
+export { EntityList } from './EntityList.js';
+export { EntityDetail } from './EntityDetail.js';
+export { EntityEdit } from './EntityEdit.js';
+export { createEntityPanel, createEntityRoutes } from './contribution.js';
+export { RELATION_OPTION_LIMIT, resolveEntityPageSize, relationFieldsOf, loadRelationIndex, readTitle, emptyDraft, draftForRow, missingRequiredFields, invalidDraftFields, toDatetimeLocalValue, fromDatetimeLocalValue, } from './rules.js';
+//# sourceMappingURL=index.js.map