@lightspeed-js/core 0.2.0 → 0.3.0

package/dist/types/src/project/component-ids.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Which file answers to each component name (ADR-058).
+ *
+ * Names are a flat namespace: a component is its filename, lowercased, from
+ * whichever root it was found in. The first root to claim a name keeps it, and
+ * `src` comes first, so an app can replace a package's component.
+ *
+ * Two files answering to one name is either that deliberate override or a
+ * collision nobody meant, and the two look identical from the files alone. So
+ * the app says which it means: an override across roots has to be declared,
+ * and two files under the same root are always a mistake.
+ */
+export interface FoundComponent {
+    /** Absolute path to the `.lsp` file. */
+    file: string;
+    /** The component root it was found under. */
+    root: string;
+}
+export type Conflict = {
+    kind: "same-root";
+    id: string;
+    kept: string;
+    other: string;
+} | {
+    kind: "undeclared-override";
+    id: string;
+    kept: string;
+    other: string;
+};
+export interface ComponentIds {
+    /** Component id to the file that answers to it. */
+    files: Map<string, string>;
+    /** Declared overrides that replaced something. */
+    overrides: Array<{
+        id: string;
+        kept: string;
+        replaced: string;
+    }>;
+    conflicts: Conflict[];
+    /** Names in `overrides` that replace nothing - left over after a rename or removal. */
+    unusedOverrides: string[];
+}
+export declare function componentIdOf(file: string): string;
+/** `found` must be in precedence order: every file of the first root, then the next. */
+export declare function resolveComponentIds(found: FoundComponent[], declaredOverrides?: readonly string[]): ComponentIds;
+/** One message per conflict, each ending in the change that fixes it (ADR-055). */
+export declare function describeConflict(conflict: Conflict, rel: (file: string) => string): string;

package/dist/types/src/project/components.d.ts

@@ -0,0 +1,61 @@
+/**
+ * A project's components: where they are found, which file answers to each
+ * name, and their compiled definitions for build-time rendering.
+ *
+ * Shared by the Vite plugin and by `renderFragment` (ADR-059), so a component
+ * rendered into someone else's page goes through exactly the pipeline a
+ * Lightspeed page does. Moved out of the plugin unchanged; a second pipeline
+ * would be a second renderer to drift.
+ */
+import { parseLSP } from "../parser/index.js";
+import type { ComponentDefinition } from "../runtime/components/index.js";
+import { type Conflict } from "./component-ids.js";
+export type Compiler = "esbuild" | "tsc" | "swc";
+export interface ComponentProjectOptions {
+    /** The project root. A function when it is only known later (Vite's configResolved). */
+    root: string | (() => string);
+    /** Roots beyond the project's own `src`, relative to the root. */
+    componentDirs?: string[];
+    /** Names the app replaces on purpose (ADR-058). */
+    overrides?: string[];
+    /** For component logic at build time. */
+    compiler?: Compiler;
+}
+/** A parsed `.lsp` file, as the registry holds it. */
+export interface RegistryEntry {
+    template: string;
+    skeleton: string;
+    style: string;
+    styleDeferred: string;
+    logic: string;
+    needs?: string[];
+}
+export interface ComponentProject {
+    /** Component id to its parsed source. Swapped in whole on each rebuild. */
+    readonly registry: Map<string, RegistryEntry>;
+    /** Component id to the file that answers to it. */
+    readonly files: Map<string, string>;
+    /** Clashes from the latest rebuild (ADR-058). */
+    readonly conflicts: Conflict[];
+    /** Every root components come from, in precedence order: `src` first. */
+    roots(): string[];
+    /** Rescan the roots. Concurrent callers share one rescan. */
+    rebuild(): Promise<void>;
+    /** Compile every component, as the client's modules do, for build-time rendering. */
+    definitions(): Promise<ComponentDefinition[]>;
+    /** Compile markup that uses components (a page, or a fragment of one) into island markers. */
+    compileMarkup(html: string, id?: string): string;
+    /** Compile component logic (TypeScript) to JavaScript. */
+    compileLogic(code: string): Promise<string>;
+}
+export declare function createComponentProject(options: ComponentProjectOptions): ComponentProject;
+/**
+ * Fold in any `<style src="…">` the component asked for.
+ *
+ * A shared block is referenced the way an import is - relative to the `.lsp`
+ * file - and each component that asks for it gets its own scoped copy, so
+ * sharing a file never means sharing a selector.
+ */
+export declare function withSharedStyles(parsed: ReturnType<typeof parseLSP>, watch?: (file: string) => void): import("../parser/lsp.ts").LSPComponent;
+/** Compile TypeScript at build time using Node.js APIs. */
+export declare function compileTypeScriptAtBuildTime(code: string, compiler: string): Promise<string>;

