@janbox/storefront-ui 2.0.29 → 2.0.30

package/dist/lib/multiple-select/README.md

@@ -0,0 +1,108 @@
+# MultipleSelect
+
+A generic multi-select dropdown component that renders selected values as tags inside an input trigger. It supports search filtering, virtualized option lists, controlled/uncontrolled state, and responsive sizing.
+
+## Import
+
+```tsx
+import { MultipleSelect } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `options*` | `O[]` | - | Array of option objects to display in the dropdown list. |
+| `value` | `Array<Partial<O> \| MultipleSelectOptionValue>` | - | Controlled selected values. Can be full option objects or primitive values (string \| number). |
+| `defaultValue` | `Array<Partial<O> \| MultipleSelectOptionValue>` | - | Initial selected values for uncontrolled usage. |
+| `onChange` | `(value: O[]) => void` | - | Callback fired when the selection changes, receiving the full array of selected option objects. |
+| `optionValue` | `keyof O \| ((option: O) => MultipleSelectOptionValue)` | `'value'` | Key or function to derive the unique value from an option object. |
+| `optionLabel` | `keyof O \| ((option: O) => React.ReactNode)` | `'label'` | Key or function to derive the display label from an option object. |
+| `tagLabel` | `keyof O \| ((option: O) => React.ReactNode)` | - | Key or function to derive the label shown inside the selected tag chip. Falls back to `optionLabel` if not set. |
+| `optionSearchLabel` | `keyof O \| Array<keyof O> \| ((option: O) => string \| string[])` | - | Field(s) or function used when filtering options by the search input. Defaults to `optionLabel`. |
+| `searchable` | `boolean` | `true` | Whether to show a search input inside the dropdown for filtering options. |
+| `displayCount` | `number` | `1` | Maximum number of tag chips shown in the trigger before collapsing into a `+N` badge. Use `Infinity` to show all. |
+| `placeholder` | `string` | - | Placeholder text shown in the trigger when no values are selected. |
+| `open` | `boolean` | - | Controlled open state of the dropdown. |
+| `onOpenChange` | `UseFloatingOptions['onOpenChange']` | - | Callback fired when the open state changes. |
+| `placement` | `Placement` | `'bottom-start'` | Floating UI placement for the dropdown panel. |
+| `error` | `boolean` | - | When true, renders the trigger in an error/invalid visual state. |
+| `helperText` | `string` | - | Helper or validation message rendered below the trigger via `FormHelperText`. |
+| `containerProps` | `PrimitiveProps<JSX.IntrinsicElements['div']>` | - | Props forwarded to the outer container `Primitive` wrapper. |
+| `inputProps` | `InputProps` | - | Props forwarded to the search `Input` rendered inside the dropdown panel. |
+| `listProps` | `PropsWithoutRef<HTMLProps<HTMLDivElement>>` | - | Props forwarded to the `VirtualizedList` container element. |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Size variant controlling height, padding, and font size of the trigger and option rows. |
+
+*Required props
+
+## Examples
+
+### Basic usage
+
+```tsx
+type Option = { label: string; value: string };
+
+const fruits: Option[] = [
+  { label: 'Apple', value: 'apple' },
+  { label: 'Banana', value: 'banana' },
+  { label: 'Cherry', value: 'cherry' },
+];
+
+<MultipleSelect<Option>
+  options={fruits}
+  placeholder="Select fruits..."
+  onChange={(selected) => console.log(selected)}
+/>
+```
+
+### Controlled with error state
+
+```tsx
+const [selected, setSelected] = useState<string[]>([]);
+
+<MultipleSelect
+  options={fruits}
+  value={selected}
+  onChange={(opts) => setSelected(opts.map((o) => o.value))}
+  error={selected.length === 0}
+  helperText={selected.length === 0 ? 'Please select at least one option' : undefined}
+  placeholder="Select fruits..."
+/>
+```
+
+### Display multiple tags with overflow badge
+
+```tsx
+// Shows up to 2 tag chips, remaining selections collapse into '+N' badge
+<MultipleSelect<Option>
+  options={fruits}
+  value={['apple', 'banana', 'cherry']}
+  displayCount={2}
+  placeholder="Select fruits..."
+  onChange={handleChange}
+/>
+```
+
+## Related Components
+
+- [Input](../input/README.md)
+- [InputMask](../inputmask/README.md)
+- [Checkbox](../checkbox/README.md)
+- [Floating](../floating/README.md)
+- [FloatingTrigger](../floatingtrigger/README.md)
+- [FloatingContent](../floatingcontent/README.md)
+- [FormHelperText](../formhelpertext/README.md)
+- [VirtualizedList](../virtualizedlist/README.md)
+- [Primitive](../primitive/README.md)
+
+## Dependencies
+
+- @floating-ui/react
+- @tanstack/react-virtual
+- lodash-es
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./multipleselect.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/nav-link/README.md

@@ -0,0 +1,61 @@
+# NavLink
+
+A wrapper around React Router's NavLink component that adds safe handling for undefined `to` prop. When `to` is nil, the link prevents navigation and treats itself as inactive, making it safe to render navigation items that may not yet have a destination.
+
+## Import
+
+```tsx
+import { NavLink } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `to` | `ReactRouterNavLinkProps['to'] \| undefined` | - | Đường dẫn hoặc location object. Khi `undefined` hoặc `null`, link sẽ ngăn navigation và được coi là inactive (`isActive = false`). |
+| `children` | `React.ReactNode \| ((props: NavLinkRenderProps) => React.ReactNode)` | - | Nội dung bên trong link. Có thể là render function nhận NavLink render props gồm `isActive`, `isPending`, `isTransitioning`. Khi `to` là nil, `isActive` luôn là `false`. |
+| `className` | `string \| ((props: NavLinkRenderProps) => string \| undefined)` | - | Class name hoặc function nhận render props để tính class động. `isActive` trong render props tuân theo nil-to override. |
+| `style` | `React.CSSProperties \| ((props: NavLinkRenderProps) => React.CSSProperties \| undefined)` | - | Inline styles hoặc function nhận render props để tính styles động. `isActive` trong render props tuân theo nil-to override. |
+| `end` | `boolean` | - | Khi `true`, active class/style chỉ được áp dụng khi URL hiện tại khớp chính xác với `to` (không partial matching). |
+| `ref` | `Ref<HTMLAnchorElement>` | - | Forwarded ref đến anchor element bên dưới. |
+| `onClick` | `(event: React.MouseEvent<HTMLAnchorElement>) => void` | - | Click handler. Navigation tự động bị ngăn khi `to` là nil hoặc khi `aria-disabled` là `true`. |
+
+## Examples
+
+### Basic navigation link
+
+```tsx
+<NavLink to="/home">Home</NavLink>
+```
+
+### Active state with exact match and dynamic class
+
+```tsx
+<NavLink
+  to="/dashboard"
+  end
+  className={({ isActive }) => isActive ? 'nav-item nav-item--active' : 'nav-item'}
+>
+  Dashboard
+</NavLink>
+```
+
+### Placeholder link with no destination (disabled navigation)
+
+```tsx
+<NavLink to={undefined} aria-disabled="true">
+  {({ isActive }) => (
+    <span style={{ opacity: isActive ? 1 : 0.5 }}>Coming Soon</span>
+  )}
+</NavLink>
+```
+
+## Dependencies
+
+- react-router
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./navlink.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/notifications/README.md

