@janbox/storefront-ui 2.0.29 → 2.0.31

package/dist/lib/tabs/README.md

@@ -0,0 +1,103 @@
+# Tabs
+
+A compound tabs component for switching between content panels. It manages active tab state (controlled or uncontrolled) and provides context to sub-components: TabList, Tab, TabContent, TabPanel, and TabIndicator.
+
+## Import
+
+```tsx
+import { Tabs } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `activeIndex` | `number` | - | Controlled active tab index. When provided, the component delegates state management to the parent. |
+| `defaultActiveIndex` | `number` | `0` | Initial active tab index for uncontrolled usage. |
+| `onTabChange` | `(tabIndex: number) => void` | - | Callback fired when the active tab changes, receiving the new tab index. |
+| `tabProps` | `Partial<TabProps>` | `{ color: 'neutral', variant: 'text', states: { active: { color: 'primary', variant: 'text' } } }` | Default props applied to every Tab child. Inactive tabs default to `color='neutral'`, active tab overrides to `color='primary'`. |
+| `tabIndicatorProps` | `TabIndicatorProps` | `{ sx: { height: 2, backgroundColor: 'var(--color-primary-600)' } }` | Props forwarded to the TabIndicator element, cho phép custom `sx` styles trên thanh gạch chân của tab đang active. |
+| `tabPanelProps` | `Partial<TabPanelProps>` | - | Default props applied to every TabPanel child. |
+| `preventActiveTabChange` | `boolean` | `true` | Khi `true`, click vào tab đang active sẽ không re-fire `onTabChange`. |
+| `sx` | `ToResponsiveProps<StyledCSS>` | - | Responsive Emotion CSS overrides cho root wrapper `div`. |
+| `children` * | `React.ReactNode` | - | Phải là composition của `TabList` (chứa các `Tab`) và `TabContent` (chứa các `TabPanel`). |
+
+*Required props
+
+## Examples
+
+### Basic uncontrolled tabs
+
+```tsx
+<Tabs defaultActiveIndex={0} onTabChange={(i) => console.log(i)} style={{ width: 500 }}>
+  <TabList>
+    <Tab>Tab 1</Tab>
+    <Tab>Tab 2</Tab>
+    <Tab>Tab 3</Tab>
+  </TabList>
+  <TabContent>
+    <TabPanel>Content for Tab 1</TabPanel>
+    <TabPanel>Content for Tab 2</TabPanel>
+    <TabPanel>Content for Tab 3</TabPanel>
+  </TabContent>
+</Tabs>
+```
+
+### Controlled tabs with second tab active by default
+
+```tsx
+const [active, setActive] = useState(1);
+
+<Tabs activeIndex={active} onTabChange={setActive} style={{ width: 500 }}>
+  <TabList>
+    <Tab>Overview</Tab>
+    <Tab>Details</Tab>
+    <Tab>Reviews</Tab>
+  </TabList>
+  <TabContent>
+    <TabPanel>Overview content</TabPanel>
+    <TabPanel>Details content</TabPanel>
+    <TabPanel>Reviews content</TabPanel>
+  </TabContent>
+</Tabs>
+```
+
+### Custom tab color and variant via tabProps
+
+```tsx
+<Tabs
+  defaultActiveIndex={0}
+  tabProps={{ color: 'primary', variant: 'text' }}
+  style={{ width: 500 }}
+>
+  <TabList>
+    <Tab>Home</Tab>
+    <Tab>Profile</Tab>
+    <Tab>Settings</Tab>
+  </TabList>
+  <TabContent>
+    <TabPanel>Home content</TabPanel>
+    <TabPanel>Profile content</TabPanel>
+    <TabPanel>Settings content</TabPanel>
+  </TabContent>
+</Tabs>
+```
+
+## Related Components
+
+- [TabList](../tablist/README.md)
+- [Tab](../tab/README.md)
+- [TabContent](../tabcontent/README.md)
+- [TabPanel](../tabpanel/README.md)
+- [TabIndicator](../tabindicator/README.md)
+- [Button](../button/README.md)
+
+## Dependencies
+
+- @emotion/react
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./tabs.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/text/README.md

@@ -0,0 +1,59 @@
+# Text
+
+A polymorphic text component for rendering text content with responsive typography sizing. Supports multiple typography size variants and can render as any HTML element.
+
+## Import
+
+```tsx
+import { Text } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `sizeVariant` | `TypographySizeVariant` | - | Typography size variant. Options: `'xs'` \| `'sm'` \| `'base'` \| `'lg'` \| `'xl'` \| `'2xl'` \| `'3xl'` \| `'4xl'` \| `'5xl'` \| `'6xl'` |
+| `as` | `HTMLElementType` | `p` | HTML element type to render as (e.g., `'p'`, `'span'`, `'div'`, `'h1'`) |
+| `children` | `React.ReactNode` | - | Text content to display |
+| `dangerouslySetInnerHTML` | `{ __html: string }` | - | Renders HTML string directly (use with caution) |
+| `sx` | `ToResponsiveProps<StyledCSS>` | - | Emotion CSS styles with responsive breakpoint support (`sm`, `md`, `lg`) |
+| `sm` | `TextResponsiveProps` | - | Responsive props for small breakpoint (768px+) |
+| `md` | `TextResponsiveProps` | - | Responsive props for medium breakpoint (1280px+) |
+| `lg` | `TextResponsiveProps` | - | Responsive props for large breakpoint (1680px+) |
+
+## Examples
+
+### Basic paragraph text
+
+```tsx
+<Text>Default paragraph text</Text>
+```
+
+### Large heading with custom element
+
+```tsx
+<Text as="h1" sizeVariant="6xl">Main Heading</Text>
+```
+
+### Responsive text sizing
+
+```tsx
+<Text sizeVariant="sm" sm={{ sizeVariant: 'base' }} md={{ sizeVariant: 'lg' }}>
+  Responsive text that grows on larger screens
+</Text>
+```
+
+## Related Components
+
+- [Primitive](../primitive/README.md)
+
+## Dependencies
+
+- @emotion/react
+- lodash-es
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./text.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/textarea/README.md

