refactor: AFCL works inside a shadow root, popups, modals, tooltips and the calendar teleport to an injected target which stays body in apps, outside clicks and focus checks look past the shadow host AdminForth/2005

Author: ivictbor

adminforth/design/system-concepts.md

@@ -25,6 +25,17 @@ Apps restyle and test AdminForth by `af-*` and `afcl-*` classes. A restyle never
 - A new AFCL component gets a section on the page of its category in the AFCL docs (`documentation/docs/tutorial/03-Customization/15-afcl/`, a link in its `index.md` as well) and its states and variants in [system.html](./system.html). Docs examples are live, not screenshots: wrap the code blocks of an example into `<AfclPreview id="...">` and the docs build renders them with real AFCL (see `documentation/afcl-preview/vite.config.ts`). Nothing is registered globally, an example imports every AFCL component it uses from `@/afcl`, otherwise the build fails.
 - Example: `DropdownMenu` and `DropdownMenuItem` replaced the hand-made menus of the list (⋯ in the header and in rows), the user menu and the import-export plugin.
 
+## AFCL works inside a shadow root
+
+The live examples of the docs render AFCL in shadow roots of the docs page (`documentation/afcl-preview/mount.ts`). Code which reaches out of the tree of a component breaks there, so an AFCL component:
+
+- teleports popups, modals, tooltips and pickers to `useTeleportTarget()` from `afcl/shadowRoot.ts`, never `to="body"`. The target is `body` in an app and an element of the shadow root in the docs, content teleported out of the root loses its styles. A library which appends its popup to `document.body` (the calendar of flowbite-datepicker in `DatePicker`) is moved to that target too;
+- takes the clicked or scrolled element as `e.composedPath()[0]` in `document` and `window` listeners (outside click, scroll), `e.target` there is the shadow host;
+- reads the focus with `activeElementIn(el)`, `document.activeElement` there is the shadow host as well;
+- finds its own elements by template refs, not by `document.getElementById` or `document.querySelector`.
+
+In an app these give exactly what `body`, `e.target` and `document.activeElement` give, so apps see no difference.
+
 ## Disabled state
 
 A disabled control gets the native `disabled` attribute (`aria-disabled` on a link, which then has no `href`), not `pointer-events-none`: the attribute also blocks the keyboard and form submit, is announced by screen readers and does not pass the click to a parent. Hover styles are left out for a disabled control.

adminforth/spa/src/afcl/CodeInput.vue

@@ -44,6 +44,7 @@
 import { computed, nextTick, onBeforeUnmount, onMounted, ref, useAttrs } from 'vue';
 import { type ClassNameValue } from 'tailwind-merge';
 import { mergeClasses } from './classMerge';
+import { activeElementIn } from './shadowRoot';
 
 defineOptions({ inheritAttrs: false });
 
