@pushwoosh/kit-helpers 4.9.2 → 4.11.0

package/ai-documentation.md

@@ -12,7 +12,7 @@ description: "React component library for building Pushwoosh products with TypeS
 
 React component library for building Pushwoosh products with TypeScript, styled-components, and comprehensive hook utilities.
 
-> This page is generated from `ai-documentation.json` and groups the API by Components, Hooks, Utilities, and Types. All styled-component props are prefixed with `$` to avoid DOM prop warnings.
+> This page groups the API by Components, Hooks, Utilities, and Types. All styled-component props are prefixed with `$` to avoid DOM prop warnings.
 
 ---
 
@@ -24,19 +24,39 @@ 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';
   $justifyItems?: 'center' | 'start' | 'end' | 'baseline' | 'stretch';
+  $left?: StrNum;
   $margin?: StrNum | CssBoxSides<StrNum>;
+  $maxHeight?: StrNum;
+  $maxWidth?: StrNum;
+  $minHeight?: StrNum;
+  $minWidth?: StrNum;
+  $overflow?: 'hidden' | 'auto' | 'scroll' | 'visible';
+  $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;
 }>
 ```
 
@@ -44,32 +64,71 @@ 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` |
 | `$justifyItems` | enum |  |  | Aligns grid items along the main axis | `center`, `start`, `end`, `baseline`, `stretch` |
+| `$left` | string\|number |  |  | `left` offset (number → px) | |
 | `$margin` | object |  |  | Margin spacing, can be number/string or object with directional properties | |
+| `$maxHeight` | string\|number |  |  | `max-height` (number → px) | |
+| `$maxWidth` | string\|number |  |  | `max-width` (number → px) | |
+| `$minHeight` | string\|number |  |  | `min-height` (number → px) | |
+| `$minWidth` | string\|number |  |  | `min-width` (number → px) | |
+| `$overflow` | enum |  |  | `overflow` | `hidden`, `auto`, `scroll`, `visible` |
+| `$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` | |
 
-**Example**
+**Examples**
 ```tsx
 <GridContainer $gap={16} $padding={20} $bgColor="#f0f0f0">
   <div>Item 1</div>
   <div>Item 2</div>
 </GridContainer>
 ```
+```tsx
+// Absolute tooltip
+<GridContainer $position="absolute" $top={40} $left={20} $width={350} $zIndex={10}>
+  <Tooltip />
+</GridContainer>
+```
+```tsx
+// Stretch horizontally
+<GridContainer $position="absolute" $left={0} $right={0} $bottom={0}>
+  <Footer />
+</GridContainer>
+```
+```tsx
+// Scrollable region
+<GridContainer $padding={16} $maxHeight={400} $overflow="auto">
+  ...
+</GridContainer>
+```
 
 **Notes**
 - All props are prefixed with `$` to indicate they are styled-component props
-- Numbers are automatically converted to `px` units
+- Numbers are automatically converted to `px` units; strings (e.g. `'100%'`, `'fit-content'`, `'2rem'`) pass through unchanged
 - Use `CssBoxSides` for asymmetric margin/padding/border
+- `$inset` maps directly to the CSS `inset` shorthand; for per-side control use individual `$top` / `$right` / `$bottom` / `$left`
 - Prefer specific layout components (Columns, Rows, Horizontal, Vertical) for common patterns
 
 ---
