@object-ui/components 17.6.0 → 18.0.0

package/dist/custom/navigation-overlay.d.ts

@@ -42,8 +42,35 @@ export interface NavigationOverlayProps {
     mainContent?: React.ReactNode;
     /**
      * Popover trigger element (for popover mode).
+     *
+     * Rendered through Radix's `PopoverTrigger asChild`, so it is mounted HERE,
+     * inside the overlay's own subtree. That makes it the right carrier only for
+     * a host that has no element of its own to point at — a host wanting the
+     * popover to sit on an element it already rendered elsewhere (a grid row, a
+     * tree node, a gantt bar, a kanban card, a calendar event) must use
+     * {@link NavigationOverlayProps.popoverAnchorRef}, because re-rendering that
+     * element here would draw a SECOND copy of it in the overlay rather than
+     * anchor to the first.
      */
     popoverTrigger?: React.ReactNode;
+    /**
+     * The already-rendered element the popover should be anchored to
+     * (popover mode).
+     *
+     * ⭐ This is how the five list-type renderers honour `navigation.mode:
+     * 'popover'` after objectui#9299: the click handler stores
+     * `event.currentTarget` — the row / node / bar / card / event the user
+     * actually clicked — on this ref in the same turn that opens the overlay,
+     * and the popover is positioned against it through Radix's virtual-anchor
+     * shape (`Popper.Anchor virtualRef`). No element is re-rendered, so nothing
+     * is duplicated and the renderer keeps ownership of its own DOM.
+     *
+     * When neither this nor `popoverTrigger` is supplied the overlay falls back
+     * to a compact `Dialog`. ⛔ After objectui#9299 none of the five renderers is
+     * allowed to reach that fallback — it survives only for a host that genuinely
+     * has no anchor to offer.
+     */
+    popoverAnchorRef?: React.RefObject<HTMLElement | null>;
     /**
      * Optional handler invoked when the user clicks the "Expand to full page"
      * affordance in the drawer/modal header. Mirrors Linear / Notion / Airtable
@@ -72,7 +99,85 @@ export interface NavigationOverlayProps {
      * by the `width` prop / configured ceiling.
      */
     storageKey?: string;
+    /**
+     * Retired storage key whose value is migrated into `storageKey` once
+     * (drawer mode only).
+     *
+     * ⭐ objectui#9299 item 4: there used to be TWO drag-resize implementations
+     * with two different persisted keys and two different floors —
+     * `RecordDetailDrawer`'s `objectui.drawerWidth.OBJECT` and this component's
+     * `ov:STORAGE_KEY`. They are now one implementation, and a user who had
+     * already dragged a gantt / kanban / calendar drawer to their preferred width
+     * must keep that width rather than be silently reset to the default. So the
+     * first mount that finds no value under `storageKey` adopts the value found
+     * under this key, writes it forward, and REMOVES the retired entry — which is
+     * what makes the migration one-time rather than a permanent second read: a
+     * later double-click reset must not resurrect the old width.
+     *
+     * Build it with {@link legacyRecordDrawerWidthKey} rather than spelling the
+     * prefix again at a call site.
+     */
+    legacyStorageKey?: string;
 }
