makersclaw 0.1.0 → 0.3.0

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

@@ -0,0 +1,338 @@
+import { cx } from "./cx";
+import { Icon } from "./icon";
+
+// Steps — where a job with named stages has got to: a CI run's stages, a
+// rollout's phases (5% → 25% → 100%), an onboarding checklist. Server-safe
+// (no hooks). An ordered list: every step is an <li>, the current one has
+// aria-current="step", and a reader hears each step's state in words —
+// the dot or segment says nothing on its own. Status sets every tone;
+// nothing takes a colour.
+//
+//   steps        [{ key, label, description?, status?, meta? }] — status
+//                complete · current · pending · failed · skipped. Plain
+//                strings are labels. A step without a status takes it
+//                from `current`
+//   current      the index of the current step, for the simple case:
+//                before it complete, after it pending
+//   variant      dots (markers joined by a line, the line filled up to
+//                where the job has got) · bar (one segment per phase, like
+//                Progress cut into pieces)
+//   size         dots only: md (24px markers with a check, a cross, a
+//                number) · sm (small plain dots, a dense card header)
+//   hideStepLabels  bare markers: every step's label, description and meta
+//                go to readers only ("Build, complete"), none on screen.
+//                Pass the labels anyway — a step without one is only
+//                "Step 1" to a reader. With onSelect each marker is the
+//                button
+//   orientation  horizontal · vertical
+//   pulse        the current step breathes; still under prefers-reduced-motion
+//   label        the list's name, shown above it (as Progress does) and read
+//                to a screen reader; `hideLabel` keeps it for readers only
+//   valueText    the right side of that header: "25% traffic", "3/5 stages"
+//   onSelect     (step, index) → makes every step a button (open its logs,
+//                jump to it). Without it the list takes no clicks
+//
+// On a phone: a horizontal list whose steps carry a description or meta
+// turns vertical below sm (640px) — those words need a line of their own.
+// Bare dots, bare segments and short labels ("5%", "Build") stay in one
+// row at every width: the spacing compresses, labels truncate, it never
+// wraps and never scrolls.
+//
+// The rule: status is the only thing that colours a step — complete is
+// success, current is primary, failed is danger, pending and skipped are
+// muted. Never use Steps for choices (that is Tabs or RadioGroup).
+
+const STATUS = {
+  complete: { word: "complete", icon: "check" },
+  current: { word: "current", icon: null },
+  pending: { word: "not started", icon: null },
+  failed: { word: "failed", icon: "x" },
+  skipped: { word: "skipped", icon: "minus" },
+};
+
+// Markers for the dots variant.
+const MARKER_MD = {
+  complete: "bg-success text-card",
+  current: "border-2 border-primary bg-card text-primary",
+  pending: "border border-border bg-card text-muted-foreground",
+  failed: "bg-destructive text-destructive-foreground",
+  skipped: "border border-dashed border-muted-foreground/50 bg-card text-muted-foreground",
+};
+const MARKER_SM = {
+  complete: "size-2.5 bg-success",
+  current: "size-3 bg-primary",
+  pending: "size-2.5 bg-muted-foreground/35",
+  failed: "size-3 bg-destructive",
+  skipped: "size-2.5 border border-muted-foreground/60",
+};
+
+// Segments for the bar variant.
+const SEGMENT = {
+  complete: "bg-success",
+  current: "bg-primary",
+  pending: "bg-accent",
+  failed: "bg-destructive",
+  skipped: "bg-muted-foreground/25",
+};
+
+const LABEL_TONE = {
+  complete: "text-foreground",
+  current: "text-foreground",
+  pending: "text-muted-foreground",
+  failed: "text-destructive",
+  skipped: "text-muted-foreground line-through decoration-muted-foreground/50",
+};
+
+// Every layout as literal class names, so Tailwind sees each one:
+// h (always a row), v (always a column), r (a column below sm, a row from sm).
+// The DOM is the same in all three: li > [track: marker + line] [text].
+const LAYOUT = {
+  dots: {
+    h: {
+      ol: "flex w-full items-start",
+      li: "relative flex min-w-0 flex-1 flex-col gap-2",
+      last: "flex-none",
+      track: "flex items-center",
+      line: "mx-2 h-0.5 min-w-2 flex-1 rounded-full",
+      text: "min-w-0 pr-3",
+      textLast: "min-w-0",
+      label: "block truncate text-sm font-medium",
+      rowMeta: "",
+    },
+    v: {
+      ol: "flex flex-col",
+      li: "relative flex min-w-0 gap-3",
+      last: "",
+      track: "flex flex-col items-center",
+      line: "my-1 min-h-3 w-0.5 flex-1 rounded-full",
+      text: "min-w-0 flex-1 pb-5",
+      textLast: "min-w-0 flex-1",
+      label: "min-w-0 text-sm font-medium",
+      rowMeta: "flex items-baseline justify-between gap-3",
+    },
+    r: {
+      ol: "flex flex-col sm:flex-row sm:items-start",
+      li: "relative flex min-w-0 gap-3 sm:flex-1 sm:flex-col sm:gap-2",
+      last: "sm:flex-none",
+      track: "flex flex-col items-center sm:flex-row",
+      line: "my-1 min-h-3 w-0.5 flex-1 rounded-full sm:mx-2 sm:my-0 sm:h-0.5 sm:min-h-0 sm:w-auto sm:min-w-2",
+      text: "min-w-0 flex-1 pb-5 sm:flex sm:flex-none sm:flex-col sm:pb-0 sm:pr-3",
+      textLast: "min-w-0 flex-1 sm:flex sm:flex-none sm:flex-col",
+      label: "min-w-0 text-sm font-medium sm:block sm:truncate",
+      rowMeta: "flex items-baseline justify-between gap-3 sm:contents",
+      meta: "sm:order-last sm:mt-0.5",
+    },
+  },
+  bar: {
+    h: {
+      ol: "flex w-full items-start gap-1",
+      li: "relative flex min-w-0 flex-1 flex-col gap-1.5",
+      last: "",
+      track: "h-2 w-full rounded-full",
+      text: "min-w-0 text-center",
+      textLast: "min-w-0 text-center",
+      label: "block truncate text-xs",
+      rowMeta: "",
+    },
+    v: {
+      ol: "flex flex-col gap-1",
+      li: "relative flex min-w-0 gap-3",
+      last: "",
+      track: "min-h-6 w-1.5 shrink-0 self-stretch rounded-full",
+      text: "min-w-0 flex-1 py-1",
+      textLast: "min-w-0 flex-1 py-1",
+      label: "min-w-0 text-sm",
+      rowMeta: "flex items-baseline justify-between gap-3",
+    },
+    r: {
+      ol: "flex flex-col gap-1 sm:flex-row sm:items-start",
+      li: "relative flex min-w-0 gap-3 sm:flex-1 sm:flex-col sm:gap-1.5",
+      last: "",
+      track: "min-h-6 w-1.5 shrink-0 self-stretch rounded-full sm:h-2 sm:min-h-0 sm:w-full",
+      text: "min-w-0 flex-1 py-1 sm:flex sm:flex-col sm:py-0 sm:text-center",
+      textLast: "min-w-0 flex-1 py-1 sm:flex sm:flex-col sm:py-0 sm:text-center",
+      label: "min-w-0 text-sm sm:block sm:truncate sm:text-xs",
+      rowMeta: "flex items-baseline justify-between gap-3 sm:contents",
+      meta: "sm:order-last sm:mt-0.5",
+    },
+  },
+};
+
+function normalize(steps, current) {
+  const cur = typeof current === "number" && Number.isFinite(current) ? current : -1;
+  return steps.map((raw, i) => {
+    const s = typeof raw === "string" ? { label: raw } : raw ?? {};
+    const derived = cur < 0 ? "pending" : i < cur ? "complete" : i === cur ? "current" : "pending";
+    const status = STATUS[s.status] ? s.status : derived;
+    return { ...s, key: s.key ?? `${i}`, status };
+  });
+}
+
+function Marker({ step, index, size, pulse }) {
+  const st = step.status;
+  if (size === "sm") {
+    return (
+      <span aria-hidden="true" className="relative grid size-3 shrink-0 place-items-center">
+        {pulse && st === "current" ? (
+          <span className={cx("absolute inset-0 rounded-full opacity-50 animate-ping bg-primary motion-reduce:hidden")} />
+        ) : null}
+        <span className={cx("relative rounded-full", MARKER_SM[st])} />
+      </span>
+    );
+  }
+  const glyph = STATUS[st].icon;
+  return (
+    <span aria-hidden="true" className="relative grid size-6 shrink-0 place-items-center">
+      {pulse && st === "current" ? (
+        <span className={cx("absolute inset-0 rounded-full opacity-30 animate-ping bg-primary motion-reduce:hidden")} />
+      ) : null}
+      <span className={cx("relative grid size-6 place-items-center rounded-full", MARKER_MD[st])}>
+        {glyph ? (
+          <Icon name={glyph} size={14} className={st === "complete" || st === "failed" ? "[stroke-width:2.6]" : undefined} />
+        ) : st === "current" ? (
+          <span className="size-2 rounded-full bg-primary" />
+        ) : (
+          <span data-nums className="text-2xs font-medium">
+            {index + 1}
+          </span>
+        )}
+      </span>
+    </span>
+  );
+}
+
+/**
+ * The steps of one job and where it has got to. See the header above.
+ */
+export function Steps({
+  steps = [],
+  current,
+  variant = "dots",
+  size = "md",
+  orientation = "horizontal",
+  pulse = false,
+  label,
+  hideLabel = false,
+  hideStepLabels = false,
+  valueText,
+  onSelect,
+  className,
+}) {
+  const list = normalize(steps, current);
+  if (!list.length) return null;
+  const kind = variant === "bar" ? "bar" : "dots";
+  const words = !hideStepLabels && list.some((s) => s.description || s.meta);
+  const mode = orientation === "vertical" ? "v" : words ? "r" : "h";
+  const L = LAYOUT[kind][mode];
+  // How far the job has got: the last step that is not pending. The line
+  // after every step before it is filled.
+  let reached = -1;
+  list.forEach((s, i) => {
+    if (s.status !== "pending") reached = i;
+  });
+  const n = list.length;
+
+  return (
+    <div className={cx("grid gap-2", className)}>
+      {label && !hideLabel ? (
+        <div aria-hidden="true" className="flex items-baseline justify-between gap-3 text-sm">
+          <span className="min-w-0 truncate text-muted-foreground">{label}</span>
+          {valueText ? (
+            <span data-nums className="shrink-0 font-medium text-foreground">
+              {valueText}
+            </span>
+          ) : null}
+        </div>
+      ) : null}
+      <ol aria-label={label ? (valueText ? `${label}, ${valueText}` : label) : undefined} className={L.ol}>
+        {list.map((step, i) => {
+          const last = i === n - 1;
+          const st = step.status;
+          const isCurrent = st === "current";
+          const labelTone = kind === "bar" && !isCurrent && st !== "failed" ? "text-muted-foreground" : LABEL_TONE[st];
+          const title = (
+            <>
+              {step.label ?? `Step ${i + 1}`}
+              {/* The state in words; aria-current already says "current step". */}
+              {isCurrent ? null : <span className="sr-only">, {STATUS[st].word}</span>}
+            </>
+          );
+          // Bare markers: the words a reader would otherwise have seen.
+          const hiddenTitle = (
+            <>
+              {title}
+              {step.description ? <>, {step.description}</> : null}
+              {step.meta ? <>, {step.meta}</> : null}
+            </>
+          );
+          return (
+            <li key={step.key} aria-current={isCurrent ? "step" : undefined} className={cx(L.li, last && L.last)}>
+              {kind === "dots" ? (
+                <div className={L.track}>
+                  <Marker step={step} index={i} size={size} pulse={pulse} />
+                  {last ? null : (
+                    <span aria-hidden="true" className={cx(L.line, i < reached ? "bg-success" : "bg-border")} />
+                  )}
+                </div>
+              ) : (
+                <span
+                  aria-hidden="true"
+                  className={cx(
+                    L.track,
+                    SEGMENT[st],
+                    "transition-colors duration-300 motion-reduce:transition-none",
+                    pulse && isCurrent && "animate-pulse motion-reduce:animate-none",
+                  )}
+                />
+              )}
+              {hideStepLabels ? (
+                onSelect ? (
+                  // raw: a button stretched over the whole step, named by its label.
+                  <button
+                    type="button"
+                    onClick={() => onSelect(step, i)}
+                    className="absolute inset-0 rounded-sm outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                  >
+                    <span className="sr-only">{hiddenTitle}</span>
+                  </button>
+                ) : (
+                  <span className="sr-only">{hiddenTitle}</span>
+                )
+              ) : step.label || step.description || step.meta ? (
+                <div className={last ? L.textLast : L.text}>
+                  <div className={L.rowMeta}>
+                    {onSelect ? (
+                      // raw: a stretched button over the whole step, as Item does.
+                      <button
+                        type="button"
+                        onClick={() => onSelect(step, i)}
+                        className={cx(
+                          L.label,
+                          labelTone,
+                          isCurrent && "font-semibold",
+                          "rounded-sm text-left outline-none after:absolute after:inset-0 after:content-[''] hover:underline focus-visible:ring-2 focus-visible:ring-ring",
+                        )}
+                      >
+                        {title}
+                      </button>
+                    ) : (
+                      <span className={cx(L.label, labelTone, kind === "bar" && isCurrent && "font-semibold")}>{title}</span>
+                    )}
+                    {step.meta ? (
+                      <span data-nums className={cx("shrink-0 text-xs text-muted-foreground", L.meta)}>
+                        {step.meta}
+                      </span>
+                    ) : null}
+                  </div>
+                  {step.description ? <p className="mt-0.5 text-xs text-muted-foreground">{step.description}</p> : null}
+                </div>
+              ) : (
+                <span className="sr-only">{title}</span>
+              )}
+            </li>
+          );
+        })}
+      </ol>
+    </div>
+  );
+}

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

