@ssa-ui-kit/utils 3.21.3 → 3.22.0

package/dist/ai/source-map.md

@@ -0,0 +1,41 @@
+# @ssa-ui-kit/utils — AI source map
+
+Generated from the TypeScript program at build time — do not edit by hand.
+
+**Everything below is imported from the package root:** `import { X } from '@ssa-ui-kit/utils'`
+
+13 functions · 1 class · 4 exported types
+
+## Reading this file
+
+- This is an index, not a reference. For full documentation and usage examples, read the matching `.d.ts` in `dist/`.
+
+## Utility namespaces
+
+- `dateFormatters` — formatTime, formatDayOfWeek, formatDate, printDayOfTheWeek, getTimeAgo
+
+## Functions
+
+- `assocPath` — Returns a copy of an object with a nested value replaced.
+- `callAll` — Combines several handlers into one that calls each with the same arguments.
+- `debounce` — Delays a call until the input stops arriving.
+- `dissocPath` — Returns a copy of an object with the key at a nested path removed.
+- `generateRange` — Builds the list of page numbers a paginator should display.
+- `isNill` — Checks whether a value is `null` or `undefined`.
+- `mapObjIndexed` — Maps over an object's values, keeping its keys.
+- `path` — Reads a nested value by key path.
+- `pathOr` — Reads a nested value by key path, falling back to a default when missing.
+- `prop` — Reads one own property from an object.
+- `propOr` — Reads one own property, falling back to a default when it is missing.
+- `seededRandom` — A deterministic stand-in for `Math.random`, for generating fixture data.
+- `throttle` — Rate-limits a function to at most one call per interval.
+
+## Classes
+
+- `ClassnameArray` — A `string[]` with chainable helpers for building a class list.
+
+## Exported types
+
+_Names only — read the `.d.ts` for their shape._
+
+`Has` · `MustInclude` · `PathObject` · `PathValue`

package/dist/index.js

