@kouji-ui/components 0.1.1

package/src/form/form.css

@@ -0,0 +1,63 @@
+@layer kj.component {
+  .kj-form {
+    /* component knobs — themes/users override any of these */
+    --kj-form-gap:           var(--kj-space-md, 0.75rem);
+    --kj-form-actions-gap:   var(--kj-space-sm, 0.5rem);
+    --kj-form-summary-bg:    var(--kj-bg-surface);
+    --kj-form-summary-fg:    var(--kj-fg-default);
+    --kj-form-summary-accent: var(--kj-fg-danger, #dc2626);
+    --kj-form-summary-radius: var(--kj-radius-box, 0.5rem);
+
+    display: flex;
+    flex-direction: column;
+    gap: var(--kj-form-gap);
+  }
+
+  .kj-form[data-submitting] {
+    cursor: progress;
+  }
+
+  /* Actions row — typically at the bottom; flex with gap, right-aligned by default. */
+  .kj-form-actions {
+    display: flex;
+    align-items: center;
+    justify-content: flex-end;
+    gap: var(--kj-form-actions-gap);
+    margin-top: var(--kj-space-sm, 0.5rem);
+  }
+
+  .kj-form-actions[data-align="start"] { justify-content: flex-start; }
+  .kj-form-actions[data-align="between"] { justify-content: space-between; }
+  .kj-form-actions[data-align="center"] { justify-content: center; }
+
+  /* Error summary — destructive-tinted alert chrome. Hidden when no errors. */
+  .kj-form-summary {
+    display: none;
+    background: var(--kj-form-summary-bg);
+    color: var(--kj-form-summary-fg);
+    border: var(--kj-border, 1px) solid var(--kj-form-summary-accent);
+    border-left: 4px solid var(--kj-form-summary-accent);
+    border-radius: var(--kj-form-summary-radius);
+    padding: var(--kj-space-md, 0.75rem) var(--kj-space-lg, 1rem);
+    font: var(--kj-text-sm, 0.875rem) / 1.45 var(--kj-font-sans, sans-serif);
+  }
+
+  .kj-form-summary[data-visible] {
+    display: block;
+  }
+
+  .kj-form-summary__title {
+    font-weight: 600;
+    margin: 0 0 var(--kj-space-xs, 0.25rem) 0;
+    color: var(--kj-form-summary-accent);
+  }
+
+  .kj-form-summary__list {
+    margin: 0;
+    padding-left: var(--kj-space-lg, 1rem);
+  }
+
+  .kj-form-summary__list li {
+    margin: 0.125rem 0;
+  }
+}

package/src/form/form.playground.ts

@@ -0,0 +1,145 @@
+import { ChangeDetectionStrategy, Component, computed, signal } from '@angular/core';
+import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
+import {
+  KjFormComponent,
+  KjFormActionsComponent,
+  KjFormSummaryComponent,
+} from './form';
+import { KjFieldComponent, KjFieldLabelComponent } from '../field/field';
+import { KjInputComponent } from '../input/input';
+import { KjButtonComponent } from '../button/button';
+import type { PlaygroundFile } from '@kouji-ui/components/playground-types';
+
+/**
+ * Playground state — module-scope signals. Field count plus the structural
+ * toggles (summary, action row, async submit) drive the canonical form
+ * recipe. The reactive `FormGroup` is rebuilt whenever the field count
+ * changes so each row owns a live control.
+ */
+const fieldCount = signal<1 | 2 | 3>(2);
+const showSummary = signal(true);
+const showActions = signal(true);
+const asyncSubmit = signal(false);
+
+const FIELDS: ReadonlyArray<{ name: string; label: string; type: 'email' | 'password' | 'text'; placeholder: string }> = [
+  { name: 'email', label: 'Email', type: 'email', placeholder: 'you@example.com' },
+  { name: 'password', label: 'Password', type: 'password', placeholder: '' },
+  { name: 'company', label: 'Company', type: 'text', placeholder: 'Acme Inc.' },
+];
+
+@Component({
+  selector: 'kj-form-playground',
+  standalone: true,
+  imports: [
+    KjFormComponent,
+    KjFormActionsComponent,
+    KjFormSummaryComponent,
+    KjFieldComponent,
+    KjFieldLabelComponent,
+    KjInputComponent,
+    KjButtonComponent,
+    ReactiveFormsModule,
+  ],
+  styles: [`:host { display: block; max-width: 480px; }`],
+  template: `
+    <form kj-form [formGroup]="form()" [kjAsyncSubmit]="resolvedHandler()" (kjSubmit)="onSubmit()">
+      @if (showSummary()) {
+        <kj-form-summary />
+      }
+      @for (f of visibleFields(); track f.name) {
+        <kj-field>
+          <kj-field-label>{{ f.label }}</kj-field-label>
+          <kj-input
+            [type]="f.type"
+            [formControlName]="f.name"
+            [placeholder]="f.placeholder"
+          />
+        </kj-field>
+      }
+      @if (showActions()) {
+        <kj-form-actions>
+          <kj-button kjVariant="ghost" kjType="reset">Cancel</kj-button>
+          <kj-button kjType="submit" [kjLoading]="busy()">Save</kj-button>
+        </kj-form-actions>
+      }
+    </form>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjFormPlaygroundDemo {
+  protected readonly fieldCount = fieldCount;
+  protected readonly showSummary = showSummary;
+  protected readonly showActions = showActions;
+  protected readonly asyncSubmit = asyncSubmit;
+  protected readonly busy = signal(false);
+
+  protected readonly visibleFields = computed(() => FIELDS.slice(0, fieldCount()));
+
+  protected readonly resolvedHandler = computed(() =>
+    this.asyncSubmit() ? () => new Promise<void>((r) => setTimeout(r, 800)) : undefined,
+  );
+
+  protected readonly form = computed(() => {
+    const group: Record<string, FormControl> = {};
+    for (const f of this.visibleFields()) {
+      const validators = [Validators.required];
+      if (f.type === 'email') validators.push(Validators.email);
+      if (f.type === 'password') validators.push(Validators.minLength(8));
+      group[f.name] = new FormControl('', validators);
+    }
+    return new FormGroup(group);
+  });
+
+  protected onSubmit(): void {
+    this.busy.set(true);
+    setTimeout(() => this.busy.set(false), 800);
+  }
+}
+
+export const PLAYGROUND: PlaygroundFile = {
+  component: KjFormPlaygroundDemo,
+  state: {
+    fieldCount: fieldCount as unknown as ReturnType<typeof signal>,
+    showSummary: showSummary as unknown as ReturnType<typeof signal>,
+    showActions: showActions as unknown as ReturnType<typeof signal>,
+    asyncSubmit: asyncSubmit as unknown as ReturnType<typeof signal>,
+  },
+  controls: [
+    { kind: 'chips', name: 'fieldCount', label: 'fields', options: [1, 2, 3] },
+    { kind: 'toggle', name: 'showSummary', label: 'with summary' },
+    { kind: 'toggle', name: 'showActions', label: 'with actions' },
+    { kind: 'toggle', name: 'asyncSubmit', label: 'async submit' },
+  ],
+  snippet: (values) => {
+    const s = values as {
+      fieldCount: number;
+      showSummary: boolean;
+      showActions: boolean;
+      asyncSubmit: boolean;
+    };
+    const formAttrs: string[] = ['[formGroup]="form"', '(kjSubmit)="onSubmit()"'];
+    if (s.asyncSubmit) formAttrs.push('[kjAsyncSubmit]="submitHandler"');
+    const rows: string[] = [];
+    if (s.showSummary) rows.push('  <kj-form-summary />');
+    rows.push(
+      ...Array.from(FIELDS.slice(0, s.fieldCount)).map((f) => {
+        const ph = f.placeholder ? ` placeholder="${f.placeholder}"` : '';
+        return (
+          `  <kj-field>\n` +
+          `    <kj-field-label>${f.label}</kj-field-label>\n` +
+          `    <kj-input type="${f.type}" formControlName="${f.name}"${ph} />\n` +
+          `  </kj-field>`
+        );
+      }),
+    );
+    if (s.showActions) {
+      rows.push(
+        `  <kj-form-actions>\n` +
+        `    <kj-button kjVariant="ghost" kjType="reset">Cancel</kj-button>\n` +
+        `    <kj-button kjType="submit">Save</kj-button>\n` +
+        `  </kj-form-actions>`,
+      );
+    }
+    return `<form kj-form\n  ${formAttrs.join('\n  ')}\n>\n${rows.join('\n')}\n</form>`;
+  },
+};

package/src/form/form.spec.ts

@@ -0,0 +1,96 @@
+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, beforeEach } from 'vitest';
+import { KjFormActionsComponent, KjFormComponent, KjFormSummaryComponent } from './form';
+
+@Component({
+  standalone: true,
+  imports: [KjFormComponent, KjFormActionsComponent, KjFormSummaryComponent, ReactiveFormsModule],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <form
+      kj-form
+      [formGroup]="form"
+      (kjSubmit)="value.set($event)"
+      (kjInvalidSubmit)="invalid.set($event)"
+    >
+      @if (showSummary) {
+        <kj-form-summary />
+      }
+      <input id="email" formControlName="email" />
+      <input id="name" formControlName="name" />
+      <kj-form-actions>
+        <button type="submit">Save</button>
+      </kj-form-actions>
+    </form>
+  `,
+})
+class HostComponent {
+  form = new FormGroup({
+    email: new FormControl('', [Validators.required, Validators.email]),
+    name: new FormControl('', [Validators.required]),
+  });
+  value = signal<unknown>(null);
+  invalid = signal<unknown>(null);
+  showSummary = false;
+}
+
+describe('KjFormComponent', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({ imports: [HostComponent] });
+  });
+
+  it('applies the .kj-form class to the host <form>', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const form: HTMLFormElement = fixture.nativeElement.querySelector('form');
+    expect(form).not.toBeNull();
+    expect(form.classList.contains('kj-form')).toBe(true);
+  });
+
+  it('renders an action group with role="group"', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const actions: HTMLElement = fixture.nativeElement.querySelector('kj-form-actions');
+    expect(actions).not.toBeNull();
+    expect(actions.getAttribute('role')).toBe('group');
+  });
+
+  it('emits (kjSubmit) when valid', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    fixture.componentInstance.form.setValue({ email: 'a@b.co', name: 'Ada' });
+    fixture.nativeElement.querySelector('form').dispatchEvent(new Event('submit'));
+    expect(fixture.componentInstance.value()).toEqual({ email: 'a@b.co', name: 'Ada' });
+  });
+
+  it('emits (kjInvalidSubmit) when invalid', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    fixture.nativeElement.querySelector('form').dispatchEvent(new Event('submit'));
+    expect(fixture.componentInstance.value()).toBeNull();
+    expect(fixture.componentInstance.invalid()).toBe(fixture.componentInstance.form);
+  });
+
+  it('summary is hidden by default and visible after invalid submit', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.showSummary = true;
+    fixture.detectChanges();
+    const summary: HTMLElement = fixture.nativeElement.querySelector('kj-form-summary');
+    expect(summary.getAttribute('data-visible')).toBeNull();
+    fixture.nativeElement.querySelector('form').dispatchEvent(new Event('submit'));
+    fixture.detectChanges();
+    expect(summary.getAttribute('data-visible')).toBe('');
+  });
+
+  it('summary renders an item per invalid control', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.showSummary = true;
+    fixture.detectChanges();
+    fixture.nativeElement.querySelector('form').dispatchEvent(new Event('submit'));
+    fixture.detectChanges();
+    const items = fixture.nativeElement.querySelectorAll('kj-form-summary li');
+    expect(items.length).toBe(2);
+  });
+});

