makersclaw 0.2.0 → 0.3.1

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

@@ -0,0 +1,149 @@
+"use client";
+
+import { useId, useRef } from "react";
+import Link from "next/link";
+import { cx } from "./cx";
+import { Icon } from "./icon";
+import { usePopoverPosition } from "./popover";
+
+// Breadcrumb — where this page sits: Deals › Acme Corp › Renewal. Items
+// are data; each with an `href` is a next/link (base path applied), the
+// last is the page you are on (aria-current) and is never a link.
+// A client part (a server surface renders it as it is; items are plain
+// data): the "…" that stands in for the middle is a native popover
+// (popovertarget), kept under its button by usePopoverPosition — CSS
+// anchoring where the browser has it, measured where it does not.
+//
+//   items      [{ label, href? }] — first is the root, last is this page
+//   max        how many slots on a wide window before the middle folds
+//              into "…" (default 4, the "…" counts as one); a narrow
+//              window shows first › … › last once there are four or more
+//   separator  chevron (default) · slash
+//
+// Long labels truncate, the full text on hover. Earlier crumbs are capped
+// (max-w-40, 56 on sm+); the current page takes the rest of the row. One item or none: nothing
+// to place the page within, so nothing is drawn.
+
+const SEP = {
+  chevron: <Icon name="chevron-right" size={14} />,
+  slash: <span className="px-0.5">/</span>,
+};
+
+// Shown at one width and not the other: the "…", each crumb, each entry
+// in the popover. Whole class names, so Tailwind sees them.
+const SHOW = {
+  flex: { both: "flex", narrow: "flex sm:hidden", wide: "hidden sm:flex", none: "hidden" },
+  block: { both: "block", narrow: "block sm:hidden", wide: "hidden sm:block", none: "hidden" },
+};
+
+// Every crumb truncates; only the earlier ones carry a cap. The current
+// page is the one worth reading, so it takes whatever the row has left
+// and cuts off only when the row really runs out. It is clamped to one
+// line rather than kept on one (nowrap), so its narrowest size is a
+// letter, not the whole title: a card or grid cell sized by its content
+// still shrinks to the window instead of being pushed wide by the title.
+const CRUMB = "min-w-0 rounded-sm outline-none focus-visible:ring-2 focus-visible:ring-ring";
+const CAP = "block max-w-40 truncate sm:max-w-56";
+const REST = "line-clamp-1 [overflow-wrap:anywhere]";
+
+export function Breadcrumb({ items, max = 4, separator = "chevron", label = "Breadcrumb", className }) {
+  const auto = useId();
+  const more = useRef(null);
+  const panel = useRef(null);
+  usePopoverPosition(more, panel, { side: "bottom", align: "start", offset: 4 });
+  const list = (items ?? []).filter(Boolean);
+  if (list.length < 2) return null;
+
+  const id = `crumbs-${auto.replace(/[^a-zA-Z0-9]/g, "")}`;
+  const n = list.length;
+  const keep = Math.max(1, max - 2); // trailing items kept beside the first and the "…"
+  // Middle item i folds on a wide window when there are more than `max`;
+  // on a narrow one every middle item folds once there are four or more
+  // (three fit, truncated).
+  const foldsWide = (i) => n > max && i > 0 && i < n - keep;
+  const foldsNarrow = n > 3;
+  const middle = list.slice(1, -1).map((item, k) => ({ item, i: k + 1 }));
+  const wideFold = middle.some(({ i }) => foldsWide(i));
+  const at = (narrow, wide, display = "flex") => SHOW[display][narrow ? (wide ? "both" : "narrow") : wide ? "wide" : "none"];
+  const sep = (
+    <span aria-hidden="true" className="shrink-0 text-muted-foreground/70">
+      {SEP[separator] ?? SEP.chevron}
+    </span>
+  );
+
+  const crumb = (item, current) =>
+    current || !item.href ? (
+      <span aria-current={current ? "page" : undefined} title={item.label} className={cx(CRUMB, current ? cx(REST, "font-medium text-foreground") : CAP)}>
+        {item.label}
+      </span>
+    ) : (
+      <Link href={item.href} title={item.label} className={cx(CRUMB, CAP, "transition-colors hover:text-foreground")}>
+        {item.label}
+      </Link>
+    );
+
+  return (
+    <nav aria-label={label} className={cx("min-w-0", className)}>
+      <ol className="flex min-w-0 items-center gap-1.5 text-sm text-muted-foreground">
+        <li className="flex min-w-0 items-center">{crumb(list[0], false)}</li>
+
+        {middle.length > 0 ? (
+          <li className={cx("shrink-0 items-center gap-1.5", at(foldsNarrow, wideFold))}>
+            {sep}
+            <button
+              type="button"
+              ref={more}
+              popoverTarget={id}
+              aria-label="Show the full path"
+              title="Show the full path"
+              className="-mx-1 inline-flex h-8 w-8 items-center justify-center rounded-md outline-none hover:bg-accent hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring"
+            >
+              <Icon name="more" size={18} />
+            </button>
+            {/* Keyed by the page, so a client navigation lands with it closed. */}
+            <div
+              key={list[n - 1].href ?? list[n - 1].label}
+              ref={panel}
+              id={id}
+              popover="auto"
+              className="min-w-44 max-w-[calc(100vw-2rem)] rounded-md border border-border bg-popover p-1 text-popover-foreground shadow-lg"
+            >
+              <ul>
+                {middle.map(({ item, i }) => (
+                  <li key={i} className={at(foldsNarrow, foldsWide(i), "block")}>
+                    {item.href ? (
+                      <Link
+                        href={item.href}
+                        className="flex min-h-10 items-center rounded-sm px-2 text-sm outline-none hover:bg-accent focus-visible:bg-accent"
+                      >
+                        <span className="truncate">{item.label}</span>
+                      </Link>
+                    ) : (
+                      <span className="flex min-h-10 items-center px-2 text-sm text-muted-foreground">
+                        <span className="truncate">{item.label}</span>
+                      </span>
+                    )}
+                  </li>
+                ))}
+              </ul>
+            </div>
+          </li>
+        ) : null}
+
+        {middle.map(({ item, i }) => (
+          <li key={i} className={cx("min-w-0 items-center gap-1.5", at(!foldsNarrow, !foldsWide(i)))}>
+            {sep}
+            {crumb(item, false)}
+          </li>
+        ))}
+
+        {/* The rest of the row, and never less than 10rem (or half a narrow
+            row): long earlier crumbs give way before this page's title. */}
+        <li className="flex min-w-[min(10rem,50%)] flex-1 items-center gap-1.5">
+          {sep}
+          {crumb(list[n - 1], true)}
+        </li>
+      </ol>
+    </nav>
+  );
+}

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