@@ -0,0 +1,103 @@
+# Notifications
+
+A toast notification system that renders dismissible notification cards in a fixed portal overlay at the top-right of the screen. It uses an external store (`notificationStore`) and the `useNotifications` hook to push notifications imperatively from anywhere in the app.
+
+## Import
+
+```tsx
+import { Notifications } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+
+## Examples
+
+### Basic usage — mount Notifications once and push via hook
+
+```tsx
+import { Notifications, useNotifications } from '@janbox/storefront-ui';
+
+const App = () => (
+  <>
+    {/* Mount once at the root level */}
+    <Notifications />
+    <MyPage />
+  </>
+);
+
+const MyPage = () => {
+  const { pushNotifications } = useNotifications();
+
+  return (
+    <button
+      onClick={() =>
+        pushNotifications({
+          title: 'Success',
+          message: 'Your changes have been saved.',
+          color: 'green',
+        })
+      }
+    >
+      Save
+    </button>
+  );
+};
+```
+
+### Push multiple notifications with custom duration
+
+```tsx
+const { pushNotifications } = useNotifications();
+
+pushNotifications([
+  {
+    title: 'Item added',
+    message: 'Product has been added to your cart.',
+    color: 'primary',
+    duration: 4000,
+  },
+  {
+    title: 'Stock low',
+    message: 'Only 2 items left in stock.',
+    color: 'orange',
+    duration: 6000,
+  },
+]);
+```
+
+### Error notification on API failure
+
+```tsx
+const { pushNotifications } = useNotifications();
+
+try {
+  await submitOrder();
+} catch (err) {
+  pushNotifications({
+    title: 'Order failed',
+    message: 'Something went wrong. Please try again.',
+    color: 'red',
+    duration: 5000,
+  });
+}
+```
+
+## Related Components
+
+- [IconButton](../icon-button/README.md)
+- [Primitive](../primitive/README.md)
+
+## Dependencies
+
+- @floating-ui/react
+- lodash-es
+- motion/react
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./notifications.stories.tsx)
+- [Main README](../../README.md)

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

@@ -0,0 +1,71 @@
+# OtpInput
+
+A one-time password input component that renders multiple individual input fields for entering verification codes. Supports auto-focus, paste handling, keyboard navigation, and automatic progression between fields.
+
+## Import
+
+```tsx
+import { OtpInput } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `length` | `number` | 6 | Number of OTP input fields to render |
+| `onChange` | `(otp: string) => void` | - | Callback fired when any digit changes, receives the complete OTP string |
+| `onFullfilled` | `(otp: string) => void` | - | Callback fired when all digits are filled, receives the complete OTP string |
+| `disabled` | `boolean` | - | Disables all input fields |
+| `autoFocus` | `boolean` | - | Auto-focuses the first input field on mount |
+| `isLoading` | `boolean` | - | Makes all input fields read-only during loading state |
+| `defaultValue` | `string` | - | Default OTP value (uncontrolled) |
+| `value` | `string` | - | Controlled OTP value |
+| `error` | `boolean` | - | Shows error state styling on all input fields |
+| `size` | `InputSizeVariant` | - | Size variant for all input fields |
+| `sm` | `InputResponsiveProps` | - | Responsive props for small breakpoint (768px+) |
+| `md` | `InputResponsiveProps` | - | Responsive props for medium breakpoint (1280px+) |
+| `lg` | `InputResponsiveProps` | - | Responsive props for large breakpoint (1680px+) |
+
+## Examples
+
+### Basic 6-digit OTP
+
+```tsx
+<OtpInput length={6} onChange={(otp) => console.log(otp)} />
+```
+
+### 4-digit PIN with auto-submit
+
+```tsx
+<OtpInput
+  length={4}
+  autoFocus
+  onFullfilled={(otp) => handleVerify(otp)}
+/>
+```
+
+### Controlled with error state
+
+```tsx
+<OtpInput
+  length={6}
+  value={otpValue}
+  onChange={setOtpValue}
+  error={hasError}
+  disabled={isSubmitting}
+/>
+```
+
+## Related Components
+
+- [Input](../input/README.md)
+
+## Dependencies
+
+- lodash-es
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./otpinput.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/pagination/README.md

