@kouji-ui/core 0.1.1 → 0.1.3

package/src/skeleton/skeleton.spec.ts

@@ -1,115 +0,0 @@
-import { render } from '@testing-library/angular';
-import { axe, toHaveNoViolations } from 'jest-axe';
-import { describe, expect, it } from 'vitest';
-import { KjSkeleton } from './skeleton';
-
-expect.extend(toHaveNoViolations);
-
-describe('KjSkeleton', () => {
-  describe('aria-hidden enforcement (load-bearing contract)', () => {
-    it('sets aria-hidden="true" on the host', async () => {
-      const { container } = await render(`<div kjSkeleton></div>`, {
-        imports: [KjSkeleton],
-      });
-      expect(container.querySelector('div')).toHaveAttribute('aria-hidden', 'true');
-    });
-
-    it('sets aria-hidden="true" on a <span> host', async () => {
-      const { container } = await render(`<span kjSkeleton></span>`, {
-        imports: [KjSkeleton],
-      });
-      expect(container.querySelector('span')).toHaveAttribute('aria-hidden', 'true');
-    });
-
-    it('host binding wins over a consumer-supplied [attr.aria-hidden]="false"', async () => {
-      // The directive's host binding `[attr.aria-hidden]="\"true\""` is a
-      // static expression evaluated by the directive, and Angular's binding
-      // semantics give the directive's host binding precedence over a
-      // template attribute literal on the same element. The consumer cannot
-      // turn the skeleton into something AT will read by writing
-      // `aria-hidden="false"` on the tag — this is the entire reason a
-      // directive exists rather than a CSS class. (Per analysis: not
-      // user-overridable.)
-      const { container } = await render(
-        `<div kjSkeleton aria-hidden="false"></div>`,
-        { imports: [KjSkeleton] },
-      );
-      expect(container.querySelector('div')).toHaveAttribute('aria-hidden', 'true');
-    });
-  });
-
-  describe('shape reflection', () => {
-    it('defaults to data-shape="rectangle"', async () => {
-      const { container } = await render(`<div kjSkeleton></div>`, {
-        imports: [KjSkeleton],
-      });
-      expect(container.querySelector('div')).toHaveAttribute('data-shape', 'rectangle');
-    });
-
-    it('reflects kjSkeletonShape="circle" to data-shape', async () => {
-      const { container } = await render(
-        `<div kjSkeleton [kjSkeletonShape]="'circle'"></div>`,
-        { imports: [KjSkeleton] },
-      );
-      expect(container.querySelector('div')).toHaveAttribute('data-shape', 'circle');
-    });
-
-    it('reflects kjSkeletonShape="text" to data-shape', async () => {
-      const { container } = await render(
-        `<div kjSkeleton [kjSkeletonShape]="'text'"></div>`,
-        { imports: [KjSkeleton] },
-      );
-      expect(container.querySelector('div')).toHaveAttribute('data-shape', 'text');
-    });
-
-    it('reflects kjSkeletonShape="text-block" to data-shape', async () => {
-      const { container } = await render(
-        `<div kjSkeleton [kjSkeletonShape]="'text-block'"></div>`,
-        { imports: [KjSkeleton] },
-      );
-      expect(container.querySelector('div')).toHaveAttribute('data-shape', 'text-block');
-    });
-  });
-
-  describe('animation reflection', () => {
-    it('defaults to data-animation="shimmer"', async () => {
-      const { container } = await render(`<div kjSkeleton></div>`, {
-        imports: [KjSkeleton],
-      });
-      expect(container.querySelector('div')).toHaveAttribute('data-animation', 'shimmer');
-    });
-
-    it('reflects kjSkeletonAnimation="pulse" to data-animation', async () => {
-      const { container } = await render(
-        `<div kjSkeleton [kjSkeletonAnimation]="'pulse'"></div>`,
-        { imports: [KjSkeleton] },
-      );
-      expect(container.querySelector('div')).toHaveAttribute('data-animation', 'pulse');
-    });
-
-    it('reflects kjSkeletonAnimation="none" to data-animation', async () => {
-      const { container } = await render(
-        `<div kjSkeleton [kjSkeletonAnimation]="'none'"></div>`,
-        { imports: [KjSkeleton] },
-      );
-      expect(container.querySelector('div')).toHaveAttribute('data-animation', 'none');
-    });
-  });
-
-  describe('a11y audits', () => {
-    it('a default skeleton passes axe', async () => {
-      const { container } = await render(`<div kjSkeleton></div>`, {
-        imports: [KjSkeleton],
-      });
-      expect(await axe(container)).toHaveNoViolations();
-    });
-
-    it('a circle skeleton with explicit dimensions passes axe', async () => {
-      const { container } = await render(
-        `<div kjSkeleton [kjSkeletonShape]="'circle'" style="width: 40px; height: 40px"></div>`,
-        { imports: [KjSkeleton] },
-      );
-      expect(await axe(container)).toHaveNoViolations();
-    });
-  });
-});

