nuxt-ui-tools 1.20.0 → 1.21.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.20.0",
+  "version": "1.21.0",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "unknown"

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

@@ -23,6 +23,37 @@ const { runtime } = page.root;
 const pageUi = computed(() => formUi.ui.value.page?.ui);
 const titleId = useId();
 const dirty = computed(() => page.dirtyCheck.value && props.section.dirty);
+const status = computed(() => {
+  if (!page.statusVisible.value) {
+    return void 0;
+  }
+  if (props.section.status === "optional") {
+    return { color: "neutral", icon: void 0, label: t("form.page.status.optional") };
+  }
+  if (props.section.status === "complete") {
+    return {
+      color: "success",
+      icon: "i-lucide-check",
+      label: t("form.page.status.complete")
+    };
+  }
+  if (props.section.status === "invalid") {
+    return {
+      color: "error",
+      icon: "i-lucide-circle-alert",
+      label: t("form.page.status.invalid")
+    };
+  }
+  const { missing, required } = props.section;
+  return {
+    color: "neutral",
+    icon: void 0,
+    label: t("form.page.progress", { filled: required - missing, required })
+  };
+});
+const spanClass = computed(
+  () => page.spanned.value ? "col-span-12 @3xl/form-sections:col-span-(--nut-form-page-section-span)" : ""
+);
 const layout = computed(
   () => resolveFormLayoutConfig(runtime.currentLayout.value, props.entry.section.layout)
 );
@@ -47,18 +78,22 @@ onBeforeUnmount(() => unregister?.());
     :data-state="section.status"
     :data-dirty="dirty || void 0"
     :style="{
-  scrollMarginTop: `calc(${page.stickyOffset.value}px + var(--nut-form-page-gap, 24px))`
+  scrollMarginTop: `calc(${page.stickyOffset.value}px + var(--nut-form-page-gap, 24px))`,
+  '--nut-form-page-section-span': page.spanned.value ? String(section.span) : void 0
 }"
     :class="
   mergeFormUiClass(
-    `flex min-w-0 flex-col ${page.surfaceClasses.value.section}`,
+    `flex min-w-0 flex-col ${spanClass} ${page.surfaceClasses.value.section}`,
     pageUi?.section
   )
 "
   >
     <header
       :class="
-  mergeFormUiClass('flex flex-wrap items-center gap-x-3 gap-y-1', pageUi?.sectionHeader)
+  mergeFormUiClass(
+    `flex flex-wrap items-center gap-x-3 gap-y-1 ${page.surfaceClasses.value.sectionHeader}`,
+    pageUi?.sectionHeader
+  )
 "
     >
       <span
@@ -99,7 +134,7 @@ onBeforeUnmount(() => unregister?.());
         {{ section.description }}
       </p>
       <UBadge
-        v-if="section.status === 'optional'"
+        v-if="section.status === 'optional' && !status"
         color="neutral"
         variant="soft"
         :label="t('form.page.status.optional')"
@@ -107,9 +142,24 @@ onBeforeUnmount(() => unregister?.());
         data-form-page-optional
       />
       <div
-        v-if="page.dirtyCheck.value || $slots.actions"
+        v-if="status || page.dirtyCheck.value || $slots.actions"
         :class="mergeFormUiClass('ms-auto -my-1.5 flex items-center gap-2', pageUi?.sectionActions)"
       >
+        <UBadge
+          v-if="status"
+          :color="status.color"
+          variant="soft"
+          :icon="status.icon"
+          :label="status.label"
+          :class="
+  mergeFormUiClass(
+    section.status === 'optional' ? pageUi?.sectionOptional : void 0,
+    pageUi?.sectionStatus
+  )
+"
+          :data-form-page-status="section.status"
+          :data-form-page-optional="section.status === 'optional' ? '' : void 0"
+        />
         <slot name="actions" :section />
         <UButton
           v-if="page.dirtyCheck.value"
@@ -125,7 +175,12 @@ onBeforeUnmount(() => unregister?.());
         />
       </div>
     </header>
-    <div :class="mergeFormUiClass('min-w-0', pageUi?.sectionBody)" :style="grid.style.value">
+    <div
+      :class="
+  mergeFormUiClass(`min-w-0 ${page.surfaceClasses.value.sectionBody}`, pageUi?.sectionBody)
+"
+      :style="grid.style.value"
+    >
       <FormFieldRenderer
         v-for="field in entry.section.fields"
         :key="field.key"

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

