nuxt-ui-tools 1.2.0 → 1.4.0

package/dist/runtime/form/composables/use-form-action-buttons.d.ts

@@ -0,0 +1,32 @@
+import type { FormAction, FormRuntime } from '../types/index.js';
+/**
+ * Turns form actions into Nuxt UI buttons: visibility, disabled and loading states, links, and
+ * what a click runs. The form footer and the form page actions render from it.
+ */
+export declare function useFormActionButtons(params: {
+    runtime: FormRuntime;
+    actions: () => readonly FormAction[];
+    onCancel: () => void;
+}): {
+    button: (action: FormAction) => {
+        readonly color: import("../types/index.js").FormActionColor | undefined;
+        readonly disabled: boolean;
+        readonly icon: string | undefined;
+        readonly label: string | undefined;
+        readonly loading: boolean;
+        readonly size: "xs" | "sm" | "md" | "lg" | "xl";
+        readonly to: string | undefined;
+        readonly trailingIcon: string | undefined;
+        readonly type: "button" | "submit";
+        readonly variant: import("../types/index.js").FormActionVariant | undefined;
+    };
+    fills: typeof fills;
+    run: (action: FormAction) => Promise<void>;
+    slot: typeof slot;
+    visible: import("vue").ComputedRef<FormAction[]>;
+};
+/** Footer group of an action at the current breakpoint. */
+declare function slot(action: FormAction): "left" | "right";
+/** True when an action fills its row at the current breakpoint. */
+declare function fills(action: FormAction): boolean;
+export {};

package/dist/runtime/form/composables/use-form-action-buttons.js

@@ -0,0 +1,89 @@
+import { computed } from "vue";
+import { getResponsiveValue } from "../../shared/composables/use-responsive-value.js";
+import { createPublicFormApi } from "../utils/api.js";
+import { invokeFormFunction, isString } from "../utils/predicate.js";
+import { resolveFormText } from "../utils/text.js";
+import { useFormUi } from "./use-form-ui.js";
+export function useFormActionButtons(params) {
+  const formUi = useFormUi();
+  const context = computed(() => ({
+    actionPending: params.runtime.actionPending.value,
+    api: createPublicFormApi(params.runtime),
+    currentStep: params.runtime.currentStepIndex.value,
+    isFirstStep: params.runtime.isFirstStep.value,
+    isLastStep: params.runtime.isLastStep.value,
+    isMultiStep: params.runtime.isStepped.value
+  }));
+  const visible = computed(
+    () => params.actions().filter((action) => action.condition?.(context.value) ?? true)
+  );
+  async function run(action) {
+    if (action.key === "submit") {
+      return;
+    }
+    if (action.key === "next") {
+      await params.runtime.nextStep();
+      return;
+    }
+    if (action.key === "previous") {
+      await params.runtime.previousStep();
+      return;
+    }
+    if (action.key === "reset") {
+      await params.runtime.reset();
+      return;
+    }
+    if (action.key === "cancel") {
+      params.onCancel();
+      return;
+    }
+    if ("action" in action) {
+      await action.action?.(context.value);
+    }
+  }
+  function link(action) {
+    if (!("link" in action)) {
+      return;
+    }
+    if (isString(action.link)) {
+      return action.link;
+    }
+    const resolved = invokeFormFunction(action.link, [context.value]);
+    return isString(resolved) ? resolved : void 0;
+  }
+  function loading(action) {
+    const pending = params.runtime.actionPending.value;
+    return pending !== null && isBuiltInActionKey(action.key) && action.key === pending;
+  }
+  function disabled(action) {
+    if (action.disabled?.(context.value)) {
+      return true;
+    }
+    return params.runtime.actionPending.value !== null && !loading(action);
+  }
+  function button(action) {
+    const primary = action.type === "primary";
+    return {
+      color: action.color ?? (primary ? "primary" : void 0),
+      disabled: disabled(action),
+      icon: action.icon === false ? void 0 : action.icon,
+      label: resolveFormText(action.label),
+      loading: loading(action),
+      size: action.size ?? formUi.controlSize.value,
+      to: link(action),
+      trailingIcon: action.trailingIcon === false ? void 0 : action.trailingIcon,
+      type: action.key === "submit" ? "submit" : "button",
+      variant: action.variant ?? (primary ? "solid" : void 0)
+    };
+  }
+  return { button, fills, run, slot, visible };
+}
+function slot(action) {
+  return getResponsiveValue(action.slot ?? "right") === "left" ? "left" : "right";
+}
+function fills(action) {
+  return getResponsiveValue(action.width ?? "fit") === "fill";
+}
+function isBuiltInActionKey(value) {
+  return value === "reset" || value === "cancel" || value === "submit" || value === "previous" || value === "next";
+}

