@lostgradient/cinder 0.1.0

package/src/components/selection-popover/selection-popover.examples.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "selection-popover",
+  "import": "@lostgradient/cinder/selection-popover",
+  "examples": [
+    {
+      "id": "basic",
+      "title": "Selection-driven comment popover",
+      "description": "Highlight text in the passage below to trigger the popover at the selection anchor. Position is viewport-relative geometry derived from the selected range.",
+      "code": "<script lang=\"ts\">\n  import { onMount } from 'svelte';\n  import type { SelectionPopoverPosition } from '@lostgradient/cinder/selection-popover';\n  import { SelectionPopover } from '@lostgradient/cinder/selection-popover';\n\n  type Comment = { id: string; body: string };\n\n  const popoverId = 'basic-selection-popover';\n  let isOpen = $state(false);\n  let position = $state<SelectionPopoverPosition | null>(null);\n  let comments = $state<Comment[]>([]);\n\n  /**\n   * A bound reference to the text surface element.\n   * Used in the document-level selectionchange handler to scope\n   * selection detection to this element's subtree.\n   */\n  let surfaceElement = $state<HTMLElement | null>(null);\n\n  /**\n   * Compute a viewport-relative anchor from the current Selection.\n   * Returns null when there is no non-collapsed selection inside the surface.\n   */\n  function getSelectionAnchor(surface: HTMLElement): SelectionPopoverPosition | null {\n    const selection = window.getSelection();\n    if (!selection || selection.isCollapsed || selection.rangeCount === 0) return null;\n\n    const range = selection.getRangeAt(0);\n    if (!surface.contains(range.commonAncestorContainer)) return null;\n\n    const rect =\n      Array.from(range.getClientRects()).find((clientRect) => {\n        return clientRect.width > 0 && clientRect.height > 0;\n      }) ?? range.getBoundingClientRect();\n\n    if (rect.width === 0 && rect.height === 0) return null;\n\n    return {\n      x: rect.left + rect.width / 2,\n      y: rect.top,\n    };\n  }\n\n  /**\n   * `selectionchange` fires on document, not on elements.\n   * Register at document level and scope to the surface via\n   * the bound surfaceElement reference.\n   *\n   * Guard: when the selection collapses because the user clicked inside the\n   * popover (e.g. the \"Add comment\" button or the textarea), do NOT close the\n   * popover mid-interaction.  Two checks mirror the production review-editor\n   * pattern:\n   *\n   *   1. Focus containment — document.activeElement is inside the popover root.\n   *      Covers the common case and all non-Safari browsers.\n   *\n   *   2. data-cinder-expanded attribute — the SelectionPopover component sets\n   *      this on its root element while the comment form is open.  Safari does\n   *      not move focus to buttons on click, so the focus check alone would\n   *      miss that case.\n   */\n  onMount(() => {\n    function handleSelectionChange(): void {\n      if (!surfaceElement) return;\n\n      // Don't close the popover while the user is interacting with it.\n      const popoverElement = document.getElementById(popoverId);\n      if (popoverElement?.contains(document.activeElement)) return;\n      if (popoverElement?.hasAttribute('data-cinder-expanded')) return;\n\n      const anchor = getSelectionAnchor(surfaceElement);\n      if (anchor) {\n        position = anchor;\n        isOpen = true;\n      } else {\n        isOpen = false;\n        position = null;\n      }\n    }\n\n    document.addEventListener('selectionchange', handleSelectionChange);\n    return () => document.removeEventListener('selectionchange', handleSelectionChange);\n  });\n\n  function handleClose(): void {\n    isOpen = false;\n    position = null;\n  }\n\n  function addComment(body: string): void {\n    comments = [...comments, { id: crypto.randomUUID(), body }];\n    handleClose();\n  }\n</script>\n\n<article\n  bind:this={surfaceElement}\n  style=\"max-width: 36rem; line-height: 1.6; user-select: text; cursor: text;\"\n>\n  <p style=\"margin: 0 0 0.75rem;\">\n    The <strong>SelectionPopover</strong> appears near highlighted text — its\n    <code>position</code> prop takes viewport-relative coordinates derived from\n    <code>Range.getClientRects()</code>, not local container offsets. Select any portion of this\n    paragraph to see it appear near your selection.\n  </p>\n  <p style=\"margin: 0;\">\n    Clicking the comment icon expands the composer. Submit with the send button or\n    <kbd>Cmd</kbd>/<kbd>Ctrl</kbd>+<kbd>Enter</kbd>. Clicking outside the popover closes it and\n    resets the popover state.\n  </p>\n</article>\n\n<SelectionPopover\n  id={popoverId}\n  open={isOpen}\n  {position}\n  onclose={handleClose}\n  oncommentsubmit={addComment}\n/>\n\n{#if comments.length > 0}\n  <section style=\"margin: 1rem 0 0;\" aria-label=\"Submitted comments\">\n    <h3\n      style=\"margin: 0 0 0.5rem; font-size: var(--cinder-text-xs); font-weight: var(--cinder-font-medium); color: var(--cinder-text-muted); text-transform: uppercase; letter-spacing: 0.04em;\"\n    >\n      Submitted comments\n    </h3>\n    {#each comments as comment (comment.id)}\n      <article\n        style=\"padding: 0.5rem 0.75rem; margin-bottom: 0.375rem; border: 1px solid var(--cinder-border-muted); border-radius: var(--cinder-radius-sm); background: var(--cinder-surface);\"\n      >\n        {comment.body}\n      </article>\n    {/each}\n  </section>\n{/if}\n"
+    },
+    {
+      "id": "existing-comments",
+      "title": "Existing commented selections",
+      "description": "Shows persistent comment highlights as consumer-owned markup while SelectionPopover handles new text selections.",
+      "code": "<script lang=\"ts\">\n  import { onMount } from 'svelte';\n  import type { SelectionPopoverPosition } from '@lostgradient/cinder/selection-popover';\n  import { SelectionPopover } from '@lostgradient/cinder/selection-popover';\n\n  type ExistingComment = {\n    id: string;\n    quote: string;\n    body: string;\n  };\n\n  type SubmittedComment = { id: string; body: string };\n\n  const popoverId = 'existing-comments-selection-popover';\n  const activeCommentPanelId = 'existing-comment-panel';\n  const existingComments: ExistingComment[] = [\n    {\n      id: 'existing-comment-platform',\n      quote: 'platform review workflow',\n      body: 'This phrase already has a persisted comment. The highlight is rendered by the consumer.',\n    },\n    {\n      id: 'existing-comment-anchors',\n      quote: 'anchored selections visible',\n      body: 'ReviewEditor uses commentary anchor decorations for the full editor-backed version.',\n    },\n  ];\n\n  let surfaceElement = $state<HTMLElement | null>(null);\n  let activeCommentId = $state(existingComments[0]?.id ?? null);\n  let isOpen = $state(false);\n  let position = $state<SelectionPopoverPosition | null>(null);\n  let submittedComments = $state<SubmittedComment[]>([]);\n\n  const activeComment = $derived(\n    existingComments.find((comment) => comment.id === activeCommentId) ?? null,\n  );\n  const layoutStyle =\n    'display: flex; flex-wrap: wrap; gap: var(--cinder-space-4); align-items: flex-start;';\n  const surfaceStyle =\n    'flex: 1 1 24rem; min-width: min(100%, 20rem); max-width: 36rem; line-height: 1.6; user-select: text; cursor: text;';\n  const paragraphStyle = 'margin: 0 0 var(--cinder-space-3);';\n  const anchorBaseStyle =\n    'border-radius: var(--cinder-radius-sm); color: inherit; text-decoration-color: var(--cinder-accent); text-decoration-thickness: 0.1em; text-underline-offset: 0.15em; cursor: pointer;';\n  const panelStyle =\n    'flex: 1 1 14rem; max-width: 18rem; padding: var(--cinder-space-3); border: 1px solid var(--cinder-border-muted); border-radius: var(--cinder-radius-md); background: var(--cinder-surface);';\n  const headingStyle =\n    'margin: 0 0 var(--cinder-space-2); font-size: var(--cinder-text-sm); font-weight: var(--cinder-font-medium);';\n  const bodyStyle =\n    'margin: 0; color: var(--cinder-text-muted); font-size: var(--cinder-text-sm); line-height: 1.5;';\n  const submittedStyle = `${panelStyle} max-width: 36rem; margin-top: var(--cinder-space-3);`;\n\n  function getAnchorStyle(active: boolean): string {\n    const background = active\n      ? 'background: color-mix(in oklch, var(--cinder-accent), transparent 72%); outline: 1px solid color-mix(in oklch, var(--cinder-accent), transparent 32%);'\n      : 'background: color-mix(in oklch, var(--cinder-accent), transparent 84%);';\n    return `${anchorBaseStyle} ${background}`;\n  }\n\n  function getSelectionAnchor(surface: HTMLElement): SelectionPopoverPosition | null {\n    const selection = window.getSelection();\n    if (!selection || selection.isCollapsed || selection.rangeCount === 0) return null;\n\n    const range = selection.getRangeAt(0);\n    if (!surface.contains(range.commonAncestorContainer)) return null;\n\n    const rect =\n      Array.from(range.getClientRects()).find((clientRect) => {\n        return clientRect.width > 0 && clientRect.height > 0;\n      }) ?? range.getBoundingClientRect();\n\n    if (rect.width === 0 && rect.height === 0) return null;\n\n    return {\n      x: rect.left + rect.width / 2,\n      y: rect.top,\n    };\n  }\n\n  onMount(() => {\n    function handleSelectionChange(): void {\n      if (!surfaceElement) return;\n\n      const popoverElement = document.getElementById(popoverId);\n      if (popoverElement?.contains(document.activeElement)) return;\n      if (popoverElement?.hasAttribute('data-cinder-expanded')) return;\n\n      const anchor = getSelectionAnchor(surfaceElement);\n      if (anchor) {\n        position = anchor;\n        isOpen = true;\n      } else {\n        position = null;\n        isOpen = false;\n      }\n    }\n\n    document.addEventListener('selectionchange', handleSelectionChange);\n    return () => document.removeEventListener('selectionchange', handleSelectionChange);\n  });\n\n  function openExistingComment(event: MouseEvent, commentId: string): void {\n    event.preventDefault();\n    activeCommentId = commentId;\n    isOpen = false;\n    position = null;\n  }\n\n  function handleExistingCommentKeydown(event: KeyboardEvent, commentId: string): void {\n    if (event.key !== ' ') return;\n    event.preventDefault();\n    activeCommentId = commentId;\n    isOpen = false;\n    position = null;\n  }\n\n  function handleClose(): void {\n    isOpen = false;\n    position = null;\n  }\n\n  function addComment(body: string): void {\n    submittedComments = [...submittedComments, { id: crypto.randomUUID(), body }];\n    handleClose();\n  }\n</script>\n\n<div style={layoutStyle}>\n  <article bind:this={surfaceElement} style={surfaceStyle}>\n    <p style={paragraphStyle}>\n      Consumers can keep the\n      <a\n        href=\"#existing-comment-platform\"\n        data-testid=\"existing-comment-anchor\"\n        data-active={activeCommentId === 'existing-comment-platform'}\n        aria-current={activeCommentId === 'existing-comment-platform' ? 'true' : undefined}\n        aria-controls={activeCommentPanelId}\n        style={getAnchorStyle(activeCommentId === 'existing-comment-platform')}\n        onclick={(event) => openExistingComment(event, 'existing-comment-platform')}\n        onkeydown={(event) => handleExistingCommentKeydown(event, 'existing-comment-platform')}\n      >\n        platform review workflow\n      </a>\n      visibly connected to saved comments while still using SelectionPopover for brand-new selections.\n    </p>\n\n    <p style={paragraphStyle}>\n      For editor-backed documents, ReviewEditor and commentary anchor decorations keep\n      <a\n        href=\"#existing-comment-anchors\"\n        data-testid=\"existing-comment-anchor\"\n        data-active={activeCommentId === 'existing-comment-anchors'}\n        aria-current={activeCommentId === 'existing-comment-anchors' ? 'true' : undefined}\n        aria-controls={activeCommentPanelId}\n        style={getAnchorStyle(activeCommentId === 'existing-comment-anchors')}\n        onclick={(event) => openExistingComment(event, 'existing-comment-anchors')}\n        onkeydown={(event) => handleExistingCommentKeydown(event, 'existing-comment-anchors')}\n      >\n        anchored selections visible\n      </a>\n      as the document changes. Select any unhighlighted text in this example to add a new note.\n    </p>\n  </article>\n\n  <aside id={activeCommentPanelId} style={panelStyle} aria-live=\"polite\">\n    {#if activeComment}\n      <h4 id={activeComment.id} style={headingStyle}>{activeComment.quote}</h4>\n      <p style={bodyStyle}>{activeComment.body}</p>\n    {/if}\n  </aside>\n</div>\n\n<SelectionPopover\n  id={popoverId}\n  open={isOpen}\n  {position}\n  onclose={handleClose}\n  oncommentsubmit={addComment}\n/>\n\n{#if submittedComments.length > 0}\n  <section style={submittedStyle} aria-label=\"New comments\">\n    <h4 style={headingStyle}>New comments</h4>\n    {#each submittedComments as comment (comment.id)}\n      <p style={bodyStyle}>{comment.body}</p>\n    {/each}\n  </section>\n{/if}\n"
+    },
+    {
+      "id": "keyboard",
+      "title": "Keyboard submit after selection",
+      "description": "Select text (by mouse or keyboard) to open the composer, then press Cmd+Enter or Ctrl+Enter to submit. The composer collapses back to the icon — the popover does not stay expanded.",
+      "code": "<script lang=\"ts\">\n  import { onMount } from 'svelte';\n  import type { SelectionPopoverPosition } from '@lostgradient/cinder/selection-popover';\n  import { SelectionPopover } from '@lostgradient/cinder/selection-popover';\n\n  const popoverId = 'keyboard-selection-popover';\n  let isOpen = $state(false);\n  let position = $state<SelectionPopoverPosition | null>(null);\n  let lastSubmitted = $state<string | null>(null);\n\n  /**\n   * A bound reference to the text surface element.\n   * Used in the document-level selectionchange handler to scope\n   * selection detection to this element's subtree.\n   */\n  let surfaceElement = $state<HTMLElement | null>(null);\n\n  function getSelectionAnchor(surface: HTMLElement): SelectionPopoverPosition | null {\n    const selection = window.getSelection();\n    if (!selection || selection.isCollapsed || selection.rangeCount === 0) return null;\n\n    const range = selection.getRangeAt(0);\n    if (!surface.contains(range.commonAncestorContainer)) return null;\n\n    const rect =\n      Array.from(range.getClientRects()).find((clientRect) => {\n        return clientRect.width > 0 && clientRect.height > 0;\n      }) ?? range.getBoundingClientRect();\n\n    if (rect.width === 0 && rect.height === 0) return null;\n\n    return {\n      x: rect.left + rect.width / 2,\n      y: rect.top,\n    };\n  }\n\n  /**\n   * `selectionchange` fires on document, not on elements.\n   * Register at document level and scope to the surface via\n   * the bound surfaceElement reference.\n   *\n   * Keyboard selection (Shift+Arrow, Shift+Home, Shift+End, etc.) fires\n   * selectionchange just like mouse-driven selection — so keyboard users\n   * get the same popover trigger without any extra wiring.\n   *\n   * Guard: when the selection collapses because the user clicked inside the\n   * popover (e.g. the \"Add comment\" button or the textarea), do NOT close the\n   * popover mid-interaction.  Two checks mirror the production review-editor\n   * pattern:\n   *\n   *   1. Focus containment — document.activeElement is inside the popover root.\n   *      Covers the common case and all non-Safari browsers.\n   *\n   *   2. data-cinder-expanded attribute — the SelectionPopover component sets\n   *      this on its root element while the comment form is open.  Safari does\n   *      not move focus to buttons on click, so the focus check alone would\n   *      miss that case.\n   */\n  onMount(() => {\n    function handleSelectionChange(): void {\n      if (!surfaceElement) return;\n\n      // Don't close the popover while the user is interacting with it.\n      const popoverElement = document.getElementById(popoverId);\n      if (popoverElement?.contains(document.activeElement)) return;\n      if (popoverElement?.hasAttribute('data-cinder-expanded')) return;\n\n      const anchor = getSelectionAnchor(surfaceElement);\n      if (anchor) {\n        position = anchor;\n        isOpen = true;\n      } else {\n        isOpen = false;\n        position = null;\n      }\n    }\n\n    document.addEventListener('selectionchange', handleSelectionChange);\n    return () => document.removeEventListener('selectionchange', handleSelectionChange);\n  });\n\n  function handleClose(): void {\n    isOpen = false;\n    position = null;\n  }\n\n  function recordComment(body: string): void {\n    lastSubmitted = body;\n    handleClose();\n  }\n</script>\n\n<article\n  bind:this={surfaceElement}\n  style=\"max-width: 36rem; line-height: 1.6; user-select: text; cursor: text;\"\n>\n  <p style=\"margin: 0;\">\n    Select text in this paragraph to open the comment popover — both mouse drag and keyboard\n    selection (hold <kbd>Shift</kbd> while pressing arrow keys, <kbd>Home</kbd>, or <kbd>End</kbd>)\n    trigger the popover. Click the comment icon to expand the composer, type a note, then press\n    <kbd>Cmd</kbd>+<kbd>Enter</kbd> (macOS) or <kbd>Ctrl</kbd>+<kbd>Enter</kbd> (Windows/Linux) to submit.\n    The composer collapses back to the icon after submission — the popover does not stay expanded.\n  </p>\n</article>\n\n<SelectionPopover\n  id={popoverId}\n  open={isOpen}\n  {position}\n  onclose={handleClose}\n  oncommentsubmit={recordComment}\n/>\n\n{#if lastSubmitted}\n  <section style=\"margin: 1rem 0 0;\" aria-label=\"Last submitted\">\n    <h3\n      style=\"margin: 0 0 0.5rem; font-size: var(--cinder-text-xs); font-weight: var(--cinder-font-medium); color: var(--cinder-text-muted); text-transform: uppercase; letter-spacing: 0.04em;\"\n    >\n      Last submitted\n    </h3>\n    <article\n      style=\"padding: 0.5rem 0.75rem; border: 1px solid var(--cinder-border-muted); border-radius: var(--cinder-radius-sm); background: var(--cinder-surface);\"\n    >\n      {lastSubmitted}\n    </article>\n  </section>\n{/if}\n"
+    },
+    {
+      "id": "null-position",
+      "title": "Null position clears the popover",
+      "description": "Setting position to null hides the popover even while open is true — the consumer can clear an active selection without changing the open flag.",
+      "code": "<script lang=\"ts\">\n  import type { SelectionPopoverPosition } from '@lostgradient/cinder/selection-popover';\n  import { Button } from '@lostgradient/cinder/button';\n  import { SelectionPopover } from '@lostgradient/cinder/selection-popover';\n\n  const popoverId = 'null-position-selection-popover';\n\n  /**\n   * A fixed anchor used to demonstrate the null-clear behavior without requiring\n   * a real text selection in this example. The coordinates are viewport-relative,\n   * consistent with how a real selection anchor would be computed.\n   */\n  const demonstrationPosition: SelectionPopoverPosition = { x: 220, y: 220 };\n\n  let isOpen = $state(false);\n  let position = $state<SelectionPopoverPosition | null>(null);\n\n  function showPopover(): void {\n    position = demonstrationPosition;\n    isOpen = true;\n  }\n\n  function clearPosition(): void {\n    position = null;\n    // open stays true — the component should hide because position is null.\n  }\n\n  function restorePosition(): void {\n    position = demonstrationPosition;\n  }\n</script>\n\n<div style=\"max-width: 36rem;\">\n  <p style=\"margin: 0 0 0.75rem; line-height: 1.5;\">\n    Demonstrates that setting <code>position</code> to <code>null</code> hides the popover even when\n    <code>open</code>\n    remains <code>true</code>. Click <em>Show popover</em> to open it, then use\n    <em>Clear position</em>\n    to set <code>position=null</code> while leaving\n    <code>open=true</code> — the popover disappears because the component has no anchor point to\n    position against. Use <em>Restore position</em> to bring it back without changing\n    <code>open</code>.\n  </p>\n\n  <div style=\"display: flex; gap: 0.5rem; flex-wrap: wrap; margin-bottom: 0.75rem;\">\n    <Button label=\"Show popover\" onclick={showPopover} />\n    <Button label=\"Clear position (set null)\" onclick={clearPosition} disabled={!isOpen} />\n    <Button label=\"Restore position\" onclick={restorePosition} disabled={!isOpen} />\n  </div>\n\n  <p style=\"margin: 0; font-size: var(--cinder-text-sm); color: var(--cinder-text-muted);\">\n    Status: open={isOpen}, position={position ? `{x:${position.x},y:${position.y}}` : 'null'}\n  </p>\n</div>\n\n<SelectionPopover id={popoverId} open={isOpen} {position} />\n"
+    },
+    {
+      "id": "toggled",
+      "title": "Toggled by an external trigger",
+      "description": "A button outside the popover drives open. When the consumer clicks outside the popover, the component invokes onclose and the consumer flips open back to false.",
+      "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import type { SelectionPopoverPosition } from '@lostgradient/cinder/selection-popover';\n  import { SelectionPopover } from '@lostgradient/cinder/selection-popover';\n\n  const popoverId = 'toggled-selection-popover';\n  let isOpen = $state(false);\n  let position = $state<SelectionPopoverPosition | null>(null);\n  let lastSubmitted = $state<string | null>(null);\n  let anchorElement = $state<HTMLElement | null>(null);\n\n  function openPopover(): void {\n    if (!anchorElement) return;\n\n    const rect = anchorElement.getBoundingClientRect();\n    position = {\n      x: rect.left + rect.width / 2,\n      y: rect.top,\n    };\n    isOpen = true;\n  }\n\n  function handleClose(): void {\n    isOpen = false;\n    position = null;\n  }\n\n  function handleSubmit(body: string): void {\n    lastSubmitted = body;\n    handleClose();\n  }\n</script>\n\n<div style=\"max-width: 36rem;\">\n  <p style=\"margin: 0 0 0.75rem; line-height: 1.5;\">\n    Click the button to open the popover at a visible marked phrase. Click anywhere outside the\n    popover and it closes — the component fires <code>onclose</code> and the consumer flips\n    <code>open</code> back to <code>false</code>. The <code>position</code> prop here is derived from\n    the marked phrase's viewport rectangle.\n  </p>\n\n  <p style=\"margin: 0 0 0.75rem; line-height: 1.5;\">\n    The comment action anchors to\n    <mark\n      bind:this={anchorElement}\n      data-testid=\"external-trigger-anchor\"\n      style=\"border-radius: var(--cinder-radius-sm); background: color-mix(in oklch, var(--cinder-accent), transparent 84%); color: var(--cinder-text); padding: 0 0.125rem;\"\n    >\n      this visible phrase\n    </mark>\n    rather than a hard-coded viewport coordinate.\n  </p>\n\n  <Button\n    label=\"Open popover\"\n    aria-expanded={isOpen}\n    aria-controls={popoverId}\n    disabled={isOpen}\n    onclick={openPopover}\n  />\n</div>\n\n<SelectionPopover\n  id={popoverId}\n  open={isOpen}\n  {position}\n  onclose={handleClose}\n  oncommentsubmit={handleSubmit}\n/>\n\n{#if lastSubmitted}\n  <section style=\"margin: 1rem 0 0;\" aria-label=\"Last submitted\">\n    <h3\n      style=\"margin: 0 0 0.5rem; font-size: var(--cinder-text-xs); font-weight: var(--cinder-font-medium); color: var(--cinder-text-muted); text-transform: uppercase; letter-spacing: 0.04em;\"\n    >\n      Last submitted\n    </h3>\n    <article\n      style=\"padding: 0.5rem 0.75rem; border: 1px solid var(--cinder-border-muted); border-radius: var(--cinder-radius-sm); background: var(--cinder-surface);\"\n    >\n      {lastSubmitted}\n    </article>\n  </section>\n{/if}\n"
+    },
+    {
+      "id": "viewport-clamping",
+      "title": "Viewport edge handling",
+      "description": "Shows that out-of-bounds selection anchors are shifted or flipped back inside the viewport.",
+      "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { SelectionPopover } from '@lostgradient/cinder/selection-popover';\n\n  let showClamping = $state(false);\n</script>\n\n<div style=\"max-width: 36rem;\">\n  <p style=\"margin: 0 0 0.75rem; line-height: 1.5;\">\n    The component shifts or flips around any requested <code>position</code> anchor near the viewport\n    edge, so a consumer can pass raw selection geometry without guards against off-screen placements.\n    The test cases below use deliberately out-of-bounds anchor coordinates.\n  </p>\n\n  <Button\n    label={showClamping ? 'Hide clamping test popovers' : 'Show clamping test popovers'}\n    aria-expanded={showClamping}\n    onclick={() => {\n      showClamping = !showClamping;\n    }}\n  />\n\n  {#if showClamping}\n    <p\n      style=\"margin: 0.75rem 0 0; font-size: var(--cinder-text-sm); color: var(--cinder-text-muted);\"\n    >\n      All three popovers below were requested from out-of-bounds anchors. Visually confirm each one\n      is inside the viewport edges — this is a human-eyeball check, not a CI assertion.\n    </p>\n  {/if}\n</div>\n\n<SelectionPopover\n  id=\"viewport-clamp-negative-x\"\n  open={showClamping}\n  position={{ x: -100, y: 300 }}\n/>\n<SelectionPopover\n  id=\"viewport-clamp-overflow-x\"\n  open={showClamping}\n  position={{ x: 99999, y: 340 }}\n/>\n<SelectionPopover\n  id=\"viewport-clamp-negative-y\"\n  open={showClamping}\n  position={{ x: 480, y: -50 }}\n/>\n"
+    }
+  ]
+}