@@ -0,0 +1,70 @@
+import { cx } from "./cx";
+
+// ButtonGroup — buttons that belong together drawn as one attached
+// piece: a split "Save | ▾", a pager "‹ 2 of 9 ›", a zoom "− 100% +".
+// It only reshapes its children (square inner corners, one shared border
+// between neighbours); each child stays the Button, IconButton or Menu
+// it is, with its own behaviour and focus. Server-safe (no hooks).
+//
+//   orientation  horizontal (the default) · vertical
+//   size         md · sm — match the buttons inside
+//   variant      secondary (the default) · primary · quiet — how a Menu's
+//                trigger inside is drawn, to match its neighbours (the
+//                Buttons keep their own variant)
+//   aria-label   what the group is for ("Pagination", "Text alignment")
+//
+// Secondary buttons share their borders, so they need no separator.
+// Primary and quiet buttons have no visible border: put a
+// <ButtonGroupSeparator /> between them. A group is for a few related
+// actions — a toolbar with sections is several groups with a gap.
+
+const ORIENT = {
+  horizontal: cx(
+    "inline-flex flex-row items-stretch",
+    "[&>:where(:not([popover]))]:rounded-none [&>:first-child]:rounded-l-md [&>:last-child]:rounded-r-md [&>:has(+[popover]:last-child)]:rounded-r-md",
+    "[&>:not(:first-child):not([popover])]:border-l-0 [&>[role=separator]]:w-px",
+  ),
+  vertical: cx(
+    "inline-flex flex-col items-stretch",
+    "[&>:where(:not([popover]))]:rounded-none [&>:first-child]:rounded-t-md [&>:last-child]:rounded-b-md [&>:has(+[popover]:last-child)]:rounded-b-md",
+    "[&>:not(:first-child):not([popover])]:border-t-0 [&>[role=separator]]:h-px",
+  ),
+};
+
+// A Menu renders a bare trigger; inside a group it wears its neighbours' look.
+const MENU = {
+  secondary: "[&>[aria-haspopup]]:border [&>[aria-haspopup]]:border-border [&>[aria-haspopup]]:bg-secondary [&>[aria-haspopup]]:text-secondary-foreground [&>[aria-haspopup]]:hover:bg-accent",
+  primary: "[&>[aria-haspopup]]:border [&>[aria-haspopup]]:border-transparent [&>[aria-haspopup]]:bg-primary [&>[aria-haspopup]]:text-primary-foreground [&>[aria-haspopup]]:hover:bg-primary [&>[aria-haspopup]]:hover:opacity-90",
+  quiet: "[&>[aria-haspopup]]:border [&>[aria-haspopup]]:border-transparent",
+};
+const MENU_SIZE = {
+  md: "[&>[aria-haspopup]]:min-h-11 [&>[aria-haspopup]]:min-w-11",
+  sm: "[&>[aria-haspopup]]:min-h-9 [&>[aria-haspopup]]:min-w-9",
+};
+
+export function ButtonGroup({ orientation = "horizontal", size = "md", variant = "secondary", className, children, ...rest }) {
+  return (
+    <div
+      role="group"
+      aria-orientation={orientation === "vertical" ? "vertical" : undefined}
+      className={cx(
+        ORIENT[orientation] ?? ORIENT.horizontal,
+        MENU[variant] ?? MENU.secondary,
+        MENU_SIZE[size] ?? MENU_SIZE.md,
+        // The focused child's ring draws over its neighbours.
+        "[&>:not([popover])]:relative [&>:focus-visible]:z-10",
+        className,
+      )}
+      {...rest}
+    >
+      {children}
+    </div>
+  );
+}
+
+/** The line between two buttons whose borders do not show (primary,
+ *  quiet). The group sizes it; in a vertical group pass
+ *  orientation="horizontal" so a screen reader hears it right. */
+export function ButtonGroupSeparator({ orientation = "vertical", className }) {
+  return <div role="separator" aria-orientation={orientation} className={cx("shrink-0 self-stretch bg-border", className)} />;
+}

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

