@brandocms/jupiter 3.55.0 → 4.0.0-beta.2

package/README.md

@@ -237,7 +237,6 @@ include images from this section. Otherwise, all lightboxed images will be inclu
 
 - `trigger` - `false` - selector representing an element you want to use as a trigger to open lightbox
 - `captions` - `false` - whether to show captions or not in the overlay
-- `swipe` - `true` – if swipe is true, native zoom won't work, so allow choosing
 - `elements` - `object` - switch out default elements in the overlay
   - `arrowRight` - `function` - returns an element
   - `arrowLeft` - `function` - returns an element
@@ -277,6 +276,33 @@ HTML
 </div>
 ```
 
+#### Group Functionality
+
+You can group togglers together to create an accordion-like behavior where only one toggler in the group can be open at a time. When you open one toggler, all others in the same group will close automatically.
+
+```html
+<div data-toggle data-toggle-group="phases">
+  <button data-toggle-trigger="phase1">Phase 1 <span class="arrow icon">&darr;</span></button>
+  <div class="panel" data-toggle-content="phase1">
+    Phase 1 content
+  </div>
+</div>
+
+<div data-toggle data-toggle-group="phases">
+  <button data-toggle-trigger="phase2">Phase 2 <span class="arrow icon">&darr;</span></button>
+  <div class="panel" data-toggle-content="phase2">
+    Phase 2 content
+  </div>
+</div>
+
+<div data-toggle data-toggle-group="phases">
+  <button data-toggle-trigger="phase3">Phase 3 <span class="arrow icon">&darr;</span></button>
+  <div class="panel" data-toggle-content="phase3">
+    Phase 3 content
+  </div>
+</div>
+```
+
 CSS
 ```css
 [data-toggle-trigger] {
@@ -290,6 +316,14 @@ CSS
   }
 }
 
