@pinkpixel/marzipan 1.0.8 → 1.1.0

package/docs/.vitepress/config.ts

@@ -0,0 +1,77 @@
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+  title: 'Marzipan',
+  description: 'Framework-agnostic markdown editor with a live overlay preview, zero runtime dependencies, and batteries-included formatting actions.',
+  lang: 'en-US',
+
+  outDir: '../docs-site',
+
+  // Links to files outside the docs root (CHANGELOG, OVERVIEW, etc.) are valid
+  // relative links for GitHub markdown but are not part of the VitePress site.
+  ignoreDeadLinks: [
+    /\/OVERVIEW/,
+    /\/CHANGELOG/,
+    /\/bakeshop-demo\//,
+    /\.d\.ts$/,
+  ],
+
+  head: [
+    ['link', { rel: 'icon', href: '/favicon.png' }],
+  ],
+
+  themeConfig: {
+    logo: '/logo.png',
+    siteTitle: 'Marzipan',
+
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Quick Start', link: '/quick-start' },
+      { text: 'API', link: '/api' },
+      { text: 'Plugins', link: '/plugins' },
+      {
+        text: 'v1.1.0',
+        items: [
+          { text: 'Changelog', link: 'https://github.com/pinkpixel-dev/marzipan/blob/main/CHANGELOG.md' },
+        ]
+      }
+    ],
+
+    sidebar: [
+      {
+        text: 'Getting Started',
+        items: [
+          { text: 'Introduction', link: '/' },
+          { text: 'Quick Start', link: '/quick-start' },
+        ]
+      },
+      {
+        text: 'Core Reference',
+        items: [
+          { text: 'API Reference', link: '/api' },
+          { text: 'Type Definitions', link: '/types' },
+        ]
+      },
+      {
+        text: 'Plugins',
+        items: [
+          { text: 'Plugin Catalogue', link: '/plugins' },
+          { text: 'Block Handles', link: '/block-handles' },
+        ]
+      },
+    ],
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/pinkpixel-dev/marzipan' },
+    ],
+
+    footer: {
+      message: 'Released under the Apache 2.0 License.',
+      copyright: 'Copyright © Pink Pixel'
+    },
+
+    search: {
+      provider: 'local'
+    }
+  }
+})

package/docs/README.md

@@ -9,6 +9,7 @@ Welcome! This folder contains everything you need to install, configure, and ext
 | [Quick Start](./quick-start.md) | Install the library, render your first editor, and wire up bundled actions and plugins. |
 | [API Reference](./api.md) | Full class API, key options, utility methods, and action helper signatures. |
 | [Plugin Catalogue](./plugins.md) | Overview of the first-party plugins shipped from `src/plugins` with configuration tips. |
+| [Block Handles Plugin](./block-handles.md) | Interactive block manipulation with visual handles, context menus, and keyboard shortcuts. |
 | [Type Definitions](./types.d.ts) | Generated TypeScript declarations for deep integration and tooling. |
 
 ## 🧭 Orientation
@@ -22,7 +23,8 @@ Welcome! This folder contains everything you need to install, configure, and ext
 1. **Quick Start** – get an editor running in under five minutes.
 2. **API Reference** – understand the Marzipan class, events, and helper utilities.
 3. **Plugin Catalogue** – explore optional capabilities like tables, Mermaid, media helpers, and syntax highlight.
-4. **Type Definitions** – browse generated typings for IDE integration.
+4. **Block Handles** – interactive block manipulation for the preview overlay.
+5. **Type Definitions** – browse generated typings for IDE integration.
 
 ## 🧁 Related Resources
 

package/docs/TABLE_OF_CONTENTS.md

@@ -10,6 +10,7 @@
 
 ## Extensions
 - [Plugin Catalogue](./plugins.md)
+- [Block Handles Plugin](./block-handles.md)
 
 ## Related Root Docs
 - [Project Overview](../OVERVIEW.md)

package/docs/api.md

