@design-edito/tools 0.3.10 → 0.3.11

package/components/Paginator/index.js

@@ -0,0 +1,116 @@
+// src/components/Paginator/index.tsx
+import {
+  useEffect,
+  useRef,
+  Children,
+  useState
+} from "react";
+import { clss } from "../../agnostic/css/clss/index.js";
+import { mergeClassNames } from "../utils/index.js";
+import { paginator as publicClassName } from "../public-classnames.js";
+import cssModule from "./styles.module.css";
+import { jsx } from "react/jsx-runtime";
+var Paginator = ({
+  thresholdOffsetPercent,
+  stateHandlers,
+  className,
+  children
+}) => {
+  const [pagesState, setPagesState] = useState(/* @__PURE__ */ new Map());
+  const [directionState, setDirectionState] = useState(null);
+  const pagesRef = useRef(null);
+  const directionRef = useRef(null);
+  useEffect(() => {
+    stateHandlers?.pageChanged?.(Array.from(pagesState).map(([, state]) => state));
+  }, [pagesState]);
+  useEffect(() => {
+    stateHandlers?.directionChanged?.(directionState);
+  }, [directionState]);
+  useEffect(() => {
+    let lastCall = 0;
+    let lastScrollY = window.scrollY;
+    const handleScroll = (e) => {
+      const now = Date.now();
+      if (now - lastCall < 100) return;
+      lastCall = now;
+      const currentScrollY = window.scrollY;
+      const direction = currentScrollY > lastScrollY ? "forwards" : "backwards";
+      lastScrollY = currentScrollY;
+      if (direction !== directionRef.current) {
+        directionRef.current = direction;
+        setDirectionState(direction);
+      }
+    };
+    window.addEventListener("scroll", handleScroll);
+    window.addEventListener("resize", handleScroll);
+    return () => {
+      window.removeEventListener("scroll", handleScroll);
+      window.removeEventListener("resize", handleScroll);
+    };
+  }, []);
+  useEffect(() => {
+    if (pagesRef.current === null) return;
+    const pages = Array.from(pagesRef.current.children);
+    const observerRootMargin = `-${thresholdOffsetPercent ?? 0}% 0px -${100 - (thresholdOffsetPercent ?? 0)}% 0px`;
+    const observer = new IntersectionObserver((entries) => {
+      setPagesState((prevState) => {
+        const nextState = new Map(prevState);
+        entries.forEach((entry) => {
+          const index = pageIndexMap.get(entry.target);
+          if (index === void 0) return;
+          const prev = prevState.get(index);
+          const position = entry.isIntersecting ? "curr" : entry.boundingClientRect.bottom < (entry.rootBounds?.top ?? 0) ? "prev" : "next";
+          const currCount = position === "curr" && prev?.position !== "curr" ? (prev?.currCount ?? 0) + 1 : prev?.currCount ?? 0;
+          nextState.set(index, { position, currCount });
+        });
+        return nextState;
+      });
+    }, { rootMargin: observerRootMargin });
+    const pageIndexMap = /* @__PURE__ */ new Map();
+    pages.forEach((page, index) => {
+      pageIndexMap.set(page, index);
+      observer.observe(page);
+    });
+    return () => observer.disconnect();
+  }, [thresholdOffsetPercent, children]);
+  const c = clss(publicClassName, { cssModule });
+  const rootClss = mergeClassNames(
+    c(null, {
+      forwards: directionState === "forwards",
+      backwards: directionState === "backwards"
+    }),
+    className
+  );
+  const pagesClss = c("pages");
+  const childrenArr = Children.toArray(children);
+  return /* @__PURE__ */ jsx("div", { className: rootClss, children: /* @__PURE__ */ jsx(
+    "div",
+    {
+      className: pagesClss,
+      ref: pagesRef,
+      children: childrenArr.map((child, pos) => {
+        const state = pagesState.get(pos);
+        const pageClss = c("page", {
+          first: pos === 0,
+          last: pos === childrenArr.length - 1,
+          prev: state?.position === "prev",
+          curr: state?.position === "curr",
+          next: state?.position === "next"
+        });
+        return /* @__PURE__ */ jsx(
+          "div",
+          {
+            className: pageClss,
+            "data-page": pos,
+            "data-curr-count": state?.currCount ?? 0,
+            children: child
+          },
+          pos
+        );
+      })
+    }
+  ) });
+};
+export {
+  Paginator
+};

