rudiment-ui 0.4.0 → 0.6.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 (186) hide show
  1. package/README.md +59 -21
  2. package/dist/components/Alert/Alert.d.ts +28 -1
  3. package/dist/components/Alert/Alert.d.ts.map +1 -1
  4. package/dist/components/AppShell/AppShell.d.ts +52 -6
  5. package/dist/components/AppShell/AppShell.d.ts.map +1 -1
  6. package/dist/components/Avatar/Avatar.d.ts +21 -1
  7. package/dist/components/Avatar/Avatar.d.ts.map +1 -1
  8. package/dist/components/Badge/Badge.d.ts +23 -0
  9. package/dist/components/Badge/Badge.d.ts.map +1 -1
  10. package/dist/components/Brand/Brand.d.ts +17 -2
  11. package/dist/components/Brand/Brand.d.ts.map +1 -1
  12. package/dist/components/Breadcrumb/Breadcrumb.d.ts +24 -2
  13. package/dist/components/Breadcrumb/Breadcrumb.d.ts.map +1 -1
  14. package/dist/components/Button/Button.d.ts +31 -0
  15. package/dist/components/Button/Button.d.ts.map +1 -1
  16. package/dist/components/Card/Card.d.ts +34 -0
  17. package/dist/components/Card/Card.d.ts.map +1 -1
  18. package/dist/components/Charts/BarChart/BarChart.d.ts +39 -4
  19. package/dist/components/Charts/BarChart/BarChart.d.ts.map +1 -1
  20. package/dist/components/Charts/DonutChart/DonutChart.d.ts +31 -0
  21. package/dist/components/Charts/DonutChart/DonutChart.d.ts.map +1 -1
  22. package/dist/components/Charts/LineChart/LineChart.d.ts +52 -6
  23. package/dist/components/Charts/LineChart/LineChart.d.ts.map +1 -1
  24. package/dist/components/Charts/Sparkline/Sparkline.d.ts +35 -0
  25. package/dist/components/Charts/Sparkline/Sparkline.d.ts.map +1 -0
  26. package/dist/components/Checkbox/Checkbox.d.ts +26 -3
  27. package/dist/components/Checkbox/Checkbox.d.ts.map +1 -1
  28. package/dist/components/Checkbox/CheckboxGroup.d.ts +20 -0
  29. package/dist/components/Checkbox/CheckboxGroup.d.ts.map +1 -1
  30. package/dist/components/CircularProgress/CircularProgress.d.ts +33 -0
  31. package/dist/components/CircularProgress/CircularProgress.d.ts.map +1 -1
  32. package/dist/components/ComboBox/ComboBox.d.ts +29 -4
  33. package/dist/components/ComboBox/ComboBox.d.ts.map +1 -1
  34. package/dist/components/DatePicker/DatePicker.d.ts +30 -2
  35. package/dist/components/DatePicker/DatePicker.d.ts.map +1 -1
  36. package/dist/components/DatePicker/DateRangePicker.d.ts +26 -1
  37. package/dist/components/DatePicker/DateRangePicker.d.ts.map +1 -1
  38. package/dist/components/DatePicker/dateUtils.d.ts +1 -0
  39. package/dist/components/DatePicker/dateUtils.d.ts.map +1 -1
  40. package/dist/components/DescriptionList/DescriptionList.d.ts +44 -0
  41. package/dist/components/DescriptionList/DescriptionList.d.ts.map +1 -0
  42. package/dist/components/Dialog/Dialog.d.ts +39 -0
  43. package/dist/components/Dialog/Dialog.d.ts.map +1 -1
  44. package/dist/components/Divider/Divider.d.ts +18 -5
  45. package/dist/components/Divider/Divider.d.ts.map +1 -1
  46. package/dist/components/Dot/Dot.d.ts +22 -8
  47. package/dist/components/Dot/Dot.d.ts.map +1 -1
  48. package/dist/components/EmptyState/EmptyState.d.ts +23 -2
  49. package/dist/components/EmptyState/EmptyState.d.ts.map +1 -1
  50. package/dist/components/Form/Form.d.ts +20 -1
  51. package/dist/components/Form/Form.d.ts.map +1 -1
  52. package/dist/components/Icon/Icon.d.ts +17 -0
  53. package/dist/components/Icon/Icon.d.ts.map +1 -1
  54. package/dist/components/IconButton/IconButton.d.ts +24 -0
  55. package/dist/components/IconButton/IconButton.d.ts.map +1 -1
  56. package/dist/components/Image/Image.d.ts +31 -6
  57. package/dist/components/Image/Image.d.ts.map +1 -1
  58. package/dist/components/Input/Input.d.ts +32 -0
  59. package/dist/components/Input/Input.d.ts.map +1 -1
  60. package/dist/components/Kanban/KanbanBoard.d.ts +32 -0
  61. package/dist/components/Kanban/KanbanBoard.d.ts.map +1 -1
  62. package/dist/components/Kanban/KanbanCard.d.ts +12 -1
  63. package/dist/components/Kanban/KanbanCard.d.ts.map +1 -1
  64. package/dist/components/Kanban/KanbanColumn.d.ts +13 -0
  65. package/dist/components/Kanban/KanbanColumn.d.ts.map +1 -1
  66. package/dist/components/Kanban/KanbanOverlayContext.d.ts +7 -0
  67. package/dist/components/Kanban/KanbanOverlayContext.d.ts.map +1 -0
  68. package/dist/components/Kanban/kanbanMoves.d.ts +18 -0
  69. package/dist/components/Kanban/kanbanMoves.d.ts.map +1 -0
  70. package/dist/components/Link/Link.d.ts +24 -3
  71. package/dist/components/Link/Link.d.ts.map +1 -1
  72. package/dist/components/Menu/Keyboard.d.ts +9 -0
  73. package/dist/components/Menu/Keyboard.d.ts.map +1 -1
  74. package/dist/components/Menu/Menu.d.ts +13 -0
  75. package/dist/components/Menu/Menu.d.ts.map +1 -1
  76. package/dist/components/Menu/MenuItem.d.ts +11 -0
  77. package/dist/components/Menu/MenuItem.d.ts.map +1 -1
  78. package/dist/components/Menu/MenuSection.d.ts +12 -0
  79. package/dist/components/Menu/MenuSection.d.ts.map +1 -1
  80. package/dist/components/Menu/MenuSeparator.d.ts +8 -0
  81. package/dist/components/Menu/MenuSeparator.d.ts.map +1 -1
  82. package/dist/components/Menu/MenuTrigger.d.ts +16 -0
  83. package/dist/components/Menu/MenuTrigger.d.ts.map +1 -1
  84. package/dist/components/Menu/SubmenuTrigger.d.ts +13 -0
  85. package/dist/components/Menu/SubmenuTrigger.d.ts.map +1 -1
  86. package/dist/components/NavItem/NavItem.d.ts +14 -0
  87. package/dist/components/NavItem/NavItem.d.ts.map +1 -1
  88. package/dist/components/NumberField/NumberField.d.ts +36 -3
  89. package/dist/components/NumberField/NumberField.d.ts.map +1 -1
  90. package/dist/components/PageHeader/PageHeader.d.ts +18 -1
  91. package/dist/components/PageHeader/PageHeader.d.ts.map +1 -1
  92. package/dist/components/Pagination/Pagination.d.ts +19 -2
  93. package/dist/components/Pagination/Pagination.d.ts.map +1 -1
  94. package/dist/components/ProgressBar/ProgressBar.d.ts +36 -2
  95. package/dist/components/ProgressBar/ProgressBar.d.ts.map +1 -1
  96. package/dist/components/RadioGroup/Radio.d.ts +6 -1
  97. package/dist/components/RadioGroup/Radio.d.ts.map +1 -1
  98. package/dist/components/RadioGroup/RadioGroup.d.ts +24 -0
  99. package/dist/components/RadioGroup/RadioGroup.d.ts.map +1 -1
  100. package/dist/components/Rating/Rating.d.ts +26 -6
  101. package/dist/components/Rating/Rating.d.ts.map +1 -1
  102. package/dist/components/RouterProvider/RouterProvider.d.ts +1 -0
  103. package/dist/components/RouterProvider/RouterProvider.d.ts.map +1 -1
  104. package/dist/components/SectionHeader/SectionHeader.d.ts +14 -1
  105. package/dist/components/SectionHeader/SectionHeader.d.ts.map +1 -1
  106. package/dist/components/Select/Option.d.ts +8 -0
  107. package/dist/components/Select/Option.d.ts.map +1 -1
  108. package/dist/components/Select/Select.d.ts +29 -0
  109. package/dist/components/Select/Select.d.ts.map +1 -1
  110. package/dist/components/StatCard/StatCard.d.ts +23 -1
  111. package/dist/components/StatCard/StatCard.d.ts.map +1 -1
  112. package/dist/components/Stepper/Stepper.d.ts +34 -2
  113. package/dist/components/Stepper/Stepper.d.ts.map +1 -1
  114. package/dist/components/Switch/Switch.d.ts +13 -0
  115. package/dist/components/Switch/Switch.d.ts.map +1 -1
  116. package/dist/components/Table/Table.d.ts +31 -3
  117. package/dist/components/Table/Table.d.ts.map +1 -1
  118. package/dist/components/Table/TableBody.d.ts +7 -0
  119. package/dist/components/Table/TableBody.d.ts.map +1 -1
  120. package/dist/components/Table/TableCell.d.ts +11 -0
  121. package/dist/components/Table/TableCell.d.ts.map +1 -1
  122. package/dist/components/Table/TableColumn.d.ts +16 -1
  123. package/dist/components/Table/TableColumn.d.ts.map +1 -1
  124. package/dist/components/Table/TableHeader.d.ts +8 -1
  125. package/dist/components/Table/TableHeader.d.ts.map +1 -1
  126. package/dist/components/Table/TableRow.d.ts +10 -1
  127. package/dist/components/Table/TableRow.d.ts.map +1 -1
  128. package/dist/components/Tabs/Tab.d.ts +8 -0
  129. package/dist/components/Tabs/Tab.d.ts.map +1 -1
  130. package/dist/components/Tabs/TabList.d.ts +15 -1
  131. package/dist/components/Tabs/TabList.d.ts.map +1 -1
  132. package/dist/components/Tabs/TabPanel.d.ts +9 -0
  133. package/dist/components/Tabs/TabPanel.d.ts.map +1 -1
  134. package/dist/components/Tabs/Tabs.d.ts +11 -1
  135. package/dist/components/Tabs/Tabs.d.ts.map +1 -1
  136. package/dist/components/Tag/Tag.d.ts +27 -0
  137. package/dist/components/Tag/Tag.d.ts.map +1 -1
  138. package/dist/components/Textarea/Textarea.d.ts +43 -0
  139. package/dist/components/Textarea/Textarea.d.ts.map +1 -1
  140. package/dist/components/Toast/Toast.d.ts +17 -3
  141. package/dist/components/Toast/Toast.d.ts.map +1 -1
  142. package/dist/components/Toast/toastQueue.d.ts +20 -1
  143. package/dist/components/Toast/toastQueue.d.ts.map +1 -1
  144. package/dist/components/Tooltip/Tooltip.d.ts +32 -0
  145. package/dist/components/Tooltip/Tooltip.d.ts.map +1 -1
  146. package/dist/components/TopBar/TopBar.d.ts +17 -2
  147. package/dist/components/TopBar/TopBar.d.ts.map +1 -1
  148. package/dist/components.json +7919 -0
  149. package/dist/hooks/useChartTheme.d.ts +10 -0
  150. package/dist/hooks/useChartTheme.d.ts.map +1 -1
  151. package/dist/hooks/useLoadingButton.d.ts +10 -0
  152. package/dist/hooks/useLoadingButton.d.ts.map +1 -1
  153. package/dist/index.css +1 -1
  154. package/dist/index.d.ts +11 -0
  155. package/dist/index.d.ts.map +1 -1
  156. package/dist/index.js +1858 -1621
  157. package/dist/layouts/Box/Box.d.ts +31 -1
  158. package/dist/layouts/Box/Box.d.ts.map +1 -1
  159. package/dist/layouts/Center/Center.d.ts +22 -0
  160. package/dist/layouts/Center/Center.d.ts.map +1 -1
  161. package/dist/layouts/Cluster/Cluster.d.ts +19 -0
  162. package/dist/layouts/Cluster/Cluster.d.ts.map +1 -1
  163. package/dist/layouts/Cover/Cover.d.ts +28 -0
  164. package/dist/layouts/Cover/Cover.d.ts.map +1 -1
  165. package/dist/layouts/Grid/Grid.d.ts +18 -0
  166. package/dist/layouts/Grid/Grid.d.ts.map +1 -1
  167. package/dist/layouts/Sidebar/Sidebar.d.ts +29 -0
  168. package/dist/layouts/Sidebar/Sidebar.d.ts.map +1 -1
  169. package/dist/layouts/Stack/Stack.d.ts +21 -2
  170. package/dist/layouts/Stack/Stack.d.ts.map +1 -1
  171. package/dist/layouts/Switcher/Switcher.d.ts +19 -0
  172. package/dist/layouts/Switcher/Switcher.d.ts.map +1 -1
  173. package/dist/llms-full.txt +2284 -0
  174. package/dist/llms.txt +162 -0
  175. package/dist/typography/Heading/Heading.d.ts +12 -0
  176. package/dist/typography/Heading/Heading.d.ts.map +1 -1
  177. package/dist/typography/Prose/Prose.d.ts +21 -0
  178. package/dist/typography/Prose/Prose.d.ts.map +1 -1
  179. package/dist/typography/Text/Text.d.ts +28 -1
  180. package/dist/typography/Text/Text.d.ts.map +1 -1
  181. package/dist/utils/cn.d.ts +7 -0
  182. package/dist/utils/cn.d.ts.map +1 -1
  183. package/mcp/README.md +111 -0
  184. package/mcp/render.mjs +116 -0
  185. package/mcp/server.mjs +321 -0
  186. package/package.json +12 -2
