makersclaw 0.7.0 → 0.8.1

package/registry/blocks/schedule-ruler/schedule-ruler.jsx

@@ -0,0 +1,548 @@
+"use client";
+
+import { Button, Empty, Icon, Notice, Skeleton, cx } from "../../ui";
+import {
+  dayName,
+  dayNumber,
+  gapOf,
+  gapWords,
+  gateOf,
+  axisOf,
+  frameOf,
+  labelPct,
+  layoutLanes,
+  placeLabel,
+  readMilestones,
+  readSegments,
+  shortDay,
+  summaryOf,
+} from "./ruler-model";
+
+// ScheduleRuler: a dated chain drawn to scale, like a surveyor's chain.
+// A baseline of days (a tick each Monday, a taller one on the 1st); the
+// segments of the chain as bars with their names; a gate post at the end of
+// a segment, built from its exit criteria as pips; milestone diamonds; the
+// target as a solid line and the forecast as a dashed one, and between them
+// the gap hatched: green when the forecast lands early (slack), red when it
+// lands late (an overrun), with its size in working days ("+3 d"). Today is
+// a line in the accent.
+//
+// GapRuler is the target against the forecast and nothing else, for a
+// sentence to sit beside. ScheduleStrip is the chain small, one row, for a
+// row in a list.
+//
+// Positions are percentages of the chain's width: nothing measures the page,
+// so the server's HTML and the browser agree. The chain is never narrower
+// than `minWidth`; a container narrower than that scrolls it sideways and,
+// under 36rem of its own width, also lists the chain in words below it.
+// Props in, one callback out (`onOpen`); it imports only React and the kit.
+// README.md beside this file lists every prop.
+
+const AXIS = 30;
+const MILE_H = 20;
+const GHOST_H = 14;
+const GATE_H = 38;
+const FLAG_H = 22;
+
+// The hatch is drawn in currentColor, so a text-* token paints it.
+const HATCH = { backgroundImage: "repeating-linear-gradient(135deg, currentColor 0 1.5px, transparent 1.5px 7px)" };
+const HATCH_FINE = { backgroundImage: "repeating-linear-gradient(135deg, currentColor 0 1.2px, transparent 1.2px 5px)" };
+
+// A segment's status: done (solid, success) · active (solid ink) · planned
+// (an ink outline) · late (solid accent: past its gate) · draft (dashed,
+// breathing: still being written).
+const TONE = {
+  done: "bg-success text-background border border-success",
+  active: "bg-foreground text-background border border-foreground",
+  planned: "bg-background text-foreground border border-foreground",
+  late: "bg-primary text-primary-foreground border border-primary",
+  draft: "border-[1.5px] border-dashed border-muted-foreground bg-background text-muted-foreground motion-safe:animate-pulse",
+};
+const STRIP = {
+  done: "bg-success",
+  active: "bg-foreground",
+  late: "bg-primary",
+  planned: "border border-foreground bg-background",
+  draft: "border border-dashed border-muted-foreground",
+};
+const STATUS_WORDS = { done: "done", active: "in progress", planned: "planned", late: "late", draft: "draft" };
+
+const GAP_TEXT = { over: "text-destructive", slack: "text-success", on: "text-foreground" };
+const GAP_LINE = { over: "border-destructive", slack: "border-success", on: "border-foreground" };
+
+const WORDS = {
+  target: "Target",
+  forecast: "Forecast",
+  today: "Today",
+  on: "On target",
+  over: (n) => `+${n} d`,
+  slack: (n) => `${n} d slack`,
+  undated: (n) => `${n} without dates, left off`,
+  early: "Earlier plan",
+};
+
+const pct = (n) => `${n}%`;
+
+/** The things every form of the ruler reads the same way. */
+function readProps({ segments, milestones, target, forecast, today, count, workweek }) {
+  const { segs, skipped } = readSegments(segments);
+  const miles = readMilestones(milestones);
+  const tgt = dayNumber(target);
+  const t = dayNumber(today);
+  // forecast: undefined → the chain's own last day; null or "" → none.
+  const derived = forecast === undefined && segs.length ? Math.max(...segs.map((p) => p.e)) : null;
+  const fc = forecast === undefined ? derived : dayNumber(forecast);
+  const gap = gapOf({ target: tgt, forecast: fc, count, workweek });
+  return { segs, skipped, miles, tgt, fc, t, gap };
+}
+
+/**
+ * The full chain.
+ *
+ * Props: see README.md. In short: `segments` [{ id, label, start, end,
+ * status, sub, gate }], `milestones` [{ id, date, label, done }], `target`,
+ * `forecast`, `today`, `ghost`, `count`, `words`, `compact`, `minWidth`,
+ * `onOpen`, `loading`, `error`, `onRetry`, `empty`, `emptyAction`.
+ */
+export function ScheduleRuler({
+  segments,
+  milestones,
+  start,
+  target,
+  forecast,
+  today,
+  ghost,
+  count = "working",
+  workweek,
+  words: wordsIn,
+  compact = false,
+  minWidth = 560,
+  fitToday = true,
+  from,
+  to,
+  onOpen,
+  loading = false,
+  error,
+  onRetry,
+  empty,
+  emptyAction,
+  label = "Schedule",
+  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", className)}>
+        <Skeleton shape="rect" className="h-4 w-full" />
+        <Skeleton shape="rect" className="h-12 w-full" />
+        <Skeleton shape="rect" className="h-4 w-2/3" />
+      </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 dates."}
+        </Notice>
+      </div>
+    );
+  }
+
+  const { segs, skipped, miles, tgt, fc, t, gap } = readProps({ segments, milestones, target, forecast, today, count, workweek });
+  const startDay = dayNumber(start);
+  const ghosts = (ghost ?? [])
+    .map((g) => ({ s: dayNumber(g?.start), e: dayNumber(g?.end) }))
+    .filter((g) => g.s != null && g.e != null && g.e >= g.s);
+  const days = [
+    startDay,
+    ...segs.flatMap((p) => [p.s, p.e + 1]),
+    ...miles.flatMap((m) => [m.day, m.day + 1]),
+    tgt != null ? tgt + 1 : null,
+    fc != null ? fc + 1 : null,
+    ...ghosts.flatMap((g) => [g.s, g.e + 1]),
+    fitToday && t != null ? t : null,
+  ].filter((d) => d != null);
+  const frame = segs.length || miles.length || tgt != null ? frameOf({ days, from: dayNumber(from), to: dayNumber(to) }) : null;
+
+  if (!frame) {
+    return (
+      <div className={cx("@container min-w-0", className)}>
+        <Empty
+          icon="calendar"
+          title={empty ?? "Nothing is dated yet"}
+          body={skipped ? words.undated(skipped) : null}
+          action={emptyAction}
+        />
+      </div>
+    );
+  }
+
+  const { r0, r1, x } = frame;
+  const axis = axisOf(r0, r1);
+  const inWindow = (d) => d != null && d >= r0 && d <= r1;
+  const tIn = inWindow(t) ? t : null;
+
+  // ---- rows, top to bottom, in px
+  const mileItems = miles.map((m) => {
+    const text = `${m.label} ${shortDay(m.day)}`;
+    const w = labelPct(text.length, minWidth, 26);
+    const px = x(m.day) + (100 / (r1 - r0)) / 2;
+    return { id: m.id, m, px, ...placeLabel({ x: px, width: w, prefer: m.side ?? "right" }) };
+  });
+  const mileLay = layoutLanes(mileItems);
+  const mileZone = miles.length ? mileLay.count * MILE_H + 6 : 0;
+  const ghostZone = ghosts.length ? GHOST_H + 4 : 0;
+  const bandTop = AXIS + mileZone + ghostZone + 8;
+  const bandH = compact ? 36 : 48;
+  const bandBottom = bandTop + bandH;
+
+  const gateItems = compact
+    ? []
+    : segs
+        .map((p) => ({ p, g: gateOf(p.gate, p.e, t) }))
+        .filter((r) => r.g)
+        .map(({ p, g }) => {
+          const gx = x(g.day + 1);
+          // The date and the count share a line; the pips (12px each) are the other.
+          const chars = Math.max(shortDay(g.day).length + (g.total ? 5 : 0), g.total * 1.7);
+          return { id: p.id, p, g, gx, ...placeLabel({ x: gx, width: labelPct(chars, minWidth, 8), prefer: "left" }) };
+        });
+  const gateLay = layoutLanes(gateItems);
+  const gateZone = gateItems.length ? 8 + gateLay.count * GATE_H : 0;
+
+  const gapTop = bandBottom + gateZone + 4;
+  const gapRow = gap ? 20 : 0;
+
+  const flags = [];
+  if (tgt != null) flags.push({ id: "target", day: tgt + 1, text: `${words.target} ${dayName(tgt)}`, kind: "target" });
+  if (fc != null && gap?.state !== "on" && (tgt != null || forecast !== undefined)) flags.push({ id: "forecast", day: fc + 1, text: `${words.forecast} ${dayName(fc)}`, kind: "forecast" });
+  if (tIn != null) flags.push({ id: "today", day: tIn, text: `${words.today} ${shortDay(tIn)}`, kind: "today" });
+  const flagItems = compact
+    ? []
+    : flags.map((f) => {
+        const fx = x(f.day);
+        return { ...f, fx, ...placeLabel({ x: fx, width: labelPct(f.text.length, minWidth, 18), prefer: "right" }) };
+      });
+  const flagLay = layoutLanes(flagItems);
+  const flagTop = gapTop + gapRow + 6;
+  const flagZone = flagItems.length ? flagLay.count * FLAG_H : 0;
+  const height = (compact ? bandBottom + 6 + gapRow : flagTop + flagZone) + 4;
+  const bottomOf = (lane) => flagTop + lane * FLAG_H + 18;
+  // A line runs down to its own flag; with no flag drawn (compact) it stops under the band.
+  const lineBottom = (id) => (flagLay.lanes[id] != null ? bottomOf(flagLay.lanes[id]) : bandBottom + 8);
+
+  const summary = summaryOf({
+    label,
+    segs: segs.map((p) => ({ ...p, status: STATUS_WORDS[p.status] ?? p.status, gate: gateOf(p.gate, p.e, t) })),
+    milestones: miles,
+    target: tgt,
+    forecast: fc,
+    gap,
+    today: t,
+    words,
+  });
+  const open = (kind, item) => (onOpen ? () => onOpen({ kind, id: item.id, item }) : undefined);
+
+  return (
+    <div role="group" aria-label={label} className={cx("@container grid min-w-0 gap-3", className)}>
+      <p className="sr-only">{summary}</p>
+      <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">
+        <div className="relative w-full" style={{ minWidth, height }}>
+          {/* the axis */}
+          <span aria-hidden="true" className="absolute inset-x-0 h-px bg-foreground" style={{ top: AXIS - 4 }} />
+          {axis.weeks.map((d) => (
+            <span key={`w${d}`} aria-hidden="true" className="absolute h-[5px] w-px bg-foreground" style={{ left: pct(x(d)), top: AXIS - 9 }} />
+          ))}
+          {axis.months.map((m) => (
+            <span key={`m${m.day}`} aria-hidden="true">
+              {m.tick ? <span className="absolute h-[17px] w-px bg-foreground" style={{ left: pct(x(m.day)), top: AXIS - 21 }} /> : null}
+              <span className="absolute top-0 whitespace-nowrap pl-1.5 font-mono text-xs uppercase tracking-[0.06em] text-muted-foreground" style={{ left: pct(x(m.day)) }}>
+                {m.label}
+              </span>
+            </span>
+          ))}
+
+          {/* milestones */}
+          {mileItems.map((m) => {
+            const lane = mileLay.lanes[m.id];
+            const top = AXIS + 4 + lane * MILE_H;
+            const Mark = onOpen ? "button" : "span";
+            return (
+              <Mark
+                key={m.id}
+                {...(onOpen ? { type: "button", onClick: open("milestone", m.m), "aria-label": `${m.m.label}${m.m.done ? ", done" : ""}, ${dayName(m.m.day)}` } : { "aria-hidden": "true" })}
+                className={cx("absolute flex h-[18px] items-center gap-1.5 whitespace-nowrap rounded-sm bg-background pr-1 text-left font-mono text-xs outline-none", onOpen && "focus-visible:ring-2 focus-visible:ring-ring")}
+                style={m.side === "right" ? { left: `calc(${pct(m.px)} - 6px)`, top } : { right: `calc(${pct(100 - m.px)} - 6px)`, top, flexDirection: "row-reverse" }}
+              >
+                <span aria-hidden="true" className={cx("block size-[11px] shrink-0 rotate-45 border-[1.5px] border-foreground", m.m.done ? "bg-foreground" : "bg-background")} />
+                <span className="font-sans text-xs font-medium text-foreground">{m.m.label}</span>
+                <span className="text-muted-foreground">{shortDay(m.m.day)}</span>
+              </Mark>
+            );
+          })}
+
+          {/* where the chain sat before */}
+          {ghosts.map((g, i) => (
+            <span
+              key={`g${i}`}
+              aria-hidden="true"
+              title={words.early}
+              className="absolute border border-dashed border-muted-foreground"
+              style={{ left: pct(x(g.s)), width: `calc(${x(g.e + 1) - x(g.s)}% - 3px)`, top: bandTop - GHOST_H - 3, height: GHOST_H - 4 }}
+            />
+          ))}
+
+          {/* the segments */}
+          {segs.map((p, i) => {
+            const x0 = x(p.s);
+            const x1 = x(p.e + 1);
+            const Seg = onOpen ? "button" : "span";
+            const status = STATUS_WORDS[p.status] ?? p.status ?? "planned";
+            return (
+              <Seg
+                key={p.id}
+                {...(onOpen
+                  ? { type: "button", onClick: open("segment", p), "aria-label": `${p.label}, ${status}, ${shortDay(p.s)} to ${shortDay(p.e)}` }
+                  : { "aria-hidden": "true" })}
+                title={`${p.label}, ${status}, ${shortDay(p.s)} to ${shortDay(p.e)}`}
+                className={cx(
+                  "absolute flex min-w-[3px] flex-col justify-between overflow-hidden px-2.5 py-2 text-left outline-none",
+                  TONE[p.status] ?? TONE.planned,
+                  onOpen && "focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1",
+                )}
+                style={{ left: pct(x0), width: `calc(${x1 - x0}% - 3px)`, top: bandTop, height: bandH }}
+              >
+                <span className="truncate text-sm font-semibold leading-tight">{p.label}</span>
+                {compact ? null : <span className="truncate font-mono text-xs leading-tight">{p.sub ?? i + 1}</span>}
+              </Seg>
+            );
+          })}
+
+          {/* the gap: slack in green, an overrun in red, hatched */}
+          {gap && gap.state !== "on" ? (
+            <span
+              aria-hidden="true"
+              className={cx("absolute border-2 border-current bg-background/70", GAP_TEXT[gap.state])}
+              style={{ ...HATCH, left: `calc(${x(gap.from)}% + 1px)`, width: `max(3px, calc(${x(gap.to + 1) - x(gap.from)}% - 3px))`, top: bandTop, height: bandH }}
+            />
+          ) : null}
+          {gap ? (
+            <span
+              aria-hidden="true"
+              className={cx("absolute whitespace-nowrap font-mono text-xs font-semibold", GAP_TEXT[gap.state])}
+              style={
+                gap.state === "on"
+                  ? { left: pct(x(gap.target + 1)), top: gapTop, transform: x(gap.target + 1) > 78 ? "translateX(-100%)" : undefined }
+                  : x(gap.from) > 72
+                    ? { right: pct(100 - x(gap.to + 1)), top: gapTop }
+                    : { left: pct(x(gap.from)), top: gapTop }
+              }
+            >
+              {gapWords(gap, words)}
+            </span>
+          ) : null}
+
+          {/* gate posts */}
+          {gateItems.map(({ id, p, g, gx, side }) => {
+            const lane = gateLay.lanes[id];
+            const top = bandBottom + 8 + lane * GATE_H;
+            const stateTone = g.state === "overdue" ? "text-destructive" : "text-muted-foreground";
+            const Post = onOpen && g.total ? "button" : "span";
+            const said = `${p.label} gate, ${shortDay(g.day)}${g.total ? `, ${g.met} of ${g.total} criteria met` : ""}${g.state === "overdue" ? ", overdue" : ""}`;
+            return (
+              <span key={`gate-${id}`}>
+                <span aria-hidden="true" className="absolute w-px bg-foreground" style={{ left: `calc(${pct(gx)} - 3.5px)`, top: bandBottom, height: 8 + lane * GATE_H }} />
+                <span
+                  aria-hidden="true"
+                  className={cx("absolute size-[9px] border border-foreground", g.state === "met" ? "bg-success border-success" : "bg-background")}
+                  style={{ left: `calc(${pct(gx)} - 8px)`, top: bandBottom - 4 }}
+                />
+                <Post
+                  {...(Post === "button" ? { type: "button", onClick: open("gate", p), "aria-label": said } : { "aria-hidden": "true" })}
+                  className={cx(
+                    "absolute grid gap-1 rounded-sm bg-background px-1 text-left outline-none",
+                    Post === "button" && "focus-visible:ring-2 focus-visible:ring-ring",
+                    side === "left" ? "justify-items-end" : "justify-items-start",
+                  )}
+                  style={side === "left" ? { right: `calc(${pct(100 - gx)} + 6px)`, top } : { left: `calc(${pct(gx)} + 3px)`, top }}
+                >
+                  <span className={cx("font-mono text-xs leading-none", stateTone)}>
+                    {shortDay(g.day)}
+                    {g.total ? <span className="ml-1.5 tabular-nums">{g.met}/{g.total}</span> : null}
+                  </span>
+                  {g.total ? (
+                    <span className="flex items-center gap-[3px]">
+                      {g.pips.map((pip, k) => (
+                        <span
+                          key={pip.id ?? k}
+                          title={`${pip.label ?? "Criterion"}${pip.met ? ", met" : ", not met"}`}
+                          className={cx("block size-[9px] rounded-full border", pip.met ? "border-success bg-success" : "border-foreground bg-background")}
+                        />
+                      ))}
+                    </span>
+                  ) : null}
+                </Post>
+              </span>
+            );
+          })}
+
+          {/* the target, the forecast, today */}
+          {tgt != null ? (
+            <span aria-hidden="true" className="absolute w-0.5 bg-foreground" style={{ left: `calc(${pct(x(tgt + 1))} - 2px)`, top: AXIS - 14, height: lineBottom("target") - (AXIS - 14) }} />
+          ) : null}
+          {fc != null && gap?.state !== "on" && flags.some((f) => f.id === "forecast") ? (
+            <span
+              aria-hidden="true"
+              className={cx("absolute w-0 border-l-2 border-dashed", gap ? GAP_LINE[gap.state] : "border-foreground")}
+              style={{ left: `calc(${pct(x(fc + 1))} - 2px)`, top: AXIS - 14, height: lineBottom("forecast") - (AXIS - 14) }}
+            />
+          ) : null}
+          {tIn != null ? (
+            <span aria-hidden="true" className="absolute w-0.5 bg-primary" style={{ left: `calc(${pct(x(tIn))} - 1px)`, top: AXIS - 4, height: (compact ? bandBottom + 6 : lineBottom("today")) - (AXIS - 4) }} />
+          ) : null}
+          {flagItems.map((f) => {
+            const lane = flagLay.lanes[f.id];
+            const top = flagTop + lane * FLAG_H;
+            const place = f.side === "left" ? { right: `calc(${pct(100 - f.fx)} + 6px)` } : { left: `calc(${pct(f.fx)} + 6px)` };
+            const tone = f.kind === "forecast" ? (gap ? GAP_TEXT[gap.state] : "text-foreground") : "text-foreground";
+            return f.kind === "today" ? (
+              <span
+                key={f.id}
+                aria-hidden="true"
+                className="absolute whitespace-nowrap bg-primary px-1.5 py-0.5 font-mono text-xs font-medium text-primary-foreground"
+                style={f.side === "left" ? { right: `calc(${pct(100 - f.fx)} - 1px)`, top } : { left: `calc(${pct(f.fx)} - 1px)`, top }}
+              >
+                {f.text}
+              </span>
+            ) : (
+              <span key={f.id} aria-hidden="true" className={cx("absolute flex items-center gap-1 whitespace-nowrap bg-background px-1 font-mono text-xs font-medium", tone)} style={{ ...place, top }}>
+                <Icon name="flag" size={12} className="shrink-0" />
+                {f.text}
+              </span>
+            );
+          })}
+        </div>
+      </div>
+
+      {skipped ? <p className="text-xs text-muted-foreground">{words.undated(skipped)}</p> : null}
+
+      {/* under 36rem the same chain in words, because a scrolled picture hides its ends */}
+      <ol aria-hidden="true" className="grid min-w-0 gap-1.5 @xl:hidden">
+        {segs.map((p, i) => {
+          const g = gateOf(p.gate, p.e, t);
+          return (
+            <li key={p.id} className="flex min-w-0 items-baseline justify-between gap-3 border-t border-border pt-1.5 text-sm">
+              <span className="min-w-0 truncate font-medium">{i + 1}. {p.label}</span>
+              <span className="shrink-0 text-right font-mono text-xs tabular-nums text-muted-foreground">
+                {shortDay(p.s)} to {shortDay(p.e)}
+                {g?.total ? ` · ${g.met}/${g.total} met` : ""}
+              </span>
+            </li>
+          );
+        })}
+        {miles.map((m) => (
+          <li key={m.id} className="flex min-w-0 items-baseline justify-between gap-3 border-t border-border pt-1.5 text-sm">
+            <span className="min-w-0 truncate font-medium">{m.label}</span>
+            <span className="shrink-0 font-mono text-xs tabular-nums text-muted-foreground">{shortDay(m.day)}{m.done ? " · done" : ""}</span>
+          </li>
+        ))}
+        {tgt != null || gap ? (
+          <li className="flex min-w-0 flex-col gap-0.5 border-t border-border pt-1.5 font-mono text-xs tabular-nums">
+            {tgt != null ? <span className="text-foreground">{words.target} {dayName(tgt)}</span> : null}
+            {fc != null && gap?.state !== "on" ? <span className={gap ? GAP_TEXT[gap.state] : "text-foreground"}>{words.forecast} {dayName(fc)}</span> : null}
+            {gap ? <span className={cx("font-semibold", GAP_TEXT[gap.state])}>{gapWords(gap, words)}</span> : null}
+          </li>
+        ) : null}
+      </ol>
+    </div>
+  );
+}
+
+/**
+ * The target against the forecast, drawn and nothing else: a dashed line
+ * for the target, a solid bar for the forecast, the gap between them
+ * hatched (green early, red late) and its size in words underneath. For a
+ * sentence to sit beside ("Public launch lands Tue 3 Nov").
+ */
+export function GapRuler({ target, forecast, count = "working", workweek, words: wordsIn, label, width = 380, className }) {
+  const words = { ...WORDS, ...wordsIn };
+  const gap = gapOf({ target, forecast, count, workweek });
+  if (!gap) return null;
+  const lo = Math.min(gap.target, gap.forecast);
+  const hi = Math.max(gap.target, gap.forecast);
+  const total = Math.max(hi - lo + 6, 14);
+  const r0 = lo - Math.floor((total - (hi - lo)) / 2);
+  const at = (d) => ((d - r0) / total) * 100;
+  const tx = at(gap.target);
+  const fx = at(gap.forecast);
+  const a = Math.min(tx, fx);
+  const b = Math.max(tx, fx);
+  const tone = GAP_TEXT[gap.state];
+  const earlierIsTarget = gap.target <= gap.forecast;
+  const said = label ?? gapWords(gap, words);
+  return (
+    <div
+      role="img"
+      aria-label={`${words.target} ${dayName(gap.target)}, ${words.forecast.toLowerCase()} ${dayName(gap.forecast)}: ${said}`}
+      className={cx("@container relative h-[92px] w-full min-w-0", className)}
+      style={{ maxWidth: width }}
+    >
+      <span aria-hidden="true" className="absolute inset-x-0 top-[46px] h-px bg-foreground" />
+      {gap.state !== "on" ? (
+        <span aria-hidden="true" className={cx("absolute top-[34px] h-6 border-y-2 border-current", tone)} style={{ ...HATCH, left: pct(a), width: pct(b - a) }} />
+      ) : null}
+      <span aria-hidden="true" className="absolute top-6 h-11 w-0 border-l-[1.5px] border-dashed border-foreground" style={{ left: pct(tx) }} />
+      <span aria-hidden="true" className={cx("absolute top-5 h-[52px] w-[3px] -translate-x-px bg-current", tone)} style={{ left: pct(fx) }} />
+      <span aria-hidden="true" className={cx("absolute top-0 whitespace-nowrap font-mono text-xs leading-tight text-muted-foreground", earlierIsTarget ? "-translate-x-full pr-1.5 text-right" : "pl-1.5")} style={{ left: pct(tx) }}>
+        {words.target.toUpperCase()}
+        <br />
+        {shortDay(gap.target)}
+      </span>
+      <span aria-hidden="true" className={cx("absolute top-0 whitespace-nowrap font-mono text-xs font-semibold leading-tight", tone, earlierIsTarget ? "pl-1.5" : "-translate-x-full pr-1.5 text-right")} style={{ left: pct(fx) }}>
+        {words.forecast.toUpperCase()}
+        <br />
+        {shortDay(gap.forecast)}
+      </span>
+      <span aria-hidden="true" className={cx("absolute top-[72px] whitespace-nowrap font-mono text-xs font-semibold", tone)} style={{ left: pct((a + b) / 2), transform: "translateX(-50%)" }}>
+        {said}
+      </span>
+    </div>
+  );
+}
+
+/**
+ * The chain small: one row of bars with the gap hatched, the target in ink
+ * and today in the accent. For a row in a list; put the numbers in words
+ * beside it.
+ */
+export function ScheduleStrip({ segments, target, forecast, today, count = "working", workweek, height = 16, label = "Schedule", className }) {
+  const { segs, tgt, fc, t, gap } = readProps({ segments, target, forecast, today, count, workweek });
+  const days = [...segs.flatMap((p) => [p.s, p.e + 1]), tgt != null ? tgt + 1 : null, fc != null ? fc + 1 : null].filter((d) => d != null);
+  const frame = frameOf({ days, padBefore: 0, padAfter: 1 });
+  if (!frame || (!segs.length && tgt == null)) return <div aria-hidden="true" className={cx("w-full border-b border-border", className)} style={{ height: height + 6 }} />;
+  const { x, r0, r1 } = frame;
+  const summary = segs.map((p) => `${p.label} ${STATUS_WORDS[p.status] ?? p.status ?? "planned"}`).join(", ");
+  return (
+    <div
+      role="img"
+      aria-label={`${label}: ${summary || "no dated items"}${gap ? `; ${gapWords(gap, { ...WORDS, over: (n) => `${n} days over`, slack: (n) => `${n} days of slack` })}` : ""}`}
+      className={cx("relative w-full min-w-0 border-b border-border", className)}
+      style={{ height: height + 6 }}
+    >
+      {segs.map((p) => (
+        <span key={p.id} aria-hidden="true" className={cx("absolute top-0", STRIP[p.status] ?? STRIP.planned)} style={{ left: pct(x(p.s)), width: `calc(${x(p.e + 1) - x(p.s)}% - 2px)`, height }} />
+      ))}
+      {gap && gap.state !== "on" ? (
+        <span aria-hidden="true" className={cx("absolute top-0 border border-current bg-background/70", GAP_TEXT[gap.state])} style={{ ...HATCH_FINE, left: pct(x(gap.from)), width: `max(2px, calc(${x(gap.to + 1) - x(gap.from)}% - 1px))`, height }} />
+      ) : null}
+      {tgt != null ? <span aria-hidden="true" className="absolute -top-1 w-0.5 bg-foreground" style={{ left: `calc(${pct(x(tgt + 1))} - 1px)`, height: height + 10 }} /> : null}
+      {t != null && t >= r0 && t <= r1 ? <span aria-hidden="true" className="absolute w-0.5 bg-primary" style={{ left: `calc(${pct(x(t))} - 1px)`, top: -5, height: height + 11 }} /> : null}
+    </div>
+  );
+}

