@janbox/storefront-ui 2.0.29 → 2.0.30

package/dist/lib/dialog/README.md

@@ -0,0 +1,109 @@
+# Dialog
+
+A modal dialog component built on top of the Floating primitive, used to display overlay content that requires user attention or interaction. It supports responsive sizing, a backdrop overlay with blur, scroll lock, and composable sub-components (DialogHeader, DialogBody, DialogFooter, DialogClose) for flexible layout.
+
+## Import
+
+```tsx
+import { Dialog } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `size` | `DialogSize (keyof typeof breakpoint \| number)` | `'sm'` | Controls the width of the dialog panel. Accepts breakpoint keys (`'xs' \| 'sm' \| 'md' \| 'lg'`) mapped to pixel values, or an explicit pixel number. `'xs'` maps to 480px; other keys use the breakpoint minWidth. |
+| `sm` | `{ size?: DialogSize }` | - | Responsive override for the dialog size at the sm breakpoint (≥768px). |
+| `md` | `{ size?: DialogSize }` | - | Responsive override for the dialog size at the md breakpoint (≥1280px). |
+| `lg` | `{ size?: DialogSize }` | - | Responsive override for the dialog size at the lg breakpoint (≥1680px). |
+| `open` | `boolean` | - | Controlled open state of the dialog. When provided, the component becomes controlled. |
+| `onOpenChange` | `UseFloatingOptions['onOpenChange']` | - | Callback fired when the open state changes (e.g., when the user dismisses the dialog). |
+| `placement` | `Placement` | - | Floating UI placement for the dialog panel. Inherited from FloatingProps. |
+| `clickProps` | `UseClickProps` | - | Options passed to the floating-ui useClick interaction hook. |
+| `dismissProps` | `UseDismissProps` | `{ enabled: true }` | Options for the floating-ui useDismiss hook. Dismiss on outside click/Escape is enabled by default. |
+| `hoverProps` | `UseHoverProps` | - | Options passed to the floating-ui useHover interaction hook. |
+| `focusProps` | `UseFocusProps` | - | Options passed to the floating-ui useFocus interaction hook. |
+| `offsetOptions` | `OffsetOptions` | - | Offset configuration for floating-ui positioning. |
+| `sizeOptions` | `SizeOptions` | - | Size middleware options for floating-ui. |
+| `autoUpdateOptions` | `AutoUpdateOptions` | - | Options for floating-ui autoUpdate (controls when position recalculates). |
+| `elements` | `UseFloatingOptions['elements']` | - | Custom reference/floating element overrides for floating-ui. |
+| `ref` | `React.Ref<FloatingRef>` | - | Ref forwarded to the underlying floating-ui UseFloatingReturn object. |
+| `children` | `React.ReactNode` | - | Dialog content. Should include a FloatingTrigger and one or more of DialogHeader, DialogBody, DialogFooter. |
+
+## Examples
+
+### Default dialog with header, body, and footer
+
+```tsx
+<Dialog>
+  <FloatingTrigger>
+    <button>Open Dialog</button>
+  </FloatingTrigger>
+  <DialogHeader closeable>Dialog Title</DialogHeader>
+  <DialogBody>
+    <p>This is the dialog body content.</p>
+  </DialogBody>
+  <DialogFooter>
+    <button>Cancel</button>
+    <button>Confirm</button>
+  </DialogFooter>
+</Dialog>
+```
+
+### Small dialog without footer
+
+```tsx
+<Dialog size="sm">
+  <FloatingTrigger>
+    <button>Open Small Dialog</button>
+  </FloatingTrigger>
+  <DialogHeader closeable>Small Dialog</DialogHeader>
+  <DialogBody>
+    <p>Small dialog content.</p>
+  </DialogBody>
+</Dialog>
+```
+
+### Controlled dialog with responsive sizing
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Dialog
+  open={open}
+  onOpenChange={setOpen}
+  size="xs"
+  md={{ size: 'md' }}
+  lg={{ size: 'lg' }}
+>
+  <FloatingTrigger>
+    <button onClick={() => setOpen(true)}>Open</button>
+  </FloatingTrigger>
+  <DialogHeader closeable>Responsive Dialog</DialogHeader>
+  <DialogBody>
+    <p>Width changes at each breakpoint.</p>
+  </DialogBody>
+</Dialog>
+```
+
+## Related Components
+
+- [Floating](../floating/README.md)
+- [FloatingContent](../floatingcontent/README.md)
+- [FloatingClose](../floatingclose/README.md)
+- [DialogHeader](../dialogheader/README.md)
+- [DialogBody](../dialogbody/README.md)
+- [DialogFooter](../dialogfooter/README.md)
+- [DialogClose](../dialogclose/README.md)
+- [IconButton](../iconbutton/README.md)
+- [ScrollView](../scrollview/README.md)
+
+## Dependencies
+
+- @floating-ui/react
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./dialog.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/drawer/README.md