@@ -1,23 +1,72 @@
 import Link from "next/link";
 import { cx } from "./cx";
 import { Icon } from "./icon";
+import { Spinner } from "./feedback";
 
-// Button — every action in the app. Four looks, one shape, 44px targets
+// Button — every action in the app. 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)
+//             quiet (no fill) · danger (destructive, red text) ·
+//             link (text only: inline, no box, padding or min-height — it
+//             wraps and truncates with the sentence it sits in) · nav (a navigation row: quiet, full
+//             width, start-aligned, normal weight; aria-current="page"
+//             fills it and sets it medium)
+//   size      md (44px) · sm (36px, for dense rows and rails); a link has
+//             no height, so for it md and sm are text-sm and `inherit`
+//             takes the surrounding text's size and weight
+//   align     center (the default) · start (label at the leading edge, for
+//             a full-width row of your own; nav is always start)
+//   loading   true while its action runs: a spinner over the label (the
+//             width does not jump), aria-busy, and disabled so a second
+//             click cannot fire it again
+//   tone      a link's colour: primary (the default, text-primary) · muted
+//             (text-muted-foreground, foreground on hover — a secondary
+//             link beside a heading, "What's new", "View all"); only a
+//             link reads it
+//   iconOnly  a square at the size (IconButton sets it; a Button whose
+//             only child is an <Icon> should too)
+//
+// cx does not merge classes: a className can add, never override, what a
+// variant or size already sets. Anything a surface needs to vary is a
+// prop here, not a className fight.
 
 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",
