@stnd/ui 0.5.0 → 0.5.2

package/Dropdown.svelte

@@ -1,5 +1,14 @@
 <script>
-  import { setContext } from "svelte";
+  import { setContext, tick } from "svelte";
+  import "./menu.css";
+  import { menuItems, navigateMenu } from "./menu.js";
+
+  /**
+   * @component Dropdown
+   * @description Accessible, keyboard-navigable dropdown menu. Use the
+   * `trigger` slot for the button that opens it, the default slot for its
+   * items — typically `<DropdownItem>`/`<DropdownLabel>`/`<DropdownSeparator>`.
+   */
 
   /**
    * @typedef {Object} DropdownProps
@@ -7,6 +16,9 @@
    * @property {import('svelte').Snippet} children - The menu items
    * @property {'start' | 'end'} [align] - Alignment of the dropdown
    * @property {string} [class] - Optional class
+   * @property {string} [label] - Accessible native trigger label (recommended)
+   * @property {string} [triggerClass] - Classes on the native trigger
+   * @property {boolean} [open] - Bindable open state
    */
 
   /** @type {DropdownProps} */
@@ -15,19 +27,26 @@
     children,
     align = "start",
     class: className = "",
+    label = "",
+    triggerClass = "",
+    open = $bindable(false),
     ...props
   } = $props();
 
-  let open = $state(false);
   let triggerElement = $state();
   let menuElement = $state();
+  const id = $props.id();
 
   function toggle() {
     open = !open;
+    if (open) tick().then(() => {
+      if (open && menuElement) (menuItems(menuElement)[0] ?? menuElement).focus();
+    });
   }
 
