@boostdev/design-system-components 1.1.2 → 1.2.1

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

@@ -0,0 +1,64 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsDescriptionList.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-description-list&gt;
+
+Framework-agnostic Description List custom element. Wraps slotted `<dt>`/`<dd>` pairs in a styled `<dl>` with stacked or inline layout.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## When to use
+
+- Displaying key–value data such as user profiles, settings summaries, or metadata panels
+- Use `layout="inline"` to place term and value side-by-side on wider screens
+
+## Examples
+
+### Default (stacked)
+<Canvas of={Stories.Default} />
+
+### Stacked
+<Canvas of={Stories.Stacked} />
+
+### Inline
+<Canvas of={Stories.Inline} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `layout` | `"stacked" \| "inline"` | `"stacked"` | Display mode — stacked places term above value; inline places them side-by-side |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `(default)` | `<dt>` and `<dd>` pairs |
+
+## Usage in plain HTML
+
+```html
+<bds-description-list layout="inline">
+  <dt>Name</dt>
+  <dd>Jane Doe</dd>
+  <dt>Email</dt>
+  <dd>jane@example.com</dd>
+</bds-description-list>
+```
+
+## Accessibility
+
+- Renders a native `<dl>` element — screen readers announce it as a description list
+- Ensure every `<dt>` has a corresponding `<dd>`

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

@@ -0,0 +1,64 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../index'; // auto-registers all custom elements
+
+function BdsDescriptionList({
+  layout = 'stacked',
+  children,
+}: {
+  layout?: 'stacked' | 'inline';
+  children?: React.ReactNode;
+}) {
+  return React.createElement('bds-description-list', { layout }, children);
+}
+
+const meta = {
+  title: 'Web Components/UI/DescriptionList',
+  component: BdsDescriptionList,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    layout: { control: 'radio', options: ['stacked', 'inline'] },
+  },
+} satisfies Meta<typeof BdsDescriptionList>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () =>
+    React.createElement(
+      'bds-description-list',
+      { layout: 'stacked' },
+      React.createElement('dt', null, 'Name'),
+      React.createElement('dd', null, 'Jane Doe'),
+      React.createElement('dt', null, 'Email'),
+      React.createElement('dd', null, 'jane@example.com'),
+      React.createElement('dt', null, 'Role'),
+      React.createElement('dd', null, 'Administrator'),
+    ),
+};
+
+export const Stacked: Story = {
+  render: () =>
+    React.createElement(
+      'bds-description-list',
+      { layout: 'stacked' },
+      React.createElement('dt', null, 'Framework'),
+      React.createElement('dd', null, 'Lit'),
+      React.createElement('dt', null, 'Language'),
+      React.createElement('dd', null, 'TypeScript'),
+    ),
+};
+
+export const Inline: Story = {
+  render: () =>
+    React.createElement(
+      'bds-description-list',
+      { layout: 'inline' },
+      React.createElement('dt', null, 'Status'),
+      React.createElement('dd', null, 'Active'),
+      React.createElement('dt', null, 'Plan'),
+      React.createElement('dd', null, 'Professional'),
+    ),
+};

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