package/components/Paginator/styles.module.css

@@ -0,0 +1,9 @@
+.threshold {
+  position: fixed;
+  left: 0px;
+  right: 0px;
+  height: 0px;
+  user-select: none;
+  pointer-events: none;
+  z-index: -9999;
+}

package/components/ResizeObserver/index.d.ts

@@ -0,0 +1,27 @@
+import { type PropsWithChildren, type FunctionComponent } from 'react';
+import type { WithClassName } from '../utils/types.js';
+type ROEntryWithBoundingRect = {
+    entry: ResizeObserverEntry;
+    boundingClientRect: DOMRect;
+};
+/**
+ * Props for the ResizeObserverComponent.
+ *
+ * @property className - Optional additional class name(s) applied to the root element.
+ * @property onResized - Callback invoked when the element is resized.
+ * Receives the `ResizeObserverEntry` from the observed element, or `undefined` if none.
+ * @property children - React children rendered inside the root element. Only the root element is observed
+ */
+export type Props = PropsWithChildren<WithClassName<{
+    onResized?: (entry: ROEntryWithBoundingRect) => void;
+}>>;
+/**
+ * Component that observes its own size changes and exposes the dimensions.
+ * Updates are exposed both via data attributes (e.g., `data-width`) and CSS custom properties
+ * (e.g., `--<prefix>-width`, `--<prefix>-width-px`) for styling or scripting purposes.
+ * @param props - Component properties
+ * @see {@link Props}
+ * @returns A div wrapping `children`, with resize observation applied.
+ */
+export declare const ResizeObserverComponent: FunctionComponent<Props>;
+export {};

package/components/ResizeObserver/index.js

@@ -0,0 +1,81 @@
+// src/components/ResizeObserver/index.tsx
+import {
+  useRef,
+  useEffect,
+  useState
+} from "react";
+import { clss } from "../../agnostic/css/clss/index.js";
+import { mergeClassNames } from "../utils/index.js";
+import { resizeObserver as publicClassName } from "../public-classnames.js";
+import cssModule from "./style.module.css";
+import { jsx } from "react/jsx-runtime";
+var ResizeObserverComponent = ({
+  className,
+  onResized,
+  children
+}) => {
+  const [roEntry, setRoEntry] = useState();
+  const rootRef = useRef(null);
+  const observerRef = useRef(null);
+  const createObserver = () => {
+    const root = rootRef.current;
+    observerRef.current?.disconnect();
+    if (root === null) return;
+    observerRef.current = new ResizeObserver((entries) => {
+      const firstEntry = entries[0];
+      if (firstEntry !== void 0) {
+        const boundingClientRect = firstEntry.target.getBoundingClientRect();
+        const fullEntry = {
+          entry: firstEntry,
+          boundingClientRect
+        };
+        setRoEntry(fullEntry);
+        if (onResized === void 0) return;
+        onResized(fullEntry);
+      }
+    });
+    observerRef.current.observe(root);
+  };
+  useEffect(() => {
+    createObserver();
+    return () => observerRef.current?.disconnect();
+  }, [onResized]);
+  const {
+    x,
+    y,
+    top,
+    left,
+    bottom,
+    right,
+    width,
+    height
+  } = roEntry?.entry.contentRect ?? {};
+  const contentRect = { x, y, top, left, bottom, right, width, height };
+  const dataAttributes = Object.entries(contentRect).reduce((acc, [key, val]) => {
+    if (val === void 0) return acc;
+    return { ...acc, [`data-${key}`]: val.toString() };
+  }, {});
+  const cssCustomProps = Object.entries(contentRect).reduce((acc, [key, val]) => {
+    if (val === void 0) return acc;
+    return {
+      ...acc,
+      [`--${publicClassName}-${key}`]: val.toString(),
+      [`--${publicClassName}-${key}-px`]: `${val.toString()}px`
+    };
+  }, {});
+  const c = clss(publicClassName, { cssModule });
+  const rootClss = mergeClassNames(c(null), className);
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      ...dataAttributes,
+      className: rootClss,
+      ref: rootRef,
+      style: { ...cssCustomProps },
+      children
+    }
+  );
+};
+export {
+  ResizeObserverComponent
+};

