@lostgradient/cinder 0.11.0 → 0.12.1

package/src/components/confirm-dialog/confirm-dialog.css

@@ -1,4 +1,6 @@
 @layer cinder.tokens, cinder.foundation, cinder.components, cinder.utilities;
+@import '../input/input.css';
+
 @layer cinder.components {
   .cinder-confirm-dialog__description {
     margin: 0;

package/src/components/confirm-dialog/confirm-dialog.schema.json

@@ -26,6 +26,14 @@
       "type": "boolean",
       "description": "When true, the confirm button uses variant=\"danger\". The cancel button still\nreceives default focus regardless — color is never the sole destructive signal."
     },
+    "typeToConfirm": {
+      "type": "string",
+      "description": "When set, renders a labelled text input and disables the confirm button until the\ntrimmed input matches this value case-insensitively."
+    },
+    "typeToConfirmLabel": {
+      "type": "string",
+      "description": "Visible label for the typed-confirmation input. Defaults to `Type \"<value>\" to confirm`."
+    },
     "class": {
       "type": "string",
       "description": "Optional extra class on the underlying <Modal>. Destructured as `class: className` per repo convention."

package/src/components/confirm-dialog/confirm-dialog.schema.ts

@@ -31,6 +31,16 @@ const schema = {
       description:
         'When true, the confirm button uses variant="danger". The cancel button still\nreceives default focus regardless — color is never the sole destructive signal.',
     },
+    typeToConfirm: {
+      type: 'string',
+      description:
+        'When set, renders a labelled text input and disables the confirm button until the\ntrimmed input matches this value case-insensitively.',
+    },
+    typeToConfirmLabel: {
+      type: 'string',
+      description:
+        'Visible label for the typed-confirmation input. Defaults to `Type "<value>" to confirm`.',
+    },
     class: {
       type: 'string',
       description:

package/src/components/confirm-dialog/confirm-dialog.svelte

@@ -4,11 +4,25 @@ export {};
 
 <script lang="ts">
 import Button from '../button/button.svelte';
+import Input from '../input/input.svelte';
 import Modal from '../modal/modal.svelte';
 import { classNames } from '../../utilities/class-names.ts';
 const descriptionId = $props.id();
-let { open = $bindable(false), title, description, cancelLabel = 'Cancel', confirmLabel, destructive = false, onconfirm, oncancel, triggerRef = null, class: className, } = $props();
+const typedConfirmationId = `${descriptionId}-typed-confirmation`;
+let { open = $bindable(false), title, description, cancelLabel = 'Cancel', confirmLabel, destructive = false, typeToConfirm, typeToConfirmLabel, onconfirm, oncancel, triggerRef = null, class: className, } = $props();
 const describedById = $derived(description ? descriptionId : undefined);
+const normalizedTypeToConfirm = $derived(typeToConfirm?.trim() || undefined);
+const normalizedTypeToConfirmLabel = $derived(typeToConfirmLabel?.trim() || undefined);
+let typedConfirmation = $state('');
+let previousOpen = open;
+const typedConfirmationMatches = $derived(normalizedTypeToConfirm === undefined ||
+    typedConfirmation.trim().toLowerCase() === normalizedTypeToConfirm.toLowerCase());
+$effect(() => {
+    if (open === previousOpen)
+        return;
+    previousOpen = open;
+    typedConfirmation = '';
+});
 function handleCancel() {
     // Mirror Modal's dismiss() ordering: state first, then callback. No try/catch —
     // consumer errors must propagate so tests, error boundaries, and observability see them.
@@ -34,10 +48,24 @@ function handleConfirm() {
     <p id={descriptionId} class="cinder-confirm-dialog__description">{description}</p>
   {/if}
 
+  {#if normalizedTypeToConfirm !== undefined}
+    <Input
+      id={typedConfirmationId}
+      class="cinder-confirm-dialog__typed-confirmation"
+      bind:value={typedConfirmation}
+      label={normalizedTypeToConfirmLabel ?? `Type "${normalizedTypeToConfirm}" to confirm`}
+      autocomplete="off"
+    />
+  {/if}
+
   {#snippet footer()}
     <Button variant="secondary" autofocus onclick={handleCancel}>{cancelLabel}</Button>
-    <Button variant={destructive ? 'danger' : 'primary'} onclick={handleConfirm}
-      >{confirmLabel}</Button
+    <Button
+      variant={destructive ? 'danger' : 'primary'}
+      disabled={!typedConfirmationMatches}
+      onclick={handleConfirm}
     >
+      {confirmLabel}
+    </Button>
   {/snippet}
 </Modal>

package/src/components/confirm-dialog/confirm-dialog.types.ts

@@ -36,6 +36,13 @@ export type ConfirmDialogProps = {
    * receives default focus regardless — color is never the sole destructive signal.
    */
   destructive?: boolean;
+  /**
+   * When set, renders a labelled text input and disables the confirm button until the
+   * trimmed input matches this value case-insensitively.
+   */
+  typeToConfirm?: string;
+  /** Visible label for the typed-confirmation input. Defaults to `Type "<value>" to confirm`. */
+  typeToConfirmLabel?: string;
   /** Fired when the user activates the confirm button. Required. Component closes itself after. */
   onconfirm: () => void;
   /**

package/src/components/faceted-filter-bar/faceted-filter-bar.schema.json

@@ -10,6 +10,10 @@
       "type": "string",
       "description": "Current text search query. When provided, the search field is controlled."
     },
+    "showSearch": {
+      "type": "boolean",
+      "description": "Whether to render the leading search field. Defaults to `true`."
+    },
     "searchPlaceholder": {
       "type": "string",
       "description": "Placeholder text shown in the leading search field."

package/src/components/faceted-filter-bar/faceted-filter-bar.schema.ts

@@ -12,6 +12,10 @@ const schema = {
       type: 'string',
       description: 'Current text search query. When provided, the search field is controlled.',
     },
+    showSearch: {
+      type: 'boolean',
+      description: 'Whether to render the leading search field. Defaults to `true`.',
+    },
     searchPlaceholder: {
       type: 'string',
       description: 'Placeholder text shown in the leading search field.',

package/src/components/faceted-filter-bar/faceted-filter-bar.svelte

@@ -10,7 +10,7 @@ import Chip from '../chip/chip.svelte';
 import Button from '../button/button.svelte';
 import { classNames } from '../../utilities/class-names.ts';
 const generatedId = $props.id();
-let { 'aria-label': ariaLabel = 'Filters', searchQuery, searchPlaceholder = 'Search…', searchAriaLabel = 'Search', facets = [], appliedFilters = [], disabled = false, class: className, onsearchchange, onfacetchange, onfilterremove, onclearall, ...rest } = $props();
+let { 'aria-label': ariaLabel = 'Filters', searchQuery, showSearch = true, searchPlaceholder = 'Search…', searchAriaLabel = 'Search', facets = [], appliedFilters = [], disabled = false, class: className, onsearchchange, onfacetchange, onfilterremove, onclearall, ...rest } = $props();
 const searchId = $derived(`${generatedId}-search`);
 let rootElement = $state();
 // Internal uncontrolled search value when searchQuery is not provided.
@@ -32,7 +32,7 @@ function resolveFilterDisplayValue(key, value) {
         return value;
     return facet.options.find((option) => option.value === value)?.label ?? value;
 }
-const hasAppliedFilters = $derived(appliedFilters.length > 0 || currentSearchQuery.length > 0);
+const hasAppliedFilters = $derived(appliedFilters.length > 0 || (showSearch && currentSearchQuery.length > 0));
 const totalActiveCount = $derived(appliedFilters.length);
 // Live region summary message — always in DOM, content changes when filters change.
 const summaryMessage = $derived.by(() => {
@@ -81,15 +81,17 @@ function getFacetCurrentValue(key) {
 >
   <!-- Controls row: search field + facet selects -->
   <div class="cinder-faceted-filter-bar__controls">
-    <SearchField
-      id={searchId}
-      class="cinder-faceted-filter-bar__search"
-      value={currentSearchQuery}
-      placeholder={searchPlaceholder}
-      aria-label={searchAriaLabel}
-      {disabled}
-      oninput={handleSearchInput}
-    />
+    {#if showSearch}
+      <SearchField
+        id={searchId}
+        class="cinder-faceted-filter-bar__search"
+        value={currentSearchQuery}
+        placeholder={searchPlaceholder}
+        aria-label={searchAriaLabel}
+        {disabled}
+        oninput={handleSearchInput}
+      />
+    {/if}
 
     {#each facets as facet (facet.key)}
       {#if facet.type === 'select'}

package/src/components/faceted-filter-bar/faceted-filter-bar.types.ts

@@ -69,6 +69,8 @@ export type FacetedFilterBarProps = Omit<HTMLAttributes<HTMLDivElement>, 'class'
   'aria-label'?: string;
   /** Current text search query. When provided, the search field is controlled. */
   searchQuery?: string;
+  /** Whether to render the leading search field. Defaults to `true`. */
+  showSearch?: boolean;
   /** Placeholder text shown in the leading search field. */
   searchPlaceholder?: string;
   /** Accessible label for the search input. Defaults to 'Search'. */

package/src/components/navigation-bar/navigation-bar.svelte

@@ -208,7 +208,7 @@ function handleKeyDown(event) {
       {@render menuToggle({
         'aria-expanded': (mobileMenuOpen ? 'true' : 'false') as 'true' | 'false',
         'aria-controls': regionId,
-        ...(browser ? { onclick: handleToggle } : {}),
+        onclick: handleToggle,
       })}
     </div>
   {/if}
@@ -224,7 +224,7 @@ function handleKeyDown(event) {
       {@render menuToggle({
         'aria-expanded': (mobileMenuOpen ? 'true' : 'false') as 'true' | 'false',
         'aria-controls': regionId,
-        ...(browser ? { onclick: handleToggle } : {}),
+        onclick: handleToggle,
       })}
     </div>
   {/if}

package/src/components/run-step-timeline/run-step-timeline.svelte

@@ -10,11 +10,11 @@ import RunStepBranchDisclosure from './run-step-branch-disclosure.svelte';
 import Link from '../link/link.svelte';
 import Progress from '../progress/progress.svelte';
 import StatusDot from '../status-dot/status-dot.svelte';
-import { actionsCountLabel, badgeVariant, branchGroupHasCurrentStep, branchOutcomeSummary, branchStartsCollapsed, hasProgress, hiddenNestedStepLabel, isCurrent, isTerminal, laneOutcomeBadgeVariant, laneOutcomeLabel, metadataItems, safeStepLinkHref, statusDotStatus, statusLabel, } from './run-step-timeline.utilities.ts';
+import { actionsCountLabel, badgeVariant, branchGroupHasCurrentStep, branchOutcomeSummary, branchStartsCollapsed, hasProgress, hiddenNestedStepLabel, isCurrent, isTerminal, laneOutcomeBadgeVariant, laneOutcomeLabel, metadataItems, relocateCompensationEntries, relocateCompensationSteps, safeStepLinkHref, statusDotStatus, statusLabel, } from './run-step-timeline.utilities.ts';
 const MAX_NESTED_STEP_DEPTH = 3;
 let { steps, label, class: className, children, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledby, ...rest } = $props();
 const resolvedAriaLabel = $derived(ariaLabelledby === undefined && ariaLabel === undefined ? label : ariaLabel);
-const renderedEntries = $derived(flattenEntries(steps));
+const renderedEntries = $derived(flattenEntries(relocateCompensationEntries(steps)));
 function isBranchGroup(entry) {
     return 'kind' in entry && entry.kind === 'branch';
 }
@@ -128,7 +128,7 @@ function applyGlobalRailAriaCurrent(rows) {
 // compensation labels. Reused for the main rail and for each branch lane.
 function flattenSteps(list, pathPrefix) {
     const rows = [];
-    appendRunStepRows(rows, list, 0, pathPrefix);
+    appendRunStepRows(rows, relocateCompensationSteps(list), 0, pathPrefix);
     const currentRowIndex = deepestCurrentStepIndex(rows);
     // Index every step row by its unique path key (built from the escaped id
     // chain). A `compensates` id then resolves to a true SIBLING — a step under
@@ -174,7 +174,7 @@ function appendRunStepRows(rows, list, depth, pathPrefix) {
         rows.push({ kind: 'step', step, depth, pathKey });
         if (step.children && step.children.length > 0) {
             if (depth < MAX_NESTED_STEP_DEPTH) {
-                appendRunStepRows(rows, step.children, depth + 1, pathKey);
+                appendRunStepRows(rows, relocateCompensationSteps(step.children), depth + 1, pathKey);
             }
             else {
                 const hiddenSummary = summarizeNestedRunSteps(step.children);

package/src/components/run-step-timeline/run-step-timeline.utilities.ts

@@ -5,8 +5,76 @@ import type {
   RunStepBranchLane,
   RunStepBranchLaneOutcome,
   RunStepStatus,
+  RunStepTimelineEntry,
 } from './run-step-timeline.types.ts';
 
+/**
+ * Relocate resolved compensation steps immediately after the subtree of the
+ * sibling they reverse. Unresolved, self-referential, and cyclic links retain
+ * consumer order. Multiple compensations retain their relative input order.
+ */
+export function relocateCompensationSteps(steps: RunStep[]): RunStep[] {
+  return relocateSiblingItems(steps, (step) => step);
+}
+
+function relocateSiblingItems<T>(items: T[], getStep: (item: T) => RunStep | undefined): T[] {
+  if (!items.some((item) => getStep(item)?.compensates !== undefined)) return items;
+
+  const stepById = new Map<string, RunStep>();
+  for (const item of items) {
+    const step = getStep(item);
+    if (step !== undefined) {
+      stepById.set(step.id, step);
+    }
+  }
+  const canRelocate = (step: RunStep): boolean => {
+    const visited = new Set<string>([step.id]);
+    let targetId = step.compensates;
+    while (targetId !== undefined) {
+      const target = stepById.get(targetId);
+      if (target === undefined || visited.has(targetId)) return false;
+      visited.add(targetId);
+      targetId = target.compensates;
+    }
+    return true;
+  };
+  const relocatable = new Set<RunStep>();
+  const compensationsByTarget = new Map<string, T[]>();
+  for (const item of items) {
+    const step = getStep(item);
+    if (step === undefined || step.compensates === undefined || !canRelocate(step)) continue;
+    relocatable.add(step);
+    const compensations = compensationsByTarget.get(step.compensates) ?? [];
+    compensations.push(item);
+    compensationsByTarget.set(step.compensates, compensations);
+  }
+  const result: T[] = [];
+  const appendWithCompensations = (item: T): void => {
+    result.push(item);
+    const step = getStep(item);
+    if (step === undefined) return;
+    for (const compensation of compensationsByTarget.get(step.id) ?? []) {
+      appendWithCompensations(compensation);
+    }
+  };
+  for (const item of items) {
+    const step = getStep(item);
+    if (step === undefined || !relocatable.has(step)) appendWithCompensations(item);
+  }
+  return result;
+}
+
+/** Relocate top-level compensations while preserving branch rows as rail entries. */
+export function relocateCompensationEntries(
+  entries: RunStepTimelineEntry[],
+): RunStepTimelineEntry[] {
+  return relocateSiblingItems(entries, (entry) => (isBranchGroup(entry) ? undefined : entry));
+}
+
+function isBranchGroup(entry: RunStepTimelineEntry): entry is RunStepBranchGroup {
+  return 'kind' in entry && entry.kind === 'branch';
+}
+
 /** Badge variants used for the per-step status chip. */
 export type RunStepBadgeVariant = 'neutral' | 'success' | 'warning' | 'danger' | 'info' | 'accent';
 

package/src/components/side-navigation/side-navigation.css

@@ -13,6 +13,7 @@
  * ======================================== */
 
   .cinder-side-navigation {
+    --cinder-side-navigation-list-gap: var(--cinder-space-1);
     display: block;
   }
 
@@ -22,7 +23,7 @@
     padding: 0;
     display: flex;
     flex-direction: column;
-    gap: var(--cinder-space-1);
+    gap: var(--cinder-side-navigation-list-gap, var(--cinder-space-1));
   }
 
   /* ----------------------------------------

package/src/components/side-navigation/side-navigation.examples.json

@@ -9,6 +9,12 @@
       "description": "A grouped sidebar nav. Uses the SideNavigation namespace API: SideNavigation.Group wraps a collapsible section and SideNavigation.Item renders each link.",
       "code": "<script lang=\"ts\">\n  import { SideNavigation } from '@lostgradient/cinder/side-navigation';\n</script>\n\n<SideNavigation ariaLabel=\"Workspace\">\n  <SideNavigation.Item href=\"/dashboard\">Dashboard</SideNavigation.Item>\n  <SideNavigation.Group label=\"Projects\">\n    <SideNavigation.Item href=\"/projects/phoenix\" active>Phoenix</SideNavigation.Item>\n    <SideNavigation.Item href=\"/projects/atlas\">Atlas</SideNavigation.Item>\n    <SideNavigation.Item href=\"/projects/beacon\">Beacon</SideNavigation.Item>\n  </SideNavigation.Group>\n  <SideNavigation.Group label=\"Settings\">\n    <SideNavigation.Item href=\"/settings/team\">Team</SideNavigation.Item>\n    <SideNavigation.Item href=\"/settings/billing\">Billing</SideNavigation.Item>\n  </SideNavigation.Group>\n</SideNavigation>\n"
     },
+    {
+      "id": "compact-sidebar",
+      "title": "Compact sidebar spacing",
+      "description": "Dense sidebars can tune the SideNavigation list gap through a public CSS variable.",
+      "code": "<script lang=\"ts\">\n  import { SideNavigation } from '@lostgradient/cinder/side-navigation';\n</script>\n\n<div style=\"max-inline-size: 18rem;\">\n  <SideNavigation ariaLabel=\"Inspector sections\" style=\"--cinder-side-navigation-list-gap: 0;\">\n    <SideNavigation.Item href=\"#overview\" active>Overview</SideNavigation.Item>\n    <SideNavigation.Item href=\"#timeline\">Timeline</SideNavigation.Item>\n    <SideNavigation.Item href=\"#payload\">Payload</SideNavigation.Item>\n    <SideNavigation.Group label=\"Artifacts\">\n      <SideNavigation.Item href=\"#source\">Source</SideNavigation.Item>\n      <SideNavigation.Item href=\"#snapshot\">Snapshot</SideNavigation.Item>\n    </SideNavigation.Group>\n  </SideNavigation>\n</div>\n"
+    },
     {
       "id": "docs-sidebar",
       "title": "Docs sidebar",

package/src/components/side-navigation/side-navigation.schema.json

@@ -5,6 +5,14 @@
     "ariaLabel": {
       "type": "string",
       "description": "Accessible name for the <nav> landmark. Required, non-empty, distinct from other navs on the page."
+    },
+    "class": {
+      "type": "string",
+      "description": "Additional CSS class merged with `.cinder-side-navigation`."
+    },
+    "style": {
+      "type": "string",
+      "description": "Inline style string applied to the `.cinder-side-navigation` root."
     }
   },
   "additionalProperties": false,
@@ -16,11 +24,6 @@
         "reason": "function-or-snippet",
         "required": true,
         "description": "Must be <li> elements containing NavigationItem and/or SideNavigationGroup."
-      },
-      {
-        "name": "class",
-        "reason": "unknown-shape",
-        "description": "Additional CSS class merged with `.cinder-side-navigation`."
       }
     ]
   }

package/src/components/side-navigation/side-navigation.schema.ts

@@ -9,6 +9,14 @@ const schema = {
       description:
         'Accessible name for the <nav> landmark. Required, non-empty, distinct from other navs on the page.',
     },
+    class: {
+      type: 'string',
+      description: 'Additional CSS class merged with `.cinder-side-navigation`.',
+    },
+    style: {
+      type: 'string',
+      description: 'Inline style string applied to the `.cinder-side-navigation` root.',
+    },
   },
   additionalProperties: false,
   required: ['ariaLabel'],
@@ -20,11 +28,6 @@ const schema = {
         required: true,
         description: 'Must be <li> elements containing NavigationItem and/or SideNavigationGroup.',
       },
-      {
-        name: 'class',
-        reason: 'unknown-shape',
-        description: 'Additional CSS class merged with `.cinder-side-navigation`.',
-      },
     ],
   },
 } satisfies ComponentSchema;

package/src/components/side-navigation/side-navigation.types.ts

@@ -12,3 +12,15 @@ export type SideNavigationProps = Omit<
   /** Must be <li> elements containing NavigationItem and/or SideNavigationGroup. */
   children: Snippet;
 };
+
+/** Schema generator surface for SideNavigation — excludes native attributes except supported styling hooks. */
+export interface SideNavigationSchemaProps {
+  /** Accessible name for the <nav> landmark. Required, non-empty, distinct from other navs on the page. */
+  ariaLabel: string;
+  /** Additional CSS class merged with `.cinder-side-navigation`. */
+  class?: string;
+  /** Inline style string applied to the `.cinder-side-navigation` root. */
+  style?: string;
+  /** Must be <li> elements containing NavigationItem and/or SideNavigationGroup. */
+  children: Snippet;
+}

package/src/components/side-navigation/side-navigation.variables.json

@@ -1 +1 @@
-[]
+["--cinder-side-navigation-list-gap"]

package/src/components/side-navigation/side-navigation.variables.ts

@@ -1,3 +1,3 @@
-const variables: readonly string[] = [];
+const variables: readonly string[] = ['--cinder-side-navigation-list-gap'];
 
 export default variables;

package/src/components/stat/stat.css

@@ -1,17 +1,25 @@
 @layer cinder.tokens, cinder.foundation, cinder.components, cinder.utilities;
 @layer cinder.components {
   .cinder-stat {
+    --cinder-stat-row-gap: var(--cinder-space-1, 0.25rem);
+    --cinder-stat-column-gap: var(--cinder-space-3, 0.75rem);
+    --cinder-stat-label-font-size: var(--cinder-text-sm);
+    --cinder-stat-value-font-size: var(--cinder-text-4xl);
+    --cinder-stat-value-font-weight: var(--cinder-font-semibold);
+    --cinder-stat-value-line-height: 1.1;
+    --cinder-stat-change-gap: var(--cinder-space-1, 0.25rem);
+    --cinder-stat-change-font-size: var(--cinder-text-sm);
     display: grid;
     grid-template-columns: 1fr;
     grid-template-rows: auto auto auto;
-    row-gap: var(--cinder-space-1, 0.25rem);
+    row-gap: var(--cinder-stat-row-gap, var(--cinder-space-1, 0.25rem));
     align-items: start;
     color: var(--cinder-text);
   }
 
   .cinder-stat[data-cinder-has-icon] {
     grid-template-columns: auto 1fr;
-    column-gap: var(--cinder-space-3, 0.75rem);
+    column-gap: var(--cinder-stat-column-gap, var(--cinder-space-3, 0.75rem));
   }
 
   .cinder-stat__icon {
@@ -25,7 +33,7 @@
   }
 
   .cinder-stat__label {
-    font-size: var(--cinder-text-sm);
+    font-size: var(--cinder-stat-label-font-size, var(--cinder-text-sm));
     color: var(--cinder-text-muted);
   }
 
@@ -34,10 +42,10 @@
   }
 
   .cinder-stat__value {
-    font-size: var(--cinder-text-4xl);
-    font-weight: var(--cinder-font-semibold);
+    font-size: var(--cinder-stat-value-font-size, var(--cinder-text-4xl));
+    font-weight: var(--cinder-stat-value-font-weight, var(--cinder-font-semibold));
     font-variant-numeric: tabular-nums;
-    line-height: 1.1;
+    line-height: var(--cinder-stat-value-line-height, 1.1);
   }
 
   .cinder-stat[data-cinder-has-icon] .cinder-stat__value {
@@ -47,8 +55,8 @@
   .cinder-stat__change {
     display: inline-flex;
     align-items: center;
-    gap: var(--cinder-space-1, 0.25rem);
-    font-size: var(--cinder-text-sm);
+    gap: var(--cinder-stat-change-gap, var(--cinder-space-1, 0.25rem));
+    font-size: var(--cinder-stat-change-font-size, var(--cinder-text-sm));
   }
 
   .cinder-stat[data-cinder-has-icon] .cinder-stat__change {

package/src/components/stat/stat.schema.json

@@ -24,6 +24,10 @@
     "class": {
       "type": "string",
       "description": "Additional class names merged with `.cinder-stat`."
+    },
+    "style": {
+      "type": "string",
+      "description": "Inline style string applied to the `.cinder-stat` root."
     }
   },
   "additionalProperties": false,

package/src/components/stat/stat.schema.ts

@@ -28,6 +28,10 @@ const schema = {
       type: 'string',
       description: 'Additional class names merged with `.cinder-stat`.',
     },
+    style: {
+      type: 'string',
+      description: 'Inline style string applied to the `.cinder-stat` root.',
+    },
   },
   additionalProperties: false,
   required: ['label', 'value'],

package/src/components/stat/stat.types.ts

@@ -33,3 +33,23 @@ export type StatProps = Omit<HTMLAttributes<HTMLDivElement>, 'class'> & {
   /** Additional class names merged with `.cinder-stat`. */
   class?: string;
 };
+
+/** Schema generator surface for Stat — excludes native attributes except supported styling hooks. */
+export interface StatSchemaProps {
+  /** Short label describing the metric, e.g. "Monthly Revenue". */
+  label: string;
+  /** The statistic. Strings rendered verbatim; numbers formatted via formatNumber. */
+  value: string | number;
+  /** Optional change indicator with direction and accessible wording. */
+  change?: StatChange;
+  /** Optional leading icon snippet (decorative — wrapper is aria-hidden). */
+  icon?: Snippet;
+  /** Intl.NumberFormat options applied only when `value` is a number. */
+  valueFormatOptions?: Intl.NumberFormatOptions;
+  /** Locale forwarded to formatNumber. Defaults to the nearest LocaleProvider locale, then en-US. */
+  valueLocale?: string;
+  /** Additional class names merged with `.cinder-stat`. */
+  class?: string;
+  /** Inline style string applied to the `.cinder-stat` root. */
+  style?: string;
+}

package/src/components/stat/stat.variables.json

@@ -1 +1,10 @@
-[]
+[
+  "--cinder-stat-change-font-size",
+  "--cinder-stat-change-gap",
+  "--cinder-stat-column-gap",
+  "--cinder-stat-label-font-size",
+  "--cinder-stat-row-gap",
+  "--cinder-stat-value-font-size",
+  "--cinder-stat-value-font-weight",
+  "--cinder-stat-value-line-height"
+]

package/src/components/stat/stat.variables.ts

@@ -1,3 +1,12 @@
-const variables: readonly string[] = [];
+const variables: readonly string[] = [
+  '--cinder-stat-change-font-size',
+  '--cinder-stat-change-gap',
+  '--cinder-stat-column-gap',
+  '--cinder-stat-label-font-size',
+  '--cinder-stat-row-gap',
+  '--cinder-stat-value-font-size',
+  '--cinder-stat-value-font-weight',
+  '--cinder-stat-value-line-height',
+];
 
 export default variables;

package/src/components/stat-group/stat-group.css

@@ -1,8 +1,11 @@
 @layer cinder.tokens, cinder.foundation, cinder.components, cinder.utilities;
 @layer cinder.components {
   .cinder-stat-group {
+    --cinder-stat-group-gap: var(--cinder-space-4, 1rem);
+    --cinder-stat-group-card-padding: var(--cinder-space-4, 1rem);
+    --cinder-stat-group-shared-cell-padding: var(--cinder-space-4, 1rem);
     display: grid;
-    gap: var(--cinder-space-4, 1rem);
+    gap: var(--cinder-stat-group-gap, var(--cinder-space-4, 1rem));
     /* Query the group's own inline size so fixed column counts can collapse when
        the group is narrow — even inside a wide viewport (RESPONSIVE-POLICY.md). */
     container-type: inline-size;
@@ -50,7 +53,7 @@
 
   /* variant: cards — each stat gets a card-style border, background, and shadow */
   .cinder-stat-group[data-cinder-variant='cards'] > .cinder-stat {
-    padding: var(--cinder-space-4, 1rem);
+    padding: var(--cinder-stat-group-card-padding, var(--cinder-space-4, 1rem));
     background: var(--cinder-surface-raised);
     border: 1px solid var(--cinder-border);
     border-radius: var(--cinder-radius-md, 0.5rem);
@@ -63,15 +66,15 @@
  * gap with the surface color, avoiding nth-child math for any column count.
  */
   .cinder-stat-group[data-cinder-variant='shared-borders'] {
+    --cinder-stat-group-gap: 1px;
     border: 1px solid var(--cinder-border);
     border-radius: var(--cinder-radius-md, 0.5rem);
     overflow: hidden;
     background: var(--cinder-border);
-    gap: 1px;
   }
 
   .cinder-stat-group[data-cinder-variant='shared-borders'] > .cinder-stat {
-    padding: var(--cinder-space-4, 1rem);
+    padding: var(--cinder-stat-group-shared-cell-padding, var(--cinder-space-4, 1rem));
     background: var(--cinder-surface-raised);
   }
 }

package/src/components/stat-group/stat-group.examples.json

@@ -21,6 +21,12 @@
       "description": "The `cards` variant renders each metric as a discrete bordered card, separating the tiles instead of laying them out edge-to-edge in a shared grid.",
       "code": "<script lang=\"ts\">\n  import { StatGroup } from '@lostgradient/cinder/stat-group';\n</script>\n\n<StatGroup label=\"This quarter\" columns={3} variant=\"cards\">\n  <StatGroup.Stat label=\"Projects\" value={42} />\n  <StatGroup.Stat label=\"Members\" value={18} />\n  <StatGroup.Stat label=\"Storage\" value=\"64 GB\" />\n</StatGroup>\n"
     },
+    {
+      "id": "compact-summary",
+      "title": "Compact summary strip",
+      "description": "Dense summaries can tune StatGroup spacing and Stat typography through public CSS variables.",
+      "code": "<script lang=\"ts\">\n  import { StatGroup } from '@lostgradient/cinder/stat-group';\n</script>\n\n<StatGroup\n  label=\"Workflow summary\"\n  columns={4}\n  variant=\"shared-borders\"\n  style=\"--cinder-stat-group-gap: 1px; --cinder-stat-group-shared-cell-padding: var(--cinder-space-2);\"\n>\n  <StatGroup.Stat\n    label=\"Events\"\n    value={128}\n    style=\"--cinder-stat-row-gap: 0; --cinder-stat-label-font-size: var(--cinder-text-xs); --cinder-stat-value-font-size: var(--cinder-text-lg); --cinder-stat-change-font-size: var(--cinder-text-xs);\"\n  />\n  <StatGroup.Stat\n    label=\"Matched\"\n    value={42}\n    style=\"--cinder-stat-row-gap: 0; --cinder-stat-label-font-size: var(--cinder-text-xs); --cinder-stat-value-font-size: var(--cinder-text-lg); --cinder-stat-change-font-size: var(--cinder-text-xs);\"\n  />\n  <StatGroup.Stat\n    label=\"Retries\"\n    value={3}\n    style=\"--cinder-stat-row-gap: 0; --cinder-stat-label-font-size: var(--cinder-text-xs); --cinder-stat-value-font-size: var(--cinder-text-lg); --cinder-stat-change-font-size: var(--cinder-text-xs);\"\n  />\n  <StatGroup.Stat\n    label=\"Latency\"\n    value=\"184 ms\"\n    style=\"--cinder-stat-row-gap: 0; --cinder-stat-label-font-size: var(--cinder-text-xs); --cinder-stat-value-font-size: var(--cinder-text-lg); --cinder-stat-change-font-size: var(--cinder-text-xs);\"\n  />\n</StatGroup>\n"
+    },
     {
       "id": "shared-borders-variant",
       "title": "Shared-borders variant",

package/src/components/stat-group/stat-group.schema.json

@@ -19,6 +19,10 @@
     "class": {
       "type": "string",
       "description": "Additional class names merged with `.cinder-stat-group`."
+    },
+    "style": {
+      "type": "string",
+      "description": "Inline style string applied to the `.cinder-stat-group` root."
     }
   },
   "additionalProperties": false,