@vizejs/composable 0.426.2 → 0.427.0

package/registry/files/use-offset-pagination.ts

@@ -0,0 +1,168 @@
+import { computed, isRef, shallowRef, toValue, watch } from "vue";
+import type { ComputedRef, MaybeRef, MaybeRefOrGetter, Ref, WritableComputedRef } from "vue";
+
+/** Page information passed to the {@link useOffsetPagination} callbacks. */
+export interface OffsetPaginationInfo {
+  /** One-based current page. */
+  readonly currentPage: number;
+
+  /** Items per page. */
+  readonly currentPageSize: number;
+
+  /** Number of pages (at least one). */
+  readonly pageCount: number;
+}
+
+/** Options for {@link useOffsetPagination}. */
+export interface UseOffsetPaginationOptions {
+  /**
+   * Total number of items. Reactive.
+   *
+   * @default Number.POSITIVE_INFINITY
+   */
+  readonly total?: MaybeRefOrGetter<number>;
+
+  /**
+   * One-based current page. Pass a writable ref for two-way binding.
+   *
+   * @default 1
+   */
+  readonly page?: MaybeRef<number>;
+
+  /**
+   * Items per page. Pass a writable ref for two-way binding.
+   *
+   * @default 10
+   */
+  readonly pageSize?: MaybeRef<number>;
+
+  /**
+   * Called after the current page changes.
+   *
+   * @default undefined
+   */
+  readonly onPageChange?: (info: OffsetPaginationInfo) => void;
+
+  /**
+   * Called after the page size changes.
+   *
+   * @default undefined
+   */
+  readonly onPageSizeChange?: (info: OffsetPaginationInfo) => void;
+
+  /**
+   * Called after the page count changes.
+   *
+   * @default undefined
+   */
+  readonly onPageCountChange?: (info: OffsetPaginationInfo) => void;
+}
+
+/** Pagination state and controls returned by {@link useOffsetPagination}. */
+export interface OffsetPagination {
+  /** One-based current page, always within `[1, pageCount]`. Writable. */
+  readonly currentPage: WritableComputedRef<number>;
+
+  /** Items per page, at least one. Writable. */
+  readonly currentPageSize: WritableComputedRef<number>;
+
+  /** Number of pages (at least one). */
+  readonly pageCount: ComputedRef<number>;
+
+  /** Zero-based offset of the first item of the current page. */
+  readonly offset: ComputedRef<number>;
+
+  /** Whether the current page is the first. */
+  readonly isFirstPage: ComputedRef<boolean>;
+
+  /** Whether the current page is the last. */
+  readonly isLastPage: ComputedRef<boolean>;
+
+  /** Go to the previous page (no-op on the first). */
+  readonly prev: () => void;
+
+  /** Go to the next page (no-op on the last). */
+  readonly next: () => void;
+}
+
+function toWritable(value: MaybeRef<number> | undefined, fallback: number): Ref<number> {
+  return isRef(value) ? value : shallowRef(value ?? fallback);
+}
+
+/**
+ * Offset-based pagination state.
+ *
+ * The page is clamped into `[1, pageCount]` on every read and write, so
+ * shrinking `total` or growing `pageSize` never leaves the cursor past the
+ * end. Writable `page`/`pageSize` refs are updated in place for two-way
+ * binding. Callbacks fire after the corresponding value settles.
+ * Synchronous state: SSR-safe; watchers follow the owning scope.
+ *
+ * @example
+ * ```ts
+ * const { currentPage, pageCount, next, offset } = useOffsetPagination({ total, pageSize: 20 });
+ * ```
+ *
+ * @param options Total, page, page size, and change callbacks.
+ * @default options {}
+ * @returns Pagination state and controls.
+ */
+export function useOffsetPagination(options: UseOffsetPaginationOptions = {}): OffsetPagination {
+  const page = toWritable(options.page, 1);
+  const size = toWritable(options.pageSize, 10);
+
+  const currentPageSize = computed<number>({
+    get: () => Math.max(1, Math.trunc(size.value)),
+    set: (value) => {
+      size.value = Math.max(1, Math.trunc(value));
+    },
+  });
+  const pageCount = computed(() => {
+    const total = toValue(options.total ?? Number.POSITIVE_INFINITY);
+    return Math.max(1, Math.ceil(Math.max(0, total) / currentPageSize.value));
+  });
+  const clampPage = (value: number): number =>
+    Math.min(pageCount.value, Math.max(1, Number.isNaN(value) ? 1 : Math.trunc(value)));
+  const currentPage = computed<number>({
+    get: () => clampPage(page.value),
+    set: (value) => {
+      page.value = clampPage(value);
+    },
+  });
+  const offset = computed(() => (currentPage.value - 1) * currentPageSize.value);
+  const isFirstPage = computed(() => currentPage.value === 1);
+  const isLastPage = computed(() => currentPage.value === pageCount.value);
+
+  const info = (): OffsetPaginationInfo => ({
+    currentPage: currentPage.value,
+    currentPageSize: currentPageSize.value,
+    pageCount: pageCount.value,
+  });
+  if (options.onPageChange !== undefined) {
+    const callback = options.onPageChange;
+    watch(currentPage, () => callback(info()));
+  }
+  if (options.onPageSizeChange !== undefined) {
+    const callback = options.onPageSizeChange;
+    watch(currentPageSize, () => callback(info()));
+  }
+  if (options.onPageCountChange !== undefined) {
+    const callback = options.onPageCountChange;
+    watch(pageCount, () => callback(info()));
+  }
+
+  return {
+    currentPage,
+    currentPageSize,
+    pageCount,
+    offset,
+    isFirstPage,
+    isLastPage,
+    prev: () => {
+      currentPage.value -= 1;
+    },
+    next: () => {
+      currentPage.value += 1;
+    },
+  };
+}

