@formfeed/engine 0.3.9 → 0.3.11

package/types/lib/source-edit.d.cts

@@ -0,0 +1,112 @@
+import type { EngineId } from './types.cjs';
+/**
+ * Editing text from the preview (plan 16 §3). An element whose content is literal text, output tags,
+ * inline children and line breaks — nothing that decides what is printed — is an *editable region*:
+ * the preview shows its text editable and everything else as atomic chips, and the edit comes back
+ * here to be written into the source. Text the user did not change keeps its source bytes, so
+ * indentation, line breaks and character references survive a one-word edit; changed text is
+ * HTML-escaped, and a `{` that could open template syntax is written as `{`. Every result is
+ * parsed again and compared with what the user typed before it is returned.
+ */
+export type RegionRefusal = 'not-an-element' | 'dynamic-tag' | 'void' | 'raw-text' | 'control-flow' | 'block-child' | 'unclosed' | 'no-text' | 'too-large';
+export type ChipKind = 'expression' | 'element' | 'comment' | 'entity';
+export type RegionPart = {
+    kind: 'text';
+    start: number;
+    end: number;
+} | {
+    kind: 'break';
+    start: number;
+    end: number;
+} | {
+    kind: 'chip';
+    start: number;
+    end: number;
+    chip: ChipKind;
+    label: string;
+    inner?: string;
+};
+export interface EditableRegion {
+    /** `t`: the whole content is one `t()` call, and the edit goes into the dictionary. */
+    kind: 'text' | 't';
+    tag: string;
+    /** Offset of the start tag's `<`. */
+    tagStart: number;
+    /** First character of the content, and the `<` of the end tag. */
+    start: number;
+    end: number;
+    /** After the end tag's `>`. */
+    outerEnd: number;
+    parts: RegionPart[];
+    /** `t` regions: the dictionary key and each parameter's expression by name. */
+    key?: string;
+    params?: Record<string, string>;
+}
+/** What the preview shows and sends back: text, a chip by its index among the region's chips, a line break. */
+export type EditItem = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'chip';
+    index: number;
+} | {
+    kind: 'break';
+};
+export interface RegionChip {
+    index: number;
+    kind: ChipKind;
+    /** What the chip stands for: the expression, `<strong>`, a character reference. */
+    label: string;
+    source: string;
+}
+export type ApplyResult = {
+    source: string;
+} | {
+    error: 'chips' | 'invalid';
+};
+/** A region, or why the element at that place is none. */
+export type RegionLookup = EditableRegion | {
+    reason: RegionRefusal;
+};
+/** The region whose start tag's `<` is at `line`/`column` (1-based, as `data-ff-src` names it). */
+export declare function editableRegion(source: string, engine: EngineId, location: {
+    line: number;
+    column: number;
+}): RegionLookup;
+/** The region whose start tag's `<` is at `at`. */
+export declare function editableRegionAt(source: string, engine: EngineId, at: number): RegionLookup;
+/**
+ * The region again after the source changed around it (someone typed in the code editor while the
+ * preview was being edited): found by its unique original markup, or null.
+ */
+export declare function findRegionAgain(source: string, engine: EngineId, outer: string): EditableRegion | null;
+/** The chips of a region in order, with what they stand for. */
+export declare function regionChips(source: string, region: EditableRegion): RegionChip[];
+/** What the preview shows while editing: decoded text (whitespace as written), chips and breaks. */
+export declare function regionItems(source: string, region: EditableRegion): EditItem[];
+/**
+ * Writes edited items back into the region. Chips may be deleted, never reordered or repeated. Text
+ * between the same two chips is diffed against what it was, so only the changed stretch is
+ * rewritten; if the result does not read back as the items (a kept `{` meeting a typed `%`), the
+ * whole content is written anew with every brace escaped.
+ */
+export declare function applyRegionEdit(source: string, engine: EngineId, region: EditableRegion, items: EditItem[]): ApplyResult;
+/** A dictionary text as items: `{name}` placeholders become chips, in order of appearance. */
+export declare function translationItems(text: string): {
+    items: EditItem[];
+    names: string[];
+};
+/** Edited dictionary items back into text: chips become their placeholders again, breaks spaces. */
+export declare function translationText(items: EditItem[], names: string[]): string;
+/**
+ * The value each chip shows while editing, read off the element's rendered text: the text between
+ * the chips must appear in it in order, and exactly one way of placing them must exist. Null when
+ * there is none or more than one (an empty value, a value that repeats a literal): the chips then
+ * show their labels.
+ */
+export declare function chipValues(rendered: string, items: EditItem[]): string[] | null;
+/**
+ * Literal text for a template's HTML, as the design emitter writes it: escaped like an edit from the
+ * preview, so a `{` that could open template syntax is written as `&#123;`.
+ */
+export declare function encodeTemplateText(text: string): string;

