tiptap-model-language 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,207 @@
+import { FieldSchema } from 'model-language';
+export { DataSnapshot, FieldDef, FieldSchema, MLType, Diagnostic as MlDiagnostic, Range as MlRange, Severity as MlSeverity, ParseResult, Quickfix, RenderOptions, RenderResult, ValidateOptions, ValidateResult, parse, render, serialize, validate } from 'model-language';
+import { Extension } from '@tiptap/core';
+
+type MlFieldType = "string" | "number" | "datetime" | "boolean" | "enum" | "array";
+interface MlField {
+    key: string;
+    type: MlFieldType;
+    /** Friendly label for the chip / autocomplete row. */
+    label: string;
+    /** Allowed values for enum fields (used only for hints). */
+    values?: string[];
+}
+interface MlNamespace {
+    key: string;
+    label: string;
+    /** Runtime-only namespace (e.g. flow.*) — never autocompleted or flagged. */
+    dynamic?: boolean;
+    fields: MlField[];
+}
+declare const CONTACT_NAMESPACE_KEY = "contact";
+declare const FLOW_NAMESPACE_KEY = "flow";
+/** Fixed namespaces — schema is constant across orgs. */
+declare const STATIC_NAMESPACES: MlNamespace[];
+interface MlFilter {
+    name: string;
+    hint: string;
+    /** Placeholder args appended on insert, e.g. `: "there"`. */
+    argTemplate?: string;
+    /** Value types this filter accepts (`"any"` = always offered). */
+    inputs: MlFieldType[] | "any";
+    /** Resulting type (for chaining `a | f1 | f2`); omit = preserves input. */
+    output?: MlFieldType;
+}
+/** Example `date` format tokens. The engine uses Intl/LDML tokens (lowercase
+ *  `yyyy`, `dd`; `EEEE` weekday; `MM`; 24h `HH`, 12h `hh`) — NOT moment/dayjs
+ *  style — plus `[literal]` escaping. Offered as insert suggestions. */
+declare const DATE_FORMATS: readonly ["yyyy-MM-dd", "MMM d, yyyy", "HH:mm", "h:mm A", "EEEE"];
+/** Engine filters (model-language). Grouped by input type; wrong input passes
+ *  through unchanged (the engine never throws). */
+declare const ML_FILTERS: MlFilter[];
+interface ParsedFilter {
+    name: string;
+    args: string;
+}
+interface ParsedToken {
+    /** Full path, e.g. "contact.first_name". */
+    path: string;
+    namespace: string;
+    field: string;
+    filters: ParsedFilter[];
+    /** True for control tokens ({{if …}}, {{for …}}, {{/if}}, …). */
+    directive: boolean;
+}
+/** Parse a token's inner text (no braces) into path + filters. */
+declare function parseModelToken(inner: string): ParsedToken;
+
+interface ModelTokenOption {
+    /** Inner token text to insert (no braces). */
+    insert: string;
+    label: string;
+    hint: string;
+    group: string;
+    kind: "path" | "filter" | "block";
+    /** Terminal step → wrap `{{…}}` and finish. Non-terminal → keep the token
+     *  open so the next stage (operator / value / filter) can autocomplete. */
+    close: boolean;
+}
+/**
+ * Staged autocomplete: each pick advances one step and keeps the token open
+ * until a terminal step, so the flow is field → operator → value/filter → done.
+ */
+declare function buildModelOptions(namespaces: MlNamespace[], query: string): ModelTokenOption[];
+
+type DiagnosticSeverity = "error" | "warning" | "info";
+/** A diagnostic collapsed to a single field path (worst severity wins). */
+interface TokenDiagnostic {
+    severity: DiagnosticSeverity;
+    message: string;
+    code: string;
+}
+/** The flat diagnostic shape surfaced to the host via `onResult`. */
+interface TemplateDiagnostic {
+    code: string;
+    severity: DiagnosticSeverity;
+    message: string;
+    fieldPath?: string | null;
+}
+interface ModelValidationResult {
+    diagnostics: TemplateDiagnostic[];
+    maxTokenEstimate: number | null;
+}
+/**
+ * Every user-facing string the extension renders — override any of them for
+ * i18n. Some are templated (they receive the block name / operator / tag).
+ */
+interface ModelLanguageLabels {
+    /** Shown when a value path in a condition isn't followed by an operator. */
+    expectedOperator: string;
+    /** A block opener (`if` / `for` / `#name`) that never closed in scope. */
+    unclosedBlock: (name: string) => string;
+    /** A close/branch tag with no matching opener. */
+    noOpenBlock: (name: string) => string;
+    /** Quick-fix: add a `| default: …` filter. */
+    addDefault: string;
+    /** Quick-fix: replace a mistyped operator. */
+    changeTo: (operator: string) => string;
+    /** Quick-fix: insert a close tag, e.g. `{{/if}}`. */
+    addCloseTag: (tag: string) => string;
+    /** Fallback quick-fix button text. */
+    quickFix: string;
+    /** Empty autocomplete menu. */
+    noMatches: string;
+    /** Severity chip text in the hover tooltip (rendered uppercase). */
+    severity: Record<DiagnosticSeverity, string>;
+}
+interface ModelSyntaxOptions {
+    /** Initial namespaces (autocomplete + highlighting). Static case only — for
+     *  async / changing data push via the `setModelData` command instead. */
+    namespaces: MlNamespace[];
+    /** Initial org field schema (local validation). Static case only — for
+     *  async / changing data push via the `setModelData` command instead. */
+    schema: FieldSchema;
+    /** Disable the local `validate()` pass entirely (structural squiggles stay). */
+    skipValidation: boolean;
+    /** Debounce for the validation pass, ms. */
+    debounceMs: number;
+    /** Which severities to render inline. Default: all three. */
+    severities: DiagnosticSeverity[];
+    /** Override any user-facing string (merged over the English defaults). */
+    labels: Partial<ModelLanguageLabels>;
+    /** Localize an engine diagnostic message (ML001/ML101/…) — return undefined
+     *  to keep the engine's English. Branch on `code`, never on `message`. */
+    translateDiagnostic?: (d: TemplateDiagnostic) => string | undefined;
+    /** Surface hook for the full result (e.g. a diagnostics list + token meter). */
+    onResult?: (result: ModelValidationResult) => void;
+}
+interface ModelSyntaxStorage {
+    timer: ReturnType<typeof setTimeout> | null;
+}
+/** English defaults for every label. */
+declare const DEFAULT_LABELS: ModelLanguageLabels;
+/** Merge host overrides over the English defaults. */
+declare function resolveLabels(overrides?: Partial<ModelLanguageLabels>): ModelLanguageLabels;
+
+/** Friendly chip label for a token: resolves the path to a field label and
+ *  appends a short filter summary ("First name · default"). Control tokens
+ *  ({{if …}}, {{for …}}) render verbatim. */
+declare function modelTokenDisplay(inner: string, namespaces: MlNamespace[]): string;
+type ModelTokenTone = "value" | "directive" | "unknown";
+/** Soft classification for chip colour. `validateTemplate` is authoritative for
+ *  real errors — "unknown" is only a hint when the path can't be resolved. */
+declare function modelTokenTone(inner: string, namespaces: MlNamespace[]): ModelTokenTone;
+
+declare module "@tiptap/core" {
+    interface Commands<ReturnType> {
+        modelSyntax: {
+            /** Push the namespaces (autocomplete + highlighting) and the org field
+             *  schema (local `validate()`). Re-runs validation against the schema. */
+            setModelData: (data: {
+                namespaces: MlNamespace[];
+                schema?: FieldSchema;
+            }) => ReturnType;
+        };
+    }
+}
+/**
+ * Self-contained model-language editing extension. Add it to any Tiptap editor
+ * and it owns the whole experience: raw-text `{{…}}` syntax highlighting, a `{{`
+ * autocomplete (variables / filters / control blocks), `flow.<cardId>` hover
+ * highlighting, hover diagnostics + quick-fixes, and live validation via the
+ * `model-language` package. The host pushes namespaces + schema via
+ * `setModelData`; everything else is configured through options.
+ */
+declare const ModelSyntax: Extension<ModelSyntaxOptions, ModelSyntaxStorage>;
+
+type HlKind = "keyword" | "operator" | "math" | "string" | "number" | "filter" | "func" | "path" | "punct";
+interface HlToken {
+    start: number;
+    end: number;
+    kind: HlKind;
+}
+declare const HL_CLASS: Record<HlKind, string>;
+/** Tokenize the raw inner text of a `{{ … }}` (no braces) into coloured spans. */
+declare function tokenizeExpression(s: string): HlToken[];
+
+/**
+ * Merge the autocomplete namespaces (so every offered field — incl. dynamic
+ * `flow.*` — is known to `validate()` and never flagged ML101) with the
+ * authoritative org schema (accurate type / nullable / enum values).
+ */
+declare function buildValidateSchema(namespaces: MlNamespace[], orgSchema: FieldSchema): FieldSchema;
+
+/** Collapse diagnostics to their field path, keeping the worst severity. */
+declare function diagnosticsByPath(diags: TemplateDiagnostic[]): Map<string, TokenDiagnostic>;
+/**
+ * Type-appropriate `| default: …` filter for the "Add default" quick-fix, so
+ * an enum/array defaults to a real option, a number to `0`, etc.
+ */
+declare function defaultFilterFor(field?: MlField): string;
+/**
+ * Closest operator whose name starts with the mistyped word (shortest wins),
+ * e.g. "contai" → "contains". Null when nothing plausibly matches.
+ */
+declare function suggestOperator(word: string): string | null;
+
+export { CONTACT_NAMESPACE_KEY, DATE_FORMATS, DEFAULT_LABELS, type DiagnosticSeverity, FLOW_NAMESPACE_KEY, HL_CLASS, type HlKind, ML_FILTERS, type MlField, type MlFieldType, type MlFilter, type MlNamespace, type ModelLanguageLabels, ModelSyntax, type ModelSyntaxOptions, type ModelTokenOption, type ModelTokenTone, type ModelValidationResult, type ParsedToken, STATIC_NAMESPACES, type TemplateDiagnostic, type TokenDiagnostic, buildModelOptions, buildValidateSchema, defaultFilterFor, diagnosticsByPath, modelTokenDisplay, modelTokenTone, parseModelToken, resolveLabels, suggestOperator, tokenizeExpression };

