@lostgradient/cinder 0.3.0 → 0.4.0

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

@@ -0,0 +1,180 @@
+import type { HTMLAttributes } from 'svelte/elements';
+
+export type ApprovalToolRisk = 'low' | 'medium' | 'high';
+
+/** @schemaObject */
+export type ApprovalTool = {
+  /** Human-readable tool name requesting approval. */
+  name: string;
+  /** Risk level assigned by the policy evaluator. */
+  risk: ApprovalToolRisk;
+};
+
+/** @schemaObject */
+export type ApprovalSandbox = {
+  /** Sandbox provider, such as Codex or a remote execution backend. */
+  provider: string;
+  /** Sandbox profile or policy name. */
+  name: string;
+  /** Working directory for the pending operation. */
+  workingDir: string;
+};
+
+export type ApprovalOperationKind = 'command' | 'file-write' | 'patch' | 'other';
+
+/** @schemaObject */
+export type ApprovalCommandOperation = {
+  /** Operation family being approved. */
+  kind: 'command';
+  /** Shell command for command approvals. */
+  command: string;
+  /** File paths that the operation may read or write. */
+  filesTouched?: string[];
+  /**
+   * JSON-like argument preview shown to the approver.
+   *
+   * @schemaPermissive
+   */
+  argsPreview?: unknown;
+};
+
+/** @schemaObject */
+export type ApprovalFileWriteOperation = {
+  /** Operation family being approved. */
+  kind: 'file-write';
+  /** File paths that the operation may read or write. File-write approvals require at least one path. */
+  filesTouched: string[];
+  /**
+   * JSON-like argument preview shown to the approver.
+   *
+   * @schemaPermissive
+   */
+  argsPreview?: unknown;
+};
+
+/** @schemaObject */
+export type ApprovalPatchOperation = {
+  /** Operation family being approved. */
+  kind: 'patch';
+  /** File paths that the operation may read or write. */
+  filesTouched?: string[];
+  /**
+   * JSON-like argument preview shown to the approver.
+   *
+   * @schemaPermissive
+   */
+  argsPreview?: unknown;
+  /** Patch diff for patch approvals. */
+  diff: string;
+};
+
+/** @schemaObject */
+export type ApprovalOtherOperation = {
+  /** Operation family being approved. */
+  kind: 'other';
+  /** File paths that the operation may read or write. */
+  filesTouched?: string[];
+  /**
+   * JSON-like argument preview shown to the approver.
+   *
+   * @schemaPermissive
+   */
+  argsPreview?: unknown;
+};
+
+export type ApprovalOperation =
+  | ApprovalCommandOperation
+  | ApprovalFileWriteOperation
+  | ApprovalPatchOperation
+  | ApprovalOtherOperation;
+
+export type ApprovalOperationSchema = ApprovalOperation;
+
+export type ApprovalState =
+  | 'pending'
+  | 'approved'
+  | 'approved_with_edits'
+  | 'denied'
+  | 'expired'
+  | 'cancelled';
+
+export type ApprovalCardCallbacks = {
+  /** Called when the approver accepts the operation as presented. */
+  onapprove?: () => void;
+  /** Called with parsed JSON arguments when the approver accepts edited arguments. */
+  onapprovewithedits?: (editedArgs: unknown) => void;
+  /** Called when the approver denies the operation. */
+  ondeny?: () => void;
+  /** Called when the approver asks the host application to remember the decision. */
+  onremember?: () => void;
+  /** Called when the approver cancels the approval prompt. */
+  oncancel?: () => void;
+};
+
+/** Props for the ApprovalCard component. */
+export type ApprovalCardProps = Omit<HTMLAttributes<HTMLElement>, 'class' | 'children'> &
+  ApprovalCardCallbacks & {
+    /** Tool requesting approval. */
+    tool: ApprovalTool;
+    /** Optional sandbox context in which the operation will run. */
+    sandbox?: ApprovalSandbox;
+    /** Operation details shown to the approver. */
+    operation: ApprovalOperation;
+    /** Environment variable names only. Values are ignored if accidentally supplied as `NAME=value`. */
+    env?: string[];
+    /** Snapshot identifier for the pending approval context. */
+    snapshotId?: string;
+    /** Policy version that produced the approval request. */
+    policyVersion: string;
+    /** Idempotency key that makes repeated decisions durable. */
+    idempotencyKey: string;
+    /** Optional ISO timestamp after which a pending approval is treated as expired. */
+    expiresAt?: string;
+    /** Persisted approval state. */
+    state: ApprovalState;
+    /** Whether approving with edited JSON arguments is available. Default `false`. */
+    editableArgs?: boolean;
+    /** Additional CSS classes applied to the root element. */
+    class?: string;
+  };
+
+/**
+ * Cinder-specific schema surface for ApprovalCard.
+ *
+ * Callback props are documented but marked unsupported because functions cannot
+ * be represented as JSON Schema controls.
+ */
+export type ApprovalCardSchemaProps = {
+  /** Tool requesting approval. */
+  tool: ApprovalTool;
+  /** Optional sandbox context in which the operation will run. */
+  sandbox?: ApprovalSandbox;
+  /** Operation details shown to the approver. */
+  operation: ApprovalOperationSchema;
+  /** Environment variable names only. Values are ignored if accidentally supplied as `NAME=value`. */
+  env?: string[];
+  /** Snapshot identifier for the pending approval context. */
+  snapshotId?: string;
+  /** Policy version that produced the approval request. */
+  policyVersion: string;
+  /** Idempotency key that makes repeated decisions durable. */
+  idempotencyKey: string;
+  /** Optional ISO timestamp after which a pending approval is treated as expired. */
+  expiresAt?: string;
+  /** Persisted approval state. */
+  state: ApprovalState;
+  /** Whether approving with edited JSON arguments is available. Default `false`. */
+  editableArgs?: boolean;
+  /** Called when the approver accepts the operation as presented. */
+  onapprove?: () => void;
+  /** Called with parsed JSON arguments when the approver accepts edited arguments. */
+  onapprovewithedits?: (editedArgs: unknown) => void;
+  /** Called when the approver denies the operation. */
+  ondeny?: () => void;
+  /** Called when the approver asks the host application to remember the decision. */
+  onremember?: () => void;
+  /** Called when the approver cancels the approval prompt. */
+  oncancel?: () => void;
+  /** Additional CSS classes applied to the root element. */
+  class?: string;
+};

