@kouji-ui/core 0.0.3 → 0.1.1

package/src/icon/icon.directive.ts

@@ -0,0 +1,113 @@
+import { Directive, computed, input } from '@angular/core';
+import { getIconMode } from './icon.mode';
+import { injectKjIconResolver } from './icon.resolver';
+import type { KjIconColor, KjIconSize } from './icon.types';
+
+/**
+ * Renders an icon on its host element via CSS custom properties. Owns icon
+ * accessibility (decorative by default; meaningful when `kjIconLabel` is set).
+ *
+ * @example
+ * ```html
+ * <span [kjIcon]="'settings'"></span>
+ * <span [kjIcon]="'alert-triangle'" [kjIconLabel]="'Warning'"></span>
+ * <span [kjIcon]="'check'" [kjIconColor]="'success'" [kjIconSize]="'lg'"></span>
+ * ```
+ *
+ * @doc-example Gallery
+ *   Browseable Lucide icon grid with a substring filter. Click any tile to
+ *   copy its `<i kjIcon="…">` snippet.
+ *   @doc-file ../../../components/src/icon/icon.gallery.example.ts
+ * @doc-example Usage
+ *   Common icon shapes — decorative inline, meaningful with a label, sized
+ *   variants, and semantic color tokens.
+ *   @doc-file ../../../components/src/icon/icon.usage.example.ts
+ *
+ * @doc-keyboard
+ *   None — the icon directive is non-interactive. Place inside a focusable parent (button/link) for activation semantics.
+ *
+ * @doc-aria
+ *   aria-hidden          — Set to "true" by default (decorative). Removed when [kjIconLabel] is provided
+ *   role="img"           — Set when [kjIconLabel] is provided (meaningful icon)
+ *   aria-label           — Bound to [kjIconLabel] when provided
+ *   data-kj-icon-mode    — Mirrors the resolved mode ("svg" | "font") for theme CSS
+ *
+ * @doc-css-var
+ *   --kj-icon            — CSS-ready resolved icon value (a url() for svg mode or a quoted glyph for font mode). Set by the directive.
+ *   --kj-icon-font       — Font family used in font mode. Consumers set this on a parent when shipping icon fonts.
+ *   --kj-color-icon-*    — Foreground color tokens for [kjIconColor] (muted/primary/success/warning/danger/info).
+ *   --kj-icon-size-*     — Em-relative size tokens for [kjIconSize] (xs/sm/md/lg/xl).
+ *
+ * @doc-touch
+ *   The icon is layout-only and does not require a 44×44 target on its own.
+ *   When the icon is the sole label of an interactive control, the parent
+ *   (`kj-button kjSize="icon"`, `<a>`, etc.) must meet WCAG 2.5.5.
+ *
+ * @doc-a11y
+ *   Decorative by default — `aria-hidden="true"` keeps the icon silent for
+ *   AT. Pass `[kjIconLabel]` only when the icon conveys meaning that is not
+ *   duplicated in adjacent text; this swaps in `role="img"` and the label.
+ *   Color tokens map to `--kj-color-icon-{token}` so theme palettes can
+ *   retarget per-mode without API churn.
+ *
+ * @doc-related button,link,badge
+ *
+ * @doc-category Core/Icon
+ * @doc
+ * @doc-name icon
+ * @doc-description Renders an accessible icon on its host element by name with color and size tokens.
+ * @doc-is-main
+ */
+@Directive({
+  selector: 'span[kjIcon], i[kjIcon]',
+  standalone: true,
+  host: {
+    class: 'kj-icon',
+    '[style.--kj-icon]': 'iconValue()',
+    '[style.color]': 'colorVar()',
+    '[style.font-size]': 'sizeVar()',
+    '[attr.data-kj-icon-mode]': 'mode()',
+    '[attr.aria-hidden]': 'ariaHidden()',
+    '[attr.role]': 'roleAttr()',
+    '[attr.aria-label]': 'ariaLabelAttr()',
+  },
+})
+export class KjIconDirective {
+  private readonly resolve = injectKjIconResolver();
+
+  /** Icon name. Names starting with `@font.` use font mode. */
+  readonly kjIcon = input.required<string>();
+
+  /**
+   * Accessible name. When set, the icon is treated as meaningful:
+   * `role="img"`, `aria-label` set, `aria-hidden` removed. When unset
+   * (the default), the icon is decorative and `aria-hidden="true"`.
+   */
+  readonly kjIconLabel = input<string | null>(null);
+
+  /** Semantic color token. Default `null` means inherit (CSS `currentColor`). */
+  readonly kjIconColor = input<KjIconColor | null>(null);
+
+  /** Size token. Default `null` means inherit from surrounding text. */
+  readonly kjIconSize = input<KjIconSize | null>(null);
+
+  protected readonly mode = computed(() => getIconMode(this.kjIcon()));
+  protected readonly iconValue = computed(() => this.resolve(this.kjIcon()));
+
+  protected readonly ariaHidden = computed(() =>
+    this.kjIconLabel() ? null : 'true',
+  );
+  protected readonly roleAttr = computed(() =>
+    this.kjIconLabel() ? 'img' : null,
+  );
+  protected readonly ariaLabelAttr = computed(() => this.kjIconLabel());
+
+  protected readonly colorVar = computed(() => {
+    const c = this.kjIconColor();
+    return c && c !== 'inherit' ? `var(--kj-color-icon-${c})` : null;
+  });
+  protected readonly sizeVar = computed(() => {
+    const s = this.kjIconSize();
+    return s ? `var(--kj-icon-size-${s})` : null;
+  });
+}

