@digithings-ai/ui 0.0.0-stage → 0.1.0

package/src/components/repo-activity/heatmap.ts

@@ -0,0 +1,123 @@
+import type { RepoPullItem } from "./types";
+
+/**
+ * One UTC day of contribution history. `count` is the total; the three source
+ * fields are the split behind it, present only when the caller bucketed them
+ * (`bucketContributions`). The heat cell's `title` reads the split so hovering a
+ * square says where the day's work came from, not just how much there was.
+ */
+export type HeatDay = {
+  date: string;
+  count: number;
+  pulls?: number;
+  commits?: number;
+  issues?: number;
+};
+
+const DAY_MS = 86_400_000;
+
+/** Stamp → UTC calendar day (`2026-08-21T00:30:00+02:00` → `2026-08-20`); "" when absent. */
+function dayOf(stamp: string | null | undefined): string {
+  if (!stamp) return "";
+  const ms = Date.parse(stamp);
+  return Number.isNaN(ms) ? "" : isoOf(ms);
+}
+
+function toUtcMidnight(d: Date): number {
+  return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());
+}
+
+function isoOf(ms: number): string {
+  return new Date(ms).toISOString().slice(0, 10);
+}
+
+/**
+ * Bucket merged-PR merge dates into consecutive UTC days, oldest → newest.
+ * `weeks * 7` cells ending at `end` (default today). Pulls outside the window
+ * or without a date are ignored. Pure — safe for SSR and tests.
+ */
+export function bucketDaily(
+  pulls: RepoPullItem[],
+  weeks = 16,
+  end: Date = new Date(),
+): HeatDay[] {
+  const safeWeeks = Math.max(1, Math.floor(weeks));
+  const endMs = toUtcMidnight(end);
+  const total = safeWeeks * 7;
+  const startMs = endMs - (total - 1) * DAY_MS;
+  const counts = new Map<string, number>();
+  for (const p of pulls) {
+    const day = dayOf(p.mergedAt);
+    if (!day) continue;
+    const ms = Date.parse(`${day}T00:00:00Z`);
+    if (Number.isNaN(ms) || ms < startMs || ms > endMs) continue;
+    counts.set(day, (counts.get(day) ?? 0) + 1);
+  }
+  const days: HeatDay[] = [];
+  for (let i = 0; i < total; i++) {
+    const date = isoOf(startMs + i * DAY_MS);
+    days.push({ date, count: counts.get(date) ?? 0 });
+  }
+  return days;
+}
+
+/**
+ * Bucket repo-level contributions (GitHub profile-graph style) into
+ * consecutive UTC days, oldest → newest. Sums merged PRs + commits +
+ * closed issues per day so the heat tracks contributions, not merges alone.
+ * Each source is an ISO timestamp (or null); undated or out-of-window
+ * entries are ignored. Pure — safe for SSR and tests.
+ */
+export function bucketContributions(
+  pulls: RepoPullItem[],
+  commits: Array<string | null | undefined> = [],
+  closedIssues: Array<string | null | undefined> = [],
+  weeks = 53,
+  end: Date = new Date(),
+): HeatDay[] {
+  const safeWeeks = Math.max(1, Math.floor(weeks));
+  const endMs = toUtcMidnight(end);
+  const total = safeWeeks * 7;
+  const startMs = endMs - (total - 1) * DAY_MS;
+  const counts = new Map<string, number>();
+  const split = {
+    pulls: new Map<string, number>(),
+    commits: new Map<string, number>(),
+    issues: new Map<string, number>(),
+  };
+  const bump = (bucket: Map<string, number>, day: string) =>
+    bucket.set(day, (bucket.get(day) ?? 0) + 1);
+  const add = (bucket: Map<string, number>, stamp: string | null | undefined) => {
+    const day = dayOf(stamp);
+    if (!day) return;
+    const ms = Date.parse(`${day}T00:00:00Z`);
+    if (Number.isNaN(ms) || ms < startMs || ms > endMs) return;
+    counts.set(day, (counts.get(day) ?? 0) + 1);
+    bump(bucket, day);
+  };
+  for (const p of pulls) add(split.pulls, p.mergedAt);
+  for (const c of commits) add(split.commits, c);
+  for (const i of closedIssues) add(split.issues, i);
+  const days: HeatDay[] = [];
+  for (let i = 0; i < total; i++) {
+    const date = isoOf(startMs + i * DAY_MS);
+    days.push({
+      date,
+      count: counts.get(date) ?? 0,
+      pulls: split.pulls.get(date) ?? 0,
+      commits: split.commits.get(date) ?? 0,
+      issues: split.issues.get(date) ?? 0,
+    });
+  }
+  return days;
+}
+
+/**
+ * Accent step for a cell: 0 when empty, otherwise 1–4. Small maxima map
+ * 1:1; larger ones use quartiles so a single busy day cannot flatten the rest.
+ */
+export function levelFor(count: number, max: number): 0 | 1 | 2 | 3 | 4 {
+  if (count <= 0) return 0;
+  if (max <= 4) return Math.min(4, count) as 1 | 2 | 3 | 4;
+  return Math.min(4, Math.max(1, Math.ceil((count / max) * 4))) as 1 | 2 | 3 | 4;
+}