package/src/components/approval-card/index.ts

@@ -0,0 +1,16 @@
+import './approval-card.css';
+import ApprovalCard from './approval-card.svelte';
+
+export default ApprovalCard;
+export type {
+  ApprovalCardCallbacks,
+  ApprovalCardProps,
+  ApprovalCardSchemaProps,
+  ApprovalOperation,
+  ApprovalOperationKind,
+  ApprovalSandbox,
+  ApprovalState,
+  ApprovalTool,
+  ApprovalToolRisk,
+} from './approval-card.types.ts';
+export { ApprovalCard };

package/src/components/autocomplete/autocomplete.css

@@ -6,6 +6,9 @@
   }
 
   .cinder-autocomplete__label {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--cinder-space-1);
     color: var(--cinder-text);
     font-size: var(--cinder-text-sm);
     font-weight: var(--cinder-font-medium);
@@ -27,6 +30,14 @@
     box-shadow: var(--_cinder-focus-ring-shadow);
   }
 
+  @media (forced-colors: active) {
+    .cinder-autocomplete__input:focus-visible {
+      outline: var(--cinder-ring-width) solid ButtonText;
+      outline-offset: 3px;
+      box-shadow: none;
+    }
+  }
+
   .cinder-autocomplete__description,
   .cinder-autocomplete__error {
     margin: 0;
@@ -99,7 +110,7 @@
     border-radius: var(--cinder-radius-sm);
     background: var(--cinder-color-warning-bg);
     color: var(--cinder-color-warning-fg);
-    font-weight: 600;
+    font-weight: var(--cinder-font-semibold);
   }
 
   .cinder-autocomplete__status {

package/src/components/autocomplete/autocomplete.svelte

@@ -87,7 +87,10 @@
   let composing = $state(false);
   let inputFocused = $state(false);
   let suggestions = $state<AutocompleteSuggestion[]>([]);
-  let activeIndex = $state<number | null>(null);
+  // rawActiveIndex tracks the user's chosen index; activeIndex clamps it from
+  // enabledIndexes so no write-back $effect is needed when renderedSuggestions
+  // changes (e.g. when maxVisibleSuggestions is updated by the consumer).
+  let rawActiveIndex = $state<number | null>(null);
   let suppressNextQuery = false;
   let ignoreSyntheticInput = false;
   let completionPointerIndex = $state<number | null>(null);
@@ -99,6 +102,17 @@
 
   const renderedSuggestions = $derived(suggestions.slice(0, resolvedMaxVisibleSuggestions));
   const enabledIndexes = $derived(getEnabledIndexes(renderedSuggestions));
+
+  // activeIndex is always valid for the current renderedSuggestions: if
+  // rawActiveIndex is not in the enabled set, fall back to the first enabled
+  // index (or null when the list is empty). This replaces the write-back
+  // $effect that previously called clampActiveIndex on every suggestions change.
+  const activeIndex = $derived.by(() => {
+    if (enabledIndexes.length === 0) return null;
+    if (rawActiveIndex !== null && enabledIndexes.includes(rawActiveIndex)) return rawActiveIndex;
+    return enabledIndexes[0] ?? null;
+  });
+
   const activeDescendant = $derived(
     activeIndex === null ? undefined : `${resolvedId}-option-${activeIndex}`,
   );
@@ -130,22 +144,6 @@
     return indexes;
   }
 
