makersclaw 0.1.0 → 0.3.0

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

@@ -1,5 +1,5 @@
 import { cx } from "./cx";
-import { Button } from "./button";
+import { IconButton } from "./button";
 import { Icon } from "./icon";
 
 // Static parts: a card, a notice, a badge, a kicker, the empty state.
@@ -13,14 +13,36 @@ const TONES = {
   danger: { box: "border-destructive/50 bg-card text-card-foreground", icon: "warning" },
 };
 
-/** A raised panel with an optional heading row. */
-export function Card({ title, description, actions, className, children, as: Tag = "section" }) {
+/** A raised panel with an optional heading row.
+ *    padding     md (default, 16px) · sm (12px, a dense rail) · none (the
+ *                body runs to the border — a table, a list of rows; the
+ *                heading row keeps its own 16px inset)
+ *    titleSize   md (default, 16px) · lg (20px, a page-level card's title)
+ *  Pick these here, never with a className: cx does not merge classes,
+ *  so a `p-0` laid over the default padding wins only by CSS order. */
+const CARD_PADDING = { none: "", sm: "p-3", md: "p-4" };
+const CARD_TITLE = { md: "text-base", lg: "text-xl" };
+
+export function Card({
+  title,
+  description,
+  actions,
+  padding = "md",
+  titleSize = "md",
+  className,
+  children,
+  as: Tag = "section",
+}) {
+  const pad = CARD_PADDING[padding] ?? CARD_PADDING.md;
+  const bare = padding === "none";
   return (
-    <Tag className={cx("rounded-lg border border-border bg-card p-4 text-card-foreground", className)}>
+    <Tag className={cx("rounded-lg border border-border bg-card text-card-foreground", pad, bare && "overflow-hidden", className)}>
       {title || actions ? (
-        <div className="mb-3 flex items-start justify-between gap-3">
+        <div className={cx("flex items-start justify-between gap-3", bare ? "px-4 pt-4 pb-3" : "mb-3")}>
           <div className="min-w-0">
-            {title ? <h2 className="text-base font-semibold leading-tight">{title}</h2> : null}
+            {title ? (
+              <h2 className={cx("font-semibold leading-tight", CARD_TITLE[titleSize] ?? CARD_TITLE.md)}>{title}</h2>
+            ) : null}
             {description ? <p className="mt-0.5 text-sm text-muted-foreground">{description}</p> : null}
           </div>
           {actions ? <div className="flex shrink-0 gap-2">{actions}</div> : null}
@@ -45,25 +67,115 @@ export function Notice({ tone = "neutral", title, action, onDismiss, className,
       </div>
       {action ? <div className="shrink-0">{action}</div> : null}
       {onDismiss ? (
-        <Button variant="quiet" size="sm" onClick={onDismiss} aria-label="Dismiss" className="-my-1 -mr-1 w-9 px-0">
-          <Icon name="x" />
-        </Button>
+        <IconButton icon="x" label="Dismiss" size="sm" onClick={onDismiss} className="-my-1 -mr-1" />
       ) : null}
     </div>
   );
 }
 
-/** A small label for a state or a count. */
-export function Badge({ tone = "neutral", className, children }) {
-  const look = {
+/** A small label for a state or a count.
+ *    tone      neutral · primary · success · warning · danger · info
+ *    variant   label (default: small caps, wide tracking; primary is a
+ *              solid fill, every other tone a tint) · soft (the case as
+ *              written, normal tracking, EVERY tone a tint — primary
+ *              included: "Ready", "Daily over", "Feature") · outline (the
+ *              case as written, a tone-coloured hairline on no fill) ·
+ *              code (the mono face, the case as written, normal tracking
+ *              — a version tag "v2.4.0", a commit "a3f8c2d", a path)
+ *    hue       1..5 — a categorical colour, read from --color-chart-N,
+ *              for KINDS of things (a DNS type, a platform, a content
+ *              type). Tone is for status; hue is for category, and a
+ *              tone given with it wins. With every variant: soft is the
+ *              case as written on a tint of the hue with a hue dot and
+ *              foreground text; label (and code) is filled with the hue
+ *              and black or white text, whichever reads; outline is a
+ *              hue hairline with foreground text. The text is never the
+ *              hue itself: a chart colour is not made to be read as type
+ *  Case is a variant, not its own prop: uppercase needs wide tracking and
+ *  sentence case needs none, so the two travel together, and a `case`
+ *  prop would have to be ignored by code. A soft primary lives on `soft`
+ *  because `label` primary is a solid fill apps already rely on. The
+ *  outline's ring is inset, so every variant is the same size in a row. */
+const BADGE_LOOK = {
+  label: {
     neutral: "bg-muted text-muted-foreground",
     primary: "bg-primary text-primary-foreground",
     success: "bg-success/15 text-success",
     warning: "bg-warning/15 text-warning",
     danger: "bg-destructive/15 text-destructive",
     info: "bg-info/15 text-info",
-  }[tone];
-  return <span className={cx("inline-flex items-center rounded-sm px-1.5 py-0.5 text-2xs font-medium uppercase tracking-wide", look, className)}>{children}</span>;
+  },
+  soft: {
+    neutral: "bg-muted text-muted-foreground",
+    primary: "bg-primary/15 text-primary",
+    success: "bg-success/15 text-success",
+    warning: "bg-warning/15 text-warning",
+    danger: "bg-destructive/15 text-destructive",
+    info: "bg-info/15 text-info",
+  },
+  outline: {
+    neutral: "bg-transparent text-foreground ring-1 ring-inset ring-border",
+    primary: "bg-transparent text-primary ring-1 ring-inset ring-primary/50",
+    success: "bg-transparent text-success ring-1 ring-inset ring-success/50",
+    warning: "bg-transparent text-warning ring-1 ring-inset ring-warning/50",
+    danger: "bg-transparent text-destructive ring-1 ring-inset ring-destructive/50",
+    info: "bg-transparent text-info ring-1 ring-inset ring-info/50",
+  },
+};
+BADGE_LOOK.code = BADGE_LOOK.label;
+
+const BADGE_FACE = {
+  label: "font-medium uppercase tracking-wide",
+  soft: "font-medium",
+  outline: "font-medium",
+  code: "font-mono font-normal",
+};
+
+// Categorical hues, literal so Tailwind sees every class. A filled hue's
+// text is black or white, picked from the fill's relative luminance (the
+// WCAG formula, on the clipped sRGB channels): what CSS contrast-color()
+// does, which no token can. A chart colour sits mid-lightness (chart-2…5
+// are clamped to OKLCH L 0.55–0.8, often past sRGB), where the theme's
+// light text fails on a light theme and its dark text on a dark primary.
+// Black below Y 0.179, white above: the better of the two is always
+// 4.58:1 or more. The soft tint is light (8%) so foreground text keeps
+// its contrast.
+const HUE_LOOK = {
+  label: {
+    1: "bg-chart-1 text-[color:color(from_var(--color-chart-1)_srgb_clamp(0,(0.179_-_(0.2126*pow(clamp(0,r,1),2.2)_+_0.7152*pow(clamp(0,g,1),2.2)_+_0.0722*pow(clamp(0,b,1),2.2)))*999,1)_clamp(0,(0.179_-_(0.2126*pow(clamp(0,r,1),2.2)_+_0.7152*pow(clamp(0,g,1),2.2)_+_0.0722*pow(clamp(0,b,1),2.2)))*999,1)_clamp(0,(0.179_-_(0.2126*pow(clamp(0,r,1),2.2)_+_0.7152*pow(clamp(0,g,1),2.2)_+_0.0722*pow(clamp(0,b,1),2.2)))*999,1))]",
+    2: "bg-chart-2 text-[color:color(from_var(--color-chart-2)_srgb_clamp(0,(0.179_-_(0.2126*pow(clamp(0,r,1),2.2)_+_0.7152*pow(clamp(0,g,1),2.2)_+_0.0722*pow(clamp(0,b,1),2.2)))*999,1)_clamp(0,(0.179_-_(0.2126*pow(clamp(0,r,1),2.2)_+_0.7152*pow(clamp(0,g,1),2.2)_+_0.0722*pow(clamp(0,b,1),2.2)))*999,1)_clamp(0,(0.179_-_(0.2126*pow(clamp(0,r,1),2.2)_+_0.7152*pow(clamp(0,g,1),2.2)_+_0.0722*pow(clamp(0,b,1),2.2)))*999,1))]",
+    3: "bg-chart-3 text-[color:color(from_var(--color-chart-3)_srgb_clamp(0,(0.179_-_(0.2126*pow(clamp(0,r,1),2.2)_+_0.7152*pow(clamp(0,g,1),2.2)_+_0.0722*pow(clamp(0,b,1),2.2)))*999,1)_clamp(0,(0.179_-_(0.2126*pow(clamp(0,r,1),2.2)_+_0.7152*pow(clamp(0,g,1),2.2)_+_0.0722*pow(clamp(0,b,1),2.2)))*999,1)_clamp(0,(0.179_-_(0.2126*pow(clamp(0,r,1),2.2)_+_0.7152*pow(clamp(0,g,1),2.2)_+_0.0722*pow(clamp(0,b,1),2.2)))*999,1))]",
+    4: "bg-chart-4 text-[color:color(from_var(--color-chart-4)_srgb_clamp(0,(0.179_-_(0.2126*pow(clamp(0,r,1),2.2)_+_0.7152*pow(clamp(0,g,1),2.2)_+_0.0722*pow(clamp(0,b,1),2.2)))*999,1)_clamp(0,(0.179_-_(0.2126*pow(clamp(0,r,1),2.2)_+_0.7152*pow(clamp(0,g,1),2.2)_+_0.0722*pow(clamp(0,b,1),2.2)))*999,1)_clamp(0,(0.179_-_(0.2126*pow(clamp(0,r,1),2.2)_+_0.7152*pow(clamp(0,g,1),2.2)_+_0.0722*pow(clamp(0,b,1),2.2)))*999,1))]",
+    5: "bg-chart-5 text-[color:color(from_var(--color-chart-5)_srgb_clamp(0,(0.179_-_(0.2126*pow(clamp(0,r,1),2.2)_+_0.7152*pow(clamp(0,g,1),2.2)_+_0.0722*pow(clamp(0,b,1),2.2)))*999,1)_clamp(0,(0.179_-_(0.2126*pow(clamp(0,r,1),2.2)_+_0.7152*pow(clamp(0,g,1),2.2)_+_0.0722*pow(clamp(0,b,1),2.2)))*999,1)_clamp(0,(0.179_-_(0.2126*pow(clamp(0,r,1),2.2)_+_0.7152*pow(clamp(0,g,1),2.2)_+_0.0722*pow(clamp(0,b,1),2.2)))*999,1))]",
+  },
+  soft: {
+    1: "bg-chart-1/8 text-foreground",
+    2: "bg-chart-2/8 text-foreground",
+    3: "bg-chart-3/8 text-foreground",
+    4: "bg-chart-4/8 text-foreground",
+    5: "bg-chart-5/8 text-foreground",
+  },
+  outline: {
+    1: "bg-transparent text-foreground ring-1 ring-inset ring-chart-1",
+    2: "bg-transparent text-foreground ring-1 ring-inset ring-chart-2",
+    3: "bg-transparent text-foreground ring-1 ring-inset ring-chart-3",
+    4: "bg-transparent text-foreground ring-1 ring-inset ring-chart-4",
+    5: "bg-transparent text-foreground ring-1 ring-inset ring-chart-5",
+  },
+};
+HUE_LOOK.code = HUE_LOOK.label;
+const HUE_DOT = { 1: "bg-chart-1", 2: "bg-chart-2", 3: "bg-chart-3", 4: "bg-chart-4", 5: "bg-chart-5" };
+
+export function Badge({ tone, hue, variant = "label", className, children }) {
+  const v = BADGE_FACE[variant] ? variant : "label";
+  const h = tone == null && HUE_DOT[hue] ? hue : null;
+  const look = h ? HUE_LOOK[v][h] : BADGE_LOOK[v][tone ?? "neutral"] ?? BADGE_LOOK[v].neutral;
+  return (
+    <span className={cx("inline-flex items-center rounded-sm px-1.5 py-0.5 text-2xs", h && v === "soft" && "gap-1", BADGE_FACE[v], look, className)}>
+      {h && v === "soft" ? <span aria-hidden="true" className={cx("size-1.5 shrink-0 rounded-full", HUE_DOT[h])} /> : null}
+      {children}
+    </span>
+  );
 }
 
 /** The small uppercase line above a heading. */

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

@@ -0,0 +1,156 @@
+import { cx } from "./cx";
+import { Button } from "./button";
+import { Icon } from "./icon";
+import { Select } from "./field";
+
+// Pagination — move through a long list a page at a time. Numbers around
+// the current page with "…" for the gaps, first and last always there,
+// previous/next disabled at the ends. Two ways to move, pick one:
+// `hrefFor(page)` makes every page a link (next/link, base path applied;
+// works in a server surface, the URL is the state) or `onPageChange(page)`
+// makes them buttons (a client surface holds the page).
+//
+//   page              the current page, 1-based
+//   pageCount         how many pages there are
+//   siblings          pages shown each side of the current one (default 1)
+//   compact           always "Page 3 of 12" with previous/next; without it
+//                     a phone gets that and a wider window the numbers
+//   pageSize          with onPageSizeChange: a "Rows per page" Select
+//   pageSizes         its choices (default 10 · 25 · 50 · 100)
+//   size              md (44px targets) · sm (36px, for a dense table foot)
+//
+// One page and no page-size choice: nothing to move through, nothing drawn.
+
+/** The slots to draw: page numbers and "gap". The row is the same width
+ *  wherever the current page is, so the buttons never jump under a thumb. */
+function slots(page, count, siblings) {
+  const width = siblings * 2 + 5; // first, gap, siblings, current, siblings, gap, last
+  if (count <= width) return Array.from({ length: count }, (_, i) => i + 1);
+  const range = (a, b) => Array.from({ length: b - a + 1 }, (_, i) => a + i);
+  const edge = siblings * 2 + 3; // what a run from either end holds before its gap
+  if (page <= edge - siblings) return [...range(1, edge), "gap", count];
+  if (page > count - (edge - siblings)) return [1, "gap", ...range(count - edge + 1, count)];
+  return [1, "gap", ...range(page - siblings, page + siblings), "gap", count];
+}
+
+export function Pagination({
+  page,
+  pageCount,
+  hrefFor,
+  onPageChange,
+  siblings = 1,
+  compact = false,
+  pageSize,
+  pageSizes = [10, 25, 50, 100],
+  onPageSizeChange,
+  size = "md",
+  label = "Pagination",
+  className,
+}) {
+  const count = Math.max(1, Math.floor(pageCount || 1));
+  const current = Math.min(Math.max(1, Math.floor(page || 1)), count);
+  const sizer = Boolean(onPageSizeChange && pageSize);
+  if (count <= 1 && !sizer) return null;
+
+  const square = size === "sm" ? "min-w-9 px-2" : "min-w-11 px-2";
+
+  // One page control: a link when hrefFor is given, else a button. Past
+  // either end it is a disabled button, never a link to nowhere.
+  const go = (to, { children, current: isCurrent, className: extra, ...rest }) => {
+    const disabled = to < 1 || to > count;
+    const common = {
+      size,
+      variant: isCurrent ? "secondary" : "quiet",
+      className: extra,
+      "aria-current": isCurrent ? "page" : undefined,
+      ...rest,
+    };
+    if (disabled) return <Button {...common} disabled>{children}</Button>;
+    if (hrefFor) return <Button {...common} href={hrefFor(to)}>{children}</Button>;
+    return (
+      <Button {...common} onClick={isCurrent ? undefined : () => onPageChange?.(to)}>
+        {children}
+      </Button>
+    );
+  };
+
+  const prev = (wide) =>
+    go(current - 1, {
+      "aria-label": "Previous page",
+      className: wide ? "gap-1 pl-2 pr-3" : square,
+      children: (
+        <>
+          <Icon name="chevron-left" />
+          {wide ? <span>Previous</span> : null}
+        </>
+      ),
+    });
+  const next = (wide) =>
+    go(current + 1, {
+      "aria-label": "Next page",
+      className: wide ? "gap-1 pl-3 pr-2" : square,
+      children: (
+        <>
+          {wide ? <span>Next</span> : null}
+          <Icon name="chevron-right" />
+        </>
+      ),
+    });
+
+  const status = (
+    <span data-nums className="whitespace-nowrap px-2 text-sm text-muted-foreground">
+      Page <span className="font-medium text-foreground">{current}</span> of {count}
+    </span>
+  );
+
+  return (
+    <nav aria-label={label} className={cx("flex flex-wrap items-center justify-between gap-x-4 gap-y-2", className)}>
+      {sizer ? (
+        <label className="inline-flex items-center gap-2 text-sm text-muted-foreground">
+          <span className="whitespace-nowrap">Rows per page</span>
+          <span className="w-20">
+            <Select
+              value={String(pageSize)}
+              onChange={(e) => onPageSizeChange(Number(e.target.value))}
+              options={pageSizes.map((n) => ({ value: String(n), label: String(n) }))}
+            />
+          </span>
+        </label>
+      ) : null}
+
+      {count > 1 ? (
+        <>
+          {/* Compact: every width when asked, else only a phone's. */}
+          <div className={cx("flex items-center gap-1", sizer ? "ml-auto" : "mx-auto", !compact && "sm:hidden")}>
+            {prev(false)}
+            {status}
+            {next(false)}
+          </div>
+
+          {compact ? null : (
+            <ul className={cx("hidden items-center gap-1 sm:flex", sizer ? "ml-auto" : "mx-auto")}>
+              <li>{prev(true)}</li>
+              {slots(current, count, Math.max(0, siblings)).map((s, i) =>
+                s === "gap" ? (
+                  <li key={`gap-${i}`} aria-hidden="true" className={cx("inline-flex items-center justify-center text-muted-foreground", square)}>
+                    <Icon name="more" />
+                  </li>
+                ) : (
+                  <li key={s}>
+                    {go(s, {
+                      current: s === current,
+                      "aria-label": `Page ${s}`,
+                      className: square,
+                      children: <span data-nums>{s}</span>,
+                    })}
+                  </li>
+                ),
+              )}
+              <li>{next(true)}</li>
+            </ul>
+          )}
+        </>
+      ) : null}
+    </nav>
+  );
+}

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

@@ -0,0 +1,284 @@
+"use client";
+
+import { useEffect, useId, useLayoutEffect, useRef, useState } from "react";
+import { cx } from "./cx";
+import { Button } from "./button";
+
+// Popover — a panel that floats beside the control that opened it: a
+// filter form under its button, a short setting beside a row. The Popover
+// API does the hard part (top layer, light dismiss, Escape, focus back to
+// the trigger); CSS anchor positioning keeps it beside the trigger where
+// the browser has it, and a measured fallback does where it does not.
+// Controlled (`open` + `onOpenChange`) or not (`defaultOpen`).
+//
+//   trigger    a node → the content of a kit Button (`variant`, `size`
+//              apply); or (props) => element for a trigger of your own —
+//              spread `props` on a <button> (ref, popoverTarget, aria-*)
+//   side       top · right · bottom (default) · left; flips to the
+//              opposite side when there is no room, and every open tries
+//              the asked side first again
+//   align      start · center (default) · end, along that side (physical:
+//              start is the left or top edge)
+//   width      sm (224px) · md (288px, default) · lg (384px) · auto (its
+//              content); never wider than the window less 16px
+//   className  the panel's; a padding in it (p-0, p-2…) replaces the p-4
+//   label      what a screen reader calls the panel (role=dialog);
+//              defaults to the trigger when it is a string
+//   open, defaultOpen, onOpenChange(open) — light dismiss and Escape
+//              report onOpenChange(false); the panel follows `open`
+//
+// Focus moves to the panel's first control when it opens and back to the
+// trigger when it closes; Tab past the panel's end closes it.
+//
+// For the parts built on this (Tooltip, HoverCard, a combobox, a date
+// picker): usePopoverPosition(anchorRef, panelRef, { side, align, offset })
+// keeps any [popover] panel beside its anchor — flipping, following scroll
+// and resize — and panelClass(width, className) is the panel's look.
+
+const WIDTHS = { sm: "w-56", md: "w-72", lg: "w-96", auto: "w-max" };
+const OPPOSITE = { top: "bottom", bottom: "top", left: "right", right: "left" };
+const EDGE = 8; // the room kept between a panel and the window's edge
+
+/** The floating panel's look: popover tokens, a border, a shadow, and a
+ *  quick fade that `prefers-reduced-motion` drops. */
+export function panelClass(width = "md", className) {
+  return cx(
+    WIDTHS[width] ?? WIDTHS.md,
+    "max-w-[calc(100vw-1rem)] rounded-md border border-border bg-popover text-popover-foreground shadow-lg outline-none",
+    "opacity-0 scale-95 transition-[opacity,scale,display,overlay] transition-discrete duration-150 open:opacity-100 open:scale-100",
+    "starting:open:opacity-0 starting:open:scale-95 motion-reduce:transition-none",
+    className,
+  );
+}
+
+// Anchor positioning with the fallbacks we name: Chrome 129+, Safari 26.
+// Checked once; anything older takes the measured path.
+let anchored;
+function canAnchor() {
+  if (anchored === undefined) {
+    anchored =
+      typeof CSS !== "undefined" &&
+      CSS.supports("position-area", "bottom span-right") &&
+      CSS.supports("position-try-fallbacks", "top span-left, bottom span-all");
+  }
+  return anchored;
+}
+
+// Every place the panel may go, preferred first: the asked side with the
+// asked alignment, then the other alignments, then the opposite side.
+// `span-all` centres on the anchor with the whole window to spread into.
+function areas(side, align) {
+  const vertical = side === "top" || side === "bottom";
+  const [start, end] = vertical ? ["span-right", "span-left"] : ["span-bottom", "span-top"];
+  const cross = { start, end, center: "span-all" };
+  const order = align === "start" ? ["start", "end", "center"] : align === "end" ? ["end", "start", "center"] : ["center", "start", "end"];
+  return [side, OPPOSITE[side]].flatMap((s) => order.map((a) => `${s} ${cross[a]}`));
+}
+
+// Set a panel beside its anchor; returns the undo.
+function attach(a, p, name, side, align, offset) {
+  const vertical = side === "top" || side === "bottom";
+  p.style.inset = "auto";
+
+  if (canAnchor()) {
+    const [first, ...rest] = areas(side, align);
+    // An anchor may hold several panels (a tooltip and a popover): the
+    // names are a list, and each panel adds and removes only its own.
+    const names = () => a.style.getPropertyValue("anchor-name").split(",").map((n) => n.trim()).filter((n) => n.startsWith("--"));
+    a.style.setProperty("anchor-name", [...names().filter((n) => n !== name), name].join(", "));
+    p.style.setProperty("position-anchor", name);
+    p.style.setProperty("position-area", first);
+    p.style.setProperty("position-try-fallbacks", rest.join(", "));
+    p.style.setProperty("position-visibility", "anchors-visible");
+    // Both sides of the axis, so a flipped panel keeps its gap.
+    p.style.margin = vertical ? `${offset}px 0` : `0 ${offset}px`;
+    // Chrome remembers the last fallback that fitted while the panel is
+    // still drawn — and the close fade keeps it drawn — so a panel that
+    // once flipped reopens flipped while that side still fits. A changed
+    // list makes it forget: every open alternates between the list and
+    // the same list with its last place repeated (a no-op try), so each
+    // open starts again from the asked side.
+    let fresh = false;
+    const reprefer = (e) => {
+      if (e.newState !== "open") return;
+      fresh = !fresh;
+      p.style.setProperty("position-try-fallbacks", (fresh ? [...rest, rest[rest.length - 1]] : rest).join(", "));
+    };
+    p.addEventListener("beforetoggle", reprefer);
+    return () => {
+      p.removeEventListener("beforetoggle", reprefer);
+      const left = names().filter((n) => n !== name);
+      if (left.length) a.style.setProperty("anchor-name", left.join(", "));
+      else a.style.removeProperty("anchor-name");
+    };
+  }
+
+  let frame = 0;
+  function place() {
+    frame = 0;
+    if (!p.matches(":popover-open")) return;
+    const r = a.getBoundingClientRect();
+    const vw = document.documentElement.clientWidth;
+    const vh = document.documentElement.clientHeight;
+    // Measure at the origin, where nothing squeezes it.
+    p.style.top = "0px";
+    p.style.left = "0px";
+    const w = p.offsetWidth;
+    const h = p.offsetHeight;
+    const room = { top: r.top, bottom: vh - r.bottom, left: r.left, right: vw - r.right };
+    const need = (vertical ? h : w) + offset + EDGE;
+    const s = room[side] < need && room[OPPOSITE[side]] > room[side] ? OPPOSITE[side] : side;
+    let x;
+    let y;
+    if (vertical) {
+      y = s === "bottom" ? r.bottom + offset : r.top - offset - h;
+      x = align === "start" ? r.left : align === "end" ? r.right - w : r.left + (r.width - w) / 2;
+    } else {
+      x = s === "right" ? r.right + offset : r.left - offset - w;
+      y = align === "start" ? r.top : align === "end" ? r.bottom - h : r.top + (r.height - h) / 2;
+    }
+    // Shift onto the screen; where neither side had room this may cover
+    // the anchor, which beats a panel cut off at the window's edge.
+    x = Math.max(EDGE, Math.min(x, vw - w - EDGE));
+    y = Math.max(EDGE, Math.min(y, vh - h - EDGE));
+    p.style.top = `${Math.round(y)}px`;
+    p.style.left = `${Math.round(x)}px`;
+    p.dataset.side = s;
+    // An anchor scrolled out of the window takes its panel with it.
+    p.style.visibility = r.bottom < 0 || r.top > vh || r.right < 0 || r.left > vw ? "hidden" : "";
+  }
+  const queue = () => {
+    if (!frame) frame = requestAnimationFrame(place);
+  };
+  // A ResizeObserver reports before paint, so the panel is placed in
+  // the frame it appears — and again whenever either box changes size.
+  const ro = new ResizeObserver(place);
+  ro.observe(p);
+  ro.observe(a);
+  window.addEventListener("scroll", queue, true);
+  window.addEventListener("resize", queue);
+  return () => {
+    ro.disconnect();
+    cancelAnimationFrame(frame);
+    window.removeEventListener("scroll", queue, true);
+    window.removeEventListener("resize", queue);
+  };
+}
+
+/**
+ * Keep an open [popover] panel beside its anchor. CSS anchor positioning
+ * where the browser has it (it follows scroll natively and hides the
+ * panel when the anchor scrolls away); else it is measured — placed
+ * before the first paint, flipped to the opposite side when the asked one
+ * has no room, shifted along the other axis to stay on screen, and moved
+ * again on scroll, resize and a change in either element's size.
+ */
+export function usePopoverPosition(anchorRef, panelRef, { side = "bottom", align = "center", offset = 6 } = {}) {
+  const name = `--pop-${useId().replace(/[^\w-]/g, "")}`;
+  const live = useRef({ key: null, off: null });
+
+  // No dependency list: a panel may mount after its anchor (a portal) or
+  // either element be replaced, so every commit looks, and sets up again
+  // only when an element or an option changed.
+  useLayoutEffect(() => {
+    const key = [anchorRef.current, panelRef.current, side, align, offset];
+    if (live.current.key?.every((v, i) => v === key[i])) return;
+    live.current.off?.();
+    const [a, p] = key;
+    live.current = { key, off: a && p ? attach(a, p, name, side, align, offset) : null };
+  });
+  useLayoutEffect(
+    () => () => {
+      live.current.off?.();
+      live.current = { key: null, off: null };
+    },
+    [],
+  );
+}
+
+const FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+export function Popover({
+  trigger,
+  label,
+  side = "bottom",
+  align = "center",
+  width = "md",
+  open,
+  defaultOpen = false,
+  onOpenChange,
+  variant = "secondary",
+  size = "md",
+  className,
+  children,
+}) {
+  const id = useId();
+  const btn = useRef(null);
+  const pop = useRef(null);
+  const controlled = open !== undefined;
+  const [own, setOwn] = useState(defaultOpen);
+  const isOpen = controlled ? open : own;
+  const last = useRef(isOpen);
+  last.current = isOpen;
+  usePopoverPosition(btn, pop, { side, align });
+
+  // The state drives the top layer; the browser's own closes (light
+  // dismiss, Escape, the trigger again) come back through onToggle.
+  useEffect(() => {
+    const p = pop.current;
+    if (!p) return;
+    const shown = p.matches(":popover-open");
+    if (isOpen && !shown) p.showPopover();
+    else if (!isOpen && shown) p.hidePopover();
+  }, [isOpen]);
+
+  function onToggle(e) {
+    const now = e.newState === "open";
+    const p = pop.current;
+    if (now) (p?.querySelector(FOCUSABLE) ?? p)?.focus({ preventScroll: true });
+    else if (!document.activeElement || document.activeElement === document.body || p?.contains(document.activeElement)) {
+      btn.current?.focus({ preventScroll: true });
+    }
+    if (!controlled) setOwn(now);
+    if (now !== last.current) onOpenChange?.(now);
+  }
+
+  // Tab out of the panel's end (to anything but the trigger) closes it.
+  function onBlur(e) {
+    const to = e.relatedTarget;
+    if (to && !pop.current?.contains(to) && to !== btn.current) pop.current?.hidePopover();
+  }
+
+  const props = {
+    ref: btn,
+    popoverTarget: id,
+    "aria-haspopup": "dialog",
+    "aria-expanded": isOpen,
+    "aria-controls": id,
+  };
+
+  return (
+    <>
+      {typeof trigger === "function" ? (
+        trigger(props)
+      ) : (
+        <Button variant={variant} size={size} {...props}>
+          {trigger}
+        </Button>
+      )}
+      <div
+        ref={pop}
+        id={id}
+        popover="auto"
+        role="dialog"
+        aria-label={label ?? (typeof trigger === "string" ? trigger : undefined)}
+        tabIndex={-1}
+        onToggle={onToggle}
+        onBlur={onBlur}
+        className={panelClass(width, cx(!/(^|\s)p[xytrbl]?-/.test(className ?? "") && "p-4", "text-sm", className))}
+      >
+        {children}
+      </div>
+    </>
+  );
+}