@kouji-ui/core 0.0.3 → 0.1.1

package/src/primitives/overlay/wrapper.ts

@@ -0,0 +1,50 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  DestroyRef,
+  ViewContainerRef,
+  ViewEncapsulation,
+  inject,
+  viewChild,
+} from '@angular/core';
+import { KjOverlayController } from './controller';
+
+/**
+ * Per-overlay wrapper component. Owns its DOM, its child views (backdrop +
+ * panel), and disposes the controller when destroyed. Created by
+ * `KjOverlayBuilder` for each open overlay; mounted into the singleton
+ * `.kj-overlay-container`. Sibling order in the container resolves
+ * stacking among open overlays — last opened wins.
+ *
+ * Internal: not exported as part of the public API surface.
+ *
+ * @doc-category Core/Overlay
+ * @doc
+ * @doc-name overlay-wrapper
+ * @doc-is-main
+ * @doc-description Hosts one overlay's DOM and tears down its backdrop, panel, and controller together.
+ */
+@Component({
+  selector: 'kj-overlay-wrapper',
+  standalone: true,
+  template: `
+    <ng-container #backdropAnchor />
+    <ng-container #panelAnchor />
+  `,
+  host: { class: 'kj-overlay-wrapper' },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+})
+export class KjOverlayWrapper {
+  /** ViewContainerRef anchored to the backdrop slot. */
+  readonly backdropAnchor = viewChild.required('backdropAnchor', { read: ViewContainerRef });
+  /** ViewContainerRef anchored to the panel slot. */
+  readonly panelAnchor = viewChild.required('panelAnchor', { read: ViewContainerRef });
+  readonly controller = inject(KjOverlayController);
+
+  constructor() {
+    // Cascade cleanup: destroying the wrapper component disposes the
+    // controller (strategy detach chain) — no manual bookkeeping needed.
+    inject(DestroyRef).onDestroy(() => this.controller.dispose());
+  }
+}

package/src/primitives/signals/deep-signal.ts

@@ -0,0 +1,109 @@
+import { computed, isSignal, Signal, untracked } from '@angular/core';
+
+/**
+ * Recursively narrowed signal view of a record. The root behaves like any
+ * `Signal<T>` (callable, returns the whole value), and each plain-record
+ * property is exposed as a child signal — recursively, so deeply-nested
+ * record fields stay reactive without manually wiring `computed()` calls.
+ *
+ * Implementation is a near-direct port of @ngrx/signals' `toDeepSignal`
+ * (see {@link https://github.com/ngrx/platform/blob/a469cbf015628f30fe1fd2a995d6289cdfc26285/modules/signals/src/deep-signal.ts}).
+ * We inline it here to avoid the @ngrx/signals dependency for a single
+ * helper. Credit: NgRx contributors, MIT.
+ */
+export type DeepSignal<T> = Signal<T> &
+  (IsKnownRecord<T> extends true
+    ? Readonly<{
+        [K in keyof T]: IsKnownRecord<T[K]> extends true
+          ? DeepSignal<T[K]>
+          : Signal<T[K]>;
+      }>
+    : unknown);
+
+type IsKnownRecord<T> = T extends object
+  ? T extends
+      | readonly unknown[]
+      | Set<unknown>
+      | Map<unknown, unknown>
+      | WeakSet<object>
+      | WeakMap<object, unknown>
+      | Date
+      | RegExp
+      | Promise<unknown>
+      | Error
+      | ((...args: never) => unknown)
+    ? false
+    : true
+  : false;
+
+const DEEP_SIGNAL = Symbol('kj.deep-signal');
+
+/**
+ * Wraps a `Signal<T>` so that `result.foo` returns a child `Signal<T['foo']>`
+ * (lazily memoised), recursively for nested plain records. The root proxy is
+ * still callable — `result()` returns the full `T`.
+ *
+ * @example
+ * ```ts
+ * const root = signal({ a: 1, b: { c: 'x' } });
+ * const deep = toDeepSignal(root.asReadonly());
+ * deep();          // { a: 1, b: { c: 'x' } }
+ * deep.a();        // 1
+ * deep.b.c();      // 'x'
+ * ```
+ */
+export function toDeepSignal<T>(source: Signal<T>): DeepSignal<T> {
+  return new Proxy(source as Signal<T> & Record<PropertyKey, unknown>, {
+    has(target, prop): boolean {
+      return !!(this.get!(target, prop, undefined) as unknown);
+    },
+    get(target, prop) {
+      const value = untracked(target as Signal<T>);
+      if (!isRecord(value) || !(prop in value)) {
+        const existing = target[prop];
+        if (isSignal(existing) && (existing as { [DEEP_SIGNAL]?: true })[DEEP_SIGNAL]) {
+          delete target[prop];
+        }
+        return target[prop];
+      }
+      if (!isSignal(target[prop])) {
+        const child = computed(() => (target as Signal<Record<PropertyKey, unknown>>)()[prop]);
+        (child as { [DEEP_SIGNAL]?: true })[DEEP_SIGNAL] = true;
+        Object.defineProperty(target, prop, {
+          value: child,
+          configurable: true,
+        });
+      }
+      return toDeepSignal(target[prop] as Signal<unknown>);
+    },
+  }) as DeepSignal<T>;
+}
+
+const nonRecords: ReadonlyArray<new (...args: never[]) => unknown> = [
+  WeakSet,
+  WeakMap,
+  Promise,
+  Date,
+  Error,
+  RegExp,
+  ArrayBuffer,
+  DataView,
+  Function,
+];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object' || isIterable(value)) {
+    return false;
+  }
+  let proto = Object.getPrototypeOf(value);
+  if (proto === Object.prototype) return true;
+  while (proto && proto !== Object.prototype) {
+    if (nonRecords.includes(proto.constructor)) return false;
+    proto = Object.getPrototypeOf(proto);
+  }
+  return proto === Object.prototype;
+}
+
+function isIterable(value: unknown): value is Iterable<unknown> {
+  return typeof (value as { [Symbol.iterator]?: unknown })?.[Symbol.iterator] === 'function';
+}

