@ulu/frontend-vue 0.1.0-beta.9 → 0.1.1-beta.1

package/lib/components/visualizations/UluProgressBar.vue

@@ -1,46 +1,33 @@
 <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,
-        }"
+  <div :class="componentClasses">
+    <div v-if="label || $slots.icon" class="progress-bar__header">
+      <strong
+        v-if="label"
+        class="progress-bar__label"
+        :class="{ '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 v-if="$slots.icon" class="progress-bar__icon">
+        <slot name="icon" />
       </div>
     </div>
     <div class="progress-bar__track">
-      <div 
-        class="progress-bar__bar"
-        :style="`width: ${ percentage }%`"
-      ></div>
-      <div 
-        v-if="deficit"
+      <div class="progress-bar__bar" :style="{ width: barWidth }"></div>
+      <div
+        v-if="deficit > 0"
         class="progress-bar__bar--deficit"
-        :style="`width: ${ defPercentage }%`"
+        :style="{ width: deficitBarWidth }"
       ></div>
     </div>
-    <div class="progress-bar__values">
+    <div v-if="!loader && !indeterminate" 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"
+      <div
+        v-if="deficit > 0"
+        class="progress-bar__value progress-bar__value--deficit"
       >
         <strong class="hidden-visually">Deficit: </strong>
         -{{ deficit }}
@@ -53,42 +40,86 @@
   </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>
+<script setup>
+import { computed } from "vue";
+
+/**
+ * A linear progress bar to display progress, with support for various styles and a deficit indicator.
+ * @slot icon - A slot for placing an icon in the header, typically to indicate status.
+ */
+const props = defineProps({
+  /**
+   * The label to display above the progress bar.
+   */
+  label: String,
+  /**
+   * Hides the label visually, but keeps it for screen readers.
+   */
+  labelHidden: Boolean,
+  /**
+   * The current amount of progress.
+   */
+  amount: {
+    type: Number,
+    default: 0,
+  },
+  /**
+   * The total amount that represents 100% progress.
+   */
+  total: {
+    type: Number,
+    default: 100,
+  },
+  /**
+   * The amount of deficit to display on the bar.
+   */
+  deficit: {
+    type: Number,
+    default: 0,
+  },
+  /**
+   * Renders a smaller version of the progress bar.
+   */
+  small: Boolean,
+  /**
+   * Applies the 'positive' style (e.g., green).
+   */
+  positive: Boolean,
+  /**
+   * Applies the 'negative' style (e.g., red).
+   */
+  negative: Boolean,
+  /**
+   * Applies styles for use as a thin loader.
+   */
+  loader: Boolean,
+  /**
+   * Applies an indeterminate animation for unknown progress.
+   */
+  indeterminate: Boolean,
+});
+
+const getCssPercentage = (amount, total) => {
+  const percent = total === 0 ? 0 : (amount / total) * 100;
+  return `${ percent }%`;
+};
+
+const barWidth = computed(() => {
+  if (props.indeterminate) return null; // No value for width
+  return getCssPercentage(props.amount, props.total);
+});
+
+const deficitBarWidth = computed(() => getCssPercentage(props.deficit, props.total));
+
+const componentClasses = computed(() => {
+  return {
+    'progress-bar': true,
+    'progress-bar--small': props.small,
+    'progress-bar--positive': props.positive,
+    'progress-bar--negative': props.negative,
+    'progress-bar--loader': props.loader,
+    'progress-bar--indeterminate': props.indeterminate,
+    'type-small': props.small, // From original component, seems to control font size
+  };
+});
+</script>

package/lib/components/visualizations/UluProgressCircle.vue

