@wonderlandlabs-pixi-ux/style-tree

A hierarchical style matching system with noun paths and state arrays.

Features

• Hierarchical noun paths (navigation.button.icon)
• State-based selection (hover, disabled, selected, ...)
• Wildcard matching in noun segments (base.*.label)
• Base-state matching with * state
• Automatic interCaps normalization (fontSize -> font.size)
• Hierarchical-to-atomic fallback via matchHierarchy()
• Ranking by specificity

Installation

yarn add @wonderlandlabs-pixi-ux/style-tree

Usage

import { StyleTree } from '@wonderlandlabs-pixi-ux/style-tree';

const tree = new StyleTree();

// Prefer dot-separated noun parts over compound keys:
// use "font.size" instead of "fontSize".
tree.set('base.*.label.font.size', [], 12);
tree.set('base.*.label.font.color', [], '#666');
tree.set('navigation.button.text.font.size', [], 14);
tree.set('navigation.button.text.font.color', [], '#000');
tree.set('navigation.button.text.font.color', ['hover'], '#0066cc');
tree.set('navigation.button.text.font.color', ['disabled', 'selected'], '#999');

const style = tree.match({
  nouns: ['navigation', 'button', 'text', 'font', 'color'],
  states: ['hover'],
});

const match = tree.findBestMatch({
  nouns: ['navigation', 'button', 'text', 'font', 'color'],
  states: ['hover'],
});

// Hierarchical first, then leaf fallback.
// Example: if "button.icon" is missing, fallback to "icon".
const iconStyle = tree.matchHierarchy({
  nouns: ['button', 'icon'],
  states: ['disabled'],
});

// Legacy interCaps keys are normalized automatically.
tree.set('button.label.fontSize', [], 12);
tree.get('button.label.font.size', []); // 12
tree.set('windowLabelFontSize', [], 10);
tree.get('window.label.font.size', []); // 10

Matching Rules

Score: (matching nouns * 100) + matching states

• Wildcard nouns (*) match any segment but do not add score.
• State * is a base state that matches any query states.
• State patterns can be less specific than query states:
  • ['disabled'] matches query ['disabled', 'selected']
  • ['disabled', 'selected'] does not match query ['disabled']

API

Constructor:

• new StyleTree(options?)
  • validateKeys?: boolean (default true)
  • autoSortStates?: boolean (default true)
  • normalizeInterCaps?: boolean (default true)

Methods:

• set(nouns: string, states: string[], value: unknown): void
• get(nouns: string, states: string[]): unknown
• has(nouns: string, states: string[]): boolean
• match(query: { nouns: string[]; states: string[] }): unknown
• matchHierarchy(query: { nouns: string[]; states: string[] }): unknown
• findBestMatch(query): StyleMatch | undefined
• findAllMatches(query): StyleMatch[]

Canonical Style Conventions

This package does not assume any sort of heirarchy or keys for nouns; you can organize your styles however you like. However withn the @wonderlandlabs-pixi-ux family of modules we have established a pattern, documented below;

context[.context].topic.propewrty

as in, window.panel (context) .font (topic) .size (property). this is comparable but not strictly analogous to the IBM convention Base, Element, Modifer (BEM).

For consistency across packages, the style package now exposes canonical key conventions: General naming rule: avoid compound keys such as fontSize in favor of dot-separated noun parts like font.size. Nouns and verbs should be lowercase across the board, unless you expect and want to have your nouns split up. This is true in the setter(s) and the getter(s) but it is really best if you express all noun keys in lowercase fully exploded termas as described below.

• *.font.size (number, px)
• *.font.color (hex string)
• *.font.family (string)
• *.font.alpha (0..1)
• *.font.visible (boolean)
• *.fill.size (number)
• *.fill.color (hex string)
• *.fill.alpha (0..1)
• *.fill.visible (boolean)
• *.stroke.size (number)
• *.stroke.color (hex string)
• *.stroke.alpha (0..1)
• *.stroke.visible (boolean)

Helpers:

• normalizeStyleConvention(partial)
• setConvention(tree, path, states, partial)
• conventionKeys(path)

Example

import { StyleTree, setConvention } from '@wonderlandlabs-pixi-ux/style-tree';

const tree = new StyleTree();
setConvention(tree, 'window.label', [], {
  font: {
    size: 10,
    family: 'Helvetica',
    color: '#000000',
    alpha: 1,
    visible: true,
  },
  fill: {
    size: 0,
    color: '#000000',
    alpha: 1,
    visible: true,
  },
  stroke: {
    size: 1,
    color: '#000000',
    alpha: 1,
    visible: true,
  },
});

JSON Tree Digestion

fromJSON() converts nested JSON into tree entries. Plain keys build noun paths; $ keys create state variants.

Example

import { fromJSON } from '@wonderlandlabs-pixi-ux/style-tree';

const themeJSON = {
  button: {
    icon: {
      fill: {
        $*: { color: { r: 1, g: 1, b: 1 }, alpha: 1 },
        $disabled: { color: { r: 0.5, g: 0.5, b: 0.5 }, alpha: 1 },
      },
    },
  },
};

const tree = fromJSON(themeJSON);

A note on stored values

This library does not make any assumptions about which values should be stored in which keys; type validation must be done by the using context. (hint - Zod can take a lot of pain out of the process.)

License

MIT