@lostgradient/cinder 0.2.0 → 0.4.0

package/src/components/keyboard-shortcuts/README.md

@@ -25,12 +25,12 @@ Grouped keyboard-shortcut reference that renders key combos via Kbd with accessi
 
 <!-- generated:props:start -->
 
-| Prop       | Type       | Required | Default | Description                                                                                                                |
-| ---------- | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `class`    | `string`   | no       | —       | Additional class names merged with `.cinder-keyboard-shortcuts`.                                                           |
-| `heading`  | `string`   | no       | —       | Optional heading for the entire shortcuts panel.                                                                           |
-| `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. |
-| `groups`   | `(opaque)` | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                    |
+| Prop       | Type       | Required | Default | Description                                                                                                         |
+| ---------- | ---------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
+| `class`    | `string`   | no       | —       | Additional class names merged with `.cinder-keyboard-shortcuts`.                                                    |
+| `heading`  | `string`   | no       | —       | Optional heading for the entire shortcuts panel.                                                                    |
+| `children` | `(opaque)` | no       | —       | Intro content rendered above the groups. Not expressible in JSON Schema; see the component types for the signature. |
+| `groups`   | `(opaque)` | yes      | —       | Groups of shortcuts to display. Not expressible in JSON Schema; see the component types for the signature.          |
 
 <!-- generated:props:end -->
 

package/src/components/keyboard-shortcuts/keyboard-shortcuts.css

@@ -8,7 +8,7 @@
 
   .cinder-keyboard-shortcuts__heading {
     font-size: var(--cinder-text-lg);
-    font-weight: 600;
+    font-weight: var(--cinder-font-semibold);
     color: var(--cinder-text);
     margin: 0;
   }
@@ -26,7 +26,7 @@
 
   .cinder-keyboard-shortcuts__group-label {
     font-size: var(--cinder-text-xs);
-    font-weight: 600;
+    font-weight: var(--cinder-font-semibold);
     text-transform: uppercase;
     letter-spacing: 0.05em;
     color: var(--cinder-text-muted);

package/src/components/keyboard-shortcuts/keyboard-shortcuts.svelte

@@ -41,7 +41,7 @@
    * Build a screen-reader–friendly label for a key combo.
    * Falls back to joining keys with " plus " when no keysLabel is provided.
    */
-  function resolveKeysLabel(keys: string[], keysLabel?: string): string {
+  function resolveKeysLabel(keys: string[], keysLabel: string | undefined = undefined): string {
     if (keysLabel) return keysLabel;
     return keys.join(' plus ');
   }

package/src/components/label/README.md

@@ -9,20 +9,20 @@ Accessible form label that associates descriptive text with its input element.
   import Label from '@lostgradient/cinder/label';
 </script>
 
-<Label />
+<Label for="my-input">Email address</Label>
 ```
 
 ## Props
 
 <!-- generated:props:start -->
 
