nuxt-ui-tools 1.3.0 → 1.5.0

package/dist/module.json

@@ -5,7 +5,7 @@
   "configKey": "nuxtUiTools",
   "docs": "https://ui.nuxt.com/docs/getting-started/installation/nuxt",
   "name": "nuxt-ui-tools",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "unknown"

package/dist/module.mjs

@@ -89,7 +89,12 @@ function getPublicComponents(runtimeDir, options) {
       filePath: `${runtimeDir}/form/components/provider/form-provider.vue`,
       global: options.global,
       name: `${prefix}FormProvider`
-    }
+    },
+    ...["", "Header", "Navigation", "Sections", "Actions"].map((part) => ({
+      filePath: `${runtimeDir}/form/components/page/form-page${part ? `-${toKebabCase(part)}` : ""}.vue`,
+      global: options.global,
+      name: `${prefix}FormPage${part}`
+    }))
   ];
 }
 function toKebabCase(value) {
@@ -138,8 +143,9 @@ function setupImports(runtimeDir) {
       { from: "i18n", name: "provideUiToolsLocale" },
       { from: "i18n", name: "useUiToolsLocale" }
     ]),
-    // Shared responsive helpers
+    // Shared runtime
     ...withRuntime(runtimeDir, [
+      { from: "shared", name: "defineRemoteOptions" },
       { from: "shared", name: "getResponsiveValue" },
       { from: "shared", name: "parseResponsiveValue" },
       { from: "shared", name: "resolveResponsiveValueAtBreakpoint" },
@@ -169,6 +175,8 @@ function setupImports(runtimeDir) {
     ...withRuntime(runtimeDir, [
       { from: "form", name: "defineFormField" },
       { from: "form", name: "defineFormFields" },
+      { from: "form", name: "defineFormPageSchema" },
+      { from: "form", name: "defineFormPageSection" },
       { from: "form", name: "defineFormSchema" },
       { from: "form", name: "useForm" },
       { from: "form", name: "useFormApi" }

package/dist/runtime/dashboard/composables/use-dashboard-remote-options.js

@@ -10,7 +10,6 @@ import { mergeDashboardOptions, resolveDashboardOptionValues } from "../utils/op
 import { runDashboardRemoteResult } from "../utils/remote.js";
 export function useDashboardRemoteOptions(params) {
   const { config } = params;
-  const queryKey = config.queryKey ?? params.queryKey;
   const pageSize = Math.max(
     1,
     config.pagination?.size ?? DASHBOARD_REMOTE_OPTIONS_DEFAULTS.pageSize
@@ -22,6 +21,12 @@ export function useDashboardRemoteOptions(params) {
     computed(() => search.value.trim()),
     config.search?.debounce ?? DASHBOARD_REMOTE_OPTIONS_DEFAULTS.searchDebounce
   );
+  function queryKeyFor(term2) {
+    return config.queryKeyFor?.({
+      page: { ...REMOTE_OPTIONS_FIRST_PAGE, size: pageSize },
+      search: term2
+    }) ?? config.queryKey ?? params.queryKey;
+  }
   const pages = useInfiniteQuery(
     computed(() => ({
       enabled: (open.value || search.value !== "") && (term.value.length === 0 || term.value.length >= minLength),
@@ -33,7 +38,7 @@ export function useDashboardRemoteOptions(params) {
         config.load({ page: { ...context.pageParam, size: pageSize }, search: term.value }),
         context
       ),
-      queryKey: [...queryKey, "options", term.value],
+      queryKey: config.queryKeyFor ? [...queryKeyFor(term.value), { remoteOptionPages: pageSize }] : [...queryKeyFor(term.value), "options", term.value],
       staleTime: DASHBOARD_REMOTE_OPTIONS_DEFAULTS.staleTime
     }))
   );
@@ -50,7 +55,7 @@ export function useDashboardRemoteOptions(params) {
     computed(() => ({
       enabled: Boolean(config.resolveSelected) && missing.value.length > 0,
       queryFn: (context) => config.resolveSelected ? runDashboardRemoteResult(config.resolveSelected({ values: missing.value }), context) : Promise.resolve([]),
-      queryKey: [...queryKey, "selected", missing.value],
+      queryKey: config.selectedQueryKeyFor ? config.selectedQueryKeyFor({ values: missing.value }) : [...queryKeyFor(""), "selected", missing.value],
       // Hydrated labels stay while the next set of missing values resolves.
       placeholderData: (previous) => previous,
       staleTime: DASHBOARD_REMOTE_OPTIONS_DEFAULTS.selectedStaleTime

package/dist/runtime/dashboard/types/filters.d.ts

@@ -150,8 +150,14 @@ export interface DashboardRemoteOptionsConfig {
     /** Defaults to `{ type: 'page', size: 25 }`. */
     pagination?: RemoteOptionsPagination;
     search?: RemoteOptionsSearch;
-    /** Cache identity of the option source. Defaults to a key derived from the filter location. */
+    /** Cache identity of an inline source. Defaults to a key derived from the filter location. */
     queryKey?: QueryKey;
+    /** Cache identity of a reusable loader, derived from its endpoint request and current search. */
+    queryKeyFor?: (request: DashboardRemoteOptionsRequest) => QueryKey;
+    /** Cache identity of a selected lookup, including scope absent from the page endpoint. */
+    selectedQueryKeyFor?: (request: {
+        values: readonly string[];
+    }) => QueryKey;
 }
 /** Option items of a filter: fixed, or read reactively (e.g. from another query's data). */
 export type DashboardFilterItems = readonly DashboardOption[] | (() => readonly DashboardOption[]);

package/dist/runtime/dashboard/utils/builders/dashboard-filters.js

@@ -79,8 +79,25 @@ function optionsFilter(items, options) {
   return defineFilter("options", codec, { ...options, items });
 }
 function remoteFilter(config, extra) {
-  const { load, pagination, queryKey, resolveSelected, search, ...options } = config;
-  const remote = { load, pagination, queryKey, resolveSelected, search };
+  const {
+    load,
+    pagination,
+    queryKey,
+    queryKeyFor,
+    resolveSelected,
+    search,
+    selectedQueryKeyFor,
+    ...options
+  } = config;
+  const remote = {
+    load,
+    pagination,
+    queryKey,
+    queryKeyFor,
+    resolveSelected,
+    search,
+    selectedQueryKeyFor
+  };
   return defineFilter("remote", optionalStringCodec, {
     searchable: true,
     ...options,

package/dist/runtime/form/components/actions/form-actions.vue

@@ -1,11 +1,8 @@
 <script setup>
 import UButton from "@nuxt/ui/components/Button.vue";
 import { computed } from "vue";
-import { getResponsiveValue } from "../../../shared/composables/use-responsive-value";
+import { useFormActionButtons } from "../../composables/use-form-action-buttons";
 import { useFormUi } from "../../composables/use-form-ui";
-import { createPublicFormApi } from "../../utils/api";
-import { invokeFormFunction, isString } from "../../utils/predicate";
-import { resolveFormText } from "../../utils/text";
 import { mergeFormUiClass } from "../../utils/ui";
 const props = defineProps({
   runtime: { type: Object, required: true },
@@ -13,117 +10,24 @@ const props = defineProps({
 });
 const formUi = useFormUi();
 const emit = defineEmits(["cancel"]);
-const actionContext = computed(() => ({
-  actionPending: props.runtime.actionPending.value,
-  api: createPublicFormApi(props.runtime),
-  currentStep: props.runtime.currentStepIndex.value,
-  isFirstStep: props.runtime.isFirstStep.value,
-  isLastStep: props.runtime.isLastStep.value,
-  isMultiStep: props.runtime.isStepped.value
-}));
-const visibleActions = computed(
-  () => props.actions.filter((action) => action.condition?.(actionContext.value) ?? true)
-);
+const buttons = useFormActionButtons({
+  actions: () => props.actions,
+  onCancel: () => emit("cancel"),
+  runtime: props.runtime
+});
 const actionsLeft = computed(
-  () => visibleActions.value.filter((action) => resolveActionSlot(action) === "left")
+  () => buttons.visible.value.filter((action) => buttons.slot(action) === "left")
 );
 const actionsRight = computed(
-  () => visibleActions.value.filter((action) => resolveActionSlot(action) !== "left")
+  () => buttons.visible.value.filter((action) => buttons.slot(action) !== "left")
 );
-async function runAction(action) {
-  if (isBuiltInAction(action, "submit")) {
-    return;
-  }
-  if (isBuiltInAction(action, "next")) {
-    await props.runtime.nextStep();
-    return;
-  }
-  if (isBuiltInAction(action, "previous")) {
-    await props.runtime.previousStep();
-    return;
-  }
-  if (isBuiltInAction(action, "reset")) {
-    await props.runtime.reset();
-    return;
-  }
-  if (isBuiltInAction(action, "cancel")) {
-    emit("cancel");
-    return;
-  }
-  if ("action" in action) {
-    await action.action?.(actionContext.value);
-  }
-}
-function resolveActionLabel(action) {
-  return resolveFormText(action.label);
-}
-function resolveActionSlot(action) {
-  const slot = getResponsiveValue(action.slot ?? "right");
-  return slot === "left" ? "left" : "right";
-}
-function resolveActionWidth(action) {
-  const width = getResponsiveValue(action.width ?? "fit");
-  return width === "fill" ? "fill" : "fit";
-}
-function resolveActionLink(action) {
-  if (!("link" in action)) {
-    return;
-  }
-  if (isString(action.link)) {
-    return action.link;
-  }
-  const link = invokeFormFunction(action.link, [actionContext.value]);
-  return isString(link) ? link : void 0;
-}
-function isActionDisabled(action) {
-  const disabled = action.disabled?.(actionContext.value) ?? false;
-  if (disabled) {
-    return true;
-  }
-  if (!props.runtime.actionPending.value) {
-    return false;
-  }
-  return !isActionLoading(action);
-}
-function isActionLoading(action) {
-  if (!isBuiltInActionKey(action.key)) {
-    return false;
-  }
-  const pending = props.runtime.actionPending.value;
-  if (pending === null) {
-    return false;
-  }
-  return action.key === pending;
-}
-function resolveActionColor(action) {
-  if (action.color) {
-    return action.color;
-  }
-  if (action.type === "primary") {
-    return "primary";
-  }
-}
-function resolveActionVariant(action) {
-  if (action.variant) {
-    return action.variant;
-  }
-  if (action.type === "primary") {
-    return "solid";
-  }
-}
 function actionButtonClass(action) {
   return mergeFormUiClass(
-    resolveActionWidth(action) === "fill" ? "flex-1 justify-center" : void 0,
+    buttons.fills(action) ? "flex-1 justify-center" : void 0,
     formUi.ui.value.actions?.ui?.button,
     action.class
   );
 }
-function isBuiltInAction(action, key) {
-  return action.key === key;
-}
-function isBuiltInActionKey(value) {
-  return value === "reset" || value === "cancel" || value === "submit" || value === "previous" || value === "next";
-}
 </script>
 
 <template>
@@ -147,18 +51,9 @@ function isBuiltInActionKey(value) {
       <UButton
         v-for="(action, index) in actionsLeft"
         :key="action.key ?? index"
-        :type="isBuiltInAction(action, 'submit') ? 'submit' : 'button'"
-        :to="resolveActionLink(action)"
-        :label="resolveActionLabel(action)"
-        :icon="action.icon === false ? void 0 : action.icon"
-        :trailing-icon="action.trailingIcon === false ? void 0 : action.trailingIcon"
-        :color="resolveActionColor(action)"
-        :variant="resolveActionVariant(action)"
-        :size="action.size ?? formUi.controlSize.value"
+        v-bind="buttons.button(action)"
         :class="actionButtonClass(action)"
-        :disabled="isActionDisabled(action)"
-        :loading="isActionLoading(action)"
-        @click="runAction(action)"
+        @click="buttons.run(action)"
       />
     </div>
 
@@ -174,18 +69,9 @@ function isBuiltInActionKey(value) {
       <UButton
         v-for="(action, index) in actionsRight"
         :key="action.key ?? index"
-        :type="isBuiltInAction(action, 'submit') ? 'submit' : 'button'"
-        :to="resolveActionLink(action)"
-        :label="resolveActionLabel(action)"
-        :icon="action.icon === false ? void 0 : action.icon"
-        :trailing-icon="action.trailingIcon === false ? void 0 : action.trailingIcon"
-        :color="resolveActionColor(action)"
-        :variant="resolveActionVariant(action)"
-        :size="action.size ?? formUi.controlSize.value"
+        v-bind="buttons.button(action)"
         :class="actionButtonClass(action)"
-        :disabled="isActionDisabled(action)"
-        :loading="isActionLoading(action)"
-        @click="runAction(action)"
+        @click="buttons.run(action)"
       />
     </div>
   </div>

package/dist/runtime/form/components/page/form-page-actions.d.vue.ts

@@ -0,0 +1,3 @@
+declare const __VLS_export: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/form/components/page/form-page-actions.vue

@@ -0,0 +1,40 @@
+<script setup>
+import UButton from "@nuxt/ui/components/Button.vue";
+import { computed } from "vue";
+import { useFormActionButtons } from "../../composables/use-form-action-buttons";
+import { useFormActions } from "../../composables/use-form-actions";
+import { useFormPageContext } from "../../composables/use-form-page";
+import { useFormUi } from "../../composables/use-form-ui";
+import { mergeFormUiClass } from "../../utils/ui";
+const page = useFormPageContext();
+const formUi = useFormUi();
+const pageUi = computed(() => formUi.ui.value.page?.ui);
+const actions = useFormActions({ runtime: page.root.runtime, slot: () => "right" });
+const buttons = useFormActionButtons({
+  actions: () => actions.value,
+  onCancel: page.cancel,
+  runtime: page.root.runtime
+});
+function buttonClass(action) {
+  return mergeFormUiClass(
+    buttons.fills(action) ? "flex-1 justify-center" : void 0,
+    formUi.ui.value.actions?.ui?.button,
+    action.class
+  );
+}
+</script>
+
+<template>
+  <div
+    :class="mergeFormUiClass('flex shrink-0 flex-wrap items-center gap-2', pageUi?.actions)"
+    data-form-page-actions
+  >
+    <UButton
+      v-for="(action, index) in buttons.visible.value"
+      :key="action.key ?? index"
+      v-bind="buttons.button(action)"
+      :class="buttonClass(action)"
+      @click="buttons.run(action)"
+    />
+  </div>
+</template>

package/dist/runtime/form/components/page/form-page-actions.vue.d.ts

@@ -0,0 +1,3 @@
+declare const __VLS_export: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/form/components/page/form-page-header.d.vue.ts

@@ -0,0 +1,24 @@
+/**
+ * Header of a form page: the schema `header` (eyebrow, title, description), an unsaved-changes
+ * badge while a form with `controls.dirtyCheck` is modified, and the page actions. It stays
+ * pinned while the page scrolls on wide layouts, and sections scroll to just below it.
+ */
+type __VLS_Slots = {
+    /** Before the heading, e.g. an avatar of the record. */
+    leading?: () => unknown;
+    eyebrow?: () => unknown;
+    title?: () => unknown;
+    /** Replaces the description, keeping the unsaved-changes badge after it. */
+    description?: () => unknown;
+    /** Replaces the page actions. */
+    actions?: () => unknown;
+};
+declare const __VLS_base: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/form/components/page/form-page-header.vue

@@ -0,0 +1,99 @@
+<script setup>
+import UBadge from "@nuxt/ui/components/Badge.vue";
+import { useResizeObserver } from "@vueuse/core";
+import { computed, onBeforeUnmount, useTemplateRef } from "vue";
+import { useUiToolsLocale } from "../../../i18n/use-locale";
+import { useFormPageContext } from "../../composables/use-form-page";
+import { useFormUi } from "../../composables/use-form-ui";
+import { getFormHeader } from "../../utils/overlay";
+import { isRecord } from "../../utils/path";
+import { resolveFormBoundaryText } from "../../utils/text";
+import { mergeFormUiClass } from "../../utils/ui";
+import FormPageActions from "./form-page-actions.vue";
+defineSlots();
+const page = useFormPageContext();
+const formUi = useFormUi();
+const { t } = useUiToolsLocale();
+const pageUi = computed(() => formUi.ui.value.page?.ui);
+const header = computed(() => getFormHeader(page.root.schema.value));
+const eyebrow = computed(() => headerText(header.value, "eyebrow"));
+const title = computed(() => headerText(header.value, "title"));
+const description = computed(() => headerText(header.value, "description"));
+const unsaved = computed(() => page.dirtyCheck.value && page.root.runtime.isDirty.value);
+const element = useTemplateRef("element");
+useResizeObserver(element, () => {
+  const node = element.value;
+  page.stickyOffset.value = node && getComputedStyle(node).position === "sticky" ? node.offsetHeight : 0;
+});
+onBeforeUnmount(() => {
+  page.stickyOffset.value = 0;
+});
+function headerText(config, key) {
+  return isRecord(config) ? resolveFormBoundaryText(config[key]) : void 0;
+}
+</script>
+
+<template>
+  <header
+    ref="element"
+    :class="
+  mergeFormUiClass(
+    'z-10 flex flex-col gap-3 border-b border-default bg-default px-4 py-4 @3xl/form-page:sticky @3xl/form-page:top-0 @3xl/form-page:flex-row @3xl/form-page:items-center @3xl/form-page:justify-between @3xl/form-page:gap-5 @3xl/form-page:px-7 @3xl/form-page:pt-[18px] @3xl/form-page:pb-4',
+    pageUi?.header
+  )
+"
+    data-form-page-header
+  >
+    <div :class="mergeFormUiClass('flex min-w-0 items-center gap-3.5', pageUi?.headerContent)">
+      <slot name="leading" />
+      <div :class="mergeFormUiClass('grid min-w-0 gap-1.5', pageUi?.heading)">
+        <p
+          v-if="eyebrow || $slots.eyebrow"
+          :class="
+  mergeFormUiClass(
+    'text-[11px] font-semibold tracking-[0.08em] text-dimmed uppercase',
+    pageUi?.eyebrow
+  )
+"
+        >
+          <slot name="eyebrow">{{ eyebrow }}</slot>
+        </p>
+        <h1
+          v-if="title || $slots.title"
+          :class="
+  mergeFormUiClass(
+    'm-0 truncate text-[22px] leading-[1.1] font-semibold tracking-[-0.025em] text-highlighted @3xl/form-page:text-[28px]',
+    pageUi?.title
+  )
+"
+        >
+          <slot name="title">{{ title }}</slot>
+        </h1>
+        <div
+          v-if="description || unsaved || $slots.description"
+          :class="
+  mergeFormUiClass(
+    'flex flex-wrap items-center gap-2.5 text-[13.5px] text-muted',
+    pageUi?.meta
+  )
+"
+        >
+          <slot name="description">
+            <span v-if="description">{{ description }}</span>
+          </slot>
+          <UBadge
+            v-if="unsaved"
+            color="warning"
+            variant="soft"
+            :label="t('form.page.unsavedChanges')"
+            :class="pageUi?.unsaved"
+            data-form-page-unsaved
+          />
+        </div>
+      </div>
+    </div>
+    <slot name="actions">
+      <FormPageActions />
+    </slot>
+  </header>
+</template>

package/dist/runtime/form/components/page/form-page-header.vue.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Header of a form page: the schema `header` (eyebrow, title, description), an unsaved-changes
+ * badge while a form with `controls.dirtyCheck` is modified, and the page actions. It stays
+ * pinned while the page scrolls on wide layouts, and sections scroll to just below it.
+ */
+type __VLS_Slots = {
+    /** Before the heading, e.g. an avatar of the record. */
+    leading?: () => unknown;
+    eyebrow?: () => unknown;
+    title?: () => unknown;
+    /** Replaces the description, keeping the unsaved-changes badge after it. */
+    description?: () => unknown;
+    /** Replaces the page actions. */
+    actions?: () => unknown;
+};
+declare const __VLS_base: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/form/components/page/form-page-navigation.d.vue.ts

@@ -0,0 +1,34 @@
+import type { FormPageSectionState } from '../../types/index.js';
+/**
+ * Navigation of a form page: one entry per visible section, following the section in view.
+ * An entry shows whether its section is complete, invalid, or still to fill, marks optional
+ * sections, and, with `controls.dirtyCheck`, a dot on modified sections. The footer sums up
+ * the sections left to complete, or the modified ones with dirty checking.
+ *
+ * From 768px of page width it is a pinned column; below, a row of chips that scrolls sideways.
+ */
+type __VLS_Slots = {
+    /** Replaces the heading, which comes from the schema `navigation.title`. */
+    title?: () => unknown;
+    /** Replaces an entry. Call `select` to scroll to the section. */
+    item?: (props: {
+        section: FormPageSectionState;
+        active: boolean;
+        select: () => void;
+    }) => unknown;
+    /** Replaces the summary under the entries. */
+    footer?: (props: {
+        sections: readonly FormPageSectionState[];
+        remaining: number;
+        modified: number;
+    }) => unknown;
+};
+declare const __VLS_base: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};