@object-ui/react 17.6.0 → 17.7.0

package/dist/hooks/useClientNotifications.js

@@ -1,162 +0,0 @@
-/**
- * ObjectUI
- * Copyright (c) 2024-present ObjectStack Inc.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-/**
- * @object-ui/react - useClientNotifications
- *
- * Bridge hook between the @objectstack/client notifications API
- * and the local NotificationContext state. Fetches server-side
- * notifications and surfaces them through the existing provider.
- *
- * ADR-0030 (Notification Convergence): the `client.notifications.*` helpers
- * are the stable transport contract — the server routes them to the L5
- * `sys_inbox_message` materialization and the `sys_notification_receipt`
- * read-state spine (the re-modeled `sys_notification` L2 event carries no
- * recipient/read columns). This hook only needs to call the SDK with its
- * current signatures: `list(options)`, `markRead(ids[])`, `markAllRead()`.
- *
- * The former registerDevice/getPreferences/updatePreferences delegates were
- * removed (objectstack#3612): the SDK deleted those methods because the
- * /notifications/devices and /notifications/preferences server routes were
- * never built — every call was a guaranteed error. They return when the
- * server side exists.
- */
-import { useCallback, useContext, useEffect, useRef, useState } from 'react';
-import { SchemaRendererContext } from '../context/SchemaRendererContext.js';
-import { useNotifications } from '../context/NotificationContext.js';
-/* ------------------------------------------------------------------ */
-/*  Helpers                                                           */
-/* ------------------------------------------------------------------ */
-/** Normalise severity coming from the server into a valid local level. */
-function toSeverity(value) {
-    const valid = ['info', 'success', 'warning', 'error'];
-    if (typeof value === 'string' && valid.includes(value)) {
-        return value;
-    }
-    return 'info';
-}
-/**
- * Resolve the ObjectStack client from explicit option or SchemaRendererContext.
- *
- * The dataSource stored in context is typically an ObjectStackAdapter which
- * exposes `getClient()`.  When the caller passes a client directly we use
- * that instead.
- */
-function useResolvedClient(explicit) {
-    const rendererCtx = useContext(SchemaRendererContext);
-    if (explicit)
-        return explicit;
-    const dataSource = rendererCtx?.dataSource;
-    if (dataSource && typeof dataSource.getClient === 'function') {
-        return dataSource.getClient();
-    }
-    return null;
-}
-/* ------------------------------------------------------------------ */
-/*  Hook                                                              */
-/* ------------------------------------------------------------------ */
-/**
- * Bridge between the `@objectstack/client` notifications API and the
- * local {@link NotificationContext}.
- *
- * The hook resolves the ObjectStack client either from the explicit
- * `client` option or from the `SchemaRendererContext` dataSource, then
- * delegates to `client.notifications.*` methods.  Fetched notifications
- * are fed into the local provider via `useNotifications().notify()`.
- *
- * @example
- * ```tsx
- * function NotificationBell() {
- *   const { fetchNotifications, loading } = useClientNotifications({
- *     autoFetch: true,
- *     pollInterval: 30_000,
- *   });
- *
- *   return <Button onClick={fetchNotifications} disabled={loading}>🔔</Button>;
- * }
- * ```
- */
-export function useClientNotifications(options = {}) {
-    const { client: explicitClient, autoFetch = false, pollInterval = 0 } = options;
-    const client = useResolvedClient(explicitClient);
-    const { notify, markAsRead: localMarkAsRead } = useNotifications();
-    const [loading, setLoading] = useState(false);
-    const [error, setError] = useState(null);
-    // Track IDs that have already been pushed into the local context so we
-    // don't add duplicates on subsequent fetches / polls.
-    const seenIdsRef = useRef(new Set());
-    /* ---- fetchNotifications ---- */
-    const fetchNotifications = useCallback(async () => {
-        if (!client?.notifications)
-            return;
-        setLoading(true);
-        setError(null);
-        try {
-            const result = await client.notifications.list({});
-            const items = Array.isArray(result) ? result : result?.data ?? result?.items ?? [];
-            for (const item of items) {
-                const id = String(item.id ?? '');
-                if (!id || seenIdsRef.current.has(id))
-                    continue;
-                seenIdsRef.current.add(id);
-                notify({
-                    title: item.title ?? 'Notification',
-                    message: item.message ?? item.body,
-                    severity: toSeverity(item.severity ?? item.level),
-                    duration: 0, // server-driven notifications are persistent
-                });
-            }
-        }
-        catch (err) {
-            setError(err instanceof Error ? err : new Error('Failed to fetch notifications'));
-        }
-        finally {
-            setLoading(false);
-        }
-    }, [client, notify]);
-    /* ---- markAsRead (server + local) ---- */
-    const markAsRead = useCallback(async (id) => {
-        // Optimistically mark locally first
-        localMarkAsRead(id);
-        if (!client?.notifications)
-            return;
-        setError(null);
-        try {
-            // ADR-0030 / @objectstack/client v7+: the SDK exposes `markRead(ids[])`
-            // (batch) — there is no single-id `markAsRead`. Server-side this writes
-            // the `read` state to the `sys_notification_receipt` spine. We keep the
-            // friendly single-id hook API and adapt to the batch call.
-            await client.notifications.markRead([id]);
-        }
-        catch (err) {
-            const wrapped = err instanceof Error ? err : new Error('Failed to mark as read');
-            setError(wrapped);
-            throw wrapped;
-        }
-    }, [client, localMarkAsRead]);
-    /* ---- auto-fetch on mount ---- */
-    useEffect(() => {
-        if (autoFetch && client?.notifications) {
-            fetchNotifications();
-        }
-    }, [autoFetch, client, fetchNotifications]);
-    /* ---- polling ---- */
-    useEffect(() => {
-        if (!pollInterval || pollInterval <= 0 || !client?.notifications)
-            return;
-        const id = setInterval(() => {
-            fetchNotifications();
-        }, pollInterval);
-        return () => clearInterval(id);
-    }, [pollInterval, client, fetchNotifications]);
-    return {
-        fetchNotifications,
-        markAsRead,
-        loading,
-        error,
-    };
-}

