@milesroxas/design-hub 0.0.0-stage → 0.1.0

package/shell/review/anchor.ts

@@ -0,0 +1,132 @@
+// Where a comment points: the prototype's state (URL and every dial) and an
+// element on the page, and the way back to both. The selector is a path of
+// tag:nth-of-type steps, stopping at a stable id, because prototype markup
+// rarely carries test ids and a pin must survive a reload.
+import { restoreDials, snapshotDials } from '@kit/dials';
+import type { Anchor } from '../../core/review/model';
+
+const RESTORE_KEY = 'hub-review-restore';
+const RESTORE_WAIT_MS = 3000;
+// React's useId values (:r1:, «r1») change between renders of different trees; never anchor on them.
+const STABLE_ID = /^[A-Za-z][\w-]*$/;
+
+export const isHarness = (el: Element | null) =>
+  !!el?.closest('[data-harness], .dialkit-root, .proto-picker');
+
+/** The element's own id when it is stable and unique on the page, so a path can stop there. */
+function stableId(node: Element): string | null {
+  if (!node.id || !STABLE_ID.test(node.id)) return null;
+  const id = `#${CSS.escape(node.id)}`;
+  return document.querySelectorAll(id).length === 1 ? id : null;
+}
+
+/** tag, or tag:nth-of-type(n) when siblings share the tag. */
+function step(node: Element): string {
+  const same = node.parentElement
+    ? [...node.parentElement.children].filter((c) => c.localName === node.localName)
+    : [];
+  return same.length > 1 ? `${node.localName}:nth-of-type(${same.indexOf(node) + 1})` : node.localName;
+}
+
+function selectorFor(el: Element): string | null {
+  if (isHarness(el) || el === document.body || el === document.documentElement) return null;
+  const steps: string[] = [];
+  for (let node: Element | null = el; node && node !== document.body; node = node.parentElement) {
+    const id = stableId(node);
+    if (id) return [id, ...steps].join(' > ');
+    steps.unshift(step(node));
+  }
+  return `body > ${steps.join(' > ')}`;
+}
+
+function resolveTarget(selector: string | null): Element | null {
+  if (!selector) return null;
+  try {
+    return document.querySelector(selector);
+  } catch {
+    return null;
+  }
+}
+
+export const currentUrl = () => location.pathname + location.search + location.hash;
+
+export function captureAnchor(
+  where: { prototype: string; feature: string },
+  target: Element | null,
+  point: { x: number; y: number } | null,
+): Anchor {
+  const selector = target ? selectorFor(target) : null;
+  let offset: Anchor['offset'] = null;
+  if (target && selector && point) {
+    const r = target.getBoundingClientRect();
+    const clamp = (v: number) => Math.min(1, Math.max(0, v));
+    offset = {
+      x: clamp(r.width ? (point.x - r.left) / r.width : 0.5),
+      y: clamp(r.height ? (point.y - r.top) / r.height : 0.5),
+    };
+  }
+  return {
+    ...where,
+    url: currentUrl(),
+    dials: snapshotDials(),
+    target: selector,
+    offset,
+    viewport: { width: innerWidth, height: innerHeight },
+  };
+}
+
+/** Where a pin sits now, in viewport pixels, or null when its element is not on the page. */
+export function pinPoint(anchor: Anchor): { x: number; y: number } | null {
+  const el = resolveTarget(anchor.target);
+  if (!el) return null;
+  const r = el.getBoundingClientRect();
+  if (!r.width && !r.height) return null;
+  const o = anchor.offset ?? { x: 0.5, y: 0.5 };
+  return { x: r.left + r.width * o.x, y: r.top + r.height * o.y };
+}
+
+function settleDials(dials: Anchor['dials'], then: (missing: string[]) => void) {
+  // Panels register as the prototype renders, so retry until every named one exists or time runs out.
+  const started = performance.now();
+  const tick = () => {
+    const missing = restoreDials(dials);
+    if (!missing.length || performance.now() - started > RESTORE_WAIT_MS) then(missing);
+    else requestAnimationFrame(tick);
+  };
+  tick();
+}
+
+/**
+ * Reopens a comment's state. A different path or query reloads the page
+ * (the variant picker and the shell read them on load), carrying the dials
+ * through sessionStorage; a different hash only changes the route.
+ */
+export function openAnchor(anchor: Anchor, commentId: string, done: (missing: string[]) => void): void {
+  const url = new URL(anchor.url, location.origin);
+  if (url.pathname !== location.pathname || url.search !== location.search) {
+    try {
+      sessionStorage.setItem(RESTORE_KEY, JSON.stringify({ id: commentId, dials: anchor.dials }));
+    } catch {
+      // Storage off (a private window): the page still opens at the URL, without the dials.
+    }
+    location.assign(anchor.url);
+    return;
+  }
+  if (url.hash !== location.hash) location.hash = url.hash;
+  settleDials(anchor.dials, done);
+}
+
+/** After a reload from openAnchor: the comment to focus, once its dials are set. */
+export function resumeAnchor(done: (commentId: string, missing: string[]) => void): void {
+  let pending: { id: string; dials: Anchor['dials'] } | null = null;
+  try {
+    pending = JSON.parse(sessionStorage.getItem(RESTORE_KEY) ?? 'null');
+    sessionStorage.removeItem(RESTORE_KEY);
+  } catch {
+    // Storage off, or a value this page did not write: there is nothing to resume.
+  }
+  if (pending) {
+    const { id, dials } = pending;
+    settleDials(dials, (missing) => done(id, missing));
+  }
+}

