@ulu/frontend-vue 0.1.0-beta.19 → 0.1.0-beta.20

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 | My Awesome Site',
+    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) : 'My Awesome Site';
+  });
+
+  // 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];
+}

package/lib/utils/router.js

@@ -1,3 +1,4 @@
+import { getPageTitle } from "../composables/usePageTitle.js";
 /**
  * This Module Creates Menus from route or router config
  * - Note: Functions prefixed with "$" work with $route objects (running application, provided by vue-router ie $router, useRoute, etc), 
@@ -251,4 +252,63 @@ export function $createSectionMenu(route, options) {
     .filter(includeIndex(opts.includeIndex))
     .map(r => createMenuItem(r, `${ parent.path }/${ r.path }`, opts.item))
     .sort(opts.sort);
+}
+
+/**
+ * For a given $route, this will generate a breadcrumb trail.
+ * It iterates through `route.matched` to build the trail.
+ * - Prioritizes titles set via the `usePageTitle` composable for the current page.
+ * - Falls back to `meta.title` (string or function).
+ * - Skips routes where `meta.breadcrumb` is set to `false`.
+ * - Avoids duplicate crumbs for nested routes with empty paths.
+ * @param {Object} route The Vue Router `$route` object.
+ * @returns {Array.<{title: String, to: Object, current: Boolean}>} An array of breadcrumb items.
+ */
+export function $createBreadcrumb(route) {
+  const { matched, path: currentPath } = route;
+  let prevPath;
+
+  const crumbs = matched.reduce((arr, match, index) => {
+    // Skip routes configured to be hidden from breadcrumbs
+    if (match.meta?.breadcrumb === false) {
+      return arr;
+    }
+
+    // Avoid duplicates from child routes with empty paths
+    if (match.path === prevPath) {
+      return arr;
+    }
+    
+    const isLast = index === matched.length - 1;
+    let title;
+
+    // 1. Prioritize component-defined title for the current page
+    if (isLast) {
+      title = getPageTitle(currentPath);
+    }
+
+    // 2. Fallback to meta.title (function or string)
+    if (!title) {
+      const metaTitle = match.meta?.title;
+      if (typeof metaTitle === 'function') {
+        title = metaTitle(route);
+      } else {
+        title = metaTitle;
+      }
+    }
+
+    // 3. Final fallback
+    title = title || 'Missing Title';
+
+    arr.push({
+      title,
+      to: { path: isLast ? currentPath : match.path },
+      current: isLast,
+    });
+
+    prevPath = match.path;
+    return arr;
+  }, []);
+  
+  return crumbs;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ulu/frontend-vue",
-  "version": "0.1.0-beta.19",
+  "version": "0.1.0-beta.20",
   "description": "A modular and tree-shakeable Vue 3 component library for the Ulu frontend",
   "type": "module",
   "files": [
@@ -59,7 +59,8 @@
     "@headlessui/vue": "^1.7.23",
     "@ulu/frontend": "^0.1.0-beta.102",
     "vue": "^3.5.17",
-    "vue-router": "^4.5.1"
+    "vue-router": "^4.5.1",
+    "@unhead/vue": "^2.0.11"
   },
   "optionalDependencies": {
     "fuse.js": "^6.6.2",
@@ -89,7 +90,8 @@
     "storybook-addon-vue-mdx": "^2.0.2",
     "typescript": "^5.3.3",
     "vite": "^7.0.0",
-    "vue-router": "^4.5.1"
+    "vue-router": "^4.5.1",
+    "@unhead/vue": "^2.0.11"
   },
   "volta": {
     "node": "22.17.0"

package/types/composables/useDocumentTitle.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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?: {
+    titleTemplate?: string;
+    useRoute?: Function;
+    useHead?: Function;
+}): void;
+//# sourceMappingURL=useDocumentTitle.d.ts.map

package/types/composables/useDocumentTitle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDocumentTitle.d.ts","sourceRoot":"","sources":["../../lib/composables/useDocumentTitle.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;GAWG;AACH,2CAJG;IAAyB,aAAa,GAA9B,MAAM;IACa,QAAQ;IACR,OAAO;CACpC,QA8BA"}

package/types/composables/usePageTitle.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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: import("vue").Ref<string> | string, { useRoute }?: {
+    useRoute: Function;
+}): void;
+/**
+ * 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: string): string | undefined;
+export const pageTitles: {};
+//# sourceMappingURL=usePageTitle.d.ts.map

package/types/composables/usePageTitle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePageTitle.d.ts","sourceRoot":"","sources":["../../lib/composables/usePageTitle.js"],"names":[],"mappings":"AAOA;;;;;;GAMG;AACH,oCAHW,OAAO,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,iBAClC;IAAE,QAAQ,WAAU;CAAE,QAchC;AAED;;;;;GAKG;AACH,mCAHW,MAAM,GACJ,MAAM,GAAG,SAAS,CAI9B;AA/BD,4BAAuC"}

package/types/utils/router.d.ts

@@ -110,6 +110,21 @@ export function $createSectionMenu(route: any, options: {
     includeIndex: boolean;
     item: any;
 }): Array<RouteMenuItem>;
+/**
+ * For a given $route, this will generate a breadcrumb trail.
+ * It iterates through `route.matched` to build the trail.
+ * - Prioritizes titles set via the `usePageTitle` composable for the current page.
+ * - Falls back to `meta.title` (string or function).
+ * - Skips routes where `meta.breadcrumb` is set to `false`.
+ * - Avoids duplicate crumbs for nested routes with empty paths.
+ * @param {Object} route The Vue Router `$route` object.
+ * @returns {Array.<{title: String, to: Object, current: Boolean}>} An array of breadcrumb items.
+ */
+export function $createBreadcrumb(route: any): Array<{
+    title: string;
+    to: any;
+    current: boolean;
+}>;
 /**
  * Route Menu Item
  */