@@ -0,0 +1,70 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsIconWrapper.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-icon-wrapper&gt;
+
+Framework-agnostic Icon Wrapper custom element. Displays a slotted icon inside a circular container with design-system background and foreground colour theming.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## When to use
+
+- To visually highlight a feature icon in a card, empty state, or marketing section
+- Use `aria-hidden="true"` when the icon is purely decorative and adjacent text provides the label
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### With label
+<Canvas of={Stories.WithLabel} />
+
+### Multiple
+<Canvas of={Stories.Multiple} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `aria-hidden` | string | — | Set to `"true"` for decorative icons |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `(default)` | Icon content (SVG or `<img>`) |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--icon-wrapper-color` | Background fill of the circular container |
+| `--bds-on-icon-wrapper-color` | Icon/foreground colour inside the wrapper |
+
+## Usage in plain HTML
+
+```html
+<bds-icon-wrapper aria-hidden="true">
+  <svg viewBox="0 0 24 24" fill="currentColor" width="24" height="24">
+    <path d="M12 2l3.09 6.26L22 9.27l-5 4.87L18.18 21 12 17.77 5.82 21 7 14.14 2 9.27l6.91-1.01z"/>
+  </svg>
+</bds-icon-wrapper>
+```
+
+## Accessibility
+
+- Use `aria-hidden="true"` when the icon is decorative and the surrounding content provides context
+- When the icon is standalone and meaningful, omit `aria-hidden` and provide a label via adjacent text or `aria-label` on the wrapper

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

@@ -0,0 +1,81 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../index'; // auto-registers all custom elements
+
+// Simple star SVG for demonstration
+const StarIcon = () =>
+  React.createElement(
+    'svg',
+    { xmlns: 'http://www.w3.org/2000/svg', viewBox: '0 0 24 24', fill: 'currentColor', width: 24, height: 24 },
+    React.createElement('path', {
+      d: 'M12 17.27L18.18 21l-1.64-7.03L22 9.24l-7.19-.61L12 2 9.19 8.63 2 9.24l5.46 4.73L5.82 21z',
+    }),
+  );
+
+function BdsIconWrapper({
+  ariaHidden,
+  children,
+}: {
+  ariaHidden?: string;
+  children?: React.ReactNode;
+}) {
+  return React.createElement('bds-icon-wrapper', { 'aria-hidden': ariaHidden }, children);
+}
+
+const meta = {
+  title: 'Web Components/UI/IconWrapper',
+  component: BdsIconWrapper,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    ariaHidden: { control: 'text' },
+  },
+} satisfies Meta<typeof BdsIconWrapper>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () =>
+    React.createElement(
+      'bds-icon-wrapper',
+      { 'aria-hidden': 'true' },
+      React.createElement(StarIcon),
+    ),
+};
+
+export const Decorative: Story = {
+  render: () =>
+    React.createElement(
+      'bds-icon-wrapper',
+      { 'aria-hidden': 'true' },
+      React.createElement(StarIcon),
+    ),
+};
+
+export const WithLabel: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 8 }}>
+      {React.createElement(
+        'bds-icon-wrapper',
+        {},
+        React.createElement(StarIcon),
+      )}
+      <span>Favourites</span>
+    </div>
+  ),
+};
+
+export const Multiple: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: 16 }}>
+      {[1, 2, 3].map(i =>
+        React.createElement(
+          'bds-icon-wrapper',
+          { key: i, 'aria-hidden': 'true' },
+          React.createElement(StarIcon),
+        ),
+      )}
+    </div>
+  ),
+};

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

@@ -0,0 +1,79 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsLink.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-link&gt;
+
+Framework-agnostic Link custom element. Renders a styled `<a>` tag with three visual variants, automatic external link handling, and design-token colours.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## When to use
+
+- Inline hyperlinks within body text (default or subtle)
+- Standalone call-to-action links that should look more prominent (standalone)
+- External links that automatically get `rel="noreferrer noopener"` and a screen reader suffix
+
+## Examples
+
+### All variants
+<Canvas of={Stories.AllVariants} />
+
+### Default
+<Canvas of={Stories.Default} />
+
+### Subtle
+<Canvas of={Stories.Subtle} />
+
+### Standalone
+<Canvas of={Stories.Standalone} />
+
+### External
+<Canvas of={Stories.External} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `href` | string | — | Link destination URL |
+| `target` | string | — | Standard `<a>` target attribute |
+| `variant` | `"default" \| "subtle" \| "standalone"` | `"default"` | Visual style |
+| `external` | boolean | `false` | Adds `rel="noreferrer noopener"`, forces `target="_blank"`, and appends a visually-hidden screen reader label |
+| `external-label` | string | `"(opens in new tab)"` | Screen reader text appended when `external` is set |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `(default)` | Link text or content |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--link_color` | Link colour |
+| `--link_color-hover` | Link hover colour |
+
+## Usage in plain HTML
+
+```html
+<bds-link href="https://example.com" external>Visit site</bds-link>
+<p>Read our <bds-link href="/privacy">privacy policy</bds-link>.</p>
+<bds-link href="/docs" variant="standalone">View documentation</bds-link>
+```
+
+## Accessibility
+
+- When `external` is set, a visually-hidden `<span>` with configurable text is appended for screen readers
+- Ensure `href` always points to a valid destination

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

