@design-edito/tools 0.3.10 → 0.3.11

package/agnostic/objects/index.d.ts

@@ -1,9 +1,9 @@
+export * as deepGetProperty from './deep-get-property/index.js'
 export * as enums from './enums/index.js'
-export * as flattenGetters from './flatten-getters/index.js'
-export * as isObject from './is-object/index.js'
 export * as isRecord from './is-record/index.js'
-export * as deepGetProperty from './deep-get-property/index.js'
+export * as isObject from './is-object/index.js'
+export * as recordFormat from './record-format/index.js'
+export * as flattenGetters from './flatten-getters/index.js'
 export * as recordMap from './record-map/index.js'
 export * as sortKeys from './sort-keys/index.js'
-export * as recordFormat from './record-format/index.js'
 export * as validation from './validation/index.js'

package/agnostic/objects/index.js

@@ -1,9 +1,9 @@
+export * as deepGetProperty from './deep-get-property/index.js'
 export * as enums from './enums/index.js'
-export * as flattenGetters from './flatten-getters/index.js'
-export * as isObject from './is-object/index.js'
 export * as isRecord from './is-record/index.js'
-export * as deepGetProperty from './deep-get-property/index.js'
+export * as isObject from './is-object/index.js'
+export * as recordFormat from './record-format/index.js'
+export * as flattenGetters from './flatten-getters/index.js'
 export * as recordMap from './record-map/index.js'
 export * as sortKeys from './sort-keys/index.js'
-export * as recordFormat from './record-format/index.js'
 export * as validation from './validation/index.js'

package/agnostic/sanitization/index.d.ts

@@ -1,4 +1,4 @@
+export * as fileName from './file-name/index.js'
 export * as path from './path/index.js'
 export * as html from './html/index.js'
-export * as fileName from './file-name/index.js'
 export * as userInput from './user-input/index.js'

package/agnostic/sanitization/index.js

@@ -1,4 +1,4 @@
+export * as fileName from './file-name/index.js'
 export * as path from './path/index.js'
 export * as html from './html/index.js'
-export * as fileName from './file-name/index.js'
 export * as userInput from './user-input/index.js'

package/agnostic/strings/index.d.ts

@@ -1,6 +1,6 @@
-export * as charCodes from './char-codes/index.js'
 export * as matches from './matches/index.js'
 export * as normalizeIndent from './normalize-indent/index.js'
+export * as charCodes from './char-codes/index.js'
 export * as parseTable from './parse-table/index.js'
 export * as replaceAll from './replace-all/index.js'
 export * as toAlphanum from './to-alphanum/index.js'

package/agnostic/strings/index.js

@@ -1,6 +1,6 @@
-export * as charCodes from './char-codes/index.js'
 export * as matches from './matches/index.js'
 export * as normalizeIndent from './normalize-indent/index.js'
+export * as charCodes from './char-codes/index.js'
 export * as parseTable from './parse-table/index.js'
 export * as replaceAll from './replace-all/index.js'
 export * as toAlphanum from './to-alphanum/index.js'

package/agnostic/time/index.d.ts

@@ -1,5 +1,5 @@
+export * as duration from './duration/index.js'
 export * as dates from './dates/index.js'
+export * as wait from './wait/index.js'
 export * as timeout from './timeout/index.js'
-export * as duration from './duration/index.js'
 export * as transitions from './transitions/index.js'
-export * as wait from './wait/index.js'

package/agnostic/time/index.js

@@ -1,5 +1,5 @@
+export * as duration from './duration/index.js'
 export * as dates from './dates/index.js'
+export * as wait from './wait/index.js'
 export * as timeout from './timeout/index.js'
-export * as duration from './duration/index.js'
 export * as transitions from './transitions/index.js'
-export * as wait from './wait/index.js'

package/agnostic/time/transitions/index.d.ts

@@ -54,16 +54,16 @@ export type EasingFunction = (progress: number) => number;
  */
 export type EasingDictionary = Record<string, EasingFunction>;
 /**
- * Performs a numeric transition from 0 to `to` over `durationMs` milliseconds.
+ * Performs a numeric transition from 0 to `steps` over `durationMs` milliseconds.
  * Invokes a callback at each step with the eased value and timestamp.
  *
- * @param to - The number of steps or increments for the transition.
+ * @param steps - The number of steps or increments for the transition.
  * @param durationMs - Total duration of the transition in milliseconds.
  * @param callbackOrEase - Either a callback function for each step or a predefined easing name.
  * @param callback - Optional callback if `callbackOrEase` is an easing name.
  * @returns A promise that resolves when the transition is complete.
  */
