@kouji-ui/core 0.0.4 → 0.1.1

package/src/kbd/kbd.ts

@@ -0,0 +1,132 @@
+import {
+  Directive,
+  ElementRef,
+  afterNextRender,
+  inject,
+  isDevMode,
+} from '@angular/core';
+import { KjSize, type KjSizePreset } from '../presets';
+
+/**
+ * Default size preset used by Kbd consumers (`xs / sm / md / lg`, default `md`).
+ *
+ * Re-exported so core-package consumers applying `[kjKbd]` directly to their
+ * own `<kbd>` elements can opt into the same size scale the eventual styled
+ * wrapper will provide, via:
+ *
+ * ```ts
+ * providers: [{ provide: KJ_SIZE_PRESET, useValue: KJ_KBD_SIZE_PRESET }]
+ * ```
+ *
+ * Avoids the silent-drift case where a consumer picks `'huge'` and the
+ * directive's dev-mode validator passes (because the consumer's preset didn't
+ * list it) but the CSS doesn't recognise the value. See
+ * `docs/component-analyses/data-display/kbd.md` (Open question 13).
+ */
+export const KJ_KBD_SIZE_PRESET: KjSizePreset = {
+  values: ['xs', 'sm', 'md', 'lg'],
+  default: 'md',
+};
+
+/**
+ * Marks an element as a kouji keyboard-key visual (`<kbd>`). The directive is
+ * a pure visual primitive: it composes `KjSize` (the only configurable axis)
+ * and otherwise relies on the native `<kbd>` element's a11y semantics.
+ *
+ * The host element is consumer-supplied. The recommended host is `<kbd>`
+ * (native semantic — implicit `role="generic"` per HTML AAM, but commonly
+ * announced with a "key" prefix in verbose AT modes); applying `[kjKbd]` to
+ * any other element is dev-mode warned but not enforced (consumers wanting a
+ * `<span>` host for inline-baseline reasons get an escape hatch).
+ *
+ * **No variant.** Kbd is tonally neutral — there is no "destructive kbd" or
+ * "primary kbd". A future design language wanting e.g. a "deprecated shortcut"
+ * tone can fold in via a CSS-only `[data-deprecated="true"]` attribute without
+ * API churn.
+ *
+ * **No keyboard contract.** Kbd is non-focusable, non-clickable. Consumers
+ * wanting a clickable shortcut chip wrap a `<button kjButton>` around the
+ * `<kbd kjKbd>` and the button owns the click / focus / a11y story. Embedding
+ * a focusable descendant inside `[kjKbd]` is dev-mode warned because most AT
+ * will re-parent or strip the interactive child out of the kbd's accessible
+ * name.
+ *
+ * **No `aria-label` injection.** When the visible text is a unicode glyph
+ * (`⌘`, `⌥`, `↵`) the consumer sets `aria-label` directly on the host —
+ * exactly the same idiom as setting `aria-label` on any HTML element. The
+ * directive does not declare a duplicate input for it. (The eventual
+ * `<kj-kbd>` wrapper exposes a template-driven `kjKbdAriaLabel` input that
+ * forwards to `[attr.aria-label]`; that is the wrapper's call, not the
+ * directive's.)
+ *
+ * @example
+ * ```html
+ * <kbd kjKbd>Enter</kbd>
+ * <kbd kjKbd kjSize="xs">⌘</kbd>
+ * <kbd kjKbd aria-label="Command">⌘</kbd>
+ * ```
+ * @doc-category Core/Data display
+ * @doc
+ * @doc-name kbd
+ * @doc-description Marks a kbd element as a keyboard-key visual with a configurable size.
+ * @doc-is-main
+ */
+@Directive({
+  selector: '[kjKbd]',
+  standalone: true,
+  hostDirectives: [{ directive: KjSize, inputs: ['kjSize'] }],
+})
+export class KjKbd {
+  private readonly el = inject<ElementRef<HTMLElement>>(ElementRef);
+
+  constructor() {
+    if (isDevMode()) {
+      afterNextRender(() => {
+        const host = this.el.nativeElement;
+
+        if (host.tagName?.toLowerCase() !== 'kbd') {
+          console.warn(
+            `[kj] kjKbd applied to <${host.tagName?.toLowerCase()}>. ` +
+              `Recommended host element is <kbd> for native semantics ` +
+              `(WCAG 1.3.1 / 4.1.2). Apply only to non-kbd elements when ` +
+              `you have a specific styling reason.`,
+          );
+        }
+
+        if (hasFocusableDescendant(host)) {
+          console.warn(
+            `[kj] kjKbd contains a focusable descendant. Kbd is a ` +
+              `non-interactive visual primitive; most AT will re-parent or ` +
+              `strip interactive children out of the kbd's accessible name. ` +
+              `Wrap the <kbd kjKbd> inside a <button kjButton> instead of ` +
+              `nesting an interactive element inside it.`,
+          );
+        }
+      });
+    }
+  }
+}
+
+/**
+ * Selector matching elements that are focusable by default. Intentionally
+ * narrow: this is a dev-mode advisory, not an a11y enforcement gate, so we
+ * accept the small risk of missing exotic focusable descendants
+ * (`contenteditable`, embedded `<object>` with focusable controls, etc.) in
+ * favour of a fast first-pass check.
+ */
+const FOCUSABLE_SELECTOR = [
+  'a[href]',
+  'button',
+  'input',
+  'select',
+  'textarea',
+  'audio[controls]',
+  'video[controls]',
+  '[tabindex]',
+  '[contenteditable=""]',
+  '[contenteditable="true"]',
+].join(',');
+
+function hasFocusableDescendant(host: HTMLElement): boolean {
+  return host.querySelector(FOCUSABLE_SELECTOR) !== null;
+}