package/src/icon/icon.mode.spec.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+import { getIconMode } from './icon.mode';
+
+describe('getIconMode', () => {
+  it('returns "font" when name starts with "@font."', () => {
+    expect(getIconMode('@font.fa-cog')).toBe('font');
+  });
+
+  it('returns "svg" for plain names', () => {
+    expect(getIconMode('settings')).toBe('svg');
+  });
+
+  it('returns "svg" for hyphenated names', () => {
+    expect(getIconMode('alert-triangle')).toBe('svg');
+  });
+
+  it('returns "svg" for namespaced names that are not @font', () => {
+    expect(getIconMode('lucide:settings')).toBe('svg');
+  });
+
+  it('returns "svg" for empty string', () => {
+    expect(getIconMode('')).toBe('svg');
+  });
+
+  it('returns "svg" for "@font" with no trailing dot', () => {
+    // Strict: must be exactly "@font." prefix; "@fontawesome" stays svg.
+    expect(getIconMode('@fontawesome')).toBe('svg');
+  });
+});

package/src/icon/icon.mode.ts

@@ -0,0 +1,23 @@
+// packages/core/src/icon/icon.mode.ts
+
+/**
+ * Render mode inferred from an icon name.
+ * @doc
+ * @doc-name icon
+ * @doc-order 14
+ */
+export type IconMode = 'svg' | 'font';
+
+const FONT_PREFIX = '@font.';
+
+/**
+ * Infer render mode from icon name. Names starting with `@font.` use the
+ * font code path (CSS `content`); everything else uses the svg/css-mask
+ * code path.
+ * @doc
+ * @doc-name icon
+ * @doc-order 5
+ */
+export function getIconMode(name: string): IconMode {
+  return name.startsWith(FONT_PREFIX) ? 'font' : 'svg';
+}

package/src/icon/icon.providers.spec.ts

