@aphrody/m3-showcase 3.3.4

package/src/shell/Shell.tsx

@@ -0,0 +1,383 @@
+// The adaptive shell. One component tree, three layouts chosen from the window size class and the layout mode:
+//   mobile  (compact)          top app bar, content, bottom navigation bar, "More" sheet for the other destinations
+//   desktop (medium and up)    navigation rail (medium, expanded) or standard drawer (large, extra large) beside the content
+//   tv                         10-foot drawer, large type, focus ring, D-pad (arrow keys + Enter + Back) navigation
+import { useM3Theme } from "@aphrody/m3-theme/react";
+import { Component, Suspense, useEffect, useRef, useState, type ReactNode } from "react";
+import closeIcon from "m3:icons/close";
+import contrastIcon from "m3:icons/contrast";
+import darkIcon from "m3:icons/dark_mode";
+import lightIcon from "m3:icons/light_mode";
+import { attachDpad } from "../adaptive/dpad.ts";
+import { useAdaptive, type AdaptiveState } from "../adaptive/window.ts";
+import { Svg } from "../components/ui.tsx";
+import { PAGES } from "../pages/index.ts";
+import { useRoute } from "../router.ts";
+import {
+  DESTINATIONS,
+  MORE_ICON,
+  MORE_ICON_FILLED,
+  PRIMARY_IDS,
+  findDestination,
+  type Destination,
+} from "./nav.ts";
+
+const MODE_LABEL = { light: "Light", dark: "Dark", system: "System" } as const;
+
+function ThemeModeButton() {
+  const { themeMode, setThemeMode } = useM3Theme();
+  const next = themeMode === "system" ? "light" : themeMode === "light" ? "dark" : "system";
+  const icon = themeMode === "light" ? lightIcon : themeMode === "dark" ? darkIcon : contrastIcon;
+  return (
+    <button
+      type="button"
+      className="state-layer inline-flex size-12 items-center justify-center rounded-full text-on-surface-variant"
+      aria-label={`Colour scheme: ${MODE_LABEL[themeMode]}. Switch to ${MODE_LABEL[next]}`}
+      title={`Colour scheme: ${MODE_LABEL[themeMode]}`}
+      onClick={() => setThemeMode(next)}
+    >
+      <Svg html={icon} />
+    </button>
+  );
+}
+
+function TopBar({ a, current }: { a: AdaptiveState; current: Destination }) {
+  return (
+    <header
+      className="flex h-16 shrink-0 items-center gap-2 bg-surface px-(--m3-gutter) text-on-surface"
+      role="banner"
+    >
+      <div
+        className={`${a.mode === "tv" ? "text-headline-medium" : "text-title-large"} flex-1 truncate`}
+        data-testid="top-title"
+      >
+        {a.mode === "mobile" ? current.label : `Aphrody M3 / ${current.label}`}
+      </div>
+      <span
+        className="hidden rounded-full bg-secondary-container px-3 py-1 text-label-medium text-on-secondary-container expanded:inline"
+        data-testid="window-class"
+        title="Window size class, M3 breakpoints"
+      >
+        {a.width} · {a.mode}
+      </span>
+      <ThemeModeButton />
+    </header>
+  );
+}
+
+function NavItem({
+  item,
+  selected,
+  variant,
+  onSelect,
+}: {
+  item: Destination;
+  selected: boolean;
+  variant: "bar" | "rail" | "drawer";
+  onSelect: (id: string) => void;
+}) {
+  const icon = <Svg html={selected ? item.iconFilled : item.icon} />;
+  if (variant === "drawer") {
+    return (
+      <a
+        href={`#/${item.id}`}
+        data-dpad
+        data-testid={`nav-${item.id}`}
+        aria-current={selected ? "page" : undefined}
+        className={`state-layer flex h-14 w-full items-center gap-3 rounded-full px-4 text-label-large ${selected ? "bg-secondary-container text-on-secondary-container" : "text-on-surface-variant"}`}
+        onClick={(event) => {
+          if (
+            event.button === 0 &&
+            !event.metaKey &&
+            !event.ctrlKey &&
+            !event.shiftKey &&
+            !event.altKey
+          ) {
+            event.preventDefault();
+            onSelect(item.id);
+          }
+        }}
+      >
+        {icon}
+        <span className="truncate">{item.label}</span>
+      </a>
+    );
+  }
+  return (
+    <a
+      href={`#/${item.id}`}
+      data-dpad
+      data-testid={`nav-${item.id}`}
+      aria-current={selected ? "page" : undefined}
+      className={`state-layer group flex ${variant === "bar" ? "flex-1 py-3" : "w-full py-1.5"} flex-col items-center gap-1 text-label-medium ${selected ? "text-on-surface" : "text-on-surface-variant"}`}
+      onClick={() => onSelect(item.id)}
+    >
+      <span
+        className={`flex h-8 w-16 items-center justify-center rounded-full ${selected ? "bg-secondary-container text-on-secondary-container" : ""}`}
+      >
+        {icon}
+      </span>
+      <span className="max-w-full truncate px-1">{item.label}</span>
+    </a>
+  );
+}
+
+function SideNav({
+  a,
+  route,
+  navigate,
+}: {
+  a: AdaptiveState;
+  route: string;
+  navigate: (id: string) => void;
+}) {
+  const drawer = a.mode === "tv" || a.navigation === "rail-expanded";
+  return (
+    <nav
+      aria-label="Destinations"
+      className={`m3-scroll flex shrink-0 flex-col gap-1 overflow-y-auto bg-surface p-3 ${drawer ? (a.mode === "tv" ? "w-[19rem]" : "w-[22.5rem]") : "w-24"}`}
+      data-testid={drawer ? "drawer" : "rail"}
+    >
+      {DESTINATIONS.map((item) => (
+        <NavItem
+          key={item.id}
+          item={item}
+          selected={route === item.id}
+          variant={drawer ? "drawer" : "rail"}
+          onSelect={navigate}
+        />
+      ))}
+    </nav>
+  );
+}
+
+function BottomBar({
+  route,
+  navigate,
+  onMore,
+}: {
+  route: string;
+  navigate: (id: string) => void;
+  onMore: () => void;
+}) {
+  const primary = PRIMARY_IDS.map(findDestination);
+  const moreSelected = !PRIMARY_IDS.includes(route as (typeof PRIMARY_IDS)[number]);
+  return (
+    <nav
+      aria-label="Destinations"
+      className="flex h-20 shrink-0 items-stretch bg-surface-container px-2 pb-[env(safe-area-inset-bottom)]"
+      data-testid="bottom-bar"
+    >
+      {primary.map((item) => (
+        <NavItem
+          key={item.id}
+          item={item}
+          selected={route === item.id}
+          variant="bar"
+          onSelect={navigate}
+        />
+      ))}
+      <button
+        type="button"
+        data-testid="nav-more"
+        aria-haspopup="dialog"
+        className={`state-layer flex flex-1 flex-col items-center gap-1 py-3 text-label-medium ${moreSelected ? "text-on-surface" : "text-on-surface-variant"}`}
+        onClick={onMore}
+      >
+        <span
+          className={`flex h-8 w-16 items-center justify-center rounded-full ${moreSelected ? "bg-secondary-container text-on-secondary-container" : ""}`}
+        >
+          <Svg html={moreSelected ? MORE_ICON_FILLED : MORE_ICON} />
+        </span>
+        <span>More</span>
+      </button>
+    </nav>
+  );
+}
+
+/** The destinations behind "More", as a modal bottom sheet on a native <dialog> (focus trap and Escape for free). */
+function MoreSheet({
+  open,
+  route,
+  navigate,
+  onClose,
+}: {
+  open: boolean;
+  route: string;
+  navigate: (id: string) => void;
+  onClose: () => void;
+}) {
+  const ref = useRef<HTMLDialogElement>(null);
+  useEffect(() => {
+    const dialog = ref.current;
+    if (!dialog) return;
+    if (open && !dialog.open) dialog.showModal();
+    if (!open && dialog.open) dialog.close();
+  }, [open]);
+  return (
+    <dialog
+      ref={ref}
+      onClose={onClose}
+      onClick={(event) => event.target === ref.current && onClose()}
+      className="m-0 mt-auto w-full max-w-none rounded-t-extra-large bg-surface-container-low p-4 text-on-surface backdrop:bg-scrim/32"
+      data-testid="more-sheet"
+      aria-label="All destinations"
+    >
+      <div className="mb-2 flex items-center justify-between">
+        <h2 className="text-title-large">All destinations</h2>
+        <button
+          type="button"
+          className="state-layer inline-flex size-12 items-center justify-center rounded-full"
+          aria-label="Close"
+          onClick={onClose}
+        >
+          <Svg html={closeIcon} />
+        </button>
+      </div>
+      <div className="grid grid-cols-3 gap-2">
+        {DESTINATIONS.map((item) => (
+          <a
+            key={item.id}
+            href={`#/${item.id}`}
+            data-testid={`more-${item.id}`}
+            aria-current={route === item.id ? "page" : undefined}
+            className={`state-layer flex flex-col items-center gap-1 rounded-large p-3 text-label-medium ${route === item.id ? "bg-secondary-container text-on-secondary-container" : "text-on-surface-variant"}`}
+            onClick={(event) => {
+              if (
+                event.button === 0 &&
+                !event.metaKey &&
+                !event.ctrlKey &&
+                !event.shiftKey &&
+                !event.altKey
+              ) {
+                event.preventDefault();
+                navigate(item.id);
+                onClose();
+              }
+            }}
+          >
+            <Svg html={route === item.id ? item.iconFilled : item.icon} />
+            <span className="truncate">{item.label}</span>
+          </a>
+        ))}
+      </div>
+    </dialog>
+  );
+}
+
+function PageSlot({
+  a,
+  route,
+  children,
+}: {
+  a: AdaptiveState;
+  route: string;
+  children: ReactNode;
+}) {
+  const heading = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    // After a route change the page, not the nav, takes focus: screen readers announce the new title. TV keeps the nav focused.
+    if (a.mode !== "tv") heading.current?.focus({ preventScroll: true });
+  }, [route, a.mode]);
+  return (
+    <main
+      id="main"
+      ref={heading}
+      tabIndex={-1}
+      className="m3-scroll min-w-0 flex-1 overflow-y-auto rounded-tl-extra-large bg-surface-container-lowest outline-none"
+      data-testid="main"
+      data-route={route}
+      aria-labelledby="page-title"
+    >
+      {children}
+    </main>
+  );
+}
+
+class PageBoundary extends Component<{ children: ReactNode }, { failed: boolean }> {
+  override state = { failed: false };
+  static getDerivedStateFromError() {
+    return { failed: true };
+  }
+  override render() {
+    if (this.state.failed)
+      return (
+        <div className="p-6" role="alert">
+          <h1 id="page-title" className="text-headline-medium">
+            Unable to load this page
+          </h1>
+          <p>Reload to try again.</p>
+          <button
+            type="button"
+            className="state-layer rounded-full bg-primary px-6 py-3 text-on-primary"
+            onClick={() => location.reload()}
+          >
+            Reload
+          </button>
+        </div>
+      );
+    return this.props.children;
+  }
+}
+
+export function Shell() {
+  const a = useAdaptive();
+  const { route, navigate } = useRoute();
+  const [more, setMore] = useState(false);
+  const current = findDestination(route);
+  const Page = PAGES[current.id];
+
+  useEffect(
+    () =>
+      a.mode === "tv" || document.documentElement.dataset["dpad"] === "on"
+        ? attachDpad({ onBack: () => history.back() })
+        : undefined,
+    [a.mode],
+  );
+  useEffect(() => {
+    document.title = `${current.label} · Aphrody M3 Showcase`;
+  }, [current.label]);
+
+  return (
+    <div className="flex h-full flex-col bg-surface" data-testid="shell" data-layout={a.mode}>
+      <a
+        href="#main"
+        onClick={(event) => {
+          event.preventDefault();
+          document.getElementById("main")?.focus();
+        }}
+        className="sr-only focus:not-sr-only focus:absolute focus:left-2 focus:top-2 focus:z-50 focus:rounded-full focus:bg-primary focus:px-4 focus:py-2 focus:text-on-primary"
+      >
+        Skip to content
+      </a>
+      <TopBar a={a} current={current} />
+      <div className="flex min-h-0 flex-1">
+        {a.mode !== "mobile" ? <SideNav a={a} route={current.id} navigate={navigate} /> : null}
+        <PageSlot a={a} route={current.id}>
+          <PageBoundary key={current.id}>
+            <Suspense
+              fallback={
+                <div className="p-6 text-body-medium text-on-surface-variant" role="status">
+                  Loading {current.label}…
+                </div>
+              }
+            >
+              <Page adaptive={a} />
+            </Suspense>
+          </PageBoundary>
+        </PageSlot>
+      </div>
+      {a.mode === "mobile" ? (
+        <BottomBar route={current.id} navigate={navigate} onMore={() => setMore(true)} />
+      ) : null}
+      {a.mode === "mobile" ? (
+        <MoreSheet
+          open={more}
+          route={current.id}
+          navigate={navigate}
+          onClose={() => setMore(false)}
+        />
+      ) : null}
+    </div>
+  );
+}

