@shortlink-org/portolan 0.1.0

package/src/lib/motion.tsx

@@ -0,0 +1,269 @@
+// Motion, in two halves.
+//
+// CSS owns what appears and what changes colour: a card rising on mount, a
+// row hovered, a stagger of cards. That is `stagger-in`, `t-micro`
+// in index.css, driven by the tokens declared there.
+//
+// Motion (motion.dev) owns the three things CSS cannot say on its own: an
+// element that leaves (an exit needs the node to stay mounted while it goes),
+// an element that changes place or size (layout), and an element that is the
+// same thing in two places (a tab indicator that slides, `layoutId`).
+//
+// The two halves share one clock. The durations and easings below are the CSS
+// tokens spelled as numbers; motion.test.ts holds them to index.css so the
+// two cannot drift.
+
+import { useEffect, useState } from "react";
+import type { CSSProperties, ReactNode } from "react";
+import {
+  AnimatePresence,
+  LayoutGroup,
+  LazyMotion,
+  MotionConfig,
+  m,
+} from "motion/react";
+import type { TargetAndTransition, Transition } from "motion/react";
+
+export { AnimatePresence, LayoutGroup, m };
+
+/* ---------------------------------------------------------------------------
+   The clock: index.css --dur-* and --ease-*, as Motion reads them.
+   --------------------------------------------------------------------------- */
+
+/** Seconds. `--dur-micro` and friends in index.css, divided by a thousand. */
+export const DURATION = {
+  micro: 0.15,
+  panel: 0.25,
+  page: 0.25,
+  narrative: 0.4,
+} as const;
+
+/** `--ease-out`: fast out, long settle. Anything that arrives or leaves. */
+export const EASE_OUT = [0.2, 0, 0, 1] as const;
+/** `--ease-in-out`: symmetric. Anything that changes in place. */
+export const EASE_IN_OUT = [0.4, 0, 0.2, 1] as const;
+
+/**
+ * One transition per token, plus the one spring.
+ *
+ * `settle` is for a thing that moves to a new place and is still the same
+ * thing when it gets there: the active-tab indicator, a chevron turning, a
+ * highlight following the current step. A spring reads as weight; a duration
+ * reads as a cut. Its numbers are chosen to land in about the panel duration
+ * with no visible overshoot.
+ */
+export const transitions = {
+  micro: { duration: DURATION.micro, ease: EASE_OUT },
+  panel: { duration: DURATION.panel, ease: EASE_OUT },
+  page: { duration: DURATION.page, ease: EASE_OUT },
+  narrative: { duration: DURATION.narrative, ease: EASE_IN_OUT },
+  settle: { type: "spring", stiffness: 520, damping: 42, mass: 1 },
+} as const satisfies Record<string, Transition>;
+
+/* ---------------------------------------------------------------------------
+   Presence: how a thing arrives and how it leaves. Spread onto an `m.*`
+   element inside an <AnimatePresence>.
+   --------------------------------------------------------------------------- */
+
+/**
+ * The transition rides inside the targets, not as a prop of its own: Headless
+ * UI's DialogPanel has a boolean `transition` of its own, and a preset that
+ * carried one could not be spread onto it.
+ */
+interface Presence {
+  initial: TargetAndTransition;
+  animate: TargetAndTransition;
+  exit: TargetAndTransition;
+}
+
+/** A backdrop, a toast body: opacity only. */
+export const fade: Presence = {
+  initial: { opacity: 0 },
+  animate: { opacity: 1, transition: transitions.panel },
+  exit: { opacity: 0, transition: transitions.panel },
+};
+
+/** A modal: it grows into place by two percent, and shrinks the same on exit. */
+export const scaleIn: Presence = {
+  initial: { opacity: 0, scale: 0.98 },
+  animate: { opacity: 1, scale: 1, transition: transitions.panel },
+  exit: { opacity: 0, scale: 0.98, transition: transitions.panel },
+};
+
+/**
+ * A route: rises the eight pixels on the page duration, and leaves on the
+ * micro duration, opacity only. The reader has already asked for the next
+ * page; the old one should be out of the way, not making an exit.
+ */
+export const page: Presence = {
+  initial: { opacity: 0, y: 8 },
+  animate: { opacity: 1, y: 0, transition: transitions.page },
+  exit: { opacity: 0, transition: transitions.micro },
+};
+
+/** A row, a toast: rises the same eight pixels a page rises. */
+export const rise: Presence = {
+  initial: { opacity: 0, y: 8 },
+  animate: { opacity: 1, y: 0, transition: transitions.panel },
+  exit: { opacity: 0, y: 8, transition: transitions.panel },
+};
+
+/**
+ * A panel that arrives from an edge and leaves the way it came: the catalog
+ * drawer from the left (`-100%`), the detail sheet from the right (`100%`).
+ * A string is a percentage of the element's own width, so the sheet need not
+ * know how wide it is.
+ */
+export function slideFrom(x: number | string): Presence {
+  return {
+    initial: { x },
+    animate: { x: 0, transition: transitions.panel },
+    exit: { x, transition: transitions.panel },
+  };
+}
+
+/**
+ * A branch that opens: height from nothing to whatever its children need, and
+ * back. Overflow is the component's, below: hidden while the height moves,
+ * visible once it has landed.
+ */
+export const unfold: Presence = {
+  initial: { height: 0, opacity: 0 },
+  animate: { height: "auto", opacity: 1, transition: transitions.panel },
+  exit: { height: 0, opacity: 0, transition: transitions.panel },
+};
+
+/**
+ * `unfold`, as a component: the children are there while `open`, and arrive
+ * and leave on the preset. `initial={false}` because a tree restored from the
+ * last session must not open every branch on the way in.
+ */
+export function Unfold({
+  open,
+  children,
+}: {
+  open: boolean;
+  children: ReactNode;
+}) {
+  return (
+    <AnimatePresence initial={false}>
+      {open ? <UnfoldBox>{children}</UnfoldBox> : null}
+    </AnimatePresence>
+  );
+}
+
+/**
+ * Overflow is hidden only while the box is moving. Open and at rest it is
+ * visible, so the focus ring on the first or last row inside is not clipped
+ * by the box that grew to hold it. (`transitionEnd` on the target would say
+ * the same, but Motion 13 applies it only to a static render, not after the
+ * animation it was meant to end.)
+ */
+function UnfoldBox({ children }: { children: ReactNode }) {
+  const [moving, setMoving] = useState(false);
+  return (
+    <m.div
+      {...unfold}
+      style={{ overflow: moving ? "hidden" : "visible" }}
+      onAnimationStart={() => setMoving(true)}
+      onAnimationComplete={() => setMoving(false)}
+    >
+      {children}
+    </m.div>
+  );
+}
+
+/* ---------------------------------------------------------------------------
+   The provider. Once, at the root.
+   --------------------------------------------------------------------------- */
+
+/**
+ * The feature bundle arrives after first paint; until then an `m.*` element
+ * renders as its plain tag, at its `animate` values. That is the correct
+ * first frame anyway: nothing on the first screen leaves or moves.
+ */
+const loadFeatures = () => import("./motion-features").then((mod) => mod.default);
+
+/**
+ * `reducedMotion="user"` makes every `m.*` element read the same media query
+ * `useReducedMotion` below reads: transforms and layout stop moving, opacity
+ * still crossfades, so a reader who asked for less motion still sees things
+ * arrive and leave, just without travelling.
+ *
+ * `strict` throws on a `motion.*` element under this tree - the full one,
+ * with every feature bundled in. Only `m.*` belongs here.
+ */
+export function MotionProvider({ children }: { children: ReactNode }) {
+  return (
+    <LazyMotion features={loadFeatures} strict>
+      <MotionConfig reducedMotion="user" transition={transitions.panel}>
+        {children}
+      </MotionConfig>
+    </LazyMotion>
+  );
+}
+
+/* ---------------------------------------------------------------------------
+   The pieces that predate Motion and stay: a count that ticks up, and the
+   media query for code that animates by hand.
+   --------------------------------------------------------------------------- */
+
+const QUERY = "(prefers-reduced-motion: reduce)";
+
+export function prefersReducedMotion(): boolean {
+  if (typeof window === "undefined" || !window.matchMedia) return false;
+  return window.matchMedia(QUERY).matches;
+}
+
+export function useReducedMotion(): boolean {
+  const [reduced, setReduced] = useState(prefersReducedMotion);
+  useEffect(() => {
+    if (typeof window === "undefined" || !window.matchMedia) return;
+    const mq = window.matchMedia(QUERY);
+    const onChange = () => setReduced(mq.matches);
+    mq.addEventListener("change", onChange);
+    return () => mq.removeEventListener("change", onChange);
+  }, []);
+  return reduced;
+}
+
+/**
+ * Ticks a count up to `value` on first mount. Linear over 200ms - a spring on
+ * a number reads as a slot machine, and these are measurements.
+ *
+ * It animates once, on mount. A later change to `value` lands immediately,
+ * because a re-render is not an arrival.
+ */
+export function useCountUp(value: number, duration = 200): number {
+  const reduced = useReducedMotion();
+  const [shown, setShown] = useState(() => (reduced ? value : 0));
+
+  useEffect(() => {
+    if (reduced || duration <= 0 || value === 0) {
+      setShown(value);
+      return;
+    }
+    let frame = 0;
+    const start = performance.now();
+    const tick = (now: number) => {
+      const t = Math.min(1, (now - start) / duration);
+      setShown(Math.round(value * t));
+      if (t < 1) frame = requestAnimationFrame(tick);
+    };
+    frame = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(frame);
+    // Mount-only on purpose: see above.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  useEffect(() => {
+    if (reduced) setShown(value);
+  }, [reduced, value]);
+
+  return shown;
+}
+
+/** Caps a list index at the stagger ceiling: ten rows, 20ms apart, then flat. */
+export function staggerStyle(index: number, cap = 10): CSSProperties {
+  return { "--i": Math.min(index, cap - 1) } as CSSProperties;
+}

