@vizejs/composable 0.426.3 → 0.427.0

package/registry/files/use-style-tag.ts

@@ -0,0 +1,200 @@
+import { hasInjectionContext, isRef, onMounted, readonly, ref, toValue, watch } from "vue";
+import type { MaybeRefOrGetter, Ref } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** `<style>` subset used by {@link useStyleTag}. */
+export interface StyleTagElement {
+  /** Style sheet text. */
+  textContent: string | null;
+
+  /** Write an attribute. */
+  setAttribute(name: string, value: string): void;
+}
+
+/** Document capability used by {@link useStyleTag}. */
+export interface StyleTagHost {
+  /** Find an existing `<style>` with the given `id`. */
+  findStyle(id: string): StyleTagElement | undefined;
+
+  /** Create a detached `<style>`. */
+  createStyle(): StyleTagElement;
+
+  /** Attach a style element to `<head>`. */
+  append(element: StyleTagElement): void;
+
+  /** Detach a style element. */
+  remove(element: StyleTagElement): void;
+}
+
+/** Options for {@link useStyleTag}. */
+export interface UseStyleTagOptions {
+  /**
+   * Element `id`. Instances sharing an id share one element (last write
+   * wins, first unload removes it), so give every independent style sheet
+   * its own stable id. The default is a constant rather than a generated
+   * counter because generated ids differ between server and client.
+   *
+   * @default "vize-style"
+   */
+  readonly id?: string;
+
+  /**
+   * `media` attribute.
+   *
+   * @default undefined
+   */
+  readonly media?: string;
+
+  /**
+   * CSP nonce.
+   *
+   * @default undefined
+   */
+  readonly nonce?: string;
+
+  /**
+   * Attach the style element when created.
+   *
+   * @default true
+   */
+  readonly immediate?: boolean;
+
+  /**
+   * Document capability for alternate runtimes and tests.
+   *
+   * @default window.document's `<head>`
+   */
+  readonly host?: MaybeRefOrGetter<StyleTagHost | null | undefined>;
+}
+
+/** Reactive state and actions returned by {@link useStyleTag}. */
+export interface StyleTagControls {
+  /** Element id in use. */
+  readonly id: string;
+
+  /**
+   * Style sheet text. Writable; when a getter was passed, the next getter
+   * change overwrites manual assignments.
+   */
+  readonly css: Ref<string>;
+
+  /** Whether the style element is attached. */
+  readonly loaded: Readonly<Ref<boolean>>;
+
+  /**
+   * Attach (or adopt an existing element with the same id) and apply `css`.
+   *
+   * @returns Whether a style element is attached afterwards.
+   */
+  readonly load: () => boolean;
+
+  /** Remove the style element. */
+  readonly unload: () => void;
+}
+
+function browserStyleHost(): StyleTagHost | undefined {
+  if (typeof window === "undefined") return undefined;
+  const { document, HTMLStyleElement } = window;
+  return {
+    findStyle: (id) => {
+      const found = document.getElementById(id);
+      return found instanceof HTMLStyleElement ? found : undefined;
+    },
+    createStyle: () => document.createElement("style"),
+    append: (element) => {
+      if (element instanceof HTMLStyleElement) document.head.append(element);
+    },
+    remove: (element) => {
+      if (element instanceof HTMLStyleElement) element.remove();
+    },
+  };
+}
+
+/**
+ * Inject a reactive `<style>` element.
+ *
+ * The element's text follows `css`. An existing `<style>` with the same
+ * id — for example one emitted in server-rendered HTML — is adopted instead
+ * of duplicated, which keeps hydration free of flashes. The element is
+ * removed when the owning reactive scope stops or `unload` is called.
+ *
+ * Server rendering: nothing is injected and `loaded` is false. Emit the
+ * server-side `<style id>` through the application's head manager using the
+ * same id to make the client adopt it.
+ *
+ * @example
+ * ```ts
+ * const { css } = useStyleTag(() => `:root { --accent: ${accent.value} }`, { id: "theme" });
+ * ```
+ *
+ * @param css Reactive style sheet text.
+ * @param options Id, attributes, timing, and capability.
+ * @default options {}
+ * @returns Style state and actions.
+ */
+export function useStyleTag(
+  css: MaybeRefOrGetter<string>,
+  options: UseStyleTagOptions = {},
+): StyleTagControls {
+  const id = options.id ?? "vize-style";
+  const state: Ref<string> = isRef(css) ? css : ref(toValue(css));
+  const loaded = ref(false);
+  let element: StyleTagElement | undefined;
+
+  const resolveHost = (): StyleTagHost | undefined =>
+    options.host === undefined ? browserStyleHost() : (toValue(options.host) ?? undefined);
+
+  if (typeof css === "function") {
+    watch(css, (next) => {
+      state.value = next;
+    });
+  }
+
+  const load = (): boolean => {
+    if (element) return true;
+    const host = resolveHost();
+    if (!host) return false;
+    const existing = host.findStyle(id);
+    const target = existing ?? host.createStyle();
+    if (!existing) {
+      target.setAttribute("id", id);
+      if (options.media !== undefined) target.setAttribute("media", options.media);
+      if (options.nonce !== undefined) target.setAttribute("nonce", options.nonce);
+    }
+    if (target.textContent !== state.value) target.textContent = state.value;
+    if (!existing) host.append(target);
+    element = target;
+    loaded.value = true;
+    return true;
+  };
+
+  const unload = (): void => {
+    if (element) resolveHost()?.remove(element);
+    element = undefined;
+    loaded.value = false;
+  };
+
+  watch(
+    state,
+    (next) => {
+      if (element && element.textContent !== next) element.textContent = next;
+    },
+    { flush: "sync" },
+  );
+
+  if (options.immediate ?? true) {
+    // Inside a component the tag is attached after mounting, so a hydrating
+    // client renders `loaded: false` exactly like the server did.
+    if (hasInjectionContext()) {
+      onMounted(() => {
+        load();
+      });
+    } else {
+      load();
+    }
+  }
+  tryOnScopeDispose(unload);
+
+  return { id, css: state, loaded: readonly(loaded), load, unload };
+}

