PatternStringProperty

PatternStringProperty<Values> (from scenerystack/axon) is a specialized DerivedProperty (technically, a DerivedStringProperty) that fills tokens in a translated pattern string with values pulled from other Properties, automatically re-deriving whenever the pattern string or any value Property changes. This is the standard way to build a translated, dynamic UI string like "Score: " or " particles remaining" without hand-rolling a DerivedProperty and a StringUtils.fillIn call yourself.

import { PatternStringProperty, NumberProperty, TinyProperty } from 'scenerystack/axon';

const scoreProperty = new NumberProperty( 0 );
const patternProperty = new TinyProperty( '{{score}} points' ); // typically a translated StringProperty

const scoreStringProperty = new PatternStringProperty( patternProperty, {
  score: scoreProperty
} );

scoreStringProperty.value; // '0 points'
scoreProperty.value = 12;
scoreStringProperty.value; // '12 points'

Values may be plain strings/numbers or Properties of strings/numbers — both work in the values record, and only the Property ones become dependencies that trigger re-derivation.

Constructor

new PatternStringProperty( patternProperty, values, providedOptions? )

Parameter	Effect
patternProperty	A TReadOnlyProperty<string> holding the pattern, e.g. a localized ...StringProperty with -style placeholders
values	A record mapping each placeholder name to a string | number | TReadOnlyProperty<string | number> (or, with a maps entry, any other Property type)
providedOptions	See below

Options

Option	Default	Effect
maps	{}	Per-key functions converting a value to string | number before substitution — required for any key whose value isn't already string, number, or a Property of those
decimalPlaces	null	Rounds numeric values (after any map) to a fixed number of decimals; either one number applied to every numeric value, or a per-key record
formatNames	[]	Back-compat shim for patterns written for StringUtils.format's {0}/{1} style — lists the placeholder names those positional indices map to

const gramsProperty = new NumberProperty( 2143 );

const kilogramsStringProperty = new PatternStringProperty(
  new TinyProperty( '{{kilograms}} kg' ),
  { kilograms: gramsProperty },
  {
    maps: { kilograms: ( grams: number ) => grams / 1000 },
    decimalPlaces: 2
  }
);

kilogramsStringProperty.value; // '2.14 kg'

It's a DerivedProperty — dispose it

Because PatternStringProperty is built on DerivedProperty, it lazy-links to patternProperty and every value Property passed in, and its value can't be set directly. Always dispose() a PatternStringProperty you create dynamically (e.g. per list item), the same as any other DerivedProperty.