@enigmax/primitives 0.26.0 → 0.28.0

package/registry.json

@@ -86,6 +86,7 @@
         "[data-enigma-marquee-copy]"
       ],
       "docs": "docs/notes/primitives.md#marquee",
+      "source": "src/core/marquee.ts",
       "recipes": [
         "tailwind",
         "css"
@@ -151,7 +152,8 @@
         ".logo-marquee[data-grabbing]",
         ".logo-marquee__item"
       ],
-      "docs": "docs/notes/primitives.md#logo-marquee"
+      "docs": "docs/notes/primitives.md#logo-marquee",
+      "source": "recipes/logo-marquee/index.tsx"
     },
     {
       "name": "input",
@@ -286,6 +288,23 @@
             "react"
           ]
         },
+        {
+          "path": "src/core/floating.ts",
+          "dest": "input/floating-core.ts",
+          "targets": [
+            "react"
+          ]
+        },
+        {
+          "path": "src/react/floating.ts",
+          "dest": "input/floating.ts",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/core/floating": "./floating-core"
+          }
+        },
         {
           "path": "src/react/input/color.tsx",
           "dest": "input/color.tsx",
@@ -297,7 +316,8 @@
             "@/react/input/write-value": "./write-value",
             "@/react/input/color-styles": "./color-styles",
             "@/react/input/types": "./types",
-            "@/react/input/color-swatch": "./color-swatch"
+            "@/react/input/color-swatch": "./color-swatch",
+            "@/react/floating": "./floating"
           }
         },
         {
@@ -392,6 +412,7 @@
         "[data-enigma-color-preset]"
       ],
       "docs": "docs/notes/primitives.md#input",
+      "source": "src/core/input.ts",
       "recipes": [
         "tailwind",
         "css"
@@ -460,6 +481,7 @@
         "fuse.js": "Fuzzy matching. Omit it and a built-in substring matcher is used."
       },
       "docs": "docs/notes/primitives.md#search",
+      "source": "src/core/search.ts",
       "recipes": [
         "tailwind"
       ],
@@ -551,7 +573,8 @@
         "[aria-busy=true]",
         "[data-enigma-button-key]"
       ],
-      "docs": "docs/notes/primitives.md#button"
+      "docs": "docs/notes/primitives.md#button",
+      "source": "src/core/button.ts"
     },
     {
       "name": "palette",
@@ -656,6 +679,7 @@
         "[data-enigma-palette-hint]"
       ],
       "docs": "docs/notes/primitives.md#palette",
+      "source": "src/core/palette.ts",
       "recipes": [
         "css"
       ]
@@ -742,6 +766,23 @@
             "@/core/select": "./select"
           }
         },
+        {
+          "path": "src/core/floating.ts",
+          "dest": "select/floating-core.ts",
+          "targets": [
+            "react"
+          ]
+        },
+        {
+          "path": "src/react/floating.ts",
+          "dest": "select/floating.ts",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/core/floating": "./floating-core"
+          }
+        },
         {
           "path": "src/react/select/root.tsx",
           "dest": "select/root.tsx",
@@ -754,7 +795,8 @@
             "@/core/search": "./search-core",
             "@/react/slot": "./slot",
             "@/react/select/styles": "./styles",
-            "@/react/select/context": "./context"
+            "@/react/select/context": "./context",
+            "@/react/floating": "./floating"
           }
         },
         {
@@ -799,6 +841,7 @@
         "[data-enigma-select-empty]"
       ],
       "docs": "docs/notes/primitives.md#select",
+      "source": "src/core/select.ts",
       "recipes": [
         "css"
       ]
@@ -888,6 +931,23 @@
             "@/core/context-menu": "./context-menu"
           }
         },
