@finggujadhav/js-helper 0.9.0

package/dist/index.d.mts

@@ -0,0 +1,51 @@
+/**
+ * Focus Trap Utility
+ * Ensures tab focus remains within a specific container.
+ */
+declare const focusTrap: (container: HTMLElement) => () => void;
+
+declare const lockScroll: () => void;
+declare const unlockScroll: () => void;
+
+/**
+ * ARIA Helper
+ * Managed attribute toggling for accessibility.
+ */
+declare const toggleAria: (element: HTMLElement, attribute: string, force?: boolean) => boolean;
+declare const setAriaHidden: (selector: string, isHidden: boolean) => void;
+
+declare const onToggle: (type: string, callback: (data: any) => void) => void;
+declare const initEvents: () => void;
+
+/**
+ * Tabs Helper
+ * Handles accessible keyboard navigation and state management for tabs.
+ */
+declare const initTabs: () => void;
+declare const activateTab: (tab: HTMLElement) => void;
+
+/**
+ * Dropdown Helper
+ * Handles accessible keyboard navigation, outside-click detection, and state management.
+ */
+declare const initDropdowns: () => void;
+
+/**
+ * FingguFlux Theme Helper
+ * Provides runtime logic for theme switching and system preference synchronization.
+ */
+type FingguTheme = 'light' | 'dark' | 'system';
+/**
+ * Apply a theme to the document or a specific element.
+ */
+declare function setTheme(theme: FingguTheme, target?: HTMLElement): void;
+/**
+ * Watch for system theme changes and sync (if in system mode).
+ */
+declare function watchSystemTheme(callback: (isDark: boolean) => void): () => void;
+/**
+ * Get the current effective theme.
+ */
+declare function getEffectiveTheme(target?: HTMLElement): 'light' | 'dark';
+
+export { type FingguTheme, activateTab, focusTrap, getEffectiveTheme, initDropdowns, initEvents, initTabs, lockScroll, onToggle, setAriaHidden, setTheme, toggleAria, unlockScroll, watchSystemTheme };

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Focus Trap Utility
+ * Ensures tab focus remains within a specific container.
+ */
+declare const focusTrap: (container: HTMLElement) => () => void;
+
+declare const lockScroll: () => void;
+declare const unlockScroll: () => void;
+
+/**
+ * ARIA Helper
+ * Managed attribute toggling for accessibility.
+ */
+declare const toggleAria: (element: HTMLElement, attribute: string, force?: boolean) => boolean;
+declare const setAriaHidden: (selector: string, isHidden: boolean) => void;
+
+declare const onToggle: (type: string, callback: (data: any) => void) => void;
+declare const initEvents: () => void;
+
+/**
+ * Tabs Helper
+ * Handles accessible keyboard navigation and state management for tabs.
+ */
+declare const initTabs: () => void;
+declare const activateTab: (tab: HTMLElement) => void;
+
+/**
+ * Dropdown Helper
+ * Handles accessible keyboard navigation, outside-click detection, and state management.
+ */
+declare const initDropdowns: () => void;
+
+/**
+ * FingguFlux Theme Helper
+ * Provides runtime logic for theme switching and system preference synchronization.
+ */
+type FingguTheme = 'light' | 'dark' | 'system';
+/**
+ * Apply a theme to the document or a specific element.
+ */
+declare function setTheme(theme: FingguTheme, target?: HTMLElement): void;
+/**
+ * Watch for system theme changes and sync (if in system mode).
+ */
+declare function watchSystemTheme(callback: (isDark: boolean) => void): () => void;
+/**
+ * Get the current effective theme.
+ */
+declare function getEffectiveTheme(target?: HTMLElement): 'light' | 'dark';
+
+export { type FingguTheme, activateTab, focusTrap, getEffectiveTheme, initDropdowns, initEvents, initTabs, lockScroll, onToggle, setAriaHidden, setTheme, toggleAria, unlockScroll, watchSystemTheme };

package/dist/index.js

