@lostgradient/cinder 0.1.0

package/dist/_internal/anchored-overlay.svelte.d.ts

@@ -0,0 +1,24 @@
+import type { Placement, ReferenceElement } from '@floating-ui/dom';
+export type AnchoredOverlayWidthMode = 'content' | 'match-anchor' | 'menu' | 'none';
+export type AnchoredOverlayOptions = {
+    open: () => boolean;
+    anchor: () => ReferenceElement | null | undefined;
+    panel: () => HTMLElement | null | undefined;
+    arrow?: () => HTMLElement | null | undefined;
+    placement?: () => Placement;
+    offset?: () => number;
+    shiftPadding?: () => number;
+    shiftCrossAxis?: () => boolean;
+    arrowPadding?: () => number;
+    showArrow?: () => boolean;
+    widthMode?: () => AnchoredOverlayWidthMode;
+};
+export declare function getAnchoredOverlayWidthStyle(widthMode: AnchoredOverlayWidthMode, anchorRect: DOMRect | {
+    width: number;
+} | null | undefined): string;
+export declare function createAnchoredOverlay(options: AnchoredOverlayOptions): {
+    readonly positionReady: boolean;
+    readonly positionStyle: string;
+    readonly resolvedPlacement: Placement;
+    readonly arrowStyle: string;
+};

package/dist/_internal/chart/chart-interaction.svelte.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Shared reactive interaction state for all chart components.
+ *
+ * Encapsulates the pointer/keyboard target tracking, resize observation, and
+ * target-staleness cleanup that are identical across LineChart, AreaChart, and
+ * BarChart. Each chart component instantiates ChartInteraction once and reads
+ * `activeTarget`, `measuredWidth`, and the handler functions from it.
+ *
+ * Series-specific logic (model creation, crosshair direction, focus-target
+ * element shape) stays in each individual chart component.
+ */
+import { type ChartTarget } from './chart-utilities.ts';
+export type ChartInteractionOptions = {
+    /**
+     * Pixel axis used by nearestTarget when the pointer moves. Defaults to 'x'.
+     * Bar charts switch this to 'y' when orientation is 'horizontal'. Pass a
+     * reactive getter (e.g. `() => orientation === 'vertical' ? 'x' : 'y'`) to
+     * follow orientation changes without re-instantiating the class.
+     */
+    pointerAxis?: 'x' | 'y' | (() => 'x' | 'y');
+};
+export declare class ChartInteraction {
+    #private;
+    /** Current measured container width in pixels. Starts at 640 as a reasonable SSR default. */
+    measuredWidth: number;
+    /** Target activated by pointer movement. Cleared on pointer-leave. */
+    pointerTarget: ChartTarget | undefined;
+    /** Target activated by keyboard navigation. Cleared on Escape or blur. */
+    focusedTarget: ChartTarget | undefined;
+    /**
+     * The active target visible to the tooltip and crosshair.
+     * Keyboard focus wins over pointer so screen-reader users are never
+     * overridden by incidental pointer events.
+     */
+    activeTarget: ChartTarget | undefined;
+    constructor(options?: ChartInteractionOptions);
+    /**
+     * Attaches a ResizeObserver to the chart root element and updates
+     * `measuredWidth` whenever the element's content rect changes.
+     * Returns a cleanup function for use inside `$effect`.
+     */
+    observeResize(element: HTMLElement): () => void;
+    /**
+     * Clears stale targets when the model's target set changes (e.g. after a
+     * legend toggle that removes the currently active series). Also clears both
+     * targets when the chart enters a loading or empty state.
+     *
+     * Call inside a `$effect` that reads `loading`, `empty`, and `targets`.
+     */
+    clearStaleTargets(loading: boolean, empty: boolean, targets: readonly ChartTarget[]): void;
+    /**
+     * Updates `pointerTarget` from a PointerEvent fired on the SVG hit surface.
+     * The hit surface must be an SVGRectElement.
+     */
+    activateByPointer(event: PointerEvent, targets: readonly ChartTarget[]): void;
+    /**
+     * Clears `pointerTarget` on pointer-leave of the hit surface.
+     */
+    clearPointerTarget(): void;
+    /**
+     * Moves DOM focus to the SVG element carrying the given `data-cinder-target-id`
+     * attribute. Keeps `:focus-visible`, `aria-describedby`, and `aria-label`
+     * synchronized with the keyboard-active target.
+     */
+    focusDomTarget(rootElement: HTMLElement, targetId: string | undefined): void;
+    /**
+     * Handles keyboard navigation across chart targets.
+     *
+     * - ArrowRight / ArrowDown — advance one target
+     * - ArrowLeft / ArrowUp — retreat one target
+     * - Home — jump to first target
+     * - End — jump to last target
+     * - Escape — clear focused target
+     *
+     * All navigating keys call `event.preventDefault()` so the page does not
+     * scroll during chart keyboard navigation.
+     */
+    activateByKeyboard(event: KeyboardEvent, rootElement: HTMLElement, targets: readonly ChartTarget[], keyboardEnabled: boolean): void;
+    /**
+     * Toggles a series in the hidden set and returns the updated array.
+     * Pure — does not mutate its argument.
+     */
+    toggleSeries(hiddenSeriesIds: string[], seriesId: string): string[];
+}