@@ -0,0 +1,63 @@
+import { TestBed } from '@angular/core/testing';
+import { describe, expect, it } from 'vitest';
+import {
+  provideIconLoader,
+  provideIconResolver,
+  provideIcons,
+} from './icon.providers';
+import {
+  KJ_ICON_LOADER,
+  KJ_ICON_REGISTRY,
+  KJ_ICON_RESOLVER,
+} from './icon.tokens';
+
+describe('provideIcons', () => {
+  it('seeds the registry with the given map', () => {
+    TestBed.configureTestingModule({
+      providers: [provideIcons({ settings: 'url("a")', save: 'url("b")' })],
+    });
+    const reg = TestBed.inject(KJ_ICON_REGISTRY);
+    expect(reg()).toEqual({ settings: 'url("a")', save: 'url("b")' });
+  });
+
+  it('merges multiple provideIcons calls (last wins on collision)', () => {
+    TestBed.configureTestingModule({
+      providers: [
+        provideIcons({ settings: 'url("first")', save: 'url("b")' }),
+        provideIcons({ settings: 'url("second")', trash: 'url("c")' }),
+      ],
+    });
+    const reg = TestBed.inject(KJ_ICON_REGISTRY);
+    expect(reg()).toEqual({
+      settings: 'url("second")',
+      save: 'url("b")',
+      trash: 'url("c")',
+    });
+  });
+
+  it('default registry is empty when no provideIcons is called', () => {
+    TestBed.configureTestingModule({ providers: [] });
+    const reg = TestBed.inject(KJ_ICON_REGISTRY);
+    expect(reg()).toEqual({});
+  });
+});
+
+describe('provideIconResolver', () => {
+  it('overrides the default resolver', () => {
+    TestBed.configureTestingModule({
+      providers: [provideIconResolver((n) => `url("/icons/${n}.svg")`)],
+    });
+    const fn = TestBed.inject(KJ_ICON_RESOLVER);
+    expect(fn('settings')).toBe('url("/icons/settings.svg")');
+  });
+});
+
+describe('provideIconLoader', () => {
+  it('registers an async loader', async () => {
+    const loader = async (n: string) => `url("loaded:${n}")`;
+    TestBed.configureTestingModule({ providers: [provideIconLoader(loader)] });
+    const fn = TestBed.inject(KJ_ICON_LOADER);
+    expect(fn).not.toBeNull();
+    await expect(fn!('x')).resolves.toBe('url("loaded:x")');
+  });
+});

package/src/icon/icon.providers.ts

@@ -0,0 +1,47 @@
+import {
+  type EnvironmentProviders,
+  makeEnvironmentProviders,
+} from '@angular/core';
+import type { IconLoader, IconResolver } from './icon.types';
+import {
+  KJ_ICON_ENTRIES,
+  KJ_ICON_LOADER,
+  KJ_ICON_RESOLVER,
+} from './icon.tokens';
+
+/**
+ * Register a map of icon names to CSS-ready values. Call multiple times to
+ * compose icon sets; later calls win on key collision.
+ * @doc
+ * @doc-name icon
+ * @doc-order 1
+ */
+export function provideIcons(
+  map: Record<string, string>,
+): EnvironmentProviders {
+  return makeEnvironmentProviders([
+    { provide: KJ_ICON_ENTRIES, useValue: map, multi: true },
+  ]);
+}
+
+/**
+ * Override the synchronous fallback resolver used when a name is not in the
+ * registry and no async loader is configured.
+ * @doc
+ * @doc-name icon
+ * @doc-order 2
+ */
+export function provideIconResolver(fn: IconResolver): EnvironmentProviders {
+  return makeEnvironmentProviders([{ provide: KJ_ICON_RESOLVER, useValue: fn }]);
+}
+
+/**
+ * Register an async loader. When present, missing icons are loaded via this
+ * function and cached into the registry.
+ * @doc
+ * @doc-name icon
+ * @doc-order 3
+ */
+export function provideIconLoader(fn: IconLoader): EnvironmentProviders {
+  return makeEnvironmentProviders([{ provide: KJ_ICON_LOADER, useValue: fn }]);
+}

package/src/icon/icon.resolver.spec.ts

