@vizejs/composable 0.426.3 → 0.428.0

package/registry/files/use-counter.ts

@@ -0,0 +1,147 @@
+import { computed, shallowRef } from "vue";
+import type { ComputedRef, ShallowRef } from "vue";
+
+/** Options for {@link useCounter}. */
+export interface UseCounterOptions {
+  /**
+   * Inclusive lower bound applied to every value the counter takes.
+   *
+   * @default Number.NEGATIVE_INFINITY
+   */
+  readonly min?: number;
+
+  /**
+   * Inclusive upper bound applied to every value the counter takes.
+   *
+   * @default Number.POSITIVE_INFINITY
+   */
+  readonly max?: number;
+}
+
+/** Reactive controls returned by {@link useCounter}. */
+export interface CounterControls {
+  /** Current count. Changes only through the controls, never by assignment. */
+  readonly count: Readonly<ShallowRef<number>>;
+
+  /** Whether the count currently sits on the configured lower bound. */
+  readonly atMin: ComputedRef<boolean>;
+
+  /** Whether the count currently sits on the configured upper bound. */
+  readonly atMax: ComputedRef<boolean>;
+
+  /**
+   * Add `delta` (default `1`) to the count and clamp into the bounds.
+   *
+   * @param delta Amount added; may be negative or infinite.
+   * @returns The count after clamping.
+   */
+  readonly increment: (delta?: number) => number;
+
+  /**
+   * Subtract `delta` (default `1`) from the count and clamp into the bounds.
+   *
+   * @param delta Amount subtracted; may be negative or infinite.
+   * @returns The count after clamping.
+   */
+  readonly decrement: (delta?: number) => number;
+
+  /**
+   * Assign a value directly, clamped into the bounds.
+   *
+   * @returns The count after clamping.
+   */
+  readonly set: (value: number) => number;
+
+  /**
+   * Restore the reset baseline, or establish a new one.
+   *
+   * Without an argument the count returns to the creation-time initial value
+   * (after its original clamping). With an argument, the clamped value
+   * becomes both the new count and the baseline used by later `reset()`
+   * calls.
+   *
+   * @param value Replacement baseline.
+   * @returns The count after clamping.
+   */
+  readonly reset: (value?: number) => number;
+}
+
+/**
+ * Create a clamped counter whose every transition stays inside `[min, max]`.
+ *
+ * All operations clamp instead of failing, including the initial value, so
+ * the count is inside the bounds at every observable moment. Only `NaN` is
+ * rejected — silently corrupting the count is never an option. Purely
+ * synchronous state: safe during server rendering (no browser globals, no
+ * timers) and nothing to dispose, so it works inside and outside reactive
+ * scopes alike. Bounds are fixed at creation and not reactive.
+ *
+ * @example
+ * ```ts
+ * const { count, increment, atMax } = useCounter(9, { min: 0, max: 10 });
+ * increment(); // 10
+ * increment(); // 10 (clamped)
+ * atMax.value; // true
+ * ```
+ *
+ * @param initial Count before any operation, clamped into the bounds.
+ * @default initial 0
+ * @param options Inclusive bounds for every value the counter takes.
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_COUNTER_INVALID_RANGE` when a
+ * bound is `NaN` or `min` exceeds `max`.
+ * @throws `RangeError` tagged `VIZE_COMPOSE_COUNTER_INVALID_VALUE` when an
+ * initial value, operand, or arithmetic result is `NaN` (for example
+ * incrementing `-Infinity` by `Infinity`); the count is left unchanged.
+ * @returns Reactive count, bound flags, and mutation controls.
+ */
+export function useCounter(initial = 0, options: UseCounterOptions = {}): CounterControls {
+  const min = requireBound(options.min ?? Number.NEGATIVE_INFINITY, "min");
+  const max = requireBound(options.max ?? Number.POSITIVE_INFINITY, "max");
+  if (min > max) {
+    throw new RangeError(
+      `[VIZE_COMPOSE_COUNTER_INVALID_RANGE] min must not exceed max; received min ${String(min)} and max ${String(max)}`,
+    );
+  }
+
+  const clamp = (value: number): number => Math.min(max, Math.max(min, value));
+  const count = shallowRef(clamp(requireValue(initial)));
+  let baseline = count.value;
+
+  const setClamped = (next: number): number => {
+    count.value = clamp(requireValue(next));
+    return count.value;
+  };
+
+  const reset = (value?: number): number => {
+    const applied = setClamped(value ?? baseline);
+    if (value !== undefined) baseline = applied;
+    return applied;
+  };
+
+  return {
+    count,
+    atMin: computed(() => count.value === min),
+    atMax: computed(() => count.value === max),
+    increment: (delta = 1) => setClamped(count.value + requireValue(delta)),
+    decrement: (delta = 1) => setClamped(count.value - requireValue(delta)),
+    set: setClamped,
+    reset,
+  };
+}
+
+function requireBound(value: number, label: "min" | "max"): number {
+  if (Number.isNaN(value)) {
+    throw new RangeError(`[VIZE_COMPOSE_COUNTER_INVALID_RANGE] ${label} must not be NaN`);
+  }
+  return value;
+}
+
+function requireValue(value: number): number {
+  if (Number.isNaN(value)) {
+    throw new RangeError(
+      "[VIZE_COMPOSE_COUNTER_INVALID_VALUE] the value is NaN; counter state was left unchanged",
+    );
+  }
+  return value;
+}

