@pushwoosh/kit-helpers 4.10.1 → 4.11.1

package/ai-documentation.md

@@ -24,15 +24,18 @@ React component library for building Pushwoosh products with TypeScript, styled-
 - **Interface:**
 ```ts
 GridContainer<{
-  $alignContent?: 'center' | 'start' | 'end' | 'space-between' | 'space-around' | 'space-evenly' | 'stretch';
+  $alignContent?: 'center' | 'start' | 'end' | 'space-between' | 'space-around' | 'space-evenly' | 'stretch' | 'baseline';
   $alignItems?: 'center' | 'start' | 'end' | 'baseline' | 'stretch';
+  $basis?: StrNum;
   $bgColor?: string;
   $border?: string | CssBoxSides<string>;
   $borderRadius?: StrNum;
   $bottom?: StrNum;
   $boxShadow?: string;
+  $flex?: StrNum;
   $gap?: StrNum;
   $gridAutoFlow?: 'row' | 'column' | 'dense' | 'row dense' | 'column dense';
+  $grow?: number;
   $height?: StrNum;
   $inset?: StrNum;
   $justifyContent?: 'center' | 'start' | 'end' | 'space-between' | 'space-around' | 'space-evenly' | 'stretch';
@@ -47,9 +50,10 @@ GridContainer<{
   $overflowX?: 'hidden' | 'auto' | 'scroll' | 'visible';
   $overflowY?: 'hidden' | 'auto' | 'scroll' | 'visible';
   $padding?: StrNum | CssBoxSides<StrNum>;
-  $placeItems?: 'center' | 'start' | 'end' | 'stretch';
+  $placeItems?: 'center' | 'start' | 'end' | 'baseline' | 'stretch';
   $position?: 'static' | 'relative' | 'absolute' | 'fixed' | 'sticky';
   $right?: StrNum;
+  $shrink?: number;
   $top?: StrNum;
   $width?: StrNum;
   $zIndex?: number;
@@ -60,15 +64,18 @@ GridContainer<{
 
 | Name | Type | Required | Default | Description | Values |
 |---|---|:---:|:---:|---|---|
-| `$alignContent` | enum |  |  | Aligns the grid content along the cross axis | `center`, `start`, `end`, `space-between`, `space-around`, `space-evenly`, `stretch` |
+| `$alignContent` | enum |  |  | Aligns the grid content along the cross axis | `center`, `start`, `end`, `space-between`, `space-around`, `space-evenly`, `stretch`, `baseline` |
 | `$alignItems` | enum |  |  | Aligns grid items along the cross axis | `center`, `start`, `end`, `baseline`, `stretch` |
+| `$basis` | string\|number |  |  | `flex-basis` (only effective when parent is a flex container; number → px) | |
 | `$bgColor` | string |  |  | Background color of the grid container | |
 | `$border` | object |  |  | Border styling, can be string or object with top/right/bottom/left properties | |
 | `$borderRadius` | string\|number |  |  | Border radius, accepts number (converted to px) or string | |
 | `$bottom` | string\|number |  |  | `bottom` offset (number → px) | |
 | `$boxShadow` | string |  |  | CSS box shadow property | |
+| `$flex` | string\|number |  |  | `flex` shorthand (only effective when parent is a flex container) | |
 | `$gap` | string\|number |  |  | Gap between grid items, accepts number (converted to px) or string | |
 | `$gridAutoFlow` | enum |  |  | Controls how auto-placed items are inserted in the grid | `row`, `column`, `dense`, `row dense`, `column dense` |
+| `$grow` | number |  |  | `flex-grow` (only effective when parent is a flex container) | |
 | `$height` | string\|number |  |  | `height` (number → px; strings like `'100%'` / `'auto'` / `'fit-content'` pass through) | |
 | `$inset` | string\|number |  |  | `inset` CSS shorthand (number → px, string passes through, e.g. `'10px 20px'`) | |
 | `$justifyContent` | enum |  |  | Aligns the grid content along the main axis | `center`, `start`, `end`, `space-between`, `space-around`, `space-evenly`, `stretch` |
@@ -83,9 +90,10 @@ GridContainer<{
 | `$overflowX` | enum |  |  | `overflow-x` | `hidden`, `auto`, `scroll`, `visible` |
 | `$overflowY` | enum |  |  | `overflow-y` | `hidden`, `auto`, `scroll`, `visible` |
 | `$padding` | object |  |  | Padding spacing, can be number/string or object with directional properties | |
-| `$placeItems` | enum |  |  | Shorthand for align-items and justify-items | `center`, `start`, `end`, `stretch` |
+| `$placeItems` | enum |  |  | Shorthand for align-items and justify-items | `center`, `start`, `end`, `baseline`, `stretch` |
 | `$position` | enum |  |  | `position` | `static`, `relative`, `absolute`, `fixed`, `sticky` |
 | `$right` | string\|number |  |  | `right` offset (number → px) | |
+| `$shrink` | number |  |  | `flex-shrink` (only effective when parent is a flex container) | |
 | `$top` | string\|number |  |  | `top` offset (number → px) | |
 | `$width` | string\|number |  |  | `width` (number → px; strings pass through) | |
 | `$zIndex` | number |  |  | `z-index` | |
@@ -230,6 +238,77 @@ GridContainer<{
 
 ---
 
+### FlexContainer
+- **Path:** `~/src/flex`
+- **Description:** Base flex container component using CSS Flexbox for one-dimensional layouts
+- **Interface:**
+```ts
+FlexContainer<{
+  // Layout (flex-specific)
+  $flexDirection?: 'row' | 'row-reverse' | 'column' | 'column-reverse';
+  $flexWrap?: 'nowrap' | 'wrap' | 'wrap-reverse';
+  // Container alignment (shared with GridContainer)
+  $alignContent?: 'center' | 'start' | 'end' | 'space-between' | 'space-around' | 'space-evenly' | 'stretch' | 'baseline';
+  $alignItems?: 'center' | 'start' | 'end' | 'baseline' | 'stretch';
+  $gap?: StrNum;
+  $justifyContent?: 'center' | 'start' | 'end' | 'space-between' | 'space-around' | 'space-evenly' | 'stretch';
+  // Plus all CommonBoxProps: sizing ($width/$height/$min*/$max*), spacing ($padding/$margin),
+  // appearance ($bgColor/$border/$borderRadius/$boxShadow), position ($position/$top/$right/$bottom/$left/$inset/$zIndex),
+  // overflow ($overflow/$overflowX/$overflowY), flex-item ($flex/$grow/$shrink/$basis)
+}>
+```
+
+**Props**
+
+| Name | Type | Required | Default | Description | Values |
+|---|---|:---:|:---:|---|---|
+| `$flexDirection` | enum |  | `row` (browser default) | `flex-direction` — main axis direction | `row`, `row-reverse`, `column`, `column-reverse` |
+| `$flexWrap` | enum |  | `nowrap` (browser default) | `flex-wrap` — whether items wrap onto multiple lines | `nowrap`, `wrap`, `wrap-reverse` |
+
+Plus everything from `CommonContainerProps` (`$alignContent`, `$alignItems`, `$justifyContent`, `$gap`) and `CommonBoxProps` — see `GridContainer` props table for the full shared list. Grid-specific props (`$gridAutoFlow`, `$justifyItems`, `$placeItems`) are NOT available on `FlexContainer`.
+
+**Examples**
+```tsx
+<FlexContainer $gap={8} $alignItems="center">
+  <Icon />
+  <span>Label</span>
+</FlexContainer>
+```
+```tsx
+// Column with growing child filling remaining space
+<FlexContainer $flexDirection="column" $height="100vh">
+  <Header />
+  <Main $flex={1} $overflow="auto" />
+  <Footer />
+</FlexContainer>
+```
+
+**Notes**
+- Use when items have content-driven sizes or need to wrap; prefer `GridContainer` for explicit 2D tracks
+- Children can use `$flex` / `$grow` / `$shrink` / `$basis` from `CommonBoxProps` to control sizing — this works on any `GridContainer`/`FlexContainer` child too
+- Prefer the `Cluster` preset for wrap-based layouts (tags/chips)
+
+---
+
+### Cluster
+- **Path:** `~/src/flex`
+- **Description:** Flex container with wrapping enabled — for tag/chip/badge groups
+- **Interface:** `Cluster<FlexContainerProps>`
+
+**Example**
+```tsx
+<Cluster $gap={8}>
+  {tags.map((tag) => <Tag key={tag.id}>{tag.label}</Tag>)}
+</Cluster>
+```
+
+**Notes**
+- Pre-configured with `$flexWrap: 'wrap'`
+- Inherits all `FlexContainer` props (override `$flexWrap` if needed)
+- Perfect for chip/tag rows that need to wrap on narrow widths
+
+---
+
 ### Collapse
 - **Path:** `~/src/expand`
 - **Description:** Animated collapsible component with height transition
@@ -601,7 +680,7 @@ formatNumber(999, 'short')      // '999'
 ---
 
 ### toCssValue
-- **Path:** `~/src/grid`
+- **Path:** `~/src/styled-helpers` (also re-exported from `~/src/grid` for back-compat)
 - **Description:** Converts number to px string or returns string as-is
 - **Signature:** `toCssValue(value: string | number): string`
 
@@ -612,7 +691,7 @@ toCssValue('2rem')  // '2rem'
 ```
 
 **Notes**
