@thewhatmatters/wmds 0.2.0

package/dist/lib/typography.js

@@ -0,0 +1,170 @@
+"use client";
+//#region src/lib/typography.ts
+var e = [
+	{
+		token: "--font-size-4xs",
+		value: "0.375rem",
+		sample: "6px step"
+	},
+	{
+		token: "--font-size-3xs",
+		value: "0.4375rem",
+		sample: "7px step"
+	},
+	{
+		token: "--font-size-2xs",
+		value: "0.5rem",
+		sample: "8px step"
+	},
+	{
+		token: "--font-size-xs",
+		value: "0.625rem",
+		sample: "10px step"
+	},
+	{
+		token: "--font-size-sm",
+		value: "0.75rem",
+		sample: "12px step"
+	},
+	{
+		token: "--font-size-base",
+		value: "0.875rem",
+		sample: "14px — UI body base"
+	},
+	{
+		token: "--font-size-lg",
+		value: "1.0625rem",
+		sample: "17px step"
+	},
+	{
+		token: "--font-size-xl",
+		value: "1.25rem",
+		sample: "20px step"
+	},
+	{
+		token: "--font-size-2xl",
+		value: "1.5rem",
+		sample: "24px — heading-1"
+	},
+	{
+		token: "--font-size-3xl",
+		value: "1.8125rem",
+		sample: "29px step"
+	},
+	{
+		token: "--font-size-4xl",
+		value: "2.1875rem",
+		sample: "35px step"
+	},
+	{
+		token: "--font-size-5xl",
+		value: "2.625rem",
+		sample: "42px step"
+	},
+	{
+		token: "--font-size-6xl",
+		value: "3.15rem",
+		sample: "50.4px step"
+	}
+];
+e.map(({ token: e, value: t, sample: n }) => ({
+	token: e.replace("--font-size-", ""),
+	size: t,
+	lineHeight: "—",
+	sample: n
+}));
+var t = [
+	{
+		role: "display",
+		label: "Display",
+		description: "Hero / marketing headlines — fluid 2.5rem → 5rem (desktop)",
+		astryxType: "display-1",
+		className: "type-display-1 text-fg",
+		tracking: "tight",
+		trackingClass: "tracking-tight",
+		sample: "WhatMatters",
+		usedIn: ["Marketing pages", "SiteNav / landing heroes"]
+	},
+	{
+		role: "page-heading",
+		label: "Page heading",
+		description: "Top-level page title — maps to heading-1",
+		astryxType: "heading-1",
+		className: "type-heading-1 text-fg tracking-tight",
+		tracking: "tight",
+		trackingClass: "tracking-tight",
+		sample: "Find a market",
+		usedIn: ["Page title", "Page headings"]
+	},
+	{
+		role: "section-heading",
+		label: "Section heading",
+		description: "In-page section title — maps to heading-2",
+		astryxType: "heading-2",
+		className: "type-heading-2 text-fg",
+		tracking: "normal",
+		trackingClass: "tracking-normal",
+		sample: "Recent activity",
+		usedIn: ["Settings sections (future)"]
+	},
+	{
+		role: "subheading",
+		label: "Subheading",
+		description: "Card titles, compact headings — maps to heading-4",
+		astryxType: "heading-4",
+		className: "type-heading-4 text-fg",
+		tracking: "normal",
+		trackingClass: "tracking-normal",
+		sample: "Portland Farmers Market",
+		usedIn: ["Card.Header"]
+	},
+	{
+		role: "body",
+		label: "Body",
+		description: "Default reading text — maps to body",
+		astryxType: "body",
+		className: "type-body text-fg",
+		tracking: "normal",
+		trackingClass: "tracking-normal",
+		sample: "The quick brown fox jumps over the lazy dog.",
+		usedIn: ["Card.Body", "Empty states"]
+	},
+	{
+		role: "ui-label",
+		label: "UI label",
+		description: "Form labels, list primary lines — maps to label",
+		astryxType: "label",
+		className: "type-label text-fg",
+		tracking: "normal",
+		trackingClass: "tracking-normal",
+		sample: "Accept recommendation",
+		usedIn: ["Input label", "List row title"]
+	},
+	{
+		role: "caption",
+		label: "Caption",
+		description: "Secondary text, metadata — maps to supporting",
+		astryxType: "supporting",
+		className: "type-supporting text-muted",
+		tracking: "normal",
+		trackingClass: "tracking-normal",
+		sample: "Updated 2 minutes ago",
+		usedIn: ["Address line", "Input description"]
+	},
+	{
+		role: "overline",
+		label: "Overline",
+		description: "Section eyebrows — supporting + uppercase (WMDS extension)",
+		astryxType: "supporting",
+		className: "type-supporting font-medium uppercase tracking-wider text-muted",
+		tracking: "wider",
+		trackingClass: "tracking-wider",
+		sample: "Other options",
+		usedIn: ["Card section labels"]
+	}
+], n = Object.fromEntries(t.map((e) => [e.role, e.className]));
+function r(e) {
+	return n[e];
+}
+//#endregion
+export { e as geometricScale, r as typographyClass, n as typographyRoleClasses, t as typographyStyles };