@@ -0,0 +1,76 @@
+# Textarea
+
+A multi-line text input component with support for debounced onChange, onBlur mode, helper text, error states, and responsive sizing. Wraps a native textarea element with enhanced styling and validation.
+
+## Import
+
+```tsx
+import { Textarea } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `size` | `SizeVariant` | `md` | Size variant controlling padding and typography. Options: `'xs' \| 'sm' \| 'md' \| 'lg'` |
+| `containerProps` | `PropsWithSx<JSX.IntrinsicElements['div']>` | - | Props for the outermost container div wrapper |
+| `mainProps` | `PrimitiveProps<JSX.IntrinsicElements['div']>` | - | Props for the main wrapper div that contains the textarea (includes border, padding, focus states) |
+| `helperText` | `string` | - | Helper text displayed below the textarea (uses FormHelperText component) |
+| `error` | `boolean` | - | Error state - displays red border and renders helperText in error style |
+| `value` | `string` | - | Controlled value for the textarea |
+| `defaultValue` | `string` | - | Uncontrolled default value for the textarea |
+| `mode` | `'onChange' \| 'onBlur'` | `'onChange'` | When to trigger onChange callback. `'onChange'` fires immediately, `'onBlur'` fires when focus leaves the textarea |
+| `debounce` | `number` | `0` | Debounce delay in milliseconds before onChange is called. Also triggers onChange on blur if value changed |
+| `onChange` | `(e: React.ChangeEvent<HTMLTextAreaElement>) => void` | - | Change event handler - respects mode and debounce settings |
+| `placeholder` | `string` | - | Placeholder text for the textarea |
+| `disabled` | `boolean` | - | Disables the textarea (styled with gray background and border) |
+| `readOnly` | `boolean` | - | Makes the textarea read-only (pointer events disabled) |
+| `rows` | `number` | - | Number of visible text rows |
+| `className` | `string` | - | Custom class name applied to the textarea element itself |
+| `sx` | `ToResponsiveProps<StyledCSS>` | - | Responsive Emotion CSS styles (supports `sm`, `md`, `lg` breakpoints) |
+
+## Examples
+
+### Basic Usage
+
+```tsx
+<Textarea placeholder="Enter text..." />
+```
+
+### With Validation
+
+```tsx
+<Textarea
+  placeholder="Enter description..."
+  error={true}
+  helperText="This field is required"
+/>
+```
+
+### Debounced Input
+
+```tsx
+<Textarea
+  placeholder="Search..."
+  debounce={500}
+  onChange={(e) => handleSearch(e.target.value)}
+  helperText="Searches as you type (500ms delay)"
+/>
+```
+
+## Related Components
+
+- [FormHelperText](../formhelpertext/README.md)
+- [Primitive](../primitive/README.md)
+- [Input](../input/README.md)
+
+## Dependencies
+
+- @floating-ui/react
+- lodash-es
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./textarea.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/time-picker/README.md

@@ -0,0 +1,100 @@
+# TimePicker
+
+Input chọn giờ và phút — hiển thị dropdown với hai cột scroll ảo (hours 0–23, minutes 0–59).
+
+## Import
+
+```tsx
+import { TimePicker } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `Date \| null` | - | Giá trị được chọn (controlled) |
+| `defaultValue` | `Date` | - | Giá trị mặc định (uncontrolled) |
+| `onChange` | `(date: Date) => void` | - | Callback khi chọn giờ hoặc phút |
+| `placeholder` | `string` | `'--:--'` | Placeholder text khi chưa chọn |
+| `clearable` | `boolean` | - | Hiện nút clear khi đã có giá trị |
+| `onClear` | `() => void` | - | Callback khi nhấn clear |
+| `disabled` | `boolean` | - | Disable input |
+| `size` | `'sm' \| 'md' \| 'lg'` | - | Kích thước — responsive prop |
+| `placement` | `Placement` | `'bottom-start'` | Vị trí dropdown (từ `@floating-ui/react`) |
+| `open` | `boolean` | - | Controlled open state |
+| `onOpenChange` | `UseFloatingOptions['onOpenChange']` | - | Callback khi dropdown mở/đóng |
+| `containerProps` | `PropsWithSx<JSX.IntrinsicElements['div']>` | - | Props cho container div bên ngoài |
+| `sx` | `ToResponsiveProps<StyledCSS>` | - | Custom styles cho trigger |
+
+## Examples
+
+### Cơ bản — Uncontrolled
+
+```tsx
+import { TimePicker } from '@janbox/storefront-ui';
+
+<TimePicker
+  placeholder="Chọn giờ"
+  onChange={(date) => console.log(date)}
+/>
+```
+
+### Controlled
+
+```tsx
+const [time, setTime] = useState<Date | null>(null);
+
+<TimePicker
+  value={time}
+  onChange={setTime}
+  clearable
+  onClear={() => setTime(null)}
+/>
+```
+
+### Với default value
+
+```tsx
+const defaultTime = new Date();
+defaultTime.setHours(9, 30);
+
+<TimePicker
+  defaultValue={defaultTime}
+  onChange={(date) => console.log(date)}
+/>
+```
+
+### Trong form
+
+```tsx
+<Box sx={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
+  <FormLabel>Giờ mở cửa</FormLabel>
+  <TimePicker
+    value={openTime}
+    onChange={setOpenTime}
+    size="md"
+    clearable
+    onClear={() => setOpenTime(null)}
+  />
+  <FormHelperText>Chọn giờ theo định dạng HH:mm</FormHelperText>
+</Box>
+```
+
+## Notes
+
+- Giá trị trả về là `Date` object — chỉ phần `hour` và `minute` có ý nghĩa, `date` và `month` lấy từ `selectedDate` hiện tại hoặc `new Date()`
+- Dropdown dùng virtualized scroll (`@tanstack/react-virtual`) nên render nhanh dù danh sách dài
+- Hiển thị định dạng `HH:mm` (24 giờ)
+- `size` là responsive prop: có thể override theo breakpoint: `size="md" sm={{ size: 'lg' }}`
+
+## Related Components
+
+- [DatePicker](../date-picker/README.md)
+- [Floating](../floating/README.md)
+- [FormLabel](../form-label/README.md)
+- [FormHelperText](../form-helper-text/README.md)
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Main README](../../README.md)