package/registry/blocks/sidebar/README.md

@@ -57,8 +57,11 @@ true) is where it starts. The icon rail shows every group unfolded.
 - `shortcut` — Cmd/Ctrl + this key toggles it; default `"b"`, `null` for none.
 - `variant` — `"inset"` draws the page as a card on the frame's ground.
   Default: the Sidebar's own `variant`, so you rarely pass it here.
-- `className` — the frame's height and edges (`min-h-dvh` in a shell).
-  Never colour.
+- `className` — the frame's edges, and its height from its parent: in a
+  shell it sits in the kit's `AppLayout contentMode="fill"` with
+  `min-h-0 flex-1` (the Example). The kit's `AppLayout` owns the
+  window's height; `min-h-dvh` or `h-dvh` here is refused by `npm run
+  check`. Never colour.
 
 ### Sidebar
 
@@ -138,6 +141,7 @@ The header button: opens the sheet on a phone, collapses to icons from
 // app/shell.jsx — the app's shell, the surfaces as the sidebar's items
 "use client";
 import { usePathname } from "next/navigation";
+import { AppLayout } from "../components/ui";
 import { Sidebar, SidebarLayout, SidebarTrigger } from "../components/blocks/sidebar";
 
 const ICONS = { inbox: "inbox", deals: "dollar", contacts: "users", reports: "chart" };
@@ -153,18 +157,24 @@ export default function Shell({ name, surfaces, children }) {
     active: s.key === activeKey,
     badge: s.built ? undefined : "planned",
   }));
+  // The outer AppLayout owns the window; the inner one (it fills its
+  // slot) is the content that scrolls, back to its top on a new route.
   return (
-    <SidebarLayout
-      storageKey={`${name}.sidebar`}
-      className="min-h-dvh"
-      sidebar={<Sidebar title={name} items={items} label={`${name} surfaces`} />}
-    >
-      <header className="flex min-h-14 items-center gap-2 border-b border-border px-2 md:hidden">
-        <SidebarTrigger />
-        <span className="font-semibold">{name}</span>
-      </header>
-      <main className="min-w-0 flex-1 p-4 sm:p-6">{children}</main>
-    </SidebarLayout>
+    <AppLayout contentMode="fill">
+      <SidebarLayout
+        storageKey={`${name}.sidebar`}
+        className="min-h-0 flex-1"
+        sidebar={<Sidebar title={name} items={items} label={`${name} surfaces`} />}
+      >
+        <header className="flex min-h-14 items-center gap-2 border-b border-border px-2 md:hidden">
+          <SidebarTrigger />
+          <span className="font-semibold">{name}</span>
+        </header>
+        <AppLayout contentClassName="p-4 sm:p-6" scrollKey={pathname}>
+          {children}
+        </AppLayout>
+      </SidebarLayout>
+    </AppLayout>
   );
 }
 ```

