@stnd/ui 0.5.0 → 0.5.1

package/Accordion.astro

@@ -1,17 +1,19 @@
 ---
 /**
- * Accordion.astro
+ * @component Accordion
+ * @description Zero-JS accordion container — ensures only one child
+ * `<details>` is open at a time via a plain click listener, no framework
+ * hydration required.
  *
- * Renders an accordion container that ensures only one child details is open at a time.
- *
- * Usage:
- *   <Accordion>
- *     <AccordionItem title="Item 1">Content</AccordionItem>
- *     <AccordionItem title="Item 2">Content</AccordionItem>
- *   </Accordion>
+ * @example astro
+ * <Accordion>
+ *   <AccordionItem title="Item 1">Content</AccordionItem>
+ *   <AccordionItem title="Item 2">Content</AccordionItem>
+ * </Accordion>
  */
 
 interface Props {
+  /** Extra class(es) for the container. */
   class?: string;
   id?: string;
 }

package/AccordionItem.astro

@@ -1,19 +1,22 @@
 ---
 /**
- * AccordionItem.astro
+ * @component AccordionItem
+ * @description One collapsible section inside an `<Accordion>` — a plain
+ * `<details>`/`<summary>` pair, so it works even without JS.
  *
- * Renders an individual accordion section.
- *
- * Usage:
- *   <AccordionItem title="Is it accessible?" headingLevel="h3">
- *     <p>Yes. It adheres to the WAI-ARIA design pattern.</p>
- *   </AccordionItem>
+ * @example astro
+ * <AccordionItem title="Is it accessible?" headingLevel="h3">
+ *   <p>Yes. It adheres to the WAI-ARIA design pattern.</p>
+ * </AccordionItem>
  */
 import Icon from "@stnd/icon/Icon.astro";
 
 interface Props {
+  /** Title text — ignored if the `title` slot is used instead. */
   title?: string;
+  /** Heading tag wrapping the title. Default: `h3`. */
   headingLevel?: "h2" | "h3" | "h4" | "h5" | "h6" | "div";
+  /** Initial open state. Default: `false`. */
   open?: boolean;
   class?: string;
 }

package/Alert.svelte

