@ulu/frontend-vue 0.1.0-beta.2 → 0.1.0-beta.21

package/lib/components/systems/facets/useFacets.js

@@ -0,0 +1,221 @@
+import { ref, computed, watch } from 'vue';
+import Fuse from 'fuse.js';
+
+/**
+ * Generates facet groups and their possible values from a list of items.
+ * @param {Array<Object>} allItems - The full list of items.
+ * @param {Array<Object>} facetFields - Configuration for which fields to create facets from.
+ * @returns {Array<Object>} The generated facet structure.
+ */
+function generateInitialFacets(allItems, facetFields) {
+  if (!facetFields || !Array.isArray(facetFields)) return [];
+  return facetFields.map(group => {
+    const allValues = new Set();
+    const getValue = group.getValue || (item => item[group.uid]);
+
+    allItems.forEach(item => {
+      const value = getValue(item);
+      if (Array.isArray(value)) {
+        value.forEach(v => v && allValues.add(v));
+      } else if (value) {
+        allValues.add(value);
+      }
+    });
+
+    const getLabel = group.getLabel || (value => value);
+
+    return {
+      ...group,
+      children: [...allValues].sort().map(value => ({
+        uid: value,
+        label: getLabel(value),
+        selected: false
+      }))
+    };
+  });
+}
+
+
+/**
+ * A composable for handling client-side faceted search, filtering, and sorting.
+ * @param {import('vue').Ref<Array<Object>>} allItems - A Vue ref containing the full list of items to be processed.
+ * @param {Object} options - Configuration options for the composable.
+ * @param {Array} [options.initialFacets] - The initial configuration for the facets. Can be generated automatically if `facetFields` is provided.
+ * @param {Array} [options.facetFields] - A simpler configuration to automatically generate facets from items. Each item can have `uid`, `name`, `open`, `getValue` and `getLabel`.
+ * @param {String} [options.initialSearchValue=''] - The initial value for the search input.
+ * @param {String} [options.initialSortType='az'] - The initial sort type.
+ * @param {Boolean} [options.noDefaultSorts=false] - If true, the default 'A-Z' and 'Z-A' sorts will not be included.
+ * @param {Object} [options.extraSortTypes={}] - Additional sort types to be merged with the default ones.
+ * @param {Object} [options.searchOptions={}] - Configuration options for Fuse.js.
+ * @param {Function} [options.getItemFacet] - A function to retrieve facet information from an item. Should always return an array of values.
+ * @param {Function} [options.getSortValue] - A function to get the value to sort by from an item.
+ */
+export function useFacets(allItems, options = {}) {
+  const defaultGetItemFacet = (item, uid) => {
+    const value = item[uid];
+    if (value === null || typeof value === 'undefined') return [];
+    return Array.isArray(value) ? value : [value];
+  };
+
+  const {
+    initialFacets,
+    facetFields,
+    initialSearchValue = '',
+    initialSortType = 'az',
+    noDefaultSorts = false,
+    extraSortTypes = {},
+    searchOptions: initialSearchOptions = {},
+    getItemFacet = defaultGetItemFacet,
+    getSortValue = item => (item.title || item.label || "")
+  } = options;
+
+  const sortAlpha = items => {
+    return items.sort((a, b) => {
+      const va = getSortValue(a);
+      const vb = getSortValue(b);
+      if (va && vb) {
+        return String(va).localeCompare(String(vb));
+      } else {
+        return va ? -1 : vb ? 1 : 0;
+      }
+    });
+  }
+  const defaultSorts = {
+    az: { text: "A-Z", sort: sortAlpha },
+    za: { text: "Z-A", sort: items => sortAlpha(items).reverse() },
+  };
+
+  // --- Helpers ---
+  function createFacets(initial) {
+    return (initial || []).map(group => ({
+      ...group,
+      open: group.open || false,
+      children: group.children.map(facet => ({
+        ...facet,
+        selected: facet.selected || false
+      })),
+      selectedCount: 0
+    }));
+  }
+
+  const generatedFacets = computed(() => {
+    if (!facetFields || !allItems.value?.length) return null;
+    return generateInitialFacets(allItems.value, facetFields);
+  });
+
+  // --- State ---
+  const facets = ref(createFacets(initialFacets || generatedFacets.value));
+  const searchValue = ref(initialSearchValue);
+  const selectedSort = ref(initialSortType);
+
+  // If using facetFields, watch for changes in items and regenerate facets
+  if (facetFields && !initialFacets) {
+    watch(generatedFacets, (newGeneratedFacets) => {
+      facets.value = createFacets(newGeneratedFacets);
+    });
+  }
+
+  // --- Computed ---
+  const sortTypes = computed(() => ({
+    ...(noDefaultSorts ? {} : defaultSorts),
+    ...extraSortTypes
+  }));
+
+  const searchOptions = computed(() => ({
+    shouldSort: true,
+    keys: ["title", "label", "description", "author"],
+    ...initialSearchOptions
+  }));
+
+  const selectedFacets = computed(() => {
+    const selected = [];
+    facets.value.forEach((group) => {
+      const { name, uid, children } = group;
+      let count = 0;
+      let added = false;
+      if (children) {
+        children.forEach(child => {
+          if (child.selected) {
+            ++count;
+            if (!added) {
+              selected.push({ uid, name, children: [] });
+              added = true;
+            }
+            selected[selected.length - 1].children.push(child);
+          }
+        });
+      }
+      group.selectedCount = count;
+    });
+    return selected;
+  });
+
+  const filteredItems = computed(() => {
+    if (!selectedFacets.value.length) {
+      return allItems.value;
+    }
+    return allItems.value.filter(item => {
+      // An item must match every active facet group
+      return selectedFacets.value.every(group => {
+        const itemFacetValues = getItemFacet(item, group.uid);
+        if (itemFacetValues && itemFacetValues.length) {
+          // An item can match any of the selected facets within a group
+          return group.children.some(facet => itemFacetValues.includes(facet.uid));
+        }
+        return false;
+      });
+    });
+  });
+
+  const searchedItems = computed(() => {
+    if (!searchValue.value?.length) {
+      return filteredItems.value;
+    }
+    const fuse = new Fuse(filteredItems.value, searchOptions.value);
+    return fuse.search(searchValue.value).map(result => result.item);
+  });
+
+  const displayItems = computed(() => {
+    const sortFn = sortTypes.value[selectedSort.value]?.sort;
+    if (typeof sortFn !== 'function') {
+      return searchedItems.value;
+    }
+    // The sort function should not mutate the original array
+    return sortFn([...searchedItems.value]);
+  });
+
+  // --- Methods ---
+  function clearFilters() {
+    facets.value.forEach(group => {
+      if (group.children) {
+        group.children.forEach(child => child.selected = false);
+      }
+    });
+  }
+
+  function handleFacetChange({ groupUid, facetUid, selected }) {
+    const group = facets.value.find(g => g.uid === groupUid);
+    if (group) {
+      const facet = group.children.find(f => f.uid === facetUid);
+      if (facet) {
+        facet.selected = selected;
+      }
+    }
+  }
+
+  return {
+    // State
+    facets,
+    searchValue,
+    selectedSort,
+    sortTypes,
+
+    // Computed
+    displayItems,
+    selectedFacets,
+
+    // Methods
+    clearFilters,
+    handleFacetChange
+  };
+}

