@boostdev/design-system-components 1.1.1 → 1.2.0

package/src/web-components/interaction/form/bds-textarea.ts

@@ -0,0 +1,141 @@
+import { LitElement, css, html } from 'lit';
+
+/**
+ * `<bds-textarea>` — form-associated Textarea custom element.
+ *
+ * Wraps a native `<textarea>` for consistent styling while participating
+ * in HTML forms via the Form-Associated Custom Elements API.
+ *
+ * Attributes:
+ *   name        — form field name
+ *   value       — text value
+ *   placeholder — placeholder text
+ *   rows        — number of visible rows (default: 4)
+ *   required    — boolean
+ *   disabled    — boolean
+ *
+ * Events:
+ *   input  — native input event
+ *   change — native change event
+ *
+ * @example
+ * <bds-textarea name="message" placeholder="Enter message…" rows="6"></bds-textarea>
+ */
+export class BdsTextarea extends LitElement {
+  static formAssociated = true;
+
+  static styles = css`
+    :host {
+      display: block;
+    }
+
+    :host([disabled]) {
+      opacity: 0.5;
+      pointer-events: none;
+    }
+
+    .textarea {
+      inline-size: 100%;
+      font-family: var(--bds-font_family--body);
+      font-size: var(--bds-font_size--body);
+      line-height: var(--bds-font_line-height--body);
+      padding: var(--bds-space_s);
+      border: none;
+      --bdc_color: currentcolor;
+      --bdc-outline_radius: var(--bds-border_radius--xs);
+
+      border-radius: var(--textarea_radius, var(--bdc-outline_radius));
+      box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color), var(--textarea_shadow, var(--bdc-outline_shadow));
+      background-color: var(--textarea_color_bg, var(--bds-color_bg));
+      color: var(--textarea_color, var(--bds-color_on-bg));
+      resize: vertical;
+      min-block-size: calc(var(--bds-space_m) * 5);
+      box-sizing: border-box;
+      transition: --bdc_color var(--bds-animation_transition-duration) var(--bds-animation_easing),
+                  background-color var(--bds-animation_transition-duration) var(--bds-animation_easing);
+    }
+
+    .textarea:focus {
+      --bdc_color: var(--bdc_color--focus);
+    }
+
+    .textarea:focus-visible {
+      outline: var(--bds-outline_default);
+      outline-offset: var(--bds-outline_offset);
+    }
+
+    .textarea:disabled {
+      opacity: 0.5;
+      cursor: not-allowed;
+      resize: none;
+    }
+  `;
+
+  static properties = {
+    name:        { type: String, reflect: true },
+    value:       { type: String },
+    placeholder: { type: String },
+    rows:        { type: Number },
+    required:    { type: Boolean, reflect: true },
+    disabled:    { type: Boolean, reflect: true },
+  };
+
+  declare name: string;
+  declare value: string;
+  declare placeholder: string;
+  declare rows: number;
+  declare required: boolean;
+  declare disabled: boolean;
+
+  private _internals!: ElementInternals;
+
+  constructor() {
+    super();
+    this._internals = this.attachInternals();
+    this.name = '';
+    this.value = '';
+    this.placeholder = '';
+    this.rows = 4;
+    this.required = false;
+    this.disabled = false;
+  }
+
+  updated(changed: Map<string, unknown>) {
+    super.updated(changed);
+    if (changed.has('value')) {
+      this._internals.setFormValue?.(this.value || null);
+    }
+  }
+
+  formResetCallback() {
+    this.value = '';
+    this._internals.setFormValue?.(null);
+  }
+
+  private _handleInput(e: Event) {
+    this.value = (e.target as HTMLTextAreaElement).value;
+  }
+
+  render() {
+    return html`
+      <textarea
+        class="textarea"
+        name=${this.name}
+        .value=${this.value}
+        placeholder=${this.placeholder}
+        rows=${this.rows}
+        ?required=${this.required}
+        ?disabled=${this.disabled}
+        @input=${this._handleInput}
+      ></textarea>
+    `;
+  }
+}
+
+customElements.define('bds-textarea', BdsTextarea);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-textarea': BdsTextarea;
+  }
+}

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

