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

package/src/integration-systems/integration-button/integration-button.ts

@@ -35,36 +35,38 @@ export enum IntegrationButtonType {
  *
  * @fires click - Fired when the internal button is activated.
  *
- * @property {boolean} hasTrailingIcon - Shows the `trailing-icon` slot.
- * @property {boolean} hasTrailingIcon2 - Shows the `trailing-icon2` slot.
- * @property {boolean} hasLeadingIcon - Shows the `leading-icon` slot.
- * @property {boolean} hasstatus - Shows the `status` slot.
- * @property {IntegrationButtonReadout[]} readouts - List of readout items shown in the rich type.
- * @property {boolean} disabled - Disables the internal button.
- * @property {boolean} activated - Applies active state styling while a selection is pending.
- * @property {boolean} selected - Applies selected state styling.
- * @property {boolean} dividerBottom - Shows a bottom divider under the button.
- * @property {boolean} dividerRight - Shows a right divider to separate from adjacent buttons.
- * @property {IntegrationButtonVariant} variant - Visual variant (`normal` or `flat`).
- * @property {IntegrationButtonType} type - Layout type (`hug`, `regular`, or `rich`).
  * @experimental
  */
 @customElement('obc-integration-button')
 export class ObcIntegrationButton extends LitElement {
+  /** Shows the `trailing-icon` slot. */
   @property({type: Boolean}) hasTrailingIcon = false;
-  /** @availableWhen hasTrailingIcon==true */
+  /**
+   * Shows the `trailing-icon2` slot.
+   * @availableWhen hasTrailingIcon==true
+   */
   @property({type: Boolean}) hasTrailingIcon2 = false;
+  /** Shows the `leading-icon` slot. */
   @property({type: Boolean}) hasLeadingIcon = false;
+  /** Shows the `status` slot. */
   @property({type: Boolean}) hasStatus = false;
+  /** List of readout items shown in the rich type. */
   @property({type: Array, attribute: false})
   readouts: IntegrationButtonReadout[] = [];
+  /** Disables the internal button. */
   @property({type: Boolean}) disabled = false;
+  /** Applies active state styling while a selection is pending. */
   @property({type: Boolean}) activated = false;
+  /** Applies selected state styling. */
   @property({type: Boolean}) selected = false;
+  /** Shows a bottom divider under the button. */
   @property({type: Boolean}) dividerBottom = false;
+  /** Shows a right divider to separate from adjacent buttons. */
   @property({type: Boolean}) dividerRight = false;
+  /** Visual variant (`normal` or `flat`). */
   @property({type: String}) variant: IntegrationButtonVariant =
     IntegrationButtonVariant.normal;
+  /** Layout type (`hug`, `regular`, or `rich`). */
   @property({type: String}) type: IntegrationButtonType =
     IntegrationButtonType.regular;
 

package/src/navigation-instruments/azimuth-thruster/azimuth-thruster.stories.ts

@@ -2,7 +2,13 @@ import type {Meta, StoryObj} from '@storybook/web-components-vite';
 import {ObcAzimuthThruster} from './azimuth-thruster.js';
 import './azimuth-thruster.js';
 import {InstrumentState, Priority, Size} from '../types.js';
-import {widthDecorator} from '../../storybook-util.js';
+import {html} from 'lit';
+import {
+  playgroundColumn,
+  resizableStoryBox,
+  storyHint,
+  widthDecorator,
+} from '../../storybook-util.js';
 import {AdviceType} from '../watch/advice.js';
 import {TickmarkStyle} from '../watch/tickmark.js';
 import {PropellerType} from '../thruster/propeller.js';
@@ -12,6 +18,11 @@ const meta: Meta<typeof ObcAzimuthThruster> = {
   tags: ['autodocs', '6.0'],
   component: 'obc-azimuth-thruster',
   argTypes: {
+    faceDiameter: {
+      control: {type: 'range', min: 100, max: 600, step: 10},
+      description:
+        'Pins the outer-ring diameter in px (fixed intrinsic size, equal circumference across instruments). Clear to return to fill-the-container sizing.',
+    },
     thrust: {control: {type: 'range', min: -100, max: 100, step: 1}},
     thrustSetpoint: {control: {type: 'range', min: -100, max: 100, step: 1}},
     angle: {control: {type: 'range', min: -180, max: 180, step: 1}},
@@ -256,3 +267,69 @@ export const OffWithAngleSetpointOverride: Story = {
     priority: Priority.enhanced,
   },
 };
+
+type SizingPlaygroundArgs = Partial<ObcAzimuthThruster> & {
+  lockFaceDiameter?: boolean;
+};
+
+/**
+ * Interactive sizing playground: drag the dashed box's bottom-right corner to
+ * resize it. The first thruster is pinned to a fixed intrinsic size by the
+ * `faceDiameter` control, while the second adapts to the remaining flex
+ * space, reserving room for its degree labels adaptively (issue #1021).
+ * Enable `lockFaceDiameter` to pin both to the same circumference. Related:
+ * *Sizing Playground* stories under Building Blocks/Watch, Building
+ * Blocks/Instrument Radial and Instruments/Gauge Radial.
+ */
+export const SizingPlayground: StoryObj<SizingPlaygroundArgs> = {
+  name: 'Sizing Playground — FaceDiameter + Resizable (Manual)',
+  tags: ['skip-test'],
+  parameters: {widthDecorator: false},
+  args: {
+    faceDiameter: 240,
+    lockFaceDiameter: false,
+  },
+  argTypes: {
+    lockFaceDiameter: {
+      control: 'boolean',
+      description:
+        'Apply faceDiameter to every instance (equal circumference) instead of only the first.',
+    },
+  },
+  render: (args) => {
+    const instances = [
+      {label: 'thruster A', angle: 45, thrust: 60},
+      {label: 'thruster B', angle: -120, thrust: 35},
+    ];
+    const fd = (index: number) =>
+      index === 0 || args.lockFaceDiameter ? args.faceDiameter : undefined;
+    const caption = (index: number, label: string) =>
+      fd(index) !== undefined
+        ? `${label} — pinned ${fd(index)}px`
+        : `${label} — adaptive (flex)`;
+    return html`
+      ${storyHint(
+        'Drag the bottom-right corner of the dashed box to resize it. The first thruster is pinned by the faceDiameter control; the second adapts to the remaining flex space. Enable lockFaceDiameter to pin both to the same circumference.'
+      )}
+      ${resizableStoryBox(
+        html`
+          ${instances.map((g, index) =>
+            playgroundColumn(
+              caption(index, g.label),
+              html`
+                <obc-azimuth-thruster
+                  .angle=${g.angle}
+                  .thrust=${g.thrust}
+                  .showLabels=${true}
+                  .faceDiameter=${fd(index)}
+                ></obc-azimuth-thruster>
+              `,
+              {pinned: fd(index) !== undefined}
+            )
+          )}
+        `,
+        {width: 680, height: 400}
+      )}
+    `;
+  },
+};

package/src/navigation-instruments/azimuth-thruster/azimuth-thruster.ts

@@ -1,12 +1,20 @@
 import {html, LitElement, unsafeCSS} from 'lit';
 import {property} from 'lit/decorators.js';
 import type {PropertyValues} from 'lit';
+import {ResizeController} from '@lit-labs/observers/resize-controller.js';
+import {
+  applyPinnedHostSize,
+  computeRadialFrame,
+  estimateLabelWidthPx,
+  measureContainerPx,
+  observeInnerBox,
+  type RadialFrame,
+} from '../../svghelpers/radial-frame.js';
 import {InstrumentState, Priority} from '../types.js';
 import {SetpointBundle} from '../../svghelpers/setpoint-bundle.js';
 import {thruster} from '../thruster/thruster.js';
 import '../watch/watch.js';
 import componentStyle from './azimuth-thruster.css?inline';
-import {ifDefined} from 'lit/directives/if-defined.js';
 import {AdviceState, AngleAdvice, AngleAdviceRaw} from '../watch/advice.js';
 import {Tickmark, TickmarkStyle, TickmarkType} from '../watch/tickmark.js';
 import {LinearAdvice} from '../thruster/advice.js';
@@ -134,6 +142,36 @@ export class ObcAzimuthThruster extends LitElement {
   @property({type: String}) tickmarkStyle: TickmarkStyle =
     TickmarkStyle.regular;
   @property({type: Boolean}) starboardPortIndicator: boolean = false;
+  /**
+   * 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;
+
+  private _frame: RadialFrame | undefined;
+
+  /** Whether the host size styles were set by applyPinnedHostSize. */
+  private _hostSizePinned = false;
+
+  private _resizeController = new ResizeController(this, {});
+
+  override firstUpdated(changed: PropertyValues): void {
+    super.firstUpdated(changed);
+    observeInnerBox(this._resizeController, this.renderRoot);
+  }
+
+  override updated(changed: PropertyValues): void {
+    super.updated(changed);
+    this._hostSizePinned = applyPinnedHostSize(
+      this,
+      this._frame,
+      this._hostSizePinned
+    );
+  }
 
   private get angleAdviceRaw(): AngleAdviceRaw[] {
     return this.angleAdvices.map((advice) => {
@@ -236,20 +274,27 @@ export class ObcAzimuthThruster extends LitElement {
 
     const tickmarks = this.getTickmarks();
 
-    let viewBox: string;
-    if (!this.hasLabelSpacer) {
-      viewBox = '-192 -192 384 384';
-    } else if (this.showLabels && !this.tickmarksInside) {
-      viewBox = '-236 -236 472 472';
-    } else {
-      viewBox = '-200 -200 400 400';
-    }
+    const frame = computeRadialFrame({
+      basePadding: this.hasLabelSpacer ? 24 : 16,
+      labelWidthPx:
+        this.hasLabelSpacer && !this.tickmarksInside
+          ? estimateLabelWidthPx(tickmarks.map((t) => t.text))
+          : 0,
+      containerPx: measureContainerPx(this),
+      faceDiameter: this.faceDiameter,
+    });
+    this._frame = frame;
+    const shownTickmarks = frame.labelsHidden
+      ? tickmarks.map((t) => ({...t, text: undefined}))
+      : tickmarks;
+    const viewBox = frame.viewBox;
 
     return html`
       <div class="container">
         <obc-watch
           .touching=${this.touching}
-          .tickmarks=${tickmarks}
+          .arcFrame=${frame}
+          .tickmarks=${shownTickmarks}
           .state=${this.state}
           .priority=${this.priority}
           .angleSetpoint=${this.angleSetpoint}
@@ -260,7 +305,6 @@ export class ObcAzimuthThruster extends LitElement {
           .animateSetpoint=${this.animateSetpoint}
           .tickmarksInside=${this.tickmarksInside}
           .tickmarkStyle=${this.tickmarkStyle}
-          padding=${ifDefined(!this.hasLabelSpacer ? 16 : undefined)}
           .advices=${this.angleAdviceRaw}
           .starboardPortIndicator=${this.starboardPortIndicator}
         ></obc-watch>

package/src/navigation-instruments/compass/compass.stories.ts

@@ -6,7 +6,13 @@ import {
   RotType,
 } from './compass.js';
 import './compass.js';
-import {widthDecorator} from '../../storybook-util.js';
+import {html} from 'lit';
+import {
+  playgroundColumn,
+  resizableStoryBox,
+  storyHint,
+  widthDecorator,
+} from '../../storybook-util.js';
 import {AdviceType} from '../watch/advice.js';
 import {VesselImage} from '../watch/watch.js';
 import {topVessels} from '../watch/vessels/storybook-helper.js';
@@ -48,6 +54,11 @@ const meta: Meta<typeof ObcCompass> = {
   },
   argTypes: {
     width: {control: {type: 'range', min: 32, max: 1028, step: 1}},
+    faceDiameter: {
+      control: {type: 'range', min: 100, max: 600, step: 10},
+      description:
+        'Pins the outer-ring diameter in px (fixed intrinsic size, equal circumference across instruments). Clear to return to fill-the-container sizing.',
+    },
     heading: {control: {type: 'range', min: 0, max: 360, step: 1}},
     courseOverGround: {control: {type: 'range', min: 0, max: 360, step: 1}},
     headingSetpoint: {control: {type: 'range', min: 0, max: 360, step: 1}},
@@ -171,3 +182,79 @@ export const WithRateOfTurnDegreesPerMinute: Story = {
     priorityElements: [CompassPriorityElement.hdg, CompassPriorityElement.rot],
   },
 };
+
+export const SmallContainer: Story = {
+  name: 'Small Container (250px, Labels + Decor Reserve)',
+  args: {
+    width: 250,
+  },
+};
+
+type SizingPlaygroundArgs = Partial<ObcCompass> & {
+  lockFaceDiameter?: boolean;
+};
+
+/**
+ * Interactive sizing playground: drag the dashed box's bottom-right corner to
+ * resize it. The first compass is pinned to a fixed intrinsic size by the
+ * `faceDiameter` control, while the second adapts to the remaining flex
+ * space, reserving room for the NSWE labels, north arrow and wind symbols
+ * adaptively (issue #1021). Enable `lockFaceDiameter` to pin both to the same
+ * circumference. Related: *Sizing Playground* stories under Building
+ * Blocks/Watch, Building Blocks/Instrument Radial and Instruments/Gauge
+ * Radial.
+ */
+export const SizingPlayground: StoryObj<SizingPlaygroundArgs> = {
+  name: 'Sizing Playground — FaceDiameter + Resizable (Manual)',
+  tags: ['skip-test'],
+  parameters: {widthDecorator: false},
+  args: {
+    faceDiameter: 240,
+    lockFaceDiameter: false,
+  },
+  argTypes: {
+    lockFaceDiameter: {
+      control: 'boolean',
+      description:
+        'Apply faceDiameter to every instance (equal circumference) instead of only the first.',
+    },
+  },
+  render: (args) => {
+    const instances = [
+      {label: 'compass A', heading: 311},
+      {label: 'compass B', heading: 45},
+    ];
+    const fd = (index: number) =>
+      index === 0 || args.lockFaceDiameter ? args.faceDiameter : undefined;
+    const caption = (index: number, label: string) =>
+      fd(index) !== undefined
+        ? `${label} — pinned ${fd(index)}px`
+        : `${label} — adaptive (flex)`;
+    return html`
+      ${storyHint(
+        'Drag the bottom-right corner of the dashed box to resize it. The first compass is pinned by the faceDiameter control; the second adapts to the remaining flex space. Enable lockFaceDiameter to pin both to the same circumference.'
+      )}
+      ${resizableStoryBox(
+        html`
+          ${instances.map((g, index) =>
+            playgroundColumn(
+              caption(index, g.label),
+              html`
+                <obc-compass
+                  .heading=${g.heading}
+                  .courseOverGround=${g.heading + 27}
+                  .currentWindSpeedKnots=${20}
+                  .windFromDirection=${45}
+                  .showLabels=${true}
+                  .faceDiameter=${fd(index)}
+                ></obc-compass>
+              `,
+              {pinned: fd(index) !== undefined}
+            )
+          )}
+        `,
+        {width: 680, height: 400}
+      )}
+    `;
+  },
+};

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

@@ -5,6 +5,14 @@ import {Tickmark, TickmarkType} from '../watch/tickmark.js';
 import {arrow, ArrowStyle} from './arrow.js';
 import {AdviceState, AngleAdvice, AngleAdviceRaw} from '../watch/advice.js';
 import {ResizeController} from '@lit-labs/observers/resize-controller.js';
+import {
+  applyPinnedHostSize,
+  computeRadialFrame,
+  measureContainerPx,
+  NORTH_ARROW_WIDTH_PX,
+  NSWE_LABEL_WIDTH_PX,
+  type RadialFrame,
+} from '../../svghelpers/radial-frame.js';
 import {
   VesselImage,
   VesselImageSize,
@@ -59,9 +67,9 @@ export enum CompassPriorityElement {
  *   Supports spinning dots (`rotType="dots"`) — the dot animation is
  *   amplified by `rotDotAnimationFactor` so small physical values still
  *   read at a glance — and a banana-shaped arc bar (`rotType="bar"`)
- *   showing the HDG→COG span. Bar extent is driven by the physical value
- *   only (gain is not applied). Position on the outer scale ring or inner
- *   circle via `rotPosition`.
+ *   showing the rate of turn as an arc anchored at the current heading.
+ *   Bar extent is driven by the physical value only (gain is not applied).
+ *   Position on the outer scale ring or inner circle via `rotPosition`.
  * - **Environmental overlays**: Wind speed/direction and current
  *   speed/direction indicators on the watch face.
  * - **Vessel image**: Configurable vessel silhouette centered on the
@@ -94,25 +102,6 @@ export enum CompassPriorityElement {
  * ></obc-compass>
  * ```
  *
- * @property {number} heading - The current heading of the vessel in degrees.
- * @property {number} courseOverGround - The current course over ground in degrees.
- * @property {number | null} headingSetpoint - The set point for the heading in degrees.
- * @property {boolean} atHeadingSetpoint - Indicates if the vessel is at the heading set point.
- * @property {boolean} autoAtHeadingSetpoint - Enables automatic at heading set point calculation.
- * @property {number} autoAtHeadingSetpointDeadband - The deadband for the heading set point in degrees.
- * @property {boolean} touching - Indicates if the compass is being touched.
- * @property {Array<AngleAdvice>} headingAdvices - An array of angle advices for the compass.
- * @property {number | null} currentWindSpeedKnots - The wind speed in knots.
- * @property {number | null} windFromDirection - The direction the wind is coming from in degrees.
- * @property {number | null} currentSpeed - The current speed, number of arrows.
- * @property {number | null} currentFromDirection - The direction the current is coming from in degrees.
- * @property {VesselImage} vesselImage - The image of the vessel.
- * @property {number|undefined} rateOfTurnDegreesPerMinute - Measured rate of turn in degrees per minute (the AIS / ITU-R M.1371 convention). Sign controls direction (positive = starboard / clockwise). Drives both the bar extent and the dot animation.
- * @property {number} rotDotAnimationFactor - Visual amplification for the dot animation only. Default `18` (≈1 rpm at 20°/min).
- * @property {number} rotationsPerMinute - **Deprecated.** Use `rateOfTurnDegreesPerMinute` instead. Kept as a backward-compatible fallback when `rateOfTurnDegreesPerMinute` is `undefined`.
- * @property {RotType} rotType - ROT display mode: `'dots'` (spinning dots, default) or `'bar'` (arc bar from HDG to COG).
- * @property {RotPosition} rotPosition - ROT track position: `'innerCircle'` (default) or `'scale'` (on the outer ring).
- * @property {Priority} priority - Color priority: `Priority.enhanced` uses the blue/enhanced color palette, `Priority.regular` (default) uses the standard palette.
  *
  * @ignition-base-height: 512px
  * @ignition-base-width: 512px
@@ -120,36 +109,65 @@ export enum CompassPriorityElement {
  */
 @customElement('obc-compass')
 export class ObcCompass extends LitElement {
+  /** The current heading of the vessel in degrees. */
   @property({type: Number}) heading = 0;
+  /** The current course over ground in degrees. */
   @property({type: Number}) courseOverGround = 0;
 
+  /** The set point for the heading in degrees. */
   @property({type: Number}) headingSetpoint: number | null = null;
   /** @availableWhen headingSetpoint!=null */
   @property({type: Number}) newHeadingSetpoint: number | undefined;
-  /** @availableWhen headingSetpoint!=null && autoAtHeadingSetpoint==false */
+  /**
+   * Indicates if the vessel is at the heading set point.
+   * @availableWhen headingSetpoint!=null && autoAtHeadingSetpoint==false
+   */
   @property({type: Boolean}) atHeadingSetpoint: boolean = false;
   /** @availableWhen headingSetpoint!=null */
   @property({type: Number}) headingSetpointAtZeroDeadband: number = 0.5;
   /** @availableWhen headingSetpoint!=null */
   @property({type: Boolean}) headingSetpointOverride: boolean = false;
-  /** @availableWhen headingSetpoint!=null */
+  /**
+   * Enables automatic at heading set point calculation.
+   * @availableWhen headingSetpoint!=null
+   */
   @property({type: Boolean, attribute: false}) autoAtHeadingSetpoint: boolean =
     true;
-  /** @availableWhen headingSetpoint!=null && autoAtHeadingSetpoint==true */
+  /**
+   * The deadband for the heading set point in degrees.
+   * @availableWhen headingSetpoint!=null && autoAtHeadingSetpoint==true
+   */
   @property({type: Number}) autoAtHeadingSetpointDeadband: number = 2;
   /** @availableWhen headingSetpoint!=null */
   @property({type: Boolean}) animateSetpoint: boolean = false;
-  /** @availableWhen headingSetpoint!=null */
+  /**
+   * Indicates if the compass is being touched.
+   * @availableWhen headingSetpoint!=null
+   */
   @property({type: Boolean}) touching: boolean = false;
+  /** An array of angle advices for the compass. */
   @property({type: Array, attribute: false}) headingAdvices: AngleAdvice[] = [];
-  /** @availableWhen windFromDirection!=null */
+  /**
+   * The wind speed in knots.
+   * @availableWhen windFromDirection!=null
+   */
   @property({type: Number}) currentWindSpeedKnots: number | null = null;
-  /** @availableWhen currentWindSpeedKnots!=null */
+  /**
+   * The direction the wind is coming from in degrees.
+   * @availableWhen currentWindSpeedKnots!=null
+   */
   @property({type: Number}) windFromDirection: number | null = null;
-  /** @availableWhen currentFromDirection!=null */
+  /**
+   * The current speed, number of arrows.
+   * @availableWhen currentFromDirection!=null
+   */
   @property({type: Number}) currentSpeed: number | null = null;
-  /** @availableWhen currentSpeed!=null */
+  /**
+   * The direction the current is coming from in degrees.
+   * @availableWhen currentSpeed!=null
+   */
   @property({type: Number}) currentFromDirection: number | null = null;
+  /** The image of the vessel. */
   @property({type: String}) vesselImage: VesselImage = VesselImage.genericTop;
   /**
    * Measured rate of turn in degrees per minute (positive = starboard).
@@ -166,12 +184,18 @@ export class ObcCompass extends LitElement {
    */
   @property({type: Number}) rotDotAnimationFactor: number = 18;
   /**
+   * Legacy rate-of-turn input, in rotations per minute. When
+   * `rateOfTurnDegreesPerMinute` is `undefined`, this value is used
+   * (unconverted) as the fallback ROT, driving both the spinning dot ring
+   * and the bar extent.
    * @deprecated Use `rateOfTurnDegreesPerMinute` (and optionally
    * `rotDotAnimationFactor`) instead. Takes effect only when
    * `rateOfTurnDegreesPerMinute` is `undefined`.
    */
   @property({type: Number}) rotationsPerMinute: number = 1;
+  /** ROT display mode: `'dots'` (spinning dots, default) or `'bar'` (a rate-of-turn arc anchored at the current heading, its length proportional to the rate of turn). */
   @property({type: String}) rotType: RotType = RotType.dots;
+  /** ROT track position: `'innerCircle'` (default) or `'scale'` (on the outer ring). */
   @property({type: String}) rotPosition: RotPosition = RotPosition.innerCircle;
   /**
    * Bar-extent reference value in **degrees per minute**. The bar fills the
@@ -192,6 +216,7 @@ export class ObcCompass extends LitElement {
   @property({type: String}) direction: CompassDirection =
     CompassDirection.NorthUp;
   @property({type: String}) state: InstrumentState = InstrumentState.active;
+  /** Color priority: `Priority.enhanced` uses the blue/enhanced color palette, `Priority.regular` (default) uses the standard palette. */
   @property({type: String}) priority: Priority = Priority.regular;
   /** @availableWhen priority==enhanced */
   @property({type: Array, attribute: false})
@@ -200,6 +225,15 @@ export class ObcCompass extends LitElement {
   @property({type: Boolean}) showLabels: boolean = false;
   /** When true, labels and north arrow are placed inside the outer ring. */
   @property({type: Boolean}) tickmarksInside: boolean = false;
+  /**
+   * 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;
 
   private _headingSp = new SetpointBundle({
     angularWraparound: true,
@@ -240,18 +274,32 @@ export class ObcCompass extends LitElement {
     return this.rateOfTurnDegreesPerMinute ?? this.rotationsPerMinute;
   }
 
-  private getPadding() {
-    const size = Math.min(this.clientHeight, this.clientWidth);
-    const deltaWidth = 512 - size;
-    const steps = deltaWidth / 128;
-    let deltaPadding;
-    if (deltaWidth > 0) {
-      deltaPadding = steps * 48;
-    } else {
-      deltaPadding = steps * 6;
+  /**
+   * Pixel cost of the outside decor: the always-rendered north-arrow glyph
+   * plus, only while shown, the NSWE labels (both keep a constant on-screen
+   * size via `1/scale` terms). Feeds the frame's width-aware reserve,
+   * replacing the former empirical `72 + delta(clientSize)` padding.
+   * Wind/current symbols at their default radius are covered by the base
+   * padding of 72.
+   */
+  private getOutsideDecorPx(): number {
+    if (this.tickmarksInside) {
+      return 0;
     }
+    return NORTH_ARROW_WIDTH_PX + (this.showLabels ? NSWE_LABEL_WIDTH_PX : 0);
+  }
+
+  /** Whether the host size styles were set by applyPinnedHostSize. */
+  private _hostSizePinned = false;
+  private _frame: RadialFrame | undefined;
 
-    return 72 + deltaPadding;
+  override updated(changed: PropertyValues): void {
+    super.updated(changed);
+    this._hostSizePinned = applyPinnedHostSize(
+      this,
+      this._frame,
+      this._hostSizePinned
+    );
   }
 
   private get angleAdviceRaw(): AngleAdviceRaw[] {
@@ -298,23 +346,28 @@ export class ObcCompass extends LitElement {
       {angle: 270, type: TickmarkType.main},
     ];
 
-    const padding = this.getPadding();
-    const width = (176 + padding) * 2;
-    const viewBox = `-${width / 2} -${width / 2} ${width} ${width}`;
+    const frame = computeRadialFrame({
+      basePadding: 72,
+      labelWidthPx: this.getOutsideDecorPx(),
+      containerPx: measureContainerPx(this),
+      faceDiameter: this.faceDiameter,
+    });
+    this._frame = frame;
+    const viewBox = frame.viewBox;
 
     return html`
       <div class="container">
         <obc-watch
           .touching=${this.touching}
-          .padding=${padding}
+          .arcFrame=${frame}
           .advices=${this.angleAdviceRaw}
           .tickmarks=${tickmarks}
           .state=${this.state}
           .watchCircleType=${WatchCircleType.triple}
-          .showLabels=${this.showLabels}
+          .showLabels=${this.showLabels && !frame.labelsHidden}
           .tickmarksInside=${this.tickmarksInside}
           .crosshairEnabled=${true}
-          .northArrow=${true}
+          .northArrow=${!frame.labelsHidden}
           .angleSetpoint=${this.headingSetpoint ?? undefined}
           .newAngleSetpoint=${this.newHeadingSetpoint}
           .atAngleSetpoint=${this._headingSp.computeAtSetpoint(this.heading)}

package/src/navigation-instruments/compass-flat/compass-flat.ts

@@ -58,14 +58,6 @@ export interface Label {
  * - **Color priority**: Per-element priority for HDG, COG, and ROT via
  *   `priorityElements`.
  *
- * @property {number} heading - Current heading in degrees.
- * @property {number} courseOverGround - Current COG in degrees.
- * @property {RotType|undefined} rotType - ROT display mode: `'dots'`, `'bar'`, or `undefined` (hidden).
- * @property {number|undefined} rateOfTurnDegreesPerMinute - Measured rate of turn in degrees per minute (positive = starboard). Drives the bar extent and (after `× rotDotAnimationFactor`) the dot animation.
- * @property {number} rotDotAnimationFactor - Visual amplification for the dot animation only. Default `18` (≈1 rpm at 20°/min).
- * @property {number} rotationsPerMinute - **Deprecated.** Use `rateOfTurnDegreesPerMinute` instead.
- * @property {number} rotMaxValue - Bar-extent reference value in **degrees per minute**. Default `60` per ES-TRIN 2025/1 Art. 3.02.
- * @property {number} rotArcExtent - Degrees of bar arc per max-value ROT (default 60).
  *
  * @ignition-base-height: 170px
  * @ignition-base-width: 512px
@@ -74,7 +66,9 @@ export interface Label {
 @customElement('obc-compass-flat')
 export class ObcCompassFlat extends LitElement {
   @property({type: Boolean}) FOVIndicator: boolean = false;
+  /** Current heading in degrees. */
   @property({type: Number}) heading = 0;
+  /** Current COG in degrees. */
   @property({type: Number}) courseOverGround = 0;
   @property({type: Number}) tickInterval = 5;
   @property({type: Number}) FOV = 45;
@@ -85,6 +79,7 @@ export class ObcCompassFlat extends LitElement {
   priorityElements: CompassFlatPriorityElement[] = [
     CompassFlatPriorityElement.hdg,
   ];
+  /** ROT display mode: `'dots'`, `'bar'`, or `undefined` (hidden). */
   @property({type: String}) rotType: RotType | undefined;
   /**
    * Measured rate of turn in degrees per minute (positive = starboard).
@@ -98,6 +93,7 @@ export class ObcCompassFlat extends LitElement {
    */
   @property({type: Number}) rotDotAnimationFactor: number = 18;
   /**
+   * **Deprecated.** Use `rateOfTurnDegreesPerMinute` instead.
    * @deprecated Use `rateOfTurnDegreesPerMinute` instead.
    * @availableWhen rotType!=undefined
    */
@@ -108,7 +104,10 @@ export class ObcCompassFlat extends LitElement {
    * @availableWhen rotType!=undefined
    */
   @property({type: Number}) rotMaxValue: number = 60;
-  /** @availableWhen rotType!=undefined */
+  /**
+   * Degrees of bar arc per max-value ROT (default 60).
+   * @availableWhen rotType!=undefined
+   */
   @property({type: Number}) rotArcExtent: number = 60;
   /** @availableWhen rotType!=undefined */
   @property({type: Boolean}) rotPortStarboard: boolean = false;

package/src/navigation-instruments/compass-sector/compass-sector.ts

@@ -31,6 +31,13 @@ export enum CompassSectorPriorityElement {
   rot = 'rot',
 }
 
+// Fixed frame padding for both the zoomed and un-zoomed paths. This component
+// deliberately keeps its bespoke FOV-compression geometry and does NOT use
+// svghelpers/radial-frame.ts: the viewBox is cached per FOV (a
+// container-size-dependent label reserve would invalidate that), and the
+// 72-unit padding covers the 3-char degree labels at typical sizes.
+// TODO(#1021): adopt computeRadialFrame if degree labels ever clip when the
+// component is shrunk far below its design size.
 const PADDING = 72;
 const WATCH_TYPE = WatchCircleType.triple;
 const INNER_RADIUS = innerRingRadiusFor(WATCH_TYPE);