@refokus-agency/navigation 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 YOUR_NAME_HERE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,233 @@
+# @refokus-agency/navigation
+
+A TypeScript package for implementing smooth navbar animations with GSAP, featuring scroll-based show/hide behavior and customizable animation settings.
+
+## Features
+
+- ✨ Smooth GSAP-powered animations
+- 📜 Scroll-based navbar show/hide behavior
+- ⚙️ Configurable animation settings
+- 🎯 Attribute-based element selection
+- 📦 ES Module-only package (no CommonJS support)
+- 🔧 Modern TypeScript configuration with strict mode
+- 🧪 Testing setup with Vitest
+- 🎨 Code formatting with Prettier
+- 🔍 Linting with ESLint (flat config)
+- 🏗️ Build pipeline with TypeScript compiler
+- 📝 Source maps for debugging
+
+## Requirements
+
+- Node.js >= 22.0.0
+
+## Installation
+
+```bash
+npm install @refokus-agency/navigation
+```
+
+## Usage
+
+### Basic Setup
+
+1. Add the `r-navbar` attribute to your navbar element(s):
+
+```html
+<nav r-navbar>
+  <!-- Your navbar content -->
+</nav>
+```
+
+2. Initialize the navbar animation system:
+
+```typescript
+import { initNavbarAnimation } from '@refokus-agency/navigation';
+
+// Initialize with custom options
+const success = initNavbarAnimation({
+  animationDuration: 0.3,
+  animationEasing: 'power2.inOut',
+});
+
+if (success) {
+  console.log('Navbar animation initialized');
+}
+```
+
+### How It Works
+
+- **Initial Animation**: Navbar slides in smoothly on page load
+- **Scroll Down**: Navbar hides when scrolling down past threshold (50px)
+- **Scroll Up**: Navbar shows when scrolling up
+- **Multiple Navbars**: Supports multiple navbar elements with the same attribute
+
+## Development
+
+### Available Scripts
+
+#### Building
+
+```bash
+npm run build          # Compile TypeScript
+npm run build:clean    # Clean and rebuild
+npm run build:watch    # Watch mode
+```
+
+#### Testing
+
+```bash
+npm test               # Run tests
+npm run test:watch     # Watch mode
+npm run test:coverage  # With coverage
+npm run test:ui        # With UI
+```
+
+#### Code Quality
+
+```bash
+npm run check-types    # Type checking
+npm run lint           # Lint and fix
+npm run format         # Format code
+```
+
+## Project Structure
+
+```
+src/
+├── index.ts                    # Main entry point
+└── nav-anim/
+    ├── index.ts                # Navbar animation initialization
+    ├── config.ts               # Configuration constants
+    ├── initial-animation.ts    # Initial slide-in animation
+    ├── scroll-behaviour.ts     # Scroll-based show/hide logic
+    └── __tests__/
+      ├── index.test.ts             # Initialization tests
+      └── scroll-behaviour.test.ts  # Scroll behavior tests
+```
+
+## Configuration
+
+The package uses the following default configuration:
+
+```typescript
+{
+  position: {
+    hidden: '-100%',   // Y position when hidden
+    visible: '0%'      // Y position when visible
+  },
+  scroll: {
+    threshold: 50      // Minimum scroll distance to trigger animation
+  },
+  selectors: {
+    navbar: '[r-navbar]' // Attribute selector for navbar elements
+  }
+}
+```
+
+## Publishing
+
+This package uses automated semantic versioning and publishing through GitHub Actions. The release process is triggered automatically on pushes to the `main` branch (or manually via the **Release** workflow's `workflow_dispatch`) and publishes to the **public npm registry** (`registry.npmjs.org`) under the `@refokus-agency` scope.
+
+### Release Process
+
+The publishing workflow (`.github/workflows/main-release.yml`, named **Release**) calls the `refokus-agency/platform` reusable workflows (`ci.yml` then `release.yml`) and handles:
+
+1. **Automatic Triggering**: Release checks run on push to the `main` branch.
+
+2. **Authentication**: Publishing to npm uses **OIDC Trusted Publishing** — there is **no `NPM_TOKEN`** secret. The caller grants `permissions: id-token: write`, which lets npm mint a short-lived credential at publish time. For this to work, a **Trusted Publisher** must be configured for `@refokus-agency/navigation` on [npmjs.com](https://docs.npmjs.com/trusted-publishers) (Package settings → Trusted Publisher), pointing at this repository (`refokus-agency/navigation`) with the **workflow filename `release.yml`**. Note: `release.yml` is the **reusable workflow in the `refokus-agency/platform` repo** — *not* a file in this repo (this repo only has `main-release.yml`). npm matches the OIDC token's `job_workflow_ref` claim, which for a reusable workflow resolves to the reusable's path, so enter exactly `release.yml`.
+
+### Semantic Versioning
+
+> **⚠️ WARNING:**
+> This repository uses automated semantic versioning and publishing.
+> **Do not publish manually with `npm publish`.**
+> All releases are handled by GitHub Actions via semantic-release.
+>
+> To trigger a release, push to the `main` branch or use the GitHub Actions workflow manually.
+>
+> Ensure your commits follow [Conventional Commits](https://www.conventionalcommits.org/) to enable correct versioning and changelog generation.
+> In order to do that, you MUST run `npm run commit` to use the Commitizen wizard and stay compliant with our versioning standards.
+
+The project uses [semantic-release](https://semantic-release.gitbook.io/) for automated version management based on conventional commits:
+
+- **Major version** (`x.0.0`): Breaking changes (commits with `BREAKING CHANGE:` or `!:`)
+- **Minor version** (`0.x.0`): New features (commits with `feat:`)
+- **Patch version** (`0.0.x`): Bug fixes (commits with `fix:`)
+
+### Commit Message Format
+
+Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
+
+```bash
+# Feature
+feat: add new functionality
+
+# Bug fix
+fix: resolve issue with feature
+
+# Breaking change
+feat!: remove deprecated API
+# or
+feat: add new API
+BREAKING CHANGE: old API has been removed
+
+# Documentation
+docs: update README
+
+# Style changes
+style: format code
+
+# Refactoring
+refactor: restructure code
+
+# Performance
+perf: improve performance
+
+# Tests
+test: add unit tests
+```
+
+### Publishing to public npm
+
+The package is published to the **public npm registry** under the `@refokus-agency` scope, so consumers can `npm install @refokus-agency/navigation` with no auth or registry configuration. The release:
+
+- Targets the public npm registry (`https://registry.npmjs.org`) via `publishConfig`
+- Publishes as a **public** scoped package (`access: public`)
+- Authenticates with **OIDC Trusted Publishing** — no `NPM_TOKEN` secret; the workflow requires `id-token: write`
+- Keeps npm **provenance disabled** because the repository is currently private (provenance requires a public repo). When the repo is made public, flip `provenance: true` on the `release.yml` caller to enable signed provenance
+
+> **Peer dependency:** `gsap` is a **peer dependency** and is not bundled. Consumers must install it themselves (`npm install gsap`), or provide it globally as Webflow/CDN setups already do.
+
+### Manual Release
+
+To trigger a release manually:
+
+1. Go to the GitHub repository
+2. Navigate to the **Actions** tab
+3. Select the **Release** workflow
+4. Click **Run workflow**
+5. Choose the branch (usually `main`)
+6. Click **Run workflow**
+
+### Prerequisites
+
+Before publishing, ensure:
+
+- All tests pass (`npm test`)
+- Code is properly formatted (`npm run format`)
+- Linting passes (`npm run lint`)
+- Type checking passes (`npm run check-types`)
+- Commit messages follow conventional commits format
+
+### Release Notes
+
+Semantic-release automatically:
+
+- Generates changelog based on commit messages
+- Creates GitHub releases with release notes
+- Tags releases in Git
+- Updates package version in `package.json`
+
+## License
+
+See [LICENSE](LICENSE) file.

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { initNavbarAnimation, type InitNavbarAnimationOptions, } from './nav-anim/index.ts';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { initNavbarAnimation, } from "./nav-anim/index.js";
+//# sourceMappingURL=index.js.map

package/dist/nav-anim/config.d.ts

@@ -0,0 +1,12 @@
+export declare const NAVBAR_CONFIG: {
+    position: {
+        hidden: string;
+        visible: string;
+    };
+    scroll: {
+        threshold: number;
+    };
+    selectors: {
+        navbar: string;
+    };
+};

package/dist/nav-anim/config.js

@@ -0,0 +1,13 @@
+export const NAVBAR_CONFIG = {
+    position: {
+        hidden: '-100%',
+        visible: '0%',
+    },
+    scroll: {
+        threshold: 50,
+    },
+    selectors: {
+        navbar: '[r-navbar]',
+    },
+};
+//# sourceMappingURL=config.js.map

package/dist/nav-anim/index.d.ts

@@ -0,0 +1,10 @@
+export type NavbarAnimationOptions = {
+    animationDuration: number;
+    animationEasing: string;
+};
+export type InitNavbarAnimationOptions = Partial<NavbarAnimationOptions>;
+/**
+ * Initializes navbar animation system
+ * @returns Whether initialization was successful
+ */
+export declare function initNavbarAnimation(options?: InitNavbarAnimationOptions): boolean;

package/dist/nav-anim/index.js

@@ -0,0 +1,25 @@
+import { NAVBAR_CONFIG } from "./config.js";
+import { performInitialAnimation } from "./initial-animation.js";
+import { initScrollBehavior } from "./scroll-behaviour.js";
+const DEFAULT_OPTIONS = {
+    animationDuration: 0.3,
+    animationEasing: 'power2.inOut',
+};
+/**
+ * Initializes navbar animation system
+ * @returns Whether initialization was successful
+ */
+export function initNavbarAnimation(options = {}) {
+    const navbarElements = document.querySelectorAll(NAVBAR_CONFIG.selectors.navbar);
+    if (!navbarElements.length)
+        return false;
+    const resolvedOptions = {
+        ...DEFAULT_OPTIONS,
+        ...options,
+    };
+    const elements = Array.from(navbarElements);
+    performInitialAnimation(elements, resolvedOptions);
+    initScrollBehavior(elements, resolvedOptions);
+    return true;
+}
+//# sourceMappingURL=index.js.map

package/dist/nav-anim/initial-animation.d.ts

@@ -0,0 +1,14 @@
+import type { NavbarAnimationOptions } from './index.ts';
+/**
+ * Creates navbar slide animation
+ * @param elements - Navbar elements to animate
+ * @param targetY - Target Y position
+ * @returns GSAP tween instance
+ */
+export declare function createNavbarAnimation(elements: Element[], targetY: string, options: NavbarAnimationOptions): gsap.core.Tween;
+/**
+ * Performs initial navbar slide-in animation
+ * @param navbarElements - Navbar elements to animate
+ * @param options - Animation options
+ */
+export declare function performInitialAnimation(navbarElements: Element[], options: NavbarAnimationOptions): void;

package/dist/nav-anim/initial-animation.js

@@ -0,0 +1,26 @@
+import { gsap } from 'gsap';
+import { NAVBAR_CONFIG } from "./config.js";
+/**
+ * Creates navbar slide animation
+ * @param elements - Navbar elements to animate
+ * @param targetY - Target Y position
+ * @returns GSAP tween instance
+ */
+export function createNavbarAnimation(elements, targetY, options) {
+    return gsap.to(elements, {
+        y: targetY,
+        duration: options.animationDuration,
+        ease: options.animationEasing,
+        overwrite: true,
+    });
+}
+/**
+ * Performs initial navbar slide-in animation
+ * @param navbarElements - Navbar elements to animate
+ * @param options - Animation options
+ */
+export function performInitialAnimation(navbarElements, options) {
+    gsap.set(navbarElements, { y: NAVBAR_CONFIG.position.hidden });
+    createNavbarAnimation(navbarElements, NAVBAR_CONFIG.position.visible, options);
+}
+//# sourceMappingURL=initial-animation.js.map

package/dist/nav-anim/scroll-behaviour.d.ts

@@ -0,0 +1,9 @@
+import type { NavbarAnimationOptions } from './index.ts';
+/**
+ * Removes scroll event listener for cleanup
+ */
+export declare function cleanupNavbarAnimation(): void;
+/**
+ * Initializes navbar scroll behavior
+ */
+export declare function initScrollBehavior(elements: Element[], options: NavbarAnimationOptions): void;

package/dist/nav-anim/scroll-behaviour.js

@@ -0,0 +1,83 @@
+import { NAVBAR_CONFIG } from "./config.js";
+import { createNavbarAnimation } from "./initial-animation.js";
+let lastScrollY = 0;
+let isNavbarVisible = true;
+let scrollHandlerBound = null;
+let currentOptions = null;
+let navbarElements = [];
+/**
+ * Shows the navbar by sliding it down
+ */
+function showNavbar() {
+    if (isNavbarVisible || navbarElements.length === 0 || !currentOptions)
+        return;
+    createNavbarAnimation(navbarElements, NAVBAR_CONFIG.position.visible, currentOptions);
+    isNavbarVisible = true;
+}
+/**
+ * Hides the navbar by sliding it up
+ */
+function hideNavbar() {
+    if (!isNavbarVisible || navbarElements.length === 0 || !currentOptions)
+        return;
+    createNavbarAnimation(navbarElements, NAVBAR_CONFIG.position.hidden, currentOptions);
+    isNavbarVisible = false;
+}
+/**
+ * Determines if scroll distance is significant enough to trigger animation
+ * @param currentScrollY - Current scroll position
+ * @returns Whether scroll is significant
+ */
+function isSignificantScroll(currentScrollY) {
+    return (Math.abs(currentScrollY - lastScrollY) >= NAVBAR_CONFIG.scroll.threshold);
+}
+/**
+ * Determines if user is scrolling down past threshold
+ * @param currentScrollY - Current scroll position
+ * @returns Whether user is scrolling down past threshold
+ */
+function isScrollingDownPastThreshold(currentScrollY) {
+    return (currentScrollY > lastScrollY &&
+        currentScrollY > NAVBAR_CONFIG.scroll.threshold);
+}
+/**
+ * Handles scroll events to show/hide navbar based on direction
+ */
+function handleScroll() {
+    const currentScrollY = window.scrollY;
+    if (!isSignificantScroll(currentScrollY))
+        return;
+    if (isScrollingDownPastThreshold(currentScrollY)) {
+        hideNavbar();
+    }
+    else {
+        showNavbar();
+    }
+    lastScrollY = currentScrollY;
+}
+/**
+ * Removes scroll event listener for cleanup
+ */
+export function cleanupNavbarAnimation() {
+    if (scrollHandlerBound) {
+        window.removeEventListener('scroll', scrollHandlerBound);
+        scrollHandlerBound = null;
+    }
+    navbarElements = [];
+    currentOptions = null;
+}
+/**
+ * Initializes navbar scroll behavior
+ */
+export function initScrollBehavior(elements, options) {
+    if (scrollHandlerBound) {
+        window.removeEventListener('scroll', scrollHandlerBound);
+    }
+    currentOptions = options;
+    navbarElements = elements;
+    isNavbarVisible = true;
+    lastScrollY = window.scrollY;
+    scrollHandlerBound = handleScroll;
+    window.addEventListener('scroll', scrollHandlerBound, { passive: true });
+}
+//# sourceMappingURL=scroll-behaviour.js.map

package/dist/navigation.browser.js

@@ -0,0 +1,74 @@
+import { gsap as d } from "gsap";
+const t = {
+  position: {
+    hidden: "-100%",
+    visible: "0%"
+  },
+  scroll: {
+    threshold: 50
+  },
+  selectors: {
+    navbar: "[r-navbar]"
+  }
+};
+function c(n, i, e) {
+  return d.to(n, {
+    y: i,
+    duration: e.animationDuration,
+    ease: e.animationEasing,
+    overwrite: !0
+  });
+}
+function f(n, i) {
+  d.set(n, { y: t.position.hidden }), c(
+    n,
+    t.position.visible,
+    i
+  );
+}
+let a = 0, r = !0, s = null, o = null, l = [];
+function h() {
+  r || l.length === 0 || !o || (c(
+    l,
+    t.position.visible,
+    o
+  ), r = !0);
+}
+function v() {
+  !r || l.length === 0 || !o || (c(
+    l,
+    t.position.hidden,
+    o
+  ), r = !1);
+}
+function m(n) {
+  return Math.abs(n - a) >= t.scroll.threshold;
+}
+function b(n) {
+  return n > a && n > t.scroll.threshold;
+}
+function p() {
+  const n = window.scrollY;
+  m(n) && (b(n) ? v() : h(), a = n);
+}
+function w(n, i) {
+  s && window.removeEventListener("scroll", s), o = i, l = n, r = !0, a = window.scrollY, s = p, window.addEventListener("scroll", s, { passive: !0 });
+}
+const g = {
+  animationDuration: 0.3,
+  animationEasing: "power2.inOut"
+};
+function N(n = {}) {
+  const i = document.querySelectorAll(
+    t.selectors.navbar
+  );
+  if (!i.length) return !1;
+  const e = {
+    ...g,
+    ...n
+  }, u = Array.from(i);
+  return f(u, e), w(u, e), !0;
+}
+export {
+  N as initNavbarAnimation
+};

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@refokus-agency/navigation",
+  "version": "1.0.2",
+  "type": "module",
+  "description": "A TypeScript package for GSAP-powered navbar animations with scroll-based show/hide behavior",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/**/*",
+    "!dist/**/*.map",
+    "!dist/**/__tests__/**",
+    "README.md",
+    "LICENSE"
+  ],
+  "author": "Refokus Agency",
+  "keywords": [
+    "navbar",
+    "animation",
+    "gsap",
+    "scroll",
+    "typescript",
+    "webflow"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/refokus-agency/navigation.git"
+  },
+  "bugs": {
+    "url": "https://github.com/refokus-agency/navigation/issues"
+  },
+  "homepage": "https://github.com/refokus-agency/navigation#readme",
+  "scripts": {
+    "build": "tsc && npm run build:browser",
+    "build:browser": "vite build",
+    "build:clean": "rimraf dist && npm run build",
+    "build:watch": "tsc --watch",
+    "prepublishOnly": "npm run check-types && npm run lint && npm run build:clean",
+    "check-types": "tsc --noEmit --strict --skipLibCheck",
+    "typecheck": "tsc --noEmit --strict --skipLibCheck",
+    "lint": "eslint src --ext .ts --fix",
+    "lint:report": "eslint src --ext .ts",
+    "format": "prettier --write \"src/**/*.{ts,js,json}\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:ui": "vitest --ui",
+    "commit": "cz"
+  },
+  "peerDependencies": {
+    "gsap": "^3.14.2"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "@total-typescript/tsconfig": "^1.0.4",
+    "@types/node": "^25.5.0",
+    "@types/webidl-conversions": "^7.0.3",
+    "@typescript-eslint/eslint-plugin": "^8.57.0",
+    "@typescript-eslint/parser": "^8.57.0",
+    "@vitest/ui": "^3.2.4",
+    "commitizen": "^4.3.1",
+    "cz-conventional-changelog": "3.3.0",
+    "eslint": "^10.0.3",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-n": "^17.21.0",
+    "gsap": "^3.14.2",
+    "jsdom": "^29.0.0",
+    "prettier": "^3.6.2",
+    "rimraf": "^6.1.3",
+    "typescript": "^5.8.3",
+    "vite": "^7.3.1",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  }
+}