@@ -0,0 +1,84 @@
+# Pagination
+
+A pagination component for navigating through multiple pages of content. Displays page numbers with ellipsis for large page counts, supports customizable navigation buttons, and provides responsive sizing.
+
+## Import
+
+```tsx
+import { Pagination } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `page` | `number` | 1 | Current active page number |
+| `totalPages` | `number` | 1 | Total number of pages available |
+| `onChange` | `(page: number) => void` | - | Callback function triggered when page changes |
+| `disabled` | `boolean` | - | Disables all pagination interactions |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `sm` | Size variant for pagination buttons and text |
+| `showPrevPageButton` | `boolean` | `true` | Show/hide the previous page navigation button |
+| `showNextPageButton` | `boolean` | `true` | Show/hide the next page navigation button |
+| `showFirstPageButton` | `boolean` | `false` | Show/hide the first page navigation button |
+| `showLastPageButton` | `boolean` | `false` | Show/hide the last page navigation button |
+| `siblingCount` | `number` | `2` | Number of pages to show on each side of the current page |
+| `states` | `Partial<Record<'normal' \| 'active', { color?: IconButtonProps['color']; variant?: IconButtonProps['variant']; }>>` | `{ normal: { color: 'neutral', variant: 'outlined' }, active: { color: 'primary', variant: 'outlined' } }` | Customize color and variant for normal and active pagination button states |
+| `sm` | `{ size?: SizeVariant }` | - | Responsive props for small breakpoint (768px) |
+| `md` | `{ size?: SizeVariant }` | - | Responsive props for medium breakpoint (1280px) |
+| `lg` | `{ size?: SizeVariant }` | - | Responsive props for large breakpoint (1680px) |
+
+## Examples
+
+### Basic pagination with 10 pages
+
+```tsx
+<Pagination
+  page={5}
+  totalPages={10}
+  onChange={(page) => console.log('Navigate to page:', page)}
+/>
+```
+
+### Pagination with first/last buttons and custom sibling count
+
+```tsx
+<Pagination
+  page={7}
+  totalPages={50}
+  siblingCount={2}
+  showFirstPageButton
+  showLastPageButton
+  onChange={(page) => setCurrentPage(page)}
+/>
+```
+
+### Disabled pagination with custom button states
+
+```tsx
+<Pagination
+  page={3}
+  totalPages={10}
+  disabled
+  states={{
+    normal: { color: 'neutral', variant: 'outlined' },
+    active: { color: 'blue', variant: 'contained' }
+  }}
+  onChange={(page) => handlePageChange(page)}
+/>
+```
+
+## Related Components
+
+- [IconButton](../iconbutton/README.md)
+- [Icon](../icon/README.md)
+- [Text](../text/README.md)
+
+## Dependencies
+
+- @emotion/react
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./pagination.stories.tsx)
+- [Main README](../../README.md)

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

@@ -0,0 +1,80 @@
+# PhoneInput
+
+A phone number input component that combines a country dial code selector with a national number text field. It supports controlled and uncontrolled usage, auto-parses country codes from dial codes, and displays formatted phone numbers when not focused.
+
+## Import
+
+```tsx
+import { PhoneInput } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `PhoneInputValue` | - | Controlled value object containing countryCode, dialCode, and nationalNumber. |
+| `defaultValue` | `PhoneInputValue` | - | Uncontrolled default value. Defaults to the first country in the countries list if not provided. |
+| `onChange` | `(value: PhoneInputValue) => void` | - | Callback fired when either the country dial code or the national number changes. Receives a PhoneInputValue object. |
+| `error` | `boolean` | `false` | Puts the input into an error state, rendering the border in red. |
+| `helperText` | `string` | - | Helper or error message displayed below the input via FormHelperText. |
+| `disabled` | `boolean` | `false` | Disables both the country select and the number input, applying a disabled surface color. |
+| `containerProps` | `PrimitiveProps<JSX.IntrinsicElements['div']>` | - | Props forwarded to the outer container Primitive div, useful for layout overrides via sx. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size variant for the input. xs is excluded. Supports responsive values via sm/md/lg breakpoint keys. |
+| `css` | `Interpolation` | - | Emotion CSS interpolation applied directly to the InputMask wrapper element. |
+
+## Examples
+
+### Default (uncontrolled)
+
+```tsx
+<div style={{ width: 300 }}>
+  <PhoneInput onChange={(value) => console.log(value)} />
+</div>
+```
+
+### Controlled with initial value
+
+```tsx
+const [phone, setPhone] = useState<PhoneInputValue>({
+  countryCode: 'JP',
+  dialCode: '+81',
+  nationalNumber: '9012345678',
+});
+
+<PhoneInput
+  value={phone}
+  onChange={setPhone}
+/>
+```
+
+### Error state with helper text
+
+```tsx
+<PhoneInput
+  error
+  helperText="Please enter a valid phone number."
+  defaultValue={{ countryCode: 'VN' }}
+  onChange={(value) => console.log(value)}
+/>
+```
+
+## Related Components
+
+- [Input](../input/README.md)
+- [InputMask](../inputmask/README.md)
+- [Select](../select/README.md)
+- [Flag](../flag/README.md)
+- [FormHelperText](../formhelpertext/README.md)
+- [Primitive](../primitive/README.md)
+
+## Dependencies
+
+- phone
+- @floating-ui/react
+- lodash-es
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./phoneinput.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/popover/README.md