package/shell/review/client.ts

@@ -0,0 +1,165 @@
+// The review UI's one store: who is signed in, this prototype's comments and,
+// for editors, the people. Components read it with useSyncExternalStore and
+// call its actions; every call goes to /api/review (server/api.ts), and each
+// answer is merged in place, so a write never refetches the list.
+import { useSyncExternalStore } from 'react';
+import type { Anchor, Comment, Person, Role } from '../../core/review/model';
+
+export type Me = Omit<Person, 'epoch'>;
+/** off: this site has no review store, so the UI stays out of the way. */
+type Status = 'loading' | 'ready' | 'guest' | 'off';
+
+type State = {
+  status: Status;
+  me: Me | null;
+  comments: Comment[];
+  people: Me[] | null;
+  error: string | null;
+};
+
+class ApiError extends Error {
+  status: number;
+  problems: string[];
+  constructor(status: number, message: string, problems: string[] = []) {
+    super(message);
+    this.status = status;
+    this.problems = problems;
+  }
+}
+
+const API = '/api/review';
+
+async function call<T>(
+  op: string,
+  body?: Record<string, unknown>,
+  params: Record<string, string> = {},
+): Promise<T> {
+  const response = body
+    ? await fetch(API, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ op, ...body }),
+        credentials: 'same-origin',
+      })
+    : await fetch(`${API}?${new URLSearchParams({ op, ...params })}`, { credentials: 'same-origin' });
+  const json = (await response.json().catch(() => null)) as
+    | ({ error?: string; problems?: string[] } & T)
+    | null;
+  if (!json)
+    throw new ApiError(response.status, `The review API did not answer with JSON (${response.status}).`);
+  if (!response.ok)
+    throw new ApiError(response.status, json.error ?? `Request failed (${response.status}).`, json.problems);
+  return json;
+}
+
+export function createReviewStore(prototype: string) {
+  let state: State = { status: 'loading', me: null, comments: [], people: null, error: null };
+  const listeners = new Set<() => void>();
+  const set = (patch: Partial<State>) => {
+    state = { ...state, ...patch };
+    for (const l of listeners) l();
+  };
+  const merge = (c: Comment) => {
+    const at = state.comments.findIndex((x) => x.id === c.id);
+    set({
+      comments: at < 0 ? [...state.comments, c] : state.comments.map((x) => (x.id === c.id ? c : x)),
+      error: null,
+    });
+    return c;
+  };
+  const mergePerson = (p: Me) => {
+    if (state.people)
+      set({
+        people: state.people.some((x) => x.id === p.id)
+          ? state.people.map((x) => (x.id === p.id ? p : x))
+          : [...state.people, p],
+      });
+    return p;
+  };
+  // Every action reports its failure in the store, and rethrows so the caller keeps the user's input.
+  const attempt = async <T>(run: () => Promise<T>): Promise<T> => {
+    try {
+      return await run();
+    } catch (error) {
+      set({
+        error:
+          error instanceof ApiError && error.problems.length
+            ? error.problems.join('. ')
+            : String((error as Error).message),
+      });
+      throw error;
+    }
+  };
+
+  return {
+    subscribe(listener: () => void) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    get: () => state,
+
+    async load() {
+      try {
+        const { person } = await call<{ person: Me | null }>('me');
+        if (!person) return set({ status: 'guest', me: null });
+        const { comments } = await call<{ comments: Comment[] }>('comments', undefined, { prototype });
+        set({ status: 'ready', me: person, comments, error: null });
+      } catch (error) {
+        // 503 is a site without a review store; 404 is a static preview with no API at all.
+        if (error instanceof ApiError && (error.status === 503 || error.status === 404))
+          set({ status: 'off' });
+        else set({ status: 'ready', error: String((error as Error).message) });
+      }
+    },
+
+    add: (body: string, anchor: Anchor, states: string[]) =>
+      attempt(async () =>
+        merge((await call<{ comment: Comment }>('comment.add', { body, anchor, states })).comment),
+      ),
+    reply: (thread: string, body: string) =>
+      attempt(async () =>
+        merge((await call<{ comment: Comment }>('comment.reply', { prototype, thread, body })).comment),
+      ),
+    edit: (id: string, body: string) =>
+      attempt(async () =>
+        merge((await call<{ comment: Comment }>('comment.edit', { prototype, id, body })).comment),
+      ),
+    resolve: (id: string, resolved: boolean) =>
+      attempt(async () =>
+        merge((await call<{ comment: Comment }>('comment.resolve', { prototype, id, resolved })).comment),
+      ),
+    triage: (id: string, triage: { kind: string | null; state: string | null }, states: string[]) =>
+      attempt(async () =>
+        merge(
+          (await call<{ comment: Comment }>('comment.triage', { prototype, id, triage, states })).comment,
+        ),
+      ),
+    remove: (id: string) =>
+      attempt(async () => {
+        const { removed } = await call<{ removed: string[] }>('comment.remove', { prototype, id });
+        set({ comments: state.comments.filter((c) => !removed.includes(c.id)) });
+      }),
+
+    loadPeople: () => attempt(async () => set({ people: (await call<{ people: Me[] }>('people')).people })),
+    invite: (name: string, team: string, role: Role) =>
+      attempt(async () => {
+        const r = await call<{ person: Me; link: string }>('people.invite', { name, team, role });
+        mergePerson(r.person);
+        return new URL(r.link, location.origin).href;
+      }),
+    reissue: (id: string) =>
+      attempt(async () => {
+        const r = await call<{ person: Me; link: string }>('people.reissue', { id });
+        mergePerson(r.person);
+        return new URL(r.link, location.origin).href;
+      }),
+    revoke: (id: string) =>
+      attempt(async () => mergePerson((await call<{ person: Me }>('people.revoke', { id })).person)),
+    clearError: () => set({ error: null }),
+  };
+}
+
+export type ReviewStore = ReturnType<typeof createReviewStore>;
+
+export const useReviewState = (store: ReviewStore) =>
+  useSyncExternalStore(store.subscribe, store.get, store.get);

