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

package/schematics/component-migration/alert/steps/icon-directive.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.editIconDirective = editIconDirective;
+const template_edits_1 = require("../../shared/template-edits");
+function editIconDirective(element, edits) {
+    const iconDirective = (0, template_edits_1.findTextAttribute)(element, 'dfInsertAlertIcon');
+    if (iconDirective) {
+        edits.push((0, template_edits_1.removeTextAttribute)(iconDirective));
+    }
+}

package/schematics/component-migration/alert/steps/legacy-module-imports.d.ts

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

package/schematics/component-migration/alert/steps/legacy-module-imports.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.editLegacyModuleImportTodos = editLegacyModuleImportTodos;
+const tslib_1 = require("tslib");
+const ts = tslib_1.__importStar(require("typescript"));
+const todo_comments_1 = require("../../shared/todo-comments");
+const alert_imports_1 = require("./alert-imports");
+const LEGACY_NG_BOOTSTRAP_IMPORTS = new Set(['@ng-bootstrap/ng-bootstrap/alert', '@ng-bootstrap/ng-bootstrap']);
+const LEGACY_DESIGN_FACTORY_IMPORTS = new Set([
+    '@design-factory/design-factory',
+    '@design-factory/design-factory/alert'
+]);
+const NGB_ALERT_MODULE = 'NgbAlertModule';
+const DF_ALERT_MODULE = 'DfAlertModule';
+function getNamedImportNames(statement) {
+    const namedBindings = statement.importClause?.namedBindings;
+    if (!namedBindings || !ts.isNamedImports(namedBindings)) {
+        return [];
+    }
+    return namedBindings.elements.map((element) => element.propertyName?.text ?? element.name.text);
+}
+function getLegacyAlertModuleNames(statement) {
+    if (!ts.isStringLiteral(statement.moduleSpecifier)) {
+        return [];
+    }
+    const moduleName = statement.moduleSpecifier.text;
+    const importedNames = getNamedImportNames(statement);
+    if (LEGACY_NG_BOOTSTRAP_IMPORTS.has(moduleName)) {
+        return importedNames.filter((name) => name === NGB_ALERT_MODULE);
+    }
+    if (LEGACY_DESIGN_FACTORY_IMPORTS.has(moduleName)) {
+        return importedNames.filter((name) => name === DF_ALERT_MODULE);
+    }
+    return [];
+}
+function editLegacyModuleImportTodos(context) {
+    const edits = [];
+    const skipNgbAlertModule = (0, alert_imports_1.sourceFileNeedsDfAlert)(context);
+    for (const statement of context.sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement)) {
+            continue;
+        }
+        const legacyModuleNames = getLegacyAlertModuleNames(statement).filter((name) => name !== NGB_ALERT_MODULE || !skipNgbAlertModule);
+        if (legacyModuleNames.length === 0) {
+            continue;
+        }
+        const edit = (0, todo_comments_1.editSourceTodo)(context.sourceFile, statement, {
+            code: 'alert.legacy-module-import',
+            message: 'Legacy alert module import remains. Verify whether it is still needed for other legacy components or remove it after alert migration.'
+        });
+        if (edit) {
+            edits.push(edit);
+            break;
+        }
+    }
+    return edits;
+}

package/schematics/component-migration/alert/steps/programmatic-close.d.ts

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

