makersclaw 0.8.0 → 0.8.1

package/registry/blocks/pace-bar/pace-bar.jsx

@@ -0,0 +1,461 @@
+"use client";
+
+import { Button, Empty, Notice, Skeleton, cx } from "../../ui";
+import { AgentMark } from "../agent-marks";
+import { axisOf, dayName, groupRows, marksOnWeeks, paceOf, paceSentence, paceWords, percent, share, shortDay, toneOf, weeksOf, WORDS } from "./pace-model";
+
+// Progress against a clock. Four pieces that share one idea, "how far
+// along, and how far along should it be by now":
+//
+//   PaceBar     one bar: filled to `value`, a hard upright tick at the pace,
+//               and the stretch between them hatched, so "behind" is a shape
+//               you see and not a sum you do.
+//   PaceList    many bars on ONE axis: the period's months and Mondays above,
+//               one today line running through the whole list, and each
+//               row's gap said in weeks ("4 wk behind"). Rows can sit in
+//               groups.
+//   PaceRuler   the axis alone (month names, a tick each Monday, a flag for
+//               today), for a screen that lays out its own rows.
+//   WeekStrip   the period as its weeks in one row: the weeks gone filled,
+//               this one marked, a mark on the week each check-in was made,
+//               by a person, by the agent, or by no one.
+//
+// Props in, one callback out (`onOpen`); the block imports only React, the
+// kit and the agent's mark. README.md beside this file lists every prop.
+// Server-safe: nothing here measures the page, positions are percentages.
+
+// ---- looks (literal class names, so Tailwind sees every one)
+
+const FILL = {
+  ink: "bg-foreground",
+  quiet: "bg-muted-foreground",
+  info: "bg-info",
+  success: "bg-success",
+  warning: "bg-warning",
+  danger: "bg-destructive",
+};
+// The hatch is drawn in currentColor, so a text-* token paints it.
+const HATCH_TEXT = {
+  ink: "text-foreground",
+  quiet: "text-muted-foreground",
+  info: "text-info",
+  success: "text-success",
+  warning: "text-warning",
+  danger: "text-destructive",
+};
+const GAP_TEXT = { ...HATCH_TEXT, ink: "text-muted-foreground" };
+const HATCH = { backgroundImage: "repeating-linear-gradient(135deg, currentColor 0 2px, transparent 2px 5px)" };
+
+const SIZE = {
+  lg: { track: "h-3.5", tick: "-inset-y-2" },
+  md: { track: "h-2.5", tick: "-inset-y-1" },
+  sm: { track: "h-1.5", tick: "-inset-y-1" },
+};
+
+const pct = (n) => `${Math.round(n * 1000) / 1000}%`;
+const asTone = (tone, p, cut) => (tone === "auto" || tone == null ? toneOf(p, cut) : FILL[tone] ? tone : "ink");
+
+/** What the bar is made of, without a meter's role: the fill, the hatched gap, and the tick when asked. */
+function Bars({ p, tone, size, hatch, tick, animate, delay }) {
+  const s = SIZE[size] ?? SIZE.md;
+  const fill = (p.value ?? 0) * 100;
+  const mark = p.pace == null ? null : p.pace * 100;
+  const spend = p.kind === "spend";
+  let from = 0;
+  let width = 0;
+  if (hatch && mark != null) {
+    if (!spend && mark > fill) [from, width] = [fill, mark - fill];
+    if (spend && fill > mark) [from, width] = [mark, fill - mark];
+  }
+  const grow = animate ? "transition-[width] duration-700 ease-out starting:w-0 motion-reduce:transition-none" : "";
+  const wait = animate && delay ? { transitionDelay: `${Math.min(540, Math.max(0, Number(delay) || 0))}ms` } : undefined;
+  return (
+    <>
+      <span className={cx("relative block overflow-hidden rounded-[1px] bg-muted", s.track)}>
+        {width ? (
+          <span
+            aria-hidden="true"
+            className={cx("absolute inset-y-0 left-(--from) w-(--width) opacity-60", HATCH_TEXT[tone])}
+            style={{ ...HATCH, "--from": pct(from), "--width": pct(width) }}
+          />
+        ) : null}
+        <span aria-hidden="true" className={cx("absolute inset-y-0 left-0 w-(--fill) rounded-[1px]", FILL[tone], grow)} style={{ "--fill": pct(fill), ...wait }} />
+      </span>
+      {tick && mark != null ? (
+        <span aria-hidden="true" className={cx("absolute left-(--mark) w-0.5 -translate-x-1/2 bg-foreground ring-1 ring-background", s.tick)} style={{ "--mark": pct(mark) }} />
+      ) : null}
+    </>
+  );
+}
+
+/**
+ * One bar against a pace. Give `pace` (0..1) yourself, or give the period
+ * (`start`, `end`, `today`) and the share of the time gone is the pace.
+ *
+ * Props: see README.md. In short: `value`, `pace`, `start`, `end`, `today`,
+ * `kind` (progress | spend), `tone` (ink | quiet | info | success | warning
+ * | danger | auto), `size` (lg | md | sm), `hatch`, `animate`, `delay`,
+ * `words`, `label`, `className`.
+ */
+export function PaceBar({ value, pace, start, end, today, kind = "progress", tone = "ink", size = "md", hatch = true, animate = false, delay = 0, words, tolerance, graceDays, graceFraction, label = "Progress", className }) {
+  const p = paceOf({ value, pace, start, end, today, kind, tolerance, graceDays, graceFraction });
+  const t = asTone(tone, p);
+  const valuetext = paceSentence(p, words) || (p.valuePct == null ? "not known" : `${p.valuePct}%`);
+  return (
+    <span
+      role="meter"
+      aria-label={label}
+      aria-valuemin={0}
+      aria-valuemax={100}
+      aria-valuenow={p.valuePct ?? 0}
+      aria-valuetext={`${valuetext}${p.state === "worse" || p.state === "better" || p.state === "on" ? `. ${paceWords(p, words)}` : ""}`}
+      className={cx("relative block min-w-0", className)}
+    >
+      <Bars p={p} tone={t} size={size} hatch={hatch} tick animate={animate} delay={delay} />
+    </span>
+  );
+}
+
+// ---- marks
+
+const MARK_WORDS = { person: "A person", agent: "The agent" };
+
+/**
+ * Who made a check-in: a filled dot for a person, the platform's mark for
+ * the agent, nothing for no one. With `empty` a mark made by no one is a
+ * hollow ring (the place a mark would be); with `missed` it is a dashed
+ * ring (a week that should have one and has none). `label` is what a
+ * screen reader hears; leave it out when words beside the mark already say it.
+ */
+export function PaceMark({ by, label, empty = false, missed = false, size = "sm", className }) {
+  const aria = label ? { role: "img", "aria-label": label, title: label } : { "aria-hidden": "true" };
+  const dot = size === "sm" ? "size-2" : "size-2.5";
+  if (by === "agent") return <AgentMark size={size === "sm" ? "xs" : size} label={label} className={className} />;
+  if (by === "person") return <span {...aria} className={cx("inline-block shrink-0 rounded-full bg-foreground", dot, className)} />;
+  if (missed) return <span {...aria} className={cx("inline-block shrink-0 rounded-full border border-dashed border-muted-foreground", dot, className)} />;
+  if (empty) return <span {...aria} className={cx("inline-block shrink-0 rounded-full border border-muted-foreground", dot, className)} />;
+  return null;
+}
+
+// ---- the ruler
+
+/** The flag's sides: a flag near the right edge hangs left of the line, near the left edge right of it. */
+const flagSide = (at) => (at > 0.78 ? "-translate-x-full" : at < 0.22 ? "" : "-translate-x-1/2");
+
+/**
+ * The axis of a period: month names, a tick each week start, the today
+ * line and its flag. Place it in the column your rows' bars share.
+ * Props: `start`, `end`, `today`, `weekStartsOn`, `words`, `showToday`,
+ * `label`, `className`.
+ */
+export function PaceRuler({ start, end, today, weekStartsOn = 0, words, showToday = true, label = "Period", className }) {
+  const w = { ...WORDS, ...words };
+  const axis = axisOf({ start, end, today, weekStartsOn });
+  if (!axis) return null;
+  const { period } = axis;
+  const at = showToday ? axis.todayAt : null;
+  const flag =
+    at == null
+      ? period.where === "before"
+        ? w.before
+        : null
+      : period.where === "after"
+        ? w.after
+        : `${w.today} · ${w.gone(percent(period.share))}`;
+  const summary = `${label}: ${shortDay(period.s)} to ${shortDay(period.e)}${period.t != null ? `. ${dayName(period.t)}${period.where === "in" ? `, ${percent(period.share)}% of the time gone, ${period.left} ${period.left === 1 ? "day" : "days"} left` : period.where === "after" ? ", ended" : ", not started"}` : ""}`;
+  return (
+    <span role="img" aria-label={summary} className={cx("relative block h-11 min-w-0", className)}>
+      {flag ? (
+        <span
+          aria-hidden="true"
+          className={cx(
+            "absolute top-0 z-10 whitespace-nowrap rounded-sm px-1.5 text-xs font-semibold leading-4",
+            at == null ? "left-0 bg-muted text-muted-foreground" : cx("bg-foreground text-background", flagSide(at)),
+          )}
+          style={at == null ? undefined : { left: pct(at * 100) }}
+        >
+          {flag}
+        </span>
+      ) : null}
+      <span aria-hidden="true" className="absolute inset-x-0 bottom-0 h-px bg-border" />
+      {axis.weeks.map((d) => (
+        <span key={`w${d.day}`} aria-hidden="true" className="absolute bottom-0 h-1.5 w-px bg-border" style={{ left: pct(d.at * 100) }} />
+      ))}
+      {axis.months.map((m) => (
+        <span key={`m${m.day}`} aria-hidden="true">
+          <span className="absolute bottom-0 h-2.5 w-px bg-foreground" style={{ left: pct(m.at * 100) }} />
+          <span className="absolute bottom-3 whitespace-nowrap pl-1 text-xs font-semibold text-foreground" style={{ left: pct(m.at * 100) }}>
+            {m.label}
+          </span>
+        </span>
+      ))}
+      {at != null ? <span aria-hidden="true" className="absolute inset-y-0 w-0.5 -translate-x-1/2 bg-foreground" style={{ left: pct(at * 100) }} /> : null}
+    </span>
+  );
+}
+
+// ---- the list
+
+// Rows are one grid, the same columns in every row, so the bars of every
+// row start and end at the same x: that is the shared axis. Narrow, a row is
+// its name on one line and the bar and number under it.
+const ROW = "grid grid-cols-[minmax(0,1fr)_4rem] items-center gap-x-3 gap-y-1 px-3 py-2 @2xl:grid-cols-(--cols)";
+// The name takes the whole narrow row; wide it is one column, or two (name and
+// meta) in a heading, where nothing sits in the meta column.
+const NAME = "col-span-2 @2xl:col-span-1";
+const NAME_WIDE = "col-span-2";
+const HEAD = "text-xs font-semibold uppercase tracking-wide text-muted-foreground";
+// The today line reaches into the row's padding and its border, so the lines
+// of the rows below one another read as one.
+const LINE = "pointer-events-none absolute -top-2 -bottom-[calc(0.5rem+1px)] w-0.5 -translate-x-1/2 bg-foreground";
+
+function Track({ children, at, className }) {
+  return (
+    <span className={cx("relative min-h-5 self-stretch", className)}>
+      {children}
+      {at != null ? <span aria-hidden="true" className={LINE} style={{ left: pct(at * 100) }} /> : null}
+    </span>
+  );
+}
+
+/**
+ * Many bars on one axis. `rows` are `{ id, label, sub, value, pace, kind,
+ * tone, by, byLabel, meta, note, group }`; `groups` are `{ id, label, sub,
+ * note, empty }`.
+ *
+ * Props: see README.md. In short: `rows`, `groups`, `start`, `end`,
+ * `today`, `pace`, `kind`, `tolerance`, `graceDays`, `graceFraction`, `unit`, `words`,
+ * `heads`, `ruler`, `metaWidth`, `trackWidth`, `gapWidth`, `size`, `selected`,
+ * `onOpen`, `loading`, `error`, `onRetry`, `empty`, `emptyAction`, `label`,
+ * `className`.
+ */
+export function PaceList({
+  rows,
+  groups,
+  start,
+  end,
+  today,
+  pace,
+  kind = "progress",
+  tolerance,
+  graceDays,
+  graceFraction,
+  unit,
+  words: wordsIn,
+  heads,
+  ruler = true,
+  weekStartsOn = 0,
+  warnAt,
+  dangerAt,
+  metaWidth,
+  trackWidth = "24rem",
+  gapWidth = "9rem",
+  size = "sm",
+  selected,
+  onOpen,
+  loading = false,
+  error,
+  onRetry,
+  empty,
+  emptyAction,
+  label = "Progress against the clock",
+  className,
+}) {
+  const words = { ...WORDS, ...wordsIn };
+  if (loading) {
+    return (
+      <div aria-busy="true" aria-label={`${label}, loading`} className={cx("@container grid min-w-0 gap-3 px-3 py-2", className)}>
+        <Skeleton shape="rect" className="h-8 w-full" />
+        {[0, 1, 2, 3].map((i) => (
+          <Skeleton key={i} shape="rect" className="h-5 w-full" />
+        ))}
+      </div>
+    );
+  }
+  if (error) {
+    return (
+      <div className={cx("@container min-w-0", className)}>
+        <Notice tone="danger" title={`${label} did not load`} action={onRetry ? <Button size="sm" onClick={onRetry}>Try again</Button> : null}>
+          {typeof error === "string" ? error : "Something went wrong reading the rows."}
+        </Notice>
+      </div>
+    );
+  }
+
+  const axis = axisOf({ start, end, today, weekStartsOn });
+  const sharedPace = pace === undefined ? undefined : share(pace);
+  // The line: the end of today on the period, or the pace given.
+  const lineAt = axis ? axis.todayAt : sharedPace ?? null;
+  const list = rows ?? [];
+  const cols = ["minmax(0,1fr)", metaWidth, `minmax(10rem,${trackWidth})`, "4rem", gapWidth].filter(Boolean).join(" ");
+  const style = { "--cols": cols };
+  // In a heading the name also takes the meta column's place.
+  const headName = cx("min-w-0", metaWidth ? NAME_WIDE : NAME);
+
+  if (!list.length && !(groups ?? []).length) {
+    return (
+      <div className={cx("@container min-w-0", className)}>
+        <Empty icon="clock" title={empty ?? "Nothing to measure yet"} action={emptyAction} />
+      </div>
+    );
+  }
+
+  const read = new Map(
+    list.map((r) => {
+      const p = paceOf({
+        value: r.value,
+        pace: r.pace === undefined ? sharedPace : r.pace,
+        start,
+        end,
+        today,
+        kind: r.kind ?? kind,
+        tolerance,
+        graceDays,
+        graceFraction,
+        unit: r.unit ?? unit,
+      });
+      return [r, { p, tone: asTone(r.tone, p, { warnAt, dangerAt }) }];
+    }),
+  );
+  const grouped = groupRows(list, groups);
+
+  const head = heads ?? {};
+  const showRuler = ruler && axis;
+  const summary = `${label}: ${list.length} ${list.length === 1 ? "row" : "rows"}${axis?.period.t != null && axis.period.where === "in" ? `, ${percent(axis.period.share)}% of the time gone` : ""}`;
+
+  return (
+    <div role="group" aria-label={summary} className={cx("@container min-w-0", className)}>
+      {showRuler || head.label || head.pct || head.gap ? (
+        <div className={cx(ROW, "border-b border-border bg-background")} style={style}>
+          <span className={cx(HEAD, "self-end", headName)}>{head.label}</span>
+          <span className="relative col-span-2 min-w-0 self-stretch @2xl:col-span-1">
+            {showRuler ? <PaceRuler start={start} end={end} today={today} weekStartsOn={weekStartsOn} words={words} label={label} /> : null}
+            {showRuler && lineAt != null ? <span aria-hidden="true" className="absolute top-full h-[calc(0.5rem+1px)] w-0.5 -translate-x-1/2 bg-foreground" style={{ left: pct(lineAt * 100) }} /> : null}
+          </span>
+          <span className={cx(HEAD, "hidden self-end text-right @2xl:block")}>{head.pct}</span>
+          <span className={cx(HEAD, "hidden self-end @2xl:block")}>{head.gap}</span>
+        </div>
+      ) : null}
+      {grouped.map(({ group, rows: inGroup }, gi) => (
+        <div key={group?.id ?? `rest-${gi}`} role="group" aria-label={group?.label ?? undefined}>
+          {group ? (
+            <div className={cx(ROW, "border-b border-border bg-background")} style={style}>
+              <div className={cx("flex flex-wrap items-baseline gap-x-3 gap-y-0.5", headName)}>
+                <h3 className="text-sm font-semibold">{group.label}</h3>
+                {group.sub ? <span className="text-xs text-muted-foreground">{group.sub}</span> : null}
+                {!inGroup.length && group.empty ? <span className="text-xs text-muted-foreground">{group.empty}</span> : null}
+                {group.note ? <span className="text-xs text-muted-foreground">{group.note}</span> : null}
+              </div>
+              <Track at={lineAt} className="hidden @2xl:block" />
+              <span className="hidden @2xl:block" />
+              <span className="hidden @2xl:block" />
+            </div>
+          ) : null}
+          <ul className="m-0 grid list-none p-0">
+            {inGroup.map((r, i) => {
+              const { p, tone } = read.get(r);
+              const said = r.note ?? paceWords(p, words);
+              const Tag = onOpen ? "button" : "div";
+              const on = selected != null && selected === r.id;
+              // A row with a pace of its own gets its own tick; one on the shared clock leaves it to the line.
+              const own = p.pace != null && lineAt != null && Math.abs(p.pace - lineAt) > 0.004;
+              return (
+                <li key={r.id ?? i} className="min-w-0">
+                  <Tag
+                    {...(onOpen ? { type: "button", onClick: () => onOpen(r), "aria-current": on ? "true" : undefined } : {})}
+                    className={cx(
+                      ROW,
+                      "w-full border-b border-border text-left outline-none",
+                      onOpen && "cursor-pointer hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset",
+                      on && "bg-accent",
+                    )}
+                    style={style}
+                  >
+                    <span className={cx("min-w-0", NAME)}>
+                      <span className="block break-words text-sm font-medium leading-snug">{r.label}</span>
+                      {r.sub ? <span className="block break-words text-xs text-muted-foreground">{r.sub}</span> : null}
+                    </span>
+                    {metaWidth ? <span className="col-span-2 min-w-0 @2xl:col-span-1">{r.meta}</span> : null}
+                    <Track at={lineAt} className="col-start-1 @2xl:col-start-auto">
+                      <span className="absolute inset-x-0 top-1/2 block -translate-y-1/2">
+                        <span className="relative block">
+                          <Bars p={p} tone={tone} size={size} hatch tick={own} />
+                        </span>
+                      </span>
+                    </Track>
+                    <span className="col-start-2 flex items-center justify-end gap-1.5 text-sm font-semibold tabular-nums @2xl:col-start-auto">
+                      <PaceMark by={r.by} label={r.byLabel ?? (r.by ? MARK_WORDS[r.by] : undefined)} />
+                      <span>{p.valuePct == null ? "–" : `${p.valuePct}%`}</span>
+                    </span>
+                    <span className={cx("col-span-2 min-w-0 break-words text-xs @2xl:col-span-1", p.state === "worse" && tone !== "ink" ? cx("font-medium", GAP_TEXT[tone]) : "text-muted-foreground")}>{said}</span>
+                  </Tag>
+                </li>
+              );
+            })}
+          </ul>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+// ---- the week strip
+
+const WEEK_WORD = "Week";
+
+/**
+ * The period as its weeks in one row. A week gone is filled, the current
+ * one is marked, weeks to come are empty. A mark sits on the week its date
+ * falls in: a filled dot for a person, the agent's mark, or (with `missed`)
+ * a dashed ring on a past week with no mark at all.
+ *
+ * Props: `start`, `end`, `today`, `marks` [{ id, date, by, label }],
+ * `weekStartsOn`, `missed`, `onOpen(week)`, `words`, `label`, `className`.
+ */
+export function WeekStrip({ start, end, today, marks, weekStartsOn = 0, missed = false, onOpen, words, label = "Weeks", className }) {
+  const w = { week: WEEK_WORD, ...words };
+  const base = weeksOf({ start, end, today, weekStartsOn });
+  if (!base.length) return null;
+  const { weeks, skipped } = marksOnWeeks(base, marks);
+  const current = weeks.find((x) => x.current);
+  const total = weeks.reduce((n, x) => n + x.marks.length, 0);
+  const summary = `${label}: ${weeks.length} ${weeks.length === 1 ? "week" : "weeks"}${current ? `, ${w.week.toLowerCase()} ${current.n} now` : ""}, ${total} ${total === 1 ? "mark" : "marks"}${skipped ? `, ${skipped} without a date left off` : ""}`;
+  return (
+    <div className={cx("@container min-w-0", className)}>
+      <div role="region" aria-label={`${label}, scrolls sideways`} tabIndex={0} className="overflow-x-auto rounded-sm outline-none focus-visible:ring-2 focus-visible:ring-ring">
+        <ol aria-label={summary} className="m-0 grid list-none gap-0.5 p-0" style={{ gridTemplateColumns: `repeat(${weeks.length}, minmax(1.5rem, 1fr))` }}>
+          {weeks.map((x) => {
+            const Tag = onOpen ? "button" : "div";
+            const name = `${w.week} ${x.n}, ${shortDay(x.from)} to ${shortDay(x.to)}${x.current ? ", now" : ""}${x.marks.length ? `, ${x.marks.map((m) => m.label ?? MARK_WORDS[m.by] ?? "a mark").join(", ")}` : ""}`;
+            return (
+              <li key={x.n} className="min-w-0">
+                <Tag
+                  {...(onOpen ? { type: "button", onClick: () => onOpen(x), "aria-label": name } : { role: "img", "aria-label": name })}
+                  {...(x.current ? { "aria-current": "date" } : {})}
+                  className={cx("grid w-full min-w-0 justify-items-center gap-1 rounded-sm px-0.5 py-1 outline-none", onOpen && "cursor-pointer hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring")}
+                >
+                  <span aria-hidden="true" className={cx("text-xs tabular-nums", x.current ? "font-semibold text-foreground" : "text-muted-foreground")}>
+                    {x.n}
+                  </span>
+                  <span
+                    aria-hidden="true"
+                    className={cx("block w-full rounded-[1px]", x.state === "past" ? "h-1.5 bg-muted-foreground" : x.current ? "h-2.5 bg-foreground" : "h-1.5 bg-muted")}
+                  />
+                  <span aria-hidden="true" className="flex min-h-3 flex-wrap items-center justify-center gap-0.5">
+                    {x.marks.slice(0, 3).map((m) => (
+                      <PaceMark key={m.id} by={m.by} empty />
+                    ))}
+                    {x.marks.length > 3 ? <span className="text-xs text-muted-foreground">+{x.marks.length - 3}</span> : null}
+                    {missed && x.state === "past" && !x.marks.length ? <PaceMark missed /> : null}
+                  </span>
+                </Tag>
+              </li>
+            );
+          })}
+        </ol>
+      </div>
+    </div>
+  );
+}
+
+export default PaceBar;