srcdev-nuxt-components 9.5.5 → 9.5.7

package/app/components/01.atoms/ui-block-decorated/stories/UiBlockDecorated.stories.ts

@@ -1,7 +1,21 @@
+import type { Meta, StoryFn } from "@nuxtjs/storybook";
+import { computed } from "vue";
 import UiBlockDecorated from "../UiBlockDecorated.vue";
-import type { Meta, StoryObj } from "@nuxtjs/storybook";
 
-const meta: Meta<typeof UiBlockDecorated> = {
+interface UiBlockDecoratedStoryArgs {
+  tag: "div" | "p" | "span" | "section" | "article" | "aside" | "header" | "footer" | "main" | "nav" | "ul" | "ol";
+  borderStrength: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+  shadowStrength: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+  innerShadowStrength: 0 | 1 | 2 | 3 | 4;
+  label: string;
+  borderColour: string;
+  shadowColour: string;
+  innerShadowColour: string;
+  background: string;
+  textColour: string;
+}
+
+export default {
   title: "Atoms/UiBlockDecorated",
   component: UiBlockDecorated,
   argTypes: {
@@ -29,120 +43,134 @@ const meta: Meta<typeof UiBlockDecorated> = {
       description: "Inner shadow strength level (0 = none)",
       table: { category: "Basic" },
     },
-    styleClassPassthrough: {
-      table: { disable: true },
+    label: { control: "text", description: "Story only: block text", table: { category: "Story" } },
+    borderColour: {
+      control: "color",
+      description: "--ui-block-decorated-border-colour (empty = var(--theme-border))",
+      table: { category: "Tokens" },
+    },
+    shadowColour: {
+      control: "color",
+      description: "--ui-block-decorated-shadow-colour (empty = black). Each strength level mixes in its own opacity.",
+      table: { category: "Tokens" },
+    },
+    innerShadowColour: {
+      control: "color",
+      description: "--ui-block-decorated-inner-shadow-colour (empty = the shadow colour)",
+      table: { category: "Tokens" },
+    },
+    background: {
+      control: "color",
+      description: "Story only: block background, for checking contrast (empty = none)",
+      table: { category: "Story" },
+    },
+    textColour: {
+      control: "color",
+      description: "Story only: block text colour (empty = inherited)",
+      table: { category: "Story" },
     },
   },
+  args: {
+    tag: "div",
+    borderStrength: 0,
+    shadowStrength: 0,
+    innerShadowStrength: 0,
+    label: "No decoration",
+    borderColour: "",
+    shadowColour: "",
+    innerShadowColour: "",
+    background: "",
+    textColour: "",
+  },
   parameters: {
     docs: {
       description: {
         component:
-          "A plain block wrapper that applies independent border / drop-shadow / inner-shadow strength levels via CSS custom properties (see CONSUMER-STYLING.md).",
+          "A plain block wrapper that applies independent border / drop-shadow / inner-shadow strength levels via CSS custom properties (see CONSUMER-STYLING.md). Use the colour pickers under Tokens to recolour every strength level at once.",
       },
     },
   },
-};
+} as Meta<UiBlockDecoratedStoryArgs>;
 
-export default meta;
-type Story = StoryObj<typeof UiBlockDecorated>;
+const Template: StoryFn<UiBlockDecoratedStoryArgs> = (args) => ({
+  components: { UiBlockDecorated },
+  setup() {
+    const blockStyle = computed(() => ({
+      padding: "2rem",
+      ...(args.borderColour ? { "--ui-block-decorated-border-colour": args.borderColour } : {}),
+      ...(args.shadowColour ? { "--ui-block-decorated-shadow-colour": args.shadowColour } : {}),
+      ...(args.innerShadowColour ? { "--ui-block-decorated-inner-shadow-colour": args.innerShadowColour } : {}),
+      ...(args.background ? { background: args.background } : {}),
+      ...(args.textColour ? { color: args.textColour } : {}),
+    }));
+    return { args, blockStyle };
+  },
+  template: `
+    <UiBlockDecorated
+      :tag="args.tag"
+      :border-strength="args.borderStrength"
+      :shadow-strength="args.shadowStrength"
+      :inner-shadow-strength="args.innerShadowStrength"
+      :style="blockStyle"
+    >
+      {{ args.label }}
+    </UiBlockDecorated>
+  `,
+});
 
-const blockStyle = "padding: 2rem; background: var(--theme-surface, #fff);";
+export const Default = Template.bind({});
 
-export const Default: Story = {
-  args: {
-    tag: "div",
-  },
-  render: (args) => ({
-    components: { UiBlockDecorated },
-    setup() {
-      return { args, blockStyle };
-    },
-    template: `<UiBlockDecorated v-bind="args" :style="blockStyle">No decoration</UiBlockDecorated>`,
-  }),
-};
+export const Border = Template.bind({});
+Border.args = { borderStrength: 3, label: "Border strength 3" };
 
-export const Border: Story = {
-  args: {
-    tag: "div",
-    borderStrength: 3,
-  },
-  render: (args) => ({
-    components: { UiBlockDecorated },
-    setup() {
-      return { args, blockStyle };
-    },
-    template: `<UiBlockDecorated v-bind="args" :style="blockStyle">Border strength 3</UiBlockDecorated>`,
-  }),
-};
+export const Shadow = Template.bind({});
+Shadow.args = { shadowStrength: 4, label: "Shadow strength 4" };
 
-export const Shadow: Story = {
-  args: {
-    tag: "div",
-    shadowStrength: 4,
-  },
-  render: (args) => ({
-    components: { UiBlockDecorated },
-    setup() {
-      return { args, blockStyle };
-    },
-    template: `<UiBlockDecorated v-bind="args" :style="blockStyle">Shadow strength 4</UiBlockDecorated>`,
-  }),
-};
+export const InnerShadow = Template.bind({});
+InnerShadow.args = { innerShadowStrength: 3, label: "Inner shadow strength 3" };
 
-export const InnerShadow: Story = {
-  args: {
-    tag: "div",
-    innerShadowStrength: 3,
-  },
-  render: (args) => ({
-    components: { UiBlockDecorated },
-    setup() {
-      return { args, blockStyle };
-    },
-    template: `<UiBlockDecorated v-bind="args" :style="blockStyle">Inner shadow strength 3</UiBlockDecorated>`,
-  }),
-};
+export const AllCombined = Template.bind({});
+AllCombined.args = { borderStrength: 2, shadowStrength: 3, innerShadowStrength: 2, label: "All three combined" };
 
-export const AllCombined: Story = {
-  args: {
-    tag: "div",
-    borderStrength: 2,
-    shadowStrength: 3,
-    innerShadowStrength: 2,
-  },
-  render: (args) => ({
-    components: { UiBlockDecorated },
-    setup() {
-      return { args, blockStyle };
+export const BrandColours = Template.bind({});
+BrandColours.args = {
+  borderStrength: 2,
+  shadowStrength: 4,
+  innerShadowStrength: 2,
+  label: "Brand colours via the colour tokens",
+  borderColour: "#7c3aed",
+  shadowColour: "#7c3aed",
+  background: "#faf5ff",
+  textColour: "#3b0764",
+};
+BrandColours.parameters = {
+  docs: {
+    description: {
+      story:
+        "`--ui-block-decorated-border-colour` and `--ui-block-decorated-shadow-colour` recolour every strength level; each shadow level keeps its own opacity. Background and text colour are story-only, for checking contrast.",
     },
-    template: `<UiBlockDecorated v-bind="args" :style="blockStyle">All three combined</UiBlockDecorated>`,
-  }),
+  },
 };
 
-export const CustomTokens: Story = {
-  args: {
-    tag: "div",
-    shadowStrength: 3,
+export const CustomTokens: StoryFn<UiBlockDecoratedStoryArgs> = (args) => ({
+  components: { UiBlockDecorated },
+  setup() {
+    return { args };
   },
-  render: (args) => ({
-    components: { UiBlockDecorated },
-    setup() {
-      return { args, blockStyle };
-    },
-    template: `
-      <UiBlockDecorated
-        v-bind="args"
-        :style="blockStyle + ' --ui-block-decorated-shadow-3: 0 6px 12px rgba(0, 0, 0, 0.25);'"
-      >
-        Custom shadow-3 token
-      </UiBlockDecorated>
-    `,
-  }),
-  parameters: {
-    docs: {
-      description: {
-        story: "Overriding a strength level's token via an inline `--ui-block-decorated-*` custom property.",
-      },
+  template: `
+    <UiBlockDecorated
+      :shadow-strength="3"
+      style="padding: 2rem; --ui-block-decorated-shadow-3: 0 6px 12px rgba(0, 0, 0, 0.25);"
+    >
+      Custom shadow-3 token
+    </UiBlockDecorated>
+  `,
+});
+CustomTokens.parameters = {
+  controls: { disable: true },
+  docs: {
+    description: {
+      story: "Overriding a whole strength level's token via an inline `--ui-block-decorated-*` custom property.",
     },
   },
 };

package/app/components/02.molecules/action-menu/ActionMenu.vue

@@ -1,5 +1,5 @@
 <template>
-  <div class="action-menu" :class="[elementClasses]" :style="`--_anchor-name: ${anchorName}`">
+  <div ref="rootRef" class="action-menu" :class="[elementClasses]" :style="`--_anchor-name: ${anchorName}`">
     <button
       ref="triggerRef"
       :popovertarget="menuId"
@@ -8,6 +8,8 @@
       class="action-menu-trigger"
       :aria-label="label"
       aria-haspopup="menu"
+      :aria-expanded="isOpen"
+      @click="handleTriggerClick"
     >
       <Icon :name="triggerIcon" class="action-menu-trigger-icon" aria-hidden="true" />
     </button>
@@ -17,6 +19,10 @@
       ref="popoverRef"
       popover
       class="action-menu-popover"
+      :class="{ 'action-menu-popover-open': usesFallbackPopover && isOpen }"
+      :style="positionStyle"
+      :data-placement="popoverPlacement"
+      @beforetoggle="handleBeforeToggle"
       @toggle="handleToggle"
       @keydown="handleKeydown"
     >
@@ -49,6 +55,7 @@ const id = useId();
 const menuId = `action-menu-${id}`;
 const anchorName = `--action-menu-anchor-${id}`;
 
+const rootRef = ref<HTMLDivElement | null>(null);
 const triggerRef = ref<HTMLButtonElement | null>(null);
 const popoverRef = ref<HTMLDivElement | null>(null);
 
@@ -56,23 +63,23 @@ const popoverRef = ref<HTMLDivElement | null>(null);
 const getMenuItems = (): HTMLElement[] =>
   Array.from(popoverRef.value?.querySelectorAll<HTMLElement>('[role="menuitem"]') ?? []);
 
-/**
- * Close the menu and return focus to the trigger.
- * Called on item click — Escape is handled natively by the Popover API
- * (which also restores focus to the trigger automatically).
- */
+const {
+  isOpen,
+  usesFallbackPopover,
+  positionStyle,
+  popoverPlacement,
+  hide,
+  handleTriggerClick,
+  handleBeforeToggle,
+  handleToggle,
+} = useAnchoredPopover({ rootRef, triggerRef, popoverRef, onOpen: () => getMenuItems()[0]?.focus() });
+
+/** Close the menu and return focus to the trigger. Called on item click. */
 const closeMenu = () => {
-  popoverRef.value?.hidePopover();
+  hide();
   triggerRef.value?.focus();
 };
 
-const handleToggle = (event: Event) => {
-  const toggleEvent = event as ToggleEvent;
-  if (toggleEvent.newState === "open") {
-    getMenuItems()[0]?.focus();
-  }
-};
-
 /**
  * Keyboard navigation following the WAI-ARIA menu pattern.
  *
@@ -81,7 +88,7 @@ const handleToggle = (event: Event) => {
  * Tab                  — close the menu; let the browser Tab naturally
  *                        (do NOT focus the trigger — Tab should advance
  *                        to the next element in the page).
- * Escape               — handled natively by the Popover API.
+ * Escape               — native light dismiss, or the fallback listener without the Popover API.
  */
 const handleKeydown = (event: KeyboardEvent) => {
   const items = getMenuItems();
@@ -108,7 +115,7 @@ const handleKeydown = (event: KeyboardEvent) => {
       break;
     case "Tab":
       // Close without stealing focus — Tab exits to the next DOM element naturally.
-      popoverRef.value?.hidePopover();
+      hide();
       break;
   }
 };
@@ -194,6 +201,24 @@ watch(
         }
       }
 
+      /* Kept apart from :popover-open, which would invalidate a shared selector list where unsupported. */
+      &.action-menu-popover-open {
+        display: block;
+        opacity: 1;
+      }
+
+      @supports not (anchor-name: --a) {
+        position: fixed;
+        top: calc(var(--_anchor-bottom, 0px) + var(--action-menu-block-distance, 0.4rem));
+        right: var(--_anchor-right-inverse, 0px);
+        z-index: var(--action-menu-popover-z-index, 999999);
+
+        &[data-placement="top"] {
+          top: auto;
+          bottom: calc(var(--_anchor-top-inverse, 0px) + var(--action-menu-block-distance, 0.4rem));
+        }
+      }
+
       .action-menu-list {
         display: grid;
         grid-template-columns: auto 1fr auto;

package/app/components/02.molecules/action-menu/CONSUMER-STYLING.md

@@ -31,6 +31,7 @@ All `--action-menu-*` tokens are the stable override surface. Action menus repea
 | `--action-menu-popover-min-width` | `20rem` | Minimum menu width |
 | `--action-menu-popover-shadow` | `0 0.4rem 1.6rem rgba(0, 0, 0, 0.1)` | Menu panel drop shadow |
 | `--action-menu-popover-transition-duration` | `200ms` | Open/close fade duration |
+| `--action-menu-popover-z-index` | `999999` | Stacking order in browsers without CSS anchor positioning (see Positioning). Ignored where the popover renders in the top layer |
 | `--action-menu-item-divider` | `0.1rem solid var(--slate-02)` | Divider between list rows |
 
 ### Menu items (`ActionMenuItem`, resolved on `.action-menu-item`)
@@ -60,7 +61,10 @@ Private (not public API): `--_trigger-size`, `--_popover-transition-duration`, `
 
 | Hook | When |
 |---|---|
-| `.action-menu-popover:popover-open` | Menu is open |
+| `.action-menu-popover:popover-open` | Menu is open, Popover API browsers |
+| `.action-menu-popover-open` | Menu is open, browsers without the Popover API (Safari 16 and older). Style it in a **separate rule** from `:popover-open`: a selector list containing `:popover-open` is dropped whole where it's unsupported |
+| `.action-menu-trigger[aria-expanded="true"]` | Menu is open, every browser |
+| `.action-menu-popover[data-placement="top"]` | Flipped above the trigger, browsers without CSS anchor positioning only |
 
 Inner classes: `.action-menu-trigger`, `.action-menu-trigger-icon`, `.action-menu-popover`,
 `.action-menu-list`, `.action-menu-list-item`; on each item `.action-menu-item`,
@@ -76,8 +80,17 @@ Inner classes: `.action-menu-trigger`, `.action-menu-trigger-icon`, `.action-men
 
 The menu uses the Popover API plus CSS anchor positioning: it opens below the trigger,
 right-aligned, and flips above near the bottom of the viewport (`position-try-fallbacks:
-flip-block`). Browsers without anchor positioning still open the popover, but not anchored to the
-trigger.
+flip-block`).
+
+Fallbacks, via the shared `useAnchoredPopover` composable:
+
+- **No anchor positioning** (e.g. Safari 17–18): the popover is placed with `position: fixed` from
+  the trigger's measured position, re-measured on scroll and resize, and flipped above when there's
+  no room below.
+- **No Popover API** (Safari 16 and older): the menu also opens and closes in JS, with
+  outside-click and Escape dismissal. It isn't in the top layer in this mode, so
+  `--action-menu-popover-z-index` matters, and an ancestor with `transform`, `filter` or `contain`
+  becomes its containing block and can misplace it.
 
 ---
 

package/app/components/02.molecules/action-menu/tests/ActionMenu.spec.ts

@@ -500,4 +500,32 @@ describe("ActionMenu", () => {
       expect(host.findAll(".action-menu-list-item")).toHaveLength(2);
     });
   });
+
+  // -------------------------
+  // Without the Popover API (Safari 16 and older)
+  // -------------------------
+  describe("Without the Popover API", () => {
+    beforeEach(() => {
+      Object.defineProperty(HTMLElement.prototype, "showPopover", { value: undefined, writable: true, configurable: true });
+    });
+
+    it("opens from the trigger with the fallback open class and aria-expanded", async () => {
+      wrapper = await createWrapper({}, { "item-0": '<button role="menuitem">Edit</button>' });
+      const popover = wrapper.find(".action-menu-popover");
+      expect(popover.classes()).not.toContain("action-menu-popover-open");
+
+      await wrapper.find(".action-menu-trigger").trigger("click");
+      expect(popover.classes()).toContain("action-menu-popover-open");
+      expect(wrapper.find(".action-menu-trigger").attributes("aria-expanded")).toBe("true");
+    });
+
+    it("closes when an item is clicked", async () => {
+      wrapper = await createWrapper({}, { "item-0": '<button role="menuitem">Edit</button>' });
+      await wrapper.find(".action-menu-trigger").trigger("click");
+      await wrapper.find(".action-menu-list-item").trigger("click");
+
+      expect(wrapper.find(".action-menu-popover").classes()).not.toContain("action-menu-popover-open");
+      expect(wrapper.find(".action-menu-trigger").attributes("aria-expanded")).toBe("false");
+    });
+  });
 });

package/app/components/02.molecules/action-menu/tests/__snapshots__/ActionMenu.spec.ts.snap

@@ -1,7 +1,7 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
 exports[`ActionMenu > Snapshots > default (no items) 1`] = `
-"<div class="action-menu" style="--_anchor-name: --action-menu-anchor-v-0-0;"><button popovertarget="action-menu-v-0-0" popovertargetaction="toggle" type="button" class="action-menu-trigger" aria-label="Open actions menu" aria-haspopup="menu"><span class="iconify i-lucide:ellipsis action-menu-trigger-icon" aria-hidden="true"></span></button>
+"<div class="action-menu" style="--_anchor-name: --action-menu-anchor-v-0-0;"><button popovertarget="action-menu-v-0-0" popovertargetaction="toggle" type="button" class="action-menu-trigger" aria-label="Open actions menu" aria-haspopup="menu" aria-expanded="false"><span class="iconify i-lucide:ellipsis action-menu-trigger-icon" aria-hidden="true"></span></button>
   <div id="action-menu-v-0-0" popover="" class="action-menu-popover">
     <ul class="action-menu-list" role="menu" aria-label="Open actions menu"></ul>
   </div>
@@ -9,7 +9,7 @@ exports[`ActionMenu > Snapshots > default (no items) 1`] = `
 `;
 
 exports[`ActionMenu > Snapshots > with custom label 1`] = `
-"<div class="action-menu" style="--_anchor-name: --action-menu-anchor-v-0-0;"><button popovertarget="action-menu-v-0-0" popovertargetaction="toggle" type="button" class="action-menu-trigger" aria-label="Record actions" aria-haspopup="menu"><span class="iconify i-lucide:ellipsis action-menu-trigger-icon" aria-hidden="true"></span></button>
+"<div class="action-menu" style="--_anchor-name: --action-menu-anchor-v-0-0;"><button popovertarget="action-menu-v-0-0" popovertargetaction="toggle" type="button" class="action-menu-trigger" aria-label="Record actions" aria-haspopup="menu" aria-expanded="false"><span class="iconify i-lucide:ellipsis action-menu-trigger-icon" aria-hidden="true"></span></button>
   <div id="action-menu-v-0-0" popover="" class="action-menu-popover">
     <ul class="action-menu-list" role="menu" aria-label="Record actions"></ul>
   </div>
@@ -17,7 +17,7 @@ exports[`ActionMenu > Snapshots > with custom label 1`] = `
 `;
 
 exports[`ActionMenu > Snapshots > with slot content 1`] = `
-"<div class="action-menu" style="--_anchor-name: --action-menu-anchor-v-0-0;"><button popovertarget="action-menu-v-0-0" popovertargetaction="toggle" type="button" class="action-menu-trigger" aria-label="Open actions menu" aria-haspopup="menu"><span class="iconify i-lucide:ellipsis action-menu-trigger-icon" aria-hidden="true"></span></button>
+"<div class="action-menu" style="--_anchor-name: --action-menu-anchor-v-0-0;"><button popovertarget="action-menu-v-0-0" popovertargetaction="toggle" type="button" class="action-menu-trigger" aria-label="Open actions menu" aria-haspopup="menu" aria-expanded="false"><span class="iconify i-lucide:ellipsis action-menu-trigger-icon" aria-hidden="true"></span></button>
   <div id="action-menu-v-0-0" popover="" class="action-menu-popover">
     <ul class="action-menu-list" role="menu" aria-label="Open actions menu">
       <li class="action-menu-list-item" role="none"><button role="menuitem">Edit</button></li>

package/app/components/02.molecules/display-tooltip-defined/DisplayTooltipDefined.vue

@@ -7,7 +7,7 @@
     <template v-if="$slots.triggerContent" #triggerContent>
       <slot name="triggerContent"></slot>
     </template>
-    <template #tooltipContent>
+    <template #tooltipContent="{ close }">
       <div class="popover-content-defined">
         <component
           :is="contentText.tooltipTitle?.tag"
@@ -31,6 +31,7 @@
           popovertargetaction="hide"
           class="display-tooltip-close-button"
           :aria-label="closeButtonAriaLabel"
+          @click="close"
         >
           {{ closeButtonText }}
         </button>

package/app/components/02.molecules/display-tooltip-defined/stories/DisplayTooltipDefined.stories.ts

@@ -67,7 +67,7 @@ export const GuidedTour: Story = {
     docs: {
       description: {
         story:
-          "Recreates the deleted `app/pages/ui/tooltips.vue` demo: `useTooltipsGuide` walks a container's `[popover]` elements in DOM order, opening each and waiting for its close button before advancing — the autoplay-through-steps pattern seen on some guide intros. Mixes a `DisplayTooltipDefined` step with a plain `DisplayTooltip` step (the guide works with either, since it only needs native `[popover]`/`popovertarget` markup). Guide auto-starts 800ms after mount in this story; use \"Run guide again\" to replay it.",
+          "Recreates the deleted `app/pages/ui/tooltips.vue` demo: `useTooltipsGuide` walks a container's `[popover]` elements in DOM order, opening each and waiting for its close button before advancing — the autoplay-through-steps pattern seen on some guide intros. Mixes a `DisplayTooltipDefined` step (its close button relabelled \"Next\" via `closeButtonText`) with a plain `DisplayTooltip` step. A hand-written close button must call the `tooltipContent` slot's `close()` as well as carrying `popovertargetaction=\"hide\"`: the attribute alone does nothing on Safari 16, which has no Popover API. Guide auto-starts 800ms after mount in this story; use \"Run guide again\" to replay it.",
       },
     },
   },
@@ -89,12 +89,14 @@ export const GuidedTour: Story = {
             {{ isGuideRunning ? 'Guide running…' : 'Run guide again' }}
           </button>
           <span v-if="isGuideRunning" style="font-size: 1.3rem; color: #666;">
-            Step {{ currentTooltipIndex + 1 }} of {{ totalPopovers }} — click each popover's Close button to advance
+            Step {{ currentTooltipIndex + 1 }} of {{ totalPopovers }} — click Next (Close on the last step) to advance
           </span>
         </div>
 
         <div ref="guideContainer" style="display: grid; gap: 2rem;">
           <DisplayTooltipDefined
+            close-button-text="Next"
+            close-button-aria-label="Next step"
             :content-text="{
               tooltipTitle: { tag: 'h3', text: 'Step 1' },
               tooltipContent: { tag: 'p', text: 'This step uses DisplayTooltipDefined — structured title/body/action content plus a built-in close button.' },
@@ -106,14 +108,15 @@ export const GuidedTour: Story = {
 
           <DisplayTooltip tooltip-id="guided-tour-step-2">
             <template #triggerContent>Trigger from plain DisplayTooltip</template>
-            <template #tooltipContent>
-              <p style="margin: 0;">This step uses plain DisplayTooltip — you supply the close button yourself via the tooltipContent slot.</p>
+            <template #tooltipContent="{ close }">
+              <p>This step uses plain DisplayTooltip — you supply the close button yourself via the tooltipContent slot.</p>
               <button
                 popovertarget="guided-tour-step-2"
                 popovertargetaction="hide"
                 class="display-tooltip-close-button"
                 style="align-self: flex-end;"
                 aria-label="Close tool tip"
+                @click="close"
               >
                 Close
               </button>

package/app/components/02.molecules/display-tooltip-defined/tests/DisplayTooltipDefined.spec.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
 import { mountSuspended } from "@nuxt/test-utils/runtime";
 import DisplayTooltipDefined from "../DisplayTooltipDefined.vue";
 import type { TooltipContentText } from "~/types/components";
@@ -63,4 +63,23 @@ describe("DisplayTooltipDefined", () => {
     });
     expect(wrapper.classes()).toContain("custom-class");
   });
+
+  describe("without the Popover API", () => {
+    beforeEach(() => {
+      Object.defineProperty(HTMLElement.prototype, "showPopover", { value: undefined, writable: true, configurable: true });
+    });
+
+    afterEach(() => {
+      delete (HTMLElement.prototype as unknown as Record<string, unknown>)["showPopover"];
+    });
+
+    it("closes from the close button", async () => {
+      const wrapper = await mountSuspended(DisplayTooltipDefined, { props: { contentText } });
+      await wrapper.find(".display-tooltip-trigger-button").trigger("click");
+      expect(wrapper.find(".display-tooltip-popover").classes()).toContain("display-tooltip-popover-open");
+
+      await wrapper.find(".display-tooltip-close-button").trigger("click");
+      expect(wrapper.find(".display-tooltip-popover").classes()).not.toContain("display-tooltip-popover-open");
+    });
+  });
 });

package/app/components/02.molecules/display-tooltip-defined/tests/__snapshots__/DisplayTooltipDefined.spec.ts.snap

@@ -3,7 +3,7 @@
 exports[`DisplayTooltipDefined > renders correct HTML structure 1`] = `
 "<div class="display-tooltip-core" style="--_anchor-name: --tooltip-anchor-v-0-0-0;">
   <div class="display-tooltip-trigger-wrapper body-md">
-    <!--v-if--><button popovertarget="nuxt-tooltip-fixed" popovertargetaction="toggle" class="display-tooltip-trigger-button" aria-label="Toggle the popover"><span class="iconify i-fa7-solid:circle-question display-tooltip-trigger-icon" aria-hidden="true"></span></button>
+    <!--v-if--><button popovertarget="nuxt-tooltip-fixed" popovertargetaction="toggle" class="display-tooltip-trigger-button" aria-label="Toggle the popover" aria-expanded="false"><span class="iconify i-fa7-solid:circle-question display-tooltip-trigger-icon" aria-hidden="true"></span></button>
   </div>
   <div id="nuxt-tooltip-fixed" popover="" class="display-tooltip-popover">
     <div class="display-tooltip-popover-content">

package/app/components/02.molecules/navigation/deep-expanding-menu/CONSUMER-STYLING.md

@@ -20,6 +20,7 @@
 | `--deep-expanding-menu-panel-list-gap` | `1.2rem` | Gap between child link grid items |
 | `--deep-expanding-menu-group-link-colour` | `var(--slate-10)` | Child link text colour |
 | `--deep-expanding-menu-group-link-border-colour-hover` | `var(--slate-10)` | Child link bottom border colour on hover/focus |
+| `--deep-expanding-menu-panel-z-index` | `999999` | Panel stacking order in browsers without CSS anchor positioning. Ignored where the panel renders in the top layer |
 
 ```css
 .my-page {
@@ -39,14 +40,28 @@ Or scope to a single instance via `styleClassPassthrough`:
 
 ## Not tokenised
 
-- The `@position-try` fallback offsets (`--anchor-left`/`--anchor-right`) are fixed at `1rem` —
-  these are CSS anchor-positioning fallback rules, not runtime custom properties, so they can't be
-  overridden per-instance without a new `@position-try` block.
+- The `1rem` gap between a toggle and its panel.
 - Anchor names and popover target ids are generated per-instance via `useId()` and are not
   consumer-configurable — they only need to be unique, not meaningful.
 
 ---
 
+## Open state and older browsers
+
+| Hook | Meaning |
+|---|---|
+| `.navigation-group-toggle[aria-expanded="true"]` | Group open, every browser (flips the caret) |
+| `.navigation-group-panel:popover-open` | Panel open, Popover API browsers |
+| `.deep-expanding-menu-panel-open` | Panel open, browsers without the Popover API (Safari 16 and older). Style it in a **separate rule** from `:popover-open`: a selector list containing `:popover-open` is dropped whole where it's unsupported |
+| `.navigation-group-panel[data-placement="top"]` | Flipped above the toggle, browsers without CSS anchor positioning only |
+
+Without CSS anchor positioning (e.g. Safari 17–18) the panel is placed with `position: fixed` from
+the toggle's measured position. Without the Popover API (Safari 16) the panel also opens and closes
+in JS and isn't in the top layer, so `--deep-expanding-menu-panel-z-index` applies, and an ancestor
+with `transform`, `filter` or `contain` becomes its containing block and can misplace it.
+
+---
+
 ## Local overrides
 
 Set the tokens above on an element you own (a page or section class, or a class added with
@@ -54,4 +69,3 @@ Set the tokens above on an element you own (a page or section class, or a class
 `@layer` wrapper) so it beats the library's `@layer components`. If your own file uses
 `<style scoped>`, tokens set on your element still work, but selectors that reach inside the component need
 `:deep()`. Patterns and examples: `.claude/skills/component-local-style-override.md`.
-