@kouji-ui/components 0.1.1

package/src/alert/_examples/alert.variants.example.ts

@@ -0,0 +1,66 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import {
+  KjAlertComponent,
+  KjAlertDescriptionComponent,
+  KjAlertIconComponent,
+  KjAlertTitleComponent,
+} from '../alert';
+
+/**
+ * Side-by-side rendering of every default severity. Each variant flips the
+ * accent border + title colour via `--kj-alert-accent`. The `error` variant
+ * additionally resolves to `role="alert"` + `aria-live="assertive"`.
+ */
+@Component({
+  selector: 'kj-alert-variants-example',
+  standalone: true,
+  imports: [
+    KjAlertComponent,
+    KjAlertIconComponent,
+    KjAlertTitleComponent,
+    KjAlertDescriptionComponent,
+  ],
+  styles: [
+    `
+      :host {
+        display: flex;
+        flex-direction: column;
+        gap: var(--kj-space-md);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-alert kjVariant="info">
+      <kj-alert-icon>i</kj-alert-icon>
+      <kj-alert-title>Info</kj-alert-title>
+      <kj-alert-description>Polite info note — non-interrupting announcement.</kj-alert-description>
+    </kj-alert>
+
+    <kj-alert kjVariant="success">
+      <kj-alert-icon>✓</kj-alert-icon>
+      <kj-alert-title>Saved</kj-alert-title>
+      <kj-alert-description>Your changes have been saved successfully.</kj-alert-description>
+    </kj-alert>
+
+    <kj-alert kjVariant="warning">
+      <kj-alert-icon>!</kj-alert-icon>
+      <kj-alert-title>Heads up</kj-alert-title>
+      <kj-alert-description>Your storage is over 80% full.</kj-alert-description>
+    </kj-alert>
+
+    <kj-alert kjVariant="error">
+      <kj-alert-icon>✕</kj-alert-icon>
+      <kj-alert-title>Could not save</kj-alert-title>
+      <kj-alert-description
+        >Network request timed out. Resolves to assertive automatically.</kj-alert-description
+      >
+    </kj-alert>
+
+    <kj-alert kjVariant="neutral">
+      <kj-alert-title>Note</kj-alert-title>
+      <kj-alert-description>Neutral message with no severity colour.</kj-alert-description>
+    </kj-alert>
+  `,
+})
+export class KjAlertVariantsExample {}

package/src/alert/_examples/alert.with-actions.example.ts

@@ -0,0 +1,57 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjButtonComponent } from '../../button/button';
+import {
+  KjAlertActionsComponent,
+  KjAlertComponent,
+  KjAlertDescriptionComponent,
+  KjAlertDismissComponent,
+  KjAlertIconComponent,
+  KjAlertTitleComponent,
+} from '../alert';
+
+/**
+ * Error alert with action buttons (Retry / View details) inside
+ * `<kj-alert-actions>` — wraps the buttons in a `role="group"` so
+ * AT can skip past them as a unit.
+ */
+@Component({
+  selector: 'kj-alert-with-actions-example',
+  standalone: true,
+  imports: [
+    KjAlertComponent,
+    KjAlertIconComponent,
+    KjAlertTitleComponent,
+    KjAlertDescriptionComponent,
+    KjAlertActionsComponent,
+    KjAlertDismissComponent,
+    KjButtonComponent,
+  ],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-alert kjVariant="error">
+      <kj-alert-icon>!</kj-alert-icon>
+      <kj-alert-title>Could not save draft</kj-alert-title>
+      <kj-alert-description>Network request timed out after 30 seconds.</kj-alert-description>
+      <kj-alert-actions kjAlertActionsLabel="Recovery actions">
+        <kj-button kjVariant="default" kjSize="sm" (click)="onRetry()">Retry</kj-button>
+        <kj-button kjVariant="ghost" kjSize="sm" (click)="onDetails()">View details</kj-button>
+      </kj-alert-actions>
+      <kj-alert-dismiss />
+    </kj-alert>
+  `,
+})
+export class KjAlertWithActionsExample {
+  onRetry(): void {
+    /* example: trigger retry */
+  }
+  onDetails(): void {
+    /* example: open details */
+  }
+}

package/src/alert/_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 { KjAlertBannerExample } from './alert.banner.example';
+export { KjAlertDismissibleExample } from './alert.dismissible.example';
+export { KjAlertExample } from './alert.example';
+export { KjAlertVariantsExample } from './alert.variants.example';
+export { KjAlertWithActionsExample } from './alert.with-actions.example';

package/src/alert/alert.css

@@ -0,0 +1,133 @@
+@layer kj.component {
+  .kj-alert {
+    /* component knobs — themes/users override any of these */
+    --kj-alert-bg:           var(--kj-bg-body);
+    --kj-alert-fg:           var(--kj-fg-default);
+    --kj-alert-border-color: var(--kj-border-default);
+    --kj-alert-accent:       var(--kj-fg-info);
+    --kj-alert-radius:       var(--kj-radius-box, 0.5rem);
+    --kj-alert-padding-x:    var(--kj-space-lg, 1rem);
+    --kj-alert-padding-y:    var(--kj-space-md, 0.75rem);
+    --kj-alert-gap:          var(--kj-space-md, 0.75rem);
+    --kj-alert-font-size:    var(--kj-text-sm, 0.875rem);
+
+    display: flex;
+    align-items: flex-start;
+    gap: var(--kj-alert-gap);
+    background: var(--kj-alert-bg);
+    color: var(--kj-alert-fg);
+    border: var(--kj-border, 1px) solid var(--kj-alert-border-color);
+    border-left: 4px solid var(--kj-alert-accent);
+    border-radius: var(--kj-alert-radius);
+    padding: var(--kj-alert-padding-y) var(--kj-alert-padding-x);
+    font: var(--kj-alert-font-size) / 1.45 var(--kj-font-sans, sans-serif);
+    transition: opacity 200ms ease, transform 200ms ease;
+  }
+
+  .kj-alert[data-dismissed="true"] {
+    opacity: 0;
+    transform: translateY(-4px);
+  }
+
+  /* Severity variants — flip accent + (optionally) bg/fg. */
+  .kj-alert[data-variant="info"]    { --kj-alert-accent: var(--kj-fg-info, #2563eb); }
+  .kj-alert[data-variant="success"] { --kj-alert-accent: var(--kj-fg-success, #16a34a); }
+  .kj-alert[data-variant="warning"] { --kj-alert-accent: var(--kj-fg-warning, #d97706); }
+  .kj-alert[data-variant="error"]   { --kj-alert-accent: var(--kj-fg-danger, #dc2626); }
+  .kj-alert[data-variant="neutral"] { --kj-alert-accent: var(--kj-fg-muted, #6b7280); }
+
+  /* Static / banner mode — span full width, sticky-friendly chrome. */
+  .kj-alert[data-mode="static"] {
+    border-left-width: var(--kj-border, 1px);
+    border-top: 4px solid var(--kj-alert-accent);
+    border-radius: 0;
+  }
+
+  /* Sizes */
+  .kj-alert[data-size="sm"] {
+    --kj-alert-padding-x: var(--kj-space-md, 0.75rem);
+    --kj-alert-padding-y: var(--kj-space-sm, 0.5rem);
+    --kj-alert-font-size: 0.8125rem;
+  }
+  .kj-alert[data-size="lg"] {
+    --kj-alert-padding-x: var(--kj-space-xl, 1.25rem);
+    --kj-alert-padding-y: var(--kj-space-lg, 1rem);
+    --kj-alert-font-size: 1rem;
+  }
+
+  /* ── Body wrapper ─────────────────────────────────────────────── */
+  .kj-alert__body {
+    flex: 1 1 auto;
+    min-width: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 0.25rem;
+  }
+
+  /* ── Title / Description ──────────────────────────────────────── */
+  .kj-alert__title {
+    margin: 0;
+    font-weight: 600;
+    font-size: 1em;
+    color: var(--kj-alert-accent);
+    line-height: 1.3;
+  }
+  .kj-alert__description {
+    margin: 0;
+    color: var(--kj-alert-fg);
+    opacity: 0.9;
+  }
+
+  /* ── Icon ─────────────────────────────────────────────────────── */
+  .kj-alert__icon {
+    flex: 0 0 auto;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 1.25em;
+    height: 1.25em;
+    color: var(--kj-alert-accent);
+    margin-top: 0.1em;
+  }
+
+  /* ── Actions ──────────────────────────────────────────────────── */
+  .kj-alert__actions {
+    flex: 0 0 auto;
+    display: inline-flex;
+    align-items: center;
+    gap: var(--kj-space-sm, 0.5rem);
+    margin-left: auto;
+  }
+
+  /* ── Dismiss ──────────────────────────────────────────────────── */
+  .kj-alert__dismiss {
+    flex: 0 0 auto;
+    appearance: none;
+    background: transparent;
+    border: 0;
+    color: inherit;
+    cursor: pointer;
+    padding: 4px 8px;
+    border-radius: 4px;
+    line-height: 1;
+    font-size: 1.1rem;
+    opacity: 0.7;
+    margin-left: auto;
+    /* Touch-target floor (WCAG 2.5.5) */
+    min-width: 2.75rem;
+    min-height: 2.75rem;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+  }
+  .kj-alert__dismiss:hover { opacity: 1; background: rgb(0 0 0 / 0.06); }
+  .kj-alert__dismiss:focus-visible {
+    outline: 2px solid var(--kj-alert-accent);
+    outline-offset: 2px;
+  }
+
+  /* When actions and dismiss coexist, dismiss should not push actions away. */
+  .kj-alert__actions + .kj-alert__dismiss {
+    margin-left: 0;
+  }
+}

package/src/alert/alert.playground.ts

@@ -0,0 +1,111 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import {
+  KjAlertComponent,
+  KjAlertDescriptionComponent,
+  KjAlertDismissComponent,
+  KjAlertIconComponent,
+  KjAlertTitleComponent,
+} from './alert';
+import { KjButtonComponent } from '../button/button';
+import type { PlaygroundFile } from '@kouji-ui/components/playground-types';
+
+/**
+ * Playground state — module-scope signals. Knobs cover severity, size,
+ * banner mode, dismiss button, and the action row to exercise every slot
+ * on the alert composition.
+ */
+const variant = signal<'info' | 'success' | 'warning' | 'error'>('info');
+const size = signal<'sm' | 'md' | 'lg'>('md');
+const banner = signal(false);
+const dismissible = signal(false);
+const withActions = signal(false);
+const title = signal('Heads up');
+const description = signal('New theme tokens just landed — try the dark variant in your settings.');
+
+@Component({
+  selector: 'kj-alert-playground',
+  standalone: true,
+  imports: [
+    KjAlertComponent,
+    KjAlertIconComponent,
+    KjAlertTitleComponent,
+    KjAlertDescriptionComponent,
+    KjAlertDismissComponent,
+    KjButtonComponent,
+  ],
+  template: `
+    <kj-alert
+      [kjVariant]="variant()"
+      [kjSize]="size()"
+      [kjAlertStatic]="banner()"
+    >
+      <kj-alert-icon>i</kj-alert-icon>
+      <kj-alert-title>{{ title() }}</kj-alert-title>
+      <kj-alert-description>{{ description() }}</kj-alert-description>
+      @if (withActions()) {
+        <kj-button kjVariant="outline" kjSize="sm">Retry</kj-button>
+      }
+      @if (dismissible()) {
+        <kj-alert-dismiss />
+      }
+    </kj-alert>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjAlertPlaygroundDemo {
+  protected readonly variant = variant;
+  protected readonly size = size;
+  protected readonly banner = banner;
+  protected readonly dismissible = dismissible;
+  protected readonly withActions = withActions;
+  protected readonly title = title;
+  protected readonly description = description;
+}
+
+export const PLAYGROUND: PlaygroundFile = {
+  component: KjAlertPlaygroundDemo,
+  state: {
+    variant: variant as unknown as ReturnType<typeof signal>,
+    size: size as unknown as ReturnType<typeof signal>,
+    banner: banner as unknown as ReturnType<typeof signal>,
+    dismissible: dismissible as unknown as ReturnType<typeof signal>,
+    withActions: withActions as unknown as ReturnType<typeof signal>,
+    title: title as unknown as ReturnType<typeof signal>,
+    description: description as unknown as ReturnType<typeof signal>,
+  },
+  controls: [
+    {
+      kind: 'chips',
+      name: 'variant',
+      label: 'variant',
+      options: ['info', 'success', 'warning', 'error'],
+    },
+    { kind: 'chips', name: 'size', label: 'size', options: ['sm', 'md', 'lg'] },
+    { kind: 'text', name: 'title', label: 'title' },
+    { kind: 'text', name: 'description', label: 'description' },
+    { kind: 'toggle', name: 'banner', label: 'banner mode' },
+    { kind: 'toggle', name: 'dismissible', label: 'dismissible' },
+    { kind: 'toggle', name: 'withActions', label: 'with action' },
+  ],
+  snippet: (values) => {
+    const s = values as {
+      variant: string;
+      size: string;
+      banner: boolean;
+      dismissible: boolean;
+      withActions: boolean;
+      title: string;
+      description: string;
+    };
+    const attrs: string[] = [`kjVariant="${s.variant}"`, `kjSize="${s.size}"`];
+    if (s.banner) attrs.push('[kjAlertStatic]="true"');
+    const slots: string[] = [
+      `  <kj-alert-icon>i</kj-alert-icon>`,
+      `  <kj-alert-title>${s.title}</kj-alert-title>`,
+      `  <kj-alert-description>${s.description}</kj-alert-description>`,
+    ];
+    if (s.withActions) slots.push(`  <kj-button kjVariant="outline" kjSize="sm">Retry</kj-button>`);
+    if (s.dismissible) slots.push(`  <kj-alert-dismiss />`);
+    return `<kj-alert\n  ${attrs.join('\n  ')}\n>\n${slots.join('\n')}\n</kj-alert>`;
+  },
+};

package/src/alert/alert.spec.ts

@@ -0,0 +1,167 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { describe, expect, test, beforeEach } from 'vitest';
+import {
+  KjAlertActionsComponent,
+  KjAlertComponent,
+  KjAlertDescriptionComponent,
+  KjAlertDismissComponent,
+  KjAlertIconComponent,
+  KjAlertTitleComponent,
+} from './alert';
+
+@Component({
+  standalone: true,
+  imports: [
+    KjAlertComponent,
+    KjAlertIconComponent,
+    KjAlertTitleComponent,
+    KjAlertDescriptionComponent,
+    KjAlertActionsComponent,
+    KjAlertDismissComponent,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    @if (visible()) {
+      <kj-alert
+        [kjVariant]="variant"
+        [kjSize]="size"
+        [kjAlertStatic]="staticBanner"
+        [kjAlertMode]="mode"
+        (kjAlertDismissed)="onDismissed()"
+      >
+        <kj-alert-icon />
+        <kj-alert-title>Title</kj-alert-title>
+        <kj-alert-description>Body</kj-alert-description>
+        <kj-alert-actions>
+          <button>Retry</button>
+        </kj-alert-actions>
+        <kj-alert-dismiss />
+      </kj-alert>
+    }
+  `,
+})
+class HostComponent {
+  variant = 'info';
+  size = 'md';
+  staticBanner = false;
+  mode: 'assertive' | 'polite' | 'static' | 'off' | undefined = undefined;
+  visible = signal(true);
+  fired = 0;
+  onDismissed(): void {
+    this.fired++;
+    this.visible.set(false);
+  }
+}
+
+describe('KjAlertComponent', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({ imports: [HostComponent] });
+  });
+
+  test('renders kj-alert host with role="status" by default', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const root = fixture.nativeElement.querySelector('kj-alert')!;
+    expect(root.getAttribute('role')).toBe('status');
+    expect(root.getAttribute('aria-live')).toBe('polite');
+  });
+
+  test('forwards kjVariant via host directive (data-variant)', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.variant = 'warning';
+    fixture.detectChanges();
+    const root = fixture.nativeElement.querySelector('kj-alert')!;
+    expect(root.getAttribute('data-variant')).toBe('warning');
+  });
+
+  test('forwards kjSize via host directive (data-size)', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.size = 'lg';
+    fixture.detectChanges();
+    const root = fixture.nativeElement.querySelector('kj-alert')!;
+    expect(root.getAttribute('data-size')).toBe('lg');
+  });
+
+  test('error variant resolves to assertive (role="alert")', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.variant = 'error';
+    fixture.detectChanges();
+    const root = fixture.nativeElement.querySelector('kj-alert')!;
+    expect(root.getAttribute('role')).toBe('alert');
+    expect(root.getAttribute('aria-live')).toBe('assertive');
+  });
+
+  test('kjAlertStatic switches to role="region" with no aria-live', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.staticBanner = true;
+    fixture.detectChanges();
+    const root = fixture.nativeElement.querySelector('kj-alert')!;
+    expect(root.getAttribute('role')).toBe('region');
+    expect(root.getAttribute('aria-live')).toBeNull();
+  });
+
+  test('explicit kjAlertMode wins over the matrix', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.variant = 'error';
+    fixture.componentInstance.mode = 'polite';
+    fixture.detectChanges();
+    const root = fixture.nativeElement.querySelector('kj-alert')!;
+    expect(root.getAttribute('role')).toBe('status');
+    expect(root.getAttribute('aria-live')).toBe('polite');
+  });
+
+  test('renders icon, title, description, actions, dismiss slots', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    expect(fixture.nativeElement.querySelector('kj-alert-icon')).not.toBeNull();
+    expect(fixture.nativeElement.querySelector('kj-alert-title')).not.toBeNull();
+    expect(fixture.nativeElement.querySelector('kj-alert-description')).not.toBeNull();
+    expect(fixture.nativeElement.querySelector('kj-alert-actions')).not.toBeNull();
+    expect(fixture.nativeElement.querySelector('button.kj-alert__dismiss')).not.toBeNull();
+  });
+
+  test('alert root wires aria-labelledby to the title id', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const root = fixture.nativeElement.querySelector('kj-alert')!;
+    const title = fixture.nativeElement.querySelector('kj-alert-title')!;
+    expect(title.getAttribute('id')).toMatch(/-title$/);
+    expect(root.getAttribute('aria-labelledby')).toBe(title.getAttribute('id'));
+  });
+
+  test('actions container exposes role="group"', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const actions = fixture.nativeElement.querySelector('kj-alert-actions');
+    expect(actions.getAttribute('role')).toBe('group');
+    expect(actions.getAttribute('aria-label')).toBe('Alert actions');
+  });
+
+  test('clicking the dismiss button fires kjAlertDismissed and consumer unmounts', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const dismissBtn = fixture.nativeElement.querySelector('button.kj-alert__dismiss');
+    expect(dismissBtn).not.toBeNull();
+    dismissBtn.click();
+    fixture.detectChanges();
+    expect(fixture.componentInstance.fired).toBe(1);
+    expect(fixture.nativeElement.querySelector('kj-alert')).toBeNull();
+  });
+
+  test('dismiss button has aria-label="Dismiss"', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const dismissBtn = fixture.nativeElement.querySelector('button.kj-alert__dismiss');
+    expect(dismissBtn.getAttribute('aria-label')).toBe('Dismiss');
+  });
+
+  test('icon picks up aria-hidden="true" and data-variant from context', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.variant = 'success';
+    fixture.detectChanges();
+    const icon = fixture.nativeElement.querySelector('kj-alert-icon')!;
+    expect(icon.getAttribute('aria-hidden')).toBe('true');
+    expect(icon.getAttribute('data-variant')).toBe('success');
+  });
+});