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

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

@@ -0,0 +1,48 @@
+import { Component, input } from '@angular/core';
+
+export type ZenHintSeverity = 'info' | 'warning' | 'error' | 'danger' | 'success' | 'neutral' | 'primary';
+
+/**
+ * ZenHint is a reusable component for displaying hints, helper text, warnings,
+ * and error messages for form controls.
+ *
+ * @example
+ * ```html
+ * <zen-hint>This is an info hint</zen-hint>
+ * <zen-hint severity="error">This field is required</zen-hint>
+ * <zen-hint severity="warning">Password strength is low</zen-hint>
+ * ```
+ *
+ * ### CSS Custom Properties
+ *
+ * You can customize the component using CSS custom properties:
+ *
+ * ```css
+ * :root {
+ *   --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.8125rem;
+ * }
+ * ```
+ *
+ * @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)
+ */
+@Component({
+  selector: 'zen-hint',
+  template: '<ng-content />',
+  styleUrl: './hint.scss',
+  host: {
+    '[attr.data-severity]': 'severity()',
+    '[attr.role]': 'severity() === "error" || severity() === "danger" ? "alert" : "status"',
+  },
+})
+export class ZenHint {
+  /** The severity level of the hint message. */
+  readonly severity = input<ZenHintSeverity>('neutral');
+}

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

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

package/schematics/ui/files/input/input.html

@@ -0,0 +1,29 @@
+@if (label()) {
+  <zen-label [disabled]="disabled()" [for]="id()" [required]="required()">{{ label() }}</zen-label>
+}
+<input
+  #inputRef
+  [aria-invalid]="invalid() || null"
+  [disabled]="disabled()"
+  [id]="id()"
+  [placeholder]="placeholder()"
+  [required]="required()"
+  [type]="type()"
+  [value]="value()"
+  (input)="onInput(inputRef.value)"
+/>
+@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/input/input.scss

