npm - @enigmax/primitives - Versions diffs - 0.25.0 → 0.26.0 - Mend

@enigmax/primitives 0.25.0 → 0.26.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.

Files changed (48) hide show

package/dist/chunk-4SZ5N7BA.js +121 -0
package/dist/chunk-EYZ366LP.js +189 -0
package/dist/chunk-ISXB5RUH.js +380 -0
package/dist/chunk-JJVZYW5C.js +946 -0
package/dist/chunk-QIIV2QSV.js +108 -0
package/dist/chunk-RUEQ3TGP.js +155 -0
package/dist/clipboard-menu-BvXJCSFN.d.ts +93 -0
package/dist/context-BfjYGPnH.d.ts +54 -0
package/dist/{clipboard-menu-B_ouitfS.d.ts → context-menu-D3FtTn7v.d.ts} +1 -91
package/dist/index.d.ts +266 -2
package/dist/index.js +4 -2
package/dist/menu-MSQSE6U5.js +54 -0
package/dist/menu-PNQRTRNV.js +33 -0
package/dist/next/index.d.ts +6 -2
package/dist/next/index.js +10 -6
package/dist/react/context-menu.d.ts +8 -54
package/dist/react/image.d.ts +109 -0
package/dist/react/image.js +3 -0
package/dist/react/index.d.ts +6 -2
package/dist/react/index.js +10 -6
package/dist/react/input.js +1 -1
package/dist/react/video.d.ts +120 -0
package/dist/react/video.js +3 -0
package/dist/react-router/index.d.ts +6 -2
package/dist/react-router/index.js +10 -6
package/dist/viewer-73LSE6RR.js +3 -0
package/package.json +15 -2
package/recipes/image/styles.css +182 -0
package/recipes/video/styles.css +154 -0
package/registry.json +465 -0
package/src/core/image-viewer.ts +222 -0
package/src/core/player.ts +303 -0
package/src/index.ts +52 -0
package/src/react/image/icons.tsx +55 -0
package/src/react/image/index.tsx +185 -0
package/src/react/image/menu.tsx +76 -0
package/src/react/image/styles.ts +213 -0
package/src/react/image/types.ts +113 -0
package/src/react/image/viewer.tsx +571 -0
package/src/react/index.ts +3 -0
package/src/react/video/icons.tsx +135 -0
package/src/react/video/index.tsx +724 -0
package/src/react/video/menu.tsx +66 -0
package/src/react/video/rail.tsx +99 -0
package/src/react/video/styles.ts +161 -0
package/src/react/video/types.ts +135 -0
/package/dist/{chunk-3MGBZOAU.js → chunk-RMNXVWQ4.js} +0 -0
/package/dist/{chunk-MSOCCQGH.js → chunk-T7I6WJSN.js} +0 -0

package/src/react/image/styles.ts ADDED Viewed

