@janbox/storefront-ui 2.0.29 → 2.0.31

package/dist/lib/input-number/README.md

@@ -0,0 +1,92 @@
+# InputNumber
+
+A numeric input field that extends the base Input component with number-specific constraints and optional increment/decrement controls. Use it when you need validated numeric entry with min/max bounds, step controls, or decimal precision.
+
+## Import
+
+```tsx
+import { InputNumber } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `number \| string` | - | Controlled value of the input. |
+| `defaultValue` | `number` | - | Uncontrolled initial value. |
+| `min` | `number` | 0 | Minimum allowed value. Defaults to 0. Also suppresses negative sign when min >= 0. |
+| `max` | `number` | Infinity | Maximum allowed value. |
+| `step` | `number` | 0 | Increment/decrement step. When > 0, renders plus and minus IconButton controls in the suffix and prefix slots. |
+| `fractionDigits` | `number \| 'auto'` | 0 | Number of decimal digits to allow. 0 strips decimals entirely; 'auto' allows up to 10 digits. |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | 'md' | Size variant inherited from Input. Supports responsive values via sm/md/lg breakpoint keys. |
+| `error` | `boolean` | false | Renders the input in an error state with red border styling. |
+| `helperText` | `string` | - | Helper or validation message displayed below the input. |
+| `prefix` | `React.ReactNode` | - | Content rendered before the input. Overrides the built-in minus IconButton when step > 0. |
+| `suffix` | `React.ReactNode` | - | Content rendered after the input. Overrides the built-in plus IconButton when step > 0. |
+| `startIcon` | `IconProps` | - | Icon rendered inside the left edge of the input field. |
+| `endIcon` | `IconProps` | - | Icon rendered inside the right edge of the input field. |
+| `mode` | `'onChange' \| 'onBlur'` | 'onChange' | When set to 'onBlur', clamps the value to min on blur rather than on every keystroke. |
+| `debounce` | `number` | - | Debounce delay in milliseconds for the onChange callback. |
+| `transform` | `(value: string) => string` | - | Custom transform function applied to the raw string value after built-in number sanitisation. |
+| `disabled` | `boolean` | false | Disables the input and step controls. |
+| `placeholder` | `string` | - | Placeholder text shown when the input is empty. |
+| `className` | `string` | - | Additional CSS class applied to the input element. |
+| `sx` | `ToResponsiveProps<StyledCSS>` | - | Emotion sx prop for inline responsive styles. |
+| `containerProps` | `PrimitiveProps<JSX.IntrinsicElements['div']>` | - | Props forwarded to the outer wrapper div. |
+| `mainProps` | `PrimitiveProps<JSX.IntrinsicElements['div']>` | - | Props forwarded to the inner main container div. |
+| `onChange` | `React.ChangeEventHandler<HTMLInputElement>` | - | Change event handler. Receives the raw input change event. |
+| `ref` | `React.Ref<HTMLInputElement>` | - | Forwarded ref to the underlying input element. |
+
+## Examples
+
+### Basic numeric input with min/max bounds
+
+```tsx
+<InputNumber
+  min={0}
+  max={100}
+  defaultValue={50}
+  placeholder="0 - 100"
+  onChange={(e) => console.log(e.target.value)}
+/>
+```
+
+### Stepper input with increment/decrement buttons
+
+```tsx
+<InputNumber
+  step={5}
+  min={0}
+  max={50}
+  defaultValue={10}
+  placeholder="Step by 5"
+/>
+```
+
+### Decimal input with validation error
+
+```tsx
+<InputNumber
+  fractionDigits={2}
+  defaultValue={3.14}
+  error={true}
+  helperText="Value must be between 0 and 100"
+  placeholder="Decimal number"
+/>
+```
+
+## Related Components
+
+- [Input](../input/README.md)
+- [IconButton](../icon-button/README.md)
+
+## Dependencies
+
+- @floating-ui/react
+- lodash-es
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./inputnumber.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/input-range/README.md

@@ -0,0 +1,85 @@
+# InputRange
+
+A dual-input numeric range component that renders two InputNumber fields (from/to) in a single bordered container, connected by an arrow icon. Designed for filtering scenarios like price ranges or quantity ranges where users need to specify a minimum and maximum value.
+
+## Import
+
+```tsx
+import { InputRange } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `inputs` | `[InputNumberProps, InputNumberProps]` | - | Tuple of two InputNumber prop objects — first for the 'from' (min) input, second for the 'to' (max) input. Supports all InputNumber props including value, defaultValue, placeholder, min, max, etc. |
+| `size` | `SizeVariant ('xs' \| 'sm' \| 'md' \| 'lg')` | `'md'` | Controls the size of both inputs and icons within the range component. |
+| `sm` | `{ size?: SizeVariant }` | - | Responsive size override applied at the sm breakpoint (≥768px). |
+| `md` | `{ size?: SizeVariant }` | - | Responsive size override applied at the md breakpoint (≥1280px). |
+| `lg` | `{ size?: SizeVariant }` | - | Responsive size override applied at the lg breakpoint (≥1680px). |
+| `error` | `boolean` | - | Puts the component in an error state. Visually indicates invalid input and styles the helper text in red. |
+| `helperText` | `string` | - | Helper or validation message displayed below the input container. Styled as error text when `error=true`. |
+| `onChange` | `(e: React.ChangeEvent<HTMLInputElement>, edge: InputRangeEdge) => void` | - | Change handler called when either input changes. The `edge` parameter indicates which input triggered the change: `'from'` for the left input, `'to'` for the right input. |
+| `prefix` | `React.ReactNode` | - | Content rendered before the start icon and the first input, inside the container border. |
+| `suffix` | `React.ReactNode` | - | Content rendered after the end icon and the last input, inside the container border. |
+| `startIcon` | `IconProps` | - | Icon displayed at the left side of the container, before the first (from) input. |
+| `endIcon` | `IconProps` | - | Icon displayed at the right side of the container, after the second (to) input. |
+| `sx` | `ToResponsiveProps<StyledCSS>` | - | Responsive CSS overrides applied to the outer wrapper element via Emotion. |
+
+## Examples
+
+### With placeholders
+
+```tsx
+<InputRange
+  inputs={[
+    { placeholder: 'Min' },
+    { placeholder: 'Max' },
+  ]}
+  onChange={(e, edge) => console.log(edge, e.target.value)}
+/>
+```
+
+### With default values and error state
+
+```tsx
+<InputRange
+  error={true}
+  helperText="Max must be greater than min"
+  inputs={[
+    { defaultValue: 100, placeholder: 'Min' },
+    { defaultValue: 10, placeholder: 'Max' },
+  ]}
+  onChange={(e, edge) => handleRangeChange(e, edge)}
+/>
+```
+
+### Small size with responsive override
+
+```tsx
+<InputRange
+  size="sm"
+  md={{ size: 'md' }}
+  inputs={[
+    { placeholder: 'From', min: 0 },
+    { placeholder: 'To', max: 10000 },
+  ]}
+  onChange={(e, edge) => {
+    if (edge === 'from') setMinPrice(Number(e.target.value));
+    else setMaxPrice(Number(e.target.value));
+  }}
+/>
+```
+
+## Related Components
+
+- [InputNumber](../inputnumber/README.md)
+- [Icon](../icon/README.md)
+- [FormHelperText](../formhelpertext/README.md)
+- [Primitive](../primitive/README.md)
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./inputrange.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/lightbox/README.md

