@notehub.md/cli 0.1.9 → 0.1.11

package/templates/docs/en/04-widgets.md

@@ -0,0 +1,318 @@
+# Widgets (Portals)
+
+Portals are custom React components that render inline within the editor, replacing matched text patterns.
+
+## How Portals Work
+
+1. You define a **regex pattern** that matches text in the document
+2. You provide a **React component** to render for each match
+3. Notehub replaces matched text with your component in **view mode**
+4. When the cursor enters the match, it switches to **edit mode** (shows source)
+
+```
+View Mode:     [████████░░] 80%     ← Your rendered component
+Edit Mode:     [progress:80]        ← Source text visible when cursor inside
+```
+
+## Registering a Portal
+
+Use the `editor:register-portal` API:
+
+```typescript
+await ctx.invokeApi('editor:register-portal', {
+    id: 'unique-id',           // Unique identifier
+    regex: /regex-pattern/g,   // Pattern to match (MUST have global flag 'g')
+    component: ReactComponent  // Component to render
+});
+```
+
+## Component Props
+
+Your component receives the regex match array:
+
+```typescript
+interface WidgetProps {
+    match: RegExpExecArray;
+}
+```
+
+The `match` array contains:
+- `match[0]` - Full matched string
+- `match[1]`, `match[2]`, ... - Capture groups
+
+## Complete Example: Progress Bar
+
+```typescript
+import { NotehubPlugin, PluginContext } from '@notehub/api';
+import React from 'react';
+
+// Widget component
+const ProgressBar: React.FC<{ match: RegExpExecArray }> = ({ match }) => {
+    const percentage = parseInt(match[1], 10);
+    
+    return (
+        <span style={{
+            display: 'inline-flex',
+            alignItems: 'center',
+            gap: '8px',
+            padding: '2px 8px',
+            background: 'var(--nh-bg-surface)',
+            borderRadius: '4px',
+        }}>
+            <span style={{
+                width: '100px',
+                height: '8px',
+                background: 'var(--nh-bg-secondary)',
+                borderRadius: '4px',
+                overflow: 'hidden',
+            }}>
+                <span style={{
+                    width: `${percentage}%`,
+                    height: '100%',
+                    background: 'var(--nh-accent-primary)',
+                    display: 'block',
+                    borderRadius: '4px',
+                    transition: 'width 0.3s ease',
+                }} />
+            </span>
+            <span style={{ fontSize: '12px', color: 'var(--nh-text-muted)' }}>
+                {percentage}%
+            </span>
+        </span>
+    );
+};
+
+// Plugin
+export default class ProgressBarPlugin extends NotehubPlugin {
+    async onload(ctx: PluginContext): Promise<void> {
+        // Match: [progress:XX] where XX is a number
+        await ctx.invokeApi('editor:register-portal', {
+            id: 'progress-bar',
+            regex: /\[progress:(\d+)\]/g,
+            component: ProgressBar
+        });
+        
+        await ctx.invokeApi('logger:info', 'ProgressBar', 'Portal registered');
+    }
+    
+    async onunload(): Promise<void> {
+        // Portal is automatically unregistered!
+    }
+}
+```
+
+**Usage in documents:**
+```markdown
+Project completion: [progress:75]
+```
+
+---
+
+## Example: Clickable Button
+
+```typescript
+const ButtonWidget: React.FC<{ match: RegExpExecArray }> = ({ match }) => {
+    const label = match[1];
+    const action = match[2];
+    
+    const handleClick = async () => {
+        // You can't access ctx here directly, but you can use events
+        // or call a registered API
+        console.log(`Button clicked: ${action}`);
+    };
+    
+    return (
+        <button
+            onClick={handleClick}
+            style={{
+                background: 'var(--nh-accent-primary)',
+                color: 'var(--nh-button-text, #fff)',
+                border: 'none',
+                borderRadius: '4px',
+                padding: '4px 12px',
+                cursor: 'pointer',
+                fontSize: 'inherit',
+            }}
+        >
+            {label}
+        </button>
+    );
+};
+
+// Register
+await ctx.invokeApi('editor:register-portal', {
+    id: 'btn-widget',
+    regex: /\[btn:([^\]:]+):([^\]]+)\]/g,
+    component: ButtonWidget
+});
+```
+
+**Usage:**
+```markdown
+Click here: [btn:Submit:action-submit]
+```
+
+---
+
+## Example: Status Badge
+
+```typescript
+const StatusBadge: React.FC<{ match: RegExpExecArray }> = ({ match }) => {
+    const status = match[1].toLowerCase();
+    
+    const colors: Record<string, { bg: string; text: string }> = {
+        done: { bg: '#22c55e20', text: '#22c55e' },
+        'in-progress': { bg: '#f59e0b20', text: '#f59e0b' },
+        todo: { bg: '#6b728020', text: '#6b7280' },
+    };
+    
+    const style = colors[status] || colors.todo;
+    
+    return (
+        <span style={{
+            padding: '2px 8px',
+            borderRadius: '12px',
+            fontSize: '12px',
+            fontWeight: 500,
+            background: style.bg,
+            color: style.text,
+        }}>
+            {match[1]}
+        </span>
+    );
+};
+
+await ctx.invokeApi('editor:register-portal', {
+    id: 'status-badge',
+    regex: /\[status:([^\]]+)\]/g,
+    component: StatusBadge
+});
+```
+
+**Usage:**
+```markdown
+Task 1 [status:Done]
+Task 2 [status:In-Progress]
+Task 3 [status:TODO]
+```
+
+---
+
+## Regex Best Practices
+
+### 1. Always use global flag (`g`)
+
+```typescript
+// ✅ Good
+/\[progress:(\d+)\]/g
+
+// ❌ Bad - won't match multiple occurrences
+/\[progress:(\d+)\]/
+```
+
+### 2. Use capture groups for dynamic content
+
+```typescript
+// Captures two groups: label and value
+/\[meter:([^:]+):(\d+)\]/g
+// match[1] = label
+// match[2] = value
+```
+
+### 3. Escape special characters
+
+```typescript
+// Match [!note] - brackets need escape
+/\[!note\]/g
+```
+
+### 4. Be specific to avoid false matches
+
+```typescript
+// ✅ Good - specific pattern
+/\[progress:(\d{1,3})\]/g
+
+// ❌ Bad - too greedy
+/\[.*\]/g  // Matches ALL bracketed content!
+```
+
+---
+
+## Styling Tips
+
+### Use CSS Variables
+
+Access theme colors for consistent styling:
+
+```typescript
+style={{
+    background: 'var(--nh-bg-surface)',
+    color: 'var(--nh-text-primary)',
+    border: '1px solid var(--nh-border-subtle)',
+}}
+```
+
+Available CSS variables:
+- `--nh-bg-main`, `--nh-bg-sidebar`, `--nh-bg-surface`
+- `--nh-text-primary`, `--nh-text-secondary`, `--nh-text-muted`
+- `--nh-accent-primary`, `--nh-accent-secondary`
+- `--nh-border-accent`, `--nh-border-subtle`
+
+### Keep it inline
+
+Widgets render inline with text. Use `display: inline-flex` or `inline-block`:
+
+```typescript
+style={{
+    display: 'inline-flex',
+    alignItems: 'center',
+    verticalAlign: 'middle',
+}}
+```
+
+---
+
+## Interaction Handling
+
+### Don't prevent default click behavior
+
+Widgets exist inside CodeMirror. Avoid stopping event propagation:
+
+```typescript
+// ✅ Good - simple click handler
+onClick={() => doSomething()}
+
+// ⚠️ Caution with event manipulation
+onClick={(e) => {
+    e.stopPropagation(); // May cause issues!
+    doSomething();
+}}
+```
+
+### Use data attributes for identification
+
+```typescript
+<span data-widget-id="my-widget" data-value={match[1]}>
+    ...
+</span>
+```
+
+---
+
+## Unregistering Widgets
+
+Portals are **automatically unregistered** when your plugin unloads.
+
+For manual unregistration:
+
+```typescript
+await ctx.invokeApi('editor:unregister-portal', 'my-portal-id');
+```
+
+---
+
+## Next Steps
+
+- Add **[Settings](05-settings.md)** to configure your widgets
+- Learn about **[Context Menus](06-context-menu.md)**
+- See **[Complete Examples](07-examples.md)**

