themelia-react-ui 1.0.2 → 2.0.0

package/dist/components/blocks/commerce/discount-stack/types.d.ts

@@ -5,7 +5,7 @@ export interface Discount {
     /** Display label. */
     label: string;
     amount: string;
-    /** Chip rendered beside the label. */
+    /** Tone of the type chip. Discount types are kinds, so pass `neutral` unless the chip states a status. */
     badge: BadgeTone;
 }
 export interface DiscountStackStrings {

package/dist/components/blocks/commerce/inventory-section/types.d.ts

@@ -36,7 +36,10 @@ export interface InventorySectionMetric {
     value: string;
     /** Supporting copy shown under the label. */
     description?: string;
-    /** Semantic tone driving the entry's colour. */
+    /**
+     * Semantic tone of the entry. Not rendered by the summary: stats are plain
+     * and the title badge carries the stock state. Kept for type compatibility.
+     */
     tone?: 'default' | 'success' | 'warning' | 'error' | 'info';
 }
 export interface InventorySectionStrings {

package/dist/components/blocks/commerce/loyalty-points/types.d.ts

@@ -20,7 +20,7 @@ export interface LoyaltyPointsProps {
     balance: number | string;
     /** Membership tier name. Defaults to `strings.tier`. */
     tier?: string;
-    /** Badge tone for the tier chip. @default 'warning' */
+    /** Badge tone for the tier chip. A tier is a kind, not a status. @default 'neutral' */
     tierTone?: BadgeTone;
     /** Recent point movements. */
     history?: LoyaltyHistoryEntry[];

package/dist/components/blocks/commerce/order-status/types.d.ts

@@ -11,9 +11,13 @@ export interface OrderStatusEvent {
 export interface OrderStatusStrings {
     /** Surface title. */
     title: string;
+    /** Not rendered: the title badge states the status. Kept for existing overrides. */
     statusLabel: string;
+    /** Label of the delivery-estimate fact. */
     eta: string;
+    /** Not rendered: the timeline shows the latest event. Kept for existing overrides. */
     latestEvent: string;
+    /** Not rendered: the timeline marks the current step. Kept for existing overrides. */
     currentStep: string;
 }
 export declare const defaultOrderStatusStrings: OrderStatusStrings;

package/dist/components/blocks/commerce/payment-method/payment-method.d.ts

@@ -1,5 +1,5 @@
 import { type PaymentMethodProps } from './types';
-export declare function PaymentMethod({ brand, last4, expiry, holderName, default: defaultMethod, onChange, className, strings: stringsProp, }: PaymentMethodProps): import("react").JSX.Element;
+export declare function PaymentMethod({ brand, last4, expiry, holderName, default: defaultMethod, onChange, surface, padding, headerDivider, className, strings: stringsProp, }: PaymentMethodProps): import("react").JSX.Element;
 export declare namespace PaymentMethod {
     var displayName: string;
 }

package/dist/components/blocks/commerce/payment-method/types.d.ts

@@ -1,3 +1,4 @@
+import type { CardProps } from '../../../base/cards';
 import type { StringsProp } from '../../../../lib/strings';
 export type PaymentBrand = 'visa' | 'mastercard' | 'amex' | 'paypal' | 'applepay' | 'googlepay' | 'unknown';
 export interface PaymentMethodStrings {
@@ -9,7 +10,8 @@ export interface PaymentMethodStrings {
     change: string;
 }
 export declare const defaultPaymentMethodStrings: PaymentMethodStrings;
-export interface PaymentMethodProps {
+/** Unframed by default. Set surface="card" to let this owner frame its heading and body. */
+export interface PaymentMethodProps extends Pick<CardProps, 'surface' | 'padding' | 'headerDivider'> {
     /** Card network or wallet. */
     brand: PaymentBrand;
     /** Last four digits, the only card number this component accepts. */

package/dist/components/blocks/commerce/seo-listing/seo-listing-card.d.ts

@@ -1,5 +1,5 @@
 import { type SeoListingCardProps } from './types';
-export declare function SeoListingCard({ siteName, baseUrl, pathSegments, permalink, title, description, price, keyword, score, limits, showChecks, onEdit, className, strings: stringsProp, }: SeoListingCardProps): import("react").JSX.Element;
+export declare function SeoListingCard({ siteName, baseUrl, pathSegments, permalink, title, description, price, keyword, score, limits, showChecks, onEdit, surface, padding, headerDivider, className, strings: stringsProp, }: SeoListingCardProps): import("react").JSX.Element;
 export declare namespace SeoListingCard {
     var displayName: string;
 }

package/dist/components/blocks/commerce/seo-listing/types.d.ts

@@ -1,4 +1,5 @@
 import type { ReactNode } from 'react';
+import type { CardProps } from '../../../base/cards';
 import type { StringsProp } from '../../../../lib/strings';
 export type SeoListingCheckId = 'title' | 'description' | 'permalink' | 'slug' | 'url' | 'keyword';
 export type SeoListingCheckStatus = 'good' | 'review' | 'missing';
@@ -60,7 +61,8 @@ export interface SeoListingCardStrings {
     checkHints: Record<SeoListingCheckId, string>;
 }
 export declare const defaultSeoListingCardStrings: SeoListingCardStrings;
-export interface SeoListingCardProps {
+/** Unframed by default. Set surface="card" to let this owner frame its heading and body. */
+export interface SeoListingCardProps extends Pick<CardProps, 'surface' | 'padding' | 'headerDivider'> {
     /** Site name shown in the search preview. */
     siteName?: string;
     /** Origin the permalink is built on. */

package/dist/components/blocks/commerce/vendor-profile/types.d.ts

@@ -76,7 +76,10 @@ export interface VendorProfileCardProps {
     onMessage?: () => void;
     /** Shows the engagement action and delegates its behavior to the consumer. */
     onHire?: () => void;
-    /** Card surface override. Defaults through the shared SmartCard configuration. */
+    /**
+     * Card surface override. Defaults through the shared SmartCard configuration.
+     * `flat` also drops the dossier's own insets, so the embedding surface owns them.
+     */
     surface?: SmartCardSurface;
     /** Card density override. Defaults through the shared SmartCard configuration. */
     /** Additional classes applied to the outer SmartCard element. */

package/dist/components/blocks/data-display/dense-info-card/dense-info.strings.d.ts

@@ -1,6 +1,9 @@
 export interface DenseInfoStrings {
     /** Total number of records across all pages. */
     total: string;
+    /** Word after the task count ("12/20 tasks"). */
     tasks: string;
+    /** Word after the priority value ("High priority"). Additive, so optional for existing dictionaries. */
+    priority?: string;
 }
-export declare const defaultDenseInfoStrings: DenseInfoStrings;
+export declare const defaultDenseInfoStrings: Required<DenseInfoStrings>;

package/dist/components/blocks/data-display/inline-stat/inline-stat.d.ts

@@ -6,7 +6,10 @@
  *  - `inline`: label sits immediately before the value, separator-style.
  *  - `stacked`: label above (xs secondary), value below (md).
  *
- * `mono` toggles `tabular-nums` on the value side for amounts and counters.
+ * `mono` switches the value to the monospace identifier role (references,
+ * codes, keys). Amounts, counts, percentages and dates stay in the sans UI
+ * font: pass `valueClassName="tabular-nums"` (or a value primitive such as
+ * `Money` / `Percent`, which are already tabular) when figures should align.
  * Use `valueClassName` for one-off colour/weight overrides; the surrounding
  * row is intentionally plain so consumers can stack many of these without
  * visual clutter.

package/dist/components/features/global-search/partials/global-search-idle-state.d.ts

@@ -3,7 +3,7 @@ import type { GlobalSearchIdleSection } from '../global-search.types';
 export interface GlobalSearchIdleStateProps {
     /** Sections to render, in display order. */
     sections: ReadonlyArray<GlobalSearchIdleSection>;
-    /** Optional override for the heading icon when missing on a section. */
+    /** Optional heading icon used when a section supplies none. Headings carry no icon by default. */
     fallbackIcons?: {
         recent?: React.ElementType;
         suggestions?: React.ElementType;

package/dist/components/features/overlays/alert-dialog.d.ts

@@ -1,4 +1,4 @@
 import type { ConfirmDialogProps } from './overlays.types';
-declare function ConfirmDialogImpl({ open, onOpenChange, onClose, children, title, description, visuallyHideHeader, className, contentClassName, initialFocusRef, closeOnEscape, strings: customStrings, showCancel, showConfirm, onCancel, onConfirm, onAsyncConfirm, onError, closeOnAsyncComplete, confirmTone, confirmStyle, loading, formId, footer, tone, showIcon, alertMessage, trigger, destructive, }: ConfirmDialogProps): import("react").JSX.Element;
+declare function ConfirmDialogImpl({ open, onOpenChange, onClose, children, title, description, visuallyHideHeader, className, contentClassName, surfaceStyle, initialFocusRef, closeOnEscape, strings: customStrings, showCancel, showConfirm, onCancel, onConfirm, onAsyncConfirm, onError, closeOnAsyncComplete, confirmTone, confirmStyle, loading, formId, footer, tone, showIcon, alertMessage, trigger, destructive, }: ConfirmDialogProps): import("react").JSX.Element;
 export declare const ConfirmDialog: import("react").MemoExoticComponent<typeof ConfirmDialogImpl>;
 export {};

package/dist/components/features/overlays/drawer.d.ts

@@ -1,4 +1,4 @@
 import type { ActionDrawerProps } from './overlays.types';
-declare function ActionDrawerImpl({ open, onOpenChange, onClose, children, title, description, visuallyHideHeader, showCloseButton, className, contentClassName, initialFocusRef, closeOnEscape, closeOnBackdropClick, strings: customStrings, showCancel, showConfirm, onCancel, onConfirm, onAsyncConfirm, onError, closeOnAsyncComplete, confirmTone, confirmStyle, loading, formId, footer, emphasis, tone, showIcon, alertMessage, direction, width, showFooter, modal, trigger, }: ActionDrawerProps): import("react").JSX.Element;
+declare function ActionDrawerImpl({ open, onOpenChange, onClose, children, title, description, visuallyHideHeader, showCloseButton, className, contentClassName, surfaceStyle, initialFocusRef, closeOnEscape, closeOnBackdropClick, strings: customStrings, showCancel, showConfirm, onCancel, onConfirm, onAsyncConfirm, onError, closeOnAsyncComplete, confirmTone, confirmStyle, loading, formId, footer, emphasis, tone, showIcon, alertMessage, direction, width, showFooter, modal, trigger, }: ActionDrawerProps): import("react").JSX.Element;
 export declare const ActionDrawer: import("react").MemoExoticComponent<typeof ActionDrawerImpl>;
 export {};

package/dist/components/features/overlays/hooks/use-overlay-actions.d.ts

@@ -7,8 +7,8 @@ export interface UseOverlayActionsOptions extends Pick<OverlayActionProps, 'onCo
     customStrings?: StringsProp<OverlayStrings>;
     emphasis?: boolean;
     tone?: OverlayTone;
-    /** Called when `onAsyncConfirm` throws. Library DEV-logs the error;
-     *  consumer wires telemetry. */
+    /** Called when `onAsyncConfirm` throws; the consumer reports or retries.
+     *  Without it the library logs the rejection in development only. */
     onError?: (error: unknown) => void;
 }
 export interface UseOverlayActionsReturn {

package/dist/components/features/overlays/hooks/use-overlay-visibility.d.ts

@@ -1,17 +1,21 @@
 import { type Dispatch, type SetStateAction } from 'react';
 export type OverlayOpenSetter = Dispatch<SetStateAction<boolean>>;
 export interface OverlayVisibilityProps {
+    /** Current visibility. */
     open: boolean;
-    /** Fired when a change is opened. */
+    /** Requests a visibility change; spread both onto an overlay. */
     onOpenChange: (open: boolean) => void;
 }
 export interface UseOverlayVisibilityOptions {
+    /** Initial visibility when uncontrolled. Default: `false`. */
     defaultOpen?: boolean;
+    /** Controlled visibility. Omit to let the hook own it. */
     open?: boolean;
-    /** Fired when a change is opened. */
+    /** Fired once for every actual visibility change. */
     onOpenChange?: (open: boolean) => void;
-    /** Fired when an entry is opened. */
+    /** Fired after a change to open. */
     onOpen?: () => void;
+    /** Fired after a change to closed, whatever dismissed the overlay. */
     onClose?: () => void;
 }
 export interface UseOverlayVisibilityReturn {
@@ -25,10 +29,13 @@ export interface UseOverlayVisibilityReturn {
 }
 export type OverlayVisibilityGroupState<TKey extends string = string> = Record<TKey, boolean>;
 export interface UseOverlayVisibilityGroupOptions<TKey extends string = string> {
+    /** Initial visibility per key when uncontrolled. */
     defaultOpen?: Partial<Record<TKey, boolean>>;
+    /** Controlled visibility per key. */
     open?: Partial<Record<TKey, boolean>>;
-    /** Fired when a change is opened. */
+    /** Fired once for every actual change, with the key, its visibility and the next group state. */
     onOpenChange?: (key: TKey, open: boolean, state: OverlayVisibilityGroupState<TKey>) => void;
+    /** Opening one key closes the others, for one-at-a-time overlays. Default: `false`. */
     closeOthersOnOpen?: boolean;
 }
 export type UseOverlayVisibilityGroupReturn<TKey extends string = string> = Record<TKey, UseOverlayVisibilityReturn>;

package/dist/components/features/overlays/overlay-tone-icon.d.ts

@@ -0,0 +1,37 @@
+import type { OverlayTone } from './overlays.types';
+/** One glyph and colour per tone, shared by every overlay's opt-in `showIcon`. */
+export declare const overlayToneGlyphs: {
+    readonly neutral: {
+        readonly Glyph: import("lucide-react").LucideIcon;
+        readonly color: "text-muted-foreground";
+        readonly surface: "bg-muted";
+    };
+    readonly destructive: {
+        readonly Glyph: import("lucide-react").LucideIcon;
+        readonly color: "text-destructive";
+        readonly surface: "bg-destructive/10";
+    };
+    readonly warning: {
+        readonly Glyph: import("lucide-react").LucideIcon;
+        readonly color: "text-warning-accent";
+        readonly surface: "bg-warning/15";
+    };
+    readonly info: {
+        readonly Glyph: import("lucide-react").LucideIcon;
+        readonly color: "text-info";
+        readonly surface: "bg-info/15";
+    };
+    readonly success: {
+        readonly Glyph: import("lucide-react").LucideIcon;
+        readonly color: "text-success";
+        readonly surface: "bg-success/15";
+    };
+};
+/**
+ * Inline tone glyph for a heading row. The wrapper takes the title's own line
+ * box (base size, snug leading, `h-lh`), so the glyph centres on the first title
+ * line at any density instead of relying on an optical offset.
+ */
+export declare function OverlayToneIcon({ tone }: {
+    tone: OverlayTone;
+}): import("react").JSX.Element;

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

@@ -34,7 +34,9 @@ export interface OverlayBaseProps {
     /**
      * Renders the corner dismiss control. Default: `true`. Set `false` for
      * overlays whose body is the whole surface — a command palette has nowhere
-     * to put a floating X without it landing on the content.
+     * to put a floating X without it landing on the content. Keep another
+     * visible way to dismiss (a cancel action) so touch screen-reader users can
+     * leave the overlay.
      */
     showCloseButton?: boolean;
     /**
@@ -43,11 +45,15 @@ export interface OverlayBaseProps {
      * on the dialog itself, which no className can express.
      */
     surfaceStyle?: CSSProperties;
-    /** Element to focus on open, instead of the first tabbable node. */
-    initialFocusRef?: RefObject<HTMLElement>;
-    /** Allows Escape to dismiss. Set `false` for destructive or in-progress work. */
+    /**
+     * Element to focus on open, instead of the first tabbable node (the first
+     * field or action; the corner dismiss control comes last). Accepts a
+     * `useRef<HTMLInputElement>(null)` ref directly.
+     */
+    initialFocusRef?: RefObject<HTMLElement | null>;
+    /** Allows Escape to dismiss. Default: `true`. Set `false` for destructive or in-progress work. */
     closeOnEscape?: boolean;
-    /** Allows a backdrop click to dismiss. */
+    /** Allows a backdrop click to dismiss. Default: `true`. */
     closeOnBackdropClick?: boolean;
     /** Overrides the overlay's own copy (confirm/cancel labels). */
     strings?: StringsProp<OverlayStrings>;
@@ -100,37 +106,46 @@ export interface OverlayActionProps {
      * `onSubmit` owns the outcome — `onConfirm` and `onAsyncConfirm` do not fire.
      */
     formId?: string;
-    /** Replaces the generated footer; the consumer owns its action states. Pending dismissal protection still applies. */
+    /**
+     * Replaces the generated footer; the consumer owns its action states.
+     * Pending dismissal protection still applies. Custom actions that close the
+     * overlay use controlled visibility (`useOverlayVisibility`).
+     */
     footer?: ReactNode;
 }
 /** Semantic weight — the header icon and the confirm button's tone. */
 export interface OverlayEmphasisProps {
     /**
-     * Lets `tone` drive the header icon and the confirm button colour. Without
-     * it the tone is presentational only and `confirmTone` decides the button.
+     * Lets `tone` decide the confirm button colour (destructive, warning or
+     * success). Without it `confirmTone` decides the button. Default: `false`.
      */
     emphasis?: boolean;
-    /** Semantic tone of the overlay. Default: `'neutral'`. */
+    /** Semantic tone of the overlay: the `showIcon` glyph and the `alertMessage` notice. Default: `'neutral'`. */
     tone?: OverlayTone;
-    /** Shows the tone's icon beside the title. */
+    /** Shows the tone's glyph beside the title, centred on its first line. Default: `false`. */
     showIcon?: boolean;
     /** Inline notice between the header and the body — a warning or consequence. */
     alertMessage?: string;
 }
 /** A modal dialog with a title, body, and generated action footer. */
 export interface ActionDialogProps extends OverlayBaseProps, OverlayActionProps, OverlayEmphasisProps {
-    /** Maximum dialog width. Default: `md`. */
+    /** Maximum dialog width from the `sm` breakpoint; below it the dialog keeps a 1rem viewport margin. Default: `lg`. */
     size?: OverlaySize;
-    /** Element that opens the dialog. Supply it for uncontrolled use instead of `open`. */
+    /** Element that opens the dialog. Supply it for uncontrolled use instead of `open`; a string renders a secondary button. */
     trigger?: ReactNode;
 }
 /** An edge-anchored panel for longer work than a dialog comfortably holds. */
 export interface ActionDrawerProps extends OverlayBaseProps, OverlayActionProps, OverlayEmphasisProps {
     /** Edge the drawer enters from. Default: `right`. */
     direction?: DrawerDirection;
-    /** Panel measurement along its opening axis — width for left/right, height for top/bottom. */
+    /**
+     * Maximum panel width for left and right drawers from the `sm` breakpoint;
+     * below it the panel spans the viewport. Top and bottom drawers span the
+     * width and size to their content up to 85% of the viewport height.
+     * Default: `lg`.
+     */
     width?: OverlaySize;
-    /** Renders the action footer. Set `false` when the body owns its own actions. */
+    /** Renders the action footer. Default: `true`. Set `false` when the body owns its own actions. */
     showFooter?: boolean;
     /**
      * Whether the drawer takes the page hostage while it is open. Default: `true`.
@@ -140,7 +155,8 @@ export interface ActionDrawerProps extends OverlayBaseProps, OverlayActionProps,
      * Some side panels are the opposite: a theme editor, an inspector, a live
      * filter rail, anything whose whole purpose is to sit beside the app while
      * you keep working in it. Those need `false`, which drops the scrim and the
-     * inerting and leaves the page interactive.
+     * inerting and leaves the page interactive; pressing the page no longer
+     * dismisses the panel, which closes from its own controls or Escape.
      *
      * `'trap-focus'` is the middle setting — focus stays inside, but the page
      * neither locks its scroll nor stops taking pointer events.
@@ -149,7 +165,7 @@ export interface ActionDrawerProps extends OverlayBaseProps, OverlayActionProps,
      * confirmation or anything the user must answer before continuing.
      */
     modal?: boolean | 'trap-focus';
-    /** Element that opens the drawer. Supply it for uncontrolled use instead of `open`. */
+    /** Element that opens the drawer. Supply it for uncontrolled use instead of `open`; a string renders a secondary button. */
     trigger?: ReactNode;
 }
 /**
@@ -157,14 +173,21 @@ export interface ActionDrawerProps extends OverlayBaseProps, OverlayActionProps,
  * body needs real content — this one is sized for a question and two answers.
  */
 export interface ConfirmDialogProps extends OverlayBaseProps, OverlayActionProps {
-    /** Semantic tone, driving the icon and confirm button. Default: `'neutral'`. */
+    /** Semantic tone, driving the confirm button, the `showIcon` glyph and the notice. Default: `'neutral'`. */
     tone?: OverlayTone;
-    /** Shows the tone's icon beside the title. */
+    /** Shows the tone's glyph above the title. Default: `false`; the confirm button and copy carry the tone. */
     showIcon?: boolean;
     /** Inline notice explaining the consequence before the user commits. */
     alertMessage?: string;
-    /** Element that opens the dialog. Supply it for uncontrolled use instead of `open`. */
+    /** Element that opens the dialog. Supply it for uncontrolled use instead of `open`; a string renders a secondary button. */
     trigger?: ReactNode;
     /** Shorthand for the destructive presentation. */
     destructive?: boolean;
+    /**
+     * Not used: a confirmation needs an explicit answer, so an outside press
+     * never dismisses it. Escape still cancels unless `closeOnEscape` is `false`.
+     */
+    closeOnBackdropClick?: boolean;
+    /** Not used: a confirmation has no corner dismiss control; Cancel or Escape declines. */
+    showCloseButton?: boolean;
 }

package/dist/components/features/products/components/product-variants-manager.d.ts

@@ -1,5 +1,5 @@
 import type { ProductVariantsManagerProps } from '../products.types';
-export declare function ProductVariantsManager({ optionGroups, variants, visibleColumns, optionCombinationDisplay, cellDisplay, selectionMode, renderOptionCombination, renderCell, selectedVariantIds, defaultSelectedVariantIds, onSelectedVariantIdsChange, onVariantFieldChange, onVariantFieldBlur, collapsedOptionIds, defaultCollapsedOptionIds, onCollapsedOptionIdsChange, editingOptionId, defaultEditingOptionId, onEditingOptionIdChange, onCreateOption, onEditOption, onDeleteOption, onAddValue, onDeleteValue, onOptionNameChange, onValueLabelChange, onDoneEditingOption, onSaveEditingOption, onCancelEditingOption, onToggleUsedForVariants, renderOptionActions, renderValue, onCreateVariant, onGenerateVariants, onSelectVariant, onEditVariant, onDuplicateVariant, onDeleteVariant, onBulkEdit, onBulkApply, onBulkDelete, renderVariantActions, renderBulkActions, groupByOptionId, defaultGroupByOptionId, onGroupByOptionIdChange, onSearchVariants, onFilterVariants, controlsEnd, actions, headerEnd, footerSlot, className, strings: stringsProp, optionsStrings, variantsStrings, }: ProductVariantsManagerProps): import("react").JSX.Element;
+export declare function ProductVariantsManager({ optionGroups, variants, visibleColumns, optionCombinationDisplay, cellDisplay, selectionMode, renderOptionCombination, renderCell, selectedVariantIds, defaultSelectedVariantIds, onSelectedVariantIdsChange, onVariantFieldChange, onVariantFieldBlur, collapsedOptionIds, defaultCollapsedOptionIds, onCollapsedOptionIdsChange, editingOptionId, defaultEditingOptionId, onEditingOptionIdChange, onCreateOption, onEditOption, onDeleteOption, onAddValue, onDeleteValue, onOptionNameChange, onValueLabelChange, onDoneEditingOption, onSaveEditingOption, onCancelEditingOption, onToggleUsedForVariants, renderOptionActions, renderValue, onCreateVariant, onGenerateVariants, onSelectVariant, onEditVariant, onDuplicateVariant, onDeleteVariant, onBulkEdit, onBulkApply, onBulkDelete, renderVariantActions, renderBulkActions, groupByOptionId, defaultGroupByOptionId, onGroupByOptionIdChange, onSearchVariants, onFilterVariants, controlsEnd, actions, headerEnd, footerSlot, surface, padding, headerDivider, footerDivider, className, strings: stringsProp, optionsStrings, variantsStrings, }: ProductVariantsManagerProps): import("react").JSX.Element;
 export declare namespace ProductVariantsManager {
     var displayName: string;
 }

package/dist/components/features/products/partials/index.d.ts

@@ -2,6 +2,6 @@ export { ProductRowActions } from './product-actions';
 export { ProductEmptyState } from './product-empty-state';
 export { ProductMetricTile } from './product-metric-tile';
 export { ProductOperationRow, ProductReadinessRow, ProductStructureMetricRow, ProductSummaryRow, } from './product-rows';
-export { PRODUCT_TONE_BADGE, PRODUCT_TONE_SURFACE, ProductToneDot, clampProductPercent, } from './product-tone';
+export { PRODUCT_TONE_BADGE, PRODUCT_TONE_TEXT, ProductToneDot, clampProductPercent, isProductStatusTone, } from './product-tone';
 export { ProductVariantActions, ProductVariantCell, } from './product-variant-table-parts';
 export { PRODUCT_EMPTY_VALUE } from './product-values';

package/dist/components/features/products/partials/product-metric-tile.d.ts

@@ -1,4 +1,10 @@
 import type { ProductMetricSummary, ProductStructureMetric } from '../products.types';
+/**
+ * A headline fact: label above an emphasised value, in the same label-over-value
+ * anatomy as the metadata lists beside it. No tile chrome — the parent grid's
+ * gap separates metrics — and colour appears only as a status dot when the
+ * metric's tone states a status.
+ */
 export declare function ProductMetricTile({ metric }: {
     metric: ProductStructureMetric | ProductMetricSummary;
 }): import("react").JSX.Element;

package/dist/components/features/products/partials/product-tone.d.ts

@@ -1,7 +1,17 @@
 import type { BadgeTone } from '../../../base/badge';
 import type { ProductTone } from '../products.types';
+/**
+ * Badge tone for a product row value. Only status tones carry colour; neutral
+ * and primary (reserved for the main command) render as neutral badges.
+ */
 export declare const PRODUCT_TONE_BADGE: Record<ProductTone, BadgeTone>;
-export declare const PRODUCT_TONE_SURFACE: Record<ProductTone, string>;
+/**
+ * Text colour for a figure whose tone states a status. Figures keep their width,
+ * so a flagged metric lines up with its plain siblings instead of growing a chip.
+ */
+export declare const PRODUCT_TONE_TEXT: Record<ProductTone, string | undefined>;
+/** Whether a tone states a status. Neutral and primary are presentation, not state. */
+export declare function isProductStatusTone(tone: ProductTone | undefined): tone is ProductTone;
 export declare function clampProductPercent(value: number): number;
 export declare function ProductToneDot({ tone }: {
     tone?: ProductTone;

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

@@ -1,4 +1,5 @@
 import type { ReactNode } from 'react';
+import type { CardProps } from '../../base/cards';
 import type { BadgeTone } from '../../base/badge';
 import type { ActionMenuAction } from '../../base/action-menu';
 import type { MetadataListItem } from '../../blocks/data-display/metadata';
@@ -741,7 +742,7 @@ export interface ProductVariantsBulkTableProps {
     /** Overrides this surface’s own copy. */
     strings?: StringsProp<ProductVariantBulkTableStrings>;
 }
-export interface ProductVariantsManagerProps extends 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' | '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. */

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

@@ -72,7 +72,7 @@ export interface DateCellProps {
     preset?: DateProps['preset'];
     /** date-fns locale override. Falls back to UIProvider dates. */
     locale?: DateProps['locale'];
-    /** Renders the icon. */
+    /** Renders the leading glyph. Off by default: a repeated calendar glyph on every row adds no information. */
     showIcon?: boolean;
     /** Leading glyph. */
     icon?: ComponentType<{

package/dist/components/layout/page/index.d.ts

@@ -1,4 +1,4 @@
 export { Page } from './page';
 export { PageHeader } from './partials/page-header';
 export { PageActions } from './partials/page-actions';
-export { defaultPageActionsStrings, type PageHeaderProps, type PageHeaderSlots, type PageActionsProps, type PageActionsDisplay, type PageAction, type PageActionContext, type PageActionsStrings, type PageProps, type PageSlotProps, } from './page.types';
+export { defaultPageActionsStrings, type PageHeaderAction, type PageHeaderProps, type PageHeaderSlots, type PageActionsProps, type PageActionsDisplay, type PageAction, type PageActionContext, type PageActionsStrings, type PageProps, type PageSlotProps, } from './page.types';

package/dist/components/layout/page/page.types.d.ts

@@ -18,6 +18,40 @@ export interface PageTitleBadge {
     tone?: BadgeTone;
     key?: Key;
 }
+/**
+ * A page command described by its role. `primaryAction` and `secondaryActions`
+ * choose the treatment, so a command carries no tone or button style.
+ */
+export interface PageHeaderAction {
+    /** Stable key. Defaults to the command's position. */
+    id?: string;
+    /** Visible command text. */
+    label: ReactNode;
+    /** Runs the command. When both are set, `onClick` wins over `href`. */
+    onClick?: () => void;
+    /** Navigates through the header's `renderLink` instead of running a callback. */
+    href?: string;
+    target?: string;
+    rel?: string;
+    /** Marks the destination as leaving the app; forwarded to `renderLink`. */
+    external?: boolean;
+    /** Leading glyph. Pass a Lucide icon component. */
+    icon?: ComponentType<{
+        className?: string;
+    }>;
+    /** Shows the pending indicator and blocks activation. */
+    loading?: boolean;
+    /** Blocks activation while keeping the command visible. */
+    disabled?: boolean;
+    /** Set false to omit the command, for example without permission. */
+    visible?: boolean;
+    /**
+     * Irreversible or harmful command. A destructive secondary command moves to
+     * the More actions menu; a destructive primary command keeps its place with
+     * the destructive treatment. Confirm it from the handler, e.g. ConfirmDialog.
+     */
+    destructive?: boolean;
+}
 export interface PageHeaderSlots {
     /** Replaces the leading back control entirely. */
     back?: ReactNode;
@@ -25,7 +59,7 @@ export interface PageHeaderSlots {
     beforeTitle?: ReactNode;
     /** Additional content after the description. */
     afterDescription?: ReactNode;
-    /** Replaces the trailing actions region. */
+    /** Replaces the trailing actions region, including role-based commands. */
     actions?: ReactNode;
 }
 export interface PageHeaderProps extends LayoutNavigationAdapter {
@@ -35,7 +69,7 @@ export interface PageHeaderProps extends LayoutNavigationAdapter {
     description?: ReactNode;
     /** Shared title/description rhythm. Defaults to dense for page copy. */
     textGap?: TextGap;
-    /** Semantic heading level for the title. Defaults to `h3` for nested app pages. */
+    /** Semantic heading level for the title. Defaults to `h1`, the route's main heading; use `h2` when the page sits inside another titled page. */
     headingTag?: HeadingTag;
     /** Optional decorative icon rendered before the title. Pass a Lucide icon component. */
     titleIcon?: ComponentType<{
@@ -54,7 +88,23 @@ export interface PageHeaderProps extends LayoutNavigationAdapter {
     backLabel?: string;
     /** Chips shown beside the page title. */
     titleBadges?: PageTitleBadge[];
-    /** Controls offered on the surface. */
+    /**
+     * The page's one main command: a solid primary button at the trailing end,
+     * visible at every width.
+     */
+    primaryAction?: PageHeaderAction;
+    /**
+     * Supporting commands in priority order. The first two render as outline
+     * buttons; the rest, and every destructive command, move into the More
+     * actions menu. Below `sm`, all secondary commands collapse into that menu.
+     */
+    secondaryActions?: readonly PageHeaderAction[];
+    /** Accessible name of the More actions menu trigger. */
+    moreActionsLabel?: string;
+    /**
+     * Custom controls before the role-based commands, such as a period select.
+     * Prefer `primaryAction` and `secondaryActions` for commands.
+     */
     actions?: ReactNode;
     /** Replaces individual regions of the shell. */
     slots?: PageHeaderSlots;

package/dist/components/layout/page/partials/page-header-commands.d.ts

@@ -0,0 +1,13 @@
+import type { LayoutLinkRenderer } from '../../layout.types';
+import type { PageHeaderAction } from '../page.types';
+/** Secondary commands rendered as buttons from `sm` up; later ones overflow. */
+export declare const PAGE_HEADER_INLINE_SECONDARY_LIMIT = 2;
+export interface PageHeaderCommandsProps {
+    primaryAction?: PageHeaderAction;
+    secondaryActions?: readonly PageHeaderAction[];
+    moreActionsLabel: string;
+    renderLink: LayoutLinkRenderer;
+}
+/** Whether the header has any role-based command to render. */
+export declare function hasPageHeaderCommands(primaryAction: PageHeaderAction | undefined, secondaryActions: readonly PageHeaderAction[] | undefined): boolean;
+export declare function PageHeaderCommands({ primaryAction, secondaryActions, moreActionsLabel, renderLink, }: PageHeaderCommandsProps): import("react").JSX.Element | null;

package/dist/components/layout/page/partials/page-header.d.ts

@@ -1,2 +1,2 @@
 import type { PageHeaderProps } from '../page.types';
-export declare function PageHeader({ title, description, textGap, headingTag, titleIcon: TitleIcon, titleIconHref, onTitleIconClick, titleIconLabel, backHref, onBack, backLabel, titleBadges, actions, slots, renderLink, className, contentClassName, actionsClassName, titleClassName, titleIconClassName, descriptionClassName, }: PageHeaderProps): import("react").JSX.Element;
+export declare function PageHeader({ title, description, textGap, headingTag, titleIcon: TitleIcon, titleIconHref, onTitleIconClick, titleIconLabel, backHref, onBack, backLabel, titleBadges, primaryAction, secondaryActions, moreActionsLabel, actions, slots, renderLink, className, contentClassName, actionsClassName, titleClassName, titleIconClassName, descriptionClassName, }: PageHeaderProps): import("react").JSX.Element;