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

package/schematics/component-migration/shared/testing.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupComponentMigrationTest = setupComponentMigrationTest;
+exports.cleanupComponentMigrationTest = cleanupComponentMigrationTest;
+exports.expectTestCaseOutputFile = expectTestCaseOutputFile;
+exports.expectSchematicIdempotent = expectSchematicIdempotent;
+const tslib_1 = require("tslib");
+const core_1 = require("@angular-devkit/core");
+const testing_1 = require("@angular-devkit/core/node/testing");
+const schematics_1 = require("@angular-devkit/schematics");
+const testing_2 = require("@angular-devkit/schematics/testing");
+const fs_1 = require("fs");
+const node_assert_1 = tslib_1.__importDefault(require("node:assert"));
+const path_1 = require("path");
+const commonTestCaseRoot = (0, path_1.join)(__dirname, 'test-cases', 'common');
+function toTreePath(filePath) {
+    return `/${filePath.split(path_1.sep).join('/')}`;
+}
+function writeFixtureDirectory(host, sourceDir, rootDir = sourceDir) {
+    for (const entry of (0, fs_1.readdirSync)(sourceDir)) {
+        const entryPath = (0, path_1.join)(sourceDir, entry);
+        if ((0, fs_1.statSync)(entryPath).isDirectory()) {
+            writeFixtureDirectory(host, entryPath, rootDir);
+            continue;
+        }
+        const treePath = toTreePath((0, path_1.relative)(rootDir, entryPath));
+        host.sync.write((0, core_1.normalize)(treePath), core_1.virtualFs.stringToFileBuffer((0, fs_1.readFileSync)(entryPath, 'utf-8')));
+    }
+}
+function setupComponentMigrationTest(runner, testCaseRoot) {
+    const host = new testing_1.TempScopedNodeJsSyncHost();
+    const tree = new testing_2.UnitTestTree(new schematics_1.HostTree(host));
+    const logs = [];
+    runner.logger.subscribe((entry) => logs.push(entry.message));
+    writeFixtureDirectory(host, commonTestCaseRoot);
+    writeFixtureDirectory(host, (0, path_1.join)(testCaseRoot, 'test-cases', 'input'));
+    const previousWorkingDir = process.cwd();
+    const tmpDirPath = (0, core_1.getSystemPath)(host.root);
+    process.chdir(tmpDirPath);
+    return { host, tree, tmpDirPath, previousWorkingDir, logs };
+}
+function cleanupComponentMigrationTest(context) {
+    process.chdir(context.previousWorkingDir);
+    (0, fs_1.rmSync)(context.tmpDirPath, { recursive: true, force: true });
+}
+function expectTestCaseOutputFile(tree, testCaseRoot, filePath) {
+    const outputDir = (0, path_1.join)(testCaseRoot, 'test-cases', 'output');
+    const treePath = toTreePath(filePath);
+    node_assert_1.default.equal(tree.readContent(treePath), (0, fs_1.readFileSync)((0, path_1.join)(outputDir, filePath), 'utf-8'), treePath);
+}
+function getTreeSnapshot(tree) {
+    return new Map(tree.files.sort().map((filePath) => [filePath, tree.readContent(filePath)]));
+}
+async function expectSchematicIdempotent(runner, schematicName, context) {
+    await runner.runSchematic(schematicName, { project: 'app' }, context.tree);
+    const once = getTreeSnapshot(context.tree);
+    await runner.runSchematic(schematicName, { project: 'app' }, context.tree);
+    node_assert_1.default.deepEqual(getTreeSnapshot(context.tree), once);
+}

package/schematics/component-migration/shared/todo-comments.d.ts

@@ -0,0 +1,10 @@
+import { TmplAstElement } from '@angular/compiler';
+import * as ts from 'typescript';
+import { TemplateEdit } from './template-edits';
+export interface MigrationTodo {
+    code: string;
+    message: string;
+    marker?: 'human';
+}
+export declare function editTemplateTodos(element: TmplAstElement, todos: MigrationTodo[], edits: TemplateEdit[]): void;
+export declare function editSourceTodo(sourceFile: ts.SourceFile, node: ts.Node, todo: MigrationTodo): TemplateEdit | null;

