@omnitend/dashboard-for-laravel 0.41.2 → 0.42.1

package/resources/js/components/extended/DXField.vue

@@ -69,15 +69,30 @@
 
         <!-- Custom value slot overrides the built-in control (checkbox / switch
              / standard types; not switch-list or repeater). -->
+        <!-- A `plaintext` field is display-only, so its value slot is wrapped
+             in `.dx-form-plaintext`: a badge or a line of text then shares
+             the label's centre line instead of sitting at the top of the row. -->
+        <div
+            v-if="showValueSlot && $slots.value && isPlaintext"
+            class="dx-form-plaintext"
+        >
+            <slot
+                name="value"
+                :field="field"
+                :model="model"
+                :value="fieldValue"
+                :update="setValue"
+            />
+        </div>
         <!--
-          @slot Replaces the built-in control with a custom value editor.
+          @slot Replaces the built-in control with a custom value editor. On a `plaintext` field the content is wrapped in `.dx-form-plaintext` so display-only content lines up with the label.
           @binding {FieldDefinition} field The field definition being rendered.
           @binding {any} model The model passed to field predicates (defaults to the live form data).
           @binding {any} value The current field value.
           @binding {(value: any) => void} update Setter that writes the value back and clears the field's validation error.
         -->
         <slot
-            v-if="showValueSlot && $slots.value"
+            v-else-if="showValueSlot && $slots.value"
             name="value"
             :field="field"
             :model="model"
@@ -154,7 +169,7 @@
                 >
                     <DFormGroup
                         v-bind="switchListRowAttrs"
-                        class="mb-0 align-items-center"
+                        class="mb-0"
                     >
                         <template #label>
                             <DXFieldLabel
