srcdev-nuxt-components 9.2.5 → 9.2.6

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

@@ -0,0 +1,91 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { nextTick, ref } from "vue";
+import { useContainerBreakpoints } from "../useContainerBreakpoints";
+
+let resizeCallback: ResizeObserverCallback | null = null;
+
+beforeEach(() => {
+  resizeCallback = null;
+  vi.stubGlobal(
+    "ResizeObserver",
+    vi.fn((callback: ResizeObserverCallback) => {
+      resizeCallback = callback;
+      return {
+        observe: vi.fn(),
+        unobserve: vi.fn(),
+        disconnect: vi.fn(),
+      };
+    })
+  );
+});
+
+function triggerResize(el: HTMLElement, width: number) {
+  Object.defineProperty(el, "offsetWidth", { value: width, configurable: true });
+  resizeCallback?.(
+    [{ contentRect: { width, height: 0 } } as unknown as ResizeObserverEntry],
+    {} as ResizeObserver
+  );
+}
+
+describe("useContainerBreakpoints", () => {
+  it("defaults active to base when narrower than the smallest breakpoint", () => {
+    const el = ref<HTMLElement | null>(document.createElement("div"));
+    const { active } = useContainerBreakpoints(undefined, el);
+    expect(active.value).toBe("base");
+  });
+
+  it("updates active as the observed element's width crosses breakpoints", async () => {
+    const el = ref<HTMLElement | null>(document.createElement("div"));
+    const { active } = useContainerBreakpoints(undefined, el);
+
+    triggerResize(el.value as HTMLElement, 700);
+    await nextTick();
+    expect(active.value).toBe("sm");
+
+    triggerResize(el.value as HTMLElement, 1300);
+    await nextTick();
+    expect(active.value).toBe("xl");
+  });
+
+  it("greaterOrEqual/smaller reflect the current width against a named breakpoint", async () => {
+    const el = ref<HTMLElement | null>(document.createElement("div"));
+    const { greaterOrEqual, smaller } = useContainerBreakpoints(undefined, el);
+    const isLg = greaterOrEqual("lg");
+    const isSmallerThanMd = smaller("md");
+
+    expect(isLg.value).toBe(false);
+    expect(isSmallerThanMd.value).toBe(true);
+
+    triggerResize(el.value as HTMLElement, 1100);
+    await nextTick();
+    expect(isLg.value).toBe(true);
+    expect(isSmallerThanMd.value).toBe(false);
+  });
+
+  it("between returns true only within the [min, max) range", async () => {
+    const el = ref<HTMLElement | null>(document.createElement("div"));
+    const { between } = useContainerBreakpoints(undefined, el);
+    const isTablet = between("sm", "lg");
+
+    triggerResize(el.value as HTMLElement, 800);
+    await nextTick();
+    expect(isTablet.value).toBe(true);
+
+    triggerResize(el.value as HTMLElement, 1024);
+    await nextTick();
+    expect(isTablet.value).toBe(false);
+  });
+
+  it("supports a custom breakpoints map", async () => {
+    const el = ref<HTMLElement | null>(document.createElement("div"));
+    const { active } = useContainerBreakpoints({ narrow: 400, wide: 900 }, el);
+
+    triggerResize(el.value as HTMLElement, 500);
+    await nextTick();
+    expect(active.value).toBe("narrow");
+
+    triggerResize(el.value as HTMLElement, 950);
+    await nextTick();
+    expect(active.value).toBe("wide");
+  });
+});

package/app/composables/useContainerBreakpoints.ts

