@genesislcap/ts-builder 15.4.0 → 15.4.1

package/dist/react-wrapper-generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"react-wrapper-generator.d.ts","sourceRoot":"","sources":["../src/react-wrapper-generator.ts"],"names":[],"mappings":"AAyCA,KAAK,cAAc,GAAG;IAAE,SAAS,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,SAAS,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AA0jC/F,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAgDhF"}
+{"version":3,"file":"react-wrapper-generator.d.ts","sourceRoot":"","sources":["../src/react-wrapper-generator.ts"],"names":[],"mappings":"AA0IA,KAAK,cAAc,GAAG;IAAE,SAAS,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,SAAS,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AA8lC/F,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAoDhF"}

package/dist/react-wrapper-generator.js

@@ -5,6 +5,63 @@ const tslib_1 = require("tslib");
 const node_fs_1 = require("node:fs");
 const promises_1 = require("node:fs/promises");
 const node_path_1 = require("node:path");
+const consola_1 = tslib_1.__importDefault(require("consola"));
+/** A bare TS identifier — `type` is emitted into a `.d.ts` verbatim. */
+const OVERRIDE_TYPE_RE = /^[A-Za-z_$][\w$]*$/;
+/** A safe module specifier — `from` is emitted inside single quotes (`from '<spec>';`), so it must
+ *  not be able to close the quote and inject further declarations. Covers relative paths and
+ *  scoped package names; rejects quotes, semicolons and whitespace. */
+const OVERRIDE_FROM_RE = /^[.\w@/-]+$/;
+/** A safe prop name. Also emitted into the `.d.ts` — both quoted in the `Omit` key list and as the
+ *  re-declared key — so it carries the same injection risk as `from`. Hyphens are allowed because
+ *  React props legitimately include `aria-*` and `data-*`; quotes, pipes and whitespace are not.
+ *  Without this, a name like `appearance' | 'disabled` widened the `Omit` to two props AND emitted
+ *  a union as a key, which is not valid in a type literal. */
+const OVERRIDE_PROP_RE = /^[A-Za-z_$][\w$-]*$/;
+/**
+ * Read + validate the `reactWrapperPropTypes` map.
+ *
+ * Malformed entries are skipped rather than thrown: bad config must never abort a build — the
+ * wrapper still generates, just without that override. But skipping SILENTLY makes a typo
+ * undiagnosable, so every skip is reported with the component, prop and reason.
+ */
+function readPropTypeOverrides(packageJson) {
+    const raw = packageJson.reactWrapperPropTypes;
+    if (raw === undefined)
+        return {};
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        consola_1.default.warn('[ts-builder] Ignoring "reactWrapperPropTypes": expected an object.');
+        return {};
+    }
+    const out = {};
+    for (const [component, props] of Object.entries(raw)) {
+        if (!props || typeof props !== 'object' || Array.isArray(props)) {
+            consola_1.default.warn(`[ts-builder] Ignoring reactWrapperPropTypes.${component}: expected an object of prop → { type, from }.`);
+            continue;
+        }
+        const byProp = {};
+        for (const [prop, spec] of Object.entries(props)) {
+            const s = spec;
+            const where = `reactWrapperPropTypes.${component}.${prop}`;
+            if (!OVERRIDE_PROP_RE.test(prop)) {
+                consola_1.default.warn(`[ts-builder] Skipping ${where}: prop name must match ${OVERRIDE_PROP_RE} (letters, digits, _, $, -).`);
+                continue;
+            }
+            if (!s || typeof s.type !== 'string' || !OVERRIDE_TYPE_RE.test(s.type)) {
+                consola_1.default.warn(`[ts-builder] Skipping ${where}: "type" must be a bare TypeScript identifier (got ${JSON.stringify(s === null || s === void 0 ? void 0 : s.type)}).`);
+                continue;
+            }
+            if (typeof s.from !== 'string' || !OVERRIDE_FROM_RE.test(s.from.trim())) {
+                consola_1.default.warn(`[ts-builder] Skipping ${where}: "from" must be a module specifier matching ${OVERRIDE_FROM_RE} (got ${JSON.stringify(s.from)}).`);
+                continue;
+            }
+            byProp[prop] = { type: s.type, from: s.from.trim() };
+        }
+        if (Object.keys(byProp).length > 0)
+            out[component] = byProp;
+    }
+    return out;
+}
 // ── Constants ────────────────────────────────────────────────────────────────
 const PRIMITIVE_UNION_REGEX = /^(?:\s*(?:string|number|boolean|bigint|null|undefined|unknown|any|void|'[^']*'|"[^"]*"|`[^`]*`|(?:\d+(?:\.\d+)?))\s*)(?:\|\s*(?:string|number|boolean|bigint|null|undefined|unknown|any|void|'[^']*'|"[^"]*"|`[^`]*`|(?:\d+(?:\.\d+)?))\s*)*$/;
 const IDENTIFIER_TOKEN_REGEX = /[A-Za-z_$][A-Za-z0-9_$]*(?:\.[A-Za-z_$][A-Za-z0-9_$]*)*/g;
@@ -661,8 +718,8 @@ function generateReactWrapperJs(entries, format) {
     }
     return lines.join('\n');
 }
