@design-edito/tools 0.5.3 → 0.5.5

package/agnostic/numbers/index.d.ts

@@ -1,6 +1,6 @@
 export * as absoluteModulo from './absolute-modulo/index.js'
 export * as approximateRational from './approximate-rational/index.js'
 export * as clamp from './clamp/index.js'
-export * as interpolate from './interpolate/index.js'
 export * as geometricProgressions from './geometric-progressions/index.js'
+export * as interpolate from './interpolate/index.js'
 export * as round from './round/index.js'

package/agnostic/numbers/index.js

@@ -1,6 +1,6 @@
 export * as absoluteModulo from './absolute-modulo/index.js'
 export * as approximateRational from './approximate-rational/index.js'
 export * as clamp from './clamp/index.js'
-export * as interpolate from './interpolate/index.js'
 export * as geometricProgressions from './geometric-progressions/index.js'
+export * as interpolate from './interpolate/index.js'
 export * as round from './round/index.js'

package/components/Clippable/index.d.ts

@@ -10,6 +10,8 @@ import type { WithClassName } from '../utils/types.js';
  * clipboard content is resolved, with the container's raw HTML.
  * @property onClipped - Called once content has been written to the clipboard.
  * Not called when the write fails.
+ * @property onCopyFailed - Called when the clipboard write throws, with the
+ * error. When set, the error is no longer logged to the console.
  * @property className - Additional class name(s) applied to the root element.
  * @property children - Content rendered inside the copyable container.
  */
@@ -17,6 +19,7 @@ export type Props = PropsWithChildren<WithClassName<{
     toClip?: string | ((curr: string | undefined) => string | undefined);
     onCopyClicked?: (e: MouseEvent<HTMLButtonElement, globalThis.MouseEvent>, rawContent: string | undefined) => void;
     onClipped?: (content: string) => void;
+    onCopyFailed?: (error: unknown) => void;
 }>>;
 /**
  * Clipboard-enabled container. Renders arbitrary content alongside a copy
@@ -34,7 +37,8 @@ export type Props = PropsWithChildren<WithClassName<{
  * @returns A copy-enabled content container.
  *
  * @remarks
- * A failed clipboard write is logged and leaves the component untouched:
- * neither `onClipped` nor the `clipped` modifier fires.
+ * A failed clipboard write fires `onCopyFailed` (or is logged when that prop is
+ * unset) and leaves the component untouched: neither `onClipped` nor the
+ * `clipped` modifier fires.
  */
 export declare const Clippable: FunctionComponent<Props>;

package/components/Clippable/index.js

@@ -22,10 +22,11 @@ const clippedModifierDurationMs = 3000;
  * @returns A copy-enabled content container.
  *
  * @remarks
- * A failed clipboard write is logged and leaves the component untouched:
- * neither `onClipped` nor the `clipped` modifier fires.
+ * A failed clipboard write fires `onCopyFailed` (or is logged when that prop is
+ * unset) and leaves the component untouched: neither `onClipped` nor the
+ * `clipped` modifier fires.
  */
