machinalayout 0.1.0 → 0.2.0

package/docs/responsive-variants.md

@@ -0,0 +1,54 @@
+# Responsive variants (M4b)
+
+Responsive variants let a single flat `LayoutRow[]` express row-local overrides selected by `rootRect` dimensions.
+
+## Purpose
+
+- Keep responsive behavior explicit and deterministic.
+- Keep selection resolver-owned and driven only by caller-provided root geometry.
+- Avoid userland row-array branching for common desktop/tablet/mobile style differences.
+
+## Authoring model
+
+Add `variants` to a `LayoutRow`. Each variant has a `when` condition plus optional override fields.
+
+```ts
+{
+  id: "sidebar",
+  parent: "root",
+  frame: { kind: "anchor", left: 0, top: 64, bottom: 0, width: 280 },
+  variants: [
+    {
+      when: { maxWidth: 800 },
+      frame: { kind: "anchor", left: 0, right: 0, top: 64, height: 56 },
+      slot: "mobileNav",
+    },
+    {
+      when: {},
+      slot: "desktopSidebar",
+    },
+  ],
+}
+```
+
+## Selection semantics
+
+- `resolveLayoutRows(rows, rootRect)` calls `selectLayoutRowsForRoot(rows, rootRect)` first.
+- Conditions are inclusive (`>= min*`, `<= max*`).
+- First matching variant wins.
+- `when: {}` matches all root rects and can be used as a fallback.
+- Effective rows are fresh copies and do not include `variants`.
+
+## Phase separation
+
+- `compileLayoutRows(rows)` directly uses base row values only.
+- Variants are an authoring-time input feature, not part of compiled or resolved node types.
+
+## Constraints and non-goals
+
+M4b variants can override row metadata (`frame`, `arrange`, `offset`, `z`, `view`, `slot`, `debugLabel`) but cannot:
+
+- change graph identity (`id`, `parent`, `order`),
+- add/remove rows,
+- use DOM measurement,
+- use CSS media query semantics.

package/docs/vue-adapter.md

@@ -0,0 +1,55 @@
+# Vue adapter (`machinalayout/vue`)
+
+`MachinaVueView` renders a `ResolvedLayoutDocument` into DOM wrappers plus Vue view components.
+
+- Import path: `import { MachinaVueView } from "machinalayout/vue";`
+- Peer dependency: `vue` (`>=3.4 <4`).
+- Machina layout stays record-shaped (`LayoutRow[]` -> resolved rectangles) across frameworks.
+
+## Shared model boundary
+
+MachinaVueView uses Vue render functions internally so application code can stay record-shaped: layout rows describe geometry, and Vue components render inside the resolved rectangles.
+
+You do not need to write `h()` calls, template layout loops, or directive ceremony to place boxes. Users can keep normal Vue SFC/template authoring for component internals, reactivity, and lifecycle.
+
+## Basic usage
+
+```vue
+<script setup lang="ts">
+import { MachinaVueView } from "machinalayout/vue";
+
+const views = { Panel };
+</script>
+
+<template>
+  <MachinaVueView :layout="layout" :views="views" :view-data="viewData" :node-data="nodeData" />
+</template>
+```
+
+## Stable view registry and data channels
+
+Keep stable component references in `views`. Pass reactive/computed dynamic values through `viewData` and `nodeData`.
+
+Avoid rebuilding component definitions as data carriers.
+
+## Props note
+
+To avoid conflicts with Vue fallthrough attrs, root/node styling props are:
+
+- `rootClass`, `rootStyle`
+- `nodeClass`, `nodeStyle`
+
+## Supported
+
+- `view ?? slot` lookup
+- `viewData` / `nodeData`
+- layer/z sorting (`layer z`, then `node z`, then sibling order)
+- DOM containment/content-visibility policy
+- debug mode
+- parent-local coordinate normalization
+
+## Not included
+
+- this package only renders layout boxes; text rendering is provided separately by `machinalayout/text/vue`
+- portals/reparenting
+- router/state abstraction layers

package/docs/vue-text-renderer.md