-| Prop       | Type       | Required | Default | Description                                                                                                                |
-| ---------- | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `disabled` | `boolean`  | no       | —       | When true, render the label in the disabled color treatment.                                                               |
-| `for`      | `string`   | yes      | —       | The id of the form control this label labels. Sets `for` on the rendered `<label>`.                                        |
-| `required` | `boolean`  | no       | —       | When true, append a visual indicator that the field is required.                                                           |
-| `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. |
-| `class`    | `(opaque)` | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                    |
+| Prop       | Type       | Required | Default | Description                                                                                                                    |
+| ---------- | ---------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `disabled` | `boolean`  | no       | —       | When true, render the label in the disabled color treatment.                                                                   |
+| `for`      | `string`   | yes      | —       | The id of the form control this label labels. Sets `for` on the rendered `<label>`.                                            |
+| `required` | `boolean`  | no       | —       | When true, append a visual indicator that the field is required.                                                               |
+| `children` | `(opaque)` | yes      | —       | The label text or composed content. Not expressible in JSON Schema; see the component types for the signature.                 |
+| `class`    | `(opaque)` | no       | —       | Additional class names merged with `.cinder-label`. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

package/src/components/label/label.css

@@ -21,13 +21,6 @@
     cursor: not-allowed;
   }
 
-  .cinder-label__required {
-    display: inline-block;
-    width: 6px;
-    height: 6px;
-    border-radius: 50%;
-    background-color: var(--cinder-danger);
-    flex-shrink: 0;
-    align-self: center;
-  }
+  /* The required marker is the shared `.cinder-_required-marker` partial
+     (styles/components/_field-label.css). */
 }

package/src/components/label/label.svelte

@@ -36,7 +36,9 @@
 >
   {@render children()}
   {#if required}
-    <!-- Decorative — accessible name comes from the field's `required` attribute. -->
-    <span class="cinder-label__required" aria-hidden="true"></span>
+    <!-- Visible asterisk conveys "required" by shape, not color alone (WCAG
+         1.4.1). aria-hidden so the accessible name stays clean — the field's
+         own `required`/`aria-required` attribute is the single AT signal. -->
+    <span class="cinder-_required-marker" aria-hidden="true">*</span>
   {/if}
 </label>

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

@@ -26,21 +26,23 @@ Responsive SVG line chart for comparing one or more numeric series over an order
 
 <!-- generated:props:start -->
 
-| Prop                       | Type                                                                                                                   | Required | Default | Description |
-| -------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ----------- |
-| `class`                    | `string`                                                                                                               | no       | —       |             |
-| `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       | —       |             |
-| `series`                   | ({ color?: `string`; data: ({ x: `string` \| `number`; y?: `number` \| `null` })[]; id: `string`; label: `string` })[] | yes      | —       |             |
-| `xAxis`                    | { label?: `string`; tickCount?: `number` }                                                                             | no       | —       |             |
-| `yAxis`                    | { label?: `string`; tickCount?: `number` }                                                                             | no       | —       |             |
+| Prop                       | Type                                                                                                                   | Required | Default | Description                                                                                                                |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `class`                    | `string`                                                                                                               | no       | —       | Custom class applied to the root element.                                                                                  |
+| `dataTableCaption`         | `string`                                                                                                               | no       | —       | Custom data table caption; falls back to `label`.                                                                          |
+| `dataTableVisibility`      | `"screen-reader-only"` \| `"visible"` \| `"hidden"`                                                                    | no       | —       | Controls data table visibility. Default `screen-reader-only`.                                                              |
+| `description`              | `string`                                                                                                               | no       | —       | Optional description rendered below the label.                                                                             |
+| `height`                   | `number`                                                                                                               | no       | —       | Pixel height of the chart viewport. Default `280`.                                                                         |
+| `hiddenSeriesIds`          | `string`[]                                                                                                             | no       | —       | IDs of series currently hidden from the chart. Can be two-way bound with `bind:hiddenSeriesIds`.                           |
+| `label`                    | `string`                                                                                                               | yes      | —       | Accessible label for the chart. Required for screen readers.                                                               |
+| `legendPosition`           | `"top"` \| `"bottom"` \| `"none"`                                                                                      | no       | —       | Where to render the series legend relative to the chart. Default `top`.                                                    |
+| `loading`                  | `boolean`                                                                                                              | no       | —       | Whether the chart is in a loading state. Default `false`.                                                                  |
+| `maximumInteractivePoints` | `number`                                                                                                               | no       | —       | Maximum number of interactive focus targets before keyboard navigation is disabled. Default `500`.                         |
+| `series`                   | ({ color?: `string`; data: ({ x: `string` \| `number`; y?: `number` \| `null` })[]; id: `string`; label: `string` })[] | yes      | —       | Series to render as one or more connected line paths.                                                                      |
+| `xAxis`                    | { label?: `string`; tickCount?: `number` }                                                                             | no       | —       | Configuration for the x-axis label and tick count.                                                                         |
+| `yAxis`                    | { label?: `string`; tickCount?: `number` }                                                                             | no       | —       | Configuration for the y-axis label and tick count.                                                                         |
+| `empty`                    | `(opaque)`                                                                                                             | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
+| `loadingContent`           | `(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 -->
 

package/src/components/line-chart/line-chart.examples.json

@@ -19,6 +19,7 @@
       "id": "single-series",
       "title": "Revenue trend",
       "description": "A single-series line chart for monthly recurring revenue.",
+      "featured": true,
       "code": "<script lang=\"ts\">\n  import { LineChart } from '@lostgradient/cinder/line-chart';\n\n  const series = [\n    {\n      id: 'revenue',\n      label: 'Revenue',\n      data: [\n        { x: 'Jan', y: 120 },\n        { x: 'Feb', y: 148 },\n        { x: 'Mar', y: 172 },\n        { x: 'Apr', y: 196 },\n      ],\n    },\n  ];\n</script>\n\n<LineChart label=\"Monthly recurring revenue\" {series} dataTableVisibility=\"visible\" />\n"
     }
   ]

package/src/components/line-chart/line-chart.types.ts

@@ -27,17 +27,30 @@ export type LineChartSchemaSeries = {
 };
 
 export type LineChartSchemaProps = {
+  /** Accessible label for the chart. Required for screen readers. */
   label: string;
+  /** Optional description rendered below the label. */
   description?: string;
+  /** Pixel height of the chart viewport. Default `280`. */
   height?: number;
+  /** Configuration for the x-axis label and tick count. */
   xAxis?: ChartAxisSchemaConfiguration;
+  /** Configuration for the y-axis label and tick count. */
   yAxis?: ChartAxisSchemaConfiguration;
+  /** Where to render the series legend relative to the chart. Default `top`. */
   legendPosition?: ChartLegendPosition;
+  /** IDs of series currently hidden from the chart. Can be two-way bound with `bind:hiddenSeriesIds`. */
   hiddenSeriesIds?: string[];
+  /** Whether the chart is in a loading state. Default `false`. */
   loading?: boolean;
+  /** Custom data table caption; falls back to `label`. */
   dataTableCaption?: string;
+  /** Controls data table visibility. Default `screen-reader-only`. */
   dataTableVisibility?: ChartDataTableVisibility;
+  /** Maximum number of interactive focus targets before keyboard navigation is disabled. Default `500`. */
   maximumInteractivePoints?: number;
+  /** Custom class applied to the root element. */
   class?: string;
+  /** Series to render as one or more connected line paths. */
   series: LineChartSchemaSeries[];
 };

package/src/components/link/README.md

@@ -33,8 +33,8 @@ Inline text link with consistent focus ring and underline behavior.
 | `href`      | `string`                            | no       | —           | The URL the link points to. Optional ONLY because a `disabled` link renders a `<span>` with no href. For any enabled (non-disabled) link you must provide it — an `<a>` without `href` is not keyboard-focusable and is not exposed as a link to assistive technology, so an enabled Link without `href` is a bug, not a feature. |
 | `rel`       | `string` \| `null`                  | no       | —           | Forwarded to the rendered `<a>`. `"noopener noreferrer"` is merged in whenever the link opens in a new tab — `external` is true OR the resolved target is `"_blank"` (case-insensitive) — and the whole value is de-duplicated case-insensitively.                                                                                |
 | `underline` | `"always"` \| `"hover"` \| `"none"` | no       | `"hover"`   | Controls text-decoration behavior. - `'always'` — underline is always visible. - `'hover'` — underline appears on hover and focus (default). - `'none'` — underline is never shown.                                                                                                                                               |
-| `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.                                                                                                                                                                                                        |
-| `target`    | `(opaque)`                          | no       | —           | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                           |
+| `children`  | `(opaque)`                          | yes      | —           | The link text or composed content. Required. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                           |
+| `target`    | `(opaque)`                          | no       | —           | Forwarded to the rendered `<a>`. `external` supplies `"_blank"` only when no target is given. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                          |
 
 <!-- generated:props:end -->
 

