@birdycom/omniaui-react 0.0.0-stage → 0.11.0

package/src/components/Toast.tsx

@@ -0,0 +1,138 @@
+"use client";
+
+import { createContext, forwardRef, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+import type { HTMLAttributes, ReactNode } from "react";
+import { cx } from "../utils";
+
+export type ToastVariant = "success" | "error" | "warning" | "info";
+
+const GLYPHS: Record<ToastVariant, string> = { success: "✓", error: "!", warning: "!", info: "i" };
+
+export interface ToastProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
+  variant?: ToastVariant;
+  title: ReactNode;
+  description?: ReactNode;
+  /** Custom status glyph (defaults per variant). */
+  icon?: ReactNode;
+  /** Shows the dismiss button. */
+  onDismiss?: () => void;
+  dismissLabel?: string;
+}
+
+/** One `.oc-toast` notification (`role="alert"` for errors, `status` otherwise). */
+export const Toast = forwardRef<HTMLDivElement, ToastProps>(function Toast(
+  { variant = "info", title, description, icon, onDismiss, dismissLabel = "Dismiss", className, ...rest },
+  ref,
+) {
+  return (
+    <div ref={ref} className={cx("oc-toast", `oc-toast--${variant}`, className)} role={variant === "error" ? "alert" : "status"} {...rest}>
+      <span className="oc-toast-icon" aria-hidden="true">{icon ?? GLYPHS[variant]}</span>
+      <div className="oc-toast-body">
+        <p className="oc-toast-title">{title}</p>
+        {description != null && <p className="oc-toast-description">{description}</p>}
+      </div>
+      {onDismiss && (
+        <button className="oc-toast-close" type="button" aria-label={dismissLabel} onClick={onDismiss}>&times;</button>
+      )}
+    </div>
+  );
+});
+
+/** `.oc-toast-container` (fixed bottom right; `top` or `static` for in-flow). */
+export const ToastContainer = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement> & { top?: boolean; static?: boolean }>(function ToastContainer(
+  { top, static: isStatic, className, ...rest },
+  ref,
+) {
+  return (
+    <div
+      ref={ref}
+      className={cx("oc-toast-container", top && "oc-toast-container--top", isStatic && "oc-toast-container--static", className)}
+      {...rest}
+    />
+  );
+});
+
+export interface ToastOptions {
+  variant?: ToastVariant;
+  title: ReactNode;
+  description?: ReactNode;
+  /** Auto-dismiss after ms (default 5000). Use 0 to keep the toast until dismissed. */
+  duration?: number;
+}
+
+interface ToastEntry extends ToastOptions {
+  id: number;
+}
+
+interface ToastApi {
+  /** Queue a toast; returns its id. */
+  toast: (options: ToastOptions) => number;
+  dismiss: (id?: number) => void;
+}
+
+const ToastContext = createContext<ToastApi | null>(null);
+
+export interface ToastProviderProps {
+  children?: ReactNode;
+  /** Stack at the top instead of the bottom. */
+  top?: boolean;
+  /** Default auto-dismiss in ms (default 5000). */
+  duration?: number;
+  /** Maximum toasts shown at once (oldest are dropped; default 5). */
+  limit?: number;
+}
+
+/** Holds the toast queue and renders the fixed `.oc-toast-container`. Use `useToast()` below it. */
+export function ToastProvider({ children, top, duration = 5000, limit = 5 }: ToastProviderProps) {
+  const [items, setItems] = useState<ToastEntry[]>([]);
+  const nextId = useRef(1);
+  const timers = useRef(new Map<number, ReturnType<typeof setTimeout>>());
+
+  const dismiss = useCallback((id?: number) => {
+    if (id === undefined) {
+      timers.current.forEach(clearTimeout);
+      timers.current.clear();
+      setItems([]);
+      return;
+    }
+    clearTimeout(timers.current.get(id));
+    timers.current.delete(id);
+    setItems((list) => list.filter((t) => t.id !== id));
+  }, []);
+
+  const toast = useCallback(
+    (options: ToastOptions) => {
+      const id = nextId.current++;
+      setItems((list) => [...list, { ...options, id }].slice(-limit));
+      const ms = options.duration ?? duration;
+      if (ms > 0) timers.current.set(id, setTimeout(() => dismiss(id), ms));
+      return id;
+    },
+    [dismiss, duration, limit],
+  );
+
+  useEffect(() => {
+    const map = timers.current;
+    return () => map.forEach(clearTimeout);
+  }, []);
+
+  const api = useMemo(() => ({ toast, dismiss }), [toast, dismiss]);
+
+  return (
+    <ToastContext.Provider value={api}>
+      {children}
+      <ToastContainer top={top} aria-live="polite">
+        {items.map((t) => (
+          <Toast key={t.id} variant={t.variant} title={t.title} description={t.description} onDismiss={() => dismiss(t.id)} />
+        ))}
+      </ToastContainer>
+    </ToastContext.Provider>
+  );
+}
+
+/** `const { toast, dismiss } = useToast()`: needs a surrounding `<ToastProvider>`. */
+export function useToast(): ToastApi {
+  const ctx = useContext(ToastContext);
+  if (!ctx) throw new Error("useToast must be used inside <ToastProvider>");
+  return ctx;
+}