package/src/components/repo-activity/index.ts

@@ -0,0 +1,28 @@
+export {
+  RepoActivity,
+  type RepoActivityProps,
+  type RepoContributor,
+  type RepoModuleRelease,
+} from "./RepoActivity";
+export { RepoHeatmap, type RepoHeatmapProps } from "./RepoHeatmap";
+export { bucketContributions, bucketDaily, levelFor, type HeatDay } from "./heatmap";
+export { fetchRepoActivityLive, type FetchRepoActivityLiveOptions } from "./fetch";
+export {
+  REPO_ACTIVITY_DEMO,
+  REPO_ACTIVITY_DEMO_CLONE,
+  REPO_ACTIVITY_DEMO_CONTRIBUTING,
+  REPO_ACTIVITY_DEMO_URL,
+} from "./demo";
+export {
+  cloneParts,
+  DEFAULT_LIVE_TIMEOUT_MS,
+  grouped,
+  isoDay,
+  type RepoActivityLiveConfig,
+  type RepoActivitySnapshot,
+  type RepoFeature,
+  type RepoIssueItem,
+  type RepoModuleActivity,
+  type RepoPullItem,
+  type RepoRelease,
+} from "./types";

package/src/components/repo-activity/types.ts

@@ -0,0 +1,99 @@
+/**
+ * Snapshot-first repository activity — the shared data contract for compact
+ * and detailed views. Velocity figures are windowed; backlog figures are not.
+ * Stars, forks and watchers are deliberately absent.
+ */
+
+import type { HeatDay } from "./heatmap";
+
+export type RepoRelease = {
+  tag: string;
+  name: string | null;
+  publishedAt: string;
+  url: string;
+};
+
+export type RepoPullItem = {
+  number: number;
+  title: string;
+  url: string;
+  /** Merge time when known; closed_at is an acceptable proxy from Search. */
+  mergedAt: string | null;
+};
+
+export type RepoIssueItem = {
+  number: number;
+  title: string;
+  url: string;
+  updatedAt: string | null;
+};
+
+export type RepoFeature = {
+  scope: string | null;
+  summary: string;
+  pr: number;
+  date: string | null;
+};
+
+export type RepoModuleActivity = {
+  path: string;
+  lastCommit: string | null;
+  files: number;
+  lines: number;
+};
+
+/**
+ * One snapshot object both variants render. `commits` / `pullsMerged` /
+ * `issuesClosed` cover `windowDays` on `branch`. `pullsOpen` / `issuesOpen`
+ * are the current backlog (unwindowed). `modules` and `features` are optional
+ * extras for hosts that already generate them; the views do not require them.
+ */
+export type RepoActivitySnapshot = {
+  generatedAt: string;
+  windowDays: number;
+  branch: string;
+  commits: number;
+  pullsMerged: number;
+  issuesClosed: number;
+  pullsOpen: number;
+  issuesOpen: number;
+  latestRelease: RepoRelease | null;
+  mergedPulls: RepoPullItem[];
+  openIssues: RepoIssueItem[];
+  /** Pre-bucketed per-day contributions for the heatmap (oldest → newest).
+   *  Emitted by scripts/fetch_repo_activity.py; absent in older snapshots. */
+  dailyContributions?: HeatDay[];
+  features?: RepoFeature[];
+  modules?: Record<string, RepoModuleActivity | undefined>;
+};
+
+/** Live GitHub refresh — all-or-nothing; the component keeps the snapshot on any failure. */
+export type RepoActivityLiveConfig = {
+  owner: string;
+  repo: string;
+  branch?: string;
+  windowDays?: number;
+  timeoutMs?: number;
+};
+
+export const DEFAULT_LIVE_TIMEOUT_MS = 8_000;
+
+/** `2026-08-06T12:34:56Z` → `2026-08-06`; empty string when absent. */
+export function isoDay(stamp: string | null | undefined): string {
+  return stamp ? stamp.slice(0, 10) : "";
+}
+
+/** Thousands-separated, locale-stable so SSR and the browser cannot drift. */
+export function grouped(n: number): string {
+  return n.toLocaleString("en-US");
+}
+
+/**
+ * Split a clone command at its last slash so a `<wbr/>` can sit after the org.
+ * Rejoining the halves must equal the copied payload.
+ */
+export function cloneParts(command: string): [string, string] {
+  const cut = command.lastIndexOf("/") + 1;
+  if (cut <= 0) return [command, ""];
+  return [command.slice(0, cut), command.slice(cut)];
+}

