@boostdev/design-system-components 1.1.2 → 1.2.0

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

@@ -0,0 +1,90 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsNotificationBanner.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-notification-banner&gt;
+
+Framework-agnostic full-width Notification Banner. Use for page-level messages that require user attention — system notices, maintenance windows, or status updates.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## Examples
+
+### All variants
+<Canvas of={Stories.AllVariants} />
+
+### Dismissible
+<Canvas of={Stories.Interactive} />
+
+### With action
+<Canvas of={Stories.WithAction} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `variant` | `"info" \| "success" \| "warning" \| "error"` | `"info"` | Semantic colour and urgency |
+| `dismissible` | boolean | `false` | Shows a dismiss (×) button |
+| `dismiss-label` | string | `"Dismiss notification"` | Accessible label for the dismiss button |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `(default)` | Banner body content |
+| `action` | Optional action area (e.g. a button or link) |
+
+## Events
+
+| Event | Detail | Bubbles | Composed | Description |
+|-------|--------|---------|----------|-------------|
+| `bds-dismiss` | — | Yes | Yes | Fired when the dismiss button is clicked |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--banner_bg` | Banner background colour |
+| `--banner_text` | Banner text colour |
+| `--banner_border` | Bottom border accent colour |
+
+## Usage in plain HTML
+
+```html
+<bds-notification-banner variant="success">
+  Your changes have been saved.
+</bds-notification-banner>
+
+<bds-notification-banner variant="warning" dismissible>
+  Scheduled maintenance on Sunday.
+</bds-notification-banner>
+
+<bds-notification-banner variant="info">
+  New features available.
+  <button slot="action" type="button">Learn more</button>
+</bds-notification-banner>
+```
+
+Listen for dismiss:
+```js
+document.querySelector('bds-notification-banner').addEventListener('bds-dismiss', () => {
+  // hide or remove the element
+});
+```
+
+## Accessibility
+
+- `error` and `warning` variants use `role="alert"` + `aria-live="assertive"` — announced immediately
+- `info` and `success` variants use `role="status"` + `aria-live="polite"` — announced at next opportunity
+- The dismiss button has an accessible label; customize with `dismiss-label` when needed

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

@@ -0,0 +1,93 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import type { NotificationBannerVariant } from './bds-notification-banner';
+import '../index';
+
+function BdsNotificationBanner({
+  variant = 'info',
+  dismissible,
+  dismissLabel,
+  onDismiss,
+  action,
+  children,
+}: {
+  variant?: NotificationBannerVariant;
+  dismissible?: boolean;
+  dismissLabel?: string;
+  onDismiss?: () => void;
+  action?: React.ReactNode;
+  children?: React.ReactNode;
+}) {
+  return React.createElement(
+    'bds-notification-banner',
+    {
+      variant,
+      dismissible: dismissible || undefined,
+      'dismiss-label': dismissLabel,
+      onbdsdismiss: onDismiss,
+    },
+    children,
+    action ? React.createElement('span', { slot: 'action' }, action) : null,
+  );
+}
+
+const meta = {
+  title: 'Web Components/UI/NotificationBanner',
+  component: BdsNotificationBanner,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'padded' },
+  argTypes: {
+    variant: { control: 'select', options: ['info', 'success', 'warning', 'error'] },
+  },
+} satisfies Meta<typeof BdsNotificationBanner>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Info: Story = { args: { children: 'Your session will expire in 10 minutes.', variant: 'info' } };
+export const Success: Story = { args: { children: 'Your changes have been saved.', variant: 'success' } };
+export const Warning: Story = { args: { children: 'Scheduled maintenance on Sunday 02:00–04:00 UTC.', variant: 'warning' } };
+export const Error: Story = { args: { children: 'Something went wrong. Please try again.', variant: 'error' } };
+export const Dismissible: Story = { args: { children: 'This banner can be dismissed.', variant: 'info', dismissible: true } };
+export const WithAction: Story = {
+  render: () => (
+    <BdsNotificationBanner
+      variant="warning"
+      action={React.createElement('button', { type: 'button' }, 'Learn more')}
+    >
+      New terms of service take effect on Jan 1.
+    </BdsNotificationBanner>
+  ),
+};
+
+export const AllVariants: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '0' }}>
+      {(['info', 'success', 'warning', 'error'] as const).map(v => (
+        <BdsNotificationBanner key={v} variant={v}>
+          This is a {v} notification banner.
+        </BdsNotificationBanner>
+      ))}
+    </div>
+  ),
+};
+
+export const Interactive: Story = {
+  render: () => {
+    const [visible, setVisible] = React.useState(true);
+    return (
+      <div style={{ width: '100%' }}>
+        {visible ? (
+          <BdsNotificationBanner variant="info" dismissible onDismiss={() => setVisible(false)}>
+            Click × to dismiss this banner.
+          </BdsNotificationBanner>
+        ) : (
+          <div style={{ padding: '1rem', textAlign: 'center' }}>
+            <p style={{ margin: '0 0 8px' }}>Banner dismissed.</p>
+            <button onClick={() => setVisible(true)}>Show again</button>
+          </div>
+        )}
+      </div>
+    );
+  },
+};

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