@wonderlandlabs-pixi-ux/box 1.2.7 → 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

@@ -29,13 +29,29 @@ The current layout pass is:
 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.
 
-`ComputeAxis` currently handles the green path for:
+`ComputeAxis` currently handles:
 
 - 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
 
+## Styles
+
+`BoxStore` also exposes style context for renderers:
+
+- `styles`
+- `variant`
+- `styleStates`
+- `styleNouns`
+- `resolveStyle(...)`
+
+See [`README.STYLES.md`](/Users/bingomanatee/Documents/repos/wonderlandlabs-pixi-ux/packages/box/README.STYLES.md) for the renderer-facing contract.
+
 ## Status
 
 This package is mid-refactor.

package/TODO.md

@@ -1,10 +1,9 @@
 # TODO
 
-- Achieve recursive layout so each child can compute and apply layout to its own children.
 - use Immer/diff to only recompute the children that have changed or the children of changed nodes. 
-- Properly compute fractional dimensions on the main axis.
-- Replace the current no-op fractional completion step with remainder distribution across unresolved spans.
 - 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;