windcraft-editor 0.0.0-stage → 0.1.1

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,3 +1,54 @@
-# Temporary Holding Version
+# windcraft-editor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+```bash
+npm install windcraft-editor
+```
+
+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.
+
+```js
+import { mountEditor } from "windcraft-editor";
+
+await mountEditor(document.getElementById("root"), {
+    host,   // saving, projects, AI and the address: see design/host.js
+    data,   // the design to open: { id, title, htmlCode, ... }
+});
+```
+
+| Piece | Where |
+|---|---|
+| 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` |
+
+The package carries the Tailwind logic inside it (`core/`) and reaches it by relative paths, so there is nothing else to map. On a plain page map `windcraft-editor` to `<where you serve the package>/editor/index.js` with an import map; a bundler does that itself (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.
+
+The AI panel and "Generate" need `host.generate`; without a working one they show its error.
+
+## Embedding in a container
+
+`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.
+
+```js
+import { embedEditor } from "windcraft-editor";
+
+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
+});
+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();
+```
+
+| `ui` | Effect |
+|---|---|
+| `panels: false` | no Layers, Properties or Code panels |
+| `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.

package/core/board-layout.js

@@ -0,0 +1,71 @@
+// Where each design sits on a project's infinite plane. Shared by the project board and the editor.
+// Saved positions win. Everything else is laid out automatically: pages in a row, each page's sections stacked beneath it.
+// Pages that have a group ("Public site", "Customer area") get a row of their own per group, the rows one under the other in
+// the order the groups first appear; without groups there is one row, as there always was.
+export const GAP_X = 320;
+export const SECTION_GAP = 200;
+export const ROW_GAP = 360; // between the bottom of one group's row and the labels of the next
+export const PAGE_H = 900;
+export const SEC_H = 480;
+
+const LABEL_H = 40; // the name above each frame belongs to it
+const CLEAR = 60; // the least air between two frames
+
+/**
+ * items: [{ id, kind, parent, group, board }]. Returns { [id]: { x, y } }. A frame may be wider than frameW (widthOf).
+ * Nothing placed automatically lands on another frame: a spot that is taken (by a frame with a saved position, or one placed before)
+ * is moved past it, a page to the right and a section below. Saved positions are never moved.
+ */
+export function computeLayout(items, { frameW, heightOf, widthOf = () => frameW }) {
+    const pos = {};
+    const box = (it, p) => ({ x: p.x, y: p.y - LABEL_H, r: p.x + widthOf(it), b: p.y + heightOf(it) });
+    const taken = []; // the boxes of what has a place: the saved ones first, then each one placed
+    items.forEach((i) => { if (i.board) taken.push(box(i, i.board)); });
+    const hit = (a, b) => a.x < b.r + CLEAR && a.r + CLEAR > b.x && a.y < b.b + CLEAR && a.b + CLEAR > b.y;
+    /** The first spot from `p` that touches nothing, moving right (down: false) or down. */
+    const clear = (it, p, down) => {
+        let q = { ...p };
+        for (let n = 0; n < 400; n++) {
+            const me = box(it, q), other = taken.find((t) => hit(me, t));
+            if (!other) return q;
+            q = down ? { x: q.x, y: other.b + CLEAR + LABEL_H } : { x: other.r + CLEAR, y: q.y };
+        }
+        return q;
+    };
+    const place = (it, want, down) => {
+        const p = it.board ? { x: it.board.x, y: it.board.y } : clear(it, want, down);
+        if (!it.board) taken.push(box(it, p));
+        return p;
+    };
+    const pages = items.filter((i) => i.kind !== "section" || !items.some((p) => p.id === i.parent));
+    /** @type {{ group: string, pages: typeof pages }[]} */
+    const rows = [];
+    pages.forEach((p) => {
+        const group = p.group || "";
+        let row = rows.find((r) => r.group === group);
+        if (!row) rows.push((row = { group, pages: [] }));
+        row.pages.push(p);
+    });
+    let rowY = 0;
+    rows.forEach((row) => {
+        let nextX = 0;
+        // the lowest edge of this row, so the next row starts below it. A page moved by hand keeps its slot, its height included:
+        // dragging a page never moves another one (a row below doesn't move up when a tall page is picked up)
+        let bottom = rowY;
+        row.pages.forEach((p) => {
+            pos[p.id] = place(p, { x: nextX, y: rowY }, false);
+            nextX = (p.board ? nextX : pos[p.id].x) + widthOf(p) + GAP_X;
+            let y = pos[p.id].y + heightOf(p) + 260;
+            let slot = rowY + heightOf(p) + 260; // the same stack, as it stands in the slot
+            bottom = Math.max(bottom, rowY + heightOf(p));
+            items.filter((i) => i.kind === "section" && i.parent === p.id).forEach((s) => {
+                pos[s.id] = place(s, { x: pos[p.id].x, y }, true);
+                bottom = Math.max(bottom, slot + heightOf(s));
+                y = pos[s.id].y + heightOf(s) + SECTION_GAP;
+                slot += heightOf(s) + SECTION_GAP;
+            });
+        });
+        rowY = bottom + ROW_GAP;
+    });
+    return pos;
+}

