Typed OM

Typed reads and change detection for CSS custom properties, in browsers with or without CSS Typed OM and @property.

Typed OM is the engine under Surface. It reads every --ax-* property of a surface as numbers, colors and keywords, and tells the surface when one of them changed. You need it only to build your own elements.

Describe your custom properties once in a schema, bind the schema to an element and read. Common forms such as 12px, 50%, calc(50% + 4px), rgb() and hex are parsed directly. Everything else, such as calc(1em + 2px) or red, goes through a hidden probe element, so the browser does the math.

Every example on this page is live. The controls set custom properties on an element, and the code of the package reads them back. The text in the preview is what the package returned.

npm install @ax-design/typed-om

import { StyleSchema, StyleBinding } from '@ax-design/typed-om';

A length-percentage property is read as an object: px is the pixel part and percent is the percentage part, where 50 means 50%. Type a value into the box and the text shows what binding.get returns.

Try 12px, 50%, calc(10% + 4px) and calc(100% - 2px). Values with em, rem or vw have no fixed form, so the package asks the browser: the last line counts how many properties needed the probe.

const schema = new StyleSchema([
  { name: '--my-size', syntax: { type: 'length-percentage' }, initial: '0px', inherits: true }
]);

// host is your element, root its shadow root.
const binding = new StyleBinding(schema, host, root);
binding.read();
binding.get('--my-size');

.my-element {
  --my-size: calc(10% + 4px);
}

A color property is read as [r, g, b, a]: red, green and blue from 0 to 255, and alpha from 0 to 1. A value that is not a color gives the initial color of the schema.

rgb() and hex are parsed directly. Named colors, hsl() and anything else go through the probe, so try rebeccapurple, hsl(200 80% 50%) or color-mix(in srgb, red, blue).

const schema = new StyleSchema([
  { name: '--my-color', syntax: { type: 'color' }, initial: 'black', inherits: true }
]);

const binding = new StyleBinding(schema, host, root);
binding.read();
binding.get('--my-color');

.my-element {
  --my-color: rgb(255 200 0 / 60%);
}

A keyword property returns one of the values you allowed, as a string. Any other word gives the initial value, so the property is always one of your keywords.

A property can be skipped when another one makes it irrelevant. Here the depth is only read while the mode is hard. While the mode is soft, the schema keeps the initial depth and the browser is not asked at all, which saves work on every read.

const schema = new StyleSchema([
  { name: '--my-mode', syntax: { type: 'keyword', values: ['soft', 'hard'] }, initial: 'soft', inherits: false },
  {
    name: '--my-depth',
    syntax: { type: 'length' },
    initial: '0px',
    inherits: false,
    skipWhen: { property: '--my-mode', values: ['soft'] }
  }
]);

const binding = new StyleBinding(schema, host, root);
binding.read();
binding.get('--my-mode');
binding.get('--my-depth');

.my-element {
  --my-mode: hard;
  --my-depth: 80px;
}

binding.observe tells you when something in the schema changed, whatever the cause: a class, a media query, a transition. It does not tell you the new values. Read them on the next frame, once, however many times the callback ran.

Move the slider. The bar follows the CSS transition, the text is read only from the callback. Turn Watch off and the package stops: the callback does not run and nothing is read. The detector costs a little on every style change of the page, so watch only while your element is visible.

const schema = new StyleSchema([
  { name: '--my-level', syntax: { type: 'number' }, initial: '0', inherits: true, register: true }
]);
const binding = new StyleBinding(schema, host, root);

let frame = 0;
binding.observe(() => {
  if (frame) return;
  frame = requestAnimationFrame(() => {
    frame = 0;
    binding.read();
    draw(binding.get('--my-level'));
  });
});

// Watch: true
binding.unobserve();

.my-element {
  --my-level: 0;
  transition: --my-level 1500ms;
}

An unregistered custom property is text to the browser, so a transition on it jumps from the start to the end. With register: true the package calls CSS.registerProperty for you, and the transition passes through every value in between.

Move the slider. Both bars are drawn from values read with the package: the registered one follows the transition, the plain one jumps. Where CSS.registerProperty does not exist, both jump and everything else still works.

const schema = new StyleSchema([
  { name: '--my-registered', syntax: { type: 'number' }, initial: '0', inherits: false, register: true },
  { name: '--my-plain', syntax: { type: 'number' }, initial: '0', inherits: true }
]);

schema.registered.has('--my-registered'); // true where CSS.registerProperty exists
schema.registered.has('--my-plain'); // false

.my-element {
  --my-registered: 0;
  transition: --my-registered 1500ms;
}

Reference