@@ -0,0 +1,33 @@
+import { cx } from "./cx";
+
+// A square of a colour that comes from DATA: a brand colour in an audit
+// row, a label's colour a user picked, a product variant. Server-safe.
+//
+// The one place in the kit that sets an inline background from a prop.
+// Every other colour in an app is a token; a colour that IS the record's
+// value cannot be one, so this part owns the inline style and nothing
+// else ever writes one (a block shows a data colour with a Swatch).
+//
+//   color      a CSS colour string from the data: "#0053fd", "rgb(…)",
+//              "oklch(…)", "rebeccapurple". An invalid one draws the
+//              empty square
+//   size       sm (16px, inline in a row) · md (24px)
+//   label      the accessible name: "Brand blue #0053FD". Without one the
+//              square is decoration and hidden from a screen reader —
+//              the text beside it must say the colour
+//
+// A hairline border keeps a colour close to the canvas (white on a light
+// page, black on a dark one) visible.
+const SIZES = { sm: "size-4 rounded-sm", md: "size-6 rounded-md" };
+
+export function Swatch({ color, size = "md", label, className }) {
+  return (
+    <span
+      role={label ? "img" : undefined}
+      aria-label={label || undefined}
+      aria-hidden={label ? undefined : "true"}
+      className={cx("inline-block shrink-0 border border-border align-middle", SIZES[size] ?? SIZES.md, className)}
+      style={{ backgroundColor: typeof color === "string" ? color : undefined }}
+    />
+  );
+}

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

