@vizejs/composable 0.426.3 → 0.428.0

package/registry/files/use-display-names.ts

@@ -0,0 +1,122 @@
+import { computed, toValue } from "vue";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+
+import { useLocale } from "./locale.ts";
+
+/** Kinds of codes `Intl.DisplayNames` can name. */
+export type DisplayNamesKind =
+  | "language"
+  | "region"
+  | "script"
+  | "currency"
+  | "calendar"
+  | "dateTimeField";
+
+/** Options for {@link useDisplayNames}. */
+export interface UseDisplayNamesOptions {
+  /** Kind of code to name. */
+  readonly type: DisplayNamesKind;
+
+  /**
+   * Locale the names are written in. Pass it explicitly for
+   * hydration-stable server rendering.
+   *
+   * @default the browser language, otherwise "en"
+   */
+  readonly locale?: string | Intl.Locale;
+
+  /**
+   * Name length.
+   *
+   * @default "long"
+   */
+  readonly style?: "narrow" | "short" | "long";
+
+  /**
+   * What to return for a well-formed code without a name: the code itself
+   * or `undefined`.
+   *
+   * @default "code"
+   */
+  readonly fallback?: "code" | "none";
+
+  /**
+   * Language names: `"dialect"` names `"en-GB"` "British English",
+   * `"standard"` names it "English (United Kingdom)".
+   *
+   * @default "dialect"
+   */
+  readonly languageDisplay?: "dialect" | "standard";
+}
+
+/** Reactive display names returned by {@link useDisplayNames}. */
+export interface DisplayNamesControls {
+  /** Canonical locale in use. */
+  readonly locale: ComputedRef<string>;
+
+  /** Display names instance for the current locale and options. */
+  readonly displayNames: ComputedRef<Intl.DisplayNames>;
+
+  /** Name of the reactive code; `undefined` for malformed or unnamed codes. */
+  readonly name: ComputedRef<string | undefined>;
+
+  /**
+   * Name any code. Malformed codes return `undefined` instead of throwing.
+   *
+   * @param code Language tag, region, script, currency, calendar, or field code.
+   * @returns The localized name.
+   */
+  readonly of: (code: string) => string | undefined;
+}
+
+function browserLanguage(): string | undefined {
+  return typeof window === "undefined" ? undefined : window.navigator.language;
+}
+
+/**
+ * Localized names of languages, regions, scripts, currencies, calendars, and
+ * date-time fields (`Intl.DisplayNames`): `"JP"` → "Japan", `"ja"` → "日本語"
+ * in Japanese, `"EUR"` → "Euro".
+ *
+ * Malformed codes yield `undefined` rather than the platform `RangeError`,
+ * so user-entered codes never crash rendering; invalid *options* still
+ * throw on first read. Derived state only: no listeners or timers, and
+ * deterministic during server rendering when the locale is explicit.
+ *
+ * @example
+ * ```ts
+ * const { name } = useDisplayNames(regionCode, { type: "region", locale: "en" });
+ * ```
+ *
+ * @param code Reactive code to name.
+ * @param options Reactive kind, locale, and display options.
+ * @returns Reactive name and a naming helper.
+ */
+export function useDisplayNames(
+  code: MaybeRefOrGetter<string | null | undefined>,
+  options: MaybeRefOrGetter<UseDisplayNamesOptions>,
+): DisplayNamesControls {
+  const localeControls = useLocale(() => toValue(options).locale, { detect: browserLanguage });
+  const displayNames = computed(() => {
+    const { locale: _locale, ...displayOptions } = toValue(options);
+    return new Intl.DisplayNames(localeControls.locale.value, displayOptions);
+  });
+  const of = (value: string): string | undefined => {
+    const names = displayNames.value;
+    try {
+      return names.of(value);
+    } catch (error) {
+      if (error instanceof RangeError) return undefined;
+      throw error;
+    }
+  };
+  return {
+    locale: localeControls.locale,
+    displayNames,
+    name: computed(() => {
+      const current = toValue(code);
+      return current === null || current === undefined || current === "" ? undefined : of(current);
+    }),
+    of,
+  };
+}

package/registry/files/use-document-title.ts