package/src/skeleton/skeleton.ts

@@ -1,56 +0,0 @@
-import { Directive, input } from '@angular/core';
-
-/**
- * Visual shape preset for a skeleton placeholder. Reflects to `data-shape`.
- */
-export type KjSkeletonShape = 'rectangle' | 'circle' | 'text' | 'text-block';
-
-/**
- * Animation preset for a skeleton placeholder. Reflects to `data-animation`.
- */
-export type KjSkeletonAnimation = 'shimmer' | 'pulse' | 'none';
-
-/**
- * Marks an element as a kouji skeleton — a decorative placeholder painted
- * while real content is loading. Forces `aria-hidden="true"` on the host so
- * AT skips the placeholder (the *parent region* carries the loading
- * semantics, see [`skeleton.md`](./skeleton.md) § Accessibility), and
- * reflects `data-shape` / `data-animation` so theme CSS can pick the
- * chrome and animation. The directive owns no dimensions, no variant, no
- * size — sizing is consumer-driven and skeletons are tonally neutral by
- * design.
- *
- * @example
- * ```html
- * <span kjSkeleton kjSkeletonShape="text" style="width: 12rem"></span>
- * <div kjSkeleton kjSkeletonShape="circle" style="width: 40px; height: 40px"></div>
- * ```
- * @doc-category Core/Layout
- * @doc
- * @doc-name skeleton
- * @doc-description Marks an element as a decorative loading placeholder hidden from screen readers.
- * @doc-is-main
- */
-@Directive({
-  selector: '[kjSkeleton]',
-  standalone: true,
-  exportAs: 'kjSkeleton',
-  host: {
-    '[attr.aria-hidden]': '"true"',
-    '[attr.data-shape]': 'kjSkeletonShape()',
-    '[attr.data-animation]': 'kjSkeletonAnimation()',
-  },
-})
-export class KjSkeleton {
-  /**
-   * The visual shape of the skeleton. Reflects to `data-shape`. Defaults to
-   * `'rectangle'`.
-   */
-  readonly kjSkeletonShape = input<KjSkeletonShape>('rectangle');
-
-  /**
-   * The animation style applied while the skeleton is on screen. Reflects to
-   * `data-animation`. Defaults to `'shimmer'`.
-   */
-  readonly kjSkeletonAnimation = input<KjSkeletonAnimation>('shimmer');
-}

package/src/slider/index.ts

@@ -1,10 +0,0 @@
-export { KjSlider } from './slider';
-export { KjSliderTrack } from './slider-track';
-export { KjSliderRange } from './slider-range';
-export { KjSliderThumb } from './slider-thumb';
-export {
-  KJ_SLIDER,
-  type KjSliderContext,
-  type KjSliderSource,
-  type KjSliderThumbHandle,
-} from './slider.context';

package/src/slider/slider-range.ts

