@lostgradient/cinder 0.1.0 → 0.2.0

package/src/components/area-chart/area-chart.svelte

@@ -24,7 +24,12 @@
     dataTableClass,
     formatNumericValue,
     legendVisible,
+    type ChartTarget,
   } from '../../_internal/chart/chart-utilities.ts';
+  import {
+    DEFAULT_CHART_FOCUS_RING_STROKE_PADDING,
+    createPointFocusRingGeometry,
+  } from '../../_internal/chart/chart-focus-ring.ts';
   import { ChartInteraction } from '../../_internal/chart/chart-interaction.svelte.ts';
   import { classNames } from '../../utilities/class-names.ts';
   import type { AreaChartProps } from './area-chart.types.ts';
@@ -86,6 +91,28 @@
       ? `${rootId}-table-guidance`
       : undefined,
   );
+  const focusedTarget = $derived.by(() => {
+    const currentTarget = interaction.focusedTarget;
+    if (!currentTarget) return undefined;
+    return model.targets.find((target) => target.id === currentTarget.id);
+  });
+  let keyboardFocusModality = $state(false);
+  let focusVisibleTargetId = $state<string>();
+  const focusRingTarget = $derived(
+    keyboardFocusModality && focusedTarget && focusVisibleTargetId === focusedTarget.id
+      ? focusedTarget
+      : undefined,
+  );
+  const pointFocusRing = $derived(
+    focusRingTarget
+      ? createPointFocusRingGeometry({
+          target: focusRingTarget,
+          plotWidth: model.geometry.plotWidth,
+          plotHeight: model.geometry.plotHeight,
+          strokePadding: DEFAULT_CHART_FOCUS_RING_STROKE_PADDING,
+        })
+      : null,
+  );
 
   $effect(() => {
     assertValidNonNegativeInteger(
@@ -99,8 +126,44 @@
   $effect(() => {
     interaction.clearStaleTargets(loading, model.empty, model.targets);
   });
+
+  function rememberKeyboardFocusModality(event: KeyboardEvent): void {
+    if (
+      event.key === 'Tab' ||
+      event.key === 'Home' ||
+      event.key === 'End' ||
+      event.key.startsWith('Arrow')
+    ) {
+      keyboardFocusModality = true;
+    }
+  }
+
+  function clearKeyboardFocusModality(): void {
+    keyboardFocusModality = false;
+    focusVisibleTargetId = undefined;
+  }
+
+  function handleTargetFocus(target: ChartTarget): void {
+    interaction.focusedTarget = target;
+    focusVisibleTargetId = keyboardFocusModality ? target.id : undefined;
+  }
+
+  function handleTargetBlur(): void {
+    interaction.focusedTarget = undefined;
+    focusVisibleTargetId = undefined;
+  }
+
+  function handleTargetKeydown(event: KeyboardEvent): void {
+    rememberKeyboardFocusModality(event);
+    interaction.activateByKeyboard(event, rootElement!, model.targets, keyboardEnabled);
+  }
 </script>
 
+<svelte:window
+  onkeydown={rememberKeyboardFocusModality}
+  onpointerdown={clearKeyboardFocusModality}
+/>
+
 <figure
   {...rest}
   bind:this={rootElement}
@@ -149,7 +212,7 @@
         <title id="{rootId}-svg-title">{label}</title>
       {/if}
       <g transform={`translate(${model.geometry.marginLeft}, ${model.geometry.marginTop})`}>
-        {#each model.yTicks as tick, index}
+        {#each model.yTicks as tick, index (tick)}
           {@const tickY =
             model.geometry.plotHeight -
             ((tick - model.yDomain[0]) / (model.yDomain[1] - model.yDomain[0])) *
@@ -228,23 +291,78 @@
                 tabindex="0"
                 role="button"
                 data-cinder-target-id={target.id}
+                data-cinder-series-id={target.seriesId}
+                data-cinder-focus-ring-active={pointFocusRing && focusRingTarget?.id === target.id
+                  ? 'true'
+                  : undefined}
                 aria-label={`${target.seriesLabel}, ${target.xLabel}, ${target.valueLabel}`}
                 aria-describedby={interaction.activeTarget?.id === target.id
                   ? `${rootId}-tooltip`
                   : undefined}
-                onfocus={() => (interaction.focusedTarget = target)}
-                onblur={() => (interaction.focusedTarget = undefined)}
-                onkeydown={(event) =>
-                  interaction.activateByKeyboard(
-                    event,
-                    rootElement!,
-                    model.targets,
-                    keyboardEnabled,
-                  )}
+                onfocus={() => handleTargetFocus(target)}
+                onblur={handleTargetBlur}
+                onkeydown={handleTargetKeydown}
               />
             {/each}
           {/if}
         {/if}
+        {#if pointFocusRing}
+          <g class="cinder-area-chart__focus-ring-layer" aria-hidden="true">
+            {#if pointFocusRing.kind === 'point'}
+              <circle
+                class="cinder-area-chart__focus-ring-halo"
+                cx={pointFocusRing.cx}
+                cy={pointFocusRing.cy}
+                r={pointFocusRing.radius}
+              />
+              <circle
+                class="cinder-area-chart__focus-ring"
+                cx={pointFocusRing.cx}
+                cy={pointFocusRing.cy}
+                r={pointFocusRing.radius}
+              />
+              {#if pointFocusRing.connector && pointFocusRing.dot}
+                <path
+                  class="cinder-area-chart__focus-ring-connector cinder-area-chart__focus-ring-halo"
+                  d={`M ${pointFocusRing.connector.x1} ${pointFocusRing.connector.y1} L ${pointFocusRing.connector.x2} ${pointFocusRing.connector.y2}`}
+                />
+                <path
+                  class="cinder-area-chart__focus-ring-connector cinder-area-chart__focus-ring"
+                  d={`M ${pointFocusRing.connector.x1} ${pointFocusRing.connector.y1} L ${pointFocusRing.connector.x2} ${pointFocusRing.connector.y2}`}
+                />
+                <circle
+                  class="cinder-area-chart__focus-ring-dot cinder-area-chart__focus-ring-halo"
+                  cx={pointFocusRing.dot.cx}
+                  cy={pointFocusRing.dot.cy}
+                  r={pointFocusRing.dot.radius}
+                />
+                <circle
+                  class="cinder-area-chart__focus-ring-dot cinder-area-chart__focus-ring"
+                  cx={pointFocusRing.dot.cx}
+                  cy={pointFocusRing.dot.cy}
+                  r={pointFocusRing.dot.radius}
+                />
+              {/if}
+            {:else}
+              <rect
+                class="cinder-area-chart__focus-ring-halo"
+                x={pointFocusRing.x}
+                y={pointFocusRing.y}
+                width={pointFocusRing.width}
+                height={pointFocusRing.height}
+                rx={pointFocusRing.radius}
+              />
+              <rect
+                class="cinder-area-chart__focus-ring"
+                x={pointFocusRing.x}
+                y={pointFocusRing.y}
+                width={pointFocusRing.width}
+                height={pointFocusRing.height}
+                rx={pointFocusRing.radius}
+              />
+            {/if}
+          </g>
+        {/if}
       </g>
     </svg>
     {#if interaction.activeTarget}<div

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

@@ -47,9 +47,8 @@
        ring; the outline is intentionally suppressed. */
     outline: none;
     box-shadow:
-      0 0 0 var(--cinder-ring-offset-width) var(--cinder-ring-offset-color),
-      0 0 0 calc(var(--cinder-ring-offset-width) + var(--cinder-ring-width))
-        var(--cinder-ring-color);
+      0 0 0 var(--cinder-ring-offset, 1px) var(--cinder-ring-offset-color),
+      0 0 0 calc(var(--cinder-ring-offset, 1px) + var(--cinder-ring-width)) var(--cinder-ring-color);
   }
 
   .cinder-avatar-group__overflow {

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

@@ -7,6 +7,7 @@
       "id": "basic",
       "title": "Collaborator stack",
       "description": "A compact stack of visible collaborators with focusable names.",
+      "featured": true,
       "code": "<script lang=\"ts\">\n  import { AvatarGroup } from '@lostgradient/cinder/avatar-group';\n\n  const avatars = [\n    { id: 'ada', name: 'Ada Lovelace' },\n    { id: 'grace', name: 'Grace Hopper' },\n    { id: 'katherine', name: 'Katherine Johnson' },\n  ];\n</script>\n\n<div class=\"example-preview-row\">\n  <AvatarGroup {avatars} aria-label=\"Active collaborators\" />\n</div>\n"
     },
     {

package/src/components/backdrop/README.md

@@ -0,0 +1,56 @@
+# Backdrop
+
+Full-viewport fixed scrim primitive for custom overlay patterns such as loading dimmers and image lightboxes.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { Backdrop } from '@lostgradient/cinder/backdrop';
+</script>
+```
+
+## Guidance
+
+### Use When
+
+- Providing a full-screen dimming layer behind a custom overlay that is not modal, drawer, or sheet.
+- Building a loading state that dims the full viewport while an async operation runs.
+
+### Avoid When
+
+- Interrupting the user for a decision — use modal or alert-dialog which manage focus and Escape automatically.
+- Showing a side panel — use drawer instead.
+- Showing structured content in a dialog — use modal, drawer, or sheet, which render their own native `<dialog>::backdrop` scrim.
+
+## Props
+
+<!-- generated:props:start -->
+
+| Prop                 | Type       | Required | Default | Description                                                                                                                                          |
+| -------------------- | ---------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`              | `string`   | no       | —       | Additional class names merged onto the root element.                                                                                                 |
+| `invisible`          | `boolean`  | no       | `false` | When true the backdrop is transparent but still captures pointer events, enabling click-to-close without dimming content behind it.                  |
+| `lockScroll`         | `boolean`  | no       | `true`  | Lock body scroll while the backdrop is open (counted lock — safe to nest with other overlays). Set false when the consumer manages scrolling itself. |
+| `open`               | `boolean`  | yes      | —       | Whether the backdrop is visible and active.                                                                                                          |
+| `transitionDuration` | `number`   | no       | —       | Enter/leave animation duration in milliseconds. Collapses to 0 under `prefers-reduced-motion`. Overrides the default when provided.                  |
+| `children`           | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                           |
+| `onclick`            | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                           |
+
+<!-- generated:props:end -->
+
+## CSS Variables
+
+<!-- generated:variables:start -->
+
+This component does not declare any local CSS variables.
+
+<!-- generated:variables:end -->
+
+## Subcomponents
+
+<!-- generated:subcomponents:start -->
+
+None.
+
+<!-- generated:subcomponents:end -->

package/src/components/badge/README.md

@@ -18,11 +18,12 @@ Use Badge for attached counts, statuses, and compact annotations; use `Chip mode
 
 <!-- generated:props:start -->
 
-| Prop      | Type                                                                              | Required | Default     | Description                               |
-| --------- | --------------------------------------------------------------------------------- | -------- | ----------- | ----------------------------------------- |
-| `class`   | `string`                                                                          | no       | —           | Custom class merged with `.cinder-badge`. |
-| `size`    | `"xs"` \| `"sm"` \| `"md"`                                                        | no       | `"md"`      | Size of the badge.                        |
-| `variant` | `"neutral"` \| `"success"` \| `"warning"` \| `"danger"` \| `"info"` \| `"accent"` | no       | `"neutral"` | Visual style.                             |
+| Prop      | Type                                                                              | Required | Default     | Description                                                                                                     |
+| --------- | --------------------------------------------------------------------------------- | -------- | ----------- | --------------------------------------------------------------------------------------------------------------- |
+| `class`   | `string`                                                                          | no       | —           | Custom class merged with `.cinder-badge`.                                                                       |
+| `mono`    | `boolean`                                                                         | no       | `false`     | Render the badge label in a monospace font. Useful for version strings, error codes, or other technical labels. |
+| `size`    | `"xs"` \| `"sm"` \| `"md"`                                                        | no       | `"md"`      | Size of the badge.                                                                                              |
+| `variant` | `"neutral"` \| `"success"` \| `"warning"` \| `"danger"` \| `"info"` \| `"accent"` | no       | `"neutral"` | Visual style.                                                                                                   |
 
 <!-- generated:props:end -->
 

package/src/components/badge/badge.css

@@ -82,4 +82,21 @@
     color: var(--cinder-accent-text);
     border-color: color-mix(in oklch, var(--cinder-accent), transparent 60%);
   }
+
+  /* ----------------------------------------
+ * Mono affordance
+ * ---------------------------------------- */
+
+  .cinder-badge[data-cinder-mono] {
+    font-family: var(
+      --cinder-font-mono,
+      ui-monospace,
+      SFMono-Regular,
+      'SF Mono',
+      Menlo,
+      Consolas,
+      'Liberation Mono',
+      monospace
+    );
+  }
 }

package/src/components/badge/badge.schema.json

@@ -12,6 +12,11 @@
       "description": "Size of the badge.",
       "default": "md"
     },
+    "mono": {
+      "type": "boolean",
+      "description": "Render the badge label in a monospace font. Useful for version strings, error codes, or other technical labels.",
+      "default": false
+    },
     "class": {
       "type": "string",
       "description": "Custom class merged with `.cinder-badge`."

package/src/components/badge/badge.schema.ts

@@ -14,6 +14,12 @@ const schema = {
       description: 'Size of the badge.',
       default: 'md',
     },
+    mono: {
+      type: 'boolean',
+      description:
+        'Render the badge label in a monospace font. Useful for version strings, error codes, or other technical labels.',
+      default: false,
+    },
     class: {
       type: 'string',
       description: 'Custom class merged with `.cinder-badge`.',

package/src/components/badge/badge.svelte

@@ -23,6 +23,7 @@
   let {
     variant = 'neutral',
     size = 'md',
+    mono = false,
     class: customClassName,
     children,
     ...rest
@@ -33,6 +34,7 @@
   class={classNames('cinder-badge', customClassName)}
   data-cinder-variant={variant}
   data-cinder-size={size}
+  data-cinder-mono={mono ? '' : undefined}
   {...rest}
 >
   {@render children?.()}

package/src/components/badge/badge.types.ts

@@ -11,6 +11,8 @@ export type BadgeSize = 'xs' | 'sm' | 'md';
 export type BadgeProps = HTMLAttributes<HTMLSpanElement> & {
   variant?: BadgeVariant;
   size?: BadgeSize;
+  /** Render the badge label in a monospace font. */
+  mono?: boolean;
   class?: string;
   /**
    * Badge content — intentionally required. A badge without content is
@@ -32,6 +34,11 @@ export interface BadgeSchemaProps {
    * @default "md"
    */
   size?: BadgeSize;
+  /**
+   * Render the badge label in a monospace font. Useful for version strings, error codes, or other technical labels.
+   * @default false
+   */
+  mono?: boolean;
   /** Custom class merged with `.cinder-badge`. */
   class?: string;
 }

package/src/components/bar-chart/README.md

@@ -0,0 +1,65 @@
+# BarChart
+
+Responsive SVG bar chart for grouped or stacked category comparisons.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { BarChart } from '@lostgradient/cinder/bar-chart';
+</script>
+```
+
+## Guidance
+
+### Use When
+
+- Comparing discrete category totals or grouped category breakdowns.
+- Showing stacked contribution across known categories.
+
+### Avoid When
+
+- Showing a continuous ordered trend — use line-chart instead.
+- Showing magnitude under a trend — use area-chart instead.
+
+## Props
+
+<!-- generated:props:start -->
+
+| Prop                       | Type                                                                      | Required | Default | Description                                                                                                                                                       |
+| -------------------------- | ------------------------------------------------------------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `categoryKey`              | `string`                                                                  | yes      | —       | Category field name. Runtime validation requires every row to contain a string, number, or Date category.                                                         |
+| `class`                    | `string`                                                                  | no       | —       |                                                                                                                                                                   |
+| `data`                     | `object`[]                                                                | yes      | —       | JSON-safe data rows. Schema cannot express dynamic categoryKey/valueKey relationships; runtime validation narrows value-key fields to number, null, or undefined. |
+| `dataTableCaption`         | `string`                                                                  | no       | —       |                                                                                                                                                                   |
+| `dataTableVisibility`      | `"screen-reader-only"` \| `"visible"` \| `"hidden"`                       | no       | —       |                                                                                                                                                                   |
+| `description`              | `string`                                                                  | no       | —       |                                                                                                                                                                   |
+| `height`                   | `number`                                                                  | no       | —       |                                                                                                                                                                   |
+| `hiddenSeriesIds`          | `string`[]                                                                | no       | —       |                                                                                                                                                                   |
+| `label`                    | `string`                                                                  | yes      | —       |                                                                                                                                                                   |
+| `legendPosition`           | `"top"` \| `"bottom"` \| `"none"`                                         | no       | —       |                                                                                                                                                                   |
+| `loading`                  | `boolean`                                                                 | no       | —       |                                                                                                                                                                   |
+| `maximumInteractivePoints` | `number`                                                                  | no       | —       |                                                                                                                                                                   |
+| `mode`                     | `"grouped"` \| `"stacked"`                                                | no       | —       |                                                                                                                                                                   |
+| `orientation`              | `"vertical"` \| `"horizontal"`                                            | no       | —       |                                                                                                                                                                   |
+| `series`                   | { color?: `string`; id: `string`; label: `string`; valueKey: `string` }[] | yes      | —       | Series value keys. Schema cannot prove every valueKey exists on every row; runtime validation enforces it.                                                        |
+| `xAxis`                    | { label?: `string`; tickCount?: `number` }                                | no       | —       |                                                                                                                                                                   |
+| `yAxis`                    | { label?: `string`; tickCount?: `number` }                                | no       | —       |                                                                                                                                                                   |
+
+<!-- generated:props:end -->
+
+## CSS Variables
+
+<!-- generated:variables:start -->
+
+This component does not declare any local CSS variables.
+
+<!-- generated:variables:end -->
+
+## Subcomponents
+
+<!-- generated:subcomponents:start -->
+
+None.
+
+<!-- generated:subcomponents:end -->

package/src/components/bar-chart/bar-chart.css

@@ -71,14 +71,64 @@
     pointer-events: none;
   }
 
-  /*
- * SVG focus indicator: drop-shadow renders a visible ring around the focused
- * element on any background. Matches line-chart and area-chart.
- */
-  .cinder-bar-chart__focus-target:focus-visible {
-    stroke: var(--cinder-accent);
+  .cinder-bar-chart__focus-target:focus-visible:not([data-cinder-focus-ring-active='true']) {
+    fill: transparent;
+    stroke: var(--cinder-ring-color);
+    stroke-width: var(--cinder-ring-width);
+    vector-effect: non-scaling-stroke;
+    filter: none;
+  }
+
+  .cinder-bar-chart__focus-ring-layer {
+    pointer-events: none;
+  }
+
+  .cinder-bar-chart__focus-ring,
+  .cinder-bar-chart__focus-ring-halo,
+  .cinder-bar-chart__focus-ring-connector,
+  .cinder-bar-chart__focus-ring-dot {
+    fill: none;
+    pointer-events: none;
+    vector-effect: non-scaling-stroke;
+    stroke-linecap: round;
+    stroke-linejoin: round;
+  }
+
+  .cinder-bar-chart__focus-ring {
+    stroke: var(--cinder-ring-color);
     stroke-width: var(--cinder-ring-width);
-    filter: drop-shadow(0 0 var(--cinder-ring-width) var(--cinder-ring-color));
+    filter: none;
+  }
+
+  .cinder-bar-chart__focus-ring-halo {
+    stroke: var(--cinder-ring-offset-color);
+    stroke-width: calc(
+      var(--cinder-ring-width) + var(--cinder-ring-offset) + var(--cinder-ring-offset)
+    );
+    filter: none;
+  }
+
+  @media (forced-colors: active) {
+    .cinder-bar-chart__focus-ring-halo {
+      display: none;
+    }
+
+    .cinder-bar-chart__focus-ring,
+    .cinder-bar-chart__focus-ring-connector,
+    .cinder-bar-chart__focus-ring-dot {
+      fill: none;
+      stroke: ButtonText;
+      stroke-width: var(--cinder-ring-width);
+      filter: none;
+    }
+
+    .cinder-bar-chart__focus-target:focus-visible:not([data-cinder-focus-ring-active='true']) {
+      fill: transparent;
+      stroke: ButtonText;
+      stroke-width: var(--cinder-ring-width);
+      vector-effect: non-scaling-stroke;
+      filter: none;
+    }
   }
 
   .cinder-bar-chart__tick-label {