package/src/components/load-more/README.md

@@ -2,7 +2,7 @@
 
 Sentinel-based infinite-scroll trigger with an always-visible button fallback and accessible status states.
 
-`onLoadMore` should be provided in real usage. When omitted, the component falls back to a no-op handler.
+`onloadmore` should be provided in real usage. When omitted, the component falls back to a no-op handler.
 
 ## Usage
 
@@ -21,26 +21,26 @@ Sentinel-based infinite-scroll trigger with an always-visible button fallback an
   }
 </script>
 
-<LoadMore onLoadMore={fetchNext} bind:loading bind:hasMore />
+<LoadMore onloadmore={fetchNext} bind:loading bind:hasMore />
 ```
 
 ## Props
 
 <!-- generated:props:start -->
 
-| Prop               | Type       | Required | Default | Description                                                                                                                |
-| ------------------ | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `buttonLabel`      | `string`   | no       | —       | Visible label for the load-more button.                                                                                    |
-| `class`            | `string`   | no       | —       | Custom class merged with `.cinder-load-more`.                                                                              |
-| `endOfListMessage` | `string`   | no       | —       | Politely announced when the end of the list is reached.                                                                    |
-| `hasMore`          | `boolean`  | no       | —       | Whether more items are available. Bindable.                                                                                |
-| `loading`          | `boolean`  | no       | —       | Whether a load is in progress. Bindable.                                                                                   |
-| `maxRetries`       | `number`   | no       | —       | Maximum consecutive sentinel-triggered requests before auto-loading pauses.                                                |
-| `retryLabel`       | `string`   | no       | —       | Visible label for the retry button after a load error.                                                                     |
-| `rootMargin`       | `string`   | no       | —       | rootMargin passed to IntersectionObserver. Captured at attachment time.                                                    |
-| `onError`          | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `onLoadMore`       | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `root`             | `(opaque)` | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                    |
+| Prop               | Type       | Required | Default | Description                                                                                                                                                                                                                                                                                                     |
+| ------------------ | ---------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `buttonLabel`      | `string`   | no       | —       | Visible label for the load-more button.                                                                                                                                                                                                                                                                         |
+| `class`            | `string`   | no       | —       | Custom class merged with `.cinder-load-more`.                                                                                                                                                                                                                                                                   |
+| `endOfListMessage` | `string`   | no       | —       | Politely announced when the end of the list is reached.                                                                                                                                                                                                                                                         |
+| `hasMore`          | `boolean`  | no       | —       | Whether more items are available. Bindable.                                                                                                                                                                                                                                                                     |
+| `loading`          | `boolean`  | no       | —       | Whether a load is in progress. Bindable.                                                                                                                                                                                                                                                                        |
+| `maxRetries`       | `number`   | no       | —       | Maximum consecutive sentinel-triggered requests before auto-loading pauses.                                                                                                                                                                                                                                     |
+| `retryLabel`       | `string`   | no       | —       | Visible label for the retry button after a load error.                                                                                                                                                                                                                                                          |
+| `rootMargin`       | `string`   | no       | —       | rootMargin passed to IntersectionObserver. Captured at attachment time.                                                                                                                                                                                                                                         |
+| `onerror`          | `(opaque)` | no       | —       | Notified when onloadmore throws or rejects. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                          |
+| `onloadmore`       | `(opaque)` | no       | —       | Called when the next page should be loaded. Caller flips `loading` and `hasMore`. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                    |
+| `root`             | `(opaque)` | no       | —       | Scroll container the sentinel is observed within. Pass the scrollable ancestor element when the list scrolls inside a container rather than the viewport. `null`/omitted observes against the viewport. Captured at attachment time. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

package/src/components/load-more/load-more.css

@@ -43,11 +43,19 @@
   }
 
   .cinder-load-more__button:focus-visible {
-    outline: 2px solid transparent;
-    outline-offset: 2px;
+    outline: var(--cinder-ring-width) solid transparent;
+    outline-offset: var(--cinder-ring-offset);
     box-shadow:
-      0 0 0 2px var(--cinder-ring-offset-color),
-      0 0 0 4px var(--cinder-ring-color);
+      0 0 0 var(--cinder-ring-offset) var(--cinder-ring-offset-color),
+      0 0 0 calc(var(--cinder-ring-offset) + var(--cinder-ring-width)) var(--cinder-ring-color);
+  }
+
+  @media (forced-colors: active) {
+    .cinder-load-more__button:focus-visible {
+      outline: 2px solid ButtonText;
+      outline-offset: 3px;
+      box-shadow: none;
+    }
   }
 
   .cinder-load-more__button:disabled {
@@ -65,7 +73,7 @@
 
   @media (prefers-reduced-motion: no-preference) {
     .cinder-load-more__spinner {
-      animation: cinder-load-more-spin 0.8s linear infinite;
+      animation: cinder-load-more-spin var(--cinder-duration-spin) linear infinite;
     }
   }
 

package/src/components/load-more/load-more.examples.json

@@ -7,13 +7,13 @@
       "id": "basic",
       "title": "Basic infinite scroll",
       "description": "The sentinel auto-loads near the end of the list, and the button remains available as the manual fallback.",
-      "code": "<script lang=\"ts\">\n  import { LoadMore } from '@lostgradient/cinder/load-more';\n\n  let items = $state(Array.from({ length: 20 }, (_, index) => `Item ${index + 1}`));\n  let loading = $state(false);\n  let hasMore = $state(true);\n\n  async function fetchNext() {\n    loading = true;\n    await new Promise((resolve) => setTimeout(resolve, 400));\n    const start = items.length;\n    items = [...items, ...Array.from({ length: 20 }, (_, index) => `Item ${start + index + 1}`)];\n    loading = false;\n    if (items.length >= 100) hasMore = false;\n  }\n</script>\n\n<ul aria-busy={loading}>\n  {#each items as item}\n    <li>{item}</li>\n  {/each}\n</ul>\n\n<LoadMore onLoadMore={fetchNext} bind:loading bind:hasMore />\n"
+      "code": "<script lang=\"ts\">\n  import { LoadMore } from '@lostgradient/cinder/load-more';\n\n  let items = $state(Array.from({ length: 20 }, (_, index) => `Item ${index + 1}`));\n  let loading = $state(false);\n  let hasMore = $state(true);\n\n  async function fetchNext() {\n    loading = true;\n    await new Promise((resolve) => setTimeout(resolve, 400));\n    const start = items.length;\n    items = [...items, ...Array.from({ length: 20 }, (_, index) => `Item ${start + index + 1}`)];\n    loading = false;\n    if (items.length >= 100) hasMore = false;\n  }\n</script>\n\n<ul aria-busy={loading}>\n  {#each items as item}\n    <li>{item}</li>\n  {/each}\n</ul>\n\n<LoadMore onloadmore={fetchNext} bind:loading bind:hasMore />\n"
     },
     {
       "id": "retry",
       "title": "Retry after a failed request",
       "description": "Rejected requests switch the button into retry mode so the user can recover explicitly.",
-      "code": "<script lang=\"ts\">\n  import { LoadMore } from '@lostgradient/cinder/load-more';\n\n  let items = $state(['Alpha', 'Bravo', 'Charlie']);\n  let loading = $state(false);\n  let hasMore = $state(true);\n  let attempts = $state(0);\n\n  async function fetchNext() {\n    loading = true;\n    await new Promise((resolve) => setTimeout(resolve, 300));\n    attempts += 1;\n    loading = false;\n    if (attempts === 1) {\n      throw new Error('Temporary network failure');\n    }\n    items = [...items, 'Delta', 'Echo'];\n    hasMore = false;\n  }\n</script>\n\n<ul aria-busy={loading}>\n  {#each items as item}\n    <li>{item}</li>\n  {/each}\n</ul>\n\n<LoadMore onLoadMore={fetchNext} bind:loading bind:hasMore retryLabel=\"Try again\" />\n"
+      "code": "<script lang=\"ts\">\n  import { LoadMore } from '@lostgradient/cinder/load-more';\n\n  let items = $state(['Alpha', 'Bravo', 'Charlie']);\n  let loading = $state(false);\n  let hasMore = $state(true);\n  let attempts = $state(0);\n\n  async function fetchNext() {\n    loading = true;\n    await new Promise((resolve) => setTimeout(resolve, 300));\n    attempts += 1;\n    loading = false;\n    if (attempts === 1) {\n      throw new Error('Temporary network failure');\n    }\n    items = [...items, 'Delta', 'Echo'];\n    hasMore = false;\n  }\n</script>\n\n<ul aria-busy={loading}>\n  {#each items as item}\n    <li>{item}</li>\n  {/each}\n</ul>\n\n<LoadMore onloadmore={fetchNext} bind:loading bind:hasMore retryLabel=\"Try again\" />\n"
     }
   ]
 }

package/src/components/load-more/load-more.svelte

@@ -21,8 +21,8 @@
   import VisuallyHiddenLiveRegion from '../_visually-hidden-live-region.svelte';
 
   let {
-    onLoadMore = async () => {},
-    onError,
+    onloadmore = async () => {},
+    onerror,
     hasMore = $bindable(true),
     loading = $bindable(false),
     root = null,
@@ -91,13 +91,13 @@
     errorState = false;
 
     try {
-      await onLoadMore();
+      await onloadmore();
       if (source === 'button') {
         retryCount = 0;
       }
     } catch (error) {
       errorState = true;
-      onError?.(error);
+      onerror?.(error);
     } finally {
       // Always clear the in-flight guard once the request settles, regardless of
       // whether the parent has flipped its own `loading` prop yet.

package/src/components/load-more/load-more.types.ts

@@ -1,6 +1,6 @@
 export type LoadMoreProps = {
   /** Called when the next page should be loaded. Caller flips `loading` and `hasMore`. */
-  onLoadMore?: () => void | Promise<void>;
+  onloadmore?: () => void | Promise<void>;
   /** Whether more items are available. Bindable. */
   hasMore?: boolean;
   /** Whether a load is in progress. Bindable. */
@@ -22,8 +22,8 @@ export type LoadMoreProps = {
   endOfListMessage?: string;
   /** Maximum consecutive sentinel-triggered requests before auto-loading pauses. */
   maxRetries?: number;
-  /** Notified when onLoadMore throws or rejects. */
-  onError?: (error: unknown) => void;
+  /** Notified when onloadmore throws or rejects. */
+  onerror?: (error: unknown) => void;
   /** Custom class merged with `.cinder-load-more`. */
   class?: string;
 };

package/src/components/locale-provider/README.md

@@ -0,0 +1,43 @@
+# LocaleProvider
+
+Shared locale and text-direction context for locale-aware descendants.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import LocaleProvider from '@lostgradient/cinder/locale-provider';
+</script>
+
+<LocaleProvider locale="de-DE">
+  <!-- locale-aware cinder components -->
+</LocaleProvider>
+```
+
+## Props
+
+<!-- generated:props:start -->
+
+| Prop        | Type               | Required | Default | Description                                                                                                                           |
+| ----------- | ------------------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `direction` | `"ltr"` \| `"rtl"` | no       | —       | Text direction exposed to direction-aware descendants.                                                                                |
+| `locale`    | `string`           | no       | —       | BCP 47 locale tag used as the default for locale-aware descendants.                                                                   |
+| `children`  | `(opaque)`         | no       | —       | Descendant content that should inherit the locale context. Not expressible in JSON Schema; see the component types for the 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/locale-provider/index.ts