@@ -0,0 +1,288 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  activateTab: () => activateTab,
+  focusTrap: () => focusTrap,
+  getEffectiveTheme: () => getEffectiveTheme,
+  initDropdowns: () => initDropdowns,
+  initEvents: () => initEvents,
+  initTabs: () => initTabs,
+  lockScroll: () => lockScroll,
+  onToggle: () => onToggle,
+  setAriaHidden: () => setAriaHidden,
+  setTheme: () => setTheme,
+  toggleAria: () => toggleAria,
+  unlockScroll: () => unlockScroll,
+  watchSystemTheme: () => watchSystemTheme
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/focus-trap.ts
+var focusTrap = (container) => {
+  const focusableSelectors = 'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])';
+  const focusableElements = container.querySelectorAll(focusableSelectors);
+  const firstFocusable = focusableElements[0];
+  const lastFocusable = focusableElements[focusableElements.length - 1];
+  const handleTrap = (e) => {
+    if (e.key !== "Tab") return;
+    if (e.shiftKey) {
+      if (document.activeElement === firstFocusable) {
+        lastFocusable.focus();
+        e.preventDefault();
+      }
+    } else {
+      if (document.activeElement === lastFocusable) {
+        firstFocusable.focus();
+        e.preventDefault();
+      }
+    }
+  };
+  container.addEventListener("keydown", handleTrap);
+  return () => container.removeEventListener("keydown", handleTrap);
+};
+
+// src/scroll-lock.ts
+var scrollPosition = 0;
+var lockScroll = () => {
+  scrollPosition = window.scrollY || window.pageYOffset;
+  const scrollbarWidth = window.innerWidth - document.documentElement.clientWidth;
+  document.body.setAttribute("data-ff-scroll-lock", "true");
+  document.documentElement.style.setProperty("--ff-scrollbar-width", `${scrollbarWidth}px`);
+};
+var unlockScroll = () => {
+  document.body.removeAttribute("data-ff-scroll-lock");
+  document.documentElement.style.removeProperty("--ff-scrollbar-width");
+  window.scrollTo(0, scrollPosition);
+};
+
+// src/aria.ts
+var toggleAria = (element, attribute, force) => {
+  const current = element.getAttribute(attribute);
+  const next = force !== void 0 ? force ? "true" : "false" : current === "true" ? "false" : "true";
+  element.setAttribute(attribute, next);
+  return next === "true";
+};
+var setAriaHidden = (selector, isHidden) => {
+  const elements = document.querySelectorAll(selector);
+  elements.forEach((el) => el.setAttribute("aria-hidden", isHidden.toString()));
+};
+
+// src/events.ts
+var registry = /* @__PURE__ */ new Map();
+var onToggle = (type, callback) => {
+  if (!registry.has(type)) registry.set(type, []);
+  registry.get(type).push(callback);
+};
+var initEvents = () => {
+  document.addEventListener("click", (e) => {
+    const trigger = e.target.closest("[data-ff-toggle]");
+    if (!trigger) return;
+    const type = trigger.getAttribute("data-ff-toggle") || "default";
+    const targetId = trigger.getAttribute("data-ff-target");
+    const target = targetId ? document.getElementById(targetId) : null;
+    if (target) {
+      const isExpanded = toggleAria(trigger, "aria-expanded");
+      target.setAttribute("data-ff-state", isExpanded ? "open" : "closed");
+      if (registry.has(type)) {
+        registry.get(type).forEach((cb) => cb({ trigger, target, isExpanded }));
+      }
+    }
+  });
+  document.addEventListener("keydown", (e) => {
+    if (e.key === "Escape") {
+      const openTargets = document.querySelectorAll('[data-ff-state="open"]');
+      openTargets.forEach((target) => {
+        target.setAttribute("data-ff-state", "closed");
+        const trigger = document.querySelector(`[data-ff-target="${target.id}"]`);
+        if (trigger) trigger.setAttribute("aria-expanded", "false");
+      });
+    }
+  });
+};
+
+// src/tabs.ts
+var initTabs = () => {
+  document.addEventListener("click", (e) => {
+    const tab = e.target.closest("[data-ff-tab]");
+    if (!tab) return;
+    activateTab(tab);
+  });
+  document.addEventListener("keydown", (e) => {
+    const tab = e.target.closest("[data-ff-tab]");
+    if (!tab) return;
+    const tablist = tab.closest('[role="tablist"]');
+    if (!tablist) return;
+    const tabs = Array.from(tablist.querySelectorAll("[data-ff-tab]"));
+    const index = tabs.indexOf(tab);
+    let nextTab;
+    switch (e.key) {
+      case "ArrowLeft":
+        nextTab = tabs[index - 1] || tabs[tabs.length - 1];
+        break;
+      case "ArrowRight":
+        nextTab = tabs[index + 1] || tabs[0];
+        break;
+      case "Home":
+        nextTab = tabs[0];
+        break;
+      case "End":
+        nextTab = tabs[tabs.length - 1];
+        break;
+      default:
+        return;
+    }
+    if (nextTab) {
+      nextTab.focus();
+      e.preventDefault();
+    }
+  });
+};
+var activateTab = (tab) => {
+  const tablist = tab.closest('[role="tablist"]');
+  if (!tablist) return;
+  const tabId = tab.getAttribute("data-ff-tab");
+  const allTabs = tablist.querySelectorAll("[data-ff-tab]");
+  allTabs.forEach((t) => {
+    const isActive = t === tab;
+    t.setAttribute("data-ff-state", isActive ? "active" : "inactive");
+    t.setAttribute("aria-selected", isActive ? "true" : "false");
+    t.setAttribute("tabindex", isActive ? "0" : "-1");
+  });
+  const allPanels = document.querySelectorAll("[data-ff-tab-panel]");
+  allPanels.forEach((panel) => {
+    const panelId = panel.getAttribute("data-ff-tab-panel");
+    const isTarget = panelId === tabId;
+    panel.setAttribute("data-ff-state", isTarget ? "active" : "inactive");
+  });
+};
+
+// src/dropdown.ts
+var initDropdowns = () => {
+  document.addEventListener("click", (e) => {
+    const trigger = e.target.closest(".ff-dropdown-trigger");
+    const dropdown = e.target.closest(".ff-dropdown");
+    if (trigger && dropdown) {
+      const currentState = dropdown.getAttribute("data-ff-state");
+      const newState = currentState === "open" ? "closed" : "open";
+      setDropdownState(dropdown, newState);
+      return;
+    }
+    if (!dropdown) {
+      closeAllDropdowns();
+    }
+  });
+  document.addEventListener("keydown", (e) => {
+    const activeElement = document.activeElement;
+    const dropdown = activeElement ? activeElement.closest(".ff-dropdown") : null;
+    if (!dropdown) {
+      if (e.key === "Escape") closeAllDropdowns();
+      return;
+    }
+    const state = dropdown.getAttribute("data-ff-state");
+    const trigger = dropdown.querySelector(".ff-dropdown-trigger");
+    const items = Array.from(dropdown.querySelectorAll(".ff-dropdown-item"));
+    const currentIndex = items.indexOf(activeElement);
+    if (e.key === "Escape") {
+      setDropdownState(dropdown, "closed");
+      if (trigger) trigger.focus();
+      e.preventDefault();
+      return;
+    }
+    if (state === "closed") {
+      if (e.key === "ArrowDown" || e.key === "Enter" || e.key === " ") {
+        setDropdownState(dropdown, "open");
+        if (items.length > 0) items[0].focus();
+        e.preventDefault();
+      }
+      return;
+    }
+    switch (e.key) {
+      case "ArrowDown":
+        const nextIndex = (currentIndex + 1) % items.length;
+        items[nextIndex].focus();
+        e.preventDefault();
+        break;
+      case "ArrowUp":
+        const prevIndex = (currentIndex - 1 + items.length) % items.length;
+        items[prevIndex].focus();
+        e.preventDefault();
+        break;
+      case "Tab":
+        setDropdownState(dropdown, "closed");
+        break;
+    }
+  });
+};
+var setDropdownState = (dropdown, state) => {
+  dropdown.setAttribute("data-ff-state", state);
+  const trigger = dropdown.querySelector(".ff-dropdown-trigger");
+  if (trigger) {
+    trigger.setAttribute("aria-expanded", state === "open" ? "true" : "false");
+  }
+};
+var closeAllDropdowns = () => {
+  const openDropdowns = document.querySelectorAll('.ff-dropdown[data-ff-state="open"]');
+  openDropdowns.forEach((dropdown) => setDropdownState(dropdown, "closed"));
+};
+
+// src/theme.ts
+function setTheme(theme, target = document.documentElement) {
+  if (theme === "system") {
+    target.removeAttribute("data-ff-theme");
+  } else {
+    target.setAttribute("data-ff-theme", theme);
+  }
+}
+function watchSystemTheme(callback) {
+  const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
+  const listener = (e) => callback(e.matches);
+  mediaQuery.addEventListener("change", listener);
+  return () => mediaQuery.removeEventListener("change", listener);
+}
+function getEffectiveTheme(target = document.documentElement) {
+  const manual = target.getAttribute("data-ff-theme");
+  if (manual) return manual;
+  return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+}
+
+// src/index.ts
+if (typeof document !== "undefined") {
+  initEvents();
+  initTabs();
+  initDropdowns();
+  console.log("FingguFlux JS Helpers initialized.");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  activateTab,
+  focusTrap,
+  getEffectiveTheme,
+  initDropdowns,
+  initEvents,
+  initTabs,
+  lockScroll,
+  onToggle,
+  setAriaHidden,
+  setTheme,
+  toggleAria,
+  unlockScroll,
+  watchSystemTheme
+});

