@kouji-ui/core 0.0.2

package/.turbo/turbo-build.log

@@ -0,0 +1,27 @@
+
+> @kouji-ui/core@0.0.2 build /home/runner/work/kouji-ui/kouji-ui/packages/core
+> ng-packagr -p ng-package.json
+
+Building Angular Package
+
+------------------------------------------------------------------------------
+Building entry point '@kouji-ui/core'
+------------------------------------------------------------------------------
+- Compiling with Angular sources in partial compilation mode.
+✔ Compiling with Angular sources in partial compilation mode.
+✔ Generating FESM and DTS bundles
+- Copying assets
+✔ Copying assets
+- Writing package manifest
+ℹ Removing scripts section in package.json as it's considered a potential security vulnerability.
+✔ Writing package manifest
+✔ Built @kouji-ui/core
+
+------------------------------------------------------------------------------
+Built Angular Package
+- from: /home/runner/work/kouji-ui/kouji-ui/packages/core
+- to:   /home/runner/work/kouji-ui/kouji-ui/dist/kj-core
+------------------------------------------------------------------------------
+
+Build at: 2026-05-04T20:37:30.262Z - Time: 4059ms
+

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @kouji-ui/core
+
+## 0.0.2
+
+### Patch Changes
+
+- 1813d21: Initial publish — headless Angular 21 UI primitives over CDK with WCAG 2.1 AAA semantics and zero CSS.

package/README.md

