@sc4rfurryx/proteusjs 1.0.0 → 1.1.0

package/src/modules/scroll/index.ts

@@ -0,0 +1,251 @@
+/**
+ * @sc4rfurryx/proteusjs/scroll
+ * Scroll-driven animations with CSS Scroll-Linked Animations
+ * 
+ * @version 1.1.0
+ * @author sc4rfurry
+ * @license MIT
+ */
+
+export interface ScrollAnimateOptions {
+  keyframes: Keyframe[];
+  range?: [string, string];
+  timeline?: {
+    axis?: 'block' | 'inline';
+    start?: string;
+    end?: string;
+  };
+  fallback?: 'io' | false;
+}
+
+/**
+ * Zero-boilerplate setup for CSS Scroll-Linked Animations with fallbacks
+ */
+export function scrollAnimate(
+  target: Element | string,
+  opts: ScrollAnimateOptions
+): void {
+  const targetEl = typeof target === 'string' ? document.querySelector(target) : target;
+  if (!targetEl) {
+    throw new Error('Target element not found');
+  }
+
+  const {
+    keyframes,
+    range = ['0%', '100%'],
+    timeline = {},
+    fallback = 'io'
+  } = opts;
+
+  const {
+    axis = 'block',
+    start = '0%',
+    end = '100%'
+  } = timeline;
+
+  // Check for CSS Scroll-Linked Animations support
+  const hasScrollTimeline = 'CSS' in window && CSS.supports('animation-timeline', 'scroll()');
+
+  // Check for reduced motion preference
+  const prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+  if (prefersReducedMotion) {
+    // Respect user preference - either disable or reduce animation
+    if (fallback === false) return;
+    
+    // Apply only the end state for reduced motion
+    const endKeyframe = keyframes[keyframes.length - 1];
+    Object.assign((targetEl as HTMLElement).style, endKeyframe);
+    return;
+  }
+
+  if (hasScrollTimeline) {
+    // Use native CSS Scroll-Linked Animations
+    const timelineName = `scroll-timeline-${Math.random().toString(36).substr(2, 9)}`;
+    
+    // Create scroll timeline
+    const style = document.createElement('style');
+    style.textContent = `
+      @scroll-timeline ${timelineName} {
+        source: nearest;
+        orientation: ${axis};
+        scroll-offsets: ${start}, ${end};
+      }
+      
+      .scroll-animate-${timelineName} {
+        animation-timeline: ${timelineName};
+        animation-duration: 1ms; /* Required but ignored */
+        animation-fill-mode: both;
+      }
+    `;
+    document.head.appendChild(style);
+
+    // Apply animation class
+    targetEl.classList.add(`scroll-animate-${timelineName}`);
+
+    // Create Web Animations API animation
+    const animation = targetEl.animate(keyframes, {
+      duration: 1, // Required but ignored with scroll timeline
+      fill: 'both'
+    });
+
+    // Set scroll timeline (when supported)
+    if ('timeline' in animation) {
+      (animation as any).timeline = new (window as any).ScrollTimeline({
+        source: document.scrollingElement,
+        orientation: axis,
+        scrollOffsets: [
+          { target: targetEl, edge: 'start', threshold: parseFloat(start) / 100 },
+          { target: targetEl, edge: 'end', threshold: parseFloat(end) / 100 }
+        ]
+      });
+    }
+
+  } else if (fallback === 'io') {
+    // Fallback using Intersection Observer
+    let animation: Animation | null = null;
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        entries.forEach(entry => {
+          const progress = Math.max(0, Math.min(1, entry.intersectionRatio));
+          
+          if (!animation) {
+            animation = targetEl.animate(keyframes, {
+              duration: 1000,
+              fill: 'both'
+            });
+            animation.pause();
+          }
+
+          // Update animation progress based on intersection
+          animation.currentTime = progress * 1000;
+        });
+      },
+      {
+        threshold: Array.from({ length: 101 }, (_, i) => i / 100) // 0 to 1 in 0.01 steps
+      }
+    );
+
+    observer.observe(targetEl);
+
+    // Store cleanup function
+    (targetEl as any)._scrollAnimateCleanup = () => {
+      observer.disconnect();
+      if (animation) {
+        animation.cancel();
+      }
+    };
+  }
+}
+
+/**
+ * Create a scroll-triggered animation that plays once when element enters viewport
+ */
+export function scrollTrigger(
+  target: Element | string,
+  keyframes: Keyframe[],
+  options: KeyframeAnimationOptions = {}
+): void {
+  const targetEl = typeof target === 'string' ? document.querySelector(target) : target;
+  if (!targetEl) {
+    throw new Error('Target element not found');
+  }
+
+  // Check for reduced motion preference
+  const prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+  if (prefersReducedMotion) {
+    // Apply end state immediately
+    const endKeyframe = keyframes[keyframes.length - 1];
+    Object.assign((targetEl as HTMLElement).style, endKeyframe);
+    return;
+  }
+
+  const observer = new IntersectionObserver(
+    (entries) => {
+      entries.forEach(entry => {
+        if (entry.isIntersecting) {
+          // Play animation
+          targetEl.animate(keyframes, {
+            duration: 600,
+            easing: 'ease-out',
+            fill: 'forwards',
+            ...options
+          });
+
+          // Disconnect observer after first trigger
+          observer.disconnect();
+        }
+      });
+    },
+    {
+      threshold: 0.1,
+      rootMargin: '0px 0px -10% 0px'
+    }
+  );
+
+  observer.observe(targetEl);
+}
+
+/**
+ * Parallax effect using scroll-driven animations
+ */
+export function parallax(
+  target: Element | string,
+  speed: number = 0.5
+): void {
+  const targetEl = typeof target === 'string' ? document.querySelector(target) : target;
+  if (!targetEl) {
+    throw new Error('Target element not found');
+  }
+
+  // Check for reduced motion preference
+  const prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+  if (prefersReducedMotion) return;
+
+  const keyframes = [
+    { transform: `translateY(${-100 * speed}px)` },
+    { transform: `translateY(${100 * speed}px)` }
+  ];
+
+  scrollAnimate(targetEl, {
+    keyframes,
+    range: ['0%', '100%'],
+    timeline: { axis: 'block' },
+    fallback: 'io'
+  });
+}
+
+/**
+ * Cleanup function to remove scroll animations
+ */
+export function cleanup(target: Element | string): void {
+  const targetEl = typeof target === 'string' ? document.querySelector(target) : target;
+  if (!targetEl) return;
+
+  // Call stored cleanup function if it exists
+  if ((targetEl as any)._scrollAnimateCleanup) {
+    (targetEl as any)._scrollAnimateCleanup();
+    delete (targetEl as any)._scrollAnimateCleanup;
+  }
+
+  // Remove animation classes
+  targetEl.classList.forEach(className => {
+    if (className.startsWith('scroll-animate-')) {
+      targetEl.classList.remove(className);
+    }
+  });
+
+  // Cancel any running animations
+  const animations = targetEl.getAnimations();
+  animations.forEach(animation => animation.cancel());
+}
+
+// Export default object for convenience
+export default {
+  scrollAnimate,
+  scrollTrigger,
+  parallax,
+  cleanup
+};