package/src/primitives/signals/index.ts

@@ -0,0 +1 @@
+export { toDeepSignal, type DeepSignal } from './deep-signal';

package/src/progress-bar/config.ts

@@ -0,0 +1,48 @@
+import { InjectionToken, Provider } from '@angular/core';
+
+/**
+ * Configurable preset shape for `KjProgressBar`. Mirrors `KjButtonConfig` /
+ * `KjAlertConfig`: variants and sizes are validated against the consumer
+ * application's preset (or extended via `provideKjProgressBar`).
+ */
+export interface KjProgressBarConfig {
+  variants: string[];
+  sizes: string[];
+  defaults: { variant: string; size: string };
+}
+
+/**
+ * Default Progress Bar presets shipped by kouji-ui. Exported so consumers can
+ * spread when extending: `[...KJ_PROGRESS_BAR_DEFAULTS.variants, 'brand']`.
+ */
+export const KJ_PROGRESS_BAR_DEFAULTS: KjProgressBarConfig = {
+  variants: ['primary', 'success', 'warning', 'error'],
+  sizes: ['xs', 'sm', 'md', 'lg'],
+  defaults: { variant: 'primary', size: 'md' },
+};
+
+/**
+ * DI token for the active Progress Bar presets. Default factory yields
+ * `KJ_PROGRESS_BAR_DEFAULTS`. Override via `provideKjProgressBar(…)` at
+ * application or component scope.
+ */
+export const KJ_PROGRESS_BAR_CONFIG = new InjectionToken<KjProgressBarConfig>(
+  'kj.progress-bar.config',
+  { factory: () => KJ_PROGRESS_BAR_DEFAULTS },
+);
+
+/**
+ * Configures the Progress Bar presets for the enclosing injector. Replaces
+ * (does not merge) `variants` and `sizes`; spread
+ * `KJ_PROGRESS_BAR_DEFAULTS.variants` to extend.
+ */
+export function provideKjProgressBar(
+  config: Partial<KjProgressBarConfig>,
+): Provider[] {
+  return [
+    {
+      provide: KJ_PROGRESS_BAR_CONFIG,
+      useValue: { ...KJ_PROGRESS_BAR_DEFAULTS, ...config },
+    },
+  ];
+}

