@nysds/codegen 0.0.0-stage → 1.20.1

package/cem-plugins/deps.mjs

@@ -0,0 +1,154 @@
+/**
+ * CEM plugin: rewrites the generated blocks in the framework package.json
+ * files so they stay in lockstep with the monorepo (decisions L3, L4).
+ *
+ * For each target it rewrites:
+ * - `dependencies`: one exact-version entry per `@nysds/nys-*` component
+ *   package that has a wrapper; other dependencies are kept as written.
+ *   The exact versions are what guarantee wrapper/component alignment —
+ *   no `@nysds/components` peer is written (nothing imports the root
+ *   package, and the peer made npm pull the published bundle into
+ *   consumer apps and into this monorepo, where its stale types shadowed
+ *   workspace source).
+ * - `exports`: the barrel entry, one subpath per component, and
+ *   `./package.json`. Hand-added subpaths outside that set are dropped, so
+ *   put extra entry points behind the barrel instead.
+ *
+ * A missing target package.json logs a warning and is skipped — the react
+ * and angular packages are scaffolded in later workstreams.
+ */
+import fs from "node:fs";
+import { listComponents } from "./lib/core.mjs";
+
+function reactSubpathEntry(component) {
+  return {
+    types: `./dist/generated/${component.className}.d.ts`,
+    import: `./dist/generated/${component.className}.js`,
+  };
+}
+
+function angularSubpathEntry(component) {
+  // One ng-packagr secondary entry point per component, generated into the
+  // staging tree by the angular wrapper plugin.
+  return angularEntry(component.subpath);
+}
+
+/** An `exports` entry for one ng-packagr entry point, by its subpath. */
+function angularEntry(subpath) {
+  return {
+    types: `./dist/${subpath}/index.d.ts`,
+    default: `./dist/fesm2022/nysds-angular-${subpath}.mjs`,
+  };
+}
+
+function vueSubpathEntry(component) {
+  return {
+    types: `./dist/generated/${component.className}.d.ts`,
+    import: `./dist/generated/${component.className}.js`,
+  };
+}
+
+const SUBPATH_ENTRY_BY_FRAMEWORK = {
+  react: reactSubpathEntry,
+  vue: vueSubpathEntry,
+  angular: angularSubpathEntry,
+};
+
+function sortObject(obj) {
+  return Object.fromEntries(
+    Object.entries(obj).sort(([a], [b]) => a.localeCompare(b))
+  );
+}
+
+export function depsPlugin(options = {}) {
+  const {
+    rootPackageJson = "package.json",
+    targets = [
+      { path: "packages/react/package.json", framework: "react" },
+      { path: "packages/angular/package.json", framework: "angular" },
+      { path: "packages/vue/package.json", framework: "vue" },
+    ],
+  } = options;
+
+  return {
+    name: "nysds-framework-deps",
+
+    packageLinkPhase({ customElementsManifest }) {
+      const components = listComponents(customElementsManifest);
+      if (components.length === 0) return;
+
+      const rootPkg = JSON.parse(fs.readFileSync(rootPackageJson, "utf8"));
+      const version = rootPkg.version;
+
+      const componentPackages = [
+        ...new Set(components.map((component) => component.packageName)),
+      ].sort();
+
+      for (const target of targets) {
+        if (!fs.existsSync(target.path)) {
+          console.warn(
+            `[nysds-framework-deps] ${target.path} not found — skipped (scaffolded in a later workstream).`
+          );
+          continue;
+        }
+        const subpathEntry = SUBPATH_ENTRY_BY_FRAMEWORK[target.framework];
+        if (!subpathEntry) {
+          throw new Error(
+            `[nysds-framework-deps] Unknown framework "${target.framework}" for ${target.path}`
+          );
+        }
+
+        const pkg = JSON.parse(fs.readFileSync(target.path, "utf8"));
+
+        const dependencies = {};
+        for (const [name, range] of Object.entries(pkg.dependencies ?? {})) {
+          if (!componentPackages.includes(name) && !name.startsWith("@nysds/nys-")) {
+            dependencies[name] = range;
+          }
+        }
+        for (const packageName of componentPackages) {
+          dependencies[packageName] = version;
+        }
+        pkg.dependencies = sortObject(dependencies);
+
+        // Remove the peer this plugin used to write, so regeneration heals
+        // package.json files from before the peer was dropped.
+        if (pkg.peerDependencies) {
+          delete pkg.peerDependencies["@nysds/components"];
+        }
+
+        // Subpath exports for per-component bundling. These are generated for
+        // both frameworks: hand-maintaining the Angular half is what let it
+        // drift into advertising a subpath for every component while the build
+        // emitted a single bundle.
+        const exportsMap = {};
+        if (target.framework === "angular") {
+          exportsMap["."] = {
+            types: "./dist/index.d.ts",
+            default: "./dist/fesm2022/nysds-angular.mjs",
+          };
+          // The shared form-control accessors are their own entry point so no
+          // source file is compiled into more than one bundle.
+          exportsMap["./forms"] = angularEntry("forms");
+        } else {
+          exportsMap["."] = pkg.exports?.["."] ?? {
+            types: "./dist/index.d.ts",
+            import: "./dist/index.js",
+          };
+        }
+        for (const component of components) {
+          exportsMap[`./${component.subpath}`] = subpathEntry(component);
+        }
+        if (target.framework === "angular") {
+          // Several tools resolve `<pkg>/package.json` directly. Safe to add
+          // here: ng-packagr generates its own map for dist/ and never reads
+          // this one.
+          exportsMap["./package.json"] = "./package.json";
+        }
+        pkg.exports = exportsMap;
+
+        fs.writeFileSync(target.path, JSON.stringify(pkg, null, 2) + "\n");
+      }
+    },
+  };
+}

