@kouji-ui/core 0.0.3 → 0.1.1

package/src/list/list.spec.ts

@@ -0,0 +1,237 @@
+import { Component, signal } from '@angular/core';
+import { render } from '@testing-library/angular';
+import { axe, toHaveNoViolations } from 'jest-axe';
+import { KJ_ROVING_TABINDEX } from '../a11y/roving-tabindex';
+import { KjList, KjListRow } from './list';
+
+expect.extend(toHaveNoViolations);
+
+const imports = [KjList, KjListRow];
+
+describe('KjList', () => {
+  describe('container role', () => {
+    it('emits role="list" on a <ul> host (defeats Safari list-style:none stripping)', async () => {
+      const { container } = await render(
+        `<ul kjList aria-label="Recent files"><li kjListRow>A</li></ul>`,
+        { imports },
+      );
+      const root = container.querySelector('[kjList]')!;
+      expect(root.tagName).toBe('UL');
+      expect(root).toHaveAttribute('role', 'list');
+    });
+
+    it('emits role="list" on a <ol> host as well', async () => {
+      const { container } = await render(
+        `<ol kjList kjAs="ol" aria-label="Steps"><li kjListRow>A</li></ol>`,
+        { imports },
+      );
+      const root = container.querySelector('[kjList]')!;
+      expect(root.tagName).toBe('OL');
+      expect(root).toHaveAttribute('role', 'list');
+    });
+
+    it('emits role="list" on a <div> host', async () => {
+      const { container } = await render(
+        `<div kjList kjAs="div" aria-label="Stats"><div kjListRow>A</div></div>`,
+        { imports },
+      );
+      const root = container.querySelector('[kjList]')!;
+      expect(root).toHaveAttribute('role', 'list');
+    });
+  });
+
+  describe('as="nav" landmark', () => {
+    it('switches the host to a <nav> landmark and omits role="list"', async () => {
+      const { container } = await render(
+        `<nav kjList kjAs="nav" aria-label="Primary"><div kjListRow>A</div></nav>`,
+        { imports },
+      );
+      const root = container.querySelector('[kjList]')!;
+      expect(root.tagName).toBe('NAV');
+      expect(root).not.toHaveAttribute('role');
+    });
+
+    it('warns in dev mode when kjAs="nav" host has no aria-label / aria-labelledby', async () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      try {
+        await render(
+          `<nav kjList kjAs="nav"><div kjListRow>A</div></nav>`,
+          { imports },
+        );
+        expect(warn).toHaveBeenCalled();
+        const message = warn.mock.calls.map((args) => args.join(' ')).join('\n');
+        expect(message).toMatch(/kjAs="nav"/);
+        expect(message).toMatch(/aria-label/);
+      } finally {
+        warn.mockRestore();
+      }
+    });
+
+    it('does not warn when kjAs="nav" host has aria-label', async () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      try {
+        await render(
+          `<nav kjList kjAs="nav" aria-label="Primary"><div kjListRow>A</div></nav>`,
+          { imports },
+        );
+        const navWarnings = warn.mock.calls
+          .map((args) => args.join(' '))
+          .filter((line) => line.includes('kjAs="nav"'));
+        expect(navWarnings).toHaveLength(0);
+      } finally {
+        warn.mockRestore();
+      }
+    });
+  });
+
+  describe('orientation propagation', () => {
+    it('reflects vertical (default) on data-orientation', async () => {
+      const { container } = await render(
+        `<ul kjList aria-label="L"><li kjListRow>A</li></ul>`,
+        { imports },
+      );
+      const root = container.querySelector('[kjList]')!;
+      expect(root).toHaveAttribute('data-orientation', 'vertical');
+    });
+
+    it('reflects horizontal when kjOrientation="horizontal"', async () => {
+      const { container } = await render(
+        `<ul kjList kjOrientation="horizontal" aria-label="L"><li kjListRow>A</li></ul>`,
+        { imports },
+      );
+      const root = container.querySelector('[kjList]')!;
+      expect(root).toHaveAttribute('data-orientation', 'horizontal');
+    });
+
+    it('does not bind aria-orientation (axe aria-allowed-attr forbids it on role="list")', async () => {
+      const { container } = await render(
+        `<ul kjList kjOrientation="horizontal" aria-label="L"><li kjListRow>A</li></ul>`,
+        { imports },
+      );
+      const root = container.querySelector('[kjList]')!;
+      expect(root).not.toHaveAttribute('aria-orientation');
+    });
+
+    it('reflects data-divided and data-hoverable when toggled', async () => {
+      const { container } = await render(
+        `<ul kjList [kjDivided]="true" [kjHoverable]="true" aria-label="L"><li kjListRow>A</li></ul>`,
+        { imports },
+      );
+      const root = container.querySelector('[kjList]')!;
+      expect(root).toHaveAttribute('data-divided', '');
+      expect(root).toHaveAttribute('data-hoverable', '');
+    });
+  });
+
+  describe('arrow-nav opt-in composes KjRovingTabindex', () => {
+    it('exposes the roving primitive as a host directive on the root', async () => {
+      // KjList unconditionally composes KjRovingTabindex (per accordion's
+      // "always-applied roving primitive that no-ops when the flag is off"
+      // pattern). Verify the primitive is provided in the root's injector by
+      // resolving its DI token from a child element.
+      @Component({
+        standalone: true,
+        imports,
+        template: `
+          <ul kjList kjArrowNavigation aria-label="Primary">
+            <li kjListRow>A</li>
+          </ul>
+        `,
+      })
+      class Host {}
+
+      const { fixture } = await render(Host);
+      // The KjRovingTabindex provider lives at the root host's element
+      // injector — resolve it through a debug element lookup.
+      const rootDebugEl = fixture.debugElement.query(
+        (de) => de.nativeElement?.matches?.('[kjList]'),
+      );
+      const rovingFromChild: unknown = rootDebugEl.injector.get(KJ_ROVING_TABINDEX, null);
+      expect(rovingFromChild).not.toBeNull();
+    });
+  });
+
+  describe('KjListRow', () => {
+    it('omits role on <li> and emits role="listitem" on <div>', async () => {
+      const { container } = await render(
+        `<ul kjList aria-label="L">
+           <li kjListRow>A</li>
+           <div kjListRow>B</div>
+         </ul>`,
+        { imports },
+      );
+      const items = Array.from(container.querySelectorAll('[kjListRow]'));
+      expect(items[0].tagName).toBe('LI');
+      expect(items[0]).not.toHaveAttribute('role');
+      expect(items[1].tagName).toBe('DIV');
+      expect(items[1]).toHaveAttribute('role', 'listitem');
+    });
+
+    it('reflects kjActive to data-active and clears it when toggled off', async () => {
+      @Component({
+        standalone: true,
+        imports,
+        template: `
+          <ul kjList aria-label="L">
+            <li kjListRow [kjActive]="active()">A</li>
+          </ul>
+        `,
+      })
+      class Host {
+        active = signal(true);
+      }
+
+      const { container, fixture } = await render(Host);
+      const item = container.querySelector('[kjListRow]')!;
+      expect(item).toHaveAttribute('data-active', '');
+
+      fixture.componentInstance.active.set(false);
+      fixture.detectChanges();
+      expect(item).not.toHaveAttribute('data-active');
+    });
+
+    it('reflects kjDisabled to data-disabled', async () => {
+      const { container } = await render(
+        `<ul kjList aria-label="L">
+           <li kjListRow [kjDisabled]="true">A</li>
+         </ul>`,
+        { imports },
+      );
+      const item = container.querySelector('[kjListRow]')!;
+      expect(item).toHaveAttribute('data-disabled', '');
+    });
+  });
+
+  describe('axe', () => {
+    it('passes axe audit on a basic <ul> list', async () => {
+      const { container } = await render(
+        `<ul kjList aria-label="Recent files">
+           <li kjListRow>A</li>
+           <li kjListRow>B</li>
+           <li kjListRow>C</li>
+         </ul>`,
+        { imports },
+      );
+      expect(await axe(container)).toHaveNoViolations();
+    });
+
+    it('passes axe audit on a <nav>-wrapped sidebar list with active row', async () => {
+      // Recommended idiom for a sidebar nav: the <nav> landmark wraps the
+      // labelled <ul kjList>, so listitems retain a `role="list"` parent and
+      // the landmark gets a clean accessible name. The kjAs="nav" form is
+      // available for layouts that prefer to put kjList on <nav> directly.
+      const { container } = await render(
+        `<nav aria-label="Primary">
+           <ul kjList>
+             <li kjListRow [kjActive]="true">
+               <a href="/home" aria-current="page">Home</a>
+             </li>
+             <li kjListRow><a href="/about">About</a></li>
+           </ul>
+         </nav>`,
+        { imports },
+      );
+      expect(await axe(container)).toHaveNoViolations();
+    });
+  });
+});