package/registry/blocks/sketch-canvas/README.md

@@ -130,8 +130,11 @@ A sketch is plain JSON. Store it as it comes out of `onChange` / `onSave`
 - `onReady(handle)` — once, when the canvas has mounted.
 - `label` — the accessible name of the canvas region (default "Sketch").
 - `className` — layout: width, margin, height. The default height is
-  `h-[32rem]`; a height class of yours (`h-dvh`, `h-full`, `min-h-…`,
-  `flex-1`) replaces it. Never colour.
+  `h-[32rem]`; a height class of yours (`h-full`, `min-h-…`, `min-h-0
+  flex-1`) replaces it. A canvas that is the whole surface sits in an
+  `AppLayout contentMode="fill"` from the kit with `min-h-0 flex-1` (the
+  Example): never `h-dvh` or a `vh` height, which `npm run check`
+  refuses. Never colour.
 
 ### The handle
 
@@ -220,6 +223,7 @@ A whiteboard that saves itself:
 import { useSearchParams } from "next/navigation";
 import { useRow } from "../lib/data";
 import { updateRow } from "../lib/actions";
+import { AppLayout } from "../components/ui";
 import { SketchCanvas } from "../components/blocks/sketch-canvas";
 
 export default function Board() {
@@ -227,13 +231,15 @@ export default function Board() {
   const { row: board, loading } = useRow({ source: "boards", id });
   if (loading || !board) return null;
   return (
-    <SketchCanvas
-      key={board.id}
-      label={board.title}
-      defaultValue={board.sketch}                       // jsonb, may be null; read once per board
-      onSave={(sketch) => updateRow({ source: "boards", id: board.id, patch: { sketch } })}
-      className="h-dvh rounded-none border-0"
-    />
+    <AppLayout contentMode="fill">
+      <SketchCanvas
+        key={board.id}
+        label={board.title}
+        defaultValue={board.sketch}                       // jsonb, may be null; read once per board
+        onSave={(sketch) => updateRow({ source: "boards", id: board.id, patch: { sketch } })}
+        className="min-h-0 flex-1 rounded-none border-0"
+      />
+    </AppLayout>
   );
 }
 ```