package/schematics/component-migration/shared/todo-comments.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.editTemplateTodos = editTemplateTodos;
+exports.editSourceTodo = editSourceTodo;
+const tslib_1 = require("tslib");
+const ts = tslib_1.__importStar(require("typescript"));
+function getLineStart(content, offset) {
+    return content.lastIndexOf('\n', offset - 1) + 1;
+}
+function getLineIndent(content, lineStart, offset) {
+    const prefix = content.slice(lineStart, offset);
+    return /^\s*$/.test(prefix) ? prefix : '';
+}
+function hasNearbyTodo(content, offset, code) {
+    return getLeadingTodoBlock(content, offset).includes(`TODO(df-migration ${code})`);
+}
+function hasSourceHeaderTodo(sourceFile, code) {
+    const firstNonImportStatement = sourceFile.statements.find((statement) => !ts.isImportDeclaration(statement));
+    const headerEnd = firstNonImportStatement?.getFullStart() ?? sourceFile.text.length;
+    return sourceFile.text.slice(0, headerEnd).includes(`TODO(df-migration ${code})`);
+}
+function isSourceHeaderTodoTarget(sourceFile, node) {
+    return node === sourceFile || ts.isImportDeclaration(node);
+}
+function getLeadingTodoBlock(content, offset) {
+    const lines = content.slice(0, offset).split('\n');
+    const block = [];
+    for (let index = lines.length - 1; index >= 0; index--) {
+        const line = lines[index];
+        if (/^\s*$/.test(line)) {
+            continue;
+        }
+        if (/^\s*(?:<!--\s*)?TODO\(df-migration [^)]+\):/.test(line)) {
+            block.unshift(line);
+            continue;
+        }
+        if (/^\s*\/\/\s*TODO\(df-migration [^)]+\):/.test(line)) {
+            block.unshift(line);
+            continue;
+        }
+        break;
+    }
+    return block.join('\n');
+}
+function editTemplateTodos(element, todos, edits) {
+    const content = element.sourceSpan.start.file.content;
+    const offset = element.sourceSpan.start.offset;
+    const lineStart = getLineStart(content, offset);
+    const indentation = getLineIndent(content, lineStart, offset);
+    const newTodos = todos.filter((todo) => !hasNearbyTodo(content, offset, todo.code));
+    if (newTodos.length === 0) {
+        return;
+    }
+    const isTemplateStart = lineStart === 0 && offset === 0;
+    edits.push({
+        start: lineStart,
+        end: lineStart,
+        text: newTodos
+            .map((todo) => `${isTemplateStart ? '' : indentation}<!-- TODO(df-migration ${todo.code}): ${formatTodoMessage(todo)} -->\n`)
+            .join('') + (isTemplateStart ? '    ' : '')
+    });
+}
+function formatTodoMessage(todo) {
+    return `${todo.marker ? `[${todo.marker}] ` : ''}${todo.message}`;
+}
+function editSourceTodo(sourceFile, node, todo) {
+    const content = sourceFile.text;
+    const offset = node.getStart(sourceFile);
+    const lineStart = getLineStart(content, offset);
+    if (isSourceHeaderTodoTarget(sourceFile, node) && hasSourceHeaderTodo(sourceFile, todo.code)) {
+        return null;
+    }
+    if (hasNearbyTodo(content, offset, todo.code)) {
+        return null;
+    }
+    return {
+        start: lineStart,
+        end: lineStart,
+        text: `${getLineIndent(content, lineStart, offset)}// TODO(df-migration ${todo.code}): ${formatTodoMessage(todo)}\n`
+    };
+}

package/schematics/component-migration/shared/types.d.ts

