@lostgradient/cinder 0.2.0 → 0.4.0

package/src/components/hover-card/README.md

@@ -28,17 +28,17 @@ Hover-and-focus triggered rich preview card for non-interactive contextual conte
 
 | Prop           | Type                                                                                                                                                                                       | Required | Default | Description                                                                                                                |
 | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `class`        | `string`                                                                                                                                                                                   | no       | —       |                                                                                                                            |
-| `closeDelay`   | `number`                                                                                                                                                                                   | no       | —       |                                                                                                                            |
-| `description`  | `string`                                                                                                                                                                                   | no       | —       |                                                                                                                            |
-| `offset`       | `number`                                                                                                                                                                                   | no       | —       |                                                                                                                            |
-| `open`         | `boolean`                                                                                                                                                                                  | no       | —       |                                                                                                                            |
-| `openDelay`    | `number`                                                                                                                                                                                   | no       | —       |                                                                                                                            |
-| `placement`    | `"top"` \| `"top-start"` \| `"top-end"` \| `"right"` \| `"right-start"` \| `"right-end"` \| `"bottom"` \| `"bottom-start"` \| `"bottom-end"` \| `"left"` \| `"left-start"` \| `"left-end"` | no       | —       |                                                                                                                            |
-| `showArrow`    | `boolean`                                                                                                                                                                                  | no       | —       |                                                                                                                            |
-| `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`        | `string`                                                                                                                                                                                   | no       | —       | Additional class names merged with the component's root class.                                                             |
+| `closeDelay`   | `number`                                                                                                                                                                                   | no       | —       | Delay in milliseconds before the card closes after the pointer leaves and focus departs. Default `150`.                    |
+| `description`  | `string`                                                                                                                                                                                   | no       | —       | Visually hidden text wired to the trigger via aria-describedby for assistive technology context.                           |
+| `offset`       | `number`                                                                                                                                                                                   | no       | —       | Distance in pixels between the trigger and the card. Default `8`.                                                          |
+| `open`         | `boolean`                                                                                                                                                                                  | no       | —       | Controls the open state of the card; bindable for controlled usage.                                                        |
+| `openDelay`    | `number`                                                                                                                                                                                   | no       | —       | Delay in milliseconds before the card opens after the pointer enters or focus lands on the trigger. Default `300`.         |
+| `placement`    | `"top"` \| `"top-start"` \| `"top-end"` \| `"right"` \| `"right-start"` \| `"right-end"` \| `"bottom"` \| `"bottom-start"` \| `"bottom-end"` \| `"left"` \| `"left-start"` \| `"left-end"` | no       | —       | Preferred placement of the card relative to the trigger. Default `bottom-start`.                                           |
+| `showArrow`    | `boolean`                                                                                                                                                                                  | no       | —       | When true, renders a directional arrow pointing from the card toward the trigger. Default `false`.                         |
+| `children`     | `(opaque)`                                                                                                                                                                                 | yes      | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
 | `onopenchange` | `(opaque)`                                                                                                                                                                                 | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `trigger`      | `(opaque)`                                                                                                                                                                                 | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
+| `trigger`      | `(opaque)`                                                                                                                                                                                 | yes      | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
 | `triggerRef`   | `(opaque)`                                                                                                                                                                                 | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                    |
 
 <!-- generated:props:end -->

package/src/components/hover-card/hover-card.types.ts

@@ -15,16 +15,24 @@ export type HoverCardPlacement =
   | 'left-end';
 
 export type HoverCardProps = {
+  /** Controls the open state of the card; bindable for controlled usage. */
   open?: boolean;
   onopenchange?: (open: boolean) => void;
+  /** Delay in milliseconds before the card opens after the pointer enters or focus lands on the trigger. Default `300`. */
   openDelay?: number;
+  /** Delay in milliseconds before the card closes after the pointer leaves and focus departs. Default `150`. */
   closeDelay?: number;
+  /** Preferred placement of the card relative to the trigger. Default `bottom-start`. */
   placement?: HoverCardPlacement;
+  /** Distance in pixels between the trigger and the card. Default `8`. */
   offset?: number;
+  /** When true, renders a directional arrow pointing from the card toward the trigger. Default `false`. */
   showArrow?: boolean;
   trigger: Snippet;
   children: Snippet;
   triggerRef?: HTMLElement | null;
+  /** Visually hidden text wired to the trigger via aria-describedby for assistive technology context. */
   description?: string;
+  /** Additional class names merged with the component's root class. */
   class?: string;
 };

