trykeyline 0.0.0-stage → 0.1.0

package/plugins/keyline/skills/keyline/glass/depth/performance-and-fallbacks.md

@@ -0,0 +1,37 @@
+# Performance and fallbacks
+
+Glass's budget and fallbacks, for depth laws 15 and 16. The cost model, what to avoid, how to measure, containment and the fallback order in general are in `domains/depth/fallbacks-and-performance.md`; glass's fallback code is in §8 of the guide.
+
+## What makes it affordable here
+
+The reference implementation runs three or four glass surfaces and stays smooth on a phone.
+
+**Small surfaces.** The dock is a few hundred pixels wide and 48px tall; the settings box is smaller. Nothing spans the viewport.
+
+**Few of them, and only while needed.** The menus **unmount** when closed rather than sitting at `opacity: 0`:
+
+```tsx
+<AnimatePresence>
+  {open && <m.div …>{children}</m.div>}
+</AnimatePresence>
+```
+
+**No animated blur**, and **nothing animating behind the glass**: the backdrop is text and static images.
+
+**The wrapper animates, the surface filters.** The `DropMenu` split in §3 of the guide is a double win: the wrapper animates on the compositor, and the child's filter isn't recomputed against a moving containing block every frame.
+
+## Reduced transparency, per material
+
+The substitutions are per material, not blanket-white: chrome goes to `gray-100`, the raised-surface token, so the dock still reads as raised; the decorative pocket goes to `background-100`, fully opaque, since its whole purpose was translucency. The block names both `:root` and `:root[data-theme="dark"]`, or it wins in one theme only.
+
+## `prefers-contrast: more`
+
+An 8%-alpha hairline is the first thing to disappear under a contrast preference, so the edge goes to `gray-1000`, primary text colour, and the surface stays.
+
+## `@supports`
+
+Without the guard, the reference implementation's surfaces get a bare tint where `backdrop-filter` is missing: legible but weak, marginal at 72% over a photograph. Support is very good (Firefox shipped it unflagged in 103, mid-2022), so it's a small risk, not a live bug. `glass/depth/assets/glass.css` in this guide ships with the guard in place.
+
+## The `-webkit-` prefix on the site
+
+Safari still requires it, and Safari is where glass looks best, but the build adds it (`domains/depth/fallbacks-and-performance.md`, the prefix and the pipeline). The reference implementation hand-wrote the pair and shipped the bug: `.glass-nav`, `.glass-menu`, `.glass-panel` and `.folder-glass` all compile prefixed-only, so Firefox loses every blur. Hand-write the prefixed `none` in the reduced-transparency block and Firefox keeps blurring for the users who asked it to stop.

package/plugins/keyline/skills/keyline/glass/layout/adaptive-presentations.md

