@oicl/openbridge-webcomponents-full-bundle 2.0.0-next.102 → 2.0.0-next.103

package/src/navigation-instruments/watch/watch.ts

@@ -52,10 +52,16 @@ import {
 import {VesselImage, VesselImageSize, vesselImages} from './vessel.js';
 import {renderCurrent, renderWind} from './environment.js';
 import {customElement} from '../../decorator.js';
+import {type ZoomToFitArcFrame} from '../../svghelpers/arc-frame.js';
 import {
-  computeZoomToFitArcFrame,
-  type ZoomToFitArcFrame,
-} from '../../svghelpers/arc-frame.js';
+  applyPinnedHostSize,
+  computeRadialFrame,
+  estimateLabelWidthPx,
+  measureContainerPx,
+  NSWE_LABEL_WIDTH_PX,
+  observeInnerBox,
+  type RadialFrame,
+} from '../../svghelpers/radial-frame.js';
 export {VesselImage, VesselImageSize, vesselImages};
 
 export enum WatchCircleType {
@@ -202,7 +208,21 @@ export class ObcWatch extends LitElement {
 
   /** Whether the setpoint CSS angle has been initialised (to skip transition on first render). */
   private _setpointCssAngleInit = false;
+  /**
+   * Explicit padding override in SVG units: the un-zoomed viewBox becomes
+   * exactly `(176 + padding) * 2`. Setting it disables the automatic
+   * width-aware label reserve (issue #1021) — the caller owns label room.
+   */
   @property({type: Number}) padding: number | undefined;
+  /**
+   * Outer-ring diameter in CSS pixels. When set, the instrument renders at a
+   * fixed intrinsic size derived from the ring, arc shape and label reserve —
+   * so instruments sharing the same value have identical ring circumference
+   * regardless of label width or arc extent (like obc-donut-chart's
+   * fixedHeight). When unset (default), the instrument fills its container.
+   */
+  @property({type: Number, attribute: 'face-diameter'})
+  faceDiameter: number | undefined;
   @property({type: Array, attribute: false}) areas: WatchArea[] = [];
   @property({type: Array, attribute: false}) barAreas: WatchBarArea[] = [];
   @property({type: Array, attribute: false}) needles: WatchNeedle[] = [];
@@ -293,10 +313,13 @@ export class ObcWatch extends LitElement {
     return this._legacyRotationsPerMinute;
   }
 
-  // @ts-expect-error TS6133: The controller ensures that the render
-  // function is called on resize of the element
   private _resizeController = new ResizeController(this, {});
 
+  override firstUpdated(changed: PropertyValues): void {
+    super.firstUpdated(changed);
+    observeInnerBox(this._resizeController, this.renderRoot);
+  }
+
   override willUpdate(changed: PropertyValues): void {
     super.willUpdate(changed);
 
@@ -333,6 +356,11 @@ export class ObcWatch extends LitElement {
 
   override updated(changed: PropertyValues): void {
     super.updated(changed);
+    this._hostSizePinned = applyPinnedHostSize(
+      this,
+      this.arcFrame ? undefined : this._ownFrame,
+      this._hostSizePinned
+    );
     const el = this.rotType
       ? this.renderRoot.querySelector('#rot-spinner')
       : null;
@@ -356,6 +384,18 @@ export class ObcWatch extends LitElement {
 
   private _rOff = 0;
 
+  /**
+   * Set by the frame when the label reserve exceeded its cap: tick label
+   * texts are dropped instead of clipped (see radial-frame.ts).
+   */
+  private _labelsHidden = false;
+
+  /** The frame of the last render, when computed internally (no arcFrame). */
+  private _ownFrame: RadialFrame | undefined;
+
+  /** Whether the host size styles were set by applyPinnedHostSize. */
+  private _hostSizePinned = false;
+
   /**
    * Radius for a dial-band edge under zoom: additive (`base + _rOff`), keeping
    * band thickness constant in SVG units. INVARIANT: every band-edge radius
@@ -680,16 +720,8 @@ export class ObcWatch extends LitElement {
   }
 
   private getScale({width, height}: {width: number; height: number}): number {
-    let clientWidth = this.clientWidth;
-    let clientHeight = this.clientHeight;
-    if (clientWidth === 0 || clientHeight === 0) {
-      const box = this.parentElement?.getBoundingClientRect();
-      if (box) {
-        clientWidth = box.width;
-        clientHeight = box.height;
-      }
-    }
-    const scale = Math.min(clientWidth / width, clientHeight / height);
+    const container = measureContainerPx(this);
+    const scale = Math.min(container.width / width, container.height / height);
     // On first paint the element and its parent can both still be zero-sized, so
     // the scale is 0 (or non-finite). That value flows into `px / scale` label
     // math and yields ±Infinity coordinates the browser rejects. Fall back to a
@@ -701,17 +733,19 @@ export class ObcWatch extends LitElement {
     return scale;
   }
 
-  private getPadding(): number {
-    if (this.padding !== undefined) {
-      return this.padding;
+  /**
+   * Pixel width of the widest outside label, feeding the frame's label
+   * reserve (issue #1021). Explicit `padding` is a hard geometry override
+   * and disables the reserve, preserving legacy consumer output.
+   */
+  private getLabelWidthPx(): number {
+    if (this.padding !== undefined || this.tickmarksInside) {
+      return 0;
     }
-    const hasTickmarksWithText =
-      this.tickmarks.length > 0 &&
-      this.tickmarks.some((t) => t.text !== undefined);
-    if (hasTickmarksWithText && !this.tickmarksInside) {
-      return 24 * 2.5;
+    if (this.showLabels) {
+      return NSWE_LABEL_WIDTH_PX;
     }
-    return 24;
+    return estimateLabelWidthPx(this.tickmarks.map((t) => t.text));
   }
 
   override render() {
@@ -721,31 +755,33 @@ export class ObcWatch extends LitElement {
 
     if (this.arcFrame) {
       this._rOff = this.arcFrame.radiusOffset;
+      this._labelsHidden = false;
+      this._ownFrame = undefined;
       width = this.arcFrame.width;
       height = this.arcFrame.height;
       viewBox = this.arcFrame.viewBox;
-    } else if (this.zoomToFitArc && this.areas.length > 0) {
-      const ext = this.getPadding();
-      const targetSize = (176 + ext) * 2;
-      const frame = computeZoomToFitArcFrame({
+    } else {
+      const frame = computeRadialFrame({
+        basePadding: this.padding ?? 24,
+        labelWidthPx: this.getLabelWidthPx(),
+        clips: {
+          top: this.clipTop,
+          bottom: this.clipBottom,
+          left: this.clipLeft,
+          right: this.clipRight,
+        },
+        containerPx: measureContainerPx(this),
+        faceDiameter: this.faceDiameter,
+        zoomToFitArc: this.zoomToFitArc,
         areas: this.areas,
-        outerRadius: OUTER_RING_RADIUS,
         innerRadius: this.innerRingRadius,
-        extension: ext,
-        targetSize,
       });
       this._rOff = frame.radiusOffset;
+      this._labelsHidden = frame.labelsHidden;
+      this._ownFrame = frame;
       width = frame.width;
       height = frame.height;
       viewBox = frame.viewBox;
-    } else {
-      this._rOff = 0;
-      const full = (176 + this.getPadding()) * 2;
-      width = full * (1 - this.clipLeft / 100 - this.clipRight / 100);
-      height = full * (1 - this.clipTop / 100 - this.clipBottom / 100);
-      const left = -full / 2 + (full * this.clipLeft) / 100;
-      const top = -full / 2 + (full * this.clipTop) / 100;
-      viewBox = `${left} ${top} ${width} ${height}`;
     }
 
     const rOff = this._rOff;
@@ -764,7 +800,7 @@ export class ObcWatch extends LitElement {
         size: t.type,
         style: this.tickmarkStyle,
         scale,
-        text: this.showLabels ? undefined : t.text,
+        text: this.showLabels || this._labelsHidden ? undefined : t.text,
         inside: this.tickmarksInside,
         textRadius,
         rotation: this.rotation,
@@ -778,10 +814,14 @@ export class ObcWatch extends LitElement {
       ? this.advices.map((a) => renderAdvice(a, rOff))
       : nothing;
 
-    // Compute label positions once – used for both rendering and crosshair knockout.
-    const insideLabels = this.tickmarksInside && this.showLabels;
+    // Compute label positions once – used for both rendering and crosshair
+    // knockout. NSWE labels and the north arrow are px-fixed outside decor,
+    // so they follow the same labelsHidden degradation as tick label texts.
+    const showNsweLabels = this.showLabels && !this._labelsHidden;
+    const showNorthArrow = this.northArrow && !this._labelsHidden;
+    const insideLabels = this.tickmarksInside && showNsweLabels;
     const includeNorth = !this.northArrow;
-    const labelPositions = this.showLabels
+    const labelPositions = showNsweLabels
       ? getLabelPositions({
           scale,
           inside: this.tickmarksInside,
@@ -799,7 +839,7 @@ export class ObcWatch extends LitElement {
           includeNorth,
         })
       : nothing;
-    const northArrowEl = this.northArrow
+    const northArrowEl = showNorthArrow
       ? renderNorthArrow({
           scale,
           rotation: this.rotation,

package/src/storybook-util.ts

@@ -98,6 +98,16 @@ export function widthDecorator(
   story: () => unknown,
   context: {args: {width?: number; height?: number}}
 ): HTMLTemplateResult {
+  // Stories that manage their own container (e.g. user-resizable sizing
+  // playgrounds) opt out with `parameters: {widthDecorator: false}` — the
+  // fixed-size overflow:auto wrapper would fence in their resize handle.
+  // (Read via a cast so the signature stays assignable to Storybook's
+  // DecoratorFunction for every Meta typing in the repo.)
+  const parameters = (context as {parameters?: {widthDecorator?: boolean}})
+    .parameters;
+  if (parameters?.widthDecorator === false) {
+    return html`${story()}`;
+  }
   const width = context.args.width ?? 300;
   const height = context.args.height ?? width;
   return html` <div
@@ -107,3 +117,52 @@ export function widthDecorator(
     ${story()}
   </div>`;
 }
+
+/**
+ * User-resizable container for sizing-playground stories: drag the
+ * bottom-right corner and watch the content adapt. CSS `resize` only works
+ * with a non-visible `overflow`, hence `overflow: auto` on the box itself.
+ */
+export function resizableStoryBox(
+  content: unknown,
+  {width = 560, height = 320}: {width?: number; height?: number} = {}
+): HTMLTemplateResult {
+  return html`<div
+    style="resize: both; overflow: auto; border: 1px dashed var(--instrument-frame-tertiary-color, gray); width: ${width}px; height: ${height}px; display: flex; gap: 8px; align-items: stretch;"
+  >
+    ${content}
+  </div>`;
+}
+
+/**
+ * One captioned column inside a sizing-playground flex row. A `pinned`
+ * instrument sets its own intrinsic size (faceDiameter), so its column
+ * shrink-wraps; an adaptive one gets an equal share of the remaining space.
+ */
+export function playgroundColumn(
+  caption: string,
+  content: unknown,
+  {pinned = false}: {pinned?: boolean} = {}
+): HTMLTemplateResult {
+  return html`<div
+    style="flex: ${pinned
+      ? '0 0 auto'
+      : '1 1 0'}; min-width: 0; display: flex; flex-direction: column; gap: 2px;"
+  >
+    <span
+      style="flex: 0 0 auto; font-family: var(--font-family-main, sans-serif); font-size: 11px; color: var(--instrument-frame-secondary-color, gray); white-space: nowrap;"
+    >
+      ${caption}
+    </span>
+    <div style="flex: 1 1 0; min-height: 0;">${content}</div>
+  </div>`;
+}
+
+/** Short explanatory line rendered above a sizing-playground box. */
+export function storyHint(text: string): HTMLTemplateResult {
+  return html`<p
+    style="max-width: 70ch; margin: 0 0 8px; font-family: var(--font-family-main, sans-serif); font-size: 12px; color: var(--instrument-frame-secondary-color, gray);"
+  >
+    ${text}
+  </p>`;
+}

package/src/svghelpers/radial-frame.spec.ts

@@ -0,0 +1,307 @@
+import {describe, expect, it} from 'vitest';
+import {computeZoomToFitArcFrame} from './arc-frame.js';
+import {
+  computeRadialFrame,
+  estimateLabelWidthPx,
+  LABEL_RESERVE_MAX_FRACTION,
+} from './radial-frame.js';
+
+const ZOOM_AREAS = [
+  {
+    startAngle: -135,
+    endAngle: 135,
+    roundInsideCut: true,
+    roundOutsideCut: true,
+  },
+];
+
+describe('computeRadialFrame — back-compat identity', () => {
+  it('no labels reproduces the legacy (176+padding)*2 box', () => {
+    const f = computeRadialFrame({basePadding: 48});
+    expect(f.viewBox).toBe('-224 -224 448 448');
+    expect(f.width).toBe(448);
+    expect(f.height).toBe(448);
+    expect(f.x).toBe(-224);
+    expect(f.y).toBe(-224);
+    expect(f.radiusOffset).toBe(0);
+    expect(f.labelReserve).toBe(0);
+    expect(f.labelsHidden).toBe(false);
+    expect(f.hostWidthPx).toBeUndefined();
+  });
+
+  it('no labels + clips reproduces the legacy clipped box (rudder: top 40%)', () => {
+    const f = computeRadialFrame({
+      basePadding: 48,
+      clips: {top: 40, bottom: 0, left: 0, right: 0},
+    });
+    expect(f.x).toBe(-224);
+    expect(f.y).toBeCloseTo(-44.8);
+    expect(f.width).toBe(448);
+    expect(f.height).toBeCloseTo(268.8);
+  });
+
+  it('labels with a generous container never shrink below the base box', () => {
+    const f = computeRadialFrame({
+      basePadding: 48,
+      labelWidthPx: 14,
+      containerPx: {width: 2000, height: 2000},
+    });
+    expect(f.width).toBe(448);
+    expect(f.labelReserve).toBe(0);
+    expect(f.labelsHidden).toBe(false);
+  });
+});
+
+describe('computeRadialFrame — mode (a) label reserve', () => {
+  it('grows the box for 4-digit labels in a shrunk container', () => {
+    const f = computeRadialFrame({
+      basePadding: 48,
+      labelWidthPx: 28,
+      containerPx: {width: 200, height: 200},
+    });
+    // P = 9 + 28 + 4 = 41; side = 374 / (1 - 82/200)
+    expect(f.width).toBeCloseTo(374 / (1 - 82 / 200), 6);
+    expect(f.width).toBeGreaterThan(448);
+    expect(f.labelsHidden).toBe(false);
+    expect(f.labelReserve).toBeCloseTo((f.width - 448) / 2, 6);
+    // The label's far edge must fit inside the box at the implied scale.
+    const scale = 200 / f.width;
+    expect(f.scale).toBeCloseTo(scale, 6);
+    expect(187 + 41 / scale).toBeLessThanOrEqual(f.width / 2 + 1e-6);
+  });
+
+  it('hides labels past the reserve cap instead of growing unboundedly', () => {
+    const f = computeRadialFrame({
+      basePadding: 48,
+      labelWidthPx: 28,
+      containerPx: {width: 120, height: 120},
+    });
+    expect((2 * 41) / 120).toBeGreaterThan(LABEL_RESERVE_MAX_FRACTION);
+    expect(f.labelsHidden).toBe(true);
+    expect(f.labelReserve).toBe(0);
+    expect(f.width).toBe(448);
+  });
+
+  it('uses the binding axis with clips (180° sector in a short wide cell)', () => {
+    const f = computeRadialFrame({
+      basePadding: 48,
+      labelWidthPx: 21,
+      clips: {top: 0, bottom: 44, left: 0, right: 0},
+      containerPx: {width: 600, height: 120},
+    });
+    // fy = 0.56 → Ceff = min(600/1, 120/0.56); P = 34
+    const ceff = 120 / 0.56;
+    const side = 374 / (1 - 68 / ceff);
+    expect(f.width).toBeCloseTo(side, 6);
+    expect(f.height).toBeCloseTo(side * 0.56, 6);
+  });
+
+  it('falls back to scale 1 for a zero-size container (first paint)', () => {
+    const f = computeRadialFrame({
+      basePadding: 48,
+      labelWidthPx: 28,
+      containerPx: {width: 0, height: 0},
+    });
+    expect(Number.isFinite(f.width)).toBe(true);
+    expect(f.labelsHidden).toBe(false);
+    expect(f.width).toBeCloseTo(2 * (187 + 41), 6);
+  });
+});
+
+describe('computeRadialFrame — labelDropPx clip adjustment', () => {
+  const SECTOR_180 = {top: 0, bottom: 44, left: 0, right: 0};
+
+  it('leaves the requested clips untouched when the drop already fits', () => {
+    const plain = computeRadialFrame({
+      basePadding: 48,
+      labelWidthPx: 21,
+      clips: SECTOR_180,
+      containerPx: {width: 400, height: 224},
+    });
+    const withDrop = computeRadialFrame({
+      basePadding: 48,
+      labelWidthPx: 21,
+      clips: SECTOR_180,
+      labelDropPx: 21,
+      containerPx: {width: 400, height: 224},
+    });
+    expect(withDrop.viewBox).toBe(plain.viewBox);
+    expect(withDrop.clipsAdjusted).toBe(false);
+    expect(plain.clipsAdjusted).toBe(false);
+  });
+
+  it('lowers the bottom clip when a pinned face would cut the end labels', () => {
+    const plain = computeRadialFrame({
+      basePadding: 48,
+      labelWidthPx: 21,
+      clips: SECTOR_180,
+      faceDiameter: 180,
+    });
+    const f = computeRadialFrame({
+      basePadding: 48,
+      labelWidthPx: 21,
+      clips: SECTOR_180,
+      labelDropPx: 21,
+      faceDiameter: 180,
+    });
+    expect(f.clipsAdjusted).toBe(true);
+    expect(f.height).toBeGreaterThan(plain.height);
+    // The box bottom must sit at least labelDropPx/scale below the center.
+    const bottomExtentUnits = f.y + f.height;
+    expect(bottomExtentUnits).toBeGreaterThanOrEqual(21 / f.scale - 1e-6);
+    // The width (and thus the ring scale) is not affected.
+    expect(f.width).toBeCloseTo(plain.width, 6);
+    expect(f.scale).toBeCloseTo(plain.scale, 6);
+  });
+
+  it('adjusts symmetrically for a top clip (rudder-style windows)', () => {
+    const f = computeRadialFrame({
+      basePadding: 48,
+      labelWidthPx: 21,
+      clips: {top: 47, bottom: 0, left: 0, right: 0},
+      labelDropPx: 21,
+      faceDiameter: 180,
+    });
+    expect(f.clipsAdjusted).toBe(true);
+    // The box top must sit at least labelDropPx/scale above the center.
+    expect(-f.y).toBeGreaterThanOrEqual(21 / f.scale - 1e-6);
+  });
+
+  it('does nothing without clips or when labels are hidden', () => {
+    const noClips = computeRadialFrame({
+      basePadding: 48,
+      labelWidthPx: 21,
+      labelDropPx: 21,
+      containerPx: {width: 400, height: 400},
+    });
+    expect(noClips.clipsAdjusted).toBe(false);
+
+    const hidden = computeRadialFrame({
+      basePadding: 48,
+      labelWidthPx: 28,
+      clips: SECTOR_180,
+      labelDropPx: 21,
+      containerPx: {width: 100, height: 56},
+    });
+    expect(hidden.labelsHidden).toBe(true);
+    expect(hidden.clipsAdjusted).toBe(false);
+    expect(hidden.height).toBeCloseTo(hidden.width * 0.56, 6);
+  });
+});
+
+describe('computeRadialFrame — mode (b) faceDiameter', () => {
+  it('pins the scale and emits fixed host px', () => {
+    const f = computeRadialFrame({basePadding: 48, faceDiameter: 368});
+    expect(f.scale).toBe(1);
+    expect(f.hostWidthPx).toBeCloseTo(448);
+    expect(f.hostHeightPx).toBeCloseTo(448);
+  });
+
+  it('same faceDiameter, wider labels → same ring scale, wider box', () => {
+    const a = computeRadialFrame({
+      basePadding: 48,
+      faceDiameter: 200,
+      labelWidthPx: 14,
+    });
+    const b = computeRadialFrame({
+      basePadding: 48,
+      faceDiameter: 200,
+      labelWidthPx: 28,
+    });
+    expect(a.scale).toBeCloseTo(b.scale, 6);
+    expect(b.hostWidthPx!).toBeGreaterThan(a.hostWidthPx!);
+  });
+
+  it('treats zero/negative/non-finite faceDiameter as unset (no host pin)', () => {
+    for (const bad of [0, -100, NaN, Infinity]) {
+      const f = computeRadialFrame({
+        basePadding: 48,
+        faceDiameter: bad,
+        containerPx: {width: 300, height: 300},
+      });
+      expect(f.hostWidthPx).toBeUndefined();
+      expect(f.hostHeightPx).toBeUndefined();
+      expect(f.viewBox).toBe('-224 -224 448 448');
+    }
+  });
+
+  it('treats an unusable faceDiameter as unset on the zoom path too', () => {
+    const f = computeRadialFrame({
+      basePadding: 48,
+      faceDiameter: NaN,
+      zoomToFitArc: true,
+      areas: ZOOM_AREAS,
+      innerRadius: 112,
+      containerPx: {width: 300, height: 300},
+    });
+    expect(f.hostWidthPx).toBeUndefined();
+    expect(f.hostHeightPx).toBeUndefined();
+  });
+
+  it('faceDiameter + 180° clips yields a shorter host box at the same scale', () => {
+    const full = computeRadialFrame({basePadding: 48, faceDiameter: 200});
+    const half = computeRadialFrame({
+      basePadding: 48,
+      faceDiameter: 200,
+      clips: {top: 0, bottom: 44, left: 0, right: 0},
+    });
+    expect(half.scale).toBeCloseTo(full.scale, 6);
+    expect(half.hostWidthPx!).toBeCloseTo(full.hostWidthPx!, 6);
+    expect(half.hostHeightPx!).toBeCloseTo(full.hostHeightPx! * 0.56, 6);
+  });
+});
+
+describe('computeRadialFrame — zoom path', () => {
+  it('matches computeZoomToFitArcFrame exactly when no labels', () => {
+    const f = computeRadialFrame({
+      basePadding: 48,
+      zoomToFitArc: true,
+      areas: ZOOM_AREAS,
+      innerRadius: 112,
+    });
+    const direct = computeZoomToFitArcFrame({
+      areas: ZOOM_AREAS,
+      outerRadius: 184,
+      innerRadius: 112,
+      extension: 48,
+      targetSize: 448,
+    });
+    expect(f.viewBox).toBe(direct.viewBox);
+    expect(f.width).toBe(direct.width);
+    expect(f.height).toBe(direct.height);
+    expect(f.radiusOffset).toBe(direct.radiusOffset);
+    expect(f.labelReserve).toBe(0);
+  });
+
+  it('adds a label reserve via the extension in a small container', () => {
+    const plain = computeRadialFrame({
+      basePadding: 48,
+      zoomToFitArc: true,
+      areas: ZOOM_AREAS,
+      innerRadius: 112,
+    });
+    const labeled = computeRadialFrame({
+      basePadding: 48,
+      zoomToFitArc: true,
+      areas: ZOOM_AREAS,
+      innerRadius: 112,
+      labelWidthPx: 28,
+      containerPx: {width: 300, height: 300},
+    });
+    expect(labeled.labelsHidden).toBe(false);
+    expect(labeled.labelReserve).toBeGreaterThan(0);
+    expect(labeled.width).toBeGreaterThan(plain.width);
+  });
+});
+
+describe('estimateLabelWidthPx', () => {
+  it('is maxChars * 7', () => {
+    expect(estimateLabelWidthPx(['0', '3600', undefined])).toBe(28);
+    expect(estimateLabelWidthPx(['5'])).toBe(7);
+  });
+
+  it('is 0 for no texts', () => {
+    expect(estimateLabelWidthPx([undefined])).toBe(0);
+    expect(estimateLabelWidthPx([])).toBe(0);
+  });
+});