@lostgradient/cinder 0.5.0 → 0.7.0

package/src/components/stats-section/stats-section.svelte

@@ -1,67 +1,28 @@
 <script lang="ts" module>
-  /**
-   * @cinder
-   * @category domain
-   * @status stable
-   * @purpose Marketing metrics section that wraps StatGroup/Stat to present headline numbers with optional trend indicators.
-   * @tag marketing
-   * @tag metrics
-   * @tag stats
-   * @useWhen Showing key outcomes such as uptime, customers, revenue, or latency in landing-page copy.
-   * @useWhen Presenting a short metrics band between hero/features and pricing sections.
-   * @avoidWhen Comparing plan pricing and feature lists across tiers. | pricing-section
-   * @avoidWhen Rendering freeform cards that are not structured numeric metrics. | feature-section
-   * @related stat, stat-group, pricing-section, feature-section, container
-   */
-  export type { StatsSectionItem, StatsSectionProps } from './stats-section.types.ts';
+export {};
 </script>
 
 <script lang="ts">
-  import Container from '../container/container.svelte';
-  import Stat from '../stat/stat.svelte';
-  import StatGroup from '../stat-group/stat-group.svelte';
-  import { classNames } from '../../utilities/class-names.ts';
-
-  import type { StatsSectionProps } from './stats-section.types.ts';
-
-  let {
-    as = 'section',
-    title,
-    description,
-    stats,
-    columns = 'auto',
-    variant = 'cards',
-    label = 'Key metrics',
-    maxWidth = 'wide',
-    class: className,
-    ...rest
-  }: StatsSectionProps = $props();
-
-  function statChange(
-    item: StatsSectionProps['stats'][number],
-  ):
-    | { value: string; direction: NonNullable<typeof item.changeDirection>; description?: string }
-    | undefined {
-    if (!item.changeValue || !item.changeDirection) return undefined;
+import Container from '../container/container.svelte';
+import Stat from '../stat/stat.svelte';
+import StatGroup from '../stat-group/stat-group.svelte';
+import { classNames } from '../../utilities/class-names.ts';
+let { as = 'section', title, description, stats, columns = 'auto', variant = 'cards', label = 'Key metrics', maxWidth = 'wide', class: className, ...rest } = $props();
+function statChange(item) {
+    if (!item.changeValue || !item.changeDirection)
+        return undefined;
     return item.changeDescription
-      ? {
-          value: item.changeValue,
-          direction: item.changeDirection,
-          description: item.changeDescription,
+        ? {
+            value: item.changeValue,
+            direction: item.changeDirection,
+            description: item.changeDescription,
         }
-      : { value: item.changeValue, direction: item.changeDirection };
-  }
-
-  function optionalStatProps(item: StatsSectionProps['stats'][number]): {
-    change?: {
-      value: string;
-      direction: NonNullable<typeof item.changeDirection>;
-      description?: string;
-    };
-  } {
+        : { value: item.changeValue, direction: item.changeDirection };
+}
+function optionalStatProps(item) {
     const change = statChange(item);
     return change ? { change } : {};
-  }
+}
 </script>
 
 <svelte:element this={as} class={classNames('cinder-stats-section', className)} {...rest}>

package/src/components/stats-section/stats-section.variables.json

@@ -0,0 +1 @@
+[]

package/src/components/stats-section/stats-section.variables.ts

@@ -0,0 +1,3 @@
+const variables: readonly string[] = [];
+
+export default variables;

package/src/components/status-dot/status-dot.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "status": {
+      "enum": ["online", "offline", "warning", "danger", "pending", "neutral", "success", "accent"],
+      "description": "Semantic status. Drives color via `data-cinder-status`; defaults to a neutral dot or derives from `connectionState`. `success` maps to `--cinder-success`; `accent` maps to `--cinder-accent`."
+    },
+    "connectionState": {
+      "enum": ["connected", "connecting", "disconnected", "error"],
+      "description": "Realtime connection preset. Sets status, default label, and live-region semantics."
+    },
+    "label": {
+      "type": "string",
+      "description": "Optional human label. Rendered visibly when `showLabel` is true; used as the accessible name either way."
+    },
+    "showLabel": {
+      "type": "boolean",
+      "description": "Whether to render the visible label.",
+      "default": true
+    },
+    "live": {
+      "type": "boolean",
+      "description": "Use role=\"status\" with polite live-region attributes. Defaults true when connectionState is provided."
+    },
+    "size": {
+      "enum": ["sm", "md"],
+      "description": "Dot size.",
+      "default": "md"
+    },
+    "class": {
+      "type": "string",
+      "description": "Extra classes appended to the root element."
+    }
+  },
+  "additionalProperties": false
+}

