@kouji-ui/components 0.1.1

package/src/button-group/button-group.spec.ts

@@ -0,0 +1,119 @@
+import { Component, inject, ChangeDetectionStrategy } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { describe, expect, test, beforeEach } from 'vitest';
+import { KJ_BUTTON_GROUP } from '@kouji-ui/core';
+import { KjButtonGroupComponent } from './button-group';
+import { KjButtonComponent } from '../button/button';
+
+@Component({
+  standalone: true,
+  imports: [KjButtonGroupComponent, KjButtonComponent],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-button-group
+      [kjOrientation]="orientation"
+      [kjVariant]="variant"
+      [kjSize]="size"
+      [kjDisabled]="disabled"
+      [kjAriaLabel]="ariaLabel"
+    >
+      <kj-button>One</kj-button>
+      <kj-button>Two</kj-button>
+      <kj-button>Three</kj-button>
+    </kj-button-group>
+  `,
+})
+class HostComponent {
+  orientation: 'horizontal' | 'vertical' = 'horizontal';
+  variant: string | undefined = undefined;
+  size: string | undefined = undefined;
+  disabled = false;
+  ariaLabel: string | undefined = undefined;
+}
+
+describe('KjButtonGroupComponent', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({ imports: [HostComponent] });
+  });
+
+  test('renders host with .kj-button-group class and role="group"', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const host = fixture.nativeElement.querySelector('kj-button-group');
+    expect(host).not.toBeNull();
+    expect(host.classList.contains('kj-button-group')).toBe(true);
+    expect(host.getAttribute('role')).toBe('group');
+  });
+
+  test('reflects kjOrientation to data-orientation', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.orientation = 'vertical';
+    fixture.detectChanges();
+    const host = fixture.nativeElement.querySelector('kj-button-group');
+    expect(host.getAttribute('data-orientation')).toBe('vertical');
+  });
+
+  test('forwards kjAriaLabel to host', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.ariaLabel = 'Toolbar';
+    fixture.detectChanges();
+    const host = fixture.nativeElement.querySelector('kj-button-group');
+    expect(host.getAttribute('aria-label')).toBe('Toolbar');
+  });
+
+  test('writes data-disabled when kjDisabled is true', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.disabled = true;
+    fixture.detectChanges();
+    const host = fixture.nativeElement.querySelector('kj-button-group');
+    expect(host.getAttribute('data-disabled')).toBe('');
+  });
+
+  test('omits data-disabled when not disabled', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const host = fixture.nativeElement.querySelector('kj-button-group');
+    expect(host.hasAttribute('data-disabled')).toBe(false);
+  });
+
+  test('projects child <kj-button> elements', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const host = fixture.nativeElement.querySelector('kj-button-group');
+    expect(host.querySelectorAll('button.kj-button').length).toBe(3);
+  });
+
+  test('exposes KJ_BUTTON_GROUP context with forwarded variant/size', () => {
+    let captured: ReturnType<typeof inject<typeof KJ_BUTTON_GROUP>> | undefined;
+
+    @Component({
+      selector: 'kj-bg-probe',
+      standalone: true,
+      template: '',
+    })
+    class Probe {
+      constructor() {
+        captured = inject(KJ_BUTTON_GROUP);
+      }
+    }
+
+    @Component({
+      standalone: true,
+      imports: [KjButtonGroupComponent, Probe],
+      template: `
+        <kj-button-group kjVariant="ghost" kjSize="lg">
+          <kj-bg-probe />
+        </kj-button-group>
+      `,
+    })
+    class HostWithProbe {}
+
+    TestBed.configureTestingModule({ imports: [HostWithProbe] });
+    const fixture = TestBed.createComponent(HostWithProbe);
+    fixture.detectChanges();
+
+    expect(captured).toBeDefined();
+    expect(captured!.variant()).toBe('ghost');
+    expect(captured!.size()).toBe('lg');
+  });
+});

package/src/button-group/button-group.ts

@@ -0,0 +1,130 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  ViewEncapsulation,
+  booleanAttribute,
+  input,
+} from '@angular/core';
+import { KjButtonGroup, KjButtonGroupOrientation } from '@kouji-ui/core';
+
+/**
+ * Styled wrapper around the headless `KjButtonGroup` directive. Renders a
+ * visually-joined cluster of `<kj-button>` children: the outer corners stay
+ * rounded while inner edges between adjacent buttons collapse to produce the
+ * segmented "chunky" look, in either horizontal or vertical orientation.
+ *
+ * Group-level `kjVariant` / `kjSize` are surfaced through the
+ * `KJ_BUTTON_GROUP` context for child buttons that read it as a fallback;
+ * children that set their own `kjVariant` / `kjSize` always win. `kjDisabled`
+ * on the group OR-s with each child's own disabled state.
+ *
+ * @example
+ * ```html
+ * <kj-button-group>
+ *   <kj-button>Save</kj-button>
+ *   <kj-button>Cancel</kj-button>
+ *   <kj-button>Delete</kj-button>
+ * </kj-button-group>
+ * ```
+ * @doc-example Default
+ *   The default playground — three joined outline buttons in a row.
+ *   @doc-file button-group.example.ts
+ * @doc-example Usage
+ *   The common shapes — segmented toolbar, vertical stack, and an icon-only
+ *   cluster. Use this as the copy-paste starting point.
+ *   @doc-file button-group.usage.example.ts
+ * @doc-example Vertical
+ *   `kjOrientation="vertical"` stacks buttons and joins their top/bottom edges.
+ *   @doc-file button-group.vertical.example.ts
+ * @doc-example Variants
+ *   Set `kjVariant` on the group to cascade onto every child button.
+ *   @doc-file button-group.variants.example.ts
+ * @doc-example Toggle
+ *   Pair with `[kjPressed]` on each child to build a segmented control.
+ *   @doc-file button-group.toggle.example.ts
+ * @doc-example Icon only
+ *   Pure-icon children — give each an `kjAriaLabel` for AT users.
+ *   @doc-file button-group.icon-only.example.ts
+ *
+ * @doc-keyboard
+ *   Tab           — Moves focus through each button in DOM order
+ *   Enter|Space   — Activates the focused button (native click)
+ *
+ * @doc-aria
+ *   role               — `group` on the host (set by `KjButtonGroup` directive)
+ *   aria-label         — Override via `kjAriaLabel` for toolbars without surrounding context
+ *   aria-orientation   — Mirrors `kjOrientation` for AT
+ *   data-orientation   — Mirrors `kjOrientation` for theme/scope hooks
+ *
+ * @doc-touch
+ *   Children inherit `<kj-button>` sizing rules — `lg` and `icon` sizes clear
+ *   WCAG 2.5.5 ≥ 44×44 by default. For high-density toolbars on touch, raise
+ *   the children to `lg` or pad the host.
+ *
+ * @doc-a11y
+ *   Renders a `role="group"` so AT announces "group, 3 buttons" instead of
+ *   listing each independently. Set `kjAriaLabel` for toolbars that lack a
+ *   surrounding labelled landmark. `kjDisabled` on the group OR-s with each
+ *   child's own disabled state.
+ *
+ * @doc-related button,toggle,tabs
+ *
+ * @doc-css-var
+ *   --kj-button-group-gap  — Gap between adjacent buttons. Defaults to 0 (segmented look); raise for a spaced cluster.
+ *
+ * @doc-category Library/Actions
+ * @doc
+ * @doc-name button-group
+ * @doc-description Themed segmented button cluster that joins adjacent buttons into a single toolbar.
+ * @doc-is-main
+ */
+@Component({
+  selector: 'kj-button-group',
+  standalone: true,
+  hostDirectives: [
+    {
+      directive: KjButtonGroup,
+      inputs: ['kjOrientation', 'kjVariant', 'kjSize', 'kjDisabled'],
+    },
+  ],
+  template: `<ng-content />`,
+  styleUrl: './button-group.css',
+  encapsulation: ViewEncapsulation.None,
+  host: {
+    class: 'kj-button-group',
+    '[attr.aria-label]': 'kjAriaLabel()',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjButtonGroupComponent {
+  /**
+   * Layout axis. Forwarded to the composed `KjButtonGroup` directive, which
+   * mirrors it to `aria-orientation` / `data-orientation` on the host.
+   * @default 'horizontal'
+   */
+  readonly kjOrientation = input<KjButtonGroupOrientation>('horizontal');
+
+  /**
+   * Default variant forwarded to children via `KJ_BUTTON_GROUP`. Children
+   * that set their own `kjVariant` override this fallback.
+   */
+  readonly kjVariant = input<string | undefined>(undefined);
+
+  /**
+   * Default size forwarded to children via `KJ_BUTTON_GROUP`. Per-child
+   * overrides win.
+   */
+  readonly kjSize = input<string | undefined>(undefined);
+
+  /**
+   * Group-level disabled flag. OR-ed with each child button's own
+   * `kjDisabled`.
+   */
+  readonly kjDisabled = input(false, { transform: booleanAttribute });
+
+  /**
+   * Optional `aria-label` for the host. Useful when the group sits in a
+   * toolbar or otherwise needs an accessible name.
+   */
+  readonly kjAriaLabel = input<string | undefined>(undefined);
+}

package/src/button-group/button-group.usage.example.ts

@@ -0,0 +1,35 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { KjButtonComponent } from '../button/button';
+import { KjButtonGroupComponent } from './button-group';
+
+/**
+ * Common button-group shapes — segmented toolbar, vertical stack, and a
+ * variant-cascaded cluster. Use this as the copy-paste starting point.
+ */
+@Component({
+  selector: 'kj-button-group-usage-example',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [KjButtonGroupComponent, KjButtonComponent],
+  styles: [`:host { display: flex; flex-direction: column; gap: var(--kj-space-md); }`],
+  template: `
+    <kj-button-group kjAriaLabel="Document actions">
+      <kj-button kjVariant="outline">Save</kj-button>
+      <kj-button kjVariant="outline">Cancel</kj-button>
+      <kj-button kjVariant="outline">Delete</kj-button>
+    </kj-button-group>
+
+    <kj-button-group kjOrientation="vertical" kjAriaLabel="Sort">
+      <kj-button kjVariant="ghost">Newest</kj-button>
+      <kj-button kjVariant="ghost">Oldest</kj-button>
+      <kj-button kjVariant="ghost">A–Z</kj-button>
+    </kj-button-group>
+
+    <kj-button-group kjVariant="default" kjSize="sm" kjAriaLabel="Pagination">
+      <kj-button>1</kj-button>
+      <kj-button>2</kj-button>
+      <kj-button>3</kj-button>
+    </kj-button-group>
+  `,
+})
+export class KjButtonGroupUsageExample {}

package/src/button-group/index.ts

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

package/src/calendar/_examples/calendar.example.ts

@@ -0,0 +1,33 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjCalendarComponent } from '../calendar';
+
+/**
+ * Default usage example for KjCalendarComponent — an inline single-date
+ * selection grid. Two-way binding keeps a local signal in sync.
+ */
+@Component({
+  selector: 'kj-calendar-example',
+  standalone: true,
+  imports: [KjCalendarComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+        padding: var(--kj-space-2xl, 2rem);
+        background: var(--kj-bg-surface, #f3f3f3);
+      }
+      .selected {
+        margin-top: var(--kj-space-md, 0.75rem);
+        font-family: monospace;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-calendar [(kjValue)]="when" />
+    <p class="selected">Selected: {{ when().toDateString() }}</p>
+  `,
+})
+export class KjCalendarExample {
+  when = signal<Date>(new Date());
+}

