@ng-zen/cli 22.9.0-next.1 → 22.10.0-next.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ng-zen/cli",
-  "version": "22.9.0-next.1",
+  "version": "22.10.0-next.1",
   "description": "Angular CLI generator for creating fully customizable UI components.",
   "license": "BSD-2-Clause",
   "private": false,
@@ -61,8 +61,10 @@
     "divider",
     "drawer",
     "form-control",
+    "hint",
     "icon",
     "input",
+    "label",
     "pin",
     "popover",
     "radio",

package/schematics/ui/files/checkbox/checkbox.html

@@ -0,0 +1,36 @@
+<input
+  #inputElement
+  type="checkbox"
+  [attr.aria-disabled]="disabled()"
+  [attr.aria-invalid]="invalid() || null"
+  [checked]="value()"
+  [disabled]="disabled()"
+  [id]="id()"
+  (change)="onInput(inputElement.checked)"
+/>
+<span aria-hidden="true" class="symbol">
+  @if (value() === null) {
+    ─
+  } @else if (value()) {
+    ✓
+  }
+  <!-- @else { ✕ } -->
+</span>
+@if (label()) {
+  <zen-label [disabled]="disabled()" [for]="id()" [required]="required()">{{ label() }}</zen-label>
+}
+@if (shouldShowError()) {
+  @for (error of errors(); track $index) {
+    <zen-hint severity="error">
+      @if (errorTemplate()) {
+        <ng-container *ngTemplateOutlet="errorTemplate()!; context: { $implicit: error }" />
+      } @else {
+        {{ error.message }}
+      }
+    </zen-hint>
+  }
+} @else if (warn()) {
+  <zen-hint severity="warning">{{ warn() }}</zen-hint>
+} @else if (hint()) {
+  <zen-hint>{{ hint() }}</zen-hint>
+}

package/schematics/ui/files/checkbox/checkbox.scss

@@ -12,58 +12,81 @@ $disabled-opacity: var(--zen-disabled-opacity, 0.6);
   --zen-checkbox-border: 1px solid hsl(0deg 0% 80%);
 }
 
