@pretty-chitty/core 1.1.1

package/src/library/utilities/LayoutHelper.ts

@@ -0,0 +1,586 @@
+import { Chit } from "../game/Chit";
+
+export type PanelLayoutResult = {
+  w: number;
+  h: number;
+  x: number;
+  y: number;
+  id?: string;
+  chit: Chit | Chit[];
+};
+
+export type LayoutDirection =
+  | "horizontal"
+  | "vertical"
+  | "optimize"
+  | "optimizePreferVertical"
+  | "optimizePreferHorizontal"
+  | "optimizeGrid";
+
+//
+// Input parameters
+//
+export interface PanelNode {
+  chit: Chit;
+  minWidth: number;
+  minHeight: number;
+  order?: number;
+}
+export interface ContainerNode {
+  direction: LayoutDirection;
+  splits: LayoutNode[];
+  collapseOrder?: number;
+  reversedIfVertical?: boolean;
+  reversedIfHorizontal?: boolean;
+}
+export interface CollapsedNode {
+  panels: PanelNode[];
+  minWidth: number;
+  minHeight: number;
+}
+export type LayoutNode = PanelNode | ContainerNode | CollapsedNode;
+
+//
+// Interim concrete panel nodes
+//
+type ConcreteDirection = "horizontal" | "vertical";
+
+interface ConcretePanelNode extends PanelNode {
+  width: number;
+  height: number;
+}
+interface ConcreteContainerNode {
+  width: number;
+  height: number;
+  direction: ConcreteDirection;
+  splits: ConcreteLayoutNode[];
+  collapseOrder?: number;
+}
+interface ConcreteCollapsedNode extends CollapsedNode {
+  width: number;
+  height: number;
+}
+type ConcreteLayoutNode = ConcretePanelNode | ConcreteContainerNode | ConcreteCollapsedNode;
+
+// Type guard helpers
+function isPanelNode(node: LayoutNode | ConcreteLayoutNode): node is PanelNode | ConcretePanelNode {
+  return "chit" in node;
+}
+
+function isCollapsedNode(node: LayoutNode | ConcreteLayoutNode): node is CollapsedNode | ConcreteCollapsedNode {
+  return "panels" in node;
+}
+
+function isContainerNode(node: LayoutNode | ConcreteLayoutNode): node is ContainerNode | ConcreteContainerNode {
+  return "splits" in node;
+}
+
+/**
+ * Recursively fixes nodes where minWidth/minHeight exceed available dimensions
+ */
+function fixInvalidNodeDimensions(tree: LayoutNode, availableWidth: number, availableHeight: number): LayoutNode {
+  if (isPanelNode(tree)) {
+    // Fix panel node dimensions if they exceed available space
+    return {
+      ...tree,
+      minWidth: Math.min(tree.minWidth, availableWidth),
+      minHeight: Math.min(tree.minHeight, availableHeight),
+    };
+  }
+
+  if (isCollapsedNode(tree)) {
+    // Fix collapsed node dimensions if they exceed available space
+    return {
+      ...tree,
+      minWidth: Math.min(tree.minWidth, availableWidth),
+      minHeight: Math.min(tree.minHeight, availableHeight),
+    };
+  }
+
+  const container = tree as ContainerNode;
+  return {
+    ...container,
+    splits: container.splits.map((split) => fixInvalidNodeDimensions(split, availableWidth, availableHeight)),
+  };
+}
+
+/**
+ * Main entry point: creates layout from tree specification
+ */
+export function createLayoutFromTree(
+  tree: LayoutNode,
+  availableWidth: number,
+  availableHeight: number,
+): PanelLayoutResult[] {
+  // Step 0: Fix invalid nodes in tree
+  const fixedTree = fixInvalidNodeDimensions(tree, availableWidth, availableHeight);
+
+  // Step 1: Build valid LayoutNode tree (with collapses applied)
+  const validTree = buildValidTree(fixedTree, availableWidth, availableHeight);
+
+  const rebalancedTree = rebalanceTree(validTree);
+
+  // Step 2: Convert the valid tree to PanelLayoutResult[]
+  const res = flattenTreeToResults(rebalancedTree, 0, 0, availableWidth, availableHeight);
+
+  return res;
+}
+
+function rebalanceTree(tree: ConcreteLayoutNode): ConcreteLayoutNode {
+  if (isPanelNode(tree) || isCollapsedNode(tree)) {
+    return tree;
+  }
+  if (tree.direction === "horizontal") {
+    return createHorizontalLayout(tree, tree.width, tree.height);
+  } else if (tree.direction === "vertical") {
+    return createVerticalLayout(tree, tree.width, tree.height);
+  } else return tree;
+}
+
+/**
+ * Builds a valid LayoutNode tree by applying collapses until everything fits
+ * Returns a NEW tree - does not modify the input
+ */
+function buildValidTree(tree: LayoutNode, width: number, height: number): ConcreteLayoutNode {
+  if (width === 0) {
+    width = 1;
+  }
+  if (height === 0) {
+    height = 1;
+  }
+
+  // Step 1: Attempt to layout - resolves all optimize* into concrete horizontal/vertical/grid
+  const concreteTree = createConcreteLayout(tree, width, height);
+
+  // Step 2: Check if the concrete layout has ANY violations
+  const hasViolations = checkConcreteViolations(concreteTree);
+
+  // If no violations, the original tree is valid!
+  if (!hasViolations) {
+    return concreteTree;
+  }
+
+  // Step 3: Scan ENTIRE tree for the container with smallest collapseOrder
+  const toCollapse = findSmallestCollapseOrder(concreteTree);
+
+  if (!toCollapse) {
+    return concreteTree;
+  }
+
+  // Step 4: Collapse that container to create NEW tree
+  const newTree = collapseContainer(tree, toCollapse.collapseOrder!);
+
+  // Step 5: Recursively build valid tree from the new tree
+  return buildValidTree(newTree, width, height);
+}
+
+function createHorizontalLayout(node: ContainerNode, width: number, height: number): ConcreteLayoutNode {
+  const widths = node.splits.map((split) => getMinWidth(split));
+  const totalUsedWidth = widths.reduce((sum, w) => sum + w, 0);
+  const scale = width / totalUsedWidth;
+  const splits = node.splits.map((split, i) => createConcreteLayout(split, widths[i] * scale, height));
+
+  if (node.reversedIfHorizontal) {
+    splits.reverse();
+  }
+
+  return {
+    width,
+    height,
+    collapseOrder: node.collapseOrder,
+    direction: "horizontal",
+    splits,
+  };
+}
+
+function createVerticalLayout(node: ContainerNode, width: number, height: number): ConcreteLayoutNode {
+  const heights = node.splits.map((split) => getMinHeight(split));
+  const totalUsedHeight = heights.reduce((sum, h) => sum + h, 0);
+  const scale = height / totalUsedHeight;
+  const splits = node.splits.map((split, i) => createConcreteLayout(split, width, heights[i] * scale));
+
+  if (node.reversedIfVertical) {
+    splits.reverse();
+  }
+
+  return {
+    collapseOrder: node.collapseOrder,
+    direction: "vertical",
+    splits,
+    width,
+    height,
+  };
+}
+
+/**
+ * Attempts to layout the tree - resolves all optimize* directions into concrete layouts
+ * Returns a ConcreteLayoutNode tree
+ */
+function createConcreteLayout(node: LayoutNode, width: number, height: number): ConcreteLayoutNode {
+  if (isPanelNode(node)) {
+    return {
+      ...node,
+      width,
+      height,
+    };
+  }
+
+  if (isCollapsedNode(node)) {
+    return {
+      ...node,
+      width,
+      height,
+    };
+  }
+
+  const container = node as ContainerNode;
+
+  // general "optimize"
+  if (container.direction === "optimize") {
+    const horizontalLayout = createHorizontalLayout(container, width, height);
+    const verticalLayout = createVerticalLayout(container, width, height);
+
+    const horizontalIsOkay = !checkConcreteViolations(horizontalLayout);
+    const verticalIsOkay = !checkConcreteViolations(verticalLayout);
+
+    if (horizontalIsOkay && verticalIsOkay) {
+      if (width >= height) {
+        return horizontalLayout;
+      } else {
+        return verticalLayout;
+      }
+    } else if (horizontalIsOkay) {
+      return horizontalLayout;
+    } else if (verticalIsOkay) {
+      return verticalLayout;
+    } else {
+      return horizontalLayout;
+    }
+  }
+  // "optimize" with a preference
+  else if (container.direction === "optimizePreferVertical" || container.direction === "optimizePreferHorizontal") {
+    const horizontalLayout = createHorizontalLayout(container, width, height);
+    const verticalLayout = createVerticalLayout(container, width, height);
+
+    const horizontalIsOkay = !checkConcreteViolations(horizontalLayout);
+    const verticalIsOkay = !checkConcreteViolations(verticalLayout);
+
+    if (
+      container.direction === "optimizePreferHorizontal" &&
+      (horizontalIsOkay || (!verticalIsOkay && !horizontalIsOkay))
+    ) {
+      return horizontalLayout;
+    } else if (
+      container.direction === "optimizePreferVertical" &&
+      (verticalIsOkay || (!verticalIsOkay && !horizontalIsOkay))
+    ) {
+      return verticalLayout;
+    } else if (verticalIsOkay) {
+      return verticalLayout;
+    } else if (horizontalIsOkay) {
+      return horizontalLayout;
+    } else {
+      return verticalLayout; // fallback, shouldn't happen.
+    }
+  }
+  // grid layout
+  else if (container.direction === "optimizeGrid") {
+    // Grid is just an optimization - resolve to actual horizontal or vertical layout
+    const bestConfig = findBestGridConfig(container.splits, width, height);
+
+    const result: ConcreteContainerNode[] = [];
+    for (let row = 0; row < bestConfig.rows; row++) {
+      const rowInfo: ConcreteContainerNode = {
+        direction: "horizontal",
+        width: width,
+        height: height / bestConfig.rows,
+        splits: container.splits
+          .slice(row * bestConfig.cols, (row + 1) * bestConfig.cols)
+          .map((d) => createConcreteLayout(d, width / bestConfig.cols, height / bestConfig.rows)),
+      };
+      result.push(rowInfo);
+    }
+
+    return {
+      direction: "vertical",
+      width,
+      height,
+      splits: result,
+    };
+  } else if (container.direction === "horizontal") {
+    return createHorizontalLayout(container, width, height);
+  } else {
+    return createVerticalLayout(container, width, height);
+  }
+}
+
+/**
+ * Check if a concrete layout has violations
+ */
+function checkConcreteViolations(node: ConcreteLayoutNode): boolean {
+  if (isPanelNode(node)) {
+    return node.minWidth > node.width || node.minHeight > node.height;
+  }
+  if (isCollapsedNode(node)) {
+    return node.minWidth > node.width || node.minHeight > node.height;
+  }
+  for (let i = 0; i < node.splits.length; i++) {
+    if (checkConcreteViolations(node.splits[i])) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Scans entire tree for the container with smallest collapseOrder
+ */
+function findSmallestCollapseOrder(node: ConcreteLayoutNode): ContainerNode | null {
+  if (isPanelNode(node) || isCollapsedNode(node)) {
+    return null;
+  }
+  // no point in collapsing anything that thinks it is all good
+  if (!checkConcreteViolations(node) && node.collapseOrder !== undefined) {
+    return null;
+  }
+
+  const container = node as ConcreteContainerNode;
+  let smallest: ContainerNode | null = container.collapseOrder !== undefined ? container : null;
+
+  for (const split of container.splits) {
+    const childSmallest = findSmallestCollapseOrder(split);
+    if (childSmallest) {
+      const childOrder = childSmallest.collapseOrder ?? Number.MAX_SAFE_INTEGER;
+      const currentOrder = smallest?.collapseOrder ?? Number.MAX_SAFE_INTEGER;
+
+      if (childOrder < currentOrder) {
+        smallest = childSmallest;
+      }
+    }
+  }
+
+  return smallest;
+}
+
+/**
+ * Flattens a valid ConcreteLayoutNode tree into PanelLayoutResult[]
+ */
+function flattenTreeToResults(
+  node: ConcreteLayoutNode,
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+): PanelLayoutResult[] {
+  // Handle leaf node (panel or panel array)
+  if (isPanelNode(node)) {
+    return [
+      {
+        x,
+        y,
+        w,
+        h,
+        id: node.chit.id ?? "no_id",
+        chit: node.chit,
+      },
+    ];
+  }
+
+  // Handle collapsed node (array of panels as chits)
+  if (isCollapsedNode(node)) {
+    return [
+      {
+        x,
+        y,
+        w,
+        h,
+        id: node.panels[0].chit.id ?? "no_id",
+        chit: node.panels.map((p) => p.chit),
+      },
+    ];
+  }
+
+  const container = node as ConcreteContainerNode;
+
+  // Handle horizontal split
+  if (container.direction === "horizontal") {
+    let currentX = x;
+    return container.splits
+      .map((split) => {
+        const splitWidth = (split.width / container.width) * w;
+        const result = flattenTreeToResults(split, currentX, y, splitWidth, h);
+        currentX += splitWidth;
+        return result;
+      })
+      .flat();
+  }
+
+  // Handle vertical split
+  let currentY = y;
+  return container.splits
+    .map((split) => {
+      const splitHeight = (split.height / container.height) * h;
+      const result = flattenTreeToResults(split, x, currentY, w, splitHeight);
+      currentY += splitHeight;
+      return result;
+    })
+    .flat();
+}
+
+function findBestGridConfig(splits: LayoutNode[], width: number, height: number): { rows: number; cols: number } {
+  if (splits.length <= 1) {
+    return { rows: 1, cols: 1 };
+  }
+
+  const cellWidth = getMinWidth(splits[0]);
+  const cellHeight = getMinHeight(splits[0]);
+
+  let cols = Math.ceil(width / cellWidth);
+  let rows = Math.ceil(height / cellHeight);
+  let lastValidCols = cols;
+  let lastValidRows = rows;
+
+  // eslint-disable-next-line no-constant-condition
+  while (splits.length > 0) {
+    let canReduceRows = rows > 1 && cols * (rows - 1) >= splits.length;
+    let canReduceCols = cols > 1 && (cols - 1) * rows >= splits.length;
+
+    if (!canReduceRows && !canReduceCols) {
+      break;
+    }
+
+    if (canReduceRows && canReduceCols) {
+      const cellAspectRatio = cellWidth / cellHeight;
+
+      // Prefer reducing the dimension that brings cellAspectRatio closer to aspectRatio
+      const reduceRowsScore = Math.abs(cellAspectRatio - cellWidth / (height / (rows - 1)));
+      const reduceColsScore = Math.abs(cellAspectRatio - width / (cols - 1) / cellHeight);
+
+      if (reduceRowsScore < reduceColsScore) {
+        canReduceRows = false;
+      } else {
+        canReduceCols = false;
+      }
+    }
+
+    if (canReduceRows) {
+      rows--;
+      lastValidCols = cols;
+      lastValidRows = rows;
+    } else if (canReduceCols) {
+      cols--;
+      lastValidCols = cols;
+      lastValidRows = rows;
+    }
+  }
+
+  return {
+    rows: lastValidRows,
+    cols: lastValidCols,
+  };
+}
+
+/**
+ * Collapse a container - replaces it with a CollapsedNode (tabs) and removes collapseOrder
+ */
+function collapseContainer(tree: LayoutNode, targetCollapseOrder: number): LayoutNode {
+  if (isContainerNode(tree) && tree.collapseOrder === targetCollapseOrder) {
+    // This is the container to collapse
+    const panels: PanelNode[] = [];
+    collectPanels(tree, panels);
+
+    // Sort panels by collapseOrder (stable sort)
+    // Panels without collapseOrder go to the end
+    const sortedPanels = panels.flat().sort((a, b) => {
+      const orderA = a.order ?? Number.MAX_SAFE_INTEGER;
+      const orderB = b.order ?? Number.MAX_SAFE_INTEGER;
+      return orderA - orderB;
+    });
+
+    const maxWidth = Math.max(...sortedPanels.map((s) => s.minWidth));
+    const maxHeight = Math.max(...sortedPanels.map((s) => s.minHeight));
+
+    // Return CollapsedNode with array of single chits (each panel becomes a single chit)
+    return {
+      panels: sortedPanels,
+      minWidth: maxWidth,
+      minHeight: maxHeight,
+    };
+  }
+
+  if (isPanelNode(tree) || isCollapsedNode(tree)) {
+    return tree;
+  }
+
+  // Recurse through container
+  const container = tree as ContainerNode;
+  return {
+    ...container,
+    splits: container.splits.map((split) => collapseContainer(split, targetCollapseOrder)),
+  };
+}
+
+function collectPanels(node: LayoutNode, panels: PanelNode[]): void {
+  if (isPanelNode(node)) {
+    panels.push(node);
+  } else if (isCollapsedNode(node)) {
+    panels.push(...node.panels);
+  } else {
+    for (const split of (node as ContainerNode).splits) {
+      collectPanels(split, panels);
+    }
+  }
+}
+
+/**
+ * Get minWidth for a node (without resolving - for estimating)
+ */
+function getMinWidth(node: LayoutNode | ConcreteLayoutNode): number {
+  if (isPanelNode(node)) {
+    return node.minWidth;
+  }
+
+  if (isCollapsedNode(node)) {
+    return node.minWidth;
+  }
+
+  const container = node as ContainerNode | ConcreteContainerNode;
+
+  // ConcreteLayoutNode - direction is already resolved
+  if (container.direction === "horizontal" || container.direction === "optimizePreferHorizontal") {
+    return container.splits.reduce((sum, split) => sum + getMinWidth(split), 0);
+  }
+
+  // LayoutNode - need to estimate based on direction type
+  if (container.direction === "optimizeGrid") {
+    const w = getMinWidth(container.splits[0]);
+    return Math.sqrt(container.splits.length) * w;
+  }
+
+  return Math.max(...container.splits.map((split) => getMinWidth(split)));
+}
+
+function getMinHeight(node: LayoutNode | ConcreteLayoutNode): number {
+  if (isPanelNode(node)) {
+    return node.minHeight;
+  }
+
+  if (isCollapsedNode(node)) {
+    return node.minHeight;
+  }
+
+  const container = node as ContainerNode | ConcreteContainerNode;
+
+  // ConcreteLayoutNode - direction is already resolved
+  if (container.direction === "vertical" || container.direction === "optimizePreferVertical") {
+    return container.splits.reduce((sum, split) => sum + getMinHeight(split), 0);
+  }
+
+  // LayoutNode - need to estimate based on direction type
+  if (container.direction === "optimizeGrid") {
+    const h = getMinHeight(container.splits[0]);
+    return Math.sqrt(container.splits.length) * h;
+  }
+
+  return Math.max(...container.splits.map((split) => getMinHeight(split)));
+}

package/src/library/utilities/ObjectWithProps.ts

@@ -0,0 +1,52 @@
+import "reflect-metadata";
+import nextTick from "next-tick";
+import { checkAnnotation, NonEditable } from "./Annotations";
+
+const CATCH_ALL = "[[null]]";
+export class ObjectWithProps {
+  /** @internal */
+  public get props(): string[] {
+    return Object.keys(this).filter((key) => !checkAnnotation(this, key, NonEditable));
+  }
+  /** @internal */
+  @NonEditable private _cbs: { [key: string]: Array<() => void> } = {};
+
+  /** @internal */
+  @NonEditable private _keysThatChanged = new Set<string>();
+
+  public set(cb: (chit: this) => void): this {
+    cb(this);
+    return this;
+  }
+
+  /** @internal */
+  public notifyChange(key: string): void {
+    if (this._keysThatChanged.size === 0) {
+      nextTick(() => {
+        this._keysThatChanged.forEach((key) => this._cbs[key]?.forEach((cb) => cb()));
+        this._cbs[CATCH_ALL]?.forEach((cb) => cb());
+        this._keysThatChanged.clear();
+      });
+    }
+    this._keysThatChanged.add(key);
+  }
+
+  /** @internal */
+  public onChange(key: string | null, cb: () => void): () => void {
+    const keysToUse = (key ?? CATCH_ALL).split(/\s/g);
+
+    keysToUse.forEach((keyToUse) => {
+      let arr = this._cbs[keyToUse];
+      if (arr === undefined) {
+        this._cbs[keyToUse] = arr = [];
+      }
+      arr.push(cb);
+    });
+
+    return () => {
+      keysToUse.forEach((keyToUse) => {
+        this._cbs[keyToUse] = this._cbs[keyToUse].filter((c) => c !== cb);
+      });
+    };
+  }
+}

package/src/library/utilities/OutlineCanvas.tsx

@@ -0,0 +1,45 @@
+import React from "react";
+import { Raw } from "./CanvasStack/ReactCanvas";
+import { ParameterizedCanvas } from "./ParameterizedCanvas";
+
+export class OutlineCanvas extends ParameterizedCanvas {
+  radius = 6;
+  lineWidth = 6;
+  innerLineWidth = 2;
+  outerColor = "#f00";
+  innerColor = "#ff0";
+  width = 100;
+  height = 100;
+  render() {
+    return (
+      <Raw
+        cb={(ctx, x, y, w, h) => {
+          ctx.imageSmoothingEnabled = false;
+          ctx.strokeStyle = this.outerColor;
+          ctx.lineWidth = this.lineWidth;
+          ctx.beginPath();
+          ctx.roundRect(
+            x + this.lineWidth / 2,
+            y + this.lineWidth / 2,
+            w - this.lineWidth,
+            h - this.lineWidth,
+            this.radius,
+          );
+          ctx.stroke();
+
+          ctx.strokeStyle = this.innerColor;
+          ctx.lineWidth = this.innerLineWidth;
+          ctx.beginPath();
+          ctx.roundRect(
+            x + this.lineWidth / 2,
+            y + this.lineWidth / 2,
+            w - this.lineWidth,
+            h - this.lineWidth,
+            this.radius,
+          );
+          ctx.stroke();
+        }}
+      />
+    );
+  }
+}