package/src/components/image/README.md

@@ -26,10 +26,10 @@ Responsive image wrapper with aspect-ratio preservation, lazy loading, and fallb
 | `ratio`       | `string`                          | no       | —       | CSS aspect-ratio applied to the wrapper (e.g. `'16 / 9'`) so layout is stable while the image loads.                                                           |
 | `src`         | `string`                          | yes      | —       | Image source URL.                                                                                                                                              |
 | `width`       | `number`                          | no       | —       | Native pixel width.                                                                                                                                            |
-| `class`       | `(opaque)`                        | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                                                        |
-| `fallback`    | `(opaque)`                        | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                     |
-| `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.                                     |
-| `onload`      | `(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       | —       | Additional class names merged with `.cinder-image`. Not expressible in JSON Schema; see the component types for the signature.                                 |
+| `fallback`    | `(opaque)`                        | no       | —       | Rendered in place of the `<img>` when it fails to load. Not expressible in JSON Schema; see the component types for the signature.                             |
+| `onerror`     | `(opaque)`                        | no       | —       | Forwarded after internal state updates. Not expressible in JSON Schema; see the component types for the signature.                                             |
+| `onload`      | `(opaque)`                        | no       | —       | Forwarded after internal state updates. Not expressible in JSON Schema; see the component types for the signature.                                             |
 
 <!-- generated:props:end -->
 

package/src/components/image/image.examples.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "image",
+  "import": "@lostgradient/cinder/image",
+  "examples": [
+    {
+      "id": "basic",
+      "title": "Basic image",
+      "description": "Responsive image with lazy loading and an explicit aspect ratio.",
+      "code": "<script lang=\"ts\">\n  import { Image } from '@lostgradient/cinder/image';\n</script>\n\n<Image\n  src=\"https://picsum.photos/seed/cinder/600/338\"\n  alt=\"A randomly selected placeholder photograph\"\n  ratio=\"16/9\"\n  width={600}\n  height={338}\n/>\n"
+    }
+  ]
+}

package/src/components/input/README.md

@@ -16,21 +16,22 @@ Single-line text input with support for labels, addons, validation states, and h
 
 <!-- generated:props:start -->
 
