@pushwoosh/kit-helpers 4.12.3 → 4.12.5

package/analytics/trackEvent.d.ts

@@ -1,2 +1,6 @@
 import { type PWTrackingEvent } from './utils';
+/**
+ * Queue a product-analytics event on `window.__trackingEventsStore`.
+ * Before shared-scripts boots the store is a plain array, so the queue survives an early call.
+ */
 export declare const trackEvent: (event: PWTrackingEvent) => void;

package/analytics/trackEvent.js

@@ -1,4 +1,8 @@
 /* eslint no-underscore-dangle: 0 */
+/**
+ * Queue a product-analytics event on `window.__trackingEventsStore`.
+ * Before shared-scripts boots the store is a plain array, so the queue survives an early call.
+ */
 export const trackEvent = event => {
   window.__trackingEventsStore = window.__trackingEventsStore ?? [];
   window.__trackingEventsStore.push(event);

package/analytics/utils.d.ts

@@ -1,7 +1,9 @@
+/** A product-analytics event: a name plus arbitrary properties. */
 export interface PWTrackingEvent {
     name: string;
     properties?: Record<string, unknown>;
 }
+/** Sink installed by shared-scripts that replaces the bootstrap array. */
 export interface PWTrackingEventsStoreAPI {
     push(event: PWTrackingEvent): void;
 }

package/callWithRetry.js

@@ -27,7 +27,6 @@ export const callWithRetry = async (operation, policy) => {
   };
   for (let attempt = 1; attempt <= policy.attempts; attempt += 1) {
     try {
-      // eslint-disable-next-line no-await-in-loop
       const result = await operation(attempt);
       if (!policy.until || policy.until(result)) {
         return result;
@@ -45,7 +44,6 @@ export const callWithRetry = async (operation, policy) => {
       };
     }
     if (attempt < policy.attempts) {
-      // eslint-disable-next-line no-await-in-loop
       await sleep(policy.delay);
     }
   }

package/expand.d.ts

@@ -6,6 +6,7 @@ type ExpandTransitionProps = {
     internalClassName?: string;
     children?: ReactNode;
 };
+/** Transition that scales content out of / into its centre; wrap it in a `TransitionGroup`. */
 export declare const ExpandTransition: import("styled-components").StyledComponent<FC<ExpandTransitionProps>, any, {}, never>;
 type CollapseProps = {
     expanded: boolean;
@@ -14,5 +15,9 @@ type CollapseProps = {
     internalClassName?: string;
     children: (() => ReactNode) | ReactNode;
 };
+/**
+ * Height transition driven by the `expanded` prop; measures its own content, so no fixed height is needed.
+ * `children` may be a function to keep the subtree unmounted while collapsed.
+ */
 export declare const Collapse: FC<CollapseProps>;
 export {};

package/expand.js

@@ -1,6 +1,5 @@
 import { createElement as _createElement } from "react";
 import { jsx as _jsx } from "react/jsx-runtime";
-/* eslint-disable react/require-default-props, react/jsx-no-bind */
 import { useEffect, useRef, useState } from 'react';
 import { CSSTransition, TransitionGroup } from 'react-transition-group';
 import styled, { css } from 'styled-components';
@@ -49,10 +48,15 @@ const CollapseTransition = styled(ExpandTransitionComp).withConfig({
 })(["transition:height var(--timeout) linear,opacity var(--timeout) linear;&-enter{overflow:hidden;opacity:0;height:0;}&-enter-active,&-exit{overflow:hidden;opacity:1;height:var(--height);}&-exit-active{overflow:hidden;opacity:0;height:0;}"]);
 const enterExpandCss = css(["overflow:hidden;position:relative;width:1px;height:1px;& > *{position:absolute;top:calc(var(--height) / -2);left:calc(var(--width) / -2);}"]);
 const exitExpandCss = css(["overflow:hidden;position:relative;width:var(--width);height:var(--height);& > *{position:absolute;top:0;left:0;}"]);
+/** Transition that scales content out of / into its centre; wrap it in a `TransitionGroup`. */
 export const ExpandTransition = styled(ExpandTransitionComp).withConfig({
   displayName: "ExpandTransition",
   componentId: "sc-k4fws9-1"
 })(["transition:all var(--timeout) ease-out;& > *{transition:all var(--timeout) ease-out;}&-enter{", "}&-enter-active,&-exit{", "}&-exit-active{", "}"], enterExpandCss, exitExpandCss, enterExpandCss);
+/**
+ * Height transition driven by the `expanded` prop; measures its own content, so no fixed height is needed.
+ * `children` may be a function to keep the subtree unmounted while collapsed.
+ */
 export const Collapse = ({
   expanded,
   children,

package/flex.d.ts

@@ -3,7 +3,9 @@ type FlexContainerProps = CommonContainerProps & {
     $flexDirection?: 'row' | 'row-reverse' | 'column' | 'column-reverse';
     $flexWrap?: 'nowrap' | 'wrap' | 'wrap-reverse';
 };
+/** `display: flex` box driven by `$`-prefixed props (`$gap`, `$alignItems`, `$flexDirection`, box props). */
 export declare const FlexContainer: import("styled-components").StyledComponent<"div", any, FlexContainerProps, never>;
+/** {@link FlexContainer} that wraps — for tag/chip rows of unknown length. */
 export declare const Cluster: import("styled-components").StyledComponent<"div", any, import("./styled-helpers").CommonBoxProps & {
     $alignContent?: import("./styled-helpers").AlignContentValue;
     $alignItems?: import("./styled-helpers").ItemAlignmentValue;

package/flex.js

@@ -10,10 +10,12 @@ const flexDeclarations = {
   }
 };
 const renderFlexCss = renderDeclarations(flexDeclarations);
+/** `display: flex` box driven by `$`-prefixed props (`$gap`, `$alignItems`, `$flexDirection`, box props). */
 export const FlexContainer = styled.div.withConfig({
   displayName: "FlexContainer",
   componentId: "sc-vvrarn-0"
 })(["display:flex;", ""], renderFlexCss);
+/** {@link FlexContainer} that wraps — for tag/chip rows of unknown length. */
 export const Cluster = styled(FlexContainer).attrs({
   $flexWrap: 'wrap'
 }).withConfig({

package/formatNumber.d.ts

@@ -1,3 +1,8 @@
+/** `spaced` groups thousands with a space; `short` compacts to `12K` from 10000 up. */
 type NumberFormat = 'spaced' | 'short';
+/**
+ * Render a number for display.
+ * @param format `spaced` for full digits, `short` for compact notation
+ */
 export declare const formatNumber: (number: number, format: NumberFormat) => string;
 export {};

package/formatNumber.js

@@ -9,6 +9,10 @@ const getNumberAsShortString = num => {
   });
   return formatter.format(num);
 };
+/**
+ * Render a number for display.
+ * @param format `spaced` for full digits, `short` for compact notation
+ */
 export const formatNumber = (number, format) => {
   switch (format) {
     case 'spaced':

package/grid.d.ts

@@ -5,7 +5,9 @@ type GridContainerProps = CommonContainerProps & {
     $justifyItems?: ItemAlignmentValue;
     $placeItems?: ItemAlignmentValue;
 };
+/** `display: grid` box driven by `$`-prefixed props (`$gap`, `$gridAutoFlow`, `$placeItems`, box props). */
 export declare const GridContainer: import("styled-components").StyledComponent<"div", any, GridContainerProps, never>;
+/** Grid with explicit columns: a number means that many equal columns, a string is used as `grid-template-columns`. */
 export declare const Columns: import("styled-components").StyledComponent<"div", any, import("./styled-helpers").CommonBoxProps & {
     $alignContent?: import("./styled-helpers").AlignContentValue;
     $alignItems?: ItemAlignmentValue;
@@ -18,6 +20,7 @@ export declare const Columns: import("styled-components").StyledComponent<"div",
 } & {
     $sizes: StrNum;
 }, never>;
+/** Grid with explicit rows: a number means that many equal rows, a string is used as `grid-template-rows`. */
 export declare const Rows: import("styled-components").StyledComponent<"div", any, import("./styled-helpers").CommonBoxProps & {
     $alignContent?: import("./styled-helpers").AlignContentValue;
     $alignItems?: ItemAlignmentValue;
@@ -30,6 +33,7 @@ export declare const Rows: import("styled-components").StyledComponent<"div", an
 } & {
     $sizes: StrNum;
 }, never>;
+/** Grid that lays children out in one row. */
 export declare const Horizontal: import("styled-components").StyledComponent<"div", any, import("./styled-helpers").CommonBoxProps & {
     $alignContent?: import("./styled-helpers").AlignContentValue;
     $alignItems?: ItemAlignmentValue;
@@ -42,6 +46,7 @@ export declare const Horizontal: import("styled-components").StyledComponent<"di
 } & {
     $gridAutoFlow: string;
 }, "$gridAutoFlow">;
+/** Grid that lays children out in one column. */
 export declare const Vertical: import("styled-components").StyledComponent<"div", any, import("./styled-helpers").CommonBoxProps & {
     $alignContent?: import("./styled-helpers").AlignContentValue;
     $alignItems?: ItemAlignmentValue;

package/grid.js

@@ -15,24 +15,29 @@ const gridDeclarations = {
   }
 };
 const renderGridCss = renderDeclarations(gridDeclarations);
+/** `display: grid` box driven by `$`-prefixed props (`$gap`, `$gridAutoFlow`, `$placeItems`, box props). */
 export const GridContainer = styled.div.withConfig({
   displayName: "GridContainer",
   componentId: "sc-1mpmh7u-0"
 })(["display:grid;", ""], renderGridCss);
+/** Grid with explicit columns: a number means that many equal columns, a string is used as `grid-template-columns`. */
 export const Columns = styled(GridContainer).withConfig({
   displayName: "Columns",
   componentId: "sc-1mpmh7u-1"
 })(["grid-template-columns:", ";"], props => gridTemplate(props.$sizes));
+/** Grid with explicit rows: a number means that many equal rows, a string is used as `grid-template-rows`. */
 export const Rows = styled(GridContainer).withConfig({
   displayName: "Rows",
   componentId: "sc-1mpmh7u-2"
 })(["grid-template-rows:", ";"], props => gridTemplate(props.$sizes));
+/** Grid that lays children out in one row. */
 export const Horizontal = styled(GridContainer).attrs({
   $gridAutoFlow: 'column'
 }).withConfig({
   displayName: "Horizontal",
   componentId: "sc-1mpmh7u-3"
 })([""]);
+/** Grid that lays children out in one column. */
 export const Vertical = styled(GridContainer).attrs({
   $gridAutoFlow: 'row'
 }).withConfig({

package/hooks/types.d.ts

@@ -1,2 +1,4 @@
+/** Value a promise resolves to. */
 export type PromiseType<P extends Promise<any>> = P extends Promise<infer T> ? T : never;
+/** Any async function, the constraint the async hooks are generic over. */
 export type FunctionReturningPromise = (...args: any[]) => Promise<any>;

package/hooks/useAsync.d.ts

@@ -1,6 +1,10 @@
 import { type DependencyList } from 'react';
 import { type FunctionReturningPromise } from './types';
 export type { AsyncState, AsyncFnReturn } from './useAsyncFn';
+/**
+ * Run an async function on mount and whenever `deps` change; starts in the loading state.
+ * Rejections land in `state.error`, they are not re-thrown.
+ */
 export default function useAsync<T extends FunctionReturningPromise>(fn: T, deps?: DependencyList): {
     loading: boolean;
     error?: undefined;

package/hooks/useAsync.js

@@ -3,6 +3,10 @@ import useAsyncFn from './useAsyncFn';
 const getInitialState = () => ({
   loading: true
 });
+/**
+ * Run an async function on mount and whenever `deps` change; starts in the loading state.
+ * Rejections land in `state.error`, they are not re-thrown.
+ */
 export default function useAsync(fn, deps = []) {
   const [state, callback] = useAsyncFn(fn, deps, getInitialState);
   useEffect(() => {

package/hooks/useAsyncFn.d.ts

@@ -1,5 +1,6 @@
 import { type DependencyList } from 'react';
 import type { FunctionReturningPromise, PromiseType } from './types';
+/** Loading / error / value of one async call; the union makes the impossible combinations untypeable. */
 export type AsyncState<T> = {
     loading: boolean;
     error?: undefined;
@@ -18,12 +19,18 @@ export type AsyncState<T> = {
     value: T;
 };
 type StateFromFunctionReturningPromise<T extends FunctionReturningPromise> = AsyncState<PromiseType<ReturnType<T>>>;
+/** `reset: true` drops the previous value while reloading, instead of keeping it visible. */
 export type CallbackParams = {
     reset?: boolean;
 };
+/** What {@link useAsyncFn} returns: current state and the trigger. */
 export type AsyncFnReturn<T extends FunctionReturningPromise = FunctionReturningPromise> = [
     StateFromFunctionReturningPromise<T>,
     (p?: CallbackParams) => ReturnType<T>
 ];
+/**
+ * Run an async function on demand and track its state. Only the newest call may write state,
+ * so an overtaken request cannot overwrite a fresher result.
+ */
 export default function useAsyncFn<T extends FunctionReturningPromise>(fn: T, deps?: DependencyList, initialState?: StateFromFunctionReturningPromise<T> | (() => StateFromFunctionReturningPromise<T>)): AsyncFnReturn<T>;
 export {};

package/hooks/useAsyncFn.js

@@ -3,6 +3,10 @@ import useMountedState from './useMountedState';
 const getDefaultState = () => ({
   loading: false
 });
+/**
+ * Run an async function on demand and track its state. Only the newest call may write state,
+ * so an overtaken request cannot overwrite a fresher result.
+ */
 export default function useAsyncFn(fn, deps = [], initialState = getDefaultState) {
   const lastCallId = useRef(0);
   const isMounted = useMountedState();
@@ -10,7 +14,6 @@ export default function useAsyncFn(fn, deps = [], initialState = getDefaultState
   const callback = useCallback(({
     reset
   } = {}) => {
-    // eslint-disable-next-line no-plusplus
     const callId = ++lastCallId.current;
     const canSet = () => isMounted() && callId === lastCallId.current;
     if (canSet()) {

package/hooks/useAsyncFunction.d.ts

@@ -1,4 +1,5 @@
 import type { FunctionReturningPromise, PromiseType } from './types';
+/** Same as `AsyncState` plus `count` — how many calls have started, useful to tell first load from a refresh. */
 export type AsyncFunctionState<T> = {
     loading: boolean;
     count: number;
@@ -21,9 +22,14 @@ export type AsyncFunctionState<T> = {
     value: T;
 };
 type StateFromFunctionReturningPromise<T extends FunctionReturningPromise> = AsyncFunctionState<PromiseType<ReturnType<T>>>;
+/** What {@link useAsyncFunction} returns: current state and the original function, stabilised. */
 export type AsyncFunctionReturn<T extends FunctionReturningPromise = FunctionReturningPromise> = [
     StateFromFunctionReturningPromise<T>,
     T
 ];
+/**
+ * Like {@link useAsyncFn} but the returned trigger keeps the function's own arguments and identity is stable.
+ * Prefer it when the call takes parameters.
+ */
 export default function useAsyncFunction<T extends FunctionReturningPromise>(fn: T): AsyncFunctionReturn<T>;
 export {};

package/hooks/useAsyncFunction.js

@@ -5,12 +5,15 @@ const getDefaultState = () => ({
   loading: false,
   count: 0
 });
+/**
+ * Like {@link useAsyncFn} but the returned trigger keeps the function's own arguments and identity is stable.
+ * Prefer it when the call takes parameters.
+ */
 export default function useAsyncFunction(fn) {
   const countRef = useRef(0);
   const isMounted = useMountedState();
   const [state, setState] = useState(getDefaultState);
   const execute = usePersistentFunction((...args) => {
-    // eslint-disable-next-line no-plusplus
     const count = ++countRef.current;
     const canSet = () => isMounted() && count === countRef.current;
     if (canSet()) {

package/hooks/useClickAway.js

@@ -48,7 +48,6 @@ export function useClickAway(use, ref,
 cb) {
   // Persist the callback function to avoid re-subscribing on every render
   const persistentCb = usePersistentFunction(cb);
-  // eslint-disable-next-line consistent-return
   useEffect(() => {
     // Only subscribe if the hook is active and the ref points to an element
     if (use && ref.current) {

package/hooks/useDelayedEffect.d.ts

@@ -1,3 +1,7 @@
 import { type DependencyList } from 'react';
+/**
+ * Run an effect `delay` ms after `deps` settle; a new change cancels the pending run.
+ * The effect gets `getIsRunning()` so async work can bail out after unmount.
+ */
 declare const useDelayedEffect: (effect: (getIsRunning: () => boolean) => void, deps: DependencyList, delay: number) => void;
 export default useDelayedEffect;

package/hooks/useDelayedEffect.js

@@ -1,4 +1,8 @@
 import { useEffect } from 'react';
+/**
+ * Run an effect `delay` ms after `deps` settle; a new change cancels the pending run.
+ * The effect gets `getIsRunning()` so async work can bail out after unmount.
+ */
 const useDelayedEffect = (effect, deps, delay) => {
   useEffect(() => {
     let isRunning = true;

package/hooks/useDelayedValue.d.ts

@@ -1,2 +1,3 @@
+/** Debounced mirror of a value — updates `delay` ms after the last change. */
 declare const useDelayedValue: <T>(value: T, delay: number) => T;
 export default useDelayedValue;

package/hooks/useDelayedValue.js

@@ -1,4 +1,5 @@
 import { useState, useEffect } from 'react';
+/** Debounced mirror of a value — updates `delay` ms after the last change. */
 const useDelayedValue = (value, delay) => {
   const [delayedValue, setDelayedValue] = useState(value);
   useEffect(() => {

package/hooks/useEffectOnce.d.ts

@@ -1,3 +1,4 @@
 import { type EffectCallback } from 'react';
+/** `useEffect` with an empty dependency list, without the lint noise at every call site. */
 declare const useEffectOnce: (effect: EffectCallback) => void;
 export default useEffectOnce;

package/hooks/useEffectOnce.js

@@ -1,4 +1,5 @@
 import { useEffect } from 'react';
+/** `useEffect` with an empty dependency list, without the lint noise at every call site. */
 const useEffectOnce = effect => {
   // eslint-disable-next-line
   useEffect(effect, []);

package/hooks/useMount.d.ts

@@ -1,2 +1,3 @@
+/** Call `fn` once after the first render. */
 declare const useMount: (fn: () => void) => void;
 export default useMount;

package/hooks/useMount.js

@@ -1,4 +1,5 @@
 import useEffectOnce from './useEffectOnce';
+/** Call `fn` once after the first render. */
 const useMount = fn => {
   useEffectOnce(() => {
     fn();

package/hooks/useMountedState.d.ts

@@ -1 +1,2 @@
+/** Getter telling whether the component is still mounted — guard state writes after an await with it. */
 export default function useMountedState(): () => boolean;

package/hooks/useMountedState.js

@@ -1,4 +1,5 @@
 import { useCallback, useEffect, useRef } from 'react';
+/** Getter telling whether the component is still mounted — guard state writes after an await with it. */
 export default function useMountedState() {
   const mountedRef = useRef(false);
   const get = useCallback(() => mountedRef.current, []);

package/hooks/useUnmount.d.ts

@@ -1,2 +1,3 @@
+/** Call `fn` on unmount; the latest render's `fn` is used, so it needs no stable identity. */
 declare const useUnmount: (fn: () => any) => void;
 export default useUnmount;

package/hooks/useUnmount.js

@@ -1,5 +1,6 @@
 import { useRef } from 'react';
 import useEffectOnce from './useEffectOnce';
+/** Call `fn` on unmount; the latest render's `fn` is used, so it needs no stable identity. */
 const useUnmount = fn => {
   const fnRef = useRef(fn);
   // update the ref each render so if it change the newest callback will be invoked

package/package.json

@@ -1,37 +1,25 @@
 {
   "name": "@pushwoosh/kit-helpers",
-  "version": "4.12.3",
+  "version": "4.12.5",
   "description": "React component for build Pushwoosh products",
   "main": "index.js",
   "module": "index.js",
   "types": "index.d.ts",
   "sideEffects": false,
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "directory": "dist"
   },
-  "scripts": {
-    "start": "npm run playground",
-    "build": "pushwoosh-engine lib:build && cp ai-documentation.md dist/ai-documentation.md",
-    "playground": "pushwoosh-engine lib:playground",
-    "check": "npm run check:lint && npm run check:types",
-    "check:lint": "echo \"Run check:lint\" && NODE_ENV=production eslint ./src",
-    "check:lint-fix": "echo \"Run check:lint\" && NODE_ENV=production eslint ./src --fix",
-    "check:types": "echo \"Run check:types\" && pushwoosh-engine lib:check-types"
-  },
-  "pre-commit": "check",
   "dependencies": {
     "react-transition-group": "^4.4.5"
   },
   "devDependencies": {
-    "@pushwoosh/frontend-builder-engine": "^3.1.0",
-    "@pushwoosh/kit-constants": "^1.6.0",
-    "@types/react": "^18.3.2",
-    "@types/react-dom": "^18.3.0",
+    "@pushwoosh/kit-constants": "^1.12.3",
+    "@types/react": "^18.3.31",
+    "@types/react-dom": "^18.3.7",
     "@types/react-transition-group": "^4.4.10",
     "@types/styled-components": "^5.1.34",
     "@types/webpack-env": "^1.18.8",
-    "cross-env": "^7.0.3",
-    "pre-commit": "^1.2.2",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "styled-components": "^5.3.11"
@@ -41,6 +29,15 @@
     "styled-components": ">=5.3.3"
   },
   "engines": {
-    "node": ">= 18"
+    "node": ">= 24"
+  },
+  "scripts": {
+    "start": "pnpm run playground",
+    "build": "pushwoosh-engine lib:build",
+    "playground": "pushwoosh-engine lib:playground",
+    "check": "pnpm run check:lint && pnpm run check:types",
+    "check:lint": "echo \"Run check:lint\" && NODE_ENV=production eslint ./src",
+    "check:lint-fix": "echo \"Run check:lint\" && NODE_ENV=production eslint ./src --fix",
+    "check:types": "echo \"Run check:types\" && pushwoosh-engine lib:check-types"
   }
-}
+}

package/styled-helpers.d.ts

@@ -1,7 +1,15 @@
+/** A CSS length: a number is taken as px, a string is passed through verbatim. */
 export type StrNum = string | number;
+/** Type guard for `number`. */
 export declare const isNumber: (value: unknown) => value is number;
+/** Turn a {@link StrNum} into a CSS value: `8` -> `8px`, `'2em'` -> `'2em'`. */
 export declare const toCssValue: (value: StrNum) => string;
+/**
+ * One `property: value;` declaration, or `undefined` when the value is unset.
+ * @param valueConvert applied to the value before printing, e.g. {@link toCssValue}
+ */
 export declare const createCssDeclaration: (property: string, value: any, valueConvert?: (v: any) => any) => string | undefined;
+/** Per-side value for a box property — either the four sides, or the `horizontal`/`vertical` shorthands. */
 export type CssBoxSides<T> = {
     top?: T;
     right?: T;
@@ -16,12 +24,22 @@ export type CssBoxSides<T> = {
     right?: T;
     left?: T;
 };
+/**
+ * Declarations for a box property (`margin`, `padding`, `border`): one shorthand for a scalar,
+ * or per-side declarations for a {@link CssBoxSides} object.
+ */
 export declare function createCssBoxDeclaration<T>(property: string, value?: StrNum | CssBoxSides<T>, valueConvert?: (v: any) => any): string | undefined;
+/** Allowed `overflow` values. */
 export type OverflowValue = 'hidden' | 'auto' | 'scroll' | 'visible';
+/** Allowed `position` values. */
 export type PositionValue = 'static' | 'relative' | 'absolute' | 'fixed' | 'sticky';
+/** Allowed values for the item-alignment properties (`align-items`, `justify-items`, `place-items`). */
 export type ItemAlignmentValue = 'center' | 'start' | 'end' | 'baseline' | 'stretch';
+/** Allowed `justify-content` values. */
 export type JustifyContentValue = 'center' | 'start' | 'end' | 'space-between' | 'space-around' | 'space-evenly' | 'stretch';
+/** Allowed `align-content` values. */
 export type AlignContentValue = JustifyContentValue | 'baseline';
+/** Box-model and positioning props shared by every layout component; the `$` prefix keeps them off the DOM. */
 export type CommonBoxProps = {
     $bgColor?: string;
     $basis?: StrNum;
@@ -50,17 +68,25 @@ export type CommonBoxProps = {
     $width?: StrNum;
     $zIndex?: number;
 };
+/** {@link CommonBoxProps} plus the alignment props meaningful for a flex or grid container. */
 export type CommonContainerProps = CommonBoxProps & {
     $alignContent?: AlignContentValue;
     $alignItems?: ItemAlignmentValue;
     $gap?: StrNum;
     $justifyContent?: JustifyContentValue;
 };
+/** How one prop maps to CSS: target property, whether it is a box property, and an optional value converter. */
 export type CssDeclarationConfig = {
     property: string;
     box?: boolean;
     convert?: (v: any) => any;
 };
+/** Prop-to-CSS map for {@link CommonBoxProps}. */
 export declare const commonBoxDeclarations: Partial<Record<keyof CommonBoxProps, CssDeclarationConfig>>;
+/** Prop-to-CSS map for {@link CommonContainerProps}. */
 export declare const commonContainerDeclarations: Partial<Record<keyof CommonContainerProps, CssDeclarationConfig>>;
+/**
+ * Build the styled-components interpolation for a declaration map: takes props, returns the CSS text.
+ * Props absent from the map are ignored, so a component only reacts to what it declared.
+ */
 export declare const renderDeclarations: <T extends Record<string, any>>(declarations: Partial<Record<keyof T, CssDeclarationConfig>>) => (props: T) => string;

package/styled-helpers.js

@@ -1,11 +1,21 @@
+/** Type guard for `number`. */
 export const isNumber = value => typeof value === 'number';
+/** Turn a {@link StrNum} into a CSS value: `8` -> `8px`, `'2em'` -> `'2em'`. */
 export const toCssValue = value => isNumber(value) ? `${value}px` : value;
+/**
+ * One `property: value;` declaration, or `undefined` when the value is unset.
+ * @param valueConvert applied to the value before printing, e.g. {@link toCssValue}
+ */
 export const createCssDeclaration = (property, value, valueConvert) => {
   if (value !== undefined) {
     return `${property}: ${valueConvert ? valueConvert(value) : value};`;
   }
   return undefined;
 };
+/**
+ * Declarations for a box property (`margin`, `padding`, `border`): one shorthand for a scalar,
+ * or per-side declarations for a {@link CssBoxSides} object.
+ */
 export function createCssBoxDeclaration(property, value, valueConvert) {
   if (typeof value === 'object') {
     const declarations = [];
@@ -27,6 +37,7 @@ export function createCssBoxDeclaration(property, value, valueConvert) {
   }
   return createCssDeclaration(property, value, valueConvert);
 }
+/** Prop-to-CSS map for {@link CommonBoxProps}. */
 export const commonBoxDeclarations = {
   $bgColor: {
     property: 'background-color'
@@ -125,6 +136,7 @@ export const commonBoxDeclarations = {
     property: 'z-index'
   }
 };
+/** Prop-to-CSS map for {@link CommonContainerProps}. */
 export const commonContainerDeclarations = {
   ...commonBoxDeclarations,
   $alignContent: {
@@ -141,6 +153,10 @@ export const commonContainerDeclarations = {
     property: 'justify-content'
   }
 };
+/**
+ * Build the styled-components interpolation for a declaration map: takes props, returns the CSS text.
+ * Props absent from the map are ignored, so a component only reacts to what it declared.
+ */
 export const renderDeclarations = declarations => props => Object.entries(props).map(([key, value]) => {
   const config = declarations[key];
   if (!config || value === undefined) return undefined;