@kedataindo/docflow-plugins 0.0.3 → 0.0.5

package/dist/citations.d.cts

@@ -0,0 +1,132 @@
+import { CslItemData } from '@kedataindo/docflow-core';
+
+type CitationMode = 'normal' | 'author-only' | 'suppress-author';
+/**
+ * Structured citation attributes stored on citation/footnote nodes. Nodes
+ * store references only — every rendered string is derived by the engine
+ * from CSL-JSON sources + the active CSL style (phase-6 plan §2 decision 1).
+ */
+interface CitationAttrs {
+    sourceId: string | null;
+    locator?: string;
+    label?: string;
+    mode?: CitationMode;
+    prefix?: string;
+    suffix?: string;
+}
+interface CiteEngineOptions {
+    sources?: CslItemData[];
+    style?: string;
+}
+interface CitationCluster {
+    citationId: string;
+    attrs: CitationAttrs;
+}
+type ChangeListener = () => void;
+/** Stable, unique-enough id for a citation cluster instance in a document. */
+declare function nextCitationId(): string;
+declare function sanitizeCiteprocHtml(html: string): string;
+/**
+ * Document-scoped citation engine. Wraps citeproc-js: holds the CSL-JSON
+ * source map + active style, recomputes ALL clusters in document order on
+ * every change (correct ibid./short-form handling for note styles), and
+ * emits a single 'change' so every node view repaints from one source of
+ * truth (phase-6 plan §2 decision 2).
+ *
+ * The engine is plain TS — no editor/DOM imports — so it is unit-testable
+ * headlessly and reusable from any host.
+ */
+declare class CiteEngine {
+    private sources;
+    private style;
+    private clusters;
+    private order;
+    private rendered;
+    private bibliography;
+    private listeners;
+    constructor(options?: CiteEngineOptions);
+    getStyle(): string;
+    /** 'note' styles (Chicago notes-bib) cite via footnotes; 'in-text' cite inline. */
+    isNoteStyle(): boolean;
+    getSource(id: string): CslItemData | undefined;
+    getSourceIds(): string[];
+    getCitedSourceIds(): string[];
+    /** Live style switch: reload the CSL, recompute everything, repaint (6A-7). */
+    setStyle(styleId: string): void;
+    updateSources(sources: CslItemData[], emit?: boolean): void;
+    onChange(cb: ChangeListener): () => void;
+    /**
+     * Replace the cluster registry with the current document state, in
+     * document order. The caller (editor sync) walks the PM doc; the engine
+     * recomputes only when the ordered signature actually changed.
+     */
+    syncCitations(ordered: CitationCluster[]): boolean;
+    private lastSignature;
+    /** Last computed in-text/note text for a cluster ('' when unknown/missing). */
+    renderCluster(citationId: string): string;
+    /** Bibliography entries (citeproc-sorted), sanitized HTML strings. */
+    getBibliography(): string[];
+    private emitChange;
+    /**
+     * Rebuild a fresh CSL.Engine and replay all clusters in document order.
+     * citeproc is stateful (ibid., subsequent-short forms), so a full ordered
+     * replay is the only reliable way to keep every cluster consistent after
+     * any edit — the same derived-view pattern used for pagination/collab.
+     */
+    private recompute;
+}
+
+/**
+ * Pure citation-node spec builder — NO tiptap imports. Lives apart from
+ * `citation.ts` so the standalone `citations.ts` entrypoint (server-side
+ * export bundle, see `apps/server/src/routes/export.ts`) can re-export it
+ * WITHOUT pulling the editor extension graph into the server bundle.
+ *
+ * Two consumers:
+ *   - `citation.ts` `insertCitationWithSource` (dispatches its OWN transaction
+ *     per interactive insert, Phase 6 behavior unchanged).
+ *   - The 7E-4 sidebar content-array insert path, which builds N specs and
+ *     dispatches ONCE via `view.dispatch(tr.insertContent(array))` (the plan
+ *     §2 decision 6 — N markers must NOT become N transactions / N Yjs
+ *     history entries).
+ *
+ * The helper is the single source of truth for the note-vs-inline branching
+ * so the sidebar does not duplicate it.
+ */
+
+type CitationNodeSpec = {
+    type: 'footnote' | 'citation';
+    attrs: Record<string, unknown>;
+};
+/**
+ * Build ONE citation node spec (inline `citation` or note-style `footnote`)
+ * WITHOUT dispatching. Returns `null` only if the engine is missing the
+ * schema primitive — `insertCitationWithSource` additionally guards against
+ * `editor.schema.nodes['footnote']` being absent since the helper itself
+ * cannot reach the schema.
+ *
+ * PURE: takes the engine + attrs, returns a node spec, no editor mutation.
+ */
+declare function buildCitationNodes(engine: CiteEngine, attrs: {
+    sourceId: string;
+    locator?: string;
+}): CitationNodeSpec;
+
+interface CslStyleInfo {
+    id: string;
+    name: string;
+    /** 'note' styles render citations as footnotes; 'in-text' render inline. */
+    category: 'note' | 'in-text';
+    xml: string;
+}
+/**
+ * CSL styles bundled with the citation engine. Bundling (instead of runtime
+ * fetch) keeps the editor standalone/offline-capable — the same guarantee the
+ * embedded source snapshot provides (see phase-6 plan §2 decision 5).
+ */
+declare const CSL_STYLES: Record<string, CslStyleInfo>;
+declare const DEFAULT_CSL_STYLE = "chicago-notes-bibliography";
+/** The single bundled locale. Multi-locale rendering is deferred (phase 6 §7). */
+declare const CSL_LOCALE_EN_US: string;
+
+export { CSL_LOCALE_EN_US, CSL_STYLES, type CitationAttrs, type CitationCluster, type CitationMode, CiteEngine, type CiteEngineOptions, type CslStyleInfo, DEFAULT_CSL_STYLE, buildCitationNodes, nextCitationId, sanitizeCiteprocHtml };