-  function clampActiveIndex(list: AutocompleteSuggestion[]): void {
-    const availableEnabledIndexes =
-      list === renderedSuggestions ? enabledIndexes : getEnabledIndexes(list);
-    if (availableEnabledIndexes.length === 0) {
-      activeIndex = null;
-      return;
-    }
-    if (activeIndex !== null && availableEnabledIndexes.includes(activeIndex)) return;
-    activeIndex = availableEnabledIndexes[0] ?? null;
-  }
-
-  $effect(() => {
-    void renderedSuggestions;
-    clampActiveIndex(renderedSuggestions);
-  });
-
   $effect(() => {
     const wasOpen = previousOpen;
     previousOpen = open;
@@ -157,7 +155,7 @@
     requestVersion += 1;
     autocompleteDismissed = true;
     loading = false;
-    activeIndex = null;
+    rawActiveIndex = null;
     suggestions = [];
   });
 
@@ -168,7 +166,7 @@
     autocompleteDismissed = true;
     open = false;
     loading = false;
-    activeIndex = null;
+    rawActiveIndex = null;
     suggestions = [];
   }
 
@@ -195,7 +193,7 @@
     loading = true;
     open = true;
     suggestions = [];
-    activeIndex = null;
+    rawActiveIndex = null;
 
     let result: AutocompleteSuggestion[] | Promise<AutocompleteSuggestion[]>;
     try {
@@ -218,10 +216,34 @@
         ) {
           return;
         }