+/* Style active trigger elements */
+[data-toggle-trigger][data-toggle-trigger-active] {
+  background-color: #e8f4ff;
+  border-color: #4a90e2;
+  color: #0056b3;
+  font-weight: bold;
+}
+
 [data-toggle-content] {
   height: 0;
   overflow: hidden;
@@ -313,6 +347,136 @@ togglers.forEach(toggleEl => {
 #### Options
 
 
+## Dataloader
+
+A component for dynamically loading and filtering content via AJAX with optional URL synchronization.
+
+### Basic Usage
+
+HTML:
+```html
+<div data-loader="/api/articles" data-loader-id="articles">
+  <div class="filters">
+    <a href="#" data-loader-param="all" data-loader-param-selected>All</a>
+    <a href="#" data-loader-param="tech" data-loader-param-key="category">Technology</a>
+    <a href="#" data-loader-param="design" data-loader-param-key="category">Design</a>
+  </div>
+  
+  <div data-loader-canvas>
+    <!-- Content will be loaded here -->
+  </div>
+  
+  <button data-loader-more>Load More</button>
+</div>
+```
+
+JavaScript:
+```js
+import { Dataloader } from '@brandocms/jupiter'
+
+const dataloader = new Dataloader(app, $loaderEl, {
+  onFetch: (dataloader) => {
+    // Initialize components after content loads
+    const mw = new Moonwalk(app, {}, dataloader.$canvasEl)
+    new Lazyload(app, {}, dataloader.$canvasEl)
+    mw.ready()
+  }
+})
+```
+
+### URL Synchronization
+
+Enable bidirectional sync between dataloader parameters and browser URL:
+
+```js
+// Configure URL patterns for different dataloaders
+const urlConfigs = {
+  events: {
+    templates: {
+      en: '/events/:location/:type',
+      no: '/arrangementer/:location/:type'
+    },
+    updateOnInit: false // Don't update URL on initialization
+  },
+  news: {
+    templates: {
+      en: '/news/:category/:year',
+      no: '/nyheter/:category/:year'
+    }
+  }
+}
+
+// Initialize all dataloaders with URL sync
+app.dataloaders = []
+Dom.all('[data-loader]').forEach($dl => {
+  app.dataloaders.push(
+    new Dataloader(app, $dl, {
+      urlSync: urlConfigs,
+      onFetch: (dataloader) => {
+        // Your onFetch logic
+      }
+    })
+  )
+})
+```
+
+### Split Layout
+
+Components can be placed outside the main dataloader element:
+
+```html
+<!-- Sidebar -->
+<div data-loader="/api/articles" data-loader-id="articles">
+  <a href="#" data-loader-param="tech" data-loader-param-key="category">Tech</a>
+</div>
+
+<!-- Main content area -->
+<div data-loader-canvas-for="articles">
+  <!-- Content loads here -->
+</div>
+
+<!-- Footer -->
+<button data-loader-more-for="articles">Load More</button>
+<input data-loader-filter-for="articles" placeholder="Search...">
+```
+
+### Options
+
+- `page` - `number` - Initial page number (default: 0)
+- `loaderParam` - `object` - Initial parameters
+- `filter` - `string` - Initial filter value
+- `onFetch` - `function` - Called after content is fetched
+- `urlSync` - `object` - URL synchronization configuration:
+  - `templates` - Language-specific URL templates with `:param` placeholders
+  - `updateOnInit` - `boolean` - Update URL on initialization (default: true)
+  - `languageInPath` - `boolean` - Include language in URL path
+  - `hideDefaultLanguage` - `boolean` - Hide default language from URL (default: true)
+  - `defaultLanguage` - `string` - Default language code (default: 'en')
+  - `buildUrl` - `function` - Custom URL building function
+  - `parseUrl` - `function` - Custom URL parsing function
+
+### Attributes
+
+- `data-loader="/api/endpoint"` - Main container with API endpoint
+- `data-loader-id="unique-id"` - Unique identifier for the dataloader
+- `data-loader-canvas` - Container where content will be loaded
+- `data-loader-canvas-for="id"` - Canvas for specific dataloader (split layout)
+- `data-loader-param="value"` - Parameter value to send to API
+- `data-loader-param-key="key"` - Parameter key (default: 'defaultParam')
+- `data-loader-param-multi` - Allow multiple selections for this parameter
+- `data-loader-param-selected` - Marks parameter as selected
+- `data-loader-more` - Load more button
+- `data-loader-more-for="id"` - Load more for specific dataloader (split layout)
+- `data-loader-filter` - Filter input field
+- `data-loader-filter-for="id"` - Filter for specific dataloader (split layout)
+- `data-loader-loading` - Added during loading
+- `data-loader-starved` - Added to load more button when no more content
+
+### API Response Headers
+
+- `jpt-dataloader: starved` - Set this header when there's no more content to load
+
+
 ## Links
 
 #### Options
@@ -532,36 +696,161 @@ Paragraph one and two will then get a `data-moonwalk="slide"` attribute.
 
 ## Popup
 
+The Popup module allows you to create modal dialogs that appear when triggered by a button click.
+
 ### Options
 
-- `tweenIn: (el, popup) => {}`
-  - Function that gets called to tween popup + background in.
-  - `el` is the popup element itself, while `popup` is the `Popup()` class.
+- `selector` - default `[data-popup]`
+  - CSS selector to find popup elements
+
+- `responsive: (app) => boolean` - default `() => true`
+  - Function to determine if popup should be shown on current breakpoint
+
+- `onOpen: (trigger, target, popup) => {}`
+  - Function called when popup opens
+  - `trigger` is the element that triggered the popup
+  - `target` is the popup element
+  - `popup` is the Popup instance
+
+- `onClose: (popup) => {}`
+  - Function called when popup closes
+  - `popup` is the Popup instance
+
+- `tweenIn: (trigger, target, popup) => {}`
+  - Function for animating the popup opening
+  - `trigger` is the element that triggered the popup
+  - `target` is the popup element
+  - `popup` is the Popup instance
   - Backdrop can be accessed as `popup.backdrop`
 
 - `tweenOut: (popup) => {}`
-  - Function that gets called to tween popup + background out
+  - Function for animating the popup closing
+  - `popup` is the Popup instance
+  - Popup element can be accessed as `popup.currentPopup`
   - Backdrop can be accessed as `popup.backdrop`
 
-- `onClose: (popup) => {}`
-  - Function that gets called right before `popup.close`
+### Basic Usage
+
+HTML:
+
+```html
+<div id="my-popup" data-popup>
+  <div class="popup-header">
+    <h3>My Popup</h3>
+    <button class="close-button" data-popup-close>×</button>
+  </div>
+  <div class="popup-content">
+    <p>This is a popup that appears when the trigger button is clicked.</p>
+  </div>
+</div>
+
+<button data-popup-trigger="#my-popup">Open Popup</button>
+```
 
-### Example
+JavaScript:
+
+```js
+import { Application, Popup } from '@brandocms/jupiter'
+
+const app = new Application()
+const popup = new Popup(app)
+```
 
-Example HTML
+### Advanced Usage with Multiple Popups
+
+You can create multiple independent popups by using the key-based system. This ensures that each popup operates independently, with its own backdrop and close behavior.
+
+HTML:
 
 ```html
-<div class="newsletter-popup" data-popup>
-  ...
-  <button data-popup-close>
+<!-- First popup with key "newsletter" -->
+<div id="newsletter-popup" data-popup data-popup-key="newsletter">
+  <div class="popup-header">
+    <h3>Newsletter Signup</h3>
+    <button class="close-button" data-popup-close>×</button>
+  </div>
+  <div class="popup-content">
+    <p>Sign up for our newsletter!</p>
+  </div>
 </div>
 
-<button data-popup-trigger=".newsletter-popup">
-  Open popup
+<!-- Second popup with key "login" -->
+<div id="login-popup" data-popup data-popup-key="login">
+  <div class="popup-header">
+    <h3>Login</h3>
+    <button class="close-button" data-popup-close>×</button>
+  </div>
+  <div class="popup-content">
+    <p>Enter your credentials to log in.</p>
+  </div>
+</div>
+
+<!-- Triggers for each popup with corresponding keys -->
+<button data-popup-trigger="#newsletter-popup" data-popup-key="newsletter">
+  Subscribe to Newsletter
+</button>
+
+<button data-popup-trigger="#login-popup" data-popup-key="login">
+  Login
 </button>
 ```
 
-Example CSS (PCSS)
+JavaScript:
+
+```js
+import { Application, Popup } from '@brandocms/jupiter'
+
+const app = new Application()
+
+// Create separate instances for different types of popups
+const newsletterPopup = new Popup(app, '[data-popup][data-popup-key="newsletter"]', {
+  onOpen: (trigger, target, popup) => {
+    console.log('Newsletter popup opened')
+  }
+})
+
+const loginPopup = new Popup(app, '[data-popup][data-popup-key="login"]', {
+  onOpen: (trigger, target, popup) => {
+    console.log('Login popup opened')
+  }
+})
+```
+
+### Custom Animations
+
+You can customize the animation for specific popups:
+
+```js
+const customPopup = new Popup(app, '[data-popup][data-popup-key="custom"]', {
+  tweenIn: (trigger, target, popup) => {
+    // Set backdrop visible
+    gsap.set(popup.backdrop, { display: 'block' })
+    gsap.to(popup.backdrop, {
+      duration: 0.3,
+      opacity: 1,
+      onComplete: () => {
+        // Bounce in animation for popup
+        gsap.fromTo(
+          target,
+          {
+            scale: 0.5,
+            opacity: 0,
+            display: 'block'
+          },
+          {
+            duration: 0.5,
+            scale: 1,
+            opacity: 1,
+            ease: 'back.out(1.7)'
+          }
+        )
+      }
+    })
+  }
+})
+```
+
+### CSS Styling
 
 ```scss
 [data-popup] {
@@ -576,9 +865,12 @@ Example CSS (PCSS)
   text-align: center;
   display: none;
   opacity: 0;
-
+  transform: translate(-50%, -50%);
+  border-radius: 6px;
+  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.2);
+  
   @responsive mobile {
-    width: 80%;
+    width: 90%;
   }
 }
 
@@ -586,13 +878,23 @@ Example CSS (PCSS)
   z-index: 4999;
   display: none;
   opacity: 0;
-  background-color: theme(colors.blue.100);
+  background-color: rgba(0, 0, 0, 0.5);
   position: fixed;
   top: 0;
   left: 0;
+  right: 0;
+  bottom: 0;
   height: 100%;
   width: 100%;
 }
+
+.close-button {
+  background: none;
+  border: none;
+  font-size: 20px;
+  cursor: pointer;
+  color: #333;
+}
 ```
 
 
@@ -614,7 +916,15 @@ Example CSS (PCSS)
 </div>
 ```
 
-## StickyHeader
+## DoubleHeader
+
+A dual-header module that clones the original header element. The clone stays fixed and
+hides when scrolling down, revealing on scroll up. Uses IntersectionObserver to detect
+when the original header is visible.
+
+> **Note:** This module was previously named `StickyHeader`. It was renamed to `DoubleHeader`
+> to better reflect its dual-header/clone architecture. The new `StickyHeader` module uses
+> CSS `position: sticky` instead.
 
  * header element should not have position: fixed
 
@@ -647,6 +957,23 @@ Example CSS (PCSS)
       before tweening into view
 
 
+## StickyHeader
+
+A header that uses `position: sticky`. Hides when scrolling down and is revealed on scrolling up.
+Unlike FixedHeader, the sticky header stays in document flow - when hidden via transform,
+its space is still reserved.
+
+> **Note:** This is a new module. If you were using the old `StickyHeader` (which cloned the header),
+> you should now use `DoubleHeader` instead.
+
+ * header element needs `position: sticky; top: 0;`
+ * No padding-top needed on content below (header stays in document flow)
+
+### Options
+
+Same options as FixedHeader - see FixedHeader documentation below.
+
+
 ## FixedHeader
 
  * header element needs position: fixed;
@@ -796,81 +1123,209 @@ Hero example:
 
 ## Parallax
 
+Smooth parallax scrolling effect for images and elements, inspired by SimpleParallax.js.
+
 ### Options
 
 - `el`
   - default `[data-parallax]`
+  - Can also be `[data-parallax-parent]` for multi-element parallax
+
+- `factor`
+  - default `1.3`
+  - Controls the speed of the parallax effect (higher = more movement)
+  - Can be overridden per-element with `data-parallax-factor` attribute
 
 - `fadeContent`
+  - default `true`
+  - If true, fades out content as it leaves the viewport
+  - For multi-element parallax, can be set per-element with `data-parallax-fade` attribute
+
+- `scale`
+  - default `1.2`
+  - Scale factor to apply to parallax background images to prevent gaps during movement
+
+- `orientation`
+  - default `'up'`
+  - Direction of parallax movement: `'up'`, `'down'`, `'left'`, or `'right'`
+  - Can be overridden per-element with `data-parallax-orientation` attribute
+
+- `overflow`
   - default `false`
-  - If true, fades out `[data-parallax-content]` as we move towards bottom of parallaxed element
+  - Whether to allow element overflow to be visible
 
+### Single-Element Parallax
 
-Example:
+For traditional parallax effects with a background and content:
 
 ```html
 <style>
   [data-parallax] {
     position: relative;
-    min-height: 100vh;
+    min-height: 70vh;
     overflow: hidden;
   }
 
   [data-parallax-figure] {
     position: absolute;
-    top: 0;
+    top: -20%;
     left: 0;
-    height: 100%;
-    width: 100%;
-    max-height: 100%;
-  }
-
-  [data-parallax-figure] picture {
-    height: 100%;
     width: 100%;
-  }
-
-  [data-parallax-figure] picture img {
-    min-height: 100%;
-    min-width: 100%;
-    max-height: 100%;
-    object-fit: cover;
+    height: 140%;
+    background-size: cover;
+    background-position: center;
+    will-change: transform;
   }
 
   [data-parallax-content] {
     position: absolute;
     top: 0;
     left: 0;
-    height: 100%;
     width: 100%;
+    height: 100%;
     display: flex;
+    flex-direction: column;
     justify-content: center;
     align-items: center;
+    color: white;
+    text-align: center;
+    background-color: rgba(0, 0, 0, 0.3);
+    z-index: 1;
+    will-change: transform, opacity;
   }
+</style>
 
-  [data-parallax-content] div {
-    color: #ffffff;
-    font-size: 4rem;
+<section data-parallax>
+  <div 
+    data-parallax-figure 
+    style="background-image: url('/path/to/image.jpg');"
+  ></div>
+  <div data-parallax-content>
+    <h2>Parallax Title</h2>
+    <p>Parallax content with automatic fade effect</p>
+  </div>
+</section>
+```
+
+### Multi-Element Parallax
+
+For creating parallax effects with multiple elements, each with their own movement speed and fade settings:
+
+```html
+<style>
+  [data-parallax-parent] {
+    position: relative;
+    height: 80vh;
+    overflow: hidden;
+  }
+  
+  .parallax-element {
+    position: absolute;
+    width: 200px;
+    height: 200px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    color: white;
+    font-weight: bold;
+    text-align: center;
+    border-radius: 10px;
+    will-change: transform, opacity;
+  }
+  
+  /* Position elements as needed */
+  .element-1 {
+    background-color: #e74c3c;
+    left: 20%;
+    top: 30%;
+  }
+  
+  .element-2 {
+    background-color: #3498db;
+    left: 50%;
+    top: 40%;
+  }
+  
+  .element-3 {
+    background-color: #2ecc71;
+    left: 70%;
+    top: 50%;
   }
 </style>
 
+<div data-parallax-parent>
+  <!-- Slow element moving down -->
+  <div 
+    class="parallax-element element-1" 
+    data-parallax-factor="0.8" 
+    data-parallax-orientation="down"
+  >
+    Slow downward movement
+  </div>
+  
+  <!-- Medium element with fade effect -->
+  <div 
+    class="parallax-element element-2" 
+    data-parallax-factor="1.5" 
+    data-parallax-fade
+  >
+    Medium upward movement with fade
+  </div>
+  
+  <!-- Fast element without fade moving left -->
+  <div 
+    class="parallax-element element-3" 
+    data-parallax-factor="2.5"
+    data-parallax-orientation="left"
+  >
+    Fast leftward movement
+  </div>
+</div>
+```
+
+### Initialize in JS
+
+```js
+import { Application, Parallax } from '@brandocms/jupiter'
+
+const app = new Application()
+
+// Traditional parallax with background image and content
+const singleParallax = new Parallax(app, {
+  // Default options
+  factor: 1.3,
+  fadeContent: true,
+  scale: 1.2  
+})
+
+// Multi-element parallax
+const multiParallax = new Parallax(app, {
+  el: '[data-parallax-parent]',
+  orientation: 'up'  // Default movement direction
+})
+
+// Cleanup when needed
+function cleanup() {
+  singleParallax.destroy()
+  multiParallax.destroy()
+}
+```
+
+### Using with picture elements
+
+For using parallax with responsive images:
+
+```html
 <section data-parallax>
   <div data-parallax-figure>
-    <%= picture_tag(
-      work.cover,
-      placeholder: false,
-      key: :original,
-      lazyload: true,
-      srcset: {Kunstnerforbundet.Artists.Work, :cover},
-      prefix: media_url(),
-      img_class: "img-fluid",
-      alt: "#{work.title} (#{work.year}) - #{work.size} - #{work.technique}")
-    %>
+    <picture>
+      <source media="(min-width: 1200px)" srcset="/images/large.jpg">
+      <source media="(min-width: 768px)" srcset="/images/medium.jpg">
+      <img src="/images/small.jpg" alt="Parallax image">
+    </picture>
   </div>
   <div data-parallax-content>
-    <div>
-      Testing some parallax :)
-    </div>
+    <h2>Responsive Parallax</h2>
   </div>
 </section>
 ```