@lostgradient/cinder 0.3.0 → 0.4.0

package/src/components/_internal/create-command-list-state.svelte.ts

@@ -0,0 +1,171 @@
+import { inDocumentOrder } from '../../utilities/document-order.ts';
+import type { CommandItemRegistrationInput, CommandListContext } from './command-list-context.ts';
+
+type RegistrationRecord = CommandItemRegistrationInput & { id: string; node: HTMLElement };
+
+export type CommandListKeyboardOptions = {
+  event: KeyboardEvent;
+  onEnter?: (id: string) => void;
+  onEscape?: () => void;
+  ignoreModifiedNavigation?: boolean;
+  preventDefaultOnEmptyEnter?: boolean;
+};
+
+export class CommandListState {
+  readonly listboxId: string;
+  registrations = $state<RegistrationRecord[]>([]);
+  registrationsReady = $state(false);
+  #itemCounter = 0;
+  #readyCycle = 0;
+  #intendedActiveId = $state<string | null>(null);
+
+  enabledIds = $derived.by(() => {
+    return inDocumentOrder(this.registrations)
+      .filter((registration) => !registration.getDisabled())
+      .map((registration) => registration.id);
+  });
+
+  activeItemId = $derived(
+    this.#intendedActiveId !== null && this.enabledIds.includes(this.#intendedActiveId)
+      ? this.#intendedActiveId
+      : (this.enabledIds[0] ?? null),
+  );
+
+  constructor(listboxId: string) {
+    this.listboxId = listboxId;
+  }
+
+  resetActiveItem(): void {
+    this.#intendedActiveId = null;
+  }
+
+  refreshRegistrationsReady(): void {
+    this.registrationsReady = false;
+    const cycle = ++this.#readyCycle;
+    queueMicrotask(() => {
+      if (cycle === this.#readyCycle) this.registrationsReady = true;
+    });
+  }
+
+  scrollActiveItemIntoView(): void {
+    if (this.activeItemId === null) return;
+    const record = this.registrations.find((registration) => registration.id === this.activeItemId);
+    record?.node.scrollIntoView({ block: 'nearest' });
+  }
+
+  setActiveById(id: string): void {
+    this.#intendedActiveId = id;
+  }
+
+  register(input: CommandItemRegistrationInput, node: HTMLElement) {
+    const id = `${this.listboxId}-item-${++this.#itemCounter}`;
+    this.registrations.push({
+      id,
+      node,
+      getValue: input.getValue,
+      getOnselect: input.getOnselect,
+      getDisabled: input.getDisabled,
+    });
+    return {
+      id,
+      unregister: () => {
+        const index = this.registrations.findIndex((registration) => registration.id === id);
+        if (index !== -1) this.registrations.splice(index, 1);
+      },
+    };
+  }
+
+  activateItemById(id: string): RegistrationRecord | null {
+    const record = this.registrations.find((registration) => registration.id === id);
+    if (!record || record.getDisabled()) return null;
+    record.getOnselect()();
+    return record;
+  }
+
+  handleKeydown({
+    event,
+    onEnter,
+    onEscape,
+    ignoreModifiedNavigation = false,
+    preventDefaultOnEmptyEnter = false,
+  }: CommandListKeyboardOptions): boolean {
+    if (event.isComposing || event.keyCode === 229) return false;
+    const isModified = event.altKey || event.ctrlKey || event.metaKey || event.shiftKey;
+    const ids = this.enabledIds;
+
+    if (event.key === 'ArrowDown') {
+      if (ignoreModifiedNavigation && isModified) return false;
+      event.preventDefault();
+      if (ids.length === 0) return true;
+      const index = this.activeItemId === null ? -1 : ids.indexOf(this.activeItemId);
+      this.#intendedActiveId = ids[(index + 1) % ids.length] ?? null;
+      return true;
+    }
+
+    if (event.key === 'ArrowUp') {
+      if (ignoreModifiedNavigation && isModified) return false;
+      event.preventDefault();
+      if (ids.length === 0) return true;
+      const index = this.activeItemId === null ? 0 : ids.indexOf(this.activeItemId);
+      this.#intendedActiveId = ids[index <= 0 ? ids.length - 1 : index - 1] ?? null;
+      return true;
+    }
+
+    if (event.key === 'Home') {
+      if (ignoreModifiedNavigation && isModified) return false;
+      event.preventDefault();
+      this.#intendedActiveId = ids[0] ?? null;
+      return true;
+    }
+
+    if (event.key === 'End') {
+      if (ignoreModifiedNavigation && isModified) return false;
+      event.preventDefault();
+      this.#intendedActiveId = ids[ids.length - 1] ?? null;
+      return true;
+    }
+
+    if (event.key === 'Enter') {
+      if (!onEnter) return false;
+      if (this.activeItemId === null && !preventDefaultOnEmptyEnter) return false;
+      event.preventDefault();
+      event.stopPropagation();
+      if (this.activeItemId === null) return true;
+      onEnter?.(this.activeItemId);
+      return true;
+    }
+
+    if (event.key === 'Escape' && onEscape) {
+      event.preventDefault();
+      event.stopPropagation();
+      onEscape();
+      return true;
+    }
+
+    return false;
+  }
+
+  createContext(activateItemById: (id: string) => void = (id) => void this.activateItemById(id)) {
+    const listboxId = this.listboxId;
+    const getActiveItemId = () => this.activeItemId;
+    const register = (input: CommandItemRegistrationInput, node: HTMLElement) =>
+      this.register(input, node);
+    const setActiveById = (id: string) => this.setActiveById(id);
+
+    return {
+      get listboxId() {
+        return listboxId;
+      },
+      get activeItemId() {
+        return getActiveItemId();
+      },
+      register,
+      setActiveById,
+      activateItemById,
+    } satisfies CommandListContext;
+  }
+}
+
+export function createCommandListState(listboxId: string): CommandListState {
+  return new CommandListState(listboxId);
+}

package/src/components/_internal/create-sliding-dialog-state.svelte.ts

@@ -0,0 +1,170 @@
+import { captureFocus, lockBodyScroll, pushEscapeHandler } from '../../_internal/overlay.ts';
+import { waitForTransitionCompletion } from '../../_internal/transition-completion.ts';
+import { restoreFocusTo } from '../../utilities/focus.ts';
+
+export type SlidingDialogStateOptions = {
+  getOpen: () => boolean;
+  setOpen: (open: boolean) => void;
+  getDialogElement: () => HTMLDialogElement | undefined;
+  getPanelElement: () => HTMLElement | undefined;
+  getReducedMotion: () => boolean;
+  getTriggerRef: () => HTMLElement | null;
+  onOpen?: () => void;
+  onClosed?: () => void;
+};
+
+export class SlidingDialogState {
+  hydrated = $state(false);
+  renderPanel = $state(false);
+  isClosing = $state(false);
+  readonly #options: SlidingDialogStateOptions;
+  #closeGeneration = $state(0);
+  #capturedFocus: HTMLElement | null = null;
+  #releaseScrollLock: (() => void) | null = null;
+  #releaseEscape: (() => void) | null = null;
+  #cancelPendingClose: (() => void) | null = null;
+
+  constructor(options: SlidingDialogStateOptions) {
+    this.#options = options;
+    this.renderPanel = options.getOpen();
+  }
+
+  markHydrated(): void {
+    this.hydrated = true;
+  }
+
+  syncOpenState(): void {
+    const dialogElement = this.#options.getDialogElement();
+    if (!dialogElement) return;
+
+    if (this.#options.getOpen()) {
+      if (this.isClosing) {
+        this.#closeGeneration += 1;
+        this.#cancelPendingClose?.();
+        this.#cancelPendingClose = null;
+        this.isClosing = false;
+      }
+
+      if (!this.renderPanel) {
+        this.renderPanel = true;
+      }
+
+      if (!dialogElement.open) {
+        this.#capturedFocus = captureFocus();
+        dialogElement.showModal();
+        this.#acquireScrollLock();
+        this.#acquireEscapeMarker();
+        this.#options.onOpen?.();
+      }
+      return;
+    }
+
+    if (dialogElement.open) {
+      this.beginClosing();
+    } else {
+      this.renderPanel = false;
+    }
+  }
+
+  beginClosing(): void {
+    const dialogElement = this.#options.getDialogElement();
+    if (!dialogElement?.open || this.isClosing) return;
+    const panelElement = this.#options.getPanelElement();
+    if (!panelElement) {
+      this.#finishClosing(this.#closeGeneration);
+      return;
+    }
+
+    this.isClosing = true;
+    const generation = ++this.#closeGeneration;
+    this.#cancelPendingClose?.();
+    this.#cancelPendingClose = waitForTransitionCompletion({
+      element: panelElement,
+      reducedMotion: this.#options.getReducedMotion(),
+      onComplete: () => this.#finishClosing(generation),
+    });
+  }
+
+  handleClose(): void {
+    this.#releaseScrollLock?.();
+    this.#releaseScrollLock = null;
+    this.#releaseEscape?.();
+    this.#releaseEscape = null;
+    this.#options.setOpen(false);
+    this.#returnFocus();
+  }
+
+  requestClose(): void {
+    if (!this.#options.getOpen() && (this.isClosing || !this.#options.getDialogElement()?.open)) {
+      return;
+    }
+    this.#options.setOpen(false);
+    this.beginClosing();
+  }
+
+  handleBackdropClick(event: MouseEvent): void {
+    if (event.target === this.#options.getDialogElement()) {
+      this.requestClose();
+    }
+  }
+
+  handleNativeCancel(event: Event): void {
+    event.preventDefault();
+    this.requestClose();
+  }
+
+  destroy(): void {
+    this.#cancelPendingClose?.();
+    this.#cancelPendingClose = null;
+    const wasOpen = this.#releaseScrollLock !== null || this.#releaseEscape !== null;
+    this.#releaseScrollLock?.();
+    this.#releaseScrollLock = null;
+    this.#releaseEscape?.();
+    this.#releaseEscape = null;
+    if (wasOpen) {
+      this.#returnFocus();
+    }
+  }
+
+  #finishClosing(generation: number): void {
+    if (generation !== this.#closeGeneration) return;
+    this.#cancelPendingClose?.();
+    this.#cancelPendingClose = null;
+    this.isClosing = false;
+    if (this.#options.getOpen()) {
+      this.renderPanel = true;
+      return;
+    }
+    this.renderPanel = false;
+    this.#options.onClosed?.();
+    const dialogElement = this.#options.getDialogElement();
+    if (dialogElement?.open) {
+      dialogElement.close();
+    }
+  }
+
+  #acquireScrollLock(): void {
+    if (this.#releaseScrollLock) return;
+    this.#releaseScrollLock = lockBodyScroll();
+  }
+
+  #acquireEscapeMarker(): void {
+    if (this.#releaseEscape) return;
+    this.#releaseEscape = pushEscapeHandler(() => {});
+  }
+
+  #returnFocus(): void {
+    const candidates: Array<HTMLElement | null> = [
+      this.#options.getTriggerRef(),
+      this.#capturedFocus,
+    ];
+    this.#capturedFocus = null;
+    for (const candidate of candidates) {
+      if (restoreFocusTo(candidate)) break;
+    }
+  }
+}
+
+export function createSlidingDialogState(options: SlidingDialogStateOptions): SlidingDialogState {
+  return new SlidingDialogState(options);
+}

