nudge-ui 0.2.0

package/dist/compiler/packageComponentContracts.js

@@ -0,0 +1,308 @@
+import { dirname, relative, resolve } from "node:path";
+import ts from "typescript";
+function isBareModuleSpecifier(value) {
+    return value !== ""
+        && !value.startsWith(".")
+        && !value.startsWith("/")
+        && !value.startsWith("\0")
+        && !value.startsWith("virtual:");
+}
+function rootJsxIdentifier(tagName) {
+    let current = tagName;
+    while (ts.isPropertyAccessExpression(current))
+        current = current.expression;
+    return ts.isIdentifier(current) ? current.text : null;
+}
+/** Returns bare modules whose imported bindings are rendered as JSX. */
+export function collectPackageComponentModules(code, fileName) {
+    const source = ts.createSourceFile(fileName, code, ts.ScriptTarget.Latest, true, fileName.endsWith("x") ? ts.ScriptKind.TSX : ts.ScriptKind.JSX);
+    const modulesByBinding = new Map();
+    for (const statement of source.statements) {
+        if (!ts.isImportDeclaration(statement)
+            || !ts.isStringLiteral(statement.moduleSpecifier)
+            || !isBareModuleSpecifier(statement.moduleSpecifier.text))
+            continue;
+        const moduleSpecifier = statement.moduleSpecifier.text;
+        const clause = statement.importClause;
+        if (clause?.name)
+            modulesByBinding.set(clause.name.text, moduleSpecifier);
+        const bindings = clause?.namedBindings;
+        if (bindings && ts.isNamespaceImport(bindings)) {
+            modulesByBinding.set(bindings.name.text, moduleSpecifier);
+        }
+        else if (bindings && ts.isNamedImports(bindings)) {
+            for (const element of bindings.elements) {
+                if (!element.isTypeOnly)
+                    modulesByBinding.set(element.name.text, moduleSpecifier);
+            }
+        }
+    }
+    const modules = new Set();
+    const visit = (node) => {
+        if (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) {
+            const binding = rootJsxIdentifier(node.tagName);
+            const moduleSpecifier = binding ? modulesByBinding.get(binding) : undefined;
+            if (moduleSpecifier)
+                modules.add(moduleSpecifier);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    return [...modules].sort();
+}
+const DEFAULT_COMPILER_OPTIONS = {
+    allowJs: false,
+    jsx: ts.JsxEmit.ReactJSX,
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    noEmit: true,
+    skipLibCheck: true,
+    strictNullChecks: true,
+    target: ts.ScriptTarget.ES2022,
+};
+const STRUCTURAL_PROP_NAMES = new Set([
+    "children",
+    "className",
+    "href",
+    "id",
+    "ref",
+    "role",
+    "src",
+    "style",
+]);
+function symbolName(symbol) {
+    if (!symbol)
+        return null;
+    return symbol.getName();
+}
+function typeName(type) {
+    return symbolName(type.aliasSymbol) ?? symbolName(type.getSymbol());
+}
+function typeArguments(checker, type) {
+    if (!(type.flags & ts.TypeFlags.Object))
+        return [];
+    return checker.getTypeArguments(type);
+}
+function isNamedType(type, name) {
+    return typeName(type) === name;
+}
+function isUndefined(type) {
+    return (type.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Void)) !== 0;
+}
+function definedTypes(type) {
+    return (type.isUnion() ? type.types : [type]).filter((member) => !isUndefined(member));
+}
+function literalValue(type) {
+    if (type.flags & ts.TypeFlags.StringLiteral)
+        return type.value;
+    if (type.flags & ts.TypeFlags.NumberLiteral)
+        return type.value;
+    if (type.flags & ts.TypeFlags.BooleanLiteral) {
+        return type.intrinsicName === "true";
+    }
+    return null;
+}
+function conditionalObjectMatches(type, checker, location, accepts) {
+    if (!(type.flags & ts.TypeFlags.Object))
+        return false;
+    if (checker.getIndexTypeOfType(type, ts.IndexKind.String)
+        || checker.getIndexTypeOfType(type, ts.IndexKind.Number))
+        return false;
+    const properties = checker.getPropertiesOfType(type);
+    if (properties.length === 0)
+        return false;
+    return properties.every((property) => {
+        const propertyType = checker.getTypeOfSymbolAtLocation(property, location);
+        const propertyMembers = definedTypes(propertyType);
+        return propertyMembers.length > 0 && propertyMembers.every(accepts);
+    });
+}
+function literalOptions(members, checker, location) {
+    const values = members
+        .map(literalValue)
+        .filter((value) => value !== null);
+    // A public prop can accept a finite scalar vocabulary as well as a
+    // responsive/conditional object. The Inspector only offers this select when
+    // the current runtime value is scalar, so retain valid scalar alternatives
+    // without pretending the object form is itself editable here.
+    if (values.length < 2)
+        return null;
+    const primitive = typeof values[0];
+    if (!values.every((value) => typeof value === primitive))
+        return null;
+    const allowed = new Set(values.map((value) => `${typeof value}:${String(value)}`));
+    if (!members.every((member) => {
+        const value = literalValue(member);
+        if (value !== null)
+            return allowed.has(`${typeof value}:${String(value)}`);
+        return conditionalObjectMatches(member, checker, location, (propertyMember) => {
+            const propertyValue = literalValue(propertyMember);
+            return propertyValue !== null
+                && allowed.has(`${typeof propertyValue}:${String(propertyValue)}`);
+        });
+    }))
+        return null;
+    return values;
+}
+function isBooleanType(members, checker, location) {
+    const scalarMembers = members.filter((member) => (member.flags & (ts.TypeFlags.Boolean | ts.TypeFlags.BooleanLiteral)) !== 0);
+    if (scalarMembers.length === 0)
+        return false;
+    if (!members.every((member) => scalarMembers.includes(member)
+        || conditionalObjectMatches(member, checker, location, (propertyMember) => (propertyMember.flags & (ts.TypeFlags.Boolean | ts.TypeFlags.BooleanLiteral)) !== 0)))
+        return false;
+    if (scalarMembers.some((member) => (member.flags & ts.TypeFlags.Boolean) !== 0))
+        return true;
+    const values = new Set(scalarMembers.map(literalValue));
+    return values.has(false) && values.has(true);
+}
+function propContract(symbol, checker, location) {
+    const name = symbol.getName();
+    if (!name || STRUCTURAL_PROP_NAMES.has(name) || name.startsWith("aria") || name.startsWith("data")) {
+        return null;
+    }
+    const types = definedTypes(checker.getTypeOfSymbolAtLocation(symbol, location));
+    if (isBooleanType(types, checker, location)) {
+        return {
+            name,
+            control: "boolean",
+            options: [false, true],
+            optional: (symbol.flags & ts.SymbolFlags.Optional) !== 0,
+        };
+    }
+    const options = literalOptions(types, checker, location);
+    if (options) {
+        return {
+            name,
+            control: "select",
+            options,
+            optional: (symbol.flags & ts.SymbolFlags.Optional) !== 0,
+        };
+    }
+    if (types.length === 1 && (types[0].flags & ts.TypeFlags.String)) {
+        return {
+            name,
+            control: "text",
+            options: [],
+            optional: (symbol.flags & ts.SymbolFlags.Optional) !== 0,
+        };
+    }
+    return null;
+}
+function packageName(moduleSpecifier) {
+    const parts = moduleSpecifier.split("/");
+    return moduleSpecifier.startsWith("@")
+        ? parts.slice(0, 2).join("/")
+        : parts[0] ?? moduleSpecifier;
+}
+function packageRootFor(resolvedModule, moduleSpecifier) {
+    const normalized = resolvedModule.replaceAll("\\", "/");
+    const marker = `/node_modules/${packageName(moduleSpecifier)}/`;
+    const markerStart = normalized.lastIndexOf(marker);
+    if (markerStart >= 0)
+        return normalized.slice(0, markerStart + marker.length - 1);
+    return dirname(resolvedModule);
+}
+function isInside(root, fileName) {
+    const relativeFile = relative(resolve(root), resolve(fileName));
+    return relativeFile === ""
+        || (relativeFile !== ".." && !relativeFile.startsWith(".." + "/") && !relativeFile.startsWith(".." + "\\"));
+}
+function packageDeclaredSymbols(propsType, checker, packageRoot) {
+    return checker.getPropertiesOfType(propsType).filter((symbol) => symbol.getDeclarations()?.some((declaration) => isInside(packageRoot, declaration.getSourceFile().fileName)) ?? false);
+}
+function propsTypeFromComponent(componentType, checker, location) {
+    if (isNamedType(componentType, "ForwardRefExoticComponent")) {
+        return typeArguments(checker, componentType)[0] ?? null;
+    }
+    const signature = componentType.getCallSignatures()
+        .find((candidate) => candidate.parameters.length > 0);
+    const props = signature?.parameters[0];
+    if (props)
+        return checker.getTypeOfSymbolAtLocation(props, location);
+    return null;
+}
+function componentContract(exportName, symbol, checker, packageRoot, moduleSpecifier) {
+    if (exportName !== "default" && !/^[A-Z]/.test(exportName))
+        return null;
+    const target = symbol.flags & ts.SymbolFlags.Alias
+        ? checker.getAliasedSymbol(symbol)
+        : symbol;
+    const declaration = target.valueDeclaration ?? target.declarations?.[0];
+    if (!declaration)
+        return null;
+    const componentType = checker.getTypeOfSymbolAtLocation(target, declaration);
+    const propsType = propsTypeFromComponent(componentType, checker, declaration);
+    if (!propsType)
+        return null;
+    const props = packageDeclaredSymbols(propsType, checker, packageRoot)
+        .map((prop) => propContract(prop, checker, declaration))
+        .filter((prop) => prop !== null);
+    if (props.length === 0)
+        return null;
+    return {
+        componentId: `${moduleSpecifier}#${exportName}`,
+        name: exportName,
+        file: moduleSpecifier,
+        props,
+        provenance: "typescript",
+    };
+}
+/**
+ * Extracts scalar controls from component exports in an installed package.
+ *
+ * It follows TypeScript's resolved module graph, including barrel re-exports
+ * and declaration-file aliases, rather than trying to parse one declaration
+ * file in isolation.
+ */
+export function extractPackageComponentContracts(context) {
+    return extractPackageComponentContractCatalog({
+        hostFile: context.hostFile,
+        moduleSpecifiers: [context.moduleSpecifier],
+        compilerOptions: context.compilerOptions,
+    });
+}
+/** Extracts several package modules through one declaration-only program. */
+export function extractPackageComponentContractCatalog(context) {
+    const compilerOptions = { ...DEFAULT_COMPILER_OPTIONS, ...context.compilerOptions };
+    const moduleSpecifiers = [...new Set(context.moduleSpecifiers)].sort();
+    if (moduleSpecifiers.length === 0)
+        return [];
+    const virtualFile = resolve(dirname(context.hostFile), "__nudge_ui_package_contracts__.tsx");
+    const virtualSource = moduleSpecifiers
+        .map((moduleSpecifier, index) => `import * as __nudgeUiPackage${index} from ${JSON.stringify(moduleSpecifier)};`)
+        .join("\n");
+    const host = ts.createCompilerHost(compilerOptions);
+    const getSourceFile = host.getSourceFile.bind(host);
+    host.fileExists = (fileName) => fileName === virtualFile || ts.sys.fileExists(fileName);
+    host.readFile = (fileName) => fileName === virtualFile ? virtualSource : ts.sys.readFile(fileName);
+    host.getSourceFile = (fileName, languageVersion, onError, shouldCreateNewSourceFile) => fileName === virtualFile
+        ? ts.createSourceFile(fileName, virtualSource, languageVersion, true, ts.ScriptKind.TSX)
+        : getSourceFile(fileName, languageVersion, onError, shouldCreateNewSourceFile);
+    const program = ts.createProgram({
+        rootNames: [virtualFile],
+        options: compilerOptions,
+        host,
+    });
+    const checker = program.getTypeChecker();
+    return moduleSpecifiers.flatMap((moduleSpecifier) => {
+        const resolution = ts.resolveModuleName(moduleSpecifier, virtualFile, compilerOptions, host).resolvedModule;
+        if (!resolution)
+            return [];
+        const sourceFile = program.getSourceFile(resolution.resolvedFileName);
+        if (!sourceFile)
+            return [];
+        const moduleSymbol = checker.getSymbolAtLocation(sourceFile);
+        if (!moduleSymbol)
+            return [];
+        const packageRoot = packageRootFor(resolution.resolvedFileName, moduleSpecifier);
+        return checker.getExportsOfModule(moduleSymbol)
+            .map((symbol) => {
+            const exportName = symbolName(symbol);
+            return exportName
+                ? componentContract(exportName, symbol, checker, packageRoot, moduleSpecifier)
+                : null;
+        })
+            .filter((contract) => contract !== null);
+    });
+}

package/dist/compiler/reactComponentProtocols.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Adapter-independent React compatibility data.
+ *
+ * Library names live in this replaceable catalog rather than in compiler
+ * control flow. Hosts may extend or replace these facts as their ecosystem
+ * support grows.
+ */
+export declare const defaultReactComponentProtocols: {
+    react: {
+        default: {
+            readonly wrap: false;
+        };
+        exports: {
+            Fragment: {
+                readonly wrap: false;
+                readonly slots: {
+                    readonly children: "rendered";
+                };
+            };
+            StrictMode: {
+                readonly wrap: false;
+                readonly slots: {
+                    readonly children: "rendered";
+                };
+            };
+            Profiler: {
+                readonly wrap: false;
+                readonly slots: {
+                    readonly children: "rendered";
+                };
+            };
+            Suspense: {
+                wrap: false;
+                slots: {
+                    children: "rendered";
+                    fallback: "rendered";
+                };
+            };
+        };
+    };
+    "react-router": {
+        readonly default: {
+            readonly wrap: false;
+        };
+        readonly exports: {
+            readonly BrowserRouter: {
+                readonly wrap: false;
+                readonly slots: {
+                    readonly children: "rendered";
+                };
+            };
+            readonly HashRouter: {
+                readonly wrap: false;
+                readonly slots: {
+                    readonly children: "rendered";
+                };
+            };
+            readonly MemoryRouter: {
+                readonly wrap: false;
+                readonly slots: {
+                    readonly children: "rendered";
+                };
+            };
+            readonly Router: {
+                readonly wrap: false;
+                readonly slots: {
+                    readonly children: "rendered";
+                };
+            };
+            readonly StaticRouter: {
+                readonly wrap: false;
+                readonly slots: {
+                    readonly children: "rendered";
+                };
+            };
+            readonly Routes: {
+                readonly wrap: false;
+                readonly slots: {
+                    readonly children: "rendered";
+                };
+            };
+            readonly Route: {
+                readonly wrap: false;
+                readonly slots: {
+                    readonly children: "rendered";
+                    readonly element: "rendered";
+                    readonly errorElement: "rendered";
+                    readonly hydrateFallbackElement: "rendered";
+                };
+            };
+        };
+    };
+    "react-router-dom": {
+        readonly default: {
+            readonly wrap: false;
+        };
+        readonly exports: {
+            readonly BrowserRouter: {
+                readonly wrap: false;
+                readonly slots: {
+                    readonly children: "rendered";
+                };
+            };
+            readonly HashRouter: {
+                readonly wrap: false;
+                readonly slots: {
+                    readonly children: "rendered";
+                };
+            };
+            readonly MemoryRouter: {
+                readonly wrap: false;
+                readonly slots: {
+                    readonly children: "rendered";
+                };
+            };
+            readonly Router: {
+                readonly wrap: false;
+                readonly slots: {
+                    readonly children: "rendered";
+                };
+            };
+            readonly StaticRouter: {
+                readonly wrap: false;
+                readonly slots: {
+                    readonly children: "rendered";
+                };
+            };
+            readonly Routes: {
+                readonly wrap: false;
+                readonly slots: {
+                    readonly children: "rendered";
+                };
+            };
+            readonly Route: {
+                readonly wrap: false;
+                readonly slots: {
+                    readonly children: "rendered";
+                    readonly element: "rendered";
+                    readonly errorElement: "rendered";
+                    readonly hydrateFallbackElement: "rendered";
+                };
+            };
+        };
+    };
+};

package/dist/compiler/reactComponentProtocols.js

@@ -0,0 +1,47 @@
+const PRESERVE = { wrap: false };
+const RENDERED_CHILDREN = { wrap: false, slots: { children: "rendered" } };
+/**
+ * Adapter-independent React compatibility data.
+ *
+ * Library names live in this replaceable catalog rather than in compiler
+ * control flow. Hosts may extend or replace these facts as their ecosystem
+ * support grows.
+ */
+export const defaultReactComponentProtocols = {
+    react: {
+        default: PRESERVE,
+        exports: {
+            Fragment: RENDERED_CHILDREN,
+            StrictMode: RENDERED_CHILDREN,
+            Profiler: RENDERED_CHILDREN,
+            Suspense: {
+                wrap: false,
+                slots: { children: "rendered", fallback: "rendered" },
+            },
+        },
+    },
+    "react-router": routerProtocols(),
+    "react-router-dom": routerProtocols(),
+};
+function routerProtocols() {
+    return {
+        default: PRESERVE,
+        exports: {
+            BrowserRouter: RENDERED_CHILDREN,
+            HashRouter: RENDERED_CHILDREN,
+            MemoryRouter: RENDERED_CHILDREN,
+            Router: RENDERED_CHILDREN,
+            StaticRouter: RENDERED_CHILDREN,
+            Routes: RENDERED_CHILDREN,
+            Route: {
+                wrap: false,
+                slots: {
+                    children: "rendered",
+                    element: "rendered",
+                    errorElement: "rendered",
+                    hydrateFallbackElement: "rendered",
+                },
+            },
+        },
+    };
+}

package/dist/compiler/reactIdentity.d.ts

@@ -0,0 +1,15 @@
+import { type SourceMap } from "magic-string";
+import { type ComponentInstrumentationOptions } from "./componentInstrumentation.js";
+export type { ComponentInstrumentationOptions } from "./componentInstrumentation.js";
+export interface InjectResult {
+    code: string;
+    map: SourceMap | null;
+}
+export interface InjectIdentityOptions extends ComponentInstrumentationOptions {
+    instrumentComponents?: boolean;
+    /** Module specifier emitted for the host-owned semantic runtime. */
+    componentRuntimeModule?: string;
+}
+export declare const DEFAULT_COMPONENT_RUNTIME_MODULE = "nudge-ui/internal/component-runtime";
+export declare function injectIdentity(code: string, id: string, root?: string, options?: InjectIdentityOptions): InjectResult | null;
+export declare function injectDataCid(code: string, id: string, root?: string): InjectResult | null;