@@ -1,49 +0,0 @@
-import { Directive, computed, inject } from '@angular/core';
-import { KJ_SLIDER } from './slider.context';
-import { fractionForValue } from './slider.geometry';
-
-/**
- * Highlighted span representing the *selected* portion of the track —
- * `0..thumb` for a single-thumb slider, or `low..high` for a range slider.
- *
- * Pure visual: writes two CSS custom properties (`--kj-slider-start` and
- * `--kj-slider-end`, both `0..1` fractions) which the wrapper layer maps
- * to `inset-inline-start` / `inline-size` (or block equivalents for
- * vertical). `aria-hidden="true"` — decoration only.
- *
- * @doc-category Library/Data input
- * @doc
- * @doc-name slider
- */
-@Directive({
-  selector: '[kjSliderRange]',
-  standalone: true,
-  exportAs: 'kjSliderRange',
-  host: {
-    'aria-hidden': 'true',
-    '[attr.data-orientation]': 'ctx.orientation()',
-    '[style.--kj-slider-start]': 'fractions().start',
-    '[style.--kj-slider-end]': 'fractions().end',
-  },
-})
-export class KjSliderRange {
-  /** @internal */
-  readonly ctx = inject(KJ_SLIDER);
-
-  /** @internal — `start` ≤ `end` regardless of inversion (CSS handles flipping). */
-  readonly fractions = computed(() => {
-    const thumbs = this.ctx.thumbs();
-    const args = { min: this.ctx.min(), max: this.ctx.max(), inverted: this.ctx.inverted() };
-    if (thumbs.length === 0) return { start: 0, end: 0 };
-    if (thumbs.length === 1) {
-      const f = fractionForValue(thumbs[0].value(), args);
-      // From the start of the track (post-invert) to the thumb.
-      const start = this.ctx.inverted() ? f : 0;
-      const end = this.ctx.inverted() ? 1 : f;
-      return { start, end };
-    }
-    const lo = fractionForValue(thumbs[0].value(), args);
-    const hi = fractionForValue(thumbs[1].value(), args);
-    return { start: Math.min(lo, hi), end: Math.max(lo, hi) };
-  });
-}

package/src/slider/slider-thumb.ts

