@vizejs/composable 0.426.3 → 0.428.0

package/registry/files/network.ts

@@ -0,0 +1,229 @@
+import {
+  hasInjectionContext,
+  readonly,
+  ref,
+  shallowRef,
+  toValue,
+  watch,
+  watchPostEffect,
+} from "vue";
+import type { MaybeRefOrGetter, Ref } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Effective connection classes reported by the Network Information API. */
+export type NetworkEffectiveType = "slow-2g" | "2g" | "3g" | "4g";
+
+/** Physical connection types reported by the Network Information API. */
+export type NetworkConnectionType =
+  | "bluetooth"
+  | "cellular"
+  | "ethernet"
+  | "none"
+  | "wifi"
+  | "wimax"
+  | "other"
+  | "unknown";
+
+/** Subset of the (non-standard) `NetworkInformation` interface. */
+export interface NetworkInformationLike extends EventTarget {
+  /** Estimated downlink bandwidth in Mbit/s. */
+  readonly downlink?: number;
+  /** Maximum downlink bandwidth in Mbit/s. */
+  readonly downlinkMax?: number;
+  /** Effective connection class. */
+  readonly effectiveType?: string;
+  /** Estimated round-trip time in milliseconds. */
+  readonly rtt?: number;
+  /** Whether the user requested reduced data usage. */
+  readonly saveData?: boolean;
+  /** Physical connection type. */
+  readonly type?: string;
+}
+
+/** Window-like capability observed by the network composables. */
+export interface NetworkHost extends EventTarget {
+  /** Navigator exposing connectivity. */
+  readonly navigator: {
+    /** Whether the browser believes it is online. */
+    readonly onLine: boolean;
+    /** Network Information API object, where supported. */
+    readonly connection?: NetworkInformationLike;
+  };
+}
+
+/** Options shared by {@link useOnline} and {@link useNetwork}. */
+export interface UseNetworkOptions {
+  /**
+   * Connectivity exposed during server rendering.
+   *
+   * @default true
+   */
+  readonly ssrOnline?: boolean;
+
+  /**
+   * Reactive window capability for alternate runtimes and tests.
+   *
+   * @default globalThis.window when available
+   */
+  readonly host?: MaybeRefOrGetter<NetworkHost | null | undefined>;
+}
+
+/** Reactive network state returned by {@link useNetwork}. */
+export interface NetworkControls {
+  /** Whether the Network Information API is available. `false` during server rendering. */
+  readonly isSupported: Readonly<Ref<boolean>>;
+  /** Whether the browser reports being online. */
+  readonly isOnline: Readonly<Ref<boolean>>;
+  /** Epoch milliseconds of the latest `online` event. */
+  readonly onlineAt: Readonly<Ref<number | null>>;
+  /** Epoch milliseconds of the latest `offline` event. */
+  readonly offlineAt: Readonly<Ref<number | null>>;
+  /** Estimated downlink in Mbit/s. */
+  readonly downlink: Readonly<Ref<number | null>>;
+  /** Maximum downlink in Mbit/s. */
+  readonly downlinkMax: Readonly<Ref<number | null>>;
+  /** Effective connection class, or `null` when unknown. */
+  readonly effectiveType: Readonly<Ref<NetworkEffectiveType | null>>;
+  /** Estimated round-trip time in milliseconds. */
+  readonly rtt: Readonly<Ref<number | null>>;
+  /** Whether the user requested reduced data usage. */
+  readonly saveData: Readonly<Ref<boolean>>;
+  /** Physical connection type, or `null` when unknown. */
+  readonly type: Readonly<Ref<NetworkConnectionType | null>>;
+}
+
+/**
+ * Track connectivity and connection quality.
+ *
+ * Listens for `online`/`offline` on the window and `change` on
+ * `navigator.connection` where available. Unknown or future enum values
+ * normalize to `null` so the public unions stay closed. Server renders
+ * report `ssrOnline` with every quality metric `null`. Inside a component
+ * the connection is read after mounting, so hydration renders the server
+ * values first. Listeners are removed with the owning reactive scope.
+ *
+ * @param options Server fallback and window capability.
+ * @default options {}
+ * @returns Reactive connectivity and connection metrics.
+ */
+export function useNetwork(options: UseNetworkOptions = {}): NetworkControls {
+  const ssrOnline = options.ssrOnline ?? true;
+  const isSupported = ref(false);
+  const isOnline = ref(ssrOnline);
+  const onlineAt = ref<number | null>(null);
+  const offlineAt = ref<number | null>(null);
+  const downlink = ref<number | null>(null);
+  const downlinkMax = ref<number | null>(null);
+  const effectiveType = ref<NetworkEffectiveType | null>(null);
+  const rtt = ref<number | null>(null);
+  const saveData = ref(false);
+  const type = ref<NetworkConnectionType | null>(null);
+  // Inside a component the host is attached by a post-flush job (after the
+  // component mounted), so a hydrating client first renders the same server
+  // fallback. Outside components it is attached synchronously.
+  const hydrated = shallowRef(!hasInjectionContext());
+  if (!hydrated.value) {
+    watchPostEffect(() => {
+      hydrated.value = true;
+    });
+  }
+
+  const stop = watch(
+    () =>
+      hydrated.value
+        ? options.host === undefined
+          ? browserNetworkHost()
+          : toValue(options.host)
+        : undefined,
+    (host, _previous, onCleanup) => {
+      if (!host) {
+        isSupported.value = false;
+        isOnline.value = ssrOnline;
+        return;
+      }
+      const connection = host.navigator.connection;
+      isSupported.value = connection !== undefined;
+      const readConnection = (): void => {
+        isOnline.value = host.navigator.onLine;
+        if (!connection) return;
+        downlink.value = connection.downlink ?? null;
+        downlinkMax.value = connection.downlinkMax ?? null;
+        effectiveType.value = toEffectiveType(connection.effectiveType);
+        rtt.value = connection.rtt ?? null;
+        saveData.value = connection.saveData ?? false;
+        type.value = toConnectionType(connection.type);
+      };
+      const onOnline = (): void => {
+        onlineAt.value = Date.now();
+        readConnection();
+      };
+      const onOffline = (): void => {
+        offlineAt.value = Date.now();
+        readConnection();
+      };
+      readConnection();
+      host.addEventListener("online", onOnline, { passive: true });
+      host.addEventListener("offline", onOffline, { passive: true });
+      connection?.addEventListener("change", readConnection, { passive: true });
+      onCleanup(() => {
+        host.removeEventListener("online", onOnline);
+        host.removeEventListener("offline", onOffline);
+        connection?.removeEventListener("change", readConnection);
+      });
+    },
+    { immediate: true },
+  );
+  tryOnScopeDispose(() => stop.stop());
+
+  return {
+    isSupported: readonly(isSupported),
+    isOnline: readonly(isOnline),
+    onlineAt: readonly(onlineAt),
+    offlineAt: readonly(offlineAt),
+    downlink: readonly(downlink),
+    downlinkMax: readonly(downlinkMax),
+    effectiveType: readonly(effectiveType),
+    rtt: readonly(rtt),
+    saveData: readonly(saveData),
+    type: readonly(type),
+  };
+}
+
+/**
+ * Track whether the browser reports being online.
+ *
+ * Shorthand for `useNetwork(options).isOnline` with the same SSR fallback
+ * and cleanup semantics.
+ *
+ * @param options Server fallback and window capability.
+ * @default options {}
+ * @returns Readonly online flag.
+ */
+export function useOnline(options: UseNetworkOptions = {}): Readonly<Ref<boolean>> {
+  return useNetwork(options).isOnline;
+}
+
+function toEffectiveType(value: string | undefined): NetworkEffectiveType | null {
+  return value === "slow-2g" || value === "2g" || value === "3g" || value === "4g" ? value : null;
+}
+
+function toConnectionType(value: string | undefined): NetworkConnectionType | null {
+  switch (value) {
+    case "bluetooth":
+    case "cellular":
+    case "ethernet":
+    case "none":
+    case "wifi":
+    case "wimax":
+    case "other":
+    case "unknown":
+      return value;
+    default:
+      return null;
+  }
+}
+
+function browserNetworkHost(): NetworkHost | undefined {
+  return typeof window !== "undefined" ? window : undefined;
+}