@@ -0,0 +1,67 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsAvatar.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-avatar&gt;
+
+Framework-agnostic Avatar custom element. Displays a profile image when `src` is set; falls back to initials derived from the `name` attribute.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## Examples
+
+### All sizes
+<Canvas of={Stories.AllSizes} />
+
+### With initials
+<Canvas of={Stories.Default} />
+
+### All variants
+<Canvas of={Stories.AllVariants} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `name` | string | — | Full name; used to compute initials and as `aria-label` fallback |
+| `src` | string | — | Image URL; when set, shows the image instead of initials |
+| `alt` | string | — | Alt text for the image (defaults to `name`) |
+| `size` | `"small" \| "medium" \| "large"` | `"medium"` | Avatar diameter (`2em` / `3em` / `4.5em`) |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--avatar_size` | Override the diameter directly |
+| `--avatar_bg` | Fallback background colour (defaults to `--bds-color_blue`) |
+| `--avatar_text` | Initials text colour (defaults to `--bds-color_on-blue`) |
+
+## Usage in plain HTML
+
+```html
+<!-- Initials fallback -->
+<bds-avatar name="Jane Doe"></bds-avatar>
+
+<!-- With image -->
+<bds-avatar src="/path/to/photo.jpg" name="Jane Doe" alt="Jane Doe's avatar"></bds-avatar>
+
+<!-- Large size -->
+<bds-avatar name="John Smith" size="large"></bds-avatar>
+```
+
+## Accessibility
+
+- When showing initials: renders `role="img"` with `aria-label` set to the `name` value
+- When showing an image: renders a standard `<img>` with `alt` text
+- Initials are hidden from assistive technology (`aria-hidden="true"`) — the label is on the container

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

@@ -0,0 +1,62 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../index';
+
+function BdsAvatar({
+  name,
+  src,
+  alt,
+  size,
+}: {
+  name?: string;
+  src?: string;
+  alt?: string;
+  size?: 'small' | 'medium' | 'large';
+}) {
+  return React.createElement('bds-avatar', { name, src, alt, size });
+}
+
+const meta = {
+  title: 'Web Components/UI/Avatar',
+  component: BdsAvatar,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    size: { control: 'select', options: ['small', 'medium', 'large'] },
+  },
+} satisfies Meta<typeof BdsAvatar>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = { args: { name: 'Jane Doe' } };
+export const SingleInitial: Story = { args: { name: 'Jane' } };
+export const Small: Story = { args: { name: 'Jane Doe', size: 'small' } };
+export const Medium: Story = { args: { name: 'Jane Doe', size: 'medium' } };
+export const Large: Story = { args: { name: 'Jane Doe', size: 'large' } };
+
+export const AllSizes: Story = {
+  render: () => (
+    <div style={{ display: 'flex', alignItems: 'center', gap: '24px' }}>
+      {(['small', 'medium', 'large'] as const).map(s => (
+        <div key={s} style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: '8px' }}>
+          <BdsAvatar name="Jane Doe" size={s} />
+          <span style={{ fontSize: '0.75rem', color: '#888' }}>{s}</span>
+        </div>
+      ))}
+    </div>
+  ),
+};
+
+export const AllVariants: Story = {
+  render: () => (
+    <div style={{ display: 'flex', alignItems: 'center', gap: '16px', flexWrap: 'wrap' }}>
+      <BdsAvatar name="Jane Doe" />
+      <BdsAvatar name="John Smith" />
+      <BdsAvatar name="Alice" />
+      <BdsAvatar name="Bob" />
+      <BdsAvatar name="Jane Doe" size="small" />
+      <BdsAvatar name="Jane Doe" size="large" />
+    </div>
+  ),
+};

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

@@ -0,0 +1,63 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsBreadcrumb.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-breadcrumb&gt;
+
+Framework-agnostic Breadcrumb navigation custom element. Renders an ordered list of links showing the user's location in the site hierarchy.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## Examples
+
+### Default (3 levels)
+<Canvas of={Stories.Default} />
+
+### Deep nested
+<Canvas of={Stories.DeepNested} />
+
+### All variants
+<Canvas of={Stories.AllVariants} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `items` | JSON string | `"[]"` | Array of `{ label: string, href?: string }` objects. The last item is the current page (no link). |
+
+## Usage in plain HTML
+
+```html
+<bds-breadcrumb items='[
+  {"label":"Home","href":"/"},
+  {"label":"Products","href":"/products"},
+  {"label":"Detail"}
+]'></bds-breadcrumb>
+```
+
+In JavaScript:
+```js
+const crumb = document.querySelector('bds-breadcrumb');
+crumb.items = [
+  { label: 'Home', href: '/' },
+  { label: 'Products', href: '/products' },
+  { label: 'Detail' },
+];
+```
+
+## Accessibility
+
+- Renders as `<nav aria-label="Breadcrumb">` with an `<ol>` list
+- The last item gets `aria-current="page"` — it is not a link
+- Separators (`›`) are hidden from screen readers with `aria-hidden="true"`

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

@@ -0,0 +1,59 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import type { BreadcrumbItem } from './bds-breadcrumb';
+import '../index';
+
+function BdsBreadcrumb({ items = [] }: { items?: BreadcrumbItem[] }) {
+  return React.createElement('bds-breadcrumb', { items: JSON.stringify(items) });
+}
+
+const meta = {
+  title: 'Web Components/UI/Breadcrumb',
+  component: BdsBreadcrumb,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'padded' },
+} satisfies Meta<typeof BdsBreadcrumb>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    items: [
+      { label: 'Home', href: '/' },
+      { label: 'Products', href: '/products' },
+      { label: 'Current page' },
+    ],
+  },
+};
+
+export const TwoLevels: Story = {
+  args: {
+    items: [
+      { label: 'Home', href: '/' },
+      { label: 'Current page' },
+    ],
+  },
+};
+
+export const DeepNested: Story = {
+  args: {
+    items: [
+      { label: 'Home', href: '/' },
+      { label: 'Category', href: '/category' },
+      { label: 'Subcategory', href: '/category/sub' },
+      { label: 'Section', href: '/category/sub/section' },
+      { label: 'Current page' },
+    ],
+  },
+};
+
+export const AllVariants: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
+      <BdsBreadcrumb items={[{ label: 'Home', href: '/' }, { label: 'Current' }]} />
+      <BdsBreadcrumb items={[{ label: 'Home', href: '/' }, { label: 'Products', href: '/products' }, { label: 'Detail' }]} />
+      <BdsBreadcrumb items={[{ label: 'Home', href: '/' }, { label: 'A', href: '/a' }, { label: 'B', href: '/a/b' }, { label: 'C', href: '/a/b/c' }, { label: 'Current' }]} />
+    </div>
+  ),
+};

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

@@ -0,0 +1,83 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsCard.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-card&gt;
+
+Framework-agnostic Card layout element. Groups related content in a contained surface with optional elevation or outline. Can be made clickable.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## Examples
+
+### All variants
+<Canvas of={Stories.AllVariants} />
+
+### Clickable
+<Canvas of={Stories.Interactive} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `variant` | `"default" \| "elevated" \| "outlined"` | `"default"` | Visual style |
+| `padding` | `"none" \| "small" \| "medium" \| "large"` | `"medium"` | Internal spacing |
+| `text-align` | `"start" \| "center" \| "end"` | `"start"` | Content alignment |
+| `clickable` | boolean | `false` | Renders as `<button>`, adds hover/active effects |
+| `aria-label` | string | — | Accessible label (required when `clickable` and the card content is not descriptive enough) |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `(default)` | Card content |
+
+## Events
+
+| Event | Detail | Bubbles | Composed | Description |
+|-------|--------|---------|----------|-------------|
+| `bds-click` | — | Yes | Yes | Fired when a clickable card is activated |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--card_color` | Card background colour |
+| `--card_on-color` | Card text colour |
+
+## Usage in plain HTML
+
+```html
+<bds-card variant="elevated" padding="large">
+  <h3>Card title</h3>
+  <p>Card body text.</p>
+</bds-card>
+
+<bds-card clickable aria-label="View product details">
+  <strong>Clickable card</strong>
+</bds-card>
+```
+
+Listen for click:
+```js
+document.querySelector('bds-card[clickable]').addEventListener('bds-click', () => {
+  console.log('card clicked');
+});
+```
+
+## Accessibility
+
+- Non-clickable cards are `<div>` elements — they have no interactive role
+- Clickable cards render as `<button>` with keyboard and pointer support
+- Always provide `aria-label` on clickable cards when the text content alone is not descriptive

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