@@ -0,0 +1,5 @@
+import LocaleProvider from './locale-provider.svelte';
+
+export default LocaleProvider;
+export type { LocaleProviderProps, TextDirection } from './locale-provider.types.ts';
+export { LocaleProvider };

package/src/components/locale-provider/locale-provider.svelte

@@ -0,0 +1,40 @@
+<script lang="ts" module>
+  /**
+   * @cinder
+   * @category layout
+   * @status stable
+   * @purpose Context provider that supplies a shared locale and text direction default to locale-aware descendant components.
+   * @tag locale
+   * @tag internationalization
+   * @useWhen Setting one application or subtree locale for number, region, date, or time formatting.
+   * @useWhen Providing text direction once for direction-aware descendants while still allowing local overrides.
+   * @avoidWhen Only one component needs a non-default locale — pass that component's locale prop directly instead.
+   * @related number-input, phone-input, stat
+   */
+  export type { LocaleProviderProps, TextDirection } from './locale-provider.types.ts';
+</script>
+
+<script lang="ts">
+  import {
+    getLocaleContext,
+    setLocaleContext,
+    type LocaleContext,
+  } from '../../_internal/locale-context.ts';
+  import type { LocaleProviderProps } from './locale-provider.types.ts';
+
+  let { locale, direction, children }: LocaleProviderProps = $props();
+  const parentContext = getLocaleContext();
+
+  const context: LocaleContext = {
+    get locale() {
+      return locale ?? parentContext?.locale;
+    },
+    get direction() {
+      return direction ?? parentContext?.direction;
+    },
+  };
+
+  setLocaleContext(context);
+</script>
+
+{@render children?.()}

