@kouji-ui/core 0.0.4 → 0.1.1

package/src/speed-dial/speed-dial-action.ts

@@ -0,0 +1,40 @@
+import { Directive, booleanAttribute, inject, input } from '@angular/core';
+import { KJ_SPEED_DIAL, type KjSpeedDialContext } from './speed-dial.context';
+
+/**
+ * One action button in a Speed Dial cluster.
+ *
+ * Apply alongside `kjButton` on a native `<button>` to inherit the button
+ * presets. This directive contributes `role="menuitem"` and closes the parent
+ * dial after the consumer's click handler runs (controllable via
+ * `kjCloseOnActivate`).
+ *
+ * @example
+ * ```html
+ * <button kjButton kjSpeedDialAction aria-label="Edit" (click)="edit()">E</button>
+ * ```
+ *
+ * @doc-category Core/Actions
+ * @doc
+ * @doc-name speed-dial
+ */
+@Directive({
+  selector: '[kjSpeedDialAction]',
+  standalone: true,
+  exportAs: 'kjSpeedDialAction',
+  host: {
+    role: 'menuitem',
+    '(click)': 'onClick()',
+  },
+})
+export class KjSpeedDialAction {
+  private readonly ctx = inject<KjSpeedDialContext>(KJ_SPEED_DIAL);
+
+  /** Whether activating this action should close the dial. Default `true`. */
+  readonly kjCloseOnActivate = input(true, { transform: booleanAttribute });
+
+  protected onClick(): void {
+    if (!this.kjCloseOnActivate()) return;
+    this.ctx.close();
+  }
+}

package/src/speed-dial/speed-dial-actions.ts

@@ -0,0 +1,31 @@
+import { Directive, inject } from '@angular/core';
+import { KJ_SPEED_DIAL, type KjSpeedDialContext } from './speed-dial.context';
+
+/**
+ * Action cluster container for a Speed Dial.
+ *
+ * Holds `role="menu"` and is hidden from the AT tree (and from layout via the
+ * styled wrapper's CSS) when the dial is collapsed. Reflects `id`,
+ * `data-direction`, `data-expanded` and `aria-hidden` for the wrapper to key
+ * its layout / animation off of.
+ *
+ * @doc-category Core/Actions
+ * @doc
+ * @doc-name speed-dial
+ */
+@Directive({
+  selector: '[kjSpeedDialActions]',
+  standalone: true,
+  exportAs: 'kjSpeedDialActions',
+  host: {
+    role: 'menu',
+    '[id]': 'ctx.contentId',
+    '[attr.data-direction]': 'ctx.direction()',
+    '[attr.data-expanded]': 'ctx.expanded() ? "" : null',
+    '[attr.aria-hidden]': 'ctx.expanded() ? null : "true"',
+  },
+})
+export class KjSpeedDialActions {
+  /** @internal */
+  readonly ctx = inject<KjSpeedDialContext>(KJ_SPEED_DIAL);
+}

package/src/speed-dial/speed-dial-trigger.ts