-  function close() {
+  function close(restore = true) {
     open = false;
+    if (restore) (triggerElement?.querySelector("button, a") ?? triggerElement)?.focus();
   }
 
   setContext("dropdown", {
@@ -41,41 +60,54 @@
       !menuElement.contains(e.target) &&
       (!triggerElement || !triggerElement.contains(e.target))
     ) {
-      close();
+      close(false);
     }
   }
 
-  function handleKeydown(e) {
-    if (!open) return;
-    if (e.key === "Escape") {
-      close();
-      triggerElement?.focus();
+  function triggerKeydown(e) {
+    if (e.key === "ArrowDown") { e.preventDefault(); if (!open) toggle(); }
+    // Legacy wrapper: native children already synthesize their own click.
+    else if (e.target === e.currentTarget && !label && (e.key === "Enter" || e.key === " ")) {
+      e.preventDefault(); toggle();
     }
   }
 </script>
 
-<svelte:window onclick={handleWindowClick} onkeydown={handleKeydown} />
+<svelte:window onclick={handleWindowClick} />
 
 <div class="std-dropdown {className}" {...props}>
+  {#if label}
+    <button bind:this={triggerElement} type="button" class={triggerClass}
+      aria-label={label} title={label} aria-haspopup="menu" aria-expanded={open} aria-controls={id}
+      onclick={toggle} onkeydown={triggerKeydown}>
+      {@render trigger?.()}
+    </button>
+  {:else}
   <div
     bind:this={triggerElement}
     class="std-dropdown-trigger"
     onclick={toggle}
     role="button"
     tabindex="0"
-    onkeydown={(e) => (e.key === "Enter" || e.key === " ") && toggle()}
+    onkeydown={triggerKeydown}
     aria-haspopup="menu"
     aria-expanded={open}
+    aria-controls={id}
   >
     {@render trigger?.()}
   </div>
+  {/if}
 
   {#if open}
     <div
       bind:this={menuElement}
+      {id}
       class="std-menu-content std-dropdown-content no-rhythm"
       class:align-end={align === "end"}
       role="menu"
+      aria-label={label || undefined}
+      tabindex="-1"
+      onkeydown={(event) => navigateMenu(event, menuElement, close)}
     >
       {@render children?.()}
     </div>
@@ -98,6 +130,9 @@
     top: 100%;
     margin-top: var(--space-d2);
     min-width: var(--space-6);
+    max-height: 70vh;
+    overflow-y: auto;
+    z-index: 100;
 
     &.align-end {
       right: 0;

package/DropdownItem.svelte

@@ -2,6 +2,12 @@
   import { getContext } from "svelte";
   import Icon from "@stnd/icon/Icon.svelte";
 
+  /**
+   * @component DropdownItem
+   * @description One clickable row inside a `<Dropdown>`. Either provide
+   * `label` or the `children` snippet, not both.
+   */
+
   /**
    * @typedef {Object} DropdownItemProps
    * @property {import('svelte').Snippet} [children] - Item label
@@ -14,7 +20,7 @@
    * @property {(e: MouseEvent) => void} [onclick] - Click handler
    */
 
-  /** @type {DropdownItemProps} */
+  /** @type {DropdownItemProps & import('svelte/elements').HTMLAttributes<HTMLElement>} */
   let {
     children,
     label,

package/DropdownLabel.svelte

@@ -1,4 +1,12 @@
 <script>
+  /**
+   * @component DropdownLabel
+   * @description A non-interactive heading row inside a `<Dropdown>`, used
+   * to group related items.
+   *
+   * @property {import('svelte').Snippet} [children] - Label content
+   * @property {string} [label] - Label as a string, if not using the children snippet
+   */
   let { children, label, ...props } = $props();
 </script>
 

package/DropdownSeparator.svelte

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

package/LauncherHint.astro

@@ -1,9 +1,13 @@
 ---
 /**
- * LauncherHint.astro
+ * @component LauncherHint
+ * @description A small launcher hint button (⌘K) — visibility/positioning
+ * is handled by whatever container places it (e.g. header slots), this
+ * component only renders the button itself.
  *
- * Renders a small launcher hint button (⌘K).
- * Logic for visibility/positioning is now handled by the container (e.g. Header slots).
+ * @property {string} [title] - Accessible label / tooltip text. Default: "Open Launcher — Cmd/Ctrl+K".
+ * @property {string} [kbd] - Shortcut text shown inside the button. Default: "⌘K".
+ * @property {string} [class] - Extra class(es) for the button.
  */
 const {
   title = "Open Launcher — Cmd/Ctrl+K",

package/Pagination.astro

@@ -1,22 +1,21 @@
 ---
 /**
- * Pagination.astro — Zero-JS pagination nav
+ * @component Pagination
+ * @description Zero-JS pagination nav — previous / page numbers / next,
+ * using standard button classes (`ghost`, `outline`) from `@stnd/styles`.
+ * URL pattern: page 1 links to `firstPageUrl` (or `baseUrl` if omitted),
+ * page N links to `baseUrl/N` (e.g. `/chroniques/page/2`).
  *
- * Renders a previous / page numbers / next navigation bar.
- * Uses standard button classes (ghost, outline) from @stnd/styles.
- *
- * Usage:
- *   <Pagination currentPage={2} totalPages={5} baseUrl="/chroniques/page" firstPageUrl="/chroniques" />
- *
- * URL pattern:
- *   Page 1 → firstPageUrl (or baseUrl if omitted)
- *   Page N → baseUrl/N   (e.g. /chroniques/page/2)
+ * @example astro
+ * <Pagination currentPage={2} totalPages={5} baseUrl="/chroniques/page" firstPageUrl="/chroniques" />
  */
 import Icon from "@stnd/icon/Icon.astro";
 
 interface Props {
+  /** 1-indexed current page. */
   currentPage: number;
   totalPages: number;
+  /** Base URL pages 2+ are appended to as `baseUrl/N`. */
   baseUrl: string;
   /** URL for page 1 when it differs from baseUrl (e.g. "/chroniques" vs "/chroniques/page") */
   firstPageUrl?: string;

package/Panel.svelte

@@ -1,7 +1,7 @@
 <script>
   /**
-   * @stnd/ui/Panel.svelte
-   * Edge Panel — a collapsible side panel fixed to the screen edge.
+   * @component Panel
+   * @description Edge Panel — a collapsible side panel fixed to the screen edge.
    *
    * Shows only a thin 6px handle strip by default. Clicking the handle slides
    * the panel open. A pin button in the header locks it open so it won't close

package/Popover.svelte

@@ -0,0 +1,83 @@
+<script>
+  import { tick } from "svelte";
+  import "./menu.css";
+
+  /**
+   * Anchored, nonmodal popup for forms/controls. The trigger snippet receives
+   * native-button attributes to spread on ONE button (no nested button wrapper).
+   */
+  let {
+    open = $bindable(false), label, trigger, children, align = "start",
+    side = "bottom", class: className = "", onclose = () => {},
+  } = $props();
+  const id = $props.id();
+  let root = $state();
+  let content = $state();
+  let triggerElement;
+
+  $effect(() => {
+    if (!open || !content) return;
+    const popup = content;
+    const triggerButton = triggerElement;
+    return () => {
+      if (popup.contains(document.activeElement) || document.activeElement === document.body) {
+        triggerButton?.focus();
+      }
+    };
+  });
+
+  function close(restore = false) {
+    open = false;
+    if (restore) triggerElement?.focus();
+    onclose();
+  }
+  function toggle(event) {
+    triggerElement = event.currentTarget;
+    if (open) close();
+    else {
+      open = true;
+      tick().then(() => content?.querySelector("input, button, select, textarea, [tabindex]")?.focus());
+    }
+  }
+</script>
+
+<svelte:window onclick={(event) => { if (open && !root?.contains(event.target)) close(); }} />
+
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<div bind:this={root} class="std-popover {className}"
+  onkeydown={(event) => {
+    if (open && event.key === "Escape") {
+      event.stopPropagation(); event.preventDefault(); close(true);
+    }
+  }}>
+  {@render trigger({
+    type: "button", "aria-haspopup": "dialog", "aria-expanded": open,
+    "aria-controls": id, onclick: toggle,
+  })}
+  {#if open}
+    <div bind:this={content} {id} class="std-menu-content std-popover-content no-rhythm"
+      class:align-end={align === "end"} class:above={side === "top"}
+      role="dialog" aria-label={label} tabindex="-1"
+      onkeydown={(event) => {
+        event.stopPropagation();
+        if (event.key === "Escape") { event.preventDefault(); close(true); }
+      }}
+      onfocusout={(event) => {
+        if (event.relatedTarget && !root?.contains(event.relatedTarget)) close();
+      }}
+    >
+      {@render children?.()}
+    </div>
+  {/if}
+</div>
+
+<style>
+  .std-popover { position: relative; display: inline-block; }
+  .std-popover-content {
+    position: absolute; top: 100%; left: 0; margin-top: var(--space-d2);
+    width: max-content; min-width: 180px; max-width: min(320px, calc(100vw - 16px));
+    max-height: 70vh; overflow-y: auto; z-index: 100;
+  }
+  .align-end { left: auto; right: 0; }
+  .above { top: auto; bottom: 100%; margin-top: 0; margin-bottom: var(--space-d2); }
+</style>

package/README.md

@@ -2,21 +2,24 @@
 title: "@stnd/ui"
 aliases: []
 created: 2026-07-05 07:47
-modified: 2026-07-05 19:15
+modified: 2026-09-16T18:33:35.950Z
 last_audited: 2026-07-14
 audit_interval_days: 90
 next_audit: 2026-10-12
 audit_priority: 3
 maturity: sprout
 mode: read
-publish: false
+publish: true
 status: active
 tags:
   - package
   - stnd
 theme: kernel
 type: package
-visibility: private
+visibility: public
+garden-url: https://standard.garden/@francis/readme
+garden-short: https://stnd.gd/Yl18ps
+permalink: readme
 ---
 
 # @[stnd](../README)/ui
@@ -77,6 +80,8 @@ You should only import components from this package when you need:
 
 ## 🧩 Component API Reference
 
+::widget UiShowcase
+
 ### Astro Components (Zero JS)
 
 #### `<Accordion />`
@@ -101,8 +106,10 @@ Semantic feedback banners.
 
 #### `<Dropdown />`
 Accessible, keyboard-navigable dropdown menus.
-- `align` (string): Alignment of the menu (`start`, `center`, `end`). Defaults to `start`.
+- `align` (string): Alignment of the menu (`start`, `end`). Defaults to `start`.
+- `label` (string): Recommended accessible name for the native trigger button. When supplied, the `trigger` snippet contains only its content (not another button). `triggerClass` styles that button; `open` is bindable. Existing trigger snippets without `label` remain supported.
 - **Slots**: `trigger` (the button that opens the menu), `default` (the menu items).
+- Arrow keys and Home/End move among enabled items; Escape dismisses and restores trigger focus. Item activation closes the menu; Tab dismisses and continues focus navigation. Native button keyboard activation does not toggle twice.
 
 **Related Sub-components**:
 - `<DropdownItem icon="ph:user" shortcut="⌘P">Profile</DropdownItem>`
@@ -112,6 +119,38 @@ Accessible, keyboard-navigable dropdown menus.
 #### `<ContextMenu />`
 Viewport-aware right-click menus.
 - **Slots**: `default` (the area that triggers the menu on right-click), `content` (the menu items).
+- For delegated/virtualized targets, omit the default snippet and pass `open`, `position={{ x, y }}` (viewport coordinates), `label`, and `onclose`. `open` is bindable. The shared menu measures its actual content, clamps to the viewport, and scrolls oversized menus.
+- Arrow keys and Home/End move among enabled items. Escape, Tab, outside clicks, viewport resize, and scrolling outside the menu dismiss it. Focus returns to the previous element when appropriate. Context-menu item components use native disabled state as well as ARIA.
+
+#### `<Dialog />`
+
+A general-purpose native modal shell for forms and other arbitrary content. This complements `AlertDialog`/`confirm()`; it does not add confirmation semantics.
+
+```svelte
+<Dialog bind:open label="Preferences" onclose={discardDraft}
+  style="--dialog-width: 580px; --dialog-max-height: 88vh">
+  <!-- Form content and semantic buttons belong to the consumer. -->
+</Dialog>
+```
+
+`label` is the accessible name; `children` supplies content; `class` and `style` customize the shell. `onkeydown` can implement a content-specific shortcut. The component owns `showModal()`, background inertness, native focus behavior, Escape/backdrop dismissal, and focus restoration. It stops keyboard propagation to application shortcut handlers. Use it for modal interactions, not for live nonmodal monitors or native OS windows.
+
+#### `<Popover />`
+
+An anchored, nonmodal popup for forms and mixed controls. Use `Dropdown` for menus of actions instead.
+
+```svelte
+<Popover label="Display options" align="end">
+  {#snippet trigger(attributes)}
+    <button class="btn ghost" {...attributes}>Display</button>
+  {/snippet}
+  <!-- Native inputs and content-specific buttons. -->
+</Popover>
+```
+
+Spread the trigger attributes onto a single native button; they supply its click behavior and ARIA relationship. Props: bindable `open`, required `label`, `trigger` and `children` snippets, `align` (`start`/`end`), `side` (`bottom`/`top`), optional wrapper `class`, and `onclose`. Escape restores trigger focus; outside click or focus leaving the popup/trigger dismisses it. Keyboard events inside the content do not reach application-wide shortcuts.
+
+The shared menu geometry/navigation helpers have dependency-free tests: `node --test packages/ui/menu.test.js` from the repository root. Reveal's browser UI regression suite also exercises controlled and wrapped context menus, dropdowns, popovers, and native dialogs with synthetic data; see [Reveal UI validation](../../apps/reveal/README.md#ui-validation).
 
 ---
 
@@ -119,6 +158,8 @@ Viewport-aware right-click menus.
 
 The `DialogManager` allows you to trigger accessible confirmation dialogs programmatically from any script using a simple Promise-based API. This prevents littering your DOM with hidden modal HTML.
 
+`AlertDialog` can also be composed directly inside an existing `Dialog` when confirmation belongs to that form. Its title provides the accessible dialog name, keyboard events stay within the confirmation instead of reaching parent form shortcuts, and a programmatic close after confirmation does not also call the cancellation callback.
+
 ### 1. Mount the Manager
 Ensure `<DialogManagerComponent client:load />` is mounted once in your root layout (Standard does this by default).
 

package/Scroller.astro

@@ -1,9 +1,12 @@
 ---
 /**
- * Scroller.astro
+ * @component Scroller
+ * @description Astro wrapper for `Scroller.svelte` that ensures it always
+ * hydrates on load — use this instead of the Svelte component directly so
+ * you don't have to remember `client:load` yourself.
  *
- * Astro wrapper for Scroller.svelte that ensures it always hydrates on load.
- * Usage: <Scroller /> (no client:load needed)
+ * @example astro
+ * <Scroller />
  */
 import SvelteScroller from "./Scroller.svelte";
 ---

package/Scroller.svelte

@@ -1,4 +1,10 @@
 <script>
+  /**
+   * @component Scroller
+   * @description A thin fixed reading-progress bar across the top of the
+   * viewport, filling as the page scrolls. No props — use the `<Scroller />`
+   * Astro wrapper instead of this directly, so hydration isn't your problem.
+   */
   let progress = $state(0);
 
   function updateProgress() {

package/TableOfContents.astro

@@ -4,17 +4,17 @@
  * @description Subtle Notion-style TOC — small lines fixed to the right side
  * that expand with heading labels on hover and highlight the current section.
  *
- * Usage:
- *   import TableOfContents from "@stnd/ui/TableOfContents.astro";
- *   <TableOfContents {headings} />
+ * @example astro - Usage
+ * import TableOfContents from "@stnd/ui/TableOfContents.astro";
+ * <TableOfContents {headings} />
  *
- * Extract headings from rendered HTML:
- *   const headings = [];
- *   const headingRegex = /<h([23])\s[^>]*id="([^"]*)"[^>]*>(.*?)<\/h\1>/gi;
- *   let m;
- *   while ((m = headingRegex.exec(html)) !== null) {
- *     headings.push({ depth: parseInt(m[1]), text: m[3].replace(/<[^>]+>/g, "").trim(), slug: m[2] });
- *   }
+ * @example js - Extracting headings from rendered HTML
+ * const headings = [];
+ * const headingRegex = /<h([23])\s[^>]*id="([^"]*)"[^>]*>(.*?)<\/h\1>/gi;
+ * let m;
+ * while ((m = headingRegex.exec(html)) !== null) {
+ *   headings.push({ depth: parseInt(m[1]), text: m[3].replace(/<[^>]+>/g, "").trim(), slug: m[2] });
+ * }
  */
 
 interface Heading {
@@ -24,6 +24,7 @@ interface Heading {
 }
 
 interface Props {
+  /** The headings to show — typically extracted from rendered HTML, see the example below. */
   headings: Heading[];
   /** Minimum headings to show the TOC. Default: 2 */
   minHeadings?: number;
@@ -31,13 +32,13 @@ interface Props {
   breakpoint?: number;
 }
 
-const { headings, minHeadings = 2 } = Astro.props;
+const { headings, minHeadings = 2, breakpoint = 1100 } = Astro.props;
 const tocHeadings = headings.filter((h) => h.depth === 2 || h.depth === 3);
 ---
 
 {
   tocHeadings.length >= minHeadings && (
-    <nav class="stnd-toc" aria-label="Table des matières">
+    <nav class="stnd-toc" aria-label="Table des matières" data-breakpoint={breakpoint}>
       {tocHeadings.map((h) => (
         <a
           href={`#${h.slug}`}
@@ -152,10 +153,12 @@ const tocHeadings = headings.filter((h) => h.depth === 2 || h.depth === 3);
     opacity: 1 !important;
   }
 
-  @media (max-width: 1100px) {
-    .stnd-toc {
-      display: none;
-    }
+  /* Set by the script below via matchMedia(breakpoint) — a CSS @media
+     condition can't take its threshold from a prop (media queries need a
+     literal value at parse time, not a per-instance one), so the
+     hide-below-breakpoint behavior has to live in JS instead. */
+  .stnd-toc[data-below-breakpoint] {
+    display: none;
   }
 </style>
 
@@ -165,6 +168,20 @@ const tocHeadings = headings.filter((h) => h.depth === 2 || h.depth === 3);
     const tocLinks = document.querySelectorAll<HTMLElement>(".toc-item[data-slug]");
     if (tocLinks.length === 0) return;
 
+    // Hide below `breakpoint` (default 1100, set via the `breakpoint` prop
+    // and read back from data-breakpoint) — a plain CSS @media rule can't
+    // take its threshold from a prop, so this does the equivalent in JS.
+    if (toc) {
+      // `|| 1100` would silently discard an intentional breakpoint={0}
+      // (0 is falsy) — parse explicitly instead.
+      const parsedBreakpoint = Number(toc.dataset.breakpoint);
+      const breakpoint = Number.isFinite(parsedBreakpoint) ? parsedBreakpoint : 1100;
+      const mql = window.matchMedia(`(max-width: ${breakpoint}px)`);
+      const applyBreakpoint = () => toc.toggleAttribute("data-below-breakpoint", mql.matches);
+      applyBreakpoint();
+      mql.addEventListener("change", applyBreakpoint);
+    }
+
     // Show on scroll or mouse move, hide after inactivity
     let hideTimer: ReturnType<typeof setTimeout>;
     const show = () => {

package/Toast.astro

@@ -1,5 +1,18 @@
 ---
-// sToastSystem.astro - Zero-dependency notification system
+/**
+ * @component Toast
+ * @description Zero-dependency notification system. Mount once (Standard
+ * does this by default); afterward, call the global `window.toast()`
+ * helper from anywhere — no import needed, since the component itself
+ * dispatches/listens for a `toast` custom event.
+ *
+ * @example js - Fire a toast
+ * window.toast("Saved!", "success");
+ * window.toast("Something went wrong", "error", 6000, {
+ *   label: "Retry",
+ *   onClick: "myRetryFn",
+ * });
+ */
 ---
 
 <div id="toast-container" aria-live="polite" aria-atomic="true"></div>
@@ -87,18 +100,16 @@
   }
 </style>
 
-<script>
-  import { navigate } from "astro:transitions/client";
-
+<script is:inline>
   function initToastSystem() {
     // Prevent duplicate listeners across re-renders
-    if ((window as any)._toastListenerAdded) return;
+    if (window._toastListenerAdded) return;
 
     const container = document.getElementById("toast-container");
     if (!container) return;
 
     // Listen for custom 'toast' events (only add once)
-    window.addEventListener("toast", ((e: CustomEvent) => {
+    window.addEventListener("toast", (e) => {
       const { message, type = "default", duration = 4000, action } = e.detail;
 
       // Create toast element
@@ -175,23 +186,16 @@
         // Wait for CSS transition before removing from DOM
         setTimeout(() => toast.remove(), 1000);
       }, duration);
-    }) as EventListener);
+    });
 
-    (window as any)._toastListenerAdded = true;
+    window._toastListenerAdded = true;
   }
 
   // Initialize
   initToastSystem();
 
-  // Global helpers for non-module scripts
-  const win = window as any;
-
-  win.toast = (
-    message: string,
-    type: string = "default",
-    duration: number = 2000,
-    action: { label?: string; view?: string; onClick?: string } | null = null,
-  ) => {
+  // Global helper for non-module scripts
+  window.toast = (message, type = "default", duration = 2000, action = null) => {
     const detail = { message, type, duration };
     if (action) detail.action = action;
     window.dispatchEvent(new CustomEvent("toast", { detail }));

package/menu.css

@@ -0,0 +1,12 @@
+/* Shared keyboard affordance, independent of hover or an app's button reset. */
+.std-menu-content [role^="menuitem"]:focus-visible,
+.std-dropdown > button:focus-visible,
+.std-dropdown-trigger:focus-visible,
+.std-popover > button:focus-visible {
+  outline: 2px solid var(--color-accent);
+  outline-offset: -2px;
+}
+
+.std-menu-content [role^="menuitem"]:focus-visible {
+  background: var(--color-surface-highest);
+}

package/menu.js

@@ -0,0 +1,33 @@
+/** Shared menu navigation; no application shortcuts belong in a menu. */
+export function menuItems(element) {
+  return Array.from(element.querySelectorAll('[role^="menuitem"]')).filter(
+    (item) => !item.disabled && item.getAttribute("aria-disabled") !== "true",
+  );
+}
+
+export function navigateMenu(event, element, close) {
+  event.stopPropagation();
+  const items = menuItems(element);
+  const current = items.indexOf(element.ownerDocument.activeElement);
+  let index;
+  if (event.key === "ArrowDown") index = (current + 1) % items.length;
+  else if (event.key === "ArrowUp") index = (current - 1 + items.length) % items.length;
+  else if (event.key === "Home") index = 0;
+  else if (event.key === "End") index = items.length - 1;
+  else if (event.key === "Escape" || event.key === "Tab") {
+    if (event.key === "Escape") event.preventDefault();
+    close();
+    return;
+  }
+  if (index !== undefined) {
+    event.preventDefault();
+    items[index]?.focus();
+  }
+}
+
+export function clampMenuPosition(x, y, width, height, viewportWidth, viewportHeight) {
+  return {
+    x: Math.max(8, Math.min(x, viewportWidth - width - 8)),
+    y: Math.max(8, Math.min(y, viewportHeight - height - 8)),
+  };
+}