@@ -420,7 +435,11 @@ interface Props {
      */
     layout?: "vertical" | "horizontal";
 
-    /** Label column width for horizontal layout (mirrors BFormGroup). */
+    /**
+     * Label column width for horizontal layout (mirrors BFormGroup's
+     * `labelCols`/`labelCols*`). Omitted: the label takes
+     * `--dx-form-label-width` (45%) from `sm` up and stacks below.
+     */
     labelCols?: LabelCols;
 
     /**
@@ -487,23 +506,39 @@ function labelColsAttrs(cols: LabelCols | undefined): Record<string, any> {
     return attrs;
 }
 
-// Default to a 3-column label when horizontal but no width was configured,
-// so `layout: "horizontal"` alone is enough to see the effect. When the
-// field's label is hidden, reserve no label column at all — BFormGroup would
-// otherwise still emit an empty label column (it goes horizontal whenever any
-// labelCols are set, regardless of whether a label exists), leaving the
-// control indented in the input column beside dead space. Dropping the column
-// lets the control span full width, so a switch/checkbox self-label lines up
-// with sibling row labels (#78).
+/**
+ * BFormGroup attrs for a horizontal label column. With no `labelCols` from the
+ * caller (field or form), the label is `--dx-form-label-width` (45%) wide from
+ * `sm` up and stacks below: `labelColsSm: true` makes it a `col-sm` (so
+ * BFormGroup goes horizontal and stacks below `sm` like any breakpoint
+ * `labelCols`), and the `--default-width` modifier is what theme.scss sizes.
+ * The 45% falls between two 12-column steps, which is why it is CSS rather
+ * than a column count. An explicit `labelCols` goes through the grid unchanged.
+ */
+function labelColumnAttrs(cols: LabelCols | undefined): Record<string, any> {
+    // Right-align the label column so the label (and the hint that sits
+    // beneath it in horizontal layout) line up against the control column,
+    // like a classic label-left settings form.
+    const labelClass = "text-sm-end dx-field-label-col";
+    if (cols === undefined) {
+        return {
+            labelColsSm: true,
+            labelClass: `${labelClass} dx-field-label-col--default-width`,
+        };
+    }
+    return { ...labelColsAttrs(cols), labelClass };
+}
+
+// `layout: "horizontal"` alone is enough to see the effect (the default label
+// width above). When the field's label is hidden, reserve no label column at
+// all — BFormGroup would otherwise still emit an empty label column (it goes
+// horizontal whenever any labelCols are set, regardless of whether a label
+// exists), leaving the control indented in the input column beside dead
+// space. Dropping the column lets the control span full width, so a
+// switch/checkbox self-label lines up with sibling row labels (#78).
 const horizontalAttrs = computed<Record<string, any>>(() =>
     isHorizontal.value && !props.hideLabel
-        ? {
-              ...labelColsAttrs(props.labelCols ?? 3),
-              // Right-align the label column so the label (and the hint that
-              // sits beneath it in horizontal layout) line up against the
-              // control column, like a classic label-left settings form.
-              labelClass: "text-sm-end dx-field-label-col",
-          }
+        ? labelColumnAttrs(props.labelCols)
         : {},
 );
 
@@ -667,12 +702,7 @@ const resolvedInfo = computed(() => resolveMaybe(props.field.info));
 // FIELD label but would collapse every option row's label column too —
 // `hideLabel` on a switch-list should drop only the section heading.
 const switchListRowAttrs = computed<Record<string, any>>(() =>
-    isHorizontal.value
-        ? {
-              ...labelColsAttrs(props.labelCols ?? 3),
-              labelClass: "text-sm-end dx-field-label-col",
-          }
-        : {},
+    isHorizontal.value ? labelColumnAttrs(props.labelCols) : {},
 );
 
 // The model is an array of selected option values, exactly like
@@ -864,9 +894,10 @@ onBeforeUnmount(() => {
 
 <style scoped>
 /* Switch-list rows (#160): compact rhythm with a divider between rows. The
-   vertical centring of label vs switch is the `align-items-center` utility on
-   each row's DFormGroup (its horizontal root IS the .row element), so no
-   deep selector into bvn internals is needed here. */
+   vertical centring of label, switch and trailing control is a global
+   `.dx-switch-list-row .row` rule in theme.scss: the `.row` is inside
+   bootstrap-vue-next's BFormGroup wrapper, so a class on the DFormGroup
+   lands on the wrapper, not the row. */
 .dx-switch-list-row {
     padding: 0.25rem 0;
     border-bottom: 1px solid var(--bs-border-color);

package/resources/js/components/extended/DXForm.vue

@@ -118,17 +118,18 @@
                 </DXFormField>
 
                 <!-- Submit button -->
-                <DButton
+                <DXSaveButton
                     v-if="showSubmit"
                     type="submit"
-                    variant="primary"
                     block
-                    :loading="resolvedForm.processing"
-                    :loading-text="submitLoadingText"
+                    :saving="resolvedForm.processing"
+                    :saving-text="submitLoadingText"
+                    :saved="isSaved"
+                    :saved-text="submitSavedText"
                     class="mt-3"
                 >
                     {{ submitText }}
-                </DButton>
+                </DXSaveButton>
 
                 <!--
                   @slot Content rendered below the submit button (e.g. a cancel link or secondary actions).
@@ -145,17 +146,18 @@
              trailing form-level actions. -->
         <template v-else>
             <!-- Submit button -->
-            <DButton
+            <DXSaveButton
                 v-if="showSubmit"
                 type="submit"
-                variant="primary"
                 block
-                :loading="resolvedForm.processing"
-                :loading-text="submitLoadingText"
+                :saving="resolvedForm.processing"
+                :saving-text="submitLoadingText"
+                :saved="isSaved"
+                :saved-text="submitSavedText"
                 class="mt-3"
             >
                 {{ submitText }}
-            </DButton>
+            </DXSaveButton>
 
             <!--
               @slot Content rendered below the submit button (e.g. a cancel link or secondary actions).
@@ -167,14 +169,20 @@
 </template>
 
 <script setup lang="ts">
-import { computed, ref, watch, type ComponentPublicInstance } from "vue";
+import {
+    computed,
+    onBeforeUnmount,
+    ref,
+    watch,
+    type ComponentPublicInstance,
+} from "vue";
 import { BForm } from "bootstrap-vue-next";
 import DAlert from "../base/DAlert.vue";
-import DButton from "../base/DButton.vue";
 import DCard from "../base/DCard.vue";
 import DTabs from "../base/DTabs.vue";
 import { BTab as DTab } from "bootstrap-vue-next"; // raw BTab: BTabs scans slot vnodes for it (#119)
 import DXFormField from "./DXFormField.vue";
+import DXSaveButton from "./DXSaveButton.vue";
 import type { UseFormReturn } from "../../composables/useForm";
 import type { DefineFormReturn } from "../../composables/defineForm";
 import { useContainerWidth } from "../../composables/useContainerWidth";
@@ -211,6 +219,17 @@ interface Props {
     /** Submit button loading text */
     submitLoadingText?: string;
 
+    /** Submit button label once the form's contents are saved. */
+    submitSavedText?: string;
+
+    /**
+     * After a successful submission through the form (`form.post/put/…`,
+     * read from `form.wasSuccessful`), turn the submit button into a
+     * disabled "✓ Saved" until any field changes. On by default; set
+     * `false` for forms whose submit is not a save (search, filter).
+     */
+    savedState?: boolean;
+
     /** Show the submit button */
     showSubmit?: boolean;
 
@@ -240,7 +259,10 @@ interface Props {
      * Form-wide field layout:
      *
      * - `"vertical"` (default) — label above input, always.
-     * - `"horizontal"` — label left, input right, always.
+     * - `"horizontal"` — label left, input right, whatever the container
+     *   width. With the default label column that holds from the `sm`
+     *   viewport breakpoint up (the label stacks on a phone); a numeric
+     *   `labelCols` keeps the split at every width.
      * - `"auto"` — horizontal when the form's **own container** is at least
      *   `layoutThreshold` px wide, vertical below that. Container-driven, not
      *   viewport-driven: a page narrowed by the dashboard sidebar, or a form
@@ -256,20 +278,22 @@ interface Props {
      * Container width (px) at or above which `layout: "auto"` goes horizontal.
      * Ignored for the explicit `"vertical"`/`"horizontal"` layouts.
      *
-     * Default 640, measured rather than guessed: with the default 3-column
-     * label the label's text area is `containerWidth / 4 - 18` px, so 640 gives
-     * it 142px — enough for a ~20-character label ("Unit price (ex VAT)"
-     * measures 128px at the theme's label font) to stay on one line, with the
-     * control column still 474px. Below ~584px that label starts wrapping,
-     * which is the cramped-label symptom this exists to avoid. Raise it if your
-     * labels run longer, or lower `labelCols` instead.
+     * Default 640, measured when the default label was 3 columns: that gave
+     * the label 142px of text at 640px, just enough for a ~20-character label
+     * ("Unit price (ex VAT)" measures 128px at the theme's label font) to stay
+     * on one line. With the 45% default label column the same 640px gives the
+     * label ~275px and the control ~341px, so the threshold now mostly keeps
+     * the control column usable. Raise it if your controls need more room, or
+     * set a narrower `labelCols`.
      */
     layoutThreshold?: number;
 
     /**
      * Label column width for horizontal layout (mirrors BFormGroup's
      * `labelCols`/`labelCols*` props). Overridable per-field via
-     * `field.labelCols`. Ignored when `layout` is "vertical".
+     * `field.labelCols`. Ignored when `layout` is "vertical". Omitted (here
+     * and on the field): the label takes `--dx-form-label-width` (45%) from
+     * `sm` up and stacks above the input below `sm`.
      */
     labelCols?: LabelCols;
 }
@@ -277,6 +301,8 @@ interface Props {
 const props = withDefaults(defineProps<Props>(), {
     submitText: "Submit",
     submitLoadingText: "Submitting...",
+    submitSavedText: "Saved",
+    savedState: true,
     showSubmit: true,
     autoErrorTab: true,
     card: false,
@@ -480,6 +506,81 @@ watch(
     { immediate: true },
 );
 
+// ————————————————— saved state (submit button shows "✓ Saved")
+
+/**
+ * True from a successful save until the form's data next changes.
+ *
+ * Three kinds of data write have to be told apart:
+ *
+ * - a user edit BEFORE the response (while the request is in flight) — not
+ *   in the payload, so the save must not be reported as covering it;
+ * - the save's own follow-up writes — `onSuccess` copying the response into
+ *   the form, `resetOnSuccess`, consumer code after `await form.post()` —
+ *   which all run in the response's macrotask and are not edits;
+ * - a user edit AFTER the save — clears the saved state.
+ *
+ * So the success (`wasSuccessful` turning true) opens a one-macrotask window
+ * in which writes are treated as part of the save, and `isSaved` is set when
+ * that window closes, unless the user edited between submit and response.
+ * All three watchers are synchronous so the ordering is exact, not dependent
+ * on Vue's scheduler.
+ */
+const isSaved = ref(false);
+let savedTimer: ReturnType<typeof setTimeout> | null = null;
+let isInSaveResponse = false;
+let wasEditedSinceSubmit = false;
+
+function cancelPendingSaved(): void {
+    if (savedTimer !== null) clearTimeout(savedTimer);
+    savedTimer = null;
+    isInSaveResponse = false;
+}
+
+watch(
+    () => resolvedForm.value.processing,
+    (isProcessing) => {
+        if (!isProcessing) return;
+        cancelPendingSaved();
+        isSaved.value = false;
+        wasEditedSinceSubmit = false;
+    },
+    { flush: "sync" },
+);
+
+watch(
+    () => resolvedForm.value.wasSuccessful,
+    (wasSuccessful) => {
+        if (!wasSuccessful || !props.savedState) return;
+        cancelPendingSaved();
+        isInSaveResponse = true;
+        savedTimer = setTimeout(() => {
+            savedTimer = null;
+            isInSaveResponse = false;
+            // A new submit or a form swap in the meantime cancels this timer.
+            if (!wasEditedSinceSubmit) isSaved.value = true;
+        }, 0);
+    },
+    { flush: "sync" },
+);
+
+watch(
+    () => resolvedForm.value.data,
+    () => {
+        isSaved.value = false;
+        if (!isInSaveResponse) wasEditedSinceSubmit = true;
+    },
+    { deep: true, flush: "sync" },
+);
+
+// A different form instance (or turning the feature off) starts unsaved.
+watch([resolvedForm, () => props.savedState], () => {
+    cancelPendingSaved();
+    isSaved.value = false;
+});
+
+onBeforeUnmount(cancelPendingSaved);
+
 function handleSubmit(): void {
     emit("submit");
 }

package/resources/js/components/extended/DXNumberStepper.vue

@@ -0,0 +1,243 @@
+<!--
+  DXNumberStepper — a number input between a decrease and an increase button.
+
+  `[ − ][ 12 ][ + ]` as one input group, for quantities that are usually
+  nudged rather than typed (cases on an order line, covers on a booking).
+
+  - The model is a number, or `null` when the input is empty (never `NaN`,
+    never `""`). Every step and every valid keystroke emits `update:modelValue`;
+    debounce on the consumer's side if each change saves.
+  - A step adds or subtracts `step` from the current value and clamps to
+    `min`/`max`. It does not snap to a grid, so 1.05 + 0.1 is 1.15. The sum is
+    rounded to the decimal places of the value and step, so 0.1 three times is
+    0.3, not 0.30000000000000004. From empty, a step goes to the in-range value
+    nearest zero.
+  - The button at a bound is disabled (decrease at `min`, increase at `max`).
+  - Typing is free: the value is emitted as typed, even out of range, and is
+    CLAMPED ON BLUR to `min`/`max` (emitting the clamped value). Half-typed
+    input the browser cannot parse ("-", "1e") emits nothing until it parses.
+  - ArrowUp/ArrowDown on the input go through the same step as the buttons
+    (the browser's own spin-button stepping snaps to a grid; this does not).
+    The native spin arrows are hidden. The buttons are `tabindex="-1"`, so a
+    list of steppers is one Tab stop each; keyboard users step with the arrows.
+  - The buttons are square icon buttons at the input's height (never narrower
+    than tall), soft `secondary` like other in-row actions, labelled
+    "Decrease"/"Increase" plus the input's `aria-label` when it has one.
+
+  `class` and `style` go on the group; every other attribute (`aria-label`,
+  `name`, `id`, `placeholder`, `required`, `state`, listeners…) goes on the
+  input. Styles live in theme.scss under `.dx-number-stepper`.
+-->
+<template>
+    <DInputGroup
+        :size="groupSize"
+        :class="['dx-number-stepper', attrs.class]"
+        :style="attrs.style as StyleValue"
+    >
+        <template #prepend>
+            <DButton
+                class="dx-number-stepper__decrease"
+                variant="secondary"
+                icon="dash-lg"
+                icon-only
+                :size="groupSize"
+                :disabled="disabled || isAtMin"
+                :aria-label="decreaseAriaLabel"
+                tabindex="-1"
+                @click="stepBy(-1)"
+            />
+        </template>
+        <DFormInput
+            v-bind="inputAttrs"
+            :model-value="displayValue"
+            type="number"
+            inputmode="decimal"
+            :min="min"
+            :max="max"
+            :step="step"
+            :disabled="disabled"
+            class="dx-number-stepper__input"
+            @input="handleInput"
+            @focus="isFocused = true"
+            @blur="handleBlur"
+            @keydown="handleKeydown"
+        />
+        <template #append>
+            <DButton
+                class="dx-number-stepper__increase"
+                variant="secondary"
+                icon="plus-lg"
+                icon-only
+                :size="groupSize"
+                :disabled="disabled || isAtMax"
+                :aria-label="increaseAriaLabel"
+                tabindex="-1"
+                @click="stepBy(1)"
+            />
+        </template>
+    </DInputGroup>
+</template>
+
+<script setup lang="ts">
+import { computed, ref, useAttrs, watch } from "vue";
+import type { StyleValue } from "vue";
+import DInputGroup from "../base/DInputGroup.vue";
+import DFormInput from "../base/DFormInput.vue";
+import DButton from "../base/DButton.vue";
+
+defineOptions({ inheritAttrs: false });
+
+interface Props {
+    /** The value (v-model). `null` when the input is empty. */
+    modelValue?: number | null;
+    /** Lowest value; the decrease button disables here and blur clamps to it. */
+    min?: number;
+    /** Highest value; the increase button disables here and blur clamps to it. */
+    max?: number;
+    /** How much one press (or ArrowUp/ArrowDown) changes the value. @default 1 */
+    step?: number;
+    /** Control size, matching the other inputs. @default 'md' */
+    size?: "sm" | "md" | "lg";
+    /** Disable the input and both buttons. */
+    disabled?: boolean;
+    /** Override the decrease button's accessible label. Default: "Decrease", plus the input's aria-label. */
+    decreaseLabel?: string;
+    /** Override the increase button's accessible label. Default: "Increase", plus the input's aria-label. */
+    increaseLabel?: string;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+    modelValue: null,
+    min: undefined,
+    max: undefined,
+    step: 1,
+    size: "md",
+    disabled: false,
+    decreaseLabel: undefined,
+    increaseLabel: undefined,
+});
+
+const emit = defineEmits<{
+    "update:modelValue": [value: number | null];
+}>();
+
+const attrs = useAttrs();
+
+// `class`/`style` belong to the group; everything else is for the input.
+const inputAttrs = computed(() => {
+    const { class: _class, style: _style, ...rest } = attrs;
+    return rest;
+});
+
+// bvn's Size has no 'md' (it is the default), so md means "no size".
+const groupSize = computed(() => (props.size === "md" ? undefined : props.size));
+
+const fieldLabel = computed(() => {
+    const label = attrs["aria-label"];
+    return typeof label === "string" && label.trim() !== "" ? label.trim() : "";
+});
+const decreaseAriaLabel = computed(
+    () => props.decreaseLabel ?? (fieldLabel.value === "" ? "Decrease" : `Decrease ${fieldLabel.value}`),
+);
+const increaseAriaLabel = computed(
+    () => props.increaseLabel ?? (fieldLabel.value === "" ? "Increase" : `Increase ${fieldLabel.value}`),
+);
+
+// The value the buttons step from: the last value emitted or received.
+const currentValue = ref<number | null>(props.modelValue);
+// The shown text tracks a local ref so typing is never rewritten mid-edit
+// ("0." must not become "0"); it resyncs from the model while not focused.
+const displayValue = ref(format(props.modelValue));
+const isFocused = ref(false);
+
+watch(
+    () => props.modelValue,
+    (value) => {
+        currentValue.value = value;
+        if (!isFocused.value) displayValue.value = format(value);
+    },
+);
+
+const isAtMin = computed(
+    () => props.min !== undefined && currentValue.value !== null && currentValue.value <= props.min,
+);
+const isAtMax = computed(
+    () => props.max !== undefined && currentValue.value !== null && currentValue.value >= props.max,
+);
+
+function format(value: number | null | undefined): string {
+    if (value === null || value === undefined || !Number.isFinite(value)) return "";
+    return String(value);
+}
+
+/** Decimal places in a number's shortest representation (handles 1e-7). */
+function decimalPlaces(value: number): number {
+    if (!Number.isFinite(value)) return 0;
+    const [mantissa, exponent] = String(value).split("e");
+    const fraction = mantissa.split(".")[1] ?? "";
+    const places = fraction.length - (exponent === undefined ? 0 : Number(exponent));
+    return Math.min(20, Math.max(0, places));
+}
+
+function clamp(value: number): number {
+    let clamped = value;
+    if (props.min !== undefined && clamped < props.min) clamped = props.min;
+    if (props.max !== undefined && clamped > props.max) clamped = props.max;
+    return clamped;
+}
+
+function commit(value: number | null): void {
+    currentValue.value = value;
+    displayValue.value = format(value);
+    emit("update:modelValue", value);
+}
+
+function stepBy(direction: 1 | -1): void {
+    if (props.disabled) return;
+    const stepSize = Number.isFinite(props.step) && props.step > 0 ? props.step : 1;
+    const from = currentValue.value;
+    if (from === null) {
+        commit(clamp(0));
+        return;
+    }
+    const places = Math.max(decimalPlaces(from), decimalPlaces(stepSize));
+    const next = clamp(Number((from + direction * stepSize).toFixed(places)));
+    if (next !== from) commit(next);
+}
+
+function handleInput(event: Event): void {
+    const target = event.target as HTMLInputElement;
+    const raw = target.value;
+    displayValue.value = raw;
+    if (raw.trim() === "") {
+        // A number input reports "" for unparseable text too ("-", "1e");
+        // wait for it to parse rather than emitting null mid-typing.
+        if (target.validity?.badInput) return;
+        currentValue.value = null;
+        emit("update:modelValue", null);
+        return;
+    }
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed)) return;
+    currentValue.value = parsed;
+    emit("update:modelValue", parsed);
+}
+
+// Consumer @blur/@focus/@keydown listeners arrive through `inputAttrs` and are
+// merged with these by Vue, so they are not re-emitted.
+function handleBlur(): void {
+    isFocused.value = false;
+    const value = currentValue.value;
+    if (value !== null && clamp(value) !== value) {
+        commit(clamp(value));
+        return;
+    }
+    displayValue.value = format(value);
+}
+
+function handleKeydown(event: KeyboardEvent): void {
+    if (event.key !== "ArrowUp" && event.key !== "ArrowDown") return;
+    event.preventDefault();
+    stepBy(event.key === "ArrowUp" ? 1 : -1);
+}
+</script>