@kouji-ui/components 0.1.1

package/src/textarea/textarea.css

@@ -0,0 +1,117 @@
+/* ─────────────────────────────────────────────────────────────
+   .kj-textarea — component-layer tokens + structural CSS
+   Same pattern as button.css / input.css: tokens default to
+   shared-layer values, variants/sizes/states retarget tokens,
+   structural CSS reads tokens only.
+   ──────────────────────────────────────────────────────────── */
+
+@layer kj.component {
+  .kj-textarea {
+    /* component knobs — themes/users can override any of these */
+    --kj-textarea-bg:               var(--kj-bg-field);
+    --kj-textarea-fg:               var(--kj-fg-default);
+    --kj-textarea-border-color:     var(--kj-border-default);
+    --kj-textarea-border-style:     solid;
+    --kj-textarea-border-width:     var(--kj-border);
+    --kj-textarea-radius:           var(--kj-radius-field);
+    --kj-textarea-padding-x:        var(--kj-space-md);
+    --kj-textarea-padding-y:        var(--kj-space-sm);
+    --kj-textarea-font:             var(--kj-font-sans);
+    --kj-textarea-font-size:        var(--kj-text-sm);
+    --kj-textarea-line-height:      1.5;
+    --kj-textarea-placeholder-fg:   var(--kj-fg-muted);
+    --kj-textarea-min-height:       2.75rem; /* WCAG 2.5.5 touch target floor */
+
+    display: block;
+    width: 100%;
+    min-height: var(--kj-textarea-min-height);
+    background: var(--kj-textarea-bg);
+    color: var(--kj-textarea-fg);
+    border: var(--kj-textarea-border-width) var(--kj-textarea-border-style) var(--kj-textarea-border-color);
+    border-radius: var(--kj-textarea-radius);
+    padding: var(--kj-textarea-padding-y) var(--kj-textarea-padding-x);
+    font: var(--kj-textarea-font-size) / var(--kj-textarea-line-height) var(--kj-textarea-font);
+    transition: var(--kj-transition);
+    /* `resize` is set inline by KjTextarea (`[style.resize]`) and overrides
+       this fallback when present. */
+    resize: vertical;
+  }
+
+  .kj-textarea::placeholder {
+    color: var(--kj-textarea-placeholder-fg);
+  }
+
+  .kj-textarea:focus-visible {
+    outline: 2px solid var(--kj-bg-primary);
+    outline-offset: 2px;
+    --kj-textarea-border-color: var(--kj-bg-primary);
+  }
+
+  .kj-textarea[aria-invalid='true'] {
+    --kj-textarea-border-color: var(--kj-bg-danger);
+  }
+
+  .kj-textarea[aria-disabled='true'],
+  .kj-textarea:disabled {
+    opacity: 0.55;
+    cursor: not-allowed;
+  }
+
+  /* ── Variants ─────────────────────────────────────────────── */
+  .kj-textarea[data-variant='filled'] {
+    --kj-textarea-bg: var(--kj-bg-surface);
+    --kj-textarea-border-color: transparent;
+  }
+  .kj-textarea[data-variant='filled']:focus-visible {
+    --kj-textarea-border-color: var(--kj-bg-primary);
+  }
+
+  /* ── Sizes ────────────────────────────────────────────────── */
+  .kj-textarea[data-size='sm'] {
+    --kj-textarea-padding-x: var(--kj-space-sm);
+    --kj-textarea-padding-y: 0.25rem;
+    --kj-textarea-font-size: 0.8125rem;
+  }
+  .kj-textarea[data-size='lg'] {
+    --kj-textarea-padding-x: var(--kj-space-lg);
+    --kj-textarea-padding-y: 0.625rem;
+    --kj-textarea-font-size: 1rem;
+  }
+
+  /* ── Auto-resize: hide the user drag handle ──────────────── */
+  .kj-textarea[data-autoresize] {
+    /* `[style.resize]` from the directive already sets resize:none, but
+       keeping the rule here for older browsers / SSR before the directive
+       initialises. */
+    resize: none;
+    overflow-y: hidden;
+  }
+
+  /* ── Counter ─────────────────────────────────────────────── */
+  .kj-textarea__counter {
+    margin-top: var(--kj-space-xs, 0.25rem);
+    font: var(--kj-text-xs, 0.75rem) / 1.2 var(--kj-font-mono, var(--kj-font-sans));
+    color: var(--kj-fg-muted);
+    text-align: end;
+  }
+  .kj-textarea__counter[data-state='warn'] {
+    color: var(--kj-fg-warning, var(--kj-fg-muted));
+  }
+  .kj-textarea__counter[data-state='limit'] {
+    color: var(--kj-fg-danger);
+  }
+
+  /* Live region: visually hidden but readable to AT. Mirrors the
+     `.sr-only` pattern. */
+  .kj-textarea__live {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+  }
+}