-export const Clippable = ({ className, children, toClip, onCopyClicked, onClipped }) => {
+export const Clippable = ({ className, children, toClip, onCopyClicked, onClipped, onCopyFailed }) => {
     // State & refs
     const [hasBeenRecentlyClipped, setHasBeenRecentlyClipped] = useState(false);
     const contentRef = useRef(null);
@@ -50,8 +51,11 @@ export const Clippable = ({ className, children, toClip, onCopyClicked, onClippe
             ]);
         }
         catch (err) {
+            if (onCopyFailed !== undefined)
+                onCopyFailed(err);
             // eslint-disable-next-line no-console
-            console.error(err);
+            else
+                console.error(err);
             return;
         }
         onClipped?.(html);

package/components/Disclaimer/index.d.ts

@@ -3,7 +3,9 @@ import type { WithClassName } from '../utils/types.js';
 /**
  * Props for the {@link Disclaimer} component.
  *
- * @property content - Content displayed inside the disclaimer panel.
+ * @property children - The content the disclaimer gates, rendered below the panel.
+ * @property undisclosedContent - Content displayed inside the disclaimer panel,
+ * until it is dismissed.
  * @property togglerContent - Content rendered inside the dismiss toggler.
  * When omitted, the toggler is not rendered.
  * @property isOn - Controlled visibility state. When defined, the component
@@ -15,10 +17,9 @@ import type { WithClassName } from '../utils/types.js';
  * @property onIsOnChanged - Called after the visibility state changed, with the
  * new value.
  * @property className - Optional additional class name(s) applied to the root element.
- * @property children - The content the disclaimer gates, rendered below the panel.
  */
 export type Props = PropsWithChildren<WithClassName<{
-    content?: ReactNode;
+    undisclosedContent?: ReactNode;
     togglerContent?: ReactNode;
     isOn?: boolean;
     defaultIsOn?: boolean;
@@ -34,7 +35,7 @@ export type Props = PropsWithChildren<WithClassName<{
  *
  * ### CSS elements
  * - `panel`
- * - `content`
+ * - `content` — wraps `undisclosedContent`.
  * - `toggler`
  * - `sensitive` — wraps `children`.
  *

package/components/Disclaimer/index.js

@@ -13,7 +13,7 @@ import cssModule from './styles.module.css';
  *
  * ### CSS elements
  * - `panel`
- * - `content`
+ * - `content` — wraps `undisclosedContent`.
  * - `toggler`
  * - `sensitive` — wraps `children`.
  *
@@ -28,7 +28,7 @@ import cssModule from './styles.module.css';
  *   know a click happened at all.
  * - `onIsOnChanged` fires in both modes too, and never on mount.
  */
-export const Disclaimer = ({ content, togglerContent, isOn: isOnProp, defaultIsOn = true, onDismissClicked, onIsOnChanged, children, className }) => {
+export const Disclaimer = ({ children, undisclosedContent, togglerContent, isOn: isOnProp, defaultIsOn = true, onDismissClicked, onIsOnChanged, className }) => {
     // State
     const [internalIsOn, setInternalIsOn] = useState(defaultIsOn);
     const isControlled = isOnProp !== undefined;
@@ -52,5 +52,5 @@ export const Disclaimer = ({ content, togglerContent, isOn: isOnProp, defaultIsO
     const contentClss = c('content');
     const togglerClss = c('toggler');
     const sensitiveClss = c('sensitive');
-    return _jsxs("div", { className: rootClss, children: [_jsxs("div", { className: panelClss, children: [content !== undefined && _jsx("div", { className: contentClss, children: content }), togglerContent !== undefined && _jsx("div", { className: togglerClss, onClick: handleDismissClick, children: togglerContent })] }), _jsx("div", { className: sensitiveClss, children: children })] });
+    return _jsxs("div", { className: rootClss, children: [_jsxs("div", { className: panelClss, children: [undisclosedContent !== undefined && _jsx("div", { className: contentClss, children: undisclosedContent }), togglerContent !== undefined && _jsx("div", { className: togglerClss, onClick: handleDismissClick, children: togglerContent })] }), _jsx("div", { className: sensitiveClss, children: children })] });
 };

package/components/Drawer/index.d.ts

@@ -15,6 +15,8 @@ import type { WithClassName } from '../utils/types.js';
  * drawer reacts, with the open state as it was.
  * @property onIsOpenedChanged - Called after the open state changed, with the
  * new value.
+ * @property onContentResized - Called after the measured content size changed,
+ * with the new width and height in pixels. Never on mount.
  * @property className - Additional class name(s) applied to the root element.
  * @property children - Drawer content.
  */
@@ -26,6 +28,10 @@ export type Props = PropsWithChildren<WithClassName<{
     onOpenerClicked?: (isOpened: boolean) => void;
     onCloserClicked?: (isOpened: boolean) => void;
     onIsOpenedChanged?: (isOpened: boolean) => void;
+    onContentResized?: (dimensions: {
+        width: number;
+        height: number;
+    }) => void;
 }>>;
 /**
  * Drawer component supporting controlled and uncontrolled usage.

package/components/Drawer/index.js

@@ -40,7 +40,7 @@ import cssModule from './styles.module.css';
  *   parent needs them to know a click happened at all.
  * - `onIsOpenedChanged` fires in both modes too, and never on mount.
  */
-export const Drawer = ({ openerContent, closerContent, defaultIsOpened = false, isOpened: isOpenedProp, onOpenerClicked, onCloserClicked, onIsOpenedChanged, className, children }) => {
+export const Drawer = ({ openerContent, closerContent, defaultIsOpened = false, isOpened: isOpenedProp, onOpenerClicked, onCloserClicked, onIsOpenedChanged, onContentResized, className, children }) => {
     // State
     const [internalIsOpened, setInternalIsOpened] = useState(defaultIsOpened);
     const [contentDimensions, setContentDimensions] = useState();
@@ -48,6 +48,8 @@ export const Drawer = ({ openerContent, closerContent, defaultIsOpened = false,
     const isOpened = isOpenedProp ?? internalIsOpened;
     // State dispatch
     useChangeDispatch(isOpened, onIsOpenedChanged);
+    useChangeDispatch(contentDimensions, dimensions => { if (dimensions !== undefined)
+        onContentResized?.(dimensions); }, (a, b) => a?.width === b?.width && a?.height === b?.height);
     // User action handlers
     const handleOpenerClick = () => {
         onOpenerClicked?.(isOpened);

package/components/Gallery/index.d.ts

@@ -31,6 +31,10 @@ import type { WithClassName } from '../utils/types.js';
  * before the gallery reacts, with the active index as it was and the target index.
  * @property onActiveSlotChanged - Called after the active slot changed, with
  * the new index.
+ * @property onCanGoLeftChanged - Called after the ability to scroll further left
+ * changed, with the new value. Never on mount.
+ * @property onCanGoRightChanged - Called after the ability to scroll further
+ * right changed, with the new value. Never on mount.
  * @property className - Optional additional class name(s) applied to the root element.
  * @property children - Elements rendered as gallery slots. Each child is wrapped in a slot container.
  */
@@ -48,6 +52,8 @@ export type Props = PropsWithChildren<WithClassName<{
     onNextClicked?: (activePos: number) => void;
     onPaginationClicked?: (activePos: number, targetPos: number) => void;
     onActiveSlotChanged?: (activePos: number) => void;
+    onCanGoLeftChanged?: (canGoLeft: boolean) => void;
+    onCanGoRightChanged?: (canGoRight: boolean) => void;
 }>>;
 /**
  * Horizontally scrollable gallery component with navigation controls and pagination.

package/components/Gallery/index.js

@@ -23,7 +23,7 @@ function resolvePadding(side, shorthand) {
  * - Previous/next navigation controls,
  * - Pagination controls allowing direct slot activation.
  */
-export const Gallery = ({ paddingLeft, paddingRight, padding, prevButtonContent, nextButtonContent, paginationContent, defaultActive, active, noSnap, onPrevClicked, onNextClicked, onPaginationClicked, onActiveSlotChanged, children, className }) => {
+export const Gallery = ({ paddingLeft, paddingRight, padding, prevButtonContent, nextButtonContent, paginationContent, defaultActive, active, noSnap, onPrevClicked, onNextClicked, onPaginationClicked, onActiveSlotChanged, onCanGoLeftChanged, onCanGoRightChanged, children, className }) => {
     // State & refs
     const scrollerRef = useRef(null);
     const [activeIndex, setActiveIndex] = useState(0);
@@ -33,6 +33,8 @@ export const Gallery = ({ paddingLeft, paddingRight, padding, prevButtonContent,
     const isControlled = active !== undefined;
     // State dispatch
     useChangeDispatch(activeIndex, onActiveSlotChanged);
+    useChangeDispatch(canGoLeft, onCanGoLeftChanged);
+    useChangeDispatch(canGoRight, onCanGoRightChanged);
     // User actions handlers
     const handlePrevClick = () => {
         onPrevClicked?.(activeIndex);

package/components/Image/index.d.ts

@@ -1,5 +1,4 @@
 import { type FunctionComponent, type ImgHTMLAttributes } from 'react';
-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.
@@ -27,16 +26,14 @@ type SourceData = {
  * - a single srcSet string,
  * - an array of srcSet strings,
  * - an array of {@link SourceData} objects for full `<source>` control.
- * @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[];
-    theatre?: TheatreProps;
 }> & ImgHTMLAttributes<HTMLImageElement>;
 /**
  * Image component. Wraps a native `<img>` (or `<picture>`) element with
- * optional responsive sources and an optional theatre mode.
+ * optional responsive sources.
  *
  * ### CSS elements
  * - `picture` — wrapping `<picture>` element, always rendered. Contains the

package/components/Image/index.js

@@ -1,13 +1,12 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo } from 'react';
 import { clss } from '../../agnostic/css/clss/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';
 /**
  * Image component. Wraps a native `<img>` (or `<picture>`) element with
- * optional responsive sources and an optional theatre mode.
+ * optional responsive sources.
  *
  * ### CSS elements
  * - `picture` — wrapping `<picture>` element, always rendered. Contains the
@@ -18,7 +17,7 @@ import cssModule from './styles.module.css';
  * @see {@link Props}
  * @returns A `<figure>` element containing a `<picture>` with the image.
  */
-export const Image = ({ sources, theatre, className, ...intrinsicImgAttributes }) => {
+export const Image = ({ sources, className, ...intrinsicImgAttributes }) => {
     // State
     const parsedSources = useMemo(() => {
         if (sources === undefined)
@@ -42,8 +41,5 @@ export const Image = ({ sources, theatre, className, ...intrinsicImgAttributes }
     const pictureClss = c('picture');
     const imgClss = c('image');
     const pictureContent = _jsxs("picture", { className: pictureClss, children: [parsedSources.map((source, index) => _jsx("source", { srcSet: typeof source === 'string' ? source : source.srcSet, type: typeof source === 'string' ? undefined : source.type, media: typeof source === 'string' ? undefined : source.media, sizes: typeof source === 'string' ? undefined : source.sizes }, index)), _jsx("img", { className: imgClss, ...intrinsicImgAttributes })] });
-    const theatricalContent = theatre !== undefined
-        ? _jsx(Theatre, { defaultIsOn: false, ...theatre, children: pictureContent })
-        : pictureContent;
-    return _jsx("figure", { className: rootClss, children: theatricalContent });
+    return _jsx("figure", { className: rootClss, children: pictureContent });
 };

package/components/Overlayer/index.d.ts

@@ -3,7 +3,7 @@ import type { WithClassName } from '../utils/types.js';
 /**
  * Describes a single overlay positioned over the base content.
  *
- * @property content - React node rendered inside the overlay element.
+ * @property children - React node rendered inside the overlay element.
  * If falsy, the overlay is not rendered.
  * @property xPercent - Horizontal position of the overlay anchor as a percentage
  * of the root element's width. Defaults to `0`.
@@ -17,7 +17,7 @@ import type { WithClassName } from '../utils/types.js';
  * - `number` — arbitrary percentage offset (e.g. `25` produces `-25%`).
  */
 type Overlay = {
-    content?: ReactNode;
+    children?: ReactNode;
     xPercent?: number;
     yPercent?: number;
     justify?: 'left' | 'center' | 'right' | number;
@@ -26,7 +26,7 @@ type Overlay = {
  * Props for the {@link Overlayer} component.
  *
  * @property overlays - Array of {@link Overlay} descriptors rendered on top of
- * the base content. Overlays with falsy `content` are skipped.
+ * the base content. Overlays with falsy `children` are skipped.
  * @property className - Optional additional class name(s) applied to the root element.
  * @property children - Content rendered in the base layer, below all overlays.
  */
@@ -40,7 +40,7 @@ export type Props = PropsWithChildren<WithClassName<{
  *
  * ### Child elements
  * - `__base` — wrapping `<div>` that contains `children`.
- * - `__overlay` — one `<div>` per entry in `overlays` (falsy `content` entries
+ * - `__overlay` — one `<div>` per entry in `overlays` (falsy `children` entries
  * are omitted).
  *
  * ### CSS custom properties on each overlay element

package/components/Overlayer/index.js

@@ -11,7 +11,7 @@ import cssModule from './styles.module.css';
  *
  * ### Child elements
  * - `__base` — wrapping `<div>` that contains `children`.
- * - `__overlay` — one `<div>` per entry in `overlays` (falsy `content` entries
+ * - `__overlay` — one `<div>` per entry in `overlays` (falsy `children` entries
  * are omitted).
  *
  * ### CSS custom properties on each overlay element
@@ -30,7 +30,7 @@ export const Overlayer = ({ overlays, children, className }) => {
     const c = clss(publicClassName, { cssModule });
     const rootClss = mergeClassNames(c(), className);
     const baseClss = c('base');
-    return _jsxs("div", { className: rootClss, children: [_jsx("div", { className: baseClss, children: children }), overlays?.map(({ content, xPercent = 0, yPercent = 0, justify }, overlayPos) => {
+    return _jsxs("div", { className: rootClss, children: [_jsx("div", { className: baseClss, children: children }), overlays?.map(({ children: overlayChildren, xPercent = 0, yPercent = 0, justify }, overlayPos) => {
                 const overlayClss = c('overlay');
                 let computedTranslateX;
                 if (typeof justify === 'number') {
@@ -53,8 +53,8 @@ export const Overlayer = ({ overlays, children, className }) => {
                     '--PRIVATE-top': `${yPercent}%`,
                     '--PRIVATE-translate-x': computedTranslateX
                 };
-                if (isFalsy(content))
+                if (isFalsy(overlayChildren))
                     return null;
-                return _jsx("div", { className: overlayClss, style: overlayCustomProps, children: content }, overlayPos);
+                return _jsx("div", { className: overlayClss, style: overlayCustomProps, children: overlayChildren }, overlayPos);
             })] });
 };

package/components/Scrllgngn/index.d.ts

@@ -74,6 +74,8 @@ export type PropsPage = {
  * @property onPageChanged - Called once the current page has changed, never on
  * mount. Receives the zero-based index of the new current page and the
  * corresponding page definition, if available.
+ * @property onContentVisibilityChanged - Called after the scrolling content
+ * area entered or left the viewport, with the new value. Never on mount.
  * @property className - Optional additional class name(s) applied to the root
  * element.
  */
@@ -83,6 +85,7 @@ export type Props = WithClassName<{
     stickyBlocksLazyLoadDistance?: number;
     forceStickBlocks?: 'before' | 'after' | 'both' | 'none';
     onPageChanged?: (currentPagePos: number, pageData?: PropsPage) => void;
+    onContentVisibilityChanged?: (isVisible: boolean) => void;
 }>;
 /**
  * Scrollytelling engine component. Orchestrates layered sticky blocks (`back`

package/components/Scrllgngn/index.js

@@ -56,7 +56,7 @@ import cssModule from './styles.module.css';
  * back-blocks layer, front-blocks layer, paginated scrolling content, and
  * bottom-bound sentinel.
  */
-export const Scrllgngn = ({ pages, thresholdOffsetPercent, stickyBlocksLazyLoadDistance = 2, forceStickBlocks, onPageChanged, className }) => {
+export const Scrllgngn = ({ pages, thresholdOffsetPercent, stickyBlocksLazyLoadDistance = 2, forceStickBlocks, onPageChanged, onContentVisibilityChanged, className }) => {
     // State
     const [topVisible, setTopVis] = useState(false);
     const [contentVisible, setCntVis] = useState(false);
@@ -72,6 +72,7 @@ export const Scrllgngn = ({ pages, thresholdOffsetPercent, stickyBlocksLazyLoadD
     const lazyLoadedFrontBlocks = lazyLoadedBlocks(stickyBlocks, 'front', currentPagePos, stickyBlocksLazyLoadDistance);
     // Handlers
     useChangeDispatch(currentPagePos, pagePos => onPageChanged?.(pagePos, pages?.[pagePos]));
+    useChangeDispatch(contentVisible, onContentVisibilityChanged);
     const handleTopBoundDetect = e => setTopVis(e.ioEntry?.isIntersecting ?? false);
     const handleCntDetect = e => setCntVis(e.ioEntry?.isIntersecting ?? false);
     const handleBtmBoundDetect = e => setBtmVis(e.ioEntry?.isIntersecting ?? false);

package/components/ScrollListener/index.d.ts

@@ -12,6 +12,11 @@ import { type ScrollState } from './utils.js';
  * changed. Receives `undefined` until the first measurement lands.
  * @property onVisibilityChanged - Called on every intersection change, with
  * `true` when the component intersects the viewport.
+ * @property onScrollProgressChanged - Called after the element's vertical outer
+ * scroll progress changed: `0` when it is about to enter the viewport, `1` once
+ * it has fully left it. Never on mount.
+ * @property onScrollDirectionChanged - Called after the document scroll
+ * direction changed, with `'up'` or `'down'`. Never on mount.
  * @property className - Optional additional class name(s) applied to the root element.
  * @property children - React nodes rendered inside the scroll listener container.
  */
@@ -20,6 +25,8 @@ export type Props = PropsWithChildren<WithClassName<{
     stopOnHidden?: boolean;
     onScrollStateChanged?: (scrollState?: ScrollState) => void;
     onVisibilityChanged?: (isVisible: boolean) => void;
+    onScrollProgressChanged?: (progress: number) => void;
+    onScrollDirectionChanged?: (direction: 'up' | 'down') => void;
 }>>;
 /**
  * Exposes scroll metrics — both the document's and its own — as CSS custom

package/components/ScrollListener/index.js

@@ -5,7 +5,7 @@ import { randomHash } from '../../agnostic/random/uuid/index.js';
 import { IntersectionObserverComponent } from '../IntersectionObserver/index.js';
 import { mergeClassNames, useChangeDispatch } from '../utils/index.js';
 import { scrollListener as publicClassName } from '../public-classnames.js';
-import { subscribe, toScrollCssProps, unsubscribe } from './utils.js';
+import { getScrollProgress, subscribe, toScrollCssProps, unsubscribe } from './utils.js';
 import cssModule from './styles.module.css';
 /**
  * Exposes scroll metrics — both the document's and its own — as CSS custom
@@ -45,13 +45,33 @@ import cssModule from './styles.module.css';
  * for everyone, each element only for itself. The listeners exist only while at
  * least one instance is tracking.
  */
-export const ScrollListener = ({ startOnVisible, stopOnHidden, onScrollStateChanged, onVisibilityChanged, className, children }) => {
+export const ScrollListener = ({ startOnVisible, stopOnHidden, onScrollStateChanged, onVisibilityChanged, onScrollProgressChanged, onScrollDirectionChanged, className, children }) => {
     // State & refs
     const [subscriberId] = useState(() => randomHash(6));
     const [scrollState, setScrollState] = useState();
+    const [scrollDirection, setScrollDirection] = useState(null);
     const rootRef = useRef(null);
+    const previousScrollYRef = useRef(null);
+    const scrollProgress = scrollState === undefined
+        ? undefined
+        : getScrollProgress(scrollState).y;
     // State dispatch
     useChangeDispatch(scrollState, onScrollStateChanged);
+    useChangeDispatch(scrollProgress, progress => { if (progress !== undefined)
+        onScrollProgressChanged?.(progress); });
+    useChangeDispatch(scrollDirection, direction => { if (direction !== null)
+        onScrollDirectionChanged?.(direction); });
+    // Fx. dep. `scrollState` - derive the document scroll direction
+    useEffect(() => {
+        if (scrollState === undefined)
+            return;
+        const y = scrollState.global.scroll.y;
+        const previous = previousScrollYRef.current;
+        previousScrollYRef.current = y;
+        if (previous === null || y === previous)
+            return;
+        setScrollDirection(y > previous ? 'down' : 'up');
+    }, [scrollState]);
     // Fx. no dep. - track from mount, unless waiting for the component to show up.
     // The cleanup runs whichever way the subscription was opened.
     useEffect(() => {

package/components/ScrollListener/utils.d.ts

@@ -79,6 +79,14 @@ export declare function subscribe(id: string, subscriber: Subscriber): void;
  * @param id - The id passed to {@link subscribe}.
  */
 export declare function unsubscribe(id: string): void;
+/**
+ * The element's outer scroll progress on each axis — `0` when it is about to
+ * enter the viewport, `1` once it has fully left it.
+ */
+export declare function getScrollProgress(scrollState: ScrollState): {
+    x: number;
+    y: number;
+};
 /**
  * Builds the CSS custom properties exposed on a {@link ScrollListener} root.
  *

package/components/ScrollListener/utils.js

@@ -116,6 +116,17 @@ function outerRange(offset, size, winSize) {
 function progressIn(scroll, [from, to]) {
     return (scroll - from) / Math.max(to - from, 1);
 }
+/**
+ * The element's outer scroll progress on each axis — `0` when it is about to
+ * enter the viewport, `1` once it has fully left it.
+ */
+export function getScrollProgress(scrollState) {
+    const { global: { win, scroll }, local } = scrollState;
+    return {
+        x: progressIn(scroll.x, outerRange(local.offsetX, local.width, win.width)),
+        y: progressIn(scroll.y, outerRange(local.offsetY, local.height, win.height))
+    };
+}
 /**
  * Builds the CSS custom properties exposed on a {@link ScrollListener} root.
  *

package/components/Sequencer/index.d.ts

@@ -36,6 +36,11 @@ import { type Props as ControlledProps } from './index.controlled.js';
  * with the new value.
  * @property onStepChanged - Called after the forwarded step changed, with the
  * new value.
+ * @property onLooped - Called when the step wraps around (either direction),
+ * only while `loop` is `true`.
+ * @property onReachedFirstStep - Called when the forwarded step becomes `0`.
+ * @property onReachedLastStep - Called when the forwarded step becomes the last
+ * one.
  */
 export type Props = Omit<ControlledProps, 'isPlaying' | 'tempo'> & {
     defaultStep?: number;
@@ -51,6 +56,9 @@ export type Props = Omit<ControlledProps, 'isPlaying' | 'tempo'> & {
     onIntersected?: IOCompProps['onIntersected'];
     onIsPlayingChanged?: (isPlaying: boolean) => void;
     onStepChanged?: (step: number) => void;
+    onLooped?: () => void;
+    onReachedFirstStep?: () => void;
+    onReachedLastStep?: () => void;
 };
 /**
  * Uncontrolled, self-advancing sequencer component. Drives a

package/components/Sequencer/index.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useState, useEffect, useCallback, Children } from 'react';
+import { useState, useEffect, useCallback, useRef, Children } from 'react';
 import { absoluteModulo } from '../../agnostic/numbers/absolute-modulo/index.js';
 import { clamp } from '../../agnostic/numbers/clamp/index.js';
 import { IntersectionObserverComponent } from '../IntersectionObserver/index.js';
@@ -30,7 +30,7 @@ import { ControlledSequencer } from './index.controlled.js';
  * @returns An {@link IntersectionObserverComponent} wrapping a
  * {@link ControlledSequencer} with the computed step and modifiers applied.
  */
-export const Sequencer = ({ defaultStep, tempo = 60, play, loop, clampFirst, clampLast, resetOnVisible, resetOnHidden, playOnVisible, pauseOnHidden, onIntersected, onIsPlayingChanged, onStepChanged, ...controlledProps }) => {
+export const Sequencer = ({ defaultStep, tempo = 60, play, loop, clampFirst, clampLast, resetOnVisible, resetOnHidden, playOnVisible, pauseOnHidden, onIntersected, onIsPlayingChanged, onStepChanged, onLooped, onReachedFirstStep, onReachedLastStep, ...controlledProps }) => {
     // State
     const { step, activateOnStep, children } = controlledProps;
     const [internalPlay, setInternalPlay] = useState(play ?? false);
@@ -63,6 +63,23 @@ export const Sequencer = ({ defaultStep, tempo = 60, play, loop, clampFirst, cla
     // State dispatch
     useChangeDispatch(actualPlay, onIsPlayingChanged);
     useChangeDispatch(forwardedStep, onStepChanged);
+    // Fx. dep. `forwardedStep` - loop / boundary events
+    const previousStepsRef = useRef(null);
+    useEffect(() => {
+        if (stepsCount <= 0)
+            return;
+        const previous = previousStepsRef.current;
+        previousStepsRef.current = { forwarded: forwardedStep, actual: actualStep };
+        if (previous === null)
+            return;
+        const lapChanged = Math.floor(actualStep / stepsCount) !== Math.floor(previous.actual / stepsCount);
+        if (loop === true && lapChanged)
+            onLooped?.();
+        if (forwardedStep === 0 && previous.forwarded !== 0)
+            onReachedFirstStep?.();
+        if (forwardedStep === stepsCount - 1 && previous.forwarded !== stepsCount - 1)
+            onReachedLastStep?.();
+    }, [forwardedStep, actualStep, stepsCount, loop]);
     // Action handlers
     const handleIntersection = useCallback(({ ioEntry, observer }) => {
         onIntersected?.({ ioEntry, observer });

package/components/Theatre/index.d.ts

@@ -13,9 +13,16 @@ import type { WithClassName } from '../utils/types.js';
  * open counts as a toggle.
  * @property exitOnBgClick - When `true`, clicking the stage background — and
  * not its content — counts as a toggle.
- * @property onToggleClicked - Called whenever a toggle is requested: the open
- * or close button, the `Escape` key, or the stage background. Fires before the
- * theatre reacts, with the state as it was.
+ * @property onOpenButtonClicked - Called when the open button is clicked, before
+ * the theatre reacts, with the state as it was.
+ * @property onCloseButtonClicked - Called when the close button is clicked,
+ * before the theatre reacts, with the state as it was.
+ * @property onBackgroundClicked - Called when the stage background is clicked
+ * (only while `exitOnBgClick` is `true`), before the theatre reacts, with the
+ * state as it was.
+ * @property onEscapePressed - Called when `Escape` is pressed while the stage is
+ * open (only while `exitOnEscape` is `true`), before the theatre reacts, with
+ * the state as it was.
  * @property onIsOnChanged - Called after the theatre mode changed, with the new
  * value.
  * @property className - Optional additional class name(s) applied to the root element.
@@ -29,7 +36,10 @@ export type Props = PropsWithChildren<WithClassName<{
     defaultIsOn?: boolean;
     exitOnEscape?: boolean;
     exitOnBgClick?: boolean;
-    onToggleClicked?: (isOn: boolean) => void;
+    onOpenButtonClicked?: (isOn: boolean) => void;
+    onCloseButtonClicked?: (isOn: boolean) => void;
+    onBackgroundClicked?: (isOn: boolean) => void;
+    onEscapePressed?: (isOn: boolean) => void;
     onIsOnChanged?: (isOn: boolean) => void;
 }>>;
 /**
@@ -53,8 +63,8 @@ export type Props = PropsWithChildren<WithClassName<{
  * @remarks
  * - In controlled mode (`isOn` defined), the state is fully driven by the
  *   parent and internal state is never updated.
- * - `onToggleClicked` fires in both modes, for all four toggle sources — a
- *   controlled parent needs it to know a toggle was requested at all.
+ * - The four toggle-source handlers fire in both modes — a controlled parent
+ *   needs them to know a toggle was requested at all.
  * - `onIsOnChanged` fires in both modes too, and never on mount.
  */
 export declare const Theatre: FunctionComponent<Props>;

package/components/Theatre/index.js

@@ -25,11 +25,11 @@ import cssModule from './styles.module.css';
  * @remarks
  * - In controlled mode (`isOn` defined), the state is fully driven by the
  *   parent and internal state is never updated.
- * - `onToggleClicked` fires in both modes, for all four toggle sources — a
- *   controlled parent needs it to know a toggle was requested at all.
+ * - The four toggle-source handlers fire in both modes — a controlled parent
+ *   needs them to know a toggle was requested at all.
  * - `onIsOnChanged` fires in both modes too, and never on mount.
  */
-export const Theatre = ({ closeBtnContent, openBtnContent, isOn: isOnProp, defaultIsOn = false, exitOnEscape, exitOnBgClick, onToggleClicked, onIsOnChanged, children, className }) => {
+export const Theatre = ({ closeBtnContent, openBtnContent, isOn: isOnProp, defaultIsOn = false, exitOnEscape, exitOnBgClick, onOpenButtonClicked, onCloseButtonClicked, onBackgroundClicked, onEscapePressed, onIsOnChanged, children, className }) => {
     // State & refs
     const [internalIsOn, setInternalIsOn] = useState(defaultIsOn);
     const stageRef = useRef(null);
@@ -39,18 +39,24 @@ export const Theatre = ({ closeBtnContent, openBtnContent, isOn: isOnProp, defau
     useChangeDispatch(isOn, onIsOnChanged);
     // User action handlers
     const requestToggle = (targetIsOn) => {
-        onToggleClicked?.(isOn);
         if (isControlled)
             return;
         setInternalIsOn(targetIsOn);
     };
-    const handleOpenBtnClick = () => requestToggle(true);
-    const handleCloseBtnClick = () => requestToggle(false);
+    const handleOpenButtonClick = () => {
+        onOpenButtonClicked?.(isOn);
+        requestToggle(true);
+    };
+    const handleCloseButtonClick = () => {
+        onCloseButtonClicked?.(isOn);
+        requestToggle(false);
+    };
     const handleStageBgClick = e => {
         if (exitOnBgClick !== true)
             return;
         if (e.target !== stageRef.current)
             return;
+        onBackgroundClicked?.(isOn);
         requestToggle(false);
     };
     // Fx. dep. `exitOnEscape`, `isOn` - close the stage on the Escape key
@@ -60,11 +66,12 @@ export const Theatre = ({ closeBtnContent, openBtnContent, isOn: isOnProp, defau
         const handleKeyDown = (e) => {
             if (e.key !== 'Escape')
                 return;
+            onEscapePressed?.(isOn);
             requestToggle(false);
         };
         window.addEventListener('keydown', handleKeyDown);
         return () => window.removeEventListener('keydown', handleKeyDown);
-    }, [exitOnEscape, isOn, isControlled]);
+    }, [exitOnEscape, isOn, isControlled, onEscapePressed]);
     // Rendering
     const c = clss(publicClassName, { cssModule });
     const rootClss = mergeClassNames(c(null, {
@@ -74,5 +81,5 @@ export const Theatre = ({ closeBtnContent, openBtnContent, isOn: isOnProp, defau
     const stageClss = c('stage');
     const openBtnClss = c('open-btn');
     const closeBtnClss = c('close-btn');
-    return _jsxs("div", { className: rootClss, children: [children, _jsx("div", { className: stageClss, onClick: handleStageBgClick, ref: stageRef, children: isOn && children }), _jsx("div", { className: closeBtnClss, onClick: handleCloseBtnClick, children: closeBtnContent }), _jsx("div", { className: openBtnClss, onClick: handleOpenBtnClick, children: openBtnContent })] });
+    return _jsxs("div", { className: rootClss, children: [children, _jsx("div", { className: stageClss, onClick: handleStageBgClick, ref: stageRef, children: isOn && children }), _jsx("div", { className: closeBtnClss, onClick: handleCloseButtonClick, children: closeBtnContent }), _jsx("div", { className: openBtnClss, onClick: handleOpenButtonClick, children: openBtnContent })] });
 };

package/node/images/transform/operations/index.d.ts

@@ -3,8 +3,8 @@ export * as brighten from './brighten/index.js'
 export * as extend from './extend/index.js'
 export * as extract from './extract/index.js'
 export * as flatten from './flatten/index.js'
-export * as flip from './flip/index.js'
 export * as flop from './flop/index.js'
+export * as flip from './flip/index.js'
 export * as hue from './hue/index.js'
 export * as level from './level/index.js'
 export * as lighten from './lighten/index.js'

package/node/images/transform/operations/index.js

@@ -3,8 +3,8 @@ export * as brighten from './brighten/index.js'
 export * as extend from './extend/index.js'
 export * as extract from './extract/index.js'
 export * as flatten from './flatten/index.js'
-export * as flip from './flip/index.js'
 export * as flop from './flop/index.js'
+export * as flip from './flip/index.js'
 export * as hue from './hue/index.js'
 export * as level from './level/index.js'
 export * as lighten from './lighten/index.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@design-edito/tools",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "description": "",
   "author": "Maxime Fabas",
   "license": "ISC",