@boostdev/design-system-components 1.0.3 → 1.1.1

package/AGENTS.md

@@ -2,25 +2,56 @@
 
 ## What this package provides
 
-A framework-agnostic React component library built on top of `@boostdev/design-system-foundation`.
-All components use CSS Modules and consume design tokens from `@boostdev/design-system-foundation`.
-Zero extra runtime — bring your own CSS reset and token layer.
+A component library with three targets:
+- **React (web)** — CSS Modules, design tokens from `@boostdev/design-system-foundation`, full component suite
+- **Web Components** (experimental) — Lit-based custom elements, framework-agnostic, entry point `@boostdev/components/web-components`
+- **React Native** (alpha) — React Native primitives, JS token layer, Metro-resolved via `"react-native"` export condition
 
 ## Prerequisites
 
-Consumers must load the design system CSS before using these components:
+**React (web):** load design system CSS before using components:
 ```css
 @import '@boostdev/design-system-foundation/css';
 ```
-Or individual token layers. All component styles live inside `@layer component`.
+All component styles live inside `@layer component`.
+
+**Web Components:** import the bundle to register all custom elements:
+```js
+import '@boostdev/components/web-components';
+```
+
+**React Native:** wrap the app in `ThemeProvider` from `@boostdev/components/native/ThemeContext`. Metro resolves the native bundle automatically via the `"react-native"` export condition — no extra config needed.
 
 ## Component categories
 
+### React (web)
 - **ui/**: Accordion, Alert, Avatar, Badge, Breadcrumb, Calendar, Carousel, Collapsible, DescriptionList, Link, Loading, NotificationBanner, Pagination, Progress, ProgressCircle, Separator, Skeleton, SkipLink, Table, Tabs, Tooltip, Typography
 - **interaction/**: Button, Command, Dialog, Drawer, DropdownMenu, Popover, Rating, Toast (ToastProvider + useToast hook)
 - **interaction/form/**: Checkbox, CheckboxGroup, Combobox, FileInput, FormInput, NumberInput, Radio, RadioGroup, SegmentedControl, Select, Slider, Switch, Textarea (+ atom primitives: Label, Message, InputContainer)
 - **layout/**: ButtonGroup, Card, IconWrapper, SectionHeader
 
+### 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.
+
+MDX docs live at `src/web-components/{ui,interaction}/Bds*.mdx` — one per component.
+
+### React Native (alpha) — `src/components/**/*.native.tsx`
+Native implementations co-located with their web counterparts. Metro resolves them automatically.
+- **ui/**: Typography, Badge, Avatar, Alert, NotificationBanner, Progress, Skeleton, Loading, Separator
+- **layout/**: Card, SectionHeader, ButtonGroup, IconWrapper
+- **interaction/**: Button
+- **interaction/form/**: Checkbox, Radio, Switch + atoms (Label, Message)
+
+Storybook stories: `src/components/**/*.native.stories.tsx` (title `'React Native/{UI|Interaction|Form|Layout}/{Name}'`, tags `['!stable', 'alpha']`). All stories wrap in `<ThemeProvider>` decorator.
+
+MDX docs: `src/components/**/*.native.mdx` — one per component.
+
+React Native overview: `src/stories/ReactNative.mdx`.
+
 ## Styling conventions
 
 - CSS Modules (`.module.css`) for all components — styles are scoped, no global leakage
@@ -28,6 +59,14 @@ Or individual token layers. All component styles live inside `@layer component`.
 - Variant classes follow the pattern `--{variant}` or `--{group}_{variant}` matching the source
 - Component-level CSS custom properties (e.g. `--button_bg`) can be overridden from a parent
 - Never hardcode colours, spacing, or typography values — always use design tokens
+- **Logical properties** — always use CSS logical properties instead of physical direction properties:
+  - `inline-size` / `block-size` instead of `width` / `height`
+  - `inset-block-start` / `inset-block-end` / `inset-inline-start` / `inset-inline-end` instead of `top` / `bottom` / `left` / `right`
+  - `margin-block-start` / `margin-block-end` / `margin-inline-start` / `margin-inline-end` instead of `margin-top` etc.
+  - `padding-block-*` / `padding-inline-*` instead of `padding-top` etc.
+  - `border-block-*` / `border-inline-*` instead of `border-top` / `border-bottom` / `border-left` / `border-right`
+  - `overflow-inline` / `overflow-block` instead of `overflow-x` / `overflow-y`
+  - Exceptions: `transform: translate*()` (geometric), SVG intrinsic dimensions, CSS Anchor Positioning `@position-try` blocks (API requires physical keywords)
 
 ### Component CSS variable pattern
 
@@ -83,7 +122,7 @@ Components that express an active, checked, or filled state use a two-level chai
 /* component var → global semantic token */
 background-color: var(--checkbox_color-active, var(--bds-color_green));
 border-color:     var(--checkbox_color-active, var(--bds-color_green));
-border: solid     var(--checkbox_color-on-active, var(--bds-on-active));
+border: solid     var(--checkbox_color-on-active, var(--bdc-color_on-active));
 ```
 
 Apply this pattern to any component with a visually distinct active/selected/filled state (checkboxes, radio buttons, sliders, progress bars, switch thumbs, etc.).
@@ -104,10 +143,10 @@ Prefer semantic tokens over palette tokens. Key tokens for component states:
 
 | Token | Meaning | Used in |
 |-------|---------|---------|
-| `--bds-color_green` | Active / checked / filled state | Checkbox, Radio, Slider, Progress, ProgressCircle |
-| `--bds-color_on-green` | Content on `--bds-color_green` | Checkbox tick, Radio inner dot |
-| `--bds-color_green--subtle` | Subtle background for active track | Switch (`--switch_track-bg--active`) |
-| `--bds-color_green--strong` | Strong foreground for active thumb | Switch (`--switch_thumb-bg--active`) |
+| `--bdc-color_active` | Active / checked / filled state (= `--bds-color_green` by default) | Checkbox, Radio, Slider, Progress, ProgressCircle |
+| `--bdc-color_on-active` | Content on active background | Checkbox tick, Radio inner dot |
+| `--bdc-color_active--subtle` | Subtle active background | Switch track when on |
+| `--bdc-color_active--strong` | Strong active foreground | Switch thumb when on |
 | `--bds-color_success--subtle` | Subtle background for success variant | Alert, NotificationBanner |
 | `--bds-color_on-success--subtle` | Text on success subtle background | Alert, NotificationBanner |
 | `--bds-color_interactive` | Focus ring colour | All focusable inputs |
@@ -158,6 +197,8 @@ References: https://developer.mozilla.org/en-US/docs/Web/Accessibility | https:/
 - **`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.
 - **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.
 
 ## Adding new components