package/dist/_internal/chart/chart-utilities.d.ts

@@ -0,0 +1,161 @@
+import type { BarChartDatum, BarChartMode, BarChartOrientation, BarChartSeries, ChartAxisConfiguration, ChartCartesianSeries, ChartDataTableVisibility, ChartFormatterContext, ChartLegendPosition, ChartNumericValue, ChartXValue } from '../../components/chart.types.ts';
+export declare const chartPalette: readonly ["var(--cinder-chart-series-1)", "var(--cinder-chart-series-2)", "var(--cinder-chart-series-3)", "var(--cinder-chart-series-4)", "var(--cinder-chart-series-5)", "var(--cinder-chart-series-6)", "var(--cinder-chart-series-7)", "var(--cinder-chart-series-8)"];
+/**
+ * Resolves a palette color for a series by index, wrapping around the palette.
+ * Exported so chart components can render legend swatches using the same
+ * resolved color the chart uses for the series itself.
+ */
+export declare function chartPaletteColor(index: number): string;
+export type NormalizedXValue = {
+    raw: ChartXValue;
+    key: string;
+    label: string;
+    comparable: string | number;
+    kind: 'string' | 'number' | 'date';
+};
+export type NormalizedPoint = {
+    seriesId: string;
+    seriesLabel: string;
+    color: string;
+    x: NormalizedXValue;
+    y: number | null;
+    originalY: ChartNumericValue;
+    index: number;
+};
+/**
+ * A point that has been placed in pixel space by the chart model. Components
+ * read `pixelX`/`pixelY` directly without a secondary lookup against targets.
+ */
+export type PlacedPoint = NormalizedPoint & {
+    pixelX: number;
+    pixelY: number;
+};
+export type ChartTarget = {
+    id: string;
+    seriesId: string;
+    seriesLabel: string;
+    xLabel: string;
+    valueLabel: string;
+    x: number;
+    y: number;
+    width?: number;
+    height?: number;
+    color: string;
+};
+export type ChartGeometry = {
+    plotWidth: number;
+    plotHeight: number;
+    marginTop: number;
+    marginRight: number;
+    marginBottom: number;
+    marginLeft: number;
+};
+/**
+ * An x-axis tick paired with its already-scaled pixel position. Charts render
+ * labels at the model-provided `x` so labels and points stay aligned for
+ * numeric and date domains.
+ */
+export type ChartXTick = {
+    label: string;
+    x: number;
+};
+export type CartesianChartModel = {
+    geometry: ChartGeometry;
+    /** Pre-scaled x-axis ticks. Render labels at `tick.x`, not by ordinal index. */
+    xTicks: ChartXTick[];
+    yTicks: number[];
+    normalizedSeries: Array<{
+        id: string;
+        label: string;
+        color: string;
+        points: PlacedPoint[];
+        path: string;
+        areaPath: string;
+        hidden: boolean;
+    }>;
+    tableRows: Array<{
+        id: string;
+        seriesLabel: string;
+        xLabel: string;
+        valueLabel: string;
+    }>;
+    /** Targets sorted by `x` (binary-search precondition for nearestTarget). */
+    targets: ChartTarget[];
+    empty: boolean;
+    yDomain: [number, number];
+};
+export type BarChartModel = {
+    geometry: ChartGeometry;
+    categories: NormalizedXValue[];
+    yTicks: number[];
+    categoryTicks: Array<{
+        label: string;
+        x: number;
+        y: number;
+    }>;
+    bars: Array<{
+        id: string;
+        seriesId: string;
+        seriesLabel: string;
+        categoryLabel: string;
+        valueLabel: string;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        color: string;
+        hidden: boolean;
+    }>;
+    tableRows: Array<{
+        categoryLabel: string;
+        values: Array<{
+            seriesId: string;
+            seriesLabel: string;
+            valueLabel: string;
+        }>;
+    }>;
+    targets: ChartTarget[];
+    empty: boolean;
+    valueDomain: [number, number];
+};
+export declare function assertValidChartNumber(componentId: string, rule: string, value: number, label: string): void;
+export declare function assertValidNonNegativeInteger(componentId: string, rule: string, value: number, label: string): void;
+export declare function assertValidTickCount(componentId: string, axis?: ChartAxisConfiguration): void;
+export declare function dataTableClass(visibility: ChartDataTableVisibility): string | undefined;
+export declare function formatXValue(value: NormalizedXValue, axis: ChartAxisConfiguration | undefined, context: ChartFormatterContext): string;
+export declare function formatNumericValue(value: number, axis: ChartAxisConfiguration | undefined, formatter: ((value: number, context: ChartFormatterContext) => string) | undefined, context: ChartFormatterContext): string;
+export declare function normalizeXValue(value: ChartXValue): NormalizedXValue;
+export declare function assertUniqueSeriesIds(componentId: string, series: Array<{
+    id: string;
+}>): void;
+export declare function toggleSeriesId(hiddenSeriesIds: string[], seriesId: string): string[];
+export declare function createCartesianModel(options: {
+    componentId: 'line-chart' | 'area-chart';
+    series: ChartCartesianSeries[];
+    hiddenSeriesIds: string[];
+    width: number;
+    height: number;
+    xAxis?: ChartAxisConfiguration | undefined;
+    yAxis?: ChartAxisConfiguration | undefined;
+    stackedArea?: boolean;
+}): CartesianChartModel;
+export declare function createBarModel(options: {
+    data: BarChartDatum[];
+    categoryKey: string;
+    series: BarChartSeries[];
+    hiddenSeriesIds: string[];
+    width: number;
+    height: number;
+    orientation: BarChartOrientation;
+    mode: BarChartMode;
+    xAxis?: ChartAxisConfiguration | undefined;
+    yAxis?: ChartAxisConfiguration | undefined;
+}): BarChartModel;
+/**
+ * Locates the target closest to a (x, y) pointer. Uses binary search on the
+ * provided `axis` (defaults to `x`) — targets MUST be sorted ascending on that
+ * axis (createCartesianModel and createBarModel guarantee this). Falls back to
+ * a linear scan when targets are empty.
+ */
+export declare function nearestTarget(targets: readonly ChartTarget[], x: number, y: number, axis?: 'x' | 'y'): ChartTarget | undefined;
+export declare function legendVisible(legendPosition: ChartLegendPosition, seriesCount: number): boolean;