@@ -0,0 +1,96 @@
+import { Injector, runInInjectionContext } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { Provider, EnvironmentProviders } from '@angular/core';
+import { provideIcons, provideIconLoader, provideIconResolver } from './icon.providers';
+import { injectKjIconResolver } from './icon.resolver';
+
+function makeResolver(providers: (Provider | EnvironmentProviders)[]) {
+  TestBed.configureTestingModule({ providers });
+  const injector = TestBed.inject(Injector);
+  return runInInjectionContext(injector, () => injectKjIconResolver());
+}
+
+describe('injectKjIconResolver', () => {
+  beforeEach(() => TestBed.resetTestingModule());
+
+  describe('registry path', () => {
+    it('returns the registry value when name is registered', () => {
+      const resolve = makeResolver([
+        provideIcons({ settings: 'url("a")' }),
+      ]);
+      expect(resolve('settings')).toBe('url("a")');
+    });
+  });
+
+  describe('fallback resolver path (no loader)', () => {
+    it('falls back to KJ_ICON_RESOLVER when name is missing', () => {
+      const resolve = makeResolver([
+        provideIconResolver((n) => `url("/icons/${n}.svg")`),
+      ]);
+      expect(resolve('missing')).toBe('url("/icons/missing.svg")');
+    });
+
+    it('default resolver returns name unchanged', () => {
+      const resolve = makeResolver([]);
+      expect(resolve('missing')).toBe('missing');
+    });
+  });
+
+  describe('loader path', () => {
+    it('returns null while load is pending, then fills registry on success', async () => {
+      let resolveLoad: (v: string) => void;
+      const loader = vi.fn(
+        (_n: string) =>
+          new Promise<string>((res) => {
+            resolveLoad = (v) => res(v);
+          }),
+      );
+      const resolve = makeResolver([provideIconLoader(loader)]);
+
+      expect(resolve('settings')).toBeNull();
+      expect(loader).toHaveBeenCalledTimes(1);
+
+      // Concurrent call must NOT trigger a second load (dedupe).
+      expect(resolve('settings')).toBeNull();
+      expect(loader).toHaveBeenCalledTimes(1);
+
+      resolveLoad!('url("loaded")');
+      await Promise.resolve();
+      await Promise.resolve();
+
+      expect(resolve('settings')).toBe('url("loaded")');
+    });
+
+    it('on loader rejection, removes pending so a subsequent call retries', async () => {
+      let calls = 0;
+      const loader = vi.fn(async (_n: string) => {
+        calls++;
+        if (calls === 1) throw new Error('boom');
+        return 'url("ok")';
+      });
+      const resolve = makeResolver([provideIconLoader(loader)]);
+
+      expect(resolve('x')).toBeNull();
+      await Promise.resolve();
+      await Promise.resolve();
+      expect(resolve('x')).toBeNull();
+      expect(loader).toHaveBeenCalledTimes(2);
+      await Promise.resolve();
+      await Promise.resolve();
+      expect(resolve('x')).toBe('url("ok")');
+    });
+
+    it('loader path takes precedence over fallback resolver', async () => {
+      const loader = async () => 'url("from-loader")';
+      const resolve = makeResolver([
+        provideIconLoader(loader),
+        provideIconResolver(() => 'url("from-fallback")'),
+      ]);
+      expect(resolve('x')).toBeNull();
+      await Promise.resolve();
+      await Promise.resolve();
+      expect(resolve('x')).toBe('url("from-loader")');
+    });
+  });
+});

package/src/icon/icon.resolver.ts

@@ -0,0 +1,49 @@
+import { inject } from '@angular/core';
+import {
+  KJ_ICON_LOADER,
+  KJ_ICON_REGISTRY,
+  KJ_ICON_RESOLVER,
+} from './icon.tokens';
+
+/**
+ * Returns a function that resolves an icon name to a CSS-ready value, or
+ * `null` while an async load is pending.
+ *
+ * Lookup order:
+ * 1. `KJ_ICON_REGISTRY` (eager)
+ * 2. `KJ_ICON_LOADER` (async; fills registry on success, returns `null` while pending)
+ * 3. `KJ_ICON_RESOLVER` (sync default, e.g. URL synthesis)
+ *
+ * Must be called in an injection context.
+ * @doc
+ * @doc-name icon
+ * @doc-order 4
+ */
+export function injectKjIconResolver(): (name: string) => string | null {
+  const registry = inject(KJ_ICON_REGISTRY);
+  const loader = inject(KJ_ICON_LOADER);
+  const fallback = inject(KJ_ICON_RESOLVER);
+  const pending = new Set<string>();
+
+  return (name: string): string | null => {
+    const map = registry();
+    if (Object.prototype.hasOwnProperty.call(map, name)) return map[name];
+
+    if (loader) {
+      if (!pending.has(name)) {
+        pending.add(name);
+        Promise.resolve(loader(name))
+          .then((value) => {
+            registry.update((m) => ({ ...m, [name]: value }));
+            pending.delete(name);
+          })
+          .catch(() => {
+            pending.delete(name);
+          });
+      }
+      return null;
+    }
+
+    return fallback(name);
+  };
+}