package/dist/index.mjs

@@ -0,0 +1,250 @@
+// src/focus-trap.ts
+var focusTrap = (container) => {
+  const focusableSelectors = 'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])';
+  const focusableElements = container.querySelectorAll(focusableSelectors);
+  const firstFocusable = focusableElements[0];
+  const lastFocusable = focusableElements[focusableElements.length - 1];
+  const handleTrap = (e) => {
+    if (e.key !== "Tab") return;
+    if (e.shiftKey) {
+      if (document.activeElement === firstFocusable) {
+        lastFocusable.focus();
+        e.preventDefault();
+      }
+    } else {
+      if (document.activeElement === lastFocusable) {
+        firstFocusable.focus();
+        e.preventDefault();
+      }
+    }
+  };
+  container.addEventListener("keydown", handleTrap);
+  return () => container.removeEventListener("keydown", handleTrap);
+};
+
+// src/scroll-lock.ts
+var scrollPosition = 0;
+var lockScroll = () => {
+  scrollPosition = window.scrollY || window.pageYOffset;
+  const scrollbarWidth = window.innerWidth - document.documentElement.clientWidth;
+  document.body.setAttribute("data-ff-scroll-lock", "true");
+  document.documentElement.style.setProperty("--ff-scrollbar-width", `${scrollbarWidth}px`);
+};
+var unlockScroll = () => {
+  document.body.removeAttribute("data-ff-scroll-lock");
+  document.documentElement.style.removeProperty("--ff-scrollbar-width");
+  window.scrollTo(0, scrollPosition);
+};
+
+// src/aria.ts
+var toggleAria = (element, attribute, force) => {
+  const current = element.getAttribute(attribute);
+  const next = force !== void 0 ? force ? "true" : "false" : current === "true" ? "false" : "true";
+  element.setAttribute(attribute, next);
+  return next === "true";
+};
+var setAriaHidden = (selector, isHidden) => {
+  const elements = document.querySelectorAll(selector);
+  elements.forEach((el) => el.setAttribute("aria-hidden", isHidden.toString()));
+};
+
+// src/events.ts
+var registry = /* @__PURE__ */ new Map();
+var onToggle = (type, callback) => {
+  if (!registry.has(type)) registry.set(type, []);
+  registry.get(type).push(callback);
+};
+var initEvents = () => {
+  document.addEventListener("click", (e) => {
+    const trigger = e.target.closest("[data-ff-toggle]");
+    if (!trigger) return;
+    const type = trigger.getAttribute("data-ff-toggle") || "default";
+    const targetId = trigger.getAttribute("data-ff-target");
+    const target = targetId ? document.getElementById(targetId) : null;
+    if (target) {
+      const isExpanded = toggleAria(trigger, "aria-expanded");
+      target.setAttribute("data-ff-state", isExpanded ? "open" : "closed");
+      if (registry.has(type)) {
+        registry.get(type).forEach((cb) => cb({ trigger, target, isExpanded }));
+      }
+    }
+  });
+  document.addEventListener("keydown", (e) => {
+    if (e.key === "Escape") {
+      const openTargets = document.querySelectorAll('[data-ff-state="open"]');
+      openTargets.forEach((target) => {
+        target.setAttribute("data-ff-state", "closed");
+        const trigger = document.querySelector(`[data-ff-target="${target.id}"]`);
+        if (trigger) trigger.setAttribute("aria-expanded", "false");
+      });
+    }
+  });
+};
+
+// src/tabs.ts
+var initTabs = () => {
+  document.addEventListener("click", (e) => {
+    const tab = e.target.closest("[data-ff-tab]");
+    if (!tab) return;
+    activateTab(tab);
+  });
+  document.addEventListener("keydown", (e) => {
+    const tab = e.target.closest("[data-ff-tab]");
+    if (!tab) return;
+    const tablist = tab.closest('[role="tablist"]');
+    if (!tablist) return;
+    const tabs = Array.from(tablist.querySelectorAll("[data-ff-tab]"));
+    const index = tabs.indexOf(tab);
+    let nextTab;
+    switch (e.key) {
+      case "ArrowLeft":
+        nextTab = tabs[index - 1] || tabs[tabs.length - 1];
+        break;
+      case "ArrowRight":
+        nextTab = tabs[index + 1] || tabs[0];
+        break;
+      case "Home":
+        nextTab = tabs[0];
+        break;
+      case "End":
+        nextTab = tabs[tabs.length - 1];
+        break;
+      default:
+        return;
+    }
+    if (nextTab) {
+      nextTab.focus();
+      e.preventDefault();
+    }
+  });
+};
+var activateTab = (tab) => {
+  const tablist = tab.closest('[role="tablist"]');
+  if (!tablist) return;
+  const tabId = tab.getAttribute("data-ff-tab");
+  const allTabs = tablist.querySelectorAll("[data-ff-tab]");
+  allTabs.forEach((t) => {
+    const isActive = t === tab;
+    t.setAttribute("data-ff-state", isActive ? "active" : "inactive");
+    t.setAttribute("aria-selected", isActive ? "true" : "false");
+    t.setAttribute("tabindex", isActive ? "0" : "-1");
+  });
+  const allPanels = document.querySelectorAll("[data-ff-tab-panel]");
+  allPanels.forEach((panel) => {
+    const panelId = panel.getAttribute("data-ff-tab-panel");
+    const isTarget = panelId === tabId;
+    panel.setAttribute("data-ff-state", isTarget ? "active" : "inactive");
+  });
+};
+
+// src/dropdown.ts
+var initDropdowns = () => {
+  document.addEventListener("click", (e) => {
+    const trigger = e.target.closest(".ff-dropdown-trigger");
+    const dropdown = e.target.closest(".ff-dropdown");
+    if (trigger && dropdown) {
+      const currentState = dropdown.getAttribute("data-ff-state");
+      const newState = currentState === "open" ? "closed" : "open";
+      setDropdownState(dropdown, newState);
+      return;
+    }
+    if (!dropdown) {
+      closeAllDropdowns();
+    }
+  });
+  document.addEventListener("keydown", (e) => {
+    const activeElement = document.activeElement;
+    const dropdown = activeElement ? activeElement.closest(".ff-dropdown") : null;
+    if (!dropdown) {
+      if (e.key === "Escape") closeAllDropdowns();
+      return;
+    }
+    const state = dropdown.getAttribute("data-ff-state");
+    const trigger = dropdown.querySelector(".ff-dropdown-trigger");
+    const items = Array.from(dropdown.querySelectorAll(".ff-dropdown-item"));
+    const currentIndex = items.indexOf(activeElement);
+    if (e.key === "Escape") {
+      setDropdownState(dropdown, "closed");
+      if (trigger) trigger.focus();
+      e.preventDefault();
+      return;
+    }
+    if (state === "closed") {
+      if (e.key === "ArrowDown" || e.key === "Enter" || e.key === " ") {
+        setDropdownState(dropdown, "open");
+        if (items.length > 0) items[0].focus();
+        e.preventDefault();
+      }
+      return;
+    }
+    switch (e.key) {
+      case "ArrowDown":
+        const nextIndex = (currentIndex + 1) % items.length;
+        items[nextIndex].focus();
+        e.preventDefault();
+        break;
+      case "ArrowUp":
+        const prevIndex = (currentIndex - 1 + items.length) % items.length;
+        items[prevIndex].focus();
+        e.preventDefault();
+        break;
+      case "Tab":
+        setDropdownState(dropdown, "closed");
+        break;
+    }
+  });
+};
+var setDropdownState = (dropdown, state) => {
+  dropdown.setAttribute("data-ff-state", state);
+  const trigger = dropdown.querySelector(".ff-dropdown-trigger");
+  if (trigger) {
+    trigger.setAttribute("aria-expanded", state === "open" ? "true" : "false");
+  }
+};
+var closeAllDropdowns = () => {
+  const openDropdowns = document.querySelectorAll('.ff-dropdown[data-ff-state="open"]');
+  openDropdowns.forEach((dropdown) => setDropdownState(dropdown, "closed"));
+};
+
+// src/theme.ts
+function setTheme(theme, target = document.documentElement) {
+  if (theme === "system") {
+    target.removeAttribute("data-ff-theme");
+  } else {
+    target.setAttribute("data-ff-theme", theme);
+  }
+}
+function watchSystemTheme(callback) {
+  const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
+  const listener = (e) => callback(e.matches);
+  mediaQuery.addEventListener("change", listener);
+  return () => mediaQuery.removeEventListener("change", listener);
+}
+function getEffectiveTheme(target = document.documentElement) {
+  const manual = target.getAttribute("data-ff-theme");
+  if (manual) return manual;
+  return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+}
+
+// src/index.ts
+if (typeof document !== "undefined") {
+  initEvents();
+  initTabs();
+  initDropdowns();
+  console.log("FingguFlux JS Helpers initialized.");
+}
+export {
+  activateTab,
+  focusTrap,
+  getEffectiveTheme,
+  initDropdowns,
+  initEvents,
+  initTabs,
+  lockScroll,
+  onToggle,
+  setAriaHidden,
+  setTheme,
+  toggleAria,
+  unlockScroll,
+  watchSystemTheme
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+    "name": "@finggujadhav/js-helper",
+    "version": "0.9.0",
+    "description": "Shared runtime logic for FingguFlux themes and motion state management.",
+    "main": "dist/index.js",
+    "module": "dist/index.mjs",
+    "types": "dist/index.d.ts",
+    "files": [
+        "dist",
+        "src"
+    ],
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.mjs"
+        }
+    },
+    "scripts": {
+        "build": "tsup src/index.ts --format cjs,esm --dts"
+    },
+    "devDependencies": {
+        "tsup": "^8.0.0",
+        "typescript": "^5.0.0"
+    },
+    "keywords": [
+        "runtime",
+        "theme-switching",
+        "motion-logic"
+    ],
+    "author": "Finggu Architecture Team",
+    "license": "MIT"
+}

