@wonderlandlabs-pixi-ux/box 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# CHANGELOG
+
+## 1.0
+
+Achieved a basic system to use nested containers / tree system
+to express flex -like containment in pixi
+
+## 1.0.1 
+
+Refactored for a single - class expression; full reboot with
+fewer size modes and more robust updating. Fully removed all pixi/
+rendering from the boxes; child classes/external utilities responsible
+for rendering content. 

package/README.BOX_VALUES.md

@@ -0,0 +1,255 @@
+# BoxTree Value Model
+
+This document describes the current value model for `BoxTree` in `@wonderlandlabs-pixi-ux/box`.
+
+## Scope
+
+This is for the new tree/value geometry model in:
+
+- `/Users/davidedelhart/Documents/repos/forestry-pixi/packages/box/src/BoxTree.ts`
+- `/Users/davidedelhart/Documents/repos/forestry-pixi/packages/box/src/types.boxtree.ts`
+- `/Users/davidedelhart/Documents/repos/forestry-pixi/packages/box/src/types.ts`
+- `/Users/davidedelhart/Documents/repos/forestry-pixi/packages/box/src/sizeUtils.ts`
+
+## State Schema
+
+```ts
+type Measurement = { mode: 'px' | '%'; value: number };
+
+type AxisConstrain = {
+  min?: number; // px
+  max?: number; // px
+};
+
+type BoxContent = {
+  type: 'text' | 'url';
+  value: string;
+};
+
+type BoxTreeState = {
+  area: {
+    x: number;
+    y: number;
+    width: Measurement;
+    height: Measurement;
+    px?: 's' | 'c' | 'e'; // optional pivot-x, aliases: < | >
+    py?: 's' | 'c' | 'e'; // optional pivot-y, aliases: < | >
+  };
+  align: {
+    x: 's' | 'c' | 'e' | 'f';
+    y: 's' | 'c' | 'e' | 'f';
+    direction: 'row' | 'column';
+  };
+  order: number;
+  absolute: boolean;
+  constrain?: { x?: AxisConstrain; y?: AxisConstrain };
+  content?: BoxContent;
+  style?: BoxStyle;
+  id?: string;
+  children?: Map<string, BoxTreeState>;
+};
+```
+
+## Core Rules
+
+- `x` and `y` are local (container-relative) coordinates.
+- `absX` and `absY` are world-space coordinates.
+- Root config must explicitly provide `area.x` and `area.y` (even `0, 0`) to define anchor origin.
+- `state.area.width` and `state.area.height` are measurements (`px` or `%`).
+- `state.area.px` and `state.area.py` are optional pivot axes and default to `s`.
+- `align.direction` controls child flow axis and defaults to `column`.
+- `order` controls sibling ordering (ascending; ties sorted by child key).
+- `absolute: true` means the node uses its own area position/sizing and ignores align-driven positioning/fill behavior.
+- `content` is optional structured payload for text or url content metadata (`{ type: 'text' | 'url', value: string }`).
+- For layout/rendering, read geometry from local getters (`x`, `y`, `width`, `height`, `area`) instead of raw state values.
+- Children are stored in `Map<string, BoxTreeState>`.
+- Child branches are passively created with Forestry wildcard branch params (`'*'`).
+
+## Zod Schemas
+
+The model is now Zod-first. Types are inferred from schemas and values are gated through parsing.
+
+Primary schemas in `/Users/davidedelhart/Documents/repos/forestry-pixi/packages/box/src/types.boxtree.ts`:
+
+- `AxisSchema`
+- `AlignKeywordSchema`
+- `AlignInputSchema`
+- `AreaPivotKeywordSchema`
+- `AreaPivotInputSchema`
+- `BoxAreaSchema`
+- `DirectionSchema`
+- `BoxAlignSchema`
+- `BoxConstrainSchema`
+- `BoxTreeNodeStateSchema`
+- `BoxTreeNodeConfigSchema`
+
+Primary schemas in `/Users/davidedelhart/Documents/repos/forestry-pixi/packages/box/src/types.ts`:
+
+- `SizeModeSchema`
+- `MeasurementConfigSchema`
+- `MeasurementSchema`
+- `PxValueSchema`
+- `AxisConstraintSchema`
+
+## Align Semantics
+
+Accepted input values:
+
+- `s` (`start`)
+- `c` (`center`)
+- `e` (`end`)
+- `f` (`fill`)
+- Aliases:
+- `<` -> `s`
+- `|` -> `c`
+- `>` -> `e`
+- `<>` -> `f`
+
+Readable constants are exported for config readability:
+
+```ts
+import { ALIGN } from '@wonderlandlabs-pixi-ux/box';
+
+const align = {
+  x: ALIGN.RIGHT,
+  y: ALIGN.MIDDLE,
+};
+```
+
+Meaning:
+
+- `s`: place child at parent start edge (+ local `area.x/y` offset).
+- `c`: center child in parent (+ local offset).
+- `e`: place child at parent end edge (- local offset).
+- `f`: size child to parent axis size, position like `s`.
+
+## Pivot Semantics (`area.px` / `area.py`)
+
+Accepted values:
+
+- Canonical: `s`, `c`, `e`
+- Aliases: `<`, `|`, `>`
+
+Meaning per axis:
+
+- `s`: anchor is at the start edge of the box on that axis.
+- `c`: anchor is at the center of the box on that axis.
+- `e`: anchor is at the end edge of the box on that axis.
+
+Resolved local position is:
+
+- `x = anchorX - pivotOffsetX`
+- `y = anchorY - pivotOffsetY`
+- `pivotOffsetX = 0 | width/2 | width` for `s | c | e`
+- `pivotOffsetY = 0 | height/2 | height` for `s | c | e`
+
+## Constrain Semantics
+
+`constrain.x` and `constrain.y` each support:
+
+- `min?: number` (px)
+- `max?: number` (px)
+
+### Impossible Ranges
+
+If both `min` and `max` resolve and `min > max`, only `min` is respected.
+
+## Geometry Resolution
+
+Width/height resolution per axis:
+
+1. Compute base size:
+- non-absolute + `f` with parent: base = parent axis size
+- otherwise: base = resolved local measurement from `state.area.width` / `state.area.height`
+2. Resolve axis `min`/`max` constraints.
+3. Apply constraints to base.
+4. If `min > max`, clamp only to `min`.
+
+Position resolution:
+
+- Root:
+- `anchorX = area.x`, `anchorY = area.y`
+- `x/y` are derived from `anchor - pivotOffset`
+- Non-root:
+- local anchor (when `absolute !== true`):
+- on flow axis (`x` for `row`, `y` for `column`): `flowOffset + area.x/y`
+- `s`/`f`: offset
+- `c`: `(parentSize - childSize)/2` + offset
+- `e`: `(parentSize - childSize)` - offset
+- local anchor (when `absolute === true`):
+- always `area.x` / `area.y` (align offsets are ignored)
+- local `x`/`y`:
+- `anchor - pivotOffset`
+- world `absX`/`absY`:
+- `parent.absX + x`, `parent.absY + y`
+
+## Practical Notes
+
+- Root nodes generally own explicit `area` dimensions.
+- `state.area.width` / `state.area.height` are measurements.
+- Numeric measurement input is valid and treated as px shorthand (`12` -> `{ mode: 'px', value: 12 }`).
+- `order` defaults to `0`; `absolute` defaults to `false`.
+- Child constrained sizing uses plain px min/max values.
+- `setWidthPx` / `setHeightPx` write measurement `{ mode: 'px', value }`.
+- `setWidthPercent` / `setHeightPercent` write measurement `{ mode: '%', value }`.
+- `resolveMeasurement(measurement, { axis, parentPixels })` resolves a full measurement object directly.
+
+## Config Example
+
+```json
+{
+  "id": "root",
+  "area": {
+    "x": 10,
+    "y": 20,
+    "width": { "mode": "px", "value": 400 },
+    "height": { "mode": "px", "value": 200 }
+  },
+  "align": { "x": "s", "y": "s", "direction": "column" },
+  "children": {
+    "bubble": {
+      "content": { "type": "text", "value": "Hello there" },
+      "area": {
+        "x": 5,
+        "y": 6,
+        "px": ">",
+        "py": "<",
+        "width": { "mode": "%", "value": 0.2 },
+        "height": { "mode": "px", "value": 30 }
+      },
+      "align": { "x": "e", "y": "c", "direction": "column" },
+      "constrain": {
+        "x": {
+          "min": 40
+        }
+      }
+    }
+  }
+}
+```
+
+Notes for this example:
+
+- `align` short forms are canonical (`s`, `c`, `e`, `f`).
+- `width` can be `%` and is resolved against parent width.
+- `constrain.x.min` is a px value and is applied directly.
+
+## Measurement Alias: `/`
+
+For config input, you can also provide ratio measurements:
+
+- `{ "mode": "/", "value": 2, "base": 3 }` means `2/3`, normalized to `{ "mode": "%", "value": 0.666... }`.
+- `base` is required for `/` measurements.
+- `base` must be `>= value`.
+- `base` must be `> 0`.
+
+Readable size mode constants are also exported:
+
+```ts
+import { MEASUREMENT_MODE as SIZE } from '@wonderlandlabs-pixi-ux/box';
+
+const area = {
+  width: { mode: SIZE.FRACTION, value: 2, base: 3 },
+  height: { mode: SIZE.PERCENT, value: 0.25 },
+};
+```

