@boostdev/design-system-components 1.2.0 → 1.2.1

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

@@ -1,13 +1,13 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
-import '../index';
+import '../index'; // auto-registers all custom elements
 
 function BdsProgress({
   value = 0,
-  max,
+  max = 100,
   label,
   showLabel,
-  size,
+  size = 'medium',
 }: {
   value?: number;
   max?: number;
@@ -28,43 +28,69 @@ const meta = {
   title: 'Web Components/UI/Progress',
   component: BdsProgress,
   tags: ['!stable', 'experimental'],
-  parameters: { layout: 'padded' },
+  parameters: { layout: 'centered' },
   argTypes: {
-    size: { control: 'select', options: ['small', 'medium', 'large'] },
+    value:     { control: { type: 'range', min: 0, max: 100 } },
+    max:       { control: 'number' },
+    size:      { control: 'select', options: ['small', 'medium', 'large'] },
+    showLabel: { control: 'boolean' },
+    label:     { control: 'text' },
   },
 } 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 Default: Story = {
+  args: { value: 60, label: 'Progress', size: 'medium' },
+  render: ({ value, max, label, showLabel, size }) => (
+    <div style={{ width: 400 }}>
+      {React.createElement('bds-progress', {
+        value,
+        max,
+        label,
+        'show-label': showLabel || undefined,
+        size,
+      })}
+    </div>
+  ),
+};
 
-export const AllVariants: Story = {
+export const WithLabel: 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 style={{ width: 400 }}>
+      {React.createElement('bds-progress', {
+        value: 60,
+        label: 'Upload progress',
+        'show-label': true,
+        size: 'medium',
+      })}
     </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>
-    );
-  },
+export const Small: Story = {
+  render: () => (
+    <div style={{ width: 400 }}>
+      {React.createElement('bds-progress', { value: 40, label: 'Loading', size: 'small' })}
+    </div>
+  ),
+};
+
+export const Large: Story = {
+  render: () => (
+    <div style={{ width: 400 }}>
+      {React.createElement('bds-progress', { value: 80, label: 'Loading', size: 'large' })}
+    </div>
+  ),
+};
+
+export const AllSizes: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 16, width: 400 }}>
+      {React.createElement('bds-progress', { value: 60, label: 'Small', 'show-label': true, size: 'small' })}
+      {React.createElement('bds-progress', { value: 60, label: 'Medium', 'show-label': true, size: 'medium' })}
+      {React.createElement('bds-progress', { value: 60, label: 'Large', 'show-label': true, size: 'large' })}
+    </div>
+  ),
 };

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

@@ -5,7 +5,7 @@ import * as Stories from './BdsProgressCircle.stories';
 
 # <bds-progress-circle>
 
-Framework-agnostic circular Progress indicator. Uses SVG to render a smooth arc that fills based on `value / max`.
+Framework-agnostic circular Progress custom element. Renders an SVG ring that fills proportionally to the `value` attribute, with an optional centred percentage label.
 
 > **Status: experimental** — API may change before stable release.
 