package/types/utils/router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../lib/utils/router.js"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AAEH;;;;;;;GAOG;AACH,uCANW,GAAC,WAET;IAAwB,SAAS;IACT,IAAI;CAC5B,GAAU,KAAK,CAAE,aAAa,CAAC,CAiCjC;AAED;;GAEG;AACH,4CAcC;AAED;;;;;;;;GAQG;AACH,0CAPW,GAAC,eACD,GAAC,WAET;IAAyB,YAAY;IACb,IAAI;CAC5B,GAAU,KAAK,CAAE,aAAa,CAAC,CA6BjC;AAED;;;;;GAKG;AASH;;;;GAIG;AACH,yDAEC;AACD;;;;;;;;GAQG;AACH,oEAJG;IAA0B,MAAM;IACN,SAAS;CACnC,GAAU,aAAa,CAsBzB;AACD;;;;GAIG;AACH,mDAEC;AACD;;;;GAIG;AACH,uDAGC;AACD;;;;GAIG;AACH,gEAUC;AACD;;;;GAIG;AACH,iEAEC;AACD;;;;;GAKG;AACH,2DAFY,UAAW,CAUtB;AAUD;;;;;;;;;;GAUG;AACH,wDALG;IAAwB,MAAM;IACL,YAAY;IACb,IAAI;CAC5B,GAAU,KAAK,CAAE,aAAa,CAAC,CAgBjC"}
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../lib/utils/router.js"],"names":[],"mappings":"AACA;;;;GAIG;AAEH;;;;;GAKG;AAEH;;;;;;;GAOG;AACH,uCANW,GAAC,WAET;IAAwB,SAAS;IACT,IAAI;CAC5B,GAAU,KAAK,CAAE,aAAa,CAAC,CAiCjC;AAED;;GAEG;AACH,4CAcC;AAED;;;;;;;;GAQG;AACH,0CAPW,GAAC,eACD,GAAC,WAET;IAAyB,YAAY;IACb,IAAI;CAC5B,GAAU,KAAK,CAAE,aAAa,CAAC,CA6BjC;AAED;;;;;GAKG;AASH;;;;GAIG;AACH,yDAEC;AACD;;;;;;;;GAQG;AACH,oEAJG;IAA0B,MAAM;IACN,SAAS;CACnC,GAAU,aAAa,CAsBzB;AACD;;;;GAIG;AACH,mDAEC;AACD;;;;GAIG;AACH,uDAGC;AACD;;;;GAIG;AACH,gEAUC;AACD;;;;GAIG;AACH,iEAEC;AACD;;;;;GAKG;AACH,2DAFY,UAAW,CAUtB;AAUD;;;;;;;;;;GAUG;AACH,wDALG;IAAwB,MAAM;IACL,YAAY;IACb,IAAI;CAC5B,GAAU,KAAK,CAAE,aAAa,CAAC,CAgBjC;AAED;;;;;;;;;GASG;AACH,+CAFa,KAAK,CAAE;IAAC,KAAK,SAAS;IAAC,EAAE,MAAS;IAAC,OAAO,UAAS;CAAC,CAAC,CAiDjE"}