@ulu/frontend-vue 0.1.0-beta.1

package/lib/components/visualizations/UluAnimateNumber.vue

@@ -0,0 +1,32 @@
+<template>
+  <span><slot :currentValue="currentValue">{{ currentValue }}</slot></span>
+</template>
+
+<script>
+  import gsap from "gsap";
+  export default {
+    name: 'AnimateNumber',
+    props: {
+      /**
+       * Number to animate as it changes
+       */
+      value: Number
+    },
+    watch: {
+      value() {
+        gsap.to(this, {
+          tweenValue: this.value,
+          onUpdate: () => {
+            this.currentValue = Math.ceil(this.tweenValue);
+          },
+        });
+      },
+    },
+    data() {
+      return {
+        currentValue: this.value,
+        tweenValue: this.value,
+      };
+    },
+  }
+</script>

package/lib/components/visualizations/UluProgressBar.vue

@@ -0,0 +1,94 @@
+<template>
+  <div 
+    class="progress-bar"
+    :class="{
+      'progress-bar--small' : small,
+      'progress-bar--icon-left' : iconOnLeft,
+      'type-small' : small
+    }"
+  >
+    <div class="progress-bar__header">
+      <strong 
+        class="progress-bar__label" 
+        :class="{ 
+          'type-normal' : small,
+          'hidden-visually' : labelHidden,
+        }"
+      >
+        {{ label }}
+      </strong>
+      <div v-if="status" class="progress-bar__icon">
+        <StatusIcon :type="status.type" />
+        <span class="hidden-visually">{{ status.message }}</span>
+      </div>
+    </div>
+    <div class="progress-bar__track">
+      <div 
+        class="progress-bar__bar"
+        :style="`width: ${ percentage }%`"
+      ></div>
+      <div 
+        v-if="deficit"
+        class="progress-bar__bar--deficit"
+        :style="`width: ${ defPercentage }%`"
+      ></div>
+    </div>
+    <div class="progress-bar__values">
+      <div class="progress-bar__value progress-bar__value--amount">
+        <strong class="hidden-visually">Amount:</strong>
+        {{ amount }}
+      </div>
+      <div 
+        v-if="deficit > 0" 
+        class="progress-bar__value progress-bar__value--deficit color-status is-danger"
+      >
+        <strong class="hidden-visually">Deficit: </strong>
+        -{{ deficit }}
+      </div>
+      <div class="progress-bar__value progress-bar__value--total">
+        <strong class="hidden-visually">Total:</strong>
+        {{ total }}
+      </div>
+    </div>
+  </div>
+</template>
+
+<script>
+  export default {
+    name: 'ProgressBar',
+    props: {
+      small: Boolean,
+      label: {
+        type: String,
+        default: "Progress"
+      },
+      labelHidden: Boolean,
+      total: Number,
+      deficit: Number,
+      amount: Number,
+      iconOnLeft: Boolean
+    },
+    computed: {
+      percentage() {
+        const { amount, total } = this;
+        return amount / total * 100;
+      },
+      defPercentage() {
+        const { deficit, total } = this;
+        return deficit ? deficit / total * 100 : 0;
+      },
+      isComplete() {
+        return this.amount >= this.total;
+      },
+      status() {
+        return this.isComplete ? {
+          type: "success",
+          message: "Item Completed"
+        } : this.deficit ? {
+          type: "danger",
+          message: "Item Has Deficit"
+         } : null;
+      }
+    }
+  }
+</script>

package/lib/components/visualizations/UluProgressDonut.vue