package/registry/files/on-click-outside.ts

@@ -0,0 +1,178 @@
+import { toValue } from "vue";
+import type { MaybeRefOrGetter } from "vue";
+
+import { resolveElement } from "./element-target.ts";
+import type { MaybeElementTarget } from "./element-target.ts";
+import { tryOnScopeDispose } from "./scope.ts";
+import type { TimeoutScheduler } from "./timeout-scheduler.ts";
+
+/** Window-like capability observed by {@link onClickOutside}. */
+export interface ClickOutsideHost extends EventTarget {
+  /** Document used to detect focus moving into an iframe. */
+  readonly document: { readonly activeElement: Element | null };
+}
+
+/** Ignore entry: an element target or a CSS selector matched against the event path. */
+export type ClickOutsideIgnore = MaybeElementTarget | string;
+
+/** Options for {@link onClickOutside}. */
+export interface OnClickOutsideOptions {
+  /**
+   * Elements (or selectors) whose clicks never count as outside, e.g. the
+   * button that toggles a popover.
+   *
+   * @default []
+   */
+  readonly ignore?: MaybeRefOrGetter<readonly ClickOutsideIgnore[]>;
+
+  /**
+   * Listen in the capture phase so `stopPropagation()` inside the page
+   * cannot hide outside clicks.
+   *
+   * @default true
+   */
+  readonly capture?: boolean;
+
+  /**
+   * Treat focus moving into an `<iframe>` outside the target as an outside
+   * click (iframes swallow pointer events).
+   *
+   * @default false
+   */
+  readonly detectIframe?: boolean;
+
+  /**
+   * Owns the zero-delay timer used for iframe detection.
+   *
+   * @default globalThis timer functions
+   */
+  readonly scheduler?: TimeoutScheduler;
+
+  /**
+   * Reactive window capability for alternate runtimes and tests.
+   *
+   * @default globalThis.window when available
+   */
+  readonly host?: MaybeRefOrGetter<ClickOutsideHost | null | undefined>;
+}
+
+const defaultScheduler: TimeoutScheduler = {
+  setTimeout: (callback, delayMs) => globalThis.setTimeout(callback, delayMs),
+  clearTimeout: (handle) => {
+    globalThis.clearTimeout(handle as ReturnType<typeof setTimeout>);
+  },
+};
+
+/**
+ * Call a handler when the user clicks (or focuses an iframe) outside an element.
+ *
+ * A click counts as outside only when its `pointerdown` also started outside
+ * the target, so drags that begin inside (e.g. text selection) and end
+ * outside are ignored. Event paths (`composedPath()`) make shadow-DOM targets
+ * work. The host is resolved once, when called. Nothing is registered
+ * during server rendering; listeners are removed with the owning scope or by
+ * the returned stop function.
+ *
+ * @param target Reactive element target.
+ * @param handler Called with the outside `PointerEvent`/`MouseEvent` or `FocusEvent`.
+ * @param options Ignore list, phase, iframe detection, and capabilities.
+ * @default options {}
+ * @returns Stop function.
+ */
+export function onClickOutside(
+  target: MaybeElementTarget,
+  handler: (event: Event) => void,
+  options: OnClickOutsideOptions = {},
+): () => void {
+  const host = options.host === undefined ? browserClickHost() : toValue(options.host);
+  if (!host) return () => undefined;
+  const capture = options.capture ?? true;
+  const scheduler = options.scheduler ?? defaultScheduler;
+  let startedInside = false;
+  let pendingBlur: unknown;
+  let hasPendingBlur = false;
+
+  const pathOf = (event: Event): readonly EventTarget[] => {
+    const path = typeof event.composedPath === "function" ? event.composedPath() : [];
+    return path.length > 0 ? path : event.target ? [event.target] : [];
+  };
+  const isIgnored = (event: Event): boolean => {
+    const path = pathOf(event);
+    for (const entry of toValue(options.ignore) ?? []) {
+      if (typeof entry === "string") {
+        if (path.some((node) => matchesSelector(node, entry))) return true;
+        continue;
+      }
+      const element = resolveElement(entry);
+      if (element && path.some((node) => node === element || containsNode(element, node))) {
+        return true;
+      }
+    }
+    return false;
+  };
+  const isInside = (event: Event): boolean => {
+    const element = resolveElement(target);
+    if (!element) return true;
+    return pathOf(event).some((node) => node === element || containsNode(element, node));
+  };
+
+  const onPointerDown = (event: Event): void => {
+    startedInside = isInside(event) || isIgnored(event);
+  };
+  const onClick = (event: Event): void => {
+    const inside = isInside(event) || isIgnored(event);
+    const began = startedInside;
+    startedInside = false;
+    if (inside || began) return;
+    handler(event);
+  };
+  const onBlur = (event: Event): void => {
+    if (hasPendingBlur) scheduler.clearTimeout(pendingBlur);
+    hasPendingBlur = true;
+    pendingBlur = scheduler.setTimeout(() => {
+      hasPendingBlur = false;
+      const active = host.document.activeElement;
+      const element = resolveElement(target);
+      if (active?.tagName === "IFRAME" && element && !containsNode(element, active)) {
+        handler(event);
+      }
+    }, 0);
+  };
+
+  host.addEventListener("pointerdown", onPointerDown, { capture, passive: true });
+  host.addEventListener("click", onClick, { capture, passive: true });
+  if (options.detectIframe) host.addEventListener("blur", onBlur);
+
+  let stopped = false;
+  const stop = (): void => {
+    if (stopped) return;
+    stopped = true;
+    host.removeEventListener("pointerdown", onPointerDown, { capture });
+    host.removeEventListener("click", onClick, { capture });
+    host.removeEventListener("blur", onBlur);
+    if (hasPendingBlur) scheduler.clearTimeout(pendingBlur);
+  };
+  tryOnScopeDispose(stop);
+  return stop;
+}
+
+function containsNode(element: Element, node: EventTarget): boolean {
+  return typeof element.contains === "function" && isNodeLike(node) && element.contains(node);
+}
+
+function isNodeLike(value: EventTarget): value is Node {
+  return "nodeType" in value;
+}
+
+function matchesSelector(node: EventTarget, selector: string): boolean {
+  if (!("matches" in node) || typeof node.matches !== "function") return false;
+  try {
+    return node.matches(selector) === true;
+  } catch {
+    return false;
+  }
+}
+
+function browserClickHost(): ClickOutsideHost | undefined {
+  return typeof window !== "undefined" ? window : undefined;
+}