package/src/components/status-dot/status-dot.schema.ts

@@ -0,0 +1,45 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    status: {
+      enum: ['online', 'offline', 'warning', 'danger', 'pending', 'neutral', 'success', 'accent'],
+      description:
+        'Semantic status. Drives color via `data-cinder-status`; defaults to a neutral dot or derives from `connectionState`. `success` maps to `--cinder-success`; `accent` maps to `--cinder-accent`.',
+    },
+    connectionState: {
+      enum: ['connected', 'connecting', 'disconnected', 'error'],
+      description:
+        'Realtime connection preset. Sets status, default label, and live-region semantics.',
+    },
+    label: {
+      type: 'string',
+      description:
+        'Optional human label. Rendered visibly when `showLabel` is true; used as the accessible name either way.',
+    },
+    showLabel: {
+      type: 'boolean',
+      description: 'Whether to render the visible label.',
+      default: true,
+    },
+    live: {
+      type: 'boolean',
+      description:
+        'Use role="status" with polite live-region attributes. Defaults true when connectionState is provided.',
+    },
+    size: {
+      enum: ['sm', 'md'],
+      description: 'Dot size.',
+      default: 'md',
+    },
+    class: {
+      type: 'string',
+      description: 'Extra classes appended to the root element.',
+    },
+  },
+  additionalProperties: false,
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

package/src/components/status-dot/status-dot.svelte

@@ -1,81 +1,36 @@
 <script lang="ts" module>
-  /**
-   * @cinder
-   * @category feedback
-   * @status stable
-   * @purpose Colored dot indicator that communicates static entity state or live realtime connection state with an accessible text label.
-   * @tag connection
-   * @tag feedback
-   * @tag realtime
-   * @tag status
-   * @useWhen Indicating the current state of a list row, user, deployment, or other entity alongside its name.
-   * @useWhen Communicating status compactly when many indicators appear together without triggering live-region announcements.
-   * @useWhen Surfacing whether a realtime channel is connected, connecting, disconnected, or errored on a dashboard or app chrome.
-   * @useWhen Giving operators an at-a-glance health signal for a long-lived transport.
-   * @avoidWhen Counting items or showing a numeric value — use badge instead.
-   * @avoidWhen Announcing a transient status change — use toast-region or alert so assistive tech reads it.
-   * @related badge
-   */
-  export type { StatusDotProps, StatusDotSize, StatusDotStatus } from './status-dot.types.ts';
+export {};
 </script>
 
 <script lang="ts">
