@matthesketh/utopia-compiler 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,155 @@
+/** A single top-level block extracted from the SFC. */
+interface SFCBlock {
+    /** The raw content between the opening and closing tags. */
+    content: string;
+    /** Attributes on the opening tag.  Boolean attrs have value `true`. */
+    attrs: Record<string, string | true>;
+    /** Byte offset of the opening tag's `<` in the original source. */
+    start: number;
+    /** Byte offset one past the closing tag's `>` in the original source. */
+    end: number;
+}
+/** The result of parsing a `.utopia` single-file component. */
+interface SFCDescriptor {
+    template: SFCBlock | null;
+    script: SFCBlock | null;
+    style: SFCBlock | null;
+    filename: string;
+}
+/**
+ * Parse a `.utopia` SFC source string into its constituent blocks.
+ *
+ * The parser only looks for *top-level* `<template>`, `<script>`, and
+ * `<style>` tags.  Anything else at the top level is silently ignored.
+ */
+declare function parse(source: string, filename?: string): SFCDescriptor;
+interface SourcePosition {
+    line: number;
+    column: number;
+}
+declare class SFCParseError extends Error {
+    filename: string;
+    position: SourcePosition;
+    constructor(message: string, filename: string, position: SourcePosition);
+}
+
+interface TemplateCompileOptions {
+    /** When set, every created element will receive this data attribute. */
+    scopeId?: string;
+}
+interface TemplateCompileResult {
+    /** The full ES-module source for the render function. */
+    code: string;
+    /** The set of @matthesketh/utopia-runtime helpers actually referenced. */
+    helpers: Set<string>;
+}
+/**
+ * Compile a raw HTML template string into a JavaScript render function module.
+ */
+declare function compileTemplate(template: string, options?: TemplateCompileOptions): TemplateCompileResult;
+declare const enum NodeType {
+    Element = 1,
+    Text = 2,
+    Interpolation = 3,
+    Comment = 4
+}
+interface ElementNode {
+    type: NodeType.Element;
+    tag: string;
+    attrs: Attribute[];
+    directives: Directive[];
+    children: TemplateNode[];
+    selfClosing: boolean;
+}
+interface TextNode {
+    type: NodeType.Text;
+    content: string;
+}
+interface InterpolationNode {
+    type: NodeType.Interpolation;
+    expression: string;
+}
+interface CommentNode {
+    type: NodeType.Comment;
+    content: string;
+}
+type TemplateNode = ElementNode | TextNode | InterpolationNode | CommentNode;
+interface Attribute {
+    name: string;
+    value: string | null;
+}
+interface Directive {
+    kind: DirectiveKind;
+    arg: string | null;
+    expression: string;
+    modifiers: string[];
+}
+type DirectiveKind = 'on' | 'bind' | 'if' | 'for' | 'model';
+/** Exported for testing — parse a template string into an AST. */
+declare function parseTemplate(source: string): TemplateNode[];
+
+interface StyleCompileOptions {
+    /** The raw CSS source. */
+    source: string;
+    /** The filename for the component (used to generate a stable hash). */
+    filename: string;
+    /** Whether the `<style>` block had the `scoped` attribute. */
+    scoped: boolean;
+    /** Override the scope ID (useful for testing). */
+    scopeId?: string;
+}
+interface StyleCompileResult {
+    /** The (possibly transformed) CSS. */
+    css: string;
+    /**
+     * The data attribute that must be added to every element in the component
+     * template so the scoped selectors match.  `null` when not scoped.
+     */
+    scopeId: string | null;
+}
+/**
+ * Compile a `<style>` block, applying scoped transformations when required.
+ */
+declare function compileStyle(options: StyleCompileOptions): StyleCompileResult;
+/**
+ * Generate a deterministic scope ID from a filename.
+ *
+ * We use a simple DJB2-style hash (fast, no crypto dependency) and format it
+ * as `data-u-XXXXXXXX`.
+ */
+declare function generateScopeId(filename: string): string;
+
+interface CompileOptions {
+    /** Filename for error messages and scope-id generation. */
+    filename?: string;
+    /** Override the scope ID for testing. */
+    scopeId?: string;
+}
+interface CompileResult {
+    /** The compiled JavaScript module source. */
+    code: string;
+    /** Extracted CSS (with scoping applied if the style block is `scoped`). */
+    css: string;
+    /** Source map (reserved for future use). */
+    map?: unknown;
+}
+/**
+ * Compile a `.utopia` single-file component source string.
+ *
+ * Returns the generated JavaScript module code and CSS string.
+ *
+ * The generated JS module has the shape:
+ * ```js
+ * import { ... } from '@matthesketh/utopia-runtime'
+ *
+ * // <script> block contents (user code) inlined here
+ *
+ * export default function render(_ctx) { ... }
+ * ```
+ *
+ * The caller (e.g. the Vite plugin) is responsible for injecting the CSS
+ * into the page (via a `<style>` tag, or a CSS module import, etc.).
+ */
+declare function compile(source: string, options?: CompileOptions): CompileResult;
+
+export { type CompileOptions, type CompileResult, type SFCBlock, type SFCDescriptor, SFCParseError, type StyleCompileOptions, type StyleCompileResult, type TemplateCompileOptions, type TemplateCompileResult, compile, compileStyle, compileTemplate, generateScopeId, parse, parseTemplate };

