@kouji-ui/components 0.1.1

package/src/calendar/calendar.ts

@@ -0,0 +1,171 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  ViewEncapsulation,
+  booleanAttribute,
+  input,
+  model,
+} from '@angular/core';
+import {
+  KjCalendar,
+  KjCalendarDay,
+  KjCalendarGrid,
+  KjCalendarHeader,
+  KjIconDirective,
+} from '@kouji-ui/core';
+
+/**
+ * Styled calendar wrapper. Composes the headless `KjCalendar` directives into
+ * a self-contained day-grid surface — header with prev/next arrows, weekday
+ * row, and 6×7 day cells.
+ *
+ * Native `Date` only — locale-aware via `Intl.DateTimeFormat`. No third-party
+ * date library.
+ *
+ * **Keyboard contract** (when focus is inside the grid, per APG):
+ * - `ArrowLeft` / `ArrowRight` — ±1 day
+ * - `ArrowUp` / `ArrowDown` — ±1 week
+ * - `Home` / `End` — first / last day of the focused week
+ * - `PageUp` / `PageDown` — ±1 month
+ * - `Shift+PageUp` / `Shift+PageDown` — ±1 year
+ * - `Enter` / `Space` — select the focused date
+ *
+ * @doc-example Default
+ *   The default playground — inline single-date selection bound to a signal.
+ *   @doc-file calendar.example.ts
+ * @doc-example Usage
+ *   The common shape — bound value, min/max bounds, and a disabled-dates
+ *   predicate. Use this as the copy-paste starting point.
+ *   @doc-file calendar.usage.example.ts
+ *
+ * @doc-keyboard
+ *   ArrowLeft|ArrowRight   — Moves focus ±1 day
+ *   ArrowUp|ArrowDown      — Moves focus ±1 week
+ *   Home|End               — First / last day of the focused week
+ *   PageUp|PageDown        — ±1 month
+ *   Shift+PageUp|Shift+PageDown — ±1 year
+ *   Enter|Space            — Selects the focused date
+ *   Tab                    — Moves focus out of the grid (single grid tab stop)
+ *
+ * @doc-aria
+ *   role                — `grid` on the day matrix; `gridcell` on each day button
+ *   aria-label          — `"Calendar"` on the host; override via `kjAriaLabel`
+ *   aria-labelledby     — Grid references the caption heading id
+ *   aria-selected       — Reflected on the currently-selected day cell
+ *   aria-disabled       — Reflected on out-of-range and disabled day cells
+ *   aria-current        — `"date"` on today's cell
+ *
+ * @doc-touch
+ *   Day cells render real `<button>` elements; ensure the surrounding
+ *   container provides ≥ 44×44 cells (WCAG 2.5.5). The default grid spacing
+ *   meets this on most screen sizes — verify when scaling down.
+ *
+ * @doc-a11y
+ *   Implements the WAI-ARIA APG Date Picker (grid) pattern. A single tab
+ *   stop into the grid, then arrow keys roam without leaving — Tab takes
+ *   focus to the next region. Native `Date` only, locale-aware via
+ *   `Intl.DateTimeFormat` — no third-party date library.
+ *
+ * @doc-related date-picker,time-picker,input
+ *
+ * @doc-category Library/Data input
+ * @doc
+ * @doc-name calendar
+ * @doc-description Themed inline calendar grid with min/max bounds, disabled dates, and full APG keyboard support.
+ * @doc-is-main
+ */
+@Component({
+  selector: 'kj-calendar',
+  standalone: true,
+  imports: [KjCalendar, KjCalendarHeader, KjCalendarGrid, KjCalendarDay, KjIconDirective],
+  template: `
+    <div
+      kjCalendar
+      class="kj-calendar"
+      [kjValue]="kjValue() ?? null!"
+      (kjValueChange)="kjValue.set($event)"
+      [kjMin]="kjMin() ?? null!"
+      [kjMax]="kjMax() ?? null!"
+      [kjDisabledDates]="kjDisabledDates() ?? null!"
+      [kjLocale]="kjLocale()"
+      [kjFirstDayOfWeek]="kjFirstDayOfWeek()"
+      [kjAriaLabel]="kjAriaLabel()"
+      [kjDisabled]="kjDisabled()"
+    >
+      <div class="kj-calendar__header" kjCalendarHeader #hdr="kjCalendarHeader">
+        <button
+          type="button"
+          class="kj-calendar__nav"
+          aria-label="Previous month"
+          [disabled]="hdr.prevDisabled()"
+          (click)="hdr.prev()"
+        >‹</button>
+        <h2 class="kj-calendar__caption" [id]="hdr.captionId()">{{ hdr.label() }}</h2>
+        <button
+          type="button"
+          class="kj-calendar__nav"
+          aria-label="Next month"
+          [disabled]="hdr.nextDisabled()"
+          (click)="hdr.next()"
+        ><i kjIcon="chevron-right"></i></button>
+      </div>
+      <table class="kj-calendar__grid" kjCalendarGrid #g="kjCalendarGrid">
+        <thead>
+          <tr>
+            @for (n of g.weekdayShort(); track $index) {
+              <th
+                scope="col"
+                class="kj-calendar__weekday"
+                [attr.abbr]="g.weekdayLong()[$index]"
+              >{{ n }}</th>
+            }
+          </tr>
+        </thead>
+        <tbody>
+          @for (week of g.weeks(); track $index) {
+            <tr>
+              @for (d of week; track d.getTime()) {
+                <td class="kj-calendar__cell">
+                  <button
+                    class="kj-calendar__day"
+                    kjCalendarDay
+                    [kjDate]="d"
+                  >{{ d.getDate() }}</button>
+                </td>
+              }
+            </tr>
+          }
+        </tbody>
+      </table>
+    </div>
+  `,
+  styleUrl: './calendar.css',
+  encapsulation: ViewEncapsulation.None,
+  host: { class: 'kj-calendar-host', style: 'display: contents;' },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjCalendarComponent {
+  /** Currently selected date. Two-way bindable — `[(kjValue)]`. `null` clears. */
+  readonly kjValue = model<Date | null>(null);
+
+  /** Earliest selectable date (inclusive). `null` = open. */
+  readonly kjMin = input<Date | null>(null);
+
+  /** Latest selectable date (inclusive). `null` = open. */
+  readonly kjMax = input<Date | null>(null);
+
+  /** Per-date predicate; `false` disables the cell. */
+  readonly kjDisabledDates = input<((d: Date) => boolean) | null>(null);
+
+  /** BCP-47 locale tag. Defaults to Angular's `LOCALE_ID`. */
+  readonly kjLocale = input<string>('');
+
+  /** First day of the week (0=Sun … 6=Sat). Locale-derived if not set. */
+  readonly kjFirstDayOfWeek = input<number>(0);
+
+  /** Accessible label override. Defaults to `"Calendar"`. */
+  readonly kjAriaLabel = input<string>('Calendar');
+
+  /** Disable the entire calendar. */
+  readonly kjDisabled = input<boolean, boolean | string>(false, { transform: booleanAttribute });
+}

package/src/calendar/calendar.usage.example.ts

@@ -0,0 +1,33 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { KjCalendarComponent } from './calendar';
+
+/**
+ * Common calendar shape — controlled date, min/max bounds, and a
+ * disabled-dates predicate (no weekends). Use this as the copy-paste
+ * starting point for new screens.
+ */
+@Component({
+  selector: 'kj-calendar-usage-example',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [KjCalendarComponent],
+  styles: [`
+    :host { display: flex; flex-direction: column; gap: var(--kj-space-md); align-items: flex-start; }
+    .selected { font-family: var(--kj-font-mono, monospace); font-size: 0.875rem; color: var(--kj-fg-muted); }
+  `],
+  template: `
+    <kj-calendar
+      [(kjValue)]="when"
+      [kjMin]="minDate"
+      [kjMax]="maxDate"
+      [kjDisabledDates]="skipWeekends"
+    />
+    <p class="selected">Selected: {{ when()?.toDateString() ?? '—' }}</p>
+  `,
+})
+export class KjCalendarUsageExample {
+  readonly when = signal<Date | null>(new Date());
+  readonly minDate = new Date(new Date().getFullYear(), 0, 1);
+  readonly maxDate = new Date(new Date().getFullYear(), 11, 31);
+  readonly skipWeekends = (d: Date): boolean => d.getDay() === 0 || d.getDay() === 6;
+}

package/src/calendar/index.ts

@@ -0,0 +1 @@
+export { KjCalendarComponent } from './calendar';

package/src/card/_examples/card.cover.example.ts

@@ -0,0 +1,53 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import {
+  KjCardComponent,
+  KjCardCoverComponent,
+  KjCardHeaderComponent,
+  KjCardTitleComponent,
+  KjCardSubtitleComponent,
+  KjCardContentComponent,
+  KjCardFooterComponent,
+} from '../card';
+import { KjButtonComponent } from '../../button/button';
+
+@Component({
+  selector: 'kj-card-cover-example',
+  standalone: true,
+  imports: [
+    KjCardComponent,
+    KjCardCoverComponent,
+    KjCardHeaderComponent,
+    KjCardTitleComponent,
+    KjCardSubtitleComponent,
+    KjCardContentComponent,
+    KjCardFooterComponent,
+    KjButtonComponent,
+  ],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-card style="max-width: 16rem;">
+      <kj-card-cover fit="contain">
+        <img
+          src="https://images.unsplash.com/photo-1508921912186-1d1a45ebb3c1?w=480&fit=crop"
+          alt="Mountains"
+        />
+      </kj-card-cover>
+      <kj-card-header>
+        <kj-card-title>Mountain trip</kj-card-title>
+        <kj-card-subtitle>March 2024</kj-card-subtitle>
+      </kj-card-header>
+      <kj-card-content>Three days in the alps with the team.</kj-card-content>
+      <kj-card-footer>
+        <kj-button>View</kj-button>
+      </kj-card-footer>
+    </kj-card>
+  `,
+})
+export class KjCardCoverExample {}

package/src/card/_examples/card.example.ts

@@ -0,0 +1,27 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjCardComponent } from '../card';
+
+/**
+ * Default usage example for KjCardComponent.
+ * Rendered live in the docs and as code in the example panel.
+ */
+@Component({
+  selector: 'kj-card-example',
+  standalone: true,
+  imports: [KjCardComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `<kj-card variant="default"
+    ><strong>Card title</strong>
+    <p style="margin: var(--kj-space-sm) 0 0; color: var(--kj-fg-muted);">
+      Body content goes here. Cards group related information.
+    </p></kj-card
+  >`,
+})
+export class KjCardExample {}

package/src/card/_examples/card.full.example.ts

@@ -0,0 +1,51 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import {
+  KjCardComponent,
+  KjCardHeaderComponent,
+  KjCardTitleComponent,
+  KjCardSubtitleComponent,
+  KjCardContentComponent,
+  KjCardFooterComponent,
+} from '../card';
+import { KjButtonComponent } from '../../button/button';
+
+@Component({
+  selector: 'kj-card-full-example',
+  standalone: true,
+  imports: [
+    KjCardComponent,
+    KjCardHeaderComponent,
+    KjCardTitleComponent,
+    KjCardSubtitleComponent,
+    KjCardContentComponent,
+    KjCardFooterComponent,
+    KjButtonComponent,
+  ],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-card style="max-width: 24rem;">
+      <kj-card-header>
+        <kj-card-title>Project Atlas</kj-card-title>
+        <kj-card-subtitle>Status: in progress</kj-card-subtitle>
+      </kj-card-header>
+      <kj-card-content>
+        <p>
+          Atlas is the planning tool used by the platform team. It supports drafts, comments, and
+          shared boards.
+        </p>
+      </kj-card-content>
+      <kj-card-footer>
+        <kj-button kjVariant="ghost">Dismiss</kj-button>
+        <kj-button>Open</kj-button>
+      </kj-card-footer>
+    </kj-card>
+  `,
+})
+export class KjCardFullExample {}

package/src/card/_examples/index.ts

@@ -0,0 +1,5 @@
+// AUTO-GENERATED by scripts/migrate-examples.mjs
+// One barrel per component folder — used by the docs app as a lazy chunk.
+export { KjCardCoverExample } from './card.cover.example';
+export { KjCardExample } from './card.example';
+export { KjCardFullExample } from './card.full.example';

package/src/card/card.css

@@ -0,0 +1,120 @@
+/* ─────────────────────────────────────────────────────────────
+   .kj-card — component-layer tokens + structural CSS
+   ──────────────────────────────────────────────────────────── */
+
+@layer kj.component {
+  .kj-card {
+    --kj-card-bg:           var(--kj-bg-surface);
+    --kj-card-fg:           var(--kj-fg-default);
+    --kj-card-border-color: transparent;
+    --kj-card-border-width: var(--kj-border);
+    --kj-card-radius:       var(--kj-radius-box);
+    --kj-card-padding-x:    var(--kj-space-xl);
+    --kj-card-padding-y:    var(--kj-space-xl);
+    --kj-card-shadow:       none;
+
+    display: block;
+    background: var(--kj-card-bg);
+    color: var(--kj-card-fg);
+    border: var(--kj-card-border-width) solid var(--kj-card-border-color);
+    border-radius: var(--kj-card-radius);
+    box-shadow: var(--kj-card-shadow);
+    overflow: hidden;
+    transition: var(--kj-transition);
+  }
+
+  /* When no sub-components are used, fall back to the padded wrapper for plain content. */
+  .kj-card:not(:has(.kj-card-header, .kj-card-content, .kj-card-footer, .kj-card-cover)) {
+    padding: var(--kj-card-padding-y) var(--kj-card-padding-x);
+  }
+
+  .kj-card[data-variant="outline"] {
+    --kj-card-bg: transparent;
+    --kj-card-border-color: var(--kj-border-default);
+  }
+
+  .kj-card[data-variant="subtle"] {
+    --kj-card-bg: var(--kj-bg-field);
+  }
+
+  /* Lift modifier — borrows the theme's button-shadow value so cards in
+     brutalist themes (kouji / bauhaus) get the same hard offset block as
+     primary buttons. Themes without an offset signature fall back to
+     `--kj-shadow-md` so the card still reads as elevated. */
+  .kj-card[data-shadow="lift"] {
+    --kj-card-shadow: var(--kj-button-shadow, var(--kj-shadow-md));
+    --kj-card-border-color: var(--kj-border-default);
+  }
+
+  /* Cover image. Fixed aspect ratio + cover-fit prevents tall hero images
+     from blowing the card. The `--kj-card-cover-height` knob lets a
+     consumer override the height; `--kj-card-cover-fit` swaps cover/contain. */
+  .kj-card-cover {
+    --kj-card-cover-height: 12rem;
+    --kj-card-cover-fit:    cover;
+
+    display: block;
+    height: var(--kj-card-cover-height);
+    background: var(--kj-bg-field);
+    overflow: hidden;
+  }
+  .kj-card-cover img,
+  .kj-card-cover video {
+    width: 100%;
+    height: 100%;
+    display: block;
+    object-fit: var(--kj-card-cover-fit);
+    object-position: center;
+  }
+  /* Per-instance override via [data-fit]. */
+  .kj-card-cover[data-fit="contain"] { --kj-card-cover-fit: contain; }
+  .kj-card-cover[data-fit="cover"]   { --kj-card-cover-fit: cover; }
+  .kj-card-cover[data-size="sm"] { --kj-card-cover-height: 8rem; }
+  .kj-card-cover[data-size="lg"] { --kj-card-cover-height: 16rem; }
+
+  /* Header */
+  .kj-card-header {
+    display: flex;
+    flex-direction: column;
+    gap: var(--kj-space-xs, 0.25rem);
+    padding: var(--kj-card-padding-y) var(--kj-card-padding-x);
+  }
+
+  /* Title */
+  .kj-card-title {
+    font: 600 1rem / 1.3 var(--kj-font-sans);
+    margin: 0;
+    color: var(--kj-fg-default);
+  }
+
+  /* Subtitle */
+  .kj-card-subtitle {
+    font: 0.875rem / 1.4 var(--kj-font-sans);
+    color: var(--kj-fg-default);
+    opacity: 0.6;
+    margin: 0;
+  }
+
+  /* Content */
+  .kj-card-content {
+    display: block;
+    color: var(--kj-fg-default);
+    font: 0.9375rem / 1.5 var(--kj-font-sans);
+  }
+  .kj-card-content[data-padded] {
+    padding: var(--kj-card-padding-y) var(--kj-card-padding-x);
+  }
+
+  /* Footer */
+  .kj-card-footer {
+    display: flex;
+    align-items: center;
+    gap: var(--kj-space-sm);
+    padding: var(--kj-card-padding-y) var(--kj-card-padding-x);
+    border-top: var(--kj-border) solid var(--kj-border-default);
+  }
+  .kj-card-footer[data-align="start"]   { justify-content: flex-start; }
+  .kj-card-footer[data-align="center"]  { justify-content: center; }
+  .kj-card-footer[data-align="end"]     { justify-content: flex-end; }
+  .kj-card-footer[data-align="between"] { justify-content: space-between; }
+}

package/src/card/card.playground.ts

@@ -0,0 +1,116 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import {
+  KjCardComponent,
+  KjCardContentComponent,
+  KjCardFooterComponent,
+  KjCardHeaderComponent,
+  KjCardSubtitleComponent,
+  KjCardTitleComponent,
+} from './card';
+import { KjButtonComponent } from '../button/button';
+import type { PlaygroundFile } from '@kouji-ui/components/playground-types';
+
+/**
+ * Playground state — module-scope signals. Tunes variant, footer alignment,
+ * and toggles header / footer slots so the full card composition can be
+ * exercised without rewriting markup.
+ */
+const variant = signal<'default' | 'outline' | 'subtle'>('default');
+const footerAlign = signal<'start' | 'center' | 'end' | 'between'>('end');
+const showHeader = signal(true);
+const showFooter = signal(true);
+const title = signal('Card title');
+const body = signal('Body content goes here. Cards group related information.');
+
+@Component({
+  selector: 'kj-card-playground',
+  standalone: true,
+  imports: [
+    KjCardComponent,
+    KjCardHeaderComponent,
+    KjCardTitleComponent,
+    KjCardSubtitleComponent,
+    KjCardContentComponent,
+    KjCardFooterComponent,
+    KjButtonComponent,
+  ],
+  template: `
+    <kj-card [variant]="variant()">
+      @if (showHeader()) {
+        <kj-card-header>
+          <kj-card-title>{{ title() }}</kj-card-title>
+          <kj-card-subtitle>Themed surface preview</kj-card-subtitle>
+        </kj-card-header>
+      }
+      <kj-card-content>{{ body() }}</kj-card-content>
+      @if (showFooter()) {
+        <kj-card-footer [align]="footerAlign()">
+          <kj-button kjVariant="ghost" kjSize="sm">Cancel</kj-button>
+          <kj-button kjSize="sm">Save</kj-button>
+        </kj-card-footer>
+      }
+    </kj-card>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjCardPlaygroundDemo {
+  protected readonly variant = variant;
+  protected readonly footerAlign = footerAlign;
+  protected readonly showHeader = showHeader;
+  protected readonly showFooter = showFooter;
+  protected readonly title = title;
+  protected readonly body = body;
+}
+
+export const PLAYGROUND: PlaygroundFile = {
+  component: KjCardPlaygroundDemo,
+  state: {
+    variant: variant as unknown as ReturnType<typeof signal>,
+    footerAlign: footerAlign as unknown as ReturnType<typeof signal>,
+    showHeader: showHeader as unknown as ReturnType<typeof signal>,
+    showFooter: showFooter as unknown as ReturnType<typeof signal>,
+    title: title as unknown as ReturnType<typeof signal>,
+    body: body as unknown as ReturnType<typeof signal>,
+  },
+  controls: [
+    {
+      kind: 'chips',
+      name: 'variant',
+      label: 'variant',
+      options: ['default', 'outline', 'subtle'],
+    },
+    {
+      kind: 'chips',
+      name: 'footerAlign',
+      label: 'footer align',
+      options: ['start', 'center', 'end', 'between'],
+    },
+    { kind: 'text', name: 'title', label: 'title' },
+    { kind: 'text', name: 'body', label: 'body' },
+    { kind: 'toggle', name: 'showHeader', label: 'header' },
+    { kind: 'toggle', name: 'showFooter', label: 'footer' },
+  ],
+  snippet: (values) => {
+    const s = values as {
+      variant: string;
+      footerAlign: string;
+      showHeader: boolean;
+      showFooter: boolean;
+      title: string;
+      body: string;
+    };
+    const slots: string[] = [];
+    if (s.showHeader) {
+      slots.push(
+        `  <kj-card-header>\n    <kj-card-title>${s.title}</kj-card-title>\n    <kj-card-subtitle>Themed surface preview</kj-card-subtitle>\n  </kj-card-header>`,
+      );
+    }
+    slots.push(`  <kj-card-content>${s.body}</kj-card-content>`);
+    if (s.showFooter) {
+      slots.push(
+        `  <kj-card-footer align="${s.footerAlign}">\n    <kj-button kjVariant="ghost" kjSize="sm">Cancel</kj-button>\n    <kj-button kjSize="sm">Save</kj-button>\n  </kj-card-footer>`,
+      );
+    }
+    return `<kj-card variant="${s.variant}">\n${slots.join('\n')}\n</kj-card>`;
+  },
+};

package/src/card/card.spec.ts

@@ -0,0 +1,50 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { describe, expect, test, beforeEach } from 'vitest';
+import { KjCardComponent } from './card';
+
+@Component({
+  standalone: true,
+  imports: [KjCardComponent],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `<kj-card [variant]="variant">Content</kj-card>`,
+})
+class HostComponent {
+  variant: 'default' | 'outline' | 'subtle' = 'default';
+}
+
+describe('KjCardComponent', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({ imports: [HostComponent] });
+  });
+
+  test('host element carries the .kj-card class', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const card = fixture.nativeElement.querySelector('kj-card');
+    expect(card).not.toBeNull();
+    expect(card.classList.contains('kj-card')).toBe(true);
+  });
+
+  test('default variant has data-variant="default" attr', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const card = fixture.nativeElement.querySelector('kj-card');
+    expect(card.getAttribute('data-variant')).toBe('default');
+  });
+
+  test('forwards variant input to data-variant attr', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.variant = 'outline';
+    fixture.detectChanges();
+    const card = fixture.nativeElement.querySelector('kj-card');
+    expect(card.getAttribute('data-variant')).toBe('outline');
+  });
+
+  test('projects content into the host', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const card = fixture.nativeElement.querySelector('kj-card');
+    expect(card.textContent.trim()).toBe('Content');
+  });
+});