@omnitend/dashboard-for-laravel 0.34.0 → 0.36.0

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

@@ -15,17 +15,32 @@
   once it lives in a child component — the scope-id doesn't cross the boundary.
   Anchoring the rules on this component's own `.dx-table-pagination` root (a
   plain element it owns) gives the scope-id a deterministic host.
+
+  In a row too narrow for the full windowed pager, the number strip collapses to
+  a "current / last" status with Previous/Next either side (#162). The decision
+  is CONTAINER-driven, not viewport-driven — see `compactThreshold`.
 -->
 <template>
     <div class="dx-table-pagination mt-3">
-        <!-- Top row: Pagination and Per-page selector -->
-        <div class="dx-pager-row d-flex justify-content-between align-items-center gap-2 mb-2">
+        <!-- Top row: Pagination and Per-page selector.
+             `containerRef` measures THIS row (the space the pager actually
+             competes for with the per-page selector) rather than the window —
+             a table narrowed by a sidebar or a modal is cramped even on a wide
+             viewport, which no media query can see. See `useContainerWidth`. -->
+        <div
+            ref="containerRef"
+            class="dx-pager-row d-flex justify-content-between align-items-center gap-2 mb-2"
+        >
             <!-- Windowed pager (#155): «Previous / leading / … / window / … /
                  trailing / Next». Client-computed from current + last page, so it
-                 works in every DXTable mode. Only shown when >1 page. -->
+                 works in every DXTable mode. Only shown when >1 page.
+                 In a row too narrow to lay the whole thing out, the number
+                 window collapses to a "current / last" status (#162) — see
+                 `isCompact`. -->
             <nav
                 v-if="showPagination && pagination.total > pagination.per_page"
                 class="dx-pager d-flex flex-wrap align-items-center gap-1"
+                :class="{ 'dx-pager--compact': isCompact }"
                 aria-label="Pagination"
             >
                 <DButton
@@ -35,7 +50,28 @@
                     @click="goToPage(currentPage - 1)"
                 >&laquo; Previous</DButton>
 
-                <template v-for="(item, index) in pageItems" :key="item.type === 'page' ? `p${item.page}` : `e${index}`">
+                <!-- Compact: one status in place of the whole number window.
+                     With no page buttons there is no `aria-current` to carry
+                     "you are here", so the position becomes a live `status`
+                     region — it is announced when paging changes it, which the
+                     numbered pager achieved through focus moving to the newly
+                     active button. The terse "11 / 45" is for the eye only
+                     (a screen reader would say "eleven slash forty-five"); the
+                     announced text is the visually-hidden long form. -->
+                <span
+                    v-if="isCompact"
+                    class="dx-pager-status small"
+                    role="status"
+                    aria-live="polite"
+                >
+                    <span class="visually-hidden">Page {{ currentPage }} of {{ lastPage }}</span>
+                    <span aria-hidden="true">{{ currentPage }} / {{ lastPage }}</span>
+                </span>
+
+                <template
+                    v-for="(item, index) in visiblePageItems"
+                    :key="item.type === 'page' ? `p${item.page}` : `e${index}`"
+                >
                     <DButton
                         v-if="item.type === 'page'"
                         size="sm"
@@ -94,6 +130,7 @@
 import { computed } from "vue";
 import DButton from "../base/DButton.vue";
 import DFormSelect from "../base/DFormSelect.vue";
+import { useContainerWidth } from "../../composables/useContainerWidth";
 import type { PaginationData } from "./DXTable.vue";
 
 interface Props {
@@ -115,9 +152,31 @@ interface Props {
     pluralItemName: string;
     /** Whether a column filter is active — gates the "Filtered from N" note. */
     hasActiveFilters: boolean;
+
+    /**
+     * Upper bound (px) on the pager ROW width at which the number window may
+     * collapse to the compact "current / last" status (#162). At or above it
+     * the full windowed pager always renders, whatever the page count.
+     *
+     * Default **576** — Bootstrap's `sm` breakpoint, i.e. the width the rest of
+     * the design system already treats as phone-sized. Its job is to GUARANTEE
+     * that a desktop-width table is never quietly downgraded: a 45-page window
+     * that doesn't quite fit at 800px should wrap (today's behaviour), not lose
+     * its numbers.
+     *
+     * Below it, compact engages only when the full pager genuinely would not
+     * fit on one line (see `fullPagerWidth`) — so a three-page pager still
+     * shows `1 2 3` on a phone, where "2 / 3" would be strictly worse.
+     *
+     * Measured on the ROW, not the viewport, so a table squeezed by a sidebar
+     * or inside a modal collapses even though the window is wide.
+     */
+    compactThreshold?: number;
 }
 
-const props = defineProps<Props>();
+const props = withDefaults(defineProps<Props>(), {
+    compactThreshold: 576,
+});
 
 const emit = defineEmits<{
     /** The user picked a page. Payload is the new 1-based page number. */
@@ -135,7 +194,7 @@ const emit = defineEmits<{
 // except a single-page gap which shows the page itself (an ellipsis hiding one
 // page is silly). Client-computed from current + last page so it works in every
 // DXTable mode (provider / client-side / inertia) — not just where a server
-// `links` array exists. Reproduces custard's `1 2 … 8 9 10 [11] 12 13 14 … 44 45`.
+// `links` array exists. Reproduces the house style: `1 2 … 8 9 10 [11] 12 13 14 … 44 45`.
 const BOUNDARY = 2;
 const AROUND = 3;
 
@@ -182,6 +241,71 @@ const pageItems = computed<PageItem[]>(() => {
   return items;
 });
 
+// Compact pager (#162). Container-driven, not viewport-driven — see the
+// `compactThreshold` prop.
+//
+// Approximate intrinsic widths of the pager's parts, in rem, mirroring this
+// component's own CSS and button labels: a page key is `min-width: 2.5rem`, the
+// row is `gap-1` (0.25rem), the ellipsis is a glyph plus 0.15rem side padding,
+// and "« Previous" + "Next »" together come to about 10rem at `.btn-sm`.
+// Deliberately an ESTIMATE, not a measurement: being wrong by a few px only
+// shifts the collapse by one page key, which is cosmetic — whereas measuring
+// the rendered strip would mean measuring the very thing this decision
+// removes, i.e. a feedback loop.
+const PAGE_KEY_REM = 2.5;
+const ITEM_GAP_REM = 0.25;
+const ELLIPSIS_REM = 1;
+const PREV_NEXT_REM = 10;
+
+/** px per rem, so a consumer scaling the root font size is tracked. */
+function rootFontSizePx(): number {
+  // Only ever reached in a browser (see `isCompact`), but stay SSR-safe.
+  if (typeof document === "undefined") return 16;
+  const size = Number.parseFloat(
+    getComputedStyle(document.documentElement).fontSize,
+  );
+  return Number.isFinite(size) && size > 0 ? size : 16;
+}
+
+/** Width the row needs to lay the full windowed pager out on ONE line. */
+const fullPagerWidth = computed(() => {
+  const remPx = rootFontSizePx();
+  let widthRem = PREV_NEXT_REM;
+  for (const item of pageItems.value) {
+    widthRem +=
+      (item.type === "page" ? PAGE_KEY_REM : ELLIPSIS_REM) + ITEM_GAP_REM;
+  }
+  return widthRem * remPx;
+});
+
+const { containerRef, hasMeasured, isBelow } = useContainerWidth({
+  // Compact means "narrower than the breakpoint AND too narrow for the full
+  // pager", which is exactly `width < min(threshold, needed)` — expressing it
+  // as one threshold rather than two conditions keeps the hysteresis below
+  // applied to the WHOLE decision instead of just half of it. A getter, so
+  // both a reactive `compactThreshold` and a changing page count re-evaluate
+  // instead of latching the mount-time value.
+  threshold: () => Math.min(props.compactThreshold, fullPagerWidth.value),
+  // The compact row is SHORTER than the wrapped full pager, so an ancestor with
+  // `overflow:auto` can lose its vertical scrollbar when we collapse, widening
+  // this row by ~15-17px, back over the threshold, and it flips forever. A band
+  // wider than any scrollbar makes the crossing one-way.
+  hysteresis: 24,
+});
+
+/**
+ * Gated on `hasMeasured` so an UNMEASURED render (the first frame, and every
+ * SSR render, where there is no `ResizeObserver`) is byte-identical to the
+ * pre-#162 full pager. `initialWidth` defaults to 0, i.e. "assume narrowest",
+ * which would otherwise make every desktop render start compact and flip.
+ */
+const isCompact = computed(() => hasMeasured.value && isBelow.value);
+
+/** Empty in compact mode — the status replaces the whole number window. */
+const visiblePageItems = computed<PageItem[]>(() =>
+  isCompact.value ? [] : pageItems.value,
+);
+
 const canPrev = computed(() => currentPage.value > 1);
 const canNext = computed(() => currentPage.value < lastPage.value);
 
@@ -192,9 +316,25 @@ const goToPage = (page: number) => {
 </script>
 
 <style scoped>
+/*
+  In `DXTable`'s card mode the card is rendered `no-body` so the table can sit
+  flush against the card border, which makes this footer a direct child of
+  `.card` — it no longer inherits any `.card-body` padding. Re-instate the inset
+  the card body used to give it, so the pager lines up with the padded card
+  header above it and keeps a bottom margin inside the (clipped) card.
+
+  Top padding is deliberately 0: the `mt-3` on the root already separates the
+  footer from the table above. `.dx-table-card` is DXTableShell's element and
+  needs no scope id — a scoped selector only stamps its LAST compound selector,
+  which here is this component's own root.
+*/
+.dx-table-card > .dx-table-pagination {
+    padding: 0 var(--bs-card-spacer-x) var(--bs-card-spacer-y);
+}
+
 /* Windowed pager (#155). The buttons are DButtons; give the numbered ones a
-   consistent min-width so they read as an even row of keys (like the house
-   custard pager), and let the whole row wrap on narrow widths rather than
+   consistent min-width so they read as an even row of keys (the house pager
+   style), and let the whole row wrap on narrow widths rather than
    overflow. `:deep(.btn)` is anchored on the plain `.dx-pager` host, so the
    scope-id has a deterministic element to attach to. */
 .dx-pager :deep(.btn) {
@@ -207,6 +347,23 @@ const goToPage = (page: number) => {
     min-width: auto;
 }
 
+/* Compact pager status (#162): "11 / 45" standing in for the number window.
+   A plain element this component owns, so it needs no `:deep()`. It is not a
+   button — deliberately, since there is nothing to click — so it is styled to
+   read as a label rather than a disabled key. */
+.dx-pager--compact .dx-pager-status {
+    padding: 0 0.35rem;
+    color: var(--bs-secondary-color);
+    white-space: nowrap;
+    user-select: none;
+}
+
+/* Nothing can wrap in compact mode — the row is three items wide by design, and
+   a wrap here would defeat the whole point of collapsing it. */
+.dx-pager--compact {
+    flex-wrap: nowrap;
+}
+
 .dx-pager-ellipsis {
     display: inline-flex;
     align-items: flex-end;

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

@@ -9,9 +9,27 @@
   - `#header` — the title / action row. In card mode it fills `DCard`'s header;
     in plain mode it renders above the table with a subtle bottom rule.
   - default — the table body (spinner/error/table/pagination).
+
+  Card mode renders `DCard` in **`no-body`** mode so the table sits FLUSH against
+  the card border. With a `.card-body` in between, a striped table's rows were
+  inset by `--bs-card-spacer-x` (24px) and left a white gutter between the
+  stripes and the border. Without it, DXTable's children — error alert, loading
+  block, table, pagination — become direct children of `.card`, which is already
+  a `flex-direction: column` container, so they still stack in order:
+
+      .card
+      ├─ .card-header          (padded by Bootstrap's card-cap padding)
+      ├─ .table-responsive     ← FLUSH, rounded when it is at a card corner
+      │   └─ table
+      └─ .dx-table-pagination  (pads itself — see DXTablePagination.vue)
+
+  Bootstrap 5 has no `.card > .table` rounding rules (that was BS4), so the
+  flush table's square corners have to be rounded here. The rounding is applied
+  to the TABLE REGION, never to the card: clipping the whole card would cut off
+  any non-teleported positioned content a consumer puts in a slot (#166).
 -->
 <template>
-  <DCard v-if="card">
+  <DCard v-if="card" no-body class="dx-table-card">
     <template v-if="$slots.header" #header>
       <slot name="header" />
     </template>
@@ -52,3 +70,89 @@ withDefaults(defineProps<Props>(), {
   border-bottom: 1px solid var(--bs-border-color);
 }
 </style>
+
+<style>
+/*
+  GLOBAL, not scoped, on purpose: these rules target slot content supplied by
+  `DXTable`, which is compiled in *DXTable's* scope. A scoped selector here would
+  get this component's `data-v-*` appended to its last compound selector and so
+  would match nothing — the same silent-inertness trap documented in CLAUDE.md.
+  Every selector is namespaced under `.dx-table-card`, a class only this
+  component applies, so nothing leaks into a consumer's own cards.
+*/
+
+/*
+  Round the flush table region so its square corners follow the card border.
+
+  This used to be `overflow: hidden` on the WHOLE card, which clipped every
+  non-teleported positioned descendant — including a consumer's own
+  `position: absolute` popover in a `#header` or `cell(<key>)` slot (#166).
+  The clip now sits on the table region itself, and only on the corners the
+  region actually occupies: `.card-header` and `.dx-table-pagination` round the
+  corners themselves when they are present, so the radius is applied via
+  `:first-child` / `:last-child` rather than unconditionally. Vue renders a
+  false `v-if` as a comment node, which `:first-child` ignores, so the error
+  alert and spinner branches don't disturb the match.
+
+  These rules stay in this global block with the rest of the card-mode layout: a
+  scoped rule WOULD reach DCard's root (the renderer walks the component-root
+  chain), but that forwarding is the exact thing CLAUDE.md records as unreliable
+  across build pipelines, and a silently-unclipped card is invisible in review.
+  The lower specificity also leaves consumers free to override it.
+*/
+.dx-table-card > .table-responsive:first-child,
+.dx-table-card > .table:first-child {
+  border-top-left-radius: var(--bs-card-inner-border-radius);
+  border-top-right-radius: var(--bs-card-inner-border-radius);
+}
+
+.dx-table-card > .table-responsive:last-child,
+.dx-table-card > .table:last-child {
+  border-bottom-left-radius: var(--bs-card-inner-border-radius);
+  border-bottom-right-radius: var(--bs-card-inner-border-radius);
+}
+
+/*
+  `.table-responsive` needs NO `overflow` of its own: Bootstrap already gives it
+  `overflow-x: auto`, which computes `overflow-y` to `auto` as well, so it is
+  already a clipping context and the radius above rounds that clip. Measured in
+  a real browser (see DXTable-CardFlush.test.ts): without the radius a hit-test
+  3px inside the card's corner lands on a `<th>`; with it, on the card.
+  Do NOT add `overflow: hidden` here — it would kill the horizontal scrolling
+  that makes a wide table usable, and the flush look would survive to hide it.
+
+  A bare `<table>` (`:responsive="false"`) is a different story: it is not a
+  clipping context, and `border-radius` on it leaves the collapsed-border cell
+  backgrounds square (measured — the corner still hit-tests to a `<th>`). That
+  one needs an explicit clip, scoped to the flush table so it is the table
+  region and not the card that clips. Note this restores the pre-0.35 behaviour
+  where a `:responsive="false"` table too wide for its card overflows visibly
+  rather than being silently cut off — that mode opts out of a scroll container
+  by definition.
+*/
+.dx-table-card > .table:first-child,
+.dx-table-card > .table:last-child {
+  overflow: hidden;
+}
+
+/*
+  The error alert is a full-width child of the card now that there is no
+  `.card-body`. Give it back the inset the card body used to provide, so it
+  doesn't bleed into the card's rounded corners.
+*/
+.dx-table-card > .alert {
+  margin: var(--bs-card-spacer-y) var(--bs-card-spacer-x);
+}
+
+/*
+  Nothing may leave a trailing margin at the bottom of the card. bvn already
+  zeroes `.table-responsive > .table`, but the responsive wrapper itself carries
+  `margin-bottom: 1rem` (and an un-responsive `.table` carries Bootstrap's own),
+  which used to be absorbed by the card body and now shows as a white band
+  inside the clipped card whenever the table is the last child (no pager). The
+  gap ABOVE the pager is unaffected — that margin only drops on the last child.
+*/
+.dx-table-card > :last-child {
+  margin-bottom: 0;
+}
+</style>

package/resources/js/composables/useContainerWidth.ts

@@ -0,0 +1,303 @@
+/**
+ * useContainerWidth — container-query-style responsiveness for Vue components.
+ *
+ * Bootstrap's breakpoints are **media** queries: they only ever see the WINDOW.
+ * A dashboard page is narrowed by the persistent sidebar (and a form inside a
+ * modal is narrower still), so a component can have very little room while the
+ * viewport is wide — and no media query ever fires. This composable closes that
+ * gap by observing an element's **own rendered width** with a `ResizeObserver`
+ * and exposing it reactively, so the template can pick a layout from the space
+ * it actually has.
+ *
+ * ```ts
+ * const { containerRef, width, isBelow, isNarrowerThan } = useContainerWidth({
+ *   threshold: 640,
+ * });
+ * // <div ref="containerRef"> … </div>
+ * ```
+ *
+ * One observer can drive several independent decisions — `isBelow` uses the
+ * configured `threshold`, and `isNarrowerThan(n)` answers for any other width:
+ *
+ * ```ts
+ * const stacked = computed(() => isNarrowerThan(576));
+ * const hideDetailColumn = computed(() => isNarrowerThan(900));
+ * ```
+ */
+import {
+    getCurrentScope,
+    onScopeDispose,
+    ref,
+    watch,
+    type Ref,
+} from "vue";
+
+/**
+ * What to observe: a template ref, or a getter (so the element can be resolved
+ * lazily / conditionally — e.g. `() => enabled ? el.value : null` to observe
+ * nothing at all).
+ */
+export type ContainerWidthTarget =
+    | Ref<HTMLElement | null | undefined>
+    | (() => HTMLElement | null | undefined);
+
+export interface UseContainerWidthOptions {
+    /**
+     * Width (px) that `isBelow` compares against. Omit if you only need
+     * `width` / `isNarrowerThan`. Pass a getter (`() => props.threshold`) when
+     * it can change at runtime — `isBelow` re-evaluates when it does.
+     */
+    threshold?: number | (() => number | undefined);
+
+    /**
+     * Hysteresis band (px) applied to `isBelow` only, to stop a layout flipping
+     * back and forth at the boundary. Once `isBelow` is true it stays true
+     * until the width reaches `threshold + hysteresis`.
+     *
+     * Defaults to `0` so `isBelow` means exactly `width < threshold` unless you
+     * ask for otherwise. Opt in whenever the layout you drive from it can
+     * change the observed width — the classic loop is: narrow layout is taller
+     * → an ancestor with `overflow:auto` gains a vertical scrollbar → the
+     * container loses ~15-17px → it crosses back over the threshold → repeat.
+     * A band wider than a scrollbar (24px is comfortable) breaks that cycle.
+     * (`isNarrowerThan` is deliberately raw — it holds no per-width state.)
+     */
+    hysteresis?: number;
+
+    /**
+     * Width assumed before the first measurement, and permanently where there
+     * is no `ResizeObserver` (SSR, or a very old browser).
+     *
+     * Defaults to `0` — i.e. "assume the narrowest until proven otherwise", so
+     * an unmeasured render picks the STACKED layout. That is the mobile-first
+     * choice and the safe one: a stacked layout is legible at every width,
+     * whereas a wide layout guessed wrongly truncates content. It also means
+     * the server-rendered markup matches the first client render.
+     */
+    initialWidth?: number;
+
+    /**
+     * Which box to report. `content-box` (default) is the space actually
+     * available to children — what a layout decision usually wants.
+     * `border-box` matches `getBoundingClientRect().width`.
+     */
+    box?: "content-box" | "border-box";
+
+    /**
+     * Extra debounce (ms) before publishing a new width. Defaults to `0`:
+     * `ResizeObserver` already batches to one delivery per frame, and the
+     * callback reads the size the observer *hands* it (no forced layout), so
+     * there is nothing to thrash. Set it only for genuinely expensive
+     * downstream work — a timer adds a frame of visible lag.
+     */
+    debounce?: number;
+}
+
+export interface UseContainerWidthReturn {
+    /** Bind to the element you want measured (`<div ref="containerRef">`). */
+    containerRef: Ref<HTMLElement | null>;
+    /** The observed width in px. `initialWidth` until first measured. */
+    width: Readonly<Ref<number>>;
+    /** False until a real measurement has landed (always false without a `ResizeObserver`). */
+    hasMeasured: Readonly<Ref<boolean>>;
+    /** `width < threshold`, with `hysteresis` applied. False when no `threshold` was given. */
+    isBelow: Readonly<Ref<boolean>>;
+    /** Raw `width < px`, for driving other decisions off the same observer. */
+    isNarrowerThan: (px: number) => boolean;
+    /** Disconnect early. Called automatically when the owning scope is disposed. */
+    stop: () => void;
+}
+
+export function useContainerWidth(
+    options?: UseContainerWidthOptions,
+): UseContainerWidthReturn;
+export function useContainerWidth(
+    target: ContainerWidthTarget,
+    options?: UseContainerWidthOptions,
+): UseContainerWidthReturn;
+export function useContainerWidth(
+    targetOrOptions?: ContainerWidthTarget | UseContainerWidthOptions,
+    maybeOptions?: UseContainerWidthOptions,
+): UseContainerWidthReturn {
+    // Disambiguate the two overloads: a ref (has `.value`) or a function is a
+    // target; anything else is the options object.
+    const targetGiven =
+        typeof targetOrOptions === "function" ||
+        (targetOrOptions !== null &&
+            targetOrOptions !== undefined &&
+            typeof targetOrOptions === "object" &&
+            "value" in targetOrOptions);
+
+    const target = targetGiven
+        ? (targetOrOptions as ContainerWidthTarget)
+        : undefined;
+    const options =
+        (targetGiven
+            ? maybeOptions
+            : (targetOrOptions as UseContainerWidthOptions | undefined)) ?? {};
+
+    const {
+        threshold,
+        hysteresis = 0,
+        initialWidth = 0,
+        box = "content-box",
+        debounce = 0,
+    } = options;
+
+    /** Returned for the common `<div ref="containerRef">` case. */
+    const containerRef = ref<HTMLElement | null>(null);
+
+    const resolveTarget = (): HTMLElement | null => {
+        if (target === undefined) return containerRef.value;
+        if (typeof target === "function") return target() ?? null;
+        return target.value ?? null;
+    };
+
+    const startWidth = Math.round(initialWidth);
+    const width = ref<number>(startWidth);
+    const hasMeasured = ref<boolean>(false);
+
+    let observer: ResizeObserver | null = null;
+    let observedElement: HTMLElement | null = null;
+    let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+
+    function publish(nextWidth: number): void {
+        // Sub-pixel churn (a 0.3px reflow) must not wake every dependent
+        // computed, so publish at whole-pixel resolution and skip no-ops.
+        const rounded = Math.round(nextWidth);
+        if (!hasMeasured.value) hasMeasured.value = true;
+        if (rounded !== width.value) width.value = rounded;
+    }
+
+    function schedule(nextWidth: number): void {
+        if (debounce <= 0) {
+            publish(nextWidth);
+            return;
+        }
+        if (debounceTimer !== null) clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(() => {
+            debounceTimer = null;
+            publish(nextWidth);
+        }, debounce);
+    }
+
+    function measure(entry: ResizeObserverEntry): number {
+        if (box === "border-box") {
+            // borderBoxSize is an array in the spec (fragmented inline boxes);
+            // some engines shipped a bare object first, hence the shape check.
+            const sizes = entry.borderBoxSize as unknown;
+            if (Array.isArray(sizes) && sizes.length > 0) {
+                return sizes[0].inlineSize;
+            }
+            if (
+                sizes !== null &&
+                sizes !== undefined &&
+                typeof sizes === "object" &&
+                "inlineSize" in (sizes as ResizeObserverSize)
+            ) {
+                return (sizes as ResizeObserverSize).inlineSize;
+            }
+            // No borderBoxSize: fall back to the element's own box.
+            return (entry.target as HTMLElement).getBoundingClientRect().width;
+        }
+        return entry.contentRect.width;
+    }
+
+    // `stop()` is final: it also tears down the watcher that re-observes when
+    // the target changes, so a later ref change cannot silently restart a
+    // stopped observer.
+    let stopTargetWatch: (() => void) | null = null;
+    let stopped = false;
+
+    function stop(): void {
+        stopped = true;
+        if (stopTargetWatch !== null) {
+            stopTargetWatch();
+            stopTargetWatch = null;
+        }
+        if (debounceTimer !== null) {
+            clearTimeout(debounceTimer);
+            debounceTimer = null;
+        }
+        if (observer !== null) {
+            observer.disconnect();
+            observer = null;
+        }
+        observedElement = null;
+    }
+
+    /**
+     * SSR guard: `ResizeObserver` (and `window`) do not exist while the docs
+     * site server-renders these components. We stay at `initialWidth`, so the
+     * markup is the stacked/narrow one — see `initialWidth` above.
+     */
+    const canObserve =
+        typeof window !== "undefined" && typeof ResizeObserver !== "undefined";
+
+    function observe(element: HTMLElement | null): void {
+        if (stopped) return;
+        if (element === observedElement) return;
+        if (!canObserve) return;
+
+        if (observer === null) {
+            observer = new ResizeObserver((entries) => {
+                // Only the last entry matters — a single element is observed and
+                // the observer coalesces to one delivery per frame.
+                const entry = entries[entries.length - 1];
+                if (entry === undefined) return;
+                schedule(measure(entry));
+            });
+        }
+
+        if (observedElement !== null) observer.unobserve(observedElement);
+        observedElement = element;
+        if (element !== null) observer.observe(element, { box });
+    }
+
+    // `post` flush so the element exists when a v-if/v-for swaps the target.
+    stopTargetWatch = watch(resolveTarget, observe, {
+        immediate: true,
+        flush: "post",
+    });
+
+    if (getCurrentScope() !== undefined) onScopeDispose(stop);
+
+    const resolveThreshold = (): number | undefined =>
+        typeof threshold === "function" ? threshold() : threshold;
+
+    // `isBelow` is a latched ref rather than a computed BECAUSE of hysteresis:
+    // the next answer depends on the current one, which a pure getter cannot
+    // express without mutating during evaluation. With `hysteresis: 0` it is
+    // exactly `width < threshold`. The watcher is `sync` so `isBelow` is never
+    // observed one tick behind `width`.
+    const initialThreshold = resolveThreshold();
+    const isBelow = ref<boolean>(
+        initialThreshold === undefined ? false : startWidth < initialThreshold,
+    );
+    watch(
+        [width, () => resolveThreshold()],
+        ([currentWidth, currentThreshold]) => {
+            if (currentThreshold === undefined) {
+                isBelow.value = false;
+                return;
+            }
+            isBelow.value = isBelow.value
+                ? currentWidth < currentThreshold + hysteresis
+                : currentWidth < currentThreshold;
+        },
+        { flush: "sync" },
+    );
+
+    function isNarrowerThan(px: number): boolean {
+        return width.value < px;
+    }
+
+    return {
+        containerRef,
+        width,
+        hasMeasured,
+        isBelow,
+        isNarrowerThan,
+        stop,
+    };
+}

package/resources/js/index.ts

@@ -110,6 +110,7 @@ export { default as DTooltip } from "./components/base/DTooltip.vue";
 export { useForm } from "./composables/useForm";
 export { defineForm } from "./composables/defineForm";
 export { useToast } from "./composables/useToast";
+export { useContainerWidth } from "./composables/useContainerWidth";
 
 // Utils
 export { api } from "./utils/api";
@@ -168,6 +169,12 @@ export type {
     DefineFormReturn,
 } from "./composables/defineForm";
 
+export type {
+    ContainerWidthTarget,
+    UseContainerWidthOptions,
+    UseContainerWidthReturn,
+} from "./composables/useContainerWidth";
+
 export type {
     ApiError,
     ApiResponse,