@sc4rfurryx/proteusjs 1.0.0 → 1.1.1

package/src/adapters/vue.ts

@@ -0,0 +1,268 @@
+/**
+ * @sc4rfurryx/proteusjs/adapters/vue
+ * Vue composables and directives for ProteusJS
+ * 
+ * @version 1.1.0
+ * @author sc4rfurry
+ * @license MIT
+ */
+
+import { ref, onMounted, onUnmounted, Ref } from 'vue';
+import { transition, TransitionOptions } from '../modules/transitions';
+import { scrollAnimate, ScrollAnimateOptions } from '../modules/scroll';
+import { attach as attachPopover, PopoverOptions, PopoverController } from '../modules/popover';
+import { tether, TetherOptions, TetherController } from '../modules/anchor';
+import { defineContainer, ContainerOptions } from '../modules/container';
+
+/**
+ * Composable for view transitions
+ */
+export function useTransition() {
+  return {
+    transition: async (run: () => Promise<any> | any, opts?: TransitionOptions) => {
+      return transition(run, opts);
+    }
+  };
+}
+
+/**
+ * Composable for scroll animations
+ */
+export function useScrollAnimate(
+  elementRef: Ref<HTMLElement | undefined>,
+  opts: ScrollAnimateOptions
+) {
+  onMounted(() => {
+    if (elementRef.value) {
+      scrollAnimate(elementRef.value, opts);
+    }
+  });
+
+  return {
+    elementRef
+  };
+}
+
+/**
+ * Composable for popover functionality
+ */
+export function usePopover(
+  triggerRef: Ref<HTMLElement | undefined>,
+  panelRef: Ref<HTMLElement | undefined>,
+  opts?: PopoverOptions
+) {
+  const controller = ref<PopoverController | null>(null);
+  const isOpen = ref(false);
+
+  onMounted(() => {
+    if (triggerRef.value && panelRef.value) {
+      controller.value = attachPopover(triggerRef.value, panelRef.value, {
+        ...opts,
+        onOpen: () => {
+          isOpen.value = true;
+          opts?.onOpen?.();
+        },
+        onClose: () => {
+          isOpen.value = false;
+          opts?.onClose?.();
+        }
+      });
+    }
+  });
+
+  onUnmounted(() => {
+    if (controller.value) {
+      controller.value.destroy();
+    }
+  });
+
+  const open = () => controller.value?.open();
+  const close = () => controller.value?.close();
+  const toggle = () => controller.value?.toggle();
+
+  return {
+    isOpen,
+    open,
+    close,
+    toggle
+  };
+}
+
+/**
+ * Composable for anchor positioning
+ */
+export function useAnchor(
+  floatingRef: Ref<HTMLElement | undefined>,
+  anchorRef: Ref<HTMLElement | undefined>,
+  opts?: Omit<TetherOptions, 'anchor'>
+) {
+  const controller = ref<TetherController | null>(null);
+
+  onMounted(() => {
+    if (floatingRef.value && anchorRef.value) {
+      controller.value = tether(floatingRef.value, {
+        anchor: anchorRef.value,
+        ...opts
+      });
+    }
+  });
+
+  onUnmounted(() => {
+    if (controller.value) {
+      controller.value.destroy();
+    }
+  });
+
+  return {
+    controller
+  };
+}
+
+/**
+ * Composable for container queries
+ */
+export function useContainer(
+  elementRef: Ref<HTMLElement | undefined>,
+  name?: string,
+  opts?: ContainerOptions
+) {
+  onMounted(() => {
+    if (elementRef.value) {
+      defineContainer(elementRef.value, name, opts);
+    }
+  });
+
+  return {
+    elementRef
+  };
+}
+
+/**
+ * Vue directive for scroll animations
+ */
+export const vProteusScroll = {
+  mounted(el: HTMLElement, binding: { value: ScrollAnimateOptions }) {
+    scrollAnimate(el, binding.value);
+  }
+};
+
+/**
+ * Vue directive for container queries
+ */
+export const vProteusContainer = {
+  mounted(el: HTMLElement, binding: { value?: { name?: string; options?: ContainerOptions } }) {
+    const { name, options } = binding.value || {};
+    defineContainer(el, name, options);
+  }
+};
+
+/**
+ * Vue directive for performance optimizations
+ */
+export const vProteusPerf = {
+  mounted(el: HTMLElement) {
+    // Apply content visibility optimization
+    const observer = new IntersectionObserver(
+      (entries) => {
+        entries.forEach(entry => {
+          if (entry.isIntersecting) {
+            el.style.contentVisibility = 'visible';
+          } else {
+            el.style.contentVisibility = 'auto';
+          }
+        });
+      },
+      { rootMargin: '50px' }
+    );
+
+    observer.observe(el);
+
+    // Store cleanup function
+    (el as any)._proteusCleanup = () => {
+      observer.disconnect();
+    };
+  },
+  unmounted(el: HTMLElement) {
+    if ((el as any)._proteusCleanup) {
+      (el as any)._proteusCleanup();
+    }
+  }
+};
+
+/**
+ * Vue directive for accessibility enhancements
+ */
+export const vProteusA11y = {
+  mounted(el: HTMLElement, binding: { value?: { announceChanges?: boolean } }) {
+    const { announceChanges = false } = binding.value || {};
+
+    // Enhance focus indicators
+    const focusableElements = el.querySelectorAll(
+      'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+    );
+
+    focusableElements.forEach(element => {
+      const htmlEl = element as HTMLElement;
+      htmlEl.addEventListener('focus', () => {
+        htmlEl.style.outline = '2px solid #0066cc';
+        htmlEl.style.outlineOffset = '2px';
+      });
+      
+      htmlEl.addEventListener('blur', () => {
+        htmlEl.style.outline = 'none';
+      });
+    });
+
+    if (announceChanges) {
+      const observer = new MutationObserver(() => {
+        const announcement = document.createElement('div');
+        announcement.setAttribute('aria-live', 'polite');
+        announcement.style.position = 'absolute';
+        announcement.style.left = '-10000px';
+        announcement.textContent = 'Content updated';
+        document.body.appendChild(announcement);
+        
+        setTimeout(() => {
+          document.body.removeChild(announcement);
+        }, 1000);
+      });
+
+      observer.observe(el, { childList: true, subtree: true });
+      
+      (el as any)._proteusA11yCleanup = () => {
+        observer.disconnect();
+      };
+    }
+  },
+  unmounted(el: HTMLElement) {
+    if ((el as any)._proteusA11yCleanup) {
+      (el as any)._proteusA11yCleanup();
+    }
+  }
+};
+
+/**
+ * Plugin for Vue 3
+ */
+export const ProteusPlugin = {
+  install(app: any) {
+    app.directive('proteus-scroll', vProteusScroll);
+    app.directive('proteus-container', vProteusContainer);
+    app.directive('proteus-perf', vProteusPerf);
+    app.directive('proteus-a11y', vProteusA11y);
+  }
+};
+
+// Export all composables and directives
+export default {
+  useTransition,
+  useScrollAnimate,
+  usePopover,
+  useAnchor,
+  useContainer,
+  vProteusScroll,
+  vProteusContainer,
+  vProteusPerf,
+  vProteusA11y,
+  ProteusPlugin
+};

package/src/index.ts

@@ -1,16 +1,32 @@
 /**
- * ProteusJS - Dynamic Responsive Design Library
+ * ProteusJS - Native-first Web Development Primitives
  * Shape-shifting responsive design that adapts like the sea god himself
- * 
- * @version 1.0.0
- * @author ProteusJS Team
+ *
+ * @version 1.1.0
+ * @author sc4rfurry
  * @license MIT
  */
 
-// Core exports
+// Core exports (legacy compatibility)
 export { ProteusJS as default } from './core/ProteusJS';
 export { ProteusJS } from './core/ProteusJS';
 
+// New modular exports
+export * as transitions from './modules/transitions';
+export * as scroll from './modules/scroll';
+export * as anchor from './modules/anchor';
+export * as popover from './modules/popover';
+export * as container from './modules/container';
+export * as typography from './modules/typography';
+export * as a11yAudit from './modules/a11y-audit';
+export * as a11yPrimitives from './modules/a11y-primitives';
+export * as perf from './modules/perf';
+
+// Framework adapters are available as separate subpath exports:
+// import { ... } from '@sc4rfurryx/proteusjs/adapters/react'
+// import { ... } from '@sc4rfurryx/proteusjs/adapters/vue'
+// import { ... } from '@sc4rfurryx/proteusjs/adapters/svelte'
+
 // Type exports
 export type {
   ProteusConfig,
@@ -23,6 +39,17 @@ export type {
   PerformanceConfig
 } from './types';
 
+// Module-specific type exports
+export type { TransitionOptions, NavigateOptions } from './modules/transitions';
+export type { ScrollAnimateOptions } from './modules/scroll';
+export type { TetherOptions, TetherController } from './modules/anchor';
+export type { PopoverOptions, PopoverController } from './modules/popover';
+export type { ContainerOptions } from './modules/container';
+export type { FluidTypeOptions, FluidTypeResult } from './modules/typography';
+export type { AuditOptions, AuditReport, AuditViolation } from './modules/a11y-audit';
+export type { Controller, DialogOptions, TooltipOptions, FocusTrapController } from './modules/a11y-primitives';
+export type { SpeculationOptions, ContentVisibilityOptions } from './modules/perf';
+
 // Utility exports
 export { version } from './utils/version';
 export { isSupported } from './utils/support';
@@ -31,5 +58,5 @@ export { isSupported } from './utils/support';
 export type { ProteusPlugin } from './core/PluginSystem';
 
 // Constants
-export const VERSION = '1.0.0';
+export const VERSION = '1.1.0';
 export const LIBRARY_NAME = 'ProteusJS';

package/src/modules/a11y-audit/index.ts

@@ -0,0 +1,84 @@
+/**
+ * @sc4rfurryx/proteusjs/a11y-audit
+ * Lightweight accessibility audits for development
+ * 
+ * @version 1.1.0
+ * @author sc4rfurry
+ * @license MIT
+ */
+
+export interface AuditOptions {
+  rules?: string[];
+  format?: 'console' | 'json';
+}
+
+export interface AuditViolation {
+  id: string;
+  impact: 'minor' | 'moderate' | 'serious' | 'critical';
+  nodes: number;
+  help: string;
+}
+
+export interface AuditReport {
+  violations: AuditViolation[];
+  passes: number;
+  timestamp: number;
+  url: string;
+}
+
+export async function audit(
+  target: Document | Element = document,
+  options: AuditOptions = {}
+): Promise<AuditReport> {
+  if (typeof window === 'undefined' || process.env['NODE_ENV'] === 'production') {
+    return { violations: [], passes: 0, timestamp: Date.now(), url: '' };
+  }
+
+  const { rules = ['images', 'headings', 'forms'], format = 'console' } = options;
+  const violations: AuditViolation[] = [];
+  let passes = 0;
+
+  if (rules.includes('images')) {
+    const imgs = target.querySelectorAll('img:not([alt])');
+    if (imgs.length > 0) {
+      violations.push({
+        id: 'image-alt', impact: 'critical', nodes: imgs.length, help: 'Images need alt text'
+      });
+    }
+    passes += target.querySelectorAll('img[alt]').length;
+  }
+
+  if (rules.includes('headings')) {
+    const h1s = target.querySelectorAll('h1');
+    if (h1s.length !== 1) {
+      violations.push({
+        id: 'heading-structure', impact: 'moderate', nodes: h1s.length, help: 'Page should have exactly one h1'
+      });
+    } else passes++;
+  }
+
+  if (rules.includes('forms')) {
+    const unlabeled = target.querySelectorAll('input:not([aria-label]):not([aria-labelledby])');
+    if (unlabeled.length > 0) {
+      violations.push({
+        id: 'form-labels', impact: 'critical', nodes: unlabeled.length, help: 'Form inputs need labels'
+      });
+    }
+    passes += target.querySelectorAll('input[aria-label], input[aria-labelledby]').length;
+  }
+
+  const report: AuditReport = {
+    violations, passes, timestamp: Date.now(),
+    url: typeof window !== 'undefined' ? window.location.href : ''
+  };
+
+  if (format === 'console' && violations.length > 0) {
+    console.group('🔍 A11y Audit Results');
+    violations.forEach(v => console.warn(`${v.impact}: ${v.help}`));
+    console.groupEnd();
+  }
+
+  return report;
+}
+
+export default { audit };

package/src/modules/a11y-primitives/index.ts

@@ -0,0 +1,152 @@
+/**
+ * @sc4rfurryx/proteusjs/a11y-primitives
+ * Lightweight accessibility patterns
+ * 
+ * @version 1.1.0
+ * @author sc4rfurry
+ * @license MIT
+ */
+
+export interface Controller {
+  destroy(): void;
+}
+
+export interface DialogOptions {
+  modal?: boolean;
+  restoreFocus?: boolean;
+}
+
+export interface TooltipOptions {
+  delay?: number;
+  placement?: 'top' | 'bottom' | 'left' | 'right';
+}
+
+export interface FocusTrapController {
+  activate(): void;
+  deactivate(): void;
+}
+
+export function dialog(root: Element | string, opts: DialogOptions = {}): Controller {
+  const el = typeof root === 'string' ? document.querySelector(root) : root;
+  if (!el) throw new Error('Dialog element not found');
+
+  const { modal = true, restoreFocus = true } = opts;
+  let prevFocus: Element | null = null;
+
+  const open = () => {
+    if (restoreFocus) prevFocus = document.activeElement;
+    el.setAttribute('role', 'dialog');
+    if (modal) el.setAttribute('aria-modal', 'true');
+    (el as HTMLElement).focus();
+  };
+
+  const close = () => {
+    if (restoreFocus && prevFocus) (prevFocus as HTMLElement).focus();
+  };
+
+  return { destroy: () => close() };
+}
+
+export function tooltip(trigger: Element, content: Element, opts: TooltipOptions = {}): Controller {
+  const { delay = 300 } = opts;
+  let timeout: number;
+
+  const show = () => {
+    clearTimeout(timeout);
+    timeout = window.setTimeout(() => {
+      content.setAttribute('role', 'tooltip');
+      trigger.setAttribute('aria-describedby', content.id || 'tooltip');
+      content.style.display = 'block';
+    }, delay);
+  };
+
+  const hide = () => {
+    clearTimeout(timeout);
+    content.style.display = 'none';
+    trigger.removeAttribute('aria-describedby');
+  };
+
+  trigger.addEventListener('mouseenter', show);
+  trigger.addEventListener('mouseleave', hide);
+  trigger.addEventListener('focus', show);
+  trigger.addEventListener('blur', hide);
+
+  return {
+    destroy: () => {
+      clearTimeout(timeout);
+      trigger.removeEventListener('mouseenter', show);
+      trigger.removeEventListener('mouseleave', hide);
+      trigger.removeEventListener('focus', show);
+      trigger.removeEventListener('blur', hide);
+    }
+  };
+}
+
+export function focusTrap(container: Element): FocusTrapController {
+  const focusable = 'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])';
+  
+  const activate = () => {
+    const elements = container.querySelectorAll(focusable);
+    if (elements.length === 0) return;
+    
+    const first = elements[0] as HTMLElement;
+    const last = elements[elements.length - 1] as HTMLElement;
+    
+    const handleTab = (e: KeyboardEvent) => {
+      if (e.key !== 'Tab') return;
+      
+      if (e.shiftKey && document.activeElement === first) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && document.activeElement === last) {
+        e.preventDefault();
+        first.focus();
+      }
+    };
+    
+    container.addEventListener('keydown', handleTab);
+    first.focus();
+    
+    return () => container.removeEventListener('keydown', handleTab);
+  };
+
+  let deactivate = () => {};
+
+  return {
+    activate: () => { deactivate = activate() || (() => {}); },
+    deactivate: () => deactivate()
+  };
+}
+
+export function menu(container: Element): Controller {
+  const items = container.querySelectorAll('[role="menuitem"]');
+  let currentIndex = 0;
+
+  const navigate = (e: KeyboardEvent) => {
+    switch (e.key) {
+      case 'ArrowDown':
+        e.preventDefault();
+        currentIndex = (currentIndex + 1) % items.length;
+        (items[currentIndex] as HTMLElement).focus();
+        break;
+      case 'ArrowUp':
+        e.preventDefault();
+        currentIndex = currentIndex === 0 ? items.length - 1 : currentIndex - 1;
+        (items[currentIndex] as HTMLElement).focus();
+        break;
+      case 'Escape':
+        e.preventDefault();
+        container.dispatchEvent(new CustomEvent('menu:close'));
+        break;
+    }
+  };
+
+  container.setAttribute('role', 'menu');
+  container.addEventListener('keydown', navigate);
+
+  return {
+    destroy: () => container.removeEventListener('keydown', navigate)
+  };
+}
+
+export default { dialog, tooltip, focusTrap, menu };