@sc4rfurryx/proteusjs 1.0.0 → 1.1.0

package/src/modules/anchor/index.ts

@@ -0,0 +1,257 @@
+/**
+ * @sc4rfurryx/proteusjs/anchor
+ * CSS Anchor Positioning utilities with robust JS fallback
+ * 
+ * @version 1.1.0
+ * @author sc4rfurry
+ * @license MIT
+ */
+
+export interface TetherOptions {
+  anchor: Element | string;
+  placement?: 'top' | 'bottom' | 'left' | 'right' | 'auto';
+  align?: 'start' | 'center' | 'end';
+  offset?: number;
+  strategy?: 'absolute' | 'fixed';
+}
+
+export interface TetherController {
+  destroy(): void;
+}
+
+/**
+ * Declarative tethers (tooltips, callouts) via CSS Anchor Positioning when available;
+ * robust JS fallback with flip/collision detection
+ */
+export function tether(
+  floating: Element | string,
+  opts: TetherOptions
+): TetherController {
+  const floatingEl = typeof floating === 'string' ? document.querySelector(floating) : floating;
+  const anchorEl = typeof opts.anchor === 'string' ? document.querySelector(opts.anchor) : opts.anchor;
+
+  if (!floatingEl || !anchorEl) {
+    throw new Error('Both floating and anchor elements must exist');
+  }
+
+  const {
+    placement = 'bottom',
+    align = 'center',
+    offset = 8,
+    strategy = 'absolute'
+  } = opts;
+
+  // Check for CSS Anchor Positioning support
+  const hasAnchorPositioning = CSS.supports('anchor-name', 'test');
+
+  let isDestroyed = false;
+  let resizeObserver: ResizeObserver | null = null;
+
+  const setupCSSAnchorPositioning = () => {
+    if (!hasAnchorPositioning) return false;
+
+    // Generate unique anchor name
+    const anchorName = `anchor-${Math.random().toString(36).substring(2, 11)}`;
+    
+    // Set anchor name on anchor element
+    (anchorEl as HTMLElement).style.setProperty('anchor-name', anchorName);
+
+    // Position floating element using CSS anchor positioning
+    const floatingStyle = floatingEl as HTMLElement;
+    floatingStyle.style.position = strategy;
+    floatingStyle.style.setProperty('position-anchor', anchorName);
+
+    // Set position based on placement
+    switch (placement) {
+      case 'top':
+        floatingStyle.style.bottom = `anchor(bottom, ${offset}px)`;
+        break;
+      case 'bottom':
+        floatingStyle.style.top = `anchor(bottom, ${offset}px)`;
+        break;
+      case 'left':
+        floatingStyle.style.right = `anchor(left, ${offset}px)`;
+        break;
+      case 'right':
+        floatingStyle.style.left = `anchor(right, ${offset}px)`;
+        break;
+    }
+
+    // Set alignment
+    if (placement === 'top' || placement === 'bottom') {
+      switch (align) {
+        case 'start':
+          floatingStyle.style.left = 'anchor(left)';
+          break;
+        case 'center':
+          floatingStyle.style.left = 'anchor(center)';
+          floatingStyle.style.transform = 'translateX(-50%)';
+          break;
+        case 'end':
+          floatingStyle.style.right = 'anchor(right)';
+          break;
+      }
+    } else {
+      switch (align) {
+        case 'start':
+          floatingStyle.style.top = 'anchor(top)';
+          break;
+        case 'center':
+          floatingStyle.style.top = 'anchor(center)';
+          floatingStyle.style.transform = 'translateY(-50%)';
+          break;
+        case 'end':
+          floatingStyle.style.bottom = 'anchor(bottom)';
+          break;
+      }
+    }
+
+    return true;
+  };
+
+  const calculatePosition = () => {
+    const anchorRect = anchorEl.getBoundingClientRect();
+    const floatingRect = floatingEl.getBoundingClientRect();
+    const viewport = {
+      width: window.innerWidth,
+      height: window.innerHeight
+    };
+
+    let finalPlacement = placement;
+    let x = 0;
+    let y = 0;
+
+    // Calculate base position
+    switch (finalPlacement) {
+      case 'top':
+        x = anchorRect.left;
+        y = anchorRect.top - floatingRect.height - offset;
+        break;
+      case 'bottom':
+        x = anchorRect.left;
+        y = anchorRect.bottom + offset;
+        break;
+      case 'left':
+        x = anchorRect.left - floatingRect.width - offset;
+        y = anchorRect.top;
+        break;
+      case 'right':
+        x = anchorRect.right + offset;
+        y = anchorRect.top;
+        break;
+      case 'auto': {
+        // Choose best placement based on available space
+        const spaces = {
+          top: anchorRect.top,
+          bottom: viewport.height - anchorRect.bottom,
+          left: anchorRect.left,
+          right: viewport.width - anchorRect.right
+        };
+
+        const bestPlacement = Object.entries(spaces).reduce((a, b) =>
+          spaces[a[0] as keyof typeof spaces] > spaces[b[0] as keyof typeof spaces] ? a : b
+        )[0] as typeof finalPlacement;
+        
+        finalPlacement = bestPlacement;
+        return calculatePosition(); // Recursive call with determined placement
+      }
+    }
+
+    // Apply alignment
+    if (finalPlacement === 'top' || finalPlacement === 'bottom') {
+      switch (align) {
+        case 'start':
+          // x already set correctly
+          break;
+        case 'center':
+          x = anchorRect.left + (anchorRect.width - floatingRect.width) / 2;
+          break;
+        case 'end':
+          x = anchorRect.right - floatingRect.width;
+          break;
+      }
+    } else {
+      switch (align) {
+        case 'start':
+          // y already set correctly
+          break;
+        case 'center':
+          y = anchorRect.top + (anchorRect.height - floatingRect.height) / 2;
+          break;
+        case 'end':
+          y = anchorRect.bottom - floatingRect.height;
+          break;
+      }
+    }
+
+    // Collision detection and adjustment
+    if (x < 0) x = 8;
+    if (y < 0) y = 8;
+    if (x + floatingRect.width > viewport.width) {
+      x = viewport.width - floatingRect.width - 8;
+    }
+    if (y + floatingRect.height > viewport.height) {
+      y = viewport.height - floatingRect.height - 8;
+    }
+
+    return { x, y };
+  };
+
+  const updatePosition = () => {
+    if (isDestroyed) return;
+
+    if (!hasAnchorPositioning) {
+      const { x, y } = calculatePosition();
+      const floatingStyle = floatingEl as HTMLElement;
+      floatingStyle.style.position = strategy;
+      floatingStyle.style.left = `${x}px`;
+      floatingStyle.style.top = `${y}px`;
+    }
+  };
+
+  const setupJSFallback = () => {
+    updatePosition();
+
+    // Set up observers for position updates
+    resizeObserver = new ResizeObserver(updatePosition);
+    resizeObserver.observe(anchorEl);
+    resizeObserver.observe(floatingEl);
+
+    window.addEventListener('scroll', updatePosition, { passive: true });
+    window.addEventListener('resize', updatePosition, { passive: true });
+  };
+
+  const destroy = () => {
+    isDestroyed = true;
+
+    if (resizeObserver) {
+      resizeObserver.disconnect();
+      resizeObserver = null;
+    }
+
+    window.removeEventListener('scroll', updatePosition);
+    window.removeEventListener('resize', updatePosition);
+
+    // Clean up CSS anchor positioning
+    if (hasAnchorPositioning) {
+      (anchorEl as HTMLElement).style.removeProperty('anchor-name');
+      const floatingStyle = floatingEl as HTMLElement;
+      floatingStyle.style.removeProperty('position-anchor');
+      floatingStyle.style.position = '';
+    }
+  };
+
+  // Initialize
+  if (!setupCSSAnchorPositioning()) {
+    setupJSFallback();
+  }
+
+  return {
+    destroy
+  };
+}
+
+// Export default object for convenience
+export default {
+  tether
+};

