@boostdev/design-system-components 1.2.0 → 1.2.1

package/src/web-components/interaction/BdsSkipLink.stories.tsx

@@ -1,9 +1,20 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
-import '../index';
+import '../index'; // auto-registers all custom elements
 
-function BdsSkipLink({ href, children }: { href?: string; children?: React.ReactNode }) {
-  return React.createElement('bds-skip-link', { href }, children);
+// Thin React wrapper so Storybook controls work with the custom element's props
+function BdsSkipLink({
+  href = '#main',
+  children,
+}: {
+  href?: string;
+  children?: React.ReactNode;
+}) {
+  return React.createElement(
+    'bds-skip-link',
+    { href },
+    children,
+  );
 }
 
 const meta = {
@@ -11,45 +22,47 @@ const meta = {
   component: BdsSkipLink,
   tags: ['!stable', 'experimental'],
   parameters: { layout: 'padded' },
+  argTypes: {
+    href: { control: 'text' },
+  },
 } satisfies Meta<typeof BdsSkipLink>;
 
 export default meta;
 type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {
-  render: () => (
-    <div style={{ position: 'relative', minHeight: '80px', border: '1px dashed #ccc', padding: '8px' }}>
-      <p style={{ margin: '0 0 8px', fontSize: '0.75rem', color: '#888' }}>
-        Tab into this area to reveal the skip link
-      </p>
-      <BdsSkipLink href="#main">Skip to main content</BdsSkipLink>
-      <p style={{ margin: '8px 0 0', fontSize: '0.875rem' }}>Press Tab to focus the skip link above</p>
-    </div>
-  ),
-};
-
-export const CustomTarget: Story = {
-  render: () => (
-    <div style={{ position: 'relative', minHeight: '80px' }}>
-      <BdsSkipLink href="#main-content">Skip to main content</BdsSkipLink>
-    </div>
-  ),
-};
-
-export const CustomLabel: Story = {
-  render: () => (
-    <div style={{ position: 'relative', minHeight: '80px' }}>
-      <BdsSkipLink href="#content">Jump to content</BdsSkipLink>
-    </div>
-  ),
+  args: { href: '#main' },
+  // Hint to the viewer that the link is visually hidden until focused
+  decorators: [
+    (Story) => (
+      <div>
+        <p style={{ marginBottom: '0.5rem', fontSize: '0.875rem', color: 'var(--bds-color_on-bg, #333)' }}>
+          Tab into the preview to see the skip link appear.
+        </p>
+        <Story />
+        <main id="main" style={{ marginTop: '1rem', padding: '1rem', border: '1px dashed currentcolor' }}>
+          Main content area
+        </main>
+      </div>
+    ),
+  ],
 };
 
-export const AllVariants: Story = {
-  render: () => (
-    <div style={{ position: 'relative', minHeight: '120px', display: 'flex', flexDirection: 'column', gap: '8px' }}>
-      <p style={{ margin: 0, fontSize: '0.75rem', color: '#888' }}>Tab to reveal — visually hidden until focused</p>
-      <BdsSkipLink href="#main">Skip to main content</BdsSkipLink>
-      <BdsSkipLink href="#nav">Skip to navigation</BdsSkipLink>
+export const WithCustomLabel: Story = {
+  args: { href: '#content' },
+  render: (args) => (
+    <div>
+      <p style={{ marginBottom: '0.5rem', fontSize: '0.875rem', color: 'var(--bds-color_on-bg, #333)' }}>
+        Tab into the preview to see the skip link appear.
+      </p>
+      {React.createElement(
+        'bds-skip-link',
+        { href: args.href },
+        'Skip to main content',
+      )}
+      <main id="content" style={{ marginTop: '1rem', padding: '1rem', border: '1px dashed currentcolor' }}>
+        Main content area
+      </main>
     </div>
   ),
 };

package/src/web-components/interaction/BdsTabs.mdx

@@ -3,45 +3,115 @@ import * as Stories from './BdsTabs.stories';
 
 <Meta of={Stories} />
 
-# Tabs
+# &lt;bds-tabs&gt;
 
-`<bds-tabs>` provides a tabbed interface. Place `<bds-tab>` elements in the `tab` slot and matching `<bds-tab-panel>` elements in the `panel` slot. Tabs and panels are associated by order.
+Framework-agnostic Tabs custom element. Coordinates `<bds-tab>` and `<bds-tab-panel>` children by DOM order, with full keyboard navigation.
 
-## Usage
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+Or in HTML without a bundler:
 
 ```html
-<bds-tabs>
-  <bds-tab slot="tab">Overview</bds-tab>
-  <bds-tab slot="tab">Details</bds-tab>
-  <bds-tab-panel slot="panel">
-    <p>Overview content.</p>
-  </bds-tab-panel>
-  <bds-tab-panel slot="panel">
-    <p>Details content.</p>
-  </bds-tab-panel>
-</bds-tabs>
+<script type="module">
+  import '@boostdev/components/web-components';
+</script>
 ```
 
-## Attributes — `<bds-tab>`
+## When to use
 
-| Attribute  | Type      | Default | Description               |
-|------------|-----------|---------|---------------------------|
-| `disabled` | `boolean` | `false` | Prevents selecting this tab |
+- Organising related content into sections when only one section is shown at a time
+- Switching between views at the same level of hierarchy
 
-## Keyboard Navigation
+## When not to use
 
-| Key         | Action                  |
-|-------------|-------------------------|
-| `ArrowLeft` | Move to previous tab    |
-| `ArrowRight`| Move to next tab        |
-| `Home`      | Move to first tab       |
-| `End`       | Move to last tab        |
+- For navigation between pages — use `<a>` links or a router
+- When all sections should be visible at once — use an accordion or separate sections
 
-## Stories
+## Examples
 
+### Default
 <Canvas of={Stories.Default} />
-<Canvas of={Stories.AllVariants} />
 
-## Controls
+### With disabled tab
+<Canvas of={Stories.WithDisabledTab} />
+
+### Many tabs
+<Canvas of={Stories.ManyTabs} />
+
+## Props
 
 <ArgTypes of={Stories} />
+
+## Attributes — `<bds-tabs>`
+
+`<bds-tabs>` has no configurable attributes. Tab state and active index are managed internally.
+
+## Attributes — `<bds-tab>`
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `disabled` | boolean | `false` | Prevents the tab from being selected; tab is skipped during keyboard navigation |
+| `selected` | boolean | `false` | Set by the parent `<bds-tabs>`; do not set manually |
+
+## Slots
+
+### `<bds-tabs>`
+
+| Slot | Description |
+|------|-------------|
+| `tab` | `<bds-tab>` elements — rendered in the tab list |
+| `panel` | `<bds-tab-panel>` elements — rendered below the tab list |
+
+### `<bds-tab>`
+
+| Slot | Description |
+|------|-------------|
+| `(default)` | Tab label text |
+
+### `<bds-tab-panel>`
+
+| Slot | Description |
+|------|-------------|
+| `(default)` | Panel content displayed when the corresponding tab is selected |
+
+## Events
+
+| Event | Fired by | Bubbles | Description |
+|-------|----------|---------|-------------|
+| `bds-tab-select` | `<bds-tab>` | Yes | Fired when a tab is clicked; handled internally by `<bds-tabs>` |
+
+## Usage in plain HTML
+
+Tabs and panels are matched by DOM order (first tab → first panel, etc.):
+
+```html
+<bds-tabs>
+  <bds-tab slot="tab">Overview</bds-tab>
+  <bds-tab slot="tab">Details</bds-tab>
+  <bds-tab slot="tab" disabled>Disabled</bds-tab>
+
+  <bds-tab-panel slot="panel">
+    <p>Overview content</p>
+  </bds-tab-panel>
+  <bds-tab-panel slot="panel">
+    <p>Details content</p>
+  </bds-tab-panel>
+  <bds-tab-panel slot="panel">
+    <p>Disabled tab content (unreachable)</p>
+  </bds-tab-panel>
+</bds-tabs>
+```
+
+## Accessibility
+
+- The tab list container has `role="tablist"`
+- Each `<bds-tab>` renders a `<button role="tab">` with `aria-selected` and the correct `tabindex` (0 for active, -1 for others)
+- Each `<bds-tab-panel>` receives `hidden` when not active
+- Keyboard navigation: ArrowRight / ArrowLeft cycles through enabled tabs; Home / End jumps to first / last enabled tab
+- Disabled tabs are excluded from keyboard navigation

package/src/web-components/interaction/BdsTabs.stories.tsx

@@ -1,80 +1,94 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
-import '../index';
+import '../index'; // auto-registers all custom elements
 
-function TabsDemo({ withDisabled = false }: { withDisabled?: boolean }) {
+// Thin React wrapper so Storybook controls work with the custom element's props
+function BdsTabs({
+  tabs = ['Overview', 'Details', 'Settings'],
+  panels = ['Overview content.', 'Details content.', 'Settings content.'],
+}: {
+  tabs?: string[];
+  panels?: string[];
+}) {
   return React.createElement(
     'bds-tabs',
     null,
-    React.createElement('bds-tab', { slot: 'tab' }, 'Overview'),
-    React.createElement('bds-tab', { slot: 'tab' }, 'Details'),
-    withDisabled
-      ? React.createElement('bds-tab', { slot: 'tab', disabled: true }, 'Disabled')
-      : React.createElement('bds-tab', { slot: 'tab' }, 'Settings'),
-    React.createElement(
-      'bds-tab-panel',
-      { slot: 'panel' },
-      React.createElement('p', { style: { margin: 0 } }, 'Overview content — general information about this item.'),
-    ),
-    React.createElement(
-      'bds-tab-panel',
-      { slot: 'panel' },
-      React.createElement('p', { style: { margin: 0 } }, 'Details content — technical specifications and metadata.'),
+    ...tabs.map(label =>
+      React.createElement('bds-tab', { key: label, slot: 'tab' }, label),
     ),
-    React.createElement(
-      'bds-tab-panel',
-      { slot: 'panel' },
-      withDisabled
-        ? React.createElement('p', { style: { margin: 0 } }, 'Disabled tab content.')
-        : React.createElement('p', { style: { margin: 0 } }, 'Settings content — configuration options.'),
+    ...panels.map((content, i) =>
+      React.createElement(
+        'bds-tab-panel',
+        { key: i, slot: 'panel' },
+        React.createElement('p', { style: { margin: 0 } }, content),
+      ),
     ),
   );
 }
 
-// Thin wrapper so Storybook controls work
-function BdsTabs({ withDisabled }: { withDisabled?: boolean }) {
-  return React.createElement(TabsDemo, { withDisabled });
-}
-
 const meta = {
   title: 'Web Components/Interaction/Tabs',
   component: BdsTabs,
   tags: ['!stable', 'experimental'],
   parameters: { layout: 'padded' },
-  argTypes: {
-    withDisabled: { control: 'boolean' },
-  },
 } satisfies Meta<typeof BdsTabs>;
 
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-export const Default: Story = { args: { withDisabled: false } };
-export const WithDisabledTab: Story = { args: { withDisabled: true } };
+export const Default: Story = {
+  args: {
+    tabs: ['Overview', 'Details', 'Settings'],
+    panels: [
+      'Overview content. Use tabs to divide related content into sections.',
+      'Details content. Each tab maps to a panel by DOM order.',
+      'Settings content. Navigate with ArrowLeft / ArrowRight keys.',
+    ],
+  },
+};
 
-export const AllVariants: Story = {
-  render: () => (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: '32px' }}>
-      <div>
-        <p style={{ margin: '0 0 8px', fontSize: '0.75rem', color: '#888', fontWeight: 600 }}>Standard tabs</p>
-        <TabsDemo />
-      </div>
-      <div>
-        <p style={{ margin: '0 0 8px', fontSize: '0.75rem', color: '#888', fontWeight: 600 }}>With disabled tab</p>
-        <TabsDemo withDisabled />
-      </div>
-    </div>
-  ),
+export const WithDisabledTab: Story = {
+  render: () =>
+    React.createElement(
+      'bds-tabs',
+      null,
+      React.createElement('bds-tab', { slot: 'tab' }, 'Active'),
+      React.createElement('bds-tab', { slot: 'tab', disabled: '' }, 'Disabled'),
+      React.createElement('bds-tab', { slot: 'tab' }, 'Another'),
+      React.createElement(
+        'bds-tab-panel',
+        { slot: 'panel' },
+        React.createElement('p', { style: { margin: 0 } }, 'Content for the first tab.'),
+      ),
+      React.createElement(
+        'bds-tab-panel',
+        { slot: 'panel' },
+        React.createElement('p', { style: { margin: 0 } }, 'This panel is paired with the disabled tab.'),
+      ),
+      React.createElement(
+        'bds-tab-panel',
+        { slot: 'panel' },
+        React.createElement('p', { style: { margin: 0 } }, 'Content for the third tab.'),
+      ),
+    ),
 };
 
-export const Interactive: Story = {
-  name: 'Interactive (keyboard nav)',
-  render: () => (
-    <div>
-      <p style={{ margin: '0 0 12px', fontSize: '0.875rem', color: '#666' }}>
-        Use ArrowLeft / ArrowRight to navigate between tabs. Home / End jump to first / last.
-      </p>
-      <TabsDemo />
-    </div>
-  ),
+export const ManyTabs: Story = {
+  render: () => {
+    const labels = ['Dashboard', 'Reports', 'Users', 'Billing', 'Integrations'];
+    return React.createElement(
+      'bds-tabs',
+      null,
+      ...labels.map(label =>
+        React.createElement('bds-tab', { key: label, slot: 'tab' }, label),
+      ),
+      ...labels.map((label, i) =>
+        React.createElement(
+          'bds-tab-panel',
+          { key: i, slot: 'panel' },
+          React.createElement('p', { style: { margin: 0 } }, `${label} content area.`),
+        ),
+      ),
+    );
+  },
 };

package/src/web-components/interaction/BdsTooltip.mdx

@@ -3,36 +3,102 @@ import * as Stories from './BdsTooltip.stories';
 
 <Meta of={Stories} />
 
-# Tooltip
+# &lt;bds-tooltip&gt;
 
-`<bds-tooltip>` wraps any trigger element and shows a floating tooltip on hover and focus. The tooltip is dismissed on mouse-out and blur.
+Framework-agnostic Tooltip custom element. Displays a small informational label on hover and keyboard focus using CSS-only visibility — no JavaScript positioning required.
 
-## Usage
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+Or in HTML without a bundler:
 
 ```html
-<bds-tooltip content="Save changes" placement="top">
-  <button type="button">Save</button>
-</bds-tooltip>
+<script type="module">
+  import '@boostdev/components/web-components';
+</script>
 ```
 
-## Attributes
+## When to use
 
-| Attribute   | Type                                    | Default  | Description                      |
-|-------------|-----------------------------------------|----------|----------------------------------|
-| `content`   | `string`                                | `""`     | Tooltip text                     |
-| `placement` | `"top" \| "bottom" \| "left" \| "right"` | `"top"`  | Preferred tooltip placement      |
+- Labelling icon-only buttons that have no visible text
+- Providing supplementary information for a UI element without cluttering the layout
+- Short, non-interactive hints (a single sentence or less)
 
-## Slots
+## When not to use
 
-| Slot      | Description                        |
-|-----------|------------------------------------|
-| (default) | The trigger element for the tooltip |
+- For interactive content (links, buttons inside the tooltip) — use `<bds-popover>` instead
+- For error messages or validation feedback — use an inline message
+- For content longer than a short phrase — use `<bds-popover>` or a disclosure pattern
 
-## Stories
+## Examples
 
-<Canvas of={Stories.Top} />
+### Default
+<Canvas of={Stories.Default} />
+
+### On a button
+<Canvas of={Stories.OnButton} />
+
+### Bottom placement
+<Canvas of={Stories.Bottom} />
+
+### Left placement
+<Canvas of={Stories.Left} />
+
+### Right placement
+<Canvas of={Stories.Right} />
+
+### All placements
 <Canvas of={Stories.AllPlacements} />
 
-## Controls
+## Props
 
 <ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `content` | string | `""` | Text to display inside the tooltip |
+| `placement` | `"top" \| "bottom" \| "left" \| "right"` | `"top"` | Where the tooltip appears relative to the trigger |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `(default)` | The trigger element (button, icon, etc.) that the tooltip is anchored to |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--tooltip_bg` | Tooltip background colour (default: `var(--bds-color_on-bg)`) |
+| `--tooltip_text` | Tooltip text colour (default: `var(--bds-color_bg)`) |
+
+## Usage in plain HTML
+
+```html
+<bds-tooltip content="Save your changes" placement="top">
+  <button type="button">Save</button>
+</bds-tooltip>
+
+<!-- Icon-only button with tooltip label -->
+<bds-tooltip content="Delete item" placement="bottom">
+  <button type="button" aria-label="Delete item">
+    <!-- icon SVG -->
+  </button>
+</bds-tooltip>
+```
+
+## Accessibility
+
+- The tooltip panel has `role="tooltip"`
+- Visibility is controlled by `:hover` and `:focus-within` — no JavaScript required
+- The tooltip is rendered adjacent to the trigger inside the same shadow root, so screen readers can read it via proximity
+- Note: `aria-describedby` cannot cross shadow DOM boundaries; if your project requires explicit ARIA association, use `<bds-popover>` instead
+- `pointer-events: none` on the tooltip prevents it from interfering with mouse events
+- Fade transition respects `prefers-reduced-motion`

package/src/web-components/interaction/BdsTooltip.stories.tsx

@@ -1,11 +1,12 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
 import type { TooltipPlacement } from './bds-tooltip';
-import '../index';
+import '../index'; // auto-registers all custom elements
 
+// Thin React wrapper so Storybook controls work with the custom element's props
 function BdsTooltip({
-  content,
-  placement,
+  content = 'Tooltip text',
+  placement = 'top',
   children,
 }: {
   content?: string;
@@ -25,6 +26,7 @@ const meta = {
   tags: ['!stable', 'experimental'],
   parameters: { layout: 'centered' },
   argTypes: {
+    content: { control: 'text' },
     placement: { control: 'select', options: ['top', 'bottom', 'left', 'right'] },
   },
 } satisfies Meta<typeof BdsTooltip>;
@@ -32,37 +34,54 @@ const meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-export const Top: Story = { args: { content: 'Tooltip on top', placement: 'top' } };
-export const Bottom: Story = { args: { content: 'Tooltip on bottom', placement: 'bottom' } };
-export const Left: Story = { args: { content: 'Tooltip on left', placement: 'left' } };
-export const Right: Story = { args: { content: 'Tooltip on right', placement: 'right' } };
+export const Default: Story = {
+  args: { content: 'Tooltip text', placement: 'top' },
+};
 
-export const AllPlacements: Story = {
-  render: () => (
-    <div style={{ display: 'grid', gridTemplateColumns: 'repeat(2, auto)', gap: '64px', padding: '48px' }}>
-      {(['top', 'bottom', 'left', 'right'] as const).map(p => (
-        <div key={p} style={{ display: 'flex', justifyContent: 'center', alignItems: 'center' }}>
-          <BdsTooltip content={`Placed ${p}`} placement={p}>
-            <button type="button">{p}</button>
-          </BdsTooltip>
-        </div>
-      ))}
-    </div>
-  ),
+export const OnButton: Story = {
+  args: { content: 'Save your changes', placement: 'top' },
+  render: (args) =>
+    React.createElement(
+      'bds-tooltip',
+      { content: args.content, placement: args.placement },
+      React.createElement(
+        'button',
+        { type: 'button', style: { padding: '0.5rem 1rem', cursor: 'pointer' } },
+        'Save',
+      ),
+    ),
+};
+
+export const Bottom: Story = {
+  args: { content: 'Appears below', placement: 'bottom' },
+};
+
+export const Left: Story = {
+  args: { content: 'Appears to the left', placement: 'left' },
 };
 
-export const AllVariants: Story = {
+export const Right: Story = {
+  args: { content: 'Appears to the right', placement: 'right' },
+};
+
+export const AllPlacements: Story = {
   render: () => (
-    <div style={{ display: 'flex', gap: '32px', flexWrap: 'wrap', padding: '32px' }}>
-      <BdsTooltip content="A helpful tip" placement="top">
-        <button type="button">Info button</button>
-      </BdsTooltip>
-      <BdsTooltip content="Delete this item" placement="bottom">
-        <button type="button">Delete</button>
-      </BdsTooltip>
-      <BdsTooltip content="Opens in new tab" placement="right">
-        <button type="button">External link</button>
-      </BdsTooltip>
+    <div style={{ display: 'grid', gridTemplateColumns: 'repeat(2, auto)', gap: '4rem', padding: '3rem' }}>
+      {(['top', 'bottom', 'left', 'right'] as const).map(placement =>
+        React.createElement(
+          'div',
+          { key: placement, style: { display: 'flex', justifyContent: 'center', alignItems: 'center' } },
+          React.createElement(
+            'bds-tooltip',
+            { content: `Placement: ${placement}`, placement },
+            React.createElement(
+              'button',
+              { type: 'button', style: { padding: '0.5rem 1rem', cursor: 'pointer' } },
+              placement,
+            ),
+          ),
+        ),
+      )}
     </div>
   ),
 };

package/src/web-components/interaction/bds-collapsible.ts

@@ -91,6 +91,7 @@ export class BdsCollapsible extends LitElement {
 
     .content {
       padding: var(--bds-space_m);
+      background-color: var(--collapsible_content-bg, var(--bds-color_bg));
       color: var(--collapsible_on-color, var(--bds-color_on-bg));
       font-size: var(--bds-font_size--body);
       line-height: var(--bds-font_line-height--body);