@kouji-ui/core 0.0.3 → 0.1.1

package/src/carousel/index.ts

@@ -0,0 +1,22 @@
+export {
+  KjCarousel,
+  KjCarouselViewport,
+  KjCarouselSlide,
+  KjCarouselPrevious,
+  KjCarouselNext,
+  KjCarouselIndicators,
+  KjCarouselIndicator,
+  KjCarouselAutoplay,
+  KjCarouselPauseToggle,
+} from './carousel';
+export {
+  KJ_CAROUSEL,
+  KJ_CAROUSEL_SLIDE,
+  KJ_CAROUSEL_INDICATORS,
+  type KjCarouselContext,
+  type KjCarouselSlideContext,
+  type KjCarouselIndicatorsContext,
+  type KjCarouselOrientation,
+  type KjCarouselAlign,
+  type KjCarouselControlPattern,
+} from './carousel.context';

package/src/cascade-select/cascade-select-option.ts

@@ -0,0 +1,205 @@
+import {
+  computed,
+  contentChildren,
+  Directive,
+  forwardRef,
+  inject,
+  OnDestroy,
+} from '@angular/core';
+import { KjListItem, injectListItem } from '../primitives/list';
+import { KJ_CASCADE_SELECT } from './cascade-select.context';
+import { KjCascadeSelectSubPanel } from './cascade-select-sub-panel';
+
+/**
+ * Single row inside a `[kjCascadeSelectPanel]` or
+ * `[kjCascadeSelectSubPanel]`. When projected `[kjCascadeSelectSubPanel]`
+ * content is present the option becomes a **sub-trigger** (branch node);
+ * otherwise it is a **leaf** that commits a value on activation.
+ *
+ * Composes `KjListItem` via `hostDirectives` — the list item owns the
+ * stable `id`, the click / Enter / Space activation, `aria-selected`
+ * (via the shared `KjSelectionModel` in `'leaf'` mode), and
+ * `aria-disabled`. This directive contributes cascade-specific
+ * semantics: `role="treeitem"`, branch `aria-haspopup` / `aria-expanded`,
+ * and hover-open / hover-close timers for sub-panels.
+ *
+ * Branch detection is signal-driven: `KjCascadeSelectSubPanel` instances
+ * declared inside this option call `_registerSubPanel()` from their
+ * constructor (they inject this directive via the element injector).
+ * No `contentChildren` + binding effect — straightforward DI both ways.
+ *
+ * Branch clicks are no-ops at the selection-model level (leaf mode
+ * filters them out when a `treeShape` is provided on the root) but
+ * still toggle their own sub-panel via this directive's
+ * `handleClick()`.
+ *
+ * Role: `treeitem`.
+ *
+ * @example Leaf
+ * ```html
+ * <div kjCascadeSelectOption [kjValue]="'sf'" kjLabel="San Francisco" />
+ * ```
+ *
+ * @example Branch
+ * ```html
+ * <div kjCascadeSelectOption [kjValue]="'us'" kjLabel="USA">
+ *   <div kjCascadeSelectSubPanel>…</div>
+ * </div>
+ * ```
+ * @doc-category Core/Data input
+ * @doc
+ * @doc-name cascade-select
+ */
+@Directive({
+  selector: '[kjCascadeSelectOption]',
+  exportAs: 'kjCascadeSelectOption',
+  standalone: true,
+  hostDirectives: [
+    {
+      directive: KjListItem,
+      inputs: [
+        'kjItemValue:kjValue',
+        'kjItemLabel:kjLabel',
+        'kjDisabled:kjDisabled',
+      ],
+    },
+  ],
+  host: {
+    'role': 'treeitem',
+    '[attr.aria-haspopup]': 'isBranch() ? "tree" : null',
+    '[attr.aria-expanded]': 'isBranch() ? subPanelOpen().toString() : null',
+    '[attr.data-label]': 'item.label()',
+    '[attr.data-leaf]': 'isLeaf().toString()',
+    '[attr.data-selected]': 'item.ariaSelected() === "true" ? "" : null',
+    '[attr.data-active-path]': 'isOnActivePath() ? "" : null',
+    '(click)': 'handleClick()',
+    '(mouseenter)': 'handleMouseEnter()',
+    '(mouseleave)': 'handleMouseLeave()',
+  },
+})
+export class KjCascadeSelectOption implements OnDestroy {
+  /** @internal — composed list-item primitive providing id/value/disabled/activation. */
+  readonly item = injectListItem<unknown>();
+  /** @internal */
+  readonly ctx = inject(KJ_CASCADE_SELECT);
+
+  /**
+   * @internal Closest ancestor sub-panel (if any). `null` when this
+   * option sits in the root cascade panel. Used by `KjCascadeSelect`'s
+   * `openSubPanel` chain rebuild — walking parent panels up to the
+   * root produces the exact open-chain that should be set, so opening
+   * a sibling at any level closes its siblings automatically (instead
+   * of leaving stale entries that a late-firing close timer can then
+   * slice through).
+   *
+   * `forwardRef` defers the class lookup so the option ↔ sub-panel
+   * import cycle doesn't trip on first evaluation.
+   */
+  readonly parentSubPanel = inject<KjCascadeSelectSubPanel | null>(
+    forwardRef(() => KjCascadeSelectSubPanel),
+    { optional: true },
+  );
+
+  // `kjValue`, `kjLabel`, `kjDisabled` are exposed via the composed
+  // `KjListItem` host directive above. Don't redeclare them on this
+  // class — duplicate public-name inputs route to the local declaration
+  // and leave `KjListItem.kjItemValue` unset. Read values back through
+  // `this.item.value()` / `this.item.label()`.
+
+  /**
+   * @internal Sub-panels projected as content of this option. Any
+   * `[kjCascadeSelectSubPanel]` declared inside the option's content
+   * makes it a branch — Angular keeps this signal in sync.
+   */
+  private readonly _subPanels = contentChildren(
+    forwardRef(() => KjCascadeSelectSubPanel),
+    { descendants: true },
+  );
+
+  /** @internal Whether this option is a branch node. */
+  readonly isBranch = computed(() => this._subPanels().length > 0);
+
+  /** @internal Inverse of `isBranch` for the `data-leaf` attribute. */
+  readonly isLeaf = computed(() => !this.isBranch());
+
+  private _openTimer: ReturnType<typeof setTimeout> | undefined;
+  private _closeTimer: ReturnType<typeof setTimeout> | undefined;
+
+  /** @internal True when this option's sub-panel is open. */
+  readonly subPanelOpen = computed(() =>
+    this.isBranch()
+      ? this.ctx.openSubPanels().includes(this.item.id)
+      : false,
+  );
+
+  /** @internal True when the selected value is in this option's sub-tree. */
+  readonly isOnActivePath = computed(() => {
+    const path = this.ctx.path();
+    const v = this.item.value();
+    return v !== undefined && path.includes(v);
+  });
+
+  ngOnDestroy(): void {
+    clearTimeout(this._openTimer);
+    clearTimeout(this._closeTimer);
+  }
+
+  /**
+   * @internal Click handler — branch-only sub-panel toggle. Leaf clicks
+   * are handled by the composed `KjListItem` (which calls
+   * `KjSelectionModel.toggle` and then `KjCascadeSelect.afterSelect`).
+   * In leaf-mode `KjSelectionModel` no-ops on branches when a tree
+   * shape is provided, so we don't need to gate that here.
+   */
+  handleClick(): void {
+    if (this.item.disabled()) return;
+    if (!this.isBranch()) return;
+    clearTimeout(this._openTimer);
+    clearTimeout(this._closeTimer);
+    if (this.subPanelOpen()) this.ctx.closeSubPanel(this.item.id);
+    else this.ctx.openSubPanel(this.item.id);
+  }
+
+  /** @internal */
+  handleMouseEnter(): void {
+    if (this.item.disabled() || !this.isBranch()) return;
+    clearTimeout(this._closeTimer);
+    const delay = this.ctx.subPanelOpenDelayMs();
+    this._openTimer = setTimeout(() => {
+      this.ctx.openSubPanel(this.item.id);
+    }, delay);
+  }
+
+  /** @internal */
+  handleMouseLeave(): void {
+    if (this.item.disabled() || !this.isBranch()) return;
+    clearTimeout(this._openTimer);
+    this._scheduleClose();
+  }
+
+  /**
+   * @internal Called by `KjCascadeSelectSubPanel` when the cursor enters
+   * the sub-panel. The option's `mouseleave` fires the moment the cursor
+   * crosses out of the option's bounding box — including the case where
+   * the cursor moves *into* the adjacent sub-panel. Without this bridge,
+   * the close timer kept ticking and dismissed an actively-hovered
+   * sub-panel after `subPanelCloseDelayMs`.
+   */
+  _cancelCloseTimer(): void {
+    clearTimeout(this._closeTimer);
+    this._closeTimer = undefined;
+  }
+
+  /**
+   * @internal Called by `KjCascadeSelectSubPanel` when the cursor leaves
+   * the sub-panel (to anywhere except back into the parent option).
+   * Restarts the same close timer the option's own `mouseleave` would.
+   */
+  _scheduleClose(): void {
+    const delay = this.ctx.subPanelCloseDelayMs();
+    this._closeTimer = setTimeout(() => {
+      if (!this.subPanelOpen()) return;
+      this.ctx.closeSubPanel(this.item.id);
+    }, delay);
+  }
+}