@@ -0,0 +1,55 @@
+# Vue MachinaText renderer
+
+`MachinaVueTextView` renders MachinaText content into DOM elements inside an already-owned rectangle.
+
+## Import
+
+```ts
+import { MachinaVueTextView } from "machinalayout/text/vue";
+```
+
+## Peer dependency
+
+- `vue` (Vue 3)
+
+## Accepted `text` inputs
+
+- `string`
+- `MachinaTextSource`
+- `MachinaTextSpec`
+- `MachinaTextDocument`
+
+## Supported rendering
+
+- paragraphs (`p`)
+- bullet lists (`ul`/`li`)
+- inline strong/emphasis/code/link
+
+## Policy support
+
+- `variant`
+- `wrap`
+- `overflow`
+- `align`
+- `leading`
+- `blockGap`
+- `listGap`
+- `valign`
+
+## Notes
+
+- Uses Vue `h()` internally so app code does not need render-function loops for the text AST.
+- Supports `rootClass`/`rootStyle` plus `linkClass`/`linkStyle` and `codeClass`/`codeStyle` hooks.
+- Link handling uses `onLinkClick` only (no routing dispatch integration).
+
+## Difference from React DOM text renderer
+
+- Vue component API (`rootClass`/`rootStyle`) instead of React `className`/`style` prop names.
+- Same parser/document model and text policy behavior.
+
+## Non-goals
+
+- text measurement
+- intrinsic sizing
+- routing behavior
+- editor/caret/selection behavior

package/package.json

@@ -1,25 +1,39 @@
 {
   "name": "machinalayout",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "scripts": {
     "typecheck": "tsc --noEmit",
     "build": "npm run typecheck && tsup --config tsup.config.ts --tsconfig tsconfig.build.json",
-    "test": "vitest run"
+    "test": "vitest run",
+    "format": "biome format --write .",
+    "format:check": "biome format .",
+    "lint": "biome lint .",
+    "check": "biome check ."
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.4.15",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
+    "@types/react-test-renderer": "^19.1.0",
+    "@vue/test-utils": "^2.4.6",
     "jsdom": "^29.1.1",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "react-native": "^0.82.0",
+    "react-test-renderer": "^19.2.6",
+    "tsup": "^8.5.1",
     "typescript": "^5.6.3",
     "vitest": "^2.1.8",
-    "tsup": "^8.5.1"
+    "vue": "^3.5.22"
   },
   "peerDependencies": {
     "react": ">=18 <20",
-    "react-dom": ">=18 <20"
+    "react-dom": ">=18 <20",
+    "react-native": ">=0.72 <1",
+    "vue": ">=3.4 <4"
   },
   "description": "Machine-native layout and text primitives for deterministic app UI records.",
   "license": "MIT",
@@ -48,6 +62,39 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js"
+    },
+    "./text": {
+      "types": "./dist/text/index.d.ts",
+      "import": "./dist/text/index.js"
+    },
+    "./text/react": {
+      "types": "./dist/text/react/index.d.ts",
+      "import": "./dist/text/react/index.js"
+    },
+    "./package.json": "./package.json",
+    "./react-native": {
+      "types": "./dist/react-native/index.d.ts",
+      "import": "./dist/react-native/index.js"
+    },
+    "./vue": {
+      "types": "./dist/vue/index.d.ts",
+      "import": "./dist/vue/index.js"
+    },
+    "./text/react-native": {
+      "types": "./dist/text/react-native/index.d.ts",
+      "import": "./dist/text/react-native/index.js"
+    },
+    "./text/vue": {
+      "types": "./dist/text/vue/index.d.ts",
+      "import": "./dist/text/vue/index.js"
+    },
+    "./dispatch": {
+      "types": "./dist/dispatch/index.d.ts",
+      "import": "./dist/dispatch/index.js"
     }
   },
   "files": [
@@ -56,5 +103,13 @@
     "LICENSE",
     "docs"
   ],
-  "sideEffects": false
+  "sideEffects": false,
+  "peerDependenciesMeta": {
+    "react-native": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  }
 }