srcdev-nuxt-components 9.4.11 → 9.5.0

package/app/components/05.forms/triple-toggle-switch/TripleToggleSwitch.vue

@@ -0,0 +1,243 @@
+<template>
+  <div class="triple-toggle-switch" :class="[elementClasses]" :data-theme="theme">
+    <div class="triple-toggle-switch-wrapper">
+      <div class="selected-option-marker-wrapper">
+        <div class="selected-option-marker" :class="[{ show: showMarker }]"></div>
+      </div>
+      <div class="option-group-wrapper" role="radiogroup" :aria-label="ariaLabel || undefined">
+        <label
+          v-for="option in fieldData.data"
+          :key="option.id"
+          ref="optionGroup"
+          :for="option.id"
+          class="option-group"
+        >
+          <span class="sr-only">{{ option.label }}</span>
+          <Icon
+            v-if="option.icon"
+            :name="option.icon"
+            class="option-icon"
+            :class="[option.id, { active: modelValue === option.value }]"
+          />
+          <input
+            :id="option.id"
+            v-model="modelValue"
+            type="radio"
+            :name="name"
+            class="option-input"
+            :value="option.value"
+          />
+        </label>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import type { FormUiTheme, IFormMultipleOptions } from "~/types/forms/types.forms";
+
+interface Props {
+  name?: string;
+  ariaLabel?: string;
+  theme?: FormUiTheme;
+  stepAnimationDuration?: string;
+  styleClassPassthrough?: string | string[];
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  name: "triple-toggle-switch",
+  ariaLabel: "",
+  theme: "default",
+  stepAnimationDuration: "250ms",
+  styleClassPassthrough: () => [],
+});
+
+const modelValue = defineModel<string | number | boolean>({ required: true });
+const fieldData = defineModel<IFormMultipleOptions>("fieldData", { required: true });
+
+const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+const { stepAnimationDuration } = toRefs(props);
+
+const optionGroupRefs = useTemplateRef<HTMLLabelElement[]>("optionGroup");
+
+const iconWidth = ref("0px");
+const showMarker = ref(false);
+
+const selectedOptionIndex = computed(() => {
+  if (!fieldData.value?.data) return 0;
+  const index = fieldData.value.data.findIndex((option) => option.value === modelValue.value);
+  return Math.max(0, index);
+});
+
+const setupDefaults = async () => {
+  await nextTick();
+
+  const firstOption = optionGroupRefs.value?.[0];
+  if (firstOption) {
+    iconWidth.value = `${firstOption.getBoundingClientRect().width}px`;
+  }
+
+  await new Promise((resolve) => {
+    requestAnimationFrame(() => {
+      setTimeout(resolve, 250);
+    });
+  });
+
+  showMarker.value = true;
+};
+
+onMounted(() => {
+  setupDefaults();
+});
+</script>
+
+<style lang="css">
+@layer components {
+  .triple-toggle-switch {
+    --_form-items-gap: var(--triple-toggle-switch-gap, 1rem);
+    --_select-scheme-group-background-color: var(--triple-toggle-switch-marker-surface, var(--theme-input-surface));
+    --_select-scheme-group-background-image: none;
+    --_scheme-icon-font-size: var(--triple-toggle-switch-icon-size, 2rem);
+
+    &:has(input[value="system"]:checked) {
+      --_select-scheme-group-background-color: transparent;
+      --_select-scheme-group-background-image: var(
+        --triple-toggle-switch-marker-gradient-system,
+        radial-gradient(circle, rgb(66, 180, 58) 0%, rgb(17, 199, 0) 27%, rgb(8, 117, 3) 100%)
+      );
+    }
+
+    &:has(input[value="light"]:checked) {
+      --_select-scheme-group-background-color: transparent;
+      --_select-scheme-group-background-image: var(
+        --triple-toggle-switch-marker-gradient-light,
+        radial-gradient(circle, rgba(180, 58, 91, 1) 0%, rgba(253, 29, 29, 1) 27%, rgba(252, 176, 69, 1) 100%)
+      );
+    }
+
+    &:has(input[value="dark"]:checked) {
+      --_select-scheme-group-background-color: transparent;
+      --_select-scheme-group-background-image: var(
+        --triple-toggle-switch-marker-gradient-dark,
+        radial-gradient(circle, rgb(50, 20, 25) 0%, rgb(0, 0, 0) 27%, rgb(100, 100, 100) 100%)
+      );
+    }
+
+    .triple-toggle-switch-wrapper {
+      display: inline-grid;
+      grid-template-areas: "select-stack";
+      width: fit-content;
+
+      background-color: var(--triple-toggle-switch-surface, var(--theme-input-surface));
+      border: var(--form-element-border-width) solid var(--triple-toggle-switch-border, var(--theme-border));
+      outline: var(--form-element-outline-width) solid transparent;
+      border-radius: 100vw;
+      padding: var(--triple-toggle-switch-padding, 0.6rem);
+
+      transition: all var(--theme-form-transition-duration) ease-in-out;
+
+      &:has(input:focus-visible) {
+        outline: var(--form-element-outline-width) solid var(--triple-toggle-switch-ring-focus, var(--theme-ring));
+        outline-offset: 0.2rem;
+      }
+
+      .selected-option-marker-wrapper {
+        grid-area: select-stack;
+        z-index: 1;
+        display: flex;
+        align-items: center;
+        position: relative;
+
+        .selected-option-marker {
+          aspect-ratio: 1;
+          width: v-bind(iconWidth);
+          transition: all v-bind(stepAnimationDuration) ease-in-out;
+          background-color: var(--_select-scheme-group-background-color);
+          background-image: var(--_select-scheme-group-background-image);
+          border: var(--form-element-border-width) solid var(--triple-toggle-switch-marker-border, var(--slate-10));
+          border-radius: 50%;
+
+          position: absolute;
+          left: calc(
+            v-bind(selectedOptionIndex) * v-bind(iconWidth) + (var(--_form-items-gap) * v-bind(selectedOptionIndex))
+          );
+
+          opacity: 0;
+
+          &.show {
+            opacity: 1;
+          }
+
+          @media (prefers-reduced-motion: reduce) {
+            transition: none;
+          }
+        }
+      }
+
+      .option-group-wrapper {
+        display: grid;
+        grid-area: select-stack;
+        grid-template-columns: repeat(3, 1fr);
+        align-items: center;
+        width: fit-content;
+        z-index: 2;
+        gap: var(--_form-items-gap);
+        position: relative;
+
+        .option-group {
+          aspect-ratio: 1;
+          display: grid;
+          grid-template-areas: "icon-stack";
+          place-content: center;
+          background: transparent;
+          border: var(--form-element-border-width) solid var(--triple-toggle-switch-option-border, #00000025);
+          outline: var(--form-element-outline-width) solid transparent;
+          border-radius: 50%;
+          padding: var(--triple-toggle-switch-option-padding, 0.5rem);
+          overflow: hidden;
+
+          transition: all calc(var(--theme-form-transition-duration) / 3);
+
+          &:has(.option-icon:hover) {
+            outline: var(--form-element-outline-width) solid
+              var(--triple-toggle-switch-option-border-hover, var(--slate-10));
+          }
+
+          &:has(input:focus-visible) {
+            outline: var(--form-element-outline-width) solid
+              var(--triple-toggle-switch-option-ring-focus, var(--theme-ring));
+            outline-offset: 0.2rem;
+          }
+
+          .option-icon {
+            grid-area: icon-stack;
+            display: block;
+            font-size: var(--_scheme-icon-font-size);
+            color: var(--triple-toggle-switch-option-icon-color, var(--slate-10));
+
+            &.active {
+              color: var(--triple-toggle-switch-option-icon-color-active, var(--slate-00));
+            }
+
+            &:hover {
+              cursor: pointer;
+            }
+          }
+
+          .option-input {
+            grid-area: icon-stack;
+            opacity: 0;
+            aspect-ratio: 1;
+            width: var(--_scheme-icon-font-size);
+
+            &:hover {
+              cursor: pointer;
+            }
+          }
+        }
+      }
+    }
+  }
+}
+</style>

package/app/components/05.forms/triple-toggle-switch/stories/TripleToggleSwitch.stories.ts

@@ -0,0 +1,104 @@
+import type { Meta, StoryFn } from "@nuxtjs/storybook";
+import { ref } from "vue";
+import StorybookComponent from "../TripleToggleSwitch.vue";
+import type { IFormMultipleOptions } from "~/types/forms/types.forms.d";
+
+interface TripleToggleSwitchStoryArgs {
+  name: string;
+  ariaLabel: string;
+  stepAnimationDuration: string;
+}
+
+// TripleToggleSwitch keys its marker gradients off three option *values*: "system", "light",
+// "dark" (see CONSUMER-STYLING.md). This story uses exactly those values so each gradient fires;
+// any other value falls back to --triple-toggle-switch-marker-surface. DisplayThemeSwitch is the
+// real-world consumer and adds the useSettingsStore wiring on top.
+export default {
+  title: "Components/Forms/Triple Toggle Switch/TripleToggleSwitch",
+  component: StorybookComponent,
+  argTypes: {
+    name: { control: "text", table: { category: "Basic" } },
+    ariaLabel: {
+      control: "text",
+      description: "Accessible name for the radiogroup",
+      table: { category: "Accessibility" },
+    },
+    stepAnimationDuration: {
+      control: "text",
+      description: "CSS transition duration for the marker sliding between options",
+      table: { category: "Styling" },
+    },
+  },
+  args: {
+    name: "colour-scheme",
+    ariaLabel: "Colour scheme",
+    stepAnimationDuration: "250ms",
+  },
+} as Meta<TripleToggleSwitchStoryArgs>;
+
+const buildOptions = (): IFormMultipleOptions => ({
+  data: [
+    { id: "system", name: "colour-scheme", value: "system", label: "System", icon: "material-symbols:night-sight-auto-sharp" },
+    { id: "light", name: "colour-scheme", value: "light", label: "Light", icon: "radix-icons:sun" },
+    { id: "dark", name: "colour-scheme", value: "dark", label: "Dark", icon: "radix-icons:moon" },
+  ],
+  total: 3,
+  skip: 0,
+  limit: 3,
+});
+
+const Template: StoryFn<TripleToggleSwitchStoryArgs> = (args) => ({
+  components: { StorybookComponent },
+  setup() {
+    const modelValue = ref("system");
+    const fieldData = ref<IFormMultipleOptions>(buildOptions());
+    return { args, modelValue, fieldData };
+  },
+  template: `
+    <div style="margin: 36px;">
+      <StorybookComponent
+        v-model="modelValue"
+        v-model:field-data="fieldData"
+        :name="args.name"
+        :aria-label="args.ariaLabel"
+        :step-animation-duration="args.stepAnimationDuration"
+      />
+      <div style="margin-top: 1.6rem; font-size: 1.4rem;">Current value: {{ modelValue }}</div>
+    </div>
+  `,
+});
+
+export const Default = Template.bind({});
+
+const CustomTokensTemplate: StoryFn<TripleToggleSwitchStoryArgs> = (args) => ({
+  components: { StorybookComponent },
+  setup() {
+    const modelValue = ref("light");
+    const fieldData = ref<IFormMultipleOptions>(buildOptions());
+    return { args, modelValue, fieldData };
+  },
+  template: `
+    <div
+      style="
+        margin: 36px;
+        --triple-toggle-switch-gap: 0.4rem;
+        --triple-toggle-switch-padding: 0.4rem;
+        --triple-toggle-switch-icon-size: 1.6rem;
+        --triple-toggle-switch-marker-gradient-system: linear-gradient(135deg, #0ea5e9, #6366f1);
+        --triple-toggle-switch-marker-gradient-light: linear-gradient(135deg, #facc15, #f97316);
+        --triple-toggle-switch-marker-gradient-dark: linear-gradient(135deg, #1e293b, #475569);
+      "
+    >
+      <StorybookComponent
+        v-model="modelValue"
+        v-model:field-data="fieldData"
+        :name="args.name"
+        :aria-label="args.ariaLabel"
+        :step-animation-duration="args.stepAnimationDuration"
+      />
+      <div style="margin-top: 1.6rem; font-size: 1.4rem;">Current value: {{ modelValue }}</div>
+    </div>
+  `,
+});
+
+export const CustomTokens = CustomTokensTemplate.bind({});

package/app/components/05.forms/triple-toggle-switch/tests/TripleToggleSwitch.spec.ts

@@ -0,0 +1,138 @@
+import { describe, it, expect, vi } from "vitest";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import { nextTick } from "vue";
+import TripleToggleSwitch from "../TripleToggleSwitch.vue";
+import type { IFormMultipleOptions } from "~/types/forms/types.forms";
+
+const buildOptions = (): IFormMultipleOptions => ({
+  data: [
+    { id: "system", name: "scheme", value: "system", label: "System", icon: "radix-icons:gear" },
+    { id: "light", name: "scheme", value: "light", label: "Light", icon: "radix-icons:sun" },
+    { id: "dark", name: "scheme", value: "dark", label: "Dark", icon: "radix-icons:moon" },
+  ],
+  total: 3,
+  skip: 0,
+  limit: 3,
+});
+
+const mountSwitch = (props: Record<string, unknown> = {}) =>
+  mountSuspended(TripleToggleSwitch, {
+    props: {
+      modelValue: "system",
+      fieldData: buildOptions(),
+      ...props,
+    },
+  });
+
+interface TripleToggleSwitchInstance {
+  selectedOptionIndex: number;
+}
+
+describe("TripleToggleSwitch", () => {
+  it("mounts without error", async () => {
+    const wrapper = await mountSwitch();
+    expect(wrapper.vm).toBeTruthy();
+    expect(wrapper.find(".triple-toggle-switch").exists()).toBe(true);
+  });
+
+  it("renders one radio per option with matching id, value and shared name", async () => {
+    const wrapper = await mountSwitch({ name: "colour-scheme" });
+    const inputs = wrapper.findAll("input.option-input");
+    expect(inputs).toHaveLength(3);
+    expect(inputs.map((i) => i.attributes("id"))).toEqual(["system", "light", "dark"]);
+    expect(inputs.map((i) => (i.element as HTMLInputElement).value)).toEqual(["system", "light", "dark"]);
+    inputs.forEach((i) => {
+      expect(i.attributes("type")).toBe("radio");
+      expect(i.attributes("name")).toBe("colour-scheme");
+    });
+  });
+
+  it("uses the default name when none is passed", async () => {
+    const wrapper = await mountSwitch();
+    expect(wrapper.find("input.option-input").attributes("name")).toBe("triple-toggle-switch");
+  });
+
+  it("links each label to its radio and renders the label text for screen readers", async () => {
+    const wrapper = await mountSwitch();
+    const labels = wrapper.findAll("label.option-group");
+    expect(labels.map((l) => l.attributes("for"))).toEqual(["system", "light", "dark"]);
+    expect(wrapper.findAll(".option-group .sr-only").map((s) => s.text())).toEqual(["System", "Light", "Dark"]);
+  });
+
+  it("exposes the options as a radiogroup", async () => {
+    const wrapper = await mountSwitch();
+    const group = wrapper.find(".option-group-wrapper");
+    expect(group.attributes("role")).toBe("radiogroup");
+    expect(group.attributes("aria-label")).toBeUndefined();
+  });
+
+  it("applies ariaLabel to the radiogroup", async () => {
+    const wrapper = await mountSwitch({ ariaLabel: "Colour scheme" });
+    expect(wrapper.find(".option-group-wrapper").attributes("aria-label")).toBe("Colour scheme");
+  });
+
+  it("checks the radio matching modelValue", async () => {
+    const wrapper = await mountSwitch({ modelValue: "light" });
+    const checked = wrapper.findAll("input.option-input").map((i) => (i.element as HTMLInputElement).checked);
+    expect(checked).toEqual([false, true, false]);
+  });
+
+  it("emits update:modelValue when another option is chosen", async () => {
+    const wrapper = await mountSwitch();
+    await wrapper.findAll("input.option-input")[2]!.setValue(true);
+    expect(wrapper.emitted("update:modelValue")?.[0]).toEqual(["dark"]);
+  });
+
+  it("marks only the selected option's icon as active", async () => {
+    const wrapper = await mountSwitch({ modelValue: "dark" });
+    const icons = wrapper.findAll(".option-icon");
+    expect(icons).toHaveLength(3);
+    expect(icons.map((i) => i.classes().includes("active"))).toEqual([false, false, true]);
+    expect(icons[0]!.classes()).toContain("system");
+  });
+
+  it("updates the active icon when modelValue changes", async () => {
+    const wrapper = await mountSwitch();
+    await wrapper.setProps({ modelValue: "light" });
+    const icons = wrapper.findAll(".option-icon");
+    expect(icons[1]!.classes()).toContain("active");
+    expect(icons[0]!.classes()).not.toContain("active");
+  });
+
+  it("omits the icon when an option has none", async () => {
+    const options = buildOptions();
+    delete options.data[1]!.icon;
+    const wrapper = await mountSwitch({ fieldData: options });
+    expect(wrapper.findAll(".option-icon")).toHaveLength(2);
+  });
+
+  it("computes the selected option index, falling back to 0 for an unknown value", async () => {
+    const wrapper = await mountSwitch({ modelValue: "dark" });
+    const vm = wrapper.vm as unknown as TripleToggleSwitchInstance;
+    expect(vm.selectedOptionIndex).toBe(2);
+    await wrapper.setProps({ modelValue: "unknown" });
+    expect(vm.selectedOptionIndex).toBe(0);
+  });
+
+  it("shows the marker only after the mount delay", async () => {
+    const wrapper = await mountSwitch();
+    const marker = wrapper.find(".selected-option-marker");
+    expect(marker.classes()).not.toContain("show");
+    vi.advanceTimersByTime(300);
+    await nextTick();
+    await nextTick();
+    expect(wrapper.find(".selected-option-marker").classes()).toContain("show");
+  });
+
+  it("applies the theme as data-theme", async () => {
+    const wrapper = await mountSwitch({ theme: "success" });
+    expect(wrapper.find(".triple-toggle-switch").attributes("data-theme")).toBe("success");
+  });
+
+  it("applies styleClassPassthrough classes to the root", async () => {
+    const wrapper = await mountSwitch({ styleClassPassthrough: ["small", "extra"] });
+    const root = wrapper.find(".triple-toggle-switch");
+    expect(root.classes()).toContain("small");
+    expect(root.classes()).toContain("extra");
+  });
+});

package/app/composables/tests/useCancellableTimer.spec.ts

@@ -132,4 +132,52 @@ describe("useCancellableTimer", () => {
       expect(secondResolved).toBe(true);
     });
   });
