@boostdev/design-system-components 1.1.2 → 1.2.1

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

@@ -0,0 +1,74 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsPagination.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-pagination&gt;
+
+Framework-agnostic Pagination navigation custom element. Renders previous/next buttons and a page number list with smart ellipsis truncation.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## When to use
+
+- Below paginated lists or tables to let users navigate between pages
+- Listen to `bds-page-change` to update your data layer when the page changes
+
+## Examples
+
+### Default (page 3 of 10)
+<Canvas of={Stories.Default} />
+
+### First page
+<Canvas of={Stories.FirstPage} />
+
+### Last page
+<Canvas of={Stories.LastPage} />
+
+### Few pages
+<Canvas of={Stories.FewPages} />
+
+### Many pages (with ellipsis)
+<Canvas of={Stories.ManyPages} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `current-page` | number | `1` | Active page number (1-based) |
+| `total-pages` | number | `1` | Total number of pages |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `bds-page-change` | `{ page: number }` | Fired when the user navigates to a different page |
+
+## Usage in plain HTML
+
+```html
+<bds-pagination current-page="3" total-pages="10"></bds-pagination>
+
+<script>
+  document.querySelector('bds-pagination')
+    .addEventListener('bds-page-change', e => {
+      console.log('Navigate to page', e.detail.page);
+    });
+</script>
+```
+
+## Accessibility
+
+- Wrapped in `<nav aria-label="Pagination">` with an `<ul>` list structure
+- Active page button carries `aria-current="page"`
+- Previous/Next buttons have descriptive `aria-label` values and are `disabled` at the boundaries

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

@@ -0,0 +1,36 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../index'; // auto-registers all custom elements
+
+function BdsPagination({
+  currentPage = 1,
+  totalPages = 1,
+}: {
+  currentPage?: number;
+  totalPages?: number;
+}) {
+  return React.createElement('bds-pagination', {
+    'current-page': currentPage,
+    'total-pages': totalPages,
+  });
+}
+
+const meta = {
+  title: 'Web Components/UI/Pagination',
+  component: BdsPagination,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    currentPage: { control: { type: 'number', min: 1 } },
+    totalPages:  { control: { type: 'number', min: 1 } },
+  },
+} satisfies Meta<typeof BdsPagination>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = { args: { currentPage: 3, totalPages: 10 } };
+export const FirstPage: Story = { args: { currentPage: 1, totalPages: 10 } };
+export const LastPage: Story = { args: { currentPage: 10, totalPages: 10 } };
+export const FewPages: Story = { args: { currentPage: 2, totalPages: 4 } };
+export const ManyPages: Story = { args: { currentPage: 7, totalPages: 20 } };

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