@@ -0,0 +1,93 @@
+# Popover
+
+A floating overlay component for displaying contextual content anchored to a trigger element. Built on top of @floating-ui/react, it supports click-to-open, dismiss-on-outside-click, and controlled/uncontrolled open state — composed via Popover, PopoverTrigger, PopoverContent, and PopoverClose sub-components.
+
+## Import
+
+```tsx
+import { Popover } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `open` | `boolean` | - | Controlled open state of the popover. |
+| `onOpenChange` | `UseFloatingOptions['onOpenChange']` | - | Callback fired when the open state changes. Receives (open: boolean, event: Event | undefined, reason: OpenChangeReason | undefined). |
+| `placement` | `Placement` | `bottom` | Preferred placement of the floating content relative to the trigger. Accepts all @floating-ui/react Placement values (e.g. `'top'`, `'bottom'`, `'left'`, `'right'` and their `'-start'`/`'-end'` variants). |
+| `clickProps` | `UseClickProps` | `{ enabled: true }` | Options forwarded to @floating-ui/react useClick interaction hook. Enabled by default in Popover. |
+| `dismissProps` | `UseDismissProps` | `{ enabled: true }` | Options forwarded to @floating-ui/react useDismiss interaction hook (close on outside click / Escape key). Enabled by default in Popover. |
+| `hoverProps` | `UseHoverProps` | - | Options forwarded to @floating-ui/react useHover interaction hook. |
+| `focusProps` | `UseFocusProps` | - | Options forwarded to @floating-ui/react useFocus interaction hook. |
+| `offsetOptions` | `OffsetOptions` | - | Distance (in px) between the trigger and the floating content. |
+| `sizeOptions` | `SizeOptions` | - | Options for the @floating-ui/react size middleware — constrain the floating element dimensions. |
+| `autoUpdateOptions` | `AutoUpdateOptions` | - | Options passed to @floating-ui/react autoUpdate to control when the position recalculates. |
+| `elements` | `UseFloatingOptions['elements']` | - | Override the reference or floating elements used by floating-ui. |
+| `ref` | `React.Ref<FloatingRef>` | - | Ref forwarded to the underlying UseFloatingReturn object, exposing the full floating-ui context. |
+| `children` | `React.ReactNode` | - | Should contain PopoverTrigger and PopoverContent (and optionally PopoverClose inside content). |
+
+## Examples
+
+### Default (click to open, dismiss on outside click)
+
+```tsx
+<Popover>
+  <PopoverTrigger>
+    <button>Open Popover</button>
+  </PopoverTrigger>
+  <PopoverContent>
+    <p>Popover content here</p>
+    <PopoverClose>
+      <button>Close</button>
+    </PopoverClose>
+  </PopoverContent>
+</Popover>
+```
+
+### Top placement
+
+```tsx
+<Popover placement="top">
+  <PopoverTrigger>
+    <button>Open Top</button>
+  </PopoverTrigger>
+  <PopoverContent>
+    <p>Popover anchored above the trigger</p>
+  </PopoverContent>
+</Popover>
+```
+
+### Controlled open state
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Popover open={open} onOpenChange={(next) => setOpen(next)}>
+  <PopoverTrigger>
+    <button>Toggle</button>
+  </PopoverTrigger>
+  <PopoverContent>
+    <p>Controlled popover</p>
+    <PopoverClose>
+      <button onClick={() => setOpen(false)}>Close</button>
+    </PopoverClose>
+  </PopoverContent>
+</Popover>
+```
+
+## Related Components
+
+- [Floating](../floating/README.md)
+- [FloatingTrigger](../floating-trigger/README.md)
+- [FloatingContent](../floating-content/README.md)
+- [FloatingClose](../floating-close/README.md)
+
+## Dependencies
+
+- @floating-ui/react
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./popover.stories.tsx)
+- [Main README](../../README.md)

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