package/dist/_internal/collection.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Internal collection / selection contract shared by parent-child components.
+ *
+ * Components that coordinate a parent (group) with N children where exactly one
+ * (or any subset) is "active" all need the same plumbing:
+ *
+ * - A reactive value (or set of values) the parent owns and mutates.
+ * - A `toggle` (multi) or `select` (single) function children call.
+ * - An `isActive(id)` predicate children read.
+ * - Keyboard navigation across the children, where arrow keys move focus or
+ *   active state, and only one child sits in the tab order at a time
+ *   (roving tabindex).
+ *
+ * This module exposes minimal helpers that the new Phase 1 components
+ * (RadioGroup, Tabs) consume directly, and that Accordion can adopt while
+ * preserving its public `AccordionContext` shape.
+ *
+ * The helpers return plain objects with getters — they do **not** themselves
+ * call `setContext`. Each consuming parent owns its own context key and
+ * shape, since the public API that children read from differs (Accordion
+ * exposes `expandedIds`, RadioGroup exposes `value`, etc.).
+ */
+/**
+ * Predicate for which key counts as "next" / "previous" given the current
+ * orientation. RadioGroup is non-orientable (per WAI-ARIA radiogroup the
+ * arrow keys move within the group regardless of orientation), Tabs and
+ * Toolbar are orientable.
+ */
+export type Orientation = 'horizontal' | 'vertical';
+/**
+ * Returns the navigation intent for a key event given an orientation. Pure —
+ * does not access the DOM or stop the event. The caller is responsible for
+ * `event.preventDefault()` after acting on the intent.
+ */
+export declare function navigationIntent(key: string, orientation?: Orientation): 'next' | 'previous' | 'first' | 'last' | null;
+/**
+ * Compute the next index for a list of length `length`, given a `current`
+ * index and a navigation intent. Wraps around at the boundaries (per WAI-ARIA
+ * convention for radiogroup, tablist, etc.).
+ *
+ * Returns the same `current` index when `length` is 0 (defensive: no items
+ * means no navigation).
+ */
+export declare function nextIndex(current: number, length: number, intent: 'next' | 'previous' | 'first' | 'last'): number;
+/**
+ * Single-selection state holder. Wraps a bindable `value` getter/setter pair
+ * so the consumer (Tabs, RadioGroup) doesn't reimplement the same select/
+ * isSelected logic. Returns plain functions; the consumer wires them into
+ * its context.
+ *
+ * Generic over the value type so RadioGroup can use string values, Tabs
+ * can use string or number values, etc.
+ */
+export declare function createSingleSelection<T>(getValue: () => T, setValue: (next: T) => void): {
+    readonly value: T;
+    select: (next: T) => void;
+    isSelected: (candidate: T) => boolean;
+};
+/**
+ * Multi-selection state holder. Wraps a bindable `values` getter/setter pair
+ * so the consumer (Accordion when `multiple=true`) doesn't reimplement the
+ * same toggle/isSelected logic.
+ *
+ * The setter receives a fresh array each toggle so reactivity is preserved
+ * even when the consumer's bindable is a non-proxied array.
+ */
+export declare function createMultiSelection<T>(getValues: () => readonly T[], setValues: (next: T[]) => void): {
+    readonly values: readonly T[];
+    toggle: (item: T) => void;
+    isSelected: (candidate: T) => boolean;
+};
+/**
+ * Returns the tabindex value for a child given whether it's the currently
+ * active item in a roving-tabindex group. Active item is in the tab order
+ * (`0`); all others are reachable only via arrow keys (`-1`).
+ */
+export declare function rovingTabIndex(isActive: boolean): 0 | -1;

