@vizejs/composable 0.426.3 → 0.427.0

package/registry/files/use-performance-observer.ts

@@ -0,0 +1,469 @@
+import {
+  computed,
+  hasInjectionContext,
+  readonly,
+  shallowRef,
+  toValue,
+  unref,
+  watch,
+  watchPostEffect,
+} from "vue";
+import type { ComputedRef, MaybeRef, MaybeRefOrGetter, ShallowRef } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Fields shared by every performance entry consumed by {@link usePerformanceObserver}. */
+export interface PerformanceEntryLike {
+  /** Entry name (URL, mark name, paint name, event type, …). */
+  readonly name: string;
+  /** Entry type this entry was reported for. */
+  readonly entryType: string;
+  /** Start time relative to the time origin, in milliseconds. */
+  readonly startTime: number;
+  /** Duration in milliseconds (`0` for instantaneous entries). */
+  readonly duration: number;
+}
+
+/** `largest-contentful-paint` entry. */
+export interface LargestContentfulPaintEntryLike extends PerformanceEntryLike {
+  /** Entry type discriminant. */
+  readonly entryType: "largest-contentful-paint";
+  /** Render time, or `0` for cross-origin images without Timing-Allow-Origin. */
+  readonly renderTime: number;
+  /** Load time of the resource, or `0` for text. */
+  readonly loadTime: number;
+  /** Visible area of the element in square pixels. */
+  readonly size: number;
+  /** Element `id`, or an empty string. */
+  readonly id: string;
+  /** Image URL, or an empty string for text. */
+  readonly url: string;
+}
+
+/** `layout-shift` entry (Layout Instability API). */
+export interface LayoutShiftEntryLike extends PerformanceEntryLike {
+  /** Entry type discriminant. */
+  readonly entryType: "layout-shift";
+  /** Layout shift score. */
+  readonly value: number;
+  /** Whether a user input happened within the previous 500 ms. */
+  readonly hadRecentInput: boolean;
+  /** Time of the most recent input. */
+  readonly lastInputTime: number;
+}
+
+/** Fields of Event Timing entries (`event` and `first-input`). */
+export interface EventTimingFieldsLike extends PerformanceEntryLike {
+  /** Time the event handlers started running. */
+  readonly processingStart: number;
+  /** Time the event handlers finished running. */
+  readonly processingEnd: number;
+  /** Whether the event was cancelable. */
+  readonly cancelable: boolean;
+  /** Interaction identifier; `0` when the event is not part of an interaction. */
+  readonly interactionId?: number;
+}
+
+/** `event` entry (Event Timing API). */
+export interface EventTimingEntryLike extends EventTimingFieldsLike {
+  /** Entry type discriminant. */
+  readonly entryType: "event";
+}
+
+/** `first-input` entry (Event Timing API). */
+export interface FirstInputEntryLike extends EventTimingFieldsLike {
+  /** Entry type discriminant. */
+  readonly entryType: "first-input";
+}
+
+/** `paint` entry (`first-paint` or `first-contentful-paint`). */
+export interface PaintEntryLike extends PerformanceEntryLike {
+  /** Entry type discriminant. */
+  readonly entryType: "paint";
+}
+
+/** Fields shared by resource and navigation timing entries. */
+export interface ResourceTimingFieldsLike extends PerformanceEntryLike {
+  /** Initiator (`navigation`, `script`, `img`, `fetch`, …). */
+  readonly initiatorType: string;
+  /** Time the request started. */
+  readonly requestStart: number;
+  /** Time the first response byte arrived. */
+  readonly responseStart: number;
+  /** Time the last response byte arrived. */
+  readonly responseEnd: number;
+  /** Transferred size in bytes including headers. */
+  readonly transferSize: number;
+}
+
+/** `resource` entry (Resource Timing API). */
+export interface ResourceTimingEntryLike extends ResourceTimingFieldsLike {
+  /** Entry type discriminant. */
+  readonly entryType: "resource";
+}
+
+/** `navigation` entry (Navigation Timing API). */
+export interface NavigationTimingEntryLike extends ResourceTimingFieldsLike {
+  /** Entry type discriminant. */
+  readonly entryType: "navigation";
+  /** Navigation type (`navigate`, `reload`, `back_forward`, `prerender`). */
+  readonly type: string;
+  /** Time a prerendered page was activated; `0` or absent otherwise. */
+  readonly activationStart?: number;
+  /** End of the `DOMContentLoaded` handlers. */
+  readonly domContentLoadedEventEnd: number;
+  /** End of the `load` handlers. */
+  readonly loadEventEnd: number;
+}
+
+/** `longtask` entry (Long Tasks API). */
+export interface LongTaskEntryLike extends PerformanceEntryLike {
+  /** Entry type discriminant. */
+  readonly entryType: "longtask";
+}
+
+/** `mark` entry (User Timing API). */
+export interface MarkEntryLike extends PerformanceEntryLike {
+  /** Entry type discriminant. */
+  readonly entryType: "mark";
+  /** Detail passed to `performance.mark`. */
+  readonly detail: unknown;
+}
+
+/** `measure` entry (User Timing API). */
+export interface MeasureEntryLike extends PerformanceEntryLike {
+  /** Entry type discriminant. */
+  readonly entryType: "measure";
+  /** Detail passed to `performance.measure`. */
+  readonly detail: unknown;
+}
+
+/** `element` entry (Element Timing API). */
+export interface ElementTimingEntryLike extends PerformanceEntryLike {
+  /** Entry type discriminant. */
+  readonly entryType: "element";
+  /** Value of the `elementtiming` attribute. */
+  readonly identifier: string;
+  /** Render time. */
+  readonly renderTime: number;
+  /** Load time of the resource, or `0` for text. */
+  readonly loadTime: number;
+  /** Element `id`, or an empty string. */
+  readonly id: string;
+  /** Image URL, or an empty string for text. */
+  readonly url: string;
+}
+
+/** `long-animation-frame` entry (Long Animation Frames API). */
+export interface LongAnimationFrameEntryLike extends PerformanceEntryLike {
+  /** Entry type discriminant. */
+  readonly entryType: "long-animation-frame";
+  /** Start of the rendering phase. */
+  readonly renderStart: number;
+  /** Start of style and layout. */
+  readonly styleAndLayoutStart: number;
+  /** Total blocking time of the frame in milliseconds. */
+  readonly blockingDuration: number;
+  /** Time of the first UI event handled in this frame, or `0`. */
+  readonly firstUIEventTimestamp: number;
+}
+
+/** Entry interface delivered for each supported entry type. */
+export interface PerformanceEntryTypeMap {
+  /** Largest Contentful Paint candidates. */
+  readonly "largest-contentful-paint": LargestContentfulPaintEntryLike;
+  /** Layout shifts. */
+  readonly "layout-shift": LayoutShiftEntryLike;
+  /** Event Timing entries. */
+  readonly event: EventTimingEntryLike;
+  /** The first input of the page. */
+  readonly "first-input": FirstInputEntryLike;
+  /** First paint and first contentful paint. */
+  readonly paint: PaintEntryLike;
+  /** Document navigation timing. */
+  readonly navigation: NavigationTimingEntryLike;
+  /** Resource timing. */
+  readonly resource: ResourceTimingEntryLike;
+  /** Tasks longer than 50 ms. */
+  readonly longtask: LongTaskEntryLike;
+  /** User Timing marks. */
+  readonly mark: MarkEntryLike;
+  /** User Timing measures. */
+  readonly measure: MeasureEntryLike;
+  /** Element Timing entries. */
+  readonly element: ElementTimingEntryLike;
+  /** Long animation frames. */
+  readonly "long-animation-frame": LongAnimationFrameEntryLike;
+}
+
+/** Entry type understood by {@link usePerformanceObserver}. */
+export type PerformanceEntryType = keyof PerformanceEntryTypeMap;
+
+/** Options passed to {@link PerformanceObserverLike.observe}. */
+export interface PerformanceObserveInit {
+  /** Single entry type to observe. */
+  readonly type: string;
+  /** Replay entries buffered before observation started. */
+  readonly buffered?: boolean;
+  /** Minimum duration of reported `event` entries. */
+  readonly durationThreshold?: number;
+}
+
+/** Minimal entry list handed to observer callbacks. */
+export interface PerformanceObserverEntryListLike {
+  /** Every entry of this batch. */
+  getEntries(): readonly PerformanceEntryLike[];
+}
+
+/** Minimal `PerformanceObserver` instance. */
+export interface PerformanceObserverLike {
+  /** Start observing one entry type. */
+  observe(options: PerformanceObserveInit): void;
+  /** Stop observing everything. */
+  disconnect(): void;
+  /** Return and clear pending entries. */
+  takeRecords(): readonly PerformanceEntryLike[];
+}
+
+/** Minimal `PerformanceObserver` constructor. */
+export interface PerformanceObserverHost {
+  /** Create an observer. */
+  new (
+    callback: (list: PerformanceObserverEntryListLike, observer: PerformanceObserverLike) => void,
+  ): PerformanceObserverLike;
+  /** Entry types this runtime supports; every type is attempted when absent. */
+  readonly supportedEntryTypes?: readonly string[] | undefined;
+}
+
+/** Options for {@link usePerformanceObserver}. */
+export interface UsePerformanceObserverOptions {
+  /**
+   * `PerformanceObserver` constructor for alternate runtimes and tests. A ref
+   * (not a getter) because the host itself is a constructor function.
+   *
+   * @default window.PerformanceObserver when it exists
+   */
+  readonly PerformanceObserver?: MaybeRef<PerformanceObserverHost | null | undefined>;
+
+  /**
+   * Replay entries recorded before observation started.
+   *
+   * @default false
+   */
+  readonly buffered?: boolean;
+
+  /**
+   * Minimum duration in milliseconds of reported `event` entries (the
+   * platform rounds it and clamps it to at least 16).
+   *
+   * @default undefined (platform default of 104)
+   */
+  readonly durationThreshold?: number;
+
+  /**
+   * Start observing immediately.
+   *
+   * @default true
+   */
+  readonly immediate?: boolean;
+}
+
+/** Callback invoked with correctly typed entries. */
+export type PerformanceObserverCallback<Type extends PerformanceEntryType> = (
+  entries: readonly PerformanceEntryTypeMap[Type][],
+  observer: PerformanceObserverLike,
+) => void;
+
+/** Reactive state and actions returned by {@link usePerformanceObserver}. */
+export interface PerformanceObserverControls<Type extends PerformanceEntryType> {
+  /** Whether an observer exists and supports at least one requested type. */
+  readonly supported: ComputedRef<boolean>;
+
+  /** Requested entry types the runtime supports. */
+  readonly observedTypes: ComputedRef<readonly Type[]>;
+
+  /** Whether an observer is currently connected. */
+  readonly isActive: Readonly<ShallowRef<boolean>>;
+
+  /** Most recent failure thrown by `observe`, cleared on the next start. */
+  readonly error: Readonly<ShallowRef<unknown>>;
+
+  /** Start (or restart) observing. */
+  readonly start: () => void;
+
+  /** Disconnect the observer. Repeated calls are safe. */
+  readonly stop: () => void;
+
+  /**
+   * Return and clear entries that are queued but not yet delivered.
+   *
+   * @returns Pending entries of the requested types.
+   */
+  readonly takeRecords: () => readonly PerformanceEntryTypeMap[Type][];
+}
+
+function isPerformanceObserverHost(candidate: unknown): candidate is PerformanceObserverHost {
+  return typeof candidate === "function";
+}
+
+function browserPerformanceObserver(): PerformanceObserverHost | undefined {
+  if (typeof window === "undefined") return undefined;
+  const candidate: unknown = Reflect.get(window, "PerformanceObserver");
+  return isPerformanceObserverHost(candidate) ? candidate : undefined;
+}
+
+function isEntryOf<Type extends PerformanceEntryType>(
+  entry: PerformanceEntryLike,
+  types: readonly Type[],
+): entry is PerformanceEntryTypeMap[Type] {
+  return types.some((type) => type === entry.entryType);
+}
+
+/**
+ * Observe performance entries with callbacks typed by entry type.
+ *
+ * Each supported type is observed with its own `observe({ type })` call so
+ * `buffered` and `durationThreshold` apply. Types missing from
+ * `PerformanceObserver.supportedEntryTypes` are skipped; `supported` is false
+ * when none remain. The observer follows reactive `entryTypes` and is
+ * disconnected when the owning reactive scope stops; outside a scope the
+ * caller owns `stop()`.
+ *
+ * Server rendering: no observer is created and `supported` is false. Inside
+ * a component the observer connects after mounting, so hydration renders the
+ * server state first.
+ *
+ * @example
+ * ```ts
+ * usePerformanceObserver("largest-contentful-paint", (entries) => {
+ *   console.log(entries.at(-1)?.renderTime);
+ * }, { buffered: true });
+ * ```
+ *
+ * @param entryTypes One entry type or a list of them.
+ * @param callback Receives batches of typed entries.
+ * @param options Constructor host and observation options.
+ * @default options {}
+ * @returns Observer state and actions.
+ */
+export function usePerformanceObserver<const Type extends PerformanceEntryType>(
+  entryTypes: MaybeRefOrGetter<Type | readonly Type[]>,
+  callback: PerformanceObserverCallback<Type>,
+  options: UsePerformanceObserverOptions = {},
+): PerformanceObserverControls<Type> {
+  const { durationThreshold } = options;
+  if (
+    durationThreshold !== undefined &&
+    (!Number.isFinite(durationThreshold) || durationThreshold < 0)
+  ) {
+    throw new RangeError(
+      `[VIZE_COMPOSE_PERF_OBSERVER_INVALID_DURATION_THRESHOLD] durationThreshold must be a finite, non-negative number, received ${String(durationThreshold)}`,
+    );
+  }
+
+  const isActive = shallowRef(false);
+  const error = shallowRef<unknown>(undefined);
+  let observer: PerformanceObserverLike | undefined;
+
+  // Inside a component the host resolves only after mounting, so a hydrating
+  // client renders the server's inactive state first. Outside components it
+  // resolves synchronously.
+  const hydrated = shallowRef(!hasInjectionContext());
+  if (!hydrated.value) {
+    watchPostEffect(() => {
+      hydrated.value = true;
+    });
+  }
+
+  const resolveHost = (): PerformanceObserverHost | undefined => {
+    if (!hydrated.value) return undefined;
+    return options.PerformanceObserver === undefined
+      ? browserPerformanceObserver()
+      : (unref(options.PerformanceObserver) ?? undefined);
+  };
+
+  const requestedTypes = (): readonly Type[] => {
+    const value = toValue(entryTypes);
+    return typeof value === "string" ? [value] : [...new Set(value)];
+  };
+
+  const observedTypes = computed((): readonly Type[] => {
+    const host = resolveHost();
+    if (!host) return [];
+    const supportedTypes = host.supportedEntryTypes;
+    const requested = requestedTypes();
+    return supportedTypes ? requested.filter((type) => supportedTypes.includes(type)) : requested;
+  });
+
+  const disconnect = (): void => {
+    observer?.disconnect();
+    observer = undefined;
+    isActive.value = false;
+  };
+
+  const connect = (): void => {
+    disconnect();
+    const host = resolveHost();
+    const types = observedTypes.value;
+    if (!host || types.length === 0) return;
+    error.value = undefined;
+    const next = new host((list, current) => {
+      const entries = list.getEntries().filter((entry) => isEntryOf(entry, types));
+      if (entries.length > 0) callback(entries, current);
+    });
+    let observing = 0;
+    for (const type of types) {
+      try {
+        next.observe({
+          type,
+          ...(options.buffered === undefined ? {} : { buffered: options.buffered }),
+          ...(type === "event" && durationThreshold !== undefined ? { durationThreshold } : {}),
+        });
+        observing += 1;
+      } catch (cause) {
+        error.value = cause;
+      }
+    }
+    if (observing === 0) {
+      next.disconnect();
+      return;
+    }
+    observer = next;
+    isActive.value = true;
+  };
+
+  let enabled = options.immediate ?? true;
+  const stopWatch = watch(
+    () => [resolveHost(), observedTypes.value.join(" ")],
+    () => {
+      if (enabled) connect();
+    },
+    { immediate: true, flush: "sync" },
+  );
+
+  const stop = (): void => {
+    enabled = false;
+    disconnect();
+  };
+
+  tryOnScopeDispose(() => {
+    stopWatch();
+    stop();
+  });
+
+  return {
+    supported: computed(() => observedTypes.value.length > 0),
+    observedTypes,
+    isActive: readonly(isActive),
+    error: readonly(error),
+    start: () => {
+      enabled = true;
+      connect();
+    },
+    stop,
+    takeRecords: () => {
+      const types = observedTypes.value;
+      return observer ? observer.takeRecords().filter((entry) => isEntryOf(entry, types)) : [];
+    },
+  };
+}