package/dist/lib/tooltip/README.md

@@ -0,0 +1,106 @@
+# Tooltip
+
+A floating tooltip component that displays contextual information when the user hovers or focuses on a trigger element. Built on top of @floating-ui/react for smart positioning with auto-flip and shift behavior.
+
+## Import
+
+```tsx
+import { Tooltip } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children*` | `ReactElement<T>` | - | The trigger element that the tooltip is anchored to. Must be a single React element that accepts a ref. |
+| `content` | `ReactNode` | - | The content to display inside the tooltip popup. |
+| `placement` | `Placement` | `'top'` | Preferred placement of the tooltip relative to the trigger. Accepts any @floating-ui/react Placement value (e.g. `'top'`, `'bottom'`, `'left'`, `'right'` and their variants). Will auto-flip if there is not enough space. |
+| `open` | `boolean` | - | Controlled open state of the tooltip. |
+| `defaultOpen` | `boolean` | `false` | Initial open state for uncontrolled usage. |
+| `onOpenChange` | `UseFloatingOptions['onOpenChange']` | - | Callback fired when the open state changes. Receives `(open, event, reason)`. |
+| `contentWidth` | `number \| 'fit-parent'` | - | Controls the max-width of the tooltip popup. Use a number for a fixed pixel value, or `'fit-parent'` to match the trigger element's width. |
+| `enable` | `true \| 'truncated'` | `true` | Controls when the tooltip is shown. Set to `'truncated'` to only show the tooltip when the trigger element's text is visually truncated (overflow hidden). |
+| `handleClose` | `UseHoverProps['handleClose'] \| 'safe-polygon'` | - | Custom close handler for hover interactions. Pass `'safe-polygon'` to use the floating-ui safePolygon handler, which keeps the tooltip open when moving the mouse toward it. |
+| `arrowProps` | `Partial<FloatingArrowProps>` | - | Props forwarded to the FloatingArrow component (the small arrow indicator pointing at the trigger). The fill color is automatically set to match the tooltip background. |
+| `className` | `string` | - | Additional CSS class name applied to the tooltip trigger wrapper. |
+
+*Required props
+
+## Examples
+
+### Basic tooltip
+
+```tsx
+<Tooltip content="This is a tooltip">
+  <button>Hover me</button>
+</Tooltip>
+```
+
+### Controlled tooltip with placement
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Tooltip
+  content="Details about this item"
+  placement="bottom"
+  open={open}
+  onOpenChange={setOpen}
+>
+  <span>More info</span>
+</Tooltip>
+```
+
+### Truncated-only tooltip
+
+```tsx
+// Tooltip chỉ hiện khi text bị cắt ngắn (overflow ellipsis)
+<Tooltip
+  content={fullLabelText}
+  enable="truncated"
+  contentWidth="fit-parent"
+>
+  <p style={{ width: 120, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
+    {fullLabelText}
+  </p>
+</Tooltip>
+```
+
+### Tooltip với arrow và safe polygon
+
+```tsx
+// Dùng safe-polygon để tooltip không đóng khi di chuột từ trigger sang tooltip
+<Tooltip
+  content="Thông tin chi tiết"
+  placement="right"
+  handleClose="safe-polygon"
+  arrowProps={{ width: 10, height: 6 }}
+>
+  <button>Chi tiết</button>
+</Tooltip>
+```
+
+### Tooltip với độ rộng cố định
+
+```tsx
+<Tooltip content="Nội dung dài hơn cần giới hạn chiều rộng" contentWidth={200}>
+  <span>Hover để xem</span>
+</Tooltip>
+```
+
+## Related Components
+
+- [Primitive](../primitive/README.md)
+- [FloatingArrow](../floatingarrow/README.md)
+- [FloatingPortal](../floatingportal/README.md)
+
+## Dependencies
+
+- @floating-ui/react
+- lodash-es
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./tooltip.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/unordered-list/README.md

@@ -0,0 +1,85 @@
+# UnorderedList
+
+A polymorphic unordered list container that renders a styled `<ul>` element using the Primitive base component. It lays out its children (`ListItem`) in a vertical flex column, and is typically paired with the `ListItem` component for building structured lists with optional responsive styling via the `sx` prop.
+
+## Import
+
+```tsx
+import { UnorderedList } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `sx` | `ToResponsiveProps<StyledCSS>` | `{ alignItems: 'flex-start' }` | Responsive style overrides using Emotion CSS object. Supports breakpoint keys (`sm`, `md`, `lg`) for responsive values. Merged on top of the default inline-flex column layout. |
+| `as` | `HTMLElementType` | `"ul"` | Polymorphic tag override inherited from Primitive. Defaults to `ul`. |
+| `children` | `React.ReactNode` | - | List content, typically one or more `ListItem` components. |
+| `className` | `string` | - | Additional CSS class names to apply to the root element. |
+| `...rest` | `JSX.IntrinsicElements['ul']` | - | All standard HTML `<ul>` attributes are forwarded to the root element (e.g., `id`, `aria-label`, `onClick`, etc.). |
+
+## Examples
+
+### Default list
+
+```tsx
+<UnorderedList>
+  <ListItem>Item 1</ListItem>
+  <ListItem>Item 2</ListItem>
+  <ListItem>Item 3</ListItem>
+</UnorderedList>
+```
+
+### List with border via sx prop
+
+```tsx
+<UnorderedList
+  sx={{
+    borderStyle: 'solid',
+    borderColor: '#ccc',
+    borderTopWidth: 1,
+    borderBottomWidth: 1,
+    borderLeftWidth: 1,
+    borderRightWidth: 1,
+    borderTopLeftRadius: 8,
+    borderTopRightRadius: 8,
+    borderBottomLeftRadius: 8,
+    borderBottomRightRadius: 8,
+  }}
+>
+  <ListItem>Item 1</ListItem>
+  <ListItem>Item 2</ListItem>
+  <ListItem>Item 3</ListItem>
+</UnorderedList>
+```
+
+### Responsive layout override
+
+```tsx
+<UnorderedList
+  sx={{
+    gap: 8,
+    sm: { flexDirection: 'row', flexWrap: 'wrap' },
+  }}
+>
+  <ListItem>First</ListItem>
+  <ListItem>Second</ListItem>
+  <ListItem>Third</ListItem>
+</UnorderedList>
+```
+
+## Related Components
+
+- [ListItem](../list-item/README.md)
+- [Primitive](../primitive/README.md)
+
+## Dependencies
+
+- `lodash-es`
+- `@emotion/react`
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./unordered-list.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/video/README.md

@@ -0,0 +1,88 @@
+# Video
+
+A wrapper around `react-player` that supports playback of YouTube, Vimeo, Twitch, TikTok, HLS, Dash, and plain HTML5 video URLs. It extends all ReactPlayer props with the project's `sx` responsive styling prop.
+
+## Import
+
+```tsx
+import { Video } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `src` | `string` | - | URL of the video to play. Supports YouTube, Vimeo, Twitch, TikTok, HLS/Dash streams, and direct video file URLs. |
+| `controls` | `boolean` | true | Whether to show native player controls. |
+| `playing` | `boolean` | false | Set to true to start or resume playback, false to pause. |
+| `muted` | `boolean` | false | Mutes the player. Required to be true for autoplay in most browsers. |
+| `width` | `number \| string` | - | Width of the player. Passed directly to the underlying ReactPlayer. |
+| `height` | `number \| string` | - | Height of the player. Passed directly to the underlying ReactPlayer. |
+| `light` | `boolean \| string \| React.ReactElement` | - | When set, renders a lightweight preview thumbnail instead of the full player. Pass true to use the video's default thumbnail, or a URL/element for a custom preview image. |
+| `pip` | `boolean` | - | Enables Picture-in-Picture mode. |
+| `playbackRate` | `number` | - | Sets the playback rate (e.g. 0.5, 1, 1.5, 2). |
+| `volume` | `number` | - | Volume level between 0 and 1. |
+| `poster` | `string` | - | URL for the poster image shown before the video plays (HTML5 video only). |
+| `playsInline` | `boolean` | - | Plays the video inline on mobile devices rather than full screen. |
+| `loop` | `boolean` | - | Whether to loop the video. |
+| `playIcon` | `React.ReactNode` | - | Custom play icon element shown over the preview thumbnail. |
+| `wrapper` | `string \| React.ComponentType<React.HTMLAttributes<HTMLDivElement>>` | - | Custom wrapper element or component for the player container. |
+| `config` | `Config` | - | Player-specific configuration for providers such as youtube, vimeo, twitch, hls, dash, tiktok, spotify, etc. |
+| `onReady` | `() => void` | - | Callback fired when the player is ready. |
+| `onStart` | `(event: SyntheticEvent<HTMLVideoElement>) => void` | - | Callback fired when playback starts. |
+| `onClickPreview` | `(event: React.SyntheticEvent) => void` | - | Callback fired when the user clicks the preview thumbnail. |
+| `sx` | `ToResponsiveProps<StyledCSS>` | - | Responsive Emotion CSS overrides applied to the player wrapper element. |
+
+## Examples
+
+### Basic YouTube embed
+
+```tsx
+<Video
+  src="https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+  width={640}
+  height={360}
+/>
+```
+
+### Autoplay muted video
+
+```tsx
+<Video
+  src="https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+  width={640}
+  height={360}
+  playing
+  muted
+/>
+```
+
+### Lightweight preview with custom thumbnail
+
+```tsx
+<Video
+  src="https://vimeo.com/123456789"
+  width={800}
+  height={450}
+  light="https://example.com/thumbnail.jpg"
+  controls
+  config={{
+    vimeo: { byline: false, portrait: false }
+  }}
+/>
+```
+
+## Related Components
+
+- [Icon](../icon/README.md)
+- [Primitive](../primitive/README.md)
+
+## Dependencies
+
+- react-player
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./video.stories.tsx)
+- [Main README](../../README.md)