package/src/icon/icon.tokens.ts

@@ -0,0 +1,88 @@
+import { InjectionToken, type WritableSignal, inject, signal } from '@angular/core';
+import type { IconLoader, IconResolver } from './icon.types';
+
+/**
+ * Multi-provider entries contributed by `provideIcons(...)`. Each entry is a
+ * `Record<name, cssReadyValue>`. The registry factory merges all entries at
+ * injection time.
+ *
+ * Internal — consumers use `provideIcons(...)`.
+ * @internal
+ */
+export const KJ_ICON_ENTRIES = new InjectionToken<Record<string, string>>(
+  'KJ_ICON_ENTRIES',
+);
+
+/**
+ * Runtime icon registry. A writable signal so the async loader can fill in
+ * resolved icons and any consuming directive's computed re-evaluates.
+ *
+ * Stored values are CSS-ready: `url("...")` for svg mode, quoted glyphs for
+ * font mode. Adapter authors are responsible for the wrapping.
+ * @doc
+ * @doc-name icon
+ * @doc-order 6
+ */
+export const KJ_ICON_REGISTRY = new InjectionToken<
+  WritableSignal<Record<string, string>>
+>('KJ_ICON_REGISTRY', {
+  providedIn: 'root',
+  factory: () => {
+    const entries = inject(KJ_ICON_ENTRIES, { optional: true }) as
+      | Record<string, string>[]
+      | Record<string, string>
+      | null;
+    const list: Record<string, string>[] = Array.isArray(entries)
+      ? entries
+      : entries
+        ? [entries]
+        : [];
+    const merged = list.reduce<Record<string, string>>(
+      (acc, m) => ({ ...acc, ...m }),
+      {},
+    );
+    return signal<Record<string, string>>(merged);
+  },
+});
+
+/**
+ * Synchronous fallback resolver. Called when a name is not in the registry
+ * and no async loader is configured. Returns a CSS-ready string.
+ *
+ * Default: returns the name unchanged.
+ * @doc
+ * @doc-name icon
+ * @doc-order 7
+ */
+export const KJ_ICON_RESOLVER = new InjectionToken<IconResolver>(
+  'KJ_ICON_RESOLVER',
+  { providedIn: 'root', factory: () => (name: string) => name },
+);
+
+/**
+ * Optional async loader. When set, missing icons are loaded via this fn and
+ * the result is written into `KJ_ICON_REGISTRY`. While loading, the
+ * directive renders nothing for that name. If unset, the resolver fallback
+ * is used instead.
+ * @doc
+ * @doc-name icon
+ * @doc-order 8
+ */
+export const KJ_ICON_LOADER = new InjectionToken<IconLoader | null>(
+  'KJ_ICON_LOADER',
+  { providedIn: 'root', factory: () => null },
+);
+
+/**
+ * Resolvable path to the kouji icon stylesheet.
+ *
+ * ```ts
+ * import { KJ_ICON_CSS_PATH } from '@kouji-ui/core';
+ * // or import the file directly:
+ * import '@kouji-ui/core/icon/icon.css';
+ * ```
+ * @doc
+ * @doc-name icon
+ * @doc-order 9
+ */
+export const KJ_ICON_CSS_PATH = '@kouji-ui/core/icon/icon.css' as const;