@@ -15,16 +15,27 @@ Framework-agnostic circular Progress indicator. Uses SVG to render a smooth arc
 import '@boostdev/components/web-components';
 ```
 
+## When to use
+
+- Compact progress indicators in dashboards, stat cards, or alongside a loading spinner
+- Use `show-value` to display the numeric percentage inside the ring
+
 ## Examples
 
 ### All sizes
-<Canvas of={Stories.AllVariants} />
+<Canvas of={Stories.AllSizes} />
+
+### Default
+<Canvas of={Stories.Default} />
 
-### With value
+### With centred value
 <Canvas of={Stories.WithValue} />
 
-### Animated
-<Canvas of={Stories.Interactive} />
+### Small
+<Canvas of={Stories.Small} />
+
+### Large
+<Canvas of={Stories.Large} />
 
 ## Props
 
@@ -36,29 +47,24 @@ import '@boostdev/components/web-components';
 |-----------|------|---------|-------------|
 | `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`) |
+| `label` | string | — | Accessible label for the progress bar |
+| `show-value` | boolean | `false` | Displays the rounded percentage in the centre of the ring |
+| `size` | `"small" \| "medium" \| "large"` | `"medium"` | Diameter (`40px` / `64px` / `96px`) |
 
 ## CSS Custom Properties
 
 | Property | Description |
 |----------|-------------|
-| `--progressCircle_color-active` | Arc stroke colour (defaults to `--bdc-color_active`) |
+| `--progressCircle_color-active` | Stroke colour of the filled arc |
 
 ## 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>
+<bds-progress-circle value="75" label="Upload progress" show-value></bds-progress-circle>
+<bds-progress-circle value="30" size="small" label="Loading"></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`
+- Renders with `role="progressbar"`, `aria-valuenow`, `aria-valuemin`, and `aria-valuemax`
+- Always provide a `label` to give the indicator a meaningful accessible name

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