package/src/modules/transitions/index.ts

@@ -0,0 +1,145 @@
+/**
+ * @sc4rfurryx/proteusjs/transitions
+ * View Transitions API wrapper with safe fallbacks
+ * 
+ * @version 1.1.0
+ * @author sc4rfurry
+ * @license MIT
+ */
+
+export interface TransitionOptions {
+  name?: string;
+  duration?: number;
+  onBefore?: () => void;
+  onAfter?: () => void;
+  allowInterrupt?: boolean;
+}
+
+export interface NavigateOptions {
+  name?: string;
+  prerender?: boolean;
+}
+
+/**
+ * One API for animating DOM state changes and cross-document navigations 
+ * using the View Transitions API with safe fallbacks.
+ */
+export async function transition(
+  run: () => Promise<any> | any,
+  opts: TransitionOptions = {}
+): Promise<void> {
+  const {
+    name,
+    duration = 300,
+    onBefore,
+    onAfter,
+    allowInterrupt = true
+  } = opts;
+
+  // Check for View Transitions API support
+  const hasViewTransitions = 'startViewTransition' in document;
+
+  if (onBefore) {
+    onBefore();
+  }
+
+  if (!hasViewTransitions) {
+    // Fallback: run immediately without transitions
+    try {
+      await run();
+    } finally {
+      if (onAfter) {
+        onAfter();
+      }
+    }
+    return;
+  }
+
+  // Use native View Transitions API
+  try {
+    const viewTransition = (document as any).startViewTransition(async () => {
+      await run();
+    });
+
+    // Add CSS view-transition-name if name provided
+    if (name) {
+      const style = document.createElement('style');
+      style.textContent = `
+        ::view-transition-old(${name}),
+        ::view-transition-new(${name}) {
+          animation-duration: ${duration}ms;
+        }
+      `;
+      document.head.appendChild(style);
+      
+      // Clean up style after transition
+      viewTransition.finished.finally(() => {
+        style.remove();
+      });
+    }
+
+    await viewTransition.finished;
+  } catch (error) {
+    console.warn('View transition failed, falling back to immediate execution:', error);
+    await run();
+  } finally {
+    if (onAfter) {
+      onAfter();
+    }
+  }
+}
+
+/**
+ * MPA-friendly navigation with view transitions when supported
+ */
+export async function navigate(url: string, opts: NavigateOptions = {}): Promise<void> {
+  const { name, prerender = false } = opts;
+
+  // Optional prerender hint (basic implementation)
+  if (prerender && 'speculation' in HTMLScriptElement.prototype) {
+    const script = document.createElement('script');
+    script.type = 'speculationrules';
+    script.textContent = JSON.stringify({
+      prerender: [{ where: { href_matches: url } }]
+    });
+    document.head.appendChild(script);
+  }
+
+  // Check for View Transitions API support
+  const hasViewTransitions = 'startViewTransition' in document;
+
+  if (!hasViewTransitions) {
+    // Fallback: normal navigation
+    window.location.href = url;
+    return;
+  }
+
+  try {
+    // Use view transitions for navigation
+    const viewTransition = (document as any).startViewTransition(() => {
+      window.location.href = url;
+    });
+
+    if (name) {
+      const style = document.createElement('style');
+      style.textContent = `
+        ::view-transition-old(${name}),
+        ::view-transition-new(${name}) {
+          animation-duration: 300ms;
+        }
+      `;
+      document.head.appendChild(style);
+    }
+
+    await viewTransition.finished;
+  } catch (error) {
+    console.warn('View transition navigation failed, falling back to normal navigation:', error);
+    window.location.href = url;
+  }
+}
+
+// Export default object for convenience
+export default {
+  transition,
+  navigate
+};

