@vizejs/composable 0.426.3 → 0.428.0

package/registry/files/use-field.ts

@@ -0,0 +1,247 @@
+import { computed, ref, shallowRef, toRaw, watch } from "vue";
+import type { ComputedRef, Ref, ShallowRef } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+import { isStandardSchema, validateStandardSchema } from "./standard-schema.ts";
+import type { StandardSchemaV1 } from "./standard-schema.ts";
+
+/** Result of a standalone field validator: messages, one message, or nothing. */
+export type FieldRuleResult = string | readonly string[] | null | undefined | void;
+
+/** Context passed to standalone field validators. */
+export interface FieldRuleContext {
+  /** Aborted when a newer validation supersedes this one. */
+  readonly signal: AbortSignal;
+}
+
+/** Plain validator for a standalone field. */
+export type FieldRule<Value> = (
+  value: Value,
+  context: FieldRuleContext,
+) => FieldRuleResult | Promise<FieldRuleResult>;
+
+/** A plain validator or a Standard Schema v1 validator for the value. */
+export type FieldRuleSource<Value> = FieldRule<Value> | StandardSchemaV1<Value, unknown>;
+
+/** When a standalone field validates automatically. */
+export type FieldValidationTrigger = "change" | "blur" | "manual";
+
+/** Options for {@link useField}. */
+export interface UseFieldOptions<Value> {
+  /**
+   * Validators run in order; their messages are concatenated.
+   *
+   * @default []
+   */
+  readonly rules?: FieldRuleSource<Value> | readonly FieldRuleSource<Value>[];
+
+  /**
+   * When validation runs automatically.
+   *
+   * @default "change"
+   */
+  readonly validateOn?: FieldValidationTrigger;
+
+  /**
+   * Field name exposed for `name` attributes and error summaries.
+   *
+   * @default ""
+   */
+  readonly name?: string;
+}
+
+/** Reactive state and actions returned by {@link useField}. */
+export interface FieldControls<Value> {
+  /** Field name. */
+  readonly name: string;
+
+  /** Writable value (use with `v-model`). */
+  readonly value: Ref<Value>;
+
+  /** Current error messages. */
+  readonly errors: Readonly<ShallowRef<readonly string[]>>;
+
+  /** First error message. */
+  readonly error: ComputedRef<string | undefined>;
+
+  /** Whether no errors are recorded. */
+  readonly valid: ComputedRef<boolean>;
+
+  /** Whether the value differs from the initial value. */
+  readonly dirty: ComputedRef<boolean>;
+
+  /** Whether the field was blurred. */
+  readonly touched: Readonly<Ref<boolean>>;
+
+  /** Whether a validation is pending. */
+  readonly validating: Readonly<Ref<boolean>>;
+
+  /** Mark the field touched (wire to `blur`); validates when configured. */
+  readonly onBlur: () => void;
+
+  /**
+   * Run every rule, aborting an older validation still in flight.
+   *
+   * @returns Whether the value is valid (`false` also when superseded).
+   */
+  readonly validate: () => Promise<boolean>;
+
+  /**
+   * Replace errors (for example with server errors).
+   *
+   * @param errors New messages.
+   */
+  readonly setErrors: (errors: readonly string[]) => void;
+
+  /**
+   * Restore the initial value (or install a new one) and clear state.
+   *
+   * @param value New initial value.
+   */
+  readonly reset: (value?: Value) => void;
+}
+
+function messagesOf(result: FieldRuleResult): readonly string[] {
+  if (result === undefined || result === null || result === "") return [];
+  return typeof result === "string" ? [result] : result.filter((message) => message !== "");
+}
+
+function sameValue(left: unknown, right: unknown): boolean {
+  if (Object.is(left, right)) return true;
+  if (left instanceof Date && right instanceof Date) return left.getTime() === right.getTime();
+  if (typeof left !== "object" || typeof right !== "object" || left === null || right === null) {
+    return false;
+  }
+  if (Array.isArray(left) !== Array.isArray(right)) return false;
+  const leftKeys = Object.keys(left);
+  const rightKeys = Object.keys(right);
+  return (
+    leftKeys.length === rightKeys.length &&
+    leftKeys.every((key) => sameValue(Reflect.get(left, key), Reflect.get(right, key)))
+  );
+}
+
+/**
+ * A standalone validated field, independent of any form.
+ *
+ * Rules may be plain (a)synchronous validators or Standard Schema v1
+ * validators (anything with a `~standard` property). A newer validation
+ * aborts older ones through their `signal`, and stale results are ignored.
+ * With `validateOn: "change"` validation runs after each value change,
+ * never during setup, so server-rendered markup matches the first client
+ * render. For multi-field state use `useForm`.
+ *
+ * Server rendering: pure state; nothing validates during setup. Pending
+ * validations are aborted when the owning scope stops.
+ *
+ * @example
+ * ```ts
+ * const email = useField("", {
+ *   name: "email",
+ *   rules: [(value) => (value.includes("@") ? undefined : "Invalid email")],
+ * });
+ * ```
+ *
+ * @typeParam Value Field value, inferred from `initialValue`.
+ * @param initialValue Initial value, or a factory returning it.
+ * @param options Rules, trigger, and name.
+ * @default options {}
+ * @returns Field state and actions.
+ */
+export function useField<Value>(
+  initialValue: Value | (() => Value),
+  options: UseFieldOptions<NoInfer<Value>> = {},
+): FieldControls<Value> {
+  const createInitial = (): Value =>
+    initialValue instanceof Function ? initialValue() : structuredClone(toRaw(initialValue));
+  let initial = createInitial();
+  // Field values are plain data, for which `UnwrapRef<Value>` equals `Value`.
+  const value = ref(structuredClone(toRaw(initial))) as Ref<Value>;
+  const errors = shallowRef<readonly string[]>([]);
+  const touched = ref(false);
+  const validating = ref(false);
+  const trigger = options.validateOn ?? "change";
+  const rules: readonly FieldRuleSource<Value>[] =
+    options.rules === undefined
+      ? []
+      : Array.isArray(options.rules)
+        ? options.rules
+        : [options.rules];
+  let controller: AbortController | undefined;
+
+  const runRule = async (
+    rule: FieldRuleSource<Value>,
+    current: Value,
+    signal: AbortSignal,
+  ): Promise<readonly string[]> => {
+    if (isStandardSchema(rule)) {
+      const result = await validateStandardSchema(rule, current);
+      return result.status === "valid" ? [] : result.issues.map((issue) => issue.message);
+    }
+    return messagesOf(await rule(current, { signal }));
+  };
+
+  const validate = async (): Promise<boolean> => {
+    controller?.abort(new DOMException("A newer validation started.", "AbortError"));
+    const active = new AbortController();
+    controller = active;
+    validating.value = true;
+    try {
+      const current = value.value;
+      const results = await Promise.all(rules.map((rule) => runRule(rule, current, active.signal)));
+      if (active.signal.aborted) return false;
+      errors.value = results.flat();
+      return errors.value.length === 0;
+    } finally {
+      if (controller === active) {
+        controller = undefined;
+        validating.value = false;
+      }
+    }
+  };
+
+  // The value installed by `reset`; its own change must not trigger validation.
+  let resetValue: unknown;
+  if (trigger === "change") {
+    watch(
+      value,
+      (current) => {
+        if (toRaw(current) === resetValue && sameValue(current, initial)) return;
+        void validate();
+      },
+      { deep: true },
+    );
+  }
+
+  tryOnScopeDispose(() => controller?.abort());
+
+  return {
+    name: options.name ?? "",
+    value,
+    errors,
+    error: computed(() => errors.value[0]),
+    valid: computed(() => errors.value.length === 0),
+    dirty: computed(() => !sameValue(value.value, initial)),
+    touched,
+    validating,
+    onBlur: () => {
+      touched.value = true;
+      if (trigger === "blur") void validate();
+    },
+    validate,
+    setErrors: (next) => {
+      errors.value = [...next];
+    },
+    reset: (next) => {
+      controller?.abort();
+      controller = undefined;
+      initial = next === undefined ? createInitial() : structuredClone(toRaw(next));
+      const fresh = structuredClone(toRaw(initial));
+      resetValue = fresh;
+      value.value = fresh;
+      errors.value = [];
+      touched.value = false;
+      validating.value = false;
+    },
+  };
+}