-export declare function transition(to: number, durationMs: number, callbackOrEase: Ease | Callback, callback?: Callback): Promise<void>;
+export declare function transition(steps: number, durationMs: number, callbackOrEase: Ease | Callback, callback?: Callback): Promise<void>;
 /**
  * Predefined easing functions used internally by transitions.
  */

package/agnostic/time/transitions/index.js

@@ -34,18 +34,18 @@ var Ease = /* @__PURE__ */ ((Ease2) => {
   Ease2["EASE_IN_OUT_BOUNCE"] = "ease-in-out-bounce";
   return Ease2;
 })(Ease || {});
-async function transition(to, durationMs, callbackOrEase, callback) {
+async function transition(steps, durationMs, callbackOrEase, callback) {
   const ease = typeof callbackOrEase === "string" ? callbackOrEase : "linear" /* LINEAR */;
   const easing = easings[ease];
   if (easing === void 0) return;
   const actualCallback = callback ?? (typeof callbackOrEase === "function" ? callbackOrEase : void 0);
   if (actualCallback === void 0) return;
   const start = Date.now();
-  const timeTable = new Array(to).fill(null).map((_, step) => {
-    const progression = (step + 1) / to;
+  const timeTable = new Array(steps).fill(null).map((_, step) => {
+    const progression = (step + 1) / steps;
     const eased = easing(progression);
     const time = start + eased * durationMs;
-    return { time, step: eased * to };
+    return { time, step: eased * steps };
   });
   for (const { time, step } of timeTable) {
     const now = Date.now();

package/components/Disclaimer/index.d.ts

@@ -0,0 +1,45 @@
+import { type ReactNode, type PropsWithChildren, type FunctionComponent } from 'react';
+import type { WithClassName } from '../utils/types.js';
+/**
+ * Props for the Disclaimer component.
+ *
+ * @property content - Content displayed inside the disclaimer panel.
+ * @property togglerContent - Content rendered inside the dismiss toggler.
+ * If not provided, the toggler is not rendered.
+ * @property isOn - Controls the visibility state. When defined, the component
+ * behaves as a controlled component.
+ * @property defaultIsOn - Default visibility state for uncontrolled mode.
+ * @property stateHandlers - Callbacks invoked after state changes.
+ * @property stateHandlers.toggled - Callback invoked after the disclaimer state changes.
+ * @property actionHandlers - Callbacks invoked before actions are committed.
+ * @property actionHandlers.dismissClick - Callback invoked before the disclaimer is dismissed.
+ * @property className - Optional additional class name(s) applied to the root element.
+ * @property children - Additional content rendered below the disclaimer panel.
+ */
+export type Props = PropsWithChildren<WithClassName<{
+    content?: ReactNode;
+    togglerContent?: ReactNode;
+    isOn?: boolean;
+    defaultIsOn?: boolean;
+    stateHandlers?: {
+        toggled?: (isOn: boolean) => void;
+    };
+    actionHandlers?: {
+        dismissClick?: (prevIsOn: boolean) => void;
+    };
+}>>;
+/**
+ * Component that displays a dismissible disclaimer panel.
+ *
+ * Supports both controlled (`isOn` provided) and uncontrolled modes.
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ *
+ * @remarks
+ * - In controlled mode, visibility is driven by `isOn` and internal state
+ *   does not toggle automatically.
+ * - In uncontrolled mode, the component manages its own visibility state.
+ * - Applies `on` and `off` modifier classes depending on visibility state.
+ */
+export declare const Disclaimer: FunctionComponent<Props>;

package/components/Disclaimer/index.js

@@ -0,0 +1,70 @@
+// src/components/Disclaimer/index.tsx
+import {
+  useState,
+  useEffect,
+  useRef
+} from "react";
+import { clss } from "../../agnostic/css/clss/index.js";
+import { mergeClassNames } from "../utils/index.js";
+import { disclaimer as publicClassName } from "../public-classnames.js";
+import cssModule from "./styles.module.css";
+import { jsx, jsxs } from "react/jsx-runtime";
+var Disclaimer = ({
+  content,
+  togglerContent,
+  isOn: isOnProp,
+  defaultIsOn: defaultIsOnProp,
+  stateHandlers,
+  actionHandlers,
+  children,
+  className
+}) => {
+  const [internalIsOn, setInternalIsOn] = useState(isOnProp ?? defaultIsOnProp ?? true);
+  const isOn = isOnProp ?? internalIsOn;
+  const pIsOn = useRef(isOn);
+  useEffect(() => {
+    if (pIsOn.current === isOn) return;
+    stateHandlers?.toggled?.(isOn);
+    pIsOn.current = isOn;
+  }, [isOn]);
+  const handleDismissClick = () => {
+    actionHandlers?.dismissClick?.(isOn);
+    if (isOnProp !== void 0) return;
+    setInternalIsOn(false);
+  };
+  const c = clss(publicClassName, { cssModule });
+  const rootClss = mergeClassNames(
+    c(null, {
+      on: isOn,
+      off: !isOn
+    }),
+    className
+  );
+  const panelClss = c("panel");
+  const contentClss = c("content");
+  const btnClss = c("toggler");
+  const sensitiveClss = c("sensitive");
+  return /* @__PURE__ */ jsxs("div", { className: rootClss, children: [
+    /* @__PURE__ */ jsxs("div", { className: panelClss, children: [
+      content !== void 0 && /* @__PURE__ */ jsx(
+        "div",
+        {
+          className: contentClss,
+          children: content
+        }
+      ),
+      togglerContent !== void 0 && /* @__PURE__ */ jsx(
+        "div",
+        {
+          className: btnClss,
+          onClick: handleDismissClick,
+          children: togglerContent
+        }
+      )
+    ] }),
+    /* @__PURE__ */ jsx("div", { className: sensitiveClss, children })
+  ] });
+};
+export {
+  Disclaimer
+};

package/components/Drawer/index.d.ts

@@ -0,0 +1,45 @@
+import { type PropsWithChildren, type FunctionComponent, type ReactNode } from 'react';
+import type { WithClassName } from '../utils/types.js';
+/**
+ * Props for the Drawer component.
+ *
+ * @property openerContent - Content rendered inside the opener control.
+ * @property closerContent - Content rendered inside the closer control.
+ * @property initialIsOpened - Initial open state in uncontrolled mode.
+ * Ignored when `isOpened` is provided.
+ * @property isOpened - Controlled open state. When defined, the component
+ * behaves as a controlled component and internal state is ignored.
+ * @property stateHandlers - Callbacks invoked after the state changes
+ * @property stateHandlers.toggled - Callbacks invoked after the isOpened state has changed
+ * @property className - Additional class name(s) applied to the root element.
+ * @property children - Drawer content.
+ */
+export type Props = PropsWithChildren<WithClassName<{
+    openerContent?: ReactNode;
+    closerContent?: ReactNode;
+    initialIsOpened?: boolean;
+    isOpened?: boolean;
+    stateHandlers?: {
+        toggled?: (isOpen: boolean) => void;
+    };
+}>>;
+/**
+ * Drawer component with optional controlled and uncontrolled behavior.
+ *
+ * @remarks
+ * - In controlled mode (`isOpened` defined), visibility is fully driven by the prop.
+ * - In uncontrolled mode, internal state is initialized from `initialIsOpened`.
+ * - The component measures its content using `ResizeObserverComponent`
+ *   and exposes the dimensions:
+ *   - As CSS custom properties:
+ *     --{prefix}-content-height
+ *     --{prefix}-content-height-px
+ *     --{prefix}-content-width
+ *     --{prefix}-content-width-px
+ *   - As `data-content-width` and `data-content-height` attributes.
+ *
+ * CSS modifier classes:
+ * - `opened` when open
+ * - `closed` when closed
+ */
+export declare const Drawer: FunctionComponent<Props>;

package/components/Drawer/index.js

@@ -0,0 +1,82 @@
+// src/components/Drawer/index.tsx
+import {
+  useState,
+  useRef,
+  useEffect
+} from "react";
+import { clss } from "../../agnostic/css/clss/index.js";
+import { mergeClassNames } from "../utils/index.js";
+import { drawer as publicClassName } from "../public-classnames.js";
+import cssModule from "./styles.module.css";
+import {
+  ResizeObserverComponent
+} from "../ResizeObserver/index.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+var Drawer = ({
+  openerContent,
+  closerContent,
+  initialIsOpened = false,
+  isOpened: isOpenedProp,
+  stateHandlers,
+  className,
+  children
+}) => {
+  const [internalIsOpened, setInternalIsOpened] = useState(isOpenedProp ?? initialIsOpened);
+  const isOpened = isOpenedProp ?? internalIsOpened;
+  const pIsOpened = useRef(isOpened);
+  const [{ width, height }, setContentDimensions] = useState({});
+  useEffect(() => {
+    if (pIsOpened.current === isOpened) return;
+    pIsOpened.current = isOpened;
+    stateHandlers?.toggled?.(isOpened);
+  }, [isOpened]);
+  const handleOpenerClick = () => {
+    if (isOpenedProp !== void 0) return;
+    setInternalIsOpened(true);
+  };
+  const handleCloserClick = () => {
+    if (isOpenedProp !== void 0) return;
+    setInternalIsOpened(false);
+  };
+  const handleROCompResize = ({ entry }) => {
+    const { width: width2, height: height2 } = entry?.contentRect ?? {};
+    setContentDimensions({ width: width2, height: height2 });
+  };
+  const c = clss(publicClassName, { cssModule });
+  const rootClss = mergeClassNames(c(null, {
+    "opened": isOpened,
+    "closed": !isOpened
+  }), className);
+  const openerClss = c("opener");
+  const closerClss = c("closer");
+  const contentClss = c("content");
+  const dimensions = { width, height };
+  const customCssProps = Object.entries(dimensions).reduce((acc, [key, val]) => {
+    if (val === void 0) return acc;
+    return {
+      ...acc,
+      [`--${publicClassName}-content-${key}`]: `${val}`,
+      [`--${publicClassName}-content-${key}-px`]: `${val}px`
+    };
+  }, {});
+  const dataAttributes = Object.entries(dimensions).reduce((acc, [key, val]) => {
+    if (val === void 0) return acc;
+    return { ...acc, [`data-content-${key}`]: `${val}` };
+  }, {});
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: rootClss,
+      ...dataAttributes,
+      style: { ...customCssProps },
+      children: [
+        /* @__PURE__ */ jsx("div", { className: openerClss, onClick: handleOpenerClick, children: openerContent }),
+        /* @__PURE__ */ jsx("div", { className: closerClss, onClick: handleCloserClick, children: closerContent }),
+        /* @__PURE__ */ jsx("div", { className: contentClss, children: /* @__PURE__ */ jsx(ResizeObserverComponent, { onResized: handleROCompResize, children }) })
+      ]
+    }
+  );
+};
+export {
+  Drawer
+};

package/components/EventListener/index.d.ts

@@ -1,10 +1,27 @@
-import { type ReactNode, type JSX } from 'react';
+import { type ReactNode, type FunctionComponent } from 'react';
+/**
+ * Props for the EventListenerComponent.
+ *
+ * @property className - Optional additional class name(s) applied to the root element.
+ * @property type - Event type or list of event types to listen to (e.g. "click", ["mouseenter", "focus"]).
+ * @property targetSelector - Optional CSS selector used to match descendant elements
+ * within the root element. If omitted, the listener is attached to the root element itself.
+ * @property onEvent - Callback invoked when one of the specified events is triggered.
+ * Receives the native DOM Event object.
+ * @property children - React children rendered inside the root element.
+ */
 export type Props = {
     className?: string;
     type?: string | string[];
     targetSelector?: string;
     onEvent?: (e: Event) => void;
-    content?: ReactNode;
     children?: ReactNode;
 };
-export declare const EventListenerComponent: ({ className, type, targetSelector, onEvent, content, children }: Props) => JSX.Element;
+/**
+ * Component that attaches one or multiple DOM event listeners to its root element
+ * or to matching descendants.
+ * @param props - Component properties
+ * @see {@link Props}
+ * @returns A span element wrapping `children`, with configured event listeners.
+ */
+export declare const EventListenerComponent: FunctionComponent<Props>;

package/components/EventListener/index.js

@@ -4,16 +4,15 @@ import {
   useEffect
 } from "react";
 import { clss } from "../../agnostic/css/clss/index.js";
-import { isNotFalsy } from "../../agnostic/booleans/is-falsy/index.js";
-import { eventListener } from "../public-classnames.js";
+import { mergeClassNames } from "../utils/index.js";
+import { eventListener 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 EventListenerComponent = ({
   className,
   type,
   targetSelector,
   onEvent,
-  content,
   children
 }) => {
   const rootRef = useRef(null);
@@ -22,25 +21,19 @@ var EventListenerComponent = ({
     if (onEvent === void 0 || type === void 0 || root === null) return;
     const typeArr = Array.isArray(type) ? type : [type];
     const elements = Array.from(targetSelector === void 0 ? [root] : root.querySelectorAll(targetSelector));
-    elements.forEach((elt) => {
-      typeArr.forEach((type2) => {
-        elt.addEventListener(type2, onEvent);
-      });
-    });
-    return () => {
-      elements.forEach((elt) => {
-        typeArr.forEach((type2) => {
-          elt.removeEventListener(type2, onEvent);
-        });
-      });
-    };
+    elements.forEach((e) => typeArr.forEach((t) => e.addEventListener(t, onEvent)));
+    return () => elements.forEach((e) => typeArr.forEach((t) => e.removeEventListener(t, onEvent)));
   }, [targetSelector, type, onEvent]);
-  const c = clss(eventListener, { cssModule });
-  const wrapperClassName = [c(null), className].filter(isNotFalsy).join(" ");
-  return /* @__PURE__ */ jsxs("span", { className: wrapperClassName, ref: rootRef, children: [
-    children,
-    content
-  ] });
+  const c = clss(publicClassName, { cssModule });
+  const rootClss = mergeClassNames(c(), className);
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      className: rootClss,
+      ref: rootRef,
+      children
+    }
+  );
 };
 export {
   EventListenerComponent

package/components/Gallery/index.d.ts

@@ -0,0 +1,67 @@
+import { type FunctionComponent, type PropsWithChildren, type ReactNode } from 'react';
+import type { WithClassName } from '../utils/types.js';
+/**
+ * Props for the Gallery component.
+ *
+ * @property paddingLeft - Left padding applied to the first slot. Accepts a number (pixels) or any valid CSS length value.
+ * If not provided, falls back to `padding` or `0px`.
+ * @property paddingRight - Right padding applied to the last slot. Accepts a number (pixels) or any valid CSS length value.
+ * If not provided, falls back to `padding` or `0px`.
+ * @property padding - Shorthand horizontal padding applied to both ends when `paddingLeft` and/or `paddingRight`
+ * are not explicitly defined. Accepts a number (pixels) or any valid CSS length value.
+ * @property prevButtonContent - Content rendered inside the "previous" navigation control.
+ * Defaults to the string `"prev"` when not provided.
+ * @property nextButtonContent - Content rendered inside the "next" navigation control.
+ * Defaults to the string `"next"` when not provided.
+ * @property paginationContent - Content rendered inside each pagination item.
+ * Can be:
+ * - A ReactNode used for all pages,
+ * - A function receiving the page index and returning a ReactNode,
+ * - Undefined, in which case the page index is displayed.
+ * @property initActive - Optional. When uncontrolled mode, sets the default active slot at mount
+ * @property active - Optional controlled index. When provided, the active slot is driven by this
+ * value instead of internal scroll-derived state. When omitted, the component manages its own
+ * active index based on scroll position.
+ * @property noSnap - Optional, defines if scroll is free in side the scroller or not (defaults to false)
+ * @property stateHandlers - Callbacks called after the state changed
+ * @property stateHandlers.slotChanged - Called when the active slot changes due to scrolling. Receives the new active index.
+ * @property actionHandlers - Callbacks called after a user interaction
+ * @property actionHandlers.prevClick - Called when the "previous" control is clicked. Receives the current active index before navigation occurs.
+ * @property actionHandlers.nextClick - Called when the "next" control is clicked. Receives the current active index before navigation occurs.
+ * @property actionHandlers.paginationClick - Called when a pagination item is clicked. Receives the current active index and the target index.
+ * @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.
+ */
+export type Props = PropsWithChildren<WithClassName<{
+    paddingLeft?: string | number;
+    paddingRight?: string | number;
+    padding?: string | number;
+    prevButtonContent?: ReactNode;
+    nextButtonContent?: ReactNode;
+    paginationContent?: ReactNode | ((page: number) => ReactNode);
+    initActive?: number;
+    active?: number;
+    noSnap?: boolean;
+    stateHandlers?: {
+        slotChanged?: (activePos: number) => void;
+    };
+    actionHandlers?: {
+        prevClick?: (activePos: number) => void;
+        nextClick?: (activePos: number) => void;
+        paginationClick?: (activePos: number, targetPos: number) => void;
+    };
+}>>;
+/**
+ * Horizontally scrollable gallery component with navigation controls and pagination.
+ *
+ * Tracks the active slot based on scroll position and exposes state through CSS class names
+ * and a `data-active` attribute on the root element.
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ * @returns A container element wrapping:
+ * - A scrollable area containing each child in a slot wrapper,
+ * - Previous/next navigation controls,
+ * - Pagination controls allowing direct slot activation.
+ */
+export declare const Gallery: FunctionComponent<Props>;