package/lib/components/systems/index.js

@@ -1,17 +1,25 @@
-export { default as UluFacets } from './facets/UluFacets.vue';
+export { useFacets } from './facets/useFacets.js';
+export { default as UluFacetsFilters } from './facets/UluFacetsFilters.vue';
+export { default as UluFacetsResults } from './facets/UluFacetsResults.vue';
 export { default as UluFacetsSearch } from './facets/UluFacetsSearch.vue';
+export { default as UluFacetsSidebarLayout } from './facets/UluFacetsSidebarLayout.vue';
+export { default as UluFacetsSort } from './facets/UluFacetsSort.vue';
 export { default as UluFacetsList } from './facets/UluFacetsList.vue';
+
 export { default as UluScrollAnchors } from './scroll-anchors/UluScrollAnchors.vue';
 export { default as UluScrollAnchorsNav } from './scroll-anchors/UluScrollAnchorsNav.vue';
 export { default as UluScrollAnchorsNavAnimated } from './scroll-anchors/UluScrollAnchorsNavAnimated.vue';
 export { default as UluScrollAnchorsSection } from './scroll-anchors/UluScrollAnchorsSection.vue';
+
 export { default as UluShowSkeleton } from './skeleton/UluShowSkeleton.vue';
 export { default as UluSkeletonContent } from './skeleton/UluSkeletonContent.vue';
 export { default as UluSkeletonMedia } from './skeleton/UluSkeletonMedia.vue';
