@lwc-bolts/sf2ts 0.0.5 → 1.0.0

package/dist/lightning-component-bundle/templates/source.js

@@ -0,0 +1,81 @@
+export class TemplateSource {
+    text;
+    #options;
+    /** Text nodes in a run of text share its location, so each is found after the previous, by the run's start. */
+    #cursors = new Map();
+    constructor(text, options) {
+        this.text = text;
+        this.#options = options;
+    }
+    /** The expression in an attribute or directive spanning `location`, if there is one. */
+    attribute(location) {
+        const brace = this.text.indexOf("{", location.start);
+        return brace !== -1 && brace < location.end ? { brace, at: (offset) => brace + offset } : undefined;
+    }
+    /**
+     * The expression of the next text node in a run of text, or undefined for a literal, which only moves
+     * the cursor. The compiler tidies a run's lines before parsing it, so a node's `raw` is in that text, not
+     * the template's.
+     *
+     * Without complex expressions, an expression is on one line, so `raw` is in the template as it is, and
+     * its offsets are relative to `raw`.
+     *
+     * With them, its offsets are relative to the tidied run. Each `{` in the text starts an expression, so
+     * the next one is this node's, and from it `raw` lines up with the template but for whitespace.
+     */
+    textExpression(raw, expression, location) {
+        const cursor = this.#cursors.get(location.start) ?? { source: location.start, tidied: 0 };
+        this.#cursors.set(location.start, cursor);
+        const tidied = cursor.tidied;
+        cursor.tidied += raw.length;
+        if (expression === undefined) {
+            return undefined;
+        }
+        if (!this.#options.complexExpressions) {
+            const position = this.text.indexOf(raw, cursor.source);
+            if (position === -1 || position >= location.end) {
+                return undefined;
+            }
+            cursor.source = position + raw.length;
+            return { brace: position, at: (offset) => position + offset };
+        }
+        const brace = this.text.indexOf("{", cursor.source);
+        if (brace === -1 || brace >= location.end) {
+            return undefined;
+        }
+        const offsets = this.#align(raw, brace);
+        cursor.source = offsets[raw.length];
+        return { brace, at: (offset) => offsets[offset - tidied] };
+    }
+    /** For each offset of `raw`, and its end, the template offset of the same text, starting at `start`. */
+    #align(raw, start) {
+        const offsets = [];
+        let position = start;
+        for (const character of raw) {
+            while (this.text[position] !== character && isSpace(this.text[position])) {
+                position++;
+            }
+            // a space the compiler made of a line break has nothing of its own in the template
+            offsets.push(position);
+            if (this.text[position] === character) {
+                position++;
+            }
+        }
+        offsets.push(position);
+        return offsets;
+    }
+    /** The offset of some literal text in a run of text, if it's there as it is. */
+    literal(text, location) {
+        const position = this.text.indexOf(text, location.start);
+        return position === -1 || position >= location.end ? undefined : position;
+    }
+    /** The offset of a name in an attribute such as `for:item="row"`, after its `=` (or its `:`). */
+    name(name, location, after) {
+        const marker = this.text.indexOf(after, location.start);
+        const position = marker === -1 ? -1 : this.text.indexOf(name, marker);
+        return position !== -1 && position + name.length <= location.end ? position : undefined;
+    }
+}
+function isSpace(character) {
+    return character !== undefined && /\s/.test(character);
+}

package/dist/lightning-component-bundle/templates/tags.d.ts

@@ -0,0 +1,41 @@
+import type { LightningComponent } from "@lwc-bolts/lightning-base-components";
+import type { BaseElement } from "./ast.ts";
+/**
+ * Salesforce's own namespaces of components that templates use, which aren't installed packages':
+ * `lightning`'s are described by LIGHTNING_COMPONENTS, and the others aren't described at all. It isn't
+ * every one there is, so a tag of one that's missing is reported as a component the project doesn't have.
+ */
+export declare const PLATFORM_NAMESPACES: Set<string>;
+/** The DOM type of a plain element, by its namespace, as `<a>` in an `<svg>` isn't an HTML `<a>`. */
+export declare function elementType(node: BaseElement): string;
+/** What a tag is, which decides how its properties, events and refs are checked. */
+export type TagKind = 
+/** A plain HTML, SVG or MathML element. */
+{
+    kind: "element";
+}
+/** One of the project's components: `name` is what the project's lookups know it by. */
+ | {
+    kind: "child";
+    name: string;
+    module: string;
+}
+/** An installed package's component, whose source is hidden. */
+ | {
+    kind: "package";
+    module: string;
+}
+/** A base component with a definition. */
+ | {
+    kind: "base";
+    tag: string;
+}
+/** Anything nothing describes, such as `<slot>`, `<lwc:component>` or another Salesforce namespace's component. */
+ | {
+    kind: "other";
+};
+/**
+ * What a tag is. `tagModule` is the compiler's, as a tag names what the compiled template imports.
+ * Installed packages' components are of any namespace but `c`, the project's own and Salesforce's.
+ */
+export declare function tagKind(node: BaseElement, tagModule: (tag: string) => string, projectNamespace: string | undefined, baseComponents: Readonly<Record<string, LightningComponent>>): TagKind;