package/src/cascade-select/cascade-select-panel.ts

@@ -0,0 +1,106 @@
+import {
+  Directive,
+  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 { KjAlign, KjSide } from '../primitives/overlay/types';
+import { bodyPortal } from '../primitives/overlay/strategies/mount/body-portal';
+import { anchoredTo } from '../primitives/overlay/strategies/position/anchored-to';
+import { KjListNavigator } from '../primitives/list';
+import { KjCascadeSelect } from './cascade-select-root';
+
+/**
+ * Root panel for a Cascade Select. Composes:
+ * - `KjOverlayPanel` — mount / position / aria wiring (rendered with
+ *   `role="tree"` via the panel-role provider).
+ * - `KjListNavigator` (vertical + activedescendant) — generic Up/Down /
+ *   Home/End / Enter / Space / type-ahead navigation across the
+ *   level-0 options.
+ *
+ * Cascade-specific ArrowRight (open the active option's sub-panel) and
+ * Escape / Tab (close everything) remain handled here because they
+ * carry cascade-specific semantics the generic navigator doesn't
+ * cover.
+ *
+ * @doc-category Core/Data input
+ * @doc
+ * @doc-name cascade-select
+ */
+@Directive({
+  selector: '[kjCascadeSelectPanel]',
+  exportAs: 'kjCascadeSelectPanel',
+  standalone: true,
+  hostDirectives: [
+    { directive: KjOverlayPanel, inputs: ['kjFor'] },
+    {
+      directive: KjListNavigator,
+      inputs: ['kjOrientation', 'kjFocusMode'],
+    },
+  ],
+  providers: [
+    { provide: KJ_OVERLAY_PANEL_ROLE, useValue: 'tree' as const },
+    { provide: KJ_OVERLAY_MOUNT_STRATEGY, useFactory: () => bodyPortal() },
+    { provide: KJ_OVERLAY_POSITION_STRATEGY, useFactory: () => anchoredTo() },
+  ],
+  host: {
+    'role': 'tree',
+    'aria-orientation': 'horizontal',
+    'aria-multiselectable': 'false',
+    'tabindex': '-1',
+    'kjOrientation': 'vertical',
+    'kjFocusMode': 'activedescendant',
+    '(keydown)': 'onKeydown($event)',
+    '(click)': '$event.stopPropagation()',
+  },
+})
+export class KjCascadeSelectPanel {
+  /** @internal — root directive (typed). Owns sub-panel state + option lookup. */
+  private readonly root = inject(KjCascadeSelect);
+  /** @internal — generic list navigator composed via `hostDirectives`. */
+  private readonly nav = inject(KjListNavigator);
+
+  /** Anchored side relative to the trigger. */
+  readonly kjSide = input<KjSide>('bottom');
+  /** Cross-axis alignment relative to the trigger. */
+  readonly kjAlign = input<KjAlign>('start');
+
+  constructor() {
+    const pos = inject(KJ_OVERLAY_POSITION_STRATEGY) as ReturnType<typeof anchoredTo>;
+    pos.configure({ side: this.kjSide, align: this.kjAlign, matchTriggerWidth: 'min' });
+  }
+
+  /**
+   * @internal Cascade-specific keys — ArrowRight opens the active
+   * branch's sub-panel; Escape / Tab dismiss everything. Up/Down /
+   * Home/End / Enter / Space / typeahead all flow through the composed
+   * `KjListNavigator`.
+   */
+  onKeydown(e: KeyboardEvent): void {
+    switch (e.key) {
+      case 'ArrowRight': {
+        e.preventDefault();
+        const activeId = this.nav.activeId();
+        if (!activeId) return;
+        const option = this.root.findOption(activeId);
+        if (option?.isBranch()) this.root.openSubPanel(option.item.id);
+        return;
+      }
+      case 'Escape':
+        e.preventDefault();
+        e.stopPropagation();
+        this.root.hide();
+        this.root.closeAll();
+        return;
+      case 'Tab':
+        this.root.hide();
+        this.root.closeAll();
+        return;
+    }
+  }
+}

package/src/cascade-select/cascade-select-root.ts

@@ -0,0 +1,265 @@
+import {
+  Directive,
+  computed,
+  contentChildren,
+  forwardRef,
+  inject,
+  input,
+  model,
+  output,
+  signal,
+  type Signal,
+  type WritableSignal,
+} from '@angular/core';
+import { KjOverlayController } from '../primitives/overlay/controller';
+import { KJ_SELECT } from '../select/select-root';
+import {
+  KJ_LIST_NAVIGATOR_CONFIG,
+  KjListItem,
+  KjSelectionModel,
+  type KjCompareFn,
+  type KjListNavigatorConfig,
+  type KjListSelectionMode,
+  type KjTreeShape,
+} from '../primitives/list';
+import {
+  KJ_CASCADE_SELECT,
+  type KjCascadeSelectContext,
+} from './cascade-select.context';
+import { KjCascadeSelectOption } from './cascade-select-option';
+
+/**
+ * Root cascade-select container. Implements
+ * {@link KjListNavigatorConfig} (items, value, mode, compareBy,
+ * treeShape, afterSelect) and provides itself under
+ * `KJ_LIST_NAVIGATOR_CONFIG` via `forwardRef`. Each cascade panel +
+ * sub-panel hosts its own `KjListNavigator` (vertical +
+ * activedescendant). All tree-walking logic — branch gating, path
+ * derivation, isLeaf — lives in the shared `KjSelectionModel`, which
+ * auto-derives the tree shape from each `KjListItem.parent` DI pointer.
+ * The root just owns cascade-specific UX: the sub-panel open-chain and
+ * the overlay close-on-commit behavior.
+ *
+ * Like `KjSelect`, the root does NOT inject `KjSelectionModel` at
+ * construction — doing so creates a runtime cycle (the model's
+ * `inject(KJ_LIST_NAVIGATOR_CONFIG)` would resolve to a still-
+ * constructing root). Lazy access via the element `Injector` resolves
+ * the model after construction finishes.
+ *
+ * @example
+ * ```html
+ * <div kjCascadeSelect [(kjValue)]="city">
+ *   <button kjCascadeSelectTrigger #t="kjCascadeSelectTrigger">Pick</button>
+ *   <div kjCascadeSelectPanel [kjFor]="t">
+ *     <div kjCascadeSelectOption [kjValue]="'us'" kjLabel="USA">…</div>
+ *   </div>
+ * </div>
+ * ```
+ *
+ * @doc-category Core/Data input
+ * @doc
+ * @doc-name cascade-select
+ * @doc-is-main
+ * @doc-description Unstyled cascade-select root that implements KjListNavigatorConfig and owns the shared selection model.
+ */
+@Directive({
+  selector: '[kjCascadeSelect]',
+  exportAs: 'kjCascadeSelect',
+  standalone: true,
+  providers: [
+    { provide: KJ_CASCADE_SELECT, useExisting: forwardRef(() => KjCascadeSelect) },
+    { provide: KJ_SELECT, useExisting: forwardRef(() => KjCascadeSelect) },
+    { provide: KJ_LIST_NAVIGATOR_CONFIG, useExisting: forwardRef(() => KjCascadeSelect) },
+    KjSelectionModel,
+    KjOverlayController,
+  ],
+})
+export class KjCascadeSelect implements KjListNavigatorConfig, KjCascadeSelectContext {
+  /** @internal — shared overlay controller; trigger + panel + options share this. */
+  private readonly _controller = inject(KjOverlayController);
+
+  /** Two-way bindable selected leaf value. */
+  readonly kjValue = model<unknown>(undefined);
+
+  /** Two-way bindable path of values from root to selected leaf. */
+  readonly kjCascadePath = model<readonly unknown[]>([]);
+
+  /**
+   * Optional consumer-supplied tree topology. When omitted, the
+   * selection model auto-derives one from each `KjListItem.parent`
+   * pointer (which Angular resolves via the element injector — the
+   * outer cascade option of a sub-panel's contents). Supply this only
+   * when the consumer's data model isn't a faithful match for the
+   * projected DOM (rare).
+   */
+  readonly kjTreeShape = input<KjTreeShape<unknown> | null>(null);
+
+  /** Sub-panel hover-open delay in ms. Default 100 (matches Dropdown Menu). */
+  readonly kjSubPanelOpenDelayMs = input<number>(100);
+
+  /** Sub-panel hover-out close delay in ms. Default 300 (prevents flicker). */
+  readonly kjSubPanelCloseDelayMs = input<number>(300);
+
+  /** Emitted when the active-descendant crosses a level boundary. */
+  readonly kjLevelChange = output<{ levelIndex: number }>();
+
+  // ── KjListNavigatorConfig implementation ──────────────────────────
+  /** All `KjListItem`s under this cascade — source for the navigators. */
+  readonly items = contentChildren(KjListItem, { descendants: true });
+
+  /**
+   * Every projected `KjCascadeSelectOption`. Used by {@link findOption}
+   * to resolve a `KjListItem` id (typically the navigator's active id)
+   * to its wrapping option directive — no `document.getElementById` /
+   * `querySelector` lookups in panel keydown handlers.
+   */
+  private readonly _options = contentChildren(KjCascadeSelectOption, { descendants: true });
+
+  private readonly _optionsById = computed(() => {
+    const map = new Map<string, KjCascadeSelectOption>();
+    for (const o of this._options()) map.set(o.item.id, o);
+    return map;
+  });
+
+  /**
+   * Resolve the `KjCascadeSelectOption` wrapping the given
+   * `KjListItem.id`. Returns `undefined` when no projected option
+   * matches.
+   */
+  findOption(itemId: string): KjCascadeSelectOption | undefined {
+    return this._optionsById().get(itemId);
+  }
+
+  /**
+   * Implements `KjListNavigatorConfig.value`. Shared with `kjValue` so
+   * `KjSelectionModel` reads / writes through the same signal — one
+   * source of truth.
+   */
+  readonly value = this.kjValue as unknown as WritableSignal<
+    unknown | readonly unknown[] | null
+  >;
+
+  /**
+   * Cascade is single-leaf select: exactly one leaf value lives in
+   * `kjValue`. The selection model's `'single'` + tree-shape branch
+   * gate blocks non-leaf commits automatically — branches only toggle
+   * their own sub-panel via `KjCascadeSelectOption.handleClick`.
+   */
+  readonly mode: Signal<KjListSelectionMode> = signal<KjListSelectionMode>('single');
+
+  /** Implements `KjListNavigatorConfig.compareBy`. */
+  readonly compareBy = signal<KjCompareFn<unknown>>(Object.is as KjCompareFn<unknown>);
+
+  /** Re-exposes `kjTreeShape` under the {@link KjListNavigatorConfig} key. */
+  readonly treeShape = this.kjTreeShape;
+
+  /**
+   * Selection model is injected directly. The model uses a {@link
+   * KjSelectionModel.bind} call to receive this root's canonical
+   * signals — that pattern keeps the DI graph acyclic (the model does
+   * not inject `KJ_LIST_NAVIGATOR_CONFIG` back, so providing both on
+   * the same element no longer collides).
+   */
+  private readonly _selection = inject(KjSelectionModel);
+
+  constructor() {
+    this._selection.bind({
+      value:     this.value,
+      items:     this.items,
+      mode:      this.mode,
+      compareBy: this.compareBy,
+      treeShape: this.treeShape,
+    });
+  }
+
+  // ── KjSelectContext-compatible surface ──────────────────────────────
+  /** Open state — drives `KjSelect.open` for downstream consumers. */
+  readonly open = this._controller.isOpen;
+
+  /** Compatibility shim — KjSelect-style single setter. Closes the panel. */
+  select(val: unknown): void {
+    this.kjValue.set(val);
+    this._controller.close('programmatic');
+  }
+
+  /** Compatibility shim — toggles the overlay. */
+  toggle(): void {
+    if (this._controller.isOpen()) this._controller.close('programmatic');
+    else this._controller.open();
+  }
+
+  // ── KjCascadeSelectContext implementation ──────────────────────────
+  private readonly _openSubPanels = signal<readonly string[]>([]);
+
+  /** Path of values from root option to the selected leaf. */
+  readonly path = computed(() => this.kjCascadePath());
+
+  /** Open sub-panel ownerOptionIds (level → level chain). */
+  readonly openSubPanels = this._openSubPanels.asReadonly();
+
+  /** Hover-open delay (ms). */
+  readonly subPanelOpenDelayMs = computed(() => this.kjSubPanelOpenDelayMs());
+  /** Hover-out close delay (ms). */
+  readonly subPanelCloseDelayMs = computed(() => this.kjSubPanelCloseDelayMs());
+
+  /**
+   * Implements `KjListNavigatorConfig.afterSelect`. The selection model
+   * already gated branches before reaching here (see
+   * `KjSelectionModel.canActivate`), so any defined `value` is a leaf
+   * commit: derive the path from the model, surface it on
+   * `kjCascadePath`, close every sub-panel, and dismiss the overlay.
+   */
+  afterSelect(value: unknown, _closeRequested: boolean): void {
+    if (value === undefined) return;
+    this.kjCascadePath.set(this._selection.pathTo(value));
+    this._openSubPanels.set([]);
+    this._controller.close('programmatic');
+  }
+
+  /**
+   * Open the sub-panel chain ending at `ownerOptionId`. Walking the
+   * target's ancestry on every open is the trick that keeps sibling
+   * sub-panels mutually exclusive: any stale entries from a prior
+   * branch get replaced atomically with the fresh chain, so a
+   * mouseleave-queued close timer on a sibling can no longer slice
+   * through the new chain after it fires. The walk also cancels any
+   * pending close timers along the new chain so a brief inter-option
+   * cursor crossing doesn't dismiss a freshly-opened panel.
+   */
+  openSubPanel(ownerOptionId: string): void {
+    const target = this.findOption(ownerOptionId);
+    if (!target) {
+      // Fallback: option not yet registered (rare — pre-content-init).
+      // Append to keep behavior monotonic; the close path is tolerant.
+      this._openSubPanels.update(panels =>
+        panels.includes(ownerOptionId) ? panels : [...panels, ownerOptionId],
+      );
+      return;
+    }
+    const chain: string[] = [];
+    let current: typeof target | null = target;
+    while (current) {
+      current._cancelCloseTimer();
+      chain.unshift(current.item.id);
+      current = current.parentSubPanel?.parentOption ?? null;
+    }
+    this._openSubPanels.set(chain);
+  }
+
+  closeSubPanel(ownerOptionId: string): void {
+    this._openSubPanels.update(panels => {
+      const idx = panels.indexOf(ownerOptionId);
+      if (idx < 0) return panels;
+      return panels.slice(0, idx);
+    });
+  }
+
+  closeAll(): void {
+    this._openSubPanels.set([]);
+  }
+
+  /** Closes the root cascade panel. */
+  hide(): void {
+    this._controller.close('programmatic');
+  }
+}