@object-ui/components 17.7.0 → 18.0.0

package/README.md

@@ -140,6 +140,28 @@ function MyComponent() {
 - `tabs` - Tab navigation
 - `accordion` - Collapsible sections
 
+#### Page region posture — `usePageRegionPosture()`
+
+The page renderer measures each region of a page against the page body, using
+`ResizeObserver` on the region, not the viewport, and tells the region's blocks
+how much room they have:
+
+```ts
+import { usePageRegionPosture, type PageRegionPosture } from '@object-ui/components';
+
+const posture: PageRegionPosture | null = usePageRegionPosture(); // 'compact' | 'full' | null
+```
+
+- `'compact'`: the region is narrower than `(page − 24) / 2`, that is, half
+  the page less the 24 px gap between regions side by side. A half-and-half
+  cell therefore stays `'full'`.
+- `'full'`: the region is half the page or wider.
+- `null`: outside a page region, or before the width is known (server render,
+  no `ResizeObserver`). Read `null` as `'full'`.
+
+The posture is measured, never authored, and no schema key sets it. The
+`list-view` block in `@object-ui/plugin-list` reads it to draw a compact list.
+
 ### Data Display
 - `table` - Data table
 - `list` - List view

package/dist/custom/RecordTitleChip.d.ts

@@ -8,13 +8,14 @@ export interface RecordTitleChipProps {
     objectLabel?: string;
     /** Record identifier shown next to the object label with a copy button. */
     resourceId?: string;
-    /** Hide the favourite star (default: shown). */
-    showStar?: boolean;
     /** Hide the copy-id button (default: shown when `resourceId` is given). */
     showCopyId?: boolean;
     /** Controlled favourite state. When omitted, the chip manages its own. */
     isFavorite?: boolean;
-    /** Called when the favourite star is toggled. */
+    /**
+     * Called when the favourite star is toggled. The star draws exactly when
+     * this is given: a star with nothing to call would store nothing.
+     */
     onToggleFavorite?: (next: boolean) => void;
     /** Extra classes for the outer flex column. */
     className?: string;

package/dist/custom/dialog-viewport-gutter.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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.
+ */
+/**
+ * The ONE viewport gutter every wide centred dialog reads from `sm` up
+ * (objectui#12593, promoted to a shared export by objectui#12603).
+ *
+ * The `DialogContent` primitive draws `w-full max-w-lg`. A consumer that raises
+ * the cap with `sm:max-w-2xl` or wider makes the dialog exactly as wide as any
+ * window narrower than that cap, at x = 0, edge to edge. With this class the
+ * dialog is the smaller of its max width and the window less 2rem, and the
+ * primitive's `left-[50%]` plus `translate-x-[-50%]` centres it with an equal
+ * 1rem either side. Above the max width plus 2rem the dialog is exactly as wide
+ * as before.
+ *
+ * `100%`, not `100vw`: the dialog is `fixed`, so `100%` is its containing
+ * block, the viewport less any classic scrollbar, the same box `left-[50%]`
+ * centres in. `100vw` counts the scrollbar, so each gutter would lose half of
+ * the scrollbar's width.
+ *
+ * `sm:` only: below `sm` a dialog is the phone sheet, which this leaves alone.
+ * A dialog that keeps its own viewport-relative cap (`sm:max-w-[95vw]
+ * sm:w-full`, the `full` size) does not read it.
+ *
+ * The class string is literal here so Tailwind's source scan emits it; an app
+ * that `@source`-scans this package gets the rule. A site writes its wide cap
+ * and this constant together (`` `sm:max-w-5xl ${DIALOG_VIEWPORT_GUTTER}` ``,
+ * or the constant as an unconditional `cn()` argument), never a gutter literal
+ * of its own. The census
+ * `packages/components/src/__tests__/dialogViewportGutterCensus-12603.test.ts`
+ * enumerates every wide `DialogContent` and fails one that does not.
+ */
+export declare const DIALOG_VIEWPORT_GUTTER = "sm:w-[calc(100%-2rem)]";

package/dist/custom/empty-state-link.d.ts

@@ -0,0 +1,63 @@
+import { EmptyState } from '@objectstack/spec/ui';
+/**
+ * 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.
+ */
+/**
+ * The one link an empty state names (objectui#12270).
+ *
+ * `@objectstack/spec`'s `EmptyStateSchema` declares an optional `link`,
+ * `{ label, url }`: the one next step an empty list names, such as the how-to
+ * page that explains what belongs here. The shape is taken by reference, so the
+ * link reaches every empty state that shape reaches, and each of them draws it
+ * through this component, ⛔ never a copy of its own:
+ *
+ * - a list view's `emptyState`, drawn by `@object-ui/plugin-list`'s `ListView`;
+ * - a list page's own `interfaceConfig.emptyState`, which that page hands the
+ *   same `ListView`;
+ * - the `object-grid` block's `emptyState`, drawn by `@object-ui/plugin-grid`'s
+ *   `ObjectGrid`.
+ *
+ * ## The click is the action runner's
+ *
+ * The link is followed as a `type: 'url'` action through the ActionRunner, so
+ * what a click may open is the runner's `classifyNavigationTarget` answer, the
+ * one answer every navigator in the app asks (ruling A+ on objectui#12191).
+ * ⛔ No scheme test lives here. An in-app path goes through the host's router,
+ * in place. An `http(s)://` address opens as the runner opens any external
+ * target. `mailto:` opens the mail client in place. Any other value is refused
+ * by the runner at the click, which reports its refusal (an error toast under
+ * the console's provider) and navigates nowhere. The spec judges the url at
+ * parse, except a template that opens with `${…}`, which it says is judged when
+ * it is clicked, after interpolation: the runner's click is that judgement, so
+ * nothing is judged here at render.
+ *
+ * Following a link is not feedback-worthy, so it raises no success toast, as
+ * the html tier's anchor and the dashboard's header link raise none.
+ *
+ * ## Without an ActionProvider
+ *
+ * `useAction()` then hands over a local runner with no navigation or toast
+ * handler. That runner hands an admitted in-app path back as `redirect`
+ * instead of navigating, and reports a refusal to nobody, so this component
+ * follows the redirect with a page navigation and logs the refusal.
+ */
+import * as React from 'react';
+/** The spec's empty-state link, `{ label, url }` (`EmptyStateSchema.link`). */
+export type EmptyStateLinkSpec = NonNullable<EmptyState['link']>;
+export interface EmptyStateLinkProps {
+    /** The authored `emptyState.link`. Absent, nothing is drawn. */
+    link?: EmptyStateLinkSpec;
+    /**
+     * The locale the `label` is resolved against when it is an inline locale
+     * map: the one the caller resolves the empty state's `title` and `message`
+     * against. A label that resolves to no text draws nothing.
+     */
+    displayLocale: string;
+    className?: string;
+    'data-testid'?: string;
+}
+export declare function EmptyStateLink({ link, displayLocale, className, 'data-testid': testId, }: EmptyStateLinkProps): React.JSX.Element | null;

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

@@ -17,11 +17,10 @@ import * as React from "react";
  * and `operator` here is the builder's own dropdown vocabulary
  * (`FILTER_BUILDER_OPERATORS`), not the spec's `$`-tokens.
  *
- * DERIVED from `@object-ui/types`, never declared a second time (objectui#9306,
- * which settles objectui#6349's two parked name-authority rows). That declaration is
- * the one name authority for the row; this one takes every member from it
- * (`id`, required since objectui#8415, and `field`) and restates exactly two,
- * each a named extension:
+ * DERIVED from `@object-ui/types`' `FilterBuilderCondition` (objectui#9306).
+ * That declaration is the one name authority for the row; this one takes every
+ * member from it (`id`, required since objectui#8415, and `field`) and restates
+ * exactly two, each a named extension:
  *
  *   - `operator` — {@link FilterBuilderOperator}: the protocol's ids, which is
  *     what the authority declares, plus the opt-in `exists` / `notExists` the
@@ -33,15 +32,25 @@ import * as React from "react";
  *     below that takes a row's value (`reshapeFilterValue`, `retypeFilterValue`,
  *     `narrowFilterValueToOptions`, …) is typed on this member, so `any` here
  *     would switch their checking off in silence.
+ *
+ * Its own NAME, not the authority's (objectui#6349, batch 12). Under the
+ * authority's name this was a second declaration of `FilterBuilderCondition`
+ * with a different shape: the two are assignable in neither direction (the
+ * operator blocks one way, the value's requiredness the other), so an
+ * auto-import picked one of two rows by package. `FilterBuilderCondition` now
+ * means the authored row in `@object-ui/types` only, and this specialisation
+ * is named for the builder that edits it.
  */
-export interface FilterBuilderCondition extends Omit<AuthoredFilterBuilderCondition, "operator" | "value"> {
+export interface FilterBuilderRow extends Omit<AuthoredFilterBuilderCondition, "operator" | "value"> {
     operator: FilterBuilderOperator;
     value: string | number | boolean | (string | number | boolean)[];
 }
 /**
  * The group the FilterBuilder edits: one `logic` over FLAT rows.
  *
- * DERIVED from `@object-ui/types` like the row above (objectui#9306). Only
+ * DERIVED from `@object-ui/types`' `FilterGroup` like the row above
+ * (objectui#9306), and named apart from it for the same reason
+ * (objectui#6349, batch 12): `FilterGroup` means the authored group only. Only
  * `conditions` is restated, to hold THIS package's row; `id` and `logic` are
  * the authority's own. So `id` is OPTIONAL here, as it is there: nothing in
  * this builder reads a group's `id`, `onChange` hands back whatever group the
@@ -53,8 +62,8 @@ export interface FilterBuilderCondition extends Omit<AuthoredFilterBuilderCondit
  * and has no control that creates a group. The authority retired nested
  * sub-groups in the same change and its zod mirror refuses one by name.
  */
-export interface FilterGroup extends Omit<AuthoredFilterGroup, "conditions"> {
-    conditions: FilterBuilderCondition[];
+export interface FilterBuilderRowGroup extends Omit<AuthoredFilterGroup, "conditions"> {
+    conditions: FilterBuilderRow[];
 }
 export interface FilterBuilderProps {
     fields?: Array<{
@@ -72,8 +81,8 @@ export interface FilterBuilderProps {
         /** ID field on the referenced object (defaults to "id") */
         idField?: string;
     }>;
-    value?: FilterGroup;
-    onChange?: (value: FilterGroup) => void;
+    value?: FilterBuilderRowGroup;
+    onChange?: (value: FilterBuilderRowGroup) => void;
     className?: string;
     showClearAll?: boolean;
     /**
@@ -298,7 +307,7 @@ export declare function filterValueArity(operator: string): FilterValueArity;
  *
  * @internal exported for tests
  */
-export declare function reshapeFilterValue(value: FilterBuilderCondition["value"], nextOperator: string): FilterBuilderCondition["value"];
+export declare function reshapeFilterValue(value: FilterBuilderRow["value"], nextOperator: string): FilterBuilderRow["value"];
 /**
  * The operator a row keeps after its FIELD is changed, given the operators the
  * NEW field offers (objectui#4768).
@@ -428,7 +437,7 @@ export declare function mountedOperatorValue(operator: string, offeredOperators:
  *
  * @internal exported for tests
  */
-export declare function retypeFilterValue(value: FilterBuilderCondition["value"], fieldType: string | undefined, operator: string): FilterBuilderCondition["value"];
+export declare function retypeFilterValue(value: FilterBuilderRow["value"], fieldType: string | undefined, operator: string): FilterBuilderRow["value"];
 /** The shape of a `fields` entry that the option-domain helpers below read. */
 type OptionBearingField = {
     type?: string;
@@ -476,7 +485,7 @@ type OptionBearingField = {
  *
  * @internal exported for tests
  */
-export declare function narrowFilterValueToOptions(value: FilterBuilderCondition["value"], field: OptionBearingField | undefined, operator: string): FilterBuilderCondition["value"];
+export declare function narrowFilterValueToOptions(value: FilterBuilderRow["value"], field: OptionBearingField | undefined, operator: string): FilterBuilderRow["value"];
 /**
  * Is this row's value FINISHED for the operator it carries — the arity-aware
  * reading of "the user has filled this in" (objectstack#8815).
@@ -528,10 +537,17 @@ export declare function narrowFilterValueToOptions(value: FilterBuilderCondition
  *
  * @internal exported for tests
  */
-export declare function isFilterValueComplete(operator: string, value: FilterBuilderCondition["value"] | undefined | null): boolean;
+export declare function isFilterValueComplete(operator: string, value: FilterBuilderRow["value"] | undefined | null): boolean;
 /**
- * The operators the dropdown offers for a field of `fieldType`, given the
- * opt-in ids this instance was granted.
+ * The operators a row on a field of `fieldType` can HOLD, given the opt-in ids
+ * this instance was granted — every operator the dropdown can draw for it.
+ *
+ * What the dropdown OFFERS a fresh choice is this set minus the nullness pair
+ * on a type that cannot tell "empty" from "null" (objectui#11810, see
+ * {@link offeredOperatorsForRow}). That narrowing is deliberately NOT applied
+ * here: callers outside this file (`app-shell`'s dataset read-back,
+ * `plugin-list`'s parity pin) ask "can the builder hold this row", and a
+ * stored `is_null` on a `select` column still can.
  *
  * A pure function rather than a closure so the selection rule — and above all
  * the {@link OPT_IN_OPERATORS} gate, whose whole job is to keep an operator OFF
@@ -557,9 +573,9 @@ interface LookupValuePickerProps {
         displayField?: string;
         idField?: string;
     };
-    value: FilterBuilderCondition["value"];
+    value: FilterBuilderRow["value"];
     multiple: boolean;
-    onChange: (value: FilterBuilderCondition["value"]) => void;
+    onChange: (value: FilterBuilderRow["value"]) => void;
 }
 declare function LookupValuePicker({ field, value, multiple, onChange }: LookupValuePickerProps): React.JSX.Element;
 export { FilterBuilder, LookupValuePicker };

package/dist/custom/grouping-editor.d.ts

@@ -47,5 +47,9 @@ export interface GroupingEditorProps {
  * Field options are filtered per row so a field can only appear in one level
  * at a time. The current row's selected field stays in its own dropdown so the
  * user sees the active selection.
+ *
+ * The field selector is the shared `Select` primitive, the control the Filter
+ * and Sort panels beside this one pick a field with, so the three panels look
+ * and behave alike (objectui#11865). It used to be a browser-native `<select>`.
  */
 export declare function GroupingEditor({ value, onChange, fieldOptions, maxLevels, className, labels, }: GroupingEditorProps): React.JSX.Element;

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

@@ -0,0 +1,18 @@
+import * as React from 'react';
+export interface HorizontalOverflowBoxProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Where the shadow is drawn: `edge` (default) overlays the box's right edge;
+     * `pinned` leaves it to the right-pinned cells inside, which carry
+     * `PINNED_RIGHT_SEAM_SHADOW_CLASSES` (`./use-horizontal-overflow`).
+     */
+    seam?: 'edge' | 'pinned';
+    /** Classes for the positioned wrapper around the scrolling box. */
+    outerClassName?: string;
+}
+/**
+ * A horizontally scrolling box with the shared overflow affordance. The
+ * scrolling element is the inner `div` (`className`, the ref and every other
+ * prop land on it); the edge shadow is its sibling, so it never scrolls away
+ * with the content.
+ */
+export declare const HorizontalOverflowBox: React.ForwardRefExoticComponent<HorizontalOverflowBoxProps & React.RefAttributes<HTMLDivElement>>;

package/dist/custom/index.d.ts

@@ -24,4 +24,8 @@ export * from './shimmer-skeleton.js';
 export * from './RecordTitleChip.js';
 export * from './refresh-indicator.js';
 export * from './view-states.js';
+export * from './empty-state-link.js';
 export * from './mobile-dialog-content.js';
+export * from './dialog-viewport-gutter.js';
+export { HorizontalOverflowBox, type HorizontalOverflowBoxProps } from './horizontal-overflow.js';
+export { PINNED_RIGHT_SEAM_SHADOW_CLASSES } from './use-horizontal-overflow.js';

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/hooks/related-count-store.d.ts

@@ -18,6 +18,11 @@ interface ProbeFn {
         length?: number;
     }>;
 }
+/** 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
@@ -32,6 +37,53 @@ declare function setCount(objectName: string, relField: string | undefined, pare
  * for the same key and caches the resulting number until invalidated.
  */
 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
@@ -70,6 +122,9 @@ 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;