-export { default as UluSkeletonTextInline } from './skeleton/UluSkeletonTextInline.vue';
+export { default as UluSkeletonText } from './skeleton/UluSkeletonText.vue';
+
 export { default as UluImageSlideShow } from './slider/UluImageSlideShow.vue';
 export { default as UluSlideShow } from './slider/UluSlideShow.vue';
 export { default as UluSlideShowSlide } from './slider/UluSlideShowSlide.vue';
+
 export { default as UluTableSticky } from './table-sticky/UluTableSticky.vue';
 export { default as UluTableStickyRows } from './table-sticky/UluTableStickyRows.vue';
 export { default as UluTableStickyTable } from './table-sticky/UluTableStickyTable.vue';

package/lib/components/systems/scroll-anchors/UluScrollAnchors.vue

@@ -10,6 +10,7 @@
   import { SECTIONS, REGISTER, UNREGISTER } from "./symbols.js";
   export default {
     name: "ScrollAnchors",
+    emits: ["section-change"],
     props: {
       firstItemActive: Boolean,
       /**
@@ -97,7 +98,7 @@
                 } else if (lastExiting && section.active) {
                   removeActive();
                 }
-                this.$emit("sectionChange", { 
+                this.$emit("section-change", { 
                   section, 
                   sections, 
                   active: isIntersecting 

package/lib/components/systems/skeleton/UluShowSkeleton.vue

@@ -1,13 +1,14 @@
 <template>
   <slot v-if="!when"/>
-  <SkeletonTextInline class="skeleton" v-else/>
+  <UluSkeletonText v-else inline/>
 </template>
 
-<script>
-  export default {
-    name: "ShowSkeleton",
-    props: {
-      when: Boolean,
-    },
-  };
+<script setup>
+  import UluSkeletonText from "./UluSkeletonText.vue";
+  defineProps({
+    /**
+     * If true will show whatever is passed to slot, else skeleton text
+     */
+    when: Boolean,
+  });
 </script>

package/lib/components/systems/skeleton/UluSkeletonContent.vue

@@ -1,11 +1,11 @@
 <template>
-  <div class="skeleton">
+  <div>
     <div v-for="(line, index) in linesWithSegments" :key="index">
       <span 
         v-for="segment in line"
         :key="segment"
-        class="skeleton__text skeleton__text--inline"
-        :class="{ 'skeleton__alt' : segment.alt }"
+        class="skeleton skeleton--text skeleton--inline"
+        :class="{ 'skeleton--background-alt' : segment.alt }"
         :style="{ width: `${ segment.width }%` }"
       > 
       </span>
@@ -13,48 +13,44 @@
   </div>
 </template>
 
-<script>
+<script setup>
+  import { computed } from "vue";
   import { randomInt } from "@ulu/utils/random.js";
   import { arrayCreate } from "@ulu/utils/array.js";