package/src/components/stages/NumberedStages.tsx

@@ -0,0 +1,116 @@
+"use client";
+import { m, useMotionSafe, EASE } from "../../motion/primitives";
+
+/**
+ * NumberedStages — the sequential-stage grammar promoted from the design
+ * reference (layout-patterns/numbered-stages): a numbered spine where each
+ * step is one move in the flow — big mono index badge, an optional mono
+ * micro-caps tag, a serif title, one sentence of mechanism. A hairline spine
+ * (`.ns-stage::before`, styles/stages.css) runs through the badge column and
+ * stops at the last stage; each stage may scope its own module livery via
+ * `livery` (`accent-<module>` — declared in @digithings-ai/design/tokens.css),
+ * which re-tints the badge's two-color color-mix and the tag/index text.
+ *
+ * Scroll cadence (#1450): stages fill the pipeline one at a time — each row
+ * rises in on its own whileInView with an index-staggered delay, so on a
+ * normal scroll the spine reads 01 → 02 → 03 → 04 in order. `animated={false}`
+ * opts a consumer out; reduced motion (useMotionSafe) and no-JS
+ * (html.no-js [data-motion]) render every stage visible with no animation.
+ *
+ * Alignment: the badge pill is 2rem tall; an untagged title's first line is
+ * flex-centered against that height so pill and title read as one row. With a
+ * `tag`, the tag takes the pill-aligned slot and the title stacks under it.
+ *
+ * Client component (Motion m.li under the app's MotionProvider). Wiring (in
+ * the consuming app):
+ *   globals.css   @import "@digithings-ai/ui/styles/stages.css";
+ *                 @source "<path-to>/packages/ui/src/components/stages";
+ */
+export type NumberedStage = {
+  /** Big mono index rendered in the spine badge — "1.0", "01", "a" … */
+  num: string;
+  /** Serif stage title. */
+  title: string;
+  /** One sentence of mechanism under the title. */
+  mech: string;
+  /** Optional mono micro-caps tag above the title (module name, phase …). */
+  tag?: string;
+  /** Optional module livery scope — suffix of an `accent-<module>` class. */
+  livery?: string;
+};
+
+export function NumberedStages({
+  stages,
+  className,
+  animated = true,
+}: {
+  stages: NumberedStage[];
+  className?: string;
+  /** Sequential scroll fill (default). Pass false for a static spine. */
+  animated?: boolean;
+}) {
+  const safe = useMotionSafe();
+  const fill = animated && safe;
+
+  return (
+    <ol className={["grid list-none gap-0 p-0", className].filter(Boolean).join(" ")}>
+      {stages.map((s, i) => {
+        // Utilities live in clean string literals on purpose: a template hole
+        // butted against a candidate (`pb-[…]${`) hides it from Tailwind's
+        // scanner, so the utility is silently never generated — the original
+        // pb-[1.8rem] shipped un-compiled and the stages rendered with no
+        // inter-stage padding at all (#1450 round 3). 2.8rem is the ruled
+        // breathing room between a stage's blurb and the next stage's title;
+        // the spine ::before spans the padded box (styles/stages.css), so the
+        // connector stays continuous, and :last-child zeroes the trailing pad.
+        const liClass = [
+          "ns-stage relative grid grid-cols-[3.4rem_1fr] gap-[1.1rem] pb-[2.8rem]",
+          s.livery ? `accent-${s.livery}` : "",
+        ]
+          .filter(Boolean)
+          .join(" ");
+        const content = (
+          <>
+            <span className="ns-node" aria-hidden="true">
+              {s.num}
+            </span>
+            <div className={s.tag ? "pt-[0.4rem]" : undefined}>
+              {s.tag ? (
+                <p className="font-mono text-[0.6rem] uppercase tracking-[0.12em] text-accent">
+                  {s.tag}
+                </p>
+              ) : null}
+              <h3
+                className={`${
+                  s.tag ? "mt-[0.25rem]" : "flex min-h-[2rem] items-center"
+                } font-display font-normal text-[clamp(1.2rem,2.4vw,1.5rem)] leading-[1.25] tracking-[-0.013em] text-ink`}
+              >
+                {s.title}
+              </h3>
+              <p className="mt-[0.35rem] max-w-[52ch] text-[0.9rem] leading-[1.55] text-ink-soft">
+                {s.mech}
+              </p>
+            </div>
+          </>
+        );
+        return fill ? (
+          <m.li
+            key={s.num}
+            className={liClass}
+            data-motion=""
+            initial={{ opacity: 0, y: 14 }}
+            whileInView={{ opacity: 1, y: 0 }}
+            viewport={{ once: true, margin: "0px 0px -12% 0px" }}
+            transition={{ duration: 0.55, ease: EASE, delay: i * 0.28 }}
+          >
+            {content}
+          </m.li>
+        ) : (
+          <li key={s.num} className={liClass}>
+            {content}
+          </li>
+        );
+      })}
+    </ol>
+  );
+}