-        suggestions = nextSuggestions;
+        // Deduplicate the ENTIRE suggestion list by value (first occurrence
+        // wins), not just the visible window. `renderedSuggestions` re-slices
+        // `suggestions` by maxVisibleSuggestions, so a duplicate anywhere in the
+        // stored list could surface in the keyed {#each} if the window widens or
+        // a tail value collides with the visible prefix — both crash with
+        // each_key_duplicate. Deduping the whole list makes the key globally
+        // unique regardless of window size.
+        const seen = new Set<string>();
+        const deduped: typeof nextSuggestions = [];
+        let hasDuplicates = false;
+        for (const suggestion of nextSuggestions) {
+          if (seen.has(suggestion.value)) {
+            hasDuplicates = true;
+          } else {
+            seen.add(suggestion.value);
+            deduped.push(suggestion);
+          }
+        }
+        if (hasDuplicates) {
+          devWarn(
+            '[cinder/Autocomplete] Duplicate suggestion values detected. Each rendered suggestion must have a unique value. Duplicates were removed; only the first occurrence of each value is shown.',
+          );
+        }
+        suggestions = deduped;
         loading = false;
         open = true;
-        clampActiveIndex(nextSuggestions.slice(0, resolvedMaxVisibleSuggestions));
+        // rawActiveIndex is reset to null when the query starts; activeIndex is
+        // $derived to auto-clamp, so no explicit clampActiveIndex call is needed.
       })
       .catch((errorValue: unknown) => {
         if (
@@ -266,7 +288,8 @@
 
     open = true;
     if (activeIndex === null) {
-      activeIndex = direction === 1 ? (enabledIndexes[0] ?? null) : (enabledIndexes.at(-1) ?? null);
+      rawActiveIndex =
+        direction === 1 ? (enabledIndexes[0] ?? null) : (enabledIndexes.at(-1) ?? null);
       return;
     }
 
@@ -275,13 +298,13 @@
       currentPosition < 0
         ? 0
         : (currentPosition + direction + enabledIndexes.length) % enabledIndexes.length;
-    activeIndex = enabledIndexes[nextPosition] ?? null;
+    rawActiveIndex = enabledIndexes[nextPosition] ?? null;
   }
 
   function moveToBoundary(direction: 'start' | 'end'): void {
     if (!open) return;
     if (enabledIndexes.length === 0) return;
-    activeIndex =
+    rawActiveIndex =
       direction === 'start' ? (enabledIndexes[0] ?? null) : (enabledIndexes.at(-1) ?? null);
   }
 
@@ -403,6 +426,9 @@
       data-disabled={field.disabled || undefined}
     >
       {label}
+      {#if field.required}
+        <span class="cinder-_required-marker" aria-hidden="true">*</span>
+      {/if}
     </label>
   {/if}
 
@@ -484,7 +510,7 @@
       {emptyMessage}
     </div>
   {:else}
-    {#each renderedSuggestions as suggestion, index (`${suggestion.value}-${index}`)}
+    {#each renderedSuggestions as suggestion, index (suggestion.value)}
       {@const suggestionLabel = suggestion.label ?? suggestion.value}
       {@const parts = highlightParts(suggestionLabel, value)}
       <div
@@ -503,7 +529,7 @@
           handleMouseDownFallback(event, index);
         }}
         onmouseenter={() => {
-          if (!suggestion.disabled) activeIndex = index;
+          if (!suggestion.disabled) rawActiveIndex = index;
         }}
       >
         <span class="cinder-autocomplete__option-text">

package/src/components/badge/README.md

@@ -18,13 +18,14 @@ Use Badge for attached counts, statuses, and compact annotations; use `Chip mode
 
 <!-- generated:props:start -->
 
-| Prop       | Type                                                                              | Required | Default     | Description                                                                                                                                                                                                                                                               |
-| ---------- | --------------------------------------------------------------------------------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `class`    | `string`                                                                          | no       | —           | Custom class merged with `.cinder-badge`.                                                                                                                                                                                                                                 |
-| `mono`     | `boolean`                                                                         | no       | `false`     | Render the badge label in a monospace font. Useful for version strings, error codes, or other technical labels.                                                                                                                                                           |
-| `size`     | `"xs"` \| `"sm"` \| `"md"`                                                        | no       | `"md"`      | Size of the badge.                                                                                                                                                                                                                                                        |
-| `variant`  | `"neutral"` \| `"success"` \| `"warning"` \| `"danger"` \| `"info"` \| `"accent"` | no       | `"neutral"` | Visual style.                                                                                                                                                                                                                                                             |
-| `children` | `(opaque)`                                                                        | yes      | —           | Badge content — intentionally required. A badge without content is semantically meaningless. The render site uses optional chaining (`children?.()`) as a runtime safety net for JS consumers. Not expressible in JSON Schema; see the component types for the signature. |
+| Prop                | Type                                                                                      | Required | Default     | Description                                                                                                                                                                                          |
+| ------------------- | ----------------------------------------------------------------------------------------- | -------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`             | `string`                                                                                  | no       | —           | Custom class merged with `.cinder-badge`.                                                                                                                                                            |
+| `mono`              | `boolean`                                                                                 | no       | `false`     | Render the badge label in a monospace font. Useful for version strings, error codes, or other technical labels.                                                                                      |
+| `size`              | `"xs"` \| `"sm"` \| `"md"`                                                                | no       | `"md"`      | Size of the badge.                                                                                                                                                                                   |
+| `subscriptionState` | `"active"` \| `"trialing"` \| `"past-due"` \| `"canceled"` \| `"expired"` \| `"refunded"` | no       | —           | Render a standardized subscription lifecycle badge without hand-wiring tone, icon, and label.                                                                                                        |
+| `variant`           | `"neutral"` \| `"success"` \| `"warning"` \| `"danger"` \| `"info"` \| `"accent"`         | no       | `"neutral"` | Visual style.                                                                                                                                                                                        |
+| `children`          | `(opaque)`                                                                                | no       | —           | Required badge content unless subscriptionState is provided; optional content override for the subscription preset label. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

package/src/components/badge/badge.svelte

@@ -4,10 +4,14 @@
    * @category data-display
    * @status stable
    * @purpose Compact non-interactive label that annotates an adjacent element with a short status, count, or category.
+   * @tag billing
    * @tag label
    * @tag indicator
+   * @tag subscription
    * @useWhen Annotating a value with a short status word like "new" or "beta".
    * @useWhen Displaying a numeric count next to an icon or title.
+   * @useWhen Displaying the billing state of a subscription in a dashboard, invoice list, or account settings page.
+   * @useWhen Annotating a plan name, customer row, or invoice line with its current payment lifecycle state.
    * @avoidWhen The label must be interactive or removable — use chip instead.
    * @avoidWhen Showing only a colored dot for presence — use status-dot instead.
    * @related chip, status-dot
@@ -18,24 +22,97 @@
 <script lang="ts">
   import { classNames } from '../../utilities/class-names.ts';
 
-  import type { BadgeProps } from './badge.types.ts';
+  import type { BadgeProps, BadgeSubscriptionState, BadgeVariant } from './badge.types.ts';
+
+  type SubscriptionStateConfiguration = {
+    variant: BadgeVariant;
+    label: string;
+  };
+
+  const subscriptionStateConfigurations: Record<
+    BadgeSubscriptionState,
+    SubscriptionStateConfiguration
+  > = {
+    active: { variant: 'success', label: 'Active' },
+    trialing: { variant: 'info', label: 'Trialing' },
+    'past-due': { variant: 'warning', label: 'Past due' },
+    canceled: { variant: 'neutral', label: 'Canceled' },
+    expired: { variant: 'danger', label: 'Expired' },
+    refunded: { variant: 'neutral', label: 'Refunded' },
+  };
+
+  const subscriptionStateIconPaths: Record<BadgeSubscriptionState, string[]> = {
+    active: ['M21.801 10A10 10 0 1 1 17 3.335', 'm9 11 3 3L22 4'],
+    trialing: ['M12 6v6l4 2', 'M21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0Z'],
+    'past-due': [
+      'm21.73 18-8-14a2 2 0 0 0-3.46 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3Z',
+      'M12 9v4',
+      'M12 17h.01',
+    ],
+    canceled: ['M15 9 9 15', 'M9 9l6 6', 'M22 12A10 10 0 1 1 12 2a10 10 0 0 1 10 10Z'],
+    expired: [
+      'M8 2v4',
+      'M16 2v4',
+      'M21 13V6a2 2 0 0 0-2-2H5a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h8',
+      'M3 10h18',
+      'm17 14-5-5',
+      'm12 14 5 5',
+    ],
+    refunded: ['M3 12a9 9 0 1 0 9-9 9.75 9.75 0 0 0-6.74 2.74L3 8', 'M3 3v5h5'],
+  };
 
   let {
     variant = 'neutral',
     size = 'md',
     mono = false,
+    subscriptionState,
     class: customClassName,
     children,
     ...rest
   }: BadgeProps = $props();
+
+  const subscriptionStateConfiguration = $derived(
+    subscriptionState === undefined
+      ? undefined
+      : subscriptionStateConfigurations[subscriptionState],
+  );
+  const resolvedVariant = $derived(subscriptionStateConfiguration?.variant ?? variant);
+  const resolvedSubscriptionIconPaths = $derived(
+    subscriptionState === undefined ? undefined : subscriptionStateIconPaths[subscriptionState],
+  );
 </script>
 
 <span
   class={classNames('cinder-badge', customClassName)}
-  data-cinder-variant={variant}
+  data-cinder-variant={resolvedVariant}
   data-cinder-size={size}
   data-cinder-mono={mono ? '' : undefined}
+  data-cinder-subscription-state={subscriptionState}
   {...rest}
 >
-  {@render children?.()}
+  {#if subscriptionStateConfiguration}
+    {#if resolvedSubscriptionIconPaths}
+      <svg
+        class="icon-sm"
+        aria-hidden="true"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="2"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+      >
+        {#each resolvedSubscriptionIconPaths as iconPath (iconPath)}
+          <path d={iconPath}></path>
+        {/each}
+      </svg>
+    {/if}
+    {#if children}
+      {@render children()}
+    {:else}
+      {subscriptionStateConfiguration.label}
+    {/if}
+  {:else}
+    {@render children?.()}
+  {/if}
 </span>

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

@@ -7,20 +7,41 @@ export type BadgeVariant = 'neutral' | 'success' | 'warning' | 'danger' | 'info'
 /** Size of the badge. */
 export type BadgeSize = 'xs' | 'sm' | 'md';
 
+/** Billing lifecycle states that Badge can render as an opinionated preset. */
+export type BadgeSubscriptionState =
+  | 'active'
+  | 'trialing'
+  | 'past-due'
+  | 'canceled'
+  | 'expired'
+  | 'refunded';
+
 /** Props for the Badge component. */
-export type BadgeProps = HTMLAttributes<HTMLSpanElement> & {
-  variant?: BadgeVariant;
-  size?: BadgeSize;
-  /** Render the badge label in a monospace font. */
-  mono?: boolean;
-  class?: string;
-  /**
-   * Badge content — intentionally required. A badge without content is
-   * semantically meaningless. The render site uses optional chaining
-   * (`children?.()`) as a runtime safety net for JS consumers.
-   */
-  children: Snippet;
-};
+export type BadgeProps =
+  | (HTMLAttributes<HTMLSpanElement> & {
+      variant?: BadgeVariant;
+      size?: BadgeSize;
+      /** Render the badge label in a monospace font. */
+      mono?: boolean;
+      class?: string;
+      /** Render a standardized subscription lifecycle badge without hand-wiring tone, icon, and label. */
+      subscriptionState: BadgeSubscriptionState;
+      /** Required badge content unless subscriptionState is provided; optional content override for the subscription preset label. */
+      children?: Snippet;
+    })
+  | (HTMLAttributes<HTMLSpanElement> & {
+      variant?: BadgeVariant;
+      size?: BadgeSize;
+      /** Render the badge label in a monospace font. */
+      mono?: boolean;
+      class?: string;
+      subscriptionState?: undefined;
+      /**
+       * Badge content — intentionally required. A badge without content is
+       * semantically meaningless.
+       */
+      children: Snippet;
+    });
 
 /** Cinder-specific props for the Badge component, used by the schema generator. */
 export interface BadgeSchemaProps {
@@ -39,6 +60,8 @@ export interface BadgeSchemaProps {
    * @default false
    */
   mono?: boolean;
+  /** Render a standardized subscription lifecycle badge without hand-wiring tone, icon, and label. */
+  subscriptionState?: BadgeSubscriptionState;
   /** Custom class merged with `.cinder-badge`. */
   class?: string;
 }

package/src/components/badge/index.ts

@@ -2,5 +2,5 @@ import './badge.css';
 import Badge from './badge.svelte';
 
 export default Badge;
-export type { BadgeProps, BadgeSize, BadgeVariant } from './badge.types.ts';
+export type { BadgeProps, BadgeSize, BadgeSubscriptionState, BadgeVariant } from './badge.types.ts';
 export { Badge };

package/src/components/banner/README.md

@@ -9,7 +9,7 @@ Full-width announcement strip for page-level alerts, promotions, or system messa
   import Banner from '@lostgradient/cinder/banner';
 </script>
 
-<Banner />
+<Banner>Your message here.</Banner>
 ```
 
 ## Props
@@ -23,7 +23,7 @@ Full-width announcement strip for page-level alerts, promotions, or system messa
 | `variant`     | `"info"` \| `"success"` \| `"warning"` \| `"danger"` | no       | —       | Visual + semantic variant. Default `'info'`.                                                                                                                                                    |
 | `actions`     | `(opaque)`                                           | no       | —       | Optional trailing CTA region (e.g., "Renew now" button). Not expressible in JSON Schema; see the component types for the signature.                                                             |
 | `children`    | `(opaque)`                                           | yes      | —       | Banner body content. Not expressible in JSON Schema; see the component types for the signature.                                                                                                 |
-| `onDismiss`   | `(opaque)`                                           | no       | —       | Called after the dismiss button is clicked. Use to persist state. Not expressible in JSON Schema; see the component types for the signature.                                                    |
+| `ondismiss`   | `(opaque)`                                           | no       | —       | Called after the dismiss button is clicked. Use to persist state. Not expressible in JSON Schema; see the component types for the signature.                                                    |
 
 <!-- generated:props:end -->
 

package/src/components/banner/banner.examples.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "banner",
+  "import": "@lostgradient/cinder/banner",
+  "examples": [
+    {
+      "id": "basic",
+      "title": "Basic banner",
+      "description": "Informational page-level banner with a dismiss button.",
+      "code": "<script lang=\"ts\">\n  import { Banner } from '@lostgradient/cinder/banner';\n\n  let visible = $state(true);\n</script>\n\n{#if visible}\n  <Banner variant=\"info\" ondismiss={() => (visible = false)}>\n    Scheduled maintenance is planned for Sunday at 2:00 AM UTC.\n  </Banner>\n{:else}\n  <p style=\"color: var(--cinder-text-muted);\">Banner dismissed.</p>\n{/if}\n"
+    },
+    {
+      "id": "variants",
+      "title": "Banner variants",
+      "description": "All four semantic variant styles — info, success, warning, and danger.",
+      "code": "<script lang=\"ts\">\n  import { Banner } from '@lostgradient/cinder/banner';\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 0.75rem;\">\n  <Banner variant=\"info\" dismissible={false}>Your trial expires in 7 days.</Banner>\n  <Banner variant=\"success\" dismissible={false}>Your changes have been saved successfully.</Banner>\n  <Banner variant=\"warning\" dismissible={false}>Storage is 90% full. Free up space soon.</Banner>\n  <Banner variant=\"danger\" dismissible={false}>Your payment method has expired.</Banner>\n</div>\n"
+    }
+  ]
+}