@kouji-ui/components 0.1.1

package/src/link/link.spec.ts

@@ -0,0 +1,146 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { describe, expect, test, beforeEach } from 'vitest';
+import { KjLinkComponent } from './link';
+
+@Component({
+  standalone: true,
+  imports: [KjLinkComponent],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-link
+      [kjHref]="href"
+      [kjTarget]="target"
+      [kjAriaLabel]="ariaLabel"
+      [kjVariant]="variant"
+      [kjSize]="size"
+      [kjUnderline]="underline"
+      [kjExternal]="external"
+      [kjDisabled]="disabled"
+      >{{ label }}</kj-link
+    >
+  `,
+})
+class HostComponent {
+  href: string | undefined = '/docs';
+  target: string | undefined = undefined;
+  ariaLabel: string | undefined = undefined;
+  variant = 'primary';
+  size = 'inherit';
+  underline: 'always' | 'hover' | 'none' = 'hover';
+  external: boolean | undefined = undefined;
+  disabled = false;
+  label = 'Click';
+}
+
+describe('KjLinkComponent', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({ imports: [HostComponent] });
+  });
+
+  test('renders an inner <a> with the .kj-link class', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const a = fixture.nativeElement.querySelector('kj-link a.kj-link');
+    expect(a).not.toBeNull();
+  });
+
+  test('forwards kjHref to the inner anchor href', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.href = '/docs/components/link';
+    fixture.detectChanges();
+    const a = fixture.nativeElement.querySelector('kj-link a.kj-link');
+    expect(a.getAttribute('href')).toBe('/docs/components/link');
+  });
+
+  test('forwards kjVariant to data-variant on inner <a>', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.variant = 'destructive';
+    fixture.detectChanges();
+    const a = fixture.nativeElement.querySelector('kj-link a.kj-link');
+    expect(a.getAttribute('data-variant')).toBe('destructive');
+  });
+
+  test('forwards kjSize to data-size on inner <a>', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.size = 'sm';
+    fixture.detectChanges();
+    const a = fixture.nativeElement.querySelector('kj-link a.kj-link');
+    expect(a.getAttribute('data-size')).toBe('sm');
+  });
+
+  test('forwards kjUnderline to data-underline on inner <a>', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.underline = 'always';
+    fixture.detectChanges();
+    const a = fixture.nativeElement.querySelector('kj-link a.kj-link');
+    expect(a.getAttribute('data-underline')).toBe('always');
+  });
+
+  test('forwards kjTarget to the inner <a> target attribute', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.href = 'https://example.com';
+    fixture.componentInstance.target = '_blank';
+    fixture.detectChanges();
+    const a = fixture.nativeElement.querySelector('kj-link a.kj-link');
+    expect(a.getAttribute('target')).toBe('_blank');
+  });
+
+  test('kjExternal=true forces external treatment (data-external="true")', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.href = 'https://example.com';
+    fixture.componentInstance.external = true;
+    fixture.detectChanges();
+    const a = fixture.nativeElement.querySelector('kj-link a.kj-link');
+    expect(a.getAttribute('data-external')).toBe('true');
+  });
+
+  test('external link injects rel="noopener noreferrer" (additive)', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.href = 'https://example.com';
+    fixture.componentInstance.external = true;
+    fixture.detectChanges();
+    const a = fixture.nativeElement.querySelector('kj-link a.kj-link');
+    const rel = (a.getAttribute('rel') ?? '').split(/\s+/u).filter(Boolean);
+    expect(rel).toContain('noopener');
+    expect(rel).toContain('noreferrer');
+  });
+
+  test('external link gets the AT suffix span', async () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.href = 'https://example.com';
+    fixture.componentInstance.external = true;
+    fixture.detectChanges();
+    await fixture.whenStable();
+    fixture.detectChanges();
+    const a = fixture.nativeElement.querySelector('kj-link a.kj-link');
+    const suffix = a.querySelector('.kj-link-external-suffix');
+    expect(suffix).not.toBeNull();
+    expect(suffix!.textContent).toContain('opens in new tab');
+  });
+
+  test('forwards kjDisabled bundle (aria-disabled, data-disabled, tabindex=-1)', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.disabled = true;
+    fixture.detectChanges();
+    const a = fixture.nativeElement.querySelector('kj-link a.kj-link');
+    expect(a.getAttribute('aria-disabled')).toBe('true');
+    expect(a.getAttribute('data-disabled')).toBe('');
+    expect(a.getAttribute('tabindex')).toBe('-1');
+  });
+
+  test('forwards kjAriaLabel to the inner <a>', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.ariaLabel = 'Open documentation';
+    fixture.detectChanges();
+    const a = fixture.nativeElement.querySelector('kj-link a.kj-link');
+    expect(a.getAttribute('aria-label')).toBe('Open documentation');
+  });
+
+  test('projects content into the inner anchor', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const a = fixture.nativeElement.querySelector('kj-link a.kj-link');
+    expect(a.textContent.trim()).toBe('Click');
+  });
+});

package/src/link/link.ts

@@ -0,0 +1,133 @@
+import { Component, ChangeDetectionStrategy, ViewEncapsulation, input } from '@angular/core';
+import { KjLink } from '@kouji-ui/core';
+
+/**
+ * Styled wrapper around the headless `KjLink` directive.
+ *
+ * Renders `<a kjLink>` underneath (mirrors `KjDividerComponent`'s "directive on
+ * inner host" pattern: the visible link element must be the native `<a>` so the
+ * directive's data attributes, ARIA semantics, and external/disabled plumbing
+ * land on the actual hyperlink rather than the `display: contents` outer
+ * `<kj-link>` custom element). Variant and size are user-configurable strings;
+ * configure the allowed values and defaults via `provideKjLink(…)` at the
+ * application or component scope.
+ *
+ * @example
+ * ```html
+ * <kj-link kjHref="/about">About</kj-link>
+ * <kj-link kjHref="https://example.com" kjTarget="_blank">External</kj-link>
+ * <kj-link kjHref="/billing" [kjDisabled]="!ready()">Manage billing</kj-link>
+ * ```
+ *
+ * @doc-example Default
+ *   Inline link with default chrome — anchors the variant / size / underline defaults.
+ *   @doc-file link.example.ts
+ * @doc-example Usage
+ *   Common link shapes — inline prose, external, disabled, and a few sizes.
+ *   @doc-file link.usage.example.ts
+ * @doc-example Variants
+ *   Primary / muted / destructive — pick the tone that matches the destination.
+ *   @doc-file link.variants.example.ts
+ * @doc-example Sizes
+ *   `sm` / `md` / `lg` / `inherit` — `inherit` matches the surrounding text.
+ *   @doc-file link.sizes.example.ts
+ * @doc-example External
+ *   `kjTarget="_blank"` enables external-icon auto-detect; pair with rel safe defaults.
+ *   @doc-file link.external.example.ts
+ * @doc-example Disabled
+ *   `[kjDisabled]="true"` removes the link from the tab order and dims it.
+ *   @doc-file link.disabled.example.ts
+ * @doc-example In prose
+ *   Links flow naturally with surrounding text without breaking baseline.
+ *   @doc-file link.in-prose.example.ts
+ *
+ * @doc-keyboard
+ *   Enter — Activates the link (native anchor semantics)
+ *   Tab   — Moves focus to the next focusable element; disabled links are skipped
+ *
+ * @doc-aria
+ *   aria-disabled — Reflected when [kjDisabled] is true; tabindex flipped to -1
+ *   aria-label    — Forwarded to the inner <a>; suppresses the AT external-suffix when set
+ *   data-variant  — Mirrors the resolved variant for theme CSS
+ *   data-size     — Mirrors the resolved size for theme CSS
+ *   data-external — Mirrors the external-link detection for the trailing icon
+ *
+ * @doc-touch
+ *   Inline links rely on WCAG 2.5.5's inline-text-link exception. Use
+ *   `kjSize="lg"` (or a `kj-button kjVariant="link"`) when the link is a
+ *   standalone touch target outside running text.
+ *
+ * @doc-a11y
+ *   Renders a real `<a kjLink>` so AT announces "link", focus visibility
+ *   comes from `:focus-visible` only, and disabled links are kept out of the
+ *   tab order. External targets get a trailing icon plus an AT suffix unless
+ *   `[kjAriaLabel]` is set.
+ *
+ * @doc-related button,icon,typography
+ *
+ * @doc-css-var
+ *   --kj-link-fg               — Link color at rest. Variants retarget this.
+ *   --kj-link-hover-fg         — Link color on hover. Variants retarget this.
+ *   --kj-link-visited-fg       — Color applied to `:visited` links.
+ *   --kj-link-decoration       — Text-decoration. Underline mode (always/hover/none) retargets this.
+ *   --kj-link-underline-offset — Distance between the text baseline and the underline.
+ *   --kj-link-font-size        — Font size. Sizes (sm/md/lg/inherit) override; defaults to inherit.
+ *   --kj-link-radius           — Corner radius applied to the focus ring.
+ *   --kj-link-external-icon    — Mask URL for the trailing external-link glyph. Swap for a custom icon.
+ *
+ * @doc-category Library/Navigation
+ * @doc
+ * @doc-name link
+ * @doc-description Themed hyperlink with variant, size, underline mode, external-link handling, and disabled semantics.
+ * @doc-is-main
+ */
+@Component({
+  selector: 'kj-link',
+  standalone: true,
+  imports: [KjLink],
+  template: `
+    <a
+      kjLink
+      class="kj-link"
+      [attr.href]="kjHref() ?? null"
+      [attr.target]="kjTarget() ?? null"
+      [attr.aria-label]="kjAriaLabel() ?? null"
+      [kjVariant]="kjVariant()"
+      [kjSize]="kjSize()"
+      [kjUnderline]="kjUnderline()"
+      [kjExternal]="kjExternal()"
+      [kjDisabled]="kjDisabled()"
+    >
+      <ng-content />
+    </a>
+  `,
+  styleUrl: './link.css',
+  encapsulation: ViewEncapsulation.None,
+  host: { style: 'display: contents;' },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjLinkComponent {
+  /** Bound to the inner `<a [href]>`. */
+  readonly kjHref = input<string | undefined>(undefined);
+
+  /** Bound to the inner `<a [target]>`. Setting `_blank` triggers external auto-detect in `KjLink`. */
+  readonly kjTarget = input<'_self' | '_blank' | '_parent' | '_top' | string | undefined>(undefined);
+
+  /** Bound to `[attr.aria-label]` on the inner `<a>`. When set, suppresses the AT suffix injection. */
+  readonly kjAriaLabel = input<string | undefined>(undefined);
+
+  /** Forwarded to the directive's `KjVariant` host directive. */
+  readonly kjVariant = input<string>('primary');
+
+  /** Forwarded to the directive's `KjSize` host directive. */
+  readonly kjSize = input<string>('inherit');
+
+  /** Forwarded to the directive's underline-mode reflection. */
+  readonly kjUnderline = input<'always' | 'hover' | 'none'>('hover');
+
+  /** Forwarded to the directive's external-link tri-state. */
+  readonly kjExternal = input(false);
+
+  /** Forwarded to the directive's disabled bundle (composed `KjDisabled` + plumbing). */
+  readonly kjDisabled = input(false);
+}

package/src/link/link.usage.example.ts

@@ -0,0 +1,37 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { KjLinkComponent } from './link';
+
+/**
+ * Common link shapes — inline prose, external, disabled, and a few sizes.
+ * Copy-paste starting point for navigation surfaces.
+ */
+@Component({
+  selector: 'kj-link-usage-example',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [KjLinkComponent],
+  styles: [`
+    :host { display: flex; flex-direction: column; gap: var(--kj-space-md); max-width: 60ch; }
+    p { line-height: 1.6; margin: 0; }
+    .row { display: flex; gap: var(--kj-space-md); align-items: baseline; flex-wrap: wrap; }
+  `],
+  template: `
+    <p>
+      Inline:
+      <kj-link kjHref="/docs" kjUnderline="always">read the documentation</kj-link>
+      or <kj-link kjHref="/playground" kjUnderline="always">try the playground</kj-link>.
+    </p>
+
+    <div class="row">
+      <kj-link kjHref="https://github.com/kouji-dev/kouji-ui" kjTarget="_blank">GitHub</kj-link>
+      <kj-link kjHref="/billing" [kjDisabled]="true">Manage billing</kj-link>
+    </div>
+
+    <div class="row">
+      <kj-link kjHref="/a" kjSize="sm">Small</kj-link>
+      <kj-link kjHref="/b" kjSize="md">Medium</kj-link>
+      <kj-link kjHref="/c" kjSize="lg">Large</kj-link>
+    </div>
+  `,
+})
+export class KjLinkUsageExample {}

package/src/list/_examples/index.ts

@@ -0,0 +1,7 @@
+// AUTO-GENERATED by scripts/migrate-examples.mjs
+// One barrel per component folder — used by the docs app as a lazy chunk.
+export { KjListDividedExample } from './list.divided.example';
+export { KjListExample } from './list.example';
+export { KjListInteractiveExample } from './list.interactive.example';
+export { KjListNavExample } from './list.nav.example';
+export { KjListWithIconsExample } from './list.with-icons.example';

package/src/list/_examples/list.divided.example.ts

@@ -0,0 +1,32 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjListComponent, KjListItemComponent } from '../list';
+
+/**
+ * Divided list. Toggling `divided` paints between-row separators via the
+ * theme CSS rule on `[data-divided]` — no per-row class plumbing required.
+ * Pairs naturally with `hoverable` to hint at interactivity on rows that
+ * are actually clickable.
+ */
+@Component({
+  selector: 'kj-list-divided-example',
+  standalone: true,
+  imports: [KjListComponent, KjListItemComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-list ariaLabel="Recent files" [divided]="true">
+      <kj-list-item>Q4 financial report.pdf</kj-list-item>
+      <kj-list-item>Brand guidelines.fig</kj-list-item>
+      <kj-list-item>Meeting notes — Oct 21.md</kj-list-item>
+      <kj-list-item>Customer interviews.csv</kj-list-item>
+      <kj-list-item>Design system roadmap.key</kj-list-item>
+    </kj-list>
+  `,
+})
+export class KjListDividedExample {}