package/types/lib/source-edit.d.ts

@@ -0,0 +1,112 @@
+import type { EngineId } from './types.js';
+/**
+ * Editing text from the preview (plan 16 §3). An element whose content is literal text, output tags,
+ * inline children and line breaks — nothing that decides what is printed — is an *editable region*:
+ * the preview shows its text editable and everything else as atomic chips, and the edit comes back
+ * here to be written into the source. Text the user did not change keeps its source bytes, so
+ * indentation, line breaks and character references survive a one-word edit; changed text is
+ * HTML-escaped, and a `{` that could open template syntax is written as `{`. Every result is
+ * parsed again and compared with what the user typed before it is returned.
+ */
+export type RegionRefusal = 'not-an-element' | 'dynamic-tag' | 'void' | 'raw-text' | 'control-flow' | 'block-child' | 'unclosed' | 'no-text' | 'too-large';
+export type ChipKind = 'expression' | 'element' | 'comment' | 'entity';
+export type RegionPart = {
+    kind: 'text';
+    start: number;
+    end: number;
+} | {
+    kind: 'break';
+    start: number;
+    end: number;
+} | {
+    kind: 'chip';
+    start: number;
+    end: number;
+    chip: ChipKind;
+    label: string;
+    inner?: string;
+};
+export interface EditableRegion {
+    /** `t`: the whole content is one `t()` call, and the edit goes into the dictionary. */
+    kind: 'text' | 't';
+    tag: string;
+    /** Offset of the start tag's `<`. */
+    tagStart: number;
+    /** First character of the content, and the `<` of the end tag. */
+    start: number;
+    end: number;
+    /** After the end tag's `>`. */
+    outerEnd: number;
+    parts: RegionPart[];
+    /** `t` regions: the dictionary key and each parameter's expression by name. */
+    key?: string;
+    params?: Record<string, string>;
+}
+/** What the preview shows and sends back: text, a chip by its index among the region's chips, a line break. */
+export type EditItem = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'chip';
+    index: number;
+} | {
+    kind: 'break';
+};
+export interface RegionChip {
+    index: number;
+    kind: ChipKind;
+    /** What the chip stands for: the expression, `<strong>`, a character reference. */
+    label: string;
+    source: string;
+}
+export type ApplyResult = {
+    source: string;
+} | {
+    error: 'chips' | 'invalid';
+};
+/** A region, or why the element at that place is none. */
+export type RegionLookup = EditableRegion | {
+    reason: RegionRefusal;
+};
+/** The region whose start tag's `<` is at `line`/`column` (1-based, as `data-ff-src` names it). */
+export declare function editableRegion(source: string, engine: EngineId, location: {
+    line: number;
+    column: number;
+}): RegionLookup;
+/** The region whose start tag's `<` is at `at`. */
+export declare function editableRegionAt(source: string, engine: EngineId, at: number): RegionLookup;
+/**
+ * The region again after the source changed around it (someone typed in the code editor while the
+ * preview was being edited): found by its unique original markup, or null.
+ */
+export declare function findRegionAgain(source: string, engine: EngineId, outer: string): EditableRegion | null;
+/** The chips of a region in order, with what they stand for. */
+export declare function regionChips(source: string, region: EditableRegion): RegionChip[];
+/** What the preview shows while editing: decoded text (whitespace as written), chips and breaks. */
+export declare function regionItems(source: string, region: EditableRegion): EditItem[];
+/**
+ * Writes edited items back into the region. Chips may be deleted, never reordered or repeated. Text
+ * between the same two chips is diffed against what it was, so only the changed stretch is
+ * rewritten; if the result does not read back as the items (a kept `{` meeting a typed `%`), the
+ * whole content is written anew with every brace escaped.
+ */
+export declare function applyRegionEdit(source: string, engine: EngineId, region: EditableRegion, items: EditItem[]): ApplyResult;
+/** A dictionary text as items: `{name}` placeholders become chips, in order of appearance. */
+export declare function translationItems(text: string): {
+    items: EditItem[];
+    names: string[];
+};
+/** Edited dictionary items back into text: chips become their placeholders again, breaks spaces. */
+export declare function translationText(items: EditItem[], names: string[]): string;
+/**
+ * The value each chip shows while editing, read off the element's rendered text: the text between
+ * the chips must appear in it in order, and exactly one way of placing them must exist. Null when
+ * there is none or more than one (an empty value, a value that repeats a literal): the chips then
+ * show their labels.
+ */
+export declare function chipValues(rendered: string, items: EditItem[]): string[] | null;
+/**
+ * Literal text for a template's HTML, as the design emitter writes it: escaped like an edit from the
+ * preview, so a `{` that could open template syntax is written as `&#123;`.
+ */
+export declare function encodeTemplateText(text: string): string;