@@ -169,7 +170,7 @@ function onBlur(e: FocusEvent) {
   }
   // the clicked button still gets its click, the focus is back before the user types again
   requestAnimationFrame(() => {
-    if (inputRef.value?.isConnected && !document.activeElement?.matches(EDITABLE_SELECTOR)) {
+    if (inputRef.value?.isConnected && !activeElementIn(inputRef.value)?.matches(EDITABLE_SELECTOR)) {
       focus();
     }
   });

adminforth/spa/src/afcl/DatePicker.vue

@@ -47,6 +47,7 @@ import utc from 'dayjs/plugin/utc';
 
 import {useCoreStore} from '@/stores/core';
 import {FLEXIBLE_DATEPICKER_FORMAT} from '@/utils/dateUtils';
+import { useTeleportTarget } from './shadowRoot';
 
 import { IconCalendar, IconChevronDown, IconClock } from '@iconify-prerendered/vue-lucide';
 
@@ -134,6 +135,8 @@ watch(start, () => {
   emit('update:valueStart', start.value)
 })
 
+const teleportTarget = useTeleportTarget();
+
 async function initDatepickers() {
   const LS_LANG_KEY = `afLanguage`;
   const options = {format: FLEXIBLE_DATEPICKER_FORMAT, language: localStorage.getItem(LS_LANG_KEY)};
@@ -147,6 +150,11 @@ async function initDatepickers() {
   );
 
   datepickerObject.value = new Datepicker(datepickerStartEl.value, options);
+  // the calendar goes to body and takes only a selector of the document for another container
+  if (teleportTarget instanceof HTMLElement) {
+    datepickerObject.value.config.container = teleportTarget;
+    teleportTarget.appendChild(datepickerObject.value.picker.element);
+  }
 
   addChangeDateListener();
 }

adminforth/spa/src/afcl/DropdownMenu.vue

@@ -3,7 +3,7 @@
     <div class="afcl-dropdown-menu-trigger" @click="onTriggerClick">
       <slot name="trigger" :open="isOpen" />
     </div>
-    <Teleport to="body" :disabled="!teleportToBody">
+    <Teleport :to="teleportTarget" :disabled="!teleportToBody">
       <div
         v-if="keepMounted || isOpen"
         v-show="isOpen"
@@ -23,6 +23,7 @@ import { computed, inject, nextTick, onBeforeUnmount, provide, ref, useAttrs, wa
 import { type ClassNameValue } from 'tailwind-merge';
 import { mergeClasses } from './classMerge';
 import { DROPDOWN_MENU_KEY, type DropdownMenuPlacement } from './dropdownMenuContext';
+import { useTeleportTarget } from './shadowRoot';
 
 defineOptions({ inheritAttrs: false });
 
@@ -39,6 +40,8 @@ const props = withDefaults(defineProps<{
   teleportToBody: false,
 });
 
+const teleportTarget = useTeleportTarget();
+
 const isOpen = defineModel<boolean>('open', { default: false });
 
 const attrs = useAttrs();
@@ -148,7 +151,8 @@ function placeFixed() {
 }
 
 function onDocumentMousedown(e: MouseEvent) {
-  const target = e.target as Node;
+  // inside a shadow root e.target is the host, composedPath() starts at the clicked element
+  const target = e.composedPath()[0] as Node;
   if (rootRef.value?.contains(target) || contentRef.value?.contains(target)) {
     return;
   }
@@ -163,7 +167,8 @@ function onKeydown(e: KeyboardEvent) {
 
 function onViewportChange(e: Event) {
   // scrolling inside the menu itself must not close it
-  if (e.target instanceof Node && contentRef.value?.contains(e.target)) {
+  const target = e.composedPath()[0];
+  if (target instanceof Node && contentRef.value?.contains(target)) {
     return;
   }
   close();

adminforth/spa/src/afcl/Dropzone.vue

@@ -5,7 +5,7 @@
     @dragleave.prevent="dragging = false"
     @drop.prevent="dragging = false; doEmit(($event.dataTransfer as DataTransfer).files)"
   >
-      <label :id="id" class="flex flex-col items-center justify-center w-full border border-dashed rounded-lg cursor-pointer transition-colors
+      <label ref="labelEl" :id="id" class="flex flex-col items-center justify-center w-full border border-dashed rounded-lg cursor-pointer transition-colors
         hover:bg-lightDropzoneBackgroundHover hover:border-lightDropzoneBorderHover  dark:hover:border-darkDropzoneBorderHover dark:hover:bg-darkDropzoneBackgroundHover"
         :class="{
           'border-lightDropzoneBorderDragging dark:border-darkDropzoneBorderDragging': dragging,
@@ -203,6 +203,7 @@ function doEmit(filesIn: FileList) {
 }
 
 const dragging = ref(false);
+const labelEl = ref<HTMLLabelElement>();
 
 function removeFile(index: number) {
   storedFiles.value = storedFiles.value.filter((_, i) => i !== index);
@@ -214,7 +215,7 @@ function clear() {
   selectedFiles.value = [];
   storedFiles.value = [];
   emit('update:modelValue', []);
-  const form = document.getElementById(id)?.closest('form');
+  const form = labelEl.value?.closest('form');
   form?.reset();
 }
 

adminforth/spa/src/afcl/Modal.vue

@@ -5,7 +5,7 @@
   >
     <slot name="trigger"></slot>
   </div>
-  <Teleport to="body">
+  <Teleport :to="teleportTarget">
     <Transition
       enter-from-class="af-modal-hidden opacity-0"
       enter-active-class="transition-opacity duration-150 ease-out motion-reduce:transition-none"
@@ -81,9 +81,11 @@ import Button from "./Button.vue";
 import { ref, onMounted, nextTick, onUnmounted, computed, watch, useId, type Ref } from 'vue';
 import { useI18n } from 'vue-i18n';
 import { dialogPanelClasses, dialogFooterClasses } from './dialogStyles';
+import { useTeleportTarget, activeElementIn } from './shadowRoot';
 
 const isModalOpen = defineModel<boolean>('open', { default: false });
 const { t } = useI18n();
+const teleportTarget = useTeleportTarget();
 
 const removeFromDom = computed(() => {
   return props.removeFromDomOnClose && !isModalOpen.value;
@@ -126,7 +128,7 @@ watch(isModalOpen, async (open) => {
   if (open) {
     focusBeforeOpen = document.activeElement as HTMLElement | null;
     await nextTick();
-    if (!panelRef.value!.contains(document.activeElement)) {
+    if (!panelRef.value!.contains(activeElementIn(panelRef.value!))) {
       panelRef.value!.focus({ preventScroll: true });
     }
   } else {

adminforth/spa/src/afcl/Select.vue

@@ -44,7 +44,7 @@
         />
       </div>
     </div>
-    <teleport to="body" v-if="(teleportToBody  || teleportToTop) && showDropdown">
+    <teleport :to="teleportTarget" v-if="(teleportToBody  || teleportToTop) && showDropdown">
       <div ref="dropdownEl" :style="getDropdownPosition" :class="{'shadow-none': isTop, 'z-30': teleportToBody, 'z-[1000]': teleportToTop}"
         class="fixed w-full bg-lightDropdownOptionsBackground shadow-popover dark:shadow-darkPopover dark:bg-darkDropdownOptionsBackground
           rounded-lg p-1 text-base overflow-auto focus:outline-none sm:text-sm max-h-60"
@@ -118,6 +118,7 @@
 import { ref, computed, onMounted, onUnmounted, watch, nextTick, useId,type PropType, type Ref } from 'vue';
 import { IconChevronDown, IconX } from '@iconify-prerendered/vue-lucide';
 import { useElementSize } from '@vueuse/core'
+import { useTeleportTarget } from './shadowRoot';
 
 type ISingleSelectModelValue = string | number | boolean | null;
 
@@ -310,9 +311,12 @@ const filteredItems: Ref<any[]> = computed(() => {
 });
 
 
+const teleportTarget = useTeleportTarget();
+
 const handleClickOutside = (event: MouseEvent) => {
-  const targetEl = event.target as HTMLElement | null;
-  const closestSelect = targetEl?.closest('.afcl-select');
+  // inside a shadow root event.target is the host, composedPath() starts at the clicked element
+  const targetEl = event.composedPath()[0] as HTMLElement;
+  const closestSelect = targetEl.closest('.afcl-select');
   if (closestSelect !== internalSelect.value)
     showDropdown.value = false;
 };

adminforth/spa/src/afcl/Tooltip.vue

@@ -2,7 +2,7 @@
   <div ref="triggerEl" class="afcl-tooltip inline-flex items-center" :style="{ anchorName }" @mouseenter="show" @mouseleave="hide">
       <slot></slot>
   </div>
-  <teleport to="body" v-if="isOpen">
+  <teleport :to="teleportTarget" v-if="isOpen">
     <div
       ref="tooltipEl"
       popover="manual"
@@ -19,11 +19,13 @@
 
 <script setup lang="ts">
 import { ref, nextTick, onBeforeUnmount, useId } from 'vue';
+import { useTeleportTarget } from './shadowRoot';
 
 const OFFSET = 8;
 const SUPPORTS_ANCHOR = CSS.supports('anchor-name: --a');
 
 const anchorName = `--afcl-tooltip-${useId()}`;
+const teleportTarget = useTeleportTarget();
 const triggerEl = ref<HTMLElement>();
 const tooltipEl = ref<HTMLElement>();
 const isOpen = ref(false);

adminforth/spa/src/afcl/shadowRoot.ts

@@ -0,0 +1,17 @@
+import { inject, type InjectionKey } from 'vue';
+
+// AFCL also renders inside a shadow root (the live examples of the docs): popups, modals and tooltips go to an
+// element of that root instead of body, or they lose the styles of the root. The element is positioned,
+// DatePicker places its calendar relative to it
+
+export const AFCL_TELEPORT_TARGET: InjectionKey<string | HTMLElement> = Symbol('afclTeleportTarget');
+
+export function useTeleportTarget() {
+  return inject(AFCL_TELEPORT_TARGET, 'body');
+}
+
+// the focused element as the tree of node sees it: document.activeElement in a page, inside a shadow root the
+// element of that root (document.activeElement there is the shadow host)
+export function activeElementIn(node: Node) {
+  return (node.getRootNode() as Document | ShadowRoot).activeElement;
+}