@boostdev/design-system-components 1.1.2 → 1.2.1

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

@@ -0,0 +1,77 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsSeparator.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-separator&gt;
+
+Framework-agnostic Separator custom element. Renders a thin decorative line to visually divide content. Supports both horizontal and vertical orientations.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+// Register all web components at once
+import '@boostdev/components/web-components';
+```
+
+Or in HTML without a bundler:
+
+```html
+<script type="module">
+  import '@boostdev/components/web-components';
+</script>
+```
+
+## When to use
+
+- To visually separate groups of related content (e.g. sections in a form or list)
+- As a vertical divider between inline elements such as navigation links
+
+## Examples
+
+### Default (horizontal)
+<Canvas of={Stories.Default} />
+
+### Horizontal
+<Canvas of={Stories.Horizontal} />
+
+### Vertical
+<Canvas of={Stories.Vertical} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Direction of the separator line |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--separator_color` | Line colour (defaults to `--bds-color_on-bg`) |
+| `--separator_thickness` | Line thickness (default: `1px`) |
+
+## Usage in plain HTML
+
+```html
+<p>Above</p>
+<bds-separator></bds-separator>
+<p>Below</p>
+
+<!-- Vertical -->
+<div style="display: flex; align-items: center; gap: 8px; height: 40px;">
+  <span>Left</span>
+  <bds-separator orientation="vertical"></bds-separator>
+  <span>Right</span>
+</div>
+```
+
+## Accessibility
+
+- Renders a `<div role="separator">` with `aria-orientation` set automatically

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

@@ -0,0 +1,55 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../index'; // auto-registers all custom elements
+
+function BdsSeparator({
+  orientation = 'horizontal',
+}: {
+  orientation?: 'horizontal' | 'vertical';
+}) {
+  return React.createElement('bds-separator', { orientation });
+}
+
+const meta = {
+  title: 'Web Components/UI/Separator',
+  component: BdsSeparator,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    orientation: { control: 'radio', options: ['horizontal', 'vertical'] },
+  },
+} satisfies Meta<typeof BdsSeparator>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+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 Horizontal: Story = {
+  render: () => (
+    <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 Vertical: Story = {
+  render: () => (
+    <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

@@ -0,0 +1,61 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsSkeleton.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-skeleton&gt;
+
+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.
+
+## Installation
+
+```js
+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
+
+### Default
+<Canvas of={Stories.Default} />
+
+### Heading placeholder
+<Canvas of={Stories.Heading} />
+
+### Avatar placeholder
+<Canvas of={Stories.Avatar} />
+
+### Content block
+<Canvas of={Stories.ContentBlock} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+`<bds-skeleton>` has no custom attributes. Size is controlled via inline styles or CSS.
+
+## Usage in plain HTML
+
+```html
+<!-- Inline text placeholder -->
+<bds-skeleton style="width: 200px; height: 1rem;"></bds-skeleton>
+
+<!-- Heading placeholder -->
+<bds-skeleton style="width: 300px; height: 2rem;"></bds-skeleton>
+
+<!-- Avatar placeholder -->
+<bds-skeleton style="width: 48px; height: 48px; border-radius: 50%;"></bds-skeleton>
+```
+
+## Accessibility
+
+- 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

@@ -0,0 +1,50 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../index'; // auto-registers all custom elements
+
+// 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 = {
+  title: 'Web Components/UI/Skeleton',
+  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 Default: Story = {
+  args: { width: '200px', height: '1rem' },
+};
+
+export const Heading: Story = {
+  args: { width: '300px', height: '2rem' },
+};
+
+export const Avatar: Story = {
+  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 ContentBlock: Story = {
+  render: () => (
+    <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

@@ -0,0 +1,74 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsTypography.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-typography&gt;
+
+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.
+
+## Installation
+
+```js
+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
+<Canvas of={Stories.AllVariants} />
+
+### 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} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `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
+
+| Slot | Description |
+|------|-------------|
+| `(default)` | Text content |
+
+## Usage in plain HTML
+
+```html
+<bds-typography variant="h1">Page title</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 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

@@ -0,0 +1,52 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import type { TypographyVariant } from './bds-typography';
+import '../index'; // auto-registers all custom elements
+
+function BdsTypography({
+  variant = 'body',
+  component,
+  children,
+}: {
+  variant?: TypographyVariant;
+  component?: string;
+  children?: React.ReactNode;
+}) {
+  return React.createElement('bds-typography', { variant, component }, children);
+}
+
+const meta = {
+  title: 'Web Components/UI/Typography',
+  component: BdsTypography,
+  tags: ['!stable', 'experimental'],
+  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 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: 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-alert.ts

@@ -110,8 +110,7 @@ export class BdsAlert extends LitElement {
       transition: var(--bds-animation_transition);
       border-radius: 50%;
       --bdc_color: currentcolor;
-      outline: var(--bdc-outline_width) solid var(--bdc_color);
-      outline-offset: var(--bdc-outline_offset);
+      box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color);
     }
 
     .dismiss svg {

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);
+  });
+});

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

@@ -0,0 +1,78 @@
+import { LitElement, css, html } from 'lit';
+
+export type ButtonGroupOrientation = 'horizontal' | 'vertical';
+
+/**
+ * `<bds-button-group>` — groups related buttons into a flex container.
+ *
+ * Attributes:
+ *   orientation — `"horizontal"` (default) | `"vertical"`
+ *   aria-label  — accessible label for the group
+ *
+ * Slots:
+ *   (default) — `<bds-button>` elements
+ *
+ * @example
+ * <bds-button-group aria-label="View options">
+ *   <bds-button>Day</bds-button>
+ *   <bds-button>Week</bds-button>
+ *   <bds-button>Month</bds-button>
+ * </bds-button-group>
+ */
+export class BdsButtonGroup extends LitElement {
+  static styles = css`
+    :host {
+      display: block;
+    }
+
+    .group {
+      display: inline-flex;
+      flex-direction: row;
+      align-items: center;
+      gap: 0;
+    }
+
+    :host([orientation='vertical']) .group {
+      flex-direction: column;
+      align-items: stretch;
+    }
+
+    /* Collapse border radius between adjacent buttons */
+    ::slotted(*:not(:first-child)) {
+      --button_radius-start: 0;
+    }
+
+    ::slotted(*:not(:last-child)) {
+      --button_radius-end: 0;
+    }
+  `;
+
+  static properties = {
+    orientation: { type: String, reflect: true },
+    'aria-label': { type: String },
+  };
+
+  declare orientation: ButtonGroupOrientation;
+  declare ['aria-label']: string | undefined;
+
+  constructor() {
+    super();
+    this.orientation = 'horizontal';
+  }
+
+  render() {
+    return html`
+      <div class="group" role="group" aria-label=${this['aria-label'] ?? ''}>
+        <slot></slot>
+      </div>
+    `;
+  }
+}
+
+customElements.define('bds-button-group', BdsButtonGroup);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-button-group': BdsButtonGroup;
+  }
+}