@omnitend/dashboard-for-laravel 0.45.0 → 0.47.0

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

@@ -113,17 +113,29 @@
   </div>
 </template>
 
-<script setup lang="ts">
-import { ref, computed, useSlots, useId, watch, onMounted, onBeforeUnmount, onActivated, onDeactivated } from 'vue';
+<script setup lang="ts" generic="TNavigation extends Navigation = Navigation">
+import { ref, computed, useId, useTemplateRef, watch, onMounted, onBeforeUnmount, onActivated, onDeactivated } from 'vue';
 import DXDashboardSidebar from './DXDashboardSidebar.vue';
 import DXDashboardNavbar from './DXDashboardNavbar.vue';
 import DContainer from '../base/DContainer.vue';
 import DRow from '../base/DRow.vue';
 import DCol from '../base/DCol.vue';
 import { acquirePageScrollLock, releasePageScrollLock } from '../../utils/pageScrollLock';
-import type { Navigation, NavbarActionsOnMobile, NavbarSearchAlign, SidebarVariant } from '../../types/navigation';
-
-const slots = useSlots();
+import type {
+  DashboardSlots,
+  Navigation,
+  NavigationItemOf,
+  NavbarActionsOnMobile,
+  NavbarSearchAlign,
+  SidebarVariant,
+} from '../../types/navigation';
+
+// Typed slots, derived from the children's slot types (see `DashboardSlots`).
+// `TNavigation` is inferred from the `navigation` prop, so
+// `#sidebar-link="{ item }"` has the app's own item keys (see
+// `NavigationItemOf`). Types only: the forwarding below stays dynamic, so it
+// never lists names.
+const slots = defineSlots<DashboardSlots<NavigationItemOf<TNavigation>>>();
 
 // Slot-binding precedence: the forwarded slots bind the child's own slot props
 // FIRST and `toggleSidebar`/`sidebarHidden` after, so ours win a name clash.
@@ -131,9 +143,12 @@ const slots = useSlots();
 // forwarded slot, and a child that later grew a same-named prop must not be
 // able to silently take the guarantee away. No child uses those names today.
 
