grapes-vue-lite 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stevenzxs
+
+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.

package/README.md

@@ -0,0 +1,149 @@
+# grapes-vue-lite
+
+Vue 3 + TypeScript page builder inspired by GrapesJS. The project is evolving toward a modular editor core with managers for blocks, components, traits, styles, selectors, CSS rules, assets, storage, commands, and history.
+
+This is an independent project and is not affiliated with or endorsed by GrapesJS.
+
+## Installation
+
+The npm package is intended to be published as a beta release first:
+
+```bash
+pnpm add grapes-vue-lite@beta
+```
+
+For local validation before publishing:
+
+```bash
+pnpm build
+npm pack
+pnpm add ./grapes-vue-lite-0.1.0.tgz
+```
+
+## Commands
+
+```bash
+pnpm install
+pnpm dev
+pnpm test:run
+pnpm build:lib
+pnpm build
+```
+
+`pnpm build` runs smoke tests, type checks, the demo app build, and the library build.
+`pnpm build:lib` emits the third-party integration package into `dist-lib`.
+
+## Third-party Vue Integration
+
+Install the package in a Vue 3 application, then import the editor component and stylesheet:
+
+```ts
+import { GrapesVueEditor } from "grapes-vue-lite";
+import "grapes-vue-lite/style.css";
+```
+
+Use the component in any Vue page:
+
+```vue
+<script setup lang="ts">
+import { GrapesVueEditor, type EditorContext, type EditorOptions } from "grapes-vue-lite";
+import "grapes-vue-lite/style.css";
+
+const options: EditorOptions = {
+  selectors: [{ name: "primary-button", label: "Primary button" }],
+  storage: {
+    localKey: "host-app-builder",
+  },
+  plugins: [
+    (editor) => {
+      editor.Blocks.add({
+        id: "host-hero",
+        label: "Host Hero",
+        description: "Hero block registered by the host app",
+        category: "Host",
+        create: ({ Components }) =>
+          Components.createNode("section", {
+            name: "Host Hero",
+            style: { padding: "64px", background: "#ffffff" },
+          }),
+      });
+    },
+  ],
+};
+
+function handleReady(editor: EditorContext) {
+  console.log(editor.exportProjectJson());
+}
+
+function handleChange(projectJson: string) {
+  console.log(projectJson);
+}
+</script>
+
+<template>
+  <GrapesVueEditor :options="options" @ready="handleReady" @change="handleChange" />
+</template>
+```
+
+The package treats `vue` as a peer dependency, so the host application owns the Vue runtime version.
+
+## Current Editor Modules
+
+- `Blocks`: block registry and categories.
+- `Components`: component type registry, node creation, and style constraints.
+- `Traits`: common and component-specific attributes.
+- `Styles`: style sectors and style properties.
+- `Selectors`: project-level class registry and class assignment.
+- `CssRules`: class selector style rules with state, component-first scope, and device overrides.
+- `Assets`: image asset registry and image assignment.
+- `Storage`: local and custom storage adapters.
+- `Commands`: command registry and shortcuts.
+- `History`: undo/redo snapshots with bounded history.
+
+## CSS And Export
+
+The editor supports both node-level styles and class selector rules.
+
+- Node styles are exported as `[data-node-id="..."]` CSS rules.
+- Component types can restrict editable style properties with `stylable` and `unstylable`.
+- Class styles are exported as normal selector rules, for example `.hero-card`.
+- Selector state rules are exported with pseudo classes, for example `.hero-card:hover`.
+- Component-first selector rules are scoped to a node, for example `[data-node-id="hero"].hero-card`.
+- Device overrides are exported as media queries.
+- Canvas preview uses device-flattened node and class CSS so Tablet/Mobile styles apply to the canvas width instead of the browser viewport.
+
+Toolbar export options:
+
+- `View HTML`: single HTML document with CSS embedded in `<style>`.
+- `View Linked HTML`: HTML document that references `grapes-vue-lite-styles.css`.
+- `View CSS`: current page CSS.
+- `Export JSON`: project data.
+- `Export HTML`: single-file HTML.
+- `Export Linked HTML`: HTML for external CSS deployment.
+- `Export CSS`: standalone CSS file.
+
+## Class Styling Workflow
+
+1. Select a node on the canvas.
+2. Add a class in the `Classes` panel.
+3. Click `Style` on the class chip.
+4. Pick `Base`, `Hover`, `Active`, or `Focus` when styling selector states.
+5. Enable `Component first` when the class style should only affect the selected node.
+6. Use the `Style` panel to edit the class rule.
+7. Switch devices to add device-specific class overrides.
+
+Deleting a project class removes it from the registry, all page nodes, and its CSS rule.
+
+## Tests
+
+`test/exporter-smoke-test.ts` directly imports the exporter module and verifies:
+
+- page CSS includes node styles;
+- page CSS includes media rules;
+- page CSS includes selector rules;
+- page CSS includes selector state and component-first rules;
+- canvas CSS flattens active device node and selector overrides;
+- linked HTML references external CSS;
+- linked HTML does not emit inline styles.
+
+The test compiles through `tsconfig.test.json` into `node_modules/.tmp/test-dist` and is executed by `scripts/run-tests.mjs`.