@spunto/design-system 0.19.0 → 0.20.0

package/README.md

@@ -66,6 +66,21 @@ const nextConfig = { transpilePackages: ["@spunto/design-system"] }
     (a confirmation variant, non-dismissible), `Sheet`, `Tooltip`. Their portals render
     into the provider's overlay container; `Tooltip`'s shared delay group is mounted by
     the provider too.
+  - _ActionMenu_ — `ActionMenu` (+`ActionMenuItem`, `ActionMenuEntry`), the `⋯` menu
+    **described instead of assembled**: `items` is a list of `{ label, icon?, onClick }`
+    (or `href`, for a real `<a>` via Base UI's `Menu.LinkItem`) and the component builds
+    the trigger, the portal, the popup, the items and their states — `loading` swaps the
+    icon for a spinner and disarms the entry, `destructive` turns it red, `shortcut`
+    right-aligns a `Kbd`. A menu is the one place an app brings nothing but data, and
+    every app was re-typing the same twenty lines of Base UI markup around it. Two things
+    the data form gets right that hand-written menus don't: entries may be
+    `false`/`null`/`undefined`, so a conditional menu stays one flat array; and
+    `"separator"` is an entry like any other, **normalized** — a rule left leading,
+    trailing or doubled by a missing neighbour disappears instead of floating at the top
+    of the popup. Empty after that pass → nothing renders, not even the `⋯`. Still
+    presentational: it never knows what an entry *does*. For what a list can't say (a
+    submenu, a checkbox item), compose Base UI directly — that's what `WorkerCard`'s
+    `actions` slot is for.
   - _Sheet_ — `Sheet` (+`SheetTrigger`/`SheetClose`/`SheetContent`/`SheetHeader`/
     `SheetFooter`/`SheetTitle`/`SheetDescription`), the same Base UI dialog entering from
     an edge. `side` (4) decides the edge, `size` (`sm`…`full`) how far it comes in — two
@@ -167,10 +182,18 @@ opinions a dashboard doesn't want, so it gets an entry too.
 - **`WorkerCard`** — a Spunto worker as a card: state, author, node, setup
   progress, git branches, resources, banners, actions. **Purely presentational** —
   hand it a snapshot plus slots and it draws. The rule that keeps it that way:
