@thebankingengineer/site-effects 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,98 @@
1
- # Temporary Holding Version
1
+ # @thebankingengineer/site-effects
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Shared motion, loading and feedback components for React apps and
4
+ micro-frontends built on [`@thebankingengineer/design-tokens`](../). Every
5
+ component is styled by the tokens' `effects.css`, so it takes on whichever
6
+ brand theme the app imports, in light and dark.
7
+
8
+ | Export | What it does |
9
+ |---|---|
10
+ | **Background** | |
11
+ | `<NetworkBackground />` | A "settlement network" mesh fixed behind the page, with ambient payment pulses. On a mouse/trackpad it adds a hover glow and **click-to-send-a-payment**. `interactive={false}` for the static mesh. |
12
+ | `<HeroFade />` | Fades the mesh out behind a hero headline so it keeps full contrast. |
13
+ | **Loading** | |
14
+ | `<ActivityBar />`, `track()`, `beginLoading()`, `useBusy()` | One indeterminate bar at the top of the page while any tracked request is in flight — across a shell and all its micro-apps (the counter is framework-free; pass `track` to micro-apps). Fades in only after 150 ms, so quick calls never flash. |
15
+ | `<Loader label mark? />`, `<LoaderMark />` | Block loader: a brand-coloured "signal" mark with a ripple above a label. Pass `mark` to use a brand's own artwork. |
16
+ | `<Spinner label? />` | Inline spinner in the current text colour, e.g. inside a busy button. |
17
+ | `<Skeleton />` | Shimmering placeholder block. |
18
+ | **Feedback** | |
19
+ | `<Toaster />`, `notify()` | Toasts. `notify()` is a framework-free bus, so a micro-app can raise a toast the shell shows. Stays ≥ 5 s, pauses on hover/focus, closable. |
20
+ | `<SuccessCheck />` | Animated success tick. |
21
+ | `<StatusTag tone />` | Status pill — `pending`, `ok`, `danger`, `info`, `neutral`. |
22
+ | `<LiveDot />` | Pulsing live/running indicator. |
23
+ | **Reading** | |
24
+ | `<ReadingProgress />`, `useScrollProgress()` | A thin line that fills as the reader scrolls. |
25
+ | `<EngagementTracker />` | GA4 reading events through the page's existing `gtag`: `scroll_depth`, `section_view`, `tool_interaction`, `read_complete`. A no-op without `gtag`. |
26
+ | **Motion** | |
27
+ | `<MotionToggle />`, `useMotionPaused()`, `setMotionPaused()` | Visible pause/play for ambient animation (WCAG 2.2.2). Persisted per browser; sets `<html data-motion="paused">`. |
28
+ | `MESH_*`, `isHub` | The mesh geometry (fixed seed — same picture every render). |
29
+
30
+ **Accessibility.** Decorative pieces are `aria-hidden` and never intercept
31
+ clicks on links, buttons or form controls. Loaders and toasts are live
32
+ regions. `prefers-reduced-motion` and the motion toggle stop ambient motion;
33
+ pointer effects are off on touch screens. All of it is exercised by the repo's
34
+ browser tests (axe-core WCAG 2.2 AA plus behaviour checks) — see the root README.
35
+
36
+ ## Install
37
+
38
+ ```bash
39
+ npm install @thebankingengineer/design-tokens @thebankingengineer/site-effects
40
+ ```
41
+
42
+ ```css
43
+ /* global stylesheet — one brand theme, then the effects */
44
+ @import '@thebankingengineer/design-tokens/fonts/bbs.css';
45
+ @import '@thebankingengineer/design-tokens/themes/bbs.css';
46
+ @import '@thebankingengineer/design-tokens/effects.css';
47
+ ```
48
+
49
+ ## Use
50
+
51
+ ```tsx
52
+ // Root layout / shell (server-safe; the interactive parts are client islands).
53
+ import { NetworkBackground, ActivityBar, Toaster, MotionToggle } from '@thebankingengineer/site-effects';
54
+
55
+ export default function Layout({ children }: { children: React.ReactNode }) {
56
+ return (
57
+ // dt-effects-root = position: relative; isolation: isolate; overflow-x: clip
58
+ <div className="dt-effects-root" style={{ minHeight: '100vh' }}>
59
+ <NetworkBackground />
60
+ <ActivityBar />
61
+ <Toaster />
62
+ <header>… <MotionToggle /></header>
63
+ {children}
64
+ </div>
65
+ );
66
+ }
67
+ ```
68
+
69
+ ```tsx
70
+ // Anywhere — including a micro-app that received track/notify from the shell.
71
+ import { track, notify, Loader, StatusTag } from '@thebankingengineer/site-effects';
72
+
73
+ const rows = await track(fetch('/api/approvals').then((r) => r.json()));
74
+ notify('Batch approved');
75
+
76
+ {loading ? <Loader label="Loading approvals…" /> : <StatusTag tone="pending">Pending</StatusTag>}
77
+ ```
78
+
79
+ ```tsx
80
+ // A long article
81
+ import { ReadingProgress, EngagementTracker } from '@thebankingengineer/site-effects';
82
+
83
+ <article className="prose">
84
+ <ReadingProgress />
85
+ <EngagementTracker /> {/* measures the <article> it is mounted in */}
86
+ …
87
+ </article>
88
+ ```
89
+
90
+ ## Develop
91
+
92
+ ```bash
93
+ cd site-effects
94
+ npm install
95
+ npm run check # build, exports present, 'use client' kept on client modules only
96
+ ```
97
+
98
+ Releases are staged by the repo's *Stage to npm* workflow — see the root README.
@@ -0,0 +1,10 @@
1
+ /** Mark work as started; call the returned function once when it ends. */
2
+ export declare function beginLoading(): () => void;
3
+ /** Wrap a promise so the activity bar shows while it is pending. */
4
+ export declare function track<T>(work: Promise<T>): Promise<T>;
5
+ /** True while any tracked work is in flight. */
6
+ export declare function useBusy(): boolean;
7
+ /** Render once, near the top of the shell/layout. */
8
+ export declare function ActivityBar({ label }: {
9
+ label?: string;
10
+ }): import("react").JSX.Element;
@@ -0,0 +1,51 @@
1
+ 'use client';
2
+ import { jsx as _jsx } from "react/jsx-runtime";
3
+ /**
4
+ * Activity tracking — one thin indeterminate bar at the top of the page that
5
+ * shows while any tracked work is in flight, across a shell and all of its
6
+ * micro-frontends.
7
+ *
8
+ * The counter is framework-free: hand `track` / `beginLoading` to a
9
+ * micro-frontend (e.g. as a prop or via shared global state) and its requests
10
+ * drive the same bar. The bar fades in only after --activity-delay (150 ms),
11
+ * so quick calls never flash.
12
+ *
13
+ * const data = await track(fetch('/api/approvals').then((r) => r.json()));
14
+ *
15
+ * const end = beginLoading(); // long-lived work
16
+ * … end(); // safe to call more than once
17
+ */
18
+ import { useSyncExternalStore } from 'react';
19
+ let inflight = 0;
20
+ const listeners = new Set();
21
+ const emit = () => listeners.forEach((l) => l());
22
+ /** Mark work as started; call the returned function once when it ends. */
23
+ export function beginLoading() {
24
+ inflight++;
25
+ emit();
26
+ let done = false;
27
+ return () => {
28
+ if (done)
29
+ return;
30
+ done = true;
31
+ inflight--;
32
+ emit();
33
+ };
34
+ }
35
+ /** Wrap a promise so the activity bar shows while it is pending. */
36
+ export function track(work) {
37
+ const end = beginLoading();
38
+ return work.finally(end);
39
+ }
40
+ /** True while any tracked work is in flight. */
41
+ export function useBusy() {
42
+ return useSyncExternalStore((l) => {
43
+ listeners.add(l);
44
+ return () => listeners.delete(l);
45
+ }, () => inflight > 0, () => false);
46
+ }
47
+ /** Render once, near the top of the shell/layout. */
48
+ export function ActivityBar({ label = 'Loading' }) {
49
+ const busy = useBusy();
50
+ return (_jsx("div", { className: busy ? 'dt-activity is-active' : 'dt-activity', role: "progressbar", "aria-label": label, "aria-busy": busy, "aria-hidden": !busy }));
51
+ }
@@ -0,0 +1,6 @@
1
+ declare global {
2
+ interface Window {
3
+ gtag?: (...args: unknown[]) => void;
4
+ }
5
+ }
6
+ export declare function EngagementTracker(): import("react").JSX.Element;
@@ -0,0 +1,138 @@
1
+ 'use client';
2
+ import { jsx as _jsx } from "react/jsx-runtime";
3
+ // Reading-engagement events for GA4, on long content pages.
4
+ //
5
+ // Client island: mount it once inside the <article> you want to measure.
6
+ // It sends four custom events, all through the existing gtag (no new vendor,
7
+ // no new cookies); each carries page_path so reports can split by page:
8
+ //
9
+ // scroll_depth percent_scrolled 25 | 50 | 75 | 100, of the article (not
10
+ // the whole document), once each per page view
11
+ // section_view section_id, section_title, engaged_seconds — time spent
12
+ // reading each h2 section, sent when the reader moves on
13
+ // (≥ MIN_SECTION_SECONDS) or leaves the page
14
+ // tool_interaction tool_name — first use of each data-toc chart/tool
15
+ // read_complete reading_seconds, expected_seconds — reached the end of
16
+ // the article after at least half the expected reading
17
+ // time (words ÷ 230 wpm), i.e. read rather than skimmed
18
+ //
19
+ // Time only counts while the tab is visible. Internal (author) devices are
20
+ // best tagged traffic_type=internal by the host app via gtag('set'), so these
21
+ // events are filtered the same way. With no gtag
22
+ // (local dev, ad blockers) everything is a no-op.
23
+ import { useEffect, useRef } from 'react';
24
+ const DEPTHS = [25, 50, 75, 100];
25
+ const MIN_SECTION_SECONDS = 5;
26
+ const WPM = 230;
27
+ const TICK_MS = 1000;
28
+ function send(name, params, beacon = false) {
29
+ window.gtag?.('event', name, {
30
+ page_path: window.location.pathname,
31
+ ...params,
32
+ ...(beacon ? { transport_type: 'beacon' } : {}),
33
+ });
34
+ }
35
+ export function EngagementTracker() {
36
+ const marker = useRef(null);
37
+ useEffect(() => {
38
+ const article = marker.current?.closest('article');
39
+ if (!article || typeof window.gtag !== 'function')
40
+ return;
41
+ const sections = Array.from(article.querySelectorAll(':scope > h2[id]'));
42
+ const words = (article.innerText || '').split(/\s+/).filter(Boolean).length;
43
+ const expectedSeconds = Math.round((words / WPM) * 60);
44
+ const sentDepth = new Set();
45
+ const sentTools = new Set();
46
+ const dwell = new Map(); // seconds per section, this page view
47
+ let engaged = 0; // visible seconds on the page
48
+ let current = null;
49
+ let readSent = false;
50
+ const title = (el) => (el.textContent ?? '').replace(/#$/, '').trim();
51
+ const flushSection = (el, beacon = false) => {
52
+ if (!el)
53
+ return;
54
+ const secs = dwell.get(el.id) ?? 0;
55
+ if (secs >= MIN_SECTION_SECONDS) {
56
+ send('section_view', { section_id: el.id, section_title: title(el), engaged_seconds: secs }, beacon);
57
+ }
58
+ dwell.set(el.id, 0); // a later return to the section is counted afresh
59
+ };
60
+ // The section being read: the last h2 whose top is above 30% of the viewport.
61
+ const sectionInView = () => {
62
+ const line = window.innerHeight * 0.3;
63
+ let found = null;
64
+ for (const s of sections) {
65
+ if (s.getBoundingClientRect().top <= line)
66
+ found = s;
67
+ else
68
+ break;
69
+ }
70
+ return found;
71
+ };
72
+ const articleProgress = () => {
73
+ const r = article.getBoundingClientRect();
74
+ const seen = window.innerHeight - r.top;
75
+ return r.height > 0 ? Math.max(0, Math.min(100, (seen / r.height) * 100)) : 0;
76
+ };
77
+ const onScroll = () => {
78
+ const pct = articleProgress();
79
+ for (const d of DEPTHS) {
80
+ if (pct >= d && !sentDepth.has(d)) {
81
+ sentDepth.add(d);
82
+ send('scroll_depth', { percent_scrolled: d });
83
+ }
84
+ }
85
+ const s = sectionInView();
86
+ if (s !== current) {
87
+ flushSection(current);
88
+ current = s;
89
+ }
90
+ if (!readSent && sentDepth.has(100) && engaged >= expectedSeconds * 0.5) {
91
+ readSent = true;
92
+ send('read_complete', { reading_seconds: engaged, expected_seconds: expectedSeconds });
93
+ }
94
+ };
95
+ // Visible-time clock.
96
+ const tick = window.setInterval(() => {
97
+ if (document.visibilityState !== 'visible')
98
+ return;
99
+ engaged += 1;
100
+ if (current)
101
+ dwell.set(current.id, (dwell.get(current.id) ?? 0) + 1);
102
+ onScroll(); // re-check read_complete as time passes at the end
103
+ }, TICK_MS);
104
+ // First interaction with each chart/tool.
105
+ const onInteract = (e) => {
106
+ const tool = e.target?.closest('[data-toc]');
107
+ const name = tool?.dataset.toc;
108
+ if (!name || sentTools.has(name))
109
+ return;
110
+ sentTools.add(name);
111
+ send('tool_interaction', { tool_name: name });
112
+ };
113
+ // Leaving: send the section being read before the page goes away.
114
+ const onHide = () => {
115
+ if (document.visibilityState === 'hidden')
116
+ flushSection(current, true);
117
+ };
118
+ const onPageHide = () => flushSection(current, true);
119
+ onScroll();
120
+ window.addEventListener('scroll', onScroll, { passive: true });
121
+ article.addEventListener('pointerdown', onInteract);
122
+ article.addEventListener('keydown', onInteract);
123
+ article.addEventListener('input', onInteract);
124
+ document.addEventListener('visibilitychange', onHide);
125
+ window.addEventListener('pagehide', onPageHide);
126
+ return () => {
127
+ flushSection(current); // client-side navigation away
128
+ window.clearInterval(tick);
129
+ window.removeEventListener('scroll', onScroll);
130
+ article.removeEventListener('pointerdown', onInteract);
131
+ article.removeEventListener('keydown', onInteract);
132
+ article.removeEventListener('input', onInteract);
133
+ document.removeEventListener('visibilitychange', onHide);
134
+ window.removeEventListener('pagehide', onPageHide);
135
+ };
136
+ }, []);
137
+ return _jsx("span", { ref: marker, hidden: true });
138
+ }
@@ -0,0 +1,24 @@
1
+ /**
2
+ * @thebankingengineer/site-effects — shared motion, loading and feedback
3
+ * components for React apps and micro-frontends built on
4
+ * @thebankingengineer/design-tokens.
5
+ *
6
+ * Requires the CSS from @thebankingengineer/design-tokens:
7
+ * @import '@thebankingengineer/design-tokens/themes/<brand>.css';
8
+ * @import '@thebankingengineer/design-tokens/effects.css';
9
+ */
10
+ export { NetworkBackground, HeroFade } from './network-background.js';
11
+ export type { NetworkBackgroundProps } from './network-background.js';
12
+ export { NetworkInteractions } from './network-interactions.js';
13
+ export { ReadingProgress, useScrollProgress } from './reading-progress.js';
14
+ export type { ReadingProgressProps, ScrollState } from './reading-progress.js';
15
+ export { EngagementTracker } from './engagement-tracker.js';
16
+ export { ActivityBar, beginLoading, track, useBusy } from './activity.js';
17
+ export { Spinner, LoaderMark, Loader, Skeleton, SuccessCheck, StatusTag, LiveDot } from './loaders.js';
18
+ export type { LoaderProps, StatusTone } from './loaders.js';
19
+ export { Toaster, notify, onToast } from './toast.js';
20
+ export type { ToasterProps, ToastMessage, ToastTone } from './toast.js';
21
+ export { MotionToggle, useMotionPaused, isMotionPaused, setMotionPaused, subscribeMotion } from './motion.js';
22
+ export type { MotionToggleProps } from './motion.js';
23
+ export { MESH_W, MESH_H, MESH_NODES, MESH_LINKS, MESH_PULSES, isHub } from './mesh.js';
24
+ export type { MeshNode, MeshLink } from './mesh.js';
package/dist/index.js ADDED
@@ -0,0 +1,18 @@
1
+ /**
2
+ * @thebankingengineer/site-effects — shared motion, loading and feedback
3
+ * components for React apps and micro-frontends built on
4
+ * @thebankingengineer/design-tokens.
5
+ *
6
+ * Requires the CSS from @thebankingengineer/design-tokens:
7
+ * @import '@thebankingengineer/design-tokens/themes/<brand>.css';
8
+ * @import '@thebankingengineer/design-tokens/effects.css';
9
+ */
10
+ export { NetworkBackground, HeroFade } from './network-background.js';
11
+ export { NetworkInteractions } from './network-interactions.js';
12
+ export { ReadingProgress, useScrollProgress } from './reading-progress.js';
13
+ export { EngagementTracker } from './engagement-tracker.js';
14
+ export { ActivityBar, beginLoading, track, useBusy } from './activity.js';
15
+ export { Spinner, LoaderMark, Loader, Skeleton, SuccessCheck, StatusTag, LiveDot } from './loaders.js';
16
+ export { Toaster, notify, onToast } from './toast.js';
17
+ export { MotionToggle, useMotionPaused, isMotionPaused, setMotionPaused, subscribeMotion } from './motion.js';
18
+ export { MESH_W, MESH_H, MESH_NODES, MESH_LINKS, MESH_PULSES, isHub } from './mesh.js';
@@ -0,0 +1,38 @@
1
+ /**
2
+ * Loaders and status visuals — server-safe (no hooks). Styled by effects.css;
3
+ * colours come from the active brand theme.
4
+ */
5
+ import type { ReactNode } from 'react';
6
+ /** Inline spinner (1em, current text colour) — e.g. inside a busy button. */
7
+ export declare function Spinner({ label }: {
8
+ label?: string;
9
+ }): import("react").JSX.Element;
10
+ /** The default loader mark: a tiny settlement network with a payment pulse travelling across it. */
11
+ export declare function LoaderMark({ small }: {
12
+ small?: boolean;
13
+ }): import("react").JSX.Element;
14
+ export type LoaderProps = {
15
+ /** Short, visible description of what is loading — also announced. */
16
+ label: string;
17
+ /** A brand's own mark in place of the default <LoaderMark />. */
18
+ mark?: ReactNode;
19
+ };
20
+ /** Block loader: a mark above a label, announced politely to screen readers. */
21
+ export declare function Loader({ label, mark }: LoaderProps): import("react").JSX.Element;
22
+ /** Placeholder block while content loads. Size it with style/className. */
23
+ export declare function Skeleton({ className, style }: {
24
+ className?: string;
25
+ style?: React.CSSProperties;
26
+ }): import("react").JSX.Element;
27
+ /** Animated success tick — e.g. after an approval or sign-in completes. */
28
+ export declare function SuccessCheck({ size }: {
29
+ size?: number;
30
+ }): import("react").JSX.Element;
31
+ export type StatusTone = 'pending' | 'ok' | 'danger' | 'info' | 'neutral';
32
+ /** Status pill with a leading dot. The text carries the meaning, not the colour. */
33
+ export declare function StatusTag({ tone, children }: {
34
+ tone?: StatusTone;
35
+ children: ReactNode;
36
+ }): import("react").JSX.Element;
37
+ /** Pulsing "live / running" indicator. Pair it with visible text. */
38
+ export declare function LiveDot(): import("react").JSX.Element;
@@ -0,0 +1,42 @@
1
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ /** Inline spinner (1em, current text colour) — e.g. inside a busy button. */
3
+ export function Spinner({ label }) {
4
+ return label ? (_jsxs("span", { role: "status", children: [_jsx("span", { className: "dt-spinner", "aria-hidden": "true" }), _jsx("span", { className: "dt-sr-only", children: label })] })) : (_jsx("span", { className: "dt-spinner", "aria-hidden": "true" }));
5
+ }
6
+ // Mark geometry (48 × 48): a small network and the route the pulse travels.
7
+ const NODES = [[7, 34], [18, 12], [33, 22], [42, 40], [20, 42]];
8
+ const LINKS = [[0, 1], [1, 2], [2, 3], [3, 4], [4, 0], [1, 4], [2, 4]];
9
+ const ROUTE = [0, 1, 2, 3]; // A → B → C → D
10
+ const HUB = 2;
11
+ const CYCLE = 1.6; // seconds — keep in step with dt-route in effects.css
12
+ // Each route node lights as the pulse head reaches it: delay = its share of the
13
+ // route length × the cycle, minus the lead-in of the dt-node-lit keyframes.
14
+ const SEGMENTS = ROUTE.slice(1).map((n, i) => Math.hypot(NODES[n][0] - NODES[ROUTE[i]][0], NODES[n][1] - NODES[ROUTE[i]][1]));
15
+ const TOTAL = SEGMENTS.reduce((a, b) => a + b, 0);
16
+ const LIT_DELAY = ROUTE.map((_, i) => SEGMENTS.slice(0, i).reduce((a, b) => a + b, 0) / TOTAL * CYCLE - 0.25);
17
+ /** The default loader mark: a tiny settlement network with a payment pulse travelling across it. */
18
+ export function LoaderMark({ small = false }) {
19
+ const size = small ? 28 : 48;
20
+ const route = ROUTE.map((n, i) => `${i ? 'L' : 'M'} ${NODES[n][0]} ${NODES[n][1]}`).join(' ');
21
+ return (_jsxs("svg", { className: "dt-loader-mark", width: size, height: size, viewBox: "0 0 48 48", "aria-hidden": "true", focusable: "false", children: [_jsx("g", { className: "dt-loader-mark__links", children: LINKS.map(([a, b], i) => (_jsx("line", { x1: NODES[a][0], y1: NODES[a][1], x2: NODES[b][0], y2: NODES[b][1] }, i))) }), _jsx("path", { className: "dt-loader-mark__pulse", d: route, pathLength: 100 }), _jsxs("g", { children: [ROUTE.map((n, i) => (_jsx("circle", { style: { animationDelay: `${LIT_DELAY[i].toFixed(2)}s` }, className: `dt-loader-mark__node dt-loader-mark__node--lit${n === HUB ? ' dt-loader-mark__node--hub' : ''}`, cx: NODES[n][0], cy: NODES[n][1], r: n === HUB ? 4.5 : 3.5 }, n))), _jsx("circle", { className: "dt-loader-mark__node", cx: NODES[4][0], cy: NODES[4][1], r: 3 })] })] }));
22
+ }
23
+ /** Block loader: a mark above a label, announced politely to screen readers. */
24
+ export function Loader({ label, mark }) {
25
+ return (_jsxs("div", { className: "dt-loader", role: "status", "aria-live": "polite", children: [mark ?? _jsx(LoaderMark, {}), _jsx("span", { children: label })] }));
26
+ }
27
+ /** Placeholder block while content loads. Size it with style/className. */
28
+ export function Skeleton({ className, style }) {
29
+ return _jsx("span", { "aria-hidden": "true", className: className ? `dt-skeleton ${className}` : 'dt-skeleton', style: style });
30
+ }
31
+ /** Animated success tick — e.g. after an approval or sign-in completes. */
32
+ export function SuccessCheck({ size = 42 }) {
33
+ return (_jsx("div", { className: "dt-check", "aria-hidden": "true", children: _jsx("svg", { width: size, height: size, viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: 2.5, strokeLinecap: "round", strokeLinejoin: "round", children: _jsx("path", { d: "M5 12.5l4.5 4.5L19 7.5" }) }) }));
34
+ }
35
+ /** Status pill with a leading dot. The text carries the meaning, not the colour. */
36
+ export function StatusTag({ tone = 'neutral', children }) {
37
+ return _jsx("span", { className: tone === 'neutral' ? 'dt-tag' : `dt-tag dt-tag--${tone}`, children: children });
38
+ }
39
+ /** Pulsing "live / running" indicator. Pair it with visible text. */
40
+ export function LiveDot() {
41
+ return _jsx("span", { className: "dt-live-dot", "aria-hidden": "true" });
42
+ }
package/dist/mesh.d.ts ADDED
@@ -0,0 +1,25 @@
1
+ /**
2
+ * Geometry for the home-page settlement-network background.
3
+ *
4
+ * Shared by the static SVG (network-background.tsx, server-safe) and the
5
+ * pointer interactions (network-interactions.tsx, client), so both
6
+ * draw from exactly the same nodes and links. Generated from a fixed seed: the
7
+ * same mesh on every build, render and visual-regression run.
8
+ *
9
+ * Coordinates are CSS pixels inside a MESH_W x MESH_H box; the SVGs are drawn
10
+ * at that size (no scaling), centred in the viewport. The background is fixed
11
+ * to the viewport, so the box only has to cover the tallest screen.
12
+ */
13
+ export declare const MESH_W = 1920;
14
+ export declare const MESH_H = 2400;
15
+ export type MeshNode = {
16
+ x: number;
17
+ y: number;
18
+ };
19
+ /** A link joins two node indexes. */
20
+ export type MeshLink = [number, number];
21
+ export declare const MESH_NODES: MeshNode[], MESH_LINKS: MeshLink[];
22
+ /** Every fifth link carries an ambient pulse. */
23
+ export declare const MESH_PULSES: MeshLink[];
24
+ /** Larger "hub" nodes. */
25
+ export declare const isHub: (i: number) => boolean;
package/dist/mesh.js ADDED
@@ -0,0 +1,69 @@
1
+ /**
2
+ * Geometry for the home-page settlement-network background.
3
+ *
4
+ * Shared by the static SVG (network-background.tsx, server-safe) and the
5
+ * pointer interactions (network-interactions.tsx, client), so both
6
+ * draw from exactly the same nodes and links. Generated from a fixed seed: the
7
+ * same mesh on every build, render and visual-regression run.
8
+ *
9
+ * Coordinates are CSS pixels inside a MESH_W x MESH_H box; the SVGs are drawn
10
+ * at that size (no scaling), centred in the viewport. The background is fixed
11
+ * to the viewport, so the box only has to cover the tallest screen.
12
+ */
13
+ export const MESH_W = 1920;
14
+ export const MESH_H = 2400;
15
+ const STEP_X = 146;
16
+ const STEP_Y = 130;
17
+ const COLS = Math.ceil(MESH_W / STEP_X);
18
+ const ROWS = Math.ceil(MESH_H / STEP_Y);
19
+ function build() {
20
+ // Small deterministic LCG.
21
+ let seed = 7;
22
+ const rand = () => {
23
+ seed = (seed * 1664525 + 1013904223) % 4294967296;
24
+ return seed / 4294967296;
25
+ };
26
+ const nodes = [];
27
+ for (let r = 0; r < ROWS; r++) {
28
+ for (let c = 0; c < COLS; c++) {
29
+ nodes.push({
30
+ x: Math.round(40 + c * STEP_X + (rand() - 0.5) * 80),
31
+ y: Math.round(40 + r * STEP_Y + (rand() - 0.5) * 70),
32
+ });
33
+ }
34
+ }
35
+ // Join each node to its two nearest neighbours; only nearby grid cells can
36
+ // be nearest, so search the surrounding 5x5 block. De-duplicate pairs.
37
+ const seen = new Set();
38
+ const links = [];
39
+ nodes.forEach((a, i) => {
40
+ const r0 = Math.floor(i / COLS);
41
+ const c0 = i % COLS;
42
+ const near = [];
43
+ for (let r = Math.max(0, r0 - 2); r <= Math.min(ROWS - 1, r0 + 2); r++) {
44
+ for (let c = Math.max(0, c0 - 2); c <= Math.min(COLS - 1, c0 + 2); c++) {
45
+ const j = r * COLS + c;
46
+ if (j !== i) {
47
+ const b = nodes[j];
48
+ near.push({ j, d: (b.x - a.x) ** 2 + (b.y - a.y) ** 2 });
49
+ }
50
+ }
51
+ }
52
+ near
53
+ .sort((p, q) => p.d - q.d)
54
+ .slice(0, 2)
55
+ .forEach(({ j }) => {
56
+ const key = i < j ? `${i}-${j}` : `${j}-${i}`;
57
+ if (!seen.has(key)) {
58
+ seen.add(key);
59
+ links.push([i, j]);
60
+ }
61
+ });
62
+ });
63
+ return { nodes, links };
64
+ }
65
+ export const { nodes: MESH_NODES, links: MESH_LINKS } = build();
66
+ /** Every fifth link carries an ambient pulse. */
67
+ export const MESH_PULSES = MESH_LINKS.filter((_, i) => i % 5 === 0);
68
+ /** Larger "hub" nodes. */
69
+ export const isHub = (i) => i % 5 === 0;
@@ -0,0 +1,13 @@
1
+ export declare function isMotionPaused(): boolean;
2
+ export declare function setMotionPaused(next: boolean): void;
3
+ export declare function subscribeMotion(listener: () => void): () => void;
4
+ /** True while the reader has paused ambient motion. */
5
+ export declare function useMotionPaused(): boolean;
6
+ export type MotionToggleProps = {
7
+ className?: string;
8
+ /** Visible labels; the button's accessible name follows the current state. */
9
+ pauseLabel?: string;
10
+ playLabel?: string;
11
+ };
12
+ /** Pause / play ambient motion. Place it somewhere persistent (header, footer). */
13
+ export declare function MotionToggle({ className, pauseLabel, playLabel }: MotionToggleProps): import("react").JSX.Element;
package/dist/motion.js ADDED
@@ -0,0 +1,68 @@
1
+ 'use client';
2
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
3
+ /**
4
+ * Ambient-motion preference — a visible pause control for WCAG 2.2.2 (Pause,
5
+ * Stop, Hide), on top of the OS-level prefers-reduced-motion.
6
+ *
7
+ * The choice is stored per browser and mirrored onto
8
+ * `<html data-motion="paused">`, which effects.css uses to stop ambient
9
+ * animation (network pulses, live dots, skeleton shimmer). The network
10
+ * background's pointer effects also switch off while paused. Loaders keep
11
+ * running: they report work in progress rather than decorate.
12
+ *
13
+ * Framework-free store underneath, so a micro-frontend shell can share it.
14
+ */
15
+ import { useSyncExternalStore } from 'react';
16
+ const KEY = 'dt-motion';
17
+ const listeners = new Set();
18
+ let paused = null;
19
+ function read() {
20
+ if (paused !== null)
21
+ return paused;
22
+ try {
23
+ paused = window.localStorage.getItem(KEY) === 'paused';
24
+ }
25
+ catch {
26
+ paused = false; // storage blocked (privacy mode, sandboxed frame)
27
+ }
28
+ apply();
29
+ return paused;
30
+ }
31
+ function apply() {
32
+ if (typeof document === 'undefined')
33
+ return;
34
+ if (paused)
35
+ document.documentElement.dataset.motion = 'paused';
36
+ else
37
+ delete document.documentElement.dataset.motion;
38
+ }
39
+ export function isMotionPaused() {
40
+ return typeof window === 'undefined' ? false : read();
41
+ }
42
+ export function setMotionPaused(next) {
43
+ paused = next;
44
+ try {
45
+ if (next)
46
+ window.localStorage.setItem(KEY, 'paused');
47
+ else
48
+ window.localStorage.removeItem(KEY);
49
+ }
50
+ catch {
51
+ /* keep the in-memory choice for this page view */
52
+ }
53
+ apply();
54
+ listeners.forEach((l) => l());
55
+ }
56
+ export function subscribeMotion(listener) {
57
+ listeners.add(listener);
58
+ return () => listeners.delete(listener);
59
+ }
60
+ /** True while the reader has paused ambient motion. */
61
+ export function useMotionPaused() {
62
+ return useSyncExternalStore(subscribeMotion, isMotionPaused, () => false);
63
+ }
64
+ /** Pause / play ambient motion. Place it somewhere persistent (header, footer). */
65
+ export function MotionToggle({ className, pauseLabel = 'Pause animation', playLabel = 'Play animation' }) {
66
+ const isPaused = useMotionPaused();
67
+ return (_jsxs("button", { type: "button", className: className ? `dt-motion-toggle ${className}` : 'dt-motion-toggle', "aria-pressed": isPaused, onClick: () => setMotionPaused(!isPaused), children: [_jsx("svg", { width: "12", height: "12", viewBox: "0 0 12 12", "aria-hidden": "true", focusable: "false", children: isPaused ? _jsx("path", { d: "M3 1.5v9l7.5-4.5z", fill: "currentColor" }) : _jsx("path", { d: "M2.5 1.5h2.5v9H2.5zM7 1.5h2.5v9H7z", fill: "currentColor" }) }), _jsx("span", { children: isPaused ? playLabel : pauseLabel })] }));
68
+ }
@@ -0,0 +1,31 @@
1
+ /**
2
+ * NetworkBackground — an app-wide decorative "settlement network" background,
3
+ * fixed to the viewport behind the page content. Render it once per layout.
4
+ *
5
+ * A faint mesh of nodes (banks, rails) joined by links, with short pulses
6
+ * travelling along some links like payments clearing. The mesh is static SVG
7
+ * (server-safe: no hooks), geometry from ./mesh (fixed seed, same picture on
8
+ * every render). All colours, opacities and washes come from the design-token
9
+ * CSS variables via effects.css, so it follows light/dark automatically.
10
+ * Ambient pulses stop under `prefers-reduced-motion`.
11
+ *
12
+ * <NetworkInteractions /> (client island) adds the pointer effects — hover glow
13
+ * and click-to-send-a-payment — on fine pointers only. Pass
14
+ * `interactive={false}` to render the static mesh alone.
15
+ *
16
+ * Requires tokens.css + effects.css from @thebankingengineer/design-tokens.
17
+ * Stacking: the layout root must be `relative isolate` (position: relative;
18
+ * isolation: isolate) so this z-index -10 layer paints above the root's own
19
+ * background but below everything else.
20
+ */
21
+ export type NetworkBackgroundProps = {
22
+ /** Hover glow + click-to-send-a-payment. Default true. */
23
+ interactive?: boolean;
24
+ };
25
+ export declare function NetworkBackground({ interactive }: NetworkBackgroundProps): import("react").JSX.Element;
26
+ /**
27
+ * HeroFade — fades the background out behind a hero headline so the text keeps
28
+ * full contrast while the mesh stays visible on the right. Place it as the
29
+ * first child of a `position: relative` (not isolated) wrapper.
30
+ */
31
+ export declare function HeroFade(): import("react").JSX.Element;
@@ -0,0 +1,37 @@
1
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ /**
3
+ * NetworkBackground — an app-wide decorative "settlement network" background,
4
+ * fixed to the viewport behind the page content. Render it once per layout.
5
+ *
6
+ * A faint mesh of nodes (banks, rails) joined by links, with short pulses
7
+ * travelling along some links like payments clearing. The mesh is static SVG
8
+ * (server-safe: no hooks), geometry from ./mesh (fixed seed, same picture on
9
+ * every render). All colours, opacities and washes come from the design-token
10
+ * CSS variables via effects.css, so it follows light/dark automatically.
11
+ * Ambient pulses stop under `prefers-reduced-motion`.
12
+ *
13
+ * <NetworkInteractions /> (client island) adds the pointer effects — hover glow
14
+ * and click-to-send-a-payment — on fine pointers only. Pass
15
+ * `interactive={false}` to render the static mesh alone.
16
+ *
17
+ * Requires tokens.css + effects.css from @thebankingengineer/design-tokens.
18
+ * Stacking: the layout root must be `relative isolate` (position: relative;
19
+ * isolation: isolate) so this z-index -10 layer paints above the root's own
20
+ * background but below everything else.
21
+ */
22
+ import { MESH_H, MESH_LINKS, MESH_NODES, MESH_PULSES, MESH_W, isHub } from './mesh.js';
23
+ import { NetworkInteractions } from './network-interactions.js';
24
+ export function NetworkBackground({ interactive = true }) {
25
+ return (_jsxs("div", { "aria-hidden": "true", className: "dt-mesh", children: [_jsxs("svg", { className: "dt-mesh__layer", width: MESH_W, height: MESH_H, viewBox: `0 0 ${MESH_W} ${MESH_H}`, focusable: "false", children: [_jsx("g", { className: "dt-mesh__links", children: MESH_LINKS.map(([a, b], i) => (_jsx("line", { x1: MESH_NODES[a].x, y1: MESH_NODES[a].y, x2: MESH_NODES[b].x, y2: MESH_NODES[b].y }, i))) }), _jsx("g", { className: "dt-mesh__pulses", children: MESH_PULSES.map(([a, b], i) => (_jsx("path", { className: "dt-mesh__pulse", d: `M ${MESH_NODES[a].x} ${MESH_NODES[a].y} L ${MESH_NODES[b].x} ${MESH_NODES[b].y}`, pathLength: 100, style: {
26
+ animationDelay: `-${((i * 1.37) % 7).toFixed(2)}s`,
27
+ animationDuration: `${5 + (i % 4) * 1.5}s`,
28
+ } }, i))) }), _jsx("g", { className: "dt-mesh__nodes", children: MESH_NODES.map((n, i) => (_jsx("circle", { cx: n.x, cy: n.y, r: isHub(i) ? 4 : 2.5 }, i))) })] }), interactive && _jsx(NetworkInteractions, {}), _jsx("div", { className: "dt-mesh__wash" }), _jsx("div", { className: "dt-mesh__wash dt-mesh__wash--narrow" })] }));
29
+ }
30
+ /**
31
+ * HeroFade — fades the background out behind a hero headline so the text keeps
32
+ * full contrast while the mesh stays visible on the right. Place it as the
33
+ * first child of a `position: relative` (not isolated) wrapper.
34
+ */
35
+ export function HeroFade() {
36
+ return _jsx("div", { "aria-hidden": "true", className: "dt-hero-fade" });
37
+ }
@@ -0,0 +1 @@
1
+ export declare function NetworkInteractions(): import("react").JSX.Element | null;
@@ -0,0 +1,194 @@
1
+ 'use client';
2
+ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
3
+ /**
4
+ * NetworkInteractions — pointer effects for the home-page settlement network
5
+ * (network-background.tsx). Two effects:
6
+ *
7
+ * 1. Hover glow: links and nodes near the pointer brighten. A brighter copy of
8
+ * the mesh sits over the base one and is masked to a soft circle at the
9
+ * pointer, moved with CSS vars (no React re-render per move).
10
+ * 2. Click to send a payment: a click on empty page space sends a pulse from
11
+ * the nearest node across a few links, with a ring at each end.
12
+ *
13
+ * Decorative only (aria-hidden, pointer-events: none): clicks on links,
14
+ * buttons and form controls are ignored here and behave as normal. Enabled
15
+ * only for a fine pointer (mouse/trackpad) and when reduced motion is off; on
16
+ * touch screens and under reduced motion nothing is rendered, so the
17
+ * background stays exactly the static SVG. They also switch off while the
18
+ * reader has paused ambient motion (<MotionToggle />).
19
+ */
20
+ import { useEffect, useRef, useState } from 'react';
21
+ import { MESH_H, MESH_LINKS, MESH_NODES, MESH_W, isHub } from './mesh.js';
22
+ import { useMotionPaused } from './motion.js';
23
+ const SVG_NS = 'http://www.w3.org/2000/svg';
24
+ const HOPS = 4;
25
+ const MAX_LIVE_EFFECTS = 40;
26
+ const INTERACTIVE = 'a, button, input, textarea, select, label, summary, [role="button"], [contenteditable="true"]';
27
+ let adjacency = null;
28
+ function neighbours(i) {
29
+ if (!adjacency) {
30
+ adjacency = MESH_NODES.map(() => []);
31
+ for (const [a, b] of MESH_LINKS) {
32
+ adjacency[a].push(b);
33
+ adjacency[b].push(a);
34
+ }
35
+ }
36
+ return adjacency[i];
37
+ }
38
+ function nearestNode(x, y) {
39
+ let best = 0;
40
+ let bestD = Infinity;
41
+ MESH_NODES.forEach((n, i) => {
42
+ const d = (n.x - x) ** 2 + (n.y - y) ** 2;
43
+ if (d < bestD) {
44
+ bestD = d;
45
+ best = i;
46
+ }
47
+ });
48
+ return best;
49
+ }
50
+ /** A random walk of up to HOPS links that never revisits a node. */
51
+ function route(start) {
52
+ const path = [start];
53
+ const seen = new Set(path);
54
+ for (let h = 0; h < HOPS; h++) {
55
+ const next = neighbours(path[path.length - 1]).filter((n) => !seen.has(n));
56
+ if (next.length === 0)
57
+ break;
58
+ const pick = next[Math.floor(Math.random() * next.length)];
59
+ path.push(pick);
60
+ seen.add(pick);
61
+ }
62
+ return path;
63
+ }
64
+ const fineNoMotionPref = '(pointer: fine) and (prefers-reduced-motion: no-preference)';
65
+ export function NetworkInteractions() {
66
+ const [capable, setCapable] = useState(false);
67
+ const paused = useMotionPaused();
68
+ const enabled = capable && !paused;
69
+ const glowRef = useRef(null);
70
+ const fxRef = useRef(null);
71
+ useEffect(() => {
72
+ const mq = window.matchMedia(fineNoMotionPref);
73
+ const sync = () => setCapable(mq.matches);
74
+ sync();
75
+ mq.addEventListener('change', sync);
76
+ return () => mq.removeEventListener('change', sync);
77
+ }, []);
78
+ useEffect(() => {
79
+ if (!enabled)
80
+ return;
81
+ const glow = glowRef.current;
82
+ const fx = fxRef.current;
83
+ if (!glow || !fx)
84
+ return;
85
+ let frame = 0;
86
+ let px = 0;
87
+ let py = 0;
88
+ const paint = () => {
89
+ frame = 0;
90
+ const r = glow.getBoundingClientRect();
91
+ glow.style.setProperty('--mx', `${px - r.left}px`);
92
+ glow.style.setProperty('--my', `${py - r.top}px`);
93
+ glow.style.opacity = '1';
94
+ };
95
+ const onMove = (e) => {
96
+ if (e.pointerType !== 'mouse' && e.pointerType !== 'pen')
97
+ return;
98
+ px = e.clientX;
99
+ py = e.clientY;
100
+ if (!frame)
101
+ frame = requestAnimationFrame(paint);
102
+ };
103
+ const onLeave = (e) => {
104
+ if (!e.relatedTarget)
105
+ glow.style.opacity = '0';
106
+ };
107
+ const ring = (x, y, delay) => {
108
+ const c = document.createElementNS(SVG_NS, 'circle');
109
+ c.setAttribute('cx', String(x));
110
+ c.setAttribute('cy', String(y));
111
+ c.setAttribute('r', '4');
112
+ c.setAttribute('fill', 'none');
113
+ c.setAttribute('stroke', 'var(--mesh-color)');
114
+ c.setAttribute('stroke-width', '2');
115
+ c.setAttribute('vector-effect', 'non-scaling-stroke');
116
+ c.style.opacity = '0';
117
+ c.style.transformBox = 'fill-box';
118
+ c.style.transformOrigin = 'center';
119
+ fx.appendChild(c);
120
+ c.animate([
121
+ { transform: 'scale(1)', opacity: 0.9 },
122
+ { transform: 'scale(5.5)', opacity: 0 },
123
+ ], { duration: 900, delay, easing: 'ease-out', fill: 'both' }).finished.then(() => c.remove(), () => c.remove());
124
+ };
125
+ const onClick = (e) => {
126
+ if (e.button !== 0)
127
+ return;
128
+ if (e.target?.closest?.(INTERACTIVE))
129
+ return;
130
+ if (window.getSelection()?.toString())
131
+ return;
132
+ if (fx.childElementCount > MAX_LIVE_EFFECTS)
133
+ return;
134
+ const r = glow.getBoundingClientRect();
135
+ const x = e.clientX - r.left;
136
+ const y = e.clientY - r.top;
137
+ if (x < 0 || y < 0 || x > r.width || y > r.height)
138
+ return;
139
+ const hops = route(nearestNode(x, y));
140
+ if (hops.length < 2)
141
+ return;
142
+ const pts = hops.map((i) => MESH_NODES[i]);
143
+ const travel = 350 * (hops.length - 1);
144
+ // Settled links: briefly lit along the whole route.
145
+ const trail = document.createElementNS(SVG_NS, 'path');
146
+ trail.setAttribute('d', pts.map((p, k) => `${k ? 'L' : 'M'} ${p.x} ${p.y}`).join(' '));
147
+ trail.setAttribute('fill', 'none');
148
+ trail.setAttribute('stroke', 'var(--mesh-color)');
149
+ trail.setAttribute('stroke-width', '1.5');
150
+ trail.setAttribute('stroke-linejoin', 'round');
151
+ fx.appendChild(trail);
152
+ trail
153
+ .animate([{ opacity: 0 }, { opacity: 0.45, offset: 0.2 }, { opacity: 0 }], {
154
+ duration: travel + 900,
155
+ easing: 'ease-out',
156
+ })
157
+ .finished.then(() => trail.remove(), () => trail.remove());
158
+ // The payment itself: a short dash travelling the route.
159
+ const pulse = document.createElementNS(SVG_NS, 'path');
160
+ pulse.setAttribute('d', trail.getAttribute('d') ?? '');
161
+ pulse.setAttribute('pathLength', '100');
162
+ pulse.setAttribute('fill', 'none');
163
+ pulse.setAttribute('stroke', 'var(--mesh-color)');
164
+ pulse.setAttribute('stroke-width', '3');
165
+ pulse.setAttribute('stroke-linecap', 'round');
166
+ pulse.setAttribute('stroke-linejoin', 'round');
167
+ pulse.style.strokeDasharray = '12 200';
168
+ fx.appendChild(pulse);
169
+ pulse
170
+ .animate([{ strokeDashoffset: 12 }, { strokeDashoffset: -100 }], {
171
+ duration: travel,
172
+ easing: 'cubic-bezier(.4,0,.2,1)',
173
+ fill: 'both',
174
+ })
175
+ .finished.then(() => pulse.remove(), () => pulse.remove());
176
+ ring(pts[0].x, pts[0].y, 0);
177
+ ring(pts[pts.length - 1].x, pts[pts.length - 1].y, travel - 150);
178
+ };
179
+ window.addEventListener('pointermove', onMove, { passive: true });
180
+ document.addEventListener('mouseout', onLeave);
181
+ window.addEventListener('click', onClick);
182
+ return () => {
183
+ if (frame)
184
+ cancelAnimationFrame(frame);
185
+ window.removeEventListener('pointermove', onMove);
186
+ document.removeEventListener('mouseout', onLeave);
187
+ window.removeEventListener('click', onClick);
188
+ fx.replaceChildren();
189
+ };
190
+ }, [enabled]);
191
+ if (!enabled)
192
+ return null;
193
+ return (_jsxs(_Fragment, { children: [_jsxs("svg", { ref: glowRef, className: "dt-mesh__layer dt-mesh__glow", width: MESH_W, height: MESH_H, viewBox: `0 0 ${MESH_W} ${MESH_H}`, focusable: "false", children: [_jsx("g", { className: "dt-mesh__glow-links", children: MESH_LINKS.map(([a, b], i) => (_jsx("line", { x1: MESH_NODES[a].x, y1: MESH_NODES[a].y, x2: MESH_NODES[b].x, y2: MESH_NODES[b].y }, i))) }), _jsx("g", { className: "dt-mesh__glow-nodes", children: MESH_NODES.map((n, i) => (_jsx("circle", { cx: n.x, cy: n.y, r: isHub(i) ? 5 : 3.5 }, i))) })] }), _jsx("svg", { className: "dt-mesh__layer", width: MESH_W, height: MESH_H, viewBox: `0 0 ${MESH_W} ${MESH_H}`, focusable: "false", children: _jsx("g", { ref: fxRef }) })] }));
194
+ }
@@ -0,0 +1,13 @@
1
+ export type ScrollState = {
2
+ /** 0–1, how far down the document the reader is. */
3
+ progress: number;
4
+ /** Pixels scrolled from the top. */
5
+ scrollTop: number;
6
+ };
7
+ export type ReadingProgressProps = {
8
+ onScrollChange?: (state: ScrollState) => void;
9
+ className?: string;
10
+ };
11
+ /** Document scroll progress, updated on scroll (passive listener). */
12
+ export declare function useScrollProgress(onChange?: (state: ScrollState) => void): ScrollState;
13
+ export declare function ReadingProgress({ onScrollChange, className }: ReadingProgressProps): import("react").JSX.Element;
@@ -0,0 +1,43 @@
1
+ 'use client';
2
+ import { jsx as _jsx } from "react/jsx-runtime";
3
+ /**
4
+ * ReadingProgress — a thin line pinned to the top of the viewport that fills
5
+ * as the reader scrolls the page. Decorative (aria-hidden, pointer-events:
6
+ * none). Styled by `.dt-progress` in effects.css: colour and height come from
7
+ * --progress-color / --progress-height, and it stops animating under
8
+ * prefers-reduced-motion.
9
+ *
10
+ * Render it only on long pages (e.g. articles with 3+ sections). Use `onScrollChange` to drive anything else from the same
11
+ * listener, e.g. a back-to-top button.
12
+ */
13
+ import { useEffect, useState } from 'react';
14
+ /** Document scroll progress, updated on scroll (passive listener). */
15
+ export function useScrollProgress(onChange) {
16
+ const [state, setState] = useState({ progress: 0, scrollTop: 0 });
17
+ useEffect(() => {
18
+ const on = () => {
19
+ const h = document.documentElement;
20
+ const max = h.scrollHeight - h.clientHeight;
21
+ const next = {
22
+ progress: max > 0 ? Math.min(1, h.scrollTop / max) : 0,
23
+ scrollTop: h.scrollTop,
24
+ };
25
+ setState(next);
26
+ onChange?.(next);
27
+ };
28
+ on();
29
+ window.addEventListener('scroll', on, { passive: true });
30
+ window.addEventListener('resize', on, { passive: true });
31
+ return () => {
32
+ window.removeEventListener('scroll', on);
33
+ window.removeEventListener('resize', on);
34
+ };
35
+ // onChange is a notification callback; re-subscribing on every render isn't needed.
36
+ // eslint-disable-next-line react-hooks/exhaustive-deps
37
+ }, []);
38
+ return state;
39
+ }
40
+ export function ReadingProgress({ onScrollChange, className }) {
41
+ const { progress } = useScrollProgress(onScrollChange);
42
+ return (_jsx("span", { "aria-hidden": "true", className: className ? `dt-progress ${className}` : 'dt-progress', style: { width: `${progress * 100}%` } }));
43
+ }
@@ -0,0 +1,18 @@
1
+ export type ToastTone = 'success' | 'error' | 'info';
2
+ export interface ToastMessage {
3
+ id: number;
4
+ message: string;
5
+ tone: ToastTone;
6
+ }
7
+ type Listener = (t: ToastMessage) => void;
8
+ /** Show a toast in whichever <Toaster /> is mounted. */
9
+ export declare function notify(message: string, tone?: ToastTone): void;
10
+ export declare function onToast(listener: Listener): () => void;
11
+ export type ToasterProps = {
12
+ /** How long a toast stays up, in ms. Minimum 5000. */
13
+ duration?: number;
14
+ closeLabel?: string;
15
+ };
16
+ /** Mount once in the shell/root layout. */
17
+ export declare function Toaster({ duration, closeLabel }: ToasterProps): import("react").JSX.Element;
18
+ export {};
package/dist/toast.js ADDED
@@ -0,0 +1,41 @@
1
+ 'use client';
2
+ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
3
+ /**
4
+ * Toasts — short confirmations at the bottom of the screen.
5
+ *
6
+ * `notify()` is a framework-free bus, so a micro-frontend can raise a toast
7
+ * that the shell's single <Toaster /> shows. Accessibility:
8
+ * - announced via a polite live region (WCAG 4.1.3 Status Messages);
9
+ * - stays up for --toast-duration-like `duration` (default 6 s, ≥ 5 s) and
10
+ * pauses while hovered or focused, so it can be read (2.2.1);
11
+ * - has a close button sized to the 24 px minimum target (2.5.8).
12
+ * Don't put the only copy of important information in a toast.
13
+ */
14
+ import { useEffect, useRef, useState } from 'react';
15
+ const listeners = new Set();
16
+ let seq = 0;
17
+ /** Show a toast in whichever <Toaster /> is mounted. */
18
+ export function notify(message, tone = 'success') {
19
+ const t = { id: ++seq, message, tone };
20
+ listeners.forEach((l) => l(t));
21
+ }
22
+ export function onToast(listener) {
23
+ listeners.add(listener);
24
+ return () => listeners.delete(listener);
25
+ }
26
+ /** Mount once in the shell/root layout. */
27
+ export function Toaster({ duration = 6000, closeLabel = 'Dismiss' }) {
28
+ const [toast, setToast] = useState(null);
29
+ const [held, setHeld] = useState(false);
30
+ const timer = useRef(undefined);
31
+ const ms = Math.max(5000, duration);
32
+ useEffect(() => onToast(setToast), []);
33
+ useEffect(() => {
34
+ window.clearTimeout(timer.current);
35
+ if (toast && !held)
36
+ timer.current = window.setTimeout(() => setToast(null), ms);
37
+ return () => window.clearTimeout(timer.current);
38
+ }, [toast, held, ms]);
39
+ const tone = toast?.tone === 'error' ? ' dt-toast--error' : toast?.tone === 'info' ? ' dt-toast--info' : '';
40
+ return (_jsx("div", { className: `dt-toast${toast ? ' is-shown' : ''}${tone}`, role: "status", "aria-live": "polite", onMouseEnter: () => setHeld(true), onMouseLeave: () => setHeld(false), onFocus: () => setHeld(true), onBlur: () => setHeld(false), children: toast && (_jsxs(_Fragment, { children: [_jsx("span", { className: "dt-toast__dot", "aria-hidden": "true" }), _jsx("span", { children: toast.message }), _jsx("button", { type: "button", className: "dt-toast__close", "aria-label": closeLabel, onClick: () => setToast(null), children: "\u00D7" })] })) }));
41
+ }
package/package.json CHANGED
@@ -1,6 +1,49 @@
1
1
  {
2
2
  "name": "@thebankingengineer/site-effects",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.0",
4
+ "description": "Shared motion, loading and feedback components for React apps and micro-frontends — animated network background, reading progress, activity bar, loaders, toasts, status pills, a motion pause control and GA4 reading-engagement events. Styled by @thebankingengineer/design-tokens.",
5
+ "license": "UNLICENSED",
6
+ "private": false,
7
+ "type": "module",
8
+ "sideEffects": false,
9
+ "files": [
10
+ "dist",
11
+ "README.md"
12
+ ],
13
+ "main": "./dist/index.js",
14
+ "types": "./dist/index.d.ts",
15
+ "exports": {
16
+ ".": {
17
+ "types": "./dist/index.d.ts",
18
+ "import": "./dist/index.js"
19
+ }
20
+ },
21
+ "scripts": {
22
+ "build": "rm -rf dist && tsc -p tsconfig.json",
23
+ "check": "npm run build && node scripts/check.mjs",
24
+ "prepack": "npm run build"
25
+ },
26
+ "peerDependencies": {
27
+ "@thebankingengineer/design-tokens": ">=0.3.0",
28
+ "react": ">=18"
29
+ },
30
+ "devDependencies": {
31
+ "@types/react": "^19.0.0",
32
+ "react": "^19.0.0",
33
+ "typescript": "^5.6.0"
34
+ },
35
+ "publishConfig": {
36
+ "access": "public",
37
+ "registry": "https://registry.npmjs.org"
38
+ },
39
+ "repository": {
40
+ "type": "git",
41
+ "url": "git+https://github.com/Building-Better-Systems-Pte-Ltd/design-tokens.git",
42
+ "directory": "site-effects"
43
+ },
44
+ "peerDependenciesMeta": {
45
+ "@thebankingengineer/design-tokens": {
46
+ "optional": true
47
+ }
48
+ }
49
+ }