package/src/components/symbols/marks.tsx

@@ -0,0 +1,116 @@
+import type { ReactNode } from "react";
+
+/**
+ * Brand marks — promoted from the design reference (symbols/marks) as pure,
+ * props-driven components. The four-stroke digiquant signature was previously
+ * copied verbatim in four places (dashboard-mark.tsx + DashboardLoader.tsx,
+ * digiquant-web's DigiquantMark, the reference specimen) — this file is the
+ * canonical copy. Everything draws in currentColor so a mark inherits the
+ * ink/accent of its livery scope. No CSS ships with this family: the marks
+ * are pure SVG/text; stroke-draw loader animations stay in the consuming
+ * app's CSS, targeted through `strokeClassPrefix`. Default hooks are
+ * `dq-mark` / `dq-stroke`.
+ */
+
+export type DigiquantMarkProps = {
+  size?: number;
+  className?: string;
+  /** Accessible name (renders a <title> + role="img"); omitted → decorative. */
+  title?: string;
+  /**
+   * Per-path class hook for stroke-draw animations: each stroke gets
+   * `${prefix} ${prefix}-N` (N = 1..4, outer arc last). The dashboard
+   * loader keys its draw keyframes off "research-loader-stroke";
+   * the reference / landing hover replay uses the default
+   * "dq-stroke".
+   */
+  strokeClassPrefix?: string;
+};
+
+export function DigiquantMark({
+  size = 22,
+  className,
+  title,
+  strokeClassPrefix = "dq-stroke",
+}: DigiquantMarkProps) {
+  const strokeClass = (n: number) => `${strokeClassPrefix} ${strokeClassPrefix}-${n}`;
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 48 48"
+      fill="none"
+      role={title ? "img" : undefined}
+      aria-hidden={title ? undefined : "true"}
+      focusable="false"
+      className={["dq-mark", className].filter(Boolean).join(" ")}
+    >
+      {title ? <title>{title}</title> : null}
+      <path
+        className={strokeClass(1)}
+        stroke="currentColor"
+        strokeWidth="2.2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        d="M4.2774,32.5293a11.6485,11.6485,0,0,1,23.2219,1.32h0c0,3.2166.0022,11.6479.0022,11.6479"
+      />
+      <path
+        className={strokeClass(2)}
+        stroke="currentColor"
+        strokeWidth="2.2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        d="M3.3047,29.8574q-.0277-.4816-.0279-.97a16.61,16.61,0,1,1,33.2209,0v0c0,4.5869.0031,16.6095.0031,16.6095"
+      />
+      <circle
+        className={strokeClass(3)}
+        stroke="currentColor"
+        strokeWidth="2"
+        cx="16.5007"
+        cy="33.4992"
+        r="5.0328"
+      />
+      <path
+        className={strokeClass(4)}
+        stroke="currentColor"
+        strokeWidth="2.2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        d="M45.5,24A21.5,21.5,0,1,0,24,45.5H45.5Z"
+      />
+    </svg>
+  );
+}
+
+export type WordmarkProps = {
+  /**
+   * Suffix after the prefix — "things", "quant". Wears var(--accent), so a
+   * livery scope (e.g. `.accent-digiquant`) dresses it automatically.
+   */
+  suffix: ReactNode;
+  /** Lockup prefix, in ink (default "digi"). */
+  prefix?: ReactNode;
+  className?: string;
+};
+
+/**
+ * Wordmark — the text lockup grammar shared with the footer colophon:
+ * `digi` in ink, the suffix wearing var(--accent). Mono, weight 500.
+ * Carries token-backed utilities — consumers need an
+ * `@source "<path-to>/packages/ui/src/components/symbols"` line.
+ */
+export function Wordmark({ suffix, prefix = "digi", className }: WordmarkProps) {
+  return (
+    <span
+      className={[
+        "font-mono text-[1.25rem] font-medium tracking-[-0.01em] text-ink",
+        className,
+      ]
+        .filter(Boolean)
+        .join(" ")}
+    >
+      {prefix}
+      <em className="not-italic text-accent">{suffix}</em>
+    </span>
+  );
+}