package/src/textarea/textarea.playground.ts

@@ -0,0 +1,70 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { KjTextareaComponent } from './textarea';
+import type { PlaygroundFile } from '@kouji-ui/components/playground-types';
+
+/**
+ * Playground state — module-scope signals.
+ */
+const size = signal<'sm' | 'md' | 'lg'>('md');
+const rows = signal<2 | 3 | 4 | 6>(4);
+const placeholder = signal('Tell us about yourself…');
+const disabled = signal(false);
+const invalid = signal(false);
+
+@Component({
+  selector: 'kj-textarea-playground',
+  standalone: true,
+  imports: [KjTextareaComponent],
+  template: `
+    <kj-textarea
+      [kjSize]="size()"
+      [kjRows]="rows()"
+      [kjPlaceholder]="placeholder()"
+      [kjDisabled]="disabled()"
+      [kjInvalid]="invalid()"
+    />
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjTextareaPlaygroundDemo {
+  protected readonly size = size;
+  protected readonly rows = rows;
+  protected readonly placeholder = placeholder;
+  protected readonly disabled = disabled;
+  protected readonly invalid = invalid;
+}
+
+export const PLAYGROUND: PlaygroundFile = {
+  component: KjTextareaPlaygroundDemo,
+  state: {
+    size: size as unknown as ReturnType<typeof signal>,
+    rows: rows as unknown as ReturnType<typeof signal>,
+    placeholder: placeholder as unknown as ReturnType<typeof signal>,
+    disabled: disabled as unknown as ReturnType<typeof signal>,
+    invalid: invalid as unknown as ReturnType<typeof signal>,
+  },
+  controls: [
+    { kind: 'chips', name: 'size', label: 'size', options: ['sm', 'md', 'lg'] },
+    { kind: 'chips', name: 'rows', label: 'rows', options: [2, 3, 4, 6] },
+    { kind: 'text', name: 'placeholder', label: 'placeholder' },
+    { kind: 'toggle', name: 'disabled', label: 'disabled' },
+    { kind: 'toggle', name: 'invalid', label: 'invalid' },
+  ],
+  snippet: (values) => {
+    const s = values as {
+      size: string;
+      rows: number;
+      placeholder: string;
+      disabled: boolean;
+      invalid: boolean;
+    };
+    const attrs: string[] = [
+      `kjSize="${s.size}"`,
+      `[kjRows]="${s.rows}"`,
+      `kjPlaceholder="${s.placeholder}"`,
+    ];
+    if (s.disabled) attrs.push('[kjDisabled]="true"');
+    if (s.invalid) attrs.push('[kjInvalid]="true"');
+    return `<kj-textarea\n  ${attrs.join('\n  ')}\n/>`;
+  },
+};

package/src/textarea/textarea.spec.ts

@@ -0,0 +1,161 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { FormControl, ReactiveFormsModule } from '@angular/forms';
+import { describe, expect, test, beforeEach } from 'vitest';
+import { KjTextareaComponent } from './textarea';
+
+@Component({
+  standalone: true,
+  imports: [KjTextareaComponent, ReactiveFormsModule],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-textarea
+      [kjRows]="rows"
+      [kjPlaceholder]="placeholder"
+      [kjVariant]="variant"
+      [kjSize]="size"
+      [kjInvalid]="invalid"
+      [kjDisabled]="disabled"
+      [kjResize]="resize"
+      [kjAutoresize]="autoresize"
+      [kjMinRows]="minRows"
+      [kjMaxRows]="maxRows"
+      [kjMaxLength]="maxLength"
+      [kjShowCounter]="showCounter"
+      [formControl]="ctrl"
+    ></kj-textarea>
+  `,
+})
+class HostComponent {
+  ctrl = new FormControl('');
+  rows = 3;
+  placeholder = '';
+  variant: string = 'outlined';
+  size: string = 'md';
+  invalid = false;
+  disabled = false;
+  resize: 'none' | 'vertical' | 'both' = 'vertical';
+  autoresize: 'off' | 'auto' = 'off';
+  minRows: number | undefined = undefined;
+  maxRows: number | undefined = undefined;
+  maxLength: number | undefined = undefined;
+  showCounter = false;
+}
+
+describe('KjTextareaComponent', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({ imports: [HostComponent] });
+  });
+
+  test('renders an inner <textarea> with the .kj-textarea class', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    expect(fixture.nativeElement.querySelector('kj-textarea textarea.kj-textarea')).not.toBeNull();
+  });
+
+  test('forwards rows and placeholder to the inner textarea', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.rows = 5;
+    fixture.componentInstance.placeholder = 'Type here…';
+    fixture.detectChanges();
+    const ta: HTMLTextAreaElement = fixture.nativeElement.querySelector('kj-textarea textarea');
+    expect(ta.getAttribute('rows')).toBe('5');
+    expect(ta.getAttribute('placeholder')).toBe('Type here…');
+  });
+
+  test('forwards variant and size as data-* attributes', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.variant = 'filled';
+    fixture.componentInstance.size = 'sm';
+    fixture.detectChanges();
+    const ta: HTMLTextAreaElement = fixture.nativeElement.querySelector('kj-textarea textarea');
+    expect(ta.getAttribute('data-variant')).toBe('filled');
+    expect(ta.getAttribute('data-size')).toBe('sm');
+  });
+
+  test('binds maxlength when kjMaxLength is set', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.maxLength = 50;
+    fixture.detectChanges();
+    expect(
+      fixture.nativeElement.querySelector('kj-textarea textarea').getAttribute('maxlength'),
+    ).toBe('50');
+  });
+
+  test('renders the counter when kjShowCounter and kjMaxLength are set', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.maxLength = 50;
+    fixture.componentInstance.showCounter = true;
+    fixture.detectChanges();
+    const counter = fixture.nativeElement.querySelector('.kj-textarea__counter');
+    expect(counter).not.toBeNull();
+    expect(counter.textContent.trim()).toContain('/ 50');
+  });
+
+  test('does not render the counter without kjMaxLength', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.showCounter = true;
+    fixture.detectChanges();
+    expect(fixture.nativeElement.querySelector('.kj-textarea__counter')).toBeNull();
+  });
+
+  test('counter element id is wired into the textareas aria-describedby', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.maxLength = 50;
+    fixture.componentInstance.showCounter = true;
+    fixture.detectChanges();
+    const counter = fixture.nativeElement.querySelector('.kj-textarea__counter');
+    const ta: HTMLTextAreaElement = fixture.nativeElement.querySelector('kj-textarea textarea');
+    const describedBy = ta.getAttribute('aria-describedby');
+    expect(describedBy).not.toBeNull();
+    expect(describedBy).toBe(counter.id);
+  });
+
+  test('counter updates with the form-control value', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.maxLength = 50;
+    fixture.componentInstance.showCounter = true;
+    fixture.detectChanges();
+    fixture.componentInstance.ctrl.setValue('hello');
+    fixture.detectChanges();
+    const counter = fixture.nativeElement.querySelector('.kj-textarea__counter');
+    expect(counter.textContent.trim()).toBe('5 / 50');
+  });
+
+  test('forwards kjResize to inline style on the inner textarea', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.resize = 'both';
+    fixture.detectChanges();
+    const ta: HTMLTextAreaElement = fixture.nativeElement.querySelector('kj-textarea textarea');
+    expect(ta.style.resize).toBe('both');
+  });
+
+  test('autoresize=auto forces resize:none and sets data-autoresize', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.autoresize = 'auto';
+    fixture.componentInstance.resize = 'both';
+    fixture.detectChanges();
+    const ta: HTMLTextAreaElement = fixture.nativeElement.querySelector('kj-textarea textarea');
+    expect(ta.style.resize).toBe('none');
+    expect(ta.getAttribute('data-autoresize')).toBe('');
+  });
+
+  test('forwards disabled (aria-disabled on inner textarea)', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.disabled = true;
+    fixture.detectChanges();
+    expect(
+      fixture.nativeElement.querySelector('kj-textarea textarea').getAttribute('aria-disabled'),
+    ).toBe('true');
+  });
+
+  test('forwards invalid → aria-invalid (after blur)', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.invalid = true;
+    fixture.detectChanges();
+    const ta: HTMLTextAreaElement = fixture.nativeElement.querySelector('kj-textarea textarea');
+    ta.dispatchEvent(new Event('blur'));
+    fixture.detectChanges();
+    expect(ta.getAttribute('aria-invalid')).toBe('true');
+  });
+});