@@ -0,0 +1,97 @@
+<template>
+  <div 
+    class="progress-donut" 
+    :class="{ 
+      'progress-donut--small' : small,
+      'progress-donut--small-below' : smallBelow,
+      'progress-donut--status-low' : !neutral && percentage < 30,
+      'progress-donut--status-incomplete' : !neutral && percentage >= 30 && percentage < 100,
+      'progress-donut--status-complete' : !neutral && percentage >= 100,
+    }"
+  >
+    <strong class="hidden-visually">Course Progress</strong>
+    <div class="progress-donut__chart">
+      <!-- Added the 1% extra to 100% becasuse sometimes it renders with a tiny gap -->
+      <svg class="progress-donut__chart-svg" viewBox="0 0 32 32">
+        <circle 
+          class="progress-donut__chart-pie" 
+          ref="pie"
+          r="16" 
+          cx="16" 
+          cy="16"
+          :style="{ strokeDasharray: endDasharray }"
+        />
+        <circle 
+          class="progress-donut__chart-mask" 
+          :r="small ? 7 : 11" 
+          cx="16" 
+          cy="16" 
+        />
+      </svg>
+      <strong v-if="!small" class="progress-donut__chart-value">
+        {{ percentage }}%
+      </strong>
+    </div>
+    <!-- The valus is shown to the side or below when small mode -->
+    <strong v-if="small" class="progress-donut__value type-small-x">
+      {{ percentage }}%
+    </strong>
+  </div>
+</template>
+
+<script>
+  let counter = 0;
+  export default {
+    name: 'ProgressDonut',
+    props: {
+      percentage: {
+        type: Number,
+        default: 0
+      },
+      small: Boolean,
+      smallBelow: Boolean,
+      neutral: Boolean,
+      duration: {
+        type: Number,
+        default: 500
+      },
+      easing: {
+        type: String,
+        default: "ease-in"
+      }
+    },
+    data() {
+      return {
+        uid: `progress-donut-${ ++counter }`
+      }
+    },
+    watch: {
+      // Need to reanimate if value changes
+      percentage(newVal, oldVal) {
+        if (newVal !== oldVal) {
+          this.animate(this.normalize(oldVal));
+        }
+      }
+    },
+    computed: {
+      endDasharray() {
+        return `${ this.normalize(this.percentage) } 100`;
+      }
+    },
+    methods: {
+      normalize(percentage) {
+        return percentage === 100 ? 101 : percentage;
+      },
+      animate(from = 0) {
+        const { pie } = this.$refs;
+        if (!pie.animate) return; // No Animation API
+        const { duration, easing, endDasharray } = this;
+        const keyframes = { strokeDasharray: [`${ from } 100`, endDasharray] };
+        pie.animate(keyframes, { duration, easing, fill: "forwards" });
+      }
+    },
+    mounted() {
+      this.animate();
+    }
+  }
+</script>

package/lib/composables/index.js

@@ -0,0 +1,10 @@
+/**
+ * @module composables/index.js
+ * Responsible for exporting all composables
+ * - Used in bundle exports
+ */
+
+export { useIcon } from './useIcon.js';
+export { useModifiers } from './useModifiers.js';
+export { useWindowResize } from './useWindowResize.js';
+export { useBreakpointManager } from './useBreakpointManager.js';

package/lib/composables/useBreakpointManager.js

@@ -0,0 +1,68 @@
+import { ref, markRaw } from "vue";
+import { isBrowser } from "@ulu/utils/browser/dom.js";
+
+const defaults = {
+  /**
+   * Set an initial value (value in mounted, SSR)
+   */
+  initialValue: null,
+  /**
+   * Function called after init (passed manager)
+   */
+  onReady: null,
+  /**
+   * Options sent to CssBreakpoints library
+   */
+  plugin: {
+    customProperty: "--breakpoint"
+  }
+};
+
+/**
+ * Use the CssBreakpoints module in Vue
+ * - Normally use only once, unless you have different sets of breakpoints
+ * @param {Object} options Configuration options overrides
+ * @return {Object} { manager, active, direction } (all are null in SSR environment until init)
+ */
+export function useBreakpointManager(options) {
+  const config = Object.assign({}, defaults, options);
+
+  const breakpointManager = ref(null);
+  const breakpointActive = ref(config.initialValue);
+  const breakpointDirection = ref(null);
+
+  const init = async () => {
+    if (!isBrowser()) return;
+
+    // Wait for the DOM to be ready before initializing the breakpoint manager
+    await new Promise(resolve => {
+      if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', () => resolve());
+      } else {
+        resolve();
+      }
+    });
+
+    const mod = await import("@ulu/frontend/js/ui/breakpoints.js");
+    const { BreakpointManager } = mod;
+    const manager = markRaw(new BreakpointManager(config.plugin));
+    
+    breakpointManager.value = markRaw(manager);
+    
+    const setValues = () => {
+      breakpointActive.value = manager.active;
+      breakpointDirection.value = manager.resizeDirection;
+    };
+    
+    setValues();
+    if (config.onReady) {
+      config.onReady(manager);
+    }
+    manager.onChange(setValues);
+  };
+
+  // Initialize automatically
+  init();
+
+  return { breakpointManager, breakpointActive, breakpointDirection };
+}