package/src/components/ToggleField.tsx

@@ -0,0 +1,39 @@
+// File: packages/react/src/components/ToggleField.tsx
+// Map: props -> component (label row: text block + span.oc-switch with checkbox)
+// Same markup as packages/ui/snippets/toggle-field.html. Works controlled (checked) or uncontrolled.
+"use client";
+
+import { forwardRef, useId } from "react";
+import type { InputHTMLAttributes, ReactNode } from "react";
+import { cx } from "../utils";
+
+export interface ToggleFieldProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "role"> {
+  label: ReactNode;
+  description?: ReactNode;
+  /** Bordered box. */
+  card?: boolean;
+  /** Switch first, text after it. */
+  reverse?: boolean;
+  /** Class for the row (`className` goes to the input). */
+  fieldClassName?: string;
+}
+
+/** `.oc-toggle-field`: the whole row is the label, so clicking the text flips the switch. */
+export const ToggleField = forwardRef<HTMLInputElement, ToggleFieldProps>(function ToggleField(
+  { label, description, card, reverse, fieldClassName, className, ...rest },
+  ref,
+) {
+  const descId = `oc-toggle-field-${useId().replace(/:/g, "")}`;
+  return (
+    <label className={cx("oc-toggle-field", card && "oc-toggle-field--card", reverse && "oc-toggle-field--reverse", fieldClassName)}>
+      <span className="oc-toggle-field-text">
+        <span className="oc-toggle-field-label">{label}</span>
+        {description != null && <span className="oc-toggle-field-description" id={descId}>{description}</span>}
+      </span>
+      <span className="oc-switch">
+        <input ref={ref} type="checkbox" role="switch" className={className} aria-describedby={description != null ? descId : undefined} {...rest} />
+        <span className="oc-switch-track" />
+      </span>
+    </label>
+  );
+});

package/src/components/Tooltip.tsx

@@ -0,0 +1,14 @@
+import { forwardRef } from "react";
+import type { HTMLAttributes, ReactNode } from "react";
+import { cx } from "../utils";
+
+export interface TooltipProps extends Omit<HTMLAttributes<HTMLSpanElement>, "content"> {
+  /** Tooltip text (`data-tooltip`). */
+  content: string;
+  children: ReactNode;
+}
+
+/** `<span class="oc-tooltip" data-tooltip>`: CSS-only tooltip around its children. */
+export const Tooltip = forwardRef<HTMLSpanElement, TooltipProps>(function Tooltip({ content, className, ...rest }, ref) {
+  return <span ref={ref} className={cx("oc-tooltip", className)} data-tooltip={content} {...rest} />;
+});

package/src/components/TopProgress.tsx