package/src/form/form.ts

@@ -0,0 +1,216 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  ViewEncapsulation,
+  computed,
+  inject,
+  input,
+  signal,
+} from '@angular/core';
+import {
+  KjForm,
+  KjFormErrorSummary,
+} from '@kouji-ui/core';
+
+/**
+ * Styled component-layer wrapper that attaches to a real `<form>` element
+ * via the attribute selector `form[kj-form]`. Composes the headless `KjForm`
+ * coordinator (submit interception, focus-on-first-error, async submitting,
+ * error summary) and applies the `.kj-form` class chrome.
+ *
+ * Use it as you would any `<form>`: the consumer keeps full control over
+ * `[formGroup]` (or `ngForm`) and `formControlName` bindings — they sit in
+ * the consumer's template, so projected content works without context
+ * gymnastics.
+ *
+ * Forward-only forwarding: every coordination knob lives on the underlying
+ * `KjForm` directive (composed via `hostDirectives`); this wrapper exists
+ * solely to stamp the class and own the `<kj-form-summary>` slot.
+ *
+ * @example
+ * ```html
+ * <form kj-form [formGroup]="form" (kjSubmit)="onSubmit($event)">
+ *   <kj-input formControlName="email" />
+ *   <kj-form-actions>
+ *     <kj-button kjType="submit">Sign in</kj-button>
+ *   </kj-form-actions>
+ * </form>
+ * ```
+ * @doc-example Default
+ *   A login form with email + password — anchors the default chrome and the
+ *   submit-on-valid plumbing.
+ *   @doc-file form.example.ts
+ * @doc-example Usage
+ *   Common form shapes — validation summary, reactive form, and an actions
+ *   row — assembled as a copy-paste starting point.
+ *   @doc-file form.usage.example.ts
+ * @doc-example Validation with summary
+ *   `<kj-form-summary />` lists invalid controls after a failed submit and
+ *   focuses on populate.
+ *   @doc-file form.validation.example.ts
+ * @doc-example Async submit
+ *   `[kjAsyncSubmit]` toggles `[kjSubmitting]` while a promise resolves —
+ *   wire to a button's `[kjLoading]`.
+ *   @doc-file form.async-submit.example.ts
+ * @doc-example Compound (multiple groups)
+ *   Multiple `<kj-field>` groups coordinated under a single
+ *   `<form kj-form>` parent.
+ *   @doc-file form.compound.example.ts
+ *
+ * @doc-keyboard
+ *   Enter — Submits the form when focus is inside any non-multiline control
+ *   Tab   — Moves focus across fields in DOM order
+ *
+ * @doc-aria
+ *   role="form"      — Native on the underlying <form>
+ *   aria-live        — kj-form-summary uses [kjPoliteness] (default polite) to announce errors
+ *   aria-busy        — Reflected on the form when [kjSubmitting] is true
+ *   data-submitting  — Mirrors [kjSubmitting] for theme CSS
+ *   data-invalid     — Mirrors the form's invalid state for theme CSS
+ *
+ * @doc-touch
+ *   The form itself is layout-only; touch-target compliance lives on each
+ *   projected control (`kj-input`, `kj-button`, etc.).
+ *
+ * @doc-a11y
+ *   `KjForm` intercepts submit so the form only fires `(kjSubmit)` when valid,
+ *   marks all controls as touched, focuses the first invalid control, and
+ *   optionally scrolls it into view. `<kj-form-summary>` reads the invalid
+ *   controls live and focuses on populate when configured.
+ *
+ * @doc-related field,input,button
+ *
+ * @doc-css-var
+ *   --kj-form-gap             — Vertical gap between projected form rows.
+ *   --kj-form-actions-gap     — Gap between buttons inside the actions row.
+ *   --kj-form-summary-bg      — Background fill for the error summary alert.
+ *   --kj-form-summary-fg      — Foreground text color of the error summary body.
+ *   --kj-form-summary-accent  — Accent color for the summary title and left bar.
+ *   --kj-form-summary-radius  — Corner radius of the error summary block.
+ *
+ * @doc-category Library/Data input
+ * @doc
+ * @doc-name form
+ * @doc-description Themed form host with submit interception, focus-on-first-error, async state, and an optional error summary.
+ * @doc-is-main
+ */
+@Component({
+  selector: 'kj-form, form[kj-form]',
+  standalone: true,
+  hostDirectives: [
+    {
+      directive: KjForm,
+      inputs: [
+        'kjFocusOnError',
+        'kjScrollOnError',
+        'kjScrollBehavior',
+        'kjScrollBlock',
+        'kjMarkAllAsTouchedOnSubmit',
+        'kjResetOnSuccess',
+        'kjAsyncSubmit',
+        'kjSubmitting',
+      ],
+      outputs: ['kjSubmit', 'kjInvalidSubmit', 'kjSubmittingChange'],
+    },
+  ],
+  template: `<ng-content />`,
+  styleUrl: './form.css',
+  encapsulation: ViewEncapsulation.None,
+  host: { class: 'kj-form' },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjFormComponent {}
+
+/**
+ * Slot for form action buttons (Submit, Cancel, …). Sets `role="group"` and
+ * defaults to right-aligned with a `var(--kj-form-actions-gap)` gap. Override
+ * alignment via `kjAlign` (`'start' | 'end' | 'center' | 'between'`).
+ *
+ * @example
+ * ```html
+ * <kj-form-actions>
+ *   <kj-button kjVariant="ghost" kjType="reset">Cancel</kj-button>
+ *   <kj-button kjType="submit">Save</kj-button>
+ * </kj-form-actions>
+ * ```
+ * @doc-category Library/Data input
+ * @doc
+ * @doc-name form
+ */
+@Component({
+  selector: 'kj-form-actions',
+  standalone: true,
+  template: `<ng-content />`,
+  styleUrl: './form.css',
+  encapsulation: ViewEncapsulation.None,
+  host: {
+    class: 'kj-form-actions',
+    role: 'group',
+    '[attr.aria-label]': 'kjLabel()',
+    '[attr.data-align]': 'kjAlign()',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjFormActionsComponent {
+  /** Accessible label for the action group. */
+  readonly kjLabel = input<string>('Form actions');
+  /** Alignment of the action row. Defaults to `'end'`. */
+  readonly kjAlign = input<'start' | 'end' | 'center' | 'between'>('end');
+}
+
+/**
+ * Live-region error summary that lists invalid controls after a failed
+ * submit. Reads from the parent `<form kj-form>` (via the injected `KjForm`)
+ * and renders an accessible alert-shaped block. Hidden when there are no
+ * invalid controls.
+ *
+ * Renders a `data-visible` attribute when there is at least one invalid
+ * control, allowing themes to drive show/hide via CSS without an `@if`.
+ *
+ * @example
+ * ```html
+ * <form kj-form [formGroup]="form">
+ *   <kj-form-summary />
+ *   <kj-input formControlName="email" />
+ *   <kj-form-actions><kj-button kjType="submit">Save</kj-button></kj-form-actions>
+ * </form>
+ * ```
+ * @doc-category Library/Data input
+ * @doc
+ * @doc-name form
+ */
+@Component({
+  selector: 'kj-form-summary',
+  standalone: true,
+  hostDirectives: [{ directive: KjFormErrorSummary, inputs: ['kjPoliteness', 'kjFocusOnPopulate'] }],
+  template: `
+    @if (visible()) {
+      <p class="kj-form-summary__title">{{ titleFor(invalidControls().length) }}</p>
+      <ul class="kj-form-summary__list">
+        @for (item of invalidControls(); track item.path) {
+          <li>{{ item.label }}</li>
+        }
+      </ul>
+    }
+  `,
+  styleUrl: './form.css',
+  encapsulation: ViewEncapsulation.None,
+  host: {
+    class: 'kj-form-summary',
+    '[attr.data-visible]': 'visible() ? "" : null',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjFormSummaryComponent {
+  private readonly form = inject(KjForm, { optional: true });
+  private readonly fallbackInvalid = signal<readonly { path: string; label: string }[]>([]);
+
+  protected readonly invalidControls = computed(
+    () => this.form?.invalidControls() ?? this.fallbackInvalid(),
+  );
+  protected readonly visible = computed(() => this.invalidControls().length > 0);
+
+  protected titleFor(count: number): string {
+    return count === 1 ? '1 error in this form' : `${count} errors in this form`;
+  }
+}

package/src/form/form.usage.example.ts

@@ -0,0 +1,63 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
+import { KjButtonComponent } from '../button/button';
+import { KjFieldComponent, KjFieldLabelComponent } from '../field/field';
+import { KjInputComponent } from '../input/input';
+import {
+  KjFormActionsComponent,
+  KjFormComponent,
+  KjFormSummaryComponent,
+} from './form';
+
+/**
+ * Common form shape — reactive group, summary, and actions row with a
+ * Cancel / Submit pair. Copy-paste starting point for new forms.
+ */
+@Component({
+  selector: 'kj-form-usage-example',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [
+    KjFormComponent,
+    KjFormActionsComponent,
+    KjFormSummaryComponent,
+    KjFieldComponent,
+    KjFieldLabelComponent,
+    KjInputComponent,
+    KjButtonComponent,
+    ReactiveFormsModule,
+  ],
+  styles: [`:host { display: block; max-width: 480px; }`],
+  template: `
+    <form kj-form [formGroup]="form" (kjSubmit)="onSubmit($event)">
+      <kj-form-summary />
+
+      <kj-field>
+        <kj-field-label>Email</kj-field-label>
+        <kj-input type="email" formControlName="email" placeholder="you@example.com" />
+      </kj-field>
+
+      <kj-field>
+        <kj-field-label>Password</kj-field-label>
+        <kj-input type="password" formControlName="password" />
+      </kj-field>
+
+      <kj-form-actions>
+        <kj-button kjVariant="ghost" kjType="reset">Cancel</kj-button>
+        <kj-button kjType="submit" [kjLoading]="busy()">Save</kj-button>
+      </kj-form-actions>
+    </form>
+  `,
+})
+export class KjFormUsageExample {
+  readonly busy = signal(false);
+  readonly form = new FormGroup({
+    email: new FormControl('', [Validators.required, Validators.email]),
+    password: new FormControl('', [Validators.required, Validators.minLength(8)]),
+  });
+
+  onSubmit(_value: unknown): void {
+    this.busy.set(true);
+    setTimeout(() => this.busy.set(false), 800);
+  }
+}

package/src/form/index.ts

@@ -0,0 +1,5 @@
+export {
+  KjFormComponent,
+  KjFormActionsComponent,
+  KjFormSummaryComponent,
+} from './form';