package/types/lib/source-positions.d.cts

@@ -5,16 +5,21 @@ import type { EngineId } from './types.cjs';
  * rendered element says where it came from instead of the editor searching the template for it.
  * Elements from a loop all point at the loop body, which is the line that wrote them.
  *
+ * With `editable`, a start tag whose content is a region the preview can edit (plan 16 §3.1,
+ * `editableRegionAt`) also gets `data-ff-edit="text"`, or `data-ff-edit="t"` when its whole content
+ * is one `t()` call.
+ *
  * The annotation must never change what the template means: tags inside template syntax, in
  * blocks whose output is captured or filtered as a string (`{% set %}…{% endset %}`, `{% filter %}`,
  * `{% capture %}`), in raw and comment blocks, in `<script>`/`<style>`/`<textarea>`/`<title>` and
  * HTML comments, closing tags, declarations, tags whose name is built by template syntax and tags
- * that already carry the attribute stay untouched. Removing the attribute from the rendered output
+ * that already carry the attribute stay untouched. Removing the attributes from the rendered output
  * gives the document of the original source. Preview only: saved versions, API renders and the
- * render-worker never see it.
+ * render-worker never see them.
  */
 export type SourceFile = 'body' | 'header' | 'footer';
 export declare const sourceAttribute = "data-ff-src";