package/src/aria.ts

@@ -0,0 +1,15 @@
+/**
+ * ARIA Helper
+ * Managed attribute toggling for accessibility.
+ */
+export const toggleAria = (element: HTMLElement, attribute: string, force?: boolean): boolean => {
+    const current = element.getAttribute(attribute);
+    const next = force !== undefined ? (force ? 'true' : 'false') : (current === 'true' ? 'false' : 'true');
+    element.setAttribute(attribute, next);
+    return next === 'true';
+};
+
+export const setAriaHidden = (selector: string, isHidden: boolean) => {
+    const elements = document.querySelectorAll(selector);
+    elements.forEach(el => el.setAttribute('aria-hidden', isHidden.toString()));
+};

package/src/dropdown.ts

@@ -0,0 +1,87 @@
+/**
+ * Dropdown Helper
+ * Handles accessible keyboard navigation, outside-click detection, and state management.
+ */
+
+export const initDropdowns = () => {
+    // Global Click Listener for Event Delegation
+    document.addEventListener('click', (e: MouseEvent) => {
+        const trigger = (e.target as HTMLElement).closest('.ff-dropdown-trigger') as HTMLElement;
+        const dropdown = (e.target as HTMLElement).closest('.ff-dropdown') as HTMLElement;
+
+        // Handle clicks on triggers
+        if (trigger && dropdown) {
+            const currentState = dropdown.getAttribute('data-ff-state');
+            const newState = currentState === 'open' ? 'closed' : 'open';
+            setDropdownState(dropdown, newState);
+            return;
+        }
+
+        // Outside Click Detection
+        if (!dropdown) {
+            closeAllDropdowns();
+        }
+    });
+
+    // Global Keydown Listener
+    document.addEventListener('keydown', (e: KeyboardEvent) => {
+        const activeElement = document.activeElement as HTMLElement;
+        const dropdown = activeElement ? activeElement.closest('.ff-dropdown') as HTMLElement : null;
+
+        if (!dropdown) {
+            if (e.key === 'Escape') closeAllDropdowns();
+            return;
+        }
+
+        const state = dropdown.getAttribute('data-ff-state');
+        const trigger = dropdown.querySelector('.ff-dropdown-trigger') as HTMLElement;
+        const items = Array.from(dropdown.querySelectorAll('.ff-dropdown-item')) as HTMLElement[];
+        const currentIndex = items.indexOf(activeElement);
+
+        if (e.key === 'Escape') {
+            setDropdownState(dropdown, 'closed');
+            if (trigger) trigger.focus(); // Return focus to trigger
+            e.preventDefault();
+            return;
+        }
+
+        if (state === 'closed') {
+            if (e.key === 'ArrowDown' || e.key === 'Enter' || e.key === ' ') {
+                setDropdownState(dropdown, 'open');
+                if (items.length > 0) items[0].focus();
+                e.preventDefault();
+            }
+            return;
+        }
+
+        // Navigation within open menu
+        switch (e.key) {
+            case 'ArrowDown':
+                const nextIndex = (currentIndex + 1) % items.length;
+                items[nextIndex].focus();
+                e.preventDefault();
+                break;
+            case 'ArrowUp':
+                const prevIndex = (currentIndex - 1 + items.length) % items.length;
+                items[prevIndex].focus();
+                e.preventDefault();
+                break;
+            case 'Tab':
+                setDropdownState(dropdown, 'closed');
+                break;
+        }
+    });
+};
+
+const setDropdownState = (dropdown: HTMLElement, state: string) => {
+    dropdown.setAttribute('data-ff-state', state);
+    const trigger = dropdown.querySelector('.ff-dropdown-trigger');
+    if (trigger) {
+        trigger.setAttribute('aria-expanded', state === 'open' ? 'true' : 'false');
+    }
+};
+
+const closeAllDropdowns = () => {
+    const openDropdowns = document.querySelectorAll('.ff-dropdown[data-ff-state="open"]');
+    openDropdowns.forEach(dropdown => setDropdownState(dropdown as HTMLElement, 'closed'));
+};