package/src/modules/typography/index.ts

@@ -0,0 +1,239 @@
+/**
+ * @sc4rfurryx/proteusjs/typography
+ * Fluid typography with CSS-first approach
+ * 
+ * @version 1.1.0
+ * @author sc4rfurry
+ * @license MIT
+ */
+
+export interface FluidTypeOptions {
+  minViewportPx?: number;
+  maxViewportPx?: number;
+  lineHeight?: number;
+  containerUnits?: boolean;
+}
+
+export interface FluidTypeResult {
+  css: string;
+}
+
+/**
+ * Generate pure-CSS clamp() rules for fluid typography
+ */
+export function fluidType(
+  minRem: number,
+  maxRem: number,
+  options: FluidTypeOptions = {}
+): FluidTypeResult {
+  const {
+    minViewportPx = 320,
+    maxViewportPx = 1200,
+    lineHeight,
+    containerUnits = false
+  } = options;
+
+  // Convert rem to px for calculations (assuming 16px base)
+  const minPx = minRem * 16;
+  const maxPx = maxRem * 16;
+
+  // Calculate slope and y-intercept for linear interpolation
+  const slope = (maxPx - minPx) / (maxViewportPx - minViewportPx);
+  const yIntercept = minPx - slope * minViewportPx;
+
+  // Generate clamp() function
+  const viewportUnit = containerUnits ? 'cqw' : 'vw';
+  const clampValue = `clamp(${minRem}rem, ${yIntercept / 16}rem + ${slope * 100}${viewportUnit}, ${maxRem}rem)`;
+
+  let css = `font-size: ${clampValue};`;
+
+  // Add line-height if specified
+  if (lineHeight) {
+    css += `\nline-height: ${lineHeight};`;
+  }
+
+  return { css };
+}
+
+/**
+ * Apply fluid typography to elements
+ */
+export function applyFluidType(
+  selector: string,
+  minRem: number,
+  maxRem: number,
+  options: FluidTypeOptions = {}
+): void {
+  const { css } = fluidType(minRem, maxRem, options);
+  
+  const styleElement = document.createElement('style');
+  styleElement.textContent = `${selector} {\n  ${css.replace(/\n/g, '\n  ')}\n}`;
+  styleElement.setAttribute('data-proteus-typography', selector);
+  document.head.appendChild(styleElement);
+}
+
+/**
+ * Create a complete typographic scale
+ */
+export function createTypographicScale(
+  baseSize: number = 1,
+  ratio: number = 1.25,
+  steps: number = 6,
+  options: FluidTypeOptions = {}
+): Record<string, FluidTypeResult> {
+  const scale: Record<string, FluidTypeResult> = {};
+
+  for (let i = -2; i <= steps - 3; i++) {
+    const size = baseSize * Math.pow(ratio, i);
+    const minSize = size * 0.8; // 20% smaller at min viewport
+    const maxSize = size * 1.2; // 20% larger at max viewport
+    
+    const stepName = i <= 0 ? `small${Math.abs(i)}` : `large${i}`;
+    scale[stepName] = fluidType(minSize, maxSize, options);
+  }
+
+  return scale;
+}
+
+/**
+ * Generate CSS custom properties for a typographic scale
+ */
+export function generateScaleCSS(
+  scale: Record<string, FluidTypeResult>,
+  prefix: string = '--font-size'
+): string {
+  const cssVars = Object.entries(scale)
+    .map(([name, result]) => `  ${prefix}-${name}: ${result.css.replace('font-size: ', '').replace(';', '')};`)
+    .join('\n');
+
+  return `:root {\n${cssVars}\n}`;
+}
+
+/**
+ * Optimize line height for readability
+ */
+export function optimizeLineHeight(fontSize: number, measure: number = 65): number {
+  // Optimal line height based on font size and measure (characters per line)
+  // Smaller fonts need more line height, larger fonts need less
+  const baseLineHeight = 1.4;
+  const sizeAdjustment = Math.max(0.1, Math.min(0.3, (1 - fontSize) * 0.5));
+  const measureAdjustment = Math.max(-0.1, Math.min(0.1, (65 - measure) * 0.002));
+  
+  return baseLineHeight + sizeAdjustment + measureAdjustment;
+}
+
+/**
+ * Calculate optimal font size for container width
+ */
+export function calculateOptimalSize(
+  containerWidth: number,
+  targetCharacters: number = 65,
+  baseCharWidth: number = 0.5
+): number {
+  // Calculate font size to achieve target characters per line
+  const optimalFontSize = containerWidth / (targetCharacters * baseCharWidth);
+  
+  // Clamp to reasonable bounds (12px to 24px)
+  return Math.max(0.75, Math.min(1.5, optimalFontSize));
+}
+
+/**
+ * Apply responsive typography to an element
+ */
+export function makeResponsive(
+  target: Element | string,
+  options: {
+    minSize?: number;
+    maxSize?: number;
+    targetCharacters?: number;
+    autoLineHeight?: boolean;
+  } = {}
+): void {
+  const targetEl = typeof target === 'string' ? document.querySelector(target) : target;
+  if (!targetEl) {
+    throw new Error('Target element not found');
+  }
+
+  const {
+    minSize = 0.875,
+    maxSize = 1.25,
+    targetCharacters = 65,
+    autoLineHeight = true
+  } = options;
+
+  // Apply fluid typography
+  const { css } = fluidType(minSize, maxSize);
+  const element = targetEl as HTMLElement;
+  
+  // Parse and apply CSS
+  const styles = css.split(';').filter(Boolean);
+  styles.forEach(style => {
+    const [property, value] = style.split(':').map(s => s.trim());
+    if (property && value) {
+      element.style.setProperty(property, value);
+    }
+  });
+
+  // Auto line height if enabled
+  if (autoLineHeight) {
+    const updateLineHeight = () => {
+      const computedStyle = getComputedStyle(element);
+      const fontSize = parseFloat(computedStyle.fontSize);
+      const containerWidth = element.getBoundingClientRect().width;
+      const charactersPerLine = containerWidth / (fontSize * 0.5);
+      
+      const optimalLineHeight = optimizeLineHeight(fontSize / 16, charactersPerLine);
+      element.style.lineHeight = optimalLineHeight.toString();
+    };
+
+    updateLineHeight();
+
+    // Update on resize
+    if ('ResizeObserver' in window) {
+      const resizeObserver = new ResizeObserver(updateLineHeight);
+      resizeObserver.observe(element);
+      
+      // Store cleanup function
+      (element as any)._proteusTypographyCleanup = () => {
+        resizeObserver.disconnect();
+      };
+    }
+  }
+}
+
+/**
+ * Remove applied typography styles
+ */
+export function cleanup(target?: Element | string): void {
+  if (target) {
+    const targetEl = typeof target === 'string' ? document.querySelector(target) : target;
+    if (targetEl && (targetEl as any)._proteusTypographyCleanup) {
+      (targetEl as any)._proteusTypographyCleanup();
+      delete (targetEl as any)._proteusTypographyCleanup;
+    }
+  } else {
+    // Remove all typography style elements
+    const styleElements = document.querySelectorAll('style[data-proteus-typography]');
+    styleElements.forEach(element => element.remove());
+  }
+}
+
+/**
+ * Check if container query units are supported
+ */
+export function supportsContainerUnits(): boolean {
+  return CSS.supports('width', '1cqw');
+}
+
+// Export default object for convenience
+export default {
+  fluidType,
+  applyFluidType,
+  createTypographicScale,
+  generateScaleCSS,
+  optimizeLineHeight,
+  calculateOptimalSize,
+  makeResponsive,
+  cleanup,
+  supportsContainerUnits
+};

package/src/utils/version.ts

@@ -2,7 +2,7 @@
  * Version utilities for ProteusJS
  */
 
-export const version = '1.0.0';
+export const version = '1.1.0';
 
 export function getVersion(): string {
   return version;