themelia-react-ui 2.0.4 → 2.0.5

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

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

@@ -68,5 +68,29 @@ export interface ActivityRowProps<TData = unknown> {
     contentClassName?: string;
     /** Merged onto the details. */
     detailsClassName?: string;
+    /**
+     * Keeps the expand toggle's column when this row has none, so timestamps
+     * share one end edge with sibling rows that do. The feed sets it.
+     */
+    reserveDisclosure?: boolean;
+    /**
+     * Keeps the overflow menu's column when this row has none, so timestamps
+     * share one end edge with sibling rows that do. The feed sets it.
+     */
+    reserveMenu?: boolean;
 }
+/**
+ * Which trailing controls a row draws beside its timestamp. The feed asks every
+ * row first, so rows without a control can keep its column and the timestamps align.
+ */
+export declare function resolveActivityRowTrailing<TData = unknown>({ activity, density, detailsCollapsible, customDetails, actions, }: {
+    activity: ActivityItem<TData>;
+    density: ActivityDensity;
+    detailsCollapsible?: boolean;
+    customDetails?: ReactNode;
+    actions: readonly ActivityAction<TData>[];
+}): {
+    disclosure: boolean;
+    menu: boolean;
+};
 export declare function ActivityRow<TData = unknown>(props: ActivityRowProps<TData>): import("react").JSX.Element;

package/dist/components/features/event-calendar/colors.d.ts

@@ -14,9 +14,9 @@ import { type EventCategory } from './event-calendar.types';
 export interface CalendarColorClasses {
     /** Solid dot fill (used as the leading bullet on event chips). */
     dot: string;
-    /** Soft tinted surface for the event badge background. */
+    /** Neutral surface for the event badge background. */
     badgeBg: string;
-    /** Border-tone for the event badge / legend swatch. */
+    /** Neutral edge for the event badge. */
     border: string;
     /** Filled legend swatch (square chip in the legend row). */
     swatch: string;

package/dist/components/features/event-calendar/event-calendar.types.d.ts

@@ -48,6 +48,10 @@ export type CalendarColorToken = 'gray' | 'red' | 'orange' | 'amber' | 'yellow'
 /**
  * Tailwind class lookups for each canonical token. Used by day-cell dots and
  * event-badge dots so we never string-parse `category.color`.
+ *
+ * A category is a kind, not a status, so each hue family takes the nearest
+ * categorical chart series (`--chart-1…5`) rather than a success, warning,
+ * destructive or info tone; `gray` stays the neutral marker.
  */
 export declare const calendarTokenDot: Record<CalendarColorToken, string>;
 /**

package/dist/components/features/filters/facets/select-facet.d.ts

@@ -14,6 +14,7 @@ export interface SelectFacetProps {
  *
  * Composes `PopoverMenu` for the popover + searchable list pattern.
  * Multi-select keeps the popover open after a tap; single-select closes
- * unless `closeOnSelect=false` is passed in the filter config.
+ * unless `closeOnSelect=false` is passed in the filter config. Options with
+ * `children` use the Cascader field instead, one level at a time.
  */
 export declare function SelectFacet({ filter, value, onValueChange, className, }: SelectFacetProps): import("react").JSX.Element;