@kouji-ui/core 0.0.3 → 0.1.1

package/src/public-api.ts

@@ -1,35 +1,84 @@
 // Public API for @kouji-ui/core
 
-export const KJ_CORE_VERSION = '0.0.1';
-
-// ── Primitives ──────────────────────────────────────────────
+// -- Primitives --
 export * from './primitives/index';
 
-// ── Accessibility utilities ──────────────────────────────────
+// -- Accessibility utilities --
 export * from './a11y/index';
 
-// ── Foundation components ────────────────────────────────────
+// -- Internal presets (composed via hostDirectives; filtered from docs) --
+export * from './presets/index';
+
+// -- Foundation components --
 export * from './button/index';
+export * from './button-group/index';
 export * from './input/index';
+export * from './input-group/index';
+export * from './input-mask/index';
+export * from './input-otp/index';
+export * from './number-input/index';
+export * from './slider/index';
+export * from './password-input/index';
+export * from './textarea/index';
 export * from './checkbox/index';
 export * from './radio/index';
 export * from './toggle/index';
 export * from './badge/index';
+export * from './overlay-badge/index';
 export * from './avatar/index';
+export * from './kbd/index';
+export * from './icon/index';
 
-// ── Overlay components ───────────────────────────────────────
+// -- Data display --
+export * from './list/index';
+export * from './carousel/index';
+export * from './chat/index';
+export * from './typography/index';
+export * from './tag/index';
+
+// -- Overlay components --
 export * from './dialog/index';
+export * from './drawer/index';
 export * from './tooltip/index';
 export * from './popover/index';
-export * from './menu/index';
+export * from './confirm-popup/index';
+export * from './dropdown-menu/index';
+export * from './speed-dial/index';
 export * from './toast/index';
+export * from './command-palette/index';
 
-// ── Data components ──────────────────────────────────────────
+// -- Data components --
 export * from './table/index';
+export * from './field/index';
+export * from './file-upload/index';
 export * from './form/index';
 export * from './tabs/index';
 export * from './accordion/index';
+export * from './stepper/index';
 export * from './select/index';
+export * from './combobox/index';
+export * from './cascade-select/index';
+export * from './tree-select/index';
+export * from './time-picker/index';
+export * from './color-picker/index';
+export * from './calendar/index';
+export * from './date-picker/index';
 
-// ── Charts ───────────────────────────────────────────────────
+// -- Charts --
 export * from './chart/index';
+
+// -- Layout components --
+export * from './divider/index';
+export * from './skeleton/index';
+
+// -- Navigation --
+export * from './link/index';
+export * from './breadcrumb/index';
+export * from './menubar/index';
+export * from './pagination/index';
+
+// -- Feedback components --
+export * from './spinner/index';
+export * from './progress-bar/index';
+
+export * from './alert/index';

package/src/radio/radio.ts

@@ -1,4 +1,4 @@
-import { Directive, computed, inject, input, model } from '@angular/core';
+import { Directive, computed, inject, input, model } from '@angular/core';
 import { KJ_RADIO_GROUP, KjRadioContext } from './radio.context';
 import { KjDisabled, KjFocusRing, KjFormControl } from '../primitives';
 
