@ulu/frontend-vue 0.1.0-beta.1

package/lib/plugins/modals/api.js

@@ -0,0 +1,76 @@
+import { ref, markRaw } from "vue";
+
+// Create array to be used internally to manage individual modals
+const modals = [];
+
+/**
+ * Reactive State Object (used inside global components)
+ */
+const state = ref({
+  /**
+   * Holds active component options (including component, and options)
+   */
+  active: null,
+  /**
+   * Populated with any props passed to open method, bound to modal component
+   */
+  activeProps: null,
+});
+
+/**
+ * Reactive data from state
+ */
+const data = state.value;
+
+export const modalsState = {
+  data,
+  modals,
+};
+
+export const createApi = (resolveModalOptions) => ({
+  open(name, props = null) {
+    const modal = this.get(name);
+    data.active = markRaw(modal);
+    data.activeProps = Object.assign({}, modal.props, props);
+  },
+  /**
+   * Close the active modal
+   * @param {String|Node} focusTo The element or selector for an element to programmatically focus after modal close
+   * @see https://www.deque.com/blog/accessible-routing-in-javascript-frameworks/
+   */
+  close() {
+    data.active = null;
+    data.activeProps = null;
+  },
+  /**
+   * Get a modal's config object by name
+   * @return {Object} Modal config object
+   */
+  get(name) {
+    const modal = modals.find(m => m.name === name);
+    if (modal) {
+      return modal;
+    } else {
+      throw new Error(`Unable to find modal named: ${ name }`);
+    }
+  },
+  /**
+   * Add a modal config
+   */
+  add(config) {
+    const resolved = resolveModalOptions(config);
+    modals.push(resolved);
+  },
+  /**
+   * Removes a modal config by name
+   * @return {Object} Modal that was removed
+   */
+  remove(name) {
+    const index = modals.findIndex(m => m.name === name);
+    if (index > -1) {
+      return modals.splice(index, 1);
+    } else {
+      warn("unable to find modal to remove");
+    }
+  }
+});

package/lib/plugins/modals/index.js

@@ -0,0 +1,60 @@
+/**
+ * @module plugins/modals/index.js
+ * @version 3.0.0
+ * Modals plugin (adds components, global registry, etc)
+ * - Updated version handles both independent and global registered/triggered modals
+ */
+
+import UluModalsDisplay from "./UluModalsDisplay.vue";
+import UluModal from "../../components/collapsible/UluModal.vue";
+import { createApi, modalsState } from "./api.js";
+
+/**
+ * Default plugin options
+ * @typedef {Object} UluModalsPluginOptions
+ * @property {String} componentNameDisplay Name for modals component that displays app-wide modals
+ * @property {String} componentNameModal Name for modal component
+ * @property {Array} modals Modals configs [{ name, component, props }]
+ * @property {UluModalOptions} modalOptions Options to merge into individual modal options (to serve as defaults for each modal, see UluModalOptions)
+ */
+const pluginDefaults = {
+  componentNameDisplay: "UluModalsDisplay",
+  componentNameModal: "UluModal",
+  modals: [],
+  modalOptions: {}
+};
+
+/**
+ * Modals Vue Plugin
+ * @param {Object} App Vue app instance passed to plugin
+ * @param {UluModalsPluginOptions} userOptions Options to change (see defaults)
+ */
+export default function install(app, userOptions) {
+  const options = Object.assign({}, pluginDefaults, userOptions);
+
+  // Merges in default modal config options on individual modal config
+  const resolveModalOptions = opts => Object.assign({}, options.modalOptions, opts);
+
+  const api = createApi(resolveModalOptions);
+
+  // Register the two global components
+  app.component(options.componentNameDisplay, UluModalsDisplay);
+  app.component(options.componentNameModal, UluModal);
+
+  // Create array to be used internally to manage individual modals
+  options.modals.forEach(config => {
+    api.add(config)
+  });
+
+  modalsState.options = options;
+
+  // Global property with API so user can interact with modals
+  app.config.globalProperties.$uluModals = api;
+  
+  // Provide the api for composition api usage
+  app.provide('uluModals', api);
+
+  // Global property for modals component to access state
+  // and for debugging logging if needed
+  app.config.globalProperties.$uluModalsState = modalsState;
+}

package/lib/plugins/modals/useModals.js

@@ -0,0 +1,9 @@
+import { inject } from 'vue';
+
+export const useModals = () => {
+  const modals = inject('uluModals');
+  if (!modals) {
+    throw new Error('Modals plugin not installed');
+  }
+  return modals;
+};

package/lib/plugins/popovers/UluPopover.vue

