@enigmax/primitives 0.25.0 → 0.26.0

package/registry.json

@@ -1402,6 +1402,471 @@
       "dependencies": {
         "@github/relative-time-element": "^4.4.0"
       }
+    },
+    {
+      "name": "image",
+      "title": "Image, with the viewer a press on it opens",
+      "description": "An image that opens into a lightbox: a press enlarges it and the picture flies out of the page into the viewer, the wheel zooms around the cursor, with a drag to pan, a pinch on touch, and the keyboard driving all of it. Everything else is a decision about the page it sits in, so it is off until asked for - the arrows and counter of a set, the strip of previews along the bottom, a three-dot menu that downloads the file, and a discard action that drops an image and moves to the next. The viewer is its own chunk, fetched on intent, and the menu another under that, so a page of images nobody enlarges downloads neither. It brings a theme: there is no useful unstyled lightbox.",
+      "targets": [
+        "react"
+      ],
+      "entry": {
+        "react": "@enigmax/primitives/react/image"
+      },
+      "exports": {
+        "react": [
+          "Image"
+        ]
+      },
+      "files": [
+        {
+          "path": "src/core/image-viewer.ts",
+          "dest": "image/image-viewer.ts",
+          "targets": [
+            "react"
+          ]
+        },
+        {
+          "path": "src/core/context-menu.ts",
+          "dest": "image/context-menu.ts",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/core/search": "./search-core",
+            "@/core/keys": "./keys"
+          }
+        },
+        {
+          "path": "src/core/search.ts",
+          "dest": "image/search-core.ts",
+          "targets": [
+            "react"
+          ]
+        },
+        {
+          "path": "src/core/keys.ts",
+          "dest": "image/keys.ts",
+          "targets": [
+            "react"
+          ]
+        },
+        {
+          "path": "src/react/image/types.ts",
+          "dest": "image/types.ts",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/react/context-menu/context": "./context"
+          }
+        },
+        {
+          "path": "src/react/image/icons.tsx",
+          "dest": "image/icons.tsx",
+          "targets": [
+            "react"
+          ]
+        },
+        {
+          "path": "src/react/image/styles.ts",
+          "dest": "image/styles.ts",
+          "targets": [
+            "react"
+          ]
+        },
+        {
+          "path": "src/core/clipboard-menu.ts",
+          "dest": "image/clipboard-menu.ts",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/core/context-menu": "./context-menu",
+            "@/react/context-menu/styles": "./context-menu-styles"
+          }
+        },
+        {
+          "path": "src/react/slot.tsx",
+          "dest": "image/slot.tsx",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/react/context-menu/styles": "./context-menu-styles"
+          }
+        },
+        {
+          "path": "src/react/context-menu/styles.ts",
+          "dest": "image/context-menu-styles.ts",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/react/context-menu/styles": "./context-menu-styles"
+          }
+        },
+        {
+          "path": "recipes/context-menu/styles.css",
+          "dest": "image/context-menu-styles.css",
+          "targets": [
+            "react"
+          ],
+          "style": "css",
+          "rewrite": {
+            "@/react/context-menu/styles": "./context-menu-styles"
+          }
+        },
+        {
+          "path": "src/react/context-menu/context.ts",
+          "dest": "image/context.ts",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/core/context-menu": "./context-menu",
+            "@/react/context-menu/styles": "./context-menu-styles"
+          }
+        },
+        {
+          "path": "src/react/context-menu/root.tsx",
+          "dest": "image/root.tsx",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/core/context-menu": "./context-menu",
+            "@/core/search": "./search-core",
+            "@/core/keys": "./keys",
+            "@/react/slot": "./slot",
+            "@/react/context-menu/styles": "./context-menu-styles",
+            "@/react/context-menu/context": "./context",
+            "@/core/clipboard-menu": "./clipboard-menu"
+          }
+        },
+        {
+          "path": "src/react/context-menu/index.tsx",
+          "dest": "image/context-menu-ui.tsx",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/react/context-menu/root": "./root",
+            "@/react/context-menu/context": "./context",
+            "@/react/context-menu/styles": "./context-menu-styles",
+            "@/core/context-menu": "./context-menu",
+            "@/core/keys": "./keys",
+            "@/core/clipboard-menu": "./clipboard-menu"
+          }
+        },
+        {
+          "path": "src/react/image/menu.tsx",
+          "dest": "image/menu.tsx",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/react/image/icons": "./icons",
+            "@/react/image/types": "./types",
+            "@/react/image/viewer": "./viewer",
+            "@/core/image-viewer": "./image-viewer",
+            "@/react/context-menu": "./context-menu-ui"
+          }
+        },
+        {
+          "path": "src/react/image/viewer.tsx",
+          "dest": "image/viewer.tsx",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/react/image/icons": "./icons",
+            "@/react/image/types": "./types",
+            "@/react/image/styles": "./styles",
+            "@/react/image/menu": "./menu",
+            "@/core/image-viewer": "./image-viewer"
+          }
+        },
+        {
+          "path": "src/react/image/index.tsx",
+          "dest": "image/index.tsx",
+          "main": true,
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/react/image/types": "./types",
+            "@/react/image/viewer": "./viewer",
+            "@/react/image/styles": "./styles"
+          }
+        },
+        {
+          "path": "recipes/image/styles.css",
+          "dest": "image/styles.css",
+          "targets": [
+            "react"
+          ],
+          "style": "css"
+        }
+      ],
+      "styles": true,
+      "themeHooks": [
+        "[data-enigma-image]",
+        "[data-enigma-image][data-clickable]",
+        "[data-enigma-image-trigger]",
+        "[data-enigma-image-viewer]",
+        "[data-enigma-image-bar]",
+        "[data-enigma-image-counter]",
+        "[data-enigma-image-button]",
+        "[data-enigma-image-frame]",
+        "[data-enigma-image-frame][data-zoomed]",
+        "[data-enigma-image-frame][data-panning]",
+        "[data-enigma-image-frame][data-loading]",
+        "[data-enigma-image-nav]",
+        "[data-enigma-image-spinner]",
+        "[data-enigma-image-foot]",
+        "[data-enigma-image-caption]",
+        "[data-enigma-image-strip]",
+        "[data-enigma-image-thumb]",
+        "[data-enigma-image-viewer][data-state]",
+        "[data-enigma-image-frame][data-flying]"
+      ],
+      "docs": "docs/notes/primitives.md#image",
+      "recipes": [
+        "css"
+      ]
+    },
+    {
+      "name": "video",
+      "title": "Video player",
+      "description": "A video with the controls a video is expected to have, shaped after Plyr: a big play button over the poster, a scrubber showing what is buffered, current time and duration, volume that folds away until reached, subtitles with a language picker, a speed menu, picture in picture, casting to a TV and fullscreen. A right-click opens a menu the way YouTube's does - play, loop, speed, subtitles, copy the link or the link at this second - built from the context-menu primitive rather than hand-rolled. The keyboard is the platform's - space and K play, J and L jump ten seconds, the arrows nudge and set the volume, M mutes, F is fullscreen, C captions, a digit seeks to that tenth - and it stands down inside anything that takes text. The bar fades while playing and comes back on the first pointer move. The element stays the source of truth: playback, the subtitle list and the cast target are all read back from it rather than kept twice.",
+      "targets": [
+        "react"
+      ],
+      "entry": {
+        "react": "@enigmax/primitives/react/video"
+      },
+      "exports": {
+        "react": [
+          "Video"
+        ]
+      },
+      "files": [
+        {
+          "path": "src/core/context-menu.ts",
+          "dest": "video/context-menu.ts",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/core/search": "./search-core",
+            "@/core/keys": "./keys"
+          }
+        },
+        {
+          "path": "src/core/search.ts",
+          "dest": "video/search-core.ts",
+          "targets": [
+            "react"
+          ]
+        },
+        {
+          "path": "src/core/keys.ts",
+          "dest": "video/keys.ts",
+          "targets": [
+            "react"
+          ]
+        },
+        {
+          "path": "src/core/clipboard-menu.ts",
+          "dest": "video/clipboard-menu.ts",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/core/context-menu": "./context-menu",
+            "@/react/context-menu/styles": "./context-menu-styles"
+          }
+        },
+        {
+          "path": "src/react/slot.tsx",
+          "dest": "video/slot.tsx",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/react/context-menu/styles": "./context-menu-styles"
+          }
+        },
+        {
+          "path": "src/react/context-menu/styles.ts",
+          "dest": "video/context-menu-styles.ts",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/react/context-menu/styles": "./context-menu-styles"
+          }
+        },
+        {
+          "path": "recipes/context-menu/styles.css",
+          "dest": "video/context-menu-styles.css",
+          "targets": [
+            "react"
+          ],
+          "style": "css",
+          "rewrite": {
+            "@/react/context-menu/styles": "./context-menu-styles"
+          }
+        },
+        {
+          "path": "src/react/context-menu/context.ts",
+          "dest": "video/context.ts",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/core/context-menu": "./context-menu",
+            "@/react/context-menu/styles": "./context-menu-styles"
+          }
+        },
+        {
+          "path": "src/react/context-menu/root.tsx",
+          "dest": "video/root.tsx",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/core/context-menu": "./context-menu",
+            "@/core/search": "./search-core",
+            "@/core/keys": "./keys",
+            "@/react/slot": "./slot",
+            "@/react/context-menu/styles": "./context-menu-styles",
+            "@/react/context-menu/context": "./context",
+            "@/core/clipboard-menu": "./clipboard-menu"
+          }
+        },
+        {
+          "path": "src/react/context-menu/index.tsx",
+          "dest": "video/context-menu-ui.tsx",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/react/context-menu/root": "./root",
+            "@/react/context-menu/context": "./context",
+            "@/react/context-menu/styles": "./context-menu-styles",
+            "@/core/context-menu": "./context-menu",
+            "@/core/keys": "./keys",
+            "@/core/clipboard-menu": "./clipboard-menu"
+          }
+        },
+        {
+          "path": "src/core/player.ts",
+          "dest": "video/player.ts",
+          "targets": [
+            "react"
+          ]
+        },
+        {
+          "path": "src/react/video/types.ts",
+          "dest": "video/types.ts",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/react/context-menu/context": "./context"
+          }
+        },
+        {
+          "path": "src/react/video/icons.tsx",
+          "dest": "video/icons.tsx",
+          "targets": [
+            "react"
+          ]
+        },
+        {
+          "path": "src/react/video/styles.ts",
+          "dest": "video/styles.ts",
+          "targets": [
+            "react"
+          ]
+        },
+        {
+          "path": "src/react/video/rail.tsx",
+          "dest": "video/rail.tsx",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/core/player": "./player"
+          }
+        },
+        {
+          "path": "src/react/video/menu.tsx",
+          "dest": "video/menu.tsx",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/core/context-menu": "./context-menu",
+            "@/react/context-menu": "./context-menu-ui"
+          }
+        },
+        {
+          "path": "src/react/video/index.tsx",
+          "dest": "video/index.tsx",
+          "main": true,
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/core/player": "./player",
+            "@/react/video/icons": "./icons",
+            "@/react/video/rail": "./rail",
+            "@/react/video/styles": "./styles",
+            "@/react/video/types": "./types",
+            "@/react/context-menu/context": "./context",
+            "@/react/video/menu": "./menu"
+          }
+        },
+        {
+          "path": "recipes/video/styles.css",
+          "dest": "video/styles.css",
+          "targets": [
+            "react"
+          ],
+          "style": "css"
+        }
+      ],
+      "styles": true,
+      "themeHooks": [
+        "[data-enigma-video]",
+        "[data-enigma-video][data-playing]",
+        "[data-enigma-video][data-hidden]",
+        "[data-enigma-video][data-fullscreen]",
+        "[data-enigma-video-big]",
+        "[data-enigma-video-overlay]",
+        "[data-enigma-video-spinner]",
+        "[data-enigma-video-controls]",
+        "[data-enigma-video-button]",
+        "[data-enigma-video-time]",
+        "[data-enigma-video-rail]",
+        "[data-enigma-video-track]",
+        "[data-enigma-video-buffer]",
+        "[data-enigma-video-played]",
+        "[data-enigma-video-knob]",
+        "[data-enigma-video-volume]",
+        "[data-enigma-video-menu]",
+        "[data-enigma-video-panel]",
+        "[data-enigma-video-option]",
+        "[data-enigma-video-heading]",
+        "[data-enigma-video][data-casting]"
+      ],
+      "docs": "docs/notes/primitives.md#video",
+      "recipes": [
+        "css"
+      ]
     }
   ]
 }