package/core/class-groups.js

@@ -0,0 +1,210 @@
+// @ts-check
+// A registry of Tailwind utility groups. Each group is a set of mutually exclusive classes
+// (for example every font size). Controls read and write a group for a chosen variant
+// (breakpoint and state), e.g. "md:hover:".
+export const HUES = ["slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose", "brand"]; // brand: every project has its own scale (brand-50 to brand-950, see theme.js)
+export const SHADES = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950];
+export const SPECIAL_COLORS = ["black", "white", "transparent", "current"];
+
+export const STEPS = ["0", "px", "0.5", "1", "1.5", "2", "2.5", "3", "3.5", "4", "5", "6", "7", "8", "9", "10", "11", "12", "14", "16", "20", "24", "28", "32", "36", "40", "44", "48", "52", "56", "60", "64", "72", "80", "96"];
+export const SIZES = [...STEPS, "auto", "full", "screen", "min", "max", "fit", "1/2", "1/3", "2/3", "1/4", "3/4", "1/5", "2/5", "3/5", "4/5"];
+export const MAX_W = ["none", "xs", "sm", "md", "lg", "xl", "2xl", "3xl", "4xl", "5xl", "6xl", "7xl", "full", "prose", "screen-sm", "screen-md", "screen-lg", "screen-xl"];
+
+const STEP = "\\d+(?:\\.5)?|px";
+const SIZE = `${STEP}|auto|full|screen|min|max|fit|\\d+/\\d+`;
+const ARB = "\\[[^\\]]+\\]";
+const HUE_RE = HUES.join("|");
+const COLOR = `(?:(?:${HUE_RE})-\\d{2,3}|black|white|transparent|current|inherit|\\[(?:#|rgb|hsl|var)[^\\]]*\\])(?:/\\d+|/\\[[^\\]]+\\])?`;
+
+const normArb = (v) => {
+    v = String(v).trim();
+    if (/^\[.*\]$/.test(v)) return v;
+    if (/^-?\d*\.?\d+(px|rem|em|%|vh|vw|vmin|vmax|ch|deg|ms|s|fr)$/.test(v) || /^(calc|var|min|max|clamp)\(/.test(v)) return `[${v}]`;
+    return v;
+};
+const normColor = (v) => {
+    v = String(v).trim();
+    if (/^(#[0-9a-fA-F]{3,8}|rgba?\(|hsla?\()/.test(v)) return `[${v.replace(/\s+/g, "_")}]`;
+    return v;
+};
+
+// prefix-value utility (w-4, -mt-2, gap-x-[10px])
+const P = (prefix, vals, { neg = false, arb = true } = {}) => ({
+    re: new RegExp(`^(${neg ? "-?" : ""})${prefix}-(${vals}${arb ? `|${ARB}` : ""})$`),
+    read: (m) => (m[1] || "") + m[2],
+    build: (v) => {
+        let sign = "";
+        v = String(v).trim();
+        if (neg && v.startsWith("-")) { sign = "-"; v = v.slice(1); }
+        return `${sign}${prefix}-${normArb(v)}`;
+    },
+});
+// exact words (display: flex)
+const E = (alts) => ({ re: new RegExp(`^(${alts})$`), read: (m) => m[1], build: (v) => v });
+// color utility with optional /opacity
+const C = (prefix) => ({
+    re: new RegExp(`^${prefix}-(${COLOR})$`),
+    read: (m) => m[1],
+    build: (v) => `${prefix}-${normColor(v)}`,
+});
+
+export const GROUPS = {
+    // layout
+    display: E("block|inline-block|inline|flex|inline-flex|grid|inline-grid|hidden|contents|table|flow-root"),
+    position: E("static|fixed|absolute|relative|sticky"),
+    overflow: E("overflow-(?:auto|hidden|visible|scroll|clip)"),
+    overflowX: E("overflow-x-(?:auto|hidden|visible|scroll|clip)"),
+    overflowY: E("overflow-y-(?:auto|hidden|visible|scroll|clip)"),
+    z: P("z", "\\d+|auto", { neg: true }),
+    visibility: E("visible|invisible"),
+    // flex and grid
+    flexDir: E("flex-(?:row|col|row-reverse|col-reverse)"),
+    flexWrap: E("flex-(?:wrap|nowrap|wrap-reverse)"),
+    justify: E("justify-(?:start|center|end|between|around|evenly|stretch|normal)"),
+    items: E("items-(?:start|center|end|stretch|baseline)"),
+    content: E("content-(?:start|center|end|between|around|evenly|stretch)"),
+    self: E("self-(?:auto|start|center|end|stretch|baseline)"),
+    grow: E("grow|grow-0"),
+    shrink: E("shrink|shrink-0"),
+    flexNum: E("flex-(?:1|auto|initial|none)"),
+    gap: P("gap", STEP),
+    gapX: P("gap-x", STEP),
+    gapY: P("gap-y", STEP),
+    gridCols: P("grid-cols", "\\d+|none|subgrid"),
+    gridRows: P("grid-rows", "\\d+|none|subgrid"),
+    colSpan: P("col-span", "\\d+|full"),
+    rowSpan: P("row-span", "\\d+|full"),
+    order: P("order", "\\d+|first|last|none", { neg: true }),
+    // size
+    w: P("w", SIZE),
+    h: P("h", SIZE),
+    minW: P("min-w", `${STEP}|full|min|max|fit`),
+    maxW: P("max-w", `${STEP}|${MAX_W.join("|")}|fit|min|max`),
+    minH: P("min-h", `${STEP}|full|screen|min|max|fit`),
+    maxH: P("max-h", `${STEP}|full|screen|min|max|fit|none`),
+    aspect: P("aspect", "auto|square|video"),
+    objectFit: E("object-(?:contain|cover|fill|none|scale-down)"),
+    // spacing
+    p: P("p", STEP), px: P("px", STEP), py: P("py", STEP), pt: P("pt", STEP), pr: P("pr", STEP), pb: P("pb", STEP), pl: P("pl", STEP),
+    m: P("m", `${STEP}|auto`, { neg: true }), mx: P("mx", `${STEP}|auto`, { neg: true }), my: P("my", `${STEP}|auto`, { neg: true }),
+    mt: P("mt", `${STEP}|auto`, { neg: true }), mr: P("mr", `${STEP}|auto`, { neg: true }), mb: P("mb", `${STEP}|auto`, { neg: true }), ml: P("ml", `${STEP}|auto`, { neg: true }),
+    spaceX: P("space-x", STEP, { neg: true }),
+    spaceY: P("space-y", STEP, { neg: true }),
+    // position offsets
+    inset: P("inset", `${STEP}|auto|full|\\d+/\\d+`, { neg: true }),
+    top: P("top", `${STEP}|auto|full|\\d+/\\d+`, { neg: true }),
+    right: P("right", `${STEP}|auto|full|\\d+/\\d+`, { neg: true }),
+    bottom: P("bottom", `${STEP}|auto|full|\\d+/\\d+`, { neg: true }),
+    left: P("left", `${STEP}|auto|full|\\d+/\\d+`, { neg: true }),
+    // typography
+    fontFamily: E("font-(?:sans|serif|mono)"),
+    fontSize: { re: /^text-(xs|sm|base|lg|xl|[2-9]xl|\[\d[^\]]*\])$/, read: (m) => m[1], build: (v) => `text-${normArb(v)}` },
+    fontWeight: E("font-(?:thin|extralight|light|normal|medium|semibold|bold|extrabold|black)"),
+    fontStyle: E("italic|not-italic"),
+    leading: P("leading", "none|tight|snug|normal|relaxed|loose|\\d+"),
+    tracking: P("tracking", "tighter|tight|normal|wide|wider|widest"),
+    textAlign: E("text-(?:left|center|right|justify|start|end)"),
+    textColor: C("text"),
+    textDecoration: E("underline|overline|line-through|no-underline"),
+    textTransform: E("uppercase|lowercase|capitalize|normal-case"),
+    textOverflow: E("truncate|text-ellipsis|text-clip"),
+    whitespace: E("whitespace-(?:normal|nowrap|pre|pre-line|pre-wrap|break-spaces)"),
+    lineClamp: P("line-clamp", "\\d+|none"),
+    // background
+    bgColor: C("bg"),
+    bgImage: E("bg-gradient-to-(?:t|tr|r|br|b|bl|l|tl)|bg-none"),
+    gradFrom: C("from"), gradVia: C("via"), gradTo: C("to"),
+    bgSize: E("bg-(?:auto|cover|contain)"),
+    bgPosition: E("bg-(?:center|top|right|bottom|left|left-top|left-bottom|right-top|right-bottom)"),
+    bgRepeat: E("bg-(?:repeat|no-repeat|repeat-x|repeat-y)"),
+    fill: C("fill"), stroke: C("stroke"),
+    // border
+    borderWidth: { re: /^border(?:-([0248]|\[\d[^\]]*\]))?$/, read: (m) => m[1] || "1", build: (v) => (v === "1" || v === "" ? "border" : `border-${normArb(v)}`) },
+    borderT: P("border-t", "[0248]"), borderR: P("border-r", "[0248]"), borderB: P("border-b", "[0248]"), borderL: P("border-l", "[0248]"),
+    borderStyle: E("border-(?:solid|dashed|dotted|double|none)"),
+    borderColor: C("border"),
+    radius: { re: /^rounded(?:-(none|sm|md|lg|xl|2xl|3xl|full|\[[^\]]+\]))?$/, read: (m) => m[1] || "", build: (v) => (v === "" || v === "default" ? "rounded" : `rounded-${normArb(v)}`) },
+    radiusTL: P("rounded-tl", "none|sm|md|lg|xl|2xl|3xl|full"), radiusTR: P("rounded-tr", "none|sm|md|lg|xl|2xl|3xl|full"),
+    radiusBR: P("rounded-br", "none|sm|md|lg|xl|2xl|3xl|full"), radiusBL: P("rounded-bl", "none|sm|md|lg|xl|2xl|3xl|full"),
+    ring: { re: /^ring(?:-([0124-8]))?$/, read: (m) => m[1] || "3", build: (v) => (v === "3" ? "ring" : `ring-${v}`) },
+    ringColor: C("ring"),
+    // effects
+    shadow: { re: /^shadow(?:-(sm|md|lg|xl|2xl|inner|none))?$/, read: (m) => m[1] || "default", build: (v) => (v === "default" || v === "" ? "shadow" : `shadow-${v}`) },
+    shadowColor: C("shadow"),
+    opacity: P("opacity", "\\d+"),
+    blur: { re: /^blur(?:-(none|sm|md|lg|xl|2xl|3xl))?$/, read: (m) => m[1] || "default", build: (v) => (v === "default" ? "blur" : `blur-${v}`) },
+    backdropBlur: { re: /^backdrop-blur(?:-(none|sm|md|lg|xl|2xl|3xl))?$/, read: (m) => m[1] || "default", build: (v) => (v === "default" ? "backdrop-blur" : `backdrop-blur-${v}`) },
+    brightness: P("brightness", "\\d+"),
+    grayscale: { re: /^grayscale(?:-(0))?$/, read: (m) => m[1] || "100", build: (v) => (v === "0" ? "grayscale-0" : "grayscale") },
+    mixBlend: E("mix-blend-(?:normal|multiply|screen|overlay|darken|lighten|difference)"),
+    rotate: P("rotate", "\\d+", { neg: true }),
+    scale: P("scale", "\\d+"),
+    // an outline: its style (outline = solid), width, colour and offset are four classes
+    outlineStyle: E("outline|outline-none|outline-dashed|outline-dotted|outline-double"),
+    outlineW: P("outline", "\\d+|\\[\\d+(?:\\.\\d+)?px\\]", { arb: false }),
+    outlineColor: C("outline"),
+    outlineOffset: P("outline-offset", "\\d+|\\[\\d+(?:\\.\\d+)?px\\]", { arb: false }),
+    flipX: E("-scale-x-100"), // a mirror image: the one scale class that works in Tailwind 3 and 4 alike
+    flipY: E("-scale-y-100"),
+    translateX: P("translate-x", `${STEP}|full|\\d+/\\d+`, { neg: true }),
+    translateY: P("translate-y", `${STEP}|full|\\d+/\\d+`, { neg: true }),
+    // motion and interaction
+    transition: { re: /^transition(?:-(none|all|colors|opacity|shadow|transform))?$/, read: (m) => m[1] || "default", build: (v) => (v === "default" ? "transition" : `transition-${v}`) },
+    duration: P("duration", "\\d+"),
+    ease: E("ease-(?:linear|in|out|in-out)"),
+    delay: P("delay", "\\d+"),
+    cursor: E("cursor-(?:pointer|default|text|move|not-allowed|wait|grab|grabbing|crosshair|help|auto)"),
+    pointerEvents: E("pointer-events-(?:none|auto)"),
+    userSelect: E("select-(?:none|text|all|auto)"),
+};
+
+export const BREAKPOINTS = ["", "sm", "md", "lg", "xl", "2xl"];
+export const STATES = ["", "hover", "focus", "active", "disabled", "dark", "group-hover", "focus-within", "first", "last", "odd", "even"];
+export const BREAKPOINT_WIDTH = { "": 390, sm: 640, md: 768, lg: 1024, xl: 1280, "2xl": 1536 };
+
+const split = (str) => String(str || "").split(/\s+/).filter(Boolean);
+
+/** "md:hover:bg-red-500" -> { variant: "md:hover:", base: "bg-red-500" } (ignores colons inside [...]) */
+export function parseToken(tok) {
+    let depth = 0, cut = -1;
+    for (let i = 0; i < tok.length; i++) {
+        if (tok[i] === "[") depth++;
+        else if (tok[i] === "]") depth--;
+        else if (tok[i] === ":" && depth === 0) cut = i;
+    }
+    return cut === -1 ? { variant: "", base: tok } : { variant: tok.slice(0, cut + 1), base: tok.slice(cut + 1) };
+}
+
+/** Current value of a group for one variant, or null. */
+export function getGroup(classes, key, variant = "") {
+    const g = GROUPS[key];
+    for (const tok of split(classes)) {
+        const { variant: v, base } = parseToken(tok);
+        if (v !== variant) continue;
+        const m = base.match(g.re);
+        if (m) return { token: tok, value: g.read(m) };
+    }
+    return null;
+}
+
+/** Sets (or, with an empty value, clears) a group for one variant. Returns the new class string, or null if the value is invalid. */
+export function setGroup(classes, key, value, variant = "") {
+    const g = GROUPS[key];
+    let built = "";
+    if (value !== "" && value !== null && value !== undefined) {
+        built = g.build(value);
+        if (!g.re.test(built)) return null;
+    }
+    // the new class takes the old one's place (or goes at the end), so the rest of the list keeps its order
+    const out = [];
+    let at = -1;
+    for (const tok of split(classes)) {
+        const { variant: v, base } = parseToken(tok);
+        if (v === variant && g.re.test(base)) { if (at === -1) at = out.length; continue; }
+        out.push(tok);
+    }
+    if (built) out.splice(at === -1 ? out.length : at, 0, variant + built);
+    return out.join(" ");
+}
+
+export const ALL_GROUP_KEYS = Object.keys(GROUPS);