makersclaw 0.1.0

package/templates/next/files/components/parts/fixture.jsx

@@ -0,0 +1,60 @@
+"use client";
+
+import { useMemo, useState } from "react";
+import { markSample } from "../../lib/sample";
+import { Button, Notice } from "../ui";
+
+// The worked example, never persisted. A surface opens populated (README
+// §3: the template test) — but populated is not persisted. The example is
+// rows in the app's code, shown while the real collection is empty and
+// never INSERTed: the workspace database is shared by every app, so an
+// invented row there is a real row somewhere else. Clearing writes
+// nothing; the first real write is the user's.
+//
+//   const { rows, isFixture, clear } = useFixture(realRows, SAMPLE);
+//   {isFixture ? <FixtureNotice onClear={clear} /> : null}
+//
+// A fixture row carries `_sample: true` and a `sample-N` id. Editing one
+// promotes it: the surface copies its values into a new draft and saves
+// THAT — it never updateRow()s a sample id (the row does not exist).
+//
+// `rows` keeps its identity between renders (an effect may depend on it);
+// declare SAMPLE at module level, not inside the component, so it does too.
+
+const NONE = [];
+
+export function useFixture(rows, sample, { idColumn = "id" } = {}) {
+  const [cleared, setCleared] = useState(false);
+  const isFixture = !cleared && (!rows || rows.length === 0) && Array.isArray(sample) && sample.length > 0;
+  const fixtureRows = useMemo(() => markSample(sample, idColumn), [sample, idColumn]);
+  return {
+    rows: isFixture ? fixtureRows : rows ?? NONE,
+    isFixture,
+    clear: () => setCleared(true),
+    restore: () => setCleared(false),
+  };
+}
+
+export function isSample(row) {
+  return Boolean(row && row._sample);
+}
+
+/** The line above a fixture, with the one control it earns. */
+export function FixtureNotice({ onClear, children, className }) {
+  return (
+    <Notice
+      tone="info"
+      title="Example only"
+      className={className}
+      action={
+        onClear ? (
+          <Button variant="quiet" size="sm" onClick={onClear}>
+            Clear the example
+          </Button>
+        ) : null
+      }
+    >
+      {children ?? "Edit it or start your own. Nothing here is saved until you save it."}
+    </Notice>
+  );
+}

package/templates/next/files/components/parts/index.js

@@ -0,0 +1,5 @@
+// Parts: the kit's pieces bound to this template's data layer. Each
+// exists because an app got it wrong once; each carries the behaviour
+// that makes it right. README §3b.
+export { useFixture, isSample, FixtureNotice } from "./fixture";
+export { RecordSwitcher } from "./record-switcher";

package/templates/next/files/components/parts/record-switcher.jsx

@@ -0,0 +1,49 @@
+"use client";
+
+import { useId } from "react";
+import { Button, Select } from "../ui";
+
+// Pick a saved record, or make a new one. With nothing saved there is
+// nothing to pick, so it shows the one control that has a job: New. A
+// disabled dropdown reading "No saved…" is a control that cannot be used
+// drawn at full weight — the thing this part exists to prevent.
+//
+//   <RecordSwitcher rows={drafts} value={draft.id} onChange={choose}
+//                   labelOf={(r) => r.title} onNew={newDraft} newLabel="New draft" />
+
+export function RecordSwitcher({ rows, value, onChange, labelOf = (r) => r.title ?? r.name ?? r.id, onNew, newLabel = "New", label = "Saved", idColumn = "id", className }) {
+  const id = useId();
+  const live = (rows ?? []).filter((r) => !r._sample);
+  if (live.length === 0) {
+    return onNew ? (
+      <div className={className}>
+        <Button variant="secondary" icon="plus" onClick={onNew}>
+          {newLabel}
+        </Button>
+      </div>
+    ) : null;
+  }
+  return (
+    <div className={["flex items-end gap-2", className].filter(Boolean).join(" ")}>
+      <label htmlFor={id} className="sr-only">
+        {label}
+      </label>
+      <div className="min-w-0 flex-1">
+        <Select
+          id={id}
+          value={value ?? ""}
+          onChange={(e) => onChange?.(e.target.value)}
+          options={[
+            ...(value ? [] : [{ value: "", label: `${label}…` }]),
+            ...live.map((r) => ({ value: String(r[idColumn]), label: labelOf(r) })),
+          ]}
+        />
+      </div>
+      {onNew ? (
+        <Button variant="secondary" icon="plus" onClick={onNew}>
+          {newLabel}
+        </Button>
+      ) : null}
+    </div>
+  );
+}

