@ng-prism/core 22.6.0 → 22.7.0-beta.0

package/dist/builder/scanner/component.scanner.js

@@ -1,11 +1,16 @@
 import ts from 'typescript';
 import { CANVAS_BGS } from '../../shared/canvas-bg.type.js';
 import { CANVAS_LAYOUTS } from '../../shared/canvas-layout.type.js';
-import { evaluateExpression, evaluateStatic, findDecorator, getDecoratorArgument, UNEVALUABLE } from './ast-utils.js';
+import { isImportableName } from '../manifest/manifest-imports.js';
+import { classifyShowcaseClass } from './api/angular-decorators.js';
+import { extractComponentApi } from './api/component-api.extractor.js';
+import { findSetupProperty } from './api/setup.reader.js';
+import { evaluateStatic, findDecorator, getDecoratorArgument, readDecoratorField, UNEVALUABLE } from './ast-utils.js';
 import { getClassHierarchy } from './class-hierarchy.js';
+import { readComposition } from './composition/read-composition.js';
 import { extractInputs, extractOutputs } from './input.extractor.js';
 import { describeValue, readPseudoStates } from './pseudo-states.js';
-import { describeDeprecatedProviders, describeUnevaluable, describeUnreadableBase } from './showcase-diagnostics.js';
+import { describeDeprecatedProviders, describeLegacyPipeComponent, describeLegacyServiceComponent, describeSetupOnComponent, describeSetupOnLegacyComponent, describeShowcaseIssue, describeUnevaluable, describeUnreadableApi, describeUnreadableBase } from './showcase-diagnostics.js';
 import { readShowcaseStates } from './showcase-states.js';
 const COMPONENT_STATUSES = ['stable', 'beta', 'wip', 'deprecated'];
 function isComponentStatus(value) {
@@ -39,47 +44,96 @@ function isCanvasBg(value) {
 function isCanvasLayout(value) {
     return typeof value === 'string' && CANVAS_LAYOUTS.includes(value);
 }
+function isShowcaseImport(value) {
+    const { name, from } = typeof value === 'object' && value !== null ? value : {};
+    return typeof name === 'string' && name !== '' && typeof from === 'string' && from !== '';
+}
+/**
+ * What is wrong with an import the generated manifest would write as `import { name } from 'from'`, `undefined` when
+ * nothing is: anything but an identifier there, `default` or a module path, is a syntax error in the whole manifest.
+ */
+function importProblem(entry) {
+    return isImportableName(entry.name) ? undefined : `expected the name a class is exported under, got ${JSON.stringify(entry.name)}; it was dropped`;
+}
+function isHostTemplate(value) {
+    return typeof value === 'object' && value !== null && typeof value['template'] === 'string';
+}
+/** The position an element has in the source, given the positions before it that the evaluator dropped: the evaluated list is shorter by those. */
+function sourceIndex(index, dropped) {
+    return [...dropped].sort((a, b) => a - b).reduce((position, gap) => (gap <= position ? position + 1 : position), index);
+}
+/**
+ * The two ways a scan warns, each printing a message once however often it is
+ * raised: `report` for a dropped value, which is also collected in
+ * `diagnostics` and fails the build under `strictShowcase`, and `notify` for
+ * anything else worth saying.
+ */
+export function createReporters(diagnostics, notices) {
+    return {
+        report: (message) => {
+            if (diagnostics.includes(message))
+                return;
+            diagnostics.push(message);
+            console.warn(`⚠ ng-prism: ${message}`);
+        },
+        notify: (message) => {
+            if (notices.has(message))
+                return;
+            notices.add(message);
+            console.warn(`⚠ ng-prism: ${message}`);
+        }
+    };
+}
 /**
- * Scan exported symbols for Angular components annotated with @Showcase.
+ * Read the Angular components among the showcased classes of an entry point.
+ * A class with `@Injectable` or `@Service` is a service and one with `@Pipe` a
+ * pipe, each left to its own scan, unless it declares fields only a component
+ * can use.
  *
  * Every @Showcase value the scan has to drop is printed and collected in
- * `diagnostics`, once: sharing the array across entry points keeps a
- * component exported from several of them from repeating its warnings.
- * `notices` does the same for warnings about what a component inherits,
- * which are not diagnostics.
+ * `diagnostics`, once. `notices` does the same for warnings about what a
+ * component inherits, which are not diagnostics.
  */
-export function scanComponents(exports, checker, diagnostics = [], notices = new Set()) {
+export function scanComponents(showcased, checker, options = {}) {
+    const { diagnostics = [], notices = new Set(), exportIndex = new Map(), api: readApi = true, composition: compositionContext } = options;
     const components = [];
-    const report = (message) => {
-        if (diagnostics.includes(message))
-            return;
-        diagnostics.push(message);
-        console.warn(`⚠ ng-prism: ${message}`);
-    };
-    const notify = (message) => {
-        if (notices.has(message))
-            return;
-        notices.add(message);
-        console.warn(`⚠ ng-prism: ${message}`);
-    };
-    for (const sym of exports) {
-        const resolved = sym.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(sym) : sym;
-        const classDecl = resolved.declarations?.find(ts.isClassDeclaration);
-        if (!classDecl)
-            continue;
-        // Perf: cheap pre-filter that skips the full decorator walk for files that don't
-        // mention Showcase at all. False positives (string-literal containing "@Showcase")
-        // just lose the optimization for that file; correctness is unaffected.
-        if (!classDecl.getSourceFile().text.includes('@Showcase'))
-            continue;
-        const showcaseDecorator = findDecorator(classDecl, 'Showcase');
-        if (!showcaseDecorator)
+    const { report, notify } = createReporters(diagnostics, notices);
+    for (const { classDecl, decorator: showcaseDecorator, argument: showcaseArg, kind: classKind } of showcased) {
+        if (classKind.kind === 'service' || classKind.kind === 'pipe')
             continue;
         const className = classDecl.name?.text ?? 'Anonymous';
-        const showcaseConfig = extractShowcaseConfig(showcaseDecorator, className, report, checker);
-        if (!showcaseConfig)
+        const read = readShowcaseConfig(showcaseDecorator, className, report, checker);
+        if (!read || !showcaseArg)
             continue;
+        const { config: showcaseConfig, sources } = read;
+        // Not a diagnostic: the component still works, and strictShowcase must not fail the build over a notice about 23.0.0.
+        if (classKind.kind === 'legacy-component') {
+            notify(classKind.source === 'pipe'
+                ? describeLegacyPipeComponent(className, classKind.fields, classKind.standalone !== false)
+                : describeLegacyServiceComponent(className, classKind.fields));
+        }
+        const setup = findSetupProperty(showcaseArg);
+        if (setup)
+            report(classKind.kind === 'legacy-component' ? describeSetupOnLegacyComponent(className, setup, classKind.fields) : describeSetupOnComponent(className, setup));
         const componentMeta = extractComponentMeta(classDecl, checker);
+        // A string or an object host puts a directive on an element. A component has ignored it so far and keeps doing so, so that what a library renders stays as it is.
+        // Not a diagnostic: nothing is lost, and strictShowcase must not start failing a build over it.
+        if (!componentMeta.isDirective && showcaseConfig.host !== undefined && !isHostTemplate(showcaseConfig.host)) {
+            notify(describeShowcaseIssue(className, showcaseArg, ['host'], 'a string or object host has no effect on a component; use host: { template } to render it inside other markup. It was dropped.'));
+            delete showcaseConfig.host;
+        }
+        const host = showcaseConfig.host;
+        // The manifest imports the class of a directive's object host, as an import of the showcase.
+        if (componentMeta.isDirective && typeof host === 'object' && host !== null && !isHostTemplate(host) && host.import !== undefined) {
+            const hostImport = host.import;
+            const problem = isShowcaseImport(hostImport)
+                ? importProblem(hostImport)
+                : `expected { name, from } with a non-empty string each, got ${describeValue(hostImport)}; it was dropped`;
+            if (problem) {
+                report(describeShowcaseIssue(className, showcaseArg, ['host', 'import'], problem));
+                delete host.import;
+            }
+        }
         const hierarchy = getClassHierarchy(classDecl, checker);
         const inputs = extractInputs(classDecl, checker, hierarchy);
         const outputs = extractOutputs(classDecl, checker, hierarchy);
@@ -94,6 +148,28 @@ export function scanComponents(exports, checker, diagnostics = [], notices = new
         for (const base of hierarchy.unreadable) {
             notify(describeUnreadableBase(className, base));
         }
+        // The API only feeds the API page, which has a fallback for a component without one: a class the extractor
+        // cannot read must not take the scan down. A notice, not a diagnostic, so strictShowcase does not fail over it.
+        let api;
+        try {
+            if (readApi)
+                api = extractComponentApi(classDecl, inputs, outputs, hierarchy, checker, exportIndex);
+        }
+        catch (error) {
+            notify(describeUnreadableApi(className, error, 'component'));
+        }
+        const composition = compositionContext &&
+            readComposition({
+                className,
+                filePath,
+                selector: componentMeta.selector,
+                isDirective: componentMeta.isDirective,
+                standalone: componentMeta.standalone,
+                inputs,
+                config: showcaseConfig,
+                configNode: showcaseArg,
+                sources
+            }, compositionContext, { report, notify });
         components.push({
             className,
             filePath,
@@ -104,11 +180,38 @@ export function scanComponents(exports, checker, diagnostics = [], notices = new
             // Plugins look a base class up by name, so an anonymous one is of no use to them.
             baseClasses: hierarchy.classes
                 .slice(1)
-                .flatMap(({ classDecl: base }) => (base.name ? [{ className: base.name.text, filePath: base.getSourceFile().fileName }] : []))
+                .flatMap(({ classDecl: base }) => (base.name ? [{ className: base.name.text, filePath: base.getSourceFile().fileName }] : [])),
+            api,
+            ...(composition && { composition })
         });
     }
     return components;
 }
+/**
+ * The classes with `@Showcase` among the exports of an entry point, each
+ * classified once: the component, the service and the pipe scan each keep
+ * the classes of their own kind.
+ */
+export function findShowcasedClasses(exports, checker) {
+    return exports.flatMap((sym) => {
+        const showcased = findShowcasedClass(sym, checker);
+        return showcased ? [{ ...showcased, kind: classifyShowcaseClass(showcased.classDecl, showcased.argument, checker) }] : [];
+    });
+}
+/** The class an export resolves to, when it carries `@Showcase`. */
+function findShowcasedClass(sym, checker) {
+    const symbol = sym.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(sym) : sym;
+    const classDecl = symbol.declarations?.find(ts.isClassDeclaration);
+    if (!classDecl)
+        return undefined;
+    // Perf: cheap pre-filter that skips the full decorator walk for files that don't
+    // mention Showcase at all. False positives (string-literal containing "@Showcase")
+    // just lose the optimization for that file; correctness is unaffected.
+    if (!classDecl.getSourceFile().text.includes('@Showcase'))
+        return undefined;
+    const decorator = findDecorator(classDecl, 'Showcase');
+    return decorator && { symbol, classDecl, decorator, argument: getDecoratorArgument(decorator) };
+}
 function hasDecoratorInputs(classDecl) {
     for (const member of classDecl.members) {
         if (!ts.isPropertyDeclaration(member))
@@ -118,7 +221,16 @@ function hasDecoratorInputs(classDecl) {
     }
     return false;
 }
-function extractShowcaseConfig(decorator, className, report, checker) {
+/**
+ * `setup` is read for services and pipes only, so a component's is never
+ * part of the config: the issue the evaluator raises for its function is
+ * swallowed here, and {@link scanComponents} says what is wrong with it instead.
+ */
+export function extractShowcaseConfig(decorator, className, report, checker) {
+    return readShowcaseConfig(decorator, className, report, checker)?.config;
+}
+/** {@link extractShowcaseConfig}, and where the entries it kept are written. */
+function readShowcaseConfig(decorator, className, report, checker) {
     const arg = getDecoratorArgument(decorator);
     if (!arg)
         return undefined;
@@ -126,15 +238,24 @@ function extractShowcaseConfig(decorator, className, report, checker) {
     let providers;
     // A state the evaluator dropped whole leaves no element behind, so its position is noted to keep the later states where the source has them.
     const unevaluableStates = new Set();
+    // The same for the elements of `imports` and `variants`, which are not put back but named by the position the source gives them.
+    const unevaluableElements = { imports: new Set(), variants: new Set() };
     const raw = evaluateStatic(arg, {
         checker,
         report: (issue) => {
+            if (issue.path[0] === 'setup')
+                return;
             if (issue.path[0] === 'providers') {
                 providers ??= issue.node;
                 return;
             }
             if (issue.path[0] === 'states' && issue.path.length === 2 && typeof issue.path[1] === 'number')
                 unevaluableStates.add(issue.path[1]);
+            const [field, index] = issue.path;
+            // A spread that fails inside an element leaves the element behind, and one in the list leaves no telling how many.
+            const isElement = issue.path.length === 2 && !ts.isSpreadAssignment(issue.node) && !ts.isSpreadElement(issue.node);
+            if (isElement && (field === 'imports' || field === 'variants') && typeof index === 'number')
+                unevaluableElements[field].add(index);
             report(describeUnevaluable(className, arg, issue));
         }
     });
@@ -151,6 +272,7 @@ function extractShowcaseConfig(decorator, className, report, checker) {
     const config = {
         title: obj['title']
     };
+    const sources = { variants: [], imports: [] };
     if (obj['description'])
         config.description = obj['description'];
     if (obj['category'])
@@ -170,8 +292,15 @@ function extractShowcaseConfig(decorator, className, report, checker) {
         config.tags = obj['tags'];
     if (obj['meta'])
         config.meta = obj['meta'];
-    if (obj['host'] !== undefined)
-        config.host = obj['host'];
+    if (obj['host'] !== undefined) {
+        // An object with a `template` is meant as a host template, so one that is no string is not a host of another kind.
+        if (typeof obj['host'] === 'object' && obj['host'] !== null && 'template' in obj['host'] && !isHostTemplate(obj['host'])) {
+            report(describeShowcaseIssue(className, arg, ['host'], `expected { template: string }, got ${describeValue(obj['host'])}; it was dropped`));
+        }
+        else {
+            config.host = obj['host'];
+        }
+    }
     if (obj['renderPage'])
         config.renderPage = obj['renderPage'];
     if (obj['states'] !== undefined) {
@@ -209,9 +338,17 @@ function extractShowcaseConfig(decorator, className, report, checker) {
             report(`${className} declares invalid canvasLayout "${String(obj['canvasLayout'])}", ` + `expected one of: ${CANVAS_LAYOUTS.join(', ')}. Skipping.`);
         }
     }
+    if (obj['imports'] !== undefined) {
+        const imports = readShowcaseImports(obj['imports'], className, arg, report, unevaluableElements.imports);
+        if (imports.length > 0) {
+            config.imports = imports.map(({ entry }) => entry);
+            sources.imports = imports.map(({ source }) => source);
+        }
+    }
     if (Array.isArray(obj['variants'])) {
-        config.variants = obj['variants'].map((variant) => {
+        config.variants = obj['variants'].map((variant, index) => {
             const cleaned = { ...variant };
+            const reportVariant = (field, text) => report(describeShowcaseIssue(className, arg, ['variants', sourceIndex(index, unevaluableElements.variants), field], text));
             if (isCanvasBg(variant['bg'])) {
                 warnDeprecatedBg(variant['bg'], `${className} variant "${String(variant['name'])}"`);
             }
@@ -237,10 +374,42 @@ function extractShowcaseConfig(decorator, className, report, checker) {
                 report(`${className} variant "${String(variant['name'])}" declares invalid states ${describeValue(variant['states'])}, expected false. Skipping.`);
                 delete cleaned['states'];
             }
+            if (variant['template'] !== undefined && typeof variant['template'] !== 'string') {
+                reportVariant('template', `expected a string, got ${describeValue(variant['template'])}; it was dropped`);
+                delete cleaned['template'];
+            }
+            if (cleaned['template'] !== undefined && variant['content'] !== undefined) {
+                reportVariant('content', 'set together with template; template wins and content was dropped');
+                delete cleaned['content'];
+            }
+            if (variant['host'] !== undefined && !isHostTemplate(variant['host'])) {
+                reportVariant('host', `expected { template: string }, got ${describeValue(variant['host'])}; it was dropped`);
+                delete cleaned['host'];
+            }
             return cleaned;
         });
+        sources.variants = (config.variants ?? []).map((_, index) => sourceIndex(index, unevaluableElements.variants));
     }
-    return config;
+    return { config, sources };
+}
+/**
+ * `ShowcaseConfig.imports` as the scanner evaluated it, with every entry that is not a `{ name, from }` pair of
+ * non-empty strings reported and dropped. `unevaluable` holds the source positions the evaluator dropped, which keep
+ * the later entries named by the position they have in the source; `source` is that position for each kept entry.
+ */
+function readShowcaseImports(value, className, config, report, unevaluable) {
+    if (!Array.isArray(value)) {
+        report(describeShowcaseIssue(className, config, ['imports'], `expected a list of { name, from }, got ${describeValue(value)}; it was dropped`));
+        return [];
+    }
+    return value.flatMap((entry, index) => {
+        const source = sourceIndex(index, unevaluable);
+        const text = isShowcaseImport(entry) ? importProblem(entry) : `expected { name, from } with a non-empty string each, got ${describeValue(entry)}; it was dropped`;
+        if (!text)
+            return [{ entry: { name: entry.name, from: entry.from }, source }];
+        report(describeShowcaseIssue(className, config, ['imports', source], text));
+        return [];
+    });
 }
 function extractComponentMeta(classDecl, checker) {
     const componentDecorator = findDecorator(classDecl, 'Component');
@@ -256,20 +425,3 @@ function extractComponentMeta(classDecl, checker) {
         isDirective
     };
 }
-/**
- * One field of `@Component`/`@Directive` metadata, read from its own
- * property where the literal has one, so that `imports`, `providers` and the
- * rest are not resolved only to be thrown away. A spread or a shorthand could
- * supply the field from elsewhere, so then the whole argument is evaluated.
- */
-function readDecoratorField(arg, key, checker) {
-    if (ts.isObjectLiteralExpression(arg) && !arg.properties.some(ts.isSpreadAssignment)) {
-        const prop = arg.properties.find((p) => p.name !== undefined && (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) && p.name.text === key);
-        if (!prop)
-            return undefined;
-        if (ts.isPropertyAssignment(prop))
-            return evaluateExpression(prop.initializer, checker);
-    }
-    const raw = evaluateExpression(arg, checker);
-    return typeof raw === 'object' && raw !== null ? raw[key] : undefined;
-}

package/dist/builder/scanner/composition/compose-template.d.ts

@@ -0,0 +1,36 @@
+import { type TmplAstNode } from '@angular/compiler';
+export interface ComposeInput {
+    selector: string;
+    isDirective: boolean;
+    /** Public input name (alias ?? name) → member name. */
+    inputNames: ReadonlyMap<string, string>;
+    hostTemplate?: string;
+    /** Inner markup of the subject: the variant's template, or a directive's text content already escaped. */
+    content?: string;
+}
+export type ComposeResult = {
+    ok: true;
+    template: string;
+    ownedInputs: string[];
+    nodes: TmplAstNode[];
+} | {
+    ok: false;
+    at: 'host' | 'template';
+    problem: string;
+};
+/**
+ * The template of a composition: the subject in its host template, or written from its selector without one, with
+ * `content` as what it holds. {@link COMPOSITION_SUBJECT_SLOT} marks the end of the subject's start tag, right after
+ * its last attribute or its tag name; whoever replaces it brings the leading space.
+ *
+ * In a host template the subject is the element marked with `prism-subject`, else the one element its selector
+ * matches. A directive whose selector does not match the marked element gets the attributes that make it match.
+ * The marker is removed, and `content` replaces what the subject holds in the host template. `ownedInputs` are the
+ * member names of the inputs the host template sets on the subject.
+ *
+ * What fails is reported against the field it comes from: `host` for the host template and finding the subject in
+ * it, `template` for the content and, when there is content, for what Angular's parser rejects in the composed
+ * template. Both are parsed as the generated wrapper holds them, inside a `@case`, where an element left open fails.
+ */
+export declare function composeTemplate(input: ComposeInput): ComposeResult;
+//# sourceMappingURL=compose-template.d.ts.map

package/dist/builder/scanner/composition/compose-template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose-template.d.ts","sourceRoot":"","sources":["../../../../src/builder/scanner/composition/compose-template.ts"],"names":[],"mappings":"AAAA,OAAO,EAKH,KAAK,WAAW,EAInB,MAAM,mBAAmB,CAAC;AAM3B,MAAM,WAAW,YAAY;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;IACrB,uDAAuD;IACvD,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0GAA0G;IAC1G,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,aAAa,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,WAAW,EAAE,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,EAAE,EAAE,MAAM,GAAG,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAUlK;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,aAAa,CAYlE"}

package/dist/builder/scanner/composition/compose-template.js

@@ -0,0 +1,187 @@
+import { CssSelector, parseTemplate, SelectorMatcher, TmplAstElement, TmplAstRecursiveVisitor, TmplAstTemplate, tmplAstVisitAll } from '@angular/compiler';
+import { COMPOSITION_SUBJECT_SLOT, SUBJECT_MARKER_ATTR } from '../../../shared/composition.js';
+import { VOID_ELEMENTS } from '../../../shared/void-elements.js';
+import { selectorElement } from '../../manifest/selector-element.js';
+import { elementSelector, isInputBinding, localName } from './template-elements.js';
+/** The URL the parser files the composition under. A problem carries only Angular's `msg`, so it shows nowhere. */
+const TEMPLATE_URL = 'prism-composition.html';
+/**
+ * The template of a composition: the subject in its host template, or written from its selector without one, with
+ * `content` as what it holds. {@link COMPOSITION_SUBJECT_SLOT} marks the end of the subject's start tag, right after
+ * its last attribute or its tag name; whoever replaces it brings the leading space.
+ *
+ * In a host template the subject is the element marked with `prism-subject`, else the one element its selector
+ * matches. A directive whose selector does not match the marked element gets the attributes that make it match.
+ * The marker is removed, and `content` replaces what the subject holds in the host template. `ownedInputs` are the
+ * member names of the inputs the host template sets on the subject.
+ *
+ * What fails is reported against the field it comes from: `host` for the host template and finding the subject in
+ * it, `template` for the content and, when there is content, for what Angular's parser rejects in the composed
+ * template. Both are parsed as the generated wrapper holds them, inside a `@case`, where an element left open fails.
+ */
+export function composeTemplate(input) {
+    const composed = input.hostTemplate === undefined ? composeWithoutHost(input) : composeInHost(input, input.hostTemplate);
+    if (!composed.ok)
+        return composed;
+    const template = composed.template.replace(COMPOSITION_SUBJECT_SLOT, '');
+    const parsed = parseTemplate(template, TEMPLATE_URL);
+    const problem = parsed.errors?.[0]?.msg ?? problemInCase(template);
+    // Without content the host template alone was parsed, so a remaining error is still its own.
+    if (problem)
+        return fail(input.content === undefined ? 'host' : 'template', problem);
+    return { ...composed, nodes: parsed.nodes };
+}
+/**
+ * What Angular rejects in `template` inside the `@case` of the generated wrapper, beyond what it rejects at the top
+ * level: there it closes an element left open at the end of the template, in a block it fails on the block's `}`.
+ */
+function problemInCase(template) {
+    const error = parseTemplate(`@switch (0) {\n@case (0) {\n${template}\n}\n}`, TEMPLATE_URL).errors?.[0];
+    if (!error)
+        return undefined;
+    // The message is about the `}` ng-prism wrote, and names the element only in passing.
+    const unclosed = /Did you forget to close the (<[^>]+>) element\?/.exec(error.msg);
+    return unclosed ? `${unclosed[1]} is not closed` : `${error.msg}, in the @case that the generated wrapper puts the template in; an unclosed {{ or block can cause it`;
+}
+function composeWithoutHost({ selector, content }) {
+    const element = selectorElement(selector);
+    if (!element)
+        return fail('template', `the selector "${selector}" names no element to render the subject on`);
+    const { tag, attributes } = element;
+    const opening = `<${tag}${attributes ? ` ${attributes}` : ''}${COMPOSITION_SUBJECT_SLOT}`;
+    if (VOID_ELEMENTS.has(tag.toLowerCase())) {
+        return content ? voidContent(tag) : { ok: true, template: `${opening} />`, ownedInputs: [] };
+    }
+    return { ok: true, template: `${opening}>${content ?? ''}</${tag}>`, ownedInputs: [] };
+}
+function composeInHost(input, hostTemplate) {
+    const parsed = parseTemplate(hostTemplate, TEMPLATE_URL, { preserveWhitespaces: true });
+    const problem = parsed.errors?.[0]?.msg ?? problemInCase(hostTemplate);
+    if (problem)
+        return fail('host', problem);
+    const subject = findSubject(parsed.nodes, input.selector);
+    if ('problem' in subject)
+        return subject;
+    const { element, matched } = subject;
+    const tag = writtenTag(element, hostTemplate);
+    let added = '';
+    if (!matched) {
+        if (!input.isDirective)
+            return fail('host', `prism-subject marks <${tag}>, which the selector "${input.selector}" does not match`);
+        const fitting = selectorElement(input.selector, tag);
+        if (!fitting?.attributes)
+            return fail('host', `prism-subject marks <${tag}>, but no part of the selector "${input.selector}" fits a <${tag}>`);
+        added = ` ${fitting.attributes}`;
+    }
+    const isVoid = VOID_ELEMENTS.has(tag.toLowerCase());
+    if (isVoid && input.content)
+        return voidContent(tag);
+    const edits = [];
+    const startTagEnd = element.startSourceSpan.end.offset;
+    const slotAt = slotOffset(hostTemplate, startTagEnd);
+    const slot = { from: slotAt, to: slotAt, text: `${added}${COMPOSITION_SUBJECT_SLOT}` };
+    const marker = element.attributes.find((attribute) => attribute.name === SUBJECT_MARKER_ATTR);
+    if (marker) {
+        edits.push({ from: skipWhitespaceBack(hostTemplate, marker.sourceSpan.start.offset), to: marker.sourceSpan.end.offset, text: '' });
+    }
+    if (!isVoid && input.content !== undefined) {
+        if (!element.isSelfClosing) {
+            const childrenEnd = element.endSourceSpan?.start.offset ?? endOffset(element);
+            edits.push({ from: startTagEnd, to: childrenEnd, text: input.content });
+        }
+        else if (input.content) {
+            slot.to = startTagEnd;
+            slot.text += `>${input.content}</${tag}>`;
+        }
+    }
+    edits.push(slot);
+    return { ok: true, template: applyEdits(hostTemplate, edits), ownedInputs: ownedInputs(element, input) };
+}
+/** The subject of a host template, and whether its selector matches it, which only a marked element may fail. */
+function findSubject(nodes, selector) {
+    const elements = collectElements(nodes);
+    const marked = elements.filter((element) => element.attributes.some((attribute) => attribute.name === SUBJECT_MARKER_ATTR));
+    if (marked.length > 1)
+        return fail('host', `prism-subject marks ${marked.length} elements of the host template; mark one`);
+    const matcher = new SelectorMatcher();
+    matcher.addSelectables(CssSelector.parse(selector));
+    const matches = (element) => matcher.match(elementSelector(element), null);
+    if (marked.length === 1)
+        return { element: marked[0], matched: matches(marked[0]) };
+    const matching = elements.filter(matches);
+    if (matching.length === 0)
+        return fail('host', `the selector "${selector}" matches no element of the host template`);
+    if (matching.length > 1)
+        return fail('host', `the selector "${selector}" matches ${matching.length} elements of the host template; mark one with prism-subject`);
+    return { element: matching[0], matched: true };
+}
+class ElementCollector extends TmplAstRecursiveVisitor {
+    elements = [];
+    visitElement(element) {
+        this.elements.push(element);
+        super.visitElement(element);
+    }
+}
+/** Every element of a template, also those in control flow blocks and in `<ng-template>`, in document order. */
+function collectElements(nodes) {
+    const collector = new ElementCollector();
+    tmplAstVisitAll(collector, nodes);
+    return collector.elements;
+}
+/**
+ * The member names of the inputs that the host template sets on the subject, statically or by a property binding.
+ * An attribute without a value that the selector names is there to match it (`<button libTooltip>`), so ng-prism
+ * still binds the input of that name.
+ */
+function ownedInputs(element, { selector, inputNames }) {
+    const selectorAttributes = new Set(CssSelector.parse(selector).flatMap((part) => part.attrs.filter((_, i) => i % 2 === 0)));
+    const written = new Set();
+    for (const attribute of element.attributes) {
+        if (attribute.value !== '' || !selectorAttributes.has(attribute.name))
+            written.add(attribute.name);
+    }
+    for (const bound of element.inputs) {
+        if (isInputBinding(bound.type))
+            written.add(bound.name);
+    }
+    return [...inputNames].filter(([publicName]) => written.has(publicName)).map(([, member]) => member);
+}
+/** The tag name as the host template writes it, which is what an end tag and a message repeat. */
+function writtenTag(element, source) {
+    const start = element.startSourceSpan.start.offset;
+    return /^<([^\s/>]+)/.exec(source.slice(start, element.startSourceSpan.end.offset))?.[1] ?? localName(element.name);
+}
+/**
+ * Where a node ends in the source. The span of an element or `<ng-template>` whose end tag the parser implies (`<li>`
+ * before the next `<li>`, anything open at the end of the template) covers only its start tag, so it ends with its
+ * last descendant.
+ */
+function endOffset(node) {
+    const end = node.sourceSpan.end.offset;
+    if (!(node instanceof TmplAstElement || node instanceof TmplAstTemplate) || node.endSourceSpan)
+        return end;
+    const last = node.children.at(-1);
+    return last ? Math.max(end, endOffset(last)) : end;
+}
+/** Where the slot goes in a start tag ending at `startTagEnd`: before its `>` or `/>` and the whitespace in front of it. */
+function slotOffset(source, startTagEnd) {
+    let offset = startTagEnd - 1;
+    if (source[offset - 1] === '/')
+        offset--;
+    return skipWhitespaceBack(source, offset);
+}
+function skipWhitespaceBack(source, offset) {
+    while (offset > 0 && /\s/.test(source[offset - 1]))
+        offset--;
+    return offset;
+}
+/** Applies edits that do not overlap, from the last to the first, so that the offsets of the others stay valid. */
+function applyEdits(source, edits) {
+    return [...edits].sort((a, b) => b.from - a.from).reduce((text, edit) => text.slice(0, edit.from) + edit.text + text.slice(edit.to), source);
+}
+function voidContent(tag) {
+    return fail('template', `<${tag}> is a void element and takes no content`);
+}
+function fail(at, problem) {
+    return { ok: false, at, problem };
+}

package/dist/builder/scanner/composition/declarables.d.ts

@@ -0,0 +1,54 @@
+import ts from 'typescript';
+import type { ShowcaseImport } from '../../../decorator/showcase.types.js';
+/** A component, directive or pipe that a template can use, and the module specifier a consumer imports it from. */
+export interface Declarable {
+    /** The name it is exported under. */
+    name: string;
+    from: string;
+    kind: 'component' | 'directive' | 'pipe';
+    /** Of a component or directive, as written in its metadata: a list of selectors is one string. */
+    selector?: string;
+    /** Of a pipe: the name a template calls it by. */
+    pipeName?: string;
+    /** `false` for a class an NgModule declares, which only that module can bring into a template. */
+    standalone: boolean;
+}
+/** What {@link readDeclarable} finds in a class: a {@link Declarable} before it is given a name and a module. */
+export type DeclarableShape = Pick<Declarable, 'kind' | 'selector' | 'pipeName' | 'standalone'>;
+/**
+ * Index every component, directive and pipe the library's entry points export
+ * by its selector or name, with or without `@Showcase`, so that a template can
+ * be matched against them. A class from a dependency that an entry point
+ * re-exports is read from its `.d.ts`. A class without a selector (or a pipe
+ * without a name) cannot be used in a template and is left out, as is
+ * everything that is not a component, directive or pipe.
+ *
+ * A class exported more than once keeps its first entry, as in
+ * `buildExportIndex`: callers put the secondary entry points before the
+ * primary one.
+ */
+export declare function buildDeclarableIndex(entries: ReadonlyArray<{
+    exports: ts.Symbol[];
+    importPath: string;
+}>, checker: ts.TypeChecker): Declarable[];
+/**
+ * Look up each `{ name, from }` of a showcase's `imports` without a program: the module is resolved the way a bundler
+ * does it, with the `paths` and the other options given, and the class is read from the file it lands in, following
+ * `export … from` up to five modules on. An entry that cannot be found, is not exported, or is not a component,
+ * directive or pipe (an NgModule or a service, say) comes back unresolved. A selector that only a checker could
+ * evaluate is not read.
+ */
+export declare function resolveShowcaseImports(imports: readonly ShowcaseImport[], containingFile: string, compilerOptions: ts.CompilerOptions): {
+    resolved: Declarable[];
+    unresolved: ShowcaseImport[];
+};
+/**
+ * What a class declares for templates: from `@Component`, `@Directive` or `@Pipe` in source, from the `ɵcmp`, `ɵdir`
+ * or `ɵpipe` that the compiler left in a `.d.ts`. `undefined` for a class that is neither, or has no selector or name.
+ * The `checker` evaluates a selector given as a constant; without one only a literal is read.
+ *
+ * A class is standalone unless it says otherwise, as in Angular since 19: with `standalone: false` in its decorator,
+ * or `false` as the `IsStandalone` type argument in a `.d.ts`.
+ */
+export declare function readDeclarable(classDecl: ts.ClassDeclaration, checker?: ts.TypeChecker): DeclarableShape | undefined;
+//# sourceMappingURL=declarables.d.ts.map

package/dist/builder/scanner/composition/declarables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"declarables.d.ts","sourceRoot":"","sources":["../../../../src/builder/scanner/composition/declarables.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sCAAsC,CAAC;AAI3E,mHAAmH;AACnH,MAAM,WAAW,UAAU;IACvB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,WAAW,GAAG,WAAW,GAAG,MAAM,CAAC;IACzC,kGAAkG;IAClG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kGAAkG;IAClG,UAAU,EAAE,OAAO,CAAC;CACvB;AAED,iHAAiH;AACjH,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,GAAG,UAAU,GAAG,YAAY,CAAC,CAAC;AAgChG;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,aAAa,CAAC;IAAE,OAAO,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,EAAE,OAAO,EAAE,EAAE,CAAC,WAAW,GAAG,UAAU,EAAE,CAoBhJ;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAClC,OAAO,EAAE,SAAS,cAAc,EAAE,EAClC,cAAc,EAAE,MAAM,EACtB,eAAe,EAAE,EAAE,CAAC,eAAe,GACpC;IAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;IAAC,UAAU,EAAE,cAAc,EAAE,CAAA;CAAE,CAgB1D;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,EAAE,CAAC,gBAAgB,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,WAAW,GAAG,eAAe,GAAG,SAAS,CA4BpH"}