package/dist/llms.txt ADDED
@@ -0,0 +1,162 @@
1
+ # rudiment-ui 0.6.0
2
+
3
+ > Accessible React 19 component library built on React Aria. Styled with BEM classes and `--rudi-*` CSS custom properties (design tokens). It does not use Tailwind classes. Eight themes are switched with `data-theme`.
4
+
5
+ This file is generated from the package's TypeScript source and JSDoc (`scripts/component-docs.mjs`), so it matches the installed version. `llms.txt` holds the conventions and an index. `llms-full.txt` adds every component's props, defaults taken from the implementation, compound parts and examples. `components.json` holds the same data as JSON and adds types and descriptions for the props inherited from React Aria. The `.d.ts` files carry the same JSDoc for editor hovers.
6
+
7
+ ## Setup
8
+
9
+ ```tsx
10
+ // Once, at the app entry (main.tsx, app/layout.tsx, …)
11
+ import 'rudiment-ui/styles'
12
+
13
+ import { RudiButton, RudiInput, RudiStack } from 'rudiment-ui'
14
+ ```
15
+
16
+ - No provider is required. `RudiDialog` portals itself. Mount `RudiToastRegion` once if you use `rudiToast`. Wrap the app in `RudiRouterProvider` for client-side routing with links.
17
+ - Every export is marked `'use client'`, so you can import it directly from a Next.js App Router Server Component.
18
+ - The stylesheet has no CSS reset and no bare-element selectors, so it won't change your app's own styles.
19
+
20
+ ## Conventions (read before writing code)
21
+
22
+ - **Every export is prefixed `Rudi`**: `RudiButton`, `RudiButtonProps`. The only exceptions are `rudiToast`, `cn`, `useChartTheme` and `useLoadingButton`.
23
+ - **`onPress`, not `onClick`.** Interactive components use React Aria press events, which cover mouse, touch and keyboard.
24
+ - **`onChange` receives a value, not an event**: `RudiInput` passes a `string`, `RudiCheckbox` a `boolean`, `RudiCheckboxGroup` a `string[]`, `RudiNumberField` a `number | null`, and `RudiDatePicker` an ISO `string | null`.
25
+ - **State props use React Aria names**: `isDisabled`, `isRequired`, `isReadOnly`, `isSelected`, `isOpen`, `selectedKey`, `onSelectionChange`. Don't use the HTML `disabled`/`checked` attributes.
26
+ - **`label` is a required string prop**, not children, on the form fields (`RudiInput`, `RudiTextarea`, `RudiSelect`, `RudiComboBox`, `RudiRadioGroup`, `RudiCheckboxGroup`, `RudiNumberField`, the date pickers), on progress indicators and on charts. It is the accessible name. Validation text goes in `errorMessage`, which also sets the invalid state.
27
+ - **Icons are Iconify name strings**: `icon="mdi:close"` or `iconBefore="lucide:plus"`. Never import icon components.
28
+ - **`className` is merged** with the component's own classes (`clsx` + `tailwind-merge`), never replaced. To change how something looks, override tokens instead of piling on classes.
29
+ - **Compound components use dot parts**: `RudiCard.Header`, `RudiDialog.Footer`, `RudiAppShell.Sidebar`, `RudiCover.Centered`.
30
+ - **Collections use React Aria's pattern**: `items` plus a render function that returns `RudiOption`, `RudiMenuItem` or `RudiTableRow`, or static children with `id`s.
31
+ - **Layout and typography primitives** (`RudiBox`, `RudiStack`, `RudiCluster`, `RudiGrid`, `RudiSidebar`, `RudiCenter`, `RudiCover`, `RudiSwitcher`, `RudiText`, `RudiProse`) take an `as` prop and spread any DOM attribute. `RudiHeading` spreads DOM attributes too, but its `level` prop picks the tag. Their spacing props take **CSS length strings** (`"1rem"`, `"var(--rudi-spacing-6)"`), not a numeric scale. The spacing prop is always named `space`; on `RudiBox` it is `padding`. Most other components have closed prop interfaces. The reference notes each one that spreads DOM props.
32
+ - **Prefer the primitives over hand-written layout CSS**: use `RudiStack` for vertical rhythm, `RudiCluster` for wrapping inline groups, `RudiGrid` for responsive cards, `RudiSidebar` for a fixed side plus fluid content, `RudiSwitcher` for a row that becomes a column, and `RudiCenter` for a max-width column.
33
+
34
+ ## Themes
35
+
36
+ Set `data-theme` on `<html>` or on any wrapper to theme a subtree. The default theme lives on `:root`, so leave the attribute off for it. There is no `"light"` value.
37
+
38
+ `dark`, `roomy`, `roomy-dark`, `soft`, `soft-dark`, `compressed`, `compressed-dark`, `auto`. `auto` follows the OS `prefers-color-scheme`.
39
+
40
+ ## Tokens
41
+
42
+ Every visual value is a `--rudi-*` custom property in three tiers: primitive (`--rudi-color-neutral-900`), then semantic (`--rudi-color-brand-primary`), then component (`--rudi-component-button-primary-bg`). Override the semantic tier in a stylesheet loaded after `rudiment-ui/styles`. Theme blocks have the same specificity as `:root` and come later in the cascade, so repeat each override under every `[data-theme="…"]` you use.
43
+
44
+ Common semantic tokens:
45
+ - `--rudi-color-brand-primary` (with `-hover` and `-active`)
46
+ - `--rudi-color-background-{surface,raised,sunken,overlay}`
47
+ - `--rudi-color-text-{default,subtle,disabled}`
48
+ - `--rudi-color-border-{default,focus,error}`
49
+ - `--rudi-color-feedback-{error,success,warning,info}`
50
+ - `--rudi-spacing-{0,1,2,3,4,6,8,12}`
51
+ - `--rudi-radius-{none,sm,md,lg,full}`
52
+ - `--rudi-font-size-{xs…4xl}`
53
+
54
+ ## Reading the prop reference (llms-full.txt)
55
+
56
+ - Each component's table lists the props it declares itself. **Required** props are marked, and a default comes from the implementation.
57
+ - "Inherited from React Aria" lists the extra props the component forwards, such as `onPress`, `isDisabled` and `aria-label`. React Aria documents their meaning, and `components.json` has their types.
58
+ - "`ref` forwards to …" names the DOM element a `ref` reaches.
59
+
60
+ ## Component index
61
+
62
+ Props, defaults and examples for each component are in `llms-full.txt` next to this file. Search it for `### RudiName`. The `.d.ts` files carry the same JSDoc.
63
+
64
+ - `RudiButton` — A text button built on React Aria's `useButton`.
65
+ - `RudiInput` — A single-line text field with label, description and error message.
66
+ - `RudiCheckbox` — A checkbox with a visible label.
67
+ - `RudiCheckboxGroup` — A labelled set of `RudiCheckbox` options whose selection is a string array.
68
+ - `RudiSelect` — A dropdown for choosing one option from a list.
69
+ - `RudiOption` — One entry in a `RudiSelect` or `RudiComboBox` list.
70
+ - `RudiMenuTrigger` — Connects a pressable trigger to a `RudiMenu`.
71
+ - `RudiMenu` — The popover and item list of a menu.
72
+ - `RudiMenuItem` — A single action in a `RudiMenu`.
73
+ - `RudiMenuSection` — Groups related `RudiMenuItem`s inside a `RudiMenu`, with an optional `title` heading.
74
+ - `RudiMenuSeparator` — Horizontal divider between groups of items in a `RudiMenu`.
75
+ - `RudiKeyboard` — Keyboard shortcut hint, styled as the trailing shortcut text of a menu item.
76
+ - `RudiSubmenuTrigger` — Nests a menu inside a `RudiMenu`.
77
+ - `RudiSeparator` — React Aria's `Separator`, re-exported unchanged and unstyled.
78
+ - `RudiDialog` — Modal dialog with a title, scrolling body and optional pinned footer.
79
+ - `RudiDialog.Footer` — Action row pinned to the bottom of the dialog; primary action last.
80
+ - `RudiSwitch` — An on/off toggle for settings that take effect immediately; use `RudiCheckbox` for choices submitted with a form.
81
+ - `RudiRadioGroup` — A labelled set of mutually exclusive `RudiRadio` options.
82
+ - `RudiRadio` — A single option inside `RudiRadioGroup`.
83
+ - `RudiTooltipTrigger` — Shows a `RudiTooltip` when its trigger is hovered or focused.
84
+ - `RudiTooltip` — Tooltip bubble.
85
+ - `RudiAlert` — Inline message banner for status, feedback, or warnings that sit within the page content.
86
+ - `RudiIconButton` — A button that shows only an icon.
87
+ - `RudiBadge` — Small non-interactive label for status or counts.
88
+ - `RudiTag` — Compact label for a keyword, filter, or selection.
89
+ - `RudiIcon` — Renders an Iconify icon by name (for example `"mdi:close"`).
90
+ - `RudiCard` — Surface container that groups related content.
91
+ - `RudiCard.Header` — Top section of the card; holds the title and actions.
92
+ - `RudiCard.Body` — Main content area of the card.
93
+ - `RudiCard.Footer` — Bottom section of the card; holds buttons or metadata.
94
+ - `RudiProgressBar` — Horizontal bar showing determinate progress.
95
+ - `RudiDivider` — Thin rule that separates sections of content.
96
+ - `RudiDot` — Small colored circle for status or category.
97
+ - `RudiLink` — Styled anchor for navigation.
98
+ - `RudiImage` — Image in a framed, rounded container with an optional aspect ratio and overlay layer.
99
+ - `RudiRating` — Star rating display that becomes an input when `onChange` is provided.
100
+ - `RudiStepper` — Ordered list of steps that shows progress through a multi-step process.
101
+ - `RudiTextarea` — A multi-line text field with label, description and error message.
102
+ - `RudiBreadcrumb` — Navigation trail showing where the current page sits in a hierarchy.
103
+ - `RudiPagination` — Page navigation with previous and next buttons and numbered pages, truncated with ellipses for long ranges.
104
+ - `RudiAvatar` — Circular representation of a person or entity: an image when `src` loads, otherwise initials derived from `name`.
105
+ - `RudiStatCard` — Outlined card showing one headline metric with an optional change indicator.
106
+ - `RudiNavItem` — Navigation entry for a sidebar: an `a` when `href` is set, otherwise a `button`.
107
+ - `RudiCircularProgress` — Ring showing determinate progress, with optional content in the center.
108
+ - `RudiBarChart` — Bar chart with one series per data key, built on Recharts and the library chart theme.
109
+ - `RudiLineChart` — Line chart with one series per data key, built on Recharts and the library chart theme.
110
+ - `RudiSparkline` — Tiny axis-less line for showing a trend inside a card, table cell, or sentence.
111
+ - `RudiDonutChart` — Donut chart showing parts of a whole, built on Recharts and the library chart theme.
112
+ - `RudiKanbanBoard` — Drag-and-drop board of columns and cards, with pointer and keyboard dragging and screen-reader announcements.
113
+ - `RudiKanbanBoard.Column` — A single column.
114
+ - `RudiKanbanColumn` — One droppable column of sortable cards.
115
+ - `RudiKanbanCard` — A draggable card with a drag handle.
116
+ - `RudiHeading` — Semantic heading (`h1` to `h6`) whose visual size is set separately from its level, so the document outline stays correct while the look follows the design.
117
+ - `RudiText` — Body-level text in one of five variants (body, body-sm, caption, overline, code).
118
+ - `RudiProse` — Wrapper that styles plain HTML children (paragraphs, headings, lists, links) with consistent typography and vertical rhythm.
119
+ - `RudiBox` — Padded container with an optional border or inverted surface.
120
+ - `RudiStack` — Vertical list of children with consistent spacing.
121
+ - `RudiCluster` — Horizontal row of items that wraps onto new lines when space runs out.
122
+ - `RudiGrid` — Responsive grid of equal-width columns that adds or drops columns as the container width changes, with no breakpoints.
123
+ - `RudiSidebar` — Two-panel layout where one panel has a set width and the other fills the rest, wrapping to a column when the content would drop below `contentMin`.
124
+ - `RudiCenter` — Horizontally centers its content in a column capped at a maximum width.
125
+ - `RudiCover` — Full-height column that pins an optional first and last child to the top and bottom and centers `RudiCover.Centered` in between. Use it for hero sections and login pages; use `RudiCenter` for horizontal centering only. Polymorphic through `as`; unrecognised DOM props (`id`, `aria-*`, `data-*`, handlers) are spread onto the root element, and `className` is merged with the built-in class, not replaced.
126
+ - `RudiCover.Centered` — The child centered vertically between the cover's other children.
127
+ - `RudiSwitcher` — Row of children that switches to a single column, all at once, when the container is narrower than `threshold`.
128
+ - `RudiAppShell` — Application frame with a sidebar and a content area; below 900px the sidebar becomes a drawer that Escape and the backdrop close.
129
+ - `RudiAppShell.Sidebar` — Navigation drawer (an `aside`) shown inline on wide screens and as a slide-over below 900px; renders its own backdrop.
130
+ - `RudiAppShell.Content` — Column beside the sidebar that holds the top bar and the main area.
131
+ - `RudiAppShell.Main` — The page's `main` landmark; centers its children in a padded column with a max width.
132
+ - `RudiAppShell.MenuButton` — Hamburger button that toggles the sidebar drawer; place it in the top bar's `start` slot.
133
+ - `RudiTopBar` — Horizontal application bar with start, center, and end slots and an optional announcement strip above.
134
+ - `RudiDescriptionList` — Semantic `dl` for read-only key-value data such as record details.
135
+ - `RudiPageHeader` — Title block for a page: heading with optional eyebrow, subtitle, metadata, and an actions slot.
136
+ - `RudiSectionHeader` — Heading row for a section of a page, with an optional description and an action slot.
137
+ - `RudiRouterProvider` — Connects Rudi links (`RudiLink`, `RudiNavItem`, `RudiBreadcrumb`) to your router for client-side navigation.
138
+ - `RudiBrand` — Logo lockup: a mark plus the product name, optionally linking home.
139
+ - `RudiForm` — A `<form>` that collects submitted values as `FormData`, never reloads the page, and shows a focusable error summary when `errors` is non-empty.
140
+ - `RudiTabs` — Root of the tabs compound.
141
+ - `RudiTabList` — Container for the `RudiTab`s inside `RudiTabs`.
142
+ - `RudiTab` — A single tab in a `RudiTabList`.
143
+ - `RudiTabPanel` — Content shown when its tab is selected.
144
+ - `RudiEmptyState` — Placeholder for a view, table, or card with no content, explaining why and offering a next step.
145
+ - `RudiComboBox` — A searchable select: a text input that filters a list of options by case- and accent-insensitive substring match.
146
+ - `RudiToastRegion` — Renders toasts queued with `rudiToast`.
147
+ - `RudiTable` — Accessible data table built on React Aria Components' `Table`.
148
+ - `RudiTableHeader` — The header row.
149
+ - `RudiTableColumn` — A column header in `RudiTableHeader`.
150
+ - `RudiTableBody` — The table body.
151
+ - `RudiTableRow` — A table row.
152
+ - `RudiTableCell` — A data cell in a `RudiTableRow`, in the same order as the table's columns.
153
+ - `RudiDatePicker` — A date (or date and time) field with segmented keyboard entry and a calendar popover.
154
+ - `RudiDateRangePicker` — A start and end date field with segmented keyboard entry and a range calendar popover.
155
+ - `RudiNumberField` — A numeric field with locale-aware parsing, optional currency or percent formatting, and stepper buttons.
156
+
157
+ ## Functions and hooks
158
+
159
+ - `cn` — Joins class names with `clsx` and resolves conflicting Tailwind utilities with `tailwind-merge`.
160
+ - `useLoadingButton` — Button behavior with a loading state, for building custom buttons.
161
+ - `useChartTheme` — Reads the active theme's chart colors (series, axes, grid, tooltip and feedback tones) from the `--rudi-*` CSS custom properties, for chart libraries that need color values in JS.
162
+ - `rudiToast` — Show toasts from anywhere: `rudiToast.success('Saved')`. Requires one `RudiToastRegion` mounted near the app root. Every method returns the toast's key, which `rudiToast.close(key)` accepts. Success, info and warning toasts dismiss after 5000 ms by default; error toasts stay until closed.
@@ -1,6 +1,8 @@
1
1
  import { RudiTypographyAlign, RudiTypographyTone, RudiTypographyWeight } from '../Text/Text';
