@kouji-ui/core 0.0.3 → 0.1.1

package/src/file-upload/index.ts

@@ -0,0 +1,23 @@
+export {
+  KjFileUpload,
+  KjFileUploadTrigger,
+  KjFileUploadDropzone,
+  KjFileUploadList,
+  KjFileUploadItem,
+  kjFileMatchesAccept,
+} from './file-upload';
+export {
+  KJ_FILE_UPLOAD,
+  KJ_FILE_UPLOAD_ITEM,
+  type KjFileUploadContext,
+  type KjFileUploadItemContext,
+  type KjFileUploadAggregateStatus,
+} from './file-upload.context';
+export {
+  type KjFileStatus,
+  type KjUploadableFile,
+  type KjFileRejectReason,
+  type KjFileRejection,
+  type KjFileUploadValidationMessages,
+  KJ_FILE_UPLOAD_DEFAULT_MESSAGES,
+} from './file-upload.types';

package/src/form/form-error-summary.ts

@@ -0,0 +1,87 @@
+import {
+  Directive,
+  ElementRef,
+  booleanAttribute,
+  computed,
+  effect,
+  inject,
+  input,
+} from '@angular/core';
+import { KjLiveRegion, KjLivePoliteness } from '../a11y/index';
+import { KjForm } from './form';
+
+let nextId = 0;
+
+/**
+ * Optional companion to `KjForm` that renders a polite/assertive live-region
+ * summary of the invalid controls after a failed submit. Composes
+ * `KjLiveRegion` via `hostDirectives`. The presence of a registered summary
+ * causes the parent `KjForm` to wire `aria-describedby` to its id.
+ *
+ * @example
+ * ```html
+ * <form kjForm [formGroup]="form" (kjSubmit)="onSubmit($event)">
+ *   <div kjFormErrorSummary></div>
+ *   …
+ * </form>
+ * ```
+ * @doc-category Core/Inputs
+ * @doc
+ * @doc-name form
+ */
+@Directive({
+  selector: '[kjFormErrorSummary]',
+  standalone: true,
+  exportAs: 'kjFormErrorSummary',
+  hostDirectives: [{ directive: KjLiveRegion, inputs: ['kjPoliteness: kjPoliteness'] }],
+  host: {
+    '[id]': 'id()',
+    '[attr.role]': '"status"',
+    '[attr.data-visible]': 'visible() ? "" : null',
+  },
+})
+export class KjFormErrorSummary {
+  // Inject the concrete class so we can call internal methods like
+  // `setErrorSummaryId` that are not part of the public KjFormContext.
+  private readonly form = inject(KjForm, { optional: true });
+  private readonly el = inject<ElementRef<HTMLElement>>(ElementRef);
+
+  /** Politeness for the underlying live region. Default `'assertive'` — users are awaiting a response. */
+  readonly kjPoliteness = input<KjLivePoliteness>('assertive');
+  /** When `true`, focuses the summary host after population. Default `false`. */
+  readonly kjFocusOnPopulate = input(false, { transform: booleanAttribute });
+
+  /** Generated id, advertised to the parent KjForm so it can set `aria-describedby`. */
+  readonly id = input<string>(`kj-form-error-summary-${++nextId}`);
+
+  /** Visible whenever there is at least one invalid control to summarise. */
+  readonly visible = computed(() => (this.form?.invalidControls().length ?? 0) > 0);
+
+  /** Invalid leaves snapshot (re-exposed for templates rendering the list). */
+  readonly invalidControls = computed(() => this.form?.invalidControls() ?? []);
+
+  constructor() {
+    if (this.form) {
+      // Advertise our id to the parent form so it can wire aria-describedby.
+      effect((onCleanup) => {
+        const id = this.id();
+        this.form!.setErrorSummaryId(id);
+        onCleanup(() => this.form!.setErrorSummaryId(null));
+      });
+    }
+
+    // Optional focus-on-populate side-effect.
+    effect(() => {
+      if (this.kjFocusOnPopulate() && this.visible()) {
+        const host = this.el.nativeElement;
+        host.tabIndex = host.tabIndex === -1 || host.tabIndex >= 0 ? host.tabIndex : -1;
+        if (host.tabIndex === undefined || host.tabIndex < 0) host.tabIndex = -1;
+        try {
+          host.focus({ preventScroll: false });
+        } catch {
+          host.focus?.();
+        }
+      }
+    });
+  }
+}

package/src/form/form-field.context.ts

@@ -0,0 +1,3 @@
+import { InjectionToken, Signal } from '@angular/core';
+export interface KjFormFieldContext { invalid: Signal<boolean>; }
+export const KJ_FORM_FIELD = new InjectionToken<KjFormFieldContext>('KjFormField');

package/src/form/form-field.spec.ts