@@ -1,19 +1,23 @@
 <script>
   /**
-   * @stnd/ui/Alert.svelte
-   * Standard UI Alert — inline notification banner.
+   * @component Alert
+   * @description Inline notification banner. Wraps the global `.alert` CSS
+   * class — use the `class` prop for semantic color variants.
    *
-   * Wraps the global `.alert` CSS class. Use the `class` prop to apply
-   * semantic color variants: "success" | "warning" | "error" | "info"
+   * @property {string} [class] - Semantic intent: "success" | "warning" | "error" | "info". Defaults to accent color.
+   * @property {string} [title] - Optional bold title.
+   * @property {string} [icon] - Optional string icon (e.g. "✓", "⚠").
+   * @property {string} [style] - Extra inline style.
+   * @property {import('svelte').Snippet} [children] - Banner content.
    *
-   * @example
-   *   <Alert>Basic message</Alert>
-   *   <Alert class="success" icon="✓" title="Saved">Changes saved.</Alert>
-   *   <Alert class="error" icon="✕" title="Failed">Something went wrong.</Alert>
+   * @example svelte
+   * <Alert>Basic message</Alert>
+   * <Alert class="success" icon="✓" title="Saved">Changes saved.</Alert>
+   * <Alert class="error" icon="✕" title="Failed">Something went wrong.</Alert>
    */
   let {
-    icon,
-    title,
+    icon = "",
+    title = "",
     class: className = "",
     style = "",
     children,

package/AlertDialog.svelte

@@ -1,7 +1,18 @@
 <script>
   /**
-   * @stnd/ui/AlertDialog.svelte
-   * Standard UI Alert Dialog
+   * @component AlertDialog
+   * @description A native `<dialog>`-based confirmation modal. Used
+   * internally by `DialogManager`/`confirm()` — most consumers should call
+   * `confirm()` from `@stnd/ui/dialog.js` instead of mounting this directly.
+   *
+   * @property {boolean} [open] - Bindable open state.
+   * @property {string} [title] - Dialog title.
+   * @property {string} [description] - Dialog body text.
+   * @property {string} [confirmLabel] - Confirm button label.
+   * @property {string} [cancelLabel] - Cancel button label.
+   * @property {'neutral' | 'danger'} [intent] - Confirm button styling.
+   * @property {() => void} [onconfirm] - Called when confirmed.
+   * @property {() => void} [oncancel] - Called when cancelled or dismissed.
    */
   let {
     open = $bindable(false),
@@ -34,12 +45,6 @@
     onconfirm?.();
   }
 
-  function handleKeydown(e) {
-    if (e.key === "Escape") {
-      e.preventDefault(); // Prevent default browser escape (which just closes it) so we can sync state
-      handleClose();
-    }
-  }
 </script>
 
 <!-- svelte-ignore a11y_click_events_have_key_events -->
@@ -47,7 +52,9 @@
 <dialog
   bind:this={dialog}
   class="std-dialog"
-  onclose={handleClose}
+  aria-label={title}
+  onkeydown={(event) => event.stopPropagation()}
+  onclose={() => { if (open) handleClose(); }}
   oncancel={(e) => {
     e.preventDefault();
     handleClose();

package/CfImage.astro

@@ -1,36 +1,42 @@
 ---
 /**
- * CfImage — Responsive image via Cloudflare Image Transformations.
+ * @component CfImage
+ * @description Responsive image via Cloudflare Image Transformations.
+ * Generates a proper `<img srcset="..." sizes="...">` using Cloudflare's
+ * `/cdn-cgi/image/` pipeline. Falls back to the original `src` in dev.
  *
- * Generates a proper <img srcset="..." sizes="..."> using Cloudflare's
- * /cdn-cgi/image/ pipeline. Falls back to the original src in dev.
+ * @example astro - Basic
+ * <CfImage src="/assets/img/test.png" alt="Hero" sizes="100vw" />
  *
- * @example Basic
- *   <CfImage src="/assets/img/hero.jpg" alt="Hero" sizes="100vw" />
- *
- * @example Card thumbnail (image is ~1/3 of viewport on desktop)
- *   <CfImage
- *     src={cover}
- *     alt={title}
- *     sizes="(max-width: 600px) 100vw, (max-width: 900px) 50vw, 33vw"
- *     loading="eager"
- *   />
+ * @example astro - Card thumbnail (image is ~1/3 of viewport on desktop)
+ * <CfImage
+ *   src={cover}
+ *   alt={title}
+ *   sizes="(max-width: 600px) 100vw, (max-width: 900px) 50vw, 33vw"
+ *   loading="eager"
+ * />
  */
 import { cfImage, cfImageSrcset } from "@stnd/utils";
 
 interface Props {
+  /** Image source path. */
   src: string;
+  /** Alt text — required, no silent fallback. */
   alt: string;
   /** CSS sizes attribute — describes the rendered image width at each breakpoint. */
   sizes?: string;
   /** Widths (px) to include in the srcset. */
   widths?: number[];
+  /** Cloudflare output quality (0–100). */
   quality?: number;
+  /** Output format passed to Cloudflare (e.g. `avif`, `webp`, `auto`). */
   format?: string;
   /** Cloudflare sharpen (0–10). */
   sharpen?: number;
   class?: string;
+  /** Native `loading` attribute. */
   loading?: "lazy" | "eager";
+  /** Native `decoding` attribute. */
   decoding?: "async" | "sync" | "auto";
   [key: string]: any;
 }

package/Combobox.svelte

@@ -1,23 +1,29 @@
 <script>
   import { setContext } from "svelte";
 
+  /**
+   * @component Combobox
+   * @description Searchable select — type to filter `options`, or type a
+   * value not in the list when `allowCustom` is set.
+   */
+
   /**
    * @typedef {Object} ComboboxOption
-   * @property {string} label
-   * @property {string} value
+   * @property {string} label - Text shown in the list.
+   * @property {string} value - Value stored when this option is selected.
    */
 
   /**
    * @typedef {Object} ComboboxProps
-   * @property {ComboboxOption[]} options
-   * @property {string} [value]
-   * @property {string} [placeholder]
-   * @property {string} [searchPlaceholder]
-   * @property {string} [emptyText]
-   * @property {boolean} [allowCustom]
-   * @property {string} [class]
-   * @property {string} [name]
-   * @property {string} [id]
+   * @property {ComboboxOption[]} options - The list to search/select from.
+   * @property {string} [value] - Bindable selected value.
+   * @property {string} [placeholder] - Placeholder before a value is selected.
+   * @property {string} [searchPlaceholder] - Placeholder inside the search input.
+   * @property {string} [emptyText] - Shown when no option matches the search.
+   * @property {boolean} [allowCustom] - Accept a typed value not present in `options`.
+   * @property {string} [class] - Extra class(es) for the trigger.
+   * @property {string} [name] - Name for an associated hidden form input.
+   * @property {string} [id] - ID for the trigger button.
    */
 
   /** @type {ComboboxProps} */

package/ContextMenu.svelte

@@ -1,120 +1,105 @@
 <script>
-  import { setContext } from "svelte";
+  import { setContext, tick } from "svelte";
+  import "./menu.css";
+  import { clampMenuPosition, menuItems, navigateMenu } from "./menu.js";
 
   /**
-   * @typedef {Object} ContextMenuProps
-   * @property {import('svelte').Snippet} children - The trigger element(s)
-   * @property {import('svelte').Snippet} [content] - The menu content
-   * @property {string} [class] - Optional class for the trigger wrapper
+   * Right-click menu, or controlled menu for virtualized/delegated targets.
+   * `position` uses viewport coordinates. `onclose` synchronizes a controlled target.
+   * Existing children/content snippets remain supported.
    */
-
-  /** @type {ContextMenuProps} */
-  let { children, content, class: className = "", ...props } = $props();
-
-  let open = $state(false);
-  let positioned = $state(false);
-  let x = $state(0);
-  let y = $state(0);
+  let {
+    children = undefined, content = undefined, class: className = "", open = $bindable(false),
+    position = null, label = "Actions", onclose = () => {}, ...props
+  } = $props();
+  let point = $state({ x: 0, y: 0 });
+  let location = $state({ x: 0, y: 0 });
+  let placed = $state(false);
   let menuElement = $state();
-
-  function onContextMenu(e) {
-    if (e.ctrlKey) return;
-    e.preventDefault();
-
-    let targetX = e.clientX;
-    let targetY = e.clientY;
-
-    x = targetX;
-    y = targetY;
-    open = true;
-    positioned = false;
-
-    // Use a microtask/timeout to wait for render then measure
-    setTimeout(() => {
-      if (!menuElement) return;
-
-      const rect = menuElement.getBoundingClientRect();
-      const viewportWidth = window.innerWidth;
-      const viewportHeight = window.innerHeight;
-
-      if (targetX + rect.width > viewportWidth) {
-        targetX -= rect.width;
-      }
-      if (targetY + rect.height > viewportHeight) {
-        targetY -= rect.height;
-      }
-
-      x = targetX;
-      y = targetY;
-      positioned = true;
-    }, 0);
-  }
+  let returnFocus;
 
   function close() {
     open = false;
-    positioned = false;
+    onclose();
   }
 
-  setContext("context-menu", {
-    get open() {
-      return open;
-    },
-    close,
-  });
-
-  function handleWindowClick(e) {
-    if (open && menuElement && !menuElement.contains(e.target)) {
-      close();
-    }
+  function onContextMenu(event) {
+    // Keep Control-click native for existing consumers.
+    if (event.ctrlKey) return;
+    event.preventDefault();
+    event.stopPropagation();
+    point = { x: event.clientX, y: event.clientY };
+    open = true;
   }
 
-  function handleWindowKeydown(e) {
-    if (open && e.key === "Escape") {
-      close();
-    }
-  }
+  $effect(() => {
+    if (!open || !menuElement) return;
+    const anchor = position ?? point;
+    const element = menuElement;
+    returnFocus = document.activeElement;
+    placed = false;
+    let cancelled = false;
+    let focusFrame;
+    const onScroll = (event) => { if (!element.contains(event.target)) close(); };
+    window.addEventListener("scroll", onScroll, true);
+    tick().then(() => {
+      if (cancelled) return;
+      location = clampMenuPosition(anchor.x, anchor.y, element.offsetWidth, element.offsetHeight, window.innerWidth, window.innerHeight);
+      placed = true;
+      // Measure without inherited visibility:hidden: menu items transition
+      // "all", which can leave their visibility hidden when focus is requested.
+      focusFrame = requestAnimationFrame(() => {
+        if (!cancelled) (menuItems(element)[0] ?? element).focus();
+      });
+    });
+    return () => {
+      cancelled = true;
+      cancelAnimationFrame(focusFrame);
+      window.removeEventListener("scroll", onScroll, true);
+      if (element.contains(document.activeElement) || document.activeElement === document.body) {
+        returnFocus?.focus?.();
+      }
+    };
+  });
+
+  setContext("context-menu", { get open() { return open; }, close });
 </script>
 
 <svelte:window
-  onclick={handleWindowClick}
-  onkeydown={handleWindowKeydown}
-  onscroll={close}
+  onclick={(event) => { if (open && !menuElement?.contains(event.target)) close(); }}
+  onresize={() => { if (open) close(); }}
 />
 
-<div
-  class="context-menu-trigger {className}"
-  oncontextmenu={onContextMenu}
-  role="presentation"
-  {...props}
->
-  {@render children?.()}
-</div>
-
+{#if children}
+  <div class="context-menu-trigger {className}" oncontextmenu={onContextMenu} role="presentation" {...props}>
+    {@render children()}
+  </div>
+{/if}
 {#if open}
   <div
     bind:this={menuElement}
     class="std-menu-content context-menu-content m-0 no-rhythm"
-    style:left="{x}px"
-    style:top="{y}px"
-    style:visibility={positioned ? "visible" : "hidden"}
-    role="menu"
-    tabindex="-1"
+    style:left="{location.x}px"
+    style:top="{location.y}px"
+    style:opacity={placed ? 1 : 0}
+    style:pointer-events={placed ? "auto" : "none"}
+    role="menu" aria-label={label} tabindex="-1"
+    onkeydown={(event) => navigateMenu(event, menuElement, close)}
+    oncontextmenu={(event) => event.preventDefault()}
   >
     {@render content?.()}
   </div>
 {/if}
 
 <style>
-  .context-menu-trigger {
-    display: contents;
-  }
-
+  .context-menu-trigger { display: contents; }
   .context-menu-content {
     position: fixed;
+    z-index: 10000;
     min-width: var(--space-6);
+    max-width: calc(100vw - 16px);
+    max-height: calc(100vh - 16px);
+    overflow-y: auto;
   }
-
-  :global(.context-menu-content > *) {
-    flex-shrink: 0;
-  }
+  :global(.context-menu-content > *) { flex-shrink: 0; }
 </style>

package/ContextMenuItem.svelte

@@ -2,6 +2,11 @@
   import { getContext } from "svelte";
   import Icon from "@stnd/icon/Icon.svelte";
 
+  /**
+   * @component ContextMenuItem
+   * @description One clickable row inside a `<ContextMenu>`'s `content` slot.
+   */
+
   /**
    * @typedef {Object} ContextMenuItemProps
    * @property {import('svelte').Snippet} [children] - Item label
@@ -13,7 +18,7 @@
    * @property {() => void} [onclick] - Click handler
    */
 
-  /** @type {ContextMenuItemProps} */
+  /** @type {ContextMenuItemProps & import('svelte/elements').HTMLButtonAttributes} */
   let {
     children,
     label,
@@ -42,6 +47,7 @@
   onclick={handleClick}
   role="menuitem"
   aria-disabled={disabled}
+  {disabled}
   {...props}
 >
   {#if icon}

package/ContextMenuItemCheckbox.svelte

@@ -2,6 +2,11 @@
   import { getContext } from "svelte";
   import Icon from "@stnd/icon/Icon.svelte";
 
+  /**
+   * @component ContextMenuItemCheckbox
+   * @description A checkable row inside a `<ContextMenu>`'s `content` slot.
+   */
+
   /**
    * @typedef {Object} ContextMenuItemCheckboxProps
    * @property {import('svelte').Snippet} [children] - Item label
@@ -42,6 +47,7 @@
   role="menuitemcheckbox"
   aria-checked={checked}
   aria-disabled={disabled}
+  {disabled}
   {...props}
 >
   <div class="item-check">

package/ContextMenuLabel.svelte

@@ -1,4 +1,10 @@
 <script>
+  /**
+   * @component ContextMenuLabel
+   * @description A non-interactive heading row inside a `<ContextMenu>`,
+   * used to group related items.
+   */
+
   /**
    * @typedef {Object} ContextMenuLabelProps
    * @property {import('svelte').Snippet} [children] - Label content

package/ContextMenuSeparator.svelte

@@ -1 +1,8 @@
+<script>
+  /**
+   * @component ContextMenuSeparator
+   * @description A visual divider between items in a `<ContextMenu>`. No props.
+   */
+</script>
+
 <hr class="std-menu-separator" />

package/Dialog.svelte

@@ -0,0 +1,60 @@
+<script>
+  import { tick } from "svelte";
+
+  /** Native modal shell. Content/layout remain the caller's responsibility. */
+  let {
+    open = $bindable(false), label, children, class: className = "",
+    style = "", onclose = () => {}, onkeydown = undefined,
+  } = $props();
+  let element = $state();
+
+  function close() {
+    if (!open) return;
+    open = false;
+    onclose();
+  }
+
+  $effect(() => {
+    if (!element || !open) return;
+    const dialog = element;
+    const previous = document.activeElement;
+    dialog.showModal();
+    return () => {
+      dialog.close();
+      tick().then(() => { if (previous?.isConnected) previous.focus?.(); });
+    };
+  });
+</script>
+
+<!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+<dialog bind:this={element} class="std-modal {className}" {style} aria-label={label}
+  oncancel={(event) => { event.preventDefault(); close(); }}
+  onclose={() => { if (element && !element.open) close(); }}
+  onkeydown={(event) => { event.stopPropagation(); onkeydown?.(event); }}
+  onclick={(event) => {
+    if (event.target !== element) return;
+    const rect = element.getBoundingClientRect();
+    if (event.clientX < rect.left || event.clientX > rect.right || event.clientY < rect.top || event.clientY > rect.bottom) close();
+  }}
+>
+  {@render children?.()}
+</dialog>
+
+<style>
+  .std-modal {
+    padding: 0;
+    margin: auto;
+    width: var(--dialog-width, min(90vw, 580px));
+    max-width: calc(100vw - 32px);
+    height: var(--dialog-height, auto);
+    max-height: var(--dialog-max-height, 88vh);
+    overflow: hidden;
+    background: var(--color-surface-low);
+    color: var(--color-foreground);
+    border: 1px solid var(--color-border);
+    border-radius: var(--radius-lg);
+    box-shadow: var(--shadow-raised);
+  }
+  .std-modal[open] { display: flex; flex-direction: column; }
+  .std-modal::backdrop { background: rgb(0 0 0 / 0.65); backdrop-filter: blur(8px); }
+</style>

package/DialogManager.svelte

@@ -1,4 +1,16 @@
 <script>
+  /**
+   * @component DialogManager
+   * @description Renders confirmation dialogs triggered programmatically —
+   * mount `<DialogManagerComponent client:load />` once in your root layout
+   * (Standard does this by default), then call `confirm()` from
+   * `@stnd/ui/dialog.js` anywhere; no props, no per-dialog markup. Bridges
+   * the `dialogState` store (set by `confirm()`) to an `<AlertDialog>`.
+   *
+   * @example js
+   * import { confirm } from "@stnd/ui/dialog.js";
+   * const ok = await confirm({ title: "Delete this?", intent: "danger" });
+   */
   import AlertDialog from "./AlertDialog.svelte";
   import { dialogState } from "./dialog.js";