@helloimjolopez-pathway/pathway-components 0.0.0-stage → 0.1.0

package/components/page-template/page-template.jsx

@@ -0,0 +1,147 @@
+/**
+ * PageTemplate: the screen a Pathway page is built on.
+ *
+ * Figma `ScreenTemplate`, set 40009709:26016, page "↳ ❇️ Page Template".
+ *
+ * TWO NESTED SURFACES, and the distinction is the whole component:
+ *
+ *   Container.Screen            the CANVAS behind everything. Fill/Surface/Canvas,
+ *                               padded by SheetContainer/Padding/*, no radius.
+ *   └─ Container.Screen.Main    the SHEET the page actually sits on.
+ *                               Fill/Surface/Elevated, padded by Sheet/Padding/*,
+ *                               rounded at the TOP ONLY, with Shadow/Sheet.
+ *      ├─ Slot.PageNavigation   optional, holds Tabs in Figma's example
+ *      └─ Container.ScreenContent  the page: heading, toolbar, sections
+ *
+ * IT TAKES NO BREAKPOINT PROP, and that is not an omission. Figma models the
+ * three breakpoints as variants because Figma has no media queries. Every value
+ * that differs between them is already a `Responsive: Layout` token, and those
+ * tokens are emitted into media queries by the token pipeline. Read off both
+ * sides on 2026-10-12, they agree exactly:
+ *
+ *            SheetContainer pad    Sheet pad (top/h/bottom)   radius
+ *   Desktop        16 / 24              16 / 32 / 56            28
+ *   Tablet         12 / 16              14 / 24 / 48            24
+ *   Mobile          8 / 12               8 / 16 / 32            20
+ *
+ * So the component reads the tokens and the browser picks the breakpoint. A
+ * `breakpoint` prop here would be a second source of truth for values the CSS
+ * already has, and it would be wrong the moment someone resized a window.
+ *
+ * WHY THIS EXISTS AT ALL. A widget on a dashboard is not understandable without
+ * the page around it: the grid's 12 columns are 12 columns OF SOMETHING, and
+ * that something is this sheet's content box, which is the viewport minus two
+ * levels of padding that both change with the breakpoint. Demonstrating a board
+ * without it shows widgets spanning a container nobody can see.
+ */
+import React from "react";
+
+const R = (n) => `var(--responsive-layout-${n})`;
+const U = (n) => `var(--semantic-layout-units-${n})`;
+const C = (n) => `var(--semantic-color-${n})`;
+
+export const T = {
+  canvas:  C("fill-surface-canvas"),
+  sheet:   C("fill-surface-elevated"),
+  divider: C("stroke-static-neutral-faint"),
+};
+
+export const L = {
+  // The canvas. Bottom is 0 in every variant: the sheet runs to the edge.
+  screenPadH:   R("sheetcontainer-padding-horizontal"),
+  screenPadT:   R("sheetcontainer-padding-top"),
+  // The sheet.
+  sheetPadH:    R("sheet-padding-horizontal"),
+  sheetPadT:    R("sheet-padding-top"),
+  sheetPadB:    R("sheet-padding-bottom"),
+  sheetRadius:  R("sheet-corner-radius-cornerradius"),
+  // Gaps: the sheet's own children, then the page content's sections.
+  sheetGap:     U("gap-tight"),   // 8
+  contentGap:   U("gap-base"),    // 16
+  navHeight:    49,
+};
+
+/**
+ * @param {node} children    Container.ScreenContent: the page itself.
+ * @param {node} navigation  Slot.PageNavigation. Figma's `Show PageTopNavigation`
+ *                           boolean is simply whether this is passed.
+ * @param {bool} grid        Draws the 12/8/4 column guides over the content, so a
+ *                           dashboard demo can show what its spans are spans OF.
+ */
+export function PageTemplate({ children, navigation, grid = false, className = "", style }) {
+  return (
+    <div className={`pw-screen ${className}`} style={{
+      background: T.canvas, minHeight: "100%", boxSizing: "border-box",
+      paddingLeft: L.screenPadH, paddingRight: L.screenPadH,
+      paddingTop: L.screenPadT, paddingBottom: 0,
+      ...style,
+    }}>
+      <div className="pw-screen-main" style={{
+        display: "flex", flexDirection: "column", gap: L.sheetGap,
+        background: T.sheet, boxSizing: "border-box",
+        paddingLeft: L.sheetPadH, paddingRight: L.sheetPadH,
+        paddingTop: L.sheetPadT, paddingBottom: L.sheetPadB,
+        /* TOP CORNERS ONLY. The sheet's bottom edge meets the bottom of the
+           viewport, so rounding it would put a visible notch there. Same shape
+           as the Widget's inner card, for the same reason. */
+        borderTopLeftRadius: L.sheetRadius,
+        borderTopRightRadius: L.sheetRadius,
+        boxShadow: "var(--elevation-sheet)",
+        minHeight: "100%",
+      }}>
+        {navigation ? (
+          <div className="pw-screen-nav" style={{
+            flex: "0 0 auto", minHeight: L.navHeight, boxSizing: "border-box",
+            borderBottom: `1px solid ${T.divider}`,
+          }}>{navigation}</div>
+        ) : null}
+
+        <div className="pw-screen-content" style={{
+          display: "flex", flexDirection: "column", gap: L.contentGap,
+          flex: 1, minHeight: 0, position: "relative",
+        }}>
+          {grid ? <ColumnGuides /> : null}
+          {children}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+/**
+ * The column guides, drawn behind the content. Not part of Figma's component:
+ * this is a teaching aid, which is why it is off by default and why it is
+ * `aria-hidden`. It exists because the board's spans are meaningless without
+ * something to count them against.
+ */
+export function ColumnGuides() {
+  return (
+    <div aria-hidden="true" className="pw-screen-guides" style={{
+      position: "absolute", inset: 0, pointerEvents: "none",
+      display: "grid", gap: U("gap-base"),
+    }}>
+      {Array.from({ length: 12 }).map((_, i) => (
+        <span key={i} style={{
+          gridRow: 1,
+          background: C("fill-action-primary-subtle-rest"),
+          opacity: 0.35,
+        }} />
+      ))}
+    </div>
+  );
+}
+
+/** The breakpoint rules the guides need, since a count cannot be a token. */
+export const PageTemplateStyles = () => (
+  <style>{`
+.pw-screen-guides { grid-template-columns: repeat(12, minmax(0, 1fr)); }
+@media (max-width: 1023px) {
+  .pw-screen-guides { grid-template-columns: repeat(8, minmax(0, 1fr)); }
+}
+@media (max-width: 767px) {
+  .pw-screen-guides { grid-template-columns: repeat(4, minmax(0, 1fr)); }
+}
+`}</style>
+);
+
+export default PageTemplate;

package/components/scrollbar/scrollbar.jsx

@@ -0,0 +1,232 @@
+/**
+ * Scrollable, Pathway Design System
+ *
+ * A reusable overlay-scrollbar wrapper. Hides the native OS scrollbar entirely and renders
+ * one custom liquid-glass thumb so scrolling looks and behaves IDENTICALLY on macOS, Windows,
+ * iOS, and Android (native scrollbars can't be made consistent: this sidesteps them).
+ *
+ * Behaviour (see components/scrollbar/scrollbar-spec.md):
+ *   - Thumb height is PROPORTIONAL to content: (viewport / total) × track, floored at 28px.
+ *   - Reveal: appears while scrolling, fades ~900ms after; also appears when the MOUSE is near
+ *     the right-edge bar (so it can be grabbed). It does NOT appear from hovering the panel.
+ *   - Drag: MOUSE only, via a wider invisible grab strip (the 6px thumb alone is hard to hit).
+ *   - Touch: passive: the bar just shows position; you scroll by swiping content. The grab
+ *     strip is disabled on touch devices via a `(hover: none)` rule.
+ *   - Keyboard / a11y: the content scrolls natively (arrows, PageUp/Down, Home/End, Space); the
+ *     thumb is decorative (`aria-hidden`) and never the only scroll mechanism.
+ *
+ * Usage:
+ *   <Scrollable style={{ flex: 1, minHeight: 0 }}>…tall content…</Scrollable>
+ */
+
+import React, { useRef, useState, useEffect, useCallback } from "react";
+import { useReducedMotion } from "../_shared/use-reduced-motion.jsx";
+
+// ─── TOKENS ──────────────────────────────────────────────────────────────────
+// Every colour + unit resolves through a SEMANTIC Pathway token: no primitives,
+// no hardcoded hex/px. Motion uses the --motion-* tokens (durations/easings from design-system-spec §2).
+export const SCROLL = {
+  thumbWidth:  "var(--semantic-layout-units-padding-xtight)",     // 6px: visible thumb thickness
+  thumbRadius: "var(--semantic-layout-units-cornerradius-full)",  // fully-rounded pill
+  thumbMin:    28,                                                // px, min thumb length (grab-target floor); JS layout math
+  gutter:      "var(--semantic-layout-units-padding-xxxtight)",   // 2px, inset from the right edge
+  grabZone:    16,                                                // px, invisible mouse grab strip (wider than the 6px thumb so it's catchable)
+  // THE LIGHT RUNGS ARE A DELIBERATE CHOICE BY THE DESIGN OWNER. Do not raise
+  // them again without asking Jo first.
+  //
+  // These were briefly Subtle (50%) and Base (70%) to clear the 3:1 AA floor
+  // for a non-text UI component, after one person reported the scrollbar as
+  // missing while another saw it fine. Measured over #fafafa: Faint 16% =
+  // 1.4:1, Light 24% = 1.68:1, Subtle 50% = 3.4:1, Base 70% = 6.57:1.
+  //
+  // Jo reviewed that in Storybook and rejected it: the heavier thumb reads as
+  // a solid grey bar rather than the light warm overlay the design intends, and
+  // an overlay scrollbar is a redundant affordance (the content scrolls with or
+  // without it, and the OS bar remains). So contrast is bought back with SIZE
+  // and PRESENCE rather than with darkness: see thumbWidth and the grab strip.
+  // Scrim/Faint and Scrim/Light resolve to Cool Neutral 800, so the thumb was
+  // drawing a COOL grey over warm surfaces and reading as a cold bar against
+  // them. Reported 2026-10-02. The comment below has always said "light warm
+  // overlay": the value simply did not match it.
+  //
+  // Scrim is also the wrong family: it is the modal backdrop, where a cool
+  // near-black is right. The thumb is an overlay on a surface, and under the
+  // alpha rule surfaces and fills are WARM. So the thumb now resolves through
+  // its own themed custom properties, set in the injected sheet below off the
+  // warm neutral alpha primitives. No new design token: a component-local
+  // property, the same mechanism the Widget uses for its column spans.
+  thumbRest:   "var(--pw-scrollbar-thumb-rest)",    // warm neutral 16%
+  thumbHover:  "var(--pw-scrollbar-thumb-hover)",   // warm neutral 24%
+  thumbBlur:   "blur(8px) saturate(180%)",
+  // Hairline glass edge: semantic white at 35% via color-mix.
+  thumbEdge:   "inset 0 0 0 0.5px color-mix(in srgb, var(--semantic-color-fill-static-neutral-faint) 35%, transparent)",
+  // Fade OUT gracefully, but appear INSTANTLY. Animating opacity on the way in
+  // multiplied the thumb's own alpha by the in-flight opacity, so during the
+  // 200ms glide-in it rendered as low as 1.18:1, below the floor at the exact
+  // moment the user is looking for it. Only the fade-out is animated now.
+  // Asymmetric fade: snappy decelerate glide-IN, graceful fade-OUT. Each entry
+  // names every property it is responsible for, because the element swaps
+  // between them with `transition: active ? fadeIn : fadeOut`.
+  //
+  // fadeIn briefly listed only `background`, on the reasoning that animating
+  // opacity multiplies the thumb's own alpha by the in-flight opacity and dips
+  // the contrast mid-glide. The visible result was worse than the thing it
+  // avoided: the thumb POPPED into existence the instant you scrolled. The
+  // glide is the point, so opacity is back.
+  fadeIn:      "opacity var(--motion-duration-3) var(--motion-easing-decelerate), background var(--motion-duration-3) var(--motion-easing-standard)",
+  fadeOut:     "opacity var(--motion-duration-5) var(--motion-easing-standard), background var(--motion-duration-3) var(--motion-easing-standard)",
+  idleHideMs:  500,                                               // hide the thumb this long after scrolling stops / mouse leaves the bar
+};
+
+// Injected once: hide the native bar on the opt-in class, and disable the mouse grab strip on
+// touch devices so finger-swipes scroll the content underneath (the thumb stays a passive indicator).
+if (typeof document !== "undefined" && !document.getElementById("pds-scrollable-base")) {
+  const s = document.createElement("style");
+  s.id = "pds-scrollable-base";
+  s.textContent =
+    // Warm neutral, and it has to INVERT: 500 is the dark warm grey for a light
+    // surface, 100 the light warm grey for a dark one. An inline style cannot
+    // branch on [data-theme], which is why these live here rather than in the
+    // SCROLL map above.
+    ":root,[data-theme=\"light\"]{" +
+      "--pw-scrollbar-thumb-rest:var(--primitive-color-warm-neutral-500-16);" +
+      "--pw-scrollbar-thumb-hover:var(--primitive-color-warm-neutral-500-24)}" +
+    "[data-theme=\"midnight\"],[data-theme=\"dark\"]{" +
+      "--pw-scrollbar-thumb-rest:var(--primitive-color-warm-neutral-100-16);" +
+      "--pw-scrollbar-thumb-hover:var(--primitive-color-warm-neutral-100-24)}" +
+    ".pds-scrollable__view{scrollbar-width:none;-ms-overflow-style:none}" +
+    ".pds-scrollable__view:-webkit-scrollbar{width:0;height:0;display:none}" +
+    "@media (hover: none){.pds-scrollable__grab{pointer-events:none!important}}";
+  document.head.appendChild(s);
+}
+
+export function Scrollable({ children, className = "", style = {}, viewClassName = "", viewStyle = {} }) {
+  const noMotion = useReducedMotion();
+  const viewRef = useRef(null);
+  const dragRef = useRef(null);
+  const idleRef = useRef(null);
+  const nearRef = useRef(false);                    // mouse currently near the right-edge bar
+  const [thumb, setThumb] = useState({ h: 0, top: 0, show: false });
+  const [active, setActive] = useState(false);       // thumb visible (scrolling, near-bar, or dragging)
+  const [hot, setHot]       = useState(false);       // mouse over / dragging the grab strip
+
+  // Thumb height is PROPORTIONAL to content; floored at thumbMin. Position maps the floored
+  // thumb across the full track so it still reaches top and bottom exactly.
+  const recompute = useCallback(() => {
+    const el = viewRef.current;
+    if (!el) return;
+    const { scrollHeight, clientHeight, scrollTop } = el;
+    if (scrollHeight <= clientHeight + 1) { setThumb(t => (t.show ? { ...t, show: false } : t)); return; }
+    const h   = Math.max(SCROLL.thumbMin, (clientHeight / scrollHeight) * clientHeight);
+    const top = (scrollTop / (scrollHeight - clientHeight)) * (clientHeight - h);
+    setThumb({ h, top, show: true });
+  }, []);
+
+  useEffect(() => {
+    recompute();
+    const el = viewRef.current;
+    if (!el || typeof ResizeObserver === "undefined") return;
+    const ro = new ResizeObserver(recompute);
+    ro.observe(el);
+    Array.from(el.children).forEach(c => ro.observe(c));
+    return () => ro.disconnect();
+  }, [children, recompute]);
+
+  const scheduleHide = () => {
+    clearTimeout(idleRef.current);
+    idleRef.current = setTimeout(() => {
+      if (!dragRef.current && !nearRef.current) setActive(false);
+    }, SCROLL.idleHideMs);
+  };
+  const wake = () => { setActive(true); scheduleHide(); };          // reveal while scrolling
+  const onScroll = () => { recompute(); wake(); };
+
+  // Edge-proximity reveal (mouse): show the bar when the cursor is within grabZone of the right
+  // edge, so it can be grabbed: but NOT from hovering the rest of the panel.
+  const onMouseMove = (e) => {
+    const rect = e.currentTarget.getBoundingClientRect();
+    if (rect.right - e.clientX <= SCROLL.grabZone) {
+      nearRef.current = true; setActive(true); clearTimeout(idleRef.current);
+    } else if (nearRef.current) {
+      nearRef.current = false; scheduleHide();
+    }
+  };
+  const onMouseLeave = () => { nearRef.current = false; if (!dragRef.current) scheduleHide(); };
+
+  // Drag (mouse only). The grab strip carries this; the visual thumb is decorative.
+  const onGrabDown = (e) => {
+    e.preventDefault();
+    const el = viewRef.current;
+    if (!el) return;
+    dragRef.current = { startY: e.clientY, startTop: el.scrollTop };
+    setHot(true); setActive(true); clearTimeout(idleRef.current);
+    const onMove = (ev) => {
+      const { scrollHeight, clientHeight } = el;
+      const h = Math.max(SCROLL.thumbMin, (clientHeight / scrollHeight) * clientHeight);
+      const ratio = (scrollHeight - clientHeight) / (clientHeight - h);
+      el.scrollTop = dragRef.current.startTop + (ev.clientY - dragRef.current.startY) * ratio;
+    };
+    const onUp = () => {
+      dragRef.current = null; setHot(false);
+      document.removeEventListener("mousemove", onMove);
+      document.removeEventListener("mouseup", onUp);
+      wake();
+    };
+    document.addEventListener("mousemove", onMove);
+    document.addEventListener("mouseup", onUp);
+  };
+
+  const barTop = thumb.top, barH = thumb.h;
+
+  return (
+    <div
+      className={`pds-scrollable ${className}`}
+      style={{ position: "relative", minHeight: 0, ...style }}
+      onMouseMove={onMouseMove}
+      onMouseLeave={onMouseLeave}
+    >
+      <div
+        ref={viewRef}
+        className={`pds-scrollable__view ${viewClassName}`}
+        onScroll={onScroll}
+        style={{ height: "100%", overflowY: "auto", overflowX: "hidden", ...viewStyle }}
+      >
+        {children}
+      </div>
+
+      {thumb.show && (
+        <>
+          {/* Visual thumb, decorative, never intercepts pointer events. */}
+          <div
+            aria-hidden="true"
+            style={{
+              position: "absolute", top: barTop, right: SCROLL.gutter,
+              width: SCROLL.thumbWidth, height: barH, borderRadius: SCROLL.thumbRadius,
+              background: hot ? SCROLL.thumbHover : SCROLL.thumbRest,
+              backdropFilter: SCROLL.thumbBlur, WebkitBackdropFilter: SCROLL.thumbBlur,
+              boxShadow: SCROLL.thumbEdge,
+              opacity: active ? 1 : 0, transition: noMotion ? "none" : (active ? SCROLL.fadeIn : SCROLL.fadeOut),
+              pointerEvents: "none", zIndex: 5,
+            }}
+          />
+          {/* Invisible mouse grab strip, wider than the thumb so it's catchable; disabled on
+              touch via the (hover:none) rule so finger-swipes scroll the content beneath. */}
+          <div
+            aria-hidden="true"
+            className="pds-scrollable__grab"
+            onMouseDown={onGrabDown}
+            onMouseEnter={() => setHot(true)}
+            onMouseLeave={() => setHot(false)}
+            style={{
+              position: "absolute", top: barTop, right: 0,
+              width: SCROLL.grabZone, height: barH,
+              pointerEvents: active ? "auto" : "none", zIndex: 6, background: "transparent",
+            }}
+          />
+        </>
+      )}
+    </div>
+  );
+}
+
+export default Scrollable;