package/components/Scrllgngn/index.d.ts

@@ -0,0 +1,123 @@
+import { type PropsWithChildren, type FunctionComponent } from 'react';
+import type { WithClassName } from '../utils/types.js';
+/**
+ * Common properties shared by all block types.
+ *
+ * @property id - Optional stable identifier for the block. Used to consolidate
+ * blocks with the same id across multiple pages into a single sticky block
+ * displayed across those pages.
+ * @property trackScroll - Whether scroll tracking is enabled for this block.
+ * @property children - Content rendered inside the block.
+ */
+type PropsCommonBlock = PropsWithChildren<{
+    id?: string;
+    trackScroll?: boolean;
+}>;
+/**
+ * A block that scrolls with the page content.
+ *
+ * @property depth - When set to `'scroll'` or omitted, the block is rendered
+ * inline in the scrolling content layer.
+ */
+type PropsScrollBlock = PropsCommonBlock & {
+    depth?: 'scroll';
+};
+/**
+ * A block that sticks to the viewport, rendered outside the scroll flow.
+ *
+ * @property depth - `'back'` renders the block behind the scrolling content;
+ * `'front'` renders it in front.
+ * @property zIndex - Optional explicit z-index. Sticky blocks are otherwise
+ * stacked in the order they appear across pages (ascending).
+ */
+type PropsStickyBlock = PropsCommonBlock & {
+    depth: 'back' | 'front';
+    zIndex?: number;
+};
+/**
+ * Union of all block variants accepted by a {@link PropsPage}.
+ *
+ * @see {@link PropsScrollBlock}
+ * @see {@link PropsStickyBlock}
+ */
+type PropsBlock = PropsScrollBlock | PropsStickyBlock;
+/**
+ * Describes a single page in the scrollytelling sequence.
+ *
+ * @property id - Optional identifier for the page.
+ * @property blocks - Ordered list of blocks belonging to this page.
+ * Scroll blocks are rendered inline; sticky blocks (`'back'` / `'front'`) are
+ * lifted into their respective layer and consolidated with same-id blocks from
+ * other pages.
+ */
+type PropsPage = {
+    id?: string;
+    blocks?: PropsBlock[];
+};
+/**
+ * Props for the {@link Scrllgngn} component.
+ *
+ * @property pages - Ordered list of pages that compose the scrollytelling
+ * sequence. Each page may contain any mix of {@link PropsBlock} variants.
+ * @property thresholdOffsetPercent - Forwarded to the internal
+ * {@link Paginator}. Defines the viewport offset percentage used to determine
+ * which page is considered current.
+ * @property stickyBlocksLazyLoadDistance - Number of pages around the current
+ * page within which sticky blocks are mounted. Blocks outside this window are
+ * unmounted to save resources. Defaults to `2`.
+ * @property forceStickBlocks - Controls which out-of-range sticky blocks are
+ * forced into a stuck state regardless of the current page:
+ * - `'before'` — forces blocks from pages before the current one.
+ * - `'after'`  — forces blocks from pages after the current one.
+ * - `'both'`   — forces blocks on both sides.
+ * - `'none'`   — no forcing (default behaviour).
+ * @property className - Optional additional class name(s) applied to the root element.
+ */
+export type Props = WithClassName<{
+    pages?: PropsPage[];
+    thresholdOffsetPercent?: number;
+    stickyBlocksLazyLoadDistance?: number;
+    forceStickBlocks?: 'before' | 'after' | 'both' | 'none';
+}>;
+/**
+ * Scrollytelling engine component. Orchestrates layered sticky blocks (`back`
+ * and `front`) over a paginated scrolling content area, with lazy loading,
+ * viewport bound detection, and dimension tracking.
+ *
+ * ### Root element modifiers
+ * The root `<div>` receives the public class name defined by `scrllgngn` and
+ * the following BEM-style modifier classes when active:
+ * - `--top-visible` — the top boundary sentinel is intersecting the viewport.
+ * - `--content-visible` — the scrolling content area is intersecting the viewport.
+ * - `--bottom-visible` — the bottom boundary sentinel is intersecting the viewport.
+ * - `--force-stick-blocks-before` — when `forceStickBlocks === 'before'`.
+ * - `--force-stick-blocks-after` — when `forceStickBlocks === 'after'`.
+ * - `--force-stick-blocks-both` — when `forceStickBlocks === 'both'`.
+ *
+ * ### Data attributes
+ * - `data-current-page-pos` — zero-based index of the page currently in view,
+ * updated on every page change reported by the internal {@link Paginator}.
+ *
+ * ### CSS custom properties
+ * Exposed on the root element and updated on resize via the internal
+ * {@link ResizeObserverComponent}:
+ * - `--scrllgngn-screen-left` / `--PRIVATE-left` — left edge of the bounding rect (px).
+ * - `--scrllgngn-screen-right` / `--PRIVATE-right` — right edge (px).
+ * - `--scrllgngn-screen-width` / `--PRIVATE-width` — total width (px).
+ * - `--scrllgngn-screen-height` / `--PRIVATE-height` — total height (px).
+ *
+ * ### Sticky block elements
+ * Each lazy-loaded sticky block receives:
+ * - `--active` modifier when the block's page range includes the current page.
+ * - `--lazy-loaded` modifier when the block is mounted but not on the current page.
+ * - An inline `z-index` derived from the block's position in the sorted stack
+ * (overridden by {@link PropsStickyBlock.zIndex} if provided).
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ * @returns A div wrapping the full scrollytelling structure: top-bound sentinel,
+ * back-blocks layer, front-blocks layer, paginated scrolling content, and
+ * bottom-bound sentinel.
+ */
+export declare const Scrllgngn: FunctionComponent<Props>;
+export {};