@@ -0,0 +1,54 @@
+// File: packages/react/src/components/TopProgress.tsx
+// Map: TopProgress = progress.oc-top-progress -> phase state (hidden / active / done) -> fade-out timer
+// `active` true shows the bar. When it turns false the bar gets `.is-done` (fades out),
+// and after the fade it is hidden again. Without `value` the bar is indeterminate.
+"use client";
+
+import { forwardRef, useEffect, useState } from "react";
+import type { ProgressHTMLAttributes } from "react";
+import { cx } from "../utils";
+
+export type TopProgressTone = "default" | "success" | "warning" | "danger" | "brand";
+
+export interface TopProgressProps extends ProgressHTMLAttributes<HTMLProgressElement> {
+  /** Show the bar (a request or page load is running). Default true. */
+  active?: boolean;
+  tone?: TopProgressTone;
+  /** 4px instead of 2px. */
+  large?: boolean;
+  /** In the normal flow (e.g. inside a card) instead of fixed at the top. */
+  static?: boolean;
+  /** Fade-out time in ms before the bar is hidden. */
+  fadeMs?: number;
+}
+
+type Phase = "hidden" | "active" | "done";
+
+/** `progress.oc-top-progress`: thin loading bar at the top of the page. */
+export const TopProgress = forwardRef<HTMLProgressElement, TopProgressProps>(function TopProgress(
+  { active = true, tone = "default", large, static: inFlow, fadeMs = 400, className, ...rest },
+  ref,
+) {
+  const [phase, setPhase] = useState<Phase>(active ? "active" : "hidden");
+
+  useEffect(() => {
+    if (active) {
+      setPhase("active");
+      return;
+    }
+    // Only fade out when the bar was visible; keep it hidden otherwise.
+    setPhase((p) => (p === "hidden" ? "hidden" : "done"));
+    const timer = setTimeout(() => setPhase("hidden"), fadeMs);
+    return () => clearTimeout(timer);
+  }, [active, fadeMs]);
+
+  const cls = cx(
+    "oc-top-progress",
+    tone !== "default" && `oc-top-progress--${tone}`,
+    large && "oc-top-progress--lg",
+    inFlow && "oc-top-progress--static",
+    phase === "done" && "is-done",
+    className,
+  );
+  return <progress ref={ref} className={cls} hidden={phase === "hidden"} {...rest} />;
+});

package/src/components/Tree.tsx

@@ -0,0 +1,97 @@
+// File: packages/react/src/components/Tree.tsx
+// Map: Tree = box -> optional head row -> list -> TreeNode (folder = details/summary, leaf = div row) -> nested list
+// Folders open and close natively (<details>), so there is no state here.
+import { forwardRef } from "react";
+import type { HTMLAttributes, ReactNode } from "react";
+import { cx } from "../utils";
+
+export interface TreeItem {
+  label: ReactNode;
+  /** Leaf link target (renders the label as `a.oc-tree-label`). */
+  href?: string;
+  icon?: ReactNode;
+  count?: ReactNode;
+  actions?: ReactNode;
+  /** Child items: makes this item a folder. */
+  children?: TreeItem[];
+  /** Folder starts open. */
+  open?: boolean;
+  /** Current / selected item. */
+  current?: boolean;
+  muted?: boolean;
+}
+
+export interface TreeProps extends HTMLAttributes<HTMLDivElement> {
+  items: TreeItem[];
+  /** Sticky root row content (label), with optional `headActions`. */
+  head?: ReactNode;
+  headActions?: ReactNode;
+  /** Actions only show on hover / focus. */
+  quiet?: boolean;
+  /** No card frame. */
+  flush?: boolean;
+}
+
+/** The row content: icon, label (link or text), count, actions. */
+function RowContent({ item }: { item: TreeItem }) {
+  const isLink = item.href !== undefined;
+  return (
+    <>
+      {item.icon != null && <span className="oc-tree-icon" aria-hidden="true">{item.icon}</span>}
+      {isLink ? (
+        <a className="oc-tree-label" href={item.href} aria-current={item.current ? "true" : undefined}>{item.label}</a>
+      ) : (
+        <span className="oc-tree-label">{item.label}</span>
+      )}
+      {item.count != null && <span className="oc-tree-count">{item.count}</span>}
+      {item.actions != null && <span className="oc-tree-actions">{item.actions}</span>}
+    </>
+  );
+}
+
+function TreeNode({ item }: { item: TreeItem }) {
+  // aria-current on the row only when the label is not a link (a link carries it itself).
+  const rowCurrent = item.current && item.href === undefined ? "true" : undefined;
+  const rowCls = cx("oc-tree-row", item.muted && "is-muted");
+  if (!item.children?.length) {
+    return (
+      <li>
+        <div className={rowCls} aria-current={rowCurrent}><RowContent item={item} /></div>
+      </li>
+    );
+  }
+  return (
+    <li>
+      <details className="oc-tree-node" open={item.open}>
+        <summary className={rowCls} aria-current={rowCurrent}><RowContent item={item} /></summary>
+        <TreeList items={item.children} />
+      </details>
+    </li>
+  );
+}
+
+function TreeList({ items }: { items: TreeItem[] }) {
+  return (
+    <ul className="oc-tree-list">
+      {items.map((item, i) => <TreeNode item={item} key={i} />)}
+    </ul>
+  );
+}
+
+/** `.oc-tree`: nested tree list with a sticky action column. */
+export const Tree = forwardRef<HTMLDivElement, TreeProps>(function Tree(
+  { items, head, headActions, quiet, flush, className, ...rest },
+  ref,
+) {
+  return (
+    <div ref={ref} className={cx("oc-tree", quiet && "oc-tree--quiet", flush && "oc-tree--flush", className)} {...rest}>
+      {head != null && (
+        <div className="oc-tree-row oc-tree-head">
+          <span className="oc-tree-label">{head}</span>
+          {headActions != null && <span className="oc-tree-actions">{headActions}</span>}
+        </div>
+      )}
+      <TreeList items={items} />
+    </div>
+  );
+});

