@chotot/clad-ui 3.0.0-next.4 → 3.0.0-next.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/dist/clad-ui.cjs +2 -2
  2. package/dist/clad-ui.es.js +1105 -1032
  3. package/dist/components/Badge/types.d.ts +1 -1
  4. package/dist/components/Box/types.d.ts +1 -1
  5. package/dist/components/CurrencyInput/types.d.ts +1 -1
  6. package/dist/components/DatePicker/types.d.ts +10 -2
  7. package/dist/components/Drawer/types.d.ts +11 -6
  8. package/dist/components/Dropdown/types.d.ts +1 -1
  9. package/dist/components/Grid/types.d.ts +2 -2
  10. package/dist/components/InputGroup/types.d.ts +1 -1
  11. package/dist/components/LegacyDialog/types.d.ts +1 -1
  12. package/dist/components/LegacyPopup/types.d.ts +1 -1
  13. package/dist/components/Pagination/types.d.ts +1 -1
  14. package/dist/components/Popup/types.d.ts +5 -5
  15. package/dist/components/RangeInput/types.d.ts +1 -1
  16. package/dist/components/RowItem/RowItem.d.ts +1 -1
  17. package/dist/components/RowItem/types.d.ts +2 -2
  18. package/dist/components/Slider/types.d.ts +1 -1
  19. package/dist/components/Snack/types.d.ts +2 -2
  20. package/dist/components/Tabs/Tabs.d.ts +2 -11
  21. package/dist/components/Tabs/types.d.ts +2 -2
  22. package/dist/components/TagCloud/TagCloud.d.ts +265 -1
  23. package/dist/components/TagCloud/types.d.ts +1 -1
  24. package/dist/components/TextArea/types.d.ts +1 -1
  25. package/dist/components/ToggleSwitch/types.d.ts +1 -1
  26. package/dist/components/Tooltip/types.d.ts +1 -1
  27. package/dist/styles.css +1 -1
  28. package/package.json +1 -1
  29. package/skills/clad-ui/SKILL.md +1 -1
  30. package/skills/clad-ui/references/components-display-layout.md +3 -1
  31. package/skills/clad-ui/references/components-inputs.md +3 -1
  32. package/skills/clad-ui/references/components-overlays-nav.md +6 -6
  33. package/skills/clad-ui-feedback/SKILL.md +1 -1
  34. package/skills/migrate-clad-ui-v3/SKILL.md +3 -2
  35. package/skills/migrate-clad-ui-v3/references/component-api-changes.md +7 -1
  36. package/skills/migrate-clad-ui-v3/references/token-and-linaria-mapping.md +8 -0
  37. package/src/styles/components/dropdown.css +1 -1
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@chotot/clad-ui",
3
- "version": "3.0.0-next.4",
3
+ "version": "3.0.0-next.6",
4
4
  "description": "Classified Ads group (Chotot) design system built on Tailwind CSS v4.",
