@janbox/storefront-ui 2.0.29 → 2.0.31

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. package/README.md +692 -0
  2. package/dist/lib/accordion/README.md +81 -0
  3. package/dist/lib/avatar/README.md +74 -0
  4. package/dist/lib/badge/README.md +58 -0
  5. package/dist/lib/box/README.md +69 -0
  6. package/dist/lib/breadcrumbs/README.md +70 -0
  7. package/dist/lib/button/README.md +115 -0
  8. package/dist/lib/cascader/README.md +128 -0
  9. package/dist/lib/checkbox/README.md +74 -0
  10. package/dist/lib/checkbox/checkbox.js +107 -12
  11. package/dist/lib/checkbox/types.d.ts +2 -2
  12. package/dist/lib/chip/README.md +72 -0
  13. package/dist/lib/collapse/README.md +78 -0
  14. package/dist/lib/container/README.md +59 -0
  15. package/dist/lib/count-up/README.md +52 -0
  16. package/dist/lib/countdown-timer/README.md +77 -0
  17. package/dist/lib/date-picker/README.md +94 -0
  18. package/dist/lib/dialog/README.md +109 -0
  19. package/dist/lib/drawer/README.md +97 -0
  20. package/dist/lib/filter-panel/README.md +146 -0
  21. package/dist/lib/flag/README.md +58 -0
  22. package/dist/lib/flexbox/README.md +59 -0
  23. package/dist/lib/floating/README.md +109 -0
  24. package/dist/lib/form-helper-text/README.md +54 -0
  25. package/dist/lib/form-label/README.md +50 -0
  26. package/dist/lib/grid/README.md +72 -0
  27. package/dist/lib/highlight-words/README.md +64 -0
  28. package/dist/lib/highlight-words/highlight-words.js +1 -2
  29. package/dist/lib/icon/README.md +69 -0
  30. package/dist/lib/icon-button/README.md +92 -0
  31. package/dist/lib/image/README.md +80 -0
  32. package/dist/lib/input/README.md +118 -0
  33. package/dist/lib/input-mask/README.md +88 -0
  34. package/dist/lib/input-number/README.md +92 -0
  35. package/dist/lib/input-range/README.md +85 -0
  36. package/dist/lib/lightbox/README.md +107 -0
  37. package/dist/lib/linear-progress/README.md +54 -0
  38. package/dist/lib/link/README.md +67 -0
  39. package/dist/lib/loading/README.md +65 -0
  40. package/dist/lib/marquee/README.md +83 -0
  41. package/dist/lib/marquee/marquee/marquee.js +1 -1
  42. package/dist/lib/menu/README.md +92 -0
  43. package/dist/lib/multiple-select/README.md +108 -0
  44. package/dist/lib/nav-link/README.md +61 -0
  45. package/dist/lib/notifications/README.md +103 -0
  46. package/dist/lib/otp-input/README.md +71 -0
  47. package/dist/lib/pagination/README.md +84 -0
  48. package/dist/lib/phone-input/README.md +80 -0
  49. package/dist/lib/popover/README.md +93 -0
  50. package/dist/lib/price-label/README.md +78 -0
  51. package/dist/lib/primitive/README.md +80 -0
  52. package/dist/lib/progress/README.md +50 -0
  53. package/dist/lib/radio-button/README.md +89 -0
  54. package/dist/lib/radio-button/radio-button.js +98 -7
  55. package/dist/lib/ripple-effect/README.md +66 -0
  56. package/dist/lib/select/README.md +124 -0
  57. package/dist/lib/star-rating/README.md +67 -0
  58. package/dist/lib/stepper/README.md +99 -0
  59. package/dist/lib/suspense-query/README.md +78 -0
  60. package/dist/lib/swiper/README.md +99 -0
  61. package/dist/lib/switch/README.md +73 -0
  62. package/dist/lib/switch/switch.d.ts +1 -1
  63. package/dist/lib/switch/switch.js +110 -11
  64. package/dist/lib/table/README.md +115 -0
  65. package/dist/lib/tabs/README.md +103 -0
  66. package/dist/lib/text/README.md +59 -0
  67. package/dist/lib/textarea/README.md +76 -0
  68. package/dist/lib/time-picker/README.md +100 -0
  69. package/dist/lib/tooltip/README.md +106 -0
  70. package/dist/lib/unordered-list/README.md +85 -0
  71. package/dist/lib/video/README.md +88 -0
  72. package/dist/style.css +1 -244
  73. package/package.json +5 -5
  74. package/dist/lib/checkbox/checkbox.module.scss.js +0 -23
  75. package/dist/lib/radio-button/radio-button.module.scss.js +0 -17
  76. package/dist/lib/switch/switch.module.scss.js +0 -14