package/src/calendar/_examples/index.ts

@@ -0,0 +1,3 @@
+// AUTO-GENERATED by scripts/migrate-examples.mjs
+// One barrel per component folder — used by the docs app as a lazy chunk.
+export { KjCalendarExample } from './calendar.example';

package/src/calendar/calendar.css

@@ -0,0 +1,129 @@
+.kj-calendar {
+  display: inline-block;
+  padding: var(--kj-space-sm);
+  /* No chrome of its own — when projected into `.kj-date-picker__panel`
+     (which already paints `bg-elevated` + border + radius + shadow), a
+     duplicate border reads as a hairline ring inside the panel. A
+     stand-alone calendar inherits its parent container's surface. */
+  background: transparent;
+  font-family: inherit;
+  font-size: 0.8125rem;
+  color: var(--kj-fg-default);
+}
+
+.kj-calendar__header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--kj-space-xs, 0.25rem);
+  margin-bottom: var(--kj-space-xs, 0.25rem);
+}
+
+.kj-calendar__caption {
+  margin: 0;
+  font-size: 0.8125rem;
+  font-weight: 600;
+  flex: 1;
+  text-align: center;
+}
+
+.kj-calendar__nav {
+  appearance: none;
+  background: transparent;
+  border: var(--kj-border) solid transparent;
+  width: 1.75rem;
+  height: 1.75rem;
+  border-radius: var(--kj-radius-field);
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 0.875rem;
+  color: inherit;
+}
+
+.kj-calendar__nav:hover:not([disabled]) {
+  /* `bg-field` (not `bg-surface`) — guarantees the hover is visible on
+     `bg-elevated` panels where surface and elevated collapse to the same
+     value (light / corporate themes). */
+  background: var(--kj-bg-field);
+}
+
+.kj-calendar__nav[disabled] {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
+
+.kj-calendar__grid {
+  border-collapse: collapse;
+  /* Fixed layout so every column gets the same explicit `2rem` width set
+     on `.kj-calendar__weekday` / `.kj-calendar__cell` regardless of cell
+     content. */
+  width: auto;
+  table-layout: fixed;
+}
+
+/* th/td share the same width contributor (the inner button or label) so
+   weekday headers align perfectly above day cells. `min-width: 2rem` on
+   both keeps the seven columns equal even when a weekday abbreviation is
+   narrower than a 2-digit day. */
+.kj-calendar__weekday {
+  width: 2rem;
+  padding: 0;
+  font-size: 0.6875rem;
+  font-weight: 500;
+  color: var(--kj-fg-muted);
+  text-align: center;
+}
+
+.kj-calendar__cell {
+  width: 2rem;
+  padding: 1px;
+}
+
+.kj-calendar__day {
+  appearance: none;
+  background: transparent;
+  border: var(--kj-border) solid transparent;
+  border-radius: var(--kj-radius-selector);
+  width: 100%;          /* Fill the cell so the button hits-area aligns
+                           with the header column above. */
+  height: 2rem;
+  min-height: 1.75rem;  /* WCAG 2.5.5 AA: ≥ 24×24px */
+  cursor: pointer;
+  font: inherit;
+  font-size: 0.8125rem;
+  color: inherit;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.kj-calendar__day:hover:not([disabled]) {
+  background: var(--kj-bg-field);
+}
+
+.kj-calendar__day:focus-visible {
+  outline: 2px solid var(--kj-border-focus);
+  outline-offset: 2px;
+}
+
+.kj-calendar__day[data-today] {
+  border-color: var(--kj-border-focus);
+  font-weight: 600;
+}
+
+.kj-calendar__day[data-selected] {
+  background: var(--kj-bg-primary);
+  color: var(--kj-fg-on-primary);
+}
+
+.kj-calendar__day[data-outside-month] {
+  opacity: 0.35;
+}
+
+.kj-calendar__day[data-disabled],
+.kj-calendar__day[disabled] {
+  opacity: 0.35;
+  cursor: not-allowed;
+}

package/src/calendar/calendar.playground.ts

@@ -0,0 +1,84 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { KjCalendarComponent } from './calendar';
+import type { PlaygroundFile } from '@kouji-ui/components/playground-types';
+
+/**
+ * Playground state — module-scope signals. Tunes the locale, first day of
+ * week, disabled state, and a "weekends disabled" predicate so the grid
+ * geometry and accessibility paths can be probed.
+ */
+const locale = signal<'en-US' | 'fr-FR' | 'ja-JP' | 'de-DE'>('en-US');
+const firstDayOfWeek = signal<0 | 1 | 6>(0);
+const disableWeekends = signal(false);
+const disabled = signal(false);
+const selected = signal<Date | null>(new Date());
+
+@Component({
+  selector: 'kj-calendar-playground',
+  standalone: true,
+  imports: [KjCalendarComponent],
+  template: `
+    <kj-calendar
+      [(kjValue)]="selected"
+      [kjLocale]="locale()"
+      [kjFirstDayOfWeek]="firstDayOfWeek()"
+      [kjDisabledDates]="disableWeekends() ? weekendPredicate : null"
+      [kjDisabled]="disabled()"
+    />
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjCalendarPlaygroundDemo {
+  protected readonly locale = locale;
+  protected readonly firstDayOfWeek = firstDayOfWeek;
+  protected readonly disableWeekends = disableWeekends;
+  protected readonly disabled = disabled;
+  protected readonly selected = selected;
+
+  protected readonly weekendPredicate = (d: Date): boolean => {
+    const day = d.getDay();
+    return day === 0 || day === 6;
+  };
+}
+
+export const PLAYGROUND: PlaygroundFile = {
+  component: KjCalendarPlaygroundDemo,
+  state: {
+    locale: locale as unknown as ReturnType<typeof signal>,
+    firstDayOfWeek: firstDayOfWeek as unknown as ReturnType<typeof signal>,
+    disableWeekends: disableWeekends as unknown as ReturnType<typeof signal>,
+    disabled: disabled as unknown as ReturnType<typeof signal>,
+  },
+  controls: [
+    {
+      kind: 'chips',
+      name: 'locale',
+      label: 'locale',
+      options: ['en-US', 'fr-FR', 'ja-JP', 'de-DE'],
+    },
+    {
+      kind: 'chips',
+      name: 'firstDayOfWeek',
+      label: 'first day',
+      options: [0, 1, 6],
+    },
+    { kind: 'toggle', name: 'disableWeekends', label: 'disable weekends' },
+    { kind: 'toggle', name: 'disabled', label: 'disabled' },
+  ],
+  snippet: (values) => {
+    const s = values as {
+      locale: string;
+      firstDayOfWeek: number;
+      disableWeekends: boolean;
+      disabled: boolean;
+    };
+    const attrs: string[] = [
+      `[(kjValue)]="selected"`,
+      `kjLocale="${s.locale}"`,
+      `[kjFirstDayOfWeek]="${s.firstDayOfWeek}"`,
+    ];
+    if (s.disableWeekends) attrs.push('[kjDisabledDates]="weekendPredicate"');
+    if (s.disabled) attrs.push('[kjDisabled]="true"');
+    return `<kj-calendar\n  ${attrs.join('\n  ')}\n/>`;
+  },
+};

package/src/calendar/calendar.spec.ts

@@ -0,0 +1,50 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { describe, expect, test, beforeEach } from 'vitest';
+import { KjCalendarComponent } from './calendar';
+
+@Component({
+  standalone: true,
+  imports: [KjCalendarComponent],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `<kj-calendar [(kjValue)]="value" />`,
+})
+class HostComponent {
+  value = signal<Date | null>(new Date(2025, 3, 15));
+}
+
+describe('KjCalendarComponent', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({ imports: [HostComponent] });
+  });
+
+  test('renders the calendar shell with the .kj-calendar class', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    expect(fixture.nativeElement.querySelector('.kj-calendar')).not.toBeNull();
+  });
+
+  test('renders the prev/next nav buttons with aria-label', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    expect(
+      fixture.nativeElement.querySelector('button[aria-label="Previous month"]'),
+    ).not.toBeNull();
+    expect(fixture.nativeElement.querySelector('button[aria-label="Next month"]')).not.toBeNull();
+  });
+
+  test('renders 42 day cells (6 × 7)', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const cells = fixture.nativeElement.querySelectorAll('button.kj-calendar__day');
+    expect(cells.length).toBe(42);
+  });
+
+  test('renders 7 weekday columns with abbr', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const headers = fixture.nativeElement.querySelectorAll('th.kj-calendar__weekday');
+    expect(headers.length).toBe(7);
+    expect((headers[0] as HTMLElement).getAttribute('abbr')?.length).toBeGreaterThan(0);
+  });
+});