+  describe("pause / resume", () => {
+    it("holds a pending wait while paused and resolves after resume", async () => {
+      const { wait, start, pause, resume } = useCancellableTimer();
+      start();
+
+      let resolved = false;
+      wait(100).then(() => {
+        resolved = true;
+      });
+      pause();
+      await vi.advanceTimersByTimeAsync(500);
+      expect(resolved).toBe(false);
+
+      resume();
+      await vi.advanceTimersByTimeAsync(100);
+      expect(resolved).toBe(true);
+    });
+
+    it("holds a scheduled callback while paused", async () => {
+      const { schedule, start, pause, resume } = useCancellableTimer();
+      start();
+
+      const fn = vi.fn();
+      schedule(fn, 100);
+      pause();
+      await vi.advanceTimersByTimeAsync(500);
+      expect(fn).not.toHaveBeenCalled();
+
+      resume();
+      await vi.advanceTimersByTimeAsync(100);
+      expect(fn).toHaveBeenCalledOnce();
+    });
+
+    it("stop still rejects a wait held by pause", async () => {
+      const { wait, start, stop, pause } = useCancellableTimer();
+      start();
+
+      let rejected = false;
+      wait(100).catch(() => {
+        rejected = true;
+      });
+      pause();
+      await vi.advanceTimersByTimeAsync(300);
+      stop();
+      await Promise.resolve();
+      expect(rejected).toBe(true);
+    });
+  });
 });

