release 1.0.0

Author: smastrom

README.md

@@ -2,7 +2,7 @@
 
 # Vue Use Fixed Header
 
-Turn your boring fixed header into a smart one with one line of code.
+Turn your boring fixed header into a smart one with three lines of code.
 
 <br />
 
@@ -12,13 +12,12 @@ Turn your boring fixed header into a smart one with one line of code.
 
 ## Features
 
--  **Dead simple** - Call a function and you're done whether you're SSR'ing or not
--  **Lightweight** - Just over 1kb without any dependency
--  **Enjoyable** - When scrolling down, the header is hidden, when scrolling up, the header is shown.
--  **Powerful** - Uses acceleration delta for both hiding and showing instead of fixed thresholds
--  **User-centric** - Behaves as your users expect on page load, scroll restoration, hovering, dropdown navigation, top reached and reduced motion.
+-  **Dead simple** - Write three lines of code and you're done.
+-  **Enjoyable defaults** - When scrolling down, the header is hidden, when scrolling up, the header is shown.
+-  **Powerful** - Uses acceleration delta (scroll speed) for both hiding and showing instead of fixed thresholds.
+-  **Intuitive** - Behaves as expected on page load, scroll restoration, hovering, dropdown navigation, top-reached and reduced motion.
 -  **Smart** - Functionalities are automatically enabled/disabled if your header turns from fixed/sticky to something else or it is hidden at different viewports
--  **Flexible** - Works with any scrolling container and with your own transition styles
+-  **Flexible** - Works with any scrolling container and with your own styles
 
 <br />
 
@@ -28,11 +27,21 @@ Turn your boring fixed header into a smart one with one line of code.
 pnpm add vue-use-fixed-header
 ```
 
+Or:
+
+```bash
+yarn add vue-use-fixed-header
+```
+
+```bash
+npm i vue-use-fixed-header
+```
+
 <br />
 
 ## Usage
 
-Pass your header's template ref to `useFixedHeader`. Then style it as you normally would. That's it.
+Pass your header's template ref to `useFixedHeader`. Then apply the returned reactive styles. That's it.
 
 ```vue
 <script setup>
@@ -41,11 +50,11 @@ import { useFixedHeader } from 'vue-use-fixed-header'
 
 const headerRef = ref(null)
 
-useFixedHeader(headerRef)
+const { styles } = useFixedHeader(headerRef)
 </script>
 
 <template>
-   <header class="Header" ref="headerRef">
+   <header class="Header" ref="headerRef" :style="styles">
       <!-- Your content -->
    </header>
 </template>
@@ -59,35 +68,33 @@ useFixedHeader(headerRef)
 </style>
 ```
 
-As long as your header position is set to fixed/sticky, it will behave as described in the [features](#features) section.
-
-> :warning: There's only **one rule** to respect: Do not apply any _transition-related_ property since they're handled internally. See [below](#customization) how to customize them.
+All you have to do is to set `position: fixed` (or `sticky`) to your header. `useFixedHeader` will take care of the rest.
 
 <br />
 
 ## Automatic behavior toggling
 
 On resize, `useFixedHeader` checks your header's `position` and `display` properties to determine whether its functionalities should be enabled or not.
 
-_Disabled_ means that the header will behave as you're not using the composable at all: no event listeners are attached and no additional styles are applied.
+_Disabled_ means that no event listeners are attached and the returned styles match an empty object `{}`.
 
 ### Different viewports
 
-If at different viewports your header position is not fixed/sticky (or it is hidden), functionalities are automatically toggled when needed.
-
-So feel free to have code like this:
+Hence feel free to have code like this:
 
 ```css
 .Header {
    position: fixed;
 }
 
+/* Will be disabled */
 @media (max-width: 768px) {
    .Header {
       position: relative;
    }
 }
 