@@ -79,6 +79,21 @@ __webpack_require__.d(dateFormatters_namespaceObject, {
 
 ;// ./src/utils/CallAll.ts
 /* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Combines several handlers into one that calls each with the same arguments.
+ *
+ * Nullish entries are skipped, so an optional prop can be passed straight
+ * through without a guard — the usual case is merging a component's own handler
+ * with one a consumer supplied.
+ *
+ * Handlers run in order and their return values are discarded. Because they all
+ * receive the same event object, one calling `stopPropagation` affects the
+ * others' view of it, but it does not stop later handlers from running.
+ *
+ * @example
+ * // `props.onClick` may be undefined — callAll skips it
+ * <button onClick={callAll(closeMenu, props.onClick)}>Close</button>
+ */
 const callAll = (...fns) => (...args) => fns.forEach(fn => fn?.(...args));
 /* eslint-enable @typescript-eslint/no-explicit-any */
 ;// ./src/utils/isNill.ts
@@ -96,6 +111,33 @@ const callAll = (...fns) => (...args) => fns.forEach(fn => fn?.(...args));
  */
 const isNill = value => value === null || value === undefined;
 ;// ./src/utils/throttle/throttle.ts
+/**
+ * Rate-limits a function to at most one call per interval.
+ *
+ * ### Returns a `[throttled, cancel]` tuple
+ * Not a callable function with a `.cancel()` method as in lodash — destructure
+ * it: `const [onScroll, cancelScroll] = throttle(fn, 100)`.
+ *
+ * Leading **and** trailing: the first call runs immediately, calls during the
+ * cooling-off window are dropped except the last, and that one runs when the
+ * window closes. So a burst produces a call at the start and a call at the end,
+ * never a silent gap — unlike `debounce`, which only fires at the end.
+ *
+ * Call `cancel` on unmount to clear a pending trailing invocation.
+ *
+ * @param delayMs - Minimum gap between invocations, in ms.
+ *
+ * @example
+ * const [onScroll, cancel] = throttle(() => setOffset(window.scrollY), 100);
+ *
+ * useEffect(() => {
+ *   window.addEventListener('scroll', onScroll);
+ *   return () => {
+ *     window.removeEventListener('scroll', onScroll);
+ *     cancel();
+ *   };
+ * }, [onScroll, cancel]);
+ */
 const throttle = (fn, delayMs) => {
   let isThrottled = false;
   let savedArgs = null;
@@ -124,6 +166,29 @@ const throttle = (fn, delayMs) => {
   }];
 };
 ;// ./src/utils/debounce/debounce.ts
+/**
+ * Delays a call until the input stops arriving.
+ *
+ * ### Returns a `[debounced, cancel]` tuple
+ * Not a callable function with a `.cancel()` method as in lodash — destructure
+ * it: `const [search, cancelSearch] = debounce(fn, 300)`. Calling the returned
+ * value directly is a type error, because it is an array.
+ *
+ * Trailing edge only: nothing runs until `wait` ms have passed with no further
+ * calls, and only the most recent arguments are used. For a call that fires
+ * immediately and then rate-limits, use `throttle`.
+ *
+ * Call `cancel` on unmount so a pending invocation cannot fire against a
+ * component that is gone.
+ *
+ * @param wait - Quiet period in ms before the call goes through. @default 200
+ *
+ * @example
+ * const [search, cancel] = debounce((term: string) => void fetchResults(term), 300);
+ *
+ * useEffect(() => cancel, [cancel]);
+ * <Input onChange={(e) => search(e.target.value)} />
+ */
 const debounce = (func, wait = 200) => {
   let timeoutId = null;
   const executedFunction = (...args) => {
@@ -157,15 +222,64 @@ const periodValues = {
   hour: 3600,
   min: 60
 };
+
+/**
+ * Formats a timestamp as a zero-padded 12-hour clock time, e.g. `"09:05 AM"`.
+ *
+ * Locale is hard-coded to `en-US`, so output does not follow the user's locale.
+ * The **time zone is not** — it uses the runtime's, so a server and a browser
+ * can render the same timestamp differently.
+ *
+ * @param timestampMs - Milliseconds since the epoch, as `Date.now()` returns.
+ *
+ * @example
+ * dateFormatters.formatTime(1735732800000); // '09:20 AM'
+ */
 const formatTime = timestampMs => new Date(timestampMs).toLocaleTimeString('en-US', {
   hour: '2-digit',
   minute: '2-digit'
 });
+
+/**
+ * Returns the three-letter English weekday for a timestamp, e.g. `"Mon"`.
+ *
+ * Uses the runtime's time zone, so a timestamp near midnight can resolve to a
+ * different day than the user expects.
+ *
+ * @param timestampMs - Milliseconds since the epoch.
+ *
+ * @example
+ * dateFormatters.formatDayOfWeek(Date.now()); // 'Thu'
+ */
 const formatDayOfWeek = timestampMs => dayOfWeekNames[new Date(timestampMs).getDay()];
+
+/**
+ * Formats a timestamp as day and abbreviated month, e.g. `"05 Jan"` — no year.
+ *
+ * Locale is hard-coded to `en-US`. Since the year is omitted, do not use it
+ * where dates span more than one year without adding the year yourself.
+ *
+ * @param timestampMs - Milliseconds since the epoch.
+ *
+ * @example
+ * dateFormatters.formatDate(1735732800000); // '01 Jan'
+ */
 const formatDate = timestampMs => new Date(timestampMs).toLocaleDateString('en-US', {
   day: '2-digit',
   month: 'short'
 });
+
+/**
+ * Maps a weekday index to its three-letter English name.
+ *
+ * Takes a **day index** (0 = Sunday … 6 = Saturday), not a timestamp — for a
+ * timestamp use `formatDayOfWeek`. Anything outside 0–6 returns `undefined`,
+ * so the return type is `string | undefined`.
+ *
+ * @example
+ * dateFormatters.printDayOfTheWeek(0); // 'Sun'
+ * dateFormatters.printDayOfTheWeek(9); // undefined
+ */
 const printDayOfTheWeek = day => {
   switch (day) {
     case 0:
@@ -184,6 +298,25 @@ const printDayOfTheWeek = day => {
       return 'Sat';
   }
 };
+
+/**
+ * Renders how long ago a date was, e.g. `"3 days ago"`, `"1 hour ago"`.
+ *
+ * Falls back to `"Just Now"` for anything under a minute. Granularity stops at
+ * years, and months are approximated as 30 days, so long gaps drift from the
+ * calendar.
+ *
+ * Throws `Error('Invalid date')` when the value cannot be parsed — including
+ * date strings the runtime does not recognise, so prefer passing a timestamp.
+ * The result is computed against `Date.now()` at call time and does not update
+ * on its own; re-render on a timer if it needs to stay current.
+ *
+ * @param timeValue - Timestamp in ms, or any string `new Date()` accepts.
+ *
+ * @example
+ * dateFormatters.getTimeAgo(Date.now() - 3 * 86400 * 1000); // '3 days ago'
+ * dateFormatters.getTimeAgo(Date.now() - 5000); // 'Just Now'
+ */
 const getTimeAgo = timeValue => {
   const date = new Date(timeValue).getTime();
   if (Number.isNaN(date)) {
@@ -201,6 +334,25 @@ const getTimeAgo = timeValue => {
   return 'Just Now';
 };
 ;// ./src/utils/objects/mapObjIndexed.ts
+/**
+ * Maps over an object's values, keeping its keys.
+ *
+ * ### Not curried, unlike the accessors in this package
+ * `prop`, `path`, `propOr` and `assocPath` all take their arguments one group
+ * at a time; this one takes both at once — `mapObjIndexed(fn, obj)`. Ramda's
+ * version is curried, so a habit carried over from there will not compile here.
+ *
+ * The callback receives `(value, key, obj)`, mirroring `Array.prototype.map`.
+ * Only own enumerable keys are visited, and a new object is returned.
+ *
+ * @example
+ * mapObjIndexed((value) => value * 2, { a: 1, b: 2 }); // { a: 2, b: 4 }
+ *
+ * @example
+ * // The key is available as the second argument
+ * mapObjIndexed((value, key) => `${key}=${value}`, { page: 2, size: 20 });
+ * // { page: 'page=2', size: 'size=20' }
+ */
 const mapObjIndexed = (fn, obj) => {
   return Object.keys(obj).reduce((result, key) => {
     result[key] = fn(obj[key], key, obj);
@@ -209,16 +361,6 @@ const mapObjIndexed = (fn, obj) => {
 };
 ;// ./src/utils/pagination/generateRange.ts
 
-/**
- * The function that returns an array of page numbers to show in the pagination
- * component.
- *
- * Rules:
- * - To always show the 1st and the last page.
- * - To show one item before and one item after the selected page.
- * - To return "-1" for the skipped items. This is to be able to display "..." in
- * the pagination component.
- * */
 const SKIPPED_ITEMS_DELTA = 2;
 const getSelectedRange = (pagesCount, selectedPage) => {
   const range = [];
@@ -238,6 +380,34 @@ const fill = (range, minValue, maxValue) => {
     range.push(i);
   }
 };
+
+/**
+ * Builds the list of page numbers a paginator should display.
+ *
+ * Always includes the first and last page, plus one page either side of the
+ * selection, and collapses the rest.
+ *
+ * ### `-1` marks a gap, it is not a page
+ * Skipped stretches are represented by `-1`, which the caller renders as an
+ * ellipsis. Render the array directly and a `-1` button appears — check for it:
+ * `range.map((page) => (page === -1 ? <Ellipsis /> : <PageButton page={page} />))`.
+ *
+ * ### It throws on bad input rather than clamping
+ * A non-integer `pagesCount` or `selectedPage`, or a selection outside
+ * `1…pagesCount`, raises an `Error`. Only `pagesCount <= 0` is tolerated,
+ * returning `[]`. Note pages are **1-based**, so `selectedPage: 0` throws.
+ *
+ * @param pagesCount - Total pages. `<= 0` yields an empty array.
+ * @param selectedPage - Current page, 1-based. Omit for the unselected layout.
+ *
+ * @example
+ * generateRange(5); // [1, 2, 3, 4, 5] — short enough to show in full
+ * generateRange(10); // [1, 2, 3, -1, 10]
+ *
+ * @example
+ * generateRange(10, 5); // [1, -1, 4, 5, 6, -1, 10] — gaps on both sides
+ * generateRange(10, 10); // [1, -1, 9, 10]
+ */
 const generateRange = (pagesCount, selectedPage) => {
   if (isNill(pagesCount) || !Number.isInteger(pagesCount)) {
     throw new Error('Pages count should be an integer');
@@ -279,11 +449,65 @@ const generateRange = (pagesCount, selectedPage) => {
 };
 /* harmony default export */ const pagination_generateRange = (generateRange);
 ;// ./src/utils/objects/assocPath.ts
+/**
+ * Returns a copy of an object with a nested value replaced.
+ *
+ * **Curried, and only curried**: `assocPath(keys, value)(obj)`. The path is an
+ * array of keys; intermediate objects are created as needed. The input is never
+ * mutated.
+ *
+ * ### It deep-clones through JSON, which is lossy
+ * The copy is produced with `JSON.parse(JSON.stringify(...))`, so any value the
+ * JSON round-trip cannot represent is altered — silently, and with no type
+ * error, because the signature still claims `T`:
+ *
+ * - `Date` becomes an ISO **string**
+ * - `Map`, `Set` and class instances become `{}` (prototypes are lost)
+ * - keys whose value is `undefined` are **dropped**
+ * - `NaN` and `Infinity` become `null`
+ * - functions are dropped
+ *
+ * Safe for plain JSON-shaped state; for anything richer, spread the update by
+ * hand or use a structural-sharing helper.
+ *
+ * @example
+ * assocPath(['user', 'name'], 'Ada')({ user: { name: 'Grace', id: 1 } });
+ * // { user: { name: 'Ada', id: 1 } }
+ *
+ * @example
+ * // Lossy: `when` comes back as a string, not a Date
+ * assocPath(['id'], 2)({ id: 1, when: new Date() });
+ * // { id: 2, when: '2020-01-01T00:00:00.000Z' }
+ */
 const assocPath = ([first, ...rest], value) => sourceObject => JSON.parse(JSON.stringify({
   ...sourceObject,
   [first]: rest.length ? assocPath(rest, value)(sourceObject[first]) : value
 }));
 ;// ./src/utils/objects/dissocPath.ts
+/**
+ * Returns a copy of an object with the key at a nested path removed.
+ *
+ * **Curried, and only curried**: `dissocPath(keys)(obj)`. The path is an array
+ * of keys. The input is never mutated.
+ *
+ * ### Missing intermediate keys throw
+ * Only the final key is optional. If a key *along the way* is absent the walk
+ * dereferences `undefined` and raises a `TypeError`, so guard paths that may
+ * not exist. Removing an already-absent leaf is a harmless no-op.
+ *
+ * ### It deep-clones through JSON, which is lossy
+ * Same caveat as `assocPath`: `Date` becomes a string, `Map`/`Set`/class
+ * instances become `{}`, `undefined` values are dropped, and `NaN`/`Infinity`
+ * become `null`. Use it on plain JSON-shaped state.
+ *
+ * @example
+ * dissocPath(['user', 'token'])({ user: { id: 1, token: 'x' } });
+ * // { user: { id: 1 } }
+ *
+ * @example
+ * dissocPath(['missing'])({ x: 1 }); // { x: 1 } — no-op
+ * dissocPath(['a', 'b'])({ x: 1 }); // TypeError: `a` does not exist
+ */
 const dissocPath = path => sourceObject => {
   const resultObject = JSON.parse(JSON.stringify(sourceObject));
   path.reduce((acc, key, index) => {
@@ -295,12 +519,48 @@ const dissocPath = path => sourceObject => {
   return resultObject;
 };
 ;// ./src/utils/objects/path.ts
+/**
+ * Reads a nested value by key path.
+ *
+ * **Curried, and only curried**: `path(keys)(obj)`. The path is an **array** of
+ * keys, not a dotted string — `path(['user', 'name'])`, never
+ * `path('user.name')`. Numeric keys index into arrays.
+ *
+ * Every step is optional-chained, so a missing key anywhere along the way
+ * yields `undefined` instead of throwing. The return type defaults to `unknown`,
+ * so annotate it when you need a narrower type.
+ *
+ * @example
+ * path(['user', 'name'])({ user: { name: 'Ada' } }); // 'Ada'
+ * path(['user', 'name'])({}); // undefined
+ *
+ * @example
+ * // Numeric keys walk into arrays
+ * path<Response, string>(['items', 0, 'label'])(response);
+ */
 const path_path = path => obj => path.reduce((prev, curr) => prev?.[curr], obj);
 ;// ./src/utils/objects/pathOr.ts
 
 
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Reads a nested value by key path, falling back to a default when missing.
+ *
+ * **Curried, and only curried**: `pathOr(fallback, keys)(obj)`. Default first,
+ * then an **array** of keys — not a dotted string, and not lodash's
+ * `get(obj, path, fallback)` order.
+ *
+ * ### Only `null` and `undefined` trigger the default
+ * As with `propOr`, the fallback applies to nullish values only. A nested `0`
+ * or `''` is returned unchanged. Because every step is optional-chained, a
+ * break anywhere along the path resolves to the default rather than throwing.
+ *
+ * @example
+ * pathOr('—', ['user', 'name'])({ user: { name: 'Ada' } }); // 'Ada'
+ * pathOr('—', ['user', 'name'])({}); // '—'
+ * pathOr('—', ['stats', 'total'])({ stats: { total: 0 } }); // 0, not '—'
+ */
 const pathOr = (defaultValue, path) => obj => {
   const result = path_path(path)(obj);
   return isNill(result) ? defaultValue : result;
@@ -308,12 +568,52 @@ const pathOr = (defaultValue, path) => obj => {
 /* eslint-enable @typescript-eslint/no-explicit-any */
 ;// ./src/utils/objects/prop.ts
 /* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Reads one own property from an object.
+ *
+ * **Curried, and only curried** — unlike Ramda's `prop`, this takes the key
+ * first and returns a reader. `prop('name', user)` is a type error; write
+ * `prop('name')(user)`. That shape is what makes it usable point-free, e.g. as
+ * `items.map(prop('id'))`.
+ *
+ * Reads a single key, not a dotted path: `prop('a.b')` looks for a literal
+ * `"a.b"` key. Use `path` for nested access. A nullish object yields
+ * `undefined` rather than throwing.
+ *
+ * @example
+ * prop('name')({ name: 'Ada' }); // 'Ada'
+ * prop('name')(undefined); // undefined
+ *
+ * @example
+ * // Point-free over a collection
+ * users.map(prop<User, string>('id'));
+ */
 const prop = propName => obj => obj?.[propName];
 ;// ./src/utils/objects/propOr.ts
 
 
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Reads one own property, falling back to a default when it is missing.
+ *
+ * **Curried, and only curried**: `propOr(fallback, key)(obj)`. The default
+ * comes first, matching Ramda's argument order — not lodash's
+ * `get(obj, key, fallback)`.
+ *
+ * ### Only `null` and `undefined` trigger the default
+ * The fallback applies when the value is nullish, **not** when it is merely
+ * falsy. `0`, `''` and `false` are returned as-is, so `propOr('—', 'count')`
+ * on `{ count: 0 }` gives `0`, not `'—'`. That is usually what you want for
+ * numbers; if you need empty strings to fall back too, check explicitly.
+ *
+ * Reads a single key, not a dotted path — use `pathOr` for nested access.
+ *
+ * @example
+ * propOr('—', 'name')({ name: 'Ada' }); // 'Ada'
+ * propOr('—', 'name')({}); // '—'
+ * propOr('—', 'count')({ count: 0 }); // 0, not '—'
+ */
 const propOr = (defaultValue, propName) => obj => {
   const result = prop(propName)(obj);
   return isNill(result) ? defaultValue : result;
@@ -328,7 +628,22 @@ const propOr = (defaultValue, propName) => obj => {
 
 
 ;// ./src/utils/story.ts
-// Useful for generating test datasets for storybook stories
+/**
+ * A deterministic stand-in for `Math.random`, for generating fixture data.
+ *
+ * Returns a generator function; calling it yields the next value in `[0, 1)`.
+ * The same seed always produces the same sequence, which is the point — chart
+ * and table stories keep identical data between renders, so visual diffs show
+ * real changes rather than new noise.
+ *
+ * Linear congruential, so it is fine for demo data and unfit for anything
+ * needing statistical quality or unpredictability.
+ *
+ * @example
+ * const random = seededRandom(42);
+ * const series = Array.from({ length: 30 }, () => Math.round(random() * 100));
+ * // identical on every run
+ */
 const seededRandom = seed => {
   return () => {
     // Linear congruential generator
@@ -337,6 +652,32 @@ const seededRandom = seed => {
   };
 };
 ;// ./src/utils/ClassnameArray/ClassnameArray.ts
+/**
+ * A `string[]` with chainable helpers for building a class list.
+ *
+ * ### It mutates, and it is a real Array
+ * `toggle` and `clear` change the instance in place and return `this`, so calls
+ * chain but the original is modified — do not share one instance across
+ * renders. Because it extends `Array`, `join(' ')` produces the final
+ * `className`, and every array method still works.
+ *
+ * Start from `new ClassnameArray()` and toggle onto it, or seed one with
+ * `ClassnameArray.from([...])`. Avoid `new ClassnameArray(n)` with a single
+ * number — the inherited `Array` constructor reads that as a length, giving you
+ * `n` empty slots.
+ *
+ * @example
+ * const classNames = new ClassnameArray();
+ * classNames
+ *   .toggle('day--selected', isSelected)
+ *   .toggle('day--disabled', isDisabled);
+ *
+ * <td className={classNames.join(' ')} />
+ *
+ * @example
+ * // Seeded with a base class
+ * ClassnameArray.from(['button']).toggle('button--active', isActive);
+ */
 class ClassnameArray extends Array {
   toggle(className, condition) {
     const index = this.indexOf(className);