@@ -0,0 +1,97 @@
+# Drawer
+
+A slide-in panel component that animates in from a configurable edge (left, right, top, or bottom) of the screen. Built on top of the Floating system, it provides overlay backdrop, scroll locking, and dismiss-on-click-outside behavior out of the box.
+
+## Import
+
+```tsx
+import { Drawer } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `placement` | `'left' \| 'right' \| 'top' \| 'bottom'` | `'left'` | The edge from which the drawer slides in. |
+| `open` | `boolean` | - | Controlled open state of the drawer. |
+| `onOpenChange` | `(open: boolean, event?: Event, reason?: OpenChangeReason) => void` | - | Callback fired when the open state changes (e.g. user dismisses the drawer). |
+| `children` | `React.ReactNode` | - | Drawer content. Should include a `FloatingTrigger` to open the drawer and a `DrawerClose` to close it. The panel content (rendered inside the sliding pane) is placed as siblings to `FloatingTrigger`. |
+| `clickProps` | `UseClickProps` | - | Options forwarded to `@floating-ui/react` `useClick` interaction hook. |
+| `dismissProps` | `UseDismissProps` | - | Options forwarded to `@floating-ui/react` `useDismiss` hook. Dismiss on outside click is enabled by default. |
+| `hoverProps` | `UseHoverProps` | - | Options forwarded to `@floating-ui/react` `useHover` interaction hook. |
+| `focusProps` | `UseFocusProps` | - | Options forwarded to `@floating-ui/react` `useFocus` interaction hook. |
+| `offsetOptions` | `OffsetOptions` | - | Offset distance between trigger and floating content, forwarded to `@floating-ui/react`. |
+| `sizeOptions` | `SizeOptions` | - | Size middleware options forwarded to `@floating-ui/react`. |
+| `autoUpdateOptions` | `AutoUpdateOptions` | - | Options for the `autoUpdate` utility from `@floating-ui/react`. |
+| `elements` | `UseFloatingOptions['elements']` | - | Custom reference/floating elements override for the floating context. |
+| `ref` | `React.Ref<FloatingRef>` | - | Ref forwarded to the underlying Floating context (`UseFloatingReturn`). |
+
+## Examples
+
+### Right-side drawer
+
+```tsx
+<Drawer placement="right">
+  <FloatingTrigger>
+    <button>Open</button>
+  </FloatingTrigger>
+  <div style={{ padding: 24, width: 320 }}>
+    <DrawerClose>
+      <button>✕ Close</button>
+    </DrawerClose>
+    <h3>Settings</h3>
+    <p>Panel content goes here.</p>
+  </div>
+</Drawer>
+```
+
+### Bottom drawer (mobile sheet pattern)
+
+```tsx
+<Drawer placement="bottom">
+  <FloatingTrigger>
+    <button>Open Sheet</button>
+  </FloatingTrigger>
+  <div style={{ padding: 24 }}>
+    <DrawerClose>
+      <button>Dismiss</button>
+    </DrawerClose>
+    <p>Bottom sheet content.</p>
+  </div>
+</Drawer>
+```
+
+### Controlled drawer
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<>
+  <button onClick={() => setOpen(true)}>Open</button>
+  <Drawer placement="left" open={open} onOpenChange={setOpen}>
+    <div style={{ width: 280, padding: 24 }}>
+      <DrawerClose>
+        <button>Close</button>
+      </DrawerClose>
+      <p>Controlled drawer panel.</p>
+    </div>
+  </Drawer>
+</>
+```
+
+## Related Components
+
+- [Floating](../floating/README.md)
+- [FloatingContent](../floatingcontent/README.md)
+- [FloatingClose](../floatingclose/README.md)
+
+## Dependencies
+
+- `motion/react`
+- `@floating-ui/react`
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./drawer.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/filter-panel/README.md