@@ -0,0 +1,70 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsProgress.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-progress&gt;
+
+Framework-agnostic horizontal Progress bar custom element. Tracks progress toward a goal with optional label and percentage display.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## When to use
+
+- File uploads, multi-step forms, or any linear task with a measurable completion percentage
+- Add `show-label` to make progress visible without screen-reader-only text
+
+## Examples
+
+### All sizes
+<Canvas of={Stories.AllSizes} />
+
+### Default
+<Canvas of={Stories.Default} />
+
+### With label
+<Canvas of={Stories.WithLabel} />
+
+### Small
+<Canvas of={Stories.Small} />
+
+### Large
+<Canvas of={Stories.Large} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `value` | number | `0` | Current progress value |
+| `max` | number | `100` | Maximum value |
+| `label` | string | — | Accessible label; also shown above the bar when `show-label` is set |
+| `show-label` | boolean | `false` | Displays label text and percentage above the bar |
+| `size` | `"small" \| "medium" \| "large"` | `"medium"` | Track height |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--progress_color-active` | Fill colour of the progress bar |
+
+## Usage in plain HTML
+
+```html
+<bds-progress value="60" label="Upload progress" show-label></bds-progress>
+<bds-progress value="30" size="small" label="Loading"></bds-progress>
+```
+
+## Accessibility
+
+- Renders with `role="progressbar"`, `aria-valuenow`, `aria-valuemin`, and `aria-valuemax`
+- Always provide a `label` to give the bar a meaningful accessible name

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

@@ -0,0 +1,96 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../index'; // auto-registers all custom elements
+
+function BdsProgress({
+  value = 0,
+  max = 100,
+  label,
+  showLabel,
+  size = 'medium',
+}: {
+  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: 'centered' },
+  argTypes: {
+    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, 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 WithLabel: Story = {
+  render: () => (
+    <div style={{ width: 400 }}>
+      {React.createElement('bds-progress', {
+        value: 60,
+        label: 'Upload progress',
+        'show-label': true,
+        size: 'medium',
+      })}
+    </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

@@ -0,0 +1,70 @@
+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 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.
+
+## Installation
+
+```js
+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.AllSizes} />
+
+### Default
+<Canvas of={Stories.Default} />
+
+### With centred value
+<Canvas of={Stories.WithValue} />
+
+### Small
+<Canvas of={Stories.Small} />
+
+### Large
+<Canvas of={Stories.Large} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `value` | number | `0` | Current progress value |
+| `max` | number | `100` | Maximum value |
+| `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` | Stroke colour of the filled arc |
+
+## Usage in plain HTML
+
+```html
+<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 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

@@ -0,0 +1,57 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../index'; // auto-registers all custom elements
+
+function BdsProgressCircle({
+  value = 0,
+  max = 100,
+  label,
+  showValue,
+  size = 'medium',
+}: {
+  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: {
+    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, 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 AllSizes: Story = {
+  render: () => (
+    <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>
+  ),
+};

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 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.
+
+## Installation
+
+```js
+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 values
+<Canvas of={Stories.AllValues} />
+
+### Default (3 of 5)
+<Canvas of={Stories.Default} />
+
+### Full (5 of 5)
+<Canvas of={Stories.Full} />
+
+### Empty (0 of 5)
+<Canvas of={Stories.Empty} />
+
+### Custom max (7 of 10)
+<Canvas of={Stories.CustomMax} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `value` | number | `0` | Number of filled stars |
+| `max` | number | `5` | Total number of stars displayed |
+
+## Usage in plain HTML
+
+```html
+<bds-rating value="3"></bds-rating>
+<bds-rating value="4" max="10"></bds-rating>
+```
+
+## Accessibility
+
+- 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

@@ -0,0 +1,45 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../index'; // auto-registers all custom elements
+
+function BdsRating({
+  value = 0,
+  max = 5,
+}: {
+  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: 'range', min: 0, max: 10 } },
+    max:   { control: 'number' },
+  },
+} satisfies Meta<typeof BdsRating>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+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 AllValues: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
+      {[1, 2, 3, 4, 5].map(v => (
+        <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

@@ -0,0 +1,72 @@
+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. 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.
+
+## Installation
+
+```js
+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.AllSizes} />
+
+### Default
+<Canvas of={Stories.Default} />
+
+### Small
+<Canvas of={Stories.Small} />
+
+### Large
+<Canvas of={Stories.Large} />
+
+### Centered
+<Canvas of={Stories.Centered} />
+
+### Title only
+<Canvas of={Stories.TitleOnly} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `title` | string | — | Heading text (required) |
+| `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"
+  subtitle="Browse the full range"
+  size="large"
+  alignment="center">
+</bds-section-header>
+```
+
+## Accessibility
+
+- 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

@@ -0,0 +1,54 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../index'; // auto-registers all custom elements
+
+function BdsSectionHeader({
+  title = '',
+  subtitle,
+  alignment = 'start',
+  size = 'medium',
+  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'] },
+    titleAs:   { control: 'text' },
+  },
+} satisfies Meta<typeof BdsSectionHeader>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+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 AllSizes: Story = {
+  render: () => (
+    <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>
+  ),
+};