@janbox/storefront-ui 2.0.28 → 2.0.30

package/dist/lib/form-helper-text/README.md

@@ -0,0 +1,54 @@
+# FormHelperText
+
+Component hiển thị text hỗ trợ nhỏ bên dưới các form field, dùng để hiển thị hướng dẫn bổ sung hoặc thông báo lỗi validation. Tự động ẩn khi không có nội dung và đổi màu đỏ khi prop `error` được set.
+
+## Import
+
+```tsx
+import { FormHelperText } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `error` | `boolean` | `false` | Khi `true`, render helper text màu đỏ (`--color-red-600`) để chỉ trạng thái lỗi validation. |
+| `children` | `React.ReactNode` | - | Nội dung helper text. Element tự ẩn (`display: none`) khi không có nội dung. |
+| `sx` | `ToResponsiveProps<StyledCSS>` | - | Style override có responsive, truyền qua hệ thống `sx` prop của `Primitive`. |
+| `as` | `React.ElementType` | `"p"` | Override element type (polymorphic), kế thừa từ `PrimitiveProps`. Mặc định là `p`. |
+| `...rest` | `JSX.IntrinsicElements['p']` | - | Tất cả HTML attributes của thẻ `<p>` đều được forward xuống element bên dưới. |
+
+## Examples
+
+### Helper text mặc định
+
+```tsx
+<FormHelperText>This is a helper text</FormHelperText>
+```
+
+### Trạng thái lỗi
+
+```tsx
+<FormHelperText error>This field is required</FormHelperText>
+```
+
+### Kết hợp với input field
+
+```tsx
+<div>
+  <input type="email" placeholder="Enter your email" />
+  <FormHelperText error={!isValid}>
+    {isValid ? 'We will never share your email.' : 'Please enter a valid email address.'}
+  </FormHelperText>
+</div>
+```
+
+## Related Components
+
+- [Primitive](../primitive/README.md)
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./form-helper-text.stories.tsx)
+- [Main README](../../README.md)

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

@@ -0,0 +1,50 @@
+# FormLabel
+
+A form label wrapper component that renders a label for form fields with optional required indicator. It accepts either a string (auto-wrapped in a `<label>` element) or custom React children, and displays a red asterisk when the field is required.
+
+## Import
+
+```tsx
+import { FormLabel } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `required` | `boolean` | undefined | When true, appends a red asterisk (*) after the label to indicate the associated field is required. |
+| `children` | `React.ReactNode` | undefined | Label content. If a plain string is passed, it is automatically wrapped in a `<label>` element. Custom React nodes are rendered as-is. |
+| `...props` | `JSX.IntrinsicElements['div']` | - | All standard HTML div attributes (className, style, id, onClick, etc.) are forwarded to the root div element. |
+
+## Examples
+
+### Default label
+
+```tsx
+<FormLabel>Email address</FormLabel>
+```
+
+### Required field label
+
+```tsx
+<FormLabel required>Password</FormLabel>
+```
+
+### With custom children and className
+
+```tsx
+<FormLabel required className="custom-label">
+  <label htmlFor="username">Username</label>
+</FormLabel>
+```
+
+## Dependencies
+
+- lodash-es
+- @emotion/react
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./formlabel.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/grid/README.md

