@ulu/frontend-vue 0.1.3-beta.2 → 0.1.3-beta.20

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

@@ -0,0 +1,50 @@
+<template>
+  <component
+    :is="element"
+    :class="[
+      'scroll-anchors__section',
+      { 'is-active': isActive }
+    ]"
+    :data-scrollpoint-state="sectionState"
+    ref="sectionRef"
+  >
+    <slot :isActive="isActive" :titleId="titleId" :section="section" :inactiveFrom="inactiveFrom" :activeFrom="activeFrom" :sectionState="sectionState" />
+  </component>
+</template>
+
+<script setup>
+  import { computed } from "vue";
+  import { useScrollAnchorSection } from "./useScrollAnchorSection";
+
+  const props = defineProps({
+    /**
+     * The title of the section, used for navigation and generating a default ID
+     */
+    title: {
+      type: String,
+      required: true
+    },
+    /**
+     * A custom ID to use for the section anchor, overriding the auto-generated one
+     */
+    customTitleId: String,
+    /**
+     * Element to use
+     */
+    element: {
+      type: String,
+      default: "div"
+    }
+  });
+
+  const { sectionRef, titleId, isActive, inactiveFrom, activeFrom, section } = useScrollAnchorSection(props);
+
+  const sectionState = computed(() => {
+    if (isActive.value) {
+      if (activeFrom.value) return `enter-${activeFrom.value}`;
+    } else {
+      if (inactiveFrom.value) return `exit-${inactiveFrom.value}`;
+    }
+    return null;
+  });
+</script>

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

@@ -1,6 +1,6 @@
 <template>
   <component 
-    v-if="sections.length" 
+    v-if="sections && sections.length" 
     :is="element"
     class="scroll-anchors__nav"
   >
@@ -13,25 +13,27 @@
           :class="{ 'is-active' : item.active }"
           :href="`#${ item.titleId }`" 
         >
-          {{ item.title }}
+          <slot :item="item" :index="index">
+            {{ item.title }}
+          </slot>
         </a>
       </li>
     </ul>
   </component>
 </template>
 
-<script>
-  import { SECTIONS } from "./symbols.js";
-  export default {
-    name: "ScrollAnchorsNav",
-    inject: {
-      sections: { from: SECTIONS }
-    },
-    props: {
-      element: {
-        type: String,
-        default: "nav"
-      }
+<script setup>
+  import { useScrollAnchorSections } from "./useScrollAnchorSections.js";
+
+  defineProps({
+    /**
+     * The HTML element to use for the navigation root
+     */
+    element: {
+      type: String,
+      default: "nav"
     }
-  };
-</script>
+  });
+
+  const sections = useScrollAnchorSections();
+</script>

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

@@ -1,16 +1,11 @@
-<!-- 
-Version: 0.0.2
-Changes: 
-  - 0.0.2 | Added transition initial state/class so the indicator 
-            doesn't transition at first
--->
 <template>
   <component 
-    v-if="sections.length" 
+    v-if="sections && sections.length" 
     :is="element"
-    class="scroll-anchors__nav scroll-anchors__nav--animated"
+    class="scroll-anchors__nav scroll-anchors__nav--animated scroll-anchors-nav-animated"
+    :style="{ '--ulu-sa-nav-rail-width': `${ railWidth }px` }"
   >
-    <ul class="scroll-anchors__rail">
+    <ul class="scroll-anchors-nav-animated__rail">
       <li 
         v-for="(item, index) in sections" :key="index"
         :class="{ 'is-active' : item.active }"
@@ -20,105 +15,121 @@ Changes:
           :ref="(el) => addLinkRef(index, el)"
           :href="`#${ item.titleId }`" 
         >
-          {{ item.title }}
+          <slot :item="item" :index="index">
+            {{ item.title }}
+          </slot>
         </a>
       </li>
     </ul>
     <div 
-      class="scroll-anchors__indicator"
+      class="scroll-anchors-nav-animated__indicator"
       :class="{
-        'scroll-anchors__indicator--can-transition' : indicatorAnimReady
+        'scroll-anchors-nav-animated__indicator--can-transition' : indicatorAnimReady
       }"
       ref="indicator"
-      :style="{ 
+      :style="{
         opacity: indicatorStyles ? '1' : '0',