package/registry/files/on-key-stroke.ts

@@ -0,0 +1,135 @@
+import { toValue, watch } from "vue";
+import type { MaybeRefOrGetter } from "vue";
+
+import { normalizeKeyName } from "./magic-keys.ts";
+import type { KeyFilter } from "./magic-keys.ts";
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Keyboard event names accepted by {@link onKeyStroke}. */
+export type KeyStrokeEventName = "keydown" | "keyup" | "keypress";
+
+/** Options for {@link onKeyStroke}. */
+export interface OnKeyStrokeOptions {
+  /**
+   * Keyboard event to listen for.
+   *
+   * @default "keydown"
+   */
+  readonly eventName?: KeyStrokeEventName;
+
+  /**
+   * Event target.
+   *
+   * @default globalThis.window when available
+   */
+  readonly target?: MaybeRefOrGetter<EventTarget | null | undefined>;
+
+  /**
+   * Register a passive listener (the handler then cannot `preventDefault()`).
+   *
+   * @default false
+   */
+  readonly passive?: boolean;
+
+  /**
+   * Ignore auto-repeated `keydown` events while a key is held.
+   *
+   * @default false
+   */
+  readonly dedupe?: MaybeRefOrGetter<boolean>;
+}
+
+/**
+ * Run a handler when matching keys are pressed.
+ *
+ * `key` accepts a name, a list of names (normalized like combos, so `"esc"`
+ * matches `Escape` and `"a"` matches `KeyA`), a predicate, or `true` for every
+ * key. The listener follows the reactive target and is removed with the
+ * owning scope or the returned stop function; nothing is registered during
+ * server rendering.
+ *
+ * @param key Key filter, or `true` for any key.
+ * @param handler Called with the matching `KeyboardEvent`.
+ * @param options Event name, target, passivity, and dedupe.
+ * @default options {}
+ * @returns Stop function.
+ */
+export function onKeyStroke(
+  key: KeyFilter | true,
+  handler: (event: KeyboardEvent) => void,
+  options: OnKeyStrokeOptions = {},
+): () => void {
+  const eventName = options.eventName ?? "keydown";
+  const names =
+    key === true || typeof key === "function"
+      ? undefined
+      : new Set((typeof key === "string" ? [key] : key).map((name) => normalizeKeyName(name)));
+  const matches = (event: KeyboardEvent): boolean => {
+    if (key === true) return true;
+    if (typeof key === "function") return key(event);
+    return (
+      names !== undefined &&
+      (names.has(normalizeKeyName(event.key)) || names.has(normalizeKeyName(event.code)))
+    );
+  };
+  const listener = (event: Event): void => {
+    if (!isKeyboardEvent(event)) return;
+    if (event.repeat && toValue(options.dedupe)) return;
+    if (matches(event)) handler(event);
+  };
+
+  const stop = watch(
+    () => (options.target === undefined ? browserWindow() : toValue(options.target)),
+    (target, _previous, onCleanup) => {
+      if (!target) return;
+      target.addEventListener(eventName, listener, { passive: options.passive ?? false });
+      onCleanup(() => target.removeEventListener(eventName, listener));
+    },
+    { immediate: true },
+  );
+  const dispose = (): void => stop.stop();
+  tryOnScopeDispose(dispose);
+  return dispose;
+}
+
+/**
+ * {@link onKeyStroke} for `keydown`.
+ *
+ * @param key Key filter, or `true` for any key.
+ * @param handler Called with the matching `KeyboardEvent`.
+ * @param options Target, passivity, and dedupe.
+ * @default options {}
+ * @returns Stop function.
+ */
+export function onKeyDown(
+  key: KeyFilter | true,
+  handler: (event: KeyboardEvent) => void,
+  options: Omit<OnKeyStrokeOptions, "eventName"> = {},
+): () => void {
+  return onKeyStroke(key, handler, { ...options, eventName: "keydown" });
+}
+
+/**
+ * {@link onKeyStroke} for `keyup`.
+ *
+ * @param key Key filter, or `true` for any key.
+ * @param handler Called with the matching `KeyboardEvent`.
+ * @param options Target, passivity, and dedupe.
+ * @default options {}
+ * @returns Stop function.
+ */
+export function onKeyUp(
+  key: KeyFilter | true,
+  handler: (event: KeyboardEvent) => void,
+  options: Omit<OnKeyStrokeOptions, "eventName"> = {},
+): () => void {
+  return onKeyStroke(key, handler, { ...options, eventName: "keyup" });
+}
+
+function isKeyboardEvent(event: Event): event is KeyboardEvent {
+  return "key" in event && "code" in event;
+}
+
+function browserWindow(): EventTarget | undefined {
+  return typeof window !== "undefined" ? window : undefined;
+}