package/src/link/config.ts

@@ -0,0 +1,44 @@
+import { InjectionToken, Provider } from '@angular/core';
+
+export interface KjLinkConfig {
+  variants: string[];
+  sizes: string[];
+  defaults: { variant: string; size: string };
+}
+
+/**
+ * Default Link presets shipped by kouji-ui. Exported so consumers can spread
+ * them when extending: `[...KJ_LINK_DEFAULTS.variants, 'brand']`.
+ */
+export const KJ_LINK_DEFAULTS: KjLinkConfig = {
+  variants: ['primary', 'secondary', 'muted', 'destructive'],
+  sizes: ['sm', 'md', 'lg', 'inherit'],
+  defaults: { variant: 'primary', size: 'inherit' },
+};
+
+/**
+ * DI token for the active Link presets. Default factory yields
+ * `KJ_LINK_DEFAULTS`. Override via `provideKjLink(…)` at the application
+ * scope (e.g. `bootstrapApplication`'s `providers` or a route's `providers`)
+ * or at the component scope (a component's own `providers: […]`).
+ */
+export const KJ_LINK_CONFIG = new InjectionToken<KjLinkConfig>('kj.link.config', {
+  factory: () => KJ_LINK_DEFAULTS,
+});
+
+/**
+ * Configures the Link presets for the enclosing injector. Replaces (does not
+ * merge) `variants` and `sizes`; spread `KJ_LINK_DEFAULTS.variants` to extend.
+ *
+ * Returns a `Provider[]` so it can be spread into either an environment
+ * `providers` (`bootstrapApplication`, route config) or a component-level
+ * `providers` array.
+ */
+export function provideKjLink(config: Partial<KjLinkConfig>): Provider[] {
+  return [
+    {
+      provide: KJ_LINK_CONFIG,
+      useValue: { ...KJ_LINK_DEFAULTS, ...config },
+    },
+  ];
+}

package/src/link/index.ts

@@ -0,0 +1,2 @@
+export * from './link';
+export * from './config';

package/src/link/link.spec.ts