package/src/list/_examples/list.example.ts

@@ -0,0 +1,31 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjListComponent, KjListItemComponent } from '../list';
+
+/**
+ * Default usage example for KjListComponent. A settings list with five rows
+ * inside a labelled list — anchors the default chrome (no dividers, no hover,
+ * vertical orientation).
+ */
+@Component({
+  selector: 'kj-list-example',
+  standalone: true,
+  imports: [KjListComponent, KjListItemComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-list ariaLabel="Account settings">
+      <kj-list-item>Profile</kj-list-item>
+      <kj-list-item>Notifications</kj-list-item>
+      <kj-list-item>Billing</kj-list-item>
+      <kj-list-item>Security</kj-list-item>
+      <kj-list-item>Connected apps</kj-list-item>
+    </kj-list>
+  `,
+})
+export class KjListExample {}

package/src/list/_examples/list.interactive.example.ts

@@ -0,0 +1,51 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjListComponent, KjListItemComponent } from '../list';
+
+/**
+ * Interactive list — `hoverable` paints a hover surface and the projected
+ * `<button>` per row owns the focus stop, the keyboard contract, and the
+ * click handler. The list itself is just rendering: Tab moves between
+ * buttons, never landing on the row chrome.
+ */
+@Component({
+  selector: 'kj-list-interactive-example',
+  standalone: true,
+  imports: [KjListComponent, KjListItemComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+      .kj-list-interactive-status {
+        margin-top: var(--kj-space-md);
+        font: 0.875rem / 1.4 var(--kj-font-sans);
+        color: var(--kj-fg-default);
+        opacity: 0.75;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-list ariaLabel="Recent contacts" [divided]="true" [hoverable]="true">
+      @for (contact of contacts; track contact) {
+        <kj-list-item>
+          <button type="button" (click)="select(contact)">{{ contact }}</button>
+        </kj-list-item>
+      }
+    </kj-list>
+    <p class="kj-list-interactive-status">Selected: {{ selected() ?? '(none)' }}</p>
+  `,
+})
+export class KjListInteractiveExample {
+  protected readonly contacts = [
+    'Ada Lovelace',
+    'Grace Hopper',
+    'Alan Turing',
+    'Katherine Johnson',
+  ];
+  protected readonly selected = signal<string | null>(null);
+
+  protected select(name: string): void {
+    this.selected.set(name);
+  }
+}

package/src/list/_examples/list.nav.example.ts

@@ -0,0 +1,44 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjListComponent, KjListItemComponent } from '../list';
+
+/**
+ * Sidebar-style nav list. `as="nav"` opts the host into the `navigation`
+ * landmark; the wrapper enforces a labelled landmark via `ariaLabel`.
+ *
+ * Each row projects a plain `<a>` — the focus stop, keyboard contract, and
+ * routing all live on the link, never on the row chrome. The active row sets
+ * both `active="true"` (paints `data-active` chrome) and
+ * `aria-current="page"` (the AT-readable signal) — they are two layers of
+ * the same idea, deliberately split because the right `aria-current` token
+ * depends on the consumer's domain.
+ */
+@Component({
+  selector: 'kj-list-nav-example',
+  standalone: true,
+  imports: [KjListComponent, KjListItemComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-list as="nav" ariaLabel="Primary" [hoverable]="true">
+      <kj-list-item [active]="true">
+        <a href="#home" aria-current="page">Home</a>
+      </kj-list-item>
+      <kj-list-item>
+        <a href="#projects">Projects</a>
+      </kj-list-item>
+      <kj-list-item>
+        <a href="#team">Team</a>
+      </kj-list-item>
+      <kj-list-item>
+        <a href="#settings">Settings</a>
+      </kj-list-item>
+    </kj-list>
+  `,
+})
+export class KjListNavExample {}

package/src/list/_examples/list.with-icons.example.ts

@@ -0,0 +1,97 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjListComponent, KjListItemComponent } from '../list';
+
+/**
+ * Rows with leading icons (decorative, `aria-hidden="true"`) and trailing
+ * badges. Demonstrates that the row is a flex slot — consumers compose
+ * leading + body + trailing without needing named slots on the wrapper.
+ *
+ * The icon glyphs are pure unicode for example portability; production
+ * usage would project an icon component (e.g. lucide-angular) instead.
+ */
+@Component({
+  selector: 'kj-list-with-icons-example',
+  standalone: true,
+  imports: [KjListComponent, KjListItemComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+      .kj-list-icon {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        width: 1.5rem;
+        height: 1.5rem;
+        font-size: 1rem;
+        color: var(--kj-fg-default);
+        opacity: 0.7;
+      }
+      .kj-list-body {
+        flex: 1 1 auto;
+        display: flex;
+        flex-direction: column;
+        gap: 0.125rem;
+      }
+      .kj-list-title {
+        font: 0.875rem / 1.4 var(--kj-font-sans);
+        font-weight: 600;
+        color: var(--kj-fg-default);
+      }
+      .kj-list-subtitle {
+        font: 0.75rem / 1.3 var(--kj-font-sans);
+        color: var(--kj-fg-default);
+        opacity: 0.65;
+      }
+      .kj-list-badge {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        min-width: 1.5rem;
+        padding: 0 var(--kj-space-sm);
+        height: 1.5rem;
+        border-radius: 9999px;
+        background: var(--kj-bg-primary);
+        color: var(--kj-fg-on-primary);
+        font: 600 0.75rem / 1 var(--kj-font-sans);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-list ariaLabel="Inbox" [divided]="true" [hoverable]="true">
+      <kj-list-item>
+        <span class="kj-list-icon" aria-hidden="true">✉</span>
+        <span class="kj-list-body">
+          <span class="kj-list-title">Inbox</span>
+          <span class="kj-list-subtitle">Mail and direct messages</span>
+        </span>
+        <span class="kj-list-badge" aria-label="12 unread">12</span>
+      </kj-list-item>
+      <kj-list-item>
+        <span class="kj-list-icon" aria-hidden="true">★</span>
+        <span class="kj-list-body">
+          <span class="kj-list-title">Starred</span>
+          <span class="kj-list-subtitle">Saved for later</span>
+        </span>
+        <span class="kj-list-badge" aria-label="3 items">3</span>
+      </kj-list-item>
+      <kj-list-item>
+        <span class="kj-list-icon" aria-hidden="true">⏰</span>
+        <span class="kj-list-body">
+          <span class="kj-list-title">Snoozed</span>
+          <span class="kj-list-subtitle">Coming back later</span>
+        </span>
+      </kj-list-item>
+      <kj-list-item>
+        <span class="kj-list-icon" aria-hidden="true">🗑</span>
+        <span class="kj-list-body">
+          <span class="kj-list-title">Trash</span>
+          <span class="kj-list-subtitle">Auto-empties after 30 days</span>
+        </span>
+      </kj-list-item>
+    </kj-list>
+  `,
+})
+export class KjListWithIconsExample {}

package/src/list/index.ts

@@ -0,0 +1 @@
+export * from './list';