package/src/components/symbols/terminal-lockup.tsx

@@ -0,0 +1,136 @@
+/**
+ * Animated brand lockup — `digi` and a cursor that types each module in turn.
+ *
+ * The identity as a live terminal line: `digi` holds, the cursor blinks, then a
+ * module suffix types in character by character, holds long enough to read,
+ * deletes, and the next one follows. Pure CSS, no JavaScript and no state — so it
+ * renders identically on the server and degrades correctly.
+ *
+ * Suffixes default to the real module registry (`data/modules`) with the shared
+ * `digi` prefix stripped, so the animation cannot drift out of sync with the
+ * stack the way a hardcoded list would.
+ *
+ * Two implementation details that are load-bearing:
+ *
+ * - **Keyframe offsets must be unique and strictly increasing, and every segment
+ *   needs its own `animation-timing-function`.** Browsers merge duplicate-offset
+ *   keyframes and silently drop the timing function — which turns the
+ *   character-by-character type-in into a smooth width slide with no error
+ *   anywhere. That is why the offsets are computed rather than hand-written.
+ * - **Typing is priced per character, not per slot.** A fixed slot makes a
+ *   3-letter module type at 2x the speed of a 6-letter one and the rhythm limps.
+ *   Constant cadence means unequal slots, so the shared cycle is built from
+ *   cumulative times.
+ *
+ * The keyframes are emitted as a scoped `<style>` rather than shipped in a family
+ * sheet because they are derived from the word list: a static sheet would have to
+ * hardcode a module count, and would go stale the moment the registry changes.
+ *
+ * `prefers-reduced-motion` renders the final state — `digi` + the first module,
+ * cursor still — per the canon's one-motion-moment rule.
+ */
+"use client";
+
+import { useId } from "react";
+import { modules } from "../../data/modules";
+
+/** Module suffixes, `digi` stripped: ["graph", "quant", …]. */
+export const MODULE_SUFFIXES: string[] = modules
+  .map((m) => m.id)
+  .filter((id) => id.startsWith("digi"))
+  .map((id) => id.slice(4));
+
+/** Seconds. Typing is per character so every module types at one cadence. */
+const TYPE_S = 0.14;
+const ERASE_S = 0.09;
+const HOLD_S = 2.4;
+const REST_S = 1.2;
+
+type Phase = { word: string; type: number; hold: number; erase: number; rest: number };
+
+function plan(words: string[]): { phases: Phase[]; total: number } {
+  let t = 0;
+  const phases: Phase[] = [];
+  for (const word of words) {
+    const n = word.length;
+    const type = t;
+    const hold = type + n * TYPE_S;
+    const erase = hold + HOLD_S;
+    const rest = erase + n * ERASE_S;
+    phases.push({ word, type, hold, erase, rest });
+    t = rest + REST_S;
+  }
+  return { phases, total: t };
+}
+
+function keyframes(scope: string, words: string[]): string {
+  const { phases, total } = plan(words);
+  const pct = (s: number) => ((s / total) * 100).toFixed(4);
+  return phases
+    .map(({ word, type, hold, erase, rest }, i) => {
+      const n = word.length;
+      const rows: string[] = [];
+      if (type > 0) {
+        rows.push(`0%{width:0;animation-timing-function:linear}`);
+        rows.push(`${pct(type)}%{width:0;animation-timing-function:steps(${n},end)}`);
+      } else {
+        rows.push(`0%{width:0;animation-timing-function:steps(${n},end)}`);
+      }
+      rows.push(`${pct(hold)}%{width:${n}ch;animation-timing-function:linear}`);
+      rows.push(`${pct(erase)}%{width:${n}ch;animation-timing-function:steps(${n},end)}`);
+      rows.push(`${pct(rest)}%{width:0;animation-timing-function:linear}`);
+      if (rest < total) rows.push(`100%{width:0}`);
+      return `@keyframes ${scope}-t${i}{${rows.join("")}}`;
+    })
+    .join("");
+}
+
+export interface AnimatedLockupProps {
+  /** Suffixes to cycle. Defaults to the module registry. */
+  suffixes?: string[];
+  /** Text before the typed suffix. */
+  prefix?: string;
+  className?: string;
+  /** Accessible name. The typed suffixes are decorative — one name for the whole. */
+  title?: string;
+}
+
+export function AnimatedLockup({
+  suffixes = MODULE_SUFFIXES,
+  prefix = "digi",
+  className,
+  title = "digithings",
+}: AnimatedLockupProps) {
+  // useId keeps the keyframe names unique if the lockup is ever mounted twice.
+  const scope = `dtl${useId().replace(/[^a-zA-Z0-9]/g, "")}`;
+  const { total } = plan(suffixes);
+  const css = [
+    `.${scope}{font-family:var(--font-mono);font-weight:400;line-height:1.05;`,
+    `letter-spacing:0;white-space:nowrap;display:inline-block;user-select:none}`,
+    `.${scope} i{font-style:normal;display:inline-block;overflow:hidden;width:0;`,
+    `vertical-align:bottom;animation-duration:${total.toFixed(2)}s;`,
+    `animation-iteration-count:infinite;animation-fill-mode:both}`,
+    suffixes.map((_, i) => `.${scope} i:nth-child(${i + 1}){animation-name:${scope}-t${i}}`).join(""),
+    `.${scope} u{display:inline-block;width:.6em;height:.71em;background:currentColor;`,
+    `text-decoration:none;animation:${scope}-blink 1.05s steps(1) infinite}`,
+    `@keyframes ${scope}-blink{50%{opacity:0}}`,
+    keyframes(scope, suffixes),
+    `@media (prefers-reduced-motion:reduce){`,
+    `.${scope} u{animation:none}`,
+    `.${scope} i{animation:none;width:0}`,
+    `.${scope} i:nth-child(1){width:${suffixes[0]?.length ?? 0}ch}}`,
+  ].join("");
+
+  return (
+    <span className={[scope, className].filter(Boolean).join(" ")} role="img" aria-label={title}>
+      <style>{css}</style>
+      {prefix}
+      <span aria-hidden="true">
+        {suffixes.map((w) => (
+          <i key={w}>{w}</i>
+        ))}
+      </span>
+      <u aria-hidden="true" />
+    </span>
+  );
+}