@design-edito/tools 0.4.22 → 0.5.0

package/agnostic/time/dates/to-french-republican/utils.js

@@ -0,0 +1,155 @@
+import { RepublicanMonth, ComplementaryDay, DecadeDay } from './types.js';
+// Ordered lookup tables derived from the enums (declaration order).
+/** The twelve month names, indexed by 0-based month index. */
+export const MONTH_NAMES = Object.values(RepublicanMonth);
+/** The six complementary day names, indexed by 0-based complementary index. */
+export const COMPLEMENTARY_DAY_NAMES = Object.values(ComplementaryDay);
+/** The ten décade day names, indexed by 0-based day-of-décade index. */
+export const DECADE_DAY_NAMES = Object.values(DecadeDay);
+// Paris Observatory meridian: 2°20'14" E ≈ +9m21s, expressed in days.
+// The Republican astronomers used the Paris meridian to decide which civil day
+// hosts the equinox, so we keep using it for every year.
+const PARIS_MERIDIAN_OFFSET_DAYS = (2 + 20 / 60 + 14 / 3600) / 360;
+const DEG_TO_RAD = Math.PI / 180;
+// --- Julian Day -------------------------------------------------------------
+/**
+ * Julian Day Number (integer, noon-based) for a proleptic Gregorian date.
+ *
+ * @param year - Gregorian year.
+ * @param month - Month, 1–12.
+ * @param day - Day of month, 1–31.
+ * @returns The Julian Day Number.
+ */
+export function gregorianToJdn(year, month, day) {
+    const a = Math.floor((14 - month) / 12);
+    const y = year + 4800 - a;
+    const m = month + 12 * a - 3;
+    return (day
+        + Math.floor((153 * m + 2) / 5)
+        + 365 * y
+        + Math.floor(y / 4)
+        - Math.floor(y / 100)
+        + Math.floor(y / 400)
+        - 32045);
+}
+// --- Astronomy: September equinox (Meeus, "Astronomical Algorithms", ch. 27) --
+// Periodic-term table 27.A: rows of [A, B (deg), C (deg)].
+const EQUINOX_TERMS = [
+    [485, 324.96, 1934.136], [203, 337.23, 32964.467], [199, 342.08, 20.186],
+    [182, 27.85, 445267.112], [156, 73.14, 45036.886], [136, 171.52, 22518.443],
+    [77, 222.54, 65928.934], [74, 296.72, 3034.906], [70, 243.58, 9037.513],
+    [58, 119.81, 33718.147], [52, 297.17, 150.678], [50, 21.02, 2281.226],
+    [45, 247.54, 29929.562], [44, 325.15, 31555.956], [29, 60.93, 4443.417],
+    [18, 155.12, 67555.328], [17, 288.79, 4562.452], [16, 198.04, 62894.029],
+    [14, 199.76, 31436.921], [12, 95.39, 14577.848], [12, 287.11, 31931.756],
+    [12, 320.81, 34777.259], [9, 227.73, 1222.114], [8, 15.45, 16859.074]
+];
+// Instant of the September equinox for a Gregorian year, as a Julian Ephemeris
+// Day (JDE) in Dynamical Time (TD). Valid roughly for years 1000..3000.
+function septemberEquinoxJde(year) {
+    const y = (year - 2000) / 1000;
+    const jde0 = 2451810.21715
+        + 365242.01767 * y
+        - 0.11575 * y * y
+        + 0.00337 * y * y * y
+        + 0.00078 * y * y * y * y;
+    const t = (jde0 - 2451545.0) / 36525;
+    const w = (35999.373 * t - 2.47) * DEG_TO_RAD;
+    const deltaLambda = 1 + 0.0334 * Math.cos(w) + 0.0007 * Math.cos(2 * w);
+    let s = 0;
+    for (const [a, b, c] of EQUINOX_TERMS) {
+        s += a * Math.cos((b + c * t) * DEG_TO_RAD);
+    }
+    return jde0 + (0.00001 * s) / deltaLambda;
+}
+// TD - UT, in seconds. Espenak & Meeus (2006) polynomial approximations,
+// covering the range that matters here (18th–22nd century) with a parabolic
+// fallback outside it.
+function deltaTSeconds(year) {
+    let t;
+    if (year >= 2005 && year < 2050) {
+        t = year - 2000;
+        return 62.92 + 0.32217 * t + 0.005589 * t * t;
+    }
+    if (year >= 1986 && year < 2005) {
+        t = year - 2000;
+        return (63.86 + 0.3345 * t - 0.060374 * t * t + 0.0017275 * t ** 3
+            + 0.000651814 * t ** 4 + 0.00002373599 * t ** 5);
+    }
+    if (year >= 1961 && year < 1986) {
+        t = year - 1975;
+        return 45.45 + 1.067 * t - (t * t) / 260 - (t ** 3) / 718;
+    }
+    if (year >= 1941 && year < 1961) {
+        t = year - 1950;
+        return 29.07 + 0.407 * t - (t * t) / 233 + (t ** 3) / 2547;
+    }
+    if (year >= 1920 && year < 1941) {
+        t = year - 1920;
+        return 21.20 + 0.84493 * t - 0.076100 * t * t + 0.0020936 * t ** 3;
+    }
+    if (year >= 1900 && year < 1920) {
+        t = year - 1900;
+        return (-2.79 + 1.494119 * t - 0.0598939 * t * t
+            + 0.0061966 * t ** 3 - 0.000197 * t ** 4);
+    }
+    if (year >= 1860 && year < 1900) {
+        t = year - 1860;
+        return (7.62 + 0.5737 * t - 0.251754 * t * t + 0.01680668 * t ** 3
+            - 0.0004473624 * t ** 4 + (t ** 5) / 233174);
+    }
+    if (year >= 1800 && year < 1860) {
+        t = year - 1800;
+        return (13.72 - 0.332447 * t + 0.0068612 * t * t + 0.0041116 * t ** 3
+            - 0.00037436 * t ** 4 + 0.0000121272 * t ** 5
+            - 0.0000001699 * t ** 6 + 0.000000000875 * t ** 7);
+    }
+    if (year >= 1700 && year < 1800) {
+        t = year - 1700;
+        return 8.83 + 0.1603 * t - 0.0059285 * t * t + 0.00013336 * t ** 3 - (t ** 4) / 1174000;
+    }
+    if (year >= 2050 && year < 2150) {
+        return -20 + 32 * ((year - 1820) / 100) ** 2 - 0.5628 * (2150 - year);
+    }
+    const u = (year - 1820) / 100;
+    return -20 + 32 * u * u;
+}
+/**
+ * JDN of 1 Vendémiaire — the civil day (Paris meridian) hosting the September
+ * equinox of the given Gregorian year.
+ *
+ * @param gregorianYear - The Gregorian year whose equinox opens the Republican year.
+ * @returns The Julian Day Number of that year's 1 Vendémiaire.
+ */
+export function republicanYearStartJdn(gregorianYear) {
+    const jde = septemberEquinoxJde(gregorianYear); // TD
+    const ut = jde - deltaTSeconds(gregorianYear) / 86400;
+    const parisMeanTime = ut + PARIS_MERIDIAN_OFFSET_DAYS;
+    return Math.floor(parisMeanTime + 0.5);
+}
+// --- Roman numerals (years were written in Roman numerals: "an VIII") --------
+/**
+ * Formats a positive integer as a Roman numeral. Non-positive inputs are
+ * returned as their decimal string.
+ *
+ * @param n - The number to format.
+ * @returns The Roman numeral (e.g. `8` -> `'VIII'`).
+ */
+export function toRoman(n) {
+    if (n <= 0)
+        return String(n);
+    const table = [
+        [1000, 'M'], [900, 'CM'], [500, 'D'], [400, 'CD'],
+        [100, 'C'], [90, 'XC'], [50, 'L'], [40, 'XL'],
+        [10, 'X'], [9, 'IX'], [5, 'V'], [4, 'IV'], [1, 'I']
+    ];
+    let remaining = n;
+    let result = '';
+    for (const [value, symbol] of table) {
+        while (remaining >= value) {
+            result += symbol;
+            remaining -= value;
+        }
+    }
+    return result;
+}

