@kouji-ui/core 0.0.3 → 0.1.1

package/src/presets/size.spec.ts

@@ -0,0 +1,67 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { render } from '@testing-library/angular';
+import { describe, expect, it, vi, afterEach } from 'vitest';
+import { KJ_SIZE_PRESET, KjSize } from './size';
+
+@Component({
+  standalone: true,
+  imports: [KjSize],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `<button kjSize [kjSize]="value">x</button>`,
+})
+class HostComponent {
+  value: string | undefined = undefined;
+}
+
+describe('KjSize', () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it('reflects kjSize input as data-size on the host', async () => {
+    const { getByRole } = await render(`<button kjSize [kjSize]="'lg'">x</button>`, {
+      imports: [KjSize],
+      providers: [{ provide: KJ_SIZE_PRESET, useValue: { values: ['md', 'lg'], default: 'md' } }],
+    });
+    expect(getByRole('button')).toHaveAttribute('data-size', 'lg');
+  });
+
+  it('falls back to KJ_SIZE_PRESET.default when input not set', async () => {
+    TestBed.configureTestingModule({
+      providers: [{ provide: KJ_SIZE_PRESET, useValue: { values: ['xs', 'md'], default: 'md' } }],
+    });
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const btn = fixture.nativeElement.querySelector('button');
+    expect(btn.getAttribute('data-size')).toBe('md');
+  });
+
+  it('uses the built-in factory default when no provider is registered', async () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const btn = fixture.nativeElement.querySelector('button');
+    expect(btn.getAttribute('data-size')).toBe('md');
+  });
+
+  it('warns once in dev mode for an unknown value', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    TestBed.configureTestingModule({
+      providers: [{ provide: KJ_SIZE_PRESET, useValue: { values: ['xs', 'md'], default: 'md' } }],
+    });
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.value = 'bogus';
+    fixture.detectChanges();
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn.mock.calls[0][0]).toMatch(/unknown size/i);
+  });
+
+  it('does not warn for a known value', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    TestBed.configureTestingModule({
+      providers: [{ provide: KJ_SIZE_PRESET, useValue: { values: ['xs', 'md'], default: 'md' } }],
+    });
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.value = 'xs';
+    fixture.detectChanges();
+    expect(warn).not.toHaveBeenCalled();
+  });
+});

package/src/presets/size.ts

@@ -0,0 +1,59 @@
+import { Directive, InjectionToken, InputSignalWithTransform, effect, inject, input, isDevMode } from '@angular/core';
+
+/**
+ * Shape of the preset configuration consumed by `KjSize`. One per consumer
+ * directive, provided via `bindPresets` from a per-component config token.
+ *
+ * @internal
+ */
+export interface KjSizePreset {
+  values: string[];
+  default: string;
+}
+
+/**
+ * DI token holding the size preset for the current consumer's injector scope.
+ * Resolved by `KjSize` at construction time.
+ *
+ * Default factory: `{ values: ['md'], default: 'md' }`.
+ *
+ * @internal
+ */
+export const KJ_SIZE_PRESET = new InjectionToken<KjSizePreset>('kj.size.preset', {
+  factory: () => ({ values: ['md'], default: 'md' }),
+});
+
+/**
+ * Internal preset directive composed via `hostDirectives` by every stylistic
+ * component to expose a configurable `size` input that reflects to a
+ * `data-size` host attribute. App code does not import this directly.
+ *
+ * @internal
+ */
+@Directive({
+  selector: '[kjSize]',
+  standalone: true,
+  host: { '[attr.data-size]': 'kjSize()' },
+})
+export class KjSize {
+  private readonly preset = inject(KJ_SIZE_PRESET);
+
+  // See `KjVariant.kjVariant` for why the field type is annotated explicitly.
+  readonly kjSize: InputSignalWithTransform<string, string | undefined> = input(
+    this.preset.default,
+    { transform: (v?: string) => v || this.preset.default },
+  );
+
+  constructor() {
+    if (isDevMode()) {
+      effect(() => {
+        const v = this.kjSize();
+        if (!this.preset.values.includes(v)) {
+          console.warn(
+            `[kj] unknown size "${v}". Allowed values: ${this.preset.values.join(', ')}.`,
+          );
+        }
+      });
+    }
+  }
+}

