@ulu/frontend-vue 0.6.23 → 0.6.24

package/lib/plugins/popovers/UluPopoverBase.vue

@@ -0,0 +1,197 @@
+<template>
+  <span 
+    class="popover"
+    ref="contentEl"
+    :style="floatingStyles"
+    :data-placement="placement"
+    :class="[
+      { 
+        'popover--fixed': isFixedStrategy,
+        'is-active': isOpen 
+      },
+      resolvedModifiers
+    ]"
+    @keydown.esc="handleEsc"
+    tabindex="-1"
+  >
+    <span class="popover__inner">
+      <slot :isOpen="isOpen" :close="close" />
+    </span>
+    <span v-if="$slots.footer" class="popover__footer">
+      <slot name="footer" :isOpen="isOpen" :close="close" />
+    </span>
+    <span 
+      v-if="resolvedConfig.arrow"
+      class="popover__arrow" 
+      ref="contentArrow"
+      :style="arrowStyles"
+      data-ulu-popover-arrow
+    ></span>
+  </span>
+</template>
+
+<script setup>
+  import { ref, computed, watch, onUnmounted, nextTick } from 'vue';
+  import { useUluFloating } from '../../composables/useUluFloating.js';
+  import { useModifiers } from '../../composables/useModifiers.js';
+  import { wasClickOutside } from '@ulu/utils/browser/dom.js';
+
+  const emit = defineEmits(['close']);
+
+  const props = defineProps({
+    /**
+     * Controls the open/active state of the popover
+     */
+    isOpen: {
+      type: Boolean,
+      default: false
+    },
+    /**
+     * Close popover when click is outside
+     */
+    clickOutsideCloses: {
+      type: Boolean,
+      default: true
+    },
+    /**
+     * Close popover when escape key is pressed
+     */
+    escapeCloses: {
+      type: Boolean,
+      default: true
+    },
+    /**
+     * Direct focus when open/closing popover
+     */
+    directFocus: {
+      type: Function,
+      default: ({ isOpen, trigger, content }) => {
+        if (isOpen && content) {
+          content.focus({ preventScroll: true });
+        } else if (!isOpen && trigger && trigger instanceof HTMLElement) {
+          // Note: using nextTick prevents scroll jumping in some cases
+          trigger.focus({ preventScroll: true });
+        }
+      }
+    },
+    /**
+     * The target element for the popover to float alongside
+     */
+    trigger: {
+      type: Object,
+      default: null
+    },
+    /**
+     * Floating UI configuration
+     */
+    config: {
+      type: Object,
+      default: () => ({})
+    },
+    /**
+     * Modifiers (to add any modifier classes based on base class [ie. 'large'])
+     */
+    modifiers: [String, Array, Object]
+  });
+
+  const contentEl = ref(null);
+  
+  const { resolvedModifiers } = useModifiers({ props, baseClass: "popover" });
+  
+  const resolvedConfig = computed(() => props.config || {});
+
+  const { floatingStyles, placement, arrowStyles, update, isFixedStrategy, contentArrow } = useUluFloating(
+    computed(() => props.trigger), 
+    contentEl, 
+    resolvedConfig
+  );
+
+  const close = () => {
+    emit('close');
+  };
+
+  const handleEsc = (event) => {
+    if (props.isOpen && props.escapeCloses) {
+      event.preventDefault();
+      close();
+    }
+  };
+
+  let outsideHandler = null;
+
+  const destroyOutsideClick = () => {
+    if (outsideHandler) {
+      document.removeEventListener("click", outsideHandler);
+      outsideHandler = null;
+    }
+  };
+
+  const addOutsideClick = () => {
+    destroyOutsideClick();
+    if (props.clickOutsideCloses) {
+      outsideHandler = (event) => {
+        if (!props.isOpen || !contentEl.value) return;
+        
+        // Ignore clicks on elements that have been removed from the DOM
+        if (!document.body.contains(event.target)) return;
+
+        // If the click happened on a DOM node physically inside the popover,
+        // it is NOT an outside click, even if floating-ui instantly moved
+        // the popover across the screen causing `wasClickOutside` (bounding rect check) to fail.
+        if (contentEl.value.contains(event.target)) return;
+
+        if (wasClickOutside(contentEl.value, event)) {
+          // If the click is on the trigger itself, we let the trigger handle toggling
+          if (props.trigger instanceof HTMLElement && props.trigger.contains(event.target)) {
+            return;
+          }
+          close();
+        }
+      };
+      // Defer so the click that opened the popover doesn't instantly close it
+      setTimeout(() => {
+        if (outsideHandler) {
+          document.addEventListener("click", outsideHandler);
+        }
+      }, 0);
+    }
+  };
+
+  watch(() => props.isOpen, (newVal) => {
+    if (newVal) {
+      update();
+      addOutsideClick();
+      if (props.directFocus) {
+        nextTick(() => {
+          props.directFocus({ isOpen: true, trigger: props.trigger, content: contentEl.value });
+        });
+      }
+    } else {
+      destroyOutsideClick();
+      if (props.directFocus) {
+        nextTick(() => {
+          props.directFocus({ isOpen: false, trigger: props.trigger, content: contentEl.value });
+        });
+      }
+    }
+  }, { immediate: true });
+
+  onUnmounted(() => {
+    destroyOutsideClick();
+  });
+
+  defineExpose({
+    /**
+     * Emits the close event
+     */
+    close,
+    /**
+     * Manually trigger a floating UI position update
+     */
+    update,
+    /**
+     * The internal root popover element reference
+     */
+    content: contentEl
+  });
+</script>

