@kouji-ui/core 0.0.4 → 0.1.1

package/src/a11y/roving-tabindex.ts

@@ -1,10 +1,12 @@
-import {
+import {
   Directive,
   ElementRef,
   InjectionToken,
   contentChildren,
   effect,
+  forwardRef,
   inject,
+  input,
   signal,
 } from '@angular/core';
 
@@ -21,7 +23,9 @@ export const KJ_ROVING_TABINDEX = new InjectionToken<KjRovingTabindex>(
  * ```html
  * <button kjRovingTabindexItem>Item</button>
  * ```
- * @category Core/Accessibility
+ * @doc-category Core/Accessibility
+ * @doc
+ * @doc-name a11y
  */
 @Directive({
   selector: '[kjRovingTabindexItem]',
@@ -48,21 +52,37 @@ export class KjRovingTabindexItemDirective {
  *   <button kjRovingTabindexItem>Italic</button>
  * </div>
  * ```
- * @category Core/Accessibility
+ * @doc-category Core/Accessibility
+ * @doc
+ * @doc-name a11y
  */
 @Directive({
   selector: '[kjRovingTabindex]',
   standalone: true,
-  providers: [{ provide: KJ_ROVING_TABINDEX, useExisting: KjRovingTabindex }],
+  providers: [{ provide: KJ_ROVING_TABINDEX, useExisting: forwardRef(() => KjRovingTabindex) }],
   host: {
     '(keydown)': 'onKeydown($event)',
     '(focusin)': 'onFocusIn($event)',
   },
 })
 export class KjRovingTabindex {
-  private readonly items = contentChildren(KjRovingTabindexItemDirective);
+  private readonly host = inject(ElementRef<HTMLElement>);
+  private readonly items = contentChildren(KjRovingTabindexItemDirective, {
+    descendants: true,
+  });
   private readonly activeIndex = signal(0);
 
+  /**
+   * Restricts arrow-key navigation to a single axis.
+   * - `'horizontal'`: only ArrowLeft / ArrowRight move focus.
+   * - `'vertical'`: only ArrowUp / ArrowDown move focus.
+   * - `'both'`: all four arrow keys move focus (default — preserves prior behaviour).
+   *
+   * Under `'horizontal'`, ArrowLeft / ArrowRight are swapped when the host
+   * element resolves to `dir="rtl"`.
+   */
+  readonly kjRovingOrientation = input<'horizontal' | 'vertical' | 'both'>('both');
+
   constructor() {
     effect(() => {
       const all = this.items();
@@ -70,6 +90,20 @@ export class KjRovingTabindex {
     });
   }
 
+  private resolveRtl(): boolean {
+    const el = this.host.nativeElement;
+    if (typeof getComputedStyle === 'function') {
+      const direction = getComputedStyle(el).direction;
+      if (direction === 'rtl') return true;
+      if (direction === 'ltr') {
+        // Some test environments (jsdom) return the default 'ltr' even when an
+        // ancestor sets `dir="rtl"`. Fall through to attribute lookup.
+      }
+    }
+    const dirHost = el.closest('[dir]') as HTMLElement | null;
+    return dirHost?.dir.toLowerCase() === 'rtl';
+  }
+
   /** @internal — syncs activeIndex when focus moves into an item programmatically */
   onFocusIn(event: FocusEvent): void {
     const all = this.items();
@@ -85,9 +119,24 @@ export class KjRovingTabindex {
     if (!all.length) return;
     let next = this.activeIndex();
 
-    if (event.key === 'ArrowRight' || event.key === 'ArrowDown') {
+    const orientation = this.kjRovingOrientation();
+    const horizontalActive = orientation === 'horizontal' || orientation === 'both';
+    const verticalActive = orientation === 'vertical' || orientation === 'both';
+
+    // Resolve directionality lazily; only matters when horizontal arrows are active.
+    // Prefer computed style; fall back to the nearest `dir` attribute (jsdom does
+    // not propagate ancestor `dir` to computed style in all cases).
+    const isRtl = horizontalActive && this.resolveRtl();
+    const forwardKey = isRtl ? 'ArrowLeft' : 'ArrowRight';
+    const backwardKey = isRtl ? 'ArrowRight' : 'ArrowLeft';
+
+    if (horizontalActive && event.key === forwardKey) {
+      next = (next + 1) % all.length;
+    } else if (horizontalActive && event.key === backwardKey) {
+      next = (next - 1 + all.length) % all.length;
+    } else if (verticalActive && event.key === 'ArrowDown') {
       next = (next + 1) % all.length;
-    } else if (event.key === 'ArrowLeft' || event.key === 'ArrowUp') {
+    } else if (verticalActive && event.key === 'ArrowUp') {
       next = (next - 1 + all.length) % all.length;
     } else if (event.key === 'Home') {
       next = 0;

package/src/a11y/visually-hidden.ts

@@ -1,4 +1,4 @@
-import { Directive } from '@angular/core';
+import { Directive } from '@angular/core';
 
 /**
  * Visually hides an element while keeping it accessible to screen readers.
@@ -11,7 +11,9 @@
  *   <span kjVisuallyHidden>Close dialog</span>
  * </button>
  * ```
- * @category Core/Accessibility
+ * @doc-category Core/Accessibility
+ * @doc
+ * @doc-name a11y
  */
 @Directive({
   selector: '[kjVisuallyHidden]',

package/src/accordion/accordion.context.ts

@@ -1,17 +1,39 @@
 import { InjectionToken, Signal } from '@angular/core';
 
+/** Accordion mode: `'single'` (one item open at a time) or `'multiple'` (any number open). */
+export type KjAccordionType = 'single' | 'multiple';
+
 /** Context interface for the root accordion directive. */
 export interface KjAccordionContext {
+  /** Set of currently open item values. */
   readonly openIds: Signal<ReadonlySet<string>>;
+  /** Current mode: single or multiple. */
+  readonly type: Signal<KjAccordionType>;
+  /** Whether opt-in arrow-key roving navigation is enabled. */
+  readonly arrowNavigation: Signal<boolean>;
+  /** Toggle an item by its string value. In single mode, closes others first. */
   toggle(id: string): void;
+  /** Whether the given item value is currently open. */
   isOpen(id: string): boolean;
 }
 
 /** Context interface for an individual accordion item directive. */
 export interface KjAccordionItemContext {
+  /** Stable string value identifying the item within the parent accordion. */
+  readonly value: Signal<string>;
+  /** Whether this item is currently expanded. */
   readonly expanded: Signal<boolean>;
+  /** Whether this item is disabled (toggle is a no-op, trigger announces aria-disabled). */
+  readonly disabled: Signal<boolean>;
+  /** Stable id for the trigger element — `aria-labelledby` target on the content region. */
+  readonly headerId: Signal<string>;
+  /** Stable id for the content region — `aria-controls` target on the trigger. */
+  readonly contentId: Signal<string>;
+  /** Toggle this item's expanded state. No-op when disabled. */
   toggle(): void;
+  /** Open this item. No-op when disabled. */
   open(): void;
+  /** Close this item. No-op when disabled. */
   close(): void;
 }
 

package/src/accordion/accordion.spec.ts

@@ -1,32 +1,242 @@
-import { render, fireEvent } from '@testing-library/angular';
+import { Component, signal } from '@angular/core';
+import { render, fireEvent } from '@testing-library/angular';
 import { axe, toHaveNoViolations } from 'jest-axe';
-import { KjAccordion, KjAccordionItem, KjAccordionTrigger, KjAccordionContent } from './accordion';
+import {
+  KjAccordion,
+  KjAccordionItem,
+  KjAccordionTrigger,
+  KjAccordionContent,
+} from './accordion';
 
 expect.extend(toHaveNoViolations);
+
 const imports = [KjAccordion, KjAccordionItem, KjAccordionTrigger, KjAccordionContent];
-const template = `<div kjAccordion><div kjAccordionItem [kjItemValue]="'i1'"><button kjAccordionTrigger>Section</button><div kjAccordionContent>Content</div></div></div>`;
+
+const baseTemplate = `
+  <div kjAccordion>
+    <div kjAccordionItem kjItemValue="i1">
+      <button kjAccordionTrigger>Section 1</button>
+      <div kjAccordionContent>Body 1</div>
+    </div>
+    <div kjAccordionItem kjItemValue="i2">
+      <button kjAccordionTrigger>Section 2</button>
+      <div kjAccordionContent>Body 2</div>
+    </div>
+  </div>
+`;
 
 describe('KjAccordion', () => {
   it('content hidden by default', async () => {
-    const { container } = await render(template, { imports });
-    expect(container.querySelector('[kjAccordionContent]')).toHaveAttribute('hidden', '');
-  });
-  it('click trigger expands', async () => {
-    const { container } = await render(template, { imports });
-    fireEvent.click(container.querySelector('[kjAccordionTrigger]')!);
-    expect(container.querySelector('[kjAccordionContent]')).not.toHaveAttribute('hidden');
-  });
-  it('trigger has aria-expanded=false when closed', async () => {
-    const { container } = await render(template, { imports });
-    expect(container.querySelector('[kjAccordionTrigger]')).toHaveAttribute('aria-expanded', 'false');
-  });
-  it('trigger has aria-expanded=true when open', async () => {
-    const { container } = await render(template, { imports });
-    fireEvent.click(container.querySelector('[kjAccordionTrigger]')!);
-    expect(container.querySelector('[kjAccordionTrigger]')).toHaveAttribute('aria-expanded', 'true');
-  });
-  it('passes axe audit', async () => {
-    const { container } = await render(template, { imports });
-    expect(await axe(container)).toHaveNoViolations();
+    const { container } = await render(baseTemplate, { imports });
+    const content = container.querySelector('[kjAccordionContent]');
+    // Visibility is driven by `[data-state]` + CSS animation (the element
+    // stays in the DOM so open/close can transition). `aria-hidden` + `inert`
+    // keep the closed panel out of the AT tree and tab sequence.
+    expect(content).toHaveAttribute('data-state', 'closed');
+    expect(content).toHaveAttribute('aria-hidden', 'true');
+    expect(content).toHaveAttribute('inert', '');
+  });
+
+  it('click trigger expands and updates aria-expanded', async () => {
+    const { container } = await render(baseTemplate, { imports });
+    const trigger = container.querySelector('[kjAccordionTrigger]')!;
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    fireEvent.click(trigger);
+    expect(trigger).toHaveAttribute('aria-expanded', 'true');
+    const content = container.querySelector('[kjAccordionContent]');
+    expect(content).toHaveAttribute('data-state', 'open');
+    expect(content).not.toHaveAttribute('aria-hidden');
+    expect(content).not.toHaveAttribute('inert');
+  });
+
+  it('single mode closes other items when one opens', async () => {
+    const { container } = await render(baseTemplate, { imports });
+    const triggers = container.querySelectorAll('[kjAccordionTrigger]');
+    fireEvent.click(triggers[0]);
+    fireEvent.click(triggers[1]);
+    expect(triggers[0]).toHaveAttribute('aria-expanded', 'false');
+    expect(triggers[1]).toHaveAttribute('aria-expanded', 'true');
+  });
+
+  it('multiple mode keeps multiple items open', async () => {
+    const { container } = await render(
+      `<div kjAccordion kjType="multiple">
+        <div kjAccordionItem kjItemValue="a"><button kjAccordionTrigger>A</button><div kjAccordionContent>A</div></div>
+        <div kjAccordionItem kjItemValue="b"><button kjAccordionTrigger>B</button><div kjAccordionContent>B</div></div>
+      </div>`,
+      { imports },
+    );
+    const triggers = container.querySelectorAll('[kjAccordionTrigger]');
+    fireEvent.click(triggers[0]);
+    fireEvent.click(triggers[1]);
+    expect(triggers[0]).toHaveAttribute('aria-expanded', 'true');
+    expect(triggers[1]).toHaveAttribute('aria-expanded', 'true');
+  });
+
+  describe('ARIA wiring', () => {
+    it('trigger gets aria-controls pointing at the content id', async () => {
+      const { container } = await render(baseTemplate, { imports });
+      const trigger = container.querySelector('[kjAccordionTrigger]') as HTMLElement;
+      const content = container.querySelector('[kjAccordionContent]') as HTMLElement;
+      const controls = trigger.getAttribute('aria-controls');
+      expect(controls).toBeTruthy();
+      expect(controls).toBe(content.id);
+    });
+
+    it('content has role="region" and aria-labelledby pointing at the trigger id', async () => {
+      const { container } = await render(baseTemplate, { imports });
+      const trigger = container.querySelector('[kjAccordionTrigger]') as HTMLElement;
+      const content = container.querySelector('[kjAccordionContent]') as HTMLElement;
+      expect(content).toHaveAttribute('role', 'region');
+      const labelledBy = content.getAttribute('aria-labelledby');
+      expect(labelledBy).toBeTruthy();
+      expect(labelledBy).toBe(trigger.id);
+    });
+
+    it('header / content ids are stable across change detection', async () => {
+      const { container, fixture } = await render(baseTemplate, { imports });
+      const trigger = container.querySelector('[kjAccordionTrigger]') as HTMLElement;
+      const before = trigger.id;
+      fireEvent.click(trigger);
+      fixture.detectChanges();
+      expect(trigger.id).toBe(before);
+    });
+
+    it('passes axe audit (closed)', async () => {
+      const { container } = await render(baseTemplate, { imports });
+      expect(await axe(container)).toHaveNoViolations();
+    });
+
+    it('passes axe audit (open)', async () => {
+      const { container } = await render(baseTemplate, { imports });
+      fireEvent.click(container.querySelector('[kjAccordionTrigger]')!);
+      expect(await axe(container)).toHaveNoViolations();
+    });
+  });
+
+  describe('disabled item', () => {
+    it('toggle is a no-op and aria-disabled is set on the trigger', async () => {
+      const { container } = await render(
+        `<div kjAccordion>
+          <div kjAccordionItem kjItemValue="locked" kjItemDisabled>
+            <button kjAccordionTrigger>Locked</button>
+            <div kjAccordionContent>Body</div>
+          </div>
+        </div>`,
+        { imports },
+      );
+      const trigger = container.querySelector('[kjAccordionTrigger]') as HTMLElement;
+      expect(trigger).toHaveAttribute('aria-disabled', 'true');
+      fireEvent.click(trigger);
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    });
+  });
+
+  describe('two-way value binding', () => {
+    @Component({
+      standalone: true,
+      imports,
+      template: `
+        <div kjAccordion [(kjValue)]="open">
+          <div kjAccordionItem kjItemValue="a"><button kjAccordionTrigger>A</button><div kjAccordionContent>A</div></div>
+          <div kjAccordionItem kjItemValue="b"><button kjAccordionTrigger>B</button><div kjAccordionContent>B</div></div>
+        </div>
+      `,
+    })
+    class SingleHost {
+      readonly open = signal<string>('a');
+    }
+
+    it('opens the seeded item from the bound value (single mode)', async () => {
+      const { container, fixture } = await render(SingleHost);
+      await fixture.whenStable();
+      fixture.detectChanges();
+      const triggers = container.querySelectorAll('[kjAccordionTrigger]');
+      expect(triggers[0]).toHaveAttribute('aria-expanded', 'true');
+      expect(triggers[1]).toHaveAttribute('aria-expanded', 'false');
+    });
+
+    it('writes the open value back to the parent signal on click', async () => {
+      const { container, fixture } = await render(SingleHost);
+      await fixture.whenStable();
+      fireEvent.click(container.querySelectorAll('[kjAccordionTrigger]')[1]);
+      fixture.detectChanges();
+      expect(fixture.componentInstance.open()).toBe('b');
+    });
+
+    @Component({
+      standalone: true,
+      imports,
+      template: `
+        <div kjAccordion kjType="multiple" [(kjValue)]="open">
+          <div kjAccordionItem kjItemValue="a"><button kjAccordionTrigger>A</button><div kjAccordionContent>A</div></div>
+          <div kjAccordionItem kjItemValue="b"><button kjAccordionTrigger>B</button><div kjAccordionContent>B</div></div>
+        </div>
+      `,
+    })
+    class MultipleHost {
+      readonly open = signal<string[]>(['a']);
+    }
+
+    it('multiple mode emits array updates', async () => {
+      const { container, fixture } = await render(MultipleHost);
+      await fixture.whenStable();
+      fireEvent.click(container.querySelectorAll('[kjAccordionTrigger]')[1]);
+      fixture.detectChanges();
+      expect(fixture.componentInstance.open()).toEqual(['a', 'b']);
+    });
+  });
+
+  describe('arrow-key navigation (opt-in)', () => {
+    it('does not move focus when kjArrowNavigation is off (default)', async () => {
+      const { container } = await render(baseTemplate, { imports });
+      const triggers = container.querySelectorAll<HTMLElement>('[kjAccordionTrigger]');
+      triggers[0].focus();
+      fireEvent.keyDown(triggers[0], { key: 'ArrowDown' });
+      // Without arrow-nav opted in, focus stays on the first trigger.
+      expect(document.activeElement).toBe(triggers[0]);
+    });
+
+    it('ArrowDown / ArrowUp / Home / End move focus when kjArrowNavigation is on', async () => {
+      const { container } = await render(
+        `<div kjAccordion kjArrowNavigation kjType="multiple">
+          <div kjAccordionItem kjItemValue="a"><button kjAccordionTrigger>A</button><div kjAccordionContent>A</div></div>
+          <div kjAccordionItem kjItemValue="b"><button kjAccordionTrigger>B</button><div kjAccordionContent>B</div></div>
+          <div kjAccordionItem kjItemValue="c"><button kjAccordionTrigger>C</button><div kjAccordionContent>C</div></div>
+        </div>`,
+        { imports },
+      );
+      const triggers = container.querySelectorAll<HTMLElement>('[kjAccordionTrigger]');
+      triggers[0].focus();
+      fireEvent.keyDown(triggers[0], { key: 'ArrowDown' });
+      expect(document.activeElement).toBe(triggers[1]);
+      fireEvent.keyDown(triggers[1], { key: 'ArrowDown' });
+      expect(document.activeElement).toBe(triggers[2]);
+      fireEvent.keyDown(triggers[2], { key: 'ArrowDown' });
+      // Wraps to first.
+      expect(document.activeElement).toBe(triggers[0]);
+      fireEvent.keyDown(triggers[0], { key: 'ArrowUp' });
+      // Wraps backwards to last.
+      expect(document.activeElement).toBe(triggers[2]);
+      fireEvent.keyDown(triggers[2], { key: 'Home' });
+      expect(document.activeElement).toBe(triggers[0]);
+      fireEvent.keyDown(triggers[0], { key: 'End' });
+      expect(document.activeElement).toBe(triggers[2]);
+    });
+
+    it('skips disabled items during arrow navigation', async () => {
+      const { container } = await render(
+        `<div kjAccordion kjArrowNavigation>
+          <div kjAccordionItem kjItemValue="a"><button kjAccordionTrigger>A</button></div>
+          <div kjAccordionItem kjItemValue="b" kjItemDisabled><button kjAccordionTrigger>B</button></div>
+          <div kjAccordionItem kjItemValue="c"><button kjAccordionTrigger>C</button></div>
+        </div>`,
+        { imports },
+      );
+      const triggers = container.querySelectorAll<HTMLElement>('[kjAccordionTrigger]');
+      triggers[0].focus();
+      fireEvent.keyDown(triggers[0], { key: 'ArrowDown' });
+      expect(document.activeElement).toBe(triggers[2]);
+    });
   });
 });