@@ -1,13 +1,13 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
-import '../index';
+import '../index'; // auto-registers all custom elements
 
 function BdsProgressCircle({
   value = 0,
-  max,
+  max = 100,
   label,
   showValue,
-  size,
+  size = 'medium',
 }: {
   value?: number;
   max?: number;
@@ -30,40 +30,28 @@ const meta = {
   tags: ['!stable', 'experimental'],
   parameters: { layout: 'centered' },
   argTypes: {
-    size: { control: 'select', options: ['small', 'medium', 'large'] },
+    value:     { control: { type: 'range', min: 0, max: 100 } },
+    max:       { control: 'number' },
+    size:      { control: 'select', options: ['small', 'medium', 'large'] },
+    showValue: { control: 'boolean' },
+    label:     { control: 'text' },
   },
 } 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 Default: Story = { args: { value: 75, label: 'Progress', size: 'medium' } };
+export const WithValue: Story = { args: { value: 75, label: 'Progress', showValue: true, size: 'medium' } };
+export const Small: Story = { args: { value: 50, label: 'Loading', size: 'small' } };
+export const Large: Story = { args: { value: 50, label: 'Loading', showValue: true, size: 'large' } };
 
-export const AllVariants: Story = {
+export const AllSizes: 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 style={{ display: 'flex', gap: 24, alignItems: 'center' }}>
+      {React.createElement('bds-progress-circle', { value: 60, label: 'Small', 'show-value': true, size: 'small' })}
+      {React.createElement('bds-progress-circle', { value: 60, label: 'Medium', 'show-value': true, size: 'medium' })}
+      {React.createElement('bds-progress-circle', { value: 60, label: 'Large', 'show-value': true, size: 'large' })}
     </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

@@ -5,7 +5,7 @@ import * as Stories from './BdsRating.stories';
 
 # <bds-rating>
 
-Framework-agnostic read-only star Rating display. Use to show a score or user rating.
+Framework-agnostic read-only star Rating custom element. Renders a row of SVG stars with filled/empty states based on `value` and `max`.
 
 > **Status: experimental** — API may change before stable release.
 
@@ -15,16 +15,27 @@ Framework-agnostic read-only star Rating display. Use to show a score or user ra
 import '@boostdev/components/web-components';
 ```
 
+## When to use
+
+- Displaying product or review ratings in cards or lists
+- Read-only — for interactive star selection, use a form input instead
+
 ## Examples
 
-### All ratings
-<Canvas of={Stories.AllVariants} />
+### All values
+<Canvas of={Stories.AllValues} />
+
+### Default (3 of 5)
+<Canvas of={Stories.Default} />
+
+### Full (5 of 5)
+<Canvas of={Stories.Full} />
 
-### 5 stars
-<Canvas of={Stories.FiveStars} />
+### Empty (0 of 5)
+<Canvas of={Stories.Empty} />
 
-### Custom max
-<Canvas of={Stories.Custom} />
+### Custom max (7 of 10)
+<Canvas of={Stories.CustomMax} />
 
 ## Props
 
@@ -35,27 +46,16 @@ import '@boostdev/components/web-components';
 | 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) |
+| `max` | number | `5` | Total number of stars displayed |
 
 ## 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>
+<bds-rating value="4" 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
+- Renders `role="img"` with `aria-label` set to `"{value} out of {max} stars"`
+- All star SVGs carry `aria-hidden="true"` to avoid duplicate announcements

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

@@ -1,8 +1,14 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
-import '../index';
+import '../index'; // auto-registers all custom elements
 
-function BdsRating({ value = 0, max }: { value?: number; max?: number }) {
+function BdsRating({
+  value = 0,
+  max = 5,
+}: {
+  value?: number;
+  max?: number;
+}) {
   return React.createElement('bds-rating', { value, max });
 }
 
@@ -12,26 +18,26 @@ const meta = {
   tags: ['!stable', 'experimental'],
   parameters: { layout: 'centered' },
   argTypes: {
-    value: { control: { type: 'number', min: 0, max: 10 } },
-    max: { control: { type: 'number', min: 1, max: 10 } },
+    value: { control: { type: 'range', min: 0, max: 10 } },
+    max:   { control: 'number' },
   },
 } 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 Default: Story = { args: { value: 3, max: 5 } };
+export const Full: Story = { args: { value: 5, max: 5 } };
+export const Empty: Story = { args: { value: 0, max: 5 } };
+export const CustomMax: Story = { args: { value: 7, max: 10 } };
 
-export const AllVariants: Story = {
+export const AllValues: Story = {
   render: () => (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
       {[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 key={v} style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+          <span style={{ width: 8 }}>{v}</span>
+          {React.createElement('bds-rating', { value: v, max: 5 })}
         </div>
       ))}
     </div>

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

@@ -5,7 +5,7 @@ import * as Stories from './BdsSectionHeader.stories';
 
 # <bds-section-header>
 
-Framework-agnostic Section Header custom element. Use to introduce page sections with a title and optional subtitle.
+Framework-agnostic Section Header custom element. Combines a title and optional subtitle into a consistently styled page or section heading with size and alignment variants.
 
 > **Status: experimental** — API may change before stable release.
 
@@ -15,16 +15,31 @@ Framework-agnostic Section Header custom element. Use to introduce page sections
 import '@boostdev/components/web-components';
 ```
 
+## When to use
+
+- At the top of page sections to introduce content areas
+- Use `alignment="center"` for marketing/hero sections
+- Override the semantic tag with `title-as` when the heading hierarchy requires a different level
+
 ## Examples
 
 ### All sizes
-<Canvas of={Stories.AllVariants} />
+<Canvas of={Stories.AllSizes} />
+
+### Default
+<Canvas of={Stories.Default} />
+
+### Small
+<Canvas of={Stories.Small} />
+
+### Large
+<Canvas of={Stories.Large} />
 
-### With subtitle
-<Canvas of={Stories.WithSubtitle} />
+### Centered
+<Canvas of={Stories.Centered} />
 
-### Center aligned
-<Canvas of={Stories.Center} />
+### Title only
+<Canvas of={Stories.TitleOnly} />
 
 ## Props
 
@@ -35,35 +50,23 @@ import '@boostdev/components/web-components';
 | 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 |
+| `subtitle` | string | — | Optional subheading text |
+| `alignment` | `"start" \| "center" \| "end"` | `"start"` | Text and flex alignment |
+| `size` | `"small" \| "medium" \| "large"` | `"medium"` | Font size scale for title and subtitle |
+| `title-as` | string | `"h2"` | Override the HTML element rendered for the title |
 
 ## 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"
+  title="Our Products"
+  subtitle="Browse the full range"
   size="large"
-></bds-section-header>
-
-<!-- Use h3 when nested inside another section -->
-<bds-section-header title="Subsection" title-as="h3"></bds-section-header>
+  alignment="center">
+</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
+- The title renders as `h2` by default; use `title-as` to match the page heading hierarchy
+- Avoid skipping heading levels when changing `title-as`

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

@@ -1,12 +1,12 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
-import '../index';
+import '../index'; // auto-registers all custom elements
 
 function BdsSectionHeader({
-  title,
+  title = '',
   subtitle,
-  alignment,
-  size,
+  alignment = 'start',
+  size = 'medium',
   titleAs,
 }: {
   title?: string;
@@ -15,13 +15,7 @@ function BdsSectionHeader({
   size?: 'small' | 'medium' | 'large';
   titleAs?: string;
 }) {
-  return React.createElement('bds-section-header', {
-    title,
-    subtitle,
-    alignment,
-    size,
-    'title-as': titleAs,
-  });
+  return React.createElement('bds-section-header', { title, subtitle, alignment, size, 'title-as': titleAs });
 }
 
 const meta = {
@@ -31,26 +25,30 @@ const meta = {
   parameters: { layout: 'padded' },
   argTypes: {
     alignment: { control: 'select', options: ['start', 'center', 'end'] },
-    size: { control: 'select', options: ['small', 'medium', 'large'] },
+    size:      { control: 'select', options: ['small', 'medium', 'large'] },
+    titleAs:   { control: 'text' },
   },
 } 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 Default: Story = {
+  args: { title: 'Our Products', subtitle: 'Browse the full range', size: 'medium', alignment: 'start' },
+};
+export const Small: Story = { args: { title: 'Recent Activity', subtitle: 'Last 30 days', size: 'small' } };
+export const Large: Story = { args: { title: 'Welcome Back', subtitle: 'Here is what happened today', size: 'large' } };
+export const Centered: Story = {
+  args: { title: 'Our Mission', subtitle: 'We are building something great', alignment: 'center' },
+};
+export const TitleOnly: Story = { args: { title: 'Settings', size: 'small' } };
 
-export const AllVariants: Story = {
+export const AllSizes: 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 style={{ display: 'flex', flexDirection: 'column', gap: 32 }}>
+      {React.createElement('bds-section-header', { title: 'Small Heading', subtitle: 'Subtitle text', size: 'small' })}
+      {React.createElement('bds-section-header', { title: 'Medium Heading', subtitle: 'Subtitle text', size: 'medium' })}
+      {React.createElement('bds-section-header', { title: 'Large Heading', subtitle: 'Subtitle text', size: 'large' })}
     </div>
   ),
 };

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

@@ -5,20 +5,34 @@ import * as Stories from './BdsSeparator.stories';
 
 # <bds-separator>
 
-Framework-agnostic Separator custom element. Renders a horizontal or vertical visual divider.
+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
 
-### All variants
-<Canvas of={Stories.AllVariants} />
+### Default (horizontal)
+<Canvas of={Stories.Default} />
 
 ### Horizontal
 <Canvas of={Stories.Horizontal} />
@@ -46,11 +60,12 @@ import '@boostdev/components/web-components';
 ## Usage in plain HTML
 
 ```html
-<!-- Horizontal (default) -->
+<p>Above</p>
 <bds-separator></bds-separator>
+<p>Below</p>
 
-<!-- Vertical — needs a height context -->
-<div style="display: flex; align-items: center; height: 40px; gap: 16px;">
+<!-- Vertical -->
+<div style="display: flex; align-items: center; gap: 8px; height: 40px;">
   <span>Left</span>
   <bds-separator orientation="vertical"></bds-separator>
   <span>Right</span>
@@ -59,5 +74,4 @@ import '@boostdev/components/web-components';
 
 ## Accessibility
 
-- Renders as `role="separator"` with `aria-orientation` set automatically
-- Purely decorative — screen readers announce it as a separator landmark
+- Renders a `<div role="separator">` with `aria-orientation` set automatically