@@ -0,0 +1,246 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { render } from '@testing-library/angular';
+import { describe, expect, it } from 'vitest';
+import { KjLink } from './link';
+
+@Component({
+  standalone: true,
+  imports: [KjLink],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `<a kjLink href="/x" [kjDisabled]="d" (click)="onClick()">x</a>`,
+})
+class DisabledClickHost {
+  d = true;
+  fired = 0;
+  onClick() {
+    this.fired++;
+  }
+}
+
+@Component({
+  standalone: true,
+  imports: [KjLink],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `<a kjLink href="/x" [kjDisabled]="d" (keydown)="onKeydown($event)">x</a>`,
+})
+class DisabledKeydownHost {
+  d = true;
+  navigated = 0;
+  onKeydown(_event: KeyboardEvent) {
+    this.navigated++;
+  }
+}
+
+describe('KjLink', () => {
+  it('renders an anchor with role=link via native <a>', async () => {
+    const { getByRole } = await render(`<a kjLink href="/foo">Foo</a>`, { imports: [KjLink] });
+    expect(getByRole('link')).toBeInTheDocument();
+  });
+
+  it('default variant comes from KJ_LINK_DEFAULTS', async () => {
+    const { getByRole } = await render(`<a kjLink href="/x">x</a>`, { imports: [KjLink] });
+    expect(getByRole('link')).toHaveAttribute('data-variant', 'primary');
+  });
+
+  it('default size comes from KJ_LINK_DEFAULTS', async () => {
+    const { getByRole } = await render(`<a kjLink href="/x">x</a>`, { imports: [KjLink] });
+    expect(getByRole('link')).toHaveAttribute('data-size', 'inherit');
+  });
+
+  it('reflects kjVariant to data-variant', async () => {
+    const { getByRole } = await render(`<a kjLink href="/x" [kjVariant]="'destructive'">x</a>`, {
+      imports: [KjLink],
+    });
+    expect(getByRole('link')).toHaveAttribute('data-variant', 'destructive');
+  });
+
+  it('reflects kjSize to data-size', async () => {
+    const { getByRole } = await render(`<a kjLink href="/x" [kjSize]="'sm'">x</a>`, {
+      imports: [KjLink],
+    });
+    expect(getByRole('link')).toHaveAttribute('data-size', 'sm');
+  });
+
+  it('reflects kjUnderline to data-underline (default hover)', async () => {
+    const { getByRole } = await render(`<a kjLink href="/x">x</a>`, { imports: [KjLink] });
+    expect(getByRole('link')).toHaveAttribute('data-underline', 'hover');
+  });
+
+  it('reflects kjUnderline=always', async () => {
+    const { getByRole } = await render(`<a kjLink href="/x" [kjUnderline]="'always'">x</a>`, {
+      imports: [KjLink],
+    });
+    expect(getByRole('link')).toHaveAttribute('data-underline', 'always');
+  });
+
+  it('reflects kjUnderline=none', async () => {
+    const { getByRole } = await render(`<a kjLink href="/x" [kjUnderline]="'none'">x</a>`, {
+      imports: [KjLink],
+    });
+    expect(getByRole('link')).toHaveAttribute('data-underline', 'none');
+  });
+
+  it('auto-detects external from target="_blank" and reflects data-external', async () => {
+    const { getByRole } = await render(
+      `<a kjLink href="https://example.com" target="_blank">Docs</a>`,
+      { imports: [KjLink] },
+    );
+    expect(getByRole('link')).toHaveAttribute('data-external', 'true');
+  });
+
+  it('does not mark as external when no target="_blank" and kjExternal unset', async () => {
+    const { getByRole } = await render(`<a kjLink href="https://example.com">Docs</a>`, {
+      imports: [KjLink],
+    });
+    expect(getByRole('link')).not.toHaveAttribute('data-external');
+  });
+
+  it('explicit kjExternal=true overrides target detection', async () => {
+    const { getByRole } = await render(`<a kjLink href="/internal" [kjExternal]="true">Docs</a>`, {
+      imports: [KjLink],
+    });
+    expect(getByRole('link')).toHaveAttribute('data-external', 'true');
+  });
+
+  it('explicit kjExternal=false suppresses external treatment even with target=_blank', async () => {
+    const { getByRole } = await render(
+      `<a kjLink href="/x" target="_blank" [kjExternal]="false">x</a>`,
+      { imports: [KjLink] },
+    );
+    expect(getByRole('link')).not.toHaveAttribute('data-external');
+  });
+
+  it('injects rel="noopener noreferrer" when external', async () => {
+    const { getByRole } = await render(
+      `<a kjLink href="https://example.com" target="_blank">Docs</a>`,
+      { imports: [KjLink] },
+    );
+    const rel = getByRole('link').getAttribute('rel') ?? '';
+    const tokens = rel.split(/\s+/u).filter(Boolean);
+    expect(tokens).toContain('noopener');
+    expect(tokens).toContain('noreferrer');
+  });
+
+  it('rel injection is additive — preserves consumer-supplied tokens', async () => {
+    const { getByRole } = await render(
+      `<a kjLink href="https://example.com" target="_blank" rel="nofollow me">Docs</a>`,
+      { imports: [KjLink] },
+    );
+    const rel = getByRole('link').getAttribute('rel') ?? '';
+    const tokens = rel.split(/\s+/u).filter(Boolean);
+    expect(tokens).toContain('nofollow');
+    expect(tokens).toContain('me');
+    expect(tokens).toContain('noopener');
+    expect(tokens).toContain('noreferrer');
+  });
+
+  it('does not add noopener/noreferrer when not external', async () => {
+    const { getByRole } = await render(`<a kjLink href="/internal" rel="nofollow">x</a>`, {
+      imports: [KjLink],
+    });
+    const rel = getByRole('link').getAttribute('rel') ?? '';
+    expect(rel.split(/\s+/u)).not.toContain('noopener');
+    expect(rel.split(/\s+/u)).toContain('nofollow');
+  });
+
+  it('appends visually-hidden "(opens in new tab)" suffix span when external', async () => {
+    const { getByRole } = await render(
+      `<a kjLink href="https://example.com" target="_blank">Docs</a>`,
+      { imports: [KjLink] },
+    );
+    const link = getByRole('link');
+    const suffix = link.querySelector('.kj-link-external-suffix');
+    expect(suffix).not.toBeNull();
+    expect(suffix!.textContent).toContain('opens in new tab');
+    // Visually hidden inline style applied.
+    const style = (suffix as HTMLElement).getAttribute('style') ?? '';
+    expect(style).toContain('width:1px');
+    expect(style).toContain('height:1px');
+  });
+
+  it('does not inject AT suffix when consumer supplies aria-label', async () => {
+    const { getByRole } = await render(
+      `<a kjLink href="https://example.com" target="_blank" aria-label="Docs (new window)">Docs</a>`,
+      { imports: [KjLink] },
+    );
+    const link = getByRole('link');
+    expect(link.querySelector('.kj-link-external-suffix')).toBeNull();
+  });
+
+  it('does not inject AT suffix for non-external links', async () => {
+    const { getByRole } = await render(`<a kjLink href="/x">x</a>`, { imports: [KjLink] });
+    expect(getByRole('link').querySelector('.kj-link-external-suffix')).toBeNull();
+  });
+
+  it('disabled bundle: aria-disabled, data-disabled, tabindex=-1', async () => {
+    const { getByRole } = await render(`<a kjLink href="/x" [kjDisabled]="true">x</a>`, {
+      imports: [KjLink],
+    });
+    const link = getByRole('link');
+    expect(link).toHaveAttribute('aria-disabled', 'true');
+    expect(link).toHaveAttribute('data-disabled', '');
+    expect(link).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('omits aria-disabled / tabindex when not disabled', async () => {
+    const { getByRole } = await render(`<a kjLink href="/x">x</a>`, { imports: [KjLink] });
+    const link = getByRole('link');
+    expect(link).not.toHaveAttribute('aria-disabled');
+    expect(link).not.toHaveAttribute('tabindex');
+  });
+
+  it('suppresses click events when disabled (capture-phase)', () => {
+    TestBed.configureTestingModule({ imports: [DisabledClickHost] });
+    const fixture = TestBed.createComponent(DisabledClickHost);
+    fixture.detectChanges();
+    const link = fixture.nativeElement.querySelector('a') as HTMLAnchorElement;
+    link.click();
+    expect(fixture.componentInstance.fired).toBe(0);
+  });
+
+  it('allows click events when not disabled', () => {
+    TestBed.configureTestingModule({ imports: [DisabledClickHost] });
+    const fixture = TestBed.createComponent(DisabledClickHost);
+    fixture.componentInstance.d = false;
+    fixture.detectChanges();
+    const link = fixture.nativeElement.querySelector('a') as HTMLAnchorElement;
+    link.addEventListener('click', (e) => e.preventDefault(), { once: true });
+    link.click();
+    expect(fixture.componentInstance.fired).toBe(1);
+  });
+
+  it('suppresses Enter keydown events when disabled', () => {
+    TestBed.configureTestingModule({ imports: [DisabledKeydownHost] });
+    const fixture = TestBed.createComponent(DisabledKeydownHost);
+    fixture.detectChanges();
+    const link = fixture.nativeElement.querySelector('a') as HTMLAnchorElement;
+    const event = new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, cancelable: true });
+    link.dispatchEvent(event);
+    expect(event.defaultPrevented).toBe(true);
+    expect(fixture.componentInstance.navigated).toBe(0);
+  });
+
+  it('does not suppress non-Enter keydown when disabled', () => {
+    TestBed.configureTestingModule({ imports: [DisabledKeydownHost] });
+    const fixture = TestBed.createComponent(DisabledKeydownHost);
+    fixture.detectChanges();
+    const link = fixture.nativeElement.querySelector('a') as HTMLAnchorElement;
+    const event = new KeyboardEvent('keydown', { key: 'Tab', bubbles: true, cancelable: true });
+    link.dispatchEvent(event);
+    expect(event.defaultPrevented).toBe(false);
+    expect(fixture.componentInstance.navigated).toBe(1);
+  });
+
+  it('does not suppress Enter when not disabled', () => {
+    TestBed.configureTestingModule({ imports: [DisabledKeydownHost] });
+    const fixture = TestBed.createComponent(DisabledKeydownHost);
+    fixture.componentInstance.d = false;
+    fixture.detectChanges();
+    const link = fixture.nativeElement.querySelector('a') as HTMLAnchorElement;
+    const event = new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, cancelable: true });
+    link.dispatchEvent(event);
+    expect(event.defaultPrevented).toBe(false);
+    expect(fixture.componentInstance.navigated).toBe(1);
+  });
+});