@@ -0,0 +1,41 @@
+import * as ts from 'typescript';
+import { TemplateEdit } from './template-edits';
+export interface ComponentMigrationTemplateResult {
+    content: string;
+    changes: number;
+    standaloneImports?: StandaloneImportRequirement[];
+}
+export interface ComponentMigrationRunContext {
+    processedSourceFiles: Set<string>;
+    processedTemplateFiles: Set<string>;
+    migratedExternalTemplates: Map<string, ComponentMigrationTemplateResult>;
+    changedFiles: Set<string>;
+}
+export interface StandaloneImportRequirement {
+    moduleName: string;
+    symbolName: string;
+}
+export interface ComponentMigrationSourceContext {
+    sourceFile: ts.SourceFile;
+    typeChecker: ts.TypeChecker;
+    templatesByComponent: Map<ts.ClassDeclaration, string[]>;
+    projectTemplatesByComponent: Map<ts.ClassDeclaration, string[]>;
+    standaloneImportsByComponent: Map<ts.ClassDeclaration, StandaloneImportRequirement[]>;
+    projectStandaloneImportsByComponent: Map<ts.ClassDeclaration, StandaloneImportRequirement[]>;
+}
+export interface ComponentMigrationDefinition {
+    id: string;
+    countLegacyTemplateUsages: (template: string) => number;
+    migrateTemplate?: (template: string) => ComponentMigrationTemplateResult;
+    migrateSourceFile?: (context: ComponentMigrationSourceContext) => TemplateEdit[];
+    migrateProjectSourceFile?: (context: ComponentMigrationSourceContext) => TemplateEdit[];
+}
+export interface ComponentMigrationScanResult {
+    migration: ComponentMigrationDefinition;
+    legacyUsages: number;
+}
+export interface ComponentMigrationSchema {
+    project?: string;
+    all?: boolean;
+    scan?: boolean;
+}

