@janbox/storefront-ui 2.0.29 → 2.0.31

package/dist/lib/primitive/README.md

@@ -0,0 +1,80 @@
+# Primitive
+
+Một polymorphic base component cho phép render HTML element động với hỗ trợ responsive styling qua `sx` prop. Đây là nền tảng để xây dựng các component khác trong design system, cho phép thay đổi loại element qua `as` prop trong khi vẫn duy trì khả năng styling nhất quán.
+
+## Import
+
+```tsx
+import { Primitive } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `as` | `HTMLElementType` | `div` | Loại HTML element cần render (e.g., `'div'`, `'button'`, `'span'`, `'a'`). |
+| `sx` | `ToResponsiveProps<StyledCSS>` | - | Responsive style object hỗ trợ breakpoint-specific styles (`sm`, `md`, `lg`). Nhận Emotion CSS properties với responsive variants. |
+| `className` | `string` | - | CSS class names bổ sung cho element. |
+| `children` | `React.ReactNode` | - | Child elements render bên trong component. |
+
+## Examples
+
+### Basic usage — render mặc định là div
+
+```tsx
+<Primitive sx={{ padding: 16, backgroundColor: 'lightblue' }}>
+  Default div element
+</Primitive>
+```
+
+### Render as button với responsive styles
+
+```tsx
+<Primitive
+  as="button"
+  sx={{
+    padding: 12,
+    fontSize: 14,
+    sm: { padding: 16, fontSize: 16 },
+    md: { padding: 20, fontSize: 18 }
+  }}
+  onClick={() => console.log('clicked')}
+>
+  Responsive Button
+</Primitive>
+```
+
+### Render as anchor link với custom styles
+
+```tsx
+<Primitive
+  as="a"
+  href="https://example.com"
+  sx={{
+    color: 'blue',
+    textDecoration: 'none',
+    '&:hover': { textDecoration: 'underline' }
+  }}
+>
+  Click me
+</Primitive>
+```
+
+## Related Components
+
+- [Box](../box/README.md)
+- [Flexbox](../flexbox/README.md)
+- [Grid](../grid/README.md)
+- [TableRow](../tablerow/README.md)
+- [ListItem](../listitem/README.md)
+
+## Dependencies
+
+- `@emotion/react`
+- `react`
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./primitive.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/progress/README.md

@@ -0,0 +1,50 @@
+# Progress
+
+A progress bar component that visually represents a completion percentage. Supports both horizontal and vertical orientations with smooth animated fill transitions.
+
+## Import
+
+```tsx
+import { Progress } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value*` | `number` | - | The progress percentage (0–100). Controls the width (horizontal) or height (vertical) of the filled indicator. |
+| `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | Orientation of the progress bar. |
+| `activeProps` | `ComponentProps<'div'>` | `{}` | Props forwarded to the inner indicator element (the filled portion). Useful for custom styling or event handlers on the fill bar. |
+| `children` | `React.ReactNode` | - | Optional content rendered inside the active/fill indicator element. |
+
+*Required props
+
+## Examples
+
+### Default horizontal at 50%
+
+```tsx
+<Progress value={50} style={{ width: 400 }} />
+```
+
+### Full completion
+
+```tsx
+<Progress value={100} style={{ width: 400 }} />
+```
+
+### Vertical progress bar at 60%
+
+```tsx
+<Progress value={60} direction="vertical" style={{ width: 8, height: 200 }} />
+```
+
+## Dependencies
+
+- @emotion/react
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./progress.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/radio-button/README.md

