@boostdev/design-system-components 1.2.0 → 1.2.2

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

@@ -1,16 +1,18 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
 import type { LinkVariant } from './bds-link';
-import '../index';
+import '../index'; // auto-registers all custom elements
 
 function BdsLink({
-  href,
-  variant,
+  href = '#',
+  target,
+  variant = 'default',
   external,
   externalLabel,
   children,
 }: {
   href?: string;
+  target?: string;
   variant?: LinkVariant;
   external?: boolean;
   externalLabel?: string;
@@ -19,7 +21,8 @@ function BdsLink({
   return React.createElement(
     'bds-link',
     {
-      href: href ?? '#',
+      href,
+      target,
       variant,
       external: external || undefined,
       'external-label': externalLabel,
@@ -34,31 +37,27 @@ const meta = {
   tags: ['!stable', 'experimental'],
   parameters: { layout: 'centered' },
   argTypes: {
-    variant: { control: 'select', options: ['default', 'subtle', 'standalone'] },
+    variant:  { control: 'select', options: ['default', 'subtle', 'standalone'] },
+    external: { control: 'boolean' },
   },
 } satisfies Meta<typeof BdsLink>;
 
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-export const Default: Story = { args: { children: 'Default link', variant: 'default' } };
-export const Subtle: Story = { args: { children: 'Subtle link', variant: 'subtle' } };
-export const Standalone: Story = { args: { children: 'Standalone link →', variant: 'standalone' } };
-export const External: Story = { args: { children: 'External link', variant: 'default', external: true } };
+export const Default: Story = { args: { children: 'Default link', variant: 'default', href: '#' } };
+export const Subtle: Story = { args: { children: 'Subtle link', variant: 'subtle', href: '#' } };
+export const Standalone: Story = { args: { children: 'Standalone link', variant: 'standalone', href: '#' } };
+export const External: Story = {
+  args: { children: 'Visit our website', href: 'https://example.com', external: true },
+};
 
 export const AllVariants: Story = {
   render: () => (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
-      {(['default', 'subtle', 'standalone'] as const).map(v => (
-        <div key={v} style={{ display: 'flex', alignItems: 'center', gap: '12px' }}>
-          <BdsLink variant={v}>{v.charAt(0).toUpperCase() + v.slice(1)} link</BdsLink>
-          <span style={{ fontSize: '0.75rem', color: '#888' }}>{v}</span>
-        </div>
-      ))}
-      <div style={{ display: 'flex', alignItems: 'center', gap: '12px' }}>
-        <BdsLink external>External link</BdsLink>
-        <span style={{ fontSize: '0.75rem', color: '#888' }}>external</span>
-      </div>
+    <div style={{ display: 'flex', gap: 16, flexWrap: 'wrap', alignItems: 'center' }}>
+      {React.createElement('bds-link', { href: '#', variant: 'default' }, 'Default')}
+      {React.createElement('bds-link', { href: '#', variant: 'subtle' }, 'Subtle')}
+      {React.createElement('bds-link', { href: '#', variant: 'standalone' }, 'Standalone')}
     </div>
   ),
 };

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

@@ -5,7 +5,7 @@ import * as Stories from './BdsLoading.stories';
 
 # <bds-loading>
 
-Framework-agnostic Loading spinner custom element. Use to indicate an ongoing asynchronous operation.
+Framework-agnostic Loading spinner custom element. Displays an animated circular spinner to indicate that a process is in progress.
 
 > **Status: experimental** — API may change before stable release.
 
@@ -15,10 +15,15 @@ Framework-agnostic Loading spinner custom element. Use to indicate an ongoing as
 import '@boostdev/components/web-components';
 ```
 
+## When to use
+
+- While a page section or full page is loading content
+- As inline feedback during form submission or data fetching
+
 ## Examples
 
 ### All sizes
-<Canvas of={Stories.AllVariants} />
+<Canvas of={Stories.AllSizes} />
 
 ### Small
 <Canvas of={Stories.Small} />
@@ -39,15 +44,6 @@ import '@boostdev/components/web-components';
 |-----------|------|---------|-------------|
 | `size` | `"small" \| "medium" \| "large"` | `"medium"` | Spinner diameter |
 
-## CSS Custom Properties
-
-The spinner uses design tokens directly:
-
-| Token | Description |
-|-------|-------------|
-| `--bds-color_bg` | Track colour |
-| `--bds-color_interactive` | Active arc colour |
-
 ## Usage in plain HTML
 
 ```html
@@ -58,5 +54,5 @@ The spinner uses design tokens directly:
 
 ## Accessibility
 
-- Renders a `role="status"` element with `aria-label="Loading"` — screen readers announce the loading state
-- Respects `prefers-reduced-motion`: the spin animation stops for users who prefer reduced motion
+- Renders `role="status"` with `aria-label="Loading"` so screen readers announce the loading state
+- The spin animation is suppressed when `prefers-reduced-motion: reduce` is set

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

@@ -1,8 +1,8 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
-import '../index';
+import '../index'; // auto-registers all custom elements
 
-function BdsLoading({ size }: { size?: 'small' | 'medium' | 'large' }) {
+function BdsLoading({ size = 'medium' }: { size?: 'small' | 'medium' | 'large' }) {
   return React.createElement('bds-loading', { size });
 }
 
@@ -19,19 +19,17 @@ const meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
+export const Default: Story = { args: { size: 'medium' } };
 export const Small: Story = { args: { size: 'small' } };
 export const Medium: Story = { args: { size: 'medium' } };
 export const Large: Story = { args: { size: 'large' } };
 
-export const AllVariants: Story = {
+export const AllSizes: Story = {
   render: () => (
-    <div style={{ display: 'flex', alignItems: 'center', gap: '32px' }}>
-      {(['small', 'medium', 'large'] as const).map(s => (
-        <div key={s} style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: '8px' }}>
-          <BdsLoading size={s} />
-          <span style={{ fontSize: '0.75rem', color: '#888' }}>{s}</span>
-        </div>
-      ))}
+    <div style={{ display: 'flex', gap: 24, alignItems: 'center' }}>
+      {React.createElement('bds-loading', { size: 'small' })}
+      {React.createElement('bds-loading', { size: 'medium' })}
+      {React.createElement('bds-loading', { size: 'large' })}
     </div>
   ),
 };

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

@@ -5,7 +5,7 @@ import * as Stories from './BdsNotificationBanner.stories';
 
 # <bds-notification-banner>
 
-Framework-agnostic full-width Notification Banner. Use for page-level messages that require user attention — system notices, maintenance windows, or status updates.
+Framework-agnostic Notification Banner custom element. Renders a full-width status banner at the top of a page or section with optional dismiss button and action slot.
 
 > **Status: experimental** — API may change before stable release.
 
@@ -15,13 +15,31 @@ Framework-agnostic full-width Notification Banner. Use for page-level messages t
 import '@boostdev/components/web-components';
 ```
 
+## When to use
+
+- To surface page-level status messages (success after save, system errors, maintenance warnings)
+- Use `dismissible` when the user should be able to close the banner manually
+- Place an action element in the `action` slot for in-line links or undo buttons
+
 ## Examples
 
 ### All variants
 <Canvas of={Stories.AllVariants} />
 
+### Default (info)
+<Canvas of={Stories.Default} />
+
+### Success
+<Canvas of={Stories.Success} />
+
+### Warning
+<Canvas of={Stories.Warning} />
+
+### Error
+<Canvas of={Stories.Error} />
+
 ### Dismissible
-<Canvas of={Stories.Interactive} />
+<Canvas of={Stories.Dismissible} />
 
 ### With action
 <Canvas of={Stories.WithAction} />
@@ -34,57 +52,34 @@ import '@boostdev/components/web-components';
 
 | Attribute | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `variant` | `"info" \| "success" \| "warning" \| "error"` | `"info"` | Semantic colour and urgency |
+| `variant` | `"info" \| "success" \| "warning" \| "error"` | `"info"` | Visual style and semantic urgency |
 | `dismissible` | boolean | `false` | Shows a dismiss (×) button |
-| `dismiss-label` | string | `"Dismiss notification"` | Accessible label for the dismiss button |
+| `dismiss-label` | string | `"Dismiss notification"` | `aria-label` for the dismiss button |
 
 ## Slots
 
 | Slot | Description |
 |------|-------------|
-| `(default)` | Banner body content |
-| `action` | Optional action area (e.g. a button or link) |
+| `(default)` | Banner body text or HTML |
+| `action` | Optional action area (e.g. a `<button>` or `<a>`) |
 
 ## 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 |
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `bds-dismiss` | — | Fired when the dismiss button is clicked |
 
 ## Usage in plain HTML
 
 ```html
-<bds-notification-banner variant="success">
+<bds-notification-banner variant="success" dismissible>
   Your changes have been saved.
+  <button slot="action" type="button">Undo</button>
 </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
+- `error` and `warning` variants render `role="alert"` with `aria-live="assertive"`
+- `info` and `success` variants render `role="status"` with `aria-live="polite"`
+- The dismiss button has a configurable `aria-label` via `dismiss-label`

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

@@ -1,22 +1,20 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
 import type { NotificationBannerVariant } from './bds-notification-banner';
-import '../index';
+import '../index'; // auto-registers all custom elements
 
 function BdsNotificationBanner({
   variant = 'info',
   dismissible,
   dismissLabel,
-  onDismiss,
-  action,
   children,
+  action,
 }: {
   variant?: NotificationBannerVariant;
   dismissible?: boolean;
   dismissLabel?: string;
-  onDismiss?: () => void;
-  action?: React.ReactNode;
   children?: React.ReactNode;
+  action?: React.ReactNode;
 }) {
   return React.createElement(
     'bds-notification-banner',
@@ -24,10 +22,11 @@ function BdsNotificationBanner({
       variant,
       dismissible: dismissible || undefined,
       'dismiss-label': dismissLabel,
-      onbdsdismiss: onDismiss,
     },
     children,
-    action ? React.createElement('span', { slot: 'action' }, action) : null,
+    action
+      ? React.createElement('span', { slot: 'action' }, action)
+      : undefined,
   );
 }
 
@@ -35,59 +34,51 @@ const meta = {
   title: 'Web Components/UI/NotificationBanner',
   component: BdsNotificationBanner,
   tags: ['!stable', 'experimental'],
-  parameters: { layout: 'padded' },
+  parameters: { layout: 'fullscreen' },
   argTypes: {
     variant: { control: 'select', options: ['info', 'success', 'warning', 'error'] },
+    dismissible: { control: 'boolean' },
   },
 } 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 Default: Story = {
+  args: { children: 'This is an informational banner.', variant: 'info' },
+};
+export const Success: Story = {
+  args: { children: 'Your changes have been saved successfully.', variant: 'success' },
+};
+export const Warning: Story = {
+  args: { children: 'Please review your settings before continuing.', variant: 'warning' },
+};
+export const Error: Story = {
+  args: { children: 'An error occurred. Please try again.', variant: 'error' },
+};
+export const Dismissible: Story = {
+  args: { children: 'You can dismiss this banner.', 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>
-  ),
+  render: () =>
+    React.createElement(
+      'bds-notification-banner',
+      { variant: 'success' },
+      'Your file has been uploaded.',
+      React.createElement('button', { slot: 'action', type: 'button' }, 'Undo'),
+    ),
 };
 
 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 style={{ display: 'flex', flexDirection: 'column', gap: 0 }}>
+      {(['info', 'success', 'warning', 'error'] as const).map(v =>
+        React.createElement(
+          'bds-notification-banner',
+          { key: v, variant: v },
+          `This is a ${v} notification banner.`,
+        ),
+      )}
     </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/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

@@ -5,7 +5,7 @@ import * as Stories from './BdsProgress.stories';
 
 # <bds-progress>
 
-Framework-agnostic linear Progress bar custom element. Use to show completion status of a task or upload.
+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.
 
@@ -15,16 +15,27 @@ Framework-agnostic linear Progress bar custom element. Use to show completion st
 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 values
-<Canvas of={Stories.AllVariants} />
+### All sizes
+<Canvas of={Stories.AllSizes} />
+
+### Default
+<Canvas of={Stories.Default} />
 
 ### With label
 <Canvas of={Stories.WithLabel} />
 
-### Animated
-<Canvas of={Stories.Interactive} />
+### Small
+<Canvas of={Stories.Small} />
+
+### Large
+<Canvas of={Stories.Large} />
 
 ## Props
 
@@ -36,28 +47,24 @@ import '@boostdev/components/web-components';
 |-----------|------|---------|-------------|
 | `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 |
+| `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 (defaults to `--bdc-color_active`) |
+| `--progress_color-active` | Fill colour of the progress bar |
 
 ## 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>
+<bds-progress value="60" label="Upload progress" show-label></bds-progress>
+<bds-progress value="30" size="small" label="Loading"></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`
+- Renders with `role="progressbar"`, `aria-valuenow`, `aria-valuemin`, and `aria-valuemax`
+- Always provide a `label` to give the bar a meaningful accessible name