@layoutit/polycss-react 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +148 -123
  2. package/dist/index.cjs +2802 -1831
  3. package/dist/index.d.cts +100 -28
  4. package/dist/index.d.ts +100 -28
  5. package/dist/index.js +2747 -1723
  6. package/package.json +2 -2
package/README.md CHANGED
@@ -1,174 +1,199 @@
1
- > **Status: pre-1.0. APIs may still change before a stable 1.0 release.**
1
+ # PolyCSS
2
2
 
3
- # @layoutit/polycss-react
3
+ A CSS polygon mesh library. A 3D engine for the DOM. Renders OBJ/MTL, GLB and VOX as real HTML elements transformed with CSS `matrix3d(...)`. Supports colors, textures, lighting, shadows, shapes and animations. Works with React, Vue or plain JavaScript.
4
4
 
5
- Declarative React components for CSS-based polygon mesh rendering. Loads OBJ, glTF, GLB, and MagicaVoxel `.vox` files; renders each polygon as a real DOM element (atlas-backed `<i>` for both textured and flat-color faces) positioned with `transform: matrix3d(...)`. No WebGL, no canvas-as-scene.
5
+ Visit [polycss.com](https://polycss.com) for docs and model examples.
6
6
 
7
- ## Install
7
+ <img width="1600" height="300" alt="PolyCSS primitives banner" src="https://github.com/user-attachments/assets/b05e2204-9323-4f83-8d1b-01ea0dd000db" />
8
+
9
+ ## Installation
8
10
 
9
11
  ```bash
12
+
13
+ # Vanilla
14
+ npm install @layoutit/polycss
15
+
16
+ # React
10
17
  npm install @layoutit/polycss-react
18
+
19
+ # Vue
20
+ npm install @layoutit/polycss-vue
21
+
11
22
  ```
12
23
 
13
- Requires React 18 or 19 as a peer dependency.
14
24
 
15
- ## Quickstart
25
+ You can also load PolyCSS directly from a CDN. Here is a minimal custom-element scene:
26
+
27
+ ```html
28
+ <script type="module" src="https://esm.sh/@layoutit/polycss/elements"></script>
29
+
30
+ <poly-camera rot-x="65" rot-y="45">
31
+ <poly-scene>
32
+ <poly-orbit-controls drag wheel></poly-orbit-controls>
33
+ <poly-box size="100" color="#ffd166"></poly-box>
34
+ </poly-scene>
35
+ </poly-camera>
36
+ ```
37
+
38
+ <img width="2500" height="1145" alt="PolyCSS intro" src="https://github.com/user-attachments/assets/0e5df0d8-04a8-4e50-8e3a-1097a96ce42f" />
39
+
40
+ ## Framework Components
41
+
42
+ React and Vue expose the same component model. `<PolyCamera>` owns the viewpoint, `<PolyScene>` owns lighting and atlas options, and `<PolyMesh>` loads or receives polygon data.
16
43
 
17
44
  ```tsx
18
- import { PolyCamera, PolyScene, PolyMesh } from "@layoutit/polycss-react";
45
+ import { PolyCamera, PolyScene, PolyOrbitControls, PolyMesh } from "@layoutit/polycss-react";
19
46
 
20
- export function App() {
47
+ export default function App() {
21
48
  return (
22
- <PolyCamera rotX={65} rotY={45} perspective={1000}>
23
- <PolyScene>
24
- <PolyMesh src="/cottage.glb" />
49
+ <PolyCamera rotX={65} rotY={45}>
50
+ <PolyScene textureLighting="dynamic">
51
+ <PolyOrbitControls drag wheel />
52
+ <PolyMesh src="/gallery/obj/cottage.obj" mtl="/gallery/obj/cottage.mtl" />
25
53
  </PolyScene>
26
54
  </PolyCamera>
27
55
  );
28
56
  }
29
57
  ```
30
58
 
31
- Every polygon in the mesh is a real DOM element: inspect it in DevTools, style it with CSS, attach event handlers.
59
+ ## API Reference
32
60
 
33
- ## Component reference
61
+ ### PolyCamera
34
62
 
35
- ### `<PolyScene>`
63
+ - `rotX`, `rotY` control the orbit angle in degrees.
64
+ - `zoom` scales the projected scene.
65
+ - `target` pans the camera target in world coordinates.
66
+ - `distance` adds dolly pull-back.
67
+ - `PolyCamera` is the orthographic default. Use `PolyPerspectiveCamera` when you want perspective depth.
36
68
 
37
- Root of every React polycss render tree. Renders polygons and meshes inside a `<PolyCamera>` context, and owns scene-level lighting and atlas options.
69
+ ### PolyScene
38
70
 
39
- | Prop | Type | Default | Description |
40
- |---|---|---|---|
41
- | `directionalLight` | `PolyDirectionalLight` | None | Directional light config |
42
- | `ambientLight` | `PolyAmbientLight` | None | Ambient light config |
43
- | `textureLighting` | `"baked" \| "dynamic"` | `"baked"` | Texture lighting mode |
44
- | `textureQuality` | `number \| "auto"` | `"auto"` | Atlas bitmap budget and compositor sprite size |
45
- | `polygons` | `Polygon[]` | None | Static polygon array (composes with `children`) |
46
- | `children` | `ReactNode` | None | `<PolyMesh>`, `<Poly>`, and/or `<PolyOrbitControls>` |
71
+ - `polygons` renders a static `Polygon[]` directly.
72
+ - `directionalLight` and `ambientLight` control scene lighting.
73
+ - `textureLighting` chooses `"baked"` or `"dynamic"`.
74
+ - `textureQuality` controls atlas raster budget.
75
+ - Solid seam bleed is automatic on detected shared solid edges.
76
+ - `strategies` can disable selected render strategies for diagnostics.
77
+ - `autoCenter` rotates around the rendered mesh bounds instead of world origin.
47
78
 
48
- For pointer drag, wheel zoom, and autorotate, mount `<PolyOrbitControls>` (or `<PolyMapControls>` for pan-first map-style input) inside `<PolyCamera>`: it receives the camera context. Mirrors Three.js's split between camera state and input.
79
+ ### PolyMesh
49
80
 
50
- ### `<PolyMesh>`
81
+ - `src` loads `.obj`, `.gltf`, `.glb`, or `.vox` files.
82
+ - `mtl` loads companion OBJ materials.
83
+ - `polygons` accepts pre-parsed geometry.
84
+ - `position`, `scale`, and `rotation` transform the mesh wrapper.
85
+ - `autoCenter` shifts the mesh bbox center to local origin.
86
+ - `meshResolution` chooses `"lossy"` (default) or `"lossless"` optimization.
87
+ - `castShadow` emits CSS-projected shadows in dynamic lighting mode.
51
88
 
52
- Loads a mesh from a URL and renders its polygons. Manages blob-URL lifecycle automatically.
89
+ ### Controls
53
90
 
54
- | Prop | Type | Description |
55
- |---|---|---|
56
- | `src` | `string` | URL to `.obj`, `.glb`, `.gltf`, or `.vox` |
57
- | `polygons` | `Polygon[]` | Pre-parsed polygons (alternative to `src`) |
58
- | `position` | `Vec3` | `[x, y, z]` offset in scene space |
59
- | `scale` | `number \| Vec3` | Uniform or per-axis scale |
60
- | `rotation` | `Vec3` | Euler angles in degrees `[x, y, z]` |
61
- | `textureQuality` | `number \| "auto"` | Atlas bitmap budget and compositor sprite size |
62
- | `autoCenter` | `boolean` | Shift mesh so its bbox center is at origin |
63
- | `mtl` | `string` | Companion `.mtl` URL for OBJ models |
64
- | `parseOptions` | `UseMeshOptions` | Forwarded to `loadMesh`; `meshResolution` defaults to `"lossy"` |
65
- | `fallback` | `ReactNode` | Rendered while loading |
66
- | `errorFallback` | `(error: Error) => ReactNode` | Rendered on parse failure |
67
- | `children` | `((polygon, index) => ReactNode) \| ReactNode` | Per-polygon render prop override, or static children mounted inside the mesh wrapper |
91
+ - `<PolyOrbitControls>` adds drag orbit, shift-drag pan, wheel zoom, and optional auto-rotate.
92
+ - `<PolyMapControls>` uses pan-first map-style input.
93
+ - `<PolyFirstPersonControls>` provides keyboard and pointer-look navigation.
94
+ - `<PolyTransformControls>` adds translate/rotate gizmos for selected mesh handles.
68
95
 
69
- ### `<Poly>`
96
+ ### Polygon Data Model
70
97
 
71
- Single polygon. The atomic primitive: renders one atlas-backed `<i>` for UV-textured and flat-color faces. Forwards all standard DOM props.
98
+ Each polygon describes one renderable face:
72
99
 
73
- | Prop | Type | Description |
74
- |---|---|---|
75
- | `vertices` | `Vec3[]` | Required: 3+ `[x, y, z]` points |
76
- | `color` | `string` | CSS color; used when no texture is set |
77
- | `texture` | `string` | Image URL for UV-mapped rendering |
78
- | `uvs` | `Vec2[]` | UV coordinates, one per vertex |
79
- | `data` | `Record<string, string \| number \| boolean>` | Reflected as `data-*` DOM attributes |
80
- | `position` | `Vec3` | Local offset |
81
- | `scale` | `number \| Vec3` | Scale |
82
- | `rotation` | `Vec3` | Euler rotation in degrees |
83
- | `textureQuality` | `number \| "auto"` | Atlas bitmap budget and compositor sprite size |
84
- | `onClick` | `MouseEventHandler` | Standard DOM event handler |
85
- | `onMouseEnter` | `MouseEventHandler` | |
86
- | `className` | `string` | CSS class |
87
- | `style` | `CSSProperties` | Inline style |
88
- | `aria-label` | `string` | ARIA label |
100
+ ```ts
101
+ const polygons = [
102
+ {
103
+ vertices: [[0, 0, 0], [60, 0, 0], [0, 60, 0]],
104
+ color: "#f97316",
105
+ },
106
+ {
107
+ vertices: [[0, 0, 0], [60, 0, 0], [60, 60, 0], [0, 60, 0]],
108
+ texture: "/texture.png",
109
+ uvs: [[0, 0], [1, 0], [1, 1], [0, 1]],
110
+ },
111
+ ];
112
+ ```
89
113
 
90
- ### `<PolyCamera>`
114
+ Render polygons directly when you need per-face DOM events or custom styling:
91
115
 
92
- Camera wrapper for perspective, rotation, zoom, target, and dolly distance. React scenes must render inside `<PolyCamera>` (or `<PolyPerspectiveCamera>` / `<PolyOrthographicCamera>`) so controls and scenes share camera state.
116
+ ```tsx
117
+ <PolyCamera>
118
+ <PolyScene>
119
+ {polygons.map((polygon, index) => (
120
+ <Poly
121
+ key={index}
122
+ {...polygon}
123
+ onClick={() => console.log("clicked polygon", index)}
124
+ className="my-polygon"
125
+ />
126
+ ))}
127
+ </PolyScene>
128
+ </PolyCamera>
129
+ ```
93
130
 
94
- ### Hooks
131
+ ## Loading Mesh Files
95
132
 
96
- | Hook | Description |
97
- |---|---|
98
- | `usePolyCamera(options)` | Internal camera integration hook (used by `<PolyCamera>`) |
99
- | `usePolySceneContext(polygons, options)` | Lower-level hook for building custom scene wrappers |
100
- | `usePolyMesh(src, options?)` | Fetch + parse a mesh. Returns `{ polygons, loading, error, warnings, dispose }`. Manages blob-URL lifecycle: safe across rapid src changes and unmounts. |
133
+ Use `loadMesh()` to parse supported model formats:
101
134
 
102
- ### Utility
103
-
104
- | Export | Description |
105
- |---|---|
106
- | `injectPolyBaseStyles(doc?)` | Inject polycss base CSS into the document. Idempotent. Called automatically by `<PolyScene>`; manual call only needed for custom scene hosts. Polygon defaults are scoped to `.polycss-scene`. |
135
+ ```ts
136
+ import { createPolyCamera, createPolyScene, loadMesh } from "@layoutit/polycss";
107
137
 
108
- ## Re-exports from `@layoutit/polycss-core`
138
+ const host = document.getElementById("polycss")!;
139
+ const camera = createPolyCamera({ rotX: 65, rotY: 45 });
140
+ const scene = createPolyScene(host, { camera });
109
141
 
110
- All types and core functions are re-exported for convenience, so you never need to add `@layoutit/polycss-core` to your dependencies:
142
+ const mesh = await loadMesh("https://polycss.com/gallery/obj/cottage.obj", {
143
+ mtlUrl: "https://polycss.com/gallery/obj/cottage.mtl",
144
+ });
111
145
 
112
- ```ts
113
- import type { Polygon, Vec2, Vec3, PolyDirectionalLight, PolyAmbientLight, ParseResult } from "@layoutit/polycss-react";
114
- import { parseObj, parseGltf, parseVox, loadMesh, normalizePolygons, mergePolygons } from "@layoutit/polycss-react";
146
+ scene.add(mesh);
115
147
  ```
116
148
 
117
- ## Per-polygon interactivity example
149
+ Supported formats:
118
150
 
119
- ```tsx
120
- import { useState } from "react";
121
- import { PolyCamera, PolyScene, Poly } from "@layoutit/polycss-react";
122
- import type { Polygon } from "@layoutit/polycss-react";
151
+ - OBJ + MTL, including `map_Kd` textures and UV coordinates.
152
+ - glTF / GLB, including embedded images and `TEXCOORD_0`.
153
+ - MagicaVoxel `.vox`, with direct voxel fast paths when eligible.
154
+ - Generated primitives: box, plane, ring, sphere, torus, cylinder, cone, and Platonic solids.
123
155
 
124
- export function InteractiveMesh({ polygons }: { polygons: Polygon[] }) {
125
- const [hoveredId, setHoveredId] = useState<number | null>(null);
156
+ ## Performance
126
157
 
127
- return (
128
- <PolyCamera rotX={65} rotY={45}>
129
- <PolyScene>
130
- {polygons.map((p, i) => (
131
- <Poly
132
- key={i}
133
- {...p}
134
- onClick={() => alert(`clicked polygon ${i}`)}
135
- onMouseEnter={() => setHoveredId(i)}
136
- onMouseLeave={() => setHoveredId(null)}
137
- className={hoveredId === i ? "highlight" : ""}
138
- style={{ transition: "filter 0.2s" }}
139
- />
140
- ))}
141
- </PolyScene>
142
- </PolyCamera>
143
- );
144
- }
145
- ```
158
+ PolyCSS renders in the DOM, so performance is mostly determined by how many polygons are mounted and how much texture atlas area they consume. The renderer uses several CSS strategies so simple surfaces stay cheap and textured or irregular surfaces fall back to atlas slices.
146
159
 
147
- ```css
148
- .highlight { filter: brightness(1.5); }
149
- ```
160
+ - One visible polygon becomes one leaf DOM element.
161
+ - Flat rectangles and stable quads use solid CSS leaves.
162
+ - Textured polygons are packed into generated texture atlases.
163
+ - Dynamic lighting runs through CSS custom properties instead of per-frame JavaScript.
164
+ - Voxel-shaped meshes mount only camera-facing leaves when the mesh is eligible.
165
+ - `meshResolution: "lossy"` merges compatible polygons, then may spend a small split budget to repair high-risk seams.
150
166
 
151
- ## `usePolyMesh`: imperative loading
167
+ Renderer internals:
152
168
 
153
- ```tsx
154
- import { PolyCamera, PolyScene, Poly, usePolyMesh } from "@layoutit/polycss-react";
169
+ Each visible polygon is emitted as one leaf element; the renderer chooses the least expensive CSS primitive that can represent the polygon, then uses `matrix3d(...)` to place that primitive in 3D space.
155
170
 
156
- function Viewer() {
157
- const { polygons, loading, error } = usePolyMesh("/cottage.glb");
171
+ - `<b>` uses `background: currentColor` on a fixed box for solid rectangles and stable quads.
172
+ - `<u>` uses `corner-shape` for stable triangles and beveled-corner solids, with a `border-width` triangle fallback when needed.
173
+ - `<i>` clips solid polygons with `border-shape: polygon(...)` when the browser supports it.
174
+ - `<s>` maps a packed texture-atlas slice with `background-image`, and is the fallback for textured or unsupported shapes.
158
175
 
159
- if (loading) return <div>Loading…</div>;
160
- if (error) return <div>Error: {error.message}</div>;
176
+ ## Packages
161
177
 
162
- return (
163
- <PolyCamera>
164
- <PolyScene>
165
- {polygons.map((p, i) => <Poly key={i} {...p} />)}
166
- </PolyScene>
167
- </PolyCamera>
168
- );
169
- }
170
- ```
178
+ | Package | Description |
179
+ |---|---|
180
+ | `@layoutit/polycss-core` | Pure math, parsers, lighting, camera helpers, mesh optimization. Zero browser globals. |
181
+ | `@layoutit/polycss` | Vanilla custom elements and imperative `createPolyScene` API. |
182
+ | `@layoutit/polycss-react` | React components, hooks, controls, and core re-exports. |
183
+ | `@layoutit/polycss-vue` | Vue 3 components, composables, controls, and core re-exports. |
184
+
185
+ ## Made with PolyCSS
186
+
187
+ [Layoutit Voxels](https://voxels.layoutit.com)
188
+ -> A CSS Voxel editor
189
+
190
+ <img width="1000" height="600" alt="layoutit-voxels" src="https://polycss.com/layoutit-voxels.png" />
191
+
192
+ [Layoutit Terra](https://terra.layoutit.com)
193
+ -> A CSS Terrain Generator
194
+
195
+ <img width="1000" height="601" alt="layoutit-terra" src="https://polycss.com/layoutit-terra.png" />
171
196
 
172
- ## Docs
197
+ ## License
173
198
 
174
- Full documentation at [polycss.com](https://polycss.com).
199
+ MIT.