@rimelight/ui 0.0.21 → 0.0.22

package/src/components/vue/RLVHeader.vue

@@ -1,9 +1,12 @@
 <script setup lang="ts">
-import { computed } from "vue"
+import { computed, onMounted, onUnmounted, ref } from "vue"
 import { scv, cx } from "css-variants"
 import { twMerge } from "tailwind-merge"
 import { useUi } from "../../composables"
-import { headerTheme } from "@/themes/header.theme.ts"
+import { headerTheme } from "../../themes/header.theme.ts"
+import { getHeaderStack } from "../../utils/headerStack.ts"
+
+// ── Style engine ─────────────────────────────────────────────────────────────
 
 const header = scv({
   slots: [...headerTheme.slots],
@@ -13,6 +16,8 @@ const header = scv({
   classNameResolver: (...args) => twMerge(cx(...args))
 })
 
+// ── Props ─────────────────────────────────────────────────────────────────────
+
 export interface RLVHeaderProps {
   /**
    * Whether to contain the header content in a max-width container.
@@ -21,11 +26,32 @@ export interface RLVHeaderProps {
    */
   contain?: boolean
   /**
-   * Whether the header should be sticky at the top.
+   * Sticky positioning when `fixed` is false.
    *
    * @default true
    */
   sticky?: boolean
+  /**
+   * Switches to `position: fixed; left: 0; right: 0` (layer mode). When true, `top` and
+   * `stackIndex` control the exact position.
+   *
+   * @default false
+   */
+  fixed?: boolean
+  /**
+   * Controls z-index when `fixed` is true: `z-index = 100 - stackIndex`. Lower index = higher in
+   * the visual stack.
+   *
+   * @default 0
+   */
+  stackIndex?: number
+  /**
+   * When true, hides the header on scroll-down and shows it on scroll-up. Uses a passive `scroll`
+   * event listener — no external dependencies. Only meaningful when `fixed` is true.
+   *
+   * @default false
+   */
+  hideOnScroll?: boolean
   /**
    * UI overrides for individual slots, derived from the header theme.
    */
@@ -39,10 +65,15 @@ export interface RLVHeaderProps {
 const {
   contain = true,
   sticky = true,
+  fixed = false,
+  stackIndex = 0,
+  hideOnScroll = false,
   class: className,
   ui: uiProp
 } = defineProps<RLVHeaderProps>()
 
+// ── Slots ─────────────────────────────────────────────────────────────────────
+
 defineSlots<{
   /**
    * Content to display on the left side of the header (e.g., Logo).
@@ -58,35 +89,126 @@ defineSlots<{
   right(props: {}): any
 }>()
 
+// ── UI merge ──────────────────────────────────────────────────────────────────
+
 const mergedUI = useUi("header", uiProp as Record<string, unknown> | undefined)
 
-const resolvedClasses = computed(() => {
-  const classes = header({
-    contain,
-    sticky
-  })
+// ── Resolved classes ──────────────────────────────────────────────────────────
 
+const resolvedClasses = computed(() => {
+  const classes = header({ contain, sticky, fixed })
   return {
     root: twMerge(classes.root, mergedUI.value.root as string | undefined),
+    content: twMerge(classes.content, mergedUI.value.content as string | undefined),
     container: twMerge(classes.container, mergedUI.value.container as string | undefined),
     left: twMerge(classes.left, mergedUI.value.left as string | undefined),
     center: twMerge(classes.center, mergedUI.value.center as string | undefined),
     right: twMerge(classes.right, mergedUI.value.right as string | undefined)
   }
 })
+
+// ── Fixed-mode state ──────────────────────────────────────────────────────────
+
+const id = `rlv-header-${Math.random().toString(36).slice(2, 8)}`
+const rootRef = ref<HTMLElement | null>(null)
+const contentRef = ref<HTMLElement | null>(null)
+const naturalHeight = ref(0)
+const isVisible = ref(true)
+
+/**
+ * Inline style applied to the root element in fixed mode.
+ */
+const fixedStyle = computed(() => {
+  if (!fixed) return {}
+  return {
+    zIndex: 100 - stackIndex
+  }
+})
+
+// ── Lifecycle: height measurement + scroll listener ───────────────────────────
+
+let resizeObserver: ResizeObserver | null = null
+let scrollHandler: (() => void) | null = null
+
+onMounted(() => {
+  if (!fixed) return
+
+  const stack = getHeaderStack()
+
+  const updateStack = () => {
+    stack.register(id, stackIndex, naturalHeight.value, isVisible.value, rootRef.value)
+  }
+
+  // Measure natural height via ResizeObserver
+  if (contentRef.value) {
+    naturalHeight.value = contentRef.value.getBoundingClientRect().height
+    resizeObserver = new ResizeObserver((entries) => {
+      const h = entries[0]?.contentRect.height
+      if (h && h > 0) {
+        naturalHeight.value = h
+        updateStack()
+      }
+    })
+    resizeObserver.observe(contentRef.value)
+  }
+
+  // Raw scroll listener for hideOnScroll
+  if (hideOnScroll) {
+    let localLastScrollY = window.scrollY
+    scrollHandler = () => {
+      const current = window.scrollY
+      const diff = current - localLastScrollY
+
+      // Ignore tiny jitter
+      if (Math.abs(diff) < 10) return
+
+      const newVisible = current <= 50 ? true : diff <= 0
+      if (newVisible !== isVisible.value) {
+        isVisible.value = newVisible
+        updateStack()
+      }
+
+      localLastScrollY = current
+    }
+
+    window.addEventListener("scroll", scrollHandler, { passive: true })
+  }
+
+  updateStack()
+})
+
+onUnmounted(() => {
+  resizeObserver?.disconnect()
+  if (scrollHandler) window.removeEventListener("scroll", scrollHandler)
+  if (fixed) getHeaderStack().unregister(id)
+})
 </script>
 
 <template>
-  <header :class="[resolvedClasses.root, className]" data-slot="rlv-header" v-bind="$attrs">
-    <div :class="resolvedClasses.container">
-      <div :class="resolvedClasses.left" data-slot="header-left">
-        <slot name="left" />
-      </div>
-      <div :class="resolvedClasses.center" data-slot="header-center">
-        <slot name="center" />
-      </div>
-      <div :class="resolvedClasses.right" data-slot="header-right">
-        <slot name="right" />
+  <header
+    ref="rootRef"
+    :id="id"
+    :class="[resolvedClasses.root, className]"
+    :style="fixedStyle"
+    data-slot="rlv-header"
+    v-bind="$attrs"
+  >
+    <!--
+      content wrapper: always rendered, but only meaningful in fixed mode.
+      The ResizeObserver targets this element so the `<header>` root's padding/border
+      don't interfere with the height measurement.
+    -->
+    <div ref="contentRef" :class="resolvedClasses.content">
+      <div :class="resolvedClasses.container">
+        <div :class="resolvedClasses.left" data-slot="header-left">
+          <slot name="left" />
+        </div>
+        <div :class="resolvedClasses.center" data-slot="header-center">
+          <slot name="center" />
+        </div>
+        <div :class="resolvedClasses.right" data-slot="header-right">
+          <slot name="right" />
+        </div>
       </div>
     </div>
   </header>

package/src/components/vue/RLVScrollToTop.vue

@@ -1,154 +1,214 @@
-<script setup lang="ts">
-import { computed } from "vue"
-import { scv, cx } from "css-variants"
-import { twMerge } from "tailwind-merge"
-import defu from "defu"
-import { scrollToTopTheme } from "../../themes/scroll-to-top.theme.ts"
-import { useScrollToTop } from "../../composables/useScrollToTop"
-import { getUIConfig } from "virtual:rimelight-ui"
-
-export interface RLVScrollToTopProps {
-  color?: keyof typeof scrollToTopTheme.variants.color
-  circleStrokeWidth?: number
-  duration?: number
-  threshold?: number
-  ui?: Partial<Record<keyof typeof scrollToTopTheme.base, string>>
-  class?: string
-  [key: string]: unknown
-}
-
-const scrollToTop = scv({
-  slots: [...scrollToTopTheme.slots],
-  base: scrollToTopTheme.base,
-  variants: scrollToTopTheme.variants,
-  compoundVariants: [...scrollToTopTheme.compoundVariants],
-  defaultVariants: scrollToTopTheme.defaultVariants,
-  classNameResolver: (...args) => twMerge(cx(...args))
-})
-
-const {
-  color = "primary",
-  circleStrokeWidth = 4,
-  duration = 0.1,
-  threshold = 200,
-  ui: uiProp,
-  class: className,
-} = defineProps<RLVScrollToTopProps>()
-
-const globalConfig = getUIConfig()
-
-const mergedUI = defu(
-    uiProp ?? {},
-    (globalConfig["scroll-to-top"] as Record<string, unknown>) ?? {}
-) as Record<keyof typeof scrollToTopTheme.base, string | undefined>
-
-defineSlots<{
-  default(props: {}): any
-}>()
-
-const { root, button, progressBase, svg: svgClass, iconContainer, icon } = scrollToTop({
-  color
-})
-
-const { isVisible, scrollPercentage, scrollToTop: scrollToTopFn } = useScrollToTop({
-  threshold
-})
-
-const circumference = 2 * Math.PI * 45
-const percentPx = circumference / 100
-
-const currentPercent = computed(() => scrollPercentage.value)
-const percentageInPx = computed(() => `${percentPx}px`)
-const durationInSeconds = computed(() => `${duration}s`)
-</script>
-
-<template>
-  <div
-      :class="[
-      'rla-scroll-to-top fixed bottom-6 right-6 z-50',
-      { 'visible': isVisible },
-      twMerge(root, mergedUI.root, className)
-    ]"
-      v-bind="$attrs"
-  >
-    <button
-        type="button"
-        :class="twMerge(button, mergedUI.button)"
-        aria-label="Scroll to top"
-        @click="scrollToTopFn"
-    >
-      <div :class="twMerge(progressBase, mergedUI.progressBase)">
-        <svg :class="twMerge(svgClass, mergedUI.svg)" viewBox="0 0 100 100">
-          <circle
-              cx="50"
-              cy="50"
-              r="45"
-              fill="var(--color-primary-950)"
-              :stroke-width="circleStrokeWidth"
-              stroke-dashoffset="0"
-              stroke-linecap="round"
-              class="gauge-secondary-stroke opacity-100"
-          />
-          <circle
-              cx="50"
-              cy="50"
-              r="45"
-              fill="transparent"
-              :stroke-width="circleStrokeWidth"
-              stroke-linecap="round"
-              class="gauge-primary-stroke opacity-100"
-              :style="{ strokeDasharray: `${(currentPercent / 100) * circumference} ${circumference}` }"
-          />
-        </svg>
-        <div :class="twMerge(iconContainer, mergedUI.iconContainer)">
-          <svg
-              xmlns="http://www.w3.org/2000/svg"
-              width="24"
-              height="24"
-              viewBox="0 0 24 24"
-              fill="none"
-              stroke="currentColor"
-              stroke-width="2"
-              stroke-linecap="round"
-              stroke-linejoin="round"
-              :class="twMerge(icon, mergedUI.icon)"
-          >
-            <path d="m5 12 7-7 7 7" />
-            <path d="M12 19V5" />
-          </svg>
-        </div>
-      </div>
-    </button>
-  </div>
-</template>
-
-<style scoped>
-.rla-scroll-to-top {
-  opacity: 0;
-  pointer-events: none;
-  transition: opacity 0.3s ease-in-out;
-}
-
-.rla-scroll-to-top.visible {
-  opacity: 1;
-  pointer-events: auto;
-}
-
-.progress-circle-base {
-  transform: translateZ(0);
-}
-
-.gauge-primary-stroke {
-  stroke: var(--color-primary-500);
-  transition: stroke-dasharray 0.1s ease, stroke 0.1s ease;
-  transform: rotate(-90deg);
-  transform-origin: center;
-}
-
-.gauge-secondary-stroke {
-  stroke: var(--color-primary-900);
-  stroke-dasharray: 282.6;
-  transform: rotate(-90deg);
-  transform-origin: center;
-}
-</style>
+<script setup lang="ts">
+import { scv, cx } from "css-variants"
+import { twMerge } from "tailwind-merge"
+import defu from "defu"
+import { scrollToTopTheme } from "../../themes/scroll-to-top.theme.ts"
+import { useScrollToTop } from "../../composables/useScrollToTop"
+import { computed } from "vue"
+import { getUIConfig } from "virtual:rimelight-ui"
+
+export interface RLVScrollToTopProps {
+  /**
+   * Button color.
+   *
+   * @default "primary"
+   */
+  color?: keyof typeof scrollToTopTheme.variants.color
+  /**
+   * Transition duration for the progress circle (in seconds).
+   *
+   * @default 0.1
+   */
+  duration?: number
+  /**
+   * Scroll threshold (in pixels) before the button becomes visible.
+   *
+   * @default 200
+   */
+  threshold?: number
+  /**
+   * Whether to show the scroll progress indicator.
+   *
+   * @default false
+   */
+  showProgress?: boolean
+  /**
+   * Stroke width of the progress circle.
+   *
+   * @default 6
+   */
+  progressWidth?: number
+  /**
+   * UI overrides for individual slots, derived from the scroll-to-top theme.
+   */
+  ui?: Partial<Record<keyof typeof scrollToTopTheme.base, string>>
+  /**
+   * External class — applied to the root element.
+   */
+  class?: string
+  /**
+   * Standard HTML attributes.
+   */
+  [key: string]: unknown
+}
+
+const scrollToTop = scv({
+  slots: [...scrollToTopTheme.slots],
+  base: scrollToTopTheme.base,
+  variants: scrollToTopTheme.variants,
+  compoundVariants: [...scrollToTopTheme.compoundVariants],
+  defaultVariants: scrollToTopTheme.defaultVariants,
+  classNameResolver: (...args) => twMerge(cx(...args))
+})
+
+const {
+  color = "primary",
+  progressWidth = 6,
+  duration = 0.1,
+  threshold = 200,
+  showProgress = false,
+  ui: uiProp,
+  class: className
+} = defineProps<RLVScrollToTopProps>()
+
+const globalConfig = getUIConfig()
+
+const mergedUI = defu(
+  uiProp ?? {},
+  (globalConfig["scroll-to-top"] as Record<string, unknown>) ?? {}
+) as Record<keyof typeof scrollToTopTheme.base, string | undefined>
+
+const {
+  root,
+  button,
+  progressBase,
+  svg: svgClass,
+  iconContainer,
+  icon
+} = scrollToTop({
+  color
+})
+
+const {
+  isVisible,
+  scrollPercentage,
+  scrollToTop: scrollToTopFn
+} = useScrollToTop({
+  threshold
+})
+
+const circumference = 2 * Math.PI * 45
+const percentPx = circumference / 100
+
+const currentPercent = computed(() => scrollPercentage.value)
+const percentageInPx = computed(() => `${percentPx}px`)
+const durationInSeconds = computed(() => `${duration}s`)
+</script>
+
+<template>
+  <div
+    :class="[
+      'rla-scroll-to-top fixed bottom-6 right-6 z-50',
+      { visible: isVisible },
+      twMerge(root, mergedUI.root, className)
+    ]"
+    v-bind="$attrs"
+  >
+    <button
+      type="button"
+      :class="twMerge(button, mergedUI.button)"
+      aria-label="Scroll to top"
+      @click="scrollToTopFn"
+    >
+      <div :class="twMerge(progressBase, mergedUI.progressBase)">
+        <svg
+          :class="twMerge(svgClass, mergedUI.svg)"
+          viewBox="0 0 100 100"
+          shape-rendering="geometricPrecision"
+        >
+          <circle
+            cx="50"
+            cy="50"
+            r="45"
+            fill="var(--color-primary-950)"
+            :stroke-width="progressWidth"
+            stroke-dashoffset="0"
+            stroke-linecap="round"
+            class="gauge-secondary-stroke opacity-100"
+          />
+          <circle
+            v-if="showProgress"
+            cx="50"
+            cy="50"
+            r="45"
+            fill="transparent"
+            :stroke-width="progressWidth"
+            stroke-linecap="round"
+            class="gauge-primary-stroke opacity-100"
+            :style="{
+              '--stroke-percent': currentPercent,
+              '--percent-to-px': percentageInPx,
+              '--circumference': circumference,
+              '--duration': durationInSeconds
+            }"
+          />
+        </svg>
+        <div :class="twMerge(iconContainer, mergedUI.iconContainer)">
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="24"
+            height="24"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+            :class="twMerge(icon, mergedUI.icon)"
+          >
+            <path d="m5 12 7-7 7 7" />
+            <path d="M12 19V5" />
+          </svg>
+        </div>
+      </div>
+    </button>
+  </div>
+</template>
+
+<style scoped>
+.rla-scroll-to-top {
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.3s ease-in-out;
+}
+
+.rla-scroll-to-top.visible {
+  opacity: 1;
+  pointer-events: auto;
+}
+
+.progress-circle-base {
+  transform: translateZ(0);
+}
+
+.gauge-primary-stroke {
+  stroke: var(--color-primary-500);
+  --stroke-percent: v-bind(currentPercent);
+  --percent-to-px: v-bind(percentageInPx);
+  --circumference: v-bind(circumference);
+  stroke-dasharray: calc(var(--stroke-percent) * var(--percent-to-px)) var(--circumference);
+  transition:
+    stroke-dasharray v-bind(durationInSeconds) ease,
+    stroke v-bind(durationInSeconds) ease;
+  transform: rotate(-90deg);
+  transform-origin: center;
+  shape-rendering: geometricPrecision;
+}
+
+.gauge-secondary-stroke {
+  stroke: var(--color-primary-900);
+  stroke-dasharray: 282.6;
+  transform: rotate(-90deg);
+  transform-origin: center;
+}
+</style>

package/src/integrations/ui.ts

@@ -11,8 +11,8 @@ import { defaultUIConfig } from "../themes"
  * Shape of the `ui` config that can be passed to the integration.
  */
 export type UIConfigOverrides = {
-  button?: Partial<(typeof defaultUIConfig)["button"]>
-  header?: Partial<(typeof defaultUIConfig)["header"]>
+  "button"?: Partial<(typeof defaultUIConfig)["button"]>
+  "header"?: Partial<(typeof defaultUIConfig)["header"]>
   "scroll-to-top"?: Partial<(typeof defaultUIConfig)["scroll-to-top"]>
 }
 

package/src/plugins/index.ts

@@ -1,2 +1,2 @@
-export { default as starlightAddons } from "../plugins/starlightAddons"
-export type { StarlightAddonsConfig } from "../plugins/starlightAddons"
+export { default as starlightAddons } from "../plugins/starlightAddons"
+export type { StarlightAddonsConfig } from "../plugins/starlightAddons"