superdoc-macros 0.1.0

package/dist/snippets/snippets.js

@@ -0,0 +1,38 @@
+const VARIABLE_PATTERN = /\{\{\s*([\p{L}\p{N}_-]+)\s*\}\}/gu;
+export function renderSnippet(text, context = {}) {
+    const now = context.now ?? new Date();
+    return text.replace(VARIABLE_PATTERN, (whole, rawName) => {
+        const name = rawName.toLowerCase();
+        switch (name) {
+            case 'date':
+                return now.toLocaleDateString('he-IL');
+            case 'time':
+                return now.toLocaleTimeString('he-IL', { hour: '2-digit', minute: '2-digit' });
+            case 'datetime':
+                return `${now.toLocaleDateString('he-IL')} ${now.toLocaleTimeString('he-IL', { hour: '2-digit', minute: '2-digit' })}`;
+            case 'selection':
+                return context.selectionText ?? '';
+            default: {
+                const value = context.variables?.[rawName] ?? context.variables?.[name];
+                return value ?? whole;
+            }
+        }
+    });
+}
+/** האם הקטע משתמש ב-`{{selection}}` — ואז ההרחבה צריכה לקרוא את הבחירה. */
+export function usesSelection(text) {
+    return /\{\{\s*selection\s*\}\}/iu.test(text);
+}
+/** מרחיבה קטע במיקום הסמן. */
+export async function expandSnippet(host, snippet, options = {}) {
+    // הבחירה נקראת רק כשנחוצה: חילוץ טקסט הבחירה עולה בביצועים במנוע.
+    const selectionText = usesSelection(snippet.text)
+        ? (await host.getSelection({ includeText: true })).text
+        : undefined;
+    const rendered = renderSnippet(snippet.text, {
+        variables: options.variables,
+        selectionText,
+        now: options.now,
+    });
+    return host.insertText(rendered);
+}

package/dist/storage.d.ts

@@ -0,0 +1,24 @@
+/**
+ * שמירת המאקרו, ההקלטות והקטעים. ברירת המחדל: localStorage; הממשק ניתן
+ * להחלפה כדי שמארח יוכל לשמור בקובץ (למשל ב-workspace של תוסף אוצריא).
+ */
+import type { RecordedMacro, SavedScript, Snippet } from './types.js';
+export interface PersistedMacroState {
+    version: 1;
+    scripts: SavedScript[];
+    recordings: RecordedMacro[];
+    snippets: Snippet[];
+}
+export interface MacroStorage {
+    /** `null` כשאין מצב שמור או כשהשמור אינו קריא. */
+    load(): PersistedMacroState | null;
+    save(state: PersistedMacroState): void;
+}
+export declare function emptyState(): PersistedMacroState;
+/** מפענחת מצב שמור. `null` על כל צורה לא צפויה — לא זורקת. */
+export declare function parsePersistedState(json: string): PersistedMacroState | null;
+export declare const DEFAULT_STORAGE_KEY = "superdoc-macros:v1";
+/** localStorage עם הגנות: גישה חסומה או מלאה אינה מפילה את הערכה. */
+export declare function createLocalStorage(key?: string, storage?: Pick<Storage, 'getItem' | 'setItem'>): MacroStorage;
+/** אחסון בזיכרון — לבדיקות ולמצבים שבהם אין persistence. */
+export declare function createMemoryStorage(): MacroStorage;

package/dist/storage.js