package/src/components/UpgradeBanner.tsx

@@ -0,0 +1,62 @@
+// File: packages/react/src/components/UpgradeBanner.tsx
+// Map: UpgradeBanner = aside -> icon -> body (title + plan pill, text, usage meter) -> actions -> dismiss button
+// The dismiss button only shows when `onDismiss` is given; your app then hides or removes the banner.
+import { forwardRef } from "react";
+import type { HTMLAttributes, ReactNode } from "react";
+import { cx } from "../utils";
+
+export interface UpgradeBannerUsage {
+  label: ReactNode;
+  value: number;
+  max: number;
+}
+
+export interface UpgradeBannerProps extends Omit<HTMLAttributes<HTMLElement>, "title"> {
+  title: ReactNode;
+  /** Plan pill next to the title, e.g. "Free". */
+  plan?: ReactNode;
+  /** Explanation; also accepted as children. */
+  text?: ReactNode;
+  usage?: UpgradeBannerUsage;
+  icon?: ReactNode;
+  actions?: ReactNode;
+  premium?: boolean;
+  compact?: boolean;
+  onDismiss?: () => void;
+  dismissLabel?: string;
+}
+
+/** `.oc-upgrade-banner`: free-plan limits callout with an upgrade action. */
+export const UpgradeBanner = forwardRef<HTMLElement, UpgradeBannerProps>(function UpgradeBanner(
+  { title, plan, text, usage, icon, actions, premium, compact, onDismiss, dismissLabel = "Dismiss", className, children, ...rest },
+  ref,
+) {
+  const cls = cx("oc-upgrade-banner", premium && "oc-upgrade-banner--premium", compact && "oc-upgrade-banner--compact", className);
+  const body = text ?? children;
+  return (
+    <aside ref={ref} className={cls} {...rest}>
+      {icon != null && <span className="oc-upgrade-banner-icon" aria-hidden="true">{icon}</span>}
+      <div className="oc-upgrade-banner-body">
+        <p className="oc-upgrade-banner-title">
+          {title}
+          {plan != null && <> <span className="oc-upgrade-banner-plan">{plan}</span></>}
+        </p>
+        {body != null && <p className="oc-upgrade-banner-text">{body}</p>}
+        {usage && (
+          <div className="oc-upgrade-banner-usage">
+            <span>{usage.label}</span>
+            {/* low / high make the meter turn "less good" near the limit. */}
+            <meter className="oc-upgrade-banner-meter" min={0} max={usage.max} low={usage.max * 0.6} high={usage.max * 0.8} optimum={0} value={usage.value}>
+              {usage.value} of {usage.max}
+            </meter>
+            <span>{usage.value} / {usage.max}</span>
+          </div>
+        )}
+      </div>
+      {actions != null && <div className="oc-upgrade-banner-actions">{actions}</div>}
+      {onDismiss && (
+        <button className="oc-upgrade-banner-dismiss" type="button" aria-label={dismissLabel} onClick={onDismiss}>×</button>
+      )}
+    </aside>
+  );
+});

package/src/components/User.tsx

