@ghxstship/xos-ui 0.0.0-stage → 4.16.0

package/src/Layout/ScrollRegion.tsx

@@ -0,0 +1,107 @@
+import { useLayoutEffect, useRef, useState, type ReactElement } from "react";
+import { cx } from "../lib/cx.ts";
+import { type ScrollRegionProps } from "./Layout.types.ts";
+
+interface Edges {
+  /** Content is hidden past the logical start (scrolled away from it). */
+  readonly start: boolean;
+  /** Content is hidden past the logical end. */
+  readonly end: boolean;
+}
+
+const NO_EDGES: Edges = { start: false, end: false };
+
+const edgeClass = cx(
+  "pointer-events-none absolute inset-y-0 z-sticky w-(--space-48) from-bg-canvas to-transparent",
+  "print:hidden forced-colors:hidden",
+);
+
+/**
+ * Keeps wide content inside the page width: it scrolls horizontally in a labeled region that joins
+ * the tab order only while it overflows. While content is hidden past an edge, that edge fades, so a
+ * table or board cut off at the right shows that it scrolls (A59-012).
+ */
+export function ScrollRegion({
+  label,
+  children,
+  className,
+  frameClassName,
+  style,
+  ref: outer,
+}: ScrollRegionProps): ReactElement {
+  const ref = useRef<HTMLDivElement>(null);
+  const setRef = (el: HTMLDivElement | null) => {
+    ref.current = el;
+    if (typeof outer === "function") outer(el);
+    else if (outer) outer.current = el;
+  };
+  // Server rendered markup cannot measure, so the region starts in the tab order and leaves it once
+  // the first measure finds nothing to scroll. Starting out of it left wide content unreachable by
+  // keyboard until hydration (A23-015).
+  const [overflows, setOverflows] = useState(true);
+  const [edges, setEdges] = useState<Edges>(NO_EDGES);
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el) return undefined;
+    const measure = () => {
+      const room = el.scrollWidth - el.clientWidth;
+      setOverflows(room > 1);
+      // scrollLeft runs negative from the start in right-to-left, so the distance is its magnitude.
+      const at = Math.abs(el.scrollLeft);
+      const start = room > 1 && at > 1;
+      const end = room > 1 && at < room - 1;
+      setEdges((old) => (old.start === start && old.end === end ? old : { start, end }));
+    };
+    measure();
+    el.addEventListener("scroll", measure, { passive: true });
+    if (typeof ResizeObserver === "undefined") {
+      return () => el.removeEventListener("scroll", measure);
+    }
+    // Content can grow wider after the first measure (rows load, fonts swap), so watch the region's
+    // children as well as its own box, and re-observe when children change.
+    const observer = new ResizeObserver(measure);
+    const observeAll = () => {
+      observer.disconnect();
+      observer.observe(el);
+      for (const child of Array.from(el.children)) observer.observe(child);
+      measure();
+    };
+    observeAll();
+    const mutations =
+      typeof MutationObserver === "undefined" ? null : new MutationObserver(observeAll);
+    mutations?.observe(el, { childList: true });
+    return () => {
+      el.removeEventListener("scroll", measure);
+      observer.disconnect();
+      mutations?.disconnect();
+    };
+  }, []);
+  return (
+    <div className={cx("relative min-w-0 max-w-full", frameClassName)}>
+      <div
+        ref={setRef}
+        role="region"
+        aria-label={label}
+        tabIndex={overflows ? 0 : undefined}
+        style={style}
+        className={cx("relative max-w-full overflow-x-auto overscroll-x-contain", className)}
+      >
+        {children}
+      </div>
+      {edges.start ? (
+        <span
+          aria-hidden="true"
+          data-scroll-edge="start"
+          className={cx(edgeClass, "start-0 bg-linear-to-r rtl:bg-linear-to-l")}
+        />
+      ) : null}
+      {edges.end ? (
+        <span
+          aria-hidden="true"
+          data-scroll-edge="end"
+          className={cx(edgeClass, "end-0 bg-linear-to-l rtl:bg-linear-to-r")}
+        />
+      ) : null}
+    </div>
+  );
+}