5
5
  "keywords": [
6
6
  "chotot",
@@ -5,7 +5,7 @@ metadata:
5
5
  purpose: Build and style React UI using @chotot/clad-ui (Clad UI v3, Tailwind CSS v4) and @chotot/icons. Use when creating or updating UI components, selecting semantic color/typography tokens, wiring forms, modals, drawers, or tabs. Not for migrating legacy @chotot/clad-ui v2 Linaria code, use migrate-clad-ui-v3 instead.
6
6
  type: core
7
7
  library: '@chotot/clad-ui'
8
- library_version: '3.0.0-next.4'
8
+ library_version: '3.0.0-next.6'
9
9
  sources:
10
10
  - 'carousell/clad-ui:packages/clad-ui/src/**'
11
11
  ---
@@ -14,6 +14,8 @@
14
14
  - [10. Layout (`Box`, `Grid`, `Col`)](#10-layout-box-grid-col)
15
15
  - [11. Icons (`@chotot/clad-ui/icons`)](#11-icons-chototclad-uiicons)
16
16
 
17
+ > **Standard HTML Attributes & Selectors:** All display, action, typography, and layout components forward `id`, `data-testid`, `data-*`, `aria-*`, and `{...rest}` to their root DOM element and render `data-clad="<ComponentName>"` on the root.
18
+
17
19
  ---
18
20
 
19
21
  ## 1. Button & Aliases (`IconButton`, `GhostButton`, `ButtonLink`)
@@ -220,7 +222,7 @@ import { Shield } from '@chotot/clad-ui/icons';
220
222
 
221
223
  ## 8. EmptyState
222
224
 
223
- Illustrated placeholder with 7 built-in Vietnamese presets plus customizable `other`.
225
+ Illustrated placeholder with 11 built-in Vietnamese presets plus customizable `other`.
224
226
 
225
227
  ```tsx
226
228
  import { EmptyState } from '@chotot/clad-ui';
@@ -37,6 +37,8 @@ Do **not** assume every form component passes a standard `e.target.value` string
37
37
  | `DateTimePicker` | `(v: DateTimePickerValue, e?) => void` | `v.dateObj` (`Date \| null`), `v.hour`, `v.minute` |
38
38
  | `Slider` | `(e: SliderOnChangeEvent) => void` | `e.value` (`number \| [number, number]`) |
39
39
 
40
+ > **Standard HTML Attributes (`id`, `data-testid`, `data-*`, `aria-*`):** All form components accept `id` and `{...rest}` attributes (`Input`, `TextArea`, `CurrencyInput`, `Dropdown`, `Checkbox`, `RadioButton`, `ToggleSwitch` forward `id` + `{...rest}` to their native `<input>`/`<textarea>`/`<select>` control; composite controls like `InputGroup`, `RangeInput`, `Searchbar`, `SearchInput`, `MultiSearchDropdown`, `DatePicker`, `DateTimePicker`, `Slider` forward them to their root container). Every component root renders `data-clad="<ComponentName>"`.
41
+
40
42
  ---
41
43
 
42
44
  ## 1. Input
@@ -102,7 +104,7 @@ import { TextArea } from '@chotot/clad-ui';
102
104
  | `lines` | `number` | `5` |
103
105
  | `status` | `'default' \| 'warning' \| 'error'` | `'default'` |
104
106
  | `helptext` | `string` | — |
105
- | `allowClear` | `boolean` | `false` |
107
+ | `allowClear` | `boolean` | `true` |
106
108
  | `characterLimit` | `number` | — |
107
109
  | `disabled` / `required` | `boolean` | `false` |
108
110
 
@@ -26,7 +26,6 @@ import { Drawer, Button } from '@chotot/clad-ui';
26
26
  import { Close } from '@chotot/clad-ui/icons';
27
27
 
28
28
  <Drawer.Container open={isOpen} onClose={() => setIsOpen(false)} size="M" halfHeight dragHandle>
29
- <Drawer.DragHandle />
30
29
  <Drawer.Header
31
30
  title="Chọn khu vực"
32
31
  leading={<Drawer.HeaderItem type="icon" icon={<Close />} onClick={() => setIsOpen(false)} />}
@@ -48,12 +47,13 @@ import { Close } from '@chotot/clad-ui/icons';
48
47
  | `Drawer.Container`: `onClose` | `MouseEventHandler<HTMLElement>` | — |
49
48
  | `Drawer.Container`: `size` | `'S' \| 'M' \| 'L'` (desktop width: 480 / 720 / 1200px) | `'S'` |
50
49
  | `Drawer.Container`: `halfHeight` | `boolean` (mobile starts at 50vh, expands on drag/scroll) | `false` |
51
- | `Drawer.Container`: `dragHandle` | `boolean` | `false` |
50
+ | `Drawer.Container`: `dragHandle` | `boolean` (auto-renders `<Drawer.DragHandle />` inside container; do not also pass `<Drawer.DragHandle />` as a child) | `false` |
52
51
  | `Drawer.Container`: `needBypassScrollLock` | `boolean` | `false` |
53
- | `Drawer.Header`: `title` / `leading` / `trailing` | `ReactNode` | — |
52
+ | `Drawer.Container`: `id`, `data-*`, `aria-*` | Standard HTML attributes forwarded to root `.drawer` (`data-clad="Drawer"`) | — |
53
+ | `Drawer.Header`: `title` / `leading` / `trailing` | `ReactNode` (`data-clad="Drawer.Header"`) | — |
54
54
  | `Drawer.HeaderItem`: `type` | `'icon' \| 'textLink'` (`icon` or `text`, `onClick`) | `'icon'` |
55
- | `Drawer.Body`: `hideScrollbar` / `childrenOverflowVisible` | `boolean` | `false` |
56
- | `Drawer.Button`: `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` |
55
+ | `Drawer.Body`: `hideScrollbar` / `childrenOverflowVisible` | `boolean` (`data-clad="Drawer.Body"`) | `false` |
56
+ | `Drawer.Button`: `direction` | `'horizontal' \| 'vertical'` (`data-clad="Drawer.Button"`) | `'horizontal'` |
57
57
 
58
58
  ### Legacy Monolithic `<Drawer>` Props & Double-Header Gotcha
59
59
 
@@ -64,7 +64,7 @@ import { Close } from '@chotot/clad-ui/icons';
64
64
  <CustomScreenWithOwnHeader onClose={onClose} />
65
65
  </Drawer>
66
66
  ```
67
- - **Legacy props on `<Drawer>`:** `title`, `img`, `primaryBtnLabel`, `secondaryBtnLabel`, `optionalBtnLabel`, `onPrimaryButtonClick`, `onSecondaryButtonClick`, `onOptionalBtnClick`, `primaryColor`, `actions`, `haveClose`, `isEmptyDrawer`, `contentClassName`.
67
+ - **Legacy props on `<Drawer>`:** `title`, `img`, `primaryBtnLabel`, `secondaryBtnLabel`, `optionalBtnLabel`, `disablePrimaryButton`, `onPrimaryButtonClick`, `onSecondaryButtonClick`, `onOptionalBtnClick`, `primaryColor`, `actions`, `haveClose`, `isEmptyDrawer`, `contentClassName` (applied only to `.drawer-children-content`), plus `id`, `data-*`, `aria-*` on the root `.drawer`.
68
68
 
69
69
  ---
70
70
 
@@ -5,7 +5,7 @@ metadata:
5
5
  purpose: Report bugs, request component/token/icon enhancements, or propose new ideas for @chotot/clad-ui, @chotot/icons, and @chotot/charts by creating structured GitHub issues in carousell/clad-ui. Use when a consumer developer hits a design system bug, missing prop/icon/token, migration blocker, or asks to file feedback/issue for Clad UI.
6
6
  type: sub-skill
7
7
  library: '@chotot/clad-ui'
8
- library_version: '3.0.0-next.4'
8
+ library_version: '3.0.0-next.6'
9
9
  requires:
10
10
  - clad-ui
11
11
  sources:
@@ -5,7 +5,7 @@ metadata:
5
5
  purpose: Migrate consumer React/Next.js code from @chotot/clad-ui v2 (Linaria) to @chotot/clad-ui v3 (Tailwind CSS v4) and @chotot/icons. Supports incremental file/feature migration (coexistence via @chotot/clad-ui-v2 alias) and full-repo cutover. Not for building new v3 UI from scratch, use clad-ui instead.
6
6
  type: lifecycle
7
7
  library: '@chotot/clad-ui'
8
- library_version: '3.0.0-next.4'
8
+ library_version: '3.0.0-next.6'
9
9
  requires:
10
10
  - clad-ui
11
11
  sources:
@@ -77,6 +77,7 @@ Discovery reads:
77
77
  - If the file imports `@linaria/core`, `@linaria/react`, or `@chotot/clad-ui/theme/*`, read [references/token-and-linaria-mapping.md](references/token-and-linaria-mapping.md).
78
78
  - Replace `styled.<tag>` and `css\`...\`` with Tailwind utility classes and Clad semantic tokens (`bg-background-*`, `text-text-*`, `border-border-*`, `text-icon-*`, `text-{display,header,label,body}-*`), merging conditional classes via `cn` from `@chotot/clad-ui`.
79
79
  - Map `theme.mediaQueries.tablet` → `md:` (`768px`) and `theme.mediaQueries.desktop` → `min-[992px]:`.
80
+ - Avoid the 3 common Linaria-to-Tailwind pitfalls in [references/token-and-linaria-mapping.md](references/token-and-linaria-mapping.md) Section 1.1: use `text-[24px]`/`text-[20px]` instead of `text-2xl`/`text-xl` when only `font-size` was set without `line-height`; strip spaces inside `var(--x,0px)` arbitrary values; and map wrapper `gap` props via `cn(gapClass, className)` rather than inline `style={{ gap }}`.
80
81
 
81
82
  5. **Run Coexistence vs Full-Repo Cutover check and verify.**
82
83
  - Run across the entire repo:
@@ -85,7 +86,7 @@ Discovery reads:
85
86
  ```
86
87
  - **If matches remain outside `target` (Incremental Coexistence mode):** do **not** remove `@chotot/clad-ui-v2`, `@linaria/*`, `next-linaria`, `.babelrc`, `@clad-ui/theme` aliases, or `withCladUi` / `withLinaria` in `next.config.js`.
87
88
  - **If 0 matches remain across the entire repo (Full-Repo Cutover mode):** remove `@chotot/clad-ui-v2` (if aliased), `@linaria/*`, `next-linaria`, `react-laag`, `@chotot/clad-ui/babel`, `@clad-ui/theme` aliases, and `withCladUi` / `withLinaria` from `package.json`, `.babelrc` / `babel.config.js`, and `next.config.js` per [references/component-api-changes.md](references/component-api-changes.md) Section 5.
88
- - Verify `target` has 0 remaining v2 subpath/alias or `@linaria/*` imports, then run the repo's typecheck (`pnpm type-check` / `tsc --noEmit`) and lint (`pnpm lint`).
89
+ - Verify `target` has 0 remaining v2 subpath/alias or `@linaria/*` imports and 0 leftover codemod placeholders (`rg "__[A-Z0-9_]+__"`), then run the repo's typecheck (`pnpm type-check` / `tsc --noEmit`) and lint (`pnpm lint`).
89
90
 
90
91
  ## Guardrails
91
92
 
@@ -92,6 +92,11 @@ import ptyTheme from '@chotot/clad-ui/theme/ct-pty';
92
92
  ### Input Family (`Input`, `CurrencyInput`, `TextArea`, `Dropdown`, `MultiSearchDropdown`, `SearchInput`, `InputGroup`)
93
93
  - `Input`, `CurrencyInput`, and `TextArea` now support `status?: 'default' | 'error' | 'warning' | 'success'` (adds `'warning'` with `--color-border-warning` / `--color-text-warning`).
94
94
  - Across the entire input family, resting border is unified to `1px solid var(--color-border-thin)` (`#e8e8e8`), disabled border is `2px solid var(--color-border-disabled)` (`#c0c0c0`), and default helptext color is `var(--color-text-secondary)` (`#595959`).
95
+ - **Legacy wrapper descendant selectors (migrate-only):** Do not introduce new descendant selectors targeting internal DOM classes (Hyrum's Law). However, when migrating an existing v2 wrapper component (e.g. `InputPhoneWrapper`) that already targets v2 internal classes, update the selectors to v3's BEM classes:
96
+ - `.hasLeftIcon` (wrapper) → `.input--has-left-icon` (wrapper) and `.input-icon-left` (left icon container)
97
+ - `.noLabel` (wrapper) → `.input--no-label`
98
+ - `input.hasValue` → `.input-el.has-value`
99
+ - `input.required` → `.input-el.is-required`
95
100
 
96
101
  ### Checkbox
97
102
  - Supports `indeterminate?: boolean` (renders the minus indicator, applies `.checkbox--indeterminate`, sets `aria-checked="mixed"`, and syncs the native `input.indeterminate` DOM property).
@@ -116,7 +121,8 @@ import ptyTheme from '@chotot/clad-ui/theme/ct-pty';
116
121
  - Valid props: `color` (`'info' | 'success' | 'error' | 'warning' | 'neutral'`), `size` (`'md' | 'sm'`), `type` (`'text' | 'status'`), `label` (`string`), `icon` (`ReactNode`).
117
122
 
118
123
  ### Drawer & Popup
119
- - Both legacy monolithic props (`<Drawer open={open} title="..." primaryBtnLabel="..." onClose={fn}>`) and compound slots (`<Drawer.Container>`, `<Drawer.Header>`, `<Drawer.Body>`, `<Drawer.Button>`) are supported in v3.
124
+ - Both legacy monolithic props (`<Drawer open={open} title="..." primaryBtnLabel="..." disablePrimaryButton onClose={fn}>`) and compound slots (`<Drawer.Container>`, `<Drawer.Header>`, `<Drawer.Body>`, `<Drawer.Button>`) are supported in v3.
125
+ - `data-clad="Drawer"` is placed exclusively on the root `.drawer` dialog element (1 open Drawer = 1 `[data-clad="Drawer"]`), while inner slots use `data-clad="Drawer.Header"`, `data-clad="Drawer.Body"`, and `data-clad="Drawer.Button"`. Pass `id` or `data-testid` to distinguish multiple open Drawers/Popups, and use `contentClassName` (applied to `.drawer-children-content`) when styling the scrollable body of a legacy `<Drawer>`.
120
126
  - `LegacyDialog` (`DialogMainIcon`) and `LegacyPopup` are also exported from `@chotot/clad-ui` for 1:1 drop-in compatibility.
121
127
 
122
128
  ### Floating Components (`Tooltip`, `Popover`, `Dropdown`, `MultiSearchDropdown`, `SearchInput`, `DatePicker`, `DateTimePicker`)
@@ -49,6 +49,14 @@ import { cn } from '@chotot/clad-ui';
49
49
  </div>
50
50
  ```
51
51
 
52
+ ### 1.1 Three Common Linaria → Tailwind Layout Pitfalls
53
+ 1. **Standalone `font-size` without `line-height` (`text-[24px]` vs `text-2xl`):**
54
+ - When a v2 Linaria rule only sets `font-size: 24px` (or `${theme.fontSizes.xxl}` / `${theme.fontSizes.xl}`) without setting `line-height` (common on icon wrappers and compact buttons), **do not** convert it to Tailwind's `text-2xl` (`font-size: 1.5rem; line-height: 2rem`) or `text-xl` (`line-height: 1.75rem`). Tailwind's built-in `line-height` will inflate the element's height (`24px` → `32px`). Use arbitrary font-size `text-[24px]` / `text-[20px]` to preserve inherited `line-height`.
55
+ 2. **CSS `var(--custom, fallback)` inside shorthand properties:**
56
+ - Never split a CSS `var()` fallback containing spaces across multiple utilities (e.g., converting `padding: var(--global-padding, 0px)` into broken `py-[var(--global-padding,] px-[0px)]`). Strip spaces inside `var(...)` and use a single arbitrary utility: `p-[var(--global-padding,0px)]`.
57
+ 3. **Layout wrapper props (`gap`, etc.) vs `className` override:**
58
+ - When migrating a reusable layout primitive (`Stack`, `Flex`) that accepts both a `gap` prop and `className`, map `gap` to a Tailwind `gap-*` class placed **before** `className` inside `cn(gapClass, className)`. Do not assign `style={{ gap }}` when `className` is also used to pass `gap-*` overrides, because inline `style.gap` always wins over CSS classes.
59
+
52
60
  ---
53
61
 
54
62
  ## 2. Semantic Color Tokens (`theme.colors.*` & `var(--clad-*)`)
@@ -145,7 +145,7 @@
145
145
  overflow-y: auto;
146
146
  scrollbar-color: var(--color-gray200) var(--color-gray200);
147
147
  scrollbar-width: thin;
148
- z-index: 1500;
148
+ z-index: 1700;
149
149
  }
150
150
 
151
151
  @utility dropdown-item {