-function generateReactWrapperDts(entries, typeImportState) {
-    var _a;
+function generateReactWrapperDts(entries, typeImportState, propTypeOverrides = {}) {
+    var _a, _b;
     const valid = entries.filter((e) => e.declaration.name && e.declaration.tagName && e.modulePath);
     if (!valid.length)
         return '';
@@ -686,7 +743,38 @@ function generateReactWrapperDts(entries, typeImportState) {
             const handlerType = toEventHandlerType((_a = event === null || event === void 0 ? void 0 : event.type) === null || _a === void 0 ? void 0 : _a.text, wrapperTypeState, event === null || event === void 0 ? void 0 : event.description);
             return `      ${handlerName}?: ${handlerType};`;
         });
-        declarationLines.push(`export declare const ${name}: React.ForwardRefExoticComponent<`, `  React.PropsWithChildren<`, `    Omit<PublicOf<${name}WC>, 'children' | 'style'> &`, `    HTMLWCProps & {`, ...eventLines, '    }', `  > & React.RefAttributes<${name}WC>`, '>;', `export type ${name}Ref = ${name}WC;`, '');
+        // Prop-type overrides (see PropTypeOverrides): drop the configured props out of the
+        // `PublicOf` mapping and re-declare them with the named type, so a design system can correct
+        // a prop whose inherited type it has outgrown. No config ⇒ identical output to before.
+        // Route each override's type through the SAME import machinery every other type uses
+        // (registerTypeImport + trackImportedIdentifierUsage) rather than writing `usedImports`
+        // directly. That is what detects an identifier already imported from a DIFFERENT module: two
+        // `import type { X }` lines from different specifiers would be a duplicate-identifier error in
+        // the generated .d.ts. On a collision, drop the override and warn — emitting the widened prop
+        // without its import would leave the declaration referencing an unresolvable type, which is
+        // worse than the original narrow type.
+        const overrides = (_b = propTypeOverrides[name]) !== null && _b !== void 0 ? _b : {};
+        const applied = [];
+        for (const prop of Object.keys(overrides).sort()) {
+            const { type, from } = overrides[prop];
+            registerTypeImport(wrapperTypeState, type, from);
+            if (wrapperTypeState.importsByIdentifier.get(type) !== from) {
+                consola_1.default.warn(`[ts-builder] Skipping the ${name}.${prop} prop-type override: "${type}" is already imported from a different module, so importing it from "${from}" would clash.`);
+                continue;
+            }
+            trackImportedIdentifierUsage(wrapperTypeState, type, from);
+            applied.push(prop);
+        }
+        const omitKeys = ["'children'", "'style'", ...applied.map((p) => `'${p}'`)].join(' | ');
+        const overrideLines = applied.map((prop) => {
+            // React props are legitimately allowed to be hyphenated (`aria-*`, `data-*`), which is not a
+            // valid bare key in a type literal — quote those. Identifier-safe names stay unquoted so the
+            // common output reads naturally. (The Omit key list above is always quoted, so it is safe
+            // for either form.)
+            const key = OVERRIDE_TYPE_RE.test(prop) ? prop : `'${prop}'`;
+            return `      ${key}?: ${overrides[prop].type};`;
+        });
+        declarationLines.push(`export declare const ${name}: React.ForwardRefExoticComponent<`, `  React.PropsWithChildren<`, `    Omit<PublicOf<${name}WC>, ${omitKeys}> &`, `    HTMLWCProps & {`, ...overrideLines, ...eventLines, '    }', `  > & React.RefAttributes<${name}WC>`, '>;', `export type ${name}Ref = ${name}WC;`, '');
     }
     return [
         '/**',
@@ -970,7 +1058,7 @@ function generateReactWrappers(cwd) {
         yield Promise.all([
             (0, promises_1.writeFile)((0, node_path_1.resolve)(cwd, 'dist/react.mjs'), generateReactWrapperJs(entries, 'esm'), 'utf8'),
             (0, promises_1.writeFile)((0, node_path_1.resolve)(cwd, 'dist/react.cjs'), generateReactWrapperJs(entries, 'cjs'), 'utf8'),
-            (0, promises_1.writeFile)(reactDtsPath, generateReactWrapperDts(entries, typeImportState), 'utf8'),
+            (0, promises_1.writeFile)(reactDtsPath, generateReactWrapperDts(entries, typeImportState, readPropTypeOverrides(packageJson)), 'utf8'),
         ]);
         return { generated: true, path: reactDtsPath };
     });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/ts-builder",
   "description": "Typescript builder",