@@ -0,0 +1,107 @@
+# Lightbox
+
+A full-screen media viewer overlay that supports image zoom/pan and video playback with slide navigation. Built on top of the Floating component, it renders a backdrop overlay with swipeable slides, prev/next navigation, zoom controls for images, and a close button.
+
+## Import
+
+```tsx
+import { Lightbox } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `slides*` | `LightboxSlide[]` | - | Array of slides to display. Each slide has a `source` (image or video) and an optional `title`. ImageSource: `{ type: 'image'; src: string }`. VideoSource: `{ type: 'video'; src: string; thumbnail?: string }`. |
+| `defaultActiveIndex` | `number` | 0 | Zero-based index of the slide to show when the lightbox first opens. |
+| `open` | `boolean` | - | Controlled open state of the lightbox (inherited from FloatingProps). |
+| `onOpenChange` | `(open: boolean, event?: Event, reason?: OpenChangeReason) => void` | - | Callback fired when the open state changes (inherited from FloatingProps). |
+| `placement` | `Placement` | - | Floating UI placement — typically not needed for lightbox usage (inherited from FloatingProps). |
+| `dismissProps` | `UseDismissProps` | - | Options for dismiss behavior (click outside, Escape key). Enabled by default in Lightbox (inherited from FloatingProps). |
+| `clickProps` | `UseClickProps` | - | Options for click interaction that opens/closes the lightbox (inherited from FloatingProps). |
+| `hoverProps` | `UseHoverProps` | - | Options for hover interaction (inherited from FloatingProps). |
+| `focusProps` | `UseFocusProps` | - | Options for focus interaction (inherited from FloatingProps). |
+| `offsetOptions` | `OffsetOptions` | - | Offset distance from the reference element (inherited from FloatingProps). |
+| `children` | `React.ReactNode` | - | Trigger element — should be wrapped in a FloatingTrigger to wire up open/close interaction. |
+
+*Required props
+
+## Examples
+
+### Image gallery with multiple slides
+
+```tsx
+<Lightbox
+  slides={[
+    { source: { type: 'image', src: 'https://example.com/photo1.jpg' }, title: 'Photo 1' },
+    { source: { type: 'image', src: 'https://example.com/photo2.jpg' }, title: 'Photo 2' },
+    { source: { type: 'image', src: 'https://example.com/photo3.jpg' }, title: 'Photo 3' },
+  ]}
+>
+  <FloatingTrigger>
+    <button>Open Gallery</button>
+  </FloatingTrigger>
+</Lightbox>
+```
+
+### Open at a specific slide index
+
+```tsx
+<Lightbox
+  defaultActiveIndex={1}
+  slides={[
+    { source: { type: 'image', src: 'https://example.com/photo1.jpg' }, title: 'First' },
+    { source: { type: 'image', src: 'https://example.com/photo2.jpg' }, title: 'Second' },
+  ]}
+>
+  <FloatingTrigger>
+    <button>Open at Second Image</button>
+  </FloatingTrigger>
+</Lightbox>
+```
+
+### Mixed image and video slides
+
+```tsx
+<Lightbox
+  slides={[
+    { source: { type: 'image', src: 'https://example.com/thumbnail.jpg' }, title: 'Product Photo' },
+    {
+      source: {
+        type: 'video',
+        src: 'https://example.com/product-demo.mp4',
+        thumbnail: 'https://example.com/video-thumb.jpg',
+      },
+      title: 'Product Demo',
+    },
+  ]}
+>
+  <FloatingTrigger>
+    <button>View Media</button>
+  </FloatingTrigger>
+</Lightbox>
+```
+
+## Related Components
+
+- [Floating](../floating/README.md)
+- [FloatingClose](../floatingclose/README.md)
+- [FloatingContent](../floatingcontent/README.md)
+- [IconButton](../iconbutton/README.md)
+- [Image](../image/README.md)
+- [Swiper](../swiper/README.md)
+- [SwiperSlide](../swiperslide/README.md)
+
+## Dependencies
+
+- motion/react
+- react-player
+- react-zoom-pan-pinch
+- @floating-ui/react
+- lodash-es
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./lightbox.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/linear-progress/README.md

@@ -0,0 +1,54 @@
+# LinearProgress
+
+A horizontal progress bar component that supports both determinate (known progress value) and indeterminate (loading/unknown) states. Commonly used to indicate file upload progress, page load status, or any operation with measurable or unknown completion.
+
+## Import
+
+```tsx
+import { LinearProgress } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `number` | - | Progress value as a percentage (0–100). When omitted, the component falls back to indeterminate mode automatically. |
+| `variant` | `'determinate' \| 'indeterminate'` | - | Explicitly set the progress mode. If not provided, inferred from whether `value` is set: defined value → determinate, undefined value → indeterminate. |
+| `color` | `ColorVariant` | `primary` | Color theme of the progress bar. Accepts any ColorVariant token: `'primary' \| 'secondary' \| 'green' \| 'red' \| 'orange' \| 'blue' \| 'neutral'`. |
+| `size` | `number` | `4` | Height of the progress bar in pixels. Border-radius is automatically set to `size/2` to keep pill shape. |
+| `sm` | `LinearProgressResponsiveProps` | - | Responsive overrides at the `sm` breakpoint (≥768px). Accepts `{ size?: number }`. |
+| `md` | `LinearProgressResponsiveProps` | - | Responsive overrides at the `md` breakpoint (≥1280px). Accepts `{ size?: number }`. |
+| `lg` | `LinearProgressResponsiveProps` | - | Responsive overrides at the `lg` breakpoint (≥1680px). Accepts `{ size?: number }`. |
+| `duration` | `number` | - | Khai báo trong props type nhưng chưa được sử dụng trong implementation hiện tại — reserved cho việc kiểm soát animation duration trong tương lai. |
+
+## Examples
+
+### Determinate progress at 70%
+
+```tsx
+<LinearProgress value={70} color="primary" style={{ width: 400 }} />
+```
+
+### Indeterminate (loading) state
+
+```tsx
+<LinearProgress variant="indeterminate" style={{ width: '100%' }} />
+```
+
+### Thick success bar with green color
+
+```tsx
+<LinearProgress value={100} color="green" size={8} style={{ width: 400 }} />
+```
+
+## Dependencies
+
+- motion/react
+- lodash-es
+- @emotion/react
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./linearprogress.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/link/README.md