@@ -0,0 +1,146 @@
+# FilterPanel
+
+Component bộ lọc có thể thu/mở, dùng trong giao diện lọc sản phẩm e-commerce. Hỗ trợ bốn loại field — checkbox, radio, price-range, và input-text — được render bên trong một toggle collapse có animation.
+
+## Import
+
+```tsx
+import { FilterPanel } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label*` | `ReactNode` | - | Nhãn hiển thị trên nút toggle header. Nhận string hoặc React element bất kỳ. |
+| `fieldType*` | `'checkbox' \| 'radio' \| 'price-range' \| 'input-text'` | - | Xác định loại control filter bên trong được render. Đây là discriminated union key, thay đổi loại props được chấp nhận. |
+| `defaultOpen` | `boolean` | `true` | Panel có mở rộng mặc định hay không. |
+| `className` | `string` | - | CSS class name bổ sung áp dụng lên root element. |
+| `isLoading` | `boolean` | - | Khi `true`, render trạng thái loading bên trong panel. |
+| `options` | `{ label: ReactNode; searchLabel?: string \| string[]; value: string; isChecked?: boolean }[]` | - | Danh sách các option có thể chọn. Bắt buộc khi `fieldType` là `'checkbox'` hoặc `'radio'`. |
+| `value` | `string[] \| string \| { from?: number; to?: number; priceType?: string }` | - | Giá trị controlled. Kiểu phụ thuộc vào `fieldType`: `string[]` cho checkbox, `string` cho radio, object `{ from, to, priceType }` cho price-range. |
+| `onChange` | `(e: React.ChangeEvent<HTMLInputElement>) => void` | - | Handler thay đổi dùng cho `checkbox` và `radio`. |
+| `inputSearchProps` | `ShallowMerge<InputProps, { enabled?: boolean }>` | - | Props cho ô tìm kiếm tùy chọn hiển thị phía trên danh sách option. Có khi `fieldType` là `'checkbox'` hoặc `'radio'`. |
+| `name` | `string` | - | HTML `name` attribute truyền xuống các checkbox. Có khi `fieldType` là `'checkbox'`. |
+| `listProps` | `PropsWithoutRef<JSX.IntrinsicElements['div']>` | - | Props spread lên div container chứa danh sách option. Có khi `fieldType` là `'checkbox'`. |
+| `fallbackValue` | `string` | - | Giá trị mặc định khi không có `value` nào được cung cấp. Có khi `fieldType` là `'radio'`. |
+| `queryParam` | `object` | - | Cấu hình query parameter URL dùng để đồng bộ trạng thái filter với URL. Cấu trúc thay đổi theo `fieldType`. |
+| `placeholder` | `{ from?: string; to?: string } \| string` | - | Placeholder cho các input field. Object `{ from, to }` cho price-range; string cho input-text. |
+| `priceTypes` | `{ label: ReactNode; value: string; isDefault?: boolean }[]` | - | Các option radio để chọn loại giá (VD: giá hiện tại vs. giá gốc). Có khi `fieldType` là `'price-range'`. |
+| `onPriceChange` | `InputRangeProps['onChange']` | - | Handler thay đổi cho các input from/to giá. Có khi `fieldType` là `'price-range'`. |
+| `onPriceTypeChange` | `(e: React.ChangeEvent<HTMLInputElement>) => void` | - | Handler thay đổi cho radio chọn loại giá. Có khi `fieldType` là `'price-range'`. |
+
+*Bắt buộc
+
+## Examples
+
+### Checkbox filter
+
+```tsx
+<FilterPanel
+  label="Danh mục"
+  fieldType="checkbox"
+  options={[
+    { label: 'Điện tử', value: 'electronics' },
+    { label: 'Thời trang', value: 'clothing' },
+    { label: 'Sách', value: 'books' },
+  ]}
+  onChange={(e) => console.log(e.target.value, e.target.checked)}
+/>
+```
+
+### Checkbox filter với tìm kiếm
+
+```tsx
+<FilterPanel
+  label="Thương hiệu"
+  fieldType="checkbox"
+  options={[
+    { label: 'Apple', value: 'apple', searchLabel: 'apple' },
+    { label: 'Samsung', value: 'samsung', searchLabel: 'samsung' },
+    { label: 'Sony', value: 'sony', searchLabel: 'sony' },
+  ]}
+  value={['apple']}
+  inputSearchProps={{ enabled: true, placeholder: 'Tìm thương hiệu...' }}
+  onChange={(e) => console.log(e.target.value, e.target.checked)}
+/>
+```
+
+### Radio filter
+
+```tsx
+<FilterPanel
+  label="Sắp xếp theo"
+  fieldType="radio"
+  value="newest"
+  options={[
+    { label: 'Giá: Thấp đến Cao', value: 'price_asc' },
+    { label: 'Giá: Cao đến Thấp', value: 'price_desc' },
+    { label: 'Mới nhất', value: 'newest' },
+  ]}
+  onChange={(e) => console.log(e.target.value)}
+/>
+```
+
+### Price range filter
+
+```tsx
+<FilterPanel
+  label="Khoảng giá"
+  fieldType="price-range"
+  value={{ from: 10, to: 500 }}
+  placeholder={{ from: 'Giá tối thiểu', to: 'Giá tối đa' }}
+  priceTypes={[
+    { label: 'Giá hiện tại', value: 'current_price', isDefault: true },
+    { label: 'Giá gốc', value: 'original_price' },
+  ]}
+  onPriceChange={(value) => console.log(value)}
+  onPriceTypeChange={(e) => console.log(e.target.value)}
+/>
+```
+
+### Input text filter
+
+```tsx
+<FilterPanel
+  label="Tìm kiếm"
+  fieldType="input-text"
+  placeholder="Nhập từ khóa..."
+  value="áo thun"
+/>
+```
+
+### Panel đóng mặc định
+
+```tsx
+<FilterPanel
+  label="Bộ lọc nâng cao"
+  fieldType="checkbox"
+  defaultOpen={false}
+  options={[
+    { label: 'Có khuyến mãi', value: 'on_sale' },
+    { label: 'Hàng mới về', value: 'new_arrival' },
+  ]}
+  onChange={(e) => console.log(e.target.value, e.target.checked)}
+/>
+```
+
+## Related Components
+
+- [Collapse](../collapse/README.md)
+- [Icon](../icon/README.md)
+- [Checkbox](../checkbox/README.md)
+- [Input](../input/README.md)
+- [InputRange](../input-range/README.md)
+- [RadioButton](../radio-button/README.md)
+- [VirtualizedList](../virtualized-list/README.md)
+
+## Dependencies
+
+- @emotion/react
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./filter-panel.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/flag/README.md