package/src/presets/variant.spec.ts

@@ -0,0 +1,72 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { render } from '@testing-library/angular';
+import { describe, expect, it, vi, afterEach } from 'vitest';
+import { KJ_VARIANT_PRESET, KjVariant } from './variant';
+
+@Component({
+  standalone: true,
+  imports: [KjVariant],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `<button kjVariant [kjVariant]="value">x</button>`,
+})
+class HostComponent {
+  value: string | undefined = undefined;
+}
+
+describe('KjVariant', () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it('reflects kjVariant input as data-variant on the host', async () => {
+    const { getByRole } = await render(`<button kjVariant [kjVariant]="'destructive'">x</button>`, {
+      imports: [KjVariant],
+      providers: [
+        {
+          provide: KJ_VARIANT_PRESET,
+          useValue: { values: ['default', 'destructive'], default: 'default' },
+        },
+      ],
+    });
+    expect(getByRole('button')).toHaveAttribute('data-variant', 'destructive');
+  });
+
+  it('falls back to KJ_VARIANT_PRESET.default when input not set', async () => {
+    TestBed.configureTestingModule({
+      providers: [{ provide: KJ_VARIANT_PRESET, useValue: { values: ['a', 'b'], default: 'b' } }],
+    });
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const btn = fixture.nativeElement.querySelector('button');
+    expect(btn.getAttribute('data-variant')).toBe('b');
+  });
+
+  it('uses the built-in factory default when no provider is registered', async () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const btn = fixture.nativeElement.querySelector('button');
+    expect(btn.getAttribute('data-variant')).toBe('default');
+  });
+
+  it('warns once in dev mode for an unknown value', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    TestBed.configureTestingModule({
+      providers: [{ provide: KJ_VARIANT_PRESET, useValue: { values: ['a', 'b'], default: 'a' } }],
+    });
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.value = 'bogus';
+    fixture.detectChanges();
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn.mock.calls[0][0]).toMatch(/unknown variant/i);
+  });
+
+  it('does not warn for a known value', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    TestBed.configureTestingModule({
+      providers: [{ provide: KJ_VARIANT_PRESET, useValue: { values: ['a', 'b'], default: 'a' } }],
+    });
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.value = 'b';
+    fixture.detectChanges();
+    expect(warn).not.toHaveBeenCalled();
+  });
+});

package/src/presets/variant.ts

@@ -0,0 +1,62 @@
+import { Directive, InjectionToken, InputSignalWithTransform, effect, inject, input, isDevMode } from '@angular/core';
+
+/**
+ * Shape of the preset configuration consumed by `KjVariant`. One per consumer
+ * directive, provided via `bindPresets` from a per-component config token.
+ *
+ * @internal
+ */
+export interface KjVariantPreset {
+  values: string[];
+  default: string;
+}
+
+/**
+ * DI token holding the variant preset for the current consumer's injector
+ * scope. Resolved by `KjVariant` at construction time.
+ *
+ * Default factory: `{ values: ['default'], default: 'default' }`.
+ *
+ * @internal
+ */
+export const KJ_VARIANT_PRESET = new InjectionToken<KjVariantPreset>('kj.variant.preset', {
+  factory: () => ({ values: ['default'], default: 'default' }),
+});
+
+/**
+ * Internal preset directive composed via `hostDirectives` by every stylistic
+ * component to expose a configurable `variant` input that reflects to a
+ * `data-variant` host attribute. App code does not import this directly.
+ *
+ * @internal
+ */
+@Directive({
+  selector: '[kjVariant]',
+  standalone: true,
+  host: { '[attr.data-variant]': 'kjVariant()' },
+})
+export class KjVariant {
+  private readonly preset = inject(KJ_VARIANT_PRESET);
+
+  // Explicit field annotation pins the ng-packagr-emitted .d.ts shape —
+  // without it ng-packagr collapses the write type to `string` (dropping the
+  // `| undefined` flow-through), which trips the docs extractor and any
+  // consumer trying to bind a `string | undefined` source.
+  readonly kjVariant: InputSignalWithTransform<string, string | undefined> = input(
+    this.preset.default,
+    { transform: (v?: string) => v || this.preset.default },
+  );
+
+  constructor() {
+    if (isDevMode()) {
+      effect(() => {
+        const v = this.kjVariant();
+        if (!this.preset.values.includes(v)) {
+          console.warn(
+            `[kj] unknown variant "${v}". Allowed values: ${this.preset.values.join(', ')}.`,
+          );
+        }
+      });
+    }
+  }
+}