@@ -0,0 +1,189 @@
+<!-- NOTE: Need to rename classes when moving this into the library -->
+<template>
+  <button 
+    type="button" 
+    ref="trigger"
+    @click="toggle"
+    :disabled="disabled"
+    :class="[ 
+      { [activeClass] : isOpen }, 
+      classes.trigger 
+    ]"
+    :aria-expanded="isOpen ? 'true' : 'false'" 
+    :aria-controls="id" 
+    :aria-label="triggerAlt"
+    v-ulu-tooltip="tooltip ? tooltip : null"
+  >
+    <slot name="trigger" :isOpen="isOpen"/>
+  </button>
+  <span 
+    class="popover"
+    ref="content"
+    :class="[ 
+      size ? `popover--${ size }` : '',
+      { 
+        'popover--no-padding' : noPadding,
+        'is-active' : isOpen
+      }, 
+      classes.content,
+    ]"
+    :aria-hidden="isOpen ? 'false' : 'true'" 
+    :id="id" 
+    :style="floatingStyles"
+    :data-placement="placement"
+    @keydown.esc="changeTo(false)"
+    tabindex="-1"
+  >
+    <span class="popover__inner">
+      <slot name="content" :close="close"/>
+    </span>
+    <span v-if="$slots.footer" class="popover__footer">
+      <slot name="footer" :close="close"/>
+    </span>
+    <span 
+      v-if="config.arrow"
+      class="popover__arrow" 
+      ref="contentArrow"
+      :style="arrowStyles"
+      data-ulu-popover-arrow
+    ></span>
+  </span>
+</template>
+<script setup>
+  import { computed, ref, unref, nextTick } from "vue";
+  import { options as defaults } from "./manager.js";
+  import { newUid } from "./utils.js";
+  import { 
+    useFloating,
+    autoUpdate,
+    offset,
+    inline,
+    flip,
+    shift,
+    arrow,
+  } from "@floating-ui/vue";
+
+  const emit = defineEmits(["toggle"]);
+  const props = defineProps({
+    triggerAlt: String,
+    disabled: Boolean,
+    tooltip: String,
+    size: String,
+    noPadding: Boolean,
+    config: Object,
+    startOpen: Boolean,
+    activeClass: {
+      type: String,
+      default: "is-active"
+    },
+    classes: {
+      type: Object,
+      default: () => ({})
+    },
+    clickOutsideCloses: {
+      type: Boolean,
+      default: true
+    },
+    directFocus: {
+      type: Function,
+      default: ({ isOpen, content }) => {
+        if (isOpen) {
+          content.focus({ preventScroll: true });
+        }
+      }
+    }
+  });
+
+  const id = newUid();
+  const config = Object.assign({}, defaults.popover, props.config);
+  const isOpen = ref(props.startOpen || false);
+  const trigger = ref(null);
+  const content = ref(null);
+  const contentArrow = ref(null);
+
+  const middleware = [
+    ...(config.inline ? [ inline() ] : []),
+    ...(config.offset ? [ offset(config.offset) ] : []),
+    flip(), 
+    shift(),
+    ...(config.arrow ? [ arrow({ element: contentArrow }) ] : []),
+  ];
+  const options = {
+    placement: config.placement,
+    whileElementsMounted: autoUpdate,
+    middleware
+  }; 
+  
+  const { 
+    floatingStyles, 
+    placement, 
+    middlewareData,
+    update,
+    isPositioned,
+  } = useFloating(trigger, content, options);
+
+  const arrowStyles = computed(() => {
+    const pos = middlewareData.value?.arrow;
+    if (!pos) return null;
+    return {
+      position: "absolute",
+      left: pos?.x != null ? `${ pos.x }px` : "",
+      top: pos?.y != null ? `${ pos.y }px` : "",
+    };
+  });
+
+  if (config.onReady) {
+    config.onReady({ update, isPositioned });
+  }
+
+  const toggle = () => {
+    changeTo(!isOpen.value);
+  };
+
+  const changeTo = (toOpen) => {
+    isOpen.value = toOpen;
+    const focusArgs = { 
+      trigger: unref(trigger), 
+      content: unref(content), 
+      isOpen: unref(isOpen) 
+    };
+    const eventArgs = { isOpen: focusArgs.isOpen };
+    nextTick(() => {
+      if (isOpen.value) {
+        update();
+        // Push to next event, without this will get triggered by the original click event
+        window.setTimeout(() => {
+          addOutsideClick();
+          props.directFocus(focusArgs);
+          emit("toggle", eventArgs);
+        }, 0);
+      } else {
+        destroyOutsideClick();
+        props.directFocus(focusArgs);
+        emit("toggle", eventArgs);
+      }
+    });
+  };
+  
+  let outsideHandler;
+  const addOutsideClick = () => {
+    if (props.clickOutsideCloses) {
+      if (outsideHandler) {
+        destroyOutsideClick();
+      }
+      outsideHandler = event => {
+        if (!content.value.contains(event.target)) {
+          changeTo(false);
+        }
+      };
+      document.addEventListener("click", outsideHandler);
+    }
+  };
+  const destroyOutsideClick = () => {
+    if (outsideHandler) {
+      document.removeEventListener("click", outsideHandler);
+      outsideHandler = null;
+    }
+  };
+  const close = () => changeTo(false);
+</script>

