@boostdev/design-system-components 1.2.1 → 1.2.3

package/AGENTS.md

@@ -158,6 +158,11 @@ Apply this pattern to any component with a visually distinct active/selected/fil
 - Shadow: use elevation scale (`--bds-shadow_s` … `--bds-shadow_2xl`). Shadows use `--bds-shadow_color-rgb` internally — override this token to theme shadow colour.
 - Z-index: use named role tokens, never raw integers
 - Focus-visible outlines: use `--bds-outline_default` (2px dotted, adapts to dark mode). `--bds-outline_color` is the colour token; `--bds-outline_offset` is the offset (2px outside). These are distinct from the inset `--bdc-outline_*` border system.
+- Border radius: use foundation tokens, never raw `px` or `%` values. Key tokens:
+  - `--bds-border_radius--full` (9999px) — pill shape for buttons, inputs, badges, tracks
+  - `--bds-border_radius--circle` (50%) — perfect circle for avatars, thumbs, close buttons, spinners
+  - `--bds-border_radius--xs` / `--s` / `--m` — standard rounded corners
+  - Always wrap in a component-scoped override: `var(--component_radius, var(--bds-border_radius--full))`
 - Dark mode: foundation tokens adapt automatically via `[data-theme="dark"]` attribute or `prefers-color-scheme: dark`. No extra CSS needed in components.
 
 ### Semantic tokens for state colours
@@ -224,6 +229,27 @@ References: https://developer.mozilla.org/en-US/docs/Web/Accessibility | https:/
 - **State guard in open/close methods**: `_open()` and `_close()` on stateful web components must return early if already in the target state, to prevent dispatching redundant events to listeners.
 - **Drawer/Dialog animation**: `<dialog>` is the sliding panel itself — no wrapper div. Slide animation uses `translate` + `@starting-style` only. Do **not** add `@keyframes` — mixing `@keyframes` (open) with `translate` transition (close) causes a stutter. Backdrop uses `opacity: 0` as default with `@starting-style { opacity: 0 }` on `[open]::backdrop` for a smooth fade. `display` and `overlay` discrete transitions must include the easing function before `allow-discrete`.
 
+## HTML attribute forwarding
+
+All components accept the full set of native HTML attributes for their root element. Props interfaces extend the appropriate `HTMLAttributes<HTMLXxxElement>` type and spread `...rest` onto the root element:
+
+```tsx
+interface BadgeProps extends WithClassName, HTMLAttributes<HTMLSpanElement> {
+  variant?: 'primary' | 'secondary' | 'success' | 'error' | 'warning';
+}
+
+export function Badge({ variant = 'primary', className, children, ...rest }: BadgeProps) {
+  return <span {...rest} className={cn(css.badge, className)}>{children}</span>;
+}
+```
+
+Key patterns:
+- Spread `{...rest}` **before** component-controlled attributes so explicit props always win
+- Use `Omit<HTMLAttributes<...>, 'prop'>` when a custom prop has an incompatible type with the HTML attribute (e.g. `title` as `ReactNode` instead of `string`, `onChange` with a custom signature, `content` as `ReactNode`)
+- Components wrapping `<fieldset>` use `FieldsetHTMLAttributes<HTMLFieldSetElement>`
+- Components wrapping `<a>` use `AnchorHTMLAttributes<HTMLAnchorElement>`
+- Composite form components (Combobox, NumberInput, FileInput) forward `...rest` through `InputContainer`
+
 ## Adding new components
 
 1. Create `src/components/{category}/{ComponentName}/`

package/README.md

@@ -149,7 +149,7 @@ Renders an `aria-hidden` shimmer block. Size it with a `className` or inline sty
 import { Button } from '@boostdev/components';
 
 <Button>Click me</Button>
-<Button variant="ghost">Cancel</Button>
+<Button variant="outline">Cancel</Button>
 <Button size="small">Small</Button>
 <Button href="/dashboard">Link button</Button>
 <Button iconStart={<Icon />} aria-label="Delete" />
@@ -158,7 +158,7 @@ import { Button } from '@boostdev/components';
 
 | Prop | Type | Default |
 |---|---|---|
-| `variant` | `'default' \| 'ghost'` | `'default'` |
+| `variant` | `'default' \| 'outline'` | `'default'` |
 | `size` | `'small' \| 'medium' \| 'large'` | `'medium'` |
 | `href` | `string` | — renders an `<a>` |
 | `iconStart` | `ReactNode` | — |