package/src/lib/palette-recent.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+import { catalog } from "../testing/estate";
+import { paletteItems } from "./palette";
+import { itemsById, recentSections } from "./palette-recent";
+import type { Visit } from "../trail/model";
+
+const items = paletteItems(catalog);
+const event = items.find((i) => i.kind === "event" && i.selectId && i.path)!;
+const service = items.find((i) => i.kind === "service" && i.path)!;
+const flow = items.find((i) => i.kind === "flow" && i.path)!;
+const adr = items.find((i) => i.kind === "adr" && i.path)!;
+
+const visit = (path: string, id?: string): Visit => ({
+  path,
+  selection: id ? { kind: "unknown", id } : null,
+});
+
+describe("itemsById", () => {
+  it("finds a selectable row by what it selects, and any row by its id", () => {
+    const byId = itemsById(items);
+    expect(byId.get(event.selectId!)).toBe(event);
+    expect(byId.get(flow.id)).toBe(flow);
+    expect(byId.get(adr.id)).toBe(adr);
+  });
+});
+
+describe("recentSections", () => {
+  it("is empty for a reader with no trail and no pins", () => {
+    expect(recentSections([], [], items, "/")).toEqual([]);
+  });
+
+  it("turns visits into rows, newest first, by selection or by page", () => {
+    const visits = [
+      visit(service.path!, event.selectId),
+      visit(flow.path!),
+      visit(adr.path!),
+    ];
+    const [recent] = recentSections(visits, [], items, "/");
+    expect(recent?.title).toBe("recent");
+    expect(recent?.hits.map((h) => h.item)).toEqual([event, flow, adr]);
+  });
+
+  it("leaves out the page the reader is standing on", () => {
+    const visits = [visit(flow.path!), visit(service.path!)];
+    const [recent] = recentSections(visits, [], items, flow.path!);
+    expect(recent?.hits.map((h) => h.item)).toEqual([service]);
+  });
+
+  it("keeps a visit to the current page when something was selected on it", () => {
+    const visits = [visit(service.path!, event.selectId)];
+    const [recent] = recentSections(visits, [], items, service.path!);
+    expect(recent?.hits.map((h) => h.item)).toEqual([event]);
+  });
+
+  it("drops a visit to something the catalog no longer has", () => {
+    const visits = [visit("/c/nope/gone"), visit(flow.path!, "nope.gone.Event")];
+    expect(recentSections(visits, [], items, "/")).toEqual([
+      { title: "recent", hits: [{ item: flow }] },
+    ]);
+  });
+
+  it("lists pins after the trail, minus what the trail already shows", () => {
+    const visits = [visit(service.path!, event.selectId)];
+    const pins = [
+      { kind: "event" as const, id: event.selectId! },
+      { kind: "service" as const, id: service.selectId ?? service.id },
+    ];
+    const sections = recentSections(visits, pins, items, "/");
+    expect(sections.map((s) => s.title)).toEqual(["recent", "pinned"]);
+    expect(sections[0]?.hits.map((h) => h.item)).toEqual([event]);
+    expect(sections[1]?.hits.map((h) => h.item)).toEqual([service]);
+  });
+
+  it("offers only the pins when there is no trail", () => {
+    const pins = [{ kind: "flow" as const, id: flow.id }];
+    expect(recentSections([], pins, items, "/")).toEqual([
+      { title: "pinned", hits: [{ item: flow }] },
+    ]);
+  });
+});