package/lib/plugins/popovers/UluTooltipDisplay.vue

@@ -0,0 +1,15 @@
+<!-- 
+  Note: 
+  Using the name TooltipDisplay incase we want to create abstract 
+  component (wrapper, renderless, etc) in the future 
+-->
+<template>
+  <Teleport :to="options.plugin.tooltipTeleportTo">
+    <TooltipPopover v-if="active" :config="activeConfig"/>
+  </Teleport>
+</template>
+
+<script setup>
+  import { active, activeConfig, options } from "./manager.js";
+  import TooltipPopover from "./UluTooltipPopover.vue";
+</script>

package/lib/plugins/popovers/UluTooltipPopover.vue

@@ -0,0 +1,83 @@
+<!-- NOTE: Need to rename classes when moving this into the library -->
+<template>
+  <span 
+    class="popover popover--tooltip is-active"
+    ref="content"
+    aria-hidden="true" 
+    :data-placement="placement"
+    :class="config.class"
+    :style="floatingStyles"
+  >
+    <span 
+      v-if="config.isHtml" 
+      class="popover__inner" 
+      v-html="config.content"
+    >
+    </span>
+    <span v-else class="popover__inner">
+      {{ config.content }}
+    </span>
+    <span 
+      v-if="config.arrow"
+      class="popover__arrow" 
+      ref="contentArrow"
+      :style="arrowStyles"
+    ></span>
+  </span>
+</template>
+
+<script setup>
+  import { ref, toRef, computed } from "vue";
+  import { 
+    useFloating,
+    autoUpdate,
+    offset,
+    inline,
+    flip,
+    shift,
+    arrow,
+  } from "@floating-ui/vue";
+
+  const { config } = defineProps({
+    config: Object
+  });
+  const trigger = toRef(config.trigger);
+  const content = ref(null);
+  const contentArrow = ref(null);
+  const middleware = [
+    ...(config.inline ? [ inline() ] : []),
+    ...(config.offset ? [ offset(config.offset) ] : []),
+    flip(), 
+    shift(),
+    ...(config.arrow ? [ arrow({ element: contentArrow }) ] : []),
+  ];
+  
+  const options = {
+    placement: config.placement,
+    whileElementsMounted: autoUpdate,
+    middleware
+  }; 
+
+  const { 
+    floatingStyles, 
+    placement, 
+    middlewareData,
+    update,
+    isPositioned,
+  } = useFloating(trigger, content, options);
+
+  const arrowStyles = computed(() => {
+    const pos = middlewareData.value?.arrow;
+    if (!pos) return null;
+    return {
+      position: "absolute",
+      left: pos?.x != null ? `${ pos.x }px` : "",
+      top: pos?.y != null ? `${ pos.y }px` : "",
+    };
+  });
+
+  if (config.onReady) {
+    config.onReady({ update, isPositioned });
+  }
+
+</script>

package/lib/plugins/popovers/defaults.js

@@ -0,0 +1,108 @@
+export default {
+  /**
+   * Default Plugin Options
+   * @type {Object}
+   */  
+  plugin: {
+    /**
+     * Whether to install all components globally in Vue and add the directive for
+     * tooltips globally in Vue
+     */
+    global: true,
+    /**
+     * The directive name to use (default 'tooltip' = <el v-ulu-tooltip="'hello world'">)
+     * @type {String}
+     */
+    directiveName: "ulu-tooltip",
+    /**
+     * The element that the tooltip should be rendered within
+     * - Default bottom of the body (on top of everything)
+     * - Doesn't need to be inline for accessibility since tooltips are just an enhancement
+     *   content displayed within them should be hidden for assistive devices, 
+     *   they are not visible to assistive devices
+     * @type {String}
+     */    
+    tooltipTeleportTo: "body",
+  },
+  /**
+   * Default Popover Options
+   */
+  popover: {
+    /**
+    * Include the floating-ui inline middleware (for inline elements that wrap)
+    * @type {Boolean}
+    */
+    inline: true,
+    /**
+    * Delay when using the directive
+    * @type {Number}
+    */
+    delay: 500,
+    /**
+    * Placement for floating-ui)
+    * @type {String}
+    */    
+    placement: "bottom", 
+    /**
+    * Strategy for floating-ui (strategy)
+    * @type {String}
+    */
+    strategy: "absolute",
+    /**
+    * Include the floating-ui offset middleware, 
+    * @type {Number}
+    */
+    offset: 16,
+    /**
+    * Include the floating-ui arrow middleware
+    * @type {Boolean}
+    */
+    arrow: true,
+  },
+  /**
+   * Default Tooltip Options
+   * @type {Object}
+   */
+  tooltip: {
+    /**
+     * Optional class binding for tooltip element
+     * @type {String|Object|Array}
+     */
+    class: null,
+    /**
+     * Events to show tooltip on
+     * @type {Array.<String>}
+     */    
+    showEvents: ["pointerenter", "focus"],
+    /**
+     * Events to hide tooltip on
+     * @type {Array.<String>}
+     */
+    hideEvents: ["pointerleave", "blur"],
+    /**
+     * Content should be output as plain HTML (ie v-html)
+     * - Note don't include interactive elements in tooltips!
+     * @type {Boolean}
+     */
+    isHtml: false,
+    /**
+     * Element for floating ui to use as reference (can be virtual) or vue ref to element
+     * @type {Node|Object}
+     */
+    trigger: null,
+    /**
+     * The content of the tooltip (String, Reactive ref or HTML [see isHtml option])
+     * @type {String|Object}
+     */
+    content: null,
+    /**
+     * Delay when using the directive
+     * @type {Number}
+     */
+    delay: 500,
+    /**
+     * Callback that is passed { update, isPositioned } for manual things
+     */
+    onReady: null,
+  },
+};