-interface Props {
+// Declared inline, not as a local `interface Props`: a generic component's
+// emitted declaration names its props type, and a local interface there fails
+// the declaration build (TS4082).
+const props = withDefaults(defineProps<{
   /** Navigation structure for sidebar */
-  navigation: Navigation;
+  navigation: TNavigation;
 
   /** Current URL path for active state */
   currentUrl: string;
@@ -209,9 +224,7 @@ interface Props {
    * If not provided, uses global HTML class approach (for SSR compatibility)
    */
   dashboardId?: string;
-}
-
-const props = withDefaults(defineProps<Props>(), {
+}>(), {
   title: 'Dashboard',
   pageTitle: '',
   user: null,
@@ -228,13 +241,15 @@ const props = withDefaults(defineProps<Props>(), {
 
 const collapsed = ref(false);
 
-// Compute sidebar slots (strip 'sidebar-' prefix)
+// Compute sidebar slots (strip 'sidebar-' prefix). The values are typed as
+// declared slot names so the template's `<slot :name>` type-checks; at runtime
+// any `sidebar-*`/`navbar-*` slot the consumer passes is forwarded.
 const sidebarSlots = computed(() => {
-  const result: Record<string, string> = {};
+  const result: Record<string, keyof DashboardSlots> = {};
   Object.keys(slots).forEach(name => {
     if (name.startsWith('sidebar-')) {
       const strippedName = name.substring(8); // Remove 'sidebar-' prefix
-      result[strippedName] = name;
+      result[strippedName] = name as keyof DashboardSlots;
     }
   });
   return result;
@@ -242,11 +257,11 @@ const sidebarSlots = computed(() => {
 
 // Compute navbar slots (strip 'navbar-' prefix)
 const navbarSlots = computed(() => {
-  const result: Record<string, string> = {};
+  const result: Record<string, keyof DashboardSlots> = {};
   Object.keys(slots).forEach(name => {
     if (name.startsWith('navbar-')) {
       const strippedName = name.substring(7); // Remove 'navbar-' prefix
-      result[strippedName] = name;
+      result[strippedName] = name as keyof DashboardSlots;
     }
   });
   return result;
@@ -352,7 +367,9 @@ const phoneMenuOpen = computed(
 
 const sidebarId = `${useId()}-sidebar`;
 const layoutRef = ref<HTMLElement | null>(null);
-const sidebarComponent = ref<InstanceType<typeof DXDashboardSidebar> | null>(null);
+// A ref to the generic sidebar carries only what it exposes; its root element
+// is the exposed `el`.
+const sidebarInstance = useTemplateRef('sidebarComponent');
 
 const setHidden = (isHidden: boolean): void => {
   hidden.value = isHidden;
@@ -388,8 +405,7 @@ const onSidebarNavigate = (): void => {
   closePhoneMenu();
 };
 
-const sidebarElement = (): HTMLElement | null =>
-  (sidebarComponent.value?.$el as HTMLElement | undefined) ?? null;
+const sidebarElement = (): HTMLElement | null => sidebarInstance.value?.el ?? null;
 
 const onKeydown = (event: KeyboardEvent): void => {
   if (event.key !== 'Escape') return;
@@ -489,6 +505,13 @@ defineExpose({
 
   /** Whether the sidebar is currently hidden. */
   sidebarHidden: computed(() => hidden.value),
+
+  /**
+   * The dashboard's root element (the `.dashboard-layout` `<div>`; `null`
+   * before mount). A template ref to this generic component carries only its
+   * exposed members, so read the DOM node here rather than through `$el`.
+   */
+  el: layoutRef,
 });
 </script>
 

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

@@ -122,7 +122,15 @@ import DContainer from "../base/DContainer.vue";
 import DButton from "../base/DButton.vue";
 import DDropdown from "../base/DDropdown.vue";
 import DXUserAvatar from "./DXUserAvatar.vue";
-import type { NavbarActionsOnMobile, NavbarSearchAlign } from "../../types/navigation";
+import type {
+  DashboardNavbarSlots,
+  NavbarActionsOnMobile,
+  NavbarSearchAlign,
+} from "../../types/navigation";
+
+// Typed slots: consumers get autocomplete and slot-prop types, and DXDashboard
+// derives its `navbar-*` slot types from this interface.
+defineSlots<DashboardNavbarSlots>();
 
 const props = withDefaults(
   defineProps<{

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

@@ -165,13 +165,26 @@
   </aside>
 </template>
 
-<script setup lang="ts">
+<script setup lang="ts" generic="TNavigation extends Navigation = Navigation">
 import { computed, ref, onMounted, watch, nextTick, useId } from 'vue';
-import type { Navigation, NavigationGroup, SidebarVariant } from '../../types/navigation';
+import type {
+  DashboardSidebarSlots,
+  Navigation,
+  NavigationGroup,
+  NavigationItemOf,
+  SidebarVariant,
+} from '../../types/navigation';
+
+// Typed slots: consumers get autocomplete and slot-prop types, and DXDashboard
+// derives its `sidebar-*` slot types from this interface. `TNavigation` is
+// inferred from the `navigation` prop, so an app whose items carry extra keys
+// gets them on the `link` slot's `item` (see `NavigationItemOf`). Types only:
+// nothing at runtime depends on it.
+defineSlots<DashboardSidebarSlots<NavigationItemOf<TNavigation>>>();
 
 const props = withDefaults(defineProps<{
   /** Grouped navigation to render: an array of groups, each with a label and items. */
-  navigation: Navigation;
+  navigation: TNavigation;
   /** The current route URL, used to highlight the matching nav item and open its group. */
   currentUrl: string;
   /** Collapse the rail to an icons-only strip, hiding labels and the brand title. */
@@ -469,6 +482,15 @@ watch(() => props.currentUrl, () => {
 watch(activeGroupIndex, () => {
   openActiveGroup();
 });
+
+defineExpose({
+  /**
+   * The sidebar's root `<aside>` element (`null` before mount). A template ref
+   * to this generic component carries only its exposed members, so read the
+   * DOM node here rather than through `$el`.
+   */
+  el: sidebarRef,
+});
 </script>
 
 <style scoped>

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

@@ -1,6 +1,6 @@
 <!--
   @component
-  Renders a single `FieldDefinition` of any type (text, select, autocomplete, checkbox, switch, repeater, currency, percentage, file/image, component, etc.) with its label, validation error, hint and help. Used by `DXForm` and `DXTable`'s edit modal; exposes `value`, `span`, `info`, `info-popover`, `hint` and `repeater-row` slots for per-field customisation.
+  Renders a single `FieldDefinition` of any type (text, select, autocomplete, checkbox, switch, repeater, currency, percentage, file/image, component, etc.) with its label, validation error, hint and help. Used by `DXForm` and `DXTable`'s edit modal; exposes `value`, `span`, `info`, `info-popover`, `hint`, `repeater-row` and `password-actions` slots for per-field customisation.
 
   Structure (#135): a thin DISPATCHER. The shared chrome (label + validation
   feedback + hint + help + info) lives in `DXFieldShell`; the numeric controls
@@ -336,28 +336,61 @@
                 <!-- Password with a reveal toggle (the default for
                      `type: "password"`). Typing a long password blind is the one
                      place the eye really earns its keep, so it's opt-out
-                     (`revealable: false`) rather than opt-in. -->
-                <DInputGroup v-else-if="isRevealablePassword">
-                    <DFormInput
-                        v-model="textFieldModel"
-                        :required="field.required"
-                        :placeholder="field.placeholder"
-                        :state="fieldState"
-                        :disabled="isDisabled"
-                        :readonly="isReadonly"
-                        v-bind="passwordInputProps"
-                    />
-                    <template #append>
-                        <DButton
-                            variant="outline-secondary"
-                            :icon="passwordRevealed ? 'eye-slash' : 'eye'"
-                            :aria-label="passwordRevealed ? 'Hide password' : 'Show password'"
-                            :aria-pressed="passwordRevealed"
+                     (`revealable: false`) rather than opt-in. The eye is drawn
+                     as part of the field (`.dx-password-reveal`: the input's
+                     border, radius and background). A `password-actions` slot
+                     lands AFTER the input group, in `.dx-password-field__actions`,
+                     which wraps below the group when the row cannot give the
+                     input `--dx-password-input-min-width` (theme.scss); it also
+                     brings the group to a `revealable: false` field. -->
+                <div v-else-if="isPasswordGroup()" class="dx-password-field">
+                    <DInputGroup class="dx-password-field__group">
+                        <DFormInput
+                            v-model="textFieldModel"
+                            :required="field.required"
+                            :placeholder="field.placeholder"
+                            :state="fieldState"
                             :disabled="isDisabled"
-                            @click="passwordRevealed = !passwordRevealed"
+                            :readonly="isReadonly"
+                            v-bind="passwordInputProps"
                         />
-                    </template>
-                </DInputGroup>
+                        <template #append>
+                            <DButton
+                                v-if="isRevealablePassword"
+                                class="dx-password-reveal"
+                                variant="outline-secondary"
+                                icon-only
+                                :icon="passwordRevealed ? 'eye-slash' : 'eye'"
+                                :aria-label="passwordRevealed ? 'Hide password' : 'Show password'"
+                                :aria-pressed="passwordRevealed"
+                                :disabled="isDisabled"
+                                @click="passwordRevealed = !passwordRevealed"
+                            />
+                        </template>
+                    </DInputGroup>
+                    <div v-if="slots['password-actions'] !== undefined" class="dx-password-field__actions">
+                        <!--
+                          @slot Extra controls beside a password input, after its input group (the input and the reveal (eye) toggle), e.g. a "Generate password" button. They sit on the input's row while it keeps `--dx-password-input-min-width`, and wrap below it when the row is too narrow. Use an ordinary button (a `secondary` `DButton` matches the form's other buttons). Not rendered on a `plaintext` field.
+                          @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.
+                          @binding {boolean} revealed Whether the password is currently shown as plain text.
+                          @binding {(revealed: boolean) => void} setRevealed Show (`true`) or mask (`false`) the password, exactly as the eye does. A no-op on a `revealable: false` field.
+                          @binding {boolean} disabled Whether the field is disabled or read-only, so actions that change the value can disable themselves.
+                        -->
+                        <slot
+                            name="password-actions"
+                            :field="field"
+                            :model="model"
+                            :value="fieldValue"
+                            :update="setValue"
+                            :revealed="passwordRevealed"
+                            :set-revealed="setPasswordRevealed"
+                            :disabled="isDisabled || isReadonly"
+                        />
+                    </div>
+                </div>
 
                 <!-- Text-based inputs (text/email/password/url/tel/date/time/datetime) -->
                 <DFormInput
@@ -819,6 +852,32 @@ const isRevealablePassword = computed(
         !isPlaintext.value,
 );
 
+/*
+ * The password input group: the eye (unless `revealable: false`) plus any
+ * `password-actions` slot content. A `revealable: false` field with no slot
+ * stays a bare input, as before; with the slot it gets the group so the
+ * actions have somewhere to sit, but still no eye and no way to unmask.
+ * A function, not a computed: `useSlots()` is not reactive, so a computed
+ * would keep the first render's answer if the slot came or went later.
+ */
+function isPasswordGroup(): boolean {
+    return (
+        isRevealablePassword.value ||
+        (props.field.type === "password" &&
+            !isPlaintext.value &&
+            slots["password-actions"] !== undefined)
+    );
+}
+
+/**
+ * The `password-actions` slot's handle on the reveal state: the same state
+ * the eye toggles, so the two never disagree. Refused on a `revealable: false`
+ * field, which promises never to unmask.
+ */
+function setPasswordRevealed(revealed: boolean): void {
+    passwordRevealed.value = isRevealablePassword.value && revealed === true;
+}
+
 // DXTable reuses ONE DXField instance per field key across modal opens (the
 // v-for is keyed on `field.key`, which is stable across rows) and swaps in a
 // fresh form per record. Without this, revealing row A's password leaves row
@@ -864,10 +923,14 @@ const controlPropsWithGuards = computed(() => {
     return merged;
 });
 
-// The reveal toggle owns the password input's `type`.
+// The reveal toggle owns the password input's `type`. Only a revealable field
+// can be shown as text (`setPasswordRevealed` also refuses the others).
 const passwordInputProps = computed(() => ({
     ...inputPropsWithGuards.value,
-    type: passwordRevealed.value ? "text" : "password",
+    type:
+        passwordRevealed.value && isRevealablePassword.value
+            ? "text"
+            : "password",
 }));
 
 const inputType = computed<string>(() => {

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

@@ -5,7 +5,8 @@
   Owns the single per-field render block that DXForm's tabbed and flat layouts
   both need: the `field(<key>)` full-replacement slot, the
   `field-before(<key>)`/`field-after(<key>)` wrapper slots, and the `<DXField>`
-  element with its `value`/`span`/`info`/`hint`/`repeater-row` slot forwarding.
+  element with its `value`/`span`/`info`/`hint`/`repeater-row`/
+  `switch-list-item`/`password-actions` slot forwarding.
 
   Extracted so those per-field props/slots are wired in ONE place — before this,
   DXForm carried two near-identical copies (tabbed + flat) and a new per-field
@@ -99,6 +100,7 @@ function fieldSlotMap(): Record<string, string> {
     ["hint", `hint(${key})`],
     ["repeater-row", `repeater-row(${key})`],
     ["switch-list-item", `switch-list-item(${key})`],
+    ["password-actions", `password-actions(${key})`],
   ];
   for (const [target, source] of candidates) {
     if (slots[source]) map[target] = source;

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

@@ -17,15 +17,28 @@
       </div>
     </div>
 
-    <div class="dx-stat-card__value">
-      <!--
-        @slot Override the rendered value.
-        @binding {string} formatted The value formatted per `format`.
-        @binding {string | number} value The raw value prop.
-      -->
-      <slot name="value" :formatted="formattedValue" :value="value">
-        {{ formattedValue }}
-      </slot>
+    <!-- The value's box (#213): a numeric value is fitted to this box's
+         width (utils/statCardFit.ts), so two cards to a phone row shrink a
+         long number instead of wrapping it, while a short one stays full
+         size. It is also a size container, for the CSS baseline used
+         before the fit runs. It wraps the value alone, not the card, so
+         inline-size containment never removes the title's or footer's
+         contribution to the width of a content-sized card. -->
+    <div ref="valueBox" class="dx-stat-card__value-box">
+      <div
+        ref="valueElement"
+        class="dx-stat-card__value"
+        :class="{ 'dx-stat-card__value--numeric': isNumericValue }"
+      >
+        <!--
+          @slot Override the rendered value.
+          @binding {string} formatted The value formatted per `format`.
+          @binding {string | number} value The raw value prop.
+        -->
+        <slot name="value" :formatted="formattedValue" :value="value">
+          {{ formattedValue }}
+        </slot>
+      </div>
     </div>
 
     <div v-if="hasDelta || deltaLabel || $slots.trend" class="dx-stat-card__foot">
@@ -49,9 +62,10 @@
 </template>
 
 <script setup lang="ts">
-import { computed } from "vue";
+import { computed, onActivated, onBeforeUnmount, onMounted, ref } from "vue";
 import DCard from "../base/DCard.vue";
 import DBadge from "../base/DBadge.vue";
+import { queueFit, registerTarget, unregisterTarget, type FitTarget } from "../../utils/statCardFit";
 
 type StatFormat = "number" | "currency" | "percent";
 type DeltaDirection = "up" | "down" | "neutral";
@@ -114,6 +128,81 @@ const formattedValue = computed<string>(() => {
   return formatNumber(raw, props.format);
 });
 
+// A number, or a string with no letters ("£1,234.56", "42%"): it must never
+// break between digits. Any other string (a URL, a status word) keeps the
+// card's last-resort break so it cannot run out of the card.
+const isNumericValue = computed<boolean>(
+  () => typeof props.value === "number" || !/\p{L}/u.test(props.value),
+);
+
+const valueBox = ref<HTMLElement | null>(null);
+const valueElement = ref<HTMLElement | null>(null);
+let fitTarget: FitTarget | null = null;
+let resizeObserver: ResizeObserver | null = null;
+let mutationObserver: MutationObserver | null = null;
+
+// Browser-only, and onMounted never runs during server rendering, so the
+// server's markup carries the CSS baseline size.
+onMounted(() => {
+  if (!valueBox.value || !valueElement.value) return;
+  const target: FitTarget = {
+    box: valueBox.value,
+    value: valueElement.value,
+    isNumeric: () => isNumericValue.value,
+    fittedBoxWidth: -1,
+  };
+  fitTarget = target;
+  registerTarget(target);
+  // A microtask: after every card in this render has mounted (one batch),
+  // and before the browser paints.
+  queueFit(target, "microtask");
+
+  if (typeof ResizeObserver !== "undefined") {
+    resizeObserver = new ResizeObserver((entries) => {
+      // Text is never fitted; a change to or from text is a mutation.
+      if (!target.isNumeric()) return;
+      const width = entries[entries.length - 1]!.contentRect.width;
+      // A fit changes the box's height; only a new width needs a new fit.
+      if (Math.abs(width - target.fittedBoxWidth) < 0.01) return;
+      queueFit(target, "frame");
+    });
+    resizeObserver.observe(target.box);
+  }
+
+  // Whatever renders in the value changing (the formatted value, the
+  // numeric class, `value` slot content at any depth) refits. The fit's own
+  // writes (`style` on the value element) are ignored.
+  if (typeof MutationObserver !== "undefined") {
+    mutationObserver = new MutationObserver((records) => {
+      const changed = records.some(
+        (record) => !(record.target === target.value && record.attributeName === "style"),
+      );
+      if (changed) queueFit(target, "microtask");
+    });
+    mutationObserver.observe(target.value, {
+      childList: true,
+      subtree: true,
+      characterData: true,
+      attributes: true,
+    });
+  }
+});
+
+// Back from a deactivated <KeepAlive>: the value or the layout may have
+// changed while it was detached, when no fit could measure it.
+onActivated(() => {
+  if (fitTarget) queueFit(fitTarget, "microtask");
+});
+
+onBeforeUnmount(() => {
+  resizeObserver?.disconnect();
+  mutationObserver?.disconnect();
+  resizeObserver = null;
+  mutationObserver = null;
+  if (fitTarget) unregisterTarget(fitTarget);
+  fitTarget = null;
+});
+
 const hasDelta = computed(
   () => typeof props.delta === "number" && Number.isFinite(props.delta),
 );
@@ -176,13 +265,67 @@ const formattedDelta = computed<string>(() => {
   flex-shrink: 0;
 }
 
+/*
+ * Inline-size containment means the box's content no longer gives it a
+ * width, so a card sized to its content (a non-growing flex item, an
+ * inline-block, a `col-auto`) would take only its title's width and crush
+ * the value. The intrinsic fallback, 8rem (128px), holds a 7-figure amount
+ * at the 1.125rem floor: "£1,234,567.89" is 6.64em, 119.6px at 18px.
+ */
+.dx-stat-card__value-box {
+  container-type: inline-size;
+  contain-intrinsic-inline-size: 8rem;
+}
+
+/*
+ * The size is the fit's (`--dx-stat-card-fit-size`, set by the script on a
+ * numeric value: 1.75rem unless that overflows the box, then just small
+ * enough, down to 1.125rem). Before the fit has run (server markup, first
+ * paint of hydrated markup, no script) a numeric value uses the baseline
+ * below and any other value 1.75rem; text wraps, so it is never shrunk.
+ * Tabular figures (#215) keep each digit on the same advance: the digits
+ * come from the theme's figures face (`--dx-font-family-figures`, as
+ * `.dx-tabular`), the rest of the value from the body face.
+ */
 .dx-stat-card__value {
-  font-size: 1.75rem;
+  font-size: var(--dx-stat-card-fit-size, 1.75rem);
+  font-family: var(--dx-font-family-figures), var(--bs-body-font-family);
+  font-variant-numeric: tabular-nums;
   font-weight: 700;
   line-height: 1.1;
   color: var(--bs-emphasis-color, var(--bs-body-color));
 }
 
+/*
+ * A numeric value (a number, or a string with no letters) never breaks:
+ * `normal` undoes the card's `word-wrap: break-word`, which split a number
+ * mid-figure when it overflowed. Any other string keeps that last-resort
+ * break, so a long URL wraps inside the card instead of running out of it.
+ */
+.dx-stat-card__value--numeric {
+  overflow-wrap: normal;
+}
+
+/*
+ * The numeric baseline before the fit runs, which never overflows for up
+ * to 7 figures: 1.75rem from a 175px box up, then a line down to the
+ * 1.125rem floor at 8rem (128px). (A plain `16cqi` also reaches 1.75rem at
+ * 175px but cannot hold a 6.64em value under 175px.) The slope is 10px over
+ * 47px, written 0.2128 so it reaches 28px at 175px, never just under. It
+ * sits in `@supports` because the `var()` makes the declaration valid at
+ * parse time: without container units the cqi fallback would be invalid at
+ * computed time and the value would fall to the inherited body size, where
+ * this way such a browser keeps the flat 1.75rem above.
+ */
+@supports (width: 1cqi) {
+  .dx-stat-card__value--numeric {
+    font-size: var(
+      --dx-stat-card-fit-size,
+      clamp(1.125rem, 1.125rem + (100cqi - 8rem) * 0.2128, 1.75rem)
+    );
+  }
+}
+
 .dx-stat-card__foot {
   display: flex;
   align-items: center;