@boostdev/design-system-components 1.2.1 → 1.2.2

package/AGENTS.md

@@ -224,6 +224,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

@@ -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>` |
 
 ---
 
@@ -515,7 +515,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
 ```