@boostdev/design-system-components 1.1.1 → 1.2.0

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

@@ -0,0 +1,63 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsProgress.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-progress&gt;
+
+Framework-agnostic linear Progress bar custom element. Use to show completion status of a task or upload.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## Examples
+
+### All values
+<Canvas of={Stories.AllVariants} />
+
+### With label
+<Canvas of={Stories.WithLabel} />
+
+### Animated
+<Canvas of={Stories.Interactive} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `value` | number | `0` | Current progress value |
+| `max` | number | `100` | Maximum value |
+| `label` | string | — | Accessible label text |
+| `show-label` | boolean | `false` | Displays label and percentage above the bar |
+| `size` | `"small" \| "medium" \| "large"` | `"medium"` | Track thickness |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--progress_color-active` | Fill colour (defaults to `--bdc-color_active`) |
+
+## Usage in plain HTML
+
+```html
+<bds-progress value="60"></bds-progress>
+
+<bds-progress value="75" label="Upload progress" show-label></bds-progress>
+
+<bds-progress value="40" size="large" label="Loading" show-label></bds-progress>
+```
+
+## Accessibility
+
+- Renders `role="progressbar"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, and `aria-label`
+- Always provide a meaningful `label` for screen reader users
+- Transition animation respects `prefers-reduced-motion`

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

@@ -0,0 +1,70 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../index';
+
+function BdsProgress({
+  value = 0,
+  max,
+  label,
+  showLabel,
+  size,
+}: {
+  value?: number;
+  max?: number;
+  label?: string;
+  showLabel?: boolean;
+  size?: 'small' | 'medium' | 'large';
+}) {
+  return React.createElement('bds-progress', {
+    value,
+    max,
+    label,
+    'show-label': showLabel || undefined,
+    size,
+  });
+}
+
+const meta = {
+  title: 'Web Components/UI/Progress',
+  component: BdsProgress,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'padded' },
+  argTypes: {
+    size: { control: 'select', options: ['small', 'medium', 'large'] },
+  },
+} satisfies Meta<typeof BdsProgress>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = { args: { value: 60 } };
+export const WithLabel: Story = { args: { value: 75, label: 'Upload progress', showLabel: true } };
+export const Complete: Story = { args: { value: 100, label: 'Complete', showLabel: true } };
+export const Small: Story = { args: { value: 40, size: 'small' } };
+export const Medium: Story = { args: { value: 40, size: 'medium' } };
+export const Large: Story = { args: { value: 40, size: 'large' } };
+
+export const AllVariants: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px', maxWidth: '400px' }}>
+      {[25, 50, 75, 100].map(v => (
+        <BdsProgress key={v} value={v} label={`${v}%`} showLabel />
+      ))}
+    </div>
+  ),
+};
+
+export const Interactive: Story = {
+  render: () => {
+    const [value, setValue] = React.useState(0);
+    React.useEffect(() => {
+      const id = setInterval(() => setValue(v => (v >= 100 ? 0 : v + 5)), 200);
+      return () => clearInterval(id);
+    }, []);
+    return (
+      <div style={{ maxWidth: '400px', display: 'flex', flexDirection: 'column', gap: '12px' }}>
+        <BdsProgress value={value} label="Loading…" showLabel />
+      </div>
+    );
+  },
+};

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

@@ -0,0 +1,64 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsProgressCircle.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-progress-circle&gt;
+
+Framework-agnostic circular Progress indicator. Uses SVG to render a smooth arc that fills based on `value / max`.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## Examples
+
+### All sizes
+<Canvas of={Stories.AllVariants} />
+
+### With value
+<Canvas of={Stories.WithValue} />
+
+### Animated
+<Canvas of={Stories.Interactive} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `value` | number | `0` | Current progress value |
+| `max` | number | `100` | Maximum value |
+| `label` | string | — | Accessible label text |
+| `show-value` | boolean | `false` | Displays the percentage in the centre |
+| `size` | `"small" \| "medium" \| "large"` | `"medium"` | SVG diameter (`40px` / `64px` / `96px`) |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--progressCircle_color-active` | Arc stroke colour (defaults to `--bdc-color_active`) |
+
+## Usage in plain HTML
+
+```html
+<bds-progress-circle value="75" label="Loading"></bds-progress-circle>
+
+<bds-progress-circle value="65" label="Upload" show-value></bds-progress-circle>
+
+<bds-progress-circle value="80" size="large" label="Progress" show-value></bds-progress-circle>
+```
+
+## Accessibility
+
+- Renders `role="progressbar"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, and `aria-label`
+- Always provide a meaningful `label` for screen readers
+- SVG is hidden from assistive technology (`aria-hidden="true"`) — ARIA attributes are on the container
+- Stroke transition respects `prefers-reduced-motion`

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