package/src/components/locale-provider/locale-provider.types.ts

@@ -0,0 +1,21 @@
+import type { Snippet } from 'svelte';
+
+import type { TextDirection } from '../../_internal/locale-context.ts';
+
+export type { TextDirection } from '../../_internal/locale-context.ts';
+
+export type LocaleProviderProps = {
+  /** BCP 47 locale tag used as the default for locale-aware descendants. */
+  locale?: string;
+  /** Text direction exposed to direction-aware descendants. */
+  direction?: TextDirection | undefined;
+  /** Descendant content that should inherit the locale context. */
+  children?: Snippet;
+};
+
+export interface LocaleProviderSchemaProps {
+  /** BCP 47 locale tag used as the default for locale-aware descendants. */
+  locale?: string;
+  /** Text direction exposed to direction-aware descendants. */
+  direction?: TextDirection | undefined;
+}

package/src/components/markdown-editor/README.md

@@ -39,17 +39,17 @@ Rich Markdown editing surface bundling a Milkdown-powered ProseMirror editor, to
 | `showToolbar`           | `boolean`                 | no       | —       | Show formatting toolbar (DEP-37)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `snapshotMode`          | `boolean`                 | no       | —       | Snapshot mode for visual regression testing. When `true`: - Applies `caret-color: transparent` and `user-select: none` to the editor root via a `data-snapshot-mode` attribute, producing a stable visual state (no blinking cursor, no selection highlights). - Blurs any focused element inside the component on mount so the initial screenshot does not capture a focused ring or active caret. This is a purely visual / CSS concern. It does NOT affect editability, ProseMirror state, or any prop controlled by `readonly` / `mode`. |
 | `value`                 | `string`                  | no       | —       | Current markdown content (two-way bindable)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `onchange`              | `(opaque)`                | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `onCommentShortcut`     | `(opaque)`                | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `onmodechange`          | `(opaque)`                | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `onReady`               | `(opaque)`                | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `onSelectionChange`     | `(opaque)`                | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `placeholderCompletion` | `(opaque)`                | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `placeholderDecoration` | `(opaque)`                | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `plugins`               | `(opaque)`                | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `toolbar`               | `(opaque)`                | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `toolbarActions`        | `(opaque)`                | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `toolbarLeading`        | `(opaque)`                | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `onchange`              | `(opaque)`                | no       | —       | Called when content changes Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `oncommentshortcut`     | `(opaque)`                | no       | —       | Called when comment shortcut (Ctrl-Alt-c) is pressed (DEP-47) Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `onmodechange`          | `(opaque)`                | no       | —       | Called when editor mode changes Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `onready`               | `(opaque)`                | no       | —       | Called when the editor is ready (Milkdown initialized) Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `onselectionchange`     | `(opaque)`                | no       | —       | Called when selection changes (stub for DEP-39) Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `placeholderCompletion` | `(opaque)`                | no       | —       | Placeholder completion configuration (DEP-583). When provided, enables inline suggestion menu for {{…}} tokens in WYSIWYG mode. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                   |