package/app/composables/tests/useMaxChildWidth.spec.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import { defineComponent, h } from "vue";
+import { useMaxChildWidth } from "../useMaxChildWidth";
+
+const widths: Record<string, number> = { short: 40, long: 120, other: 300 };
+
+const offsetWidthSpy = vi
+  .spyOn(HTMLElement.prototype, "offsetWidth", "get")
+  .mockImplementation(function (this: HTMLElement) {
+    return widths[this.dataset.size ?? ""] ?? 0;
+  });
+
+afterEach(() => {
+  offsetWidthSpy.mockClear();
+});
+
+const mountWith = (refKey?: string, items = ["short", "long"]) =>
+  mountSuspended(
+    defineComponent({
+      setup() {
+        const { maxChildWidth, updateMaxChildWidth } = refKey
+          ? useMaxChildWidth(".item", "100px", refKey)
+          : useMaxChildWidth(".item", "100px");
+        return { maxChildWidth, updateMaxChildWidth };
+      },
+      render() {
+        return h("div", [
+          h(
+            "div",
+            { ref: refKey ?? "itemsContainer" },
+            items.map((size) => h("span", { class: "item", "data-size": size }))
+          ),
+          h("span", { class: "item", "data-size": "other" }),
+        ]);
+      },
+    })
+  );
+
+describe("useMaxChildWidth", () => {
+  it("starts at the fallback", async () => {
+    const wrapper = await mountWith();
+
+    expect(wrapper.vm.maxChildWidth).toBe("100px");
+  });
+
+  it("measures the widest match inside the itemsContainer template ref", async () => {
+    const wrapper = await mountWith();
+    wrapper.vm.updateMaxChildWidth();
+
+    expect(wrapper.vm.maxChildWidth).toBe("120px");
+  });
+
+  it("uses a custom template ref name", async () => {
+    const wrapper = await mountWith("optionsList");
+    wrapper.vm.updateMaxChildWidth();
+
+    expect(wrapper.vm.maxChildWidth).toBe("120px");
+  });
+
+  it("falls back when nothing matches", async () => {
+    const wrapper = await mountWith(undefined, []);
+    wrapper.vm.updateMaxChildWidth();
+
+    expect(wrapper.vm.maxChildWidth).toBe("100px");
+  });
+});