@@ -0,0 +1,58 @@
+# Flag
+
+Hiển thị hình ảnh quốc kỳ từ flagcdn.com dựa trên mã quốc gia ISO 2 ký tự. Tự động fallback về icon địa cầu (hoặc fallback tùy chỉnh) khi không có mã quốc gia hoặc hình ảnh tải thất bại.
+
+## Import
+
+```tsx
+import { Flag } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `countryCode` | `string` | - | Mã quốc gia ISO 3166-1 alpha-2 (ví dụ: `'VN'`, `'JP'`, `'US'`). Dùng để tạo URL hình ảnh từ flagcdn.com. Nếu không truyền, hiển thị ảnh fallback. |
+| `fallback` | `string` | EarthIcon (SVG địa cầu nội bộ) | URL hoặc giá trị hiển thị khi hình ảnh tải thất bại hoặc `countryCode` không được cung cấp. Mặc định là icon địa cầu tích hợp sẵn. |
+| `alt` | `string` | - | Alt text cho thẻ `img`, kế thừa từ phần tử Image/img bên dưới. |
+| `sx` | `ToResponsiveProps<StyledCSS>` | `{ width: 24, aspectRatio: '4 / 3', objectFit: 'contain' }` | Style override responsive qua Emotion sx prop. Mặc định: width 24px, tỉ lệ 4/3, objectFit contain. |
+| `...rest` | `JSX.IntrinsicElements['img']` | - | Tất cả HTML img attributes tiêu chuẩn được forward xuống phần tử img (ví dụ: `className`, `style`, `onClick`, v.v.). |
+
+## Examples
+
+### Quốc kỳ cơ bản
+
+```tsx
+<Flag countryCode="VN" alt="Vietnam" />
+```
+
+### Nhiều quốc kỳ cạnh nhau
+
+```tsx
+<div style={{ display: 'flex', gap: 8 }}>
+  <Flag countryCode="JP" alt="Japan" />
+  <Flag countryCode="US" alt="United States" />
+  <Flag countryCode="VN" alt="Vietnam" />
+</div>
+```
+
+### Kích thước tùy chỉnh và fallback cho mã không hợp lệ
+
+```tsx
+<Flag
+  countryCode="UNKNOWN"
+  fallback="https://example.com/placeholder-flag.svg"
+  alt="Unknown country"
+  sx={{ width: 32 }}
+/>
+```
+
+## Related Components
+
+- [Image](../image/README.md)
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./flag.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/flexbox/README.md

@@ -0,0 +1,59 @@
+# Flexbox
+
+A layout component that renders a `div` with `display: flex` applied by default. It supports responsive `sx` prop overrides and an optional `container` prop that applies the project's responsive container styles for page-level layout use cases.
+
+## Import
+
+```tsx
+import { Flexbox } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `container` | `boolean` | undefined (false) | When true, applies the global `containerStyle` (responsive padding and max-width) on top of the flex display — useful for page-level section wrappers. |
+| `sx` | `ToResponsiveProps<StyledCSS>` | { flexDirection: 'row', alignItems: 'flex-start', justifyContent: 'flex-start' } | Responsive style overrides via the Emotion-powered sx prop. Supports base styles plus `sm`, `md`, and `lg` breakpoint keys. Merged on top of the component defaults (`flexDirection: 'row'`, `alignItems: 'flex-start'`, `justifyContent: 'flex-start'`). |
+| `children` | `React.ReactNode` | - | Child elements rendered inside the flex container — typically `FlexItem` components. |
+| `ref` | `React.Ref<HTMLDivElement>` | - | Forwarded ref to the underlying `div` element. |
+| `...rest` | `JSX.IntrinsicElements['div']` | - | All standard HTML div attributes (className, style, onClick, aria-*, data-*, etc.) are forwarded to the underlying element. |
+
+## Examples
+
+### Default row layout with gap
+
+```tsx
+<Flexbox sx={{ gap: 8 }}>
+  <FlexItem style={{ padding: 8 }}>Item 1</FlexItem>
+  <FlexItem style={{ padding: 8 }}>Item 2</FlexItem>
+  <FlexItem style={{ padding: 8 }}>Item 3</FlexItem>
+</Flexbox>
+```
+
+### Column layout
+
+```tsx
+<Flexbox sx={{ flexDirection: 'column', gap: 8 }}>
+  <FlexItem>Top</FlexItem>
+  <FlexItem>Middle</FlexItem>
+  <FlexItem>Bottom</FlexItem>
+</Flexbox>
+```
+
+### Centered content (both axes)
+
+```tsx
+<Flexbox sx={{ justifyContent: 'center', alignItems: 'center' }} style={{ height: 200 }}>
+  <FlexItem>Centered</FlexItem>
+</Flexbox>
+```
+
+## Related Components
+
+- [Primitive](../primitive/README.md)
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./flexbox.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/floating/README.md

