@design-factory/angular 21.1.0 → 22.0.0-next.0

package/schematics/component-migration/dropdown/guide.md

@@ -0,0 +1,252 @@
+# Dropdown Migration Guide
+
+This guide is used by AI-assisted migration after the deterministic `migrate-dropdown` schematic has run.
+
+Use it together with the user's current working tree and current git diff. The diff shows which safe changes were made
+by the schematic and which `TODO(df-migration ...)` comments still need review.
+
+## Legacy API
+
+Legacy dropdowns are based on `NgbDropdown` / `NgbDropdownModule` from `@ng-bootstrap/ng-bootstrap/dropdown` or
+`@ng-bootstrap/ng-bootstrap`.
+
+Common legacy template pieces:
+
+- `ngbDropdown`
+- `ngbDropdownToggle`
+- `ngbDropdownAnchor`
+- `ngbDropdownMenu`
+- `ngbDropdownItem`
+- `NgbDropdownButtonItem` in standalone imports
+- `placement`
+- `open`
+- `openChange`
+- `autoClose`
+- `container`
+- `display`
+- `dropdownClass`
+- `popperOptions`
+- `#dropdown="ngbDropdown"`
+
+## New API
+
+New dropdowns use standalone imports from `@design-factory/angular/dropdown` and, when separators are present,
+`DfSeparator` from `@design-factory/angular/separator`.
+
+Common template form:
+
+```html
+<button [dfDropdownToggle]="menu" appearance="outline">Actions</button>
+<df-dropdown #menu placement="bottom-start bottom-end top-start top-end">
+  <button dfDropdownItem>Action</button>
+  <a dfDropdownItem href="/details">Details</a>
+  <df-separator />
+</df-dropdown>
+```
+
+## Deterministic Schematic Changes
+
+The schematic handles these changes when syntax is local and unambiguous:
+
+- wrappers with one `ngbDropdownToggle`, one `ngbDropdownMenu`, and no anchor, split, nested-dropdown, or datepicker
+  menu pattern
+- `ngbDropdownToggle` -> `[dfDropdownToggle]="menuRef"`
+- `ngbDropdownMenu` host element -> `<df-dropdown #menuRef>`
+- `ngbDropdownItem` -> `dfDropdownItem` on `button` and `a` hosts
+- static `dropdown-item` class removal on migrated items
+- static `active` item class -> `active`
+- `[class.active]` -> `[active]`
+- simple `<hr class="dropdown-divider">` -> `<df-separator />`
+- `placement` moved from wrapper to `df-dropdown`, with legacy `left` / `right` mapped to `start` / `end`
+- legacy corner placement names such as `bottom-right` -> `bottom-end`
+- static `auto` placements are preserved, for example `bottom-right auto` -> `bottom-end auto`
+- `container` moved from wrapper to `df-dropdown`
+- `[open]` -> `[opened]`
+- `(openChange)` -> `(openedChange)`
+- static dropdown menu size classes -> `size="sm"` / `size="lg"`
+- `#dropdown="ngbDropdown"` template references moved to `<df-dropdown #dropdown>` when the dropdown is otherwise
+  migratable
+- supported legacy toggle button visual classes -> dropdown toggle visual inputs
+- pre-existing `dfButton` attributes removed from migrated dropdown toggles, while existing visual inputs such as
+  `appearance`, `variant`, and `size` are preserved
+- standalone `DfDropdown`, `DfDropdownToggle`, `DfDropdownItemButton`, `DfDropdownItemLink`, and `DfSeparator` imports
+  where needed
+- direct standalone `NgbDropdown*` imports, including `NgbDropdownButtonItem`, removed when no legacy dropdown template
+  remains in the component scope
+- TODO comments for dynamic toggle button class logic
+- TODO comments for cases that need review or AI/manual migration
+
+Do not repeat these changes unless the schematic missed a local occurrence.
+
+The schematic keeps the old wrapper element as a plain layout container. This preserves layout utility classes such as
+`d-inline-block`, spacing, and width classes.
+
+During AI-assisted cleanup, remove that wrapper only when it is empty or trivial and the DOM change is clearly harmless.
+Keep it when it carries layout classes, ids, QA attributes, structural context, component CSS hooks, or anything whose
+placement on the toggle button would not be equivalent.
+
+## TODO Codes
+
+TODO comments may include `[human]`.
+
+Verify every TODO and remove it only when the underlying issue is actually resolved. Preserve `[human]` TODO comments
+unchanged so a human can review them after the AI-assisted pass. `[human]` does not forbid AI-assisted edits around the
+comment when the intent is clear; it means the final result must remain visible for human verification.
+
+### `dropdown.review`
+
+The dropdown was migrated automatically. Verify behavior and visual appearance.
+
+Keep or remove this TODO based on review. If no behavior issue is found, remove it.
+
+### `dropdown.structure`
+
+The dropdown was left in legacy markup because it is not a supported one-toggle/one-menu pattern.
+Adjacent TODOs usually name the unsupported feature, such as anchor, split button, datepicker, or programmatic API. When
+there is no more specific adjacent TODO, inspect for missing toggles, missing menus, multiple toggles or menus, nested
+dropdowns, or empty menu content.
+
+Rebuild the dropdown using `[dfDropdownToggle]` and `<df-dropdown>` only when the behavior is clear. Keep the `[human]`
+TODO after the conversion so the structure can be reviewed.
+
+### `dropdown.dynamic-toggle-class`
+
+Dynamic dropdown toggle classes were detected on a legacy-looking toggle.
+
+This TODO is emitted only when the toggle has explicit dynamic legacy button class bindings, or when a generic `class`
+or `ngClass` expression appears on a toggle that also has exact static `btn` evidence. It is not emitted for unrelated
+class bindings such as spacing, icon, state, or layout classes.
+
+Inspect `[class]`, `[ngClass]`, and class binding expressions. Convert legacy button styling to dropdown toggle inputs
+only when the expression is clear:
+
+- `[class.btn-lg]="large"` -> `[size]="large ? 'lg' : 'md'"`
+- `[class.btn-sm]="small"` -> `[size]="small ? 'sm' : 'md'"`
+- `[class.df-btn-tertiary]="text"` -> `[appearance]="text ? 'text' : defaultAppearance"` where `defaultAppearance`
+  preserves the existing static style, such as `solid` or `outline`
+- `[class.df-btn-transparent]="transparent"` -> `[transparent]="transparent"`
+- `[class.df-btn-primary-mirror]="mirror"` -> `[mirror]="mirror"` and keep/default `variant="primary"`
+
+When multiple dynamic legacy classes can conflict, prefer a small TypeScript helper that returns a typed value for
+`variant`, `appearance`, or `size`.
+
+### `dropdown.auto-close`
+
+Legacy `autoClose` behavior was not migrated.
+
+The new dropdown has fixed outside-click dismissal behavior. Verify whether the old `inside`, `outside`, `false`, or
+dynamic value still matters. Keep the `[human]` TODO for review after any related cleanup.
+
+### `dropdown.anchor`
+
+`ngbDropdownAnchor` is not supported by the new dropdown API.
+
+Rebuild the anchor/toggle relationship only when the behavior is clear, using a supported toggle or another overlay
+component. The new API expects a button with `[dfDropdownToggle]="menu"`. Keep the `[human]` TODO after any conversion.
+
+### `dropdown.split`
+
+Split dropdown button structure was not migrated.
+
+Rebuild the split button using the current dropdown/button API only when behavior is clear. Verify keyboard and
+accessible-name behavior, and keep the `[human]` TODO after any conversion.
+
+### `dropdown.datepicker`
+
+The dropdown menu contains an ng-bootstrap datepicker, which is not supported by the new dropdown API.
+
+Rebuild it with a datepicker component or another dedicated overlay. Legacy datepicker dropdowns often use custom
+anchoring, refs, open/close calls, and focus handling that should not be migrated as a regular menu. Keep the `[human]`
+TODO after any conversion.
+
+### `dropdown.rich-menu`
+
+The dropdown menu contains non-item content such as forms, filters, or arbitrary layout.
+
+This pattern is not supported by the new dropdown API and will not be supported in future versions. Rebuild the content
+with supported dropdown items, or use another overlay component such as a popover or dialog. Keep the `[human]` TODO for
+review after any conversion.
+
+### `dropdown.custom-positioning`
+
+Legacy positioning configuration was not fully migrated.
+
+Review `display`, `popperOptions`, `dropdownClass`, and dynamic `placement` values. Keep intentional `auto`
+placements. `container` is migrated to `df-dropdown`. Convert old `left` / `right` values to `start` / `end` when
+they still exist in expressions. Keep the `[human]` TODO for review after any related cleanup.
+
+### `dropdown.custom-menu-classes`
+
+The legacy menu had custom classes.
+
+The new menu content is rendered in an overlay window, so classes left on `<df-dropdown>` may not style the rendered
+overlay. Replace the styling with supported inputs or updated CSS only when the styling intent is clear. Keep the
+`[human]` TODO for review after any related cleanup.
+
+### `dropdown.unsupported-item-host`
+
+`ngbDropdownItem` was used on a host other than `button` or `a`.
+
+Convert the item to a supported host only when semantics are clear, or rebuild the content if it is not a menu item.
+Keep the `[human]` TODO after any conversion.
+
+### `dropdown.icon-only-accessible-name`
+
+An icon-only dropdown toggle needs an accessible name.
+
+Add `aria-label`, `aria-labelledby`, or the project-standard equivalent after verifying the visible context. Keep the
+`[human]` TODO after any conversion.
+
+### `dropdown.btn-link-toggle`
+
+The legacy toggle used `btn-link`.
+
+There is no deterministic dropdown visual equivalent. Verify and choose the intended button appearance only when the
+intent is clear. Keep the `[human]` TODO after any conversion.
+
+### `dropdown.programmatic-api`
+
+Programmatic `NgbDropdown` API usage was not migrated.
+
+The schematic preserves simple template-reference names by moving `#dropdown="ngbDropdown"` to `<df-dropdown
+#dropdown>` when the dropdown is otherwise migratable. Calls to `open()`, `close()`, `toggle()`, and `isOpen()` are
+available on the new component, but TypeScript queries and imports are not equivalent.
+
+Replace `ViewChild(NgbDropdown)`, `ViewChildren(NgbDropdown)`, typed `NgbDropdown` parameters, and any private legacy
+usage such as `_nativeElement` with the new API manually. Keep the `[human]` TODO after any conversion.
+
+### `dropdown.legacy-import`
+
+A legacy dropdown import remains after deterministic migration.
+
+Legacy modules such as `NgbDropdownModule` are intentionally kept for second-pass verification. Remove legacy imports
+only after no legacy dropdown APIs remain.
+
+### `dropdown.indirect-component-imports`
+
+The component needs new DF dropdown imports, but its Angular `imports` metadata is not a simple array literal.
+
+Inspect the referenced value or expression. Add the required standalone imports to the actual imports list only when the
+shape is clear.
+
+## Configuration Migration
+
+Legacy `NgbDropdownConfig` is not supported anymore and is marked with `TODO(df-migration dropdown.config)` for human
+review.
+
+Do not migrate it automatically. `DfDropdown` currently has no `provideDfDropdownConfig()` equivalent, so review legacy
+defaults manually and decide whether they should become local dropdown inputs or application-specific cleanup.
+
+## Validation
+
+After AI-assisted dropdown migration:
+
+1. Confirm no unexpected `ngbDropdown`, `ngbDropdownToggle`, `ngbDropdownMenu`, `ngbDropdownItem`, `NgbDropdown`,
+   `NgbDropdownButtonItem`, or `NgbDropdownModule` usages remain in app code.
+2. Confirm every migrated toggle points to the intended `df-dropdown` reference.
+3. Confirm dynamic `placement` values use supported new placements and preserve intentional `auto` values.
+4. Verify dynamic toggle button class logic.
+5. Verify icon-only and split-button accessible names.
+6. Run the narrowest useful typecheck/build command for touched projects when the command is clear.
+7. Run visual or e2e checks for menus with custom classes, rich content, custom positioning, or programmatic control.
+8. Ask the user before running broad or expensive validation commands if the right command is unclear.