@@ -0,0 +1,31 @@
+import { forwardRef } from "react";
+import type { HTMLAttributes, ReactNode } from "react";
+import { cx } from "../utils";
+import { Avatar } from "./Avatar";
+import type { AvatarSize } from "./Avatar";
+
+export interface UserProps extends HTMLAttributes<HTMLDivElement> {
+  name: ReactNode;
+  email?: ReactNode;
+  /** Initials shown in the avatar. */
+  initials?: string;
+  /** Avatar image URL (wins over initials). */
+  avatarSrc?: string;
+  avatarSize?: AvatarSize;
+}
+
+/** `.oc-user`: avatar with name and e-mail. */
+export const User = forwardRef<HTMLDivElement, UserProps>(function User(
+  { name, email, initials, avatarSrc, avatarSize = "md", className, ...rest },
+  ref,
+) {
+  return (
+    <div ref={ref} className={cx("oc-user", className)} {...rest}>
+      <Avatar size={avatarSize} src={avatarSrc}>{initials}</Avatar>
+      <span className="oc-user-text">
+        <span className="oc-user-name">{name}</span>
+        {email != null && <span className="oc-user-email">{email}</span>}
+      </span>
+    </div>
+  );
+});

package/src/components/VersionBanner.tsx

@@ -0,0 +1,41 @@
+// File: packages/react/src/components/VersionBanner.tsx
+// Map: VersionBanner = chip (role=status) -> dot -> long text -> short text -> reload action
+// Renders nothing while `version` is empty. Your app sets `version` when it sees a newer build.
+import { forwardRef } from "react";
+import type { HTMLAttributes, ReactNode } from "react";
+import { cx } from "../utils";
+
+export interface VersionBannerProps extends HTMLAttributes<HTMLDivElement> {
+  /** The new version, e.g. "v0.6.0". Empty = no banner. */
+  version?: string | null;
+  /** Long text; default "New version (vX) available - reload the page". */
+  text?: ReactNode;
+  /** Short text below 40rem; default "New version". */
+  short?: ReactNode;
+  actionLabel?: ReactNode;
+  /** Custom reload; without it the action is a plain link to the current page. */
+  onReload?: () => void;
+  tone?: "warning" | "info" | "success";
+  floating?: boolean;
+}
+
+/** `.oc-version-banner`: "new version available - reload" chip. */
+export const VersionBanner = forwardRef<HTMLDivElement, VersionBannerProps>(function VersionBanner(
+  { version, text, short = "New version", actionLabel = "Reload", onReload, tone = "warning", floating, className, ...rest },
+  ref,
+) {
+  if (!version) return null;
+  const cls = cx("oc-version-banner", tone !== "warning" && `oc-version-banner--${tone}`, floating && "oc-version-banner--floating", className);
+  return (
+    <div ref={ref} className={cls} role="status" {...rest}>
+      <span className="oc-version-banner-dot" aria-hidden="true" />
+      <span className="oc-version-banner-text">{text ?? `New version (${version}) available - reload the page`}</span>
+      <span className="oc-version-banner-short">{short}</span>
+      {onReload ? (
+        <button className="oc-version-banner-action" type="button" onClick={onReload}>{actionLabel}</button>
+      ) : (
+        <a className="oc-version-banner-action" href="">{actionLabel}</a>
+      )}
+    </div>
+  );
+});

package/src/hooks.tsx