package/dist/_internal/constraints.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Constraints DSL — types, authoring helper, and reference evaluator.
+ *
+ * Components with discriminated-union or cross-prop rules that JSON Schema
+ * cannot cleanly represent author a `{name}.constraints.ts` sidecar calling
+ * `defineConstraints`. The generator serializes it to `{name}.constraints.json`.
+ * The evaluator (`evaluateConstraints`) is the reference implementation agents
+ * and tooling use to verify attribute sets against the rules.
+ *
+ * Four combinators: `exactlyOne | anyOf | allOf | requires`.
+ * Four predicate types: `{prop,equals}`, `{prop,exists}`, `{prop,nonEmpty}`, `{snippet}`.
+ */
+/** Severity level attached to a constraint rule violation. */
+export type ConstraintSeverity = 'error' | 'warning' | 'info';
+/**
+ * A single predicate evaluated against a `ComponentAttributes` map.
+ *
+ * - `{prop, equals}` — strict equality against the named attribute value.
+ * - `{prop, exists}` — attribute key is present (any value, including null/false/'').
+ * - `{prop, nonEmpty}` — attribute key exists and its value is not undefined, null, '',
+ *   or an empty array.
+ * - `{snippet}` — presence check for a named snippet; treated identically to
+ *   `{prop, nonEmpty}` against the snippet name.
+ * - `{allOf}` / `{anyOf}` — logical composition of child predicates.
+ */
+export type Predicate = {
+    prop: string;
+    equals: string | number | boolean;
+} | {
+    prop: string;
+    exists: true;
+} | {
+    prop: string;
+    nonEmpty: true;
+} | {
+    snippet: string;
+} | {
+    allOf: Predicate[];
+} | {
+    anyOf: Predicate[];
+};
+/**
+ * Rule combinator — determines how the `of: Predicate[]` list is evaluated.
+ *
+ * - `exactlyOne`: exactly one predicate must match; zero or 2+ → violation.
+ * - `anyOf`: at least one predicate must match; zero matches → violation.
+ * - `allOf`: all predicates must match; any non-match → violation.
+ * - `requires`: `of` has exactly one entry; that predicate must match. Used for
+ *   "if `when` then require X" rules where `anyOf` reads oddly with one entry.
+ */
+export type Combinator = 'exactlyOne' | 'anyOf' | 'allOf' | 'requires';
+/**
+ * A single constraint rule with an identifier, severity, human description,
+ * combinator kind, an optional `when` guard, and a list of predicates.
+ */
+export type ConstraintRule = {
+    id: string;
+    severity: ConstraintSeverity;
+    description: string;
+    kind: Combinator;
+    /** Rule only fires when this predicate matches; absent means always fires. */
+    when?: Predicate;
+    of: Predicate[];
+};
+/** A usage example that illustrates a rule (or its absence). */
+export type ConstraintExample = {
+    title: string;
+    code: string;
+    /** Rule id this invalid example demonstrates. Present only on invalid examples. */
+    violates?: string;
+};
+/**
+ * The top-level document authored per-component in `{name}.constraints.ts`
+ * and serialized to `{name}.constraints.json` by the generator.
+ */
+export type ConstraintsDocument = {
+    /** Kebab-case component id matching the directory name. */
+    component: string;
+    /** One-paragraph summary of what these constraints enforce. */
+    summary: string;
+    rules: ConstraintRule[];
+    examples?: {
+        valid?: ConstraintExample[];
+        invalid?: ConstraintExample[];
+    };
+};
+/**
+ * Attribute map presented to the evaluator. Keys are prop names or snippet
+ * names; values are the actual attribute values (or a boolean presence marker
+ * for snippets). Missing keys mean the prop was not supplied.
+ */
+export type ComponentAttributes = Record<string, unknown>;
+/** A single violation returned by `evaluateConstraints`. */
+export type EvaluationViolation = {
+    /** The rule id that was violated. */
+    rule: string;
+    severity: ConstraintSeverity;
+    message: string;
+};
+/**
+ * Identity helper for authoring constraint documents. Returns the argument
+ * unchanged; its value is the type inference and editor autocomplete.
+ *
+ * @example
+ * export default defineConstraints({
+ *   component: 'button',
+ *   summary: '...',
+ *   rules: [...],
+ * });
+ */
+export declare function defineConstraints(document: ConstraintsDocument): ConstraintsDocument;
+/**
+ * Evaluate a single predicate against the supplied attribute map.
+ *
+ * Predicate semantics:
+ * - `{prop, equals}` — `attributes[prop] === equals`. Missing key → undefined → not equal.
+ * - `{prop, exists}` — key is present in the map (including null, false, '').
+ * - `{prop, nonEmpty}` — key exists AND value is not undefined, null, '', or [].
+ * - `{snippet}` — non-empty presence check against the snippet name key.
+ * - `{allOf}` — all child predicates match.
+ * - `{anyOf}` — at least one child predicate matches.
+ */
+export declare function evaluatePredicate(predicate: Predicate, attributes: ComponentAttributes): boolean;
+/**
+ * Evaluate a rule's `when` guard. Returns `true` when the rule should fire
+ * (i.e. the guard matches, or no guard was supplied).
+ */
+export declare function whenMatches(when: Predicate | undefined, attributes: ComponentAttributes): boolean;
+/**
+ * Run all rules in a `ConstraintsDocument` against the given attribute map.
+ * Returns the list of violations; an empty array means the attributes are valid.
+ *
+ * Violation message format: `"<rule.description> (rule: <rule.id>)"`.
+ */
+export declare function evaluateConstraints(document: ConstraintsDocument, attributes: ComponentAttributes): EvaluationViolation[];