@@ -0,0 +1,69 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../index';
+
+function BdsProgressCircle({
+  value = 0,
+  max,
+  label,
+  showValue,
+  size,
+}: {
+  value?: number;
+  max?: number;
+  label?: string;
+  showValue?: boolean;
+  size?: 'small' | 'medium' | 'large';
+}) {
+  return React.createElement('bds-progress-circle', {
+    value,
+    max,
+    label,
+    'show-value': showValue || undefined,
+    size,
+  });
+}
+
+const meta = {
+  title: 'Web Components/UI/ProgressCircle',
+  component: BdsProgressCircle,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    size: { control: 'select', options: ['small', 'medium', 'large'] },
+  },
+} satisfies Meta<typeof BdsProgressCircle>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = { args: { value: 75 } };
+export const WithValue: Story = { args: { value: 65, showValue: true, label: 'Progress' } };
+export const Complete: Story = { args: { value: 100, showValue: true, label: 'Complete' } };
+export const Small: Story = { args: { value: 60, size: 'small', showValue: true } };
+export const Medium: Story = { args: { value: 60, size: 'medium', showValue: true } };
+export const Large: Story = { args: { value: 60, size: 'large', showValue: true } };
+
+export const AllVariants: Story = {
+  render: () => (
+    <div style={{ display: 'flex', alignItems: 'center', gap: '32px', flexWrap: 'wrap' }}>
+      {(['small', 'medium', 'large'] as const).map(s => (
+        <div key={s} style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: '8px' }}>
+          <BdsProgressCircle value={75} size={s} showValue label="Progress" />
+          <span style={{ fontSize: '0.75rem', color: '#888' }}>{s}</span>
+        </div>
+      ))}
+    </div>
+  ),
+};
+
+export const Interactive: Story = {
+  render: () => {
+    const [value, setValue] = React.useState(0);
+    React.useEffect(() => {
+      const id = setInterval(() => setValue(v => (v >= 100 ? 0 : v + 2)), 100);
+      return () => clearInterval(id);
+    }, []);
+    return <BdsProgressCircle value={value} showValue label="Loading" size="large" />;
+  },
+};

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

@@ -0,0 +1,61 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsRating.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-rating&gt;
+
+Framework-agnostic read-only star Rating display. Use to show a score or user rating.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## Examples
+
+### All ratings
+<Canvas of={Stories.AllVariants} />
+
+### 5 stars
+<Canvas of={Stories.FiveStars} />
+
+### Custom max
+<Canvas of={Stories.Custom} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `value` | number | `0` | Number of filled stars |
+| `max` | number | `5` | Total number of stars |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--bds-color_warning` | Filled star colour (foundation token) |
+
+## Usage in plain HTML
+
+```html
+<bds-rating value="3"></bds-rating>
+
+<bds-rating value="4" max="5"></bds-rating>
+
+<!-- Custom scale -->
+<bds-rating value="7" max="10"></bds-rating>
+```
+
+## Accessibility
+
+- Renders `role="img"` with `aria-label="X out of Y stars"`
+- Individual star SVGs are hidden from assistive technology (`aria-hidden="true"`)
+- This is a read-only display — for interactive ratings, use a radio group pattern

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

@@ -0,0 +1,39 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../index';
+
+function BdsRating({ value = 0, max }: { value?: number; max?: number }) {
+  return React.createElement('bds-rating', { value, max });
+}
+
+const meta = {
+  title: 'Web Components/UI/Rating',
+  component: BdsRating,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    value: { control: { type: 'number', min: 0, max: 10 } },
+    max: { control: { type: 'number', min: 1, max: 10 } },
+  },
+} satisfies Meta<typeof BdsRating>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const OneStar: Story = { args: { value: 1 } };
+export const ThreeStars: Story = { args: { value: 3 } };
+export const FiveStars: Story = { args: { value: 5 } };
+export const Custom: Story = { args: { value: 7, max: 10 } };
+
+export const AllVariants: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+      {[1, 2, 3, 4, 5].map(v => (
+        <div key={v} style={{ display: 'flex', alignItems: 'center', gap: '12px' }}>
+          <BdsRating value={v} />
+          <span style={{ fontSize: '0.875rem', color: '#888' }}>{v}/5</span>
+        </div>
+      ))}
+    </div>
+  ),
+};

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

@@ -0,0 +1,69 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsSectionHeader.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-section-header&gt;
+
+Framework-agnostic Section Header custom element. Use to introduce page sections with a title and optional subtitle.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## Examples
+
+### All sizes
+<Canvas of={Stories.AllVariants} />
+
+### With subtitle
+<Canvas of={Stories.WithSubtitle} />
+
+### Center aligned
+<Canvas of={Stories.Center} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `title` | string | — | Heading text (required) |
+| `subtitle` | string | — | Optional subheading |
+| `alignment` | `"start" \| "center" \| "end"` | `"start"` | Text alignment |
+| `size` | `"small" \| "medium" \| "large"` | `"medium"` | Typography scale |
+| `title-as` | string | `"h2"` | HTML tag for the title element |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--sectionHeader-title-color` | Title text colour |
+| `--sectionHeader_subtitle-color` | Subtitle text colour |
+
+## Usage in plain HTML
+
+```html
+<bds-section-header title="Our Products"></bds-section-header>
+
+<bds-section-header
+  title="Features"
+  subtitle="Everything you need"
+  alignment="center"
+  size="large"
+></bds-section-header>
+
+<!-- Use h3 when nested inside another section -->
+<bds-section-header title="Subsection" title-as="h3"></bds-section-header>
+```
+
+## Accessibility
+
+- Always set `title-as` to match the correct heading level in the document outline
+- Default is `h2` — adjust if the section header is nested inside an `h2` section

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