@@ -0,0 +1,67 @@
+# Link
+
+A navigation link component built on top of React Router's Link, supporting typography variants, optional underline effects, and responsive styling via the sx prop. Use it for internal and external navigation within a React Router context.
+
+## Import
+
+```tsx
+import { Link } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `to` | `ReactRouterLinkProps['to']` | - | Navigation destination — can be a path string, URL object, or React Router To value. If omitted, click events are prevented. |
+| `underline` | `boolean` | false | When true, applies a hover underline animation effect via createUnderlineEffect(). |
+| `textVariant` | `TypographySizeVariant` | - | Typography size variant applied to the link text. Accepts 'xs' | 'sm' | 'base' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl' | '5xl' | '6xl'. Supports responsive overrides via sm/md/lg. |
+| `sm` | `LinkResponsiveProps` | - | Responsive overrides applied at the sm breakpoint (≥768px). Accepts { textVariant }. |
+| `md` | `LinkResponsiveProps` | - | Responsive overrides applied at the md breakpoint (≥1280px). Accepts { textVariant }. |
+| `lg` | `LinkResponsiveProps` | - | Responsive overrides applied at the lg breakpoint (≥1680px). Accepts { textVariant }. |
+| `sx` | `ToResponsiveProps<StyledCSS>` | - | Escape-hatch for custom Emotion CSS styles, including responsive overrides via sx.sm / sx.md / sx.lg. |
+| `children` | `React.ReactNode` | - | Content rendered inside the anchor element. |
+| `ref` | `Ref<HTMLAnchorElement>` | - | Forwarded ref to the underlying anchor element. |
+| `aria-disabled` | `string` | - | When set to 'true', click events are prevented and pointer-events are set to none, making the link non-interactive without removing it from the DOM. |
+| `target` | `string` | - | Standard HTML anchor target attribute, e.g. '_blank' for external links. Passed through to the underlying ReactRouterLink. |
+
+## Examples
+
+### Default navigation link
+
+```tsx
+<Link to="/products">Browse products</Link>
+```
+
+### Link with underline hover effect and typography variant
+
+```tsx
+<Link to="/about" underline textVariant="sm">
+  Learn more about us
+</Link>
+```
+
+### External link opening in new tab, responsive text size
+
+```tsx
+<Link
+  to="https://example.com"
+  target="_blank"
+  textVariant="xs"
+  md={{ textVariant: 'sm' }}
+  sx={{ color: 'var(--color-primary-600)' }}
+>
+  Visit external site
+</Link>
+```
+
+## Dependencies
+
+- react-router
+- @emotion/react
+- lodash-es
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./link.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/loading/README.md

@@ -0,0 +1,65 @@
+# LoadingOverlay
+
+A suite of loading/skeleton components for displaying placeholder states and loading indicators. Includes BlockSkeleton, ImageSkeleton, TextSkeleton (animated pulse placeholders) and LoadingOverlay (spinning icon overlay for async content).
+
+## Import
+
+```tsx
+import { LoadingOverlay } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isLoading` | `boolean` | false | Controls whether the loading overlay spinner is visible over the content. |
+| `size` | `number` | 32 | Size in pixels for the spinning loader icon and minimum dimensions of the container. |
+| `color` | `ColorVariant` | 'primary' | Color variant for the spinning loader icon. Accepts 'primary' | 'secondary' | 'green' | 'red' | 'orange' | 'blue' | 'neutral'. |
+| `iconProps` | `PrimitiveProps<JSX.IntrinsicElements['div']>` | - | Additional props passed to the overlay container div that wraps the spinner icon. |
+| `children` | `React.ReactNode` | - | Content rendered beneath the overlay. Visible when isLoading is false; obscured by the spinner when isLoading is true. |
+| `sx` | `ToResponsiveProps<StyledCSS>` | - | Responsive style overrides via the sx prop, inherited from PrimitiveProps. |
+| `style` | `React.CSSProperties` | - | Inline style for the root container. Merged with the minWidth/minHeight derived from size. |
+
+## Examples
+
+### LoadingOverlay wrapping async content
+
+```tsx
+<LoadingOverlay isLoading style={{ width: 300, height: 200, position: 'relative' }}>
+  <div style={{ padding: 16 }}>Content behind overlay</div>
+</LoadingOverlay>
+```
+
+### Skeleton placeholders for a card layout
+
+```tsx
+<div style={{ width: 300 }}>
+  <ImageSkeleton style={{ width: 300, height: 160, marginBottom: 12 }} />
+  <TextSkeleton sx={{ width: 160 }} style={{ marginBottom: 8 }} />
+  <TextSkeleton style={{ marginBottom: 8, width: '80%' }} />
+  <TextSkeleton style={{ width: '60%' }} />
+</div>
+```
+
+### BlockSkeleton for generic placeholder blocks
+
+```tsx
+<BlockSkeleton style={{ width: 300, height: 100 }} />
+```
+
+## Related Components
+
+- [Primitive](../primitive/README.md)
+- [SvgLoader](../svgloader/README.md)
+
+## Dependencies
+
+- @emotion/react
+- @janbox/storefront-ui/constants (animatePulseStyle, animateSpinStyle)
+- @janbox/storefront-ui/theme (getColorVar, getColorShadesByVariant)
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./loadingoverlay.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/marquee/README.md

@@ -0,0 +1,83 @@
+# Marquee
+
+A horizontally auto-scrolling carousel component built on top of Embla Carousel with the AutoScroll plugin. Use it to display a continuous looping ticker of items — logos, tags, or any inline content — with configurable spacing and an optional separator icon between items.
+
+## Import
+
+```tsx
+import { Marquee } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `spaceBetween` | `number` | - | Gap in pixels between each marquee slide. Supports responsive variants via sm/md/lg props. |
+| `sm` | `MarqueeResponsiveProps` | - | Responsive overrides for screens ≥768px. Accepts { spaceBetween?: number }. |
+| `md` | `MarqueeResponsiveProps` | - | Responsive overrides for screens ≥1280px. Accepts { spaceBetween?: number }. |
+| `lg` | `MarqueeResponsiveProps` | - | Responsive overrides for screens ≥1680px. Accepts { spaceBetween?: number }. |
+| `autoScrollOptions` | `AutoScrollOptionsType` | { playOnInit: true, stopOnFocusIn: false, stopOnInteraction: false, stopOnMouseEnter: false } | Options passed directly to the embla-carousel-auto-scroll plugin. Controls playback behaviour such as playOnInit, stopOnMouseEnter, stopOnInteraction, and stopOnFocusIn. |
+| `separatorIcon` | `IconProps` | - | Optional icon rendered as a separator slide between every content item. |
+| `children` | `React.ReactNode` | - | Slide content. Each direct child is wrapped in an individual slide. Intended to be composed with MarqueeItem. |
+| `sx` | `ToResponsiveProps<StyledCSS>` | - | Emotion sx prop for custom responsive styles on the root container. |
+
+## Examples
+
+### Default — basic text items
+
+```tsx
+<div style={{ width: 400 }}>
+  <Marquee spaceBetween={16}>
+    {Array.from({ length: 10 }).map((_, index) => (
+      <MarqueeItem key={index}>Item {index + 1}</MarqueeItem>
+    ))}
+  </Marquee>
+</div>
+```
+
+### Logo ticker with separator icon
+
+```tsx
+<Marquee
+  spaceBetween={24}
+  separatorIcon={{ source: DotIcon, size: 8 }}
+>
+  <MarqueeItem><img src="/logo-a.svg" alt="Brand A" /></MarqueeItem>
+  <MarqueeItem><img src="/logo-b.svg" alt="Brand B" /></MarqueeItem>
+  <MarqueeItem><img src="/logo-c.svg" alt="Brand C" /></MarqueeItem>
+</Marquee>
+```
+
+### Pause on mouse enter with responsive spacing
+
+```tsx
+<Marquee
+  spaceBetween={8}
+  sm={{ spaceBetween: 16 }}
+  md={{ spaceBetween: 24 }}
+  autoScrollOptions={{ playOnInit: true, stopOnMouseEnter: true }}
+>
+  {tags.map((tag) => (
+    <MarqueeItem key={tag}>
+      <Badge color="primary">{tag}</Badge>
+    </MarqueeItem>
+  ))}
+</Marquee>
+```
+
+## Related Components
+
+- [Icon](../icon/README.md)
+- [Primitive](../primitive/README.md)
+
+## Dependencies
+
+- embla-carousel-react
+- embla-carousel-auto-scroll
+- @floating-ui/react
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./marquee.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/marquee/marquee/marquee.js

