@oicl/openbridge-webcomponents-full-bundle 2.0.0-next.136 → 2.0.0-next.137

package/src/automation/hydraulic-valve-x-2/hydraulic-valve-x-2.ts

@@ -0,0 +1,101 @@
+import {html} from 'lit';
+import type {TemplateResult} from 'lit';
+import {property} from 'lit/decorators.js';
+import {customElement} from '../../decorator.js';
+import {ObcShuffleButtonBase} from '../shuffle-button/shuffle-button-base.js';
+import '../../icons/icon-hydraulic-01.js';
+import '../../icons/icon-hydraulic-02.js';
+import '../../icons/icon-hydraulic-07.js';
+import '../../icons/icon-hydraulic-10.js';
+import '../../icons/icon-hydraulic-11.js';
+
+/**
+ * Detail payload for the `position-selected` event: the zero-based position
+ * the user requested (0 = first, 1 = second).
+ *
+ * Declared here rather than imported from the base: the wrapper generators
+ * resolve event types in the component's own module only.
+ */
+export interface PositionSelectedDetail {
+  position: number;
+}
+
+/**
+ * Port/position configuration of `<obc-hydraulic-valve-x-2>`:
+ * `2/2`, `3/2` or `4/2` (ports/positions). Each value maps to its own pair of
+ * position symbols.
+ */
+export enum HydraulicValveX2Type {
+  TwoTwo = '2/2',
+  ThreeTwo = '3/2',
+  FourTwo = '4/2',
+}
+
+/**
+ * `<obc-hydraulic-valve-x-2>` – Position selector symbol for a two-position valve.
+ *
+ * Shows the valve's two positions as icon thumbs on a shared track. The
+ * selected position always occupies the fixed center slot; the option thumb
+ * sits to its left or right depending on logical order, and an empty spacer
+ * slot keeps the total width constant (three 48px slots at regular size).
+ *
+ * ## Features / Variants
+ * - `type` selects the port/position configuration: `2/2`, `3/2` or `4/2`.
+ * - `vertical` stacks the positions top to bottom and rotates the symbols to
+ *   match a vertical flow path.
+ * - Controlled selection: clicking the option or pressing arrow keys fires
+ *   `position-selected`; the application updates `selectedPosition` once the
+ *   change is confirmed.
+ * - Scales with the component size classes (`obc-component-size-*`).
+ *
+ * ## Usage Guidelines
+ * Use to display and command the position of a two-position valve. For 4/3
+ * directional valves use `<obc-hydraulic-valve-4-3>`; for a static check
+ * valve symbol use `<obc-hydraulic-check-valve>`. Bind `selectedPosition` to
+ * the position the device reports, not to the last request, so the symbol
+ * never shows a position the valve has not reached.
+ *
+ * ## Events
+ * - `position-selected` – Fired when the user requests a position (click or
+ *   arrow key). Detail: `{position: number}` (0 = first, 1 = second).
+ *
+ * @property type - Port/position configuration.
+ * @property ariaLabel - Accessible name for the control.
+ * @fires {CustomEvent<PositionSelectedDetail>} position-selected - Fired when the user requests a position (click or arrow key).
+ * @experimental
+ */
+@customElement('obc-hydraulic-valve-x-2')
+export class ObcHydraulicValveX2 extends ObcShuffleButtonBase {
+  @property({type: String}) type: HydraulicValveX2Type =
+    HydraulicValveX2Type.TwoTwo;
+
+  @property({type: String}) override ariaLabel = 'Hydraulic valve';
+
+  protected override get positionCount(): number {
+    return 2;
+  }
+
+  protected override renderPositionIcon(position: number): TemplateResult {
+    switch (this.type) {
+      case HydraulicValveX2Type.ThreeTwo:
+        return position === 0
+          ? html`<obi-hydraulic-11></obi-hydraulic-11>`
+          : html`<obi-hydraulic-10></obi-hydraulic-10>`;
+      case HydraulicValveX2Type.FourTwo:
+        return position === 0
+          ? html`<obi-hydraulic-02></obi-hydraulic-02>`
+          : html`<obi-hydraulic-07></obi-hydraulic-07>`;
+      case HydraulicValveX2Type.TwoTwo:
+      default:
+        return position === 0
+          ? html`<obi-hydraulic-02></obi-hydraulic-02>`
+          : html`<obi-hydraulic-01></obi-hydraulic-01>`;
+    }
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'obc-hydraulic-valve-x-2': ObcHydraulicValveX2;
+  }
+}

