@lostgradient/cinder 0.5.0 → 0.7.0

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

@@ -0,0 +1,88 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Optional panel id. Defaults to a generated `cinder-popover-*` id."
+    },
+    "open": {
+      "type": "boolean",
+      "description": "Open state. Bindable. Default `false`."
+    },
+    "placement": {
+      "enum": [
+        "top",
+        "bottom",
+        "left",
+        "right",
+        "top-start",
+        "top-end",
+        "bottom-start",
+        "bottom-end"
+      ],
+      "description": "Anchor placement. Default `'bottom-start'`."
+    },
+    "offset": {
+      "type": "number",
+      "description": "Distance in px between trigger and panel. Default `8`."
+    },
+    "showArrow": {
+      "type": "boolean",
+      "description": "Render a directional arrow on the panel. Default `false`."
+    },
+    "label": {
+      "type": "string",
+      "description": "Accessible name. Sets `aria-label` when `ariaLabelledby` is not supplied."
+    },
+    "ariaLabelledby": {
+      "type": "string",
+      "description": "Id of an element labelling the panel. Wins over `label`."
+    },
+    "role": {
+      "enum": ["dialog", "group", "listbox"],
+      "description": "ARIA role for the panel. Default `'dialog'`."
+    },
+    "focusManagement": {
+      "enum": ["panel", "preserve"],
+      "description": "Focus behavior for each open session. Default `'panel'`."
+    },
+    "wireTriggerAria": {
+      "type": "boolean",
+      "description": "Whether Popover owns trigger ARIA wiring. Default `true`."
+    },
+    "closeOnEscape": {
+      "type": "boolean",
+      "description": "Whether Escape closes the Popover. Default `true`. Set `false` when a parent\ncomposite widget (e.g. Combobox) owns Escape for the whole interaction, so the\nPopover does not shadow the parent's handler while its panel is open."
+    },
+    "widthMode": {
+      "enum": ["content", "match-anchor", "menu", "none"],
+      "description": "Floating panel width strategy. Default `'content'`."
+    },
+    "class": {
+      "type": "string",
+      "description": "Extra class merged onto `.cinder-popover`."
+    }
+  },
+  "additionalProperties": false,
+  "metadata": {
+    "unsupportedProps": [
+      {
+        "name": "children",
+        "reason": "function-or-snippet",
+        "required": true,
+        "description": "Panel content. Required."
+      },
+      {
+        "name": "trigger",
+        "reason": "function-or-snippet",
+        "description": "Optional trigger snippet rendered inside a wrapper."
+      },
+      {
+        "name": "triggerRef",
+        "reason": "unknown-shape",
+        "description": "Explicit anchor element. Wins over the snippet-resolved focusable."
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,93 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Optional panel id. Defaults to a generated `cinder-popover-*` id.',
+    },
+    open: {
+      type: 'boolean',
+      description: 'Open state. Bindable. Default `false`.',
+    },
+    placement: {
+      enum: [
+        'top',
+        'bottom',
+        'left',
+        'right',
+        'top-start',
+        'top-end',
+        'bottom-start',
+        'bottom-end',
+      ],
+      description: "Anchor placement. Default `'bottom-start'`.",
+    },
+    offset: {
+      type: 'number',
+      description: 'Distance in px between trigger and panel. Default `8`.',
+    },
+    showArrow: {
+      type: 'boolean',
+      description: 'Render a directional arrow on the panel. Default `false`.',
+    },
+    label: {
+      type: 'string',
+      description: 'Accessible name. Sets `aria-label` when `ariaLabelledby` is not supplied.',
+    },
+    ariaLabelledby: {
+      type: 'string',
+      description: 'Id of an element labelling the panel. Wins over `label`.',
+    },
+    role: {
+      enum: ['dialog', 'group', 'listbox'],
+      description: "ARIA role for the panel. Default `'dialog'`.",
+    },
+    focusManagement: {
+      enum: ['panel', 'preserve'],
+      description: "Focus behavior for each open session. Default `'panel'`.",
+    },
+    wireTriggerAria: {
+      type: 'boolean',
+      description: 'Whether Popover owns trigger ARIA wiring. Default `true`.',
+    },
+    closeOnEscape: {
+      type: 'boolean',
+      description:
+        "Whether Escape closes the Popover. Default `true`. Set `false` when a parent\ncomposite widget (e.g. Combobox) owns Escape for the whole interaction, so the\nPopover does not shadow the parent's handler while its panel is open.",
+    },
+    widthMode: {
+      enum: ['content', 'match-anchor', 'menu', 'none'],
+      description: "Floating panel width strategy. Default `'content'`.",
+    },
+    class: {
+      type: 'string',
+      description: 'Extra class merged onto `.cinder-popover`.',
+    },
+  },
+  additionalProperties: false,
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'children',
+        reason: 'function-or-snippet',
+        required: true,
+        description: 'Panel content. Required.',
+      },
+      {
+        name: 'trigger',
+        reason: 'function-or-snippet',
+        description: 'Optional trigger snippet rendered inside a wrapper.',
+      },
+      {
+        name: 'triggerRef',
+        reason: 'unknown-shape',
+        description: 'Explicit anchor element. Wins over the snippet-resolved focusable.',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

package/src/components/popover/popover.svelte

@@ -1,161 +1,108 @@
 <script lang="ts" module>
-  /**
-   * @cinder
-   * @category overlay
-   * @status stable
-   * @purpose Anchored floating panel positioned by Floating UI that hosts non-modal contextual content beside a trigger element.
-   * @tag overlay
-   * @tag floating
-   * @useWhen Showing rich, interactive contextual content anchored to a trigger such as a help panel, color picker, or listbox surface.
-   * @useWhen Presenting non-blocking supplementary controls that should dismiss on outside click or Escape.
-   * @avoidWhen Showing a short descriptive hint on hover or focus — use tooltip instead.
-   * @avoidWhen Interrupting the user for a focused task — use modal, drawer, or sheet so the surface is modal.
-   * @related modal, drawer, sheet, tooltip
-   */
-  export type {
-    PopoverFocusManagement,
-    PopoverPlacement,
-    PopoverProps,
-    PopoverRole,
-    PopoverWidthMode,
-  } from './popover.types.ts';
+export {};
 </script>
 
 <script lang="ts">
-  import type { PopoverProps } from './popover.types.ts';
-  import { onDestroy, untrack } from 'svelte';
-  import type { Placement } from '@floating-ui/dom';
-  import { createAnchoredOverlay } from '../../_internal/anchored-overlay.svelte.ts';
-  import { captureFocus, pushEscapeHandler } from '../../_internal/overlay.ts';
-  import { devWarn } from '../../utilities/dev-warn.ts';
-  import { classNames } from '../../utilities/class-names.ts';
-  import { restoreFocusTo } from '../../utilities/focus.ts';
-  import { createClickOutside } from '../../utilities/attachments.ts';
-  import { createPortalAttachment } from '../portal/index.ts';
-
-  let {
-    id: panelIdProp,
-    open = $bindable(false),
-    placement = 'bottom-start',
-    offset = 8,
-    showArrow = false,
-    label,
-    ariaLabelledby,
-    triggerRef = null,
-    trigger,
-    children,
-    role = 'dialog',
-    focusManagement = 'panel',
-    wireTriggerAria = true,
-    closeOnEscape = true,
-    widthMode = 'content',
-    class: className,
-  }: PopoverProps = $props();
-
-  const FOCUSABLE_SELECTOR =
-    'button:not([disabled]), a[href], [tabindex]:not([tabindex="-1"]), input:not([disabled]), select:not([disabled]), textarea:not([disabled])';
-
-  function findFirstFocusable(container: HTMLElement | undefined | null): HTMLElement | null {
-    if (!container) return null;
-    const candidates = container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR);
+import { onDestroy, untrack } from 'svelte';
+import { createAnchoredOverlay } from '../../_internal/anchored-overlay.svelte.ts';
+import { captureFocus, pushEscapeHandler } from '../../_internal/overlay.ts';
+import { devWarn } from '../../utilities/dev-warn.ts';
+import { classNames } from '../../utilities/class-names.ts';
+import { restoreFocusTo } from '../../utilities/focus.ts';
+import { createClickOutside } from '../../utilities/attachments.ts';
+import { createPortalAttachment } from '../portal/index.ts';
+let { id: panelIdProp, open = $bindable(false), placement = 'bottom-start', offset = 8, showArrow = false, label, ariaLabelledby, triggerRef = null, trigger, children, role = 'dialog', focusManagement = 'panel', wireTriggerAria = true, closeOnEscape = true, widthMode = 'content', class: className, } = $props();
+const FOCUSABLE_SELECTOR = 'button:not([disabled]), a[href], [tabindex]:not([tabindex="-1"]), input:not([disabled]), select:not([disabled]), textarea:not([disabled])';
+function findFirstFocusable(container) {
+    if (!container)
+        return null;
+    const candidates = container.querySelectorAll(FOCUSABLE_SELECTOR);
     for (const el of candidates) {
-      if (el.closest('[hidden], [inert], [aria-hidden="true"]')) continue;
-      return el;
+        if (el.closest('[hidden], [inert], [aria-hidden="true"]'))
+            continue;
+        return el;
     }
     return null;
-  }
-
-  let triggerWrapper: HTMLDivElement | undefined = $state();
-  let panelElement: HTMLDivElement | undefined = $state();
-  let arrowElement: HTMLSpanElement | undefined = $state();
-
-  const generatedPanelId = $props.id();
-  const panelId = $derived(panelIdProp ?? generatedPanelId);
-
-  // `triggerRef.isConnected` is a native DOM read, not a reactive source: this
-  // derived only re-evaluates when the triggerRef prop reference changes, not when
-  // the same element is detached/re-attached without a prop change. That edge is
-  // not supported — pass a fresh ref (or toggle it) to re-resolve the anchor.
-  const anchorElement = $derived<HTMLElement | null>(
-    triggerRef && triggerRef.isConnected
-      ? triggerRef
-      : (findFirstFocusable(triggerWrapper) ?? null),
-  );
-  const resolvedAriaLabel = $derived(
-    ariaLabelledby ? undefined : role === 'dialog' ? (label ?? 'Popover') : label,
-  );
-
-  // mounted gates the panel render so SSR emits empty markup regardless of
-  // open. See _internal/OVERLAY-POLICY.md ("SSR rule").
-  let mounted = $state(false);
-  let capturedFocus: HTMLElement | null = null;
-  let resolvedAnchorAtOpen: HTMLElement | null = null;
-  let pendingInitialFocus = $state(false);
-  let openSessionFocusManagement = $state<'panel' | 'preserve'>('panel');
-
-  let isDestroyed = false;
-  onDestroy(() => {
+}
+let triggerWrapper = $state();
+let panelElement = $state();
+let arrowElement = $state();
+const generatedPanelId = $props.id();
+const panelId = $derived(panelIdProp ?? generatedPanelId);
+// `triggerRef.isConnected` is a native DOM read, not a reactive source: this
+// derived only re-evaluates when the triggerRef prop reference changes, not when
+// the same element is detached/re-attached without a prop change. That edge is
+// not supported — pass a fresh ref (or toggle it) to re-resolve the anchor.
+const anchorElement = $derived(triggerRef && triggerRef.isConnected
+    ? triggerRef
+    : (findFirstFocusable(triggerWrapper) ?? null));
+const resolvedAriaLabel = $derived(ariaLabelledby ? undefined : role === 'dialog' ? (label ?? 'Popover') : label);
+// mounted gates the panel render so SSR emits empty markup regardless of
+// open. See _internal/OVERLAY-POLICY.md ("SSR rule").
+let mounted = $state(false);
+let capturedFocus = null;
+let resolvedAnchorAtOpen = null;
+let pendingInitialFocus = $state(false);
+let openSessionFocusManagement = $state('panel');
+let isDestroyed = false;
+onDestroy(() => {
     isDestroyed = true;
-  });
-
-  const portalAttachment = createPortalAttachment({
+});
+const portalAttachment = createPortalAttachment({
     target: () => document.body,
     inheritAttributes: true,
     source: () => anchorElement ?? null,
-  });
-
-  const anchoredOverlay = createAnchoredOverlay({
+});
+const anchoredOverlay = createAnchoredOverlay({
     open: () => open,
     anchor: () => anchorElement,
     panel: () => panelElement,
     arrow: () => arrowElement,
-    placement: () => placement as Placement,
+    placement: () => placement,
     offset: () => offset,
     showArrow: () => showArrow,
     widthMode: () => widthMode,
-  });
-
-  $effect(() => {
+});
+$effect(() => {
     mounted = true;
-  });
-
-  const dismissOnOutsideMousedown = $derived(
-    createClickOutside({
-      handler: () => {
+});
+const dismissOnOutsideMousedown = $derived(createClickOutside({
+    handler: () => {
         open = false;
-      },
-      enabled: () => open,
-      eventType: 'mousedown',
-      capture: true,
-      // Use the open-time snapshot so a swapped/removed trigger does not cause
-      // unexpected close when the user mouses down on the original opener.
-      ignoreRefs: [() => resolvedAnchorAtOpen ?? null],
-    }),
-  );
-
-  function moveFocusIntoPanel() {
-    if (isDestroyed || !panelElement) return;
+    },
+    enabled: () => open,
+    eventType: 'mousedown',
+    capture: true,
+    // Use the open-time snapshot so a swapped/removed trigger does not cause
+    // unexpected close when the user mouses down on the original opener.
+    ignoreRefs: [() => resolvedAnchorAtOpen ?? null],
+}));
+function moveFocusIntoPanel() {
+    if (isDestroyed || !panelElement)
+        return;
     const focusable = findFirstFocusable(panelElement);
     (focusable ?? panelElement).focus();
-  }
-
-  // Effect: open lifecycle (captures focus, registers Escape + outside-mousedown).
-  // Gated on anchorElement so a no-anchor open session does not push onto the
-  // shared escape stack or steal mousedowns from other visible overlays — the
-  // panel itself won't render without an anchor.
-  $effect(() => {
-    if (!open) return;
-    if (!anchorElement) return;
+}
+// Effect: open lifecycle (captures focus, registers Escape + outside-mousedown).
+// Gated on anchorElement so a no-anchor open session does not push onto the
+// shared escape stack or steal mousedowns from other visible overlays — the
+// panel itself won't render without an anchor.
+$effect(() => {
+    if (!open)
+        return;
+    if (!anchorElement)
+        return;
     // Snapshot focusManagement at open time. untrack so a consumer changing the
     // prop while open (even via a parent re-render) does not tear down and re-run
     // this effect — matching the resolvedAnchorAtOpen snapshot below.
     openSessionFocusManagement = untrack(() => focusManagement);
     if (openSessionFocusManagement === 'panel') {
-      capturedFocus = captureFocus();
-      pendingInitialFocus = true;
-    } else {
-      capturedFocus = null;
-      pendingInitialFocus = false;
+        capturedFocus = captureFocus();
+        pendingInitialFocus = true;
+    }
+    else {
+        capturedFocus = null;
+        pendingInitialFocus = false;
     }
     // Snapshot the anchor at open time. untrack so anchor/trigger changes while
     // open don't retrigger this effect; positioning rebind is the positioning
@@ -166,111 +113,109 @@
     // Popover on top of the shared stack and shadow the parent's handler while
     // options are visible.
     const releaseEscape = closeOnEscape
-      ? pushEscapeHandler(() => {
-          open = false;
+        ? pushEscapeHandler(() => {
+            open = false;
         })
-      : () => {};
-
+        : () => { };
     return () => {
-      releaseEscape();
-      pendingInitialFocus = false;
-      if (isDestroyed) {
+        releaseEscape();
+        pendingInitialFocus = false;
+        if (isDestroyed) {
+            capturedFocus = null;
+            resolvedAnchorAtOpen = null;
+            return;
+        }
+        if (openSessionFocusManagement === 'panel') {
+            // Preserve the 3-candidate priority order; the shared helper enforces
+            // the per-candidate connection/ownership check so we no longer need
+            // the inline `.isConnected` guards.
+            const candidates = [
+                triggerRef,
+                resolvedAnchorAtOpen,
+                capturedFocus,
+            ];
+            for (const candidate of candidates) {
+                if (restoreFocusTo(candidate))
+                    break;
+            }
+        }
         capturedFocus = null;
         resolvedAnchorAtOpen = null;
-        return;
-      }
-      if (openSessionFocusManagement === 'panel') {
-        // Preserve the 3-candidate priority order; the shared helper enforces
-        // the per-candidate connection/ownership check so we no longer need
-        // the inline `.isConnected` guards.
-        const candidates: Array<HTMLElement | null> = [
-          triggerRef,
-          resolvedAnchorAtOpen,
-          capturedFocus,
-        ];
-        for (const candidate of candidates) {
-          if (restoreFocusTo(candidate)) break;
-        }
-      }
-      capturedFocus = null;
-      resolvedAnchorAtOpen = null;
     };
-  });
-
-  // Effect: state-driven initial-focus move. Fires once per open session when
-  // the panel mounts, the anchor resolves, and positioning is ready — so focus
-  // never lands in invisible content.
-  $effect(() => {
-    if (isDestroyed) return;
-    if (openSessionFocusManagement !== 'panel') return;
-    if (
-      !open ||
-      !panelElement ||
-      !anchorElement ||
-      !anchoredOverlay.positionReady ||
-      !pendingInitialFocus
-    ) {
-      return;
+});
+// Effect: state-driven initial-focus move. Fires once per open session when
+// the panel mounts, the anchor resolves, and positioning is ready — so focus
+// never lands in invisible content.
+$effect(() => {
+    if (isDestroyed)
+        return;
+    if (openSessionFocusManagement !== 'panel')
+        return;
+    if (!open ||
+        !panelElement ||
+        !anchorElement ||
+        !anchoredOverlay.positionReady ||
+        !pendingInitialFocus) {
+        return;
     }
     moveFocusIntoPanel();
     pendingInitialFocus = false;
-  });
-
-  // Effect: dev-only guidance warnings. Single effect, fires on each open
-  // transition; the cost of repeat warnings is acceptable for dev mode.
-  $effect(() => {
-    if (!open) return;
+});
+// Effect: dev-only guidance warnings. Single effect, fires on each open
+// transition; the cost of repeat warnings is acceptable for dev mode.
+$effect(() => {
+    if (!open)
+        return;
     if (!anchorElement) {
-      devWarn(
-        '[cinder/popover] open without a trigger anchor. ' +
-          'Provide either a `trigger` snippet with a focusable child or a `triggerRef`.',
-      );
+        devWarn('[cinder/popover] open without a trigger anchor. ' +
+            'Provide either a `trigger` snippet with a focusable child or a `triggerRef`.');
     }
     if (role === 'dialog' && !label && !ariaLabelledby) {
-      devWarn(
-        '[cinder/popover] role="dialog" without `label` or `ariaLabelledby` falls back to ' +
-          'aria-label="Popover". Pass a descriptive name for production usage.',
-      );
+        devWarn('[cinder/popover] role="dialog" without `label` or `ariaLabelledby` falls back to ' +
+            'aria-label="Popover". Pass a descriptive name for production usage.');
     }
     if (role === 'listbox' && wireTriggerAria) {
-      devWarn(
-        '[cinder/popover] role="listbox" only sets the surface role. ' +
-          'You must render role="option" children and own selection/keyboard semantics. ' +
-          'See popover.a11y.md §Role.',
-      );
+        devWarn('[cinder/popover] role="listbox" only sets the surface role. ' +
+            'You must render role="option" children and own selection/keyboard semantics. ' +
+            'See popover.a11y.md §Role.');
     }
-  });
-
-  // Effect: trigger ARIA wiring. Captures pre-existing values and restores on
-  // teardown so consumers can manage their own attributes through changes.
-  $effect(() => {
-    if (!wireTriggerAria) return;
+});
+// Effect: trigger ARIA wiring. Captures pre-existing values and restores on
+// teardown so consumers can manage their own attributes through changes.
+$effect(() => {
+    if (!wireTriggerAria)
+        return;
     const target = anchorElement;
-    if (!target) return;
+    if (!target)
+        return;
     const prior = {
-      expanded: target.getAttribute('aria-expanded'),
-      controls: target.getAttribute('aria-controls'),
-      haspopup: target.getAttribute('aria-haspopup'),
+        expanded: target.getAttribute('aria-expanded'),
+        controls: target.getAttribute('aria-controls'),
+        haspopup: target.getAttribute('aria-haspopup'),
     };
-
     target.setAttribute('aria-expanded', String(open));
     const mappedHaspopup = role === 'group' ? null : role === 'listbox' ? 'listbox' : 'dialog';
-    if (mappedHaspopup) target.setAttribute('aria-haspopup', mappedHaspopup);
-    else target.removeAttribute('aria-haspopup');
-    if (open) target.setAttribute('aria-controls', panelId);
-    else target.removeAttribute('aria-controls');
-
+    if (mappedHaspopup)
+        target.setAttribute('aria-haspopup', mappedHaspopup);
+    else
+        target.removeAttribute('aria-haspopup');
+    if (open)
+        target.setAttribute('aria-controls', panelId);
+    else
+        target.removeAttribute('aria-controls');
     return () => {
-      for (const [name, value] of Object.entries({
-        'aria-expanded': prior.expanded,
-        'aria-controls': prior.controls,
-        'aria-haspopup': prior.haspopup,
-      })) {
-        if (value === null) target.removeAttribute(name);
-        else target.setAttribute(name, value);
-      }
+        for (const [name, value] of Object.entries({
+            'aria-expanded': prior.expanded,
+            'aria-controls': prior.controls,
+            'aria-haspopup': prior.haspopup,
+        })) {
+            if (value === null)
+                target.removeAttribute(name);
+            else
+                target.setAttribute(name, value);
+        }
     };
-  });
+});
 </script>
 
 {#if trigger}

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

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

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

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

package/src/components/portal/portal.schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "target": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "CSS selector string or `null` specifying where the portal content is appended. Defaults to `document.body` when `null` or omitted."
+    },
+    "disabled": {
+      "type": "boolean",
+      "description": "When true, renders the content inline in normal document flow instead of teleporting it to the target."
+    },
+    "class": {
+      "type": "string",
+      "description": "Additional class applied to the portal wrapper element."
+    },
+    "inheritAttributes": {
+      "type": "boolean",
+      "description": "When true (default), HTML attributes passed to the portal are forwarded onto the wrapper element inside the target."
+    }
+  },
+  "additionalProperties": false,
+  "metadata": {
+    "unsupportedProps": [
+      {
+        "name": "children",
+        "reason": "function-or-snippet",
+        "required": true
+      }
+    ]
+  }
+}