nuxt-ui-tools 1.3.0 → 1.4.0

package/dist/runtime/form/components/root/form.vue

@@ -4,27 +4,17 @@ import UBadge from "@nuxt/ui/components/Badge.vue";
 import UButton from "@nuxt/ui/components/Button.vue";
 import USkeleton from "@nuxt/ui/components/Skeleton.vue";
 import { useScrollShadow } from "@nuxt/ui/composables/useScrollShadow";
-import { useAppConfig } from "nuxt/app";
-import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from "vue";
-import { useRouter } from "vue-router";
+import { computed, nextTick, ref, watch } from "vue";
 import { useUiToolsLocale } from "#ui-tools/i18n";
 import { useFormActions } from "../../composables/use-form-actions";
 import { useFormGridLayout } from "../../composables/use-form-layout";
-import { provideFormRuntime, useFormRuntime } from "../../composables/use-form-runtime";
-import { provideFormUi } from "../../composables/use-form-ui";
+import { useFormRoot } from "../../composables/use-form-root";
 import { getFormHeader } from "../../utils/overlay";
 import { isRecord } from "../../utils/path";
-import {
-  isBoolean,
-  isFunction,
-  isNumber,
-  isString,
-  isUndefined,
-  stringArray
-} from "../../utils/predicate";
+import { isFunction, isNumber, isString } from "../../utils/predicate";
 import { getSchemaFields, getSchemaSteps, isSteppedSchema } from "../../utils/state";
 import { resolveFormText } from "../../utils/text";
-import { mergeFormUi, mergeFormUiClass, resolveAppFormUi } from "../../utils/ui";
+import { mergeFormUiClass } from "../../utils/ui";
 import FormActions from "../actions/form-actions.vue";
 import FormFieldRenderer from "../renderer/form-field-renderer.vue";
 import FormDirectionalTransition from "../utils/form-directional-transition.vue";
@@ -38,68 +28,28 @@ const props = defineProps({
   showCloseButton: { type: Boolean, required: false },
   ui: { type: Object, required: false }
 });
-const router = useRouter();
 const emit = defineEmits(["submit", "cancel"]);
 const { t } = useUiToolsLocale();
-const schemaRef = computed(() => props.form?.schema.value ?? props.schema ?? {});
-const appConfig = useAppConfig();
-const formUi = provideFormUi(
-  computed(
-    () => mergeFormUi(resolveAppFormUi(appConfig), getSchemaUi(schemaRef.value), props.ui)
-  )
-);
-const inputRef = computed(() => props.form?.input.value ?? props.input);
-const syncInputRef = computed(
-  () => props.form?.syncInput.value ?? props.syncInput ?? getSchemaSyncInput(schemaRef.value)
-);
-const validationModeRef = computed(
-  () => props.form?.validationMode.value ?? props.validate ?? getSchemaValidationMode(schemaRef.value)
-);
-const runtime = useFormRuntime({
-  input: inputRef,
+const {
+  cancel,
+  contextError,
+  contextLoading,
+  contextPending,
+  formUi,
+  refreshContext,
+  runtime,
   schema: schemaRef,
-  syncInput: syncInputRef,
-  validationMode: validationModeRef
+  submit
+} = useFormRoot({
+  form: () => props.form,
+  input: () => props.input,
+  onCancelled: (value) => emit("cancel", value),
+  onSubmitted: (value, result) => emit("submit", value, result),
+  schema: () => props.schema,
+  syncInput: () => props.syncInput,
+  ui: () => props.ui,
+  validate: () => props.validate
 });
-provideFormRuntime(runtime);
-watch(
-  () => props.form,
-  (controller, previousController) => {
-    previousController?.unbind(runtime);
-    controller?.bind(runtime);
-  },
-  { immediate: true }
-);
-onBeforeUnmount(() => props.form?.unbind(runtime));
-onMounted(async () => {
-  await nextTick();
-  const target = getSchemaAutoFocus(schemaRef.value);
-  if (isString(target)) {
-    await runtime.focusField(target);
-    return;
-  }
-  if (target === true) {
-    await focusFirstRenderedField();
-  }
-});
-if (import.meta.client) {
-  let handleBeforeUnload = function(event) {
-    if (!shouldConfirmDirtyNavigation()) {
-      return;
-    }
-    event.preventDefault();
-    event.returnValue = "";
-  };
-  window.addEventListener("beforeunload", handleBeforeUnload);
-  onBeforeUnmount(() => window.removeEventListener("beforeunload", handleBeforeUnload));
-}
-const removeRouteGuard = router.beforeEach(() => {
-  if (!shouldConfirmDirtyNavigation()) {
-    return true;
-  }
-  return window.confirm(getDirtyNavigationMessage());
-});
-onBeforeUnmount(removeRouteGuard);
 const viewportRef = ref(null);
 const viewportShadow = useScrollShadow(viewportRef, { size: 20 });
 const displayedStepIndex = ref(runtime.currentStepIndex.value);
@@ -114,9 +64,6 @@ watch(
     });
   }
 );
-const parentPath = computed(
-  () => runtime.currentStepRoot.value ? [runtime.currentStepRoot.value] : []
-);
 const displayedStep = computed(
   () => isSteppedSchema(schemaRef.value) ? getSchemaSteps(schemaRef.value)[displayedStepIndex.value] : void 0
 );