-  import { classNames } from '../../utilities/class-names.ts';
-  import type {
-    StatusDotConnectionState,
-    StatusDotProps,
-    StatusDotStatus,
-  } from './status-dot.types.ts';
-
-  const connectionStatusMap: Record<StatusDotConnectionState, StatusDotStatus> = {
+import { classNames } from '../../utilities/class-names.ts';
+const connectionStatusMap = {
     connected: 'online',
     connecting: 'warning',
     disconnected: 'offline',
     error: 'danger',
-  };
-
-  const connectionLabels: Record<StatusDotConnectionState, string> = {
+};
+const connectionLabels = {
     connected: 'Connected',
     connecting: 'Connecting',
     disconnected: 'Disconnected',
     error: 'Error',
-  };
-
-  let {
-    status,
-    connectionState,
-    label,
-    live,
-    showLabel = true,
-    size = 'md',
-    class: className,
-    'aria-label': ariaLabel,
-    ...rest
-  }: StatusDotProps = $props();
-
-  const normalizedAriaLabel = $derived(ariaLabel?.trim() ? ariaLabel.trim() : undefined);
-  const resolvedStatus = $derived(
-    status ?? (connectionState === undefined ? 'neutral' : connectionStatusMap[connectionState]),
-  );
-  const resolvedLive = $derived(live ?? connectionState !== undefined);
-  const normalizedLabel = $derived(
-    label?.trim()
-      ? label.trim()
-      : connectionState === undefined
+};
+let { status, connectionState, label, live, showLabel = true, size = 'md', class: className, 'aria-label': ariaLabel, ...rest } = $props();
+const normalizedAriaLabel = $derived(ariaLabel?.trim() ? ariaLabel.trim() : undefined);
+const resolvedStatus = $derived(status ?? (connectionState === undefined ? 'neutral' : connectionStatusMap[connectionState]));
+const resolvedLive = $derived(live ?? connectionState !== undefined);
+const normalizedLabel = $derived(label?.trim()
+    ? label.trim()
+    : connectionState === undefined
         ? undefined
-        : connectionLabels[connectionState],
-  );
-  const hasVisibleLabel = $derived(showLabel && normalizedLabel !== undefined);
-
-  // `role="img"` needs an author-provided name. Blank labels are treated as
-  // absent so status is never communicated by color alone.
-  const resolvedAriaLabel = $derived(normalizedAriaLabel ?? normalizedLabel ?? resolvedStatus);
-  const visibleLabelIsLiveDuplicate = $derived(
-    resolvedLive && normalizedLabel !== undefined && resolvedAriaLabel !== normalizedLabel,
-  );
-  const needsHiddenLiveLabel = $derived(
-    resolvedLive && (!hasVisibleLabel || visibleLabelIsLiveDuplicate),
-  );
+        : connectionLabels[connectionState]);
+const hasVisibleLabel = $derived(showLabel && normalizedLabel !== undefined);
+// `role="img"` needs an author-provided name. Blank labels are treated as
+// absent so status is never communicated by color alone.
+const resolvedAriaLabel = $derived(normalizedAriaLabel ?? normalizedLabel ?? resolvedStatus);
+const visibleLabelIsLiveDuplicate = $derived(resolvedLive && normalizedLabel !== undefined && resolvedAriaLabel !== normalizedLabel);
+const needsHiddenLiveLabel = $derived(resolvedLive && (!hasVisibleLabel || visibleLabelIsLiveDuplicate));
 </script>
 
 <!--

package/src/components/status-dot/status-dot.variables.json

@@ -0,0 +1 @@
+["--cinder-status-dot-color", "--cinder-status-dot-size"]

package/src/components/status-dot/status-dot.variables.ts

@@ -0,0 +1,3 @@
+const variables: readonly string[] = ['--cinder-status-dot-color', '--cinder-status-dot-size'];
+
+export default variables;

package/src/components/steps/index.ts

@@ -2,5 +2,5 @@ import './steps.css';
 import Steps from './steps.svelte';
 
 export default Steps;
-export type { StepItem, StepsOrientation, StepsProps } from './steps.types.ts';
+export type { StepItem, StepItemState, StepsOrientation, StepsProps } from './steps.types.ts';
 export { Steps };

package/src/components/steps/steps.css

@@ -203,6 +203,19 @@
     }
   }
 
+  [data-cinder-state='skipped'] .cinder-steps__marker {
+    background: var(--cinder-surface);
+    box-shadow: inset 0 0 0 1px var(--cinder-border-muted);
+    color: var(--cinder-text-muted);
+  }
+
+  @media (forced-colors: active) {
+    [data-cinder-state='skipped'] .cinder-steps__marker {
+      outline: 1px solid ButtonText;
+      box-shadow: none;
+    }
+  }
+
   [data-cinder-state='upcoming'] .cinder-steps__marker {
     color: var(--cinder-text-muted);
   }
@@ -301,6 +314,7 @@
     font-weight: var(--cinder-font-semibold);
   }
 
