@kouji-ui/components 0.1.1

package/src/confirm-popup/confirm-popup.ts

@@ -0,0 +1,279 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  ViewEncapsulation,
+  computed,
+  input,
+} from '@angular/core';
+import {
+  KjConfirmPopup,
+  KjConfirmPopupAction,
+  KjConfirmPopupCancel,
+  KjConfirmPopupContent,
+  KjConfirmPopupMessage,
+  KjConfirmPopupTrigger,
+  KjPopoverContent,
+  type KjOverlayTriggerLike,
+} from '@kouji-ui/core';
+
+/**
+ * Styled wrapper around the headless `KjConfirmPopup` state-container
+ * directive. Composes the core directive via `hostDirectives` and forwards
+ * every confirm-popup input under its `kj`-prefixed name. The host renders
+ * with `display: contents` so it never interferes with the consumer's layout.
+ *
+ * Pair with `<kj-confirm-popup-trigger>` for the activator (typically the
+ * destructive button) and `<kj-confirm-popup-content>` (placed inside an
+ * `<ng-template>`) for the floating panel.
+ *
+ * @doc
+ * @doc-name confirm-popup
+ * @doc-is-main
+ * @doc-example Default
+ *   The simplest anchored confirmation — a trigger button with a yes/no panel.
+ *   @doc-file confirm-popup.example.ts
+ * @doc-example Usage
+ *   A walkthrough of the most common confirm-popup usages — destructive and
+ *   benign variants with `(kjResult)` handling.
+ *   @doc-file confirm-popup.usage.example.ts
+ * @doc-example Destructive
+ *   `[kjDestructive]="true"` tints the action button and announces an `alertdialog`.
+ *   @doc-file confirm-popup.destructive.example.ts
+ * @doc-example With message
+ *   A descriptive paragraph projected as the panel's accessible description.
+ *   @doc-file confirm-popup.with-message.example.ts
+ * @doc-example Placement
+ *   Anchor side and offset overrides for tight layouts.
+ *   @doc-file confirm-popup.placement.example.ts
+ *
+ * @doc-keyboard
+ *   Enter|Space — Opens the popup from the trigger
+ *   Escape      — Closes the popup, resolves `false`, restores focus to the trigger
+ *   Tab         — Cycles between the cancel and action buttons (focus trap)
+ *   Shift+Tab   — Cycles backward
+ *
+ * @doc-aria
+ *   role           — "alertdialog" when destructive, "dialog" otherwise
+ *   aria-modal     — "true" while open
+ *   aria-labelledby — Wire to the heading id when you project one
+ *   aria-describedby — Auto-wired to the `<kj-confirm-popup-message>` id
+ *   data-state     — Reflects "open" / "closed" for animation hooks
+ *
+ * @doc-css-var
+ *   --kj-confirm-popup-bg            — Panel background fill. Defaults to --kj-bg-elevated.
+ *   --kj-confirm-popup-fg            — Foreground text color. Defaults to --kj-fg-default.
+ *   --kj-confirm-popup-border-color  — Border color around the panel. Defaults to --kj-border-default.
+ *   --kj-confirm-popup-radius        — Corner radius of the panel. Inherits --kj-radius-box.
+ *   --kj-confirm-popup-padding-x     — Horizontal inset of panel content.
+ *   --kj-confirm-popup-padding-y     — Vertical inset of panel content.
+ *   --kj-confirm-popup-shadow        — Box shadow under the floating panel. Defaults to --kj-shadow-md.
+ *
+ * @doc-touch
+ *   The trigger inherits its host button's touch target. The action and cancel
+ *   buttons should use `kj-button` `size="md"` or larger (≥ 44px) per WCAG 2.5.5.
+ *
+ * @doc-a11y
+ *   Built on the WAI-ARIA `alertdialog` pattern. Cancel receives initial focus
+ *   by default (WCAG 3.3.4 *Error Prevention*) — flip via `[kjDefaultFocus]`.
+ *   Focus is trapped inside the panel while open and restored to the trigger
+ *   on dismiss. Outside-clicks and Escape both resolve the popup with `false`,
+ *   so consumers can treat any dismissal as cancellation.
+ *
+ * @doc-related dialog,popover,tooltip
+ *
+ * @doc-category Library/Overlay
+ */
+@Component({
+  selector: 'kj-confirm-popup',
+  standalone: true,
+  // Only forward inputs that KjConfirmPopup declares DIRECTLY (not those
+  // inherited through its own nested hostDirectives [KjPopover]). Angular
+  // cannot chain nested hostDirectives input forwarding.
+  hostDirectives: [
+    {
+      directive: KjConfirmPopup,
+      inputs: [
+        'kjDestructive',
+        'kjDefaultFocus',
+      ],
+      outputs: [
+        'kjConfirmed',
+        'kjCancelled',
+        'kjResult',
+      ],
+    },
+  ],
+  template: `<ng-content />`,
+  styleUrl: './confirm-popup.css',
+  encapsulation: ViewEncapsulation.None,
+  host: {
+    class: 'kj-confirm-popup',
+    style: 'display: contents;',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjConfirmPopupComponent {}
+
+/**
+ * Styled wrapper around `KjConfirmPopupTrigger`.
+ *
+ * Place inside a `<kj-confirm-popup>` for the compound shape, or use it
+ * standalone with `[kjConfirmPopupTriggerFor]` pointing at an `<ng-template>`
+ * containing the popup content for the flat trigger-for shape.
+ *
+ * The host renders with `display: contents` so the projected `<button>` (or
+ * `<kj-button>`) is the actual interactive trigger and inherits the
+ * directive's ARIA wiring (`aria-haspopup="dialog"`, `aria-expanded`,
+ * `aria-controls`).
+ *
+ * @doc-category Library/Overlay
+ */
+@Component({
+  selector: 'kj-confirm-popup-trigger',
+  standalone: true,
+  hostDirectives: [KjConfirmPopupTrigger],
+  template: `<ng-content />`,
+  styleUrl: './confirm-popup.css',
+  encapsulation: ViewEncapsulation.None,
+  host: {
+    class: 'kj-confirm-popup-trigger',
+    style: 'display: contents;',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjConfirmPopupTriggerComponent {}
+
+/**
+ * Styled wrapper around the structural `KjConfirmPopupContent` directive.
+ *
+ * Place inside an `<ng-template>` (compound shape) or referenced via
+ * `[kjConfirmPopupTriggerFor]` (flat shape). The wrapper renders an inner
+ * `<ng-template kjPopoverContent kjConfirmPopupContent>` and forwards the
+ * projected content into the portal-mounted overlay panel —
+ * `role="alertdialog"` and the family's keyboard / outside-click coordination
+ * come from the underlying directives.
+ *
+ * @doc-category Library/Overlay
+ */
+@Component({
+  selector: 'kj-confirm-popup-content',
+  standalone: true,
+  imports: [KjPopoverContent, KjConfirmPopupContent],
+  template: `
+    <kj-popover-content [kjFor]="kjFor()" kjConfirmPopupContent [class]="resolvedPanelClass()">
+      <ng-content />
+    </kj-popover-content>
+  `,
+  styleUrl: './confirm-popup.css',
+  encapsulation: ViewEncapsulation.None,
+  host: {
+    class: 'kj-confirm-popup-content-host',
+    style: 'display: contents;',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjConfirmPopupContentComponent {
+  /** Anchor — the `[kjConfirmPopupTrigger]` template reference. */
+  readonly kjFor = input.required<KjOverlayTriggerLike>();
+  /** Optional class hook for the body-level overlay container. */
+  readonly kjPanelClass = input<string | string[]>('');
+
+  /**
+   * Always include the `kj-confirm-popup-content` class on the panel so the
+   * styled wrapper CSS lands on the floating box. Consumer-provided classes
+   * are concatenated.
+   */
+  readonly resolvedPanelClass = computed<string>(() => {
+    const out: string[] = ['kj-confirm-popup-content'];
+    const c = this.kjPanelClass();
+    if (Array.isArray(c)) {
+      for (const v of c) if (v) out.push(v);
+    } else if (c) {
+      out.push(c);
+    }
+    return out.join(' ');
+  });
+}
+
+/**
+ * Marks the message body inside `<kj-confirm-popup-content>`. Generates an
+ * auto-id and registers it with the popup so `aria-describedby` on the panel
+ * is wired automatically. Required for accessibility (WAI-ARIA `alertdialog`
+ * pattern requires a description).
+ *
+ * @doc-category Library/Overlay
+ */
+@Component({
+  selector: 'kj-confirm-popup-message',
+  standalone: true,
+  hostDirectives: [KjConfirmPopupMessage],
+  template: `<ng-content />`,
+  styleUrl: './confirm-popup.css',
+  encapsulation: ViewEncapsulation.None,
+  host: { class: 'kj-confirm-popup-message' },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjConfirmPopupMessageComponent {}
+
+/**
+ * Confirm action button slot. Click resolves the popup with `true`, emits
+ * `(kjConfirmed)` on the parent `<kj-confirm-popup>`. The styled wrapper
+ * adds the `kj-confirm-popup-action` class — pair with `<kj-button>` for
+ * the destructive variant when the popup is destructive.
+ *
+ * @doc-category Library/Overlay
+ */
+@Component({
+  selector: 'kj-confirm-popup-action',
+  standalone: true,
+  hostDirectives: [KjConfirmPopupAction],
+  template: `<ng-content />`,
+  styleUrl: './confirm-popup.css',
+  encapsulation: ViewEncapsulation.None,
+  host: {
+    class: 'kj-confirm-popup-action',
+    style: 'display: contents;',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjConfirmPopupActionComponent {}
+
+/**
+ * Cancel action button slot. Click resolves the popup with `false`, emits
+ * `(kjCancelled)` on the parent `<kj-confirm-popup>`. Receives initial focus
+ * by default — WCAG 3.3.4 *Error Prevention*.
+ *
+ * @doc-category Library/Overlay
+ */
+@Component({
+  selector: 'kj-confirm-popup-cancel',
+  standalone: true,
+  hostDirectives: [KjConfirmPopupCancel],
+  template: `<ng-content />`,
+  styleUrl: './confirm-popup.css',
+  encapsulation: ViewEncapsulation.None,
+  host: {
+    class: 'kj-confirm-popup-cancel',
+    style: 'display: contents;',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjConfirmPopupCancelComponent {}
+
+/**
+ * Convenience container for the action button row. Pure styling hook — the
+ * semantic comes from the `<kj-confirm-popup-action>` and
+ * `<kj-confirm-popup-cancel>` slots inside.
+ *
+ * @doc-category Library/Overlay
+ */
+@Component({
+  selector: 'kj-confirm-popup-actions',
+  standalone: true,
+  template: `<ng-content />`,
+  styleUrl: './confirm-popup.css',
+  encapsulation: ViewEncapsulation.None,
+  host: { class: 'kj-confirm-popup-actions' },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjConfirmPopupActionsComponent {}

package/src/confirm-popup/index.ts

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

package/src/date-picker/_examples/date-picker.disabled-dates.example.ts

@@ -0,0 +1,44 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjDatePickerComponent } from '../date-picker';
+
+/**
+ * Disabled-dates example. Pass a predicate via `kjDisabledDates` — return
+ * `true` for selectable, `false` for disabled. Here we disable weekends so
+ * only weekdays can be picked.
+ */
+@Component({
+  selector: 'kj-date-picker-disabled-dates-example',
+  standalone: true,
+  imports: [KjDatePickerComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+        padding: var(--kj-space-2xl, 2rem);
+        background: var(--kj-bg-surface, #f3f3f3);
+        min-height: 24rem;
+      }
+      .hint {
+        margin-top: var(--kj-space-md, 0.75rem);
+        font-size: 0.875rem;
+        opacity: 0.75;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-date-picker
+      [(kjValue)]="when"
+      [kjDisabledDates]="weekdaysOnly"
+      kjPlaceholder="Pick a weekday"
+    />
+    <p class="hint">Saturdays and Sundays are disabled.</p>
+  `,
+})
+export class KjDatePickerDisabledDatesExample {
+  when = signal<Date>(new Date());
+  readonly weekdaysOnly = (d: Date) => {
+    const dow = d.getDay();
+    return dow !== 0 && dow !== 6;
+  };
+}

package/src/date-picker/_examples/date-picker.example.ts

@@ -0,0 +1,38 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjDatePickerComponent } from '../date-picker';
+
+/**
+ * Default usage example for KjDatePickerComponent.
+ *
+ * The input accepts typed dates (`2025-04-15` or locale-aware `4/15/2025`)
+ * and the calendar icon opens a popover for click-selection. Two-way binding
+ * to a `signal<Date | null>` keeps the model in sync.
+ */
+@Component({
+  selector: 'kj-date-picker-example',
+  standalone: true,
+  imports: [KjDatePickerComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+        padding: var(--kj-space-2xl, 2rem);
+        background: var(--kj-bg-surface, #f3f3f3);
+        min-height: 24rem;
+      }
+      .selected {
+        margin-top: var(--kj-space-md, 0.75rem);
+        font-family: monospace;
+        color: var(--kj-fg-default, #111);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-date-picker [(kjValue)]="when" kjPlaceholder="Pick a date" />
+    <p class="selected">Selected: {{ when().toDateString() }}</p>
+  `,
+})
+export class KjDatePickerExample {
+  when = signal<Date>(new Date());
+}

package/src/date-picker/_examples/date-picker.locale.example.ts

@@ -0,0 +1,50 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjDatePickerComponent } from '../date-picker';
+
+/**
+ * Locale example. Passing `kjLocale="fr-FR"` switches month/weekday names to
+ * French and flips the input format to `dd/mm/yyyy`. The first day of the
+ * week follows `Intl.Locale.getWeekInfo()` (Monday for `fr-FR`).
+ */
+@Component({
+  selector: 'kj-date-picker-locale-example',
+  standalone: true,
+  imports: [KjDatePickerComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+        padding: var(--kj-space-2xl, 2rem);
+        background: var(--kj-bg-surface, #f3f3f3);
+        min-height: 24rem;
+      }
+      .row {
+        display: grid;
+        grid-template-columns: 6rem 1fr;
+        align-items: center;
+        gap: var(--kj-space-md, 0.75rem);
+        margin-bottom: var(--kj-space-md, 0.75rem);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <div class="row">
+      <span>en-US</span>
+      <kj-date-picker [(kjValue)]="enValue" kjLocale="en-US" kjPlaceholder="MM/DD/YYYY" />
+    </div>
+    <div class="row">
+      <span>fr-FR</span>
+      <kj-date-picker [(kjValue)]="frValue" kjLocale="fr-FR" kjPlaceholder="JJ/MM/AAAA" />
+    </div>
+    <div class="row">
+      <span>ja-JP</span>
+      <kj-date-picker [(kjValue)]="jaValue" kjLocale="ja-JP" />
+    </div>
+  `,
+})
+export class KjDatePickerLocaleExample {
+  enValue = signal<Date>(new Date());
+  frValue = signal<Date>(new Date());
+  jaValue = signal<Date>(new Date());
+}

package/src/date-picker/_examples/date-picker.readonly.example.ts

@@ -0,0 +1,32 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjDatePickerComponent } from '../date-picker';
+
+/**
+ * Read-only example. The input shows the formatted value but cannot be
+ * edited and the popover toggle is disabled. Useful for "view as a date
+ * picker" scenarios where the value is computed elsewhere.
+ *
+ * (A range-mode / multi-mode example is reserved for a follow-up release —
+ * see `docs/component-analyses/data-input/date-picker.md` for the
+ * deferred range surface.)
+ */
+@Component({
+  selector: 'kj-date-picker-readonly-example',
+  standalone: true,
+  imports: [KjDatePickerComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+        padding: var(--kj-space-2xl, 2rem);
+        background: var(--kj-bg-surface, #f3f3f3);
+        min-height: 12rem;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: ` <kj-date-picker [(kjValue)]="when" [kjReadonly]="true" /> `,
+})
+export class KjDatePickerReadonlyExample {
+  readonly when = signal<Date>(new Date());
+}

package/src/date-picker/_examples/date-picker.usage.example.ts

@@ -0,0 +1,60 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjDatePickerComponent } from '../date-picker';
+
+/**
+ * A walkthrough of the most common date-picker usages — single-date two-way
+ * binding, min / max bounds to enforce a valid range, and a read-only field.
+ */
+@Component({
+  selector: 'kj-date-picker-usage-example',
+  standalone: true,
+  imports: [KjDatePickerComponent],
+  styles: [
+    `
+      :host {
+        display: flex;
+        flex-direction: column;
+        gap: var(--kj-space-md);
+        padding: var(--kj-space-xl);
+      }
+      .row {
+        display: flex;
+        gap: var(--kj-space-md);
+        align-items: center;
+        flex-wrap: wrap;
+      }
+      code {
+        font: 0.8125rem/1 var(--kj-font-mono, monospace);
+        color: var(--kj-fg-muted);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <div class="row">
+      <kj-date-picker [(kjValue)]="when" kjPlaceholder="Pick a date" />
+      <code>{{ when()?.toDateString() ?? '—' }}</code>
+    </div>
+
+    <div class="row">
+      <kj-date-picker
+        [(kjValue)]="bounded"
+        [kjMin]="minDate"
+        [kjMax]="maxDate"
+        kjPlaceholder="This week only"
+      />
+      <code>min/max constrained</code>
+    </div>
+
+    <div class="row">
+      <kj-date-picker [kjValue]="when()" [kjReadonly]="true" />
+      <code>readonly</code>
+    </div>
+  `,
+})
+export class KjDatePickerUsageExample {
+  readonly when = signal<Date | null>(new Date());
+  readonly bounded = signal<Date | null>(null);
+  readonly minDate = new Date();
+  readonly maxDate = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000);
+}

package/src/date-picker/_examples/date-picker.with-min-max.example.ts

@@ -0,0 +1,47 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjDatePickerComponent } from '../date-picker';
+
+/**
+ * Min / max bounds example. Dates outside `[kjMin, kjMax]` carry
+ * `aria-disabled="true"` in the calendar grid and are skipped by keyboard
+ * navigation. Out-of-bounds typed input is rejected on blur.
+ */
+@Component({
+  selector: 'kj-date-picker-with-min-max-example',
+  standalone: true,
+  imports: [KjDatePickerComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+        padding: var(--kj-space-2xl, 2rem);
+        background: var(--kj-bg-surface, #f3f3f3);
+        min-height: 24rem;
+      }
+      .hint {
+        margin-top: var(--kj-space-md, 0.75rem);
+        font-size: 0.875rem;
+        opacity: 0.75;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-date-picker
+      [(kjValue)]="when"
+      [kjMin]="min"
+      [kjMax]="max"
+      kjPlaceholder="Pick a date in the next 14 days"
+    />
+    <p class="hint">Bounds: {{ min.toDateString() }} → {{ max.toDateString() }}</p>
+  `,
+})
+export class KjDatePickerWithMinMaxExample {
+  readonly min = new Date();
+  readonly max = (() => {
+    const d = new Date();
+    d.setDate(d.getDate() + 14);
+    return d;
+  })();
+  when = signal<Date>(new Date());
+}

package/src/date-picker/_examples/index.ts

@@ -0,0 +1,8 @@
+// AUTO-GENERATED by scripts/migrate-examples.mjs
+// One barrel per component folder — used by the docs app as a lazy chunk.
+export { KjDatePickerDisabledDatesExample } from './date-picker.disabled-dates.example';
+export { KjDatePickerExample } from './date-picker.example';
+export { KjDatePickerLocaleExample } from './date-picker.locale.example';
+export { KjDatePickerReadonlyExample } from './date-picker.readonly.example';
+export { KjDatePickerUsageExample } from './date-picker.usage.example';
+export { KjDatePickerWithMinMaxExample } from './date-picker.with-min-max.example';

package/src/date-picker/date-picker.css

@@ -0,0 +1,61 @@
+.kj-date-picker {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--kj-space-xs);
+  position: relative;
+}
+
+.kj-date-picker__input {
+  /* Explicit height contract (matches input.css / button.css) so the date
+     input lines up with sibling inputs in a form row. */
+  --kj-date-picker-input-height: 2.25rem;
+  appearance: none;
+  border: var(--kj-border) solid var(--kj-border-default);
+  border-radius: var(--kj-radius-field);
+  padding: 0 var(--kj-space-md);
+  height: var(--kj-date-picker-input-height);
+  font: inherit;
+  background: var(--kj-bg-field);
+  color: var(--kj-fg-default);
+  min-width: 12ch;
+}
+.kj-date-picker[data-size="xs"] .kj-date-picker__input { --kj-date-picker-input-height: 1.75rem; font-size: 0.75rem;   padding-inline: var(--kj-space-sm); min-width: 0; }
+.kj-date-picker[data-size="sm"] .kj-date-picker__input { --kj-date-picker-input-height: 2rem;    font-size: 0.8125rem; }
+.kj-date-picker[data-size="lg"] .kj-date-picker__input { --kj-date-picker-input-height: 2.75rem; font-size: 1rem; }
+
+.kj-date-picker__input:focus {
+  outline: 2px solid var(--kj-border-focus);
+  outline-offset: 2px;
+  border-color: var(--kj-border-focus);
+}
+
+.kj-date-picker__input[disabled] {
+  opacity: 0.55;
+  cursor: not-allowed;
+}
+
+/* Panel owns the elevated surface chrome (bg, border, radius, shadow,
+   inset padding). The projected `.kj-calendar` stays chrome-less so it
+   reads as a flat grid inside the panel. */
+.kj-date-picker__panel {
+  box-sizing: border-box;
+  z-index: 50;
+  display: inline-block;
+  background: var(--kj-bg-elevated);
+  color: var(--kj-fg-default);
+  border: var(--kj-border) solid var(--kj-border-default);
+  border-radius: var(--kj-radius-box);
+  box-shadow: var(--kj-shadow-md);
+  padding: var(--kj-space-sm);
+}
+
+/* When the calendar is projected into the panel it already gets padding
+   from above; collapse its own padding so the inner content lines up with
+   the panel's inset. */
+.kj-date-picker__panel .kj-calendar {
+  padding: 0;
+}
+
+.kj-date-picker__panel[hidden] {
+  display: none;
+}