package/src/events.ts

@@ -0,0 +1,48 @@
+/**
+ * Event Delegation System
+ * Handles global listeners for better performance and dynamic elements.
+ */
+import { toggleAria } from './aria';
+
+const registry = new Map<string, any[]>();
+
+export const onToggle = (type: string, callback: (data: any) => void) => {
+    if (!registry.has(type)) registry.set(type, []);
+    registry.get(type)!.push(callback);
+};
+
+export const initEvents = () => {
+    // Global Click Listener
+    document.addEventListener('click', (e: MouseEvent) => {
+        const trigger = (e.target as HTMLElement).closest('[data-ff-toggle]') as HTMLElement;
+        if (!trigger) return;
+
+        const type = trigger.getAttribute('data-ff-toggle') || 'default';
+        const targetId = trigger.getAttribute('data-ff-target');
+        const target = targetId ? document.getElementById(targetId) : null;
+
+        // Default state toggle
+        if (target) {
+            const isExpanded = toggleAria(trigger, 'aria-expanded');
+            target.setAttribute('data-ff-state', isExpanded ? 'open' : 'closed');
+
+            // Notify custom listeners
+            if (registry.has(type)) {
+                registry.get(type)!.forEach(cb => cb({ trigger, target, isExpanded }));
+            }
+        }
+    });
+
+    // Global Keydown Listener
+    document.addEventListener('keydown', (e) => {
+        if (e.key === 'Escape') {
+            // Find all open toggles and close them
+            const openTargets = document.querySelectorAll('[data-ff-state="open"]');
+            openTargets.forEach(target => {
+                target.setAttribute('data-ff-state', 'closed');
+                const trigger = document.querySelector(`[data-ff-target="${target.id}"]`);
+                if (trigger) trigger.setAttribute('aria-expanded', 'false');
+            });
+        }
+    });
+};

