@oicl/openbridge-webcomponents-full-bundle 2.0.0-next.149 → 2.0.0-next.150

package/src/components/table/table.stories.ts

@@ -2,6 +2,7 @@ import type {Meta, StoryObj} from '@storybook/web-components-vite';
 import {
   ObcTable,
   ObcTableCellData,
+  ObcTableExpandToggleEvent,
   ObcTableRow,
   ObcTableCellType,
 } from './table.js';
@@ -689,3 +690,281 @@ export const Interactive: Story = {
     `;
   },
 };
+
+interface HierarchyNode {
+  id: string;
+  system: string;
+  location: string;
+  state: string;
+  members?: HierarchyNode[];
+}
+
+const systemTree: HierarchyNode[] = [
+  {
+    id: 'propulsion',
+    system: 'Propulsion',
+    location: 'Engine room',
+    state: 'Running',
+    members: [
+      {
+        id: 'main-engine',
+        system: 'Main engine',
+        location: 'Engine room',
+        state: 'Running',
+        members: [
+          {
+            id: 'lube-oil',
+            system: 'Lube oil',
+            location: 'Engine room',
+            state: 'Nominal',
+          },
+          {
+            id: 'cooling-water',
+            system: 'Cooling water',
+            location: 'Engine room',
+            state: 'Nominal',
+          },
+        ],
+      },
+      {
+        id: 'shaft-generator',
+        system: 'Shaft generator',
+        location: 'Engine room',
+        state: 'Standby',
+      },
+    ],
+  },
+  {
+    id: 'power',
+    system: 'Power',
+    location: 'Switchboard',
+    state: 'Running',
+    members: [
+      {
+        id: 'aux-engine-1',
+        system: 'Aux engine 1',
+        location: 'Switchboard',
+        state: 'Running',
+      },
+      {
+        id: 'aux-engine-2',
+        system: 'Aux engine 2',
+        location: 'Switchboard',
+        state: 'Stopped',
+      },
+    ],
+  },
+  {
+    id: 'ballast',
+    system: 'Ballast',
+    location: 'Pump room',
+    state: 'Idle',
+  },
+];
+
+const collapsedRowIds = new Set<string>(['power']);
+
+const hierarchyRows = (
+  nodes: HierarchyNode[],
+  level = 0,
+  parentId?: string
+): ObcTableRow[] => {
+  const rows: ObcTableRow[] = [];
+  for (const node of nodes) {
+    const expanded = !collapsedRowIds.has(node.id);
+    rows.push({
+      id: node.id,
+      parentId,
+      level,
+      expandable: (node.members?.length ?? 0) > 0,
+      expanded,
+      system: {type: ObcTableCellType.Regular, text: node.system},
+      location: {type: ObcTableCellType.Regular, text: node.location},
+      state: {type: ObcTableCellType.Regular, text: node.state, neutral: true},
+    });
+    if (expanded && node.members) {
+      rows.push(...hierarchyRows(node.members, level + 1, node.id));
+    }
+  }
+  return rows;
+};
+
+const compareCellText = (a: ObcTableCellData, b: ObcTableCellData) => {
+  const text = (value: ObcTableCellData) =>
+    value?.type === ObcTableCellType.Regular ? String(value.text ?? '') : '';
+  return text(a).localeCompare(text(b));
+};
+
+export const Hierarchy: Story = {
+  args: {
+    width: 700,
+    columns: [
+      {
+        label: 'System',
+        key: 'system',
+        sortable: true,
+        compareFunction: compareCellText,
+      },
+      {label: 'Location', key: 'location'},
+      {label: 'State', key: 'state'},
+    ],
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Rows form a tree through `parentId` and `level`. The table draws the indent and the chevron and reports `expand-toggle`; the story owns which rows are collapsed and passes only the visible ones. Sorting the System column reorders each sibling set on its own, so a child never leaves its parent.',
+      },
+    },
+  },
+  render: (args) => {
+    return html`<obc-table
+      .data=${hierarchyRows(systemTree)}
+      .columns=${args.columns}
+      .striped=${true}
+      @expand-toggle=${(e: ObcTableExpandToggleEvent) => {
+        if (e.detail.expanded) {
+          collapsedRowIds.delete(e.detail.rowId);
+        } else {
+          collapsedRowIds.add(e.detail.rowId);
+        }
+        (e.target as ObcTable).data = hierarchyRows(systemTree);
+      }}
+    ></obc-table>`;
+  },
+};
+
+const cyclicRows = (): ObcTableRow[] => [
+  {
+    id: 'standalone',
+    level: 0,
+    system: {type: ObcTableCellType.Regular, text: 'Ballast'},
+    parent: {type: ObcTableCellType.Regular, text: '—', neutral: true},
+  },
+  {
+    id: 'pump-a',
+    parentId: 'pump-b',
+    level: 1,
+    system: {type: ObcTableCellType.Regular, text: 'Pump A'},
+    parent: {type: ObcTableCellType.Regular, text: 'pump-b', neutral: true},
+  },
+  {
+    id: 'pump-b',
+    parentId: 'pump-a',
+    level: 1,
+    system: {type: ObcTableCellType.Regular, text: 'Pump B'},
+    parent: {type: ObcTableCellType.Regular, text: 'pump-a', neutral: true},
+  },
+];
+
+export const CyclicHierarchy: Story = {
+  args: {width: 700},
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Regression guard. Both tables get the same three rows, two of which name each other as `parentId`. `sortWithinSiblings()` walks down from rows whose `parentId` is absent from the data, so the cycle yields no root; the rows it cannot reach are re-entered as a top-level sibling set instead of being dropped. Both tables list all three rows, in the sort order each is given. Make all three rows cyclic and all three still render.',
+      },
+    },
+  },
+  render: (args) => {
+    const columns = (sorted: boolean) => [
+      {
+        label: 'System',
+        key: 'system',
+        ...(sorted
+          ? {
+              sortable: true as const,
+              sortDirection: 'asc' as const,
+              compareFunction: compareCellText,
+            }
+          : {}),
+      },
+      {label: 'Declared parentId', key: 'parent'},
+    ];
+    return html`<div style="display: grid; gap: 24px; width: ${args.width}px;">
+      <div>
+        <p>Unsorted</p>
+        <obc-table .data=${cyclicRows()} .columns=${columns(false)}></obc-table>
+      </div>
+      <div>
+        <p>Sorted on System — the cyclic rows are recovered</p>
+        <obc-table .data=${cyclicRows()} .columns=${columns(true)}></obc-table>
+      </div>
+    </div>`;
+  },
+};
+
+const cycleWithDescendantRows = (): ObcTableRow[] => [
+  {
+    id: 'standalone',
+    level: 0,
+    system: {type: ObcTableCellType.Regular, text: 'Ballast'},
+    parent: {type: ObcTableCellType.Regular, text: '—', neutral: true},
+  },
+  {
+    id: 'pump-a',
+    parentId: 'pump-b',
+    level: 1,
+    system: {type: ObcTableCellType.Regular, text: 'Pump A'},
+    parent: {type: ObcTableCellType.Regular, text: 'pump-b', neutral: true},
+  },
+  {
+    id: 'pump-b',
+    parentId: 'pump-a',
+    level: 1,
+    system: {type: ObcTableCellType.Regular, text: 'Pump B'},
+    parent: {type: ObcTableCellType.Regular, text: 'pump-a', neutral: true},
+  },
+  {
+    id: 'pump-sensor',
+    parentId: 'pump-a',
+    level: 2,
+    system: {type: ObcTableCellType.Regular, text: 'Pump sensor'},
+    parent: {type: ObcTableCellType.Regular, text: 'pump-a', neutral: true},
+  },
+];
+
+export const CycleWithDescendants: Story = {
+  args: {width: 700},
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Regression guard for the blast radius of a cycle. Pump sensor has one ordinary parent and is in no cycle, but its parent sits in one, so recovering only the cycle members would still lose it. All four rows render in both tables; Pump sensor stays under Pump A, because the recovered rows are walked, not flattened.',
+      },
+    },
+  },
+  render: (args) => {
+    const columns = (sorted: boolean) => [
+      {
+        label: 'System',
+        key: 'system',
+        ...(sorted
+          ? {
+              sortable: true as const,
+              sortDirection: 'asc' as const,
+              compareFunction: compareCellText,
+            }
+          : {}),
+      },
+      {label: 'Declared parentId', key: 'parent'},
+    ];
+    return html`<div style="display: grid; gap: 24px; width: ${args.width}px;">
+      <div>
+        <p>Unsorted</p>
+        <obc-table
+          .data=${cycleWithDescendantRows()}
+          .columns=${columns(false)}
+        ></obc-table>
+      </div>
+      <div>
+        <p>Sorted on System — the cycle and its descendant are recovered</p>
+        <obc-table
+          .data=${cycleWithDescendantRows()}
+          .columns=${columns(true)}
+        ></obc-table>
+      </div>
+    </div>`;
+  },
+};

package/src/components/table/table.ts

@@ -13,6 +13,7 @@ import '../table-header-item/table-header-item.js';
 import {ObcTableHeaderItemType} from '../table-header-item/table-header-item.js';
 import {classMap} from 'lit/directives/class-map.js';
 import '../button/button.js';
+import '../../icons/icon-chevron-right-google.js';
 import {CheckboxStatus, ObcCheckboxChangeEvent} from '../checkbox/checkbox.js';
 import {TagColor} from '../tag/tag.js';
 import '../../building-blocks/bar-horizontal/bar-horizontal.js';
@@ -130,7 +131,11 @@ export type ObcTableCellData =
 export interface ObcTableRow {
   selected?: boolean;
   id: string;
-  [key: string]: ObcTableCellData | boolean | undefined | string;
+  parentId?: string;
+  level?: number;
+  expandable?: boolean;
+  expanded?: boolean;
+  [key: string]: ObcTableCellData | boolean | undefined | string | number;
 }
 
 export interface ObcTableColumnUnsortable<
@@ -187,6 +192,11 @@ export type ObcTableRowClickEvent = CustomEvent<{
   row: ObcTableRow;
 }>;
 
+export type ObcTableExpandToggleEvent = CustomEvent<{
+  rowId: string;
+  expanded: boolean;
+}>;
+
 function cssPart(value: ObcTableCellData, subpart: string): string | undefined {
   if (value.cssPart) {
     return `${value.cssPart} ${subpart}`;
@@ -206,11 +216,17 @@ function cssPart(value: ObcTableCellData, subpart: string): string | undefined {
  * - Cell rendering variants: `checkbox`, `tag`, `horizontal-bar`, and `button` cell types.
  * - Visual variants: `rowDivider`, `striped`, `narrowHeader`, and `showHeader`.
  * - Sorting support for sortable columns via column definitions.
+ * - Hierarchical rows via `parentId`, `level`, `expandable` and `expanded`.
  *
  * Usage Guidelines
  * - Controlled selection: pass `selectedRowIds` and update it on `selection-change`.
  * - Uncontrolled selection: pass `defaultSelectedRowIds` and listen to `selection-change`.
  * - Use `selectAllAriaLabel` to customize the header checkbox accessibility label.
+ * - Hierarchy is controlled, and flat: pass only the rows that are currently
+ *   visible, each with the `parentId` of its parent row, and drop a collapsed
+ *   group's descendants from `data` on `expand-toggle`. The table draws the
+ *   indent and the chevron, keeps each sibling set sorted within its parent,
+ *   and owns no expansion state of its own.
  *
  * Slots/Content
  * - This component does not expose public slots. Provide content via `data` and `columns`.
@@ -221,6 +237,15 @@ function cssPart(value: ObcTableCellData, subpart: string): string | undefined {
  * - `cell-checkbox-change` fires when a checkbox cell changes.
  * - `cell-tag-click` fires when a tag inside a cell is clicked.
  * - `selection-change` fires when row selection changes (source: `row` or `header`).
+ * - `expand-toggle` fires when a group row's chevron or expand key is used.
+ *
+ * Accessibility
+ * A table with hierarchical rows renders as a
+ * [treegrid](https://www.w3.org/WAI/ARIA/apg/patterns/treegrid/): rows carry
+ * `aria-level`, and group rows `aria-expanded`. Right expands a collapsed
+ * group, Left collapses an expanded one or moves to the parent row. Cell-level
+ * arrow navigation, which the full pattern also specifies, is out of scope —
+ * arrow keys move between rows, matching the flat table.
  *
  * Best Practices
  * - Keep column `key` values stable across renders to avoid selection or sorting resets.
@@ -247,6 +272,7 @@ function cssPart(value: ObcTableCellData, subpart: string): string | undefined {
  * @fires {ObcTableCellCheckboxChangeEvent} cell-checkbox-change - Fired when a cell checkbox is changed.
  * @fires {ObcTableCellTagClickEvent} cell-tag-click - Fired when a tag inside a cell is clicked.
  * @fires {ObcTableSelectionChangeEvent} selection-change - Fired when row selection changes.
+ * @fires {ObcTableExpandToggleEvent} expand-toggle - Fired when a group row is expanded or collapsed.
  * @beta
  */
 @customElement('obc-table')
@@ -273,6 +299,50 @@ export class ObcTable extends LitElement {
 
   private _previousPositions: {top: number; index: string}[] = [];
 
+  private get hasHierarchy() {
+    return this.data.some(
+      (row) =>
+        row.parentId !== undefined ||
+        (row.level ?? 0) > 0 ||
+        row.expandable === true
+    );
+  }
+
+  private sortWithinSiblings(
+    rows: ObcTableRow[],
+    compare: (a: ObcTableRow, b: ObcTableRow) => number
+  ) {
+    const ids = new Set(rows.map((row) => row.id));
+    const childrenByParent = new Map<string, ObcTableRow[]>();
+    const roots: ObcTableRow[] = [];
+    for (const row of rows) {
+      const parentId = row.parentId;
+      if (parentId !== undefined && parentId !== row.id && ids.has(parentId)) {
+        const siblings = childrenByParent.get(parentId) ?? [];
+        siblings.push(row);
+        childrenByParent.set(parentId, siblings);
+      } else {
+        roots.push(row);
+      }
+    }
+
+    const sorted: ObcTableRow[] = [];
+    const visited = new Set<string>();
+    const visit = (siblings: ObcTableRow[]) => {
+      for (const row of [...siblings].sort(compare)) {
+        if (visited.has(row.id)) {
+          continue;
+        }
+        visited.add(row.id);
+        sorted.push(row);
+        visit(childrenByParent.get(row.id) ?? []);
+      }
+    };
+    visit(roots);
+    visit(rows.filter((row) => !visited.has(row.id)));
+    return sorted;
+  }
+
   get sortedData() {
     if (this._sortByColumnIdx === undefined) {
       return this.data;
@@ -285,8 +355,7 @@ export class ObcTable extends LitElement {
       return this.data;
     }
     const sortDirection = this._sortDirection;
-    const sortedData = [...this.data];
-    sortedData.sort((a, b) => {
+    const compare = (a: ObcTableRow, b: ObcTableRow) => {
       const aValue = a[sortByColumn.key];
       const bValue = b[sortByColumn.key];
       if (sortDirection === 'asc') {
@@ -304,7 +373,12 @@ export class ObcTable extends LitElement {
           a
         );
       }
-    });
+    };
+    if (this.hasHierarchy) {
+      return this.sortWithinSiblings(this.data, compare);
+    }
+    const sortedData = [...this.data];
+    sortedData.sort(compare);
     return sortedData;
   }
 
@@ -329,6 +403,42 @@ export class ObcTable extends LitElement {
     );
   }
 
+  private _handleExpandToggle(row: ObcTableRow, expanded: boolean) {
+    if (!row.expandable) {
+      return;
+    }
+    this.dispatchEvent(
+      new CustomEvent('expand-toggle', {
+        detail: {rowId: row.id, expanded},
+      }) as ObcTableExpandToggleEvent
+    );
+  }
+
+  private _renderRowExpander(row: ObcTableRow) {
+    if (!this.hasHierarchy) {
+      return nothing;
+    }
+    const level = row.level ?? 0;
+    return html`<span
+      class="row-expander"
+      style="--row-level: ${level}"
+      aria-hidden="true"
+    >
+      ${row.expandable
+        ? html`<span
+            class=${classMap({chevron: true, expanded: row.expanded ?? false})}
+            @click=${(event: MouseEvent) => {
+              event.preventDefault();
+              event.stopPropagation();
+              this._handleExpandToggle(row, !(row.expanded ?? false));
+            }}
+          >
+            <obi-chevron-right-google></obi-chevron-right-google>
+          </span>`
+        : nothing}
+    </span>`;
+  }
+
   private _focusFirstRow() {
     const firstRow = this.renderRoot.querySelector<HTMLButtonElement>(
       'button[role="row"].grid-row'
@@ -393,6 +503,13 @@ export class ObcTable extends LitElement {
 
   private _handleRowKeyDown(event: KeyboardEvent) {
     const key = event.key;
+    if (
+      this.hasHierarchy &&
+      (key === 'ArrowRight' || key === 'ArrowLeft') &&
+      this._handleRowExpandKey(event, key)
+    ) {
+      return;
+    }
     if (
       key !== 'ArrowDown' &&
       key !== 'ArrowUp' &&
@@ -447,6 +564,37 @@ export class ObcTable extends LitElement {
     }
   }
 
+  private _handleRowExpandKey(
+    event: KeyboardEvent,
+    key: 'ArrowRight' | 'ArrowLeft'
+  ) {
+    const target = event.currentTarget as HTMLButtonElement | null;
+    const rowId = target?.dataset.rowId;
+    const row = this.sortedData.find((candidate) => candidate.id === rowId);
+    if (!row) return false;
+
+    const expanded = row.expanded ?? false;
+    if (key === 'ArrowRight' && row.expandable && !expanded) {
+      this._handleExpandToggle(row, true);
+    } else if (key === 'ArrowLeft' && row.expandable && expanded) {
+      this._handleExpandToggle(row, false);
+    } else if (key === 'ArrowLeft') {
+      const parent = this.renderRoot.querySelector<HTMLButtonElement>(
+        `button[role="row"].grid-row[data-row-id="${CSS.escape(
+          row.parentId ?? ''
+        )}"]`
+      );
+      if (!parent) return false;
+      parent.focus();
+    } else {
+      return false;
+    }
+
+    event.preventDefault();
+    event.stopPropagation();
+    return true;
+  }
+
   private _getAllPositions(): {
     top: number;
     height: number;
@@ -459,7 +607,6 @@ export class ObcTable extends LitElement {
       )
     );
 