@@ -9,6 +9,7 @@ A comprehensive guide to the core Marzipan class, bundled action toolkit, and fi
 - [Instance Methods](#instance-methods)
 - [Static Methods](#static-methods)
 - [Actions API](#actions-api)
+- [Link Tooltip](#link-tooltip)
 - [Options](#options)
 - [Themes](#themes)
 - [Plugin Exports](#plugin-exports)
@@ -321,18 +322,57 @@ Available helpers include:
 - `toggleBold(textarea)`
 - `toggleItalic(textarea)`
 - `toggleCode(textarea)`
+- `toggleStrikethrough(textarea)` — toggles `~~text~~` / `~text~` strikethrough
 - `insertLink(textarea, options?)`
+- `insertHorizontalRule(textarea)` — inserts a `---` divider at the cursor
 - `toggleBulletList(textarea)`
 - `toggleNumberedList(textarea)`
 - `toggleQuote(textarea)`
 - `toggleTaskList(textarea)`
-- `toggleH1/H2/H3(textarea)`
+- `insertHeader(textarea, level?, toggle?)`
+- `toggleH1(textarea)` / `toggleH2(textarea)` / `toggleH3(textarea)`
 - `applyCustomFormat(textarea, format)`
-- `getActiveFormats(textarea)`
+- `getActiveFormats(textarea)` / `hasFormat(textarea, format)`
+- `expandSelection(textarea)` / `preserveSelection(textarea, fn)`
 - `setUndoMethod(method)` / `getUndoMethod()`
+- `setDebugMode(enabled)` / `getDebugMode()`
 
 These functions mirror the toolbar and keyboard shortcut behaviour, making it easy to build custom UI without extra dependencies.
 
+### Strikethrough
+
+```ts
+import { actions } from '@pinkpixel/marzipan';
+
+// Wraps selection in ~~…~~ or ~…~
+actions.toggleStrikethrough(textarea);
+```
+
+### Horizontal Rule
+
+```ts
+import { actions } from '@pinkpixel/marzipan';
+
+// Inserts --- at the cursor with surrounding newlines
+actions.insertHorizontalRule(textarea);
+```
+
+## Link Tooltip
+
+Marzipan automatically shows a floating URL tooltip whenever the cursor moves inside a markdown link (`[text](url)`). The tooltip is clickable and opens the link in a new tab.
+
+```
+[Visit docs](https://marzipan.pinkpixel.dev)
+                   ^^^ cursor here → tooltip appears
+```
+
+**Implementation details:**
+- Uses the CSS Anchor Positioning API (`position-anchor` / `position-area`) for pixel-accurate placement below the link.
+- Gracefully degrades — in browsers that do not support CSS anchor positioning the tooltip is silently disabled.
+- Managed by the `LinkTooltip` class, which is instantiated automatically by every editor and cleaned up on `destroy()`.
+
+No configuration is required; the feature is always active.
+
 ## Options
 
 Default options and their descriptions:

package/docs/block-handles.md

@@ -0,0 +1,325 @@
+# Block Handles Plugin
+
+The **Block Handles Plugin** provides an interactive block manipulation system for Marzipan's preview overlay. It displays visual handles on the left side of markdown blocks, allowing users to easily select, copy, and delete blocks with mouse and keyboard interactions.
+
+## Features
+
+- 🎨 **Visual Handles**: Unique icons for each block type (headings, paragraphs, lists, quotes, code, tables, etc.)
+- 🖱️ **Hover Interaction**: Handles appear when hovering over blocks
+- ✨ **Selection System**: Click handles or Shift+Click blocks to select them
+- 📋 **Context Menu**: Right-click handles for quick actions (copy, delete, select)
+- ⌨️ **Keyboard Shortcuts**: Ctrl/Cmd+C to copy, Delete/Backspace to delete selected blocks
+- 🎯 **Visual Feedback**: Highlight effects for hover and selection states
+- 🔔 **Toast Notifications**: User-friendly feedback for actions
+- 📡 **Event System**: Custom events for block selection and deselection
+
+## Installation
+
+The plugin is included with Marzipan by default. Simply enable it in your editor configuration:
+
+```javascript
+import Marzipan from '@pinkpixel/marzipan';
+
+const editor = new Marzipan('#editor', {
+  blockHandles: true  // Enabled by default
+});
+```
+
+## Configuration
+
+You can customize the plugin's behavior and appearance:
+
+```javascript
+const editor = new Marzipan('#editor', {
+  blockHandles: {
+    enabled: true,           // Enable/disable the plugin
+    showOnHover: true,       // Show handles on hover
+    handleOffset: 4,         // Horizontal offset from block's left edge (px)
+    handleSize: 20,          // Handle size (px)
+    colors: {
+      hover: 'rgba(59, 130, 246, 0.1)',      // Hover highlight color
+      selected: 'rgba(59, 130, 246, 0.2)',   // Selection highlight color
+      handle: 'rgba(59, 130, 246, 0.8)',     // Handle background color
+    }
+  }
+});
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | `boolean` | `true` | Enable or disable the plugin |
+| `showOnHover` | `boolean` | `true` | Show handles when hovering over blocks |
+| `handleOffset` | `number` | `4` | Horizontal offset of handles from the block's left edge (in pixels) |
+| `handleSize` | `number` | `20` | Size of handle buttons (in pixels) |
+| `colors.hover` | `string` | `'rgba(59, 130, 246, 0.1)'` | Background color when hovering over blocks |
+| `colors.selected` | `string` | `'rgba(59, 130, 246, 0.2)'` | Background color for selected blocks |
+| `colors.handle` | `string` | `'rgba(59, 130, 246, 0.8)'` | Background color of handle buttons |
+
+## Usage
+
+### Basic Interactions
+
+#### Mouse Interactions
+
+1. **Hover**: Move your mouse over any markdown block to see its handle appear on the left
+2. **Click Handle**: Click a handle to select the block
+3. **Right-Click Handle**: Right-click to open the context menu with available actions
+4. **Shift+Click Block**: Hold Shift and click anywhere on a block to select it
+
+#### Keyboard Shortcuts
+
+- **Escape**: Deselect the currently selected block
+- **Ctrl/Cmd+C**: Copy the selected block to clipboard
+- **Delete** or **Backspace**: Delete the selected block
+
+### Context Menu Actions
+
+Right-click any handle to access these actions:
+
+- **Copy**: Copy the block's content to clipboard
+- **Delete**: Remove the block from the document
+- **Select**: Select the block (same as clicking the handle)
+
+### Block Types and Icons
+
+Each markdown block type has a unique icon:
+
+| Block Type | Icon | Description |
+|------------|------|-------------|
+| Heading | ⚡ | H1-H6 headers |
+| Paragraph | ¶ | Regular text paragraphs |
+| List Item | • | Bullet and numbered lists |
+| Quote | " | Blockquotes |
+| Code Fence | { | Code fence markers |
+| Code Content | {} | Content inside code blocks |
+| Horizontal Rule | ― | Horizontal lines |
+| Table Row | ⊞ | Table data rows |
+| Table Separator | ═ | Table header separators |
+
+## Programmatic API
+
+Access the plugin instance through your Marzipan editor:
+
+```javascript
+const editor = new Marzipan('#editor', {
+  blockHandles: true
+});
+
+const plugin = editor[0].blockHandlesPlugin;
+```
+
+### Methods
+
+#### `refresh()`
+Rescan blocks and update handle positions.
+
+```javascript
+plugin.refresh();
+```
+
+#### `updateAllHandlePositions()`
+Update positions of all handles (useful after scroll or resize).
+
+```javascript
+plugin.updateAllHandlePositions();
+```
+
+#### `getSelectedBlock()`
+Get the currently selected block.
+
+```javascript
+const block = plugin.getSelectedBlock();
+if (block) {
+  console.log('Selected block:', block.type, block.lineStart, block.lineEnd);
+}
+```
+
+#### `getAllBlocks()`
+Get all blocks tracked by the plugin.
+
+```javascript
+const blocks = plugin.getAllBlocks();
+console.log(`Found ${blocks.length} blocks`);
+```
+
+#### `enable()`
+Enable the plugin.
+
+```javascript
+plugin.enable();
+```
+
+#### `disable()`
+Disable the plugin and remove all handles.
+
+```javascript
+plugin.disable();
+```
+
+#### `destroy()`
+Clean up and remove the plugin completely.
+
+```javascript
+plugin.destroy();
+```
+
+### Events
+
+Listen for block selection events:
+
+```javascript
+const preview = editor[0].preview;
+
+preview.addEventListener('blockSelected', (e) => {
+  console.log('Block selected:', e.detail.blockId, e.detail.block);
+});
+
+preview.addEventListener('blockDeselected', (e) => {
+  console.log('Block deselected:', e.detail.blockId);
+});
+```
+
+### Block Object Structure
+
+Each block object contains:
+
+```typescript
+interface BlockHandle {
+  id: string;              // Unique block identifier
+  type: string;            // Block type (heading, paragraph, etc.)
+  lineStart: number;       // Starting line number in editor
+  lineEnd: number;         // Ending line number in editor
+  element: HTMLElement;    // DOM element for the block
+  handleElement: HTMLElement | null;  // Handle DOM element
+}
+```
+
+## Advanced Usage
+
+### Custom Handle Styling
+
+You can override handle styles with CSS:
+
+```css
+/* Customize handle appearance */
+.mz-block-handle {
+  border: 2px solid white;
+  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.2);
+}
+
+/* Style specific block types */
+.mz-block-handle-heading {
+  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+}
+
+.mz-block-handle-quote {
+  background: #10b981;
+}
+```
+
+### Conditional Enable/Disable
+
+Enable handles only for certain conditions:
+
+```javascript
+const editor = new Marzipan('#editor', {
+  blockHandles: {
+    enabled: window.innerWidth > 768  // Only on desktop
+  }
+});
+
+// Toggle based on user preference
+window.addEventListener('resize', () => {
+  if (window.innerWidth > 768) {
+    editor[0].blockHandlesPlugin?.enable();
+  } else {
+    editor[0].blockHandlesPlugin?.disable();
+  }
+});
+```
+
+### Integrate with Custom Actions
+
+```javascript
+const preview = editor[0].preview;
+
+preview.addEventListener('blockSelected', (e) => {
+  const block = e.detail.block;
+  
+  // Add custom toolbar for selected block
+  showCustomToolbar(block);
+  
+  // Highlight corresponding line in editor
+  highlightEditorLines(block.lineStart, block.lineEnd);
+});
+
+preview.addEventListener('blockDeselected', () => {
+  hideCustomToolbar();
+  clearEditorHighlights();
+});
+```
+
+## Browser Compatibility
+
+The Block Handles Plugin requires:
+
+- Modern browser with ES6+ support
+- `navigator.clipboard` API for copy functionality
+- CSS Grid support for handle positioning
+
+Supported browsers:
+- Chrome/Edge 90+
+- Firefox 88+
+- Safari 14+
+
+## Troubleshooting
+
+### Handles Not Appearing
+
+1. Verify the plugin is enabled:
+   ```javascript
+   console.log(editor[0].blockHandlesPlugin);
+   ```
+
+2. Check if block metadata is present:
+   ```javascript
+   const blocks = editor[0].preview.querySelectorAll('[data-block-id]');
+   console.log('Blocks found:', blocks.length);
+   ```
+
+3. Ensure preview has relative positioning:
+   ```javascript
+   console.log(getComputedStyle(editor[0].preview).position);
+   ```
+
+### Handles Misaligned
+
+Call `updateAllHandlePositions()` after DOM changes:
+
+```javascript
+editor[0].blockHandlesPlugin.updateAllHandlePositions();
+```
+
+### Performance Issues
+
+If you notice performance issues with many blocks:
+
+1. Disable hover effects:
+   ```javascript
+   blockHandles: { showOnHover: false }
+   ```
+
+2. Throttle position updates on scroll
+
+## License
+
+Apache 2.0
+
+## Credits
+
+Created by **Pink Pixel** as part of the Marzipan markdown editor.
+
+- Website: [pinkpixel.dev](https://pinkpixel.dev)
+- GitHub: [@pinkpixel-dev](https://github.com/pinkpixel-dev)

package/docs/index.md

@@ -0,0 +1,95 @@
+---
+layout: home
+
+hero:
+  name: "🧁 Marzipan"
+  text: "Framework-agnostic markdown editor"
+  tagline: "Live overlay preview, zero runtime dependencies, and batteries-included formatting actions."
+  image:
+    src: /logo.png
+    alt: Marzipan Logo
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /quick-start
+    - theme: alt
+      text: API Reference
+      link: /api
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/pinkpixel-dev/marzipan
+
+features:
+  - icon: 🔷
+    title: Pure TypeScript Core
+    details: Ships typed ESM builds and declaration files with zero runtime dependencies.
+  - icon: ⚡
+    title: First-Party Actions
+    details: Formatting helpers live in src/actions and export with the library — no extra installs needed.
+  - icon: 🧩
+    title: Plugin Library
+    details: Production-ready plugins for tables, Mermaid, syntax highlighting, media helpers, and more.
+  - icon: 👁️
+    title: Overlay Preview
+    details: Renders markdown directly over the textarea so alignment never drifts.
+  - icon: 🎨
+    title: Themeable UI
+    details: Includes Solar (light) and Cave (dark) themes, plus accent swatch tooling for custom palettes.
+  - icon: 🛝
+    title: Demo Bakeshop
+    details: A Vite + React playground that exercises every option and plugin in a live environment.
+---
+
+## Quick Install
+
+```bash
+npm install @pinkpixel/marzipan
+```
+
+## Create Your First Editor
+
+```ts
+import { Marzipan } from '@pinkpixel/marzipan';
+
+const [editor] = new Marzipan('#my-textarea', {
+  toolbar: true,
+  theme: 'cave',
+  smartLists: true,
+});
+```
+
+## Use the Bundled Actions
+
+```ts
+import { actions } from '@pinkpixel/marzipan';
+
+const textarea = document.querySelector('textarea')!;
+actions.toggleBold(textarea);
+```
+
+## Add a Plugin
+
+```ts
+import { tablePlugin } from '@pinkpixel/marzipan/plugins/tablePlugin';
+
+new Marzipan('#editor', {
+  plugins: [tablePlugin()],
+});
+```
+
+## Bundled Plugins
+
+| Plugin | Description |
+|--------|-------------|
+| `tablePlugin` | Toolbar-driven table generator with inline editing controls |
+| `tableGridPlugin` | Grid overlay for rapid column/row creation |
+| `tableGeneratorPlugin` | Quick GFM table inserter with prompt-driven sizing |
+| `tinyHighlightPlugin` | Zero-runtime syntax highlighting for fenced code blocks |
+| `accentSwatchPlugin` | Synced accent palette picker |
+| `imageManagerPlugin` | Dropzone and gallery UI for inserting images and managing uploads |
+| `imagePickerPlugin` | Toolbar button for inserting images via URL or optional uploader callback |
+| `mermaidPlugin` | Diagram rendering via ESM import |
+| `mermaidExternalPlugin` | Mermaid integration via CDN script tag |
+| `BlockHandlesPlugin` | Interactive block manipulation with visual handles, context menus, and keyboard shortcuts |
+
+See the full [Plugin Catalogue](/plugins) for configuration details.

package/docs/plugins.md

@@ -4,6 +4,7 @@ Marzipan ships first-party plugins from the `src/plugins` directory. Each plugin
 
 ## Using a plugin
 
+### Individual plugin imports (recommended)
 ```ts
 import { Marzipan } from '@pinkpixel/marzipan';
 import { tablePlugin } from '@pinkpixel/marzipan/plugins/tablePlugin';
@@ -17,6 +18,28 @@ new Marzipan('#editor', {
 });
 ```
 
+### Main package imports (convenience)
+```ts
+import { Marzipan, tablePlugin, mermaidPlugin } from '@pinkpixel/marzipan';
+
+new Marzipan('#editor', {
+  plugins: [tablePlugin(), mermaidPlugin()],
+});
+```
+
+### Namespace imports (all plugins)
+```ts
+import { Marzipan, plugins } from '@pinkpixel/marzipan';
+
+new Marzipan('#editor', {
+  plugins: [
+    plugins.tablePlugin(),
+    plugins.mermaidPlugin(),
+    plugins.accentSwatchPlugin(),
+  ],
+});
+```
+
 Every factory returns an object that Marzipan consumes internally. You can mix and match plugins freely.
 
 ## Available plugins
@@ -24,6 +47,7 @@ Every factory returns an object that Marzipan consumes internally. You can mix a
 | Plugin | Import Path | Description |
 |--------|-------------|-------------|
 | `accentSwatchPlugin` | `@pinkpixel/marzipan/plugins/accentSwatchPlugin` | Adds a palette picker for accent colours and syncs with the toolbar + stats bar. |
+| `BlockHandlesPlugin` | `@pinkpixel/marzipan/plugins/block-handles` | Interactive block manipulation with visual handles, context menus, and keyboard shortcuts. See [Block Handles](./block-handles.md) for full documentation. |
 | `imageManagerPlugin` | `@pinkpixel/marzipan/plugins/imageManagerPlugin` | Dropzone and gallery UI for inserting images and managing uploads. |
 | `imagePickerPlugin` | `@pinkpixel/marzipan/plugins/imagePickerPlugin` | Toolbar button for inserting images via URL or optional uploader callback. |
 | `mermaidPlugin` | `@pinkpixel/marzipan/plugins/mermaidPlugin` | Lazy-loads Mermaid from npm/ESM and renders diagrams inline. |

package/docs/types.d.ts

@@ -1,6 +1,6 @@
 /**
  * TypeScript definitions for Marzipan markdown editor
- * @version 1.0.7
+ * @version 1.0.9
  * @author Pink Pixel
  */