package/schematics/component-migration/dropdown/index.d.ts

@@ -0,0 +1,2 @@
+declare const _default: (options: import("../shared/types").ComponentMigrationSchema) => import("@angular-devkit/schematics").Rule;
+export default _default;

package/schematics/component-migration/dropdown/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const create_component_schematic_1 = require("../shared/create-component-schematic");
+const migration_1 = require("./migration");
+exports.default = (0, create_component_schematic_1.createComponentMigrationSchematic)(migration_1.dropdownMigration);

package/schematics/component-migration/dropdown/migration.d.ts

@@ -0,0 +1,2 @@
+import { ComponentMigrationDefinition } from '../shared/types';
+export declare const dropdownMigration: ComponentMigrationDefinition;

package/schematics/component-migration/dropdown/migration.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dropdownMigration = void 0;
+const template_result_1 = require("../shared/template-result");
+const template_edits_1 = require("../shared/template-edits");
+const template_attributes_1 = require("./steps/template-attributes");
+const dropdown_imports_1 = require("./steps/dropdown-imports");
+const legacy_config_todos_1 = require("../shared/legacy-config-todos");
+function getDropdownElements(template) {
+    return (0, template_edits_1.findTemplateElements)(template, template_attributes_1.countDropdownWrapperUsage);
+}
+function getTemplateReferenceNames(template) {
+    const names = new Set();
+    const templateRefPattern = /#([A-Za-z_$][\w$-]*)/g;
+    let match = templateRefPattern.exec(template);
+    while (match) {
+        names.add(match[1]);
+        match = templateRefPattern.exec(template);
+    }
+    return names;
+}
+function migrateDropdownTemplate(template) {
+    const edits = [];
+    const standaloneImports = [];
+    const usedReferenceNames = getTemplateReferenceNames(template);
+    for (const element of getDropdownElements(template)) {
+        const result = (0, template_attributes_1.editDropdownWrapper)(element, { usedReferenceNames }, edits);
+        standaloneImports.push(...result.standaloneImports);
+    }
+    return (0, template_result_1.createTemplateMigrationResult)(template, edits, standaloneImports);
+}
+function migrateDropdownSourceFile(context) {
+    return (0, dropdown_imports_1.editDropdownImports)(context);
+}
+exports.dropdownMigration = {
+    id: 'dropdown',
+    countLegacyTemplateUsages: (template) => getDropdownElements(template).length,
+    migrateTemplate: migrateDropdownTemplate,
+    migrateSourceFile: migrateDropdownSourceFile,
+    migrateProjectSourceFile: (context) => (0, legacy_config_todos_1.editLegacyConfigTodos)(context, ['NgbDropdownConfig'])
+};

