@boostdev/design-system-components 1.2.0 → 1.2.2

package/AGENTS.md

@@ -32,12 +32,32 @@ import '@boostdev/components/web-components';
 
 ### Web Components (experimental) — `src/web-components/`
 Custom elements built with Lit. Entry: `src/web-components/index.ts`. Bundled with Lit (no peer dep required).
-- **ui/**: `<bds-alert>`, `<bds-badge>`
-- **interaction/**: `<bds-button>`, `<bds-popover>`, `<bds-toast-provider>`
 
-Storybook stories live at `src/web-components/{ui,interaction}/Bds*.stories.tsx` (title path `'Web Components/{UI|Interaction}/{Name}'`, tags `['!stable', 'experimental']`). Stories use a thin React wrapper to enable Storybook controls.
+- **ui/**: `<bds-alert>`, `<bds-avatar>`, `<bds-badge>`, `<bds-breadcrumb>`, `<bds-button-group>`, `<bds-calendar>`, `<bds-card>`, `<bds-carousel>`, `<bds-description-list>`, `<bds-icon-wrapper>`, `<bds-link>`, `<bds-loading>`, `<bds-notification-banner>`, `<bds-pagination>`, `<bds-progress>`, `<bds-progress-circle>`, `<bds-rating>`, `<bds-section-header>`, `<bds-separator>`, `<bds-skeleton>`, `<bds-table>`, `<bds-typography>`
+- **interaction/**: `<bds-accordion>`, `<bds-accordion-item>`, `<bds-button>`, `<bds-collapsible>`, `<bds-dialog>`, `<bds-drawer>`, `<bds-dropdown-menu>`, `<bds-dropdown-menu-item>`, `<bds-popover>`, `<bds-skip-link>`, `<bds-tab>`, `<bds-tab-panel>`, `<bds-tabs>`, `<bds-toast-provider>`, `<bds-tooltip>`
+- **interaction/form/**: `<bds-checkbox>`, `<bds-checkbox-group>`, `<bds-combobox>`, `<bds-file-input>`, `<bds-form-input>`, `<bds-number-input>`, `<bds-radio>`, `<bds-radio-group>`, `<bds-segmented-control>`, `<bds-select>`, `<bds-slider>`, `<bds-switch>`, `<bds-textarea>`
 
-MDX docs live at `src/web-components/{ui,interaction}/Bds*.mdx` — one per component.
+**Not ported** (deferred): `Command` — depends on `cmdk` React library internals. Use `<bds-combobox>` as the web component alternative.
+
+Storybook stories live at `src/web-components/{ui,interaction,interaction/form}/Bds*.stories.tsx` (title path `'Web Components/{UI|Interaction|Form}/{Name}'`, tags `['!stable', 'experimental']`). Stories use a thin React wrapper to enable Storybook controls.
+
+MDX docs live at `src/web-components/{ui,interaction,interaction/form}/Bds*.mdx` — one per component.
+
+**Custom events in stories**: React 18 does NOT wire `onBdsClose` (or any `onBds*` prop) as a DOM event listener on custom elements — it sets it as a property, which is a no-op. Always use `addEventListener` via `ref` + `useEffect` to handle custom events from web components:
+
+```tsx
+const ref = React.useRef<HTMLElement>(null);
+React.useEffect(() => {
+  const el = ref.current;
+  if (!el) return;
+  const handler = () => setState(false);
+  el.addEventListener('bds-close', handler);
+  return () => el.removeEventListener('bds-close', handler);
+}, []);
+// then pass ref={ref} to React.createElement(...)
+```
+
+Also: never define story component functions inside a `render: () => { function Foo() {...} }` arrow — React treats each render as a new component type and unmounts/remounts it. Define them at module scope instead.
 
 ### React Native (alpha) — `src/components/**/*.native.tsx`
 Native implementations co-located with their web counterparts. Metro resolves them automatically.
@@ -202,6 +222,28 @@ References: https://developer.mozilla.org/en-US/docs/Web/Accessibility | https:/
 - **Backdrop token**: `var(--color_backdrop, rgb(0 0 0 / 50%))` — never hardcode rgba. (`--color_backdrop` is a library hook token, not a foundation token.)
 - **`bds-popover` Invoker Commands API**: `<button commandfor="<id>" command="--toggle|--open|--close">` declaratively controls the popover. Handled via a `command` event listener on the host (light DOM) in `connectedCallback`/`disconnectedCallback`. Use an arrow-function handler for stable `removeEventListener` reference.
 - **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
 

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
 ```