@milesroxas/design-hub 0.0.0-stage → 0.1.1

package/shell/Guide.tsx

@@ -0,0 +1,160 @@
+import { Icon } from '@kit/Icon';
+import '@kit/ui/ui.css';
+import { Suspense, use, useEffect, useState } from 'react';
+import { featureTitle, guideHref } from '../core/feature';
+import type { Doc } from './doc';
+import { Boundary, Notice } from './Notice';
+import { featureEntry, guides } from './registry';
+import './guide.css';
+
+const fmtDate = (iso: string) =>
+  iso
+    ? new Date(`${iso}T12:00:00`).toLocaleDateString('en-GB', {
+        day: 'numeric',
+        month: 'long',
+        year: 'numeric',
+      })
+    : '';
+
+// One promise per guide, so a suspended render retries against the same load;
+// a failed load leaves the cache, so the next render asks again.
+const docs = new Map<string, Promise<Doc>>();
+function docOf(feature: string) {
+  let doc = docs.get(feature);
+  if (!doc) {
+    doc = guides.get(feature)!();
+    docs.set(feature, doc);
+    doc.catch(() => docs.delete(feature));
+  }
+  return doc;
+}
+
+// /guide/<feature>/ renders docs/sprints/<feature>/guide.md. /guide/ alone
+// opens the only guide when there is one, and lists them otherwise.
+export default function Guide({ feature }: { feature?: string }) {
+  const key = feature ?? (guides.size === 1 ? guides.keys().next().value : undefined);
+  if (!key || !guides.has(key))
+    return feature ? (
+      <Notice title={`No walkthrough for “${feature}”`} body="Add one at docs/sprints/<feature>/guide.md." />
+    ) : (
+      <GuideList />
+    );
+  return (
+    <Boundary name={`The ${featureTitle(key)} walkthrough`}>
+      <Suspense fallback={null}>
+        <GuidePage feature={key} />
+      </Suspense>
+    </Boundary>
+  );
+}
+
+function GuideList() {
+  return (
+    <main className="shell-notice">
+      <h1>Walkthroughs</h1>
+      {guides.size ? (
+        <ul>
+          {[...guides.keys()].map((f) => (
+            <li key={f}>
+              <a href={guideHref(f)}>{featureTitle(f)}</a>
+            </li>
+          ))}
+        </ul>
+      ) : (
+        <p>No walkthrough yet. Start one with pnpm new:guide &lt;feature&gt;.</p>
+      )}
+      <a href="/">All prototypes</a>
+    </main>
+  );
+}
+
+// The Markdown is the source; this page is how a reviewer without the repo reads it.
+function GuidePage({ feature }: { feature: string }) {
+  const { html, meta, title, toc } = use(docOf(feature));
+  const prototype = featureEntry(feature);
+  const [current, setCurrent] = useState<string | null>(null);
+
+  useEffect(() => {
+    document.title = `${title} · Prototypes`;
+    if (location.hash)
+      document.getElementById(location.hash.slice(1))?.scrollIntoView({ behavior: 'instant' });
+  }, [title]);
+
+  // The contents follow the reader: the last heading above the top third of
+  // the viewport is the current one.
+  useEffect(() => {
+    const heads = Array.from(document.querySelectorAll<HTMLElement>('.doc-body :is(h2, h3)'));
+    if (!heads.length) return;
+    let frame = 0;
+    const update = () => {
+      frame = 0;
+      const line = innerHeight / 3;
+      let found: string | null = null;
+      for (const h of heads) {
+        if (h.getBoundingClientRect().top <= line) found = h.id;
+        else break;
+      }
+      setCurrent(found);
+    };
+    const onScroll = () => {
+      if (!frame) frame = requestAnimationFrame(update);
+    };
+    update();
+    addEventListener('scroll', onScroll, { passive: true });
+    addEventListener('resize', onScroll);
+    return () => {
+      removeEventListener('scroll', onScroll);
+      removeEventListener('resize', onScroll);
+      if (frame) cancelAnimationFrame(frame);
+    };
+  }, []);
+
+  return (
+    <main className="doc">
+      <div className="doc-layout">
+        <header className="doc-head">
+          <a className="doc-back" href="/">
+            <Icon name="arrow-left" size={16} />
+            Prototypes
+          </a>
+          <div className="doc-head-row">
+            <div className="doc-head-text">
+              <p className="doc-kicker">
+                {featureTitle(feature)} · Walkthrough · <time dateTime={meta.date}>{fmtDate(meta.date)}</time>
+              </p>
+              <h1 className="doc-title">{title}</h1>
+            </div>
+            {prototype ? (
+              <a
+                className="btn btn-primary btn-md"
+                href={`/${prototype.slug}/`}
+                target="_blank"
+                rel="noreferrer"
+              >
+                <span className="btn-label">Open the prototype</span>
+                <Icon name="arrow-up-right" size={16} />
+              </a>
+            ) : null}
+          </div>
+        </header>
+        <nav className="doc-toc" aria-label="Contents">
+          <p className="doc-toc-label">Contents</p>
+          <ol>
+            {toc.map((h) => (
+              <li key={h.id} className={h.depth === 3 ? 'is-sub' : undefined}>
+                <a href={`#${h.id}`} aria-current={current === h.id ? 'location' : undefined}>
+                  {h.text}
+                </a>
+              </li>
+            ))}
+          </ol>
+        </nav>
+        {/* biome-ignore lint/security/noDangerouslySetInnerHtml: compiled at build time from a Markdown file in this repo */}
+        <article className="doc-body" dangerouslySetInnerHTML={{ __html: html }} />
+        <footer className="doc-foot">
+          <a href="/">All prototypes</a>
+        </footer>
+      </div>
+    </main>
+  );
+}