@@ -1,335 +0,0 @@
-import {
-  DestroyRef,
-  Directive,
-  ElementRef,
-  afterNextRender,
-  booleanAttribute,
-  computed,
-  effect,
-  inject,
-  input,
-  model,
-  signal,
-} from '@angular/core';
-import { KjDisabled } from '../primitives/interaction/disabled';
-import { KjFocusRing } from '../primitives/interaction/focus-ring';
-import { KjFormControl } from '../primitives/forms/form-control';
-import { KJ_SLIDER, KjSliderSource, KjSliderThumbHandle } from './slider.context';
-import { fractionForValue } from './slider.geometry';
-
-let nextId = 0;
-
-/**
- * Per-thumb directive. Owns `role="slider"`, `aria-valuemin/max/now/text`,
- * `aria-orientation`, the keyboard contract (Arrow / Page / Home / End),
- * pointer-drag with capture, and one `KjFormControl` per thumb so each
- * thumb is independently bindable through Angular Forms.
- *
- * Range mode is just two `[kjSliderThumb]`s as siblings inside one
- * `[kjSliderTrack]`. The root resolves DOM order to `index` (0 = low,
- * 1 = high) and narrows each thumb's `aria-valuemin/max` to the partner
- * thumb's position when `kjMinDistance` would otherwise place a value
- * out of reach.
- *
- * Composes `KjDisabled`, `KjFocusRing`, and `KjFormControl` via
- * `hostDirectives`. Effective disabled is the OR of root + per-thumb.
- *
- * @doc-category Library/Data input
- * @doc
- * @doc-name slider
- */
-@Directive({
-  selector: '[kjSliderThumb]',
-  standalone: true,
-  hostDirectives: [
-    { directive: KjDisabled, inputs: ['kjDisabled'] },
-    KjFocusRing,
-    KjFormControl,
-  ],
-  exportAs: 'kjSliderThumb',
-  host: {
-    '[attr.role]': '"slider"',
-    '[attr.id]': 'thumbId()',
-    '[attr.tabindex]': 'effectiveDisabled() ? -1 : 0',
-    '[attr.aria-orientation]': 'ctx.orientation()',
-    '[attr.aria-valuemin]': 'effectiveValueMin()',
-    '[attr.aria-valuemax]': 'effectiveValueMax()',
-    '[attr.aria-valuenow]': 'kjValue()',
-    '[attr.aria-valuetext]': 'ariaValueText()',
-    '[attr.aria-disabled]': 'effectiveDisabled() ? "true" : null',
-    '[attr.aria-readonly]': 'ctx.readonly() ? "true" : null',
-    '[attr.aria-label]': 'kjAriaLabel()',
-    '[attr.aria-labelledby]': 'kjAriaLabelledBy()',
-    '[attr.data-orientation]': 'ctx.orientation()',
-    '[attr.data-dragging]': 'dragging() ? "" : null',
-    '[style.--kj-slider-thumb-fraction]': 'fraction()',
-    '[style.touch-action]': '"none"',
-    '(keydown)': 'onKeydown($event)',
-    '(pointerdown)': 'onPointerDown($event)',
-    '(focus)': 'onFocus()',
-    '(blur)': 'onBlur()',
-  },
-})
-export class KjSliderThumb implements KjSliderThumbHandle {
-  /** @internal */
-  readonly ctx = inject(KJ_SLIDER);
-  /** @internal */
-  readonly formCtrl = inject(KjFormControl);
-  private readonly el = inject<ElementRef<HTMLElement>>(ElementRef);
-  private readonly destroyRef = inject(DestroyRef);
-
-  // ── Inputs ───────────────────────────────────────────────────────────────
-
-  /** Per-thumb value. Two-way bindable. CVA-bridged via `KjFormControl`. */
-  readonly kjValue = model<number>(0);
-
-  /** Required when there is no `aria-labelledby` ancestor. */
-  readonly kjAriaLabel = input<string | null>(null);
-
-  /** Alternative to `kjAriaLabel`. */
-  readonly kjAriaLabelledBy = input<string | null>(null);
-
-  /** Per-thumb override of the root's `kjDisplayWith`. */
-  readonly kjAriaValueText = input<string | null>(null);
-
-  /** Per-thumb disable. ORed with the root's `kjDisabled`. */
-  readonly kjDisabled = input<boolean, unknown>(false, { transform: booleanAttribute });
-
-  // ── Internal state ───────────────────────────────────────────────────────
-
-  /** @internal — DOM-order index assigned by the root on register. Mutable for re-indexing. */
-  index = 0;
-
-  private readonly _dragging = signal(false);
-  private readonly _id = `kj-slider-thumb-${++nextId}`;
-  private dragStartValue: number | null = null;
-
-  // ── KjSliderThumbHandle interface ────────────────────────────────────────
-
-  /** @internal */
-  readonly value = this.kjValue.asReadonly();
-
-  /** @internal */
-  get element(): HTMLElement {
-    return this.el.nativeElement;
-  }
-
-  /** @internal */
-  setValue(value: number, _source: KjSliderSource): void {
-    if (this.kjValue() !== value) {
-      this.kjValue.set(value);
-      this.formCtrl.notifyChange(value);
-    }
-  }
-
-  /** @internal */
-  focus(): void {
-    this.el.nativeElement.focus();
-  }
-
-  // ── Computed ─────────────────────────────────────────────────────────────
-
-  protected readonly thumbId = computed(() => this.el.nativeElement.id || this._id);
-
-  /** OR of root + per-thumb disabled. */
-  readonly effectiveDisabled = computed(
-    () => this.ctx.disabled() || this.kjDisabled() || this.formCtrl.disabled(),
-  );
-
-  /** @internal */
-  readonly disabled = this.effectiveDisabled;
-
-  /** Effective `aria-valuemin` — narrowed to partner-thumb position in range mode. */
-  protected readonly effectiveValueMin = computed(() => {
-    const thumbs = this.ctx.thumbs();
-    if (thumbs.length === 2 && this.index === 1) {
-      return thumbs[0].value() + this.ctx.minDistance();
-    }
-    return this.ctx.min();
-  });
-
-  /** Effective `aria-valuemax` — narrowed to partner-thumb position in range mode. */
-  protected readonly effectiveValueMax = computed(() => {
-    const thumbs = this.ctx.thumbs();
-    if (thumbs.length === 2 && this.index === 0) {
-      return thumbs[1].value() - this.ctx.minDistance();
-    }
-    return this.ctx.max();
-  });
-
-  protected readonly ariaValueText = computed<string | null>(() => {
-    const override = this.kjAriaValueText();
-    if (override) return override;
-    const formatter = this.ctx.displayWith();
-    if (formatter) return formatter(this.kjValue(), this.index);
-    // Continuous mode (step <= 0): truncate FP noise.
-    if (this.ctx.step() <= 0) {
-      try {
-        return new Intl.NumberFormat(undefined, { maximumFractionDigits: 2 }).format(this.kjValue());
-      } catch {
-        return String(this.kjValue());
-      }
-    }
-    return null;
-  });
-
-  /** @internal — used by the wrapper layer to position the thumb visually. */
-  readonly fraction = computed(() =>
-    fractionForValue(this.kjValue(), {
-      min: this.ctx.min(),
-      max: this.ctx.max(),
-      inverted: this.ctx.inverted(),
-    }),
-  );
-
-  /** @internal */
-  readonly dragging = this._dragging.asReadonly();
-
-  constructor() {
-    // Register with the root after construction so the host element exists.
-    this.ctx.registerThumb(this);
-    this.destroyRef.onDestroy(() => this.ctx.unregisterThumb(this));
-
-    // Default the value to `min` if uninitialised. afterNextRender so the
-    // host element is in DOM and the root has registered us first.
-    afterNextRender(() => {
-      const v = this.kjValue();
-      if (!Number.isFinite(v)) {
-        this.kjValue.set(this.ctx.min());
-      }
-    });
-
-    // Bridge KjFormControl ↔ kjValue.
-    effect(() => {
-      const cvaValue = this.formCtrl.value();
-      if (cvaValue == null || cvaValue === undefined) return;
-      const num = typeof cvaValue === 'number' ? cvaValue : Number(cvaValue);
-      if (Number.isFinite(num) && num !== this.kjValue()) {
-        this.kjValue.set(num);
-      }
-    });
-  }
-
-  // ── Event handlers ───────────────────────────────────────────────────────
-
-  /** @internal */
-  onKeydown(event: KeyboardEvent): void {
-    if (this.effectiveDisabled() || this.ctx.readonly()) return;
-    const step = this.ctx.step() > 0 ? this.ctx.step() : 1;
-    const pageStep = this.ctx.pageStep();
-    const orientation = this.ctx.orientation();
-    const rtl = this.ctx.direction() === 'rtl';
-
-    switch (event.key) {
-      case 'ArrowUp':
-        event.preventDefault();
-        this.stepBy(step);
-        return;
-      case 'ArrowDown':
-        event.preventDefault();
-        this.stepBy(-step);
-        return;
-      case 'ArrowRight': {
-        event.preventDefault();
-        // Visual semantics: LTR right = increase; RTL right = decrease.
-        // Vertical: right = increase too (APG: visual axis collapses to value axis).
-        const sign = orientation === 'horizontal' && rtl ? -1 : 1;
-        this.stepBy(sign * step);
-        return;
-      }
-      case 'ArrowLeft': {
-        event.preventDefault();
-        const sign = orientation === 'horizontal' && rtl ? 1 : -1;
-        this.stepBy(sign * step);
-        return;
-      }
-      case 'PageUp':
-        event.preventDefault();
-        this.stepBy(pageStep);
-        return;
-      case 'PageDown':
-        event.preventDefault();
-        this.stepBy(-pageStep);
-        return;
-      case 'Home':
-        event.preventDefault();
-        this.ctx.setThumbValue(this.index, this.effectiveValueMin(), 'keyboard');
-        return;
-      case 'End':
-        event.preventDefault();
-        this.ctx.setThumbValue(this.index, this.effectiveValueMax(), 'keyboard');
-        return;
-      case 'Escape':
-        if (this._dragging() && this.dragStartValue != null) {
-          event.preventDefault();
-          this.ctx.setThumbValue(this.index, this.dragStartValue, 'keyboard');
-          this.endDrag(true);
-        }
-        return;
-      default:
-        return;
-    }
-  }
-
-  /** @internal */
-  onPointerDown(event: PointerEvent): void {
-    if (this.effectiveDisabled() || this.ctx.readonly()) return;
-    if (event.button !== undefined && event.button !== 0) return;
-    event.preventDefault();
-    this.dragStartValue = this.kjValue();
-    this._dragging.set(true);
-    this.ctx.beginDrag(this.index);
-
-    const target = this.el.nativeElement;
-    target.setPointerCapture?.(event.pointerId);
-    target.focus();
-
-    const onMove = (e: PointerEvent) => {
-      if (!this._dragging()) return;
-      const value = this.ctx.valueFromClientPosition(e.clientX, e.clientY);
-      this.ctx.setThumbValue(this.index, value, 'pointer');
-    };
-    const onUp = () => {
-      cleanup();
-      this.endDrag(false);
-    };
-    const onCancel = () => {
-      cleanup();
-      this.endDrag(true);
-    };
-    const cleanup = () => {
-      target.removeEventListener('pointermove', onMove);
-      target.removeEventListener('pointerup', onUp);
-      target.removeEventListener('pointercancel', onCancel);
-      target.removeEventListener('lostpointercapture', onCancel);
-    };
-
-    target.addEventListener('pointermove', onMove);
-    target.addEventListener('pointerup', onUp);
-    target.addEventListener('pointercancel', onCancel);
-    target.addEventListener('lostpointercapture', onCancel);
-  }
-
-  /** @internal */
-  onFocus(): void {
-    /* hook for KjFocusRing */
-  }
-
-  /** @internal */
-  onBlur(): void {
-    this.formCtrl.notifyTouched();
-  }
-
-  // ── Internals ────────────────────────────────────────────────────────────
-
-  private stepBy(delta: number): void {
-    const next = this.kjValue() + delta;
-    this.ctx.setThumbValue(this.index, next, 'keyboard');
-  }
-
-  private endDrag(cancelled: boolean): void {
-    this._dragging.set(false);
-    this.dragStartValue = null;
-    this.ctx.endDrag(cancelled);
-  }
-}