package/lib/plugins/popovers/directive.js

@@ -0,0 +1,95 @@
+import { show, hide, createConfig } from "./manager.js";
+/**
+ * Using weak map for listener to element relationship
+ * - As an extra fallback to remove listeners without affecting garabage collection
+ * - The unmount should be called for every element the directive is bound to but
+ */
+const cache = new WeakMap();
+/**
+ * - We should consider allowing components to be passed for markup
+ * - don't want to use a component as then everything that uses this will have complicated conditionals
+ *   ie. menu component could just have an option to bind the directive but if component needs conditional when not being used
+ */
+/**
+ * Directive Object
+ */
+export default {
+  mounted(trigger, binding) {
+    setup(trigger, binding);
+  },
+  beforeUpdate(trigger) {
+    removeListeners(trigger);
+  },
+  updated(trigger, binding) {
+    setup(trigger, binding);
+  },
+  umounted(trigger) {
+    removeListeners(trigger);
+  }
+};
+/**
+ * Resolves the users local config and attaches handlers
+ */
+function setup(trigger, binding) {
+  const config = resolveConfig(trigger, binding);
+  if (!config) return;
+  let tid = null;
+  
+  const onShow = () => { 
+    if (tid) return;
+    tid = setTimeout(() => {
+      show(config);
+      clearTimeout(tid);
+    }, config.delay);
+  };
+
+  const onHide = () => { 
+    if (tid) {
+      clearTimeout(tid);
+      tid = null;
+    }
+    hide(config);
+  };
+
+  config.showEvents.forEach(eventName => {
+    trigger.addEventListener(eventName, onShow);
+  });
+  config.hideEvents.forEach(eventName => {
+    trigger.addEventListener(eventName, onHide);
+  });
+  cache.set(trigger, { onShow, onHide, config });
+}
+/**
+ * Removes an elements listeners by checking agains local cache map
+ */
+function removeListeners(trigger) {
+  if (!cache.has(trigger)) {
+    return;
+  }
+  const { config, onShow, onHide } = cache.get(trigger);
+  config.showEvents.forEach(eventName => {
+    trigger.removeEventListener(eventName, onShow);
+  });
+  config.hideEvents.forEach(eventName => {
+    trigger.removeEventListener(eventName, onHide);
+  });
+  cache.delete(trigger);
+}
+/**
+ * Allow user to provide a simple string for the content of the toolkit
+ * or the extended object syntax. This resolves to the object syntax
+ */
+function resolveConfig(trigger, binding) {
+  const { value } = binding;
+  let config;
+  if (value === false || value === null) {
+    return; // Disabled
+  } else if (typeof value === "object") {
+    config = value;
+  // String/Number, etc (displayed as is)
+  } else {
+    config = { content: value };
+  }
+  // Using assign so users can override trigger if needed
+  return createConfig(Object.assign({}, { trigger }, config));
+}

package/lib/plugins/popovers/index.js

@@ -0,0 +1,18 @@
+import { init } from "./manager.js";
+import directive from "./directive.js";
+import UluPopover from "./UluPopover.vue";
+import UluTooltipDisplay from "./UluTooltipDisplay.vue";
+
+/**
+ * Install plugin
+ * - Set user options
+ * - Add the global directive for the user to trigger tooltips
+ */
+export default function install(app, userOptions = {}) {
+  const options = init(userOptions);
+  if (options.plugin.global) {
+    app.directive(options.plugin.directiveName, directive);
+    app.component("UluTooltipDisplay", UluTooltipDisplay);
+    app.component("UluPopover", UluPopover);
+  }
+}