@omnitend/dashboard-for-laravel 0.33.1 → 0.35.0

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

@@ -47,6 +47,9 @@
             :form="form"
             :fields="fields"
             :tabs="tabs"
+            :layout="layout"
+            :label-cols="labelCols"
+            :card="card"
             :card-tabs="false"
             :context="item ?? undefined"
             :show-submit="false"
@@ -147,7 +150,7 @@
                         :disabled="form?.processing || loading"
                         @click="emit('delete')"
                     >
-                        Delete
+                        {{ deleteLabel }}
                     </DButton>
                 </div>
                 <div class="d-flex gap-2">
@@ -161,7 +164,7 @@
                         :disabled="form?.processing || loading"
                         @click="emit('save')"
                     >
-                        {{ isCreateMode ? 'Create' : 'Save Changes' }}
+                        {{ isCreateMode ? createLabel : saveLabel }}
                     </DButton>
                 </div>
             </div>
@@ -176,6 +179,7 @@ import DButton from "../base/DButton.vue";
 import DSpinner from "../base/DSpinner.vue";
 import DXForm from "./DXForm.vue";
 import type { EditTab } from "./DXTable.vue";
+import type { LabelCols } from "../../types";
 
 interface Props {
     /** Whether the modal is open (v-model:show). */
@@ -204,10 +208,43 @@ interface Props {
     pendingAction: 'save' | 'delete' | null;
     /** Delete endpoint — gates the Delete button. */
     deleteUrl?: string;
+    /**
+     * Field layout forwarded to the modal's DXForm (defaults handled upstream).
+     * Includes `"auto"`, which lets the form stack to vertical when the MODAL is
+     * narrow even though the viewport is wide — the container-query case a
+     * viewport media query cannot see.
+     */
+    layout?: 'vertical' | 'horizontal' | 'auto';
+    /** Label column width forwarded to DXForm (horizontal layout). */
+    labelCols?: LabelCols;
+    /** Wrap the modal form in a card (opt-in — off by default). */
+    card?: boolean;
+    /** Singular item noun for the default button labels (e.g. "customer"). */
+    itemName?: string;
+    /** Override the Save button label (edit mode). */
+    saveText?: string;
+    /** Override the Create button label (create mode). */
+    createText?: string;
+    /** Override the Delete button label. */
+    deleteText?: string;
 }
 
 const props = defineProps<Props>();
 
+// Title-case the singular item noun for button labels ("customer" → "Customer",
+// "sales order" → "Sales Order") — capitalize the first letter of each word.
+const capitalizedItem = computed(() => {
+    const noun = props.itemName?.trim() || 'item';
+    return noun.replace(/\b\w/g, (char) => char.toUpperCase());
+});
+
+// Buttons default to item-named copy ("Save Customer" / "Create Customer" /
+// "Delete Customer") — clearer than a generic "Save Changes" — overridable per
+// action. Falls back to "Save Item" etc. when no `itemName` is set.
+const saveLabel = computed(() => props.saveText ?? `Save ${capitalizedItem.value}`);
+const createLabel = computed(() => props.createText ?? `Create ${capitalizedItem.value}`);
+const deleteLabel = computed(() => props.deleteText ?? `Delete ${capitalizedItem.value}`);
+
 const emit = defineEmits<{
     /** v-model:show — the modal open state changed. */
     'update:show': [value: boolean];

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

@@ -135,7 +135,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;
 
@@ -192,9 +192,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) {

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 (overflow: hidden)
+      ├─ .card-header          (padded by Bootstrap's card-cap padding)
+      ├─ .table-responsive     ← FLUSH
+      │   └─ table
+      └─ .dx-table-pagination  (pads itself — see DXTablePagination.vue)
+
+  Bootstrap 5 has no `.card > .table` rounding rules (that was BS4), so the
+  clipping is done with `overflow: hidden` on the card: the flush table's square
+  top corners then follow the card's radius whether or not a header is present.
+  bvn's popups position `fixed` by default, so they are not clipped by it.
 -->
 <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,54 @@ 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.
+*/
+
+/*
+  Clip the card to its radius so the flush table's square corners follow the
+  border. Kept 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.
+
+  KNOWN LIMITATION (#166): this clips the WHOLE card, so a consumer's own
+  non-teleported `position: absolute` overlay in a slot is cut off at the card
+  edge. dfl's own components are fine — DDropdown teleports to <body>, the
+  filter menus are `fixed` — so the residual case is a hand-rolled popover.
+  The fix is to move the radius clipping onto the flush table region, which
+  `.table-responsive`'s `overflow-x: auto` complicates; see the issue.
+*/
+.dx-table-card {
+  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/defineForm.ts

@@ -1,5 +1,6 @@
 import { useForm, type UseFormReturn } from "./useForm";
-import type { FieldDefinition, FieldType } from "../types";
+import type { FieldDefinition } from "../types";
+import { resolveFieldDefault } from "../utils/formSchema";
 
 /**
  * Extended field definition that includes default value
@@ -30,35 +31,6 @@ export interface DefineFormReturn<TData extends Record<string, any>> {
     fields: FieldDefinition[];
 }
 
-/**
- * Helper to get default value for a field type
- */
-function getDefaultValueForType(type: FieldType): any {
-    switch (type) {
-        case "checkbox":
-        case "switch":
-            return false;
-        case "number":
-        case "currency":
-        case "percentage":
-            return 0;
-        case "repeater":
-        // Array-valued selections: checkbox-group previously fell through to
-        // the "" default, which is the wrong shape for an array model.
-        case "checkbox-group":
-        case "switch-list":
-            return [];
-        case "image":
-        case "file":
-            return null;
-        case "select":
-        case "radio":
-            return "";
-        default:
-            return "";
-    }
-}
-
 /**
  * Define a form with type-safe field definitions.
  * Reduces duplication by inferring initial values from field definitions.
@@ -75,22 +47,14 @@ export function defineForm<const TFields extends readonly FormFieldDefinition[]>
 ): DefineFormReturn<InferFormData<TFields>> {
     type FormData = InferFormData<TFields>;
 
-    // Extract initial data from field definitions.
-    //
-    // #125: `field.default ?? getDefaultValueForType(type)` cannot express a
-    // *null* default — a select whose "none" option is `value: null` (which is
-    // what the column stores) seeded '' (the type default), matched no option,
-    // and rendered blank. This is the same bug #122 fixed in DXTable. Decide on
-    // definedness, not nullishness, so null survives; an absent (or explicitly
-    // `undefined`) default still falls back to the type default rather than
-    // seeding `undefined`, which would drop the key from the JSON payload. This
-    // matches DXRepeater's `!== undefined` rule, so all seeding sites agree.
+    // Extract initial data from field definitions. Seeding (definedness over
+    // nullishness so a `null` default survives — #122/#125 — plus a type-aware
+    // fallback and deep-cloning) is the shared `resolveFieldDefault` rule, so
+    // every seeding site (defineForm / useResourceEditor / DXRepeater) agrees
+    // by construction (#134).
     const initialData = fieldDefinitions.reduce(
         (acc, field) => {
-            acc[field.key] =
-                field.default !== undefined
-                    ? field.default
-                    : getDefaultValueForType(field.type);
+            acc[field.key] = resolveFieldDefault(field);
             return acc;
         },
         {} as Record<string, any>,

package/resources/js/composables/useAsyncOptions.ts

@@ -0,0 +1,61 @@
+import { onMounted, ref, watch, type ComputedRef, type Ref } from "vue";
+import type { FieldDefinition, FieldOption } from "../types";
+
+/**
+ * Async option loading for a `DXField`: runs `field.optionsLoader` on mount and
+ * (when `field.reloadOptionsOnChange` is set) whenever the model changes,
+ * exposing the loaded options. A monotonic request token guards against
+ * out-of-order responses clobbering newer ones; loader failures are swallowed
+ * so the last good options (or the static `field.options` fallback) stay put.
+ *
+ * Extracted verbatim from DXField's inline logic (#135) — behaviour unchanged.
+ * `getField` is an accessor (props aren't destructurable without losing
+ * reactivity); `effectiveModel` is the model passed to the loader.
+ */
+export interface UseAsyncOptionsReturn {
+    /** Options returned by the most recent successful load, or null if none yet. */
+    loadedOptions: Ref<FieldOption[] | null>;
+    /** Trigger a load (no-op when the field has no `optionsLoader`). */
+    loadOptions: () => Promise<void>;
+}
+
+export function useAsyncOptions(
+    getField: () => FieldDefinition,
+    effectiveModel: ComputedRef<any> | Ref<any>,
+): UseAsyncOptionsReturn {
+    const loadedOptions = ref<FieldOption[] | null>(null);
+
+    // Monotonic token so out-of-order async responses can't clobber newer ones.
+    let optionsRequestToken = 0;
+
+    async function loadOptions(): Promise<void> {
+        const field = getField();
+        if (!field.optionsLoader) return;
+        const token = ++optionsRequestToken;
+        try {
+            const options = await field.optionsLoader(effectiveModel.value);
+            // Ignore a stale response superseded by a newer load.
+            if (token === optionsRequestToken) loadedOptions.value = options;
+        } catch (error) {
+            // Swallow loader failures: keep the last successfully loaded options
+            // (or the static `field.options` fallback when none have loaded yet).
+            if (token === optionsRequestToken) {
+                // eslint-disable-next-line no-console
+                console.error(
+                    `optionsLoader failed for field "${field.key}"`,
+                    error,
+                );
+            }
+        }
+    }
+
+    onMounted(() => {
+        void loadOptions();
+    });
+
+    if (getField().reloadOptionsOnChange) {
+        watch(effectiveModel, () => void loadOptions(), { deep: true });
+    }
+
+    return { loadedOptions, loadOptions };
+}

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,
+    };
+}