@@ -0,0 +1,72 @@
+# Grid
+
+A CSS Grid layout component that renders a responsive grid container with configurable column counts. It works in tandem with the Cell component, which supports colSpan for spanning multiple columns.
+
+## Import
+
+```tsx
+import { Grid } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `cols` | `number` | 1 | Number of equal-width columns in the grid. Generates `grid-template-columns: repeat(cols, minmax(0, 1fr))`. Supports responsive variants via sm/md/lg. |
+| `sm` | `GridResponsiveProps` | - | Responsive overrides applied at the sm breakpoint (≥768px). Accepts `{ cols?: number }`. |
+| `md` | `GridResponsiveProps` | - | Responsive overrides applied at the md breakpoint (≥1280px). Accepts `{ cols?: number }`. |
+| `lg` | `GridResponsiveProps` | - | Responsive overrides applied at the lg breakpoint (≥1680px). Accepts `{ cols?: number }`. |
+| `container` | `boolean` | false | When true, applies the shared responsive container styles (padding and max-width) from `containerStyle`. |
+| `sx` | `ToResponsiveProps<StyledCSS>` | - | Escape-hatch for inline Emotion styles. Supports responsive keys (sm, md, lg) alongside base styles. |
+| `children` | `React.ReactNode` | - | Grid children, typically Cell components. |
+| `ref` | `React.Ref<HTMLDivElement>` | - | Forwarded ref to the underlying div element. |
+
+## Examples
+
+### Two-column grid
+
+```tsx
+<Grid cols={2} style={{ width: 600 }}>
+  <Cell style={{ padding: 8, background: '#e0f0ff' }}>Cell 1</Cell>
+  <Cell style={{ padding: 8, background: '#f0ffe0' }}>Cell 2</Cell>
+  <Cell style={{ padding: 8, background: '#fff0e0' }}>Cell 3</Cell>
+  <Cell style={{ padding: 8, background: '#f0e0ff' }}>Cell 4</Cell>
+</Grid>
+```
+
+### Three-column grid with colSpan
+
+```tsx
+<Grid cols={3} style={{ width: 600 }}>
+  <Cell colSpan={2} style={{ padding: 8, background: '#e0f0ff' }}>Span 2 columns</Cell>
+  <Cell style={{ padding: 8, background: '#f0ffe0' }}>Cell 2</Cell>
+  <Cell style={{ padding: 8, background: '#fff0e0' }}>Cell 3</Cell>
+  <Cell style={{ padding: 8, background: '#f0e0ff' }}>Cell 4</Cell>
+</Grid>
+```
+
+### Responsive columns (1 on mobile, 2 on tablet, 4 on desktop)
+
+```tsx
+<Grid cols={1} sm={{ cols: 2 }} md={{ cols: 4 }} container>
+  <Cell>Item 1</Cell>
+  <Cell>Item 2</Cell>
+  <Cell>Item 3</Cell>
+  <Cell>Item 4</Cell>
+</Grid>
+```
+
+## Related Components
+
+- [Cell](./cell/README.md)
+- [Primitive](../primitive/README.md)
+
+## Dependencies
+
+- lodash-es
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./grid.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/grid/grid/grid.d.ts

@@ -1,4 +1,4 @@
 import { GridProps } from './types';
 export declare const GRID_MINIMUM_COLS = 1;
 export declare const GRID_MAXIMUM_COLS = 24;
-export declare const Grid: ({ children, ref, ..._props }: GridProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+export declare const Grid: ({ children, ref, ..._props }: GridProps) => import("react/jsx-runtime").JSX.Element;

package/dist/lib/grid/grid/grid.js

@@ -1,38 +1,33 @@
-import { jsx } from "@emotion/react/jsx-runtime";
+import { jsx } from "react/jsx-runtime";
 import { isNil } from "lodash-es";
 import { getGridProps } from "./helpers.js";
-import { mediaQuery } from "../../../theme/screens.js";
-import "../../../theme/palette.js";
 import { containerStyle } from "../../../constants/emotion.js";
+import { Primitive } from "../../primitive/primitive.js";
 const GRID_MINIMUM_COLS = 1;
 const GRID_MAXIMUM_COLS = 24;
 const Grid = ({ children, ref, ..._props }) => {
   const { cols, sm, md, lg, container, sx = {}, ...rest } = getGridProps(_props);
-  const { sm: sxSm, md: sxMd, lg: sxLg, ...sxXs } = sx;
-  const css = [
-    container && containerStyle,
-    createStyle({ cols }, sxXs),
+  return /* @__PURE__ */ jsx(
+    Primitive,
     {
-      [mediaQuery("sm")]: createStyle(sm, sxSm),
-      [mediaQuery("md")]: createStyle(md, sxMd),
-      [mediaQuery("lg")]: createStyle(lg, sxLg)
+      sx: {
+        display: "grid",
+        ...container ? containerStyle : {},
+        ...createStyle({ cols }),
+        ...sx,
+        sm: { ...createStyle(sm), ...sx.sm },
+        md: { ...createStyle(md), ...sx.md },
+        lg: { ...createStyle(lg), ...sx.lg }
+      },
+      ...rest,
+      ref,
+      children
     }
-  ];
-  return /* @__PURE__ */ jsx("div", { css, ...rest, ref, children: /* @__PURE__ */ jsx("div", { css: { display: "grid", width: "100%", height: "100%" }, children }) });
-};
-const createStyle = ({ cols } = {}, sx = {}) => {
-  const { width, height, ...css } = sx;
-  return [
-    {
-      width,
-      height,
-      "& > *": {
-        gridTemplateColumns: isNil(cols) ? void 0 : `repeat(${cols}, minmax(0, 1fr))`,
-        ...css
-      }
-    }
-  ];
+  );
 };
+const createStyle = ({ cols } = {}) => ({
+  gridTemplateColumns: isNil(cols) ? void 0 : `repeat(${cols}, minmax(0, 1fr))`
+});
 export {
   GRID_MAXIMUM_COLS,
   GRID_MINIMUM_COLS,

package/dist/lib/highlight-words/README.md

@@ -0,0 +1,64 @@
+# HighlightWords
+
+Renders a text string with specified search words highlighted using bold font weight. Built on top of `highlight-words-core`, it is useful for search result UIs where matched terms need to be visually distinguished within a body of text.
+
+## Import
+
+```tsx
+import { HighlightWords } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `textToHighlight*` | `string` | - | The full text string to display and search within. |
+| `searchWords*` | `string[]` | - | Array of words or phrases to highlight within the text. |
+| `highlightClassName` | `string` | - | Optional CSS class name(s) applied to the highlighted `<span>` elements. Useful for custom highlight styling (e.g. background color). |
+| `caseSensitive` | `boolean` | `false` | Whether the search matching should be case-sensitive. Defaults to false (case-insensitive). |
+| `autoEscape` | `boolean` | `false` | Whether to escape special regex characters in the search words before matching. |
+| `sanitize` | `(text: string) => string` | - | Optional function to sanitize/normalize text before matching (e.g. removing diacritics). |
+| `findChunks` | `(args: FindChunksArgs) => Chunk[]` | - | Custom chunk-finding function to override the default highlight-words-core matching logic. |
+
+*Required props
+
+## Examples
+
+### Basic usage
+
+```tsx
+<HighlightWords
+  textToHighlight="The quick brown fox jumps over the lazy dog"
+  searchWords={["fox", "dog"]}
+/>
+```
+
+### Case-sensitive matching
+
+```tsx
+<HighlightWords
+  textToHighlight="Hello World hello world"
+  searchWords={["Hello"]}
+  caseSensitive
+/>
+```
+
+### Custom highlight class
+
+```tsx
+<HighlightWords
+  textToHighlight="React is a JavaScript library for building user interfaces"
+  searchWords={["React", "JavaScript"]}
+  highlightClassName="bg-yellow-200 font-bold"
+/>
+```
+
+## Dependencies
+
+- highlight-words-core
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./highlightwords.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/highlight-words/highlight-words.js