package/src/icon/icon.types.ts

@@ -0,0 +1,48 @@
+// packages/core/src/icon/icon.types.ts
+
+/**
+ * Resolves an icon name to a CSS-ready value (e.g. `url("data:...")` for svg
+ * mode, or a quoted glyph like `"\\f013"` for font mode). Synchronous.
+ *
+ * Used as a fallback when an icon is not in the registry and no async loader
+ * is configured.
+ * @doc
+ * @doc-name icon
+ * @doc-order 10
+ */
+export type IconResolver = (name: string) => string;
+
+/**
+ * Asynchronously resolves an icon name to a CSS-ready value. Result is
+ * memoized into the registry so subsequent reads are synchronous.
+ * @doc
+ * @doc-name icon
+ * @doc-order 11
+ */
+export type IconLoader = (name: string) => Promise<string>;
+
+/**
+ * Semantic color tokens for `[kjIconColor]`. Maps to
+ * `var(--kj-color-icon-{token})`. `'inherit'` is the default and means
+ * "use whatever the surrounding text color is" (CSS `currentColor`).
+ * @doc
+ * @doc-name icon
+ * @doc-order 12
+ */
+export type KjIconColor =
+  | 'inherit'
+  | 'muted'
+  | 'primary'
+  | 'success'
+  | 'warning'
+  | 'danger'
+  | 'info';
+
+/**
+ * Size tokens for `[kjIconSize]`. Maps to `var(--kj-icon-size-{token})`.
+ * Sizes are em-relative so an icon scales with surrounding text by default.
+ * @doc
+ * @doc-name icon
+ * @doc-order 13
+ */
+export type KjIconSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';

package/src/icon/index.ts

@@ -0,0 +1,21 @@
+export { getIconMode, type IconMode } from './icon.mode';
+export type {
+  IconResolver,
+  IconLoader,
+  KjIconColor,
+  KjIconSize,
+} from './icon.types';
+export {
+  KJ_ICON_ENTRIES,
+  KJ_ICON_REGISTRY,
+  KJ_ICON_RESOLVER,
+  KJ_ICON_LOADER,
+  KJ_ICON_CSS_PATH,
+} from './icon.tokens';
+export {
+  provideIcons,
+  provideIconResolver,
+  provideIconLoader,
+} from './icon.providers';
+export { injectKjIconResolver } from './icon.resolver';
+export { KjIconDirective } from './icon.directive';

package/src/input/input.ts

@@ -1,4 +1,4 @@
-import { Directive, ElementRef, effect, inject, input } from '@angular/core';
+import { Directive, ElementRef, effect, inject, input } from '@angular/core';
 import { KjDisabled, KjFocusRing, KjFormControl } from '../primitives';
 
 /**
@@ -45,7 +45,10 @@ import { KjDisabled, KjFocusRing, KjFormControl } from '../primitives';
  *         emailCtrl = new FormControl('', [Validators.email, Validators.required]);
  *       }
  *    ```
- * @category Core/Inputs
+ * @doc-category Core/Inputs
+ * @doc-name input
+ * @doc-description Adds Angular forms integration, invalid and disabled state, and a focus ring to a native input.
+ * @doc-is-main
  */
 @Directive({
   selector: '[kjInput]',
@@ -72,9 +75,15 @@ export class KjInput {
 
   constructor() {
     // Reflect the CVA value signal back to the native input element.
+    // Skip when the form control's value is null/undefined so external [value]
+    // bindings (template attribute, parent component) are preserved when no
+    // ngModel/formControl is wired. When a form is wired, callers clear via
+    // setValue('') rather than setValue(null), preserving the clear-on-empty
+    // behavior.
     effect(() => {
       const val = this.formCtrl.value();
-      this.el.nativeElement.value = val == null ? '' : String(val);
+      if (val == null) return;
+      this.el.nativeElement.value = String(val);
     });
   }
 }

package/src/input-group/index.ts

@@ -0,0 +1,3 @@
+export * from './input-group';
+export * from './input-group-addon';
+export * from './input-group.context';