@@ -0,0 +1,196 @@
+import { computed, hasInjectionContext, isRef, ref, toValue, watch } from "vue";
+import type { ComputedRef, MaybeRefOrGetter, Ref } from "vue";
+
+import { useMounted } from "./use-mounted.ts";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Document subset used by {@link useDocumentTitle}. */
+export interface DocumentTitleHost {
+  /** Current document title (readable and writable). */
+  title: string;
+
+  /**
+   * Observe external title changes (for example by other libraries).
+   * Returns a function that stops observing.
+   */
+  readonly observeTitle?: (callback: () => void) => () => void;
+}
+
+/** Title template: a string containing `%s`, or a formatting function. */
+export type DocumentTitleTemplate = string | ((title: string) => string);
+
+/** Title applied when the owning scope stops. */
+export type DocumentTitleRestore =
+  | false
+  | "previous"
+  | ((originalTitle: string, currentTitle: string) => string);
+
+/** Options for {@link useDocumentTitle}. */
+export interface UseDocumentTitleOptions {
+  /**
+   * Template applied to every title written to the document.
+   *
+   * @default "%s"
+   */
+  readonly template?: DocumentTitleTemplate;
+
+  /**
+   * Title restored when the owning reactive scope stops: `false` leaves the
+   * current title, `"previous"` restores the title seen at creation, and a
+   * function computes it.
+   *
+   * @default false
+   */
+  readonly restoreOnDispose?: DocumentTitleRestore;
+
+  /**
+   * Follow title changes made outside this composable.
+   *
+   * @default false
+   */
+  readonly observe?: boolean;
+
+  /**
+   * Document capability for alternate runtimes and tests.
+   *
+   * @default window.document (with a MutationObserver on `<title>`)
+   */
+  readonly host?: MaybeRefOrGetter<DocumentTitleHost | null | undefined>;
+}
+
+/** Reactive state returned by {@link useDocumentTitle}. */
+export interface DocumentTitleControls {
+  /**
+   * Title before templating. Writable; `null`/`undefined` leaves the
+   * document title untouched. When a getter was passed, the next getter
+   * change overwrites manual assignments.
+   */
+  readonly title: Ref<string | null | undefined>;
+
+  /**
+   * Whether a document capability is attached. Inside a component it stays
+   * `false` until mounted, so hydration matches the server render.
+   */
+  readonly supported: ComputedRef<boolean>;
+}
+
+function browserTitleHost(): DocumentTitleHost | undefined {
+  if (typeof window === "undefined") return undefined;
+  const { document, MutationObserver } = window;
+  return {
+    get title() {
+      return document.title;
+    },
+    set title(value: string) {
+      document.title = value;
+    },
+    observeTitle: (callback) => {
+      const observer = new MutationObserver(callback);
+      const element = document.head.querySelector("title");
+      if (element) {
+        observer.observe(element, { childList: true, characterData: true, subtree: true });
+      }
+      return () => observer.disconnect();
+    },
+  };
+}
+
+function formatTitle(template: DocumentTitleTemplate, title: string): string {
+  return typeof template === "function" ? template(title) : template.replaceAll("%s", title);
+}
+
+/**
+ * Bind the document title to reactive state.
+ *
+ * Accepts a writable ref (used as-is), a getter (followed), a plain
+ * string, or nothing (an owned ref seeded from the current title). Every
+ * non-nullish title is passed through `template` before it is written.
+ * With `observe`, external title changes flow back into `title`.
+ *
+ * Server rendering: the document is never touched and `title` keeps the
+ * value it was given (or `undefined`). Head management for server-rendered
+ * markup (`<title>` in the HTML) is the job of the application's head
+ * manager; this composable only updates the live document on the client.
+ * Watchers and the observer are released with the owning reactive scope,
+ * which also applies `restoreOnDispose`.
+ *
+ * @example
+ * ```ts
+ * const { title } = useDocumentTitle(() => route.meta.title, { template: "%s | Vize" });
+ * ```
+ *
+ * @param title Reactive title source.
+ * @param options Template, restore policy, observation, and capability.
+ * @default options {}
+ * @returns The title ref and support flag.
+ */
+export function useDocumentTitle(
+  title?: MaybeRefOrGetter<string | null | undefined>,
+  options: UseDocumentTitleOptions = {},
+): DocumentTitleControls {
+  const template = options.template ?? "%s";
+  const resolveHost = (): DocumentTitleHost | undefined =>
+    options.host === undefined ? browserTitleHost() : (toValue(options.host) ?? undefined);
+  const initialHost = resolveHost();
+  const originalTitle = initialHost?.title ?? "";
+  // Inside a component the current document title is adopted only after
+  // mounting, so a hydrating client first renders what the server did.
+  const mounted = hasInjectionContext() ? useMounted() : undefined;
+  const adoptTitle = title === undefined && mounted !== undefined;
+  const state: Ref<string | null | undefined> = isRef(title)
+    ? title
+    : ref(title === undefined && !adoptTitle ? initialHost?.title : toValue(title));
+  if (adoptTitle) {
+    watch(mounted, (isMounted) => {
+      if (isMounted && state.value === undefined) state.value = resolveHost()?.title;
+    });
+  }
+  let lastWritten: string | undefined;
+
+  if (typeof title === "function") {
+    watch(title, (next) => {
+      state.value = next;
+    });
+  }
+
+  watch(
+    [state, resolveHost],
+    ([next, host]) => {
+      if (!host || next === null || next === undefined) return;
+      const formatted = formatTitle(template, next);
+      lastWritten = formatted;
+      if (host.title !== formatted) host.title = formatted;
+    },
+    { immediate: true, flush: "sync" },
+  );
+
+  if (options.observe ?? false) {
+    watch(
+      resolveHost,
+      (host, _previous, onCleanup) => {
+        if (!host?.observeTitle) return;
+        onCleanup(
+          host.observeTitle(() => {
+            if (host.title !== lastWritten) state.value = host.title;
+          }),
+        );
+      },
+      { immediate: true, flush: "sync" },
+    );
+  }
+
+  const restore = options.restoreOnDispose ?? false;
+  if (restore !== false) {
+    tryOnScopeDispose(() => {
+      const host = resolveHost();
+      if (!host) return;
+      host.title = restore === "previous" ? originalTitle : restore(originalTitle, host.title);
+    });
+  }
+
+  return {
+    title: state,
+    supported: computed(() => (mounted?.value ?? true) && resolveHost() !== undefined),
+  };
+}