+export declare const editAttribute = "data-ff-edit";
 export interface SourceLocation {
     file: SourceFile;
     /** 1-based, as Monaco counts. */
@@ -22,6 +27,10 @@ export interface SourceLocation {
     /** 1-based UTF-16 column of the tag's `<`. */
     column: number;
 }
+export interface AnnotateOptions {
+    /** Mark editable regions with `data-ff-edit` as well (the preview's edit mode). */
+    editable?: boolean;
+}
 /** Parses a `data-ff-src` value; null when it is not one. */
 export declare function parseSourceAttribute(value: string | null | undefined): SourceLocation | null;
-export declare function annotateSourcePositions(source: string, engine: EngineId, file: SourceFile): string;
+export declare function annotateSourcePositions(source: string, engine: EngineId, file: SourceFile, options?: AnnotateOptions): string;

package/types/lib/source-positions.d.ts

@@ -5,16 +5,21 @@ import type { EngineId } from './types.js';
  * rendered element says where it came from instead of the editor searching the template for it.
  * Elements from a loop all point at the loop body, which is the line that wrote them.
  *
+ * With `editable`, a start tag whose content is a region the preview can edit (plan 16 §3.1,
+ * `editableRegionAt`) also gets `data-ff-edit="text"`, or `data-ff-edit="t"` when its whole content
+ * is one `t()` call.
+ *
  * The annotation must never change what the template means: tags inside template syntax, in
  * blocks whose output is captured or filtered as a string (`{% set %}…{% endset %}`, `{% filter %}`,
  * `{% capture %}`), in raw and comment blocks, in `<script>`/`<style>`/`<textarea>`/`<title>` and
  * HTML comments, closing tags, declarations, tags whose name is built by template syntax and tags
- * that already carry the attribute stay untouched. Removing the attribute from the rendered output
+ * that already carry the attribute stay untouched. Removing the attributes from the rendered output
  * gives the document of the original source. Preview only: saved versions, API renders and the
- * render-worker never see it.
+ * render-worker never see them.
  */
 export type SourceFile = 'body' | 'header' | 'footer';
 export declare const sourceAttribute = "data-ff-src";
+export declare const editAttribute = "data-ff-edit";
 export interface SourceLocation {
     file: SourceFile;
     /** 1-based, as Monaco counts. */
@@ -22,6 +27,10 @@ export interface SourceLocation {
     /** 1-based UTF-16 column of the tag's `<`. */
     column: number;
 }
+export interface AnnotateOptions {
+    /** Mark editable regions with `data-ff-edit` as well (the preview's edit mode). */
+    editable?: boolean;
+}
 /** Parses a `data-ff-src` value; null when it is not one. */
 export declare function parseSourceAttribute(value: string | null | undefined): SourceLocation | null;
-export declare function annotateSourcePositions(source: string, engine: EngineId, file: SourceFile): string;
+export declare function annotateSourcePositions(source: string, engine: EngineId, file: SourceFile, options?: AnnotateOptions): string;

package/types/lib/source-scan.d.cts

@@ -0,0 +1,61 @@
+import type { EngineId } from './types.cjs';
+/**
+ * A template source read as HTML with template constructs in it: the scanner that finds start tags
+ * for click-to-source (`source-positions.ts`) and the regions text can be edited in from the preview
+ * (`source-edit.ts`). It knows each engine's delimiters, string literals inside expressions, raw and
+ * comment blocks, and blocks whose output is captured as a string. Internal to the engine.
+ */
+export declare const tagName: RegExp;
+/** Elements whose content the HTML parser reads as text, so a `<b>` inside is not an element. */
+export declare const rawTextElements: Set<string>;
+/**
+ * What a template construct is, for a reader that has to tell output from control flow: `output` is
+ * a value printed in place (`{{ x }}`, `{{{ x }}}`, `{{t 'k'}}`), `comment` prints nothing, and
+ * `statement` is everything that decides what is printed (`{% if %}`, `{{#each}}`, `{{else}}`,
+ * `{{> partial}}`, raw blocks).
+ */
+export type TemplateConstruct = {
+    type: 'output';
+    end: number;
+    inner: string;
+} | {
+    type: 'comment';
+    end: number;
+} | {
+    type: 'statement';
+    end: number;
+    keyword?: string;
+};
+export declare class Scanner {
+    private readonly source;
+    private readonly engine;
+    private readonly n;
+    private readonly escapes;
+    constructor(source: string, engine: EngineId);
+    /** End of the template construct starting at `at` (with a capturing block's body), or null. */
+    skipTemplate(at: number): number | null;
+    /** The construct starting at `at` and what kind it is, or null when `{` starts none. */
+    classify(at: number): TemplateConstruct | null;
+    /** Index after `close`, stepping over template constructs; the end of the source when missing. */
+    skipTo(from: number, close: string): number;
+    /** Index after the `>` that ends a tag, stepping over quoted values and template constructs. */
+    tagEnd(from: number): number;
+    /** Index of the `</name` that closes a raw text element. */
+    skipToClosingTag(from: number, name: string): number;
+    private captures;
+    private blockEnd;
+    private templateTag;
+    /** `{{{{raw}}}} … {{{{/raw}}}}`: the content is never parsed. */
+    private handlebarsRawBlock;
+    private indexAfter;
+    /** End of an expression or statement; a `close` inside a string literal does not end it. */
+    private expressionEnd;
+}
+/** Offsets where lines start; `\r\n`, `\n` and a lone `\r` all end a line, as in Monaco. */
+export declare function lineStarts(source: string): number[];
+export declare function locate(starts: number[], offset: number): {
+    line: number;
+    column: number;
+};
+/** The offset of a 1-based line and column, or null when the source has no such place. */
+export declare function offsetOf(starts: number[], sourceLength: number, line: number, column: number): number | null;

package/types/lib/source-scan.d.ts

@@ -0,0 +1,61 @@
+import type { EngineId } from './types.js';
+/**
+ * A template source read as HTML with template constructs in it: the scanner that finds start tags
+ * for click-to-source (`source-positions.ts`) and the regions text can be edited in from the preview
+ * (`source-edit.ts`). It knows each engine's delimiters, string literals inside expressions, raw and
+ * comment blocks, and blocks whose output is captured as a string. Internal to the engine.
+ */
+export declare const tagName: RegExp;
+/** Elements whose content the HTML parser reads as text, so a `<b>` inside is not an element. */
+export declare const rawTextElements: Set<string>;
+/**
+ * What a template construct is, for a reader that has to tell output from control flow: `output` is
+ * a value printed in place (`{{ x }}`, `{{{ x }}}`, `{{t 'k'}}`), `comment` prints nothing, and
+ * `statement` is everything that decides what is printed (`{% if %}`, `{{#each}}`, `{{else}}`,
+ * `{{> partial}}`, raw blocks).
+ */
+export type TemplateConstruct = {
+    type: 'output';
+    end: number;
+    inner: string;
+} | {
+    type: 'comment';
+    end: number;
+} | {
+    type: 'statement';
+    end: number;
+    keyword?: string;
+};
+export declare class Scanner {
+    private readonly source;
+    private readonly engine;
+    private readonly n;
+    private readonly escapes;
+    constructor(source: string, engine: EngineId);
+    /** End of the template construct starting at `at` (with a capturing block's body), or null. */
+    skipTemplate(at: number): number | null;
+    /** The construct starting at `at` and what kind it is, or null when `{` starts none. */
+    classify(at: number): TemplateConstruct | null;
+    /** Index after `close`, stepping over template constructs; the end of the source when missing. */
+    skipTo(from: number, close: string): number;
+    /** Index after the `>` that ends a tag, stepping over quoted values and template constructs. */
+    tagEnd(from: number): number;
+    /** Index of the `</name` that closes a raw text element. */
+    skipToClosingTag(from: number, name: string): number;
+    private captures;
+    private blockEnd;
+    private templateTag;
+    /** `{{{{raw}}}} … {{{{/raw}}}}`: the content is never parsed. */
+    private handlebarsRawBlock;
+    private indexAfter;
+    /** End of an expression or statement; a `close` inside a string literal does not end it. */
+    private expressionEnd;
+}
+/** Offsets where lines start; `\r\n`, `\n` and a lone `\r` all end a line, as in Monaco. */
+export declare function lineStarts(source: string): number[];
+export declare function locate(starts: number[], offset: number): {
+    line: number;
+    column: number;
+};
+/** The offset of a 1-based line and column, or null when the source has no such place. */
+export declare function offsetOf(starts: number[], sourceLength: number, line: number, column: number): number | null;

package/types/lib/translation.d.cts

@@ -0,0 +1,17 @@
+/** Template-level dictionaries: locale → key → text (USP-8). */
+export type Dictionaries = Record<string, Record<string, string>>;
+/**
+ * The `t` helper's lookup, with where the text came from: the exact locale (`de-DE`), its language
+ * (`de`), English, or — `from: null` — nowhere, in which case the key itself is shown. The editor uses
+ * `from` to write an edited translation where the reader will find it (plan 16 §3.1).
+ */
+export declare function resolveTranslation(dictionaries: Dictionaries | undefined, locale: string, key: string): {
+    text: string;
+    from: string | null;
+};
+/**
+ * The dictionary an edit of `key` shown in `locale` belongs in: the one the text came from when that
+ * is the reader's own language, otherwise the reader's locale (when it has a dictionary) or language —
+ * never English on behalf of someone reading German.
+ */
+export declare function translationTarget(dictionaries: Dictionaries | undefined, locale: string, key: string): string;

package/types/lib/translation.d.ts

@@ -0,0 +1,17 @@
+/** Template-level dictionaries: locale → key → text (USP-8). */
+export type Dictionaries = Record<string, Record<string, string>>;
+/**
+ * The `t` helper's lookup, with where the text came from: the exact locale (`de-DE`), its language
+ * (`de`), English, or — `from: null` — nowhere, in which case the key itself is shown. The editor uses
+ * `from` to write an edited translation where the reader will find it (plan 16 §3.1).
+ */
+export declare function resolveTranslation(dictionaries: Dictionaries | undefined, locale: string, key: string): {
+    text: string;
+    from: string | null;
+};
+/**
+ * The dictionary an edit of `key` shown in `locale` belongs in: the one the text came from when that
+ * is the reader's own language, otherwise the reader's locale (when it has a dictionary) or language —
+ * never English on behalf of someone reading German.
+ */
+export declare function translationTarget(dictionaries: Dictionaries | undefined, locale: string, key: string): string;