package/schematics/component-migration/alert/steps/programmatic-close.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.editProgrammaticCloseTodos = editProgrammaticCloseTodos;
+const tslib_1 = require("tslib");
+const ts = tslib_1.__importStar(require("typescript"));
+const todo_comments_1 = require("../../shared/todo-comments");
+function isCloseSubscribeCall(node) {
+    if (!ts.isCallExpression(node) || !ts.isPropertyAccessExpression(node.expression)) {
+        return false;
+    }
+    const closeCall = node.expression.expression;
+    return (node.expression.name.text === 'subscribe' &&
+        ts.isCallExpression(closeCall) &&
+        ts.isPropertyAccessExpression(closeCall.expression) &&
+        closeCall.expression.name.text === 'close');
+}
+function findStatement(node) {
+    let current = node;
+    while (current.parent && !ts.isStatement(current)) {
+        current = current.parent;
+    }
+    return current;
+}
+function editProgrammaticCloseTodos(context) {
+    const edits = [];
+    const hasAlertTemplate = [...context.templatesByComponent.values()].some((templates) => templates.some((template) => template.includes('<ngb-alert') || template.includes('<df-alert')));
+    if (!hasAlertTemplate) {
+        return edits;
+    }
+    const visitNode = (node) => {
+        if (isCloseSubscribeCall(node)) {
+            const edit = (0, todo_comments_1.editSourceTodo)(context.sourceFile, findStatement(node), {
+                code: 'alert.programmatic-close',
+                message: 'close() now returns a Promise. Migrate this legacy Observable close handling manually.'
+            });
+            if (edit) {
+                edits.push(edit);
+            }
+        }
+        ts.forEachChild(node, visitNode);
+    };
+    visitNode(context.sourceFile);
+    return edits;
+}

package/schematics/component-migration/alert/steps/selector.d.ts

@@ -0,0 +1,3 @@
+import { TmplAstElement } from '@angular/compiler';
+import { TemplateEdit } from '../../shared/template-edits';
+export declare function editSelector(element: TmplAstElement, edits: TemplateEdit[]): void;

package/schematics/component-migration/alert/steps/selector.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.editSelector = editSelector;
+function editSelector(element, edits) {
+    const startTagOffset = element.startSourceSpan.start.offset;
+    edits.push({
+        start: startTagOffset + 1,
+        end: startTagOffset + 10,
+        text: 'df-alert'
+    });
+    if (element.endSourceSpan) {
+        edits.push({
+            start: element.endSourceSpan.start.offset + 2,
+            end: element.endSourceSpan.start.offset + 11,
+            text: 'df-alert'
+        });
+    }
+}

package/schematics/component-migration/alert/steps/static-classes.d.ts

@@ -0,0 +1,3 @@
+import { TmplAstElement } from '@angular/compiler';
+import { TemplateEdit } from '../../shared/template-edits';
+export declare function editStaticClasses(element: TmplAstElement, edits: TemplateEdit[]): void;