package/README.md

@@ -0,0 +1,68 @@
+# @wonderlandlabs-pixi-ux/box
+
+Tree-first box layout model built on Forestry branches.
+
+## Status
+
+- Public API is `BoxTree` + BoxTree measurement/alignment utilities.
+
+## Installation
+
+```bash
+yarn add @wonderlandlabs-pixi-ux/box
+```
+
+## Basic Usage
+
+```ts
+import { BoxTree, ALIGN, MEASUREMENT_MODE } from '@wonderlandlabs-pixi-ux/box';
+
+const root = new BoxTree({
+  value: {
+    id: 'root',
+    area: {
+      x: 0,
+      y: 0,
+      width: { mode: MEASUREMENT_MODE.PIXELS, value: 400 },
+      height: { mode: MEASUREMENT_MODE.PIXELS, value: 200 },
+      px: 's',
+      py: 's',
+    },
+    align: {
+      x: ALIGN.S,
+      y: ALIGN.S,
+      direction: 'column',
+    },
+  },
+});
+
+root.$set('children.card', {
+  id: 'card',
+  area: {
+    x: 12,
+    y: 8,
+    width: { mode: MEASUREMENT_MODE.PERCENT, value: 0.5 },
+    height: { mode: MEASUREMENT_MODE.PIXELS, value: 48 },
+    px: 's',
+    py: 's',
+  },
+  align: { x: 's', y: 's', direction: 'column' },
+});
+```
+
+## Public API
+
+- `BoxTree`
+- `createBoxTreeState`
+- `resolveTreeMeasurement`
+- `resolveMeasurementPx`
+- `resolveConstraintValuePx`
+- `applyAxisConstraints`
+- `boxTreeToPixi`
+- `boxTreeToSvg`
+- `pathToString`, `pathString`, `combinePaths`
+- `ALIGN`, `AXIS`, `MEASUREMENT_MODE`, `SIZE_MODE`, `SIZE_MODE_INPUT`
+
+## Data Model
+
+See `/Users/davidedelhart/Documents/repos/forestry-pixi/packages/box/README.BOX_VALUES.md` for the current schema, constraints, aliases, and examples.