package/components/Scrllgngn/index.js

@@ -0,0 +1,175 @@
+// src/components/Scrllgngn/index.tsx
+import {
+  useState,
+  useEffect
+} from "react";
+import { clss } from "../../agnostic/css/clss/index.js";
+import { randomHash } from "../../agnostic/random/uuid/index.js";
+import {
+  IntersectionObserverComponent
+} from "../IntersectionObserver/index.js";
+import {
+  Paginator
+} from "../Paginator/index.js";
+import {
+  ResizeObserverComponent
+} from "../ResizeObserver/index.js";
+import { mergeClassNames } from "../utils/index.js";
+import { scrllgngn as publicClassName } from "../public-classnames.js";
+import cssModule from "./styles.module.css";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+var Scrllgngn = ({
+  pages,
+  thresholdOffsetPercent,
+  stickyBlocksLazyLoadDistance = 2,
+  forceStickBlocks,
+  className
+}) => {
+  const [topVisible, setTopVis] = useState(false);
+  const [contentVisible, setCntVis] = useState(false);
+  const [bottomVisible, setBtmVis] = useState(false);
+  const [currentPagePos, setCurrentPagePos] = useState(0);
+  const [stickyBlocks, setStickyBlocks] = useState(/* @__PURE__ */ new Map());
+  const [partialBoundingRect, setPartialBoundingRect] = useState();
+  useEffect(() => {
+    const consolidatedBlocks = /* @__PURE__ */ new Map();
+    for (const page of pages ?? []) {
+      const pageIndex = pages?.indexOf(page) ?? -1;
+      for (const block of page.blocks ?? []) {
+        const blockId = block.id ?? randomHash(12);
+        const found = consolidatedBlocks.get(blockId);
+        if (found !== void 0) consolidatedBlocks.set(blockId, {
+          ...found,
+          ...block,
+          displayOnPages: [
+            ...found.displayOnPages,
+            pageIndex
+          ]
+        });
+        else consolidatedBlocks.set(blockId, {
+          ...block,
+          displayOnPages: [pageIndex]
+        });
+      }
+    }
+    const consolidatedStickyBlocks = new Map(Array.from(consolidatedBlocks).filter((e) => {
+      const block = e[1];
+      return block.depth === "back" || block.depth === "front";
+    }));
+    setStickyBlocks(consolidatedStickyBlocks);
+  }, [pages]);
+  const lazyLoadedBackBlocks = Array.from(stickyBlocks).filter(
+    ([, block]) => block.depth === "back" && block.displayOnPages.some((dispPage) => {
+      const absDiff = Math.abs(dispPage - currentPagePos);
+      return absDiff <= stickyBlocksLazyLoadDistance;
+    })
+  ).map(([, block]) => block).sort((a, b) => {
+    return (a.zIndex ?? -Infinity) - (b.zIndex ?? -Infinity);
+  });
+  const lazyLoadedFrontBlocks = Array.from(stickyBlocks).filter(
+    ([, block]) => block.depth === "front" && block.displayOnPages.some((dispPage) => {
+      const absDiff = Math.abs(dispPage - currentPagePos);
+      return absDiff <= stickyBlocksLazyLoadDistance;
+    })
+  ).map(([, block]) => block).sort((a, b) => {
+    return (a.zIndex ?? -Infinity) - (b.zIndex ?? -Infinity);
+  });
+  const handleTopBoundDetect = (e) => setTopVis(e.ioEntry?.isIntersecting ?? false);
+  const handleCntDetect = (e) => setCntVis(e.ioEntry?.isIntersecting ?? false);
+  const handleBtmBoundDetect = (e) => setBtmVis(e.ioEntry?.isIntersecting ?? false);
+  const handlePageChange = (pages2) => {
+    const curPagePos = pages2.findIndex((page) => page.position === "curr");
+    if (curPagePos === -1) return;
+    return setCurrentPagePos(curPagePos);
+  };
+  const handleResize = ({ boundingClientRect }) => {
+    if (partialBoundingRect === void 0 || boundingClientRect.left !== partialBoundingRect.left || boundingClientRect.right !== partialBoundingRect.right || boundingClientRect.height !== partialBoundingRect.height || boundingClientRect.width !== partialBoundingRect.width) setPartialBoundingRect(boundingClientRect);
+  };
+  const c = clss(publicClassName, { cssModule });
+  const rootClss = mergeClassNames(
+    c(null, {
+      "top-visible": topVisible,
+      "content-visible": contentVisible,
+      "bottom-visible": bottomVisible,
+      "force-stick-blocks-before": forceStickBlocks === "before",
+      "force-stick-blocks-after": forceStickBlocks === "after",
+      "force-stick-blocks-both": forceStickBlocks === "both"
+    }),
+    className
+  );
+  const customCssProps = {};
+  if (partialBoundingRect?.left !== void 0) {
+    customCssProps[`--${publicClassName}-screen-left`] = `${partialBoundingRect.left}px`;
+    customCssProps["--PRIVATE-left"] = `${partialBoundingRect.left}px`;
+  }
+  if (partialBoundingRect?.right !== void 0) {
+    customCssProps[`--${publicClassName}-screen-right`] = `${partialBoundingRect.right}px`;
+    customCssProps["--PRIVATE-right"] = `${partialBoundingRect.right}px`;
+  }
+  if (partialBoundingRect?.width !== void 0) {
+    customCssProps[`--${publicClassName}-screen-width`] = `${partialBoundingRect.width}px`;
+    customCssProps["--PRIVATE-width"] = `${partialBoundingRect.width}px`;
+  }
+  if (partialBoundingRect?.height !== void 0) {
+    customCssProps[`--${publicClassName}-screen-height`] = `${partialBoundingRect.height}px`;
+    customCssProps["--PRIVATE-height"] = `${partialBoundingRect.height}px`;
+  }
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      className: rootClss,
+      "data-current-page-pos": currentPagePos,
+      style: { ...customCssProps },
+      children: /* @__PURE__ */ jsxs(ResizeObserverComponent, { onResized: handleResize, children: [
+        /* @__PURE__ */ jsx("div", { className: c("top-bound"), children: /* @__PURE__ */ jsx(IntersectionObserverComponent, { onIntersected: handleTopBoundDetect }) }),
+        /* @__PURE__ */ jsx("div", { className: c("back-blocks"), children: lazyLoadedBackBlocks.map((block, blockPos) => {
+          const isActive = block.displayOnPages.includes(currentPagePos);
+          const blockClss = c("back-block", {
+            active: isActive,
+            "lazy-loaded": !isActive
+          });
+          return /* @__PURE__ */ jsx(
+            "div",
+            {
+              className: blockClss,
+              style: { zIndex: blockPos },
+              children: block.children
+            }
+          );
+        }) }),
+        /* @__PURE__ */ jsx("div", { className: c("front-blocks"), children: lazyLoadedFrontBlocks.map((block, blockPos) => {
+          const isActive = block.displayOnPages.includes(currentPagePos);
+          const blockClss = c("front-block", {
+            active: isActive,
+            "lazy-loaded": !isActive
+          });
+          return /* @__PURE__ */ jsx(
+            "div",
+            {
+              className: blockClss,
+              style: { zIndex: blockPos },
+              children: block.children
+            }
+          );
+        }) }),
+        /* @__PURE__ */ jsx("div", { className: c("scrolling-content"), children: /* @__PURE__ */ jsx(IntersectionObserverComponent, { onIntersected: handleCntDetect, children: /* @__PURE__ */ jsx(
+          Paginator,
+          {
+            thresholdOffsetPercent,
+            stateHandlers: {
+              pageChanged: handlePageChange
+            },
+            children: pages?.map((page) => {
+              const scrollBlocks = page.blocks?.filter((b) => b.depth === "scroll" || b.depth === void 0) ?? [];
+              return /* @__PURE__ */ jsx(Fragment, { children: scrollBlocks.map((b) => b.children) });
+            })
+          }
+        ) }) }),
+        /* @__PURE__ */ jsx("div", { className: c("bottom-bound"), children: /* @__PURE__ */ jsx(IntersectionObserverComponent, { onIntersected: handleBtmBoundDetect }) })
+      ] })
+    }
+  );
+};
+export {
+  Scrllgngn
+};

