@taiga-ui/eslint-plugin-experience-next 0.470.0 → 0.471.0

package/README.md

@@ -43,6 +43,7 @@ export default [
 | class-property-naming                           | Enforce custom naming for class properties based on their type                                      |     | 🔧  |     |
 | decorator-key-sort                              | Sorts the keys of the object passed to the `@Component/@Injectable/@NgModule/@Pipe` decorator       | ✅  | 🔧  |     |
 | flat-exports                                    | Spread nested arrays when exporting Angular entity collections                                      |     | 🔧  |     |
+| host-attributes-sort                            | Sort Angular host metadata attributes using configurable attribute groups                           | ✅  | 🔧  |     |
 | injection-token-description                     | They are required to provide a description for `InjectionToken`                                     | ✅  |     |     |
 | no-deep-imports                                 | Disables deep imports of Taiga UI packages                                                          | ✅  | 🔧  |     |
 | no-deep-imports-to-indexed-packages             | Disallow deep imports from packages that expose an index.ts next to ng-package.json or package.json | ✅  | 🔧  |     |
@@ -180,6 +181,105 @@ export const TuiInput = [...TuiTextfield, TuiInputDirective] as const;
 
 ---
 
+## host-attributes-sort
+
+<sup>`✅ Recommended`</sup> <sup>`Fixable`</sup>
+
+Sorts Angular `host` metadata entries in `@Component` and `@Directive` using configurable attribute groups, matching the
+same grouping model used for template attributes in Prettier. The recommended config enables the rule with a default
+group order that places `id` before plain attributes, `class`, animation bindings, inputs, two-way bindings, and
+outputs.
+
+```ts
+// ❌ error
+@Component({
+  host: {
+    '(click)': 'handleClick()',
+    '[value]': 'value()',
+    class: 'cmp',
+    id: 'cmp-id',
+  },
+})
+
+// ✅ after autofix
+@Component({
+  host: {
+    id: 'cmp-id',
+    class: 'cmp',
+    '[value]': 'value()',
+    '(click)': 'handleClick()',
+  },
+})
+```
+
+The rule understands the same preset names as `prettier-plugin-organize-attributes`. You can use aggregate presets such
+as `$ANGULAR`, `$HTML`, and `$CODE_GUIDE`, or compose atomic presets such as `$CLASS`, `$ID`, `$ARIA`, `$ANGULAR_INPUT`,
+`$ANGULAR_TWO_WAY_BINDING`, and `$ANGULAR_OUTPUT`.
+
+```json
+{
+  "@taiga-ui/experience-next/host-attributes-sort": [
+    "error",
+    {
+      "attributeGroups": ["$ANGULAR"]
+    }
+  ]
+}
+```
+
+Use `$ANGULAR` when `host` should follow the familiar Angular template-style order:
+`class -> id -> #ref -> *directive -> @animation -> [@animation] -> [(model)] -> [input] -> (output)`.
+
+```json
+{
+  "@taiga-ui/experience-next/host-attributes-sort": [
+    "error",
+    {
+      "attributeGroups": ["$HTML"]
+    }
+  ]
+}
+```
+
+Use `$HTML` when only `class` and `id` should be pulled to the front, and everything else can stay in the trailing
+default group.
+
+```json
+{
+  "@taiga-ui/experience-next/host-attributes-sort": [
+    "error",
+    {
+      "attributeGroups": ["$CODE_GUIDE"]
+    }
+  ]
+}
+```
+
+Use `$CODE_GUIDE` for a wider HTML-oriented order: `class`, `id`, `name`, `data-*`, `src`, `for`, `type`, `href`,
+`value`, `title`, `alt`, `role`, `aria-*`.
+
+```json
+{
+  "@taiga-ui/experience-next/host-attributes-sort": [
+    "error",
+    {
+      "attributeGroups": ["$ID", "$DEFAULT", "$ARIA", "$ANGULAR_OUTPUT"]
+    }
+  ]
+}
+```
+
+Use atomic presets when you want a custom order instead of one of the bundled aliases.
+
+| Option                | Type                        | Description                                                       |
+| --------------------- | --------------------------- | ----------------------------------------------------------------- |
+| `attributeGroups`     | `string[]`                  | Group order. Supports the same preset tokens as Prettier plugins. |
+| `attributeIgnoreCase` | `boolean`                   | Ignore case when matching custom regexp groups.                   |
+| `attributeSort`       | `'ASC' \| 'DESC' \| 'NONE'` | Sort order inside each matched group.                             |
+| `decorators`          | `string[]`                  | Decorator names whose `host` metadata should be checked.          |
+
+---
+
 ## injection-token-description
 
 <sup>`✅ Recommended`</sup>

package/index.d.ts

@@ -18,6 +18,14 @@ declare const plugin: {
         'flat-exports': import("@typescript-eslint/utils/ts-eslint").RuleModule<"spreadArrays", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
             name: string;
         };
+        'host-attributes-sort': import("@typescript-eslint/utils/ts-eslint").RuleModule<"incorrectOrder", [{
+            attributeGroups?: string[];
+            attributeIgnoreCase?: boolean;
+            attributeSort?: "ASC" | "DESC" | "NONE";
+            decorators?: string[];
+        }], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+            name: string;
+        };
         'html-logical-properties': import("eslint").Rule.RuleModule;
         'injection-token-description': import("@typescript-eslint/utils/ts-eslint").RuleModule<"invalid-injection-token-description", readonly unknown[], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
             name: string;