package/src/primitives/directionality/directionality.spec.ts

@@ -0,0 +1,112 @@
+import { Component, PLATFORM_ID, inject } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { render } from '@testing-library/angular';
+import { KjDirectionality } from './directionality';
+
+/**
+ * Helpers — flush microtasks + the rAF that backs afterNextRender so the
+ * service has a chance to run its initial read and attach the observer.
+ */
+async function flushAfterNextRender(): Promise<void> {
+  // Allow any queued afterNextRender callbacks to run, then flush
+  // microtasks twice (Angular batches signal updates).
+  await new Promise<void>((resolve) => setTimeout(resolve, 0));
+  await Promise.resolve();
+  await Promise.resolve();
+}
+
+function setHtmlDir(value: string | null): void {
+  if (value === null) {
+    document.documentElement.removeAttribute('dir');
+  } else {
+    document.documentElement.setAttribute('dir', value);
+  }
+}
+
+describe('KjDirectionality', () => {
+  afterEach(() => {
+    setHtmlDir(null);
+    document.body.removeAttribute('dir');
+  });
+
+  it('reads "ltr" initially when <html dir="ltr">', async () => {
+    setHtmlDir('ltr');
+
+    @Component({ standalone: true, template: '' })
+    class Host {
+      readonly dir = inject(KjDirectionality);
+    }
+    const { fixture } = await render(Host);
+    await flushAfterNextRender();
+
+    expect(fixture.componentInstance.dir.current()).toBe('ltr');
+  });
+
+  it('reads "rtl" initially when <html dir="rtl">', async () => {
+    setHtmlDir('rtl');
+
+    @Component({ standalone: true, template: '' })
+    class Host {
+      readonly dir = inject(KjDirectionality);
+    }
+    const { fixture } = await render(Host);
+    await flushAfterNextRender();
+
+    expect(fixture.componentInstance.dir.current()).toBe('rtl');
+  });
+
+  it('defaults to "ltr" when no dir attribute is set on <html> or <body>', async () => {
+    setHtmlDir(null);
+    document.body.removeAttribute('dir');
+
+    @Component({ standalone: true, template: '' })
+    class Host {
+      readonly dir = inject(KjDirectionality);
+    }
+    const { fixture } = await render(Host);
+    await flushAfterNextRender();
+
+    expect(fixture.componentInstance.dir.current()).toBe('ltr');
+  });
+
+  it('updates the signal when <html dir> changes via MutationObserver', async () => {
+    setHtmlDir('ltr');
+
+    @Component({ standalone: true, template: '' })
+    class Host {
+      readonly dir = inject(KjDirectionality);
+    }
+    const { fixture } = await render(Host);
+    await flushAfterNextRender();
+
+    const svc = fixture.componentInstance.dir;
+    expect(svc.current()).toBe('ltr');
+
+    setHtmlDir('rtl');
+    // Allow MutationObserver microtask to deliver and the signal to update.
+    await flushAfterNextRender();
+
+    expect(svc.current()).toBe('rtl');
+
+    setHtmlDir('ltr');
+    await flushAfterNextRender();
+
+    expect(svc.current()).toBe('ltr');
+  });
+
+  it('returns "ltr" on the server (PLATFORM_ID="server") without DOM access', () => {
+    // Spy proves the SSR path never touches documentElement.getAttribute.
+    const getAttrSpy = vi.spyOn(document.documentElement, 'getAttribute');
+
+    TestBed.resetTestingModule();
+    TestBed.configureTestingModule({
+      providers: [{ provide: PLATFORM_ID, useValue: 'server' }],
+    });
+
+    const svc = TestBed.inject(KjDirectionality);
+    expect(svc.current()).toBe('ltr');
+    expect(getAttrSpy).not.toHaveBeenCalled();
+
+    getAttrSpy.mockRestore();
+  });
+});

package/src/primitives/directionality/directionality.ts

