@scaffold-ui-kit/preview 0.0.0-stage → 2.3.0

package/dist/props-from.js

@@ -0,0 +1,510 @@
+// Read a manual component's props from its React driver's props interface, so the
+// preview cannot drift from the code. The read is syntactic - source files parsed,
+// no program or type checker - so it costs milliseconds per component. It takes
+// the own members of the interface or object type, or of each operand of an
+// intersection that is one, resolving type aliases and interfaces declared in the
+// same file or imported from another (a relative path, a tsconfig path, or the
+// kit's own package name), re-exports included. It also reads a few type forms a
+// driver uses to build on a template component's props:
+//
+// - `ComponentProps<typeof X>` (or `ComponentPropsWithRef`,
+//   `ComponentPropsWithoutRef`), where `X` names one of the kit's template
+//   components: that template's props, and `children` when it has a default slot;
+// - `Omit<T, 'a' | 'b'>` over a readable `T`: `T`'s members without those names;
+// - a generic type alias given arguments: its body with the arguments in place;
+// - a conditional type that always holds (`T extends unknown ? A : never`, the
+//   idiom that applies `A` to each member of a union): its true branch.
+//
+// Whatever stays opaque (a function, an object, a utility type over a native
+// element) becomes a hidden prop the check lists, or contributes nothing.
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import ts from 'typescript';
+import { parseType } from './lib/parse-type.js';
+/** Splits `'<file>#<InterfaceName>'`, failing on any other shape. */
+function parseReference(reference) {
+    const [file, name, ...rest] = reference.split('#');
+    if (!file || !name || rest.length > 0) {
+        throw new Error(`propsFrom '${reference}' must be '<file relative to the kit root>#<InterfaceName>'`);
+    }
+    return { file, name };
+}
+/** The React utility types that take a component's props from `typeof X`. */
+const COMPONENT_PROPS_TYPES = new Set([
+    'ComponentProps',
+    'ComponentPropsWithRef',
+    'ComponentPropsWithoutRef',
+]);
+/** Finds type declarations by name across a kit's source files, following
+ *  imports and re-exports with TypeScript's module resolution and the kit's
+ *  tsconfig. Parses each file once. */
+export class DeclarationResolver {
+    files = new Map();
+    options;
+    constructor(kitRoot) {
+        const configurationPath = ts.findConfigFile(kitRoot, ts.sys.fileExists);
+        const parsed = configurationPath
+            ? ts.parseJsonConfigFileContent(ts.readConfigFile(configurationPath, ts.sys.readFile).config, ts.sys, dirname(configurationPath))
+            : undefined;
+        this.options = {
+            ...(parsed?.options ?? {}),
+            // Bundler resolution reads package `exports`, so a kit importing its own
+            // package by name resolves to its source.
+            moduleResolution: parsed?.options.moduleResolution ?? ts.ModuleResolutionKind.Bundler,
+            module: parsed?.options.module ?? ts.ModuleKind.ESNext,
+        };
+    }
+    /** Parses source that is not on disk, as if it were the file at `path`, so
+     *  its imports resolve from there. Not cached. */
+    virtual(path, text) {
+        return ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    }
+    file(path) {
+        let file = this.files.get(path);
+        if (!file) {
+            file = ts.createSourceFile(path, readFileSync(path, 'utf8'), ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+            this.files.set(path, file);
+        }
+        return file;
+    }
+    resolveModule(specifier, from) {
+        const resolved = ts.resolveModuleName(specifier, from.fileName, this.options, ts.sys).resolvedModule;
+        return resolved && existsSync(resolved.resolvedFileName)
+            ? this.file(resolved.resolvedFileName)
+            : undefined;
+    }
+    /** The declaration `name` refers to inside `file`: declared there, or imported. */
+    find(name, file, seen = new Set()) {
+        const key = `${file.fileName}#${name}`;
+        if (seen.has(key))
+            return undefined;
+        seen.add(key);
+        for (const statement of file.statements) {
+            if (ts.isInterfaceDeclaration(statement) &&
+                statement.name.text === name) {
+                return { kind: 'interface', node: statement, file };
+            }
+            if (ts.isTypeAliasDeclaration(statement) &&
+                statement.name.text === name) {
+                return { kind: 'alias', node: statement, file };
+            }
+        }
+        for (const statement of file.statements) {
+            if (ts.isImportDeclaration(statement) &&
+                ts.isStringLiteral(statement.moduleSpecifier)) {
+                const bindings = statement.importClause?.namedBindings;
+                if (!bindings || !ts.isNamedImports(bindings))
+                    continue;
+                for (const element of bindings.elements) {
+                    if (element.name.text !== name)
+                        continue;
+                    const target = this.resolveModule(statement.moduleSpecifier.text, file);
+                    return target
+                        ? this.findExport((element.propertyName ?? element.name).text, target, seen)
+                        : undefined;
+                }
+            }
+        }
+        return undefined;
+    }
+    /** The declaration a module exports as `name`, through re-exports. */
+    findExport(name, file, seen) {
+        const local = this.find(name, file, seen);
+        if (local)
+            return local;
+        for (const statement of file.statements) {
+            if (!ts.isExportDeclaration(statement) || !statement.moduleSpecifier)
+                continue;
+            if (!ts.isStringLiteral(statement.moduleSpecifier))
+                continue;
+            const clause = statement.exportClause;
+            let exported;
+            if (!clause)
+                exported = name;
+            else if (ts.isNamedExports(clause)) {
+                const element = clause.elements.find((candidate) => candidate.name.text === name);
+                exported = element
+                    ? (element.propertyName ?? element.name).text
+                    : undefined;
+            }
+            if (exported === undefined)
+                continue;
+            const target = this.resolveModule(statement.moduleSpecifier.text, file);
+            const found = target
+                ? this.findExport(exported, target, seen)
+                : undefined;
+            if (found)
+                return found;
+        }
+        return undefined;
+    }
+}
+/**
+ * Reads the own members of the interface (or object type alias, or intersection
+ * of them) `propsFrom` names into preview prop definitions.
+ *
+ * @param reference - `'<file relative to the kit root>#<InterfaceName>'`
+ * @param kitRoot - The kit root the file resolves against
+ * @param templates - The kit's template components, which a
+ *   `ComponentProps<typeof X>` in the type can name
+ * @returns The props, the default-slot flag, and the hidden and member names
+ */
+export function readPropsFrom(reference, kitRoot, templates = []) {
+    const { file, name } = parseReference(reference);
+    const path = resolve(kitRoot, file);
+    if (!existsSync(path))
+        throw new Error(`propsFrom '${reference}': no file at ${path}`);
+    const resolver = new DeclarationResolver(kitRoot);
+    const source = resolver.file(path);
+    const declaration = resolver.find(name, source);
+    const located = declaration
+        ? membersOf(declaration, {
+            resolver,
+            templates,
+            bindings: new Map(),
+            seen: new Set(),
+        })
+        : undefined;
+    if (!located) {
+        throw new Error(`propsFrom '${reference}': no interface or object type named ${name} in ${file}`);
+    }
+    // Expands aliases one member at a time, so a union of aliases reads as the
+    // union of their members; anything else keeps its source text.
+    const typeText = (node, file, seen = new Set()) => {
+        if (ts.isUnionTypeNode(node))
+            return node.types
+                .map((member) => typeText(member, file, seen))
+                .join(' | ');
+        if (ts.isParenthesizedTypeNode(node))
+            return typeText(node.type, file, seen);
+        if (ts.isTypeReferenceNode(node) &&
+            ts.isIdentifier(node.typeName) &&
+            !node.typeArguments) {
+            const found = resolver.find(node.typeName.text, file);
+            const key = found ? `${found.file.fileName}#${node.typeName.text}` : '';
+            if (found?.kind === 'alias' && !seen.has(key)) {
+                return typeText(found.node.type, found.file, new Set([...seen, key]));
+            }
+        }
+        return node.getText(file);
+    };
+    // Later operands of an intersection win a shared name, as the type would.
+    const byName = new Map();
+    for (const entry of located) {
+        const memberName = locatedName(entry);
+        if (memberName !== undefined)
+            byName.set(memberName, entry);
+    }
+    const result = {
+        props: {},
+        hasChildren: false,
+        childrenScoped: false,
+        hiddenProps: [],
+        memberNames: [],
+    };
+    for (const [memberName, entry] of byName) {
+        if (entry.kind === 'template-children') {
+            result.memberNames.push('children');
+            result.hasChildren = true;
+            result.childrenScoped = entry.scoped;
+            continue;
+        }
+        if (entry.kind === 'template') {
+            result.memberNames.push(memberName);
+            result.props[memberName] = entry.definition;
+            if (parseType(entry.definition.type).kind === 'complex')
+                result.hiddenProps.push(memberName);
+            continue;
+        }
+        const { member, file: memberFile } = entry;
+        if (!ts.isPropertySignature(member) && !ts.isMethodSignature(member))
+            continue;
+        result.memberNames.push(memberName);
+        if (memberName === 'children') {
+            const childrenType = ts.isPropertySignature(member) && member.type ? member.type : undefined;
+            result.hasChildren =
+                childrenType !== undefined && !ts.isFunctionTypeNode(childrenType);
+            result.childrenScoped = false;
+            continue;
+        }
+        // A method signature is a function prop: never a control.
+        const type = ts.isPropertySignature(member) && member.type
+            ? typeText(member.type, memberFile)
+            : '(...) => unknown';
+        result.props[memberName] = {
+            type,
+            ...(member.questionToken ? {} : { required: true }),
+        };
+        if (parseType(type).kind === 'complex')
+            result.hiddenProps.push(memberName);
+    }
+    return result;
+}
+/** The name a located member declares, when it has a plain one. */
+function locatedName(entry) {
+    if (entry.kind === 'template')
+        return entry.name;
+    if (entry.kind === 'template-children')
+        return 'children';
+    const { name } = entry.member;
+    return name && (ts.isIdentifier(name) || ts.isStringLiteral(name))
+        ? name.text
+        : undefined;
+}
+/** The members a declaration contributes: an interface's own members, an object
+ *  type's, or each readable operand's of an intersection. `undefined` when the
+ *  declaration holds no object type at all. */
+function membersOf(declaration, context) {
+    const key = `${declaration.file.fileName}#${declaration.node.name.text}`;
+    if (context.seen.has(key))
+        return [];
+    const inner = { ...context, seen: new Set([...context.seen, key]) };
+    if (declaration.kind === 'interface') {
+        return declaration.node.members.map((member) => ({
+            kind: 'member',
+            member,
+            file: declaration.file,
+        }));
+    }
+    return typeMembers(declaration.node.type, declaration.file, inner);
+}
+/** The rightmost identifier of a type name: `ComponentProps` for both
+ *  `ComponentProps` and `React.ComponentProps`. */
+function simpleName(name) {
+    return ts.isIdentifier(name) ? name.text : name.right.text;
+}
+/** The string literals of `'a'` or `'a' | 'b'`, or `undefined` for anything else. */
+function literalNames(node, file, context) {
+    if (ts.isParenthesizedTypeNode(node))
+        return literalNames(node.type, file, context);
+    if (ts.isLiteralTypeNode(node) && ts.isStringLiteral(node.literal))
+        return [node.literal.text];
+    if (ts.isUnionTypeNode(node)) {
+        const parts = node.types.map((part) => literalNames(part, file, context));
+        return parts.every((part) => part !== undefined)
+            ? parts.flatMap((part) => part ?? [])
+            : undefined;
+    }
+    if (ts.isTypeReferenceNode(node) && ts.isIdentifier(node.typeName)) {
+        const bound = context.bindings.get(node.typeName.text);
+        if (bound)
+            return literalNames(bound.node, bound.file, {
+                ...context,
+                bindings: bound.bindings,
+            });
+    }
+    return undefined;
+}
+function typeMembers(node, file, context) {
+    if (ts.isParenthesizedTypeNode(node))
+        return typeMembers(node.type, file, context);
+    if (ts.isTypeLiteralNode(node))
+        return node.members.map((member) => ({
+            kind: 'member',
+            member,
+            file,
+        }));
+    if (ts.isIntersectionTypeNode(node)) {
+        // A utility type or anything else unreadable contributes nothing; the
+        // intersection still reads when one operand is an object type.
+        const parts = node.types.map((part) => typeMembers(part, file, context));
+        return parts.some((part) => part !== undefined)
+            ? parts.flatMap((part) => part ?? [])
+            : undefined;
+    }
+    // A conditional that always holds is its true branch.
+    if (ts.isConditionalTypeNode(node)) {
+        const always = node.extendsType.kind === ts.SyntaxKind.UnknownKeyword ||
+            node.extendsType.kind === ts.SyntaxKind.AnyKeyword;
+        return always ? typeMembers(node.trueType, file, context) : undefined;
+    }
+    if (!ts.isTypeReferenceNode(node))
+        return undefined;
+    const name = simpleName(node.typeName);
+    const typeArguments = node.typeArguments ?? [];
+    // A generic alias's parameter reads as the argument it was given.
+    if (ts.isIdentifier(node.typeName)) {
+        const bound = context.bindings.get(name);
+        if (bound)
+            return typeMembers(bound.node, bound.file, {
+                ...context,
+                bindings: bound.bindings,
+            });
+    }
+    if (COMPONENT_PROPS_TYPES.has(name) && typeArguments.length === 1) {
+        const [argument] = typeArguments;
+        if (ts.isTypeQueryNode(argument)) {
+            const component = simpleName(argument.exprName);
+            const template = context.templates.find((candidate) => candidate.name === component);
+            if (!template)
+                return undefined;
+            return [
+                ...Object.entries(template.props).map(([propName, definition]) => ({
+                    kind: 'template',
+                    name: propName,
+                    definition,
+                })),
+                ...(template.hasDefaultSlot
+                    ? [
+                        {
+                            kind: 'template-children',
+                            scoped: template.defaultSlotScoped === true,
+                        },
+                    ]
+                    : []),
+            ];
+        }
+    }
+    if (name === 'Omit' && typeArguments.length === 2) {
+        const base = typeMembers(typeArguments[0], file, context);
+        const omitted = literalNames(typeArguments[1], file, context);
+        if (!base || !omitted)
+            return undefined;
+        return base.filter((entry) => {
+            const entryName = locatedName(entry);
+            return entryName === undefined || !omitted.includes(entryName);
+        });
+    }
+    if (!ts.isIdentifier(node.typeName))
+        return undefined;
+    const found = context.resolver.find(name, file);
+    if (!found)
+        return undefined;
+    const parameters = found.kind === 'alias' ? (found.node.typeParameters ?? []) : [];
+    if (parameters.length === 0 || typeArguments.length === 0)
+        return membersOf(found, { ...context, bindings: new Map() });
+    // A generic alias given arguments: its body, each parameter bound to the
+    // argument in this position (read where the reference is).
+    const bindings = new Map();
+    parameters.forEach((parameter, index) => {
+        const argument = typeArguments[index] ?? parameter.default;
+        if (argument)
+            bindings.set(parameter.name.text, {
+                node: argument,
+                file: typeArguments[index] ? file : found.file,
+                bindings: typeArguments[index] ? context.bindings : new Map(),
+            });
+    });
+    return membersOf(found, { ...context, bindings });
+}
+/** The keywords a type's text can name that are never a declaration. */
+const TYPE_KEYWORDS = new Set([
+    'string',
+    'number',
+    'boolean',
+    'bigint',
+    'symbol',
+    'object',
+    'unknown',
+    'any',
+    'never',
+    'null',
+    'undefined',
+    'void',
+    'true',
+    'false',
+]);
+/**
+ * A template prop's type with the named types it uses expanded, read through
+ * the template's own import statements: an alias becomes its members (a
+ * generic one with its arguments in place), an interface reads as an object
+ * form, and a union is flattened. `undefined` when the type names nothing to
+ * expand, or expands to the same text.
+ *
+ * @param type - The prop's type as the template writes it
+ * @param templatePath - The template file, which its imports resolve from
+ * @param imports - The template's import statements
+ * @param resolver - The declaration resolver to read through
+ * @returns The expanded type, or `undefined`
+ * @example
+ * // With `import type { StackAlign } from '@acme/kit/scripts';`
+ * resolveNamedType('StackAlign', templatePath, imports, resolver);
+ * // "'start' | 'center' | 'end'"
+ */
+export function resolveNamedType(type, templatePath, imports, resolver) {
+    const names = type.match(/[A-Za-z_$][\w$]*/g) ?? [];
+    if (names.every((name) => TYPE_KEYWORDS.has(name)))
+        return undefined;
+    const marker = '__PreviewPropType';
+    const source = resolver.virtual(templatePath, `${imports.join('\n')}\ntype ${marker} = ${type};\n`);
+    const statement = source.statements.find((candidate) => ts.isTypeAliasDeclaration(candidate) && candidate.name.text === marker);
+    if (!statement)
+        return undefined;
+    const expand = (node, file, bindings, seen) => {
+        if (ts.isUnionTypeNode(node))
+            return node.types
+                .map((member) => expand(member, file, bindings, seen))
+                .join(' | ');
+        if (ts.isParenthesizedTypeNode(node) && ts.isUnionTypeNode(node.type))
+            return expand(node.type, file, bindings, seen);
+        if (ts.isTypeReferenceNode(node) && ts.isIdentifier(node.typeName)) {
+            const name = node.typeName.text;
+            const bound = bindings.get(name);
+            if (bound)
+                return expand(bound.node, bound.file, bound.bindings, seen);
+            const found = resolver.find(name, file);
+            const key = found ? `${found.file.fileName}#${name}` : '';
+            if (found && !seen.has(key)) {
+                if (found.kind === 'interface')
+                    return '{}';
+                const inner = new Map();
+                (found.node.typeParameters ?? []).forEach((parameter, index) => {
+                    const argument = node.typeArguments?.[index];
+                    if (argument)
+                        inner.set(parameter.name.text, { node: argument, file, bindings });
+                    else if (parameter.default)
+                        inner.set(parameter.name.text, {
+                            node: parameter.default,
+                            file: found.file,
+                            bindings: new Map(),
+                        });
+                });
+                return expand(found.node.type, found.file, inner, new Set([...seen, key]));
+            }
+        }
+        return node.getText(file);
+    };
+    const expanded = expand(statement.type, source, new Map(), new Set());
+    return expanded === type ? undefined : expanded;
+}
+/**
+ * Resolves a manual spec into an EnumeratedComponent, reading `propsFrom` when set.
+ *
+ * @param specification - The manual component's specification
+ * @param kitRoot - The kit root `propsFrom` resolves against
+ * @param templates - The kit's template components, which a
+ *   `ComponentProps<typeof X>` in the props type can name
+ * @returns The component, with its props read from `propsFrom` or given inline
+ */
+export function resolveManualComponent(specification, kitRoot, templates = []) {
+    const { propsFrom, ...rest } = specification;
+    if (propsFrom !== undefined && specification.props !== undefined) {
+        throw new Error(`[preview] manual component ${specification.name}: give props or propsFrom, not both`);
+    }
+    if (propsFrom === undefined) {
+        return {
+            ...rest,
+            props: specification.props ?? {},
+            hasDefaultSlot: specification.hasDefaultSlot ?? false,
+            slotNames: specification.slotNames ?? [],
+        };
+    }
+    let read;
+    try {
+        read = readPropsFrom(propsFrom, kitRoot, templates);
+    }
+    catch (error) {
+        throw new Error(`[preview] manual component ${specification.name}: ${error.message}`, { cause: error });
+    }
+    return {
+        ...rest,
+        props: read.props,
+        hasDefaultSlot: specification.hasDefaultSlot ?? read.hasChildren,
+        ...((specification.defaultSlotScoped ?? read.childrenScoped)
+            ? { defaultSlotScoped: true }
+            : {}),
+        slotNames: specification.slotNames ?? [],
+        hiddenProps: read.hiddenProps,
+        memberNames: read.memberNames,
+    };
+}