package/templates/next/files/components/ui/button.jsx

@@ -0,0 +1,81 @@
+import Link from "next/link";
+import { cx } from "./cx";
+import { Icon } from "./icon";
+
+// Button — every action in the app. Four looks, one shape, 44px targets
+// (mobile first: a thumb hits it). `href` makes it a next/link (base
+// path applied); `icon` names one from ./icon. Never style a <button>
+// by hand in a surface: the look is the workspace's, the behaviour is
+// the browser's, and this is the only place both meet.
+//
+//   variant   primary (the one main action per surface) · secondary ·
+//             quiet (no fill) · danger (destructive, red text) · link
+//   size      md (44px) · sm (36px, for dense rows and rails)
+
+const VARIANTS = {
+  primary: "bg-primary text-primary-foreground hover:opacity-90 border-transparent",
+  secondary: "bg-secondary text-secondary-foreground border-border hover:bg-accent",
+  quiet: "bg-transparent text-foreground border-transparent hover:bg-accent",
+  danger: "bg-transparent text-destructive border-border hover:bg-accent",
+  link: "bg-transparent text-primary underline-offset-4 hover:underline border-transparent px-0 min-h-0",
+};
+
+const SIZES = {
+  md: "min-h-11 px-4 text-sm",
+  sm: "min-h-9 px-3 text-sm",
+};
+
+export function Button({
+  variant = "secondary",
+  size = "md",
+  icon,
+  href,
+  className,
+  children,
+  type = "button",
+  ...rest
+}) {
+  const classes = cx(
+    "inline-flex items-center justify-center gap-2 rounded-md border font-medium whitespace-nowrap",
+    "outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
+    "disabled:cursor-not-allowed disabled:opacity-50",
+    VARIANTS[variant] ?? VARIANTS.secondary,
+    SIZES[size] ?? SIZES.md,
+    className,
+  );
+  const body = (
+    <>
+      {icon ? <Icon name={icon} /> : null}
+      {children}
+    </>
+  );
+  if (href) {
+    return (
+      <Link href={href} className={classes} {...rest}>
+        {body}
+      </Link>
+    );
+  }
+  return (
+    <button type={type} className={classes} {...rest}>
+      {body}
+    </button>
+  );
+}
+
+/** A square button holding only an icon; `label` is required and is what
+ *  a screen reader says. */
+export function IconButton({ icon, label, size = "md", variant = "quiet", className, ...rest }) {
+  return (
+    <Button
+      variant={variant}
+      size={size}
+      aria-label={label}
+      title={label}
+      className={cx(size === "sm" ? "w-9 px-0" : "w-11 px-0", className)}
+      {...rest}
+    >
+      <Icon name={icon} size={size === "sm" ? 16 : 18} />
+    </Button>
+  );
+}

package/templates/next/files/components/ui/cx.js

@@ -0,0 +1,4 @@
+/** Join class names, dropping falsy entries. The only helper the kit needs. */
+export function cx(...parts) {
+  return parts.flat().filter(Boolean).join(" ");
+}

package/templates/next/files/components/ui/depiction.jsx