package/src/focus-trap.ts

@@ -0,0 +1,31 @@
+/**
+ * Focus Trap Utility
+ * Ensures tab focus remains within a specific container.
+ */
+export const focusTrap = (container: HTMLElement) => {
+  const focusableSelectors = 'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])';
+  const focusableElements = container.querySelectorAll(focusableSelectors) as NodeListOf<HTMLElement>;
+  const firstFocusable = focusableElements[0];
+  const lastFocusable = focusableElements[focusableElements.length - 1];
+
+  const handleTrap = (e: KeyboardEvent) => {
+    if (e.key !== 'Tab') return;
+
+    if (e.shiftKey) { // Back tab
+      if (document.activeElement === firstFocusable) {
+        lastFocusable.focus();
+        e.preventDefault();
+      }
+    } else { // Forward tab
+      if (document.activeElement === lastFocusable) {
+        firstFocusable.focus();
+        e.preventDefault();
+      }
+    }
+  };
+
+  container.addEventListener('keydown', handleTrap);
+
+  // Return cleanup function
+  return () => container.removeEventListener('keydown', handleTrap);
+};

package/src/index.ts

@@ -0,0 +1,22 @@
+/**
+ * FingguFlux JS Helper - Entry Point
+ */
+export * from './focus-trap';
+export * from './scroll-lock';
+export * from './aria';
+export * from './events';
+export * from './tabs';
+export * from './dropdown';
+export * from './theme';
+
+import { initEvents } from './events';
+import { initTabs } from './tabs';
+import { initDropdowns } from './dropdown';
+
+// Auto-initialize if running in a standard environment
+if (typeof document !== 'undefined') {
+    initEvents();
+    initTabs();
+    initDropdowns();
+    console.log('FingguFlux JS Helpers initialized.');
+}

