@yoo-digital/eslint-plugin-angular 1.0.0 → 1.2.0

package/README.md

@@ -8,28 +8,106 @@ Here should live all custom Angular lint rules that eslint does not already prov
 
 Wrong code is yellow underlined in VScode, it can also be raises running : `npm run lint`
 
-## Rule 1 : boolean input conversion
+## Rule 1 : boolean input conversion (prefer-boolean-attribute-shorthand)
 
 `booleanAttribute @angular/core`
 
 `BooleanInput @angular/cdk/coercion`
 
+### ⚠️ Important Limitations
+
+**Current Implementation:** This rule enforces shorthand syntax (`<x a />` instead of `<x [a]="true" />`) but **cannot automatically verify**:
+- Whether an input has `transform: booleanAttribute` 
+- What the default value of an input is
+
+This is a technical limitation of Angular ESLint - template rules cannot access the component's TypeScript code.
+
+### Recommended Usage
+
+This rule works best when:
+1. **All boolean inputs** in your project use `booleanAttribute` transform
+2. **Most boolean inputs** have `default = false` or no default
+3. You treat this as a **style guide enforcer** rather than a safety checker
+
+### Configuration
+
+By default, the rule only flags `[attr]="true"` bindings (safe default):
+
+```json
+{
+  "rules": {
+    "@yoo-digital/eslint-plugin-angular/prefer-boolean-attribute-shorthand": "error"
+  }
+}
+```
+
+To also enforce removal of `[attr]="false"` bindings:
+
+```json
+{
+  "rules": {
+    "@yoo-digital/eslint-plugin-angular/prefer-boolean-attribute-shorthand": [
+      "error",
+      { "allowFalseLiteral": false }
+    ]
+  }
+}
+```
+
 ### Examples
 
-`<myComp [myBoolInput]="true" ` must be `<myComp myBoolInput`
+#### ✅ Recommended Pattern (Default false or no default)
+
+```typescript
+// Component
+@Input({ transform: booleanAttribute }) disabled: boolean = false;
+// OR
+disabled = input<boolean, BooleanInput>(false, { transform: booleanAttribute });
+```
+
+**Template:**
+- ❌ `<button [disabled]="true">` → Should be `<button disabled>`
+- ✅ `<button disabled>` (shorthand for true)
+- ✅ `<button>` (omit for false)
+- ✅ `<button [disabled]="isLoading">` (expressions are allowed)
+
+#### ⚠️ Special Case: Default true (Disable rule if needed)
+
+```typescript
+// Component
+@Input({ transform: booleanAttribute }) enabled: boolean = true;
+```
+
+**Template:**
+```html
+<!-- eslint-disable-next-line @yoo-digital/eslint-plugin-angular/prefer-boolean-attribute-shorthand -->
+<button [enabled]="false">Explicitly disabled</button>
+```
+
+When default is `true`, you may need explicit `[attr]="true"` or `[attr]="false"` bindings.
+
+#### ❌ Without booleanAttribute (Won't work!)
 
-`<myComp [myBoolInput]="false"` must be `<myComp `
+```typescript
+// Component - Missing transform!
+@Input() checked: boolean = false;
+```
 
-`<myComp [myBoolInput]="2+2===4"` is accepted
+**Template:**
+- ❌ `<input checked>` → Will pass `""` (empty string), NOT boolean!
+- ✅ `<input [checked]="true">` (must use property binding)
 
-### Decorator
+### Decorator Syntax
 
-`@Input({ transform: booleanAttribute }) myInput: boolean = true;`
+`@Input({ transform: booleanAttribute }) myInput: boolean = false;`
 
-### Signal
+### Signal Input Syntax
 
-`myInput = input<boolean, BooleanInput>(true, {transform: booleanAttribute,});`
+`myInput = input<boolean, BooleanInput>(false, { transform: booleanAttribute });`
 
-### Exception
+### Summary
 
-If a **required** boolean input needs to be false, no choice, `[myRequiredInput]="false"` must be written. Therefore boolean input should never be required.
+- **Rule enforces**: `[attr]="true"` → `attr` shorthand
+- **Rule assumes**: Inputs have `booleanAttribute` and `default ≠ true`
+- **Manual override**: Use eslint-disable comments for special cases
+- **Best practice**: Ensure all boolean inputs use `booleanAttribute`

package/dist/rules/prefer-boolean-attribute-shorthand.d.ts

@@ -1,8 +1,25 @@
 import type { TSESLint } from '@typescript-eslint/utils';
-interface Options {
-    allowFalseLiteral?: boolean;
-}
-type MessageIds = 'preferTrue' | 'preferFalse' | 'suggestTrue' | 'suggestRemove';
+type MessageIds = 'preferTrue' | 'suggestTrue';
 export declare const RULE_NAME = "prefer-boolean-attribute-shorthand";