package/src/textarea/textarea.ts

@@ -0,0 +1,339 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  ViewEncapsulation,
+  booleanAttribute,
+  computed,
+  effect,
+  forwardRef,
+  input,
+  signal,
+} from '@angular/core';
+import { ControlValueAccessor, NG_VALUE_ACCESSOR } from '@angular/forms';
+import {
+  KjLiveRegion,
+  KjTextarea,
+  type KjTextareaAutoresize,
+  type KjTextareaResize,
+} from '@kouji-ui/core';
+
+let nextId = 0;
+
+/**
+ * Number transform that preserves `undefined` (instead of NaN-ing on absent
+ * numbers like Angular's built-in `numberAttribute`).
+ *
+ * @internal
+ */
+function optionalNumber(v: number | string | undefined): number | undefined {
+  if (v == null || v === '') return undefined;
+  const n = typeof v === 'number' ? v : Number(v);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+/**
+ * Required-number transform: same shape, but returns the default when the
+ * input is missing/invalid (used for `kjRows`).
+ *
+ * @internal
+ */
+function numberWithDefault(def: number) {
+  return (v: number | string | undefined): number => {
+    const n = optionalNumber(v);
+    return n ?? def;
+  };
+}
+
+/**
+ * Styled wrapper around the headless `KjTextarea` directive.
+ *
+ * Element-wrapper pattern: `<kj-textarea>` is a structural shell
+ * (`display: contents;`); the inner `<textarea>` carries native textarea
+ * semantics (focus, form integration, validation, native maxlength).
+ *
+ * Adds, on top of `KjTextarea`:
+ * - A theme-token CSS shell (`.kj-textarea`).
+ * - An optional visible character counter (`{ length } / { kjMaxLength }`)
+ *   wired to a polite live region for screen-reader announcements at
+ *   threshold crossings (≤ 20, ≤ 10, 0 remaining).
+ * - `aria-describedby` plumbing from the textarea to the counter element.
+ *
+ * @example
+ * ```html
+ * <kj-textarea kjRows="4" [(ngModel)]="bio" kjPlaceholder="Tell us about yourself" />
+ *
+ * <kj-textarea kjAutoresize="auto" [kjMinRows]="2" [kjMaxRows]="8"
+ *              [(ngModel)]="bio" />
+ *
+ * <kj-textarea [kjMaxLength]="200" kjShowCounter [(ngModel)]="bio" />
+ * ```
+ *
+ * @doc-example Default
+ *   The default playground — a 4-row textarea with placeholder.
+ *   @doc-file textarea.example.ts
+ * @doc-example Usage
+ *   A walkthrough of the most common textarea usages — `[(ngModel)]`,
+ *   placeholder, character counter, and an invalid state with a helper note.
+ *   @doc-file textarea.usage.example.ts
+ * @doc-example Auto-resize
+ *   `kjAutoresize="auto"` grows the textarea to fit content between
+ *   `kjMinRows` and `kjMaxRows`.
+ *   @doc-file textarea.autoresize.example.ts
+ * @doc-example Character counter
+ *   `[kjMaxLength]` + `kjShowCounter` renders a live `n / max` counter wired
+ *   to a polite live region.
+ *   @doc-file textarea.character-count.example.ts
+ * @doc-example No resize handle
+ *   `kjResize="none"` hides the native drag-to-resize affordance.
+ *   @doc-file textarea.no-resize.example.ts
+ * @doc-example With Field wrapper
+ *   Compose under `<kj-field>` for label / error / hint association.
+ *   @doc-file textarea.with-field.example.ts
+ *
+ * @doc-keyboard
+ *   Tab            — Moves focus into the textarea
+ *   Shift+Tab      — Moves focus to the previous focusable element
+ *   Enter          — Inserts a newline (native textarea behaviour)
+ *   Cmd/Ctrl+A     — Selects all (native)
+ *
+ * @doc-aria
+ *   aria-disabled       — Reflected when `[kjDisabled]="true"`
+ *   aria-invalid        — Reflected when `[kjInvalid]="true"`
+ *   aria-describedby    — Wired to the counter id when the counter is visible
+ *   role="status"       — Internal live region announces threshold crossings
+ *   data-variant        — Mirrors the resolved variant for theme hooks
+ *   data-size           — Mirrors the resolved size for theme hooks
+ *
+ * @doc-touch
+ *   Default `--kj-textarea-min-height` is the WCAG 2.5.5 touch-target floor
+ *   (≥ 44×44). `sm` density retains the floor — only padding shrinks.
+ *
+ * @doc-a11y
+ *   Renders a real `<textarea>` so native focus, form integration, validation,
+ *   and `maxlength` all work without ceremony. The character counter is wired
+ *   via `aria-describedby` plus a polite live region that announces at 20 / 10
+ *   / 0 remaining, never interrupting the typist.
+ *
+ * @doc-related input,field,form
+ *
+ * @doc-css-var
+ *   --kj-textarea-bg              — Background fill. Filled variant retargets to --kj-bg-surface.
+ *   --kj-textarea-fg              — Foreground (text) color.
+ *   --kj-textarea-border-color    — Border color. Focus and invalid states retarget this.
+ *   --kj-textarea-border-style    — Border style. Default solid.
+ *   --kj-textarea-border-width    — Border thickness. Inherits the theme's --kj-border.
+ *   --kj-textarea-radius          — Corner radius. Inherits --kj-radius-field.
+ *   --kj-textarea-padding-x       — Horizontal padding. Sizes override.
+ *   --kj-textarea-padding-y       — Vertical padding. Sizes override.
+ *   --kj-textarea-font            — Font family. Defaults to --kj-font-sans.
+ *   --kj-textarea-font-size       — Font size. Sizes (sm/md/lg) override.
+ *   --kj-textarea-line-height     — Line height for the text content.
+ *   --kj-textarea-placeholder-fg  — Foreground color of the placeholder text.
+ *   --kj-textarea-min-height      — Minimum height. Defaults to the WCAG 2.5.5 touch-target floor.
+ *
+ * @doc-category Library/Data input
+ * @doc
+ * @doc-name textarea
+ * @doc-description Themed multi-line text input with optional auto-resize and live character counter.
+ * @doc-is-main
+ */
+@Component({
+  selector: 'kj-textarea',
+  standalone: true,
+  imports: [KjTextarea, KjLiveRegion],
+  providers: [
+    {
+      provide: NG_VALUE_ACCESSOR,
+      useExisting: forwardRef(() => KjTextareaComponent),
+      multi: true,
+    },
+  ],
+  template: `
+    <textarea
+      kjTextarea
+      class="kj-textarea"
+      [rows]="kjRows()"
+      [value]="currentValue()"
+      [placeholder]="kjPlaceholder()"
+      [kjVariant]="kjVariant()"
+      [kjSize]="kjSize()"
+      [kjInvalid]="kjInvalid()"
+      [kjDisabled]="kjDisabled() || cvaDisabled()"
+      [kjResize]="kjResize()"
+      [kjAutoresize]="kjAutoresize()"
+      [kjMinRows]="kjMinRows()"
+      [kjMaxRows]="kjMaxRows()"
+      [kjMaxLength]="kjMaxLength()"
+      [attr.aria-describedby]="ariaDescribedBy()"
+      (input)="onInnerInput($any($event.target).value)"
+      (blur)="onInnerBlur()"
+    ></textarea>
+    @if (showCounter()) {
+      <div
+        class="kj-textarea__counter"
+        [id]="counterId"
+        [attr.data-state]="counterState()"
+      >{{ valueLength() }} / {{ kjMaxLength() }}</div>
+      <div
+        class="kj-textarea__live"
+        kjLiveRegion
+        kjPoliteness="polite"
+      >{{ liveMessage() }}</div>
+    }
+  `,
+  styleUrl: './textarea.css',
+  encapsulation: ViewEncapsulation.None,
+  host: {
+    style: 'display: contents;',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjTextareaComponent implements ControlValueAccessor {
+  /** Uncontrolled fallback value. Templated forms use `[(ngModel)]` / `[formControl]`. */
+  readonly kjValue = input<string>('');
+
+  /** Native `placeholder` attribute. */
+  readonly kjPlaceholder = input<string>('');
+
+  /** Native `rows` attribute. Default `3`. */
+  readonly kjRows = input<number, number | string | undefined>(3, {
+    transform: numberWithDefault(3),
+  });
+
+  /** CSS `resize` override. Forced to `none` when `kjAutoresize === 'auto'`. */
+  readonly kjResize = input<KjTextareaResize>('vertical');
+
+  /** Auto-resize mode. `'auto'` measures `scrollHeight` on each input. */
+  readonly kjAutoresize = input<KjTextareaAutoresize>('off');
+
+  /** Minimum rows when auto-resize is on. */
+  readonly kjMinRows = input<number, number | string | undefined>(0, {
+    transform: numberWithDefault(0),
+  });
+
+  /** Maximum rows when auto-resize is on. */
+  readonly kjMaxRows = input<number, number | string | undefined>(Number.POSITIVE_INFINITY, {
+    transform: numberWithDefault(Number.POSITIVE_INFINITY),
+  });
+
+  /** Native `maxlength`. Required to enable the visible counter. */
+  readonly kjMaxLength = input<number, number | string | undefined>(Number.POSITIVE_INFINITY, {
+    transform: numberWithDefault(Number.POSITIVE_INFINITY),
+  });
+
+  /** Renders a visible `{ length } / { kjMaxLength }` counter. Requires `kjMaxLength`. */
+  readonly kjShowCounter = input(false, { transform: booleanAttribute });
+
+  /** Whether the textarea is invalid. Combined with `touched` for ARIA. */
+  readonly kjInvalid = input(false, { transform: booleanAttribute });
+
+  /** Disables the textarea. Reflects `aria-disabled` and native `disabled`. */
+  readonly kjDisabled = input(false, { transform: booleanAttribute });
+
+  /** Theme variant. Configurable via `provideKjTextarea(...)`. */
+  readonly kjVariant = input('outlined');
+
+  /** Theme size. Configurable via `provideKjTextarea(...)`. */
+  readonly kjSize = input('md');
+
+  /** @internal stable id for the counter / aria-describedby wiring. */
+  protected readonly counterId = `kj-textarea-counter-${++nextId}`;
+
+  // ── CVA plumbing ───────────────────────────────────────────────────────
+  // The wrapper itself acts as the form-control bound to `<kj-textarea>` so
+  // consumers can write `[(ngModel)]="bio"` / `[formControl]="bio"` on the
+  // wrapper element. The inner `[kjTextarea]` directive's own KjFormControl is
+  // a local signal channel that powers value reflection + the counter; both
+  // are kept in sync via the (input) handler.
+  private readonly cvaValue = signal<string>('');
+  protected readonly cvaDisabled = signal<boolean>(false);
+
+  /** @internal Effective textarea value: CVA-bound value with kjValue fallback. */
+  protected readonly currentValue = computed(() => {
+    const v = this.cvaValue();
+    return v !== '' && v != null ? v : this.kjValue();
+  });
+
+  private _onChange?: (value: string) => void;
+  private _onTouched?: () => void;
+
+  /** @internal Whether the visible counter element should render. */
+  protected readonly showCounter = computed(
+    () => this.kjShowCounter() && Number.isFinite(this.kjMaxLength()),
+  );
+
+  /** @internal — value length, prioritised from the CVA-bound signal so the
+   * counter updates the same tick the form control writes. */
+  protected readonly valueLength = computed(() => {
+    const cva = this.cvaValue();
+    if (cva) return cva.length;
+    return (this.kjValue() ?? '').length;
+  });
+
+  /** @internal — counter state for theming (`ok` / `warn` / `limit`). */
+  protected readonly counterState = computed(() => {
+    const max = this.kjMaxLength();
+    if (!Number.isFinite(max)) return 'ok';
+    const remaining = max - this.valueLength();
+    if (remaining <= 0) return 'limit';
+    if (remaining <= 20) return 'warn';
+    return 'ok';
+  });
+
+  /** @internal — composed aria-describedby (counter id when visible). */
+  protected readonly ariaDescribedBy = computed(() =>
+    this.showCounter() ? this.counterId : null,
+  );
+
+  /** @internal — threshold-based announcement string (mirrors the directive's
+   * own logic so the wrapper doesn't need a viewChild handle to read it). */
+  protected readonly liveMessage = computed<string>(() => {
+    const max = this.kjMaxLength();
+    if (!Number.isFinite(max)) return '';
+    const r = max - this.valueLength();
+    if (r === 0) return 'Character limit reached';
+    if (r === 10) return '10 characters remaining';
+    if (r === 20) return '20 characters remaining';
+    return '';
+  });
+
+  constructor() {
+    // Dev-mode guidance: counter requested without max length is a no-op.
+    effect(() => {
+      if (this.kjShowCounter() && !Number.isFinite(this.kjMaxLength()) && typeof console !== 'undefined') {
+        console.warn(
+          '[kj-textarea] kjShowCounter is set without kjMaxLength — counter will not render.',
+        );
+      }
+    });
+  }
+
+  /** @internal — host (input) wired into the wrapper's CVA. */
+  onInnerInput(value: string): void {
+    this.cvaValue.set(value);
+    this._onChange?.(value);
+  }
+
+  /** @internal — host (blur) marks CVA touched. */
+  onInnerBlur(): void {
+    this._onTouched?.();
+  }
+
+  // ── ControlValueAccessor implementation ────────────────────────────────
+  writeValue(val: unknown): void {
+    const next = val == null ? '' : String(val);
+    this.cvaValue.set(next);
+  }
+
+  registerOnChange(fn: (value: string) => void): void {
+    this._onChange = fn;
+  }
+
+  registerOnTouched(fn: () => void): void {
+    this._onTouched = fn;
+  }
+
+  setDisabledState(isDisabled: boolean): void {
+    this.cvaDisabled.set(isDisabled);
+  }
+}