rudiment-ui 0.2.0 → 0.4.0

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 (126) hide show
  1. package/LICENSE +1 -1
  2. package/README.md +222 -160
  3. package/dist/components/AppShell/AppShell.d.ts +48 -0
  4. package/dist/components/AppShell/AppShell.d.ts.map +1 -0
  5. package/dist/components/Brand/Brand.d.ts +16 -0
  6. package/dist/components/Brand/Brand.d.ts.map +1 -0
  7. package/dist/components/Breadcrumb/Breadcrumb.d.ts +14 -0
  8. package/dist/components/Breadcrumb/Breadcrumb.d.ts.map +1 -0
  9. package/dist/components/Charts/BarChart/BarChart.d.ts +5 -1
  10. package/dist/components/Charts/BarChart/BarChart.d.ts.map +1 -1
  11. package/dist/components/Charts/DonutChart/DonutChart.d.ts.map +1 -1
  12. package/dist/components/Charts/LineChart/LineChart.d.ts +18 -2
  13. package/dist/components/Charts/LineChart/LineChart.d.ts.map +1 -1
  14. package/dist/components/Checkbox/Checkbox.d.ts +7 -0
  15. package/dist/components/Checkbox/Checkbox.d.ts.map +1 -1
  16. package/dist/components/Checkbox/CheckboxGroup.d.ts.map +1 -1
  17. package/dist/components/Checkbox/CheckboxGroupContext.d.ts +4 -0
  18. package/dist/components/Checkbox/CheckboxGroupContext.d.ts.map +1 -0
  19. package/dist/components/ComboBox/ComboBox.d.ts +41 -0
  20. package/dist/components/ComboBox/ComboBox.d.ts.map +1 -0
  21. package/dist/components/DatePicker/CalendarParts.d.ts +21 -0
  22. package/dist/components/DatePicker/CalendarParts.d.ts.map +1 -0
  23. package/dist/components/DatePicker/DatePicker.d.ts +34 -0
  24. package/dist/components/DatePicker/DatePicker.d.ts.map +1 -0
  25. package/dist/components/DatePicker/DateRangePicker.d.ts +33 -0
  26. package/dist/components/DatePicker/DateRangePicker.d.ts.map +1 -0
  27. package/dist/components/DatePicker/dateUtils.d.ts +14 -0
  28. package/dist/components/DatePicker/dateUtils.d.ts.map +1 -0
  29. package/dist/components/Dialog/Dialog.d.ts +11 -1
  30. package/dist/components/Dialog/Dialog.d.ts.map +1 -1
  31. package/dist/components/Divider/Divider.d.ts +15 -0
  32. package/dist/components/Divider/Divider.d.ts.map +1 -0
  33. package/dist/components/Dot/Dot.d.ts +20 -0
  34. package/dist/components/Dot/Dot.d.ts.map +1 -0
  35. package/dist/components/EmptyState/EmptyState.d.ts +18 -0
  36. package/dist/components/EmptyState/EmptyState.d.ts.map +1 -0
  37. package/dist/components/Footer/Footer.d.ts +31 -0
  38. package/dist/components/Footer/Footer.d.ts.map +1 -0
  39. package/dist/components/Form/Form.d.ts +17 -0
  40. package/dist/components/Form/Form.d.ts.map +1 -0
  41. package/dist/components/Image/Image.d.ts +18 -0
  42. package/dist/components/Image/Image.d.ts.map +1 -0
  43. package/dist/components/Input/Input.d.ts +11 -0
  44. package/dist/components/Input/Input.d.ts.map +1 -1
  45. package/dist/components/Kanban/KanbanBoard.d.ts +3 -1
  46. package/dist/components/Kanban/KanbanBoard.d.ts.map +1 -1
  47. package/dist/components/Kanban/KanbanCard.d.ts +6 -1
  48. package/dist/components/Kanban/KanbanCard.d.ts.map +1 -1
  49. package/dist/components/Link/Link.d.ts +16 -0
  50. package/dist/components/Link/Link.d.ts.map +1 -0
  51. package/dist/components/Menu/MenuItem.d.ts +10 -1
  52. package/dist/components/Menu/MenuItem.d.ts.map +1 -1
  53. package/dist/components/Menu/MenuSeparator.d.ts +5 -0
  54. package/dist/components/Menu/MenuSeparator.d.ts.map +1 -0
  55. package/dist/components/Menu/SubmenuTrigger.d.ts +5 -0
  56. package/dist/components/Menu/SubmenuTrigger.d.ts.map +1 -0
  57. package/dist/components/NavItem/NavItem.d.ts.map +1 -1
  58. package/dist/components/NumberField/NumberField.d.ts +37 -0
  59. package/dist/components/NumberField/NumberField.d.ts.map +1 -0
  60. package/dist/components/PageHeader/PageHeader.d.ts +12 -0
  61. package/dist/components/PageHeader/PageHeader.d.ts.map +1 -0
  62. package/dist/components/Pagination/Pagination.d.ts +14 -0
  63. package/dist/components/Pagination/Pagination.d.ts.map +1 -0
  64. package/dist/components/ProgressBar/ProgressBar.d.ts +14 -2
  65. package/dist/components/ProgressBar/ProgressBar.d.ts.map +1 -1
  66. package/dist/components/RadioGroup/Radio.d.ts +15 -0
  67. package/dist/components/RadioGroup/Radio.d.ts.map +1 -0
  68. package/dist/components/RadioGroup/RadioGroup.d.ts.map +1 -1
  69. package/dist/components/Rating/Rating.d.ts +18 -0
  70. package/dist/components/Rating/Rating.d.ts.map +1 -0
  71. package/dist/components/RouterProvider/RouterProvider.d.ts +15 -0
  72. package/dist/components/RouterProvider/RouterProvider.d.ts.map +1 -0
  73. package/dist/components/SectionHeader/SectionHeader.d.ts +12 -0
  74. package/dist/components/SectionHeader/SectionHeader.d.ts.map +1 -0
  75. package/dist/components/Select/Option.d.ts +3 -0
  76. package/dist/components/Select/Option.d.ts.map +1 -0
  77. package/dist/components/Stepper/Stepper.d.ts +17 -0
  78. package/dist/components/Stepper/Stepper.d.ts.map +1 -0
  79. package/dist/components/Switch/Switch.d.ts +5 -1
  80. package/dist/components/Switch/Switch.d.ts.map +1 -1
  81. package/dist/components/Table/Table.d.ts +30 -0
  82. package/dist/components/Table/Table.d.ts.map +1 -0
  83. package/dist/components/Table/TableBody.d.ts +10 -0
  84. package/dist/components/Table/TableBody.d.ts.map +1 -0
  85. package/dist/components/Table/TableCell.d.ts +11 -0
  86. package/dist/components/Table/TableCell.d.ts.map +1 -0
  87. package/dist/components/Table/TableColumn.d.ts +15 -0
  88. package/dist/components/Table/TableColumn.d.ts.map +1 -0
  89. package/dist/components/Table/TableHeader.d.ts +10 -0
  90. package/dist/components/Table/TableHeader.d.ts.map +1 -0
  91. package/dist/components/Table/TableRow.d.ts +10 -0
  92. package/dist/components/Table/TableRow.d.ts.map +1 -0
  93. package/dist/components/Table/TableSelectionCheckbox.d.ts +3 -0
  94. package/dist/components/Table/TableSelectionCheckbox.d.ts.map +1 -0
  95. package/dist/components/Tabs/Tab.d.ts +15 -0
  96. package/dist/components/Tabs/Tab.d.ts.map +1 -0
  97. package/dist/components/Tabs/TabList.d.ts +10 -0
  98. package/dist/components/Tabs/TabList.d.ts.map +1 -0
  99. package/dist/components/Tabs/TabPanel.d.ts +8 -0
  100. package/dist/components/Tabs/TabPanel.d.ts.map +1 -0
  101. package/dist/components/Tabs/Tabs.d.ts +15 -0
  102. package/dist/components/Tabs/Tabs.d.ts.map +1 -0
  103. package/dist/components/Textarea/Textarea.d.ts +17 -0
  104. package/dist/components/Textarea/Textarea.d.ts.map +1 -0
  105. package/dist/components/Toast/Toast.d.ts +15 -0
  106. package/dist/components/Toast/Toast.d.ts.map +1 -0
  107. package/dist/components/Toast/toastQueue.d.ts +40 -0
  108. package/dist/components/Toast/toastQueue.d.ts.map +1 -0
  109. package/dist/components/TopBar/TopBar.d.ts +18 -0
  110. package/dist/components/TopBar/TopBar.d.ts.map +1 -0
  111. package/dist/hooks/useChartTheme.d.ts +2 -0
  112. package/dist/hooks/useChartTheme.d.ts.map +1 -1
  113. package/dist/index.css +1 -1
  114. package/dist/index.d.ts +79 -5
  115. package/dist/index.d.ts.map +1 -1
  116. package/dist/index.js +2689 -1094
  117. package/dist/layouts/Box/Box.d.ts +2 -0
  118. package/dist/layouts/Box/Box.d.ts.map +1 -1
  119. package/dist/layouts/Cover/Cover.d.ts +7 -1
  120. package/dist/layouts/Cover/Cover.d.ts.map +1 -1
  121. package/dist/typography/Heading/Heading.d.ts +9 -0
  122. package/dist/typography/Heading/Heading.d.ts.map +1 -1
  123. package/dist/typography/Text/Text.d.ts +11 -0
  124. package/dist/typography/Text/Text.d.ts.map +1 -1
  125. package/package.json +11 -6
  126. package/styles.d.ts +3 -0