package/registry/files/use-css-var.ts

@@ -0,0 +1,191 @@
+import { computed, ref, toValue, watch } from "vue";
+import type { ComputedRef, MaybeRefOrGetter, Ref } from "vue";
+
+/** Style declaration subset used by {@link useCssVar}. */
+export interface CssVarStyle {
+  /** Read a property value. */
+  getPropertyValue(name: string): string;
+
+  /** Write a property value. */
+  setProperty(name: string, value: string | null): void;
+
+  /** Remove a property. */
+  removeProperty(name: string): string;
+}
+
+/** Element subset used by {@link useCssVar}. */
+export interface CssVarTarget {
+  /** Inline style declaration. */
+  readonly style: CssVarStyle;
+}
+
+/** Minimal `MutationObserver` instance. */
+export interface CssVarObserver {
+  /** Start observing `target`. */
+  observe(target: CssVarTarget, options: { attributes: true; attributeFilter: string[] }): void;
+
+  /** Stop observing. */
+  disconnect(): void;
+}
+
+/** Capabilities used by {@link useCssVar}. */
+export interface CssVarHost {
+  /** Resolved (computed) style of a target. */
+  getComputedStyle(target: CssVarTarget): Pick<CssVarStyle, "getPropertyValue">;
+
+  /** Target used when none is given (the document root element). */
+  readonly documentElement: CssVarTarget;
+
+  /** Observer factory used when `observe` is enabled. */
+  readonly createObserver?: (callback: () => void) => CssVarObserver;
+}
+
+/** Options for {@link useCssVar}. */
+export interface UseCssVarOptions {
+  /**
+   * Value used while the variable is unset and during server rendering.
+   *
+   * @default ""
+   */
+  readonly initialValue?: string;
+
+  /**
+   * Re-read the variable when the target's `style` or `class` attribute
+   * changes (MutationObserver).
+   *
+   * @default false
+   */
+  readonly observe?: boolean;
+
+  /**
+   * Style capability for alternate runtimes and tests.
+   *
+   * @default window.getComputedStyle, document.documentElement, and MutationObserver
+   */
+  readonly host?: MaybeRefOrGetter<CssVarHost | null | undefined>;
+}
+
+/** Reactive state returned by {@link useCssVar}. */
+export interface CssVarControls {
+  /** Writable variable value; assignments are written as inline style. */
+  readonly value: Ref<string>;
+
+  /** Whether a style capability and target are attached. */
+  readonly supported: ComputedRef<boolean>;
+}
+
+function browserCssVarHost(): CssVarHost | undefined {
+  if (typeof window === "undefined") return undefined;
+  const view = window;
+  return {
+    getComputedStyle: (target) =>
+      target instanceof view.Element ? view.getComputedStyle(target) : target.style,
+    documentElement: view.document.documentElement,
+    createObserver: (callback) => {
+      const observer = new view.MutationObserver(callback);
+      return {
+        observe: (target, init) => {
+          if (target instanceof view.Node) observer.observe(target, init);
+        },
+        disconnect: () => observer.disconnect(),
+      };
+    },
+  };
+}
+
+function assertVariableName(name: string): void {
+  if (!name.startsWith("--")) {
+    throw new TypeError(
+      `[VIZE_COMPOSE_CSS_VAR_INVALID_NAME] custom property names must start with "--"; received ${JSON.stringify(name)}`,
+    );
+  }
+}
+
+/**
+ * Read and write a CSS custom property reactively.
+ *
+ * The value is read from the target's computed style whenever the
+ * reactive name, target, or host changes (and, with `observe`, when its
+ * `style`/`class` attribute changes). Assigning `value` writes an inline
+ * `style.setProperty`; assigning `""` removes the inline declaration. Values
+ * read from the element are never written back, so a stylesheet-provided
+ * variable is not frozen into inline style.
+ *
+ * Server rendering: nothing is read or written; `value` holds
+ * `initialValue`. Keep server markup and the first client render identical
+ * by rendering from `initialValue` until mounted. The observer and
+ * watchers are released with the owning reactive scope.
+ *
+ * @example
+ * ```ts
+ * const accent = useCssVar("--accent", rootRef, { initialValue: "#0af" });
+ * accent.value.value = "#f60";
+ * ```
+ *
+ * @param name Reactive custom property name, starting with `--`.
+ * @param target Reactive element; defaults to the document root element.
+ * @param options Initial value, observation, and capability.
+ * @default options {}
+ * @returns The writable variable value.
+ * @throws {TypeError} `[VIZE_COMPOSE_CSS_VAR_INVALID_NAME]` when the name does not start with `--`.
+ */
+export function useCssVar(
+  name: MaybeRefOrGetter<string>,
+  target?: MaybeRefOrGetter<CssVarTarget | null | undefined>,
+  options: UseCssVarOptions = {},
+): CssVarControls {
+  const initialValue = options.initialValue ?? "";
+  assertVariableName(toValue(name));
+  const value = ref(initialValue);
+  let lastRead: string | undefined;
+
+  const resolveHost = (): CssVarHost | undefined =>
+    options.host === undefined ? browserCssVarHost() : (toValue(options.host) ?? undefined);
+  const resolveTarget = (host: CssVarHost | undefined): CssVarTarget | undefined => {
+    if (!host) return undefined;
+    return target === undefined ? host.documentElement : (toValue(target) ?? undefined);
+  };
+
+  const read = (host: CssVarHost, element: CssVarTarget, variable: string): void => {
+    const current = host.getComputedStyle(element).getPropertyValue(variable).trim();
+    const next = current === "" ? initialValue : current;
+    lastRead = next;
+    value.value = next;
+  };
+
+  watch(
+    () => {
+      const host = resolveHost();
+      return [host, resolveTarget(host), toValue(name)] as const;
+    },
+    ([host, element, variable], _previous, onCleanup) => {
+      assertVariableName(variable);
+      if (!host || !element) return;
+      read(host, element, variable);
+      if (!(options.observe ?? false) || !host.createObserver) return;
+      const observer = host.createObserver(() => read(host, element, variable));
+      observer.observe(element, { attributes: true, attributeFilter: ["style", "class"] });
+      onCleanup(() => observer.disconnect());
+    },
+    { immediate: true, flush: "sync" },
+  );
+
+  watch(
+    value,
+    (next) => {
+      if (next === lastRead) return;
+      lastRead = undefined;
+      const element = resolveTarget(resolveHost());
+      if (!element) return;
+      const variable = toValue(name);
+      if (next === "") element.style.removeProperty(variable);
+      else element.style.setProperty(variable, next);
+    },
+    { flush: "sync" },
+  );
+
+  return {
+    value,
+    supported: computed(() => resolveTarget(resolveHost()) !== undefined),
+  };
+}