+        {
+          "path": "src/core/floating.ts",
+          "dest": "context-menu/floating-core.ts",
+          "targets": [
+            "react"
+          ]
+        },
+        {
+          "path": "src/react/floating.ts",
+          "dest": "context-menu/floating.ts",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/core/floating": "./floating-core"
+          }
+        },
         {
           "path": "src/react/context-menu/root.tsx",
           "dest": "context-menu/root.tsx",
@@ -901,7 +961,9 @@
             "@/react/slot": "./slot",
             "@/react/context-menu/styles": "./styles",
             "@/react/context-menu/context": "./context",
-            "@/core/clipboard-menu": "./clipboard-menu"
+            "@/core/clipboard-menu": "./clipboard-menu",
+            "@/react/floating": "./floating",
+            "@/core/floating": "./floating-core"
           }
         },
         {
@@ -946,6 +1008,7 @@
         "[data-enigma-menu-status][data-error]"
       ],
       "docs": "docs/notes/primitives.md#context-menu",
+      "source": "src/core/context-menu.ts",
       "recipes": [
         "css"
       ]
@@ -1019,7 +1082,8 @@
         "[data-enigma-selection-marquee]",
         "[data-enigma-selection-empty]"
       ],
-      "docs": "docs/notes/primitives.md#selection"
+      "docs": "docs/notes/primitives.md#selection",
+      "source": "src/core/selection.ts"
     },
     {
       "name": "flags",
@@ -1081,7 +1145,8 @@
         "[data-enigma-flag][data-flag-shape=circle]"
       ],
       "assets": "flags",
-      "docs": "docs/notes/primitives.md#flags"
+      "docs": "docs/notes/primitives.md#flags",
+      "source": "src/core/flags.ts"
     },
     {
       "name": "notifications",
@@ -1140,6 +1205,7 @@
       ],
       "styles": false,
       "docs": "docs/notes/primitives.md#notifications",
+      "source": "src/core/notifications.ts",
       "recipes": [
         "tailwind"
       ]
@@ -1278,6 +1344,7 @@
         "[data-icon]"
       ],
       "docs": "docs/notes/primitives.md#toast",
+      "source": "src/react/toaster.tsx",
       "recipes": [
         "tailwind",
         "css"
@@ -1331,7 +1398,8 @@
         }
       ],
       "styles": false,
-      "docs": "docs/notes/primitives.md#network"
+      "docs": "docs/notes/primitives.md#network",
+      "source": "src/core/network.ts"
     },
     {
       "name": "relative-time",
@@ -1399,6 +1467,7 @@
         "[data-relative-time-capitalize-first-letter=true]"
       ],
       "docs": "docs/notes/primitives.md#relative-time",
+      "source": "src/core/relative-time.ts",
       "dependencies": {
         "@github/relative-time-element": "^4.4.0"
       }
@@ -1528,6 +1597,23 @@
             "@/react/context-menu/styles": "./context-menu-styles"
           }
         },
+        {
+          "path": "src/core/floating.ts",
+          "dest": "image/floating-core.ts",
+          "targets": [
+            "react"
+          ]
+        },
+        {
+          "path": "src/react/floating.ts",
+          "dest": "image/floating.ts",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/core/floating": "./floating-core"
+          }
+        },
         {
           "path": "src/react/context-menu/root.tsx",
           "dest": "image/root.tsx",
@@ -1541,7 +1627,9 @@
             "@/react/slot": "./slot",
             "@/react/context-menu/styles": "./context-menu-styles",
             "@/react/context-menu/context": "./context",
-            "@/core/clipboard-menu": "./clipboard-menu"
+            "@/core/clipboard-menu": "./clipboard-menu",
+            "@/react/floating": "./floating",
+            "@/core/floating": "./floating-core"
           }
         },
         {
@@ -1632,6 +1720,7 @@
         "[data-enigma-image-frame][data-flying]"
       ],
       "docs": "docs/notes/primitives.md#image",
+      "source": "src/core/image-viewer.ts",
       "recipes": [
         "css"
       ]