+  link: "underline-offset-4 hover:underline",
+  nav:
+    "w-full min-w-0 bg-transparent text-foreground border-transparent hover:bg-accent " +
+    "[&[aria-current]:not([aria-current=false])]:bg-accent [&[aria-current]:not([aria-current=false])]:text-accent-foreground",
+};
+
+// A link's colour, apart from its variant so a secondary link is a prop
+// and not a text-muted-foreground laid over text-primary.
+const LINK_TONES = {
+  primary: "text-primary",
+  muted: "text-muted-foreground hover:text-foreground",
+};
+
+// The shape each variant is drawn in. A nav row spaces its icon wider.
+// A link is text in a line: inline, not a flex box — no border, padding
+// or height, it wraps where the sentence wraps and truncates with it. Its
+// icons sit on the text's line: `icon` leads, an <Icon> child trails.
+const SHAPE = {
+  box: "inline-flex items-center gap-2 rounded-md border whitespace-nowrap",
+  nav: "inline-flex items-center gap-3 rounded-md border whitespace-nowrap",
+  link: "inline rounded-sm [&>svg]:ml-1 [&>svg]:inline-block [&>svg]:align-[-0.125em]",
+};
+
+// Weight lives apart from the shape so a nav row can be normal weight
+// (its current row medium) without laying one font weight over another.
+const WEIGHT = {
+  box: "font-medium",
+  nav: "font-normal [&[aria-current]:not([aria-current=false])]:font-medium",
 };
 
 const SIZES = {
@@ -25,6 +74,27 @@ const SIZES = {
   sm: "min-h-9 px-3 text-sm",
 };
 
+// A link's sizes are only its text: md and sm as every other button,
+// inherit for a link inside a sentence.
+const LINK_SIZES = {
+  md: "text-sm font-medium",
+  sm: "text-sm font-medium",
+  inherit: "",
+};
+
+// IconButton's squares. Their own entries, never a px-0 laid over a
+// size's padding: cx does not merge classes, so which of two paddings
+// wins is CSS order, not the order they were written in.
+const ICON_SIZES = {
+  md: "size-11 px-0 text-sm",
+  sm: "size-9 px-0 text-sm",
+};
+
+const ALIGN = {
+  center: "justify-center",
+  start: "justify-start text-left",
+};
+
 export function Button({
   variant = "secondary",
   size = "md",
@@ -33,31 +103,80 @@ export function Button({
   className,
   children,
   type = "button",
+  loading = false,
+  disabled,
+  iconOnly = false,
+  align = "center",
+  tone = "primary",
   ...rest
 }) {
+  const look = VARIANTS[variant] ? variant : "secondary";
+  const link = look === "link";
+  const nav = look === "nav";
+  const sizeClass = link
+    ? LINK_SIZES[size] ?? LINK_SIZES.md
+    : iconOnly
+      ? ICON_SIZES[size] ?? ICON_SIZES.md
+      : SIZES[size] ?? SIZES.md;
   const classes = cx(
-    "inline-flex items-center justify-center gap-2 rounded-md border font-medium whitespace-nowrap",
+    SHAPE[link ? "link" : nav ? "nav" : "box"],
+    !link && (nav ? WEIGHT.nav : WEIGHT.box),
+    !link && !iconOnly && (ALIGN[nav ? "start" : align] ?? ALIGN.center),
+    iconOnly && ALIGN.center,
     "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,
+    VARIANTS[look],
+    link && (LINK_TONES[tone] ?? LINK_TONES.primary),
+    sizeClass,
+    // Busy is not unavailable: the button keeps its full colour.
+    loading && "relative disabled:aria-busy:opacity-100 disabled:aria-busy:cursor-progress",
+    loading && href && "pointer-events-none opacity-50",
     className,
   );
-  const body = (
+  const lead = icon ? (
+    link ? (
+      <span className="mr-1 inline-block align-[-0.125em]">
+        <Icon name={icon} />
+      </span>
+    ) : (
+      <Icon name={icon} />
+    )
+  ) : null;
+  const content = (
     <>
-      {icon ? <Icon name={icon} /> : null}
+      {lead}
       {children}
     </>
   );
+  // Loading: the label stays in place (transparent, still the accessible
+  // name) so the button keeps its width; the spinner sits on top of it.
+  const body = loading ? (
+    <>
+      <span className="inline-flex items-center gap-2 opacity-0">{content}</span>
+      <span className="absolute inset-0 grid place-items-center">
+        <Spinner size="sm" label={null} />
+      </span>
+    </>
+  ) : (
+    content
+  );
   if (href) {
     return (
-      <Link href={href} className={classes} {...rest}>
+      <Link
+        href={href}
+        className={classes}
+        aria-busy={loading || undefined}
+        aria-disabled={loading || undefined}
+        tabIndex={loading ? -1 : undefined}
+        disabled={disabled}
+        {...rest}
+      >
         {body}
       </Link>
     );
   }
   return (
-    <button type={type} className={classes} {...rest}>
+    <button type={type} className={classes} disabled={loading || disabled} aria-busy={loading || undefined} {...rest}>
       {body}
     </button>
   );
@@ -72,7 +191,8 @@ export function IconButton({ icon, label, size = "md", variant = "quiet", classN
       size={size}
       aria-label={label}
       title={label}
-      className={cx(size === "sm" ? "w-9 px-0" : "w-11 px-0", className)}
+      iconOnly
+      className={cx("shrink-0", className)}
       {...rest}
     >
       <Icon name={icon} size={size === "sm" ? 16 : 18} />