@@ -0,0 +1,213 @@
+/**
+ * The image viewer's look.
+ *
+ * It ships one, for the reason the colour picker and the toast do: there is no useful
+ * "unstyled" lightbox. A dialog with no backdrop, no size and no stacking is not a plain
+ * viewer, it is the page with an image lying across it - so the panel arrives dressed and
+ * `styles={false}` takes it away for anyone drawing their own.
+ *
+ * A string because the component injects it. `scripts/sync-recipes.mjs` generates
+ * `recipes/image/styles.css` from here and CI fails when the two drift, so this module is the
+ * source and the stylesheet is the copy for anyone who prefers an import.
+ *
+ * Everything below is a custom property or an attribute selector: the sheet is PREPENDED to
+ * `<head>`, so anything the document already has wins at equal specificity.
+ */
+export const IMAGE_STYLES = `
+:root {
+    --enigma-image-backdrop: rgba(0, 0, 0, 0.92);
+    --enigma-image-text: #f5f5f5;
+    --enigma-image-muted: #a3a3a3;
+    --enigma-image-control-bg: rgba(23, 23, 23, 0.72);
+    --enigma-image-control-hover: rgba(64, 64, 64, 0.82);
+    --enigma-image-control-size: 2.25rem;
+    --enigma-image-radius: 0.625rem;
+    --enigma-image-gap: 0.75rem;
+    --enigma-image-thumb-size: 3.5rem;
+    --enigma-image-focus: #f5f5f5;
+    /* Above the page's own chrome, not merely above its content: a header or a sticky sidebar
+       with a z-index of its own would otherwise paint over the dialog covering it. */
+    --enigma-image-z: 9999;
+    /* How long the picture takes to fly out of the page and back into it, and the curve it
+       flies on. They are the numbers core/image-viewer.ts waits for, so a project that
+       changes one here changes it there - see the note above the keyframes. */
+    --enigma-image-flight: 300ms;
+    --enigma-image-flight-ease: cubic-bezier(0.2, 0, 0.2, 1);
+}
+/* The thumbnail in the page. Only what the behaviour needs: the pointer says it opens, and
+   the box is the caller's to size. */
+[data-enigma-image] { display: inline-flex; max-width: 100%; }
+[data-enigma-image][data-clickable] { cursor: zoom-in; }
+/* Stated on the picture as well as inherited: a project that restyles the trigger button is
+   one cursor: pointer away from a thumbnail that no longer says it enlarges. */
+[data-enigma-image][data-clickable] img { cursor: zoom-in; }
+[data-enigma-image] img { display: block; max-width: 100%; height: auto; }
+/* A real box, never display:contents: an element without one cannot be focused in Chromium,
+   so a viewer closed with Escape would hand focus to the body instead of back to the picture
+   it was opened from, and the next Tab would start at the top of the page. */
+[data-enigma-image-trigger] {
+    display: inline-flex; max-width: 100%; padding: 0; margin: 0;
+    background: none; border: 0; color: inherit; font: inherit; cursor: inherit;
+}
+[data-enigma-image-trigger]:focus-visible img { outline: 2px solid var(--enigma-image-focus); outline-offset: 3px; }
+/* The viewer. Fixed and portalled: a lightbox inside the page's own stacking context is a
+   lightbox some ancestor's overflow or transform will clip. */
+[data-enigma-image-viewer] {
+    position: fixed; inset: 0; z-index: var(--enigma-image-z);
+    display: grid; grid-template-rows: auto minmax(0, 1fr) auto;
+    background: var(--enigma-image-backdrop);
+    color: var(--enigma-image-text);
+}
+/* The opening: the backdrop arrives while the picture flies out of the page, and the toolbar
+   and the strip arrive with it rather than being there first over a picture that is still on
+   its way. data-state is only ever "opening" or "closing" while an animation is meant to be
+   running, so a viewer that skipped the flight - reduced motion, animate={false} - matches
+   none of these rules and simply exists. */
+@keyframes enigma-image-in { from { background-color: transparent; } to { background-color: var(--enigma-image-backdrop); } }
+@keyframes enigma-image-chrome { from { opacity: 0; } to { opacity: 1; } }
+[data-enigma-image-viewer][data-state="opening"] { animation: enigma-image-in var(--enigma-image-flight) ease-out; }
+[data-enigma-image-viewer][data-state="opening"] [data-enigma-image-bar],
+[data-enigma-image-viewer][data-state="opening"] [data-enigma-image-foot],
+[data-enigma-image-viewer][data-state="opening"] [data-enigma-image-nav] {
+    animation: enigma-image-chrome var(--enigma-image-flight) ease-out;
+}
+/* On the way out the backdrop drains, and the dialog stops taking presses: it is over the
+   page again, so a click through it would land on whatever is now under the pointer. */
+[data-enigma-image-viewer][data-state="closing"] {
+    background-color: transparent; pointer-events: none;
+    transition: background-color var(--enigma-image-flight) var(--enigma-image-flight-ease);
+}
+[data-enigma-image-viewer][data-state="closing"] [data-enigma-image-bar],
+[data-enigma-image-viewer][data-state="closing"] [data-enigma-image-foot],
+[data-enigma-image-viewer][data-state="closing"] [data-enigma-image-nav] {
+    opacity: 0; transition: opacity calc(var(--enigma-image-flight) / 2) ease-in;
+}
+[data-enigma-image-bar] {
+    display: flex; align-items: center; gap: 0.5rem;
+    padding: var(--enigma-image-gap);
+}
+[data-enigma-image-counter] {
+    font-size: 0.8125rem; font-variant-numeric: tabular-nums; color: var(--enigma-image-muted);
+    margin-inline-end: auto;
+}
+[data-enigma-image-button] {
+    display: grid; place-items: center; flex: none;
+    width: var(--enigma-image-control-size); height: var(--enigma-image-control-size);
+    padding: 0; color: var(--enigma-image-text);
+    background: var(--enigma-image-control-bg); border: 0; border-radius: 999px;
+    cursor: pointer;
+}
+[data-enigma-image-button]:hover { background: var(--enigma-image-control-hover); }
+[data-enigma-image-button]:focus-visible { outline: 2px solid var(--enigma-image-focus); outline-offset: 2px; }
+[data-enigma-image-button][disabled] { opacity: 0.35; cursor: not-allowed; }
+/* The frame the picture is fitted into, and the surface every gesture is measured against. */
+[data-enigma-image-frame] {
+    position: relative; overflow: hidden;
+    display: grid; place-items: center;
+    /* Room for the arrows down each side, so they sit beside the picture rather than on it. */
+    padding: 0 calc(var(--enigma-image-control-size) + var(--enigma-image-gap) * 1.5);
+    /* The drag IS the control once zoomed, so the page must not scroll under it. */
+    touch-action: none;
+    -webkit-user-select: none; user-select: none;
+}
+[data-enigma-image-frame] img {
+    max-width: 100%; max-height: 100%;
+    -webkit-user-drag: none;
+    will-change: transform;
+}
+/* Only while it is MOVING, which is not the same as "during the flight".
+   A transition left on permanently would put 300ms of lag between the wheel and the zoom, and
+   turn every pan into a drag the picture follows late. And one left on during "pending" is
+   worse than useless: putting the picture on the thumbnail is itself a transform change, so it
+   animated there over 300ms - behind a hidden element - and by the time anybody could see it
+   the flight was nearly over. */
+[data-enigma-image-frame][data-flying="moving"] img { transition: transform var(--enigma-image-flight) var(--enigma-image-flight-ease); }
+/* Not drawn until there is somewhere to fly from - see the note on the attribute. The spinner
+   is what stands in for it, the same one a slow picture gets. */
+[data-enigma-image-frame][data-flying="pending"] img { visibility: hidden; }
+@media (prefers-reduced-motion: reduce) {
+    [data-enigma-image-frame][data-flying="moving"] img { transition: none; }
+}
+/* The cursor says what a press does, which in a lightbox is three different things. The empty
+   part of the frame IS the backdrop and closes it; the picture at rest takes a double press to
+   enlarge; once it is enlarged the gesture is a drag. */
+[data-enigma-image-frame] { cursor: zoom-out; }
+[data-enigma-image-frame][data-zoom] img { cursor: zoom-in; }
+[data-enigma-image-frame][data-zoomed],
+[data-enigma-image-frame][data-zoomed] img { cursor: grab; }
+[data-enigma-image-frame][data-panning],
+[data-enigma-image-frame][data-panning] img { cursor: grabbing; }
+[data-enigma-image-frame][data-loading] img { opacity: 0.35; }
+/* Left and right sit over the picture rather than beside it: the frame is the biggest thing
+   on screen and the arrows have to be reachable without hunting for an edge. */
+[data-enigma-image-nav] {
+    position: absolute; top: 50%; translate: 0 -50%;
+    width: var(--enigma-image-control-size); height: var(--enigma-image-control-size);
+}
+[data-enigma-image-nav="previous"] { left: var(--enigma-image-gap); }
+[data-enigma-image-nav="next"] { right: var(--enigma-image-gap); }
+[data-enigma-image-spinner] {
+    position: absolute; width: 1.75rem; height: 1.75rem;
+    border: 2px solid rgba(255, 255, 255, 0.25); border-top-color: var(--enigma-image-text);
+    border-radius: 999px; animation: enigma-image-spin 700ms linear infinite;
+}
+@keyframes enigma-image-spin { to { rotate: 360deg; } }
+@media (prefers-reduced-motion: reduce) {
+    [data-enigma-image-spinner] { animation-duration: 2s; }
+}
+[data-enigma-image-foot] { display: grid; gap: 0.5rem; padding: var(--enigma-image-gap); }
+[data-enigma-image-caption] {
+    margin: 0; text-align: center; font-size: 0.8125rem; line-height: 1.5;
+    color: var(--enigma-image-muted);
+}
+/* The strip. Scrolls on its own rather than wrapping: a gallery of forty is one row you drag
+   through, not five rows that push the picture off the screen. */
+[data-enigma-image-strip] {
+    display: flex; gap: 0.5rem; overflow-x: auto; scrollbar-width: thin;
+    justify-content: safe center;
+    padding-bottom: 0.25rem;
+}
+[data-enigma-image-thumb] {
+    flex: none; width: var(--enigma-image-thumb-size); height: var(--enigma-image-thumb-size);
+    padding: 0; overflow: hidden;
+    background: none; border: 0; border-radius: 0.375rem;
+    opacity: 0.55; cursor: pointer;
+}
+[data-enigma-image-thumb] img { width: 100%; height: 100%; object-fit: cover; }
+[data-enigma-image-thumb]:hover { opacity: 0.85; }
+[data-enigma-image-thumb][aria-current="true"] { opacity: 1; box-shadow: 0 0 0 2px var(--enigma-image-focus); }
+[data-enigma-image-thumb]:focus-visible { outline: 2px solid var(--enigma-image-focus); outline-offset: 2px; }
+`;
+let injected = false;
+/**
+ * Put the sheet in the document, once.
+ *
+ * It lives here rather than in the component because BOTH halves need it and they are in
+ * different chunks: the thumbnail is in the page from the first paint, and the viewer arrives
+ * with its own module later. Injecting only from the viewer left the picture in the page
+ * unstyled until somebody opened one - so the cursor did not say it enlarges, and the focus
+ * ring around it did not exist, until after the first press.
+ */
+export function injectImageStyles(): void {
+    if (injected || typeof document === "undefined") return;
+    injected = true;
+    if (document.querySelector("[data-enigma-image-styles]")) return;
+    const element = document.createElement("style");
+    element.setAttribute("data-enigma-image-styles", "");
+    element.textContent = IMAGE_STYLES;
+    document.head.prepend(element);
+}