package/components/Scrllgngn/styles.module.css

@@ -0,0 +1,74 @@
+.root {
+  position: relative;
+}
+
+/* MAIN LAYOUTS (back / front blocks, scrolling content) */
+
+.back-blocks {
+  z-index: 1;
+}
+
+.scrolling-content {
+  z-index: 2;
+}
+
+.front-blocks {
+  z-index: 3;
+}
+
+/* Scrllgngn entering the viewport, blocks not fixed yet */
+.back-blocks,
+.front-blocks,
+.root.root--top-visible.root--content-visible .back-blocks,
+.root.root--top-visible.root--content-visible .front-blocks {
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  height: 100vh;
+}
+
+/*
+Scrllgngn well in the viewport, fixed blocks
+OR
+Force stick blocks option
+*/
+.root.root--content-visible .back-blocks,
+.root.root--content-visible .front-blocks,
+
+.root.root--top-visible.root--content-visible.root--force-stick-blocks-before .back-blocks,
+.root.root--top-visible.root--content-visible.root--force-stick-blocks-before .front-blocks,
+.root.root--top-visible.root--content-visible.root--force-stick-blocks-both .back-blocks,
+.root.root--top-visible.root--content-visible.root--force-stick-blocks-both .front-blocks,
+
+.root.root--bottom-visible.root--content-visible.root--force-stick-blocks-after .back-blocks,
+.root.root--bottom-visible.root--content-visible.root--force-stick-blocks-after .front-blocks,
+.root.root--bottom-visible.root--content-visible.root--force-stick-blocks-both .back-blocks,
+.root.root--bottom-visible.root--content-visible.root--force-stick-blocks-both .front-blocks {
+  position: fixed;
+  top: 0;
+  left: var(--PRIVATE-left);
+  width: var(--PRIVATE-width);
+  height: 100vh;
+}
+
+/* Scrllgngn leaving the viewport, blocks not fixed but have offset */
+.root.root--bottom-visible.root--content-visible .back-blocks,
+.root.root--bottom-visible.root--content-visible .front-blocks {
+  position: absolute;
+  top: calc(var(--PRIVATE-height) - 100vh);
+  left: 0;
+  right: 0;
+  height: 100vh;
+}
+
+/* INDIVIDUAL FIXED BLOCKS */
+
+.back-block,
+.front-block {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  left: 0;
+  right: 0;
+}