@@ -0,0 +1,89 @@
+import {
+  DOCUMENT,
+  DestroyRef,
+  Injectable,
+  PLATFORM_ID,
+  Signal,
+  afterNextRender,
+  inject,
+  signal,
+} from '@angular/core';
+import { isPlatformBrowser } from '@angular/common';
+
+/** Logical text direction. */
+export type KjDirection = 'ltr' | 'rtl';
+
+/**
+ * Reads the document's logical text direction (`<html dir>`, falling back to
+ * `<body dir>`) and exposes it as a signal that updates when the attribute
+ * changes. SSR-safe — on the server the signal returns `'ltr'` and no DOM
+ * APIs are touched.
+ *
+ * Use this for RTL-aware behaviour in directives that cannot rely on CSS
+ * (e.g. computing logical positions, emitting `[attr.data-direction]`,
+ * choosing arrow-key handlers).
+ *
+ * @example
+ * ```ts
+ * private readonly dir = inject(KjDirectionality);
+ * readonly isRtl = computed(() => this.dir.current() === 'rtl');
+ * ```
+ * @doc-category Core/Primitives
+ */
+@Injectable({ providedIn: 'root' })
+export class KjDirectionality {
+  private readonly platformId = inject(PLATFORM_ID);
+  private readonly destroyRef = inject(DestroyRef);
+  private readonly doc = inject(DOCUMENT, { optional: true }) as Document | null;
+
+  private readonly _current = signal<KjDirection>('ltr');
+
+  /**
+   * Current document direction. `'ltr'` on the server and as the fallback
+   * when no `dir` attribute is set.
+   */
+  readonly current: Signal<KjDirection> = this._current.asReadonly();
+
+  constructor() {
+    if (!isPlatformBrowser(this.platformId) || !this.doc) {
+      // SSR: leave the default `'ltr'` and skip all DOM access.
+      return;
+    }
+
+    // Read the initial value as soon as the DOM is ready. afterNextRender
+    // guarantees a browser context and avoids reading during SSR.
+    afterNextRender(() => {
+      this._current.set(this.read());
+
+      const html = this.doc!.documentElement;
+      const observer = new MutationObserver(() => {
+        const next = this.read();
+        if (next !== this._current()) {
+          this._current.set(next);
+        }
+      });
+      observer.observe(html, {
+        attributes: true,
+        attributeFilter: ['dir'],
+        subtree: false,
+      });
+
+      this.destroyRef.onDestroy(() => observer.disconnect());
+    });
+  }
+
+  /**
+   * Reads the effective direction from `<html dir>`, falling back to
+   * `<body dir>`, then `'ltr'`. Any value other than `'rtl'` collapses to
+   * `'ltr'` — `dir="auto"` is treated as LTR until the browser computes
+   * something more specific (which we cannot observe via attribute changes).
+   */
+  private read(): KjDirection {
+    const doc = this.doc;
+    if (!doc) return 'ltr';
+    const htmlDir = doc.documentElement?.getAttribute('dir');
+    const bodyDir = doc.body?.getAttribute('dir');
+    const value = (htmlDir ?? bodyDir ?? '').toLowerCase();
+    return value === 'rtl' ? 'rtl' : 'ltr';
+  }
+}

package/src/primitives/directionality/index.ts

@@ -0,0 +1 @@
+export { KjDirectionality, type KjDirection } from './directionality';

package/src/primitives/forms/form-control.spec.ts

@@ -1,7 +1,7 @@
-import { Component } from '@angular/core';
+import { Component, ChangeDetectionStrategy } from '@angular/core';
 import { FormControl, ReactiveFormsModule } from '@angular/forms';
-import { render, fireEvent } from '@testing-library/angular';
-import { axe, toHaveNoViolations } from 'jest-axe';
+import { render } from '@testing-library/angular';
+import { toHaveNoViolations } from 'jest-axe';
 import { KjFormControl } from './form-control';
 
 expect.extend(toHaveNoViolations);