package/src/shell/nav.ts

@@ -0,0 +1,198 @@
+// Destinations of the showcase: one per group of packages, each with the packages it demonstrates.
+import appsIcon from "m3:icons/apps";
+import appsFilled from "m3:icons/apps?fill=1";
+import badgeIcon from "m3:icons/badge";
+import badgeFilled from "m3:icons/badge?fill=1";
+import designIcon from "m3:icons/design_services";
+import designFilled from "m3:icons/design_services?fill=1";
+import devicesIcon from "m3:icons/devices";
+import devicesFilled from "m3:icons/devices?fill=1";
+import editIcon from "m3:icons/edit_note";
+import editFilled from "m3:icons/edit_note?fill=1";
+import folderIcon from "m3:icons/folder";
+import folderFilled from "m3:icons/folder?fill=1";
+import homeIcon from "m3:icons/home";
+import homeFilled from "m3:icons/home?fill=1";
+import motionIcon from "m3:icons/animation";
+import motionFilled from "m3:icons/animation?fill=1";
+import paletteIcon from "m3:icons/palette";
+import paletteFilled from "m3:icons/palette?fill=1";
+import readerIcon from "m3:icons/menu_book";
+import readerFilled from "m3:icons/menu_book?fill=1";
+import smartIcon from "m3:icons/smart_toy";
+import smartFilled from "m3:icons/smart_toy?fill=1";
+import symbolsIcon from "m3:icons/interests";
+import symbolsFilled from "m3:icons/interests?fill=1";
+import terminalIcon from "m3:icons/terminal";
+import terminalFilled from "m3:icons/terminal?fill=1";
+import webIcon from "m3:icons/web";
+import webFilled from "m3:icons/web?fill=1";
+import widgetsIcon from "m3:icons/widgets";
+import widgetsFilled from "m3:icons/widgets?fill=1";
+import extensionIcon from "m3:icons/extension";
+import extensionFilled from "m3:icons/extension?fill=1";
+
+import type { PageId } from "../pages/index.ts";
+
+export interface Destination {
+  id: PageId;
+  label: string;
+  /** Outlined and filled (selected) Material Symbols SVG markup. */
+  icon: string;
+  iconFilled: string;
+  /** What the page shows, one sentence. */
+  summary: string;
+  /** The workspace packages the page imports and exercises. */
+  packages: readonly string[];
+}
+
+export const DESTINATIONS: readonly Destination[] = [
+  {
+    id: "overview",
+    label: "Overview",
+    icon: homeIcon,
+    iconFilled: homeFilled,
+    summary: "Every package of the monorepo, served by this app's own API.",
+    packages: ["@aphrody/m3", "@aphrody/m3-bun", "@aphrody/m3-config"],
+  },
+  {
+    id: "theme",
+    label: "Theme",
+    icon: paletteIcon,
+    iconFilled: paletteFilled,
+    summary: "Material You roles from a seed: tokens, Tailwind preset, fonts, a scoped <m3-theme>.",
+    packages: [
+      "@aphrody/m3-theme",
+      "@aphrody/m3-tokens",
+      "@aphrody/m3-front",
+      "@aphrody/m3-tailwind",
+      "@aphrody/m3-fonts",
+    ],
+  },
+  {
+    id: "components",
+    label: "Components",
+    icon: widgetsIcon,
+    iconFilled: widgetsFilled,
+    summary: "The Material Web components through their React wrappers.",
+    packages: ["@aphrody/m3-react"],
+  },
+  {
+    id: "primitives",
+    label: "Primitives",
+    icon: extensionIcon,
+    iconFilled: extensionFilled,
+    summary: "Accessible parts on Base UI, styled with M3 tokens.",
+    packages: ["@aphrody/m3-primitives", "@aphrody/m3-baseui"],
+  },
+  {
+    id: "forms",
+    label: "Forms",
+    icon: editIcon,
+    iconFilled: editFilled,
+    summary: "react-hook-form fields with M3 inputs, validation and descriptions.",
+    packages: ["@aphrody/m3-forms"],
+  },
+  {
+    id: "explorer",
+    label: "Explorer",
+    icon: folderIcon,
+    iconFilled: folderFilled,
+    summary: "A file explorer: list and grid views, thumbnails, tags, rename.",
+    packages: ["@aphrody/m3-explorer"],
+  },
+  {
+    id: "motion",
+    label: "Motion",
+    icon: motionIcon,
+    iconFilled: motionFilled,
+    summary: "Springs, easings, shared axis, container transform, list stagger.",
+    packages: ["@aphrody/m3-motion", "@aphrody/m3-react"],
+  },
+  {
+    id: "icons",
+    label: "Icons & fonts",
+    icon: symbolsIcon,
+    iconFilled: symbolsFilled,
+    summary: "Material Symbols from the forked catalogue, inlined at build time.",
+    packages: ["@aphrody/m3-icons", "@aphrody/material-design-icons", "@aphrody/m3-fonts"],
+  },
+  {
+    id: "ai",
+    label: "AI",
+    icon: smartIcon,
+    iconFilled: smartFilled,
+    summary: "A chat transcript, tool calls, markdown and an AG-UI stream from the API.",
+    packages: ["@aphrody/m3-ai", "@aphrody/ag-ui"],
+  },
+  {
+    id: "reader",
+    label: "Reader",
+    icon: readerIcon,
+    iconFilled: readerFilled,
+    summary: "Manga and databook readers with paging, vertical scroll and RTL.",
+    packages: ["@aphrody/m3-reader"],
+  },
+  {
+    id: "design",
+    label: "Design",
+    icon: designIcon,
+    iconFilled: designFilled,
+    summary: "A design brief parsed and turned into an M3 theme by the design engine.",
+    packages: ["@aphrody/m3-design"],
+  },
+  {
+    id: "next",
+    label: "Next",
+    icon: webIcon,
+    iconFilled: webFilled,
+    summary: "Metadata, scheme CSS, robots, sitemap and JSON-LD from the Next integration.",
+    packages: ["@aphrody/m3-next", "@aphrody/m3-next-migrate"],
+  },
+  {
+    id: "system",
+    label: "System",
+    icon: terminalIcon,
+    iconFilled: terminalFilled,
+    summary: "OS themes, scaffolds, MCP tools, codemods and lint rules, computed by the API.",
+    packages: [
+      "@aphrody/m3-os-themes",
+      "@aphrody/scaffold",
+      "@aphrody/m3-mcp",
+      "@aphrody/m3-codemods",
+      "@aphrody/eslint-plugin-m3",
+    ],
+  },
+  {
+    id: "brands",
+    label: "Brands",
+    icon: badgeIcon,
+    iconFilled: badgeFilled,
+    summary: "Host-bound UI kits where they resolve, the identity set, canvas and assets.",
+    packages: [
+      "@rosegriffon/ui",
+      "@shenron/ui",
+      "@aphrody/nie-ui",
+      "@aphrody/identity",
+      "@aphrody/canvas",
+      "@aphrody/assets",
+    ],
+  },
+  {
+    id: "adaptive",
+    label: "Adaptive",
+    icon: devicesIcon,
+    iconFilled: devicesFilled,
+    summary: "Window size classes, layout modes and the TV D-pad lab.",
+    packages: ["@aphrody/m3-tokens", "@aphrody/m3-front"],
+  },
+];
+
+/** The destinations the mobile bottom bar shows; the rest sit behind "More". */
+export const PRIMARY_IDS = ["overview", "theme", "components", "adaptive"] as const;
+
+export const MORE_ICON = appsIcon;
+export const MORE_ICON_FILLED = appsFilled;
+
+export const findDestination = (id: string): Destination =>
+  DESTINATIONS.find((d) => d.id === id) ?? DESTINATIONS[0]!;