package/registry/files/use-cycle-list.ts

@@ -0,0 +1,136 @@
+import { computed, shallowRef, toValue, watch } from "vue";
+import type { MaybeRefOrGetter, ShallowRef, WritableComputedRef } from "vue";
+
+/** Options for {@link useCycleList}. */
+export interface UseCycleListOptions<Item> {
+  /**
+   * Item selected initially.
+   *
+   * @default the first item
+   */
+  readonly initialValue?: Item;
+
+  /**
+   * Index used when the current item is not in the list.
+   *
+   * @default 0
+   */
+  readonly fallbackIndex?: number;
+
+  /**
+   * Locate an item in the list, for example by id.
+   *
+   * @default Array.prototype.indexOf
+   */
+  readonly getIndexOf?: (item: Item, list: readonly Item[]) => number;
+}
+
+/** Cursor over a list returned by {@link useCycleList}. */
+export interface CycleList<Current, Item> {
+  /** Current item. Writable: assigning moves the cursor to that item. */
+  readonly state: ShallowRef<Current>;
+
+  /** Current index. Writable: assigning wraps around the list. */
+  readonly index: WritableComputedRef<number>;
+
+  /**
+   * Move forward `steps` items (default `1`), wrapping around.
+   *
+   * @returns The new current item.
+   */
+  readonly next: (steps?: number) => Current;
+
+  /**
+   * Move backward `steps` items (default `1`), wrapping around.
+   *
+   * @returns The new current item.
+   */
+  readonly prev: (steps?: number) => Current;
+
+  /**
+   * Jump to `index`, wrapping around.
+   *
+   * @returns The new current item.
+   */
+  readonly go: (index: number) => Current;
+
+  /** The list items, for convenience. */
+  readonly list: Readonly<ShallowRef<readonly Item[]>>;
+}
+
+/**
+ * Cycle through a list with wrap-around navigation.
+ *
+ * Non-empty tuple sources (`["light", "dark", "system"] as const`) yield a
+ * `state` typed as the element union; general arrays may be empty, so their
+ * `state` includes `undefined`. When the list changes, the cursor keeps the
+ * current item if it is still present and otherwise moves to
+ * `fallbackIndex`. Synchronous state: SSR-safe; the list watcher follows the
+ * owning scope.
+ *
+ * @example
+ * ```ts
+ * const { state, next } = useCycleList(["light", "dark", "system"] as const);
+ * next(); // "dark"
+ * ```
+ *
+ * @param list Reactive list to cycle through.
+ * @param options Initial item, fallback index, and item lookup.
+ * @default options {}
+ * @returns The cursor and navigation controls.
+ */
+export function useCycleList<const List extends readonly [unknown, ...unknown[]]>(
+  list: MaybeRefOrGetter<List>,
+  options?: UseCycleListOptions<List[number]>,
+): CycleList<List[number], List[number]>;
+export function useCycleList<Item>(
+  list: MaybeRefOrGetter<readonly Item[]>,
+  options?: UseCycleListOptions<Item>,
+): CycleList<Item | undefined, Item>;
+export function useCycleList<Item>(
+  list: MaybeRefOrGetter<readonly Item[]>,
+  options: UseCycleListOptions<Item> = {},
+): CycleList<Item | undefined, Item> {
+  const items = computed(() => toValue(list));
+  const locate = options.getIndexOf ?? ((item: Item, all: readonly Item[]) => all.indexOf(item));
+  const state = shallowRef<Item | undefined>(
+    "initialValue" in options ? options.initialValue : items.value[0],
+  );
+
+  const wrap = (index: number): number => {
+    const length = items.value.length;
+    return length === 0 ? 0 : ((Math.trunc(index) % length) + length) % length;
+  };
+
+  const index = computed<number>({
+    get: () => {
+      const current = state.value;
+      const found = current === undefined ? -1 : locate(current, items.value);
+      return found === -1 ? wrap(options.fallbackIndex ?? 0) : found;
+    },
+    set: (next) => {
+      state.value = items.value[wrap(next)];
+    },
+  });
+
+  const go = (target: number): Item | undefined => {
+    index.value = target;
+    return state.value;
+  };
+
+  watch(items, () => {
+    const current = state.value;
+    if (current === undefined || locate(current, items.value) === -1) {
+      state.value = items.value[wrap(options.fallbackIndex ?? 0)];
+    }
+  });
+
+  return {
+    state,
+    index,
+    next: (steps = 1) => go(index.value + steps),
+    prev: (steps = 1) => go(index.value - steps),
+    go,
+    list: items,
+  };
+}