+| `placeholderDecoration` | `(opaque)`                | no       | —       | Placeholder decoration configuration (DEP-583). When provided, decorates invalid {{…}} tokens with CSS class and data attributes. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                 |
+| `plugins`               | `(opaque)`                | no       | —       | Additional Milkdown plugins to load. Used for comment anchoring (DEP-39), decorations, and other extensions. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                                      |
+| `toolbar`               | `(opaque)`                | no       | —       | Custom toolbar content. When provided, replaces default toolbar. Receives ToolbarContext for building custom toolbar UI. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                          |
+| `toolbarActions`        | `(opaque)`                | no       | —       | Additional toolbar actions (appended to default toolbar). Use this for adding buttons without replacing the entire toolbar. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                       |
+| `toolbarLeading`        | `(opaque)`                | no       | —       | Leading toolbar content (prepended before default toolbar items). Useful for adding undo/redo or other leading actions. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                           |
 
 <!-- generated:props:end -->
 

package/src/components/markdown-editor/editor-toolbar/editor-toolbar.svelte

@@ -23,6 +23,8 @@
     disabled?: boolean;
     /** Callback to open link popover, receives the triggering button element */
     onLinkClick?: (triggerElement: HTMLElement) => void;
+    /** Whether the link dialog is currently open */
+    linkPopoverOpen?: boolean;
     /** Callback for undo button click */
     onUndo?: () => void;
     /** Callback for redo button click */