-input {
-  position: absolute;
-  cursor: pointer;
-  opacity: 0;
-  height: 100%;
-  width: 100%;
-  padding: 0;
-  margin: 0;
-  top: 0;
-  left: 0;
-}
-
 /* stylelint-disable-next-line no-duplicate-selectors -- separate variables and styles */
 :host {
+  display: inline-grid;
+  grid-template-columns: var(--zen-checkbox-size) 1fr;
+  gap: 0.25rem 0.5rem;
+  align-items: center;
+
+  &:has(input[type='checkbox']:disabled) {
+    opacity: $disabled-opacity;
+
+    &,
+    input,
+    label {
+      cursor: not-allowed;
+    }
+  }
+}
+
+input[type='checkbox'] {
+  appearance: none;
+  grid-column: 1;
+  grid-row: 1;
   border: var(--zen-checkbox-border);
   border-radius: var(--zen-checkbox-border-radius);
   height: var(--zen-checkbox-size);
   width: var(--zen-checkbox-size);
   background-color: white;
   cursor: pointer;
-  position: relative;
+  margin: 0;
+  padding: 0;
   transition:
     background-color ease,
     border-color ease;
   transition-duration: $transition-duration;
-  user-select: none;
-  justify-content: center;
-  display: grid;
-  place-items: center;
-  font-size: small;
 
-  &:has(input:checked) {
-    color: white;
+  &:checked,
+  &:indeterminate {
     background-color: var(--zen-checkbox-appearance);
     border-color: var(--zen-checkbox-appearance);
   }
 
-  &:has(input[type='checkbox']:disabled) {
-    opacity: $disabled-opacity;
-
-    &,
-    input {
-      cursor: not-allowed;
-    }
-  }
-
-  &:has(input:focus-visible) {
+  &:focus-visible {
     outline: $outline;
     box-shadow: $focus-shadow;
   }
 
-  &:has(input:user-invalid) {
+  &:user-invalid {
     border-color: $error;
   }
 }
+
+zen-label {
+  grid-column: 2;
+  grid-row: 1;
+}
+
+zen-hint {
+  grid-column: 1 / -1;
+}
+
+.symbol {
+  grid-column: 1;
+  grid-row: 1;
+  place-self: center center;
+  pointer-events: none;
+  font-size: small;
+  line-height: 1;
+  color: white;
+  user-select: none;
+
+  &:empty {
+    display: none;
+  }
+}
+
+input[type='checkbox']:not(:checked, :indeterminate) ~ .symbol {
+  color: var(--zen-checkbox-appearance);
+}

package/schematics/ui/files/checkbox/checkbox.spec.ts

@@ -1,13 +1,38 @@
-import { provideZonelessChangeDetection } from '@angular/core';
+import { Component, provideZonelessChangeDetection, signal } from '@angular/core';
 import { TestBed } from '@angular/core/testing';
+import type { ValidationError } from '@angular/forms/signals';
 import { beforeEach, describe, expect, it } from 'vitest';
 
 import { ZenCheckbox } from './checkbox';
 
+@Component({
+  imports: [ZenCheckbox],
+  template: `
+    <zen-checkbox
+      [errors]="errors()"
+      [hint]="hint()"
+      [invalid]="invalid()"
+      [label]="label()"
+      [required]="required()"
+      [touched]="touched()"
+      [warn]="warn()"
+    />
+  `,
+})
+class TestCheckboxHostComponent {
+  readonly label = signal('');
+  readonly hint = signal('');
+  readonly warn = signal('');
+  readonly invalid = signal(false);
+  readonly touched = signal(false);
+  readonly required = signal(false);
+  readonly errors = signal<ValidationError.WithOptionalFieldTree[]>([]);
+}
+
 describe('ZenCheckbox', () => {
   beforeEach(async () => {
     await TestBed.configureTestingModule({
-      imports: [ZenCheckbox],
+      imports: [ZenCheckbox, TestCheckboxHostComponent],
       providers: [provideZonelessChangeDetection()],
     }).compileComponents();
   });
@@ -17,4 +42,71 @@ describe('ZenCheckbox', () => {
     const component = fixture.componentInstance;
     expect(component).toBeTruthy();
   });
+
+  it('should render label linked to checkbox id and handle required state', () => {
+    const fixture = TestBed.createComponent(TestCheckboxHostComponent);
+    fixture.componentInstance.label.set('Accept terms');
+    fixture.detectChanges();
+
+    const labelEl = fixture.nativeElement.querySelector('label') as HTMLLabelElement;
+    const inputEl = fixture.nativeElement.querySelector('input') as HTMLInputElement;
+
+    expect(labelEl).toBeTruthy();
+    expect(labelEl.textContent?.trim()).toBe('Accept terms');
+    expect(labelEl.getAttribute('for')).toBe(inputEl.id);
+
+    fixture.componentInstance.required.set(true);
+    fixture.detectChanges();
+
+    const requiredSpan = fixture.nativeElement.querySelector('zen-label .required');
+    expect(requiredSpan).toBeTruthy();
+    expect(requiredSpan.textContent).toBe('*');
+  });
+
+  it('should handle indeterminate state and display indeterminate symbol', () => {
+    const fixture = TestBed.createComponent(ZenCheckbox);
+    fixture.componentRef.setInput('value', null);
+    fixture.detectChanges();
+
+    const inputEl = fixture.nativeElement.querySelector('input') as HTMLInputElement;
+    expect(inputEl.indeterminate).toBe(true);
+
+    const symbolEl = fixture.nativeElement.querySelector('.symbol');
+    expect(symbolEl?.textContent?.trim()).toBe('─');
+  });
+
+  it('should reset indeterminate state when value changes to boolean', () => {
+    const fixture = TestBed.createComponent(ZenCheckbox);
+    fixture.componentRef.setInput('value', null);
+    fixture.detectChanges();
+
+    const inputEl = fixture.nativeElement.querySelector('input') as HTMLInputElement;
+    expect(inputEl.indeterminate).toBe(true);
+
+    fixture.componentRef.setInput('value', true);
+    fixture.detectChanges();
+    expect(inputEl.indeterminate).toBe(false);
+  });
+
+  it('should display checkmark symbol when checked', () => {
+    const fixture = TestBed.createComponent(ZenCheckbox);
+    fixture.componentRef.setInput('value', true);
+    fixture.detectChanges();
+
+    const symbolEl = fixture.nativeElement.querySelector('.symbol');
+    expect(symbolEl?.textContent?.trim()).toBe('✓');
+  });
+
+  it('should render errors when invalid and touched', () => {
+    const fixture = TestBed.createComponent(TestCheckboxHostComponent);
+    fixture.componentInstance.invalid.set(true);
+    fixture.componentInstance.touched.set(true);
+    fixture.componentInstance.errors.set([{ kind: 'required', message: 'Agreement is required' }]);
+    fixture.detectChanges();
+
+    const hintEl = fixture.nativeElement.querySelector('zen-hint');
+    expect(hintEl).toBeTruthy();
+    expect(hintEl.getAttribute('data-severity')).toBe('error');
+    expect(hintEl.textContent?.trim()).toBe('Agreement is required');
+  });
 });

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

@@ -40,13 +40,12 @@ type Story = StoryObj<Options>;
 export const Default: Story = {};
 
 export const WithLabel: Story = {
-  render: () => ({
-    template: `
-      <div style="display: flex; align-items: center; gap: 0.25rem">
-        <zen-checkbox id="label-example"/>
-        <label for="label-example"> With label </label>
-      </div>
-  `,
+  args: {
+    label: 'I agree to the terms and conditions',
+  },
+  render: args => ({
+    props: args,
+    template: '<zen-checkbox [label]="label" />',
   }),
 };
 
@@ -59,18 +58,7 @@ export const WithSignalForm: Story = {
   parameters: {
     docs: {
       source: {
-        code: `
-    <div style="display: flex; flex-direction: column; gap: 0.5rem;">
-      <div style="display: flex; align-items: center; gap: 0.25rem">
-        <zen-checkbox id="agree" [formField]="form.agree" />
-        <label for="agree">I agree to the terms</label>
-      </div>
-      @if (form.agree().invalid()) {
-        <p style="color: red; margin: 0; font-size: 0.875rem;">
-          {{ form.agree().errors()![0].message }}
-        </p>
-      }
-    </div>`,
+        code: `<zen-checkbox label="I agree to the terms" [formField]="form.agree" />`,
       },
     },
   },
@@ -80,15 +68,7 @@ export const WithSignalForm: Story = {
   standalone: true,
   template: `
     <div style="display: flex; flex-direction: column; gap: 0.5rem;">
-      <div style="display: flex; align-items: center; gap: 0.25rem">
-        <zen-checkbox id="agree" [formField]="form.agree" />
-        <label for="agree">I agree to the terms</label>
-      </div>
-      @if (form.agree().invalid()) {
-        <p style="color: red; margin: 0; font-size: 0.875rem;">
-          {{ form.agree().errors()![0].message }}
-        </p>
-      }
+      <zen-checkbox label="I agree to the terms" [formField]="form.agree" />
     </div>
   `,
   imports: [FormField, ZenCheckbox],

package/schematics/ui/files/checkbox/checkbox.ts

@@ -1,6 +1,9 @@
+import { NgTemplateOutlet } from '@angular/common';
 import { Component, effect, ElementRef, model, viewChild } from '@angular/core';
 
 import { ZenFormControl } from '../form-control';
+import { ZenHint } from '../hint';
+import { ZenLabel } from '../label';
 
 /**
  * ZenCheckbox is a checkbox component supporting checked (`true`),
@@ -9,8 +12,7 @@ import { ZenFormControl } from '../form-control';
  * Connect it to a Signal Forms field with `[formField]`:
  *
  * ```html
- * <zen-checkbox [formField]="myForm.agree" />
- * <label for="agree">I agree to the terms</label>
+ * <zen-checkbox [formField]="myForm.agree" label="I agree to the terms" />
  * ```
  *
  * When `value` is `null` the native checkbox is set to indeterminate via
@@ -37,24 +39,9 @@ import { ZenFormControl } from '../form-control';
  */
 @Component({
   selector: 'zen-checkbox',
-  template: `
-    <input
-      #inputElement
-      type="checkbox"
-      [attr.aria-disabled]="disabled()"
-      [attr.aria-invalid]="invalid() || null"
-      [checked]="value()"
-      [disabled]="disabled()"
-      (change)="onInput(inputElement.checked)"
-    />
-    @if (inputElement.indeterminate) {
-      ─
-    } @else if (inputElement.checked) {
-      ✓
-    }
-    <!-- @else { ✕ } -->
-  `,
-  styleUrls: ['./checkbox.scss'],
+  imports: [NgTemplateOutlet, ZenHint, ZenLabel],
+  templateUrl: './checkbox.html',
+  styleUrl: './checkbox.scss',
 })
 export class ZenCheckbox extends ZenFormControl<boolean | null> {
   /**
@@ -68,7 +55,7 @@ export class ZenCheckbox extends ZenFormControl<boolean | null> {
     super();
 
     effect(() => {
-      if (this.value() === null) this.inputElement().nativeElement.indeterminate = true;
+      this.inputElement().nativeElement.indeterminate = this.value() === null;
     });
   }
 }

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

@@ -38,6 +38,23 @@ describe('FormControl', () => {
     expect(component.readonly()).toBe(false);
     expect(component.name()).toBe('');
     expect(component.errors()).toEqual([]);
-    expect(component.disabledReasons()).toEqual([]);
+    expect(component.label()).toBe('');
+    expect(component.hint()).toBe('');
+    expect(component.warn()).toBe('');
+    expect(component.id()).toMatch(/^zen-control-\d+$/);
+  });
+
+  it('should compute shouldShowError based on invalid, touched/dirty, and errors', () => {
+    const fixture = TestBed.createComponent(TestFormControl);
+    const component = fixture.componentInstance;
+    expect(component.shouldShowError()).toBe(false);
+
+    fixture.componentRef.setInput('invalid', true);
+    fixture.componentRef.setInput('touched', true);
+    fixture.componentRef.setInput('errors', [{ message: 'Required' }]);
+    expect(component.shouldShowError()).toBe(true);
+
+    fixture.componentRef.setInput('errors', []);
+    expect(component.shouldShowError()).toBe(false);
   });
 });

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

@@ -53,14 +53,26 @@ export default {
       control: 'text' as const,
       table: { category: 'models', type: { summary: 'string' } },
     },
+    label: {
+      control: 'text' as const,
+      table: { category: 'inputs', type: { summary: 'string' } },
+    },
+    hint: {
+      control: 'text' as const,
+      table: { category: 'inputs', type: { summary: 'string' } },
+    },
+    warn: {
+      control: 'text' as const,
+      table: { category: 'inputs', type: { summary: 'string' } },
+    },
+    id: {
+      control: 'text' as const,
+      table: { category: 'inputs', type: { summary: 'string' } },
+    },
     errors: {
       control: false as const,
       table: { category: 'models', type: { summary: 'ValidationError[]' }, readonly: true },
     },
-    disabledReasons: {
-      control: false as const,
-      table: { category: 'models', type: { summary: 'DisabledReason[]' }, readonly: true },
-    },
     value: {
       control: false as const,
       table: {
@@ -87,6 +99,9 @@ export default {
     readonly: false,
     name: '',
     value: '',
+    label: '',
+    hint: '',
+    warn: '',
   },
   parameters: {
     docs: {

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

@@ -1,5 +1,14 @@
-import { booleanAttribute, Directive, input, ModelSignal, output } from '@angular/core';
-import type { DisabledReason, ValidationError, WithOptionalFieldTree } from '@angular/forms/signals';
+import {
+  booleanAttribute,
+  computed,
+  contentChild,
+  Directive,
+  input,
+  ModelSignal,
+  output,
+  TemplateRef,
+} from '@angular/core';
+import type { ValidationError } from '@angular/forms/signals';
 import { FormValueControl } from '@angular/forms/signals';
 
 /**
@@ -40,12 +49,29 @@ import { FormValueControl } from '@angular/forms/signals';
   },
 })
 export abstract class ZenFormControl<Value> implements FormValueControl<Value> {
+  private static uniqueId = 0;
+
+  /** HTML id attribute for the control and its label. Defaults to an auto-generated unique id. */
+  readonly id = input<string>(`zen-control-${ZenFormControl.uniqueId++}`);
+  /** Label text displayed for the form control. */
+  readonly label = input<string>('');
+  /** Informational hint message displayed when there are no errors. */
+  readonly hint = input<string>('');
+  /** Warning message displayed when there are no errors. */
+  readonly warn = input<string>('');
+
+  /** Custom template to render validation errors: `<ng-template #error let-error>` */
+  readonly errorTemplate = contentChild<TemplateRef<{ $implicit: ValidationError.WithOptionalFieldTree }>>('error');
+
+  /** Whether validation errors should be displayed (invalid + touched/dirty). */
+  readonly shouldShowError = computed(() => {
+    return this.invalid() && (this.touched() || this.dirty()) && this.errors().length > 0;
+  });
+
   /** Validation errors for the field. Auto-bound by the Signal Forms directive. */
   readonly errors = input<readonly ValidationError.WithOptionalFieldTree[]>([]);
   /** Whether the control is disabled. Auto-bound by the Signal Forms directive. */
   readonly disabled = input(false);
-  /** Reasons why the field is disabled. Auto-bound by the Signal Forms directive. */
-  readonly disabledReasons = input<readonly WithOptionalFieldTree<DisabledReason>[]>([]);
   /** Whether the field is read-only. Auto-bound by the Signal Forms directive. */
   readonly readonly = input<boolean>(false);
   /** Whether the field is hidden from view. Auto-bound by the Signal Forms directive. */

package/schematics/ui/files/hint/hint.scss

@@ -0,0 +1,48 @@
+:host {
+  --zen-hint-neutral: var(--zen-neutral, hsl(30deg 5% 10%));
+  --zen-hint-primary: var(--zen-primary, hsl(193deg 58% 34%));
+  --zen-hint-success: var(--zen-success, hsl(142deg 38% 36%));
+  --zen-hint-warning: var(--zen-warning, hsl(36deg 72% 46%));
+  --zen-hint-danger: var(--zen-danger, hsl(348deg 52% 42%));
+  --zen-hint-info: var(--zen-info, hsl(214deg 34% 46%));
+  --zen-hint-font-size: 0.75rem;
+}
+
+/* stylelint-disable-next-line no-duplicate-selectors -- separate variables and styles */
+:host {
+  display: block;
+  font-size: var(--zen-hint-font-size);
+  line-height: 1.4;
+  color: var(--zen-hint-neutral);
+  opacity: 0.8;
+
+  &[data-severity='info'] {
+    color: var(--zen-hint-info);
+    opacity: 1;
+  }
+
+  &[data-severity='warning'] {
+    color: var(--zen-hint-warning);
+    opacity: 1;
+  }
+
+  &[data-severity='error'],
+  &[data-severity='danger'] {
+    color: var(--zen-hint-danger);
+    opacity: 1;
+  }
+
+  &[data-severity='success'] {
+    color: var(--zen-hint-success);
+    opacity: 1;
+  }
+
+  &[data-severity='neutral'] {
+    color: var(--zen-hint-neutral);
+  }
+
+  &[data-severity='primary'] {
+    color: var(--zen-hint-primary);
+    opacity: 1;
+  }
+}

package/schematics/ui/files/hint/hint.spec.ts

@@ -0,0 +1,54 @@
+import { provideZonelessChangeDetection } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { beforeEach, describe, expect, it } from 'vitest';
+
+import { ZenHint } from './hint';
+
+describe('ZenHint', () => {
+  beforeEach(async () => {
+    await TestBed.configureTestingModule({
+      imports: [ZenHint],
+      providers: [provideZonelessChangeDetection()],
+    }).compileComponents();
+  });
+
+  it('should create', () => {
+    const fixture = TestBed.createComponent(ZenHint);
+    const component = fixture.componentInstance;
+    expect(component).toBeTruthy();
+  });
+
+  it('should set default severity to neutral and role to status', () => {
+    const fixture = TestBed.createComponent(ZenHint);
+    fixture.detectChanges();
+    const el = fixture.nativeElement as HTMLElement;
+    expect(el.getAttribute('data-severity')).toBe('neutral');
+    expect(el.getAttribute('role')).toBe('status');
+  });
+
+  it('should set role to alert when severity is error or danger', () => {
+    const fixture = TestBed.createComponent(ZenHint);
+    fixture.componentRef.setInput('severity', 'error');
+    fixture.detectChanges();
+    let el = fixture.nativeElement as HTMLElement;
+    expect(el.getAttribute('data-severity')).toBe('error');
+    expect(el.getAttribute('role')).toBe('alert');
+
+    fixture.componentRef.setInput('severity', 'danger');
+    fixture.detectChanges();
+    el = fixture.nativeElement as HTMLElement;
+    expect(el.getAttribute('data-severity')).toBe('danger');
+    expect(el.getAttribute('role')).toBe('alert');
+  });
+
+  it('should set role to status for info, warning, success, and primary', () => {
+    const fixture = TestBed.createComponent(ZenHint);
+    for (const severity of ['info', 'warning', 'success', 'primary'] as const) {
+      fixture.componentRef.setInput('severity', severity);
+      fixture.detectChanges();
+      const el = fixture.nativeElement as HTMLElement;
+      expect(el.getAttribute('data-severity')).toBe(severity);
+      expect(el.getAttribute('role')).toBe('status');
+    }
+  });
+});

package/schematics/ui/files/hint/hint.stories.ts

@@ -0,0 +1,57 @@
+import { Meta, StoryObj } from '@storybook/angular';
+
+import { ZenHint } from './hint';
+
+type Options = ZenHint;
+
+export default {
+  title: 'Ui/Hint',
+  component: ZenHint,
+  argTypes: {
+    severity: {
+      control: 'select',
+      options: ['info', 'warning', 'error', 'danger', 'success', 'neutral', 'primary'],
+    },
+  },
+  args: {
+    severity: 'neutral',
+  },
+  render: args => ({
+    props: args,
+    template: `<zen-hint [severity]="severity">This is a ${args.severity ?? 'neutral'} message.</zen-hint>`,
+  }),
+} satisfies Meta<Options>;
+
+type Story = StoryObj<Options>;
+
+export const Default: Story = {};
+
+export const ErrorSeverity: Story = {
+  args: {
+    severity: 'error',
+  },
+  render: args => ({
+    props: args,
+    template: '<zen-hint [severity]="severity">This field is required.</zen-hint>',
+  }),
+};
+
+export const WarningSeverity: Story = {
+  args: {
+    severity: 'warning',
+  },
+  render: args => ({
+    props: args,
+    template: '<zen-hint [severity]="severity">Password strength is moderate.</zen-hint>',
+  }),
+};
+
+export const SuccessSeverity: Story = {
+  args: {
+    severity: 'success',
+  },
+  render: args => ({
+    props: args,
+    template: '<zen-hint [severity]="severity">Username is available.</zen-hint>',
+  }),
+};