package/src/lib/palette-recent.ts

@@ -0,0 +1,90 @@
+// What ⌘K offers before anything is typed: where the reader has been, and
+// what they have kept.
+//
+// The trail and the pins already answer both questions, in the chrome. The
+// palette is where a reader's hands already are, though, and "back to the
+// event I was on" as two keystrokes from anywhere is a different thing from
+// the same chip in a strip they would have to find with the mouse.
+//
+// Both stores hold ids, and the rows here are the palette's own rows found
+// by those ids - so a visit to a renamed event shows the new name, and one to
+// a deleted event shows nothing, exactly as the trail and the pin list do.
+
+import type { Pin } from "./pins";
+import type { PaletteHit, PaletteItem } from "./palette";
+import type { Visit } from "../trail/model";
+
+export interface PaletteSection {
+  title: "recent" | "pinned";
+  hits: PaletteHit[];
+}
+
+/** Rows by the id a visit or a pin would name them with. */
+export function itemsById(items: readonly PaletteItem[]): Map<string, PaletteItem> {
+  const byId = new Map<string, PaletteItem>();
+  for (const item of items) {
+    // Selectable rows are named by what they select; the rest by their own
+    // id. A row's own id goes in too when nothing has claimed it, so a pin
+    // on an ADR and a visit to a flow both find their row.
+    if (item.selectId && !byId.has(item.selectId)) byId.set(item.selectId, item);
+    if (!byId.has(item.id)) byId.set(item.id, item);
+  }
+  return byId;
+}
+
+/** The row a visit stands for: its selection when it had one, else its page. */
+function itemOfVisit(
+  visit: Visit,
+  byId: Map<string, PaletteItem>,
+  byPath: Map<string, PaletteItem>,
+): PaletteItem | null {
+  if (visit.selection) {
+    const item = byId.get(visit.selection.id);
+    if (item) return item;
+  }
+  return byPath.get(visit.path) ?? null;
+}
+
+/**
+ * The sections for an empty query. Recent first, newest at the top; then the
+ * pins, minus any row already in the recent list. A section with nothing in
+ * it is left out, and a reader with neither gets an empty list - the palette
+ * falls back to its full index for them.
+ */
+export function recentSections(
+  visits: readonly Visit[],
+  pins: readonly Pin[],
+  items: readonly PaletteItem[],
+  currentPath: string,
+): PaletteSection[] {
+  const byId = itemsById(items);
+  const byPath = new Map<string, PaletteItem>();
+  for (const item of items) {
+    if (item.path && !byPath.has(item.path)) byPath.set(item.path, item);
+  }
+
+  const seen = new Set<PaletteItem>();
+  const recent: PaletteHit[] = [];
+  for (const visit of visits) {
+    // The page the reader is on is not somewhere to go back to - unless the
+    // visit is to something selected on it, which they may have cleared.
+    if (visit.path === currentPath && !visit.selection) continue;
+    const item = itemOfVisit(visit, byId, byPath);
+    if (!item || seen.has(item)) continue;
+    seen.add(item);
+    recent.push({ item });
+  }
+
+  const pinned: PaletteHit[] = [];
+  for (const pin of pins) {
+    const item = byId.get(pin.id);
+    if (!item || seen.has(item)) continue;
+    seen.add(item);
+    pinned.push({ item });
+  }
+
+  const sections: PaletteSection[] = [];
+  if (recent.length > 0) sections.push({ title: "recent", hits: recent });
+  if (pinned.length > 0) sections.push({ title: "pinned", hits: pinned });
+  return sections;
+}