package/dist/Box.stories.d.ts

@@ -0,0 +1,15 @@
+import type { Meta, StoryObj } from '@storybook/html';
+import type { Align } from './types';
+interface BoxArgs {
+    padding: number;
+    alignX: Align;
+    alignY: Align;
+    boxWidth: number;
+    boxHeight: number;
+    contentWidth: number;
+    contentHeight: number;
+}
+declare const meta: Meta<BoxArgs>;
+export default meta;
+type Story = StoryObj<BoxArgs>;
+export declare const AlignmentDemo: Story;

package/dist/Box.stories.js

@@ -0,0 +1,103 @@
+import { Application, Graphics } from 'pixi.js';
+import { BoxLeafStore } from './BoxLeafStore';
+const meta = {
+    title: 'Box/BoxLeafStore',
+    argTypes: {
+        padding: {
+            control: { type: 'range', min: 0, max: 50, step: 5 },
+            description: 'Uniform padding around content',
+        },
+        alignX: {
+            control: { type: 'select' },
+            options: ['start', 'center', 'end'],
+            description: 'Horizontal alignment of content',
+        },
+        alignY: {
+            control: { type: 'select' },
+            options: ['start', 'center', 'end'],
+            description: 'Vertical alignment of content',
+        },
+        boxWidth: {
+            control: { type: 'range', min: 100, max: 500, step: 10 },
+            description: 'Box width',
+        },
+        boxHeight: {
+            control: { type: 'range', min: 100, max: 400, step: 10 },
+            description: 'Box height',
+        },
+        contentWidth: {
+            control: { type: 'range', min: 20, max: 200, step: 10 },
+            description: 'Content box width',
+        },
+        contentHeight: {
+            control: { type: 'range', min: 20, max: 200, step: 10 },
+            description: 'Content box height',
+        },
+    },
+    args: {
+        padding: 20,
+        alignX: 'center',
+        alignY: 'center',
+        boxWidth: 300,
+        boxHeight: 200,
+        contentWidth: 80,
+        contentHeight: 60,
+    },
+};
+export default meta;
+export const AlignmentDemo = {
+    render: (args) => {
+        const wrapper = document.createElement('div');
+        wrapper.style.width = '100%';
+        wrapper.style.height = '600px';
+        wrapper.style.position = 'relative';
+        let boxStore;
+        const app = new Application();
+        app.init({
+            width: 800,
+            height: 600,
+            backgroundColor: 0x1a1a2e,
+            antialias: true,
+        }).then(() => {
+            wrapper.appendChild(app.canvas);
+            // Create the box store with new config format
+            boxStore = new BoxLeafStore({
+                id: 'demo-box',
+                x: 250,
+                y: 200,
+                xDef: { size: args.boxWidth, align: args.alignX, sizeMode: 'px' },
+                yDef: { size: args.boxHeight, align: args.alignY, sizeMode: 'px' },
+                padding: {
+                    top: args.padding,
+                    right: args.padding,
+                    bottom: args.padding,
+                    left: args.padding,
+                },
+                style: {
+                    fill: {
+                        color: { r: 0.2, g: 0.3, b: 0.5 },
+                        alpha: 1,
+                    },
+                    stroke: {
+                        color: { r: 0.4, g: 0.5, b: 0.8 },
+                        alpha: 1,
+                        width: 2,
+                    },
+                    borderRadius: 8,
+                },
+            }, app);
+            // Create content graphics
+            const contentBox = new Graphics({ label: 'content-box' });
+            contentBox.roundRect(0, 0, args.contentWidth, args.contentHeight, 4);
+            contentBox.fill({ color: 0xff6b6b, alpha: 0.9 });
+            contentBox.stroke({ color: 0xffffff, alpha: 0.5, width: 1 });
+            // Set content on the leaf store
+            boxStore.setContent(contentBox);
+            // Add box to stage
+            app.stage.addChild(boxStore.container);
+            // Trigger initial render
+            boxStore.markDirty();
+        });
+        return wrapper;
+    },
+};