package/schematics/component-migration/alert/steps/static-classes.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.editStaticClasses = editStaticClasses;
+const template_edits_1 = require("../../shared/template-edits");
+const SIZE_CLASSES = new Map([
+    ['df-alert-sm', 'sm'],
+    ['df-alert-lg', 'lg']
+]);
+const BANNER_CLASSES = new Set(['df-page-alert', 'df-card-alert']);
+const RESPONSIVE_BREAKPOINT = '(?:sm|md|lg|xl|xxl)';
+const SPACING_CLASS = new RegExp(`^[mp][trblxy]?(?:-${RESPONSIVE_BREAKPOINT})?-(?:n?\\d+|auto)$`);
+const BOTTOM_MARGIN_CLASS = new RegExp(`^m(?:[by])?(?:-${RESPONSIVE_BREAKPOINT})?-(?:n?\\d+|auto)$`);
+const UTILITY_CLASS_PATTERNS = [
+    SPACING_CLASS,
+    /^d(?:-(?:sm|md|lg|xl|xxl))?-(?:none|inline|inline-block|block|grid|inline-grid|table|table-row|table-cell|flex|inline-flex)$/,
+    /^w-(?:25|50|75|100|auto)$/,
+    /^h-(?:25|50|75|100|auto)$/,
+    /^text-/,
+    /^fw-/,
+    /^fs-/,
+    /^lh-/,
+    /^align-/,
+    /^justify-content-/,
+    /^align-items-/,
+    /^align-self-/,
+    /^flex-/,
+    /^overflow-/,
+    /^position-/,
+    /^rounded(?:-.+)?$/,
+    /^border(?:-.+)?$/,
+    /^word-break-all$/,
+    /^overflow-wrap-word$/
+];
+function hasBottomMarginClass(classes) {
+    return classes.some((className) => BOTTOM_MARGIN_CLASS.test(className));
+}
+function isUtilityClass(className) {
+    return UTILITY_CLASS_PATTERNS.some((pattern) => pattern.test(className));
+}
+function shouldAddDefaultBottomMargin(element, classes, remainingClasses) {
+    if ((0, template_edits_1.hasDynamicClassBinding)(element) || hasBottomMarginClass(classes)) {
+        return false;
+    }
+    if (classes.some((className) => BANNER_CLASSES.has(className))) {
+        return false;
+    }
+    if ((0, template_edits_1.findTextAttribute)(element, 'appearance') || (0, template_edits_1.findBoundAttribute)(element, 'appearance')) {
+        return false;
+    }
+    return remainingClasses.every(isUtilityClass);
+}
+function editStaticClasses(element, edits) {
+    const classAttribute = (0, template_edits_1.findTextAttribute)(element, 'class');
+    const classes = classAttribute?.value.split(/\s+/).filter(Boolean) ?? [];
+    const removableClasses = new Set();
+    const addedAttributes = [];
+    const sizeClasses = classes.filter((className) => SIZE_CLASSES.has(className));
+    if (sizeClasses.length === 1 && !(0, template_edits_1.findTextAttribute)(element, 'size') && !(0, template_edits_1.findBoundAttribute)(element, 'size')) {
+        removableClasses.add(sizeClasses[0]);
+        addedAttributes.push(`size="${SIZE_CLASSES.get(sizeClasses[0])}"`);
+    }
+    const hasBannerClass = classes.some((className) => BANNER_CLASSES.has(className));
+    if (hasBannerClass && !(0, template_edits_1.findTextAttribute)(element, 'appearance') && !(0, template_edits_1.findBoundAttribute)(element, 'appearance')) {
+        for (const className of BANNER_CLASSES) {
+            removableClasses.add(className);
+        }
+        addedAttributes.push('appearance="banner"');
+    }
+    const remainingClasses = classes.filter((className) => !removableClasses.has(className));
+    if (shouldAddDefaultBottomMargin(element, classes, remainingClasses)) {
+        remainingClasses.push('mb-5');
+    }
+    if (removableClasses.size === 0 && remainingClasses.length === classes.length && addedAttributes.length === 0) {
+        return;
+    }
+    if (!classAttribute && remainingClasses.length > 0) {
+        addedAttributes.unshift(`class="${remainingClasses.join(' ')}"`);
+    }
+    else if (classAttribute && remainingClasses.length === 0) {
+        edits.push((0, template_edits_1.removeTextAttribute)(classAttribute));
+    }
+    else if (classAttribute?.valueSpan) {
+        edits.push({
+            start: classAttribute.valueSpan.start.offset,
+            end: classAttribute.valueSpan.end.offset,
+            text: remainingClasses.join(' ')
+        });
+    }
+    if (addedAttributes.length > 0) {
+        const insertOffset = (0, template_edits_1.getStartTagInsertOffset)(element);
+        edits.push({
+            start: insertOffset,
+            end: insertOffset,
+            text: ` ${addedAttributes.join(' ')}`
+        });
+    }
+}

package/schematics/component-migration/alert/steps/static-type.d.ts

@@ -0,0 +1,3 @@
+import { TmplAstElement } from '@angular/compiler';
+import { TemplateEdit } from '../../shared/template-edits';
+export declare function editStaticType(element: TmplAstElement, edits: TemplateEdit[]): void;

