@motionstudies/web 0.1.0-alpha.0 → 0.1.0-alpha.2

package/README.md

@@ -4,7 +4,7 @@ Shared packages for the Motion Studies transport instrument. The source workspac
 
 - `@motionstudies/core`: transport contracts, indexing, interpolation and visual theme contracts; no browser or Node dependencies.
 - `@motionstudies/three`: `NationalNetworkScene`, `HubPulseScene`, `StationFlowScene`, camera framing and label-mode contracts. React, React Three Fiber and Three.js are peers; rendering internals are not public subpaths.
-- `@motionstudies/web`: picker, theme application, mounting, progressive loaders, observed operations and recording. Import `tokens.css` and `mobile-picker.css` for isolated widgets. `shell.css` is an optional full-page study shell scoped to `.motion-study`; `mountMotionStudy` applies that class. Fonts and edition layouts belong to consumers.
+- `@motionstudies/web`: picker, button tooltips, theme application, mounting, progressive loaders, observed operations and recording. Import `tokens.css` and `mobile-picker.css` for isolated widgets. `shell.css` is an optional full-page study shell scoped to `.motion-study`; `mountMotionStudy` applies that class. Fonts and edition layouts belong to consumers.
 - `@motionstudies/data`: Node-only GTFS readers, network chunking, merging and station ranking. ZIP reading requires `unzip` on the host. Source selection, provenance overrides and compilation commands belong to each edition.
 
 ```tsx
@@ -24,3 +24,9 @@ Keep the resolver stable across renders. Manifest paths and their chunk paths ar
 Build release candidates with `npm run build:packages`. Distribution manifests and compiled ESM/declarations are written to `.package-dist/`; workspace manifests continue to point at source for fast local iteration. `npm run check:packed` packs and installs those distributions into a separate consumer, builds the lab and validates the public exports. No source aliases or workspace links are used in that consumer.
 
 Source workspace manifests always stay private. `npm run check:release` builds public candidates, tests their packed consumer and records the tested tarball hashes; `npm run release:dry-run` inspects the publication without writing to npm. The manual main-branch `release.yml` workflow publishes those same tarballs with public access and provenance. See [release instructions](https://github.com/emmettl/motionstudies/blob/main/docs/RELEASING.md) for bootstrap-token and trusted-publisher setup. All four shared packages are MIT-licensed; each distribution includes `LICENSE`.
+
+## Button help
+
+`mountMotionStudy` installs one shared tooltip surface. Independent consumers such as the lab can render `ButtonTooltips` from `@motionstudies/web/components/ButtonTooltips` once instead. Put concise, action-oriented help in each button’s `data-tooltip`; icon buttons fall back to their `aria-label`. An empty `data-tooltip` opts out. Avoid native `title` attributes on these buttons, which can also appear during touch interaction.
+
+Help appears after a short mouse hover or on keyboard focus when the primary pointer is fine and supports hover. Touch input suppresses it, including on hybrid devices. Escape, activation, scrolling and blur dismiss it. The tooltip stays inside the viewport, can itself be hovered, and temporarily extends `aria-describedby` without replacing existing descriptions. Copy and translations stay in the edition; rendering and input handling stay in this package. The Controls specimen and packed-consumer tests exercise this contract.

package/components/ButtonTooltips.d.ts

@@ -0,0 +1,5 @@
+/** One delegated tooltip surface per application. Copy belongs to each edition.
+ * data-tooltip supplies help; aria-label is the fallback for icon controls.
+ * An empty data-tooltip opts a self-explanatory button out.
+ */
+export declare function ButtonTooltips(): null;

package/components/ButtonTooltips.js

@@ -0,0 +1,146 @@
+import { useEffect } from 'react';
+let nextTooltipId = 0;
+/** One delegated tooltip surface per application. Copy belongs to each edition.
+ * data-tooltip supplies help; aria-label is the fallback for icon controls.
+ * An empty data-tooltip opts a self-explanatory button out.
+ */
+export function ButtonTooltips() {
+    useEffect(() => {
+        const capability = window.matchMedia('(hover: hover) and (pointer: fine)');
+        const tooltip = document.createElement('div');
+        tooltip.id = `motion-study-tooltip-${++nextTooltipId}`;
+        tooltip.setAttribute('role', 'tooltip');
+        Object.assign(tooltip.style, {
+            position: 'fixed', zIndex: '2147483647', boxSizing: 'border-box',
+            maxWidth: 'min(300px, calc(100vw - 16px))', padding: '9px 12px',
+            border: '1px solid #73818d', borderRadius: '6px', background: '#101820',
+            color: '#f5f7fa', font: '400 13px/1.45 system-ui, sans-serif',
+            letterSpacing: 'normal', textTransform: 'none', textAlign: 'start',
+            whiteSpace: 'normal', overflowWrap: 'anywhere',
+            boxShadow: '0 4px 18px #0006', pointerEvents: 'auto',
+        });
+        let anchor = null;
+        let showTimer = 0;
+        let hideTimer = 0;
+        let touch = false;
+        const copy = (button) => (button.getAttribute('data-tooltip') ?? button.getAttribute('aria-label') ?? '').trim();
+        const buttonAt = (target) => target instanceof Element ? target.closest('button') : null;
+        const hide = () => {
+            window.clearTimeout(showTimer);
+            window.clearTimeout(hideTimer);
+            if (anchor) {
+                const descriptions = (anchor.getAttribute('aria-describedby') ?? '').split(/\s+/).filter((id) => id && id !== tooltip.id);
+                if (descriptions.length)
+                    anchor.setAttribute('aria-describedby', descriptions.join(' '));
+                else
+                    anchor.removeAttribute('aria-describedby');
+            }
+            anchor = null;
+            observer.disconnect();
+            tooltip.remove();
+        };
+        const refresh = () => {
+            if (!anchor)
+                return;
+            if (!anchor.isConnected || !copy(anchor) || !anchor.getClientRects().length) {
+                hide();
+                return;
+            }
+            const text = copy(anchor);
+            if (tooltip.textContent !== text)
+                tooltip.textContent = text;
+            const lang = anchor.closest('[lang]')?.getAttribute('lang') ?? document.documentElement.lang;
+            if (tooltip.lang !== lang)
+                tooltip.lang = lang;
+            const rect = anchor.getBoundingClientRect();
+            const width = tooltip.offsetWidth;
+            const height = tooltip.offsetHeight;
+            const left = Math.max(8, Math.min(rect.left + (rect.width - width) / 2, window.innerWidth - width - 8));
+            const below = rect.bottom + 8;
+            const top = below + height <= window.innerHeight - 8 ? below : Math.max(8, rect.top - height - 8);
+            tooltip.style.left = `${left}px`;
+            tooltip.style.top = `${top}px`;
+        };
+        const show = (button, delay) => {
+            if (!capability.matches || touch || !copy(button))
+                return;
+            if (anchor === button) {
+                window.clearTimeout(hideTimer);
+                return;
+            }
+            hide();
+            showTimer = window.setTimeout(() => {
+                if (!button.isConnected || !capability.matches || touch)
+                    return;
+                anchor = button;
+                document.body.append(tooltip);
+                const descriptions = (button.getAttribute('aria-describedby') ?? '').split(/\s+/).filter(Boolean);
+                button.setAttribute('aria-describedby', [...descriptions, tooltip.id].join(' '));
+                refresh();
+                observer.observe(document.body, { subtree: true, childList: true, attributes: true, attributeFilter: ['data-tooltip', 'aria-label', 'hidden', 'lang'] });
+            }, delay);
+        };
+        const over = (event) => {
+            if (event.pointerType !== 'mouse')
+                return;
+            touch = false;
+            if (tooltip.contains(event.target)) {
+                window.clearTimeout(hideTimer);
+                return;
+            }
+            const button = buttonAt(event.target);
+            if (button && !button.contains(event.relatedTarget))
+                show(button, 400);
+        };
+        const out = (event) => {
+            const button = buttonAt(event.target);
+            if (button?.contains(event.relatedTarget) || tooltip.contains(event.relatedTarget))
+                return;
+            window.clearTimeout(showTimer);
+            if (anchor || tooltip.contains(event.target)) {
+                window.clearTimeout(hideTimer);
+                hideTimer = window.setTimeout(hide, 160);
+            }
+        };
+        const focus = (event) => {
+            const button = buttonAt(event.target);
+            if (button)
+                show(button, 0);
+        };
+        const down = (event) => { touch = event.pointerType !== 'mouse'; hide(); };
+        const key = (event) => {
+            if (event.key === 'Escape')
+                hide();
+            else if (event.key === 'Tab')
+                touch = false;
+        };
+        const observer = new MutationObserver(refresh);
+        document.addEventListener('pointerover', over, true);
+        document.addEventListener('pointerout', out, true);
+        document.addEventListener('pointerdown', down, true);
+        document.addEventListener('focusin', focus);
+        document.addEventListener('focusout', hide);
+        document.addEventListener('keydown', key, true);
+        document.addEventListener('click', hide, true);
+        document.addEventListener('scroll', hide, true);
+        window.addEventListener('resize', hide);
+        window.addEventListener('blur', hide);
+        capability.addEventListener('change', hide);
+        return () => {
+            hide();
+            observer.disconnect();
+            document.removeEventListener('pointerover', over, true);
+            document.removeEventListener('pointerout', out, true);
+            document.removeEventListener('pointerdown', down, true);
+            document.removeEventListener('focusin', focus);
+            document.removeEventListener('focusout', hide);
+            document.removeEventListener('keydown', key, true);
+            document.removeEventListener('click', hide, true);
+            document.removeEventListener('scroll', hide, true);
+            window.removeEventListener('resize', hide);
+            window.removeEventListener('blur', hide);
+            capability.removeEventListener('change', hide);
+        };
+    }, []);
+    return null;
+}

package/mount-motion-study.js

@@ -1,6 +1,7 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
+import { ButtonTooltips } from './components/ButtonTooltips.js';
 import { applyVisualTheme } from './visual-theme.js';
 export function mountMotionStudy(edition, application) {
     const root = document.getElementById('root');
@@ -9,5 +10,5 @@ export function mountMotionStudy(edition, application) {
     document.documentElement.classList.add('motion-study');
     document.documentElement.dataset.edition = edition.id;
     applyVisualTheme(edition.theme);
-    createRoot(root).render(_jsx(StrictMode, { children: application }));
+    createRoot(root).render(_jsxs(StrictMode, { children: [application, _jsx(ButtonTooltips, {})] }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motionstudies/web",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.2",
   "private": false,
   "type": "module",
   "description": "Browser controls and loaders for Motion Studies.",
@@ -72,7 +72,12 @@
     },
     "./tokens.css": "./tokens.css",
     "./shell.css": "./shell.css",
-    "./mobile-picker.css": "./components/mobile-picker.css"
+    "./mobile-picker.css": "./components/mobile-picker.css",
+    "./components/ButtonTooltips": {
+      "types": "./components/ButtonTooltips.d.ts",
+      "import": "./components/ButtonTooltips.js",
+      "default": "./components/ButtonTooltips.js"
+    }
   },
   "files": [
     "**/*.js",
@@ -87,7 +92,7 @@
     "**/*.css"
   ],
   "dependencies": {
-    "@motionstudies/core": "0.1.0-alpha.0"
+    "@motionstudies/core": "0.1.0-alpha.2"
   },
   "peerDependencies": {
     "react": "^19.2.8",