package/dist/lightning-component-bundle/templates/tags.js

@@ -0,0 +1,36 @@
+/**
+ * Salesforce's own namespaces of components that templates use, which aren't installed packages':
+ * `lightning`'s are described by LIGHTNING_COMPONENTS, and the others aren't described at all. It isn't
+ * every one there is, so a tag of one that's missing is reported as a component the project doesn't have.
+ */
+export const PLATFORM_NAMESPACES = new Set(["lightning", "lightningsnapin", "force", "ui"]);
+/** Which helper types an element in a namespace other than HTML, whose tags can have the same names. */
+const ELEMENT_HELPERS = {
+    "http://www.w3.org/2000/svg": "__lwcSvgElement",
+    "http://www.w3.org/1998/Math/MathML": "__lwcMathElement",
+};
+/** The DOM type of a plain element, by its namespace, as `<a>` in an `<svg>` isn't an HTML `<a>`. */
+export function elementType(node) {
+    return `${ELEMENT_HELPERS[node.namespace] ?? "__lwcElement"}<${JSON.stringify(node.name)}>`;
+}
+/**
+ * What a tag is. `tagModule` is the compiler's, as a tag names what the compiled template imports.
+ * Installed packages' components are of any namespace but `c`, the project's own and Salesforce's.
+ */
+export function tagKind(node, tagModule, projectNamespace, baseComponents) {
+    if (node.type === "Element") {
+        return { kind: "element" };
+    }
+    if (node.type !== "Component") {
+        return { kind: "other" };
+    }
+    const module = tagModule(node.name);
+    const [namespace, name] = module.split("/");
+    if (namespace === "c") {
+        return { kind: "child", name, module };
+    }
+    if (namespace !== projectNamespace?.toLowerCase() && !PLATFORM_NAMESPACES.has(namespace)) {
+        return { kind: "package", module };
+    }
+    return baseComponents[node.name] === undefined ? { kind: "other" } : { kind: "base", tag: node.name };
+}

package/dist/lightning-component-bundle/templates/template.d.ts

@@ -0,0 +1,53 @@
+import { type LightningComponent } from "@lwc-bolts/lightning-base-components";
+import type { ConversionContext } from "../../context.ts";
+import type { ConversionOutput, LightningComponentBundleComponent, MapPair } from "../../types.ts";
+/** An error the LWC template compiler reports in a template, at a UTF-16 offset and length. */
+export interface TemplateDiagnostic {
+    message: string;
+    start: number;
+    length: number;
+}
+/** A template converted to TypeScript, with where its pieces came from and the compiler's errors. */
+export interface ConvertedTemplate {
+    text: string;
+    mapData: MapPair[];
+    diagnostics: TemplateDiagnostic[];
+}
+/**
+ * Converts one of a bundle's templates (`convert` with a `LightningComponentBundle`'s `.html`). What the
+ * template needs to know about its bundle is on the component: how it imports the bundle's component
+ * (`componentModule`), the bundle's name, its API version, and whether it has other templates. Without
+ * them, the template is taken to be in the bundle's folder, named for it. Other components' slots come
+ * from their own templates' declarations. The compiler's errors are `TemplateError` diagnostics.
+ */
+export declare function convertBundleTemplate(component: LightningComponentBundleComponent, context: ConversionContext): Promise<ConversionOutput>;
+/**
+ * The name of a template's default export, which editors show and offer in auto-imports: `<file>Template`,
+ * so `default.html`'s is `defaultTemplate` rather than a reserved word. A file name can have characters
+ * a name can't.
+ */
+export declare function templateExportName(fileName: string): string;
+/** What a template converter can find out about the rest of the project. */
+export interface TemplateContext {
+    /** The template's file, which names its default export (see templateExportName): `default.html` when not given. */
+    fileName?: string;
+    /**
+     * The module other components import the template's component as, such as `c/orders`, under which it
+     * declares its slots for their templates. Without it, the template declares none.
+     */
+    module?: string;
+    /** Whether the bundle has other templates, any of which may be the one rendered. */
+    alternateTemplates?: boolean;
+    /** The API version of the template's component, which it's parsed at: the compiler's latest when not given. */
+    apiVersion?: number;
+    /** The project's own namespace, whose tags are left unchecked: components in it use `c`. */
+    projectNamespace?: string;
+    /** The `lightning-*` base components, by tag, that templates are checked against: LIGHTNING_COMPONENTS by default. */
+    baseComponents?: Readonly<Record<string, LightningComponent>>;
+}
+/**
+ * Converts a component's template to TypeScript that checks its bindings against the component, imported
+ * as `componentModule` (such as `./orders.js`). `context` tells it about its own bundle, and names
+ * the component's module, for the slots it declares.
+ */
+export declare function convertTemplate(content: string, componentModule: string, context?: TemplateContext): Promise<ConvertedTemplate>;