package/cem-plugins/form-control.mjs

@@ -0,0 +1,94 @@
+/**
+ * CEM plugin: reads the class-level `@formControl` JSDoc tag and attaches
+ * `declaration.formControl = { kind, changeEvent, inputEvent? }` to the
+ * manifest.
+ *
+ * A malformed tag fails the analyze run with the file path. A form component
+ * (any class extending the form-control superclass) without the tag throws
+ * in strict mode and logs one warning otherwise. The allowlist names classes
+ * that extend the superclass but are not bindable form controls.
+ */
+import { parseFormControlTag } from "./lib/core.mjs";
+
+export function formControlPlugin(options = {}) {
+  const {
+    strict = true,
+    allowlist = ["NysButton", "NysRadiobutton", "NysOption"],
+    superclassName = "NysFormControlElement",
+  } = options;
+  const allowed = new Set(allowlist);
+
+  /** Map<modulePath, Map<className, FormControlMeta>> */
+  const collected = new Map();
+
+  return {
+    name: "nysds-form-control",
+
+    analyzePhase({ ts, node, moduleDoc }) {
+      if (!ts.isClassDeclaration(node) || !("jsDoc" in node)) return;
+      const className = node.name?.getText();
+      if (!className) return;
+
+      for (const jsdoc of node.jsDoc ?? []) {
+        if (!Array.isArray(jsdoc.tags)) continue;
+        for (const tag of jsdoc.tags) {
+          let tagName;
+          try {
+            tagName = tag.tagName.getText();
+          } catch {
+            continue;
+          }
+          if (tagName !== "formControl") continue;
+
+          let parsed;
+          try {
+            parsed = parseFormControlTag(
+              typeof tag.comment === "string" ? tag.comment : ""
+            );
+          } catch (error) {
+            throw new Error(
+              `[nysds-form-control] ${moduleDoc.path}: ${error.message}`
+            );
+          }
+
+          if (!collected.has(moduleDoc.path)) {
+            collected.set(moduleDoc.path, new Map());
+          }
+          collected.get(moduleDoc.path).set(className, parsed);
+        }
+      }
+    },
+
+    packageLinkPhase({ customElementsManifest }) {
+      // Attach collected tags.
+      for (const mod of customElementsManifest.modules ?? []) {
+        const byClass = collected.get(mod.path);
+        if (!byClass) continue;
+        for (const decl of mod.declarations ?? []) {
+          const formControl = byClass.get(decl.name);
+          if (formControl) decl.formControl = formControl;
+        }
+      }
+
+      // Verify every form component carries the tag.
+      const missing = [];
+      for (const mod of customElementsManifest.modules ?? []) {
+        for (const decl of mod.declarations ?? []) {
+          if (decl.kind !== "class") continue;
+          if (decl.superclass?.name !== superclassName) continue;
+          if (allowed.has(decl.name)) continue;
+          if (!decl.formControl) missing.push(`${decl.name} (${mod.path})`);
+        }
+      }
+
+      if (missing.length > 0) {
+        const message =
+          `[nysds-form-control] ${missing.length} form component(s) extend ` +
+          `${superclassName} but have no @formControl JSDoc tag:\n  - ` +
+          missing.join("\n  - ");
+        if (strict) throw new Error(message);
+        console.warn(`${message}\n  (strict: false — continuing)`);
+      }
+    },
+  };
+}