package/src/Layout/SplitView.tsx

@@ -0,0 +1,78 @@
+import { useRef, useState, type ReactElement } from "react";
+import { cx } from "../lib/cx.ts";
+import { rovingIndex, useControllable } from "../lib/hooks.ts";
+import { StateIcon } from "../StateIcon/StateIcon.tsx";
+import { type SplitViewProps } from "./Layout.types.ts";
+
+/**
+ * A list beside the selected record (Inbox, Dispatch, Advancing). The list is a listbox: arrow keys
+ * move, Home and End jump, Enter or Space selects.
+ */
+export function SplitView({
+  label,
+  selected,
+  items,
+  detail,
+  onSelect,
+}: SplitViewProps): ReactElement {
+  const [current, setCurrent] = useControllable<number>(undefined, selected, onSelect);
+  const [focused, setFocused] = useState(selected);
+  const refs = useRef<(HTMLDivElement | null)[]>([]);
+  return (
+    <div
+      className={cx(
+        "grid grid-cols-[var(--ui-split-list)_minmax(0,1fr)] max-lg:grid-cols-[minmax(0,1fr)]",
+        "min-h-(--ui-split-min) overflow-hidden rounded-card border border-border-subtle",
+      )}
+    >
+      <div
+        role="listbox"
+        aria-label={label}
+        className="bg-bg-surface border-e border-border-subtle max-lg:border-e-0 max-lg:border-b"
+      >
+        {items.map((item, i) => (
+          <div
+            key={`${item.title}-${i}`}
+            ref={(el) => {
+              refs.current[i] = el;
+            }}
+            role="option"
+            aria-selected={i === current}
+            tabIndex={i === focused ? 0 : -1}
+            onClick={() => {
+              setFocused(i);
+              setCurrent(i);
+            }}
+            onKeyDown={(e) => {
+              if (e.key === "Enter" || e.key === " ") {
+                e.preventDefault();
+                setCurrent(i);
+                return;
+              }
+              const next = rovingIndex(e.key, i, items.length, "vertical");
+              if (next === null) return;
+              e.preventDefault();
+              setFocused(next);
+              refs.current[next]?.focus();
+            }}
+            className={cx(
+              "flex items-start gap-8 p-12 border-b border-border-subtle cursor-pointer",
+              "aria-selected:bg-bg-hover hover:bg-bg-hover focus-visible:outline-offset-[calc(var(--stroke-width-focus)*-1)]",
+            )}
+          >
+            {item.state ? (
+              <span className="mt-2">
+                <StateIcon state={item.state} />
+              </span>
+            ) : null}
+            <div className="flex flex-col min-w-0">
+              <strong className="font-medium truncate">{item.title}</strong>
+              <span className="text-text-secondary">{item.meta}</span>
+            </div>
+          </div>
+        ))}
+      </div>
+      <div className="p-20 min-w-0">{detail}</div>
+    </div>
+  );
+}

package/src/Layout/Stepper.tsx

@@ -0,0 +1,39 @@
+import { type ReactElement } from "react";
+import { cx } from "../lib/cx.ts";
+import { Icon } from "../Icon/Icon.tsx";
+import { type StepperProps } from "./Layout.types.ts";
+
+/** Wizard progress: done steps show a check, the current step is marked for assistive technology. */
+export function Stepper({ steps, current }: StepperProps): ReactElement {
+  return (
+    <ol className="flex flex-wrap items-center gap-8 m-0 p-0 list-none">
+      {steps.map((step, i) => {
+        const state = i < current ? "done" : i === current ? "current" : "todo";
+        return (
+          <li
+            key={step}
+            aria-current={state === "current" ? "step" : undefined}
+            className={cx(
+              "flex items-center gap-6 text-text-secondary",
+              "[&+&]:before:w-(--ui-step-line) [&+&]:before:h-(--stroke-width-hairline) [&+&]:before:bg-border-strong [&+&]:before:me-2",
+              state === "current" && "text-text-primary font-medium",
+            )}
+          >
+            <span
+              className={cx(
+                "inline-grid place-items-center flex-none size-icon-20 rounded-full text-text-11 font-semibold tabular-nums",
+                state === "todo" &&
+                  "ring-(length:--stroke-width-hairline) ring-inset ring-border-strong",
+                state === "current" && "bg-accent text-accent-text-on",
+                state === "done" && "bg-bg-hover text-success",
+              )}
+            >
+              {state === "done" ? <Icon name="Check" size={12} /> : i + 1}
+            </span>
+            <span>{step}</span>
+          </li>
+        );
+      })}
+    </ol>
+  );
+}

