@wonderlandlabs-pixi-ux/box 1.2.5 → 1.2.7

package/README.md

@@ -1,284 +1,53 @@
 # @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.
 
-layout.styles = styles;
-layout.assignUx((box) => new BoxUxPixi(box));
-layout.render(); // calls ux.init() once, then ux.render()
-```
+`ComputeAxis` currently handles the green path for:
 
-`addChild()` inherits the parent UX map function automatically.
+- absolute pixel dimensions
+- percentage dimensions
+- parent-owned start / center / end alignment
 
-Constructor shortcut:
+## Status
 
-```ts
-const layout = new BoxTree({
-  id: 'root',
-  area: { x: 0, y: 0, width: 200, height: 100 },
-  ux: (box) => new BoxUxPixi(box),
-});
-layout.styles = styles;
-```
+This package is mid-refactor.
 
-## Style Definitions
+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.
 
-`BoxTree` integrates with a shared style manager by way of `styleName` and verbs:
+## Test Artifacts
 
-- `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`, ...)
+The `ComputeAxis` tests generate:
 
-Use `resolveStyle(styleManager, extraStates?)` to query styles. Resolution order is:
+- SVG diagrams for layout inspection
+- HTML tables for readable scenario metadata
 
-1. Hierarchical nouns (`button.icon`, `toolbar.button.label`, ...)
-2. Fallback to atomic noun (`icon`, `label`, ...)
-
-Combined state list is:
-
-- `globalVerb + modeVerb + extraStates`
-
-```ts
-import { fromJSON } from '@wonderlandlabs-pixi-ux/style-tree';
-
-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,10 @@
+# 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.

package/dist/BoxStore.d.ts

@@ -1,56 +1,7 @@
-import { StoreParams } from '@wonderlandlabs/forestry4';
-import { TickerForest } from '@wonderlandlabs-pixi-ux/ticker-forest';
-import { Application, Container, Graphics, Text, type ContainerOptions, type Sprite, type TextStyleOptions } from 'pixi.js';
-import type { AxisDef, BaseBoxConfig, BoxProps, BoxState, BoxStyle, ContentArea, Padding, RgbColor } from './types';
-export declare class BoxStore extends TickerForest<BoxState> {
-    #private;
-    readonly id: string;
-    protected _container: Container;
-    protected _background: Graphics;
-    protected _contentContainer: Container;
-    maskGraphics: Graphics;
-    protected _boxProps: BoxProps;
-    constructor(configOrParams: BaseBoxConfig | StoreParams<BoxState>, app: Application, boxProps?: BoxProps, rootProps?: ContainerOptions);
-    get container(): Container;
-    get contentContainer(): Container;
-    get rect(): {
-        x: number;
-        y: number;
-        width: number;
-        height: number;
-    };
-    get xDef(): AxisDef;
-    get yDef(): AxisDef;
-    get children(): readonly BoxStore[];
-    get style(): BoxStyle | undefined;
-    setStyle(style: Partial<BoxStyle>): void;
-    get gap(): number;
-    setGap(gap: number): void;
-    get direction(): 'horizontal' | 'vertical';
-    setDirection(direction: 'horizontal' | 'vertical'): void;
-    get gapMode(): 'between' | 'before' | 'after' | 'all';
-    setGapMode(gapMode: 'between' | 'before' | 'after' | 'all'): void;
-    get text(): string;
-    get textDisplay(): Text | null;
-    setText(text: string): void;
-    setTextStyle(style: TextStyleOptions): void;
-    setPadding(padding: Partial<Padding>): void;
-    setPosition(x: number, y: number): void;
-    setSize(width: number, height: number): void;
-    getContentArea(): ContentArea;
-    setContent(content: Graphics | Sprite | Text | Container | null): void;
-    get content(): Graphics | Sprite | Text | Container | null;
-    addChild(config: BaseBoxConfig): BoxStore;
-    removeChild(childOrId: string | BoxStore): void;
-    getChild(id: string): BoxStore | undefined;
-    toConfig(): BaseBoxConfig;
-    protected _rgbToNumber(rgb: RgbColor): number;
-    protected _renderBackground(): void;
-    protected _updateMask(): void;
-    protected _updateContentPosition(): void;
-    protected isDirty(): boolean;
-    protected clearDirty(): void;
-    markDirty(): void;
-    protected resolve(): void;
-    cleanup(): void;
+import { Forest } from '@wonderlandlabs/forestry4';
+import type { BoxCellType, RectPXType } from './types.js';
+export declare class BoxStore extends Forest<BoxCellType> {
+    update(): void;
+    get location(): RectPXType;
+    alignChildren(): void;
 }