@design-edito/tools 0.3.10 → 0.3.12

package/components/Gallery/index.js

@@ -0,0 +1,173 @@
+// src/components/Gallery/index.tsx
+import {
+  Children,
+  useEffect,
+  useState,
+  useRef
+} from "react";
+import { clss } from "../../agnostic/css/clss/index.js";
+import { mergeClassNames } from "../utils/index.js";
+import { gallery as publicClassName } from "../public-classnames.js";
+import { forceActivateSlot } from "./utils.js";
+import cssModule from "./styles.module.css";
+import { jsx, jsxs } from "react/jsx-runtime";
+var Gallery = ({
+  paddingLeft,
+  paddingRight,
+  padding,
+  prevButtonContent,
+  nextButtonContent,
+  paginationContent,
+  initActive,
+  active,
+  noSnap,
+  stateHandlers,
+  actionHandlers,
+  children,
+  className
+}) => {
+  const scrollerRef = useRef(null);
+  const [activeIndex, setActiveIndex] = useState(0);
+  const [canGoLeft, setCanGoLeft] = useState(false);
+  const [canGoRight, setCanGoRight] = useState(false);
+  const childrenCount = Children.count(children);
+  useEffect(() => {
+    stateHandlers?.slotChanged?.(activeIndex);
+  }, [activeIndex]);
+  const handlePrevClick = () => {
+    actionHandlers?.prevClick?.(activeIndex);
+    if (active === void 0) forceActivateSlot(scrollerRef.current, activeIndex - 1);
+  };
+  const handleNextClick = () => {
+    actionHandlers?.nextClick?.(activeIndex);
+    if (active === void 0) forceActivateSlot(scrollerRef.current, activeIndex + 1);
+  };
+  const handlePaginationClick = (pos) => {
+    actionHandlers?.paginationClick?.(activeIndex, pos);
+    if (active === void 0) forceActivateSlot(scrollerRef.current, pos);
+  };
+  useEffect(() => {
+    const scrollerElt = scrollerRef.current;
+    if (scrollerElt === null) return;
+    scrollerElt.scrollBy(-1, 0);
+    let animationFrame = null;
+    const update = () => {
+      animationFrame = null;
+      const { scrollLeft, clientWidth, scrollWidth } = scrollerElt;
+      const center = scrollLeft + clientWidth / 2;
+      const children2 = Array.from(scrollerElt.children);
+      let closestIndex = 0;
+      let closestDistance = Infinity;
+      children2.forEach((child, index) => {
+        const childCenter = child.offsetLeft + child.offsetWidth / 2;
+        const distance = Math.abs(center - childCenter);
+        if (distance < closestDistance) {
+          closestDistance = distance;
+          closestIndex = index;
+        }
+      });
+      setActiveIndex(closestIndex);
+      setCanGoLeft(scrollLeft > 0);
+      setCanGoRight(scrollLeft + clientWidth < scrollWidth);
+    };
+    const onScroll = () => {
+      if (animationFrame !== null) return;
+      animationFrame = requestAnimationFrame(update);
+    };
+    scrollerElt.addEventListener("scroll", onScroll, { passive: true });
+    update();
+    return () => {
+      scrollerElt.removeEventListener("scroll", onScroll);
+      if (animationFrame !== null) cancelAnimationFrame(animationFrame);
+    };
+  }, []);
+  useEffect(() => {
+    const toActivate = active ?? initActive;
+    if (toActivate === void 0) return;
+    const id = setTimeout(() => forceActivateSlot(scrollerRef.current, toActivate, false), 50);
+    return () => clearTimeout(id);
+  }, []);
+  useEffect(() => {
+    if (active === void 0) return;
+    forceActivateSlot(scrollerRef.current, active);
+  }, [active]);
+  const c = clss(publicClassName, { cssModule });
+  const rootClss = mergeClassNames(
+    c(null, {
+      "controlled": active !== void 0,
+      "no-snap": noSnap === true,
+      "at-first": activeIndex === 0,
+      "at-last": activeIndex === childrenCount - 1,
+      "can-go-left": canGoLeft,
+      "can-go-right": canGoRight
+    }),
+    className
+  );
+  const scrollerClss = c("scroller");
+  const actionsClss = c("actions");
+  const prevBtnClss = c("prev");
+  const nextBtnClss = c("next");
+  const paginationClss = c("pagination");
+  const dataAttributes = { "data-active": `${activeIndex}` };
+  const actualPaddingLeft = typeof paddingLeft === "number" ? `${paddingLeft}px` : typeof paddingLeft === "string" ? paddingLeft : typeof padding === "number" ? `${padding}px` : padding ?? "0px";
+  const actualPaddingRight = typeof paddingRight === "number" ? `${paddingRight}px` : typeof paddingRight === "string" ? paddingRight : typeof padding === "number" ? `${padding}px` : padding ?? "0px";
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: rootClss,
+      ...dataAttributes,
+      children: [
+        /* @__PURE__ */ jsx("div", { className: scrollerClss, ref: scrollerRef, children: Children.map(children, (child, pos) => {
+          const slotClss = c("slot", { active: pos === activeIndex });
+          const style = {
+            "margin-left": pos === 0 ? actualPaddingLeft : void 0,
+            "margin-right": pos === Children.count(children) - 1 ? actualPaddingRight : void 0
+          };
+          return /* @__PURE__ */ jsx(
+            "div",
+            {
+              className: `${slotClss}`,
+              style: { ...style },
+              "data-slot": pos,
+              children: child
+            },
+            pos
+          );
+        }) }),
+        /* @__PURE__ */ jsxs("div", { className: actionsClss, children: [
+          /* @__PURE__ */ jsx(
+            "div",
+            {
+              className: prevBtnClss,
+              onClick: handlePrevClick,
+              children: prevButtonContent ?? "prev"
+            }
+          ),
+          /* @__PURE__ */ jsx(
+            "div",
+            {
+              className: nextBtnClss,
+              onClick: handleNextClick,
+              children: nextButtonContent ?? "next"
+            }
+          )
+        ] }),
+        /* @__PURE__ */ jsx("div", { className: paginationClss, children: Children.map(children, (_, pos) => {
+          const pageClss = c("page", { active: pos === activeIndex });
+          return /* @__PURE__ */ jsx(
+            "div",
+            {
+              className: pageClss,
+              "data-page": pos,
+              onClick: () => handlePaginationClick(pos),
+              children: typeof paginationContent === "string" ? paginationContent : typeof paginationContent === "function" ? paginationContent(pos) : pos
+            }
+          );
+        }) })
+      ]
+    }
+  );
+};
+export {
+  Gallery
+};