@@ -0,0 +1,71 @@
+import type { Ref } from "vue";
+import { useElementSize } from "@vueuse/core";
+
+export const containerBreakpointsDefault = {
+  sm: 640,
+  md: 768,
+  lg: 1024,
+  xl: 1280,
+  "2xl": 1536,
+  "4k": 2560,
+} as const;
+
+export type ContainerBreakpointName = keyof typeof containerBreakpointsDefault;
+
+/**
+ * useContainerBreakpoints composable
+ * Container-query equivalent of VueUse's useBreakpoints — tracks an element's
+ * own width via ResizeObserver instead of the viewport, for layouts where
+ * page decoration (nav, sidebars) means viewport width != available width.
+ * @param breakpoints - map of breakpoint name to min-width in px (default: containerBreakpointsDefault)
+ * @param target - optional existing element ref to observe; creates its own if omitted
+ * @returns { el, width, active, greater, greaterOrEqual, smaller, smallerOrEqual, between }
+ */
+export function useContainerBreakpoints<K extends string = ContainerBreakpointName>(
+  breakpoints: Record<K, number> = containerBreakpointsDefault as unknown as Record<K, number>,
+  target?: Ref<HTMLElement | null>
+) {
+  const el = target ?? ref<HTMLElement | null>(null);
+  const { width } = useElementSize(el);
+
+  const sortedEntries = (Object.entries(breakpoints) as [K, number][]).sort((a, b) => a[1] - b[1]);
+
+  function greaterOrEqual(name: K) {
+    return computed(() => width.value >= breakpoints[name]);
+  }
+
+  function greater(name: K) {
+    return computed(() => width.value > breakpoints[name]);
+  }
+
+  function smaller(name: K) {
+    return computed(() => width.value < breakpoints[name]);
+  }
+
+  function smallerOrEqual(name: K) {
+    return computed(() => width.value <= breakpoints[name]);
+  }
+
+  function between(min: K, max: K) {
+    return computed(() => width.value >= breakpoints[min] && width.value < breakpoints[max]);
+  }
+
+  const active = computed<K | "base">(() => {
+    let current: K | "base" = "base";
+    for (const [name, minWidth] of sortedEntries) {
+      if (width.value >= minWidth) current = name;
+    }
+    return current;
+  });
+
+  return {
+    el,
+    width,
+    active,
+    greater,
+    greaterOrEqual,
+    smaller,
+    smallerOrEqual,
+    between,
+  };
+}

package/app/layouts/default.vue

