@wonderlandlabs-pixi-ux/box 1.2.6 → 1.2.8

package/README.STYLES.md

@@ -1,115 +1,124 @@
-# Box Styles and Composition
+# Box Styles
 
-This page documents how the default `BoxUxPixi` composes render layers and which style keys it reads.
+The rebuilt `box` package does not ship a default renderer.
 
-Typical flow:
+Instead, [`BoxStore`](/Users/bingomanatee/Documents/repos/wonderlandlabs-pixi-ux/packages/box/src/BoxStore.ts) provides a small style-resolution surface that renderers can use after layout has been computed.
 
-1. `root.styles = styles`
-2. `root.assignUx((box) => new BoxUxPixi(box))`
-3. `root.render()`
+## Current Contract
 
-## Style Path Resolution
+A box cell can carry:
 
-Each `BoxTree` node has:
+- `name`
+- `variant`
+- `states`
+- `content`
+- `children`
 
-- `styleName`
-- `modeVerb[]`
-- root-level `globalVerb[]`
+`BoxStore` contributes:
 
-When UX code resolves a style property:
+- `styles`
+- `styleStates`
+- `styleNouns`
+- `variant`
+- `resolveStyle(propertyPath, { states?, extraNouns? })`
 
-1. Try hierarchical path + property, e.g. `button.icon.bgColor`
-2. Try hierarchical object, e.g. `button.icon` then pick `bgColor`
-3. Fallback to atomic path + property, e.g. `icon.bgColor`
-4. Fallback to atomic object, e.g. `icon` then pick `bgColor`
+The intent is:
 
-State list is:
+- cells define nouns and state
+- parents compute layout
+- renderers ask the store for appearance
 
-- `globalVerb + modeVerb`
+## Style Resolution
 
-## Default Style Keys
+`resolveStyle()` builds noun paths from the current box node.
 
-The default UX reads:
+For a box named `button` with:
 
-- `bgColor`
-- `bgAlpha`
-- `bgStrokeColor`
-- `bgStrokeAlpha`
-- `bgStrokeSize`
+- `variant: 'primary'`
+- `states: ['hover']`
 
-From resolved paths, this means keys like:
+and a renderer request of:
 
-- `panel.bgColor`
-- `button.icon.bgStrokeColor`
-- `icon.bgStrokeSize`
+```ts
+box.resolveStyle(['fill', 'color']);
+```
+
+the store will try, in order:
 
-## Composition Model
+1. `button.primary.fill.color` with `['hover']`
+2. `button.fill.color` with `['hover']`
+3. `color` with `['hover']`
 
-`BoxUxPixi` exposes:
+If `extraNouns` are provided, they are inserted between the box noun path and the property path. That is how higher-level components can express mode-specific branches such as:
 
-- `content: MapEnhanced` (`Map<string, unknown>` subclass)
-- `content.$box` for the owner node
-- `getContainer(key): unknown` with keys:
-  - `ROOT_CONTAINER`, `BACKGROUND_CONTAINER`, `CHILD_CONTAINER`, `CONTENT_CONTAINER`, `OVERLAY_CONTAINER`, `STROKE_CONTAINER`
-- `attach(targetContainer?)` to mount root container to a parent (or `ux.app?.stage`)
-- `generateStyleMap(box)` -> `{ fill: { color, alpha }, stroke: { color, alpha, width } }`
+- `button.inline.fill.color`
+- `button.icon.vertical.icon.size.x`
 
-Default reserved layer keys:
+## Expected Style Manager Shape
 
-- `BOX_RENDER_CONTENT_ORDER.BACKGROUND = 0`
-- `BOX_RENDER_CONTENT_ORDER.CHILDREN = 50`
-- `BOX_RENDER_CONTENT_ORDER.CONTENT = 75`
-- `BOX_RENDER_CONTENT_ORDER.OVERLAY = 100`
-- `BOX_UX_ORDER` map + `setUxOrder(name, zIndex)` + `getUxOrder(name)` for named custom layers
+The style object attached to `box.styles` only needs to satisfy:
 
-On every `render()`:
+```ts
+type BoxStyleQueryLike = {
+  nouns: string[];
+  states: string[];
+};
+
+type BoxStyleManagerLike = {
+  match: (query: BoxStyleQueryLike) => unknown;
+  matchHierarchy?: (query: BoxStyleQueryLike) => unknown;
+};
+```
 