package/schematics/component-migration/alert/steps/static-type.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.editStaticType = editStaticType;
+const template_edits_1 = require("../../shared/template-edits");
+const SUPPORTED_TYPES = new Set(['success', 'info', 'warning', 'danger', 'tip']);
+const UNSUPPORTED_TYPE_REPLACEMENTS = new Map([
+    ['primary', 'info'],
+    ['secondary', 'info'],
+    ['light', 'info'],
+    ['dark', 'info']
+]);
+function editStaticType(element, edits) {
+    if ((0, template_edits_1.findBoundAttribute)(element, 'type')) {
+        return;
+    }
+    const typeAttribute = (0, template_edits_1.findTextAttribute)(element, 'type');
+    if (!typeAttribute || !typeAttribute.valueSpan || typeAttribute.value.includes('{{')) {
+        return;
+    }
+    if (SUPPORTED_TYPES.has(typeAttribute.value)) {
+        return;
+    }
+    edits.push({
+        start: typeAttribute.valueSpan.start.offset,
+        end: typeAttribute.valueSpan.end.offset,
+        text: UNSUPPORTED_TYPE_REPLACEMENTS.get(typeAttribute.value) ?? 'info'
+    });
+}

package/schematics/component-migration/alert/steps/template-reference.d.ts

@@ -0,0 +1,3 @@
+import { TmplAstElement } from '@angular/compiler';
+import { TemplateEdit } from '../../shared/template-edits';
+export declare function editTemplateReference(element: TmplAstElement, edits: TemplateEdit[]): void;

package/schematics/component-migration/alert/steps/template-reference.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.editTemplateReference = editTemplateReference;
+function editTemplateReference(element, edits) {
+    for (const reference of element.references) {
+        if (reference.value !== 'ngbAlert') {
+            continue;
+        }
+        edits.push({
+            start: reference.sourceSpan.start.offset,
+            end: reference.sourceSpan.end.offset,
+            text: `#${reference.name}`
+        });
+    }
+}

package/schematics/component-migration/alert/steps/template-todos.d.ts

@@ -0,0 +1,3 @@
+import { TmplAstElement } from '@angular/compiler';
+import { TemplateEdit } from '../../shared/template-edits';
+export declare function editAlertTemplateTodos(element: TmplAstElement, edits: TemplateEdit[]): void;

package/schematics/component-migration/alert/steps/template-todos.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.editAlertTemplateTodos = editAlertTemplateTodos;
+const compiler_1 = require("@angular/compiler");
+const todo_comments_1 = require("../../shared/todo-comments");
+const template_edits_1 = require("../../shared/template-edits");
+function hasCollapsibleDescendant(element) {
+    const visitNode = (node) => {
+        if (!(node instanceof compiler_1.TmplAstElement)) {
+            return false;
+        }
+        const classes = (0, template_edits_1.getStaticClassTokens)(node);
+        if ((0, template_edits_1.findTextAttribute)(node, 'ngbCollapse') ||
+            (0, template_edits_1.findBoundAttribute)(node, 'ngbCollapse') ||
+            classes.includes('df-alert-collapse-main-text') ||
+            classes.includes('df-alert-collapsed-text')) {
+            return true;
+        }
+        return node.children.some(visitNode);
+    };
+    return element.children.some(visitNode);
+}
+function hasDynamicLegacyClassBinding(element) {
+    const legacyClassNames = new Set([
+        'df-alert-sm',
+        'df-alert-lg',
+        'df-page-alert',
+        'df-card-alert',
+        'df-superheader',
+        'df-alert-collapse-main-text',
+        'df-alert-collapsed-text'
+    ]);
+    return element.inputs.some((input) => legacyClassNames.has(input.name));
+}
+function hasPageLevelAlertClass(element) {
+    return ((0, template_edits_1.getStaticClassTokens)(element).includes('df-page-alert') ||
+        element.inputs.some((input) => input.name === 'df-page-alert'));
+}
+function editAlertTemplateTodos(element, edits) {
+    const todos = [
+        {
+            code: 'alert.review',
+            message: 'This alert was migrated automatically. Verify behavior and visual appearance.'
+        }
+    ];
+    if ((0, template_edits_1.hasDynamicClassBinding)(element)) {
+        todos.push({
+            code: 'alert.dynamic-class',
+            message: 'Dynamic alert classes were not migrated. Check whether they still target legacy alert classes.'
+        });
+    }
+    if (hasDynamicLegacyClassBinding(element)) {
+        todos.push({
+            code: 'alert.dynamic-legacy-class',
+            message: 'Dynamic legacy alert class binding was not migrated. Convert it to size or appearance input logic.'
+        });
+    }
+    if (hasPageLevelAlertClass(element)) {
+        todos.push({
+            code: 'alert.page-level-layout',
+            marker: 'human',
+            message: 'Legacy df-page-alert fixed positioning was not migrated. Move this banner into the page layout alert slot or add app-owned positioning below the top navigation.'
+        });
+    }
+    if ((0, template_edits_1.findBoundAttribute)(element, 'type')) {
+        todos.push({
+            code: 'alert.dynamic-type',
+            message: 'Dynamic alert type was preserved. Verify it only produces df-alert supported types.'
+        });
+    }
+    if (hasCollapsibleDescendant(element)) {
+        todos.push({
+            code: 'alert.collapsible-pattern',
+            message: 'Legacy collapsible alert markup was not migrated. Convert it to expandable alert structure manually.'
+        });
+    }
+    (0, todo_comments_1.editTemplateTodos)(element, todos, edits);
+}

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