package/src/progress-bar/index.ts

@@ -0,0 +1,12 @@
+export { KjProgressBar } from './progress-bar';
+export { KjProgressBarFill } from './progress-bar-fill';
+export {
+  KJ_PROGRESS_BAR,
+  type KjProgressBarContext,
+} from './progress-bar.context';
+export {
+  KJ_PROGRESS_BAR_CONFIG,
+  KJ_PROGRESS_BAR_DEFAULTS,
+  provideKjProgressBar,
+  type KjProgressBarConfig,
+} from './config';

package/src/progress-bar/progress-bar-fill.ts

@@ -0,0 +1,37 @@
+import { Directive, inject } from '@angular/core';
+
+import { KJ_PROGRESS_BAR } from './progress-bar.context';
+
+/**
+ * Inner fill / indicator child for `[kjProgressBar]`. Reads
+ * `KJ_PROGRESS_BAR.fraction` and re-emits `--kj-progress-fraction` plus
+ * `data-indeterminate` on its own host so themes can target the inner
+ * element directly without traversing the parent.
+ *
+ * The directive sets nothing visual — themes own the actual `transform` /
+ * `width` and the indeterminate stripe animation. Re-exposing the CSS
+ * variable (and the `data-indeterminate` branch attribute) at the named
+ * fill element saves consumers a CSS selector hop and gives themes a
+ * stable hook for the inner node.
+ *
+ * @example
+ * ```html
+ * <div kjProgressBar [kjValue]="progress()">
+ *   <div kjProgressBarFill></div>
+ * </div>
+ * ```
+ * @doc-category Core/Feedback
+ * @doc
+ * @doc-name progress-bar
+ */
+@Directive({
+  selector: '[kjProgressBarFill]',
+  standalone: true,
+  host: {
+    '[style.--kj-progress-fraction]': 'ctx.fraction()',
+    '[attr.data-indeterminate]': 'ctx.indeterminate() ? "true" : null',
+  },
+})
+export class KjProgressBarFill {
+  protected readonly ctx = inject(KJ_PROGRESS_BAR);
+}

package/src/progress-bar/progress-bar.context.ts

@@ -0,0 +1,34 @@
+import { InjectionToken, Signal } from '@angular/core';
+
+/**
+ * Shared state surfaced by `KjProgressBar` for `KjProgressBarFill` (and any
+ * consumer-side child directives) to read.
+ *
+ * The root directive owns all derivations: `value` is the raw input,
+ * `clampedValue` enforces `[min, max]`, `fraction` is the `0..1` reading the
+ * fill consumes for CSS, and `valuenow` is the rounded integer the host emits
+ * as `aria-valuenow`. `null` flows through every derived signal in
+ * indeterminate mode so the fill knows to stop reading the fraction (and
+ * themes can branch on `data-indeterminate`).
+ */
+export interface KjProgressBarContext {
+  /** Raw value as provided, possibly null (indeterminate). */
+  readonly value: Signal<number | null>;
+  /** Clamped value in `[min, max]`, or `null` if indeterminate. */
+  readonly clampedValue: Signal<number | null>;
+  /** `0..1` fraction for CSS, or `null` if indeterminate. */
+  readonly fraction: Signal<number | null>;
+  /** Rounded integer for `aria-valuenow`, or `null` if indeterminate. */
+  readonly valuenow: Signal<number | null>;
+  /** True iff value is `null` (indeterminate mode). */
+  readonly indeterminate: Signal<boolean>;
+  /** `aria-valuemin` as provided. */
+  readonly min: Signal<number>;
+  /** `aria-valuemax` as provided. */
+  readonly max: Signal<number>;
+}
+
+/** Injection token for `KjProgressBarContext`. */
+export const KJ_PROGRESS_BAR = new InjectionToken<KjProgressBarContext>(
+  'KjProgressBar',
+);