package/src/react/image/types.ts ADDED Viewed

@@ -0,0 +1,113 @@
+/**
+ * The prop shapes for `<Image>`, split from the component so the viewer's chunk can import
+ * them without pulling the component in - the same arrangement `<Input>` is in.
+ *
+ * WHAT IS ON BY DEFAULT is the whole design of this API: an image that opens and zooms, and
+ * nothing else. A gallery's arrows, its thumbnails, a menu and a discard action are each a
+ * decision about the page they sit in, so each is a prop you turn on rather than one you
+ * remember to turn off.
+ */
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import type { ContextMenuNode } from "@/react/context-menu/context";
+/** One image in a set: a URL, or the URL plus what is known about it. */
+export type ImageSource = string | ImageItem;
+export interface ImageItem {
+    src: string;
+    alt?: string;
+    /** A smaller file for the strip and for the frame while the full one loads. */
+    thumbnail?: string;
+    /** The URL to save, when the file to download is not the one being shown. */
+    download?: string;
+    /** Saved under this name instead of the one in the URL. */
+    filename?: string;
+    caption?: ReactNode;
+}
+export interface ZoomOptions {
+    /** How far out. 1 is the fitted image; below it the picture is smaller than its frame. */
+    min?: number;
+    max?: number;
+    /** Zoom on the wheel. On by default - it is the gesture every image viewer answers. */
+    wheel?: boolean;
+    /** A double press toggles between fitted and this. `false` leaves the gesture alone. */
+    doubleClick?: boolean;
+}
+export interface ImageMenuOptions {
+    /** The download row. On whenever the menu is. */
+    download?: boolean;
+    /** Rows of your own, after the built-in ones. */
+    items?: readonly ContextMenuNode[];
+    onSelect?: (id: string, item: ImageItem, index: number) => void;
+}
+/** Every string the viewer says, for a UI that is not in English. */
+export interface ImageLabels {
+    open?: string;
+    close?: string;
+    zoomIn?: string;
+    zoomOut?: string;
+    reset?: string;
+    previous?: string;
+    next?: string;
+    menu?: string;
+    download?: string;
+    discard?: string;
+    thumbnails?: string;
+    /** The frame itself, announced as the dialog's name. Default "Image viewer". */
+    viewer?: string;
+    /** `{index}` and `{total}` are replaced. Default "{index} of {total}". */
+    counter?: string;
+}
+export interface ImageProps extends Omit<ComponentPropsWithoutRef<"img">, "children" | "onSelect"> {
+    src: string;
+    alt: string;
+    /**
+     * The set this image belongs to. Without it the viewer shows this one image; with it the
+     * arrows, the strip and the discard action have something to move through.
+     */
+    images?: readonly ImageSource[];
+    /** Where in `images` this one is. Found by `src` when it is left out. */
+    index?: number;
+    /** Click to see it larger. ON by default: it is what an image in a page is expected to do. */
+    lightbox?: boolean;
+    /** Zoom, with the wheel and the keyboard. ON by default. */
+    zoom?: boolean | ZoomOptions;
+    /**
+     * The picture flies out of the page into the viewer, and back into it on the way out. ON
+     * by default, and skipped anyway for a reader who has asked for less movement.
+     */
+    animate?: boolean;
+    /** Arrows, the counter, and Left/Right on the keyboard. Off by default. */
+    navigation?: boolean;
+    /** The strip of previews along the bottom. Off by default. */
+    thumbnails?: boolean;
+    /** The three dots, and what is under them. Off by default. */
+    menu?: boolean | ImageMenuOptions;
+    /**
+     * Take an image out of the set and move to the next one. Off by default, because it is
+     * destructive and only the caller knows whether it means anything on their page.
+     */
+    discardable?: boolean;
+    onDiscard?: (item: ImageItem, index: number) => void;
+    /** Whether the arrows and the strip wrap around at the ends. On by default. */
+    loop?: boolean;
+    /** The caption under the frame, when the item carries none of its own. */
+    caption?: ReactNode;
+    onOpenChange?: (open: boolean) => void;
+    onIndexChange?: (index: number, item: ImageItem) => void;
+    /** The viewer's stylesheet, injected once. There is no useful unstyled lightbox. */
+    styles?: boolean;
+    labels?: ImageLabels;
+    /** Props for the element wrapping the thumbnail - this is what you position. */
+    wrapperProps?: ComponentPropsWithoutRef<"span">;
+}
+/** A source in either spelling, as the one the viewer works in. */
+export function toItem(source: ImageSource): ImageItem {
+    return typeof source === "string" ? { src: source } : source;
+}