package/registry/files/use-file-dialog.ts

@@ -0,0 +1,257 @@
+import { shallowRef, toValue } from "vue";
+import type { MaybeRefOrGetter, ShallowRef } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Camera facing hint for capture-capable file inputs. */
+export type FileDialogCapture = "user" | "environment";
+
+/** Minimal `<input type="file">` consumed by {@link useFileDialog}. */
+export interface FileInputLike extends EventTarget {
+  /** Input type; set to `"file"`. */
+  type: string;
+
+  /** Accepted MIME types / extensions. */
+  accept: string;
+
+  /** Allow selecting multiple files. */
+  multiple: boolean;
+
+  /** Selected files. */
+  readonly files: ArrayLike<File> | null;
+
+  /** Serialized value; cleared to reset the selection. */
+  value: string;
+
+  /** Open the native dialog. */
+  click(): void;
+
+  /** Set an attribute (`capture`, `webkitdirectory`). */
+  setAttribute(name: string, value: string): void;
+
+  /** Remove an attribute. */
+  removeAttribute(name: string): void;
+}
+
+/** Document capability used to create the hidden input. */
+export interface FileDialogHost {
+  /** Create an `<input>` element. */
+  createElement(tagName: "input"): FileInputLike;
+}
+
+/** Per-dialog settings accepted by {@link useFileDialog} and `open`. */
+export interface FileDialogSettings {
+  /** Accepted MIME types / extensions, for example `"image/*,.pdf"`. */
+  readonly accept?: string;
+
+  /** Allow selecting multiple files. */
+  readonly multiple?: boolean;
+
+  /** Capture from a camera on supporting devices. */
+  readonly capture?: FileDialogCapture;
+
+  /** Select a directory (`webkitdirectory`). */
+  readonly directory?: boolean;
+
+  /** Clear the current selection before the dialog opens. */
+  readonly reset?: boolean;
+}
+
+/** Options for {@link useFileDialog}. */
+export interface UseFileDialogOptions {
+  /**
+   * Accepted MIME types / extensions.
+   *
+   * @default "*"
+   */
+  readonly accept?: MaybeRefOrGetter<string>;
+
+  /**
+   * Allow selecting multiple files.
+   *
+   * @default true
+   */
+  readonly multiple?: MaybeRefOrGetter<boolean>;
+
+  /**
+   * Capture from a camera on supporting devices.
+   *
+   * @default undefined
+   */
+  readonly capture?: MaybeRefOrGetter<FileDialogCapture | undefined>;
+
+  /**
+   * Select a directory instead of files.
+   *
+   * @default false
+   */
+  readonly directory?: MaybeRefOrGetter<boolean>;
+
+  /**
+   * Clear the current selection whenever the dialog opens.
+   *
+   * @default false
+   */
+  readonly reset?: boolean;
+
+  /**
+   * Selection before the dialog was used.
+   *
+   * @default null
+   */
+  readonly initialFiles?: readonly File[] | null;
+
+  /**
+   * Document capability for alternate runtimes and tests.
+   *
+   * @default window.document when a browser window exists
+   */
+  readonly host?: MaybeRefOrGetter<FileDialogHost | null | undefined>;
+}
+
+/** Reactive state and actions returned by {@link useFileDialog}. */
+export interface FileDialogControls {
+  /** Current selection; `null` before any selection or after `reset`. */
+  readonly files: Readonly<ShallowRef<readonly File[] | null>>;
+
+  /**
+   * Open the native dialog. Browsers require a user gesture.
+   *
+   * @param overrides Settings overriding the options for this dialog.
+   * @returns Whether a dialog could be opened.
+   */
+  readonly open: (overrides?: FileDialogSettings) => boolean;
+
+  /** Clear the selection. */
+  readonly reset: () => void;
+
+  /**
+   * Observe selections.
+   *
+   * @param handler Called with the new selection.
+   * @returns Unsubscribe function.
+   */
+  readonly onChange: (handler: (files: readonly File[] | null) => void) => () => void;
+
+  /**
+   * Observe dialogs dismissed without a selection.
+   *
+   * @param handler Called on cancel.
+   * @returns Unsubscribe function.
+   */
+  readonly onCancel: (handler: () => void) => () => void;
+}
+
+function browserFileDialogHost(): FileDialogHost | undefined {
+  return typeof window === "undefined" ? undefined : window.document;
+}
+
+/**
+ * Open the native file picker without rendering an input.
+ *
+ * A detached `<input type="file">` is created lazily on the first `open`
+ * (never during setup or server rendering), configured from reactive
+ * options plus per-call overrides, and observed for `change` and `cancel`.
+ * The selection is exposed as a readonly `File[]`. Listeners are removed
+ * when the owning reactive scope stops.
+ *
+ * Server rendering: `files` is `initialFiles` and `open` returns false.
+ *
+ * @example
+ * ```ts
+ * const { files, open, onChange } = useFileDialog({ accept: "image/*" });
+ * onChange((selection) => upload(selection));
+ * ```
+ *
+ * @param options Dialog settings, initial selection, and capability.
+ * @default options {}
+ * @returns Selection state and dialog actions.
+ */
+export function useFileDialog(options: UseFileDialogOptions = {}): FileDialogControls {
+  const files = shallowRef<readonly File[] | null>(options.initialFiles ?? null);
+  const changeHandlers = new Set<(files: readonly File[] | null) => void>();
+  const cancelHandlers = new Set<() => void>();
+  let input: FileInputLike | undefined;
+  let inputHost: FileDialogHost | undefined;
+
+  const resolveHost = (): FileDialogHost | undefined =>
+    options.host === undefined ? browserFileDialogHost() : (toValue(options.host) ?? undefined);
+
+  const onInputChange = (): void => {
+    const selected = input?.files ? Array.from(input.files) : [];
+    files.value = selected.length > 0 ? selected : null;
+    for (const handler of changeHandlers) handler(files.value);
+  };
+  const onInputCancel = (): void => {
+    for (const handler of cancelHandlers) handler();
+  };
+
+  const detach = (): void => {
+    input?.removeEventListener("change", onInputChange);
+    input?.removeEventListener("cancel", onInputCancel);
+    input = undefined;
+    inputHost = undefined;
+  };
+
+  const ensureInput = (host: FileDialogHost): FileInputLike => {
+    if (input && inputHost === host) return input;
+    detach();
+    const created = host.createElement("input");
+    created.type = "file";
+    created.addEventListener("change", onInputChange);
+    created.addEventListener("cancel", onInputCancel);
+    input = created;
+    inputHost = host;
+    return created;
+  };
+
+  const reset = (): void => {
+    files.value = null;
+    if (input) input.value = "";
+    for (const handler of changeHandlers) handler(null);
+  };
+
+  const open = (overrides: FileDialogSettings = {}): boolean => {
+    const host = resolveHost();
+    if (!host) return false;
+    const element = ensureInput(host);
+    element.accept = overrides.accept ?? toValue(options.accept) ?? "*";
+    element.multiple = overrides.multiple ?? toValue(options.multiple) ?? true;
+    const capture = overrides.capture ?? toValue(options.capture);
+    if (capture === undefined) element.removeAttribute("capture");
+    else element.setAttribute("capture", capture);
+    if (overrides.directory ?? toValue(options.directory) ?? false) {
+      element.setAttribute("webkitdirectory", "");
+    } else {
+      element.removeAttribute("webkitdirectory");
+    }
+    if (overrides.reset ?? options.reset ?? false) reset();
+    // Clearing the value lets selecting the same file again fire `change`.
+    element.value = "";
+    element.click();
+    return true;
+  };
+
+  const subscribe =
+    <Handler>(handlers: Set<Handler>) =>
+    (handler: Handler): (() => void) => {
+      handlers.add(handler);
+      return () => {
+        handlers.delete(handler);
+      };
+    };
+
+  tryOnScopeDispose(() => {
+    detach();
+    changeHandlers.clear();
+    cancelHandlers.clear();
+  });
+
+  return {
+    files,
+    open,
+    reset,
+    onChange: subscribe(changeHandlers),
+    onCancel: subscribe(cancelHandlers),
+  };
+}