package/cem-plugins/index.mjs

@@ -0,0 +1,12 @@
+/**
+ * CEM plugin entry point. Imported by
+ * `src/scripts/custom-elements-manifest.config.mjs` as
+ * `@nysds/codegen/cem-plugins`. Register `formControlPlugin()` before
+ * `reactPlugin()`, `angularPlugin()` and `vuePlugin()` so the wrappers see the
+ * `formControl` metadata.
+ */
+export { formControlPlugin } from "./form-control.mjs";
+export { reactPlugin } from "./react.mjs";
+export { angularPlugin } from "./angular.mjs";
+export { vuePlugin } from "./vue.mjs";
+export { depsPlugin } from "./deps.mjs";

package/cem-plugins/lib/core.d.mts

@@ -0,0 +1,79 @@
+/**
+ * Types for `core.mjs`. Hand-written; keep in sync with the implementation.
+ * The TypeScript public API re-exports these, so this file is the single
+ * place the metadata types are declared.
+ */
+
+export declare const NYS_PREFIX: string;
+export declare const NYS_BLUR_EVENT: string;
+
+export interface FormControlMeta {
+  kind: "value" | "checked" | "files";
+  changeEvent: string;
+  inputEvent?: string;
+}
+
+export interface PropMeta {
+  name: string;
+  attribute?: string;
+  type: string;
+  default?: string;
+  description?: string;
+  isBoolean: boolean;
+  isNumber: boolean;
+  isPrimitive: boolean;
+}
+
+export interface EventMeta {
+  name: string;
+  typeText: string;
+  reactProp: string;
+  angularOutput: string;
+  description?: string;
+}
+
+export interface SlotMeta {
+  name: string;
+  description?: string;
+}
+
+export interface ComponentMeta {
+  tag: string;
+  className: string;
+  packageName: string;
+  subpath: string;
+  modulePath: string;
+  description?: string;
+  props: PropMeta[];
+  events: EventMeta[];
+  slots: SlotMeta[];
+  formControl?: FormControlMeta;
+}
+
+export interface ManifestModule {
+  path: string;
+  declarations?: unknown[];
+  [key: string]: unknown;
+}
+
+export interface Manifest {
+  modules: ManifestModule[];
+  [key: string]: unknown;
+}
+
+export declare function pascalize(name: string): string;
+export declare function tagToClass(tag: string, manifest?: Manifest): string;
+export declare function classToAngularClass(className: string): string;
+export declare function eventToReactProp(eventName: string): string;
+export declare function eventToAngularOutput(eventName: string): string;
+export declare function tagToSubpath(tag: string): string;
+export declare function tagToPackage(modulePath: string): string;
+
+export declare function isPublicMember(member: unknown): boolean;
+export declare function isPublicProp(member: unknown): boolean;
+export declare function isExposedEvent(event: unknown): boolean;
+
+export declare function parseFormControlTag(comment: string): FormControlMeta;
+
+export declare function normalizeTypeText(text: unknown): string | undefined;
+export declare function listComponents(manifest: Manifest): ComponentMeta[];

package/cem-plugins/lib/core.mjs