@@ -167,8 +167,8 @@ import { Button } from '@boostdev/components';
 | `disabled` | `boolean` | `false` |
 
 **Variants:**
-- `default` — filled with `--button_color` (CTA green). Hover transitions to an outlined state.
-- `ghost` — transparent background, border and text use `--button_color`. Hover fills.
+- `default` — filled with `--button_color`. Hover transitions to an outlined state.
+- `outline` — transparent background, border and text use `--button_color`. Hover fills. (`ghost` is a deprecated alias.)
 
 **Re-theming** — set two CSS custom properties to change the colour of both variants:
 
@@ -243,7 +243,7 @@ Toasts auto-dismiss after 5 seconds.
 
 ### Form components
 
-All form components accept standard HTML input attributes via spread in addition to their own props.
+All components accept native HTML attributes for their root element via `...rest` spread in addition to their own props. This means you can pass `id`, `data-*`, `aria-*`, `style`, event handlers, and any other valid HTML attribute directly.
 
 #### FormInput
 
@@ -309,20 +309,20 @@ Sizes: `small` · `medium` (default) · `large`
 ```tsx
 import { SegmentedControl } from '@boostdev/components';
 
-<SegmentedControl
-  name="view"
-  defaultValue="week"
-  aria-label="Calendar view"
-  options={[
-    { value: 'day',   label: 'Day'   },
-    { value: 'week',  label: 'Week'  },
-    { value: 'month', label: 'Month' },
-  ]}
-  onChange={value => console.log(value)}
-/>
+<SegmentedControl aria-label="Calendar view" selectedIndex={1}>
+  <button>Day</button>
+  <button>Week</button>
+  <button>Month</button>
+</SegmentedControl>
+
+{/* Navigation variant — active item auto-detected from aria-current */}
+<SegmentedControl aria-label="Section">
+  <a href="/overview" aria-current="page">Overview</a>
+  <a href="/details">Details</a>
+</SegmentedControl>
 ```
 
-Single-select control with a sliding thumb. All options have equal width (sized to the widest). Sizes: `small` · `medium` (default) · `large`.
+Children-based API — pass `<button>`, `<a>`, or router `<Link>` elements directly. Active item is set via `selectedIndex` or auto-detected from `aria-current="page"` / `aria-pressed={true}` / `aria-selected={true}`. Variants: `outline` (default) · `filled`. Sizes: `small` · `medium` (default) · `large`.
 
 ---
 
@@ -362,7 +362,7 @@ import { Card } from '@boostdev/components';
 | `variant` | `'default' \| 'elevated' \| 'outlined'` | `'default'` |
 | `padding` | `'none' \| 'small' \| 'medium' \| 'large'` | `'medium'` |
 | `textAlign` | `'start' \| 'center' \| 'end'` | `'start'` |
-| `onClick` | `() => void` | — renders a `<button>` |
+| `onClick` | `MouseEventHandler<HTMLElement>` | — renders a `<button>` |
 
 ---
 
@@ -447,6 +447,23 @@ All component styles sit in `@layer component`. You can also write rules in a hi
 }
 ```
 
+### Overriding border-radius
+
+Components default to pill (`--bds-border_radius--full`) or circle (`--bds-border_radius--circle`)
+shapes from the foundation. Override the component-scoped variable to change individual components:
+
+```css
+/* Make all buttons square-cornered */
+.my-button {
+  --button_radius: var(--bds-border_radius--s);
+}
+
+/* Make avatars rounded-square instead of circular */
+.my-avatar {
+  --avatar_radius: var(--bds-border_radius--m);
+}
+```
+
 ### Overriding active/checked state colour
 
 Components with a checked or filled state (Checkbox, Radio, Slider, Progress, ProgressCircle)
@@ -515,7 +532,7 @@ pnpm build        # compile to dist/
 pnpm typecheck    # TypeScript check (library code only)
 pnpm lint         # ESLint
 pnpm lint:css     # Stylelint
-pnpm test         # Vitest — 364 tests
+pnpm test         # Vitest — 857 tests
 pnpm mcp:start    # Start the MCP server locally (http://localhost:3001/api/mcp)
 pnpm storybook    # Storybook dev server on port 6006
 ```