package/index.esm.js

@@ -896,6 +896,7 @@ var recommended = defineConfig([
                     Pipe: ['standalone', 'name', 'pure'],
                 },
             ],
+            '@taiga-ui/experience-next/host-attributes-sort': 'error',
             '@taiga-ui/experience-next/injection-token-description': 'error',
             '@taiga-ui/experience-next/no-deep-imports': [
                 'error',
@@ -1334,8 +1335,8 @@ function intersect(a, b) {
     return a.some((type) => origin.has(type));
 }
 
-const createRule$g = ESLintUtils.RuleCreator((name) => name);
-var classPropertyNaming = createRule$g({
+const createRule$h = ESLintUtils.RuleCreator((name) => name);
+var classPropertyNaming = createRule$h({
     create(context, [configs]) {
         const parserServices = ESLintUtils.getParserServices(context);
         const typeChecker = parserServices.program.getTypeChecker();
@@ -1504,9 +1505,9 @@ function isExternalPureTuple(typeChecker, type) {
     return typeArgs.every((item) => isClassType(item));
 }
 
-const createRule$f = ESLintUtils.RuleCreator((name) => name);
+const createRule$g = ESLintUtils.RuleCreator((name) => name);
 const MESSAGE_ID$7 = 'spreadArrays';
-var flatExports = createRule$f({
+var flatExports = createRule$g({
     create(context) {
         const parserServices = ESLintUtils.getParserServices(context);
         const typeChecker = parserServices.program.getTypeChecker();
@@ -1630,6 +1631,317 @@ var flatExports = createRule$f({
     name: 'flat-exports',
 });
 
+function isObject(node) {
+    return node?.type === AST_NODE_TYPES$1.ObjectExpression;
+}
+
+/**
+ * Extracts the metadata object from a class decorator such as
+ * `@Component()`, `@Directive()`, `@NgModule()`, or `@Pipe()`.
+ *
+ * Returns the first argument of the decorator call *if and only if*
+ * it is an `ObjectExpression`.
+ *
+ * @example
+ * // Given:
+ * @Component({
+ *   selector: 'x',
+ *   imports: [A, B],
+ * })
+ * class MyCmp {}
+ *
+ * // In the AST for @Component(...)
+ * getDecoratorMetadata(decorator, allowed) →
+ *    ObjectExpression({ selector: ..., imports: ... })
+ *
+ * @param decorator - The decorator node attached to a class declaration.
+ * @param allowedNames - A set of decorator names to consider
+ *                       (e.g., Component, Directive, NgModule, Pipe).
+ *
+ * @returns The metadata `ObjectExpression` if present and valid,
+ *          otherwise `null`.
+ */
+function getDecoratorMetadata(decorator, allowedNames) {
+    const expr = decorator.expression;
+    if (expr.type !== AST_NODE_TYPES$1.CallExpression) {
+        return null;
+    }
+    const callee = expr.callee;
+    if (callee.type !== AST_NODE_TYPES$1.Identifier) {
+        return null;
+    }
+    if (!allowedNames.has(callee.name)) {
+        return null;
+    }
+    const arg = expr.arguments[0];
+    return isObject(arg) ? arg : null;
+}
+
+function sameOrder(a, b) {
+    return a.length === b.length && a.every((value, index) => value === b[index]);
+}
+
+const DEFAULT_GROUP = '$DEFAULT';
+const DEFAULT_ATTRIBUTE_GROUPS = [
+    '$ANGULAR_STRUCTURAL_DIRECTIVE',
+    '$ANGULAR_ELEMENT_REF',
+    '$ID',
+    '$DEFAULT',
+    '$CLASS',
+    '$ANGULAR_ANIMATION',
+    '$ANGULAR_ANIMATION_INPUT',
+    '$ANGULAR_INPUT',
+    '$ANGULAR_TWO_WAY_BINDING',
+    '$ANGULAR_OUTPUT',
+];
+const DEFAULT_DECORATORS$1 = ['Component', 'Directive'];
+const PRESETS = {
+    $ALT: /^alt$/,
+    $ANGULAR: [
+        '$CLASS',
+        '$ID',
+        '$ANGULAR_ELEMENT_REF',
+        '$ANGULAR_STRUCTURAL_DIRECTIVE',
+        '$ANGULAR_ANIMATION',
+        '$ANGULAR_ANIMATION_INPUT',
+        '$ANGULAR_TWO_WAY_BINDING',
+        '$ANGULAR_INPUT',
+        '$ANGULAR_OUTPUT',
+    ],
+    $ANGULAR_ANIMATION: /^@/,
+    $ANGULAR_ANIMATION_INPUT: /^\[@/,
+    $ANGULAR_ELEMENT_REF: /^#/,
+    $ANGULAR_INPUT: /^\[[^(@]/,
+    $ANGULAR_OUTPUT: /^\(/,
+    $ANGULAR_STRUCTURAL_DIRECTIVE: /^\*/,
+    $ANGULAR_TWO_WAY_BINDING: /^\[\(/,
+    $ARIA: /^aria-/,
+    $CLASS: /^class$/,
+    $CODE_GUIDE: [
+        '$CLASS',
+        '$ID',
+        '$NAME',
+        '$DATA',
+        '$SRC',
+        '$FOR',
+        '$TYPE',
+        '$HREF',
+        '$VALUE',
+        '$TITLE',
+        '$ALT',
+        '$ROLE',
+        '$ARIA',
+    ],
+    $DATA: /^data-/,
+    $FOR: /^for$/,
+    $HREF: /^href$/,
+    $HTML: ['$CLASS', '$ID'],
+    $ID: /^id$/,
+    $NAME: /^name$/,
+    $ROLE: /^role$/,
+    $SRC: /^src$/,
+    $TITLE: /^title$/,
+    $TYPE: /^type$/,
+    $VALUE: /^value$/,
+    $VUE: ['$CLASS', '$ID', '$VUE_ATTRIBUTE'],
+    $VUE_ATTRIBUTE: /^v-/,
+};
+const createRule$f = ESLintUtils.RuleCreator((name) => name);
+const rule$i = createRule$f({
+    create(context, [options]) {
+        const sourceCode = context.sourceCode;
+        const settings = {
+            attributeGroups: [...DEFAULT_ATTRIBUTE_GROUPS],
+            attributeIgnoreCase: true,
+            attributeSort: 'ASC',
+            decorators: [...DEFAULT_DECORATORS$1],
+            ...options,
+        };
+        const allowedDecorators = new Set(settings.decorators);
+        return {
+            ClassDeclaration(node) {
+                for (const decorator of node?.decorators ?? []) {
+                    const metadata = getDecoratorMetadata(decorator, allowedDecorators);
+                    if (!metadata) {
+                        continue;
+                    }
+                    const hostObject = getHostObject(metadata);
+                    if (!hostObject) {
+                        continue;
+                    }
+                    const properties = getHostAttributeProperties(hostObject);
+                    if (!properties || properties.length <= 1) {
+                        continue;
+                    }
+                    const sortedProperties = organizeProperties(properties, settings);
+                    const currentOrder = properties.map(({ name }) => name);
+                    const expectedOrder = sortedProperties.map(({ name }) => name);
+                    if (sameOrder(currentOrder, expectedOrder)) {
+                        continue;
+                    }
+                    const report = {
+                        data: { expected: expectedOrder.join(', ') },
+                        messageId: 'incorrectOrder',
+                        node: hostObject,
+                    };
+                    if (sourceCode.getCommentsInside(hostObject).length > 0) {
+                        context.report(report);
+                        continue;
+                    }
+                    context.report({
+                        ...report,
+                        fix: (fixer) => fixer.replaceTextRange(hostObject.range, `{${sortedProperties
+                            .map(({ node: property }) => sourceCode.getText(property))
+                            .join(', ')}}`),
+                    });
+                }
+            },
+        };
+    },
+    meta: {
+        defaultOptions: [
+            {
+                attributeGroups: [...DEFAULT_ATTRIBUTE_GROUPS],
+                attributeIgnoreCase: true,
+                attributeSort: 'ASC',
+                decorators: [...DEFAULT_DECORATORS$1],
+            },
+        ],
+        docs: {
+            description: 'Sort Angular host metadata attributes using configurable attribute groups.',
+        },
+        fixable: 'code',
+        messages: { incorrectOrder: 'Host attributes should be sorted as [{{expected}}]' },
+        schema: [
+            {
+                additionalProperties: false,
+                properties: {
+                    attributeGroups: {
+                        items: { type: 'string' },
+                        type: 'array',
+                    },
+                    attributeIgnoreCase: { type: 'boolean' },
+                    attributeSort: {
+                        enum: ['ASC', 'DESC', 'NONE'],
+                        type: 'string',
+                    },
+                    decorators: {
+                        items: { type: 'string' },
+                        type: 'array',
+                    },
+                },
+                type: 'object',
+            },
+        ],
+        type: 'problem',
+    },
+    name: 'host-attributes-sort',
+});
+function getHostObject(metadata) {
+    for (const property of metadata.properties) {
+        if (property.type !== AST_NODE_TYPES$1.Property ||
+            property.kind !== 'init' ||
+            property.computed ||
+            property.method) {
+            continue;
+        }
+        if (getStaticPropertyName(property.key) !== 'host') {
+            continue;
+        }
+        return property.value.type === AST_NODE_TYPES$1.ObjectExpression
+            ? property.value
+            : null;
+    }
+    return null;
+}
+function getHostAttributeProperties(hostObject) {
+    const properties = [];
+    for (const property of hostObject.properties) {
+        if (property.type !== AST_NODE_TYPES$1.Property ||
+            property.kind !== 'init' ||
+            property.computed ||
+            property.method) {
+            return null;
+        }
+        const name = getStaticPropertyName(property.key);
+        if (name === null) {
+            return null;
+        }
+        properties.push({ name, node: property });
+    }
+    return properties;
+}
+function getStaticPropertyName(key) {
+    if (key.type === AST_NODE_TYPES$1.Identifier) {
+        return key.name;
+    }
+    if (key.type === AST_NODE_TYPES$1.Literal &&
+        (typeof key.value === 'string' || typeof key.value === 'number')) {
+        return String(key.value);
+    }
+    if (key.type === AST_NODE_TYPES$1.TemplateLiteral &&
+        key.expressions.length === 0 &&
+        key.quasis.length === 1) {
+        return key.quasis[0]?.value.cooked ?? null;
+    }
+    return null;
+}
+function organizeProperties(properties, options) {
+    const groups = getGroups(options.attributeGroups.length > 0 ? options.attributeGroups : ['$ANGULAR'], options.attributeIgnoreCase);
+    const defaultGroup = ensureDefaultGroup(groups);
+    for (const property of properties) {
+        const targetGroup = groups.find(({ regexp }) => regexp?.test(property.name)) ?? defaultGroup;
+        targetGroup.values.push(property);
+    }
+    if (options.attributeSort !== 'NONE') {
+        for (const group of groups) {
+            group.values.sort((left, right) => left.name.localeCompare(right.name));
+            if (options.attributeSort === 'DESC') {
+                group.values.reverse();
+            }
+        }
+    }
+    return groups.flatMap(({ values }) => values);
+}
+function getGroups(queries, ignoreCase) {
+    return queries.flatMap((query) => getGroup(query, ignoreCase));
+}
+function getGroup(query, ignoreCase) {
+    if (query === DEFAULT_GROUP) {
+        return [createDefaultGroup()];
+    }
+    const preset = PRESETS[query];
+    if (!preset) {
+        return [
+            {
+                query,
+                regexp: new RegExp(query, ignoreCase ? 'i' : ''),
+                values: [],
+            },
+        ];
+    }
+    if (Array.isArray(preset)) {
+        return preset.flatMap((item) => getGroup(item, ignoreCase));
+    }
+    return [{ query, regexp: preset, values: [] }];
+}
+function ensureDefaultGroup(groups) {
+    const existing = groups.find(({ unknown }) => unknown);
+    if (existing) {
+        return existing;
+    }
+    const fallback = createDefaultGroup();
+    groups.push(fallback);
+    return fallback;
+}
+function createDefaultGroup() {
+    return {
+        query: DEFAULT_GROUP,
+        unknown: true,
+        values: [],
+    };
+}
+
 const DIRECTIONAL_TO_LOGICAL = {
     'border-bottom': 'border-block-end',
     'border-left': 'border-inline-start',
@@ -5315,52 +5627,6 @@ const rule$1 = createRule$2({
     name: 'short-tui-imports',
 });
 
-function isObject(node) {
-    return node?.type === AST_NODE_TYPES$1.ObjectExpression;
-}
-
-/**
- * Extracts the metadata object from a class decorator such as
- * `@Component()`, `@Directive()`, `@NgModule()`, or `@Pipe()`.
- *
- * Returns the first argument of the decorator call *if and only if*
- * it is an `ObjectExpression`.
- *
- * @example
- * // Given:
- * @Component({
- *   selector: 'x',
- *   imports: [A, B],
- * })
- * class MyCmp {}
- *
- * // In the AST for @Component(...)
- * getDecoratorMetadata(decorator, allowed) →
- *    ObjectExpression({ selector: ..., imports: ... })
- *
- * @param decorator - The decorator node attached to a class declaration.
- * @param allowedNames - A set of decorator names to consider
- *                       (e.g., Component, Directive, NgModule, Pipe).
- *
- * @returns The metadata `ObjectExpression` if present and valid,
- *          otherwise `null`.
- */
-function getDecoratorMetadata(decorator, allowedNames) {
-    const expr = decorator.expression;
-    if (expr.type !== AST_NODE_TYPES$1.CallExpression) {
-        return null;
-    }
-    const callee = expr.callee;
-    if (callee.type !== AST_NODE_TYPES$1.Identifier) {
-        return null;
-    }
-    if (!allowedNames.has(callee.name)) {
-        return null;
-    }
-    const arg = expr.arguments[0];
-    return isObject(arg) ? arg : null;
-}
-
 function getImportsArray(meta) {
     const property = meta.properties.find((literal) => literal.type === AST_NODE_TYPES$1.Property &&
         literal.key.type === AST_NODE_TYPES$1.Identifier &&
@@ -5436,10 +5702,6 @@ function getSortedNames(elements, source) {
     return [...sortedRegular, ...sortedSpreads].map((n) => nameOf(n, source));
 }
 
-function sameOrder(a, b) {
-    return a.length === b.length && a.every((value, index) => value === b[index]);
-}
-
 const createRule$1 = ESLintUtils.RuleCreator((name) => name);
 var standaloneImportsSort = createRule$1({
     create(context, [options]) {
@@ -5609,6 +5871,7 @@ const plugin = {
         'class-property-naming': classPropertyNaming,
         'decorator-key-sort': config$3,
         'flat-exports': flatExports,
+        'host-attributes-sort': rule$i,
         'html-logical-properties': config$2,
         'injection-token-description': rule$h,
         'no-deep-imports': rule$g,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taiga-ui/eslint-plugin-experience-next",
-  "version": "0.470.0",
+  "version": "0.471.0",
   "description": "An ESLint plugin to enforce a consistent code styles across taiga-ui projects",
   "repository": {
     "type": "git",

package/rules/host-attributes-sort.d.ts

@@ -0,0 +1,14 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+type SortOrder = 'ASC' | 'DESC' | 'NONE';
+type Options = [
+    {
+        attributeGroups?: string[];
+        attributeIgnoreCase?: boolean;
+        attributeSort?: SortOrder;
+        decorators?: string[];
+    }
+];
+export declare const rule: ESLintUtils.RuleModule<"incorrectOrder", Options, unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};
+export default rule;