package/dist/index.d.ts

@@ -0,0 +1,207 @@
+import { FieldSchema } from 'model-language';
+export { DataSnapshot, FieldDef, FieldSchema, MLType, Diagnostic as MlDiagnostic, Range as MlRange, Severity as MlSeverity, ParseResult, Quickfix, RenderOptions, RenderResult, ValidateOptions, ValidateResult, parse, render, serialize, validate } from 'model-language';
+import { Extension } from '@tiptap/core';
+
+type MlFieldType = "string" | "number" | "datetime" | "boolean" | "enum" | "array";
+interface MlField {
+    key: string;
+    type: MlFieldType;
+    /** Friendly label for the chip / autocomplete row. */
+    label: string;
+    /** Allowed values for enum fields (used only for hints). */
+    values?: string[];
+}
+interface MlNamespace {
+    key: string;
+    label: string;
+    /** Runtime-only namespace (e.g. flow.*) — never autocompleted or flagged. */
+    dynamic?: boolean;
+    fields: MlField[];
+}
+declare const CONTACT_NAMESPACE_KEY = "contact";
+declare const FLOW_NAMESPACE_KEY = "flow";
+/** Fixed namespaces — schema is constant across orgs. */
+declare const STATIC_NAMESPACES: MlNamespace[];
+interface MlFilter {
+    name: string;
+    hint: string;
+    /** Placeholder args appended on insert, e.g. `: "there"`. */
+    argTemplate?: string;
+    /** Value types this filter accepts (`"any"` = always offered). */
+    inputs: MlFieldType[] | "any";
+    /** Resulting type (for chaining `a | f1 | f2`); omit = preserves input. */
+    output?: MlFieldType;
+}
+/** Example `date` format tokens. The engine uses Intl/LDML tokens (lowercase
+ *  `yyyy`, `dd`; `EEEE` weekday; `MM`; 24h `HH`, 12h `hh`) — NOT moment/dayjs
+ *  style — plus `[literal]` escaping. Offered as insert suggestions. */
+declare const DATE_FORMATS: readonly ["yyyy-MM-dd", "MMM d, yyyy", "HH:mm", "h:mm A", "EEEE"];
+/** Engine filters (model-language). Grouped by input type; wrong input passes
+ *  through unchanged (the engine never throws). */
+declare const ML_FILTERS: MlFilter[];
+interface ParsedFilter {
+    name: string;
+    args: string;
+}
+interface ParsedToken {
+    /** Full path, e.g. "contact.first_name". */
+    path: string;
+    namespace: string;
+    field: string;
+    filters: ParsedFilter[];
+    /** True for control tokens ({{if …}}, {{for …}}, {{/if}}, …). */
+    directive: boolean;
+}
+/** Parse a token's inner text (no braces) into path + filters. */
+declare function parseModelToken(inner: string): ParsedToken;
+
+interface ModelTokenOption {
+    /** Inner token text to insert (no braces). */
+    insert: string;
+    label: string;
+    hint: string;
+    group: string;
+    kind: "path" | "filter" | "block";
+    /** Terminal step → wrap `{{…}}` and finish. Non-terminal → keep the token
+     *  open so the next stage (operator / value / filter) can autocomplete. */
+    close: boolean;
+}
+/**
+ * Staged autocomplete: each pick advances one step and keeps the token open
+ * until a terminal step, so the flow is field → operator → value/filter → done.
+ */
+declare function buildModelOptions(namespaces: MlNamespace[], query: string): ModelTokenOption[];
+
+type DiagnosticSeverity = "error" | "warning" | "info";
+/** A diagnostic collapsed to a single field path (worst severity wins). */
+interface TokenDiagnostic {
+    severity: DiagnosticSeverity;
+    message: string;
+    code: string;
+}
+/** The flat diagnostic shape surfaced to the host via `onResult`. */
+interface TemplateDiagnostic {
+    code: string;
+    severity: DiagnosticSeverity;
+    message: string;
+    fieldPath?: string | null;
+}
+interface ModelValidationResult {
+    diagnostics: TemplateDiagnostic[];
+    maxTokenEstimate: number | null;
+}
+/**
+ * Every user-facing string the extension renders — override any of them for
+ * i18n. Some are templated (they receive the block name / operator / tag).
+ */
+interface ModelLanguageLabels {
+    /** Shown when a value path in a condition isn't followed by an operator. */
+    expectedOperator: string;
+    /** A block opener (`if` / `for` / `#name`) that never closed in scope. */
+    unclosedBlock: (name: string) => string;
+    /** A close/branch tag with no matching opener. */
+    noOpenBlock: (name: string) => string;
+    /** Quick-fix: add a `| default: …` filter. */
+    addDefault: string;
+    /** Quick-fix: replace a mistyped operator. */
+    changeTo: (operator: string) => string;
+    /** Quick-fix: insert a close tag, e.g. `{{/if}}`. */
+    addCloseTag: (tag: string) => string;
+    /** Fallback quick-fix button text. */
+    quickFix: string;
+    /** Empty autocomplete menu. */
+    noMatches: string;
+    /** Severity chip text in the hover tooltip (rendered uppercase). */
+    severity: Record<DiagnosticSeverity, string>;
+}
+interface ModelSyntaxOptions {
+    /** Initial namespaces (autocomplete + highlighting). Static case only — for
+     *  async / changing data push via the `setModelData` command instead. */
+    namespaces: MlNamespace[];
+    /** Initial org field schema (local validation). Static case only — for
+     *  async / changing data push via the `setModelData` command instead. */
+    schema: FieldSchema;
+    /** Disable the local `validate()` pass entirely (structural squiggles stay). */
+    skipValidation: boolean;
+    /** Debounce for the validation pass, ms. */
+    debounceMs: number;
+    /** Which severities to render inline. Default: all three. */
+    severities: DiagnosticSeverity[];
+    /** Override any user-facing string (merged over the English defaults). */
+    labels: Partial<ModelLanguageLabels>;
+    /** Localize an engine diagnostic message (ML001/ML101/…) — return undefined
+     *  to keep the engine's English. Branch on `code`, never on `message`. */
+    translateDiagnostic?: (d: TemplateDiagnostic) => string | undefined;
+    /** Surface hook for the full result (e.g. a diagnostics list + token meter). */
+    onResult?: (result: ModelValidationResult) => void;
+}
+interface ModelSyntaxStorage {
+    timer: ReturnType<typeof setTimeout> | null;
+}
+/** English defaults for every label. */
+declare const DEFAULT_LABELS: ModelLanguageLabels;
+/** Merge host overrides over the English defaults. */
+declare function resolveLabels(overrides?: Partial<ModelLanguageLabels>): ModelLanguageLabels;
+
+/** Friendly chip label for a token: resolves the path to a field label and
+ *  appends a short filter summary ("First name · default"). Control tokens
+ *  ({{if …}}, {{for …}}) render verbatim. */
+declare function modelTokenDisplay(inner: string, namespaces: MlNamespace[]): string;
+type ModelTokenTone = "value" | "directive" | "unknown";
+/** Soft classification for chip colour. `validateTemplate` is authoritative for
+ *  real errors — "unknown" is only a hint when the path can't be resolved. */
+declare function modelTokenTone(inner: string, namespaces: MlNamespace[]): ModelTokenTone;
+
+declare module "@tiptap/core" {
+    interface Commands<ReturnType> {
+        modelSyntax: {
+            /** Push the namespaces (autocomplete + highlighting) and the org field
+             *  schema (local `validate()`). Re-runs validation against the schema. */
+            setModelData: (data: {
+                namespaces: MlNamespace[];
+                schema?: FieldSchema;
+            }) => ReturnType;
+        };
+    }
+}
+/**
+ * Self-contained model-language editing extension. Add it to any Tiptap editor
+ * and it owns the whole experience: raw-text `{{…}}` syntax highlighting, a `{{`
+ * autocomplete (variables / filters / control blocks), `flow.<cardId>` hover
+ * highlighting, hover diagnostics + quick-fixes, and live validation via the
+ * `model-language` package. The host pushes namespaces + schema via
+ * `setModelData`; everything else is configured through options.
+ */
+declare const ModelSyntax: Extension<ModelSyntaxOptions, ModelSyntaxStorage>;
+
+type HlKind = "keyword" | "operator" | "math" | "string" | "number" | "filter" | "func" | "path" | "punct";
+interface HlToken {
+    start: number;
+    end: number;
+    kind: HlKind;
+}
+declare const HL_CLASS: Record<HlKind, string>;
+/** Tokenize the raw inner text of a `{{ … }}` (no braces) into coloured spans. */
+declare function tokenizeExpression(s: string): HlToken[];
+
+/**
+ * Merge the autocomplete namespaces (so every offered field — incl. dynamic
+ * `flow.*` — is known to `validate()` and never flagged ML101) with the
+ * authoritative org schema (accurate type / nullable / enum values).
+ */
+declare function buildValidateSchema(namespaces: MlNamespace[], orgSchema: FieldSchema): FieldSchema;
+
+/** Collapse diagnostics to their field path, keeping the worst severity. */
+declare function diagnosticsByPath(diags: TemplateDiagnostic[]): Map<string, TokenDiagnostic>;
+/**
+ * Type-appropriate `| default: …` filter for the "Add default" quick-fix, so
+ * an enum/array defaults to a real option, a number to `0`, etc.
+ */
+declare function defaultFilterFor(field?: MlField): string;
+/**
+ * Closest operator whose name starts with the mistyped word (shortest wins),
+ * e.g. "contai" → "contains". Null when nothing plausibly matches.
+ */
+declare function suggestOperator(word: string): string | null;
+
+export { CONTACT_NAMESPACE_KEY, DATE_FORMATS, DEFAULT_LABELS, type DiagnosticSeverity, FLOW_NAMESPACE_KEY, HL_CLASS, type HlKind, ML_FILTERS, type MlField, type MlFieldType, type MlFilter, type MlNamespace, type ModelLanguageLabels, ModelSyntax, type ModelSyntaxOptions, type ModelTokenOption, type ModelTokenTone, type ModelValidationResult, type ParsedToken, STATIC_NAMESPACES, type TemplateDiagnostic, type TokenDiagnostic, buildModelOptions, buildValidateSchema, defaultFilterFor, diagnosticsByPath, modelTokenDisplay, modelTokenTone, parseModelToken, resolveLabels, suggestOperator, tokenizeExpression };