package/lib/composables/useIcon.js

@@ -0,0 +1,62 @@
+/**
+ * Utility composable for handling and formatting icon props for UluIcon.
+ * @returns {Object} An object with utility functions { getIconProps, getClassesFromDefinition }
+ */
+export function useIcon() {
+  const getIconProps = (definition) => {
+    if (!definition) return null;
+    if (typeof definition === 'object' && !Array.isArray(definition)) {
+      // If it's already an object (and not an array), assume it's directly props
+      return definition;
+    }
+    // Otherwise, treat it as the 'icon' prop
+    return { icon: definition };
+  };
+
+  /**
+   * Converts an icon definition (string, array, or object) into a string of FontAwesome classes.
+   * @param {String|Array|Object} definition - The icon definition.
+   * @returns {String|null} A string of FontAwesome classes, or null if unable to parse.
+   */
+  const getClassesFromDefinition = (definition) => {
+    if (!definition) {
+      return null;
+    }
+
+    // If definition is already a string (e.g., "fas fa-home")
+    if (typeof definition === "string") {
+      return definition;
+    }
+
+    // If definition is an array (e.g., ["fas", "home"])
+    if (Array.isArray(definition)) {
+      // FontAwesome's component expects ['fas', 'home'], but for classes,
+      // we need to join them. Assuming the first element is the style prefix.
+      if (definition.length >= 2) {
+        // Common case: ['fas', 'home'] -> 'fas fa-home'
+        return `${definition[0]} fa-${definition[1]}`;
+      }
+      // Handle edge cases or just return the first if it's the only one
+      // e.g., ['fas'] might result in just 'fas' which isn't a full icon, but handles the edge
+      return definition.join(' ');
+    }
+
+    // If definition is an object (e.g., { icon: ['fas', 'home'] } or { icon: 'fas fa-home' })
+    if (typeof definition === 'object' && definition.icon) {
+      if (typeof definition.icon === 'string') {
+        return definition.icon;
+      }
+      if (Array.isArray(definition.icon)) {
+        if (definition.icon.length >= 2) {
+          return `${definition.icon[0]} fa-${definition.icon[1]}`;
+        }
+        return definition.icon.join(' ');
+      }
+    }
+
+    console.warn("useIcon: Unable to parse definition for static FontAwesome classes:", definition);
+    return null;
+  };
+
+  return { getIconProps, getClassesFromDefinition };
+}

package/lib/composables/useModifiers.js