@@ -92,7 +92,7 @@ const MarqueeSlide = ({ children }) => {
         flexShrink: 0,
         flexGrow: 0,
         overflow: "hidden",
-        paddingRight: `var(${SPACING_VAR}, 0px)`
+        paddingLeft: `var(${SPACING_VAR}, 0px)`
       },
       className: HTMLClasses.MARQUEE_SLIDE,
       children

package/dist/lib/menu/README.md

@@ -0,0 +1,92 @@
+# Menu
+
+Dropdown menu component hiển thị danh sách actions hoặc options khi được kích hoạt. Xây dựng trên Floating UI, hỗ trợ tương tác hover và click với safe polygon hover detection.
+
+## Import
+
+```tsx
+import { Menu } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `placement` | `Placement` | `'bottom'` | Vị trí của menu so với trigger (vd: `'top'`, `'bottom'`, `'left'`, `'right'`, và các biến thể như `'top-start'`) |
+| `open` | `boolean` | - | Controlled open state của menu |
+| `onOpenChange` | `(open: boolean, event?: Event, reason?: string) => void` | - | Callback khi trạng thái open thay đổi |
+| `clickProps` | `UseClickProps` | - | Cấu hình tương tác click (bật mặc định) |
+| `dismissProps` | `UseDismissProps` | - | Cấu hình dismiss khi click ra ngoài (bật mặc định) |
+| `hoverProps` | `UseHoverProps` | - | Cấu hình tương tác hover (dùng `safePolygon` mặc định để tránh đóng nhầm) |
+| `focusProps` | `UseFocusProps` | - | Cấu hình tương tác focus |
+| `offsetOptions` | `OffsetOptions` | - | Khoảng cách giữa trigger và menu content |
+| `sizeOptions` | `SizeOptions` | - | Ràng buộc kích thước của floating menu |
+| `autoUpdateOptions` | `AutoUpdateOptions` | - | Tùy chọn tự động cập nhật vị trí menu |
+| `children` * | `ReactNode` | - | Nội dung menu (thường là `MenuTrigger` và `MenuList`) |
+
+*Bắt buộc
+
+## Examples
+
+### Basic Menu
+
+```tsx
+<Menu>
+  <MenuTrigger>
+    <button>Open Menu ▼</button>
+  </MenuTrigger>
+  <MenuList>
+    <MenuItem>Profile</MenuItem>
+    <MenuItem>Settings</MenuItem>
+    <MenuItem>Help</MenuItem>
+    <MenuItem>Logout</MenuItem>
+  </MenuList>
+</Menu>
+```
+
+### Menu with Icons
+
+```tsx
+<Menu>
+  <MenuTrigger>
+    <button>Actions ▼</button>
+  </MenuTrigger>
+  <MenuList>
+    <MenuItem>✏️ Edit</MenuItem>
+    <MenuItem>📋 Copy</MenuItem>
+    <MenuItem>🗑️ Delete</MenuItem>
+  </MenuList>
+</Menu>
+```
+
+### Top Placement Menu
+
+```tsx
+<Menu placement="top">
+  <MenuTrigger>
+    <button>Open Top ▲</button>
+  </MenuTrigger>
+  <MenuList>
+    <MenuItem>Option 1</MenuItem>
+    <MenuItem>Option 2</MenuItem>
+    <MenuItem>Option 3</MenuItem>
+  </MenuList>
+</Menu>
+```
+
+## Related Components
+
+- [Floating](../floating/README.md)
+- [FloatingTrigger](../floating-trigger/README.md)
+- [FloatingContent](../floating-content/README.md)
+- [Button](../button/README.md)
+
+## Dependencies
+
+- `@floating-ui/react`
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./menu.stories.tsx)
+- [Main README](../../README.md)