+  [data-cinder-state='skipped'] .cinder-steps__label,
   [data-cinder-state='upcoming'] .cinder-steps__label {
     color: var(--cinder-text-muted);
   }
@@ -326,7 +340,7 @@
   }
 
   /* ----------------------------------------
- * Visually-hidden text for completed steps
+ * Visually-hidden text for completed and skipped steps
  * ---------------------------------------- */
 
   .cinder-steps__sr-only,

package/src/components/steps/steps.examples.json

@@ -15,6 +15,12 @@
       "description": "A step becomes navigable when its `StepItem` carries an `href` (renders the body as a link) or an `onclick` (renders it as a button). The marker and connector stay decorative — only the body region is the focusable, clickable target.",
       "code": "<script lang=\"ts\">\n  import { Steps } from '@lostgradient/cinder/steps';\n  import type { StepItem } from '@lostgradient/cinder/steps';\n\n  let current = $state(1);\n\n  const steps: StepItem[] = [\n    { id: 'account', label: 'Account', description: 'Create your login', href: '#account' },\n    {\n      id: 'profile',\n      label: 'Profile',\n      description: 'Jump back to edit',\n      onclick: () => (current = 1),\n    },\n    { id: 'review', label: 'Review', description: 'Confirm and submit' },\n  ];\n</script>\n\n<Steps {steps} currentStep={current} label=\"Onboarding\" />\n"
     },
+    {
+      "id": "skipped",
+      "title": "Skipped step",
+      "description": "Use `state: \"skipped\"` when a flow advances past a step without completing it.",
+      "code": "<script lang=\"ts\">\n  import { Steps } from '@lostgradient/cinder/steps';\n  import type { StepItem } from '@lostgradient/cinder/steps';\n\n  const steps: StepItem[] = [\n    { id: 'account', label: 'Account', description: 'Create your login' },\n    {\n      id: 'profile',\n      label: 'Profile',\n      description: 'Optional details were skipped',\n      state: 'skipped',\n    },\n    { id: 'review', label: 'Review', description: 'Confirm and submit' },\n  ];\n</script>\n\n<Steps {steps} currentStep={2} label=\"Onboarding\" />\n"
+    },
     {
       "id": "vertical",
       "title": "Vertical orientation",

package/src/components/steps/steps.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "currentStep": {
+      "type": "number",
+      "description": "Zero-based index of the active step. Steps with index < currentStep are\n\"completed\". Pass `steps.length` to mark every step as complete (terminal\n\"done\" state)."
+    },
+    "orientation": {
+      "enum": ["horizontal", "vertical"],
+      "description": "Layout direction. Defaults to 'horizontal'."
+    },
+    "label": {
+      "type": "string",
+      "description": "Accessible name for the wrapping nav landmark. Defaults to 'Progress'."
+    },
+    "completedLabel": {
+      "type": "string",
+      "description": "Visually-hidden text prepended to completed steps so screen readers\nannounce state + label. Defaults to 'Completed'."
+    },
+    "skippedLabel": {
+      "type": "string",
+      "description": "Visually-hidden text prepended to skipped steps so screen readers announce\nstate + label. Defaults to 'Skipped'."
+    },
+    "class": {
+      "type": "string",
+      "description": "Additional class names merged with `.cinder-steps`."
+    }
+  },
+  "additionalProperties": false,
+  "required": ["currentStep"],
+  "metadata": {
+    "unsupportedProps": [
+      {
+        "name": "steps",
+        "reason": "unknown-shape",
+        "required": true,
+        "description": "Ordered list of step entries from first to last."
+      }
+    ]
+  }
+}

package/src/components/steps/steps.schema.ts