package/src/automation/shuffle-button/shuffle-button-base.ts

@@ -0,0 +1,170 @@
+import {LitElement, html, unsafeCSS} from 'lit';
+import type {PropertyValues, TemplateResult} from 'lit';
+import {property, state} from 'lit/decorators.js';
+import {classMap} from 'lit/directives/class-map.js';
+import componentStyle from './shuffle-button.css?inline';
+import {
+  clampPosition,
+  shuffleSlotCount,
+  shuffleWindowOffset,
+} from './shuffle-layout.js';
+
+/**
+ * Detail payload for the `position-selected` event dispatched by
+ * shuffle-button components. `position` is the zero-based position the user
+ * requested.
+ */
+export interface PositionSelectedDetail {
+  position: number;
+}
+
+/**
+ * The `position-selected` event dispatched by shuffle-button components.
+ */
+export type PositionSelectedEvent = CustomEvent<PositionSelectedDetail>;
+
+/**
+ * Base class for shuffle-button selectors: a control whose selected thumb
+ * always occupies the fixed center slot of a (2·n−1)-slot row (or column when
+ * `vertical`). Option thumbs keep their logical order and redistribute to
+ * either side of the selected thumb; empty spacer slots absorb the remaining
+ * length so the total size never changes.
+ *
+ * ## Controlled selection
+ * Clicking an option or pressing an arrow key only fires `position-selected`.
+ * The host application sets `selectedPosition` once the device confirms the
+ * change, so the control never shows a position the device has not reached.
+ *
+ * ## Keyboard
+ * Follows the WAI-ARIA radio group pattern
+ * (https://www.w3.org/WAI/ARIA/apg/patterns/radio/): `role="radiogroup"` with
+ * one `role="radio"` thumb per position, a single tab stop on the selected
+ * thumb, and Left/Up and Right/Down moving to the previous/next position with
+ * wrap-around. Departures: arrow keys request the position rather than moving
+ * the checked state (controlled selection above), and focus follows the thumb
+ * only once the host confirms it. Space/Enter on a focused thumb request it
+ * through the native button click. Home/End are out of scope.
+ *
+ * Subclasses define `positionCount` and `renderPositionIcon()` and carry the
+ * `@fires position-selected` tag: the manifest and the framework wrappers read
+ * events from the registered element, not from this base.
+ *
+ * Not declared `abstract`: the wrapper generators wrap every `LitElement`
+ * subclass and pass its constructor as a concrete `Constructor<T>`, so the
+ * default implementations below stand in for abstract members (same as
+ * `ObcAbstractAutomationButton`).
+ *
+ * @property selectedPosition - Zero-based index of the currently selected position. Out-of-range values are clamped.
+ * @property vertical - Lays the control out vertically: positions stack top to bottom and the position symbols rotate 90° counter-clockwise to match a vertical flow path.
+ * @property ariaLabel - Accessible name for the radio group (the control is icon-only). Concrete components override the default with a device-specific name.
+ */
+export class ObcShuffleButtonBase extends LitElement {
+  @property({type: Number}) selectedPosition = 1;
+
+  @property({type: Boolean}) vertical = false;
+
+  @property({type: String}) override ariaLabel = 'Position selector';
+
+  @state() private suppressHover = false;
+
+  protected get positionCount(): number {
+    return 1;
+  }
+
+  protected renderPositionIcon(_position: number): TemplateResult {
+    return html``;
+  }
+
+  override render() {
+    const count = this.positionCount;
+    const selected = clampPosition(count, this.selectedPosition);
+    return html`
+      <div
+        class=${classMap({shuffle: true, vertical: this.vertical})}
+        role="radiogroup"
+        aria-label=${this.ariaLabel}
+        aria-orientation=${this.vertical ? 'vertical' : 'horizontal'}
+        style="--_shuffle-slot-count: ${shuffleSlotCount(
+          count
+        )}; --_shuffle-window-offset: ${shuffleWindowOffset(
+          count,
+          selected
+        )};${this.suppressHover ? ' --obc-can-hover: 0;' : ''}"
+        @keydown=${this.handleKeydown}
+        @pointermove=${this.restoreHover}
+      >
+        <div class="window">
+          <div class="track"></div>
+          ${Array.from({length: count}, (_, position) =>
+            this.renderThumb(position, selected)
+          )}
+        </div>
+      </div>
+    `;
+  }
+
+  private renderThumb(position: number, selected: number) {
+    const isSelected = position === selected;
+    return html`
+      <button
+        class=${classMap({thumb: true, selected: isSelected})}
+        type="button"
+        role="radio"
+        aria-checked=${isSelected}
+        tabindex=${isSelected ? 0 : -1}
+        @click=${() => this.requestPosition(position)}
+      >
+        <div class="visible-wrapper">
+          <div class="icon-container">${this.renderPositionIcon(position)}</div>
+        </div>
+      </button>
+    `;
+  }
+
+  private requestPosition(position: number) {
+    if (position === clampPosition(this.positionCount, this.selectedPosition)) {
+      return;
+    }
+    // Browsers keep :hover on the thumb that shuffles away from under a
+    // stationary pointer; mute hover feedback until the pointer really moves.
+    this.suppressHover = true;
+    const event: PositionSelectedEvent = new CustomEvent('position-selected', {
+      detail: {position},
+      bubbles: true,
+      composed: true,
+    });
+    this.dispatchEvent(event);
+  }
+
+  private restoreHover() {
+    this.suppressHover = false;
+  }
+
+  private handleKeydown(event: KeyboardEvent) {
+    let delta: number;
+    if (event.key === 'ArrowRight' || event.key === 'ArrowDown') {
+      delta = 1;
+    } else if (event.key === 'ArrowLeft' || event.key === 'ArrowUp') {
+      delta = -1;
+    } else {
+      return;
+    }
+    event.preventDefault();
+    const count = this.positionCount;
+    const selected = clampPosition(count, this.selectedPosition);
+    this.requestPosition((selected + delta + count) % count);
+  }
+
+  protected override updated(changed: PropertyValues) {
+    if (
+      changed.has('selectedPosition') &&
+      this.shadowRoot?.activeElement instanceof HTMLElement
+    ) {
+      this.shadowRoot
+        .querySelector<HTMLButtonElement>('button.thumb.selected')
+        ?.focus();
+    }
+  }
+
+  static override styles = unsafeCSS(componentStyle);
+}