@@ -0,0 +1,109 @@
+# Floating
+
+A compound component system for creating accessible floating UI elements such as tooltips, popovers, dropdowns, and menus. Built on top of @floating-ui/react, it manages positioning, interactions (click, hover, focus, dismiss), and portal rendering with enter/exit animations.
+
+## Import
+
+```tsx
+import { Floating } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `placement` | `Placement` | `'bottom'` | Vị trí của floating element so với trigger. Nhận bất kỳ giá trị `Placement` nào từ @floating-ui/react (VD: `'bottom'`, `'top'`, `'top-start'`, `'right'`, ...). |
+| `open` | `boolean` | - | Controlled open state — kiểm soát trạng thái mở/đóng từ bên ngoài. |
+| `onOpenChange` | `UseFloatingOptions['onOpenChange']` | - | Callback khi trạng thái open thay đổi. Nhận `(open: boolean, event?: Event, reason?: OpenChangeReason)`. |
+| `elements` | `UseFloatingOptions['elements']` | - | DOM elements được quản lý bên ngoài (reference và floating). Dùng cho advanced use cases khi tự quản lý element refs. |
+| `clickProps` | `UseClickProps` | `{ enabled: false }` | Cấu hình cho click interaction hook từ @floating-ui/react. Điều khiển việc click trigger có mở/đóng floating element không. |
+| `dismissProps` | `UseDismissProps` | `{ enabled: false }` | Cấu hình cho dismiss interaction hook. Điều khiển việc click ngoài hoặc nhấn Escape có đóng floating element không. |
+| `hoverProps` | `UseHoverProps` | `{ enabled: false }` | Cấu hình cho hover interaction hook. Điều khiển việc hover trigger có mở floating element không. |
+| `focusProps` | `UseFocusProps` | `{ enabled: false }` | Cấu hình cho focus interaction hook. Điều khiển việc focus trigger có mở floating element không. |
+| `offsetOptions` | `OffsetOptions` | `4` | Khoảng cách (px) giữa trigger và floating element. Nhận số hoặc `OffsetOptions` object. |
+| `sizeOptions` | `SizeOptions` | - | Cấu hình cho size middleware. Component cung cấp sẵn `apply` function giới hạn height/width theo viewport khả dụng. |
+| `autoUpdateOptions` | `AutoUpdateOptions` | - | Cấu hình cho `autoUpdate` từ @floating-ui/react. Kiểm soát các event kích hoạt tính lại vị trí (scroll, resize, ...). |
+| `children` | `React.ReactNode` | - | Nội dung của compound component. Nên chứa `FloatingTrigger` và `FloatingContent` là children trực tiếp hoặc lồng nhau. |
+| `ref` | `React.Ref<FloatingRef>` | - | Ref expose `UseFloatingReturn` object, cho phép truy cập floating context, refs, và positioning data. |
+
+## Examples
+
+### Controlled popover với click-to-open và dismiss
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Floating
+  open={open}
+  onOpenChange={setOpen}
+  clickProps={{ enabled: true }}
+  dismissProps={{ enabled: true }}
+>
+  <FloatingTrigger>
+    <button>Open Popover</button>
+  </FloatingTrigger>
+  <FloatingContent>
+    <div style={{ padding: 16, background: 'white', border: '1px solid #ccc', borderRadius: 8 }}>
+      Popover content
+    </div>
+  </FloatingContent>
+</Floating>
+```
+
+### Tooltip khi hover với placement top
+
+```tsx
+<Floating placement="top" hoverProps={{ enabled: true }}>
+  <FloatingTrigger>
+    <button>Hover me</button>
+  </FloatingTrigger>
+  <FloatingContent>
+    <div style={{ padding: '4px 8px', background: '#333', color: '#fff', borderRadius: 4, fontSize: 12 }}>
+      Tooltip text
+    </div>
+  </FloatingContent>
+</Floating>
+```
+
+### Dropdown menu với FloatingClose
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Floating
+  open={open}
+  onOpenChange={setOpen}
+  placement="bottom-start"
+  clickProps={{ enabled: true }}
+  dismissProps={{ enabled: true }}
+>
+  <FloatingTrigger>
+    <button>Actions</button>
+  </FloatingTrigger>
+  <FloatingContent>
+    <ul style={{ listStyle: 'none', margin: 0, padding: '4px 0', background: 'white', border: '1px solid #eee', borderRadius: 8 }}>
+      <li>
+        <FloatingClose>
+          <button style={{ display: 'block', width: '100%', padding: '8px 16px', textAlign: 'left' }}>Edit</button>
+        </FloatingClose>
+      </li>
+      <li>
+        <FloatingClose>
+          <button style={{ display: 'block', width: '100%', padding: '8px 16px', textAlign: 'left' }}>Delete</button>
+        </FloatingClose>
+      </li>
+    </ul>
+  </FloatingContent>
+</Floating>
+```
+
+## Dependencies
+
+- @floating-ui/react
+- motion/react
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./floating.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/form-helper-text/README.md

@@ -0,0 +1,54 @@
+# FormHelperText
+
+Component hiển thị text hỗ trợ nhỏ bên dưới các form field, dùng để hiển thị hướng dẫn bổ sung hoặc thông báo lỗi validation. Tự động ẩn khi không có nội dung và đổi màu đỏ khi prop `error` được set.
+
+## Import
+
+```tsx
+import { FormHelperText } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `error` | `boolean` | `false` | Khi `true`, render helper text màu đỏ (`--color-red-600`) để chỉ trạng thái lỗi validation. |
+| `children` | `React.ReactNode` | - | Nội dung helper text. Element tự ẩn (`display: none`) khi không có nội dung. |
+| `sx` | `ToResponsiveProps<StyledCSS>` | - | Style override có responsive, truyền qua hệ thống `sx` prop của `Primitive`. |
+| `as` | `React.ElementType` | `"p"` | Override element type (polymorphic), kế thừa từ `PrimitiveProps`. Mặc định là `p`. |
+| `...rest` | `JSX.IntrinsicElements['p']` | - | Tất cả HTML attributes của thẻ `<p>` đều được forward xuống element bên dưới. |
+
+## Examples
+
+### Helper text mặc định
+
+```tsx
+<FormHelperText>This is a helper text</FormHelperText>
+```
+
+### Trạng thái lỗi
+
+```tsx
+<FormHelperText error>This field is required</FormHelperText>
+```
+
+### Kết hợp với input field
+
+```tsx
+<div>
+  <input type="email" placeholder="Enter your email" />
+  <FormHelperText error={!isValid}>
+    {isValid ? 'We will never share your email.' : 'Please enter a valid email address.'}
+  </FormHelperText>
+</div>
+```
+
+## Related Components
+
+- [Primitive](../primitive/README.md)
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./form-helper-text.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/form-label/README.md

@@ -0,0 +1,50 @@
+# FormLabel
+
+A form label wrapper component that renders a label for form fields with optional required indicator. It accepts either a string (auto-wrapped in a `<label>` element) or custom React children, and displays a red asterisk when the field is required.
+
+## Import
+
+```tsx
+import { FormLabel } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `required` | `boolean` | undefined | When true, appends a red asterisk (*) after the label to indicate the associated field is required. |
+| `children` | `React.ReactNode` | undefined | Label content. If a plain string is passed, it is automatically wrapped in a `<label>` element. Custom React nodes are rendered as-is. |
+| `...props` | `JSX.IntrinsicElements['div']` | - | All standard HTML div attributes (className, style, id, onClick, etc.) are forwarded to the root div element. |
+
+## Examples
+
+### Default label
+
+```tsx
+<FormLabel>Email address</FormLabel>
+```
+
+### Required field label
+
+```tsx
+<FormLabel required>Password</FormLabel>
+```
+
+### With custom children and className
+
+```tsx
+<FormLabel required className="custom-label">
+  <label htmlFor="username">Username</label>
+</FormLabel>
+```
+
+## Dependencies
+
+- lodash-es
+- @emotion/react
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./formlabel.stories.tsx)
+- [Main README](../../README.md)