-  *everything that CALLS the API is a slot or a callback; everything that DRAWS is
-  in the component.* So the `⋯` menu (`actions`), the footer (`footer`), the link
-  (`href` + `render.link`, never `next/link`), the rebuild (`onRebuild`) and the
-  tag persistence (`onAddTag`/`onRemoveTag`) all stay in the app.
+  *everything that CALLS the API is data, a slot or a callback; everything that
+  DRAWS is in the component.* So what the `⋯` entries **do** (`menu`), the footer
+  (`footer`), the link (`href` + `render.link`, never `next/link`), the rebuild
+  (`onRebuild`) and the tag persistence (`onAddTag`/`onRemoveTag`) all stay in the
+  app.
+- **The `⋯` menu is a prop, not markup.** `menu` takes the `ActionMenuEntry[]` of
+  the `ActionMenu` primitive — `{ label, icon?, onClick }`, falsy entries allowed,
+  `"separator"` normalized — and the card draws the whole menu. Before, every app
+  handed the card a fully-built menu through the `actions` slot and re-typed the
+  same Base UI markup to do it. `actions` stays as the escape hatch (a submenu, a
+  checkbox item) and wins over `menu` when both are given; `render.menuLink` is
+  the link slot for an entry with an `href`.
 - **Its bricks, exported individually** because the table view assembles them
   differently: `WorkerStatusDot`/`WorkerStatusPill` (+`resolveWorkerStatus`,
   `workerStatusConfig`), `SetupProgress` (+`setupProgress`, `phaseLabel`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/design-system",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Spunto's shared design system — warm/flame tokens, color constants, and UI primitives.",
   "type": "module",
   "license": "MIT",

package/src/components/action-menu.tsx

@@ -0,0 +1,225 @@
+"use client"
+
+import type { ComponentType, ReactElement, ReactNode } from "react"
+import { Menu as MenuPrimitive } from "@base-ui/react/menu"
+import { ExternalLinkIcon, MoreVerticalIcon } from "lucide-react"
+
+import { cn } from "../utils"
+import { Spinner } from "./spinner"
+import { useOverlayContainer } from "./spunto-provider"
+
+/** One entry of an `ActionMenu`, described rather than rendered. */
+export interface ActionMenuItem {
+  /** What the entry says. */
+  label: ReactNode
+  /**
+   * React key. Defaults to the label when it's a string — give one explicitly if
+   * the label is a node, or if two entries share a label.
+   */
+  key?: string
+  /** Leading icon — any component taking a `className` (lucide-react, a local SVG…). */
+  icon?: ComponentType<{ className?: string }>
+  /** What the entry does. Omitted (and no `href`) → the entry is inert. */
+  onClick?: () => void
+  /** Navigates instead of acting: the entry renders as a real `<a>` (middle-click, ⌘-click…). */
+  href?: string
+  /** `"_blank"` implies the trailing ↗ unless `external` says otherwise. */
+  target?: string
+  /** Trailing ↗. Defaults to `target === "_blank"`. */
+  external?: boolean
+  disabled?: boolean
+  /**
+   * Action in flight: a spinner takes the icon's place and the entry is
+   * disabled. Kept apart from `disabled` so the caller doesn't have to swap the
+   * icon itself — the pending flag of a mutation goes straight in here.
+   */
+  loading?: boolean
+  /** Red, and pushed below a separator by convention (the caller still places it). */
+  destructive?: boolean
+  /** Trailing hint, right-aligned — a `Kbd`, a shortcut, a count. */
+  shortcut?: ReactNode
+  /** Keeps the popup open after a click (a toggle, typically). */
+  closeOnClick?: boolean
+}
+
+/**
+ * An entry, a rule between groups, or nothing.
+ *
+ * The falsy members are the point: a menu is almost always conditional
+ * (`isRunning && { label: "Stop", … }`), and allowing `false`/`null`/`undefined`
+ * keeps that written as one flat array instead of a `filter(Boolean)` dance.
+ * Separators are normalized afterwards — see `normalizeEntries`.
+ */
+export type ActionMenuEntry = ActionMenuItem | "separator" | false | null | undefined
+
+/** Renders an `href` entry with the app's link component (`next/link`, a router link…). */
+export type ActionMenuLinkRender = (props: {
+  href: string
+  target?: string
+  children?: ReactNode
+}) => ReactElement
+
+export interface ActionMenuProps {
+  /** The menu, as data. Falsy entries are dropped; empty → nothing renders at all. */
+  items: ActionMenuEntry[]
+  /** Accessible name of the default `⋯` trigger. */
+  label?: string
+  /** Replaces the `⋯` button. Base UI merges its trigger props into this element. */
+  trigger?: ReactElement
+  triggerClassName?: string
+  /** Classes for the popup (its width, typically). */
+  className?: string
+  align?: "start" | "center" | "end"
+  side?: "top" | "bottom" | "left" | "right"
+  sideOffset?: number
+  /** Escape hatch for `href` entries; without it they render as a plain `<a>`. */
+  render?: { link?: ActionMenuLinkRender }
+}
+
+/**
+ * The `⋯` menu, described instead of assembled: give it a list of
+ * `{ label, icon, onClick }` and it builds the trigger, the popup, the items,
+ * the separators and their states.
+ *
+ * Every app was rebuilding the same twenty lines of Base UI markup around the
+ * same five shapes of entry (an action, a link, a destructive one, one with a
+ * mutation in flight, a rule between groups) — and drifting: different paddings,
+ * different red, a spinner here and not there. The data form is what the callers
+ * actually have anyway; the markup is ours.
+ *
+ * Two things it does that hand-written menus keep getting wrong:
+ *
+ * - **Conditional entries.** `false`/`null`/`undefined` are legal entries, so a
+ *   menu stays one flat array (`isRunning && { label: "Stop", … }`).
+ * - **Separators are normalized.** Leading, trailing and consecutive rules are
+ *   dropped, so a `"separator"` next to an entry that just disappeared doesn't
+ *   leave a stray line floating at the top of the popup. That's the bug you get
+ *   every time a conditional item sits next to a conditional separator.
+ *
+ * It stays presentational: it never knows what an entry *does*. `onClick` and
+ * `href` come from the caller, like everywhere else in this package.
+ */
+export function ActionMenu({
+  items,
+  label = "Actions",
+  trigger,
+  triggerClassName,
+  className,
+  align = "end",
+  side = "bottom",
+  sideOffset = 4,
+  render,
+}: ActionMenuProps) {
+  const container = useOverlayContainer()
+  const entries = normalizeEntries(items)
+
+  // No action → no affordance. A `⋯` that opens an empty popup is worse than no
+  // `⋯` at all, and callers build these lists conditionally: an empty one is the
+  // normal outcome for, say, a worker on an offline node.
+  if (entries.length === 0) return null
+
+  return (
+    <MenuPrimitive.Root>
+      {trigger ? (
+        <MenuPrimitive.Trigger render={trigger} />
+      ) : (
+        <MenuPrimitive.Trigger aria-label={label} className={cn(triggerButton, triggerClassName)}>
+          <MoreVerticalIcon className="h-4 w-4" />
+        </MenuPrimitive.Trigger>
+      )}
+
+      <MenuPrimitive.Portal container={container ?? undefined}>
+        <MenuPrimitive.Positioner className="isolate z-50 outline-none" align={align} side={side} sideOffset={sideOffset}>
+          <MenuPrimitive.Popup
+            data-slot="action-menu"
+            className={cn(
+              // `max-h-(--available-height)` + scroll: a menu of twenty actions
+              // opened from a card at the bottom of the page must scroll inside
+              // the viewport, never spill past its edge.
+              "max-h-(--available-height) min-w-52 origin-(--transform-origin) overflow-x-hidden overflow-y-auto rounded-lg border border-border bg-popover p-1 text-popover-foreground shadow-lg shadow-black/[0.06] outline-none",
+              "transition-[transform,opacity] duration-150 data-ending-style:scale-95 data-ending-style:opacity-0 data-starting-style:scale-95 data-starting-style:opacity-0",
+              className
+            )}
+          >
+            {entries.map((entry, i) =>
+              entry === "separator" ? (
+                <div key={`sep-${i}`} role="separator" className="-mx-1 my-1 h-px bg-border" />
+              ) : (
+                <Item key={entry.key ?? (typeof entry.label === "string" ? entry.label : `item-${i}`)} item={entry} render={render} />
+              )
+            )}
+          </MenuPrimitive.Popup>
+        </MenuPrimitive.Positioner>
+      </MenuPrimitive.Portal>
+    </MenuPrimitive.Root>
+  )
+}
+
+const triggerButton =
+  "flex h-7 w-7 shrink-0 cursor-pointer items-center justify-center rounded-md text-muted-foreground/50 transition-colors outline-none hover:bg-accent hover:text-foreground focus-visible:ring-3 focus-visible:ring-ring/50 data-popup-open:bg-accent data-popup-open:text-foreground"
+
+const itemClass =
+  "flex cursor-default items-center gap-2 rounded-md px-1.5 py-1 text-sm no-underline outline-none select-none data-highlighted:bg-accent data-highlighted:text-accent-foreground data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-3.5 [&_svg]:shrink-0"
+
+const destructiveClass =
+  "text-destructive data-highlighted:bg-destructive/10 data-highlighted:text-destructive dark:data-highlighted:bg-destructive/20"
+
+function Item({ item, render }: { item: ActionMenuItem; render?: { link?: ActionMenuLinkRender } }) {
+  const { label, icon: Icon, href, target, external, disabled, loading, destructive, shortcut, closeOnClick, onClick } = item
+  const className = cn(itemClass, destructive && destructiveClass)
+  const showExternal = external ?? target === "_blank"
+
+  const content = (
+    <>
+      {loading ? <Spinner className="size-3.5" /> : Icon ? <Icon /> : null}
+      <span className="min-w-0 flex-1 truncate">{label}</span>
+      {shortcut != null && <span className="text-xs text-muted-foreground">{shortcut}</span>}
+      {showExternal && <ExternalLinkIcon className="opacity-50" />}
+    </>
+  )
+
+  // A navigation is an `<a>` — Base UI's `LinkItem` renders one, so ⌘-click and
+  // "open in new tab" work like anywhere else. `render.link` swaps in the app's
+  // router link; without it, a plain anchor (the package never imports `next/link`).
+  if (href) {
+    return (
+      <MenuPrimitive.LinkItem
+        className={className}
+        closeOnClick
+        render={render?.link?.({ href, target }) ?? <a href={href} target={target} rel={target === "_blank" ? "noopener noreferrer" : undefined} />}
+      >
+        {content}
+      </MenuPrimitive.LinkItem>
+    )
+  }
+
+  return (
+    <MenuPrimitive.Item className={className} disabled={disabled || loading} closeOnClick={closeOnClick ?? true} onClick={onClick}>
+      {content}
+    </MenuPrimitive.Item>
+  )
+}
+
+/**
+ * Drops falsy entries, then every separator that would end up alone: leading,
+ * trailing, or next to another one.
+ *
+ * This is the whole reason separators are data here. Written by hand, a rule
+ * between two conditional groups needs its own condition — the union of the
+ * conditions below it — and that condition is what goes stale when an entry is
+ * added. Here the rule simply disappears when nothing follows it.
+ */
+export function normalizeEntries(entries: ActionMenuEntry[]): (ActionMenuItem | "separator")[] {
+  const out: (ActionMenuItem | "separator")[] = []
+  for (const entry of entries) {
+    if (!entry) continue
+    if (entry === "separator") {
+      if (out.length === 0 || out[out.length - 1] === "separator") continue
+      out.push("separator")
+      continue
+    }
+    out.push(entry)
+  }
+  while (out.length > 0 && out[out.length - 1] === "separator") out.pop()
+  return out
+}

package/src/components/workers/index.ts

@@ -9,6 +9,12 @@
 export { WorkerCard } from "./worker-card"
 export type { WorkerCardProps, LinkRender } from "./worker-card"
 
+// The card's `menu` prop is a list of these. Re-exported here (they also ship
+// from the root entry) so an app can type its worker menu without importing the
+// primitives entry just for that.
+export { ActionMenu } from "../action-menu"
+export type { ActionMenuProps, ActionMenuItem, ActionMenuEntry, ActionMenuLinkRender } from "../action-menu"
+
 export { WorkerCockpit } from "./worker-cockpit"
 export type { WorkerCockpitProps } from "./worker-cockpit"
 

package/src/components/workers/worker-card.tsx

@@ -12,6 +12,7 @@ import {
 } from "lucide-react"
 
 import { cn, formatDuration, formatRelativeTime } from "../../utils"
+import { ActionMenu, type ActionMenuEntry, type ActionMenuLinkRender } from "../action-menu"
 import { buttonVariants } from "../button-variants"
 import { CreatorAvatar } from "./creator-avatar"
 import { GitBranchChips, type GitRepoStatus } from "./git-branch-chips"
@@ -33,8 +34,12 @@ export interface WorkerCardProps {
    * Escape hatches for app-specific rendering. `link` receives `{ href, className,
    * children }` and must return an anchor-ish node (`next/link`, a router link…);
    * without it the card falls back to a plain `<a>`.
+   *
+   * `menuLink` does the same for a `menu` entry carrying an `href`, but with the
+   * other contract: it returns an *element* that Base UI merges its own props
+   * and children into, so it takes no `children` of its own.
    */
-  render?: { link?: LinkRender }
+  render?: { link?: LinkRender; menuLink?: ActionMenuLinkRender }
 
   creator?: WorkerCreator
   nodeName?: string
@@ -71,7 +76,33 @@ export interface WorkerCardProps {
   error?: string | null
   onDismissError?: () => void
 
-  /** The `⋯` menu, top-right. A slot: every entry in it calls the API. */
+  /**
+   * The `⋯` menu, top-right, **as data**: one entry is a `label`, optionally an
+   * `icon`, and an `onClick` (or an `href`) — the card builds the trigger, the
+   * popup and the items. Entries may be `false`/`null` (a menu is always
+   * conditional) and `"separator"` is an entry like any other; rules left alone
+   * by a missing neighbour are dropped. Empty or all-falsy → no `⋯` at all.
+   *
+   * What an entry *does* still belongs to the app: `onClick` is where the API
+   * call lives. What it *looks like* is ours — that's the difference with the
+   * `actions` slot below, which each app used to fill with its own twenty lines
+   * of menu markup.
+   *
+   * ```tsx
+   * menu={[
+   *   codeUrl && { label: "Open in VS Code", icon: Code2Icon, href: codeUrl, target: "_blank" },
+   *   "separator",
+   *   isRunning && { label: "Stop", icon: SquareIcon, onClick: () => stop.mutate(), loading: stop.isPending },
+   *   "separator",
+   *   { label: "Delete", icon: Trash2Icon, destructive: true, onClick: () => del.mutate() },
+   * ]}
+   * ```
+   */
+  menu?: ActionMenuEntry[]
+  /**
+   * Escape hatch for a menu the data form can't express (a submenu, a checkbox
+   * item, a dialog opened from an entry). Takes precedence over `menu`.
+   */
   actions?: ReactNode
   /** Replaces the default "View" footer entirely (extra buttons, a VS Code link…). */
   footer?: ReactNode
@@ -86,10 +117,10 @@ export interface WorkerCardProps {
  * on, and what you can do with it.
  *
  * **Purely presentational.** It receives a snapshot and draws it — no query, no
- * mutation, no router. Everything that would talk to an API is a slot
- * (`actions`, `footer`) or a callback (`onAddTag`, `onRebuild`…). That rule is
- * what makes the same card renderable by the dashboard, by Spunto Lite, and by
- * the showcase with hand-written fixtures. The card is the assembly; each brick
+ * mutation, no router. Everything that would talk to an API is data (`menu`), a
+ * slot (`actions`, `footer`) or a callback (`onAddTag`, `onRebuild`…). That rule
+ * is what makes the same card renderable by the dashboard, by Spunto Lite, and
+ * by the showcase with hand-written fixtures. The card is the assembly; each brick
  * (`WorkerStatusDot`, `SetupProgress`, `ResourceBars`, `GitBranchChips`,
  * `TagChips`) is exported on its own because the table view needs them without
  * the card.
@@ -116,6 +147,7 @@ export function WorkerCard({
   rebuilding = false,
   error,
   onDismissError,
+  menu,
   actions,
   footer,
   viewLabel = "View",
@@ -215,7 +247,7 @@ export function WorkerCard({
           </div>
         </div>
 
-        {actions}
+        {actions ?? (menu && <ActionMenu items={menu} render={{ link: render?.menuLink }} />)}
       </div>
 
       {status.settingUp && (

package/src/index.ts

@@ -208,6 +208,13 @@ export type {
   OAuthProvider,
 } from "./components/auth"
 
+// ActionMenu — the `⋯` menu described as data (`{ label, icon, onClick }[]`)
+// rather than assembled from parts: the caller owns what an entry does, the
+// package owns the markup, the states, and the separators (which are normalized,
+// so a conditional entry can't leave a stray rule behind).
+export { ActionMenu } from "./components/action-menu"
+export type { ActionMenuProps, ActionMenuItem, ActionMenuEntry, ActionMenuLinkRender } from "./components/action-menu"
+
 // Kbd — one keyboard cap, or a whole shortcut (`keys="mod+k"` → ⌘ K). Used by the
 // palette, exported on its own for anywhere else a shortcut needs drawing.
 export { Kbd } from "./components/kbd"