@@ -0,0 +1,25 @@
+import { render } from '@testing-library/angular';
+import { axe, toHaveNoViolations } from 'jest-axe';
+import { KjFormField, KjFormError, KjFormLabel } from './form-field';
+
+expect.extend(toHaveNoViolations);
+const imports = [KjFormField, KjFormError, KjFormLabel];
+
+describe('KjFormField', () => {
+  it('sets data-invalid when invalid', async () => {
+    const { container } = await render(`<div kjFormField [kjFieldInvalid]="true"><label kjFormLabel for="f">Name</label><input id="f" /><span kjFormError>Required</span></div>`, { imports });
+    expect(container.querySelector('[kjFormField]')).toHaveAttribute('data-invalid', '');
+  });
+  it('error visible when invalid', async () => {
+    const { getByText } = await render(`<div kjFormField [kjFieldInvalid]="true"><label kjFormLabel for="f">Name</label><input id="f" /><span kjFormError>Required</span></div>`, { imports });
+    expect(getByText('Required')).not.toHaveAttribute('hidden');
+  });
+  it('error hidden when valid', async () => {
+    const { getByText } = await render(`<div kjFormField [kjFieldInvalid]="false"><label kjFormLabel for="f">Name</label><input id="f" /><span kjFormError>Required</span></div>`, { imports });
+    expect(getByText('Required').closest('[kjFormError]')).toHaveAttribute('hidden', '');
+  });
+  it('passes axe audit', async () => {
+    const { container } = await render(`<div kjFormField [kjFieldInvalid]="false"><label kjFormLabel for="e">Email</label><input id="e" type="email" /></div>`, { imports });
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});

package/src/form/form-field.ts

@@ -0,0 +1,52 @@
+import { Directive, computed, inject, input } from '@angular/core';
+import { KJ_FORM_FIELD, KjFormFieldContext } from './form-field.context';
+
+/**
+ * Container for a form field. Groups label, input, and error message.
+ * @example
+ * ```html
+ * <div kjFormField [kjFieldInvalid]="ctrl.invalid && ctrl.touched">
+ *   <label kjFormLabel for="name">Name</label>
+ *   <input id="name" kjInput />
+ *   <span kjFormError>Name is required</span>
+ * </div>
+ * ```
+ * @doc-category Core/Inputs
+ * @doc
+ * @doc-name form
+ */
+@Directive({
+  selector: '[kjFormField]', standalone: true,
+  providers: [{ provide: KJ_FORM_FIELD, useExisting: KjFormField }],
+  host: { '[attr.data-invalid]': 'kjFieldInvalid() ? "" : null' },
+})
+export class KjFormField implements KjFormFieldContext {
+  /** Whether the field is in an invalid state. */
+  kjFieldInvalid = input<boolean>(false);
+  readonly invalid = computed(() => this.kjFieldInvalid());
+}
+
+/**
+ * Label element within a form field.
+ * @doc-category Core/Inputs
+ * @doc
+ * @doc-name form
+ */
+@Directive({
+  selector: '[kjFormLabel]', standalone: true,
+  host: { '[attr.data-invalid]': 'ctx.invalid() ? "" : null' },
+})
+export class KjFormLabel { readonly ctx = inject(KJ_FORM_FIELD); }
+
+/**
+ * Error message element. Visible only when field is invalid.
+ * @example `<span kjFormError>Email is invalid</span>`
+ * @doc-category Core/Inputs
+ * @doc
+ * @doc-name form
+ */
+@Directive({
+  selector: '[kjFormError]', standalone: true,
+  host: { role: 'alert', 'aria-live': 'polite', '[attr.hidden]': '!ctx.invalid() ? "" : null' },
+})
+export class KjFormError { readonly ctx = inject(KJ_FORM_FIELD); }

package/src/form/form.context.ts

@@ -1,3 +1,53 @@
 import { InjectionToken, Signal } from '@angular/core';
-export interface KjFormFieldContext { invalid: Signal<boolean>; }
-export const KJ_FORM_FIELD = new InjectionToken<KjFormFieldContext>('KjFormField');
+import { AbstractControl, FormGroup } from '@angular/forms';
+
+/**
+ * A pair of (control name path, host element) registered with KjForm so the
+ * focus-on-error pipeline can target the right DOM node without a query crawl.
+ */
+export interface KjFormControlRegistration {
+  /** Dot-path of the control within the form group (e.g. `'address.street'`). */
+  readonly path: string;
+  /** Host element that should receive focus when this control is the first invalid one. */
+  readonly element: HTMLElement;
+  /** Optional human label (used by the error summary). */
+  readonly label?: string;
+}
+
+/**
+ * Public surface that `KjForm` exposes to descendants via the `KJ_FORM`
+ * injection token. Only descendants that need form-level coordination
+ * (submitting flag, control registry, summary updates) inject this token.
+ */
+export interface KjFormContext {
+  /** The Angular FormGroup powering this form (resolved from `[formGroup]` or `NgForm`). */
+  readonly form: Signal<FormGroup | null>;
+  /** True while an async submit is in flight. */
+  readonly submitting: Signal<boolean>;
+  /** True after the user has attempted submit at least once. */
+  readonly submitted: Signal<boolean>;
+  /** True when the most recent submit attempt was invalid. */
+  readonly invalid: Signal<boolean>;
+  /** Snapshot of the invalid leaf controls from the most recent submit attempt. */
+  readonly invalidControls: Signal<readonly InvalidControlInfo[]>;
+  /**
+   * Register a host element as the focus target for `path`.
+   * Returns a cleanup callback that removes the registration.
+   */
+  registerControl(reg: KjFormControlRegistration): () => void;
+  /** Imperative submit — equivalent to dispatching a `submit` event on the host. */
+  submit(): void;
+}
+
+/** Invalid leaf control descriptor used by the error summary. */
+export interface InvalidControlInfo {
+  /** Dot-path of the control. */
+  readonly path: string;
+  /** The Angular AbstractControl reference. */
+  readonly control: AbstractControl;
+  /** Human label (falls back to the path). */
+  readonly label: string;
+}
+
+/** Injection token for the parent `<form kjForm>` directive. */
+export const KJ_FORM = new InjectionToken<KjFormContext>('KjForm');

package/src/form/form.spec.ts

@@ -1,25 +1,162 @@
-import { render } from '@testing-library/angular';
-import { axe, toHaveNoViolations } from 'jest-axe';
-import { KjFormField, KjFormError, KjFormLabel } from './form';
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
+import { describe, expect, it } from 'vitest';
+import { KjForm } from './form';
+import { KjFormErrorSummary } from './form-error-summary';
 
-expect.extend(toHaveNoViolations);
-const imports = [KjFormField, KjFormError, KjFormLabel];
+@Component({
+  standalone: true,
+  imports: [KjForm, ReactiveFormsModule],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <form
+      kjForm
+      [formGroup]="group"
+      (kjSubmit)="submitted.set($event)"
+      (kjInvalidSubmit)="invalid.set($event)"
+    >
+      <input id="email" formControlName="email" />
+      <input id="password" formControlName="password" />
+      <button type="submit">Sign in</button>
+    </form>
+  `,
+})
+class ReactiveHost {
+  group = new FormGroup({
+    email: new FormControl('', [Validators.required, Validators.email]),
+    password: new FormControl('', [Validators.required]),
+  });
+  submitted = signal<unknown>(null);
+  invalid = signal<unknown>(null);
+}
 
-describe('KjFormField', () => {
-  it('sets data-invalid when invalid', async () => {
-    const { container } = await render(`<div kjFormField [kjFieldInvalid]="true"><label kjFormLabel for="f">Name</label><input id="f" /><span kjFormError>Required</span></div>`, { imports });
-    expect(container.querySelector('[kjFormField]')).toHaveAttribute('data-invalid', '');
+@Component({
+  standalone: true,
+  imports: [KjForm, KjFormErrorSummary, ReactiveFormsModule],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <form kjForm [formGroup]="group" (kjSubmit)="submitted.set($event)">
+      <div kjFormErrorSummary #s="kjFormErrorSummary">
+        @if (s.visible()) {
+          <strong>{{ s.invalidControls().length }} errors</strong>
+          <ul>
+            @for (item of s.invalidControls(); track item.path) {
+              <li>{{ item.label }}</li>
+            }
+          </ul>
+        }
+      </div>
+      <input id="email" formControlName="email" />
+      <input id="name" formControlName="name" />
+      <button type="submit">Save</button>
+    </form>
+  `,
+})
+class SummaryHost {
+  group = new FormGroup({
+    email: new FormControl('', [Validators.required]),
+    name: new FormControl('', [Validators.required]),
   });
-  it('error visible when invalid', async () => {
-    const { getByText } = await render(`<div kjFormField [kjFieldInvalid]="true"><label kjFormLabel for="f">Name</label><input id="f" /><span kjFormError>Required</span></div>`, { imports });
-    expect(getByText('Required')).not.toHaveAttribute('hidden');
+  submitted = signal<unknown>(null);
+}
+
+describe('KjForm', () => {
+  it('emits (kjSubmit) with form value when valid', () => {
+    const fixture = TestBed.createComponent(ReactiveHost);
+    fixture.detectChanges();
+    fixture.componentInstance.group.setValue({ email: 'a@b.co', password: 'x' });
+    const form: HTMLFormElement = fixture.nativeElement.querySelector('form');
+    form.dispatchEvent(new Event('submit'));
+    expect(fixture.componentInstance.submitted()).toEqual({ email: 'a@b.co', password: 'x' });
+    expect(fixture.componentInstance.invalid()).toBeNull();
   });
-  it('error hidden when valid', async () => {
-    const { getByText } = await render(`<div kjFormField [kjFieldInvalid]="false"><label kjFormLabel for="f">Name</label><input id="f" /><span kjFormError>Required</span></div>`, { imports });
-    expect(getByText('Required').closest('[kjFormError]')).toHaveAttribute('hidden', '');
+
+  it('emits (kjInvalidSubmit) and not (kjSubmit) when invalid', () => {
+    const fixture = TestBed.createComponent(ReactiveHost);
+    fixture.detectChanges();
+    const form: HTMLFormElement = fixture.nativeElement.querySelector('form');
+    form.dispatchEvent(new Event('submit'));
+    expect(fixture.componentInstance.submitted()).toBeNull();
+    expect(fixture.componentInstance.invalid()).toBe(fixture.componentInstance.group);
+  });
+
+  it('marks all controls as touched on submit by default', () => {
+    const fixture = TestBed.createComponent(ReactiveHost);
+    fixture.detectChanges();
+    const form: HTMLFormElement = fixture.nativeElement.querySelector('form');
+    form.dispatchEvent(new Event('submit'));
+    expect(fixture.componentInstance.group.controls.email.touched).toBe(true);
+    expect(fixture.componentInstance.group.controls.password.touched).toBe(true);
+  });
+
+  it('reflects data-invalid attribute when last submit was invalid', () => {
+    const fixture = TestBed.createComponent(ReactiveHost);
+    fixture.detectChanges();
+    const form: HTMLFormElement = fixture.nativeElement.querySelector('form');
+    form.dispatchEvent(new Event('submit'));
+    fixture.detectChanges();
+    expect(form.getAttribute('data-invalid')).toBe('');
+  });
+
+  it('prevents native form submission', () => {
+    const fixture = TestBed.createComponent(ReactiveHost);
+    fixture.detectChanges();
+    const form: HTMLFormElement = fixture.nativeElement.querySelector('form');
+    const event = new Event('submit', { cancelable: true });
+    form.dispatchEvent(event);
+    expect(event.defaultPrevented).toBe(true);
   });
-  it('passes axe audit', async () => {
-    const { container } = await render(`<div kjFormField [kjFieldInvalid]="false"><label kjFormLabel for="e">Email</label><input id="e" type="email" /></div>`, { imports });
-    expect(await axe(container)).toHaveNoViolations();
+
+  it('focuses the first invalid control on submit', () => {
+    const fixture = TestBed.createComponent(ReactiveHost);
+    fixture.detectChanges();
+    const form: HTMLFormElement = fixture.nativeElement.querySelector('form');
+    const emailInput: HTMLInputElement = fixture.nativeElement.querySelector('#email');
+    form.dispatchEvent(new Event('submit'));
+    expect(document.activeElement).toBe(emailInput);
+  });
+
+  it('does not run async submit when validity fails', async () => {
+    let calls = 0;
+    @Component({
+      standalone: true,
+      imports: [KjForm, ReactiveFormsModule],
+      template: `<form kjForm [formGroup]="group" [kjAsyncSubmit]="handler">
+        <input formControlName="x" /><button type="submit">go</button>
+      </form>`,
+    })
+    class Host {
+      group = new FormGroup({ x: new FormControl('', [Validators.required]) });
+      handler = (): Promise<void> => {
+        calls++;
+        return Promise.resolve();
+      };
+    }
+    const fixture = TestBed.createComponent(Host);
+    fixture.detectChanges();
+    fixture.nativeElement.querySelector('form').dispatchEvent(new Event('submit'));
+    expect(calls).toBe(0);
+  });
+});
+
+describe('KjFormErrorSummary', () => {
+  it('exposes invalid controls after invalid submit', () => {
+    const fixture = TestBed.createComponent(SummaryHost);
+    fixture.detectChanges();
+    const form: HTMLFormElement = fixture.nativeElement.querySelector('form');
+    form.dispatchEvent(new Event('submit'));
+    fixture.detectChanges();
+    const items = fixture.nativeElement.querySelectorAll('li');
+    expect(items.length).toBe(2);
+  });
+
+  it('wires aria-describedby on the form to the summary id', () => {
+    const fixture = TestBed.createComponent(SummaryHost);
+    fixture.detectChanges();
+    const form: HTMLFormElement = fixture.nativeElement.querySelector('form');
+    const summary: HTMLElement = fixture.nativeElement.querySelector('[kjFormErrorSummary]');
+    fixture.detectChanges();
+    expect(form.getAttribute('aria-describedby')).toBe(summary.id);
   });
 });