@@ -0,0 +1,63 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import type { LinkVariant } from './bds-link';
+import '../index'; // auto-registers all custom elements
+
+function BdsLink({
+  href = '#',
+  target,
+  variant = 'default',
+  external,
+  externalLabel,
+  children,
+}: {
+  href?: string;
+  target?: string;
+  variant?: LinkVariant;
+  external?: boolean;
+  externalLabel?: string;
+  children?: React.ReactNode;
+}) {
+  return React.createElement(
+    'bds-link',
+    {
+      href,
+      target,
+      variant,
+      external: external || undefined,
+      'external-label': externalLabel,
+    },
+    children,
+  );
+}
+
+const meta = {
+  title: 'Web Components/UI/Link',
+  component: BdsLink,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    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', 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', 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

@@ -0,0 +1,58 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsLoading.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-loading&gt;
+
+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.
+
+## Installation
+
+```js
+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.AllSizes} />
+
+### Small
+<Canvas of={Stories.Small} />
+
+### Medium
+<Canvas of={Stories.Medium} />
+
+### Large
+<Canvas of={Stories.Large} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `size` | `"small" \| "medium" \| "large"` | `"medium"` | Spinner diameter |
+
+## Usage in plain HTML
+
+```html
+<bds-loading></bds-loading>
+<bds-loading size="small"></bds-loading>
+<bds-loading size="large"></bds-loading>
+```
+
+## Accessibility
+
+- 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

@@ -0,0 +1,35 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../index'; // auto-registers all custom elements
+
+function BdsLoading({ size = 'medium' }: { size?: 'small' | 'medium' | 'large' }) {
+  return React.createElement('bds-loading', { size });
+}
+
+const meta = {
+  title: 'Web Components/UI/Loading',
+  component: BdsLoading,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    size: { control: 'select', options: ['small', 'medium', 'large'] },
+  },
+} satisfies Meta<typeof BdsLoading>;
+
+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 AllSizes: Story = {
+  render: () => (
+    <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

@@ -0,0 +1,85 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsNotificationBanner.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-notification-banner&gt;
+
+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.
+
+## Installation
+
+```js
+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.Dismissible} />
+
+### With action
+<Canvas of={Stories.WithAction} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `variant` | `"info" \| "success" \| "warning" \| "error"` | `"info"` | Visual style and semantic urgency |
+| `dismissible` | boolean | `false` | Shows a dismiss (×) button |
+| `dismiss-label` | string | `"Dismiss notification"` | `aria-label` for the dismiss button |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `(default)` | Banner body text or HTML |
+| `action` | Optional action area (e.g. a `<button>` or `<a>`) |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `bds-dismiss` | — | Fired when the dismiss button is clicked |
+
+## Usage in plain HTML
+
+```html
+<bds-notification-banner variant="success" dismissible>
+  Your changes have been saved.
+  <button slot="action" type="button">Undo</button>
+</bds-notification-banner>
+```
+
+## Accessibility
+
+- `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

@@ -0,0 +1,84 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import type { NotificationBannerVariant } from './bds-notification-banner';
+import '../index'; // auto-registers all custom elements
+
+function BdsNotificationBanner({
+  variant = 'info',
+  dismissible,
+  dismissLabel,
+  children,
+  action,
+}: {
+  variant?: NotificationBannerVariant;
+  dismissible?: boolean;
+  dismissLabel?: string;
+  children?: React.ReactNode;
+  action?: React.ReactNode;
+}) {
+  return React.createElement(
+    'bds-notification-banner',
+    {
+      variant,
+      dismissible: dismissible || undefined,
+      'dismiss-label': dismissLabel,
+    },
+    children,
+    action
+      ? React.createElement('span', { slot: 'action' }, action)
+      : undefined,
+  );
+}
+
+const meta = {
+  title: 'Web Components/UI/NotificationBanner',
+  component: BdsNotificationBanner,
+  tags: ['!stable', 'experimental'],
+  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 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: () =>
+    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 =>
+        React.createElement(
+          'bds-notification-banner',
+          { key: v, variant: v },
+          `This is a ${v} notification banner.`,
+        ),
+      )}
+    </div>
+  ),
+};