@boostdev/design-system-components 1.2.0 → 1.2.1

package/src/web-components/ui/BdsSeparator.stories.tsx

@@ -1,8 +1,12 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
-import '../index';
+import '../index'; // auto-registers all custom elements
 
-function BdsSeparator({ orientation }: { orientation?: 'horizontal' | 'vertical' }) {
+function BdsSeparator({
+  orientation = 'horizontal',
+}: {
+  orientation?: 'horizontal' | 'vertical';
+}) {
   return React.createElement('bds-separator', { orientation });
 }
 
@@ -12,36 +16,40 @@ const meta = {
   tags: ['!stable', 'experimental'],
   parameters: { layout: 'centered' },
   argTypes: {
-    orientation: { control: 'select', options: ['horizontal', 'vertical'] },
+    orientation: { control: 'radio', options: ['horizontal', 'vertical'] },
   },
 } satisfies Meta<typeof BdsSeparator>;
 
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-export const Horizontal: Story = { args: { orientation: 'horizontal' } };
+export const Default: Story = {
+  args: { orientation: 'horizontal' },
+  render: ({ orientation }) => (
+    <div style={{ width: 300 }}>
+      <p style={{ margin: 0 }}>Above the separator</p>
+      {React.createElement('bds-separator', { orientation })}
+      <p style={{ margin: 0 }}>Below the separator</p>
+    </div>
+  ),
+};
 
-export const Vertical: Story = {
+export const Horizontal: Story = {
   render: () => (
-    <div style={{ display: 'flex', alignItems: 'center', gap: '16px', height: '40px' }}>
-      <span>Left</span>
-      <BdsSeparator orientation="vertical" />
-      <span>Right</span>
+    <div style={{ width: 300 }}>
+      <p style={{ margin: 0 }}>First section</p>
+      {React.createElement('bds-separator', { orientation: 'horizontal' })}
+      <p style={{ margin: 0 }}>Second section</p>
     </div>
   ),
 };
 
-export const AllVariants: Story = {
+export const Vertical: Story = {
   render: () => (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px', width: '300px' }}>
-      <p style={{ margin: 0 }}>Content above horizontal separator</p>
-      <BdsSeparator orientation="horizontal" />
-      <p style={{ margin: 0 }}>Content below</p>
-      <div style={{ display: 'flex', alignItems: 'center', gap: '16px', height: '40px' }}>
-        <span>Left</span>
-        <BdsSeparator orientation="vertical" />
-        <span>Right</span>
-      </div>
+    <div style={{ display: 'flex', alignItems: 'center', gap: 12, height: 40 }}>
+      <span>Left</span>
+      {React.createElement('bds-separator', { orientation: 'vertical' })}
+      <span>Right</span>
     </div>
   ),
 };

package/src/web-components/ui/BdsSkeleton.mdx

@@ -5,7 +5,7 @@ import * as Stories from './BdsSkeleton.stories';
 
 # <bds-skeleton>
 
-Framework-agnostic Skeleton loading placeholder. Shows a shimmer animation while content is loading. Size is set via inline `style` or container CSS — the element inherits its dimensions from the surrounding layout.
+Framework-agnostic Skeleton loading placeholder custom element. Displays an animated shimmer while real content is loading. Size is set via inline styles or CSS on the host element.
 
 > **Status: experimental** — API may change before stable release.
 
@@ -15,19 +15,24 @@ Framework-agnostic Skeleton loading placeholder. Shows a shimmer animation while
 import '@boostdev/components/web-components';
 ```
 
+## When to use
+
+- While fetching data, replace text, images, and cards with skeleton placeholders to reduce perceived loading time
+- Match the shape of the final content as closely as possible
+
 ## Examples
 
-### Card layout skeleton
-<Canvas of={Stories.AllVariants} />
+### Default
+<Canvas of={Stories.Default} />
 
-### Text line
-<Canvas of={Stories.TextLine} />
+### Heading placeholder
+<Canvas of={Stories.Heading} />
 
 ### Avatar placeholder
 <Canvas of={Stories.Avatar} />
 
-### Card placeholder
-<Canvas of={Stories.Card} />
+### Content block
+<Canvas of={Stories.ContentBlock} />
 
 ## Props
 
@@ -35,33 +40,22 @@ import '@boostdev/components/web-components';
 
 ## Attributes
 
-This element has no attributes. Control dimensions via `style` or a CSS class on the host.
-
-## CSS Custom Properties
-
-The shimmer animation uses design tokens directly:
-
-| Token | Description |
-|-------|-------------|
-| `--bds-color_grey--subtle` | Shimmer base colour |
-| `--bds-color_bg` | Shimmer highlight colour |
-| `--bds-border_radius--xs` | Default corner radius |
+`<bds-skeleton>` has no custom attributes. Size is controlled via inline styles or CSS.
 
 ## Usage in plain HTML
 
 ```html
-<!-- Text line -->
+<!-- Inline text placeholder -->
 <bds-skeleton style="width: 200px; height: 1rem;"></bds-skeleton>
 
-<!-- Avatar -->
-<bds-skeleton style="width: 3rem; height: 3rem; border-radius: 50%;"></bds-skeleton>
+<!-- Heading placeholder -->
+<bds-skeleton style="width: 300px; height: 2rem;"></bds-skeleton>
 
-<!-- Card block -->
-<bds-skeleton style="width: 280px; height: 160px;"></bds-skeleton>
+<!-- Avatar placeholder -->
+<bds-skeleton style="width: 48px; height: 48px; border-radius: 50%;"></bds-skeleton>
 ```
 
 ## Accessibility
 
-- Hidden from assistive technology via `aria-hidden="true"` — it is a purely visual placeholder
-- Pair with a live region or announce loading state through other means if necessary
-- Respects `prefers-reduced-motion`: shimmer animation is disabled for users who prefer reduced motion
+- The inner `<span>` carries `aria-hidden="true"` so screen readers skip the placeholder
+- Replace the skeleton with real content and a meaningful accessible label once loaded

package/src/web-components/ui/BdsSkeleton.stories.tsx

@@ -1,9 +1,10 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
-import '../index';
+import '../index'; // auto-registers all custom elements
 
-function BdsSkeleton({ style }: { style?: React.CSSProperties }) {
-  return React.createElement('bds-skeleton', { style });
+// bds-skeleton has no attributes — the wrapper just passes inline style
+function BdsSkeleton({ width = '200px', height = '1rem' }: { width?: string; height?: string }) {
+  return React.createElement('bds-skeleton', { style: `width: ${width}; height: ${height};` });
 }
 
 const meta = {
@@ -11,40 +12,39 @@ const meta = {
   component: BdsSkeleton,
   tags: ['!stable', 'experimental'],
   parameters: { layout: 'centered' },
+  argTypes: {
+    width:  { control: 'text' },
+    height: { control: 'text' },
+  },
 } satisfies Meta<typeof BdsSkeleton>;
 
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-export const TextLine: Story = {
-  render: () => <BdsSkeleton style={{ width: '200px', height: '1rem' }} />,
+export const Default: Story = {
+  args: { width: '200px', height: '1rem' },
 };
 
 export const Heading: Story = {
-  render: () => <BdsSkeleton style={{ width: '300px', height: '1.75rem' }} />,
+  args: { width: '300px', height: '2rem' },
 };
 
 export const Avatar: Story = {
-  render: () => <BdsSkeleton style={{ width: '3rem', height: '3rem', borderRadius: '50%' }} />,
-};
-
-export const Card: Story = {
-  render: () => <BdsSkeleton style={{ width: '280px', height: '160px' }} />,
+  args: { width: '48px', height: '48px' },
+  render: ({ width, height }) => (
+    <div style={{ borderRadius: '50%', overflow: 'hidden', display: 'inline-block', width, height }}>
+      {React.createElement('bds-skeleton', { style: `width: ${width}; height: ${height};` })}
+    </div>
+  ),
 };
 
-export const AllVariants: Story = {
+export const ContentBlock: Story = {
   render: () => (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: '12px', width: '280px' }}>
-      <div style={{ display: 'flex', alignItems: 'center', gap: '12px' }}>
-        <BdsSkeleton style={{ width: '3rem', height: '3rem', borderRadius: '50%', flexShrink: 0 }} />
-        <div style={{ display: 'flex', flexDirection: 'column', gap: '8px', flex: 1 }}>
-          <BdsSkeleton style={{ width: '100%', height: '1rem' }} />
-          <BdsSkeleton style={{ width: '60%', height: '0.75rem' }} />
-        </div>
-      </div>
-      <BdsSkeleton style={{ width: '100%', height: '120px' }} />
-      <BdsSkeleton style={{ width: '80%', height: '0.875rem' }} />
-      <BdsSkeleton style={{ width: '60%', height: '0.875rem' }} />
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 8, width: 300 }}>
+      {React.createElement('bds-skeleton', { style: 'width: 100%; height: 1.5rem;' })}
+      {React.createElement('bds-skeleton', { style: 'width: 80%; height: 1rem;' })}
+      {React.createElement('bds-skeleton', { style: 'width: 90%; height: 1rem;' })}
+      {React.createElement('bds-skeleton', { style: 'width: 60%; height: 1rem;' })}
     </div>
   ),
 };

package/src/web-components/ui/BdsTable.mdx

@@ -0,0 +1,81 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsTable.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-table&gt;
+
+Framework-agnostic scrollable Table wrapper custom element. Apply design-system styles to a standard `<table>` element by nesting it in the default slot.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## When to use
+
+- Displaying tabular data with design-system typography and colour tokens
+- Use `sticky-header` to keep `<thead>` visible when the table overflows vertically inside a fixed-height container
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### Sticky header
+<Canvas of={Stories.StickyHeader} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `sticky-header` | boolean | `false` | Freezes `<thead>` at the top when the table overflows vertically |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `(default)` | A standard `<table>` element with `<thead>` and `<tbody>` |
+
+## Usage in plain HTML
+
+```html
+<bds-table>
+  <table>
+    <thead>
+      <tr>
+        <th>Name</th>
+        <th>Role</th>
+        <th>Status</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td>Jane Doe</td>
+        <td>Designer</td>
+        <td>Active</td>
+      </tr>
+    </tbody>
+  </table>
+</bds-table>
+
+<!-- Sticky header in a scrollable container -->
+<div style="max-height: 300px; overflow: auto;">
+  <bds-table sticky-header>
+    <table>...</table>
+  </bds-table>
+</div>
+```
+
+## Accessibility
+
+- Use a standard `<table>` with proper `<thead>` / `<tbody>` structure
+- Column headers (`<th>`) are automatically styled; add `scope="col"` for complex tables
+- The wrapper is horizontally scrollable (`overflow-inline: auto`) on small viewports

package/src/web-components/ui/BdsTable.stories.tsx

@@ -0,0 +1,83 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../index'; // auto-registers all custom elements
+
+function BdsTable({
+  stickyHeader,
+  children,
+}: {
+  stickyHeader?: boolean;
+  children?: React.ReactNode;
+}) {
+  return React.createElement(
+    'bds-table',
+    { 'sticky-header': stickyHeader || undefined },
+    children,
+  );
+}
+
+const sampleTable = () =>
+  React.createElement(
+    'table',
+    null,
+    React.createElement(
+      'thead',
+      null,
+      React.createElement(
+        'tr',
+        null,
+        React.createElement('th', null, 'Name'),
+        React.createElement('th', null, 'Role'),
+        React.createElement('th', null, 'Department'),
+        React.createElement('th', null, 'Status'),
+      ),
+    ),
+    React.createElement(
+      'tbody',
+      null,
+      ...[
+        ['Alice Brown', 'Designer', 'Product', 'Active'],
+        ['Bob Smith', 'Engineer', 'Platform', 'Active'],
+        ['Carol White', 'Manager', 'Operations', 'Away'],
+        ['Dan Jones', 'Analyst', 'Data', 'Inactive'],
+      ].map(([name, role, dept, status]) =>
+        React.createElement(
+          'tr',
+          { key: name },
+          React.createElement('td', null, name),
+          React.createElement('td', null, role),
+          React.createElement('td', null, dept),
+          React.createElement('td', null, status),
+        ),
+      ),
+    ),
+  );
+
+const meta = {
+  title: 'Web Components/UI/Table',
+  component: BdsTable,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'fullscreen' },
+  argTypes: {
+    stickyHeader: { control: 'boolean' },
+  },
+} satisfies Meta<typeof BdsTable>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <div style={{ padding: 24 }}>
+      {React.createElement('bds-table', {}, sampleTable())}
+    </div>
+  ),
+};
+
+export const StickyHeader: Story = {
+  render: () => (
+    <div style={{ padding: 24, maxHeight: 200, overflow: 'auto' }}>
+      {React.createElement('bds-table', { 'sticky-header': true }, sampleTable())}
+    </div>
+  ),
+};

package/src/web-components/ui/BdsTypography.mdx

@@ -5,7 +5,7 @@ import * as Stories from './BdsTypography.stories';
 
 # <bds-typography>
 
-Framework-agnostic Typography custom element. Renders slotted content inside the appropriate semantic HTML element with the correct typographic styles.
+Framework-agnostic Typography custom element. Renders slotted text inside the appropriate semantic HTML element (`h1`–`h3`, `p`) based on the `variant` attribute, with optional tag override via `component`.
 
 > **Status: experimental** — API may change before stable release.
 
@@ -15,6 +15,11 @@ Framework-agnostic Typography custom element. Renders slotted content inside the
 import '@boostdev/components/web-components';
 ```
 
+## When to use
+
+- To apply design-system typography styles in non-React environments
+- When you need to override the rendered HTML tag while keeping the visual style
+
 ## Examples
 
 ### All variants
@@ -23,12 +28,21 @@ import '@boostdev/components/web-components';
 ### Heading 1
 <Canvas of={Stories.H1} />
 
+### Heading 2
+<Canvas of={Stories.H2} />
+
+### Heading 3
+<Canvas of={Stories.H3} />
+
 ### Body
 <Canvas of={Stories.Body} />
 
 ### Body small
 <Canvas of={Stories.BodySmall} />
 
+### Custom tag
+<Canvas of={Stories.CustomTag} />
+
 ## Props
 
 <ArgTypes of={Stories} />
@@ -37,7 +51,7 @@ import '@boostdev/components/web-components';
 
 | Attribute | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `variant` | `"h1" \| "h2" \| "h3" \| "body" \| "body_s"` | `"body"` | Typographic style and semantic element |
+| `variant` | `"h1" \| "h2" \| "h3" \| "body" \| "body_s"` | `"body"` | Visual style and default semantic tag |
 | `component` | string | — | Override the rendered HTML tag (e.g. `"span"`, `"label"`) |
 
 ## Slots
@@ -46,38 +60,15 @@ import '@boostdev/components/web-components';
 |------|-------------|
 | `(default)` | Text content |
 
-## Default tag mapping
-
-| Variant | Rendered tag |
-|---------|-------------|
-| `h1` | `<h1>` |
-| `h2` | `<h2>` |
-| `h3` | `<h3>` |
-| `body` | `<p>` |
-| `body_s` | `<p>` |
-
-## CSS Custom Properties
-
-| Property | Description |
-|----------|-------------|
-| `--typography_color` | Text colour (defaults to `--bds-color_on-bg`) |
-
 ## Usage in plain HTML
 
 ```html
 <bds-typography variant="h1">Page title</bds-typography>
-
-<bds-typography variant="body">
-  A paragraph of body text.
-</bds-typography>
-
-<!-- Override tag while keeping style -->
-<bds-typography variant="body_s" component="span">
-  Inline small text
-</bds-typography>
+<bds-typography variant="body">Regular paragraph text.</bds-typography>
+<bds-typography variant="body_s" component="span">Small helper text</bds-typography>
 ```
 
 ## Accessibility
 
-- Uses the correct semantic HTML element by default — always prefer semantic variants over overriding `component`
-- Use `component` only when the semantic element must differ from the visual style (e.g. a `<span>` styled as `body_s` inside a heading)
+- Uses semantic heading elements (`h1`–`h3`) or `<p>` by default
+- Override with `component` only when the semantic meaning differs from the visual style

package/src/web-components/ui/BdsTypography.stories.tsx

@@ -1,10 +1,10 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
 import type { TypographyVariant } from './bds-typography';
-import '../index';
+import '../index'; // auto-registers all custom elements
 
 function BdsTypography({
-  variant,
+  variant = 'body',
   component,
   children,
 }: {
@@ -19,33 +19,34 @@ const meta = {
   title: 'Web Components/UI/Typography',
   component: BdsTypography,
   tags: ['!stable', 'experimental'],
-  parameters: { layout: 'padded' },
+  parameters: { layout: 'centered' },
   argTypes: {
     variant: { control: 'select', options: ['h1', 'h2', 'h3', 'body', 'body_s'] },
+    component: { control: 'text' },
   },
 } satisfies Meta<typeof BdsTypography>;
 
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-export const H1: Story = { args: { variant: 'h1', children: 'Heading level 1' } };
-export const H2: Story = { args: { variant: 'h2', children: 'Heading level 2' } };
-export const H3: Story = { args: { variant: 'h3', children: 'Heading level 3' } };
-export const Body: Story = { args: { variant: 'body', children: 'Body text — the default paragraph style for reading comfort.' } };
-export const BodySmall: Story = { args: { variant: 'body_s', children: 'Small body text — useful for captions and helper text.' } };
+export const Default: Story = { args: { children: 'Body text', variant: 'body' } };
+export const H1: Story = { args: { children: 'Heading 1', variant: 'h1' } };
+export const H2: Story = { args: { children: 'Heading 2', variant: 'h2' } };
+export const H3: Story = { args: { children: 'Heading 3', variant: 'h3' } };
+export const Body: Story = { args: { children: 'Regular body text.', variant: 'body' } };
+export const BodySmall: Story = { args: { children: 'Small body text.', variant: 'body_s' } };
+export const CustomTag: Story = {
+  args: { children: 'Rendered as a <span>', variant: 'body_s', component: 'span' },
+};
 
 export const AllVariants: Story = {
   render: () => (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
-      {(['h1', 'h2', 'h3', 'body', 'body_s'] as const).map(v => (
-        <BdsTypography key={v} variant={v}>
-          {v === 'h1' && 'Heading level 1'}
-          {v === 'h2' && 'Heading level 2'}
-          {v === 'h3' && 'Heading level 3'}
-          {v === 'body' && 'Body text — comfortable reading size for paragraphs.'}
-          {v === 'body_s' && 'Small body — captions, labels, and secondary text.'}
-        </BdsTypography>
-      ))}
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 12 }}>
+      {React.createElement('bds-typography', { variant: 'h1' }, 'Heading 1')}
+      {React.createElement('bds-typography', { variant: 'h2' }, 'Heading 2')}
+      {React.createElement('bds-typography', { variant: 'h3' }, 'Heading 3')}
+      {React.createElement('bds-typography', { variant: 'body' }, 'Body text — regular paragraph copy.')}
+      {React.createElement('bds-typography', { variant: 'body_s' }, 'Body small — captions and helper text.')}
     </div>
   ),
 };

package/src/web-components/ui/bds-button-group.spec.ts

@@ -0,0 +1,40 @@
+import { fixture, cleanup } from '../test/helpers';
+import { BdsButtonGroup } from './bds-button-group';
+
+describe('bds-button-group', () => {
+  it('is registered as a custom element', () => {
+    expect(customElements.get('bds-button-group')).toBe(BdsButtonGroup);
+  });
+
+  it('renders a group role element', async () => {
+    const el = await fixture('<bds-button-group>content</bds-button-group>');
+    expect(el.shadowRoot!.querySelector('[role="group"]')).not.toBeNull();
+    cleanup(el);
+  });
+
+  it('defaults to horizontal orientation', async () => {
+    const el = await fixture('<bds-button-group>content</bds-button-group>') as BdsButtonGroup;
+    expect(el.orientation).toBe('horizontal');
+    cleanup(el);
+  });
+
+  it('reflects vertical orientation attribute', async () => {
+    const el = await fixture('<bds-button-group orientation="vertical">content</bds-button-group>') as BdsButtonGroup;
+    expect(el.orientation).toBe('vertical');
+    expect(el.getAttribute('orientation')).toBe('vertical');
+    cleanup(el);
+  });
+
+  it('renders a slot', async () => {
+    const el = await fixture('<bds-button-group><span>item</span></bds-button-group>');
+    expect(el.shadowRoot!.querySelector('slot')).not.toBeNull();
+    cleanup(el);
+  });
+
+  it('sets aria-label on the group element', async () => {
+    const el = await fixture('<bds-button-group aria-label="View options">content</bds-button-group>');
+    const group = el.shadowRoot!.querySelector('[role="group"]')!;
+    expect(group.getAttribute('aria-label')).toBe('View options');
+    cleanup(el);
+  });
+});