@@ -0,0 +1,64 @@
+# KjCore
+
+This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 21.2.0.
+
+## Code scaffolding
+
+Angular CLI includes powerful code scaffolding tools. To generate a new component, run:
+
+```bash
+ng generate component component-name
+```
+
+For a complete list of available schematics (such as `components`, `directives`, or `pipes`), run:
+
+```bash
+ng generate --help
+```
+
+## Building
+
+To build the library, run:
+
+```bash
+ng build kj-core
+```
+
+This command will compile your project, and the build artifacts will be placed in the `dist/` directory.
+
+### Publishing the Library
+
+Once the project is built, you can publish your library by following these steps:
+
+1. Navigate to the `dist` directory:
+
+   ```bash
+   cd dist/kj-core
+   ```
+
+2. Run the `npm publish` command to publish your library to the npm registry:
+   ```bash
+   npm publish
+   ```
+
+## Running unit tests
+
+To execute unit tests with the [Karma](https://karma-runner.github.io) test runner, use the following command:
+
+```bash
+ng test
+```
+
+## Running end-to-end tests
+
+For end-to-end (e2e) testing, run:
+
+```bash
+ng e2e
+```
+
+Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.
+
+## Additional Resources
+
+For more information on using the Angular CLI, including detailed command references, visit the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page.

package/ng-package.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "../../node_modules/ng-packagr/ng-package.schema.json",
+  "dest": "../../dist/kj-core",
+  "lib": {
+    "entryFile": "src/public-api.ts"
+  }
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@kouji-ui/core",
+  "version": "0.0.2",
+  "description": "Headless Angular 21 UI primitives — directives over CDK with WCAG 2.1 AAA semantics and zero CSS.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kouji-dev/kouji-ui.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://kouji-ui.onrender.com",
+  "bugs": {
+    "url": "https://github.com/kouji-dev/kouji-ui/issues"
+  },
+  "keywords": [
+    "angular",
+    "ui",
+    "headless",
+    "directives",
+    "cdk",
+    "a11y",
+    "wcag"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "peerDependencies": {
+    "@angular/common": "^21.0.0",
+    "@angular/core": "^21.0.0",
+    "@angular/cdk": "^21.0.0"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "ng-packagr -p ng-package.json",
+    "test": "vitest run",
+    "lint": "ng lint kj-core"
+  }
+}

package/src/a11y/aria-describedby.spec.ts

@@ -0,0 +1,55 @@
+import { render } from '@testing-library/angular';
+import { axe, toHaveNoViolations } from 'jest-axe';
+import { KjAriaDescribedBy } from './aria-describedby';
+
+expect.extend(toHaveNoViolations);
+
+describe('KjAriaDescribedBy', () => {
+  it('sets aria-describedby from a single id string', async () => {
+    const { container } = await render(
+      `<input kjAriaDescribedBy [kjDescribedBy]="'hint-1'" />
+       <span id="hint-1">This is a hint</span>`,
+      { imports: [KjAriaDescribedBy] },
+    );
+    expect(container.querySelector('input')).toHaveAttribute('aria-describedby', 'hint-1');
+  });
+
+  it('sets aria-describedby from multiple ids', async () => {
+    const { container } = await render(
+      `<input kjAriaDescribedBy [kjDescribedBy]="['hint-1', 'error-1']" />
+       <span id="hint-1">Hint</span>
+       <span id="error-1">Error</span>`,
+      { imports: [KjAriaDescribedBy] },
+    );
+    expect(container.querySelector('input')).toHaveAttribute(
+      'aria-describedby',
+      'hint-1 error-1',
+    );
+  });
+
+  it('removes aria-describedby when given empty array', async () => {
+    const { container } = await render(
+      `<input kjAriaDescribedBy [kjDescribedBy]="[]" />`,
+      { imports: [KjAriaDescribedBy] },
+    );
+    expect(container.querySelector('input')).not.toHaveAttribute('aria-describedby');
+  });
+
+  it('removes aria-describedby when given empty string', async () => {
+    const { container } = await render(
+      `<input kjAriaDescribedBy [kjDescribedBy]="''" />`,
+      { imports: [KjAriaDescribedBy] },
+    );
+    expect(container.querySelector('input')).not.toHaveAttribute('aria-describedby');
+  });
+
+  it('passes axe accessibility audit', async () => {
+    const { container } = await render(
+      `<label for="f">Name</label>
+       <input id="f" kjAriaDescribedBy [kjDescribedBy]="'hint'" />
+       <span id="hint">Enter your full name</span>`,
+      { imports: [KjAriaDescribedBy] },
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});

package/src/a11y/aria-describedby.ts

@@ -0,0 +1,33 @@
+import { Directive, computed, input } from '@angular/core';
+
+/**
+ * Wires `aria-describedby` to one or more element IDs.
+ * Accepts a single ID string or an array of ID strings.
+ * Removes the attribute automatically when the value is empty.
+ *
+ * @example
+ * ```html
+ * <input kjAriaDescribedBy [kjDescribedBy]="['hint-id', errorId()]" />
+ * <span id="hint-id">Format: DD/MM/YYYY</span>
+ * ```
+ * @category Core/Accessibility
+ */
+@Directive({
+  selector: '[kjAriaDescribedBy]',
+  standalone: true,
+  host: {
+    '[attr.aria-describedby]': 'ariaDescribedBy()',
+  },
+})
+export class KjAriaDescribedBy {
+  /** One or more element IDs to reference via `aria-describedby`. */
+  kjDescribedBy = input<string | string[]>('');
+
+  /** @internal */
+  readonly ariaDescribedBy = computed(() => {
+    const val = this.kjDescribedBy();
+    const ids = Array.isArray(val) ? val : [val];
+    const filtered = ids.filter(Boolean);
+    return filtered.length ? filtered.join(' ') : null;
+  });
+}

package/src/a11y/focus-trap.spec.ts

@@ -0,0 +1,86 @@
+import { render, fireEvent } from '@testing-library/angular';
+import { axe, toHaveNoViolations } from 'jest-axe';
+import { KjFocusTrap } from './focus-trap';
+
+expect.extend(toHaveNoViolations);
+
+describe('KjFocusTrap', () => {
+  it('renders without error when enabled', async () => {
+    const { container } = await render(
+      `<div kjFocusTrap [kjFocusTrapEnabled]="true">
+        <button>First</button>
+        <button>Last</button>
+      </div>`,
+      { imports: [KjFocusTrap] },
+    );
+    expect(container.querySelector('[kjFocusTrap]')).toBeInTheDocument();
+  });
+
+  it('renders without error when disabled', async () => {
+    const { container } = await render(
+      `<div kjFocusTrap [kjFocusTrapEnabled]="false">
+        <button>First</button>
+      </div>`,
+      { imports: [KjFocusTrap] },
+    );
+    expect(container.querySelector('[kjFocusTrap]')).toBeInTheDocument();
+  });
+
+  it('wraps focus from last to first on Tab when enabled', async () => {
+    const { container } = await render(
+      `<div kjFocusTrap [kjFocusTrapEnabled]="true">
+        <button>First</button>
+        <button>Last</button>
+      </div>`,
+      { imports: [KjFocusTrap] },
+    );
+    const buttons = container.querySelectorAll('button');
+    const last = buttons[buttons.length - 1] as HTMLElement;
+    last.focus();
+    fireEvent.keyDown(document, { key: 'Tab', shiftKey: false });
+    expect(document.activeElement).toBe(buttons[0]);
+  });
+
+  it('wraps focus from first to last on Shift+Tab when enabled', async () => {
+    const { container } = await render(
+      `<div kjFocusTrap [kjFocusTrapEnabled]="true">
+        <button>First</button>
+        <button>Last</button>
+      </div>`,
+      { imports: [KjFocusTrap] },
+    );
+    const buttons = container.querySelectorAll('button');
+    const first = buttons[0] as HTMLElement;
+    first.focus();
+    fireEvent.keyDown(document, { key: 'Tab', shiftKey: true });
+    expect(document.activeElement).toBe(buttons[buttons.length - 1]);
+  });
+
+  it('does not trap focus when disabled', async () => {
+    const { container } = await render(
+      `<div kjFocusTrap [kjFocusTrapEnabled]="false">
+        <button>First</button>
+        <button>Last</button>
+      </div>`,
+      { imports: [KjFocusTrap] },
+    );
+    const buttons = container.querySelectorAll('button');
+    const last = buttons[buttons.length - 1] as HTMLElement;
+    last.focus();
+    // Tab should not redirect focus — no focus change from the handler.
+    const activeBeforeTab = document.activeElement;
+    fireEvent.keyDown(document, { key: 'Tab', shiftKey: false });
+    // When disabled, the handler does nothing, so focus stays on last.
+    expect(document.activeElement).toBe(activeBeforeTab);
+  });
+
+  it('passes axe accessibility audit', async () => {
+    const { container } = await render(
+      `<div role="dialog" aria-label="Test dialog" kjFocusTrap [kjFocusTrapEnabled]="true">
+        <button>Action</button>
+      </div>`,
+      { imports: [KjFocusTrap] },
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});

package/src/a11y/focus-trap.ts

@@ -0,0 +1,70 @@
+import { Directive, DestroyRef, ElementRef, afterNextRender, inject, input } from '@angular/core';
+import { PLATFORM_ID } from '@angular/core';
+import { isPlatformBrowser } from '@angular/common';
+
+const FOCUSABLE = [
+  'a[href]', 'button:not([disabled])', 'input:not([disabled])',
+  'select:not([disabled])', 'textarea:not([disabled])',
+  '[tabindex]:not([tabindex="-1"])', '[contenteditable="true"]',
+].join(',');
+
+/**
+ * Traps keyboard focus within the host element using a native Tab-key interceptor.
+ * Designed for modal dialogs, drawers, and other overlay patterns.
+ *
+ * @example
+ * ```html
+ * <div role="dialog" kjFocusTrap [kjFocusTrapEnabled]="isOpen()">
+ *   <button>Action</button>
+ * </div>
+ * ```
+ * @category Core/Accessibility
+ */
+@Directive({
+  selector: '[kjFocusTrap]',
+  standalone: true,
+})
+export class KjFocusTrap {
+  private readonly el = inject(ElementRef<HTMLElement>);
+  private readonly destroyRef = inject(DestroyRef);
+  private readonly platformId = inject(PLATFORM_ID);
+
+  /** Whether the focus trap is active. Set to true when the overlay is open. */
+  kjFocusTrapEnabled = input<boolean>(false);
+
+  constructor() {
+    afterNextRender(() => {
+      if (!isPlatformBrowser(this.platformId)) return;
+
+      const handleKeydown = (e: KeyboardEvent) => {
+        if (!this.kjFocusTrapEnabled() || e.key !== 'Tab') return;
+        const focusable = (Array.from(
+          this.el.nativeElement.querySelectorAll(FOCUSABLE)
+        ) as HTMLElement[]).filter(el => !el.closest('[hidden]') && getComputedStyle(el).display !== 'none');
+
+        if (!focusable.length) { e.preventDefault(); return; }
+        const first = focusable[0];
+        const last = focusable[focusable.length - 1];
+
+        if (e.shiftKey) {
+          if (document.activeElement === first || !this.el.nativeElement.contains(document.activeElement)) {
+            e.preventDefault(); last.focus();
+          }
+        } else {
+          if (document.activeElement === last || !this.el.nativeElement.contains(document.activeElement)) {
+            e.preventDefault(); first.focus();
+          }
+        }
+      };
+
+      document.addEventListener('keydown', handleKeydown);
+      this.destroyRef.onDestroy(() => document.removeEventListener('keydown', handleKeydown));
+    });
+  }
+
+  /** Focuses the first tabbable element inside the trap. */
+  focusFirst(): void {
+    const el = this.el.nativeElement.querySelector(FOCUSABLE) as HTMLElement | null;
+    el?.focus();
+  }
+}

package/src/a11y/index.ts

@@ -0,0 +1,9 @@
+export { KjAriaDescribedBy } from './aria-describedby';
+export { KjFocusTrap } from './focus-trap';
+export { KjLiveRegion, type KjLivePoliteness } from './live-region';
+export {
+  KjRovingTabindex,
+  KjRovingTabindexItemDirective,
+  KJ_ROVING_TABINDEX,
+} from './roving-tabindex';
+export { KjVisuallyHidden } from './visually-hidden';

package/src/a11y/live-region.spec.ts

@@ -0,0 +1,58 @@
+import { render } from '@testing-library/angular';
+import { axe, toHaveNoViolations } from 'jest-axe';
+import { vi } from 'vitest';
+import { KjLiveRegion } from './live-region';
+
+expect.extend(toHaveNoViolations);
+
+describe('KjLiveRegion', () => {
+  it('sets aria-live to polite by default', async () => {
+    const { container } = await render(
+      `<div kjLiveRegion></div>`,
+      { imports: [KjLiveRegion] },
+    );
+    expect(container.querySelector('div')).toHaveAttribute('aria-live', 'polite');
+  });
+
+  it('sets aria-live to assertive when specified', async () => {
+    const { container } = await render(
+      `<div kjLiveRegion [kjPoliteness]="'assertive'"></div>`,
+      { imports: [KjLiveRegion] },
+    );
+    expect(container.querySelector('div')).toHaveAttribute('aria-live', 'assertive');
+  });
+
+  it('sets aria-atomic to true', async () => {
+    const { container } = await render(
+      `<div kjLiveRegion></div>`,
+      { imports: [KjLiveRegion] },
+    );
+    expect(container.querySelector('div')).toHaveAttribute('aria-atomic', 'true');
+  });
+
+  it('announces a message via DOM text content after a brief timeout', async () => {
+    vi.useFakeTimers();
+    const { container } = await render(
+      `<div kjLiveRegion></div>`,
+      { imports: [KjLiveRegion] },
+    );
+    const div = container.querySelector('div')!;
+
+    // Simulate the announce mechanism: clear, then set after 50ms.
+    div.textContent = '';
+    setTimeout(() => { div.textContent = 'Item saved'; }, 50);
+
+    vi.advanceTimersByTime(50);
+    expect(div.textContent).toBe('Item saved');
+
+    vi.useRealTimers();
+  });
+
+  it('passes axe accessibility audit', async () => {
+    const { container } = await render(
+      `<div kjLiveRegion></div>`,
+      { imports: [KjLiveRegion] },
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});

package/src/a11y/live-region.ts

@@ -0,0 +1,48 @@
+import { Directive, ElementRef, inject, input } from '@angular/core';
+
+/** Politeness setting for ARIA live regions. */
+export type KjLivePoliteness = 'off' | 'polite' | 'assertive';
+
+/**
+ * Marks an element as an ARIA live region and exposes an `announce` method
+ * for programmatically pushing announcements to screen readers via DOM text content.
+ *
+ * @example
+ * ```html
+ * <div kjLiveRegion [kjPoliteness]="'polite'" #region="kjLiveRegion"></div>
+ * <button (click)="region.announce('Item saved')">Save</button>
+ * ```
+ * @category Core/Accessibility
+ */
+@Directive({
+  selector: '[kjLiveRegion]',
+  standalone: true,
+  exportAs: 'kjLiveRegion',
+  host: {
+    '[attr.aria-live]': 'kjPoliteness()',
+    '[attr.aria-atomic]': '"true"',
+  },
+})
+export class KjLiveRegion {
+  private readonly el = inject(ElementRef<HTMLElement>);
+
+  /** The ARIA live politeness setting. Defaults to `'polite'`. */
+  kjPoliteness = input<KjLivePoliteness>('polite');
+
+  /**
+   * Announces a message to screen readers by briefly clearing and re-setting text.
+   * @param message - The message to announce.
+   * @param durationMs - Optional duration in ms before clearing the announcement.
+   */
+  announce(message: string, durationMs?: number): void {
+    const el = this.el.nativeElement;
+    el.textContent = '';
+    // Brief timeout lets screen readers detect the content change.
+    setTimeout(() => {
+      el.textContent = message;
+      if (durationMs != null) {
+        setTimeout(() => { el.textContent = ''; }, durationMs);
+      }
+    }, 50);
+  }
+}

package/src/a11y/roving-tabindex.spec.ts

@@ -0,0 +1,62 @@
+import { render, fireEvent } from '@testing-library/angular';
+import { axe, toHaveNoViolations } from 'jest-axe';
+import {
+  KjRovingTabindex,
+  KjRovingTabindexItemDirective,
+} from './roving-tabindex';
+
+expect.extend(toHaveNoViolations);
+
+const template = `
+  <div kjRovingTabindex role="toolbar" aria-label="Formatting">
+    <button kjRovingTabindexItem>Bold</button>
+    <button kjRovingTabindexItem>Italic</button>
+    <button kjRovingTabindexItem>Underline</button>
+  </div>`;
+const imports = [KjRovingTabindex, KjRovingTabindexItemDirective];
+
+describe('KjRovingTabindex', () => {
+  it('renders all items', async () => {
+    const { getAllByRole } = await render(template, { imports });
+    expect(getAllByRole('button')).toHaveLength(3);
+  });
+
+  it('first item has tabindex 0, others -1', async () => {
+    const { getAllByRole } = await render(template, { imports });
+    const [first, second, third] = getAllByRole('button');
+    expect(first).toHaveAttribute('tabindex', '0');
+    expect(second).toHaveAttribute('tabindex', '-1');
+    expect(third).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('moves focus right on ArrowRight', async () => {
+    const { getAllByRole, container } = await render(template, { imports });
+    const [first, second] = getAllByRole('button');
+    first.focus();
+    fireEvent.keyDown(container.querySelector('[kjRovingTabindex]')!, { key: 'ArrowRight' });
+    expect(second).toHaveAttribute('tabindex', '0');
+    expect(first).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('moves focus left on ArrowLeft', async () => {
+    const { getAllByRole, container } = await render(template, { imports });
+    const [first, second] = getAllByRole('button');
+    second.focus();
+    fireEvent.keyDown(container.querySelector('[kjRovingTabindex]')!, { key: 'ArrowLeft' });
+    expect(first).toHaveAttribute('tabindex', '0');
+    expect(second).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('wraps to last item on ArrowLeft from first', async () => {
+    const { getAllByRole, container } = await render(template, { imports });
+    const buttons = getAllByRole('button');
+    buttons[0].focus();
+    fireEvent.keyDown(container.querySelector('[kjRovingTabindex]')!, { key: 'ArrowLeft' });
+    expect(buttons[2]).toHaveAttribute('tabindex', '0');
+  });
+
+  it('passes axe accessibility audit', async () => {
+    const { container } = await render(template, { imports });
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});

package/src/a11y/roving-tabindex.ts

@@ -0,0 +1,104 @@
+import {
+  Directive,
+  ElementRef,
+  InjectionToken,
+  contentChildren,
+  effect,
+  inject,
+  signal,
+} from '@angular/core';
+
+/** Context token for roving tabindex coordination. */
+export const KJ_ROVING_TABINDEX = new InjectionToken<KjRovingTabindex>(
+  'KjRovingTabindex',
+);
+
+/**
+ * Marks an individual item within a `[kjRovingTabindex]` container.
+ * Its `tabindex` is managed automatically by the parent directive.
+ *
+ * @example
+ * ```html
+ * <button kjRovingTabindexItem>Item</button>
+ * ```
+ * @category Core/Accessibility
+ */
+@Directive({
+  selector: '[kjRovingTabindexItem]',
+  standalone: true,
+  host: {
+    '[attr.tabindex]': 'active() ? "0" : "-1"',
+  },
+})
+export class KjRovingTabindexItemDirective {
+  /** @internal */
+  readonly el = inject(ElementRef<HTMLElement>);
+  /** @internal */
+  readonly active = signal(false);
+}
+
+/**
+ * Implements the roving tabindex pattern for composite widgets such as toolbars and tab lists.
+ * Only one item has `tabindex="0"` at a time; arrow keys move focus between items.
+ *
+ * @example
+ * ```html
+ * <div kjRovingTabindex role="toolbar" aria-label="Formatting">
+ *   <button kjRovingTabindexItem>Bold</button>
+ *   <button kjRovingTabindexItem>Italic</button>
+ * </div>
+ * ```
+ * @category Core/Accessibility
+ */
+@Directive({
+  selector: '[kjRovingTabindex]',
+  standalone: true,
+  providers: [{ provide: KJ_ROVING_TABINDEX, useExisting: KjRovingTabindex }],
+  host: {
+    '(keydown)': 'onKeydown($event)',
+    '(focusin)': 'onFocusIn($event)',
+  },
+})
+export class KjRovingTabindex {
+  private readonly items = contentChildren(KjRovingTabindexItemDirective);
+  private readonly activeIndex = signal(0);
+
+  constructor() {
+    effect(() => {
+      const all = this.items();
+      all.forEach((item, i) => item.active.set(i === this.activeIndex()));
+    });
+  }
+
+  /** @internal — syncs activeIndex when focus moves into an item programmatically */
+  onFocusIn(event: FocusEvent): void {
+    const all = this.items();
+    const idx = all.findIndex((item) => item.el.nativeElement === event.target);
+    if (idx !== -1) {
+      this.activeIndex.set(idx);
+    }
+  }
+
+  /** @internal */
+  onKeydown(event: KeyboardEvent): void {
+    const all = this.items();
+    if (!all.length) return;
+    let next = this.activeIndex();
+
+    if (event.key === 'ArrowRight' || event.key === 'ArrowDown') {
+      next = (next + 1) % all.length;
+    } else if (event.key === 'ArrowLeft' || event.key === 'ArrowUp') {
+      next = (next - 1 + all.length) % all.length;
+    } else if (event.key === 'Home') {
+      next = 0;
+    } else if (event.key === 'End') {
+      next = all.length - 1;
+    } else {
+      return;
+    }
+
+    event.preventDefault();
+    this.activeIndex.set(next);
+    all[next].el.nativeElement.focus();
+  }
+}