@g4rcez/components 3.0.0-0 → 3.0.1

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 (265) hide show
  1. package/dist/ai/SKILL.md +266 -0
  2. package/dist/ai/docs/Alert.md +167 -0
  3. package/dist/ai/docs/AnimatedList.md +205 -0
  4. package/dist/ai/docs/Autocomplete.md +225 -0
  5. package/dist/ai/docs/Button.md +182 -0
  6. package/dist/ai/docs/Calendar.md +219 -0
  7. package/dist/ai/docs/Card.md +174 -0
  8. package/dist/ai/docs/Checkbox.md +199 -0
  9. package/dist/ai/docs/CommandPalette.md +293 -0
  10. package/dist/ai/docs/DatePicker.md +171 -0
  11. package/dist/ai/docs/Dropdown.md +223 -0
  12. package/dist/ai/docs/Empty.md +163 -0
  13. package/dist/ai/docs/Expand.md +143 -0
  14. package/dist/ai/docs/FileUpload.md +225 -0
  15. package/dist/ai/docs/Form.md +107 -0
  16. package/dist/ai/docs/FormReset.md +117 -0
  17. package/dist/ai/docs/Heading.md +88 -0
  18. package/dist/ai/docs/Input.md +237 -0
  19. package/dist/ai/docs/InputField.md +170 -0
  20. package/dist/ai/docs/List.md +205 -0
  21. package/dist/ai/docs/Menu.md +166 -0
  22. package/dist/ai/docs/Modal.md +280 -0
  23. package/dist/ai/docs/MultiSelect.md +196 -0
  24. package/dist/ai/docs/Notifications.md +231 -0
  25. package/dist/ai/docs/PageCalendar.md +271 -0
  26. package/dist/ai/docs/Polymorph.md +159 -0
  27. package/dist/ai/docs/Progress.md +145 -0
  28. package/dist/ai/docs/Radiobox.md +128 -0
  29. package/dist/ai/docs/RenderOnView.md +138 -0
  30. package/dist/ai/docs/Resizable.md +159 -0
  31. package/dist/ai/docs/Select.md +284 -0
  32. package/dist/ai/docs/Shortcut.md +105 -0
  33. package/dist/ai/docs/Skeleton.md +166 -0
  34. package/dist/ai/docs/Slider.md +144 -0
  35. package/dist/ai/docs/Slot.md +173 -0
  36. package/dist/ai/docs/Spinner.md +118 -0
  37. package/dist/ai/docs/Stats.md +137 -0
  38. package/dist/ai/docs/Step.md +159 -0
  39. package/dist/ai/docs/Switch.md +167 -0
  40. package/dist/ai/docs/Table.md +298 -0
  41. package/dist/ai/docs/Tabs.md +191 -0
  42. package/dist/ai/docs/Tag.md +224 -0
  43. package/dist/ai/docs/TaskList.md +144 -0
  44. package/dist/ai/docs/Textarea.md +167 -0
  45. package/dist/ai/docs/Timeline.md +210 -0
  46. package/dist/ai/docs/Toolbar.md +132 -0
  47. package/dist/ai/docs/Tooltip.md +231 -0
  48. package/dist/ai/docs/TransferList.md +142 -0
  49. package/dist/ai/docs/Typography.md +187 -0
  50. package/dist/ai/docs/Wizard.md +213 -0
  51. package/dist/ai/docs/index.md +183 -0
  52. package/dist/components/core/button.d.ts +2 -8
  53. package/dist/components/core/button.d.ts.map +1 -1
  54. package/dist/components/core/polymorph.d.ts.map +1 -1
  55. package/dist/components/core/slot.d.ts +1 -1
  56. package/dist/components/core/slot.d.ts.map +1 -1
  57. package/dist/components/core/tag.d.ts +2 -2
  58. package/dist/components/core/tag.d.ts.map +1 -1
  59. package/dist/components/core/typography.d.ts.map +1 -1
  60. package/dist/components/display/alert.d.ts.map +1 -1
  61. package/dist/components/display/calendar.d.ts.map +1 -1
  62. package/dist/components/display/card.d.ts.map +1 -1
  63. package/dist/components/display/list.d.ts.map +1 -1
  64. package/dist/components/display/notifications.d.ts +2 -0
  65. package/dist/components/display/notifications.d.ts.map +1 -1
  66. package/dist/components/display/progress.d.ts.map +1 -1
  67. package/dist/components/display/skeleton.d.ts.map +1 -1
  68. package/dist/components/display/step.d.ts.map +1 -1
  69. package/dist/components/display/tabs.d.ts.map +1 -1
  70. package/dist/components/floating/command-palette.d.ts +1 -0
  71. package/dist/components/floating/command-palette.d.ts.map +1 -1
  72. package/dist/components/floating/dropdown.d.ts +1 -0
  73. package/dist/components/floating/dropdown.d.ts.map +1 -1
  74. package/dist/components/floating/menu.d.ts +2 -2
  75. package/dist/components/floating/menu.d.ts.map +1 -1
  76. package/dist/components/floating/modal.d.ts +20 -53
  77. package/dist/components/floating/modal.d.ts.map +1 -1
  78. package/dist/components/floating/tooltip.d.ts.map +1 -1
  79. package/dist/components/floating/wizard.d.ts +1 -1
  80. package/dist/components/floating/wizard.d.ts.map +1 -1
  81. package/dist/components/form/autocomplete.d.ts.map +1 -1
  82. package/dist/components/form/date-picker.d.ts.map +1 -1
  83. package/dist/components/form/free-text.d.ts.map +1 -1
  84. package/dist/components/form/input-field.d.ts +3 -2
  85. package/dist/components/form/input-field.d.ts.map +1 -1
  86. package/dist/components/form/multi-select.d.ts.map +1 -1
  87. package/dist/components/form/select.d.ts.map +1 -1
  88. package/dist/components/form/slider.d.ts.map +1 -1
  89. package/dist/components/index.d.ts +2 -0
  90. package/dist/components/index.d.ts.map +1 -1
  91. package/dist/components/page-calendar/calendar-header.d.ts +16 -0
  92. package/dist/components/page-calendar/calendar-header.d.ts.map +1 -0
  93. package/dist/components/page-calendar/day-view.d.ts +12 -0
  94. package/dist/components/page-calendar/day-view.d.ts.map +1 -0
  95. package/dist/components/page-calendar/event-pill.d.ts +9 -0
  96. package/dist/components/page-calendar/event-pill.d.ts.map +1 -0
  97. package/dist/components/page-calendar/index.d.ts +4 -0
  98. package/dist/components/page-calendar/index.d.ts.map +1 -0
  99. package/dist/components/page-calendar/month-view.d.ts +11 -0
  100. package/dist/components/page-calendar/month-view.d.ts.map +1 -0
  101. package/dist/components/page-calendar/page-calendar.d.ts +18 -0
  102. package/dist/components/page-calendar/page-calendar.d.ts.map +1 -0
  103. package/dist/components/page-calendar/page-calendar.types.d.ts +18 -0
  104. package/dist/components/page-calendar/page-calendar.types.d.ts.map +1 -0
  105. package/dist/components/page-calendar/page-calendar.utils.d.ts +18 -0
  106. package/dist/components/page-calendar/page-calendar.utils.d.ts.map +1 -0
  107. package/dist/components/page-calendar/week-view.d.ts +11 -0
  108. package/dist/components/page-calendar/week-view.d.ts.map +1 -0
  109. package/dist/components/table/index.d.ts.map +1 -1
  110. package/dist/components/table/inner-table.d.ts.map +1 -1
  111. package/dist/components/table/metadata.d.ts.map +1 -1
  112. package/dist/components/table/row.d.ts.map +1 -1
  113. package/dist/components/table/table-lib.d.ts.map +1 -1
  114. package/dist/components/table/thead.d.ts.map +1 -1
  115. package/dist/config/context.d.ts.map +1 -1
  116. package/dist/config/default-translations.d.ts +21 -4
  117. package/dist/config/default-translations.d.ts.map +1 -1
  118. package/dist/constants.d.ts.map +1 -1
  119. package/dist/hooks/use-components-provider.d.ts.map +1 -1
  120. package/dist/hooks/use-form.d.ts +11 -11
  121. package/dist/hooks/use-form.d.ts.map +1 -1
  122. package/dist/hooks/use-input-id.d.ts.map +1 -1
  123. package/dist/hooks/use-preferences.d.ts.map +1 -1
  124. package/dist/hooks/use-previous.d.ts.map +1 -1
  125. package/dist/hooks/use-reactive.d.ts.map +1 -1
  126. package/dist/hooks/use-resize-observer.d.ts.map +1 -1
  127. package/dist/hooks/use-stable-ref.d.ts.map +1 -1
  128. package/dist/hooks/use-swipe.d.ts.map +1 -1
  129. package/dist/hooks/use-translations.d.ts +21 -4
  130. package/dist/hooks/use-translations.d.ts.map +1 -1
  131. package/dist/index.css +1 -0
  132. package/dist/index.d.ts.map +1 -1
  133. package/dist/index.js +28 -20
  134. package/dist/index.js.map +1 -1
  135. package/dist/index.mjs +13862 -12512
  136. package/dist/index.mjs.map +1 -1
  137. package/dist/index.umd.js +24 -17
  138. package/dist/index.umd.js.map +1 -1
  139. package/dist/lib/dom.d.ts +1 -0
  140. package/dist/lib/dom.d.ts.map +1 -1
  141. package/dist/lib/fns.d.ts.map +1 -1
  142. package/dist/preset/plugin.tailwind.d.ts +9 -0
  143. package/dist/preset/plugin.tailwind.d.ts.map +1 -0
  144. package/dist/preset/plugin.tailwind.js +27 -0
  145. package/dist/preset/preset.tailwind.d.ts +8 -0
  146. package/dist/preset/preset.tailwind.d.ts.map +1 -0
  147. package/dist/preset/preset.tailwind.js +54 -0
  148. package/dist/preset/src/styles/common.d.ts +2 -14
  149. package/dist/preset/src/styles/common.d.ts.map +1 -1
  150. package/dist/preset/src/styles/common.js +1 -0
  151. package/dist/preset/src/styles/dark.d.ts.map +1 -1
  152. package/dist/preset/src/styles/dark.js +119 -114
  153. package/dist/preset/src/styles/light.d.ts.map +1 -1
  154. package/dist/preset/src/styles/light.js +111 -106
  155. package/dist/preset/src/styles/theme.types.d.ts +17 -8
  156. package/dist/preset/src/styles/theme.types.d.ts.map +1 -1
  157. package/dist/styles/common.d.ts +2 -14
  158. package/dist/styles/common.d.ts.map +1 -1
  159. package/dist/styles/dark.d.ts.map +1 -1
  160. package/dist/styles/light.d.ts.map +1 -1
  161. package/dist/styles/theme.types.d.ts +17 -8
  162. package/dist/styles/theme.types.d.ts.map +1 -1
  163. package/package.json +299 -301
  164. package/dist/components/core/button.jsx +0 -86
  165. package/dist/components/core/heading.jsx +0 -4
  166. package/dist/components/core/polymorph.jsx +0 -5
  167. package/dist/components/core/render-on-view.jsx +0 -31
  168. package/dist/components/core/resizable.jsx +0 -51
  169. package/dist/components/core/slot.jsx +0 -163
  170. package/dist/components/core/tag.jsx +0 -51
  171. package/dist/components/core/typography.jsx +0 -26
  172. package/dist/components/display/alert.jsx +0 -56
  173. package/dist/components/display/calendar.jsx +0 -301
  174. package/dist/components/display/card.jsx +0 -43
  175. package/dist/components/display/empty.jsx +0 -11
  176. package/dist/components/display/list.jsx +0 -81
  177. package/dist/components/display/notifications.jsx +0 -98
  178. package/dist/components/display/progress.jsx +0 -13
  179. package/dist/components/display/shortcut.jsx +0 -23
  180. package/dist/components/display/skeleton.jsx +0 -14
  181. package/dist/components/display/spinner.jsx +0 -7
  182. package/dist/components/display/stats.jsx +0 -20
  183. package/dist/components/display/step.jsx +0 -131
  184. package/dist/components/display/tabs.jsx +0 -100
  185. package/dist/components/display/timeline.jsx +0 -25
  186. package/dist/components/floating/command-palette.jsx +0 -172
  187. package/dist/components/floating/dropdown.jsx +0 -53
  188. package/dist/components/floating/expand.jsx +0 -44
  189. package/dist/components/floating/menu.jsx +0 -147
  190. package/dist/components/floating/modal.jsx +0 -241
  191. package/dist/components/floating/toolbar.jsx +0 -5
  192. package/dist/components/floating/tooltip.jsx +0 -64
  193. package/dist/components/floating/wizard.jsx +0 -164
  194. package/dist/components/form/autocomplete.jsx +0 -275
  195. package/dist/components/form/checkbox.jsx +0 -12
  196. package/dist/components/form/date-picker.jsx +0 -115
  197. package/dist/components/form/file-upload.jsx +0 -133
  198. package/dist/components/form/form.jsx +0 -10
  199. package/dist/components/form/formReset.jsx +0 -17
  200. package/dist/components/form/free-text.jsx +0 -41
  201. package/dist/components/form/input-field.jsx +0 -54
  202. package/dist/components/form/input.jsx +0 -36
  203. package/dist/components/form/multi-select.jsx +0 -328
  204. package/dist/components/form/radiobox.jsx +0 -6
  205. package/dist/components/form/select.jsx +0 -42
  206. package/dist/components/form/slider.jsx +0 -45
  207. package/dist/components/form/switch.jsx +0 -46
  208. package/dist/components/form/task-list.jsx +0 -26
  209. package/dist/components/form/textarea.jsx +0 -12
  210. package/dist/components/form/transfer-list.jsx +0 -39
  211. package/dist/components/index.js +0 -43
  212. package/dist/components/table/filter.jsx +0 -141
  213. package/dist/components/table/group.jsx +0 -68
  214. package/dist/components/table/index.jsx +0 -60
  215. package/dist/components/table/inner-table.jsx +0 -104
  216. package/dist/components/table/metadata.jsx +0 -37
  217. package/dist/components/table/pagination.jsx +0 -73
  218. package/dist/components/table/row.jsx +0 -58
  219. package/dist/components/table/sort.jsx +0 -105
  220. package/dist/components/table/table-lib.js +0 -84
  221. package/dist/components/table/table.context.jsx +0 -4
  222. package/dist/components/table/thead.jsx +0 -103
  223. package/dist/config/context.js +0 -12
  224. package/dist/config/default-translations.jsx +0 -66
  225. package/dist/config/default-tweaks.js +0 -4
  226. package/dist/constants.js +0 -2
  227. package/dist/hooks/use-click-outside.js +0 -17
  228. package/dist/hooks/use-color-parser.js +0 -9
  229. package/dist/hooks/use-components-provider.jsx +0 -16
  230. package/dist/hooks/use-debounce.js +0 -12
  231. package/dist/hooks/use-floating-ref.js +0 -6
  232. package/dist/hooks/use-form.js +0 -549
  233. package/dist/hooks/use-hover.js +0 -18
  234. package/dist/hooks/use-input-id.js +0 -5
  235. package/dist/hooks/use-is-coarse-device.js +0 -12
  236. package/dist/hooks/use-locale.js +0 -10
  237. package/dist/hooks/use-media-query.js +0 -25
  238. package/dist/hooks/use-on-event.js +0 -7
  239. package/dist/hooks/use-parent.js +0 -21
  240. package/dist/hooks/use-preferences.js +0 -23
  241. package/dist/hooks/use-previous.js +0 -8
  242. package/dist/hooks/use-reactive.js +0 -8
  243. package/dist/hooks/use-remove-scroll.js +0 -61
  244. package/dist/hooks/use-resize-observer.js +0 -17
  245. package/dist/hooks/use-stable-ref.js +0 -8
  246. package/dist/hooks/use-swipe.js +0 -16
  247. package/dist/hooks/use-translations.js +0 -9
  248. package/dist/hooks/use-tweaks.js +0 -9
  249. package/dist/hooks/use-window-size.js +0 -14
  250. package/dist/lib/combi-keys.js +0 -60
  251. package/dist/lib/dict.js +0 -39
  252. package/dist/lib/dom.js +0 -44
  253. package/dist/lib/fns.js +0 -46
  254. package/dist/lib/fzf.js +0 -117
  255. package/dist/lib/keyboard-area.js +0 -14
  256. package/dist/preset/tailwindcssv4.d.ts +0 -3
  257. package/dist/preset/tailwindcssv4.d.ts.map +0 -1
  258. package/dist/preset/tailwindcssv4.js +0 -75
  259. package/dist/styles/common.js +0 -28
  260. package/dist/styles/dark.js +0 -209
  261. package/dist/styles/design-tokens.js +0 -69
  262. package/dist/styles/light.js +0 -209
  263. package/dist/styles/theme.js +0 -4
  264. package/dist/styles/theme.types.js +0 -1
  265. package/dist/types.js +0 -1