@@ -0,0 +1,55 @@
+import { Directive, inject } from '@angular/core';
+import { KJ_SPEED_DIAL, type KjSpeedDialContext } from './speed-dial.context';
+
+/**
+ * The floating action button that toggles the Speed Dial open/closed.
+ *
+ * Apply alongside `kjButton` on a native `<button>` so the trigger inherits
+ * the button presets (variant, size, focus ring, capture-phase disabled
+ * suppression). The trigger itself contributes the menu-button ARIA wiring
+ * (`aria-haspopup="menu"`, `aria-expanded`, `aria-controls`) and the click
+ * toggle semantics that drive the parent `[kjSpeedDial]`.
+ *
+ * @example
+ * ```html
+ * <div kjSpeedDial>
+ *   <button kjButton kjSpeedDialTrigger aria-label="Open actions">+</button>
+ *   …
+ * </div>
+ * ```
+ *
+ * @doc-category Core/Actions
+ * @doc
+ * @doc-name speed-dial
+ */
+@Directive({
+  selector: '[kjSpeedDialTrigger]',
+  standalone: true,
+  exportAs: 'kjSpeedDialTrigger',
+  host: {
+    type: 'button',
+    '[attr.aria-haspopup]': '"menu"',
+    '[attr.aria-expanded]': 'ctx.expanded() ? "true" : "false"',
+    '[attr.aria-controls]': 'ctx.contentId',
+    '[attr.data-state]': 'ctx.expanded() ? "open" : "closed"',
+    '(click)': 'onClick($event)',
+    '(keydown.escape)': 'onEscape($event)',
+  },
+})
+export class KjSpeedDialTrigger {
+  /** @internal */
+  readonly ctx = inject<KjSpeedDialContext>(KJ_SPEED_DIAL);
+
+  protected onClick(event: MouseEvent): void {
+    if (this.ctx.disabled()) return;
+    event.stopPropagation();
+    this.ctx.toggle();
+  }
+
+  protected onEscape(event: Event): void {
+    if (!this.ctx.expanded()) return;
+    event.preventDefault();
+    event.stopPropagation();
+    this.ctx.close();
+  }
+}

package/src/speed-dial/speed-dial.context.ts

@@ -0,0 +1,36 @@
+import { InjectionToken, type Signal } from '@angular/core';
+
+/** Direction the action cluster fans out from the trigger. */
+export type KjSpeedDialDirection = 'up' | 'down' | 'left' | 'right';
+
+/**
+ * Shared state surface exposed by `[kjSpeedDial]` to its trigger, container
+ * and action descendants. Injected via {@link KJ_SPEED_DIAL}.
+ */
+export interface KjSpeedDialContext {
+  /** Whether the action cluster is currently expanded. */
+  readonly expanded: Signal<boolean>;
+  /** Disabled state — when true, opening is suppressed. */
+  readonly disabled: Signal<boolean>;
+  /** Direction the cluster fans out from the trigger. */
+  readonly direction: Signal<KjSpeedDialDirection>;
+  /** Auto-generated id for the action container, used by `aria-controls`. */
+  readonly contentId: string;
+  /** Open the cluster. */
+  open(): void;
+  /** Close the cluster. */
+  close(): void;
+  /** Toggle the cluster. */
+  toggle(): void;
+}
+
+/** DI token for the shared speed-dial state. */
+export const KJ_SPEED_DIAL = new InjectionToken<KjSpeedDialContext>('KJ_SPEED_DIAL');
+
+let nextSpeedDialId = 0;
+
+/** @internal Generates a unique id for each speed-dial instance. */
+export function nextKjSpeedDialId(): string {
+  nextSpeedDialId += 1;
+  return `kj-speed-dial-${nextSpeedDialId}`;
+}

package/src/speed-dial/speed-dial.spec.ts

