@object-ui/components 17.6.0 → 18.0.0

package/README.md

@@ -86,15 +86,16 @@ tree-shake that import away.
 ```tsx
 import { SchemaRenderer } from '@object-ui/react'
 import { initializeComponents } from '@object-ui/components'
+import type { DeclaredNode } from '@object-ui/types'
 
 initializeComponents()
 
-const schema = {
+const schema: DeclaredNode = {
   type: 'card',
   title: 'Welcome',
-  body: {
+  children: {
     type: 'text',
-    value: 'Hello from Object UI!'
+    content: 'Hello from Object UI!'
   }
 }
 
@@ -139,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
@@ -175,6 +198,7 @@ them draw the notification's `severity` icon unless it declares an `icon`
 override naming a real Lucide icon. See the
 [notifications guide](https://objectui.org/docs/guide/notifications).
 
+<!-- doc-snippet: fragment — router-layout excerpt: `Outlet` is react-router's, supplied by the host application -->
 ```tsx
 import { NotificationBanners, NotificationAlerts } from '@object-ui/components';
 

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/button-group.d.ts

@@ -1,7 +1,7 @@
 import { VariantProps } from 'class-variance-authority';
 import { Separator } from '../ui/separator.js';
 declare const buttonGroupVariants: (props?: ({
-    orientation?: "horizontal" | "vertical" | null | undefined;
+    orientation?: "vertical" | "horizontal" | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string;
 declare function ButtonGroup({ className, orientation, ...props }: React.ComponentProps<"div"> & VariantProps<typeof buttonGroupVariants>): import("react").JSX.Element;
 declare function ButtonGroupText({ className, asChild, ...props }: React.ComponentProps<"div"> & {

package/dist/custom/combobox.d.ts

@@ -1,3 +1,4 @@
+import { ComboboxOption } from '@object-ui/types/form';
 /**
  * ObjectUI
  * Copyright (c) 2024-present ObjectStack Inc.
@@ -6,10 +7,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 import * as React from "react";
-export interface ComboboxOption {
-    value: string;
-    label: string;
-}
+export type { ComboboxOption } from '@object-ui/types/form';
 /**
  * Beyond its own named props, the combobox accepts standard button attributes
  * (`id`, `aria-*`, `data-*`, handlers, …) and forwards them to the trigger —

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/empty.d.ts

@@ -6,15 +6,27 @@ declare const emptyMediaVariants: (props?: ({
 } & import('class-variance-authority/types').ClassProp) | undefined) => string;
 declare function EmptyMedia({ className, variant, ...props }: React.ComponentProps<"div"> & VariantProps<typeof emptyMediaVariants>): import("react").JSX.Element;
 declare function EmptyTitle({ className, ...props }: React.ComponentProps<"div">): import("react").JSX.Element;
-declare function EmptyDescription({ className, ...props }: React.ComponentProps<"p">): import("react").JSX.Element;
+declare function EmptyDescription({ className, ...props }: React.ComponentProps<"div">): import("react").JSX.Element;
 declare function EmptyContent({ className, ...props }: React.ComponentProps<"div">): import("react").JSX.Element;
 /**
  * EmptyValue — universal inline placeholder for missing cell/field values.
  *
  * Use this anywhere a renderer would otherwise show "-" or "—" for a null,
- * undefined or empty value. It renders a muted, non-interactive en-dash that
- * does not inherit link/button colors from surrounding ancestors, so a missing
- * value never looks clickable.
+ * undefined or empty value. It renders a muted, non-interactive EM-dash (the
+ * `glyph` default below is U+2014, and every call site depends on that width)
+ * that does not inherit link/button colors from surrounding ancestors, so a
+ * missing value never looks clickable. This sentence said "en-dash" until
+ * objectui#8506: the word was wrong, never the code — do not "fix" the glyph
+ * to match a stale docblock.
+ *
+ * ⚠️ A caller that passes a `title` through `...props` must also pass
+ * `pointer-events-auto` in `className`. `pointer-events-none` below stops this
+ * span being a hit target, so a `title` on it never renders a tooltip — the
+ * hover falls through to whichever ancestor has one. The attribute stays in the
+ * DOM either way, which is exactly why nothing catches it: a test that reads
+ * `getAttribute('title')` is green over a tooltip that can never appear
+ * (objectui#8506, where `DetailSection` kept such a `title` and two landed pins
+ * navigate by it).
  */
 declare function EmptyValue({ className, glyph, ...props }: React.ComponentProps<"span"> & {
     glyph?: string;

package/dist/custom/field.d.ts

@@ -25,7 +25,7 @@ export interface FieldProps extends React.HTMLAttributes<HTMLDivElement>, Varian
  * A labelled form-control wrapper: label, slotted control, description, error.
  *
  * Named `FieldContainer`, not `Field` (objectstack#4115): `@objectstack/spec/data`
- * exports `Field` — an object FIELD's metadata (type, reference_to, options,
+ * exports `Field` — an object FIELD's metadata (type, reference, options,
  * permissions, …) and its builder namespace — which has nothing to do with this
  * `<div>`. Two unrelated things under one name is the defect that issue exists
  * to remove; `@object-ui/app-shell` already renamed the same kind of collision