@@ -0,0 +1,66 @@
+"use client";
+
+import { useLayoutEffect, useRef, useState } from "react";
+
+// Depiction — the frame around a picture of something that exists
+// elsewhere: a tweet as X will show it, a LinkedIn post in the feed, the
+// row an email makes in Gmail's inbox. The picture itself is a file in
+// components/depictions/<thing>.jsx and wears THAT place's colours, face
+// and widths (README §3c); this frame is the boundary where the
+// workspace theme stops. app/globals.css resets the inherited face, size,
+// letter-spacing and density on [data-depiction] and sets color-scheme
+// from data-scheme, so nothing of the workspace reaches the picture.
+//
+//   <Depiction of="x-post" scheme="dark" width={600} label="On X · Dim">
+//     <XPost text={draft.text} name={me.name} handle={me.handle} mode="dim" />
+//   </Depiction>
+//
+//   of       the depiction file's basename; `npm run check` ties them
+//   scheme   the TARGET's light or dark — never the workspace's
+//   width    the target's real column in px (X 600, LinkedIn 555, phone 375)
+//   label    the caption, chrome, in the workspace's tokens
+//
+// Scale, never reflow: line breaks and the "…more" fold ARE the preview,
+// so a narrow column shrinks the picture (transform) instead of
+// re-wrapping it. One ResizeObserver, no dependency. The caption sits
+// outside the reset boundary; the frame paints no ground inside it — the
+// depiction's root paints its target's page colour.
+
+export function Depiction({ of, scheme, width, label, children }) {
+  const outer = useRef(null);
+  const inner = useRef(null);
+  const [fit, setFit] = useState({ k: 1, height: undefined });
+
+  useLayoutEffect(() => {
+    const o = outer.current;
+    const i = inner.current;
+    if (!o || !i || typeof ResizeObserver === "undefined") return;
+    const measure = () => {
+      const k = Math.min(1, o.clientWidth / width);
+      setFit({ k, height: Math.round(i.offsetHeight * k) });
+    };
+    measure();
+    const ro = new ResizeObserver(measure);
+    ro.observe(o);
+    ro.observe(i);
+    return () => ro.disconnect();
+  }, [width]);
+
+  return (
+    <figure className="min-w-0">
+      <figcaption className="mb-2 text-2xs font-medium uppercase tracking-wider text-muted-foreground">
+        {label ?? `How it will look · ${of}`}
+      </figcaption>
+      <div ref={outer} className="overflow-hidden" style={{ height: fit.height }}>
+        <div
+          ref={inner}
+          data-depiction={of}
+          data-scheme={scheme}
+          style={{ width, transform: fit.k === 1 ? undefined : `scale(${fit.k})`, transformOrigin: "top left" }}
+        >
+          {children}
+        </div>
+      </div>
+    </figure>
+  );
+}

package/templates/next/files/components/ui/field.jsx