package/src/components/selection-popover/selection-popover.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Unique identifier for the popover."
+    },
+    "open": {
+      "type": "boolean",
+      "description": "Whether the popover is visible."
+    },
+    "class": {
+      "type": "string",
+      "description": "Additional class names merged with `.cinder-selection-popover`."
+    }
+  },
+  "additionalProperties": false,
+  "required": ["id"],
+  "metadata": {
+    "unsupportedProps": [
+      {
+        "name": "oncancel",
+        "reason": "function-or-snippet"
+      },
+      {
+        "name": "onclose",
+        "reason": "function-or-snippet"
+      },
+      {
+        "name": "oncommentsubmit",
+        "reason": "function-or-snippet"
+      },
+      {
+        "name": "onexpand",
+        "reason": "function-or-snippet"
+      },
+      {
+        "name": "position",
+        "reason": "unknown-shape"
+      }
+    ]
+  }
+}

package/src/components/selection-popover/selection-popover.schema.ts

@@ -0,0 +1,48 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Unique identifier for the popover.',
+    },
+    open: {
+      type: 'boolean',
+      description: 'Whether the popover is visible.',
+    },
+    class: {
+      type: 'string',
+      description: 'Additional class names merged with `.cinder-selection-popover`.',
+    },
+  },
+  additionalProperties: false,
+  required: ['id'],
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'oncancel',
+        reason: 'function-or-snippet',
+      },
+      {
+        name: 'onclose',
+        reason: 'function-or-snippet',
+      },
+      {
+        name: 'oncommentsubmit',
+        reason: 'function-or-snippet',
+      },
+      {
+        name: 'onexpand',
+        reason: 'function-or-snippet',
+      },
+      {
+        name: 'position',
+        reason: 'unknown-shape',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

package/src/components/selection-popover/selection-popover.svelte

@@ -0,0 +1,266 @@
+<script lang="ts" module>
+  /**
+   * @cinder
+   * @category overlay
+   * @status stable
+   * @purpose Floating toolbar anchored to a text selection that exposes a comment-on-selection action with an inline composer.
+   * @tag overlay
+   * @tag selection
+   * @useWhen Letting readers annotate or comment on a highlighted range of text in a document or article surface.
+   * @useWhen Surfacing selection-scoped actions such as quote, share, or comment near the user's pointer.
+   * @avoidWhen Anchoring generic non-selection content to a trigger — use popover.
+   * @avoidWhen Building a general-purpose floating toolbar unrelated to text selection — compose a popover with custom controls.
+   * @related popover
+   */
+  export type {
+    SelectionPopoverPosition,
+    SelectionPopoverProps,
+  } from './selection-popover.types.ts';
+</script>
+
+<script lang="ts">
+  import type { Placement, VirtualElement } from '@floating-ui/dom';
+  import type { SelectionPopoverProps } from './selection-popover.types.ts';
+  import { tick } from 'svelte';
+
+  import { createAnchoredOverlay } from '../../_internal/anchored-overlay.svelte.ts';
+  import { createClickOutside } from '../../utilities/attachments.ts';
+  import { classNames } from '../../utilities/class-names.ts';
+  import { createPortalAttachment } from '../portal/index.ts';
+
+  let {
+    id,
+    position,
+    open = false,
+    oncommentsubmit,
+    onexpand,
+    oncancel,
+    onclose,
+    class: customClassName,
+    ...rest
+  }: SelectionPopoverProps = $props();
+
+  let expanded = $state(false);
+  let commentBody = $state('');
+  let textareaElement = $state<HTMLTextAreaElement | null>(null);
+  let popoverElement = $state<HTMLDivElement | null>(null);
+  let restoreFocusElement: HTMLElement | null = null;
+  let wasOpen = false;
+
+  const virtualAnchor = $derived.by<VirtualElement | null>(() => {
+    if (!position) return null;
+
+    return {
+      getBoundingClientRect: () =>
+        ({
+          x: position.x,
+          y: position.y,
+          top: position.y,
+          left: position.x,
+          right: position.x,
+          bottom: position.y,
+          width: 0,
+          height: 0,
+        }) as DOMRect,
+    };
+  });
+
+  const isPositionedOpen = $derived(open && position != null);
+
+  const anchoredOverlay = createAnchoredOverlay({
+    open: () => isPositionedOpen,
+    anchor: () => virtualAnchor,
+    panel: () => popoverElement,
+    placement: () => 'top' as Placement,
+    offset: () => 8,
+    shiftPadding: () => 16,
+    shiftCrossAxis: () => true,
+    widthMode: () => 'none',
+  });
+  const portalAttachment = createPortalAttachment({
+    target: () => document.body,
+    inheritAttributes: true,
+  });
+
+  const canSubmit = $derived(commentBody.trim().length > 0);
+
+  function rememberFocus(): void {
+    if (restoreFocusElement) return;
+    const activeElement = document.activeElement;
+    restoreFocusElement = activeElement instanceof HTMLElement ? activeElement : null;
+  }
+
+  function restoreFocus(): void {
+    restoreFocusElement?.focus();
+    restoreFocusElement = null;
+  }
+
+  function closePopover(): void {
+    onclose?.();
+    restoreFocus();
+  }
+
+  function handleExpand(): void {
+    rememberFocus();
+    expanded = true;
+    onexpand?.();
+    // tick() resolves once Svelte flushes the expanded state to the DOM (so the
+    // textarea exists), aligned with the codebase's flush timing — faster and
+    // more idiomatic than waiting a paint frame via requestAnimationFrame.
+    void tick().then(() => textareaElement?.focus());
+  }
+
+  function handleCancel(): void {
+    expanded = false;
+    commentBody = '';
+    oncancel?.();
+    restoreFocus();
+  }
+
+  function handleSubmit(): void {
+    const trimmedBody = commentBody.trim();
+    if (!trimmedBody) return;
+
+    oncommentsubmit?.(trimmedBody);
+    expanded = false;
+    commentBody = '';
+    restoreFocus();
+  }
+
+  function handleKeydown(event: KeyboardEvent): void {
+    if (event.key === 'Escape' && !event.defaultPrevented) {
+      event.preventDefault();
+      if (expanded) {
+        handleCancel();
+      } else {
+        closePopover();
+      }
+      return;
+    }
+
+    if ((event.key === 'Enter' || event.key === ' ') && !expanded && !event.defaultPrevented) {
+      event.preventDefault();
+      handleExpand();
+    }
+  }
+
+  function handleTextareaKeydown(event: KeyboardEvent): void {
+    if (event.key === 'Enter' && (event.metaKey || event.ctrlKey)) {
+      event.preventDefault();
+      handleSubmit();
+    }
+  }
+
+  // Outside-pointerdown dismiss via the shared overlay primitive (OVERLAY-POLICY § Outside-click).
+  // pointerdown (not click) so the popover closes before a fresh text selection commits.
+  // $derived keeps the attachment stable across renders (recreating it would re-bind the
+  // document listener every update); enabled gates it to the open state.
+  const dismissOnOutsidePointerdown = $derived(
+    // capture: false preserves the original bubble-phase semantics
+    // (the previous document.addEventListener call had no capture arg).
+    createClickOutside({
+      handler: closePopover,
+      enabled: () => isPositionedOpen,
+      eventType: 'pointerdown',
+      capture: false,
+    }),
+  );
+
+  $effect(() => {
+    if (!isPositionedOpen) {
+      // Only act on the true -> false transition. This keeps the close logic
+      // (state reset + focus restore) from re-running on unrelated effect
+      // re-evaluations while already closed.
+      if (wasOpen) {
+        wasOpen = false;
+        expanded = false;
+        commentBody = '';
+        // Return focus to wherever it was before the popover opened.
+        // restoreFocus() null-guards and clears the ref, so an internal close
+        // that already restored leaves this a safe no-op (no double-restore).
+        restoreFocus();
+      }
+      return;
+    }
+
+    // Capture the pre-open focus owner once, on the false -> true transition,
+    // before focus can move into the popover. This guarantees something to
+    // restore to on an external close even if the popover is never expanded,
+    // while never re-capturing mid-open (which would otherwise re-grab focus
+    // after an internal close-and-restore left the popover open).
+    if (!wasOpen) {
+      wasOpen = true;
+      rememberFocus();
+    }
+  });
+</script>
+
+<div
+  bind:this={popoverElement}
+  {id}
+  class={classNames('cinder-selection-popover', customClassName)}
+  data-cinder-expanded={expanded ? '' : undefined}
+  data-cinder-position-ready={anchoredOverlay.positionReady}
+  data-cinder-placement={anchoredOverlay.resolvedPlacement}
+  style={anchoredOverlay.positionStyle}
+  role="toolbar"
+  aria-label="Selection actions"
+  onkeydown={handleKeydown}
+  {@attach portalAttachment}
+  {@attach dismissOnOutsidePointerdown}
+  {...rest}
+>
+  {#if expanded}
+    <div class="cinder-selection-popover__form">
+      <textarea
+        bind:this={textareaElement}
+        bind:value={commentBody}
+        class="cinder-selection-popover__textarea"
+        aria-label="Comment text"
+        placeholder="Add a comment..."
+        rows={2}
+        onkeydown={handleTextareaKeydown}
+      ></textarea>
+      <div class="cinder-selection-popover__actions">
+        <button
+          type="button"
+          class="cinder-selection-popover__cancel"
+          onclick={handleCancel}
+          aria-label="Cancel"
+        >
+          <svg class="cinder-selection-popover__icon" aria-hidden="true" viewBox="0 0 24 24">
+            <path d="M18 6 6 18" />
+            <path d="m6 6 12 12" />
+          </svg>
+        </button>
+        <button
+          type="button"
+          class="cinder-selection-popover__submit"
+          onclick={handleSubmit}
+          disabled={!canSubmit}
+          aria-label="Submit comment"
+          title="Submit comment"
+        >
+          <svg class="cinder-selection-popover__icon" aria-hidden="true" viewBox="0 0 24 24">
+            <path d="m22 2-7 20-4-9-9-4Z" />
+            <path d="M22 2 11 13" />
+          </svg>
+        </button>
+      </div>
+    </div>
+  {:else}
+    <button
+      type="button"
+      class="cinder-selection-popover__button"
+      onclick={handleExpand}
+      aria-label="Add comment"
+      title="Add comment to selection"
+    >
+      <svg class="cinder-selection-popover__icon" aria-hidden="true" viewBox="0 0 24 24">
+        <path d="M21 15a4 4 0 0 1-4 4H7l-4 4V7a4 4 0 0 1 4-4h6" />
+        <path d="M19 3v6" />
+        <path d="M16 6h6" />
+      </svg>
+    </button>
+  {/if}
+</div>

package/src/components/selection-popover/selection-popover.types.ts

@@ -0,0 +1,23 @@
+import type { HTMLAttributes } from 'svelte/elements';
+export type SelectionPopoverPosition = {
+  x: number;
+  y: number;
+};
+export type SelectionPopoverProps = Omit<HTMLAttributes<HTMLDivElement>, 'class'> & {
+  /** Unique identifier for the popover. */
+  id: string;
+  /** Viewport-relative anchor point for the popover. */
+  position: SelectionPopoverPosition | null;
+  /** Whether the popover is visible. */
+  open?: boolean;
+  /** Called when a comment is submitted. */
+  oncommentsubmit?: (body: string) => void;
+  /** Called when the compact action expands into the composer. */
+  onexpand?: () => void;
+  /** Called when the composer is canceled. */
+  oncancel?: () => void;
+  /** Called when the popover should close. */
+  onclose?: () => void;
+  /** Additional class names merged with `.cinder-selection-popover`. */
+  class?: string;
+};

package/src/components/selection-popover/selection-popover.variables.json

@@ -0,0 +1 @@
+[]

package/src/components/selection-popover/selection-popover.variables.ts

@@ -0,0 +1,3 @@
+const variables: readonly string[] = [];
+
+export default variables;

package/src/components/sheet/README.md

@@ -0,0 +1,62 @@
+# Sheet
+
+Bottom-anchored overlay panel optimised for mobile-style drawer interactions.
+
+## When to use
+
+- 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
+
+- 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.
+
+## Related components
+
+- [`Drawer`](../drawer/README.md) — side-anchored overlay for desktop-first supplementary content.
+- [`Modal`](../modal/README.md) — blocking full-attention overlay.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import Sheet from '@lostgradient/cinder/sheet';
+</script>
+
+<Sheet />
+```
+
+## Props
+
+<!-- generated:props:start -->
+
+| Prop             | Type       | Required | Default | Description                                                                                                                                                                                                                                                                                                                      |
+| ---------------- | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ariaLabelledBy` | `string`   | no       | —       | Optional id of an element that names the sheet. When supplied, sheet wires `aria-labelledby` to this id and renders no internal heading. Use this when a custom `header` snippet has its own visible heading — supply `ariaLabelledBy` pointing to that heading's id so the visible and accessible names stay in sync.           |
+| `class`          | `string`   | no       | —       | Additional class names merged with `.cinder-sheet`.                                                                                                                                                                                                                                                                              |
+| `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.                                                                                                                                                                                                                          |
+
+<!-- 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/sheet/index.ts

@@ -0,0 +1,6 @@
+import './sheet.css';
+import Sheet from './sheet.svelte';
+
+export default Sheet;
+export type { SheetProps } from './sheet.types.ts';
+export { Sheet };