package/lib/plugins/popovers/UluTooltipPopover.vue

@@ -1,39 +1,25 @@
-<!-- NOTE: Need to rename classes when moving this into the library -->
 <template>
-  <span 
-    class="popover popover--tooltip is-active"
-    ref="content"
+  <UluPopoverBase 
+    class="popover--tooltip is-active"
     :id="TOOLTIP_ID"
-    :data-placement="placement"
-    :class="[
-      {
-        'popover--fixed' : isFixedStrategy
-      },
-      resolvedConfig.class
-    ]"
-    :style="floatingStyles"
+    :trigger="trigger"
+    :config="resolvedConfig"
+    :class="resolvedConfig.class"
   >
-    <span v-if="resolvedConfig.isHtml" class="popover__inner" v-html="resolvedConfig.content">
-    </span>
-    <span v-else class="popover__inner">
+    <span v-if="resolvedConfig.isHtml" v-html="resolvedConfig.content"></span>
+    <template v-else>
       <component v-if="resolvedConfig.component" :is="resolvedConfig.component" v-bind="resolvedConfig.componentProps"/>
       <template v-else>
         {{ resolvedConfig.content }}
       </template>
-    </span>
-    <span 
-      v-if="resolvedConfig.arrow"
-      class="popover__arrow" 
-      ref="contentArrow"
-      :style="arrowStyles"
-    ></span>
-  </span>
+    </template>
+  </UluPopoverBase>
 </template>
 
 <script setup>
-  import { ref, toRef, computed } from "vue";
-  import { useUluFloating } from "../../composables/useUluFloating.js";
+  import { computed } from "vue";
   import { TOOLTIP_ID } from "./index.js";
+  import UluPopoverBase from "./UluPopoverBase.vue";
 
   const props = defineProps({
     config: Object,
@@ -43,13 +29,5 @@
     }
   });
 
-  const content = ref(null);
   const resolvedConfig = computed(() => props.config);
-  const { 
-    floatingStyles, 
-    placement,
-    arrowStyles,
-    contentArrow,
-    isFixedStrategy
-  } = useUluFloating(toRef(props, 'trigger'), content, resolvedConfig);
 </script>

package/lib/plugins/popovers/index.js

@@ -4,6 +4,7 @@
 import { reactive, markRaw } from 'vue';
 import UluTooltipDisplay from './UluTooltipDisplay.vue';
 import UluPopover from "./UluPopover.vue";
+import UluPopoverBase from "./UluPopoverBase.vue";
 import defaults from './defaults.js';
 import { useTooltip } from './useTooltip.js';
 