@@ -0,0 +1,146 @@
+<template>
+  <div :class="componentClasses">
+    <strong class="hidden-visually">{{ label }}</strong>
+    <div class="progress-circle__chart">
+      <svg class="progress-circle__chart-svg" viewBox="0 0 32 32">
+        <circle
+          class="progress-circle__chart-track"
+          r="16"
+          cx="16"
+          cy="16"
+        />
+        <circle 
+          class="progress-circle__chart-pie" 
+          ref="pie"
+          r="16" 
+          cx="16" 
+          cy="16"
+          :style="{ strokeDasharray: endDasharray }"
+        />
+        <circle 
+          class="progress-circle__chart-mask" 
+          cx="16" 
+          cy="16" 
+        />
+      </svg>
+      <strong v-if="!showValueOutside" class="progress-circle__chart-value">
+        {{ percentage }}%
+      </strong>
+    </div>
+    <strong v-if="showValueOutside" class="progress-circle__value type-small-x">
+      {{ percentage }}%
+    </strong>
+  </div>
+</template>
+
+<script>
+  /**
+   * A circular progress indicator component.
+   */
+  export default {
+    name: 'UluProgressCircle',
+    props: {
+      /**
+       * The label for accessibility (visually hidden).
+       */
+      label: {
+        type: String,
+        default: "Progress"
+      },
+      /**
+       * The progress percentage (0-100).
+       */
+      percentage: {
+        type: Number,
+        default: 0
+      },
+      /**
+       * Renders a smaller version of the component.
+       */
+      small: Boolean,
+      /**
+       * Displays the percentage value outside (to the side) of the circle.
+       */
+      outside: Boolean,
+      /**
+       * Displays the percentage value below the circle.
+       */
+      outsideBelow: Boolean,
+      /**
+       * Sets the status color of the progress circle (e.g., 'low', 'incomplete', 'complete').
+       */
+      status: {
+        type: String,
+        default: ''
+      },
+      /**
+       * Renders the component as a solid pie chart instead of a donut.
+       */
+      pieStyle: Boolean,
+      /**
+       * Removes the center mask, filling the entire circle.
+       */
+      noMask: Boolean,
+      /**
+       * The duration of the animation in milliseconds.
+       */
+      duration: {
+        type: Number,
+        default: 1000 // Matches SCSS animation-duration
+      },
+      /**
+       * The easing function for the animation.
+       */
+      easing: {
+        type: String,
+        default: "ease-in" // Matches SCSS animation-timing
+      }
+    },
+    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`;
+      },
+      showValueOutside() {
+        return this.outside || this.outsideBelow || this.small;
+      },
+      componentClasses() {
+        const classes = {
+          'progress-circle': true,
+          'progress-circle--small': this.small,
+          'progress-circle--pie': this.pieStyle,
+          'progress-circle--outside': this.showValueOutside,
+          'progress-circle--outside-below': this.outsideBelow,
+          'progress-circle--no-mask': this.noMask,
+        };
+        if (this.status) {
+          classes[`progress-circle--${this.status}`] = true;
+        }
+        return classes;
+      }
+    },
+    methods: {
+      normalize(percentage) {
+        // Added the 1% extra to 100% because sometimes it renders with a tiny gap
+        return percentage === 100 ? 101 : percentage;
+      },
+      animate(from = 0) {
+        const { pie } = this.$refs;
+        if (!pie || !pie.animate) return; // No Animation API or element not ready
+        const { duration, easing, endDasharray } = this;
+        const keyframes = { strokeDasharray: [`${ from } 100`, endDasharray] };
+        pie.animate(keyframes, { duration, easing, fill: "forwards" });
+      }
+    },
+    mounted() {
+      this.animate();
+    }
+  }
+</script>

package/lib/components/visualizations/progress-bar-examples.html

@@ -0,0 +1,175 @@
+
+<h2 class="h2">Basic Example</h2>
+<p>The default progress bar has no modifiers.</p>
+<div class="progress-bar">
+  <div class="progress-bar__header"><strong class="progress-bar__label">Label that is long test</strong>
+  </div>
+  <div class="progress-bar__track">
+    <div class="progress-bar__bar" style="width: 40%;"></div>
+  </div>
+  <div class="progress-bar__values">
+    <div class="progress-bar__value progress-bar__value--amount"><strong class="hidden-visually">Amount:</strong>
+      200</div>
+    <div class="progress-bar__value progress-bar__value--total"><strong class="hidden-visually">Total:</strong> 500
+    </div>
+  </div>
+</div>
+
+<div class="rule rule--light"></div>
+
+<h2 class="h2">Indeterminate Modifier</h2>
+<p>Uses the <code>.progress-bar--indeterminate</code> modifier for an animated loading state when the progress is unknown.</p>
+<div class="progress-bar progress-bar--loader progress-bar--indeterminate">
+  <div class="progress-bar__track">
+    <div class="progress-bar__bar"></div>
+  </div>
+</div>
+
+<div class="rule rule--light"></div>
+
+<h2 class="h2">Loader Style</h2>
+<p>Uses the <code>.progress-bar--loader</code> modifier for a thin loading bar.</p>
+<div class="progress-bar progress-bar--loader">
+  <div class="progress-bar__track">
+    <div class="progress-bar__bar" style="width: 65%;"></div>
+  </div>
+</div>
+
+
+<div class="rule rule--light"></div>
+
+<h2 class="h2">Completed Example</h2>
+<p>An example of a completed progress bar with an icon.</p>
+<div class="progress-bar">
+  <div class="progress-bar__header"><strong class="progress-bar__label">Progress</strong>
+    <div class="progress-bar__icon">
+      <span class="fas fa-check" aria-hidden="true"></span>
+      <span class="hidden-visually">Item Completed</span>
+    </div>
+  </div>
+  <div class="progress-bar__track">
+    <div class="progress-bar__bar" style="width: 100%;"></div>
+  </div>
+  <div class="progress-bar__values">
+    <div class="progress-bar__value progress-bar__value--amount"><strong class="hidden-visually">Amount:</strong>
+      500</div>
+    <div class="progress-bar__value progress-bar__value--total"><strong class="hidden-visually">Total:</strong> 500
+    </div>
+  </div>
+</div>
+
+<div class="rule rule--light"></div>
+
+<h2 class="h2">Deficit Example</h2>
+<p>An example of a progress bar with a deficit.</p>
+<div class="progress-bar">
+  <div class="progress-bar__header"><strong class="progress-bar__label">Progress</strong>
+    <div class="progress-bar__icon"><span class="fas fa-triangle-exclamation" aria-hidden="true"></span><span class="hidden-visually">Item Has Deficit</span></div>
+  </div>
+  <div class="progress-bar__track">
+    <div class="progress-bar__bar" style="width: 60%;"></div>
+    <div class="progress-bar__bar progress-bar__bar--deficit" style="width: 20%;"></div>
+  </div>
+  <div class="progress-bar__values">
+    <div class="progress-bar__value progress-bar__value--amount"><strong class="hidden-visually">Amount:</strong>
+      300</div>
+    <div class="progress-bar__value progress-bar__value--deficit color-status is-danger"><strong
+        class="hidden-visually">Deficit: </strong> -100</div>
+    <div class="progress-bar__value progress-bar__value--total"><strong class="hidden-visually">Total:</strong> 500
+    </div>
+  </div>
+</div>
+
+<div class="rule rule--light"></div>
+
+<h2 class="h2">Positive Style</h2>
+<p>Uses the <code>.progress-bar--positive</code> modifier.</p>
+<div class="progress-bar progress-bar--positive">
+  <div class="progress-bar__header"><strong class="progress-bar__label">Positive</strong></div>
+  <div class="progress-bar__track">
+    <div class="progress-bar__bar" style="width: 75%;"></div>
+  </div>
+</div>
+
+<div class="rule rule--light"></div>
+
+<h2 class="h2">Negative Style</h2>
+<p>Uses the <code>.progress-bar--negative</code> modifier.</p>
+<div class="progress-bar progress-bar--negative">
+  <div class="progress-bar__header"><strong class="progress-bar__label">Negative</strong></div>
+  <div class="progress-bar__track">
+    <div class="progress-bar__bar" style="width: 30%;"></div>
+  </div>
+</div>
+
+<div class="rule rule--light"></div>
+
+<h2 class="h2">Small Modifier</h2>
+<p>Uses the <code>.progress-bar--small</code> modifier. Font sizing is controlled by the parent element.</p>
+<div class="progress-bar progress-bar--small progress-bar--positive type-small">
+  <div class="progress-bar__header"><strong class="progress-bar__label type-normal">Progress</strong>
+    <div class="progress-bar__icon">
+      <span class="fas fa-check" aria-hidden="true"></span>
+      <span class="hidden-visually">Item Completed</span>
+    </div>
+  </div>
+  <div class="progress-bar__track">
+    <div class="progress-bar__bar" style="width: 100%;"></div>
+  </div>
+  <div class="progress-bar__values">
+    <div class="progress-bar__value progress-bar__value--amount"><strong class="hidden-visually">Amount:</strong>
+      500</div>
+    <div class="progress-bar__value progress-bar__value--total"><strong class="hidden-visually">Total:</strong> 500
+    </div>
+  </div>
+</div>
+
+<div class="progress-bar progress-bar--small progress-bar--deficit type-small">
+  <div class="progress-bar__header"><strong class="progress-bar__label type-normal">Progress</strong>
+    <div class="progress-bar__icon"><span class="fas fa-triangle-exclamation" aria-hidden="true"></span><span class="hidden-visually">Item Has Deficit</span></div>
+  </div>
+  <div class="progress-bar__track">
+    <div class="progress-bar__bar" style="width: 60%;"></div>
+    <div class="progress-bar__bar progress-bar__bar--deficit" style="width: 20%;"></div>
+  </div>
+  <div class="progress-bar__values">
+    <div class="progress-bar__value progress-bar__value--amount"><strong class="hidden-visually">Amount:</strong>
+      300</div>
+    <div class="progress-bar__value progress-bar__value--deficit color-status is-danger"><strong
+        class="hidden-visually">Deficit: </strong> -100</div>
+    <div class="progress-bar__value progress-bar__value--total"><strong class="hidden-visually">Total:</strong> 500
+    </div>
+  </div>
+</div>
+
+<div class="rule rule--light"></div>
+
+<h2 class="h2">Icon left with rail</h2>
+<p>Combining with rail component for icon on left</p>
+
+<div class="progress-bar progress-bar--positive">
+  <div class="rail">
+    <div class="rail__item">
+      <div class="progress-bar__icon type-large">
+        <span class="fas fa-check" aria-hidden="true"></span>
+      </div>
+    </div>
+    <div class="rail__item flex-grow">
+      <div class="progress-bar__header">
+        <strong class="progress-bar__label">Progress</strong>
+      </div>
+      <div class="progress-bar__track">
+        <div class="progress-bar__bar" style="width: 100%;"></div>
+      </div>
+      <div class="progress-bar__values">
+        <div class="progress-bar__value progress-bar__value--amount"><strong class="hidden-visually">Amount:</strong>
+          300</div>
+        <div class="progress-bar__value progress-bar__value--deficit color-status is-danger"><strong
+            class="hidden-visually">Deficit: </strong> -100</div>
+        <div class="progress-bar__value progress-bar__value--total"><strong class="hidden-visually">Total:</strong> 500
+      </div>
+    </div>
+  </div>
+</div>
+
+

package/lib/composables/index.js

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

package/lib/composables/useDocumentTitle.js

@@ -0,0 +1,61 @@
+import { reactive, watchEffect, onUnmounted, unref, computed } from "vue";
+import { useHead as defaultUseHead } from "@unhead/vue";
+import { useRoute as defaultUseRoute } from "vue-router";
+import { getRouteTitle } from "../utils/router.js";
+
+// A reactive map to store component-defined titles.
+const componentTitles = reactive({});
+
+/**
+ * A composable to manage the document title.
+ *
+ * When called with a `title` option, it sets a dynamic title for the current page.
+ * This is for use within specific components.
+ *
+ * When called without a `title` option (typically in App.vue), it manages the
+ * document title for the whole app, using titles from components or route meta.
+ *
+ * @param {object} options
+ * @param {import('vue').Ref<string> | string} [options.title] - The dynamic title to set for the current page.
+ * @param {string} [options.titleTemplate='%s'] - The template for the document title, e.g., '%s | My Site'.
+ * @param {Function} [options.useRoute=defaultUseRoute] - Injectable `useRoute` for testing.
+ * @param {Function} [options.useHead=defaultUseHead] - Injectable `useHead` for testing.
+ */
+export function useDocumentTitle(options = {}) {
+  const {
+    title,
+    titleTemplate = "%s",
+    useRoute = defaultUseRoute,
+    useHead = defaultUseHead,
+  } = options;
+
+  const route = useRoute();
+  const path = route.path;
+
+  // --- Setter Mode ---
+  // If a title is provided, we're in "setter" mode, used within a component.
+  if (title !== undefined) {
+    watchEffect(() => {
+      componentTitles[path] = unref(title);
+    });
+
+    onUnmounted(() => {
+      delete componentTitles[path];
+    });
+    return; // End execution for setter mode.
+  }
+
+  // --- Manager Mode ---
+  // If no title is provided, we're in "manager" mode, used in App.vue.
+  const documentTitle = computed(() => {
+    const titleFromComponent = componentTitles[route.path];
+    const titleFromMeta = getRouteTitle(route, route);
+    const resolvedTitle = titleFromComponent || titleFromMeta;
+
+    return resolvedTitle ? titleTemplate.replace("%s", resolvedTitle) : "App";
+  });
+
+  useHead({
+    title: documentTitle,
+  });
+}