2
2
  export interface RudiHeadingProps extends React.HTMLAttributes<HTMLHeadingElement> {
3
+ /** Semantic level; picks the element (`1` renders `h1`, through `6` for `h6`) and the document outline. Keep levels in order. */
3
4
  level: 1 | 2 | 3 | 4 | 5 | 6;
5
+ /** Visual size on the same 1-6 scale, independent of `level`; matches `level` when omitted. */
4
6
  size?: 1 | 2 | 3 | 4 | 5 | 6;
5
7
  /** Font weight, overriding the size default. */
6
8
  weight?: RudiTypographyWeight;
@@ -10,8 +12,18 @@ export interface RudiHeadingProps extends React.HTMLAttributes<HTMLHeadingElemen
10
12
  align?: RudiTypographyAlign;
11
13
  /** Removes the element's default block margin. */
12
14
  noMargin?: boolean;
15
+ /** Heading content. */
13
16
  children: React.ReactNode;
17
+ /** Extra class names, merged with the built-in classes. */
14
18
  className?: string;
15
19
  }
20
+ /**
21
+ * Semantic heading (`h1` to `h6`) whose visual size is set separately from its level, so the document outline stays correct while the look follows the design. Use `RudiText` for non-heading text. Not polymorphic: the element is always chosen by `level`. Other DOM props are spread onto the element.
22
+ *
23
+ * @example
24
+ * <RudiHeading level={2} size={4} tone="brand">
25
+ * Section title
26
+ * </RudiHeading>
27
+ */
16
28
  export declare const RudiHeading: import('react').ForwardRefExoticComponent<RudiHeadingProps & import('react').RefAttributes<HTMLHeadingElement>>;
