@kouji-ui/components 0.1.1

package/src/password-input/password-input.css

@@ -0,0 +1,155 @@
+/* ─────────────────────────────────────────────────────────────
+   .kj-password-input — component-layer tokens + structural CSS
+   Same pattern as input.css / button.css: tokens default to the
+   shared layer; variants/states retarget the component tokens.
+   ──────────────────────────────────────────────────────────── */
+
+@layer kj.component {
+  .kj-password-input {
+    --kj-password-input-bg:               var(--kj-bg-field);
+    --kj-password-input-fg:               var(--kj-fg-default);
+    --kj-password-input-border-color:     var(--kj-border-default);
+    --kj-password-input-border-style:     solid;
+    --kj-password-input-border-width:     var(--kj-border);
+    --kj-password-input-radius:           var(--kj-radius-field);
+    --kj-password-input-padding-x:        var(--kj-space-md);
+    --kj-password-input-padding-y:        var(--kj-space-sm);
+    --kj-password-input-font:             var(--kj-font-sans);
+    --kj-password-input-font-size:        var(--kj-text-sm);
+    --kj-password-input-placeholder-fg:   var(--kj-fg-muted);
+    --kj-password-input-toggle-fg:        var(--kj-fg-muted);
+    --kj-password-input-toggle-fg-hover:  var(--kj-fg-default);
+    /* Explicit height contract (same pattern as input.css / button.css) so
+       password-input lines up with sibling inputs in a form row. */
+    --kj-password-input-height:           2.25rem;
+
+    display: inline-flex;
+    align-items: center;
+    gap: var(--kj-space-xs);
+    inline-size: 100%;
+    height: var(--kj-password-input-height);
+    background: var(--kj-password-input-bg);
+    color: var(--kj-password-input-fg);
+    border: var(--kj-password-input-border-width)
+            var(--kj-password-input-border-style)
+            var(--kj-password-input-border-color);
+    border-radius: var(--kj-password-input-radius);
+    padding: 0 var(--kj-password-input-padding-x);
+    font: var(--kj-password-input-font-size) / 1.4 var(--kj-password-input-font);
+    transition: var(--kj-transition);
+  }
+  .kj-password-input[data-size="sm"] { --kj-password-input-height: 2rem;    --kj-password-input-font-size: 0.8125rem; }
+  .kj-password-input[data-size="lg"] { --kj-password-input-height: 2.75rem; --kj-password-input-font-size: 1rem; }
+
+  .kj-password-input__field {
+    flex: 1 1 auto;
+    inline-size: 100%;
+    height: 100%;
+    background: transparent;
+    color: inherit;
+    border: 0;
+    outline: 0;
+    padding: 0;
+    font: inherit;
+  }
+  .kj-password-input__field::placeholder {
+    color: var(--kj-password-input-placeholder-fg);
+  }
+
+  .kj-password-input:focus-within {
+    outline: 2px solid var(--kj-fg-primary);
+    outline-offset: 2px;
+    --kj-password-input-border-color: var(--kj-fg-primary);
+  }
+  .kj-password-input:has([aria-invalid="true"]) {
+    --kj-password-input-border-color: var(--kj-fg-danger);
+  }
+  .kj-password-input:has([aria-disabled="true"]),
+  .kj-password-input:has(:disabled) {
+    opacity: 0.55;
+    cursor: not-allowed;
+  }
+
+  /* eye-icon toggle button: ghost, square, in-row */
+  .kj-password-input__toggle {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    inline-size: 1.75rem;
+    block-size: 1.75rem;
+    margin-inline-start: var(--kj-space-xs);
+    color: var(--kj-password-input-toggle-fg);
+    background: transparent;
+    border: 0;
+    border-radius: var(--kj-radius-field);
+    cursor: pointer;
+  }
+  .kj-password-input__toggle:hover,
+  .kj-password-input__toggle:focus-visible {
+    color: var(--kj-password-input-toggle-fg-hover);
+  }
+  .kj-password-input__toggle:focus-visible {
+    outline: 2px solid var(--kj-fg-primary);
+    outline-offset: 2px;
+  }
+
+  .kj-password-input__icon {
+    inline-size: 1rem;
+    block-size: 1rem;
+    fill: none;
+    stroke: currentColor;
+    stroke-width: 1.5;
+    stroke-linecap: round;
+    stroke-linejoin: round;
+  }
+
+  /* strength meter — 4-segment bar, colour ramp owned here */
+  .kj-password-strength {
+    display: flex;
+    gap: var(--kj-space-xs);
+    inline-size: 100%;
+    margin-block-start: var(--kj-space-xs);
+  }
+  .kj-password-strength__seg {
+    flex: 1 1 0;
+    block-size: 0.25rem;
+    background: var(--kj-bg-surface);
+    border-radius: 2px;
+    transition: background-color var(--kj-transition);
+  }
+  .kj-password-strength[data-score="1"] .kj-password-strength__seg:nth-child(-n+1),
+  .kj-password-strength[data-score="2"] .kj-password-strength__seg:nth-child(-n+2),
+  .kj-password-strength[data-score="3"] .kj-password-strength__seg:nth-child(-n+3),
+  .kj-password-strength[data-score="4"] .kj-password-strength__seg:nth-child(-n+4) {
+    background: var(--kj-password-strength-color, var(--kj-bg-primary));
+  }
+  .kj-password-strength[data-score="1"] {
+    --kj-password-strength-color: var(--kj-bg-danger);
+  }
+  .kj-password-strength[data-score="2"] {
+    --kj-password-strength-color: var(--kj-bg-warning, #d97706);
+  }
+  .kj-password-strength[data-score="3"] {
+    --kj-password-strength-color: var(--kj-bg-success, #059669);
+  }
+  .kj-password-strength[data-score="4"] {
+    --kj-password-strength-color: var(--kj-bg-success, #059669);
+  }
+
+  .kj-password-strength__label {
+    display: block;
+    margin-block-start: var(--kj-space-xs);
+    font-size: var(--kj-text-xs);
+    color: var(--kj-fg-muted);
+  }
+
+  .kj-password-caps-lock-warning {
+    display: block;
+    margin-block-start: var(--kj-space-xs);
+    font-size: var(--kj-text-xs);
+    color: var(--kj-fg-warning, #d97706);
+  }
+  .kj-password-caps-lock-warning[hidden] {
+    display: none;
+  }
+}

package/src/password-input/password-input.playground.ts

@@ -0,0 +1,81 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { KjPasswordInputComponent } from './password-input';
+import type { PlaygroundFile } from '@kouji-ui/components/playground-types';
+
+const passwordValue = signal<string>('');
+const placeholder = signal<string>('Enter your password');
+const showToggle = signal(true);
+const showStrength = signal(false);
+const showCapsLockWarning = signal(false);
+const disabled = signal(false);
+const invalid = signal(false);
+
+@Component({
+  selector: 'kj-password-input-playground',
+  standalone: true,
+  imports: [KjPasswordInputComponent],
+  template: `
+    <kj-password-input
+      [(kjValue)]="passwordValue"
+      [kjPlaceholder]="placeholder()"
+      [kjShowToggle]="showToggle()"
+      [kjShowStrength]="showStrength()"
+      [kjShowCapsLockWarning]="showCapsLockWarning()"
+      [kjDisabled]="disabled()"
+      [kjInvalid]="invalid()"
+      kjAutocomplete="current-password"
+    />
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjPasswordInputPlaygroundDemo {
+  protected readonly passwordValue = passwordValue;
+  protected readonly placeholder = placeholder;
+  protected readonly showToggle = showToggle;
+  protected readonly showStrength = showStrength;
+  protected readonly showCapsLockWarning = showCapsLockWarning;
+  protected readonly disabled = disabled;
+  protected readonly invalid = invalid;
+}
+
+export const PLAYGROUND: PlaygroundFile = {
+  component: KjPasswordInputPlaygroundDemo,
+  state: {
+    passwordValue: passwordValue as unknown as ReturnType<typeof signal>,
+    placeholder: placeholder as unknown as ReturnType<typeof signal>,
+    showToggle: showToggle as unknown as ReturnType<typeof signal>,
+    showStrength: showStrength as unknown as ReturnType<typeof signal>,
+    showCapsLockWarning: showCapsLockWarning as unknown as ReturnType<typeof signal>,
+    disabled: disabled as unknown as ReturnType<typeof signal>,
+    invalid: invalid as unknown as ReturnType<typeof signal>,
+  },
+  controls: [
+    { kind: 'text', name: 'placeholder', label: 'placeholder' },
+    { kind: 'toggle', name: 'showToggle', label: 'show toggle' },
+    { kind: 'toggle', name: 'showStrength', label: 'show strength meter' },
+    { kind: 'toggle', name: 'showCapsLockWarning', label: 'caps-lock warning' },
+    { kind: 'toggle', name: 'disabled', label: 'disabled' },
+    { kind: 'toggle', name: 'invalid', label: 'invalid' },
+  ],
+  snippet: (values) => {
+    const s = values as {
+      placeholder: string;
+      showToggle: boolean;
+      showStrength: boolean;
+      showCapsLockWarning: boolean;
+      disabled: boolean;
+      invalid: boolean;
+    };
+    const attrs: string[] = [
+      `[(kjValue)]="password"`,
+      `kjPlaceholder="${s.placeholder}"`,
+    ];
+    if (!s.showToggle) attrs.push('[kjShowToggle]="false"');
+    if (s.showStrength) attrs.push('[kjShowStrength]="true"');
+    if (s.showCapsLockWarning) attrs.push('[kjShowCapsLockWarning]="true"');
+    if (s.disabled) attrs.push('[kjDisabled]="true"');
+    if (s.invalid) attrs.push('[kjInvalid]="true"');
+    attrs.push('kjAutocomplete="current-password"');
+    return `<kj-password-input\n  ${attrs.join('\n  ')}\n/>`;
+  },
+};

package/src/password-input/password-input.spec.ts

@@ -0,0 +1,129 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { beforeEach, describe, expect, test } from 'vitest';
+import { KjPasswordInputComponent } from './password-input';
+
+@Component({
+  standalone: true,
+  imports: [KjPasswordInputComponent],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-password-input
+      [kjAutocomplete]="autocomplete"
+      [kjMaxLength]="maxLength"
+      [kjDisabled]="disabled"
+      [kjInvalid]="invalid"
+      [kjPlaceholder]="placeholder"
+      [kjShowToggle]="showToggle"
+      [kjShowStrength]="showStrength"
+      [kjShowCapsLockWarning]="showCapsLock"
+    />
+  `,
+})
+class HostComponent {
+  autocomplete: 'current-password' | 'new-password' | 'off' = 'current-password';
+  maxLength: number | undefined = undefined;
+  disabled = false;
+  invalid = false;
+  placeholder = '';
+  showToggle = true;
+  showStrength = false;
+  showCapsLock = false;
+}
+
+describe('KjPasswordInputComponent', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({ imports: [HostComponent] });
+  });
+
+  test('renders an inner <input> with type="password"', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const input = fixture.nativeElement.querySelector('kj-password-input input');
+    expect(input).not.toBeNull();
+    expect(input.getAttribute('type')).toBe('password');
+  });
+
+  test('forwards kjAutocomplete to the inner input', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.autocomplete = 'new-password';
+    fixture.detectChanges();
+    expect(
+      fixture.nativeElement.querySelector('kj-password-input input').getAttribute('autocomplete'),
+    ).toBe('new-password');
+  });
+
+  test('forwards kjMaxLength to native maxlength', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.maxLength = 24;
+    fixture.detectChanges();
+    expect(
+      fixture.nativeElement.querySelector('kj-password-input input').getAttribute('maxlength'),
+    ).toBe('24');
+  });
+
+  test('forwards kjPlaceholder to native placeholder', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.placeholder = 'Enter password';
+    fixture.detectChanges();
+    expect(
+      fixture.nativeElement.querySelector('kj-password-input input').getAttribute('placeholder'),
+    ).toBe('Enter password');
+  });
+
+  test('renders the show/hide toggle by default', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const button = fixture.nativeElement.querySelector('kj-password-input button');
+    expect(button).not.toBeNull();
+    expect(button.getAttribute('aria-label')).toBe('Show password');
+    expect(button.getAttribute('aria-controls')).toBeTruthy();
+  });
+
+  test('hides the toggle when kjShowToggle is false', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.showToggle = false;
+    fixture.detectChanges();
+    expect(fixture.nativeElement.querySelector('kj-password-input button')).toBeNull();
+  });
+
+  test('clicking the toggle flips the input type', async () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const input = fixture.nativeElement.querySelector('kj-password-input input');
+    const button = fixture.nativeElement.querySelector('kj-password-input button');
+    expect(input.getAttribute('type')).toBe('password');
+    button.click();
+    fixture.detectChanges();
+    await new Promise((r) => setTimeout(r, 0));
+    fixture.detectChanges();
+    expect(input.getAttribute('type')).toBe('text');
+  });
+
+  test('renders the strength meter when kjShowStrength is true', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.showStrength = true;
+    fixture.detectChanges();
+    const meter = fixture.nativeElement.querySelector('[kjPasswordStrength]');
+    expect(meter).not.toBeNull();
+    expect(meter.getAttribute('role')).toBe('progressbar');
+  });
+
+  test('renders the caps lock warning when kjShowCapsLockWarning is true', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.showCapsLock = true;
+    fixture.detectChanges();
+    const warn = fixture.nativeElement.querySelector('[kjPasswordCapsLockWarning]');
+    expect(warn).not.toBeNull();
+    expect(warn.getAttribute('role')).toBe('status');
+    expect(warn.hasAttribute('hidden')).toBe(true);
+  });
+
+  test('forwards kjDisabled to aria-disabled on the input', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.disabled = true;
+    fixture.detectChanges();
+    const input = fixture.nativeElement.querySelector('kj-password-input input');
+    expect(input.getAttribute('aria-disabled')).toBe('true');
+  });
+});