@@ -10,7 +10,9 @@ import { KjDisabled, KjFocusRing, KjFormControl } from '../primitives';
  *   <div kjRadio [kjRadioValue]="'s'" tabindex="0">Small</div>
  * </div>
  * ```
- * @category Core/Inputs
+ * @doc-category Core/Inputs
+ * @doc
+ * @doc-name radio
  */
 @Directive({
   selector: '[kjRadioGroup]', standalone: true,
@@ -25,8 +27,17 @@ export class KjRadioGroup implements KjRadioContext {
 
 /**
  * Individual radio button within a `[kjRadioGroup]`. Includes CVA for forms integration.
+ *
+ * Owns `role="radio"`, `aria-checked`, Space/Enter activation, and Angular
+ * forms integration via the `KjFormControl` host directive so each radio
+ * participates in reactive and template-driven forms.
+ *
  * @example `<div kjRadio [kjRadioValue]="'a'" tabindex="0">Option A</div>`
- * @category Core/Inputs
+ * @doc-category Core/Inputs
+ * @doc
+ * @doc-name radio
+ * @doc-description Individual radio button within a radio group with accessible activation and forms support.
+ * @doc-is-main
  */
 @Directive({
   selector: '[kjRadio]', standalone: true,

package/src/select/index.ts

@@ -1,2 +1,4 @@
-export { KjSelect, KjSelectTrigger, KjSelectContent, KjOption } from './select';
-export { KJ_SELECT, type KjSelectContext } from './select.context';
+export * from './select-root';
+export * from './select-trigger';
+export * from './select-content';
+export * from './select-option';

package/src/select/select-content.ts

@@ -0,0 +1,69 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  ViewEncapsulation,
+  inject,
+  input,
+} from '@angular/core';
+import { KjOverlayPanel } from '../primitives/overlay/panel';
+import {
+  KJ_OVERLAY_MOUNT_STRATEGY,
+  KJ_OVERLAY_POSITION_STRATEGY,
+  KJ_OVERLAY_PANEL_ROLE,
+} from '../primitives/overlay/tokens';
+import type { KjSide, KjAlign } from '../primitives/overlay/types';
+import { bodyPortal } from '../primitives/overlay/strategies/mount/body-portal';
+import { anchoredTo } from '../primitives/overlay/strategies/position/anchored-to';
+import { KjListNavigator, injectSelectionModel } from '../primitives/list';
+
+/**
+ * Listbox panel for `KjSelect`. Composes `KjOverlayPanel` for
+ * mount/position/role wiring and `KjListNavigator` for the WAI-ARIA APG
+ * listbox keyboard + active-descendant contract. Reflects
+ * `KjSelectionModel.mode()` as `aria-multiselectable`.
+ *
+ * @doc-category Core/Inputs
+ */
+@Component({
+  selector: 'kj-select-content',
+  standalone: true,
+  hostDirectives: [
+    { directive: KjOverlayPanel, inputs: ['kjFor'] },
+    KjListNavigator,
+  ],
+  providers: [
+    { provide: KJ_OVERLAY_PANEL_ROLE, useValue: 'listbox' as const },
+    { provide: KJ_OVERLAY_MOUNT_STRATEGY, useFactory: () => bodyPortal() },
+    { provide: KJ_OVERLAY_POSITION_STRATEGY, useFactory: () => anchoredTo() },
+  ],
+  host: {
+    '[attr.aria-multiselectable]':
+      'selection.mode() === "multi" ? "true" : null',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  template: `<ng-content />`,
+})
+export class KjSelectContent {
+  /** @internal — for the aria-multiselectable host binding. */
+  protected readonly selection = injectSelectionModel<unknown>();
+
+  /** Which side of the trigger to anchor on. */
+  readonly kjSide = input<KjSide>('bottom');
+  /** Alignment along the chosen side. */
+  readonly kjAlign = input<KjAlign>('start');
+  /** Pixel offset between trigger and panel. */
+  readonly kjOffset = input<number, unknown>(4, {
+    transform: v => Number(v) || 4,
+  });
+
+  constructor() {
+    const pos = inject(KJ_OVERLAY_POSITION_STRATEGY) as ReturnType<typeof anchoredTo>;
+    pos.configure({
+      side: this.kjSide,
+      align: this.kjAlign,
+      offset: this.kjOffset,
+      matchTriggerWidth: 'min',
+    });
+  }
+}

package/src/select/select-option.ts

@@ -0,0 +1,35 @@
+import { Directive } from '@angular/core';
+import { KjListItem } from '../primitives/list';
+
+/**
+ * Individual option inside a `<kj-select-content>`. Public inputs
+ * (`kjOptionValue`, `kjOptionLabel`) are aliased onto the composed
+ * `KjListItem`'s `kjItemValue` / `kjItemLabel`. Activation (click /
+ * Enter / Space), selection-model toggle, and overlay dismissal are
+ * all owned by `KjListItem` + `KjSelect.afterSelect` — this directive
+ * is just role + class + the input aliasing.
+ *
+ * @example
+ * ```html
+ * <div kjOption [kjOptionValue]="'apple'">Apple</div>
+ * ```
+ * @doc-category Core/Inputs
+ */
+@Directive({
+  selector: '[kjOption]',
+  standalone: true,
+  hostDirectives: [
+    {
+      directive: KjListItem,
+      inputs: [
+        'kjItemValue:kjOptionValue',
+        'kjItemLabel:kjOptionLabel',
+      ],
+    },
+  ],
+  host: {
+    'class': 'kj-option',
+    'role': 'option',
+  },
+})
+export class KjOption {}

package/src/select/select-root.ts

@@ -0,0 +1,129 @@
+import {
+  Directive,
+  ElementRef,
+  InjectionToken,
+  computed,
+  contentChildren,
+  forwardRef,
+  inject,
+  input,
+  model,
+  signal,
+  type Signal,
+  type WritableSignal,
+} from '@angular/core';
+import { KjOverlayController } from '../primitives/overlay/controller';
+import {
+  KJ_LIST_NAVIGATOR_CONFIG,
+  KjListItem,
+  KjSelectionModel,
+  KjTypeAhead,
+  type KjCompareFn,
+  type KjListNavigatorConfig,
+  type KjListSelectionMode,
+} from '../primitives/list';
+
+export const KJ_SELECT = new InjectionToken<KjSelect>('KjSelect');
+
+/**
+ * Root select container. Implements `KjListNavigatorConfig` (items,
+ * value, mode, compareBy) and provides itself under
+ * `KJ_LIST_NAVIGATOR_CONFIG` via `forwardRef`. Downstream primitives
+ * (`KjSelectionModel`, `KjListNavigator`, `KjTypeAhead`) read whatever
+ * they need from this single contract.
+ *
+ * `KjSelect` itself does NOT inject `KjSelectionModel` — doing so at
+ * construction would create a runtime cycle (the model's
+ * `inject(KJ_LIST_NAVIGATOR_CONFIG)` would try to resolve a not-yet-
+ * constructed `KjSelect` instance, regardless of `forwardRef`). Instead,
+ * the model is constructed lazily when a child (`KjOption`, `KjListItem`)
+ * first asks for it, by which point `KjSelect` is fully built.
+ *
+ * @doc-category Core/Inputs
+ */
+@Directive({
+  selector: '[kjSelect]',
+  standalone: true,
+  exportAs: 'kjSelect',
+  providers: [
+    { provide: KJ_SELECT, useExisting: forwardRef(() => KjSelect) },
+    { provide: KJ_LIST_NAVIGATOR_CONFIG, useExisting: forwardRef(() => KjSelect) },
+    KjSelectionModel,
+    KjTypeAhead,
+    KjOverlayController,
+  ],
+})
+export class KjSelect implements KjListNavigatorConfig {
+  /** Two-way bindable selected value (single) or values (multi). */
+  readonly kjSelectValue = model<unknown>(undefined);
+
+  /**
+   * Implements `KjListNavigatorConfig.value`. The selection model reads
+   * and writes through this same signal — one source of truth, no
+   * bridging effects.
+   */
+  readonly value = this.kjSelectValue as unknown as WritableSignal<
+    unknown | readonly unknown[] | null
+  >;
+
+  /** Optional custom equality fn. Defaults to `Object.is`. */
+  readonly kjCompareBy = input<KjCompareFn<unknown>>(Object.is as KjCompareFn<unknown>);
+
+  /** @internal — written by `KjSelectTrigger`'s `kjMultiple` input. */
+  readonly _multiple = signal(false);
+  /** Whether multi-select is enabled. */
+  readonly multiple = this._multiple.asReadonly();
+
+  /** @internal — set by `KjSelectTrigger` at construction time. */
+  readonly _triggerEl = signal<ElementRef<HTMLElement> | null>(null);
+  /**
+   * Element ref of the registered trigger button. Resolves the moment
+   * `KjSelectTrigger` constructs (no view-query lifecycle wait), so
+   * consumers can call `focus()` synchronously from `effect()` blocks
+   * even when the select is mounted dynamically.
+   */
+  readonly triggerEl = this._triggerEl.asReadonly();
+
+  /** Move keyboard focus to the trigger. No-op if no trigger registered. */
+  focus(): void {
+    this._triggerEl()?.nativeElement.focus();
+  }
+
+  /** All `KjListItem`s under this select — source for navigator + type-ahead. */
+  readonly items = contentChildren(KjListItem, { descendants: true });
+
+  /** Implements `KjListNavigatorConfig.mode`. */
+  readonly mode: Signal<KjListSelectionMode> = computed(() =>
+    this._multiple() ? 'multi' : 'single',
+  );
+
+  /** Implements `KjListNavigatorConfig.compareBy`. */
+  readonly compareBy = this.kjCompareBy;
+
+  private readonly controller = inject(KjOverlayController);
+
+  /** Whether the overlay is open. */
+  readonly open = this.controller.isOpen;
+
+  /** Directly-injected selection model; wired via `bind()` below. */
+  private readonly _selection = inject(KjSelectionModel);
+
+  constructor() {
+    this._selection.bind({
+      value:     this.value,
+      items:     this.items,
+      mode:      this.mode,
+      compareBy: this.compareBy,
+    });
+  }
+
+  /**
+   * Implements `KjListNavigatorConfig.afterSelect`. Called by
+   * `KjListItem` right after it toggles the shared selection model.
+   * In single mode (the only mode where `closeRequested` is `true`)
+   * we dismiss the overlay; multi mode keeps it open.
+   */
+  afterSelect(_: unknown, closeRequested: boolean): void {
+    if (closeRequested) this.controller.close('programmatic');
+  }
+}

package/src/select/select-trigger.ts

@@ -0,0 +1,93 @@
+import {
+  Directive,
+  ElementRef,
+  booleanAttribute,
+  effect,
+  inject,
+  input,
+} from '@angular/core';
+import { KjFocusRing } from '../primitives';
+import { KjOverlayTrigger } from '../primitives/overlay/trigger';
+import type { KjOverlayPanel } from '../primitives/overlay/panel';
+import { KjOverlayController } from '../primitives/overlay/controller';
+import {
+  KJ_OVERLAY_TRIGGER_EVENT_STRATEGY,
+  KJ_OVERLAY_PANEL_ROLE,
+  type KjTriggerEventStrategy,
+} from '../primitives/overlay/tokens';
+import { onClick } from '../primitives/overlay/strategies/trigger-event/on-click';
+import { KJ_SELECT } from './select-root';
+
+/**
+ * Wraps `onClick()` and forces `ariaHasPopup` to `'listbox'` so the trigger
+ * advertises its panel role to assistive tech.
+ */
+function listboxClickTrigger(): KjTriggerEventStrategy {
+  const inner = onClick();
+  return {
+    ariaHasPopup: 'listbox',
+    attach: c => inner.attach(c),
+    bindToggle: t => inner.bindToggle(t),
+    onOpen: () => inner.onOpen?.(),
+    onClose: () => inner.onClose?.(),
+    detach: () => inner.detach(),
+  };
+}
+
+/**
+ * Trigger directive for `KjSelectContent`. Composes the overlay
+ * `KjOverlayTrigger` host directive (which wires `aria-expanded`,
+ * `aria-controls`, `aria-haspopup`) and forwards the `kjMultiple` input
+ * onto the umbrella `KjSelect` root.
+ *
+ * The shared `KjOverlayController` is provided by the `KjSelect` root
+ * directive, not here — so option clicks can call `controller.close()`
+ * directly through the same instance the trigger is wired to.
+ *
+ * @doc-category Core/Inputs
+ */
+@Directive({
+  selector: '[kjSelectTrigger]',
+  exportAs: 'kjSelectTrigger',
+  standalone: true,
+  hostDirectives: [
+    KjFocusRing,
+    { directive: KjOverlayTrigger, inputs: ['kjOpen'] },
+  ],
+  providers: [
+    {
+      provide: KJ_OVERLAY_TRIGGER_EVENT_STRATEGY,
+      useFactory: () => listboxClickTrigger(),
+    },
+    { provide: KJ_OVERLAY_PANEL_ROLE, useValue: 'listbox' as const },
+  ],
+})
+export class KjSelectTrigger {
+  /** @internal — same instance as the one provided on KjSelect root. */
+  readonly controller = inject(KjOverlayController);
+  private readonly select = inject(KJ_SELECT, { optional: true });
+
+  /** Whether the listbox supports multiple selection (absorbs `multi-select`). */
+  readonly kjMultiple = input(false, { transform: booleanAttribute });
+  /** Disabled state (advisory; downstream styling). */
+  readonly kjDisabled = input(false, { transform: booleanAttribute });
+
+  private readonly hostEl = inject(ElementRef<HTMLElement>);
+
+  constructor() {
+    // Forward kjMultiple onto the parent KjSelect (when present) so options
+    // and content can read a single source of truth.
+    effect(() => {
+      this.select?._multiple.set(this.kjMultiple());
+    });
+    // Register the trigger's host element with the parent KjSelect so
+    // consumers (cell editors, dialogs, custom integrations) can call
+    // `KjSelect.focus()` without a view-query round-trip.
+    this.select?._triggerEl.set(this.hostEl);
+  }
+
+  private readonly _overlayTrigger = inject(KjOverlayTrigger, { self: true });
+  attachPanel(panel: KjOverlayPanel): void {
+    this._overlayTrigger.attachPanel(panel);
+  }
+}