windcraft-editor 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 Swapnil Jadhav
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Third-party code included in this repository is licensed under its own terms; see THIRD_PARTY_LICENSES.md.

package/README.md

@@ -1,44 +1,77 @@
-# @windcraft/editor
+<p align="center">
+  <a href="https://github.com/Tolaj/windcraft"><img src="https://raw.githubusercontent.com/Tolaj/windcraft/main/docs/media/logo-card.png" alt="Windcraft" width="320"></a>
+</p>
 
-The Windcraft visual editor (HTML + Tailwind): canvas, layers, Properties panel, code panel and pages. It has no backend of its own: the page that mounts it gives it a **host** that loads and saves.
+# windcraft-editor
 
-```js
-import { mountEditor } from "@windcraft/editor";
+A visual editor for **HTML + Tailwind** that you can put in any web page. Select, drag and style like Figma, and every change is real Tailwind code. No backend, no build step.
 
-await mountEditor(document.getElementById("root"), {
-    host,   // saving, projects, AI and the address: see design/host.js
-    data,   // the design to open: { id, title, htmlCode, ... }
-});
+## Try it in one file
+
+Save this as `index.html`, run `npx serve` next to it, and open the address it prints:
+
+```html
+<div id="root"></div>
+<script type="module">
+  import { startEditor } from "https://unpkg.com/windcraft-editor/editor/index.js";
+  startEditor(document.getElementById("root"), {
+    html: '<h1 class="p-10 text-4xl font-bold">Hello</h1>',
+  });
+</script>
+```
+
+That is all. Designs are saved in the browser (localStorage).
+
+## Use it from npm
+
+```bash
+npm install windcraft-editor
+```
+
+Serve the `node_modules/windcraft-editor` folder as static files (for example `app.use("/windcraft", express.static("node_modules/windcraft-editor"))`) and import from it:
+
+```js
+import { startEditor } from "/windcraft/editor/index.js";
+startEditor(document.getElementById("root"), { html: "<h1>Hello</h1>" });
 ```
 
-| Piece | Where |
+### `startEditor(root, options)`
+
+| Option | What it does |
 |---|---|
-| What the app must provide | `design/host.js` (the `Host` type) |
-| A host with no backend (localStorage) | `demo/demo.js` |
-| Run the demo | `npm run demo`, then open http://localhost:4000/editor/demo/ |
-| Windcraft's own host | `src/public/js/app-host.js` |
+| `html` | The HTML a new design starts with |
+| `title` | The design's name (default `My design`) |
+| `key` | The localStorage key, so two editors on one site do not share designs |
+| `theme` | `{ brand: "#e11d48", gray: "stone", font: "Poppins", radius: "xl" }` |
 
-The page must map `@windcraft/core/` and `@windcraft/editor/` to where they are served (an import map, as in `demo/index.html`, or a bundler). `mountEditor` loads Tailwind's play CDN (v3) unless you pass `tailwind: false`. One editor per page; it takes over the page's size, keys and zoom.
+## Save to your own server
 
-The AI panel and "Generate" need `host.generate`; without a working one they show its error.
+`startEditor` keeps designs in the browser. To load and save somewhere else, use `mountEditor` and give it a **host**: a few functions (`createComponent`, `updateComponent`, ...) that talk to your backend. The list is in [`editor/design/host.js`](design/host.js), and [`local-host.js`](local-host.js) is a complete one to copy.
 
-## Embedding in a container
+```js
+import { mountEditor } from "/windcraft/editor/index.js";
 
-`embedEditor` puts the editor in an element of your page, isolated in an iframe (its own keys, zoom and styles), so several can share a page and it fills whatever size you give it. Leave out the parts you don't need with `ui`; keep the code box and the details form in your own page.
+await mountEditor(document.getElementById("root"), {
+    host,                              // your load and save functions
+    data: { id, title, htmlCode },     // the design to open
+});
+```
+
+## Put it inside a part of a page
+
+`startEditor` and `mountEditor` take over the whole page. To place the editor in one box, use `embedEditor`. It runs in an iframe, so several can share a page.
 
 ```js
-import { embedEditor } from "@windcraft/editor";
+import { embedEditor } from "/windcraft/editor/index.js";
 