package/dist/_internal/data-list-context.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Internal DataList context, factored out of `data-list.svelte` so that
+ * `stacked-list-item.svelte` (the recommended DataList row) can read the
+ * list-level density without importing the `.svelte` module path.
+ *
+ * DataList publishes a list-level `density` so a consumer can set the density
+ * once on the list rather than on every row. `StackedListItem` reads this
+ * context and falls back to its own `density` prop, which in turn defaults to
+ * `comfortable` — so a standalone `StackedListItem` (no DataList ancestor) is
+ * unaffected, and a per-row `density` prop always overrides the list default.
+ *
+ * The context value is intentionally minimal (density only). Additional
+ * list-level fields require a separate API review before being added.
+ */
+import type { StackedListItemDensity } from '../components/stacked-list-item/stacked-list-item.types.ts';
+/**
+ * Context published by `<DataList>` for descendant rows. `density` is a getter
+ * property so reads stay reactive — reading `context.density` inside a
+ * `$derived` flows through the getter. Destructuring breaks reactivity.
+ */
+export type DataListContextValue = {
+    /** The list-level density, or `undefined` when the list set none. */
+    readonly density: StackedListItemDensity | undefined;
+};
+/** Publish the DataList context for descendant rows. */
+export declare function setDataListContext(context: DataListContextValue): void;
+/**
+ * Read the nearest enclosing `<DataList>` context. Returns `undefined` when no
+ * `<DataList>` ancestor exists (a standalone `StackedListItem` in a
+ * consumer-owned list is a supported, first-class state).
+ */
+export declare const getDataListContext: () => DataListContextValue | undefined;