@@ -0,0 +1,49 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    currentStep: {
+      type: 'number',
+      description:
+        'Zero-based index of the active step. Steps with index < currentStep are\n"completed". Pass `steps.length` to mark every step as complete (terminal\n"done" state).',
+    },
+    orientation: {
+      enum: ['horizontal', 'vertical'],
+      description: "Layout direction. Defaults to 'horizontal'.",
+    },
+    label: {
+      type: 'string',
+      description: "Accessible name for the wrapping nav landmark. Defaults to 'Progress'.",
+    },
+    completedLabel: {
+      type: 'string',
+      description:
+        "Visually-hidden text prepended to completed steps so screen readers\nannounce state + label. Defaults to 'Completed'.",
+    },
+    skippedLabel: {
+      type: 'string',
+      description:
+        "Visually-hidden text prepended to skipped steps so screen readers announce\nstate + label. Defaults to 'Skipped'.",
+    },
+    class: {
+      type: 'string',
+      description: 'Additional class names merged with `.cinder-steps`.',
+    },
+  },
+  additionalProperties: false,
+  required: ['currentStep'],
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'steps',
+        reason: 'unknown-shape',
+        required: true,
+        description: 'Ordered list of step entries from first to last.',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

package/src/components/steps/steps.svelte

@@ -1,48 +1,23 @@
 <script lang="ts" module>
-  /**
-   * @cinder
-   * @category navigation
-   * @status stable
-   * @purpose Ordered progress indicator that visualizes a fixed sequence of steps with completed, current, and upcoming states.
-   * @tag navigation
-   * @tag progress
-   * @useWhen Walking the user through a multi-step wizard or checkout flow with strict ordering.
-   * @useWhen Showing how far the user has advanced through a known number of stages.
-   * @avoidWhen Switching between independent peer views with no order — use tabs instead.
-   * @avoidWhen Showing ancestor hierarchy of the current page — use breadcrumbs instead.
-   * @related tabs, breadcrumbs, pagination
-   */
-  export type { StepItem, StepsOrientation, StepsProps } from './steps.types.ts';
+export {};
 </script>
 
 <script lang="ts">
-  import type { StepsProps } from './steps.types.ts';
-  import { classNames } from '../../utilities/class-names.ts';
-  import Check from 'lucide-svelte/icons/check';
-
-  let {
-    steps,
-    currentStep,
-    orientation = 'horizontal',
-    label = 'Progress',
-    completedLabel = 'Completed',
-    class: className,
-  }: StepsProps = $props();
-
-  const clampedCurrent = $derived(
-    steps.length === 0 ? undefined : Math.max(0, Math.min(steps.length, currentStep)),
-  );
-
-  type StepState = 'complete' | 'current' | 'upcoming';
-
-  const stepStates = $derived<StepState[]>(
-    steps.map((_, index) => {
-      if (clampedCurrent === undefined) return 'upcoming';
-      if (index < clampedCurrent) return 'complete';
-      if (index === clampedCurrent) return 'current';
-      return 'upcoming';
-    }),
-  );
+import { classNames } from '../../utilities/class-names.ts';
+import Check from 'lucide-svelte/icons/check';
+let { steps, currentStep, orientation = 'horizontal', label = 'Progress', completedLabel = 'Completed', skippedLabel = 'Skipped', class: className, } = $props();
+const clampedCurrent = $derived(steps.length === 0 ? undefined : Math.max(0, Math.min(steps.length, currentStep)));
+const stepStates = $derived(steps.map((step, index) => {
+    if (clampedCurrent === undefined)
+        return 'upcoming';
+    if (index === clampedCurrent)
+        return 'current';
+    if (step.state === 'skipped' && index < clampedCurrent)
+        return 'skipped';
+    if (index < clampedCurrent)
+        return 'complete';
+    return 'upcoming';
+}));
 </script>
 
 <nav