package/components/Sequencer/index.controlled.d.ts

@@ -0,0 +1,78 @@
+import { type FunctionComponent, type PropsWithChildren } from 'react';
+import type { WithClassName } from '../utils/types.js';
+/**
+ * Props for the {@link SequencerControlled} component.
+ *
+ * This is the low-level controlled interface. All state is driven externally —
+ * the component holds no internal state of its own. For the uncontrolled
+ * version that reacts to external events and derives these props automatically,
+ * see the default export of the parent module.
+ *
+ * @property step - Zero-based index of the currently active step. Determines
+ * which child is marked active, which are previous, and which are next.
+ * Defaults to `0`.
+ * @property activateOnStep - Optional 2D array that overrides the default
+ * one-child-per-step activation logic. Each entry at index `i` is the list of
+ * child indices that should be active when `step === i`, allowing multiple
+ * children to be simultaneously active on a given step. When omitted, exactly
+ * one child is active at a time (the child at index `step`).
+ * @property _modifiers - Internal modifier flags forwarded directly to the
+ * BEM class builder on the root element. Intended to be injected by the
+ * uncontrolled wrapper; avoid setting manually in consumer code.
+ * - `playing` — sequence is currently progressing.
+ * - `at-start` — current step is the first step.
+ * - `at-end` — current step is the last step.
+ * @property _dataAttributes - Internal data attribute values forwarded to the
+ * root element as `data-<key>`. Intended to be injected by the uncontrolled
+ * wrapper; avoid setting manually in consumer code.
+ * - `tempo` — exposed as `data-tempo`, reflects the current playback tempo.
+ * @property className - Optional additional class name(s) applied to the root element.
+ * @property children - The items to sequence. Each child is wrapped in a
+ * classifier `<div>` and receives one of the `--active`, `--previous`, or
+ * `--next` modifiers depending on its position relative to the current `step`.
+ */
+export type ControlledProps = PropsWithChildren<WithClassName<{
+    step?: number;
+    activateOnStep?: number[][];
+    _modifiers?: {
+        playing?: boolean;
+        'at-start'?: boolean;
+        'at-end'?: boolean;
+    };
+    _dataAttributes?: {
+        tempo?: number;
+    };
+}>>;
+/**
+ * Controlled sequencer component. Renders each child inside a classifier
+ * wrapper and assigns step-relative modifiers based on `step` and the optional
+ * `activateOnStep` override map.
+ *
+ * This component is purely presentational and holds no internal state.
+ * It is designed to be driven by the uncontrolled wrapper, which handles
+ * timing, playback events, and derives the props passed here.
+ *
+ * ### Root element modifiers
+ * The root `<div>` receives the public class name defined by `sequencer` and
+ * the following BEM-style modifier classes, sourced from `_modifiers`:
+ * - `--playing` — when the sequence is actively progressing.
+ * - `--at-start` — when the current step is the first step.
+ * - `--at-end` — when the current step is the last step.
+ *
+ * ### Data attributes on the root element
+ * Derived from `_dataAttributes`, each key is prefixed with `data-`:
+ * - `data-tempo` — current playback tempo, when provided.
+ *
+ * ### Child wrapper elements
+ * Each child is wrapped in a `<div>` with the `__child` element class and
+ * exactly one of the following mutually exclusive modifiers:
+ * - `--active` — this child corresponds to the current step (or is included
+ * in `activateOnStep[step]`).
+ * - `--previous` — this child was active in a prior step.
+ * - `--next` — this child has not yet been reached.
+ *
+ * @param props - Component properties.
+ * @see {@link ControlledProps}
+ * @returns A root `<div>` containing one classifier wrapper per child.
+ */
+export declare const SequencerControlled: FunctionComponent<ControlledProps>;