package/src/slider/slider-track.ts

@@ -1,70 +0,0 @@
-import {
-  DestroyRef,
-  Directive,
-  ElementRef,
-  afterNextRender,
-  inject,
-  output,
-} from '@angular/core';
-import { KJ_SLIDER } from './slider.context';
-
-/**
- * Pointer-event owner for the slider. Captures `pointerdown` on the track,
- * resolves the target value via the root's geometry helper, picks the
- * nearest thumb (by absolute value distance), and forwards the value.
- *
- * Pointer interactions on a *thumb* are handled by `[kjSliderThumb]` —
- * the track only handles the click-on-empty-track-jump case.
- *
- * Sets `touch-action` to allow page scroll on the cross axis (e.g. vertical
- * page scroll on a horizontal slider) while blocking the on-axis drag.
- *
- * @doc-category Library/Data input
- * @doc
- * @doc-name slider
- */
-@Directive({
-  selector: '[kjSliderTrack]',
-  standalone: true,
-  exportAs: 'kjSliderTrack',
-  host: {
-    '[attr.aria-orientation]': 'ctx.orientation()',
-    '[attr.data-orientation]': 'ctx.orientation()',
-    '[style.touch-action]': 'ctx.orientation() === "vertical" ? "pan-x" : "pan-y"',
-    '(pointerdown)': 'onPointerDown($event)',
-  },
-})
-export class KjSliderTrack {
-  /** @internal */
-  readonly ctx = inject(KJ_SLIDER);
-  private readonly el = inject<ElementRef<HTMLElement>>(ElementRef);
-  private readonly destroyRef = inject(DestroyRef);
-
-  /** Diagnostics: emitted when click-to-jump moves a thumb. */
-  readonly kjTrackClick = output<{ value: number; thumbIndex: number }>();
-
-  constructor() {
-    afterNextRender(() => {
-      this.ctx.setTrackElement(this.el.nativeElement);
-      this.destroyRef.onDestroy(() => this.ctx.setTrackElement(null));
-    });
-  }
-
-  /** @internal */
-  onPointerDown(event: PointerEvent): void {
-    if (this.ctx.disabled() || this.ctx.readonly()) {
-      event.preventDefault();
-      return;
-    }
-    const target = event.target as Element | null;
-    // If the press landed on a thumb, let the thumb directive handle it.
-    if (target && target.closest('[kjSliderThumb]')) return;
-
-    event.preventDefault();
-    const value = this.ctx.valueFromClientPosition(event.clientX, event.clientY);
-    const thumbIndex = this.ctx.nearestThumbIndex(value);
-    this.ctx.setThumbValue(thumbIndex, value, 'pointer');
-    this.ctx.thumbs()[thumbIndex]?.focus();
-    this.kjTrackClick.emit({ value, thumbIndex });
-  }
-}