package/dist/index.d.ts

@@ -0,0 +1,155 @@
+/** A single top-level block extracted from the SFC. */
+interface SFCBlock {
+    /** The raw content between the opening and closing tags. */
+    content: string;
+    /** Attributes on the opening tag.  Boolean attrs have value `true`. */
+    attrs: Record<string, string | true>;
+    /** Byte offset of the opening tag's `<` in the original source. */
+    start: number;
+    /** Byte offset one past the closing tag's `>` in the original source. */
+    end: number;
+}
+/** The result of parsing a `.utopia` single-file component. */
+interface SFCDescriptor {
+    template: SFCBlock | null;
+    script: SFCBlock | null;
+    style: SFCBlock | null;
+    filename: string;
+}
+/**
+ * Parse a `.utopia` SFC source string into its constituent blocks.
+ *
+ * The parser only looks for *top-level* `<template>`, `<script>`, and
+ * `<style>` tags.  Anything else at the top level is silently ignored.
+ */
+declare function parse(source: string, filename?: string): SFCDescriptor;
+interface SourcePosition {
+    line: number;
+    column: number;
+}
+declare class SFCParseError extends Error {
+    filename: string;
+    position: SourcePosition;
+    constructor(message: string, filename: string, position: SourcePosition);
+}
+
+interface TemplateCompileOptions {
+    /** When set, every created element will receive this data attribute. */
+    scopeId?: string;
+}
+interface TemplateCompileResult {
+    /** The full ES-module source for the render function. */
+    code: string;
+    /** The set of @matthesketh/utopia-runtime helpers actually referenced. */
+    helpers: Set<string>;
+}
+/**
+ * Compile a raw HTML template string into a JavaScript render function module.
+ */
+declare function compileTemplate(template: string, options?: TemplateCompileOptions): TemplateCompileResult;
+declare const enum NodeType {
+    Element = 1,
+    Text = 2,
+    Interpolation = 3,
+    Comment = 4
+}
+interface ElementNode {
+    type: NodeType.Element;
+    tag: string;
+    attrs: Attribute[];
+    directives: Directive[];
+    children: TemplateNode[];
+    selfClosing: boolean;
+}
+interface TextNode {
+    type: NodeType.Text;
+    content: string;
+}
+interface InterpolationNode {
+    type: NodeType.Interpolation;
+    expression: string;
+}
+interface CommentNode {
+    type: NodeType.Comment;
+    content: string;
+}
+type TemplateNode = ElementNode | TextNode | InterpolationNode | CommentNode;
+interface Attribute {
+    name: string;
+    value: string | null;
+}
+interface Directive {
+    kind: DirectiveKind;
+    arg: string | null;
+    expression: string;
+    modifiers: string[];
+}
+type DirectiveKind = 'on' | 'bind' | 'if' | 'for' | 'model';
+/** Exported for testing — parse a template string into an AST. */
+declare function parseTemplate(source: string): TemplateNode[];
+
+interface StyleCompileOptions {
+    /** The raw CSS source. */
+    source: string;
+    /** The filename for the component (used to generate a stable hash). */
+    filename: string;
+    /** Whether the `<style>` block had the `scoped` attribute. */
+    scoped: boolean;
+    /** Override the scope ID (useful for testing). */
+    scopeId?: string;
+}
+interface StyleCompileResult {
+    /** The (possibly transformed) CSS. */
+    css: string;
+    /**
+     * The data attribute that must be added to every element in the component
+     * template so the scoped selectors match.  `null` when not scoped.
+     */
+    scopeId: string | null;
+}
+/**
+ * Compile a `<style>` block, applying scoped transformations when required.
+ */
+declare function compileStyle(options: StyleCompileOptions): StyleCompileResult;
+/**
+ * Generate a deterministic scope ID from a filename.
+ *
+ * We use a simple DJB2-style hash (fast, no crypto dependency) and format it
+ * as `data-u-XXXXXXXX`.
+ */
+declare function generateScopeId(filename: string): string;
+
+interface CompileOptions {
+    /** Filename for error messages and scope-id generation. */
+    filename?: string;
+    /** Override the scope ID for testing. */
+    scopeId?: string;
+}
+interface CompileResult {
+    /** The compiled JavaScript module source. */
+    code: string;
+    /** Extracted CSS (with scoping applied if the style block is `scoped`). */
+    css: string;
+    /** Source map (reserved for future use). */
+    map?: unknown;
+}
+/**
+ * Compile a `.utopia` single-file component source string.
+ *
+ * Returns the generated JavaScript module code and CSS string.
+ *
+ * The generated JS module has the shape:
+ * ```js
+ * import { ... } from '@matthesketh/utopia-runtime'
+ *
+ * // <script> block contents (user code) inlined here
+ *
+ * export default function render(_ctx) { ... }
+ * ```
+ *
+ * The caller (e.g. the Vite plugin) is responsible for injecting the CSS
+ * into the page (via a `<style>` tag, or a CSS module import, etc.).
+ */
+declare function compile(source: string, options?: CompileOptions): CompileResult;
+
+export { type CompileOptions, type CompileResult, type SFCBlock, type SFCDescriptor, SFCParseError, type StyleCompileOptions, type StyleCompileResult, type TemplateCompileOptions, type TemplateCompileResult, compile, compileStyle, compileTemplate, generateScopeId, parse, parseTemplate };