mountly-vite-plugin 1.3.0 → 1.6.0

package/README.md

@@ -78,6 +78,34 @@ to compose them into a config you already own:
 | `mountlyCssAsText`              | import CSS as a string, for adopting into a shadow root  |
 | `getFrameworkPeerExternals`     | the externals list for a peer build                      |
 
+## Script-tag component libraries
+
+`defineElementsConfig({ prefix, elements })` turns typed React/Vue/Svelte
+components into lazily-loaded custom elements, and emits `embed.d.ts` and
+`custom-elements.json` alongside `embed.js`.
+
+Elements render in light DOM, so the consuming page's design system reaches in.
+Pass `shadow: true` when the host is not one you trust: every element in the
+distribution then renders into its own shadow root, and the build emits one
+stylesheet that it injects into no document.
+
+Pass `peer: true` when one page loads several distributions, such as widgets
+from several teams. The build leaves the framework, its mountly adapter and
+mountly's runtime as bare imports (`react`, `mountly-react`, `mountly/embed`),
+and the page maps them once in an import map, so every distribution shares one
+React. Without it, each `embed.js` works alone on any page.
+
+`custom-elements.json` carries each component's JSDoc as its description, and
+each prop's JSDoc, its type as written (`"paid" | "overdue"`) and a JSON Schema
+derived from that type. JSDoc tags add constraints: `@minimum`, `@maximum`,
+`@minLength`, `@maxLength`, `@pattern` and `@format`. `@slot` tags declare the
+slots a component renders, and the element fills them from the page's children.
+Slots need a `shadow: true` distribution, and the build warns without one.
+
+See the [complete guide](https://mountly.dev/concepts/script-embeds/) and the
+[React](../../docs/examples/react-embed) and
+[mixed-framework](../../docs/examples/mixed-embed) examples.
+
 ## TypeScript
 
 `mountlyManifestFragmentPlugin` reads exports from the TypeScript checker and

package/dist/docs.d.ts

@@ -0,0 +1,31 @@
+import { type ExtractOptions } from "./props.js";
+/** A JSON Schema, as far as the build can derive one from a TypeScript type. */
+export type PropSchema = Record<string, unknown>;
+export interface ComponentDocs {
+    /** The component's JSDoc summary. */
+    description?: string;
+    /**
+     * Per prop: its JSDoc summary, its type as written (`"paid" | "overdue"`), and
+     * a JSON Schema derived from that type plus any `@minimum`, `@maximum`,
+     * `@minLength`, `@maxLength`, `@pattern` or `@format` tags.
+     */
+    props: Record<string, {
+        description?: string;
+        type?: string;
+        schema?: PropSchema;
+    }>;
+    /** `@slot` tags on the component: `@slot - body` or `@slot actions - the buttons`. */
+    slots?: Array<{
+        name: string;
+        description: string;
+    }>;
+}
+/**
+ * The prose a reader of the component's source would see: the JSDoc on the
+ * component and on each prop, and each prop's type as the author wrote it.
+ * The prop table says how to wire a prop; this says what it is for, which is
+ * what a person browsing a catalog — or a model composing from one — needs.
+ *
+ * Best effort: anything unreadable is simply absent, never an error.
+ */
+export declare function extractDocs(code: string, options?: ExtractOptions): ComponentDocs;

package/dist/embed.d.ts

@@ -0,0 +1,74 @@
+import { type UserConfig } from "vite";
+import { type MountlyWidgetFramework } from "./externals.js";
+import { type PropSpec } from "./props.js";
+export interface MountlyElementEntry {
+    /** Browser-compatible component source, also importable directly by your app. */
+    component: string;
+    exportName?: string;
+    /**
+     * Override the adapter for this element. Inferred from the file extension, so
+     * this is only for a component whose extension does not say what it is — a
+     * Vue `defineComponent` written in a `.ts` file, say.
+     */
+    framework?: MountlyWidgetFramework;
+    /** Override the prop table when the component's props type lives elsewhere. */
+    props?: PropSpec[];
+    /** Core trigger syntax. Defaults to mounting when connected. */
+    trigger?: string;
+}
+export interface MountlyElementsConfigOptions {
+    /**
+     * Namespace for the generated tags. Custom element names need a dash, and
+     * the consumer's page is not yours — `acme` gives `<acme-payments-summary>`.
+     */
+    prefix: string;
+    /** A glob of component files, or an explicit tag → component map. */
+    elements: string | string[] | Record<string, string | MountlyElementEntry>;
+    /**
+     * Project root. Only needed when the config is not loaded from it — a
+     * monorepo running the build from elsewhere, say. Defaults to `process.cwd()`.
+     */
+    root?: string;
+    /**
+     * Render every element into a shadow root instead of the host's light DOM.
+     *
+     * Light DOM is the default because the usual consumer is a page that wants
+     * its own design system to reach in — a CMS template, a partner site running
+     * your tokens. Turn this on when the host is one you do not trust to leave
+     * your component alone, or that you must not affect: the host's CSS cannot
+     * reach in, and your CSS stops being emitted into its document.
+     *
+     * The whole distribution shares the setting, because it describes the kind
+     * of host you ship to, not the component.
+     */
+    shadow?: boolean;
+    /**
+     * Leave the framework (React, Vue or Svelte), its mountly adapter and
+     * mountly's runtime as bare imports, for the page's import map to resolve.
+     *
+     * Off by default, because then one script tag works on any page. Turn it on
+     * when one page loads several distributions — widgets from several teams,
+     * say — so they share one copy of React instead of each bringing its own.
+     * The page must map every bare specifier the build leaves behind (`react`,
+     * `react-dom/client`, `mountly-react`, `mountly/embed`, …).
+     */
+    peer?: boolean;
+}
+/**
+ * Route each `new Worker(…)` that means the platform's Worker through the
+ * cross-origin shim. Parsed, not pattern-matched: the same characters in a
+ * string, template or comment are content, and an inline worker's source is one
+ * of those strings. A call is left alone when any enclosing scope binds
+ * `Worker` (a parameter, a catch, a var, a let, a class, an import), since that
+ * call constructs the author's Worker.
+ */
+export declare function shimWorkers(code: string): string | null;
+/**
+ * Build a script-tag distribution: one file registers every tag, and each
+ * component, its framework and its CSS arrive only when an element connects.
+ *
+ * The author writes an ordinary React/Vue/Svelte component. Its props type is
+ * read at build time, so the consumer gets real attributes, real properties and
+ * real DOM events with nothing to configure on either side.
+ */
+export declare function defineElementsConfig(options: MountlyElementsConfigOptions): UserConfig;

package/dist/externals.d.ts

@@ -0,0 +1,11 @@
+/** Which imports a build leaves for the page to provide, per framework. */
+export type MountlyWidgetFramework = "react" | "vue" | "svelte";
+export declare function getFrameworkPeerExternals(framework: MountlyWidgetFramework): Array<string | RegExp>;
+/**
+ * The self-contained build's whole promise is "drop this file in a page and it
+ * works", so mountly's own runtime helpers are bundled in rather than
+ * externalised: the host then needs no import map at all. The peer build still
+ * externalises them, because sharing through the host's import map is the point
+ * of that build.
+ */
+export declare function getSelfContainedExternals(framework: MountlyWidgetFramework): Array<string | RegExp>;

package/dist/index.d.ts

@@ -1,16 +1,8 @@
 import type { Plugin, UserConfig } from "vite";
 export { mountlyHostPlugin, type MountlyHostPluginOptions } from "./host.js";
 export { mountlyManifestFragmentPlugin, type ManifestFragmentPluginOptions } from "./fragment.js";
-export type MountlyWidgetFramework = "react" | "vue" | "svelte";
-export declare function getFrameworkPeerExternals(framework: MountlyWidgetFramework): Array<string | RegExp>;
-/**
- * The self-contained build's whole promise is "drop this file in a page and it
- * works", so mountly's own runtime helpers are bundled in rather than
- * externalised: the host then needs no import map at all. The peer build still
- * externalises them, because sharing through the host's import map is the point
- * of that build.
- */
-export declare function getSelfContainedExternals(framework: MountlyWidgetFramework): Array<string | RegExp>;
+import { getFrameworkPeerExternals, getSelfContainedExternals, type MountlyWidgetFramework } from "./externals.js";
+export { getFrameworkPeerExternals, getSelfContainedExternals, type MountlyWidgetFramework };
 export interface MountlyCssAsTextOptions {
     include?: string | RegExp | (string | RegExp)[];
 }
@@ -70,3 +62,6 @@ export interface DefineMountlyWidgetConfigOptions {
     featureExport?: string;
 }
 export declare function defineMountlyWidgetConfig(options?: DefineMountlyWidgetConfigOptions): UserConfig[];
+export { defineElementsConfig, type MountlyElementsConfigOptions, type MountlyElementEntry, } from "./embed.js";
+export { extractDocs, type ComponentDocs, type PropSchema } from "./docs.js";
+export { extractProps, type PropSpec, type PropKind } from "./props.js";