-- Used internally by grid components
+- Used internally by grid and flex components
 - Numbers become pixels
 - Strings pass through unchanged
 - Enables flexible prop values
@@ -687,6 +766,30 @@ type CssBoxSides<T> =
 ```
 - **Description:** Flexible type for directional CSS properties like margin/padding
 
+### CommonBoxProps
+- **Path:** `~/src/styled-helpers`
+- **Description:** Shared box-model/positioning/flex-item props consumed by both `GridContainer` and `FlexContainer`. Covers sizing (`$width`, `$height`, `$minWidth`/`$minHeight`, `$maxWidth`/`$maxHeight`), spacing (`$padding`, `$margin`), appearance (`$bgColor`, `$border`, `$borderRadius`, `$boxShadow`), position (`$position`, `$top`/`$right`/`$bottom`/`$left`, `$inset`, `$zIndex`), overflow (`$overflow`/`$overflowX`/`$overflowY`), and flex-item sizing (`$flex`, `$grow`, `$shrink`, `$basis`)
+
+### CommonContainerProps
+- **Path:** `~/src/styled-helpers`
+- **Definition:** `CommonBoxProps & { $alignContent?: AlignContentValue; $alignItems?: ItemAlignmentValue; $gap?: StrNum; $justifyContent?: JustifyContentValue }`
+- **Description:** Extends `CommonBoxProps` with alignment props that work in both grid and flex contexts. Used as the base for `GridContainer` and `FlexContainer` props
+
+### ItemAlignmentValue
+- **Path:** `~/src/styled-helpers`
+- **Definition:** `'center' | 'start' | 'end' | 'baseline' | 'stretch'`
+- **Description:** Valid values for item-level alignment props: `$alignItems`, `$justifyItems`, `$placeItems`
+
+### JustifyContentValue
+- **Path:** `~/src/styled-helpers`
+- **Definition:** `'center' | 'start' | 'end' | 'space-between' | 'space-around' | 'space-evenly' | 'stretch'`
+- **Description:** Valid values for `$justifyContent`. Per CSS Box Alignment L3, `justify-content` does NOT accept `baseline` — use `AlignContentValue` for `$alignContent`
+
+### AlignContentValue
+- **Path:** `~/src/styled-helpers`
+- **Definition:** `JustifyContentValue | 'baseline'`
+- **Description:** Valid values for `$alignContent`. Same as `JustifyContentValue` plus `baseline` (which is spec-valid only for the cross-axis content distribution)
+
 ### AsyncState
 - **Definition:** `type AsyncState<T> = { loading: boolean; error?: Error; value?: T }`
 - **Description:** State shape for async operations with loading, error, and value
@@ -723,6 +826,9 @@ type CssBoxSides<T> =
 
 ## Best Practices
 - Use specific layout components (Columns, Horizontal, Vertical) over generic GridContainer
+- Use the `Cluster` preset for wrap-based layouts; reach for `FlexContainer` for everything else
+- Prefer `FlexContainer` over `GridContainer` when item sizes are content-driven or you need wrapping; prefer Grid when you have explicit row/column tracks
+- Set `$flex` / `$grow` / `$shrink` / `$basis` on any `GridContainer`/`FlexContainer` child to control its size inside a flex parent — no extra wrapper needed
 - Prefix all styled-component props with `$` to avoid DOM prop warnings
 - Use `usePersistentFunction` for callbacks passed to memoized components
 - Check `isMounted()` before state updates in async operations

package/flex.d.ts

@@ -0,0 +1,18 @@
+import { CommonContainerProps } from './styled-helpers';
+type FlexContainerProps = CommonContainerProps & {
+    $flexDirection?: 'row' | 'row-reverse' | 'column' | 'column-reverse';
+    $flexWrap?: 'nowrap' | 'wrap' | 'wrap-reverse';
+};
+export declare const FlexContainer: import("styled-components").StyledComponent<"div", any, FlexContainerProps, never>;
+export declare const Cluster: import("styled-components").StyledComponent<"div", any, import("./styled-helpers").CommonBoxProps & {
+    $alignContent?: import("./styled-helpers").AlignContentValue | undefined;
+    $alignItems?: import("./styled-helpers").ItemAlignmentValue | undefined;
+    $gap?: import("./styled-helpers").StrNum | undefined;
+    $justifyContent?: import("./styled-helpers").JustifyContentValue | undefined;
+} & {
+    $flexDirection?: "row" | "row-reverse" | "column" | "column-reverse" | undefined;
+    $flexWrap?: "wrap" | "nowrap" | "wrap-reverse" | undefined;
+} & {
+    $flexWrap: string;
+}, "$flexWrap">;
+export {};

package/flex.js

@@ -0,0 +1,22 @@
+import styled from 'styled-components';
+import { commonContainerDeclarations, renderDeclarations } from './styled-helpers';
+const flexDeclarations = {
+  ...commonContainerDeclarations,
+  $flexDirection: {
+    property: 'flex-direction'
+  },
+  $flexWrap: {
+    property: 'flex-wrap'
+  }
+};
+const renderFlexCss = renderDeclarations(flexDeclarations);
+export const FlexContainer = styled.div.withConfig({
+  displayName: "FlexContainer",
+  componentId: "sc-vvrarn-0"
+})(["display:flex;", ""], renderFlexCss);
+export const Cluster = styled(FlexContainer).attrs({
+  $flexWrap: 'wrap'
+}).withConfig({
+  displayName: "Cluster",
+  componentId: "sc-vvrarn-1"
+})([""]);

package/grid.d.ts

@@ -1,62 +1,56 @@
-type StrNum = string | number;
-export declare const toCssValue: (value: StrNum) => string;
-type CssBoxSides<T> = {
-    top?: T;
-    right?: T;
-    bottom?: T;
-    left?: T;
-} | {
-    horizontal: T;
-    top?: T;
-    bottom?: T;
-} | {
-    vertical: T;
-    right?: T;
-    left?: T;
-};
-type OverflowValue = 'hidden' | 'auto' | 'scroll' | 'visible';
-type GridContainerProps = {
-    $alignContent?: 'center' | 'start' | 'end' | 'space-between' | 'space-around' | 'space-evenly' | 'stretch';
-    $alignItems?: 'center' | 'start' | 'end' | 'baseline' | 'stretch';
-    $bgColor?: string;
-    $border?: string | CssBoxSides<string>;
-    $borderRadius?: StrNum;
-    $bottom?: StrNum;
-    $boxShadow?: string;
-    $gap?: StrNum;
+import { StrNum, ItemAlignmentValue, CommonContainerProps } from './styled-helpers';
+export { toCssValue } from './styled-helpers';
+type GridContainerProps = CommonContainerProps & {
     $gridAutoFlow?: 'row' | 'column' | 'dense' | 'row dense' | 'column dense';
-    $height?: StrNum;
-    $inset?: StrNum;
-    $justifyContent?: 'center' | 'start' | 'end' | 'space-between' | 'space-around' | 'space-evenly' | 'stretch';
-    $justifyItems?: 'center' | 'start' | 'end' | 'baseline' | 'stretch';
-    $left?: StrNum;
-    $margin?: StrNum | CssBoxSides<StrNum>;
-    $maxHeight?: StrNum;
-    $maxWidth?: StrNum;
-    $minHeight?: StrNum;
-    $minWidth?: StrNum;
-    $overflow?: OverflowValue;
-    $overflowX?: OverflowValue;
-    $overflowY?: OverflowValue;
-    $padding?: StrNum | CssBoxSides<StrNum>;
-    $placeItems?: 'center' | 'start' | 'end' | 'stretch';
-    $position?: 'static' | 'relative' | 'absolute' | 'fixed' | 'sticky';
-    $right?: StrNum;
-    $top?: StrNum;
-    $width?: StrNum;
-    $zIndex?: number;
+    $justifyItems?: ItemAlignmentValue;
+    $placeItems?: ItemAlignmentValue;
 };
 export declare const GridContainer: import("styled-components").StyledComponent<"div", any, GridContainerProps, never>;
-export declare const Columns: import("styled-components").StyledComponent<"div", any, GridContainerProps & {
+export declare const Columns: import("styled-components").StyledComponent<"div", any, import("./styled-helpers").CommonBoxProps & {
+    $alignContent?: import("./styled-helpers").AlignContentValue | undefined;
+    $alignItems?: ItemAlignmentValue | undefined;
+    $gap?: StrNum | undefined;
+    $justifyContent?: import("./styled-helpers").JustifyContentValue | undefined;
+} & {
+    $gridAutoFlow?: "row" | "column" | "dense" | "row dense" | "column dense" | undefined;
+    $justifyItems?: ItemAlignmentValue | undefined;
+    $placeItems?: ItemAlignmentValue | undefined;
+} & {
     $sizes: StrNum;
 }, never>;
-export declare const Rows: import("styled-components").StyledComponent<"div", any, GridContainerProps & {
+export declare const Rows: import("styled-components").StyledComponent<"div", any, import("./styled-helpers").CommonBoxProps & {
+    $alignContent?: import("./styled-helpers").AlignContentValue | undefined;
+    $alignItems?: ItemAlignmentValue | undefined;
+    $gap?: StrNum | undefined;
+    $justifyContent?: import("./styled-helpers").JustifyContentValue | undefined;
+} & {
+    $gridAutoFlow?: "row" | "column" | "dense" | "row dense" | "column dense" | undefined;
+    $justifyItems?: ItemAlignmentValue | undefined;
+    $placeItems?: ItemAlignmentValue | undefined;
+} & {
     $sizes: StrNum;
 }, never>;
-export declare const Horizontal: import("styled-components").StyledComponent<"div", any, GridContainerProps & {
+export declare const Horizontal: import("styled-components").StyledComponent<"div", any, import("./styled-helpers").CommonBoxProps & {
+    $alignContent?: import("./styled-helpers").AlignContentValue | undefined;
+    $alignItems?: ItemAlignmentValue | undefined;
+    $gap?: StrNum | undefined;
+    $justifyContent?: import("./styled-helpers").JustifyContentValue | undefined;
+} & {
+    $gridAutoFlow?: "row" | "column" | "dense" | "row dense" | "column dense" | undefined;
+    $justifyItems?: ItemAlignmentValue | undefined;
+    $placeItems?: ItemAlignmentValue | undefined;
+} & {
     $gridAutoFlow: string;
 }, "$gridAutoFlow">;
-export declare const Vertical: import("styled-components").StyledComponent<"div", any, GridContainerProps & {
+export declare const Vertical: import("styled-components").StyledComponent<"div", any, import("./styled-helpers").CommonBoxProps & {
+    $alignContent?: import("./styled-helpers").AlignContentValue | undefined;
+    $alignItems?: ItemAlignmentValue | undefined;
+    $gap?: StrNum | undefined;
+    $justifyContent?: import("./styled-helpers").JustifyContentValue | undefined;
+} & {
+    $gridAutoFlow?: "row" | "column" | "dense" | "row dense" | "column dense" | undefined;
+    $justifyItems?: ItemAlignmentValue | undefined;
+    $placeItems?: ItemAlignmentValue | undefined;
+} & {
     $gridAutoFlow: string;
 }, "$gridAutoFlow">;
-export {};

package/grid.js

@@ -1,153 +1,24 @@
 import styled from 'styled-components';
-const isNumber = value => typeof value === 'number';
-export const toCssValue = value => isNumber(value) ? `${value}px` : value;
+import { isNumber, commonContainerDeclarations, renderDeclarations } from './styled-helpers';
+export { toCssValue } from './styled-helpers';
 const gridTemplate = value => isNumber(value) ? `repeat(${value}, 1fr)` : value;
-const createCssDeclaration = (property, value, valueConvert) => {
-  if (value !== undefined) {
-    return `${property}: ${valueConvert ? valueConvert(value) : value};`;
-  }
-  return undefined;
-};
-function createCssBoxDeclaration(property, value, valueConvert) {
-  if (typeof value === 'object') {
-    const declarations = [];
-    const {
-      horizontal,
-      vertical,
-      ...rest
-    } = value;
-    if (horizontal) {
-      declarations.push(createCssDeclaration(`${property}-left`, horizontal, valueConvert), createCssDeclaration(`${property}-right`, horizontal, valueConvert));
-    }
-    if (vertical) {
-      declarations.push(createCssDeclaration(`${property}-top`, vertical, valueConvert), createCssDeclaration(`${property}-bottom`, vertical, valueConvert));
-    }
-    Object.entries(rest).forEach(([key, keyValue]) => {
-      declarations.push(createCssDeclaration(`${property}-${key}`, keyValue, valueConvert));
-    });
-    return declarations.join('');
-  }
-  return createCssDeclaration(property, value, valueConvert);
-}
-const cssDeclarations = {
-  $alignContent: {
-    property: 'align-content'
-  },
-  $alignItems: {
-    property: 'align-items'
-  },
-  $bgColor: {
-    property: 'background-color'
-  },
-  $border: {
-    property: 'border',
-    box: true
-  },
-  $borderRadius: {
-    property: 'border-radius',
-    convert: toCssValue
-  },
-  $boxShadow: {
-    property: 'box-shadow'
-  },
-  $gap: {
-    property: 'gap',
-    convert: toCssValue
-  },
+const gridDeclarations = {
+  ...commonContainerDeclarations,
   $gridAutoFlow: {
     property: 'grid-auto-flow'
   },
-  $height: {
-    property: 'height',
-    convert: toCssValue
-  },
-  $justifyContent: {
-    property: 'justify-content'
-  },
   $justifyItems: {
     property: 'justify-items'
   },
-  $margin: {
-    property: 'margin',
-    box: true,
-    convert: toCssValue
-  },
-  $maxHeight: {
-    property: 'max-height',
-    convert: toCssValue
-  },
-  $maxWidth: {
-    property: 'max-width',
-    convert: toCssValue
-  },
-  $minHeight: {
-    property: 'min-height',
-    convert: toCssValue
-  },
-  $minWidth: {
-    property: 'min-width',
-    convert: toCssValue
-  },
-  $overflow: {
-    property: 'overflow'
-  },
-  $overflowX: {
-    property: 'overflow-x'
-  },
-  $overflowY: {
-    property: 'overflow-y'
-  },
-  $padding: {
-    property: 'padding',
-    box: true,
-    convert: toCssValue
-  },
   $placeItems: {
     property: 'place-items'
-  },
-  $position: {
-    property: 'position'
-  },
-  $inset: {
-    property: 'inset',
-    convert: toCssValue
-  },
-  $top: {
-    property: 'top',
-    convert: toCssValue
-  },
-  $right: {
-    property: 'right',
-    convert: toCssValue
-  },
-  $bottom: {
-    property: 'bottom',
-    convert: toCssValue
-  },
-  $left: {
-    property: 'left',
-    convert: toCssValue
-  },
-  $width: {
-    property: 'width',
-    convert: toCssValue
-  },
-  $zIndex: {
-    property: 'z-index'
   }
 };
-const renderCssDeclarations = props => Object.entries(props).map(([key, value]) => {
-  const config = cssDeclarations[key];
-  if (!config || value === undefined) return undefined;
-  if (config.box) {
-    return createCssBoxDeclaration(config.property, value, config.convert);
-  }
-  return createCssDeclaration(config.property, value, config.convert);
-}).filter(Boolean).join('\n');
+const renderGridCss = renderDeclarations(gridDeclarations);
 export const GridContainer = styled.div.withConfig({
   displayName: "GridContainer",
   componentId: "sc-1mpmh7u-0"
-})(["display:grid;", ""], renderCssDeclarations);
+})(["display:grid;", ""], renderGridCss);
 export const Columns = styled(GridContainer).withConfig({
   displayName: "Columns",
   componentId: "sc-1mpmh7u-1"

package/index.d.ts

@@ -1,9 +1,11 @@
 export * from './grid';
+export * from './flex';
 export * from './expand';
 export * from './hooks/useClickAway';
 export { identifyOpenReplaySession } from './analytics/identifyOpenReplay';
 export { trackEvent } from './analytics/trackEvent';
 export { formatNumber } from './formatNumber';
+export { readNavigationHistory, writeNavigationHistory } from './navigation';
 export { default as usePersistentFunction } from './hooks/usePersistentFunction';
 export { default as useEffectOnce } from './hooks/useEffectOnce';
 export { default as useMountedState } from './hooks/useMountedState';

package/index.js

@@ -1,9 +1,11 @@
 export * from './grid';
+export * from './flex';
 export * from './expand';
 export * from './hooks/useClickAway';
 export { identifyOpenReplaySession } from './analytics/identifyOpenReplay';
 export { trackEvent } from './analytics/trackEvent';
 export { formatNumber } from './formatNumber';
+export { readNavigationHistory, writeNavigationHistory } from './navigation';
 export { default as usePersistentFunction } from './hooks/usePersistentFunction';
 export { default as useEffectOnce } from './hooks/useEffectOnce';
 export { default as useMountedState } from './hooks/useMountedState';

package/navigation.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Reads the navigation stack from sessionStorage.
+ * The last element is the current page.
+ */
+export declare function readNavigationHistory(): string[];
+/**
+ * Persists the navigation stack to sessionStorage.
+ */
+export declare function writeNavigationHistory(entries: string[]): void;

package/navigation.js

@@ -0,0 +1,25 @@
+const STORAGE_KEY = 'pw_navigation_history';
+const MAX_ENTRIES = 50;
+/**
+ * Reads the navigation stack from sessionStorage.
+ * The last element is the current page.
+ */
+export function readNavigationHistory() {
+  try {
+    const raw = sessionStorage.getItem(STORAGE_KEY);
+    const parsed = raw ? JSON.parse(raw) : null;
+    return Array.isArray(parsed) && parsed.every(e => typeof e === 'string') ? parsed.slice(-MAX_ENTRIES) : [];
+  } catch {
+    return [];
+  }
+}
+/**
+ * Persists the navigation stack to sessionStorage.
+ */
+export function writeNavigationHistory(entries) {
+  try {
+    sessionStorage.setItem(STORAGE_KEY, JSON.stringify(entries.slice(-MAX_ENTRIES)));
+  } catch {
+    // sessionStorage is unavailable (private mode / quota exceeded) — silently ignore.
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pushwoosh/kit-helpers",
-  "version": "4.10.1",
+  "version": "4.11.1",
   "description": "React component for build Pushwoosh products",
   "main": "index.js",
   "module": "index.js",

package/styled-helpers.d.ts

@@ -0,0 +1,66 @@
+export type StrNum = string | number;
+export declare const isNumber: (value: unknown) => value is number;
+export declare const toCssValue: (value: StrNum) => string;
+export declare const createCssDeclaration: (property: string, value: any, valueConvert?: (v: any) => any) => string | undefined;
+export type CssBoxSides<T> = {
+    top?: T;
+    right?: T;
+    bottom?: T;
+    left?: T;
+} | {
+    horizontal: T;
+    top?: T;
+    bottom?: T;
+} | {
+    vertical: T;
+    right?: T;
+    left?: T;
+};
+export declare function createCssBoxDeclaration<T>(property: string, value?: StrNum | CssBoxSides<T>, valueConvert?: (v: any) => any): string | undefined;
+export type OverflowValue = 'hidden' | 'auto' | 'scroll' | 'visible';
+export type PositionValue = 'static' | 'relative' | 'absolute' | 'fixed' | 'sticky';
+export type ItemAlignmentValue = 'center' | 'start' | 'end' | 'baseline' | 'stretch';
+export type JustifyContentValue = 'center' | 'start' | 'end' | 'space-between' | 'space-around' | 'space-evenly' | 'stretch';
+export type AlignContentValue = JustifyContentValue | 'baseline';
+export type CommonBoxProps = {
+    $bgColor?: string;
+    $basis?: StrNum;
+    $border?: string | CssBoxSides<string>;
+    $borderRadius?: StrNum;
+    $bottom?: StrNum;
+    $boxShadow?: string;
+    $flex?: StrNum;
+    $grow?: number;
+    $height?: StrNum;
+    $inset?: StrNum;
+    $left?: StrNum;
+    $margin?: StrNum | CssBoxSides<StrNum>;
+    $maxHeight?: StrNum;
+    $maxWidth?: StrNum;
+    $minHeight?: StrNum;
+    $minWidth?: StrNum;
+    $overflow?: OverflowValue;
+    $overflowX?: OverflowValue;
+    $overflowY?: OverflowValue;
+    $padding?: StrNum | CssBoxSides<StrNum>;
+    $position?: PositionValue;
+    $right?: StrNum;
+    $shrink?: number;
+    $top?: StrNum;
+    $width?: StrNum;
+    $zIndex?: number;
+};
+export type CommonContainerProps = CommonBoxProps & {
+    $alignContent?: AlignContentValue;
+    $alignItems?: ItemAlignmentValue;
+    $gap?: StrNum;
+    $justifyContent?: JustifyContentValue;
+};
+export type CssDeclarationConfig = {
+    property: string;
+    box?: boolean;
+    convert?: (v: any) => any;
+};
+export declare const commonBoxDeclarations: Partial<Record<keyof CommonBoxProps, CssDeclarationConfig>>;
+export declare const commonContainerDeclarations: Partial<Record<keyof CommonContainerProps, CssDeclarationConfig>>;
+export declare const renderDeclarations: <T extends Record<string, any>>(declarations: Partial<Record<keyof T, CssDeclarationConfig>>) => (props: T) => string;

package/styled-helpers.js

@@ -0,0 +1,151 @@
+export const isNumber = value => typeof value === 'number';
+export const toCssValue = value => isNumber(value) ? `${value}px` : value;
+export const createCssDeclaration = (property, value, valueConvert) => {
+  if (value !== undefined) {
+    return `${property}: ${valueConvert ? valueConvert(value) : value};`;
+  }
+  return undefined;
+};
+export function createCssBoxDeclaration(property, value, valueConvert) {
+  if (typeof value === 'object') {
+    const declarations = [];
+    const {
+      horizontal,
+      vertical,
+      ...rest
+    } = value;
+    if (horizontal) {
+      declarations.push(createCssDeclaration(`${property}-left`, horizontal, valueConvert), createCssDeclaration(`${property}-right`, horizontal, valueConvert));
+    }
+    if (vertical) {
+      declarations.push(createCssDeclaration(`${property}-top`, vertical, valueConvert), createCssDeclaration(`${property}-bottom`, vertical, valueConvert));
+    }
+    Object.entries(rest).forEach(([key, keyValue]) => {
+      declarations.push(createCssDeclaration(`${property}-${key}`, keyValue, valueConvert));
+    });
+    return declarations.join('');
+  }
+  return createCssDeclaration(property, value, valueConvert);
+}
+export const commonBoxDeclarations = {
+  $bgColor: {
+    property: 'background-color'
+  },
+  $basis: {
+    property: 'flex-basis',
+    convert: toCssValue
+  },
+  $border: {
+    property: 'border',
+    box: true
+  },
+  $borderRadius: {
+    property: 'border-radius',
+    convert: toCssValue
+  },
+  $bottom: {
+    property: 'bottom',
+    convert: toCssValue
+  },
+  $boxShadow: {
+    property: 'box-shadow'
+  },
+  $flex: {
+    property: 'flex'
+  },
+  $grow: {
+    property: 'flex-grow'
+  },
+  $height: {
+    property: 'height',
+    convert: toCssValue
+  },
+  $inset: {
+    property: 'inset',
+    convert: toCssValue
+  },
+  $left: {
+    property: 'left',
+    convert: toCssValue
+  },
+  $margin: {
+    property: 'margin',
+    box: true,
+    convert: toCssValue
+  },
+  $maxHeight: {
+    property: 'max-height',
+    convert: toCssValue
+  },
+  $maxWidth: {
+    property: 'max-width',
+    convert: toCssValue
+  },
+  $minHeight: {
+    property: 'min-height',
+    convert: toCssValue
+  },
+  $minWidth: {
+    property: 'min-width',
+    convert: toCssValue
+  },
+  $overflow: {
+    property: 'overflow'
+  },
+  $overflowX: {
+    property: 'overflow-x'
+  },
+  $overflowY: {
+    property: 'overflow-y'
+  },
+  $padding: {
+    property: 'padding',
+    box: true,
+    convert: toCssValue
+  },
+  $position: {
+    property: 'position'
+  },
+  $right: {
+    property: 'right',
+    convert: toCssValue
+  },
+  $shrink: {
+    property: 'flex-shrink'
+  },
+  $top: {
+    property: 'top',
+    convert: toCssValue
+  },
+  $width: {
+    property: 'width',
+    convert: toCssValue
+  },
+  $zIndex: {
+    property: 'z-index'
+  }
+};
+export const commonContainerDeclarations = {
+  ...commonBoxDeclarations,
+  $alignContent: {
+    property: 'align-content'
+  },
+  $alignItems: {
+    property: 'align-items'
+  },
+  $gap: {
+    property: 'gap',
+    convert: toCssValue
+  },
+  $justifyContent: {
+    property: 'justify-content'
+  }
+};
+export const renderDeclarations = declarations => props => Object.entries(props).map(([key, value]) => {
+  const config = declarations[key];
+  if (!config || value === undefined) return undefined;
+  if (config.box) {
+    return createCssBoxDeclaration(config.property, value, config.convert);
+  }
+  return createCssDeclaration(config.property, value, config.convert);
+}).filter(Boolean).join('\n');