+/* Same */
 @media (max-width: 375px) {
    .Header {
       display: none;
@@ -132,28 +139,41 @@ useFixedHeader(headerRef, {
 ## Customization
 
 ```ts
-useFixedHeader(headerRef, {
+const { styles, isEnter, isLeave } = useFixedHeader(headerRef, {
    /**
+    *
     * Use `null` if content is scrolled by the window,
     * otherwise pass a custom scrolling container template ref */
    root: null,
    /**
+    *
     * ref or computed to watch for automatic behavior toggling */
    watch: () => null,
    /**
-    * Minimum acceleration delta required to show the header */
+    *
+    * Minimum acceleration delta required to show the header.
+    * An higher value means that the user has to scroll faster. */
    enterDelta: 0.5,
    /**
+    *
     * Minimum acceleration delta required to hide the header */
    leaveDelta: 0.15,
    /**
-    * Custom enter transition styles */
+    *
+    * Whether to toggle `visibility: hidden` on leave.
+    * Set this to `false` if you want to keep the header
+    * visible. */
+   toggleVisibility: true,
+   /**
+    *
+    * Custom styles applied when scrolling up */
    enterStyles: {
       transition: `transform 0.3s ease-out`,
       transform: 'translateY(0px)',
    },
    /**
-    * Custom leave transition styles */
+    *
+    * Custom styles applied when scrolling down */
    leaveStyles: {
       transition: `transform 0.5s ease-out`,
       transform: 'translateY(-100%)',

demo/Header.vue

@@ -1,15 +1,26 @@
 <script setup lang="ts">
-import { ref } from 'vue'
+import { ref, watchEffect } from 'vue'
 import { useFixedHeader } from '../src'
 
 const headerRef = ref<HTMLElement | null>(null)
 
-useFixedHeader(headerRef)
+const { styles, isEnter, isLeave } = useFixedHeader(headerRef, {
+   toggleVisibility: true,
+})
+
+watchEffect(() => {
+   console.table([
+      {
+         isEnter: isEnter.value,
+         isLeave: isLeave.value,
+      },
+   ])
+})
 </script>
 
 <template>
    <div>
-      <header class="Header" ref="headerRef">
+      <header class="Header" ref="headerRef" :style="styles">
          <div class="Nav">
             <h2 class="Global_Logo">Vufh</h2>
             <ul class="Nav_List">
@@ -167,3 +178,4 @@ useFixedHeader(headerRef)
    }
 }
 </style>
+../src/useFixedHeader

demo/WithContainer.vue

@@ -7,15 +7,15 @@ import Header from './Header.vue'
 const containerRef = ref<HTMLElement | null>(null)
 const headerRef = ref<HTMLElement | null>(null)
 
-useFixedHeader(headerRef, {
+const { styles } = useFixedHeader(headerRef, {
    root: containerRef,
 })
 </script>
 
 <template>
    <div class="Scroll_Container" ref="containerRef">
       <div class="Container">
-         <header class="Header_Wrapper" ref="headerRef">
+         <header class="Header_Wrapper" ref="headerRef" :style="styles">
             <div class="Header_Container">
                <h2 class="Global_Logo">Vufh</h2>
 
@@ -80,7 +80,9 @@ useFixedHeader(headerRef, {
    line-height: 1;
    padding: 0.65rem 1rem;
    text-decoration: none;
-   transition: color 200ms ease-in-out, background-color 200ms ease-in-out;
+   transition:
+      color 200ms ease-in-out,
+      background-color 200ms ease-in-out;
 }
 
 @media (hover: hover) {
@@ -103,3 +105,4 @@ useFixedHeader(headerRef, {
    text-align: center;
 }
 </style>
+../src/useFixedHeader

package.json

@@ -1,8 +1,8 @@
 {
    "name": "vue-use-fixed-header",
-   "description": "Turn your boring fixed header into a smart one.",
+   "description": "Turn your boring fixed header into a smart one with three lines of code.",
    "private": false,
-   "version": "0.9.8",
+   "version": "1.0.0",
    "type": "module",
    "keywords": [
       "vue",
@@ -31,7 +31,7 @@
    "exports": {
       ".": {
          "import": "./dist/index.js",
-         "require": "./dist/index.cjs"
+         "types": "./dist/index.d.ts"
       }
    },
    "main": "dist/index.cjs",
@@ -42,9 +42,9 @@
    ],
    "scripts": {
       "dev": "vite",
-      "build": "rimraf dist && vue-tsc && vite build",
+      "build": "rm -rf dist && vue-tsc && vite build",
       "postbuild": "pnpm pack",
-      "build:demo": "rimraf dist && vue-tsc && vite build --mode demo",
+      "build:demo": "rm -rf dist && vue-tsc && vite build --mode demo",
       "preview": "vite preview --mode demo",
       "test": "pnpm run test:chrome && pnpm run test:firefox && pnpm run test:container:chrome && pnpm run test:container:firefox",
       "test:chrome": "cypress run --component --browser chrome",
@@ -58,16 +58,14 @@
    },
    "devDependencies": {
       "@rollup/plugin-terser": "^0.4.3",
-      "@types/node": "^20.4.5",
+      "@types/node": "^20.5.0",
       "@vitejs/plugin-vue": "^4.2.3",
-      "@vue/compiler-dom": "^3.3.4",
-      "cypress": "^12.17.2",
-      "cypress-real-events": "^1.9.1",
+      "cypress": "^12.17.4",
+      "cypress-real-events": "^1.10.0",
       "playwright-webkit": "~1.34.3",
-      "rimraf": "^5.0.1",
       "typescript": "^5.1.6",
-      "vite": "^4.4.7",
-      "vite-plugin-dts": "^3.3.1",
+      "vite": "^4.4.9",
+      "vite-plugin-dts": "^3.5.2",
       "vue": "^3.3.4",
       "vue-tsc": "^1.8.8"
    }