package/src/automation/shuffle-button/shuffle-button.css

@@ -0,0 +1,136 @@
+:host {
+  display: inline-block;
+}
+
+/* ---- Slot grid ----
+ * The box is (2n-1) touch-target slots; the selected thumb always sits in the
+ * center slot, so the box never changes size with the selection. */
+.shuffle {
+  --shuffle-slot-size: var(--global-size-spacing-touch-target-min);
+  --_shuffle-slot-count: 1;
+  --_shuffle-window-offset: 0;
+  position: relative; /* containing block for the sliding .window */
+  width: calc(var(--_shuffle-slot-count) * var(--shuffle-slot-size));
+  height: var(--shuffle-slot-size);
+}
+
+.shuffle.vertical {
+  width: var(--shuffle-slot-size);
+  height: calc(var(--_shuffle-slot-count) * var(--shuffle-slot-size));
+}
+
+/* The window holds the n thumbs in logical order and slides by whole slots so
+ * the selected one lands in the center; the box above stays put. */
+.window {
+  position: absolute; /* slides inside the fixed-size .shuffle box */
+  top: 0;
+  left: 0;
+  display: flex;
+  transform: translateX(
+    calc(var(--_shuffle-window-offset) * var(--shuffle-slot-size))
+  );
+  transition: transform 100ms ease-out; /* TODO(designer): Figma is WIP and specifies no motion */
+}
+
+.shuffle.vertical .window {
+  flex-direction: column;
+  transform: translateY(
+    calc(var(--_shuffle-window-offset) * var(--shuffle-slot-size))
+  );
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .window {
+    transition: none;
+  }
+}
+
+/* The track is inset to the visual target height so it aligns with the thumbs'
+ * visible wrappers, not with the touch slots. */
+.track {
+  @mixin style style=indent noClick=true;
+  position: absolute;
+  inset: calc(
+      (
+          var(--shuffle-slot-size) -
+            var(--global-size-spacing-visual-target-min)
+        ) /
+        2
+    )
+    0;
+  border-radius: var(--global-border-radius-border-radius-base);
+  box-sizing: border-box; /* the mixin border must not grow the track past the slots */
+}
+
+.shuffle.vertical .track {
+  inset: 0
+    calc(
+      (
+          var(--shuffle-slot-size) -
+            var(--global-size-spacing-visual-target-min)
+        ) /
+        2
+    );
+}
+
+/* ---- Thumbs ----
+ * Two-layer pattern: the button is the touch target and focus-ring layer, the
+ * .visible-wrapper is the visual target. */
+.thumb {
+  position: relative;
+  width: var(--shuffle-slot-size);
+  height: var(--shuffle-slot-size);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0; /* a slot never shrinks below the touch target */
+  padding: 0;
+  margin: 0;
+  border: none;
+  background: none;
+  cursor: pointer;
+}
+
+button.thumb {
+  @mixin style style=flat visibleWrapperClass=.visible-wrapper;
+}
+
+.visible-wrapper {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  height: var(--global-size-spacing-visual-target-min);
+  box-sizing: border-box;
+  border-radius: var(--global-border-radius-border-radius-base);
+  color: var(--automation-device-secondary-color);
+}
+
+.thumb.selected {
+  cursor: default; /* clicking the selected position is a no-op */
+}
+
+.thumb.selected .visible-wrapper {
+  background-color: var(--automation-pipe-primary-color);
+  border: 1px solid var(--automation-pipe-tertiary-color);
+  color: var(--automation-device-tertiary-color);
+}
+
+.shuffle.vertical .visible-wrapper {
+  width: var(--global-size-spacing-visual-target-min);
+  height: 100%;
+}
+
+.icon-container {
+  width: var(--global-size-spacing-icon-icon-size-regular);
+  height: var(--global-size-spacing-icon-icon-size-regular);
+}
+
+.shuffle.vertical .icon-container {
+  transform: rotate(-90deg); /* symbols are drawn for horizontal flow */
+}
+
+.icon-container > * {
+  width: 100%;
+  height: 100%;
+}