@@ -0,0 +1,78 @@
+# PriceLabel
+
+A component for displaying a primary price alongside an optional exchange/secondary price. Supports currency formatting, pending states, skeleton placeholders, responsive typography sizing, and both vertical and horizontal layout orientations.
+
+## Import
+
+```tsx
+import { PriceLabel } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `price*` | `PriceLabelEntry` | - | Primary price data. Contains currency, value, isPending, placeholder, prefix, and suffix fields. |
+| `price.currency` | `string` | - | ISO currency code (e.g. 'USD', 'VND'). When combined with value, renders a formatted price string. |
+| `price.value` | `number` | - | Numeric price value to format and display. |
+| `price.isPending` | `boolean` | - | When true and no value is set, renders an 'updating' label. |
+| `price.placeholder` | `boolean` | - | When true and no value or pending state, renders a skeleton placeholder. Defaults to true on the primary price. |
+| `price.prefix` | `string` | - | String prepended to the formatted price. |
+| `price.suffix` | `string` | - | String appended to the formatted price. |
+| `exchangePrice` | `PriceLabelEntry` | - | Optional secondary/exchange price displayed below (vertical) or beside (horizontal) the primary price. |
+| `priceProps` | `PrimitiveProps<JSX.IntrinsicElements['span']>` | - | Additional props forwarded to the primary price span element, including sx for style overrides. |
+| `exchangePriceProps` | `PrimitiveProps<JSX.IntrinsicElements['span']>` | - | Additional props forwarded to the exchange price span element, including sx for style overrides. |
+| `color` | `ColorVariant` | `neutral` | Color variant used for the price text. Primary price uses the 600 shade, exchange price uses the 500 shade. |
+| `orientation` | `'horizontal' \| 'vertical'` | `vertical` | Layout direction of the primary and exchange prices. Vertical stacks them with a line break; horizontal places them side by side. |
+| `showEqual` | `boolean` | `false` | When true, shows the exchange price even if it is equal to the primary price (same currency and value). |
+| `size` | `TypographySizeVariant` | `sm` | Typography size for the primary price. Accepts responsive values via sm/md/lg breakpoint props. Exchange price automatically uses one size smaller. |
+
+*Required props
+
+## Examples
+
+### Basic price with exchange rate
+
+```tsx
+<PriceLabel
+  price={{ value: 100, currency: 'USD' }}
+  exchangePrice={{ value: 2000000, currency: 'VND' }}
+/>
+```
+
+### Horizontal layout with color variant and larger size
+
+```tsx
+<PriceLabel
+  price={{ value: 49.99, currency: 'USD' }}
+  exchangePrice={{ value: 999000, currency: 'VND' }}
+  orientation="horizontal"
+  color="primary"
+  size="lg"
+/>
+```
+
+### Pending state while price is loading
+
+```tsx
+<PriceLabel
+  price={{ isPending: true }}
+  exchangePrice={{ isPending: true }}
+  color="neutral"
+/>
+```
+
+## Related Components
+
+- [TextSkeleton](../loading/README.md)
+- [Primitive](../primitive/README.md)
+
+## Dependencies
+
+- lodash-es
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./pricelabel.stories.tsx)
+- [Main README](../../README.md)