package/src/modules/container/index.ts

@@ -0,0 +1,230 @@
+/**
+ * @sc4rfurryx/proteusjs/container
+ * Container/Style Query helpers with visualization devtools
+ * 
+ * @version 1.1.0
+ * @author sc4rfurry
+ * @license MIT
+ */
+
+export interface ContainerOptions {
+  type?: 'size' | 'style';
+  inlineSize?: boolean;
+}
+
+/**
+ * Sugar on native container queries with dev visualization
+ */
+export function defineContainer(
+  target: Element | string,
+  name?: string,
+  opts: ContainerOptions = {}
+): void {
+  const targetEl = typeof target === 'string' ? document.querySelector(target) : target;
+  if (!targetEl) {
+    throw new Error('Target element not found');
+  }
+
+  const {
+    type = 'size',
+    inlineSize: _inlineSize = true
+  } = opts;
+
+  const containerName = name || `container-${Math.random().toString(36).substring(2, 11)}`;
+
+  // Apply container properties
+  const element = targetEl as HTMLElement;
+  element.style.containerName = containerName;
+  element.style.containerType = type;
+
+  // Warn if containment settings are missing
+  const computedStyle = getComputedStyle(element);
+  if (!computedStyle.contain || computedStyle.contain === 'none') {
+    console.warn(`Container "${containerName}" may need explicit containment settings for optimal performance`);
+  }
+
+  // Dev overlay (only in development)
+  if (process.env['NODE_ENV'] === 'development' || (window as unknown as { __PROTEUS_DEV__?: boolean }).__PROTEUS_DEV__) {
+    createDevOverlay(element, containerName);
+  }
+}
+
+/**
+ * Create development overlay showing container bounds and breakpoints
+ */
+function createDevOverlay(element: HTMLElement, name: string): void {
+  const overlay = document.createElement('div');
+  overlay.className = 'proteus-container-overlay';
+  overlay.style.cssText = `
+    position: absolute;
+    top: 0;
+    left: 0;
+    right: 0;
+    bottom: 0;
+    pointer-events: none;
+    border: 2px dashed rgba(255, 0, 255, 0.5);
+    background: rgba(255, 0, 255, 0.05);
+    z-index: 9999;
+    font-family: monospace;
+    font-size: 12px;
+    color: #ff00ff;
+  `;
+
+  const label = document.createElement('div');
+  label.style.cssText = `
+    position: absolute;
+    top: -20px;
+    left: 0;
+    background: rgba(255, 0, 255, 0.9);
+    color: white;
+    padding: 2px 6px;
+    border-radius: 3px;
+    font-size: 10px;
+    white-space: nowrap;
+  `;
+  label.textContent = `Container: ${name}`;
+
+  const sizeInfo = document.createElement('div');
+  sizeInfo.style.cssText = `
+    position: absolute;
+    bottom: 2px;
+    right: 2px;
+    background: rgba(0, 0, 0, 0.7);
+    color: white;
+    padding: 2px 4px;
+    border-radius: 2px;
+    font-size: 10px;
+  `;
+
+  overlay.appendChild(label);
+  overlay.appendChild(sizeInfo);
+
+  // Position overlay relative to container
+  if (getComputedStyle(element).position === 'static') {
+    element.style.position = 'relative';
+  }
+  element.appendChild(overlay);
+
+  // Update size info
+  const updateSizeInfo = () => {
+    const rect = element.getBoundingClientRect();
+    sizeInfo.textContent = `${Math.round(rect.width)}×${Math.round(rect.height)}`;
+  };
+
+  updateSizeInfo();
+
+  // Update on resize
+  if ('ResizeObserver' in window) {
+    const resizeObserver = new ResizeObserver(updateSizeInfo);
+    resizeObserver.observe(element);
+  }
+
+  // Store cleanup function
+  (element as HTMLElement & { _proteusContainerCleanup?: () => void })._proteusContainerCleanup = () => {
+    overlay.remove();
+  };
+}
+
+/**
+ * Helper to create container query CSS rules
+ */
+export function createContainerQuery(
+  containerName: string,
+  condition: string,
+  styles: Record<string, string>
+): string {
+  const cssRules = Object.entries(styles)
+    .map(([property, value]) => `  ${property}: ${value};`)
+    .join('\n');
+
+  return `@container ${containerName} (${condition}) {\n${cssRules}\n}`;
+}
+
+/**
+ * Apply container query styles dynamically
+ */
+export function applyContainerQuery(
+  containerName: string,
+  condition: string,
+  styles: Record<string, string>
+): void {
+  const css = createContainerQuery(containerName, condition, styles);
+  
+  const styleElement = document.createElement('style');
+  styleElement.textContent = css;
+  styleElement.setAttribute('data-proteus-container', containerName);
+  document.head.appendChild(styleElement);
+}
+
+/**
+ * Remove container query styles
+ */
+export function removeContainerQuery(containerName: string): void {
+  const styleElements = document.querySelectorAll(`style[data-proteus-container="${containerName}"]`);
+  styleElements.forEach(element => element.remove());
+}
+
+/**
+ * Get container size information
+ */
+export function getContainerSize(target: Element | string): { width: number; height: number } {
+  const targetEl = typeof target === 'string' ? document.querySelector(target) : target;
+  if (!targetEl) {
+    throw new Error('Target element not found');
+  }
+
+  const rect = targetEl.getBoundingClientRect();
+  return {
+    width: rect.width,
+    height: rect.height
+  };
+}
+
+/**
+ * Check if container queries are supported
+ */
+export function isSupported(): boolean {
+  return CSS.supports('container-type', 'size');
+}
+
+/**
+ * Cleanup container overlays and observers
+ */
+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
+  const elementWithCleanup = targetEl as HTMLElement & { _proteusContainerCleanup?: () => void };
+  if (elementWithCleanup._proteusContainerCleanup) {
+    elementWithCleanup._proteusContainerCleanup();
+    delete elementWithCleanup._proteusContainerCleanup;
+  }
+}
+
+/**
+ * Toggle dev overlay visibility
+ */
+export function toggleDevOverlay(visible?: boolean): void {
+  const overlays = document.querySelectorAll('.proteus-container-overlay');
+  overlays.forEach(overlay => {
+    const element = overlay as HTMLElement;
+    if (visible !== undefined) {
+      element.style.display = visible ? 'block' : 'none';
+    } else {
+      element.style.display = element.style.display === 'none' ? 'block' : 'none';
+    }
+  });
+}
+
+// Export default object for convenience
+export default {
+  defineContainer,
+  createContainerQuery,
+  applyContainerQuery,
+  removeContainerQuery,
+  getContainerSize,
+  isSupported,
+  cleanup,
+  toggleDevOverlay
+};