@nysds/codegen 0.0.0-stage → 1.20.1

package/cem-plugins/react.mjs

@@ -0,0 +1,143 @@
+/**
+ * CEM plugin: generates the `@lit/react` wrapper for every NYSDS component
+ * into `packages/react/src/generated/` (decision R1).
+ *
+ * The output directory is cleared and recreated on every run, so removed
+ * components leave no orphans. A hand-written file at
+ * `src/overrides/<ClassName>.ts` replaces the generated one: the component
+ * is skipped and the barrel re-exports the override.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { listComponents } from "./lib/core.mjs";
+
+/** Event interface names the platform provides; never imported. */
+const GLOBAL_EVENT_TYPES = new Set([
+  "Event",
+  "CustomEvent",
+  "UIEvent",
+  "FocusEvent",
+  "InputEvent",
+  "KeyboardEvent",
+  "MouseEvent",
+  "PointerEvent",
+  "TouchEvent",
+  "WheelEvent",
+  "AnimationEvent",
+  "TransitionEvent",
+  "ClipboardEvent",
+  "DragEvent",
+  "SubmitEvent",
+]);
+
+const IDENTIFIER_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+/**
+ * Splits event types into locally usable text and package type imports.
+ * Bare identifiers that are not platform globals are assumed to be typed
+ * aliases exported by the component package (section 4.3 of the plan).
+ * Anything else — including today's bare `CustomEvent` — is used verbatim.
+ */
+export function resolveEventType(typeText) {
+  if (IDENTIFIER_RE.test(typeText) && !GLOBAL_EVENT_TYPES.has(typeText)) {
+    return { text: typeText, importName: typeText };
+  }
+  return { text: typeText, importName: undefined };
+}
+
+function renderReactWrapper(component) {
+  const { tag, className, packageName, events } = component;
+  const elementAlias = `${className}Element`;
+
+  const typeImports = new Set();
+  const eventLines = [];
+  const seenProps = new Set();
+  for (const event of events) {
+    // Two event names can map to one React prop (a deprecated camelCase
+    // alias like `nys-fileRemove` next to `nys-file-remove`). Keep the
+    // first, which is the canonical name in manifest order.
+    if (seenProps.has(event.reactProp)) continue;
+    seenProps.add(event.reactProp);
+    const { text, importName } = resolveEventType(event.typeText);
+    if (importName) typeImports.add(importName);
+    eventLines.push(`    ${event.reactProp}: "${event.name}" as EventName<${text}>,`);
+  }
+
+  const lines = [];
+  lines.push(`"use client";`);
+  lines.push(
+    `// GENERATED by @nysds/codegen — do not edit. Override: src/overrides/${className}.ts`
+  );
+  lines.push(`import * as React from "react";`);
+  lines.push(
+    events.length > 0
+      ? `import { createComponent, type EventName } from "@lit/react";`
+      : `import { createComponent } from "@lit/react";`
+  );
+  lines.push(
+    `import { ${className} as ${elementAlias} } from "${packageName}";`
+  );
+  if (typeImports.size > 0) {
+    lines.push(
+      `import type { ${[...typeImports].sort().join(", ")} } from "${packageName}";`
+    );
+  }
+  lines.push(``);
+  lines.push(`export const ${className} = createComponent({`);
+  lines.push(`  react: React,`);
+  lines.push(`  tagName: "${tag}",`);
+  lines.push(`  elementClass: ${elementAlias},`);
+  lines.push(`  displayName: "${className}",`);
+  if (eventLines.length > 0) {
+    lines.push(`  events: {`);
+    lines.push(...eventLines);
+    lines.push(`  },`);
+  }
+  lines.push(`});`);
+  lines.push(``);
+  lines.push(
+    `export type ${className}Props = React.ComponentProps<typeof ${className}>;`
+  );
+  lines.push(`export type { ${elementAlias} };`);
+  lines.push(``);
+  return lines.join("\n");
+}
+
+export function reactPlugin(options = {}) {
+  const {
+    outDir = "packages/react/src/generated",
+    overridesDir = "packages/react/src/overrides",
+  } = options;
+
+  return {
+    name: "nysds-react-wrappers",
+
+    packageLinkPhase({ customElementsManifest }) {
+      const components = listComponents(customElementsManifest);
+      if (components.length === 0) return;
+
+      fs.rmSync(outDir, { recursive: true, force: true });
+      fs.mkdirSync(outDir, { recursive: true });
+
+      const barrel = [
+        `// GENERATED by @nysds/codegen — do not edit.`,
+      ];
+      for (const component of components) {
+        const overridePath = path.join(
+          overridesDir,
+          `${component.className}.ts`
+        );
+        if (fs.existsSync(overridePath)) {
+          barrel.push(`export * from "../overrides/${component.className}.js";`);
+          continue;
+        }
+        fs.writeFileSync(
+          path.join(outDir, `${component.className}.ts`),
+          renderReactWrapper(component)
+        );
+        barrel.push(`export * from "./${component.className}.js";`);
+      }
+      fs.writeFileSync(path.join(outDir, "index.ts"), barrel.join("\n") + "\n");
+    },
+  };
+}

