@boostdev/design-system-components 1.1.1 → 1.2.0

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

@@ -0,0 +1,79 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../index';
+
+function BdsDescriptionList({
+  layout,
+  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: 'select', options: ['stacked', 'inline'] },
+  },
+} satisfies Meta<typeof BdsDescriptionList>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const items = [
+  { term: 'Name', detail: 'Jane Doe' },
+  { term: 'Email', detail: 'jane@example.com' },
+  { term: 'Role', detail: 'Designer' },
+];
+
+export const Stacked: Story = {
+  render: () => (
+    <BdsDescriptionList layout="stacked">
+      {items.flatMap(({ term, detail }) => [
+        React.createElement('dt', { key: `dt-${term}` }, term),
+        React.createElement('dd', { key: `dd-${term}` }, detail),
+      ])}
+    </BdsDescriptionList>
+  ),
+};
+
+export const Inline: Story = {
+  render: () => (
+    <BdsDescriptionList layout="inline">
+      {items.flatMap(({ term, detail }) => [
+        React.createElement('dt', { key: `dt-${term}` }, term),
+        React.createElement('dd', { key: `dd-${term}` }, detail),
+      ])}
+    </BdsDescriptionList>
+  ),
+};
+
+export const AllVariants: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: '48px', flexWrap: 'wrap', alignItems: 'flex-start' }}>
+      <div>
+        <p style={{ margin: '0 0 8px', fontSize: '0.75rem', color: '#888', fontWeight: 600 }}>Stacked</p>
+        <BdsDescriptionList layout="stacked">
+          {items.flatMap(({ term, detail }) => [
+            React.createElement('dt', { key: `dt-${term}` }, term),
+            React.createElement('dd', { key: `dd-${term}` }, detail),
+          ])}
+        </BdsDescriptionList>
+      </div>
+      <div>
+        <p style={{ margin: '0 0 8px', fontSize: '0.75rem', color: '#888', fontWeight: 600 }}>Inline</p>
+        <BdsDescriptionList layout="inline">
+          {items.flatMap(({ term, detail }) => [
+            React.createElement('dt', { key: `dt-${term}` }, term),
+            React.createElement('dd', { key: `dd-${term}` }, detail),
+          ])}
+        </BdsDescriptionList>
+      </div>
+    </div>
+  ),
+};

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 an icon inside a circular container with background and foreground theming.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## Examples
+
+### All variants
+<Canvas of={Stories.AllVariants} />
+
+### With star icon
+<Canvas of={Stories.WithStar} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `aria-hidden` | string | — | Set to `"true"` for purely decorative icons |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `(default)` | Icon content (SVG or `<img>`) |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--icon-wrapper-color` | Circle background colour |
+| `--bds-on-icon-wrapper-color` | Icon fill/stroke colour |
+
+## Usage in plain HTML
+
+```html
+<!-- Decorative icon -->
+<bds-icon-wrapper aria-hidden="true">
+  <svg viewBox="0 0 24 24" fill="currentColor">
+    <path d="M12 17.27L18.18 21..."/>
+  </svg>
+</bds-icon-wrapper>
+
+<!-- Meaningful icon — add aria-label to the wrapper -->
+<bds-icon-wrapper aria-label="Favourite">
+  <svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+    <path d="M12 21.593c..."/>
+  </svg>
+</bds-icon-wrapper>
+```
+
+## Accessibility
+
+- When the icon is decorative, set `aria-hidden="true"` on the host
+- When the icon conveys meaning, set `aria-label` on the host and `aria-hidden="true"` on the SVG itself

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

@@ -0,0 +1,76 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../index';
+
+const StarIcon = () =>
+  React.createElement(
+    'svg',
+    { viewBox: '0 0 24 24', fill: 'currentColor', width: '1.25em', height: '1.25em', 'aria-hidden': 'true' },
+    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',
+    }),
+  );
+
+const CheckIcon = () =>
+  React.createElement(
+    'svg',
+    { viewBox: '0 0 24 24', fill: 'none', stroke: 'currentColor', strokeWidth: '2.5', width: '1.25em', height: '1.25em', 'aria-hidden': 'true' },
+    React.createElement('path', { strokeLinecap: 'round', strokeLinejoin: 'round', d: 'M5 13l4 4L19 7' }),
+  );
+
+const HeartIcon = () =>
+  React.createElement(
+    'svg',
+    { viewBox: '0 0 24 24', fill: 'currentColor', width: '1.25em', height: '1.25em', 'aria-hidden': 'true' },
+    React.createElement('path', {
+      d: 'M12 21.593c-.425-.052-8.092-5.65-8.092-10.82C3.908 6.64 7.084 4 10.408 4c1.75 0 3.192.806 4.175 2.016A5.355 5.355 0 0 1 18.175 4c3.324 0 6.5 2.64 6.5 6.773 0 5.17-7.667 10.768-8.092 10.82z',
+    }),
+  );
+
+function BdsIconWrapper({ children }: { children?: React.ReactNode }) {
+  return React.createElement('bds-icon-wrapper', null, children);
+}
+
+const meta = {
+  title: 'Web Components/UI/IconWrapper',
+  component: BdsIconWrapper,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+} satisfies Meta<typeof BdsIconWrapper>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const WithStar: Story = {
+  render: () => (
+    <BdsIconWrapper>
+      <StarIcon />
+    </BdsIconWrapper>
+  ),
+};
+
+export const WithCheck: Story = {
+  render: () => (
+    <BdsIconWrapper>
+      <CheckIcon />
+    </BdsIconWrapper>
+  ),
+};
+
+export const WithHeart: Story = {
+  render: () => (
+    <BdsIconWrapper>
+      <HeartIcon />
+    </BdsIconWrapper>
+  ),
+};
+
+export const AllVariants: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: '16px', alignItems: 'center' }}>
+      <BdsIconWrapper><StarIcon /></BdsIconWrapper>
+      <BdsIconWrapper><CheckIcon /></BdsIconWrapper>
+      <BdsIconWrapper><HeartIcon /></BdsIconWrapper>
+    </div>
+  ),
+};

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

@@ -0,0 +1,75 @@
+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 semantic `<a>` element with three visual styles and built-in external link handling.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## Examples
+
+### All variants
+<Canvas of={Stories.AllVariants} />
+
+### Default
+<Canvas of={Stories.Default} />
+
+### Standalone
+<Canvas of={Stories.Standalone} />
+
+### External
+<Canvas of={Stories.External} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `href` | string | — | Link destination |
+| `target` | string | — | Native anchor target |
+| `variant` | `"default" \| "subtle" \| "standalone"` | `"default"` | Visual style |
+| `external` | boolean | `false` | Adds `rel="noreferrer noopener"`, opens in new tab, appends screen-reader text |
+| `external-label` | string | `"(opens in new tab)"` | Visually-hidden text appended for external links |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `(default)` | Link text content |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--link_color` | Link text colour |
+| `--link_color-hover` | Link colour on hover |
+
+## Usage in plain HTML
+
+```html
+<bds-link href="/docs">Read the docs</bds-link>
+
+<bds-link href="/about" variant="subtle">About us</bds-link>
+
+<bds-link href="/get-started" variant="standalone">Get started →</bds-link>
+
+<bds-link href="https://example.com" external>Visit site</bds-link>
+```
+
+## Accessibility
+
+- Renders a native `<a>` — fully keyboard accessible
+- `external` adds a visually-hidden `(opens in new tab)` label for screen reader users and sets `rel="noreferrer noopener"` for security
+- Always provide meaningful link text — avoid "click here" or "read more"

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

@@ -0,0 +1,64 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import type { LinkVariant } from './bds-link';
+import '../index';
+
+function BdsLink({
+  href,
+  variant,
+  external,
+  externalLabel,
+  children,
+}: {
+  href?: string;
+  variant?: LinkVariant;
+  external?: boolean;
+  externalLabel?: string;
+  children?: React.ReactNode;
+}) {
+  return React.createElement(
+    'bds-link',
+    {
+      href: href ?? '#',
+      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'] },
+  },
+} 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 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>
+  ),
+};

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

@@ -0,0 +1,62 @@
+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. Use to indicate an ongoing asynchronous operation.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## Examples
+
+### All sizes
+<Canvas of={Stories.AllVariants} />
+
+### 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 |
+
+## 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
+<bds-loading></bds-loading>
+<bds-loading size="small"></bds-loading>
+<bds-loading size="large"></bds-loading>
+```
+
+## 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

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

@@ -0,0 +1,37 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../index';
+
+function BdsLoading({ size }: { 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 Small: Story = { args: { size: 'small' } };
+export const Medium: Story = { args: { size: 'medium' } };
+export const Large: Story = { args: { size: 'large' } };
+
+export const AllVariants: 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>
+  ),
+};

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