@@ -13,7 +13,8 @@ $disabled-opacity: var(--zen-disabled-opacity, 0.6);
 
 /* stylelint-disable-next-line no-duplicate-selectors -- separate variables and styles */
 :host {
-  display: contents;
+  display: inline-flex;
+  flex-direction: column;
 }
 
 input {

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

@@ -1,13 +1,43 @@
-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 { ZenInput } from './input';
 
+@Component({
+  imports: [ZenInput],
+  template: `
+    <zen-input
+      [errors]="errors()"
+      [hint]="hint()"
+      [invalid]="invalid()"
+      [label]="label()"
+      [required]="required()"
+      [touched]="touched()"
+      [warn]="warn()"
+    >
+      @if (customError()) {
+        <ng-template #error let-error>Custom: {{ error.message }}</ng-template>
+      }
+    </zen-input>
+  `,
+})
+class TestInputHostComponent {
+  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[]>([]);
+  readonly customError = signal(false);
+}
+
 describe('ZenInput', () => {
   beforeEach(async () => {
     await TestBed.configureTestingModule({
-      imports: [ZenInput],
+      imports: [ZenInput, TestInputHostComponent],
       providers: [provideZonelessChangeDetection()],
     }).compileComponents();
   });
@@ -17,4 +47,79 @@ describe('ZenInput', () => {
     const component = fixture.componentInstance;
     expect(component).toBeTruthy();
   });
+
+  it('should render label linked to input id and handle required state', () => {
+    const fixture = TestBed.createComponent(TestInputHostComponent);
+    fixture.componentInstance.label.set('User Email');
+    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('User Email');
+    expect(labelEl.getAttribute('for')).toBe(inputEl.id);
+    expect(inputEl.id).toMatch(/^zen-control-\d+$/);
+
+    fixture.componentInstance.required.set(true);
+    fixture.detectChanges();
+
+    const requiredSpan = fixture.nativeElement.querySelector('zen-label .required');
+    expect(requiredSpan).toBeTruthy();
+    expect(requiredSpan.textContent).toBe('*');
+  });
+
+  it('should render hint when provided', () => {
+    const fixture = TestBed.createComponent(TestInputHostComponent);
+    fixture.componentInstance.hint.set('Informational hint');
+    fixture.detectChanges();
+
+    const hintEl = fixture.nativeElement.querySelector('zen-hint');
+    expect(hintEl).toBeTruthy();
+    expect(hintEl.getAttribute('data-severity')).toBe('neutral');
+    expect(hintEl.textContent?.trim()).toBe('Informational hint');
+  });
+
+  it('should render warn when provided and take precedence over hint', () => {
+    const fixture = TestBed.createComponent(TestInputHostComponent);
+    fixture.componentInstance.hint.set('Informational hint');
+    fixture.componentInstance.warn.set('Warning message');
+    fixture.detectChanges();
+
+    const hintEl = fixture.nativeElement.querySelector('zen-hint');
+    expect(hintEl).toBeTruthy();
+    expect(hintEl.getAttribute('data-severity')).toBe('warning');
+    expect(hintEl.textContent?.trim()).toBe('Warning message');
+  });
+
+  it('should render error messages when invalid and touched', () => {
+    const fixture = TestBed.createComponent(TestInputHostComponent);
+    fixture.componentInstance.invalid.set(true);
+    fixture.componentInstance.touched.set(true);
+    fixture.componentInstance.errors.set([
+      { kind: 'required', message: 'Field required' },
+      { kind: 'minLength', message: 'Min length 5' },
+    ]);
+    fixture.detectChanges();
+
+    const hintEls = fixture.nativeElement.querySelectorAll('zen-hint');
+    expect(hintEls.length).toBe(2);
+    expect(hintEls[0].getAttribute('data-severity')).toBe('error');
+    expect(hintEls[0].textContent?.trim()).toBe('Field required');
+    expect(hintEls[1].textContent?.trim()).toBe('Min length 5');
+  });
+
+  it('should allow overriding error message via ng-template #error', () => {
+    const fixture = TestBed.createComponent(TestInputHostComponent);
+    fixture.componentInstance.customError.set(true);
+    fixture.componentInstance.invalid.set(true);
+    fixture.componentInstance.touched.set(true);
+    fixture.componentInstance.errors.set([{ kind: 'required', message: 'Field 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('Custom: Field required');
+  });
 });

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

@@ -41,13 +41,25 @@ type Story = StoryObj<Options>;
 export const Default: Story = {};
 
 export const WithLabel: Story = {
-  render: () => ({
-    template: `
-      <div style="display: flex; flex-direction: column">
-        <label for="label-example"> With label </label>
-        <zen-input id="label-example"/>
-      </div>
-  `,
+  args: {
+    label: 'Username',
+    placeholder: 'Enter username',
+  },
+  render: args => ({
+    props: args,
+    template: '<zen-input [label]="label" [placeholder]="placeholder" />',
+  }),
+};
+
+export const WithHintAndWarn: Story = {
+  args: {
+    label: 'Password',
+    hint: 'Must be at least 8 characters',
+    placeholder: 'Enter password',
+  },
+  render: args => ({
+    props: args,
+    template: '<zen-input [label]="label" [hint]="hint" [placeholder]="placeholder" type="password" />',
   }),
 };
 
@@ -60,7 +72,7 @@ export const WithSignalForm: Story = {
   parameters: {
     docs: {
       source: {
-        code: `<zen-input [formField]="form.name" />`,
+        code: `<zen-input label="Full Name" [formField]="form.name" />`,
       },
     },
   },
@@ -76,8 +88,8 @@ export const WithFormRoot: Story = {
     docs: {
       source: {
         code: `<form [formRoot]="loginForm">
-  <zen-input [formField]="loginForm.email" placeholder="Email" />
-  <zen-input [formField]="loginForm.password" placeholder="Password" type="password" />
+  <zen-input label="Email" [formField]="loginForm.email" placeholder="Email" />
+  <zen-input label="Password" [formField]="loginForm.password" placeholder="Password" type="password" />
   <button type="submit">Sign in</button>
 </form>`,
       },
@@ -89,12 +101,7 @@ export const WithFormRoot: Story = {
   standalone: true,
   template: `
     <div style="display: flex; flex-direction: column; gap: 0.5rem; max-width: 300px;">
-      <zen-input placeholder="Type something" [formField]="form.name" />
-      @if (form.name().invalid()) {
-        <p style="color: red; margin: 0; font-size: 0.875rem;">
-          {{ form.name().errors()![0].message }}
-        </p>
-      }
+      <zen-input label="Full Name" placeholder="Type something" [formField]="form.name" />
     </div>
   `,
   imports: [FormField, ZenInput],

package/schematics/ui/files/input/input.ts

@@ -1,6 +1,9 @@
+import { NgTemplateOutlet } from '@angular/common';
 import { Component, input, model } from '@angular/core';
 
 import { ZenFormControl } from '../form-control';
+import { ZenHint } from '../hint';
+import { ZenLabel } from '../label';
 
 /**
  * ZenInput is a single-line text input component backed by Signal Forms.
@@ -8,7 +11,7 @@ import { ZenFormControl } from '../form-control';
  * Connect it to a Signal Forms field with `[formField]`:
  *
  * ```html
- * <zen-input [formField]="myForm.name" placeholder="Enter name" />
+ * <zen-input [formField]="myForm.name" placeholder="Enter name" label="Name" />
  * ```
  *
  * The `[formField]` directive automatically synchronises value, disabled
@@ -35,19 +38,9 @@ import { ZenFormControl } from '../form-control';
  */
 @Component({
   selector: 'zen-input',
-  template: `
-    <input
-      #inputRef
-      [aria-invalid]="invalid() || null"
-      [disabled]="disabled()"
-      [placeholder]="placeholder()"
-      [required]="required()"
-      [type]="type()"
-      [value]="value()"
-      (input)="onInput(inputRef.value)"
-    />
-  `,
-  styleUrls: ['./input.scss'],
+  imports: [NgTemplateOutlet, ZenHint, ZenLabel],
+  templateUrl: './input.html',
+  styleUrl: './input.scss',
 })
 export class ZenInput extends ZenFormControl<string> {
   /** The current input value with two-way binding support. */

package/schematics/ui/files/label/index.ts

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

package/schematics/ui/files/label/label.html

@@ -0,0 +1,6 @@
+<label [attr.for]="targetId()">
+  <ng-content />
+  @if (required()) {
+    <span aria-hidden="true" class="required">*</span>
+  }
+</label>

package/schematics/ui/files/label/label.scss

@@ -0,0 +1,52 @@
+$disabled-opacity: var(--zen-disabled-opacity, 0.6);
+
+:host {
+  --zen-label-font-size: 0.875rem;
+  --zen-label-font-weight: 500;
+  --zen-label-color: hsl(0deg 0% 15%);
+  --zen-label-required-color: var(--zen-danger, hsl(348deg 52% 42%));
+}
+
+/* stylelint-disable-next-line no-duplicate-selectors -- separate variables and styles */
+:host {
+  display: inline-flex;
+  align-items: center;
+  font-size: var(--zen-label-font-size);
+  font-weight: var(--zen-label-font-weight);
+  color: var(--zen-label-color);
+  line-height: 1.4;
+  user-select: none;
+
+  &[data-size='sm'] {
+    --zen-label-font-size: 0.75rem;
+  }
+
+  &[data-size='md'] {
+    --zen-label-font-size: 0.875rem;
+  }
+
+  &[data-size='lg'] {
+    --zen-label-font-size: 1rem;
+  }
+
+  &[data-disabled] {
+    opacity: $disabled-opacity;
+    cursor: not-allowed;
+
+    label {
+      cursor: not-allowed;
+    }
+  }
+}
+
+label {
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+}
+
+.required {
+  color: var(--zen-label-required-color);
+  margin-inline-start: 0.25rem;
+  font-weight: 600;
+}

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

@@ -0,0 +1,77 @@
+import { Component, provideZonelessChangeDetection } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { beforeEach, describe, expect, it } from 'vitest';
+
+import { ZenLabel } from './label';
+
+@Component({
+  imports: [ZenLabel],
+  template: '<zen-label [for]="targetId" [required]="required">User Label</zen-label>',
+})
+class TestHostComponent {
+  targetId = 'input-1';
+  required = false;
+}
+
+describe('ZenLabel', () => {
+  beforeEach(async () => {
+    await TestBed.configureTestingModule({
+      imports: [ZenLabel, TestHostComponent],
+      providers: [provideZonelessChangeDetection()],
+    }).compileComponents();
+  });
+
+  it('should create', () => {
+    const fixture = TestBed.createComponent(ZenLabel);
+    const component = fixture.componentInstance;
+    expect(component).toBeTruthy();
+  });
+
+  it('should render label with for attribute matching targetId', () => {
+    const fixture = TestBed.createComponent(TestHostComponent);
+    fixture.detectChanges();
+
+    const labelEl = fixture.nativeElement.querySelector('label') as HTMLLabelElement;
+    expect(labelEl).toBeTruthy();
+    expect(labelEl.getAttribute('for')).toBe('input-1');
+    expect(labelEl.textContent?.trim()).toBe('User Label');
+  });
+
+  it('should support id input as fallback for for attribute', () => {
+    const fixture = TestBed.createComponent(ZenLabel);
+    fixture.componentRef.setInput('id', 'input-fallback');
+    fixture.detectChanges();
+
+    const labelEl = fixture.nativeElement.querySelector('label') as HTMLLabelElement;
+    expect(labelEl.getAttribute('for')).toBe('input-fallback');
+  });
+
+  it('should render asterisk when required is true', () => {
+    const fixture = TestBed.createComponent(TestHostComponent);
+    fixture.componentInstance.required = true;
+    fixture.detectChanges();
+
+    const requiredEl = fixture.nativeElement.querySelector('.required') as HTMLElement;
+    expect(requiredEl).toBeTruthy();
+    expect(requiredEl.textContent?.trim()).toBe('*');
+  });
+
+  it('should set size attribute', () => {
+    const fixture = TestBed.createComponent(ZenLabel);
+    for (const size of ['sm', 'md', 'lg'] as const) {
+      fixture.componentRef.setInput('size', size);
+      fixture.detectChanges();
+      const el = fixture.nativeElement as HTMLElement;
+      expect(el.getAttribute('data-size')).toBe(size);
+    }
+  });
+
+  it('should apply data-disabled when disabled is true', () => {
+    const fixture = TestBed.createComponent(ZenLabel);
+    fixture.componentRef.setInput('disabled', true);
+    fixture.detectChanges();
+
+    const el = fixture.nativeElement as HTMLElement;
+    expect(el.hasAttribute('data-disabled')).toBe(true);
+  });
+});

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

@@ -0,0 +1,67 @@
+import { Meta, StoryObj } from '@storybook/angular';
+
+import { ZenLabel } from './label';
+
+type Options = ZenLabel;
+
+export default {
+  title: 'Ui/Label',
+  component: ZenLabel,
+  argTypes: {
+    size: {
+      control: 'select',
+      options: ['sm', 'md', 'lg'],
+    },
+    required: {
+      control: 'boolean',
+    },
+    disabled: {
+      control: 'boolean',
+    },
+    for: {
+      control: 'text',
+    },
+  },
+  args: {
+    size: 'md',
+    required: false,
+    disabled: false,
+    for: 'example-control',
+  },
+  render: args => ({
+    props: args,
+    template: `
+      <zen-label [disabled]="disabled" [for]="for" [required]="required" [size]="size">
+        Label text
+      </zen-label>
+    `,
+  }),
+} satisfies Meta<Options>;
+
+type Story = StoryObj<Options>;
+
+export const Default: Story = {};
+
+export const Required: Story = {
+  args: {
+    required: true,
+  },
+};
+
+export const Small: Story = {
+  args: {
+    size: 'sm',
+  },
+};
+
+export const Large: Story = {
+  args: {
+    size: 'lg',
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    disabled: true,
+  },
+};

package/schematics/ui/files/label/label.ts

@@ -0,0 +1,57 @@
+import { booleanAttribute, Component, computed, input } from '@angular/core';
+
+export type ZenLabelSize = 'sm' | 'md' | 'lg';
+
+/**
+ * ZenLabel is an accessible label component that links to form controls,
+ * supports required indicators (*), multiple sizes, and disabled states.
+ *
+ * @example
+ * ```html
+ * <zen-label [for]="id()" required>Email</zen-label>
+ * <zen-label for="terms" size="sm">I accept the terms</zen-label>
+ * ```
+ *
+ * ### CSS Custom Properties
+ *
+ * You can customize the component using CSS custom properties:
+ *
+ * ```css
+ * :root {
+ *   --zen-label-font-size: 0.875rem;
+ *   --zen-label-font-weight: 500;
+ *   --zen-label-color: hsl(0deg 0% 15%);
+ *   --zen-label-required-color: var(--zen-danger, hsl(348deg 52% 42%));
+ * }
+ * ```
+ *
+ * @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)
+ */
+@Component({
+  selector: 'zen-label',
+  templateUrl: './label.html',
+  styleUrl: './label.scss',
+  host: {
+    '[attr.data-size]': 'size()',
+    '[attr.data-disabled]': 'disabled() ? "" : null',
+  },
+})
+export class ZenLabel {
+  /** The id of the form control this label is linked to. Supports both [for] and [id]. */
+  readonly for = input<string>('');
+  readonly id = input<string>('');
+
+  /** Resolved target control id (prioritizes `for`, falls back to `id`). */
+  protected readonly targetId = computed(() => this.for() || this.id());
+
+  /** Whether the associated control is required. Renders a red asterisk (*) when true. */
+  readonly required = input(false, { transform: booleanAttribute });
+
+  /** Visual size variant: 'sm' | 'md' | 'lg'. Defaults to 'md'. */
+  readonly size = input<ZenLabelSize>('md');
+
+  /** Whether the label is in a disabled state. */
+  readonly disabled = input(false, { transform: booleanAttribute });
+}

package/schematics/ui/files/radio/radio.html

@@ -0,0 +1,34 @@
+<input
+  #inputElement
+  type="radio"
+  [attr.aria-checked]="checked()"
+  [attr.aria-disabled]="disabled()"
+  [attr.aria-invalid]="invalid() || null"
+  [checked]="checked()"
+  [disabled]="disabled()"
+  [id]="id()"
+  [name]="name()"
+  [value]="option()"
+  (change)="onRadioChange()"
+/>
+@if (checked()) {
+  <span class="radio-dot"></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>
+}