@@ -0,0 +1,89 @@
+# RadioButton
+
+Component radio input được styled tùy chỉnh, render một label wrapper với checkmark visual. Hỗ trợ color variants cho brand và semantic theming, và chấp nhận tất cả các HTML input[type="radio"] attributes chuẩn.
+
+## Import
+
+```tsx
+import { RadioButton } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `color` | `ColorVariant` | `'primary'` | Điều khiển màu accent của radio button. Map tới design token color shades qua getColorShadesByVariant. |
+| `containerProps` | `PrimitiveProps<JSX.IntrinsicElements['label']>` | - | Props được forward tới outer label element (Primitive as='label'). Hỗ trợ sx cho responsive styles và tất cả standard label HTML attributes. |
+| `children` | `React.ReactNode` | - | Nội dung label được render bên cạnh radio button checkmark. |
+| `className` | `string` | - | CSS class names bổ sung được apply vào inner input element. |
+| `disabled` | `boolean` | `false` | Disable radio input, ngăn chặn interaction. |
+| `checked` | `boolean` | - | Controlled checked state của radio input. |
+| `defaultChecked` | `boolean` | - | Uncontrolled initial checked state của radio input. |
+| `onChange` | `React.ChangeEventHandler<HTMLInputElement>` | - | Change event handler được gọi khi radio selection thay đổi. |
+| `name` | `string` | - | Nhóm các radio buttons có cùng name để chỉ một button có thể được chọn tại một thời điểm. |
+| `value` | `string \| number \| readonly string[]` | - | Value được liên kết với radio button này khi submit trong form. |
+| `ref` | `React.Ref<HTMLInputElement>` | - | Ref được forward tới underlying input element. |
+
+## Examples
+
+### Default radio button
+
+```tsx
+<RadioButton onChange={handleChange} />
+```
+
+### Grouped radio buttons với color và label
+
+```tsx
+<>
+  <RadioButton name="delivery" value="standard" color="primary" defaultChecked onChange={handleChange}>
+    Giao hàng tiêu chuẩn
+  </RadioButton>
+  <RadioButton name="delivery" value="express" color="primary" onChange={handleChange}>
+    Giao hàng nhanh
+  </RadioButton>
+</>
+```
+
+### Error state và disabled
+
+```tsx
+<>
+  <RadioButton color="red" defaultChecked onChange={handleChange}>
+    Tùy chọn không hợp lệ
+  </RadioButton>
+  <RadioButton disabled defaultChecked onChange={handleChange}>
+    Tùy chọn không khả dụng
+  </RadioButton>
+</>
+```
+
+### Sử dụng containerProps để customize label
+
+```tsx
+<RadioButton
+  name="payment"
+  value="card"
+  color="blue"
+  containerProps={{
+    sx: { padding: '8px', border: '1px solid #ddd', borderRadius: '4px' }
+  }}
+>
+  Thanh toán qua thẻ
+</RadioButton>
+```
+
+## Related Components
+
+- [Primitive](../primitive/README.md)
+- [Checkbox](../checkbox/README.md)
+
+## Dependencies
+
+- @emotion/react
+
+## See Also
+
+- [Component Source](./radio-button.tsx)
+- [Storybook Stories](./radio-button.stories.ts)
+- [Types](./types.ts)

package/dist/lib/radio-button/radio-button.js

@@ -1,8 +1,8 @@
 import { jsxs, jsx } from "react/jsx-runtime";
 import { getRadioButtonProps } from "./helpers.js";
-import classes from "./radio-button.module.scss.js";
 import { getColorShadesByVariant } from "../../utils/index.js";
-import clsx from "clsx";
+import "lodash-es";
+import { getColorVar } from "../../theme/palette.js";
 import { Primitive } from "../primitive/primitive.js";
 const RadioButton = ({ ref, ..._props }) => {
   const { children, color = "primary", className, containerProps, ...props } = getRadioButtonProps(_props);
@@ -11,17 +11,108 @@ const RadioButton = ({ ref, ..._props }) => {
     Primitive,
     {
       ...containerProps,
-      className: clsx(classes.radio_button__container, containerProps == null ? void 0 : containerProps.className),
       sx: {
         "--radio-button-color": main,
+        display: "flex",
+        width: "fit-content",
+        maxWidth: "100%",
+        alignItems: "center",
+        gap: "0.5rem",
+        cursor: "pointer",
+        "&:has(input:disabled)": {
+          cursor: "default",
+          pointerEvents: "none"
+        },
+        '&:hover [data-radio-button-part="main"]': {
+          "--radio-button-checkmark-color": "var(--radio-button-color)",
+          '& [data-radio-button-part="checkmark"]': {
+            boxShadow: "0 1px 3px 0 currentColor, 0 1px 2px -1px currentColor"
+          }
+        },
         ...containerProps == null ? void 0 : containerProps.sx
       },
       as: "label",
       children: [
-        /* @__PURE__ */ jsxs("span", { className: classes.radio_button__main, children: [
-          /* @__PURE__ */ jsx("input", { ...props, className: clsx(classes.radio_button__input, className), type: "radio", ref }),
-          /* @__PURE__ */ jsx("span", { className: classes.radio_button__checkmark })
-        ] }),
+        /* @__PURE__ */ jsxs(
+          Primitive,
+          {
+            as: "span",
+            "data-radio-button-part": "main",
+            sx: {
+              "--radio-button-checkmark-color": getColorVar("neutral.600"),
+              "--radio-button-dot-scale": 0,
+              position: "relative",
+              display: "flex",
+              borderRadius: 9999,
+              padding: "0.125rem",
+              width: "1.5rem",
+              height: "1.5rem",
+              flexShrink: 0,
+              "&:has(input:checked)": {
+                "--radio-button-checkmark-color": "var(--radio-button-color)",
+                "--radio-button-dot-scale": 1
+              },
+              "&:has(input:disabled)": {
+                "--radio-button-checkmark-color": getColorVar("neutral.300")
+              }
+            },
+            children: [
+              /* @__PURE__ */ jsx(
+                Primitive,
+                {
+                  ...props,
+                  className,
+                  type: "radio",
+                  ref,
+                  as: "input",
+                  sx: {
+                    width: 0,
+                    height: 0,
+                    opacity: 0,
+                    display: "none"
+                  }
+                }
+              ),
+              /* @__PURE__ */ jsx(
+                Primitive,
+                {
+                  as: "span",
+                  "data-radio-button-part": "checkmark",
+                  sx: {
+                    color: "var(--radio-button-checkmark-color)",
+                    width: "100%",
+                    height: "100%",
+                    borderWidth: 1,
+                    borderStyle: "solid",
+                    borderColor: "currentColor",
+                    borderRadius: 9999,
+                    position: "relative",
+                    "&::after": {
+                      content: '""',
+                      position: "absolute",
+                      top: 0,
+                      right: 0,
+                      bottom: 0,
+                      left: 0,
+                      borderWidth: 2,
+                      borderStyle: "solid",
+                      backgroundClip: "content-box",
+                      width: "100%",
+                      height: "100%",
+                      borderRadius: 9999,
+                      transform: "scale(var(--radio-button-dot-scale))",
+                      transitionProperty: "transform",
+                      transitionTimingFunction: "cubic-bezier(0.4, 0, 0.2, 1)",
+                      transitionDuration: "300ms",
+                      borderColor: "transparent",
+                      backgroundColor: "currentColor"
+                    }
+                  }
+                }
+              )
+            ]
+          }
+        ),
         children
       ]
     }

package/dist/lib/ripple-effect/README.md

@@ -0,0 +1,66 @@
+# RippleEffect
+
+A presentational component that renders a Material-style ripple animation on pointer interactions. It attaches itself to its parent element and is used internally by interactive components like Button and IconButton.
+
+## Import
+
+```tsx
+import { RippleEffect } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `enabled` | `boolean` | `true` | Whether to enable the ripple effect. When false, the component renders nothing and no event listeners are attached. |
+| `color` | `string` | `'currentColor'` | CSS color value for the ripple circle. Accepts any valid CSS color string. |
+| `duration` | `number` | `400` | Duration of the ripple animation in milliseconds. |
+| `opacity` | `number` | `0.2` | Starting opacity of the ripple circle before it fades out. |
+| `sizeMultiplier` | `number` | `1` | Multiplier applied to the computed ripple radius. Values greater than 1 make the ripple larger relative to the parent element. |
+
+## Examples
+
+### Basic usage inside a button
+
+```tsx
+import { RippleEffect } from '@janbox/storefront-ui';
+
+const MyButton = () => (
+  <button style={{ position: 'relative', overflow: 'hidden' }}>
+    Click me
+    <RippleEffect />
+  </button>
+);
+```
+
+### Custom color and duration
+
+```tsx
+import { RippleEffect } from '@janbox/storefront-ui';
+
+const PrimaryButton = () => (
+  <button style={{ position: 'relative', overflow: 'hidden', backgroundColor: '#1976d2', color: '#fff' }}>
+    Submit
+    <RippleEffect color="#ffffff" opacity={0.3} duration={600} />
+  </button>
+);
+```
+
+### Disabled ripple conditionally
+
+```tsx
+import { RippleEffect } from '@janbox/storefront-ui';
+
+const ToggleButton = ({ disabled }: { disabled: boolean }) => (
+  <button style={{ position: 'relative', overflow: 'hidden' }} disabled={disabled}>
+    Toggle
+    <RippleEffect enabled={!disabled} />
+  </button>
+);
+```
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./rippleeffect.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/select/README.md