@@ -0,0 +1,81 @@
1
+ # Accordion
2
+
3
+ Component panel nội dung có thể thu gọn, hiển thị hoặc ẩn nội dung khi người dùng click vào phần summary. Hỗ trợ cả controlled và uncontrolled open state, có thể kết hợp với AccordionGroup để kiểm soát hành vi mở đơn hoặc nhiều panel cùng lúc.
4
+
5
+ ## Import
6
+
7
+ ```tsx
8
+ import { Accordion } from '@janbox/storefront-ui';
9
+ ```
10
+
11
+ ## Props
12
+
13
+ | Prop | Type | Default | Description |
14
+ |------|------|---------|-------------|
15
+ | `open` | `boolean` | - | Controlled open state. Khi được cung cấp, component chuyển sang controlled mode. |
16
+ | `defaultOpen` | `boolean` | `false` | Trạng thái mở ban đầu cho uncontrolled usage. |
17
+ | `onOpenChange` | `(open: boolean) => void` | - | Callback được gọi khi trạng thái mở thay đổi. |
18
+ | `children` | `React.ReactNode` | - | Nội dung accordion — thường là AccordionSummary và AccordionContent. |
19
+ | `sx` | `ToResponsiveProps<StyledCSS>` | - | Responsive style overrides thông qua sx prop (kế thừa từ PrimitiveProps). |
20
+ | `className` | `string` | - | CSS class names bổ sung áp dụng cho root div. |
21
+ | `ref` | `React.Ref<HTMLDivElement>` | - | Forwarded ref tới root div element. |
22
+
23
+ ## Examples
24
+
25
+ ### Default (uncontrolled)
26
+
27
+ ```tsx
28
+ <Accordion style={{ width: 400 }}>
29
+ <AccordionSummary>What is React?</AccordionSummary>
30
+ <AccordionContent>
31
+ React is a JavaScript library for building user interfaces.
32
+ </AccordionContent>
33
+ </Accordion>
34
+ ```
35
+
36
+ ### Default open
37
+
38
+ ```tsx
39
+ <Accordion defaultOpen style={{ width: 400 }}>
40
+ <AccordionSummary>What is React?</AccordionSummary>
41
+ <AccordionContent>
42
+ React is a JavaScript library for building user interfaces.
43
+ </AccordionContent>
44
+ </Accordion>
45
+ ```
46
+
47
+ ### Group with single open mode
48
+
49
+ ```tsx
50
+ <AccordionGroup openMode="single" style={{ width: 400 }}>
51
+ <Accordion>
52
+ <AccordionSummary>Section 1</AccordionSummary>
53
+ <AccordionContent>Content for section 1</AccordionContent>
54
+ </Accordion>
55
+ <Accordion>
56
+ <AccordionSummary>Section 2</AccordionSummary>
57
+ <AccordionContent>Content for section 2</AccordionContent>
58
+ </Accordion>
59
+ <Accordion>
60
+ <AccordionSummary>Section 3</AccordionSummary>
61
+ <AccordionContent>Content for section 3</AccordionContent>
62
+ </Accordion>
63
+ </AccordionGroup>
64
+ ```
65
+
66
+ ## Related Components
67
+
68
+ - [Icon](../icon/README.md)
69
+ - [Primitive](../primitive/README.md)
70
+
71
+ ## Dependencies
72
+
73
+ - motion/react
74
+ - @floating-ui/react
75
+ - lodash-es
76
+
77
+ ## See Also
78
+
79
+ - [Component Source](./index.ts)
80
+ - [Storybook Stories](./accordion.stories.tsx)
81
+ - [Main README](../../README.md)
@@ -0,0 +1,74 @@
1
+ # Avatar
2
+
3
+ A circular user avatar component that displays a profile image with graceful fallback to name initials. Supports online status indicators, custom sizing, responsive props, and color variants for the initials background.
4
+
5
+ ## Import
6
+
7
+ ```tsx
8
+ import { Avatar } from '@janbox/storefront-ui';
9
+ ```
10
+
11
+ ## Props
12
+
13
+ | Prop | Type | Default | Description |
14
+ |------|------|---------|-------------|
15
+ | `src` | `string` | - | URL of the avatar image. Falls back to initials if the image fails to load or is not provided. |
16
+ | `name` | `string` | - | User's full name — used to generate initials for the fallback display and as the alt/aria-label for the image. |
17
+ | `status` | `'online' \| 'offline' \| 'busy' \| 'away'` | - | Online status indicator shown as a colored dot in the bottom-right corner of the avatar. |
18
+ | `color` | `ColorVariant` | `'primary'` | Color variant for the initials fallback background. Uses the 600 shade of the specified color. |
19
+ | `size` | `number` | `40` | Width and height of the avatar in pixels. Font size and status dot scale proportionally. |
20
+ | `sm` | `{ size?: number }` | - | Responsive overrides applied at the sm breakpoint (≥768px). |
21
+ | `md` | `{ size?: number }` | - | Responsive overrides applied at the md breakpoint (≥1280px). |
22
+ | `lg` | `{ size?: number }` | - | Responsive overrides applied at the lg breakpoint (≥1680px). |
23
+ | `sx` | `ToResponsiveProps<StyledCSS>` | - | Escape hatch for custom Emotion CSS styles, including responsive overrides via `sx.sm` / `sx.md` / `sx.lg`. |
24
+
25
+ ## Examples
26
+
27
+ ### With image
28
+
29
+ ```tsx
30
+ <Avatar
31
+ src="https://i.pravatar.cc/150?img=3"
32
+ name="Alice Johnson"
33
+ size={40}
34
+ />
35
+ ```
36
+
37
+ ### Initials fallback with status indicator
38
+
39
+ ```tsx
40
+ <Avatar
41
+ name="Bob Smith"
42
+ color="secondary"
43
+ size={48}
44
+ status="online"
45
+ />
46
+ ```
47
+
48
+ ### All status variants
49
+
50
+ ```tsx
51
+ (['online', 'offline', 'busy', 'away'] as const).map((status) => (
52
+ <Avatar
53
+ key={status}
54
+ src="https://i.pravatar.cc/150?img=5"
55
+ name="Diana Ross"
56
+ size={64}
57
+ status={status}
58
+ />
59
+ ))
60
+ ```
61
+
62
+ ## Related Components
63
+
64
+ - [Primitive](../primitive/README.md)
65
+
66
+ ## Dependencies
67
+
68
+ - lodash-es
69
+
70
+ ## See Also
71
+
72
+ - [Component Source](./index.ts)
73
+ - [Storybook Stories](./avatar.stories.tsx)
74
+ - [Main README](../../README.md)
@@ -0,0 +1,58 @@
1
+ # Badge
2
+
3
+ A floating badge component that overlays a count or label on a child element, anchored to its top-end corner. Commonly used to display notification counts, message indicators, or status markers on icons and buttons.
4
+
5
+ ## Import
6
+
7
+ ```tsx
8
+ import { Badge } from '@janbox/storefront-ui';
9
+ ```
10
+
11
+ ## Props
12
+
13
+ | Prop | Type | Default | Description |
14
+ |------|------|---------|-------------|
15
+ | `children*` | `ReactElement<{ ref?: Ref<Element> }>` | - | The anchor element the badge is positioned relative to. Must be a single React element that accepts a ref. |
16
+ | `content` | `number \| string` | - | The content displayed inside the badge bubble. When undefined or null, the badge is hidden. |
17
+ | `color` | `ColorVariant` | `red` | Color variant for the badge background. Accepts any ColorVariant (`'primary' \| 'secondary' \| 'green' \| 'red' \| 'orange' \| 'blue' \| 'neutral'`). |
18
+ | `offset` | `number \| { x?: number; y?: number }` | `0` | Fine-tunes the badge position relative to the anchor corner. A number applies the same offset on both axes; an object allows independent x/y control. |
19
+ | `offsetY` | `number` | - | Legacy vertical offset prop. Prefer using the `offset` prop instead. |
20
+
21
+ *Required props
22
+
23
+ ## Examples
24
+
25
+ ### Default notification badge
26
+
27
+ ```tsx
28
+ <Badge content={5}>
29
+ <span>Notifications</span>
30
+ </Badge>
31
+ ```
32
+
33
+ ### Colored badge on a button
34
+
35
+ ```tsx
36
+ <Badge content={3} color="red">
37
+ <Button>Messages</Button>
38
+ </Badge>
39
+ ```
40
+
41
+ ### Badge with position offset
42
+
43
+ ```tsx
44
+ <Badge content={99} color="primary" offset={{ x: -4, y: 4 }}>
45
+ <IconButton icon={BellIcon} />
46
+ </Badge>
47
+ ```
48
+
49
+ ## Dependencies
50
+
51
+ - @floating-ui/react
52
+ - lodash-es
53
+
54
+ ## See Also
55
+
56
+ - [Component Source](./index.ts)
57
+ - [Storybook Stories](./badge.stories.tsx)
58
+ - [Main README](../../README.md)
@@ -0,0 +1,69 @@
1
+ # Box
2
+
3
+ A general-purpose layout primitive that renders a `div` by default. It supports responsive `sx` styling and an optional `container` mode that applies responsive max-width, horizontal centering, and breakpoint-aware padding.
4
+
5
+ ## Import
6
+
7
+ ```tsx
8
+ import { Box } from '@janbox/storefront-ui';
9
+ ```
10
+
11
+ ## Props
12
+
13
+ | Prop | Type | Default | Description |
14
+ |------|------|---------|-------------|
15
+ | `container` | `boolean` | false | When true, applies responsive container styles: full width, auto horizontal margins, and breakpoint-aware max-width and padding (xs → sm → md → lg). |
16
+ | `sx` | `ToResponsiveProps<StyledCSS>` | - | Responsive Emotion CSS overrides. Accepts a base StyledCSS object plus optional `sm`, `md`, and `lg` breakpoint keys for responsive styles. |
17
+ | `as` | `HTMLElementType` | "div" | Override the rendered HTML element (polymorphic). Defaults to `div`. |
18
+ | `children` | `React.ReactNode` | - | Content rendered inside the Box. |
19
+ | `className` | `string` | - | Additional CSS class names applied to the root element. |
20
+ | `style` | `React.CSSProperties` | - | Inline styles applied to the root element. |
21
+ | `ref` | `React.Ref<HTMLDivElement>` | - | Forwarded ref to the underlying DOM element. |
22
+
23
+ ## Examples
24
+
25
+ ### Basic Box
26
+
27
+ ```tsx
28
+ <Box style={{ padding: 16, border: '1px solid #ccc' }}>
29
+ Box content
30
+ </Box>
31
+ ```
32
+
33
+ ### Container Box
34
+
35
+ ```tsx
36
+ <Box container>
37
+ <h1>Page title</h1>
38
+ <p>Centered, max-width constrained content with responsive padding.</p>
39
+ </Box>
40
+ ```
41
+
42
+ ### Responsive sx styling
43
+
44
+ ```tsx
45
+ <Box
46
+ sx={{
47
+ backgroundColor: 'var(--color-neutral-100)',
48
+ padding: 12,
49
+ md: { padding: 24, display: 'flex', gap: 16 },
50
+ lg: { padding: 32 },
51
+ }}
52
+ >
53
+ Responsive layout
54
+ </Box>
55
+ ```
56
+
57
+ ## Related Components
58
+
59
+ - [Primitive](../primitive/README.md)
60
+
61
+ ## Dependencies
62
+
63
+ - @emotion/react
64
+
65
+ ## See Also
66
+
67
+ - [Component Source](./index.ts)
68
+ - [Storybook Stories](./box.stories.tsx)
69
+ - [Main README](../../README.md)
@@ -0,0 +1,70 @@
1
+ # Breadcrumbs
2
+
3
+ A navigation aid component that displays a hierarchy of links showing the user's current location within the app. It renders BreadcrumbItem children separated by a configurable separator and supports color theming for hover states.
4
+
5
+ ## Import
6
+
7
+ ```tsx
8
+ import { Breadcrumbs } from '@janbox/storefront-ui';
9
+ ```
10
+
11
+ ## Props
12
+
13
+ | Prop | Type | Default | Description |
14
+ |------|------|---------|-------------|
15
+ | `separator` | `string \| IconProps` | `'>'` | The separator rendered between each breadcrumb item. Can be a plain string (e.g. `'>'` or `'/'`) or an IconProps object to render an icon. |
16
+ | `color` | `ColorVariant` | `'primary'` | Controls the hover color of breadcrumb items. Accepts any ColorVariant: `'primary' \| 'secondary' \| 'green' \| 'red' \| 'orange' \| 'blue' \| 'neutral'`. |
17
+ | `children` | `React.ReactNode` | - | BreadcrumbItem elements to render as the navigation trail. Flattened automatically to support wrapping in Fragments. |
18
+ | `BreadcrumbItem.to` | `ReactRouterLinkProps['to']` | - | (BreadcrumbItem prop) The route target passed to react-router Link. |
19
+ | `BreadcrumbItem.icon` | `IconProps` | - | (BreadcrumbItem prop) An optional icon rendered before the item label. |
20
+ | `BreadcrumbItem.underline` | `boolean` | - | (BreadcrumbItem prop, inherited from Link) Whether to show an underline on the link. |
21
+ | `BreadcrumbItem.textVariant` | `TypographySizeVariant` | - | (BreadcrumbItem prop, inherited from Link) Typography size variant for the link text. |
22
+
23
+ ## Examples
24
+
25
+ ### Default
26
+
27
+ ```tsx
28
+ <Breadcrumbs>
29
+ <BreadcrumbItem to="/">Home</BreadcrumbItem>
30
+ <BreadcrumbItem to="/products">Products</BreadcrumbItem>
31
+ <BreadcrumbItem to="/products/detail">Detail</BreadcrumbItem>
32
+ </Breadcrumbs>
33
+ ```
34
+
35
+ ### WithCustomSeparator
36
+
37
+ ```tsx
38
+ <Breadcrumbs separator="/">
39
+ <BreadcrumbItem to="/">Home</BreadcrumbItem>
40
+ <BreadcrumbItem to="/products">Products</BreadcrumbItem>
41
+ <BreadcrumbItem to="/products/detail">Detail</BreadcrumbItem>
42
+ </Breadcrumbs>
43
+ ```
44
+
45
+ ### WithColor
46
+
47
+ ```tsx
48
+ <Breadcrumbs color="primary">
49
+ <BreadcrumbItem to="/">Home</BreadcrumbItem>
50
+ <BreadcrumbItem to="/products">Products</BreadcrumbItem>
51
+ <BreadcrumbItem to="/products/detail">Detail</BreadcrumbItem>
52
+ </Breadcrumbs>
53
+ ```
54
+
55
+ ## Related Components
56
+
57
+ - [Link](../link/README.md)
58
+ - [Icon](../icon/README.md)
59
+
60
+ ## Dependencies
61
+
62
+ - lodash-es
63
+ - react-router
64
+ - @emotion/react
65
+
66
+ ## See Also
67
+
68
+ - [Component Source](./index.ts)
69
+ - [Storybook Stories](./breadcrumbs.stories.tsx)
70
+ - [Main README](../../README.md)
@@ -0,0 +1,115 @@
1
+ # Button
2
+
3
+ A versatile button component that supports multiple variants (contained, outlined, text), colors, sizes, loading states, icons, and navigation through React Router integration. It includes ripple effects for enhanced user interaction feedback.
4
+
5
+ ## Import
6
+
7
+ ```tsx
8
+ import { Button } from '@janbox/storefront-ui';
9
+ ```
10
+
11
+ ## Props
12
+
13
+ | Prop | Type | Default | Description |
14
+ |------|------|---------|-------------|
15
+ | `variant` | `ButtonVariant` | contained | Visual style variant of the button: 'contained' (filled background), 'outlined' (border only), or 'text' (no background) |
16
+ | `color` | `ColorVariant` | primary | Color theme for the button: 'primary', 'secondary', 'green', 'red', 'orange', 'blue', or 'neutral' |
17
+ | `size` | `ButtonSizeVariant` | md | Size variant: 'sm', 'md', or 'lg' (excludes 'xs'). Controls padding, height, and typography |
18
+ | `sm` | `ButtonResponsiveProps` | - | Responsive props override for small screens (≥768px) |
19
+ | `md` | `ButtonResponsiveProps` | - | Responsive props override for medium screens (≥1280px) |
20
+ | `lg` | `ButtonResponsiveProps` | - | Responsive props override for large screens (≥1680px) |
21
+ | `isLoading` | `boolean` | - | Shows loading spinner and disables interaction. Hides button content while loading |
22
+ | `disabled` | `boolean` | - | Disables the button and applies disabled styling |
23
+ | `startIcon` | `IconProps` | - | Icon component props to display before the button text |
24
+ | `endIcon` | `IconProps` | - | Icon component props to display after the button text |
25
+ | `prefix` | `React.ReactNode` | - | Custom content to render before button content (for advanced use cases) |
26
+ | `suffix` | `React.ReactNode` | - | Custom content to render after button content (for advanced use cases) |
27
+ | `anchor` | `RouterNavigateOptions & { to?: LinkProps['to']; target?: LinkProps['target'] }` | - | Navigation configuration using React Router. Supports internal routes and external URLs. Use target='_blank' for new tabs |
28
+ | `sx` | `ToResponsiveProps<StyledCSS>` | - | Custom Emotion CSS styles with responsive breakpoint support |
29
+ | `children` | `React.ReactNode` | - | Button content (text or React elements) |
30
+ | `type` | `string` | button | HTML button type attribute |
31
+ | `onClick` | `(e: React.MouseEvent<HTMLButtonElement>) => void` | - | Click event handler. Called before navigation if anchor is provided |
32
+
33
+ ## Examples
34
+
35
+ ### Basic Button with Variants
36
+
37
+ ```tsx
38
+ import { Button } from '@janbox/storefront-ui';
39
+
40
+ <Button variant="contained" color="primary">
41
+ Click Me
42
+ </Button>
43
+
44
+ <Button variant="outlined" color="secondary">
45
+ Outlined
46
+ </Button>
47
+
48
+ <Button variant="text" color="neutral">
49
+ Text Button
50
+ </Button>
51
+ ```
52
+
53
+ ### Button with Icons and Loading State
54
+
55
+ ```tsx
56
+ import { Button } from '@janbox/storefront-ui';
57
+ import CheckIcon from './icons/check.svg?raw';
58
+ import ArrowIcon from './icons/arrow.svg?raw';
59
+
60
+ <Button
61
+ startIcon={{ source: CheckIcon }}
62
+ endIcon={{ source: ArrowIcon }}
63
+ size="lg"
64
+ >
65
+ Confirm
66
+ </Button>
67
+
68
+ <Button isLoading color="green">
69
+ Processing...
70
+ </Button>
71
+ ```
72
+
73
+ ### Button with Navigation and Responsive Sizing
74
+
75
+ ```tsx
76
+ import { Button } from '@janbox/storefront-ui';
77
+
78
+ <Button
79
+ anchor={{ to: '/dashboard', target: '_self' }}
80
+ size="sm"
81
+ md={{ size: 'md' }}
82
+ lg={{ size: 'lg' }}
83
+ color="blue"
84
+ >
85
+ Go to Dashboard
86
+ </Button>
87
+
88
+ <Button
89
+ anchor={{ to: 'https://example.com', target: '_blank' }}
90
+ variant="outlined"
91
+ >
92
+ External Link
93
+ </Button>
94
+ ```
95
+
96
+ ## Related Components
97
+
98
+ - [Icon](../icon/README.md)
99
+ - [RippleEffect](../ripple-effect/README.md)
100
+ - [Primitive](../primitive/README.md)
101
+
102
+ ## Dependencies
103
+
104
+ - react
105
+ - react-dom
106
+ - @emotion/react
107
+ - react-router
108
+ - lodash-es
109
+ - @floating-ui/react
110
+
111
+ ## See Also
112
+
113
+ - [Component Source](./index.ts)
114
+ - [Storybook Stories](./button.stories.tsx)
115
+ - [Main README](../../README.md)
@@ -0,0 +1,128 @@
1
+ # Cascader
2
+
3
+ A hierarchical selection component that allows users to navigate and select values from nested option trees. Commonly used for category selection, location pickers, or any multi-level data structures where the user drills down through levels to reach a final value.
4
+
5
+ ## Import
6
+
7
+ ```tsx
8
+ import { Cascader } from '@janbox/storefront-ui';
9
+ ```
10
+
11
+ ## Props
12
+
13
+ | Prop | Type | Default | Description |
14
+ |------|------|---------|-------------|
15
+ | `options*` | `CascaderOption[]` | - | Tree options data. Each option can have nested children to form the hierarchy. |
16
+ | `value` | `string[]` | - | Controlled selected path — an array of values from root to the selected leaf node. |
17
+ | `onChange` | `(value: string[], selectedOptions: CascaderOption[]) => void` | - | Callback fired when selection changes. Receives the path as a string array and the corresponding option objects. |
18
+ | `placeholder` | `string` | - | Placeholder text shown when no value is selected. |
19
+ | `searchable` | `boolean` | false | Enable search input within the dropdown to filter options. |
20
+ | `loadOptions` | `(tree: CascaderOption[]) => Promise<CascaderOption[]>` | - | Async function to lazy-load children for a node. Receives the current expanded path as an array of selected options from root to the clicked node. |
21
+ | `placement` | `Placement` | "bottom-start" | Placement of the floating dropdown relative to the trigger. Uses @floating-ui/react Placement type. |
22
+ | `open` | `boolean` | - | Controlled open state of the dropdown. |
23
+ | `onOpenChange` | `UseFloatingOptions['onOpenChange']` | - | Callback when dropdown open state changes. |
24
+ | `separator` | `React.ReactNode` | "/" | Separator used when displaying the selected path in the trigger input. |
25
+ | `valueRenderer` | `ReactNode` | - | Custom renderer for the selected value display inside the trigger. When provided, replaces the default joined path string. |
26
+ | `error` | `boolean` | - | Show error state on the input trigger. |
27
+ | `helperText` | `string` | - | Helper text displayed below the input, typically used to show validation messages. |
28
+ | `fullWidth` | `boolean` | true | Whether the component takes full width of its container. |
29
+ | `lazy` | `boolean` | true | Enable virtualized list rendering for performance with large option sets. |
30
+ | `menuWidth` | `number \| 'exact-reference' \| 'min-reference'` | "exact-reference" | Controls the width of the dropdown menu. 'exact-reference' matches the trigger width exactly, 'min-reference' sets it as the minimum width, or a number for a fixed pixel width. |
31
+ | `size` | `SizeVariant` | "md" | Size variant of the input trigger. Supports responsive values via sm/md/lg breakpoint props. |
32
+ | `listProps` | `HTMLAttributes<HTMLDivElement>` | - | Props forwarded to the options list container element. |
33
+ | `containerProps` | `PropsWithSx<JSX.IntrinsicElements['div']>` | - | Props forwarded to the outer container div. Supports sx prop for responsive styling. |
34
+ | `inputProps` | `InputProps` | - | Props forwarded to the internal search input when searchable is enabled. |
35
+
36
+ *Required props
37
+
38
+ ## Examples
39
+
40
+ ### Basic category selection
41
+
42
+ ```tsx
43
+ const options = [
44
+ {
45
+ value: 'electronics',
46
+ label: 'Electronics',
47
+ children: [
48
+ {
49
+ value: 'phones',
50
+ label: 'Phones',
51
+ children: [
52
+ { value: 'iphone', label: 'iPhone' },
53
+ { value: 'android', label: 'Android' },
54
+ ],
55
+ },
56
+ ],
57
+ },
58
+ {
59
+ value: 'clothing',
60
+ label: 'Clothing',
61
+ children: [
62
+ { value: 'men', label: 'Men' },
63
+ { value: 'women', label: 'Women' },
64
+ ],
65
+ },
66
+ ];
67
+
68
+ <Cascader
69
+ options={options}
70
+ placeholder="Select category..."
71
+ onChange={(value, selectedOptions) => console.log(value, selectedOptions)}
72
+ />
73
+ ```
74
+
75
+ ### Searchable with controlled value and error state
76
+
77
+ ```tsx
78
+ const [value, setValue] = useState<string[]>([]);
79
+
80
+ <Cascader
81
+ options={options}
82
+ value={value}
83
+ onChange={(path) => setValue(path)}
84
+ searchable
85
+ placeholder="Search and select..."
86
+ error={value.length === 0}
87
+ helperText={value.length === 0 ? 'Please select a category' : undefined}
88
+ />
89
+ ```
90
+
91
+ ### Async lazy-loading children
92
+
93
+ ```tsx
94
+ const loadOptions = async (tree: CascaderOption[]) => {
95
+ const lastSelected = tree[tree.length - 1];
96
+ const children = await fetchCategoryChildren(lastSelected.value);
97
+ return children.map((c) => ({ value: c.id, label: c.name, isLeaf: !c.hasChildren }));
98
+ };
99
+
100
+ <Cascader
101
+ options={topLevelOptions}
102
+ loadOptions={loadOptions}
103
+ placeholder="Select location..."
104
+ onChange={(value) => console.log('Selected path:', value)}
105
+ menuWidth="min-reference"
106
+ />
107
+ ```
108
+
109
+ ## Related Components
110
+
111
+ - [InputMask](../inputmask/README.md)
112
+ - [Floating](../floating/README.md)
113
+ - [FloatingContent](../floatingcontent/README.md)
114
+ - [FloatingTrigger](../floatingtrigger/README.md)
115
+ - [FormHelperText](../formhelpertext/README.md)
116
+ - [Input](../input/README.md)
117
+ - [TextSkeleton](../loading/README.md)
118
+
119
+ ## Dependencies
120
+
121
+ - @floating-ui/react
122
+ - lodash-es
123
+
124
+ ## See Also
125
+
126
+ - [Component Source](./index.ts)
127
+ - [Storybook Stories](./cascader.stories.tsx)
128
+ - [Main README](../../README.md)
@@ -0,0 +1,74 @@
1
+ # Checkbox
2
+
3
+ A styled checkbox input component that supports color variants, indeterminate state, and a container label wrapper. Suitable for form fields, multi-select lists, and toggle interactions where a three-state (checked/unchecked/indeterminate) checkbox is needed.
4
+
5
+ ## Import
6
+
7
+ ```tsx
8
+ import { Checkbox } from '@janbox/storefront-ui';
9
+ ```
10
+
11
+ ## Props
12
+
13
+ | Prop | Type | Default | Description |
14
+ |------|------|---------|-------------|
15
+ | `color` | `ColorVariant` | "primary" | Color variant for the checkbox. Controls the checked/focus color using design tokens. |
16
+ | `indeterminate` | `boolean` | false | When true, sets the checkbox to an indeterminate state (shows a minus icon). The checked prop is ignored when this is set. See https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/indeterminate |
17
+ | `containerProps` | `PrimitiveProps<JSX.IntrinsicElements['label']>` | - | Props forwarded to the outer <label> wrapper (Primitive as='label'). Supports sx prop for responsive styling. |
18
+ | `children` | `React.ReactNode` | - | Label content rendered next to the checkbox. |
19
+ | `className` | `string` | - | Additional CSS class applied to the underlying <input> element. |
20
+ | `ref` | `React.Ref<HTMLInputElement>` | - | Forwarded ref to the underlying <input type='checkbox'> element. Merged internally with an internal ref used for the indeterminate effect. |
21
+ | `disabled` | `boolean` | - | Disables the checkbox input. Inherited from JSX.IntrinsicElements['input']. |
22
+ | `checked` | `boolean` | - | Controlled checked state. Inherited from JSX.IntrinsicElements['input']. |
23
+ | `defaultChecked` | `boolean` | - | Uncontrolled default checked state. Inherited from JSX.IntrinsicElements['input']. |
24
+ | `onChange` | `React.ChangeEventHandler<HTMLInputElement>` | - | Change event handler. Inherited from JSX.IntrinsicElements['input']. |
25
+
26
+ ## Examples
27
+
28
+ ### Default unchecked checkbox
29
+
30
+ ```tsx
31
+ <Checkbox onChange={(e) => console.log(e.target.checked)} />
32
+ ```
33
+
34
+ ### Checked with error color and label
35
+
36
+ ```tsx
37
+ <Checkbox color="red" defaultChecked>
38
+ Accept terms and conditions
39
+ </Checkbox>
40
+ ```
41
+
42
+ ### Indeterminate state for select-all pattern
43
+
44
+ ```tsx
45
+ const [selected, setSelected] = React.useState<string[]>([]);
46
+ const allItems = ['a', 'b', 'c'];
47
+ const allChecked = selected.length === allItems.length;
48
+ const someChecked = selected.length > 0 && !allChecked;
49
+
50
+ <Checkbox
51
+ indeterminate={someChecked}
52
+ checked={allChecked}
53
+ onChange={(e) =>
54
+ setSelected(e.target.checked ? allItems : [])
55
+ }
56
+ >
57
+ Select all
58
+ </Checkbox>
59
+ ```
60
+
61
+ ## Related Components
62
+
63
+ - [SvgLoader](../svgloader/README.md)
64
+ - [Primitive](../primitive/README.md)
65
+
66
+ ## Dependencies
67
+
68
+ - @floating-ui/react
69
+
70
+ ## See Also
71
+
72
+ - [Component Source](./index.ts)
73
+ - [Storybook Stories](./checkbox.stories.tsx)
74
+ - [Main README](../../README.md)