package/shell/Index.tsx

@@ -0,0 +1,301 @@
+import { fmtDate, plural } from '@kit/format';
+import { useStoredState } from '@kit/hooks';
+import { Icon } from '@kit/Icon';
+import {
+  type CSSProperties,
+  type KeyboardEvent,
+  type MouseEvent,
+  useDeferredValue,
+  useEffect,
+  useRef,
+  useState,
+} from 'react';
+import { featureTitle, guideHref } from '../core/feature';
+import { type Entry, entries, guides } from './registry';
+import './shell.css';
+
+// One group per feature: its one primary prototype, its alternates on a rail
+// under it, then its internal explorations folded away. A second sprint
+// becomes an alternate, since a feature has one primary. Prototypes with no
+// feature fold into their own group. Archived ones leave their group.
+type Group = {
+  id: string;
+  title: string;
+  guide?: string;
+  items: Entry[];
+  alternates: Entry[];
+  explorations: Entry[];
+};
+const groupsOf = (list: Entry[]): Group[] => {
+  const live = list.filter((e) => e.status !== 'archived');
+  const features = [...new Set(live.map((e) => e.feature).filter(Boolean))];
+  return [
+    ...features.map((f) => {
+      const own = live.filter((e) => e.feature === f);
+      const primary = own.find((e) => e.kind === 'sprint');
+      const alternates = own.filter((e) => e.kind !== 'exploration' && e !== primary);
+      return {
+        id: `feature-${f}`,
+        title: featureTitle(f),
+        guide: guides.has(f) ? guideHref(f) : undefined,
+        items: primary ? [primary] : alternates,
+        alternates: primary ? alternates : [],
+        explorations: own.filter((e) => e.kind === 'exploration'),
+      };
+    }),
+    {
+      id: 'unassigned',
+      title: 'Without a feature',
+      items: [],
+      alternates: [],
+      explorations: live.filter((e) => !e.feature),
+    },
+    {
+      id: 'archived',
+      title: 'Archived',
+      items: list.filter((e) => e.status === 'archived'),
+      alternates: [],
+      explorations: [],
+    },
+  ].filter((g) => g.items.length || g.alternates.length || g.explorations.length);
+};
+
+const RISE_CAP = 8;
+const rise = (i: number) => ({ '--i': Math.min(i, RISE_CAP) }) as CSSProperties;
+
+export function Index() {
+  const [query, setQuery] = useState('');
+  const [leaving, setLeaving] = useState<string | null>(null);
+  const [opened, setOpened] = useStoredState<Record<string, boolean>>('index-explorations-open', {});
+  const [instant, setInstant] = useState(false);
+  const q = useDeferredValue(query.trim().toLowerCase());
+  const main = useRef<HTMLElement>(null);
+  const shown = entries.filter((e) => !q || `${e.title} ${e.summary} ${e.slug}`.toLowerCase().includes(q));
+  const groups = groupsOf(shown);
+  const archivedTotal = entries.filter((e) => e.status === 'archived').length;
+
+  // A back-forward cache restore brings the faded page back; undo the exit.
+  useEffect(() => {
+    const restore = (e: PageTransitionEvent) => {
+      if (e.persisted) setLeaving(null);
+    };
+    addEventListener('pageshow', restore);
+    return () => removeEventListener('pageshow', restore);
+  }, []);
+
+  // Arrows walk the rows; keyboard moves never animate.
+  const onKeyDown = (e: KeyboardEvent) => {
+    if (e.key !== 'ArrowDown' && e.key !== 'ArrowUp') return;
+    const rows = Array.from(
+      main.current?.querySelectorAll<HTMLAnchorElement>('.index-row, .index-fold:not([inert]) .index-card') ??
+        [],
+    );
+    if (!rows.length) return;
+    const at = rows.indexOf(document.activeElement as HTMLAnchorElement);
+    const next = e.key === 'ArrowDown' ? Math.min(at + 1, rows.length - 1) : Math.max(at - 1, 0);
+    rows[next]?.focus();
+    e.preventDefault();
+  };
+
+  // Pointer opens fade the page while the prototype loads. A keyboard open
+  // (detail 0) is instant, and a modified click opens elsewhere, so neither fades.
+  const onOpen = (e: MouseEvent<HTMLAnchorElement>, slug: string) => {
+    if (e.detail === 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+    setLeaving(slug);
+  };
+
+  // A keyboard toggle (detail 0) opens and closes without motion.
+  const onToggle = (e: MouseEvent<HTMLButtonElement>, id: string) => {
+    setInstant(e.detail === 0);
+    setOpened((o) => ({ ...o, [id]: !o[id] }));
+  };
+
+  const rows = (items: Entry[], from: number) =>
+    items.map((e, i) => (
+      <li key={e.slug} className="index-rise" style={rise(from + i)}>
+        <a
+          className="index-row"
+          href={`/${e.slug}/`}
+          data-kind={e.kind}
+          data-chosen={leaving === e.slug || undefined}
+          onClick={(ev) => onOpen(ev, e.slug)}
+        >
+          <span className="index-title">{e.title}</span>
+          <span className="index-summary">{e.summary}</span>
+          <EntryMeta entry={e} className="index-meta" />
+        </a>
+      </li>
+    ));
+
+  let slot = 0;
+  return (
+    <main className={leaving ? 'index is-leaving' : 'index'} ref={main} onKeyDown={onKeyDown}>
+      <header className="index-head">
+        <h1>Prototypes</h1>
+        <p className="index-voice">
+          High-fidelity sketches in code, made as we sprint on features and improve the product.
+        </p>
+      </header>
+      {entries.length > 6 ? (
+        <label className="index-filter">
+          <span className="sr-only">Filter prototypes</span>
+          <input
+            type="search"
+            placeholder="Filter"
+            autoComplete="off"
+            value={query}
+            onChange={(e) => setQuery(e.target.value)}
+          />
+        </label>
+      ) : null}
+      {entries.length === 0 ? (
+        <section className="index-empty index-rise" style={rise(0)}>
+          <h2>No prototypes yet</h2>
+          <p>
+            Write the problem and the one question in a README, then start one with{' '}
+            <code>pnpm new &lt;slug&gt;</code>.
+          </p>
+        </section>
+      ) : null}
+      {groups.map((g) => {
+        const from = slot;
+        const alt = from + 1 + g.items.length;
+        const sub = g.alternates.length ? alt + 1 + g.alternates.length : alt;
+        const open = Boolean(q || opened[g.id]);
+        slot = g.explorations.length ? sub + 1 + (open ? g.explorations.length : 0) : sub;
+        return (
+          <section key={g.id} aria-labelledby={`group-${g.id}`} className="index-group">
+            <div className="index-section index-rise" style={rise(from)}>
+              <h2 id={`group-${g.id}`}>{g.title}</h2>
+              {g.guide ? (
+                <a className="index-guide" href={g.guide}>
+                  Walkthrough
+                  <span className="sr-only"> for {g.title}</span>
+                  <Icon name="arrow-right" size={16} />
+                </a>
+              ) : null}
+            </div>
+            {g.items.length ? <ul className="index-list">{rows(g.items, from + 1)}</ul> : null}
+            {g.alternates.length ? (
+              <div className="index-alternates">
+                <h3
+                  id={`group-${g.id}-alternates`}
+                  className="index-alternates-label index-rise"
+                  style={rise(alt)}
+                >
+                  Alternates
+                </h3>
+                <ul className="index-list" aria-labelledby={`group-${g.id}-alternates`}>
+                  {rows(g.alternates, alt + 1)}
+                </ul>
+              </div>
+            ) : null}
+            {g.explorations.length ? (
+              <Explorations
+                group={g}
+                at={sub}
+                open={open}
+                instant={instant}
+                leaving={leaving}
+                onToggle={(ev) => onToggle(ev, g.id)}
+                onOpen={onOpen}
+              />
+            ) : null}
+          </section>
+        );
+      })}
+      {entries.length > 0 && shown.length === 0 ? (
+        <p className="index-none" role="status">
+          Nothing matches “{query}”.
+        </p>
+      ) : null}
+      {entries.length > 0 ? (
+        <footer className="index-foot index-rise" style={rise(slot)}>
+          <p className="tabular">
+            {plural(entries.length - archivedTotal, 'prototype')}
+            {archivedTotal ? `, ${plural(archivedTotal, 'archived')}` : ''}
+          </p>
+        </footer>
+      ) : null}
+    </main>
+  );
+}
+
+/** A group's internal explorations, folded away under a toggle until asked for or a search matches them. */
+function Explorations({
+  group,
+  at,
+  open,
+  instant,
+  leaving,
+  onToggle,
+  onOpen,
+}: {
+  group: Group;
+  at: number;
+  open: boolean;
+  instant: boolean;
+  leaving: string | null;
+  onToggle: (e: MouseEvent<HTMLButtonElement>) => void;
+  onOpen: (e: MouseEvent<HTMLAnchorElement>, slug: string) => void;
+}) {
+  const foldId = `group-${group.id}-explorations`;
+  return (
+    <>
+      <h3 id={`${foldId}-title`} className="index-subsection index-rise" style={rise(at)}>
+        <button
+          type="button"
+          className="index-fold-toggle"
+          aria-expanded={open}
+          aria-controls={foldId}
+          onClick={onToggle}
+        >
+          Internal explorations
+          <span className="index-fold-count tabular">{group.explorations.length}</span>
+          <Icon name="chevron-down" size={16} />
+        </button>
+      </h3>
+      <div
+        id={foldId}
+        className="index-fold"
+        data-open={open || undefined}
+        data-instant={instant || undefined}
+        inert={!open}
+      >
+        <ul className="index-cards" aria-labelledby={`${foldId}-title`}>
+          {group.explorations.map((e, i) => (
+            <li key={e.slug} className="index-rise" style={rise(at + 1 + i)}>
+              <a
+                className="index-card"
+                href={`/${e.slug}/`}
+                data-chosen={leaving === e.slug || undefined}
+                onClick={(ev) => onOpen(ev, e.slug)}
+              >
+                <span className="index-card-head">
+                  <span className="index-title">{e.title}</span>
+                  <Icon name="arrow-right" size={16} />
+                </span>
+                <span className="index-summary">{e.summary}</span>
+                <EntryMeta entry={e} className="index-card-meta" />
+              </a>
+            </li>
+          ))}
+        </ul>
+      </div>
+    </>
+  );
+}
+
+function EntryMeta({ entry, className }: { entry: Entry; className: string }) {
+  return (
+    <span className={className}>
+      <span>{entry.context === 'app' ? 'App shell' : 'Space'}</span>
+      <span className="index-status" data-status={entry.status}>
+        {entry.status}
+      </span>
+      <time dateTime={entry.created} className="tabular">
+        {fmtDate(entry.created)}
+      </time>
+    </span>
+  );
+}

package/shell/Notice.tsx

@@ -0,0 +1,27 @@
+import { Component, type ReactNode } from 'react';
+import './shell.css';
+
+export function Notice({ title, body, detail }: { title: string; body: string; detail?: string }) {
+  return (
+    <main className="shell-notice sys">
+      <h1>{title}</h1>
+      <p>{body}</p>
+      {detail ? <pre>{detail}</pre> : null}
+      <a href="/">All prototypes</a>
+    </main>
+  );
+}
+
+export class Boundary extends Component<{ name: string; children: ReactNode }, { error: Error | null }> {
+  state = { error: null as Error | null };
+
+  static getDerivedStateFromError(error: Error) {
+    return { error };
+  }
+
+  render() {
+    const { error } = this.state;
+    if (!error) return this.props.children;
+    return <Notice title={`${this.props.name} crashed`} body={error.message} detail={error.stack} />;
+  }
+}

package/shell/Prototype.tsx

@@ -0,0 +1,31 @@
+import { lazy, Suspense, useEffect, useMemo } from 'react';
+import { Boundary, Notice } from './Notice';
+import type { Entry } from './registry';
+
+export function Prototype({ slug, entry }: { slug: string; entry?: Entry }) {
+  const View = useMemo(() => (entry?.load ? lazy(entry.load) : null), [entry]);
+
+  useEffect(() => {
+    document.title = `${entry?.title ?? slug} · Prototypes`;
+  }, [entry, slug]);
+
+  if (!entry)
+    return (
+      <Notice
+        title={`No prototype called “${slug}”`}
+        body="Check the folder name, or start one with pnpm new."
+      />
+    );
+  if (!View)
+    return (
+      <Notice title={entry.title} body={`${slug}/index.tsx is missing. It default-exports the prototype.`} />
+    );
+
+  return (
+    <Boundary name={slug}>
+      <Suspense fallback={null}>
+        <View />
+      </Suspense>
+    </Boundary>
+  );
+}

package/shell/a11y.ts

@@ -0,0 +1,50 @@
+import axe from 'axe-core';
+
+// Dev only: axe runs once the page has been quiet for a moment and logs
+// new violations as [a11y] warnings. ?a11y=0 turns it off.
+const HARNESS = [['.proto-picker'], ['.dialkit-root'], ['[data-harness]'], ['[data-lapse-panel]']];
+
+export function watchA11y() {
+  let timer = 0;
+  let running = false;
+  let last: string | null = null;
+
+  const run = async () => {
+    if (running) return;
+    running = true;
+    try {
+      const { violations } = await axe.run(
+        { exclude: HARNESS },
+        { resultTypes: ['violations'], rules: { region: { enabled: false } } },
+      );
+      const key = violations.map((v) => `${v.id}:${v.nodes.length}`).join('|');
+      if (key && key !== last) {
+        console.groupCollapsed(`[a11y] ${violations.length} rule(s) failing`);
+        for (const v of violations) {
+          console.warn(
+            `[a11y] ${v.impact} ${v.id}: ${v.help}`,
+            v.nodes.map((n) => n.target.join(' ')),
+            v.helpUrl,
+          );
+        }
+        console.groupEnd();
+      } else if (!key && last !== '') {
+        console.info('[a11y] clean');
+      }
+      last = key;
+    } finally {
+      running = false;
+    }
+  };
+
+  const schedule = () => {
+    clearTimeout(timer);
+    // Safari has no requestIdleCallback; without the fallback the watcher throws and never runs there.
+    const idle = window.requestIdleCallback ?? ((fn: () => void) => window.setTimeout(fn, 200));
+    timer = window.setTimeout(() => idle(run, { timeout: 2000 }), 1200);
+  };
+
+  new MutationObserver(schedule).observe(document.body, { subtree: true, childList: true });
+  addEventListener('hashchange', schedule);
+  schedule();
+}

package/shell/doc.d.ts

@@ -0,0 +1,7 @@
+declare module '*.md?doc' {
+  type Doc = import('./doc').Doc;
+  export const meta: Doc['meta'];
+  export const title: Doc['title'];
+  export const toc: Doc['toc'];
+  export const html: Doc['html'];
+}

package/shell/doc.ts

@@ -0,0 +1,3 @@
+// The compiled walkthrough's shape, for the page. The compiler runs only at
+// build time, so the page imports this shape, never the compiler.
+export type { Doc } from '../core/doc';