@@ -0,0 +1,124 @@
+# Select
+
+A dropdown select component that supports searchable filtering, virtualized option lists, controlled/uncontrolled state, and responsive sizing. It is built on top of InputMask and Floating UI, making it suitable for forms that need single-value selection from a list of options.
+
+## Import
+
+```tsx
+import { Select } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `options*` | `O[]` | - | Array of option objects to display in the dropdown list. |
+| `value` | `V \| null` | - | Controlled selected value. |
+| `defaultValue` | `V` | - | Default selected value for uncontrolled usage. |
+| `onChange` | `(value: V, option: O) => void` | - | Callback fired when the user selects an option. Receives both the selected value and the full option object. |
+| `placeholder` | `string` | - | Placeholder text shown when no option is selected. |
+| `searchable` | `boolean` | - | Enables a search input inside the dropdown. Defaults to `true` automatically when options count exceeds `displayRowCount`. |
+| `optionLabel` | `keyof O \| ((option: O) => React.ReactNode)` | `'label'` | Key or function to derive the display label from an option. |
+| `optionValue` | `keyof O \| ((option: O) => V)` | `'value'` | Key or function to derive the value from an option. |
+| `optionSearchLabel` | `keyof O \| Array<keyof O> \| ((option: O) => string \| string[])` | - | Key, array of keys, or function used to extract searchable text from an option. Falls back to `optionLabel` if not provided. |
+| `selectedRenderer` | `(option: O) => React.ReactNode` | - | Custom render function for the selected option displayed in the trigger button. |
+| `placement` | `Placement` | `'bottom-start'` | Floating UI placement for the dropdown panel. |
+| `open` | `boolean` | - | Controlled open state of the dropdown. |
+| `onOpenChange` | `UseFloatingOptions['onOpenChange']` | - | Callback fired when the dropdown open state changes. |
+| `error` | `boolean` | - | Puts the trigger input into an error visual state. |
+| `helperText` | `string` | - | Helper or validation message displayed below the select trigger. |
+| `displayRowCount` | `number` | `5` | Maximum number of rows visible in the dropdown list before scrolling. Use `Infinity` to show all options. |
+| `lazy` | `boolean` | `true` | When `true`, uses windowed/virtualized rendering for the option list. |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Size variant for the trigger input and option rows. Supports responsive breakpoint overrides via `sm`/`md`/`lg` props. |
+| `disabled` | `boolean` | - | Disables the select trigger, preventing interaction. |
+| `containerProps` | `PrimitiveProps<JSX.IntrinsicElements['div']>` | - | Props forwarded to the outer container `Primitive` div. |
+| `listProps` | `HTMLAttributes<HTMLDivElement>` | - | Props forwarded to the `VirtualizedList` container div. |
+| `inputProps` | `InputProps` | - | Props forwarded to the search `Input` rendered inside the dropdown when `searchable` is `true`. |
+| `css` | `Interpolation` | - | Emotion CSS interpolation applied to the `InputMask` trigger element. |
+| `sx` | `ToResponsiveProps<StyledCSS>` | - | Responsive sx prop for inline styles via Emotion (inherited from `InputMaskProps`). |
+
+*Required props
+
+## Examples
+
+### Default
+
+```tsx
+const options = [
+  { label: 'Apple', value: 'apple' },
+  { label: 'Banana', value: 'banana' },
+  { label: 'Cherry', value: 'cherry' },
+];
+
+<Select
+  options={options}
+  placeholder="Select a fruit..."
+  onChange={(value, option) => console.log(value, option)}
+/>
+```
+
+### Searchable with error state
+
+```tsx
+const options = [
+  { label: 'Apple', value: 'apple' },
+  { label: 'Banana', value: 'banana' },
+  { label: 'Cherry', value: 'cherry' },
+];
+
+<Select
+  options={options}
+  placeholder="Search and select..."
+  searchable
+  error
+  helperText="Please select an option"
+  onChange={(value) => console.log(value)}
+/>
+```
+
+### Controlled with custom optionLabel and selectedRenderer
+
+```tsx
+type Product = { id: number; name: string; price: number };
+
+const products: Product[] = [
+  { id: 1, name: 'Shirt', price: 29 },
+  { id: 2, name: 'Pants', price: 59 },
+];
+
+<Select<number, Product>
+  options={products}
+  optionValue="id"
+  optionLabel="name"
+  optionSearchLabel="name"
+  value={selectedId}
+  selectedRenderer={(p) => `${p.name} — $${p.price}`}
+  onChange={(id) => setSelectedId(id)}
+  size="lg"
+  placeholder="Pick a product"
+/>
+```
+
+## Related Components
+
+- [InputMask](../input-mask/README.md)
+- [Input](../input/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`
+- `@emotion/react`
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./select.stories.ts)
+- [Main README](../../README.md)