package/src/components/_radio/README.md

@@ -13,7 +13,7 @@ runtime. (A standalone `Checkbox`, by contrast, is a legitimate independent cont
   import { RadioGroup } from '@lostgradient/cinder/radio-group';
 </script>
 
-<RadioGroup name="plan" legend="Pricing tier">
+<RadioGroup name="plan" label="Pricing tier">
   <RadioGroup.Option id="free" value="free" label="Free" />
   <RadioGroup.Option id="pro" value="pro" label="Pro" />
 </RadioGroup>

package/src/components/access-gate/access-gate-inline.svelte

@@ -231,7 +231,9 @@
       moveFocusOffControl(control);
     }
 
-    function syncDisabledControls(stateRefreshes?: ConsumerStateRefreshes): void {
+    function syncDisabledControls(
+      stateRefreshes: ConsumerStateRefreshes | undefined = undefined,
+    ): void {
       const currentControls = new Set(element.querySelectorAll<HTMLElement>(INTERACTIVE_SELECTOR));
 
       for (const control of currentControls) {

package/src/components/alert/README.md

@@ -16,14 +16,14 @@ A status message that communicates contextual feedback and can optionally be dis
 
 <!-- generated:props:start -->
 
-| Prop          | Type                                                              | Required | Default  | Description                                                                                                                |
-| ------------- | ----------------------------------------------------------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `class`       | `string`                                                          | no       | —        | Custom class merged with `.cinder-alert`.                                                                                  |
-| `dismissible` | `boolean`                                                         | no       | `false`  | Allow the alert to be dismissed.                                                                                           |
-| `variant`     | `"info"` \| `"success"` \| `"warning"` \| `"error"` \| `"danger"` | no       | `"info"` | Visual style. `danger` is an accepted alias for `error` — both render identically.                                         |
-| `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. |
-| `icon`        | `(opaque)`                                                        | no       | —        | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `onDismiss`   | `(opaque)`                                                        | no       | —        | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
+| Prop          | Type                                                 | Required | Default  | Description                                                                                                                |
+| ------------- | ---------------------------------------------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `class`       | `string`                                             | no       | —        | Custom class merged with `.cinder-alert`.                                                                                  |
+| `dismissible` | `boolean`                                            | no       | `false`  | Allow the alert to be dismissed.                                                                                           |
+| `variant`     | `"info"` \| `"success"` \| `"warning"` \| `"danger"` | no       | `"info"` | Visual severity variant. `danger` is the canonical failure-severity spelling, consistent with banner and callout.          |
+| `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. |
+| `icon`        | `(opaque)`                                           | no       | —        | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
+| `ondismiss`   | `(opaque)`                                           | no       | —        | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
 
 <!-- generated:props:end -->
 

package/src/components/alert/alert.css

@@ -149,7 +149,7 @@
     --_cinder-status-fg-chroma-dark: 0.14;
   }
 
-  .cinder-alert[data-cinder-variant='error'] {
+  .cinder-alert[data-cinder-variant='danger'] {
     --_cinder-alert-ring: var(--cinder-danger);
     --_cinder-status-base: var(--cinder-danger);
     --_cinder-status-fg-chroma-light: 0.18;

package/src/components/alert/alert.examples.json

@@ -6,14 +6,14 @@
     {
       "id": "dismissible",
       "title": "Dismissible alert",
-      "description": "An alert with a close button that fires onDismiss.",
-      "code": "<script lang=\"ts\">\n  import { Alert } from '@lostgradient/cinder/alert';\n  let dismissed = $state(false);\n</script>\n\n{#if !dismissed}\n  <Alert variant=\"info\" dismissible onDismiss={() => (dismissed = true)}>\n    You have 3 unread notifications.\n  </Alert>\n{:else}\n  <p style=\"color: var(--cinder-text-muted); font-style: italic;\">Alert dismissed.</p>\n{/if}\n"
+      "description": "An alert with a close button that fires ondismiss.",
+      "code": "<script lang=\"ts\">\n  import { Alert } from '@lostgradient/cinder/alert';\n  let dismissed = $state(false);\n</script>\n\n{#if !dismissed}\n  <Alert variant=\"info\" dismissible ondismiss={() => (dismissed = true)}>\n    You have 3 unread notifications.\n  </Alert>\n{:else}\n  <p style=\"color: var(--cinder-text-muted); font-style: italic;\">Alert dismissed.</p>\n{/if}\n"
     },
     {
       "id": "variants",
       "title": "Alert variants",
-      "description": "Info, success, warning, and error alerts.",
-      "code": "<script lang=\"ts\">\n  import { Alert } from '@lostgradient/cinder/alert';\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 1rem;\">\n  <Alert variant=\"info\">Your account sync is in progress.</Alert>\n  <Alert variant=\"success\">Changes saved successfully.</Alert>\n  <Alert variant=\"warning\">Your trial expires in 3 days.</Alert>\n  <Alert variant=\"error\">Failed to connect to the server.</Alert>\n</div>\n"
+      "description": "Info, success, warning, and danger alerts.",
+      "code": "<script lang=\"ts\">\n  import { Alert } from '@lostgradient/cinder/alert';\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 1rem;\">\n  <Alert variant=\"info\">Your account sync is in progress.</Alert>\n  <Alert variant=\"success\">Changes saved successfully.</Alert>\n  <Alert variant=\"warning\">Your trial expires in 3 days.</Alert>\n  <Alert variant=\"danger\">Failed to connect to the server.</Alert>\n</div>\n"
     },
     {
       "id": "with-icon",

package/src/components/alert/alert.svelte

@@ -28,16 +28,14 @@
   let {
     variant = 'info',
     dismissible = false,
-    onDismiss,
+    ondismiss,
     class: className,
     children,
     icon,
     ...rest
   }: AlertProps = $props();
 
-  // `danger` is a consumer-friendly alias for `error` — normalize before stamping the
-  // data attribute so the CSS rules only need to handle `error`.
-  const resolvedVariant = $derived(variant === 'danger' ? 'error' : variant);
+  const resolvedVariant = $derived(variant);
 
   let visible = $state(true);
   let rootElement: HTMLDivElement | undefined = $state();
@@ -48,7 +46,7 @@
     visible = false;
     await tick();
     if (focusTarget?.isConnected) focusTarget.focus();
-    onDismiss?.();
+    ondismiss?.();
   }
 
   function resolveFocusTarget(alertElement: HTMLElement): HTMLElement | null {

package/src/components/alert/alert.types.ts

@@ -1,8 +1,8 @@
 import type { Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
 
-/** `danger` is an accepted alias for `error` — both render identically. */
-export type AlertVariant = 'info' | 'success' | 'warning' | 'error' | 'danger';
+/** Visual severity variants for the Alert component. `danger` is the canonical spelling shared by banner and callout. */
+export type AlertVariant = 'info' | 'success' | 'warning' | 'danger';
 
 /**
  * Props for the {@link Alert} component — a live-region notification card.
@@ -24,7 +24,7 @@ export type AlertProps = Omit<
 > & {
   variant?: AlertVariant;
   dismissible?: boolean;
-  onDismiss?: () => void;
+  ondismiss?: () => void;
   class?: string;
   children: Snippet;
   icon?: Snippet;
@@ -37,7 +37,7 @@ export type AlertProps = Omit<
  */
 export interface AlertSchemaProps {
   /**
-   * Visual style. `danger` is an accepted alias for `error` — both render identically.
+   * Visual severity variant. `danger` is the canonical failure-severity spelling, consistent with banner and callout.
    * @default "info"
    */
   variant?: AlertVariant;

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

@@ -0,0 +1,92 @@
+# ApprovalCard
+
+Presentational human-in-the-loop approval surface for reviewing a tool operation
+before the host application executes it.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { ApprovalCard } from '@lostgradient/cinder/approval-card';
+</script>
+
+<ApprovalCard
+  tool={{ name: 'deploy-cloud', risk: 'medium' }}
+  sandbox={{
+    provider: 'codex',
+    name: 'workspace-write',
+    workingDir: '/workspace/project',
+  }}
+  operation={{
+    kind: 'command',
+    command: 'bun run --filter=@lostgradient/cinder validate',
+    argsPreview: { package: '@lostgradient/cinder' },
+  }}
+  env={['DATABASE_URL', 'OPENAI_API_KEY']}
+  policyVersion="policy-2026-06"
+  idempotencyKey="approval-01JZ8T"
+  state="pending"
+  onapprove={() => approve()}
+  ondeny={() => deny()}
+/>
+```
+
+`ApprovalCard` is fully controlled. It does not execute commands, apply patches,
+persist policy decisions, or read environment values. The component only renders
+the supplied context and invokes callback props for host-owned actions.
+
+## Operation rendering
+
+- `operation.kind: 'command'` renders the command with `CodeBlock`.
+- `operation.kind: 'patch'` renders the supplied unified patch as diff code.
+- `operation.argsPreview` renders through `PayloadInspector`; oversized previews
+  are replaced with a bounded truncation notice before rendering.
+- `env` renders variable names only. Values are not accepted and are stripped if
+  a caller accidentally passes `NAME=value`.
+
+## Approval states
+
+Pending requests render action buttons. Non-pending requests render a read-only
+summary. When `expiresAt` passes while `state` is still `pending`, the effective
+state becomes `expired`, actions disappear, and no callback fires automatically.
+
+## Props
+
+<!-- generated:props:start -->
+
+| Prop                 | Type                                                                                                                                                                                                                                                                                                                                              | Required | Default | Description                                                                                                                                              |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`              | `string`                                                                                                                                                                                                                                                                                                                                          | no       | —       | Additional CSS classes applied to the root element.                                                                                                      |
+| `editableArgs`       | `boolean`                                                                                                                                                                                                                                                                                                                                         | no       | —       | Whether approving with edited JSON arguments is available. Default `false`.                                                                              |
+| `env`                | `string`[]                                                                                                                                                                                                                                                                                                                                        | no       | —       | Environment variable names only. Values are ignored if accidentally supplied as `NAME=value`.                                                            |
+| `expiresAt`          | `string`                                                                                                                                                                                                                                                                                                                                          | no       | —       | Optional ISO timestamp after which a pending approval is treated as expired.                                                                             |
+| `idempotencyKey`     | `string`                                                                                                                                                                                                                                                                                                                                          | yes      | —       | Idempotency key that makes repeated decisions durable.                                                                                                   |
+| `operation`          | { argsPreview?: `unknown`; command: `string`; filesTouched?: `string`[]; kind: `"command"` } \| { argsPreview?: `unknown`; filesTouched: `string`[]; kind: `"file-write"` } \| { argsPreview?: `unknown`; diff: `string`; filesTouched?: `string`[]; kind: `"patch"` } \| { argsPreview?: `unknown`; filesTouched?: `string`[]; kind: `"other"` } | yes      | —       | Operation details shown to the approver.                                                                                                                 |
+| `policyVersion`      | `string`                                                                                                                                                                                                                                                                                                                                          | yes      | —       | Policy version that produced the approval request.                                                                                                       |
+| `sandbox`            | { name: `string`; provider: `string`; workingDir: `string` }                                                                                                                                                                                                                                                                                      | no       | —       | Optional sandbox context in which the operation will run.                                                                                                |
+| `snapshotId`         | `string`                                                                                                                                                                                                                                                                                                                                          | no       | —       | Snapshot identifier for the pending approval context.                                                                                                    |
+| `state`              | `"pending"` \| `"approved"` \| `"approved_with_edits"` \| `"denied"` \| `"expired"` \| `"cancelled"`                                                                                                                                                                                                                                              | yes      | —       | Persisted approval state.                                                                                                                                |
+| `tool`               | { name: `string`; risk: `"low"` \| `"medium"` \| `"high"` }                                                                                                                                                                                                                                                                                       | yes      | —       | Tool requesting approval.                                                                                                                                |
+| `onapprove`          | `(opaque)`                                                                                                                                                                                                                                                                                                                                        | no       | —       | Called when the approver accepts the operation as presented. Not expressible in JSON Schema; see the component types for the signature.                  |
+| `onapprovewithedits` | `(opaque)`                                                                                                                                                                                                                                                                                                                                        | no       | —       | Called with parsed JSON arguments when the approver accepts edited arguments. Not expressible in JSON Schema; see the component types for the signature. |
+| `oncancel`           | `(opaque)`                                                                                                                                                                                                                                                                                                                                        | no       | —       | Called when the approver cancels the approval prompt. Not expressible in JSON Schema; see the component types for the signature.                         |
+| `ondeny`             | `(opaque)`                                                                                                                                                                                                                                                                                                                                        | no       | —       | Called when the approver denies the operation. Not expressible in JSON Schema; see the component types for the signature.                                |
+| `onremember`         | `(opaque)`                                                                                                                                                                                                                                                                                                                                        | no       | —       | Called when the approver asks the host application to remember the decision. Not expressible in JSON Schema; see the component types for the signature.  |
+
+<!-- generated:props:end -->
+
+## CSS Variables
+
+<!-- generated:variables:start -->
+
+This component does not declare any local CSS variables.
+
+<!-- generated:variables:end -->
+
+## Subcomponents
+
+<!-- generated:subcomponents:start -->
+
+None.
+
+<!-- generated:subcomponents:end -->

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

@@ -0,0 +1,24 @@
+import type { ApprovalState } from './approval-card.types.ts';
+
+export function resolveEffectiveApprovalState(
+  approvalState: ApprovalState,
+  expirationTimestamp: number | undefined,
+  currentTime: number | undefined,
+): ApprovalState {
+  if (approvalState !== 'pending' || expirationTimestamp === undefined) return approvalState;
+  return resolveComparisonTime(currentTime) >= expirationTimestamp ? 'expired' : approvalState;
+}
+
+export function isApprovalActionable(
+  approvalState: ApprovalState,
+  expirationTimestamp: number | undefined,
+  currentTime: number | undefined,
+): boolean {
+  if (approvalState !== 'pending') return false;
+  if (expirationTimestamp === undefined) return true;
+  return resolveComparisonTime(currentTime) < expirationTimestamp;
+}
+
+function resolveComparisonTime(currentTime: number | undefined): number {
+  return currentTime ?? Date.now();
+}