package/schematics/component-migration/shared/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,196 @@
+# Tooltip Migration Guide
+
+This guide is used by AI-assisted migration after the deterministic `migrate-tooltip` 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 tooltips are based on `NgbTooltip` / `NgbTooltipModule` from `@ng-bootstrap/ng-bootstrap/tooltip` or
+`@ng-bootstrap/ng-bootstrap`, often exposed through legacy Design Factory helpers:
+
+- `DfTooltipModule`
+- `DfTooltipTruncateDirective`
+- `dfTooltipTruncate`
+- `NgbTooltipConfig`
+- `ngbTooltip`
+- `placement`
+- `tooltipClass`
+- `disableTooltip`
+- `triggers`
+- `autoClose`
+- `container`
+- `#tooltip="ngbTooltip"`
+
+Legacy tooltip content can be plain text, a dynamic expression, or an `ng-template`.
+
+## New API
+
+New tooltips use the standalone `DfTooltip` directive from `@design-factory/angular/tooltip`:
+
+```ts
+import { DfTooltip, provideDfTooltipConfig } from '@design-factory/angular/tooltip';
+```
+
+Common template forms:
+
+```html
+<button dfTooltip="Short helpful text">Button</button>
+<button [dfTooltip]="tooltipText" dfTooltipPlacement="vertical" dfTooltipSize="sm">Button</button>
+<button dfTooltip="Disabled reason" [dfTooltipDisabled]="enabled">Button</button>
+```
+
+Supported placement values include `top`, `bottom`, `start`, `end`, aligned variants such as `top-start`, and the
+`auto`, `vertical`, and `horizontal` shortcuts. Supported sizes are `sm`, `md`, and `lg`.
+
+## Deterministic Schematic Changes
+
+The schematic handles these changes when syntax is local and unambiguous:
+
+- `ngbTooltip` -> `dfTooltip` for static plain text, interpolated text, and bound content expressions
+- `i18n-ngbTooltip` -> `i18n-dfTooltip` when the tooltip content is migrated
+- `placement` -> `dfTooltipPlacement`
+- static `left` / `right` placements -> `start` / `end`
+- static `auto` placements are preserved, for example `top auto` -> `top auto`
+- `tooltipClass="tooltip-inner-sm"` -> `dfTooltipSize="sm"`
+- `tooltipClass="tooltip-inner-lg"` -> `dfTooltipSize="lg"`
+- unsupported static or dynamic `tooltipClass` removal with a `[human]` TODO
+- `dfTooltipTruncate` removal with a `[human]` TODO because the overflow-only behavior has no new API equivalent
+- `disableTooltip` -> `dfTooltipDisabled`
+- orphan `i18n-ngbTooltip` removal with a `[human]` TODO when no tooltip binding exists on the element
+- custom `triggers` removal for migrated tooltips because the new tooltip has fixed trigger behavior
+- standalone `DfTooltip` imports where needed
+- direct standalone `NgbTooltip` imports replaced or removed when no legacy tooltip remains in that component scope
+- unused `DfTooltipTruncateDirective` import cleanup
+- legacy tooltip module imports such as `NgbTooltipModule` and `DfTooltipModule` are preserved with TODOs for
+  second-pass verification
+- TODO comments for cases that need review or AI/manual migration
+
+Do not repeat these changes unless the schematic missed a local occurrence.
+
+## 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.
+
+### `tooltip.review`
+
+The tooltip was migrated automatically. Verify behavior and visual appearance.
+
+Keep or remove this TODO based on review. If no behavior issue is found, remove it.
+
+### `tooltip.dynamic-content`
+
+Dynamic tooltip content was moved to the new tooltip input without rewriting the expression.
+
+Confirm the expression returns plain text. This includes pipes, function calls, ternaries, `async`, and object-literal
+expressions passed to a pipe. `null` or `undefined` are valid when the tooltip should be hidden. If the expression can
+return a `TemplateRef`, HTML structure, or interactive content, convert it manually to plain text or use a popover.
+
+### `tooltip.template-content`
+
+Template-based tooltip content was not migrated.
+
+New `DfTooltip` supports text content only. Convert simple templates to string content when the rendered text is clear.
+Use popover for rich markup or interactive content. Keep the `[human]` TODO when the conversion needs human
+verification.
+
+### `tooltip.custom-class`
+
+The legacy `tooltipClass` attribute/input is not supported by the new tooltip API.
+
+Known static size classes are migrated automatically when the tooltip itself is migrated. Other static or dynamic
+`tooltipClass` bindings are removed by the deterministic migration. Inspect the old styling intent and replace it with
+supported tooltip inputs or local design changes.
+
+### `tooltip.custom-triggers`
+
+Custom tooltip triggers are not supported by the new tooltip API. The deterministic migration removes trigger attributes
+from migrated tooltips.
+
+The new tooltip opens on hover, keyboard focus, and long press. Verify whether the old custom trigger behavior still
+matters. Click or manual trigger behavior may need a popover or custom interaction. If the old trigger behavior is no
+longer needed after inspecting usage, update the code and keep the `[human]` TODO for review.
+
+### `tooltip.manual-trigger`
+
+Manual tooltip trigger control was not migrated.
+
+Replace programmatic `open()`, `close()`, `toggle()`, and `isOpen()` flows when the intent is clear and the new behavior
+can be represented safely. Use popover or custom interaction if manual control is still required. Keep the `[human]`
+TODO when human verification is needed.
+
+### `tooltip.auto-close`
+
+Legacy click `autoClose` behavior was not migrated.
+
+This usually belongs with old click-trigger tooltips. Prefer popover or custom interaction if click persistence is
+still required.
+
+### `tooltip.truncate`
+
+`dfTooltipTruncate` depends on the legacy `NgbTooltip` directive and is removed by the deterministic migration.
+
+Rebuild the behavior if the tooltip should only appear when text overflows. If always-on tooltip behavior is acceptable
+or the overflow-only behavior is no longer needed, update the code and keep the `[human]` TODO for review.
+
+### `tooltip.template-reference`
+
+Template references such as `#tooltip="ngbTooltip"` were not migrated.
+
+The new tooltip has no equivalent export or programmatic API. The deterministic migration may still remove independent
+legacy attributes such as `tooltipClass` or `dfTooltipTruncate` on the same element.
+
+### `tooltip.dynamic-placement`
+
+Dynamic placement was migrated to `dfTooltipPlacement`.
+
+Verify the expression only returns supported new placement values. Convert old `left` / `right` values to `start` /
+`end`. Keep `auto`, `vertical`, and `horizontal` values when they are intentional.
+
+### `tooltip.orphan-i18n`
+
+An `i18n-ngbTooltip` marker existed without `ngbTooltip` or `[ngbTooltip]` on the same element.
+
+The deterministic migration removes the orphan i18n marker and leaves a `[human]` TODO. Verify whether a tooltip was
+intended on that element.
+
+### `tooltip.legacy-import`
+
+A legacy tooltip import remains after the deterministic migration.
+
+The deterministic migration intentionally keeps legacy tooltip modules such as `NgbTooltipModule` and `DfTooltipModule`
+so the AI-assisted or manual pass can verify whether shared module imports are still needed. Remove direct `NgbTooltip`
+imports only after no legacy tooltip usages remain.
+
+`DfTooltipTruncateDirective` is different: it should be removed when `dfTooltipTruncate` has been removed.
+
+### `tooltip.indirect-component-imports`
+
+The component needs `DfTooltip`, but its Angular `imports` metadata is not a simple array literal.
+
+Inspect the referenced value or expression. Add `DfTooltip` to the actual imports list only when the shape is clear. If
+the imports value is computed, shared, or otherwise ambiguous, preserve the TODO for human review.
+
+## Configuration Migration
+
+Legacy `NgbTooltipConfig` is not supported anymore and is marked with `TODO(df-migration tooltip.config)` for human
+review.
+
+Do not migrate it automatically. Review the legacy defaults and decide whether they should become local tooltip inputs,
+new `provideDfTooltipConfig()` usage, or application-specific cleanup.
+
+## Validation
+
+After AI-assisted tooltip migration:
+
+1. Confirm no unexpected `ngbTooltip`, `NgbTooltip`, `DfTooltipModule`, `NgbTooltipModule`, or `dfTooltipTruncate`
+   usages remain in app code.
+2. Confirm dynamic `dfTooltip` values are plain text.
+3. Confirm dynamic `dfTooltipPlacement` values use supported new placements.
+4. Run the narrowest useful typecheck/build command for touched projects when the command is clear.
+5. Run visual or e2e checks for dynamic content, truncation, custom trigger, and custom class cases when available.