+/**
+ * The one `storageKey` spelling every record overlay uses, keyed by object.
+ *
+ * `NavigationOverlay` prefixes it with `ov:` on the way to `localStorage`, so
+ * the stored key is `ov:drawer-width:OBJECT`. The console's own object page
+ * (`app-shell`'s `ObjectView`) has always used this spelling; after
+ * objectui#9299 the five list-type renderers use it too, so one object has one
+ * remembered overlay width no matter which view type the user resized it on.
+ */
+export declare function recordOverlayWidthStorageKey(objectName: string): string;
+/**
+ * The RETIRED per-object key `RecordDetailDrawer` persisted its width under
+ * before objectui#9299. Read once, migrated forward, then removed — see
+ * {@link NavigationOverlayProps.legacyStorageKey}. ⛔ Nothing writes it.
+ */
+export declare function legacyRecordDrawerWidthKey(objectName: string): string;
+/**
+ * Remember the element a click landed on, so `popover` mode can anchor to it.
+ *
+ * ⭐ objectui#9299 item 3: `popover` is anchored to the clicked element — the
+ * row, node, bar, card or event the user actually pressed. That element is
+ * rendered by the RENDERER, not by this overlay, so the overlay cannot find it
+ * on its own, and `popoverTrigger` (which MOUNTS an element of its own inside
+ * the overlay) is the wrong carrier for it — passing the row there would draw
+ * a second copy of the row instead of pointing at the first.
+ *
+ * Two carriers, same recorder. Spread `anchorCaptureProps` on the renderer's
+ * own container when the click reaches it without a DOM event (a chart, a
+ * calendar grid); call `captureAnchor(event)` directly at a click site that
+ * already HAS one (a kanban card, a tree row). Either way hand `anchorRef` to
+ * {@link NavigationOverlayProps.popoverAnchorRef}. The container form uses the
+ * capture phase deliberately: it runs before the bubbling `onClick` that opens
+ * the overlay, so by the time the popover renders the anchor is recorded.
+ *
+ * It reads `target`, not `currentTarget`, because the handler sits on the
+ * CONTAINER: `currentTarget` there is the whole view, and a popover anchored
+ * to the whole board is not anchored to anything. `target` is the deepest
+ * element under the pointer — the bar, the card, the cell — which is what the
+ * user pointed at.
+ *
+ * ⚠️ Read synchronously, which is what this does: React nulls its event fields
+ * out once the handler returns, so stashing the event rather than the element
+ * would hand the overlay a dead reference.
+ *
+ * Clicks that do not open anything (a toolbar button, a filter) also land here
+ * and are harmless: `anchorRef` is only ever read while the popover is open,
+ * and the click that opened it is by construction the last one recorded.
+ */
+export declare function useOverlayAnchor(): {
+    anchorRef: React.RefObject<HTMLElement | null>;
+    captureAnchor: (event: {
+        target?: unknown;
+    } | null | undefined) => void;
+    anchorCaptureProps: {
+        onClickCapture: (event: {
+            target?: unknown;
+        }) => void;
+    };
+};
 /**
  * NavigationOverlay — renders record detail in the configured overlay mode.
  *

package/dist/custom/refresh-indicator.d.ts

@@ -9,8 +9,14 @@ import * as React from "react";
 export interface RefreshIndicatorProps extends React.HTMLAttributes<HTMLDivElement> {
     /** Whether the indicator is active. When false, nothing is rendered. */
     active: boolean;
-    /** Accessible label. Defaults to "Refreshing". */
-    ariaLabel?: string;
+    /**
+     * Accessible name of the progress bar, rendered as its `aria-label`.
+     * Required, with no default: the caller passes a string from its own
+     * translation layer, so the name a screen reader announces is in the active
+     * locale. An English default here reached every non-English screen-reader
+     * user through the callers that passed nothing (objectui#10580).
+     */
+    ariaLabel: string;
 }
 /**
  * Thin, absolutely-positioned indeterminate progress bar that animates across

package/dist/custom/sort-builder.d.ts

@@ -26,6 +26,14 @@ export interface SortBuilderProps {
     fields?: Array<{
         value: string;
         label: string;
+        /**
+         * Listed but not choosable (objectui#11943). A disabled entry still names
+         * a row whose current field it is, so that row shows its label and can be
+         * changed or removed, but no row's dropdown lets the user pick it and
+         * "Add sort" never seeds it. "Add sort" seeds the first entry that is not
+         * disabled, and is itself disabled when every entry is.
+         */
+        disabled?: boolean;
     }>;
     value?: SortItem[];
     onChange?: (value: SortItem[]) => void;