package/dist/_internal/field-control.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Internal field-control contract shared by form-control components.
+ *
+ * Components that wrap a native form element (`<input>`, `<select>`,
+ * `<textarea>`, custom-roled buttons that participate in form submission) all
+ * need the same wiring:
+ *
+ * - A stable `id` for label association
+ * - Derived IDs for description and error elements
+ * - A combined `aria-describedby` that lists both when present
+ * - `aria-invalid` set when an error message is supplied
+ *
+ * This module centralizes that boilerplate so:
+ *
+ * - All field controls produce identical ARIA wiring (audited once, here, not
+ *   per-component).
+ * - Phase 1's Checkbox and Radio components reuse the same shape without
+ *   reimplementing the description/error/`aria-describedby` triad.
+ *
+ * The helpers are pure functions that take string inputs and return strings
+ * or undefined — they have no Svelte runtime dependency, so they remain
+ * simple to test and to consume from any component shape (Shape A, B, or C
+ * per the project conventions).
+ */
+/**
+ * Build the description element's id for a given field id.
+ * Returns `undefined` when there is no description, so it can be passed
+ * directly to Svelte attribute bindings (which omit the attribute when undefined).
+ */
+export declare function describeId(fieldId: string, hasDescription: boolean): string | undefined;
+/**
+ * Build the error element's id for a given field id.
+ * Returns `undefined` when there is no error.
+ */
+export declare function errorId(fieldId: string, hasError: boolean): string | undefined;
+/**
+ * Compose the `aria-describedby` value for a field. Filters out undefined ids,
+ * joins the remainder with a single space, and returns `undefined` when no ids
+ * are present so the attribute can be omitted entirely from the rendered element.
+ *
+ * Accepts arbitrary additional ids so consumers can layer in extra references
+ * (e.g. a tooltip id, a counter id) without re-implementing the join logic.
+ */
+export declare function composeDescribedBy(...ids: Array<string | undefined | null>): string | undefined;
+/**
+ * Convert the truthiness of an error to the value `aria-invalid` expects.
+ * Returns `'true'` when `hasError` is true, `undefined` otherwise (so the
+ * attribute is omitted when there's no error).
+ */
+export declare function ariaInvalid(hasError: boolean): 'true' | undefined;
+export type FieldControlContextLike = {
+    readonly controlId: string;
+    readonly descriptionId: string | undefined;
+    readonly errorId: string | undefined;
+    readonly describedBy: string | undefined;
+    readonly invalid: 'true' | undefined;
+    readonly required: boolean;
+    readonly disabled: boolean;
+};
+export type ResolveFieldControlInput = {
+    id?: string;
+    generatedId: string;
+    context?: FieldControlContextLike | undefined;
+    localIdNamespace?: string | undefined;
+    hasDescription?: boolean;
+    hasError?: boolean;
+    consumerDescribedBy?: string | null | undefined;
+    additionalDescribedBy?: Array<string | undefined | null> | undefined;
+    consumerInvalid?: 'true' | 'false' | 'grammar' | 'spelling' | boolean | null | undefined;
+    required?: boolean | undefined;
+    disabled?: boolean | undefined;
+};
+export type ResolvedFieldControl = {
+    id: string;
+    ownDescriptionId: string | undefined;
+    ownErrorId: string | undefined;
+    descriptionId: string | undefined;
+    errorId: string | undefined;
+    describedBy: string | undefined;
+    ariaInvalid: 'true' | 'false' | 'grammar' | 'spelling' | undefined;
+    required: boolean;
+    disabled: boolean;
+};
+export declare function resolveFieldControl(input: ResolveFieldControlInput): ResolvedFieldControl;