package/dist/ai/SKILL.md ADDED
@@ -0,0 +1,266 @@
1
+ ---
2
+ name: g4rcez-components
3
+ description: >
4
+ Use when: setting up @g4rcez/components in a new project, migrating native
5
+ HTML elements or hand-rolled UI to this design system, building any React UI
6
+ that should use @g4rcez/components, or when the user's project already has
7
+ @g4rcez/components as a dependency. Covers installation, Tailwind preset,
8
+ theming with createTokenStyles/TokenRemap, ComponentsProvider/tweaks,
9
+ parsers, the full component catalog (components, hooks, React, UI,
10
+ design-system, tokens, Tailwind, forms, modals, notifications, tables,
11
+ calendar, theming), and native-element migration.
12
+ ---
13
+
14
+ # @g4rcez/components — Agent Skill
15
+
16
+ A React design system built on Tailwind CSS and design tokens. This skill covers
17
+ installation, Tailwind preset setup, theming APIs, conventions, the full
18
+ component catalog, and migration from native HTML patterns.
19
+
20
+ ---
21
+
22
+ ## 1 — Package Structure & Installation
23
+
24
+ ```bash
25
+ pnpm add @g4rcez/components
26
+ ```
27
+
28
+ When installed in `node_modules`, the package follows this structure:
29
+ - `node_modules/@g4rcez/components/dist/` — Compiled JS/TS and CSS.
30
+ - `node_modules/@g4rcez/components/index.css` — Main stylesheet.
31
+ - `node_modules/@g4rcez/components/ai/` — This skill and detailed markdown documentation.
32
+ - `node_modules/@g4rcez/components/ai/docs/` — Component-specific documentation files.
33
+
34
+ ### Tailwind Preset (recommended)
35
+
36
+ Add the library preset in your `tailwind.config.ts` (or `.js`). The preset
37
+ wires all design tokens as Tailwind utilities.
38
+
39
+ ```ts
40
+ // tailwind.config.ts
41
+ import preset from "@g4rcez/components/preset.tailwind";
42
+
43
+ export default {
44
+ presets: [preset],
45
+ content: [
46
+ "./src/**/*.{ts,tsx}",
47
+ // include node_modules so Tailwind scans the library's classes:
48
+ "./node_modules/@g4rcez/components/dist/**/*.js",
49
+ ],
50
+ };
51
+ ```
52
+
53
+ ### Theme class (required)
54
+
55
+ Apply `light` or `dark` on your root element:
56
+
57
+ ```tsx
58
+ <html className="light">…</html>
59
+ // or
60
+ <html className="dark">…</html>
61
+ ```
62
+
63
+ ### ComponentsProvider (optional, mandatory for dark-mode)
64
+
65
+ Wrap your app root to enable i18n strings, locale-aware masks, and the
66
+ programmatic `Modal.confirm` utility:
67
+
68
+ ```tsx
69
+ import { ComponentsProvider } from "@g4rcez/components";
70
+
71
+ export default function App({ children }) {
72
+ return (
73
+ <ComponentsProvider locale="en-US">
74
+ {children}
75
+ </ComponentsProvider>
76
+ );
77
+ }
78
+ ```
79
+
80
+ ---
81
+
82
+ ## 2 — Theme Setup with createTokenStyles
83
+
84
+ Use `createTokenStyles` to generate scoped CSS strings for light and dark
85
+ themes, then inject them into `<head>`.
86
+
87
+ ### API
88
+
89
+ ```ts
90
+ import {
91
+ createTokenStyles,
92
+ createCssProperties,
93
+ type TokenRemap,
94
+ } from "@g4rcez/components";
95
+ ```
96
+
97
+ | Function | Signature | Returns |
98
+ |----------|-----------|---------|
99
+ | `createTokenStyles` | `(theme: DesignTokens, map?: TokenRemap) => string` | Scoped CSS string, e.g. `html { --primary: … }` |
100
+ | `createCssProperties` | `(theme: DesignTokens, map?: TokenRemap) => CSSProperties` | Inline style object with CSS custom properties |
101
+
102
+ - When `map.name` is set (e.g. `"dark"`), the output is scoped to
103
+ `html.dark { … }` instead of `html { … }`.
104
+ - Use `createTokenStyles` for `<style>` injection; use `createCssProperties`
105
+ for inline `style` props.
106
+
107
+ ### Two-theme pattern (light + dark)
108
+
109
+ ```tsx
110
+ import {
111
+ createTokenStyles,
112
+ type TokenRemap,
113
+ defaultLightTheme,
114
+ defaultDarkTheme,
115
+ } from "@g4rcez/components";
116
+
117
+ const tokenRemap: TokenRemap = {
118
+ colors: (t) => {
119
+ // Strip hsla( prefix and ) suffix for Tailwind opacity utility support
120
+ t.value = t.value.replace("hsla(", "").replace(/\)$/, "");
121
+ return t;
122
+ },
123
+ };
124
+
125
+ const stylesLight = createTokenStyles(defaultLightTheme, tokenRemap);
126
+ const stylesDark = createTokenStyles(defaultDarkTheme, {
127
+ ...tokenRemap,
128
+ name: "dark", // scopes output to html.dark { … }
129
+ });
130
+
131
+ // In your layout:
132
+ export default function RootLayout({ children }) {
133
+ return (
134
+ <html lang="en">
135
+ <head>
136
+ <style dangerouslySetInnerHTML={{ __html: stylesLight }} />
137
+ <style dangerouslySetInnerHTML={{ __html: stylesDark }} />
138
+ </head>
139
+ <body>{children}</body>
140
+ </html>
141
+ );
142
+ }
143
+ ```
144
+
145
+ ---
146
+
147
+ ## 3 — TokenRemap
148
+
149
+ `TokenRemap` lets you transform each design token value before it is emitted
150
+ as a CSS custom property.
151
+
152
+ ```ts
153
+ export type TokenRemap = Partial<
154
+ Record<
155
+ "colors" | "spacing" | "rounded" | "customTokens" | "zIndex",
156
+ (t: Token) => Token
157
+ > & { name: string }
158
+ >;
159
+ ```
160
+
161
+ ### Why strip `hsla(…)` in the colors transformer
162
+
163
+ Tailwind v4 opacity utilities (e.g. `bg-primary/50`) expect raw channel values
164
+ like `210 40% 60%` — not a wrapped `hsla(210 40% 60%)`.
165
+
166
+ ---
167
+
168
+ ## 4 — ComponentsProvider & Tweaks
169
+
170
+ ```tsx
171
+ import { ComponentsProvider, type Tweaks, parsers } from "@g4rcez/components";
172
+
173
+ const tweaks: Tweaks = {
174
+ table: {
175
+ sorters: true, // show/hide column sort controls
176
+ filters: true, // show/hide column filter controls
177
+ operations: true, // show/hide table operation buttons
178
+ sticky: 55, // px offset for sticky header
179
+ },
180
+ };
181
+
182
+ <ComponentsProvider
183
+ locale="en-US"
184
+ tweaks={tweaks}
185
+ parser={parsers.hsla}
186
+ >
187
+ {children}
188
+ </ComponentsProvider>
189
+ ```
190
+
191
+ ---
192
+
193
+ ## 5 — Key Conventions
194
+
195
+ ### Never use raw Tailwind color classes
196
+
197
+ ```tsx
198
+ // ❌ Wrong
199
+ <div className="bg-blue-500 text-white">…</div>
200
+
201
+ // ✅ Right — use design-token classes
202
+ <div className="bg-primary text-primary-foreground">…</div>
203
+ ```
204
+
205
+ ### Always use component `theme` / `variant` props
206
+
207
+ ```tsx
208
+ // ❌ Wrong
209
+ <button className="bg-red-600 text-white">Delete</button>
210
+
211
+ // ✅ Right
212
+ <Button theme="danger">Delete</Button>
213
+ ```
214
+
215
+ ---
216
+
217
+ ## 6 — Component Catalog
218
+
219
+ ### Import paths
220
+
221
+ The library supports both barrel imports and sub-path imports for better tree-shaking.
222
+
223
+ | Component | Main Export | Sub-path Export |
224
+ |-----------|-------------|-----------------|
225
+ | `Button` | `@g4rcez/components` | `@g4rcez/components/button` |
226
+ | `Input` | `@g4rcez/components` | `@g4rcez/components/input` |
227
+ | `Modal` | `@g4rcez/components` | `@g4rcez/components/modal` |
228
+ | `Table` | `@g4rcez/components` | `@g4rcez/components/table` |
229
+ | `Select` | `@g4rcez/components` | `@g4rcez/components/select` |
230
+
231
+ See `node_modules/@g4rcez/components/ai/docs/index.md` for the full list of exports.
232
+
233
+ ---
234
+
235
+ ## 7 — Migration Guide
236
+
237
+ Use this table when migrating native HTML elements to library equivalents.
238
+
239
+ | Native / custom pattern | Library replacement |
240
+ |-------------------------|---------------------|
241
+ | `<button>` | `Button` |
242
+ | `<input type="text">` | `Input` |
243
+ | `<input type="date">` | `DatePicker` |
244
+ | `<input type="checkbox">` | `Checkbox` |
245
+ | `<select>` | `Select` |
246
+ | Custom modal / dialog | `Modal` (type `"dialog"`) |
247
+ | Side panel / drawer | `Modal` (type `"drawer"`) |
248
+ | Toast / notifications | `Notifications` |
249
+ | Data table | `Table` |
250
+
251
+ ---
252
+
253
+ ## 8 — Where to Find Detailed Docs
254
+
255
+ For any specific component, read its doc file for full props, design tokens,
256
+ and usage examples. These files are located within the package in `node_modules`:
257
+
258
+ `node_modules/@g4rcez/components/ai/docs/<ComponentName>.md`
259
+
260
+ **Examples:**
261
+ - `node_modules/@g4rcez/components/ai/docs/Button.md`
262
+ - `node_modules/@g4rcez/components/ai/docs/Input.md`
263
+ - `node_modules/@g4rcez/components/ai/docs/Modal.md`
264
+ - `node_modules/@g4rcez/components/ai/docs/Table.md`
265
+ - `node_modules/@g4rcez/components/ai/docs/Form.md`
266
+
package/dist/ai/docs/Alert.md ADDED
@@ -0,0 +1,167 @@
1
+ ---
2
+ title: Alert
3
+ description: Collapsible, themed alert banner for displaying important messages and status updates.
4
+ package: "@g4rcez/components"
5
+ export: "{ Alert }"
6
+ import: "import { Alert } from '@g4rcez/components/alert'"
7
+ category: display
8
+ ---
9
+
10
+ # Alert
11
+
12
+ Collapsible, themed alert banner for displaying important messages and status updates.
13
+
14
+ ## Import
15
+
16
+ ```tsx
17
+ import { Alert } from "@g4rcez/components/alert";
18
+ ```
19
+
20
+ ## Props
21
+
22
+ | Prop | Type | Default | Description |
23
+ |------|------|---------|-------------|
24
+ | `theme` | `"primary" \| "secondary" \| "info" \| "warn" \| "danger" \| "success" \| "neutral"` | `"neutral"` | Visual theme variant |
25
+ | `title` | `string` | — | Alert heading text |
26
+ | `Icon` | `React.ReactElement` | — | Custom icon element (overrides default theme icon) |
27
+ | `open` | `boolean` | `true` | Controls visibility with collapse animation |
28
+ | `onClose` | `(nextState: boolean) => void` | — | Callback when close button is clicked; omit to hide the button |
29
+ | `container` | `string` | — | Additional classes for the outer wrapper |
30
+ | `as` | `React.ElementType` | `"div"` | Polymorphic root element |
31
+ | `className` | `string` | — | Additional classes for the alert element |
32
+ | `children` | `React.ReactNode` | — | Alert body content |
33
+
34
+ ## Design Tokens
35
+
36
+ Tokens this component reads. Customize by overriding these CSS variables in your theme.
37
+
38
+ | Token | CSS Variable | Purpose |
39
+ |-------|-------------|---------|
40
+ | `bg-alert-{theme}-bg` | `--alert-{theme}-bg` | Background per theme |
41
+ | `text-alert-{theme}-text` | `--alert-{theme}-text` | Text color per theme |
42
+ | `border-alert-{theme}-border` | `--alert-{theme}-border` | Border color per theme |
43
+ | `border-card-border` | `--card-border` | Border for `neutral` theme |
44
+ | `text-foreground` | `--foreground` | Close button color |
45
+ | `text-danger` | `--danger` | Close button hover color |
46
+
47
+ Themes: `primary`, `secondary`, `info`, `warn`, `danger`, `success`, `neutral`.
48
+
49
+ ## Themes
50
+
51
+ Each theme maps to a set of `bg-alert-{theme}-*` tokens and provides default icons for some variants:
52
+
53
+ | Theme | Default Icon |
54
+ |-------|-------------|
55
+ | `success` | `CheckCircleIcon` |
56
+ | `info` | `InfoIcon` |
57
+ | `danger` | `TriangleAlertIcon` |
58
+ | `warn` | — |
59
+ | `primary` / `secondary` / `neutral` | — |
60
+
61
+ ## Examples
62
+
63
+ ### Basic Variants
64
+
65
+ ```tsx
66
+ <Alert theme="info" title="Information">
67
+ This is an informational message.
68
+ </Alert>
69
+
70
+ <Alert theme="success" title="Success">
71
+ Your changes have been saved successfully.
72
+ </Alert>
73
+
74
+ <Alert theme="warn" title="Warning">
75
+ Please review your input before proceeding.
76
+ </Alert>
77
+
78
+ <Alert theme="danger" title="Error">
79
+ Something went wrong. Please try again.
80
+ </Alert>
81
+ ```
82
+
83
+ ### With Custom Icon
84
+
85
+ ```tsx
86
+ import { BellIcon } from "lucide-react";
87
+
88
+ <Alert theme="info" title="Notification" Icon={<BellIcon size={20} />}>
89
+ You have new messages.
90
+ </Alert>
91
+ ```
92
+
93
+ ### Dismissible Alert
94
+
95
+ ```tsx
96
+ const [showAlert, setShowAlert] = useState(true);
97
+
98
+ <Alert
99
+ theme="success"
100
+ title="Welcome!"
101
+ open={showAlert}
102
+ onClose={() => setShowAlert(false)}
103
+ >
104
+ Thanks for joining our platform.
105
+ </Alert>
106
+ ```
107
+
108
+ ### Rich Content
109
+
110
+ ```tsx
111
+ import { Button } from "@g4rcez/components/button";
112
+
113
+ <Alert theme="info" title="Update Available">
114
+ <p>A new version of the application is available.</p>
115
+ <div className="mt-3 flex gap-2">
116
+ <Button theme="primary" size="small">Update Now</Button>
117
+ <Button theme="neutral" size="small">Later</Button>
118
+ </div>
119
+ </Alert>
120
+ ```
121
+
122
+ ### Form Validation
123
+
124
+ ```tsx
125
+ const [errors, setErrors] = useState<string[]>([]);
126
+
127
+ <Alert theme="danger" title="Validation Errors" open={errors.length > 0}>
128
+ <ul className="list-disc list-inside space-y-1">
129
+ {errors.map((error, index) => (
130
+ <li key={index}>{error}</li>
131
+ ))}
132
+ </ul>
133
+ </Alert>
134
+ ```
135
+
136
+ ## Do
137
+
138
+ - Use `theme` to match message severity (`danger` for errors, `success` for completions, `warn` for cautions).
139
+ - Provide a concise, descriptive `title` so users immediately understand the alert.
140
+ - Supply `onClose` when the alert should be user-dismissible.
141
+ - Use design-token classes for any wrapper elements (`bg-background`, `border-border`).
142
+
143
+ ## Don't
144
+
145
+ - Don't pass raw Tailwind color classes (`bg-blue-500`, `text-white`, `border-gray-300`) — use `theme` or design tokens instead.
146
+ - Don't use arbitrary Tailwind values (`bg-[#abc]`, `bg-[--my-var]`) — override CSS variables in your `@theme` block instead.
147
+ - Don't use `danger` for non-critical information; use `warn` or `info` instead.
148
+ - Don't omit `onClose` if the alert must be dismissible — the close button only renders when the prop is provided.
149
+
150
+ ## Accessibility
151
+
152
+ - Renders with `role="alert"` for immediate screen reader announcement.
153
+ - Title uses a semantic `h4` element for proper heading hierarchy.
154
+ - Close button is keyboard accessible and uses a visible icon.
155
+ - The `aria-hidden` attribute on the collapse wrapper prevents interaction with hidden content.
156
+
157
+ ## Data Attributes
158
+
159
+ - `data-component="alert"` — outer wrapper element.
160
+ - `data-theme` — current theme variant (e.g. `"danger"`).
161
+ - `data-open` — current visibility state (`"true"` / `"false"`).
162
+
163
+ ## Notes
164
+
165
+ - Animation uses Framer Motion (`motion/react`): 0.7 s collapse/expand with spring easing.
166
+ - When `open` becomes `false`, the alert collapses and is removed from the DOM via `AnimatePresence`.
167
+ - The component is polymorphic — pass `as="section"` or any other element type via the `as` prop.
package/dist/ai/docs/AnimatedList.md ADDED
@@ -0,0 +1,205 @@
1
+ ---
2
+ title: AnimatedList
3
+ description: Animated list that expands each item into a floating detail overlay on click.
4
+ package: "@g4rcez/components"
5
+ export: "{ AnimatedList, AnimatedListItem }"
6
+ import: "import { AnimatedList, AnimatedListItem } from '@g4rcez/components'"
7
+ category: display
8
+ ---
9
+
10
+ # AnimatedList
11
+
12
+ Animated list that expands each item into a floating detail overlay on click.
13
+
14
+ ## Import
15
+
16
+ ```tsx
17
+ import { AnimatedList, AnimatedListItem } from "@g4rcez/components";
18
+ ```
19
+
20
+ ## Props
21
+
22
+ ### AnimatedList
23
+
24
+ | Prop | Type | Default | Description |
25
+ |------|------|---------|-------------|
26
+ | `children` | `React.ReactNode` | — | One or more `AnimatedListItem` elements. |
27
+
28
+ ### AnimatedListItem
29
+
30
+ | Prop | Type | Default | Description |
31
+ |------|------|---------|-------------|
32
+ | `title` | `Label` | — | Primary heading shown in the list row and the overlay header. |
33
+ | `description` | `Label` | — | Secondary text shown below the title in both the row and overlay header. |
34
+ | `children` | `Label` | — | Content rendered inside the expanded overlay below the header. |
35
+ | `avatar` | `Label` | — | Optional node (icon, image, or element) shown at the leading edge of the row. |
36
+ | `leading` | `React.FC<{ open: () => void }>` | — | Optional render-prop component placed at the trailing edge of the row. Receives an `open` function to trigger the overlay programmatically. |
37
+
38
+ `Label` is `string | number | ReactNode`.
39
+
40
+ ## Design Tokens
41
+
42
+ Tokens this component reads. Customize by overriding these CSS variables in your theme.
43
+
44
+ | Token | CSS Variable | Purpose |
45
+ |-------|-------------|---------|
46
+ | `border-card-border` | `--card-border` | Row separator border and overlay border |
47
+ | `bg-card-background` | `--card-background` | Overlay card background |
48
+ | `rounded-card` | `--radius-card` | Overlay card border radius |
49
+ | `shadow-shadow-card` | `--shadow-card` | Overlay card drop shadow |
50
+ | `text-foreground` | `--foreground` | Default row and overlay text color |
51
+ | `text-secondary` | `--secondary` | Description text color in rows and overlay |
52
+ | `text-primary` | `--primary` | Row title hover color |
53
+ | `text-danger` | `--danger` | Close button hover color |
54
+ | `bg-floating-overlay` | `--floating-overlay` | Overlay backdrop tint (used at 70% opacity) |
55
+ | `z-floating` | `--z-floating` | `z-index` for the overlay (value: 22) |
56
+ | `z-overlay` | `--z-overlay` | `z-index` for the backdrop scrim |
57
+
58
+ ## Examples
59
+
60
+ ### Basic list
61
+
62
+ ```tsx
63
+ import { AnimatedList, AnimatedListItem } from "@g4rcez/components";
64
+
65
+ const items = [
66
+ { id: "1", name: "Alice Johnson", role: "Engineering" },
67
+ { id: "2", name: "Bob Smith", role: "Design" },
68
+ ];
69
+
70
+ export function TeamList() {
71
+ return (
72
+ <AnimatedList>
73
+ {items.map((member) => (
74
+ <AnimatedListItem
75
+ key={member.id}
76
+ title={member.name}
77
+ description={member.role}
78
+ >
79
+ <p className="text-foreground">
80
+ Full profile details for {member.name}.
81
+ </p>
82
+ </AnimatedListItem>
83
+ ))}
84
+ </AnimatedList>
85
+ );
86
+ }
87
+ ```
88
+
89
+ ### With avatar
90
+
91
+ ```tsx
92
+ import { AnimatedList, AnimatedListItem } from "@g4rcez/components";
93
+ import { UserCircleIcon } from "lucide-react";
94
+
95
+ export function UserDirectory() {
96
+ return (
97
+ <AnimatedList>
98
+ <AnimatedListItem
99
+ title="Carol White"
100
+ description="Product Manager"
101
+ avatar={<UserCircleIcon size={40} className="text-muted-foreground" />}
102
+ >
103
+ <div className="flex flex-col gap-2 text-foreground">
104
+ <p>Department: Product</p>
105
+ <p>Location: San Francisco</p>
106
+ </div>
107
+ </AnimatedListItem>
108
+ </AnimatedList>
109
+ );
110
+ }
111
+ ```
112
+
113
+ ### With trailing action using `leading`
114
+
115
+ ```tsx
116
+ import { AnimatedList, AnimatedListItem } from "@g4rcez/components";
117
+ import { Button } from "@g4rcez/components/button";
118
+
119
+ export function OrderList({ orders }: { orders: Order[] }) {
120
+ return (
121
+ <AnimatedList>
122
+ {orders.map((order) => (
123
+ <AnimatedListItem
124
+ key={order.id}
125
+ title={`Order #${order.id}`}
126
+ description={`Total: ${order.total}`}
127
+ leading={({ open }) => (
128
+ <Button size="small" theme="ghost-muted" onClick={open}>
129
+ View details
130
+ </Button>
131
+ )}
132
+ >
133
+ <OrderDetailContent order={order} />
134
+ </AnimatedListItem>
135
+ ))}
136
+ </AnimatedList>
137
+ );
138
+ }
139
+ ```
140
+
141
+ ### Activity feed
142
+
143
+ ```tsx
144
+ import { AnimatedList, AnimatedListItem } from "@g4rcez/components";
145
+ import { BellIcon, CheckCircleIcon, AlertTriangleIcon } from "lucide-react";
146
+
147
+ const activities = [
148
+ { id: "a1", icon: <CheckCircleIcon size={20} className="text-success" />, title: "Deployment succeeded", description: "2 minutes ago", detail: "All 3 services started." },
149
+ { id: "a2", icon: <AlertTriangleIcon size={20} className="text-warn" />, title: "High memory usage", description: "15 minutes ago", detail: "Instance i-0ab2c was at 91%." },
150
+ ];
151
+
152
+ export function ActivityFeed() {
153
+ return (
154
+ <AnimatedList>
155
+ {activities.map((a) => (
156
+ <AnimatedListItem
157
+ key={a.id}
158
+ title={a.title}
159
+ description={a.description}
160
+ avatar={a.icon}
161
+ >
162
+ <p className="text-sm text-muted-foreground">{a.detail}</p>
163
+ </AnimatedListItem>
164
+ ))}
165
+ </AnimatedList>
166
+ );
167
+ }
168
+ ```
169
+
170
+ ## Do
171
+
172
+ - Keep `title` and `description` concise — they share one row and truncation is not automatic.
173
+ - Provide meaningful `children` content in the overlay; it should justify opening the detail view.
174
+ - Use `leading` to surface a primary call-to-action without forcing the user to click the title.
175
+ - Use design-token classes for any content inside the overlay (`bg-card-background`, `text-foreground`, `border-card-border`).
176
+
177
+ ## Don't
178
+
179
+ - Don't pass raw Tailwind color classes (`bg-blue-500`, `text-white`, `border-gray-300`) — use design tokens instead.
180
+ - Don't use arbitrary Tailwind values (`bg-[#abc]`, `bg-[--my-var]`) — override CSS variables in your `@theme` block instead.
181
+ - Don't use `AnimatedList` for purely informational lists with no actionable detail — use a plain `<ul>` or the `List` component instead.
182
+ - Don't embed full sub-applications inside the overlay `children`; keep the detail view focused and lightweight.
183
+ - Don't rely on `AnimatedListItem` rendering its `children` directly — it renders nothing on its own; all rendering is managed by the parent `AnimatedList`.
184
+
185
+ ## Accessibility
186
+
187
+ - The list renders as a semantic `<ul role="list">`.
188
+ - Each item's title/description area is a `<button>` that triggers the overlay, making it keyboard accessible.
189
+ - The overlay uses `FloatingFocusManager` to trap focus and `FloatingOverlay` with `lockScroll` to prevent background interaction.
190
+ - Pressing `Escape` or clicking outside the overlay dismisses it.
191
+ - The close button inside the overlay is a focusable `<button>` element.
192
+ - `MotionConfig reducedMotion="user"` respects the user's system-level reduced-motion preference.
193
+
194
+ ## Data Attributes
195
+
196
+ - `data-component="collapse"` — internal animation wrapper (referenced in motion layout animations).
197
+ - `layoutId="item-{id}"` — shared between the list row and the overlay card to drive the expand/collapse shared-element animation.
198
+ - `layoutId="toast-{id}"` — inner content wrapper used for coordinated layout transitions.
199
+
200
+ ## Notes
201
+
202
+ - Animations use `motion/react` shared layout (`layoutId`) so the item smoothly expands from its row position into the centered overlay.
203
+ - The overlay is rendered in a `FloatingPortal`, outside the normal DOM tree, to avoid stacking-context issues.
204
+ - Only one item can be open at a time; opening a new item first closes the current one.
205
+ - `AnimatedListItem` is a thin shell component — it returns `Fragment` and holds no state. All logic lives in `AnimatedList`, which reads child `props` via `React.Children.toArray`.