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

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

@@ -6,7 +6,12 @@ import {
   WatchCircleType,
 } from './watch.js';
 import './watch.js';
-import {widthDecorator} from '../../storybook-util.js';
+import {
+  playgroundColumn,
+  resizableStoryBox,
+  storyHint,
+  widthDecorator,
+} from '../../storybook-util.js';
 import {AdviceState, AdviceType} from './advice.js';
 import {InstrumentState, Priority} from '../types.js';
 import {TickmarkType} from './tickmark.js';
@@ -70,6 +75,11 @@ Source of truth: \`packages/openbridge-webcomponents/src/navigation-instruments/
     },
     areas: {control: {type: 'object'}},
     padding: {control: {type: 'range', min: 0, max: 100, 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.',
+    },
     vessels: {control: {type: 'object'}},
     windKnots: {control: {type: 'range', min: 0, max: 100, step: 1}},
     windFromDirectionDeg: {control: {type: 'range', min: 0, max: 360, step: 1}},
@@ -729,6 +739,135 @@ export const TickmarksTestInsideRotation: Story = {
   },
 };
 
+/**
+ * Regression test for label counter-scaling after a container resize: the
+ * wrapper starts at 400px and `play` shrinks it to 240px BEFORE the snapshot.
+ * The standalone watch host renders inline (no box), so its ResizeObserver
+ * only fires via the internal `<svg>` (`observeInnerBox`) — if that
+ * observation is lost, `--scale` stays at the 400px value and the labels
+ * shrink with the box (~7px on screen) instead of holding ~12px.
+ */
+export const CounterScaleAfterResize: Story = {
+  args: {
+    tickmarks: [
+      ...Array.from({length: 24}, (_, i) => ({
+        angle: i * 15,
+        type: TickmarkType.secondary,
+        text: `${i * 15}`,
+      })),
+    ],
+  },
+  parameters: {widthDecorator: false},
+  render: (args) => html`
+    <div id="counter-scale-wrap" style="width: 400px; height: 400px;">
+      <obc-watch .tickmarks=${args.tickmarks}></obc-watch>
+    </div>
+  `,
+  play: async ({canvasElement}) => {
+    const wrap = canvasElement.querySelector(
+      '#counter-scale-wrap'
+    ) as HTMLElement;
+    wrap.style.width = '240px';
+    wrap.style.height = '240px';
+    await new Promise((resolve) =>
+      requestAnimationFrame(() => requestAnimationFrame(resolve))
+    );
+    await wrap.querySelector('obc-watch')?.updateComplete;
+  },
+};
+
+type SizingPlaygroundArgs = Partial<ObcWatch> & {
+  lockFaceDiameter?: boolean;
+};
+
+/**
+ * Interactive sizing playground for the core renderer: drag the dashed box's
+ * bottom-right corner to resize it. The first watch (2-digit tick labels) is
+ * pinned to a fixed intrinsic size by the `faceDiameter` control, while the
+ * 4-digit watch and the 180° arc adapt to the remaining flex space, reserving
+ * label room adaptively (and hiding labels past the reserve cap in
+ * `svghelpers/radial-frame.ts`, issue #1021). Enable `lockFaceDiameter` to
+ * pin all three to the same circumference. Related: *Sizing Playground*
+ * stories under 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: 200,
+    lockFaceDiameter: false,
+  },
+  argTypes: {
+    lockFaceDiameter: {
+      control: 'boolean',
+      description:
+        'Apply faceDiameter to every instance (equal circumference) instead of only the first.',
+    },
+  },
+  render: (args) => {
+    const fullCircleTicks = (factor: number) =>
+      Array.from({length: 12}, (_, i) => ({
+        angle: i * 30,
+        type: TickmarkType.secondary,
+        text: `${i * 30 * factor}`,
+      }));
+    const instances = [
+      {label: '2-digit ticks', ticks: fullCircleTicks(1), areas: undefined},
+      {label: '4-digit ticks', ticks: fullCircleTicks(10), areas: undefined},
+      {
+        label: '180° arc',
+        ticks: Array.from({length: 7}, (_, i) => ({
+          angle: i * 30 - 90,
+          type: TickmarkType.secondary,
+          text: `${i * 30}`,
+        })),
+        areas: [
+          {
+            startAngle: -90,
+            endAngle: 90,
+            roundInsideCut: true,
+            roundOutsideCut: true,
+          },
+        ],
+      },
+    ];
+    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 watch is pinned by the faceDiameter control; the 4-digit watch and the 180° arc adapt to the remaining flex space. Enable lockFaceDiameter to pin all three to the same circumference.'
+      )}
+      ${resizableStoryBox(
+        html`
+          ${instances.map((g, index) =>
+            playgroundColumn(
+              caption(index, g.label),
+              html`
+                <obc-watch
+                  .faceDiameter=${fd(index)}
+                  .tickmarks=${g.ticks}
+                  .areas=${g.areas ?? []}
+                  .watchCircleType=${g.areas
+                    ? WatchCircleType.double
+                    : WatchCircleType.single}
+                ></obc-watch>
+              `,
+              {pinned: fd(index) !== undefined}
+            )
+          )}
+        `,
+        {width: 760, height: 320}
+      )}
+    `;
+  },
+};
+
 /**
  * Side-by-side comparison of setpoint visual states for radial instruments.
  *

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 {
@@ -161,22 +167,6 @@ const RADIAL_SETPOINT_INWARD_ADJUST = 4;
  * `_setpointCssAngle` tracks the accumulated CSS angle to avoid long-way-around
  * transitions across the 0°/360° boundary.
  *
- * @property {InstrumentState} state - Instrument state (active, loading, off)
- * @property {Priority} priority - Color priority (enhanced = blue palette, regular = gray palette)
- * @property {number|undefined} angleSetpoint - Setpoint angle in degrees (0° = 12 o'clock)
- * @property {number|undefined} newAngleSetpoint - New setpoint being adjusted (focus mode)
- * @property {boolean} atAngleSetpoint - Whether value matches setpoint (within deadband)
- * @property {number} angleSetpointAtZeroDeadband - Deadband for zero detection (default 0.5°)
- * @property {boolean} setpointOverride - Override to derive setpoint color from priority regardless of state
- * @property {RotType|undefined} rotType - ROT visualization type: `'dots'` (spinning dots) or `'bar'` (arc bar with clipped dots). Undefined hides the ROT layer.
- * @property {RotPosition} rotPosition - Track on which ROT elements are placed: `'scale'` (on the outer ring) or `'innerCircle'` (default, inside the inner ring)
- * @property {number} rotStartAngle - Start angle of the ROT bar arc in degrees (0° = 12 o'clock, clockwise). Only used when `rotType` is `'bar'`.
- * @property {number} rotEndAngle - End angle of the ROT bar arc in degrees. The bar is hidden when the difference from `rotStartAngle` is less than 0.1°.
- * @property {Priority|undefined} rotPriority - Override priority for ROT color derivation. When set, ROT colors use this instead of the main `priority`. Useful when the ROT element has independent priority (e.g. compass per-element priority).
- * @property {number|undefined} rateOfTurnDegreesPerMinute - Measured rate of turn in degrees per minute (the maritime/AIS convention, see ES-TRIN 2025/1 Art. 3.02 and ITU-R M.1371). Sign controls direction (positive = starboard/clockwise). When defined, this drives both the dot animation (multiplied by `rotDotAnimationFactor`) and the port/starboard direction sign.
- * @property {number} rotDotAnimationFactor - Visual amplification factor applied only to the spinning-dot animation (not to bar extent). Default `18` keeps the legacy visual feel (≈1 rpm at 20°/min).
- * @property {number} rotationsPerMinute - **Deprecated.** Spin speed of the ROT dot ring in rotations per minute. Sign controls direction (positive = clockwise). Use `rateOfTurnDegreesPerMinute` instead.
- * @property {ZoomToFitArcFrame|undefined} arcFrame - Pre-computed zoom-to-fit arc frame. When set, the watch skips its own `computeZoomToFitArcFrame()` call and uses these values directly. Consumer instruments (e.g. rudder, instrument-radial) should compute the frame once and pass it here to avoid redundant computation. If you pass `arcFrame`, you own keeping it in sync with `areas` / `watchCircleType` — obc-watch will NOT recompute it, so a stale frame renders stale geometry.
  * @experimental
  */
 @customElement('obc-watch')