package/src/LegalText/LegalText.tsx

@@ -0,0 +1,289 @@
+import type { ReactElement, ReactNode } from "react";
+import {
+  LEGAL_HISTORY_ID,
+  type LegalBlock,
+  type LegalInline,
+  type LegalVersion,
+} from "./legal-markdown.ts";
+
+/** Where a document's path leads in this app; null leaves the text as it is written. */
+export type LegalHref = (slug: string) => string | null;
+
+const LINK = "text-accent-text underline";
+const CODE =
+  "font-mono text-mono-12 px-4 py-1 rounded-control bg-bg-raised border border-border-subtle";
+const CELL_PAD = "p-8 align-top";
+/** Past two columns, a table keeps a readable width and scrolls in its region on a phone. */
+const MANY_COLUMNS = 3;
+
+const HEADING_CLASS = {
+  1: "m-0 text-heading-24 font-semibold",
+  2: "m-0 mt-16 text-heading-20 font-semibold scroll-mt-16",
+  3: "m-0 mt-8 text-heading-16 font-semibold scroll-mt-16",
+  4: "m-0 mt-8 text-text-14 font-semibold scroll-mt-16",
+  5: "m-0 mt-8 text-text-14 font-semibold scroll-mt-16",
+  6: "m-0 mt-8 text-text-14 font-semibold scroll-mt-16",
+} as const;
+
+function Inlines({ parts, hrefFor }: { parts: readonly LegalInline[]; hrefFor: LegalHref }) {
+  return parts.map((part, i): ReactNode => {
+    switch (part.t) {
+      case "text":
+        return part.v;
+      case "strong":
+        return (
+          <strong key={i}>
+            <Inlines parts={part.c} hrefFor={hrefFor} />
+          </strong>
+        );
+      case "em":
+        return (
+          <em key={i}>
+            <Inlines parts={part.c} hrefFor={hrefFor} />
+          </em>
+        );
+      case "code":
+        return (
+          <code key={i} className={CODE}>
+            {part.v}
+          </code>
+        );
+      case "link":
+        return (
+          <a key={i} href={part.href} rel="noreferrer" className={LINK}>
+            <Inlines parts={part.c} hrefFor={hrefFor} />
+          </a>
+        );
+      case "mail":
+        return (
+          <a key={i} href={`mailto:${part.v}`} className={LINK}>
+            {part.v}
+          </a>
+        );
+      case "section":
+        return (
+          <a key={i} href={`#${part.id}`} className={LINK}>
+            {part.v}
+          </a>
+        );
+      case "document": {
+        const href = hrefFor(part.slug);
+        return href === null ? (
+          part.v
+        ) : (
+          <a key={i} href={href} className={LINK}>
+            {part.v}
+          </a>
+        );
+      }
+    }
+  });
+}
+
+function Blocks({ blocks, hrefFor }: { blocks: readonly LegalBlock[]; hrefFor: LegalHref }) {
+  return blocks.map((block, i): ReactNode => {
+    switch (block.t) {
+      case "heading": {
+        const Heading = `h${block.level}` as const;
+        return (
+          <Heading key={i} id={block.id} className={HEADING_CLASS[block.level]}>
+            {block.v}
+          </Heading>
+        );
+      }
+      case "p":
+        return (
+          <p key={i} id={block.id} className="m-0 text-text-14 scroll-mt-16">
+            <Inlines parts={block.c} hrefFor={hrefFor} />
+          </p>
+        );
+      case "quote":
+        return (
+          <blockquote
+            key={i}
+            className="m-0 flex flex-col gap-8 border-s-2 border-border-strong ps-12"
+          >
+            <Blocks blocks={block.c} hrefFor={hrefFor} />
+          </blockquote>
+        );
+      case "list": {
+        const List = block.ordered ? "ol" : "ul";
+        return (
+          <List
+            key={i}
+            {...(block.ordered && block.start !== 1 ? { start: block.start } : {})}
+            className={`m-0 flex flex-col gap-4 ps-20 text-text-14 ${block.ordered ? "list-decimal" : "list-disc"}`}
+          >
+            {block.items.map((item, j) => (
+              <li key={j}>
+                <Inlines parts={item.c} hrefFor={hrefFor} />
+                {item.children.length > 0 ? (
+                  <div className="mt-4 flex flex-col gap-4">
+                    <Blocks blocks={item.children} hrefFor={hrefFor} />
+                  </div>
+                ) : null}
+              </li>
+            ))}
+          </List>
+        );
+      }
+      case "table":
+        // In the tab order so a keyboard can scroll it; this page runs no script to measure it.
+        return (
+          <div
+            key={i}
+            role="region"
+            aria-label={block.label}
+            tabIndex={0}
+            className="overflow-x-auto"
+          >
+            <table
+              className={`w-full border-collapse text-text-13 ${block.head.length >= MANY_COLUMNS ? "min-w-(--layout-form)" : ""}`.trim()}
+            >
+              <thead>
+                <tr>
+                  {block.head.map((cell, j) => (
+                    <th
+                      key={j}
+                      scope="col"
+                      className="p-8 text-start align-bottom font-semibold border-b border-border-strong"
+                    >
+                      <Inlines parts={cell} hrefFor={hrefFor} />
+                    </th>
+                  ))}
+                </tr>
+              </thead>
+              <tbody>
+                {block.rows.map((row, j) => (
+                  <tr key={j}>
+                    {row.map((cell, k) => (
+                      <td key={k} className={`${CELL_PAD} border-b border-border-subtle`}>
+                        <Inlines parts={cell} hrefFor={hrefFor} />
+                      </td>
+                    ))}
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+        );
+    }
+  });
+}
+
+/**
+ * A legal document's text as plain elements, for a server component: no hooks and no script, so it
+ * adds nothing to the browser's bundle. The text is written in English whatever the page's locale,
+ * so it says so to assistive technology, and the pseudo-locale check treats it as content.
+ */
+export function LegalText({
+  blocks,
+  hrefFor,
+}: {
+  blocks: readonly LegalBlock[];
+  hrefFor: LegalHref;
+}): ReactElement {
+  return (
+    <div data-pseudo-exempt lang="en-US" dir="ltr" className="contents break-words">
+      <Blocks blocks={blocks} hrefFor={hrefFor} />
+    </div>
+  );
+}
+
+function topHeadings(blocks: readonly LegalBlock[]) {
+  return blocks.filter((b): b is Extract<LegalBlock, { t: "heading" }> => {
+    return b.t === "heading" && b.level === 2;
+  });
+}
+
+function OutlineLinks({ blocks }: { blocks: readonly LegalBlock[] }) {
+  return (
+    <ul lang="en-US" dir="ltr" data-pseudo-exempt className="m-0 flex list-none flex-col gap-8 p-0">
+      {topHeadings(blocks).map((h) => (
+        <li key={h.id}>
+          <a href={`#${h.id}`} className="text-text-secondary hover:text-text-primary no-underline">
+            {h.v}
+          </a>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+/** The fewest headings worth an outline; a shorter document is read in one look. */
+const OUTLINE_MIN = 3;
+
+/** The outline for TemplateDocument's sidebar: the document's sections as in-page links. */
+export function LegalOutline({
+  blocks,
+  label,
+}: {
+  blocks: readonly LegalBlock[];
+  label: string;
+}): ReactElement | null {
+  if (topHeadings(blocks).length < OUTLINE_MIN) return null;
+  return (
+    <nav
+      aria-label={label}
+      className="sticky top-0 flex max-h-dvh flex-col gap-8 overflow-y-auto text-text-13"
+    >
+      <p className="m-0 text-text-12 font-semibold text-text-secondary">{label}</p>
+      <OutlineLinks blocks={blocks} />
+    </nav>
+  );
+}
+
+/** The same outline in the flow of the page, closed until asked for; it needs no script. */
+export function LegalContents({
+  blocks,
+  label,
+}: {
+  blocks: readonly LegalBlock[];
+  label: string;
+}): ReactElement | null {
+  if (topHeadings(blocks).length < OUTLINE_MIN) return null;
+  return (
+    <nav aria-label={label} className="text-text-13">
+      <details className="rounded-card border border-border-subtle bg-bg-surface p-12">
+        <summary className="cursor-pointer font-semibold">{label}</summary>
+        <div className="mt-8">
+          <OutlineLinks blocks={blocks} />
+        </div>
+      </details>
+    </nav>
+  );
+}
+
+/**
+ * The document's versions, newest first, each with its version number and whether and since when
+ * it is in effect (`describe`, in the page's language) and its summary of changes, which is written
+ * in English with the text. Terms of Service 15 promises this list.
+ */
+export function LegalHistory({
+  history,
+  title,
+  describe,
+}: {
+  history: readonly LegalVersion[];
+  title: string;
+  describe: (version: LegalVersion) => string;
+}): ReactElement | null {
+  if (history.length === 0) return null;
+  return (
+    <section aria-labelledby={LEGAL_HISTORY_ID} className="flex flex-col gap-8">
+      <h2 id={LEGAL_HISTORY_ID} className={HEADING_CLASS[2]}>
+        {title}
+      </h2>
+      <ol className="m-0 flex list-none flex-col gap-12 p-0 text-text-14">
+        {history.map((v) => (
+          <li key={v.version} className="flex flex-col gap-4">
+            <span className="font-semibold">{describe(v)}</span>
+            <span data-pseudo-exempt lang="en-US" dir="ltr" className="text-text-secondary">
+              {v.summary}
+            </span>
+          </li>
+        ))}
+      </ol>
+    </section>
+  );
+}

package/src/LegalText/README.md

@@ -0,0 +1,10 @@
+# LegalText
+
+LegalText renders a legal document's Markdown as plain, styled elements on a server component. It has no hooks and no script, so it adds nothing to the browser's bundle, and it writes no HTML string.
+
+- Import it from `@xos/ui/legal-text`, not through an app's client boundary.
+- The text stays in English in every locale and is marked `lang="en-US"`.
+- A wide table scrolls in a labeled region in the tab order; the page itself never scrolls sideways.
+- A `/legal/{slug}` path in the text, an email address, and a "Section 3.6" of the same document become links. The page decides where a document's path leads through `hrefFor`.
+- `LegalOutline` fits TemplateDocument's sidebar; `LegalContents` is the same list in the flow of the page, for where there is no sidebar.
+- `legalTextSource` writes the module an app's generator checks in, so the text reaches the server without reading a file at runtime.

package/src/LegalText/index.ts

@@ -0,0 +1,29 @@
+export {
+  frontmatterField,
+  inlineText,
+  isDraftVersion,
+  LEGAL_HISTORY_ID,
+  legalDay,
+  legalDocumentLinks,
+  legalPlainText,
+  legalTextSource,
+  legalVersionInEffect,
+  legalVersions,
+  legalVersionState,
+  parseLegalMarkdown,
+  stripFrontmatter,
+  type LegalBlock,
+  type LegalHistoryEntry,
+  type LegalInline,
+  type LegalListItem,
+  type LegalTextEntry,
+  type LegalVersion,
+  type LegalVersionState,
+} from "./legal-markdown.ts";
+export {
+  LegalContents,
+  LegalHistory,
+  LegalOutline,
+  LegalText,
+  type LegalHref,
+} from "./LegalText.tsx";