@@ -1730,6 +1819,23 @@
             "@/react/context-menu/styles": "./context-menu-styles"
           }
         },
+        {
+          "path": "src/core/floating.ts",
+          "dest": "video/floating-core.ts",
+          "targets": [
+            "react"
+          ]
+        },
+        {
+          "path": "src/react/floating.ts",
+          "dest": "video/floating.ts",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/core/floating": "./floating-core"
+          }
+        },
         {
           "path": "src/react/context-menu/root.tsx",
           "dest": "video/root.tsx",
@@ -1743,7 +1849,9 @@
             "@/react/slot": "./slot",
             "@/react/context-menu/styles": "./context-menu-styles",
             "@/react/context-menu/context": "./context",
-            "@/core/clipboard-menu": "./clipboard-menu"
+            "@/core/clipboard-menu": "./clipboard-menu",
+            "@/react/floating": "./floating",
+            "@/core/floating": "./floating-core"
           }
         },
         {
@@ -1864,6 +1972,7 @@
         "[data-enigma-video][data-casting]"
       ],
       "docs": "docs/notes/primitives.md#video",
+      "source": "src/core/player.ts",
       "recipes": [
         "css"
       ]

package/src/core/context-menu.ts

@@ -82,8 +82,18 @@ export function isAction(entry: ContextMenuEntry): entry is ContextMenuAction {
 /** The fields the filter reads when the caller does not say. */
 export const CONTEXT_MENU_SEARCH_KEYS = ["label", "description", "group", "keywords"];
 
-/** Filtering six rows is worth a field; filtering three is a bigger panel for nothing. */
-export const SEARCHABLE_FROM = 8;
+/**
+ * How many rows a level needs before it grows a filter on its own.
+ *
+ * Raised from 8, which turned out to be a number you can still READ. A menu of eight is
+ * scanned in one look, so the field was a row of chrome, a focus stop and a taller panel in
+ * exchange for nothing - the video player's own menu, at nine rows, is what showed it. Twelve
+ * is about where a list stops being a shape and starts being a list.
+ *
+ * It is only the DEFAULT. A menu whose rows arrive from somewhere - a list of files, a
+ * directory, anything fetched - says `searchable` and does not wait to grow into it.
+ */
+export const SEARCHABLE_FROM = 12;
 
 /** Where a menu was opened. Viewport coordinates, which is what a pointer event reports. */
 export interface ContextMenuPoint {
@@ -141,6 +151,12 @@ export interface ContextMenuOptions {
     /** A row was invoked. The menu has already closed unless the row keeps it open. */
     onSelect?: (item: ContextMenuAction, path: string[]) => void;
     onOpenChange?: (open: boolean) => void;
+    /**
+     * Whether the ROOT level draws a filter. `"auto"` (the default) grows one from
+     * `SEARCHABLE_FROM` rows; `true` puts one there whatever the count, which is what a menu
+     * filling itself from somewhere wants; `false` never does.
+     */
+    searchable?: boolean | "auto";
 }
 
 export interface ContextMenuInstance {
@@ -235,7 +251,10 @@ export function createContextMenu(options: ContextMenuOptions = {}): ContextMenu
     }
 
     function searchableFor(item: ContextMenuAction | null, entries: readonly ContextMenuEntry[]): boolean {
-        const asked = item?.searchable ?? "auto";
+        // The root has no item to carry the answer, so it reads the menu's own option - which
+        // is the only way a caller can turn the field on for rows they are about to fetch, or
+        // off for a menu they know is short.
+        const asked = (item ? item.searchable : opts.searchable) ?? "auto";
         if (asked !== "auto") return asked;
         return entries.filter(isAction).length >= SEARCHABLE_FROM;
     }

package/src/core/floating.ts

@@ -0,0 +1,71 @@
+/**
+ * Where a floating panel goes: below or above the thing that opened it, inside the window.
+ *
+ * One function for every popup here - the select's list, the colour picker, the context menu
+ * - because they are the same question with different anchors. The select and the picker
+ * hang from a trigger's box; the context menu hangs from the pointer, which is the same box
+ * with no size. Pure arithmetic on rectangles, so it has no DOM and no framework: the React
+ * half that measures and applies it is `react/floating.ts`.
+ */
+
+/** A box in viewport coordinates, the shape `getBoundingClientRect()` returns. */
+export interface FloatingRect {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+
+export type FloatingSide = "top" | "bottom";
+
+export interface FloatingOptions {
+    /** The area the panel has to stay inside - the window, or less when something clips it. */
+    boundary: FloatingRect;
+    /** Kept clear of the boundary's edge, so a panel never sits flush against it. */
+    margin?: number;
+    /** Between the anchor and the panel. */
+    gap?: number;
+    /** A side the caller insists on. `"auto"` (the default) measures. */
+    side?: FloatingSide | "auto";
+}
+
+export interface FloatingPlacement {
+    left: number;
+    top: number;
+    side: FloatingSide;
+    /**
+     * The tallest the panel can be on that side without leaving the boundary. Applied as a
+     * `max-height`, so a list longer than the room scrolls inside the panel instead of
+     * running off the screen where its last rows cannot be reached.
+     */
+    maxHeight: number;
+}
+
+/**
+ * Below when it fits, above when it does not and there is more room there.
+ *
+ * Flipped only when the other side is genuinely roomier: near the bottom of the window an
+ * unflipped panel hangs off the screen, but flipping a panel that fits neither way into the
+ * SMALLER side just moves the problem. Whichever side wins, `maxHeight` is the room it has.
+ *
+ * Horizontally it starts at the anchor's left edge and flips to end at its right edge when
+ * it would run past the window - flipped rather than dragged back, because a context menu
+ * dragged back to fit sits under the pointer and the release chooses its first row. The
+ * clamp after it only matters for a panel wider than the room on both sides.
+ */
+export function placeFloating(anchor: FloatingRect, size: { width: number; height: number; }, options: FloatingOptions): FloatingPlacement {
+    const { boundary, margin = 8, gap = 0, side = "auto" } = options;
+    const below = boundary.bottom - margin - anchor.bottom - gap;
+    const above = anchor.top - gap - boundary.top - margin;
+    const chosen: FloatingSide = side !== "auto" ? side : size.height <= below || below >= above ? "bottom" : "top";
+    const maxHeight = Math.max(0, Math.floor(chosen === "bottom" ? below : above));
+    const height = Math.min(size.height, maxHeight);
+    const top = chosen === "bottom" ? anchor.bottom + gap : anchor.top - gap - height;
+
+    const maxLeft = boundary.right - margin - size.width;
+    let left = anchor.left;
+    if (left > maxLeft) left = anchor.right - size.width;
+    left = Math.max(boundary.left + margin, Math.min(left, maxLeft));
+
+    return { left: Math.round(left), top: Math.round(top), side: chosen, maxHeight };
+}

package/src/core/image-viewer.ts

@@ -174,6 +174,53 @@ function saveAs(href: string, name: string, external = false): void {
     anchor.remove();
 }
 
+/**
+ * A `data:` URL as the bytes it stands for.
+ *
+ * Synchronous on purpose: it is used to open a tab, and a window opened after an `await` is a
+ * popup with no gesture behind it, which the browser blocks.
+ */
+export function dataUrlToBlob(url: string): Blob {
+    const comma = url.indexOf(",");
+    if (!url.startsWith("data:") || comma === -1) throw new Error("not a data URL");
+    const head = url.slice("data:".length, comma);
+    const body = url.slice(comma + 1);
+    const base64 = head.endsWith(";base64");
+    const type = (base64 ? head.slice(0, -";base64".length) : head) || "text/plain";
+    if (!base64) return new Blob([decodeURIComponent(body)], { type });
+
+    const binary = atob(body);
+    const bytes = new Uint8Array(binary.length);
+    for (let at = 0; at < binary.length; at += 1) bytes[at] = binary.charCodeAt(at);
+    return new Blob([bytes], { type });
+}
+
+/**
+ * The picture on its own, in another tab.
+ *
+ * Chromium refuses a top-level navigation to a `data:` URL - it was a phishing vector - so a
+ * row that just called `window.open` on one did nothing at all, silently, which is how it
+ * shipped. Those are handed over as a blob instead; everything else opens as it is.
+ *
+ * `noopener` on both: the new tab must not get a handle on the page that opened it.
+ */
+export function openInNewTab(url: string): void {
+    if (typeof window === "undefined") return;
+    if (!url.startsWith("data:")) {
+        window.open(url, "_blank", "noopener,noreferrer");
+        return;
+    }
+    try {
+        const href = URL.createObjectURL(dataUrlToBlob(url));
+        window.open(href, "_blank", "noopener,noreferrer");
+        // Revoked later, not now: the tab has not finished reading it yet.
+        setTimeout(() => URL.revokeObjectURL(href), 60_000);
+    } catch {
+        // Undecodable, or a blocked popup. Better the browser's own refusal than a throw.
+        window.open(url, "_blank", "noopener,noreferrer");
+    }
+}
+
 /* -------- the flight from the thumbnail into the viewer -------- */
 
 /** How long the picture takes to fly, when the stylesheet does not say otherwise. */

package/src/core/player.ts

@@ -150,6 +150,48 @@ export async function togglePip(video: HTMLVideoElement): Promise<void> {
     await video.requestPictureInPicture();
 }
 
+/* -------- what a source IS -------- */
+
+/**
+ * The MIME types worth naming from a file extension, and nothing else.
+ *
+ * Deliberately short. A `<source>` with no `type` makes the browser fetch and sniff, which
+ * costs a request and always works; a `<source>` with the WRONG type is skipped outright, and
+ * the video then does not play at all. So a guess is more expensive than silence, and only
+ * extensions that mean one thing are in here.
+ */
+const SOURCE_TYPES: Record<string, string> = {
+    mp4: "video/mp4",
+    m4v: "video/mp4",
+    webm: "video/webm",
+    ogv: "video/ogg",
+    mov: "video/quicktime",
+    mkv: "video/x-matroska",
+    m3u8: "application/vnd.apple.mpegurl",
+    mpd: "application/dash+xml"
+};
+
+/**
+ * The type a URL's extension implies, or undefined.
+ *
+ * Read from the PATH, so a query string or a fragment cannot be mistaken for one -
+ * `/clip.mp4?token=...` is still an mp4, and `/download?file=x.webm` is not a webm, because
+ * the extension has to be on the path's last segment. A `blob:` or `data:` URL has no
+ * extension to read and gets nothing, which is the right answer: the browser sniffs.
+ */
+export function sourceType(url: string): string | undefined {
+    let path = url;
+    try {
+        path = new URL(url, typeof location === "undefined" ? "https://localhost" : location.href).pathname;
+    } catch {
+        path = url.split("?")[0]!.split("#")[0]!;
+    }
+    const name = path.split("/").pop() ?? "";
+    const dot = name.lastIndexOf(".");
+    if (dot <= 0) return undefined;
+    return SOURCE_TYPES[name.slice(dot + 1).toLowerCase()];
+}
+
 /* -------- captions -------- */
 
 /** One subtitle track, as the menu lists it. */

package/src/index.ts

@@ -167,6 +167,8 @@ export {
     downloadFile,
     flightFrom,
     flightMs,
+    openInNewTab,
+    dataUrlToBlob,
     prefersReducedMotion,
     FLIGHT_MS,
     IDENTITY,
@@ -190,6 +192,7 @@ export {
     toggleFullscreen,
     supportsPip,
     togglePip,
+    sourceType,
     captionTracks,
     activeCaption,
     showCaption,