package/dist/spec-bridge/SpecBridge.d.ts

@@ -1,28 +0,0 @@
-/**
- * ObjectUI
- * Copyright (c) 2024-present ObjectStack Inc.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-import type { BaseSchema } from '@object-ui/types';
-import type { BridgeContext, BridgeFn } from './types.js';
-export declare class SpecBridge {
-    private bridges;
-    private context;
-    constructor(context?: BridgeContext);
-    register(specType: string, bridge: BridgeFn): void;
-    /**
-     * Transform a spec schema into a schema node tree.
-     *
-     * Returns `BaseSchema` rather than `SchemaNode` — see {@link BridgeFn} for
-     * the ruling (objectui#4580 Q4-B) and the measurement behind it. A registered
-     * bridge always produces an object; the union only made callers narrow.
-     */
-    transform(specType: string, spec: any): BaseSchema;
-    /** Transform a ListView spec */
-    transformListView(spec: any): BaseSchema;
-    /** Transform a FormView spec */
-    transformFormView(spec: any): BaseSchema;
-    updateContext(ctx: Partial<BridgeContext>): void;
-}

package/dist/spec-bridge/SpecBridge.js

@@ -1,56 +0,0 @@
-/**
- * ObjectUI
- * Copyright (c) 2024-present ObjectStack Inc.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-import { bridgeListView } from './bridges/list-view.js';
-import { bridgeFormView } from './bridges/form-view.js';
-export class SpecBridge {
-    constructor(context = {}) {
-        Object.defineProperty(this, "bridges", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: new Map()
-        });
-        Object.defineProperty(this, "context", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        this.context = context;
-        this.register('list', bridgeListView);
-        this.register('form', bridgeFormView);
-    }
-    register(specType, bridge) {
-        this.bridges.set(specType, bridge);
-    }
-    /**
-     * Transform a spec schema into a schema node tree.
-     *
-     * Returns `BaseSchema` rather than `SchemaNode` — see {@link BridgeFn} for
-     * the ruling (objectui#4580 Q4-B) and the measurement behind it. A registered
-     * bridge always produces an object; the union only made callers narrow.
-     */
-    transform(specType, spec) {
-        const bridge = this.bridges.get(specType);
-        if (!bridge) {
-            throw new Error(`No bridge registered for spec type: ${specType}`);
-        }
-        return bridge(spec, this.context);
-    }
-    /** Transform a ListView spec */
-    transformListView(spec) {
-        return this.transform('list', spec);
-    }
-    /** Transform a FormView spec */
-    transformFormView(spec) {
-        return this.transform('form', spec);
-    }
-    updateContext(ctx) {
-        this.context = { ...this.context, ...ctx };
-    }
-}