@@ -1,9 +1,10 @@
 import type { FormPageSectionState } from '../../types/index.js';
 /**
  * Sections of a form page, one per visible section, each with its title, description, fields, and,
- * with `controls.dirtyCheck`, a mark and a reset button while it is modified. They are cards, or
- * plain blocks with the `page.surface` UI option. Skeletons stand in while the schema context
- * loads.
+ * with `controls.dirtyCheck`, a mark and a reset button while it is modified. They are cards,
+ * panels, or plain blocks with the `page.surface` UI option. Once a section sets a `span`, they lay
+ * out in a twelve-column grid, which is also the container their spans query. Skeletons stand in
+ * while the schema context loads.
  */
 type __VLS_Slots = {
     /** Extra buttons in a section header, before its reset button. */

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

@@ -14,20 +14,22 @@ const formUi = useFormUi();
 const { t } = useUiToolsLocale();
 const pageUi = computed(() => formUi.ui.value.page?.ui);
 const { contextError, contextLoading, contextPending, refreshContext } = page.root;
+const flow = computed(
+  () => page.spanned.value ? "@container/form-sections grid grid-cols-12 items-stretch" : "flex flex-col"
+);
+const fullRow = computed(() => page.spanned.value ? "col-span-12" : "");
 </script>
 
 <template>
   <div
     :class="
-  mergeFormUiClass(
-    `flex min-w-0 flex-col ${page.surfaceClasses.value.sections}`,
-    pageUi?.sections
-  )
+  mergeFormUiClass(`${flow} min-w-0 ${page.surfaceClasses.value.sections}`, pageUi?.sections)
 "
     data-form-page-sections
   >
     <UAlert
       v-if="contextError"
+      :class="fullRow"
       color="error"
       variant="soft"
       icon="i-lucide-circle-alert"
@@ -53,7 +55,7 @@ const { contextError, contextLoading, contextPending, refreshContext } = page.ro
         :key="section.key"
         :class="
   mergeFormUiClass(
-    `grid gap-4 ${page.surfaceClasses.value.sectionSkeleton}`,
+    `grid gap-4 ${fullRow} ${page.surfaceClasses.value.sectionSkeleton}`,
     pageUi?.sectionSkeleton
   )
 "

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

@@ -1,9 +1,10 @@
 import type { FormPageSectionState } from '../../types/index.js';
 /**
  * Sections of a form page, one per visible section, each with its title, description, fields, and,
- * with `controls.dirtyCheck`, a mark and a reset button while it is modified. They are cards, or
- * plain blocks with the `page.surface` UI option. Skeletons stand in while the schema context
- * loads.
+ * with `controls.dirtyCheck`, a mark and a reset button while it is modified. They are cards,
+ * panels, or plain blocks with the `page.surface` UI option. Once a section sets a `span`, they lay
+ * out in a twelve-column grid, which is also the container their spans query. Skeletons stand in
+ * while the schema context loads.
  */
 type __VLS_Slots = {
     /** Extra buttons in a section header, before its reset button. */

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

@@ -43,6 +43,8 @@ export declare function useFormPage(params: {
     };
     scrollTo: (key: string, options?: import("../types/index.js").FormPageScrollOptions) => boolean;
     sections: import("vue").ComputedRef<readonly FormPageSectionState[]>;
+    spanned: import("vue").ComputedRef<boolean>;
+    statusVisible: import("vue").ComputedRef<boolean>;
     stickyOffset: import("vue").Ref<number, number>;
     surface: import("vue").ComputedRef<import("../types/index.js").FormPageSurface>;
     surfaceClasses: import("vue").ComputedRef<import("../utils/page-surface.js").FormPageSurfaceClasses>;
@@ -80,6 +82,8 @@ export declare function provideFormPage(page: ReturnType<typeof useFormPage>): {
     };
     scrollTo: (key: string, options?: import("../types/index.js").FormPageScrollOptions) => boolean;
     sections: import("vue").ComputedRef<readonly FormPageSectionState[]>;
+    spanned: import("vue").ComputedRef<boolean>;
+    statusVisible: import("vue").ComputedRef<boolean>;
     stickyOffset: import("vue").Ref<number, number>;
     surface: import("vue").ComputedRef<import("../types/index.js").FormPageSurface>;
     surfaceClasses: import("vue").ComputedRef<import("../utils/page-surface.js").FormPageSurfaceClasses>;
@@ -118,6 +122,8 @@ export declare function useFormPageContext(): {
     };
     scrollTo: (key: string, options?: import("../types/index.js").FormPageScrollOptions) => boolean;
     sections: import("vue").ComputedRef<readonly FormPageSectionState[]>;
+    spanned: import("vue").ComputedRef<boolean>;
+    statusVisible: import("vue").ComputedRef<boolean>;
     stickyOffset: import("vue").Ref<number, number>;
     surface: import("vue").ComputedRef<import("../types/index.js").FormPageSurface>;
     surfaceClasses: import("vue").ComputedRef<import("../utils/page-surface.js").FormPageSurfaceClasses>;

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

@@ -43,6 +43,8 @@ export function useFormPage(params) {
   const navigationVisible = computed(() => sections.value.length >= navigationMinSections.value);
   const surface = computed(() => resolveFormPageSurface(root.formUi.ui.value.page?.surface));
   const surfaceClasses = computed(() => getFormPageSurfaceClasses(surface.value));
+  const statusVisible = computed(() => root.formUi.ui.value.page?.status === true);
+  const spanned = computed(() => sections.value.some((section) => section.span < 12));
   const remaining = computed(() => sections.value.filter(isFormPageSectionBlocking).length);
   const modified = computed(() => sections.value.filter((section) => section.dirty).length);
   const stickyOffset = ref(0);
@@ -72,6 +74,8 @@ export function useFormPage(params) {
     root,
     scrollTo: scroll.scrollTo,
     sections,
+    spanned,
+    statusVisible,
     stickyOffset,
     surface,
     surfaceClasses

package/dist/runtime/form/fields/auto-complete/component.vue

@@ -10,6 +10,7 @@ import FormOptionSuffix from "../../components/utils/form-option-suffix.vue";
 import FormOptionValueOverlay from "../../components/utils/form-option-value-overlay.vue";
 import { useFieldControl } from "../../composables/use-field-control";
 import { useOptionMenu } from "../../composables/use-option-menu";
+import { leadingVisualPadding } from "../../utils/options";
 import { isBoolean, isNumber, isString } from "../../utils/predicate";
 import { mergeFormUiClass } from "../../utils/ui";
 const props = defineProps({
@@ -61,6 +62,7 @@ const controlUi = computed(() => ({
   ...controlProps.value.ui,
   base: mergeFormUiClass(
     controlProps.value.ui?.base,
+    menu.leadingOption.value ? leadingVisualPadding(controlProps.value.size) : void 0,
     overlayActive.value ? "text-transparent" : void 0
   ),
   content: mergeFormUiClass(controlProps.value.ui?.content, interactionOwnerClass.value),

package/dist/runtime/form/fields/select/component.vue

@@ -11,6 +11,7 @@ import FormOptionMenuFooter from "../../components/utils/form-option-menu-footer
 import FormOptionSuffix from "../../components/utils/form-option-suffix.vue";
 import { useFieldControl } from "../../composables/use-field-control";
 import { useOptionMenu } from "../../composables/use-option-menu";
+import { leadingVisualPadding } from "../../utils/options";
 import { isBoolean, isNumber, isString } from "../../utils/predicate";
 import { mergeFormUiClass } from "../../utils/ui";
 const props = defineProps({
@@ -65,6 +66,10 @@ const menu = useOptionMenu({
 });
 const controlUi = computed(() => ({
   ...controlProps.value.ui,
+  base: mergeFormUiClass(
+    controlProps.value.ui?.base,
+    menu.leadingOption.value ? leadingVisualPadding(controlProps.value.size) : void 0
+  ),
   content: mergeFormUiClass(controlProps.value.ui?.content, interactionOwnerClass.value),
   itemDescription: mergeFormUiClass(
     menu.renderOption.value ? "hidden" : "text-[12.5px]",

package/dist/runtime/form/types/page.d.ts

@@ -54,6 +54,13 @@ export interface FormPageSection<TContext = NonNullable<unknown>, TFields extend
     optional?: boolean;
     /** Grid of the section's fields, merged over the schema `layout`. */
     layout?: FormLayoutConfig;
+    /**
+     * Columns, out of twelve, the section takes once the sections area is at least 48rem wide, so
+     * short sections sit side by side: `span: 4` next to `span: 8`. Sections fill the rows in order
+     * and the ones sharing a row stretch to the same height. Below that width, or without a `span`,
+     * the section takes the whole row.
+     */
+    span?: number;
     /** Raw dependency paths read before evaluating `condition`. */
     dependencies?: readonly (string | readonly [string, string])[];
     /** Hides the section, its navigation entry, and its fields while it returns `false`. */
@@ -186,6 +193,10 @@ export interface FormPageSectionState {
     optional: boolean;
     /** Number of required fields without a value, the fields of array items included. */
     missing: number;
+    /** Number of required fields, the fields of array items included. */
+    required: number;
+    /** Columns, out of twelve, the section takes on a wide sections area: 12 without a `span`. */
+    span: number;
     /** Where the section stands, see `FormPageSectionStatus`. */
     status: FormPageSectionStatus;
     /** True when a value of the section differs from the form's baseline. */

package/dist/runtime/form/types/ui.d.ts

@@ -197,10 +197,11 @@ export interface FormOverlayUi {
  * How the sections of a form page are drawn:
  *
  * - `card`: each section is a bordered card on the gray canvas of the page (default)
+ * - `panel`: a card whose heading sits in a bar across its top, above the fields
  * - `plain`: no box. A section is its heading, description, and fields on the page itself,
  *   separated from the next by spacing and a hairline
  */
-export type FormPageSurface = 'card' | 'plain';
+export type FormPageSurface = 'card' | 'panel' | 'plain';
 /**
  * The `page` part of the form UI config: the surface of the sections and the `ui` slots of the
  * page parts. Both follow the usual layering: app config, then schema `ui`, then the `ui` prop.
@@ -208,6 +209,13 @@ export type FormPageSurface = 'card' | 'plain';
 export interface FormPageUiConfig extends FormUiPartConfig<FormPageUi> {
     /** Defaults to `card`. */
     surface?: FormPageSurface;
+    /**
+     * Shows where each section stands at the end of its heading: the required fields filled out of
+     * the total while some are missing ("2 sur 3"), "Complété" once nothing is, "À corriger" while a
+     * field shows an error, and "Facultatif" for an optional section with nothing entered, which
+     * then carries its tag there instead of after the title. Off by default.
+     */
+    status?: boolean;
 }
 /**
  * Slots of a form page and its parts. Data attributes carry the live state, so a slot can
@@ -274,6 +282,8 @@ export interface FormPageUi {
     sectionDescription?: FormUiClass;
     /** The "Optional" badge of an optional section with nothing entered. */
     sectionOptional?: FormUiClass;
+    /** Badge of where the section stands, with `page.status`. Carries `data-form-page-status`. */
+    sectionStatus?: FormUiClass;
     sectionActions?: FormUiClass;
     sectionReset?: FormUiClass;
     sectionBody?: FormUiClass;

package/dist/runtime/form/utils/options.d.ts

@@ -12,6 +12,12 @@ export interface FormOptionKeys {
 export type { ResolvedFormOption } from '../types/index.js';
 /** The one visual an option draws before its label: its icon, else its avatar, else its chip. */
 export type OptionLeading = 'icon' | 'avatar' | 'chip';
+/**
+ * Start padding of a select or auto-complete that draws the chosen option's visual in its leading
+ * slot. Nuxt UI decides that padding from the slot once, so a visual that appears after mount (a
+ * value picked later) would otherwise draw over the text.
+ */
+export declare function leadingVisualPadding(size: unknown): "ps-10" | "ps-9" | "ps-8" | "ps-11" | "ps-7";
 export declare function resolveOptionLeading(option: ResolvedFormOption): OptionLeading | undefined;
 export declare function resolveOptionDescriptionIndent(option: ResolvedFormOption): string | undefined;
 export declare function normalizeOptionItem(option: FormValue, keys?: FormOptionKeys): ResolvedFormOption;

package/dist/runtime/form/utils/options.js

@@ -12,6 +12,13 @@ const CHIP_COLORS = [
   "error",
   "neutral"
 ];
+const LEADING_PADDING = { lg: "ps-10", md: "ps-9", sm: "ps-8", xl: "ps-11", xs: "ps-7" };
+export function leadingVisualPadding(size) {
+  return LEADING_PADDING[isLeadingSize(size) ? size : "md"];
+}
+function isLeadingSize(size) {
+  return isString(size) && Object.hasOwn(LEADING_PADDING, size);
+}
 export function resolveOptionLeading(option) {
   if (option.icon) return "icon";
   if (option.avatar) return "avatar";

package/dist/runtime/form/utils/page-surface.d.ts

@@ -10,6 +10,10 @@ export interface FormPageSurfaceClasses {
     sections: string;
     /** The box of a card, or the spacing, hairline, and modified marker of a plain section. */
     section: string;
+    /** The bar of a panel heading. */
+    sectionHeader: string;
+    /** Padding of the fields under a panel bar. */
+    sectionBody: string;
     /** Where the description sits against the title. */
     sectionDescription: string;
     /** Placeholder shown while the schema context loads. */

package/dist/runtime/form/utils/page-surface.js

@@ -5,14 +5,27 @@ const FORM_PAGE_SURFACES = {
   card: {
     root: "bg-muted",
     section: "gap-[18px] rounded-xl border border-default bg-default px-5 pt-5 pb-6 transition-[border-color,box-shadow] duration-200 @3xl/form-page:px-6 @3xl/form-page:pt-[22px] data-[dirty]:border-primary data-[dirty]:ring-4 data-[dirty]:ring-primary/20 data-[dirty]:ring-inset",
+    sectionBody: "",
     sectionDescription: "order-last basis-full @3xl/form-page:order-none @3xl/form-page:basis-auto",
+    sectionHeader: "",
     sectionSkeleton: "rounded-xl border border-default bg-default px-6 pt-[22px] pb-6",
     sections: "gap-[18px]"
   },
+  panel: {
+    root: "bg-muted",
+    section: "overflow-hidden rounded-xl border border-default bg-default transition-[border-color,box-shadow] duration-200 focus-within:border-accented data-[dirty]:border-primary data-[dirty]:ring-4 data-[dirty]:ring-primary/20 data-[dirty]:ring-inset",
+    sectionBody: "px-5 pt-5 pb-6 @3xl/form-page:px-6",
+    sectionDescription: "order-last basis-full",
+    sectionHeader: "min-h-13 border-b border-default bg-elevated/60 px-4 py-2.5 @3xl/form-page:px-5",
+    sectionSkeleton: "rounded-xl border border-default bg-default px-6 pt-[22px] pb-6",
+    sections: "gap-4"
+  },
   plain: {
     root: "bg-default",
     section: "relative gap-[18px] border-t border-default py-8 first:border-t-0 first:pt-0 last:pb-0 before:pointer-events-none before:absolute before:inset-y-8 before:-start-3 before:w-0.5 before:rounded-full before:transition-colors first:before:top-0 last:before:bottom-0 data-[dirty]:before:bg-primary",
+    sectionBody: "",
     sectionDescription: "order-last basis-full",
+    sectionHeader: "",
     sectionSkeleton: "border-t border-default py-8 first:border-t-0 first:pt-0",
     sections: "gap-0"
   }

package/dist/runtime/form/utils/page.d.ts

@@ -38,3 +38,5 @@ export declare function resolveFormPageSectionState(params: {
     /** False when the validation mode does not enforce required fields. */
     requiredEnforced: boolean;
 }): FormPageSectionState;
+/** Columns a section takes out of twelve: a whole number from 1 to 12, the full row otherwise. */
+export declare function resolveFormPageSectionSpan(value: FormValue): number;

package/dist/runtime/form/utils/page.js

@@ -76,9 +76,14 @@ export function resolveFormPageSectionState(params) {
     label: resolveFormText(entry.section.label) ?? entry.section.key,
     missing,
     optional,
+    required: required.length,
+    span: resolveFormPageSectionSpan(entry.section.span),
     status: resolveFormPageSectionStatus({ invalid, missing, optional, provided })
   };
 }
+export function resolveFormPageSectionSpan(value) {
+  return isNumber(value) && value >= 1 ? Math.min(12, Math.trunc(value)) : 12;
+}
 function collectVisibleLeaves(fields, parentPath, runtime, item = false) {
   return fields.flatMap((field) => {
     if (field.ignore === true) {

package/dist/runtime/i18n/locales/en.js

@@ -206,6 +206,7 @@ export default defineUiToolsLocale({
       },
       page: {
         complete: "Everything is ready.",
+        progress: "{filled} of {required}",
         modifiedOne: "{count} modified.",
         modifiedOther: "{count} modified.",
         navigation: "Form sections",

package/dist/runtime/i18n/locales/fr.js

@@ -206,6 +206,7 @@ export default defineUiToolsLocale({
       },
       page: {
         complete: "Tout est pr\xEAt.",
+        progress: "{filled} sur {required}",
         modifiedOne: "{count} modifi\xE9e.",
         modifiedOther: "{count} modifi\xE9es.",
         navigation: "Sections du formulaire",

package/dist/runtime/i18n/types.d.ts

@@ -464,6 +464,8 @@ export interface UiToolsFormMessages {
         remaining: string;
         /** Navigation summary once every required section is complete. */
         complete: string;
+        /** Status of a section with required fields left, with `page.status`: "{filled} of {required}". */
+        progress: string;
         /** Navigation summary of a form with dirty checking: "{count} modified." */
         modifiedOne: string;
         modifiedOther: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-ui-tools",
-  "version": "1.20.0",
+  "version": "1.21.0",
   "description": "Nuxt module and runtime toolkit for UI-heavy Nuxt applications",
   "homepage": "https://github.com/ChronicStone/nuxt-ui-tools#readme",
   "bugs": "https://github.com/ChronicStone/nuxt-ui-tools/issues",