@@ -0,0 +1,143 @@
+import { render, fireEvent } from '@testing-library/angular';
+import { axe, toHaveNoViolations } from 'jest-axe';
+import { KjButton } from '../button/button';
+import {
+  KjSpeedDial,
+  KjSpeedDialAction,
+  KjSpeedDialActions,
+  KjSpeedDialTrigger,
+} from './index';
+
+expect.extend(toHaveNoViolations);
+
+const imports = [
+  KjButton,
+  KjSpeedDial,
+  KjSpeedDialTrigger,
+  KjSpeedDialActions,
+  KjSpeedDialAction,
+];
+
+const TEMPLATE = `
+  <div kjSpeedDial>
+    <button kjButton kjSpeedDialTrigger aria-label="Open">+</button>
+    <div kjSpeedDialActions>
+      <button kjButton kjSpeedDialAction aria-label="Edit">E</button>
+      <button kjButton kjSpeedDialAction aria-label="Share">S</button>
+    </div>
+  </div>
+`;
+
+describe('KjSpeedDial', () => {
+  it('starts collapsed and reflects ARIA on the trigger', async () => {
+    const { getByLabelText, container } = await render(TEMPLATE, { imports });
+    const trigger = getByLabelText('Open');
+    expect(trigger).toHaveAttribute('aria-haspopup', 'menu');
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    expect(trigger.getAttribute('aria-controls')).toMatch(/^kj-speed-dial-\d+$/);
+
+    const actions = container.querySelector('[kjSpeedDialActions]') as HTMLElement;
+    expect(actions).toHaveAttribute('aria-hidden', 'true');
+    expect(actions.id).toMatch(/^kj-speed-dial-\d+$/);
+    expect(trigger.getAttribute('aria-controls')).toBe(actions.id);
+  });
+
+  it('reflects kjDirection as data-direction on root and actions container', async () => {
+    const { container } = await render(
+      `
+        <div kjSpeedDial kjDirection="left">
+          <button kjButton kjSpeedDialTrigger aria-label="Open">+</button>
+          <div kjSpeedDialActions>
+            <button kjButton kjSpeedDialAction aria-label="A">A</button>
+          </div>
+        </div>
+      `,
+      { imports },
+    );
+
+    const root = container.querySelector('[kjSpeedDial]') as HTMLElement;
+    const actions = container.querySelector('[kjSpeedDialActions]') as HTMLElement;
+    expect(root).toHaveAttribute('data-direction', 'left');
+    expect(actions).toHaveAttribute('data-direction', 'left');
+  });
+
+  it('toggles open on trigger click and expands the cluster', async () => {
+    const { getByLabelText, container } = await render(TEMPLATE, { imports });
+    const trigger = getByLabelText('Open');
+    const actions = container.querySelector('[kjSpeedDialActions]') as HTMLElement;
+    const root = container.querySelector('[kjSpeedDial]') as HTMLElement;
+
+    fireEvent.click(trigger);
+    expect(trigger).toHaveAttribute('aria-expanded', 'true');
+    expect(trigger).toHaveAttribute('data-state', 'open');
+    expect(actions).not.toHaveAttribute('aria-hidden');
+    expect(actions).toHaveAttribute('data-expanded', '');
+    expect(root).toHaveAttribute('data-expanded', '');
+
+    fireEvent.click(trigger);
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    expect(actions).toHaveAttribute('aria-hidden', 'true');
+  });
+
+  it('closes when an action is activated (default kjCloseOnActivate=true)', async () => {
+    const { getByLabelText } = await render(TEMPLATE, { imports });
+    fireEvent.click(getByLabelText('Open'));
+    expect(getByLabelText('Open')).toHaveAttribute('aria-expanded', 'true');
+
+    fireEvent.click(getByLabelText('Edit'));
+    expect(getByLabelText('Open')).toHaveAttribute('aria-expanded', 'false');
+  });
+
+  it('keeps the dial open when kjCloseOnActivate=false', async () => {
+    const { getByLabelText } = await render(
+      `
+        <div kjSpeedDial>
+          <button kjButton kjSpeedDialTrigger aria-label="Open">+</button>
+          <div kjSpeedDialActions>
+            <button kjButton kjSpeedDialAction [kjCloseOnActivate]="false" aria-label="Stay">S</button>
+          </div>
+        </div>
+      `,
+      { imports },
+    );
+    fireEvent.click(getByLabelText('Open'));
+    fireEvent.click(getByLabelText('Stay'));
+    expect(getByLabelText('Open')).toHaveAttribute('aria-expanded', 'true');
+  });
+
+  it('closes when Escape is pressed on the trigger', async () => {
+    const { getByLabelText } = await render(TEMPLATE, { imports });
+    fireEvent.click(getByLabelText('Open'));
+    expect(getByLabelText('Open')).toHaveAttribute('aria-expanded', 'true');
+
+    fireEvent.keyDown(getByLabelText('Open'), { key: 'Escape' });
+    expect(getByLabelText('Open')).toHaveAttribute('aria-expanded', 'false');
+  });
+
+  it('does not open when kjDisabled', async () => {
+    const { getByLabelText } = await render(
+      `
+        <div kjSpeedDial [kjDisabled]="true">
+          <button kjButton kjSpeedDialTrigger aria-label="Open">+</button>
+          <div kjSpeedDialActions>
+            <button kjButton kjSpeedDialAction aria-label="A">A</button>
+          </div>
+        </div>
+      `,
+      { imports },
+    );
+    fireEvent.click(getByLabelText('Open'));
+    expect(getByLabelText('Open')).toHaveAttribute('aria-expanded', 'false');
+  });
+
+  it('passes axe audit when collapsed', async () => {
+    const { container } = await render(TEMPLATE, { imports });
+    expect(await axe(container)).toHaveNoViolations();
+  });
+
+  it('passes axe audit when expanded', async () => {
+    const { getByLabelText, container } = await render(TEMPLATE, { imports });
+    fireEvent.click(getByLabelText('Open'));
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});

package/src/speed-dial/speed-dial.ts

@@ -0,0 +1,127 @@
+import {
+  Directive,
+  booleanAttribute,
+  computed,
+  input,
+  linkedSignal,
+  output,
+  signal,
+} from '@angular/core';
+import {
+  KJ_SPEED_DIAL,
+  type KjSpeedDialContext,
+  type KjSpeedDialDirection,
+  nextKjSpeedDialId,
+} from './speed-dial.context';
+
+/**
+ * Root container for a Speed Dial / FAB.
+ *
+ * A Speed Dial is a viewport-anchored floating action button that, when
+ * activated, fans out a cluster of secondary action buttons. This directive
+ * owns the open/closed state and exposes it to descendant trigger, container
+ * and action directives via the {@link KJ_SPEED_DIAL} injection token.
+ *
+ * Reflects `data-direction`, `data-expanded` and `data-disabled` host
+ * attributes for the styled wrapper to drive its layout and animation.
+ *
+ * @example
+ * ```html
+ * <div kjSpeedDial kjDirection="up">
+ *   <button kjButton kjSpeedDialTrigger aria-label="Open menu">+</button>
+ *   <div kjSpeedDialActions>
+ *     <button kjButton kjSpeedDialAction aria-label="Edit">E</button>
+ *     <button kjButton kjSpeedDialAction aria-label="Share">S</button>
+ *   </div>
+ * </div>
+ * ```
+ *
+ * @doc-category Core/Actions
+ * @doc
+ * @doc-name speed-dial
+ * @doc-description Unstyled speed dial root that owns open state and fan-out direction for trigger and action children.
+ * @doc-is-main
+ */
+@Directive({
+  selector: '[kjSpeedDial]',
+  standalone: true,
+  exportAs: 'kjSpeedDial',
+  providers: [{ provide: KJ_SPEED_DIAL, useExisting: KjSpeedDial }],
+  host: {
+    '[attr.data-direction]': 'kjDirection()',
+    '[attr.data-expanded]': 'expanded() ? "" : null',
+    '[attr.data-disabled]': 'kjDisabled() ? "" : null',
+    '(mouseenter)': 'onPointerEnter()',
+    '(mouseleave)': 'onPointerLeave()',
+  },
+})
+export class KjSpeedDial implements KjSpeedDialContext {
+  /** Direction the action cluster fans out from the trigger. */
+  readonly kjDirection = input<KjSpeedDialDirection>('up');
+
+  /** Two-way bindable expanded state. */
+  // eslint-disable-next-line @angular-eslint/no-input-rename -- alias keeps the public `kjOpen` name distinct from this internal linkedSignal-backed property
+  readonly kjOpenInput = input<boolean>(false, { alias: 'kjOpen' });
+  readonly kjOpen = linkedSignal(this.kjOpenInput);
+
+  /** Disables opening; if open, closes. */
+  readonly kjDisabled = input(false, { transform: booleanAttribute });
+
+  /** Open on hover (desktop only — coarse pointers always click-to-open). */
+  readonly kjOpenOnHover = input(false, { transform: booleanAttribute });
+
+  /** Convenience output paired with the `kjOpen` input, deduplicated against internal writes. */
+  readonly kjOpenChange = output<boolean>();
+
+  // ── KjSpeedDialContext fields ────────────────────────────────────────
+
+  readonly contentId: string = nextKjSpeedDialId();
+  readonly expanded = computed(() => this.kjOpen() && !this.kjDisabled());
+  readonly disabled = computed(() => this.kjDisabled());
+  readonly direction = computed(() => this.kjDirection());
+
+  // Track the last value emitted to consumers so we don't double-emit when
+  // an internal close is followed by the model effect.
+  private readonly lastEmitted = signal<boolean>(false);
+
+  // ── Mutations ────────────────────────────────────────────────────────
+
+  open(): void {
+    if (this.kjDisabled()) return;
+    if (this.kjOpen()) return;
+    this.kjOpen.set(true);
+    if (this.lastEmitted() !== true) {
+      this.lastEmitted.set(true);
+      this.kjOpenChange.emit(true);
+    }
+  }
+
+  close(): void {
+    if (!this.kjOpen()) return;
+    this.kjOpen.set(false);
+    if (this.lastEmitted() !== false) {
+      this.lastEmitted.set(false);
+      this.kjOpenChange.emit(false);
+    }
+  }
+
+  toggle(): void {
+    if (this.kjOpen()) this.close();
+    else this.open();
+  }
+
+  protected onPointerEnter(): void {
+    if (!this.kjOpenOnHover()) return;
+    if (this.kjDisabled()) return;
+    if (typeof window !== 'undefined' && window.matchMedia?.('(pointer: coarse)').matches) {
+      return;
+    }
+    this.open();
+  }
+
+  protected onPointerLeave(): void {
+    if (!this.kjOpenOnHover()) return;
+    if (this.kjDisabled()) return;
+    this.close();
+  }
+}

package/src/spinner/config.ts

@@ -0,0 +1,48 @@
+import { InjectionToken, Provider } from '@angular/core';
+
+/**
+ * Animation shape preset for `KjSpinner`. Reflected to `data-animation`;
+ * themes own the keyframes.
+ */
+export type KjSpinnerAnimation = 'spin' | 'dots' | 'pulse' | 'bars';
+
+export interface KjSpinnerConfig {
+  variants: string[];
+  sizes: string[];
+  animations: string[];
+  defaults: { variant: string; size: string; animation: string; ariaLabel: string };
+}
+
+/**
+ * Default Spinner presets shipped by kouji-ui. Exported so consumers can
+ * spread them when extending: `[...KJ_SPINNER_DEFAULTS.animations, 'ring']`.
+ */
+export const KJ_SPINNER_DEFAULTS: KjSpinnerConfig = {
+  variants: ['neutral', 'primary', 'secondary', 'success', 'warning', 'error', 'info'],
+  sizes: ['xs', 'sm', 'md', 'lg'],
+  animations: ['spin', 'dots', 'pulse', 'bars'],
+  defaults: { variant: 'neutral', size: 'md', animation: 'spin', ariaLabel: 'Loading' },
+};
+
+/**
+ * DI token for the active Spinner presets. Default factory yields
+ * `KJ_SPINNER_DEFAULTS`. Override via `provideKjSpinner(…)` at the
+ * application scope or at a component scope.
+ */
+export const KJ_SPINNER_CONFIG = new InjectionToken<KjSpinnerConfig>('kj.spinner.config', {
+  factory: () => KJ_SPINNER_DEFAULTS,
+});
+
+/**
+ * Configures the Spinner presets for the enclosing injector. Replaces (does
+ * not merge) `variants`, `sizes`, and `animations`; spread
+ * `KJ_SPINNER_DEFAULTS.*` to extend.
+ */
+export function provideKjSpinner(config: Partial<KjSpinnerConfig>): Provider[] {
+  return [
+    {
+      provide: KJ_SPINNER_CONFIG,
+      useValue: { ...KJ_SPINNER_DEFAULTS, ...config },
+    },
+  ];
+}

package/src/spinner/index.ts

@@ -0,0 +1,8 @@
+export { KjSpinner } from './spinner';
+export {
+  KJ_SPINNER_CONFIG,
+  KJ_SPINNER_DEFAULTS,
+  provideKjSpinner,
+  type KjSpinnerAnimation,
+  type KjSpinnerConfig,
+} from './config';