package/dist/citations.d.ts

@@ -0,0 +1,132 @@
+import { CslItemData } from '@kedataindo/docflow-core';
+
+type CitationMode = 'normal' | 'author-only' | 'suppress-author';
+/**
+ * Structured citation attributes stored on citation/footnote nodes. Nodes
+ * store references only — every rendered string is derived by the engine
+ * from CSL-JSON sources + the active CSL style (phase-6 plan §2 decision 1).
+ */
+interface CitationAttrs {
+    sourceId: string | null;
+    locator?: string;
+    label?: string;
+    mode?: CitationMode;
+    prefix?: string;
+    suffix?: string;
+}
+interface CiteEngineOptions {
+    sources?: CslItemData[];
+    style?: string;
+}
+interface CitationCluster {
+    citationId: string;
+    attrs: CitationAttrs;
+}
+type ChangeListener = () => void;
+/** Stable, unique-enough id for a citation cluster instance in a document. */
+declare function nextCitationId(): string;
+declare function sanitizeCiteprocHtml(html: string): string;
+/**
+ * Document-scoped citation engine. Wraps citeproc-js: holds the CSL-JSON
+ * source map + active style, recomputes ALL clusters in document order on
+ * every change (correct ibid./short-form handling for note styles), and
+ * emits a single 'change' so every node view repaints from one source of
+ * truth (phase-6 plan §2 decision 2).
+ *
+ * The engine is plain TS — no editor/DOM imports — so it is unit-testable
+ * headlessly and reusable from any host.
+ */
+declare class CiteEngine {
+    private sources;
+    private style;
+    private clusters;
+    private order;
+    private rendered;
+    private bibliography;
+    private listeners;
+    constructor(options?: CiteEngineOptions);
+    getStyle(): string;
+    /** 'note' styles (Chicago notes-bib) cite via footnotes; 'in-text' cite inline. */
+    isNoteStyle(): boolean;
+    getSource(id: string): CslItemData | undefined;
+    getSourceIds(): string[];
+    getCitedSourceIds(): string[];
+    /** Live style switch: reload the CSL, recompute everything, repaint (6A-7). */
+    setStyle(styleId: string): void;
+    updateSources(sources: CslItemData[], emit?: boolean): void;
+    onChange(cb: ChangeListener): () => void;
+    /**
+     * Replace the cluster registry with the current document state, in
+     * document order. The caller (editor sync) walks the PM doc; the engine
+     * recomputes only when the ordered signature actually changed.
+     */
+    syncCitations(ordered: CitationCluster[]): boolean;
+    private lastSignature;
+    /** Last computed in-text/note text for a cluster ('' when unknown/missing). */
+    renderCluster(citationId: string): string;
+    /** Bibliography entries (citeproc-sorted), sanitized HTML strings. */
+    getBibliography(): string[];
+    private emitChange;
+    /**
+     * Rebuild a fresh CSL.Engine and replay all clusters in document order.
+     * citeproc is stateful (ibid., subsequent-short forms), so a full ordered
+     * replay is the only reliable way to keep every cluster consistent after
+     * any edit — the same derived-view pattern used for pagination/collab.
+     */
+    private recompute;
+}
+
+/**
+ * Pure citation-node spec builder — NO tiptap imports. Lives apart from
+ * `citation.ts` so the standalone `citations.ts` entrypoint (server-side
+ * export bundle, see `apps/server/src/routes/export.ts`) can re-export it
+ * WITHOUT pulling the editor extension graph into the server bundle.
+ *
+ * Two consumers:
+ *   - `citation.ts` `insertCitationWithSource` (dispatches its OWN transaction
+ *     per interactive insert, Phase 6 behavior unchanged).
+ *   - The 7E-4 sidebar content-array insert path, which builds N specs and
+ *     dispatches ONCE via `view.dispatch(tr.insertContent(array))` (the plan
+ *     §2 decision 6 — N markers must NOT become N transactions / N Yjs
+ *     history entries).
+ *
+ * The helper is the single source of truth for the note-vs-inline branching
+ * so the sidebar does not duplicate it.
+ */
+
+type CitationNodeSpec = {
+    type: 'footnote' | 'citation';
+    attrs: Record<string, unknown>;
+};
+/**
+ * Build ONE citation node spec (inline `citation` or note-style `footnote`)
+ * WITHOUT dispatching. Returns `null` only if the engine is missing the
+ * schema primitive — `insertCitationWithSource` additionally guards against
+ * `editor.schema.nodes['footnote']` being absent since the helper itself
+ * cannot reach the schema.
+ *
+ * PURE: takes the engine + attrs, returns a node spec, no editor mutation.
+ */
+declare function buildCitationNodes(engine: CiteEngine, attrs: {
+    sourceId: string;
+    locator?: string;
+}): CitationNodeSpec;
+
+interface CslStyleInfo {
+    id: string;
+    name: string;
+    /** 'note' styles render citations as footnotes; 'in-text' render inline. */
+    category: 'note' | 'in-text';
+    xml: string;
+}
+/**
+ * CSL styles bundled with the citation engine. Bundling (instead of runtime
+ * fetch) keeps the editor standalone/offline-capable — the same guarantee the
+ * embedded source snapshot provides (see phase-6 plan §2 decision 5).
+ */
+declare const CSL_STYLES: Record<string, CslStyleInfo>;
+declare const DEFAULT_CSL_STYLE = "chicago-notes-bibliography";
+/** The single bundled locale. Multi-locale rendering is deferred (phase 6 §7). */
+declare const CSL_LOCALE_EN_US: string;
+
+export { CSL_LOCALE_EN_US, CSL_STYLES, type CitationAttrs, type CitationCluster, type CitationMode, CiteEngine, type CiteEngineOptions, type CslStyleInfo, DEFAULT_CSL_STYLE, buildCitationNodes, nextCitationId, sanitizeCiteprocHtml };

package/dist/citations.js

@@ -0,0 +1,18 @@
+import {
+  CSL_LOCALE_EN_US,
+  CSL_STYLES,
+  CiteEngine,
+  DEFAULT_CSL_STYLE,
+  buildCitationNodes,
+  nextCitationId,
+  sanitizeCiteprocHtml
+} from "./chunk-MZZTJIFJ.js";
+export {
+  CSL_LOCALE_EN_US,
+  CSL_STYLES,
+  CiteEngine,
+  DEFAULT_CSL_STYLE,
+  buildCitationNodes,
+  nextCitationId,
+  sanitizeCiteprocHtml
+};