@ssa-ui-kit/utils 3.21.2 → 3.22.0

package/dist/utils/pagination/generateRange.d.ts

@@ -1,3 +1,30 @@
 import { GenerateRangeFn } from './types';
+/**
+ * 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]
+ */
 declare const generateRange: GenerateRangeFn;
 export default generateRange;

package/dist/utils/pagination/types.d.ts

@@ -1 +1,7 @@
+/**
+ * Signature of `generateRange`.
+ *
+ * The returned array mixes page numbers with `-1` sentinels marking collapsed
+ * stretches, so it is not a plain list of pages.
+ */
 export type GenerateRangeFn = (pagesCount: number, selectedPage?: number) => Array<number>;

package/dist/utils/story.d.ts

@@ -1 +1,17 @@
+/**
+ * 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
+ */
 export declare const seededRandom: (seed: number) => () => number;

package/dist/utils/throttle/throttle.d.ts

@@ -1 +1,28 @@
+/**
+ * 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]);
+ */
 export declare const throttle: <T extends unknown[]>(fn: (...args: T) => unknown, delayMs: number) => readonly [(...args: T) => void, () => void];

package/dist/utils/types.d.ts

@@ -1,6 +1,46 @@
+/** A JSON-representable leaf value. Note `undefined` is not one — see `PathObject`. */
 export type PathValue = string | number | boolean | null;
+/**
+ * An arbitrarily nested, JSON-shaped object.
+ *
+ * Deliberately excludes `Date`, `Map`, `Set` and `undefined`, because the
+ * helpers typed with it round-trip through JSON and would corrupt those.
+ */
 export interface PathObject {
     [key: string | number]: PathValue | PathObject;
 }
+/**
+ * `true` when the string union `T` covers every member of `U`.
+ *
+ * A type-level check, not a runtime one — used to make the compiler prove a
+ * list is exhaustive. See `MustInclude`.
+ */
 export type Has<T extends string, U extends string> = Exclude<U, T> extends never ? true : false;
+/**
+ * Resolves to `T` when the array type `T` contains every member of `I`, and to
+ * `never` when it does not — so an incomplete list has no assignable value.
+ *
+ * ### It only bites on a concrete tuple type
+ * The check reads `T[number]`, which means `T` has to be a literal tuple for
+ * there to be anything to check. Applied to a **generic parameter that must be
+ * inferred from the value**, TypeScript cannot infer through the conditional,
+ * so the parameter falls back to its constraint — usually `string[]` — and
+ * `MustInclude` then accepts any array at all.
+ *
+ * In other words `features: MustInclude<T, 'x'>` on a `<T extends string[]>`
+ * component prop does **not** enforce anything at the call site. Pass the tuple
+ * type explicitly, or add `as const`, if you want the guarantee.
+ *
+ * @example
+ * // Enforced — the tuple type is given explicitly
+ * type Ok = MustInclude<['fullscreenMode', 'legend'], 'fullscreenMode'>;
+ * type No = MustInclude<['legend'], 'fullscreenMode'>; // never
+ *
+ * @example
+ * // NOT enforced — `F` is inferred, so it widens to string[] and this compiles
+ * declare const Header: <F extends string[]>(
+ *   props: { features: MustInclude<F, 'fullscreenMode'> },
+ * ) => null;
+ * Header({ features: ['legend'] });
+ */
 export type MustInclude<T extends readonly string[], I extends string> = Has<T[number], I> extends true ? T : never;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssa-ui-kit/utils",
-  "version": "3.21.2",
+  "version": "3.22.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -37,7 +37,7 @@
   "module": "dist/index.mjs",
   "scripts": {
     "clean": "node ../../scripts/clean.mjs",
-    "build": "node ../../scripts/clean.mjs && webpack --mode=production --node-env=production && node ../../scripts/verify-esm-bundle.mjs && tsc --build ./tsconfig.build.json && resolve-tspaths -p ./tsconfig.build.json",
+    "build": "node ../../scripts/clean.mjs && webpack --mode=production --node-env=production && node ../../scripts/verify-esm-bundle.mjs && tsc --build ./tsconfig.build.json && resolve-tspaths -p ./tsconfig.build.json && node ../../scripts/ai-source-map.mjs .",
     "ts-show-config": "tsc --showConfig -p ./tsconfig.json",
     "ts-show-config-build": "tsc --showConfig -p ./tsconfig.build.json",
     "ts-check": "tsc -p ./tsconfig.json",