@@ -110,6 +110,7 @@ const responsiveNavLinks = {
         { name: "Layout Grid A", path: "/ui/layout-grid-a" },
         { name: "Layout Grid B", path: "/ui/layout-grid-b" },
         { name: "Simple Grid", path: "/ui/simple-grid" },
+        { name: "Layout Content Docs", path: "/ui/layout-content-docs" },
         { name: "Masonry Grid Simple", path: "/ui/masonry-grid" },
         { name: "Masonry Grid Sorted", path: "/ui/masonry-grid-sorted" },
         { name: "Masonry Grid Ordered", path: "/ui/masonry-grid-ordered" },

package/app/pages/ui/expanding-panel.vue

@@ -2,134 +2,142 @@
   <div>
     <NuxtLayout name="default">
       <template #layout-content>
-        <PageRow tag="div" variant="full" :style-class-passthrough="['expanding-panel-section', 'mbe-20']">
-          <h1 class="page-heading-2">Details element - Unlinked</h1>
-          <p class="mbe-12">Following 2 details block behave independantly.</p>
-
-          <ExpandingPanel :animation-duration="300" icon-size="medium" :style-class-passthrough="['custom-style-1']">
-            <template #summary>
-              <h3 class="page-heading-3 mb-2">Expander Panel 1 (Fast)</h3>
-            </template>
-            <template #icon>
-              <Icon name="bi:caret-down-fill" class="icon" />
-            </template>
-            <template #content>
-              <div>
-                <p class="mt-0">Details content</p>
-                <p>Details content</p>
-                <p>Details content</p>
-                <p>Details content</p>
-                <p>Details content</p>
-              </div>
-            </template>
-          </ExpandingPanel>
-
-          <ExpandingPanel :animation-duration="2000" icon-size="medium" :style-class-passthrough="['custom-style-2']">
-            <template #summary>
-              <h3 class="page-heading-3 mb-2">Expander Panel 2 (Slow)</h3>
-            </template>
-            <template #icon>
-              <Icon name="bi:caret-down-fill" class="icon" />
-            </template>
-            <template #content>
-              <div>
-                <p class="mt-0">Details content</p>
-                <p>Details content</p>
-                <p>Details content</p>
-                <p>Details content</p>
-                <p>Details content</p>
-              </div>
-            </template>
-          </ExpandingPanel>
-        </PageRow>
+        <PageRow tag="div" variant="content" :style-class-passthrough="['expanding-panel-section', 'mb-20']">
+          <!-- ── QA Panel ─────────────────────────────────────────────── -->
+          <div class="qa-panel">
+            <details class="qa-panel__details" open>
+              <summary class="qa-panel__summary">
+                <span class="qa-panel__title">QA — ExpandingPanel</span>
+                <code class="qa-panel__status">
+                  duration:{{ qaAnimationDuration }}ms · forceOpened:{{ qaForceOpened }} · contentIsOnTop:{{
+                    qaContentIsOnTop
+                  }}
+                  · linked:{{ qaLinked }}
+                </code>
+              </summary>
+              <div class="qa-panel__body">
+                <div class="qa-panel__group">
+                  <span class="qa-panel__label">Animation Duration</span>
+                  <div class="qa-panel__chips">
+                    <button
+                      v-for="d in animationDurations"
+                      :key="d"
+                      class="qa-panel__chip"
+                      :class="{ 'is-active': qaAnimationDuration === d }"
+                      @click="qaAnimationDuration = d"
+                    >
+                      {{ d }}ms
+                    </button>
+                  </div>
+                </div>
 
-        <PageRow tag="div" variant="full" :style-class-passthrough="['expanding-panel-section', 'mbe-20', 'hidden']">
-          <h2 class="page-heading-2">Details element - Linked</h2>
-          <p class="mbe-12">Details panels are linked, only 1 can be open at a time.</p>
-
-          <ExpandingPanel
-            :animation-duration="300"
-            name="details-linked"
-            icon-size="medium"
-            :style-class-passthrough="['linked']"
-          >
-            <template #summary>
-              <h3 class="page-heading-3 mb-2">Expander Panel 1 Linked</h3>
-            </template>
-            <template #icon>
-              <Icon name="bi:caret-down-fill" class="icon" />
-            </template>
-            <template #content>
-              <div>
-                <p class="mt-0">Details content</p>
-                <p>Details content</p>
-                <p>Details content</p>
-                <p>Details content</p>
-                <p>Details content</p>
-              </div>
-            </template>
-          </ExpandingPanel>
-
-          <ExpandingPanel
-            :animation-duration="300"
-            name="details-linked"
-            icon-size="medium"
-            :style-class-passthrough="['linked']"
-          >
-            <template #summary>
-              <h3 class="page-heading-3 mb-2">Expander Panel 2 Linked</h3>
-            </template>
-            <template #icon>
-              <Icon name="bi:caret-down-fill" class="icon" />
-            </template>
-            <template #content>
-              <div>
-                <p class="mt-0">Details content</p>
-                <p>Details content</p>
-                <p>Details content</p>
-                <p>Details content</p>
-                <p>Details content</p>
+                <div class="qa-panel__group">
+                  <span class="qa-panel__label">Force Opened</span>
+                  <div class="qa-panel__chips">
+                    <button
+                      class="qa-panel__chip"
+                      :class="{ 'is-active': !qaForceOpened }"
+                      @click="qaForceOpened = false"
+                    >
+                      off
+                    </button>
+                    <button
+                      class="qa-panel__chip"
+                      :class="{ 'is-active': qaForceOpened }"
+                      @click="qaForceOpened = true"
+                    >
+                      on
+                    </button>
+                  </div>
+                </div>
+
+                <div class="qa-panel__group">
+                  <span class="qa-panel__label">Content Is On Top</span>
+                  <div class="qa-panel__chips">
+                    <button
+                      class="qa-panel__chip"
+                      :class="{ 'is-active': !qaContentIsOnTop }"
+                      @click="qaContentIsOnTop = false"
+                    >
+                      off
+                    </button>
+                    <button
+                      class="qa-panel__chip"
+                      :class="{ 'is-active': qaContentIsOnTop }"
+                      @click="qaContentIsOnTop = true"
+                    >
+                      on
+                    </button>
+                  </div>
+                </div>
+
+                <div class="qa-panel__group">
+                  <span class="qa-panel__label">Linked (shared name)</span>
+                  <div class="qa-panel__chips">
+                    <button class="qa-panel__chip" :class="{ 'is-active': !qaLinked }" @click="qaLinked = false">
+                      off
+                    </button>
+                    <button class="qa-panel__chip" :class="{ 'is-active': qaLinked }" @click="qaLinked = true">
+                      on
+                    </button>
+                  </div>
+                </div>
               </div>
-            </template>
-          </ExpandingPanel>
+            </details>
+          </div>
         </PageRow>
 
-        <PageRow tag="div" variant="full" :style-class-passthrough="['expanding-panel-section', 'mbe-20']">
-          <h1 class="page-heading-2">Details element - forceOpened</h1>
-          <p class="page-body-normal">Will be displayed as force opened via prop forceOpened</p>
-          <p class="page-body-normal">Also contains a button and link within content which toggles to closed</p>
-          <p class="mbe-12">
-            <button class="btn btn-primary" @click="forceOpened = !forceOpened">
-              Toggle forceOpened (currently: {{ forceOpened }})
-            </button>
-          </p>
-
-          <ExpandingPanel v-model="isPanelOpen" :animation-duration="300" icon-size="medium" :force-opened>
-            <template #summary>
-              <h3 class="page-heading-3 mb-2">Expander Panel Force Opened</h3>
-            </template>
-            <template #icon>
-              <Icon name="bi:caret-down-fill" class="icon" />
-            </template>
-            <template #content>
-              <div>
-                <p class="mt-0">Details content with test link and button</p>
-                <p>
-                  <button @click.prevent="closePanel()" @keydown.enter="closePanel()">
-                    Close via reactive binding
-                  </button>
-                </p>
-                <p>
-                  <a href="#forceClose" @click="closePanel()" @keydown.enter="closePanel()" class="page-link-normal">
-                    Close via ref
-                  </a>
-                </p>
-                <p>Details content</p>
-                <p>Details content</p>
-                <p>Details content</p>
-              </div>
-            </template>
-          </ExpandingPanel>
+        <PageRow tag="div" variant="content" :style-class-passthrough="['qa-panel__preview']">
+          <section class="qa-panel__preview">
+            <h2 class="page-heading-3">Interactive preview</h2>
+            <div style="position: relative">
+              <ExpandingPanel
+                v-model="qaOpen1"
+                :name="qaPanel1Name"
+                :animation-duration="qaAnimationDuration"
+                :force-opened="qaForceOpened"
+                :content-is-on-top="qaContentIsOnTop"
+                :style-class-passthrough="['qa-preview-panel']"
+              >
+                <template #summary>
+                  <h3 class="page-heading-3 mb-2">Interactive preview panel 1</h3>
+                </template>
+                <template #content>
+                  <!-- Wrapper INSIDE the slot carries visual styling — never .inner itself,
+                         see .claude/skills/components/expanding-panel.md for why -->
+                  <div class="qa-preview-panel-body">
+                    <p class="mt-0">Content driven by the controls above.</p>
+                    <p class="mb-0">
+                      Toggle "Content Is On Top" to see it overlay the text below instead of pushing it down.
+                    </p>
+                  </div>
+                </template>
+              </ExpandingPanel>
+
+              <!-- When "Linked" is on, this shares its name with panel 1 above, grouping them
+                   into a native accordion (only one open at a time). -->
+              <ExpandingPanel
+                v-model="qaOpen2"
+                :name="qaPanel2Name"
+                :animation-duration="qaAnimationDuration"
+                :force-opened="qaForceOpened"
+                :content-is-on-top="qaContentIsOnTop"
+                :style-class-passthrough="['qa-preview-panel']"
+              >
+                <template #summary>
+                  <h3 class="page-heading-3 mb-2">Interactive preview panel 2</h3>
+                </template>
+                <template #content>
+                  <div class="qa-preview-panel-body">
+                    <p class="mt-0">When "Linked" is on, opening this panel closes panel 1, and vice versa.</p>
+                    <p class="mb-0">Also driven by the controls above.</p>
+                  </div>
+                </template>
+              </ExpandingPanel>
+
+              <p class="mbs-16">Page content below the preview panel — stays in place when contentIsOnTop is on.</p>
+            </div>
+          </section>
         </PageRow>
       </template>
     </NuxtLayout>
@@ -149,14 +157,32 @@ useHead({
       content: "Meta description content",
     },
   ],
+  bodyAttrs: {
+    class: "ui-expanding-panel-page",
+  },
 });
 
