themelia-react-ui 2.0.3 → 2.0.5

package/dist/components/base/value-inputs/date-time-input.d.ts

@@ -1,4 +1,5 @@
-export interface DateTimeInputProps {
+import type { DatePickerBaseProps } from '../date-pickers/datepicker.types';
+export interface DateTimeInputProps extends Pick<DatePickerBaseProps, 'triggerRef' | 'onBlur' | 'aria-describedby' | 'aria-invalid'> {
     /** Controlled value (ISO string) */
     value?: string;
     /** Change handler */

package/dist/components/base/value-inputs/slider.d.ts

@@ -12,9 +12,13 @@ export interface SliderImitationEvent {
     };
 }
 export interface SliderProps {
+    /** Native range input ref; the forwarded ref continues to name the slider root. */
+    inputRef?: React.Ref<HTMLInputElement>;
+    /** Blur callback from the native range input. */
+    onBlur?: React.FocusEventHandler<HTMLInputElement>;
     /** Field name for form integration */
     name?: string;
-    /** Element id */
+    /** Slider group id; use aria-labelledby to associate visible copy with its native range input. */
     id?: string;
     /** Accessible name when a visible label is not associated with the slider. */
     'aria-label'?: string;

package/dist/components/base/value-inputs/tags-input.d.ts

@@ -21,6 +21,10 @@ export interface TagsInputStrings {
 }
 export declare const defaultTagsInputStrings: TagsInputStrings;
 export interface TagsInputProps<T = string> {
+    /** Ref to the editable input, for focus and form registration. */
+    inputRef?: React.Ref<HTMLInputElement>;
+    /** Native blur callback, emitted even when there is no draft to commit. */
+    onBlur?: React.FocusEventHandler<HTMLInputElement>;
     /** ID of the editable input, for an external field label. */
     id?: string;
     /** Names the editable input when no visible label points at it. */
@@ -87,7 +91,7 @@ export interface TagsInputProps<T = string> {
     /** Additional class names */
     className?: string;
 }
-export declare function TagsInput<T = string>({ id, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, 'aria-required': ariaRequired, value, defaultValue, onValueChange, name, placeholder, recommendations, maxTags, showMaxTags, allowDuplicates, validate, disabled, showClearAll, renderTag, delimiter, addOnBlur, minLength, maxLength, sortTags, caseSensitive, field, invalid, className, strings: stringsProp, }: TagsInputProps<T>): React.JSX.Element;
+export declare function TagsInput<T = string>({ id, inputRef: forwardedInputRef, onBlur, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, 'aria-required': ariaRequired, value, defaultValue, onValueChange, name, placeholder, recommendations, maxTags, showMaxTags, allowDuplicates, validate, disabled, showClearAll, renderTag, delimiter, addOnBlur, minLength, maxLength, sortTags, caseSensitive, field, invalid, className, strings: stringsProp, }: TagsInputProps<T>): React.JSX.Element;
 export declare namespace TagsInput {
     var displayName: string;
 }

package/dist/components/blocks/ai/ai-file-tree/types.d.ts

@@ -38,7 +38,7 @@ export interface AiFileTreeProps extends Omit<ComponentProps<'div'>, 'children'
     selectedId?: string;
     /** Click handler — fires for files only by default. */
     onSelect?: (node: AiFileTreeNode) => void;
-    /** Hide diff status badges; semantic icon colors remain visible. */
+    /** Hide diff status badges; each file icon then takes its status colour instead. With badges shown, icons stay neutral. */
     hideStatusLabels?: boolean;
     /** Indent width per nesting level (px). Omit for the shared token-backed hierarchy inset. */
     indent?: number;

package/dist/components/blocks/ai/ai-tool-call/types.d.ts

@@ -12,6 +12,8 @@ export interface AiToolCallStrings {
     args: string;
     result: string;
     durationLabel: string;
+    /** Label before the elapsed time of a call that is still queued or running. Additive. */
+    elapsedLabel?: string;
 }
 export declare const defaultAiToolCallStrings: AiToolCallStrings;
 export interface AiToolCallProps {
@@ -23,7 +25,7 @@ export interface AiToolCallProps {
     args?: ReactNode;
     result?: ReactNode;
     error?: ReactNode;
-    /** Duration in ms; rendered as "Took 1.2s". */
+    /** Duration in ms; rendered as "Took 1.2s", or "Elapsed 1.2s" while the call is queued or running. */
     durationMs?: number;
     /** Expanded state, for controlled use. */
     expanded?: boolean;

package/dist/components/blocks/ai/ai.strings.d.ts

@@ -15,6 +15,8 @@ export interface AiSummaryStrings {
         medium: string;
         high: string;
     };
+    /** Visible name of the confidence signal, read before its level. Additive. */
+    confidenceLabel?: string;
 }
 export declare const defaultAiSummaryStrings: AiSummaryStrings;
 export interface AiClassificationStrings {

package/dist/components/blocks/analytics/metric-comparison/metric-comparison.d.ts

@@ -6,6 +6,8 @@ export interface MetricComparisonStrings {
     currentLabel: string;
     previousLabel: string;
     suffix: string;
+    /** Unit for the absolute change between two percentages. Additive; defaults to `pp`. */
+    pointsUnit?: string;
 }
 export declare const defaultMetricComparisonStrings: MetricComparisonStrings;
 export interface MetricComparisonProps {

package/dist/components/blocks/analytics/usage-card/usage-card.strings.d.ts

@@ -12,6 +12,8 @@ export interface UsageCardStrings {
     daily: string;
     average: string;
     perDay: string;
+    /** Shown in place of the daily average when a day's record is missing. Additive. */
+    averageUnavailable?: string;
     resources: string;
     periods: string;
     loading: string;

package/dist/components/blocks/commerce/cart-summary/cart-summary.d.ts

@@ -1,5 +1,5 @@
 import { type CartSummaryCardProps } from './types';
-export declare function CartSummaryCard({ items, subtotal, tax, shipping, discount, total, onCheckout, className, strings: stringsProp, ...props }: CartSummaryCardProps): import("react").JSX.Element;
+export declare function CartSummaryCard({ items, subtotal, tax, shipping, discount, total, onCheckout, className, strings: stringsProp, surface, padding, headerDivider, ...props }: CartSummaryCardProps): import("react").JSX.Element;
 export declare namespace CartSummaryCard {
     var displayName: string;
 }

package/dist/components/blocks/commerce/cart-summary/types.d.ts

@@ -1,4 +1,5 @@
 import type { ComponentPropsWithoutRef } from 'react';
+import type { CardProps } from '../../../base/cards';
 import type { StringsProp } from '../../../../lib/strings';
 export interface CartLineItem {
     /** Stable identity for this entry. */
@@ -35,7 +36,8 @@ export interface CartSummaryStrings {
     formatQuantity: (quantity: number) => string;
 }
 export declare const defaultCartSummaryStrings: CartSummaryStrings;
-export interface CartSummaryCardProps extends Omit<ComponentPropsWithoutRef<'div'>, 'children' | 'title'> {
+/** Unframed by default. Set surface="card" to let this owner frame its heading and body. */
+export interface CartSummaryCardProps extends Omit<ComponentPropsWithoutRef<'div'>, 'children' | 'title'>, Pick<CardProps, 'surface' | 'padding' | 'headerDivider'> {
     /** Line items in the cart. */
     items: CartLineItem[];
     /** Formatted total before tax, shipping, and discounts. */

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

@@ -1,5 +1,5 @@
 import { type DiscountStackPreviewProps } from './types';
-export declare function DiscountStackPreview({ discounts, totalSavings, className, strings: stringsProp, ...props }: DiscountStackPreviewProps): import("react").JSX.Element;
+export declare function DiscountStackPreview({ discounts, totalSavings, className, strings: stringsProp, surface, padding, headerDivider, ...props }: DiscountStackPreviewProps): import("react").JSX.Element;
 export declare namespace DiscountStackPreview {
     var displayName: string;
 }

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

@@ -1,5 +1,6 @@
 import type { ComponentPropsWithoutRef, ReactNode } from 'react';
 import type { BadgeTone } from '../../../base/badge';
+import type { CardProps } from '../../../base/cards';
 import type { StringsProp } from '../../../../lib/strings';
 export interface Discount {
     /** Stable identity for this entry. Falls back to the kind, label and position. */
@@ -25,7 +26,8 @@ export interface DiscountStackStrings {
     totalSavings: string;
 }
 export declare const defaultDiscountStackStrings: DiscountStackStrings;
-export interface DiscountStackPreviewProps extends Omit<ComponentPropsWithoutRef<'div'>, 'children' | 'title'> {
+/** Unframed by default. Set surface="card" to let this owner frame its heading and body. */
+export interface DiscountStackPreviewProps extends Omit<ComponentPropsWithoutRef<'div'>, 'children' | 'title'>, Pick<CardProps, 'surface' | 'padding' | 'headerDivider'> {
     /** Discounts applied, in the order they stack. */
     discounts: Discount[];
     /** Formatted sum of every discount. */

package/dist/components/blocks/commerce/fulfillment-group/fulfillment-group.d.ts

@@ -1,5 +1,5 @@
 import { type FulfillmentGroupProps } from './types';
-export declare function FulfillmentGroup({ status, location, notice, noticeIcon: NoticeIcon, items, children, actions, renderLink, className, strings: stringsProp, ...props }: FulfillmentGroupProps): import("react").JSX.Element;
+export declare function FulfillmentGroup({ status, location, notice, noticeIcon: NoticeIcon, items, count, children, actions, renderLink, surface, padding, className, strings: stringsProp, ...props }: FulfillmentGroupProps): import("react").JSX.Element;
 export declare namespace FulfillmentGroup {
     var displayName: string;
 }

package/dist/components/blocks/commerce/fulfillment-group/types.d.ts

@@ -13,8 +13,12 @@ export interface FulfillmentGroupStrings extends OrderLineItemStrings {
     moreActions: string;
 }
 export declare const defaultFulfillmentGroupStrings: FulfillmentGroupStrings;
-/** Header and footer rules follow Card's provider defaults; `headerDivider` / `footerDivider` override them per group. */
-export interface FulfillmentGroupProps extends Omit<ComponentPropsWithoutRef<'div'>, 'children' | 'title'>, Pick<CardProps, 'headerDivider' | 'footerDivider'> {
+/**
+ * Framed by default. Set surface="flat" to embed the group in an existing
+ * surface without a second frame. Header and footer rules follow Card's
+ * provider defaults; `headerDivider` / `footerDivider` override them per group.
+ */
+export interface FulfillmentGroupProps extends Omit<ComponentPropsWithoutRef<'div'>, 'children' | 'title'>, Pick<CardProps, 'surface' | 'padding' | 'headerDivider' | 'footerDivider'> {
     /** Where these goods are. Drives the heading chip's label and tone. */
     status: FulfillmentStatus;
     /** Where the group ships from. */
@@ -30,6 +34,11 @@ export interface FulfillmentGroupProps extends Omit<ComponentPropsWithoutRef<'di
     }>;
     /** The rows, as data. The heading counts them. */
     items?: OrderLine[];
+    /**
+     * Units in the group, for the heading's count when `children` replace the
+     * `items` rows, such as a partial dispatch of a discounted line.
+     */
+    count?: number;
     /** Replaces `items` wholesale, for a caller who needs control of a row. The heading then carries no count. */
     children?: ReactNode;
     /**

package/dist/components/blocks/commerce/index.d.ts

@@ -21,12 +21,12 @@ export { CouponInputCard, defaultCouponInputStrings, type CouponInputCardProps,
 export { OrderStatusCard, defaultOrderStatusStrings, type OrderStatusCardProps, type OrderStatusStrings, type OrderStatusEvent, type OrderStatusKind, } from './order-status';
 export { PaymentMethod, PaymentMethodCard, defaultPaymentMethodStrings, type PaymentMethodCardProps, type PaymentMethodProps, type PaymentMethodStrings, type PaymentMethodVariant, type PaymentBrand, } from './payment-method';
 export { SeoListingCard, DEFAULT_SEO_LISTING_LIMITS, calculateSeoListingScore, defaultSeoListingCardStrings, getSeoPermalinkPath, getSeoPermalinkSlug, type SeoListingCardProps, type SeoListingCardStrings, type SeoListingCheckId, type SeoListingCheckResult, type SeoListingCheckStatus, type SeoListingScoreInput, type SeoListingScoreLimits, type SeoListingScoreResult, } from './seo-listing';
-export type { InvoiceStatus, InvoiceMiniData, InvoiceMiniProps } from './invoice-mini';
-export { InvoiceMini } from './invoice-mini';
-export type { InvoiceHeaderProps, InvoiceParty } from './invoice-header';
-export { InvoiceHeader } from './invoice-header';
-export type { InvoiceLineItem, InvoiceLineItemsProps } from './invoice-line-items';
-export { InvoiceLineItems } from './invoice-line-items';
+export type { InvoiceStatus, InvoiceMiniData, InvoiceMiniProps, InvoiceMiniStrings } from './invoice-mini';
+export { InvoiceMini, defaultInvoiceMiniStrings, invoiceStatusTone } from './invoice-mini';
+export type { InvoiceHeaderProps, InvoiceHeaderStrings, InvoiceParty } from './invoice-header';
+export { InvoiceHeader, defaultInvoiceHeaderStrings } from './invoice-header';
+export type { InvoiceColumn, InvoiceLineItem, InvoiceLineItemsFooterRow, InvoiceLineItemsProps, InvoiceLineItemsStrings, } from './invoice-line-items';
+export { InvoiceLineItems, defaultInvoiceLineItemsStrings } from './invoice-line-items';
 export type { OrderTimelineEvent, OrderTimelineProps } from './order-timeline';
 export { OrderTimeline } from './order-timeline';
 export type { PaymentEvent, PaymentTimelineProps } from './payment-timeline';
@@ -34,6 +34,7 @@ export { PaymentTimeline } from './payment-timeline';
 export { InventorySectionCard, defaultInventorySectionStrings, type InventoryPolicy, type InventorySectionCardProps, type InventorySectionChange, type InventorySectionField, type InventorySectionMetric, type InventorySectionName, type InventorySectionStrings, type InventorySectionValue, type InventoryStatus, } from './inventory-section';
 export { AmountRow, SummaryPanel, type AmountRowProps, type SummaryPanelProps } from './summary-panel';
 export type { FulfillmentStatus, OrderAddress, PaymentStatus, TransactionKind, TransactionStatus, } from './shared/order-status';
+export { fulfillmentStatusTone, paymentStatusTone, transactionStatusTone } from './shared/order-status';
 export { OrderHeader, defaultOrderHeaderStrings, type OrderHeaderProps, type OrderHeaderStrings, } from './order-header';
 export { FulfillmentGroup, defaultFulfillmentGroupStrings, type FulfillmentGroupProps, type FulfillmentGroupStrings, } from './fulfillment-group';
 export { OrderLineItem, defaultOrderLineItemStrings, type OrderLine, type OrderLineItemProps, type OrderLineItemStrings, type OrderLineProperty, } from './order-line-item';

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

@@ -1,5 +1,5 @@
 import { type InventorySectionCardProps } from './types';
-export declare function InventorySectionCard({ value, onValueChange, errors, disabled, readOnly, visibleSections, visibleFields, locationOptions, countryOptions, tagRecommendations, maxTags, onGenerateSku, onRestock, className, strings: stringsProp, }: InventorySectionCardProps): import("react").JSX.Element;
+export declare function InventorySectionCard({ value, onValueChange, errors, disabled, readOnly, visibleSections, visibleFields, locationOptions, countryOptions, tagRecommendations, maxTags, onGenerateSku, onRestock, surface, padding, headerDivider, className, strings: stringsProp, }: InventorySectionCardProps): import("react").JSX.Element;
 export declare namespace InventorySectionCard {
     var displayName: string;
 }

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

@@ -1,3 +1,4 @@
+import type { CardProps } from '../../../base/cards';
 import type { SelectOption } from '../../../base/choice-inputs';
 import type { WeightUnit } from '../../../base/forms-numeric';
 import type { StringsProp } from '../../../../lib/strings';
@@ -76,7 +77,8 @@ export interface InventorySectionStrings {
     };
 }
 export declare const defaultInventorySectionStrings: InventorySectionStrings;
-export interface InventorySectionCardProps {
+/** Unframed by default. Set surface="card" to let this owner frame its heading and body. */
+export interface InventorySectionCardProps extends Pick<CardProps, 'surface' | 'padding' | 'headerDivider'> {
     /** Current field values for every inventory section. Controlled. */
     value: InventorySectionValue;
     /** Fired with the next value. */
@@ -85,7 +87,10 @@ export interface InventorySectionCardProps {
     errors?: Partial<Record<InventorySectionField, string>>;
     /** Renders the entry as unselectable. */
     disabled?: boolean;
-    /** Renders every field as read-only text instead of an editable control. */
+    /**
+     * Locks every field and command while keeping the current values visible,
+     * for a reviewer without edit permission. Controls render disabled.
+     */
     readOnly?: boolean;
     /** Which sections are shown. Omitted sections default to visible. */
     visibleSections?: Partial<Record<InventorySectionName, boolean>>;

package/dist/components/blocks/commerce/invoice-header/index.d.ts

@@ -1,2 +1,3 @@
 export { InvoiceHeader } from './invoice-header';
-export type { InvoiceHeaderProps, InvoiceParty } from './types';
+export { defaultInvoiceHeaderStrings } from './types';
+export type { InvoiceHeaderProps, InvoiceHeaderStrings, InvoiceParty } from './types';

package/dist/components/blocks/commerce/invoice-header/invoice-header.d.ts

@@ -1,5 +1,5 @@
 import { type InvoiceHeaderProps } from './types';
-export declare function InvoiceHeader({ invoiceNumber, status, statusTone, from, to, issuedDate, dueDate, amount, className, strings: stringsProp, ...props }: InvoiceHeaderProps): import("react").JSX.Element;
+export declare function InvoiceHeader({ invoiceNumber, status, statusTone, from, to, issuedDate, dueDate, amount, className, strings: stringsProp, surface, padding, headerDivider, ...props }: InvoiceHeaderProps): import("react").JSX.Element;
 export declare namespace InvoiceHeader {
     var displayName: string;
 }

package/dist/components/blocks/commerce/invoice-header/types.d.ts

@@ -1,12 +1,18 @@
 import type { ComponentPropsWithoutRef, ReactNode } from 'react';
 import type { BadgeTone } from '../../../base/badge';
+import type { CardProps } from '../../../base/cards';
 import type { StringsProp } from '../../../../lib/strings';
 import type { InvoiceStatus } from '../invoice-mini/types';
 export interface InvoiceParty {
-    /** Display name. */
+    /** Display name, usually the legal name. */
     name: string;
     /** Where the party is: a city line, or a node such as a full address. */
     location?: ReactNode;
+    /**
+     * Further identity lines under the location in the same supporting role:
+     * tax or VAT ID, company registration, billing contact.
+     */
+    details?: ReactNode;
 }
 export interface InvoiceHeaderStrings {
     /** Surface title. */
@@ -17,20 +23,24 @@ export interface InvoiceHeaderStrings {
     due: string;
     amountDue: string;
     /** Chip label for each `InvoiceStatus`. */
+    draft: string;
     paid: string;
     pending: string;
     overdue: string;
+    disputed: string;
 }
 export declare const defaultInvoiceHeaderStrings: InvoiceHeaderStrings;
-export interface InvoiceHeaderProps extends Omit<ComponentPropsWithoutRef<'div'>, 'children' | 'title'> {
+/** Unframed by default. Set surface="card" to let this owner frame its heading and body. */
+export interface InvoiceHeaderProps extends Omit<ComponentPropsWithoutRef<'div'>, 'children' | 'title'>, Pick<CardProps, 'surface' | 'padding' | 'headerDivider'> {
     /** Human-facing invoice reference. */
     invoiceNumber: string;
     /**
-     * Payment state. Drives both the chip label (through `strings`) and its
+     * Invoice state. Drives both the chip label (through `strings`) and its
      * tone, so the two can never disagree. Shares the `InvoiceStatus` union
-     * with `InvoiceMini`.
+     * with `InvoiceMini`. Omit it when the page header already states the
+     * status, so the document shows no second chip.
      */
-    status: InvoiceStatus;
+    status?: InvoiceStatus;
     /**
      * Overrides the badge tone derived from `status`. Reach for it only when
      * the surrounding surface needs a tone the status does not imply.
@@ -44,7 +54,11 @@ export interface InvoiceHeaderProps extends Omit<ComponentPropsWithoutRef<'div'>
     issuedDate?: string;
     /** Formatted due date. */
     dueDate?: string;
-    /** Formatted invoice total. */
+    /**
+     * Formatted amount due: what the bill-to party still owes, shown as the
+     * header's total row under `strings.amountDue`. Before any payment it
+     * equals the invoice total; relabel through `strings` to show the total.
+     */
     amount: string;
     /** Merged onto the outermost node. */
     className?: string;

package/dist/components/blocks/commerce/invoice-line-items/invoice-line-items.d.ts

@@ -1,5 +1,5 @@
 import { type InvoiceLineItem, type InvoiceLineItemsProps } from './types';
-export declare function InvoiceLineItems<TItem = InvoiceLineItem>({ items, columns, footerRows, taxRate, currency, className, strings: stringsProp, }: InvoiceLineItemsProps<TItem>): import("react").JSX.Element;
+export declare function InvoiceLineItems<TItem = InvoiceLineItem>({ items, columns, footerRows, taxRate, currency, surface, className, strings: stringsProp, }: InvoiceLineItemsProps<TItem>): import("react").JSX.Element;
 export declare namespace InvoiceLineItems {
     var displayName: string;
 }

package/dist/components/blocks/commerce/invoice-line-items/types.d.ts

@@ -2,11 +2,11 @@ import type { ReactNode } from 'react';
 import type { StringsProp } from '../../../../lib/strings';
 /** Default line-item shape used by the concise InvoiceLineItems mode. */
 export interface InvoiceLineItem {
-    /** Supporting copy shown under the label. */
+    /** Purchased goods or service description for this line. */
     description: string;
     qty: number;
     price: number;
-    /** Total number of records across all pages. */
+    /** Accepted line amount, including any app-owned line adjustments. */
     total: number;
 }
 /**
@@ -18,10 +18,17 @@ export interface InvoiceColumn<TItem = InvoiceLineItem> {
     /** Stable identity for this entry. */
     id: string;
     header: ReactNode;
-    /** Tailwind class for the column's grid track (e.g. `'1fr'`, `'80px'`). */
+    /** CSS grid track value (e.g. `'minmax(0, 1fr)'`, `'80px'`), not a class name. */
     width?: string;
     align?: 'left' | 'right' | 'center';
     cell: (item: TItem, index: number) => ReactNode;
+    /**
+     * Shows the column only when the table is at least its `@lg` container
+     * width (32rem), the default recipe's breakpoint; narrower tables drop its
+     * track instead of crushing the others. Repeat its value in another cell
+     * with the `@lg/invoice-line-items:hidden` class so it stays readable.
+     */
+    wideOnly?: boolean;
     /** Class names appended to header cell. */
     headerClassName?: string;
     /** Class names appended to each row cell of this column. */
@@ -32,7 +39,10 @@ export interface InvoiceLineItemsFooterRow {
     /** Display label. */
     label: ReactNode;
     value: ReactNode;
-    /** Emphasis for the row. `total` renders bold + thicker top spacing. */
+    /**
+     * `total` adds top spacing and bolds the label and a plain-text value.
+     * React-node values keep their own typography; set their weight explicitly.
+     */
     emphasis?: 'normal' | 'total';
 }
 export interface InvoiceLineItemsStrings {
@@ -41,7 +51,7 @@ export interface InvoiceLineItemsStrings {
     price: string;
     subtotal: string;
     tax: string;
-    /** Total number of records across all pages. */
+    /** Label for line totals and the financial grand total. */
     total: string;
 }
 export declare const defaultInvoiceLineItemsStrings: InvoiceLineItemsStrings;
@@ -50,13 +60,20 @@ export interface InvoiceLineItemsProps<TItem = InvoiceLineItem> {
     items: TItem[];
     /** Optional custom columns. Defaults to Description / Qty / Price / Total. */
     columns?: InvoiceColumn<TItem>[];
-    /** Optional custom footer rows. When omitted with the default columns, an
-     * auto-computed subtotal / tax / total footer is used. */
+    /** Optional custom footer rows. React nodes own their typography, including
+     * total-value weight. When omitted with the default columns, an auto-computed
+     * subtotal / tax / total footer is used. */
     footerRows?: InvoiceLineItemsFooterRow[];
     /** Tax ratio for the default footer (`0.2` means 20%). @default 0.2 */
     taxRate?: number;
     /** ISO 4217 code for default monetary cells. Falls back to UIProvider. */
     currency?: string;
+    /**
+     * `card` paints the table's own framed surface. `flat` drops the frame,
+     * striping and row insets so the table sits flush inside a parent Card,
+     * ruled row from row. @default 'card'
+     */
+    surface?: 'card' | 'flat';
     /** Merged onto the outermost node. */
     className?: string;
     /** Overrides this surface's own copy. */

package/dist/components/blocks/commerce/invoice-mini/index.d.ts

@@ -1,2 +1,3 @@
 export { InvoiceMini } from './invoice-mini';
-export type { InvoiceStatus, InvoiceMiniData, InvoiceMiniProps } from './types';
+export { defaultInvoiceMiniStrings, invoiceStatusTone } from './types';
+export type { InvoiceStatus, InvoiceMiniData, InvoiceMiniProps, InvoiceMiniStrings } from './types';

package/dist/components/blocks/commerce/invoice-mini/types.d.ts

@@ -1,7 +1,11 @@
 import type { ComponentPropsWithoutRef } from 'react';
 import type { BadgeTone } from '../../../base/badge';
 import type { StringsProp } from '../../../../lib/strings';
-export type InvoiceStatus = 'paid' | 'pending' | 'overdue';
+/**
+ * Where an invoice stands: `draft` (not yet issued), `pending` (issued, open,
+ * not yet due), `overdue`, `disputed` (part of it is contested) or `paid`.
+ */
+export type InvoiceStatus = 'draft' | 'pending' | 'overdue' | 'disputed' | 'paid';
 export interface InvoiceMiniData {
     invoiceNumber: string;
     customerName: string;
@@ -11,9 +15,11 @@ export interface InvoiceMiniData {
     dueDate: string;
 }
 export interface InvoiceMiniStrings {
+    draft: string;
     paid: string;
     pending: string;
     overdue: string;
+    disputed: string;
     items: (count: number) => string;
     due: string;
 }

package/dist/components/blocks/commerce/order-customer/order-customer.d.ts

@@ -1,5 +1,5 @@
 import { type OrderCustomerProps } from './types';
-export declare function OrderCustomer({ name, email, phone, orderCount, shippingAddress, billingAddress, billingSameAsShipping, onOpenCustomer, onEditShipping, onEditBilling, surface, padding, headerDivider, className, strings: stringsProp, ...props }: OrderCustomerProps): import("react").JSX.Element;
+export declare function OrderCustomer({ name, email, phone, orderCount, shippingAddress, shippingMethod, showShippingAddress, billingAddress, billingSameAsShipping, onOpenCustomer, onEditShipping, onEditBilling, surface, padding, headerDivider, className, strings: stringsProp, ...props }: OrderCustomerProps): import("react").JSX.Element;
 export declare namespace OrderCustomer {
     var displayName: string;
 }

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

@@ -1,4 +1,4 @@
-import type { ComponentPropsWithoutRef } from 'react';
+import type { ComponentPropsWithoutRef, ReactNode } from 'react';
 import type { CardProps } from '../../../base/cards';
 import type { StringsProp } from '../../../../lib/strings';
 import type { OrderAddress } from '../shared/order-status';
@@ -33,6 +33,14 @@ export interface OrderCustomerProps extends Omit<ComponentPropsWithoutRef<'div'>
     orderCount?: number;
     /** Where the order ships. */
     shippingAddress?: OrderAddress;
+    /** How it ships, such as "Standard courier · 2–3 business days", under the shipping address. */
+    shippingMethod?: ReactNode;
+    /**
+     * Shows the shipping address section. Set `false` for a subject that never
+     * ships, such as an invoice or a digital order, rather than stating that no
+     * address is on file. @default true
+     */
+    showShippingAddress?: boolean;
     /** Where the order is billed. */
     billingAddress?: OrderAddress;
     /** Renders one line in place of a repeated billing address. */

package/dist/components/blocks/commerce/refund-status/refund-status.d.ts

@@ -1,5 +1,5 @@
 import { type RefundStatusCardProps } from './types';
-export declare function RefundStatusCard({ stage, amount, reason, method, eta, requestedAt, className, strings: stringsProp, ...props }: RefundStatusCardProps): import("react").JSX.Element;
+export declare function RefundStatusCard({ stage, amount, reason, method, eta, requestedAt, className, strings: stringsProp, surface, padding, headerDivider, ...props }: RefundStatusCardProps): import("react").JSX.Element;
 export declare namespace RefundStatusCard {
     var displayName: string;
 }

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

@@ -1,4 +1,5 @@
 import type { ComponentPropsWithoutRef, ReactNode } from 'react';
+import type { CardProps } from '../../../base/cards';
 import type { StringsProp } from '../../../../lib/strings';
 export type RefundStage = 'requested' | 'approved' | 'processing' | 'completed';
 export interface RefundStatusStrings {
@@ -18,7 +19,8 @@ export interface RefundStatusStrings {
     method: string;
 }
 export declare const defaultRefundStatusStrings: RefundStatusStrings;
-export interface RefundStatusCardProps extends Omit<ComponentPropsWithoutRef<'div'>, 'children' | 'title'> {
+/** Unframed by default. Set surface="card" to let this owner frame its heading and body. */
+export interface RefundStatusCardProps extends Omit<ComponentPropsWithoutRef<'div'>, 'children' | 'title'>, Pick<CardProps, 'surface' | 'padding' | 'headerDivider'> {
     /** How far the refund has progressed. */
     stage: RefundStage;
     /** Formatted refund amount. */

package/dist/components/blocks/commerce/shipment-tracking/shipment-tracking.d.ts

@@ -1,5 +1,5 @@
 import { type ShipmentTrackingProps } from './types';
-export declare function ShipmentTracking({ trackingNumber, carrier, status, steps, details, onCopyTracking, className, strings: stringsProp, ...props }: ShipmentTrackingProps): import("react").JSX.Element;
+export declare function ShipmentTracking({ trackingNumber, carrier, status, steps, details, onCopyTracking, className, strings: stringsProp, surface, padding, headerDivider, ...props }: ShipmentTrackingProps): import("react").JSX.Element;
 export declare namespace ShipmentTracking {
     var displayName: string;
 }

package/dist/components/blocks/commerce/shipment-tracking/types.d.ts

@@ -1,5 +1,6 @@
 import type { ComponentPropsWithoutRef, ReactNode } from 'react';
 import type { BadgeTone } from '../../../base/badge';
+import type { CardProps } from '../../../base/cards';
 import type { StringsProp } from '../../../../lib/strings';
 /**
  * Transit stage. Drives the status label (through `strings`) and the tone of
@@ -45,7 +46,8 @@ export interface ShipmentTrackingStrings {
     delayed: string;
 }
 export declare const defaultShipmentTrackingStrings: ShipmentTrackingStrings;
-export interface ShipmentTrackingProps extends Omit<ComponentPropsWithoutRef<'div'>, 'children' | 'title'> {
+/** Unframed by default. Set surface="card" to let this owner frame its heading and body. */
+export interface ShipmentTrackingProps extends Omit<ComponentPropsWithoutRef<'div'>, 'children' | 'title'>, Pick<CardProps, 'surface' | 'padding' | 'headerDivider'> {
     /** Carrier tracking reference. */
     trackingNumber: string;
     /** Carrier handling the shipment. */

package/dist/components/blocks/commerce/tax-breakdown/tax-breakdown.d.ts

@@ -1,5 +1,5 @@
 import { type TaxBreakdownCardProps } from './types';
-export declare function TaxBreakdownCard({ subtotal, taxes, totalTax, total, className, strings: stringsProp, ...props }: TaxBreakdownCardProps): import("react").JSX.Element;
+export declare function TaxBreakdownCard({ subtotal, taxes, totalTax, total, className, strings: stringsProp, surface, padding, headerDivider, ...props }: TaxBreakdownCardProps): import("react").JSX.Element;
 export declare namespace TaxBreakdownCard {
     var displayName: string;
 }

package/dist/components/blocks/commerce/tax-breakdown/types.d.ts

@@ -1,4 +1,5 @@
 import type { ComponentPropsWithoutRef } from 'react';
+import type { CardProps } from '../../../base/cards';
 import type { StringsProp } from '../../../../lib/strings';
 export interface TaxLineItem {
     /** Stable identity for this entry. */
@@ -19,7 +20,8 @@ export interface TaxBreakdownStrings {
     total: string;
 }
 export declare const defaultTaxBreakdownStrings: TaxBreakdownStrings;
-export interface TaxBreakdownCardProps extends Omit<ComponentPropsWithoutRef<'div'>, 'children' | 'title'> {
+/** Unframed by default. Set surface="card" to let this owner frame its heading and body. */
+export interface TaxBreakdownCardProps extends Omit<ComponentPropsWithoutRef<'div'>, 'children' | 'title'>, Pick<CardProps, 'surface' | 'padding' | 'headerDivider'> {
     /** Formatted amount before tax. */
     subtotal: string;
     /** Individual tax lines making up the total. */

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

@@ -142,7 +142,10 @@ export interface ActivityItem<TData = unknown> {
 export interface ActivityEventConfig {
     /** Leading glyph. */
     icon: LucideIcon;
-    /** Semantic tone driving the entry's colour. */
+    /**
+     * Status tone for the event. It colours status dots and status segments;
+     * the event icon tile names a kind and stays neutral.
+     */
     tone: ActivityTone;
     /** Display label for the event. Defaults to `strings.events[event] || event`. */
     label?: string;
@@ -313,7 +316,10 @@ export interface ActivityLogActivityEntry<TResource extends string = string> {
     event?: string;
     /** Leading glyph. */
     icon?: LucideIcon;
-    /** Semantic tone driving the entry's colour. */
+    /**
+     * Status tone for the entry. It colours status dots and status segments;
+     * the event icon tile names a kind and stays neutral.
+     */
     tone?: ActivityTone;
     actor?: string | ActivityActor;
     /** The action this surface performs. */

package/dist/components/features/activities/partials/activity-marker.d.ts

@@ -2,9 +2,13 @@
  * ActivityMarker — left-edge visual for a row.
  *
  * Density mapping:
- *   - `compact`  → small tone-coloured dot
- *   - `default`  → icon-lg tone-tinted disc with the event icon
- *   - `rich`     → small IconBadge (avatar-sm) with the event icon
+ *   - `compact`  → small tone-coloured status dot
+ *   - `default`  → icon-lg neutral disc with the event icon
+ *   - `rich`     → small neutral IconBadge (avatar-sm) with the event icon
+ *
+ * Event icons name a kind, not a status, so their tiles and the rail stay
+ * neutral whatever the tone; the tone reaches the compact status dot and the
+ * headline's status segment.
  *
  * Every marker heads a first-line box at least `icon-lg` tall, the height of
  * the headline's first line, so the glyph centres on that line by layout