measureElement

Read as Markdown

import {
  createElement,
  measureElement,
  Rectangle,
  type CanvasMeasurementService,
  type Constraints,
} from "@pibbl/core";

measureElement(element, constraints, service) measures one element through its opt-in primitive capability. It is pure: it cannot render or acquire runtime resources. Components without a measure capability return an unsupported result, and cyclic measurement dependencies are rejected.

Signal writes are rejected throughout measurement, including custom normalization, measurement callbacks and the text-measurement service. This also applies when called outside a mounted component. A rejected signal update does not run its updater or change its value; ordinary writes remain available after measurement returns or throws.

const element = createElement(Rectangle, {
  style: { width: 120, height: 60, fill: "#2563eb" },
});
const constraints: Constraints = {
  minWidth: 0,
  maxWidth: 240,
  minHeight: 0,
  maxHeight: 120,
};
const measurementService: CanvasMeasurementService = {
  measureText: () => ({}) as TextMetrics,
};
const result = measureElement(element, constraints, measurementService);

Constraints and a CanvasMeasurementService describe the call; its result is a MeasureResult. Use declared boxes for ordinary layout rather than assuming visual primitives have intrinsic dimensions.

API details from source

Measures an element against finite constraints using the supplied Canvas measurement service.

measureElement: (element: PibblElement<any>, constraints: Readonly<Constraints>, service: CanvasMeasurementService) => MeasureResult

Parameters

element — Element whose declared measurement capability is used. See PibblElement.
constraints — Available size constraints in logical units. See Constraints.
service — Canvas text measurement service. See CanvasMeasurementService.

Returns

Measured dimensions, or an unsupported result with its reason. See MeasureResult .

Implementation guidance for agents

Read the Drawing, layout, and effects companion for ownership, adaptation, failure modes, and verification. Agent start provides the version-selection workflow.

Complete minimal examples

Intrinsic measurement: Measure a Text element with a Canvas service and display its computed dimensions. Plain source

Documentation version

Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.