package/dist/lib/useScrollThreshold.d.ts

@@ -0,0 +1,22 @@
+import { type RefObject } from "react";
+export interface UseScrollThresholdOptions {
+    /**
+     * Scroll container to observe. Defaults to the window / document scroller.
+     * Pass a ref when the page scrolls inside an element (e.g. a demo frame).
+     */
+    container?: RefObject<HTMLElement | null>;
+    /**
+     * Pixels of slack before flipping back below the threshold — prevents flicker
+     * when the scroll position hovers around `threshold`. Default: `8`.
+     */
+    hysteresis?: number;
+    /** Skip listening (e.g. when a controlled state is supplied). Default: `false`. */
+    disabled?: boolean;
+}
+/**
+ * `true` once the scroller has moved `threshold`px or more down the page.
+ * Passive `scroll` listener throttled to one read per frame; SSR-safe (starts `false`).
+ * Internal — consumed by SiteNav collapse (`useSiteNavCollapse`); not a package export.
+ */
+export declare function useScrollThreshold(threshold: number, { container, hysteresis, disabled }?: UseScrollThresholdOptions): boolean;
+//# sourceMappingURL=useScrollThreshold.d.ts.map

package/dist/lib/useScrollThreshold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useScrollThreshold.d.ts","sourceRoot":"","sources":["../../src/lib/useScrollThreshold.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAE5D,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC1C;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAQD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,EAAE,SAAS,EAAE,UAAc,EAAE,QAAgB,EAAE,GAAE,yBAA8B,GAC9E,OAAO,CAmCT"}

package/dist/lib/useScrollThreshold.js

@@ -0,0 +1,29 @@
+"use client";
+import { useEffect as e, useState as t } from "react";
+//#region src/lib/useScrollThreshold.ts
+function n(e) {
+	return e ? e.scrollTop : typeof window > "u" ? 0 : window.scrollY ?? document.documentElement.scrollTop ?? 0;
+}
+function r(r, { container: i, hysteresis: a = 8, disabled: o = !1 } = {}) {
+	let [s, c] = t(!1);
+	return e(() => {
+		if (o || typeof window > "u") return;
+		let e = i?.current ?? window, t = 0, s = () => {
+			t = 0;
+			let e = n(i?.current);
+			c((t) => t ? e > Math.max(0, r - a) : e >= r);
+		}, l = () => {
+			t ||= window.requestAnimationFrame(s);
+		};
+		return s(), e.addEventListener("scroll", l, { passive: !0 }), window.addEventListener("resize", l, { passive: !0 }), () => {
+			t && window.cancelAnimationFrame(t), e.removeEventListener("scroll", l), window.removeEventListener("resize", l);
+		};
+	}, [
+		r,
+		a,
+		o,
+		i
+	]), s;
+}
+//#endregion
+export { r as useScrollThreshold };

package/dist/lib/viewports.d.ts

