@lostgradient/cinder 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,157 @@
 # @lostgradient/cinder
 
+## 0.4.1
+
+### Patch Changes
+
+- [#535](https://github.com/stevekinney/cinder/pull/535) [`fb757d1`](https://github.com/stevekinney/cinder/commit/fb757d1afb82f85457800ba0bb1561906c1a93ce) Thanks [@stevekinney](https://github.com/stevekinney)! - Fix Node SSR export condition precedence so resolvers with both `node` and `svelte` active load compiled server artifacts instead of source entries.
+
+## 0.4.0
+
+### Minor Changes
+
+- [#524](https://github.com/stevekinney/cinder/pull/524) [`680c499`](https://github.com/stevekinney/cinder/commit/680c499a8822882693f387f93f0eab9c086a12b8) Thanks [@stevekinney](https://github.com/stevekinney)! - Add the alpha ApprovalCard component for durable human-in-the-loop tool approvals.
+
+- [#475](https://github.com/stevekinney/cinder/pull/475) [`9349f11`](https://github.com/stevekinney/cinder/commit/9349f11e71874b3056f59a68609eb705ed185aca) Thanks [@stevekinney](https://github.com/stevekinney)! - Remove write-back $effects from rating, pin-input, chat, and image-lightbox; fix schema-form schema-change reset.
+
+  **No-write-back contract for rating and pin-input.** The `value` bindable in `Rating` and `PinInput` is no longer mutated back to the normalized/filtered value. The displayed and submitted value is derived internally via `$derived`, but the bound prop reflects exactly what the consumer set. Consumers relying on the binding being silently normalized should read from `onchange` instead.
+
+  **Chat scroll/unread bindables now update via explicit callbacks.** The `isAtBottom`, `unreadCount`, and `hasNewMessageIndicator` bindables are maintained through the existing `onscrollstatechange`, `onunreadindicatorchange`, and `onReachBottom` callback paths — no $effect write-back. The `handleSubmit` path now also writes `isAtBottom = true` after `scrollState.setIsAtBottom(true)` so the binding stays current after the user sends a message.
+
+  **SchemaForm schema-change now genuinely resets form state.** The internal form body has been extracted into a child component (`schema-form-body.svelte`). The outer component renders `{#key schema}<SchemaFormBody />` so that changing `schema` destroys and recreates the child — causing genuine `$state` recreation (formValue, errors, rawDrafts, arrayKeys, serializedValue) rather than only DOM reconciliation. Changing `value` with the same schema does NOT reset the form (seed-only contract, documented on the prop).
+
+  **image-lightbox index reset.** The `previousOpen $state + $effect` write-back is replaced by a `navigationIndex` (null = no navigation yet) with `effectiveIndex = $derived(navigationIndex ?? clampedInitialIndex)`. Calling `close()` resets `navigationIndex` to null so the next open starts at `initialIndex` without any $effect.
+
+- [#473](https://github.com/stevekinney/cinder/pull/473) [`51355f8`](https://github.com/stevekinney/cinder/commit/51355f83cf0d56f7ccaf3bec27a9c2c34d26006a) Thanks [@stevekinney](https://github.com/stevekinney)! - **Breaking: `DataList` now requires a `key` extractor.** `DataListProps.key` was
+  optional and silently fell back to an unkeyed `{#each}` block when omitted, which
+  made a stable data-display primitive use index-based reconciliation for mutable
+  lists (O(n) row churn and incorrect row instance reuse on insert/remove/filter/
+  reorder). `key` is now required and the unkeyed fallback is removed. Consumers
+  that omitted `key` must pass a stable extractor, e.g. `key={(item) => item.id}`.
+
+  **Breaking: `Masonry.as` is narrowed to a layout-safe element union.** `as` was
+  typed as any `string`, allowing void elements (`img`, `input`, `br`, `hr`) that
+  cannot validly contain masonry children. It now accepts a `MasonryElement` union
+  (`article | aside | div | footer | header | main | nav | section | ul | ol`).
+
+- [#520](https://github.com/stevekinney/cinder/pull/520) [`7b0baa4`](https://github.com/stevekinney/cinder/commit/7b0baa4667907744d56973d49411edc6370e346d) Thanks [@stevekinney](https://github.com/stevekinney)! - Backfill missing component accessibility documentation, gate `.a11y.md` presence in `components:check`, and tighten DataGrid/DataTable audit fixes.
+
+  DataGrid columns can now opt into `role="rowheader"` with `rowHeader: true`, virtualized-column overflow keeps a stable gutter and edge cue, and DataTable sortable headers describe the next sort action while focused rows receive the same hover affordance. The package also normalizes optional Svelte component function parameters so packed source remains valid for downstream SvelteKit consumers.
+
+- [#524](https://github.com/stevekinney/cinder/pull/524) [`680c499`](https://github.com/stevekinney/cinder/commit/680c499a8822882693f387f93f0eab9c086a12b8) Thanks [@stevekinney](https://github.com/stevekinney)! - Add EventStreamViewer reconnect replay markers and advisory sequence-gap markers.
+
+- [#458](https://github.com/stevekinney/cinder/pull/458) [`731784d`](https://github.com/stevekinney/cinder/commit/731784d59ea655a469f596e7de4574e336c35c9b) Thanks [@stevekinney](https://github.com/stevekinney)! - Unify form-control consistency and accessibility, and rebuild `SchemaForm` on the
+  real cinder components.
+
+  **Required indicator.** Every form control now renders a visible required marker
+  on its own `label`/`legend` — previously the asterisk only appeared when a control
+  was wrapped in `FormField`, so `<Textarea required label="…">` silently showed no
+  indicator. The marker is a shared, centered red asterisk (`*`, not a color-only
+  dot) so the meaning is conveyed by glyph shape (WCAG 1.4.1). Screen readers rely
+  on the native `required`/`aria-required` attribute, so there is no double
+  announcement. Affects Input, Textarea, Select, NumberInput, Combobox, Autocomplete,
+  Checkbox, PinInput, PhoneInput, CheckboxGroup, RadioGroup, FormField, and Label.
+
+  **`SchemaForm` now composes cinder components** (Input, NumberInput, Select,
+  Checkbox, Textarea) via Svelte 5 function-bindings instead of rendering raw HTML
+  controls. Boolean fields render as a `Checkbox` (a deferred form boolean) rather
+  than a bespoke switch. This removes all behavior/style drift between SchemaForm and
+  the standalone controls.
+
+  **Consistency fixes.** Combobox now inherits id/`aria-describedby`/`disabled` from a
+  wrapping `FormField` and gained a `required` prop. Toggle inherits `disabled` from
+  `FormField` context. Input and NumberInput now share the same ARIA resolver as the
+  other controls (Input no longer drops a wrapping FormField's describedby id).
+  CheckboxGroup sets `aria-required` to match RadioGroup. Select and Textarea labels
+  gained their missing class/disabled styling.
+
+  **Breaking changes:**
+  - `ColorField`: `ariaLabel` → `aria-label`, `ariaLabelledby` → `aria-labelledby`.
+  - `CheckboxGroup` and `RadioGroup`: the `legend` prop is renamed to `label` for
+    consistency with every other form control (still rendered as a `<legend>`).
+
+- [#476](https://github.com/stevekinney/cinder/pull/476) [`58072f7`](https://github.com/stevekinney/cinder/commit/58072f7b694a54a1704a7f78b0a0bce86aeff401) Thanks [@stevekinney](https://github.com/stevekinney)! - Idiom & developer-experience cleanups (audit [#468](https://github.com/stevekinney/cinder/issues/468)).
+
+  **Breaking type rename.** `diff-viewer`'s exported `ViewMode` type is renamed to
+  `DiffViewerMode` for a self-describing, collision-free public name. There is no
+  compatibility alias (per the audit's no-shim requirement) — consumers importing
+  `ViewMode` from `@lostgradient/cinder` or `@lostgradient/cinder/diff-viewer` must
+  import `DiffViewerMode` instead.
+
+  **Accessibility.** `CheckboxGroup` and `RadioGroup` now emit a development-only
+  warning when they render a `<fieldset>` without an accessible group name
+  (`<legend>`/label), matching the rest of the form-control suite.
+
+  **Correctness.** The `run-step-timeline` rail uses logical positioning
+  (`inset-inline-start`/`inset-block-start`/`inline-size`) so it lays out correctly
+  in right-to-left contexts. Several icon-button hit areas were enlarged for touch.
+
+  **Maintenance (no behavior change).** Svelte 4 lifecycle helpers migrated to
+  `$effect`, hand-rolled `ResizeObserver` setups moved to the shared
+  `useResizeObserver` utility, and `use:`-actions converted to `{@attach}`
+  attachments. Form-control `error` props consistently include `undefined`.
+  Review-editor types are consolidated into one authoritative module.
+
+- [#477](https://github.com/stevekinney/cinder/pull/477) [`15a46b3`](https://github.com/stevekinney/cinder/commit/15a46b35247473b87beebbb2088795fc3352c9be) Thanks [@stevekinney](https://github.com/stevekinney)! - **Breaking: PascalCase event-callback props renamed to lowercase.** Svelte 5 event
+  props use the same lowercase syntax as DOM handler props (`onclick`, `ondismiss`),
+  and cinder's convention is all-lowercase. The following public callback props are
+  renamed to their lowercase forms across the affected components (alert, banner,
+  capability-gate, collapsible, click-away-listener, data-grid, load-more,
+  markdown-editor, media-controls, table, table-header, table-row, transfer-list,
+  tree, tree-item):
+
+  `onDismiss`→`ondismiss`, `onToggle`→`ontoggle`, `onReorder`→`onreorder`,
+  `onPlay`→`onplay`, `onLoadMore`→`onloadmore`, `onSelectedChange`→`onselectedchange`,
+  `onSelectionChange`→`onselectionchange`, `onFilterChange`→`onfilterchange`,
+  `onPause`→`onpause`, `onReplay`→`onreplay`, `onLoadError`→`onloaderror`,
+  `onRename`→`onrename`, `onChange`→`onchange`, `onClickAway`→`onclickaway`,
+  `onSortChange`→`onsortchange`, `onSortModelChange`→`onsortmodelchange`,
+  `onSelectionModelChange`→`onselectionmodelchange`, `onReady`→`onready`.
+
+  Each renamed callback keeps the same payload arguments and invocation timing. No
+  compatibility aliases are provided — update call sites to the lowercase names.
+
+  The stable-promotion `PROP_NAME_DENYLIST` is now compared case-insensitively for
+  `on*` props, so a PascalCase event-callback prop can no longer slip past the gate.
+
+- [#524](https://github.com/stevekinney/cinder/pull/524) [`680c499`](https://github.com/stevekinney/cinder/commit/680c499a8822882693f387f93f0eab9c086a12b8) Thanks [@stevekinney](https://github.com/stevekinney)! - Enhance RunStepTimeline with waiting-approval state, nested child lanes, step links, and action counts.
+
+- [#524](https://github.com/stevekinney/cinder/pull/524) [`680c499`](https://github.com/stevekinney/cinder/commit/680c499a8822882693f387f93f0eab9c086a12b8) Thanks [@stevekinney](https://github.com/stevekinney)! - Promote the Stardust agent-operations components based on promotion-gate evidence.
+
+  `EventStreamViewer`, `PayloadInspector`, and `SecretValueField` are now marked stable. `InvocationRuleBuilder` is now marked beta after passing the same readiness gate with tests, accessibility coverage, and prop-name checks passing.
+
+  `SecretValueField` also now uses Svelte's explicit untracked initial-state capture for `initiallyRevealed`, preserving its initial-only behavior while avoiding a local-state warning.
+
+- [#478](https://github.com/stevekinney/cinder/pull/478) [`0302908`](https://github.com/stevekinney/cinder/commit/03029085e54dcc3344d568821e553340f70d17fc) Thanks [@stevekinney](https://github.com/stevekinney)! - **Breaking: unify public API vocabulary across components.** Several public APIs
+  used different words for the same concept; this standardizes them. No compatibility
+  aliases are provided (per the audit's no-shim requirement) — update call sites.
+  - **Severity spelling.** `alert` and `status-dot` drop the `error` value in favor of
+    `danger`, the canonical failure-severity spelling already used by `banner` and
+    `callout`. Use `variant="danger"` (Alert) / `status="danger"` (StatusDot) instead
+    of `"error"`.
+  - **Accessible-name props.** `ariaLabel` / `navAriaLabel` are renamed to `label` on
+    `sidebar`, `scroll-area`, `navigation-bar`, and `dropdown-group`; `StatChange.ariaLabel`
+    becomes `StatChange.label`.
+  - **Chat boolean props.** `isAtBottom` → `atBottom`, `hasNewMessageIndicator` →
+    `newMessageIndicatorVisible`, `isStreaming` → `streaming`, `hasMoreHistory` →
+    `moreHistoryAvailable`. The per-feature `allow*` flags (`allowAttachments`,
+    `allowSearch`, `allowCopy`, `allowEditing`, `allowRetry`) are grouped into a single
+    `capabilities` object prop.
+  - **FloatingActionButton visual API.** `color` → `variant` (the palette) and
+    `variant` → `shape` (filled/extended). The exported types rename accordingly:
+    `FloatingActionButtonColor` → `FloatingActionButtonVariant` and the old
+    `FloatingActionButtonVariant` → `FloatingActionButtonShape`.
+
+  Generated schemas, README tables, examples, and package exports are updated to match.
+
+### Patch Changes
+
+- [#470](https://github.com/stevekinney/cinder/pull/470) [`644a646`](https://github.com/stevekinney/cinder/commit/644a646edccd03cc6f4394c1ed532643101083b0) Thanks [@stevekinney](https://github.com/stevekinney)! - Add `@media (forced-colors: active)` focus-ring fallbacks to nine components whose `:focus-visible` ring relied exclusively on `box-shadow` — which Windows High Contrast Mode (forced-colors) removes. Keyboard focus was invisible in HCM for users of CapabilityGate, KanbanBoard, MediaControls, PermissionMatrix, ShareCard, TransferList, Table, MenuBar, and ChatConversationList.
+
+  Each fallback repaints the outline with `ButtonText` at the correct offset for the control type: `3px` for bordered controls (separates the ring from `ButtonBorder`, which shares the `ButtonText` color family in HCM), `2px` for borderless controls, and an inset `calc(-1 * var(--cinder-ring-width))` for the TransferList scrollable panel (which has `overflow: auto` — a positive offset would be clipped). Each fallback also sets `box-shadow: none` explicitly so forced-colors suppression is unambiguous across engines.
+
+  A new Stylelint rule (`cinder/require-forced-colors-focus-fallback`) is wired into root `.stylelintrc.json` and into the test suite, so any future `:focus-visible` rule that relies on `box-shadow` without a matching forced-colors fallback will fail linting.
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -2,7 +2,7 @@
 
 Svelte 5 components for product interfaces: accessible primitives, design-system tokens, per-component CSS, generated prop schemas, and examples that can be read by people or tooling.
 
-Use cinder when you want UI building blocks without adopting a framework-level state, routing, form, or theme provider. The package is SSR-safe and targets Svelte `>=5.55.0 <6`.
+Use cinder when you want UI building blocks without adopting a framework-level router, form-state manager, data fetching layer, global state provider, or theme provider. The package is SSR-safe and targets Svelte `>=5.55.0 <6`.
 
 ## Install
 
@@ -126,7 +126,7 @@ Cinder is a presentation library, not an application framework.
 
 - No router.
 - No form-state manager.
-- No toast queue store.
+- No application-wide toast singleton; use `ToastRegion` for scoped toast UI.
 - No data fetching layer.
 - No global state provider.
 - No general-purpose icon library for product-specific icons.

package/components.json

@@ -3,7 +3,7 @@
   "manifestVersion": 1,
   "package": {
     "name": "@lostgradient/cinder",
-    "version": "0.3.0",
+    "version": "0.4.1",
     "framework": "svelte",
     "frameworkVersionRange": ">=5.55.0 <6",
     "classPrefix": "cinder-",
@@ -239,6 +239,49 @@
         "examples": "@lostgradient/cinder/alert-dialog/examples"
       }
     },
+    {
+      "name": "ApprovalCard",
+      "id": "approval-card",
+      "import": "@lostgradient/cinder/approval-card",
+      "exportName": "ApprovalCard",
+      "category": "domain",
+      "status": "alpha",
+      "purpose": "Durable human-in-the-loop approval surface for reviewing risky tool operations before they execute.",
+      "tags": ["approval", "human-in-the-loop", "tool"],
+      "useWhen": [
+        "A tool call, command, file write, or patch needs explicit human approval before execution.",
+        "Showing policy, sandbox, idempotency, environment-name, and argument context for an approval request."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "The action has already completed and only needs historical display — use event-stream-viewer or run-step-timeline instead."
+        },
+        {
+          "reason": "Collecting arbitrary form input for a workflow — compose form controls directly instead."
+        }
+      ],
+      "related": [
+        "card",
+        "badge",
+        "status-dot",
+        "payload-inspector",
+        "secret-value-field",
+        "code-block"
+      ],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/approval-card/schema",
+        "variables": "@lostgradient/cinder/approval-card/variables",
+        "examples": "@lostgradient/cinder/approval-card/examples"
+      },
+      "a11y": {
+        "notes": [
+          "Uses a named region and native button controls so approval actions are discoverable by assistive technology.",
+          "Expiration changes update the visible state but do not fire approval callbacks automatically."
+        ]
+      }
+    },
     {
       "name": "AreaChart",
       "id": "area-chart",
@@ -424,10 +467,12 @@
       "category": "data-display",
       "status": "stable",
       "purpose": "Compact non-interactive label that annotates an adjacent element with a short status, count, or category.",
-      "tags": ["label", "indicator"],
+      "tags": ["billing", "label", "indicator", "subscription"],
       "useWhen": [
         "Annotating a value with a short status word like \"new\" or \"beta\".",
-        "Displaying a numeric count next to an icon or title."
+        "Displaying a numeric count next to an icon or title.",
+        "Displaying the billing state of a subscription in a dashboard, invoice list, or account settings page.",
+        "Annotating a plan name, customer row, or invoice line with its current payment lifecycle state."
       ],
       "avoidWhen": [
         {
@@ -469,10 +514,11 @@
       ],
       "related": ["alert", "callout", "toast-region"],
       "hasConstraints": false,
-      "hasExamples": false,
+      "hasExamples": true,
       "artifacts": {
         "schema": "@lostgradient/cinder/banner/schema",
-        "variables": "@lostgradient/cinder/banner/variables"
+        "variables": "@lostgradient/cinder/banner/variables",
+        "examples": "@lostgradient/cinder/banner/examples"
       }
     },
     {
@@ -619,10 +665,11 @@
       ],
       "related": ["alert", "banner"],
       "hasConstraints": false,
-      "hasExamples": false,
+      "hasExamples": true,
       "artifacts": {
         "schema": "@lostgradient/cinder/callout/schema",
-        "variables": "@lostgradient/cinder/callout/variables"
+        "variables": "@lostgradient/cinder/callout/variables",
+        "examples": "@lostgradient/cinder/callout/examples"
       }
     },
     {
@@ -825,10 +872,11 @@
       ],
       "related": ["checkbox", "radio-group", "form-field"],
       "hasConstraints": false,
-      "hasExamples": false,
+      "hasExamples": true,
       "artifacts": {
         "schema": "@lostgradient/cinder/checkbox-group/schema",
-        "variables": "@lostgradient/cinder/checkbox-group/variables"
+        "variables": "@lostgradient/cinder/checkbox-group/variables",
+        "examples": "@lostgradient/cinder/checkbox-group/examples"
       }
     },
     {
@@ -1074,10 +1122,11 @@
       ],
       "related": ["color-picker"],
       "hasConstraints": false,
-      "hasExamples": false,
+      "hasExamples": true,
       "artifacts": {
         "schema": "@lostgradient/cinder/color-swatch-picker/schema",
-        "variables": "@lostgradient/cinder/color-swatch-picker/variables"
+        "variables": "@lostgradient/cinder/color-swatch-picker/variables",
+        "examples": "@lostgradient/cinder/color-swatch-picker/examples"
       }
     },
     {
@@ -1229,32 +1278,6 @@
         "examples": "@lostgradient/cinder/confirm-dialog/examples"
       }
     },
-    {
-      "name": "ConnectionIndicator",
-      "id": "connection-indicator",
-      "import": "@lostgradient/cinder/connection-indicator",
-      "exportName": "ConnectionIndicator",
-      "category": "feedback",
-      "status": "stable",
-      "purpose": "Live-status pill pairing a semantic dot with a label to communicate real-time WebSocket, SSE, or polling connection state.",
-      "tags": ["connection", "status", "realtime"],
-      "useWhen": [
-        "Surfacing whether a realtime channel is connected, connecting, disconnected, or errored on a dashboard or app chrome.",
-        "Giving operators an at-a-glance health signal for a long-lived transport."
-      ],
-      "avoidWhen": [
-        {
-          "reason": "Communicating generic semantic state with no realtime connection backing it — status-dot is the lower-level primitive."
-        }
-      ],
-      "related": ["status-dot", "spinner"],
-      "hasConstraints": false,
-      "hasExamples": false,
-      "artifacts": {
-        "schema": "@lostgradient/cinder/connection-indicator/schema",
-        "variables": "@lostgradient/cinder/connection-indicator/variables"
-      }
-    },
     {
       "name": "Container",
       "id": "container",
@@ -1450,7 +1473,7 @@
           "reason": "You need custom cell rendering, interactive cells, nested components, or column spanning — use the compositional Table family directly."
         },
         {
-          "reason": "You need row selection — DataTable does not expose a selection prop; use Table with selectable instead."
+          "reason": "You need fully custom cell or row composition — use Table directly."
         }
       ],
       "related": [
@@ -1487,7 +1510,7 @@
           "reason": "A single date is sufficient — use a plain date input instead."
         },
         {
-          "reason": "Date-time precision (hours/minutes/timezone) is required — this v1 is date-only."
+          "reason": "Timezone conversion or a standalone time-of-day value is required — use time-field for the latter."
         }
       ],
       "related": ["input", "form-field", "chip", "segmented-control"],
@@ -1901,7 +1924,7 @@
       "import": "@lostgradient/cinder/event-stream-viewer",
       "exportName": "EventStreamViewer",
       "category": "data-display",
-      "status": "beta",
+      "status": "stable",
       "purpose": "Dense append-only log of timestamped events with follow-latest scrolling, severity tones, expandable JSON details, and copy actions.",
       "tags": ["log", "stream", "events"],
       "useWhen": [
@@ -1916,7 +1939,7 @@
           "reason": "Rendering paginated historical records with sorting — use data-table instead."
         }
       ],
-      "related": ["feed", "timeline", "json-viewer", "connection-indicator", "copy-button"],
+      "related": ["feed", "timeline", "json-viewer", "status-dot", "copy-button"],
       "hasConstraints": false,
       "hasExamples": true,
       "artifacts": {
@@ -2028,10 +2051,11 @@
       ],
       "related": ["form-field", "progress", "input"],
       "hasConstraints": false,
-      "hasExamples": false,
+      "hasExamples": true,
       "artifacts": {
         "schema": "@lostgradient/cinder/file-upload/schema",
-        "variables": "@lostgradient/cinder/file-upload/variables"
+        "variables": "@lostgradient/cinder/file-upload/variables",
+        "examples": "@lostgradient/cinder/file-upload/examples"
       }
     },
     {
@@ -2307,10 +2331,11 @@
       ],
       "related": ["avatar"],
       "hasConstraints": false,
-      "hasExamples": false,
+      "hasExamples": true,
       "artifacts": {
         "schema": "@lostgradient/cinder/image/schema",
-        "variables": "@lostgradient/cinder/image/variables"
+        "variables": "@lostgradient/cinder/image/variables",
+        "examples": "@lostgradient/cinder/image/examples"
       }
     },
     {
@@ -2350,7 +2375,7 @@
       "import": "@lostgradient/cinder/invocation-rule-builder",
       "exportName": "InvocationRuleBuilder",
       "category": "form",
-      "status": "alpha",
+      "status": "beta",
       "purpose": "Render and edit conditional automation rules composed of conditions and actions.",
       "tags": ["automation", "rules"],
       "useWhen": [
@@ -2617,6 +2642,32 @@
         "examples": "@lostgradient/cinder/load-more/examples"
       }
     },
+    {
+      "name": "LocaleProvider",
+      "id": "locale-provider",
+      "import": "@lostgradient/cinder/locale-provider",
+      "exportName": "LocaleProvider",
+      "category": "layout",
+      "status": "stable",
+      "purpose": "Context provider that supplies a shared locale and text direction default to locale-aware descendant components.",
+      "tags": ["locale", "internationalization"],
+      "useWhen": [
+        "Setting one application or subtree locale for number, region, date, or time formatting.",
+        "Providing text direction once for direction-aware descendants while still allowing local overrides."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "Only one component needs a non-default locale — pass that component's locale prop directly instead."
+        }
+      ],
+      "related": ["number-input", "phone-input", "stat"],
+      "hasConstraints": false,
+      "hasExamples": false,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/locale-provider/schema",
+        "variables": "@lostgradient/cinder/locale-provider/variables"
+      }
+    },
     {
       "name": "MarkdownEditor",
       "id": "markdown-editor",
@@ -2917,10 +2968,11 @@
       ],
       "related": ["input", "slider"],
       "hasConstraints": false,
-      "hasExamples": false,
+      "hasExamples": true,
       "artifacts": {
         "schema": "@lostgradient/cinder/number-input/schema",
-        "variables": "@lostgradient/cinder/number-input/variables"
+        "variables": "@lostgradient/cinder/number-input/variables",
+        "examples": "@lostgradient/cinder/number-input/examples"
       }
     },
     {
@@ -2959,7 +3011,7 @@
       "import": "@lostgradient/cinder/payload-inspector",
       "exportName": "PayloadInspector",
       "category": "data-display",
-      "status": "beta",
+      "status": "stable",
       "purpose": "Composed inspector for structured payloads with summary, tree, and raw views, copy actions, and size/truncation status.",
       "tags": ["json", "inspector", "payload"],
       "useWhen": [
@@ -3344,10 +3396,10 @@
       "exportName": "SchemaForm",
       "category": "form",
       "status": "beta",
-      "purpose": "Schema-driven form that renders accessible controls from JSON Schema or Standard Schema and submits one validated value object.",
+      "purpose": "Schema-driven form that renders accessible controls from JSON Schema and submits one validated value object.",
       "tags": ["form", "schema", "validation"],
       "useWhen": [
-        "Capturing a payload whose shape is already described by a workflow, API, or Standard Schema validator.",
+        "Capturing a payload whose shape is already described by a workflow, API, or JSON Schema document.",
         "You need callback submission and native FormData submission to expose the same validated object."
       ],
       "avoidWhen": [
@@ -3442,7 +3494,7 @@
       "import": "@lostgradient/cinder/secret-value-field",
       "exportName": "SecretValueField",
       "category": "data-display",
-      "status": "beta",
+      "status": "stable",
       "purpose": "Displays a masked secret (API key, token, webhook secret) with copy action and optional reveal toggle.",
       "tags": ["clipboard", "security"],
       "useWhen": [
@@ -3933,10 +3985,11 @@
       ],
       "related": ["grid-list"],
       "hasConstraints": false,
-      "hasExamples": false,
+      "hasExamples": true,
       "artifacts": {
         "schema": "@lostgradient/cinder/sortable-list/schema",
-        "variables": "@lostgradient/cinder/sortable-list/variables"
+        "variables": "@lostgradient/cinder/sortable-list/variables",
+        "examples": "@lostgradient/cinder/sortable-list/examples"
       }
     },
     {
@@ -4186,11 +4239,13 @@
       "exportName": "StatusDot",
       "category": "feedback",
       "status": "stable",
-      "purpose": "Static role=\"img\" badge that communicates an entity's state through a colored dot with an accessible text label.",
-      "tags": ["feedback", "status"],
+      "purpose": "Colored dot indicator that communicates static entity state or live realtime connection state with an accessible text label.",
+      "tags": ["connection", "feedback", "realtime", "status"],
       "useWhen": [
         "Indicating the current state of a list row, user, deployment, or other entity alongside its name.",
-        "Communicating status compactly when many indicators appear together without triggering live-region announcements."
+        "Communicating status compactly when many indicators appear together without triggering live-region announcements.",
+        "Surfacing whether a realtime channel is connected, connecting, disconnected, or errored on a dashboard or app chrome.",
+        "Giving operators an at-a-glance health signal for a long-lived transport."
       ],
       "avoidWhen": [
         {
@@ -4239,36 +4294,6 @@
         "examples": "@lostgradient/cinder/steps/examples"
       }
     },
-    {
-      "name": "SubscriptionBadge",
-      "id": "subscription-badge",
-      "import": "@lostgradient/cinder/subscription-badge",
-      "exportName": "SubscriptionBadge",
-      "category": "data-display",
-      "status": "alpha",
-      "purpose": "Opinionated Badge variant that communicates billing subscription states with a standardized tone, icon, and human-readable label.",
-      "tags": ["billing", "subscription", "status"],
-      "useWhen": [
-        "Displaying the billing state of a subscription in a dashboard, invoice list, or account settings page.",
-        "Annotating a plan name, customer row, or invoice line with its current payment lifecycle state."
-      ],
-      "avoidWhen": [
-        {
-          "reason": "The subscription state is not one of the six recognized values — use Badge directly with a custom label instead."
-        },
-        {
-          "reason": "You need an interactive control that lets users change the state — use a Button or Select."
-        }
-      ],
-      "related": ["badge", "status-dot", "chip"],
-      "hasConstraints": false,
-      "hasExamples": true,
-      "artifacts": {
-        "schema": "@lostgradient/cinder/subscription-badge/schema",
-        "variables": "@lostgradient/cinder/subscription-badge/variables",
-        "examples": "@lostgradient/cinder/subscription-badge/examples"
-      }
-    },
     {
       "name": "Surface",
       "id": "surface",
@@ -4627,6 +4652,33 @@
         "examples": "@lostgradient/cinder/textarea/examples"
       }
     },
+    {
+      "name": "TimeField",
+      "id": "time-field",
+      "import": "@lostgradient/cinder/time-field",
+      "exportName": "TimeField",
+      "category": "form",
+      "status": "stable",
+      "purpose": "Standalone time-of-day field that collects a canonical time string with optional timezone selection.",
+      "tags": ["form", "time", "internationalization"],
+      "useWhen": [
+        "Collecting a time of day without a date, such as a reminder time or office-hours boundary.",
+        "Pairing a time value with an optional timezone while keeping a canonical `HH:mm` or `HH:mm:ss` value."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "Collecting a full date range — use date-range-field instead."
+        }
+      ],
+      "related": ["date-range-field", "number-input"],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/time-field/schema",
+        "variables": "@lostgradient/cinder/time-field/variables",
+        "examples": "@lostgradient/cinder/time-field/examples"
+      }
+    },
     {
       "name": "Timeline",
       "id": "timeline",

package/dist/_internal/locale-context.d.ts

@@ -0,0 +1,9 @@
+export type TextDirection = 'ltr' | 'rtl';
+export type LocaleContext = {
+    /** BCP 47 locale tag used by locale-aware components when no local prop is set. */
+    readonly locale: string | undefined;
+    /** Text direction for components that need direction-aware behavior. */
+    readonly direction: TextDirection | undefined;
+};
+export declare function setLocaleContext(context: LocaleContext): void;
+export declare const getLocaleContext: () => LocaleContext | undefined;

package/dist/_internal/text-direction.d.ts

@@ -0,0 +1,4 @@
+import type { TextDirection } from './locale-context.ts';
+export declare function resolveTextDirection(element: HTMLElement | null | undefined, fallback?: TextDirection): TextDirection | undefined;
+export declare function isRightToLeftElement(element: HTMLElement | null | undefined): boolean;
+export declare function observeTextDirection(element: HTMLElement | null | undefined, onChange: () => void): (() => void) | undefined;

package/dist/_internal/tree-context.d.ts

@@ -36,6 +36,8 @@ export type TreeContext = {
     isExpanded(id: string): boolean;
     isSelected(id: string): boolean;
     isFocused(id: string): boolean;
+    positionInSet(id: string): number | undefined;
+    setSize(id: string): number | undefined;
     isVisible(id: string): boolean;
     hasVisibleDescendant(id: string): boolean;
     matchesFilter(label: string, id: string): boolean;

package/dist/api-contract.d.ts

@@ -36,7 +36,7 @@ export type SnippetSpec = {
 };
 export type PropSpec = {
     optional: boolean;
-    type_kind: 'TSStringKeyword' | 'TSBooleanKeyword' | 'TSNumberKeyword' | 'TSLiteralType' | 'TSUnionType' | 'TSTypeReference' | 'TSArrayType' | 'TSFunctionType' | 'TSTypeOperator';
+    type_kind: 'TSStringKeyword' | 'TSBooleanKeyword' | 'TSNumberKeyword' | 'TSLiteralType' | 'TSUnionType' | 'TSTypeReference' | 'TSArrayType' | 'TSFunctionType' | 'TSTypeOperator' | 'TSUndefinedKeyword';
     default?: DefaultSpec;
 };
 export type ContractArm = {