package/cem-plugins/vue.mjs

@@ -0,0 +1,228 @@
+/**
+ * CEM plugin: generates the Vue typings for every NYSDS component into
+ * `packages/vue/src/generated/`.
+ *
+ * Per component, `<ClassName>.ts` exports:
+ * - `<ClassName>Props`, `<ClassName>Events`: the attributes, properties and
+ *   `on<Event>` handlers a raw `<nys-*>` tag accepts.
+ * - `<ClassName>Slots`: the slot names from the manifest, typed for
+ *   `<template #name>` on the wrapper.
+ * - `<ClassName>Model` (form controls only): `modelValue` and
+ *   `onUpdate:modelValue`, derived from the `@formControl` tag.
+ * - `<ClassName>`: a Vue component (built by `createNysComponent` in
+ *   `src/runtime.ts`) that renders the element, maps slots to light-DOM
+ *   children, and supports `v-model` on form controls.
+ *
+ * Plus:
+ * - `index.ts` is the barrel.
+ * - `global.ts` augments `vue`'s `GlobalComponents` (typed `<nys-*>` in
+ *   templates via Volar / vue-tsc) and the global `JSX.IntrinsicElements`
+ *   (typed `<nys-*>` in TSX/JSX).
+ *
+ * Prop types are picked from the element class, so they stay exact even where
+ * the manifest carries only a loose type string. The output directory is
+ * cleared on every run, so removed components leave no orphans.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { listComponents } from "./lib/core.mjs";
+import { resolveEventType } from "./react.mjs";
+
+function renderVueProps(component) {
+  const { className, packageName, props, events, slots, formControl } =
+    component;
+  const elementAlias = `${className}Element`;
+  const propsName = `${className}Props`;
+
+  const typeImports = new Set();
+  const eventLines = [];
+  const seenProps = new Set();
+  for (const event of events) {
+    // Vue camelizes `@nys-change` to `onNysChange`, the same shape React
+    // uses, so two event names can collide here too. Keep the first.
+    if (seenProps.has(event.reactProp)) continue;
+    seenProps.add(event.reactProp);
+    const { text, importName } = resolveEventType(event.typeText);
+    if (importName) typeImports.add(importName);
+    if (event.description) {
+      eventLines.push(
+        `  /** ${event.description.replace(/\s*\n\s*/g, " ").replace(/\*\//g, "*\\/")} */`
+      );
+    }
+    eventLines.push(`  ${event.reactProp}?: (event: ${text}) => void;`);
+  }
+
+  const propNames = [...new Set(props.map((prop) => prop.name))].sort();
+  const propsType =
+    propNames.length > 0
+      ? `Partial<Pick<${elementAlias}, ${propNames.map((n) => JSON.stringify(n)).join(" | ")}>>`
+      : `{}`;
+
+  const lines = [];
+  lines.push(
+    `// GENERATED by @nysds/codegen — do not edit. Regenerate with \`npm run cem\`.`
+  );
+  lines.push(
+    `import type { ${className} as ${elementAlias}${[...typeImports].sort().map((n) => `, ${n}`).join("")} } from "${packageName}";`
+  );
+  lines.push(`import "${packageName}";`);
+  lines.push(`import type { HTMLAttributes, ReservedProps } from "vue";`);
+  lines.push(
+    `import { createNysComponent, type NysComponent, type NysSlots } from "../runtime.js";`
+  );
+  lines.push(``);
+  lines.push(`/** Handlers for the events \`<${component.tag}>\` dispatches. */`);
+  lines.push(`export interface ${className}Events {`);
+  lines.push(...eventLines);
+  lines.push(`}`);
+  lines.push(``);
+  lines.push(`type ${className}Members = ${propsType};`);
+  lines.push(``);
+  lines.push(
+    `/** Everything \`<${component.tag}>\` accepts in a Vue template or TSX file. */`
+  );
+  lines.push(`export type ${propsName} = Omit<`);
+  lines.push(`  HTMLAttributes,`);
+  lines.push(`  keyof ${className}Members | keyof ${className}Events`);
+  lines.push(`> &`);
+  lines.push(`  ReservedProps &`);
+  lines.push(`  ${className}Members &`);
+  lines.push(`  ${className}Events;`);
+  lines.push(``);
+  lines.push(`export type { ${elementAlias} };`);
+  lines.push(``);
+
+  // Slots: "" is the default slot. The default slot is always allowed: some
+  // elements take children without documenting one in the manifest.
+  const slotKeys = [
+    ...new Set(["default", ...slots.map((slot) => slot.name || "default")]),
+  ].sort();
+  lines.push(
+    `/** Slots of \`<${component.tag}>\`, fillable with \`<template #name>\` on the wrapper. */`
+  );
+  lines.push(
+    `export type ${className}SlotName = ${slotKeys.map((n) => JSON.stringify(n)).join(" | ")};`
+  );
+  lines.push(
+    `export type ${className}Slots = NysSlots<${className}SlotName>;`
+  );
+  lines.push(``);
+
+  // v-model: only where the manifest declares a form contract.
+  let modelType = "";
+  if (formControl) {
+    const modelValueType = `${elementAlias}[${JSON.stringify(formControl.kind)}]`;
+    lines.push(
+      `/** \`v-model\` binds \`${formControl.kind}\`; add \`.lazy\` to update on \`${formControl.changeEvent}\`. */`
+    );
+    lines.push(`export interface ${className}Model {`);
+    lines.push(`  modelValue?: ${modelValueType};`);
+    lines.push(
+      `  "onUpdate:modelValue"?: (value: ${modelValueType}) => void;`
+    );
+    lines.push(`}`);
+    lines.push(``);
+    modelType = ` & ${className}Model`;
+  }
+
+  // Runtime wrapper.
+  const booleanProps = [
+    ...new Set(props.filter((prop) => prop.isBoolean).map((prop) => prop.name)),
+  ].sort();
+  lines.push(`export const ${className} = createNysComponent<`);
+  lines.push(
+    `  NysComponent<${propsName}${modelType}, ${className}Slots, ${elementAlias}>`
+  );
+  lines.push(`>({`);
+  lines.push(`  tag: "${component.tag}",`);
+  lines.push(`  name: "${className}",`);
+  lines.push(`  props: ${JSON.stringify(propNames)},`);
+  lines.push(`  booleanProps: ${JSON.stringify(booleanProps)},`);
+  if (formControl) {
+    const listener = (name) =>
+      events.find((event) => event.name === name)?.reactProp;
+    const changeListener = listener(formControl.changeEvent);
+    const inputListener = formControl.inputEvent
+      ? listener(formControl.inputEvent)
+      : undefined;
+    lines.push(`  model: {`);
+    lines.push(`    kind: "${formControl.kind}",`);
+    lines.push(`    changeListener: "${changeListener}",`);
+    if (inputListener) lines.push(`    inputListener: "${inputListener}",`);
+    lines.push(`  },`);
+  }
+  lines.push(`});`);
+  lines.push(``);
+  return lines.join("\n");
+}
+
+function renderGlobal(components) {
+  const lines = [];
+  lines.push(`// GENERATED by @nysds/codegen — do not edit.`);
+  lines.push(`import type { DefineComponent } from "vue";`);
+  // A module augmentation only resolves if the program already loads the
+  // module; this import guarantees it does.
+  lines.push(`import type {} from "vue/jsx-runtime";`);
+  for (const c of components) {
+    lines.push(`import type { ${c.className}Props } from "./${c.className}.js";`);
+  }
+  lines.push(``);
+  lines.push(`declare module "vue" {`);
+  lines.push(`  /** Typed \`<nys-*>\` tags in Vue templates (Volar / vue-tsc). */`);
+  lines.push(`  interface GlobalComponents {`);
+  for (const c of components) {
+    lines.push(`    "${c.tag}": DefineComponent<${c.className}Props>;`);
+  }
+  lines.push(`  }`);
+  lines.push(`}`);
+  lines.push(``);
+  // Vue exposes JSX two ways: the global namespace (`vue/jsx`) and the
+  // `vue/jsx-runtime` module (`jsxImportSource: "vue"`). Augment both.
+  for (const [open, close, indent] of [
+    ["declare module \"vue/jsx-runtime\" {", "}", "  "],
+    ["declare global {", "}", "  "],
+  ]) {
+    lines.push(open);
+    lines.push(`${indent}namespace JSX {`);
+    lines.push(`${indent}  /** Typed \`<nys-*>\` tags in TSX / JSX. */`);
+    lines.push(`${indent}  interface IntrinsicElements {`);
+    for (const c of components) {
+      lines.push(`${indent}    "${c.tag}": ${c.className}Props;`);
+    }
+    lines.push(`${indent}  }`);
+    lines.push(`${indent}}`);
+    lines.push(close);
+    lines.push(``);
+  }
+  lines.push(`export {};`);
+  lines.push(``);
+  return lines.join("\n");
+}
+
+export function vuePlugin(options = {}) {
+  const { outDir = "packages/vue/src/generated" } = options;
+
+  return {
+    name: "nysds-vue-types",
+
+    packageLinkPhase({ customElementsManifest }) {
+      const components = listComponents(customElementsManifest);
+      if (components.length === 0) return;
+
+      fs.rmSync(outDir, { recursive: true, force: true });
+      fs.mkdirSync(outDir, { recursive: true });
+
+      const barrel = [`// GENERATED by @nysds/codegen — do not edit.`];
+      for (const component of components) {
+        fs.writeFileSync(
+          path.join(outDir, `${component.className}.ts`),
+          renderVueProps(component)
+        );
+        barrel.push(`export * from "./${component.className}.js";`);
+      }
+      barrel.push(`import "./global.js";`);
+      fs.writeFileSync(path.join(outDir, "global.ts"), renderGlobal(components));
+      fs.writeFileSync(path.join(outDir, "index.ts"), barrel.join("\n") + "\n");
+    },
+  };
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @nysds/codegen public API.
+ *
+ * One package that reads the custom elements manifest and derives every
+ * framework artifact: metadata for generators, naming rules, and the HTML
+ * to JSX / Angular snippet transformer. The CEM plugins ship separately as
+ * `@nysds/codegen/cem-plugins`.
+ */
+export { loadManifest } from "./manifest/load.js";
+export { listComponents, normalizeTypeText } from "./manifest/components.js";
+export { parseFormControlTag } from "./manifest/form-control.js";
+export { isPublicMember, isPublicProp, isExposedEvent, } from "./manifest/filters.js";
+export { NYS_PREFIX, NYS_BLUR_EVENT, pascalize, tagToClass, classToAngularClass, eventToReactProp, eventToAngularOutput, tagToSubpath, tagToPackage, } from "./manifest/naming.js";
+export type { Manifest, ManifestModule, ComponentMeta, PropMeta, EventMeta, SlotMeta, FormControlMeta, } from "./manifest/types.js";
+export { transformExample, toJsx, toAngular } from "./transform/index.js";
+export type { TransformExampleInput, TransformResult, FormsMode, } from "./transform/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7E,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EACL,cAAc,EACd,YAAY,EACZ,cAAc,GACf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,UAAU,EACV,cAAc,EACd,SAAS,EACT,UAAU,EACV,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,EACZ,YAAY,GACb,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,QAAQ,EACR,cAAc,EACd,aAAa,EACb,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,gBAAgB,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAC1E,YAAY,EACV,qBAAqB,EACrB,eAAe,EACf,SAAS,GACV,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * @nysds/codegen public API.
+ *
+ * One package that reads the custom elements manifest and derives every
+ * framework artifact: metadata for generators, naming rules, and the HTML
+ * to JSX / Angular snippet transformer. The CEM plugins ship separately as
+ * `@nysds/codegen/cem-plugins`.
+ */
+export { loadManifest } from "./manifest/load.js";
+export { listComponents, normalizeTypeText } from "./manifest/components.js";
+export { parseFormControlTag } from "./manifest/form-control.js";
+export { isPublicMember, isPublicProp, isExposedEvent, } from "./manifest/filters.js";
+export { NYS_PREFIX, NYS_BLUR_EVENT, pascalize, tagToClass, classToAngularClass, eventToReactProp, eventToAngularOutput, tagToSubpath, tagToPackage, } from "./manifest/naming.js";
+export { transformExample, toJsx, toAngular } from "./transform/index.js";

package/dist/manifest/components.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Component metadata reader. Logic lives in `cem-plugins/lib/core.mjs`;
+ * this module re-exports it with types.
+ */
+export { listComponents, normalizeTypeText, } from "../../cem-plugins/lib/core.mjs";
+//# sourceMappingURL=components.d.ts.map

package/dist/manifest/components.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"components.d.ts","sourceRoot":"","sources":["../../src/manifest/components.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACL,cAAc,EACd,iBAAiB,GAClB,MAAM,gCAAgC,CAAC"}

package/dist/manifest/components.js

@@ -0,0 +1,5 @@
+/**
+ * Component metadata reader. Logic lives in `cem-plugins/lib/core.mjs`;
+ * this module re-exports it with types.
+ */
+export { listComponents, normalizeTypeText, } from "../../cem-plugins/lib/core.mjs";

package/dist/manifest/filters.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Member and event filters. Logic lives in `cem-plugins/lib/core.mjs`;
+ * this module re-exports it with types.
+ */
+export { isPublicMember, isPublicProp, isExposedEvent, } from "../../cem-plugins/lib/core.mjs";
+//# sourceMappingURL=filters.d.ts.map

package/dist/manifest/filters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filters.d.ts","sourceRoot":"","sources":["../../src/manifest/filters.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACL,cAAc,EACd,YAAY,EACZ,cAAc,GACf,MAAM,gCAAgC,CAAC"}

package/dist/manifest/filters.js

@@ -0,0 +1,5 @@
+/**
+ * Member and event filters. Logic lives in `cem-plugins/lib/core.mjs`;
+ * this module re-exports it with types.
+ */
+export { isPublicMember, isPublicProp, isExposedEvent, } from "../../cem-plugins/lib/core.mjs";

package/dist/manifest/form-control.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `@formControl` tag parsing. Logic lives in `cem-plugins/lib/core.mjs`;
+ * this module re-exports it with types.
+ */
+export { parseFormControlTag } from "../../cem-plugins/lib/core.mjs";
+//# sourceMappingURL=form-control.d.ts.map

package/dist/manifest/form-control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-control.d.ts","sourceRoot":"","sources":["../../src/manifest/form-control.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC"}

package/dist/manifest/form-control.js

@@ -0,0 +1,5 @@
+/**
+ * `@formControl` tag parsing. Logic lives in `cem-plugins/lib/core.mjs`;
+ * this module re-exports it with types.
+ */
+export { parseFormControlTag } from "../../cem-plugins/lib/core.mjs";

package/dist/manifest/load.d.ts

@@ -0,0 +1,11 @@
+import type { Manifest } from "./types.js";
+/**
+ * Loads and validates a custom elements manifest.
+ *
+ * Without an argument, resolves the manifest that ships with
+ * `@nysds/components`. The root package's `exports` map doesn't expose
+ * `./custom-elements.json` as a subpath, so resolution goes through the
+ * package entry point and walks up to the package root.
+ */
+export declare function loadManifest(manifestPath?: string): Manifest;
+//# sourceMappingURL=load.d.ts.map

package/dist/manifest/load.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../src/manifest/load.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAkB,MAAM,YAAY,CAAC;AAE3D;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,QAAQ,CAW5D"}

package/dist/manifest/load.js

@@ -0,0 +1,64 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+/**
+ * Loads and validates a custom elements manifest.
+ *
+ * Without an argument, resolves the manifest that ships with
+ * `@nysds/components`. The root package's `exports` map doesn't expose
+ * `./custom-elements.json` as a subpath, so resolution goes through the
+ * package entry point and walks up to the package root.
+ */
+export function loadManifest(manifestPath) {
+    const resolved = manifestPath ?? defaultManifestPath();
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(resolved, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`Cannot read manifest at ${resolved}: ${error.message}`);
+    }
+    return validateManifest(raw, resolved);
+}
+function defaultManifestPath() {
+    const require = createRequire(import.meta.url);
+    let entry;
+    try {
+        entry = require.resolve("@nysds/components");
+    }
+    catch {
+        throw new Error("Cannot resolve @nysds/components. Install it, or pass an explicit manifest path to loadManifest().");
+    }
+    let dir = path.dirname(entry);
+    for (let depth = 0; depth < 4; depth += 1) {
+        const candidate = path.join(dir, "custom-elements.json");
+        if (fs.existsSync(candidate))
+            return candidate;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    throw new Error(`Found @nysds/components at ${entry} but no custom-elements.json near it. Pass an explicit manifest path to loadManifest().`);
+}
+/** Light structural validation: enough to fail fast on the wrong file. */
+function validateManifest(raw, source) {
+    if (typeof raw !== "object" || raw === null) {
+        throw new Error(`${source} is not a custom elements manifest: not an object.`);
+    }
+    const manifest = raw;
+    if (!Array.isArray(manifest.modules)) {
+        throw new Error(`${source} is not a custom elements manifest: missing "modules" array.`);
+    }
+    for (const mod of manifest.modules) {
+        const candidate = mod;
+        if (typeof candidate?.path !== "string") {
+            throw new Error(`${source} is not a custom elements manifest: a module has no "path".`);
+        }
+        if (candidate.declarations !== undefined &&
+            !Array.isArray(candidate.declarations)) {
+            throw new Error(`${source} is not a custom elements manifest: "declarations" of ${candidate.path} is not an array.`);
+        }
+    }
+    return raw;
+}

package/dist/manifest/naming.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Naming rules (README section 4.1 of the framework-support plan is
+ * normative). Logic lives in `cem-plugins/lib/core.mjs`; this module
+ * re-exports it with types.
+ */
+export { NYS_PREFIX, NYS_BLUR_EVENT, pascalize, tagToClass, classToAngularClass, eventToReactProp, eventToAngularOutput, tagToSubpath, tagToPackage, } from "../../cem-plugins/lib/core.mjs";
+//# sourceMappingURL=naming.d.ts.map

package/dist/manifest/naming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"naming.d.ts","sourceRoot":"","sources":["../../src/manifest/naming.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,UAAU,EACV,cAAc,EACd,SAAS,EACT,UAAU,EACV,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,EACZ,YAAY,GACb,MAAM,gCAAgC,CAAC"}

package/dist/manifest/naming.js

@@ -0,0 +1,6 @@
+/**
+ * Naming rules (README section 4.1 of the framework-support plan is
+ * normative). Logic lives in `cem-plugins/lib/core.mjs`; this module
+ * re-exports it with types.
+ */
+export { NYS_PREFIX, NYS_BLUR_EVENT, pascalize, tagToClass, classToAngularClass, eventToReactProp, eventToAngularOutput, tagToSubpath, tagToPackage, } from "../../cem-plugins/lib/core.mjs";

package/dist/manifest/packages.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Package derivation from manifest module paths. Logic lives in
+ * `cem-plugins/lib/core.mjs`; this module re-exports it with types.
+ */
+export { tagToPackage } from "../../cem-plugins/lib/core.mjs";
+//# sourceMappingURL=packages.d.ts.map

package/dist/manifest/packages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"packages.d.ts","sourceRoot":"","sources":["../../src/manifest/packages.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC"}

package/dist/manifest/packages.js

@@ -0,0 +1,5 @@
+/**
+ * Package derivation from manifest module paths. Logic lives in
+ * `cem-plugins/lib/core.mjs`; this module re-exports it with types.
+ */
+export { tagToPackage } from "../../cem-plugins/lib/core.mjs";

package/dist/manifest/types.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Metadata types. Declared once in `cem-plugins/lib/core.d.mts` (next to the
+ * runtime rules) and re-exported here so the TypeScript API and the plugins
+ * can never disagree.
+ */
+export type { Manifest, ManifestModule, ComponentMeta, PropMeta, EventMeta, SlotMeta, FormControlMeta, } from "../../cem-plugins/lib/core.mjs";
+//# sourceMappingURL=types.d.ts.map

package/dist/manifest/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/manifest/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,YAAY,EACV,QAAQ,EACR,cAAc,EACd,aAAa,EACb,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,eAAe,GAChB,MAAM,gCAAgC,CAAC"}

package/dist/manifest/types.js

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

package/dist/transform/index.d.ts

@@ -0,0 +1,20 @@
+import type { Manifest } from "../manifest/types.js";
+import type { FormsMode, TransformResult } from "./shared.js";
+export type { FormsMode, TransformResult } from "./shared.js";
+export { toJsx } from "./to-jsx.js";
+export { toAngular } from "./to-angular.js";
+export interface TransformExampleInput {
+    /** The canonical HTML example. */
+    html: string;
+    framework: "react" | "angular";
+    manifest: Manifest;
+    /**
+     * How form components render. `"none"` (default) keeps snippets static;
+     * `"template"` emits `[(ngModel)]` (Angular) or the controlled pattern
+     * (React); `"reactive"` emits `formControlName` (Angular).
+     */
+    formsMode?: FormsMode;
+}
+/** Transforms one HTML example into a framework snippet. */
+export declare function transformExample(input: TransformExampleInput): TransformResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/transform/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/transform/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAI9D,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,MAAM,WAAW,qBAAqB;IACpC,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,GAAG,SAAS,CAAC;IAC/B,QAAQ,EAAE,QAAQ,CAAC;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,qBAAqB,GAC3B,eAAe,CAKjB"}

package/dist/transform/index.js

@@ -0,0 +1,11 @@
+import { toJsx } from "./to-jsx.js";
+import { toAngular } from "./to-angular.js";
+export { toJsx } from "./to-jsx.js";
+export { toAngular } from "./to-angular.js";
+/** Transforms one HTML example into a framework snippet. */
+export function transformExample(input) {
+    const formsMode = input.formsMode ?? "none";
+    return input.framework === "react"
+        ? toJsx(input.html, input.manifest, formsMode)
+        : toAngular(input.html, input.manifest, formsMode);
+}

package/dist/transform/parse.d.ts

@@ -0,0 +1,19 @@
+import type { DefaultTreeAdapterMap } from "parse5";
+export type P5Node = DefaultTreeAdapterMap["childNode"];
+export type P5Element = DefaultTreeAdapterMap["element"];
+export type P5Text = DefaultTreeAdapterMap["textNode"];
+export type P5Comment = DefaultTreeAdapterMap["commentNode"];
+/**
+ * Parses an HTML fragment (a docs `preview` block or an `@example` block)
+ * into parse5 nodes. parse5 lowercases element and attribute names, matching
+ * what a browser does to the same markup.
+ */
+export declare function parseHtmlFragment(html: string): P5Node[];
+export declare function isElement(node: P5Node): node is P5Element;
+export declare function isText(node: P5Node): node is P5Text;
+export declare function isComment(node: P5Node): node is P5Comment;
+/** Child nodes, reading through `<template>` content. */
+export declare function childNodesOf(element: P5Element): P5Node[];
+/** Concatenated text content of an element's direct text children. */
+export declare function textContent(element: P5Element): string;
+//# sourceMappingURL=parse.d.ts.map