@@ -0,0 +1,120 @@
+/**
+ * WMDS viewport and breakpoint reference — Tailwind v4 defaults.
+ * Mobile-first: unprefixed utilities = mobile; scale up with sm/md/lg.
+ */
+export interface BreakpointToken {
+    prefix: string;
+    minWidth: string;
+    tier: "mobile" | "sm" | "md" | "lg" | "xl" | "2xl";
+    label: string;
+}
+/** Tailwind default breakpoints — change only via ADR + @theme. */
+export declare const breakpoints: BreakpointToken[];
+/** Storybook viewport presets — use in preview.tsx and story parameters. */
+export declare const storybookViewports: {
+    mobile: {
+        name: string;
+        styles: {
+            width: string;
+            height: string;
+        };
+        type: "mobile";
+    };
+    tablet: {
+        name: string;
+        styles: {
+            width: string;
+            height: string;
+        };
+        type: "tablet";
+    };
+    desktop: {
+        name: string;
+        styles: {
+            width: string;
+            height: string;
+        };
+        type: "desktop";
+    };
+};
+export type StorybookViewportTier = keyof typeof storybookViewports;
+/**
+ * Lock a story to a WMDS viewport tier (Storybook 10 globals API).
+ * Iframe matches breakpoint width; toolbar cannot override.
+ * @see https://storybook.js.org/docs/essentials/viewport
+ */
+export declare function lockedViewportGlobals(tier: StorybookViewportTier): {
+    readonly viewport: {
+        readonly value: "mobile" | "tablet" | "desktop";
+        readonly isRotated: false;
+    };
+};
+/** Story spread — locked viewport + WMDS options catalog + docs iframe (not inline). */
+export declare function lockedViewportStory(tier: StorybookViewportTier): {
+    readonly globals: {
+        readonly viewport: {
+            readonly value: "mobile" | "tablet" | "desktop";
+            readonly isRotated: false;
+        };
+    };
+    readonly parameters: {
+        readonly layout: "fullscreen";
+        readonly viewport: {
+            readonly options: {
+                mobile: {
+                    name: string;
+                    styles: {
+                        width: string;
+                        height: string;
+                    };
+                    type: "mobile";
+                };
+                tablet: {
+                    name: string;
+                    styles: {
+                        width: string;
+                        height: string;
+                    };
+                    type: "tablet";
+                };
+                desktop: {
+                    name: string;
+                    styles: {
+                        width: string;
+                        height: string;
+                    };
+                    type: "desktop";
+                };
+            };
+        };
+        readonly docs: {
+            readonly story: {
+                /** Inline docs use the browser viewport — Tailwind `md:` never fires. Iframe + globals locks width. */
+                readonly inline: false;
+                readonly iframeHeight: string;
+            };
+        };
+    };
+};
+/** One step of the breakpoint ↔ grid contract. `sm:` exists; the column count does not change there. */
+export interface GridBreakpointStep {
+    prefix: string;
+    minWidth: string;
+    minWidthPx: number;
+    cols: number;
+    gutterPx: number;
+    marginPx: number;
+    /** Storybook review viewport that lands on this step, if any. */
+    reviewViewport: StorybookViewportTier | null;
+    label: string;
+}
+/**
+ * Breakpoints and `--grid-cols` are the same scale.
+ * Keep in sync with `src/theme/grid.css` media queries — do not invent a second ladder.
+ */
+export declare const gridScale: readonly GridBreakpointStep[];
+/** Steps where `--grid-cols` actually changes (must match `grid.css`). */
+export declare const gridColumnSteps: GridBreakpointStep[];
+/** Minimum touch target — WCAG 2.5.5 target size (Level AAA); use for atoms on mobile. */
+export declare const minTouchTargetPx = 44;
+//# sourceMappingURL=viewports.d.ts.map

package/dist/lib/viewports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewports.d.ts","sourceRoot":"","sources":["../../src/lib/viewports.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,KAAK,CAAC;IACnD,KAAK,EAAE,MAAM,CAAC;CACf;AAED,mEAAmE;AACnE,eAAO,MAAM,WAAW,EAAE,eAAe,EAqCxC,CAAC;AAEF,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;CAgB9B,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG,MAAM,OAAO,kBAAkB,CAAC;AAEpE;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,qBAAqB;;;;;EAOhE;AAED,wFAAwF;AACxF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gBAYrD,uGAAuG;;;;;;EAOhH;AAED,wGAAwG;AACxG,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,cAAc,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAC7C,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,eAAO,MAAM,SAAS,EAAE,SAAS,kBAAkB,EA6DlD,CAAC;AAEF,0EAA0E;AAC1E,eAAO,MAAM,eAAe,sBAG1B,CAAC;AAEH,0FAA0F;AAC1F,eAAO,MAAM,gBAAgB,KAAK,CAAC"}

package/dist/motion.css