@@ -0,0 +1,231 @@
+# Adaptive presentations
+
+Glass's forks, views and breakpoints, for layout laws 8, 9 and 11; the fork test, capability queries, the touch audit and container breakpoints in general are in `domains/layout/forks-gating-and-disclosures.md`.
+
+## Case 1: the navigation dock
+
+```tsx
+export function BottomNav() {
+  return (
+    <nav aria-label="Primary"
+         className="pointer-events-none fixed inset-x-0 bottom-5 z-50 flex justify-center">
+      <MobileDock />    {/* sm:hidden  */}
+      <DesktopDock />   {/* hidden sm:block */}
+    </nav>
+  );
+}
+```
+
+**`DesktopDock`** — icon buttons with a shared sliding highlight and tooltip; hovering an arrow opens a settings drop-up. Scrolling down collapses it to the avatar; hovering, scrolling up, or reaching either end of the page expands it.
+
+**`MobileDock`** — the avatar and a menu button opening a drop-up sheet: pages as text rows, then socials, sound and theme. Toggling a preference leaves the sheet open; navigating or tapping outside closes it.
+
+Almost nothing is shared, because every desktop interaction is hover-driven and touch fires none of them:
+
+| Behaviour | Desktop | Mobile |
+|---|---|---|
+| Reveal pages | Always visible, collapse on scroll | Inside a sheet |
+| Reveal settings | Hover an arrow | A row in the sheet |
+| Item feedback | Sliding highlight + tooltip | `active:bg-highlight` |
+| Labels | Tooltip on hover | Text in the row |
+| Collapse on scroll | Yes | No — nothing brings it back |
+| Press feedback | `active:scale-[0.92]` | `active:scale-[0.92]` |
+
+What *is* shared is extracted — the destinations array, the icons, the preferences hook:
+
+```tsx
+function useNavPrefs() {
+  const [soundOn, setSoundOn] = useState(true);
+  const [theme, setTheme] = useState<ThemeChoice>(getThemeChoice);
+  // …
+  return { soundOn, setSound, theme, pickTheme, sync };
+}
+```
+
+The collapse-on-scroll effect bails out entirely unless `(hover: hover) and (pointer: fine)` matches, so touch never attaches the listener (layout law 8).
+
+### The `sync` subtlety
+
+Both docks are always mounted (hidden by CSS), each with its own copy of the preferences, so a change in the desktop settings box before the viewport crossed the breakpoint would leave the mobile sheet showing a stale toggle.
+
+```tsx
+const toggle = () => {
+  if (!open) sync();     // re-read the stored values as the sheet opens
+  setOpen((o) => !o);
+};
+```
+
+The desktop panel needs no equivalent: it *mounts fresh* on open and reads the values then, whereas the mobile trigger lives in the always-present dock, so its state outlives the panel.
+
+## Case 2: the table of contents
+
+Same tree, two containers, shared row rendering.
+
+```tsx
+/** Shared — used by both presentations. */
+function Rows({ nodes, active, parents, onJump }) { … }
+
+/** The sticky rail, in the left margin on wide screens. */
+export function SectionNav({ nodes, active, onJump }) {
+  return (
+    <nav aria-label="On this page">
+      <ul className="flex flex-col">
+        <Rows … />
+      </ul>
+    </nav>
+  );
+}
+
+/** The narrow-screen disclosure — one line above the article. */
+export function SectionNavCompact({ nodes, active, onJump }) {
+  const [open, setOpen] = useState(false);
+  const jump = (id: string) => { setOpen(false); onJump(id); };
+  return (
+    <details open={open} onToggle={(e) => setOpen(e.currentTarget.open)}
+             className="group rounded-xl border border-gray-alpha-300">
+      <summary className="… [&::-webkit-details-marker]:hidden">
+        On this page
+        <span className="… group-open:rotate-180 motion-reduce:transition-none">
+          <ChevronDownIcon />
+        </span>
+      </summary>
+      <ul className="… border-t border-gray-alpha-300">
+        <Rows … onJump={jump} />
+      </ul>
+    </details>
+  );
+}
+```
+
+Both are rendered; CSS picks one:
+
+```tsx
+<div className="absolute inset-y-0 left-8 hidden w-[196px] xl:block">
+  <div className="sticky top-28 max-h-[calc(100dvh-11rem)] overflow-y-auto">
+    <SectionNav {...nav} />
+  </div>
+</div>
+
+<div className="reveal mt-8 xl:hidden">
+  <SectionNavCompact {...nav} />
+</div>
+```
+
+The props are memoised so both get a stable object:
+
+```tsx
+const nav = useMemo(() => ({ nodes: toc, active, onJump: jump }), [active, jump]);
+```
+
+The compact version is a `<details>` (layout law 11); `open` is mirrored into React state only so it can close itself after a jump. `[&::-webkit-details-marker]:hidden` plus `list-none` removes the default triangle so the chevron can be styled, and `group-open:rotate-180` reads the parent's `open` attribute, so the rotation needs no state. It costs **one line** above the article, which is what makes a nav in the reading flow acceptable.
+
+## Case 3: two views of one collection, chosen by the reader
+
+The first two cases fork on a *device* capability; the gallery's **wall** and **roll** fork on a preference. The interaction model changes, not just the arrangement (layout law 8).
+
+### The state can't live in either component
+
+The control and what it controls are siblings, so a third party owns the value:
+
+```ts
+export type GalleryLayout = "grid" | "roll";
+let current: GalleryLayout = "grid";
+
+const listeners = new Set<(layout: GalleryLayout) => void>();
+export function onGalleryLayoutChange(fn: (l: GalleryLayout) => void) {
+  listeners.add(fn);
+  return () => { listeners.delete(fn); };
+}
+export function setGalleryLayout(layout: GalleryLayout) {
+  current = layout;
+  for (const fn of listeners) fn(layout);
+}
+```
+
+The shape of a theme or sound store, for the same reason: neither consumer can be the other's parent without distorting the layout.
+
+```ts
+// Mirror it in a hook. Read in an EFFECT, not during render: on a
+// server-rendered page the module and the server agree on "grid" for a fresh
+// load, but arriving from another gallery with "roll" already picked would
+// have the client's first paint disagree with the markup.
+export function useGalleryLayout() {
+  const [layout, setLayout] = useState<GalleryLayout>("grid");
+  useEffect(() => {
+    setLayout(getGalleryLayout());
+    return onGalleryLayoutChange(setLayout);
+  }, []);
+  return { layout, pickLayout: setGalleryLayout };
+}
+```
+
+### The choice doesn't persist
+
+The theme persists to `localStorage` forever; the gallery layout lives in module memory, so a fresh load, a reload and a move between galleries all open on the wall (layout law 9; the reason is in §6 of the guide).
+
+### The switch carries the position
+
+Find the item nearest the viewport's centre before the outgoing layout unmounts and open the incoming one there — the measurement is `centreFrame` in `glass/motion/shared-element.md`.
+
+### Each tile declares its own aspect ratio
+
+```tsx
+<figure style={{ aspectRatio: `${photo.w} / ${photo.h}` }}>
+```
+
+Nothing is cropped, so `object-cover` has nothing to do; nothing shifts on load; and one image travels between layouts undistorted, because both ends compute to the same shape.
+
+## Hover in Tailwind
+
+Tailwind v4's `hover:` variant already compiles to a `(hover: hover)` guard, so utility hover states are safe by default. Imperative JavaScript needs the explicit check.
+
+## The touch-versus-hover audit
+
+Glass's answers to the audit in `domains/layout/forks-gating-and-disclosures.md`:
+
+| Hover behaviour | Touch equivalent |
+|---|---|
+| Icon label as a tooltip | Text label in the sheet |
+| Settings box on hover | A row in the sheet |
+| Company card on row hover | Sits below the row instead of beside it, at a wider breakpoint |
+| Folder cards rising | Not available — but the folder is still a link to the same page |
+| Dock collapse on scroll | Doesn't happen |
+
+The folder-card lift is the honest case: a delight beat carrying no information, so touch users lose nothing they need.
+
+## Where responsive utilities are still right
+
+Arrangement, not interaction:
+
+```tsx
+"grid gap-4 sm:gap-6 grid-cols-3"           // grid density
+"columns-3 gap-1 sm:columns-4"              // masonry columns
+"pt-28 sm:pt-20"                            // page padding under fixed chrome
+"absolute left-3 right-3 top-full … xl:left-full xl:top-1/2 xl:ml-6 xl:w-60"
+```
+
+The last is a hover card *below* its row on narrow screens and *beside* it at `xl`, where there's finally margin: only position moves, so it's correctly a breakpoint.
+
+## Breakpoints in use
+
+| Breakpoint | Width | What changes |
+|---|---|---|
+| `sm` | 640px | Mobile dock ↔ desktop dock. Page padding. Masonry columns. Stack columns. |
+| `xl` | 1280px | The TOC rail appears. The hover card moves beside its row. |
+
+Two for the whole site, both derived from content. Both are viewport breakpoints only because here the column *is* the page. `sm` coincides with the reading measure: below it the column is padding-limited, the natural place for the layout to change character. `xl` is where a 640px column finally leaves margin for a 196px rail. Type size is *not* on the list: a 30px article title once stepped to 26px below `sm`, until an 18px type ceiling removed the need (`glass/layout/measure-and-rhythm.md`; the Glass type guide, `glass/type/guide.md`).
+
+## Breakpoints on the container
+
+Where a pane shares the screen with something that opens and closes, it breaks on its own width (layout law 8). In Tailwind:
+
+```tsx
+<section className="@container">                  {/* the pane, not the page */}
+  <div className="grid @2xl:grid-cols-[minmax(240px,1fr)_2fr]">
+    <List />
+    <Detail className="@container" />            {/* sizes its own insides */}
+  </div>
+</section>
+```
+
+Tailwind v4 ships `@container` and the `@sm:`…`@7xl:` variants; plain CSS is `container-type: inline-size` and `@container (min-width: …)`. The list is clamped with `minmax` so it narrows before the detail does, and the nested `@container` lets the detail size its own gutters, rail and labels.