@@ -167,56 +114,10 @@ const footerClass = computed(
     formUi.ui.value.root?.ui?.footer
   )
 );
-const actions = useFormActions({ runtime, shell });
-const contextPending = computed(
-  () => Object.values(runtime.context).some(
-    (resource) => "pending" in resource && resource.pending && isUndefined(resource.value)
-  )
-);
-const contextLoading = computed(
-  () => Object.values(runtime.context).some((resource) => "loading" in resource && resource.loading)
-);
-const contextError = computed(() => {
-  for (const resource of Object.values(runtime.context)) {
-    if (!("error" in resource) || !resource.error) {
-      continue;
-    }
-    if (resource.error instanceof Error) {
-      return resource.error.message;
-    }
-    if (isString(resource.error)) {
-      return resource.error;
-    }
-    return t("form.states.contextError.description");
-  }
-  return void 0;
+const actions = useFormActions({
+  runtime,
+  slot: () => shell.value === "inline" ? "left" : "right"
 });
-async function submit() {
-  if (props.form) {
-    const result2 = await props.form.submitHandler();
-    if (result2.success) {
-      emit("submit", runtime.output.value, result2);
-    }
-    return;
-  }
-  const result = await runtime.submitHandler();
-  if (result.success) {
-    emit("submit", runtime.output.value, result);
-  }
-}
-async function refreshContext() {
-  await Promise.all(
-    Object.values(runtime.context).flatMap(
-      (resource) => "refresh" in resource ? [resource.refresh()] : []
-    )
-  );
-}
-function cancel() {
-  if (shouldConfirmDirtyNavigation() && !window.confirm(getDirtyNavigationMessage())) {
-    return;
-  }
-  emit("cancel", runtime.output.value);
-}
 defineExpose({
   actionPending: runtime.actionPending,
   dirtyPaths: runtime.dirtyPaths,
@@ -268,13 +169,6 @@ function headerDisplayed(display, currentShell) {
 function isRenderShell(value) {
   return value === "inline" || value === "drawer" || value === "modal" || value === "fullscreen";
 }
-function getSchemaUi(schema) {
-  if (!isRecord(schema)) {
-    return void 0;
-  }
-  const value = Object.getOwnPropertyDescriptor(schema, "ui")?.value;
-  return isRecord(value) ? value : void 0;
-}
 function getSchemaShowStepper(schema) {
   if (!isRecord(schema)) {
     return true;
@@ -282,69 +176,6 @@ function getSchemaShowStepper(schema) {
   const value = Object.getOwnPropertyDescriptor(schema, "showStepper")?.value;
   return value !== false;
 }
-function getSchemaSyncInput(schema) {
-  const controls = getSchemaControls(schema);
-  const value = controls ? Object.getOwnPropertyDescriptor(controls, "syncInput")?.value : void 0;
-  if (isBoolean(value)) {
-    return value;
-  }
-  return stringArray(value);
-}
-function getSchemaValidationMode(schema) {
-  const controls = getSchemaControls(schema);
-  const value = controls ? Object.getOwnPropertyDescriptor(controls, "validate")?.value : void 0;
-  return value === false || value === "required" || value === "validators" ? value : true;
-}
-function getSchemaControls(schema) {
-  if (!isRecord(schema)) {
-    return;
-  }
-  const controls = Object.getOwnPropertyDescriptor(schema, "controls")?.value;
-  return isRecord(controls) ? controls : void 0;
-}
-function getSchemaAutoFocus(schema) {
-  const controls = getSchemaControls(schema);
-  const value = controls ? Object.getOwnPropertyDescriptor(controls, "autoFocus")?.value : void 0;
-  return isString(value) || isBoolean(value) ? value : false;
-}
-function dirtyNavigationConfig() {
-  const controls = getSchemaControls(schemaRef.value);
-  return controls ? Object.getOwnPropertyDescriptor(controls, "confirmNavOnDirty")?.value : void 0;
-}
-function shouldConfirmDirtyNavigation() {
-  if (!runtime.isDirty.value) {
-    return false;
-  }
-  const config = dirtyNavigationConfig();
-  if (!config) {
-    return false;
-  }
-  if (!isRecord(config)) {
-    return config === true;
-  }
-  const ignored = stringArray(config.ignorePaths);
-  return runtime.dirtyPaths.value.some(
-    (path) => !ignored.some((ignoredPath) => path === ignoredPath || path.startsWith(`${ignoredPath}.`))
-  );
-}
-function getDirtyNavigationMessage() {
-  const config = dirtyNavigationConfig();
-  if (!isRecord(config)) {
-    return "You have unsaved changes. Close this form?";
-  }
-  const message = Object.getOwnPropertyDescriptor(config, "message")?.value;
-  return resolveFormText(message) ?? "You have unsaved changes. Close this form?";
-}
-async function focusFirstRenderedField() {
-  const paths = runtime.currentFields.value.map(
-    (field) => `${parentPath.value.join(".")}${parentPath.value.length ? "." : ""}${field.key}`
-  );
-  for (const path of paths) {
-    if (await runtime.focusField(path)) {
-      return;
-    }
-  }
-}
 </script>
 
 <template>

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);
+}