@object-ui/components 17.6.0 → 17.7.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/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,20 @@ 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;
+/**
+ * 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>;
 /**
  * Invalidate every cached count that involves the given object. Called by
  * mutation paths (e.g. ObjectGrid's onBulkDelete callback, drawer save) so
@@ -55,7 +47,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,6 +59,12 @@ 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;