package/dist/spec-bridge/bridges/form-view.d.ts

@@ -1,158 +0,0 @@
-/**
- * ObjectUI
- * Copyright (c) 2024-present ObjectStack Inc.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-/**
- * Form-view bridge input — the documented SUBSET of `@objectstack/spec`'s
- * FormViewSchema this bridge consumes, with every drift-prone key's TYPE bound
- * to the contract instead of restated (objectui#5652).
- *
- * The subset stays hand-listed on purpose: this declaration is load-bearing
- * documentation, and its NON-declarations are a retirement ledger
- * (`defaultSort` / `aria`, objectui#3901 / #3974) that a blanket
- * `Omit<FormView, ...>` would erase. What was never deliberate is the TYPE each
- * declared key was given. Three of them had drifted from what the contract
- * accepts, and nothing ever compared the two descriptions — the mirror shape
- * `scripts/check-spec-symbol-derivation.mjs` exists to catch. The sibling
- * bridge in this directory (`list-view.ts`) was converted the same way and for
- * the same reason (objectui#2231): the shape derives, so it cannot drift.
- *
- * ## What the contract actually answers
- *
- * Measured with `safeParse` against the installed `@objectstack/spec` while
- * fixing this, NOT copied from the finding — two of its three rows were wrong,
- * in ways that change the repair:
- *
- *   FormSection.columns    `1 | 2 | 3 | 4 | '1' | '2' | '3' | '4'`. The string
- *                          arm IS admitted, and the section schema's own pipe
- *                          folds it to a number. The bridge declared `number`
- *                          and refused it.
- *   FormView.columns       `number`, with NO string arm: `FormViewSchema`
- *                          rejects `columns: '3'` at the FORM level while
- *                          `FormSectionSchema` accepts it at the SECTION level.
- *                          The bridge's `number` was already right here — it is
- *                          bound to the contract so the asymmetry cannot rot,
- *                          and the two answers are pinned side by side.
- *   FormField.dependsOn    a BARE parent-field name. The array arm is rejected
- *                          by the contract outright. The bridge declared
- *                          `string[]`, so it admitted only the arm the contract
- *                          refuses and refused the only arm it admits — the one
- *                          configuration that makes `field-selector` and
- *                          `dynamic-config` work (objectui#5040).
- *   *.visibleWhen          `string | { dialect, source?, ast?, meta? }`, with
- *                          `dialect` REQUIRED and enum-typed. `{ dialect?,
- *                          source }` is a DIFFERENT layer's type — the
- *                          evaluator's `FieldRulePredicate` (`@object-ui/core`,
- *                          ADR-0089) — and the contract does not accept it: an
- *                          object arm without `dialect` is refused. The bridge
- *                          declared `string` and refused the object arm
- *                          entirely.
- *
- * ## Declaring an arm is not consuming it
- *
- * A key that is declarable but dropped on the way out is the same defect one
- * layer over (objectui#5542 / #5594), so each widened arm is followed all the
- * way onto the `object-form` node by `FormViewWidenedArms.test.ts`, and the one
- * arm that needs a translation to get there gets it — see `normalizeColumns`.
- */
-import type { DependsOnInput } from '@object-ui/types';
-import type { FormFieldInput, FormSection, FormView } from '@objectstack/spec/ui';
-import type { BridgeFn } from '../types.js';
-/**
- * A form field as authored. Exported so the derivation pins in
- * `__tests__/FormViewWidenedArms.test.ts` can name the declared types; NOT
- * re-exported by `spec-bridge/index.ts`, so the package surface is unchanged.
- */
-export interface FormFieldSpec {
-    field: string;
-    /** Field type (spec FormFieldSchema reuses Data.FieldType; auto-infers widget). */
-    type?: string;
-    /** Options for select/multiselect/radio/checkboxes fields. */
-    options?: any[];
-    /** Target object name for lookup/master_detail fields. */
-    reference?: string;
-    label?: string;
-    placeholder?: string;
-    helpText?: string;
-    readonly?: boolean;
-    required?: boolean;
-    hidden?: boolean;
-    colSpan?: number;
-    widget?: string;
-    /**
-     * Sibling field name whose value this field's widget reads (objectui#5040).
-     *
-     * The contract admits a BARE NAME and refuses an array. This is the wider
-     * {@link DependsOnInput} rather than the contract's `string` alone because
-     * the value is FORWARDED, unread, into the node slot that is declared with
-     * exactly this type (`FormField.dependsOn`, `@object-ui/types`) and read by
-     * `resolveCascadingOptions` / `resolveDependsOnFields` (`@object-ui/core`),
-     * whose parameter is also exactly this type (framework#4074). Narrowing to
-     * the contract's `string` would refuse array-authored layouts that the
-     * runtime has always honoured, on the same never-parsed inputs `groups` and
-     * `visibleOn` below are still read for. The contract's arm is a subset of
-     * this one, which is what the derivation pin asserts — so a spec that widens
-     * `dependsOn` fails the pin instead of silently outgrowing the declaration.
-     */
-    dependsOn?: DependsOnInput;
-    /** Canonical conditional-visibility predicate (ADR-0089), bound to the contract. */
-    visibleWhen?: FormFieldInput['visibleWhen'];
-    /** @deprecated ADR-0089 -> `visibleWhen`. */
-    visibleOn?: FormFieldInput['visibleOn'];
-}
-/** One section of a form layout, as authored. */
-export interface FormSectionSpec {
-    /** Stable section identifier for i18n lookup (spec FormSectionSchema.name). */
-    name?: string;
-    label?: string;
-    description?: string;
-    collapsible?: boolean;
-    collapsed?: boolean;
-    /** Bound to the contract: the string spelling of a column count is admitted. */
-    columns?: FormSection['columns'];
-    /** Section-level conditional-visibility predicate (ADR-0089), bound to the contract. */
-    visibleWhen?: FormSection['visibleWhen'];
-    /**
-     * The authored field list. A bare string is the spec's shorthand for "this
-     * object's own field, rendered with its defaults" — the same shorthand
-     * `mapColumn` already honours on the list bridge.
-     */
-    fields?: Array<string | FormFieldSpec>;
-}
-/**
- * The subset of `@objectstack/spec` FormViewSchema the bridge consumes.
- * Every serializable spec key is either mapped onto the `object-form` node
- * or listed here with an explicit reason for being ignored — the bridge must
- * never silently drop spec configuration (#2545).
- */
-export interface FormViewSpec {
-    type?: string;
-    layout?: string;
-    /** Bound to the contract, which admits NO string arm here — unlike a section. */
-    columns?: FormView['columns'];
-    title?: string;
-    description?: string;
-    defaultTab?: string;
-    tabPosition?: string;
-    allowSkip?: boolean;
-    showStepIndicator?: boolean;
-    splitDirection?: string;
-    splitSize?: number;
-    splitResizable?: boolean;
-    drawerSide?: string;
-    drawerWidth?: string;
-    modalSize?: string;
-    data?: any;
-    sections?: FormSectionSpec[];
-    /** Legacy alias of `sections` (spec: "Legacy support → alias to sections"). */
-    groups?: FormSectionSpec[];
-    /** Inline master-detail child collections. */
-    subforms?: any[];
-    sharing?: any;
-    submitBehavior?: any;
-}
-/** Transforms a FormView spec into a Form SchemaNode */
-export declare const bridgeFormView: BridgeFn<FormViewSpec>;