-  "version": "15.4.0",
+  "version": "15.4.1",
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,7 +17,7 @@
   },
   "dependencies": {
     "@custom-elements-manifest/analyzer": "^0.8.2",
-    "@genesislcap/build-kit": "15.4.0",
+    "@genesislcap/build-kit": "15.4.1",
     "consola": "^3.0.2",
     "copyfiles": "^2.4.1",
     "pkg-types": "^1.0.2"
@@ -30,5 +30,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "2c61100a9805e799c8047a26ad6a147d1ac1af87"
+  "gitHead": "984a77280362d69ba3eab6256dbb7fe03b8c76b3"
 }

package/src/react-wrapper-generator.ts

@@ -1,6 +1,7 @@
 import { readFileSync } from 'node:fs';
 import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
+import consola from 'consola';
 
 // ── CEM type shapes ──────────────────────────────────────────────────────────
 
@@ -37,6 +38,102 @@ type TypeImportState = {
   wildcardExportModules: Set<string>;
 };
 
+// ── Prop type overrides ──────────────────────────────────────────────────────
+//
+// WHY THIS EXISTS. Wrapper props are derived from the element CLASS via
+// `Omit<PublicOf<XWC>, …>`, so a prop's type is whatever TypeScript resolves up the inheritance
+// chain. That is normally exactly right — but it breaks when a design system RESTYLES a prop whose
+// type is a closed union owned by a base package. The reported case: rapid-design-system's
+// `button.styles.ts` styles 12 `appearance` values (primary, secondary, danger, …) while the
+// inherited FAST type is `ButtonAppearance = 'accent' | 'lightweight' | 'neutral' | 'outline' |
+// 'stealth'`. Consumers writing `appearance="danger"` get TS2322 for a value that renders
+// correctly, and the three FAST-only values type-check while rendering unstyled.
+//
+// It CANNOT be fixed on the component. TypeScript requires a derived property to be assignable to
+// the base's, so widening an inherited property is rejected — verified for all three candidate
+// forms: `declare appearance: RapidButtonAppearance` and `declare appearance: string` both give
+// TS2416, and class/interface declaration merging gives TS2415 + TS2430. (`foundation-zero` exports
+// a `ZeroButtonAppearance` union but never wires it to the class, which is why that precedent does
+// not actually work; `SearchBar` gets away with `appearance: string` only because its own base has
+// no `appearance`.) The wrapper boundary is therefore the only place the public prop type can be
+// corrected.
+//
+// Opt-in per package via package.json — same convention as the existing `customElements` field:
+//
+//   "reactWrapperPropTypes": {
+//     "Button": { "appearance": { "type": "RapidButtonAppearance", "from": "./button/button.styles" } }
+//   }
+//
+// A configured prop is removed from the `PublicOf` mapping and re-declared as optional with the
+// named type, which is imported into react.d.ts. Packages that configure nothing are byte-for-byte
+// unchanged, so this is inert for every wrapper that does not opt in.
+type PropTypeOverride = { type: string; from: string };
+type PropTypeOverrides = Record<string, Record<string, PropTypeOverride>>;
+
+/** A bare TS identifier — `type` is emitted into a `.d.ts` verbatim. */
+const OVERRIDE_TYPE_RE = /^[A-Za-z_$][\w$]*$/;
+/** A safe module specifier — `from` is emitted inside single quotes (`from '<spec>';`), so it must
+ *  not be able to close the quote and inject further declarations. Covers relative paths and
+ *  scoped package names; rejects quotes, semicolons and whitespace. */
+const OVERRIDE_FROM_RE = /^[.\w@/-]+$/;
+/** A safe prop name. Also emitted into the `.d.ts` — both quoted in the `Omit` key list and as the
+ *  re-declared key — so it carries the same injection risk as `from`. Hyphens are allowed because
+ *  React props legitimately include `aria-*` and `data-*`; quotes, pipes and whitespace are not.
+ *  Without this, a name like `appearance' | 'disabled` widened the `Omit` to two props AND emitted
+ *  a union as a key, which is not valid in a type literal. */
+const OVERRIDE_PROP_RE = /^[A-Za-z_$][\w$-]*$/;
+
+/**
+ * Read + validate the `reactWrapperPropTypes` map.
+ *
+ * Malformed entries are skipped rather than thrown: bad config must never abort a build — the
+ * wrapper still generates, just without that override. But skipping SILENTLY makes a typo
+ * undiagnosable, so every skip is reported with the component, prop and reason.
+ */
+function readPropTypeOverrides(packageJson: Record<string, unknown>): PropTypeOverrides {
+  const raw = packageJson.reactWrapperPropTypes;
+  if (raw === undefined) return {};
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    consola.warn('[ts-builder] Ignoring "reactWrapperPropTypes": expected an object.');
+    return {};
+  }
+  const out: PropTypeOverrides = {};
+  for (const [component, props] of Object.entries(raw as Record<string, unknown>)) {
+    if (!props || typeof props !== 'object' || Array.isArray(props)) {
+      consola.warn(
+        `[ts-builder] Ignoring reactWrapperPropTypes.${component}: expected an object of prop → { type, from }.`,
+      );
+      continue;
+    }
+    const byProp: Record<string, PropTypeOverride> = {};
+    for (const [prop, spec] of Object.entries(props as Record<string, unknown>)) {
+      const s = spec as Partial<PropTypeOverride> | undefined;
+      const where = `reactWrapperPropTypes.${component}.${prop}`;
+      if (!OVERRIDE_PROP_RE.test(prop)) {
+        consola.warn(
+          `[ts-builder] Skipping ${where}: prop name must match ${OVERRIDE_PROP_RE} (letters, digits, _, $, -).`,
+        );
+        continue;
+      }
+      if (!s || typeof s.type !== 'string' || !OVERRIDE_TYPE_RE.test(s.type)) {
+        consola.warn(
+          `[ts-builder] Skipping ${where}: "type" must be a bare TypeScript identifier (got ${JSON.stringify(s?.type)}).`,
+        );
+        continue;
+      }
+      if (typeof s.from !== 'string' || !OVERRIDE_FROM_RE.test(s.from.trim())) {
+        consola.warn(
+          `[ts-builder] Skipping ${where}: "from" must be a module specifier matching ${OVERRIDE_FROM_RE} (got ${JSON.stringify(s.from)}).`,
+        );
+        continue;
+      }
+      byProp[prop] = { type: s.type, from: s.from.trim() };
+    }
+    if (Object.keys(byProp).length > 0) out[component] = byProp;
+  }
+  return out;
+}
+
 // ── Public API return type ───────────────────────────────────────────────────
 
 type GenerateResult = { generated: true; path: string } | { generated: false; reason: string };
