@kouji-ui/core 0.0.2

package/src/tooltip/tooltip.spec.ts

@@ -0,0 +1,104 @@
+import { render, fireEvent } from '@testing-library/angular';
+import { axe, toHaveNoViolations } from 'jest-axe';
+import { KjTooltipContent, KjTooltipTrigger } from './tooltip';
+
+expect.extend(toHaveNoViolations);
+const imports = [KjTooltipTrigger, KjTooltipContent];
+
+// [kjTooltipTrigger]="t" is a property binding — it does not appear as a DOM attribute.
+// Select the trigger element by its tag or by aria-describedby (always set per WAI-ARIA spec).
+// Select the content element by [kjTooltipContent] which IS a static directive attribute.
+
+describe('KjTooltipContent + KjTooltipTrigger', () => {
+  it('content hidden by default', async () => {
+    const { container } = await render(
+      `<button [kjTooltipTrigger]="t">Hover</button>
+       <span #t kjTooltipContent [kjTooltipDelay]="0" [kjTooltipHideDelay]="0">Tip</span>`,
+      { imports },
+    );
+    expect(container.querySelector('[kjTooltipContent]')).toHaveAttribute('hidden', '');
+  });
+
+  it('content has role=tooltip by default', async () => {
+    const { container } = await render(
+      `<button [kjTooltipTrigger]="t">Hover</button>
+       <span #t kjTooltipContent [kjTooltipDelay]="0">Tip</span>`,
+      { imports },
+    );
+    expect(container.querySelector('[kjTooltipContent]')).toHaveAttribute('role', 'tooltip');
+  });
+
+  it('shows on mouseenter (no delay)', async () => {
+    const { container } = await render(
+      `<button [kjTooltipTrigger]="t">Hover</button>
+       <span #t kjTooltipContent [kjTooltipDelay]="0" [kjTooltipHideDelay]="0">Tip</span>`,
+      { imports },
+    );
+    fireEvent.mouseEnter(container.querySelector('button')!);
+    expect(container.querySelector('[kjTooltipContent]')).not.toHaveAttribute('hidden');
+  });
+
+  it('hides on mouseleave (no delay)', async () => {
+    const { container } = await render(
+      `<button [kjTooltipTrigger]="t">Hover</button>
+       <span #t kjTooltipContent [kjTooltipDelay]="0" [kjTooltipHideDelay]="0">Tip</span>`,
+      { imports },
+    );
+    fireEvent.mouseEnter(container.querySelector('button')!);
+    fireEvent.mouseLeave(container.querySelector('button')!);
+    expect(container.querySelector('[kjTooltipContent]')).toHaveAttribute('hidden', '');
+  });
+
+  it('hides on Escape key', async () => {
+    const { container } = await render(
+      `<button [kjTooltipTrigger]="t">Hover</button>
+       <span #t kjTooltipContent [kjTooltipDelay]="0">Tip</span>`,
+      { imports },
+    );
+    fireEvent.mouseEnter(container.querySelector('button')!);
+    fireEvent.keyDown(container.querySelector('button')!, { key: 'Escape' });
+    expect(container.querySelector('[kjTooltipContent]')).toHaveAttribute('hidden', '');
+  });
+
+  it('hides on blur', async () => {
+    const { container } = await render(
+      `<button [kjTooltipTrigger]="t">Hover</button>
+       <span #t kjTooltipContent [kjTooltipDelay]="0" [kjTooltipHideDelay]="0">Tip</span>`,
+      { imports },
+    );
+    fireEvent.focus(container.querySelector('button')!);
+    fireEvent.blur(container.querySelector('button')!);
+    expect(container.querySelector('[kjTooltipContent]')).toHaveAttribute('hidden', '');
+  });
+
+  it('trigger has aria-describedby wired to content id always', async () => {
+    const { container } = await render(
+      `<button [kjTooltipTrigger]="t">Info</button>
+       <span #t kjTooltipContent [kjTooltipDelay]="0">Info text</span>`,
+      { imports },
+    );
+    const trigger = container.querySelector('button')!;
+    const content = container.querySelector('[kjTooltipContent]')!;
+    expect(trigger.getAttribute('aria-describedby')).toBeTruthy();
+    expect(trigger.getAttribute('aria-describedby')).toBe(content.id);
+  });
+
+  it('role can be customised', async () => {
+    const { container } = await render(
+      `<button [kjTooltipTrigger]="t">X</button>
+       <span #t kjTooltipContent kjTooltipRole="note" [kjTooltipDelay]="0">Note</span>`,
+      { imports },
+    );
+    expect(container.querySelector('[kjTooltipContent]')).toHaveAttribute('role', 'note');
+  });
+
+  it('passes axe audit when shown', async () => {
+    const { container } = await render(
+      `<button [kjTooltipTrigger]="t">Info</button>
+       <span #t kjTooltipContent [kjTooltipDelay]="0">Info text</span>`,
+      { imports },
+    );
+    fireEvent.mouseEnter(container.querySelector('button')!);
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});

package/src/tooltip/tooltip.ts

@@ -0,0 +1,129 @@
+import { Directive, ElementRef, inject, input, signal } from '@angular/core';
+
+/** Preferred side for the tooltip relative to its trigger. */
+export type KjTooltipSide = 'top' | 'bottom' | 'left' | 'right';
+
+let _tooltipIdCounter = 0;
+
+/** Maps a tooltip content element to its directive instance. */
+const _tooltipRegistry = new WeakMap<Element, KjTooltipContent>();
+
+/**
+ * Tooltip content panel. Owns all configuration and visibility state.
+ * Pair with `[kjTooltipTrigger]` — pass the native element reference using `#myTip` (no `exportAs` needed).
+ *
+ * Automatically sets `role="tooltip"` (customisable via `kjTooltipRole`).
+ * Note: `role="tooltip"` prohibits `aria-label` and `aria-labelledby` per WAI-ARIA.
+ *
+ * @doc
+ *  @doc-example Basic
+ *    @doc-theme default
+ *      @doc-file tooltip.example.ts
+ *    @doc-theme retro
+ *      @doc-file tooltip.retro.example.ts
+ *    @doc-theme finance
+ *      @doc-file tooltip.finance.example.ts
+ *  @doc-example Placements
+ *    @doc-file tooltip.placements.example.ts
+ * @category Core/Overlays
+ * @required
+ */
+@Directive({
+  selector: '[kjTooltipContent]',
+  standalone: true,
+  host: {
+    '[attr.id]':       'tooltipId',
+    '[attr.role]':     'kjTooltipRole()',
+    '[attr.data-side]':'kjTooltipSide()',
+    '[attr.hidden]':   '!visible() ? "" : null',
+    '(mouseenter)': 'cancelHide()',
+    '(mouseleave)': 'startHide()',
+  },
+})
+export class KjTooltipContent {
+  private readonly el = inject(ElementRef<HTMLElement>);
+
+  /** Preferred placement relative to the trigger. One of `'top'`, `'bottom'`, `'left'`, `'right'`. Defaults to `'top'`. */
+  readonly kjTooltipSide = input<KjTooltipSide>('top');
+
+  /** ARIA role for the tooltip element. Defaults to `'tooltip'`. Note: `role="tooltip"` prohibits `aria-label` and `aria-labelledby`. */
+  readonly kjTooltipRole = input<string>('tooltip');
+
+  /** Delay in ms before the tooltip appears on hover. Defaults to `600`. Set to `0` for instant. */
+  readonly kjTooltipDelay = input<number>(600);
+
+  /** Delay in ms before the tooltip disappears after hover ends. Defaults to `200`. */
+  readonly kjTooltipHideDelay = input<number>(200);
+
+  /** Auto-generated `id` wired to the trigger's `aria-describedby`. Always present — set before first display per WAI-ARIA spec. */
+  readonly tooltipId = `kj-tooltip-${++_tooltipIdCounter}`;
+
+  readonly visible = signal(false);
+
+  private showTimer?: ReturnType<typeof setTimeout>;
+  private hideTimer?: ReturnType<typeof setTimeout>;
+
+  constructor() {
+    // Register synchronously so KjTooltipTrigger's host binding can resolve immediately
+    _tooltipRegistry.set(this.el.nativeElement, this);
+  }
+
+  show(): void {
+    clearTimeout(this.hideTimer);
+    const delay = this.kjTooltipDelay();
+    if (delay <= 0) { this.visible.set(true); return; }
+    this.showTimer = setTimeout(() => this.visible.set(true), delay);
+  }
+
+  startHide(): void {
+    clearTimeout(this.showTimer);
+    const delay = this.kjTooltipHideDelay();
+    if (delay <= 0) { this.visible.set(false); return; }
+    this.hideTimer = setTimeout(() => this.visible.set(false), delay);
+  }
+
+  cancelHide(): void {
+    clearTimeout(this.hideTimer);
+  }
+
+  forceHide(): void {
+    clearTimeout(this.showTimer);
+    clearTimeout(this.hideTimer);
+    this.visible.set(false);
+  }
+}
+
+/**
+ * Trigger element for the tooltip. Pass the `[kjTooltipContent]` native element reference via `[kjTooltipTrigger]`.
+ *
+ * - Automatically wires `aria-describedby` to the content's `id` — always set before first display per WAI-ARIA spec
+ * - Shows on hover and focus, hides on leave, blur, or Escape
+ *
+ * @category Core/Overlays
+ * @required
+ */
+@Directive({
+  selector: '[kjTooltipTrigger]',
+  standalone: true,
+  host: {
+    '[attr.aria-describedby]': '_content?.tooltipId',
+    '(mouseenter)':     '_show()',
+    '(mouseleave)':     '_startHide()',
+    '(focus)':          '_show()',
+    '(blur)':           '_forceHide()',
+    '(keydown.escape)': '_forceHide()',
+  },
+})
+export class KjTooltipTrigger {
+  /** Native element of the `[kjTooltipContent]` to associate. Use `#myTip` *(no `exportAs`)* in the template. */
+  readonly kjTooltipTrigger = input.required<HTMLElement>();
+
+  /** Resolved `KjTooltipContent` instance looked up from the registry. */
+  protected get _content(): KjTooltipContent | undefined {
+    return _tooltipRegistry.get(this.kjTooltipTrigger());
+  }
+
+  protected _show():      void { this._content?.show(); }
+  protected _startHide(): void { this._content?.startHide(); }
+  protected _forceHide(): void { this._content?.forceHide(); }
+}

package/tsconfig.lib.json

@@ -0,0 +1,13 @@
+/* To learn more about Typescript configuration file: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html. */
+/* To learn more about Angular compiler options: https://angular.dev/reference/configs/angular-compiler-options. */
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../out-tsc/lib",
+    "declaration": true,
+    "declarationMap": true,
+    "types": []
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["**/*.spec.ts"]
+}

package/tsconfig.lib.prod.json

@@ -0,0 +1,11 @@
+/* To learn more about Typescript configuration file: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html. */
+/* To learn more about Angular compiler options: https://angular.dev/reference/configs/angular-compiler-options. */
+{
+  "extends": "./tsconfig.lib.json",
+  "compilerOptions": {
+    "declarationMap": false
+  },
+  "angularCompilerOptions": {
+    "compilationMode": "partial"
+  }
+}

package/tsconfig.spec.json

@@ -0,0 +1,10 @@
+/* To learn more about Typescript configuration file: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html. */
+/* To learn more about Angular compiler options: https://angular.dev/reference/configs/angular-compiler-options. */
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../out-tsc/spec",
+    "types": ["vitest/globals"]
+  },
+  "include": ["src/**/*.d.ts", "src/**/*.spec.ts"]
+}

package/vite.config.ts

@@ -0,0 +1,19 @@
+import { defineProject } from 'vitest/config';
+import angular from '@analogjs/vite-plugin-angular';
+
+export default defineProject({
+  plugins: [angular()],
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    setupFiles: ['src/test-setup.ts'],
+    include: ['src/**/*.spec.ts'],
+    reporters: ['default'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json'],
+      include: ['src/**/*.ts'],
+      exclude: ['src/**/*.spec.ts', 'src/test-setup.ts'],
+    },
+  },
+});