@@ -1,13 +1,12 @@
 import { jsx } from "@emotion/react/jsx-runtime";
 import { Fragment } from "react";
 import { findAll } from "highlight-words-core";
-import { clsx } from "clsx";
 const HighlightWords = ({ highlightClassName, ...props }) => {
   const chunks = findAll(props);
   return /* @__PURE__ */ jsx(Fragment, { children: chunks.map((chunk, index) => {
     const { end, highlight, start } = chunk;
     const text = props.textToHighlight.substring(start, end);
-    return /* @__PURE__ */ jsx(Fragment, { children: highlight ? /* @__PURE__ */ jsx("span", { css: { fontWeight: 500 }, className: clsx(highlightClassName), children: text }) : text }, index);
+    return /* @__PURE__ */ jsx(Fragment, { children: highlight ? /* @__PURE__ */ jsx("span", { css: { fontWeight: 500 }, className: highlightClassName, children: text }) : text }, index);
   }) });
 };
 export {

package/dist/lib/icon/README.md

@@ -0,0 +1,69 @@
+# Icon
+
+A responsive SVG icon component that renders raw SVG strings via the SvgLoader component. Supports numeric size control with responsive breakpoint overrides (sm/md/lg) and the sx prop for custom styling.
+
+## Import
+
+```tsx
+import { Icon } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `source*` | `string` | - | Raw SVG string to render. Typically imported via Vite's ?raw query (e.g. import MyIcon from '@/assets/svg/my-icon.svg?raw'). |
+| `size` | `number` | 24 | Width and height of the icon in pixels. Applied as the base (mobile-first) size. |
+| `sm` | `{ size?: number }` | - | Responsive overrides applied at the sm breakpoint (≥768px). Accepts an object with the same responsive props. |
+| `md` | `{ size?: number }` | - | Responsive overrides applied at the md breakpoint (≥1280px). Accepts an object with the same responsive props. |
+| `lg` | `{ size?: number }` | - | Responsive overrides applied at the lg breakpoint (≥1680px). Accepts an object with the same responsive props. |
+| `sx` | `ToResponsiveProps<StyledCSS>` | - | Escape hatch for custom Emotion CSS. Supports responsive keys (sm/md/lg) for breakpoint-scoped styles. |
+| `...svgProps` | `JSX.IntrinsicElements['svg']` | - | All native SVG element attributes (e.g. className, style, aria-label, onClick) are forwarded to the underlying svg element. |
+
+*Required props
+
+## Examples
+
+### Default icon at 24px
+
+```tsx
+import HomeIcon from '@/assets/svg/home.svg?raw';
+
+<Icon source={HomeIcon} />
+```
+
+### Custom size with accessible label
+
+```tsx
+import StarIcon from '@/assets/svg/star.svg?raw';
+
+<Icon source={StarIcon} size={32} aria-label="Favourite" />
+```
+
+### Responsive size across breakpoints
+
+```tsx
+import SearchIcon from '@/assets/svg/search.svg?raw';
+
+<Icon
+  source={SearchIcon}
+  size={20}
+  sm={{ size: 20 }}
+  md={{ size: 24 }}
+  lg={{ size: 28 }}
+/>
+```
+
+## Related Components
+
+- [SvgLoader](../svgloader/README.md)
+
+## Dependencies
+
+- @emotion/react
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./icon.stories.tsx)
+- [Main README](../../README.md)

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

@@ -0,0 +1,92 @@
+# IconButton
+
+A button component that renders an icon (and optionally children) with support for contained, outlined, and text variants. Designed for icon-only or icon-with-label actions, with built-in loading state, ripple effect, and responsive sizing.
+
+## Import
+
+```tsx
+import { IconButton } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `icon` | `IconProps` | - | Icon to render inside the button. Accepts an SVG raw string via `source` plus any Icon component props (size, sx, responsive breakpoints). |
+| `variant` | `'contained' \| 'outlined' \| 'text'` | `'text'` | Visual style of the button. |
+| `color` | `'primary' \| 'secondary' \| 'green' \| 'red' \| 'orange' \| 'blue' \| 'neutral'` | `'primary'` | Color variant that controls background, border, and icon color based on the design token palette. |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Controls the minimum width/height of the button and icon size. |
+| `isLoading` | `boolean` | `false` | When true, hides the icon and shows a spinning loading indicator. Disables pointer events. |
+| `sx` | `ToResponsiveProps<StyledCSS>` | - | Escape hatch for custom Emotion CSS styles, including responsive overrides at sm/md/lg breakpoints. |
+| `sm` | `IconButtonResponsiveProps` | - | Responsive size override applied at the sm breakpoint (≥768px). |
+| `md` | `IconButtonResponsiveProps` | - | Responsive size override applied at the md breakpoint (≥1280px). |
+| `lg` | `IconButtonResponsiveProps` | - | Responsive size override applied at the lg breakpoint (≥1680px). |
+| `disabled` | `boolean` | `false` | Native HTML disabled attribute. Disables pointer events and applies neutral disabled colors. |
+| `aria-disabled` | `boolean \| 'true' \| 'false'` | - | Aria-disabled state. Applies disabled styling without removing the element from the tab order. |
+| `children` | `React.ReactNode` | - | Optional content rendered alongside the icon (e.g. a label). |
+| `onClick` | `React.MouseEventHandler<HTMLButtonElement>` | - | Click handler forwarded from native button props. |
+
+## Examples
+
+### Text variant (default) with a star icon
+
+```tsx
+<IconButton icon={{ source: starSvg }} onClick={handleClick} />
+```
+
+### Contained primary button with loading state
+
+```tsx
+<IconButton
+  icon={{ source: searchSvg }}
+  variant="contained"
+  color="primary"
+  isLoading={isFetching}
+/>
+```
+
+### Outlined small close button with aria-disabled
+
+```tsx
+<IconButton
+  icon={{ source: closeSvg }}
+  variant="outlined"
+  color="red"
+  size="sm"
+  aria-disabled={!canClose}
+/>
+```
+
+### Responsive size — nhỏ trên mobile, lớn hơn trên desktop
+
+```tsx
+<IconButton
+  icon={{ source: filterSvg }}
+  variant="outlined"
+  size="sm"
+  md={{ size: 'md' }}
+/>
+```
+
+### Icon button với label
+
+```tsx
+<IconButton icon={{ source: editSvg }} variant="text" color="primary">
+  Chỉnh sửa
+</IconButton>
+```
+
+## Related Components
+
+- [Icon](../icon/README.md)
+- [RippleEffect](../ripple-effect/README.md)
+
+## Dependencies
+
+- `@emotion/react`
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./icon-button.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/image/README.md

@@ -0,0 +1,80 @@
+# Image
+
+A polymorphic image component that wraps the native `<img>` element with built-in fallback support and sensible defaults. It automatically handles broken image sources by swapping in a fallback URL or a default placeholder, and applies `loading="lazy"` and `object-fit: cover` out of the box.
+
+## Import
+
+```tsx
+import { Image } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `src` | `string` | - | The URL of the image to display. If empty or undefined, the fallback source is used instead. |
+| `alt` | `string` | "" | Alternative text for the image. Defaults to an empty string if not provided. |
+| `fallback` | `string \| boolean` | true | Controls fallback behavior when the image fails to load. Pass `true` to use the built-in IMAGE_PLACEHOLDER constant, a string URL to use a custom fallback image, or `false` to disable fallback entirely. |
+| `loading` | `"lazy" \| "eager"` | "lazy" | Native img loading attribute. Defaults to 'lazy' for performance. |
+| `sx` | `ToResponsiveProps<StyledCSS>` | { objectFit: 'cover' } | Responsive style overrides via the Emotion sx prop. Base styles apply `objectFit: 'cover'` and `maxHeight: '100%'`. |
+| `width` | `number \| string` | - | Native img width attribute. |
+| `height` | `number \| string` | - | Native img height attribute. |
+| `onError` | `React.ReactEventHandler<HTMLImageElement>` | - | Called after the fallback logic runs when the image fails to load. The component handles src replacement internally before invoking this callback. |
+| `as` | `React.ElementType` | "img" | Polymorphic tag override inherited from Primitive. Defaults to 'img'. |
+| `ref` | `React.Ref<HTMLImageElement>` | - | Forwarded ref to the underlying img element. |
+
+## Examples
+
+### Default usage
+
+```tsx
+<Image
+  src="https://via.placeholder.com/300x200"
+  alt="Placeholder image"
+  width={300}
+  height={200}
+/>
+```
+
+### Custom fallback URL on error
+
+```tsx
+<Image
+  src="https://invalid-url.example.com/image.jpg"
+  alt="Image with fallback"
+  fallback="https://via.placeholder.com/300x200?text=Fallback"
+  width={300}
+  height={200}
+/>
+```
+
+### Built-in placeholder fallback with responsive sx
+
+```tsx
+<Image
+  src="https://cdn.example.com/product.jpg"
+  alt="Product thumbnail"
+  fallback={true}
+  width={120}
+  height={120}
+  sx={{
+    borderRadius: 8,
+    objectFit: 'contain',
+    md: { width: 160, height: 160 },
+  }}
+/>
+```
+
+## Related Components
+
+- [Primitive](../primitive/README.md)
+
+## Dependencies
+
+- lodash-es
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./image.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/input/README.md

@@ -0,0 +1,118 @@
+# Input
+
+A flexible text input component with support for prefix/suffix slots, start/end icons, password visibility toggle, error state, helper text, debounced onChange, and responsive sizing. Designed for form fields across all sizes of the design system.
+
+## Import
+
+```tsx
+import { Input } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `size` | `SizeVariant ('xs' \| 'sm' \| 'md' \| 'lg')` | `md` | Controls height, padding, and font size of the input via the size variant scale. |
+| `sm` | `InputResponsiveProps ({ size?: SizeVariant })` | - | Responsive overrides applied at the sm breakpoint (≥768px). |
+| `md` | `InputResponsiveProps ({ size?: SizeVariant })` | - | Responsive overrides applied at the md breakpoint (≥1280px). |
+| `lg` | `InputResponsiveProps ({ size?: SizeVariant })` | - | Responsive overrides applied at the lg breakpoint (≥1680px). |
+| `sx` | `ToResponsiveProps<StyledCSS>` | - | Escape-hatch for custom Emotion CSS styles, passed to the container element. |
+| `error` | `boolean` | `false` | Puts the input into an error state, showing a red border and applying error styling to the helper text. |
+| `helperText` | `string` | - | Descriptive or validation text rendered below the input via FormHelperText. Color changes when `error` is `true`. |
+| `prefix` | `React.ReactNode` | - | Arbitrary node rendered at the far-left of the input wrapper, outside the icon slots (e.g. a country code badge). |
+| `suffix` | `React.ReactNode` | - | Arbitrary node rendered at the far-right of the input wrapper, outside the icon slots. |
+| `startIcon` | `IconProps` | - | Icon displayed on the left side of the input field, inside the wrapper. Size tracks the current size variant automatically. |
+| `endIcon` | `IconProps` | - | Icon displayed on the right side of the input field, inside the wrapper. Size tracks the current size variant automatically. |
+| `containerProps` | `PrimitiveProps<JSX.IntrinsicElements['div']>` | - | Props forwarded to the outermost wrapper div (position: relative, flex column container). |
+| `mainProps` | `PrimitiveProps<JSX.IntrinsicElements['div']>` | - | Props forwarded to the inner wrapper div that renders the border, background, and layout for the input row. |
+| `value` | `string` | - | Controlled value of the input. When provided alongside `debounce` or `mode='onBlur'`, the component buffers the typing value internally. |
+| `defaultValue` | `string` | - | Uncontrolled default value for the input. |
+| `transform` | `(value: string) => string` | - | Optional function applied to the raw input value on every change event before propagating it (e.g. uppercase, numeric-only filter). |
+| `mode` | `'onChange' \| 'onBlur'` | `onChange` | Determines when `onChange` fires. `'onBlur'` defers the call until the user leaves the field; `'onChange'` fires on every keystroke (subject to `debounce`). |
+| `debounce` | `number` | `0` | Milliseconds to debounce the `onChange` callback. Set to `0` to disable debouncing. |
+| `type` | `string (HTML input type)` | - | Standard HTML input type. When set to `'password'`, a visibility toggle icon is automatically appended. |
+| `disabled` | `boolean` | - | Disables the input and applies a neutral muted style to the wrapper via CSS `:has` selector. |
+| `placeholder` | `string` | - | Placeholder text shown when the input is empty. |
+| `onChange` | `React.ChangeEventHandler<HTMLInputElement>` | - | Change handler. May be deferred depending on `mode` and `debounce` settings. |
+
+## Examples
+
+### Default input with placeholder
+
+```tsx
+<Input placeholder="Enter text..." onChange={handleChange} />
+```
+
+### Error state with helper text
+
+```tsx
+<Input
+  placeholder="Enter email..."
+  error={true}
+  helperText="Invalid email address"
+  onChange={handleChange}
+/>
+```
+
+### Password input with debounced onChange
+
+```tsx
+<Input
+  type="password"
+  placeholder="Enter password..."
+  mode="onChange"
+  debounce={300}
+  value={password}
+  onChange={(e) => setPassword(e.target.value)}
+/>
+```
+
+### Input với icon và prefix/suffix
+
+```tsx
+<Input
+  placeholder="Tìm kiếm..."
+  startIcon={{ source: SearchIcon }}
+  suffix={<span>VND</span>}
+  size="lg"
+/>
+```
+
+### Responsive sizing
+
+```tsx
+<Input
+  size="sm"
+  sm={{ size: 'md' }}
+  md={{ size: 'lg' }}
+  placeholder="Responsive input"
+/>
+```
+
+### onBlur mode với transform
+
+```tsx
+<Input
+  mode="onBlur"
+  transform={(val) => val.toUpperCase()}
+  placeholder="Uppercase on blur"
+  onChange={(e) => console.log(e.target.value)}
+/>
+```
+
+## Related Components
+
+- [Icon](../icon/README.md)
+- [FormHelperText](../formhelpertext/README.md)
+- [Primitive](../primitive/README.md)
+
+## Dependencies
+
+- `@floating-ui/react`
+- `lodash-es`
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./input.stories.tsx)
+- [Main README](../../README.md)