package/schematics/component-migration/tooltip/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/tooltip/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.tooltipMigration);

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

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

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

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tooltipMigration = 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 template_todos_1 = require("./steps/template-todos");
+const tooltip_imports_1 = require("./steps/tooltip-imports");
+const legacy_config_todos_1 = require("../shared/legacy-config-todos");
+const TOOLTIP_IMPORT = {
+    moduleName: '@design-factory/angular/tooltip',
+    symbolName: 'DfTooltip'
+};
+function getTooltipElements(template) {
+    return (0, template_edits_1.findTemplateElements)(template, (element) => element.attributes.some((attribute) => attribute.name === 'ngbTooltip') ||
+        (0, template_attributes_1.hasTooltipI18nAttribute)(element) ||
+        element.inputs.some((input) => input.name === 'ngbTooltip'));
+}
+function getTemplateReferenceNames(template) {
+    const names = new Set();
+    const templateRefPattern = /<ng-template\b[^>]*#([A-Za-z_$][\w$-]*)/g;
+    let match = templateRefPattern.exec(template);
+    while (match) {
+        names.add(match[1]);
+        match = templateRefPattern.exec(template);
+    }
+    return names;
+}
+function migrateTooltipTemplate(template) {
+    const edits = [];
+    const standaloneImports = [];
+    for (const element of getTooltipElements(template)) {
+        const result = (0, template_attributes_1.editTooltipElement)(element, { templateReferenceNames: getTemplateReferenceNames(template) }, edits);
+        (0, template_todos_1.editTooltipTemplateTodos)(element, edits, { ...result.todos, migrated: result.migrated });
+        if (result.migrated && standaloneImports.length === 0) {
+            standaloneImports.push(TOOLTIP_IMPORT);
+        }
+    }
+    return (0, template_result_1.createTemplateMigrationResult)(template, edits, standaloneImports);
+}
+function migrateTooltipSourceFile(context) {
+    return (0, tooltip_imports_1.editTooltipImports)(context);
+}
+exports.tooltipMigration = {
+    id: 'tooltip',
+    countLegacyTemplateUsages: (template) => getTooltipElements(template).length,
+    migrateTemplate: migrateTooltipTemplate,
+    migrateSourceFile: migrateTooltipSourceFile,
+    migrateProjectSourceFile: (context) => (0, legacy_config_todos_1.editLegacyConfigTodos)(context, ['NgbTooltipConfig'])
+};

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

@@ -0,0 +1,25 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "SchematicsMigrateTooltip",
+  "title": "Migrate Tooltip 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 tooltip usages without applying the migration",
+      "default": false
+    }
+  }
+}

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

@@ -0,0 +1,13 @@
+import { TmplAstElement } from '@angular/compiler';
+import { TemplateEdit } from '../../shared/template-edits';
+import { TooltipTemplateTodoContext } from './template-todos';
+interface TooltipTemplateContext {
+    templateReferenceNames: Set<string>;
+}
+interface TooltipTemplateEditResult {
+    migrated: boolean;
+    todos: TooltipTemplateTodoContext;
+}
+export declare function hasTooltipI18nAttribute(element: TmplAstElement): boolean;
+export declare function editTooltipElement(element: TmplAstElement, context: TooltipTemplateContext, edits: TemplateEdit[]): TooltipTemplateEditResult;
+export {};