package/dist/lib/star-rating/README.md

@@ -0,0 +1,67 @@
+# StarRating
+
+Component SVG một ngôi sao hiển thị rating theo tỷ lệ phần trăm bằng kỹ thuật clip-path fill. Dùng để hiển thị điểm đánh giá sản phẩm hoặc review score, hỗ trợ giá trị thập phân và color variants.
+
+## Import
+
+```tsx
+import { StarRating } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `rating*` | `number` | - | Giá trị rating hiện tại. Kiểm soát mức độ tô màu ngôi sao qua clip-path. Hỗ trợ giá trị thập phân (VD: 2.5). |
+| `maxRating` | `number` | 5 | Giá trị rating tối đa. Dùng để tính phần trăm tô màu của ngôi sao. |
+| `size` | `number` | 24 | Chiều rộng và chiều cao của SVG tính bằng pixel. ViewBox nội bộ luôn là 24x24 nên giá trị này scale output. |
+| `colorVariant` | `ColorVariant` | `"secondary"` | Color variant dùng cho cả stroke và fill của ngôi sao. Ánh xạ tới design token color shades qua `getColorShadesByVariant`. |
+| `className` | `string` | - | CSS class name tùy chọn áp dụng lên root SVG element. |
+
+*Props bắt buộc
+
+## Examples
+
+### Mặc định (partial fill)
+
+```tsx
+<StarRating rating={3} />
+```
+
+### Nửa ngôi sao với kích thước tùy chỉnh
+
+```tsx
+<StarRating rating={2.5} size={32} />
+```
+
+### Max rating tùy chỉnh và color variant
+
+```tsx
+<StarRating rating={7} maxRating={10} colorVariant="primary" />
+```
+
+### Ngôi sao đầy và rỗng
+
+```tsx
+{/* Đầy hoàn toàn */}
+<StarRating rating={5} />
+
+{/* Rỗng hoàn toàn */}
+<StarRating rating={0} />
+```
+
+## Related Components
+
+- [Icon](../icon/README.md)
+
+## Dependencies
+
+- react (forwardRef, useId)
+- @/utils (getColorShadesByVariant)
+- @/types (ColorVariant)
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./star-rating.stories.tsx)
+- [Main README](../../README.md)