@@ -0,0 +1,93 @@
+/**
+ * @module composables/useModifiers
+ * Handles user modifiers prop and internal modifiers for a given component
+ */
+
+import { computed, toRefs, toValue } from "vue";
+import { normalizeClasses } from "@ulu/utils/templating.js";
+
+/**
+ * A composable to manage and resolve BEM style modifiers for a component,
+ * combining user-passed modifiers with internally derived conditional modifiers.
+ *
+ * @param {object} options - The options for the composable.
+ * @param {object} options.props - The component's props object. (Must contain a 'modifiers' prop if user-passed modifiers are expected)
+ * @param {string | import('vue').Ref<string>} options.baseClass - The base CSS class name for the component (e.g., 'modal').
+ * Can be a string or a ref to a string.
+ * @param {string | string[] | Object.<string, any> | import('vue').ComputedRef<string | string[] | Object.<string, any>>} [options.internal={}] -
+ * A flexible input for component's internal modifiers. Can be a string, array of strings/objects, or an object mapping modifier names to conditions.
+ * @returns {object} An object containing the computed property `resolvedModifiers`
+ * 
+ * @example
+ * // In MyComponent.vue:
+ * <template>
+ * <div :class="[resolvedModifiers, 'other-class']"></div>
+ * </template>
+ *
+ * <script>
+ * import { computed, ref } from 'vue';
+ * import { useModifiers } from './composables/useModifiers.js'; // Adjust path
+ *
+ * export default {
+ *   props: {
+ *     variant: String, // e.g., 'primary', 'secondary'
+ *     isActive: Boolean,
+ *     modifiers: [String, Array, Object] // User-passed modifiers
+ *   },
+ *   setup(props) {
+ *     const isHovered = ref(false);
+ *
+ *     // Define component-internal modifiers based on props or local state
+ *     const internalModifiers = computed(() => ({
+ *       [props.variant]: !!props.variant, // Add 'primary' or 'secondary' if prop exists
+ *       'active': props.isActive, // Add 'active' if isActive prop is true
+ *       'hovered': isHovered.value, // Add 'hovered' if local state is true
+ *       'default': !props.variant && !props.isActive // Add 'default' if no variant/active
+ *     }));
+ *
+ *     // Use the composable to get the combined modifier classes
+ *     const { resolvedModifiers } = useModifiers({
+ *       props: props, // Pass component props for 'modifiers' prop
+ *       baseClass: 'button', // The BEM block name
+ *       internal: internalModifiers // The computed internal modifiers
+ *     });
+ *
+ *     return { resolvedModifiers, isHovered };
+ *   }
+ * };
+ * </script>
+ *
+ * // Resulting class examples for 'my-component':
+ * // <MyComponent />                       => class="my-component my-component--default"
+ * // <MyComponent variant="primary" />     => class="my-component my-component--primary"
+ * // <MyComponent isActive />              => class="my-component my-component--active"
+ * // <MyComponent modifiers="condensed" /> => class="my-component my-component--default my-component--condensed"
+ * // <MyComponent variant="secondary" :isActive="true" modifiers="round" />
+ * //   => class="my-component my-component--secondary my-component--active my-component--round"
+ */
+export function useModifiers({ props, baseClass, internal = {} }) {
+  // Use toRefs to destructure props to maintain reactivity for `modifiers`
+  // Ensure props has a 'modifiers' property, or handle its absence
+  const { modifiers } = toRefs(props);
+
+  const resolvedModifiers = computed(() => {
+    const resolvedBase = toValue(baseClass);
+    
+    // Normalize both userModifiers and internal using the helper
+    const userModifiers = normalizeClasses(toValue(modifiers));
+    const internalModifiers = normalizeClasses(toValue(internal));
+
+    if (!resolvedBase) {
+      console.warn("useModifiers: Missing 'baseClass' argument, modifiers will not be applied.");
+      return '';
+    }
+
+    // Combine all active modifiers into one Set
+    const all = new Set([...internalModifiers, ...userModifiers]);
+
+    // Join all collected modifiers
+    return Array.from(all).map(modifier => `${ resolvedBase }--${ modifier }`);
+  });
+
+  return { resolvedModifiers };
+}

package/lib/composables/useWindowResize.js

@@ -0,0 +1,64 @@
+/**
+ * Reusable window resize
+ * - Future could have request animation frame throttled onResize
+ *   - Just start and end for now, until thats needed
+ */
+import { ref } from "vue";
+import { debounce } from "@ulu/utils/performance.js";
+const resizing = ref(false);
+const callbacks = {
+  start: [],
+  end: []
+};
+// Method is to add a resize handler just for the first call (start)
+// which removes itself, the end (debounced) will be called after resizing
+// stops at which point it will add the start handler to repeat the process
+// Debounced end handler never needs to be removed.
+function onStart() {
+  window.removeEventListener("resize", onStart);
+  resizing.value = true;
+  callbacks.start.forEach(cb => cb());
+}
+function onEnd() {
+  resizing.value = false;
+  callbacks.end.forEach(cb => cb());
+  window.addEventListener("resize", onStart);
+}
+
+// Only allow in browser contexts
+if (!import.meta.env.SSR) {
+  window.addEventListener("resize", onStart);
+  window.addEventListener("resize", debounce(onEnd, 300));
+}
+
+/**
+ * 
+ * @param {Array} array Internal callback array to put callback in
+ * @param {*} callback Users callback
+ * @returns {Function} Remove Function
+ */
+function register(array, callback) {
+  array.push(callback);
+  return () => {
+    const index = array.findIndex(cb => cb === callback);
+    if (index > -1) {
+      array.splice(index);
+    }
+  };
+}
+
+/**
+ * Composable function
+ * @return {Object} Contains reactive 'resizing' and two methods for calling callbacks (onResizeStart, onResizeEnd)
+ */
+export function useWindowResize() {
+  return {
+    resizing,
+    onResizeStart(callback) {
+      return register(callbacks.start, callback);
+    },
+    onResizeEnd(callback) {
+      return register(callbacks.end, callback);
+    }
+  };
+}