package/src/core/image-viewer.ts

@@ -0,0 +1,222 @@
+/**
+ * The arithmetic behind the image viewer: zoom around a point, panning that cannot lose the
+ * image, moving through a set, and getting a file onto the disk.
+ *
+ * Not a React module, and deliberately: none of this is rendering. A page drawing its own
+ * viewer, or a test, gets the same maths - and the parts that are easy to get wrong (zoom
+ * that drifts away from the cursor, a pan that strands the image off screen, a download that
+ * silently opens a tab instead) are then testable without a browser.
+ */
+
+/** How far the image is scaled, and where its centre sits relative to the frame's, in px. */
+export interface Transform {
+    scale: number;
+    x: number;
+    y: number;
+}
+
+export interface ZoomLimits {
+    min: number;
+    max: number;
+}
+
+/** A box in viewport coordinates - the frame the image is being viewed in. */
+export interface Box {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+
+export const IDENTITY: Transform = { scale: 1, x: 0, y: 0 };
+
+export const ZOOM_LIMITS: ZoomLimits = { min: 1, max: 8 };
+
+/** What a keyboard `+`/`-` step multiplies by, and the ratio a double press toggles to. */
+export const ZOOM_STEP = 1.35;
+export const ZOOM_DOUBLE = 2.5;
+
+export function clampScale(scale: number, limits: ZoomLimits = ZOOM_LIMITS): number {
+    return Math.min(Math.max(scale, limits.min), limits.max);
+}
+
+/**
+ * A wheel notch to a zoom factor.
+ *
+ * `deltaMode` matters: a mouse reports pixels, but Firefox reports LINES (mode 1) and a page
+ * scroll reports pages (mode 2), so treating every delta as pixels makes the same gesture
+ * zoom a hundred times harder in one browser than another. The exponential keeps a notch
+ * proportional - zooming out from 8x and in from 1x take the same number of turns.
+ */
+export function wheelFactor(deltaY: number, deltaMode = 0): number {
+    const pixels = deltaMode === 1 ? deltaY * 16 : deltaMode === 2 ? deltaY * 400 : deltaY;
+    return Math.exp(-Math.min(Math.max(pixels, -240), 240) / 320);
+}
+
+/**
+ * Zoom, keeping the point under the pointer under the pointer.
+ *
+ * The defect this exists for: scaling around the frame's centre slides whatever the visitor
+ * was pointing at out from under them, so zooming into a face means zooming and then hunting
+ * for it again. The offset is corrected by how much that point moved when the scale changed.
+ */
+export function zoomAt(current: Transform, factor: number, point: { x: number; y: number; }, box: Box, limits: ZoomLimits = ZOOM_LIMITS): Transform {
+    const scale = clampScale(current.scale * factor, limits);
+    if (scale === current.scale) return current;
+
+    // Where the pointer is relative to the frame's centre, which is what the offsets are
+    // measured from.
+    const dx = point.x - (box.left + box.width / 2);
+    const dy = point.y - (box.top + box.height / 2);
+    const ratio = scale / current.scale;
+
+    return { scale, x: dx - (dx - current.x) * ratio, y: dy - (dy - current.y) * ratio };
+}
+
+/**
+ * Keep the image over the frame.
+ *
+ * At 1x it is centred and there is nothing to pan. Zoomed, the offset is bounded by the half
+ * of the image that hangs outside the frame - without it a drag can throw the picture off the
+ * screen entirely, and the only way back is to close the viewer.
+ */
+export function clampPan(transform: Transform, box: Box, natural: { width: number; height: number; }): Transform {
+    const width = natural.width * transform.scale;
+    const height = natural.height * transform.scale;
+    const x = Math.max(0, (width - box.width) / 2);
+    const y = Math.max(0, (height - box.height) / 2);
+
+    return {
+        scale: transform.scale,
+        x: Math.min(Math.max(transform.x, -x), x),
+        y: Math.min(Math.max(transform.y, -y), y)
+    };
+}
+
+/** The size an image is DRAWN at inside a frame it is fitted to, which is what pan is bounded by. */
+export function fittedSize(natural: { width: number; height: number; }, box: Box): { width: number; height: number; } {
+    if (!natural.width || !natural.height) return { width: box.width, height: box.height };
+    const ratio = Math.min(box.width / natural.width, box.height / natural.height, 1);
+    return { width: natural.width * ratio, height: natural.height * ratio };
+}
+
+/** The distance between two pointers, for a pinch. */
+export function pinchDistance(a: { x: number; y: number; }, b: { x: number; y: number; }): number {
+    return Math.hypot(a.x - b.x, a.y - b.y);
+}
+
+/**
+ * The next index in a set, skipping what has been discarded.
+ *
+ * Returns -1 when there is nothing left to show, which is the viewer's cue to close rather
+ * than to sit on an empty frame.
+ */
+export function nextIndex(index: number, length: number, step: number, options: { loop?: boolean; skip?: ReadonlySet<number>; } = {}): number {
+    const { loop = true, skip } = options;
+    if (length <= 0) return -1;
+
+    let next = index;
+    // At most one full pass: with everything else discarded the walk would never stop.
+    for (let moved = 0; moved < length; moved += 1) {
+        next += step;
+        if (next < 0 || next >= length) {
+            if (!loop) return -1;
+            next = (next % length + length) % length;
+        }
+        if (!skip?.has(next)) return next;
+    }
+    return -1;
+}
+
+/** The file name to save as: whatever the caller asked for, else the one in the URL. */
+export function filenameFrom(url: string, fallback = "image"): string {
+    try {
+        const { pathname } = new URL(url, typeof location === "undefined" ? "https://localhost" : location.href);
+        const name = pathname.split("/").filter(Boolean).pop();
+        return name && name.includes(".") ? decodeURIComponent(name) : fallback;
+    } catch {
+        return fallback;
+    }
+}
+
+/**
+ * Save the file, rather than navigate to it.
+ *
+ * `<a download>` is honoured only for a same-origin URL; on a CDN the browser ignores the
+ * attribute and opens the image in a tab instead, which is not what the row said it would do.
+ * So the bytes are fetched and handed over as a blob, and the plain anchor is the fallback for
+ * when that is refused (no CORS header) - a tab is still better than nothing happening.
+ */
+export async function downloadFile(url: string, filename?: string): Promise<void> {
+    const name = filename ?? filenameFrom(url);
+    try {
+        const response = await fetch(url, { mode: "cors", credentials: "omit" });
+        if (!response.ok) throw new Error(`the file answered ${response.status}`);
+        const blob = await response.blob();
+        const href = URL.createObjectURL(blob);
+        saveAs(href, name);
+        // Revoked on the next task, not immediately: Safari has not started reading yet.
+        setTimeout(() => URL.revokeObjectURL(href), 10_000);
+    } catch {
+        saveAs(url, name, true);
+    }
+}
+
+function saveAs(href: string, name: string, external = false): void {
+    if (typeof document === "undefined") return;
+    const anchor = document.createElement("a");
+    anchor.href = href;
+    anchor.download = name;
+    anchor.rel = "noopener";
+    if (external) anchor.target = "_blank";
+    document.body.append(anchor);
+    anchor.click();
+    anchor.remove();
+}
+
+/* -------- the flight from the thumbnail into the viewer -------- */
+
+/** How long the picture takes to fly, when the stylesheet does not say otherwise. */
+export const FLIGHT_MS = 300;
+
+/**
+ * How long the flight ACTUALLY lasts, read off the element.
+ *
+ * The duration lives in the stylesheet (`--enigma-image-flight`), so a project that slows it
+ * down would otherwise have the viewer give up waiting halfway through and close mid-flight.
+ * The constant above is only the answer for an element with no transition on it at all.
+ */
+export function flightMs(element: Element | null): number {
+    if (!element || typeof getComputedStyle === "undefined") return FLIGHT_MS;
+    const seconds = Number.parseFloat(getComputedStyle(element).transitionDuration);
+    return Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : FLIGHT_MS;
+}
+
+/**
+ * The transform that puts a picture exactly over another box.
+ *
+ * This is the FLIP the lightbox opens with: the full-size image is laid out where it belongs,
+ * measured, and then drawn back ON the thumbnail with this transform - so releasing it to the
+ * identity transform is the picture growing out of the one in the page rather than a dialog
+ * appearing over it. Closing is the same transform applied in the other direction.
+ *
+ * Both boxes are the same picture, so one scale is enough; the width is used because a
+ * thumbnail is nearly always constrained by it. Null when either box has not been laid out
+ * yet, which is the caller's cue to skip the animation rather than to divide by zero.
+ */
+export function flightFrom(from: Box, to: Box): Transform | null {
+    if (!from.width || !from.height || !to.width || !to.height) return null;
+    return {
+        scale: from.width / to.width,
+        // Centre to centre: `translate(x, y) scale(s)` scales about the element's own centre
+        // first, so the offset that lands it on the thumbnail is the distance between them.
+        x: (from.left + from.width / 2) - (to.left + to.width / 2),
+        y: (from.top + from.height / 2) - (to.top + to.height / 2)
+    };
+}
+
+/** Whether the reader has asked for less movement. Every animation here is skipped when they have. */
+export function prefersReducedMotion(): boolean {
+    if (typeof window === "undefined" || !window.matchMedia) return false;
+    return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}