@@ -78,6 +80,7 @@
     canUndo = false,
     canRedo = false,
     disabled = false,
+    linkPopoverOpen = false,
     onLinkClick,
     onUndo,
     onRedo,
@@ -285,8 +288,8 @@
       icon={Link}
       label="Insert Link"
       shortcut={getShortcutDisplay('Mod-k')}
-      toggle
-      pressed={activeMarks.link}
+      aria-haspopup="dialog"
+      aria-expanded={linkPopoverOpen}
       {disabled}
       onclick={handleLink}
       data-testid="toolbar-link"

package/src/components/markdown-editor/editor-toolbar/link-popover.svelte

@@ -30,6 +30,7 @@
 </script>
 
 <script lang="ts">
+  import { tick } from 'svelte';
   import type { Placement, VirtualElement } from '@floating-ui/dom';
   import { createAnchoredOverlay } from '../../../_internal/anchored-overlay.svelte.ts';
   import { classNames } from '../../../utilities/class-names.ts';
@@ -71,6 +72,18 @@
   // in-progress edits if `initialUrl` / `initialText` recomputed mid-open.
   let url = $state(initialUrl);
   let text = $state(initialText);
+  let initialFocusApplied = false;
+
+  $effect(() => {
+    if (initialFocusApplied) return;
+    if (!popoverElement) return;
+    if (anchorElement && !anchoredOverlay.positionReady) return;
+    tick().then(() => {
+      if (initialFocusApplied) return;
+      document.getElementById(`${id}-url`)?.focus();
+      initialFocusApplied = true;
+    });
+  });
 
   // Allowed URL protocols (safe for links)
   const ALLOWED_PROTOCOLS = [