@@ -0,0 +1,126 @@
+import { cx } from "./cx";
+
+// Form parts. Each is the native element with the workspace's look and a
+// 44px target; the browser supplies the behaviour (focus, keyboard,
+// validation, autofill). Wrap one in <Field> for its label, hint and
+// error — never a bare <input> with a <div> label beside it.
+
+const CONTROL =
+  "w-full min-h-11 rounded-md border border-input bg-background px-3 text-sm text-foreground " +
+  "placeholder:text-muted-foreground outline-none focus-visible:ring-2 focus-visible:ring-ring " +
+  "disabled:cursor-not-allowed disabled:opacity-50 aria-[invalid=true]:border-destructive";
+
+/** Label, control, hint and error in one stack. Pass `id`; the label
+ *  points at it. `error` (a string) marks the control invalid. */
+export function Field({ id, label, hint, error, required, className, children }) {
+  return (
+    <div className={cx("grid gap-1.5", className)}>
+      {label ? (
+        <label htmlFor={id} className="text-sm font-medium text-foreground">
+          {label}
+          {required ? <span aria-hidden="true" className="text-destructive"> *</span> : null}
+        </label>
+      ) : null}
+      {children}
+      {error ? (
+        <p id={id ? `${id}-error` : undefined} role="alert" className="text-xs text-destructive">
+          {error}
+        </p>
+      ) : hint ? (
+        <p id={id ? `${id}-hint` : undefined} className="text-xs text-muted-foreground">
+          {hint}
+        </p>
+      ) : null}
+    </div>
+  );
+}
+
+export function Input({ className, invalid, ...rest }) {
+  return <input className={cx(CONTROL, className)} aria-invalid={invalid ? true : undefined} {...rest} />;
+}
+
+export function Textarea({ className, invalid, rows = 4, ...rest }) {
+  return (
+    <textarea
+      rows={rows}
+      className={cx(CONTROL, "min-h-24 resize-y py-2.5 leading-normal", className)}
+      aria-invalid={invalid ? true : undefined}
+      {...rest}
+    />
+  );
+}
+
+/**
+ * The native <select>, styled. `options` is [{ value, label }]; children
+ * work too. A select with nothing to choose from is not a control — when
+ * `options` is empty it renders `empty` (a short muted line, or nothing
+ * when `empty` is null) rather than a disabled dropdown. For "pick a
+ * saved record or make a new one" use RecordSwitcher (components/parts).
+ */
+export function Select({ options, empty = "Nothing to choose yet.", className, invalid, children, ...rest }) {
+  if (options && options.length === 0 && !children) {
+    return empty ? <p className="text-sm text-muted-foreground">{empty}</p> : null;
+  }
+  return (
+    <span className="relative block">
+      <select
+        className={cx(CONTROL, "appearance-none pr-9", className)}
+        aria-invalid={invalid ? true : undefined}
+        {...rest}
+      >
+        {options ? options.map((o) => <option key={o.value} value={o.value}>{o.label}</option>) : children}
+      </select>
+      <svg
+        aria-hidden="true"
+        className="pointer-events-none absolute right-3 top-1/2 -translate-y-1/2 text-muted-foreground"
+        width="16"
+        height="16"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="1.8"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <path d="m6 9 6 6 6-6" />
+      </svg>
+    </span>
+  );
+}
+
+/** An on/off. A checkbox underneath (role=switch), so forms, labels and
+ *  keyboards work; the track is drawn from tokens. */
+export function Switch({ id, checked, onChange, label, disabled, className }) {
+  return (
+    <label htmlFor={id} className={cx("inline-flex min-h-11 cursor-pointer items-center gap-3 text-sm", disabled && "cursor-not-allowed opacity-50", className)}>
+      <span className="relative inline-flex h-6 w-10 shrink-0">
+        <input
+          id={id}
+          type="checkbox"
+          role="switch"
+          className="peer sr-only"
+          checked={checked}
+          onChange={onChange}
+          disabled={disabled}
+        />
+        <span className="absolute inset-0 rounded-full border border-input bg-muted transition-colors peer-checked:bg-primary peer-focus-visible:ring-2 peer-focus-visible:ring-ring" />
+        <span className="absolute left-0.5 top-0.5 h-5 w-5 rounded-full bg-foreground transition-transform peer-checked:translate-x-4 peer-checked:bg-primary-foreground" />
+      </span>
+      {label ? <span>{label}</span> : null}
+    </label>
+  );
+}
+
+export function Checkbox({ id, label, className, ...rest }) {
+  return (
+    <label htmlFor={id} className={cx("inline-flex min-h-11 cursor-pointer items-center gap-2 text-sm", className)}>
+      <input
+        id={id}
+        type="checkbox"
+        className="h-4 w-4 rounded-sm border-input accent-[var(--color-primary)] outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        {...rest}
+      />
+      {label ? <span>{label}</span> : null}
+    </label>
+  );
+}

package/templates/next/files/components/ui/icon.jsx