@@ -810,6 +907,7 @@ function generateReactWrapperJs(entries: CEMElementEntry[], format: 'esm' | 'cjs
 function generateReactWrapperDts(
   entries: CEMElementEntry[],
   typeImportState: TypeImportState,
+  propTypeOverrides: PropTypeOverrides = {},
 ): string {
   const valid = entries.filter((e) => e.declaration.name && e.declaration.tagName && e.modulePath);
   if (!valid.length) return '';
@@ -844,11 +942,46 @@ function generateReactWrapperDts(
       return `      ${handlerName}?: ${handlerType};`;
     });
 
+    // Prop-type overrides (see PropTypeOverrides): drop the configured props out of the
+    // `PublicOf` mapping and re-declare them with the named type, so a design system can correct
+    // a prop whose inherited type it has outgrown. No config ⇒ identical output to before.
+    // Route each override's type through the SAME import machinery every other type uses
+    // (registerTypeImport + trackImportedIdentifierUsage) rather than writing `usedImports`
+    // directly. That is what detects an identifier already imported from a DIFFERENT module: two
+    // `import type { X }` lines from different specifiers would be a duplicate-identifier error in
+    // the generated .d.ts. On a collision, drop the override and warn — emitting the widened prop
+    // without its import would leave the declaration referencing an unresolvable type, which is
+    // worse than the original narrow type.
+    const overrides = propTypeOverrides[name] ?? {};
+    const applied: string[] = [];
+    for (const prop of Object.keys(overrides).sort()) {
+      const { type, from } = overrides[prop];
+      registerTypeImport(wrapperTypeState, type, from);
+      if (wrapperTypeState.importsByIdentifier.get(type) !== from) {
+        consola.warn(
+          `[ts-builder] Skipping the ${name}.${prop} prop-type override: "${type}" is already imported from a different module, so importing it from "${from}" would clash.`,
+        );
+        continue;
+      }
+      trackImportedIdentifierUsage(wrapperTypeState, type, from);
+      applied.push(prop);
+    }
+    const omitKeys = ["'children'", "'style'", ...applied.map((p) => `'${p}'`)].join(' | ');
+    const overrideLines = applied.map((prop) => {
+      // React props are legitimately allowed to be hyphenated (`aria-*`, `data-*`), which is not a
+      // valid bare key in a type literal — quote those. Identifier-safe names stay unquoted so the
+      // common output reads naturally. (The Omit key list above is always quoted, so it is safe
+      // for either form.)
+      const key = OVERRIDE_TYPE_RE.test(prop) ? prop : `'${prop}'`;
+      return `      ${key}?: ${overrides[prop].type};`;
+    });
+
     declarationLines.push(
       `export declare const ${name}: React.ForwardRefExoticComponent<`,
       `  React.PropsWithChildren<`,
-      `    Omit<PublicOf<${name}WC>, 'children' | 'style'> &`,
+      `    Omit<PublicOf<${name}WC>, ${omitKeys}> &`,
       `    HTMLWCProps & {`,
+      ...overrideLines,
       ...eventLines,
       '    }',
       `  > & React.RefAttributes<${name}WC>`,
@@ -1165,7 +1298,11 @@ export async function generateReactWrappers(cwd: string): Promise<GenerateResult
   await Promise.all([
     writeFile(resolve(cwd, 'dist/react.mjs'), generateReactWrapperJs(entries, 'esm'), 'utf8'),
     writeFile(resolve(cwd, 'dist/react.cjs'), generateReactWrapperJs(entries, 'cjs'), 'utf8'),
-    writeFile(reactDtsPath, generateReactWrapperDts(entries, typeImportState), 'utf8'),
+    writeFile(
+      reactDtsPath,
+      generateReactWrapperDts(entries, typeImportState, readPropTypeOverrides(packageJson)),
+      'utf8',
+    ),
   ]);
 
   return { generated: true, path: reactDtsPath };