package/registry/files/use-permission.ts

@@ -0,0 +1,220 @@
+import { hasInjectionContext, readonly, ref, toValue, watchEffect } from "vue";
+import type { MaybeRefOrGetter, Ref } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/**
+ * Permission names understood by at least one major browser.
+ *
+ * The `(string & {})` member keeps autocompletion for the well-known names
+ * while still accepting names that browsers add later.
+ */
+export type WellKnownPermissionName =
+  | "accelerometer"
+  | "background-fetch"
+  | "background-sync"
+  | "bluetooth"
+  | "camera"
+  | "clipboard-read"
+  | "clipboard-write"
+  | "display-capture"
+  | "geolocation"
+  | "gyroscope"
+  | "idle-detection"
+  | "local-fonts"
+  | "magnetometer"
+  | "microphone"
+  | "midi"
+  | "nfc"
+  | "notifications"
+  | "payment-handler"
+  | "periodic-background-sync"
+  | "persistent-storage"
+  | "push"
+  | "screen-wake-lock"
+  | "speaker-selection"
+  | "storage-access"
+  | "window-management"
+  | (string & {});
+
+/** Descriptor passed to `navigator.permissions.query`. */
+export interface PermissionDescriptorLike {
+  /** Permission name. */
+  readonly name: WellKnownPermissionName;
+
+  /** Push: only user-visible notifications (required `true` by most browsers). */
+  readonly userVisibleOnly?: boolean;
+
+  /** MIDI: request system-exclusive message access. */
+  readonly sysex?: boolean;
+
+  /** Camera: request pan-tilt-zoom control. */
+  readonly panTiltZoom?: boolean;
+
+  /** Clipboard (Chromium): allow access without a user gesture. */
+  readonly allowWithoutGesture?: boolean;
+}
+
+/** Browser permission state, plus the capability states added by this package. */
+export type PermissionQueryState = "granted" | "denied" | "prompt" | "unsupported" | "unknown";
+
+/** Minimal `PermissionStatus` shape consumed by {@link usePermission}. */
+export interface PermissionStatusLike extends EventTarget {
+  /** Current state reported by the browser. */
+  readonly state: string;
+}
+
+/** Minimal `Permissions` shape consumed by {@link usePermission}. */
+export interface PermissionsHost {
+  /**
+   * Query one permission. Rejects (TypeError) for names the browser does not
+   * know. Declared with method syntax so the DOM `Permissions` object, whose
+   * descriptor names are a narrower union, satisfies this interface.
+   */
+  query(descriptor: PermissionDescriptorLike): Promise<PermissionStatusLike>;
+}
+
+/** Options for {@link usePermission}. */
+export interface UsePermissionOptions {
+  /**
+   * Permissions capability for alternate runtimes and tests.
+   *
+   * @default window.navigator.permissions when a browser window exists
+   */
+  readonly host?: MaybeRefOrGetter<PermissionsHost | null | undefined>;
+
+  /**
+   * State exposed before the first query settles and during server rendering.
+   *
+   * @default "unknown"
+   */
+  readonly initialState?: PermissionQueryState;
+}
+
+/** Reactive state returned by {@link usePermission}. */
+export interface PermissionControls {
+  /**
+   * Current permission state. `"unsupported"` means the Permissions API (or
+   * this permission name) is unavailable; `"unknown"` means no answer yet.
+   */
+  readonly state: Readonly<Ref<PermissionQueryState>>;
+
+  /** Whether a Permissions capability is attached. */
+  readonly supported: Readonly<Ref<boolean>>;
+
+  /**
+   * Query the permission again and resubscribe to its changes.
+   *
+   * @returns The settled state.
+   */
+  readonly query: () => Promise<PermissionQueryState>;
+}
+
+function normalizeState(state: string): PermissionQueryState {
+  return state === "granted" || state === "denied" || state === "prompt" ? state : "unknown";
+}
+
+function browserPermissions(): PermissionsHost | undefined {
+  if (typeof window === "undefined") return undefined;
+  return window.navigator.permissions ?? undefined;
+}
+
+function toDescriptor(
+  name: WellKnownPermissionName | PermissionDescriptorLike,
+): PermissionDescriptorLike {
+  return typeof name === "string" ? { name } : name;
+}
+
+/**
+ * Observe a browser permission reactively.
+ *
+ * The permission is queried when the composable is created and whenever
+ * the reactive name/descriptor or host changes; the `change` event of the
+ * returned `PermissionStatus` keeps `state` current (for example after the
+ * user revokes camera access in the site settings). The subscription is
+ * removed when the name changes and when the owning reactive scope stops.
+ *
+ * Server rendering: no browser window exists, so nothing is queried and
+ * `state` stays at `initialState` (`"unknown"`) with `supported` false.
+ * Unknown names (the browser rejects the query) report `"unsupported"`.
+ * Inside a component the first query runs after mounting, so hydration
+ * renders `initialState` exactly like the server did.
+ *
+ * @example
+ * ```ts
+ * const { state } = usePermission("camera");
+ * const canUseCamera = computed(() => state.value === "granted");
+ * ```
+ *
+ * @param name Reactive permission name or full descriptor.
+ * @param options Capability host and initial state.
+ * @default options {}
+ * @returns The reactive permission state and a re-query control.
+ */
+export function usePermission(
+  name: MaybeRefOrGetter<WellKnownPermissionName | PermissionDescriptorLike>,
+  options: UsePermissionOptions = {},
+): PermissionControls {
+  const initialState = options.initialState ?? "unknown";
+  const state = ref<PermissionQueryState>(initialState);
+  const supported = ref(false);
+  let generation = 0;
+  let unsubscribe: (() => void) | undefined;
+  let active = true;
+
+  const resolveHost = (): PermissionsHost | undefined =>
+    options.host === undefined ? browserPermissions() : (toValue(options.host) ?? undefined);
+
+  const release = (): void => {
+    unsubscribe?.();
+    unsubscribe = undefined;
+  };
+
+  const query = async (): Promise<PermissionQueryState> => {
+    const current = ++generation;
+    release();
+    const host = resolveHost();
+    supported.value = host !== undefined;
+    if (!host) {
+      // Without a browser window (server rendering) the answer is unknown,
+      // not "unsupported": keep the initial state so hydration matches.
+      state.value = typeof window === "undefined" ? initialState : "unsupported";
+      return state.value;
+    }
+    let status: PermissionStatusLike;
+    try {
+      status = await host.query(toDescriptor(toValue(name)));
+    } catch {
+      if (current === generation) state.value = "unsupported";
+      return "unsupported";
+    }
+    if (current !== generation || !active) return normalizeState(status.state);
+    const update = (): void => {
+      state.value = normalizeState(status.state);
+    };
+    update();
+    status.addEventListener("change", update);
+    unsubscribe = () => status.removeEventListener("change", update);
+    return state.value;
+  };
+
+  if (typeof window !== "undefined" || options.host !== undefined) {
+    // `query` reads the name and host synchronously, so the effect re-runs
+    // when either changes. Inside a component the first query waits for the
+    // post-render flush: hydration renders `initialState` like the server.
+    watchEffect(
+      () => {
+        void query();
+      },
+      { flush: hasInjectionContext() ? "post" : "sync" },
+    );
+  }
+
+  tryOnScopeDispose(() => {
+    active = false;
+    generation += 1;
+    release();
+  });
+
+  return { state: readonly(state), supported: readonly(supported), query };
+}