-        transform: `translateY(${ indicatorStyles.y }px)`,
-        height: `${ indicatorStyles.height }px`,
+        transform: `translateY(${ indicatorStyles ? indicatorStyles.y : 0 }px)`,
+        height: `${ indicatorStyles ? indicatorStyles.height : 0 }px`,
+        width: `${ indicatorStyles ? indicatorStyles.width : 0 }px`
       }"
     ></div>
   </component>
 </template>
 
-<script>
+<script setup>
+  import { ref, computed, watch } from 'vue';
   import { runAfterFramePaint } from "@ulu/utils/browser/performance.js";
-  import { SECTIONS } from "./symbols.js";
-  export default {
-    name: "ScrollAnchorsNavAnimated",
-    inject: {
-      sections: { from: SECTIONS }
+  import { useScrollAnchorSections } from './useScrollAnchorSections.js';
+
+  const props = defineProps({
+    /**
+     * The HTML element to use for the navigation root
+     */
+    element: {
+      type: String,
+      default: "nav"
     },
-    props: {
-      /**
-       * Element to use for container
-       */
-      element: {
-        type: String,
-        default: "nav"
-      },
+    /**
+     * The width of the navigation rail
+     */
+    railWidth: {
+      type: Number,
+      default: 3
     },
-    data() {
-      return {
-        linkRefs: {},
-        indicatorAnimReady: false
-      };
+    /**
+     * The width of the indicator, defaults to railWidth
+     */
+    indicatorWidth: {
+      type: Number,
+      default: null
     },
-    computed: {
-      indicatorStyles() {
-        const { sections, linkRefs } = this;
-        const linkCount = Object.keys(linkRefs).length;
-        // Checking for sections and link refs incase 
-        // we were waiting for the components to mount, etc
-        if (!sections || !linkCount) {
-          return false;
-        }
-        const activeIndex = sections.findIndex(s => s.active);
-        if (activeIndex === -1) {
-          return false;
-        }
-        const link = this.linkRefs[activeIndex];
-        const { offsetTop, offsetHeight } = link;
-        return {
-          y: offsetTop,
-          height: offsetHeight,
-          initial: this.inidica
-        };
-      }
+    /**
+     * If set, creates a static height, centered indicator
+     */
+    indicatorHeight: {
+      type: Number,
+      default: null
     },
-    watch: {
-      indicatorStyles(val) {
-        if (val && !this.indicatorAnimReady) {
-          runAfterFramePaint(() => {
-            this.indicatorAnimReady = true;
-          });
-        }
-      }
+    /**
+     * Vertical alignment of the indicator relative to the link
+     */
+    indicatorAlignment: {
+      type: String,
+      default: 'center' // options: center, top
     },
-    methods: {
-      addLinkRef(index, el) {
-        this.linkRefs[index] = el;
-      }
+    /**
+     * Pixel offset for the indicator's vertical alignment
+     */
+    indicatorAlignmentOffset: {
+      type: Number,
+      default: 0
     }
-  };
-</script>
+  });
 
-<style lang="scss">
-  // User can override these styles
-  // - Think this is better than props/etc 
-  //   - Refactored from props to just plain css to be overridden
-  .scroll-anchors__rail {
-    border-left: 3px solid rgb(220, 220, 220);
-    padding-left: 1rem;
-  }
-  .scroll-anchors__indicator {
-    position: absolute;
-    top: 0;
-    left: 0;
-    width: 3px;
-    background-color: black;
-  }
-  .scroll-anchors__indicator--can-transition {
-    transition-property: height, transform;
-    transition-timing-function: ease-in-out;
-    transition-duration: 250ms;
+  const sections = useScrollAnchorSections();
+
+  const linkRefs = ref({});
+  const indicatorAnimReady = ref(false);
+  const indicator = ref(null);
+
+  const indicatorStyles = computed(() => {
+    if (!sections || !sections.value || !sections.value.length) {
+      return false;
+    }
+    const activeIndex = sections.value.findIndex(s => s.active);
+    if (activeIndex === -1) {
+      return false;
+    }
+    const link = linkRefs.value[activeIndex];
+    if (!link) return false; // Link might not be rendered yet
+
+    const { offsetTop, offsetHeight } = link;
+    const isStatic = props.indicatorHeight != null;
+    const width = props.indicatorWidth ?? props.railWidth;
+    const height = isStatic ? props.indicatorHeight : offsetHeight;
+
+    let y = offsetTop; // Default to 'top' alignment
+    if (props.indicatorAlignment === 'center') {
+      y = offsetTop + (offsetHeight / 2) - (height / 2);
+    }
+
+    y += props.indicatorAlignmentOffset;
+
+    return { y, height, width };
+  });
+
+  watch(indicatorStyles, (val) => {
+    if (val && !indicatorAnimReady.value) {
+      runAfterFramePaint(() => {
+        indicatorAnimReady.value = true;
+      });
+    }
+  });
+
+  function addLinkRef(index, el) {
+    if (el) {
+      linkRefs.value[index] = el;
+    }
   }
-</style>
+</script>

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

@@ -1,63 +1,77 @@
 <template>
-  <div :class="[wrapperClass, { [activeClass] : activeClass && section?.active }]" ref="element">
+  <component
+    :is="element"
+    :class="[wrapperClass, { [activeClass]: activeClass && isActive }]"
+    :data-scrollpoint-state="sectionState"
+    ref="sectionRef"
+  >
     <component :is="titleElement" :class="titleClass" :id="titleId">
-      {{ title }}
+      <slot name="title">
+        {{ title }}
+      </slot>
     </component>
     <slot :section="section"></slot>
-  </div>
+  </component>
 </template>
 
-<script>
+<script setup>
   import { computed } from "vue";
-  import { urlize } from "@ulu/utils/string.js";
-  import { REGISTER, UNREGISTER, SECTIONS } from "./symbols.js";
-  export default {
-    name: "ScrollAnchorsSection",
-    props: {
-      title: String,
-      titleElement: {
-        type: String,
-        default: "h2"
-      },
-      titleClass: {
-        type: String,
-        default: "h2"
-      },
-      anchorId: String,
-      wrapperClass: {
-        type: String,
-        default: "scroll-anchors__section"
-      },
-      activeClass: {
-        type: String,
-        default: 'is-active'
-      }
-    },
-    inject: {
-      register: { from: REGISTER }, 
-      unregister: { from: UNREGISTER },
-      sections: { from: SECTIONS, default: () => computed(() => []) }
+  import { useScrollAnchorSection } from "./useScrollAnchorSection";
+
+  const props = defineProps({
+    /**
+     * The title of the section, used for navigation and generating a default ID
+     */
+    title: String,
+    /**
+     * The HTML element to use for the title
+     */
+    titleElement: {
+      type: String,
+      default: "h2"
     },
-    data() {
-      const { anchorId, title } = this;
-      return {
-        titleId: anchorId || `sas-title-${ urlize(title) }`
-      };
+    /**
+     * The class to apply to the title element
+     */
+    titleClass: {
+      type: String,
+      default: "h2"
     },
-    computed: {
-      section() {
-        return this.sections.find(s => s.instance === this);
-      }
+    /**
+     * A custom ID to use for the section anchor, overriding the auto-generated one
+     */
+    customTitleId: String,
+    /**
+     * The class to apply to the section's wrapper div
+     */
+    wrapperClass: {
+      type: String,
+      default: "scroll-anchors__section"
     },
-    mounted() {
-      if (this.register) {
-        this.register(this);
-      }
+    /**
+     * The class to apply to the wrapper div when the section is active
+     */
+    activeClass: {
+      type: String,
+      default: 'is-active'
     },
-    unmounted() {
-      if (this.unregister) {
-        this.unregister(this);
-      }
+    /**
+     * The HTML element to use for the section root
+     */
+    element: {
+      type: String,
+      default: 'section'
+    }
+  });
+
+  const { sectionRef, titleId, isActive, inactiveFrom, activeFrom, section } = useScrollAnchorSection(props);
+
+  const sectionState = computed(() => {
+    if (isActive.value) {
+      if (activeFrom.value) return `enter-${activeFrom.value}`;
+    } else {
+      if (inactiveFrom.value) return `exit-${inactiveFrom.value}`;
     }
-  };
-</script>
+    return null;
+  });
+</script>

package/lib/components/systems/scroll-anchors/_scroll-anchors-nav-animated.scss

@@ -0,0 +1,67 @@
+////
+/// @group scroll-anchors-nav-animated
+/// For use with UluScrollAnchorsNavAnimated vue component.
+////
+
+@use "sass:map";
+@use "sass:meta";
+
+@use "@ulu/frontend/scss/selector";
+@use "@ulu/frontend/scss/utils";
+@use "@ulu/frontend/scss/color";
+
+// Used for function fallback
+$-fallbacks: () !default;
+
+/// Module Settings
+/// @type Map
+$config: (
+  "rail-border-color": #dcdcdc,
+  "rail-padding": 1rem,
+  "indicator-color": #000,
+  "indicator-clip-path": null,
+  "transition-duration": 250ms,
+  "transition-timing-function": ease-in-out
+) !default;
+
+/// Change modules $config
+/// @param {Map} $changes Map of changes
+@mixin set($changes) {
+  $config: map.merge($config, $changes) !global;
+}
+
+/// Get a config option
+/// @param {Map} $name Name of property
+@function get($name) {
+  $value: utils.require-map-get($config, $name, "scroll-anchors-nav-animated [config]");
+  @return utils.function-fallback($name, $value, $-fallbacks);
+}
+
+/// Prints component styles
+/// @demo scroll-anchors-nav-animated
+/// @example scss
+///  @include ulu.component-scroll-anchors-nav-animated-styles();
+
+@mixin styles {
+  $prefix: selector.class("scroll-anchors-nav-animated");
+
+  #{ $prefix } {
+    position: relative;
+  }
+  #{ $prefix }__rail {
+    border-left: var(--ulu-sa-nav-rail-width, 3px) solid color.get(get("rail-border-color"));
+    padding-left: get("rail-padding");
+  }
+  #{ $prefix }__indicator {
+    position: absolute;
+    top: 0;
+    left: 0;
+    background-color: color.get(get("indicator-color"));
+    clip-path: get("indicator-clip-path");
+  }
+  #{ $prefix }__indicator--can-transition {
+    transition-property: height, transform, width;
+    transition-timing-function: get("transition-timing-function");
+    transition-duration: get("transition-duration");
+  }
+}

package/lib/components/systems/scroll-anchors/useScrollAnchorSection.js

@@ -0,0 +1,60 @@
+import { ref, onMounted, onUnmounted, inject, computed, reactive, watch } from 'vue';
+import { urlize } from '@ulu/utils/string.js';
+
+/**
+ * Composable for a component that acts as a section within the Scroll Anchors system.
+ * It handles registering the section with the parent `UluScrollAnchors` component,
+ * manages its active state, and provides reactive properties for use in the template.
+ * @param {object} props The component props, requires `title` and optional `customTitleId`.
+ * @returns {object} An object with reactive properties for the section: `sectionRef` (the ref to bind), `titleId`, `isActive`, and the raw `section` object.
+ */
+export function useScrollAnchorSection(props) {
+  const sectionRef = ref(null); // for the user to bind to their root element
+
+  const register = inject('uluScrollAnchorsRegister');
+  const unregister = inject('uluScrollAnchorsUnregister');
+  const newId = title => `ulu-sa-${ urlize(title) }`;
+
+  const titleId = computed(() => props.customTitleId || newId(props.title));
+  
+  const section = reactive({
+    id: Symbol('section-id'),
+    title: props.title,
+    titleId: titleId.value,
+    element: null, // will be set on mount
+    active: false,
+    inactiveFrom: null,
+    activeFrom: null
+  });
+  
+  // Keep title and titleId in sync with props
+  watch(() => props.title, (newTitle) => {
+    section.title = newTitle;
+    section.titleId = props.customTitleId || newId(newTitle);
+  });
+  watch(() => props.customTitleId, (newTitleId) => {
+    section.titleId = newTitleId || newId(props.title);
+  });
+
+  onMounted(() => {
+    if (register && sectionRef.value) {
+      section.element = sectionRef.value;
+      register(section);
+    }
+  });
+
+  onUnmounted(() => {
+    if (unregister) {
+      unregister(section.id);
+    }
+  });
+
+  return {
+    sectionRef, // the ref for the user to attach
+    titleId,
+    isActive: computed(() => section.active),
+    inactiveFrom: computed(() => section.inactiveFrom),
+    activeFrom: computed(() => section.activeFrom),
+    section
+  };
+}

package/lib/components/systems/scroll-anchors/useScrollAnchorSections.js

@@ -0,0 +1,15 @@
+import { inject } from 'vue';
+
+/**
+ * Composable that provides a reactive list of all registered scroll anchor sections.
+ * This is the recommended way to access section data for building custom navigation.
+ * Must be used within a component that is a descendant of `UluScrollAnchors`.
+ * @returns {object} A reactive ref containing an array of section objects.
+ */
+export function useScrollAnchorSections() {
+  const sections = inject('uluScrollAnchorsSections');
+  if (!sections) {
+    console.warn('useScrollAnchorSections() must be used within an UluScrollAnchors component provider.');
+  }
+  return sections;
+}