@boostdev/design-system-components 1.1.2 → 1.2.0

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

@@ -0,0 +1,90 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import type { CardVariant, CardPadding, CardTextAlign } from './bds-card';
+import '../index';
+
+function BdsCard({
+  variant,
+  padding,
+  textAlign,
+  clickable,
+  ariaLabel,
+  onClick,
+  children,
+}: {
+  variant?: CardVariant;
+  padding?: CardPadding;
+  textAlign?: CardTextAlign;
+  clickable?: boolean;
+  ariaLabel?: string;
+  onClick?: () => void;
+  children?: React.ReactNode;
+}) {
+  return React.createElement(
+    'bds-card',
+    {
+      variant,
+      padding,
+      'text-align': textAlign,
+      clickable: clickable || undefined,
+      'aria-label': ariaLabel,
+      onbdsclick: onClick,
+    },
+    children,
+  );
+}
+
+const meta = {
+  title: 'Web Components/UI/Card',
+  component: BdsCard,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    variant: { control: 'select', options: ['default', 'elevated', 'outlined'] },
+    padding: { control: 'select', options: ['none', 'small', 'medium', 'large'] },
+    textAlign: { control: 'select', options: ['start', 'center', 'end'] },
+  },
+} satisfies Meta<typeof BdsCard>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const cardContent = React.createElement(
+  'div',
+  null,
+  React.createElement('strong', null, 'Card title'),
+  React.createElement('p', { style: { margin: '8px 0 0' } }, 'Card body with some descriptive text.'),
+);
+
+export const Default: Story = { args: { variant: 'default', children: cardContent } };
+export const Elevated: Story = { args: { variant: 'elevated', children: cardContent } };
+export const Outlined: Story = { args: { variant: 'outlined', children: cardContent } };
+export const Clickable: Story = { args: { variant: 'default', clickable: true, ariaLabel: 'Open details', children: cardContent } };
+
+export const AllVariants: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: '16px', flexWrap: 'wrap' }}>
+      {(['default', 'elevated', 'outlined'] as const).map(v => (
+        <BdsCard key={v} variant={v} style={{ width: '200px' } as React.CSSProperties}>
+          <strong>{v}</strong>
+          <p style={{ margin: '8px 0 0' }}>Card variant</p>
+        </BdsCard>
+      ))}
+    </div>
+  ),
+};
+
+export const Interactive: Story = {
+  render: () => {
+    const [count, setCount] = React.useState(0);
+    return (
+      <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: '16px' }}>
+        <BdsCard variant="elevated" clickable ariaLabel="Click me" onClick={() => setCount(c => c + 1)}>
+          <strong>Clickable card</strong>
+          <p style={{ margin: '8px 0 0' }}>Click to increment counter</p>
+        </BdsCard>
+        <p style={{ margin: 0 }}>Clicked {count} times</p>
+      </div>
+    );
+  },
+};

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

@@ -0,0 +1,67 @@
+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 a semantic `<dl>` element for rendering key–value pairs. Consumers provide `<dt>` and `<dd>` elements as slotted children.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## Examples
+
+### All layouts
+<Canvas of={Stories.AllVariants} />
+
+### Stacked
+<Canvas of={Stories.Stacked} />
+
+### Inline
+<Canvas of={Stories.Inline} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `layout` | `"stacked" \| "inline"` | `"stacked"` | Arrangement of terms and details |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `(default)` | `<dt>` and `<dd>` element pairs |
+
+## Usage in plain HTML
+
+```html
+<bds-description-list>
+  <dt>Name</dt>
+  <dd>Jane Doe</dd>
+  <dt>Email</dt>
+  <dd>jane@example.com</dd>
+</bds-description-list>
+
+<bds-description-list layout="inline">
+  <dt>Status</dt>
+  <dd>Active</dd>
+  <dt>Role</dt>
+  <dd>Designer</dd>
+</bds-description-list>
+```
+
+## Accessibility
+
+- Renders a semantic `<dl>` element — screen readers announce it as a description list
+- Ensure `<dt>` and `<dd>` elements are properly paired
+- The `::slotted(dt)` and `::slotted(dd)` CSS selectors apply the visual styling

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