@boostdev/design-system-components 1.1.2 → 1.2.1

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.
@@ -92,7 +112,7 @@ For **border colours** that should match surrounding text/icon colour, use `curr
 
 ### bdc border tokens
 
-Components use `outline` (not `border`) for all visual frame edges via `--bdc_*` tokens defined in `src/css/bdc.css`. Set local values on the component rule:
+Components use `box-shadow: inset` (not `outline` or `border`) for all visual frame edges via `--bdc_*` tokens defined in `src/css/bdc.css`. This keeps `outline` exclusively for `:focus-visible` rings. Set local values on the component rule:
 
 ```css
 .myElement {
@@ -100,19 +120,22 @@ Components use `outline` (not `border`) for all visual frame edges via `--bdc_*`
   --bdc_color: currentcolor;
   --bdc-outline_radius: var(--bds-border_radius--xs);
 
-  outline: var(--bdc-outline_width) solid var(--bdc_color);
-  outline-offset: var(--bdc-outline_offset);
   border-radius: var(--myComponent_radius, var(--bdc-outline_radius));
-  box-shadow: var(--myComponent_shadow, var(--bdc-outline_shadow));
+  box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color),
+              var(--myComponent_shadow, var(--bdc-outline_shadow));
   transition: --bdc_color var(--bds-animation_transition-duration) var(--bds-animation_easing);
 }
 
-.myElement:focus {
-  --bdc_color: var(--bdc_color--focus); /* transitions smoothly */
+.myElement:focus-visible {
+  outline: var(--bds-outline_default);
+  outline-offset: var(--bds-outline_offset);
 }
 ```
 
-Focus state uses `--bdc_color--focus` (= `--bds-color_interactive`) for mouse focus, and `var(--bds-outline_default)` for `:focus-visible` keyboard focus.
+- The `--bdc_color` `<color>` registered property enables smooth CSS transitions on the inset shadow colour.
+- The neutral shadow default is `0 0 0 0 transparent` — `none` is invalid in a comma-separated `box-shadow` list.
+- `:focus-visible` always uses `outline` + `var(--bds-outline_default)` (never the inset shadow).
+- Focus rings use `--bds-outline_default` (2 px solid interactive colour, 2 px offset) — defined in `src/css/bdc.css`.
 
 ### Two-level fallback for active/selected state
 
@@ -192,13 +215,14 @@ References: https://developer.mozilla.org/en-US/docs/Web/Accessibility | https:/
 
 ## Key decisions
 
-- **Button variants**: `default` (filled) and `ghost` (transparent, outlined). Renamed from `primary`/`secondary`.
+- **Button variants**: `default` (filled) and `outline` (transparent, outlined). `ghost` is a deprecated alias for `outline` — use `outline` for new code.
 - **Button colour model**: `--button_color` + `--button_on-color` are the two theming inputs. All other button CSS vars derive from these.
-- **`bdc` border token system**: All component frame borders use `outline` (not `border`) via `--bdc_color`, `--bdc-outline_width`, `--bdc-outline_offset`, `--bdc-outline_radius`, `--bdc-outline_shadow` custom properties registered with `@property`. Default `border: none`. The `--bdc_color` `<color>` registration enables smooth CSS transitions on focus/error state changes without JavaScript.
-- **`--bdc-outline_offset: -1px`** (inset) makes outline appear like a traditional inset border. Switch uses `var(--bds-outline_offset)` (2px outside) — keep distinct.
+- **`bdc` border token system**: All component frame borders use `box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color)` (not `outline` or `border`). `outline` is reserved exclusively for `:focus-visible` rings. `--bdc_color` is registered as `<color>` with `@property`, enabling smooth `transition: --bdc_color` animations. The neutral `--bdc-outline_shadow` default is `0 0 0 0 transparent` (not `none` — `none` breaks comma-separated box-shadow).
+- **Focus rings**: all components use `outline: var(--bds-outline_default)` + `outline-offset: var(--bds-outline_offset)` on `:focus-visible`. The `--bds-outline_default` is overridden in `bdc.css` to `2px solid var(--bds-color_interactive)` at 2px offset.
 - **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`.
 
 ## Adding new components