package/dist/BoxLeafStore.d.ts

@@ -0,0 +1,7 @@
+import { Application, type ContainerOptions, type Graphics, type Sprite, type Text, type Container } from 'pixi.js';
+import { BoxStore } from './BoxStore';
+import type { BaseBoxConfig, BoxProps } from './types';
+export declare class BoxLeafStore extends BoxStore {
+    constructor(config: BaseBoxConfig, app: Application, boxProps?: BoxProps, rootProps?: ContainerOptions);
+    setContent(content: Graphics | Sprite | Text | Container | null): void;
+}

package/dist/BoxLeafStore.js

@@ -0,0 +1,9 @@
+import { BoxStore } from './BoxStore';
+export class BoxLeafStore extends BoxStore {
+    constructor(config, app, boxProps, rootProps) {
+        super({ ...config, kind: 'leaf' }, app, boxProps, rootProps);
+    }
+    setContent(content) {
+        super.setContent(content);
+    }
+}

package/dist/BoxListStore.d.ts

@@ -0,0 +1,7 @@
+import { Application, type ContainerOptions } from 'pixi.js';
+import { BoxStore } from './BoxStore';
+import type { BaseBoxConfig, BoxProps } from './types';
+export declare class BoxListStore extends BoxStore {
+    constructor(config: BaseBoxConfig, app: Application, boxProps?: BoxProps, rootProps?: ContainerOptions);
+    addChild(child: BaseBoxConfig | BoxStore): BoxStore;
+}

package/dist/BoxListStore.js

@@ -0,0 +1,10 @@
+import { BoxStore } from './BoxStore';
+export class BoxListStore extends BoxStore {
+    constructor(config, app, boxProps, rootProps) {
+        super({ ...config, kind: 'list' }, app, boxProps, rootProps);
+    }
+    addChild(child) {
+        const nextConfig = child instanceof BoxStore ? child.toConfig() : child;
+        return super.addChild(nextConfig);
+    }
+}

package/dist/BoxStore.d.ts

@@ -0,0 +1,56 @@
+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;
+}