-| Prop                  | Type                                                                                                | Required | Default | Description                                                                                                                |
-| --------------------- | --------------------------------------------------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `description`         | `string`                                                                                            | no       | —       |                                                                                                                            |
-| `disabled`            | `boolean`                                                                                           | no       | —       |                                                                                                                            |
-| `error`               | `string`                                                                                            | no       | —       |                                                                                                                            |
-| `id`                  | `string`                                                                                            | yes      | —       |                                                                                                                            |
-| `label`               | `string`                                                                                            | no       | —       |                                                                                                                            |
-| `leadingInteractive`  | `boolean`                                                                                           | no       | —       |                                                                                                                            |
-| `required`            | `boolean`                                                                                           | no       | —       |                                                                                                                            |
-| `trailingInteractive` | `boolean`                                                                                           | no       | —       |                                                                                                                            |
-| `type`                | `"number"` \| `"date"` \| `"email"` \| `"password"` \| `"search"` \| `"tel"` \| `"text"` \| `"url"` | no       | —       |                                                                                                                            |
-| `class`               | `(opaque)`                                                                                          | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                    |
-| `leading`             | `(opaque)`                                                                                          | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `trailing`            | `(opaque)`                                                                                          | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `value`               | `(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                                                                                                                                                                             |
+| --------------------- | --------------------------------------------------------------------------------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `description`         | `string`                                                                                            | no       | —       | Helper text rendered below the input and associated via `aria-describedby`.                                                                                                             |
+| `disabled`            | `boolean`                                                                                           | no       | —       | When true, disables the input, matching the native `disabled` attribute.                                                                                                                |
+| `error`               | `string`                                                                                            | no       | —       | Error message rendered below the input; also sets `aria-invalid` on the input.                                                                                                          |
+| `id`                  | `string`                                                                                            | yes      | —       | HTML `id` for the underlying input, used to associate the `<label>` and ARIA attributes. Required.                                                                                      |
+| `label`               | `string`                                                                                            | no       | —       | Visible label text rendered above the input and linked via `for`/`id`.                                                                                                                  |
+| `leadingInteractive`  | `boolean`                                                                                           | no       | —       | When true, the leading adornment is interactive and included in the accessibility tree. Default `false`.                                                                                |
+| `required`            | `boolean`                                                                                           | no       | —       | Marks the input as required for form validation, matching the native `required` attribute.                                                                                              |
+| `trailingInteractive` | `boolean`                                                                                           | no       | —       | When true, the trailing adornment is interactive and included in the accessibility tree. Default `false`.                                                                               |
+| `type`                | `"number"` \| `"date"` \| `"email"` \| `"password"` \| `"search"` \| `"tel"` \| `"text"` \| `"url"` | no       | —       | Input type controlling the browser's built-in validation and keyboard. Default `"text"`.                                                                                                |
+| `class`               | `(opaque)`                                                                                          | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                 |
+| `leading`             | `(opaque)`                                                                                          | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                              |
+| `onValueChange`       | `(opaque)`                                                                                          | no       | —       | Intercept a proposed value before the bindable value is written. Return a replacement value to transform it. Not expressible in JSON Schema; see the component types for the signature. |
+| `trailing`            | `(opaque)`                                                                                          | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                              |
+| `value`               | `(opaque)`                                                                                          | yes      | —       | Bindable current text value of the input. Not expressible in JSON Schema; see the component types for the signature.                                                                    |
 
 <!-- generated:props:end -->
 

package/src/components/input/input.examples.json

@@ -7,13 +7,13 @@
       "id": "basic",
       "title": "Basic input",
       "description": "Text input with label and bound value.",
-      "code": "<script lang=\"ts\">\n  import { Input } from '@lostgradient/cinder/input';\n  let name = $state('');\n</script>\n\n<Input id=\"name\" bind:value={name} label=\"Full name\" placeholder=\"Jane Smith\" />\n{#if name}\n  <p style=\"margin-top: 0.5rem; color: var(--cinder-text-muted);\">Hello, {name}!</p>\n{/if}\n"
+      "code": "<script lang=\"ts\">\n  import { Input } from '@lostgradient/cinder/input';\n\n  let name = $state('');\n</script>\n\n<Input id=\"field\" bind:value={name} label=\"Full name\" placeholder=\"Jane Smith\" />\n{#if name}\n  <p style=\"margin-top: 0.5rem; color: var(--cinder-text-muted);\">Hello, {name}!</p>\n{/if}\n"
     },
     {
       "id": "sign-in",
       "title": "Sign-in composition",
       "description": "Composition of FormField + Input + Button with a top-of-form Alert auth-error region. Demonstrates the required autocomplete values and the assertive announcement pattern via role=\"alert\".",
-      "code": "<script lang=\"ts\">\n  import { Alert } from '@lostgradient/cinder/alert';\n  import { Button } from '@lostgradient/cinder/button';\n  import { FormField } from '@lostgradient/cinder/form-field';\n  import { Input } from '@lostgradient/cinder/input';\n  let email = $state('');\n  let password = $state('');\n  let authError = $state<string | undefined>(undefined);\n  let submitting = $state(false);\n\n  function handleSignIn() {\n    if (submitting) return;\n    // Clear any prior error so a re-submit re-announces by re-mounting the Alert\n    // rather than mutating its text (assistive tech announces on mount of role=\"alert\").\n    authError = undefined;\n    submitting = true;\n\n    // Static example: simulate an auth failure. A real implementation would\n    // POST { email, password } and redirect on success.\n    setTimeout(() => {\n      authError = 'Email or password is incorrect.';\n      submitting = false;\n    }, 600);\n  }\n</script>\n\n<form\n  novalidate\n  aria-labelledby=\"sign-in-heading\"\n  style=\"display: flex; flex-direction: column; gap: 1rem;\"\n  onsubmit={(event) => {\n    event.preventDefault();\n    handleSignIn();\n  }}\n>\n  <h2 id=\"sign-in-heading\">Sign in</h2>\n\n  <!--\n    Top-of-form auth-error region.\n    Alert's role=\"alert\" implies aria-live=\"assertive\" and aria-atomic=\"true\".\n    We intentionally do NOT add an explicit aria-live attribute (see alert.test.ts:\n    \"has role=alert on root element and does not set an explicit aria-live\").\n    Mounting the Alert in response to submit triggers the assertive announcement.\n  -->\n  {#if authError}\n    <Alert variant=\"error\">\n      {authError}\n    </Alert>\n  {/if}\n\n  <FormField id=\"sign-in-email\" label=\"Email\" required>\n    <!-- autocomplete=\"email\" — the identifier is an email address.\n         Use \"username\" instead when the field collects an opaque handle. -->\n    <Input\n      id=\"sign-in-email\"\n      type=\"email\"\n      bind:value={email}\n      autocomplete=\"email\"\n      required\n      placeholder=\"you@example.com\"\n    />\n  </FormField>\n\n  <FormField id=\"sign-in-password\" label=\"Password\" required>\n    <!-- autocomplete=\"current-password\" — required for password managers to\n         recognize this as a sign-in form and offer saved credentials. -->\n    <Input\n      id=\"sign-in-password\"\n      type=\"password\"\n      bind:value={password}\n      autocomplete=\"current-password\"\n      required\n    />\n  </FormField>\n\n  <Button type=\"submit\" variant=\"primary\" loading={submitting}>\n    {submitting ? 'Signing in…' : 'Sign in'}\n  </Button>\n</form>\n"
+      "code": "<script lang=\"ts\">\n  import { Alert } from '@lostgradient/cinder/alert';\n  import { Button } from '@lostgradient/cinder/button';\n  import { FormField } from '@lostgradient/cinder/form-field';\n  import { Input } from '@lostgradient/cinder/input';\n  let email = $state('');\n  let password = $state('');\n  let authError = $state<string | undefined>(undefined);\n  let submitting = $state(false);\n\n  function handleSignIn() {\n    if (submitting) return;\n    // Clear any prior error so a re-submit re-announces by re-mounting the Alert\n    // rather than mutating its text (assistive tech announces on mount of role=\"alert\").\n    authError = undefined;\n    submitting = true;\n\n    // Static example: simulate an auth failure. A real implementation would\n    // POST { email, password } and redirect on success.\n    setTimeout(() => {\n      authError = 'Email or password is incorrect.';\n      submitting = false;\n    }, 600);\n  }\n</script>\n\n<form\n  novalidate\n  aria-labelledby=\"sign-in-heading\"\n  style=\"display: flex; flex-direction: column; gap: 1rem;\"\n  onsubmit={(event) => {\n    event.preventDefault();\n    handleSignIn();\n  }}\n>\n  <h2 id=\"sign-in-heading\">Sign in</h2>\n\n  <!--\n    Top-of-form auth-error region.\n    Alert's role=\"alert\" implies aria-live=\"assertive\" and aria-atomic=\"true\".\n    We intentionally do NOT add an explicit aria-live attribute (see alert.test.ts:\n    \"has role=alert on root element and does not set an explicit aria-live\").\n    Mounting the Alert in response to submit triggers the assertive announcement.\n  -->\n  {#if authError}\n    <Alert variant=\"danger\">\n      {authError}\n    </Alert>\n  {/if}\n\n  <FormField id=\"sign-in-email\" label=\"Email\" required>\n    <!-- autocomplete=\"email\" — the identifier is an email address.\n         Use \"username\" instead when the field collects an opaque handle. -->\n    <Input\n      id=\"sign-in-email\"\n      type=\"email\"\n      bind:value={email}\n      autocomplete=\"email\"\n      required\n      placeholder=\"you@example.com\"\n    />\n  </FormField>\n\n  <FormField id=\"sign-in-password\" label=\"Password\" required>\n    <!-- autocomplete=\"current-password\" — required for password managers to\n         recognize this as a sign-in form and offer saved credentials. -->\n    <Input\n      id=\"sign-in-password\"\n      type=\"password\"\n      bind:value={password}\n      autocomplete=\"current-password\"\n      required\n    />\n  </FormField>\n\n  <Button type=\"submit\" variant=\"primary\" loading={submitting}>\n    {submitting ? 'Signing in…' : 'Sign in'}\n  </Button>\n</form>\n"
     },
     {
       "id": "types",

package/src/components/input/input.svelte

@@ -18,19 +18,16 @@
 <script lang="ts">
   import type { InputProps } from './input.types.ts';
 
-  import {
-    ariaInvalid,
-    composeDescribedBy,
-    describeId,
-    errorId as buildErrorId,
-  } from '../../_internal/field-control.ts';
+  import { resolveFieldControl } from '../../_internal/field-control.ts';
   import { getFormFieldContext } from '../../_internal/form-field-context.ts';
   import { classNames } from '../../utilities/class-names.ts';
   import { devWarn } from '../../utilities/dev-warn.ts';
+  import { commitValue } from '../../utilities/value-change.ts';
 
   let {
     id,
     value = $bindable(''),
+    onValueChange,
     label,
     description,
     error,
@@ -43,6 +40,8 @@
     leadingInteractive = false,
     trailingInteractive = false,
     'aria-describedby': consumerDescribedBy,
+    'aria-invalid': consumerInvalid,
+    oninput: consumerOninput,
     ...rest
   }: InputProps = $props();
 
@@ -56,32 +55,65 @@
     }
   });
 
-  const defaultDescriptionId = $derived(describeId(id, !!description));
-  const defaultErrorId = $derived(buildErrorId(id, !!error));
-  const ownDescriptionId = $derived(
-    description && defaultDescriptionId === context?.descriptionId
-      ? `${id}-input-description`
-      : defaultDescriptionId,
+  const field = $derived(
+    resolveFieldControl({
+      id,
+      generatedId: id,
+      context,
+      hasDescription: !!description,
+      hasError: !!error,
+      localIdNamespace: 'input',
+      consumerDescribedBy,
+      consumerInvalid,
+      required,
+      disabled,
+    }),
   );
-  const ownErrorId = $derived(
-    error && defaultErrorId === context?.errorId ? `${id}-input-error` : defaultErrorId,
-  );
-  const resolvedDescriptionId = $derived(ownDescriptionId ?? context?.descriptionId);
-  const resolvedErrorId = $derived(ownErrorId ?? context?.errorId);
-  const describedBy = $derived(
-    composeDescribedBy(resolvedDescriptionId, resolvedErrorId, consumerDescribedBy),
-  );
-  const resolvedAriaInvalid = $derived(
-    error ? ariaInvalid(true) : (context?.invalid ?? rest['aria-invalid'] ?? ariaInvalid(false)),
-  );
-  const resolvedRequired = $derived(required ?? context?.required ?? false);
-  const resolvedDisabled = $derived(disabled ?? context?.disabled ?? false);
+  const ownDescriptionId = $derived(field.ownDescriptionId);
+  const ownErrorId = $derived(field.ownErrorId);
+  const describedBy = $derived(field.describedBy);
+  const resolvedAriaInvalid = $derived(field.ariaInvalid);
+  const resolvedRequired = $derived(field.required);
+  const resolvedDisabled = $derived(field.disabled);
 
   const isNativeDateInput = $derived(type === 'date');
   const rendersNativeDateIcon = $derived(isNativeDateInput && !trailing);
   const hasTrailing = $derived(!!trailing || isNativeDateInput);
   const hasGroupWrapper = $derived(!!leading || hasTrailing);
-  const isInvalid = $derived(resolvedAriaInvalid === 'true' || resolvedAriaInvalid === true);
+  const isInvalid = $derived(resolvedAriaInvalid === 'true');
+  let inputNode: HTMLInputElement | undefined = $state();
+  let resetSyncTimeout: ReturnType<typeof setTimeout> | undefined;
+
+  function syncValueAfterFormReset(): void {
+    if (resetSyncTimeout !== undefined) clearTimeout(resetSyncTimeout);
+    resetSyncTimeout = setTimeout(() => {
+      resetSyncTimeout = undefined;
+      if (inputNode) value = inputNode.value;
+    }, 0);
+  }
+
+  $effect(() => {
+    const form = inputNode?.form;
+    if (!form) return;
+
+    form.addEventListener('reset', syncValueAfterFormReset);
+    return () => {
+      form.removeEventListener('reset', syncValueAfterFormReset);
+      if (resetSyncTimeout !== undefined) {
+        clearTimeout(resetSyncTimeout);
+        resetSyncTimeout = undefined;
+      }
+    };
+  });
+
+  function handleInput(event: Event): void {
+    const target = event.currentTarget as HTMLInputElement;
+    const committed = commitValue(target.value, onValueChange, (next) => {
+      value = next;
+    });
+    target.value = committed;
+    consumerOninput?.(event as Parameters<NonNullable<InputProps['oninput']>>[0]);
+  }
 </script>
 
 {#snippet calendarIcon()}
@@ -106,16 +138,18 @@
 
 {#snippet inputElement()}
   <input
+    bind:this={inputNode}
     {id}
     {type}
+    {...rest}
     disabled={resolvedDisabled}
     required={resolvedRequired}
-    bind:value
+    {value}
+    oninput={handleInput}
     class={classNames('cinder-input', className)}
     data-cinder-native-date={rendersNativeDateIcon ? '' : undefined}
     aria-invalid={resolvedAriaInvalid}
     aria-describedby={describedBy}
-    {...rest}
   />
 {/snippet}
 
@@ -123,6 +157,9 @@
   {#if label}
     <label for={id} class="cinder-input-field__label" data-disabled={resolvedDisabled || undefined}>
       {label}
+      {#if resolvedRequired}
+        <span class="cinder-_required-marker" aria-hidden="true">*</span>
+      {/if}
     </label>
   {/if}
 

package/src/components/input/input.types.ts

@@ -15,6 +15,7 @@ type InputAddonProps =
   | { leading?: never; leadingInteractive?: never; trailing?: never; trailingInteractive?: never }
   | {
       leading: Snippet;
+      /** When true, the leading adornment is interactive and included in the accessibility tree. Default `false`. */
       leadingInteractive?: boolean;
       trailing?: never;
       trailingInteractive?: never;
@@ -23,24 +24,37 @@ type InputAddonProps =
       leading?: never;
       leadingInteractive?: never;
       trailing: Snippet;
+      /** When true, the trailing adornment is interactive and included in the accessibility tree. Default `false`. */
       trailingInteractive?: boolean;
     }
   | {
       leading: Snippet;
+      /** When true, the leading adornment is interactive and included in the accessibility tree. Default `false`. */
       leadingInteractive?: boolean;
       trailing: Snippet;
+      /** When true, the trailing adornment is interactive and included in the accessibility tree. Default `false`. */
       trailingInteractive?: boolean;
     };
 
 export type InputProps = HTMLInputAttributes &
   InputAddonProps & {
+    /** HTML `id` for the underlying input, used to associate the `<label>` and ARIA attributes. Required. */
     id: string;
+    /** Bindable current text value of the input. */
     value: string;
+    /** Intercept a proposed value before the bindable value is written. Return a replacement value to transform it. */
+    onValueChange?: (next: string) => string | void;
+    /** Visible label text rendered above the input and linked via `for`/`id`. */
     label?: string;
+    /** Helper text rendered below the input and associated via `aria-describedby`. */
     description?: string;
+    /** Error message rendered below the input; also sets `aria-invalid` on the input. */
     error?: string;
+    /** When true, disables the input, matching the native `disabled` attribute. */
     disabled?: boolean;
+    /** Marks the input as required for form validation, matching the native `required` attribute. */
     required?: boolean;
+    /** Input type controlling the browser's built-in validation and keyboard. Default `"text"`. */
     type?: InputType;
     class?: string;
   };

package/src/components/invocation-rule-builder/README.md

@@ -0,0 +1,128 @@
+# InvocationRuleBuilder
+
+A presentation component for building and reviewing conditional automation rules. Each rule is composed of one or more conditions (field / operator / value) and one or more actions (a target agent or service). Cinder renders the UI and reports every edit through a callback — it owns no rule execution, persistence, or validation semantics.
+
+## Ownership boundary
+
+Cinder does not execute, validate, or persist rules. The consumer provides the complete rule model through the `rules` prop and handles every change emitted by `onchange`. Cinder is responsible only for rendering the controls with correct accessible names and emitting pure (non-mutating) change descriptors.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { InvocationRuleBuilder } from '@lostgradient/cinder/invocation-rule-builder';
+  import type {
+    InvocationRule,
+    InvocationRuleChange,
+    InvocationRuleOption,
+  } from '@lostgradient/cinder/invocation-rule-builder';
+
+  let rules = $state<InvocationRule[]>([]);
+
+  const fieldOptions: InvocationRuleOption[] = [
+    { value: 'path', label: 'Path' },
+    { value: 'label', label: 'Label' },
+    { value: 'author', label: 'Author' },
+  ];
+
+  const operatorOptions: InvocationRuleOption[] = [
+    { value: 'matches', label: 'matches' },
+    { value: 'is', label: 'is' },
+    { value: 'is-not', label: 'is not' },
+  ];
+
+  const actionOptions: InvocationRuleOption[] = [
+    { value: 'security-review', label: 'Security Review Agent' },
+    { value: 'code-review', label: 'Code Review Agent' },
+  ];
+
+  function handleChange(nextRules: InvocationRule[], change: InvocationRuleChange): void {
+    rules = nextRules;
+    // Persist or validate here — cinder does not do this for you.
+  }
+</script>
+
+<InvocationRuleBuilder
+  {rules}
+  onchange={handleChange}
+  {fieldOptions}
+  {operatorOptions}
+  {actionOptions}
+  label="PR routing rules"
+/>
+```
+
+## Data model
+
+```ts
+type InvocationRule = {
+  id: string;
+  label: string;
+  conditions: InvocationRuleCondition[];
+  actions: InvocationRuleAction[];
+};
+
+type InvocationRuleCondition = {
+  id: string;
+  field: string; // consumer-defined, e.g. "path"
+  operator: string; // consumer-defined, e.g. "matches"
+  value: string; // consumer-defined, e.g. "src/**"
+};
+
+type InvocationRuleAction = {
+  id: string;
+  target: string; // consumer-defined, e.g. "security-review"
+};
+```
+
+A rule fires when ALL of its conditions match (implicit AND). Boolean grouping, OR logic, and nested condition trees are out of scope for this component.
+
+## Modes
+
+Pass `readonly={true}` to render a read-only summary instead of editable controls. Schema-driven usage is read-only because callbacks are not representable in JSON Schema. Runtime consumers can render editable controls by passing `onchange` and leaving `readonly` false.
+
+## Props
+
+<!-- generated:props:start -->
+
+| Prop                | Type                                                                                                                                                                     | Required | Default | Description                                                                                                                                                                                                                                                                                                                                             |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `actionOptions`     | { label: `string`; value: `string` }[]                                                                                                                                   | yes      | —       | Options for the action target selector. Consumer-provided list of targets, e.g. review-agent slugs or step identifiers.                                                                                                                                                                                                                                 |
+| `addActionLabel`    | `string`                                                                                                                                                                 | no       | —       | Label for the "Add action" button. Defaults to "Add action".                                                                                                                                                                                                                                                                                            |
+| `addConditionLabel` | `string`                                                                                                                                                                 | no       | —       | Label for the "Add condition" button. Defaults to "Add condition".                                                                                                                                                                                                                                                                                      |
+| `addRuleLabel`      | `string`                                                                                                                                                                 | no       | —       | Label for the "Add rule" button. Defaults to "Add rule".                                                                                                                                                                                                                                                                                                |
+| `class`             | `string`                                                                                                                                                                 | no       | —       | Additional CSS classes applied to the root element.                                                                                                                                                                                                                                                                                                     |
+| `fieldOptions`      | { label: `string`; value: `string` }[]                                                                                                                                   | yes      | —       | Options for the condition field selector. Consumer-provided list of fields that a condition can test, e.g. "path", "label", "author".                                                                                                                                                                                                                   |
+| `label`             | `string`                                                                                                                                                                 | no       | —       | Accessible label for the entire rule builder region.                                                                                                                                                                                                                                                                                                    |
+| `operatorOptions`   | { label: `string`; value: `string` }[]                                                                                                                                   | yes      | —       | Options for the condition operator selector. Consumer-provided list of operators, e.g. "matches", "is", "is-not", "contains".                                                                                                                                                                                                                           |
+| `readonly`          | `true`                                                                                                                                                                   | yes      | —       | Must be true for schema-driven usage because editable mode requires the unsupported `onchange` callback. Runtime consumers may omit this when passing `onchange` directly.                                                                                                                                                                              |
+| `rules`             | { actions: { id: `string`; target: `string` }[]; conditions: { field: `string`; id: `string`; operator: `string`; value: `string` }[]; id: `string`; label: `string` }[] | yes      | —       | The current list of automation rules. Controlled — pass the updated list returned from `onchange` back into this prop to commit a change.                                                                                                                                                                                                               |
+| `onchange`          | `(opaque)`                                                                                                                                                               | no       | —       | Called whenever the user makes any edit. Required for editable runtime usage because editable controls must commit controlled state changes. Receives the next rule array (pure, not mutated) and a change descriptor. Consumer owns persistence, validation, and execution. 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 -->
+
+## Accessibility
+
+Each condition's field selector, operator selector, value input, and remove button carry accessible labels that identify which condition and rule they belong to (e.g. "Field for condition 2 of Rule 1"). Each action's target selector and remove button are similarly labeled. Rule reorder buttons are labeled "Move Rule 1 up" and "Move Rule 1 down". Add buttons describe their destination rule. A live region announces add, remove, and move events to screen reader users.
+
+In readonly mode all controls are replaced by visible text, so no interaction is possible and keyboard navigation follows the natural document order.
+
+Focus management on remove: when a condition or action row is removed, focus moves to the preceding row's remove button, or to the "Add condition" / "Add action" button if the removed row was the last one.
+
+The component uses semantic HTML: the root is a `section` with an `aria-label`, condition and action lists use `role="list"` with `aria-labelledby` pointing to the "Conditions" / "Actions" section heading, and each row uses `role="listitem"`.

package/src/components/invocation-rule-builder/index.ts

@@ -0,0 +1,14 @@
+import './invocation-rule-builder.css';
+import InvocationRuleBuilder from './invocation-rule-builder.svelte';
+
+export default InvocationRuleBuilder;
+export type {
+  InvocationRule,
+  InvocationRuleAction,
+  InvocationRuleBuilderProps,
+  InvocationRuleBuilderSchemaProps,
+  InvocationRuleChange,
+  InvocationRuleCondition,
+  InvocationRuleOption,
+} from './invocation-rule-builder.types.ts';
+export { InvocationRuleBuilder };