package/dist/types/src/ssg/fragment.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Render Lightspeed components into a page Lightspeed doesn't own (ADR-059).
+ *
+ * A host - a docs site, a CMS preview, another framework's page - hands over
+ * markup that uses components (`<Button variant="secondary">Save</Button>`)
+ * and gets back what a Lightspeed page build would have produced for it: the
+ * rendered islands, the CSS, and the `<head>` payload hydration reads. The
+ * same component project, compiler and renderer as a page, so a fragment
+ * cannot render differently from the page it stands in for.
+ *
+ * In the browser the host imports `virtual:lightspeed/components` from
+ * `lightspeedPlugin({ host: true, fragments })` and calls
+ * `app.hydrate(container)` on the element it put the fragment in.
+ */
+import type { TemplateExpression } from "../compile/expressions.js";
+import type { ComponentProject, Compiler } from "../project/components.js";
+export interface FragmentRendererOptions {
+    /** The project root: components are found in its `src`, then `componentDirs`. */
+    root: string;
+    /** Further component roots, relative to the root - as `lightspeedPlugin`'s. */
+    componentDirs?: string[];
+    /** Names the app replaces on purpose (ADR-058). */
+    overrides?: string[];
+    compiler?: Compiler;
+}
+export interface RenderFragmentsOptions {
+    /** Ship islands that need nothing from the browser as plain HTML. On by default, as for pages. */
+    flattenStatic?: boolean;
+}
+export interface RenderedFragments {
+    /** Each fragment's markup, rendered, in the order given. */
+    html: string[];
+    /**
+     * Tags for the host page's `<head>`: the manifest hydration reads, and any
+     * build-time state. One payload for all the fragments, because the runtime
+     * reads them by id, once per page.
+     */
+    head: string;
+    /** Scoped CSS for the components the fragments use. */
+    css: string;
+    /** Their deferred CSS (`<style deferred>`). */
+    cssDeferred: string;
+    /** Component ids the fragments reach. */
+    used: string[];
+    /** Islands rendered, and shipped as plain HTML. */
+    rendered: number;
+    flattened: number;
+    /**
+     * The fragments' own expressions (`$disabled="true"` on a component tag).
+     * The browser needs the same table: pass the fragments to
+     * `lightspeedPlugin({ host: true, fragments })`, which compiles it into
+     * `virtual:lightspeed/components`.
+     */
+    expressions: TemplateExpression[];
+}
+export interface FragmentRenderer {
+    render(fragments: string[], options?: RenderFragmentsOptions): Promise<RenderedFragments>;
+    /** The component project it renders with. */
+    readonly project: ComponentProject;
+}
+export declare function createFragmentRenderer(options: FragmentRendererOptions): FragmentRenderer;

package/dist/types/src/ssg/index.d.ts

@@ -7,6 +7,8 @@
  */
 export { renderPage } from "./render.js";
 export type { RenderPageOptions, RenderPageResult } from "./render.js";
+export { createFragmentRenderer } from "./fragment.js";
+export type { FragmentRenderer, FragmentRendererOptions, RenderFragmentsOptions, RenderedFragments, } from "./fragment.js";
 export { rebuildPages } from "./rebuild.js";
 export type { RebuildOptions, RebuildResult } from "./rebuild.js";
 /**

package/dist/types/src/vite/plugin.d.ts

@@ -73,6 +73,22 @@ interface LightspeedPluginOptions {
      * Two files under the same root are never an override.
      */
     overrides?: string[];
+    /**
+     * Run inside a site Lightspeed doesn't own (ADR-059): an Astro site, a
+     * Vite app, a docs site. The plugin compiles `.lsp` files and provides
+     * `virtual:lightspeed/components`, and leaves the host's HTML alone: no
+     * page discovery, no page compiling or rendering, no route or manifest
+     * files. The host renders islands at build with `createFragmentRenderer`
+     * from `@lightspeed-js/core/ssg` and calls `app.hydrate(container)`.
+     */
+    host?: boolean;
+    /**
+     * Files of markup the host renders with `createFragmentRenderer`, relative
+     * to the root (globs allowed). Their own expressions - `$disabled="true"` on
+     * a component tag - are compiled into `virtual:lightspeed/components`, as a
+     * page's are, so hydration finds them.
+     */
+    fragments?: string[];
 }
 export declare function lightspeedPlugin(options?: LightspeedPluginOptions): Plugin[];
 export {};

package/dist/types/test/fragment.test.d.ts

@@ -0,0 +1 @@
+export {};