-export declare const preferBooleanAttributeShorthandRule: TSESLint.RuleModule<MessageIds, Options[]>;
+/**
+ * This rule enforces shorthand syntax for boolean inputs bound to true.
+ *
+ * BEHAVIOR:
+ * - [attr]="true"  → Warns and suggests: attr
+ * - [attr]="false" → No warning (ignored)
+ * - attr           → OK (already shorthand)
+ *
+ * ASSUMPTIONS:
+ * This rule assumes that boolean inputs use Angular's booleanAttribute transform,
+ * which allows the shorthand syntax to work correctly. The presence of the attribute
+ * alone (without a binding) will be interpreted as true.
+ *
+ * LIMITATIONS:
+ * Cannot verify at lint-time whether:
+ * - The input actually has `transform: booleanAttribute`
+ * - The input's default value
+ *
+ * Use this rule in projects where boolean inputs consistently use booleanAttribute.
+ */
+export declare const preferBooleanAttributeShorthandRule: TSESLint.RuleModule<MessageIds, []>;
 export {};

package/dist/rules/prefer-boolean-attribute-shorthand.js

@@ -3,39 +3,41 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.preferBooleanAttributeShorthandRule = exports.RULE_NAME = void 0;
 const utils_1 = require("@angular-eslint/utils");
 exports.RULE_NAME = 'prefer-boolean-attribute-shorthand';
+/**
+ * This rule enforces shorthand syntax for boolean inputs bound to true.
+ *
+ * BEHAVIOR:
+ * - [attr]="true"  → Warns and suggests: attr
+ * - [attr]="false" → No warning (ignored)
+ * - attr           → OK (already shorthand)
+ *
+ * ASSUMPTIONS:
+ * This rule assumes that boolean inputs use Angular's booleanAttribute transform,
+ * which allows the shorthand syntax to work correctly. The presence of the attribute
+ * alone (without a binding) will be interpreted as true.
+ *
+ * LIMITATIONS:
+ * Cannot verify at lint-time whether:
+ * - The input actually has `transform: booleanAttribute`
+ * - The input's default value
+ *
+ * Use this rule in projects where boolean inputs consistently use booleanAttribute.
+ */
 exports.preferBooleanAttributeShorthandRule = {
     meta: {
         type: 'suggestion',
         docs: {
-            description: 'Prefer boolean input attribute shorthand instead of binding to literal true/false.',
+            description: 'Prefer boolean input attribute shorthand when binding to true (e.g., use "disabled" instead of [disabled]="true").',
         },
         hasSuggestions: true,
-        schema: [
-            {
-                type: 'object',
-                properties: {
-                    allowFalseLiteral: { type: 'boolean' },
-                },
-                additionalProperties: false,
-            },
-        ],
+        schema: [],
         messages: {
             preferTrue: 'Use attribute shorthand "{{attr}}" instead of [{{attr}}]="true".',
-            preferFalse: 'Avoid binding [{{attr}}]="false"; remove the binding or ensure default is false.',
             suggestTrue: 'Replace with attribute shorthand {{attr}}',
-            suggestRemove: 'Remove the false binding',
         },
     },
-    defaultOptions: [
-        {
-            allowFalseLiteral: false,
-        },
-    ],
+    defaultOptions: [],
     create(context) {
-        // Robust to missing options: default to [{}] if undefined
-        const optionsArr = context.options ?? [{}];
-        const options = optionsArr[0] ?? {};
-        const allowFalseLiteral = options.allowFalseLiteral ?? false;
         const parserServices = (0, utils_1.getTemplateParserServices)(context);
         return {
             BoundAttribute(node) {
@@ -43,12 +45,14 @@ exports.preferBooleanAttributeShorthandRule = {
                 if (!value || !value.ast)
                     return;
                 const ast = value.ast;
+                // Only check for boolean literals
                 if (ast?.constructor?.name === 'LiteralPrimitive' && typeof ast.value === 'boolean') {
-                    const attrName = node.name;
-                    const loc = parserServices.convertNodeSourceSpanToLoc(node.sourceSpan);
-                    const start = node.sourceSpan.start.offset;
-                    const end = node.sourceSpan.end.offset;
+                    // Only warn for [attr]="true", ignore [attr]="false"
                     if (ast.value === true) {
+                        const attrName = node.name;
+                        const loc = parserServices.convertNodeSourceSpanToLoc(node.sourceSpan);
+                        const start = node.sourceSpan.start.offset;
+                        const end = node.sourceSpan.end.offset;
                         context.report({
                             loc,
                             messageId: 'preferTrue',
@@ -62,20 +66,7 @@ exports.preferBooleanAttributeShorthandRule = {
                             ],
                         });
                     }
-                    else if (ast.value === false && !allowFalseLiteral) {
-                        context.report({
-                            loc,
-                            messageId: 'preferFalse',
-                            data: { attr: attrName },
-                            suggest: [
-                                {
-                                    messageId: 'suggestRemove',
-                                    data: { attr: attrName },
-                                    fix: (fixer) => fixer.replaceTextRange([start, end], ''),
-                                },
-                            ],
-                        });
-                    }
+                    // [attr]="false" is explicitly ignored - no warning
                 }
             },
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yoo-digital/eslint-plugin-angular",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Yoo Digital custom Angular ESLint plugin providing prefer-boolean-attribute-shorthand rule.",
   "type": "commonjs",
   "main": "dist/index.js",