@boostdev/design-system-components 1.2.0 → 1.2.2

package/src/web-components/interaction/form/BdsTextarea.mdx

@@ -3,39 +3,71 @@ import * as Stories from './BdsTextarea.stories';
 
 <Meta of={Stories} />
 
-# Textarea
+# &lt;bds-textarea&gt;
 
-`<bds-textarea>` wraps a native `<textarea>` for consistent styling while participating in HTML forms via the Form-Associated Custom Elements API.
+Form-associated multiline text input. Wraps a native `<textarea>` with consistent styling while participating in HTML forms via the Form-Associated Custom Elements API.
 
-## Usage
+> **Status: experimental** — API may change before stable release.
 
-```html
-<bds-textarea name="message" placeholder="Enter your message…" rows="6"></bds-textarea>
+## Installation
+
+```js
+import '@boostdev/components/web-components';
 ```
 
+## When to use
+
+Use `<bds-textarea>` for multiline text entry — messages, comments, descriptions, or any input that may span more than one line.
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### Pre-filled value
+<Canvas of={Stories.WithValue} />
+
+### Tall (8 rows)
+<Canvas of={Stories.TallRows} />
+
+### Required
+<Canvas of={Stories.Required} />
+
+### Disabled
+<Canvas of={Stories.Disabled} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
 ## Attributes
 
-| Attribute     | Type      | Default | Description                  |
-|---------------|-----------|---------|------------------------------|
-| `name`        | `string`  | `""`    | Form field name              |
-| `value`       | `string`  | `""`    | Current text value           |
-| `placeholder` | `string`  | `""`    | Placeholder text             |
-| `rows`        | `number`  | `4`     | Number of visible rows       |
-| `required`    | `boolean` | `false` | Marks the field as required  |
-| `disabled`    | `boolean` | `false` | Disables the textarea        |
+| Attribute     | Type    | Default | Description                              |
+|---------------|---------|---------|------------------------------------------|
+| `name`        | string  | `""`    | Form field name                          |
+| `value`       | string  | `""`    | Text value                               |
+| `placeholder` | string  | `""`    | Placeholder text                         |
+| `rows`        | number  | `4`     | Number of visible rows                   |
+| `required`    | boolean | `false` | Marks the field as required              |
+| `disabled`    | boolean | `false` | Disables the textarea                    |
 
 ## Events
 
-| Event    | Description                        |
-|----------|------------------------------------|
-| `input`  | Fired as the user types            |
-| `change` | Fired when value is committed      |
+| Event    | Detail | Description                                         |
+|----------|--------|-----------------------------------------------------|
+| `input`  | —      | Fired on every keystroke (native input event)       |
+| `change` | —      | Fired when the value is committed (native change event) |
 
-## Stories
+## Usage in plain HTML
 
-<Canvas of={Stories.Default} />
-<Canvas of={Stories.AllVariants} />
+```html
+<bds-textarea name="message" placeholder="Enter message…" rows="6"></bds-textarea>
+<bds-textarea name="bio" required rows="4"></bds-textarea>
+```
 
-## Controls
+## Accessibility
 
-<ArgTypes of={Stories} />
+- Wraps a native `<textarea>` which has full browser and assistive technology support
+- `required` uses the native `required` attribute for browser validation
+- `disabled` sets `pointer-events: none`, reduces opacity, and removes the resize handle
+- Participates in HTML forms via the Form-Associated Custom Elements API

package/src/web-components/interaction/form/BdsTextarea.stories.tsx

@@ -1,24 +1,29 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
-import '../../index';
+import '../../index'; // auto-registers all custom elements
 
 function BdsTextarea({
-  placeholder = 'Enter text…',
+  name,
+  value,
+  placeholder,
   rows,
-  disabled,
   required,
+  disabled,
 }: {
+  name?: string;
+  value?: string;
   placeholder?: string;
   rows?: number;
-  disabled?: boolean;
   required?: boolean;
+  disabled?: boolean;
 }) {
   return React.createElement('bds-textarea', {
+    name,
+    value,
     placeholder,
     rows,
-    disabled: disabled || undefined,
     required: required || undefined,
-    style: { display: 'block', maxInlineSize: '400px' },
+    disabled: disabled || undefined,
   });
 }
 
@@ -26,54 +31,40 @@ const meta = {
   title: 'Web Components/Interaction/Form/Textarea',
   component: BdsTextarea,
   tags: ['!stable', 'experimental'],
-  parameters: { layout: 'padded' },
+  parameters: { layout: 'centered' },
   argTypes: {
     rows: { control: 'number' },
-    disabled: { control: 'boolean' },
     required: { control: 'boolean' },
+    disabled: { control: 'boolean' },
   },
+  decorators: [
+    (Story: React.ComponentType) => (
+      <div style={{ width: '360px' }}>
+        <Story />
+      </div>
+    ),
+  ],
 } satisfies Meta<typeof BdsTextarea>;
 
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-export const Default: Story = { args: { placeholder: 'Enter your message…' } };
-export const WithRows: Story = { args: { placeholder: 'Extended text area…', rows: 8 } };
-export const Disabled: Story = { args: { placeholder: 'Not editable', disabled: true } };
+export const Default: Story = {
+  args: { name: 'message', placeholder: 'Enter your message…' },
+};
 
-export const AllVariants: Story = {
-  render: () => (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px', maxInlineSize: '400px' }}>
-      <div>
-        <p style={{ margin: '0 0 4px', fontSize: '0.75rem', color: '#888' }}>Default (4 rows)</p>
-        {React.createElement('bds-textarea', { placeholder: 'Write something…' })}
-      </div>
-      <div>
-        <p style={{ margin: '0 0 4px', fontSize: '0.75rem', color: '#888' }}>Tall (8 rows)</p>
-        {React.createElement('bds-textarea', { placeholder: 'More space to write…', rows: 8 })}
-      </div>
-      <div>
-        <p style={{ margin: '0 0 4px', fontSize: '0.75rem', color: '#888' }}>Disabled</p>
-        {React.createElement('bds-textarea', { placeholder: 'Read-only area', disabled: true })}
-      </div>
-    </div>
-  ),
+export const WithValue: Story = {
+  args: { name: 'message', value: 'Hello, this is a pre-filled message.' },
 };
 
-export const Interactive: Story = {
-  render: () => {
-    const [value, setValue] = React.useState('');
-    return (
-      <div style={{ display: 'flex', flexDirection: 'column', gap: '8px', maxInlineSize: '400px' }}>
-        <p style={{ margin: '0 0 4px', fontSize: '0.875rem' }}>
-          Characters: {value.length}
-        </p>
-        {React.createElement('bds-textarea', {
-          placeholder: 'Start typing…',
-          value,
-          onInput: (e: Event) => setValue((e.target as HTMLTextAreaElement).value),
-        })}
-      </div>
-    );
-  },
+export const TallRows: Story = {
+  args: { name: 'message', placeholder: 'Enter a longer text…', rows: 8 },
+};
+
+export const Required: Story = {
+  args: { name: 'message', placeholder: 'Required field', required: true },
+};
+
+export const Disabled: Story = {
+  args: { name: 'message', value: 'Read-only content', disabled: true },
 };

package/src/web-components/interaction/form/bds-checkbox-group.spec.ts

@@ -0,0 +1,55 @@
+import { fixture, cleanup } from '../../test/helpers';
+import { BdsCheckboxGroup } from './bds-checkbox-group';
+
+describe('bds-checkbox-group', () => {
+  it('is registered as a custom element', () => {
+    expect(customElements.get('bds-checkbox-group')).toBe(BdsCheckboxGroup);
+  });
+
+  it('renders a fieldset', async () => {
+    const el = await fixture('<bds-checkbox-group label="Interests"></bds-checkbox-group>');
+    expect(el.shadowRoot!.querySelector('fieldset')).not.toBeNull();
+    cleanup(el);
+  });
+
+  it('renders the label as a legend', async () => {
+    const el = await fixture('<bds-checkbox-group label="My Group"></bds-checkbox-group>');
+    const legend = el.shadowRoot!.querySelector('legend');
+    expect(legend?.textContent?.trim()).toContain('My Group');
+    cleanup(el);
+  });
+
+  it('renders slotted children', async () => {
+    const el = await fixture('<bds-checkbox-group label="Test"><span id="child">item</span></bds-checkbox-group>');
+    expect(el.shadowRoot!.querySelector('slot')).not.toBeNull();
+    cleanup(el);
+  });
+
+  it('disables the fieldset when disabled attribute is set', async () => {
+    const el = await fixture('<bds-checkbox-group label="Test" disabled></bds-checkbox-group>');
+    const fieldset = el.shadowRoot!.querySelector('fieldset')!;
+    expect(fieldset.disabled).toBe(true);
+    cleanup(el);
+  });
+
+  it('shows required asterisk when required', async () => {
+    const el = await fixture('<bds-checkbox-group label="Test" required></bds-checkbox-group>');
+    const required = el.shadowRoot!.querySelector('.required');
+    expect(required).not.toBeNull();
+    cleanup(el);
+  });
+
+  it('renders error message when error attribute is set', async () => {
+    const el = await fixture('<bds-checkbox-group label="Test" error="Select at least one"></bds-checkbox-group>');
+    const message = el.shadowRoot!.querySelector('.message--error');
+    expect(message?.textContent?.trim()).toBe('Select at least one');
+    cleanup(el);
+  });
+
+  it('renders hint message when hint attribute is set', async () => {
+    const el = await fixture('<bds-checkbox-group label="Test" hint="Select all that apply"></bds-checkbox-group>');
+    const message = el.shadowRoot!.querySelector('.message--hint');
+    expect(message?.textContent?.trim()).toBe('Select all that apply');
+    cleanup(el);
+  });
+});

package/src/web-components/interaction/form/bds-checkbox-group.ts

@@ -0,0 +1,117 @@
+import { LitElement, css, html } from 'lit';
+
+/**
+ * `<bds-checkbox-group>` — groups related checkboxes with a shared label.
+ *
+ * Renders a `<fieldset>` with a `<legend>` for accessible grouping.
+ *
+ * Attributes:
+ *   label    — visible group label (rendered as `<legend>`)
+ *   error    — error message shown below items
+ *   hint     — hint text shown below items
+ *   disabled — disables the entire fieldset
+ *   required — marks the group as required
+ *
+ * Slots:
+ *   (default) — `<bds-checkbox>` elements
+ *
+ * @example
+ * <bds-checkbox-group label="Interests" required>
+ *   <bds-checkbox name="sports" value="sports">Sports</bds-checkbox>
+ *   <bds-checkbox name="music"  value="music">Music</bds-checkbox>
+ * </bds-checkbox-group>
+ */
+export class BdsCheckboxGroup extends LitElement {
+  static styles = css`
+    :host {
+      display: block;
+    }
+
+    fieldset {
+      border: none;
+      margin: 0;
+      padding: 0;
+    }
+
+    .legend {
+      font-size: var(--bds-font_size--body--s);
+      font-family: var(--bds-font_family--body);
+      font-weight: var(--bds-font_weight--semibold);
+      color: var(--bds-color_on-bg);
+      margin-block-end: var(--bds-space_xs);
+    }
+
+    .required {
+      color: var(--bds-color_error);
+      margin-inline-start: var(--bds-space_xxxs);
+    }
+
+    .items {
+      display: flex;
+      flex-direction: column;
+      gap: var(--bds-space_xs);
+    }
+
+    .message {
+      margin-block-start: var(--bds-space_xs);
+      font-size: var(--bds-font_size--body--s);
+      font-family: var(--bds-font_family--body);
+    }
+
+    .message--error {
+      color: var(--bds-color_error);
+    }
+
+    .message--hint {
+      color: var(--bds-color_on-bg--subtle);
+    }
+  `;
+
+  static properties = {
+    label:    { type: String },
+    error:    { type: String },
+    hint:     { type: String },
+    disabled: { type: Boolean, reflect: true },
+    required: { type: Boolean, reflect: true },
+  };
+
+  declare label: string;
+  declare error: string | undefined;
+  declare hint: string | undefined;
+  declare disabled: boolean;
+  declare required: boolean;
+
+  constructor() {
+    super();
+    this.label = '';
+    this.disabled = false;
+    this.required = false;
+  }
+
+  render() {
+    return html`
+      <fieldset ?disabled=${this.disabled}>
+        <legend class="legend">
+          ${this.label}
+          ${this.required ? html`<span class="required" aria-hidden="true"> *</span>` : ''}
+        </legend>
+        <div class="items">
+          <slot></slot>
+        </div>
+        ${this.error
+          ? html`<p class="message message--error" role="alert">${this.error}</p>`
+          : this.hint
+            ? html`<p class="message message--hint">${this.hint}</p>`
+            : ''}
+      </fieldset>
+    `;
+  }
+}
+
+customElements.define('bds-checkbox-group', BdsCheckboxGroup);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-checkbox-group': BdsCheckboxGroup;
+  }
+}

package/src/web-components/interaction/form/bds-form-input.spec.ts

@@ -0,0 +1,83 @@
+import { fixture, cleanup } from '../../test/helpers';
+import { BdsFormInput } from './bds-form-input';
+
+describe('bds-form-input', () => {
+  it('is registered as a custom element', () => {
+    expect(customElements.get('bds-form-input')).toBe(BdsFormInput);
+  });
+
+  it('is form-associated', () => {
+    expect(BdsFormInput.formAssociated).toBe(true);
+  });
+
+  it('renders an input element', async () => {
+    const el = await fixture('<bds-form-input name="email"></bds-form-input>');
+    expect(el.shadowRoot!.querySelector('input')).not.toBeNull();
+    cleanup(el);
+  });
+
+  it('renders a label when label attribute is set', async () => {
+    const el = await fixture('<bds-form-input name="email" label="Email"></bds-form-input>');
+    expect(el.shadowRoot!.querySelector('label')?.textContent?.trim()).toContain('Email');
+    cleanup(el);
+  });
+
+  it('input id matches label for attribute', async () => {
+    const el = await fixture('<bds-form-input name="email" label="Email"></bds-form-input>');
+    const input = el.shadowRoot!.querySelector('input')!;
+    const label = el.shadowRoot!.querySelector('label')!;
+    expect(input.id).toBeTruthy();
+    expect(label.getAttribute('for')).toBe(input.id);
+    cleanup(el);
+  });
+
+  it('defaults type to text', async () => {
+    const el = await fixture('<bds-form-input name="search"></bds-form-input>') as BdsFormInput;
+    const input = el.shadowRoot!.querySelector<HTMLInputElement>('input')!;
+    expect(input.type).toBe('text');
+    cleanup(el);
+  });
+
+  it('applies the specified type', async () => {
+    const el = await fixture('<bds-form-input name="pass" type="password"></bds-form-input>');
+    const input = el.shadowRoot!.querySelector<HTMLInputElement>('input')!;
+    expect(input.type).toBe('password');
+    cleanup(el);
+  });
+
+  it('disables input when disabled attribute is set', async () => {
+    const el = await fixture('<bds-form-input name="email" disabled></bds-form-input>');
+    const input = el.shadowRoot!.querySelector<HTMLInputElement>('input')!;
+    expect(input.disabled).toBe(true);
+    cleanup(el);
+  });
+
+  it('renders error message and sets aria-invalid when error is set', async () => {
+    const el = await fixture('<bds-form-input name="email" error="Invalid email"></bds-form-input>');
+    const input = el.shadowRoot!.querySelector<HTMLInputElement>('input')!;
+    const errorMsg = el.shadowRoot!.querySelector('.message--error');
+    expect(input.getAttribute('aria-invalid')).toBe('true');
+    expect(errorMsg?.textContent?.trim()).toBe('Invalid email');
+    cleanup(el);
+  });
+
+  it('renders hint message when hint is set (no error)', async () => {
+    const el = await fixture('<bds-form-input name="email" hint="We will not share your email"></bds-form-input>');
+    const hint = el.shadowRoot!.querySelector('.message--hint');
+    expect(hint?.textContent?.trim()).toBe('We will not share your email');
+    cleanup(el);
+  });
+
+  it('fires bds-change on change', async () => {
+    const el = await fixture('<bds-form-input name="email"></bds-form-input>');
+    const values: string[] = [];
+    el.addEventListener('bds-change', (e: Event) => {
+      values.push((e as CustomEvent).detail.value);
+    });
+    const input = el.shadowRoot!.querySelector<HTMLInputElement>('input')!;
+    Object.defineProperty(input, 'value', { value: 'test@example.com', writable: true });
+    input.dispatchEvent(new Event('change', { bubbles: true }));
+    expect(values).toEqual(['test@example.com']);
+    cleanup(el);
+  });
+});