package/lib/index.js

@@ -0,0 +1,10 @@
+/**
+ * @module index.js
+ * - Main library entrypoint
+ * - Exports everything
+ */
+
+export * from './plugins/index.js';
+export * from './components/index.js';
+export * from './composables/index.js';
+export * from './settings.js';

package/lib/plugins/_index.scss

@@ -0,0 +1,7 @@
+////
+/// @group index
+/// Forwards all plugins
+////
+
+
+@forward "toast/toast" as toast-*;

package/lib/plugins/breakpoints/index.js

@@ -0,0 +1,47 @@
+import { ref, computed } from "vue";
+import { useBreakpointManager } from "../../composables/useBreakpointManager.js";
+
+/**
+ * Plugin Options
+ */
+const defaults = {
+  /**
+   * Breakpoint for mobile down/max
+   */
+  breakpointMobile: "small",
+  /**
+   * Options to pass to useBreakpointManager()
+   */
+  managerOptions: {}
+};
+
+export default function install(app, userOptions) {
+  const isMobile = ref(false);
+  const options = Object.assign({}, defaults, userOptions);
+  const { breakpointMobile } = options;
+  const { onReady: userOnReady } = options.managerOptions;
+
+  // Setup breakpoint manager options but insert our own onReady (create flag for mobile)
+  const pluginManagerOptions = { 
+    onReady(manager) {
+      manager.at(breakpointMobile).max({
+        on() { isMobile.value = true; },
+        off() { isMobile.value = false; }
+      });
+      if (userOnReady) userOnReady(manager);
+    }
+  };
+
+  const managerOptions = Object.assign({}, options.managerOptions, pluginManagerOptions);
+
+  const {
+    breakpointManager,
+    breakpointActive,
+    breakpointDirection
+  } = useBreakpointManager(managerOptions);
+
+  app.provide("uluBreakpointActive", computed(() => breakpointActive.value));
+  app.provide("uluBreakpointDirection", computed(() => breakpointDirection.value));
+  app.provide("uluBreakpointManager", computed(() => breakpointManager.value));
+  app.provide("uluIsMobile", computed(() => isMobile.value));
+}

package/lib/plugins/index.js

@@ -0,0 +1,11 @@
+/**
+ * @module plugins/index.js
+ * Responsible for exporting all plugins
+ * - Used in bundle exports
+ */
+
+
+export { default as popoversPlugin } from './popovers/index.js';
+export { default as modalsPlugin } from './modals/index.js';
+export { default as toastPlugin } from './toast/index.js';
+export { default as breakpointsPlugin } from './breakpoints/index.js';

package/lib/plugins/modals/UluModalsDisplay.vue

@@ -0,0 +1,59 @@
+<template>
+  <component 
+    v-if="currentModal" 
+    :is="currentModal.component"
+    v-bind="currentProps"
+    v-model="open"
+    @vue:mounted="modalMounted"
+    @vue:unmounted="modalUnmounted"
+  />
+</template>
+
+<script>
+  export default {
+    name: "UluModalsDisplay",
+    emits: [
+      "modal-unmount",
+      "modal-mount"
+    ],
+    data() {
+      return {
+        open: false
+      };
+    },
+    computed: {
+      currentModal() {
+        return this.$uluModalsState.data?.active;
+      },
+      currentProps() {
+        return this.$uluModalsState.data?.activeProps;
+      }
+    },
+    watch: {
+      // Watch for changes in the global state (e.g., when $uluModals.open() is called)
+      currentModal(newValue) {
+        if (newValue) {
+          this.open = true;
+        } else {
+          this.open = false;
+        }
+      },
+      // Watch for changes in the local state (e.g., when the modal emits 'update:modelValue')
+      open(newValue) {
+        if (!newValue && this.currentModal) {
+          this.$uluModals.close();
+        }
+      }
+    },
+    methods: {
+      modalMounted() {
+        this.$emit("modal-mount", { modal: this.currentModal });
+      },
+      modalUnmounted() {
+        this.$nextTick(() => {
+          this.$emit("modal-unmount");
+        });
+      }
+    }
+  };
+</script>