-const forceOpened = ref(false);
-const isPanelOpen = ref(false);
+const animationDurations = [0, 300, 800] as const;
+type AnimationDuration = (typeof animationDurations)[number];
 
-const closePanel = () => {
-  isPanelOpen.value = false;
-};
+const qaAnimationDuration = ref<AnimationDuration>(300);
+const qaForceOpened = ref(false);
+const qaContentIsOnTop = ref(false);
+const qaLinked = ref(false);
+const qaOpen1 = ref(false);
+const qaOpen2 = ref(false);
+
+const qaPanel1Name = "qa-preview-1";
+const qaPanel2Name = computed(() => (qaLinked.value ? qaPanel1Name : "qa-preview-2"));
+
+// forceOpened only forces panels *open*; a panel's own isPanelOpen state is left untouched
+// by the component (see expanding-panel skill notes), so toggling forceOpened off can leave
+// a panel open or closed depending on hidden prior clicks. Reset both panels to a known,
+// visible state on every toggle so the QA control always produces an obvious response.
+watch(qaForceOpened, () => {
+  qaOpen1.value = false;
+  qaOpen2.value = false;
+});
 </script>
 
 <style lang="css">
@@ -186,4 +212,115 @@ const closePanel = () => {
     }
   }
 }
+
+.ui-expanding-panel-page {
+  .qa-panel {
+    background: oklch(15% 0 0);
+    color: white;
+    font-size: 1.3rem;
+    margin-block-end: 2rem;
+  }
+
+  .qa-panel__details {
+    padding: 1rem 2rem;
+  }
+
+  .qa-panel__summary {
+    cursor: pointer;
+    display: flex;
+    align-items: center;
+    gap: 1.6rem;
+    list-style: none;
+    user-select: none;
+
+    &::-webkit-details-marker {
+      display: none;
+    }
+  }
+
+  .qa-panel__title {
+    font-weight: 600;
+    font-size: 1.1rem;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+  }
+
+  .qa-panel__status {
+    font-family: monospace;
+    font-size: 1.2rem;
+    background: oklch(0% 0 0 / 0.3);
+    padding: 0.2rem 0.8rem;
+    border-radius: 0.4rem;
+    user-select: text;
+    cursor: text;
+  }
+
+  .qa-panel__body {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 2.4rem;
+    padding-block: 1.2rem 0.4rem;
+  }
+
+  .qa-panel__group {
+    display: flex;
+    flex-direction: column;
+    gap: 0.6rem;
+  }
+
+  .qa-panel__label {
+    font-size: 1.1rem;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    opacity: 0.55;
+  }
+
+  .qa-panel__chips {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.4rem;
+  }
+
+  .qa-panel__chip {
+    font-family: monospace;
+    font-size: 1.2rem;
+    color: white;
+    background: oklch(0% 0 0 / 0.25);
+    border: 1px solid oklch(100% 0 0 / 0.18);
+    padding: 0.3rem 1rem;
+    border-radius: 0.4rem;
+    cursor: pointer;
+    transition: background 0.15s;
+
+    &:hover {
+      background: oklch(0% 0 0 / 0.4);
+    }
+
+    &.is-active {
+      background: oklch(55% 0.18 240);
+      border-color: oklch(55% 0.18 240);
+    }
+  }
+
+  .qa-panel__preview {
+    padding: 0 2rem 2rem;
+
+    .expanding-panel.qa-preview-panel {
+      --expanding-panel-content-z-index: 20;
+
+      + .expanding-panel.qa-preview-panel {
+        margin-block-start: 1rem;
+      }
+    }
+
+    .qa-preview-panel-body {
+      background-color: white;
+      color: black;
+      border: 1px solid oklch(0% 0 0 / 0.15);
+      border-radius: 0.4rem;
+      padding: 1rem;
+      box-shadow: 0 4px 12px rgb(0 0 0 / 15%);
+    }
+  }
+}
 </style>

