@janbox/storefront-ui 2.0.29 → 2.0.30

package/dist/lib/stepper/README.md

@@ -0,0 +1,99 @@
+# Stepper
+
+Component hiển thị tiến trình theo từng bước — dùng cho checkout flow, wizard, onboarding, hoặc bất kỳ quy trình nhiều bước nào.
+
+## Import
+
+```tsx
+import { Stepper } from '@janbox/storefront-ui';
+```
+
+## Props
+
+### StepperProps
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items*` | `StepProps[]` | - | Danh sách các bước |
+| `activeIndex` | `number` | `0` | Index của bước đang active |
+| `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | Hướng hiển thị |
+| `circleSize` | `number` | `32` | Kích thước circle của mỗi step (px) |
+| `className` | `string` | - | Custom class name |
+
+### StepProps
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `state` | `'done' \| 'active' \| 'normal'` | auto | Trạng thái của step (tự tính từ `activeIndex` nếu không set) |
+| `content` | `ReactNode` | - | Nội dung label của step |
+| `description` | `ReactNode` | - | Mô tả phụ bên dưới step |
+| `size` | `number` | - | Override circle size cho từng step riêng lẻ |
+
+*Required props
+
+## Examples
+
+### Cơ bản — Horizontal
+
+```tsx
+import { Stepper } from '@janbox/storefront-ui';
+
+const steps = [
+  { content: 'Giỏ hàng' },
+  { content: 'Thông tin' },
+  { content: 'Thanh toán' },
+  { content: 'Hoàn tất' },
+];
+
+<Stepper items={steps} activeIndex={1} />
+```
+
+### Với mô tả
+
+```tsx
+const steps = [
+  { content: 'Bước 1', description: 'Chọn sản phẩm' },
+  { content: 'Bước 2', description: 'Nhập địa chỉ' },
+  { content: 'Bước 3', description: 'Xác nhận đơn' },
+];
+
+<Stepper items={steps} activeIndex={2} />
+```
+
+### Vertical
+
+```tsx
+<Stepper
+  items={steps}
+  activeIndex={1}
+  direction="vertical"
+  circleSize={28}
+/>
+```
+
+### Controlled — cập nhật bước theo user action
+
+```tsx
+const [step, setStep] = useState(0);
+
+<Stepper items={steps} activeIndex={step} />
+
+<Button onClick={() => setStep(s => Math.min(s + 1, steps.length - 1))}>
+  Tiếp theo
+</Button>
+```
+
+## Notes
+
+- State của từng step được tính tự động từ `activeIndex`: bước trước → `done`, bước hiện tại → `active`, bước sau → `normal`
+- `Progress` component được dùng làm progress bar nền bên dưới các step
+- `circleSize` ảnh hưởng đến vị trí căn giữa của progress bar
+
+## Related Components
+
+- [Progress](../progress/README.md)
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Main README](../../README.md)

package/dist/lib/suspense-query/README.md