package/dist/spec-bridge/bridges/form-view.js

@@ -1,170 +0,0 @@
-/**
- * ObjectUI
- * Copyright (c) 2024-present ObjectStack Inc.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-/**
- * Fold the contract's string spelling of a column count onto the number the
- * node carries.
- *
- * `FormSectionSchema` accepts `'2'` and `2` and normalises the string away in
- * its own pipe; the `object-form` node's section declares `columns?: 1|2|3|4`
- * and `FormSectionContainer` indexes its grid-class map by that number. Its
- * header states where the fold belongs: "The normalisation belongs at the seam
- * that parses authored metadata, not in the container's props." This bridge is
- * that seam. Forwarding `'2'` verbatim hands every downstream renderer a value
- * outside the type it declares.
- */
-function normalizeColumns(columns) {
-    return typeof columns === 'string' ? Number(columns) : columns;
-}
-function mapField(field) {
-    const mapped = {
-        name: field.field,
-        label: field.label ?? field.field,
-    };
-    if (field.type)
-        mapped.type = field.type;
-    if (field.options)
-        mapped.options = field.options;
-    if (field.reference)
-        mapped.reference = field.reference;
-    if (field.placeholder)
-        mapped.placeholder = field.placeholder;
-    if (field.helpText)
-        mapped.helpText = field.helpText;
-    if (field.readonly != null)
-        mapped.readonly = field.readonly;
-    if (field.required != null)
-        mapped.required = field.required;
-    if (field.hidden != null)
-        mapped.hidden = field.hidden;
-    if (field.colSpan != null)
-        mapped.colSpan = field.colSpan;
-    if (field.widget)
-        mapped.widget = field.widget;
-    // Forwarded unread into the node's `dependsOn`, which is declared with the
-    // same type and read by `@object-ui/core`'s cascading-option resolver.
-    if (field.dependsOn)
-        mapped.dependsOn = field.dependsOn;
-    // ADR-0089: `visibleWhen` is the canonical view-form-field visibility predicate
-    // (the spec folds the deprecated `visibleOn` into it at parse). Prefer it and
-    // fall back to `visibleOn` for raw / un-normalized metadata. The ObjectForm
-    // renderer reads this view-level predicate from the node's `visibleOn` slot.
-    //
-    // Both contract arms travel whole: the bare CEL string, and the expression
-    // object. `evalFieldPredicate` reads `{ dialect, source }` back out of the
-    // object arm, which is how a spec-authored `{ dialect: 'cel', source: ... }`
-    // now drives visibility instead of being refused by this declaration. An
-    // `ast`-only expression (legal metadata: the contract requires `dialect` plus
-    // one of `source` / `ast`) is forwarded whole rather than dropped, but no
-    // evaluator in this repo reads an `ast` today — that gap is the evaluator's,
-    // and the bridge must not hide it by discarding the key.
-    const visiblePredicate = field.visibleWhen ?? field.visibleOn;
-    if (visiblePredicate)
-        mapped.visibleOn = visiblePredicate;
-    return mapped;
-}
-function mapSection(section) {
-    const mapped = {
-        // A bare field name is the spec's shorthand and is forwarded verbatim: the
-        // node's `fields` slot admits it and `normalizeSectionField`
-        // (@object-ui/plugin-form) resolves it against the object schema. Running
-        // it through `mapField` instead produced `{ name: undefined }` — a field
-        // with no identity — for the most ordinary section a form can declare.
-        fields: (section.fields ?? []).map((field) => typeof field === 'string' ? field : mapField(field)),
-    };
-    if (section.name)
-        mapped.name = section.name;
-    if (section.label)
-        mapped.label = section.label;
-    if (section.description)
-        mapped.description = section.description;
-    if (section.collapsible != null)
-        mapped.collapsible = section.collapsible;
-    if (section.collapsed != null)
-        mapped.collapsed = section.collapsed;
-    if (section.columns != null)
-        mapped.columns = normalizeColumns(section.columns);
-    // Whole, both arms — same predicate contract as the field above.
-    if (section.visibleWhen)
-        mapped.visibleWhen = section.visibleWhen;
-    return mapped;
-}
-/** Maps spec formType to ObjectUI formType */
-function mapFormType(type) {
-    if (!type)
-        return undefined;
-    const validTypes = ['simple', 'tabbed', 'wizard', 'split', 'drawer', 'modal'];
-    return validTypes.includes(type) ? type : undefined;
-}
-/**
- * Spec FormViewSchema keys carried onto the `object-form` node verbatim.
- * All of them are declared with the same name (and semantics) on
- * `ObjectFormSchema`, so no per-key mapping is needed — only presence checks.
- */
-const PASSTHROUGH_KEYS = [
-    'layout',
-    'columns',
-    'title',
-    'description',
-    'defaultTab',
-    'tabPosition',
-    'allowSkip',
-    'showStepIndicator',
-    'splitDirection',
-    'splitSize',
-    'splitResizable',
-    'drawerSide',
-    'drawerWidth',
-    'modalSize',
-    'subforms',
-];
-/** Transforms a FormView spec into a Form SchemaNode */
-export const bridgeFormView = (spec, _context) => {
-    // Spec defines `groups` as a legacy alias of `sections`; normalize here so
-    // downstream renderers only ever see `sections` (ObjectForm never reads a
-    // `groups` key — before this normalization a groups-only spec silently
-    // rendered no sections at all, #2545).
-    const sections = (spec.sections ?? spec.groups ?? []).map(mapSection);
-    const formType = mapFormType(spec.type);
-    const node = {
-        type: 'object-form',
-        id: `form-${spec.type ?? 'default'}`,
-        sections,
-        data: spec.data,
-    };
-    // P1.2 — formType mapping (tabbed, wizard, split, drawer, modal)
-    if (formType)
-        node.formType = formType;
-    // #2545 — same-name spec keys (layout, title, tab/wizard/split/drawer/modal
-    // options, subforms) pass straight through onto the node.
-    for (const key of PASSTHROUGH_KEYS) {
-        if (spec[key] != null)
-            node[key] = spec[key];
-    }
-    if (spec.submitBehavior)
-        node.submitBehavior = spec.submitBehavior;
-    // P1.6 — sharing
-    if (spec.sharing)
-        node.sharing = spec.sharing;
-    // `defaultSort` (#3974) and `aria` (#3901) USED to be copied here. Both are
-    // `retiredKey()` tombstones on spec 17's FormViewSchema, so a FormView that
-    // parsed can never carry either — the guards were unreachable, and their
-    // shape invited the next reader to copy a dead pattern. Removed under the
-    // maintainer's 2026-08-11 enforce-or-remove ruling; measured dormant at BOTH
-    // ends before removal:
-    //   - producer: `FormViewSchema.safeParse` rejects both keys by name
-    //     (`form.defaultSort` / `form.aria` removed in the #3896 close-out).
-    //   - consumer: no form renderer reads either off the node — plugin-form
-    //     reads neither, and `SchemaRenderer`'s generic ARIA injection resolves
-    //     FLAT `ariaLabel`/`ariaDescribedBy`/`role` (SchemaRenderer.tsx:109-119),
-    //     never a nested `aria` object.
-    // The nested `aria` copy is still correct on the LIST bridge
-    // (`list-view.ts:214`), whose carrier stayed live and IS consumed at
-    // `plugin-list/src/ListView.tsx:2389-2392` — do not "align" the two.
-    // Pinned by `__tests__/FormViewRetiredKeys.test.ts`.
-    return node;
-};

package/dist/spec-bridge/bridges/list-view.d.ts

@@ -1,20 +0,0 @@
-/**
- * ObjectUI
- * Copyright (c) 2024-present ObjectStack Inc.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-import type { BridgeFn } from '../types.js';
-import type { ListView } from '@objectstack/spec/ui';
-/**
- * Bridge input: the spec-canonical ListView (#2231 — the former hand-written
- * `ListViewSpec`/`ListColumn` mirrors are retired; the shape now derives from
- * `@objectstack/spec/ui` and can no longer drift). Relaxed to `Partial` because
- * hosts routinely hand the bridge fragmentary view-configs (every field was
- * optional in the old mirror too, including spec-required `columns`).
- */
-type ListViewSpec = Partial<ListView>;
-/** Transforms a ListView spec into a DataTable SchemaNode */
-export declare const bridgeListView: BridgeFn<ListViewSpec>;
-export {};