@@ -0,0 +1,278 @@
+# Button Migration Guide
+
+This guide is used by AI-assisted migration after the deterministic `migrate-button` 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 buttons are plain `button` or `a` elements styled with Bootstrap and legacy Design Factory classes:
+
+- `btn`
+- `btn-primary`
+- `btn-outline-primary`
+- `btn-neutral`
+- `btn-outline-neutral`
+- `btn-danger`
+- `btn-outline-danger`
+- `btn-link`
+- `btn-sm`
+- `btn-lg`
+- `df-btn-tertiary`
+- `df-btn-transparent`
+- `df-btn-icononly`
+- `df-btn-primary-mirror`
+- `df-btn-outline-primary-mirror`
+- `df-btn-neutral-mirror`
+- `df-btn-outline-neutral-mirror`
+- `df-btn-danger-mirror`
+- `df-btn-outline-danger-mirror`
+
+Some Bootstrap button-like patterns are not migrated deterministically, including dropdown toggles, button groups, and
+radio/checkbox `btn-check` patterns.
+
+## New API
+
+New buttons use standalone exports from `@design-factory/angular/button`:
+
+```ts
+import { DfButton, DfIconButton } from '@design-factory/angular/button';
+```
+
+Supported directives:
+
+- `button[dfButton]`
+- `a[dfButton]`
+- `button[dfIconButton]`
+- `a[dfIconButton]`
+
+Supported visual inputs:
+
+- `variant`: `primary`, `neutral`, `danger`
+- `appearance`: `solid`, `outline`, `text`
+- `size`: `sm`, `md`, `lg`
+- `transparent`
+- `mirror`
+
+Native `button` hosts default to `type="button"`. Preserve explicit non-default types such as `type="submit"`.
+
+`dfIconButton` does not project content. Icon classes must be present on the `button` or `a` host.
+
+## Deterministic Schematic Changes
+
+The schematic handles static legacy button classes when the host is `button` or `a` and exact static class `btn` is
+present.
+
+It can:
+
+- add `dfButton` or `dfIconButton`;
+- convert supported static variant, appearance, size, transparent, mirror, and icon-only classes;
+- move a single static projected icon element class to the host for simple icon-only buttons;
+- keep complex projected icon-only content in place while still migrating the host;
+- remove `type="button"` from `button` hosts;
+- preserve `type="submit"` and other non-default button types;
+- preserve unrelated user classes;
+- add standalone imports;
+- add TODO comments for review, skipped patterns, and dynamic legacy class logic.
+
+The schematic intentionally ignores already migrated button directives.
+
+## 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.
+
+Some button TODO sections explicitly say to leave a pattern unchanged during the AI-assisted pass. Those instructions
+override the general `[human]` rule because the behavior belongs to another component migration or changes host
+semantics too much for a safe button-only pass.
+
+### `button.review`
+
+The button was migrated automatically. Verify behavior and visual appearance.
+
+Keep or remove this TODO based on review. If no behavior issue is found, remove it.
+
+Pay attention to custom classes preserved by the schematic. A class that previously relied on `.btn` may need a local
+CSS adjustment after `.btn` is removed.
+
+### `button.unsupported-static-classes`
+
+The element has exact static `btn` but the deterministic schematic could not map the static legacy classes.
+
+Do not resolve this TODO in the AI-assisted pass. Preserve the TODO and leave the markup unchanged unless the user
+explicitly asks to map the unsupported visual style manually.
+
+Common cases:
+
+- `btn-success`
+- `btn-info`
+- `btn-warning`
+- `btn-secondary`
+- `btn-light`
+- `btn-dark`
+  For unsupported color variants, prefer migrating the structural button API and mapping to the closest supported new
+  variant only when the semantic intent is clear. Supported variants are `primary`, `neutral`, and `danger`.
+
+If the old color was purely decorative or ambiguous, keep the migration local and leave a review note rather than
+inventing behavior.
+
+### `button.dropdown-pattern`
+
+The button is part of a legacy dropdown pattern. Leave it for the dropdown migration unless the user explicitly asks to
+handle dropdowns now.
+
+Common detected patterns:
+
+- dropdown toggles, such as `ngbDropdownToggle`, `dropdownToggle`, `dropdown-toggle`, or `dropdown-toggle-split`;
+- dropdown item buttons such as `ngbDropdownItem` or `dropdown-item`.
+
+Regular buttons inside dropdown containers are still handled by the button migration unless the button itself is a
+dropdown toggle or item.
+
+Do not blindly remove dropdown classes or directives. Preserve dropdown behavior, IDs used by menus, and test selectors.
+
+### `button.link-pattern`
+
+The button uses legacy `btn-link` styling.
+
+The closest new API is probably `appearance="text"`, but `btn-link` is no longer supported by DF.
+Do not resolve this TODO in the AI-assisted pass. Preserve the TODO and leave the button unchanged unless the user
+explicitly asks to handle `btn-link` manually.
+
+### `button.card-pattern`
+
+The button is used as a selectable card or card-like control and was skipped by the deterministic migration.
+
+Do not blindly remove `card` classes or custom selectable-card directives. Check whether this should remain custom card
+markup, use a future card migration, or use a button directive only for keyboard/interaction behavior.
+
+### `button.group-pattern`
+
+The button is inside a legacy `.btn-group`, `.btn-group-vertical`, or `.btn-toolbar` container and was skipped by the
+deterministic migration.
+
+Do not resolve this TODO in the AI-assisted pass. Preserve the TODO and leave the markup unchanged unless the user
+explicitly asks to handle button groups manually.
+
+Button groups may depend on shared borders, focus order, selection semantics, or a future group-specific migration.
+
+### `button.non-native-icon-only-pattern`
+
+The element uses legacy icon-only button classes on a non-native host such as `span`.
+
+Do not resolve this TODO in the AI-assisted pass. Preserve the TODO and leave the markup unchanged unless the user
+explicitly asks to handle this pattern manually.
+
+A non-native host may be purely decorative today, while a native button becomes focusable and clickable. Removing legacy
+button classes can also change visual styling without proving intent.
+
+### `button.projected-icon-only-content`
+
+The legacy icon-only button projects content, but the new `dfIconButton` ignores projected content.
+
+The deterministic schematic migrates the host to `dfIconButton` even when projected content is complex. It only removes
+projected content for the safe case where the content is one static `span`, `i`, or `df-icon` element with a static
+`class`. For this TODO, inspect the remaining projected content and migrate it only when intent is clear:
+
+- move static icon classes to the `button` or `a` host;
+- remove the projected icon element only if it has no behavior or meaningful attributes;
+- convert projected visually-hidden label text to `aria-label` or `[attr.aria-label]` when the value is clear;
+- preserve dynamic icon logic by moving it to host class bindings when straightforward;
+- leave the TODO in place when there are multiple children, conditional content, events, directives, or unclear visual
+  logic.
+
+### `button.icon-only-accessible-name`
+
+The icon-only button has no obvious `aria-label`, `aria-labelledby`, or known project helper such as
+`prefixAriaLabelledby`.
+
+This TODO is marked `[human]`. AI may add an accessible name when the intent is clear from nearby text, a projected
+visually-hidden label, icon class names, click handlers, or component context, but the TODO must remain for human
+review. Leave the markup unchanged when the label would be a guess.
+
+### `button.non-native-button-pattern`
+
+The element uses legacy button classes on a non-native host such as `span`.
+
+Do not resolve this TODO in the AI-assisted pass. Preserve the TODO and leave the markup unchanged unless the user
+explicitly asks to handle this pattern manually.
+
+Changing the host to a native button can alter layout, focus behavior, keyboard behavior, form behavior, and
+accessibility semantics. Removing legacy button classes can also change visual styling without proving intent.
+
+### `button.trigger-click-pattern`
+
+The element uses `dfTriggerClick` with legacy button-like markup.
+
+Do not resolve this TODO in the AI-assisted pass. Preserve the TODO and leave the markup unchanged unless the user
+explicitly asks to handle this pattern manually.
+
+`dfTriggerClick` often delegates interaction to another control, such as a hidden file input. Replacing it with a native
+button and direct click handler changes behavior and must be reviewed manually.
+
+### `button.dynamic-class`
+
+Dynamic button classes were detected on a legacy-looking button.
+
+This TODO is emitted only when the element has exact static `btn` with a generic class expression, or explicit dynamic
+legacy button class bindings. It is not emitted for non-button class bindings such as icon or state classes, and it is
+not emitted when the element already has a hard-stop TODO, such as `button.unsupported-static-classes`,
+`button.card-pattern`, `button.dropdown-pattern`, `button.group-pattern`, `button.link-pattern`,
+`button.non-native-button-pattern`, `button.non-native-icon-only-pattern`, or `button.trigger-click-pattern`.
+
+Arbitrary dynamic-class buttons without legacy button evidence should not be migrated.
+
+Inspect `[class]`, `[ngClass]`, and class binding expressions. Convert legacy button styling to new inputs only when the
+expression is clear.
+
+### `button.dynamic-legacy-class`
+
+An explicit dynamic legacy button class binding was detected, for example `[class.btn-lg]` or
+`[class.btn-primary]`.
+
+Convert to input logic when possible:
+
+- `[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`.
+
+### `button.indirect-component-imports`
+
+The component needs one or more DF button imports, but its Angular `imports` metadata is not a simple array literal.
+
+Inspect the referenced value or expression. Add the required imports, such as `DfButton` or `DfIconButton`, only when
+the shape is clear. If the imports value is computed, shared, or otherwise ambiguous, preserve the TODO for human
+review.
+
+## Links
+
+For `a.btn.disabled` legacy links, prefer `a dfButton disabled` when the anchor should behave as a disabled button.
+Clean up stale `disabled` class, `aria-disabled`, or `tabindex` only when the new directive now owns the behavior and no
+custom logic relies on those attributes.
+
+Preserve `href`, `routerLink`, query params, targets, rel attributes, click handlers, and test selectors.
+
+## Configuration Migration
+
+Configuration migration is out of scope for this component migration. Do not migrate global or shared button styling,
+theme configuration, or wrapper defaults unless the user explicitly asks for configuration migration.
+
+## Validation
+
+After AI-assisted button migration:
+
+1. Confirm no unexpected legacy `btn` button usages remain for the selected scope.
+2. Run the narrowest useful typecheck/build command for touched projects when the command is clear.
+3. Run visual or e2e checks for links, disabled states, dropdowns, button groups, icon-only buttons, and dynamic class
+   logic.
+4. Ask the user before running broad or expensive validation commands if the right command is unclear.

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

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