@kouji-ui/core 0.0.4 → 0.1.1

package/src/tag/tag.spec.ts

@@ -0,0 +1,240 @@
+import { Component, signal } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { render, fireEvent } from '@testing-library/angular';
+import { describe, expect, it } from 'vitest';
+import { KjTag } from './tag';
+import { KjTagRemove } from './tag-remove';
+import { KjTagList } from './tag-list';
+
+const imports = [KjTag, KjTagRemove, KjTagList];
+
+describe('KjTag', () => {
+  it('decorative by default — omits role and tabindex', async () => {
+    const { container } = await render(`<span kjTag>Acme</span>`, { imports });
+    const host = container.querySelector('span')!;
+    expect(host).not.toHaveAttribute('role');
+    expect(host).not.toHaveAttribute('tabindex');
+    expect(host).not.toHaveAttribute('aria-pressed');
+    expect(host).not.toHaveAttribute('aria-selected');
+  });
+
+  it('selectable mode sets role="button", tabindex="0", and aria-pressed', async () => {
+    const { container } = await render(
+      `<span kjTag [kjTagSelectable]="true">Filter</span>`,
+      { imports },
+    );
+    const host = container.querySelector('span')!;
+    expect(host).toHaveAttribute('role', 'button');
+    expect(host).toHaveAttribute('tabindex', '0');
+    expect(host).toHaveAttribute('aria-pressed', 'false');
+  });
+
+  it('selectable mode toggles aria-pressed on click', async () => {
+    @Component({
+      standalone: true,
+      imports,
+      template: `<span kjTag [kjTagSelectable]="true" [(kjTagSelected)]="on">Filter</span>`,
+    })
+    class Host {
+      readonly on = signal(false);
+    }
+
+    TestBed.configureTestingModule({ imports: [Host] });
+    const fixture = TestBed.createComponent(Host);
+    fixture.detectChanges();
+    const el = fixture.nativeElement.querySelector('span')!;
+    expect(el.getAttribute('aria-pressed')).toBe('false');
+    el.click();
+    fixture.detectChanges();
+    expect(fixture.componentInstance.on()).toBe(true);
+    expect(el.getAttribute('aria-pressed')).toBe('true');
+  });
+
+  it('Space key activates selectable chip and prevents default', async () => {
+    @Component({
+      standalone: true,
+      imports,
+      template: `<span kjTag [kjTagSelectable]="true" [(kjTagSelected)]="on">x</span>`,
+    })
+    class Host {
+      readonly on = signal(false);
+    }
+
+    TestBed.configureTestingModule({ imports: [Host] });
+    const fixture = TestBed.createComponent(Host);
+    fixture.detectChanges();
+    const el = fixture.nativeElement.querySelector('span')!;
+    fireEvent.keyDown(el, { key: ' ' });
+    fixture.detectChanges();
+    expect(fixture.componentInstance.on()).toBe(true);
+  });
+
+  it('forwards kjVariant to KjVariant via host directive composition', async () => {
+    const { container } = await render(
+      `<span kjTag [kjVariant]="'success'">x</span>`,
+      { imports },
+    );
+    expect(container.querySelector('span')).toHaveAttribute('data-variant', 'success');
+  });
+
+  it('forwards kjSize to KjSize via host directive composition', async () => {
+    const { container } = await render(
+      `<span kjTag [kjSize]="'xs'">x</span>`,
+      { imports },
+    );
+    expect(container.querySelector('span')).toHaveAttribute('data-size', 'xs');
+  });
+
+  it('forwards kjTagDisabled to KjDisabled and reflects aria-disabled', async () => {
+    const { container } = await render(
+      `<span kjTag [kjTagSelectable]="true" [kjTagDisabled]="true">x</span>`,
+      { imports },
+    );
+    const host = container.querySelector('span')!;
+    expect(host).toHaveAttribute('aria-disabled', 'true');
+    expect(host).toHaveAttribute('data-disabled', '');
+    // Disabled selectable chip stays focusable but at tabindex="-1".
+    expect(host).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('disabled chip click does not toggle selection', () => {
+    @Component({
+      standalone: true,
+      imports,
+      template: `<span kjTag [kjTagSelectable]="true" [kjTagDisabled]="true" [(kjTagSelected)]="on">x</span>`,
+    })
+    class Host {
+      readonly on = signal(false);
+    }
+    TestBed.configureTestingModule({ imports: [Host] });
+    const fixture = TestBed.createComponent(Host);
+    fixture.detectChanges();
+    const el = fixture.nativeElement.querySelector('span')!;
+    el.click();
+    fixture.detectChanges();
+    expect(fixture.componentInstance.on()).toBe(false);
+  });
+});
+
+describe('KjTagRemove', () => {
+  it('auto-derives aria-label from the parent tag textContent', async () => {
+    const { container } = await render(
+      `<span kjTag>Acme Corp<button kjTagRemove>×</button></span>`,
+      { imports },
+    );
+    const btn = container.querySelector('button')!;
+    expect(btn.getAttribute('aria-label')).toMatch(/^Remove\s+Acme Corp/);
+  });
+
+  it('respects kjTagRemoveLabel override', async () => {
+    const { container } = await render(
+      `<span kjTag>Acme<button kjTagRemove kjTagRemoveLabel="Dismiss filter">×</button></span>`,
+      { imports },
+    );
+    expect(container.querySelector('button')).toHaveAttribute('aria-label', 'Dismiss filter');
+  });
+
+  it('respects kjTagLabel override on the parent for label derivation', async () => {
+    const { container } = await render(
+      `<span kjTag kjTagLabel="Acme Corp">x<button kjTagRemove>×</button></span>`,
+      { imports },
+    );
+    expect(container.querySelector('button')).toHaveAttribute('aria-label', 'Remove Acme Corp');
+  });
+
+  it('emits (kjTagRemoved) on click', () => {
+    @Component({
+      standalone: true,
+      imports,
+      template: `<span kjTag (kjTagRemoved)="hits.set(hits() + 1)">Acme<button kjTagRemove>×</button></span>`,
+    })
+    class Host {
+      readonly hits = signal(0);
+    }
+    TestBed.configureTestingModule({ imports: [Host] });
+    const fixture = TestBed.createComponent(Host);
+    fixture.detectChanges();
+    fixture.nativeElement.querySelector('button')!.click();
+    fixture.detectChanges();
+    expect(fixture.componentInstance.hits()).toBe(1);
+  });
+
+  it('does not emit (kjTagRemoved) when the parent tag is disabled', () => {
+    @Component({
+      standalone: true,
+      imports,
+      template: `<span kjTag [kjTagDisabled]="true" (kjTagRemoved)="hits.set(hits() + 1)">x<button kjTagRemove>×</button></span>`,
+    })
+    class Host {
+      readonly hits = signal(0);
+    }
+    TestBed.configureTestingModule({ imports: [Host] });
+    const fixture = TestBed.createComponent(Host);
+    fixture.detectChanges();
+    fixture.nativeElement.querySelector('button')!.click();
+    fixture.detectChanges();
+    expect(fixture.componentInstance.hits()).toBe(0);
+  });
+});
+
+describe('KjTagList', () => {
+  it('propagates listbox role into chips as role="option" with aria-selected', async () => {
+    const { container } = await render(
+      `
+      <div kjTagList kjTagListRole="listbox" [kjTagListMultiple]="true" aria-label="Filters">
+        <span kjTag>One</span>
+        <span kjTag [kjTagSelected]="true">Two</span>
+      </div>
+      `,
+      { imports },
+    );
+    const list = container.querySelector('[kjTagList]')!;
+    expect(list).toHaveAttribute('role', 'listbox');
+    expect(list).toHaveAttribute('aria-multiselectable', 'true');
+    const chips = container.querySelectorAll('[kjTag]');
+    expect(chips[0]).toHaveAttribute('role', 'option');
+    expect(chips[0]).toHaveAttribute('aria-selected', 'false');
+    expect(chips[1]).toHaveAttribute('aria-selected', 'true');
+  });
+
+  it('propagates grid role into chips as role="row"', async () => {
+    const { container } = await render(
+      `
+      <div kjTagList kjTagListRole="grid">
+        <span kjTag>One</span>
+      </div>
+      `,
+      { imports },
+    );
+    expect(container.querySelector('[kjTagList]')).toHaveAttribute('role', 'grid');
+    expect(container.querySelector('[kjTag]')).toHaveAttribute('role', 'row');
+  });
+
+  it('group role does not force a chip role nor aria-selected', async () => {
+    const { container } = await render(
+      `
+      <div kjTagList>
+        <span kjTag>One</span>
+      </div>
+      `,
+      { imports },
+    );
+    expect(container.querySelector('[kjTagList]')).toHaveAttribute('role', 'group');
+    const chip = container.querySelector('[kjTag]')!;
+    expect(chip).not.toHaveAttribute('role');
+    expect(chip).not.toHaveAttribute('aria-selected');
+  });
+
+  it('cascades kjTagListDisabled into each chip', async () => {
+    const { container } = await render(
+      `
+      <div kjTagList kjTagListRole="listbox" [kjTagListDisabled]="true">
+        <span kjTag>One</span>
+      </div>
+      `,
+      { imports },
+    );
+    const chip = container.querySelector('[kjTag]')!;
+    expect(chip).toHaveAttribute('aria-disabled', 'true');
+  });
+});

package/src/tag/tag.ts

@@ -0,0 +1,203 @@
+import {
+  DestroyRef,
+  Directive,
+  ElementRef,
+  PLATFORM_ID,
+  Signal,
+  afterNextRender,
+  computed,
+  inject,
+  input,
+  model,
+  output,
+  signal,
+} from '@angular/core';
+import { isPlatformBrowser } from '@angular/common';
+import { KjFocusRing } from '../primitives/interaction/focus-ring';
+import { KjDisabled } from '../primitives/interaction/disabled';
+import { KjSize, KjVariant, bindPresets } from '../presets';
+import { KJ_TAG, KJ_TAG_LIST, KjTagContext } from './tag.context';
+import { KJ_TAG_CONFIG } from './config';
+
+/**
+ * Root tag/chip directive. Renders one of four shapes from the same DOM
+ * skeleton — decorative, removable, selectable, or input-chip — chosen by
+ * inputs and the optional `KjTagList` container the host is rendered in.
+ *
+ * The host element stays element-agnostic (the wrapper picks `<button>` vs.
+ * `<span>`); this directive owns the role / `tabindex` / `aria-pressed` /
+ * `aria-selected` attribute decisions and the projected-text label signal
+ * consumed by `KjTagRemove` to build its accessible name.
+ *
+ * @example
+ * ```html
+ * <span kjTag>Decorative</span>
+ *
+ * <span kjTag>
+ *   Acme
+ *   <button kjTagRemove>×</button>
+ * </span>
+ *
+ * <span kjTag kjTagSelectable [(kjTagSelected)]="on">Toggle</span>
+ * ```
+ * @doc-category Core/Data display
+ * @doc
+ * @doc-name tag
+ * @doc-description Unstyled tag or chip with decorative, removable, selectable, or listbox option modes.
+ * @doc-is-main
+ */
+@Directive({
+  selector: '[kjTag]',
+  standalone: true,
+  providers: [
+    { provide: KJ_TAG, useExisting: KjTag },
+    ...bindPresets(KJ_TAG_CONFIG),
+  ],
+  hostDirectives: [
+    { directive: KjVariant, inputs: ['kjVariant'] },
+    { directive: KjSize, inputs: ['kjSize'] },
+    { directive: KjDisabled, inputs: ['kjDisabled: kjTagDisabled'] },
+    KjFocusRing,
+  ],
+  host: {
+    '[attr.role]': 'computedRole()',
+    '[attr.tabindex]': 'computedTabindex()',
+    '[attr.aria-pressed]': 'computedPressed()',
+    '[attr.aria-selected]': 'computedSelected()',
+    '[attr.aria-disabled]': 'disabled() ? "true" : null',
+    '[attr.data-selected]': 'kjTagSelected() ? "" : null',
+    '[attr.data-disabled]': 'disabled() ? "" : null',
+    '(click)': 'onClick($event)',
+    '(keydown.space)': 'onActivate($event)',
+    '(keydown.enter)': 'onActivate($event)',
+  },
+})
+export class KjTag implements KjTagContext {
+  private readonly el = inject<ElementRef<HTMLElement>>(ElementRef);
+  private readonly destroyRef = inject(DestroyRef);
+  private readonly platformId = inject(PLATFORM_ID);
+  private readonly list = inject(KJ_TAG_LIST, { optional: true });
+
+  /** Enables toggle-button behaviour. Standalone selectable chips become `role="button"` + `aria-pressed`. */
+  readonly kjTagSelectable = input(false);
+
+  /** Two-way bound selection state; only meaningful when `kjTagSelectable` is true or inside a listbox container. */
+  readonly kjTagSelected = model(false);
+
+  /**
+   * Optional explicit text label. When set, `KjTagRemove` reads this for its
+   * auto-generated `aria-label` instead of the `MutationObserver`-derived
+   * projected text content.
+   */
+  readonly kjTagLabel = input<string | undefined>(undefined);
+
+  /** Disabled state, aliased through `KjDisabled` from `kjTagDisabled`. */
+  readonly kjTagDisabled = input(false);
+
+  /** Fires when this tag's projected `KjTagRemove` is activated. */
+  readonly kjTagRemoved = output<void>();
+
+  private readonly _textContent = signal('');
+
+  /** Live projected text content. Powers `KjTagRemove`'s auto aria-label. */
+  readonly textContent: Signal<string> = computed(
+    () => this.kjTagLabel() ?? this._textContent(),
+  );
+
+  /** Selection state exposed via `KjTagContext` for child directives. */
+  readonly selected: Signal<boolean> = this.kjTagSelected.asReadonly();
+
+  /**
+   * Effective disabled state: the tag's own `kjTagDisabled` OR the parent
+   * `KjTagList`'s cascading `disabled` signal.
+   */
+  readonly disabled: Signal<boolean> = computed(
+    () => this.kjTagDisabled() || (this.list?.disabled() ?? false),
+  );
+
+  /**
+   * Role decision tree. Container wins first:
+   * - `KjTagList[role="listbox"]` -> `option`
+   * - `KjTagList[role="grid"]`    -> `row`
+   * - else if `kjTagSelectable`   -> `button`
+   * - else                        -> null (decorative).
+   */
+  protected readonly computedRole = computed<string | null>(() => {
+    const listRole = this.list?.role();
+    if (listRole === 'listbox') return 'option';
+    if (listRole === 'grid') return 'row';
+    if (this.kjTagSelectable()) return 'button';
+    return null;
+  });
+
+  /** Focusable iff interactive (selectable, listbox option, or grid row). */
+  protected readonly computedTabindex = computed<string | null>(() => {
+    if (this.computedRole() === null) return null;
+    return this.disabled() ? '-1' : '0';
+  });
+
+  /** `aria-pressed` only on standalone selectable chips (the toggle-button pattern). */
+  protected readonly computedPressed = computed<string | null>(() => {
+    if (this.list) return null;
+    if (!this.kjTagSelectable()) return null;
+    return this.kjTagSelected() ? 'true' : 'false';
+  });
+
+  /** `aria-selected` for chips inside a listbox container; never on grid rows / decorative. */
+  protected readonly computedSelected = computed<string | null>(() => {
+    if (this.list?.role() !== 'listbox') return null;
+    return this.kjTagSelected() ? 'true' : 'false';
+  });
+
+  constructor() {
+    afterNextRender(() => {
+      // Always seed once on first render so SSR-rendered text is captured
+      // immediately. The MutationObserver attaches in browsers only.
+      this._textContent.set(this.el.nativeElement.textContent?.trim() ?? '');
+
+      if (!isPlatformBrowser(this.platformId)) return;
+      if (typeof MutationObserver === 'undefined') return;
+
+      const observer = new MutationObserver(() => {
+        this._textContent.set(this.el.nativeElement.textContent?.trim() ?? '');
+      });
+      observer.observe(this.el.nativeElement, {
+        characterData: true,
+        childList: true,
+        subtree: true,
+      });
+      this.destroyRef.onDestroy(() => observer.disconnect());
+    });
+  }
+
+  /** @internal Click handler — toggles selection in selectable shapes only. */
+  onClick(event: Event): void {
+    if (this.disabled()) {
+      event.preventDefault();
+      event.stopImmediatePropagation();
+      return;
+    }
+    if (this.computedRole() === 'button' || this.computedRole() === 'option') {
+      this.kjTagSelected.set(!this.kjTagSelected());
+    }
+  }
+
+  /** @internal Space / Enter activator — mirrors the click path; prevents page scroll on Space. */
+  onActivate(event: Event): void {
+    if (this.computedRole() === null) return;
+    if (this.disabled()) return;
+    event.preventDefault();
+    if (this.computedRole() === 'button' || this.computedRole() === 'option') {
+      this.kjTagSelected.set(!this.kjTagSelected());
+    }
+  }
+
+  /**
+   * Triggers removal. Called from a projected `KjTagRemove`. Re-emitted as
+   * `(kjTagRemoved)` for the consumer to drop this chip from their model.
+   */
+  remove(): void {
+    if (this.disabled()) return;
+    this.kjTagRemoved.emit();
+  }
+}

package/src/textarea/config.ts

@@ -0,0 +1,42 @@
+import { InjectionToken, Provider } from '@angular/core';
+
+/** Preset configuration consumed by `KjTextarea` via `bindPresets`. */
+export interface KjTextareaConfig {
+  variants: string[];
+  sizes: string[];
+  defaults: { variant: string; size: string };
+}
+
+/**
+ * Default Textarea presets shipped by kouji-ui. Variant list mirrors `KjInput`
+ * — outlined / filled — so a textarea inside a form sits naturally next to a
+ * matching input.
+ */
+export const KJ_TEXTAREA_DEFAULTS: KjTextareaConfig = {
+  variants: ['outlined', 'filled'],
+  sizes: ['sm', 'md', 'lg'],
+  defaults: { variant: 'outlined', size: 'md' },
+};
+
+/**
+ * DI token for the active Textarea presets. Default factory yields
+ * `KJ_TEXTAREA_DEFAULTS`. Override via `provideKjTextarea(…)` at application
+ * or component scope.
+ */
+export const KJ_TEXTAREA_CONFIG = new InjectionToken<KjTextareaConfig>('kj.textarea.config', {
+  factory: () => KJ_TEXTAREA_DEFAULTS,
+});
+
+/**
+ * Configures the Textarea presets for the enclosing injector. Replaces (does
+ * not merge) `variants` and `sizes`; spread `KJ_TEXTAREA_DEFAULTS.variants` to
+ * extend.
+ */
+export function provideKjTextarea(config: Partial<KjTextareaConfig>): Provider[] {
+  return [
+    {
+      provide: KJ_TEXTAREA_CONFIG,
+      useValue: { ...KJ_TEXTAREA_DEFAULTS, ...config },
+    },
+  ];
+}

package/src/textarea/index.ts

@@ -0,0 +1,8 @@
+export { KjTextarea } from './textarea';
+export type { KjTextareaAutoresize, KjTextareaResize } from './textarea';
+export {
+  KJ_TEXTAREA_CONFIG,
+  KJ_TEXTAREA_DEFAULTS,
+  provideKjTextarea,
+} from './config';
+export type { KjTextareaConfig } from './config';

package/src/textarea/textarea.spec.ts

@@ -0,0 +1,176 @@
+import { Component, type DebugElement, ChangeDetectionStrategy } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { FormControl, ReactiveFormsModule } from '@angular/forms';
+import { describe, expect, test, beforeEach } from 'vitest';
+import { KjTextarea } from './textarea';
+
+@Component({
+  standalone: true,
+  imports: [KjTextarea, ReactiveFormsModule],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <textarea
+      kjTextarea
+      [formControl]="ctrl"
+      [kjInvalid]="invalid"
+      [kjResize]="resize"
+      [kjAutoresize]="autoresize"
+      [kjMinRows]="minRows"
+      [kjMaxRows]="maxRows"
+      [kjMaxLength]="maxLength"
+      [kjVariant]="variant"
+      [kjSize]="size"
+      [kjDisabled]="disabled"
+    ></textarea>
+  `,
+})
+class HostComponent {
+  ctrl = new FormControl('');
+  invalid = false;
+  resize: 'none' | 'vertical' | 'both' = 'vertical';
+  autoresize: 'off' | 'auto' = 'off';
+  minRows: number | undefined = undefined;
+  maxRows: number | undefined = undefined;
+  maxLength: number | undefined = undefined;
+  variant: string = 'outlined';
+  size: string = 'md';
+  disabled = false;
+}
+
+describe('KjTextarea', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({ imports: [HostComponent] });
+  });
+
+  test('renders the directive on a native <textarea>', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const ta = fixture.nativeElement.querySelector('textarea');
+    expect(ta).not.toBeNull();
+  });
+
+  test('reflects variant and size to data-* host attributes', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.variant = 'filled';
+    fixture.componentInstance.size = 'sm';
+    fixture.detectChanges();
+    const ta = fixture.nativeElement.querySelector('textarea');
+    expect(ta.getAttribute('data-variant')).toBe('filled');
+    expect(ta.getAttribute('data-size')).toBe('sm');
+  });
+
+  test('writes form-control value into the native element', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.ctrl.setValue('hello');
+    fixture.detectChanges();
+    expect(fixture.nativeElement.querySelector('textarea').value).toBe('hello');
+  });
+
+  test('forwards user input back to the form-control', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const ta: HTMLTextAreaElement = fixture.nativeElement.querySelector('textarea');
+    ta.value = 'typed';
+    ta.dispatchEvent(new Event('input'));
+    fixture.detectChanges();
+    expect(fixture.componentInstance.ctrl.value).toBe('typed');
+  });
+
+  test('sets aria-invalid only after touched + invalid', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.invalid = true;
+    fixture.detectChanges();
+    const ta: HTMLTextAreaElement = fixture.nativeElement.querySelector('textarea');
+    // Not yet touched.
+    expect(ta.getAttribute('aria-invalid')).toBeNull();
+    ta.dispatchEvent(new Event('blur'));
+    fixture.detectChanges();
+    expect(ta.getAttribute('aria-invalid')).toBe('true');
+  });
+
+  test('binds maxlength when kjMaxLength is set', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.maxLength = 200;
+    fixture.detectChanges();
+    expect(fixture.nativeElement.querySelector('textarea').getAttribute('maxlength')).toBe('200');
+  });
+
+  test('omits maxlength when kjMaxLength is undefined', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    expect(fixture.nativeElement.querySelector('textarea').getAttribute('maxlength')).toBeNull();
+  });
+
+  test('applies kjResize to inline style.resize', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.resize = 'both';
+    fixture.detectChanges();
+    const ta: HTMLTextAreaElement = fixture.nativeElement.querySelector('textarea');
+    expect(ta.style.resize).toBe('both');
+  });
+
+  test('forces resize:none when kjAutoresize is on', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.resize = 'both';
+    fixture.componentInstance.autoresize = 'auto';
+    fixture.detectChanges();
+    const ta: HTMLTextAreaElement = fixture.nativeElement.querySelector('textarea');
+    expect(ta.style.resize).toBe('none');
+    expect(ta.getAttribute('data-autoresize')).toBe('');
+  });
+
+  test('reflects native disabled when the form control is disabled', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.ctrl.disable();
+    fixture.detectChanges();
+    expect(fixture.nativeElement.querySelector('textarea').hasAttribute('disabled')).toBe(true);
+  });
+
+  test('counterAnnouncement is empty when kjMaxLength is unset', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const debugEl = fixture.debugElement.query((el: DebugElement) => el.name === 'textarea');
+    const dir = debugEl.injector.get(KjTextarea);
+    expect(dir.counterAnnouncement()).toBe('');
+    expect(dir.remaining()).toBeNull();
+  });
+
+  test('remaining computes from value length when kjMaxLength is set', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.maxLength = 200;
+    fixture.detectChanges();
+    fixture.componentInstance.ctrl.setValue('hello');
+    fixture.detectChanges();
+    const debugEl = fixture.debugElement.query((el: DebugElement) => el.name === 'textarea');
+    const dir = debugEl.injector.get(KjTextarea);
+    expect(dir.remaining()).toBe(195);
+  });
+
+  test('counterAnnouncement crosses thresholds at 20, 10, 0 remaining', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.maxLength = 30;
+    fixture.detectChanges();
+    const debugEl = fixture.debugElement.query((el: DebugElement) => el.name === 'textarea');
+    const dir = debugEl.injector.get(KjTextarea);
+
+    // 20 remaining -> length 10
+    fixture.componentInstance.ctrl.setValue('a'.repeat(10));
+    fixture.detectChanges();
+    expect(dir.counterAnnouncement()).toBe('20 characters remaining');
+
+    // 10 remaining -> length 20
+    fixture.componentInstance.ctrl.setValue('a'.repeat(20));
+    fixture.detectChanges();
+    expect(dir.counterAnnouncement()).toBe('10 characters remaining');
+
+    // 0 remaining -> length 30
+    fixture.componentInstance.ctrl.setValue('a'.repeat(30));
+    fixture.detectChanges();
+    expect(dir.counterAnnouncement()).toBe('Character limit reached');
+
+    // Off-threshold -> empty
+    fixture.componentInstance.ctrl.setValue('a'.repeat(15));
+    fixture.detectChanges();
+    expect(dir.counterAnnouncement()).toBe('');
+  });
+});