@lostgradient/cinder 0.1.1 → 0.3.0

package/src/components/share-card/share-card.svelte

@@ -0,0 +1,348 @@
+<script lang="ts" module>
+  /**
+   * @cinder
+   * @category action
+   * @status alpha
+   * @purpose Compact share card with copy-link, copy-text, and native navigator.share actions, with accessible success announcements and graceful fallback when navigator.share is unavailable.
+   * @tag action
+   * @tag clipboard
+   * @useWhen Offering a quick way to share a link or text with copy and native share options.
+   * @useWhen Presenting a result, invite link, or exported report link with sharing affordances.
+   * @avoidWhen Generating the share text or images — compose ShareCard with your own copy generation logic.
+   * @avoidWhen Posting directly to social media or analytics — wire those externally.
+   * @related copy-button, card, button
+   */
+  export type { ShareCardAction, ShareCardProps } from './share-card.types.ts';
+</script>
+
+<script lang="ts">
+  import { onDestroy } from 'svelte';
+
+  import { classNames } from '../../utilities/class-names.ts';
+  import { copyToClipboard } from '../../utilities/clipboard.ts';
+  import VisuallyHiddenLiveRegion from '../_visually-hidden-live-region.svelte';
+  import type { ShareCardAction, ShareCardProps } from './share-card.types.ts';
+
+  let {
+    value,
+    title,
+    description,
+    actions,
+    copyLinkLabel = 'Copy link',
+    copiedLabel = 'Copied!',
+    shareLabel = 'Share',
+    confirmDuration = 2000,
+    preview,
+    class: customClassName,
+    ...rest
+  }: ShareCardProps = $props();
+
+  // Track which action is in the "copied" state by its key.
+  let copiedKey = $state<string | null>(null);
+  let resetTimer: ReturnType<typeof setTimeout> | undefined;
+  let announcement = $state('');
+
+  // Hydration gate. The native-share button depends on `navigator.share`, which
+  // only exists in the browser — but gating it on a plain browser check would
+  // make the client's first render add a button the server never emitted,
+  // producing a hydration mismatch. `$effect` runs only on the client, AFTER
+  // hydration, so the server render and the initial client render both omit the
+  // button; it appears on the next tick once `hydrated` flips. Matches the
+  // toast-region / drawer hydration-gate convention.
+  let hydrated = $state(false);
+  $effect(() => {
+    hydrated = true;
+  });
+
+  // Detect native share support. Gated on `hydrated` (not a bare browser flag)
+  // so it is always `false` during SSR and the initial hydration render.
+  const canNativeShare = $derived(
+    hydrated && typeof navigator !== 'undefined' && typeof navigator.share === 'function',
+  );
+
+  let announceTimer: ReturnType<typeof setTimeout> | undefined;
+
+  // Clear BOTH transient timers — the copied-state reset AND any pending
+  // announcement auto-clear — so a new copy/share cycle never has a stale timer
+  // from a previous cycle mutating the current state out from under it.
+  function clearTimer() {
+    if (resetTimer !== undefined) {
+      clearTimeout(resetTimer);
+      resetTimer = undefined;
+    }
+    if (announceTimer !== undefined) {
+      clearTimeout(announceTimer);
+      announceTimer = undefined;
+    }
+  }
+
+  // Set a transient announcement that auto-clears to '' after the confirmation
+  // window, so a stale message isn't left in the live region and the NEXT
+  // announcement (even an identical one) re-fires because the prop transitions
+  // through ''. A single write — the live region (VisuallyHiddenLiveRegion) owns
+  // the blank-then-set re-announce timing, matching copy-button / media-controls.
+  function announce(message: string) {
+    if (announceTimer !== undefined) clearTimeout(announceTimer);
+    announcement = message;
+    announceTimer = setTimeout(() => {
+      announcement = '';
+    }, confirmDuration);
+  }
+
+  async function handleCopy(key: string, text: string, successMessage = copiedLabel) {
+    let succeeded = false;
+    try {
+      succeeded = await copyToClipboard(text);
+    } catch {
+      succeeded = false;
+    }
+    if (!succeeded) {
+      // Clear any lingering "copied" state from a previous success so a failed
+      // attempt doesn't leave a button stuck showing the copied label. Route the
+      // failure through announce() so it auto-clears and a second identical
+      // failure re-announces (the live region only fires on a change).
+      clearTimer();
+      copiedKey = null;
+      announce('Copy failed');
+      return;
+    }
+    clearTimer();
+    copiedKey = key;
+    // The success message is overridable so a fallback copy (after a failed
+    // native share) announces the full story rather than overwriting the
+    // "Share failed" notice with a bare "Copied!". announce() owns the message
+    // lifecycle; resetTimer owns only the copied visual state.
+    announce(successMessage);
+    resetTimer = setTimeout(() => {
+      copiedKey = null;
+    }, confirmDuration);
+  }
+
+  // Heuristic: an absolute http(s) URL shares as `url`, anything else as `text`.
+  function looksLikeUrl(candidate: string): boolean {
+    return /^https?:\/\//i.test(candidate.trim());
+  }
+
+  function buildShareData(): ShareData {
+    const shareData: ShareData = looksLikeUrl(value) ? { url: value } : { text: value };
+    if (title) shareData.title = title;
+    return shareData;
+  }
+
+  async function handleNativeShare() {
+    if (!canNativeShare) {
+      // Native share unavailable — fall back to copying the value.
+      await handleCopy('share-fallback', value);
+      return;
+    }
+    const shareData = buildShareData();
+    // Respect navigator.canShare when present so an unsupported payload falls
+    // back to copy instead of rejecting.
+    if (typeof navigator.canShare === 'function' && !navigator.canShare(shareData)) {
+      await handleCopy('share-fallback', value);
+      return;
+    }
+    try {
+      await navigator.share(shareData);
+      announce('Shared successfully');
+    } catch (error) {
+      // A user-cancelled share rejects with AbortError — NOT a failure, stay
+      // silent. Every other rejection (NotAllowedError, TypeError, platform
+      // failure) is real: announce it and fall back to copy so the value is
+      // never lost.
+      if (error instanceof DOMException && error.name === 'AbortError') return;
+      // Announce the full outcome on the fallback copy so the "share failed"
+      // notice isn't overwritten by a bare "Copied!".
+      await handleCopy('share-fallback', value, 'Share failed. Copied to clipboard instead.');
+    }
+  }
+
+  // Accessible label for the read-only value region — "Link to share" only when
+  // the value actually looks like a URL, otherwise "Text to share".
+  const valueRegionLabel = $derived(looksLikeUrl(value) ? 'Link to share' : 'Text to share');
+
+  onDestroy(() => {
+    // clearTimer() clears BOTH resetTimer and announceTimer.
+    clearTimer();
+  });
+
+  // The action list: explicit `actions` verbatim, else the copy-link default.
+  // The default native-share button is NOT in this array — it is rendered by a
+  // standalone `{#if !actions && canNativeShare}` in the template. `canNativeShare`
+  // only flips true after hydration (it is gated on the `hydrated` $effect), and
+  // when the native-share action was instead appended to this reactive array
+  // post-hydration, the keyed `{#each}` did not render it. The standalone `{#if}`
+  // (matching the drawer/sheet hydration convention) renders reliably on the flip.
+  const defaultActions: ShareCardAction[] = $derived([
+    {
+      key: 'copy-link',
+      label: copyLinkLabel,
+      copyValue: value,
+    },
+  ]);
+  const resolvedActions = $derived(actions ?? defaultActions);
+</script>
+
+<div {...rest} class={classNames('cinder-share-card', customClassName)}>
+  {#if preview}
+    <div class="cinder-share-card__preview">
+      {@render preview()}
+    </div>
+  {/if}
+
+  {#if title || description}
+    <div class="cinder-share-card__meta">
+      {#if title}
+        <p class="cinder-share-card__title">{title}</p>
+      {/if}
+      {#if description}
+        <p class="cinder-share-card__description">{description}</p>
+      {/if}
+    </div>
+  {/if}
+
+  <!-- Value display: truncated read-only URL/text field -->
+  <div class="cinder-share-card__value" aria-label={valueRegionLabel}>
+    <span class="cinder-share-card__value-text" title={value}>{value}</span>
+  </div>
+
+  <div class="cinder-share-card__actions" role="group" aria-label="Share actions">
+    {#each resolvedActions as action (action.key)}
+      {#if action.key === 'native-share' || action.useNativeShare}
+        {@render shareButton(action)}
+      {:else}
+        {@render copyButton(action)}
+      {/if}
+    {/each}
+    <!-- The default native-share button is gated by a standalone `{#if}` rather
+         than pushed into `resolvedActions`, so it reconciles correctly when
+         `canNativeShare` flips from false to true after hydration. Only rendered
+         in the default surface (no explicit `actions`); a consumer-supplied
+         native-share action goes through the `{#each}` above. -->
+    {#if !actions && canNativeShare}
+      {@render shareButton({ key: 'native-share', label: shareLabel, useNativeShare: true })}
+    {/if}
+  </div>
+</div>
+
+<!-- Native-share button. Reflects the `share-fallback` copied state so that when
+     `handleNativeShare` falls back to a clipboard copy (native share unavailable
+     or failed) the visual matches the live-region announcement instead of staying
+     on the Share label. -->
+{#snippet shareButton(action: ShareCardAction)}
+  {@const shareCopied = copiedKey === 'share-fallback'}
+  <button
+    type="button"
+    class="cinder-share-card__action"
+    data-cinder-action={action.key}
+    data-cinder-copied={shareCopied ? '' : undefined}
+    onclick={() => {
+      // Honour a consumer onClick (analytics/side-effects) on the native share
+      // action too, then run the share. `void` marks the floating promise as
+      // intentional (the handler is synchronous).
+      action.onClick?.();
+      void handleNativeShare();
+    }}
+    aria-label={shareCopied ? copiedLabel : action.label}
+  >
+    {#if shareCopied}
+      <!-- Copied state icon (after a fallback copy) -->
+      <span class="cinder-share-card__action-icon" aria-hidden="true">
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          class="cinder-share-card__icon"
+        >
+          <polyline points="20,6 9,17 4,12" />
+        </svg>
+      </span>
+      {copiedLabel}
+    {:else}
+      <!-- Share icon -->
+      <span class="cinder-share-card__action-icon" aria-hidden="true">
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          class="cinder-share-card__icon"
+        >
+          <circle cx="18" cy="5" r="3" />
+          <circle cx="6" cy="12" r="3" />
+          <circle cx="18" cy="19" r="3" />
+          <line x1="8.59" y1="13.51" x2="15.42" y2="17.49" />
+          <line x1="15.41" y1="6.51" x2="8.59" y2="10.49" />
+        </svg>
+      </span>
+      {action.label}
+    {/if}
+  </button>
+{/snippet}
+
+<!-- Copy button. `onClick` is a side-effect callback (e.g. analytics), NOT an
+     override — it runs AND the copy still fires when `copyValue` is present. An
+     empty string is a legitimate copyValue, so test for `undefined`, not
+     truthiness. -->
+{#snippet copyButton(action: ShareCardAction)}
+  <button
+    type="button"
+    class="cinder-share-card__action"
+    data-cinder-action={action.key}
+    data-cinder-copied={copiedKey === action.key ? '' : undefined}
+    onclick={() => {
+      action.onClick?.();
+      if (action.copyValue !== undefined) {
+        void handleCopy(action.key, action.copyValue);
+      }
+    }}
+    aria-label={copiedKey === action.key ? copiedLabel : action.label}
+  >
+    {#if copiedKey === action.key}
+      <!-- Copied state icon -->
+      <span class="cinder-share-card__action-icon" aria-hidden="true">
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          class="cinder-share-card__icon"
+        >
+          <polyline points="20,6 9,17 4,12" />
+        </svg>
+      </span>
+      {copiedLabel}
+    {:else}
+      <!-- Copy icon -->
+      <span class="cinder-share-card__action-icon" aria-hidden="true">
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          class="cinder-share-card__icon"
+        >
+          <rect x="9" y="9" width="13" height="13" rx="2" ry="2" />
+          <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
+        </svg>
+      </span>
+      {action.label}
+    {/if}
+  </button>
+{/snippet}
+
+<!-- Announce copy/share outcomes to assistive technology. -->
+<VisuallyHiddenLiveRegion message={announcement} />

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

@@ -0,0 +1,69 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+
+/** An action to include in the share card. */
+export type ShareCardAction = {
+  /** Unique key for this action. */
+  key: string;
+  /** Visible label for the action button. */
+  label: string;
+  /** Text to copy when this action is triggered (used for copy-link/copy-text). */
+  copyValue?: string;
+  /** Called when this action button is clicked. */
+  onClick?: () => void;
+  /** Whether to use navigator.share for this action. */
+  useNativeShare?: boolean;
+};
+
+/** Props for the ShareCard component. */
+export type ShareCardProps = Omit<HTMLAttributes<HTMLDivElement>, 'class' | 'children'> & {
+  /** The URL or text to share/copy. */
+  value: string;
+  /** Human-readable title for the share card. */
+  title?: string;
+  /** Additional descriptive text below the title. */
+  description?: string;
+  /** Explicit actions to show. When omitted, default copy-link and native-share actions are rendered. */
+  actions?: ShareCardAction[];
+  /** Label for the copy-link button. @default "Copy link" */
+  copyLinkLabel?: string;
+  /** Label shown after a successful copy. @default "Copied!" */
+  copiedLabel?: string;
+  /** Label for the native-share button. Only shown when navigator.share is available. @default "Share" */
+  shareLabel?: string;
+  /** Duration in ms to show the copied confirmation state. @default 2000 */
+  confirmDuration?: number;
+  /** Preview content slot rendered above the actions. */
+  preview?: Snippet;
+  /** Additional class names merged with `.cinder-share-card`. */
+  class?: string;
+};
+
+/**
+ * Cinder-specific props for ShareCard, used by the schema generator.
+ */
+export interface ShareCardSchemaProps {
+  /** The URL or text to share/copy. */
+  value: string;
+  /** Human-readable title for the share card. */
+  title?: string;
+  /** Additional descriptive text. */
+  description?: string;
+  /** Label for the copy-link button. */
+  copyLinkLabel?: string;
+  /** Label shown after a successful copy. */
+  copiedLabel?: string;
+  /** Label for the native-share button. */
+  shareLabel?: string;
+  /**
+   * Duration in ms to show the copied confirmation state.
+   * @default 2000
+   */
+  confirmDuration?: number;
+  /** Additional class names merged with `.cinder-share-card`. */
+  class?: string;
+  /** Explicit actions to show. When omitted, default copy + native-share actions render. */
+  actions?: ShareCardAction[];
+  /** Preview content slot rendered above the actions. */
+  preview?: Snippet;
+}

package/src/components/sheet/README.md

@@ -2,12 +2,12 @@
 
 Bottom-anchored overlay panel optimised for mobile-style drawer interactions.
 
-## When to use
+## Choosing this component
 
 - Action sheets and option pickers on mobile or touch-first layouts where a bottom-up slide feels natural.
 - Quick-select panels (share, sort, filter) that need to feel native on small screens.
 
-## When not to use
+## Choosing something else
 
 - Desktop-first side panels — use [`Drawer`](../drawer/README.md) for left/right edge placement.
 - Full-attention blocking dialogs — use [`Modal`](../modal/README.md) when the user must act before continuing.
@@ -38,10 +38,10 @@ Bottom-anchored overlay panel optimised for mobile-style drawer interactions.
 | `open`           | `boolean`  | no       | —       | Whether the sheet is open. Bindable via `bind:open`.                                                                                                                                                                                                                                                                             |
 | `showDragHandle` | `boolean`  | no       | —       | When `true`, render a decorative drag handle above the header. Swipe-to-close gesture is a stretch goal not implemented in MVP — the handle is purely a visual affordance. Default `false`. Named `showDragHandle` (not `draggable`) to avoid colliding with the native HTML `draggable` attribute on the underlying `<dialog>`. |
 | `title`          | `string`   | yes      | —       | Accessible name for the sheet. Required for screen-reader labelling. Rendered as a visible `<h2>` in the default header. When a custom `header` snippet is provided without `ariaLabelledBy`, this text is rendered in a visually-hidden `<h2>` as the accessible name fallback.                                                 |
-| `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.                                                                                                                                                                                                       |
-| `footer`         | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                       |
-| `header`         | `(opaque)` | no       | —       | 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.                                                                                                                                                                                                                          |
+| `children`       | `(opaque)` | yes      | —       | Sheet body content. Required. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                         |
+| `footer`         | `(opaque)` | no       | —       | Optional footer (e.g. action buttons). Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                |
+| `header`         | `(opaque)` | no       | —       | Custom header. Falls back to a default header that renders `title`. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                   |
+| `triggerRef`     | `(opaque)` | no       | —       | Optional reference to the element that opened the sheet. When supplied, focus returns to this element on close. When omitted, focus restores to the element that held focus before the sheet opened. Not expressible in JSON Schema; see the component types for the signature.                                                  |
 
 <!-- generated:props:end -->
 

package/src/components/sheet/sheet.svelte

@@ -22,6 +22,7 @@
   import { captureFocus, lockBodyScroll, pushEscapeHandler } from '../../_internal/overlay.ts';
   import { waitForTransitionCompletion } from '../../_internal/transition-completion.ts';
   import { overflowFade } from '../../utilities/attachments.ts';
+  import { createFocusTrap } from '../focus-trap/index.ts';
   import { classNames } from '../../utilities/class-names.ts';
   import { restoreFocusTo } from '../../utilities/focus.ts';
   import { useReducedMotion } from '../../utilities/use-reduced-motion.svelte.ts';
@@ -246,6 +247,11 @@
         class="cinder-sheet__panel"
         data-cinder-closing={isClosing ? '' : undefined}
         inert={isClosing}
+        {@attach createFocusTrap({
+          active: () => open && !isClosing,
+          restoreFocus: false,
+          manageInitialFocus: false,
+        })}
       >
         {#if showDragHandle}
           <div class="cinder-sheet__drag-handle" aria-hidden="true">

package/src/components/shortcut-hint/README.md

@@ -0,0 +1,52 @@
+# ShortcutHint
+
+Inline shortcut hint that renders a key combo via Kbd alongside an action label, with an accessible text representation not reliant on visual keycaps alone.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { ShortcutHint } from '@lostgradient/cinder/shortcut-hint';
+</script>
+```
+
+## Guidance
+
+### Use When
+
+- Showing a keyboard shortcut inline beside a label in a toolbar button, menu item, or tooltip.
+- Pairing with command-palette items to surface available shortcuts.
+
+### Avoid When
+
+- Displaying a full shortcut reference table — use keyboard-shortcuts instead.
+
+## Props
+
+<!-- generated:props:start -->
+
+| Prop           | Type                    | Required | Default   | Description                                                                                                           |
+| -------------- | ----------------------- | -------- | --------- | --------------------------------------------------------------------------------------------------------------------- |
+| `class`        | `string`                | no       | —         | Additional class names merged with `.cinder-shortcut-hint`.                                                           |
+| `keys`         | `string`[]              | yes      | —         | The key sequence to display.                                                                                          |
+| `keysLabel`    | `string`                | no       | —         | Accessible label for the key combo.                                                                                   |
+| `keysPosition` | `"before"` \| `"after"` | no       | `"after"` | Position of keys relative to children.                                                                                |
+| `children`     | `(opaque)`              | no       | —         | The action label rendered beside the keys. 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/shortcut-hint/index.ts

@@ -0,0 +1,6 @@
+import './shortcut-hint.css';
+import ShortcutHint from './shortcut-hint.svelte';
+
+export default ShortcutHint;
+export type { ShortcutHintProps } from './shortcut-hint.types.ts';
+export { ShortcutHint };

package/src/components/shortcut-hint/shortcut-hint.css

@@ -0,0 +1,26 @@
+@layer cinder.tokens, cinder.foundation, cinder.components, cinder.utilities;
+@layer cinder.components {
+  .cinder-shortcut-hint {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--cinder-space-1);
+  }
+
+  .cinder-shortcut-hint__label {
+    color: var(--cinder-text);
+  }
+
+  .cinder-shortcut-hint__keys {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--cinder-space-1);
+    flex-shrink: 0;
+  }
+
+  .cinder-shortcut-hint__separator {
+    font-size: var(--cinder-text-xs);
+    color: var(--cinder-text-muted);
+    line-height: 1;
+    user-select: none;
+  }
+}

package/src/components/shortcut-hint/shortcut-hint.examples.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "shortcut-hint",
+  "import": "@lostgradient/cinder/shortcut-hint",
+  "examples": [
+    {
+      "id": "toolbar",
+      "title": "Toolbar shortcut hints",
+      "description": "Inline shortcut hints in a compact toolbar, keys positioned after the label.",
+      "code": "<script lang=\"ts\">\n  import { ShortcutHint } from '@lostgradient/cinder/shortcut-hint';\n</script>\n\n<div style=\"display: flex; gap: 0.75rem; align-items: center; flex-wrap: wrap;\">\n  <ShortcutHint keys={['Ctrl', 'S']}>Save</ShortcutHint>\n  <ShortcutHint keys={['Ctrl', 'Z']}>Undo</ShortcutHint>\n  <ShortcutHint keys={['Escape']}>Cancel</ShortcutHint>\n  <ShortcutHint keys={['Space']} keysLabel=\"Space bar\" keysPosition=\"before\">Play</ShortcutHint>\n</div>\n"
+    }
+  ]
+}

package/src/components/shortcut-hint/shortcut-hint.svelte

@@ -0,0 +1,62 @@
+<script lang="ts" module>
+  /**
+   * @cinder
+   * @category typography
+   * @status alpha
+   * @purpose Inline shortcut hint that renders a key combo via Kbd alongside an action label, with an accessible text representation not reliant on visual keycaps alone.
+   * @tag shortcut
+   * @tag inline
+   * @useWhen Showing a keyboard shortcut inline beside a label in a toolbar button, menu item, or tooltip.
+   * @useWhen Pairing with command-palette items to surface available shortcuts.
+   * @avoidWhen Displaying a full shortcut reference table — use keyboard-shortcuts instead.
+   * @related kbd, keyboard-shortcuts, tooltip
+   */
+  export type { ShortcutHintProps } from './shortcut-hint.types.ts';
+</script>
+
+<script lang="ts">
+  import { classNames } from '../../utilities/class-names.ts';
+  import Kbd from '../kbd/kbd.svelte';
+  import type { ShortcutHintProps } from './shortcut-hint.types.ts';
+
+  let {
+    keys,
+    keysLabel,
+    children,
+    keysPosition = 'after',
+    class: customClassName,
+    ...rest
+  }: ShortcutHintProps = $props();
+
+  /**
+   * Build a screen-reader–friendly label for the key combo.
+   */
+  const resolvedKeysLabel = $derived(keysLabel ?? keys.join(' plus '));
+</script>
+
+<!--
+  The visual keycaps are aria-hidden so assistive technology never encounters the
+  raw Kbd glyphs; the spoken representation is a single cinder-sr-only text node
+  ("Ctrl plus S") — a more reliable strategy than aria-label on a generic span.
+  Keycaps are inlined (not a {#snippet}) to avoid a Svelte 5 + happy-dom snippet
+  ordering quirk when a snippet is the first child of an {#if} branch.
+-->
+<span {...rest} class={classNames('cinder-shortcut-hint', customClassName)}>
+  {#if children && keysPosition === 'after'}
+    <span class="cinder-shortcut-hint__label">{@render children()}</span>
+  {/if}
+
+  <span class="cinder-shortcut-hint__keys" aria-hidden="true">
+    {#each keys as key, index (key + index)}
+      <Kbd label={key} size="sm" />
+      {#if index < keys.length - 1}
+        <span class="cinder-shortcut-hint__separator">+</span>
+      {/if}
+    {/each}
+  </span>
+  <span class="cinder-sr-only">{resolvedKeysLabel}</span>
+
+  {#if children && keysPosition === 'before'}
+    <span class="cinder-shortcut-hint__label">{@render children()}</span>
+  {/if}
+</span>

package/src/components/shortcut-hint/shortcut-hint.types.ts

@@ -0,0 +1,35 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+
+/** Props for the ShortcutHint component. */
+export type ShortcutHintProps = Omit<HTMLAttributes<HTMLSpanElement>, 'class' | 'children'> & {
+  /** The key sequence to display (e.g. ["Ctrl", "S"] or ["Space"]). */
+  keys: string[];
+  /** Optional accessible label for the key combo. Defaults to joining keys with " plus ". */
+  keysLabel?: string;
+  /** The action or label to render alongside the key combo. */
+  children?: Snippet;
+  /** Whether to place the keys before or after the children. @default "after" */
+  keysPosition?: 'before' | 'after';
+  /** Additional class names merged with `.cinder-shortcut-hint`. */
+  class?: string;
+};
+
+/**
+ * Cinder-specific props for ShortcutHint, used by the schema generator.
+ */
+export interface ShortcutHintSchemaProps {
+  /** The key sequence to display. */
+  keys: string[];
+  /** Accessible label for the key combo. */
+  keysLabel?: string;
+  /**
+   * Position of keys relative to children.
+   * @default "after"
+   */
+  keysPosition?: 'before' | 'after';
+  /** Additional class names merged with `.cinder-shortcut-hint`. */
+  class?: string;
+  /** The action label rendered beside the keys. */
+  children?: Snippet;
+}