package/components/Gallery/styles.module.css

@@ -0,0 +1,33 @@
+.scroller {
+  display: flex;
+  overflow-x: auto;
+  scroll-snap-type: x mandatory;
+  scroll-behavior: smooth;
+  -webkit-overflow-scrolling: touch;
+  scrollbar-width: none;
+  -ms-overflow-style: none;
+  scrollbar-color: transparent transparent;
+}
+
+.scroller::-webkit-scrollbar {
+  display: none;
+  height: 0;
+}
+
+.scroller::-webkit-scrollbar-track,
+.scroller::-webkit-scrollbar-thumb {
+  background: transparent;
+}
+
+.root.root--controlled .scroller {
+  overflow-x: hidden;
+}
+
+.root.root--no-snap .scroller {
+  scroll-snap-type: unset;
+  scroll-behavior: unset;
+}
+
+.slot {
+  scroll-snap-align: center;
+}

package/components/Gallery/utils.d.ts

@@ -0,0 +1 @@
+export declare const forceActivateSlot: (div: HTMLDivElement | null, targetPos: number, smooth?: boolean) => void;

package/components/Image/index.d.ts

@@ -0,0 +1,60 @@
+import { type FunctionComponent, type ImgHTMLAttributes } from 'react';
+import { type Props as DisclaimerProps } from '../Disclaimer/index.js';
+import { type Props as TheatreProps } from '../Theatre/index.js';
+import type { WithClassName } from '../utils/types.js';
+/**
+ * Describes a single responsive image source for use in a `<picture>` element.
+ *
+ * @property srcSet - One or more image URLs with optional width/density descriptors
+ * (e.g. `'img@2x.png 2x'`).
+ * @property type - MIME type hint for the source (e.g. `'image/webp'`).
+ * @property media - Media condition under which this source is selected
+ * (e.g. `'(max-width: 768px)'`).
+ * @property sizes - Sizes attribute forwarded to the `<source>` element.
+ */
+type SourceData = {
+    srcSet?: string;
+    type?: string;
+    media?: string;
+    sizes?: string;
+};
+/**
+ * Props for the {@link Image} component.
+ *
+ * Extends all native `ImgHTMLAttributes<HTMLImageElement>`, so any standard
+ * img attribute (`alt`, `loading`, `sizes`, `srcSet`, etc.) can be passed
+ * and will be forwarded to the underlying `<img>` element.
+ *
+ * @property sources - One or more responsive sources rendered as `<source>`
+ * elements inside a wrapping `<picture>`. Accepts:
+ * - a single srcSet string,
+ * - an array of srcSet strings,
+ * - an array of {@link SourceData} objects for full `<source>` control.
+ * @property disclaimer - Props forwarded to the internal {@link Disclaimer} component.
+ * While the disclaimer is active the `<img>` is hidden.
+ * @property theatre - Props forwarded to the internal {@link Theatre} component.
+ * @property className - Optional additional class name(s) applied to the root element.
+ */
+export type Props = WithClassName<{
+    sources?: string | string[] | SourceData[];
+    disclaimer?: DisclaimerProps;
+    theatre?: TheatreProps;
+}> & ImgHTMLAttributes<HTMLImageElement>;
+/**
+ * Image component. Wraps a native `<img>` (or `<picture>`) element with
+ * optional responsive sources, an optional disclaimer gate, and
+ * viewport-driven visibility tracking.
+ *
+ *
+ * ### Child elements
+ * - `__picture` — wrapping `<picture>` element, always rendered. Contains the
+ * `<source>` elements (if any) and the `<img>`.
+ * - `__img` — the native `<img>` element.
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ * @returns A `<figure>` element containing a `<picture>` with the image,
+ * and an optional disclaimer overlay.
+ */
+export declare const Image: FunctionComponent<Props>;
+export {};

