@ng-zen/cli 20.0.0 → 20.1.0-next.1

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [20.1.0-next.1](https://github.com/kstepien3/ng-zen/compare/v20.0.0...v20.1.0-next.1) (2025-07-30)
+
+### 🚀 New Features
+
+* **checkbox:** add indeterminate state if value is null ([#260](https://github.com/kstepien3/ng-zen/issues/260)) ([d13c241](https://github.com/kstepien3/ng-zen/commit/d13c2416984df1de188082760aadfe280c7ed315))
+* **form-control:** add abstract logic for form control components ([#252](https://github.com/kstepien3/ng-zen/issues/252)) ([10e66b4](https://github.com/kstepien3/ng-zen/commit/10e66b4b0606a05d02ba527de42407129e085cbe))
+
 ## [20.0.0](https://github.com/kstepien3/ng-zen/compare/v19.4.0...v20.0.0) (2025-07-22)
 
 ### ⚠ BREAKING CHANGES

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ng-zen/cli",
-  "version": "20.0.0",
+  "version": "20.1.0-next.1",
   "description": "A CLI tool for generating customizable, modern Angular UI components using schematics.",
   "license": "BSD-2-Clause",
   "private": false,

package/schematics/components/components-generator.js.map

@@ -1 +1 @@
-{"version":3,"file":"components-generator.js","sourceRoot":"","sources":["../../../../../src/schematics/components/components-generator.ts"],"names":[],"mappings":"","sourcesContent":["import { GeneratorSchemaBase } from '../../types';\n\nexport type ComponentType =\n  | 'avatar'\n  | 'button'\n  | 'checkbox'\n  | 'divider'\n  | 'icon'\n  | 'input'\n  | 'skeleton'\n  | 'switch'\n  | 'textarea';\n\nexport interface ComponentGeneratorSchema extends GeneratorSchemaBase {\n  components: ComponentType[];\n}\n"]}
+{"version":3,"file":"components-generator.js","sourceRoot":"","sources":["../../../../../src/schematics/components/components-generator.ts"],"names":[],"mappings":"","sourcesContent":["import { GeneratorSchemaBase } from '../../types';\n\nexport type ComponentType =\n  | 'avatar'\n  | 'button'\n  | 'checkbox'\n  | 'divider'\n  | 'form-control'\n  | 'icon'\n  | 'input'\n  | 'skeleton'\n  | 'switch'\n  | 'textarea';\n\nexport interface ComponentGeneratorSchema extends GeneratorSchemaBase {\n  components: ComponentType[];\n}\n"]}

package/schematics/components/components-generator.ts

@@ -5,6 +5,7 @@ export type ComponentType =
   | 'button'
   | 'checkbox'
   | 'divider'
+  | 'form-control'
   | 'icon'
   | 'input'
   | 'skeleton'

package/schematics/components/files/checkbox/checkbox.stories.ts

@@ -7,16 +7,17 @@ export default {
   component: ZenCheckbox,
   tags: ['autodocs'],
   argTypes: {
-    value: { control: 'boolean' },
+    value: {
+      control: 'radio',
+      options: [true, false, null],
+    },
     disabled: { control: 'boolean' },
     required: { control: 'boolean' },
-    id: { control: 'text' },
   },
   args: {
     value: false,
     disabled: false,
     required: false,
-    id: '',
   },
 } satisfies Meta<ZenCheckbox>;
 
@@ -29,7 +30,6 @@ export const Default: Story = {
       <zen-checkbox
         [disabled]="${args.disabled}"
         [value]="${args.value}"
-        ${args.id ? 'id="' + args.id + '"' : ''}
         ${args.required ? 'required' : ''}
       />`,
   }),

package/schematics/components/files/checkbox/checkbox.ts

@@ -1,5 +1,7 @@
-import { booleanAttribute, ChangeDetectionStrategy, Component, forwardRef, input, model } from '@angular/core';
-import { ControlValueAccessor, FormsModule, NG_VALUE_ACCESSOR } from '@angular/forms';
+import { ChangeDetectionStrategy, Component, effect, ElementRef, model, viewChild } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+
+import { ZenFormControl, ZenFormControlProvider } from '../form-control';
 
 /**
  * ZenCheckbox is a reusable checkbox component designed to provide
@@ -8,7 +10,9 @@ import { ControlValueAccessor, FormsModule, NG_VALUE_ACCESSOR } from '@angular/f
  * for boolean values.
  *
  * @example
- * <zen-checkbox value="false" />
+ * <zen-checkbox [value]="true" /> Checked
+ * <zen-checkbox [value]="false" /> Unchecked
+ * <zen-checkbox [value]="null" /> Indeterminate
  *
  * ### CSS Custom Properties
  *
@@ -25,7 +29,7 @@ import { ControlValueAccessor, FormsModule, NG_VALUE_ACCESSOR } from '@angular/f
  * }
  * ```
  *
- * @implements {ControlValueAccessor}
+ * @implements {ZenFormControl<boolean>}
  *
  * @author Konrad Stępień
  * @license {@link https://github.com/kstepien3/ng-zen/blob/master/LICENSE|BSD-2-Clause}
@@ -37,10 +41,9 @@ import { ControlValueAccessor, FormsModule, NG_VALUE_ACCESSOR } from '@angular/f
   template: `
     <input
       [attr.aria-disabled]="disabled()"
-      [attr.id]="id()"
       [disabled]="disabled()"
       [ngModel]="value()"
-      (ngModelChange)="onInputChange($event)"
+      (ngModelChange)="onInput($event)"
       #inputElement
       type="checkbox"
     />
@@ -54,59 +57,25 @@ import { ControlValueAccessor, FormsModule, NG_VALUE_ACCESSOR } from '@angular/f
   styleUrls: ['./checkbox.scss'],
   changeDetection: ChangeDetectionStrategy.OnPush,
   imports: [FormsModule],
-  providers: [
-    {
-      provide: NG_VALUE_ACCESSOR,
-      useExisting: forwardRef(() => ZenCheckbox),
-      multi: true,
-    },
-  ],
+  providers: [ZenFormControlProvider(ZenCheckbox)],
   host: {
     '(blur)': 'onTouched()',
   },
 })
-export class ZenCheckbox implements ControlValueAccessor {
-  /** Holds the current checkbox value. */
-  readonly value = model(false);
-  /** Determines if the checkbox is disabled. */
-  readonly disabled = model(false);
-  /** Determines if the input is required.*/
-  readonly required = input(false, { transform: booleanAttribute });
-  /** Sets the HTML id attribute for the checkbox element. */
-  readonly id = input<string>();
-
-  /** @ignore */
-  // eslint-disable-next-line @typescript-eslint/no-empty-function
-  onChange: (value: boolean) => void = () => {};
-  /** @ignore */
-  // eslint-disable-next-line @typescript-eslint/no-empty-function
-  onTouched: () => void = () => {};
-
-  /** @ignore */
-  writeValue(value: boolean): void {
-    this.value.set(value);
-  }
-
+export class ZenCheckbox extends ZenFormControl<boolean | null> {
+  /**
+   * Holds the current checkbox value.
+   * Set value to `null` to mark the checkbox as indeterminate
+   */
+  readonly value = model<boolean | null>(false);
   /** @ignore */
-  registerOnChange(fn: (value: boolean) => void): void {
-    this.onChange = fn;
-  }
-
-  /** @ignore */
-  registerOnTouched(fn: () => void): void {
-    this.onTouched = fn;
-  }
-
-  /** @ignore */
-  setDisabledState(isDisabled: boolean): void {
-    this.disabled.set(isDisabled);
-  }
+  private readonly inputElement = viewChild.required<ElementRef<HTMLInputElement>>('inputElement');
 
-  /** Handles checkbox change event */
-  onInputChange(value: boolean): void {
-    if (this.disabled()) return;
+  constructor() {
+    super();
 
-    this.value.set(value);
-    this.onChange(value);
+    effect(() => {
+      if (this.value() === null) this.inputElement().nativeElement.indeterminate = true;
+    });
   }
 }

package/schematics/components/files/form-control/form-control.spec.ts

@@ -0,0 +1,31 @@
+import { Component, model } from '@angular/core';
+import { ComponentFixture, TestBed } from '@angular/core/testing';
+
+import { ZenFormControl, ZenFormControlProvider } from './form-control';
+
+@Component({
+  template: '...',
+  providers: [ZenFormControlProvider(FormControl)],
+})
+class FormControl extends ZenFormControl<string> {
+  readonly value = model<string>('');
+}
+
+describe('FormControl', () => {
+  let component: FormControl;
+  let fixture: ComponentFixture<FormControl>;
+
+  beforeEach(async () => {
+    await TestBed.configureTestingModule({
+      imports: [FormControl],
+    }).compileComponents();
+
+    fixture = TestBed.createComponent(FormControl);
+    component = fixture.componentInstance;
+    fixture.detectChanges();
+  });
+
+  it('should create', () => {
+    expect(component).toBeTruthy();
+  });
+});

package/schematics/components/files/form-control/form-control.stories.ts

@@ -0,0 +1,37 @@
+import { Meta, moduleMetadata } from '@storybook/angular';
+
+import { ZenCheckbox } from '../checkbox';
+import { ZenInput } from '../input';
+import { ZenSwitch } from '../switch';
+import { ZenFormControl } from './form-control';
+
+export default {
+  title: 'Components/FormControl',
+  component: ZenFormControl,
+  tags: ['autodocs'],
+  decorators: [moduleMetadata({ imports: [ZenCheckbox, ZenInput, ZenSwitch] })],
+  args: {
+    value: '',
+    disabled: false,
+    required: false,
+  },
+  argTypes: {
+    value: { control: false },
+    placeholder: { control: false },
+    disabled: { control: 'boolean' },
+    required: { control: 'boolean' },
+  },
+  parameters: {
+    docs: {
+      canvas: {
+        // This will remove the "show code" button
+        // https://storybook.js.org/docs/api/doc-blocks/doc-block-canvas#sourcestate
+        sourceState: 'none',
+      },
+    },
+  },
+} satisfies Meta<ZenFormControl<unknown>>;
+
+export { Default as Checkbox } from '../checkbox/checkbox.stories';
+export { Default as Input } from '../input/input.stories';
+export { Default as Switch } from '../switch/switch.stories';

package/schematics/components/files/form-control/form-control.ts

@@ -0,0 +1,116 @@
+import { booleanAttribute, Directive, forwardRef, input, model, ModelSignal, Type } from '@angular/core';
+import { ControlValueAccessor, NG_VALUE_ACCESSOR } from '@angular/forms';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const ZenFormControlProvider = <T extends ZenFormControl<any>>(component: Type<T>) => ({
+  provide: NG_VALUE_ACCESSOR,
+  useExisting: forwardRef(() => component),
+  multi: true,
+});
+
+/**
+ * A base class for creating custom Angular form controls that integrate with both
+ * template-driven and reactive forms. It simplifies the implementation of the
+ * ControlValueAccessor interface by using signals for the control's value and state.
+ *
+ * Subclasses must provide an implementation for the abstract `value` property.
+ *
+ * @example
+ *
+ * ```ts
+ * @Component({
+ *   template: '...',
+ *   providers: [ZenFormControlProvider(ZenInput)]
+ * })
+ * export class Input extends ZenFormControl<string> {
+ *   readonly value = model<string>('')
+ * }
+ * ```
+ *
+ * @implements {ControlValueAccessor}
+ *
+ * @author Konrad Stępień
+ * @license {@link https://github.com/kstepien3/ng-zen/blob/master/LICENSE|BSD-2-Clause}
+ * @see [GitHub](https://github.com/kstepien3/ng-zen)
+ */
+@Directive({})
+export abstract class ZenFormControl<Value> implements ControlValueAccessor {
+  /**
+   * The underlying value of the control.
+   * Subclasses must provide their own implementation, typically using `model()`.
+   */
+  abstract readonly value: ModelSignal<Value>;
+
+  /** The placeholder text for the form control. */
+  readonly placeholder = input<string>();
+
+  /**
+   * Whether the form control is disabled.
+   */
+  readonly disabled = model(false);
+
+  /** Whether the form control is required. */
+  readonly required = input(false, { transform: booleanAttribute });
+
+  /**
+   * @internal For internal use by Angular forms.
+   * @ignore
+   */
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  onChange: (value: Value) => void = () => {};
+
+  /**
+   * @internal For internal use by Angular forms.
+   * @ignore
+   */
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  onTouched: () => void = () => {};
+
+  /**
+   * Should be called by the subclass when the control's value changes
+   * as a result of user interaction. This method updates the control's value
+   * and notifies Angular of the change.
+   */
+  onInput(value: Value): void {
+    if (this.disabled()) return;
+
+    this.value.set(value);
+    this.onChange(this.value());
+  }
+
+  /**
+   * Writes a new value to the element.
+   * @internal For internal use by Angular forms.
+   * @ignore
+   */
+  writeValue(value: Value): void {
+    this.value.set(value);
+  }
+
+  /**
+   * Registers a callback function that is called when the control's value changes in the UI.
+   * @internal For internal use by Angular forms.
+   * @ignore
+   */
+  registerOnChange(fn: (value: Value) => void): void {
+    this.onChange = fn;
+  }
+
+  /**
+   * Registers a callback function that is called by the forms API on component touch.
+   * @internal For internal use by Angular forms.
+   * @ignore
+   */
+  registerOnTouched(fn: () => void): void {
+    this.onTouched = fn;
+  }
+
+  /**
+   * This function is called by the forms API when the control status changes to or from "DISABLED".
+   * @internal For internal use by Angular forms.
+   * @ignore
+   */
+  setDisabledState(isDisabled: boolean): void {
+    this.disabled.set(isDisabled);
+  }
+}

package/schematics/components/files/form-control/index.ts

@@ -0,0 +1 @@
+export * from './form-control';

package/schematics/components/files/input/input.stories.ts

@@ -11,14 +11,12 @@ export default {
     placeholder: { control: 'text' },
     disabled: { control: 'boolean' },
     required: { control: 'boolean' },
-    id: { control: 'text' },
   },
   args: {
     value: '',
     placeholder: '',
     disabled: false,
     required: false,
-    id: '',
   },
 } satisfies Meta<ZenInput>;
 
@@ -31,7 +29,6 @@ export const Default: Story = {
       <zen-input
         [disabled]="${args.disabled}"
         [value]="'${args.value}'"
-        ${args.id ? 'id="' + args.id + '"' : ''}
         ${args.placeholder ? 'placeholder="' + args.placeholder + '"' : ''}
         ${args.required ? 'required' : ''}
       />`,

package/schematics/components/files/input/input.ts

@@ -1,5 +1,7 @@
-import { booleanAttribute, ChangeDetectionStrategy, Component, forwardRef, input, model } from '@angular/core';
-import { ControlValueAccessor, FormsModule, NG_VALUE_ACCESSOR } from '@angular/forms';
+import { ChangeDetectionStrategy, Component, model } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+
+import { ZenFormControl, ZenFormControlProvider } from '../form-control/form-control';
 
 /**
  * ZenInput is a reusable text input component designed to provide
@@ -22,7 +24,7 @@ import { ControlValueAccessor, FormsModule, NG_VALUE_ACCESSOR } from '@angular/f
  * }
  * ```
  *
- * @implements {ControlValueAccessor}
+ * @implements {ZenFormControl<string>}
  *
  * @author Konrad Stępień
  * @license {@link https://github.com/kstepien3/ng-zen/blob/master/LICENSE|BSD-2-Clause}
@@ -33,69 +35,20 @@ import { ControlValueAccessor, FormsModule, NG_VALUE_ACCESSOR } from '@angular/f
   standalone: true,
   template: `
     <input
-      [attr.id]="id()"
       [attr.placeholder]="placeholder()"
       [attr.required]="required()"
       [disabled]="disabled()"
       [ngModel]="value()"
       [value]="value()"
       (blur)="onTouched()"
-      (ngModelChange)="onInputChange($event)"
+      (ngModelChange)="onInput($event)"
     />
   `,
   styleUrls: ['./input.scss'],
   changeDetection: ChangeDetectionStrategy.OnPush,
-  providers: [
-    {
-      provide: NG_VALUE_ACCESSOR,
-      useExisting: forwardRef(() => ZenInput),
-      multi: true,
-    },
-  ],
+  providers: [ZenFormControlProvider(ZenInput)],
   imports: [FormsModule],
 })
-export class ZenInput implements ControlValueAccessor {
-  /** Holds the current input value. */
+export class ZenInput extends ZenFormControl<string> {
   readonly value = model('');
-  /** Determines if the input is disabled. */
-  readonly disabled = model(false);
-  /** Determines if the input is required.*/
-  readonly required = input(false, { transform: booleanAttribute });
-  /** Sets the HTML id attribute for the input element.*/
-  readonly id = input<string>();
-  /** Provides a hint or example text that will be displayed */
-  readonly placeholder = input<string>();
-
-  /** @ignore */
-  // eslint-disable-next-line @typescript-eslint/no-empty-function
-  onChange: (value: string) => void = () => {};
-  /** @ignore */
-  // eslint-disable-next-line @typescript-eslint/no-empty-function
-  onTouched: () => void = () => {};
-
-  /** @ignore */
-  writeValue(value: string): void {
-    this.value.set(value);
-  }
-  /** @ignore */
-  registerOnChange(fn: (value: string) => void): void {
-    this.onChange = fn;
-  }
-  /** @ignore */
-  registerOnTouched(fn: () => void): void {
-    this.onTouched = fn;
-  }
-
-  /** @ignore */
-  setDisabledState(isDisabled: boolean): void {
-    this.disabled.set(isDisabled);
-  }
-
-  /** Handles input change event */
-  onInputChange(value: string): void {
-    if (this.disabled()) return;
-
-    this.value.set(value);
-    this.onChange(value);
-  }
 }

package/schematics/components/files/switch/switch.ts

@@ -1,5 +1,6 @@
-import { ChangeDetectionStrategy, Component, forwardRef, model } from '@angular/core';
-import { ControlValueAccessor, NG_VALUE_ACCESSOR } from '@angular/forms';
+import { ChangeDetectionStrategy, Component, model } from '@angular/core';
+
+import { ZenFormControl, ZenFormControlProvider } from '../form-control';
 
 /**
  * ZenInput is a reusable text input component designed to provide
@@ -25,7 +26,7 @@ import { ControlValueAccessor, NG_VALUE_ACCESSOR } from '@angular/forms';
  * }
  * ```
  *
- * @implements {ControlValueAccessor}
+ * @implements {ZenFormControl<boolean>}
  *
  * @author Konrad Stępień
  * @license {@link https://github.com/kstepien3/ng-zen/blob/master/LICENSE|BSD-2-Clause}
@@ -41,75 +42,19 @@ import { ControlValueAccessor, NG_VALUE_ACCESSOR } from '@angular/forms';
   `,
   styleUrl: './switch.scss',
   changeDetection: ChangeDetectionStrategy.OnPush,
-  providers: [
-    {
-      provide: NG_VALUE_ACCESSOR,
-      useExisting: forwardRef(() => ZenSwitch),
-      multi: true,
-    },
-  ],
+  providers: [ZenFormControlProvider(ZenSwitch)],
   host: {
     tabindex: '0',
     '[attr.data-disabled]': 'disabled()',
     '[attr.data-checked]': 'value()',
     '(blur)': 'onTouched()',
-    '(click)': 'onInputChange(!this.value())',
+    '(click)': 'onInput(!this.value())',
     '(keydown)': 'onKeyDown($event)',
   },
 })
-export class ZenSwitch implements ControlValueAccessor {
+export class ZenSwitch extends ZenFormControl<boolean> {
   /** Holds the current checkbox value. */
   readonly value = model(false);
-  /** Determines if the checkbox is disabled. */
-  readonly disabled = model(false);
-
-  /** @ignore */
-  // eslint-disable-next-line @typescript-eslint/no-empty-function
-  onChange: (value: boolean) => void = () => {};
-  /** @ignore */
-  // eslint-disable-next-line @typescript-eslint/no-empty-function
-  onTouched: () => void = () => {};
-  /**
-   * Writes a new value to the component.
-   * @ignore
-   */
-  writeValue(value: boolean): void {
-    this.value.set(value);
-  }
-
-  /**
-   * Registers a function to be called when the value changes.
-   * @ignore
-   */
-  registerOnChange(fn: (value: boolean) => void): void {
-    this.onChange = fn;
-  }
-
-  /**
-   * Registers a function to be called when the component is touched.
-   * @ignore
-   */
-  registerOnTouched(fn: () => void): void {
-    this.onTouched = fn;
-  }
-
-  /**
-   * Sets the disabled state of the component.
-   * @ignore
-   */
-  setDisabledState(isDisabled: boolean): void {
-    this.disabled.set(isDisabled);
-  }
-
-  /**
-   * Toggles the switch value and notifies the change.
-   */
-  onInputChange(value: boolean): void {
-    if (this.disabled()) return;
-
-    this.writeValue(value);
-    this.onChange(value);
-  }
 
   /**
    * Handles keyboard events for accessibility.
@@ -119,15 +64,15 @@ export class ZenSwitch implements ControlValueAccessor {
       case 'Enter':
       case 'Space': {
         event.preventDefault();
-        this.onInputChange(!this.value());
+        this.onInput(!this.value());
         break;
       }
       case 'ArrowRight': {
-        this.onInputChange(true);
+        this.onInput(true);
         break;
       }
       case 'ArrowLeft': {
-        this.onInputChange(false);
+        this.onInput(false);
         break;
       }
     }

package/schematics/components/schema.json

@@ -10,7 +10,18 @@
       "type": "array",
       "items": {
         "type": "string",
-        "enum": ["avatar", "button", "checkbox", "divider", "icon", "input", "skeleton", "switch", "textarea"]
+        "enum": [
+          "avatar",
+          "button",
+          "checkbox",
+          "divider",
+          "form-control",
+          "icon",
+          "input",
+          "skeleton",
+          "switch",
+          "textarea"
+        ]
       },
       "multiselect": true,
       "x-prompt": "Which component should be generated?"