package/plugins/keyline/skills/keyline/glass/layout/assets/SectionNav.tsx

@@ -0,0 +1,244 @@
+/**
+ * Two presentations of one tree — the canonical "fork the container, share
+ * the data" example.
+ *
+ *   SectionNav         the sticky rail that lives in the left margin
+ *   SectionNavCompact  the disclosure that replaces it when there's no margin
+ *
+ * Both render the same nodes through the same `Rows` component. Only the
+ * container differs, because only the container's interaction model differs.
+ *
+ * Rows are real in-page anchors, so they work without JavaScript and can be
+ * copied as links; the click handler takes over to scroll smoothly and keep
+ * the URL in step.
+ *
+ * Pair with useActiveSection (`glass/motion/guide.md`) for the scroll spy, and
+ * give every heading a scroll-margin-top just under its READING_LINE.
+ */
+
+import { useMemo, useState } from "react";
+
+export type TocNode = {
+  /** Id of the heading this row jumps to. */
+  id: string;
+  label: string;
+  children?: TocNode[];
+};
+
+/** Flattens the tree into document order — what the scroll spy measures. */
+export function tocIds(nodes: TocNode[]): string[] {
+  return nodes.flatMap((n) => [n.id, ...tocIds(n.children ?? [])]);
+}
+
+/** child id → parent id, so the section an active row belongs to stays lit. */
+function parentMap(nodes: TocNode[]): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const n of nodes) for (const c of n.children ?? []) map.set(c.id, n.id);
+  return map;
+}
+
+type RowState = "active" | "ancestor" | "rest";
+
+function ChevronDownIcon() {
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden
+      className="h-3.5 w-3.5"
+    >
+      <path d="M6 9l6 6 6-6" />
+    </svg>
+  );
+}
+
+/**
+ * One row.
+ *
+ * Top-level rows sit flush and carry no marker — they read as the headings
+ * they are, and the active one takes a heavier WEIGHT so its state isn't
+ * signalled by colour alone (WCAG 1.4.1). Weight is a genuine second channel:
+ * it survives greyscale, colour-blindness and low-contrast displays, and it's
+ * cheaper than a background pill in a list that's meant to be quiet.
+ *
+ * Nested rows carry a horizontal marker that extends and darkens when active,
+ * and which doubles as their indent. It sits in a FIXED-WIDTH box so growing
+ * it never nudges the label.
+ *
+ * Three tiers of tone and marker, not two: `ancestor` (the section you're
+ * inside, when a child is active) sits between active and rest, so you never
+ * lose the larger context.
+ */
+function Row({
+  node,
+  state,
+  nested,
+  onJump,
+}: {
+  node: TocNode;
+  state: RowState;
+  nested?: boolean;
+  onJump: (id: string) => void;
+}) {
+  const tone =
+    state === "active"
+      ? "text-gray-1000"
+      : state === "ancestor"
+        ? "text-gray-900"
+        : "text-quiet hover:text-gray-1000";
+
+  const marker =
+    state === "active"
+      ? "w-4 bg-gray-1000"
+      : state === "ancestor"
+        ? "w-2.5 bg-gray-600"
+        : "w-2 bg-gray-500";
+
+  return (
+    <a
+      href={`#${node.id}`}
+      aria-current={state === "active" ? "true" : undefined}
+      onClick={(e) => {
+        e.preventDefault();
+        onJump(node.id);
+      }}
+      className={`flex items-start gap-2.5 py-[3px] text-[13px] leading-[1.4] transition-colors duration-150 ease-geist ${tone} ${
+        !nested && state === "active" ? "font-medium" : ""
+      }`}
+    >
+      {nested && (
+        <span aria-hidden className="mt-[9px] w-4 shrink-0">
+          <span
+            className={`block h-px transition-[width,background-color] duration-150 ease-geist motion-reduce:transition-none ${marker}`}
+          />
+        </span>
+      )}
+      {node.label}
+    </a>
+  );
+}
+
+/** Shared tree rendering. Both presentations go through this. */
+function Rows({
+  nodes,
+  active,
+  parents,
+  onJump,
+}: {
+  nodes: TocNode[];
+  active: string;
+  parents: Map<string, string>;
+  onJump: (id: string) => void;
+}) {
+  const state = (id: string): RowState =>
+    id === active ? "active" : parents.get(active) === id ? "ancestor" : "rest";
+
+  return (
+    <>
+      {nodes.map((n) => (
+        <li key={n.id}>
+          <Row node={n} state={state(n.id)} onJump={onJump} />
+          {n.children && (
+            <ul className="flex flex-col">
+              {n.children.map((c) => (
+                <li key={c.id}>
+                  <Row node={c} state={state(c.id)} nested onJump={onJump} />
+                </li>
+              ))}
+            </ul>
+          )}
+        </li>
+      ))}
+    </>
+  );
+}
+
+/**
+ * The sticky rail. Mount it as an absolute child of the wider frame, so it
+ * sits outside the reading column:
+ *
+ *   <div className="relative mx-auto max-w-[1280px]">
+ *     <div className="absolute inset-y-0 left-8 hidden w-[196px] xl:block">
+ *       <div className="sticky top-28 max-h-[calc(100dvh-11rem)] overflow-y-auto">
+ *         <SectionNav {...nav} />
+ *       </div>
+ *     </div>
+ *     <div className="col">…</div>
+ *   </div>
+ *
+ * The absolute wrapper spans the section's full height so the sticky child
+ * has a track to travel. The dvh cap plus overflow-y-auto means a long
+ * contents scrolls inside itself rather than running off the screen.
+ */
+export function SectionNav({
+  nodes,
+  active,
+  onJump,
+}: {
+  nodes: TocNode[];
+  active: string;
+  onJump: (id: string) => void;
+}) {
+  const parents = useMemo(() => parentMap(nodes), [nodes]);
+
+  return (
+    <nav aria-label="On this page">
+      <ul className="flex flex-col">
+        <Rows nodes={nodes} active={active} parents={parents} onJump={onJump} />
+      </ul>
+    </nav>
+  );
+}
+
+/**
+ * The narrow-screen contents: collapsed to a single row, so it costs one line
+ * above the article — which is the constraint that makes putting a nav in the
+ * reading flow acceptable at all. Closes itself once you've jumped.
+ *
+ * <details> rather than a div and state, because it brings keyboard behaviour,
+ * aria-expanded, and find-in-page (browsers open a closed <details> to reveal
+ * a match) for free, and it works with JS disabled. Mirroring `open` into
+ * state is only so the disclosure can close itself after a jump.
+ *
+ * group-open:rotate-180 reads the parent's `open` attribute directly — no
+ * state needed for the chevron.
+ */
+export function SectionNavCompact({
+  nodes,
+  active,
+  onJump,
+}: {
+  nodes: TocNode[];
+  active: string;
+  onJump: (id: string) => void;
+}) {
+  const parents = useMemo(() => parentMap(nodes), [nodes]);
+  const [open, setOpen] = useState(false);
+
+  const jump = (id: string) => {
+    setOpen(false);
+    onJump(id);
+  };
+
+  return (
+    <details
+      open={open}
+      onToggle={(e) => setOpen(e.currentTarget.open)}
+      className="group rounded-xl border border-gray-alpha-300"
+    >
+      <summary className="flex cursor-pointer list-none items-center justify-between gap-3 px-3.5 py-2.5 text-[13px] text-gray-1000 [&::-webkit-details-marker]:hidden">
+        On this page
+        <span className="text-quiet transition-transform duration-200 ease-geist group-open:rotate-180 motion-reduce:transition-none">
+          <ChevronDownIcon />
+        </span>
+      </summary>
+      <ul className="flex flex-col border-t border-gray-alpha-300 px-3.5 py-2">
+        <Rows nodes={nodes} active={active} parents={parents} onJump={jump} />
+      </ul>
+    </details>
+  );
+}