@kouji-ui/components 0.1.1 → 0.1.3

package/src/form/form.css

@@ -1,63 +0,0 @@
-@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

@@ -1,145 +0,0 @@
-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

@@ -1,96 +0,0 @@
-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

@@ -1,216 +0,0 @@
-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

@@ -1,63 +0,0 @@
-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

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