@@ -0,0 +1,65 @@
+export function emptyState() {
+    return { version: 1, scripts: [], recordings: [], snippets: [] };
+}
+function isValidState(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const state = value;
+    return (state.version === 1 &&
+        Array.isArray(state.scripts) &&
+        Array.isArray(state.recordings) &&
+        Array.isArray(state.snippets));
+}
+/** מפענחת מצב שמור. `null` על כל צורה לא צפויה — לא זורקת. */
+export function parsePersistedState(json) {
+    try {
+        const parsed = JSON.parse(json);
+        return isValidState(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export const DEFAULT_STORAGE_KEY = 'superdoc-macros:v1';
+/** localStorage עם הגנות: גישה חסומה או מלאה אינה מפילה את הערכה. */
+export function createLocalStorage(key = DEFAULT_STORAGE_KEY, storage) {
+    const backing = () => {
+        if (storage)
+            return storage;
+        try {
+            return globalThis.localStorage ?? null;
+        }
+        catch {
+            return null;
+        }
+    };
+    return {
+        load() {
+            try {
+                const raw = backing()?.getItem(key);
+                return raw ? parsePersistedState(raw) : null;
+            }
+            catch {
+                return null;
+            }
+        },
+        save(state) {
+            try {
+                backing()?.setItem(key, JSON.stringify(state));
+            }
+            catch (error) {
+                console.warn('[superdoc-macros] שמירת המאקרו נכשלה', error);
+            }
+        },
+    };
+}
+/** אחסון בזיכרון — לבדיקות ולמצבים שבהם אין persistence. */
+export function createMemoryStorage() {
+    let saved = null;
+    return {
+        load: () => (saved ? JSON.parse(JSON.stringify(saved)) : null),
+        save(state) {
+            saved = JSON.parse(JSON.stringify(state));
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,119 @@
+/**
+ * החוזים המשותפים של הערכה.
+ *
+ * `MacroHost` הוא נקודת החיבור היחידה לעורך: כל שלוש היכולות (סקריפטים,
+ * מקליט, קטעי טקסט) עובדות מולו ולא מול SuperDoc ישירות. כך אפשר לבדוק את
+ * הערכה עם כפיל בזיכרון, וכך מארח אחר (גרסת מנוע אחרת, עורך אחר) מתחבר
+ * במימוש אחד של הממשק הזה.
+ */
+/** תוצאת פעולה. אותה צורה כמו `CommandOutcome` של otzaria-word-editor. */
+export type MacroOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+    reason?: string;
+};
+/** תצלום הבחירה במסמך ברגע הקריאה. */
+export interface SelectionSnapshot {
+    /** הטקסט המסומן. `''` כשאין בחירה או כשלא התבקש. */
+    text: string;
+    /** האם יש טווח מסומן ולא רק סמן. */
+    hasRange: boolean;
+    /** מזהה הפסקה שהבחירה מתחילה בה, או `null`. */
+    blockId: string | null;
+    /** היעד שפעולות כתיבה (`insert`) צורכות. אטום — נמסר חזרה למנוע כמו שהוא. */
+    selectionTarget: unknown | null;
+    /** האם הבחירה ריקה (סמן בלבד). */
+    empty: boolean;
+}
+/** אירוע הקלדה שהמארח מדווח למקליט ולהשלמה האוטומטית. */
+export type TextInputEvent = {
+    kind: 'insert-text';
+    text: string;
+} | {
+    kind: 'insert-paragraph';
+} | {
+    kind: 'delete-backward';
+} | {
+    kind: 'delete-forward';
+};
+/**
+ * מה שהערכה צריכה מהעורך. מימוש ל-SuperDoc v2 נמצא ב-`createSuperdocHost`;
+ * לבדיקות יש כפיל בזיכרון.
+ */
+export interface MacroHost {
+    commands: {
+        /** האם המנוע מכיר את הפקודה. */
+        has(id: string): boolean;
+        /** מריצה פקודה מהקטלוג של המנוע ומחזירה תוצאה מנורמלת. */
+        execute(id: string, payload?: unknown): Promise<MacroOutcome>;
+        /** מזהי הפקודות המוכרות, אם המארח יודע למנות אותם. */
+        ids(): readonly string[];
+    };
+    /** מכניסה טקסט במיקום הסמן (או בסוף המסמך כשאין סמן). */
+    insertText(text: string): Promise<MacroOutcome>;
+    /** מוחקת תווים לאחור מהסמן. */
+    deleteBackward(count: number): Promise<MacroOutcome>;
+    /** תצלום הבחירה הנוכחית. לעולם לא זורקת. */
+    getSelection(options?: {
+        includeText?: boolean;
+    }): Promise<SelectionSnapshot>;
+    /** מחליפה את כל המופעים של `query` ב-`replacement`. מחזירה כמה הוחלפו. */
+    replaceAll(query: string, replacement: string): Promise<{
+        ok: boolean;
+        replaced: number;
+        message?: string;
+    }>;
+    /** הטקסט המלא של גוף המסמך. `''` כשאינו זמין. */
+    getDocumentText(): Promise<string>;
+    /** מאזינה לכל פקודה שהמנוע מריץ (מכל מקור). מחזירה פונקציית ביטול. */
+    onCommand(listener: (id: string, payload: unknown) => void): () => void;
+    /** מאזינה להקלדה במסמך. מחזירה פונקציית ביטול. */
+    onTextInput(listener: (event: TextInputEvent) => void): () => void;
+}
+/** צעד אחד במאקרו מוקלט. JSON-serializable במלואו. */
+export type MacroStep = {
+    type: 'command';
+    id: string;
+    payload?: unknown;
+} | {
+    type: 'insert-text';
+    text: string;
+} | {
+    type: 'insert-paragraph';
+} | {
+    type: 'delete-backward';
+    count: number;
+} | {
+    type: 'delete-forward';
+    count: number;
+};
+/** מאקרו מוקלט, כפי שהוא נשמר ומיובא/מיוצא. */
+export interface RecordedMacro {
+    version: 1;
+    id: string;
+    name: string;
+    /** ISO-8601. */
+    createdAt?: string;
+    shortcut?: string;
+    steps: MacroStep[];
+}
+/** מאקרו כתוב — סקריפט JavaScript שרץ מול ה-API של הערכה. */
+export interface SavedScript {
+    id: string;
+    name: string;
+    source: string;
+    shortcut?: string;
+}
+/** קטע טקסט (Snippet / AutoText). */
+export interface Snippet {
+    id: string;
+    name: string;
+    /** תוכן הקטע. תומך במשתני `{{...}}` — ראו `renderSnippet`. */
+    text: string;
+    /** מילת הפעלה להשלמה אוטומטית: הקלדת המילה ואחריה רווח מחליפה אותה בתוכן. */
+    trigger?: string;
+    /** קיצור מקלדת, למשל `Ctrl+Alt+1`. */
+    shortcut?: string;
+}

package/dist/types.js

@@ -0,0 +1,9 @@
+/**
+ * החוזים המשותפים של הערכה.
+ *
+ * `MacroHost` הוא נקודת החיבור היחידה לעורך: כל שלוש היכולות (סקריפטים,
+ * מקליט, קטעי טקסט) עובדות מולו ולא מול SuperDoc ישירות. כך אפשר לבדוק את
+ * הערכה עם כפיל בזיכרון, וכך מארח אחר (גרסת מנוע אחרת, עורך אחר) מתחבר
+ * במימוש אחד של הממשק הזה.
+ */
+export {};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "superdoc-macros",
+  "version": "0.1.0",
+  "description": "Macro toolkit for SuperDoc-based editors: sandboxed scripted macros, a Word-style macro recorder, and snippets with auto-text expansion.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepare": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/palmoni5/superdoc-macros.git"
+  },
+  "keywords": [
+    "superdoc",
+    "macros",
+    "macro-recorder",
+    "snippets",
+    "autotext",
+    "docx",
+    "editor",
+    "otzaria"
+  ],
+  "devDependencies": {
+    "typescript": "^5.7.2",
+    "vitest": "^3.2.4"
+  }
+}