@@ -0,0 +1,73 @@
+/**
+ * WMDS motion sheet — Astryx-aligned duration and easing tokens.
+ * Reference: https://astryx.atmeta.com/docs/motion
+ *
+ * Tier guide:
+ * - fast — hovers, presses, color, focus (high frequency)
+ * - medium — panels, expand/collapse, layout rearrangement
+ * - slow — large spatial transitions (rare)
+ */
+:root {
+  /* Fast tier */
+  --duration-fast-min: 130ms;
+  --duration-fast: 175ms;
+  --duration-fast-max: 230ms;
+
+  /* Medium tier */
+  --duration-medium-min: 310ms;
+  --duration-medium: 410ms;
+  --duration-medium-max: 550ms;
+
+  /* Slow tier */
+  --duration-slow-min: 730ms;
+  --duration-slow: 975ms;
+  --duration-slow-max: 1300ms;
+
+  --ease-standard: cubic-bezier(0.24, 1, 0.4, 1);
+
+  --motion-press-scale: 0.98;
+
+  /* Choreography — sequenced reveals (streamed words, step lists). Read through lib/motion helpers. */
+  --motion-stagger: 60ms;
+  --motion-beat: 160ms;
+  --motion-blur-reveal: 4px;
+
+  /* Legacy aliases — prefer fast/medium/slow tiers in new code */
+  --duration-instant: var(--duration-fast-min);
+  --duration-base: var(--duration-medium-min);
+  --duration-slower: var(--duration-medium-max);
+  --ease-out-expo: var(--ease-standard);
+}
+
+/** Skeleton screens — higher contrast resting fill when shimmer is off (reduced motion). */
+@media (prefers-contrast: more) {
+  .wmds-skeleton-host {
+    background-color: color-mix(in srgb, var(--color-skeleton) 70%, var(--color-text-primary) 30%);
+  }
+}
+
+/** Overflow-only marquee — pause on hover / focus; never run under reduced motion. */
+@keyframes wmds-marquee {
+  to {
+    transform: translate3d(-50%, 0, 0);
+  }
+}
+
+@utility marquee-track {
+  animation: wmds-marquee var(--marquee-duration, 24s) linear infinite;
+
+  @media (prefers-reduced-motion: reduce) {
+    animation: none;
+  }
+}
+
+.group:hover .marquee-track,
+.group:focus-within .marquee-track {
+  animation-play-state: paused;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .marquee-track {
+    animation: none !important;
+  }
+}

package/dist/patterns.css

@@ -0,0 +1,37 @@
+/**
+ * Background patterns — textures for Card occupants, chart canvases, empty states.
+ * Apply via backgroundPattern*Classes from src/lib/backgroundPatterns.ts.
+ */
+
+.wmds-pattern-dot-grid {
+  --wmds-pattern-dot-grid-size: 14px;
+  --wmds-pattern-dot-grid-dot: color-mix(in srgb, var(--color-text-primary) 8%, transparent);
+  background-color: var(--color-background-body);
+  background-image: radial-gradient(
+    circle,
+    var(--wmds-pattern-dot-grid-dot) 1px,
+    transparent 1px
+  );
+  background-size: var(--wmds-pattern-dot-grid-size) var(--wmds-pattern-dot-grid-size);
+}
+
+[data-theme="dark"] .wmds-pattern-dot-grid {
+  --wmds-pattern-dot-grid-dot: color-mix(in srgb, var(--color-text-primary) 12%, transparent);
+}
+
+.wmds-pattern-diagonal-lines {
+  --wmds-pattern-diagonal-lines-size: 14px;
+  --wmds-pattern-diagonal-lines-stroke: color-mix(in srgb, var(--color-text-primary) 8%, transparent);
+  background-color: var(--color-background-body);
+  background-image: repeating-linear-gradient(
+    -45deg,
+    var(--wmds-pattern-diagonal-lines-stroke) 0,
+    var(--wmds-pattern-diagonal-lines-stroke) 1px,
+    transparent 1px,
+    transparent var(--wmds-pattern-diagonal-lines-size)
+  );
+}
+
+[data-theme="dark"] .wmds-pattern-diagonal-lines {
+  --wmds-pattern-diagonal-lines-stroke: color-mix(in srgb, var(--color-text-primary) 12%, transparent);
+}