@vizejs/composable 0.426.3 → 0.427.0

package/registry/files/locale.ts

@@ -0,0 +1,148 @@
+import { computed, toValue } from "vue";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+
+/** Text flow reported by the internationalization runtime. */
+export type TextDirection = "ltr" | "rtl";
+
+/** Locale selection options for {@link useLocale}. */
+export interface UseLocaleOptions {
+  /**
+   * Locale detector used when the reactive source has no value.
+   *
+   * @default navigator.language when available; otherwise undefined
+   */
+  readonly detect?: () => Intl.Locale | string | null | undefined;
+
+  /**
+   * Locale used when neither the source nor detector provides one.
+   *
+   * @default "en"
+   */
+  readonly fallback?: Intl.Locale | string;
+}
+
+/**
+ * Reactive locale metadata and cached formatter factories.
+ *
+ * Formatter factories propagate `TypeError` and `RangeError` from the
+ * platform `Intl` constructors when the supplied options are invalid.
+ */
+export interface LocaleControls {
+  /** Canonical Unicode locale identifier. */
+  readonly locale: ComputedRef<string>;
+
+  /** Parsed locale details supplied by the internationalization runtime. */
+  readonly details: ComputedRef<Intl.Locale>;
+
+  /** Native writing direction for the active locale. */
+  readonly direction: ComputedRef<TextDirection>;
+
+  /** Return a cached number formatter for the active locale and options. */
+  readonly number: (options?: Intl.NumberFormatOptions) => Intl.NumberFormat;
+
+  /** Return a cached date and time formatter for the active locale and options. */
+  readonly dateTime: (options?: Intl.DateTimeFormatOptions) => Intl.DateTimeFormat;
+
+  /** Return a cached list formatter for the active locale and options. */
+  readonly list: (options?: Intl.ListFormatOptions) => Intl.ListFormat;
+
+  /** Return a cached relative-time formatter for the active locale and options. */
+  readonly relativeTime: (options?: Intl.RelativeTimeFormatOptions) => Intl.RelativeTimeFormat;
+}
+
+const FORMATTER_CACHE_LIMIT = 32;
+
+/**
+ * Create reactive locale metadata and platform-native formatter factories.
+ *
+ * Equivalent formatter options reuse instances. The bounded cache follows the
+ * active locale automatically and prevents repeated constructor overhead in
+ * reactive render paths.
+ *
+ * Detection is lazy and guarded: the default detector reads
+ * `navigator.language` behind a `typeof` check at call time, so importing and
+ * calling this during server rendering is safe, and runtimes without a
+ * `navigator` resolve to the fallback locale. The composable owns no timers
+ * or listeners, so no scope cleanup is required.
+ *
+ * @param source Reactive locale source. Empty values defer to the detector.
+ * @param options Detection and fallback behavior.
+ * @default options {}
+ * @throws `RangeError` on first read of the reactive values when the winning
+ * candidate is not a structurally valid locale identifier.
+ * @returns Reactive locale metadata and cached formatter factories.
+ */
+export function useLocale(
+  source?: MaybeRefOrGetter<Intl.Locale | string | null | undefined>,
+  options: UseLocaleOptions = {},
+): LocaleControls {
+  const locale = computed(() => {
+    const candidate =
+      (source === undefined ? undefined : toValue(source)) ??
+      (options.detect ?? detectBrowserLocale)() ??
+      options.fallback ??
+      "en";
+    return candidate instanceof Intl.Locale
+      ? candidate.toString()
+      : new Intl.Locale(candidate).toString();
+  });
+  const details = computed(() => new Intl.Locale(locale.value));
+  const direction = computed<TextDirection>(() => details.value.getTextInfo().direction ?? "ltr");
+
+  const number = createFormatterCache<Intl.NumberFormatOptions, Intl.NumberFormat>(
+    (activeLocale, formatOptions) => new Intl.NumberFormat(activeLocale, formatOptions),
+  );
+  const dateTime = createFormatterCache<Intl.DateTimeFormatOptions, Intl.DateTimeFormat>(
+    (activeLocale, formatOptions) => new Intl.DateTimeFormat(activeLocale, formatOptions),
+  );
+  const list = createFormatterCache<Intl.ListFormatOptions, Intl.ListFormat>(
+    (activeLocale, formatOptions) => new Intl.ListFormat(activeLocale, formatOptions),
+  );
+  const relativeTime = createFormatterCache<
+    Intl.RelativeTimeFormatOptions,
+    Intl.RelativeTimeFormat
+  >((activeLocale, formatOptions) => new Intl.RelativeTimeFormat(activeLocale, formatOptions));
+
+  return {
+    locale,
+    details,
+    direction,
+    number: (formatOptions) => number(locale.value, formatOptions),
+    dateTime: (formatOptions) => dateTime(locale.value, formatOptions),
+    list: (formatOptions) => list(locale.value, formatOptions),
+    relativeTime: (formatOptions) => relativeTime(locale.value, formatOptions),
+  };
+}
+
+function detectBrowserLocale(): string | undefined {
+  return typeof navigator === "undefined" ? undefined : navigator.language;
+}
+
+function createFormatterCache<Options extends object, Formatter>(
+  create: (locale: string, options?: Options) => Formatter,
+): (locale: string, options?: Options) => Formatter {
+  const cache = new Map<string, Formatter>();
+  return (locale, options) => {
+    const key = `${locale}\u0000${serializeOptions(options)}`;
+    const cached = cache.get(key);
+    if (cached !== undefined) {
+      cache.delete(key);
+      cache.set(key, cached);
+      return cached;
+    }
+    const formatter = create(locale, options);
+    if (cache.size >= FORMATTER_CACHE_LIMIT) {
+      const oldest = cache.keys().next().value;
+      if (oldest !== undefined) cache.delete(oldest);
+    }
+    cache.set(key, formatter);
+    return formatter;
+  };
+}
+
+function serializeOptions(options: object | undefined): string {
+  if (options === undefined) return "";
+  return JSON.stringify(
+    Object.entries(options).sort(([left], [right]) => left.localeCompare(right)),
+  );
+}

