@qarakash/blockwriteai 1.0.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qarAkash
+
+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,642 @@
+# BlockWriteAI
+
+BlockWriteAI is a drop-in block writing editor for the web. It is built to feel familiar to Editor.js users, but ships as plain CSS and JavaScript files that can be used in PHP, Laravel, CodeIgniter, static HTML, dashboards, or any project that can load a script tag.
+
+The editor stores and saves content as JSON first. Projects can render that JSON on any page by adding a BlockWriteAI preview container, while advanced document blocks such as tables, media galleries, attachments, diagrams, charts, signatures, and code editing remain available as plugins.
+
+All public assets, package entry points, and browser globals use the `BlockWriteAI` name.
+
+## Highlights
+
+- Editor.js-style block JSON output.
+- Plain script tag integration with no build step required.
+- Paragraphs, headings, quotes, callouts, dividers, buttons, toggle blocks, raw HTML, links, embeds, tables, lists, and nested checklists.
+- Floating inline toolbar with typography, colors, highlight, alignment, comments, links, and formatting controls.
+- Multi-image upload, drag and drop, resize, crop, rotate, and gallery layout.
+- Attachment blocks for documents and videos.
+- Code block with formatting, syntax help, language detection, and suggestions.
+- Mermaid-style drawing designer with shapes, arrows, images, text formatting, ruler, workspace resizing, and preview/export support.
+- Charts, LaTeX, audio, drawing, layout columns, signature, signature flow, AI writing, and optional history plugins.
+- Undo, redo, autosave, block actions, drag reordering, and optional JSON save/export buttons.
+- JSON-powered preview mounting for public document pages.
+- JSON save API examples for future database storage.
+
+## Project Structure
+
+```text
+BlockWriteAI/
+  package.json
+  composer.json
+  pyproject.toml
+  dist/
+    blockwriteai.css
+    blockwriteai.js
+    blockwriteai-logo.svg
+    blockwriteai-favicon.svg
+    plugins/
+      blockwriteai-advanced-blocks.js
+      blockwriteai-drawing.js
+      blockwriteai-mermaid.js
+      blockwriteai-ai.js
+      blockwriteai-code-assist.js
+      blockwriteai-history.js
+      blockwriteai-signature.js
+      blockwriteai-signature-flow.js
+  examples/
+    index.html
+    preview.html
+    upload.php
+    api/
+      document.php
+      preview.php
+    uploads/
+      .gitkeep
+  blockwriteai_editor/
+    static/blockwriteai/
+  src/
+    BlockWriteAIAssets.php
+  types/
+    index.d.ts
+```
+
+## Installation
+
+BlockWriteAI can be consumed as a CDN/script-link package, an npm package, a Python static-assets package, or a Composer package.
+
+### Script Link
+
+Use the GitHub CDN link directly from the current main build:
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/qarAkash/BlockWriteAI@main/dist/blockwriteai.css">
+
+<script src="https://cdn.jsdelivr.net/gh/qarAkash/BlockWriteAI@main/dist/blockwriteai.js"></script>
+<script src="https://cdn.jsdelivr.net/gh/qarAkash/BlockWriteAI@main/dist/plugins/blockwriteai-code-assist.js"></script>
+<script src="https://cdn.jsdelivr.net/gh/qarAkash/BlockWriteAI@main/dist/plugins/blockwriteai-advanced-blocks.js"></script>
+<script src="https://cdn.jsdelivr.net/gh/qarAkash/BlockWriteAI@main/dist/plugins/blockwriteai-ai.js"></script>
+<script src="https://cdn.jsdelivr.net/gh/qarAkash/BlockWriteAI@main/dist/plugins/blockwriteai-signature.js"></script>
+<script src="https://cdn.jsdelivr.net/gh/qarAkash/BlockWriteAI@main/dist/plugins/blockwriteai-signature-flow.js"></script>
+```
+
+`blockwriteai-advanced-blocks.js` is kept as the compatibility bundle. New
+licensed delivery can load Drawing and Mermaid separately:
+
+```html
+<script src="https://cdn.jsdelivr.net/gh/qarAkash/BlockWriteAI@main/dist/plugins/blockwriteai-drawing.js"></script>
+<script src="https://cdn.jsdelivr.net/gh/qarAkash/BlockWriteAI@main/dist/plugins/blockwriteai-mermaid.js"></script>
+```
+
+Load History only when a project needs the history dropdown:
+
+```html
+<script src="https://cdn.jsdelivr.net/gh/qarAkash/BlockWriteAI@main/dist/plugins/blockwriteai-history.js"></script>
+```
+
+For locked production builds, replace `@main` with a release tag after publishing.
+
+### Premium License Gating
+
+Drawing, Mermaid drawing, Signature, Signature Flow, and AI can be licensed through
+the BlockWriteAI Platform. Normal editor blocks continue to work without a license.
+Premium tools are shown as locked until the license endpoint returns an active trial
+or subscription.
+
+```js
+const editor = new BlockWriteAI({
+  holder: "#editor",
+  licenseKey: "bwai_live_xxxxx",
+  premium: {
+    verifyEndpoint: "http://localhost/blockwriteai-platform/api/license_verify.php",
+    usageEndpoint: "http://localhost/blockwriteai-platform/api/ai_usage.php"
+  },
+  ai: {
+    endpoint: "/api/ai.php"
+  }
+});
+```
+
+The verify endpoint must return a `features` object with these keys when enabled:
+
+```json
+{
+  "drawing": true,
+  "mermaid": true,
+  "signature": true,
+  "signature_flow": true,
+  "ai": true
+}
+```
+
+The AI plugin calls `premium.usageEndpoint` before each AI request so the platform
+can enforce the 7-day trial and daily prompt limits.
+
+For stronger production security, do not load premium plugin files directly from a
+public CDN. Load the free core first, request the premium plugins from your
+BlockWriteAI Platform, and create the editor only after the server has verified
+the license. The platform serves Drawing, Mermaid, Signature, Signature Flow,
+and AI as separate plugin files after checking the requested feature flags:
+
+```html
+<link rel="stylesheet" href="/BlockWriteAI/dist/blockwriteai.css">
+<script src="/BlockWriteAI/dist/blockwriteai.js"></script>
+<script src="/BlockWriteAI/dist/plugins/blockwriteai-code-assist.js"></script>
+<script>
+  async function boot() {
+    await BlockWriteAI.loadPremiumPlugins({
+      licenseKey: "bwai_live_xxxxx",
+      endpoint: "http://localhost/blockwriteai-platform/api/premium_plugins.php",
+      features: ["drawing", "mermaid", "signature", "signature_flow", "ai"]
+    });
+
+    window.editor = new BlockWriteAI({
+      holder: "#editor",
+      licenseKey: "bwai_live_xxxxx",
+      premium: {
+        verifyEndpoint: "http://localhost/blockwriteai-platform/api/license_verify.php",
+        usageEndpoint: "http://localhost/blockwriteai-platform/api/ai_usage.php"
+      }
+    });
+  }
+  boot();
+</script>
+```
+
+This matters because browser-only locks can be edited in DevTools. Server-side
+license verification, usage metering, signature event storage, and verified
+premium bundle delivery are the enforceable parts.
+
+### npm
+
+Package name:
+
+```text
+@qarakash/blockwriteai
+```
+
+Install:
+
+```bash
+npm install @qarakash/blockwriteai
+```
+
+Bundler entry points:
+
+```js
+import BlockWriteAI from "@qarakash/blockwriteai";
+import "@qarakash/blockwriteai/css";
+import "@qarakash/blockwriteai/plugins/code-assist";
+import "@qarakash/blockwriteai/plugins/advanced";
+import "@qarakash/blockwriteai/plugins/ai";
+import "@qarakash/blockwriteai/plugins/history";
+import "@qarakash/blockwriteai/plugins/signature";
+import "@qarakash/blockwriteai/plugins/signature-flow";
+```
+
+After npm publishing, the same package is also available through npm CDNs:
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@qarakash/blockwriteai@1.0.7/dist/blockwriteai.css">
+<script src="https://cdn.jsdelivr.net/npm/@qarakash/blockwriteai@1.0.7/dist/blockwriteai.js"></script>
+```
+
+### Python
+
+Package name:
+
+```text
+blockwriteai-editor
+```
+
+Install:
+
+```bash
+pip install blockwriteai-editor
+```
+
+Copy packaged static files into your Flask, Django, or any Python web app static directory:
+
+```python
+from blockwriteai_editor import copy_static
+
+copy_static("static/blockwriteai")
+```
+
+Python helpers are also available for generating asset tags. Pass `history=True` only on pages where you want the optional History dropdown:
+
+```python
+from blockwriteai_editor import stylesheet_tag, script_tags
+
+print(stylesheet_tag("/static/blockwriteai"))
+print(script_tags("/static/blockwriteai"))
+print(script_tags("/static/blockwriteai", history=True))
+print(script_tags("/static/blockwriteai", ai=True))
+```
+
+### PHP / Composer
+
+Package name:
+
+```text
+qarakash/blockwriteai
+```
+
+Install:
+
+```bash
+composer require qarakash/blockwriteai
+```
+
+Publish assets into your public folder:
+
+```bash
+cp -R vendor/qarakash/blockwriteai/dist public/blockwriteai
+```
+
+PHP helper. Pass `history: true` only on pages where you want the optional History dropdown, and `ai: true` only on pages where you want the AI drawer:
+
+```php
+use QarAkash\BlockWriteAI\BlockWriteAIAssets;
+
+echo BlockWriteAIAssets::stylesheetTag('/blockwriteai');
+echo BlockWriteAIAssets::scriptTags('/blockwriteai');
+echo BlockWriteAIAssets::scriptTags('/blockwriteai', plugins: true, history: true, ai: true);
+```
+
+## Local XAMPP Demo
+
+Copy the `BlockWriteAI` folder into your web root, for example:
+
+```text
+C:\xampp\htdocs\BlockWriteAI
+```
+
+Open:
+
+```text
+http://localhost/BlockWriteAI/examples/
+```
+
+## Browser Usage
+
+```html
+<link rel="stylesheet" href="/BlockWriteAI/dist/blockwriteai.css">
+
+<div id="editor"></div>
+
+<script src="/BlockWriteAI/dist/blockwriteai.js"></script>
+<script src="/BlockWriteAI/dist/plugins/blockwriteai-code-assist.js"></script>
+<script src="/BlockWriteAI/dist/plugins/blockwriteai-advanced-blocks.js"></script>
+<script src="/BlockWriteAI/dist/plugins/blockwriteai-signature.js"></script>
+<script src="/BlockWriteAI/dist/plugins/blockwriteai-signature-flow.js"></script>
+
+<script>
+const editor = new BlockWriteAI({
+  holder: "#editor",
+  maxWidth: "960px", // optional; omit for full-width editor shell
+  placeholder: "Write something, or press / for blocks",
+    data: {
+      blocks: [
+        {
+          type: "paragraph",
+          data: {
+            text: "Hello from BlockWriteAI",
+            alignment: "left"
+          }
+        }
+      ]
+    },
+    onChange(data) {
+      console.log("Changed document", data);
+    },
+    async onSave(data) {
+      await fetch("/save-document.php", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(data)
+      });
+    }
+});
+</script>
+```
+
+By default, BlockWriteAI mounts the full branded editor shell: logo, product subtitle,
+`Editor` heading, centered AI progress, and the right-aligned JSON sync status. If no
+`data` is provided, the editor starts with one empty paragraph block automatically. Use
+`shell: false` when you only want the raw editor surface, or pass `maxWidth: "960px"` /
+`shell: { maxWidth: "960px" }` to constrain the editor width in your project.
+
+Built-in toolbar buttons are intentionally opt-in for package consumers. `saveButton`, `exportButton`, and `exportHtmlButton` default to `false`, so applications can use their own UI and call `editor.save()` when needed.
+
+## Saving JSON
+
+BlockWriteAI is designed to save JSON first. In production, store the JSON in your database and render it later in read-only mode or through exported HTML.
+
+```js
+document.querySelector("#save").addEventListener("click", async () => {
+  const data = await editor.save();
+
+  await fetch("/save-document.php", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify(data)
+  });
+});
+```
+
+The default toolbar includes a Save button. Use `onSave` to receive the JSON response when the user clicks it:
+
+```js
+const editor = new BlockWriteAI({
+  holder: "#editor",
+  async onSave(data) {
+    await fetch("/documents/123", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(data)
+    });
+  }
+});
+```
+
+## AI Plugin
+
+Load the optional AI plugin only on pages where you want writing assistance. The browser plugin never receives your OpenAI API key; it calls your own server endpoint.
+
+```html
+<script src="/blockwriteai/blockwriteai.js"></script>
+<script src="/blockwriteai/plugins/blockwriteai-ai.js"></script>
+
+<script>
+  const editor = new BlockWriteAI({
+    holder: "#editor",
+    ai: {
+      endpoint: "/api/blockwriteai-ai.php"
+    }
+  });
+</script>
+```
+
+The included demo endpoint is `examples/api/ai.php`. For local development, copy `examples/api/openai.local.example.php` to `examples/api/openai.local.php` and add a development key, or set `OPENAI_API_KEY` in the server environment. Do not expose the key in browser JavaScript.
+
+The drawer can also be opened without selecting text from the centered AI button in the editor toolbar, or programmatically with `editor.openAI()`.
+
+Available AI drawer actions:
+
+- Improve writing
+- Fix grammar
+- Summarize
+- Expand
+- Make professional
+- Generate BlockWriteAI blocks from a prompt
+
+## Preview Pages
+
+Create any page in your application and add a preview container. BlockWriteAI will load saved JSON and render the document HTML inside that container.
+
+```html
+<link rel="stylesheet" href="/blockwriteai/blockwriteai.css">
+
+<div class="blockwriteai-preview" data-source="/documents/123.json"></div>
+
+<script src="/blockwriteai/blockwriteai.js"></script>
+<script src="/blockwriteai/plugins/blockwriteai-advanced-blocks.js"></script>
+<script src="/blockwriteai/plugins/blockwriteai-signature.js"></script>
+<script src="/blockwriteai/plugins/blockwriteai-signature-flow.js"></script>
+<script>
+  BlockWriteAI.mountPreviews();
+</script>
+```
+
+The JSON endpoint can return either a BlockWriteAI document directly or an API wrapper such as:
+
+```json
+{
+  "ok": true,
+  "data": {
+    "time": 1779540000000,
+    "version": "1.0.7",
+    "blocks": []
+  }
+}
+```
+
+Example PHP receiver:
+
+```php
+<?php
+header('Content-Type: application/json');
+
+$json = file_get_contents('php://input');
+$data = json_decode($json, true);
+
+if (!$data || !isset($data['blocks']) || !is_array($data['blocks'])) {
+    http_response_code(422);
+    echo json_encode(['error' => 'Invalid BlockWriteAI document']);
+    exit;
+}
+
+file_put_contents(__DIR__ . '/saved-document.json', json_encode($data, JSON_PRETTY_PRINT));
+
+echo json_encode(['ok' => true]);
+```
+
+## Uploads
+
+The demo includes `examples/upload.php` and stores files under `examples/uploads/`. For production, replace this with your own storage layer.
+
+```js
+const editor = new BlockWriteAI({
+  holder: "#editor",
+  uploadOutput: ["upload", "base64"],
+  upload: {
+    image: async (file) => {
+      const form = new FormData();
+      form.append("file", file);
+      form.append("kind", "image");
+
+      const response = await fetch("/BlockWriteAI/examples/upload.php", {
+        method: "POST",
+        body: form
+      });
+
+      return response.json();
+    },
+    file: async (file) => {
+      const form = new FormData();
+      form.append("file", file);
+      form.append("kind", "file");
+
+      const response = await fetch("/BlockWriteAI/examples/upload.php", {
+        method: "POST",
+        body: form
+      });
+
+      return response.json();
+    }
+  }
+});
+```
+
+`uploadOutput` controls what gets written into the saved JSON:
+
+- `"base64"` or `["base64"]` stores uploaded media directly in the block JSON. This is the default.
+- `"upload"` or `["upload"]` stores the response from your upload handler, such as a server URL.
+- `["upload", "base64"]` stores both, useful when you want server files plus a portable JSON backup.
+
+Expected upload response:
+
+```json
+{
+  "url": "/BlockWriteAI/examples/uploads/example.pdf",
+  "name": "example.pdf",
+  "size": 12345,
+  "type": "application/pdf"
+}
+```
+
+When both outputs are enabled, saved image and attachment items include the server response under `upload` and the inline file data under `base64`.
+
+## API Methods
+
+```js
+await editor.save();          // Get JSON document
+editor.getData();             // Get current data synchronously
+editor.render(data);          // Replace editor content
+editor.clear();               // Reset editor
+editor.exportHTML();          // Export HTML
+editor.exportMarkdown();      // Export Markdown API, hidden from the default UI
+editor.importHTML(html);      // Import HTML into blocks
+editor.setReadOnly(true);     // Toggle read-only mode
+editor.undo();                // Undo last change
+editor.redo();                // Redo last undo
+editor.destroy();             // Remove editor instance
+BlockWriteAI.mountPreviews(); // Render JSON into .blockwriteai-preview containers
+```
+
+## Data Shape
+
+```json
+{
+  "time": 1779540000000,
+  "version": "1.0.7",
+  "blocks": [
+    {
+      "id": "block-title",
+      "type": "heading",
+      "data": {
+        "level": 2,
+        "text": "BlockWriteAI document",
+        "alignment": "left"
+      }
+    },
+    {
+      "id": "block-body",
+      "type": "paragraph",
+      "data": {
+        "text": "Reusable content saved as JSON."
+      }
+    }
+  ]
+}
+```
+
+## Tool Control
+
+Limit available blocks per project:
+
+```js
+const editor = new BlockWriteAI({
+  holder: "#editor",
+  tools: [
+    "paragraph",
+    "heading",
+    "image",
+    "list",
+    "table"
+  ]
+});
+```
+
+Disable specific tools:
+
+```js
+const editor = new BlockWriteAI({
+  holder: "#editor",
+  tools: {
+    raw: false,
+    attaches: false
+  }
+});
+```
+
+## Autosave
+
+```js
+const editor = new BlockWriteAI({
+  holder: "#editor",
+  autosave: {
+    key: "blockwriteai-draft",
+    load: true
+  }
+});
+```
+
+## Security Notes
+
+BlockWriteAI sanitizes normal rich text blocks before saving and exporting. Raw HTML blocks are intentionally treated as trusted HTML, so enable the raw HTML tool only for trusted users.
+
+For production applications:
+
+- Validate JSON on the server.
+- Sanitize output again before public rendering.
+- Restrict upload types and file sizes.
+- Store uploaded files outside executable PHP paths when possible.
+- Add authentication before saving documents.
+
+## GitHub
+
+Repository target:
+
+```text
+https://github.com/qarAkash/BlockWriteAI.git
+```
+
+## Publishing Packages
+
+After a release is ready, publish each package from the repository root.
+
+Create a Git release tag for script-link/CDN users:
+
+```bash
+git tag v1.0.7
+git push origin v1.0.7
+```
+
+Publish npm:
+
+```bash
+npm publish --access public
+```
+
+Publish Python:
+
+```bash
+python -m build
+python -m twine upload dist/*
+```
+
+Publish Composer:
+
+```text
+Submit https://github.com/qarAkash/BlockWriteAI to Packagist as qarakash/blockwriteai.
+```
+
+## Status
+
+BlockWriteAI is currently an active custom editor library and demo project. It is suitable for continued feature development, integration testing, and database-backed storage work.

