@omnitend/dashboard-for-laravel 0.41.1 → 0.42.0

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/DXLoading.vue

@@ -0,0 +1,47 @@
+<template>
+  <div
+    v-if="isVisible"
+    class="dx-loading text-center text-muted py-5"
+    role="status"
+    aria-live="polite"
+  >
+    <DSpinner variant="primary" aria-hidden="true" />
+    <div class="mt-2">{{ text }}</div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { onBeforeUnmount, onMounted, ref } from "vue";
+import DSpinner from "../base/DSpinner.vue";
+
+const props = withDefaults(
+  defineProps<{
+    text?: string;
+    delay?: number;
+  }>(),
+  {
+    text: "Loading…",
+    delay: 300,
+  },
+);
+
+const isVisible = ref(false);
+let showTimer: ReturnType<typeof setTimeout> | undefined;
+
+onMounted(() => {
+  if (props.delay <= 0) {
+    isVisible.value = true;
+    return;
+  }
+
+  showTimer = setTimeout(() => {
+    isVisible.value = true;
+  }, props.delay);
+});
+
+onBeforeUnmount(() => {
+  if (showTimer !== undefined) {
+    clearTimeout(showTimer);
+  }
+});
+</script>

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

@@ -0,0 +1,13 @@
+<!-- Shared secondary modal actions; distinct from the modal footer controls. -->
+<template>
+  <div class="dx-modal-actions"><slot /></div>
+</template>
+
+<style scoped>
+.dx-modal-actions {
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+  gap: 0.75rem;
+}
+</style>

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>

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

@@ -0,0 +1,82 @@
+<!--
+  DXSaveButton — a save button that confirms the save in place.
+
+  Three states, driven by two booleans the consumer owns:
+
+  - idle (`saving` and `saved` both false) — the normal Save button.
+  - saving (`saving`) — DButton's busy state: disabled at once, spinner after
+    the anti-flash delay, `savingText` if given.
+  - saved (`saved` and not `saving`) — "✓ Saved" (tick icon) and genuinely
+    `disabled`, until the consumer clears `saved` (typically on the next edit
+    to the form). The colour does not change: the button keeps its own
+    variant (navy primary by default) at full strength, neither the neutral
+    grey of a disabled button nor a faded one. Only the label and the
+    disabled state say it is saved.
+
+  `saving` wins over `saved`, so re-saving from the saved state shows busy.
+  The label change is announced: the button itself is a polite live region,
+  and while it is `aria-busy` (saving) announcements wait until it settles,
+  so a screen reader hears "Saved" once the save lands.
+
+  Every other attribute (type, block, size, class, listeners…) passes through
+  to DButton. DXForm uses this for its submit button.
+-->
+<template>
+    <DButton
+        v-bind="$attrs"
+        :variant="variant"
+        :icon="isShowingSaved ? 'check-lg' : icon"
+        :loading="saving"
+        :loading-text="savingText"
+        :disabled="disabled || isShowingSaved"
+        :class="{ 'dx-save-button--saved': isShowingSaved }"
+        aria-live="polite"
+    >
+        <template v-if="isShowingSaved">{{ savedText }}</template>
+        <slot v-else>Save</slot>
+    </DButton>
+</template>
+
+<script setup lang="ts">
+import { computed } from "vue";
+import type { ButtonVariant } from "bootstrap-vue-next";
+import DButton from "../base/DButton.vue";
+
+defineOptions({ inheritAttrs: false });
+
+interface Props {
+    /** A save is in flight: busy/spinner state (DButton's `loading`). */
+    saving?: boolean;
+
+    /**
+     * The form's current contents have been saved: show `savedText` with a
+     * tick and disable the button. Clear it when the form changes.
+     */
+    saved?: boolean;
+
+    /** Label for the saved state. @default 'Saved' */
+    savedText?: string;
+
+    /** Label shown beside the spinner while saving (DButton's `loadingText`). */
+    savingText?: string;
+
+    /** Variant in every state; the saved state keeps it. @default 'primary' */
+    variant?: ButtonVariant | null;
+
+    /** Leading icon when not saved. The saved state shows `check-lg`. */
+    icon?: string;
+
+    /** Disable the button regardless of state. */
+    disabled?: boolean;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+    saving: false,
+    saved: false,
+    savedText: "Saved",
+    variant: "primary",
+    disabled: false,
+});
+
+const isShowingSaved = computed(() => props.saved && !props.saving);
+</script>

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

@@ -5,7 +5,7 @@
   An opinionated switch built on `DFormCheckbox` (`switch`): a bordered box sized
   like a `.form-control` with the label on the left and the toggle on the right,
   colour-coding its state. By default (`onVariant="success"`) it reads the house
-  green-on / red-off style: a light-red box with a grey toggle when off, a
+  green-on / red-off style: a light-red box with a muted red-grey toggle when off, a
   soft-green box with a muted green-grey toggle when on. `onVariant="neutral"` (brand primary on / grey off)
   is for semantically-mixed switches that shouldn't imply good/bad (#158). Used
   standalone or, internally, by `DXField`'s `switch` field type so a form switch
@@ -64,7 +64,7 @@ interface Props {
    */
   onVariant?: "success" | "neutral";
   /**
-   * `"sm"` renders a compact box (a few px shorter than the default, which
+   * `"sm"` renders a compact rounded pill (a few px shorter than the default, which
    * matches the input height) for dense rows that repeat the switch per item (a
    * per-line visibility toggle in a modal). Omit for the standard size, which
    * lines the switch up with the `.form-control`
@@ -147,6 +147,7 @@ defineOptions({
    chrome tightens. */
 .dx-switch--sm :deep(.form-check) {
   font-size: 0.875rem;
+  border-radius: var(--bs-border-radius-pill, 50rem);
   min-height: auto;
   padding: 0.25rem 0.625rem;
 }
@@ -173,6 +174,10 @@ defineOptions({
    glance (the house style). `success` (default) is green ON / light-red OFF;
    `neutral` keeps a brand primary panel for mixed-semantics switches. Pair with
    `textWhenTrue`/`textWhenFalse` so the LABEL also names each state. */
+.dx-switch--success {
+  --dx-switch-pill: var(--dx-switch-off-pill);
+}
+
 .dx-switch--success :deep(.form-check) {
   background-color: var(--dx-switch-off-bg);
   border-color: var(--dx-switch-off-line);
@@ -189,14 +194,13 @@ defineOptions({
 
 .dx-switch--success.dx-switch--on :deep(.form-check-label) {
   color: var(--dx-switch-on-ink);
-  font-weight: 500;
 }
 
 .dx-switch--success.dx-switch--on {
   --dx-switch-pill: var(--dx-switch-on-pill);
 }
 
-/* Muted pill with a white sliding thumb: green-grey ON, neutral grey OFF.
+/* Muted pill with a white sliding thumb: green-grey ON, red-grey OFF.
    The stronger box colour and position continue to communicate the state. Explicit `:checked`/`:focus` selectors so they out-specify the global
    `.form-switch .form-check-input:checked` rule. */
 .dx-switch--success :deep(.form-check-input),
@@ -220,6 +224,5 @@ defineOptions({
 
 .dx-switch--neutral.dx-switch--on :deep(.form-check-label) {
   color: var(--bs-primary-text-emphasis);
-  font-weight: 500;
 }
 </style>