package/src/list/list.ts

@@ -0,0 +1,277 @@
+import {
+  Directive,
+  ElementRef,
+  InjectionToken,
+  Signal,
+  computed,
+  effect,
+  inject,
+  input,
+  isDevMode,
+} from '@angular/core';
+import { KjRovingTabindex } from '../a11y/roving-tabindex';
+import { KjSize, KjVariant } from '../presets';
+import type { KjListOrientation } from '../primitives/list/tokens';
+
+export type { KjListOrientation };
+
+/**
+ * Host element kind the consumer chose for the list root. The directive does
+ * not render this element — the consumer does — but the input lets the
+ * directive emit the right `role` and warn on landmark misuse.
+ *
+ * `'ul'` is the default and the recommended choice in 90% of cases.
+ */
+export type KjListAs = 'ul' | 'ol' | 'div' | 'nav';
+
+/** @internal Public shape of the parent list context exposed to descendants. */
+export interface KjListContext {
+  readonly kjOrientation: Signal<KjListOrientation>;
+  readonly kjDivided: Signal<boolean>;
+  readonly kjHoverable: Signal<boolean>;
+}
+
+/** Context token for the parent `KjList`, injected by descendants. */
+export const KJ_LIST = new InjectionToken<KjListContext>('KjList');
+
+/** Context token for the parent `KjListRow`, injected by descendants. */
+export const KJ_LIST_ROW = new InjectionToken<KjListRowContext>('KjListRow');
+
+/** @internal Public shape of the per-row context exposed to descendants. */
+export interface KjListRowContext {
+  readonly active: Signal<boolean>;
+  readonly disabled: Signal<boolean>;
+}
+
+/**
+ * Root list container. Owns the container ARIA role, orientation,
+ * divider/hover data attributes, and an opt-in roving-tabindex composition for
+ * sidebar-nav-list use cases. Composes `KjVariant` + `KjSize` via
+ * `hostDirectives` so theme CSS can read the standard `data-variant` /
+ * `data-size` mirrors.
+ *
+ * The directive does **not** render the host element — the consumer does. The
+ * `kjAs` input declares which element the consumer chose so the directive can
+ * emit (or omit) `role="list"` and warn when a `<nav>` host is missing an
+ * accessible name.
+ *
+ * **Why `role="list"` on `<ul>`/`<ol>`?** Safari's WebKit "list voice"
+ * heuristic strips the implicit `role="list"` from a `<ul>` whose CSS sets
+ * `list-style: none` (the default in our wrapper CSS). Re-emitting the role
+ * defeats the heuristic. The redundancy is deliberate.
+ *
+ * @example
+ * ```html
+ * <ul kjList kjOrientation="vertical" aria-label="Recent files">
+ *   <li kjListRow>Item A</li>
+ *   <li kjListRow>Item B</li>
+ * </ul>
+ * ```
+ *
+ * @example Sidebar nav with arrow-key navigation
+ * ```html
+ * <nav kjList kjAs="nav" kjArrowNavigation aria-label="Primary">
+ *   <div kjListRow [kjActive]="true">
+ *     <a kjLink kjRovingTabindexItem aria-current="page">Home</a>
+ *   </div>
+ *   <div kjListRow>
+ *     <a kjLink kjRovingTabindexItem>Settings</a>
+ *   </div>
+ * </nav>
+ * ```
+ *
+ * @doc-category Core/Data display
+ * @doc
+ * @doc-name list
+ * @doc-description Unstyled list container with role, orientation, and opt-in arrow-key navigation for sidebars.
+ * @doc-is-main
+ */
+@Directive({
+  selector: '[kjList]',
+  standalone: true,
+  hostDirectives: [
+    { directive: KjVariant, inputs: ['kjVariant'] },
+    { directive: KjSize, inputs: ['kjSize'] },
+    // Forward the composed roving primitive's orientation under the same
+    // external name as `kjOrientation` so consumers writing
+    // `<ul kjList kjOrientation="horizontal">` get both axes wired.
+    {
+      directive: KjRovingTabindex,
+      inputs: ['kjRovingOrientation: kjOrientation'],
+    },
+  ],
+  providers: [{ provide: KJ_LIST, useExisting: KjList }],
+  exportAs: 'kjList',
+  host: {
+    '[attr.role]': 'roleAttr()',
+    // `aria-orientation` is rejected by axe's `aria-allowed-attr` on
+    // `role="list"` (the implicit/explicit list role does not list
+    // `aria-orientation` as a supported attribute in ARIA 1.2). The keyboard
+    // axis is enforced via the composed `KjRovingTabindex.kjRovingOrientation`
+    // and themes read `data-orientation` for visual layout. Same precedent
+    // as `KjStepper`.
+    '[attr.data-orientation]': 'kjOrientation()',
+    '[attr.data-divided]': 'kjDivided() ? "" : null',
+    '[attr.data-hoverable]': 'kjHoverable() ? "" : null',
+  },
+})
+export class KjList implements KjListContext {
+  private readonly el = inject<ElementRef<HTMLElement>>(ElementRef);
+
+  /**
+   * Declares which host element the consumer is rendering this list as.
+   * Default `'ul'` matches the `<ul kjList>` ergonomic. `'nav'` switches the
+   * implicit role to the `navigation` landmark (the directive omits its
+   * `role="list"` binding in that case) and triggers a dev-mode warning when
+   * neither `aria-label` nor `aria-labelledby` is set on the host.
+   */
+  readonly kjAs = input<KjListAs>('ul');
+
+  /**
+   * List orientation. Drives `aria-orientation` and `data-orientation`.
+   * Forwarded to the composed `KjRovingTabindex` (when `kjArrowNavigation` is
+   * `true`) so arrow-key navigation moves on the right axis.
+   */
+  readonly kjOrientation = input<KjListOrientation>('vertical');
+
+  /**
+   * Whether the list draws between-row borders. Theme CSS reads
+   * `data-divided` on the root and applies a `:not(:last-child)` border on
+   * `KjListRow`. Pure CSS effect — no JS.
+   */
+  readonly kjDivided = input<boolean>(false);
+
+  /**
+   * Whether rows highlight on hover. Theme CSS reads `data-hoverable` on the
+   * root. Off by default because purely informational lists (stat blocks)
+   * should not hint at interactivity.
+   */
+  readonly kjHoverable = input<boolean>(false);
+
+  /**
+   * Opt-in flag that turns the list into a roving-tabindex group. When
+   * `false` (default), the composed `KjRovingTabindex` is configured with
+   * `kjRovingOrientation="vertical" | "horizontal"` but no item is registered
+   * unless the consumer applies `kjRovingTabindexItem` to a focusable child.
+   * Setting this to `true` documents the intent at the consumer site; the
+   * actual focus-stop wiring is done by the consumer applying
+   * `kjRovingTabindexItem` on their projected `<a>` / `<button>`.
+   */
+  readonly kjArrowNavigation = input<boolean>(false);
+
+  /**
+   * Whether arrow-key navigation wraps at the ends. Forwarded conceptually to
+   * theme/keyboard logic; only meaningful when `kjArrowNavigation` is `true`.
+   * Defaults to `true` to match the typical sidebar-nav UX.
+   */
+  readonly kjListWrap = input<boolean>(true);
+
+  /** @internal Computes the role the directive should host-bind. */
+  protected readonly roleAttr = computed<string | null>(() => {
+    const as = this.kjAs();
+    // `<nav>` is a landmark (implicit `role="navigation"`); emitting
+    // `role="list"` on top of it would conflict with the landmark semantics.
+    if (as === 'nav') return null;
+    // Always emit on `<ul>` / `<ol>` to defeat Safari's `list-style: none`
+    // voice-stripping heuristic, and on `<div>` because there is no implicit
+    // role to inherit from.
+    return 'list';
+  });
+
+  constructor() {
+    if (isDevMode()) {
+      // Landmark naming discipline: a `<nav>` MUST have an accessible name.
+      // We warn (not throw) so downstream tooling that adds the attribute via
+      // a wrapper or a parent `aria-labelledby` on the surrounding heading
+      // does not flake under unit tests; the wrapper layer escalates to an
+      // error per the analysis doc.
+      effect(() => {
+        if (this.kjAs() !== 'nav') return;
+        // Read host attributes lazily — the host element is the consumer's,
+        // so attribute presence is the source of truth.
+        const host = this.el.nativeElement;
+        const hasLabel =
+          host.hasAttribute('aria-label') || host.hasAttribute('aria-labelledby');
+        if (!hasLabel) {
+          console.warn(
+            '[kj] kjList with kjAs="nav" requires aria-label or aria-labelledby on the host. ' +
+              'A <nav> is a landmark and must be named.',
+          );
+        }
+      });
+    }
+  }
+}
+
+/**
+ * Per-row directive for themed list surfaces (settings panels, sidebar nav).
+ * Owns the listitem ARIA role and reflects active / disabled state to data
+ * attributes the wrapper CSS reads to paint chrome. Provides a tiny
+ * `KJ_LIST_ROW` token so descendants (e.g. an icon button inside the row) can
+ * read the parent's active/disabled signals.
+ *
+ * Distinct from the listbox/menu/tree primitive `KjListItem` in
+ * `primitives/list` — that one drives selection, ARIA `aria-selected`, and
+ * activation, whereas this directive is purely a presentational row in a
+ * navigation/list surface.
+ *
+ * The row host is **not** a focus stop. Keyboard reachability lives on the
+ * projected interactive child (`<a kjLink>`, `<button kjButton>`). The
+ * directive's `kjDisabled` only paints the chrome via `data-disabled`; it
+ * does **not** wire `aria-disabled` on the projected child — that is the
+ * projected child's responsibility (via `KjDisabled`).
+ *
+ * @example
+ * ```html
+ * <li kjListRow [kjActive]="route === '/home'">
+ *   <a kjLink href="/home" aria-current="page">Home</a>
+ * </li>
+ * ```
+ *
+ * @doc-category Core/Data display
+ * @doc
+ * @doc-name list
+ */
+@Directive({
+  selector: '[kjListRow]',
+  standalone: true,
+  providers: [{ provide: KJ_LIST_ROW, useExisting: KjListRow }],
+  exportAs: 'kjListRow',
+  host: {
+    '[attr.role]': 'roleAttr()',
+    '[attr.data-active]': 'kjActive() ? "" : null',
+    '[attr.data-disabled]': 'kjDisabled() ? "" : null',
+  },
+})
+export class KjListRow implements KjListRowContext {
+  private readonly el = inject<ElementRef<HTMLElement>>(ElementRef);
+
+  /**
+   * Whether the row is the current/active selection (e.g. the current page in
+   * a sidebar nav). Reflects to `data-active=""`. The directive does **not**
+   * infer `aria-current` from this — the consumer sets `aria-current="page"`
+   * (or `step`, `date`, `true`) on the projected link/button because the
+   * right token depends on the consumer's domain.
+   */
+  readonly kjActive = input<boolean>(false);
+
+  /**
+   * Whether the row is disabled. Reflects to `data-disabled=""` so theme CSS
+   * can dim the projected interactive child. Does not block keyboard
+   * reachability — that responsibility is the projected child's (via
+   * `KjDisabled`).
+   */
+  readonly kjDisabled = input<boolean>(false);
+
+  /** @internal Mirrors `kjActive` for descendant-side reads via `KJ_LIST_ROW`. */
+  readonly active = this.kjActive;
+
+  /** @internal Mirrors `kjDisabled` for descendant-side reads via `KJ_LIST_ROW`. */
+  readonly disabled = this.kjDisabled;
+
+  /** @internal Computes the role to host-bind, omitting when the host is `<li>`. */
+  protected readonly roleAttr = computed<string | null>(() => {
+    const tag = this.el.nativeElement.tagName?.toLowerCase();
+    return tag === 'li' ? null : 'listitem';
+  });
+}

package/src/menubar/index.ts

@@ -0,0 +1,7 @@
+export { KjMenubar } from './menubar';
+export { KjMenubarItem } from './menubar-item';
+export {
+  KJ_MENUBAR,
+  type KjMenubarContext,
+  type KjMenubarItemContext,
+} from './menubar.context';