package/LICENSE CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2026 Joshua Briley
3
+ Copyright (c) 2026 Rudy Vincent
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
package/README.md CHANGED
@@ -1,21 +1,23 @@
1
1
  # Rudiment UI
2
2
 
3
+ > Rudiment is still in beta (not even beta, really) and should not be used in production. I'm happy to accept pull requests that help improve this tool.
4
+
3
5
  A complete, accessible React component library template built on [React Aria](https://react-spectrum.adobe.com/react-aria/), styled with [Tailwind CSS 4](https://tailwindcss.com/), and documented in [Storybook](https://storybook.js.org/).
4
6
 
5
7
  Clone it. Swap the tokens. Ship your design system.
6
8
 
7
9
  ## What's included
8
10
 
9
- | Category | Components |
10
- |----------|-----------|
11
- | **UI Components** | Button, Input, Checkbox, CheckboxGroup, Select, Dialog, Switch, RadioGroup, Tooltip, Alert, IconButton, Badge, Tag, Avatar, Card, Icon, NavItem, ProgressBar, StatCard, CircularProgress |
12
- | **Charts** | BarChart, LineChart, DonutChart |
13
- | **Kanban** | KanbanBoard, KanbanColumn, KanbanCard |
14
- | **Typography** | Heading, Text, Prose |
15
- | **Layout Primitives** | Box, Stack, Cluster, Grid, Sidebar, Center, Cover, Switcher |
16
- | **Page Examples** | App Shell, App Header, App Footer, Settings Page, Sign-In Form, Marketing Hero, Sidebar Layout, Article Page, Simple Form, Empty State |
11
+ | Category | Components |
12
+ | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
13
+ | **UI Components** | Button, Input, Checkbox, CheckboxGroup, Select, Dialog, Switch, RadioGroup, Tooltip, Alert, IconButton, Badge, Tag, Avatar, Card, Icon, NavItem, ProgressBar, StatCard, CircularProgress |
14
+ | **Charts** | BarChart, LineChart, DonutChart |
15
+ | **Kanban** | KanbanBoard, KanbanColumn, KanbanCard |
16
+ | **Typography** | Heading, Text, Prose |
17
+ | **Layout Primitives** | Box, Stack, Cluster, Grid, Sidebar, Center, Cover, Switcher |
18
+ | **Page Examples** | App Shell, App Header, App Footer, Settings Page, Sign-In Form, Marketing Hero, Sidebar Layout, Article Page, Simple Form, Empty State |
17
19
 
18
- Also included: a three-tier design token architecture, six built-in themes (Default, Teal, and Cyberpunk in light and dark variants), motion tokens, a data visualization palette, surface tokens, a Vitest test suite with accessibility checks, and interactive Storybook documentation.
20
+ Also included: a three-tier design token architecture, eight built-in themes (Default plus the Roomy, Soft, and Compressed modifier themes, each in light and dark variants), motion tokens, a data visualization palette, surface tokens, a Vitest test suite with accessibility checks, and interactive Storybook documentation.
19
21
 
20
22
  ## Quick start
21
23
 
@@ -51,7 +53,7 @@ Import the stylesheet once at your app's entry point:
51
53
  import 'rudiment-ui/styles'
52
54
  ```
53
55
 
54
- This ships the component styles plus all six themes. It does **not** include Tailwind — components are styled with plain BEM classes and CSS custom properties, and the bundle contains no bare-element selectors, so it will not reset or clobber your app's own styles.
56
+ This ships the component styles plus all eight themes. It does **not** include Tailwind — components are styled with plain BEM classes and CSS custom properties, and the bundle contains no bare-element selectors, so it will not reset or clobber your app's own styles.
55
57
 
56
58
  Every export is marked `"use client"`, so the package can be imported directly into a Next.js App Router Server Component without a re-export barrel.
57
59
 
@@ -66,25 +68,35 @@ Every export is marked `"use client"`, so the package can be imported directly i
66
68
  import 'rudiment-ui/styles'
67
69
  ```
68
70
 
69
- That single import is the whole setup. There is no provider to mount — `Dialog` portals itself, and `useChartTheme` reads tokens straight off `document.documentElement`.
71
+ That single import is the whole setup. There is no provider to mount — `RudiDialog` portals itself, and `useChartTheme` reads tokens straight off `document.documentElement`.
70
72
 
71
73
  ## Themes
72
74
 
73
- Six themes ship in the stylesheet. Set `data-theme` on a root element to switch:
75
+ Eight themes ship in the stylesheet. Set `data-theme` on a root element to switch:
74
76
 
75
- | Theme | Attribute |
76
- |-------|-----------|
77
- | Default (light) | *no attribute* |
78
- | Dark | `data-theme="dark"` |
79
- | Teal | `data-theme="teal"` |
80
- | Teal Dark | `data-theme="teal-dark"` |
81
- | Cyberpunk | `data-theme="cyberpunk"` |
82
- | Cyberpunk Dark | `data-theme="cyberpunk-dark"` |
77
+ | Theme | Attribute |
78
+ | --------------- | ------------------------------ |
79
+ | Default (light) | _no attribute_ |
80
+ | Dark | `data-theme="dark"` |
81
+ | Roomy | `data-theme="roomy"` |
82
+ | Roomy Dark | `data-theme="roomy-dark"` |
83
+ | Soft | `data-theme="soft"` |
84
+ | Soft Dark | `data-theme="soft-dark"` |
85
+ | Compressed | `data-theme="compressed"` |
86
+ | Compressed Dark | `data-theme="compressed-dark"` |
83
87
 
84
88
  The default theme lives on `:root`, so **omit the attribute for it** — there is no `data-theme="light"`. Remove the attribute to return to default.
85
89
 
86
90
  ```tsx
87
- type Theme = 'default' | 'dark' | 'teal' | 'teal-dark' | 'cyberpunk' | 'cyberpunk-dark'
91
+ type Theme =
92
+ | 'default'
93
+ | 'dark'
94
+ | 'roomy'
95
+ | 'roomy-dark'
96
+ | 'soft'
97
+ | 'soft-dark'
98
+ | 'compressed'
99
+ | 'compressed-dark'
88
100
 
89
101
  function applyTheme(theme: Theme) {
90
102
  if (theme === 'default') {
@@ -97,23 +109,20 @@ function applyTheme(theme: Theme) {
97
109
 
98
110
  Themes are scoped by attribute rather than element, so you can theme a subtree — a dark sidebar inside a light page — by putting `data-theme` on any wrapper.
99
111
 
100
- No `prefers-color-scheme` query ships with the package. If you want OS-driven dark mode, wire it up yourself:
112
+ For OS-driven dark mode, set `data-theme="auto"`: it applies the dark tokens when the system prefers dark and the default tokens otherwise, in pure CSS.
101
113
 
102
- ```tsx
103
- const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches
104
- applyTheme(prefersDark ? 'dark' : 'default')
105
- ```
106
-
107
- Charts follow theme changes automatically — `useChartTheme` watches `data-theme` on `<html>` with a `MutationObserver` and re-resolves its colors.
114
+ Charts follow theme changes automatically: `useChartTheme` re-resolves its colors when `data-theme` on `<html>` changes or the OS color scheme flips.
108
115
 
109
116
  ## Tokens
110
117
 
111
118
  Every visual value is a CSS custom property prefixed `--rudi-`, arranged in three tiers that resolve through `var()` chains. Overriding a tier cascades to everything below it.
112
119
 
113
120
  ```css
114
- --rudi-color-neutral-900: #171717; /* 1. primitive */
115
- --rudi-color-brand-primary: var(--rudi-color-neutral-900); /* 2. semantic */
116
- --rudi-component-button-primary-bg: var(--rudi-color-brand-primary); /* 3. component */
121
+ --rudi-color-neutral-900: #171717; /* 1. primitive */
122
+ --rudi-color-brand-primary: var(--rudi-color-neutral-900); /* 2. semantic */
123
+ --rudi-component-button-primary-bg: var(
124
+ --rudi-color-brand-primary
125
+ ); /* 3. component */
117
126
  ```
118
127
 
119
128
  Rebrand by overriding tier 2 in your own stylesheet, loaded after `rudiment-ui/styles`:
@@ -129,79 +138,87 @@ Rebrand by overriding tier 2 in your own stylesheet, loaded after `rudiment-ui/s
129
138
  **Scope overrides per theme.** `:root` and `[data-theme="dark"]` have equal specificity, and the theme blocks come later in the stylesheet — so a plain `:root` override loses inside a themed subtree. Repeat it under each theme you use:
130
139
 
131
140
  ```css
132
- :root { --rudi-color-brand-primary: #7c3aed; }
133
- [data-theme="dark"] { --rudi-color-brand-primary: #a78bfa; }
141
+ :root {
142
+ --rudi-color-brand-primary: #7c3aed;
143
+ }
144
+ [data-theme='dark'] {
145
+ --rudi-color-brand-primary: #a78bfa;
146
+ }
134
147
  ```
135
148
 
136
149
  The tokens worth reaching for most often:
137
150
 
138
- | Purpose | Tokens |
139
- |---------|--------|
140
- | **Brand** | `--rudi-color-brand-primary`, `-hover`, `-active` |
141
- | **Surfaces** | `--rudi-color-background-surface`, `-raised`, `-sunken`, `-overlay`, `--rudi-color-background-disabled`, `-inverted` |
142
- | **Text** | `--rudi-color-text-default`, `-subtle`, `-disabled`, `-on-brand`, `-on-inverted` |
143
- | **Borders** | `--rudi-color-border-default`, `-focus`, `-error` |
144
- | **Feedback** | `--rudi-color-feedback-{error,success,warning,info}` each with `-surface`, `-border`, `-text` |
145
- | **Charts** | `--rudi-color-dataviz-series-1` … `-8` |
146
- | **Spacing** | `--rudi-spacing-{0,1,2,3,4,6,8,12}` (`0.25rem` steps — note 5, 7, 9–11 don't exist) |
147
- | **Radius** | `--rudi-radius-{none,sm,md,lg,full}` |
148
- | **Type** | `--rudi-font-family-{sans,mono}`, `--rudi-font-size-{xs…4xl}`, `--rudi-font-weight-{regular,medium,semibold,bold}` |
149
- | **Motion** | `--rudi-motion-duration-{fast,base,slow}`, `--rudi-motion-easing-standard` |
150
- | **Layout** | `--rudi-layout-sidebar-width`, `--rudi-layout-grid-min-cell`, `--rudi-layout-center-max-width`, `--rudi-layout-switcher-threshold` |
151
+ | Purpose | Tokens |
152
+ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
153
+ | **Brand** | `--rudi-color-brand-primary`, `-hover`, `-active` |
154
+ | **Surfaces** | `--rudi-color-background-surface`, `-raised`, `-sunken`, `-overlay`, `--rudi-color-background-disabled`, `-inverted` |
155
+ | **Text** | `--rudi-color-text-default`, `-subtle`, `-disabled`, `-on-brand`, `-on-inverted` |
156
+ | **Borders** | `--rudi-color-border-default`, `-focus`, `-error` |
157
+ | **Feedback** | `--rudi-color-feedback-{error,success,warning,info}` each with `-surface`, `-border`, `-text` |
158
+ | **Charts** | `--rudi-color-dataviz-series-1` … `-8` |
159
+ | **Spacing** | `--rudi-spacing-{0,1,2,3,4,6,8,12}` (`0.25rem` steps — note 5, 7, 9–11 don't exist) |
160
+ | **Radius** | `--rudi-radius-{none,sm,md,lg,full}` |
161
+ | **Type** | `--rudi-font-family-{sans,mono}`, `--rudi-font-size-{xs…4xl}`, `--rudi-font-weight-{regular,medium,semibold,bold}` |
162
+ | **Motion** | `--rudi-motion-duration-{fast,base,slow}`, `--rudi-motion-easing-standard` |
163
+ | **Layout** | `--rudi-layout-sidebar-width`, `--rudi-layout-grid-min-cell`, `--rudi-layout-center-max-width`, `--rudi-layout-switcher-threshold` |
151
164
 
152
165
  Component-level tokens (`--rudi-component-*`) are available for surgical changes — `--rudi-component-button-primary-bg`, `--rudi-component-card-bg`, `--rudi-component-input-bg`, and so on — but prefer semantic overrides so the change carries across every component.
153
166
 
154
167
  ## Components
155
168
 
156
169
  ```tsx
157
- import { Button, Input, Stack } from 'rudiment-ui'
170
+ import { RudiButton, RudiInput, RudiStack } from 'rudiment-ui'
158
171
 
159
172
  function LoginForm() {
160
173
  return (
161
- <Stack space="1.5rem">
162
- <Input label="Email" type="email" />
163
- <Input label="Password" type="password" />
164
- <Button variant="primary">Sign in</Button>
165
- </Stack>
174
+ <RudiStack space="1.5rem">
175
+ <RudiInput label="Email" type="email" />
176
+ <RudiInput label="Password" type="password" />
177
+ <RudiButton variant="primary">Sign in</RudiButton>
178
+ </RudiStack>
166
179
  )
167
180
  }
168
181
  ```
169
182
 
170
183
  ### Conventions worth knowing up front
171
184
 
172
- - **`onPress`, not `onClick`.** `Button`, `IconButton`, `Tag`, and `NavItem` are built on React Aria and take `onPress`. React Aria handles pointer, touch, and keyboard activation in one event.
173
- - **`onChange` gives you a value, not an event.** `Input` calls `onChange(value: string)`, `Checkbox` calls `onChange(isSelected: boolean)`, `CheckboxGroup` calls `onChange(value: string[])`.
174
- - **Labels are required props, not children.** `Input`, `Select`, `RadioGroup`, `CheckboxGroup`, `ProgressBar`, and the charts all take `label` as a string — it wires up the accessible name for you.
185
+ - **`onPress`, not `onClick`.** `RudiButton`, `RudiIconButton`, `RudiTag`, and `RudiNavItem` are built on React Aria and take `onPress`. React Aria handles pointer, touch, and keyboard activation in one event.
186
+ - **`onChange` gives you a value, not an event.** `RudiInput` calls `onChange(value: string)`, `RudiCheckbox` calls `onChange(isSelected: boolean)`, `RudiCheckboxGroup` calls `onChange(value: string[])`.
187
+ - **Labels are required props, not children.** `RudiInput`, `RudiSelect`, `RudiRadioGroup`, `RudiCheckboxGroup`, `RudiProgressBar`, and the charts all take `label` as a string — it wires up the accessible name for you.
175
188
  - **Icons are Iconify names.** Any prop typed as an icon takes a `"collection:name"` string, e.g. `icon="mdi:close"`. No icon imports needed.
176
189
  - **`className` is merged, not replaced** — every component runs it through `clsx` + `tailwind-merge`. `cn` is exported if you want the same helper.
177
- - **Layout primitives are polymorphic and spread props**; components are not. `Stack`, `Box`, `Text` etc. accept `as` plus any DOM attribute. `Button`, `Card`, `Alert` have closed prop interfaces.
190
+ - **Layout primitives are polymorphic and spread props**; components are not. `RudiStack`, `RudiBox`, `RudiText` etc. accept `as` plus any DOM attribute. `RudiButton`, `RudiCard`, `RudiAlert` have closed prop interfaces.
178
191
 
179
192
  ### Component reference
180
193
 
181
194
  **Actions**
182
195
 
183
- | Component | Props |
184
- |-----------|-------|
185
- | `Button` | `variant?: 'primary' \| 'secondary' \| 'destructive' \| 'ghost'` (`'primary'`), `size?: 'sm' \| 'md' \| 'lg'` (`'md'`), `isLoading?`, `iconBefore?`, `iconAfter?`, `onPress?`, `isDisabled?` |
186
- | `IconButton` | `aria-label` **(required)**, `variant?` (`'secondary'`), `size?: 'sm' \| 'md' \| 'lg'` (`'md'`), `isLoading?`, `onPress?`; `children` is a single element |
187
- | `NavItem` | `label` **(required)**, `icon?`, `isActive?`, `href?` (renders `<a>`, else `<button>`), `onPress?`, `badge?`, `isDisabled?` |
196
+ | Component | Props |
197
+ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
198
+ | `RudiButton` | `variant?: 'primary' \| 'secondary' \| 'destructive' \| 'ghost'` (`'primary'`), `size?: 'sm' \| 'md' \| 'lg'` (`'md'`), `isLoading?`, `iconBefore?`, `iconAfter?`, `onPress?`, `isDisabled?` |
199
+ | `RudiIconButton` | `aria-label` **(required)**, `variant?` (`'secondary'`), `size?: 'sm' \| 'md' \| 'lg'` (`'md'`), `isLoading?`, `onPress?`; `children` is a single element |
200
+ | `RudiNavItem` | `label` **(required)**, `icon?`, `isActive?`, `href?` (renders `<a>`, else `<button>`), `onPress?`, `badge?`, `isDisabled?` |
188
201
 
189
202
  **Forms**
190
203
 
191
- | Component | Props |
192
- |-----------|-------|
193
- | `Input` | `label` **(required)**, `type?: 'text' \| 'email' \| 'password' \| 'url' \| 'tel' \| 'search' \| 'number'` (`'text'`), `placeholder?`, `description?`, `errorMessage?` (sets invalid state), `isRequired?`, `isDisabled?`, `value?`, `defaultValue?`, `onChange?: (value: string) => void` |
194
- | `Checkbox` | `children` (label), `isSelected?`, `defaultSelected?`, `isIndeterminate?`, `onChange?: (isSelected: boolean) => void`, `isDisabled?`, `value?` |
195
- | `CheckboxGroup` | `label` **(required)**, `description?`, `value?: string[]`, `defaultValue?`, `onChange?: (value: string[]) => void`, `errorMessage?`, `isDisabled?` |
196
- | `Switch` | `children` (label), `isSelected?`, `defaultSelected?`, `onChange?: (isSelected: boolean) => void`, `isDisabled?` |
197
- | `Select` | `label`, `items`, `children: (item) => ReactNode`, `selectedKey?`, `defaultSelectedKey?`, `onSelectionChange?: (key) => void`, `placeholder?`, `description?`, `errorMessage?`, `isRequired?`, `isDisabled?` |
198
- | `RadioGroup` | `label`, `orientation?: 'horizontal' \| 'vertical'`, `value?`, `defaultValue?`, `onChange?: (value: string) => void`, `errorMessage?`, `isDisabled?` |
199
-
200
- `Select` renders its options from an `items` collection plus a render function. The item element comes from `react-stately`:
204
+ | Component | Props |
205
+ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
206
+ | `RudiInput` | `label` **(required)**, `type?: 'text' \| 'email' \| 'password' \| 'url' \| 'tel' \| 'search' \| 'number'` (`'text'`), `placeholder?`, `description?`, `errorMessage?` (sets invalid state), `isRequired?`, `isDisabled?`, `value?`, `defaultValue?`, `onChange?: (value: string) => void`, `onBlur?`, `name?`, `autoComplete?`, `inputMode?`, `maxLength?`, `isReadOnly?`, `autoFocus?` |
207
+ | `RudiNumberField` | `label` **(required)**, `value?` / `defaultValue?: number \| null`, `onChange?: (value: number \| null) => void`, `minValue?`, `maxValue?`, `step?`, `formatOptions?: Intl.NumberFormatOptions`, `placeholder?`, `description?`, `errorMessage?`, `isRequired?`, `isDisabled?`, `isReadOnly?`, `name?`, `hideStepper?` |
208
+ | `RudiDatePicker` | `label` **(required)**, `value?` / `defaultValue?: string \| null`, `onChange?: (value: string \| null) => void`, `granularity?: 'day' \| 'minute'` (`'day'`), `minValue?`, `maxValue?`, `isDateUnavailable?: (date: string) => boolean`, `hourCycle?: 12 \| 24`, `description?`, `errorMessage?`, `isRequired?`, `isDisabled?`, `isReadOnly?`, `name?` |
209
+ | `RudiDateRangePicker` | `label` **(required)**, `value?` / `defaultValue?: { start: string; end: string } \| null`, `onChange?`, `minValue?`, `maxValue?`, `isDateUnavailable?`, `description?`, `errorMessage?`, `isRequired?`, `isDisabled?`, `isReadOnly?`, `startName?`, `endName?` |
210
+ | `RudiCheckbox` | `children` (label), `isSelected?`, `defaultSelected?`, `isIndeterminate?`, `onChange?: (isSelected: boolean) => void`, `isDisabled?`, `value?` |
211
+ | `RudiCheckboxGroup` | `label` **(required)**, `description?`, `value?: string[]`, `defaultValue?`, `onChange?: (value: string[]) => void`, `errorMessage?`, `isDisabled?` |
212
+ | `RudiSwitch` | `children` (label), `isSelected?`, `defaultSelected?`, `onChange?: (isSelected: boolean) => void`, `isDisabled?` |
213
+ | `RudiSelect` | `label`, `items`, `children: (item) => ReactNode`, `selectedKey?`, `defaultSelectedKey?`, `onSelectionChange?: (key) => void`, `placeholder?`, `description?`, `errorMessage?`, `isRequired?`, `isDisabled?` |
214
+ | `RudiComboBox` | `label`, `items`, `children: (item) => RudiOption`, `selectedKey?`, `defaultSelectedKey?`, `onSelectionChange?: (key) => void`, `inputValue?`, `onInputChange?`, `menuTrigger?`, `allowsCustomValue?`, `emptyMessage?`, `placeholder?`, `description?`, `errorMessage?`, `isRequired?`, `isDisabled?`, `name?` |
215
+ | `RudiRadio` | `value`, `children`, `isDisabled?` — must be rendered inside `RudiRadioGroup` |
216
+ | `RudiRadioGroup` | `label`, `orientation?: 'horizontal' \| 'vertical'`, `value?`, `defaultValue?`, `onChange?: (value: string) => void`, `errorMessage?`, `isDisabled?` |
217
+
218
+ `RudiSelect` renders its options from an `items` collection plus a render function that returns a `RudiOption` for each item:
201
219
 
202
220
  ```tsx
203
- import { Item } from 'react-stately'
204
- import { Select } from 'rudiment-ui'
221
+ import { RudiSelect, RudiOption } from 'rudiment-ui'
205
222
 
206
223
  const roles = [
207
224
  { id: 'viewer', label: 'Viewer' },
@@ -209,117 +226,163 @@ const roles = [
209
226
  { id: 'admin', label: 'Admin' },
210
227
  ]
211
228
 
212
- <Select label="Role" items={roles} placeholder="Choose a role" onSelectionChange={setRole}>
213
- {(item) => <Item key={item.id}>{item.label}</Item>}
214
- </Select>
229
+ <RudiSelect label="Role" items={roles} placeholder="Choose a role" onSelectionChange={setRole}>
230
+ {(item) => <RudiOption key={item.id}>{item.label}</RudiOption>}
231
+ </RudiSelect>
215
232
  ```
216
233
 
217
234
  **Feedback & display**
218
235
 
219
- | Component | Props |
220
- |-----------|-------|
221
- | `Alert` | `variant: 'info' \| 'success' \| 'warning' \| 'error'` **(required)**, `title?`, `icon?`, `isPolite?` (`role="status"` instead of `"alert"`), `dismissible?`, `onDismiss?` |
222
- | `Badge` | `variant?: 'default' \| 'success' \| 'warning' \| 'error' \| 'info'` (`'default'`), `size?: 'sm' \| 'md'` (`'md'`), `dot?` (hides children) |
223
- | `Tag` | `variant?` (as Badge), `dismissible?`, `onDismiss?`, `onPress?` (switches root to `<button>`), `isDisabled?` |
224
- | `Avatar` | `src?`, `alt?`, `name?` (derives initials), `size?: 'sm' \| 'md' \| 'lg'` (`'md'`), `status?: 'success' \| 'warning' \| 'error' \| 'info'` |
225
- | `Icon` | `icon` **(required)**, `size?: 'sm' \| 'md' \| 'lg' \| number` (`'md'`), `color?`, `label?` (sets `role="img"`; without it the icon is `aria-hidden`) |
226
- | `ProgressBar` | `value` + `label` **(required)**, `minValue?` (`0`), `maxValue?` (`100`), `showValueLabel?`, `variant?: 'default' \| 'success' \| 'warning' \| 'error'`, `size?: 'sm' \| 'md'` |
227
- | `CircularProgress` | same as ProgressBar plus `size?: 'sm' \| 'md' \| 'lg'` and `children?` for custom center content |
228
- | `StatCard` | `label`, `value: string \| number`, `delta?: string`, `trend?: 'up' \| 'down' \| 'neutral'` (`'neutral'`), `children?` |
236
+ | Component | Props |
237
+ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
238
+ | `RudiAlert` | `variant: 'info' \| 'success' \| 'warning' \| 'error'` **(required)**, `title?`, `icon?`, `isPolite?` (`role="status"` instead of `"alert"`), `dismissible?`, `onDismiss?` |
239
+ | `RudiBadge` | `variant?: 'default' \| 'success' \| 'warning' \| 'error' \| 'info'` (`'default'`), `size?: 'sm' \| 'md'` (`'md'`), `dot?` (hides children) |
240
+ | `RudiTag` | `variant?` (as Badge), `dismissible?`, `onDismiss?`, `onPress?` (switches root to `<button>`), `isDisabled?` |
241
+ | `RudiAvatar` | `src?`, `alt?`, `name?` (derives initials), `size?: 'sm' \| 'md' \| 'lg'` (`'md'`), `status?: 'success' \| 'warning' \| 'error' \| 'info'` |
242
+ | `RudiIcon` | `icon` **(required)**, `size?: 'sm' \| 'md' \| 'lg' \| number` (`'md'`), `color?`, `label?` (sets `role="img"`; without it the icon is `aria-hidden`) |
243
+ | `RudiProgressBar` | `value` + `label` **(required)**, `minValue?` (`0`), `maxValue?` (`100`), `showValueLabel?`, `variant?: 'default' \| 'success' \| 'warning' \| 'error'`, `size?: 'sm' \| 'md'` |
244
+ | `RudiCircularProgress` | same as ProgressBar plus `size?: 'sm' \| 'md' \| 'lg'` and `children?` for custom center content |
245
+ | `RudiStatCard` | `label`, `value: string \| number`, `delta?: string`, `trend?: 'up' \| 'down' \| 'neutral'` (`'neutral'`), `children?` |
229
246
 
230
- `Alert` and `Tag` handle dismissal with internal state — once dismissed they render `null` and can't be reopened via props. Control visibility yourself if you need it back.
247
+ `RudiAlert` and `RudiTag` handle dismissal with internal state — once dismissed they render `null` and can't be reopened via props. Control visibility yourself if you need it back.
231
248
 
232
249
  **Containers & overlays**
233
250
 
234
- | Component | Props |
235
- |-----------|-------|
236
- | `Card` | `variant?: 'default' \| 'outlined' \| 'elevated'` (`'default'`), `padding?: 'none' \| 'sm' \| 'md' \| 'lg'` (`'md'`) |
237
- | `Dialog` | `isOpen`, `onClose`, `title` **(all required)**, `isDismissable?` (`true`), `size?: 'sm' \| 'md' \| 'lg'` (`'md'`) |
238
- | `TooltipTrigger` / `Tooltip` | `delay?` (`500`ms), `closeDelay?` (`0`ms); children must be exactly `[trigger, tooltip]` |
239
- | `MenuTrigger` / `Menu` / `MenuItem` / `MenuSection` / `Keyboard` | React Aria menu primitives; `MenuItem` adds `isDestructive?` |
251
+ | Component | Props |
252
+ | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
253
+ | `RudiCard` | `variant?: 'default' \| 'outlined' \| 'elevated'` (`'default'`), `padding?: 'none' \| 'sm' \| 'md' \| 'lg'` (`'md'`) |
254
+ | `RudiDialog` | `isOpen`, `onClose`, `title` **(all required)**, `isDismissable?` (`true`, adds a close button), `size?: 'sm' \| 'md' \| 'lg'` (`'md'`); part `RudiDialog.Footer` for actions |
255
+ | `RudiTooltipTrigger` / `RudiTooltip` | `delay?` (`500`ms), `closeDelay?` (`0`ms); children must be exactly `[trigger, tooltip]` |
256
+ | `RudiMenuTrigger` / `RudiMenu` / `RudiMenuItem` / `RudiMenuSection` / `RudiKeyboard` | React Aria menu primitives; `RudiMenuItem` adds `isDestructive?` |
240
257
 
241
- `Card` is compound — use the dot subcomponents:
258
+ `RudiCard` is compound — use the dot subcomponents:
242
259
 
243
260
  ```tsx
244
- <Card variant="elevated" padding="lg">
245
- <Card.Header>Monthly revenue</Card.Header>
246
- <Card.Body>…</Card.Body>
247
- <Card.Footer>…</Card.Footer>
248
- </Card>
261
+ <RudiCard variant="elevated" padding="lg">
262
+ <RudiCard.Header>Monthly revenue</RudiCard.Header>
263
+ <RudiCard.Body>…</RudiCard.Body>
264
+ <RudiCard.Footer>…</RudiCard.Footer>
265
+ </RudiCard>
249
266
  ```
250
267
 
251
- `Dialog` is fully controlled — it has no internal open state:
268
+ `RudiDialog` is fully controlled — it has no internal open state:
252
269
 
253
270
  ```tsx
254
271
  const [isOpen, setIsOpen] = useState(false)
255
272
 
256
- <Button onPress={() => setIsOpen(true)}>Delete account</Button>
257
- <Dialog isOpen={isOpen} onClose={() => setIsOpen(false)} title="Are you sure?" size="sm">
258
- <Button variant="destructive" onPress={confirmDelete}>Delete</Button>
259
- </Dialog>
273
+ <RudiButton onPress={() => setIsOpen(true)}>Delete account</RudiButton>
274
+ <RudiDialog isOpen={isOpen} onClose={() => setIsOpen(false)} title="Are you sure?" size="sm">
275
+ <RudiButton variant="destructive" onPress={confirmDelete}>Delete</RudiButton>
276
+ </RudiDialog>
277
+ ```
278
+
279
+ `RudiTooltipTrigger` takes exactly two children, in order:
280
+
281
+ ```tsx
282
+ <RudiTooltipTrigger>
283
+ <RudiIconButton aria-label="Delete">
284
+ <RudiIcon icon="mdi:trash-can" />
285
+ </RudiIconButton>
286
+ <RudiTooltip>Delete this item</RudiTooltip>
287
+ </RudiTooltipTrigger>
288
+ ```
289
+
290
+ **App chrome**
291
+
292
+ | Component | Key props |
293
+ | ------------------- | --------- |
294
+ | `RudiForm` | `onSubmit?: (data: FormData, event) => void`, `errors?: string[]` (shows and focuses a summary), `errorTitle?` |
295
+ | `RudiAppShell` | `isSidebarOpen?`, `onSidebarOpenChange?`, `defaultSidebarOpen?`; parts `.Sidebar` (`width?`, `aria-label?`), `.Content`, `.Main` (`maxWidth?`, `padding?`), `.MenuButton` |
296
+ | `RudiTopBar` | `start?`, `end?`, `children` (center), `announcement?`, `sticky?` (`true`), `as?` (`'header'`) |
297
+ | `RudiPageHeader` | `title` **(required)**, `subtitle?`, `actions?`, `headingLevel?` (`1`) |
298
+ | `RudiBrand` | `name` **(required)**, `mark?`, `hideName?`, `href?`, `size?: 'sm' \| 'md' \| 'lg'` (`'md'`) |
299
+ | `RudiSectionHeader` | `title` **(required)**, `description?`, `action?`, `headingLevel?` (`2`) |
300
+ | `RudiTabs` | `selectedKey?`, `defaultSelectedKey?`, `onSelectionChange?`, `orientation?: 'horizontal' \| 'vertical'` (`'horizontal'`), `disabledKeys?`, `keyboardActivation?` |
301
+ | `RudiTabList` | `aria-label` **(required)**, `variant?: 'underline' \| 'pill'` (`'underline'`) |
302
+ | `RudiTab` | `id` **(required)**, `children` (label), `icon?`, `badge?`, `href?`, `isDisabled?` |
303
+ | `RudiTabPanel` | `id` **(required, matches its tab)**, `shouldForceMount?` |
304
+ | `RudiToastRegion` | `placement?: 'top-end' \| 'bottom-end' \| 'bottom-center'`, `aria-label?`; queue with `rudiToast.success(title, { description?, timeout?, onClose? })` (and `info`, `warning`, `error`), `.add({...})`, `.close(key)` |
305
+ | `RudiEmptyState` | `title` **(required)**, `icon?`, `description?`, `action?`, `headingLevel?: 2–6` (`3`), `size?: 'sm' \| 'md'` (`'md'`) |
306
+ | `RudiTable` (+ `Header`, `Column`, `Body`, `Row`, `Cell` parts) | `aria-label` **(required)**, `density?: 'compact' \| 'regular'`, `striped?`, `stickyHeader?`, `maxHeight?`, `sortDescriptor?`, `onSortChange?`, `onRowAction?`, `selectionMode?`; columns take `align?`, `allowsSorting?`, `isRowHeader?`, `width?`, `minWidth?`; rows take `href?`; body takes `renderEmptyState?` |
307
+
308
+ ```tsx
309
+ <RudiAppShell>
310
+ <RudiAppShell.Sidebar aria-label="Main navigation">
311
+ <RudiNavItem label="Shipments" icon="lucide:package" href="/shipments" isActive />
312
+ </RudiAppShell.Sidebar>
313
+ <RudiAppShell.Content>
314
+ <RudiTopBar start={<RudiAppShell.MenuButton />} end={<RudiAvatar name="Ada Admin" />} />
315
+ <RudiAppShell.Main>
316
+ <RudiPageHeader title="Shipments" actions={<RudiButton>New shipment</RudiButton>} />
317
+ </RudiAppShell.Main>
318
+ </RudiAppShell.Content>
319
+ </RudiAppShell>
260
320
  ```
261
321
 
262
- `TooltipTrigger` takes exactly two children, in order:
322
+ **Routing.** In a single-page app, wrap the tree in `RudiRouterProvider` so Rudi links navigate client-side:
263
323
 
264
324
  ```tsx
265
- <TooltipTrigger>
266
- <IconButton aria-label="Delete"><Icon icon="mdi:trash-can" /></IconButton>
267
- <Tooltip>Delete this item</Tooltip>
268
- </TooltipTrigger>
325
+ import { useHref, useNavigate } from 'react-router'
326
+ import { RudiRouterProvider } from 'rudiment-ui'
327
+
328
+ function Providers({ children }) {
329
+ const navigate = useNavigate()
330
+ return <RudiRouterProvider navigate={navigate} useHref={useHref}>{children}</RudiRouterProvider>
331
+ }
269
332
  ```
270
333
 
271
334
  ## Layout primitives
272
335
 
273
- Eight primitives handle spacing and composition. **Every spacing prop takes a raw CSS length string** — `"1rem"`, `"2rem"`, or `var(--rudi-spacing-6)` — not a numeric scale. The prop is `space` everywhere (never `gap`); `Box` uses `padding`. All accept `as`, `className`, and any DOM attribute.
336
+ Eight primitives handle spacing and composition. **Every spacing prop takes a raw CSS length string** — `"1rem"`, `"2rem"`, or `var(--rudi-spacing-6)` — not a numeric scale. The prop is `space` everywhere (never `gap`); `RudiBox` uses `padding`. All accept `as`, `className`, and any DOM attribute.
274
337
 
275
- | Component | Props | Default |
276
- |-----------|-------|---------|
277
- | `Box` | `padding?`, `bordered?`, `invert?` | padding `1rem` |
278
- | `Stack` | `space?`, `recursive?`, `splitAfter?: number` | space `1.5rem` |
279
- | `Cluster` | `space?`, `justify?: 'flex-start' \| 'flex-end' \| 'center' \| 'space-between' \| 'space-around'`, `align?: 'flex-start' \| 'flex-end' \| 'center' \| 'baseline' \| 'stretch'` | space `1rem`, justify `flex-start`, align `center` |
280
- | `Grid` | `minCellWidth?`, `space?` | min cell `15rem`, space `1.5rem` |
281
- | `Sidebar` | `side?: 'left' \| 'right'`, `sideWidth?`, `contentMin?`, `space?`, `noStretch?` | side `left`, width `20rem`, content min `50%` |
282
- | `Center` | `maxWidth?`, `gutters?`, `intrinsic?` | max width `60rem`, gutters `1rem` |
283
- | `Cover` | `minHeight?`, `space?` | min height `100vh` |
284
- | `Switcher` | `threshold?`, `space?` | threshold `30rem`, space `1.5rem` |
338
+ | Component | Props | Default |
339
+ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- |
340
+ | `RudiBox` | `padding?`, `bordered?`, `invert?` | padding `1rem` |
341
+ | `RudiStack` | `space?`, `recursive?`, `splitAfter?: number` | space `1.5rem` |
342
+ | `RudiCluster` | `space?`, `justify?: 'flex-start' \| 'flex-end' \| 'center' \| 'space-between' \| 'space-around'`, `align?: 'flex-start' \| 'flex-end' \| 'center' \| 'baseline' \| 'stretch'` | space `1rem`, justify `flex-start`, align `center` |
343
+ | `RudiGrid` | `minCellWidth?`, `space?` | min cell `15rem`, space `1.5rem` |
344
+ | `RudiSidebar` | `side?: 'left' \| 'right'`, `sideWidth?`, `contentMin?`, `space?`, `noStretch?` | side `left`, width `20rem`, content min `50%` |
345
+ | `RudiCenter` | `maxWidth?`, `gutters?`, `intrinsic?` | max width `60rem`, gutters `1rem` |
346
+ | `RudiCover` | `minHeight?`, `space?` | min height `100vh` |
347
+ | `RudiSwitcher` | `threshold?`, `space?` | threshold `30rem`, space `1.5rem` |
285
348
 
286
349
  ```tsx
287
- <Sidebar side="left" sideWidth="16rem" space="2rem">
350
+ <RudiSidebar side="left" sideWidth="16rem" space="2rem">
288
351
  <nav>…</nav>
289
- <Stack space="1.5rem">
290
- <Heading level={1}>Dashboard</Heading>
291
- <Grid minCellWidth="18rem" space="1rem">
292
- <StatCard label="Revenue" value="$48.2k" delta="+12.5%" trend="up" />
293
- <StatCard label="Users" value="1,284" delta="+3.1%" trend="up" />
294
- </Grid>
295
- </Stack>
296
- </Sidebar>
352
+ <RudiStack space="1.5rem">
353
+ <RudiHeading level={1}>Dashboard</RudiHeading>
354
+ <RudiGrid minCellWidth="18rem" space="1rem">
355
+ <RudiStatCard label="Revenue" value="$48.2k" delta="+12.5%" trend="up" />
356
+ <RudiStatCard label="Users" value="1,284" delta="+3.1%" trend="up" />
357
+ </RudiGrid>
358
+ </RudiStack>
359
+ </RudiSidebar>
297
360
  ```
298
361
 
299
- `Stack` deserves a note: `recursive` applies the spacing to all nested descendants rather than direct children, and `splitAfter={n}` pushes everything after the nth child to the bottom — useful for pinning a footer inside a sidebar.
362
+ `RudiStack` deserves a note: `recursive` applies the spacing to all nested descendants rather than direct children, and `splitAfter={n}` pushes everything after the nth child to the bottom — useful for pinning a footer inside a sidebar.
300
363
 
301
364
  ## Typography
302
365
 
303
- | Component | Props |
304
- |-----------|-------|
305
- | `Heading` | `level: 1–6` **(required, sets the tag)**, `size?: 1–6` (visual size, defaults to `level`) |
306
- | `Text` | `variant?: 'body' \| 'body-sm' \| 'caption' \| 'overline' \| 'code'` (`'body'`), `as?` (`'p'`) |
307
- | `Prose` | `size?: 'sm' \| 'base' \| 'lg'` (`'base'`), `as?` (`'div'`) |
366
+ | Component | Props |
367
+ | --------- | ---------------------------------------------------------------------------------------------- |
368
+ | `RudiHeading` | `level: 1–6` **(required, sets the tag)**, `size?: 1–6` (visual size, defaults to `level`) |
369
+ | `RudiText` | `variant?: 'body' \| 'body-sm' \| 'caption' \| 'overline' \| 'code'` (`'body'`), `as?` (`'p'`) |
370
+ | `RudiProse` | `size?: 'sm' \| 'base' \| 'lg'` (`'base'`), `as?` (`'div'`) |
308
371
 
309
- `level` and `size` are separate so you can keep a correct document outline while styling freely — `<Heading level={2} size={4}>` renders an `<h2>` that looks like an h4. `Prose` styles a block of unstyled HTML (CMS content, rendered Markdown).
372
+ `level` and `size` are separate so you can keep a correct document outline while styling freely — `<Heading level={2} size={4}>` renders an `<h2>` that looks like an h4. `RudiProse` styles a block of unstyled HTML (CMS content, rendered Markdown).
310
373
 
311
374
  ## Charts
312
375
 
313
376
  All three wrap Recharts, size themselves to their container, and require a `label` for the accessible name. Series colors come from the dataviz tokens and follow the active theme automatically.
314
377
 
315
- | Component | Props |
316
- |-----------|-------|
317
- | `BarChart` | `data`, `dataKeys: string[]`, `indexKey`, `label`, `layout?: 'vertical' \| 'horizontal'` (`'vertical'`), `stacked?`, `showLegend?` (`true`), `showGrid?` (`true`), `height?` (`300`) |
318
- | `LineChart` | `data`, `dataKeys`, `indexKey`, `label`, `curved?` (`true`), `showDots?` (`true`), `showGrid?`, `showLegend?`, `height?` |
319
- | `DonutChart` | `data: { name, value }[]`, `label`, `innerRadius?` (`60`), `showLabels?` (`false`), `showLegend?`, `height?` |
378
+ | Component | Props |
379
+ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
380
+ | `RudiBarChart` | `data`, `dataKeys: string[]`, `indexKey`, `label`, `layout?: 'vertical' \| 'horizontal'` (`'vertical'`), `stacked?`, `showLegend?` (`true`), `showGrid?` (`true`), `height?` (`300`) |
381
+ | `RudiLineChart` | `data`, `dataKeys`, `indexKey`, `label`, `curved?` (`true`), `showDots?` (`true`), `showGrid?`, `showLegend?`, `height?` |
382
+ | `RudiDonutChart` | `data: { name, value }[]`, `label`, `innerRadius?` (`60`), `showLabels?` (`false`), `showLegend?`, `height?` |
320
383
 
321
384
  ```tsx
322
- <BarChart
385
+ <RudiBarChart
323
386
  label="Revenue by month"
324
387
  data={[
325
388
  { month: 'Jan', revenue: 4200, costs: 2400 },
@@ -331,19 +394,18 @@ All three wrap Recharts, size themselves to their container, and require a `labe
331
394
  />
332
395
  ```
333
396
 
334
- Note that `BarChart`'s `layout` describes the bars, not the Recharts axis: the default `"vertical"` gives you vertical bars, and `"horizontal"` gives horizontal ones.
397
+ Note that `RudiBarChart`'s `layout` describes the bars, not the Recharts axis: the default `"vertical"` gives you vertical bars, and `"horizontal"` gives horizontal ones.
335
398
 
336
399
  ## Kanban
337
400
 
338
- `KanbanBoard` is fully controlled — it never mutates `columns`. Apply the move yourself in `onCardMove`:
401
+ `RudiKanbanBoard` is fully controlled — it never mutates `columns`. Apply the move yourself in `onCardMove`:
339
402
 
340
403
  ```tsx
341
- import { KanbanBoard, KanbanCard, type KanbanCardMoveEvent } from 'rudiment-ui'
342
-
343
- <KanbanBoard
344
- columns={columns} // { id, title, items: { id, ... }[] }[]
345
- renderCard={(item) => <KanbanCard id={item.id}>{item.title}</KanbanCard>}
346
- onCardMove={(e: KanbanCardMoveEvent) => {
404
+ import { RudiKanbanBoard, RudiKanbanCard, type RudiKanbanCardMoveEvent } from 'rudiment-ui'
405
+ ;<RudiKanbanBoard
406
+ columns={columns} // { id, title, items: { id, ... }[] }[]
407
+ renderCard={(item) => <RudiKanbanCard id={item.id}>{item.title}</RudiKanbanCard>}
408
+ onCardMove={(e: RudiKanbanCardMoveEvent) => {
347
409
  // e: { cardId, fromColumnId, toColumnId, fromIndex, toIndex }
348
410
  setColumns((prev) => applyMove(prev, e))
349
411
  }}
@@ -356,7 +418,7 @@ import { KanbanBoard, KanbanCard, type KanbanCardMoveEvent } from 'rudiment-ui'
356
418
 
357
419
  **`useChartTheme()`** returns the resolved chart palette for the active theme — `{ colors, axisColor, gridColor, labelColor, legendColor, tooltipBg, tooltipText, tooltipBorder, chartBg }`. Use it to style custom Recharts compositions so they match the built-in charts. It's SSR-safe and re-resolves on theme change.
358
420
 
359
- **`useLoadingButton(ariaProps, isLoading, ref)`** returns `{ buttonProps }` with disabled and `aria-busy` handled. Useful if you're building a custom button rather than using `Button`.
421
+ **`useLoadingButton(ariaProps, isLoading, ref)`** returns `{ buttonProps }` with disabled and `aria-busy` handled. Useful if you're building a custom button rather than using `RudiButton`.
360
422
 
361
423
  ## Customizing the tokens at source
362
424
 
@@ -370,15 +432,15 @@ If you cloned the template rather than installing the package:
370
432
 
371
433
  ## Available scripts
372
434
 
373
- | Command | Description |
374
- |---------|------------|
375
- | `npm run dev` | Start Storybook dev server on port 6006 |
376
- | `npm run build` | Build the component library for distribution |
377
- | `npm run build-storybook` | Build a static Storybook site |
378
- | `npm run build:tokens` | Generate CSS from design token JSON files |
379
- | `npm run test` | Run the test suite |
380
- | `npm run test:coverage` | Run tests with coverage report |
381
- | `npm run test:watch` | Run tests in watch mode |
435
+ | Command | Description |
436
+ | ------------------------- | -------------------------------------------- |
437
+ | `npm run dev` | Start Storybook dev server on port 6006 |
438
+ | `npm run build` | Build the component library for distribution |
439
+ | `npm run build-storybook` | Build a static Storybook site |
440
+ | `npm run build:tokens` | Generate CSS from design token JSON files |
441
+ | `npm run test` | Run the test suite |
442
+ | `npm run test:coverage` | Run tests with coverage report |
443
+ | `npm run test:watch` | Run tests in watch mode |
382
444
 
383
445
  ## Project structure
384
446