package/registry/files/use-supported.ts

@@ -0,0 +1,26 @@
+import { computed, hasInjectionContext, shallowRef } from "vue";
+import type { ComputedRef } from "vue";
+
+import { useMounted } from "./use-mounted.ts";
+
+/**
+ * Hydration-stable feature detection.
+ *
+ * Inside a component the result is `false` until the component mounts and
+ * then reflects `check()`, so server and hydrating client render the same
+ * fallback first. Outside a component it is evaluated right away when a
+ * browser `window` exists and stays `false` otherwise. `check` may read
+ * reactive state; the result recomputes when it changes.
+ *
+ * @example
+ * ```ts
+ * const isSupported = useSupported(() => "share" in navigator);
+ * ```
+ *
+ * @param check Returns a truthy value when the feature is available.
+ * @returns Computed support flag.
+ */
+export function useSupported(check: () => unknown): ComputedRef<boolean> {
+  const ready = hasInjectionContext() ? useMounted() : shallowRef(typeof window !== "undefined");
+  return computed(() => ready.value && Boolean(check()));
+}

package/registry/files/use-throttled.ts

@@ -0,0 +1,215 @@
+import { shallowRef, toValue, watch } from "vue";
+import type { MaybeRefOrGetter, ShallowRef } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+import type { TimeoutScheduler } from "./timeout-scheduler.ts";
+
+/** Options for {@link useThrottled}. */
+export interface UseThrottledOptions {
+  /**
+   * Apply the first change of a cooldown window immediately.
+   *
+   * @default true
+   */
+  readonly leading?: boolean;
+
+  /**
+   * Apply the newest change collected during a cooldown window when the
+   * window ends. When disabled, changes inside a window are dropped.
+   *
+   * @default true
+   */
+  readonly trailing?: boolean;
+
+  /**
+   * Applies the timing policy when no browser `window` is available.
+   *
+   * Keep this disabled during server rendering, where the throttled view
+   * mirrors the source synchronously instead of starting timers. Enable it
+   * for native, desktop, worker, and test runtimes whose scheduler is
+   * lifecycle-bound.
+   *
+   * @default false
+   */
+  readonly runOnServer?: boolean;
+
+  /**
+   * Owns the single-shot cooldown timer.
+   *
+   * @default globalThis timer functions
+   */
+  readonly scheduler?: TimeoutScheduler;
+}
+
+/** Reactive throttled view and controls returned by {@link useThrottled}. */
+export interface ThrottledControls<Value> {
+  /** Readonly view of the source updated at most once per cooldown window. */
+  readonly throttled: Readonly<ShallowRef<Value>>;
+
+  /** Whether a trailing update is waiting for the current window to end. */
+  readonly pending: Readonly<ShallowRef<boolean>>;
+
+  /**
+   * Discard the waiting trailing update and close the cooldown window, so
+   * the next change starts fresh on a leading edge.
+   *
+   * @returns Whether a waiting trailing update was discarded.
+   */
+  readonly cancel: () => boolean;
+
+  /**
+   * Apply the waiting trailing update immediately and close the cooldown
+   * window. Without a waiting update the window is left untouched.
+   *
+   * @returns Whether a waiting trailing update was applied.
+   */
+  readonly flush: () => boolean;
+}
+
+const defaultScheduler: TimeoutScheduler = {
+  setTimeout: (callback, delayMs) => globalThis.setTimeout(callback, delayMs),
+  clearTimeout: (handle) => {
+    globalThis.clearTimeout(handle as ReturnType<typeof setTimeout>);
+  },
+};
+
+/**
+ * Create a readonly throttled view of a reactive source.
+ *
+ * Changes are observed with `flush: "sync"`, so every synchronous write
+ * counts. Outside a cooldown window, a change applies immediately when
+ * {@link UseThrottledOptions.leading} is enabled (otherwise it waits as a
+ * trailing update) and opens a window of `waitMs` milliseconds. Changes
+ * inside a window are collected as the trailing candidate; when the window
+ * ends with a candidate waiting, the source value current at that moment is
+ * applied and the next window opens back to back, keeping applications
+ * spaced by `waitMs`. A window that ends without a candidate closes silently.
+ * `waitMs` is reactive and is read each time a window opens; changing it
+ * never disturbs an already-open window. A wait of `0` still defers trailing
+ * updates to the next scheduler tick.
+ *
+ * Server rendering is explicit: without a browser `window` (and with
+ * {@link UseThrottledOptions.runOnServer} disabled) no timer ever starts and
+ * the view mirrors the source synchronously, so server-rendered output shows
+ * current values and nothing leaks. `pending` stays `false` and the controls
+ * report `false` in that mode.
+ *
+ * Cleanup rule: the watcher and any open window timer are released when the
+ * owning reactive scope stops; call inside an active scope. Outside one, the
+ * watcher lives as long as the source and `cancel()` only clears the window.
+ *
+ * @example
+ * ```ts
+ * const scrollY = shallowRef(0);
+ * const { throttled } = useThrottled(scrollY, 100);
+ * scrollY.value = 40; // applied immediately (leading edge)
+ * scrollY.value = 80; // applied when the 100ms window ends
+ * ```
+ *
+ * @param source Reactive source to throttle.
+ * @param waitMs Reactive cooldown in milliseconds; must be finite and at
+ * least zero. Fractions are truncated.
+ * @param options Edge policy and runtime scheduling overrides.
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_THROTTLE_INVALID_WAIT` when the
+ * resolved wait is not finite or is negative, both synchronously at creation
+ * (even in mirror mode) and again each time a window opens.
+ * @throws `TypeError` tagged `VIZE_COMPOSE_THROTTLE_INVALID_EDGES` when both
+ * `leading` and `trailing` are disabled, because updates could then never
+ * propagate.
+ * @returns Readonly throttled view, pending flag, and cancel/flush controls.
+ */
+export function useThrottled<Value>(
+  source: MaybeRefOrGetter<Value>,
+  waitMs: MaybeRefOrGetter<number>,
+  options: UseThrottledOptions = {},
+): ThrottledControls<Value> {
+  const leading = options.leading ?? true;
+  const trailing = options.trailing ?? true;
+  if (!leading && !trailing) {
+    throw new TypeError(
+      "[VIZE_COMPOSE_THROTTLE_INVALID_EDGES] at least one of leading or trailing must be enabled",
+    );
+  }
+  const scheduler = options.scheduler ?? defaultScheduler;
+  const throttled = shallowRef(toValue(source));
+  const pending = shallowRef(false);
+  let windowHandle: unknown;
+  let windowOpen = false;
+
+  // Fail synchronously for invalid initial input, even in mirror mode.
+  resolveWaitMs(toValue(waitMs));
+
+  const openWindow = (): void => {
+    windowOpen = true;
+    windowHandle = scheduler.setTimeout(
+      () => {
+        windowHandle = undefined;
+        if (!pending.value) {
+          windowOpen = false;
+          return;
+        }
+        pending.value = false;
+        throttled.value = toValue(source);
+        openWindow();
+      },
+      resolveWaitMs(toValue(waitMs)),
+    );
+  };
+
+  const closeWindow = (): void => {
+    if (windowOpen) scheduler.clearTimeout(windowHandle);
+    windowHandle = undefined;
+    windowOpen = false;
+    pending.value = false;
+  };
+
+  const cancel = (): boolean => {
+    const hadTrailing = pending.value;
+    closeWindow();
+    return hadTrailing;
+  };
+
+  const flush = (): boolean => {
+    if (!pending.value) return false;
+    closeWindow();
+    throttled.value = toValue(source);
+    return true;
+  };
+
+  watch(
+    () => toValue(source),
+    (next) => {
+      if (typeof window === "undefined" && !(options.runOnServer ?? false)) {
+        throttled.value = next;
+        return;
+      }
+      if (windowOpen) {
+        if (trailing) pending.value = true;
+        return;
+      }
+      if (leading) {
+        throttled.value = next;
+      } else {
+        pending.value = true;
+      }
+      openWindow();
+    },
+    { flush: "sync" },
+  );
+
+  tryOnScopeDispose(() => {
+    cancel();
+  });
+
+  return { throttled, pending, cancel, flush };
+}
+
+function resolveWaitMs(value: number): number {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new RangeError(
+      `[VIZE_COMPOSE_THROTTLE_INVALID_WAIT] waitMs must be finite and at least zero; received ${String(value)}`,
+    );
+  }
+  return Math.trunc(value);
+}