package/components/Image/index.js

@@ -0,0 +1,99 @@
+// src/components/Image/index.tsx
+import {
+  useState,
+  useMemo,
+  useCallback
+} from "react";
+import { clss } from "../../agnostic/css/clss/index.js";
+import {
+  Disclaimer
+} from "../Disclaimer/index.js";
+import {
+  Theatre
+} from "../Theatre/index.js";
+import { mergeClassNames } from "../utils/index.js";
+import { image as publicClassName } from "../public-classnames.js";
+import cssModule from "./styles.module.css";
+import { jsx, jsxs } from "react/jsx-runtime";
+var Image = ({
+  sources,
+  disclaimer,
+  theatre,
+  className,
+  ...intrinsicImgAttributes
+}) => {
+  const [isDisclaimerOn, setIsDisclaimerOn] = useState(
+    disclaimer?.isOn === true || disclaimer?.defaultIsOn === true || disclaimer !== void 0 && disclaimer.defaultIsOn === void 0
+  );
+  let shouldDisclaimerBeOn = isDisclaimerOn;
+  if (disclaimer?.isOn === true) shouldDisclaimerBeOn = true;
+  if (disclaimer?.isOn === false) shouldDisclaimerBeOn = false;
+  const parsedSources = useMemo(() => {
+    if (sources === void 0) return [];
+    if (typeof sources === "string") return [{ srcSet: sources }];
+    if (Array.isArray(sources)) {
+      if (sources.length === 0) return [];
+      if (typeof sources[0] === "string") return sources.map((srcSet) => ({ srcSet }));
+      return sources;
+    }
+    return [];
+  }, [sources]);
+  const handleDisclaimerDismissClick = useCallback(() => {
+    disclaimer?.actionHandlers?.dismissClick?.(isDisclaimerOn);
+    setIsDisclaimerOn(false);
+  }, []);
+  const c = clss(publicClassName, { cssModule });
+  const rootClss = mergeClassNames(c(), className);
+  const rootAttributes = {};
+  const pictureClss = c("picture");
+  const imgClss = c("image");
+  const sensitiveContent = /* @__PURE__ */ jsxs("picture", { className: pictureClss, children: [
+    parsedSources.map(
+      (source, index) => /* @__PURE__ */ jsx(
+        "source",
+        {
+          srcSet: typeof source === "string" ? source : source.srcSet,
+          type: typeof source === "string" ? void 0 : source.type,
+          media: typeof source === "string" ? void 0 : source.media,
+          sizes: typeof source === "string" ? void 0 : source.sizes
+        },
+        index
+      )
+    ),
+    /* @__PURE__ */ jsx(
+      "img",
+      {
+        className: imgClss,
+        ...intrinsicImgAttributes
+      }
+    )
+  ] });
+  const theatricalContent = theatre !== void 0 ? /* @__PURE__ */ jsx(
+    Theatre,
+    {
+      defaultIsOn: false,
+      ...theatre,
+      children: sensitiveContent
+    }
+  ) : sensitiveContent;
+  const disclaimedContent = disclaimer !== void 0 ? /* @__PURE__ */ jsx(
+    Disclaimer,
+    {
+      ...disclaimer,
+      isOn: shouldDisclaimerBeOn,
+      actionHandlers: { dismissClick: handleDisclaimerDismissClick },
+      children: theatricalContent
+    }
+  ) : theatricalContent;
+  return /* @__PURE__ */ jsx(
+    "figure",
+    {
+      className: rootClss,
+      ...rootAttributes,
+      children: disclaimedContent
+    }
+  );
+};
+export {
+  Image
+};