@@ -0,0 +1,87 @@
+// The kit's icons: one inline sprite, no icon package to install. Every
+// glyph is a 24-box stroke path; add one here, never an <svg> in a surface.
+// `name` is the key below; unknown names render nothing (and `npm run
+// check` names them).
+
+const PATHS = {
+  plus: "M12 5v14M5 12h14",
+  x: "M18 6 6 18M6 6l12 12",
+  check: "m5 12 5 5L20 7",
+  "chevron-down": "m6 9 6 6 6-6",
+  "chevron-up": "m18 15-6-6-6 6",
+  "chevron-left": "m15 18-6-6 6-6",
+  "chevron-right": "m9 18 6-6-6-6",
+  "arrow-left": "M19 12H5m7-7-7 7 7 7",
+  "arrow-right": "M5 12h14m-7-7 7 7-7 7",
+  search: "M11 4a7 7 0 1 0 0 14 7 7 0 0 0 0-14ZM21 21l-4.3-4.3",
+  trash: "M3 6h18M8 6V4h8v2m-9 0 1 14h8l1-14",
+  pencil: "M12 20h9M16.5 3.5a2.1 2.1 0 0 1 3 3L7 19l-4 1 1-4Z",
+  copy: "M8 8h12v12H8zM4 16V4h12",
+  more: "M5 12h.01M12 12h.01M19 12h.01",
+  external: "M14 3h7v7m0-7L10 14M21 14v7H3V3h7",
+  refresh: "M21 12a9 9 0 1 1-2.6-6.4M21 3v6h-6",
+  filter: "M3 5h18l-7 8v6l-4 2v-8Z",
+  calendar: "M3 5h18v16H3zM16 3v4M8 3v4M3 10h18",
+  clock: "M12 3a9 9 0 1 0 0 18 9 9 0 0 0 0-18Zm0 4v5l3 3",
+  user: "M20 21a8 8 0 0 0-16 0M12 3a5 5 0 1 0 0 10 5 5 0 0 0 0-10Z",
+  users: "M17 21a4 4 0 0 0-8 0M13 4a4 4 0 1 0 0 8 4 4 0 0 0 0-8ZM23 21a4 4 0 0 0-3-3.9M16 3.1a4 4 0 0 1 0 7.8M3 21a4 4 0 0 1 3-3.9M8 3.1a4 4 0 0 0 0 7.8",
+  mail: "M3 5h18v14H3zM3 7l9 6 9-6",
+  link: "M10 14a5 5 0 0 0 7 0l3-3a5 5 0 0 0-7-7l-1 1M14 10a5 5 0 0 0-7 0l-3 3a5 5 0 0 0 7 7l1-1",
+  grip: "M9 6h.01M15 6h.01M9 12h.01M15 12h.01M9 18h.01M15 18h.01",
+  info: "M12 3a9 9 0 1 0 0 18 9 9 0 0 0 0-18Zm0 5h.01M12 12v4",
+  warning: "M12 3 2 20h20L12 3Zm0 7v4m0 3h.01",
+  sparkles: "m12 3 2 6 6 2-6 2-2 6-2-6-6-2 6-2 2-6ZM19 15l1 2 2 1-2 1-1 2-1-2-2-1 2-1 1-2Z",
+  play: "m6 4 14 8-14 8V4Z",
+  pause: "M6 4h4v16H6zM14 4h4v16h-4z",
+  download: "M12 3v12m-5-5 5 5 5-5M4 21h16",
+  upload: "M12 21V9m-5 5 5-5 5 5M4 3h16",
+  eye: "M2 12s4-7 10-7 10 7 10 7-4 7-10 7S2 12 2 12Zm10-3a3 3 0 1 0 0 6 3 3 0 0 0 0-6Z",
+  send: "m22 2-7 20-4-9-9-4 20-7Z",
+  home: "m3 11 9-8 9 8v10h-6v-6H9v6H3V11Z",
+  settings: "M12 8a4 4 0 1 0 0 8 4 4 0 0 0 0-8Zm8 4-1.5-.5.3-1.6 1.4-.9-1-1.7-1.6.5-1.2-1.2.5-1.6-1.7-1-.9 1.4-1.6-.3L12 4l-.5 1.5-1.6.3-.9-1.4-1.7 1 .5 1.6-1.2 1.2-1.6-.5-1 1.7 1.4.9.3 1.6L4 12l1.5.5-.3 1.6-1.4.9 1 1.7 1.6-.5 1.2 1.2-.5 1.6 1.7 1 .9-1.4 1.6.3L12 20l.5-1.5 1.6-.3.9 1.4 1.7-1-.5-1.6 1.2-1.2 1.6.5 1-1.7-1.4-.9-.3-1.6L20 12Z",
+  reply: "M9 17 4 12l5-5M4 12h10a6 6 0 0 1 6 6v1",
+  repeat: "m17 2 4 4-4 4M3 11V9a3 3 0 0 1 3-3h15M7 22l-4-4 4-4M21 13v2a3 3 0 0 1-3 3H3",
+  heart: "M20.8 4.6a5.5 5.5 0 0 0-7.8 0L12 5.7l-1.1-1.1a5.5 5.5 0 0 0-7.8 7.8l1.1 1.1L12 21l7.8-7.5 1.1-1.1a5.5 5.5 0 0 0-.1-7.8Z",
+  chart: "M3 3v18h18M7 16l4-5 4 3 5-7",
+  share: "M12 3v12M7 8l5-5 5 5M5 14v6h14v-6",
+  star: "m12 3 2.8 5.7 6.2.9-4.5 4.4 1.1 6.2L12 17.3 6.4 20.2l1.1-6.2L3 9.6l6.2-.9L12 3Z",
+  bell: "M6 8a6 6 0 0 1 12 0c0 7 3 9 3 9H3s3-2 3-9M10 21a2 2 0 0 0 4 0",
+  tag: "M20 12 12 20l-9-9V3h8l9 9ZM7 7h.01",
+  folder: "M3 7V5h6l2 2h10v13H3V7Z",
+  file: "M14 3H6v18h12V7l-4-4ZM14 3v4h4",
+  image: "M3 5h18v14H3zM8 11a1.5 1.5 0 1 0 0-3 1.5 1.5 0 0 0 0 3ZM21 15l-5-5-9 9",
+  phone: "M22 16.9v3a2 2 0 0 1-2.2 2A19.8 19.8 0 0 1 2.1 4.2 2 2 0 0 1 4.1 2h3a2 2 0 0 1 2 1.7l.8 3.6a2 2 0 0 1-.5 1.9L8.1 10.5a16 16 0 0 0 5.4 5.4l1.3-1.3a2 2 0 0 1 1.9-.5l3.6.8a2 2 0 0 1 1.7 2Z",
+  globe: "M12 3a9 9 0 1 0 0 18 9 9 0 0 0 0-18ZM3 12h18M12 3c3 3 3 15 0 18M12 3c-3 3-3 15 0 18",
+  lock: "M5 11h14v10H5zM8 11V7a4 4 0 0 1 8 0v4",
+  zap: "M13 2 3 14h8l-1 8 10-12h-8l1-8Z",
+  dollar: "M12 2v20M17 6H9.5a3.5 3.5 0 0 0 0 7h5a3.5 3.5 0 0 1 0 7H6",
+  map: "m3 6 6-3 6 3 6-3v15l-6 3-6-3-6 3V6ZM9 3v15M15 6v15",
+  minus: "M5 12h14",
+  archive: "M3 4h18v4H3zM5 8v12h14V8M10 12h4",
+  inbox: "M3 13h5l2 3h4l2-3h5M3 13V5h18v8M3 13v6h18v-6",
+};
+
+export const ICON_NAMES = Object.keys(PATHS);
+
+export function Icon({ name, size = 16, className, label }) {
+  const d = PATHS[name];
+  if (!d) return null;
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.8"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden={label ? undefined : true}
+      role={label ? "img" : undefined}
+      aria-label={label}
+      className={className}
+    >
+      <path d={d} />
+    </svg>
+  );
+}