package/app/pages/ui/layout-content-docs.vue

@@ -0,0 +1,72 @@
+<template>
+  <div>
+    <NuxtLayout name="default">
+      <template #layout-content>
+        <PageRow tag="div" variant="content" :style-class-passthrough="['mbe-20']">
+          <h1 class="page-heading-2">Layout Content Docs</h1>
+
+          <CanvasSwitcher v-model:canvas-name="canvasName" />
+        </PageRow>
+
+        <PageRow tag="div" variant="content" :style-class-passthrough="['mbe-20']">
+          <div :class="[canvasName]">
+            <ContentDocs
+              v-model:active-nav-item="activeNavItem"
+              v-model:active-page-nav-item="activePageNavItem"
+              :docs-nav-items="docsNavItems"
+              :docs-page-nav-items="docsPageNavItems"
+            >
+              <template #docsContent>
+                <h3 class="page-heading-3">Docs Content</h3>
+                <p>
+                  Mi nibh quisque taciti porta curabitur nostra volutpat. Habitant sodales arcu habitasse mi duis
+                  conubia leo lacinia. Montes torquent sodales adipiscing; proin semper feugiat morbi ullamcorper
+                  praesent. Arcu luctus tempor quam ligula vestibulum sapien faucibus ridiculus. Cursus consequat
+                  ultricies consectetur class suscipit quisque convallis eget? Dignissim mattis luctus enim habitant
+                  porta pretium litora. Parturient montes imperdiet massa; sollicitudin varius hac aptent. Eleifend
+                  parturient mattis tellus nisi a montes.
+                </p>
+              </template>
+            </ContentDocs>
+          </div>
+        </PageRow>
+      </template>
+    </NuxtLayout>
+  </div>
+</template>
+
+<script setup lang="ts">
+import type { MediaCanvas, DocsNavItem } from "~/types/components";
+definePageMeta({
+  layout: false,
+});
+
+useHead({
+  title: "UI Layout Content Docs",
+  meta: [{ name: "description", content: "Examples of UI Component Layout Content Docs" }],
+  bodyAttrs: {
+    class: "content-docs-demo-page",
+  },
+});
+
+const canvasName = ref<MediaCanvas>("mobileCanvas");
+
+const docsNavItems: DocsNavItem[] = [
+  { label: "Getting started", to: "/ui/layout-content-docs", icon: "lucide:rocket" },
+  { label: "Installation", to: "/ui/layout-content-docs#installation", icon: "lucide:download" },
+  { label: "Configuration", to: "/ui/layout-content-docs#configuration" },
+  { label: "Theming", to: "/ui/layout-content-docs#theming", icon: "lucide:palette" },
+  { label: "Accessibility", to: "/ui/layout-content-docs#accessibility" },
+  { label: "Troubleshooting", to: "/ui/layout-content-docs#troubleshooting", icon: "lucide:life-buoy" },
+];
+
+const docsPageNavItems: DocsNavItem[] = [
+  { label: "Overview", to: "/ui/layout-content-docs#overview", icon: "lucide:eye" },
+  { label: "Examples", to: "/ui/layout-content-docs#examples" },
+  { label: "Props", to: "/ui/layout-content-docs#props", icon: "lucide:settings-2" },
+  { label: "Slots", to: "/ui/layout-content-docs#slots" },
+];
+
+const activeNavItem = ref<string | undefined>(docsNavItems[0]?.to);
+const activePageNavItem = ref<string | undefined>(undefined);
+</script>