themelia-react-ui 2.0.4 → 2.0.6

package/dist/components/features/products/products.types.d.ts

@@ -174,7 +174,7 @@ export interface ProductDetailsCardProps {
     description?: ReactNode | false;
     /** Label/value facts rendered as a metadata list. */
     metadata?: MetadataListItem[];
-    /** Leading media for the card. */
+    /** Leading media; remains visible when no metadata facts are supplied. */
     media?: ReactNode;
     /** Fired when a details is edited. */
     onEditDetails?: () => void;
@@ -290,7 +290,7 @@ export interface ProductOptionValue {
 export interface ProductOptionGroup {
     /** Stable identity for this entry. */
     id: string;
-    /** Display name. */
+    /** Display name. Inline configuration requires text or a number. Use onEditOption for rich names. */
     name: ReactNode;
     /** Supporting copy shown under the label. */
     description?: ReactNode;
@@ -406,8 +406,12 @@ export interface ProductOptionsMatrixProps {
     onValueLabelChange?: (option: ProductOptionGroup, value: ProductOptionValue, label: string) => void;
     /** Fired when editing an editing option finishes. */
     onDoneEditingOption?: (option: ProductOptionGroup) => void;
-    /** Fired when an editing option is saved. */
-    onSaveEditingOption?: (option: ProductOptionGroup, draft: ProductOptionEditDraft) => void;
+    /** Saves the option draft. A Promise keeps editing locked until acceptance;
+     * rejection retains the draft, shows an error and permits retry. Legacy change
+     * and done callbacks run only after this callback succeeds. */
+    onSaveEditingOption?: (option: ProductOptionGroup, draft: ProductOptionEditDraft) => void | Promise<void>;
+    /** Receives a rejected option save after its draft has been retained. */
+    onError?: (error: unknown) => void;
     /** Fired when editing an editing option is cancelled. */
     onCancelEditingOption?: (option: ProductOptionGroup, draft: ProductOptionEditDraft) => void;
     /** Fired when an used for variants is toggled. */
@@ -749,13 +753,21 @@ export interface ProductVariantsBulkTableProps {
     /** Overrides this surface’s own copy. */
     strings?: StringsProp<ProductVariantBulkTableStrings>;
 }
-export interface ProductVariantsManagerProps extends Pick<CardProps, 'surface' | 'padding' | 'headerDivider' | 'footerDivider'>, Pick<ProductOptionsMatrixProps, 'optionGroups' | 'collapsedOptionIds' | 'defaultCollapsedOptionIds' | 'onCollapsedOptionIdsChange' | 'editingOptionId' | 'defaultEditingOptionId' | 'onEditingOptionIdChange' | 'onCreateOption' | 'onEditOption' | 'onDeleteOption' | 'onAddValue' | 'onDeleteValue' | 'onOptionNameChange' | 'onValueLabelChange' | 'onDoneEditingOption' | 'onSaveEditingOption' | 'onCancelEditingOption' | 'onToggleUsedForVariants' | 'renderOptionActions' | 'renderValue'>, Pick<ProductVariantsBulkTableProps, 'variants' | 'groupByOptionId' | 'visibleColumns' | 'optionCombinationDisplay' | 'cellDisplay' | 'selectionMode' | 'renderOptionCombination' | 'renderCell' | 'selectedVariantIds' | 'defaultSelectedVariantIds' | 'onSelectedVariantIdsChange' | 'onVariantFieldChange' | 'onVariantFieldBlur' | 'onCreateVariant' | 'onGenerateVariants' | 'onSelectVariant' | 'onEditVariant' | 'onDuplicateVariant' | 'onDeleteVariant' | 'onBulkEdit' | 'onBulkApply' | 'onBulkDelete' | 'renderVariantActions' | 'renderBulkActions'> {
+export interface ProductVariantsManagerProps extends Pick<CardProps, 'surface' | 'padding' | 'headerDivider' | 'footerDivider'>, Pick<ProductOptionsMatrixProps, 'optionGroups' | 'collapsedOptionIds' | 'defaultCollapsedOptionIds' | 'onCollapsedOptionIdsChange' | 'editingOptionId' | 'defaultEditingOptionId' | 'onEditingOptionIdChange' | 'onCreateOption' | 'onEditOption' | 'onDeleteOption' | 'onAddValue' | 'onDeleteValue' | 'onOptionNameChange' | 'onValueLabelChange' | 'onDoneEditingOption' | 'onSaveEditingOption' | 'onError' | 'onCancelEditingOption' | 'onToggleUsedForVariants' | 'renderOptionActions' | 'renderValue'>, Pick<ProductVariantsBulkTableProps, 'variants' | 'groupByOptionId' | 'visibleColumns' | 'optionCombinationDisplay' | 'cellDisplay' | 'selectionMode' | 'renderOptionCombination' | 'renderCell' | 'selectedVariantIds' | 'defaultSelectedVariantIds' | 'onSelectedVariantIdsChange' | 'onVariantFieldChange' | 'onVariantFieldBlur' | 'onCreateVariant' | 'onGenerateVariants' | 'onSelectVariant' | 'onEditVariant' | 'onDuplicateVariant' | 'onDeleteVariant' | 'onBulkEdit' | 'onBulkApply' | 'onBulkDelete' | 'renderVariantActions' | 'renderBulkActions'> {
     /** Groups rows under the values of this option. `null` leaves the list flat. */
     groupByOptionId?: string | null;
     /** Option group used for grouping on first render. */
     defaultGroupByOptionId?: string | null;
+    /**
+     * Shows the Group by control. Set `false` for a short variant list that
+     * needs no grouping chrome; rows then stay flat unless `groupByOptionId`
+     * or `defaultGroupByOptionId` names an option. @default true
+     */
+    showGroupBy?: boolean;
     onGroupByOptionIdChange?: (optionId: string | undefined, option?: ProductOptionGroup) => void;
+    /** Opens the app-owned variant search. Omitted handler hides its toolbar command. */
     onSearchVariants?: () => void;
+    /** Opens or applies app-owned filtering. Omitted handler hides its toolbar command. */
     onFilterVariants?: () => void;
     /** Content at the end of the manager's control row. */
     controlsEnd?: ReactNode;
@@ -772,7 +784,7 @@ export interface ProductVariantsManagerProps extends Pick<CardProps, 'surface' |
     variantsStrings?: ProductVariantsBulkTableProps['strings'];
 }
 export interface ProductVariantDetailsProps {
-    /** Shell treatment. */
+    /** The selected variant and its accepted summary fields. */
     variant?: ProductVariantSummary;
     /** Label/value facts rendered as a metadata list. */
     metadata?: MetadataListItem[];
@@ -823,7 +835,7 @@ export interface ProductVariantOptionField {
     id: string;
     /** Display label. */
     label: string;
-    /** Value shown beside the label. */
+    /** Fallback for an absent option value. @deprecated Set value.options or defaultValue.options on ProductVariantEditor. */
     value?: string;
     choices?: ProductChoice[];
     placeholder?: string;
@@ -842,6 +854,8 @@ export interface ProductVariantEditorValues {
     /** Options to render. */
     options?: Record<string, string | undefined>;
 }
+/** A built-in ProductVariantEditor field that `visibleFields` can hide. */
+export type ProductVariantEditorField = 'name' | 'sku' | 'description' | 'price' | 'inventory' | 'status' | 'channels';
 export interface ProductVariantEditorProps {
     /** Value shown beside the label. */
     value?: ProductVariantEditorValues;
@@ -865,6 +879,29 @@ export interface ProductVariantEditorProps {
     headerEnd?: ReactNode;
     /** Content rendered in the footer. */
     footerSlot?: ReactNode;
+    /**
+     * Which built-in fields are shown. Omitted fields default to visible; a
+     * section whose fields are all hidden is omitted with its heading.
+     */
+    visibleFields?: Partial<Record<ProductVariantEditorField, boolean>>;
+    /** Validation messages for built-in fields, shown under each and marking it invalid. */
+    errors?: Partial<Record<ProductVariantEditorField, ReactNode>>;
+    /**
+     * Id of the editor's form. Pass the same id to `ActionDrawer formId` so the
+     * drawer's footer submits it. Generated when omitted.
+     */
+    formId?: string;
+    /**
+     * Shows the editor's own title and description. Set `false` inside an
+     * overlay whose header already names the task. @default true
+     */
+    showHeader?: boolean;
+    /**
+     * App-owned fields, such as unit cost or per-location stock, rendered inside
+     * the form after the built-in sections and before the default commands.
+     * Their values, validation and submission stay with the caller.
+     */
+    children?: ReactNode;
     /** Renders the entry as unselectable. */
     disabled?: boolean;
     /** Shows the pending state and blocks repeat submissions. */
@@ -901,7 +938,7 @@ export interface ProductOverviewProps {
     quote?: ProductQuotePreviewCardProps;
     /** Policies card configuration. */
     policies?: ProductPoliciesCardProps;
-    /** Replaces individual cards in the overview. */
+    /** Inserts content at the named main and supporting-region positions. */
     slots?: ProductOverviewSlots;
     /** Merged onto the outermost node. */
     className?: string;

package/dist/components/features/questionnaire/questionnaire.types.d.ts

@@ -83,6 +83,9 @@ export interface QuestionnaireProps extends Omit<ComponentPropsWithoutRef<'form'
     /** Controlled active question key. */
     questionId?: string;
     defaultQuestionId?: string;
+    /** Fired when navigation requests a question. Takes precedence over `onQuestionChange`. */
+    onQuestionIdChange?: (id: string) => void;
+    /** Legacy alias for `onQuestionIdChange`. */
     onQuestionChange?: (id: string) => void;
     disabled?: boolean;
     /** Receives only visible, enabled questions. Respect signal to cancel application requests. */

package/dist/components/features/resource/resource.d.ts

@@ -1,8 +1,12 @@
 import type { ResourceActionBarProps, ResourceDetailsSectionProps, ResourceEmptyStateProps, ResourceHeaderProps, ResourceIndexShellProps, ResourceShowShellProps, TabbedResourceShellProps } from './resource.types';
-export declare function ResourceHeader({ title, description, eyebrow, media, avatarUrl, avatarAlt, avatarFallback, icon, iconTone, badges, metadata, actions, primaryAction, secondaryActions, moreActionsLabel, renderLink, className, contentClassName, mediaClassName, }: ResourceHeaderProps): import("react").JSX.Element;
+/** @deprecated Use Page from themelia-react-ui/layout/page; PageHeader is available for embedded headers. */
+export declare function ResourceHeader({ title, description, eyebrow, media, avatarUrl, avatarAlt, avatarFallback, icon, iconTone, badges, metadata, actions, primaryAction, secondaryActions, maxVisibleSecondaryActions, moreActionsLabel, renderLink, className, contentClassName, mediaClassName, }: ResourceHeaderProps): import("react").JSX.Element;
 export declare function ResourceActionBar({ children, leading, trailing, sticky, className }: ResourceActionBarProps): import("react").JSX.Element;
 export declare function ResourceEmptyState(props: ResourceEmptyStateProps): import("react").JSX.Element;
+/** @deprecated Use Page from themelia-react-ui/layout/page; PageHeader is available for embedded headers. */
 export declare function ResourceIndexShell(props: ResourceIndexShellProps): import("react").JSX.Element;
+/** @deprecated Use Page from themelia-react-ui/layout/page; PageHeader is available for embedded headers. */
 export declare function ResourceShowShell(props: ResourceShowShellProps): import("react").JSX.Element;
-export declare function TabbedResourceShell({ tabs, activeTab, onTabChange, tabsClassName, moreLabel, tabsAriaLabel, toolbar, slots, className, strings: stringsProp, ...props }: TabbedResourceShellProps): import("react").JSX.Element;
+/** @deprecated Use Page from themelia-react-ui/layout/page; PageHeader is available for embedded headers. */
+export declare function TabbedResourceShell({ tabs, activeTab, defaultActiveTab, onTabChange, tabsClassName, moreLabel, tabsAriaLabel, toolbar, slots, className, strings: stringsProp, ...props }: TabbedResourceShellProps): import("react").JSX.Element;
 export declare function ResourceDetailsSection({ metadata, metadataColumns, metadataDense, body, help, children, contentClassName, ...props }: ResourceDetailsSectionProps): import("react").JSX.Element;

package/dist/components/features/resource/resource.types.d.ts

@@ -33,7 +33,7 @@ export interface ResourceShellSlots {
  * menu.
  */
 export interface ResourceHeaderCommandProps {
-    /** The resource's one main command: a solid primary button, visible at every width. */
+    /** The resource's one main command: a solid primary button, in the command menu in compact headers. */
     primaryAction?: PageHeaderAction;
     /**
      * Supporting commands in priority order. The first two render as outline
@@ -41,11 +41,19 @@ export interface ResourceHeaderCommandProps {
      * command, move into the More actions menu, which always closes the row.
      */
     secondaryActions?: readonly PageHeaderAction[];
+    /**
+     * How many routine secondary commands render as outline buttons on wide
+     * headers; later ones join the More actions menu. Use `1` or `0` when long
+     * labels beside the primary command would crowd the header; `Infinity`
+     * keeps every routine command inline. @default 2
+     */
+    maxVisibleSecondaryActions?: number;
     /** Accessible name of the More actions menu trigger. Default: `'More actions'`. */
     moreActionsLabel?: string;
     /** Renders `href` commands as framework links. Defaults to a native anchor. */
     renderLink?: PageHeaderLinkRenderer;
 }
+/** @deprecated Use PageProps or PageHeaderProps from themelia-react-ui/layout/page. */
 export interface ResourceIndexShellProps extends ResourceHeaderCommandProps {
     /** Primary workspace content. Replaced by loading, error, or empty state when active. */
     children?: ReactNode;
@@ -82,10 +90,12 @@ export interface ResourceIndexShellProps extends ResourceHeaderCommandProps {
     /** Copy overrides for loading, empty, error, retry, and tab labels. */
     strings?: StringsProp<ResourceStrings>;
 }
+/** @deprecated Use PageProps or PageHeaderProps from themelia-react-ui/layout/page. */
 export interface ResourceShowShellProps extends ResourceIndexShellProps {
     /** Class name for `slots.aside`. */
     asideClassName?: string;
 }
+/** @deprecated Use PageProps or PageHeaderProps from themelia-react-ui/layout/page. */
 export interface ResourceHeaderProps extends ResourceHeaderCommandProps {
     /** Primary resource identity. */
     title: ReactNode;
@@ -172,11 +182,14 @@ export interface ResourceDetailsSectionProps extends ResourceSectionFrameProps {
     /** Quiet guidance rendered after the section content. */
     help?: ReactNode;
 }
+/** @deprecated Use PageProps or PageHeaderProps from themelia-react-ui/layout/page. */
 export interface TabbedResourceShellProps extends ResourceShowShellProps {
     /** Workspace tabs, including optional overflow metadata. */
     tabs: OverflowTabItem[];
     /** Controlled active tab identifier. */
     activeTab?: string;
+    /** Initial tab identifier when the shell manages selection. `activeTab` takes precedence. */
+    defaultActiveTab?: string;
     /** Called when a visible or overflow tab is selected. */
     onTabChange?: (id: string) => void;
     /** Class name for the overflow tab bar. */

package/dist/components/features/rich-text-editor/form-rich-text-editor.d.ts

@@ -3,4 +3,4 @@ export interface FormRichTextEditorProps extends Omit<RichTextEditorProps, 'valu
     /** Form field name, forwarded for native submits. */
     name: string;
 }
-export declare function FormRichTextEditor({ name, ...props }: FormRichTextEditorProps): import("react").JSX.Element;
+export declare function FormRichTextEditor({ name, className, disabled, invalid, onBlur, ...props }: FormRichTextEditorProps): import("react").JSX.Element;

package/dist/components/features/rich-text-editor/partials/caret-helpers.d.ts

@@ -24,5 +24,5 @@ export declare function readCaretContext(): RichTextCaretContext | null;
  * range with the chip atomically — no manual text-content mutation, no
  * timing races between "delete" and "insert".
  */
-export declare function replaceBeforeCaret(editor: TiptapEditor | null, length: number, html: string, notifyChange: (next: string) => void): void;
+export declare function replaceBeforeCaret(editor: TiptapEditor | null, length: number, html: string, notifyChange?: (next: string) => void): void;
 export declare function insertHtmlIntoEditable(editable: HTMLElement | null, html: string): void;

package/dist/components/features/rich-text-editor/partials/editor-field-aria.d.ts

@@ -0,0 +1,14 @@
+export declare function editorFieldAria(label: string, listboxId?: string, activeOptionId?: string): {
+    readonly role: "textbox";
+    readonly 'aria-label': string;
+    readonly 'aria-multiline': "true";
+} | {
+    readonly 'aria-activedescendant'?: string | undefined;
+    readonly role: "combobox";
+    readonly 'aria-label': string;
+    readonly 'aria-expanded': "true";
+    readonly 'aria-haspopup': "listbox";
+    readonly 'aria-autocomplete': "list";
+    readonly 'aria-controls': string;
+    readonly 'aria-multiline'?: undefined;
+};

package/dist/components/features/rich-text-editor/partials/image-uploads.d.ts

@@ -5,7 +5,7 @@ export declare const DEFAULT_IMAGE_ACCEPT = "image/png,image/jpeg,image/gif,imag
 /** Marks an upload placeholder in the editing surface; never part of the value. */
 export declare const UPLOAD_ATTRIBUTE = "data-rte-upload";
 /** The placeholder occupies a line of its own while its image uploads. */
-export declare const UPLOAD_PLACEHOLDER_CLASS = "rich-text-editor--upload my-space-xs flex min-h-control items-center rounded-inner border border-dashed border-input bg-muted/30 px-row-x py-row-y";
+export declare const UPLOAD_PLACEHOLDER_CLASS = "rich-text-editor--upload my-space-xs flex min-h-control items-center rounded-radius border border-dashed border-input bg-muted/30 px-row-x py-row-y";
 /** Removes upload placeholders from serialized editor HTML. */
 export declare function stripUploadPlaceholders(html: string): string;
 export declare function acceptsImageFile(file: File, accept: string): boolean;

package/dist/components/features/rich-text-editor/partials/rich-text-editor-toolbar.d.ts

@@ -6,6 +6,8 @@ export interface RichTextEditorToolbarProps {
     buttons: ToolbarButtonConfig[];
     /** Additional controls appended to the toolbar. */
     extraToolbarItems?: ReadonlyArray<RichTextEditorToolbarItem>;
+    /** Active values read from the editor's transaction subscription. */
+    extraToolbarActive?: readonly boolean[];
     /** Hides the control that switches to HTML source. */
     hideSourceToggle?: boolean;
     /** Whether the editor is currently showing HTML source. */
@@ -27,7 +29,7 @@ export interface RichTextEditorToolbarProps {
     /** Merged onto the outermost node. */
     className?: string;
 }
-export declare function RichTextEditorToolbar({ buttons, extraToolbarItems, hideSourceToggle, sourceMode, toggleSourceMode, disabled, hasEditor, toolbarTrailing, strings, className, }: RichTextEditorToolbarProps): import("react").JSX.Element;
+export declare function RichTextEditorToolbar({ buttons, extraToolbarItems, extraToolbarActive, hideSourceToggle, sourceMode, toggleSourceMode, disabled, hasEditor, toolbarTrailing, strings, className, }: RichTextEditorToolbarProps): import("react").JSX.Element;
 export declare namespace RichTextEditorToolbar {
     var displayName: string;
 }

package/dist/components/features/rich-text-editor/rich-text-editor.recipes.d.ts

@@ -1,7 +1,17 @@
-/** Shared field anatomy for rich editors, including specialized document schemas. */
+/**
+ * Shared field anatomy for rich editors, including specialized document schemas.
+ * Every region takes the toolbar's `surface-xs` inset, on both axes for the body,
+ * so the first line sits as far below the toolbar rule as text sits from the frame edge.
+ */
 export declare const richTextEditorRecipes: {
     readonly source: string;
-    readonly frame: "min-w-0 overflow-hidden border-input bg-background rounded-inner border";
+    /** Editable body: shared content typography inside the editor's surface inset. Every embedded editor uses it. */
+    readonly editable: string;
+    /** Placeholder overlay, laid over the editable body at the same inset. */
+    readonly placeholder: "pointer-events-none absolute inset-0 p-surface-xs";
+    /** Inline inset for the regions under the body (image details, counts, footer slot). */
+    readonly regionX: "px-surface-xs";
+    readonly frame: string;
     readonly disabled: "opacity-50";
     readonly disabledControl: "disabled:opacity-100 aria-disabled:opacity-100";
     readonly content: "h-full [&_.ProseMirror]:h-full [&_.ProseMirror]:min-h-full [&_.ProseMirror]:outline-none";

package/dist/components/features/rich-text-editor/rich-text-editor.types.d.ts

@@ -1,5 +1,6 @@
-import type { ComponentType, ReactNode } from 'react';
+import type { ComponentType, FocusEventHandler, ReactNode } from 'react';
 import type * as TiptapReact from '@tiptap/react';
+import type { FieldControlAttributes } from '../../../lib/field-control-attributes';
 import type { StringsProp } from '../../../lib/strings';
 import type { RichTextImageRendering } from '../../typography/rich-text';
 import type { RichTextEditorStrings } from './rich-text-editor.strings';
@@ -94,11 +95,15 @@ export interface RichTextEditorImages extends RichTextImageRendering {
 }
 /** Body floor roles for the rich text editor. */
 export type RichTextEditorBodyHeight = 'control' | 'field' | 'document';
-export interface RichTextEditorProps {
+export interface RichTextEditorProps extends FieldControlAttributes {
     /** Editor content as HTML. Controlled. */
     value: string;
-    /** Fired with the next value. */
+    /** Reports the document HTML. Source edits commit when switching back to rich text. */
     onValueChange: (html: string) => void;
+    /** Includes the committed HTML under this name in native form submissions. */
+    name?: string;
+    /** Runs when focus leaves the editor and its toolbar. */
+    onBlur?: FocusEventHandler<HTMLElement>;
     /** Shown while the document is empty. */
     placeholder?: string;
     /** Tightens the toolbar and body for inline use. */
@@ -115,6 +120,8 @@ export interface RichTextEditorProps {
     maxHeight?: string;
     /** Renders the entry as unselectable. */
     disabled?: boolean;
+    /** Marks the editable field invalid and applies the shared field state. */
+    invalid?: boolean;
     /** Show character and word counts in a footer bar. */
     showCounts?: boolean;
     /** Optional character limit — displayed as "X / max" when showCounts is true. */
@@ -137,6 +144,13 @@ export interface RichTextEditorProps {
      * comment composer to detect `@`-style trigger characters.
      */
     onCaretChange?: () => void;
+    /** Consumes an editable-body key before the editor handles it. Return true to handle the key. */
+    onEditorKeyDown?: (event: KeyboardEvent) => boolean;
+    /** Associates the editable body with an open inline completion listbox. */
+    suggestionPopup?: {
+        listboxId: string;
+        activeOptionId?: string;
+    };
     /** Per-instance string overrides (deep-merged over `defaultRichTextEditorStrings`). */
     strings?: StringsProp<RichTextEditorStrings>;
     /**

package/dist/components/features/schema-form/hooks/use-schema-form.d.ts

@@ -15,9 +15,13 @@ export interface UseSchemaFormResult extends SchemaFormSubmitHelpers {
     errors: SchemaFormErrors;
     getFieldError: (key: string) => string | undefined;
     getFieldValue: (key: string) => SchemaFormValue;
+    /** Reads the latest values, including writes made in the current event. */
+    getValues: () => SchemaFormValues;
     setFieldValue: (key: string, value: SchemaFormValue) => void;
     setValues: (values: SchemaFormValues) => void;
+    /** Registers a field editor's current parse validity with form validation. */
+    setFieldParseValidity: (key: string, valid: boolean) => void;
     reset: () => SchemaFormValues;
     validate: () => boolean;
 }
-export declare function useSchemaForm({ fields, value, defaultValue, errors: externalErrors, onValueChange, onFieldChange, formatRequiredError, validationError, onError, }: UseSchemaFormOptions): UseSchemaFormResult;
+export declare function useSchemaForm(options: UseSchemaFormOptions): UseSchemaFormResult;

package/dist/components/features/schema-form/partials/schema-form-field.d.ts

@@ -5,8 +5,10 @@ export interface SchemaFormFieldRendererProps extends SchemaFormFieldContext {
     strings: SchemaFormStrings;
     /** Merged onto the outermost node. */
     className?: string;
+    /** Reports whether the JSON editor can parse its current draft. */
+    onParseValidityChange?: (key: string, valid: boolean) => void;
 }
-export declare function SchemaFormFieldRenderer({ field, value, values, error, disabled, required, fieldId, onValueChange, onError, strings, className, }: SchemaFormFieldRendererProps): import("react").JSX.Element;
+export declare function SchemaFormFieldRenderer({ field, value, values, error, disabled, required, fieldId, onValueChange, onError, strings, className, onParseValidityChange, }: SchemaFormFieldRendererProps): import("react").JSX.Element;
 export declare namespace SchemaFormFieldRenderer {
     var displayName: string;
 }

package/dist/components/features/schema-form/schema-form.utils.d.ts

@@ -10,7 +10,7 @@ export declare function toStringValue(value: SchemaFormValue): string;
 export declare function toStringArray(value: SchemaFormValue): string[];
 export declare function toBooleanValue(value: SchemaFormValue): boolean;
 export declare function parseNumberValue(rawValue: string, integer?: boolean): number | null;
-export declare function formatJsonValue(value: SchemaFormValue, indent?: number): string;
+export declare function formatJsonValue(value: SchemaFormValue, indent?: number, quoteString?: boolean): string;
 export declare function parseJsonValue(rawValue: string): {
     value: SchemaFormValue;
     valid: boolean;

package/dist/components/features/suggestions/suggestions.types.d.ts

@@ -68,7 +68,7 @@ export interface SuggestionsComboboxProps<T> extends UseSuggestionsConfig<T> {
     renderError?: (context: SuggestionsErrorRenderContext) => ReactNode;
     /** Shows a control that clears the current selection. */
     allowClear?: boolean;
-    /** Resets the query when the list closes without a selection. */
+    /** Resets the query when a results list closes. Failed queries remain available to retry. */
     clearInputOnClose?: boolean;
     /** Renders the entry as unselectable. */
     disabled?: boolean;

package/dist/components/features/table/data-table.d.ts

@@ -1,6 +1,6 @@
 export declare function useDataTableSize(): 'xs' | 'sm';
 import { type DataTableProps } from './table.types';
-export declare function DataTable<TData extends object, TValue = unknown>({ size, surface, headerTransparent, columns, data, columnGroups, rowActions, rowActionsMenuLabel, rowActionsDisplayMode, rowActionsBreakpoint, enableSorting, enableResizing, enableFiltering, filterColumn, filterPlaceholder, manualSorting, enableColumnVisibility, fullscreen: controlledFullscreen, defaultFullscreen, onFullscreenChange, showFullscreenToggle, enableRowSelection, enableMultiRowSelection, enableSubRowSelection, pagination, pageQueryKey, onPageChange, onSortingChange, onColumnFiltersChange, onRowClick, onRowSelectionChange, stickyHeader, stickyToolbar, stickyFirstColumn, maxBodyHeight, fillAvailableHeight, emptyStateMessage, emptyStateAction, className, rowClassName, cellClassName, headerClassName, wrapperClassName, innerClassName, tableContainerClassName, getRowId, rowSelection: controlledRowSelection, sorting: controlledSorting, defaultSorting, columnVisibility: controlledColumnVisibility, defaultColumnVisibility, initialState, onColumnVisibilityChange, strings: stringsOverride, topbarContent, topbarEnd, topbarClassName, toolbarLabelVisibility, footerContent, selectionToolbar, bulkActions, selectionToolbarClassName, selectionToolbarPlacement, totalRowCount: totalRowCountProp, storageKey, }: DataTableProps<TData, TValue>): import("react").JSX.Element;
+export declare function DataTable<TData extends object, TValue = unknown>({ size, surface, headerTransparent, columns, data, loading, loadingRows, columnGroups, rowActions, rowActionsMenuLabel, rowActionsDisplayMode, rowActionsBreakpoint, enableSorting, enableResizing, enableFiltering, filterColumn, filterPlaceholder, manualSorting, enableColumnVisibility, fullscreen: controlledFullscreen, defaultFullscreen, onFullscreenChange, showFullscreenToggle, enableRowSelection, enableMultiRowSelection, enableSubRowSelection, pagination, pageQueryKey, onPageChange, onSortingChange, onColumnFiltersChange, onRowClick, onRowSelectionChange, stickyHeader, stickyToolbar, stickyFirstColumn, maxBodyHeight, fillAvailableHeight, emptyStateMessage, emptyStateAction, className, rowClassName, cellClassName, headerClassName, wrapperClassName, innerClassName, tableContainerClassName, getRowId, rowSelection: controlledRowSelection, sorting: controlledSorting, defaultSorting, columnVisibility: controlledColumnVisibility, defaultColumnVisibility, initialState, onColumnVisibilityChange, strings: stringsOverride, topbarContent, topbarEnd, topbarClassName, toolbarLabelVisibility, footerContent, selectionToolbar, bulkActions, selectionToolbarClassName, selectionToolbarPlacement, totalRowCount: totalRowCountProp, storageKey, }: DataTableProps<TData, TValue>): import("react").JSX.Element;
 export declare namespace DataTable {
     var displayName: string;
 }

package/dist/components/features/table/index.d.ts

@@ -9,6 +9,7 @@ export { DataTableToolbar } from './table-toolbar';
 export { CellValue, CellStack, type CellStackProps, type CellStackValue, type CellValueDescriptor, type CellValueKind, type CellValueProps, type CellValueTuple, type PrimitiveCellValue, } from './partials/cell-value';
 export { TableLink, type TableLinkProps } from './partials/table-link';
 export { StatusCell, type StatusCellEntry, type StatusCellProps, StatusClusterCell, type StatusClusterCellItem, type StatusClusterCellProps, DateCell, type DateCellProps, DateMetaCell, type DateMetaCellProps, CurrencyCell, type CurrencyCellProps, AvatarCell, type AvatarCellProps, ResourceCell, type ResourceCellBadge, type ResourceCellLinkProps, type ResourceCellMetadataItem, type ResourceCellProps, } from './partials/cell-renderers';
+export type { ColumnDef } from '@tanstack/react-table';
 export * from './table.types';
 export { defaultDataTableStrings, mergeDataTableStrings } from './table.strings';
 export { handleRowSelectionChange, handleSortingChange, handleColumnVisibilityChange, getRowClassName, getCellClassName, getSelectedRowsData, createRowSelectionCheckbox, createHeaderSelectionCheckbox, addSelectionColumn, } from './table-helpers';

package/dist/components/features/table/partials/resource-cell.d.ts

@@ -1,5 +1,5 @@
 import type { ComponentType, ReactNode } from 'react';
-import { type LucideIcon } from 'lucide-react';
+import type { LucideIcon } from 'lucide-react';
 import { type BadgeTone } from '../../../base/badge';
 export interface ResourceCellMetadataItem {
     /** Stable identity for this entry. */
@@ -32,13 +32,24 @@ export interface ResourceCellProps {
     metadata?: ReactNode | readonly ResourceCellMetadataItem[];
     /** Status chips shown after the title. */
     badges?: readonly ResourceCellBadge[];
-    /** Thumbnail source. Falls back to `icon`, then `fallback`, when absent or broken. */
+    /**
+     * Thumbnail source. When it is absent or fails to load, the circle shows
+     * `fallback`, then `icon`, then the title's initials.
+     */
     imageUrl?: string;
-    /** Leading glyph. */
+    /** Leading glyph in the media circle. Pass one only when it identifies the resource. */
     icon?: ComponentType<{
         className?: string;
     }>;
-    /** Media shown when neither `imageUrl` nor `icon` resolves — usually initials. */
+    /**
+     * Media shown when `imageUrl` is absent or fails — usually
+     * `<Initials value={name} />` for a person or organization.
+     *
+     * The cell draws its media circle only when `imageUrl`, `icon` or
+     * `fallback` is supplied, so identifiers such as orders and invoices read
+     * as plain text with no decorative monogram. In a person column where only
+     * some rows have a photo, pass `fallback` on every row so titles align.
+     */
     fallback?: ReactNode;
     /** Destination for the entry, when it navigates. */
     href?: string;
@@ -48,6 +59,12 @@ export interface ResourceCellProps {
     emptyLabel?: ReactNode;
     /** Merged onto the outermost node. */
     className?: string;
+    /**
+     * `circle` for people and organizations; `square` (the default radius) for
+     * product photos and documents, so square images are not clipped.
+     * @default 'circle'
+     */
+    mediaShape?: 'circle' | 'square';
     /** Merged onto the media. */
     mediaClassName?: string;
     /** Merged onto the content. */
@@ -57,7 +74,7 @@ export interface ResourceCellProps {
     /** Merged onto the subtitle. */
     subtitleClassName?: string;
 }
-export declare function ResourceCell({ title, subtitle, metadata, badges, imageUrl, icon: IconComponent, fallback, href, renderLink, emptyLabel, className, mediaClassName, contentClassName, titleClassName, subtitleClassName, }: ResourceCellProps): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react").JSX.Element | null | undefined;
+export declare function ResourceCell({ title, subtitle, metadata, badges, imageUrl, icon: IconComponent, fallback, href, renderLink, emptyLabel, className, mediaShape, mediaClassName, contentClassName, titleClassName, subtitleClassName, }: ResourceCellProps): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react").JSX.Element | null | undefined;
 export declare namespace ResourceCell {
     var displayName: string;
 }

package/dist/components/features/table/table-body.d.ts

@@ -1,5 +1,5 @@
 import { type DataTableBodyProps } from './table.types';
-export declare function DataTableBody<TData>({ table, onRowClick, emptyStateMessage, emptyStateAction, cellClassName, rowClassName, stickyFirstColumn, striped, strings, }: DataTableBodyProps<TData>): import("react").JSX.Element;
+export declare function DataTableBody<TData>({ loading, loadingRows, table, onRowClick, emptyStateMessage, emptyStateAction, cellClassName, rowClassName, stickyFirstColumn, striped, strings, }: DataTableBodyProps<TData>): import("react").JSX.Element;
 export declare namespace DataTableBody {
     var displayName: string;
 }

package/dist/components/features/table/table-helpers.d.ts

@@ -1,6 +1,11 @@
 import type { SortingState, RowSelectionState, VisibilityState, Table, Row, Updater, ColumnDef } from '@tanstack/react-table';
 import React from 'react';
 import type { DataTableStrings } from './table.types';
+export interface GeneratedColumnOptions<TData> {
+    strings: DataTableStrings;
+    renderActions?: (row: TData) => React.ReactNode;
+}
+export declare function getGeneratedColumnOptions<TData>(table: Table<TData>): GeneratedColumnOptions<TData> | undefined;
 /**
  * Helper function for handling row selection changes with OnChangeFn compatibility
  */
@@ -33,7 +38,5 @@ export declare const createRowSelectionCheckbox: <TData>(row: Row<TData>, string
  * Create header selection checkbox
  */
 export declare const createHeaderSelectionCheckbox: <TData>(table: Table<TData>, strings?: DataTableStrings) => React.JSX.Element;
-/**
- * Add selection column to columns
- */
+/** Prepends the checkbox selection column. Explicit strings override table defaults. */
 export declare const addSelectionColumn: <TData, TValue = unknown>(columns: ColumnDef<TData, TValue>[], strings?: DataTableStrings) => ColumnDef<TData, TValue>[];

package/dist/components/features/table/table.strings.d.ts

@@ -1,5 +1,8 @@
 import { type DataTableStrings, type DataTableStringsOverride } from './table.types';
 export declare const defaultDataTableStrings: {
+    loading: {
+        label: string;
+    };
     emptyState: {
         message: string;
         ariaLabel: string;

package/dist/components/features/table/table.types.d.ts

@@ -72,6 +72,10 @@ export interface DataTablePaginationStrings extends ExistingRequiredPaginationLa
     to: string;
 }
 export interface DataTableStrings {
+    /** Copy announced while the table body is loading. Optional for existing dictionaries. */
+    loading?: {
+        label: string;
+    };
     /** Shown in place of the collection when it has no entries. */
     emptyState: {
         message: string;
@@ -128,6 +132,7 @@ export interface DataTableStrings {
     };
 }
 export type DataTableStringsOverride = Partial<{
+    loading: Partial<NonNullable<DataTableStrings['loading']>>;
     /** Shown in place of the collection when it has no entries. */
     emptyState: Partial<DataTableStrings['emptyState']>;
     /** Overflow menu for the surface as a whole. */
@@ -171,7 +176,9 @@ export interface DataTableToolbarProps<TData> {
 }
 export interface DataTableSelectionToolbarContext<TData extends object> {
     table: Table<TData>;
+    /** Selected records available in the current `data` prop. */
     selectedRows: TData[];
+    /** Number of selected IDs, including selections outside the current page. */
     selectedRowCount: number;
     /** `totalRowCount` when supplied, else `pagination.total`, else the rows in `data`. */
     totalRowCount: number;
@@ -190,7 +197,7 @@ export type DataTableSize = ComponentScale;
  *
  * - `card` (default): rounded card with `border-border bg-card` and a
  *   soft shadow — the canonical admin treatment.
- * - `glass`: a hairline `border-border/60 rounded-radius` outline with no
+ * - `glass`: a hairline `border-border/60 rounded-surface` outline with no
  *   shadow and no card background — pairs with consumer-supplied
  *   surrounding chrome (e.g. dropping into an existing SmartCard).
  *   Background remains transparent so a glassy parent shows
@@ -221,7 +228,8 @@ export interface DataTableProps<TData extends object, TValue> {
      * 1. Regular array: `columns={myColumns}`
      * 2. Tuple pattern with auto-memoization: `columns={[getColumns(t, actions), [t, actions]]}`
      *
-     * The tuple pattern eliminates the need for manual useMemo on the page level.
+     * The tuple keeps its definitions until the dependencies change. Include
+     * every value read by the definitions, including their cell callbacks.
      *
      * @example
      * // Pattern 1: Regular (requires manual memoization)
@@ -235,6 +243,10 @@ export interface DataTableProps<TData extends object, TValue> {
     columns: ColumnDef<TData, TValue>[] | [ColumnDef<TData, TValue>[], React.DependencyList];
     /** Records to render. */
     data: TData[];
+    /** Replaces body rows with placeholders while preserving headers and table state. */
+    loading?: boolean;
+    /** Number of placeholder rows while loading. Defaults to 6, capped at 20. */
+    loadingRows?: number;
     /** Banded headers spanning several columns, drawn above the header row. */
     columnGroups?: ColumnGroup[];
     /** Enables column sorting. */
@@ -485,6 +497,10 @@ export interface DataTableActionsProps<TData> {
     strings?: DataTableStrings;
 }
 export interface DataTableBodyProps<TData> {
+    /** Replaces the body with non-interactive shared Skeleton rows. */
+    loading?: boolean;
+    /** Number of placeholder rows. Defaults to 6, capped at 20. */
+    loadingRows?: number;
     /** The table instance from `useReactTable`, supplied by `DataTable`. */
     table: Table<TData>;
     /** Fired when a row is activated. */