@@ -0,0 +1,288 @@
+/**
+ * Shared rules for NYSDS code generation.
+ *
+ * This module is the single source of truth for naming rules, member and
+ * event filters, `@formControl` parsing, package derivation, and component
+ * metadata. It is plain JavaScript so the CEM plugins can run before
+ * `@nysds/codegen` is built. The TypeScript sources in `src/manifest/`
+ * re-export from this file and add no logic of their own; `core.d.mts`
+ * carries the types.
+ */
+
+/** Prefix shared by every NYSDS custom element tag. */
+export const NYS_PREFIX = "nys-";
+
+/** Event that marks a form control as touched in framework wrappers. */
+export const NYS_BLUR_EVENT = `${NYS_PREFIX}blur`;
+
+// ---------------------------------------------------------------------------
+// Naming rules (README.md section 4.1 is normative)
+// ---------------------------------------------------------------------------
+
+/**
+ * Mechanical PascalCase of a tag. Inner capitals in a segment are kept.
+ * Use `tagToClass` with a manifest when the real class name matters:
+ * class names in the manifest can capitalize differently.
+ */
+export function pascalize(name) {
+  return name
+    .split("-")
+    .map((part) => (part ? part[0].toUpperCase() + part.slice(1) : part))
+    .join("");
+}
+
+/**
+ * Tag to class name. With a manifest, returns the manifest
+ * `declaration.name`, which is authoritative. Without one, falls back to
+ * mechanical PascalCase.
+ */
+export function tagToClass(tag, manifest) {
+  if (manifest) {
+    for (const component of listComponents(manifest)) {
+      if (component.tag === tag) return component.className;
+    }
+  }
+  return pascalize(tag);
+}
+
+/** Class name to Angular component class name. */
+export function classToAngularClass(className) {
+  return `${className}Component`;
+}
+
+/** Event name to React prop: `on` + PascalCase of the full event name. */
+export function eventToReactProp(eventName) {
+  return `on${pascalize(eventName)}`;
+}
+
+/** Event name to Angular output: camelCase of the full event name. */
+export function eventToAngularOutput(eventName) {
+  const parts = eventName.split("-");
+  return (
+    parts[0] +
+    parts
+      .slice(1)
+      .map((part) => (part ? part[0].toUpperCase() + part.slice(1) : part))
+      .join("")
+  );
+}
+
+/** Tag to import subpath: the tag minus the prefix. */
+export function tagToSubpath(tag) {
+  return tag.startsWith(NYS_PREFIX) ? tag.slice(NYS_PREFIX.length) : tag;
+}
+
+/**
+ * Manifest module path to package name. Derived, never a table:
+ * `packages/nys-accordion/src/nys-accordionitem.ts` -> `@nysds/nys-accordion`.
+ */
+export function tagToPackage(modulePath) {
+  const match = /(?:^|\/)packages\/([^/]+)\//.exec(modulePath);
+  if (!match) {
+    throw new Error(
+      `Cannot derive a package name from module path "${modulePath}": expected a packages/<name>/ segment.`
+    );
+  }
+  return `@nysds/${match[1]}`;
+}
+
+// ---------------------------------------------------------------------------
+// Filters
+// ---------------------------------------------------------------------------
+
+/** Lit and custom-element machinery that must never surface as a prop. */
+const LIT_INTERNAL_MEMBERS = new Set([
+  "updateComplete",
+  "isUpdatePending",
+  "hasUpdated",
+  "renderRoot",
+  "renderOptions",
+  "shadowRootOptions",
+  "elementProperties",
+  "elementStyles",
+  "styles",
+  "properties",
+  "observedAttributes",
+  "formAssociated",
+]);
+
+/**
+ * True when a manifest member is part of the public API: not static, not
+ * underscore- or hash-prefixed, not `privacy: private | protected`, not
+ * deprecated, and not Lit machinery.
+ */
+export function isPublicMember(member) {
+  if (!member || typeof member.name !== "string" || member.name.length === 0) {
+    return false;
+  }
+  if (member.static) return false;
+  if (member.name.startsWith("_") || member.name.startsWith("#")) return false;
+  if (member.privacy === "private" || member.privacy === "protected") {
+    return false;
+  }
+  if (member.deprecated) return false;
+  if (LIT_INTERNAL_MEMBERS.has(member.name)) return false;
+  return true;
+}
+
+/** True for a public, non-deprecated field. */
+export function isPublicProp(member) {
+  return member?.kind === "field" && isPublicMember(member);
+}
+
+/** True when an event should surface in wrappers and snippets. */
+export function isExposedEvent(event) {
+  if (!event || typeof event.name !== "string" || event.name.length === 0) {
+    return false;
+  }
+  if (event.deprecated) return false;
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// @formControl parsing
+// ---------------------------------------------------------------------------
+
+const FORM_CONTROL_KINDS = new Set(["value", "checked", "files"]);
+const EVENT_NAME_RE = new RegExp(`^${NYS_PREFIX}[a-z][a-zA-Z-]*$`);
+
+/**
+ * Parses the `@formControl <kind> <changeEvent> [inputEvent]` JSDoc tag
+ * body. Throws on a malformed tag; the caller adds the file path.
+ */
+export function parseFormControlTag(comment) {
+  const parts = String(comment ?? "")
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean);
+  if (parts.length < 2 || parts.length > 3) {
+    throw new Error(
+      `@formControl expects "<kind> <changeEvent> [inputEvent]"; got "${String(comment ?? "").trim()}"`
+    );
+  }
+  const [kind, changeEvent, inputEvent] = parts;
+  if (!FORM_CONTROL_KINDS.has(kind)) {
+    throw new Error(
+      `@formControl kind must be "value", "checked", or "files"; got "${kind}"`
+    );
+  }
+  for (const eventName of [changeEvent, inputEvent]) {
+    if (eventName !== undefined && !EVENT_NAME_RE.test(eventName)) {
+      throw new Error(
+        `@formControl event "${eventName}" must be a ${NYS_PREFIX}* event name`
+      );
+    }
+  }
+  return inputEvent ? { kind, changeEvent, inputEvent } : { kind, changeEvent };
+}
+
+// ---------------------------------------------------------------------------
+// Component metadata
+// ---------------------------------------------------------------------------
+
+/** Collapses whitespace in a manifest type text and trims a leading pipe. */
+export function normalizeTypeText(text) {
+  if (typeof text !== "string") return undefined;
+  const collapsed = text.replace(/\s+/g, " ").replace(/^\|\s*/, "").trim();
+  return collapsed.length > 0 ? collapsed : undefined;
+}
+
+const PRIMITIVE_PARTS = new Set([
+  "string",
+  "number",
+  "boolean",
+  "null",
+  "undefined",
+]);
+
+function isPrimitiveType(typeText) {
+  if (!typeText) return false;
+  return typeText
+    .split("|")
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .every(
+      (part) =>
+        PRIMITIVE_PARTS.has(part) ||
+        /^".*"$/.test(part) ||
+        /^'.*'$/.test(part) ||
+        /^-?\d+(\.\d+)?$/.test(part)
+    );
+}
+
+function isNumberType(typeText) {
+  if (!typeText) return false;
+  const parts = typeText
+    .split("|")
+    .map((part) => part.trim())
+    .filter(Boolean);
+  return (
+    parts.includes("number") &&
+    parts.every((part) => part === "number" || part === "null" || part === "undefined")
+  );
+}
+
+/**
+ * Reads every NYSDS component out of a custom elements manifest and returns
+ * uniform metadata: naming, public props, exposed events, slots, and the
+ * `formControl` block when the manifest carries one. Sorted by tag.
+ */
+export function listComponents(manifest) {
+  const components = [];
+  for (const mod of manifest?.modules ?? []) {
+    for (const decl of mod.declarations ?? []) {
+      if (decl.kind !== "class") continue;
+      const tag = decl.tagName;
+      if (typeof tag !== "string" || !tag.startsWith(NYS_PREFIX)) continue;
+
+      const attributeByField = new Map();
+      for (const attr of decl.attributes ?? []) {
+        if (attr.fieldName && attr.name) {
+          attributeByField.set(attr.fieldName, attr.name);
+        }
+      }
+
+      const props = (decl.members ?? []).filter(isPublicProp).map((member) => {
+        const type = normalizeTypeText(member.type?.text);
+        return {
+          name: member.name,
+          attribute: member.attribute ?? attributeByField.get(member.name),
+          type: type ?? "unknown",
+          default: member.default,
+          description: member.description,
+          isBoolean: type === "boolean",
+          isNumber: isNumberType(type),
+          isPrimitive: isPrimitiveType(type),
+        };
+      });
+
+      const events = (decl.events ?? []).filter(isExposedEvent).map((event) => ({
+        name: event.name,
+        typeText: normalizeTypeText(event.type?.text) ?? "CustomEvent",
+        reactProp: eventToReactProp(event.name),
+        angularOutput: eventToAngularOutput(event.name),
+        description: event.description,
+      }));
+
+      const slots = (decl.slots ?? [])
+        .filter((slot) => typeof slot?.name === "string")
+        .map((slot) => ({ name: slot.name, description: slot.description }));
+
+      const component = {
+        tag,
+        className: decl.name,
+        packageName: tagToPackage(mod.path),
+        subpath: tagToSubpath(tag),
+        modulePath: mod.path,
+        description: decl.description,
+        props,
+        events,
+        slots,
+      };
+      if (decl.formControl) component.formControl = decl.formControl;
+      components.push(component);
+    }
+  }
+  components.sort((a, b) => a.tag.localeCompare(b.tag));
+  return components;
+}