grapes-vue-lite 0.1.21 → 0.1.23

package/README.md

@@ -262,21 +262,196 @@ Example local `.json` file:
 }
 ```
 
+Supported local component JSON shapes:
+
+1. Standard `ComponentLibraryItemInput` object
+
+```json
+{
+  "id": "hero-card",
+  "name": "Hero Card",
+  "cnName": "英雄卡片",
+  "description": "Reusable marketing hero",
+  "category": "Marketing",
+  "tags": ["hero", "banner"],
+  "previewSrc": "https://cdn.example.com/previews/hero-card.png",
+  "block": {
+    "type": "section",
+    "name": "Hero Card",
+    "children": [
+      {
+        "type": "heading",
+        "text": "Hero Card"
+      },
+      {
+        "type": "text",
+        "text": "Imported from a local JSON component file."
+      }
+    ]
+  }
+}
+```
+
+2. Raw `ComponentNodeInput` object
+
+```json
+{
+  "type": "section",
+  "name": "Simple Hero",
+  "children": [
+    {
+      "type": "heading",
+      "text": "Simple Hero"
+    },
+    {
+      "type": "text",
+      "text": "This file is a raw component node."
+    }
+  ]
+}
+```
+
+When the root JSON value is a raw node object, the importer uses the filename as the fallback `id` and `name`.
+
+3. `BlockDefinition` object with declarative `content`
+
+```json
+{
+  "id": "hero-block",
+  "label": "Hero Block",
+  "description": "Hero block definition",
+  "category": "Marketing",
+  "content": {
+    "type": "section",
+    "children": [
+      {
+        "type": "heading",
+        "text": "Hero Block"
+      }
+    ]
+  }
+}
+```
+
+4. Array of any supported item shape
+
+```json
+[
+  {
+    "id": "hero-card",
+    "name": "Hero Card",
+    "block": {
+      "type": "section",
+      "children": [
+        {
+          "type": "heading",
+          "text": "Hero Card"
+        }
+      ]
+    }
+  },
+  {
+    "id": "feature-grid",
+    "name": "Feature Grid",
+    "block": {
+      "type": "section",
+      "children": [
+        {
+          "type": "heading",
+          "text": "Feature Grid"
+        }
+      ]
+    }
+  }
+]
+```
+
+5. `svg` component node inside local component JSON
+
+```json
+{
+  "id": "weather-icon",
+  "name": "Weather Icon",
+  "category": "Media",
+  "block": {
+    "type": "svg",
+    "name": "Weather Icon",
+    "attributes": {
+      "data-gv-svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"32\" height=\"32\" viewBox=\"0 0 32 32\"><path fill=\"currentColor\" d=\"M17 19h4v4h-4zm-6 0h4v4h-4zm6 6h4v4h-4zm-6 0h4v4h-4z\"/><path fill=\"currentColor\" d=\"M24.5 25H24v-2h.5a5.496 5.496 0 0 0 .377-10.98l-.836-.056l-.09-.834a7.998 7.998 0 0 0-15.902 0l-.09.834l-.836.057A5.496 5.496 0 0 0 7.5 23H8v2h-.5a7.496 7.496 0 0 1-1.322-14.876a10 10 0 0 1 19.644 0A7.496 7.496 0 0 1 24.5 25\"/></svg>",
+      "aria-label": "Weather icon"
+    },
+    "style": {
+      "width": "64px",
+      "height": "64px",
+      "color": "#1f2520",
+      "display": "inline-flex",
+      "alignItems": "center",
+      "justifyContent": "center",
+      "lineHeight": "0"
+    }
+  }
+}
+```
+
+For local component JSON with SVG:
+
+- use `type: "svg"`
+- put the raw SVG string in `attributes["data-gv-svg"]`
+- control scaling with `style.width` and `style.height`
+- control color with `style.color`
+- prefer `fill="currentColor"` or `stroke="currentColor"` inside the SVG markup
+- hard-coded colors such as `fill="#000"` are not automatically rewritten
+
+Recommended minimum fields for local component JSON:
+
+- `id`
+- `name`
+- `block`
+
+Where `block` should contain declarative component data instead of runtime functions.
+
+See [docs/component-library-local-json.md](docs/component-library-local-json.md) for the full local component JSON protocol reference.
+
 Imported component library items are registered into the existing block system. When `persistImported` is enabled, they are also written into project JSON as `customBlocks` and restored when the project is loaded again.
 
 The built-in component library panel currently supports:
 
 - choosing local `.json` component files
 - browsing static or paged host-provided sources
-- search, category filtering, and load-more pagination
+- per-source search, category filtering, and previous/next pagination
 - importing an item once and preventing duplicate imports in the browser view
 - inserting already imported items directly from the library browser
 - removing imported items from the local project library
 
 If a remote source request fails, the browser view exposes a retry action instead of silently failing. When no sources are configured, the panel renders an explicit empty state.
 
+The built-in image library dialog follows the same paged-browser model for remote `assets.sources`: static sources render as immediate thumbnail grids, while paged sources render a fixed previous/next footer and switch pages instead of appending more thumbnails into the current view.
+
 The package treats `vue` as a peer dependency, so the host application owns the Vue runtime version.
 
+## SVG Block
+
+The built-in block library includes an `SVG` block for inline icons or illustrations. It is designed for trusted SVG markup that you want to paste directly into the editor and scale on the canvas.
+
+Current behavior:
+
+- inserts a dedicated `svg` component block
+- stores raw SVG markup in the `data-gv-svg` trait field
+- renders inline SVG on the canvas with `v-html`
+- scales through the component `width` and `height`
+- changes color through the component `color`
+
+Recommended SVG format:
+
+```svg
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32">
+  <path fill="currentColor" d="M17 19h4v4h-4zm-6 0h4v4h-4zm6 6h4v4h-4zm-6 0h4v4h-4z"/>
+  <path fill="currentColor" d="M24.5 25H24v-2h.5a5.496 5.496 0 0 0 .377-10.98l-.836-.056l-.09-.834a7.998 7.998 0 0 0-15.902 0l-.09.834l-.836.057A5.496 5.496 0 0 0 7.5 23H8v2h-.5a7.496 7.496 0 0 1-1.322-14.876a10 10 0 0 1 19.644 0A7.496 7.496 0 0 1 24.5 25"/>
+</svg>
+```
+
+Color editing works best when the SVG uses `fill="currentColor"` or `stroke="currentColor"`. Hard-coded colors such as `fill="#000"` are not automatically rewritten by the editor.
+
 Hosts that own application theme state can control the editor theme with the dedicated `theme` prop. The prop accepts the same `ThemeInput` shape as `options.theme`, and updates are applied to the active editor instance without remounting:
 
 ```vue
@@ -582,7 +757,7 @@ const options: EditorOptions = {
 - `I18n`: English and Simplified Chinese UI messages with English as the default locale.
 - `Theme`: light/dark editor UI themes and host-provided design tokens.
 - `Assets`: image asset registry and image assignment.
-- `EditorOptions.assets.sources`: host-provided third-party image lists that appear in the left asset panel as selectable thumbnails.
+- `EditorOptions.assets.sources`: host-provided third-party image lists that appear in the left asset panel as selectable thumbnails. Paged sources open in the built-in image library dialog with fixed previous/next pagination.
 - `EditorOptions.assets.allowManual`: keep or hide the manual URL entry form when the host wants only curated assets.
 - `Storage`: local and custom storage adapters.
 - `Commands`: command registry and shortcuts.