@@ -0,0 +1,78 @@
+# SuspenseQuery
+
+A generic component that combines React Suspense and ErrorBoundary to handle async data fetching declaratively. It manages promise lifecycle with dep-based re-fetching, providing a render-prop children pattern to consume the resolved data.
+
+## Import
+
+```tsx
+import { SuspenseQuery } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `factory*` | `(...args: A) => Promise<R>` | - | Async function that returns a Promise. Called on mount and whenever deps change (deep equality check). Receives the spread deps array as arguments. |
+| `children*` | `(data: R) => React.ReactNode` | - | Render-prop function called with the resolved data once the Promise resolves. Rendered inside Suspense so it only runs after data is available. |
+| `deps` | `A` | [] | Dependency array passed as arguments to factory. Required when factory takes arguments; optional (defaults to []) when factory takes no arguments. Re-triggers factory on deep-equality change. |
+| `LoadingComponent` | `ComponentType` | - | Optional component rendered as the Suspense fallback while the Promise is pending. If omitted, the fallback renders null. |
+| `ErrorComponent` | `ComponentType<FallbackProps>` | DefaultErrorComponent (logs error, renders nothing) | Component rendered by the ErrorBoundary when the Promise rejects or a render error occurs. Receives the react-error-boundary FallbackProps (error, resetErrorBoundary). Defaults to a silent component that logs the error to console. |
+
+*Required props
+
+## Examples
+
+### Basic usage — no arguments
+
+```tsx
+const fetchUser = () => fetch('/api/me').then(res => res.json());
+
+<SuspenseQuery factory={fetchUser}>
+  {(user) => <span>{user.name}</span>}
+</SuspenseQuery>
+```
+
+### With deps and custom loading/error components
+
+```tsx
+const fetchProduct = (id: string) => fetch(`/api/products/${id}`).then(r => r.json());
+
+<SuspenseQuery
+  factory={fetchProduct}
+  deps={[productId]}
+  LoadingComponent={() => <Skeleton />}
+  ErrorComponent={({ error }) => <Alert color="red">{error.message}</Alert>}
+>
+  {(product) => <ProductCard title={product.name} price={product.price} />}
+</SuspenseQuery>
+```
+
+### Multiple deps — re-fetches when any dep changes
+
+```tsx
+const searchItems = (query: string, page: number) =>
+  fetch(`/api/search?q=${query}&page=${page}`).then(r => r.json());
+
+<SuspenseQuery factory={searchItems} deps={[query, page]}>
+  {(result) => (
+    <ul>
+      {result.items.map(item => <li key={item.id}>{item.title}</li>)}
+    </ul>
+  )}
+</SuspenseQuery>
+```
+
+## Related Components
+
+- [ErrorBoundary](../errorboundary/README.md)
+
+## Dependencies
+
+- react-error-boundary
+- lodash-es
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./suspensequery.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/swiper/README.md

@@ -0,0 +1,99 @@
+# Swiper
+
+A responsive carousel/swiper component built on top of Embla Carousel, supporting touch gestures, wheel scroll, autoplay, and multiple paging styles. Used for displaying horizontally (or vertically) scrollable slide content such as product carousels and image galleries.
+
+## Import
+
+```tsx
+import { Swiper } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | Slide content — typically one or more SwiperSlide components. |
+| `slidesPerView` | `number \| 'auto'` | - | Number of slides visible at once at the base (mobile) breakpoint. Use `'auto'` to let each slide define its own width. |
+| `spaceBetween` | `number` | - | Gap in pixels between slides at the base (mobile) breakpoint. |
+| `sm` | `{ slidesPerView?: number \| 'auto'; spaceBetween?: number }` | - | Override `slidesPerView` và `spaceBetween` tại breakpoint sm (≥768px). |
+| `md` | `{ slidesPerView?: number \| 'auto'; spaceBetween?: number }` | - | Override `slidesPerView` và `spaceBetween` tại breakpoint md (≥1280px). |
+| `lg` | `{ slidesPerView?: number \| 'auto'; spaceBetween?: number }` | - | Override `slidesPerView` và `spaceBetween` tại breakpoint lg (≥1680px). |
+| `autoplayOptions` | `ShallowMerge<AutoplayOptionsType, { delay?: number }>` | `{ active: false, delay: 3000, stopOnFocusIn: false, stopOnInteraction: false, stopOnLastSnap: false }` | Embla Carousel Autoplay plugin options. Autoplay mặc định không kích hoạt. |
+| `options` | `Partial<SwiperOptions>` | - | Raw Embla Carousel options (e.g. `loop`, `axis`, `align`). Truyền thẳng vào `useEmblaCarousel`. Default `align` là `'start'`. |
+| `paging` | `{ type: 'dots'; color?: ColorVariant; size?: number; spaceBetween?: number; offset?: number } \| { type: 'side-arrows'; color?: ColorVariant; visibility?: 'auto' \| 'always'; anchorSelector?: string; size?: number; offsetX?: number \| 'center'; offsetY?: number \| 'center' }` | - | Cấu hình paging control. Dùng `'dots'` cho dải chấm tròn bên dưới slides, hoặc `'side-arrows'` cho nút prev/next ở hai bên. |
+| `onApi` | `(api: EmblaCarouselType) => void` | - | Callback khi Embla Carousel API instance sẵn sàng, cho phép truy cập trực tiếp các carousel methods. |
+| `sx` | `ToResponsiveProps<StyledCSS>` | - | Responsive style overrides áp dụng lên root container của swiper. |
+| `ref` | `React.Ref<HTMLDivElement>` | - | Forwarded ref đến root container element (cũng được forward vào Embla's ref). |
+
+## Examples
+
+### Basic carousel with dot paging
+
+```tsx
+<Swiper spaceBetween={20} paging={{ type: 'dots' }} sx={{ width: 300, sm: { width: 500 } }}>
+  <SwiperSlide style={{ width: 200, height: 200, background: 'orange' }}>Slide 1</SwiperSlide>
+  <SwiperSlide style={{ width: 200, height: 200, background: 'orange' }}>Slide 2</SwiperSlide>
+  <SwiperSlide style={{ width: 200, height: 200, background: 'orange' }}>Slide 3</SwiperSlide>
+</Swiper>
+```
+
+### Product carousel with side arrows and responsive slides per view
+
+```tsx
+<Swiper
+  slidesPerView={2}
+  spaceBetween={16}
+  sm={{ slidesPerView: 3, spaceBetween: 20 }}
+  md={{ slidesPerView: 4, spaceBetween: 24 }}
+  paging={{
+    type: 'side-arrows',
+    anchorSelector: '.product-image',
+    visibility: 'auto',
+    color: 'primary',
+  }}
+>
+  {products.map((p) => (
+    <SwiperSlide key={p.id}>
+      <img className="product-image" src={p.image} alt={p.name} />
+      <p>{p.name}</p>
+    </SwiperSlide>
+  ))}
+</Swiper>
+```
+
+### Autoplay banner with loop enabled
+
+```tsx
+<Swiper
+  slidesPerView={1}
+  options={{ loop: true }}
+  autoplayOptions={{ active: true, delay: 4000 }}
+  paging={{ type: 'dots', color: 'primary', offset: 12 }}
+  sx={{ width: '100%' }}
+>
+  <SwiperSlide><img src="/banner1.jpg" alt="Banner 1" /></SwiperSlide>
+  <SwiperSlide><img src="/banner2.jpg" alt="Banner 2" /></SwiperSlide>
+  <SwiperSlide><img src="/banner3.jpg" alt="Banner 3" /></SwiperSlide>
+</Swiper>
+```
+
+## Related Components
+
+- [SwiperSlide](../swiperslide/README.md)
+- [SwiperDotsPaging](../swiperdotspaging/README.md)
+- [SwiperSideArrowsPaging](../swipersidearrowspaging/README.md)
+
+## Dependencies
+
+- embla-carousel
+- embla-carousel-react
+- embla-carousel-autoplay
+- embla-carousel-wheel-gestures
+- @floating-ui/react
+- lodash-es
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./swiper.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/switch/README.md

@@ -0,0 +1,73 @@
+# Switch
+
+A toggle switch component built on a native checkbox input, styled as a sliding toggle. Use it for binary on/off settings where users expect immediate visual feedback without a form submission.
+
+## Import
+
+```tsx
+import { Switch } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `color` | `ColorVariant` | `'primary'` | Color variant for the checked state. Accepts `'primary'` \| `'secondary'` \| `'green'` \| `'red'` \| `'orange'` \| `'blue'` \| `'neutral'`. |
+| `checked` | `boolean` | - | Controlled checked state of the switch. |
+| `defaultChecked` | `boolean` | `false` | Initial checked state for uncontrolled usage. |
+| `disabled` | `boolean` | `false` | Disables the switch and prevents interaction. Renders the knob in a neutral gray and suppresses pointer events. |
+| `onChange` | `React.ChangeEventHandler<HTMLInputElement>` | - | Change handler fired when the switch is toggled. |
+| `children` | `React.ReactNode` | - | Optional label content rendered to the right of the toggle. |
+| `className` | `string` | - | Additional CSS class applied to the underlying checkbox input. |
+| `ref` | `React.Ref<HTMLInputElement>` | - | Forwarded ref to the underlying checkbox input element. |
+
+Inherits all standard `<input type="checkbox">` HTML attributes.
+
+## Examples
+
+### Default (uncontrolled)
+
+```tsx
+<Switch onChange={(e) => console.log(e.target.checked)} />
+```
+
+### Pre-checked with green color and label
+
+```tsx
+<Switch color="green" defaultChecked>
+  Enable notifications
+</Switch>
+```
+
+### Disabled states
+
+```tsx
+<div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
+  <Switch disabled>Disabled off</Switch>
+  <Switch disabled defaultChecked>Disabled on</Switch>
+</div>
+```
+
+### Controlled usage
+
+```tsx
+const [enabled, setEnabled] = useState(false);
+
+<Switch 
+  checked={enabled} 
+  onChange={(e) => setEnabled(e.target.checked)}
+>
+  Dark mode
+</Switch>
+```
+
+## Dependencies
+
+- `@floating-ui/react` (useMergeRefs)
+
+## See Also
+
+- [Component Source](./switch.tsx)
+- [Types](./types.ts)
+- [Storybook Stories](./switch.stories.ts)
+- [Main README](../../README.md)

package/dist/lib/switch/switch.d.ts

@@ -1,2 +1,2 @@
 import { SwitchProps } from './types';
-export declare const Switch: ({ children, className, ref, ...props }: SwitchProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Switch: ({ children, className, color, ref, ...props }: SwitchProps) => import("react/jsx-runtime").JSX.Element;

package/dist/lib/switch/switch.js

@@ -1,15 +1,114 @@
 import { jsxs, jsx } from "react/jsx-runtime";
-import { useRef } from "react";
-import { useMergeRefs } from "@floating-ui/react";
-import classes from "./switch.module.scss.js";
-import { clsx } from "clsx";
-const Switch = ({ children, className, ref, ...props }) => {
-  const inputRef = useRef(null);
-  const mergedRefs = useMergeRefs([ref, inputRef]);
-  return /* @__PURE__ */ jsxs("label", { className: classes.switch__container, children: [
-    /* @__PURE__ */ jsx("span", { className: classes.switch__main, children: /* @__PURE__ */ jsx("input", { ...props, type: "checkbox", className: clsx(classes.switch__input, className), ref: mergedRefs }) }),
-    children
-  ] });
+import "lodash-es";
+import { getColorVar } from "../../theme/palette.js";
+import { Primitive } from "../primitive/primitive.js";
+const Switch = ({ children, className, color = "primary", ref, ...props }) => {
+  return /* @__PURE__ */ jsxs(
+    Primitive,
+    {
+      as: "label",
+      sx: {
+        display: "flex",
+        alignItems: "center",
+        gap: "0.5rem",
+        cursor: "pointer",
+        width: "fit-content",
+        maxWidth: "100%",
+        paddingLeft: "0.125rem",
+        paddingRight: "0.125rem",
+        "&:has(input:disabled)": {
+          cursor: "default",
+          pointerEvents: "none"
+        },
+        '&:hover [data-switch-part="main"]': {
+          "--switch-track-background": getColorVar("neutral.300"),
+          "--switch-thumb-shadow": "0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1)"
+        },
+        '&:hover [data-switch-part="main"]:has(input:checked)': {
+          "--switch-track-background": getColorVar(`${color}.500`),
+          "--switch-thumb-shadow": `0 1px 3px 0 ${getColorVar(`${color}.600`)}, 0 1px 2px -1px ${getColorVar(
+            `${color}.600`
+          )}`
+        }
+      },
+      children: [
+        /* @__PURE__ */ jsx(
+          Primitive,
+          {
+            as: "span",
+            "data-switch-part": "main",
+            sx: {
+              "--switch-track-background": getColorVar("neutral.300"),
+              "--switch-thumb-background": "white",
+              "--switch-thumb-left": "0",
+              "--switch-thumb-transform": "translateY(-50%)",
+              "--switch-thumb-shadow": "none",
+              position: "relative",
+              width: "2rem",
+              height: "1.5rem",
+              "&::before": {
+                position: "absolute",
+                left: 0,
+                right: 0,
+                content: '""',
+                backgroundColor: "var(--switch-track-background)",
+                height: "1rem",
+                top: "50%",
+                transform: "translateY(-50%)",
+                borderRadius: 9999,
+                transition: "all 150ms cubic-bezier(0.4, 0, 0.2, 1)"
+              },
+              "&::after": {
+                position: "absolute",
+                left: "var(--switch-thumb-left)",
+                aspectRatio: 1,
+                content: '""',
+                backgroundColor: "var(--switch-thumb-background)",
+                height: "1.25rem",
+                top: "50%",
+                transform: "var(--switch-thumb-transform)",
+                borderRadius: 9999,
+                borderWidth: 1,
+                borderStyle: "solid",
+                borderColor: `var(--switch-thumb-border-color, ${getColorVar("border.default")})`,
+                boxShadow: "var(--switch-thumb-shadow)",
+                transition: "all 150ms cubic-bezier(0.4, 0, 0.2, 1)"
+              },
+              "&:has(input:checked)": {
+                "--switch-track-background": getColorVar(`${color}.400`),
+                "--switch-thumb-background": getColorVar(`${color}.600`),
+                "--switch-thumb-border-color": getColorVar(`${color}.600`),
+                "--switch-thumb-left": "100%",
+                "--switch-thumb-transform": "translateX(-100%) translateY(-50%)"
+              },
+              "&:has(input:disabled)": {
+                "--switch-track-background": getColorVar("neutral.300"),
+                "--switch-thumb-background": getColorVar("neutral.400"),
+                "--switch-thumb-border-color": getColorVar("neutral.400")
+              }
+            },
+            children: /* @__PURE__ */ jsx(
+              Primitive,
+              {
+                ...props,
+                type: "checkbox",
+                className,
+                ref,
+                as: "input",
+                sx: {
+                  width: 0,
+                  height: 0,
+                  opacity: 0,
+                  display: "none"
+                }
+              }
+            )
+          }
+        ),
+        children
+      ]
+    }
+  );
 };
 export {
   Switch

package/dist/lib/table/README.md

@@ -0,0 +1,115 @@
+# Table
+
+A semantic HTML table component with composable sub-components for building data tables. Includes Table, TableHead, TableBody, TableFooter, TableRow, and TableCell components with built-in styling and sx prop support.
+
+## Import
+
+```tsx
+import { Table } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children*` | `React.ReactNode` | - | Table content, typically TableHead, TableBody, and optionally TableFooter components |
+| `sx` | `StyledCSS \| ToResponsiveProps<StyledCSS>` | - | Custom styles using Emotion CSS-in-JS with responsive breakpoint support (sm, md, lg) |
+| `style` | `React.CSSProperties` | - | Inline styles for the table element |
+| `className` | `string` | - | Additional CSS class names |
+
+*Required props
+
+## Examples
+
+### Basic Table
+
+```tsx
+<Table style={{ width: 600, borderCollapse: 'collapse' }}>
+  <TableHead>
+    <TableRow>
+      <TableCell style={{ fontWeight: 'bold' }}>Name</TableCell>
+      <TableCell style={{ fontWeight: 'bold' }}>Age</TableCell>
+      <TableCell style={{ fontWeight: 'bold' }}>Email</TableCell>
+    </TableRow>
+  </TableHead>
+  <TableBody>
+    <TableRow>
+      <TableCell>Alice</TableCell>
+      <TableCell>28</TableCell>
+      <TableCell>alice@example.com</TableCell>
+    </TableRow>
+    <TableRow>
+      <TableCell>Bob</TableCell>
+      <TableCell>34</TableCell>
+      <TableCell>bob@example.com</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+### Table with Footer
+
+```tsx
+<Table style={{ width: 400, borderCollapse: 'collapse' }}>
+  <TableHead>
+    <TableRow>
+      <TableCell style={{ fontWeight: 'bold' }}>Item</TableCell>
+      <TableCell style={{ fontWeight: 'bold' }}>Price</TableCell>
+    </TableRow>
+  </TableHead>
+  <TableBody>
+    <TableRow>
+      <TableCell>Apple</TableCell>
+      <TableCell>$1.00</TableCell>
+    </TableRow>
+    <TableRow>
+      <TableCell>Banana</TableCell>
+      <TableCell>$0.50</TableCell>
+    </TableRow>
+  </TableBody>
+  <TableFooter>
+    <TableRow>
+      <TableCell style={{ fontWeight: 'bold' }}>Total</TableCell>
+      <TableCell style={{ fontWeight: 'bold' }}>$1.50</TableCell>
+    </TableRow>
+  </TableFooter>
+</Table>
+```
+
+### Table with Custom Styling
+
+```tsx
+<Table sx={{ backgroundColor: 'var(--color-neutral-50)', borderRadius: '8px' }}>
+  <TableHead>
+    <TableRow>
+      <TableCell sx={{ color: 'var(--color-primary-600)' }}>Product</TableCell>
+      <TableCell sx={{ color: 'var(--color-primary-600)' }}>Status</TableCell>
+    </TableRow>
+  </TableHead>
+  <TableBody>
+    <TableRow>
+      <TableCell>Product A</TableCell>
+      <TableCell>In Stock</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+## Related Components
+
+- [TableHead](../tablehead/README.md)
+- [TableBody](../tablebody/README.md)
+- [TableFooter](../tablefooter/README.md)
+- [TableRow](../tablerow/README.md)
+- [TableCell](../tablecell/README.md)
+- [Primitive](../primitive/README.md)
+
+## Dependencies
+
+- @emotion/react
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./table.stories.tsx)
+- [Main README](../../README.md)