package/dist/_internal/form-field-context.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Context published by `<FormField>` for descendant controls. Controls read this
+ * to wire identity and ARIA. All members are getter properties on the object so
+ * reads stay reactive — when a consumer reads `context.describedBy` inside a
+ * `$derived`, the read flows through the getter, which returns a value recomputed
+ * from FormField's `$derived` internals. Destructuring breaks reactivity; getter
+ * reads preserve it.
+ */
+export type FormFieldContext = {
+    /** Stable id for the underlying control element. Source of `<label for>`. */
+    readonly controlId: string;
+    /** Id of the `<label>` element. Used by `aria-labelledby` for grouped controls. */
+    readonly labelId: string;
+    /** Composed `aria-describedby` value (description + error), or undefined. */
+    readonly describedBy: string | undefined;
+    /** Id of the description `<p>`, or undefined. */
+    readonly descriptionId: string | undefined;
+    /** Id of the error `<p>`, or undefined. */
+    readonly errorId: string | undefined;
+    /** `'true'` when the field is in an error state, else undefined. */
+    readonly invalid: 'true' | undefined;
+    /** True when `required` prop is set on FormField. */
+    readonly required: boolean;
+    /** True when `disabled` prop is set on FormField. */
+    readonly disabled: boolean;
+};
+export declare function setFormFieldContext(context: FormFieldContext): void;
+/**
+ * Read the nearest enclosing `<FormField>` context, or `undefined` when no
+ * `<FormField>` ancestor exists. Controls rely on the `undefined` contract to
+ * fall back to their standalone behavior.
+ *
+ * Svelte 5's `createContext` getter throws when no provider exists;
+ * `optionalContext` converts that throw to `undefined` so the consumer
+ * contract is preserved.
+ */
+export declare const getFormFieldContext: () => FormFieldContext | undefined;

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

@@ -0,0 +1,27 @@
+/**
+ * Shared helper for contexts that treat a missing provider as a valid state.
+ *
+ * Svelte 5's `createContext` returns a strict `[get, set]` pair whose `get`
+ * THROWS when no ancestor has called `set`. That contract is exactly right for
+ * required contexts (a `CommandItem` outside a command list is a programmer
+ * error), but several cinder components legitimately support running with no
+ * parent provider — a standalone `<Input>` with no `<FormField>` ancestor, a
+ * `<SideNavigationItem>` in a flat sidebar with no group, and so on. Those
+ * readers want `undefined` on no provider, not a throw.
+ *
+ * Before this helper, each such reader hand-rolled the same
+ * `try { return getStrict() } catch { return undefined }` block. This factors
+ * the throw→undefined conversion into ONE place so the contract is named,
+ * documented, and not re-derived at every call site.
+ */
+/**
+ * Wrap a strict context getter (from `createContext`) so it returns `undefined`
+ * when no provider exists instead of throwing. Use this for contexts where a
+ * missing parent provider is a supported, first-class state.
+ *
+ * @param getStrict The strict getter returned by `createContext` (throws when
+ *   no ancestor called `set`).
+ * @returns A getter that yields the context value, or `undefined` when no
+ *   provider is mounted.
+ */
+export declare function optionalContext<T>(getStrict: () => T): () => T | undefined;