@atom63/slides 0.1.1 → 0.3.0

package/dist/editor/index.d.ts

@@ -40,43 +40,61 @@ declare function stripImports(body: string): string;
 declare function compileDeck(source: string): Promise<CompileDeckResult>;
 
 interface DeckEditorProps {
-    /** Raw deck MDX source (frontmatter + body with `---` slide separators). */
     source: string;
-    /**
-     * Called with the next source on every edit / template insert. When omitted,
-     * the editor manages source internally (uncontrolled).
-     */
     onChange?: (next: string) => void;
-    /** Debounce window (ms) before recompiling the preview. Default 300. */
     debounceMs?: number;
 }
 /**
- * v0.1 GUI deck editor for @atom63/slides.
- *
- * Two panes:
- *  - left: a LIVE preview rendered by `SlidesPlayer`, compiled from the source
- *    at runtime via {@link compileDeck} (browser-safe frontmatter split +
- *    strip-imports + `@mdx-js/mdx` evaluate, with slide components injected
- *    through MDX context).
- *  - right: a `<textarea>` editing surface, a registry-driven template palette
- *    (click inserts the template's MDX snippet at the end of the source), and a
- *    light/dark theme toggle for the preview container.
- *
- * Compilation is debounced and resilient: the LAST good preview is retained on
- * a failed compile and the error is surfaced in a non-blocking banner, so a bad
- * keystroke never blanks or crashes the editor.
- *
- * The editor's own chrome is styled by self-contained plain CSS shipped as a
- * side-effect import — consumers must `import '@atom63/slides/editor/styles'`
- * (the CSS is intentionally NOT bundled into the JS so it isn't orphaned by the
- * build, mirroring how `@atom63/slides` ships `./styles`).
- *
- * A `<textarea>` is intentional
- * for v0.1; CodeMirror (syntax highlight, structured editing) is a future
- * upgrade. Structured per-slide form editing and template-switch-by-form are
- * explicitly v2 — the source textarea is the only editing surface here.
+ * Backward-compatible editor: DeckSurface locked to Edit mode. The unified
+ * surface ({@link DeckSurface}) is the preferred API; this remains for existing
+ * consumers.
  */
-declare function DeckEditor({ source: sourceProp, onChange, debounceMs }: DeckEditorProps): react_jsx_runtime.JSX.Element;
+declare function DeckEditor({ source, onChange, debounceMs }: DeckEditorProps): react_jsx_runtime.JSX.Element;
+
+type DeckSurfaceMode = 'present' | 'edit';
+interface DeckSurfaceProps {
+    /**
+     * Raw deck MDX source (frontmatter + `---`-separated slide body). The single
+     * canonical input for both Present and Edit modes.
+     *
+     * **Controlled vs. uncontrolled:**
+     * - When `onChange` is provided the surface is **controlled** — the parent
+     *   owns source state and must feed back the updated string on each change.
+     * - When `onChange` is omitted the surface is **uncontrolled** and
+     *   **present-only**: `source` is read once on mount and later prop changes
+     *   are ignored. This is the production / read-only contract.
+     */
+    source: string;
+    /**
+     * Called with the next source string on every edit or template insert
+     * (in-memory, per-keystroke). Presence of this prop **enables Edit mode**
+     * and makes the surface controlled — the parent holds source state.
+     * When omitted the surface is present-only (no edit chrome, no keyboard
+     * shortcut to enter Edit).
+     */
+    onChange?: (next: string) => void;
+    /**
+     * Called on an **explicit** save action (Save button or Cmd/Ctrl-S in Edit
+     * mode). This is the persistence hook, distinct from the per-keystroke
+     * `onChange`. Wire it to the dev write-back plugin (or any async persistence
+     * layer) to flush the source to disk on demand. No-op / absent in a
+     * production build.
+     */
+    onSave?: (source: string) => void | Promise<void>;
+    /**
+     * The mode the surface starts in. Defaults to `'present'`. Forced to
+     * `'present'` when `onChange` is absent (present-only surfaces cannot enter
+     * Edit mode).
+     */
+    initialMode?: DeckSurfaceMode;
+    /**
+     * Debounce window in milliseconds before recompiling the preview after a
+     * source change. Defaults to `300`. Pass `0` in tests to compile
+     * synchronously on the next microtask tick.
+     */
+    debounceMs?: number;
+}
+declare function DeckSurface({ source: sourceProp, onChange, onSave, initialMode, debounceMs, }: DeckSurfaceProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Synthesize a minimal, valid MDX usage example from a template's schema.
@@ -93,4 +111,4 @@ declare function toInsertSnippet(t: TemplateDef): string;
 /** Map of `templateName -> insertable MDX snippet`, built from the live registry. */
 declare const templateSnippets: Record<string, string>;
 
-export { type CompileDeckResult, DeckEditor, type DeckEditorProps, compileDeck, stripImports, synthExample, templateSnippets, toInsertSnippet };
+export { type CompileDeckResult, DeckEditor, type DeckEditorProps, DeckSurface, type DeckSurfaceMode, type DeckSurfaceProps, compileDeck, stripImports, synthExample, templateSnippets, toInsertSnippet };