@@ -0,0 +1,56 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../index';
+
+function BdsSectionHeader({
+  title,
+  subtitle,
+  alignment,
+  size,
+  titleAs,
+}: {
+  title?: string;
+  subtitle?: string;
+  alignment?: 'start' | 'center' | 'end';
+  size?: 'small' | 'medium' | 'large';
+  titleAs?: string;
+}) {
+  return React.createElement('bds-section-header', {
+    title,
+    subtitle,
+    alignment,
+    size,
+    'title-as': titleAs,
+  });
+}
+
+const meta = {
+  title: 'Web Components/UI/SectionHeader',
+  component: BdsSectionHeader,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'padded' },
+  argTypes: {
+    alignment: { control: 'select', options: ['start', 'center', 'end'] },
+    size: { control: 'select', options: ['small', 'medium', 'large'] },
+  },
+} satisfies Meta<typeof BdsSectionHeader>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = { args: { title: 'Our Products' } };
+export const WithSubtitle: Story = { args: { title: 'Our Products', subtitle: 'Browse the full range of components' } };
+export const Center: Story = { args: { title: 'Features', subtitle: 'Everything you need to build faster', alignment: 'center' } };
+export const End: Story = { args: { title: 'Aligned end', alignment: 'end' } };
+export const Small: Story = { args: { title: 'Small header', subtitle: 'Compact section intro', size: 'small' } };
+export const Large: Story = { args: { title: 'Large header', subtitle: 'Hero-scale section heading', size: 'large' } };
+
+export const AllVariants: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '32px' }}>
+      {(['small', 'medium', 'large'] as const).map(s => (
+        <BdsSectionHeader key={s} title={`${s.charAt(0).toUpperCase() + s.slice(1)} header`} subtitle="Optional subtitle text" size={s} />
+      ))}
+    </div>
+  ),
+};

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

@@ -0,0 +1,63 @@
+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 horizontal or vertical visual divider.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## Examples
+
+### All variants
+<Canvas of={Stories.AllVariants} />
+
+### 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
+<!-- Horizontal (default) -->
+<bds-separator></bds-separator>
+
+<!-- Vertical — needs a height context -->
+<div style="display: flex; align-items: center; height: 40px; gap: 16px;">
+  <span>Left</span>
+  <bds-separator orientation="vertical"></bds-separator>
+  <span>Right</span>
+</div>
+```
+
+## Accessibility
+
+- Renders as `role="separator"` with `aria-orientation` set automatically
+- Purely decorative — screen readers announce it as a separator landmark

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

@@ -0,0 +1,47 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../index';
+
+function BdsSeparator({ orientation }: { 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: 'select', options: ['horizontal', 'vertical'] },
+  },
+} satisfies Meta<typeof BdsSeparator>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Horizontal: Story = { args: { orientation: 'horizontal' } };
+
+export const Vertical: Story = {
+  render: () => (
+    <div style={{ display: 'flex', alignItems: 'center', gap: '16px', height: '40px' }}>
+      <span>Left</span>
+      <BdsSeparator orientation="vertical" />
+      <span>Right</span>
+    </div>
+  ),
+};
+
+export const AllVariants: 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>
+  ),
+};

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

@@ -0,0 +1,67 @@
+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. 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.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## Examples
+
+### Card layout skeleton
+<Canvas of={Stories.AllVariants} />
+
+### Text line
+<Canvas of={Stories.TextLine} />
+
+### Avatar placeholder
+<Canvas of={Stories.Avatar} />
+
+### Card placeholder
+<Canvas of={Stories.Card} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## 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 |
+
+## Usage in plain HTML
+
+```html
+<!-- Text line -->
+<bds-skeleton style="width: 200px; height: 1rem;"></bds-skeleton>
+
+<!-- Avatar -->
+<bds-skeleton style="width: 3rem; height: 3rem; border-radius: 50%;"></bds-skeleton>
+
+<!-- Card block -->
+<bds-skeleton style="width: 280px; height: 160px;"></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