@kouji-ui/components 0.1.1

package/src/time-picker/time-picker.ts

@@ -0,0 +1,207 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  ViewEncapsulation,
+  booleanAttribute,
+  computed,
+  input,
+  model,
+  numberAttribute,
+} from '@angular/core';
+import {
+  KjHourCycle,
+  KjTimePicker,
+  KjTimePickerHours,
+  KjTimePickerMeridiem,
+  KjTimePickerMinutes,
+  KjTimePickerSeconds,
+  TimeParts,
+} from '@kouji-ui/core';
+
+/**
+ * Styled wrapper around the headless `[kjTimePicker]` directive family. Renders
+ * an internal HH : MM (: SS) row of segmented spinbuttons plus an AM/PM toggle
+ * when 12-hour mode is active.
+ *
+ * Accepts and emits either `Date` (default) or `'HH:mm[:ss]'` strings via
+ * `kjValueShape`. Per-segment ARIA wiring (`spinbutton`,
+ * `aria-valuemin / max / now / text`) is forwarded by the headless directives.
+ *
+ * @doc-example Default (24-hour)
+ *   The default playground — HH : MM spinbuttons, 24-hour cycle.
+ *   @doc-file time-picker.example.ts
+ * @doc-example Usage
+ *   A walkthrough of the most common time-picker usages — 24-hour, 12-hour
+ *   with AM/PM, and a formatted string output bound to `[(kjValue)]`.
+ *   @doc-file time-picker.usage.example.ts
+ * @doc-example 12-hour with AM/PM
+ *   `[kj12Hour]="true"` renders an AM/PM toggle next to the segments.
+ *   @doc-file time-picker.12-hour.example.ts
+ * @doc-example With seconds
+ *   `kjShowSeconds` adds an HH : MM : SS spinbutton triple.
+ *   @doc-file time-picker.with-seconds.example.ts
+ * @doc-example Range (start / end)
+ *   Two pickers wired with `[kjMin]` / `[kjMax]` so end can't precede start.
+ *   @doc-file time-picker.range.example.ts
+ * @doc-example Formatted string output
+ *   `kjValueShape="string"` emits `'HH:mm[:ss]'` strings instead of `Date`.
+ *   @doc-file time-picker.formatted.example.ts
+ *
+ * @doc-keyboard
+ *   ArrowUp|ArrowDown   — Steps the focused segment up/down by its step value
+ *   ArrowLeft|ArrowRight — Moves focus between segments (HH ↔ MM ↔ SS ↔ AM/PM)
+ *   Home                — Sets the focused segment to its minimum
+ *   End                 — Sets the focused segment to its maximum
+ *   PageUp|PageDown     — Coarse step (10×) on the focused segment
+ *   0-9                 — Type-ahead entry on the focused segment
+ *   Enter|Space         — Toggles AM/PM when focused on the meridiem button
+ *
+ * @doc-aria
+ *   role="group"        — applied to the host wrapping the segments
+ *   role="spinbutton"   — set on each HH / MM / SS input by the headless directive
+ *   aria-valuemin / max / now / text — wired per segment for AT announcement
+ *   aria-label          — `kjAriaLabel` on the wrapper; per-segment labels via
+ *                         `kjHoursLabel` / `kjMinutesLabel` / `kjSecondsLabel`
+ *   aria-disabled       — Reflected when `[kjDisabled]="true"`
+ *   data-disabled       — Mirrors disabled state for CSS hooks
+ *
+ * @doc-touch
+ *   Each segment ships with the `md` density floor (≥ 44×44 via padding).
+ *   The meridiem toggle inherits the same surface. `sm` keeps the floor —
+ *   only horizontal padding shrinks.
+ *
+ * @doc-a11y
+ *   Each segment is a real ARIA `spinbutton` so AT reads the current value,
+ *   range, and step. Min/max gating is enforced at the directive layer — the
+ *   picker never reports an out-of-range value through `(kjValueChange)`.
+ *
+ * @doc-related date-picker,number-input,form
+ *
+ * @doc-css-var
+ *   --kj-time-picker-bg              — Background fill of the segment row.
+ *   --kj-time-picker-fg              — Foreground (text) color of the segments.
+ *   --kj-time-picker-border-color    — Border color of the segment row.
+ *   --kj-time-picker-border-width    — Border thickness. Inherits --kj-border.
+ *   --kj-time-picker-radius          — Corner radius. Inherits --kj-radius-field.
+ *   --kj-time-picker-padding-x       — Horizontal padding of the segment row.
+ *   --kj-time-picker-font            — Font family. Defaults to --kj-font-sans.
+ *   --kj-time-picker-font-size       — Font size. Sizes (sm/md/lg) override.
+ *   --kj-time-picker-segment-width   — Fixed width of each HH/MM/SS spinbutton.
+ *   --kj-time-picker-height          — Row height. Sizes override.
+ *   --kj-time-picker-meridiem-bg     — Background of the AM/PM toggle button.
+ *   --kj-time-picker-meridiem-fg     — Foreground of the AM/PM toggle button.
+ *
+ * @doc-category Library/Data input
+ * @doc
+ * @doc-name time-picker
+ * @doc-description Themed time entry with HH MM SS spinbuttons, optional AM/PM, and `Date` or string output.
+ * @doc-is-main
+ */
+@Component({
+  selector: 'kj-time-picker',
+  standalone: true,
+  imports: [
+    KjTimePicker,
+    KjTimePickerHours,
+    KjTimePickerMinutes,
+    KjTimePickerSeconds,
+    KjTimePickerMeridiem,
+  ],
+  template: `
+    <div
+      kjTimePicker
+      class="kj-time-picker"
+      [kjValue]="kjValue() ?? null!"
+      (kjValueChange)="kjValue.set($event)"
+      [kjValueShape]="kjValueShape()"
+      [kj12Hour]="kj12Hour()"
+      [kjHourCycle]="kjHourCycle()"
+      [kjShowSeconds]="kjShowSeconds()"
+      [kjStep]="kjStep()"
+      [kjHourStep]="kjHourStep()"
+      [kjMinuteStep]="kjMinuteStep()"
+      [kjSecondStep]="kjSecondStep()"
+      [kjMin]="kjMin() ?? null!"
+      [kjMax]="kjMax() ?? null!"
+      [kjReadonly]="kjReadonly()"
+      [kjDisabled]="kjDisabled()"
+      [kjInvalid]="kjInvalid()"
+      [kjLocale]="kjLocale()"
+      [kjReferenceDate]="kjReferenceDate() ?? null!"
+      [attr.data-disabled]="kjDisabled() ? '' : null"
+      [attr.aria-label]="kjAriaLabel()"
+    >
+      <input
+        kjTimePickerHours
+        class="kj-time-picker__segment kj-time-picker__hours"
+        [kjAriaLabel]="kjHoursLabel()"
+      />
+      <span class="kj-time-picker__separator" aria-hidden="true">:</span>
+      <input
+        kjTimePickerMinutes
+        class="kj-time-picker__segment kj-time-picker__minutes"
+        [kjAriaLabel]="kjMinutesLabel()"
+      />
+      @if (kjShowSeconds()) {
+        <span class="kj-time-picker__separator" aria-hidden="true">:</span>
+        <input
+          kjTimePickerSeconds
+          class="kj-time-picker__segment kj-time-picker__seconds"
+          [kjAriaLabel]="kjSecondsLabel()"
+        />
+      }
+      @if (showMeridiem()) {
+        <button
+          type="button"
+          kjTimePickerMeridiem
+          class="kj-time-picker__meridiem"
+          [attr.aria-label]="kjMeridiemLabel()"
+          [kjAriaLabel]="kjMeridiemLabel()"
+        ></button>
+      }
+    </div>
+  `,
+  styleUrl: './time-picker.css',
+  encapsulation: ViewEncapsulation.None,
+  host: { style: 'display: contents;' },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjTimePickerComponent {
+  /** Two-way bindable time value. `null` clears. */
+  readonly kjValue = model<Date | string | null>(null);
+
+  readonly kjValueShape = input<'date' | 'string'>('date');
+  readonly kj12Hour = input(false, { transform: booleanAttribute });
+  readonly kjHourCycle = input<KjHourCycle | 'auto'>('auto');
+  readonly kjShowSeconds = input(false, { transform: booleanAttribute });
+
+  readonly kjStep = input<number, unknown>(1, { transform: numberAttribute });
+  readonly kjHourStep = input<number, unknown>(1, { transform: numberAttribute });
+  readonly kjMinuteStep = input<number | undefined, unknown>(undefined, {
+    transform: (v: unknown) => (v === undefined || v === null || v === '' ? undefined : numberAttribute(v)),
+  });
+  readonly kjSecondStep = input<number, unknown>(1, { transform: numberAttribute });
+
+  readonly kjMin = input<Date | string | TimeParts | null>(null);
+  readonly kjMax = input<Date | string | TimeParts | null>(null);
+
+  readonly kjReadonly = input(false, { transform: booleanAttribute });
+  readonly kjDisabled = input(false, { transform: booleanAttribute });
+  readonly kjInvalid = input(false, { transform: booleanAttribute });
+
+  readonly kjLocale = input<string>('');
+  readonly kjReferenceDate = input<Date | undefined>(undefined);
+
+  readonly kjAriaLabel = input<string>('');
+  readonly kjHoursLabel = input<string>('Hours');
+  readonly kjMinutesLabel = input<string>('Minutes');
+  readonly kjSecondsLabel = input<string>('Seconds');
+  readonly kjMeridiemLabel = input<string>('Toggle AM/PM');
+
+  /** Whether the meridiem toggle should be rendered. */
+  protected readonly showMeridiem = computed(() => {
+    if (this.kj12Hour()) return true;
+    const cycle = this.kjHourCycle();
+    return cycle === 'h11' || cycle === 'h12';
+  });
+}

package/src/toast/_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 { KjToastDefaultExample } from './toast.default.example';
+export { KjToastDismissibleExample } from './toast.dismissible.example';
+export { KjToastUsageExample } from './toast.usage.example';
+export { KjToastVariantsExample } from './toast.variants.example';
+export { KjToastWithActionExample } from './toast.with-action.example';

package/src/toast/_examples/toast.default.example.ts

@@ -0,0 +1,37 @@
+import { Component, TemplateRef, inject, viewChild, ChangeDetectionStrategy } from '@angular/core';
+import { KjToastService } from '@kouji-ui/core';
+import type { KjToastTemplateContext } from '@kouji-ui/core';
+import { KjButtonComponent } from '../../button/button';
+import { KjToastViewportComponent, KjToastComponent, KjToastCloseComponent } from '../toast';
+
+@Component({
+  selector: 'kj-toast-default-example',
+  standalone: true,
+  imports: [KjButtonComponent, KjToastViewportComponent, KjToastComponent, KjToastCloseComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+        min-height: 8rem;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-button (click)="show()">Show toast</kj-button>
+    <kj-toast-viewport />
+    <ng-template #tpl let-ctx>
+      <kj-toast [variant]="ctx.variant" [id]="ctx.id">
+        <span>{{ ctx.title }}</span>
+        <kj-toast-close [toastId]="ctx.id">×</kj-toast-close>
+      </kj-toast>
+    </ng-template>
+  `,
+})
+export class KjToastDefaultExample {
+  private readonly svc = inject(KjToastService);
+  readonly tpl = viewChild.required<TemplateRef<KjToastTemplateContext>>('tpl');
+  show(): void {
+    this.svc.show(this.tpl(), { title: 'Hello from kouji-ui!' });
+  }
+}

package/src/toast/_examples/toast.dismissible.example.ts

@@ -0,0 +1,38 @@
+import { Component, TemplateRef, inject, viewChild, ChangeDetectionStrategy } from '@angular/core';
+import { KjToastService } from '@kouji-ui/core';
+import type { KjToastTemplateContext } from '@kouji-ui/core';
+import { KjButtonComponent } from '../../button/button';
+import { KjToastViewportComponent, KjToastComponent, KjToastCloseComponent } from '../toast';
+
+@Component({
+  selector: 'kj-toast-dismissible-example',
+  standalone: true,
+  imports: [KjButtonComponent, KjToastViewportComponent, KjToastComponent, KjToastCloseComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+        min-height: 8rem;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-button (click)="show()">Show persistent toast</kj-button>
+    <kj-toast-viewport />
+    <ng-template #tpl let-ctx>
+      <kj-toast [variant]="ctx.variant" [id]="ctx.id">
+        <span>{{ ctx.title }}</span>
+        <kj-toast-close [toastId]="ctx.id">×</kj-toast-close>
+      </kj-toast>
+    </ng-template>
+  `,
+})
+export class KjToastDismissibleExample {
+  private readonly svc = inject(KjToastService);
+  readonly tpl = viewChild.required<TemplateRef<KjToastTemplateContext>>('tpl');
+
+  show(): void {
+    this.svc.show(this.tpl(), { title: 'I stay until dismissed.', duration: 0 });
+  }
+}

package/src/toast/_examples/toast.usage.example.ts

@@ -0,0 +1,57 @@
+import { Component, TemplateRef, inject, viewChild, ChangeDetectionStrategy } from '@angular/core';
+import { KjToastService } from '@kouji-ui/core';
+import type { KjToastTemplateContext } from '@kouji-ui/core';
+import { KjButtonComponent } from '../../button/button';
+import { KjToastViewportComponent, KjToastComponent, KjToastCloseComponent } from '../toast';
+
+/**
+ * A walkthrough of the most common toast usages — enqueue with a variant,
+ * project an action button inside the body, and dismiss via the close icon.
+ * Use this as the copy-paste starting point.
+ */
+@Component({
+  selector: 'kj-toast-usage-example',
+  standalone: true,
+  imports: [KjButtonComponent, KjToastViewportComponent, KjToastComponent, KjToastCloseComponent],
+  styles: [
+    `
+      :host {
+        display: flex;
+        flex-direction: column;
+        gap: var(--kj-space-md);
+        min-height: 10rem;
+      }
+      .row {
+        display: flex;
+        gap: var(--kj-space-sm);
+        flex-wrap: wrap;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <div class="row">
+      <kj-button (click)="show('default', 'Saved')">Default</kj-button>
+      <kj-button kjVariant="destructive" (click)="show('destructive', 'Save failed')"
+        >Error</kj-button
+      >
+      <kj-button (click)="show('success', 'Uploaded — view file')">With action</kj-button>
+    </div>
+    <kj-toast-viewport />
+
+    <ng-template #tpl let-ctx>
+      <kj-toast [variant]="ctx.variant" [id]="ctx.id">
+        <span>{{ ctx.title }}</span>
+        <kj-toast-close [toastId]="ctx.id">×</kj-toast-close>
+      </kj-toast>
+    </ng-template>
+  `,
+})
+export class KjToastUsageExample {
+  private readonly svc = inject(KjToastService);
+  readonly tpl = viewChild.required<TemplateRef<KjToastTemplateContext>>('tpl');
+
+  show(variant: 'default' | 'success' | 'destructive' | 'warning', title: string): void {
+    this.svc.show(this.tpl(), { title, variant });
+  }
+}

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

@@ -0,0 +1,43 @@
+import { Component, TemplateRef, inject, viewChild, ChangeDetectionStrategy } from '@angular/core';
+import { KjToastService } from '@kouji-ui/core';
+import type { KjToastVariant, KjToastTemplateContext } from '@kouji-ui/core';
+import { KjButtonComponent } from '../../button/button';
+import { KjToastViewportComponent, KjToastComponent, KjToastCloseComponent } from '../toast';
+
+@Component({
+  selector: 'kj-toast-variants-example',
+  standalone: true,
+  imports: [KjButtonComponent, KjToastViewportComponent, KjToastComponent, KjToastCloseComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+        min-height: 8rem;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <div style="display:flex; gap:0.5rem; flex-wrap:wrap;">
+      <kj-button (click)="show('default')">Default</kj-button>
+      <kj-button (click)="show('success')">Success</kj-button>
+      <kj-button (click)="show('warning')">Warning</kj-button>
+      <kj-button kjVariant="destructive" (click)="show('destructive')">Destructive</kj-button>
+    </div>
+    <kj-toast-viewport />
+    <ng-template #tpl let-ctx>
+      <kj-toast [variant]="ctx.variant" [id]="ctx.id">
+        <span>{{ ctx.title }}</span>
+        <kj-toast-close [toastId]="ctx.id">×</kj-toast-close>
+      </kj-toast>
+    </ng-template>
+  `,
+})
+export class KjToastVariantsExample {
+  private readonly svc = inject(KjToastService);
+  readonly tpl = viewChild.required<TemplateRef<KjToastTemplateContext>>('tpl');
+  show(variant: KjToastVariant): void {
+    const label = variant[0].toUpperCase() + variant.slice(1);
+    this.svc.show(this.tpl(), { variant, title: `${label} toast` });
+  }
+}

package/src/toast/_examples/toast.with-action.example.ts

@@ -0,0 +1,46 @@
+import { Component, TemplateRef, inject, viewChild, ChangeDetectionStrategy } from '@angular/core';
+import { KjToastService } from '@kouji-ui/core';
+import type { KjToastContext, KjToastTemplateContext } from '@kouji-ui/core';
+import { KjButtonComponent } from '../../button/button';
+import { KjToastViewportComponent, KjToastComponent, KjToastCloseComponent } from '../toast';
+
+@Component({
+  selector: 'kj-toast-with-action-example',
+  standalone: true,
+  imports: [KjButtonComponent, KjToastViewportComponent, KjToastComponent, KjToastCloseComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+        min-height: 8rem;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-button kjVariant="destructive" (click)="deleteItem()">Delete item</kj-button>
+    <kj-toast-viewport />
+    <ng-template #tpl let-ctx>
+      <kj-toast [variant]="ctx.variant" [id]="ctx.id">
+        <span>{{ ctx.title }}</span>
+        <kj-button kjSize="sm" kjVariant="ghost" style="margin-left:auto" (click)="undo(ctx)"
+          >Undo</kj-button
+        >
+        <kj-toast-close [toastId]="ctx.id">×</kj-toast-close>
+      </kj-toast>
+    </ng-template>
+  `,
+})
+export class KjToastWithActionExample {
+  private readonly svc = inject(KjToastService);
+  readonly tpl = viewChild.required<TemplateRef<KjToastTemplateContext>>('tpl');
+
+  deleteItem(): void {
+    this.svc.show(this.tpl(), { title: 'Item deleted', variant: 'default' });
+  }
+
+  undo(ctx: KjToastContext): void {
+    console.log('Undo triggered');
+    ctx.dismiss();
+  }
+}

package/src/toast/index.ts

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

package/src/toast/toast.css

@@ -0,0 +1,115 @@
+@layer kj.component {
+  /* ── Viewport ── */
+  .kj-toast-viewport {
+    position: fixed;
+    list-style: none;
+    padding: 0;
+    margin: 0;
+    z-index: var(--kj-toast-z-index, 1000);
+    /* Default position: bottom-right (mirrors KJ_TOAST_SONNER_STRATEGY) */
+    bottom: 1rem;
+    right: 1rem;
+    width: 22rem;
+    max-width: calc(100vw - 2rem);
+  }
+
+  /* Positional overrides driven by data-position-* from the directive */
+  .kj-toast-viewport[data-position-y="bottom"] { bottom: 1rem; top: auto; }
+  .kj-toast-viewport[data-position-y="top"]    { top: 1rem; bottom: auto; }
+  .kj-toast-viewport[data-position-x="end"]    { right: 1rem; left: auto; }
+  .kj-toast-viewport[data-position-x="start"]  { left: 1rem; right: auto; }
+  .kj-toast-viewport[data-position-x="center"] { left: 50%; right: auto; transform: translateX(-50%); }
+
+  /* Each <li> wraps a toast — absolutely positioned so siblings overlap. */
+  .kj-toast-viewport li {
+    position: absolute;
+    left: 0;
+    right: 0;
+    transition:
+      transform 0.4s cubic-bezier(0.21, 0.61, 0.35, 1),
+      opacity 0.3s ease;
+  }
+  .kj-toast-viewport[data-position-y="bottom"] li { bottom: 0; }
+  .kj-toast-viewport[data-position-y="top"]    li { top: 0; }
+
+  /* ── Collapsed (stacked) state ── */
+  .kj-toast-viewport[data-expanded="false"] .kj-toast:not([data-front="true"]) {
+    height: var(--kj-toast-front-height);
+    overflow: hidden;
+    transform:
+      translateY(calc((var(--kj-toast-index) - 1) * var(--kj-toast-gap, 14px) * -1))
+      scale(calc(1 - (var(--kj-toast-index) - 1) * 0.06));
+    opacity: calc(1 - (var(--kj-toast-index) - 1) * 0.25);
+  }
+  .kj-toast-viewport[data-position-y="top"][data-expanded="false"] .kj-toast:not([data-front="true"]) {
+    transform:
+      translateY(calc((var(--kj-toast-index) - 1) * var(--kj-toast-gap, 14px)))
+      scale(calc(1 - (var(--kj-toast-index) - 1) * 0.06));
+  }
+
+  /* ── Expanded state ── */
+  .kj-toast-viewport[data-expanded="true"] .kj-toast {
+    transform: translateY(
+      calc((var(--kj-toast-index) - 1) * (var(--kj-toast-height, 0px) + var(--kj-toast-gap, 14px)) * -1)
+    );
+  }
+  .kj-toast-viewport[data-position-y="top"][data-expanded="true"] .kj-toast {
+    transform: translateY(
+      calc((var(--kj-toast-index) - 1) * (var(--kj-toast-height, 0px) + var(--kj-toast-gap, 14px)))
+    );
+  }
+
+  /* ── Toast ── */
+  .kj-toast {
+    display: flex;
+    align-items: center;
+    gap: var(--kj-space-md, 0.75rem);
+    padding: var(--kj-space-md, 0.75rem) var(--kj-space-lg, 1rem);
+    min-width: 18rem;
+    font: 0.875rem / 1.4 var(--kj-font-sans, sans-serif);
+    border-radius: var(--kj-radius-box, 0.5rem);
+    box-shadow: 0 4px 16px rgb(0 0 0 / 0.18), 0 1px 0 rgb(255 255 255 / 0.04) inset;
+    border: var(--kj-border, 1px) solid var(--kj-border-default, #e2e8f0);
+    background: var(--kj-bg-elevated, #fff);
+    color: var(--kj-fg-default, #1a202c);
+    animation: kj-toast-enter 0.35s cubic-bezier(0.21, 0.61, 0.35, 1);
+  }
+
+  @keyframes kj-toast-enter {
+    from { opacity: 0; transform: translateY(100%) scale(0.95); }
+    to   { opacity: 1; transform: translateY(0) scale(1); }
+  }
+
+  .kj-toast[data-variant="success"] {
+    background: var(--kj-bg-success, #16a34a);
+    color: var(--kj-fg-on-success, #fff);
+    border-color: transparent;
+  }
+  .kj-toast[data-variant="warning"] {
+    background: var(--kj-bg-warning, #d97706);
+    color: var(--kj-fg-on-warning, #fff);
+    border-color: transparent;
+  }
+  .kj-toast[data-variant="destructive"] {
+    background: var(--kj-bg-danger, #dc2626);
+    color: var(--kj-fg-on-danger, #fff);
+    border-color: transparent;
+  }
+
+  /* ── Close button ── */
+  .kj-toast-close {
+    background: transparent;
+    border: 0;
+    color: inherit;
+    cursor: pointer;
+    padding: 4px 6px;
+    border-radius: 4px;
+    line-height: 1;
+    font-size: 1.1rem;
+    opacity: 0.7;
+    margin-left: auto;
+    flex-shrink: 0;
+  }
+  .kj-toast-close:hover { opacity: 1; background: rgb(0 0 0 / 0.08); }
+  .kj-toast-close:focus-visible { outline: 2px solid currentColor; outline-offset: 2px; }
+}

package/src/toast/toast.playground.ts

@@ -0,0 +1,61 @@
+import { ChangeDetectionStrategy, Component, inject, signal } from '@angular/core';
+import { KjToastService, type KjToastVariant } from '@kouji-ui/core';
+import { KjButtonComponent } from '../button/button';
+import { KjToastViewportComponent } from './toast';
+import type { PlaygroundFile } from '@kouji-ui/components/playground-types';
+
+/**
+ * Playground state — module-scope signals. Service-launched toast surfaces a
+ * trigger button; the variant + message are wired into the click handler.
+ */
+const variant = signal<KjToastVariant>('default');
+const message = signal('Saved your changes.');
+
+@Component({
+  selector: 'kj-toast-playground',
+  standalone: true,
+  imports: [KjButtonComponent, KjToastViewportComponent],
+  styles: [`:host { display: block; min-height: 6rem; }`],
+  template: `
+    <kj-button (click)="show()">Show toast</kj-button>
+    <kj-toast-viewport />
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjToastPlaygroundDemo {
+  private readonly toast = inject(KjToastService);
+  protected readonly variant = variant;
+  protected readonly message = message;
+
+  protected show(): void {
+    this.toast.show(this.message(), { variant: this.variant() });
+  }
+}
+
+export const PLAYGROUND: PlaygroundFile = {
+  component: KjToastPlaygroundDemo,
+  state: {
+    variant: variant as unknown as ReturnType<typeof signal>,
+    message: message as unknown as ReturnType<typeof signal>,
+  },
+  controls: [
+    {
+      kind: 'chips',
+      name: 'variant',
+      label: 'variant',
+      options: ['default', 'success', 'warning', 'destructive', 'info'],
+    },
+    { kind: 'text', name: 'message', label: 'message' },
+  ],
+  snippet: (values) => {
+    const s = values as { variant: string; message: string };
+    return `<kj-button (click)="show()">Show toast</kj-button>
+<kj-toast-viewport />
+
+// In your component:
+private readonly toast = inject(KjToastService);
+show(): void {
+  this.toast.show('${s.message}', { variant: '${s.variant}' });
+}`;
+  },
+};