@@ -52,9 +27,11 @@
 >
   <ol class="cinder-steps__list">
     {#each steps as step, index (step.id)}
-      {@const state = stepStates[index]}
+      {@const state = stepStates[index] ?? 'upcoming'}
       {@const isCurrent = state === 'current'}
       {@const isComplete = state === 'complete'}
+      {@const connectorState =
+        clampedCurrent !== undefined && index < clampedCurrent ? 'complete' : 'upcoming'}
       {@const hasHref = step.href !== undefined}
       {@const isInteractive = hasHref || step.onclick !== undefined}
       {@const stepLabel = step.label}
@@ -78,7 +55,7 @@
             onclick={step.onclick}
             aria-current={isCurrent ? 'step' : undefined}
           >
-            {@render stepBody(stepLabel, stepDescription, isComplete, completedLabel)}
+            {@render stepBody(stepLabel, stepDescription, state, completedLabel, skippedLabel)}
           </a>
         {:else if step.onclick}
           <button
@@ -87,17 +64,17 @@
             onclick={step.onclick}
             aria-current={isCurrent ? 'step' : undefined}
           >
-            {@render stepBody(stepLabel, stepDescription, isComplete, completedLabel)}
+            {@render stepBody(stepLabel, stepDescription, state, completedLabel, skippedLabel)}
           </button>
         {:else}
           <span class="cinder-steps__body">
-            {@render stepBody(stepLabel, stepDescription, isComplete, completedLabel)}
+            {@render stepBody(stepLabel, stepDescription, state, completedLabel, skippedLabel)}
           </span>
         {/if}
         {#if index < steps.length - 1}
           <span
             class="cinder-steps__connector"
-            data-cinder-state={isComplete ? 'complete' : 'upcoming'}
+            data-cinder-state={connectorState}
             aria-hidden="true"
           ></span>
         {/if}
@@ -109,13 +86,17 @@
 {#snippet stepBody(
   bodyLabel: string,
   bodyDescription: string | undefined,
-  bodyIsComplete: boolean,
+  bodyState: StepItemState,
   bodyCompletedLabel: string,
+  bodySkippedLabel: string,
 )}
   <span class="cinder-steps__body-content">
-    {#if bodyIsComplete}
+    {#if bodyState === 'complete'}
       <span class="cinder-steps__sr-only">{bodyCompletedLabel}</span>
       <span class="cinder-steps__sr-only-separator"> </span>
+    {:else if bodyState === 'skipped'}
+      <span class="cinder-steps__sr-only">{bodySkippedLabel}</span>
+      <span class="cinder-steps__sr-only-separator"> </span>
     {/if}
     <span class="cinder-steps__label">{bodyLabel}</span>
     {#if bodyDescription}

package/src/components/steps/steps.types.ts

@@ -1,4 +1,5 @@
 export type StepsOrientation = 'horizontal' | 'vertical';
+export type StepItemState = 'complete' | 'current' | 'upcoming' | 'skipped';
 export type StepItem = {
   /** Stable identifier used as the keyed-each key. Must be unique. */
   id: string;
@@ -6,6 +7,12 @@ export type StepItem = {
   label: string;
   /** Optional secondary text shown beneath the label. */
   description?: string;
+  /**
+   * Optional state override for this step. When omitted, state is derived from
+   * `currentStep`. Use `skipped` for a past step that was advanced past without
+   * completing.
+   */
+  state?: 'skipped';
   /**
    * When set, the step body renders as a link (`<a>`) to this href. The marker
    * and connector stay decorative; only the body (label + description) is the
@@ -37,6 +44,11 @@ export type StepsProps = {
    * announce state + label. Defaults to 'Completed'.
    */
   completedLabel?: string;
+  /**
+   * Visually-hidden text prepended to skipped steps so screen readers announce
+   * state + label. Defaults to 'Skipped'.
+   */
+  skippedLabel?: string;
   /** Additional class names merged with `.cinder-steps`. */
   class?: string;
 };

package/src/components/steps/steps.variables.json

@@ -0,0 +1 @@
+[]

package/src/components/steps/steps.variables.ts

@@ -0,0 +1,3 @@
+const variables: readonly string[] = [];
+
+export default variables;

package/src/components/surface/surface.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "tone": {
+      "enum": ["default", "raised", "inset", "transparent"],
+      "description": "Surface tone.",
+      "default": "default"
+    },
+    "class": {
+      "type": "string",
+      "description": "Additional CSS classes"
+    }
+  },
+  "additionalProperties": false,
+  "metadata": {
+    "unsupportedProps": [
+      {
+        "name": "children",
+        "reason": "function-or-snippet",
+        "description": "Content rendered inside the surface container."
+      }
+    ]
+  }
+}