grapes-vue-lite 0.1.2 → 0.1.4

package/README.md

@@ -16,8 +16,7 @@ For local validation before publishing:
 
 ```bash
 pnpm build
-npm pack
-pnpm add ./grapes-vue-lite-0.1.0.tgz
+pnpm check:release
 ```
 
 ## Commands
@@ -26,12 +25,22 @@ pnpm add ./grapes-vue-lite-0.1.0.tgz
 pnpm install
 pnpm dev
 pnpm test:run
+pnpm check:dist-import
+pnpm check:package
+pnpm check:release
+pnpm check:types-consumer
+pnpm pack:dry-run
 pnpm build:lib
 pnpm build
 ```
 
-`pnpm build` runs smoke tests, type checks, the demo app build, and the library build.
+`pnpm check:package` verifies package export paths, generated declaration files, peer dependency shape, and embeddable library CSS.
+`pnpm check:dist-import` verifies the built ESM and UMD/CJS entrypoints can be imported and expose the expected public exports.
+`pnpm check:types-consumer` compiles a temporary TypeScript consumer that imports the built package through `package.json` exports.
+`pnpm pack:dry-run` prints the exact npm tarball file list with a workspace-local npm cache; run it before publishing.
+`pnpm build` runs smoke tests, type checks, the demo app build, the library build, and the package check.
 `pnpm build:lib` emits the third-party integration package into `dist-lib`.
+`pnpm check:release` runs the full publish gate: default build, built entrypoint import checks, consumer type checks, and npm pack dry-run. It is intentionally separate from `pnpm build` because it exercises npm and TypeScript entrypoints as an external consumer would.
 
 ## Third-party Vue Integration
 
@@ -69,6 +78,15 @@ const options: EditorOptions = {
   storage: {
     localKey: "host-app-builder",
   },
+  toolbar: {
+    hidden: ["clear", "languageMenu", "themeMenu", "importHtml", "exportCss", "command:paste"],
+    commandIds: ["togglePreview", "undo", "redo"],
+  },
+  initialContent: {
+    pageName: "Landing",
+    html: '<section class="hero"><h1>Imported from host</h1></section>',
+    css: ".hero { padding: 64px; background: #ffffff; } .hero:hover { background: #f3f4f6; }",
+  },
   plugins: [
     (editor) => {
       editor.Blocks.add({
@@ -102,6 +120,8 @@ function handleChange(projectJson: string) {
 
 The package treats `vue` as a peer dependency, so the host application owns the Vue runtime version.
 
+### Embedding Checklist
+
 The editor fills its parent container by default. When embedding it in a dialog, drawer, tab pane, or any constrained area, set the host container height explicitly:
 
 ```vue
@@ -119,7 +139,41 @@ The editor fills its parent container by default. When embedding it in a dialog,
 </style>
 ```
 
-For full-screen usage, set the host container to `100dvh`. The library stylesheet avoids forcing `body`, `html`, or `#app` height so it does not override the host application's page layout.
+For full-screen usage, set the host container to `100dvh`. The library stylesheet scopes editor tokens, box sizing, form-control font rules, and overlays under `.app-shell`; it avoids forcing `body`, `html`, `#app`, or viewport-height layout so it does not override the host application's page layout.
+
+Keyboard shortcuts are scoped to the active editor instance. Focus or pointer interaction inside an editor marks it active, typing targets are ignored, and multiple editors on the same page do not share command handling. Disable built-in shortcuts when a host application owns all keyboard handling:
+
+```vue
+<GrapesVueEditor :options="options" :shortcuts="false" />
+```
+
+Use `:emit-changes="false"` when the host only needs `@ready` and will pull project JSON manually, for example before saving a larger form.
+
+### Toolbar Customization
+
+Host applications can hide toolbar buttons or choose which commands appear as quick actions:
+
+```ts
+const options: EditorOptions = {
+  toolbar: {
+    hidden: [
+      "clear",
+      "languageMenu",
+      "themeMenu",
+      "storageMenu",
+      "importJson",
+      "importHtml",
+      "exportCss",
+      "command:paste",
+    ],
+    commandIds: ["togglePreview", "undo", "redo"],
+  },
+};
+```
+
+`hidden` accepts top-level toolbar IDs such as `title`, `selectionStatus`, `save`, `load`, `clear`, `commandsMenu`, `languageMenu`, `themeMenu`, `deviceButtons`, `deviceManager`, `storageMenu`, and `exportMenu`. It also accepts export menu item IDs: `importJson`, `importHtml`, `viewJson`, `viewHtml`, `viewLinkedHtml`, `viewCss`, `exportJson`, `exportHtml`, `exportLinkedHtml`, and `exportCss`.
+
+Use `command:<id>` to hide a command everywhere it appears in the toolbar and stop its built-in keyboard shortcut from running. `commandIds` controls the quick command buttons near the selection status and can include host-registered commands. For strict allow-list behavior, use `visible`; include parent menu IDs such as `exportMenu` plus any child IDs that should appear inside the menu.
 
 ## Current Editor Modules
 
@@ -160,6 +214,38 @@ Toolbar export options:
 - `Export Linked HTML`: HTML for external CSS deployment.
 - `Export CSS`: standalone CSS file.
 
+## Initial Content
+
+Hosts can initialize the editor with content instead of the built-in starter page:
+
+```ts
+const options: EditorOptions = {
+  initialContent: {
+    pageName: "Landing",
+    html: '<section class="hero"><h1>Hello</h1><p>Editable content</p></section>',
+    css: ".hero { padding: 64px; background: #ffffff; } .hero:hover { background: #f3f4f6; }",
+  },
+};
+```
+
+`initialContent.project` accepts either a `ProjectData` object or a serialized project JSON string and takes precedence over `html`/`css`. `initialContent.html` uses the same parser as `Import HTML`. `initialContent.css` currently imports simple class rules such as `.hero { ... }` plus `.hero:hover`, `.hero:active`, and `.hero:focus`.
+
+## Pages And Internal Links
+
+Projects can contain multiple pages. Each page has a stable `id` for editor references and a public `path` for preview links and exported markup:
+
+```ts
+editor.addPage();
+editor.updatePagePath(editor.getActivePage().id, "/pricing");
+editor.setActivePage("page-home");
+```
+
+Button and link components support internal page links. Select a button, set `Link type` to `page`, then choose the target page in the `Page` trait. The editor stores the target page id in `data-gv-page-id` and mirrors the page path into `href`, so preview and exported HTML still have normal anchor URLs.
+
+In preview mode, clicking an internal page link switches the active editor page with `setActivePage(pageId)`. In edit mode, the same click still selects the component for editing.
+
+When a page path changes, internal links pointing at that page are updated automatically. Old project JSON without `path` is still accepted; missing paths are normalized on import.
+
 ## Class Styling Workflow
 
 1. Select a node on the canvas.