package/schematics/component-migration/dropdown/schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "SchematicsMigrateDropdown",
+  "title": "Migrate Dropdown Schema",
+  "type": "object",
+  "properties": {
+    "project": {
+      "type": "string",
+      "description": "Name of the Angular project to scan or migrate",
+      "$default": {
+        "$source": "projectName"
+      }
+    },
+    "all": {
+      "type": "boolean",
+      "description": "Scan or migrate every buildable Angular project",
+      "default": false
+    },
+    "scan": {
+      "type": "boolean",
+      "description": "Only scan dropdown usages without applying the migration",
+      "default": false
+    }
+  }
+}

package/schematics/component-migration/dropdown/steps/dropdown-imports.d.ts

@@ -0,0 +1,3 @@
+import { TemplateEdit } from '../../shared/template-edits';
+import { ComponentMigrationSourceContext } from '../../shared/types';
+export declare function editDropdownImports(context: ComponentMigrationSourceContext): TemplateEdit[];

package/schematics/component-migration/dropdown/steps/dropdown-imports.js

@@ -0,0 +1,308 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.editDropdownImports = editDropdownImports;
+const tslib_1 = require("tslib");
+const ts = tslib_1.__importStar(require("typescript"));
+const angular_component_1 = require("../../shared/angular-component");
+const component_imports_1 = require("../../shared/component-imports");
+const component_context_1 = require("../../shared/component-context");
+const import_edits_1 = require("../../shared/import-edits");
+const todo_comments_1 = require("../../shared/todo-comments");
+const template_imports_1 = require("./template-imports");
+const LEGACY_DROPDOWN_IMPORTS = new Set(['@ng-bootstrap/ng-bootstrap/dropdown', '@ng-bootstrap/ng-bootstrap']);
+const NGB_DROPDOWN = 'NgbDropdown';
+const DF_DROPDOWN = 'DfDropdown';
+const LEGACY_DIRECTIVE_SCOPE_SYMBOLS = new Set([
+    NGB_DROPDOWN,
+    'NgbDropdownAnchor',
+    'NgbDropdownButtonItem',
+    'NgbDropdownItem',
+    'NgbDropdownMenu',
+    'NgbDropdownToggle'
+]);
+const LEGACY_MODULE_SCOPE_SYMBOLS = new Set(['NgbDropdownModule']);
+const LEGACY_IMPORT_SYMBOLS = new Set([
+    ...LEGACY_DIRECTIVE_SCOPE_SYMBOLS,
+    ...LEGACY_MODULE_SCOPE_SYMBOLS,
+    'NgbDropdownConfig'
+]);
+function componentUsesLegacyDropdown(templates) {
+    return templates.some((template) => /(^|[\s<])(?:\[)?ngbDropdown(?:\]|=|\s|>)/.test(template.replace(/<!--[\s\S]*?-->/g, '')));
+}
+function componentUsesDfDropdown(templates) {
+    return templates.some((template) => template.includes('<df-dropdown') || template.includes('</df-dropdown>'));
+}
+function getLegacyDropdownImports(sourceFile) {
+    return (0, component_imports_1.getComponentNamedImports)(sourceFile, LEGACY_DROPDOWN_IMPORTS, LEGACY_IMPORT_SYMBOLS);
+}
+function getLegacyLocalNames(legacyImports, importedNames) {
+    return new Set(legacyImports
+        .filter((legacyImport) => importedNames.has(legacyImport.importedName))
+        .map((legacyImport) => legacyImport.localName));
+}
+function editUnusedLegacyImportDeclarations(context, legacyImports, migratedLocalNames) {
+    const sourceNeedsLegacyDropdown = (0, component_context_1.sourceFileNeedsComponentTemplate)(context, componentUsesLegacyDropdown);
+    const removableImports = legacyImports
+        .filter((legacyImport) => {
+        if (LEGACY_MODULE_SCOPE_SYMBOLS.has(legacyImport.importedName)) {
+            return false;
+        }
+        if (sourceNeedsLegacyDropdown && LEGACY_DIRECTIVE_SCOPE_SYMBOLS.has(legacyImport.importedName)) {
+            return false;
+        }
+        return LEGACY_DIRECTIVE_SCOPE_SYMBOLS.has(legacyImport.importedName);
+    })
+        .filter((legacyImport) => migratedLocalNames.has(legacyImport.localName) ||
+        !(0, component_imports_1.hasIdentifierReferenceOutsideImports)(context.sourceFile, legacyImport.localName))
+        .map((legacyImport) => legacyImport.importedName);
+    return (0, import_edits_1.removeNamedImports)(context.sourceFile, LEGACY_DROPDOWN_IMPORTS, removableImports);
+}
+function getSortedSymbolNames(requirements) {
+    return [...new Set(requirements.map((requirement) => requirement.symbolName))].sort();
+}
+function getRequirementsByModule(requirements) {
+    const requirementsByModule = new Map();
+    for (const requirement of requirements) {
+        const moduleRequirements = requirementsByModule.get(requirement.moduleName) ?? [];
+        moduleRequirements.push(requirement);
+        requirementsByModule.set(requirement.moduleName, moduleRequirements);
+    }
+    return new Map([...requirementsByModule.entries()].map(([moduleName, moduleRequirements]) => [
+        moduleName,
+        getSortedSymbolNames(moduleRequirements)
+    ]));
+}
+function findComponentImportsProperty(sourceFile, component) {
+    const metadata = (0, angular_component_1.findComponentMetadata)(component);
+    if (!metadata) {
+        return null;
+    }
+    for (const property of metadata.properties) {
+        if (ts.isPropertyAssignment(property) && property.name.getText(sourceFile) === 'imports') {
+            return property;
+        }
+    }
+    return null;
+}
+function editNewComponentImportsProperty(component, symbolNames) {
+    const metadata = (0, angular_component_1.findComponentMetadata)(component);
+    const lastProperty = metadata?.properties[metadata.properties.length - 1];
+    if (!lastProperty) {
+        return [];
+    }
+    return [
+        { start: lastProperty.getEnd(), end: lastProperty.getEnd(), text: `,\n  imports: [${symbolNames.join(', ')}]` }
+    ];
+}
+function editNewNgModuleImportsProperty(moduleClass, symbolNames) {
+    const metadata = (0, angular_component_1.findNgModuleMetadata)(moduleClass);
+    const lastProperty = metadata?.properties[metadata.properties.length - 1];
+    if (!lastProperty) {
+        return [];
+    }
+    return [
+        { start: lastProperty.getEnd(), end: lastProperty.getEnd(), text: `,\n  imports: [${symbolNames.join(', ')}]` }
+    ];
+}
+function isDeclaredInSourceNgModule(context, component) {
+    return (0, angular_component_1.getNgModuleClasses)(context.sourceFile).some((moduleClass) => {
+        const declarations = (0, angular_component_1.findNgModuleDeclarationsArray)(moduleClass);
+        return declarations?.elements.some((element) => (0, angular_component_1.resolveClassDeclaration)(context.typeChecker, element) === component);
+    });
+}
+function editImportsArrayContents(context, importsArray, requirements, removableLocalNames) {
+    const requiredSymbols = getSortedSymbolNames(requirements);
+    const remaining = importsArray.elements
+        .map((element) => element.getText(context.sourceFile))
+        .filter((elementText) => !removableLocalNames.has(elementText));
+    const existing = new Set(remaining);
+    const missing = requiredSymbols.filter((symbolName) => !existing.has(symbolName));
+    if (remaining.length === importsArray.elements.length && missing.length === 0) {
+        return [];
+    }
+    const elements = [...remaining, ...missing];
+    return [
+        {
+            start: importsArray.getStart(context.sourceFile) + 1,
+            end: importsArray.getEnd() - 1,
+            text: elements.join(', ')
+        }
+    ];
+}
+function addTopLevelImports(sourceFile, fileRequirements) {
+    const edits = [];
+    for (const [moduleName, symbolNames] of getRequirementsByModule(fileRequirements)) {
+        edits.push(...(0, import_edits_1.addNamedImports)(sourceFile, moduleName, symbolNames));
+    }
+    return edits;
+}
+function editDropdownStandaloneImports(context, legacyImports, additionalTopLevelImportNames = []) {
+    const edits = [];
+    const fileRequirements = [];
+    const removableLocalNames = getLegacyLocalNames(legacyImports, LEGACY_DIRECTIVE_SCOPE_SYMBOLS);
+    for (const [component, requirements] of context.standaloneImportsByComponent) {
+        if ((0, angular_component_1.isExplicitlyNonStandaloneComponent)(component)) {
+            continue;
+        }
+        const keepsLegacyDropdown = componentUsesLegacyDropdown(context.templatesByComponent.get(component) ?? []);
+        const importsArray = (0, angular_component_1.findComponentImportsArray)(component);
+        if (importsArray) {
+            edits.push(...editImportsArrayContents(context, importsArray, requirements, keepsLegacyDropdown ? new Set() : removableLocalNames));
+            if (requirements.length > 0) {
+                fileRequirements.push(...requirements);
+            }
+            continue;
+        }
+        if (requirements.length === 0) {
+            continue;
+        }
+        const importsProperty = findComponentImportsProperty(context.sourceFile, component);
+        if (importsProperty) {
+            if (!ts.isArrayLiteralExpression(importsProperty.initializer)) {
+                const edit = (0, todo_comments_1.editSourceTodo)(context.sourceFile, importsProperty, {
+                    code: 'dropdown.indirect-component-imports',
+                    message: 'Component imports use an indirect value. Add the required DF dropdown imports after verifying its shape.'
+                });
+                if (edit) {
+                    edits.push(edit);
+                }
+            }
+            continue;
+        }
+        if (isDeclaredInSourceNgModule(context, component)) {
+            continue;
+        }
+        edits.push(...editNewComponentImportsProperty(component, getSortedSymbolNames(requirements)));
+        fileRequirements.push(...requirements);
+    }
+    for (const moduleClass of (0, angular_component_1.getNgModuleClasses)(context.sourceFile)) {
+        const declarationsArray = (0, angular_component_1.findNgModuleDeclarationsArray)(moduleClass);
+        if (!declarationsArray) {
+            continue;
+        }
+        const requirements = declarationsArray.elements.flatMap((element) => {
+            const component = (0, angular_component_1.resolveClassDeclaration)(context.typeChecker, element);
+            return component ? (context.projectStandaloneImportsByComponent.get(component) ?? []) : [];
+        });
+        if (requirements.length === 0) {
+            continue;
+        }
+        const symbolNames = getSortedSymbolNames(requirements);
+        const importsArray = (0, angular_component_1.findNgModuleImportsArray)(moduleClass);
+        if (importsArray) {
+            const keepsLegacyDropdown = (0, component_context_1.moduleDeclaresComponentTemplate)(context, moduleClass, componentUsesLegacyDropdown);
+            edits.push(...editImportsArrayContents(context, importsArray, requirements, keepsLegacyDropdown ? new Set() : removableLocalNames));
+        }
+        else {
+            edits.push(...editNewNgModuleImportsProperty(moduleClass, symbolNames));
+        }
+        fileRequirements.push(...requirements);
+    }
+    for (const symbolName of additionalTopLevelImportNames) {
+        fileRequirements.push({ moduleName: template_imports_1.DROPDOWN_IMPORTS.dropdown.moduleName, symbolName });
+    }
+    edits.push(...addTopLevelImports(context.sourceFile, fileRequirements));
+    return edits;
+}
+function editProgrammaticApiTodos(context, legacyImports, migratedLocalNames) {
+    const edits = [];
+    if (migratedLocalNames.size > 0) {
+        const edit = (0, todo_comments_1.editSourceTodo)(context.sourceFile, context.sourceFile, {
+            code: 'dropdown.programmatic-api',
+            marker: 'human',
+            message: 'Dropdown TypeScript references were migrated to DfDropdown. Verify open, close, toggle, isOpen, ViewChild, and ViewChildren behavior manually.'
+        });
+        if (edit) {
+            edits.push(edit);
+        }
+    }
+    for (const legacyImport of legacyImports) {
+        if (legacyImport.importedName !== NGB_DROPDOWN ||
+            migratedLocalNames.has(legacyImport.localName) ||
+            !(0, component_imports_1.hasIdentifierReferenceOutsideImports)(context.sourceFile, legacyImport.localName)) {
+            continue;
+        }
+        const edit = (0, todo_comments_1.editSourceTodo)(context.sourceFile, context.sourceFile, {
+            code: 'dropdown.programmatic-api',
+            marker: 'human',
+            message: 'NgbDropdown is still referenced in TypeScript. Replace ViewChild, ViewChildren, open, close, toggle, and isOpen usage with the new API manually.'
+        });
+        if (edit) {
+            edits.push(edit);
+        }
+        break;
+    }
+    return edits;
+}
+function getNewDropdownImportName(legacyImport) {
+    return legacyImport.importedName === NGB_DROPDOWN && legacyImport.localName !== NGB_DROPDOWN
+        ? `${DF_DROPDOWN} as ${legacyImport.localName}`
+        : DF_DROPDOWN;
+}
+function getDropdownScopeName(legacyImport) {
+    return legacyImport.importedName === NGB_DROPDOWN && legacyImport.localName !== NGB_DROPDOWN
+        ? legacyImport.localName
+        : DF_DROPDOWN;
+}
+function getSkippedRanges(sourceFile) {
+    const importDeclarationRanges = sourceFile.statements.flatMap((statement) => ts.isImportDeclaration(statement) ? [{ start: statement.getFullStart(), end: statement.getEnd() }] : []);
+    const decoratorImportsArrayRanges = (0, angular_component_1.findDecoratorImportsArrays)(sourceFile).map((importsArray) => ({
+        start: importsArray.getStart(sourceFile),
+        end: importsArray.getEnd()
+    }));
+    return [...importDeclarationRanges, ...decoratorImportsArrayRanges];
+}
+function editNgbDropdownReferences(sourceFile, legacyImports, newImports, migratedLocalNames) {
+    const edits = [];
+    const skippedRanges = getSkippedRanges(sourceFile);
+    const dropdownImports = legacyImports.filter((legacyImport) => legacyImport.importedName === NGB_DROPDOWN);
+    const scanner = ts.createScanner(ts.ScriptTarget.Latest, false, ts.LanguageVariant.Standard, sourceFile.text);
+    let token = scanner.scan();
+    while (token !== ts.SyntaxKind.EndOfFileToken) {
+        const start = scanner.getTokenStart();
+        const end = scanner.getTokenEnd();
+        const legacyImport = dropdownImports.find((candidate) => candidate.localName === scanner.getTokenText());
+        if (token === ts.SyntaxKind.Identifier &&
+            legacyImport &&
+            !skippedRanges.some((range) => start >= range.start && end <= range.end)) {
+            const replacement = getDropdownScopeName(legacyImport);
+            newImports.add(getNewDropdownImportName(legacyImport));
+            migratedLocalNames.add(legacyImport.localName);
+            if (scanner.getTokenText() !== replacement) {
+                edits.push({ start, end, text: replacement });
+            }
+        }
+        token = scanner.scan();
+    }
+    return edits;
+}
+function editRemainingLegacyImportTodos(context, legacyImports) {
+    if (legacyImports.length === 0) {
+        return [];
+    }
+    const sourceNeedsLegacyDropdown = (0, component_context_1.sourceFileNeedsComponentTemplate)(context, componentUsesLegacyDropdown);
+    return (0, component_imports_1.editLegacyImportTodos)(context.sourceFile, LEGACY_DROPDOWN_IMPORTS, (legacyImport) => LEGACY_MODULE_SCOPE_SYMBOLS.has(legacyImport.importedName) ||
+        (sourceNeedsLegacyDropdown && LEGACY_DIRECTIVE_SCOPE_SYMBOLS.has(legacyImport.importedName)), {
+        code: 'dropdown.legacy-import',
+        message: 'Legacy dropdown import remains for second-pass verification. Remove it after confirming no legacy dropdown APIs need it.'
+    });
+}
+function editDropdownImports(context) {
+    const edits = [];
+    const newImports = new Set();
+    const migratedLocalNames = new Set();
+    const legacyImports = getLegacyDropdownImports(context.sourceFile);
+    const sourceNeedsDfDropdown = (0, component_context_1.sourceFileNeedsComponentTemplate)(context, componentUsesDfDropdown);
+    const sourceNeedsLegacyDropdown = (0, component_context_1.sourceFileNeedsComponentTemplate)(context, componentUsesLegacyDropdown);
+    if (sourceNeedsDfDropdown && !sourceNeedsLegacyDropdown) {
+        edits.push(...editNgbDropdownReferences(context.sourceFile, legacyImports, newImports, migratedLocalNames));
+    }
+    edits.push(...editDropdownStandaloneImports(context, legacyImports, newImports));
+    if (legacyImports.length === 0) {
+        return edits;
+    }
+    edits.push(...editProgrammaticApiTodos(context, legacyImports, migratedLocalNames));
+    edits.push(...editUnusedLegacyImportDeclarations(context, legacyImports, migratedLocalNames));
+    edits.push(...editRemainingLegacyImportTodos(context, legacyImports));
+    return edits;
+}

package/schematics/component-migration/dropdown/steps/template-attributes.d.ts

@@ -0,0 +1,10 @@
+import { TmplAstElement } from '@angular/compiler';
+import { TemplateEdit } from '../../shared/template-edits';
+import { StandaloneImportRequirement } from '../../shared/types';
+import { DropdownTemplateContext } from './template-wrapper';
+export interface DropdownTemplateEditResult {
+    migrated: boolean;
+    standaloneImports: StandaloneImportRequirement[];
+}
+export declare function editDropdownWrapper(wrapper: TmplAstElement, context: DropdownTemplateContext, edits: TemplateEdit[]): DropdownTemplateEditResult;
+export declare function countDropdownWrapperUsage(element: TmplAstElement): boolean;