package/src/styles.css

@@ -0,0 +1,61 @@
+@import "tailwindcss";
+@import "@aphrody/m3-tokens/m3-tokens.css";
+@import "@aphrody/m3-tokens/expressive.css";
+@import "@aphrody/m3-tailwind/preset.css";
+
+/*
+ * Google Sans Flex (latin subset) from @aphrody/m3-fonts. The package's own fonts.css also declares Google Sans Code and
+ * Roboto Mono: Bun inlines CSS url() assets under ~128 KB as base64 (neither a loader nor a plugin changes that), which
+ * would put ~290 KB of data URLs into the render-blocking stylesheet. The Icons & fonts page loads the other families itself.
+ */
+@font-face {
+  font-family: "Google Sans Flex";
+  src: url("../../../packages/m3-fonts/fonts/web/GoogleSansFlex-latin.woff2") format("woff2");
+  font-weight: 1 1000;
+  font-stretch: 25% 151%;
+  font-style: oblique -10deg 0deg;
+  font-display: swap;
+}
+
+/* The showcase sets colour roles at runtime (M3ThemeProvider); everything else comes from the token sheets. */
+:root {
+  --m3-nav-width: 0px;
+  --m3-gutter: 16px;
+  color-scheme: light dark;
+}
+html[data-m3-width="medium"], html[data-m3-width="expanded"], html[data-m3-width="large"], html[data-m3-width="extra-large"] { --m3-gutter: 24px; }
+
+html, body, #root { height: 100%; }
+body {
+  margin: 0;
+  background: var(--md-sys-color-background);
+  color: var(--md-sys-color-on-background);
+  font-family: var(--md-ref-typeface-plain);
+  font-size: var(--md-sys-typescale-body-large-size);
+  line-height: var(--md-sys-typescale-body-large-line-height);
+  -webkit-font-smoothing: antialiased;
+  overscroll-behavior: none;
+}
+* { box-sizing: border-box; }
+a { color: inherit; }
+
+/* TV: 10-foot type scale, safe area, obvious focus. */
+html[data-layout="tv"] { font-size: 150%; }
+html[data-layout="tv"] body { padding: 2.5vh 2.5vw; }
+html[data-layout="tv"] :focus-visible,
+html[data-layout="tv"] [data-dpad-focus] {
+  outline: 4px solid var(--md-sys-color-primary);
+  outline-offset: 4px;
+  border-radius: var(--md-sys-shape-corner-medium);
+}
+:focus-visible { outline: 2px solid var(--md-sys-color-primary); outline-offset: 2px; }
+
+.m3-scroll { scrollbar-width: thin; scrollbar-color: var(--md-sys-color-outline-variant) transparent; }
+.m3-card { background: var(--md-sys-color-surface-container); border-radius: var(--md-sys-shape-corner-large); padding: 16px; }
+.m3-code { font-family: var(--md-ref-typeface-code, ui-monospace, monospace); font-size: 0.8125rem; background: var(--md-sys-color-surface-container-highest); border-radius: var(--md-sys-shape-corner-small); padding: 12px; overflow: auto; white-space: pre; }
+.m3-icon svg { width: 1.5rem; height: 1.5rem; fill: currentColor; display: block; }
+.m3-icon-sm svg { width: 1.125rem; height: 1.125rem; fill: currentColor; display: block; }
+
+@media (prefers-reduced-motion: reduce) {
+  * { animation-duration: 0.01ms !important; transition-duration: 0.01ms !important; }
+}