package/src/link/link.ts

@@ -0,0 +1,226 @@
+import { DOCUMENT } from '@angular/common';
+import {
+  Directive,
+  ElementRef,
+  afterNextRender,
+  computed,
+  effect,
+  inject,
+  input,
+} from '@angular/core';
+import { KjFocusRing, KjDisabled } from '../primitives';
+import { KjVariant, KjSize, bindPresets } from '../presets';
+import { KJ_LINK_CONFIG } from './config';
+
+/** CSS class applied to the visually-hidden "(opens in new tab)" suffix span. */
+const KJ_LINK_EXTERNAL_SUFFIX_CLASS = 'kj-link-external-suffix';
+
+/** AT suffix copy. English-only for v1; i18n is a v1.1 concern (see analysis §15). */
+const KJ_LINK_EXTERNAL_SUFFIX_TEXT = '(opens in new tab)';
+
+/** Inline style string equivalent to `KjVisuallyHidden` — applied to the AT suffix span. */
+const KJ_LINK_VISUALLY_HIDDEN_STYLE =
+  'position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border-width:0';
+
+/**
+ * Enhances a native `<a>` (or any element used as a link) with kouji-ui
+ * presets, focus-ring and disabled-link plumbing, and external-link
+ * `rel` + AT suffix discipline.
+ *
+ * Composes `KjVariant`, `KjSize`, `KjFocusRing`, and `KjDisabled` via
+ * `hostDirectives`. Variants and sizes are configurable via
+ * `provideKjLink(…)`.
+ *
+ * Owns three behaviours that a CSS-only solution cannot deliver:
+ *
+ * 1. **External-link plumbing.** When `kjExternal` is `true` (or `undefined`
+ *    and the host carries `target="_blank"`), the directive ensures `rel`
+ *    contains both `noopener` and `noreferrer` (additive — preserves any
+ *    consumer-supplied `rel` tokens like `nofollow`, `me`, `bookmark`) and
+ *    appends a visually-hidden `(opens in new tab)` `<span>` to the host's
+ *    accessible name. The suffix is suppressed when the consumer has set
+ *    their own `aria-label` (the consumer is presumed to have authored the
+ *    complete accessible name).
+ *
+ * 2. **Disabled-link bundle.** When `kjDisabled` is `true`, the directive
+ *    sets `aria-disabled="true"`, `tabindex="-1"`, and capture-phase
+ *    intercepts both `click` and `keydown.enter` to call `preventDefault()`
+ *    and `stopImmediatePropagation()`. Capture phase ensures the suppression
+ *    runs before any consumer-bound `(click)` handler and before Angular
+ *    Router's bubble-phase click handler — so `<a kjLink routerLink="/foo"
+ *    [kjDisabled]="true">` does not navigate either.
+ *
+ * 3. **Underline-mode reflection.** `kjUnderline: 'always' | 'hover' |
+ *    'none'` reflects to `[attr.data-underline]` for the components-package
+ *    CSS to key off. The `kj-prose a` selector overrides only when the
+ *    directive's input is left at its default — explicit consumer values
+ *    win over the prose container's defaults.
+ *
+ * @example
+ * ```html
+ * <a kjLink href="/about">Inline link</a>
+ * <a kjLink href="https://example.com" target="_blank">External</a>
+ * <a kjLink [kjDisabled]="!ready()" routerLink="/billing">Manage billing</a>
+ * ```
+ *
+ * @doc-category Core/Navigation
+ * @doc
+ * @doc-name link
+ * @doc-description Adds disabled-link, external-link, and underline-mode handling to a native anchor.
+ * @doc-is-main
+ */
+@Directive({
+  selector: 'a[kjLink], [kjLink]',
+  standalone: true,
+  hostDirectives: [
+    { directive: KjVariant, inputs: ['kjVariant'] },
+    { directive: KjSize, inputs: ['kjSize'] },
+    KjFocusRing,
+    { directive: KjDisabled, inputs: ['kjDisabled'] },
+  ],
+  providers: [...bindPresets(KJ_LINK_CONFIG)],
+  host: {
+    '[attr.data-underline]': 'kjUnderline()',
+    '[attr.data-external]': 'isExternal() ? "true" : null',
+    '[attr.tabindex]': 'kjDisabled() ? "-1" : null',
+    '[attr.rel]': 'relAttr()',
+  },
+})
+export class KjLink {
+  private readonly el = inject<ElementRef<HTMLElement>>(ElementRef);
+  private readonly document = inject(DOCUMENT);
+
+  /**
+   * Disables the link. Forwarded to `KjDisabled` (which reflects
+   * `aria-disabled` and `data-disabled`); the directive additionally sets
+   * `tabindex="-1"` and intercepts `click` + `keydown.enter` in the capture
+   * phase.
+   */
+  readonly kjDisabled = input(false);
+
+  /**
+   * Underline policy. `'always'` for in-content links (WCAG 1.4.1 — colour
+   * is not the only means); `'hover'` for standalone links sitting in a
+   * group of links that already signals "this is a link" via layout;
+   * `'none'` for the rare cases where the consumer wants to suppress the
+   * underline entirely (e.g. icon-text links inside breadcrumb separators).
+   * Reflects `[attr.data-underline]`.
+   */
+  readonly kjUnderline = input<'always' | 'hover' | 'none'>('hover');
+
+  /**
+   * External-link tri-state. `undefined` (default) auto-detects from the
+   * host's `target` attribute (`target="_blank"` → external). `true` forces
+   * external treatment regardless of `target` (e.g. for cross-origin URLs
+   * served through the app's router that still warrant the indicator).
+   * `false` forces internal treatment even when `target="_blank"` is
+   * present (suppresses the icon and AT suffix).
+   */
+  readonly kjExternal = input<boolean | undefined>(undefined);
+
+  /** Whether the host element currently carries `target="_blank"`. */
+  protected readonly hasBlankTarget = computed(() => this.targetSignal() === '_blank');
+
+  /** Computed external state — explicit input wins, else target-based auto-detect. */
+  protected readonly isExternal = computed(() => {
+    const explicit = this.kjExternal();
+    if (explicit !== undefined) return explicit;
+    return this.hasBlankTarget();
+  });
+
+  /**
+   * `rel` attribute computation. Additive: existing tokens (`nofollow`,
+   * `me`, `bookmark`, …) are preserved; the directive only adds the missing
+   * `noopener` / `noreferrer` security tokens when external. When not
+   * external, the directive returns `null` so the consumer's literal `rel`
+   * attribute (read at construction) is preserved as-is.
+   */
+  protected readonly relAttr = computed(() => {
+    if (!this.isExternal()) return this.initialRel || null;
+    const tokens = new Set<string>();
+    if (this.initialRel) {
+      for (const token of this.initialRel.split(/\s+/u)) {
+        if (token) tokens.add(token);
+      }
+    }
+    tokens.add('noopener');
+    tokens.add('noreferrer');
+    return [...tokens].join(' ');
+  });
+
+  /**
+   * Snapshot of the host's `target` attribute. Re-read after the host
+   * renders — host bindings are evaluated synchronously on creation, so
+   * the SSR HTML carries the right `[data-external]` / `[rel]` values
+   * provided the consumer's `target` is set declaratively in the template
+   * (the common case).
+   */
+  private readonly targetSignal = (() => {
+    const initial = this.el.nativeElement.getAttribute('target');
+    return computed(() => initial);
+  })();
+
+  /** Snapshot of the host's `rel` attribute at construction time. */
+  private readonly initialRel: string | null = this.el.nativeElement.getAttribute('rel');
+
+  /** Reference to the injected AT suffix span, if any. Cleaned up on toggle. */
+  private suffixSpan: HTMLSpanElement | null = null;
+
+  constructor() {
+    // Capture-phase native listeners: fire BEFORE Angular's template-bound
+    // bubble-phase (click) handlers and before Angular Router's bubble-phase
+    // click handler on `<a routerLink>`, so `stopImmediatePropagation()`
+    // actually prevents both navigation and any consumer (click) handlers.
+    afterNextRender(() => {
+      const node = this.el.nativeElement;
+
+      const onClick = (event: Event) => {
+        if (this.kjDisabled()) {
+          event.preventDefault();
+          event.stopImmediatePropagation();
+        }
+      };
+
+      const onKeydown = (event: KeyboardEvent) => {
+        if (this.kjDisabled() && event.key === 'Enter') {
+          event.preventDefault();
+          event.stopImmediatePropagation();
+        }
+      };
+
+      node.addEventListener('click', onClick, { capture: true });
+      node.addEventListener('keydown', onKeydown, { capture: true });
+    });
+
+    // External-link AT suffix injection. Runs reactively so the suffix
+    // appears / disappears as `kjExternal` (or the host's `target`) changes.
+    // The effect itself is created in injection context (constructor); its
+    // first run happens after the first change-detection pass, by which
+    // point the host element has been attached to the DOM in browser
+    // contexts. Use injected DOCUMENT — prerender VMs may have no global `document`.
+    effect(() => {
+      const external = this.isExternal();
+      const doc = this.document;
+      if (!doc.createElement) return;
+
+      const node = this.el.nativeElement;
+      const consumerOwnsName = node.hasAttribute('aria-label');
+
+      if (external && !consumerOwnsName) {
+        if (!this.suffixSpan) {
+          const span = doc.createElement('span');
+          span.className = KJ_LINK_EXTERNAL_SUFFIX_CLASS;
+          span.setAttribute('style', KJ_LINK_VISUALLY_HIDDEN_STYLE);
+          // Leading space so AT reads "Documentation (opens in new tab)"
+          // not "Documentation(opens in new tab)".
+          span.textContent = ` ${KJ_LINK_EXTERNAL_SUFFIX_TEXT}`;
+          node.appendChild(span);
+          this.suffixSpan = span;
+        }
+      } else if (this.suffixSpan) {
+        this.suffixSpan.remove();
+        this.suffixSpan = null;
+      }
+    });
+  }
+}

package/src/list/index.ts

@@ -0,0 +1,11 @@
+export {
+  KjList,
+  KjListRow,
+  KJ_LIST,
+  KJ_LIST_ROW,
+} from './list';
+export type {
+  KjListAs,
+  KjListContext,
+  KjListRowContext,
+} from './list';