package/dist/blockwriteai-favicon.svg

@@ -0,0 +1,20 @@
+<svg width="64" height="64" viewBox="0 0 64 64" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="BlockWriteAI">
+  <defs>
+    <linearGradient id="bwai-favicon-bg" x1="8" y1="8" x2="56" y2="56" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#102033"/>
+      <stop offset="1" stop-color="#172A46"/>
+    </linearGradient>
+    <linearGradient id="bwai-favicon-accent" x1="16" y1="18" x2="48" y2="48" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#2BEA8A"/>
+      <stop offset="1" stop-color="#10B981"/>
+    </linearGradient>
+  </defs>
+  <rect x="6" y="6" width="52" height="52" rx="16" fill="url(#bwai-favicon-bg)"/>
+  <rect x="18" y="18" width="10" height="10" rx="2.5" fill="#FFFFFF"/>
+  <rect x="31" y="18" width="10" height="10" rx="2.5" fill="#FFFFFF" opacity="0.92"/>
+  <rect x="18" y="31" width="10" height="10" rx="2.5" fill="url(#bwai-favicon-accent)"/>
+  <path d="M33.2 43.1L45 31.3C45.7 30.6 46.8 30.6 47.5 31.3L51.1 34.9C51.8 35.6 51.8 36.7 51.1 37.4L39.3 49.2L31.5 50.8L33.2 43.1Z" fill="#FFFFFF"/>
+  <path d="M43.1 33.3L49.2 39.4" stroke="#10B981" stroke-width="3" stroke-linecap="round"/>
+  <circle cx="51" cy="51" r="7" fill="#19B86B" stroke="#FFFFFF" stroke-width="3"/>
+  <path d="M49.5 16.5H55.5M52.5 13.5V19.5" stroke="#19B86B" stroke-width="3" stroke-linecap="round"/>
+</svg>