package/shell/review/mount.tsx

@@ -0,0 +1,12 @@
+// Mounts the review layer in its own root beside the prototype, so a
+// prototype that throws never takes the comments down with it, and the
+// review code loads only on prototype pages.
+import { createRoot } from 'react-dom/client';
+import { Review } from './Review';
+
+export function mountReview(props: { prototype: string; feature: string; states: string[] }) {
+  const host = document.createElement('div');
+  host.dataset.harness = 'review-root';
+  document.body.append(host);
+  createRoot(host).render(<Review {...props} />);
+}

package/shell/review/review.css

@@ -0,0 +1,296 @@
+/* The review layer. Harness material in both themes (--harness-*), so it
+   never reads as part of the design under review. The panel and launcher sit
+   above everything but the variant picker. Pins and the picking surface sit
+   below the dials panel (DialKit's 9999), because they belong to the page. */
+
+.rv {
+  --rv-z: 2147483600;
+  --rv-z-page: 9000;
+  --rv-gap: 16px;
+  --rv-fg-strong: oklch(1 0 0);
+  --rv-fill: oklch(1 0 0 / 0.06);
+  --rv-fill-hover: oklch(1 0 0 / 0.1);
+  --rv-accent: oklch(0.92 0 0);       /* light neutral on the dark panel */
+  --rv-on-accent: oklch(0.205 0 0);
+  --rv-mark: oklch(0.55 0 0);         /* on the page: mid grey holds on light and dark */
+  --rv-pin: oklch(0.205 0 0);
+  --rv-danger: oklch(0.779 0.131 23.4);
+  font: 13px/18px var(--sys-font);
+  -webkit-font-smoothing: antialiased;
+  color: var(--harness-fg);
+}
+
+.rv button,
+.rv input,
+.rv select,
+.rv textarea { font: inherit; color: inherit; }
+
+.rv :focus-visible { outline: 2px solid var(--rv-accent); outline-offset: 2px; }
+
+.rv-sr { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }
+.rv-muted { color: var(--harness-fg-muted); }
+
+/* ---------- launcher ---------- */
+.rv-launch {
+  position: fixed;
+  right: max(var(--rv-gap), env(safe-area-inset-right));
+  bottom: max(var(--rv-gap), env(safe-area-inset-bottom));
+  z-index: var(--rv-z);
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  height: 40px;
+  padding: 0 14px;
+  border: 1px solid var(--harness-border);
+  border-radius: 999px;
+  background: var(--harness-bg);
+  box-shadow: var(--harness-shadow);
+  cursor: pointer;
+  touch-action: manipulation;
+  transition: transform var(--dur-press) var(--ease-press), background-color var(--dur-hover) var(--ease-hover);
+}
+.rv-launch:active { transform: scale(0.97); }
+.rv-count {
+  min-width: 20px;
+  height: 20px;
+  padding: 0 6px;
+  border-radius: 999px;
+  background: var(--rv-accent);
+  color: var(--rv-on-accent);
+  font-weight: 600;
+  font-variant-numeric: tabular-nums;
+  line-height: 20px;
+  text-align: center;
+}
+@media (hover: hover) and (pointer: fine) {
+  .rv-launch:hover { background: color-mix(in srgb, var(--harness-bg), white 8%); }
+}
+
+/* ---------- panel ---------- */
+.rv-panel {
+  position: fixed;
+  top: var(--rv-gap);
+  right: var(--rv-gap);
+  bottom: calc(var(--rv-gap) + 48px);
+  z-index: var(--rv-z);
+  display: flex;
+  flex-direction: column;
+  width: min(380px, calc(100vw - 2 * var(--rv-gap)));
+  border: 1px solid var(--harness-border);
+  border-radius: 12px;
+  background: var(--harness-bg);
+  box-shadow: var(--harness-shadow);
+  overflow: hidden;
+  transition: opacity var(--dur-dialog) var(--ease-out), transform var(--dur-dialog) var(--ease-out);
+}
+@starting-style { .rv-panel { opacity: 0; transform: translateX(12px); } }
+@media (prefers-reduced-motion: reduce) {
+  @starting-style { .rv-panel { transform: none; } }
+  .rv-launch:active { transform: none; }
+}
+[data-motion="reduce"] .rv-panel { transform: none; }
+
+.rv-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  padding: 10px 10px 10px 16px;
+  border-bottom: 1px solid var(--harness-border);
+}
+.rv-title { margin: 0; font-size: 14px; font-weight: 600; color: var(--rv-fg-strong); }
+.rv-tabs { display: flex; gap: 2px; padding: 2px; border-radius: 8px; background: var(--rv-fill); }
+.rv-tabs button {
+  height: 28px;
+  padding: 0 12px;
+  border: 0;
+  border-radius: 6px;
+  background: transparent;
+  cursor: pointer;
+}
+.rv-tabs [aria-selected="true"] { background: var(--rv-fill-hover); color: var(--rv-fg-strong); font-weight: 600; }
+
+.rv-icon {
+  display: grid;
+  place-items: center;
+  width: 32px;
+  height: 32px;
+  border: 0;
+  border-radius: 6px;
+  background: transparent;
+  cursor: pointer;
+}
+@media (hover: hover) and (pointer: fine) {
+  .rv-icon:hover, .rv-tabs button:hover { background: var(--rv-fill-hover); }
+}
+
+.rv-body { flex: 1; overflow-y: auto; overscroll-behavior: contain; padding: 12px 16px 16px; display: flex; flex-direction: column; gap: 12px; }
+.rv-empty { margin: 16px; color: var(--harness-fg-muted); text-wrap: pretty; }
+.rv-error { display: flex; gap: 8px; align-items: baseline; justify-content: space-between; margin: 12px 16px 0; padding: 8px 10px; border-radius: 8px; background: oklch(0.779 0.131 23.4 / 0.12); color: var(--rv-danger); }
+
+/* ---------- controls ---------- */
+.rv-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 6px;
+  height: 32px;
+  padding: 0 12px;
+  border: 1px solid var(--harness-border);
+  border-radius: 8px;
+  background: var(--rv-fill);
+  color: var(--rv-fg-strong);
+  font-weight: 500;
+  cursor: pointer;
+  transition: background-color var(--dur-hover) var(--ease-hover), transform var(--dur-press) var(--ease-press);
+}
+.rv-button:active { transform: scale(0.97); }
+.rv-button:disabled { opacity: 0.5; cursor: default; transform: none; }
+.rv-new { align-self: stretch; height: 36px; }
+.rv-link {
+  min-height: 24px;
+  padding: 0 2px;
+  border: 0;
+  background: none;
+  color: var(--rv-accent);
+  cursor: pointer;
+}
+.rv-danger { color: var(--rv-danger); }
+@media (hover: hover) and (pointer: fine) {
+  .rv-button:not(:disabled):hover { background: var(--rv-fill-hover); }
+  .rv-link:hover { text-decoration: underline; }
+}
+
+.rv-label { display: flex; flex-direction: column; gap: 6px; color: var(--harness-fg-muted); }
+.rv input,
+.rv textarea,
+.rv select {
+  width: 100%;
+  border: 1px solid var(--harness-border);
+  border-radius: 8px;
+  background: oklch(0 0 0 / 0.25);
+  color: var(--rv-fg-strong);
+}
+.rv input, .rv select { height: 32px; padding: 0 10px; }
+.rv textarea { padding: 8px 10px; resize: vertical; min-height: 72px; line-height: 18px; }
+.rv input::placeholder { color: var(--harness-fg-muted); }
+
+.rv-filter { display: flex; gap: 4px; min-width: 0; margin: 0; padding: 0; border: 0; }
+.rv-filter button {
+  height: 28px;
+  padding: 0 10px;
+  border: 1px solid transparent;
+  border-radius: 999px;
+  background: none;
+  cursor: pointer;
+}
+.rv-filter [aria-pressed="true"] { border-color: var(--harness-border); background: var(--rv-fill); color: var(--rv-fg-strong); }
+
+/* ---------- threads ---------- */
+.rv-list, .rv-replies, .rv-people { margin: 0; padding: 0; list-style: none; display: flex; flex-direction: column; }
+.rv-list { gap: 8px; }
+.rv-thread {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 12px;
+  border: 1px solid var(--harness-border);
+  border-radius: 10px;
+  background: var(--rv-fill);
+  scroll-margin: 12px;
+  transition: border-color var(--dur-hover) var(--ease-hover);
+}
+.rv-thread[data-focused] { border-color: var(--rv-accent); }
+.rv-thread[data-resolved] .rv-text { color: var(--harness-fg-muted); }
+.rv-entry header { display: flex; flex-wrap: wrap; align-items: baseline; gap: 6px; }
+.rv-entry strong { color: var(--rv-fg-strong); font-weight: 600; }
+.rv-edit { margin-left: auto; }
+.rv-no {
+  display: inline-grid;
+  place-items: center;
+  min-width: 18px;
+  height: 18px;
+  padding: 0 4px;
+  border-radius: 999px;
+  background: var(--rv-accent);
+  color: var(--rv-on-accent);
+  font-size: 11px;
+  font-weight: 700;
+  font-variant-numeric: tabular-nums;
+}
+.rv-text { margin: 4px 0 0; white-space: pre-wrap; overflow-wrap: anywhere; color: var(--harness-fg); }
+.rv-replies { gap: 10px; padding-left: 12px; border-left: 2px solid var(--harness-border); }
+.rv-tags { display: flex; flex-wrap: wrap; gap: 6px; align-items: center; }
+.rv-tag { padding: 0 8px; height: 22px; line-height: 22px; border-radius: 999px; background: var(--rv-fill-hover); color: var(--rv-fg-strong); font-size: 12px; }
+.rv-select select { height: 26px; padding: 0 6px; font-size: 12px; width: auto; }
+.rv-actions { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
+.rv-hint { margin-left: auto; font-size: 12px; }
+.rv-composer { display: flex; flex-direction: column; gap: 8px; }
+
+/* ---------- people ---------- */
+.rv-invite { display: flex; flex-direction: column; gap: 10px; padding-bottom: 12px; border-bottom: 1px solid var(--harness-border); }
+.rv-share { display: flex; flex-direction: column; gap: 8px; padding: 10px; border-radius: 8px; background: var(--rv-fill); }
+.rv-share p { margin: 0; text-wrap: pretty; }
+.rv-share-row { display: flex; gap: 6px; }
+.rv-people { gap: 2px; }
+.rv-people li { display: flex; flex-direction: column; gap: 4px; padding: 8px 0; border-bottom: 1px solid var(--harness-border); }
+.rv-people li > div:first-child { display: flex; flex-wrap: wrap; gap: 6px; align-items: baseline; }
+.rv-people strong { color: var(--rv-fg-strong); }
+.rv-people [data-revoked] { opacity: 0.55; }
+
+/* ---------- pins and picking ---------- */
+.rv-pins { position: fixed; inset: 0; z-index: var(--rv-z-page); pointer-events: none; }
+.rv-pin {
+  position: absolute;
+  top: 0;
+  left: 0;
+  display: grid;
+  place-items: center;
+  width: 24px;
+  height: 24px;
+  margin: -24px 0 0 0;
+  border: 2px solid oklch(1 0 0);
+  border-radius: 12px 12px 12px 2px;
+  background: var(--rv-pin);
+  color: oklch(1 0 0);
+  font: 700 11px/1 var(--sys-font);
+  font-variant-numeric: tabular-nums;
+  box-shadow: 0 2px 8px oklch(0 0 0 / 0.35);
+  pointer-events: auto;
+  cursor: pointer;
+}
+.rv-pin[hidden] { display: none; }
+.rv-pin[data-new] { background: oklch(1 0 0); color: var(--rv-pin); pointer-events: none; }
+
+.rv-pick { position: fixed; inset: 0; z-index: calc(var(--rv-z-page) + 1); cursor: crosshair; }
+.rv-pick-box {
+  position: fixed;
+  top: 0;
+  left: 0;
+  z-index: calc(var(--rv-z-page) + 2);
+  pointer-events: none;
+  border: 2px solid var(--rv-mark);
+  border-radius: 4px;
+  background: oklch(0.55 0 0 / 0.12);
+}
+.rv-pick-bar {
+  position: fixed;
+  left: 50%;
+  bottom: max(var(--rv-gap), env(safe-area-inset-bottom));
+  z-index: var(--rv-z);
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 6px 6px 6px 16px;
+  transform: translateX(-50%);
+  border: 1px solid var(--harness-border);
+  border-radius: 999px;
+  background: var(--harness-bg);
+  box-shadow: var(--harness-shadow);
+  white-space: nowrap;
+}
+
+@media (max-width: 520px) {
+  .rv-panel { top: auto; left: var(--rv-gap); height: min(70vh, 560px); }
+  .rv-pick-bar { white-space: normal; left: var(--rv-gap); right: var(--rv-gap); transform: none; border-radius: 12px; }
+}