package/dist/custom/use-horizontal-overflow.d.ts

@@ -0,0 +1,36 @@
+import * as React from 'react';
+/**
+ * The horizontal-overflow affordance every wide table shares (objectui#12708):
+ * a box that scrolls sideways says so with a right-edge shadow while columns
+ * remain to its right, and shows its scrollbar while the pointer is over it or
+ * focus is inside it. Built once, here, and used by `data-table`'s own scroll
+ * box, `ObjectGrid`'s grouped scroller and any table a page mounts itself.
+ */
+/** Whether `box` can scroll further to the right (one pixel of slack for sub-pixel layouts). */
+export declare function hasOverflowRight(box: Pick<HTMLElement, 'scrollLeft' | 'clientWidth' | 'scrollWidth'>): boolean;
+/**
+ * Track {@link hasOverflowRight} for the box `ref` points at: read in a layout
+ * effect, so the first painted frame is already right, and again on every
+ * scroll and whenever the box or its content changes size. `false` while
+ * `disabled` (the box does not scroll on its own).
+ */
+export declare function useHorizontalOverflow(ref: React.RefObject<HTMLElement | null>, { disabled }?: {
+    disabled?: boolean;
+}): boolean;
+/**
+ * Scrollbar colours for a box that scrolls: transparent until the pointer is
+ * over the box or focus is inside it, then the theme's muted foreground. The bar
+ * keeps its place, so nothing shifts when it appears. Marked important
+ * because a host may theme every scrollbar with an unlayered `*` rule (the
+ * console does), which outranks any layered utility.
+ */
+export declare const HOVER_SCROLLBAR_CLASSES = "[scrollbar-width:thin]! [scrollbar-color:transparent_transparent]! hover:[scrollbar-color:var(--color-muted-foreground)_transparent]! focus-within:[scrollbar-color:var(--color-muted-foreground)_transparent]!";
+/**
+ * Classes for a RIGHT-PINNED cell inside a {@link HorizontalOverflowBox} with
+ * `seam="pinned"`: the cell draws the shadow on its own left edge, the seam
+ * where the scrolling columns slide under it, while the box can scroll further
+ * right. Needs no measurement, because the pinned cell is where the seam is.
+ * Spelled out in full (as the edge overlay below is) so Tailwind's source scan
+ * sees every utility.
+ */
+export declare const PINNED_RIGHT_SEAM_SHADOW_CLASSES = "before:pointer-events-none before:absolute before:inset-y-0 before:right-full before:w-6 before:bg-gradient-to-l before:from-foreground/10 before:to-transparent before:opacity-0 group-data-[overflow-right=true]/hscroll:before:opacity-100";

package/dist/custom/view-states.d.ts

@@ -44,8 +44,54 @@ interface DataEmptyStateProps extends React.ComponentProps<"div"> {
     /** Optional action rendered below the description */
     action?: React.ReactNode;
 }