@@ -179,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
@@ -550,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`
 
@@ -561,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
@@ -636,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
@@ -672,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,100 +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;
+import { StrNum, ItemAlignmentValue, CommonContainerProps } from './styled-helpers';
+export { toCssValue } from './styled-helpers';
+type GridContainerProps = CommonContainerProps & {
+    $gridAutoFlow?: 'row' | 'column' | 'dense' | 'row dense' | 'column dense';
+    $justifyItems?: ItemAlignmentValue;
+    $placeItems?: ItemAlignmentValue;
 };
-export declare const GridContainer: import("styled-components").StyledComponent<"div", any, {
-    $alignContent?: "end" | "start" | "center" | "space-between" | "space-around" | "space-evenly" | "stretch" | undefined;
-    $alignItems?: "end" | "start" | "center" | "stretch" | "baseline" | undefined;
-    $bgColor?: string | undefined;
-    $border?: string | CssBoxSides<string> | undefined;
-    $borderRadius?: StrNum | undefined;
-    $boxShadow?: string | undefined;
-    $gap?: StrNum | undefined;
-    $gridAutoFlow?: "row" | "column" | "dense" | "row dense" | "column dense" | undefined;
-    $justifyContent?: "end" | "start" | "center" | "space-between" | "space-around" | "space-evenly" | "stretch" | undefined;
-    $justifyItems?: "end" | "start" | "center" | "stretch" | "baseline" | undefined;
-    $margin?: StrNum | CssBoxSides<StrNum> | undefined;
-    $padding?: StrNum | CssBoxSides<StrNum> | undefined;
-    $placeItems?: "end" | "start" | "center" | "stretch" | undefined;
-}, never>;
-export declare const Columns: import("styled-components").StyledComponent<"div", any, {
-    $alignContent?: "end" | "start" | "center" | "space-between" | "space-around" | "space-evenly" | "stretch" | undefined;
-    $alignItems?: "end" | "start" | "center" | "stretch" | "baseline" | undefined;
-    $bgColor?: string | undefined;
-    $border?: string | CssBoxSides<string> | undefined;
-    $borderRadius?: StrNum | undefined;
-    $boxShadow?: string | undefined;
+export declare const GridContainer: import("styled-components").StyledComponent<"div", any, GridContainerProps, never>;
+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;
-    $justifyContent?: "end" | "start" | "center" | "space-between" | "space-around" | "space-evenly" | "stretch" | undefined;
-    $justifyItems?: "end" | "start" | "center" | "stretch" | "baseline" | undefined;
-    $margin?: StrNum | CssBoxSides<StrNum> | undefined;
-    $padding?: StrNum | CssBoxSides<StrNum> | undefined;
-    $placeItems?: "end" | "start" | "center" | "stretch" | undefined;
+    $justifyItems?: ItemAlignmentValue | undefined;
+    $placeItems?: ItemAlignmentValue | undefined;
 } & {
     $sizes: StrNum;
 }, never>;
-export declare const Rows: import("styled-components").StyledComponent<"div", any, {
-    $alignContent?: "end" | "start" | "center" | "space-between" | "space-around" | "space-evenly" | "stretch" | undefined;
-    $alignItems?: "end" | "start" | "center" | "stretch" | "baseline" | undefined;
-    $bgColor?: string | undefined;
-    $border?: string | CssBoxSides<string> | undefined;
-    $borderRadius?: StrNum | undefined;
-    $boxShadow?: string | undefined;
+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;
-    $justifyContent?: "end" | "start" | "center" | "space-between" | "space-around" | "space-evenly" | "stretch" | undefined;
-    $justifyItems?: "end" | "start" | "center" | "stretch" | "baseline" | undefined;
-    $margin?: StrNum | CssBoxSides<StrNum> | undefined;
-    $padding?: StrNum | CssBoxSides<StrNum> | undefined;
-    $placeItems?: "end" | "start" | "center" | "stretch" | undefined;
+    $justifyItems?: ItemAlignmentValue | undefined;
+    $placeItems?: ItemAlignmentValue | undefined;
 } & {
     $sizes: StrNum;
 }, never>;
-export declare const Horizontal: import("styled-components").StyledComponent<"div", any, {
-    $alignContent?: "end" | "start" | "center" | "space-between" | "space-around" | "space-evenly" | "stretch" | undefined;
-    $alignItems?: "end" | "start" | "center" | "stretch" | "baseline" | undefined;
-    $bgColor?: string | undefined;
-    $border?: string | CssBoxSides<string> | undefined;
-    $borderRadius?: StrNum | undefined;
-    $boxShadow?: string | undefined;
+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;
-    $justifyContent?: "end" | "start" | "center" | "space-between" | "space-around" | "space-evenly" | "stretch" | undefined;
-    $justifyItems?: "end" | "start" | "center" | "stretch" | "baseline" | undefined;
-    $margin?: StrNum | CssBoxSides<StrNum> | undefined;
-    $padding?: StrNum | CssBoxSides<StrNum> | undefined;
-    $placeItems?: "end" | "start" | "center" | "stretch" | undefined;
+    $justifyItems?: ItemAlignmentValue | undefined;
+    $placeItems?: ItemAlignmentValue | undefined;
 } & {
     $gridAutoFlow: string;
 }, "$gridAutoFlow">;
-export declare const Vertical: import("styled-components").StyledComponent<"div", any, {
-    $alignContent?: "end" | "start" | "center" | "space-between" | "space-around" | "space-evenly" | "stretch" | undefined;
-    $alignItems?: "end" | "start" | "center" | "stretch" | "baseline" | undefined;
-    $bgColor?: string | undefined;
-    $border?: string | CssBoxSides<string> | undefined;
-    $borderRadius?: StrNum | undefined;
-    $boxShadow?: string | undefined;
+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;
-    $justifyContent?: "end" | "start" | "center" | "space-between" | "space-around" | "space-evenly" | "stretch" | undefined;
-    $justifyItems?: "end" | "start" | "center" | "stretch" | "baseline" | undefined;
-    $margin?: StrNum | CssBoxSides<StrNum> | undefined;
-    $padding?: StrNum | CssBoxSides<StrNum> | undefined;
-    $placeItems?: "end" | "start" | "center" | "stretch" | undefined;
+    $justifyItems?: ItemAlignmentValue | undefined;
+    $placeItems?: ItemAlignmentValue | undefined;
 } & {
     $gridAutoFlow: string;
 }, "$gridAutoFlow">;
-export {};

package/grid.js

@@ -1,38 +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};`;
+const gridDeclarations = {
+  ...commonContainerDeclarations,
+  $gridAutoFlow: {
+    property: 'grid-auto-flow'
+  },
+  $justifyItems: {
+    property: 'justify-items'
+  },
+  $placeItems: {
+    property: 'place-items'
   }
-  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 renderGridCss = renderDeclarations(gridDeclarations);
 export const GridContainer = styled.div.withConfig({
   displayName: "GridContainer",
   componentId: "sc-1mpmh7u-0"
-})(["display:grid;", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", ""], props => createCssDeclaration('align-content', props.$alignContent), props => createCssDeclaration('align-items', props.$alignItems), props => createCssDeclaration('background-color', props.$bgColor), props => createCssBoxDeclaration('border', props.$border), props => createCssDeclaration('border-radius', props.$borderRadius, toCssValue), props => createCssDeclaration('box-shadow', props.$boxShadow), props => createCssDeclaration('gap', props.$gap, toCssValue), props => createCssDeclaration('grid-auto-flow', props.$gridAutoFlow), props => createCssDeclaration('justify-content', props.$justifyContent), props => createCssDeclaration('justify-items', props.$justifyItems), props => createCssBoxDeclaration('margin', props.$margin, toCssValue), props => createCssBoxDeclaration('padding', props.$padding, toCssValue), props => createCssDeclaration('place-items', props.$placeItems));
+})(["display:grid;", ""], renderGridCss);
 export const Columns = styled(GridContainer).withConfig({
   displayName: "Columns",
   componentId: "sc-1mpmh7u-1"

package/index.d.ts

@@ -1,4 +1,5 @@
 export * from './grid';
+export * from './flex';
 export * from './expand';
 export * from './hooks/useClickAway';
 export { identifyOpenReplaySession } from './analytics/identifyOpenReplay';

package/index.js

@@ -1,4 +1,5 @@
 export * from './grid';
+export * from './flex';
 export * from './expand';
 export * from './hooks/useClickAway';
 export { identifyOpenReplaySession } from './analytics/identifyOpenReplay';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pushwoosh/kit-helpers",
-  "version": "4.9.2",
+  "version": "4.11.0",
   "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');