@@ -73,9 +74,12 @@ export default function install(app, userOptions = {}) {
     config: {},
   });
   const showTooltip = (triggerEl, configObj) => {
+    const isDOMElement = triggerEl instanceof Element;
+
     // If a teleport target isn't already specified in the config,
     // try to find a parent dialog to teleport to automatically.
-    if (triggerEl && !configObj.teleportTo) {
+    // (Note: triggerEl might be a virtual element object from useTooltipFollow, not a real DOM element)
+    if (isDOMElement && !configObj.teleportTo) {
       const dialog = triggerEl.closest("dialog");
       if (dialog) {
         configObj.teleportTo = dialog;
@@ -84,12 +88,12 @@ export default function install(app, userOptions = {}) {
     
     // If a tooltip is already active for a different element, remove its attribute.
     if (tooltipState.trigger && tooltipState.trigger !== triggerEl) {
-      if (tooltipState.trigger?.removeAttribute) {
+      if (tooltipState.trigger instanceof Element) {
         tooltipState.trigger.removeAttribute('aria-describedby');
       }
     }
 
-    if (triggerEl?.setAttribute) {
+    if (isDOMElement) {
       triggerEl.setAttribute('aria-describedby', TOOLTIP_ID);
     }
 
@@ -97,8 +101,9 @@ export default function install(app, userOptions = {}) {
     tooltipState.config = configObj;
     tooltipState.visible = true;
   };
+
   const hideTooltip = () => {
-    if (tooltipState.trigger?.removeAttribute) {
+    if (tooltipState.trigger instanceof Element) {
       tooltipState.trigger.removeAttribute('aria-describedby');
     }
     tooltipState.visible = false;
@@ -114,6 +119,7 @@ export default function install(app, userOptions = {}) {
   // Register components and directives
   app.component('UluTooltipDisplay', UluTooltipDisplay);
   app.component('UluPopover', UluPopover);
+  app.component('UluPopoverBase', UluPopoverBase);
 
   const elementHandlers = new WeakMap();
   const popoverDefaults = mergedOptions.popover;
@@ -197,4 +203,8 @@ export default function install(app, userOptions = {}) {
       }
     }
   });
-}
+}
+export { default as UluPopover } from './UluPopover.vue';
+export { default as UluPopoverBase } from './UluPopoverBase.vue';
+export { default as UluTooltipDisplay } from './UluTooltipDisplay.vue';
+export { default as UluTooltipPopover } from './UluTooltipPopover.vue';

package/lib/plugins/tour/UluTourContent.vue

@@ -0,0 +1,37 @@
+<template>
+  <div class="tour-content crop-margins">
+    <component 
+      v-if="step?.title"
+      :is="isModal ? 'h2' : 'strong'" 
+      :class="isModal ? 'h3' : 'h4'" 
+      class="display-block no-margin"
+    >
+      {{ step.title }}
+    </component>
+    <UluRule />
+    <p v-if="step?.content">
+      {{ step.content }}
+    </p>
+  </div>
+</template>
+
+<script setup>
+  import UluRule from "../../components/elements/UluRule.vue";
+
+  defineProps({
+    /**
+     * The tour step configuration object
+     */
+    step: {
+      type: Object,
+      required: true
+    },
+    /**
+     * Adjusts the typography to match a modal context rather than a popover context
+     */
+    isModal: {
+      type: Boolean,
+      default: false
+    }
+  });
+</script>

package/lib/plugins/tour/UluTourDisplay.vue

@@ -0,0 +1,182 @@
+<template>
+  <Teleport to="body">
+    <template v-if="tourState.active">
+      
+      <!-- 1. FULL COMPONENT TAKEOVER -->
+      <component 
+        v-if="currentStep?.component" 
+        :is="currentStep.component" 
+        v-bind="currentStep.componentProps" 
+      />
+
+      <!-- 2. RENDER MODAL STEP -->
+      <UluModal 
+        v-else-if="!currentStep?.target" 
+        :modelValue="true"
+        v-bind="resolvedModalProps"
+        @close="api.stop()"
+      >
+        <component 
+          v-if="currentStep?.contentComponent" 
+          :is="currentStep.contentComponent" 
+          v-bind="currentStep.componentProps"
+        />
+        <UluTourContent v-else :step="currentStep" :is-modal="true" />
+        
+        <template #footer v-if="!currentStep?.hideFooter">
+          <UluTourPager />
+        </template>
+      </UluModal>
+
+      <!-- 3. RENDER POPOVER STEP -->
+      <UluPopoverBase 
+        v-else
+        ref="popoverBase"
+        :trigger="targetEl"
+        :config="resolvedConfig"
+        :style="{ zIndex: 9999 }"
+        :isOpen="true"
+        @close="api.stop()"
+        v-bind="resolvedPopoverProps"
+      >
+        <component 
+          v-if="currentStep?.contentComponent" 
+          :is="currentStep.contentComponent" 
+          v-bind="currentStep.componentProps"
+        />
+        <UluTourContent v-else :step="currentStep" :is-modal="false" />
+        
+        <template #footer v-if="!currentStep?.hideFooter">
+          <UluTourPager />
+        </template>
+      </UluPopoverBase>
+
+      <!-- OPTIONAL HIGHLIGHT BACKDROP -->
+      <div 
+        v-if="currentStep?.target && currentStep?.highlight && targetRect" 
+        class="tour-highlight-backdrop"
+        :style="highlightStyles"
+        @click="api.stop()"
+      ></div>
+    </template>
+  </Teleport>
+</template>
+
+<script setup>
+  import { ref, computed, watch, nextTick, onMounted, onUnmounted } from 'vue';
+  import UluModal from '../../components/collapsible/UluModal.vue';
+  import UluPopoverBase from '../popovers/UluPopoverBase.vue';
+  import UluTourPager from './UluTourPager.vue';
+  import UluTourContent from './UluTourContent.vue';
+  import { useTour } from './useTour.js';
+  
+  const { api, state: tourState } = useTour();
+  
+  const currentStep = computed(() => tourState.active?.steps[tourState.stepIndex]);
+
+  // Floating UI Setup for Popovers
+  const targetEl = ref(null);
+  const popoverBase = ref(null);
+
+  const resolvedConfig = computed(() => ({
+    placement: currentStep.value?.placement || 'bottom',
+    arrow: true,
+    offset: 8
+  }));
+  
+  // Prop Resolution
+  const resolvedModalProps = computed(() => {
+    return {
+      ...(tourState.active?.modalProps || {}),
+      ...(currentStep.value?.modalProps || {})
+    };
+  });
+  
+  const resolvedPopoverProps = computed(() => {
+    return {
+      modifiers: 'large',
+      ...(tourState.active?.popoverProps || {}),
+      ...(currentStep.value?.popoverProps || {})
+    };
+  });
+
+  // Highlight Backdrop Setup
+  const targetRect = ref(null);
+  
+  const updateTargetRect = () => {
+    if (targetEl.value) {
+      const rect = targetEl.value.getBoundingClientRect();
+      targetRect.value = {
+        top: rect.top,
+        left: rect.left,
+        width: rect.width,
+        height: rect.height
+      };
+    } else {
+      targetRect.value = null;
+    }
+  };
+
+  const highlightStyles = computed(() => {
+    if (!targetRect.value) return {};
+    const t = targetRect.value;
+    return {
+      position: 'fixed',
+      top: 0,
+      left: 0,
+      width: '100vw',
+      height: '100vh',
+      pointerEvents: 'auto',
+      zIndex: 9998,
+      background: 'rgba(0,0,0,0.5)',
+      clipPath: `polygon(
+        0% 0%, 
+        100% 0%, 
+        100% 100%, 
+        0% 100%, 
+        0% ${ t.top }px, 
+        ${ t.left }px ${ t.top }px, 
+        ${ t.left }px ${ t.top +  t.height }px, 
+        ${ t.left +  t.width }px ${ t.top +  t.height }px, 
+        ${ t.left +  t.width }px ${ t.top }px, 
+        ${ t.left }px ${ t.top }px, 
+        0% ${ t.top }px
+      )`
+    };
+  });
+
+  // Watch for step changes to update floating UI target
+  watch(currentStep, async (step) => {
+    if (step?.target) {
+      await nextTick();
+      const el = document.querySelector(step.target);
+      if (el) {
+        targetEl.value = el;
+        // UluPopoverBase's isOpen watcher automatically calls update(), 
+        // but since isOpen stays strictly true here when switching between popover steps,
+        // we might need to manually trigger an update if the target changed.
+        if (popoverBase.value) {
+          popoverBase.value.update();
+        }
+        if (step.highlight) {
+          updateTargetRect();
+        }
+      } else {
+        console.warn(`Tour target not found: ${step.target}`);
+      }
+    } else {
+      targetEl.value = null;
+      targetRect.value = null;
+    }
+  }, { immediate: true });
+
+  onMounted(() => {
+    window.addEventListener('resize', updateTargetRect);
+    window.addEventListener('scroll', updateTargetRect);
+  });
+  
+  onUnmounted(() => {
+    window.removeEventListener('resize', updateTargetRect);
+    window.removeEventListener('scroll', updateTargetRect);
+  });
+</script>

package/lib/plugins/tour/UluTourPager.vue

@@ -0,0 +1,36 @@
+<template>
+  <div class="tour-pager layout-flex-justified">
+    <UluButton 
+      @click="api.prev()"
+      text="Previous"
+      :disabled="state.stepIndex === 0"
+      icon="type:previous"
+      iconBefore
+      small
+      secondary
+      transparent
+    />
+    <UluButton 
+      primary
+      :icon="isLastStep ? null : 'type:next'"
+      @click="api.next()"
+      :text="isLastStep ? 'Finish' : 'Next'"
+      small
+    />
+  </div>
+</template>
+
+<script setup>
+  import { computed } from 'vue';
+  import { useTour } from './useTour.js';
+  import UluButton from '../../components/elements/UluButton.vue';
+
+  const { api, state } = useTour();
+
+  const isLastStep = computed(() => {
+    return state.active && state.stepIndex === state.active.steps.length - 1;
+  });
+  const isFirstStep = computed(() => {
+    return state.active && state.stepIndex === 0;
+  });
+</script>

package/lib/plugins/tour/api.js

@@ -0,0 +1,83 @@
+import { markRaw } from "vue";
+
+/**
+ * @typedef {Object} TourStep
+ * @property {String} [target] - The CSS selector for the target element. If omitted, step renders as a modal.
+ * @property {String} [title] - The title text for the step.
+ * @property {String} [content] - The content text for the step.
+ * @property {Object} [component] - A Vue component to completely replace the modal/popover wrapper and layout.
+ * @property {Object} [contentComponent] - A Vue component to replace the step text content, keeping the modal/popover wrappers and default footer.
+ * @property {Object} [componentProps] - Props to bind to the custom component.
+ * @property {Boolean} [hideFooter] - If true, hides the default tour footer (Next/Back buttons).
+ * @property {String} [placement] - Floating UI placement string (e.g. 'bottom', 'right').
+ * @property {Boolean} [highlight] - If true, darkens the backdrop around the target element.
+ * @property {Object} [modalProps] - Props to pass to the modal (if target is omitted).
+ * @property {Object} [popoverProps] - Props to pass to the popover (if target is present).
+ * @property {Function} [onEnter] - Async hook called before the step is rendered.
+ */
+
+/**
+ * Creates the tour API methods used to control the tour lifecycle
+ * @param {Object} state - The reactive state object
+ * @returns {Object} Tour API object
+ */
+export const createApi = (state) => ({
+  /**
+   * Starts a new tour
+   * @param {Object} tour - The tour configuration object
+   * @param {TourStep[]} tour.steps - Array of steps for the tour
+   * @param {String} [tour.name] - Optional name for the tour
+   * @param {Object} [tour.modalProps] - Global props applied to all modal steps in this tour (can be overridden by step)
+   * @param {Object} [tour.popoverProps] - Global props applied to all popover steps in this tour (can be overridden by step)
+   */
+  async start(tour) {
+    if (!tour?.steps?.length) return;
+    await this._runHooks(tour.steps[0]);
+    state.active = markRaw(tour);
+    state.stepIndex = 0;
+  },
+  /**
+   * Advances the tour to the next step, or stops if it is the last step
+   */
+  async next() {
+    const active = state.active;
+    if (!active) return;
+    
+    if (state.stepIndex < active.steps.length - 1) {
+      const nextIndex = state.stepIndex + 1;
+      await this._runHooks(active.steps[nextIndex]);
+      state.stepIndex = nextIndex;
+    } else {
+      this.stop();
+    }
+  },
+  /**
+   * Returns the tour to the previous step
+   */
+  async prev() {
+    const active = state.active;
+    if (!active) return;
+    
+    if (state.stepIndex > 0) {
+      const prevIndex = state.stepIndex - 1;
+      await this._runHooks(active.steps[prevIndex]);
+      state.stepIndex = prevIndex;
+    }
+  },
+  /**
+   * Stops and closes the current tour
+   */
+  stop() {
+    state.active = null;
+    state.stepIndex = 0;
+  },
+  /**
+   * Internal method to run asynchronous lifecycle hooks on a step
+   * @param {Object} step - The tour step configuration
+   */
+  async _runHooks(step) {
+    if (step && typeof step.onEnter === 'function') {
+      await step.onEnter();
+    }
+  }
+});

package/lib/plugins/tour/index.js

@@ -0,0 +1,29 @@
+/**
+ * @module tourPlugin
+ */
+import { reactive } from 'vue';
+import UluTourDisplay from './UluTourDisplay.vue';
+import { createApi } from './api.js';
+import { useTour } from './useTour.js';
+
+export default function install(app) {
+  const state = reactive({
+    active: null,
+    stepIndex: 0
+  });
+  
+  const api = createApi(state);
+  
+  app.component("UluTourDisplay", UluTourDisplay);
+  
+  app.config.globalProperties.$uluTour = api;
+  app.config.globalProperties.$uluTourState = state;
+  
+  app.provide('uluTour', api);
+  app.provide('uluTourState', state);
+}
+
+export { useTour };
+export { default as UluTourDisplay } from './UluTourDisplay.vue';
+export { default as UluTourPager } from './UluTourPager.vue';
+export { default as UluTourContent } from './UluTourContent.vue';