package/templates/docs/en/05-settings.md

@@ -0,0 +1,303 @@
+# Settings Integration
+
+Add configuration options to your plugin with the Settings API.
+
+## Settings Structure
+
+Settings are organized in a hierarchy:
+
+```
+Settings Modal
+└── Tab (e.g., "My Plugin")
+    └── Group (e.g., "Appearance")
+        └── Item (e.g., "Enable dark mode")
+```
+
+## Step 1: Register a Tab
+
+```typescript
+await ctx.invokeApi('settings:register-tab', {
+    id: 'my-plugin',            // Unique identifier
+    label: 'My Plugin',         // Display name
+    icon: 'puzzle',             // Lucide icon name (kebab-case)
+    order: 100                  // Position (lower = first)
+});
+```
+
+## Step 2: Register a Group
+
+```typescript
+await ctx.invokeApi('settings:register-group', {
+    id: 'my-plugin-general',    // Unique identifier
+    tabId: 'my-plugin',         // Parent tab ID
+    label: 'General',           // Display name
+    order: 0                    // Position within tab
+});
+```
+
+## Step 3: Register Items
+
+### Toggle (Boolean)
+
+```typescript
+await ctx.invokeApi('settings:register-item', {
+    key: 'my-plugin.enabled',
+    type: 'toggle',
+    label: 'Enable plugin',
+    description: 'Turn the plugin on or off',
+    groupId: 'my-plugin-general',
+    order: 0,
+    defaultValue: true
+});
+```
+
+### Text Input
+
+```typescript
+await ctx.invokeApi('settings:register-item', {
+    key: 'my-plugin.prefix',
+    type: 'text',
+    label: 'Custom prefix',
+    description: 'Text to prepend to all items',
+    placeholder: 'Enter prefix...',
+    groupId: 'my-plugin-general',
+    order: 1,
+    defaultValue: ''
+});
+```
+
+### Number Input
+
+```typescript
+await ctx.invokeApi('settings:register-item', {
+    key: 'my-plugin.max-items',
+    type: 'number',
+    label: 'Maximum items',
+    description: 'Limit the number of items shown',
+    groupId: 'my-plugin-general',
+    order: 2,
+    min: 1,
+    max: 100,
+    step: 1,
+    defaultValue: 10
+});
+```
+
+### Select (Dropdown)
+
+```typescript
+await ctx.invokeApi('settings:register-item', {
+    key: 'my-plugin.theme',
+    type: 'select',
+    label: 'Widget theme',
+    description: 'Choose the visual style',
+    groupId: 'my-plugin-general',
+    order: 3,
+    options: [
+        { label: 'Default', value: 'default' },
+        { label: 'Compact', value: 'compact' },
+        { label: 'Minimal', value: 'minimal' }
+    ],
+    defaultValue: 'default'
+});
+```
+
+### Color Picker
+
+```typescript
+await ctx.invokeApi('settings:register-item', {
+    key: 'my-plugin.accent-color',
+    type: 'color',
+    label: 'Accent color',
+    description: 'Primary color for highlights',
+    groupId: 'my-plugin-general',
+    order: 4,
+    defaultValue: '#3b82f6'
+});
+```
+
+---
+
+## Reading Settings Values
+
+Use the `config:get` API to read settings:
+
+```typescript
+const isEnabled = await ctx.invokeApi<boolean>('config:get', 'my-plugin.enabled', true);
+const prefix = await ctx.invokeApi<string>('config:get', 'my-plugin.prefix', '');
+const maxItems = await ctx.invokeApi<number>('config:get', 'my-plugin.max-items', 10);
+const theme = await ctx.invokeApi<string>('config:get', 'my-plugin.theme', 'default');
+const color = await ctx.invokeApi<string>('config:get', 'my-plugin.accent-color', '#3b82f6');
+```
+
+---
+
+## Complete Example
+
+```typescript
+import { NotehubPlugin, PluginContext } from '@notehub/api';
+
+export default class ConfigurablePlugin extends NotehubPlugin {
+    async onload(ctx: PluginContext): Promise<void> {
+        // Register settings tab
+        await ctx.invokeApi('settings:register-tab', {
+            id: 'my-plugin',
+            label: 'My Plugin',
+            icon: 'settings-2',
+            order: 100
+        });
+        
+        // Register settings group
+        await ctx.invokeApi('settings:register-group', {
+            id: 'my-plugin-appearance',
+            tabId: 'my-plugin',
+            label: 'Appearance',
+            order: 0
+        });
+        
+        // Register settings items
+        await ctx.invokeApi('settings:register-items', [
+            {
+                key: 'my-plugin.show-icons',
+                type: 'toggle',
+                label: 'Show icons',
+                groupId: 'my-plugin-appearance',
+                order: 0,
+                defaultValue: true
+            },
+            {
+                key: 'my-plugin.icon-size',
+                type: 'select',
+                label: 'Icon size',
+                groupId: 'my-plugin-appearance',
+                order: 1,
+                options: [
+                    { label: 'Small', value: 16 },
+                    { label: 'Medium', value: 24 },
+                    { label: 'Large', value: 32 }
+                ],
+                defaultValue: 24
+            }
+        ]);
+        
+        // Use settings values
+        const showIcons = await ctx.invokeApi<boolean>('config:get', 'my-plugin.show-icons', true);
+        const iconSize = await ctx.invokeApi<number>('config:get', 'my-plugin.icon-size', 24);
+        
+        await ctx.invokeApi('logger:info', 'MyPlugin', 
+            `Settings: showIcons=${showIcons}, iconSize=${iconSize}`);
+    }
+    
+    async onunload(): Promise<void> {
+        // Settings items are automatically unregistered!
+    }
+}
+```
+
+---
+
+## Batch Registration
+
+For multiple items, use the batch APIs:
+
+```typescript
+// Register multiple tabs
+await ctx.invokeApi('settings:register-tabs', [
+    { id: 'tab1', label: 'Tab 1', icon: 'star', order: 0 },
+    { id: 'tab2', label: 'Tab 2', icon: 'heart', order: 1 }
+]);
+
+// Register multiple groups
+await ctx.invokeApi('settings:register-groups', [
+    { id: 'group1', tabId: 'tab1', label: 'Group 1', order: 0 },
+    { id: 'group2', tabId: 'tab1', label: 'Group 2', order: 1 }
+]);
+
+// Register multiple items
+await ctx.invokeApi('settings:register-items', [/* items array */]);
+```
+
+---
+
+## Custom Settings View
+
+For complex settings UI, register a custom React component:
+
+```typescript
+const MyCustomSettings: React.FC = () => {
+    return (
+        <div>
+            <h2>Custom Settings UI</h2>
+            {/* Your custom settings interface */}
+        </div>
+    );
+};
+
+await ctx.invokeApi('settings:register-custom-view', {
+    tabId: 'my-plugin',
+    view: MyCustomSettings
+});
+```
+
+---
+
+## Programmatic Control
+
+```typescript
+// Open settings modal
+await ctx.invokeApi('settings:open');
+
+// Close settings modal
+await ctx.invokeApi('settings:close');
+
+// Toggle settings modal
+await ctx.invokeApi('settings:toggle');
+```
+
+---
+
+## Type Definitions
+
+```typescript
+interface SettingsTabDef {
+    id: string;          // Unique identifier
+    label: string;       // Display text
+    icon: string;        // Lucide icon name
+    order: number;       // Sort order
+}
+
+interface SettingsGroupDef {
+    id: string;          // Unique identifier
+    tabId: string;       // Parent tab ID
+    label: string;       // Display text
+    order: number;       // Sort order
+}
+
+interface SettingsItemDef {
+    key: string;         // Config key (e.g., 'my-plugin.option')
+    type: 'toggle' | 'text' | 'number' | 'select' | 'color';
+    label: string;       // Display text
+    description?: string;
+    groupId: string;     // Parent group ID
+    order: number;       // Sort order
+    defaultValue?: unknown;
+    
+    // For 'text'
+    placeholder?: string;
+    
+    // For 'number'
+    min?: number;
+    max?: number;
+    step?: number;
+    
+    // For 'select'
+    options?: Array<{ label: string; value: unknown }>;
+}
+```
+
+---
+
+## Next Steps
+
+- Learn about **[Context Menu](06-context-menu.md)** integration
+- See **[Complete Examples](07-examples.md)**