@@ -0,0 +1,130 @@
+import { cx } from "./cx";
+import { Icon } from "./icon";
+
+// Table parts — the native <table> with the workspace's look. Presentation
+// only: the rows, the sort order and the selection are the caller's state;
+// these draw them. Server-safe (no hooks). `Table` is a scroll box, so a
+// wide table scrolls inside itself and never widens a 390px window; cells
+// do not wrap, so a narrow window scrolls rather than squashing columns.
+//
+//   <Table>
+//     <TableHeader><TableRow>
+//       <TableHead sort={dir} onSort={flip}>Name</TableHead>
+//       <TableHead numeric>Amount</TableHead>
+//     </TableRow></TableHeader>
+//     <TableBody>{rows.map((r) => (
+//       <TableRow key={r.id} selected={r.id === picked}>
+//         <TableCell>{r.name}</TableCell>
+//         <TableCell numeric>{r.amount}</TableCell>
+//       </TableRow>
+//     ))}</TableBody>
+//   </Table>
+//
+//   Table      variant outline (a bordered card; the default) · plain
+//   TableRow   selected — the row the rest of the surface is showing
+//   TableHead  sort asc · desc · none makes it a button with aria-sort;
+//              `onSort` is called on press and the caller picks the next
+//              order. One column is sorted at a time; the rest are none —
+//              or, sorting by several, pass each sorted column its
+//              `sortIndex` (1 first): the number shows beside the arrow.
+//              Pass it only while two or more are sorted
+//   numeric    TableHead and TableCell: right-aligned, tabular figures
+
+export function Table({ variant = "outline", className, children, ...rest }) {
+  return (
+    <div
+      className={cx(
+        "relative w-full max-w-full overflow-x-auto",
+        variant === "outline" && "rounded-lg border border-border bg-card text-card-foreground",
+        className,
+      )}
+    >
+      <table className="w-full caption-bottom border-collapse text-sm" {...rest}>
+        {children}
+      </table>
+    </div>
+  );
+}
+
+export function TableHeader({ className, ...rest }) {
+  return <thead className={cx("[&_tr]:border-b [&_tr]:hover:bg-transparent", className)} {...rest} />;
+}
+
+export function TableBody({ className, ...rest }) {
+  return <tbody className={cx("[&_tr:last-child]:border-b-0", className)} {...rest} />;
+}
+
+export function TableFooter({ className, ...rest }) {
+  return <tfoot className={cx("border-t border-border bg-muted/50 font-medium [&_tr]:border-b-0", className)} {...rest} />;
+}
+
+export function TableRow({ selected, className, ...rest }) {
+  return (
+    <tr
+      data-selected={selected ? "" : undefined}
+      className={cx("border-b border-border transition-colors hover:bg-muted/50 data-[selected]:bg-muted", className)}
+      {...rest}
+    />
+  );
+}
+
+const SORT = {
+  asc: { aria: "ascending", icon: "chevron-up" },
+  desc: { aria: "descending", icon: "chevron-down" },
+  none: { aria: undefined, icon: "chevrons-up-down" },
+};
+
+export function TableHead({ sort, onSort, sortIndex, numeric, scope = "col", className, children, ...rest }) {
+  const s = sort ? SORT[sort] ?? SORT.none : null;
+  return (
+    <th
+      scope={scope}
+      aria-sort={s?.aria}
+      className={cx(
+        "h-11 whitespace-nowrap px-3 text-left align-middle text-xs font-medium text-muted-foreground",
+        numeric && "text-right",
+        className,
+      )}
+      {...rest}
+    >
+      {s ? (
+        <button
+          type="button"
+          onClick={onSort}
+          className={cx(
+            "-mx-2 inline-flex min-h-9 items-center gap-1 rounded-md px-2 outline-none hover:bg-accent hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring",
+            sort !== "none" && "text-foreground",
+            numeric && "flex-row-reverse",
+          )}
+        >
+          {children}
+          {sortIndex != null && sort !== "none" ? (
+            <span className={cx("inline-flex items-center", numeric && "flex-row-reverse")}>
+              <Icon name={s.icon} size={14} />
+              <span className="sr-only">, sort priority </span>
+              <span className="font-semibold leading-none tabular-nums">{sortIndex}</span>
+            </span>
+          ) : (
+            <Icon name={s.icon} size={14} className={sort === "none" ? "opacity-50" : undefined} />
+          )}
+        </button>
+      ) : (
+        children
+      )}
+    </th>
+  );
+}
+
+export function TableCell({ numeric, className, ...rest }) {
+  return (
+    <td
+      data-nums={numeric ? "" : undefined}
+      className={cx("whitespace-nowrap px-3 py-2.5 align-middle", numeric && "text-right", className)}
+      {...rest}
+    />
+  );
+}
+
+export function TableCaption({ className, ...rest }) {
+  return <caption className={cx("px-3 py-3 text-left text-xs text-muted-foreground", className)} {...rest} />;
+}