@@ -9,12 +9,18 @@ expect.extend(toHaveNoViolations);
 @Component({
   standalone: true,
   imports: [KjFormControl, ReactiveFormsModule],
-  template: `<input kjFormControl [formControl]="ctrl" (input)="onInput($event)" (blur)="onBlur()" />`,
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `<input
+    kjFormControl
+    [formControl]="ctrl"
+    (input)="onInput($event)"
+    (blur)="onBlur()"
+  />`,
 })
 class TestHostComponent {
   ctrl = new FormControl('');
   formCtrl!: KjFormControl;
-  onInput(e: Event): void {
+  onInput(_e: Event): void {
     // will be wired by the directive consumer pattern
   }
   onBlur(): void {}
@@ -44,7 +50,9 @@ describe('KjFormControl', () => {
     const { fixture } = await render(TestHostComponent);
     const directive = fixture.debugElement.children[0].injector.get(KjFormControl);
     let emitted: unknown;
-    directive.registerOnChange((v) => { emitted = v; });
+    directive.registerOnChange((v) => {
+      emitted = v;
+    });
     directive.notifyChange('test');
     expect(directive.value()).toBe('test');
     expect(emitted).toBe('test');

package/src/primitives/forms/form-control.ts

@@ -1,4 +1,4 @@
-import { Directive, forwardRef, signal } from '@angular/core';
+import { Directive, forwardRef, signal } from '@angular/core';
 import { ControlValueAccessor, NG_VALUE_ACCESSOR } from '@angular/forms';
 
 /**
@@ -23,7 +23,11 @@ import { ControlValueAccessor, NG_VALUE_ACCESSOR } from '@angular/forms';
  *   readonly formCtrl = inject(KjFormControl);
  * }
  * ```
- * @category Core/Primitives
+ * @doc-category Core/Primitives
+ * @doc
+ * @doc-name forms
+ * @doc-description Wires any input directive into Angular reactive and template-driven forms.
+ * @doc-is-main
  */
 @Directive({
   selector: '[kjFormControl]',

package/src/primitives/index.ts

@@ -1,3 +1,6 @@
 export * from './interaction/index';
 export * from './forms/index';
 export * from './overlay/index';
+export * from './directionality/index';
+export * from './list/index';
+export * from './signals/index';

package/src/primitives/interaction/disabled.ts

@@ -1,14 +1,21 @@
-import { Directive, input } from '@angular/core';
+import { Directive, booleanAttribute, input } from '@angular/core';
 
 /**
  * Applies disabled state to any element via ARIA and data attributes.
- * Compose via `hostDirectives` on other directives to add disabled behavior.
+ *
+ * Compose via `hostDirectives` on other directives to add disabled behaviour.
+ * The directive reflects `aria-disabled` and `data-disabled` so consumers do
+ * not need to repeat the same host-binding pattern on every input.
  *
  * @example
  * ```html
- * <button kjButton [kjDisabled]="isLoading()">Submit</button>
+ * <div kjDisabled [kjDisabled]="isLoading()">Content</div>
  * ```
- * @category Core/Primitives
+ * @doc-category Core/Primitives
+ * @doc
+ * @doc-name interaction
+ * @doc-description Adds accessible disabled state to any element you compose it onto.
+ * @doc-is-main
  */
 @Directive({
   selector: '[kjDisabled]',
@@ -20,5 +27,5 @@
 })
 export class KjDisabled {
   /** Whether the element is disabled. Reflects via `aria-disabled` and `data-disabled`. */
-  readonly disabled = input<boolean>(false, { alias: 'kjDisabled' });
+  readonly disabled = input<boolean, unknown>(false, { alias: 'kjDisabled', transform: booleanAttribute });
 }

package/src/primitives/interaction/focus-ring.ts

@@ -1,4 +1,4 @@
-import { Directive, DestroyRef, ElementRef, afterNextRender, inject, signal } from '@angular/core';
+import { Directive, DestroyRef, ElementRef, afterNextRender, inject, signal } from '@angular/core';
 import { PLATFORM_ID } from '@angular/core';
 import { isPlatformBrowser } from '@angular/common';
 
@@ -11,7 +11,9 @@ import { isPlatformBrowser } from '@angular/common';
  * ```html
  * <button kjFocusRing>Focusable button</button>
  * ```
- * @category Core/Primitives
+ * @doc-category Core/Primitives
+ * @doc
+ * @doc-name interaction
  */
 @Directive({
   selector: '[kjFocusRing]',