-const ed = embedEditor(el, {
-    host,                                    // saving, as above
-    data: { htmlCode },                      // what to open
-    ui: { panels: false, nav: false, tools: ["move", "hand", "interact", "frame", "shape", "text", "add"] },
-    onDetails: (fields) => showMyForm(fields), // the first save of a new design needs a name: you ask, then call saveDetails
+const ed = embedEditor(document.getElementById("box"), {
+    host,
+    data: { htmlCode: "<h1>Hello</h1>" },
+    ui: { panels: false, nav: false },   // hide parts you do not need
 });
-ed.onChange(({ html, dirty, status, source }) => {});  // source: "host" (your setHtml), "editor" (a change there), "status" (save state only)
-ed.setHtml(html);  ed.getHtml();  ed.isDirty();  ed.save();
-await ed.saveDetails({ title, category, description, tags, isPublished, useAsReference, project });
-ed.destroy();
+
+ed.onChange(({ html }) => console.log(html));
+ed.setHtml("<p>New</p>");   // ed.getHtml(), ed.isDirty(), ed.save(), ed.destroy()
 ```
 
 | `ui` | Effect |
@@ -47,4 +80,9 @@ ed.destroy();
 | `nav: false` | no Back, page list or project |
 | `tools: [...]` | only these tools (`move hand interact frame shape text add`); `null` keeps all |
 
-The iframe loads `embed.html` (next to `embed.js`; pass `src` if you serve it elsewhere). It needs the same import map as any editor page. Run `npm run demo` and open `/editor/demo/embed.html` for a working example: a code box and the editor following each other.
+## Notes
+
+- The editor loads Tailwind's play CDN (v3) unless you pass `tailwind: false` because your page already has it.
+- One full-page editor per page. It takes over the page's size and keyboard.
+- Source, demo and issues: https://github.com/Tolaj/windcraft
+- MIT licensed.

package/{design → editor/design}/classes-section.js

@@ -3,7 +3,7 @@
 // They act through `actions`, which the editor provides:
 //   setClassesText(text) · setStyle(css | null) · setAttribute(name, value | null)
 import { html, useState, useEffect, useRef } from "../vendor/preact-htm.js";
-import { parseToken } from "@windcraft/core/class-groups.js";
+import { parseToken } from "../../core/class-groups.js";
 import { TextInput } from "./controls.js";
 
 /** "color: red; margin: 0" -> [["color","red"],["margin","0"]] */

package/{design → editor/design}/controls.js

@@ -3,7 +3,7 @@
 // and a colour field. Each keeps what is being typed in its own state and reports changes through callbacks; none reads the
 // page or the editor's state. Their classes are the ones canvas.handlebars styles.
 import { html, useState, useRef } from "../vendor/preact-htm.js";
-import { HUES, SHADES, SPECIAL_COLORS } from "@windcraft/core/class-groups.js";
+import { HUES, SHADES, SPECIAL_COLORS } from "../../core/class-groups.js";
 
 /**
  * What a typed-in field needs: it shows `value` until it is focused, keeps what is typed in its own state (a redraw with the

package/{design → editor/design}/design-tab.js

@@ -3,7 +3,7 @@
 // frame's breakpoint) through useUi() and act through `actions`, which the editor provides:
 //   select(path) · move(dir) · duplicate() · remove() · setTag(tag) · setBreakpoint(bp) · setState(st) · setText(text) · setAttr(name, value)
 import { html, useState } from "../vendor/preact-htm.js";
-import { BREAKPOINT_WIDTH, parseToken } from "@windcraft/core/class-groups.js";
+import { BREAKPOINT_WIDTH, parseToken } from "../../core/class-groups.js";
 import { TAG_KINDS, variant } from "./panel-model.js";
 import { useUi } from "./panel-state.js";
 import { TextInput, TextArea, SelectInput, Field } from "./controls.js";

package/{design → editor/design}/editor/designs.js

@@ -1,7 +1,7 @@
 import { parseComponentSource, buildPreviewDocument } from "../../playground/component-source.js";
 import { host } from "../host.js";
-import { normalizeGroup } from "@windcraft/core/pages.js";
-import { GAP_X } from "@windcraft/core/board-layout.js";
+import { normalizeGroup } from "../../../core/pages.js";
+import { GAP_X } from "../../../core/board-layout.js";
 import { DEVICES } from "../float-toolbar.js";
 import { $, S, collapsed, data, esc, frame, model, send } from "./base.js";
 import { MIN_H, applyView, canvas, fitTo, heightOfDoc, layout, pageGroupOf, placePills, positions, view, widthOf } from "./plane.js";

package/{design → editor/design}/editor/inspector.js

@@ -1,9 +1,9 @@
 import { panelStore, togglePalette, toggleSection } from "../panel-state.js";
-import { BREAKPOINT_WIDTH, setGroup, getGroup, GROUPS, parseToken } from "@windcraft/core/class-groups.js";
+import { BREAKPOINT_WIDTH, setGroup, getGroup, GROUPS, parseToken } from "../../../core/class-groups.js";
 import { renderPanel } from "../panel.js";
 import { inspectorView, variant, val, srcOf, modeFor } from "../panel-model.js";
 import { checkTags } from "../code-view.js";
-import { groupOf, variantOf, twShown, hasScale, twValue, fromPx, tokenFor } from "@windcraft/core/prop-tailwind.js";
+import { groupOf, variantOf, twShown, hasScale, twValue, fromPx, tokenFor } from "../../../core/prop-tailwind.js";
 import { normalizeValue } from "../css-props.js";
 import { host } from "../host.js";
 import { $, S, data, model, send } from "./base.js";

package/{design → editor/design}/editor/plane.js

@@ -1,4 +1,4 @@
-import { computeLayout } from "@windcraft/core/board-layout.js";
+import { computeLayout } from "../../../core/board-layout.js";
 import { $, DEFAULT_W, S, data, frame, send } from "./base.js";
 import { docs, wraps } from "./designs.js";
 import { placeFloat, renderFloat, renderFrameSel } from "./frame-handles.js";

package/{design → editor/design}/figma-sections.js

@@ -5,8 +5,8 @@
 //   setProp · setProps · resetProp · setGeom · freePosition · align · arrange · group · ungroup · autoLayout · sizeItMyself
 import { html, useState } from "../vendor/preact-htm.js";
 import { srcOf, shownOf, ownsValue, styled, val, variant, modeFor, PRESETS, OPTS } from "./panel-model.js";
-import { parseToken } from "@windcraft/core/class-groups.js";
-import { tokenFor } from "@windcraft/core/prop-tailwind.js";
+import { parseToken } from "../../core/class-groups.js";
+import { tokenFor } from "../../core/prop-tailwind.js";
 import { useUi } from "./panel-state.js";
 import { TextInput } from "./controls.js";
 

package/{design → editor/design}/panel-model.js

@@ -1,8 +1,8 @@
 // What the Properties panel draws from: the data tables behind its controls (suggestions, options, tags), small selectors
 // that read the selection and the panel's state (panel-state.js), and inspectorView, which says what the panel shows. The
 // components themselves are in panel.js, design-tab.js, figma-sections.js, style-sections.js, prop-sections.js and classes-section.js.
-import { HUES, SHADES, SPECIAL_COLORS, STEPS, SIZES, MAX_W, GROUPS, getGroup, parseToken } from "@windcraft/core/class-groups.js";
-import { twShown } from "@windcraft/core/prop-tailwind.js";
+import { HUES, SHADES, SPECIAL_COLORS, STEPS, SIZES, MAX_W, GROUPS, getGroup, parseToken } from "../../core/class-groups.js";
+import { twShown } from "../../core/prop-tailwind.js";
 import { panelStore } from "./panel-state.js";
 
 const esc = (s) => String(s ?? "").replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));

package/{design → editor/design}/style-sections.js

@@ -11,8 +11,8 @@ import { useUi } from "./panel-state.js";
 import { TextInput, ColorInput } from "./controls.js";
 import { GroupColor } from "./group-controls.js";
 import { I, IconBtn, NumField, FSection, Sub, PropField, PropSelect, TwField, TwSelect, num, owns, has, off, comp, srcKind, srcNote, atVariant } from "./figma-sections.js";
-import { twShown } from "@windcraft/core/prop-tailwind.js";
-import { brandScale, normalizeTheme } from "@windcraft/core/theme.js";
+import { twShown } from "../../core/prop-tailwind.js";
+import { brandScale, normalizeTheme } from "../../core/theme.js";
 import { data } from "./editor/base.js";
 import { PropRow } from "./prop-sections.js";
 

package/{index.js → editor/index.js}

@@ -1,14 +1,15 @@
-// @windcraft/editor: the visual editor as a package.
+// windcraft-editor: the visual editor as a package.
 //
-//   import { mountEditor } from "@windcraft/editor";
+//   import { mountEditor } from "windcraft-editor";
 //   await mountEditor(document.getElementById("root"), { host, data });
 //
 // `host` is what the editor needs from the app around it (design/host.js lists it): saving, projects, the AI and the page address.
-// `data` is the design to open (below). The page must map "@windcraft/core/" and "@windcraft/editor/" to where those packages are
-// served (an import map, or a bundler does it). One editor per page: it takes over the page's size and keyboard.
+// `data` is the design to open (below). The page must serve this package's files and, for a plain browser page, map "windcraft-editor"
+// to editor/index.js with an import map (a bundler does that itself). One editor per page: it takes over the page's size and keyboard.
 import { setHost } from "./design/host.js";
 import { config } from "./design/config.js";
 import { editorHtml } from "./template.js";
+import { localHost, savedDesign } from "./local-host.js";
 
 const here = (path) => new URL(path, import.meta.url).href;
 const TAILWIND = "https://cdn.tailwindcss.com";
@@ -60,3 +61,21 @@ export async function mountEditor(root, { host, data = {}, back = null, tailwind
     return (await import("./design/editor/api.js")).api;
 }
 export { embedEditor } from "./embed.js";
+
+/**
+ * The quickest way in: the editor with nothing to set up. Designs are saved in this browser (localStorage).
+ * @param {HTMLElement} root
+ * @param {{ html?: string, title?: string, key?: string, theme?: object }} [options]
+ *     html: what a new design starts with; title: its name; key: the localStorage key (use different ones for different editors);
+ *     theme: { brand, gray, font, radius }
+ */
+export async function startEditor(root, { html = "", title = "My design", key = "windcraft", theme } = {}) {
+    const categories = [{ group: "Designs", items: [{ slug: "design", name: "Design" }] }];
+    const saved = savedDesign(key);
+    await mountEditor(root, {
+        host: localHost(key),
+        data: saved
+            ? { id: saved._id, title: saved.title, htmlCode: saved.htmlCode, version: saved.version, category: saved.category || "design", description: saved.description, tags: String(saved.tags || "").split(",").filter(Boolean), categories }
+            : { title, htmlCode: html, category: "design", description: "", theme, categories },
+    });
+}

package/editor/local-host.js

@@ -0,0 +1,39 @@
+// A host with no backend: designs are kept in this browser's localStorage. startEditor (index.js) uses it, and so does the demo.
+
+const read = (key) => { try { return JSON.parse(localStorage.getItem(key) || "{}"); } catch { return {}; } };
+const write = (key, all) => localStorage.setItem(key, JSON.stringify(all));
+const id = () => Math.random().toString(36).slice(2, 10);
+
+/** @param {string} key  the localStorage key the designs are kept under */
+export function localHost(key = "windcraft") {
+    /** @type {import("./design/host.js").Host} */
+    const host = {
+        async createComponent(fields) {
+            const all = read(key), _id = id();
+            all[_id] = { ...fields, _id, version: 1 };
+            write(key, all);
+            return all[_id];
+        },
+        async updateComponent(docId, fields) {
+            const all = read(key);
+            if (!all[docId]) throw new Error("That design isn't saved here");
+            const next = { ...all[docId], ...fields };
+            if (fields.htmlCode !== undefined && fields.htmlCode !== all[docId].htmlCode) next.version = (all[docId].version || 1) + 1;
+            all[docId] = next;
+            write(key, all);
+            return next;
+        },
+        async deleteComponent(docId) { const all = read(key); delete all[docId]; write(key, all); },
+        async createProject(name) { return { id: id(), name }; },
+        async saveLayout() {},
+        saveLayoutOnExit() {},
+        showDesign(docId) { history.replaceState({}, "", docId ? `?design=${docId}` : location.pathname); },
+        openDesign(docId) { location.href = `?design=${docId}`; },
+    };
+    return host;
+}
+
+/** The design the address (?design=...) points at, if it is saved here. */
+export function savedDesign(key = "windcraft") {
+    return read(key)[new URLSearchParams(location.search).get("design") || ""] || null;
+}

package/{playground → editor/playground}/component-source.js

@@ -1,4 +1,4 @@
-import { themeHead } from "@windcraft/core/theme.js";
+import { themeHead } from "../../core/theme.js";
 const TAILWIND_RE = /tailwindcss|@tailwindcss\/browser/i;
 
 const isTailwindScript = (s) => s.src && TAILWIND_RE.test(s.src);

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "windcraft-editor",
-    "version": "0.1.0",
-    "description": "Windcraft's visual HTML + Tailwind editor. Mount it in a page and give it a host that loads and saves designs. Includes @windcraft/core.",
+    "version": "0.2.0",
+    "description": "Windcraft's visual HTML + Tailwind editor. Mount it in a page and give it a host that loads and saves designs.",
     "keywords": [
         "tailwind",
         "tailwindcss",
@@ -23,29 +23,18 @@
     "bugs": {
         "url": "https://github.com/Tolaj/windcraft/issues"
     },
-    "main": "index.js",
+    "main": "editor/index.js",
     "exports": {
-        ".": "./index.js",
+        ".": "./editor/index.js",
         "./*": "./*"
     },
     "files": [
-        "index.js",
-        "embed.js",
-        "embed.html",
-        "embed-frame.js",
-        "template.js",
-        "styles.css",
-        "design",
-        "playground",
-        "vendor",
+        "editor",
         "core",
+        "LICENSE",
         "README.md"
     ],
     "publishConfig": {
         "access": "public"
-    },
-    "scripts": {
-        "prepack": "node scripts/bundle-core.mjs",
-        "postpack": "node scripts/bundle-core.mjs clean"
     }
 }