package/dist/runtime/form/composables/use-form-actions.d.ts

@@ -1,6 +1,9 @@
-import type { ComputedRef } from 'vue';
-import type { FormAction, FormRenderShell, FormRuntime } from '../types/index.js';
-export declare function useFormActions(params: {
+import type { FormAction, FormActionSlot, FormRuntime } from '../types/index.js';
+interface UseFormActionsParams {
     runtime: FormRuntime;
-    shell: ComputedRef<FormRenderShell>;
-}): ComputedRef<readonly FormAction[]>;
+    /** Slot the built-in actions take unless an authored action sets its own. */
+    slot: () => FormActionSlot;
+}
+/** Resolves the actions of the current schema or step, completing built-in actions. */
+export declare function useFormActions(params: UseFormActionsParams): import("vue").ComputedRef<readonly FormAction[]>;
+export {};

package/dist/runtime/form/composables/use-form-actions.js

@@ -28,7 +28,7 @@ function normalizeFormAction(action, params, t) {
   };
 }
 function getBaseFormAction(key, params, t) {
-  const slot = params.shell.value === "inline" ? "left" : "right";
+  const slot = params.slot();
   if (key === "submit") {
     return {
       condition: (context) => context.isMultiStep ? context.isLastStep : true,

package/dist/runtime/form/composables/use-form-page-scroll.d.ts

@@ -0,0 +1,22 @@
+import type { ComputedRef } from 'vue';
+import type { FormPageScrollOptions, FormPageSectionState } from '../types/index.js';
+/**
+ * Scroll behavior of a form page: which section is in view (a scrollspy on the nearest scrolling
+ * ancestor), scrolling to a section, and the URL hash that records and restores it.
+ *
+ * A section counts as reached once its top passes the line its `scroll-margin-top` defines, the
+ * same offset `scrollIntoView` honors, so the pinned header and the scrollspy agree. The section
+ * of an entry clicked in the navigation, and the one holding the field that takes focus (such as
+ * the first invalid field on submit), stay current through the scroll they cause, until the page
+ * is scrolled again.
+ */
+export declare function useFormPageScroll(params: {
+    sections: ComputedRef<readonly FormPageSectionState[]>;
+    /** Element the scroll container is looked up from: the page itself, or an ancestor. */
+    root: () => HTMLElement | null;
+    hash: () => boolean;
+}): {
+    active: import("vue").Ref<string | undefined, string | undefined>;
+    register: (key: string, element: HTMLElement) => () => void;
+    scrollTo: (key: string, options?: FormPageScrollOptions) => boolean;
+};

package/dist/runtime/form/composables/use-form-page-scroll.js

@@ -0,0 +1,178 @@
+import { nextTick, onBeforeUnmount, onMounted, ref } from "vue";
+const SCROLL_SETTLE_MS = 120;
+const ACTIVATION_SLACK = 8;
+export function useFormPageScroll(params) {
+  const elements = /* @__PURE__ */ new Map();
+  const active = ref();
+  let scroller;
+  let focusRoot = null;
+  let target;
+  let pendingHash;
+  let settleTimer;
+  let holdFrame = 0;
+  let frame = 0;
+  function register(key, element) {
+    elements.set(key, element);
+    if (pendingHash === key) {
+      pendingHash = void 0;
+      void nextTick(() => scrollTo(key, { behavior: "instant", hash: false }));
+    } else {
+      schedule();
+    }
+    return () => {
+      if (elements.get(key) === element) {
+        elements.delete(key);
+      }
+      schedule();
+    };
+  }
+  function scrollTo(key, options = {}) {
+    const element = elements.get(key);
+    if (!element) {
+      return false;
+    }
+    hold(key);
+    element.scrollIntoView?.({
+      behavior: options.behavior ?? (prefersReducedMotion() ? "instant" : "smooth"),
+      block: "start"
+    });
+    if (options.focus) {
+      element.querySelector("[data-form-page-section-title]")?.focus({ preventScroll: true });
+    }
+    if (options.hash ?? params.hash()) {
+      writeHash(key);
+    }
+    return true;
+  }
+  function hold(key) {
+    target = key;
+    active.value = key;
+    clearTimeout(settleTimer);
+    cancelAnimationFrame(holdFrame);
+    holdFrame = requestAnimationFrame(() => {
+      holdFrame = requestAnimationFrame(() => {
+        holdFrame = 0;
+        settleSoon();
+      });
+    });
+  }
+  function settleSoon() {
+    clearTimeout(settleTimer);
+    settleTimer = setTimeout(() => {
+      target = void 0;
+    }, SCROLL_SETTLE_MS);
+  }
+  function onScroll() {
+    if (target) {
+      settleSoon();
+      return;
+    }
+    schedule();
+  }
+  function onFocusIn(event) {
+    const section = event.target instanceof Element ? event.target.closest("[data-form-page-section]") : null;
+    const key = section?.dataset.formPageSection;
+    if (key && elements.get(key) === section) {
+      hold(key);
+    }
+  }
+  function schedule() {
+    if (frame) {
+      return;
+    }
+    frame = requestAnimationFrame(() => {
+      frame = 0;
+      update();
+    });
+  }
+  function update() {
+    if (target) {
+      return;
+    }
+    const next = findActive();
+    if (next !== void 0) {
+      active.value = next;
+    }
+  }
+  function findActive() {
+    const keys = params.sections.value.map((section) => section.key).filter((key) => elements.has(key));
+    if (!keys.length) {
+      return void 0;
+    }
+    if (isScrolledToEnd()) {
+      return keys.at(-1);
+    }
+    const line = scroller instanceof HTMLElement ? scroller.getBoundingClientRect().top : 0;
+    let current = keys[0];
+    for (const key of keys) {
+      const element = elements.get(key);
+      if (!element) {
+        continue;
+      }
+      const margin = Number.parseFloat(getComputedStyle(element).scrollMarginTop) || 0;
+      if (element.getBoundingClientRect().top - margin > line + ACTIVATION_SLACK) {
+        break;
+      }
+      current = key;
+    }
+    return current;
+  }
+  function isScrolledToEnd() {
+    const box = scroller instanceof HTMLElement ? scroller : document.scrollingElement;
+    if (!box || box.scrollHeight <= box.clientHeight) {
+      return false;
+    }
+    return box.scrollTop + box.clientHeight >= box.scrollHeight - 1;
+  }
+  function onHashChange() {
+    const key = readHash();
+    if (key && elements.has(key)) {
+      scrollTo(key, { hash: false });
+    }
+  }
+  onMounted(() => {
+    focusRoot = params.root();
+    focusRoot?.addEventListener("focusin", onFocusIn);
+    scroller = findScroller(focusRoot);
+    scroller.addEventListener("scroll", onScroll, { passive: true });
+    window.addEventListener("hashchange", onHashChange);
+    const key = params.hash() ? readHash() : void 0;
+    if (key && elements.has(key)) {
+      void nextTick(() => scrollTo(key, { behavior: "instant", hash: false }));
+    } else {
+      pendingHash = key;
+      schedule();
+    }
+  });
+  onBeforeUnmount(() => {
+    focusRoot?.removeEventListener("focusin", onFocusIn);
+    scroller?.removeEventListener("scroll", onScroll);
+    window.removeEventListener("hashchange", onHashChange);
+    clearTimeout(settleTimer);
+    cancelAnimationFrame(holdFrame);
+    if (frame) {
+      cancelAnimationFrame(frame);
+    }
+  });
+  return { active, register, scrollTo };
+}
+function findScroller(element) {
+  for (let node = element; node; node = node.parentElement) {
+    if (/auto|scroll/u.test(getComputedStyle(node).overflowY)) {
+      return node;
+    }
+  }
+  return window;
+}
+function prefersReducedMotion() {
+  return window.matchMedia?.("(prefers-reduced-motion: reduce)").matches === true;
+}
+function readHash() {
+  const hash = window.location.hash.slice(1);
+  return hash ? decodeURIComponent(hash) : void 0;
+}
+function writeHash(key) {
+  const url = new URL(window.location.href);
+  url.hash = key;
+  window.history.replaceState(window.history.state, "", url);
+}

package/dist/runtime/form/composables/use-form-page.d.ts

@@ -0,0 +1,114 @@
+import type { FormPageSectionState } from '../types/index.js';
+import type { useFormRoot } from './use-form-root.js';
+/**
+ * State shared by a form page and its parts: the visible sections and where each stands, the
+ * section in view, the navigation summary, and the actions a part can take on a section.
+ */
+export declare function useFormPage(params: {
+    root: ReturnType<typeof useFormRoot>;
+    /** The page element, where the lookup of the scroll container starts. */
+    element: () => HTMLElement | null;
+    hash: () => boolean;
+}): {
+    active: import("vue").Ref<string | undefined, string | undefined>;
+    cancel: () => void;
+    dirtyCheck: import("vue").ComputedRef<boolean>;
+    items: import("vue").ComputedRef<{
+        entry: import("../types/index.js").FormPageSectionEntry;
+        section: FormPageSectionState;
+    }[]>;
+    modified: import("vue").ComputedRef<number>;
+    navigationTitle: import("vue").ComputedRef<string | undefined>;
+    register: (key: string, element: HTMLElement) => () => void;
+    remaining: import("vue").ComputedRef<number>;
+    resetSection: (key: string) => Promise<void>;
+    root: {
+        cancel: () => void;
+        contextError: import("vue").ComputedRef<string | undefined>;
+        contextLoading: import("vue").ComputedRef<boolean>;
+        contextPending: import("vue").ComputedRef<boolean>;
+        formUi: {
+            controlSize: import("vue").ComputedRef<import("../types/index.js").FormControlSize>;
+            density: import("vue").ComputedRef<import("../types/index.js").FormDensity>;
+            ui: import("vue").ComputedRef<import("../types/index.js").FormUiConfig>;
+        };
+        input: import("vue").ComputedRef<import("../../shared/index.js").GenericObject | undefined>;
+        refreshContext: () => Promise<void>;
+        runtime: import("../types/index.js").FormRuntime;
+        schema: import("vue").ComputedRef<{}>;
+        submit: () => Promise<void>;
+        validationMode: import("vue").ComputedRef<import("../types/index.js").FormValidationMode>;
+    };
+    scrollTo: (key: string, options?: import("../types/index.js").FormPageScrollOptions) => boolean;
+    sections: import("vue").ComputedRef<readonly FormPageSectionState[]>;
+    stickyOffset: import("vue").Ref<number, number>;
+};
+export declare function provideFormPage(page: ReturnType<typeof useFormPage>): {
+    active: import("vue").Ref<string | undefined, string | undefined>;
+    cancel: () => void;
+    dirtyCheck: import("vue").ComputedRef<boolean>;
+    items: import("vue").ComputedRef<{
+        entry: import("../types/index.js").FormPageSectionEntry;
+        section: FormPageSectionState;
+    }[]>;
+    modified: import("vue").ComputedRef<number>;
+    navigationTitle: import("vue").ComputedRef<string | undefined>;
+    register: (key: string, element: HTMLElement) => () => void;
+    remaining: import("vue").ComputedRef<number>;
+    resetSection: (key: string) => Promise<void>;
+    root: {
+        cancel: () => void;
+        contextError: import("vue").ComputedRef<string | undefined>;
+        contextLoading: import("vue").ComputedRef<boolean>;
+        contextPending: import("vue").ComputedRef<boolean>;
+        formUi: {
+            controlSize: import("vue").ComputedRef<import("../types/index.js").FormControlSize>;
+            density: import("vue").ComputedRef<import("../types/index.js").FormDensity>;
+            ui: import("vue").ComputedRef<import("../types/index.js").FormUiConfig>;
+        };
+        input: import("vue").ComputedRef<import("../../shared/index.js").GenericObject | undefined>;
+        refreshContext: () => Promise<void>;
+        runtime: import("../types/index.js").FormRuntime;
+        schema: import("vue").ComputedRef<{}>;
+        submit: () => Promise<void>;
+        validationMode: import("vue").ComputedRef<import("../types/index.js").FormValidationMode>;
+    };
+    scrollTo: (key: string, options?: import("../types/index.js").FormPageScrollOptions) => boolean;
+    sections: import("vue").ComputedRef<readonly FormPageSectionState[]>;
+    stickyOffset: import("vue").Ref<number, number>;
+};
+/** The page a part renders in. Parts only work inside `FormPage`. */
+export declare function useFormPageContext(): {
+    active: import("vue").Ref<string | undefined, string | undefined>;
+    cancel: () => void;
+    dirtyCheck: import("vue").ComputedRef<boolean>;
+    items: import("vue").ComputedRef<{
+        entry: import("../types/index.js").FormPageSectionEntry;
+        section: FormPageSectionState;
+    }[]>;
+    modified: import("vue").ComputedRef<number>;
+    navigationTitle: import("vue").ComputedRef<string | undefined>;
+    register: (key: string, element: HTMLElement) => () => void;
+    remaining: import("vue").ComputedRef<number>;
+    resetSection: (key: string) => Promise<void>;
+    root: {
+        cancel: () => void;
+        contextError: import("vue").ComputedRef<string | undefined>;
+        contextLoading: import("vue").ComputedRef<boolean>;
+        contextPending: import("vue").ComputedRef<boolean>;
+        formUi: {
+            controlSize: import("vue").ComputedRef<import("../types/index.js").FormControlSize>;
+            density: import("vue").ComputedRef<import("../types/index.js").FormDensity>;
+            ui: import("vue").ComputedRef<import("../types/index.js").FormUiConfig>;
+        };
+        input: import("vue").ComputedRef<import("../../shared/index.js").GenericObject | undefined>;
+        refreshContext: () => Promise<void>;
+        runtime: import("../types/index.js").FormRuntime;
+        schema: import("vue").ComputedRef<{}>;
+        submit: () => Promise<void>;
+        validationMode: import("vue").ComputedRef<import("../types/index.js").FormValidationMode>;
+    };
+    scrollTo: (key: string, options?: import("../types/index.js").FormPageScrollOptions) => boolean;
+    sections: import("vue").ComputedRef<readonly FormPageSectionState[]>;
+    stickyOffset: import("vue").Ref<number, number>;
+};

package/dist/runtime/form/composables/use-form-page.js

@@ -0,0 +1,83 @@
+import { computed, inject, provide, ref } from "vue";
+import { getSchemaDirtyCheck } from "../utils/controls.js";
+import {
+  getFormPageNavigationTitle,
+  getFormPageSections,
+  isFormPageSectionVisible,
+  resolveFormPageSectionState
+} from "../utils/page.js";
+import { cloneFormValue } from "../utils/path.js";
+import { useFormPageScroll } from "./use-form-page-scroll.js";
+export function useFormPage(params) {
+  const { root } = params;
+  const { runtime } = root;
+  const entries = computed(
+    () => getFormPageSections(root.schema.value).filter(
+      (entry) => isFormPageSectionVisible(entry, runtime)
+    )
+  );
+  const requiredEnforced = computed(
+    () => root.validationMode.value === true || root.validationMode.value === "required"
+  );
+  const items = computed(
+    () => entries.value.map((entry, index) => ({
+      entry,
+      section: resolveFormPageSectionState({
+        entry,
+        index,
+        input: root.input.value,
+        requiredEnforced: requiredEnforced.value,
+        runtime
+      })
+    }))
+  );
+  const sections = computed(
+    () => items.value.map((item) => item.section)
+  );
+  const dirtyCheck = computed(() => getSchemaDirtyCheck(root.schema.value));
+  const navigationTitle = computed(() => getFormPageNavigationTitle(root.schema.value));
+  const remaining = computed(
+    () => sections.value.filter((section) => !section.optional && section.status !== "complete").length
+  );
+  const modified = computed(() => sections.value.filter((section) => section.dirty).length);
+  const stickyOffset = ref(0);
+  const scroll = useFormPageScroll({ hash: params.hash, root: params.element, sections });
+  async function resetSection(key) {
+    const section = sections.value.find((candidate) => candidate.key === key);
+    if (!section) {
+      return;
+    }
+    for (const path of section.dirtyPaths) {
+      runtime.setValue(path, cloneFormValue(runtime.getInitialValue(path)));
+      runtime.clearError(path);
+    }
+    await runtime.settleEffects();
+  }
+  return {
+    active: scroll.active,
+    cancel: root.cancel,
+    dirtyCheck,
+    items,
+    modified,
+    navigationTitle,
+    register: scroll.register,
+    remaining,
+    resetSection,
+    root,
+    scrollTo: scroll.scrollTo,
+    sections,
+    stickyOffset
+  };
+}
+const formPageKey = Symbol("nuxt-ui-tools-form-page");
+export function provideFormPage(page) {
+  provide(formPageKey, page);
+  return page;
+}
+export function useFormPageContext() {
+  const page = inject(formPageKey, null);
+  if (!page) {
+    throw new Error("Form page parts must be rendered inside <FormPage>.");
+  }
+  return page;
+}

package/dist/runtime/form/composables/use-form-root.d.ts

@@ -0,0 +1,34 @@
+import type { FormObject, FormRendererController, FormSubmitHandlerResult, FormUiConfig, FormValidationMode, FormValue } from '../types/index.js';
+export interface UseFormRootParams {
+    /** Controller from `useForm`. Its schema, input, and policies win over the direct ones. */
+    form: () => FormRendererController | undefined;
+    schema: () => FormValue;
+    input: () => FormObject | undefined;
+    syncInput: () => boolean | readonly string[] | undefined;
+    validate: () => FormValidationMode | undefined;
+    ui: () => FormUiConfig | undefined;
+    onSubmitted: (value: FormObject, result: FormSubmitHandlerResult<FormValue>) => void;
+    onCancelled: (value: FormObject) => void;
+}
+/**
+ * Root of a rendered form. It creates the runtime and binds it to the controller, provides the
+ * runtime and the presentation config to the fields, guards navigation away from a dirty form,
+ * and owns submit and cancel. `<NutForm>` and `FormPage` both render from it.
+ */
+export declare function useFormRoot(params: UseFormRootParams): {
+    cancel: () => void;
+    contextError: import("vue").ComputedRef<string | undefined>;
+    contextLoading: import("vue").ComputedRef<boolean>;
+    contextPending: import("vue").ComputedRef<boolean>;
+    formUi: {
+        controlSize: import("vue").ComputedRef<import("../types/index.js").FormControlSize>;
+        density: import("vue").ComputedRef<import("../types/index.js").FormDensity>;
+        ui: import("vue").ComputedRef<FormUiConfig>;
+    };
+    input: import("vue").ComputedRef<import("../../shared/index.js").GenericObject | undefined>;
+    refreshContext: () => Promise<void>;
+    runtime: import("../types/index.js").FormRuntime;
+    schema: import("vue").ComputedRef<{}>;
+    submit: () => Promise<void>;
+    validationMode: import("vue").ComputedRef<FormValidationMode>;
+};