@nivaro/react 0.1.4

package/dist/index.d.ts

@@ -0,0 +1,1608 @@
+import { CascadeFilterRule } from '@nivaro/sdk';
+import { default as default_2 } from 'react';
+import { FieldDependencyConfig } from '@nivaro/sdk';
+import type { ImportParseResponse } from '@nivaro/sdk';
+import { JSX } from 'react';
+import { JSXElementConstructor } from 'react';
+import { NivaroClient } from '@nivaro/sdk';
+import { default as React_2 } from 'react';
+import { ReactElement } from 'react';
+import { ReactNode } from 'react';
+import { ReactPortal } from 'react';
+import { ReportDateRange } from '@nivaro/sdk';
+import { ReportEntityFilter } from '@nivaro/sdk';
+import { ReportQueryWidgetConfig } from '@nivaro/sdk';
+import { UseMutationResult } from '@tanstack/react-query';
+import { UserScopesInfo } from '@nivaro/sdk';
+
+export declare function AlertManagerView({ defaultTab, hiddenTabs, onOpenReport, className }: AlertManagerViewProps): JSX.Element;
+
+export declare interface AlertManagerViewProps {
+    /** Tab shown on first render. */
+    defaultTab?: TabKey;
+    /** Hide specific tabs (e.g. widget tabs when Report Studio is unused). */
+    hiddenTabs?: TabKey[];
+    /** Called when a widget alert's report name is clicked (host navigation). */
+    onOpenReport?: (reportId: string) => void;
+    className?: string;
+}
+
+export declare function BooleanField({ field, value, onChange, error, disabled, readOnly, inputId, errorId }: FieldComponentProps): JSX.Element;
+
+export declare function canOpenDm(): boolean;
+
+export { CascadeFilterRule }
+
+declare interface ChannelMeta {
+    id: number;
+    visibility: 'open' | 'role' | 'private';
+    role: string | null;
+    topic: string | null;
+    created_by: string | null;
+}
+
+export declare function chatAvatarColor(id: string): string;
+
+export declare interface ChatConfig {
+    collections: {
+        messages: string;
+        reads: string;
+        presence: string;
+    };
+    globalRoom: string;
+    globalLabel: string;
+    /** Entity-id pattern rendered as record links (RegExp source, global flags applied). */
+    entityPattern: string;
+    /** URL for an entity token (null = plain text). */
+    entityUrl: (token: string) => string | null;
+    /** Label for a non-global, non-dm room key (null = uppercased key). */
+    roomLabel?: (room: string) => string | null;
+    /** Host route for a resolved record (entity rooms' "Open record" action) —
+     *  admin passes /collections/:c/:id, efp-new /records/:c/:id. Absent = the
+     *  admin shape; return null = hide the action. */
+    recordUrl?: (collection: string, id: string | number) => string | null;
+    /** Live updates: subscribe to a collection's change feed; return unsubscribe.
+     *  Still used for presence/typing, which remain plain /items collections. */
+    realtime?: (collection: string, cb: () => void) => () => void;
+    /**
+     * Live chat delivery: join the given rooms' socket rooms and call back on a
+     * `chat:message` event. Replaces invalidating on every chat_messages write
+     * anywhere — at channel scale that fan-out is a broadcast storm, and the
+     * server only emits to `chat:<room>` now. Without it the queries still poll.
+     */
+    subscribeRooms?: (rooms: string[], cb: (msg: ChatMessage) => void) => () => void;
+    me: {
+        id: string;
+        name: string;
+    } | null;
+    /** Online users (presence) — drives the Online tab + mention autocomplete. */
+    onlineUsers: ChatOnlineUser[];
+    /** Presence typing setter (userId, room|null). */
+    setTypingRoom?: (userId: string, room: string | null) => void | Promise<void>;
+    navigate?: (url: string) => void;
+    sound: boolean;
+}
+
+export declare function chatInitials(name: string | null): string;
+
+/**
+ * Nivaro chat — data layer.
+ *
+ * Messages, rooms and watermarks go through /api/chat, NOT plain /items: room
+ * visibility (your DMs, the channels you belong to, entity rooms for records
+ * you can read) cannot be expressed as a table-level policy, and the items API
+ * now refuses these collections outright. Presence/typing stay on /items,
+ * which is per-user by nature. Live delivery comes from a host-provided
+ * realtime adapter, with polling fallbacks baked into every query.
+ *
+ * Ported from the EFP implementation with its semantics preserved:
+ * - DM room keys are 'dm:<A>:<B>' with UPPERCASED sorted uuids (MSSQL returns
+ *   uuids uppercased — a casing mismatch forks a second room).
+ * - Read watermarks are serialized per room (markInFlight) because the reads
+ *   table has UNIQUE(user, room) and the room view marks on entry AND on each
+ *   new message — concurrent select-then-insert would 500 on duplicate key.
+ * - Mentions store '@[Display Name]' with no id; notifications fire only for
+ *   users picked from the autocomplete.
+ */
+export declare interface ChatMessage {
+    id: number;
+    sender: string;
+    sender_name: string | null;
+    room: string;
+    message: string;
+    date_created: string;
+}
+
+export declare interface ChatOnlineUser {
+    user_id: string;
+    display_name: string | null;
+    role_name?: string | null;
+    current_path?: string | null;
+}
+
+export declare function ChatPanel({ open, onClose, renderMessageBody, requestedDm }: {
+    open: boolean;
+    onClose: () => void;
+    renderMessageBody?: (m: ChatMessage, ctx: {
+        mine: boolean;
+    }) => React.ReactNode;
+    /** External DM request (UserChip "Send message" via registerDmOpener) —
+     *  nonce bumps re-trigger even for the same user. */
+    requestedDm?: {
+        userId: string;
+        name?: string;
+        nonce: number;
+    } | null;
+}): JSX.Element | null;
+
+export declare function ChatProvider({ children, me, onlineUsers, collections, globalRoom, globalLabel, entityPattern, entityUrl, roomLabel, recordUrl, realtime, subscribeRooms, setTypingRoom, navigate, sound, theme }: ChatProviderProps): JSX.Element;
+
+declare interface ChatProviderProps {
+    children: React.ReactNode;
+    me: ChatConfig['me'];
+    onlineUsers?: ChatOnlineUser[];
+    collections?: Partial<ChatConfig['collections']>;
+    globalRoom?: string;
+    globalLabel?: string;
+    entityPattern?: string;
+    entityUrl?: ChatConfig['entityUrl'];
+    roomLabel?: ChatConfig['roomLabel'];
+    recordUrl?: ChatConfig['recordUrl'];
+    realtime?: ChatConfig['realtime'];
+    subscribeRooms?: ChatConfig['subscribeRooms'];
+    setTypingRoom?: ChatConfig['setTypingRoom'];
+    navigate?: ChatConfig['navigate'];
+    sound?: boolean;
+    theme?: Partial<ChatTheme>;
+}
+
+export declare function ChatRoomList({ rooms, onOpen }: {
+    rooms: RoomInfo[];
+    onOpen: (room: RoomInfo) => void;
+}): JSX.Element;
+
+export declare function ChatRoomView({ room, label, onBack, onOpenSettings, renderMessageBody }: {
+    room: string;
+    label: string;
+    onBack: () => void;
+    /** Channel rooms only — opens members/visibility settings. */
+    onOpenSettings?: () => void;
+    renderMessageBody?: (m: ChatMessage, ctx: {
+        mine: boolean;
+    }) => React.ReactNode;
+}): JSX.Element;
+
+/**
+ * Nivaro chat UI — a complete team panel (Online tab, grouped rooms, live
+ * conversations with mentions, typing, receipts, search).
+ *
+ * Theming: every visual slot reads from `ChatTheme` (className strings) with
+ * nvr-cyan defaults — pass `theme` overrides on ChatProvider to restyle
+ * without forking. Structural hooks: `data-chat-*` attributes on every major
+ * element, `renderMessageBody` to override message rendering entirely.
+ */
+export declare interface ChatTheme {
+    /** My message bubble. */
+    bubbleMine: string;
+    /** Others' message bubble. */
+    bubbleOther: string;
+    /** Accent text (links, read receipt, active states). */
+    accentText: string;
+    /** Soft accent fill (active tab, selected candidate, mention highlight). */
+    accentSoft: string;
+    /** Unread pill. */
+    pill: string;
+    /** Primary action (send button). */
+    action: string;
+    /** Panel/popover surface. */
+    surface: string;
+    /** Input fields. */
+    input: string;
+    /** Divider borders. */
+    divider: string;
+}
+
+/** Clear the schema cache (e.g. after a schema change). */
+export declare function clearFormSchemaCache(collection?: string): void;
+
+/** @deprecated Column model changed to plain field keys — kept for source
+ *  compatibility with early adopters; maps `path` to a field key. */
+export declare interface CollectionBrowserColumn {
+    path: string;
+    label?: string;
+    format?: 'currency' | 'date' | 'datetime' | 'text';
+    filterable?: boolean;
+}
+
+export declare function CollectionBrowserView({ collection, quickFilters, initialColumns, initialSort, pageSize, initialSearch, initialConditions, onOpenItem, showCreate, className }: CollectionBrowserViewProps): React_2.JSX.Element;
+
+export declare interface CollectionBrowserViewProps {
+    collection: string;
+    /** Persistent facet dropdowns above the table (multi-select + Apply/Clear);
+     *  selections filter server-side over the entire record set. */
+    quickFilters?: QuickFilterDef[];
+    /** Initial visible columns (plain field keys). Defaults to the first 7
+     *  non-hidden fields. */
+    initialColumns?: string[];
+    /** Default sort until a header is clicked (e.g. '-created'). */
+    initialSort?: string;
+    pageSize?: number;
+    /** Initial quick-search value (deep links). */
+    initialSearch?: string;
+    /** Contextual deep-link conditions (e.g. a dashboard tile linking to "my
+     *  drafts"): ANDed into every fetch until the user clears the context chip.
+     *  `label` is what the chip displays for that condition. */
+    initialConditions?: Array<{
+        path: string[];
+        op: string;
+        value: unknown;
+        label?: string;
+    }>;
+    /** Override row-open behavior; defaults to NavigationContext itemUrl. */
+    onOpenItem?: (id: string | number) => void;
+    showCreate?: boolean;
+    className?: string;
+}
+
+export declare function CollectionImportPanel({ initialJobId, onJobOpen }: {
+    /** Deep link: open this job's detail on mount. */
+    initialJobId?: string | null;
+    onJobOpen?: (id: string | null) => void;
+}): JSX.Element;
+
+declare interface Column<T = Record<string, unknown>> {
+    key: string;
+    header: React_2.ReactNode;
+    sortable?: boolean;
+    className?: string;
+    headerClassName?: string;
+    render?: (row: T, index: number) => React_2.ReactNode;
+}
+
+declare type ColumnFormatConfig = {
+    type: 'datetime';
+    template: string;
+} | {
+    type: 'number';
+    decimals?: number;
+    thousands?: boolean;
+    prefix?: string;
+    suffix?: string;
+} | {
+    type: 'boolean';
+    true_label: string;
+    false_label: string;
+};
+
+export declare function CommentPanel({ collection, item, title, defaultExpanded, queuedComments, onQueueComment }: {
+    collection: string;
+    item: string | number;
+    title?: string;
+    defaultExpanded?: boolean;
+    queuedComments?: string[];
+    onQueueComment?: (text: string) => void;
+}): React_2.JSX.Element;
+
+export declare type ComponentOverrides = {
+    text?: default_2.ComponentType<FieldComponentProps>;
+    textarea?: default_2.ComponentType<FieldComponentProps>;
+    integer?: default_2.ComponentType<FieldComponentProps>;
+    float?: default_2.ComponentType<FieldComponentProps>;
+    decimal?: default_2.ComponentType<FieldComponentProps>;
+    boolean?: default_2.ComponentType<FieldComponentProps>;
+    date?: default_2.ComponentType<FieldComponentProps>;
+    datetime?: default_2.ComponentType<FieldComponentProps>;
+    select?: default_2.ComponentType<FieldComponentProps>;
+    radio?: default_2.ComponentType<FieldComponentProps>;
+    'checkbox-group'?: default_2.ComponentType<FieldComponentProps>;
+    'relation-m2o'?: default_2.ComponentType<FieldComponentProps>;
+    'relation-o2m'?: default_2.ComponentType<FieldComponentProps>;
+    'relation-m2m'?: default_2.ComponentType<FieldComponentProps>;
+    wysiwyg?: default_2.ComponentType<FieldComponentProps>;
+    file?: default_2.ComponentType<FieldComponentProps>;
+    json?: default_2.ComponentType<FieldComponentProps>;
+    uuid?: default_2.ComponentType<FieldComponentProps>;
+    fallback?: default_2.ComponentType<FieldComponentProps>;
+};
+
+export declare function DataTable<T = Record<string, unknown>>({ columns, rows, rowKey, total, page, limit, isLoading, isError, errorMessage, sort, onSortChange, onPageChange, onRowClick, searchValue, onSearchChange, searchPlaceholder, filterDefs, filterValues, onFilterChange, toolbarRight, emptyMessage, minBodyHeight, fillHeight, hideFilterRow, nowrapCells, pinFirstColumn, columnPins, onColumnPinChange, columnFilterRow, hScrollProxy, selectedIds, onSelectionChange, rowClassName, rowGroups, collapsedGroups, onToggleGroup }: DataTableProps<T>): React_2.JSX.Element;
+
+declare interface DataTableProps<T = Record<string, unknown>> {
+    columns: Column<T>[];
+    rows: T[];
+    rowKey?: (row: T, i: number) => string;
+    total: number;
+    page: number;
+    limit?: number;
+    isLoading?: boolean;
+    isError?: boolean;
+    errorMessage?: string;
+    sort?: string;
+    onSortChange?: (sort: string) => void;
+    onPageChange: (page: number) => void;
+    onRowClick?: (row: T) => void;
+    searchValue?: string;
+    onSearchChange?: (val: string) => void;
+    searchPlaceholder?: string;
+    filterDefs?: FilterDef[];
+    filterValues?: Record<string, string | string[]>;
+    onFilterChange?: (key: string, value: string | string[]) => void;
+    toolbarRight?: React_2.ReactNode;
+    emptyMessage?: string;
+    /** Suppress the inline filter-control row while keeping filterDefs available
+     *  to the host (e.g. a page rendering its own filter rail). */
+    hideFilterRow?: boolean;
+    /** Force single-line cells (whitespace-nowrap on every body cell) — hosts
+     *  pair this with per-column truncation for dense, scannable tables. */
+    nowrapCells?: boolean;
+    /** Pin the selection checkbox (when present) and the first data column so
+     *  they stay visible while the table scrolls horizontally. */
+    pinFirstColumn?: boolean;
+    /** Per-column pinning (CollectionBrowserView parity). When provided (even
+     *  empty), replaces `pinFirstColumn`: left-pinned columns render first,
+     *  right-pinned last, sticky offsets come from live header-cell width
+     *  measurement, and (with `onColumnPinChange`) every header grows a
+     *  hover-revealed pin button cycling none → left → right → none. */
+    columnPins?: Record<string, 'left' | 'right'>;
+    onColumnPinChange?: (key: string, pin: 'left' | 'right' | null) => void;
+    /** Render a compact per-column filter row under the headers — each column
+     *  whose key matches a FilterDef gets that def's control inline (the
+     *  CollectionBrowserView column-filter pattern). Independent of the
+     *  toolbar/rail rendering controlled by `hideFilterRow`. */
+    columnFilterRow?: boolean;
+    /** Always-visible draggable horizontal scrollbar under the table (the
+     *  CollectionBrowserView HScrollProxy) — the native x-scrollbar is hidden
+     *  and trackpad panning is translated by the proxy. */
+    hScrollProxy?: boolean;
+    /** Minimum height for the table body region — keeps empty/short tables from
+     *  collapsing to a sliver (empty message centers in the space). */
+    minBodyHeight?: number;
+    /** Fill the parent's (bounded) height: rows scroll INSIDE the card under a
+     *  sticky header, so the h-scroll proxy and pagination stay pinned in view
+     *  instead of sitting below a page-tall table. Parent must give the card a
+     *  definite height (flex chain with min-h-0). */
+    fillHeight?: boolean;
+    selectedIds?: string[];
+    onSelectionChange?: (ids: string[]) => void;
+    /** Optional per-row class — e.g. at-risk background tinting. */
+    rowClassName?: (row: T) => string | undefined;
+    /** Grouped rendering: when set, `rows` is ignored for the body; each group renders
+     *  a full-width header row followed by its rows (unless collapsed). Pagination hides. */
+    rowGroups?: Array<{
+        key: string;
+        header: React_2.ReactNode;
+        rows: T[];
+    }>;
+    collapsedGroups?: Set<string>;
+    onToggleGroup?: (key: string) => void;
+}
+
+export declare function DateField({ field, value, onChange, error, disabled, readOnly, inputId, errorId }: FieldComponentProps): JSX.Element;
+
+/** The admin's route shape — the default when the host supplies no itemUrl. */
+export declare function defaultItemUrl(t: ItemLinkTarget): string;
+
+declare type DmOpener = (userId: string, displayName?: string) => void;
+
+export declare function dmPeer(room: string, self: string): string | null;
+
+export declare function dmRoom(a: string, b: string): string;
+
+export declare const DrilldownContext: React_2.Context<DrilldownContextValue | null>;
+
+declare interface DrilldownContextValue {
+    open: (target: DrilldownTarget) => void;
+}
+
+export declare interface DrilldownTarget {
+    collection: string;
+    itemId: string;
+    layoutId?: number | null;
+    width?: number | string | null;
+    title?: string;
+}
+
+/**
+ * The ids a filter surface should PRE-SELECT for a dimension. Restrictions are
+ * server-enforced regardless, so the seeded selection must reflect them:
+ * defaults ∩ restricted when both are set; ALL restricted values when defaults
+ * are empty or entirely outside the restriction; plain defaults otherwise.
+ */
+export declare function effectiveScopeSeedIds(scopes: {
+    defaults: Record<string, Array<string | number>>;
+    restricted: Record<string, Array<string | number>>;
+}, dimName: string): Array<string | number>;
+
+export declare function fetchSchema(client: NivaroClient, collection: string, includeHidden: boolean, layoutId?: number, layoutSlug?: string): Promise<FormSchema>;
+
+export declare type FieldArrayReturn = {
+    items: unknown[];
+    append: (item?: unknown) => void;
+    remove: (index: number) => void;
+    move: (from: number, to: number) => void;
+    update: (index: number, value: unknown) => void;
+    replace: (items: unknown[]) => void;
+};
+
+export declare type FieldComponentProps = {
+    field: FormFieldDescriptor;
+    value: unknown;
+    onChange: (value: unknown) => void;
+    error: string[] | undefined;
+    disabled: boolean;
+    readOnly: boolean;
+    /**
+     * Unique DOM id for the input element — generated by NivaroField via useId().
+     * Falls back to `field.field` when not provided (may collide if two forms
+     * with the same collection are mounted simultaneously).
+     */
+    inputId?: string;
+    /** id of the error container element, for aria-describedby wiring */
+    errorId?: string;
+};
+
+export { FieldDependencyConfig }
+
+export declare type FieldState = {
+    value: unknown;
+    error: string[] | undefined;
+    visible: boolean;
+    locked: boolean;
+    required: boolean;
+    colSpan: number;
+    descriptor: FormFieldDescriptor | null;
+    onChange: (v: unknown) => void;
+};
+
+/**
+ * Unstyled file input. On selection it uploads via client.upload() (POST /files)
+ * and calls onChange with the returned file id. Renders the current id/url as text.
+ *
+ * On upload error the file input is reset via a key increment so the browser
+ * doesn't show the failed filename as if the upload succeeded.
+ */
+export declare function FileField({ field, value, onChange, error, disabled, readOnly, inputId, errorId }: FieldComponentProps): JSX.Element;
+
+declare interface FilterDef {
+    key: string;
+    placeholder: string;
+    /** Defaults to 'select' — every existing FilterDef without this field keeps its current dropdown behavior unchanged. */
+    type?: 'select' | 'text' | 'range' | 'combobox';
+    /** Required when type is 'select' or omitted; static options for 'combobox'; ignored for 'text'/'range'. */
+    options?: {
+        label: string;
+        value: string;
+    }[];
+    /** 'combobox' only: server-backed autocomplete. Called (debounced) with the search
+     *  text; overrides `options` when provided. */
+    loadOptions?: (search: string) => Promise<{
+        label: string;
+        value: string;
+    }[]>;
+    /** 'combobox' only: allow selecting multiple values (filter matches ANY of them). */
+    multi?: boolean;
+}
+
+export declare type FormDirtyState = {
+    isDirty: boolean;
+    dirtyFields: string[];
+    isFieldDirty: (field: string) => boolean;
+};
+
+export declare type FormErrors = Record<string, string[]>;
+
+export declare type FormFieldDescriptor = {
+    field: string;
+    /** raw DB type (string, integer, boolean, uuid, json, …) */
+    type: string;
+    /** normalized type used to pick the rendering component */
+    fieldType: FormFieldType;
+    /** CMS interface string (input, select-dropdown, many-to-one, …) */
+    interface: string | null;
+    label: string;
+    note: string | null;
+    required: boolean;
+    readonly: boolean;
+    hidden: boolean;
+    sort: number | null;
+    /** field group key (null = ungrouped) */
+    group: string | null;
+    /** interface options (e.g. { choices: [{text, value}] } for selects) */
+    options: Record<string, unknown> | null;
+    validationRules: FormValidationRule[] | null;
+    visibilityRules: FormVisibilityRule[] | null;
+    lockCondition: FormLockCondition | null;
+    relation?: {
+        type: 'o2m' | 'm2o' | 'm2m' | 'm2a';
+        relatedCollection: string;
+        /** For M2M: the junction/pivot table (e.g. workflows_divisions). relatedCollection is the far-end. */
+        junctionCollection?: string | null;
+        displayTemplate: string | null;
+        manyField?: string | null;
+        junctionField?: string | null;
+    } | null;
+    defaultValue?: unknown;
+    /** cascade_filters from dependency_config — each rule links a parent field to a filter column */
+    cascadeFilters?: Array<{
+        parent_field: string;
+        filter_column: string;
+        clear_on_parent_change?: boolean;
+    }> | null;
+};
+
+/**
+ * Normalized field type used by the form renderer to pick a component.
+ * Derived from the raw DB type + CMS interface string in `useFormSchema`.
+ */
+export declare type FormFieldType = 'text' | 'textarea' | 'integer' | 'float' | 'decimal' | 'boolean' | 'date' | 'datetime' | 'select' | 'radio' | 'checkbox-group' | 'relation-m2o' | 'relation-o2m' | 'relation-m2m' | 'wysiwyg' | 'file' | 'json' | 'uuid' | 'unknown';
+
+export declare type FormGroupDescriptor = {
+    key: string;
+    label: string;
+    type: 'section' | 'tab';
+    icon: string | null;
+    sort: number;
+    isCollapsed: boolean;
+};
+
+/** A client-evaluable lock condition. */
+export declare type FormLockCondition = {
+    when: string;
+    op: string;
+    value?: unknown;
+};
+
+export declare type FormSchema = {
+    collection: string;
+    displayName: string | null;
+    singleton: boolean;
+    draftPublishEnabled: boolean;
+    fields: FormFieldDescriptor[];
+    groups: FormGroupDescriptor[];
+    /** index of the Ungrouped zone among groups (null = after all groups) */
+    ungroupedSort: number | null;
+    /** 'steps' for step-wizard mode, 'tabs' or null for standard tabs */
+    tabMode: 'tabs' | 'steps' | null;
+    aiEnabled: boolean;
+    summaryEnabled: boolean;
+    validateBeforeNext: boolean;
+    /** Slot assignments from the active layout (__pipeline__, __comments__, __tasks__) */
+    slotAssignments: FormSlotAssignment[];
+};
+
+export declare type FormSlotAssignment = {
+    slot: string;
+    groupKey: string | null;
+    sort: number;
+    labelOverride: string | null;
+    isVisible: boolean;
+    defaultExpanded: boolean;
+};
+
+export declare type FormStatus = {
+    isDirty: boolean;
+    isValid: boolean;
+    isSubmitting: boolean;
+    isLoading: boolean;
+    canSubmit: boolean;
+};
+
+/** A single validation rule attached to a field. */
+export declare type FormValidationRule = {
+    type: string;
+    value?: unknown;
+    message?: string;
+    /** soft = warning only, hard (default) = blocks save */
+    soft?: boolean;
+};
+
+/** A client-evaluable visibility rule. */
+export declare type FormVisibilityRule = {
+    /** key of the field this rule observes */
+    when: string;
+    /** eq | neq | null | nnull | in | contains */
+    op: string;
+    value?: unknown;
+    action: 'show' | 'hide';
+};
+
+export declare function getMentionQuery(text: string, cursorPos: number): string | null;
+
+export declare const GridFlushContext: React_2.Context<GridFlushContextValue | null>;
+
+declare type GridFlushContextValue = {
+    register: (key: string, fn: () => Promise<void>) => void;
+    unregister: (key: string) => void;
+};
+
+declare interface HeaderWidgetInfo {
+    field: string;
+    widgetId: number;
+    label: string | null;
+    inputBindings: InputBinding[];
+}
+
+export declare function ImportConsole({ realtime, defaultTab, initialJobId, onJobOpen }: ImportConsoleProps): JSX.Element;
+
+export declare interface ImportConsoleProps {
+    /**
+     * Live `import:progress` events. Hosts own the socket; without an adapter the
+     * console still tracks state on its poll, just up to 5s later.
+     */
+    realtime?: ImportRealtimeAdapter;
+    /** Which section to open on. `definitions` is admin-only. */
+    defaultTab?: ImportConsoleTab;
+    /** Deep link into a collection-import job's detail (admin /imports/:id). */
+    initialJobId?: string | null;
+    /** Fires when a collection-import job's detail opens or closes, so a host
+     *  can keep its own URL in step. */
+    onJobOpen?: (id: string | null) => void;
+}
+
+export declare type ImportConsoleTab = 'runs' | 'collection' | 'definitions';
+
+export declare interface ImportDefinition {
+    id: number;
+    key: string;
+    label: string | null;
+    description: string | null;
+    staging_table: string | null;
+    procedure: string | null;
+    loader: 'bulk' | 'insert' | null;
+    file_types: string | null;
+    is_active: boolean;
+    sort: number;
+}
+
+export declare interface ImportJob {
+    id: string;
+    collection: string;
+    file_name: string;
+    column_map: Record<string, string> | null;
+    duplicate_strategy: string;
+    id_field: string | null;
+    status: ImportJobStatus;
+    total_rows: number | null;
+    processed_rows: number | null;
+    created_rows: number | null;
+    updated_rows: number | null;
+    skipped_rows: number | null;
+    error_rows: number | null;
+    errors: Array<{
+        row: number;
+        error: string;
+    }> | null;
+    created_by: string | null;
+    created_at: string;
+    started_at: string | null;
+    completed_at: string | null;
+}
+
+export declare type ImportJobStatus = 'pending' | 'processing' | 'complete' | 'failed';
+
+/** Result of `POST /staged-imports/preview` — the worker's own parse, run
+ *  against the file before anything is queued. */
+export declare interface ImportPreview {
+    row_count: number;
+    columns: string[];
+    rows: Array<Record<string, string>>;
+    file_name: string;
+    staging_table: string | null;
+    staging_columns: string[] | null;
+    unknown_columns: string[];
+    missing_columns: string[];
+}
+
+/** Emitted by the worker on the `import:progress` socket event. */
+export declare interface ImportProgressEvent {
+    id: number;
+    stage: 'row_count' | 'preparing' | 'importing' | 'completed' | 'error';
+    row_count?: number;
+    duration?: number;
+    error?: string;
+}
+
+/**
+ * Hosts own the socket (the shared package has no transport of its own — the
+ * same contract `QueueWorklist` uses for `collection:update`). Without an
+ * adapter the console still stays current on its 5s poll.
+ */
+export declare interface ImportRealtimeAdapter {
+    subscribe: (onProgress: (event: ImportProgressEvent) => void) => () => void;
+}
+
+/** A row of `nivaro_import_queue`, joined with its definition, file and queuer. */
+export declare interface ImportRun {
+    id: number;
+    definition: number | null;
+    import_key: string;
+    status: ImportRunStatus;
+    sort: number;
+    file: string | null;
+    row_count: number | null;
+    duration: number | null;
+    logs: string | null;
+    started_at: string | null;
+    finished_at: string | null;
+    created_by: string | null;
+    created_at: string | null;
+    updated_at: string | null;
+    legacy_id: number | null;
+    definition_label: string | null;
+    staging_table: string | null;
+    procedure: string | null;
+    loader: 'bulk' | 'insert' | null;
+    definition_active: boolean | null;
+    file_name: string | null;
+    file_size: string | number | null;
+    created_by_first_name: string | null;
+    created_by_last_name: string | null;
+    created_by_email: string | null;
+}
+
+/** Shared types for the Import Console (`/api/staged-imports`). */
+export declare type ImportRunStatus = 'queued' | 'running' | 'completed' | 'error' | 'canceled';
+
+/** Live queue depth is never windowed; the rest respects `window_days`. */
+export declare interface ImportStats {
+    window_days: number;
+    by_status: Partial<Record<ImportRunStatus, number>>;
+    total: number;
+    /** Unwindowed — distinguishes "nothing has ever run" from "nothing recently". */
+    all_time_total: number;
+    /** Unwindowed run count per import key — a property of the definition. */
+    by_key: Record<string, number>;
+    rows_imported: number;
+    median_duration: number | null;
+    success_rate: number | null;
+    runs_today: number;
+    active: Array<{
+        id: number;
+        import_key: string;
+        status: 'queued' | 'running';
+        started_at: string | null;
+        created_at: string | null;
+        row_count: number | null;
+    }>;
+}
+
+declare interface InputBinding {
+    key: string;
+    binding_type: 'item_field' | 'static' | 'url_param';
+    binding_value: string;
+}
+
+export declare const ItemEditAuthContext: React_2.Context<ItemEditAuthContextValue>;
+
+declare type ItemEditAuthContextValue = {
+    isAdmin: boolean;
+    userId: string;
+};
+
+export declare function ItemEditForm({ collection, itemId: itemIdProp, layoutSlug, onBack, onSaved, onDeleted, showHeader, showItemActions, showRevisions, showClone, showPipeline, showWorkflow, showComments, showTasks, showLockBanner, className, headerClassName, renderField, extraTopContent, extraBottomContent, onHeaderWidgets, initialImportResult, initialValues }: ItemEditFormProps): JSX.Element;
+
+export declare interface ItemEditFormProps {
+    collection: string;
+    itemId?: string;
+    layoutSlug?: string;
+    onBack?: () => void;
+    onSaved?: (id: string) => void;
+    onDeleted?: () => void;
+    showHeader?: boolean;
+    /** Render extension-registered item actions (Push to Fusion etc.) in the
+     *  header toolbar. Off by default — the admin's ItemEdit page renders its
+     *  own copy in the page header; headless hosts opt in. */
+    showItemActions?: boolean;
+    showRevisions?: boolean;
+    showClone?: boolean;
+    showPipeline?: boolean;
+    showWorkflow?: boolean;
+    showComments?: boolean;
+    showTasks?: boolean;
+    showLockBanner?: boolean;
+    className?: string;
+    headerClassName?: string;
+    renderField?: (props: RenderFieldProps) => ReactNode;
+    extraTopContent?: ReactNode;
+    extraBottomContent?: ReactNode;
+    onHeaderWidgets?: (widgets: HeaderWidgetInfo[]) => void;
+    /** Consumed once, on mount, when `isNew` — prefills the draft + stages O2M
+     *  lines from an already-parsed import result (e.g. handed off by a caller
+     *  that ran the file picker before this form existed). */
+    initialImportResult?: ImportParseResponse;
+    /** Consumed once, on mount, when `isNew` — seeds the draft with plain field
+     *  values (deep-link prefill, "create from common values", AI hand-offs).
+     *  User edits made before the seed applies win over seeded keys. */
+    initialValues?: Record<string, unknown>;
+}
+
+/** A record the UI wants to link to / open the edit page for. */
+export declare type ItemLinkTarget = {
+    collection: string;
+    itemId: string;
+    /** Grouped-layout slug to pin (queue item_layout etc.); null/absent = default. */
+    layoutSlug?: string | null;
+};
+
+export declare function ItemLockBanner({ lockHolder, onTakeOver, takingOver, isAdmin }: {
+    lockHolder: LockHolder | null;
+    onTakeOver: () => void;
+    takingOver: boolean;
+    isAdmin?: boolean;
+}): JSX.Element | null;
+
+/**
+ * Full layout-aware form renderer.
+ *
+ * Renders the form exactly as configured in the Layout tab:
+ * - Tab-type groups become clickable tabs (or step wizards when tabMode='steps')
+ * - Section-type groups become collapsible sections
+ * - Ungrouped fields appear at the position set in the Layout tab
+ * - Fields honour their col_span width inside a 12-column grid
+ * - Page slots (__pipeline__, __comments__, __tasks__) rendered via slotRenderers
+ *
+ * Zero CSS shipped — style via className props or data-* attributes.
+ */
+export declare function LayoutForm({ form, components, className, style, sectionClassName, tabStripClassName, activeTabClassName, inactiveTabClassName, gridClassName, slotRenderers, itemId, stepperClassName, stepNavClassName, prevButtonClassName, nextButtonClassName, lastStepActions, layoutSlug: _layoutSlug }: LayoutFormProps): default_2.JSX.Element | null;
+
+declare type LayoutFormProps = {
+    form: UseNivaroFormReturn;
+    components?: ComponentOverrides;
+    /** CSS class applied to the <form> element */
+    className?: string;
+    style?: default_2.CSSProperties;
+    /** CSS class for a section group wrapper */
+    sectionClassName?: string;
+    /** CSS class for a tab strip wrapper */
+    tabStripClassName?: string;
+    /** CSS class for the active tab button */
+    activeTabClassName?: string;
+    /** CSS class for inactive tab buttons */
+    inactiveTabClassName?: string;
+    /** CSS class for the 12-col grid row (col_span chips snap to this) */
+    gridClassName?: string;
+    /**
+     * Slot renderers — keyed by slot name (__pipeline__, __comments__, __tasks__).
+     * Called with { slot, collection, itemId, labelOverride, defaultExpanded }.
+     * If omitted, slots are silently skipped.
+     */
+    slotRenderers?: Record<string, (props: SlotRendererProps) => default_2.ReactNode>;
+    /**
+     * itemId of the currently-loaded item — needed for slot renderers.
+     * For edit mode: pass the item id. For create mode: leave undefined.
+     */
+    itemId?: string | number | null;
+    /** CSS class for the stepper strip wrapper (steps mode) */
+    stepperClassName?: string;
+    /** CSS class for the prev/next button bar (steps mode) */
+    stepNavClassName?: string;
+    /** CSS class for the Prev button */
+    prevButtonClassName?: string;
+    /** CSS class for the Next/Save button */
+    nextButtonClassName?: string;
+    /** Extra content rendered before the Save button on the last step (steps mode only) */
+    lastStepActions?: default_2.ReactNode;
+    /**
+     * Layout slug that was used to load this form's schema.
+     * Informational only — schema resolution happens in useNivaroForm.
+     */
+    layoutSlug?: string;
+};
+
+export declare type LayoutItem = FormGroupDescriptor | '__ungrouped__';
+
+declare interface LockHolder {
+    locked_by: string;
+    locked_by_name: string | null;
+}
+
+/** Match a filter surface (by its own key and/or its options collection) to a
+ *  scope dimension. Convention: key === dimension name wins, else the filter's
+ *  options collection === the dimension's target collection. */
+export declare function matchScopeDimension(scopes: UserScopesInfo | null, probe: {
+    key?: string;
+    collection?: string;
+}): UserScopesInfo['dimensions'][number] | null;
+
+declare interface MessageToken {
+    text: string;
+    entity?: string;
+    mention?: string;
+}
+
+export declare const NavigationContext: React_2.Context<NavigationContextValue>;
+
+declare type NavigationContextValue = {
+    /** `options.state` rides along for hosts whose router supports it (e.g. react-router's
+     *  useNavigate) — hosts that ignore the second argument still navigate correctly. */
+    navigate: (path: string, options?: {
+        state?: unknown;
+    }) => void;
+    /** Map item links onto the host app's own routes. Components fall back to
+     *  the admin shape (/collections/:collection/:id?layout=…) when absent —
+     *  external embeds supply one function and every open path follows. */
+    itemUrl?: (target: ItemLinkTarget) => string;
+    /** Full interception of item-opening: return true = handled (components
+     *  skip navigation entirely — open your own modal/drawer instead). Checked
+     *  before itemUrl/navigate. */
+    openItem?: (target: ItemLinkTarget) => boolean | undefined;
+    /** Route for a user's profile page (UserChip "View profile"). Absent = the
+     *  admin shape `/users/:id`; return null = host has no such page, the
+     *  action is hidden instead of navigating into the host's 404 fallback. */
+    userUrl?: (userId: string) => string | null;
+};
+
+/**
+ * Selects and renders the correct field component for a single field based on
+ * its normalized fieldType. Override any type via `components`; falls back to
+ * `components.fallback` or a basic text input for unknown types.
+ *
+ * Uses React 18's useId() to generate a unique DOM id per field instance so
+ * two forms with the same collection mounted simultaneously don't collide.
+ */
+export declare function NivaroField({ field, value, onChange, error, disabled, readOnly, components, className, itemId }: NivaroFieldProps): default_2.JSX.Element;
+
+declare type NivaroFieldProps = {
+    field: FormFieldDescriptor;
+    value: unknown;
+    onChange: (value: unknown) => void;
+    error?: string[];
+    disabled?: boolean;
+    readOnly?: boolean;
+    components?: ComponentOverrides;
+    className?: string;
+    /** Parent item id — passed through to inline-grid fields */
+    itemId?: string | number | null;
+};
+
+/**
+ * Optional convenience wrapper that renders a <form> driven by useNivaroForm.
+ * Provide `children` to fully control layout, or omit them to auto-render every
+ * group and its fields via NivaroField.
+ */
+export declare function NivaroForm({ form, children, components, renderField, renderGroup, className, style }: NivaroFormProps): default_2.JSX.Element;
+
+declare type NivaroFormProps = {
+    /** the object returned by useNivaroForm */
+    form: UseNivaroFormReturn;
+    /** custom render children; if omitted the form auto-renders all fields/groups */
+    children?: default_2.ReactNode;
+    /** override specific field-type renderers */
+    components?: ComponentOverrides;
+    /** wrap/replace the rendering of a single field */
+    renderField?: (field: FormFieldDescriptor, defaultRender: () => default_2.ReactNode) => default_2.ReactNode;
+    /** wrap/replace the rendering of a group + its fields */
+    renderGroup?: (group: FormGroupDescriptor | null, fields: default_2.ReactNode) => default_2.ReactNode;
+    className?: string;
+    style?: default_2.CSSProperties;
+};
+
+export declare function NivaroProvider({ client, children }: {
+    client: NivaroClient;
+    children: React_2.ReactNode;
+}): React_2.JSX.Element;
+
+/**
+ * Map a raw DB type + CMS interface string to the normalized FormFieldType
+ * the renderer uses to choose a component.
+ */
+export declare function normalizeFieldType(rawType: string, iface: string | null, relation: FormFieldDescriptor['relation']): FormFieldType;
+
+export declare function NumberField({ field, value, onChange, error, disabled, readOnly, inputId, errorId }: FieldComponentProps): JSX.Element;
+
+declare interface O2MFieldInfo {
+    field: string;
+    label: string;
+    relatedCollection: string;
+    manyField: string;
+    parentId: string;
+}
+
+export declare function openDmWith(userId: string, displayName?: string): void;
+
+export declare function OwnerAvatars({ owners, max, emptyLabel }: {
+    owners: OwnerLike[];
+    max?: number;
+    emptyLabel?: string;
+}): JSX.Element;
+
+declare interface OwnerLike {
+    id: string;
+    name: string;
+}
+
+export declare function PageRenderer({ slug, hideHeader, className }: PageRendererProps): JSX.Element;
+
+export declare interface PageRendererPage {
+    slug: string;
+    name: string;
+    layout?: {
+        columns?: number;
+        widgets?: PageRendererWidget[];
+    } | null;
+}
+
+export declare interface PageRendererProps {
+    /** nivaro_pages slug to render. */
+    slug: string;
+    /** Hide the page-name header row (host renders its own chrome). */
+    hideHeader?: boolean;
+    className?: string;
+}
+
+export declare interface PageRendererWidget {
+    id: string;
+    type: string;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    config?: Record<string, unknown>;
+}
+
+declare interface PendingTask {
+    title: string;
+    assignee: string | null;
+    due_date: string;
+}
+
+export declare function PipelinePanel({ collection, item, defaultExpanded, title, showApprovalChain, onBeforeTransition, addendumPending }: {
+    collection: string;
+    item: string;
+    defaultExpanded?: boolean;
+    title?: string;
+    showApprovalChain?: boolean;
+    onBeforeTransition?: () => boolean;
+    addendumPending?: boolean;
+}): JSX.Element | null;
+
+export declare function PipelineTransitionButtons({ collection, item, onBeforeTransition }: {
+    collection: string;
+    item: string;
+    onBeforeTransition?: () => boolean;
+}): JSX.Element | null;
+
+export declare function ProfileView({ userId, className }: {
+    userId?: string | null;
+    className?: string;
+}): JSX.Element;
+
+export declare function QueryWidgetBody({ cfg, dateRange, entityFilters, refetchInterval, onStatus, onDrill }: {
+    cfg: ReportQueryWidgetConfig;
+    dateRange: ReportDateRange | null;
+    entityFilters: ReportEntityFilter[];
+    refetchInterval?: number;
+    onStatus?: (s: {
+        isFetching: boolean;
+        refetch: () => void;
+    }) => void;
+    onDrill?: (t: {
+        collection: string;
+        itemId: string;
+        title?: string;
+    }) => void;
+}): JSX.Element;
+
+export declare function QueueBulkBar({ count, states, busy, claimsEnabled, onClaim, onRelease, onTransition, onClear }: {
+    count: number;
+    states: Array<{
+        value: string;
+        label: string;
+    }>;
+    busy: boolean;
+    claimsEnabled?: boolean;
+    onClaim: () => void;
+    onRelease: () => void;
+    onTransition: (state: string) => void;
+    onClear: () => void;
+}): JSX.Element | null;
+
+declare interface QueueItemRow {
+    collection: string;
+    item_id: string;
+    label: string;
+    state: string | null;
+    state_color: string | null;
+    owners: QueueOwner_2[];
+    sla_status: 'ok' | 'warning' | 'breached' | null;
+    at_risk: boolean;
+    aging_hours: number | null;
+    claimed_by: QueueOwner_2 | null;
+    url: string;
+}
+
+export declare function QueueItemSheet({ item, onOpenChange, onClaim, onRelease, workNextActive, onNext, refetchItems, stateLabels, collectionLabel, claimsEnabled, columnFormats, width, itemLayout }: {
+    item: SheetItem | null;
+    onOpenChange: (open: boolean) => void;
+    onClaim: (item: SheetItem) => void;
+    onRelease: (item: SheetItem) => void;
+    workNextActive?: boolean;
+    onNext?: () => void;
+    refetchItems: () => void;
+    /** State key → display label (falls back to the raw key). */
+    stateLabels?: Record<string, string>;
+    /** Collection name → display name. */
+    collectionLabel?: (name: string) => string;
+    /** When false the claim/release button is hidden. */
+    claimsEnabled?: boolean;
+    /** Extra-field path → display format config (display-only). */
+    columnFormats?: Record<string, ColumnFormatConfig>;
+    /** Sidebar width: px number or 'NN%' of viewport; default 480. */
+    width?: number | string | null;
+    /** Layout slug the Open button pins on the full item; null = default. */
+    itemLayout?: string | null;
+}): JSX.Element;
+
+export declare function QueueKanbanBoard({ items, onDrop, onCardClick, onClaim, onRelease, swimlaneBy, stateLabels, laneLabel, claimsEnabled }: {
+    items: QueueItemRow[];
+    onDrop: (item: QueueItemRow, targetState: string) => void;
+    onCardClick: (item: QueueItemRow) => void;
+    onClaim: (item: QueueItemRow) => void;
+    onRelease: (item: QueueItemRow) => void;
+    /** Optional horizontal lanes crossed with the state columns. */
+    swimlaneBy?: 'collection' | 'owners' | null;
+    /** State key → display label (falls back to the raw key). */
+    stateLabels?: Record<string, string>;
+    /** Formats lane keys (e.g. collection names → display names). */
+    laneLabel?: (key: string) => string;
+    /** When false the per-card Claim/Release button is hidden. */
+    claimsEnabled?: boolean;
+}): JSX.Element;
+
+declare interface QueueOwner {
+    id: string;
+    name: string;
+}
+
+declare interface QueueOwner_2 {
+    id: string;
+    name: string;
+}
+
+export declare interface QueueRealtimeAdapter {
+    /** Subscribe to update events for these collections; call onUpdate per event; return unsubscribe. */
+    subscribe: (collections: string[], onUpdate: () => void) => () => void;
+}
+
+export declare function QueueWorklist({ queueId, realtime, renderError }: QueueWorklistProps): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | ReactPortal | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | JSX.Element | null;
+
+export declare interface QueueWorklistProps {
+    queueId: string;
+    realtime?: QueueRealtimeAdapter;
+    renderError?: (status: number) => React.ReactNode;
+}
+
+export declare function QueueWorkloadView({ queueId }: {
+    queueId: string;
+}): JSX.Element;
+
+declare interface QuickFilterDef {
+    /** Unique key for this filter's selection state. */
+    key: string;
+    label: string;
+    /** Server condition path — supports M2O chains and O2M/M2M alias hops
+     *  (e.g. ['funding_years'], ['project', 'project_type']). */
+    path: string[];
+    /** When set, the selection matches if ANY of these paths hits (server _or
+     *  group) — e.g. project.project_type OR car_project_type. Overrides path. */
+    or_paths?: string[][];
+    /** Collection the options list loads from. */
+    collection: string;
+    /** Option value column (default 'id'). */
+    value_field?: string;
+    /** Option label column. */
+    label_field: string;
+    sort?: string;
+}
+
+export declare function RecordDrilldownSheet({ collection, itemId, layoutId, rootLayoutSlug, width, title, onClose }: {
+    collection: string;
+    itemId: string;
+    layoutId?: number | null;
+    /** Render the ROOT record with this exact layout slug (a queue's configured
+     *  grouped item_layout), bypassing detail-layout resolution. Nested drills
+     *  still use detail layouts. */
+    rootLayoutSlug?: string | null;
+    /** Panel width per config: px number or 'NN%' of the viewport; default 640. */
+    width?: number | string | null;
+    title?: string;
+    onClose: () => void;
+}): JSX.Element;
+
+/** Register the host's DM opener. Returns an unregister function. */
+export declare function registerDmOpener(fn: DmOpener): () => void;
+
+/**
+ * Unstyled relation picker.
+ *  - m2o: single <select> of related items
+ *  - o2m / m2m: multi <select> of related item ids
+ *
+ * Options are fetched from the related collection via useRelationOptions and
+ * labelled with the relation's display template.
+ *
+ * If no NivaroClient is available (neither via NivaroProvider nor passed
+ * directly to the field consumer), a visible error is shown instead of a
+ * silently-empty picker.
+ */
+export declare function RelationField({ field, value, onChange, error, disabled, readOnly, inputId, errorId }: FieldComponentProps): JSX.Element;
+
+export declare type RelationOption = {
+    id: string | number;
+    label: string;
+    raw: Record<string, unknown>;
+};
+
+declare type RenderFieldProps = {
+    field: any;
+    value: unknown;
+    onChange: (v: unknown) => void;
+    disabled: boolean;
+    collection: string;
+    itemId: string;
+    relations: any[];
+    cascadeFilter?: Record<string, unknown>;
+    unsatisfiedParentLabel?: string | null;
+    requiredParentLabel?: string | null;
+};
+
+export declare function ReportView({ reportId, showFilterBar, dateRange, initialEntityFilters, refetchInterval, className, emptyState }: ReportViewProps): JSX.Element;
+
+/**
+ * ReportView — the full, styled, interactive Report Studio renderer for
+ * headless frontends, matching how QueueWorklist / ItemEditForm ship.
+ *
+ * Fully Tailwind-styled (bring the styles via `@nivaro/react/full.css` or the
+ * Tailwind preset, exactly like the other shared components) and interactive:
+ * a global filter bar (date-range switcher + live entity-filter chips), and
+ * per-widget freshness + one-click refresh. Every widget resolves as the
+ * client identity — collection read permissions apply server-side. Charts use
+ * recharts (bundled into the react package). Read-only: no drag/resize edit
+ * surface (that lives in the admin builder).
+ */
+export declare interface ReportViewProps {
+    reportId: string;
+    /** Show the global filter bar (date range + entity chips). Default true. */
+    showFilterBar?: boolean;
+    /** Override the report's saved date range at view time. */
+    dateRange?: ReportDateRange | null;
+    /** Initial report-level entity filters. */
+    initialEntityFilters?: ReportEntityFilter[];
+    /** Poll interval (ms) for live refresh; omit for one-shot. */
+    refetchInterval?: number;
+    className?: string;
+    emptyState?: React.ReactNode;
+}
+
+export declare function RevisionsPanel({ collection, item, onRollback, triggerClassName, inlineTableFields, open, onOpenChange }: {
+    collection: string;
+    item: string;
+    onRollback?: () => void;
+    triggerClassName?: string;
+    inlineTableFields?: O2MFieldInfo[];
+    /** Controlled mode (no trigger button) — open the sheet programmatically,
+     *  e.g. from a row Actions menu. */
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+}): JSX.Element;
+
+export declare interface RoomInfo {
+    room: string;
+    label: string;
+    kind: 'global' | 'dm' | 'channel' | 'entity';
+    lastMessage: ChatMessage | null;
+    unread: number;
+    muted: boolean;
+    joined: boolean;
+    channel: ChannelMeta | null;
+}
+
+export declare type SectionState = {
+    isCollapsed: (key: string) => boolean;
+    toggle: (key: string) => void;
+    collapseAll: () => void;
+    expandAll: () => void;
+};
+
+export declare function SelectField({ field, value, onChange, error, disabled, readOnly, inputId, errorId }: FieldComponentProps): JSX.Element;
+
+/**
+ * rrweb session recorder for headless frontends.
+ *
+ * Drop `useSessionRecorder({ app: 'customer-portal' })` anywhere inside a
+ * NivaroProvider (or pass a client explicitly) and the app records itself —
+ * ONLY when the Nivaro instance has session recording enabled in Settings,
+ * and ONLY if the host app has `rrweb` installed (optional peer dependency;
+ * without it the hook warns once and no-ops).
+ *
+ * Privacy defaults match the admin recorder: every input masked before
+ * events leave the browser, elements with the `nvr-no-record` class blocked.
+ * Events flush every 10s (or 150 events); the server enforces size caps and
+ * a 7-day retention. Recordings attribute to the authenticated SDK identity
+ * (usually your service token's user) with the `app` label telling replays
+ * apart per frontend.
+ */
+export declare interface SessionRecorderOptions {
+    /** Label shown in the admin replay list — which frontend this is. */
+    app?: string;
+    /** Explicit client; defaults to the NivaroProvider context client. */
+    client?: NivaroClient;
+    /** Force-disable locally regardless of the instance setting. */
+    disabled?: boolean;
+}
+
+declare interface SheetItem {
+    collection: string;
+    item_id: string;
+    label: string;
+    state: string | null;
+    state_color: string | null;
+    owners: QueueOwner[];
+    sla_status: 'ok' | 'warning' | 'breached' | null;
+    at_risk: boolean;
+    aging_hours: number | null;
+    claimed_by: QueueOwner | null;
+    extra?: Record<string, unknown>;
+    url: string;
+}
+
+export declare type SlotRendererProps = {
+    slot: string;
+    collection: string;
+    itemId: string | number | null | undefined;
+    labelOverride: string | null;
+    defaultExpanded: boolean;
+};
+
+export declare function splitMessageTokens(text: string, entityPattern: string): MessageToken[];
+
+declare type TabKey = 'catalog' | 'rules' | 'subscriptions' | 'history' | 'widget_alerts' | 'widget_alert_history' | 'anomaly_rules' | 'anomaly_history';
+
+export declare type TabState = {
+    activeTab: string | null;
+    setActiveTab: (key: string) => void;
+    tabs: FormGroupDescriptor[];
+    hasTabs: boolean;
+};
+
+export declare function TaskPanel({ collection, item, title, defaultExpanded, queuedTasks, onQueueTask }: {
+    collection: string;
+    item: string;
+    title?: string;
+    defaultExpanded?: boolean;
+    queuedTasks?: PendingTask[];
+    onQueueTask?: (task: PendingTask) => void;
+}): JSX.Element | null;
+
+export declare function TextareaField({ field, value, onChange, error, disabled, readOnly, inputId, errorId }: FieldComponentProps): JSX.Element;
+
+export declare function TextField({ field, value, onChange, error, disabled, readOnly, inputId, errorId }: FieldComponentProps): JSX.Element;
+
+/**
+ * Translate scope values (target-collection IDS) into a filter's value space.
+ * When the filter compares ids (valueField 'id'/undefined) this is identity;
+ * otherwise the target collection is fetched once to map id → valueField.
+ */
+export declare function translateScopeValues(client: {
+    request: (c: unknown) => Promise<unknown>;
+}, dimension: {
+    target_collection: string;
+}, ids: Array<string | number>, valueField?: string): Promise<Array<string | number>>;
+
+export declare function useChatConfig(): ChatConfig;
+
+export declare function useChatMessages(room: string | null): {
+    messages: NoInfer<ChatMessage[]>;
+    loading: boolean;
+};
+
+/**
+ * The sidebar. The server decides WHICH rooms (visibility) and computes unread
+ * in SQL against the watermark; the client only labels them. The old version
+ * pulled the last 500 messages globally and grouped them here, which both
+ * leaked other people's rooms and silently dropped quiet ones once a busy room
+ * filled the window.
+ */
+export declare function useChatRooms(): {
+    rooms: RoomInfo[];
+    totalUnread: number;
+    loading: boolean;
+};
+
+export declare function useDrilldown(): DrilldownContextValue | null;
+
+export declare function useFieldArray(form: UseNivaroFormReturn, field: string): FieldArrayReturn;
+
+export declare function useFieldState(form: UseNivaroFormReturn, field: string): FieldState;
+
+export declare function useFormDirty(form: UseNivaroFormReturn, initialValuesOverride?: Record<string, unknown>): FormDirtyState;
+
+/**
+ * Fetch + cache a collection's form schema. Caches by client URL + collection +
+ * includeHidden flag so re-mounts and sibling forms share one request.
+ *
+ * NOTE: Pass a stable `client` reference. A new object on every render resets
+ * the cache key and re-fetches. Use `useMemo` or define the client outside the
+ * component tree.
+ */
+export declare function useFormSchema(client: NivaroClient | null, collection: string, includeHidden?: boolean, layoutId?: number, layoutSlug?: string): {
+    schema: FormSchema | null;
+    loading: boolean;
+    error: Error | null;
+};
+
+export declare function useFormStatus(form: UseNivaroFormReturn): FormStatus;
+
+export declare function useGridFlush(): GridFlushContextValue | null;
+
+export declare function useItemEditAuth(): ItemEditAuthContextValue;
+
+export declare function useItemLock(collection: string | undefined, item: string | undefined, enabled: boolean): {
+    lockHolder: LockHolder | null;
+    acquired: boolean;
+    isReadOnly: boolean;
+    takeOver: () => Promise<void>;
+    takingOver: boolean;
+    isAdmin: boolean;
+};
+
+/** Resolved item-link helpers honoring the host's itemUrl/openItem overrides. */
+export declare function useItemNavigation(): {
+    urlFor: (target: ItemLinkTarget) => string;
+    open: (target: ItemLinkTarget) => void;
+};
+
+/**
+ * Mark read. The server upserts against UNIQUE(user, room), so the old
+ * select-then-insert dance (and the per-room promise chain that stopped it
+ * 500ing on duplicate key) is gone.
+ */
+export declare function useMarkRoomRead(): UseMutationResult<unknown, Error, string, unknown>;
+
+/**
+ * The signed-in user's scope dimensions + default/restricted value sets
+ * (User Scopes feature). Filter surfaces use this to SEED initial selections
+ * from defaults and NARROW visible options to restricted values — narrowing
+ * is curation; the items service enforces restrictions server-side regardless.
+ */
+export declare function useMyScopes(): {
+    scopes: UserScopesInfo | null;
+    ready: boolean;
+};
+
+export declare function useNavigation(): NavigationContextValue;
+
+export declare function useNivaroClient(): NivaroClient;
+
+/**
+ * Primary form hook for Nivaro CMS.
+ *
+ * IMPORTANT: Pass a stable `client` reference (defined outside the component
+ * or wrapped in useMemo). A new object on every render triggers schema
+ * re-fetches and item reloads on every render cycle.
+ */
+export declare function useNivaroForm(collection: string, options: UseNivaroFormOptions, client?: NivaroClient): UseNivaroFormReturn;
+
+export declare type UseNivaroFormOptions = {
+    mode: 'create' | 'edit';
+    /** required when mode='edit' */
+    itemId?: string | number;
+    defaultValues?: Record<string, unknown>;
+    onSuccess?: (item: Record<string, unknown>) => void;
+    onError?: (error: Error) => void;
+    /** custom synchronous validators; return an error string or null when valid */
+    validate?: Record<string, (value: unknown, values: Record<string, unknown>) => string | null>;
+    /** include hidden fields in the schema (default false) */
+    includeHidden?: boolean;
+    /**
+     * Specific layout id to use for group/field ordering.
+     * When omitted, the collection's active layout is used automatically.
+     */
+    layoutId?: number;
+    /**
+     * Layout slug to resolve a specific named layout variant.
+     * When set, overrides `layoutId` and fetches the layout by its machine name.
+     */
+    layoutSlug?: string;
+    /**
+     * Debounce delay in ms for server-side field-rules evaluation (default 300).
+     * Pass 0 to disable server evaluation entirely.
+     */
+    fieldRulesDebounce?: number;
+};
+
+export declare type UseNivaroFormReturn = {
+    schema: FormSchema | null;
+    schemaLoading: boolean;
+    schemaError: Error | null;
+    values: Record<string, unknown>;
+    /** Snapshot of values as last confirmed by the server (or seeded defaults). */
+    initialValues: Record<string, unknown>;
+    errors: FormErrors;
+    isDirty: boolean;
+    isSubmitting: boolean;
+    /** true while loading schema or the item being edited */
+    isLoading: boolean;
+    isVisible: (field: string) => boolean;
+    isLocked: (field: string) => boolean;
+    setValue: (field: string, value: unknown) => void;
+    setValues: (patch: Record<string, unknown>) => void;
+    reset: (values?: Record<string, unknown>) => void;
+    handleSubmit: (e?: default_2.FormEvent) => Promise<void>;
+    fieldsByGroup: Map<string | null, FormFieldDescriptor[]>;
+    visibleGroups: FormGroupDescriptor[];
+    gridFlushersRef: default_2.MutableRefObject<Map<string, () => Promise<void>>>;
+};
+
+export declare function useOrderedLayout(form: UseNivaroFormReturn): {
+    items: LayoutItem[];
+    hasTabs: boolean;
+    tabGroups: FormGroupDescriptor[];
+    sectionGroups: FormGroupDescriptor[];
+    ungroupedFields: FormFieldDescriptor[];
+};
+
+export declare function usePeerReadAt(room: string | null): string | null;
+
+export declare function UserChip({ userId, size }: {
+    userId: string;
+    size?: 'default' | 'compact';
+}): React_2.JSX.Element;
+
+/**
+ * Fetch selectable options for a relation field's related collection.
+ * Re-fetches when `search` changes. Pass `enabled: false` to skip fetching
+ * (e.g. while the related collection name is still unknown).
+ *
+ * When `enabled` transitions to false, previously-loaded options are retained
+ * so cascading pickers don't flash blank while a parent field is being cleared.
+ */
+export declare function useRelationOptions(client: NivaroClient | null, relatedCollection: string, options?: {
+    search?: string;
+    limit?: number;
+    displayTemplate?: string | null;
+    enabled?: boolean;
+    filter?: Record<string, unknown>;
+}): {
+    options: RelationOption[];
+    loading: boolean;
+    error: Error | null;
+};
+
+/** Stacked avatar cluster (+N) with a hover/pinnable portal roster whose rows
+ *  are UserChips — the single user-display primitive for owners/user lists.
+ *  Reused by the item-header Owners chip and the collection browser. */
+export declare function UserRosterCluster({ users, showSingleName }: {
+    users: Array<{
+        id: string;
+        name: string;
+    }>;
+    showSingleName?: boolean;
+}): React_2.JSX.Element;
+
+export declare function useSectionState(form: UseNivaroFormReturn, defaultCollapsed?: string[]): SectionState;
+
+export declare function useSendChatMessage(room: string): UseMutationResult<void, Error, string | {
+text: string;
+mentions?: string[];
+}, unknown>;
+
+export declare function useSessionRecorder(options?: SessionRecorderOptions): void;
+
+export declare function useTabState(form: UseNivaroFormReturn): TabState;
+
+export declare function useTypingIndicator(room: string | null): {
+    onType: () => void;
+    clearTyping: () => void;
+    typingText: string | null;
+};
+
+export declare function useUnreadChirp(totalUnread: number): void;
+
+export declare function useWatchFields(form: UseNivaroFormReturn, fields: string[]): Record<string, unknown>;
+
+export declare function WorkflowPanel({ collection, item }: {
+    collection: string;
+    item: string;
+}): JSX.Element | null;
+
+export { }