@oicl/openbridge-webcomponents-full-bundle 2.0.0-next.144 → 2.0.0-next.145

package/src/components/checkbox-item/checkbox-item.ts

@@ -2,10 +2,12 @@ import {LitElement, html, nothing, unsafeCSS} from 'lit';
 import {property, query} from 'lit/decorators.js';
 import {classMap} from 'lit/directives/class-map.js';
 import {ifDefined} from 'lit/directives/if-defined.js';
+import {styleMap} from 'lit/directives/style-map.js';
 import {customElement} from '../../decorator.js';
 import componentStyle from './checkbox-item.css?inline';
 import '../checkbox/checkbox.js';
 import '../../icons/icon-chevron-right-google.js';
+import '../../icons/icon-chevron-down-google.js';
 import {
   CheckboxState,
   CheckboxStatus,
@@ -22,59 +24,73 @@ export enum ObcCheckboxItemHoverStyle {
   visualTarget = 'visual-target',
 }
 
+export type ObcCheckboxItemExpandToggleEvent = CustomEvent<boolean>;
+
 /**
- * `<obc-checkbox-item>` – A list-item wrapper for `<obc-checkbox>` with label
- * and optional nested indentation affordances.
+ * `<obc-checkbox-item>` – A list row that pairs `<obc-checkbox>` with a label,
+ * an optional description, and hierarchy affordances for nested lists.
  *
  * ### Overview
- * Combines checkbox interaction with a row-like container used in menus and
- * hierarchical selection lists. The component proxies checkbox state changes,
- * supports touch-target or visual-target interaction behavior, and can render
- * nested structure indicators.
+ * The row is the touch target: clicking anywhere on it toggles the checkbox,
+ * except on the chevron button, which only asks to expand or collapse. Depth
+ * is a number (`level`); the row indents itself so a flat sequence of rows
+ * reads as a tree. `<obc-checkbox-list>` builds on this to hide the rows
+ * under a collapsed parent.
  *
  * ### Features
- * - Three checkbox statuses: `unchecked`, `checked`, `mixed`.
- * - Item state control: `enabled` or `disabled`.
- * - Two hover/focus interaction modes: `touch-target` and `visual-target`.
- * - Optional nested layout controls via `isNested`, `isLevel1`, `isLevel2`.
- * - Forwards `aria-describedby` to the inner checkbox for assistive context.
- *
- * ### Variants
- * - **Nested level 1:** Chevron icon is shown.
- * - **Nested level 2:** Chevron slot is reserved and nested spacer is shown.
+ * - Three statuses: `unchecked`, `checked`, `mixed`.
+ * - `touch-target` or `visual-target` hover treatment.
+ * - `level` indentation: level 1 reserves the chevron slot, each further
+ *   level adds a spacer.
+ * - `expandable` rows show a chevron button that fires `expand-toggle`; the
+ *   host owns `expanded`.
+ * - Optional `description` line under the label.
+ * - Forwards `aria-describedby` to the inner checkbox.
  *
  * ### Usage Guidelines
- * - Use for checkbox rows that require text labels and optional hierarchy.
- * - Keep `status` as the source of truth for checked/mixed/unchecked value.
- * - Use `state="disabled"` or `disabled` to lock interaction.
- * - Prefer `hoverStyle="touch-target"` for standard list behavior.
- *
- * ### Slots / Content
- * - No named slots. Label content is provided through the `label` property.
+ * - Keep `status` as the source of truth; update it from the `change` event.
+ * - Set `expanded` in response to `expand-toggle` — the row never flips it
+ *   itself, so a parent (or `<obc-checkbox-list>`) can veto or persist it.
+ * - Use `level` 0 for a plain list; start at 1 when any row in the list is
+ *   expandable so chevrons and checkboxes line up.
+ * - Prefer `hoverStyle="touch-target"` for standard list behaviour.
  *
- * ### Events
- * - `change` – Fired when status changes (from row click or inner checkbox).
- *   **detail:** `{ status, disabled }`
- *
- * ### Best Practices
- * - Provide non-empty `label` for accessible naming.
- * - Use `aria-describedby` when additional contextual text exists outside.
- * - For deep hierarchies, use `isNested` with `isLevel1` / `isLevel2`
- *   consistently to preserve spacing and alignment.
+ * ### Accessibility
+ * The checkbox and the chevron are separate controls in the natural tab
+ * order. The chevron is a native button named by the row's label, with the
+ * state in `aria-expanded`, following the WAI-ARIA checkbox and disclosure
+ * button patterns.
  *
  * ### Example
  * ```html
  * <obc-checkbox-item
+ *   level="1"
+ *   expandable
+ *   expanded
  *   status="mixed"
- *   label="Include archived items"
- *   hoverStyle="touch-target"
+ *   label="Reports"
+ * ></obc-checkbox-item>
+ * <obc-checkbox-item
+ *   level="2"
+ *   status="checked"
+ *   label="Monthly"
+ *   description="Sent on the 1st"
  * ></obc-checkbox-item>
  * ```
  *
- * @availableWhen isLevel1 isNested==true || hoverStyle==visual-target
- * @availableWhen isLevel2 isNested==true || hoverStyle==visual-target
- * @slot - No named slots.
+ * @property status - Checkbox status: `unchecked`, `checked` or `mixed`.
+ * @property state - Item state: `enabled` or `disabled`.
+ * @property disabled - Disables the row and the inner checkbox.
+ * @property label - Text label; also the checkbox's accessible name.
+ * @property description - Secondary line under the label; hidden when empty.
+ * @property level - Depth in a nested list. 0 is a plain row; 1 reserves the chevron slot; each level above 1 adds a spacer.
+ * @property expandable - Shows the chevron button that fires `expand-toggle`.
+ * @property expanded - Whether the row's children are shown; drives the chevron direction and `aria-expanded`.
+ * @availableWhen expanded expandable==true
+ * @property hoverStyle - Which box shows hover and focus: the whole row (`touch-target`) or the checkbox (`visual-target`).
+ * @property ariaDescribedBy - Forwarded to the inner checkbox as `aria-describedby`.
  * @fires {ObcCheckboxChangeEvent} change - Emitted when status changes.
+ * @fires {ObcCheckboxItemExpandToggleEvent} expand-toggle - Emitted when the chevron is activated; detail is the next `expanded` value. Bubbles and is composed.
  * @stable
  */
 @customElement('obc-checkbox-item')
@@ -88,11 +104,13 @@ export class ObcCheckboxItem extends LitElement {
 
   @property({type: String}) label = '';
 
-  @property({type: Boolean, reflect: true}) isNested = false;
+  @property({type: String}) description = '';
+
+  @property({type: Number, reflect: true}) level = 0;
 
-  @property({type: Boolean, reflect: true}) isLevel1 = false;
+  @property({type: Boolean, reflect: true}) expandable = false;
 
-  @property({type: Boolean, reflect: true}) isLevel2 = false;
+  @property({type: Boolean, reflect: true}) expanded = false;
 
   @property({type: String}) hoverStyle: ObcCheckboxItemHoverStyle =
     ObcCheckboxItemHoverStyle.touchTarget;
@@ -102,10 +120,13 @@ export class ObcCheckboxItem extends LitElement {
 
   @query('obc-checkbox') private checkboxElement?: HTMLElement;
 
-  private toggleStatusFromItem() {
-    const isDisabled =
-      this.disabled || this.state === ObcCheckboxItemState.disabled;
+  @query('.chevron-button') private chevronButton?: HTMLElement;
+
+  private get isDisabled(): boolean {
+    return this.disabled || this.state === ObcCheckboxItemState.disabled;
+  }
 
+  private toggleStatusFromItem() {
     if (this.status === CheckboxStatus.checked) {
       this.status = CheckboxStatus.unchecked;
     } else {
@@ -116,22 +137,33 @@ export class ObcCheckboxItem extends LitElement {
       new CustomEvent('change', {
         detail: {
           status: this.status,
-          disabled: isDisabled,
+          disabled: this.isDisabled,
         },
       })
     );
   }
 
   private handleItemClick(event: MouseEvent) {
-    if (this.disabled || this.state === ObcCheckboxItemState.disabled) return;
+    if (this.isDisabled) return;
 
     const path = event.composedPath();
-    const checkboxElement = this.checkboxElement;
-    if (checkboxElement && path.includes(checkboxElement)) return;
+    if (this.checkboxElement && path.includes(this.checkboxElement)) return;
+    if (this.chevronButton && path.includes(this.chevronButton)) return;
 
     this.toggleStatusFromItem();
   }
 
+  private handleChevronClick(event: MouseEvent) {
+    event.stopPropagation();
+    this.dispatchEvent(
+      new CustomEvent<boolean>('expand-toggle', {
+        detail: !this.expanded,
+        bubbles: true,
+        composed: true,
+      })
+    );
+  }
+
   private handleCheckboxChange(event: Event) {
     const checkboxEvent = event as ObcCheckboxChangeEvent;
     this.status = checkboxEvent.detail.status;
@@ -147,15 +179,35 @@ export class ObcCheckboxItem extends LitElement {
     this.checkboxElement?.focus(options);
   }
 
+  private renderChevron() {
+    if (!this.expandable) return nothing;
+    return html`<button
+      type="button"
+      class="chevron-button"
+      aria-expanded=${this.expanded ? 'true' : 'false'}
+      aria-label=${ifDefined(this.label.trim() || undefined)}
+      ?disabled=${this.isDisabled}
+      @click=${this.handleChevronClick}
+    >
+      <span class="chevron-visible">
+        ${this.expanded
+          ? html`<obi-chevron-down-google
+              class="chevron-icon"
+            ></obi-chevron-down-google>`
+          : html`<obi-chevron-right-google
+              class="chevron-icon"
+            ></obi-chevron-right-google>`}
+      </span>
+    </button>`;
+  }
+
   override render() {
-    const isDisabled =
-      this.disabled || this.state === ObcCheckboxItemState.disabled;
+    const isDisabled = this.isDisabled;
     const hasCheckboxHoverEffects = !(
       this.hoverStyle === ObcCheckboxItemHoverStyle.touchTarget && !isDisabled
     );
-    const shouldRenderNestedSpacer = this.isNested && this.isLevel2;
-    const shouldRenderChevronContainer = this.isNested;
-    const shouldRenderChevronIcon = this.isNested && this.isLevel1;
+    const depth = Math.max(0, Math.floor(this.level) - 1);
+    const hasChevronSlot = this.level >= 1 || this.expandable;
     const checkboxAriaLabel =
       this.label.trim().length > 0 ? this.label : undefined;
 
@@ -165,24 +217,21 @@ export class ObcCheckboxItem extends LitElement {
           'checkbox-item-container': true,
           [`status-${this.status}`]: true,
           [`hover-style-${this.hoverStyle}`]: true,
-          'is-nested': this.isNested,
-          'is-level-1': this.isLevel1,
-          'is-level-2': this.isLevel2,
+          'is-nested': hasChevronSlot,
+          'has-description': this.description !== '',
           disabled: isDisabled,
         })}
         @click=${this.handleItemClick}
       >
-        ${shouldRenderChevronContainer
-          ? html`<div class="chevron-container" aria-hidden="true">
-              ${shouldRenderChevronIcon
-                ? html`<obi-chevron-right-google
-                    class="chevron-icon"
-                  ></obi-chevron-right-google>`
-                : nothing}
-            </div>`
+        ${depth > 0
+          ? html`<div
+              class="nested-spacer"
+              aria-hidden="true"
+              style=${styleMap({'--checkbox-item-depth': String(depth)})}
+            ></div>`
           : nothing}
-        ${shouldRenderNestedSpacer
-          ? html`<div class="nested-spacer" aria-hidden="true"></div>`
+        ${hasChevronSlot
+          ? html`<div class="chevron-container">${this.renderChevron()}</div>`
           : nothing}
         <div class="content-container">
           <obc-checkbox
@@ -196,6 +245,11 @@ export class ObcCheckboxItem extends LitElement {
           ></obc-checkbox>
           <div class="checkbox-label-container">
             <span class="checkbox-label">${this.label}</span>
+            ${this.description
+              ? html`<span class="checkbox-description"
+                  >${this.description}</span
+                >`
+              : nothing}
           </div>
         </div>
       </div>

package/src/components/checkbox-list/checkbox-list-visibility.spec.ts

@@ -0,0 +1,68 @@
+import {describe, expect, it} from 'vitest';
+import {
+  computeHiddenRows,
+  type CheckboxListRow,
+} from './checkbox-list-visibility.js';
+
+const row = (
+  level: number,
+  expandable = false,
+  expanded = false
+): CheckboxListRow => ({level, expandable, expanded});
+
+describe('computeHiddenRows', () => {
+  it('shows every row when nothing is collapsed', () => {
+    expect(
+      computeHiddenRows([row(1, true, true), row(2), row(2), row(1)])
+    ).toEqual([false, false, false, false]);
+  });
+
+  it('hides descendants of a collapsed row until a sibling or ancestor', () => {
+    expect(
+      computeHiddenRows([row(1, true, false), row(2), row(3), row(1)])
+    ).toEqual([false, true, true, false]);
+  });
+
+  it('a collapsed row nested under an open one hides only its own subtree', () => {
+    expect(
+      computeHiddenRows([
+        row(1, true, true),
+        row(2, true, false),
+        row(3),
+        row(2),
+        row(1),
+      ])
+    ).toEqual([false, false, true, false, false]);
+  });
+
+  it('a collapsed row that is itself hidden does not change the cut level', () => {
+    expect(
+      computeHiddenRows([
+        row(1, true, false),
+        row(2, true, true),
+        row(3),
+        row(1),
+      ])
+    ).toEqual([false, true, true, false]);
+  });
+
+  it('non-expandable rows never collapse anything', () => {
+    expect(computeHiddenRows([row(1), row(2), row(2)])).toEqual([
+      false,
+      false,
+      false,
+    ]);
+  });
+
+  it('treats level 0 like any other depth', () => {
+    expect(computeHiddenRows([row(0, true, false), row(1), row(0)])).toEqual([
+      false,
+      true,
+      false,
+    ]);
+  });
+
+  it('returns an empty array for no rows', () => {
+    expect(computeHiddenRows([])).toEqual([]);
+  });
+});

package/src/components/checkbox-list/checkbox-list-visibility.ts

@@ -0,0 +1,23 @@
+/**
+ * Visibility of a flat checkbox-item sequence
+ *
+ * `<obc-checkbox-list>` keeps its rows flat and infers the tree from each
+ * row's `level`. A row is hidden while a preceding, visible, collapsed
+ * expandable row of smaller level is still "open" — that is, until a row of
+ * equal or smaller level closes it. Kept free of DOM so it can be unit-tested.
+ * @module
+ */
+export interface CheckboxListRow {
+  level: number;
+  expandable: boolean;
+  expanded: boolean;
+}
+
+export function computeHiddenRows(rows: readonly CheckboxListRow[]): boolean[] {
+  let cutLevel: number | null = null;
+  return rows.map((row) => {
+    if (cutLevel !== null && row.level > cutLevel) return true;
+    cutLevel = row.expandable && !row.expanded ? row.level : null;
+    return false;
+  });
+}

package/src/components/checkbox-list/checkbox-list.css

@@ -0,0 +1,13 @@
+:host {
+  display: block;
+}
+
+.list {
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+}
+
+::slotted([hidden]) {
+  display: none; /* collapsed rows leave layout; :host is display:block so [hidden] alone would not win */
+}

package/src/components/checkbox-list/checkbox-list.spec.ts

@@ -0,0 +1,93 @@
+import {afterEach, describe, expect, it} from 'vitest';
+import './checkbox-list.js';
+import '../checkbox-item/checkbox-item.js';
+import type {ObcCheckboxItem} from '../checkbox-item/checkbox-item.js';
+import {ObcCheckboxItemHoverStyle} from '../checkbox-item/checkbox-item.js';
+
+const nextTick = () => new Promise((resolve) => setTimeout(resolve, 0));
+
+function item(level: number, expandable = false, expanded = false) {
+  const el = document.createElement('obc-checkbox-item');
+  el.label = `Level ${level}`;
+  el.level = level;
+  el.expandable = expandable;
+  el.expanded = expanded;
+  return el;
+}
+
+async function mount(items: ObcCheckboxItem[]) {
+  const list = document.createElement('obc-checkbox-list');
+  items.forEach((i) => list.appendChild(i));
+  document.body.appendChild(list);
+  await list.updateComplete;
+  await nextTick();
+  return list;
+}
+
+afterEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('obc-checkbox-list', () => {
+  it('hides rows under a collapsed parent', async () => {
+    const rows = [item(1, true, false), item(2), item(1)];
+    await mount(rows);
+    expect(rows.map((r) => r.hidden)).toEqual([false, true, false]);
+  });
+
+  it('applies expand-toggle to the item and recomputes', async () => {
+    const rows = [item(1, true, false), item(2)];
+    await mount(rows);
+    rows[0]
+      .shadowRoot!.querySelector<HTMLButtonElement>('.chevron-button')!
+      .click();
+    await rows[0].updateComplete;
+    await nextTick();
+    expect(rows[0].expanded).toBe(true);
+    expect(rows[1].hidden).toBe(false);
+  });
+
+  it('recomputes when expanded is changed from outside', async () => {
+    const rows = [item(1, true, true), item(2)];
+    await mount(rows);
+    rows[0].expanded = false;
+    await rows[0].updateComplete;
+    await nextTick();
+    expect(rows[1].hidden).toBe(true);
+  });
+
+  it('forwards hoverStyle to every item, including late ones', async () => {
+    const rows = [item(0), item(0)];
+    const list = await mount(rows);
+    list.hoverStyle = ObcCheckboxItemHoverStyle.visualTarget;
+    await list.updateComplete;
+    expect(rows.map((r) => r.hoverStyle)).toEqual([
+      'visual-target',
+      'visual-target',
+    ]);
+    const late = item(0);
+    list.appendChild(late);
+    await nextTick();
+    expect(late.hoverStyle).toBe('visual-target');
+  });
+
+  it('recomputes when a collapsed row stops being expandable', async () => {
+    const rows = [item(1, true, false), item(2)];
+    await mount(rows);
+    expect(rows[1].hidden).toBe(true);
+    rows[0].expandable = false;
+    await rows[0].updateComplete;
+    await nextTick();
+    expect(rows[1].hidden).toBe(false);
+  });
+
+  it('is the group and keeps a role the consumer set', async () => {
+    const list = await mount([]);
+    expect(list.getAttribute('role')).toBe('group');
+    const custom = document.createElement('obc-checkbox-list');
+    custom.setAttribute('role', 'presentation');
+    document.body.appendChild(custom);
+    await custom.updateComplete;
+    expect(custom.getAttribute('role')).toBe('presentation');
+  });
+});

package/src/components/checkbox-list/checkbox-list.stories.ts

@@ -0,0 +1,161 @@
+import type {Meta, StoryObj} from '@storybook/web-components-vite';
+import {html} from 'lit';
+import {ObcCheckboxList} from './checkbox-list.js';
+import './checkbox-list.js';
+import '../checkbox-item/checkbox-item.js';
+import {ObcCheckboxItemHoverStyle} from '../checkbox-item/checkbox-item.js';
+import {CheckboxStatus} from '../checkbox/checkbox.js';
+
+const meta = {
+  title: 'UI Components/Selection Controls and Switches/Checkbox List',
+  tags: ['autodocs', '6.1', 'beta'],
+  component: 'obc-checkbox-list',
+  parameters: {
+    layout: 'centered',
+    actions: {
+      handles: ['change', 'expand-toggle'],
+    },
+  },
+  argTypes: {
+    hoverStyle: {
+      name: 'Hover style',
+      options: Object.values(ObcCheckboxItemHoverStyle),
+      control: {type: 'select'},
+    },
+  },
+  args: {
+    hoverStyle: ObcCheckboxItemHoverStyle.touchTarget,
+  },
+} satisfies Meta<ObcCheckboxList>;
+
+export default meta;
+type Story = StoryObj<ObcCheckboxList>;
+
+const regularRows = html`
+  <obc-checkbox-item label="Label"></obc-checkbox-item>
+  <obc-checkbox-item
+    label="Label"
+    status=${CheckboxStatus.checked}
+  ></obc-checkbox-item>
+  <obc-checkbox-item
+    label="Label"
+    status=${CheckboxStatus.checked}
+  ></obc-checkbox-item>
+  <obc-checkbox-item label="Label"></obc-checkbox-item>
+`;
+
+const nestedRows = html`
+  <obc-checkbox-item
+    level="1"
+    expandable
+    expanded
+    label="Label"
+    status=${CheckboxStatus.mixed}
+  ></obc-checkbox-item>
+  <obc-checkbox-item
+    level="2"
+    label="Label"
+    status=${CheckboxStatus.checked}
+  ></obc-checkbox-item>
+  <obc-checkbox-item level="2" label="Label"></obc-checkbox-item>
+  <obc-checkbox-item level="1" expandable label="Label"></obc-checkbox-item>
+  <obc-checkbox-item
+    level="2"
+    label="Hidden until expanded"
+  ></obc-checkbox-item>
+`;
+
+/** The Figma frame widths: 240px for a regular list, 320px for a nested one. */
+const renderRegular: Story['render'] = (args) =>
+  html`<obc-checkbox-list style="width:240px" .hoverStyle=${args.hoverStyle}>
+    ${regularRows}
+  </obc-checkbox-list>`;
+
+const renderNested: Story['render'] = (args) =>
+  html`<obc-checkbox-list style="width:320px" .hoverStyle=${args.hoverStyle}>
+    ${nestedRows}
+  </obc-checkbox-list>`;
+
+export const Regular: Story = {
+  render: renderRegular,
+};
+
+export const Nested: Story = {
+  render: renderNested,
+};
+
+export const RegularVisualTarget: Story = {
+  args: {hoverStyle: ObcCheckboxItemHoverStyle.visualTarget},
+  render: renderRegular,
+};
+
+export const NestedVisualTarget: Story = {
+  args: {hoverStyle: ObcCheckboxItemHoverStyle.visualTarget},
+  render: renderNested,
+};
+
+export const WithDescriptions: Story = {
+  render: (args) =>
+    html`<obc-checkbox-list style="width:320px" .hoverStyle=${args.hoverStyle}>
+      <obc-checkbox-item
+        level="1"
+        expandable
+        expanded
+        label="Reports"
+        description="All report types"
+        status=${CheckboxStatus.mixed}
+      ></obc-checkbox-item>
+      <obc-checkbox-item
+        level="2"
+        label="Monthly"
+        description="Sent on the 1st"
+        status=${CheckboxStatus.checked}
+      ></obc-checkbox-item>
+      <obc-checkbox-item
+        level="2"
+        label="Quarterly"
+        description="Sent every third month"
+      ></obc-checkbox-item>
+    </obc-checkbox-list>`,
+};
+
+/** `level` is not capped at 2: each level above 1 adds one more spacer. */
+export const DeepNesting: Story = {
+  render: (args) =>
+    html`<obc-checkbox-list style="width:320px" .hoverStyle=${args.hoverStyle}>
+      <obc-checkbox-item
+        level="1"
+        expandable
+        expanded
+        label="Documents"
+        status=${CheckboxStatus.mixed}
+      ></obc-checkbox-item>
+      <obc-checkbox-item
+        level="2"
+        expandable
+        expanded
+        label="Reports"
+        status=${CheckboxStatus.mixed}
+      ></obc-checkbox-item>
+      <obc-checkbox-item
+        level="3"
+        label="Monthly"
+        status=${CheckboxStatus.checked}
+      ></obc-checkbox-item>
+      <obc-checkbox-item level="3" label="Quarterly"></obc-checkbox-item>
+      <obc-checkbox-item
+        level="2"
+        expandable
+        label="Presentations"
+      ></obc-checkbox-item>
+      <obc-checkbox-item
+        level="3"
+        label="Hidden until expanded"
+      ></obc-checkbox-item>
+      <obc-checkbox-item
+        level="1"
+        expandable
+        label="Images"
+      ></obc-checkbox-item>
+    </obc-checkbox-list>`,
+};