-    // Calculate the zoom factor for the first row
     const firstRow = rows[0];
     if (!firstRow) {
       return [];
@@ -609,7 +756,7 @@ export class ObcTable extends LitElement {
           --grid-columns-rest: ${selectionColumnCount};
           --selection-column-width: var(--menu-navigation-components-table-item-touch-target-size);
         "
-        role="table"
+        role=${this.hasHierarchy ? 'treegrid' : 'table'}
       >
         ${this.showHeader
           ? html`
@@ -741,8 +888,18 @@ export class ObcTable extends LitElement {
                   data-row-id=${row.id}
                   style="grid-row: ${rowIndex + 1}"
                   part="row"
+                  aria-level=${ifDefined(
+                    this.hasHierarchy ? (row.level ?? 0) + 1 : undefined
+                  )}
+                  aria-expanded=${ifDefined(
+                    row.expandable ? (row.expanded ?? false) : undefined
+                  )}
                 >
-                  ${map(effectiveColumns, (col) => {
+                  ${map(effectiveColumns, (col, colIndex) => {
+                    const expander =
+                      colIndex === (this.selectable ? 1 : 0)
+                        ? this._renderRowExpander(row)
+                        : nothing;
                     if (this.selectable && col.key === '__selection__') {
                       const checked = this._selectedRowIds.has(row.id);
                       return html`<div
@@ -765,7 +922,9 @@ export class ObcTable extends LitElement {
                     }
                     const value = row[col.key];
                     if (value === undefined) {
-                      return html`<div class="grid-cell" role="cell"></div>`;
+                      return html`<div class="grid-cell" role="cell">
+                        ${expander}
+                      </div>`;
                     }
                     if (col.renderCell) {
                       return html`<div
@@ -775,7 +934,7 @@ export class ObcTable extends LitElement {
                         role="cell"
                         part=${ifDefined((value as ObcTableCellData).cssPart)}
                       >
-                        ${col.renderCell(
+                        ${expander}${col.renderCell(
                           value as ObcTableCellData,
                           row,
                           row.id
@@ -785,7 +944,8 @@ export class ObcTable extends LitElement {
                       return this._renderCell(
                         value as ObcTableCellData,
                         row,
-                        col
+                        col,
+                        expander
                       );
                     }
                   })}
@@ -951,7 +1111,8 @@ export class ObcTable extends LitElement {
   private _renderCell(
     value: ObcTableCellData,
     row: ObcTableRow,
-    column: ObcTableColumn<ObcTableCellData, ObcTableRow>
+    column: ObcTableColumn<ObcTableCellData, ObcTableRow>,
+    expander: HTMLTemplateResult | typeof nothing = nothing
   ) {
     if (value.type === ObcTableCellType.Regular) {
       return html`<div
@@ -968,7 +1129,7 @@ export class ObcTable extends LitElement {
         role="cell"
         part=${ifDefined(cssPart(value, 'cell'))}
       >
-        ${value.icon3
+        ${expander}${value.icon3
           ? html`<span class="icon" part=${ifDefined(cssPart(value, 'icon3'))}
               >${value.icon3}</span
             >`
@@ -999,6 +1160,7 @@ export class ObcTable extends LitElement {
         class="grid-cell button ${column.dividerRight ? 'divider-right' : ''}"
         role="cell"
       >
+        ${expander}
         <obc-button
           variant="normal"
           fullWidth
@@ -1036,6 +1198,7 @@ export class ObcTable extends LitElement {
         role="cell"
         part=${ifDefined(cssPart(value, 'cell'))}
       >
+        ${expander}
         <obc-checkbox
           .status=${value.status ?? CheckboxStatus.unchecked}
           .disabled=${value.disabled ?? false}
@@ -1083,7 +1246,7 @@ export class ObcTable extends LitElement {
         role="cell"
         part=${ifDefined(cssPart(value, 'cell'))}
       >
-        ${visibleTags.map((tag) => {
+        ${expander}${visibleTags.map((tag) => {
           const hasIcon = tag.hasIcon ?? tag.icon !== undefined;
           return html`<obc-tag
             .label=${tag.label}
@@ -1122,6 +1285,7 @@ export class ObcTable extends LitElement {
         role="cell"
         part=${ifDefined(cssPart(value, 'cell'))}
       >
+        ${expander}
         <obc-bar-horizontal
           .minValue=${value.minValue ?? 0}
           .maxValue=${value.maxValue ?? 100}

package/src/types.ts

@@ -34,11 +34,11 @@ export enum AlertCategory {
 }
 
 export interface Alert {
-  id: string; // The id of the alert
-  tagId: string; // The tag ID visible to the user
+  id: string;
+  tagId: string;
   source: string;
   text: string;
-  note?: string; // The note of the alert, typically by the operator
+  note?: string;
   acknowledged:
     | false
     | {
@@ -67,8 +67,10 @@ export interface Alert {
         blockedEndTime?: Date;
         blockedBy?: string;
       };
-  noAck?: boolean; // If true, the alarm has no ack button
+  noAck?: boolean;
+  noSilence?: boolean;
   category?: AlertCategory;
+  memberOf?: string[];
 }
 
 export function isActive(alert: Alert) {