package/src/automation/shuffle-button/shuffle-layout.spec.ts

@@ -0,0 +1,44 @@
+import {describe, expect, it} from 'vitest';
+import {
+  clampPosition,
+  shuffleSlotCount,
+  shuffleWindowOffset,
+} from './shuffle-layout.js';
+
+describe('shuffleSlotCount', () => {
+  it('is 2n-1 so the selected thumb can sit center with all options on one side', () => {
+    expect(shuffleSlotCount(1)).toBe(1);
+    expect(shuffleSlotCount(2)).toBe(3);
+    expect(shuffleSlotCount(3)).toBe(5);
+  });
+});
+
+describe('clampPosition', () => {
+  it('passes through valid positions', () => {
+    expect(clampPosition(3, 0)).toBe(0);
+    expect(clampPosition(3, 2)).toBe(2);
+  });
+  it('clamps out-of-range and rounds non-integers', () => {
+    expect(clampPosition(3, -1)).toBe(0);
+    expect(clampPosition(3, 7)).toBe(2);
+    expect(clampPosition(3, 1.4)).toBe(1);
+  });
+  it('falls back to position 0 for NaN', () => {
+    expect(clampPosition(3, Number.NaN)).toBe(0);
+  });
+});
+
+describe('shuffleWindowOffset', () => {
+  it('offsets the window so the selected thumb lands in the center slot', () => {
+    expect(shuffleWindowOffset(3, 0)).toBe(2);
+    expect(shuffleWindowOffset(3, 1)).toBe(1);
+    expect(shuffleWindowOffset(3, 2)).toBe(0);
+    expect(shuffleWindowOffset(2, 0)).toBe(1);
+    expect(shuffleWindowOffset(2, 1)).toBe(0);
+    expect(shuffleWindowOffset(1, 0)).toBe(0);
+  });
+  it('clamps invalid selections', () => {
+    expect(shuffleWindowOffset(3, 9)).toBe(0);
+    expect(shuffleWindowOffset(3, -4)).toBe(2);
+  });
+});

package/src/automation/shuffle-button/shuffle-layout.ts

@@ -0,0 +1,21 @@
+/**
+ * Pure layout math for the shuffle-button mechanism: a selector whose selected
+ * thumb always occupies the fixed center slot of a (2n-1)-slot row while the
+ * remaining option thumbs keep their logical order on either side.
+ */
+
+export function clampPosition(positionCount: number, position: number): number {
+  const rounded = Number.isNaN(position) ? 0 : Math.round(position);
+  return Math.min(Math.max(rounded, 0), positionCount - 1);
+}
+
+export function shuffleSlotCount(positionCount: number): number {
+  return 2 * positionCount - 1;
+}
+
+export function shuffleWindowOffset(
+  positionCount: number,
+  selectedPosition: number
+): number {
+  return positionCount - 1 - clampPosition(positionCount, selectedPosition);
+}