-1. Default layers are pre-populated if missing
-2. Child UX instances are updated
-3. Child container is cleared and rebuilt from current child UX containers
-4. Optional `box.content` is rendered into the `CONTENT` layer (`text` and image URL content)
-5. Background/stroke are redrawn from styles
-6. `content` is sorted by `zIndex` and non-empty items are attached to the root container
+[`@wonderlandlabs-pixi-ux/style-tree`](https://www.npmjs.com/package/@wonderlandlabs-pixi-ux/style-tree) already matches that shape and is the intended default pairing.
 
-Render queueing is owned by `BoxTree` (store-level watcher), not by `BoxUxPixi`.
+## Renderer Pattern
 
-`BoxUxPixi` extends `BoxUxBase`; custom renderers can usually start from `BoxUxBase`
-to reuse lifecycle patterns (`init`/`render`/`clear` and visible up/down flow).
+The happy-path renderer flow is:
 
-## Built-in Layers
+1. Build or mutate the `BoxStore` tree.
+2. Attach `styles` to the root store.
+3. Call `box.update()` to compute locations.
+4. Walk the resulting tree and render from `location`, `content`, and resolved styles.
 
-- `BACKGROUND`:
-  - `Graphics`
-  - draws fill from `bgColor`
-- `CHILDREN`:
-  - `Container`
-  - receives child renderer containers each frame
-- `CONTENT`:
-  - `Container`
-  - receives optional `box.content` rendering (`text` and image URL content)
-- `OVERLAY`:
-  - `Container`
-  - contains stroke `Graphics` drawing from `bgStrokeColor` + `bgStrokeSize`
+That keeps the responsibilities separated:
 
-## Extending With Custom Layers
+- `ComputeAxis` resolves spans and alignment
+- `BoxStore` owns the layout tree and style lookup context
+- your renderer owns Pixi, HTML, SVG, canvas, or any other output target
 
-You can inject custom layers by setting additional `content` entries:
+## Example
 
 ```ts
-import { Graphics } from 'pixi.js';
-import { BoxUxPixi } from '@wonderlandlabs-pixi-ux/box';
+import { BoxStore } from '@wonderlandlabs-pixi-ux/box';
+import { fromJSON } from '@wonderlandlabs-pixi-ux/style-tree';
+
+const styles = fromJSON({
+  button: {
+    fill: {
+      $*: { color: { r: 0.2, g: 0.4, b: 0.8 }, alpha: 1 }
+    }
+  }
+});
+
+const box = new BoxStore({
+  value: {
+    name: 'button',
+    absolute: true,
+    dim: { x: 0, y: 0, w: 120, h: 40 },
+    align: { direction: 'horizontal', xPosition: 'center', yPosition: 'center' },
+    children: [],
+  },
+});
 
 box.styles = styles;
-const ux = new BoxUxPixi(box);
-const custom = new Graphics();
-custom.visible = true;
+box.update();
 
-custom.zIndex = 76; // 75 is reserved for CONTENT
-ux.content.set('CUSTOM', custom);
-ux.box.render();
+const fillColor = box.resolveStyle(['fill', 'color']);
 ```
 
 ## Notes
 
-- The default UX is intentionally simple: background + children + overlay stroke.
-- If you need richer visuals, return a custom UX object from `assignUx`.
+- The old `BoxTree` / `BoxUxPixi` renderer stack still exists under [`src/_deprecated`](/Users/bingomanatee/Documents/repos/wonderlandlabs-pixi-ux/packages/box/src/_deprecated), but it is legacy code now.
+- The new architecture is intentionally renderer-agnostic.
+- `content` is descriptive data, not a renderer by itself.

package/README.md

@@ -1,284 +1,69 @@
 # @wonderlandlabs-pixi-ux/box
 
-Tree-first box layout model / graphic DSL built on Forestry branches. 
-This emulates FlexBox based layout. This module is a data-model of a flex layout system.
-It was designed for Pixi; however, as an abstract DSL for visual trees it may have other uses.
+`box` is a small parent-driven layout model for rectangular children.
 
-## Installation
+The current implementation is centered around:
 
-```bash
-yarn add @wonderlandlabs-pixi-ux/box
-```
+- [`BoxStore`](/Users/bingomanatee/Documents/repos/wonderlandlabs-pixi-ux/packages/box/src/BoxStore.ts)
+- [`ComputeAxis`](/Users/bingomanatee/Documents/repos/wonderlandlabs-pixi-ux/packages/box/src/ComputeAxis.ts)
 
-## Basic Usage
+## Current Model
 
-```ts
-import {
-  ALIGN,
-  BoxTree,
-  UNIT_BASIS,
-} from '@wonderlandlabs-pixi-ux/box';
+- The parent owns alignment.
+- Children provide dimensions.
+- Child `x` / `y` are not part of the happy-path alignment flow.
+- Width and height are computed from the parent container.
+- All units are relative to the parent in the dimension they address.
 
-const layout = new BoxTree({
-  id: 'root',
-  styleName: 'button',
-  globalVerb: [],
-  area: {
-    x: 60,
-    y: 50,
-    width: { mode: UNIT_BASIS.PX, value: 720 },
-    height: { mode: UNIT_BASIS.PX, value: 340 },
-    px: 's',
-    py: 's',
-  },
-  align: {
-    x: ALIGN.START,
-    y: ALIGN.START,
-    direction: 'column',
-  },
-  children: {
-    header: {
-      styleName: 'header',
-      area: {
-        x: 0,
-        y: 0,
-        width: { mode: UNIT_BASIS.PERCENT, value: 1 },
-        height: { mode: UNIT_BASIS.PX, value: 60 },
-        px: 's',
-        py: 's',
-      },
-      align: { x: 's', y: 's', direction: 'row' },
-    },
-    icon: {
-      styleName: 'icon',
-      modeVerb: ['hover'],
-      area: {
-        x: 0,
-        y: 0,
-        width: { mode: UNIT_BASIS.PX, value: 24 },
-        height: { mode: UNIT_BASIS.PX, value: 24 },
-        px: 's',
-        py: 's',
-      },
-      align: { x: 's', y: 's', direction: 'column' },
-    },
-  },
-});
+That means:
 
-const icon = layout.getChild('icon');
-icon?.toggleModeVerb('selected');
-layout.toggleGlobalVerb('disabled');
-```
+- width-like values resolve against the parent width
+- height-like values resolve against the parent height
+- percent values are always percentages of the parent dimension
+- absolute pixel values are still interpreted within the parent container
 
-## Ux Assignment
+## Flow
 
-`BoxTree` defaults to the built-in Pixi UX map. Override with `assignUx(ux, applyToChildren?)`:
+The current layout pass is:
 
-```ts
-import { BoxUxPixi } from '@wonderlandlabs-pixi-ux/box';
+1. Resolve the main-axis spans for the children.
+2. Complete unresolved fractional spans.
+3. Place children from the parent alignment and the resolved spans.
+4. Recurse into child boxes using the computed location rectangles.
 
-layout.styles = styles;
-layout.assignUx((box) => new BoxUxPixi(box));
-layout.render(); // calls ux.init() once, then ux.render()
-```
+`ComputeAxis` currently handles:
 
-`addChild()` inherits the parent UX map function automatically.
+- absolute pixel dimensions
+- percentage dimensions
+- fractional dimensions on the main axis by weighted remainder distribution
+- fractional dimensions on the cross axis by resolving to the largest resolved peer span
+- cross-axis `fill`
+- parent-owned start / center / end alignment
 
-Constructor shortcut:
+## Styles
 
-```ts
-const layout = new BoxTree({
-  id: 'root',
-  area: { x: 0, y: 0, width: 200, height: 100 },
-  ux: (box) => new BoxUxPixi(box),
-});
-layout.styles = styles;
-```
+`BoxStore` also exposes style context for renderers:
 
-## Style Definitions
+- `styles`
+- `variant`
+- `styleStates`
+- `styleNouns`
+- `resolveStyle(...)`
 
-`BoxTree` integrates with a shared style manager by way of `styleName` and verbs:
+See [`README.STYLES.md`](/Users/bingomanatee/Documents/repos/wonderlandlabs-pixi-ux/packages/box/README.STYLES.md) for the renderer-facing contract.
 
-- `styleName` is the noun for that node (`button`, `icon`, `label`, ...)
-- `modeVerb` is node-local state (`hover`, `selected`, ...)
-- `globalVerb` is root-level state shared by all descendants (`disabled`, ...)
+## Status
 
-Use `resolveStyle(styleManager, extraStates?)` to query styles. Resolution order is:
+This package is mid-refactor.
 
-1. Hierarchical nouns (`button.icon`, `toolbar.button.label`, ...)
-2. Fallback to atomic noun (`icon`, `label`, ...)
+The active architecture is the simplified `BoxStore` / `ComputeAxis` path in `src/`.
+Older `BoxTree`-style code still exists under [`src/_deprecated`](/Users/bingomanatee/Documents/repos/wonderlandlabs-pixi-ux/packages/box/src/_deprecated), but it is not the current direction.
 
-Combined state list is:
+## Test Artifacts
 
-- `globalVerb + modeVerb + extraStates`
+The `ComputeAxis` tests generate:
 
-```ts
-import { fromJSON } from '@wonderlandlabs-pixi-ux/style-tree';
+- SVG diagrams for layout inspection
+- HTML tables for readable scenario metadata
 
-const styles = fromJSON({
-  button: {
-    icon: {
-      fill: {
-        $*: { color: { r: 0.2, g: 0.2, b: 0.2 }, alpha: 1 },
-        $disabled: { color: { r: 0.45, g: 0.45, b: 0.45 }, alpha: 1 },
-      },
-    },
-  },
-  icon: {
-    fill: {
-      $*: { color: { r: 1, g: 1, b: 1 }, alpha: 1 },
-    },
-  },
-});
-
-const icon = layout.getChild('icon');
-const fillStyle = icon?.resolveStyle(styles, ['pressed']);
-```
-
-## Default Ux
-
-`box` ships with `BoxUxPixi`, a default Pixi UX implementation for `BoxTree`.
-
-Behavior:
-
-- Creates a container when `container` is not provided
-- Uses public `content: MapEnhanced` (a `Map<string, unknown>` subclass)
-- `content.$box` points at the owning `BoxTree`
-- Exposes `ux.getContainer(key): unknown` for renderer-to-renderer handoff:
-  - `ROOT_CONTAINER`, `BACKGROUND_CONTAINER`, `CHILD_CONTAINER`, `CONTENT_CONTAINER`, `OVERLAY_CONTAINER`, `STROKE_CONTAINER`
-- Exposes `ux.attach(targetContainer?)`:
-  - attaches root container to `targetContainer`
-  - if omitted, uses `ux.app?.stage`
-- Pre-populates built-in layers if absent:
-  - `BOX_RENDER_CONTENT_ORDER.BACKGROUND = 0`
-  - `BOX_RENDER_CONTENT_ORDER.CHILDREN = 50`
-  - `BOX_RENDER_CONTENT_ORDER.CONTENT = 75`
-  - `BOX_RENDER_CONTENT_ORDER.OVERLAY = 100`
-- Supports named layer order lookups:
-  - `BOX_UX_ORDER` (`ReadonlyMap<string, number>`)
-  - `setUxOrder(name, zIndex)` with duplicate z-index protection
-  - `getUxOrder(name)` for safe lookup
-- Rebuilds children layer each render by clearing and re-adding child UX containers
-- Draws a background graphic from style props:
-  - `[stylePath].bgColor`
-  - `[stylePath].bgAlpha`
-  - `[stylePath].bgStrokeColor`
-  - `[stylePath].bgStrokeAlpha`
-  - `[stylePath].bgStrokeSize`
-- Exposes `ux.generateStyleMap(box)` with normalized shape:
-  - `fill: { color, alpha }`
-  - `stroke: { color, alpha, width }`
-- Honors `box.isVisible`:
-  - when `false`, detaches (hides) the container without destroying render content
-  - when `true` again, existing layers are reused on next render
-- Iterates `content` and injects non-empty items into root container sorted by each item's `zIndex`
-
-```ts
-import { Graphics } from 'pixi.js';
-import {
-  BOX_RENDER_CONTENT_ORDER,
-  BoxTree,
-  BoxUxPixi,
-} from '@wonderlandlabs-pixi-ux/box';
-import { fromJSON } from '@wonderlandlabs-pixi-ux/style-tree';
-
-const styles = fromJSON({
-  button: {
-    bgColor: { $*: 0x2d3a45 },
-    bgStrokeColor: { $*: 0x8fd3ff },
-    bgStrokeSize: { $*: 2 },
-    icon: {
-      bgColor: { $*: 0x3a4957 },
-    },
-  },
-  icon: {
-    bgColor: { $*: 0x222222 },
-  },
-});
-
-const root = new BoxTree({
-  id: 'root',
-  styleName: 'button',
-  area: { x: 40, y: 30, width: 200, height: 100 },
-  children: {
-    icon: {
-      styleName: 'icon',
-      order: 0,
-      area: { width: 24, height: 24 },
-    },
-  },
-});
-
-root.styles = styles;
-const ux = new BoxUxPixi(root);
-root.render();
-// manual mount
-ux.attach(app.stage);
-
-// custom content layer example:
-const custom = new Graphics();
-custom.zIndex = 76;
-custom.visible = true;
-ux.content.set('CUSTOM', custom);
-ux.content.get('OVERLAY')?.visible = true;
-const ownerBox = ux.content.$box;
-```
-
-## Override Points
-
-`BoxUxBase` is the renderer-agnostic lifecycle base (`init`, `render`, `clear`, visible up/down flow).
-`BoxUxPixi` extends `BoxUxBase` and provides the Pixi-specific containers/graphics behavior.
-
-For custom behavior, return your own UX instance from `assignUx((box) => ...)`, either:
-
-- extending `BoxUxBase` for a new renderer, or
-- extending `BoxUxPixi` for Pixi-specific customization.
-
-Detailed style/composition docs:
-
-- [`README.STYLES.md`](./README.STYLES.md)
-
-## Optional Pixi Debug Rendering
-
-If you just want geometry previews, you can use `boxTreeToPixi`:
-
-```ts
-import { boxTreeToPixi } from '@wonderlandlabs-pixi-ux/box';
-
-const graphics = await boxTreeToPixi(layout, {
-  includeRoot: true,
-  fill: 0x2d3a45,
-  fillAlpha: 0.35,
-  stroke: 0x8fd3ff,
-  strokeAlpha: 0.9,
-  strokeWidth: 2,
-});
-```
-
-## Public API
-
-- `BoxTree`
-- `BoxUx` (UX object type)
-- `BoxUxMapFn`
-- `BoxRenderer` (legacy alias of `BoxUx`)
-- `BoxRenderMapFn` (legacy alias of `BoxUxMapFn`)
-- `MapEnhanced`
-- `BoxUxBase`
-- `BoxUxPixi`
-- `BoxTreeRenderer` (legacy alias of `BoxUxPixi`)
-- `BOX_UX_ORDER`, `getUxOrder`, `setUxOrder`
-- `BOX_RENDER_CONTENT_ORDER`
-- `createBoxTreeState`
-- `resolveTreeMeasurement`
-- `resolveMeasurementPx`
-- `resolveConstraintValuePx`
-- `applyAxisConstraints`
-- `boxTreeToPixi`
-- `boxTreeToSvg`
-- `pathToString`, `pathString`, `combinePaths`
-- `ALIGN`, `AXIS`, `UNIT_BASIS`, `SIZE_MODE`, `SIZE_MODE_INPUT`
-- `TreeStyleNameSchema`, `TreeVerbSchema`, `TreeVerbListSchema`
-
-## Data Model
-
-Use exported BoxTree schemas/types in `src/types.boxtree.ts` and measurement schemas in `src/types.ts` as the source of truth.
+These artifacts are written under [`packages/box/test/artifacts`](/Users/bingomanatee/Documents/repos/wonderlandlabs-pixi-ux/packages/box/test/artifacts) and are ignored by the package-level `.gitignore`.

package/TODO.md

@@ -0,0 +1,9 @@
+# TODO
+
+- use Immer/diff to only recompute the children that have changed or the children of changed nodes. 
+- Decide how overflow should resolve when content exceeds the parent container:
+  squash content to fit, crop content to the container, or allow overflow without intervention.
+- Consider adding min/max sizing constraints, especially if fractional sizing makes alignment too inert.
+- Keep the parent-owned alignment model strict: children define dimensions, parents place them.
+- Add a first-class renderer package or reference renderer examples for Pixi, HTML, and SVG.
+- Normalize package-root exports so sibling packages do not need `dist` subpath imports during local compilation.

package/dist/BorderThickness.d.ts

@@ -0,0 +1,11 @@
+import type { BorderPartType, BoxBorderType } from './types.js';
+export type BorderInsets = Record<BorderPartType, number>;
+export declare class BorderThickness {
+    #private;
+    readonly top: number;
+    readonly right: number;
+    readonly bottom: number;
+    readonly left: number;
+    constructor(defs?: BoxBorderType);
+    toInsets(): BorderInsets;
+}

package/dist/BorderThickness.js

@@ -0,0 +1,57 @@
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _a, _BorderThickness_apply;
+import { BORDER_PART_BOTTOM, BORDER_PART_LEFT, BORDER_PART_RIGHT, BORDER_PART_TOP, BORDER_SCOPE_ALL, BORDER_SCOPE_BOTTOM, BORDER_SCOPE_HORIZ, BORDER_SCOPE_LEFT, BORDER_SCOPE_RIGHT, BORDER_SCOPE_TOP, BORDER_SCOPE_VERT, } from './constants.js';
+export class BorderThickness {
+    constructor(defs = []) {
+        const insets = defs.reduce((nextInsets, def) => {
+            return __classPrivateFieldGet(_a, _a, "m", _BorderThickness_apply).call(_a, nextInsets, def);
+        }, {
+            [BORDER_PART_TOP]: 0,
+            [BORDER_PART_RIGHT]: 0,
+            [BORDER_PART_BOTTOM]: 0,
+            [BORDER_PART_LEFT]: 0,
+        });
+        this.top = insets[BORDER_PART_TOP];
+        this.right = insets[BORDER_PART_RIGHT];
+        this.bottom = insets[BORDER_PART_BOTTOM];
+        this.left = insets[BORDER_PART_LEFT];
+    }
+    toInsets() {
+        return {
+            [BORDER_PART_TOP]: this.top,
+            [BORDER_PART_RIGHT]: this.right,
+            [BORDER_PART_BOTTOM]: this.bottom,
+            [BORDER_PART_LEFT]: this.left,
+        };
+    }
+}
+_a = BorderThickness, _BorderThickness_apply = function _BorderThickness_apply(insets, def) {
+    const { scope, value } = def;
+    switch (scope) {
+        case BORDER_SCOPE_ALL:
+            return {
+                [BORDER_PART_TOP]: value,
+                [BORDER_PART_RIGHT]: value,
+                [BORDER_PART_BOTTOM]: value,
+                [BORDER_PART_LEFT]: value,
+            };
+        case BORDER_SCOPE_HORIZ:
+            return { ...insets, [BORDER_PART_LEFT]: value, [BORDER_PART_RIGHT]: value };
+        case BORDER_SCOPE_VERT:
+            return { ...insets, [BORDER_PART_TOP]: value, [BORDER_PART_BOTTOM]: value };
+        case BORDER_SCOPE_TOP:
+            return { ...insets, [BORDER_PART_TOP]: value };
+        case BORDER_SCOPE_RIGHT:
+            return { ...insets, [BORDER_PART_RIGHT]: value };
+        case BORDER_SCOPE_BOTTOM:
+            return { ...insets, [BORDER_PART_BOTTOM]: value };
+        case BORDER_SCOPE_LEFT:
+            return { ...insets, [BORDER_PART_LEFT]: value };
+        default:
+            return insets;
+    }
+};

package/dist/BoxPixi.stories.d.ts

@@ -0,0 +1,9 @@
+import type { Meta, StoryObj } from '@storybook/html';
+type Story = StoryObj;
+declare const meta: Meta;
+export default meta;
+export declare const PixiBoxRendererPOC: Story;
+export declare const ProductCatalogGrid: Story;
+export declare const ProductDetailHero: Story;
+export declare const ProductComparisonStrip: Story;
+export declare const BoxDebugLoop: Story;