@janbox/storefront-ui 4.0.17 → 5.0.1

package/README.md

@@ -140,12 +140,7 @@ export const Button = ({ ref, ..._props }: ButtonProps) => {
   const { size, variant, color, children, ...rest } = getButtonProps(_props);
 
   // 2. Build CSS từ helpers
-  const css = [
-    getButtonCssBySize(size),
-    getButtonCssByVariant(variant),
-    getButtonCssByColor(color),
-    createSxInterpolation(sx),
-  ];
+  const css = [getButtonCssBySize(size), getButtonCssByVariant(variant), getButtonCssByColor(color), createSxStyle(sx)];
 
   // 3. Render với Primitive hoặc native element
   return (
@@ -287,12 +282,12 @@ Hầu hết components hỗ trợ 4 size variants:
 
 **Size mapping:**
 
-| size | iconSize | inputSize | inputPaddingX | textVariant |
-| ---- | -------- | --------- | ------------- | ----------- |
-| `xs` | 20px     | 24px      | 8px           | `xs`        |
-| `sm` | 20px     | 32px      | 12px          | `sm`        |
-| `md` | 24px     | 40px      | 12px          | `sm`        |
-| `lg` | 24px     | 48px      | 16px          | `base`      |
+| size | iconSize | inputSize | inputPaddingInline | textVariant |
+| ---- | -------- | --------- | ------------------ | ----------- |
+| `xs` | 20px     | 24px      | 8px                | `xs`        |
+| `sm` | 20px     | 32px      | 12px               | `sm`        |
+| `md` | 24px     | 40px      | 12px               | `sm`        |
+| `lg` | 24px     | 48px      | 16px               | `base`      |
 
 ### Color Variants
 

package/dist/components/scroll-view.js

@@ -1,6 +1,6 @@
 import { jsx } from "react/jsx-runtime";
-import { Stylesheet } from "../lib/stylesheet/stylesheet.js";
 import { OverlayScrollbarsComponent } from "overlayscrollbars-react";
+import { Stylesheet } from "../lib/stylesheet/stylesheet.js";
 const ScrollView = ({ children, options, sx, ...props }) => {
   return /* @__PURE__ */ jsx(Stylesheet, { children: ({ cx, css }) => /* @__PURE__ */ jsx(
     OverlayScrollbarsComponent,

package/dist/index.js

@@ -89,8 +89,9 @@ import { SwiperSlide } from "./lib/swiper/swiper-slide/swiper-slide.js";
 import { Switch } from "./lib/switch/switch.js";
 import { Tab } from "./lib/tabs/tab/tab.js";
 import { TabContent } from "./lib/tabs/tab-content/tab-content.js";
-import { TabIndexContext, useTabIndexContext } from "./lib/tabs/tab/helpers.js";
+import { TabIndexContext, useGetTabProps, useTabIndexContext } from "./lib/tabs/tab/helpers.js";
 import { TabList } from "./lib/tabs/tab-list/tab-list.js";
+import { TabListContext, getTabListProps, useTabListContext } from "./lib/tabs/tab-list/helpers.js";
 import { TabPanel } from "./lib/tabs/tab-panel/tab-panel.js";
 import { Table } from "./lib/table/table/table.js";
 import { TableBody } from "./lib/table/table-body/table-body.js";
@@ -135,7 +136,6 @@ import { getPriceLabelProps } from "./lib/price-label/helpers.js";
 import { getRadioButtonProps } from "./lib/radio-button/helpers.js";
 import { getStarRatingProps } from "./lib/star-rating/helpers.js";
 import { getSwiperProps } from "./lib/swiper/swiper/helpers.js";
-import { getTabListProps } from "./lib/tabs/tab-list/helpers.js";
 import { getTabPanelProps } from "./lib/tabs/tab-panel/helpers.js";
 import { getTextCssByVariant, getTextProps } from "./lib/text/helpers.js";
 import { getTextareaProps } from "./lib/textarea/helpers.js";
@@ -241,6 +241,7 @@ export {
   TabContent,
   TabIndexContext,
   TabList,
+  TabListContext,
   TabPanel,
   Table,
   TableBody,
@@ -308,8 +309,10 @@ export {
   useDialogContext,
   useDrawerContext,
   useFloatingContext,
+  useGetTabProps,
   useNotifications,
   usePopoverContext,
   useTabIndexContext,
+  useTabListContext,
   useTabsContext
 };

package/dist/lib/accordion/accordion-content/accordion-content.js

@@ -3,8 +3,8 @@ import { useRef } from "react";
 import { motion } from "motion/react";
 import { getAccordionContentProps } from "./helpers.js";
 import { useAccordionContext } from "../accordion/helpers.js";
-import { Stylesheet } from "../../stylesheet/stylesheet.js";
 import { useAccordionGroupContext } from "../accordion-group/helpers.js";
+import { Stylesheet } from "../../stylesheet/stylesheet.js";
 import { Primitive } from "../../primitive/primitive.js";
 const AccordionContent = ({ children, ref, ..._props }) => {
   const { accordionContentProps: accordionContentPropsByGroup = {} } = useAccordionGroupContext();

package/dist/lib/button/button.js

@@ -8,7 +8,7 @@ import LoadingIcon from "../../assets/svg/loading-waiting.svg.js";
 import { mediaQuery } from "../../theme/screens.js";
 import { getColorVar } from "../../theme/palette.js";
 import { getColorShadesByVariant, getSizeVariantState } from "../../utils/index.js";
-import { createSxInterpolation } from "../../utils/stylesheet.js";
+import { createSxStyle } from "../../utils/stylesheet.js";
 import { RippleEffect } from "../ripple-effect/ripple-effect.js";
 import { Icon } from "../icon/icon.js";
 import { Primitive } from "../primitive/primitive.js";
@@ -114,7 +114,7 @@ const Button = ({ children, ref, ..._props }) => {
       [mediaQuery("md")]: createStyle(md),
       [mediaQuery("lg")]: createStyle(lg)
     },
-    createSxInterpolation(sx)
+    createSxStyle(sx)
   ];
   const onClick = (e) => {
     var _a;
@@ -133,7 +133,7 @@ const Button = ({ children, ref, ..._props }) => {
       try {
         const url = new URL(href);
         window.location.href = url.toString();
-      } catch (error) {
+      } catch (_error) {
         navigate(href, otherOptions);
       }
     }

package/dist/lib/button/helpers.js

@@ -16,10 +16,10 @@ const defaultProps = {
   type: "button"
 };
 const getButtonCssBySize = (size) => {
-  const { inputSize, inputPaddingX } = getSizeVariantState(size);
+  const { inputSize, inputPaddingInline } = getSizeVariantState(size);
   const css = {
-    paddingLeft: inputPaddingX,
-    paddingRight: inputPaddingX,
+    paddingLeft: inputPaddingInline,
+    paddingRight: inputPaddingInline,
     minHeight: inputSize
   };
   switch (size) {

package/dist/lib/cascader/cascader-floating-content.js

@@ -160,7 +160,7 @@ const CascaderFloatingContent = ({
     });
   }, [inputValue, currentOptions]);
   const responsiveSize = isNil(windowScreen.name) ? void 0 : getResponsiveProp({ sm, md, lg }, "size", windowScreen.name) ?? size;
-  const { inputSize: rowMinHeight = 0, inputPaddingX } = getSizeVariantState(responsiveSize);
+  const { inputSize: rowMinHeight = 0, inputPaddingInline } = getSizeVariantState(responsiveSize);
   const onInputChange = (e) => {
     var _a;
     e.target.value = trimStart(e.target.value);
@@ -193,8 +193,8 @@ const CascaderFloatingContent = ({
       Primitive,
       {
         sx: {
-          paddingLeft: inputPaddingX,
-          paddingRight: inputPaddingX,
+          paddingLeft: inputPaddingInline,
+          paddingRight: inputPaddingInline,
           minHeight: rowMinHeight,
           borderTop: `1px solid ${getColorVar("neutral.200")}`,
           display: "flex",
@@ -292,8 +292,8 @@ const CascaderFloatingContent = ({
         onClick: handleSelect,
         sx: {
           minHeight: rowMinHeight,
-          paddingLeft: inputPaddingX,
-          paddingRight: inputPaddingX,
+          paddingLeft: inputPaddingInline,
+          paddingRight: inputPaddingInline,
           paddingBlock: 4,
           display: "flex",
           alignItems: "center",

package/dist/lib/chip/chip.js

@@ -42,10 +42,10 @@ const Chip = ({ children, ..._props }) => {
   );
 };
 const createStyle = ({ size } = {}) => {
-  const { inputSize, inputPaddingX, textVariant, rounded } = getChipSizeState(size);
+  const { inputSize, paddingInline, textVariant, rounded } = getChipSizeState(size);
   return {
-    paddingLeft: inputPaddingX,
-    paddingRight: inputPaddingX,
+    paddingLeft: paddingInline,
+    paddingRight: paddingInline,
     minHeight: inputSize,
     fontSize: textVariant ? getTypographyVar(textVariant).fontSize : void 0,
     lineHeight: textVariant ? getTypographyVar(textVariant).lineHeight : void 0,

package/dist/lib/chip/helpers.d.ts

@@ -3,7 +3,7 @@ import { TypographySizeVariant } from '../../theme';
 import { ChipProps } from './types';
 export declare const getChipSizeState: (size?: SizeVariant) => Partial<{
     inputSize: number;
-    inputPaddingX: number;
+    paddingInline: number;
     textVariant: TypographySizeVariant;
     rounded: number;
 }>;

package/dist/lib/chip/helpers.js

@@ -6,13 +6,13 @@ const defaultProps = {
 const getChipSizeState = (size) => {
   switch (size) {
     case "xs":
-      return { inputSize: 20, inputPaddingX: 6, textVariant: "xs", rounded: 4 };
+      return { inputSize: 20, paddingInline: 6, textVariant: "xs", rounded: 4 };
     case "sm":
-      return { inputSize: 24, inputPaddingX: 8, textVariant: "xs", rounded: 6 };
+      return { inputSize: 24, paddingInline: 8, textVariant: "xs", rounded: 6 };
     case "md":
-      return { inputSize: 28, inputPaddingX: 10, textVariant: "sm", rounded: 8 };
+      return { inputSize: 28, paddingInline: 10, textVariant: "sm", rounded: 8 };
     case "lg":
-      return { inputSize: 32, inputPaddingX: 12, textVariant: "sm", rounded: 8 };
+      return { inputSize: 32, paddingInline: 12, textVariant: "sm", rounded: 8 };
     default:
       return {};
   }

package/dist/lib/count-up/count-up.js

@@ -7,9 +7,9 @@ import { useTranslation } from "../../i18n/index.js";
 import "lodash-es";
 import "../../theme/palette.js";
 import { getTypographyVar } from "../../theme/typography.js";
-import { Stylesheet } from "../stylesheet/stylesheet.js";
 import { getCountUpProps } from "./helpers.js";
 import { getDecimalDigits } from "../../utils/common.js";
+import { Stylesheet } from "../stylesheet/stylesheet.js";
 const CountUp = ({ ref, ..._props }) => {
   const {
     from = 0,

package/dist/lib/date-picker/date-picker.js

@@ -11,7 +11,7 @@ import "lodash-es";
 import { getColorVar } from "../../theme/palette.js";
 import { getTypographyVar } from "../../theme/typography.js";
 import CloseIcon from "../../assets/svg/times-close-delete.svg.js";
-import { createSxInterpolation } from "../../utils/stylesheet.js";
+import { createSxStyle } from "../../utils/stylesheet.js";
 import { TimePicker } from "../time-picker/time-picker.js";
 import { Floating } from "../floating/floating/floating.js";
 import { FloatingTrigger } from "../floating/floating-trigger/floating-trigger.js";
@@ -193,8 +193,8 @@ const DatePicker = (_props, ref) => {
           flexDirection: "column",
           width: "100%"
         },
-        createSxInterpolation(sx),
-        createSxInterpolation(containerSx)
+        createSxStyle(sx),
+        createSxStyle(containerSx)
       ],
       children: [
         /* @__PURE__ */ jsxs(

package/dist/lib/drawer/drawer/drawer.js

@@ -1,10 +1,10 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import { useMemo } from "react";
 import { motion } from "motion/react";
-import { Stylesheet } from "../../stylesheet/stylesheet.js";
 import { Floating } from "../../floating/floating/floating.js";
 import { FloatingContent } from "../../floating/floating-content/floating-content.js";
 import { Primitive } from "../../primitive/primitive.js";
+import { Stylesheet } from "../../stylesheet/stylesheet.js";
 const Drawer = ({ children, placement = "left", ...props }) => {
   const initial = useMemo(() => {
     switch (placement) {

package/dist/lib/floating/floating-content/floating-content.js

@@ -4,8 +4,8 @@ import { motion, AnimatePresence } from "motion/react";
 import { useFloatingContext } from "../floating/helpers.js";
 import { FLOATING_Z_INDEX } from "../../../theme/index.js";
 import { useIsHydrated } from "../../../hooks/use-is-hydrated/index.js";
-import { Stylesheet } from "../../stylesheet/stylesheet.js";
 import { usePortalContainer } from "../../../theme/provider.js";
+import { Stylesheet } from "../../stylesheet/stylesheet.js";
 const FloatingContent = ({ preserveTabOrder, focus, overlay, sx, ref, ...props }) => {
   const { getFloatingProps, context } = useFloatingContext();
   const mergedRefs = useMergeRefs([context.refs.setFloating, ref]);

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

@@ -1,6 +1,6 @@
 import { jsxs, jsx } from "@emotion/react/jsx-runtime";
 import { getIconButtonProps } from "./helpers.js";
-import { createSxInterpolation } from "../../utils/stylesheet.js";
+import { createSxStyle } from "../../utils/stylesheet.js";
 import LoadingIcon from "../../assets/svg/loading-waiting.svg.js";
 import { mediaQuery } from "../../theme/screens.js";
 import { getColorVar } from "../../theme/palette.js";
@@ -92,7 +92,7 @@ const IconButton = ({ children, ref, ..._props }) => {
       [mediaQuery("md")]: createStyle(md),
       [mediaQuery("lg")]: createStyle(lg)
     },
-    createSxInterpolation(sx)
+    createSxStyle(sx)
   ];
   const onClick = (e) => {
     var _a;

package/dist/lib/input/input.js

@@ -252,10 +252,10 @@ const Input = ({ ref, ..._props }) => {
   );
 };
 const createStyle = ({ size } = {}) => {
-  const { inputPaddingX, inputSize, textVariant } = getSizeVariantState(size);
+  const { inputPaddingInline, inputSize, textVariant } = getSizeVariantState(size);
   return {
-    paddingLeft: inputPaddingX,
-    paddingRight: inputPaddingX,
+    paddingLeft: inputPaddingInline,
+    paddingRight: inputPaddingInline,
     height: inputSize,
     fontSize: textVariant ? getTypographyVar(textVariant).fontSize : void 0,
     lineHeight: textVariant ? getTypographyVar(textVariant).lineHeight : void 0

package/dist/lib/input-mask/input-mask.js

@@ -4,7 +4,7 @@ import { getInputMaskProps } from "./helpers.js";
 import { mediaQuery } from "../../theme/screens.js";
 import { getColorVar } from "../../theme/palette.js";
 import { getSizeVariantState } from "../../utils/index.js";
-import { createSxInterpolation } from "../../utils/stylesheet.js";
+import { createSxStyle } from "../../utils/stylesheet.js";
 import { Primitive } from "../primitive/primitive.js";
 import { Icon } from "../icon/icon.js";
 const InputMask = (_props, ref) => {
@@ -37,7 +37,7 @@ const InputMask = (_props, ref) => {
       [mediaQuery("md")]: createStyle(md),
       [mediaQuery("lg")]: createStyle(lg)
     },
-    createSxInterpolation(sx)
+    createSxStyle(sx)
   ];
   return /* @__PURE__ */ jsxs(Primitive, { css, ...props, ref, children: [
     prefix,
@@ -85,12 +85,12 @@ const InputMask = (_props, ref) => {
 };
 const ForwardRefInputMask = forwardRef(InputMask);
 const createStyle = ({ size, outline } = {}) => {
-  const { inputSize, inputPaddingX } = getSizeVariantState(size);
+  const { inputSize, inputPaddingInline } = getSizeVariantState(size);
   return [
     {
       minHeight: inputSize,
-      paddingLeft: inputPaddingX,
-      paddingRight: inputPaddingX,
+      paddingLeft: inputPaddingInline,
+      paddingRight: inputPaddingInline,
       ":after": {
         borderTopWidth: outline == null ? void 0 : outline.top,
         borderRightWidth: outline == null ? void 0 : outline.right,

package/dist/lib/input-range/input-range.js

@@ -64,8 +64,8 @@ const InputRange = ({ ref: _ref, ..._props }) => {
           borderStyle: "solid",
           borderRadius: "0.5rem",
           gap: "0.5rem",
-          paddingLeft: getSizeVariantState(size).inputPaddingX,
-          paddingRight: getSizeVariantState(size).inputPaddingX,
+          paddingLeft: getSizeVariantState(size).inputPaddingInline,
+          paddingRight: getSizeVariantState(size).inputPaddingInline,
           "&:has(input:focus)": {
             borderColor: getColorVar("primary.600"),
             boxShadow: `0 1px 3px 0 ${getColorVar("primary.300")}, 0 1px 2px -1px ${getColorVar("primary.300")}`
@@ -74,16 +74,16 @@ const InputRange = ({ ref: _ref, ..._props }) => {
             borderColor: getColorVar("primary.300")
           },
           sm: {
-            paddingLeft: getSizeVariantState(sm == null ? void 0 : sm.size).inputPaddingX,
-            paddingRight: getSizeVariantState(sm == null ? void 0 : sm.size).inputPaddingX
+            paddingLeft: getSizeVariantState(sm == null ? void 0 : sm.size).inputPaddingInline,
+            paddingRight: getSizeVariantState(sm == null ? void 0 : sm.size).inputPaddingInline
           },
           md: {
-            paddingLeft: getSizeVariantState(md == null ? void 0 : md.size).inputPaddingX,
-            paddingRight: getSizeVariantState(md == null ? void 0 : md.size).inputPaddingX
+            paddingLeft: getSizeVariantState(md == null ? void 0 : md.size).inputPaddingInline,
+            paddingRight: getSizeVariantState(md == null ? void 0 : md.size).inputPaddingInline
           },
           lg: {
-            paddingLeft: getSizeVariantState(lg == null ? void 0 : lg.size).inputPaddingX,
-            paddingRight: getSizeVariantState(lg == null ? void 0 : lg.size).inputPaddingX
+            paddingLeft: getSizeVariantState(lg == null ? void 0 : lg.size).inputPaddingInline,
+            paddingRight: getSizeVariantState(lg == null ? void 0 : lg.size).inputPaddingInline
           }
         },
         children: [

package/dist/lib/lightbox/lightbox.js

@@ -10,12 +10,12 @@ import ZoomPlusIcon from "../../assets/svg/search-add-plus-middle.svg.js";
 import ZoomMinusIcon from "../../assets/svg/search-minus.svg.js";
 import CloseIcon from "../../assets/svg/times-close-delete.svg.js";
 import { FLOATING_Z_INDEX } from "../../theme/index.js";
-import { Stylesheet } from "../stylesheet/stylesheet.js";
 import { Swiper } from "../swiper/swiper/swiper.js";
 import { SwiperSlide } from "../swiper/swiper-slide/swiper-slide.js";
 import { Floating } from "../floating/floating/floating.js";
 import { FloatingContent } from "../floating/floating-content/floating-content.js";
 import { Primitive } from "../primitive/primitive.js";
+import { Stylesheet } from "../stylesheet/stylesheet.js";
 import { Image } from "../image/image.js";
 import { FloatingClose } from "../floating/floating-close/floating-close.js";
 import { IconButton } from "../icon-button/icon-button.js";

package/dist/lib/loading/image-skeleton/image-skeleton.js

@@ -1,9 +1,9 @@
 import { jsx } from "react/jsx-runtime";
 import { animatePulseStyle } from "../../../constants/emotion.js";
-import { Stylesheet } from "../../stylesheet/stylesheet.js";
 import "lodash-es";
 import { getColorVar } from "../../../theme/palette.js";
 import { Primitive } from "../../primitive/primitive.js";
+import { Stylesheet } from "../../stylesheet/stylesheet.js";
 const ImageSkeleton = (props) => {
   return /* @__PURE__ */ jsx(
     Primitive,

package/dist/lib/notifications/notifications.js

@@ -7,9 +7,9 @@ import { notificationStore } from "./helpers.js";
 import { getColorShadesByVariant } from "../../utils/index.js";
 import { FLOATING_Z_INDEX } from "../../theme/index.js";
 import CloseIcon from "../../assets/svg/times-close-delete.svg.js";
-import { Stylesheet } from "../stylesheet/stylesheet.js";
 import { usePortalContainer } from "../../theme/provider.js";
 import { Primitive } from "../primitive/primitive.js";
+import { Stylesheet } from "../stylesheet/stylesheet.js";
 import { getTypographyVar } from "../../theme/typography.js";
 import { IconButton } from "../icon-button/icon-button.js";
 const Notifications = () => {

package/dist/lib/star-rating/star-rating.js

@@ -1,7 +1,7 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import { useId } from "react";
-import { Stylesheet } from "../stylesheet/stylesheet.js";
 import { getStarRatingProps } from "./helpers.js";
+import { Stylesheet } from "../stylesheet/stylesheet.js";
 const StarRating = (_props) => {
   const { rating, maxRating, size, sm, md, lg, ref, color, sx } = getStarRatingProps(_props);
   const id = useId();

package/dist/lib/swiper/swiper-dots-paging/swiper-dots-paging.js

@@ -6,8 +6,8 @@ import { motion } from "motion/react";
 import { getColorVar } from "../../../theme/palette.js";
 import { usePortalContainer } from "../../../theme/provider.js";
 import { useIsHydrated } from "../../../hooks/use-is-hydrated/index.js";
-import { Stylesheet } from "../../stylesheet/stylesheet.js";
 import { Primitive } from "../../primitive/primitive.js";
+import { Stylesheet } from "../../stylesheet/stylesheet.js";
 const SWIPER_DOTS_SIZE_VAR = "--swiper-dots-size";
 const SWIPER_DOTS_OFFSET_VAR = "--swiper-dots-offset";
 const SWIPER_DOTS_SPACING_VAR = "--swiper-dots-spacing";

package/dist/lib/tabs/README.md

@@ -1,35 +1,48 @@
 # Tabs
 
-A compound tabs component for switching between content panels. It manages active tab state (controlled or uncontrolled) and provides context to sub-components: TabList, Tab, TabContent, TabPanel, and TabIndicator.
+Compound component để chuyển đổi giữa các panel nội dung. `Tabs` quản lý active tab index (controlled hoặc uncontrolled) và cung cấp `activeIndex` + hàm `focusTab` xuống sub-components qua context: `TabList`, `Tab`, `TabContent`, `TabPanel`, `TabIndicator`.
+
+Việc styling các tab được cấu hình ở `TabList` (`tabConfig`, `indicator`, `align`, `overflowBehavior`), không phải ở `Tabs`.
 
 ## Import
 
 ```tsx
-import { Tabs } from '@janbox/storefront-ui';
+import { Tabs, TabList, Tab, TabContent, TabPanel } from '@janbox/storefront-ui';
 ```
 
 ## Props
 
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `activeIndex` | `number` | - | Controlled active tab index. When provided, the component delegates state management to the parent. |
-| `defaultActiveIndex` | `number` | `0` | Initial active tab index for uncontrolled usage. |
-| `onTabChange` | `(tabIndex: number) => void` | - | Callback fired when the active tab changes, receiving the new tab index. |
-| `tabProps` | `Partial<TabProps>` | `{ color: 'neutral', variant: 'text', states: { active: { color: 'primary', variant: 'text' } } }` | Default props applied to every Tab child. Inactive tabs default to `color='neutral'`, active tab overrides to `color='primary'`. |
-| `tabIndicatorProps` | `TabIndicatorProps` | `{ sx: { height: 2, backgroundColor: 'var(--color-primary-600)' } }` | Props forwarded to the TabIndicator element, cho phép custom `sx` styles trên thanh gạch chân của tab đang active. |
-| `tabPanelProps` | `Partial<TabPanelProps>` | - | Default props applied to every TabPanel child. |
+| ------ | ------ | ------- | ----------- |
+| `activeIndex` | `number` | - | Controlled active tab index. Khi được cung cấp, component chuyển sang controlled mode và state nội bộ không tự đổi. |
+| `defaultActiveIndex` | `number` | `0` | Active tab index ban đầu cho uncontrolled usage. |
+| `onTabChange` | `(nextIndex: number) => void` | - | Callback được gọi khi active tab thay đổi, nhận index mới. |
 | `preventActiveTabChange` | `boolean` | `true` | Khi `true`, click vào tab đang active sẽ không re-fire `onTabChange`. |
 | `sx` | `ToResponsiveProps<StyledCSS>` | - | Responsive Emotion CSS overrides cho root wrapper `div`. |
 | `children` * | `React.ReactNode` | - | Phải là composition của `TabList` (chứa các `Tab`) và `TabContent` (chứa các `TabPanel`). |
+| `ref` | `React.Ref<HTMLDivElement>` | - | Forwarded ref tới root `div`. |
+
+Kế thừa toàn bộ `JSX.IntrinsicElements['div']` attributes.
 
 *Required props
 
+## Cách hoạt động
+
+- **Index của mỗi Tab**: `TabList` flatten children và bọc mỗi child trong `TabIndexContext.Provider` với index tương ứng. `Tab` đọc index này để so với `activeIndex` từ `TabsContext`.
+- **Click handling**: mỗi `Tab` tự gắn `onClick` và gọi `focusTab(tabIndex)` lấy từ `TabsContext`. `focusTab` kiểm tra `preventActiveTabChange` rồi cập nhật state và gọi `onTabChange`. `onClick` bạn truyền vào `Tab` vẫn được gọi sau đó.
+- **Styling**: `TabList` truyền `tabConfig` xuống mọi `Tab` con qua `TabListContext`. Mỗi `Tab` merge theo thứ tự `defaultProps` → `tabConfig` → props của chính nó, nên prop trực tiếp trên `Tab` luôn thắng.
+- **Panel rendering**: `TabContent` chỉ render đúng một child tại `activeIndex` — các `TabPanel` khác bị unmount, state nội bộ của chúng không được giữ lại.
+
+> ⚠️ `Tab` phải nằm trong cả `Tabs` và `TabList`. Ngoài `Tabs` thì `focusTab` là `undefined` và click sẽ throw; ngoài `TabList` thì index luôn là `-1` nên không tab nào active được.
+>
+> ⚠️ Ở controlled mode (`activeIndex` được truyền), state nội bộ không tự đổi — bạn phải cập nhật `activeIndex` trong `onTabChange`, nếu không tab sẽ không chuyển.
+
 ## Examples
 
 ### Basic uncontrolled tabs
 
 ```tsx
-<Tabs defaultActiveIndex={0} onTabChange={(i) => console.log(i)} style={{ width: 500 }}>
+<Tabs defaultActiveIndex={0} onTabChange={(i) => console.log(i)} sx={{ width: 500 }}>
   <TabList>
     <Tab>Tab 1</Tab>
     <Tab>Tab 2</Tab>
@@ -43,12 +56,12 @@ import { Tabs } from '@janbox/storefront-ui';
 </Tabs>
 ```
 
-### Controlled tabs with second tab active by default
+### Controlled tabs
 
 ```tsx
 const [active, setActive] = useState(1);
 
-<Tabs activeIndex={active} onTabChange={setActive} style={{ width: 500 }}>
+<Tabs activeIndex={active} onTabChange={setActive} sx={{ width: 500 }}>
   <TabList>
     <Tab>Overview</Tab>
     <Tab>Details</Tab>
@@ -62,15 +75,23 @@ const [active, setActive] = useState(1);
 </Tabs>
 ```
 
-### Custom tab color and variant via tabProps
+### Custom styling qua TabList
 
 ```tsx
-<Tabs
-  defaultActiveIndex={0}
-  tabProps={{ color: 'primary', variant: 'text' }}
-  style={{ width: 500 }}
->
-  <TabList>
+<Tabs defaultActiveIndex={0} sx={{ width: 500 }}>
+  <TabList
+    align="center"
+    tabConfig={{
+      sx: {
+        color: getColorVar('neutral.500'),
+        sm: { height: 48 },
+      },
+      states: {
+        active: { sx: { color: getColorVar('green.600') } },
+      },
+    }}
+    indicator={{ size: 3, sx: { backgroundColor: getColorVar('green.600') } }}
+  >
     <Tab>Home</Tab>
     <Tab>Profile</Tab>
     <Tab>Settings</Tab>
@@ -83,17 +104,63 @@ const [active, setActive] = useState(1);
 </Tabs>
 ```
 
+### Tab wrap thay vì scroll ngang
+
+```tsx
+<Tabs sx={{ width: 300 }}>
+  <TabList overflowBehavior="wrap">
+    <Tab>Tab 1</Tab>
+    <Tab>Tab 2</Tab>
+    <Tab>Tab 3</Tab>
+    <Tab>Tab 4</Tab>
+    <Tab>Tab 5</Tab>
+  </TabList>
+  <TabContent>{/* … */}</TabContent>
+</Tabs>
+```
+
+### Tab với icon
+
+```tsx
+import HomeIcon from '@/assets/svg/home.svg?raw';
+
+<Tabs defaultActiveIndex={0}>
+  <TabList>
+    <Tab startIcon={{ source: HomeIcon, size: 20 }}>Home</Tab>
+    <Tab endIcon={{ source: HomeIcon, size: 20 }}>Settings</Tab>
+  </TabList>
+  <TabContent>{/* … */}</TabContent>
+</Tabs>
+```
+
+### Ẩn indicator
+
+```tsx
+<Tabs defaultActiveIndex={0}>
+  <TabList indicator={false}>
+    <Tab>Tab 1</Tab>
+    <Tab>Tab 2</Tab>
+  </TabList>
+  <TabContent>{/* … */}</TabContent>
+</Tabs>
+```
+
+## Sub-components
+
+- [TabList](./tab-list/README.md)
+- [Tab](./tab/README.md)
+- [TabContent](./tab-content/README.md)
+- [TabPanel](./tab-panel/README.md)
+- [TabIndicator](./tab-indicator/README.md)
+
 ## Related Components
 
-- [TabList](../tablist/README.md)
-- [Tab](../tab/README.md)
-- [TabContent](../tabcontent/README.md)
-- [TabPanel](../tabpanel/README.md)
-- [TabIndicator](../tabindicator/README.md)
-- [Button](../button/README.md)
+- [Icon](../icon/README.md)
+- [Primitive](../primitive/README.md)
 
 ## Dependencies
 
+- motion/react
 - @emotion/react
 
 ## See Also