@@ -0,0 +1,141 @@
+"use client";
+
+import { createContext, useCallback, useContext, useEffect, useRef, useState } from "react";
+import type { RefObject, SyntheticEvent } from "react";
+
+/** Merge several refs into one callback ref. */
+export function useMergedRef<T>(...refs: Array<React.Ref<T> | undefined>) {
+  return useCallback((node: T | null) => {
+    for (const ref of refs) {
+      if (typeof ref === "function") ref(node);
+      else if (ref) (ref as React.MutableRefObject<T | null>).current = node;
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, refs);
+}
+
+/** Controlled + uncontrolled value in one hook. */
+export function useControllable<T>(value: T | undefined, defaultValue: T, onChange?: (v: T) => void) {
+  const [inner, setInner] = useState<T>(defaultValue);
+  const controlled = value !== undefined;
+  const current = controlled ? (value as T) : inner;
+  const set = useCallback(
+    (next: T) => {
+      if (!controlled) setInner(next);
+      onChange?.(next);
+    },
+    [controlled, onChange],
+  );
+  return [current, set] as const;
+}
+
+export interface DialogState {
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+}
+
+export const DialogContext = createContext<{ close: () => void } | null>(null);
+export const useDialogContext = () => useContext(DialogContext);
+
+/**
+ * Keeps a native <dialog> in sync with an `open` prop: showModal() / close() in an effect,
+ * and reports native closes (Escape, backdrop, form method=dialog) through onOpenChange.
+ */
+export function useDialog(ref: RefObject<HTMLDialogElement | null>, { open, defaultOpen, onOpenChange }: DialogState) {
+  const [isOpen, setOpen] = useControllable<boolean>(open, defaultOpen ?? false, onOpenChange);
+  const openRef = useRef(isOpen);
+  openRef.current = isOpen;
+
+  useEffect(() => {
+    const dialog = ref.current;
+    if (!dialog) return;
+    if (isOpen && !dialog.open) dialog.showModal?.();
+    else if (!isOpen && dialog.open) dialog.close?.();
+  }, [isOpen, ref]);
+
+  const onClose = useCallback(
+    (e: SyntheticEvent<HTMLDialogElement>) => {
+      e.stopPropagation();
+      if (openRef.current) setOpen(false);
+    },
+    [setOpen],
+  );
+  const close = useCallback(() => setOpen(false), [setOpen]);
+  return { open: isOpen, setOpen, close, onClose };
+}
+
+/* ---------------------------------------------------------------------------------------------
+ * Menu keyboard helpers (shared by DropdownMenu, Menubar and ContextMenu)
+ * ------------------------------------------------------------------------------------------- */
+
+/** Focusable items that belong directly to a `[role=menu]` (sub-menu triggers included, sub-menu items excluded). */
+export function menuItems(menu: Element): HTMLElement[] {
+  const out: HTMLElement[] = [];
+  for (const child of Array.from(menu.children)) {
+    if (child.matches('[role^="menuitem"]')) out.push(child as HTMLElement);
+    else if (child.classList.contains("oc-dropdown-sub") && child.firstElementChild) out.push(child.firstElementChild as HTMLElement);
+  }
+  return out.filter((el) => el.getAttribute("aria-disabled") !== "true" && !(el as HTMLButtonElement).disabled);
+}
+
+/**
+ * Roving focus inside an `.oc-dropdown-menu[role=menu]`: ArrowDown / ArrowUp (wrapping), Home, End,
+ * ArrowRight on a sub-menu trigger enters the sub-menu, ArrowLeft inside a sub-menu returns to its trigger.
+ * Returns `true` (and calls preventDefault) when the key was handled.
+ */
+export function handleMenuKeyDown(e: React.KeyboardEvent<HTMLElement>): boolean {
+  const item = (e.target as HTMLElement).closest<HTMLElement>('[role^="menuitem"]');
+  const menu = item?.closest<HTMLElement>('[role="menu"]');
+  if (!item || !menu) return false;
+  const items = menuItems(menu);
+  const at = items.indexOf(item);
+  let next: HTMLElement | undefined;
+  switch (e.key) {
+    case "ArrowDown":
+      next = items[(at + 1) % items.length];
+      break;
+    case "ArrowUp":
+      next = items[(at - 1 + items.length) % items.length];
+      break;
+    case "Home":
+      next = items[0];
+      break;
+    case "End":
+      next = items[items.length - 1];
+      break;
+    case "ArrowRight": {
+      const sub = item.parentElement?.classList.contains("oc-dropdown-sub") ? item.parentElement.querySelector<HTMLElement>(".oc-dropdown-submenu") : null;
+      next = sub ? menuItems(sub)[0] : undefined;
+      break;
+    }
+    case "ArrowLeft":
+      if (menu.classList.contains("oc-dropdown-submenu")) next = menu.parentElement?.firstElementChild as HTMLElement | undefined;
+      break;
+    default:
+      return false;
+  }
+  if (!next) return false;
+  e.preventDefault();
+  e.stopPropagation();
+  next.focus();
+  return true;
+}
+
+/** Closes the popover a menu item lives in. */
+export function closeMenuOf(el: Element | null) {
+  (el?.closest("[popover]") as (HTMLElement & { hidePopover?: () => void }) | null)?.hidePopover?.();
+}
+
+/** Focuses the first menu item whenever the popover opens (the native `toggle` event). */
+export function useMenuAutofocus(ref: RefObject<HTMLElement | null>) {
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    const onToggle = (e: Event) => {
+      if ((e as Event & { newState?: string }).newState === "open") menuItems(el)[0]?.focus();
+    };
+    el.addEventListener("toggle", onToggle);
+    return () => el.removeEventListener("toggle", onToggle);
+  }, [ref]);
+}