package/agnostic/time/duration/index.js

@@ -41,6 +41,7 @@ export class Duration {
         else if (type === 'mo' || type === 'mth' || type === 'months') {
             this.type = 'months';
         }
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
         else if (type === 'y' || type === 'years') {
             this.type = 'years';
         }
@@ -64,6 +65,7 @@ export class Duration {
             return this.value * 1000 * 60 * 60 * 24 * 7;
         if (this.type === 'months')
             return this.value * 1000 * 60 * 60 * 24 * 30;
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
         if (this.type === 'years')
             return this.value * 1000 * 60 * 60 * 24 * 365;
         return this.value; // defaults to milliseconds

package/agnostic/time/index.d.ts

@@ -1,5 +1,5 @@
 export * as dates from './dates/index.js'
 export * as duration from './duration/index.js'
-export * as wait from './wait/index.js'
-export * as transitions from './transitions/index.js'
 export * as timeout from './timeout/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 dates from './dates/index.js'
 export * as duration from './duration/index.js'
-export * as wait from './wait/index.js'
-export * as transitions from './transitions/index.js'
 export * as timeout from './timeout/index.js'
+export * as transitions from './transitions/index.js'
+export * as wait from './wait/index.js'

package/agnostic/time/timeout/index.js

@@ -8,18 +8,18 @@
  */
 export async function timeout(timeoutMs, callback) {
     let hasRejected = false;
-    // eslint-disable-next-line @typescript-eslint/no-misused-promises, no-async-promise-executor
-    return await new Promise(async (resolve, reject) => {
+    return await new Promise((resolve, reject) => {
         const rejectTimeout = setTimeout(() => {
-            // eslint-disable-next-line prefer-promise-reject-errors
+            // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors
             reject(false);
             hasRejected = true;
         }, timeoutMs);
-        // eslint-disable-next-line @typescript-eslint/await-thenable
-        const callbackResult = await callback();
-        if (hasRejected)
-            return;
-        clearTimeout(rejectTimeout);
-        return resolve(callbackResult);
+        void (async () => {
+            const callbackResult = await callback();
+            if (hasRejected)
+                return;
+            clearTimeout(rejectTimeout);
+            resolve(callbackResult);
+        })();
     });
 }

package/agnostic/time/transitions/index.js

@@ -89,13 +89,14 @@ const c5 = (2 * PI) / 4.5;
 const bounceOut = function (x) {
     const n1 = 7.5625;
     const d1 = 2.75;
-    if (x < 1 / d1)
-        return n1 * x * x;
-    if (x < 2 / d1)
-        return n1 * (x -= 1.5 / d1) * x + 0.75;
-    if (x < 2.5 / d1)
-        return n1 * (x -= 2.25 / d1) * x + 0.9375;
-    return n1 * (x -= 2.625 / d1) * x + 0.984375;
+    let t = x;
+    if (t < 1 / d1)
+        return n1 * t * t;
+    if (t < 2 / d1)
+        return n1 * (t -= 1.5 / d1) * t + 0.75;
+    if (t < 2.5 / d1)
+        return n1 * (t -= 2.25 / d1) * t + 0.9375;
+    return n1 * (t -= 2.625 / d1) * t + 0.984375;
 };
 /**
  * Predefined easing functions used internally by transitions.

package/components/BeforeAfter/index.controlled.js

@@ -32,6 +32,7 @@ import cssModule from './styles.module.css';
  * @returns A split-panel container with pointer interaction handlers and ratio state applied.
  */
 export const BeforeAfterControlled = ({ mode = 'horizontal', ratio = 0, before, after, className, children, actionHandlers }) => {
+    // eslint-disable-next-line no-param-reassign
     ratio = clamp(ratio, 0, 1);
     // State & refs
     const rootRef = useRef(null);

package/components/BeforeAfter/index.js

@@ -26,7 +26,9 @@ export const BeforeAfter = ({ mode = 'horizontal', actionHandlers, stateHandlers
     const isControlled = ratio !== undefined;
     const effectiveRatio = isControlled ? ratio : internalRatio;
     const handleDrag = (x, y) => {
+        // eslint-disable-next-line no-param-reassign
         x = 1.02 * x - 0.01;
+        // eslint-disable-next-line no-param-reassign
         y = 1.02 * y - 0.01;
         actionHandlers?.dragged?.(x, y);
         if (!isControlled) {
@@ -35,7 +37,9 @@ export const BeforeAfter = ({ mode = 'horizontal', actionHandlers, stateHandlers
         }
     };
     const handleClick = (x, y) => {
+        // eslint-disable-next-line no-param-reassign
         x = 1.02 * x - 0.01;
+        // eslint-disable-next-line no-param-reassign
         y = 1.02 * y - 0.01;
         actionHandlers?.clicked?.(x, y);
         if (!isControlled) {

package/components/Button/index.d.ts

@@ -1,4 +1,4 @@
-import { type FunctionComponent, type ButtonHTMLAttributes, type ReactNode } from 'react';
+import type { FunctionComponent, ButtonHTMLAttributes } from 'react';
 import type { WithClassName } from '../utils/types.js';
 /**
  * Props for the {@link Button} component.
@@ -6,14 +6,9 @@ import type { WithClassName } from '../utils/types.js';
  * Extends all native {@link ButtonHTMLAttributes} and {@link WithClassName}
  * with optional label and error content.
  *
- * @property label - Content rendered as the button label.
- * @property error - Content rendered to convey an error state associated with the button.
  * @property className - Additional class name(s) applied to the root element.
  */
-export type Props = ButtonHTMLAttributes<HTMLButtonElement> & WithClassName<{
-    label?: ReactNode;
-    error?: ReactNode;
-}>;
+export type Props = ButtonHTMLAttributes<HTMLButtonElement> & WithClassName<Record<string, unknown>>;
 /**
  * Base button component.
  *

package/components/Button/index.js

@@ -13,8 +13,8 @@ import cssModule from './styles.module.css';
  * @see {@link Props}
  * @returns A styled native button element.
  */
-export const Button = ({ label, error, className, ...rest }) => {
+export const Button = ({ className, ...rest }) => {
     const c = clss(publicClassName, { cssModule });
     const rootClss = mergeClassNames(c(null), className);
-    return _jsx("button", { ...rest, className: c(rootClss) });
+    return _jsx("button", { ...rest, className: rootClss });
 };

package/components/Clippable/index.js

@@ -51,6 +51,7 @@ export const Clippable = ({ className, children, toClip, actionHandlers, stateHa
             ]);
         }
         catch (err) {
+            // eslint-disable-next-line no-console
             console.error(err);
         }
         stateHandlers?.clipped?.(html);

package/components/Drawer/index.js

@@ -49,7 +49,7 @@ export const Drawer = ({ openerContent, closerContent, initialIsOpened = false,
         setInternalIsOpened(false);
     };
     const handleROCompResize = ({ entry }) => {
-        const { width, height } = entry?.contentRect ?? {};
+        const { width, height } = entry.contentRect;
         setContentDimensions({ width, height });
     };
     // Rendering

package/components/Gallery/index.js

@@ -56,6 +56,7 @@ export const Gallery = ({ paddingLeft, paddingRight, padding, prevButtonContent,
             animationFrame = null;
             const { scrollLeft, clientWidth, scrollWidth } = scrollerElt;
             const center = scrollLeft + clientWidth / 2;
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- scrollerElt.children (HTMLCollection) always contains Element/HTMLElement nodes
             const children = Array.from(scrollerElt.children);
             let closestIndex = 0;
             let closestDistance = Infinity;
@@ -138,7 +139,7 @@ export const Gallery = ({ paddingLeft, paddingRight, padding, prevButtonContent,
                             ? actualPaddingRight
                             : undefined
                     };
-                    return _jsx("div", { className: `${slotClss}`, style: { ...style }, "data-slot": pos, children: child }, pos);
+                    return _jsx("div", { className: slotClss, style: { ...style }, "data-slot": pos, children: child }, pos);
                 }) }), _jsxs("div", { className: actionsClss, children: [_jsx("div", { className: prevBtnClss, onClick: handlePrevClick, children: prevButtonContent ?? 'prev' }), _jsx("div", { className: nextBtnClss, onClick: handleNextClick, children: nextButtonContent ?? 'next' })] }), _jsx("div", { className: paginationClss, children: Children.map(children, (_, pos) => {
                     const pageClss = c('page', { active: pos === activeIndex });
                     return _jsx("div", { className: pageClss, "data-page": pos, onClick: () => handlePaginationClick(pos), children: typeof paginationContent === 'string'

package/components/Gallery/utils.js

@@ -1,6 +1,7 @@
 export const forceActivateSlot = (div, targetPos, smooth = true) => {
     if (div === null)
         return;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- div.children (HTMLCollection) always contains Element/HTMLElement nodes
     const children = Array.from(div.children);
     if (children[targetPos] === undefined)
         return;
@@ -8,5 +9,8 @@ export const forceActivateSlot = (div, targetPos, smooth = true) => {
     const halfClientWidth = div.clientWidth / 2;
     const halfOffsetWidth = div.offsetWidth / 2;
     const offset = target.offsetLeft - (halfClientWidth - halfOffsetWidth);
-    div.scrollTo({ left: offset, behavior: smooth ? 'smooth' : 'instant' });
+    div.scrollTo({
+        left: offset,
+        behavior: smooth ? 'smooth' : 'instant'
+    });
 };

package/components/Iframe/index.d.ts

@@ -1,48 +1,30 @@
-import { type FunctionComponent, type IframeHTMLAttributes, type PropsWithChildren } from 'react';
+import { type FunctionComponent, type IframeHTMLAttributes } from 'react';
 import type { WithClassName } from '../utils/types.js';
 /**
  * Props for the {@link Iframe} component.
  *
- * Extends native {@link IframeHTMLAttributes} with optional class name support.
+ * Extends native {@link IframeHTMLAttributes} with class name support and
+ * automatic height adjustment.
  *
- * @property className - Additional class name(s) applied to the root element.
- * @property children - React content rendered as the iframe document body.
- * @property srcDoc - Raw HTML string used as iframe content when `children` is not provided.
- *
- * @remarks
- * This component behaves as a hybrid between a native `<iframe>` and a React renderer.
- *
- * Rendering priority:
- * - `children` takes precedence over `srcDoc` when provided.
- * - If `children` is `null` or `undefined`, `srcDoc` is used directly.
- *
- * When `children` is provided, it is converted to static HTML using
- * `renderToStaticMarkup` and injected into a complete HTML document:
- * `<!doctype html><html><body>...</body></html>`.
+ * @property autoHeight - Enables automatic iframe height adjustment based on
+ * document content size. Only supported with `srcDoc`.
+ * @property className - Optional additional class names applied to the iframe.
+ * @property style - Optional inline style applied to the iframe.
+ * @property srcDoc - Raw HTML string rendered inside the iframe.
  */
-export type Props = PropsWithChildren<WithClassName<Record<never, never>>> & Omit<IframeHTMLAttributes<HTMLIFrameElement>, 'children'>;
+export type Props = WithClassName<{
+    autoHeight?: boolean;
+}> & Omit<IframeHTMLAttributes<HTMLIFrameElement>, 'children'>;
 /**
- * Iframe component with React-to-HTML rendering support.
- *
- * Renders either:
- * - A raw HTML string via the `srcDoc` attribute, or
- * - A ReactNode rendered into static HTML via `renderToStaticMarkup`.
- *
- * ### Rendering strategy
- * 1. If `children` is defined (non-nullish), it is rendered to static HTML
- *    and used as iframe content.
- * 2. Otherwise, `srcDoc` is used as-is.
+ * Iframe component with optional automatic height adjustment.
  *
- * The resulting content is wrapped in a minimal HTML document:
- * `<!doctype html><html><body>...</body></html>`.
+ * When `autoHeight` is enabled, the iframe injects a script that measures
+ * document height and sends updates to the parent via `postMessage`.
  *
- * ### Notes
- * - The iframe content is static (no hydration, no client-side React inside iframe).
- * - `children` overrides `srcDoc`.
- * - Useful for embedding server-rendered UI fragments or documentation blocks.
+ * The parent component updates the iframe height via React state and `style`
+ * prop (no direct DOM mutation).
  *
  * @param props - Component properties.
  * @see {@link Props}
- * @returns A styled iframe element with computed HTML document content.
  */
 export declare const Iframe: FunctionComponent<Props>;

package/components/Iframe/index.js

@@ -1,43 +1,86 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useMemo } from 'react';
-import { renderToStaticMarkup } from 'react-dom/server';
+import { useEffect, useMemo, useRef, useState } from 'react';
 import { clss } from '../../agnostic/css/clss/index.js';
+import { randomHash } from '../../agnostic/random/uuid/index.js';
 import { mergeClassNames } from '../utils/index.js';
 import { iframe as publicClassName } from '../public-classnames.js';
 import cssModule from './styles.module.css';
-import { isNotNullish } from '../../agnostic/misc/is-nullish/index.js';
+const innerAutoHeightNitifier = (messageType) => `<script>
+  (() => {
+    const notify = () => {
+      const height = Math.max(
+        document.body?.scrollHeight ?? 0,
+        document.documentElement?.scrollHeight ?? 0
+      )
+      window.parent.postMessage({
+        type: '${messageType}',
+        height
+      }, '*')
+    }
+    window.addEventListener('load', notify)
+    const observer = new ResizeObserver(notify)
+    observer.observe(document.body)
+    observer.observe(document.documentElement)
+    notify()
+  })()
+</script>`;
 /**
- * Iframe component with React-to-HTML rendering support.
+ * Iframe component with optional automatic height adjustment.
  *
- * Renders either:
- * - A raw HTML string via the `srcDoc` attribute, or
- * - A ReactNode rendered into static HTML via `renderToStaticMarkup`.
+ * When `autoHeight` is enabled, the iframe injects a script that measures
+ * document height and sends updates to the parent via `postMessage`.
  *
- * ### Rendering strategy
- * 1. If `children` is defined (non-nullish), it is rendered to static HTML
- *    and used as iframe content.
- * 2. Otherwise, `srcDoc` is used as-is.
- *
- * The resulting content is wrapped in a minimal HTML document:
- * `<!doctype html><html><body>...</body></html>`.
- *
- * ### Notes
- * - The iframe content is static (no hydration, no client-side React inside iframe).
- * - `children` overrides `srcDoc`.
- * - Useful for embedding server-rendered UI fragments or documentation blocks.
+ * The parent component updates the iframe height via React state and `style`
+ * prop (no direct DOM mutation).
  *
  * @param props - Component properties.
  * @see {@link Props}
- * @returns A styled iframe element with computed HTML document content.
  */
-export const Iframe = ({ className, children, srcDoc, ...iframeProps }) => {
+export const Iframe = ({ autoHeight = false, className, srcDoc, style, ...iframeProps }) => {
+    const iframeRef = useRef(null);
+    const [height, setHeight] = useState(null);
+    const [innerMessageType] = useState(`_${randomHash(10)}`);
+    // Fx. dep. `autoHeight` - Handles messages from iframe content when autoHeight is enabled.
+    useEffect(() => {
+        if (!autoHeight)
+            return;
+        const handleMessage = (event) => {
+            const iframe = iframeRef.current;
+            if (iframe === null
+                || event.source !== iframe.contentWindow
+                || typeof event.data !== 'object'
+                || event.data === null
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+                || event.data.type !== innerMessageType
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+                || typeof event.data.height !== 'number')
+                return;
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-type-assertion -- event.data.height was already checked to be a number above; event.data is typed any by MessageEvent
+            setHeight(event.data.height);
+        };
+        window.addEventListener('message', handleMessage);
+        return () => window.removeEventListener('message', handleMessage);
+    }, [autoHeight]);
+    const iframeStyle = useMemo(() => {
+        const base = style ?? {};
+        if (!autoHeight || height === null)
+            return base;
+        return { ...base, height: `${height}px` };
+    }, [style, autoHeight, height]);
     const c = clss(publicClassName, { cssModule });
     const rootClss = mergeClassNames(c(), className);
     const html = useMemo(() => {
-        const body = isNotNullish(children)
-            ? renderToStaticMarkup(children)
-            : srcDoc;
-        return `<!doctype html><html><body>${body}</body></html>`;
-    }, [children, srcDoc]);
-    return _jsx("iframe", { ...iframeProps, className: rootClss, srcDoc: html });
+        const autoHeightScript = autoHeight
+            ? innerAutoHeightNitifier(innerMessageType)
+            : '';
+        return `<!doctype html>
+      <html>
+        <body>
+          ${srcDoc ?? ''}
+          ${autoHeightScript}
+        </body>
+      </html>
+    `;
+    }, [srcDoc, autoHeight]);
+    return _jsx("iframe", { ...iframeProps, ref: iframeRef, className: rootClss, style: iframeStyle, srcDoc: html });
 };

package/components/Image/index.js

@@ -40,8 +40,10 @@ export const Image = ({ sources, disclaimer, theatre, className, ...intrinsicImg
         if (Array.isArray(sources)) {
             if (sources.length === 0)
                 return [];
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- first element sampled just above; array is expected to be homogeneous
             if (typeof sources[0] === 'string')
                 return sources.map(srcSet => ({ srcSet }));
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- first element was checked not to be a string just above; array is expected to be homogeneous
             return sources;
         }
         return [];

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

@@ -0,0 +1,42 @@
+import { type FunctionComponent, type InputHTMLAttributes, type ReactNode } from 'react';
+import type { WithClassName } from '../utils/types.js';
+/**
+ * Props for the {@link Input} component.
+ *
+ * Extends all native {@link InputHTMLAttributes} and {@link WithClassName}
+ * with optional label and error content.
+ *
+ * @property label - Content rendered as an associated `<label>`. When omitted, no label is rendered.
+ * @property error - Content rendered as an error message below the input. When omitted, no error is rendered.
+ * @property className - Additional class name(s) applied to the root element.
+ */
+export type Props = InputHTMLAttributes<HTMLInputElement> & WithClassName<{
+    label?: ReactNode;
+    error?: ReactNode;
+}>;
+/**
+ * Controlled input field component.
+ *
+ * Renders a native `<input>` element with optional label and error feedback.
+ * The input value is entirely driven by the provided `value` prop and all
+ * native input attributes are forwarded to the underlying element.
+ *
+ * A stable auto-generated `id` is created on mount and used to associate the
+ * rendered label through the `htmlFor` attribute.
+ *
+ * ### CSS elements
+ * - `label`
+ * - `error`
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ *
+ * @returns A labelled controlled input with optional error feedback.
+ *
+ * @remarks
+ * - The component does not manage its own value state.
+ * - Consumers are responsible for updating `value` in response to `onChange`.
+ * - Additional `className` values are merged with the component public class name
+ *   and applied to the underlying `<input>` element.
+ */
+export declare const ControlledInput: FunctionComponent<Props>;

package/components/Input/index.controlled.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { clss } from '../../agnostic/css/clss/index.js';
+import { isNotFalsy } from '../../agnostic/booleans/is-falsy/index.js';
+import { randomHash } from '../../agnostic/random/uuid/index.js';
+import { input as publicClassName } from '../public-classnames.js';
+import { mergeClassNames } from '../utils/index.js';
+import cssModule from './styles.module.css';
+/**
+ * Controlled input field component.
+ *
+ * Renders a native `<input>` element with optional label and error feedback.
+ * The input value is entirely driven by the provided `value` prop and all
+ * native input attributes are forwarded to the underlying element.
+ *
+ * A stable auto-generated `id` is created on mount and used to associate the
+ * rendered label through the `htmlFor` attribute.
+ *
+ * ### CSS elements
+ * - `label`
+ * - `error`
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ *
+ * @returns A labelled controlled input with optional error feedback.
+ *
+ * @remarks
+ * - The component does not manage its own value state.
+ * - Consumers are responsible for updating `value` in response to `onChange`.
+ * - Additional `className` values are merged with the component public class name
+ *   and applied to the underlying `<input>` element.
+ */
+export const ControlledInput = ({ label, error, value, className, ...rest }) => {
+    const [id] = useState(`_${randomHash(12)}`);
+    const c = clss(publicClassName, { cssModule });
+    const rootClss = mergeClassNames(c(null), className);
+    return _jsxs(_Fragment, { children: [isNotFalsy(label) && _jsx("label", { className: c('label'), htmlFor: id, children: label }), _jsx("input", { ...rest, id: id, className: rootClss, value: value ?? '', onChange: e => {
+                    const { target } = e;
+                    rest.onChange?.(e);
+                    if (value === undefined)
+                        return;
+                    if (typeof value === 'number') {
+                        target.value = `${value}`;
+                    }
+                    else if (typeof value === 'string') {
+                        target.value = value;
+                    }
+                    else {
+                        // value is readonly string[]
+                        // not supported for <input>; ignore or normalize if needed
+                    }
+                } }), isNotFalsy(error) && _jsx("span", { className: c('error'), children: error })] });
+};