@enigmax/primitives 0.14.0 → 0.15.0

package/dist/{chunk-DD2X5B2J.js → chunk-53DQY6LP.js}

@@ -16,6 +16,7 @@ var DEFAULTS = {
   manageStyles: true,
   copies: "clone"
 };
+var MAX_COPIES = 24;
 function createMarquee(lane, track, options = {}) {
   let opts = { ...DEFAULTS, ...options };
   let period = 0;
@@ -80,7 +81,7 @@ function createMarquee(lane, track, options = {}) {
   }
   function requiredCopies(measured) {
     if (measured <= 0) return 2;
-    return Math.max(2, Math.ceil(axisSize(lane) / measured) + 1);
+    return Math.min(MAX_COPIES, Math.max(2, Math.ceil(axisSize(lane) / measured) + 1));
   }
   function syncClones(count) {
     const source = track.children[0];
@@ -241,6 +242,19 @@ function createMarquee(lane, track, options = {}) {
     if (first) resizeObserver?.observe(first);
     measure();
     void document.fonts?.ready.then(() => measure());
+    remeasureOnImageLoad();
+  }
+  function remeasureOnImageLoad() {
+    for (const image of track.querySelectorAll("img")) {
+      if (image.complete) continue;
+      const done = () => {
+        image.removeEventListener("load", done);
+        image.removeEventListener("error", done);
+        if (!destroyed) measure();
+      };
+      image.addEventListener("load", done);
+      image.addEventListener("error", done);
+    }
   }
   init();
   return {

package/dist/{chunk-YFM2FWHQ.js → chunk-U2KYYMBJ.js}

@@ -1,4 +1,4 @@
-import { generatePassword, estimatePasswordStrength, INPUT_ICON_PATHS, createNotifications, createButton, createMarquee, createInput, createNetworkMonitor, SERVER_NETWORK_STATE, relativeTimeView, relativeTimeAttributes } from './chunk-DD2X5B2J.js';
+import { generatePassword, estimatePasswordStrength, INPUT_ICON_PATHS, createNotifications, createButton, createMarquee, createInput, createNetworkMonitor, SERVER_NETWORK_STATE, relativeTimeView, relativeTimeAttributes } from './chunk-53DQY6LP.js';
 import { createSearch } from './chunk-UZFEEFMF.js';
 import { forwardRef, createElement, useRef, useState, useId, useCallback, useEffect, useMemo, useSyncExternalStore, useLayoutEffect } from 'react';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
@@ -680,6 +680,11 @@ function RelativeTime({
   ...rest
 }) {
   useEffect(loadElement, []);
+  const applyPrefix = useCallback((node) => {
+    if (!node) return;
+    if (prefix === void 0 || prefix === "") node.removeAttribute("prefix");
+    else node.setAttribute("prefix", prefix);
+  }, [prefix]);
   const options = {
     format,
     tense,
@@ -712,7 +717,8 @@ function RelativeTime({
   if (view.absoluteOnly) {
     return createElement("time", { dateTime: view.iso, title: noTitle ? void 0 : view.exact, ...marks, ...rest }, view.label);
   }
-  return createElement("relative-time", { ...relativeTimeAttributes(view, options), ...marks, ...rest }, view.label);
+  const { prefix: prefixAttribute, ...attributes } = relativeTimeAttributes(view, options);
+  return createElement("relative-time", { ...attributes, ...marks, ...rest, ref: applyPrefix }, view.label);
 }
 
 export { Button, Input, PasswordStrength, RelativeTime, Toaster, createNotificationQueue, defaultQueue, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useNetworkState, useNotifications, useSearch };

package/dist/index.d.ts

@@ -78,13 +78,6 @@ interface MarqueeInstance {
     resume(): void;
     destroy(): void;
 }
-/**
- * Wire a lane and its track into a draggable infinite marquee.
- *
- * @param lane  The clipping viewport. Receives the pointer and the click guard.
- * @param track The moved element. Its children are the repeated copies; child 0
- *              is the source content and must already be rendered.
- */
 declare function createMarquee(lane: HTMLElement, track: HTMLElement, options?: MarqueeOptions): MarqueeInstance;
 
 /**

package/dist/index.js

@@ -1,2 +1,2 @@
-export { INPUT_ICON_PATHS, SERVER_NETWORK_STATE, createButton, createInput, createMarquee, createNetworkMonitor, createNotifications, ensureZone, estimatePasswordStrength, generatePassword, iconMarkup, normalizeDate, parseDuration, relativeTimeAttributes, relativeTimeView } from './chunk-DD2X5B2J.js';
+export { INPUT_ICON_PATHS, SERVER_NETWORK_STATE, createButton, createInput, createMarquee, createNetworkMonitor, createNotifications, ensureZone, estimatePasswordStrength, generatePassword, iconMarkup, normalizeDate, parseDuration, relativeTimeAttributes, relativeTimeView } from './chunk-53DQY6LP.js';
 export { createSearch } from './chunk-UZFEEFMF.js';

package/dist/next/index.js

@@ -1,7 +1,7 @@
 "use client";
-import { Button } from '../chunk-YFM2FWHQ.js';
-export { Input, PasswordStrength, RelativeTime, Toaster, createNotificationQueue, defaultQueue, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useNetworkState, useNotifications, useSearch } from '../chunk-YFM2FWHQ.js';
-export { estimatePasswordStrength, generatePassword } from '../chunk-DD2X5B2J.js';
+import { Button } from '../chunk-U2KYYMBJ.js';
+export { Input, PasswordStrength, RelativeTime, Toaster, createNotificationQueue, defaultQueue, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useNetworkState, useNotifications, useSearch } from '../chunk-U2KYYMBJ.js';
+export { estimatePasswordStrength, generatePassword } from '../chunk-53DQY6LP.js';
 import '../chunk-UZFEEFMF.js';
 import Link from 'next/link';
 import { forwardRef, createElement } from 'react';

package/dist/react/index.js

@@ -1,4 +1,4 @@
 "use client";
-export { Button, Input, PasswordStrength, RelativeTime, Toaster, createNotificationQueue, defaultQueue, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useNetworkState, useNotifications, useSearch } from '../chunk-YFM2FWHQ.js';
-export { estimatePasswordStrength, generatePassword } from '../chunk-DD2X5B2J.js';
+export { Button, Input, PasswordStrength, RelativeTime, Toaster, createNotificationQueue, defaultQueue, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useNetworkState, useNotifications, useSearch } from '../chunk-U2KYYMBJ.js';
+export { estimatePasswordStrength, generatePassword } from '../chunk-53DQY6LP.js';
 import '../chunk-UZFEEFMF.js';

package/dist/react-router/index.js

@@ -1,7 +1,7 @@
 "use client";
-import { Button } from '../chunk-YFM2FWHQ.js';
-export { Input, PasswordStrength, RelativeTime, Toaster, createNotificationQueue, defaultQueue, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useNetworkState, useNotifications, useSearch } from '../chunk-YFM2FWHQ.js';
-export { estimatePasswordStrength, generatePassword } from '../chunk-DD2X5B2J.js';
+import { Button } from '../chunk-U2KYYMBJ.js';
+export { Input, PasswordStrength, RelativeTime, Toaster, createNotificationQueue, defaultQueue, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useNetworkState, useNotifications, useSearch } from '../chunk-U2KYYMBJ.js';
+export { estimatePasswordStrength, generatePassword } from '../chunk-53DQY6LP.js';
 import '../chunk-UZFEEFMF.js';
 import { Link } from 'react-router';
 import { forwardRef, createElement } from 'react';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enigmax/primitives",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Headless components: the behaviour, the timing and the accessibility, with no styles of their own. Framework-agnostic core plus thin adapters.",
   "type": "module",
   "main": "./dist/index.js",
@@ -30,7 +30,8 @@
     "./relative-time.css": "./recipes/relative-time/styles.css",
     "./toast.css": "./recipes/toast/styles.css",
     "./input.css": "./recipes/input/styles.css",
-    "./marquee.css": "./recipes/marquee/styles.css"
+    "./marquee.css": "./recipes/marquee/styles.css",
+    "./logo-marquee.css": "./recipes/logo-marquee/styles.css"
   },
   "scripts": {
     "build": "tsup",

package/recipes/logo-marquee/index.tsx

@@ -0,0 +1,103 @@
+import "./styles.css";
+import type { ReactNode, Ref } from "react";
+import { useMarquee, type MarqueeHover } from "@enigmax/primitives/react";
+
+/**
+ * The "trusted by" logo wall, yours to edit.
+ *
+ * A logo wall is a marquee with one extra job: the logos arrive at wildly different aspect
+ * ratios and optical weights, and a row that just drops them in reads as random. Normalising
+ * them to a common height is most of what makes it look designed.
+ *
+ * Some of the logos in any real wall are not images - Bloomberg, NASA and Harvard are set in
+ * type - so an item is either an image or a node.
+ */
+
+export type LogoItem =
+    | { kind: "img"; src: string; alt?: string; /** Override the shared height for one that reads small. */ height?: number; }
+    | { kind: "node"; node: ReactNode; key?: string; };
+
+export interface LogoMarqueeProps {
+    logos: LogoItem[];
+    /**
+     * Pixels per second. NEVER a duration: a lap is as long as its content, so seconds-per-
+     * loop makes the speed content/duration and the row runs faster every time a logo is
+     * added. Measured on one rail: 45, 67 and 87 px/s at 10, 15 and 20 items.
+     */
+    speed?: number;
+    /** Space between logos, in px. */
+    gap?: number;
+    /** Fade both ends, so logos enter and leave instead of being cut. */
+    fade?: boolean;
+    /**
+     * What a pointer resting on the row does: "off", "pause", a multiplier (0.15 crawls),
+     * or `{ speed }` for an absolute px/s.
+     */
+    hover?: MarqueeHover;
+    reverse?: boolean;
+    /** The shared optical height every image is scaled to. */
+    logoHeight?: number;
+    /**
+     * `mono` drains the colour so twelve brand palettes stop fighting each other, and
+     * restores it under the pointer. `brand` leaves them alone.
+     */
+    tone?: "brand" | "mono";
+    /** Names the row for a screen reader, e.g. "Trusted by". Untranslated by default. */
+    label?: string;
+    className?: string;
+}
+
+export function LogoMarquee({
+    logos,
+    speed = 40,
+    gap = 56,
+    fade = true,
+    hover = "off",
+    reverse = false,
+    logoHeight = 28,
+    tone = "mono",
+    label,
+    className = ""
+}: LogoMarqueeProps) {
+    const { laneRef, trackRef, copies, dragging } = useMarquee({ speed, hover, reverse });
+
+    const render = (item: LogoItem, index: number): ReactNode => (
+        <span className="logo-marquee__item" key={item.kind === "node" ? item.key ?? index : index}>
+            {item.kind === "img"
+                ? <img
+                    src={item.src}
+                    // Empty by default: a wall of brand names read out one after another is
+                    // noise, and `label` already says what the row is.
+                    alt={item.alt ?? ""}
+                    style={item.height ? { height: `${item.height}px` } : undefined}
+                    draggable={false}
+                    // Never lazy: the row measures its own lap from the rendered width, and
+                    // an image with no size yet measures as nothing.
+                    decoding="async"
+                />
+                : item.node}
+        </span>
+    );
+
+    return (
+        <div
+            ref={laneRef as Ref<HTMLDivElement>}
+            className={["logo-marquee", fade ? "is-faded" : "", className].filter(Boolean).join(" ")}
+            style={{ "--logo-marquee-gap": `${gap}px`, "--logo-marquee-height": `${logoHeight}px` } as React.CSSProperties}
+            data-tone={tone}
+            data-grabbing={dragging ? "" : undefined}
+            role={label ? "group" : undefined}
+            aria-label={label}
+        >
+            <div ref={trackRef as Ref<HTMLDivElement>} className="logo-marquee__track">
+                {Array.from({ length: copies }, (unused, copy) => (
+                    // Only the first copy is read: the rest are the same logos again, and a
+                    // screen reader announcing the wall three times is the bug this prevents.
+                    <div key={copy} aria-hidden={copy > 0} className="logo-marquee__copy">
+                        {logos.map(render)}
+                    </div>
+                ))}
+            </div>
+        </div>
+    );
+}

package/recipes/logo-marquee/styles.css

@@ -0,0 +1,74 @@
+/*
+ * The logo wall's look. Yours to edit - the behaviour above ships none of this.
+ *
+ * The two custom properties are set from the props, so the component never writes a class
+ * per gap or per height.
+ */
+
+.logo-marquee {
+    --logo-marquee-gap: 56px;
+    --logo-marquee-height: 28px;
+    position: relative;
+    overflow: hidden;
+    /* The lane's width must come from its container, never from its content. `width: 100%`
+       and `min-width: 0` say so explicitly, because a lane that sizes to max-content - a
+       grid cell with `justify-items: center`, a flex item without `min-width: 0` - grows to
+       fit the track, and a wider lane needs more copies, which makes it wider again. */
+    width: 100%;
+    min-width: 0;
+    /* Set by the primitive too, but declared here so the row still behaves before the
+       script runs: the page scrolls vertically, the drag takes the horizontal. */
+    touch-action: pan-y;
+    cursor: grab;
+}
+
+.logo-marquee[data-grabbing] { cursor: grabbing; }
+
+/* Both ends fade out, so a logo leaves rather than being sliced by the container edge. */
+.logo-marquee.is-faded {
+    -webkit-mask-image: linear-gradient(90deg, transparent, #000 8%, #000 92%, transparent);
+    mask-image: linear-gradient(90deg, transparent, #000 8%, #000 92%, transparent);
+}
+
+.logo-marquee__track { display: flex; width: max-content; }
+.logo-marquee__copy { display: flex; align-items: center; gap: var(--logo-marquee-gap); padding-right: var(--logo-marquee-gap); }
+
+.logo-marquee__item {
+    display: inline-flex;
+    align-items: center;
+    flex: 0 0 auto;
+    /* The whole trick of a logo wall: one optical height for everything, whatever the
+       source images measure, so a row of twelve brands reads as one row. */
+    height: var(--logo-marquee-height);
+    font-size: calc(var(--logo-marquee-height) * 0.72);
+    font-weight: 600;
+    line-height: 1;
+    white-space: nowrap;
+    user-select: none;
+}
+
+.logo-marquee__item img {
+    height: 100%;
+    /* Never stretched: a logo is the one image where the aspect ratio is the brand. */
+    width: auto;
+    object-fit: contain;
+    display: block;
+}
+
+/* Twelve brand palettes side by side fight each other and pull the eye off the copy, so
+   the default drains them - and gives the colour back to whichever one you point at. */
+.logo-marquee[data-tone="mono"] .logo-marquee__item {
+    filter: grayscale(1);
+    opacity: 0.65;
+    transition: filter 160ms ease-out, opacity 160ms ease-out;
+}
+
+.logo-marquee[data-tone="mono"] .logo-marquee__item:hover {
+    filter: grayscale(0);
+    opacity: 1;
+}
+
+@media (prefers-reduced-motion: reduce) {
+    /* The primitive already stops the autoplay; this stops the colour from animating too. */
+    .logo-marquee__item { transition: none; }
+}

package/recipes/relative-time/styles.css

@@ -3,22 +3,29 @@
  *
  *     import "@enigmax/utils/relative-time.css";
  *
+ * The element renders its output into a SHADOW ROOT, which is why these work the way they
+ * do: `text-transform` is an inherited property, so it crosses the boundary from the host
+ * and reaches text no outer selector could ever match. A descendant selector cannot - the
+ * light-DOM children are the fallback, not what you are looking at.
+ *
  * Both are opt-in per timestamp - the attributes only appear when you ask for them - and
- * both are marked !important on purpose: the element writes its own text content, so a
- * `text-transform` from a reset or a typography plugin lands on the same node and would
- * otherwise win on cascade order alone.
+ * both are !important on purpose: the transform lands on the host, where a reset or a
+ * typography plugin would otherwise win on cascade order alone.
  */
 
 /* Title Case Every Word. Reads oddly on "2 Days Ago"; usually you want the rule below. */
-[data-relative-time-capitalize="true"],
-[data-relative-time-capitalize="true"] * {
+[data-relative-time-capitalize="true"] {
     text-transform: capitalize !important;
 }
 
-/* Just the first letter, so a standalone "yesterday" starts a line properly. The nested
-   selectors cover the element wrapping its text in a child, which it does for some formats. */
-[data-relative-time-capitalize-first-letter="true"]::first-letter,
-[data-relative-time-capitalize-first-letter="true"] *::first-letter,
-[data-relative-time-capitalize-first-letter="true"] * *::first-letter {
+/* Just the first letter, so a standalone "yesterday" starts a line properly.
+   `::first-letter` only applies to a BLOCK container and the element is inline, so the
+   host is made inline-block for it - scoped to the hook, so a timestamp that did not ask
+   for this keeps its inline layout. */
+[data-relative-time-capitalize-first-letter="true"] {
+    display: inline-block;
+}
+
+[data-relative-time-capitalize-first-letter="true"]::first-letter {
     text-transform: uppercase !important;
 }

package/registry.json

@@ -91,6 +91,68 @@
         "css"
       ]
     },
+    {
+      "name": "logo-marquee",
+      "title": "Logo wall",
+      "description": "The \"trusted by\" row: a marquee that also does the job a logo wall needs doing - one optical height for logos that arrive at a dozen different sizes, colour drained so twelve brand palettes stop fighting, and text logos like NASA or Bloomberg alongside the images.",
+      "targets": [
+        "react"
+      ],
+      "entry": {
+        "react": "@enigmax/primitives/react"
+      },
+      "exports": {
+        "react": [
+          "LogoMarquee"
+        ]
+      },
+      "files": [
+        {
+          "path": "src/core/marquee.ts",
+          "dest": "logo-marquee/marquee.ts",
+          "targets": [
+            "react"
+          ]
+        },
+        {
+          "path": "src/react/use-marquee.ts",
+          "dest": "logo-marquee/use-marquee.ts",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/core/marquee": "./marquee"
+          }
+        },
+        {
+          "path": "recipes/logo-marquee/styles.css",
+          "dest": "logo-marquee/styles.css",
+          "targets": [
+            "react"
+          ]
+        },
+        {
+          "path": "recipes/logo-marquee/index.tsx",
+          "dest": "logo-marquee/index.tsx",
+          "main": true,
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@enigmax/primitives/react": "./use-marquee"
+          }
+        }
+      ],
+      "styles": true,
+      "themeHooks": [
+        "[data-tone=mono]",
+        ".logo-marquee",
+        ".logo-marquee.is-faded",
+        ".logo-marquee[data-grabbing]",
+        ".logo-marquee__item"
+      ],
+      "docs": "docs/notes/primitives.md#logo-marquee"
+    },
     {
       "name": "input",
       "title": "Input, with what a password field needs",

package/src/core/marquee.ts

@@ -121,6 +121,9 @@ const DEFAULTS: ResolvedOptions = {
  * @param track The moved element. Its children are the repeated copies; child 0
  *              is the source content and must already be rendered.
  */
+/** Ceiling on the copy count. See requiredCopies for why a ceiling is needed at all. */
+const MAX_COPIES = 24;
+
 export function createMarquee(lane: HTMLElement, track: HTMLElement, options: MarqueeOptions = {}): MarqueeInstance {
     let opts: ResolvedOptions = { ...DEFAULTS, ...options };
 
@@ -211,7 +214,14 @@ export function createMarquee(lane: HTMLElement, track: HTMLElement, options: Ma
     /** Non-negotiable 2: the lane plus one whole period, so there is always one to wrap into. */
     function requiredCopies(measured: number): number {
         if (measured <= 0) return 2;
-        return Math.max(2, Math.ceil(axisSize(lane) / measured) + 1);
+        // Capped, because the measurement can be transiently TINY rather than zero: a row
+        // of images measured before they load is a few pixels wide, and lane/period then
+        // asks for hundreds of copies. In React that renders hundreds of subtrees before
+        // the images arrive to correct it, which trips the update-depth limit and takes the
+        // page down - the zero guard above does not catch it because the width is not zero.
+        // The cap is far past any real wall; a copy narrow enough to need more than this is
+        // a measurement that has not settled yet, and the ResizeObserver will come back.
+        return Math.min(MAX_COPIES, Math.max(2, Math.ceil(axisSize(lane) / measured) + 1));
     }
 
     function syncClones(count: number): void {
@@ -437,6 +447,27 @@ export function createMarquee(lane: HTMLElement, track: HTMLElement, options: Ma
         measure();
         // A late font changes every width the lap was measured from.
         void document.fonts?.ready.then(() => measure());
+        // So does a late IMAGE, and that one is the common case: a logo wall measured
+        // before its logos have loaded reads as a few pixels wide, which asks for far more
+        // copies than the row needs. The ResizeObserver above sees the first copy resize,
+        // but only while that exact node survives - a framework re-rendering the copies
+        // replaces it - so the images are waited on directly.
+        remeasureOnImageLoad();
+    }
+
+    /** Re-measure once each image that had not loaded at mount finishes. */
+    function remeasureOnImageLoad(): void {
+        for (const image of track.querySelectorAll("img")) {
+            if (image.complete) continue;
+            const done = (): void => {
+                image.removeEventListener("load", done);
+                image.removeEventListener("error", done);
+                if (!destroyed) measure();
+            };
+            // `error` too: a logo that 404s still settles the layout it was holding open.
+            image.addEventListener("load", done);
+            image.addEventListener("error", done);
+        }
     }
 
     init();

package/src/react/relative-time.ts

@@ -1,6 +1,6 @@
 "use client";
 
-import { createElement, useEffect, type HTMLAttributes, type ReactNode } from "react";
+import { createElement, useCallback, useEffect, type HTMLAttributes, type ReactNode } from "react";
 import { relativeTimeView, relativeTimeAttributes, type RelativeTimeOptions } from "@/core/relative-time";
 
 /**
@@ -75,6 +75,22 @@ export function RelativeTime({
 }: RelativeTimeProps): ReactNode {
     useEffect(loadElement, []);
 
+    /**
+     * `prefix` is set through the DOM, never as a React prop.
+     *
+     * `Element.prototype.prefix` is a read-only accessor (the XML namespace prefix), and
+     * React sets a KNOWN property rather than an attribute - so passing it through throws
+     * "Cannot set property prefix of #<Element> which has only a getter" and takes the
+     * whole tree down with it. It is the only attribute here that collides; the rest are
+     * either kebab-cased or writable. Applied on the ref, which runs before the custom
+     * element upgrades, so the element still reads it.
+     */
+    const applyPrefix = useCallback((node: HTMLElement | null) => {
+        if (!node) return;
+        if (prefix === undefined || prefix === "") node.removeAttribute("prefix");
+        else node.setAttribute("prefix", prefix);
+    }, [prefix]);
+
     const options: RelativeTimeOptions = {
         format, tense, precision, threshold, prefix, formatStyle, locale, timeZone,
         second, minute, hour, weekday, day, month, year, timeZoneName, noTitle, numericBeyondThreshold
@@ -99,5 +115,6 @@ export function RelativeTime({
     // createElement rather than JSX: `<relative-time>` is not a known intrinsic element, and
     // declaring it means augmenting React's JSX namespace from inside a published package -
     // which collides with any consumer that declared it too, differently.
-    return createElement("relative-time", { ...relativeTimeAttributes(view, options), ...marks, ...rest }, view.label);
+    const { prefix: prefixAttribute, ...attributes } = relativeTimeAttributes(view, options);
+    return createElement("relative-time", { ...attributes, ...marks, ...rest, ref: applyPrefix }, view.label);
 }