package/src/password-input/password-input.ts

@@ -0,0 +1,254 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  type OnInit,
+  ViewEncapsulation,
+  booleanAttribute,
+  computed,
+  inject,
+  input,
+  model,
+} from '@angular/core';
+import { FormControl, FormsModule, ReactiveFormsModule } from '@angular/forms';
+import {
+  KJ_PASSWORD_INPUT,
+  KjButton,
+  KjPasswordCapsLockWarning,
+  KjPasswordInput,
+  KjPasswordInputScope,
+  KjPasswordStrength,
+  KjPasswordToggle,
+  type KjPasswordAutocomplete,
+  type KjPasswordScore,
+} from '@kouji-ui/core';
+
+/**
+ * Styled wrapper around the headless `KjPasswordInput` directive family. Owns
+ * the visual shape of the input + toggle button, and renders the optional
+ * strength meter and Caps Lock warning when their feature flags are on.
+ *
+ * The component composes four directives behind a single API:
+ * - `KjPasswordInputScope` on the wrapper (provides the shared context).
+ * - `KjPasswordInput` on the inner `<input>`.
+ * - `KjPasswordToggle` on a composed `[kjButton]` next to the input.
+ * - `KjPasswordStrength` and `KjPasswordCapsLockWarning` rendered conditionally.
+ *
+ * @example
+ * ```html
+ * <kj-password-input
+ *   [(kjValue)]="password"
+ *   kjAutocomplete="new-password"
+ *   [kjShowStrength]="true"
+ *   [kjShowCapsLockWarning]="true" />
+ * ```
+ *
+ * @doc-example Default
+ *   The bare-minimum recipe — a sign-in password input with the toggle button.
+ *   @doc-file password-input.example.ts
+ * @doc-example Usage
+ *   A walkthrough of the most common usages — sign-in, sign-up with strength
+ *   meter, and a disabled state. Use this as the copy-paste starting point.
+ *   @doc-file password-input.usage.example.ts
+ * @doc-example Show / hide toggle
+ *   Two-way bind `[(kjRevealed)]` to drive the inner icon from outside.
+ *   @doc-file password-input.toggle.example.ts
+ * @doc-example Strength meter
+ *   `[kjShowStrength]="true"` renders the four-segment estimator under the row.
+ *   @doc-file password-input.strength.example.ts
+ * @doc-example With validation rules
+ *   Live rule list bound to the value; pairs well with reactive forms.
+ *   @doc-file password-input.with-rules.example.ts
+ *
+ * @doc-keyboard
+ *   Tab              — Moves focus into the input, then onto the toggle button
+ *   Enter            — Submits the parent <form> when present (native input behavior)
+ *   Space (on toggle) — Flips the reveal state
+ *
+ * @doc-aria
+ *   type="password"|"text" — Native attribute toggles when `kjRevealed` flips
+ *   aria-pressed     — Reflected on the toggle button (mirrors `kjRevealed`)
+ *   aria-label       — Wired from `kjShowLabel` / `kjHideLabel` per state
+ *   aria-invalid     — Reflected on the input when `kjInvalid` is true
+ *   aria-disabled    — Reflected on input and toggle when `kjDisabled` is true
+ *   role="status"    — Used by the optional Caps Lock warning paragraph
+ *
+ * @doc-touch
+ *   The toggle button uses `kjSize="icon"` (44×44) so it meets WCAG 2.5.5.
+ *   The input row matches `kj-input` height for form-row alignment.
+ *
+ * @doc-a11y
+ *   The toggle button never reads the password aloud — it only flips the
+ *   native input type. The Caps Lock warning is a live region so AT
+ *   announces the state change without stealing focus. Strength feedback is
+ *   rendered as decorative segments — pair with a textual cue if the score
+ *   is the only signal carrying meaning.
+ *
+ * @doc-related input,field,form
+ *
+ * @doc-css-var
+ *   --kj-password-input-bg                — Background fill. Inherits --kj-bg-field.
+ *   --kj-password-input-fg                — Foreground (text) color.
+ *   --kj-password-input-border-color      — Border color. Flips to danger when invalid.
+ *   --kj-password-input-border-style      — Border style. Defaults to solid.
+ *   --kj-password-input-border-width      — Border thickness. Inherits --kj-border.
+ *   --kj-password-input-radius            — Corner radius. Inherits --kj-radius-field.
+ *   --kj-password-input-padding-x         — Horizontal padding inside the field row.
+ *   --kj-password-input-padding-y         — Vertical padding inside the field row.
+ *   --kj-password-input-font              — Font family. Defaults to --kj-font-sans.
+ *   --kj-password-input-font-size         — Font size. Size attributes override.
+ *   --kj-password-input-placeholder-fg    — Placeholder text color.
+ *   --kj-password-input-toggle-fg         — Show/hide toggle icon color.
+ *   --kj-password-input-toggle-fg-hover   — Show/hide toggle icon color on hover or focus.
+ *   --kj-password-input-height            — Row height. Matches input/select for form alignment.
+ *
+ * @doc-category Library/Data input
+ * @doc
+ * @doc-name password-input
+ * @doc-description Themed password input with show/hide toggle, optional strength meter, and Caps Lock warning.
+ * @doc-is-main
+ */
+@Component({
+  selector: 'kj-password-input',
+  standalone: true,
+  imports: [
+    FormsModule,
+    ReactiveFormsModule,
+    KjButton,
+    KjPasswordInput,
+    KjPasswordInputScope,
+    KjPasswordToggle,
+    KjPasswordStrength,
+    KjPasswordCapsLockWarning,
+  ],
+  template: `
+    <div kjPasswordInputScope class="kj-password-input">
+      <input
+        kjPasswordInput
+        class="kj-password-input__field"
+        [kjAutocomplete]="kjAutocomplete()"
+        [kjMaxLength]="kjMaxLength()"
+        [kjDisabled]="kjDisabled()"
+        [kjInvalid]="kjInvalid()"
+        [(kjRevealed)]="kjRevealed"
+        [placeholder]="kjPlaceholder()"
+        [formControl]="control"
+      />
+      @if (kjShowToggle()) {
+        <button
+          kjButton
+          kjPasswordToggle
+          class="kj-password-input__toggle"
+          [kjVariant]="'ghost'"
+          [kjSize]="'icon'"
+          [kjShowLabel]="kjShowLabel()"
+          [kjHideLabel]="kjHideLabel()"
+        >
+          @if (kjRevealed()) {
+            <svg class="kj-password-input__icon" viewBox="0 0 24 24" aria-hidden="true">
+              <path d="M3 3l18 18M10.7 10.7a3 3 0 0 0 4.2 4.2M9.3 5.5A10.5 10.5 0 0 1 12 5c5 0 9.3 3.4 10.5 7-.3 1-.9 2-1.7 2.9M6.6 6.6C4.4 8 2.9 9.9 2 11.5 3.2 15.1 7.5 18.5 12 18.5c1.5 0 2.9-.4 4.2-1" />
+            </svg>
+          } @else {
+            <svg class="kj-password-input__icon" viewBox="0 0 24 24" aria-hidden="true">
+              <path d="M2 12c2-4 5.5-7 10-7s8 3 10 7c-2 4-5.5 7-10 7s-8-3-10-7z" />
+              <circle cx="12" cy="12" r="3" />
+            </svg>
+          }
+        </button>
+      }
+      @if (kjShowStrength()) {
+        <div class="kj-password-strength" kjPasswordStrength [attr.data-score]="score()">
+          <span class="kj-password-strength__seg"></span>
+          <span class="kj-password-strength__seg"></span>
+          <span class="kj-password-strength__seg"></span>
+          <span class="kj-password-strength__seg"></span>
+        </div>
+      }
+      @if (kjShowCapsLockWarning()) {
+        <p kjPasswordCapsLockWarning class="kj-password-caps-lock-warning">
+          {{ kjCapsLockMessage() }}
+        </p>
+      }
+    </div>
+  `,
+  styleUrl: './password-input.css',
+  encapsulation: ViewEncapsulation.None,
+  host: { 'style': 'display: contents;' },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjPasswordInputComponent implements OnInit {
+  /**
+   * Native `autocomplete` attribute. Restricted to `'current-password'` |
+   * `'new-password'` | `'off'`.
+   * @default 'current-password'
+   */
+  readonly kjAutocomplete = input<KjPasswordAutocomplete>('current-password');
+
+  /** Native `maxlength` attribute. */
+  readonly kjMaxLength = input<number>(Number.POSITIVE_INFINITY);
+
+  /** Disabled state. Reflects to the host `KjPasswordInput`. */
+  readonly kjDisabled = input(false, { transform: booleanAttribute });
+
+  /** Invalid state — wires to ARIA-invalid via the host `KjInput`. */
+  readonly kjInvalid = input(false, { transform: booleanAttribute });
+
+  /** Two-way bindable plain-text reveal state. @default false */
+  readonly kjRevealed = model<boolean>(false);
+
+  /** Placeholder text on the inner `<input>`. */
+  readonly kjPlaceholder = input<string>('');
+
+  /** Two-way bindable value (proxy CVA for non-form usage). */
+  readonly kjValue = model<string>('');
+
+  /** Show the show/hide toggle button. @default true */
+  readonly kjShowToggle = input(true, { transform: booleanAttribute });
+
+  /** Show the strength meter under the input. @default false */
+  readonly kjShowStrength = input(false, { transform: booleanAttribute });
+
+  /** Show the Caps Lock warning element. @default false */
+  readonly kjShowCapsLockWarning = input(false, { transform: booleanAttribute });
+
+  /** `aria-label` for the toggle when password is hidden. @default 'Show password' */
+  readonly kjShowLabel = input<string>('Show password');
+
+  /** `aria-label` for the toggle when password is revealed. @default 'Hide password' */
+  readonly kjHideLabel = input<string>('Hide password');
+
+  /** Caps Lock warning message (overridable for i18n). */
+  readonly kjCapsLockMessage = input<string>('Caps Lock is on.');
+
+  /** @internal — bridges template-bound `[(kjValue)]` to the inner `KjPasswordInput`. */
+  protected readonly control = new FormControl<string>('', { nonNullable: true });
+
+  /** @internal — exposes the score for the strength meter's data attr. */
+  protected readonly score = computed<KjPasswordScore>(() => {
+    // The directive provides the full `KJ_PASSWORD_INPUT` context; we re-read
+    // the score for the data-attribute styling hook on our wrapper element.
+    // The host-bound `data-score` from `KjPasswordStrength` already exists,
+    // but mirroring it here lets CSS target the wrapper without `:has()`.
+    const ctx = this._ctx;
+    return ctx?.score() ?? 0;
+  });
+
+  /**
+   * @internal — context resolved from the same scope. Optional because the
+   * component itself owns the `[kjPasswordInputScope]` element, so injection
+   * resolves up via the providers chain after init. If unavailable, the
+   * meter still renders with score 0.
+   */
+  private readonly _ctx = inject(KJ_PASSWORD_INPUT, { optional: true });
+
+  constructor() {
+    // Two-way bind value <-> control.
+    this.control.valueChanges.subscribe(v => this.kjValue.set(v ?? ''));
+  }
+
+  ngOnInit(): void {
+    if (this.kjValue() !== this.control.value) {
+      this.control.setValue(this.kjValue(), { emitEvent: false });
+    }
+  }
+}
+

package/src/password-input/password-input.usage.example.ts

@@ -0,0 +1,55 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjPasswordInputComponent } from './password-input';
+
+/**
+ * A walkthrough of the most common password-input usages — a sign-in field,
+ * a sign-up field with the strength meter and Caps Lock warning, and a
+ * disabled state. Use this as the copy-paste starting point for auth forms.
+ */
+@Component({
+  selector: 'kj-password-input-usage-example',
+  standalone: true,
+  imports: [KjPasswordInputComponent],
+  styles: [
+    `
+      :host {
+        display: flex;
+        flex-direction: column;
+        gap: var(--kj-space-lg);
+        max-width: 22rem;
+      }
+      label {
+        display: grid;
+        gap: var(--kj-space-xs);
+        font-size: 0.875rem;
+        color: var(--kj-fg-default);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <!-- eslint-disable-next-line @angular-eslint/template/label-has-associated-control -->
+    <label>
+      Current password
+      <kj-password-input kjAutocomplete="current-password" kjPlaceholder="Enter your password" />
+    </label>
+
+    <!-- eslint-disable-next-line @angular-eslint/template/label-has-associated-control -->
+    <label>
+      New password
+      <kj-password-input
+        kjAutocomplete="new-password"
+        kjPlaceholder="Choose a strong one"
+        [kjShowStrength]="true"
+        [kjShowCapsLockWarning]="true"
+      />
+    </label>
+
+    <!-- eslint-disable-next-line @angular-eslint/template/label-has-associated-control -->
+    <label>
+      Read-only (disabled)
+      <kj-password-input [kjDisabled]="true" kjPlaceholder="Locked" />
+    </label>
+  `,
+})
+export class KjPasswordInputUsageExample {}