package/components/IntersectionObserver/index.d.ts

@@ -1,20 +1,57 @@
-import { type ReactNode, type JSX } from 'react';
+import { type PropsWithChildren, type FunctionComponent } from 'react';
+import type { WithClassName } from '../utils/types.js';
+/** Alias for the native IntersectionObserver interface. */
 export type IO = IntersectionObserver;
+/** Alias for the native IntersectionObserverEntry interface. */
 export type IOE = IntersectionObserverEntry;
-type ObserverOptions = {
+/**
+ * Configuration options for the underlying IntersectionObserver instance.
+ *
+ * @property root - The element used as the viewport for checking visibility.
+ * If not provided, the browser viewport is used.
+ * @property rootMargin - Margin around the root, in CSS margin format
+ * (e.g. "10px 20px"). Expands or shrinks the effective root bounds.
+ * @property threshold - A single number or an array of numbers indicating
+ * at what percentage(s) of the target's visibility the observer callback
+ * should be executed.
+ */
+export type ObserverOptions = {
     root?: HTMLElement;
     rootMargin?: string;
     threshold?: number[] | number;
 };
-export type Props = {
-    className?: string;
-    render?: ReactNode;
-    onIntersection?: (details: {
+/**
+ * Props for the IntersectionObserverComponent.
+ *
+ * @property onIntersected - Callback invoked whenever an intersection change
+ * is reported. Receives an object containing the current
+ * {@link IntersectionObserverEntry} (if available) and the active
+ * {@link IntersectionObserver} instance.
+ *
+ * @property root - See {@link ObserverOptions.root}.
+ * @property rootMargin - See {@link ObserverOptions.rootMargin}.
+ * @property threshold - See {@link ObserverOptions.threshold}.
+ * @property className - Optional additional class name(s) applied to the root element.
+ * @property children - React children rendered inside the observed element.
+ */
+export type Props = PropsWithChildren<WithClassName<{
+    onIntersected?: (details: {
         ioEntry?: IOE | undefined;
         observer: IO;
     }) => void;
-    content?: ReactNode;
-    children?: ReactNode;
-} & ObserverOptions;
-export declare const IntersectionObserverComponent: ({ className, render, content, onIntersection, root, rootMargin, threshold, children }: Props) => JSX.Element;
-export {};
+} & ObserverOptions>>;
+/**
+ * Component that observes its root element using the IntersectionObserver API
+ * and notifies consumers about visibility changes.
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ *
+ * @returns A div element wrapping `children`, observed for intersection changes.
+ *
+ * @remarks
+ * - Automatically creates and disconnects the {@link IntersectionObserver} instance.
+ * - Re-observes the element shortly after mount to handle late layout changes.
+ * - Adds an `is-intersecting` modifier class when the element is intersecting.
+ */
+export declare const IntersectionObserverComponent: FunctionComponent<Props>;

package/components/IntersectionObserver/index.js

@@ -6,18 +6,16 @@ import {
   useCallback
 } from "react";
 import { clss } from "../../agnostic/css/clss/index.js";
-import { isNotFalsy } from "../../agnostic/booleans/is-falsy/index.js";
-import { intersectionObserver } from "../public-classnames.js";
+import { mergeClassNames } from "../utils/index.js";
+import { intersectionObserver as publicClassName } from "../public-classnames.js";
 import cssModule from "./styles.module.css";
-import { jsxs } from "react/jsx-runtime";
+import { jsx } from "react/jsx-runtime";
 var IntersectionObserverComponent = ({
-  className,
-  render,
-  content,
-  onIntersection,
+  onIntersected,
   root,
   rootMargin,
   threshold,
+  className,
   children
 }) => {
   const [ioEntry, setIoEntry] = useState(null);
@@ -26,12 +24,9 @@ var IntersectionObserverComponent = ({
   const observation = useCallback((entries, observer) => {
     const thisEntry = entries[0];
     if (thisEntry === void 0) return setIoEntry(null);
-    if (onIntersection !== void 0) onIntersection({
-      ioEntry: thisEntry,
-      observer
-    });
+    onIntersected?.({ ioEntry: thisEntry, observer });
     setIoEntry(thisEntry);
-  }, [onIntersection]);
+  }, [onIntersected]);
   const forceObservation = useCallback(() => {
     const rootEl = rootRef.current;
     const observer = observerRef.current;
@@ -55,22 +50,18 @@ var IntersectionObserverComponent = ({
       window.clearTimeout(timeout2);
     };
   }, [forceObservation]);
-  const c = clss(intersectionObserver, { cssModule });
+  const c = clss(publicClassName, { cssModule });
   const isIntersecting = ioEntry?.isIntersecting ?? false;
-  const wrapperClassName = [
+  const rootClss = mergeClassNames(
     c(null, { "is-intersecting": isIntersecting }),
     className
-  ].filter(isNotFalsy).join(" ");
-  return /* @__PURE__ */ jsxs(
+  );
+  return /* @__PURE__ */ jsx(
     "div",
     {
+      className: rootClss,
       ref: rootRef,
-      className: wrapperClassName,
-      children: [
-        render ?? null,
-        children,
-        content
-      ]
+      children
     }
   );
 };

package/components/Paginator/index.d.ts

@@ -0,0 +1,72 @@
+import { type PropsWithChildren, type FunctionComponent } from 'react';
+import type { WithClassName } from '../utils/types.js';
+/**
+ * State associated with a single page slot.
+ *
+ * @property position - The current position of the page relative to the viewport:
+ * - `'prev'` — the page has been scrolled past.
+ * - `'curr'` — the page is currently visible in the viewport.
+ * - `'next'` — the page has not yet been reached.
+ * @property currCount - The number of times this page has entered the `'curr'` position.
+ */
+type PageState = {
+    position: 'prev' | 'curr' | 'next';
+    currCount: number;
+};
+/**
+ * Represents the scroll direction state of the paginator.
+ * - `'forwards'` — the user is scrolling down.
+ * - `'backwards'` — the user is scrolling up.
+ * - `null` — no scroll has been detected yet.
+ */
+type DirectionState = 'forwards' | 'backwards' | null;
+/**
+ * Props for the {@link Paginator} component.
+ *
+ * @property thresholdOffsetPercent - Optional percentage offset used to compute
+ * the {@link IntersectionObserver} root margin. Determines how far into the viewport
+ * a page must be before it is considered `'curr'`. Defaults to `0`.
+ *
+ * @property stateHandlers - Callbacks called after the internal state changed
+ * @property stateHandlers.directionChanged - Callback invoked when the scroll direction changes.
+ * Receives the new {@link DirectionState}. Only fires when the direction actually
+ * changes — repeated scrolls in the same direction do not trigger it again.
+ *
+ * @property stateHandlers.pageChanged - Callback invoked whenever any page's {@link PageState}
+ * changes. Receives a flat array of all pages' states, ordered by position.
+ *
+ * @property className - Optional additional class name(s) applied to the root element.
+ * @property children - Each direct child is treated as an individual page slot.
+ */
+export type Props = PropsWithChildren<WithClassName<{
+    thresholdOffsetPercent?: number;
+    stateHandlers?: {
+        directionChanged?: (direction: DirectionState) => void;
+        pageChanged?: (pages: PageState[]) => void;
+    };
+}>>;
+/**
+ * A scroll-driven pagination component that tracks which child page is currently
+ * visible in the viewport and the direction of scroll.
+ *
+ * Each direct child is wrapped in a page slot and observed via
+ * {@link IntersectionObserver}. Page slots receive `'prev'`, `'curr'`, or `'next'`
+ * positional modifier classes based on their visibility.
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ *
+ * @returns A root div containing a pages wrapper, with each child isolated in
+ * its own observed page slot div.
+ *
+ * @remarks
+ * - Scroll direction is throttled to one update per 100ms and only dispatched
+ *   when the direction actually changes, using an internal ref to avoid stale
+ *   closure comparisons.
+ * - Page visibility is tracked via a single {@link IntersectionObserver} instance
+ *   that is recreated when `thresholdOffsetPercent` or `children` change.
+ * - `currCount` on each {@link PageState} increments each time a page transitions
+ *   into the `'curr'` position, making it useful as a re-entry counter.
+ */
+export declare const Paginator: FunctionComponent<Props>;
+export {};