package/app/composables/useCancellableTimer.ts

@@ -1,8 +1,23 @@
+const PAUSE_POLL_MS = 100;
+
 export function useCancellableTimer() {
   let _isActive = false;
+  let _isPaused = false;
   let timeoutId: ReturnType<typeof setTimeout> | null = null;
   let rejectCurrent: (() => void) | null = null;
 
+  // While paused, a due timer re-arms itself instead of firing, so the sequence resumes where it stopped.
+  const arm = (fn: () => void, ms: number) => {
+    timeoutId = setTimeout(() => {
+      if (!_isActive) return;
+      if (_isPaused) {
+        arm(fn, PAUSE_POLL_MS);
+        return;
+      }
+      fn();
+    }, ms);
+  };
+
   const wait = (ms: number): Promise<void> =>
     new Promise((resolve, reject) => {
       if (!_isActive) {
@@ -10,18 +25,15 @@ export function useCancellableTimer() {
         return;
       }
       rejectCurrent = reject;
-      timeoutId = setTimeout(() => {
+      arm(() => {
         rejectCurrent = null;
-        if (_isActive) resolve();
-        else reject();
+        resolve();
       }, ms);
     });
 
   const schedule = (fn: () => void, ms: number) => {
     if (!_isActive) return;
-    timeoutId = setTimeout(() => {
-      if (_isActive) fn();
-    }, ms);
+    arm(fn, ms);
   };
 
   const stop = () => {
@@ -38,5 +50,13 @@ export function useCancellableTimer() {
     _isActive = true;
   };
 
-  return { wait, schedule, stop, start };
+  const pause = () => {
+    _isPaused = true;
+  };
+
+  const resume = () => {
+    _isPaused = false;
+  };
+
+  return { wait, schedule, stop, start, pause, resume };
 }

package/app/composables/useMaxChildWidth.ts

@@ -1,15 +1,14 @@
-import type { Ref } from "vue";
-
 /**
  * useMaxChildWidth composable
  * Measures the widest child element matching a selector inside a container and returns a reactive pixel width.
  * @param selector - CSS selector for child elements to measure
  * @param fallback - fallback width if no children found (default: "100px")
- * @returns { maxChildWidth, itemsContainer, updateMaxChildWidth }
+ * @param refKey - template ref name of the container element (default: "itemsContainer", i.e. `ref="itemsContainer"`)
+ * @returns { maxChildWidth, updateMaxChildWidth }
  */
-export function useMaxChildWidth(selector: string, fallback = "100px") {
+export function useMaxChildWidth(selector: string, fallback = "100px", refKey = "itemsContainer") {
   const maxChildWidth = ref<string>(fallback);
-  const itemsContainer = ref<HTMLElement | null>(null);
+  const itemsContainer = useTemplateRef<HTMLElement>(refKey);
 
   function updateMaxChildWidth() {
     if (!itemsContainer.value) return;
@@ -24,7 +23,6 @@ export function useMaxChildWidth(selector: string, fallback = "100px") {
 
   return {
     maxChildWidth,
-    itemsContainer,
     updateMaxChildWidth,
   };
 }