17
29
  //# sourceMappingURL=Heading.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"Heading.d.ts","sourceRoot":"","sources":["../../../src/typography/Heading/Heading.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACrB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,eAAe,CAAA;AAEtB,MAAM,WAAW,gBAAiB,SAAQ,KAAK,CAAC,cAAc,CAAC,kBAAkB,CAAC;IAChF,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAC5B,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAC5B,gDAAgD;IAChD,MAAM,CAAC,EAAE,oBAAoB,CAAA;IAC7B,2BAA2B;IAC3B,IAAI,CAAC,EAAE,kBAAkB,CAAA;IACzB,sBAAsB;IACtB,KAAK,CAAC,EAAE,mBAAmB,CAAA;IAC3B,kDAAkD;IAClD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;IACzB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,eAAO,MAAM,WAAW,iHAyBvB,CAAA"}
1
+ {"version":3,"file":"Heading.d.ts","sourceRoot":"","sources":["../../../src/typography/Heading/Heading.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACrB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,eAAe,CAAA;AAEtB,MAAM,WAAW,gBAAiB,SAAQ,KAAK,CAAC,cAAc,CAAC,kBAAkB,CAAC;IAChF,iIAAiI;IACjI,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAC5B,+FAA+F;IAC/F,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAC5B,gDAAgD;IAChD,MAAM,CAAC,EAAE,oBAAoB,CAAA;IAC7B,2BAA2B;IAC3B,IAAI,CAAC,EAAE,kBAAkB,CAAA;IACzB,sBAAsB;IACtB,KAAK,CAAC,EAAE,mBAAmB,CAAA;IAC3B,kDAAkD;IAClD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,uBAAuB;IACvB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;IACzB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,iHAyBvB,CAAA"}
@@ -1,8 +1,29 @@
1
1
  export interface RudiProseProps extends React.HTMLAttributes<HTMLElement> {
2
+ /**
3
+ * Type scale for the whole block: `sm`, `base`, or `lg`.
4
+ *
5
+ * @default 'base'
6
+ */
2
7
  size?: 'sm' | 'base' | 'lg';
8
+ /**
9
+ * Element or component to render as the root.
10
+ *
11
+ * @default 'div'
12
+ */
3
13
  as?: React.ElementType;
14
+ /** Long-form content, such as paragraphs, headings, lists, and quotes, as plain elements. */
4
15
  children: React.ReactNode;
16
+ /** Extra class names, merged with the built-in classes. */
5
17
  className?: string;
6
18
  }
19
+ /**
20
+ * Wrapper that styles plain HTML children (paragraphs, headings, lists, links) with consistent typography and vertical rhythm. Use it for articles, documentation, and CMS output; use `RudiText` and `RudiHeading` when you compose individual pieces. Polymorphic through `as`; DOM props are spread onto the root.
21
+ *
22
+ * @example
23
+ * <RudiProse size="lg">
24
+ * <h2>Title</h2>
25
+ * <p>Body copy.</p>
26
+ * </RudiProse>
27
+ */
7
28
  export declare const RudiProse: import('react').ForwardRefExoticComponent<RudiProseProps & import('react').RefAttributes<HTMLElement>>;
8
29
  //# sourceMappingURL=Prose.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"Prose.d.ts","sourceRoot":"","sources":["../../../src/typography/Prose/Prose.tsx"],"names":[],"mappings":"AAEA,OAAO,aAAa,CAAA;AAEpB,MAAM,WAAW,cAAe,SAAQ,KAAK,CAAC,cAAc,CAAC,WAAW,CAAC;IACvE,IAAI,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAAA;IAC3B,EAAE,CAAC,EAAE,KAAK,CAAC,WAAW,CAAA;IACtB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;IACzB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,eAAO,MAAM,SAAS,wGAiBpB,CAAA"}
1
+ {"version":3,"file":"Prose.d.ts","sourceRoot":"","sources":["../../../src/typography/Prose/Prose.tsx"],"names":[],"mappings":"AAEA,OAAO,aAAa,CAAA;AAEpB,MAAM,WAAW,cAAe,SAAQ,KAAK,CAAC,cAAc,CAAC,WAAW,CAAC;IACvE;;;;OAIG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAAA;IAC3B;;;;OAIG;IACH,EAAE,CAAC,EAAE,KAAK,CAAC,WAAW,CAAA;IACtB,6FAA6F;IAC7F,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;IACzB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,wGAiBpB,CAAA"}
@@ -1,8 +1,25 @@
1
+ /** Font weight options shared by `RudiText` and `RudiHeading`, mapped to the font-weight tokens. */
1
2
  export type RudiTypographyWeight = 'regular' | 'medium' | 'semibold' | 'bold';
3
+ /** Semantic text colors shared by `RudiText` and `RudiHeading`, mapped to semantic color tokens that adapt per theme. */
2
4
  export type RudiTypographyTone = 'default' | 'subtle' | 'disabled' | 'brand' | 'inverted' | 'success' | 'warning' | 'error' | 'info';
5
+ /** Text alignment options shared by `RudiText` and `RudiHeading`; `start` and `end` follow the writing direction. */
3
6
  export type RudiTypographyAlign = 'start' | 'center' | 'end' | 'justify';
4
- export interface RudiTextProps extends React.HTMLAttributes<HTMLElement> {
7
+ /**
8
+ * Props for `RudiText`. Extends `AllHTMLAttributes` rather than `HTMLAttributes` so element-specific
9
+ * attributes type-check with `as`, such as `href` with `as="a"` and `htmlFor` with `as="label"`.
10
+ */
11
+ export interface RudiTextProps extends Omit<React.AllHTMLAttributes<HTMLElement>, 'as'> {
12
+ /**
13
+ * Typographic role: `body` for paragraphs, `body-sm` for supporting text, `caption` for metadata, `overline` for uppercase labels, `code` for monospace values.
14
+ *
15
+ * @default 'body'
16
+ */
5
17
  variant?: 'body' | 'body-sm' | 'caption' | 'overline' | 'code';
18
+ /**
19
+ * Element or component to render. Use `"span"` for inline text, or `"label"` and `"strong"` where the semantics call for them.
20
+ *
21
+ * @default 'p'
22
+ */
6
23
  as?: React.ElementType;
7
24
  /** Font weight, overriding the variant default. */
8
25
  weight?: RudiTypographyWeight;
@@ -12,8 +29,18 @@ export interface RudiTextProps extends React.HTMLAttributes<HTMLElement> {
12
29
  align?: RudiTypographyAlign;
13
30
  /** Removes the element's default block margin. */
14
31
  noMargin?: boolean;
32
+ /** Text content. */
15
33
  children: React.ReactNode;
34
+ /** Extra class names, merged with the built-in classes. */
16
35
  className?: string;
17
36
  }
37
+ /**
38
+ * Body-level text in one of five variants (body, body-sm, caption, overline, code). Use `RudiHeading` for headings and `RudiProse` for long-form content with its own rhythm. Polymorphic through `as`, which defaults to a `p`; other DOM props are spread onto the element.
39
+ *
40
+ * @example
41
+ * <RudiText variant="caption" tone="subtle">
42
+ * Last updated March 2026
43
+ * </RudiText>
44
+ */
18
45
  export declare const RudiText: import('react').ForwardRefExoticComponent<RudiTextProps & import('react').RefAttributes<HTMLElement>>;
19
46
  //# sourceMappingURL=Text.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"Text.d.ts","sourceRoot":"","sources":["../../../src/typography/Text/Text.tsx"],"names":[],"mappings":"AAEA,OAAO,YAAY,CAAA;AAEnB,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAA;AAC7E,MAAM,MAAM,kBAAkB,GAC1B,SAAS,GACT,QAAQ,GACR,UAAU,GACV,OAAO,GACP,UAAU,GACV,SAAS,GACT,SAAS,GACT,OAAO,GACP,MAAM,CAAA;AACV,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAA;AAExE,MAAM,WAAW,aAAc,SAAQ,KAAK,CAAC,cAAc,CAAC,WAAW,CAAC;IACtE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,GAAG,MAAM,CAAA;IAC9D,EAAE,CAAC,EAAE,KAAK,CAAC,WAAW,CAAA;IACtB,mDAAmD;IACnD,MAAM,CAAC,EAAE,oBAAoB,CAAA;IAC7B,2BAA2B;IAC3B,IAAI,CAAC,EAAE,kBAAkB,CAAA;IACzB,sBAAsB;IACtB,KAAK,CAAC,EAAE,mBAAmB,CAAA;IAC3B,kDAAkD;IAClD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;IACzB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,eAAO,MAAM,QAAQ,uGA8BnB,CAAA"}
1
+ {"version":3,"file":"Text.d.ts","sourceRoot":"","sources":["../../../src/typography/Text/Text.tsx"],"names":[],"mappings":"AAEA,OAAO,YAAY,CAAA;AAEnB,oGAAoG;AACpG,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAA;AAC7E,yHAAyH;AACzH,MAAM,MAAM,kBAAkB,GAC1B,SAAS,GACT,QAAQ,GACR,UAAU,GACV,OAAO,GACP,UAAU,GACV,SAAS,GACT,SAAS,GACT,OAAO,GACP,MAAM,CAAA;AACV,qHAAqH;AACrH,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAA;AAExE;;;GAGG;AACH,MAAM,WAAW,aAAc,SAAQ,IAAI,CAAC,KAAK,CAAC,iBAAiB,CAAC,WAAW,CAAC,EAAE,IAAI,CAAC;IACrF;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,GAAG,MAAM,CAAA;IAC9D;;;;OAIG;IACH,EAAE,CAAC,EAAE,KAAK,CAAC,WAAW,CAAA;IACtB,mDAAmD;IACnD,MAAM,CAAC,EAAE,oBAAoB,CAAA;IAC7B,2BAA2B;IAC3B,IAAI,CAAC,EAAE,kBAAkB,CAAA;IACzB,sBAAsB;IACtB,KAAK,CAAC,EAAE,mBAAmB,CAAA;IAC3B,kDAAkD;IAClD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,oBAAoB;IACpB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;IACzB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,uGA8BnB,CAAA"}
@@ -1,3 +1,10 @@
1
1
  import { ClassValue } from 'clsx';
2
+ /**
3
+ * Joins class names with `clsx` and resolves conflicting Tailwind utilities with `tailwind-merge`.
4
+ * Falsy values are dropped. Components use it so a consumer's `className` is merged, not replaced.
5
+ *
6
+ * @example
7
+ * cn('rudi-button', isBusy && 'rudi-button--busy', className)
8
+ */
2
9
  export declare function cn(...inputs: ClassValue[]): string;
3
10
  //# sourceMappingURL=cn.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"cn.d.ts","sourceRoot":"","sources":["../../src/utils/cn.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAQ,MAAM,MAAM,CAAA;AAG5C,wBAAgB,EAAE,CAAC,GAAG,MAAM,EAAE,UAAU,EAAE,UAEzC"}
1
+ {"version":3,"file":"cn.d.ts","sourceRoot":"","sources":["../../src/utils/cn.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAQ,MAAM,MAAM,CAAA;AAG5C;;;;;;GAMG;AACH,wBAAgB,EAAE,CAAC,GAAG,MAAM,EAAE,UAAU,EAAE,UAEzC"}
package/mcp/README.md ADDED
@@ -0,0 +1,111 @@
1
+ # rudiment-ui MCP server
2
+
3
+ An [MCP](https://modelcontextprotocol.io) server that gives coding agents (Claude Code, Cursor, VS Code Copilot, Codex, Claude Desktop) the rudiment-ui API: every component, prop, default, compound part and convention.
4
+
5
+ It ships inside the `rudiment-ui` package and reads the `dist/components.json` generated from that version's source. Its answers always match the version in your `node_modules`, with no network access, no account and no extra install.
6
+
7
+ ## Quick start
8
+
9
+ Install the library, then register the server with your agent from the project root:
10
+
11
+ ```bash
12
+ npm install rudiment-ui
13
+ claude mcp add rudiment-ui -- npx --no rudiment-ui-mcp # Claude Code
14
+ ```
15
+
16
+ Restart the agent (or run `/mcp` in Claude Code) and confirm that `rudiment-ui` is listed as connected. Then ask for UI as usual, for example "build a settings form with rudiment-ui". The server tells the agent to read the conventions first.
17
+
18
+ > **Why `npx --no`?** The `--no` flag stops npx from downloading anything when it can't find the binary. `rudiment-ui-mcp` is a binary inside the `rudiment-ui` package, not a package of its own on npm. Without the flag, a project that hasn't installed rudiment-ui would make npx try to fetch a package of that name from the registry.
19
+
20
+ ## Client setup
21
+
22
+ Every client runs the same command: `npx --no rudiment-ui-mcp`, started from the project root.
23
+
24
+ **Claude Code**: for your machine only:
25
+ ```bash
26
+ claude mcp add rudiment-ui -- npx --no rudiment-ui-mcp
27
+ ```
28
+ or for everyone on the project (writes `.mcp.json`, which you commit):
29
+ ```bash
30
+ claude mcp add --scope project rudiment-ui -- npx --no rudiment-ui-mcp
31
+ ```
32
+
33
+ **`.mcp.json`** (Claude Code project scope) and **`.cursor/mcp.json`** (Cursor). Most other clients use the same `mcpServers` shape:
34
+ ```json
35
+ {
36
+ "mcpServers": {
37
+ "rudiment-ui": { "command": "npx", "args": ["--no", "rudiment-ui-mcp"] }
38
+ }
39
+ }
40
+ ```
41
+
42
+ **VS Code** (`.vscode/mcp.json`):
43
+ ```json
44
+ {
45
+ "servers": {
46
+ "rudiment-ui": { "type": "stdio", "command": "npx", "args": ["--no", "rudiment-ui-mcp"] }
47
+ }
48
+ }
49
+ ```
50
+
51
+ **Codex** (`~/.codex/config.toml`):
52
+ ```toml
53
+ [mcp_servers.rudiment-ui]
54
+ command = "npx"
55
+ args = ["--no", "rudiment-ui-mcp"]
56
+ ```
57
+
58
+ **Claude Desktop** and any client that doesn't start in your project folder: point `node` at the server file with an absolute path.
59
+ ```json
60
+ {
61
+ "mcpServers": {
62
+ "rudiment-ui": {
63
+ "command": "node",
64
+ "args": ["/absolute/path/to/your-app/node_modules/rudiment-ui/mcp/server.mjs"]
65
+ }
66
+ }
67
+ }
68
+ ```
69
+
70
+ ## Tools
71
+
72
+ | Tool | Arguments | Returns |
73
+ | ---- | --------- | ------- |
74
+ | `get_conventions` | none | Library-wide rules: setup, `onPress` vs `onClick`, `onChange` values, required `label`, Iconify icons, layout primitives, theming, tokens. Agents should call it once before writing UI code. |
75
+ | `list_components` | `category?`: `component` \| `layout` \| `typography` \| `chart`. `query?`: substring | Every component and compound part with a one-line summary. |
76
+ | `get_component` | `name`: `"RudiSelect"`, `"Select"`, `"card.header"`, `"rudiToast"`. `includeInherited?`: boolean | Summary, examples, a props table (type, default, required, description), parts, `ref` target, inherited React Aria props, import line and source path. Unknown names return close suggestions. |
77
+ | `search` | `query`: keywords, all must match. `limit?` | Components, props, functions and types whose name or description matches, e.g. `"sticky header"`, `"dismiss"`, `"required"`. |
78
+
79
+ Resources: `rudiment-ui://conventions` (Markdown) and `rudiment-ui://components.json` (the full manifest), for clients that attach resources directly.
80
+
81
+ ## Trying it by hand
82
+
83
+ ```bash
84
+ printf '%s\n' \
85
+ '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{}}}' \
86
+ '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_component","arguments":{"name":"Button"}}}' \
87
+ | npx --no rudiment-ui-mcp
88
+ ```
89
+
90
+ Or browse it with the MCP Inspector: `npx @modelcontextprotocol/inspector npx --no rudiment-ui-mcp`.
91
+
92
+ ## No MCP? Use the files
93
+
94
+ Every answer the server gives comes from files that ship in the package, so agents without MCP support can read them directly:
95
+
96
+ - `node_modules/rudiment-ui/dist/llms.txt`: conventions and the component index
97
+ - `node_modules/rudiment-ui/dist/llms-full.txt`: every prop table
98
+ - `node_modules/rudiment-ui/dist/components.json`: the manifest
99
+
100
+ ## Troubleshooting
101
+
102
+ | Symptom | Fix |
103
+ | ------- | --- |
104
+ | `npx: … could not determine executable to run` | rudiment-ui isn't installed in the folder the client started in. Run `npm install rudiment-ui`, or use the absolute-path setup above. |
105
+ | Tool calls return "manifest not found" | The package is missing `dist/`. Reinstall it. Inside the rudiment-ui repo itself, run `npm run build` first. |
106
+ | Answers look out of date | The server reads the installed version. Upgrade `rudiment-ui` and restart the agent so the server reloads. |
107
+ | Use a manifest from somewhere else | Set `RUDIMENT_UI_MANIFEST=/path/to/components.json` in the server's environment. |
108
+
109
+ ## How it works
110
+
111
+ `npm run build` runs `scripts/component-docs.mjs`, which walks every export of `src/index.ts` with the TypeScript checker and writes `dist/components.json`. `mcp/server.mjs` is a zero-dependency stdio JSON-RPC server: MCP over stdio is newline-delimited JSON-RPC 2.0, and a UI library shouldn't make every consumer install an SDK. It renders Markdown with `mcp/render.mjs`, the same renderer that writes `llms*.txt`. It supports protocol versions 2024-11-05 through 2025-11-25. `mcp/server.test.mjs` drives the real binary over stdio.
package/mcp/render.mjs ADDED
@@ -0,0 +1,116 @@
1
+ /**
2
+ * Markdown rendering for the rudiment-ui API manifest (`dist/components.json`).
3
+ *
4
+ * Pure functions with no dependencies, so they can ship in the published package.
5
+ * `scripts/component-docs.mjs` uses them at build time to write `dist/llms*.txt`,
6
+ * and `mcp/server.mjs` uses them at runtime to answer tool calls.
7
+ */
8
+
9
+ const cell = (s) => String(s ?? '').replaceAll('|', '\\|').replace(/\s*\n\s*/g, ' ')
10
+
11
+ /** First sentence of a description, ignoring the periods in "e.g." and similar. */
12
+ export function firstSentence(s = '') {
13
+ const flat = s.replace(/\s+/g, ' ').trim()
14
+ return (flat.match(/^(?:e\.g\.|i\.e\.|etc\.|vs\.|[^.!?])*[.!?](?=\s|$)/)?.[0] ?? flat).trim()
15
+ }
16
+
17
+ const fence = (code, lang = 'tsx') => (code.startsWith('```') ? code : '```' + lang + '\n' + code + '\n```')
18
+
19
+ function propTable(props) {
20
+ const rows = props.map(
21
+ (p) =>
22
+ `| \`${p.name}\`${p.required ? ' *(required)*' : ''} | \`${cell(p.type)}\` | ${p.default !== undefined ? `\`${cell(p.default)}\`` : ''} | ${cell(p.deprecated ? `**Deprecated.** ${p.description}` : p.description)} |`,
23
+ )
24
+ return ['| Prop | Type | Default | Description |', '| --- | --- | --- | --- |', ...rows].join('\n')
25
+ }
26
+
27
+ /**
28
+ * One component (and its compound parts) as Markdown.
29
+ * `inheritedDetail: true` lists inherited React Aria props with types and summaries
30
+ * instead of names only.
31
+ */
32
+ export function componentMarkdown(c, { depth = 3, inheritedDetail = false } = {}) {
33
+ const h = '#'.repeat(depth)
34
+ const out = [`${h} ${c.name}`, '']
35
+ if (c.reexportedFrom) out.push(`Re-exported unchanged from \`${c.reexportedFrom}\`.`, '')
36
+ if (c.description) out.push(c.description, '')
37
+ for (const ex of c.examples ?? []) out.push(fence(ex), '')
38
+ const own = c.props.filter((p) => p.origin === 'own' || p.origin === 'dom')
39
+ const inherited = c.props.filter((p) => p.origin === 'react-aria' || p.origin === 'other')
40
+ if (own.length) out.push(propTable(own), '')
41
+ if (inherited.length) {
42
+ if (inheritedDetail) {
43
+ out.push(`Inherited from React Aria (${inherited.length}):`, '')
44
+ out.push(
45
+ inherited
46
+ .map((p) => `- \`${p.name}${p.required ? '' : '?'}: ${p.type}\`${p.description ? ` — ${firstSentence(p.description)}` : ''}`)
47
+ .join('\n'),
48
+ '',
49
+ )
50
+ } else {
51
+ out.push(
52
+ `Inherited from React Aria (types and descriptions in \`components.json\`): ${inherited.map((p) => `\`${p.name}\``).join(', ')}.`,
53
+ '',
54
+ )
55
+ }
56
+ }
57
+ const extras = []
58
+ if (c.refElement) extras.push(`\`ref\` forwards to \`${c.refElement}\`.`)
59
+ if (c.ariaGlobals) extras.push(`Also accepts React Aria's global DOM props (\`${c.ariaGlobals.join('`, `')}\`).`)
60
+ if (c.domAttributes?.length) extras.push(`Spreads remaining props onto the DOM element (\`${c.domAttributes.join('`, `')}\`).`)
61
+ if (extras.length) out.push(extras.join(' '), '')
62
+ for (const part of c.parts ?? []) out.push(componentMarkdown(part, { depth: depth + 1, inheritedDetail }))
63
+ return out.join('\n')
64
+ }
65
+
66
+ export function functionMarkdown(f, depth = 3) {
67
+ const out = [`${'#'.repeat(depth)} ${f.name}`, '', f.description, '', fence(f.signature, 'ts'), '']
68
+ for (const ex of f.examples ?? []) out.push(fence(ex), '')
69
+ return out.join('\n')
70
+ }
71
+
72
+ export function typeMarkdown(t, depth = 3) {
73
+ const out = [`${'#'.repeat(depth)} ${t.name}`, '']
74
+ if (t.description) out.push(t.description, '')
75
+ if (t.definition) out.push(fence(`type ${t.name} = ${t.definition}`, 'ts'), '')
76
+ if (t.fields) out.push(propTable(t.fields), '')
77
+ return out.join('\n')
78
+ }
79
+
80
+ /** One line per component and part: "- `RudiButton` — summary". */
81
+ export function componentIndex(api) {
82
+ const lines = []
83
+ for (const c of api.components) {
84
+ lines.push(`- \`${c.name}\` — ${firstSentence(c.description) || (c.reexportedFrom ? `re-export from ${c.reexportedFrom}` : '')}`)
85
+ for (const p of c.parts ?? []) lines.push(` - \`${p.name}\` — ${firstSentence(p.description)}`)
86
+ }
87
+ return lines.join('\n')
88
+ }
89
+
90
+ /**
91
+ * `full: false` gives the short llms.txt: conventions plus a one-line index.
92
+ * `full: true` gives llms-full.txt with every prop table.
93
+ */
94
+ export function renderMarkdown(api, { full = true } = {}) {
95
+ const out = [api.conventions.trim(), '', '## Component index', '']
96
+ if (!full)
97
+ out.push(
98
+ 'Props, defaults and examples for each component are in `llms-full.txt` next to this file. Search it for `### RudiName`. The `.d.ts` files carry the same JSDoc.',
99
+ '',
100
+ )
101
+ out.push(componentIndex(api))
102
+ if (!full) {
103
+ out.push('', '## Functions and hooks', '')
104
+ for (const f of api.functions) out.push(`- \`${f.name}\` — ${firstSentence(f.description)}`)
105
+ return tidy(out)
106
+ }
107
+ out.push('', '## Components', '')
108
+ for (const c of api.components) out.push(componentMarkdown(c))
109
+ out.push('## Functions and hooks', '')
110
+ for (const f of api.functions) out.push(functionMarkdown(f))
111
+ out.push('## Supporting types', '')
112
+ for (const t of api.types) out.push(typeMarkdown(t))
113
+ return tidy(out)
114
+ }
115
+
116
+ const tidy = (lines) => lines.join('\n').replace(/\n{3,}/g, '\n\n') + '\n'