package/registry/files/use-payment-request.ts

@@ -0,0 +1,465 @@
+import {
+  computed,
+  hasInjectionContext,
+  readonly,
+  shallowRef,
+  toValue,
+  unref,
+  watchPostEffect,
+} from "vue";
+import type { ComputedRef, MaybeRef, MaybeRefOrGetter, ShallowRef } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Monetary amount. */
+export interface PaymentAmount {
+  /** ISO 4217 currency code. */
+  readonly currency: string;
+  /** Decimal amount, for example `"9.99"`. */
+  readonly value: string;
+}
+
+/** Line item shown on the payment sheet. */
+export interface PaymentLineItem {
+  /** Human-readable label. */
+  readonly label: string;
+  /** Amount. */
+  readonly amount: PaymentAmount;
+  /** Whether the amount is not final yet. */
+  readonly pending?: boolean;
+}
+
+/** Selectable shipping option. */
+export interface PaymentShippingOption {
+  /** Option id reported back in `shippingOption`. */
+  readonly id: string;
+  /** Human-readable label. */
+  readonly label: string;
+  /** Price of the option. */
+  readonly amount: PaymentAmount;
+  /** Whether the option is preselected. */
+  readonly selected?: boolean;
+}
+
+/** Accepted payment method. */
+export interface PaymentMethod {
+  /** Payment method identifier (URL or standardized name). */
+  readonly supportedMethods: string;
+  /** Method-specific data. */
+  readonly data?: unknown;
+}
+
+/** Initial payment details. */
+export interface PaymentDetails {
+  /** Request id. */
+  readonly id?: string;
+  /** Total amount. */
+  readonly total: PaymentLineItem;
+  /** Line items. */
+  readonly displayItems?: readonly PaymentLineItem[];
+  /** Shipping options. */
+  readonly shippingOptions?: readonly PaymentShippingOption[];
+}
+
+/** Details passed to `updateWith` after a shipping change. */
+export interface PaymentDetailsUpdate {
+  /** Updated total. */
+  readonly total?: PaymentLineItem;
+  /** Updated line items. */
+  readonly displayItems?: readonly PaymentLineItem[];
+  /** Updated shipping options (empty to reject the address). */
+  readonly shippingOptions?: readonly PaymentShippingOption[];
+  /** Error message shown to the user. */
+  readonly error?: string;
+  /** Per-field shipping address errors. */
+  readonly shippingAddressErrors?: Readonly<Record<string, string>>;
+}
+
+/** Shipping category of the request. */
+export type PaymentShippingType = "shipping" | "delivery" | "pickup";
+
+/** Payer information requested from the sheet. */
+export interface PaymentRequestOptionsInit {
+  /** Request the payer name. */
+  readonly requestPayerName?: boolean;
+  /** Request the payer email. */
+  readonly requestPayerEmail?: boolean;
+  /** Request the payer phone. */
+  readonly requestPayerPhone?: boolean;
+  /** Request a shipping address. */
+  readonly requestShipping?: boolean;
+  /** Shipping category. */
+  readonly shippingType?: PaymentShippingType;
+}
+
+/** Outcome passed to {@link PaymentResponseLike.complete}. */
+export type PaymentCompletion = "success" | "fail" | "unknown";
+
+/** Minimal `PaymentResponse`. */
+export interface PaymentResponseLike {
+  /** Request id. */
+  readonly requestId: string;
+  /** Method the payer chose. */
+  readonly methodName: string;
+  /** Method-specific response data. */
+  readonly details: unknown;
+  /** Payer name, when requested. */
+  readonly payerName?: string | null;
+  /** Payer email, when requested. */
+  readonly payerEmail?: string | null;
+  /** Payer phone, when requested. */
+  readonly payerPhone?: string | null;
+  /** Shipping address, when requested. */
+  readonly shippingAddress?: unknown;
+  /** Selected shipping option id. */
+  readonly shippingOption?: string | null;
+  /** Close the sheet with an outcome. */
+  complete(result?: PaymentCompletion): Promise<void>;
+}
+
+/** Minimal `PaymentRequest` instance. */
+export interface PaymentRequestLike extends EventTarget {
+  /** Current shipping address. */
+  readonly shippingAddress?: unknown;
+  /** Current shipping option id. */
+  readonly shippingOption?: string | null;
+  /** Whether a method can be used. */
+  canMakePayment(): Promise<boolean>;
+  /** Show the payment sheet (needs user activation). */
+  show(): Promise<PaymentResponseLike>;
+  /** Abort a showing sheet. */
+  abort(): Promise<void>;
+}
+
+/** Minimal `PaymentRequest` constructor. */
+export type PaymentRequestHost = new (
+  methods: PaymentMethod[],
+  details: PaymentDetails,
+  options?: PaymentRequestOptionsInit,
+) => PaymentRequestLike;
+
+/** Context passed to shipping change hooks. */
+export interface PaymentShippingChange {
+  /** Request that fired the change. */
+  readonly request: PaymentRequestLike;
+  /** Current shipping address. */
+  readonly shippingAddress: unknown;
+  /** Current shipping option id. */
+  readonly shippingOption: string | null;
+}
+
+/**
+ * Shipping change hook. Return (or resolve to) a details update to call
+ * `updateWith`; return `undefined` to leave the sheet unchanged.
+ */
+export type PaymentShippingChangeHook = (
+  change: PaymentShippingChange,
+) => PaymentDetailsUpdate | Promise<PaymentDetailsUpdate> | undefined;
+
+/** Options for {@link usePaymentRequest}. */
+export interface UsePaymentRequestOptions {
+  /** Accepted payment methods. Reactive; read when a request is created. */
+  readonly methods: MaybeRefOrGetter<readonly PaymentMethod[]>;
+
+  /** Payment details. Reactive; read when a request is created. */
+  readonly details: MaybeRefOrGetter<PaymentDetails>;
+
+  /**
+   * Payer information to request.
+   *
+   * @default {}
+   */
+  readonly paymentOptions?: MaybeRefOrGetter<PaymentRequestOptionsInit>;
+
+  /**
+   * `PaymentRequest` constructor for alternate runtimes and tests. A ref
+   * (not a getter) because the host is a constructor function.
+   *
+   * @default window.PaymentRequest when it exists
+   */
+  readonly PaymentRequest?: MaybeRef<PaymentRequestHost | null | undefined>;
+
+  /**
+   * Called on `shippingaddresschange`.
+   *
+   * @default undefined
+   */
+  readonly onShippingAddressChange?: PaymentShippingChangeHook;
+
+  /**
+   * Called on `shippingoptionchange`.
+   *
+   * @default undefined
+   */
+  readonly onShippingOptionChange?: PaymentShippingChangeHook;
+}
+
+/** Lifecycle of the payment sheet. */
+export type PaymentRequestState = "idle" | "interactive" | "awaiting-complete";
+
+/** Discriminated outcome of {@link PaymentRequestControls.show}. */
+export type PaymentShowResult =
+  | {
+      /** The payer authorized the payment; call `complete` next. */
+      readonly status: "completed";
+      /** Payment response. */
+      readonly response: PaymentResponseLike;
+    }
+  | {
+      /**
+       * `aborted`: dismissed or aborted; `unsupported`: no API or no
+       * supported method; `failed`: anything else.
+       */
+      readonly status: "aborted" | "unsupported" | "failed";
+      /** Error thrown by the host, when one was thrown. */
+      readonly error: unknown;
+    };
+
+/** Reactive state and actions returned by {@link usePaymentRequest}. */
+export interface PaymentRequestControls {
+  /** Whether the Payment Request API is available. */
+  readonly supported: ComputedRef<boolean>;
+  /** Sheet lifecycle. */
+  readonly state: Readonly<ShallowRef<PaymentRequestState>>;
+  /** Most recent response, cleared when a new sheet is shown. */
+  readonly response: Readonly<ShallowRef<PaymentResponseLike | undefined>>;
+  /** Most recent failure (not dismissals). */
+  readonly error: Readonly<ShallowRef<unknown>>;
+  /**
+   * Whether the configured methods can be used.
+   *
+   * @returns `false` when unsupported or the check fails.
+   */
+  readonly canMakePayment: () => Promise<boolean>;
+  /**
+   * Show the payment sheet. Aborts a sheet that is still showing.
+   *
+   * @returns The discriminated outcome; never rejects.
+   */
+  readonly show: () => Promise<PaymentShowResult>;
+  /**
+   * Close the sheet after processing the response.
+   *
+   * @param result Processing outcome.
+   * @default result "unknown"
+   * @returns Whether a response was completed.
+   */
+  readonly complete: (result?: PaymentCompletion) => Promise<boolean>;
+  /**
+   * Abort the showing sheet.
+   *
+   * @returns Whether a sheet was aborted.
+   */
+  readonly abort: () => Promise<boolean>;
+}
+
+function isPaymentRequestHost(candidate: unknown): candidate is PaymentRequestHost {
+  return typeof candidate === "function";
+}
+
+function browserPaymentRequest(): PaymentRequestHost | undefined {
+  if (typeof window === "undefined") return undefined;
+  const candidate: unknown = Reflect.get(window, "PaymentRequest");
+  return isPaymentRequestHost(candidate) ? candidate : undefined;
+}
+
+function hasUpdateWith(
+  event: Event,
+): event is Event & { updateWith(details: Promise<PaymentDetailsUpdate>): void } {
+  return "updateWith" in event && typeof event.updateWith === "function";
+}
+
+function errorName(error: unknown): unknown {
+  return typeof error === "object" && error !== null && "name" in error ? error.name : undefined;
+}
+
+/**
+ * Collect payments with a typed Payment Request API wrapper.
+ *
+ * Every `show()` constructs a fresh request from the reactive `methods`,
+ * `details`, and `paymentOptions`, wires the shipping hooks (which call
+ * `updateWith` synchronously when they return an update), and resolves to a
+ * discriminated {@link PaymentShowResult}. Call `complete()` after
+ * processing a `"completed"` result. A showing sheet is aborted when the
+ * owning reactive scope stops; outside a scope call `abort()`.
+ *
+ * Server rendering: nothing is constructed, `supported` is false and
+ * `state` is `"idle"`.
+ * Inside a component `supported` turns true only after mounting, so
+ * hydration renders this server state first.
+ *
+ * @example
+ * ```ts
+ * const payment = usePaymentRequest({ methods, details: { total } });
+ * const result = await payment.show();
+ * if (result.status === "completed") await payment.complete(await charge(result.response));
+ * ```
+ *
+ * @param options Methods, details, hooks, and the constructor host.
+ * @returns Payment state and actions.
+ */
+export function usePaymentRequest(options: UsePaymentRequestOptions): PaymentRequestControls {
+  const state = shallowRef<PaymentRequestState>("idle");
+  const response = shallowRef<PaymentResponseLike | undefined>(undefined);
+  const error = shallowRef<unknown>(undefined);
+  let active: PaymentRequestLike | undefined;
+  let generation = 0;
+  let completing = false;
+
+  // Inside a component the host is resolved only after mounting, so a
+  // hydrating client renders the server's unsupported state first. Outside
+  // components it resolves synchronously.
+  const hydrated = shallowRef(!hasInjectionContext());
+  if (!hydrated.value) {
+    watchPostEffect(() => {
+      hydrated.value = true;
+    });
+  }
+
+  const resolveHost = (): PaymentRequestHost | undefined =>
+    options.PaymentRequest === undefined
+      ? browserPaymentRequest()
+      : (unref(options.PaymentRequest) ?? undefined);
+
+  const construct = (Host: PaymentRequestHost): PaymentRequestLike =>
+    new Host(
+      [...toValue(options.methods)],
+      toValue(options.details),
+      toValue(options.paymentOptions) ?? {},
+    );
+
+  const bindHook = (
+    request: PaymentRequestLike,
+    type: string,
+    hook: PaymentShippingChangeHook | undefined,
+  ): void => {
+    if (!hook) return;
+    request.addEventListener(type, (event) => {
+      const update = hook({
+        request,
+        shippingAddress: request.shippingAddress ?? null,
+        shippingOption: request.shippingOption ?? null,
+      });
+      if (update !== undefined && hasUpdateWith(event)) event.updateWith(Promise.resolve(update));
+    });
+  };
+
+  const canMakePayment = async (): Promise<boolean> => {
+    const Host = resolveHost();
+    if (!Host) return false;
+    try {
+      return await construct(Host).canMakePayment();
+    } catch {
+      return false;
+    }
+  };
+
+  const abort = async (): Promise<boolean> => {
+    const current = active;
+    if (!current) return false;
+    try {
+      await current.abort();
+      if (active === current) {
+        active = undefined;
+        state.value = "idle";
+        generation += 1;
+      }
+      return true;
+    } catch {
+      return false;
+    }
+  };
+
+  const show = async (): Promise<PaymentShowResult> => {
+    const Host = resolveHost();
+    if (!Host) return { status: "unsupported", error: undefined };
+    if (state.value === "awaiting-complete") {
+      return {
+        status: "failed",
+        error: new Error("[VIZE_COMPOSE_PAYMENT_RESPONSE_INCOMPLETE] call complete() first"),
+      };
+    }
+    const currentGeneration = ++generation;
+    const previous = active;
+    if (previous) {
+      try {
+        await previous.abort();
+      } catch (cause) {
+        if (active === previous) {
+          error.value = cause;
+          return { status: "failed", error: cause };
+        }
+      }
+      if (active === previous) {
+        active = undefined;
+        state.value = "idle";
+      }
+      if (currentGeneration !== generation) return { status: "aborted", error: undefined };
+    }
+    response.value = undefined;
+    let request: PaymentRequestLike;
+    try {
+      request = construct(Host);
+    } catch (cause) {
+      error.value = cause;
+      return { status: "failed", error: cause };
+    }
+    bindHook(request, "shippingaddresschange", options.onShippingAddressChange);
+    bindHook(request, "shippingoptionchange", options.onShippingOptionChange);
+    active = request;
+    state.value = "interactive";
+    try {
+      const result = await request.show();
+      if (active !== request || currentGeneration !== generation) {
+        return { status: "aborted", error: undefined };
+      }
+      active = undefined;
+      response.value = result;
+      state.value = "awaiting-complete";
+      error.value = undefined;
+      return { status: "completed", response: result };
+    } catch (cause) {
+      if (active !== request || currentGeneration !== generation) {
+        return { status: "aborted", error: cause };
+      }
+      active = undefined;
+      state.value = "idle";
+      const name = errorName(cause);
+      if (name === "AbortError") return { status: "aborted", error: cause };
+      if (name === "NotSupportedError") return { status: "unsupported", error: cause };
+      error.value = cause;
+      return { status: "failed", error: cause };
+    }
+  };
+
+  const complete = async (result: PaymentCompletion = "unknown"): Promise<boolean> => {
+    const current = response.value;
+    if (!current || state.value !== "awaiting-complete" || completing) return false;
+    completing = true;
+    try {
+      await current.complete(result);
+      return true;
+    } catch (cause) {
+      error.value = cause;
+      return false;
+    } finally {
+      completing = false;
+      state.value = "idle";
+    }
+  };
+
+  tryOnScopeDispose(() => {
+    void abort();
+  });
+
+  return {
+    supported: computed(() => hydrated.value && resolveHost() !== undefined),
+    state: readonly(state),
+    response: readonly(response),
+    error: readonly(error),
+    canMakePayment,
+    show,
+    complete,
+    abort,
+  };
+}