package/templates/next/files/components/ui/index.js

@@ -0,0 +1,12 @@
+// The kit. Import from "../components/ui" (a surface) or "./ui" (a
+// component). Every part is the workspace's look over the browser's own
+// behaviour; none of them takes a colour. README §3b.
+export { cx } from "./cx";
+export { Icon, ICON_NAMES } from "./icon";
+export { Button, IconButton } from "./button";
+export { Field, Input, Textarea, Select, Switch, Checkbox } from "./field";
+export { Card, Notice, Badge, Kicker, Empty } from "./notice";
+export { Sheet, Confirm } from "./sheet";
+export { Tabs, TabPanel } from "./tabs";
+export { Menu } from "./menu";
+export { Depiction } from "./depiction";

package/templates/next/files/components/ui/menu.jsx

@@ -0,0 +1,123 @@
+"use client";
+
+import { useEffect, useId, useRef, useState } from "react";
+import { cx } from "./cx";
+import { Icon } from "./icon";
+
+// Menu — the "…" of a row, the kebab of a card. The Popover API does the
+// hard part (top layer, light dismiss, Escape); this positions it under
+// its button and moves focus with the arrow keys. `items` with nothing in
+// them render nothing: a menu is earned by having actions.
+//
+//   items   [{ label, onSelect, icon?, tone?: "danger", disabled? }]
+//   trigger a node to use as the button's content; default is the ⋯ icon
+
+export function Menu({ items, label = "More", trigger, align = "end", className }) {
+  const id = useId();
+  const btn = useRef(null);
+  const pop = useRef(null);
+  const [open, setOpen] = useState(false);
+  const live = (items ?? []).filter(Boolean);
+
+  // A fixed-positioned popover does not follow its button; close it when
+  // the page moves rather than leave it floating where the button was.
+  useEffect(() => {
+    if (!open) return;
+    const close = () => pop.current?.hidePopover();
+    window.addEventListener("resize", close);
+    window.addEventListener("scroll", close, true);
+    return () => {
+      window.removeEventListener("resize", close);
+      window.removeEventListener("scroll", close, true);
+    };
+  }, [open]);
+
+  if (live.length === 0) return null;
+
+  function place() {
+    const b = btn.current?.getBoundingClientRect();
+    const p = pop.current;
+    if (!b || !p) return;
+    p.style.position = "fixed";
+    p.style.top = `${Math.round(b.bottom + 4)}px`;
+    const width = p.offsetWidth || 200;
+    const left = align === "end" ? b.right - width : b.left;
+    p.style.left = `${Math.max(8, Math.min(left, window.innerWidth - width - 8))}px`;
+  }
+
+  function toggle() {
+    const p = pop.current;
+    if (!p) return;
+    if (p.matches(":popover-open")) p.hidePopover();
+    else {
+      p.showPopover();
+      place();
+      p.querySelector('[role="menuitem"]:not([disabled])')?.focus();
+    }
+  }
+
+  function onKeyDown(e) {
+    const nodes = [...(pop.current?.querySelectorAll('[role="menuitem"]:not([disabled])') ?? [])];
+    const i = nodes.indexOf(document.activeElement);
+    if (e.key === "ArrowDown") nodes[(i + 1) % nodes.length]?.focus();
+    else if (e.key === "ArrowUp") nodes[(i - 1 + nodes.length) % nodes.length]?.focus();
+    else if (e.key === "Home") nodes[0]?.focus();
+    else if (e.key === "End") nodes[nodes.length - 1]?.focus();
+    else if (e.key === "Tab" || e.key === "Escape") {
+      pop.current?.hidePopover();
+      btn.current?.focus();
+    } else return;
+    e.preventDefault();
+  }
+
+  return (
+    <>
+      <button
+        ref={btn}
+        type="button"
+        aria-haspopup="menu"
+        aria-expanded={open}
+        aria-controls={id}
+        aria-label={trigger ? undefined : label}
+        title={trigger ? undefined : label}
+        onClick={toggle}
+        className={cx(
+          "inline-flex min-h-9 min-w-9 items-center justify-center gap-2 rounded-md px-2 text-sm text-foreground outline-none hover:bg-accent focus-visible:ring-2 focus-visible:ring-ring",
+          className,
+        )}
+      >
+        {trigger ?? <Icon name="more" />}
+      </button>
+      <div
+        ref={pop}
+        id={id}
+        popover="auto"
+        role="menu"
+        aria-label={label}
+        onToggle={(e) => setOpen(e.newState === "open")}
+        onKeyDown={onKeyDown}
+        className="min-w-44 rounded-md border border-border bg-popover p-1 text-popover-foreground shadow-lg"
+      >
+        {live.map((item, i) => (
+          <button
+            key={i}
+            type="button"
+            role="menuitem"
+            disabled={item.disabled}
+            onClick={() => {
+              pop.current?.hidePopover();
+              item.onSelect?.();
+            }}
+            className={cx(
+              "flex w-full min-h-10 items-center gap-2 rounded-sm px-2 text-left text-sm outline-none hover:bg-accent focus-visible:bg-accent disabled:opacity-50",
+              item.tone === "danger" && "text-destructive",
+            )}
+          >
+            {item.icon ? <Icon name={item.icon} /> : null}
+            {item.label}
+          </button>
+        ))}
+      </div>
+    </>
+  );
+}