themelia-react-ui 2.0.6 → 3.0.0

package/dist/components/blocks/ai/ai-sources/ai-sources.d.ts

@@ -1,5 +1,5 @@
 import { type AiSourcesProps } from './types';
-export declare function AiSources({ sources, variant, maxAvatars, expanded: expandedProp, defaultExpanded, onExpandedChange, onSelect, className, strings: stringsProp, }: AiSourcesProps): import("react").JSX.Element;
+export declare function AiSources({ sources, variant, maxAvatars, expanded: expandedProp, defaultExpanded, onExpandedChange, onSelect, surface, className, strings: stringsProp, }: AiSourcesProps): import("react").JSX.Element;
 export declare namespace AiSources {
     var displayName: string;
 }

package/dist/components/blocks/ai/ai-sources/types.d.ts

@@ -1,5 +1,6 @@
 import type { ReactNode } from 'react';
 import type { StringsProp } from '../../../../lib/strings';
+import type { CardSurface } from '../../../../lib/component-vocabulary';
 export interface AiSourceItem {
     /** Stable identity for this entry. */
     id: string;
@@ -14,8 +15,8 @@ export interface AiSourceItem {
     snippet?: ReactNode;
 }
 export interface AiSourcesStrings {
-    /** Header title — `{{count}}` placeholder for the source count. */
-    title: string;
+    /** Writes the header title for a source count, so a translation owns its plural forms. */
+    formatTitle: (count: number) => string;
     /** Supplied overrides describe how to open the source list. */
     expand: string;
     /** Supplied overrides describe how to close the source list. */
@@ -39,6 +40,11 @@ export interface AiSourcesProps {
     onExpandedChange?: (expanded: boolean) => void;
     /** Click handler — preferred over `url` for SPA routing. */
     onSelect?: (source: AiSourceItem, index: number) => void;
+    /**
+     * Outer chrome. `card` (default) frames the block; `flat` drops the frame
+     * so a composing `Card` or message surface owns it.
+     */
+    surface?: CardSurface;
     /** Merged onto the outermost node. */
     className?: string;
     /** Overrides this surface's own copy. */

package/dist/components/blocks/ai/ai-task/ai-task.d.ts

@@ -1,5 +1,5 @@
 import { type AiTaskProps } from './types';
-export declare function AiTask({ task, density, indent, className, strings: stringsProp, }: AiTaskProps): import("react").JSX.Element;
+export declare function AiTask({ task, density, indent, surface, className, strings: stringsProp, }: AiTaskProps): import("react").JSX.Element;
 export declare namespace AiTask {
     var displayName: string;
 }

package/dist/components/blocks/ai/ai-task/types.d.ts

@@ -1,6 +1,7 @@
 import type { LucideIcon } from 'lucide-react';
 import type { ReactNode } from 'react';
 import type { StringsProp } from '../../../../lib/strings';
+import type { CardSurface } from '../../../../lib/component-vocabulary';
 export type AiTaskStatus = 'queued' | 'running' | 'completed' | 'failed' | 'cancelled' | 'skipped';
 export interface AiTaskItem {
     /** Stable identity for this entry. */
@@ -27,10 +28,18 @@ export declare const defaultAiTaskStrings: AiTaskStrings;
 export interface AiTaskProps {
     /** Top-level task. */
     task: AiTaskItem;
-    /** Compact = single row with collapsible children; expanded = always show. */
+    /**
+     * Compact = nested rows start collapsed; expanded = every row starts open.
+     * Changing it re-seeds every row; a toggle made afterwards still wins.
+     */
     density?: 'compact' | 'expanded';
     /** Indentation width per nesting level (px). */
     indent?: number;
+    /**
+     * Outer chrome. `card` (default) frames the block; `flat` drops the frame
+     * so a composing `Card` or message surface owns it.
+     */
+    surface?: CardSurface;
     /** Merged onto the outermost node. */
     className?: string;
     /** Overrides this surface's own copy. */

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

@@ -1,5 +1,5 @@
 import { type AiToolCallProps } from './types';
-export declare function AiToolCall({ name, status, icon: IconComponent, args, result, error, durationMs, expanded: expandedProp, defaultExpanded, onExpandedChange, className, strings: stringsProp, }: AiToolCallProps): import("react").JSX.Element;
+export declare function AiToolCall({ name, status, icon: IconComponent, args, result, error, durationMs, expanded: expandedProp, defaultExpanded, onExpandedChange, surface, className, strings: stringsProp, }: AiToolCallProps): import("react").JSX.Element;
 export declare namespace AiToolCall {
     var displayName: string;
 }

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

@@ -1,6 +1,7 @@
 import type { LucideIcon } from 'lucide-react';
 import type { ReactNode } from 'react';
 import type { StringsProp } from '../../../../lib/strings';
+import type { CardSurface } from '../../../../lib/component-vocabulary';
 export type AiToolCallStatus = 'pending' | 'running' | 'success' | 'error';
 export interface AiToolCallStrings {
     pending: string;
@@ -35,6 +36,11 @@ export interface AiToolCallProps {
     defaultExpanded?: boolean;
     /** Fired whenever the disclosure state changes. */
     onExpandedChange?: (expanded: boolean) => void;
+    /**
+     * Outer chrome. `card` (default) frames the block; `flat` drops the frame
+     * so a composing `Card` or message surface owns it.
+     */
+    surface?: CardSurface;
     /** Merged onto the outermost node. */
     className?: string;
     /** Overrides this surface's own copy. */

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

@@ -34,5 +34,7 @@ export interface AiClassificationStrings {
         medium: string;
         high: string;
     };
+    /** Writes the complexity score against its maximum. Defaults to `"<score>/<max>"`. */
+    formatComplexity?: (score: number, max: number) => string;
 }
 export declare const defaultAiClassificationStrings: AiClassificationStrings;

package/dist/components/blocks/analytics/activity-heatmap/types.d.ts

@@ -5,7 +5,7 @@ export interface ActivityHeatmapDay {
     date: string;
     level: ActivityLevel;
 }
-export type ActivityHeatmapStrings = Pick<AnalyticsStrings, 'heatmapDayLabels' | 'heatmapMonthNames' | 'heatmapLegendLess' | 'heatmapLegendMore'>;
+export type ActivityHeatmapStrings = Pick<AnalyticsStrings, 'heatmapDayLabels' | 'heatmapMonthNames' | 'heatmapLegendLess' | 'heatmapLegendMore' | 'heatmapFormatCell'>;
 export interface ActivityHeatmapProps {
     /** Surface title. */
     title: string;

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

@@ -31,5 +31,7 @@ export interface AnalyticsStrings {
     heatmapLegendLess: string;
     /** Heatmap legend "more" label (right edge of intensity legend). */
     heatmapLegendMore: string;
+    /** Writes a heatmap day's tooltip from its date and level (0–4). Defaults to `"<date>: Level <level>"`. */
+    heatmapFormatCell?: (date: string, level: number) => string;
 }
 export declare const defaultAnalyticsStrings: AnalyticsStrings;

package/dist/components/blocks/analytics/atoms/metric-trend-chip.d.ts

@@ -1,4 +1,12 @@
+import { type StringsProp } from '../../../../lib/strings';
 import type { MetricChange, MetricSize, MetricTrend, MetricTrendVariant } from '../types';
+export interface MetricTrendChipStrings {
+    /** Direction in words, read out before the value. */
+    up: string;
+    down: string;
+    neutral: string;
+}
+export declare const defaultMetricTrendChipStrings: MetricTrendChipStrings;
 export interface MetricTrendChipProps {
     change: MetricChange;
     trend?: MetricTrend;
@@ -8,8 +16,10 @@ export interface MetricTrendChipProps {
     variant?: MetricTrendVariant;
     /** Merged onto the outermost node. */
     className?: string;
+    /** Overrides the direction words. */
+    strings?: StringsProp<MetricTrendChipStrings>;
 }
-export declare function MetricTrendChip({ change, trend, size, variant, className, }: MetricTrendChipProps): import("react").JSX.Element;
+export declare function MetricTrendChip({ change, trend, size, variant, className, strings: stringsProp, }: MetricTrendChipProps): import("react").JSX.Element;
 export declare namespace MetricTrendChip {
     var displayName: string;
 }

package/dist/components/blocks/analytics/chart-card/chart-card.d.ts

@@ -8,8 +8,10 @@
  */
 import type { ComponentProps, ReactNode } from 'react';
 import { ChartContainer, type ChartConfig, type ChartInitialDimension } from '../../../base/chart';
-import type { CardSurface, ComponentScale } from '../../../../lib/component-vocabulary';
-export type ChartCardPadding = ComponentScale;
+import { type CardProps } from '../../../base/cards';
+import type { CardSurface } from '../../../../lib/component-vocabulary';
+/** Card's inset scale, including `none` for a chart placed inside an existing boundary. */
+export type ChartCardPadding = NonNullable<CardProps['padding']>;
 export type ChartCardSurface = CardSurface;
 export interface ChartCardProps {
     /** Surface title. */
@@ -25,9 +27,9 @@ export interface ChartCardProps {
     config: ChartConfig;
     children: ComponentProps<typeof ChartContainer>['children'];
     initialDimension?: ChartInitialDimension;
-    /** Outer chrome. */
+    /** Outer chrome. Omit it to stay card-free. */
     surface?: ChartCardSurface;
-    /** Surface inset. */
+    /** Surface inset. Defaults to `none` when unframed and `md` on a framed surface. */
     padding?: ChartCardPadding;
     /** Merged onto the outermost node. */
     className?: string;
@@ -36,7 +38,7 @@ export interface ChartCardProps {
     /** Merged onto the chart. */
     chartClassName?: string;
 }
-export declare function ChartCard({ title, description, headerEnd, titleSuffix, footer, config, children, initialDimension, surface, padding, className, contentClassName, chartClassName, }: ChartCardProps): import("react").JSX.Element;
+export declare function ChartCard({ title, description, headerEnd, titleSuffix, footer, config, children, initialDimension, surface, padding: paddingProp, className, contentClassName, chartClassName, }: ChartCardProps): import("react").JSX.Element;
 export declare namespace ChartCard {
     var displayName: string;
 }

package/dist/components/blocks/analytics/charts/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Analytics charts — every analytics block that draws with Recharts.
+ *
+ * `recharts` is an optional peer. These blocks live in their own exact entry
+ * (`themelia-react-ui/blocks/analytics/charts`) so that importing the
+ * chart-free analytics blocks from `themelia-react-ui/blocks/analytics` never
+ * loads it.
+ *
+ *   - Metric              — single metric (7 variants); draws a sparkline
+ *   - MetricBar           — horizontal strip of Metric cells
+ *   - MetricGrid          — responsive grid of Metric cells
+ *   - MetricMicroGrid     — 6-cell dense overview with mini charts
+ *   - MetricGradient      — hero card with an embedded area chart
+ *   - MetricSparkline     — the area mini chart on its own
+ *   - ChartCard           — chart surface for custom Recharts children
+ *
+ * The shared metric types are re-exported here so one import covers a metric
+ * and its data shape; they are type-only and add nothing at runtime.
+ */
+export type { MetricChange, MetricData, MetricDataPoint, MetricDirection, MetricPeriod, MetricSize, MetricTrend, MetricTrendVariant, MetricValueType, MetricVariant, } from '../types';
+export { MetricSparkline, type MetricSparklineProps } from '../atoms/metric-sparkline';
+export { Metric, type MetricProps } from '../metric';
+export { MetricBar, type MetricBarProps, type MetricBarVariant } from '../metric-bar';
+export { MetricGrid, type MetricGridProps } from '../metric-grid';
+export { MetricMicroGrid, type MetricMicroGridProps, type MicroChartKind, type MicroMetricCell, } from '../metric-micro-grid';
+export { MetricGradient, type MetricGradientProps, type MetricGradientTheme, } from '../metric-gradient';
+export { ChartCard, type ChartCardProps } from '../chart-card';

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

@@ -1,35 +1,28 @@
 /**
- * Analytics — unified module for every metric/stat/KPI surface in the
- * library. One data shape (`MetricData`), one trend chip, one sparkline,
- * eight composable surfaces:
+ * Analytics — the chart-free metric and statistic surfaces. Nothing exported
+ * here reaches `recharts`, so this entry is safe to import without that
+ * optional peer:
  *
- *   - Metric              — single metric (7 visual variants)
- *   - MetricBar           — horizontal strip (default + gradient frame)
- *   - MetricGrid          — responsive grid of Metric cells
- *   - MetricComparison    — period-over-period delta box
- *   - MetricMicroGrid     — 6-cell dense overview with mini visualizations
- *   - MetricGradient      — vivid hero card with embedded area chart
- *   - ActivityHeatmap     — daily-activity calendar grid
- *   - ChartCard           — card-free chart composition for custom Recharts children
+ *   - MetricComparison       — period-over-period delta box
+ *   - ActivityHeatmap        — daily-activity calendar grid
+ *   - TimeDistributionRuler  — activity by hour of day
+ *   - UsageCard              — quota and usage summary
+ *   - MetricTrendChip        — ↑/↓/→ delta indicator (4 variants)
+ *   - MetricSkeleton         — loading placeholder per Metric variant
  *
- * Atoms used internally:
- *   - MetricTrendChip     — ↑/↓/→ delta indicator (4 variants)
- *   - MetricSparkline     — recharts area mini chart
- *   - MetricSkeleton      — loading placeholder per variant
+ * plus the shared metric types, strings and formatters.
+ *
+ * The blocks that draw with Recharts — Metric, MetricBar, MetricGrid,
+ * MetricMicroGrid, MetricGradient, MetricSparkline and ChartCard — live in
+ * `themelia-react-ui/blocks/analytics/charts`. `analytics-entry.test.ts`
+ * keeps this entry free of that import.
  */
-export type { MetricChange, MetricColorScheme, MetricData, MetricDataPoint, MetricDirection, MetricPeriod, MetricSize, MetricTrend, MetricTrendVariant, MetricValueType, MetricVariant, } from './types';
+export type { MetricChange, MetricData, MetricDataPoint, MetricDirection, MetricPeriod, MetricSize, MetricTrend, MetricTrendVariant, MetricValueType, MetricVariant, } from './types';
 export { defaultAnalyticsStrings, type AnalyticsStrings, } from './analytics.strings';
 export { formatMetricValue, resolveTrend, type FormatMetricValueOptions } from './format-metric-value';
-export { MetricTrendChip, type MetricTrendChipProps } from './atoms/metric-trend-chip';
-export { MetricSparkline, type MetricSparklineProps } from './atoms/metric-sparkline';
+export { MetricTrendChip, defaultMetricTrendChipStrings, type MetricTrendChipProps, type MetricTrendChipStrings, } from './atoms/metric-trend-chip';
 export { MetricSkeleton, type MetricSkeletonProps } from './atoms/metric-skeleton';
-export { Metric, type MetricProps } from './metric';
-export { MetricBar, type MetricBarProps, type MetricBarVariant } from './metric-bar';
-export { MetricGrid, type MetricGridProps } from './metric-grid';
 export { MetricComparison, defaultMetricComparisonStrings, type MetricComparisonProps, type MetricComparisonStrings, } from './metric-comparison';
-export { MetricMicroGrid, type MetricMicroGridProps, type MicroChartKind, type MicroMetricCell, } from './metric-micro-grid';
-export { MetricGradient, type MetricGradientProps, type MetricGradientTheme, } from './metric-gradient';
 export { ActivityHeatmap, type ActivityHeatmapDay, type ActivityHeatmapProps, type ActivityHeatmapStrings, type ActivityLevel, } from './activity-heatmap';
-export { ChartCard, type ChartCardProps } from './chart-card';
 export { TimeDistributionRuler, defaultTimeDistributionRulerStrings, type TimeDistributionRulerProps, type TimeDistributionRulerStrings, } from './time-ruler';
 export * from './usage-card';

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

@@ -1,5 +1,5 @@
 import type { SemanticTone } from '../../../../lib/component-vocabulary';
-import type { MetricColorScheme, MetricData, MetricSize, MetricVariant } from '../types';
+import type { MetricData, MetricSize, MetricVariant } from '../types';
 export interface MetricProps {
     /** Records to render. */
     data: MetricData;
@@ -7,10 +7,8 @@ export interface MetricProps {
     variant?: MetricVariant;
     /** Size preset. */
     size?: MetricSize;
-    /** Tone for bordered surfaces and colored progress. Takes precedence over colorScheme. */
+    /** Tone for bordered surfaces and colored progress. Defaults to neutral; the `colored` variant defaults to primary. */
     tone?: SemanticTone;
-    /** @deprecated Use tone. */
-    colorScheme?: MetricColorScheme;
     /** Renders the sparkline. */
     showSparkline?: boolean;
     /** Renders the change. */
@@ -20,8 +18,10 @@ export interface MetricProps {
     loading?: boolean;
     error?: boolean;
     errorLabel?: string;
-    /** `colored` variant only — 0-100 fill percentage. */
+    /** `colored` variant only — 0-100 fill percentage. Values outside the range are clamped. */
     progress?: number;
+    /** `colored` variant only — accessible name of the progress bar. Defaults to "<label> progress". */
+    progressLabel?: string;
     /** Merged onto the outermost node. */
     className?: string;
     'aria-label'?: string;

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

@@ -1,6 +1,6 @@
 import { type MetricProps } from '../metric/metric';
 import type { MetricData, MetricSize, MetricVariant } from '../types';
-export interface MetricGridProps extends Pick<MetricProps, 'tone' | 'colorScheme'> {
+export interface MetricGridProps extends Pick<MetricProps, 'tone'> {
     /** Metrics rendered as one responsive peer collection. */
     metrics: MetricData[];
     /** Cell variant. `card` composes the canonical Card surface. */
@@ -26,7 +26,7 @@ export interface MetricGridProps extends Pick<MetricProps, 'tone' | 'colorScheme
      */
     className?: string;
 }
-export declare function MetricGrid({ metrics, variant, size, tone, colorScheme, columns, gap, showSparklines, showChanges, showIcons, loading, className, }: MetricGridProps): import("react").JSX.Element;
+export declare function MetricGrid({ metrics, variant, size, tone, columns, gap, showSparklines, showChanges, showIcons, loading, className, }: MetricGridProps): import("react").JSX.Element;
 export declare namespace MetricGrid {
     var displayName: string;
 }

package/dist/components/blocks/analytics/types.d.ts

@@ -5,6 +5,7 @@
  * card, a metric bar, a grid, or a comparison view without re-mapping.
  */
 import type { LucideIcon } from 'lucide-react';
+import type { MouseEvent } from 'react';
 import type { ComponentScale } from '../../../lib/component-vocabulary';
 /** Format hint for a metric value. The Metric component formats accordingly. */
 export type MetricValueType = 'number' | 'currency' | 'percentage' | 'duration' | 'text';
@@ -15,8 +16,6 @@ export type MetricDirection = 'up' | 'down' | 'neutral';
  * for some metrics "down" is good (e.g. churn), so consumers can override.
  */
 export type MetricTrend = 'positive' | 'negative' | 'neutral';
-/** @deprecated Use the shared semantic tone through the tone prop. */
-export type MetricColorScheme = 'default' | 'primary' | 'success' | 'warning' | 'danger' | 'info';
 /** Visual layout variant for the canonical `Metric` component. */
 export type MetricVariant = 
 /** Default tile — label, value, optional sparkline / trend chip / footer. */
@@ -49,6 +48,11 @@ export interface MetricChange {
     direction: MetricDirection;
     /** Display label. */
     label?: string;
+    /**
+     * The direction in words for assistive technology ("Up", "Down"). Defaults
+     * to the trend chip's own strings; set it to localise per datum.
+     */
+    directionLabel?: string;
 }
 /**
  * Shared metric data shape. `id` is required for stable list keys; `value` accepts
@@ -73,7 +77,12 @@ export interface MetricData {
     trend?: MetricTrend;
     /** Destination for the entry, when it navigates. */
     href?: string;
-    onClick?: () => void;
+    /**
+     * Fired when the metric is activated. With `href` the metric stays a real
+     * link and the handler receives the click: call `event.preventDefault()` to
+     * route in-app.
+     */
+    onClick?: (event: MouseEvent<HTMLElement>) => void;
 }
 /** Time-series datapoint used by the gradient/area chart variants. */
 export interface MetricDataPoint {

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

@@ -14,6 +14,8 @@ export interface UsageCardStrings {
     perDay: string;
     /** Shown in place of the daily average when a day's record is missing. Additive. */
     averageUnavailable?: string;
+    /** Writes a quota's progress for assistive technology from formatted figures. Defaults to "<used> of <limit> <unit> used". */
+    formatQuotaValueText?: (used: string, limit: string, unit?: string) => string;
     resources: string;
     periods: string;
     loading: string;

package/dist/components/blocks/commerce/address-card/address-card.d.ts

@@ -1,5 +1,5 @@
 import { type AddressCardProps } from './types';
-export declare function AddressCard({ kind, name, line1, line2, city, region, postalCode, country, phone, default: defaultAddress, onEdit, onRemove, onMakeDefault, surface, padding, headerDivider, className, strings: stringsProp, ...props }: AddressCardProps): import("react").JSX.Element;
+export declare function AddressCard({ kind, address, default: defaultAddress, onEdit, onRemove, onMakeDefault, surface, padding, headerDivider, className, strings: stringsProp, ...props }: AddressCardProps): import("react").JSX.Element;
 export declare namespace AddressCard {
     var displayName: string;
 }

package/dist/components/blocks/commerce/address-card/types.d.ts

@@ -1,6 +1,7 @@
 import type { ComponentPropsWithoutRef } from 'react';
 import type { CardProps } from '../../../base/cards';
 import type { StringsProp } from '../../../../lib/strings';
+import type { OrderAddress } from '../shared/order-status';
 export type AddressKind = 'shipping' | 'billing' | 'pickup';
 export interface AddressCardStrings {
     defaultBadge: string;
@@ -10,28 +11,16 @@ export interface AddressCardStrings {
     shipping: string;
     billing: string;
     pickup: string;
+    /** Names the overflow menu after its card's title, since several cards share a page. */
+    formatActionsLabel?: (title: string) => string;
 }
 export declare const defaultAddressCardStrings: AddressCardStrings;
 /** Unframed by default. Set surface="card" to let this owner frame its heading and body. */
 export interface AddressCardProps extends Omit<ComponentPropsWithoutRef<'div'>, 'children' | 'title'>, Pick<CardProps, 'surface' | 'padding' | 'headerDivider'> {
     /** What the address is for — billing, shipping, or both. */
     kind?: AddressKind;
-    /** Display name. */
-    name: string;
-    /** Street address. */
-    line1: string;
-    /** Apartment, suite, or unit. */
-    line2?: string;
-    /** City or town. */
-    city: string;
-    /** State, province, or region. */
-    region?: string;
-    /** Postal or ZIP code. */
-    postalCode?: string;
-    /** Country name or code. */
-    country: string;
-    /** Contact number for the delivery. */
-    phone?: string;
+    /** The address to show, in the shape `OrderCustomer` takes. Its `phone` closes the card as a click-to-call link. */
+    address: OrderAddress;
     /** Marks this as the account's default address. */
     default?: boolean;
     /** Fired when an entry is edited. */

package/dist/components/blocks/commerce/booking-calendar-event-card/booking-calendar-event-card.d.ts

@@ -7,10 +7,10 @@ import type { BookingCalendarEventCardProps } from './booking-calendar-event-car
  * no inset note panel and no rule above the action.
  *
  * All visible copy is supplied by props, so this component intentionally has
- * no strings file. Frame it with `Card` only when the page needs card
+ * no strings file. Pass `surface="card"` only when the page needs card
  * chrome.
  */
-export declare function BookingCalendarEventCard({ title, description, status, items, actionLabel, onAction, className, contentClassName, }: BookingCalendarEventCardProps): import("react").JSX.Element;
+export declare function BookingCalendarEventCard({ title, description, status, items, actionLabel, onAction, surface, padding, headerDivider, className, contentClassName, }: BookingCalendarEventCardProps): import("react").JSX.Element;
 export declare namespace BookingCalendarEventCard {
     var displayName: string;
 }

package/dist/components/blocks/commerce/booking-calendar-event-card/booking-calendar-event-card.types.d.ts

@@ -1,11 +1,12 @@
 import type { ReactNode } from 'react';
+import type { CardProps } from '../../../base/cards';
 /** One labeled fact displayed in a booking-event summary. */
 export interface BookingCalendarEventCardItem {
     /** Stable key used to preserve the fact row across renders. */
     id: string;
     /** Consumer-owned fact label, such as “Date” or “Guest”. */
     label: ReactNode;
-    /** Display value. Strings and numbers use the canonical `Value` primitive. */
+    /** Display value, rendered by the shared `MetadataList` value role. */
     value: ReactNode;
     /** Span both detail columns, for a note that should not sit in a column. */
     fullWidth?: boolean;
@@ -15,21 +16,22 @@ export interface BookingCalendarEventCardItem {
  *
  * The component owns compact commerce presentation only. The consumer owns
  * booking data, formatting, status copy, routing, and action behavior.
+ * Unframed by default; set surface="card" to let this owner frame itself.
  */
-export interface BookingCalendarEventCardProps {
+export interface BookingCalendarEventCardProps extends Pick<CardProps, 'surface' | 'padding' | 'headerDivider'> {
     /** Primary booking identifier or event title. */
     title: ReactNode;
     /** Optional supporting context shown beneath the title. */
     description?: ReactNode;
     /** Optional status, rendered beside the title. */
     status?: ReactNode;
-    /** Ordered booking facts rendered as a responsive definition list. */
+    /** Ordered booking facts, rendered through the shared `MetadataList` in one or two columns. */
     items: BookingCalendarEventCardItem[];
     /** Label for the primary booking action. */
     actionLabel: ReactNode;
     /** Called when the primary booking action is activated. */
     onAction: () => void;
-    /** Class applied to the outer content block. */
+    /** Class applied to the outermost node. */
     className?: string;
     /** Class applied to the details-and-action content region. */
     contentClassName?: string;

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

@@ -3,5 +3,3 @@ export declare function CartSummaryCard({ items, subtotal, tax, shipping, discou
 export declare namespace CartSummaryCard {
     var displayName: string;
 }
-/** The source kit's name for `CartSummaryCard`; the same component. */
-export declare const CartSummary: typeof CartSummaryCard;

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

@@ -1,2 +1,2 @@
-export { CartSummary, CartSummaryCard } from './cart-summary';
-export { defaultCartSummaryStrings, type CartSummaryCardProps, type CartSummaryProps, type CartSummaryStrings, type CartLineItem, } from './types';
+export { CartSummaryCard } from './cart-summary';
+export { defaultCartSummaryStrings, type CartSummaryCardProps, type CartSummaryStrings, type CartLineItem, } from './types';

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

@@ -4,18 +4,16 @@ import type { StringsProp } from '../../../../lib/strings';
 export interface CartLineItem {
     /** Stable identity for this entry. */
     id: string;
-    /** Display name. */
-    name?: string;
-    productTitle?: string;
-    /** Surface title. */
-    title?: string;
+    /** Product name shown on the line. */
+    title: string;
+    /** Variant or option summary under the title. */
     variantTitle?: string;
     qty: number;
+    /** Formatted line price. */
     price: string;
-    imageUrl?: string;
+    /** Product image. Without one, or when it fails to load, the line's initials show. */
     imageSrc?: string;
-    src?: string;
-    url?: string;
+    /** Alternative text for the image. Defaults to the title. */
     imageAlt?: string;
 }
 export interface CartSummaryStrings {
@@ -34,8 +32,10 @@ export interface CartSummaryStrings {
     checkout: string;
     /** Writes a line's quantity, so a translation owns the multiplication sign. */
     formatQuantity: (quantity: number) => string;
+    /** Shown in place of the lines when the cart has none. */
+    empty?: string;
 }
-export declare const defaultCartSummaryStrings: CartSummaryStrings;
+export declare const defaultCartSummaryStrings: Required<CartSummaryStrings>;
 /** 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. */
@@ -56,5 +56,3 @@ export interface CartSummaryCardProps extends Omit<ComponentPropsWithoutRef<'div
     /** Overrides this surface's own copy. */
     strings?: StringsProp<CartSummaryStrings>;
 }
-/** The source kit's name for `CartSummaryCardProps`. */
-export type CartSummaryProps = CartSummaryCardProps;

package/dist/components/blocks/commerce/coupon-input/coupon-input.d.ts

@@ -1,5 +1,5 @@
 import { type CouponInputCardProps } from './types';
-export declare function CouponInputCard({ appliedCode, appliedDiscount, error, onApply, onRemove, loading, className, strings: stringsProp, }: CouponInputCardProps): import("react").JSX.Element;
+export declare function CouponInputCard({ appliedCode, appliedDiscount, error, onApply, onRemove, loading, surface, padding, headerDivider, className, strings: stringsProp, }: CouponInputCardProps): import("react").JSX.Element;
 export declare namespace CouponInputCard {
     var displayName: string;
 }

package/dist/components/blocks/commerce/coupon-input/types.d.ts

@@ -1,3 +1,4 @@
+import type { CardProps } from '../../../base/cards';
 import type { StringsProp } from '../../../../lib/strings';
 export interface CouponInputStrings {
     /** Surface title. */
@@ -13,16 +14,19 @@ export interface CouponInputStrings {
     apply: string;
     remove: string;
     applied: string;
+    /** Error copy used when `error` is passed as `true`. */
     invalid: string;
 }
 export declare const defaultCouponInputStrings: CouponInputStrings;
-export interface CouponInputCardProps {
+/** Unframed by default. Set surface="card" to let this owner frame its heading and body. */
+export interface CouponInputCardProps extends Pick<CardProps, 'surface' | 'padding' | 'headerDivider'> {
     /** Coupon currently applied, if any. */
     appliedCode?: string;
     /** Formatted discount the coupon grants. */
     appliedDiscount?: string;
-    /** Validation message for a rejected code. */
-    error?: string;
+    /** Validation message for a rejected code. `true` shows `strings.invalid`. */
+    error?: string | boolean;
+    /** Fired with the trimmed, upper-cased code when the form is submitted, by the button or by Enter. */
     onApply?: (code: string) => void;
     /** Fired when an entry is removed. */
     onRemove?: () => void;

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

@@ -3,5 +3,3 @@ export declare function DiscountStackPreview({ discounts, totalSavings, classNam
 export declare namespace DiscountStackPreview {
     var displayName: string;
 }
-/** The source kit's name for `DiscountStackPreview`; the same component. */
-export declare const DiscountStack: typeof DiscountStackPreview;

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

@@ -1,2 +1,2 @@
-export { DiscountStack, DiscountStackPreview } from './discount-stack';
-export { defaultDiscountStackStrings, type Discount, type DiscountStackPreviewProps, type DiscountStackProps, type DiscountStackStrings, } from './types';
+export { DiscountStackPreview } from './discount-stack';
+export { defaultDiscountStackStrings, type Discount, type DiscountStackPreviewProps, type DiscountStackStrings, } from './types';

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

@@ -3,7 +3,7 @@ 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. */
+    /** Stable identity for this entry. Falls back to the label and position. */
     id?: string;
     /** Display label. */
     label: string;
@@ -11,8 +11,6 @@ export interface Discount {
     amount: string;
     /** What kind of discount it is ("Code", "Automatic"), shown quietly beside the amount. */
     kind?: ReactNode;
-    /** The kind as plain text. Kept for existing callers; `kind` wins when both are set. */
-    type?: string;
     /**
      * Draws the kind as a chip in this tone. Discount kinds are categories, so
      * pass `neutral` unless the chip states a status. Omit it for the quiet note.
@@ -24,8 +22,10 @@ export interface DiscountStackStrings {
     title: string;
     /** Formatted sum of every discount. */
     totalSavings: string;
+    /** Shown in place of the ledger when no discount applies. */
+    empty?: string;
 }
-export declare const defaultDiscountStackStrings: DiscountStackStrings;
+export declare const defaultDiscountStackStrings: Required<DiscountStackStrings>;
 /** 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. */
@@ -37,5 +37,3 @@ export interface DiscountStackPreviewProps extends Omit<ComponentPropsWithoutRef
     /** Overrides this surface's own copy. */
     strings?: StringsProp<DiscountStackStrings>;
 }
-/** The source kit's name for `DiscountStackPreviewProps`. */
-export type DiscountStackProps = DiscountStackPreviewProps;