package/registry/files/use-drop-zone.ts

@@ -0,0 +1,287 @@
+import { readonly, ref, shallowRef, toValue, unref, watch } from "vue";
+import type { MaybeRef, MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** One entry of `DataTransfer.items`. */
+export interface DataTransferItemLike {
+  /** `"file"` or `"string"`. */
+  readonly kind: string;
+
+  /** MIME type of the item. */
+  readonly type: string;
+}
+
+/** Minimal `DataTransfer` consumed by {@link useDropZone}. */
+export interface DataTransferLike {
+  /** Items being dragged; types are readable during the drag. */
+  readonly items?: ArrayLike<DataTransferItemLike>;
+
+  /** Dropped files; populated on `drop`. */
+  readonly files: ArrayLike<File>;
+
+  /** Feedback shown to the user (`"copy"`, `"none"`, …). */
+  dropEffect: string;
+}
+
+/** File name and MIME type used for acceptance checks. */
+export interface DropZoneFileInfo {
+  /** File name including extension. Empty while dragging. */
+  readonly name: string;
+
+  /** MIME type, possibly empty for unknown types. */
+  readonly type: string;
+}
+
+/**
+ * Accepted files: `accept`-attribute style patterns (`"image/*"`,
+ * `"application/pdf"`, `".png"`), or a predicate over the dragged MIME types.
+ */
+export type DropZoneAccept = readonly string[] | ((types: readonly string[]) => boolean);
+
+/** Options for {@link useDropZone}. */
+export interface UseDropZoneOptions {
+  /**
+   * Accepted files. Extension patterns can only be verified on drop
+   * because browsers hide file names while dragging. A ref rather than a
+   * getter, because a predicate is itself a function.
+   *
+   * @default every file
+   */
+  readonly accept?: MaybeRef<DropZoneAccept | undefined>;
+
+  /**
+   * Accept more than one file per drop.
+   *
+   * @default true
+   */
+  readonly multiple?: MaybeRefOrGetter<boolean>;
+
+  /**
+   * Call `preventDefault` even for rejected drags, so the browser never
+   * opens a rejected file dropped onto the zone.
+   *
+   * @default false
+   */
+  readonly preventDefaultForUnhandled?: boolean;
+
+  /**
+   * Called with the accepted files (or `null` when none were accepted).
+   *
+   * @default undefined
+   */
+  readonly onDrop?: (files: readonly File[] | null, event: Event) => void;
+
+  /**
+   * Called when a drag enters the zone.
+   *
+   * @default undefined
+   */
+  readonly onEnter?: (event: Event) => void;
+
+  /**
+   * Called when a drag leaves the zone (including its children).
+   *
+   * @default undefined
+   */
+  readonly onLeave?: (event: Event) => void;
+
+  /**
+   * Called for every `dragover` inside the zone.
+   *
+   * @default undefined
+   */
+  readonly onOver?: (event: Event) => void;
+}
+
+/** Reactive state returned by {@link useDropZone}. */
+export interface DropZoneControls {
+  /** Whether a drag is currently over the zone (children included). */
+  readonly isOverDropZone: Readonly<Ref<boolean>>;
+
+  /** Whether the current drag is acceptable. */
+  readonly accepted: Readonly<Ref<boolean>>;
+
+  /** Files accepted by the most recent drop. */
+  readonly files: Readonly<ShallowRef<readonly File[] | null>>;
+}
+
+function matchesPattern(pattern: string, file: DropZoneFileInfo): boolean {
+  const normalized = pattern.trim().toLowerCase();
+  if (normalized === "" || normalized === "*" || normalized === "*/*") return true;
+  if (normalized.startsWith(".")) {
+    // While dragging the name is unknown: treat extensions as provisionally
+    // acceptable and verify them on drop.
+    return file.name === "" || file.name.toLowerCase().endsWith(normalized);
+  }
+  const type = file.type.toLowerCase();
+  if (normalized.endsWith("/*")) return type.startsWith(normalized.slice(0, -1));
+  return type === normalized;
+}
+
+/**
+ * Test a file against `accept`-attribute style patterns.
+ *
+ * Supports exact MIME types, wildcard subtypes (`"image/*"`), extensions
+ * (`".png"`, case-insensitive), and `"*"`. An empty pattern list accepts
+ * everything. An empty `name` (the file is still being dragged) makes
+ * extension patterns match provisionally.
+ *
+ * @param accept Patterns to test.
+ * @param file File name and MIME type.
+ * @returns Whether any pattern matches.
+ */
+export function matchesAccept(accept: readonly string[], file: DropZoneFileInfo): boolean {
+  return accept.length === 0 || accept.some((pattern) => matchesPattern(pattern, file));
+}
+
+function dataTransferOf(event: Event): DataTransferLike | undefined {
+  if (!("dataTransfer" in event)) return undefined;
+  const transfer: unknown = event.dataTransfer;
+  if (typeof transfer !== "object" || transfer === null || !("files" in transfer)) return undefined;
+  return isDataTransfer(transfer) ? transfer : undefined;
+}
+
+function isDataTransfer(candidate: object): candidate is DataTransferLike {
+  return "files" in candidate && "dropEffect" in candidate;
+}
+
+function draggedTypes(transfer: DataTransferLike): readonly string[] {
+  const types: string[] = [];
+  const items = transfer.items;
+  if (!items) return types;
+  for (let index = 0; index < items.length; index += 1) {
+    const item = items[index];
+    if (item?.kind === "file") types.push(item.type);
+  }
+  return types;
+}
+
+/**
+ * Headless drop-zone logic for any element.
+ *
+ * Tracks whether a drag is over the target (a nesting counter keeps
+ * `dragleave` from child elements from flickering the state), decides
+ * acceptance from the dragged MIME types while dragging, and filters the
+ * dropped files by `accept` (including extension patterns) and `multiple`.
+ * Rejected drags show the `"none"` drop effect. Rendering is entirely up to
+ * the caller. Listeners follow the reactive target and are removed when the
+ * owning reactive scope stops.
+ *
+ * Server rendering: no listener is attached; all state is empty/false.
+ *
+ * @example
+ * ```ts
+ * const zone = useTemplateRef<HTMLElement>("zone");
+ * const { isOverDropZone, files } = useDropZone(zone, { accept: ["image/*"] });
+ * ```
+ *
+ * @param target Reactive drop target.
+ * @param options Acceptance rules and lifecycle callbacks.
+ * @default options {}
+ * @returns Drag and drop state.
+ */
+export function useDropZone(
+  target: MaybeRefOrGetter<EventTarget | null | undefined>,
+  options: UseDropZoneOptions = {},
+): DropZoneControls {
+  const isOverDropZone = ref(false);
+  const accepted = ref(false);
+  const files = shallowRef<readonly File[] | null>(null);
+  let depth = 0;
+
+  const acceptsTypes = (types: readonly string[]): boolean => {
+    const accept = unref(options.accept);
+    if (types.length === 0) return false;
+    if (!(toValue(options.multiple) ?? true) && types.length > 1) return false;
+    if (accept === undefined) return true;
+    if (typeof accept === "function") return accept(types);
+    return types.every((type) => matchesAccept(accept, { name: "", type }));
+  };
+
+  const acceptedFiles = (transfer: DataTransferLike): readonly File[] => {
+    const dropped = Array.from(transfer.files);
+    const accept = unref(options.accept);
+    const matching =
+      accept === undefined
+        ? dropped
+        : typeof accept === "function"
+          ? accept(dropped.map((file) => file.type))
+            ? dropped
+            : []
+          : dropped.filter((file) => matchesAccept(accept, file));
+    if (matching.length !== dropped.length) return [];
+    return !(toValue(options.multiple) ?? true) && matching.length > 1 ? [] : matching;
+  };
+
+  const settleDefault = (event: Event, transfer: DataTransferLike | undefined): void => {
+    if (accepted.value || (options.preventDefaultForUnhandled ?? false)) event.preventDefault();
+    if (transfer) transfer.dropEffect = accepted.value ? "copy" : "none";
+  };
+
+  const onEnter = (event: Event): void => {
+    const transfer = dataTransferOf(event);
+    depth += 1;
+    if (depth === 1) {
+      accepted.value = transfer !== undefined && acceptsTypes(draggedTypes(transfer));
+      isOverDropZone.value = true;
+      options.onEnter?.(event);
+    }
+    settleDefault(event, transfer);
+  };
+
+  const onOver = (event: Event): void => {
+    settleDefault(event, dataTransferOf(event));
+    options.onOver?.(event);
+  };
+
+  const onLeave = (event: Event): void => {
+    depth = Math.max(0, depth - 1);
+    if (depth > 0) return;
+    isOverDropZone.value = false;
+    accepted.value = false;
+    options.onLeave?.(event);
+  };
+
+  const onDrop = (event: Event): void => {
+    const transfer = dataTransferOf(event);
+    const dropped = transfer ? acceptedFiles(transfer) : [];
+    if (dropped.length > 0 || (options.preventDefaultForUnhandled ?? false)) {
+      event.preventDefault();
+    }
+    depth = 0;
+    isOverDropZone.value = false;
+    accepted.value = false;
+    files.value = dropped.length > 0 ? dropped : null;
+    options.onDrop?.(files.value, event);
+  };
+
+  const stop = watch(
+    () => toValue(target) ?? undefined,
+    (element, _previous, onCleanup) => {
+      depth = 0;
+      isOverDropZone.value = false;
+      accepted.value = false;
+      if (!element) return;
+      element.addEventListener("dragenter", onEnter);
+      element.addEventListener("dragover", onOver);
+      element.addEventListener("dragleave", onLeave);
+      element.addEventListener("drop", onDrop);
+      onCleanup(() => {
+        element.removeEventListener("dragenter", onEnter);
+        element.removeEventListener("dragover", onOver);
+        element.removeEventListener("dragleave", onLeave);
+        element.removeEventListener("drop", onDrop);
+      });
+    },
+    { immediate: true, flush: "sync" },
+  );
+
+  tryOnScopeDispose(stop);
+
+  return {
+    isOverDropZone: readonly(isOverDropZone),
+    accepted: readonly(accepted),
+    files,
+  };
+}