package/src/scroll-lock.ts

@@ -0,0 +1,20 @@
+/**
+ * Scroll Lock Utility
+ * Prevents body scrolling without layout shift.
+ */
+let scrollPosition = 0;
+
+export const lockScroll = () => {
+    scrollPosition = window.scrollY || window.pageYOffset;
+    const scrollbarWidth = window.innerWidth - document.documentElement.clientWidth;
+
+    // Use a data attribute for styling instead of inline styles
+    document.body.setAttribute('data-ff-scroll-lock', 'true');
+    document.documentElement.style.setProperty('--ff-scrollbar-width', `${scrollbarWidth}px`);
+};
+
+export const unlockScroll = () => {
+    document.body.removeAttribute('data-ff-scroll-lock');
+    document.documentElement.style.removeProperty('--ff-scrollbar-width');
+    window.scrollTo(0, scrollPosition);
+};

package/src/tabs.ts

@@ -0,0 +1,71 @@
+/**
+ * Tabs Helper
+ * Handles accessible keyboard navigation and state management for tabs.
+ */
+
+export const initTabs = () => {
+    document.addEventListener('click', (e: MouseEvent) => {
+        const tab = (e.target as HTMLElement).closest('[data-ff-tab]') as HTMLElement;
+        if (!tab) return;
+        activateTab(tab);
+    });
+
+    document.addEventListener('keydown', (e: KeyboardEvent) => {
+        const tab = (e.target as HTMLElement).closest('[data-ff-tab]') as HTMLElement;
+        if (!tab) return;
+
+        const tablist = tab.closest('[role="tablist"]');
+        if (!tablist) return;
+
+        const tabs = Array.from(tablist.querySelectorAll('[data-ff-tab]')) as HTMLElement[];
+        const index = tabs.indexOf(tab);
+
+        let nextTab: HTMLElement | undefined;
+
+        switch (e.key) {
+            case 'ArrowLeft':
+                nextTab = tabs[index - 1] || tabs[tabs.length - 1];
+                break;
+            case 'ArrowRight':
+                nextTab = tabs[index + 1] || tabs[0];
+                break;
+            case 'Home':
+                nextTab = tabs[0];
+                break;
+            case 'End':
+                nextTab = tabs[tabs.length - 1];
+                break;
+            default:
+                return;
+        }
+
+        if (nextTab) {
+            nextTab.focus();
+            e.preventDefault();
+        }
+    });
+};
+
+export const activateTab = (tab: HTMLElement) => {
+    const tablist = tab.closest('[role="tablist"]');
+    if (!tablist) return;
+
+    const tabId = tab.getAttribute('data-ff-tab');
+    const allTabs = tablist.querySelectorAll('[data-ff-tab]');
+
+    // Update Tabs
+    allTabs.forEach(t => {
+        const isActive = t === tab;
+        t.setAttribute('data-ff-state', isActive ? 'active' : 'inactive');
+        t.setAttribute('aria-selected', isActive ? 'true' : 'false');
+        t.setAttribute('tabindex', isActive ? '0' : '-1');
+    });
+
+    // Update Panels
+    const allPanels = document.querySelectorAll('[data-ff-tab-panel]');
+    allPanels.forEach(panel => {
+        const panelId = panel.getAttribute('data-ff-tab-panel');
+        const isTarget = panelId === tabId;
+        panel.setAttribute('data-ff-state', isTarget ? 'active' : 'inactive');
+    });
+};

package/src/theme.ts

@@ -0,0 +1,38 @@
+/**
+ * FingguFlux Theme Helper
+ * Provides runtime logic for theme switching and system preference synchronization.
+ */
+
+export type FingguTheme = 'light' | 'dark' | 'system';
+
+/**
+ * Apply a theme to the document or a specific element.
+ */
+export function setTheme(theme: FingguTheme, target: HTMLElement = document.documentElement) {
+    if (theme === 'system') {
+        target.removeAttribute('data-ff-theme');
+    } else {
+        target.setAttribute('data-ff-theme', theme);
+    }
+}
+
+/**
+ * Watch for system theme changes and sync (if in system mode).
+ */
+export function watchSystemTheme(callback: (isDark: boolean) => void) {
+    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
+    const listener = (e: MediaQueryListEvent) => callback(e.matches);
+
+    mediaQuery.addEventListener('change', listener);
+    return () => mediaQuery.removeEventListener('change', listener);
+}
+
+/**
+ * Get the current effective theme.
+ */
+export function getEffectiveTheme(target: HTMLElement = document.documentElement): 'light' | 'dark' {
+    const manual = target.getAttribute('data-ff-theme') as 'light' | 'dark' | null;
+    if (manual) return manual;
+
+    return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+}