package/registry/files/magic-keys.ts

@@ -0,0 +1,298 @@
+import { computed, reactive, readonly, ref, toValue, watch } from "vue";
+import type { ComputedRef, MaybeRefOrGetter, Ref } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Modifier key names recognized in combos (after alias resolution). */
+export type ModifierKeyName = "control" | "shift" | "alt" | "meta";
+
+/**
+ * Validate a key combo string at the type level.
+ *
+ * Combos join lowercase-insensitive key names with `+` or `_`
+ * (`"ctrl+s"`, `"shift_arrowup"`). Empty segments such as `"ctrl+"` or
+ * `"+s"` resolve to `never`, turning typos into compile errors. Non-literal
+ * `string` values are accepted unchanged.
+ */
+export type KeyCombo<Combo extends string> = string extends Combo
+  ? string
+  : Combo extends ""
+    ? never
+    : Combo extends `${infer Head}${"+" | "_"}${infer Tail}`
+      ? Head extends ""
+        ? never
+        : Tail extends ""
+          ? never
+          : KeyCombo<Tail> extends never
+            ? never
+            : Combo
+      : Combo;
+
+/** Default aliases resolved before matching combos. */
+export const DEFAULT_KEY_ALIASES = {
+  ctrl: "control",
+  command: "meta",
+  cmd: "meta",
+  option: "alt",
+  esc: "escape",
+  up: "arrowup",
+  down: "arrowdown",
+  left: "arrowleft",
+  right: "arrowright",
+  " ": "space",
+  spacebar: "space",
+} as const satisfies Readonly<Record<string, string>>;
+
+/** Options shared by the keyboard composables. */
+export interface UseKeyboardTargetOptions {
+  /**
+   * Event target that receives `keydown`/`keyup`.
+   *
+   * @default globalThis.window when available
+   */
+  readonly target?: MaybeRefOrGetter<EventTarget | null | undefined>;
+
+  /**
+   * Register passive listeners.
+   *
+   * @default true
+   */
+  readonly passive?: boolean;
+}
+
+/** Options for {@link useMagicKeys}. */
+export interface UseMagicKeysOptions extends UseKeyboardTargetOptions {
+  /**
+   * Extra aliases merged over {@link DEFAULT_KEY_ALIASES}. Keys and values are
+   * matched case-insensitively.
+   *
+   * @default {}
+   */
+  readonly aliasMap?: Readonly<Record<string, string>>;
+
+  /**
+   * Called for every `keydown`/`keyup` after the pressed set has been
+   * updated. Useful for `preventDefault()` with `passive: false`.
+   *
+   * @default undefined
+   */
+  readonly onEventFired?: (event: KeyboardEvent) => void;
+}
+
+/** Reactive keyboard state returned by {@link useMagicKeys}. */
+export interface MagicKeys {
+  /** Normalized names (`event.key` and `event.code`, lowercase) currently pressed. */
+  readonly current: ReadonlySet<string>;
+
+  /**
+   * Proxy of combo refs created lazily on property access, e.g.
+   * `const { shift, ctrl_s } = keys.combos`.
+   */
+  readonly combos: Readonly<Record<string, ComputedRef<boolean>>>;
+
+  /**
+   * Create (or reuse) a ref that is `true` while every key of the combo is
+   * pressed.
+   *
+   * @param combo Key combo such as `"ctrl+shift+p"`.
+   * @returns Readonly computed ref.
+   */
+  readonly isPressed: <const Combo extends string>(
+    combo: Combo & KeyCombo<Combo>,
+  ) => ComputedRef<boolean>;
+
+  /** Forget every pressed key (for example after a modal steals focus). */
+  readonly reset: () => void;
+}
+
+const modifierNames: ReadonlySet<string> = new Set<ModifierKeyName>([
+  "control",
+  "shift",
+  "alt",
+  "meta",
+]);
+
+/**
+ * Normalize a key name the way combos are matched.
+ *
+ * @param name Raw `KeyboardEvent.key`/`code` or combo segment.
+ * @param aliases Alias table (keys lowercased).
+ * @default aliases DEFAULT_KEY_ALIASES
+ * @returns Lowercase, alias-resolved name.
+ */
+export function normalizeKeyName(
+  name: string,
+  aliases: Readonly<Record<string, string>> = DEFAULT_KEY_ALIASES,
+): string {
+  const lower = name.toLowerCase();
+  return (aliases[lower] ?? lower).toLowerCase();
+}
+
+/**
+ * Track pressed keys and expose reactive key combos.
+ *
+ * Both `event.key` and `event.code` are recorded (lowercased), so `"a"` and
+ * `"keya"` both match. Because some platforms (notably macOS with `meta`)
+ * swallow `keyup` for other keys while a modifier is held, releasing a
+ * modifier clears every non-modifier key; losing window focus clears
+ * everything. Nothing is pressed during server rendering, and listeners are
+ * removed with the owning reactive scope.
+ *
+ * @param options Target, passivity, aliases, and event hook.
+ * @default options {}
+ * @returns Pressed set, lazily created combo refs, and controls.
+ */
+export function useMagicKeys(options: UseMagicKeysOptions = {}): MagicKeys {
+  const aliases: Record<string, string> = { ...DEFAULT_KEY_ALIASES };
+  for (const [alias, key] of Object.entries(options.aliasMap ?? {})) {
+    aliases[alias.toLowerCase()] = key.toLowerCase();
+  }
+  const current = reactive(new Set<string>());
+  const cache = new Map<string, ComputedRef<boolean>>();
+
+  const namesOf = (event: KeyboardEvent): string[] => {
+    const names = new Set<string>();
+    if (event.key) names.add(normalizeKeyName(event.key, aliases));
+    if (event.code) names.add(normalizeKeyName(event.code, aliases));
+    return [...names];
+  };
+  const reset = (): void => current.clear();
+  const onKey = (event: Event): void => {
+    if (!isKeyboardEvent(event)) return;
+    const names = namesOf(event);
+    if (event.type === "keydown") {
+      for (const name of names) current.add(name);
+    } else {
+      for (const name of names) current.delete(name);
+      if (names.some((name) => modifierNames.has(name))) {
+        for (const name of current) if (!modifierNames.has(name)) current.delete(name);
+      }
+    }
+    options.onEventFired?.(event);
+  };
+
+  const stop = watch(
+    () => (options.target === undefined ? browserWindow() : toValue(options.target)),
+    (target, _previous, onCleanup) => {
+      if (!target) return;
+      const listenerOptions: AddEventListenerOptions = { passive: options.passive ?? true };
+      target.addEventListener("keydown", onKey, listenerOptions);
+      target.addEventListener("keyup", onKey, listenerOptions);
+      target.addEventListener("blur", reset, { passive: true });
+      onCleanup(() => {
+        target.removeEventListener("keydown", onKey);
+        target.removeEventListener("keyup", onKey);
+        target.removeEventListener("blur", reset);
+        reset();
+      });
+    },
+    { immediate: true },
+  );
+  tryOnScopeDispose(() => stop.stop());
+
+  const comboRef = (combo: string): ComputedRef<boolean> => {
+    const key = combo.toLowerCase();
+    const cached = cache.get(key);
+    if (cached) return cached;
+    const parts = key
+      .split(/[+_]/)
+      .filter((part) => part !== "")
+      .map((part) => normalizeKeyName(part, aliases));
+    const pressed = computed(() => parts.length > 0 && parts.every((part) => current.has(part)));
+    cache.set(key, pressed);
+    return pressed;
+  };
+
+  const combos = new Proxy<Record<string, ComputedRef<boolean>>>(
+    {},
+    {
+      get: (_target, property) => (typeof property === "string" ? comboRef(property) : undefined),
+      has: (_target, property) => typeof property === "string",
+    },
+  );
+
+  return {
+    current: readonly(current),
+    combos,
+    isPressed: (combo) => comboRef(combo),
+    reset,
+  };
+}
+
+/** Key filter accepted by {@link useKeyPressed}. */
+export type KeyFilter = string | readonly string[] | ((event: KeyboardEvent) => boolean);
+
+/**
+ * Track whether any key matching a filter is held down.
+ *
+ * String filters are normalized like combos (`"esc"` matches `Escape`) and
+ * compared against both `event.key` and `event.code`. The state resets on
+ * window blur and during server rendering is always `false`.
+ *
+ * @param filter Key name(s) or predicate.
+ * @param options Target and passivity.
+ * @default options {}
+ * @returns Readonly ref that is `true` while a matching key is held.
+ */
+export function useKeyPressed(
+  filter: KeyFilter,
+  options: UseKeyboardTargetOptions = {},
+): Readonly<Ref<boolean>> {
+  const held = new Set<string>();
+  const pressed = ref(false);
+  const names =
+    typeof filter === "function"
+      ? undefined
+      : new Set(
+          (typeof filter === "string" ? [filter] : filter).map((name) => normalizeKeyName(name)),
+        );
+  const matches = (event: KeyboardEvent): boolean =>
+    names === undefined
+      ? typeof filter === "function" && filter(event)
+      : names.has(normalizeKeyName(event.key)) || names.has(normalizeKeyName(event.code));
+  const identity = (event: KeyboardEvent): string => event.code || event.key;
+
+  const onDown = (event: Event): void => {
+    if (!isKeyboardEvent(event) || !matches(event)) return;
+    held.add(identity(event));
+    pressed.value = true;
+  };
+  const onUp = (event: Event): void => {
+    if (!isKeyboardEvent(event)) return;
+    held.delete(identity(event));
+    pressed.value = held.size > 0;
+  };
+  const reset = (): void => {
+    held.clear();
+    pressed.value = false;
+  };
+
+  const stop = watch(
+    () => (options.target === undefined ? browserWindow() : toValue(options.target)),
+    (target, _previous, onCleanup) => {
+      if (!target) return;
+      const listenerOptions: AddEventListenerOptions = { passive: options.passive ?? true };
+      target.addEventListener("keydown", onDown, listenerOptions);
+      target.addEventListener("keyup", onUp, listenerOptions);
+      target.addEventListener("blur", reset, { passive: true });
+      onCleanup(() => {
+        target.removeEventListener("keydown", onDown);
+        target.removeEventListener("keyup", onUp);
+        target.removeEventListener("blur", reset);
+        reset();
+      });
+    },
+    { immediate: true },
+  );
+  tryOnScopeDispose(() => stop.stop());
+
+  return readonly(pressed);
+}
+
+function isKeyboardEvent(event: Event): event is KeyboardEvent {
+  return "key" in event && "code" in event;
+}
+
+function browserWindow(): EventTarget | undefined {
+  return typeof window !== "undefined" ? window : undefined;
+}