-  export default {
-    name: "SkeletonContent",
-    props: {
-      lines: {
-        type: Number,
-        default: 6
-      },
-    },
-    methods: {
-      randomInt
+
+  const props = defineProps({
+    /**
+     * Amount of lines to generate
+     */
+    lines: {
+      type: Number,
+      default: 6
     },
-    computed: {
-      /**
-       * Creates the segments (like words) for the given line count
-       * - Uses random number of segments and makes sure to fill the line between 70% - 100%
-       */
-      linesWithSegments() {
-        return arrayCreate(this.lines, () => {
-          const minWidth = 15;
-          const total = randomInt(70, 100);
-          let widthCurrent = 0;
-          const newWidth = () => {
-            const remaining = total - widthCurrent;
-            const width = randomInt(minWidth, remaining);
-            widthCurrent += width;
-            return width;
-          };
-          const segments = [];
-          while (widthCurrent < total - minWidth) {
-            segments.push(newWidth());
-          }
-          const getActualTotal = () => segments.reduce((acc, a) => acc + a, 0);
-          while (getActualTotal() >= total) {
-            let removed = segments.pop();
-            if (!removed) break;
-          }
-          return segments.map(width => ({ width, alt: Math.random() < 0.5 }));
-        });
-      }
+  });
+
+  /**
+   * Creates the segments (like words) for the given line count
+   * - Uses random number of segments and makes sure to fill the line between 70% - 100%
+   */
+  const linesWithSegments = computed(() => arrayCreate(props.lines, () => {
+    const minWidth = 15;
+    const total = randomInt(70, 100);
+    let widthCurrent = 0;
+    const newWidth = () => {
+      const remaining = total - widthCurrent;
+      const width = randomInt(minWidth, remaining);
+      widthCurrent += width;
+      return width;
+    };
+    const segments = [];
+    while (widthCurrent < total - minWidth) {
+      segments.push(newWidth());
+    }
+    const getActualTotal = () => segments.reduce((acc, a) => acc + a, 0);
+    while (getActualTotal() >= total) {
+      let removed = segments.pop();
+      if (!removed) break;
     }
-  };
+    return segments.map(width => ({ width, alt: Math.random() < 0.5 }));
+  }));
 </script>

package/lib/components/systems/skeleton/UluSkeletonMedia.vue

@@ -1,11 +1,9 @@
 <template>
-  <div class="skeleton__block skeleton__block--media layout-flex-center-all">
-    <FaIcon style="font-size: 2rem" icon="image"/>
+  <div class="skeleton skeleton-block--media">
+    <UluIcon icon="type:image"/>
   </div>
 </template>
 
-<script>
-  export default {
-    name: "SkeletonMedia",
-  };
+<script setup>
+  import UluIcon from "../../elements/UluIcon.vue";
 </script>

package/lib/components/systems/skeleton/UluSkeletonText.vue

@@ -0,0 +1,27 @@
+<template>
+  <span 
+    class="skeleton skeleton--text"
+    :class="{
+      'skeleton--inline' : inline,
+      'skeleton--background-alt' : alt,
+      [`skeleton--width-${ width }`] : width
+    }"
+  ></span>
+</template>
+
+<script setup>
+  defineProps({
+    /**
+     * Inline modifier
+     */
+    inline: Boolean,
+    /**
+     * Use alternate background color
+     */
+    alt: Boolean,
+    /**
+     * Optional size (width) - should correspond with width setup in scss component
+     */
+    width: String
+  });
+</script>

package/lib/components/systems/slider/UluImageSlideShow.vue

@@ -9,7 +9,7 @@
   <UluSlideShow 
     class="slideshow--images" 
     :items="images"
-    @slideChange="slideChange"
+    @slide-change="slideChange"
   >
     <template #slide="{ item }">
       <img :src="item.src" :alt="item.alt">

package/lib/components/systems/slider/UluSlideShow.vue

@@ -50,7 +50,7 @@
             @click="previous"
             :disabled="!canScrollLeft"
           >
-            <FaIcon class="slideshow__control-icon" icon="fas fa-chevron-left"/>
+            <UluIcon class="slideshow__control-icon" icon="type:next"/>
           </button>
         </li>
         <li class="slideshow__controls-item slideshow__controls-item--next">
@@ -60,7 +60,7 @@
             @click="next"
             :disabled="!canScrollRight"
           >
-            <FaIcon class="slideshow__control-icon" icon="fas fa-chevron-right"/>
+            <UluIcon class="slideshow__control-icon" icon="type:previous" />
           </button>
         </li>
       </ul>
@@ -97,8 +97,13 @@
 </template>
 
 <script>
+  import UluIcon from "../../elements/UluIcon.vue";
   export default {
     name: 'SlideShow',
+    emits: ['slide-change'],
+    components: {
+      UluIcon
+    },
     props: {
       /**
        * Should slides be focusable by tab key
@@ -278,7 +283,7 @@
             this.$nextTick(() => {
               const slide = this.getSlideByElement(entry.target);
               slide.active = entry.isIntersecting;
-              this.$emit('slideChange', { slide, track, nav });
+              this.$emit('slide-change', { slide, track, nav });
             });
           });
         };

package/lib/components/systems/table-sticky/UluTableSticky.vue

@@ -43,7 +43,7 @@
             pointerEvents: sizesCalculated ? 'auto' : 'none',
             width: tableWidth
           }"
-          @columnSorted="applySort"
+          @column-sorted="applySort"
         >
           <template v-for="(_, name) in $slots" v-slot:[name]="slotData">
             <slot :name="name" v-bind="slotData" />
@@ -66,7 +66,7 @@
           opacity: headerOpacityX,
           pointerEvents: headerVisibleX ? 'auto' : 'none'
         }"
-        @columnSorted="applySort"
+        @column-sorted="applySort"
       >
         <template v-for="(_, name) in $slots" v-slot:[name]="slotData">
           <slot :name="name" v-bind="slotData" />
@@ -138,9 +138,9 @@
         :getRowValue="getRowValue"
         :getColumnTitle="getColumnTitle"
         @vue:mounted="tableReady"
-        @actualHeaderRemoved="headerRemoved"
-        @actualHeaderAdded="headerAdded"
-        @columnSorted="applySort"
+        @actual-header-removed="headerRemoved"
+        @actual-header-added="headerAdded"
+        @column-sorted="applySort"
       >
         <template v-for="(_, name) in $slots" v-slot:[name]="slotData">
           <slot :name="name" v-bind="slotData" />
@@ -167,7 +167,7 @@
         opacity: headerOpacityX,
         pointerEvents: headerVisibleX ? 'auto' : 'none'
       }"
-      @columnSorted="applySort"
+      @column-sorted="applySort"
     >
       <template v-for="(_, name) in $slots" v-slot:[name]="slotData">
         <slot :name="name" v-bind="slotData" />
@@ -180,7 +180,7 @@
   import UluTableStickyTable from "./UluTableStickyTable.vue";
   import { debounce } from "@ulu/utils/performance.js";
   import { runAfterFramePaint } from "@ulu/utils/browser/performance.js";
-  import cloneDeep from "lodash/cloneDeep";
+  import cloneDeep from "lodash-es/cloneDeep.js";
   
   const arrayOfObjects = a => a.every(o => typeof o === "object");
   const required = true;
@@ -443,7 +443,7 @@
         } else {
           column.sortApplied = true;
         }
-        this.$emit("columnSort", column);
+        this.$emit("column-sort", column);
       },
       onColumnResize() {
         if (this.sizesPainted) {

package/lib/components/systems/table-sticky/UluTableStickyTable.vue

@@ -50,7 +50,7 @@
             :class="{ 
               'table-sticky__sort-button--focused' : column.sortFocused,
             }"
-            @click="$emit('columnSorted', column)"
+            @click="$emit('column-sorted', column)"
             @focus="handleSortFocus(column, true)"
             @blur="handleSortFocus(column, false)"
             :aria-pressed="column.sortApplied ? 'true' : 'false'"
@@ -199,9 +199,9 @@
         const { id } = column;
         const old = headerRefs[id];
         if (old) {
-          this.$emit("actualHeaderRemoved", old);
+          this.$emit("actual-header-removed", old);
         }
-        this.$emit("actualHeaderAdded", el);
+        this.$emit("actual-header-added", el);
         headerRefs[id] = el;
       },
       /**

package/lib/composables/index.js

@@ -7,4 +7,6 @@
 export { useIcon } from './useIcon.js';
 export { useModifiers } from './useModifiers.js';
 export { useWindowResize } from './useWindowResize.js';
-export { useBreakpointManager } from './useBreakpointManager.js';
+export { useRequiredInject } from './useRequiredInject.js';
+export { useBreakpointManager } from './useBreakpointManager.js';
+export { usePagination } from './usePagination.js';

package/lib/composables/useDocumentTitle.js

@@ -0,0 +1,47 @@
+import { computed } from 'vue';
+import { useHead as defaultUseHead } from '@unhead/vue';
+import { useRoute as defaultUseRoute } from 'vue-router';
+import { pageTitles } from './usePageTitle.js';
+
+/**
+ * Manages the document's <title> tag based on the current route's title.
+ * It pulls titles from the `usePageTitle` system, falling back to `meta.title`,
+ * and formats it with a template.
+ *
+ * This should be called once in the root App.vue component.
+ *
+ * @param {object} options
+ * @param {string} [options.titleTemplate='%s | My Awesome Site'] - The template for the title.
+ * @param {Function} [options.useRoute=defaultUseRoute] - The `useRoute` function, injectable for testing.
+ * @param {Function} [options.useHead=defaultUseHead] - The `useHead` function, injectable for testing.
+ */
+export function useDocumentTitle(options = {}) {
+  const {
+    titleTemplate = '%s',
+    useRoute = defaultUseRoute,
+    useHead = defaultUseHead
+  } = options;
+
+  const route = useRoute();
+
+  const documentTitle = computed(() => {
+    // Get the title from our reactive state, or fall back to the route's meta.
+    const titleFromState = pageTitles[route.path];
+    const titleFromMeta = route.meta.title;
+
+    let title = titleFromState || titleFromMeta;
+
+    // If the title from meta is a function, resolve it.
+    if (typeof title === 'function') {
+      title = title(route);
+    }
+
+    // Format the title with the template, or provide a default.
+    return title ? titleTemplate.replace('%s', title) : 'App';
+  });
+
+  // useHead is reactive, so it will automatically update when documentTitle changes.
+  useHead({
+    title: documentTitle,
+  });
+}

package/lib/composables/usePageTitle.js

@@ -0,0 +1,37 @@
+import { reactive, watchEffect, onUnmounted, unref } from "vue";
+import { useRoute as defaultUseRoute } from "vue-router";
+
+// A reactive map to store component-defined titles for the current route.
+// Key: route.path, Value: title string
+export const pageTitles = reactive({});
+
+/**
+ * A composable to set the title for the current page/route from within its component.
+ * This provides a single source of truth for a page's title, which can be
+ * consumed by various parts of the application (e.g., breadcrumbs, document title).
+ * @param {import('vue').Ref<string> | string} title The title to set for the current page. Can be a ref, computed, or a plain string.
+ * @param {{ useRoute: Function }} options For dependency injection in tests/stories.
+ */
+export function usePageTitle(title, { useRoute = defaultUseRoute } = {}) {
+  const route = useRoute();
+  const path = route.path;
+
+  watchEffect(() => {
+    pageTitles[path] = unref(title);
+  });
+
+  // Clean up when the component is unmounted to prevent memory leaks
+  onUnmounted(() => {
+    delete pageTitles[path];
+  });
+}
+
+/**
+ * Gets the dynamically set page title for a given path.
+ * For internal use by consumers like breadcrumb or document title utilities.
+ * @param {string} path The route path to look up.
+ * @returns {string | undefined}
+ */
+export function getPageTitle(path) {
+  return pageTitles[path];
+}