+/**
+ * `role` defaults to `"status"` (objectui#7132).
+ *
+ * The sibling states in this file each declare what they are — `DataLoadingState`
+ * is `role="status"`, `DataErrorState` is `role="alert"` — and the empty state
+ * alone declared nothing, so an empty box and a failed box were the same node
+ * shape to a screen reader and to any structural test. That is the exact
+ * property both the hotcrm#1212 (objectui#7063) and hotcrm#1247 (objectui#7064)
+ * rulings named first: an empty state must be *distinguishable from a load
+ * failure at a glance*.
+ *
+ * With no default, every surface that wanted the property had to type it at its
+ * own call site, and four independently did — `plugin-kanban`'s empty board,
+ * `plugin-dashboard`'s `WidgetEmptyState`, and `plugin-charts`' `ObjectChart` —
+ * while `plugin-list`, `plugin-detail`'s two timelines and the `ui:empty`
+ * renderer silently did not. Four hand-copies of one line is the per-app tax
+ * objectstack#13848 rules against, paid at the package level.
+ *
+ * It is a DEFAULT, not a fixed attribute: `role` is spread from `props` below,
+ * so a call site keeps the last word. That is what makes this change inert for
+ * the two ruled surfaces — both already pass `role="status"` explicitly and
+ * receive the identical attribute either way — and it is what lets a call site
+ * rendering something that is NOT empty say so.
+ *
+ * The call site that needed that last word was `plugin-list`'s load-failure
+ * panel, which borrowed this component for its layout. Since objectui#7143 it
+ * no longer does: `DataErrorState` grew the icon props it was missing and the
+ * panel is drawn by the component named for what it is. The default stays a
+ * default for the same reason it always was — a borrow can recur, and a fixed
+ * attribute would announce the next one as a routine status.
+ */
 declare function DataEmptyState({ className, icon, illustration, showIcon, iconWrapperClassName, title, description, action, children, ...props }: DataEmptyStateProps): React.JSX.Element;
 interface DataErrorStateProps extends React.ComponentProps<"div"> {
+    /** Icon rendered above the title */
+    icon?: React.ReactNode;
+    /**
+     * When false, the icon container is omitted entirely. Useful for
+     * banner-style failures that should not draw a glyph at all. Defaults to
+     * true.
+     */
+    showIcon?: boolean;
+    /**
+     * Override class on the icon wrapper. By default the wrapper renders as a
+     * small destructive-tinted rounded square (`size-10 rounded-lg
+     * bg-destructive/10`). Pass `""` to strip that styling and render the icon
+     * raw, or extend the look (e.g. larger size).
+     */
+    iconWrapperClassName?: string;
     title?: string;
     /** Error message or description */
     message?: string;
@@ -54,5 +100,32 @@ interface DataErrorStateProps extends React.ComponentProps<"div"> {
     /** Label for the retry button */
     retryLabel?: string;
 }
-declare function DataErrorState({ className, title, message, onRetry, retryLabel, children, ...props }: DataErrorStateProps): React.JSX.Element;
+/**
+ * `icon` / `showIcon` / `iconWrapperClassName` MIRROR `DataEmptyState` above —
+ * same names, same types, same default semantics, including
+ * `iconWrapperClassName` REPLACING the wrapper's default class rather than
+ * merging with it, so `""` renders the icon raw (objectui#7143). A second
+ * spelling of the same three ideas is the defect the mirror exists to prevent;
+ * the only intended difference is the default class the `??` falls back to,
+ * which stays this component's own destructive square.
+ *
+ * They exist because `plugin-list` rendered its load FAILURE through
+ * `DataEmptyState` — the component named for the *empty* case — for want of
+ * them: this one hardcoded its glyph, so the one panel that needed to draw a
+ * network failure differently from a permission denial could only get that from
+ * the wrong component. objectui#7132 fixed the accessibility half of that
+ * collision (`role`) and deliberately left the structural half here.
+ *
+ * Deliberately NOT mirrored: `illustration` — an empty state's product-feel hero
+ * has no failure analogue — and `action`, because this component already spells
+ * its affordance as `onRetry` / `retryLabel`, with `children` for a call site
+ * that needs to render its own control.
+ *
+ * The icon wrapper carries `data-slot="data-error-state-icon"`, mirroring the
+ * empty state's `data-empty-state-icon`. Not a prop, and not in the ruling's
+ * list of three — it is here so the wrapper `iconWrapperClassName` now governs
+ * can be named by a test and a stylesheet, and so migrating a call site off
+ * `DataEmptyState` renames that identifier instead of dropping it.
+ */
+declare function DataErrorState({ className, icon, showIcon, iconWrapperClassName, title, message, onRetry, retryLabel, children, ...props }: DataErrorStateProps): React.JSX.Element;
 export { DataLoadingState, DataEmptyState, DataEmptyState as EmptyState, DataErrorState, type DataLoadingStateProps, type DataEmptyStateProps, type DataEmptyStateProps as EmptyStateProps, type DataErrorStateProps, };

package/dist/hooks/related-count-store.d.ts

@@ -1,29 +1,14 @@
-/**
- * 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.
- *
- * Module-scoped store for related-list counts displayed in tab badges
- * (e.g. "Contacts (12)" on an Account detail). The store deduplicates
- * concurrent probes for the same key, lets the renderer subscribe with
- * `useSyncExternalStore`, and exposes invalidation hooks so other parts
- * of the runtime (bulk delete, inline create, optimistic update) can
- * keep the badges in sync without a full page refetch.
- *
- * Design notes:
- *  - One global Map keyed by `${objectName}::${relField}::${parentId}` so
- *    a count fetched by one tab strip is reused by every other consumer.
- *  - Subscribers receive *all* keyspace changes; coarse-grained but
- *    badges are cheap to re-render and avoids per-key subscription noise.
- *  - We deliberately avoid Zustand here — the surface area is one Map +
- *    an emit() — and the React binding uses the built-in
- *    `useSyncExternalStore` so we don't grow the dependency graph.
- */
+import { FieldContainerLike } from '@object-ui/core';
 interface ProbeFn {
     (objectName: string, query: {
-        $filter?: Record<string, unknown>;
+        /**
+         * The parent scope alone (a MongoDB-style object, as it always was), or
+         * — once a list declares its own scope — the ObjectQL AST node
+         * `mergeFilterNodes` lowers the pair to. Both arms are what the ROW
+         * query on the same list already sends, so this union is not a new
+         * dialect: it is the same two shapes `RelatedList` puts on the wire.
+         */
+        $filter?: Record<string, unknown> | unknown[];
         $top?: number;
         $count?: boolean;
     }): Promise<{
@@ -33,13 +18,72 @@ interface ProbeFn {
         length?: number;
     }>;
 }
-declare function getCount(objectName: string, relField: string | undefined, parentId: string | undefined): number | undefined;
-declare function setCount(objectName: string, relField: string | undefined, parentId: string | undefined, value: number): void;
+/** What one read of a related list answered: the server total and its rows. */
+interface ReadResult {
+    total: number;
+    rows: unknown[];
+}
+/**
+ * A list's own declared scope, as carried on the `record:related_list` node it
+ * badges (objectui#4664 / objectstack#7118). Two probes over the SAME
+ * (object, relField, parent) triple are different questions when their scopes
+ * differ, so it is part of the cache identity below.
+ */
+export type CountScopeFilter = Record<string, any> | any[];
+declare function getCount(objectName: string, relField: string | undefined, parentId: string | undefined, filter?: CountScopeFilter): number | undefined;
+declare function setCount(objectName: string, relField: string | undefined, parentId: string | undefined, value: number, filter?: CountScopeFilter): void;
 /**
  * Probe a count via the supplied finder. Deduplicates concurrent requests
  * for the same key and caches the resulting number until invalidated.
  */
-declare function fetchCount(probe: ProbeFn, objectName: string, relField: string | undefined, parentId: string | undefined): Promise<number>;
+declare function fetchCount(probe: ProbeFn, objectName: string, relField: string | undefined, parentId: string | undefined, filter?: CountScopeFilter, fields?: FieldContainerLike): Promise<number>;
+/**
+ * objectui#13010 — the rail card's read: the first `limit` rows of the
+ * unfiltered related list and its total. Takes the rows a badge's read holds
+ * for this card's claim, joins a read in flight that asked for enough rows, or
+ * reads itself and registers that read in flight for a badge to join.
+ * Rejects when the read fails, so the card can show its error state.
+ *
+ * One exception to the registration: when a read with too FEW rows (a badge's
+ * one-row probe) is already in flight, this card's own read is NOT registered
+ * in flight. The too-small read stays the one a badge joins, and since only the
+ * current in-flight read installs a count, the card's own read installs none:
+ * the badge's read does.
+ *
+ * Contract: held rows are a HAND-OFF, not a cache. They are taken once (the
+ * first `fetchRows` that finds them removes them; a second call reads again),
+ * and they are dropped without being taken when the child object is
+ * invalidated (`invalidate` / `invalidateAll`, and the data-change bus that
+ * calls them), when the claim is released (`releaseRows`: the card unmounts or
+ * moves to a new scope), and when the read that fetched them was overtaken by
+ * either. The total is recorded in the store as `fetch` records it. A caller
+ * that must see data newer than the record open (a refresh) does not call this.
+ */
+declare function fetchRows(probe: ProbeFn, objectName: string, relField: string, parentId: string, limit: number, fields?: FieldContainerLike): Promise<ReadResult>;
+/**
+ * objectui#13010 — a rail card says, while it renders, that it will list the
+ * first `limit` rows of this unfiltered related list. Idempotent, so a render
+ * React repeats or discards claims nothing new.
+ *
+ * Contract: a claim reads nothing by itself. While it stands, a `fetch` of the
+ * same unfiltered (object, relField, parentId) key asks for the claimed rows
+ * (the largest `limit` claimed) with its count and holds them for one
+ * `fetchRows` to take. A probe with a declared filter never meets a claim. The
+ * claim stands until `releaseRows` (unmount or new scope) or `_reset`; an
+ * invalidation drops held rows but leaves the claim.
+ */
+declare function claimRows(objectName: string, relField: string, parentId: string, limit: number): void;
+/**
+ * objectui#13010 — the rail card is gone: its claim, the rows held for it and
+ * the read it started itself are dropped, so nothing outlives the record open.
+ *
+ * Contract: call it with the key a `claimRows` named, when the card unmounts
+ * or moves to a new scope (another parent or other entries). Afterwards a
+ * `fetch` of that key asks for one row again, untaken held rows are gone, and
+ * a later `fetchRows` does not join a read the card started itself. A read a
+ * badge started stays in flight for the badges that joined it.
+ */
+declare function releaseRows(objectName: string, relField: string, parentId: string): void;
 /**
  * Invalidate every cached count that involves the given object. Called by
  * mutation paths (e.g. ObjectGrid's onBulkDelete callback, drawer save) so
@@ -55,7 +99,7 @@ declare function invalidateAll(): void;
  * (object, relField, parentId) triple. Returns `undefined` while the
  * probe is in flight or before the first request.
  */
-export declare function useRelatedCount(objectName: string | undefined, relField: string | undefined, parentId: string | undefined): number | undefined;
+export declare function useRelatedCount(objectName: string | undefined, relField: string | undefined, parentId: string | undefined, filter?: CountScopeFilter): number | undefined;
 /**
  * Subscribe to the store's monotonic version. Put it in an effect dependency
  * array to RE-RUN count probes after an invalidation (#2269) — invalidate
@@ -67,11 +111,20 @@ export declare function useRelatedCountVersion(): number;
 /**
  * Imperative store API for non-React callers (mutation handlers, tests).
  * Prefer `useRelatedCount` in components.
+ *
+ * `fetch`'s last parameter is the CHILD object's field defs. It is optional
+ * because a caller that cannot see metadata must still be able to probe — the
+ * seam then compiles the historical equality wire — but a caller that CAN see
+ * them owes them: that is the difference between a badge and no badge on a
+ * multi-value relationship (objectui#8882).
  */
 export declare const RelatedCountStore: {
     get: typeof getCount;
     set: typeof setCount;
     fetch: typeof fetchCount;
+    fetchRows: typeof fetchRows;
+    claimRows: typeof claimRows;
+    releaseRows: typeof releaseRows;
     invalidate: typeof invalidate;
     invalidateAll: typeof invalidateAll;
     _reset: () => void;