package/registry/files/math.ts

@@ -0,0 +1,175 @@
+import { computed, isReadonly, isRef, shallowRef, toValue } from "vue";
+import type { ComputedRef, MaybeRefOrGetter, Ref, WritableComputedRef } from "vue";
+
+function clampNumber(value: number, min: number, max: number): number {
+  if (min > max) {
+    throw new RangeError(
+      `[VIZE_COMPOSE_MATH_INVALID_RANGE] min must not exceed max; received [${String(min)}, ${String(max)}]`,
+    );
+  }
+  return Math.min(max, Math.max(min, value));
+}
+
+function isWritableRef(value: MaybeRefOrGetter<number>): value is Ref<number> {
+  return isRef(value) && !isReadonly(value);
+}
+
+/**
+ * Number kept inside `[min, max]`.
+ *
+ * A writable source (a number or a writable ref) yields a writable ref whose
+ * reads and writes are clamped; writes go through to the source ref. A
+ * getter or computed source yields a readonly computed. Bounds are reactive.
+ * Pure derived state: SSR-safe and nothing to dispose.
+ *
+ * @example
+ * ```ts
+ * const volume = useClamp(50, 0, 100);
+ * volume.value = 150; // 100
+ * const progress = useClamp(() => loaded.value / total.value, 0, 1);
+ * ```
+ *
+ * @param value Source number, writable ref, or getter.
+ * @param min Reactive inclusive lower bound.
+ * @param max Reactive inclusive upper bound.
+ * @throws `RangeError` tagged `VIZE_COMPOSE_MATH_INVALID_RANGE` on read or
+ * write when `min > max`.
+ * @returns Writable clamped ref, or a readonly computed for getters.
+ */
+export function useClamp(
+  value: (() => number) | ComputedRef<number>,
+  min: MaybeRefOrGetter<number>,
+  max: MaybeRefOrGetter<number>,
+): ComputedRef<number>;
+export function useClamp(
+  value: number | Ref<number>,
+  min: MaybeRefOrGetter<number>,
+  max: MaybeRefOrGetter<number>,
+): WritableComputedRef<number>;
+export function useClamp(
+  value: MaybeRefOrGetter<number>,
+  min: MaybeRefOrGetter<number>,
+  max: MaybeRefOrGetter<number>,
+): ComputedRef<number> | WritableComputedRef<number> {
+  let source: Ref<number>;
+  if (isWritableRef(value)) source = value;
+  else if (typeof value === "number") source = shallowRef(value);
+  else return computed(() => clampNumber(toValue(value), toValue(min), toValue(max)));
+  return computed({
+    get: () => clampNumber(source.value, toValue(min), toValue(max)),
+    set: (next) => {
+      source.value = clampNumber(next, toValue(min), toValue(max));
+    },
+  });
+}
+
+/** Rounding strategy used by {@link useRound}. */
+export type RoundingMethod = "round" | "floor" | "ceil" | "trunc";
+
+/** Options for {@link useRound}. */
+export interface UseRoundOptions {
+  /**
+   * Decimal places to keep; negative values round to tens, hundreds, …
+   * Reactive.
+   *
+   * @default 0
+   */
+  readonly precision?: MaybeRefOrGetter<number>;
+
+  /**
+   * Rounding strategy.
+   *
+   * @default "round"
+   */
+  readonly method?: RoundingMethod;
+}
+
+/** Multiply by `10 ** places` exactly, by editing the decimal exponent. */
+function shiftExponent(value: number, places: number): number {
+  const [mantissa, exponent = "0"] = String(value).split("e");
+  return Number(`${mantissa}e${Number(exponent) + places}`);
+}
+
+/**
+ * Reactive rounding with decimal precision.
+ *
+ * Uses exponent shifting instead of multiplying by powers of ten, so values
+ * such as `1.005` round to `1.01` at two decimals. Pure derived state.
+ *
+ * @example
+ * ```ts
+ * const price = useRound(rawPrice, { precision: 2 });
+ * ```
+ *
+ * @param value Reactive number.
+ * @param options Precision and method.
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_MATH_INVALID_PRECISION` on read
+ * when the precision is not an integer.
+ * @returns Computed rounded number.
+ */
+export function useRound(
+  value: MaybeRefOrGetter<number>,
+  options: UseRoundOptions = {},
+): ComputedRef<number> {
+  return computed(() => {
+    const precision = toValue(options.precision ?? 0);
+    if (!Number.isInteger(precision)) {
+      throw new RangeError(
+        `[VIZE_COMPOSE_MATH_INVALID_PRECISION] precision must be an integer; received ${String(precision)}`,
+      );
+    }
+    const number = toValue(value);
+    if (!Number.isFinite(number)) return number;
+    const round = Math[options.method ?? "round"];
+    return shiftExponent(round(shiftExponent(number, precision)), -precision);
+  });
+}
+
+/** A `[start, end]` numeric interval. */
+export type ProjectionDomain = readonly [start: number, end: number];
+
+/** Options for {@link useProjection}. */
+export interface UseProjectionOptions {
+  /**
+   * Clamp the result into the target domain.
+   *
+   * @default false
+   */
+  readonly clamp?: boolean;
+}
+
+/**
+ * Linearly map a value from one domain to another.
+ *
+ * Domains are reactive tuples and may be reversed (`[100, 0]`). A degenerate
+ * source domain maps everything to the target start. Pure derived state.
+ *
+ * @example
+ * ```ts
+ * const percent = useProjection(scrollY, () => [0, maxScroll.value], [0, 100], { clamp: true });
+ * ```
+ *
+ * @param value Reactive number in the source domain.
+ * @param from Reactive source domain.
+ * @param to Reactive target domain.
+ * @param options Clamping.
+ * @default options {}
+ * @returns Computed projected number.
+ */
+export function useProjection(
+  value: MaybeRefOrGetter<number>,
+  from: MaybeRefOrGetter<ProjectionDomain>,
+  to: MaybeRefOrGetter<ProjectionDomain>,
+  options: UseProjectionOptions = {},
+): ComputedRef<number> {
+  return computed(() => {
+    const [fromStart, fromEnd] = toValue(from);
+    const [toStart, toEnd] = toValue(to);
+    const span = fromEnd - fromStart;
+    const ratio = span === 0 ? 0 : (toValue(value) - fromStart) / span;
+    const projected = toStart + ratio * (toEnd - toStart);
+    if (!(options.clamp ?? false)) return projected;
+    return Math.min(Math.max(projected, Math.min(toStart, toEnd)), Math.max(toStart, toEnd));
+  });
+}