@@ -184,16 +174,23 @@ export class ObcWatch extends LitElement {
   private _setpointId = `watch-setpoint-${Math.random().toString(36).slice(2, 9)}`;
   private _newSetpointId = `watch-new-setpoint-${Math.random().toString(36).slice(2, 9)}`;
 
+  /** Instrument state (active, loading, off) */
   @property({type: String}) state: InstrumentState = InstrumentState.active;
+  /** Color priority (enhanced = blue palette, regular = gray palette) */
   @property({type: String}) priority: Priority = Priority.regular;
   @property({type: String}) watchCircleType: WatchCircleType =
     WatchCircleType.single;
   @property({type: Boolean}) northArrow: boolean = false;
   @property({type: Boolean}) northArrowInside: boolean | undefined;
+  /** Setpoint angle in degrees (0° = 12 o'clock) */
   @property({type: Number}) angleSetpoint: number | undefined;
+  /** New setpoint being adjusted (focus mode) */
   @property({type: Number}) newAngleSetpoint: number | undefined;
+  /** Whether value matches setpoint (within deadband) */
   @property({type: Boolean}) atAngleSetpoint: boolean = false;
+  /** Deadband for zero detection (default 0.5°) */
   @property({type: Number}) angleSetpointAtZeroDeadband: number = 0.5;
+  /** Override to derive setpoint color from priority regardless of state */
   @property({type: Boolean}) setpointOverride: boolean = false;
   @property({type: Boolean}) touching: boolean = false;
 
@@ -211,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[] = [];
@@ -250,17 +261,25 @@ export class ObcWatch extends LitElement {
   @property({type: Number}) scaleWindIcon: number = 1;
   @property({type: Number}) rotation: number | undefined;
   @property({type: Boolean}) zoomToFitArc: boolean = false;
+  /** Pre-computed zoom-to-fit arc frame. When set, the watch skips its own `computeZoomToFitArcFrame()` call and uses these values directly. Consumer instruments (e.g. rudder, instrument-radial) should compute the frame once and pass it here to avoid redundant computation. If you pass `arcFrame`, you own keeping it in sync with `areas` / `watchCircleType` — obc-watch will NOT recompute it, so a stale frame renders stale geometry. */
   @property({attribute: false}) arcFrame: ZoomToFitArcFrame | undefined;
   @property({type: Number}) tickFadeAngle: number = 0;
 
+  /** ROT visualization type: `'dots'` (spinning dots) or `'bar'` (arc bar with clipped dots). Undefined hides the ROT layer. */
   @property({type: String}) rotType: RotType | undefined;
+  /** Track on which ROT elements are placed: `'scale'` (on the outer ring) or `'innerCircle'` (default, inside the inner ring) */
   @property({type: String}) rotPosition: RotPosition = RotPosition.innerCircle;
+  /** Start angle of the ROT bar arc in degrees (0° = 12 o'clock, clockwise). Only used when `rotType` is `'bar'`. */
   @property({type: Number}) rotStartAngle: number = 0;
+  /** End angle of the ROT bar arc in degrees. The bar is hidden when the difference from `rotStartAngle` is less than 0.1°. */
   @property({type: Number}) rotEndAngle: number = 0;
+  /** Override priority for ROT color derivation. When set, ROT colors use this instead of the main `priority`. Useful when the ROT element has independent priority (e.g. compass per-element priority). */
   @property({type: String}) rotPriority: Priority | undefined;
   @property({type: Boolean}) rotPortStarboard: boolean = false;
   @property({type: Number}) rotAtZeroDeadband: number = ROT_ZERO_DEADBAND_DEG;
+  /** Measured rate of turn in degrees per minute (the maritime/AIS convention, see ES-TRIN 2025/1 Art. 3.02 and ITU-R M.1371). Sign controls direction (positive = starboard/clockwise). When defined, this drives both the dot animation (multiplied by `rotDotAnimationFactor`) and the port/starboard direction sign. */
   @property({type: Number}) rateOfTurnDegreesPerMinute: number | undefined;
+  /** Visual amplification factor applied only to the spinning-dot animation (not to bar extent). Default `18` keeps the legacy visual feel (≈1 rpm at 20°/min). */
   @property({type: Number}) rotDotAnimationFactor: number = 18;
   /**
    * @deprecated Use `rateOfTurnDegreesPerMinute` (and optionally `rotDotAnimationFactor`) instead.
@@ -271,6 +290,7 @@ export class ObcWatch extends LitElement {
   set rotationsPerMinute(value: number) {
     this._legacyRotationsPerMinute = value;
   }
+  /** Legacy spin speed of the ROT dot ring, in rotations per minute (sign controls direction; positive = clockwise). */
   get rotationsPerMinute() {
     return this._legacyRotationsPerMinute;
   }
@@ -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>`;
+}