v1.1.4 - Targeting Fix

🐛 Bug Fix

Fixed Dataset Check in Per-Element Debounce

Issue: Console error when event target doesn't have a dataset property (e.g., window, document, or certain SVG elements).

Fix: Added safety check before accessing :

// Check if target is a DOM element with dataset property
if (target && target.dataset) {
    elementId = target.dataset.yehDid || target.id || target.getAttribute('name');
}

This is a patch release that fixes a regression introduced in v1.1.3. All v1.1.3 features remain unchanged.

Full v1.1.3 Release Notes: See DEV.NEXT.RELEASE_NOTES.md

v1.1.3 Release Notes and npm

YaiJS v1.1.3 Release Notes

🎉 Major Features

🔧 Per-Element Debounce/Throttle (Fixes Input Counter Bug)

Problem Solved: Previously, all debounced inputs in the same container shared a single timer. Typing in one input, then quickly switching to another would cancel the first input's debounce timer, preventing counter updates and validation.

Solution: YEH now implements per-element debounce by default, isolating timers per input element:

// Each input gets its own isolated timer
{ type: 'input', debounce: 750 }
// Username timer: #app-input-username-debounce
// Password timer: #app-input-password-debounce

Element ID Priority System:

1. data-yeh-did - Custom YEH debounce ID (highest priority)
2. id - Standard element ID
3. name - Form element name attribute
4. Fallback - Container-level key (legacy behavior)

Backward Compatibility: 100% backward compatible. Opt-in legacy mode available:

{ type: 'input', debounce: 750, perElement: false } // Legacy behavior

🎯 Leading/Trailing Edge Support

Added granular control over when debounced/throttled functions execute:

Debounce Defaults:

• leading: false - Don't execute on first event
• trailing: true - Execute after quiet period
• perElement: true - Isolate timers per element

Throttle Defaults:

• leading: true - Execute immediately on first event
• trailing: true - Execute with latest args after cooldown

Configuration Examples:

// Immediate feedback + final update
{ type: 'input', debounce: 750, leading: true }

// Leading-only (no trailing update)
{ type: 'input', debounce: 750, leading: true, trailing: false }

// Throttle: Leading-only (rate limit)
{ type: 'scroll', throttle: 100, leading: true, trailing: false }

🌍 Global Event Hook Support

New Feature: Events on window, document, body, and documentElement now fire hooks without requiring data-* attributes on target elements.

Use Cases:

• Global keyboard shortcuts (without interfering with form inputs)
• Scroll/resize handling
• Document load events
• Window-level interactions

Example:

const inputUtils = new YaiInputUtils({
  appConfig: {
    eventHandler: {
      selector: {
        window: [
          'keydown',
          { type: 'scroll', throttle: 240 },
          { type: 'resize', throttle: 700 },
          { type: 'load', options: { once: true } }
        ]
      }
    }
  }
});

// Global keyboard shortcuts
inputUtils.hook('eventkeydown', (target, event) => {
  if (YaiInputUtils.hasActiveInput()) return; // Skip if typing in form
  // Handle global shortcuts
});

// Scroll handling
inputUtils.hook('eventscroll', (target, event) => {
  console.log('Scrolled to:', window.scrollY);
});

Element-specific events still require data-* attributes:

// #app events require data-click="action" on elements
{ '#app': ['click'] }

🛠️ YaiInputUtils Enhancements

Textarea & Select Support

// Now works with all form elements
preValidation(input: HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement)
inputCounter(input: HTMLInputElement | HTMLTextAreaElement)
autoEnhance(input: HTMLInputElement | HTMLTextAreaElement)

Custom Error Messages

<!-- Display custom validation errors -->
<input type="text"
       minlength="3"
       data-error-message="Username must be at least 3 characters"
       required>

Static Helper: hasActiveInput()

Prevent keyboard shortcuts while user is typing in forms or contenteditable elements:

handleKeydown(event, target) {
  // Don't trigger shortcuts while user is editing
  if (YaiInputUtils.hasActiveInput()) return;

  if (event.key === 's' && event.ctrlKey) {
    event.preventDefault();
    this.save();
  }
}

Checks for:

• INPUT, TEXTAREA, SELECT elements
• contenteditable elements

🐛 Bug Fixes

Fixed Document/Window Container Handling

Issue: Events on document and window had container = null.

Fix: Modified findClosest() in YEH to return proper global objects:

findClosest(element, selector) {
  if (selector === 'document') return document;
  if (selector === 'window') return window;
  // ... rest of implementation
}

Fixed handleWiredEvents Signature

Issue: Method only received target parameter instead of full event context.

Fix: Updated signature to include all parameters:

handleWiredEvents(eventName, target, event, container) {
  // Hooks now receive complete event information
  this._executeHook(`${emitPrefix}${eventName}`, { target, event, container }, this);
}

📁 File Organization

Moved YaiInputUtils to Utils Directory

/utils/yai-input-utils.js      // Main utility
/utils/yai-input-utils.d.ts    // TypeScript definitions

Relocated Demo Page

/docs/utilities/yai-input-utils.html  // Interactive demo

📚 Documentation Updates

YEH Documentation Cleanup

• Removed performance hype claims (O(1), 46x efficiency)
• Removed AI author credits and comparison tables
• Added personal author story about discovering handleEvent
• Added "Documentation Status: Early release - actively being refined"

Enhanced TypeScript Definitions

• Documented global event support with examples
• Added comprehensive hasActiveInput() documentation (3 practical examples)
• Updated all signatures to match implementation

🧪 Test Coverage

All tests passing: 80 passed, 5 skipped

Key test areas:

• Per-element debounce isolation
• Leading/trailing edge execution
• Global event hook firing
• Closure support for on() method
• Hook system lifecycle

🔧 Implementation Details

YEH Core Changes (yeh.js)

Lines 477-497 - Per-element debounce:

if (options.perElement) {  // Default: true
  handler = {
    handleEvent: (event) => {
      const elementId = event.target.dataset.yehDid ||
                        event.target.id ||
                        event.target.getAttribute('name');

      const debounceKey = elementId
        ? `${key}-${eventType}-${elementId}-debounce`
        : `${key}-${eventType}-debounce`;

      this.debounce(() => this.handleEvent(event), eventConfig.debounce, debounceKey, options).call(this);
    }
  };
}

Lines 1075-1103 - Leading/trailing edge debounce
Lines 1111-1145 - Leading/trailing edge throttle

Lines 579-582 - Global selector handling in findClosest()

YaiInputUtils Changes (utils/yai-input-utils.js)

Lines 126-143 - Global event support in handleEventProxy:

const isGlobalEvent = container === document.body ||
                     container === document.documentElement ||
                     container === document ||
                     container === window;

if (!isGlobalEvent && !target.dataset) return;

Lines 377-385 - hasActiveInput() static method:

static hasActiveInput() {
  const activeElement = document.activeElement;
  const formInputs = ['INPUT', 'TEXTAREA', 'SELECT'];

  return activeElement && (
    formInputs.includes(activeElement.tagName) ||
    activeElement.isContentEditable
  );
}

📦 Package Info

• Version: 1.1.3
• Previous Version: 1.1.2
• NPM Package: @yaijs/core
• CDN: https://cdn.jsdelivr.net/npm/@yaijs/core@1.1.3/yeh/yeh.min.js

🚀 Upgrade Instructions

No breaking changes - simply update your package:

npm install @yaijs/core@1.1.3

Or via CDN:

import { YEH } from 'https://cdn.jsdelivr.net/npm/@yaijs/core@1.1.3/yeh/yeh.min.js';

📝 Migration Guide

This release is 100% backward compatible. No changes needed to existing code.

Optional Enhancements

Use per-element debounce explicitly:

// Default behavior (recommended)
{ type: 'input', debounce: 750 }

// Add leading edge for immediate feedback
{ type: 'input', debounce: 750, leading: true }

// Legacy container-level (not recommended)
{ type: 'input', debounce: 750, perElement: false }

Add global event hooks:

const inputUtils = new YaiInputUtils({
  appConfig: {
    eventHandler: {
      selector: {
        window: ['keydown', 'scroll', 'resize'],
        '#app': ['click', 'input']
      }
    }
  }
});

inputUtils.hook('eventkeydown', (target, event) => {
  if (YaiInputUtils.hasActiveInput()) return;
  // Handle shortcuts
});

🎯 Real-World Impact

Before: Typing in username, switching to password = username counter never updates
After: Each input has isolated timer, everything updates correctly

Before: Keydown on window requires data-keydown on every element
After: Global events fire hooks automatically, element-specific events still require data attributes

Before: Manual checks for focused inputs across codebase
After: YaiInputUtils.hasActiveInput() provides consistent utility

v1.1.1 New Features

YaiJS v1.1.1 Release Notes

🎉 New Features

✨ Closure Support for on() Method

The on() and subscribe() methods now accept function closures in addition to string handler names, providing a more flexible and modern API:

const yeh = new YEH();

// NEW: Direct function closures
yeh.on('custom-event', (event) => {
  console.log('Event fired!', event.detail);
});

// Still supported: String handler names
yeh.on('click', 'handleClick');

Benefits:

• ✅ Modern JavaScript patterns with arrow functions
• ✅ Access to outer scope variables naturally
• ✅ No need to define methods in the class or methods object
• ✅ Fully backward compatible - all existing code works unchanged

🧪 Test Coverage

Comprehensive Hook System Tests

Added 7 new tests for the hook system that was previously untested:

• Hook registration and execution with closures
• Multiple hooks for the same event
• unhook() to remove specific callbacks
• clearHooks() to clear all hooks
• Instance chaining support
• beforeHandleEvent and afterHandleEvent lifecycle hooks

Closure Support Tests

Added 3 new tests for the enhanced on() API:

• String handler name support (existing functionality)
• Function closure support (new feature)
• subscribe() alias verification

Test Results: 79/79 tests passing ✅

🔧 Implementation Details

Updated Methods

• resolveHandler(): Now checks if handler is a function and returns it directly
• validateResolvedHandler(): Skips validation for function closures
• on(): Enhanced JSDoc to document closure support

Code Quality

• Fully backward compatible - no breaking changes
• All existing tests continue to pass
• TypeScript-ready with updated JSDoc annotations

🌟 Real-World Usage

YEH is powering production applications, including our newest library:

• PHP-Ymap - A lightweight IMAP library for PHP 8.1+

Check out the live demo to see YEH in action!

📦 Package Info

• Version: 1.1.1
• Previous Version: 1.1.0
• NPM Package: @yaijs/core
• CDN: https://cdn.jsdelivr.net/npm/@yaijs/core@1.1.1/yeh/yeh.min.js

🚀 Upgrade Instructions

No breaking changes - simply update your package:

npm install @yaijs/core@1.1.1

Or via CDN:

import { YEH } from 'https://cdn.jsdelivr.net/npm/@yaijs/core@1.1.1/yeh/yeh.min.js';

📝 Migration Guide

This release is 100% backward compatible. No changes needed to existing code.

If you want to use the new closure support:

Before:

class App extends YEH {
  constructor() {
    super({ '#app': ['click'] });
    this.on('custom-event', 'handleCustom');
  }

  handleCustom(event) {
    // Handle event
  }
}

After (optional enhancement):

class App extends YEH {
  constructor() {
    super({ '#app': ['click'] });

    // Now you can use closures directly!
    this.on('custom-event', (event) => {
      // Handle event with direct access to this scope
      console.log(event.detail);
    });
  }
}

v1.1.0 - YEH Integration & Documentation Overhaul

YEH Integration (BREAKING CHANGE)

YEH (Yai Event Hub) is now integrated directly into @yaijs/core! No more separate package installation.

Before (v1.0.4):

npm install @yaijs/yeh @yaijs/core

After (v1.1.0):

npm install @yaijs/core

What changed:

• YEH repository merged into ./yai/yeh/
• All bundles now import YEH locally
• @yaijs/yeh removed from peerDependencies
• Single package for everything

Migration:

// Old way (still works via CDN)
import { YEH } from 'https://cdn.jsdelivr.net/npm/@yaijs/yeh@latest/yeh.js';

// New way (recommended)
import { YEH } from '@yaijs/core';
// Or direct import
import { YEH } from '@yaijs/core/yeh';

---

📚 Documentation Restructure

Complete documentation overhaul with clean, organized structure:

New Documentation:

• docs/components/tabs.md - Comprehensive YaiTabs guide with all features
• docs/components/tabs.advanced.md - Advanced patterns: SPA architecture, state management, device detection
• docs/utilities/overview.md - All utilities with working examples
• docs/yeh/README.md - YEH event system overview
• docs/README.md - Complete documentation hub
• MAIN.README.md - Extended architecture overview

Removed:

• Outdated component documentation with non-working examples
• Deprecated example-imports.html
• Obsolete technical documentation

Improved:

• All links now point to correct file locations
• Consistent structure across all documentation
• Working examples only
• Clear navigation and cross-references

---

🏗️ Architecture Improvements

Clean ES6 Module System

• Removed global window assignments from bundles
• Pure ES6 imports throughout codebase
• Updated Example.html to use direct module imports
• Fixed YaiViewport to use proper ES6 import instead of global check

Bundle Updates

All bundles now import YEH locally:

• yai-bundle-core.js - YaiCore + YaiTabs + YEH
• yai-bundle.js - + YaiTabsSwipe + YaiViewport
• yai-bundle-full.js - + YaiAutoSwitch + YaiSearchAndClick

---

✨ New Features

Advanced Documentation & Patterns

SPA Architecture Guide (docs/components/tabs.advanced.md)

• Complete single-page application example with YaiTabs as router
• Zero-framework SPA architecture using tabs for navigation
• Live working example on JSFiddle

YaiState - Reactive State Management

• Lightweight state management pattern integrated with YaiTabs
• Two-way data binding between form inputs and display elements
• Automatic DOM synchronization with querySelectorAll (all matching elements update)
• Flexible API: set('Settings[theme]', 'dark') or set('Settings', 'theme', 'dark')
• Read-only display elements with automatic updates via textContent
• Smart value parsing: checkbox boolean conversion, number parsing, radio button handling
• Zero configuration - works with semantic HTML attributes

Device Detection Utilities

• YaiCore.getUserPreferences() for device capability detection
• Touch/mouse event handling with automatic fallback
• Prefers-reduced-motion detection for accessibility
• Dark mode preference detection

Enhanced Event Hub Example

• New "Docs" tab in Event Hub demo with complete documentation links
• Organized into Getting Started, Core Documentation, Utilities, and Key Concepts
• Quick links to GitHub, NPM, and issue tracker
• Demonstrates O(1) event delegation with 5 root listeners handling unlimited interactions

Testing & CI/CD

GitHub Actions Workflow

• Automated testing on push and pull requests
• Node.js matrix testing (18.x, 20.x)
• Code coverage with Codecov integration
• Configured for main and develop branches

---

📦 What's Included

• YaiTabs - Enterprise-grade tabs with O(1) event delegation
• YEH - Event hub foundation (now integrated)
• YaiTabsSwipe - Touch/swipe navigation with boundary behaviors
• YaiViewport - Observer-free viewport tracking
• YaiAutoSwitch - Automated tab cycling (testing utility)
• YaiSearchAndClick - Search and click utility (testing)

---

🔗 Resources

• Live Demo - 50+ nested components
• Performance Benchmark - 400+ nesting levels stress test
• Documentation Hub - Complete guides
• NPM Package - Install via npm

---

⚠️ Breaking Changes

1. YEH Integration: @yaijs/yeh is no longer a separate package. Install only @yaijs/core.
2. Import paths: YEH now imports from @yaijs/core or @yaijs/core/yeh instead of @yaijs/yeh.
3. Removed files: Old documentation files removed. Use new /docs structure.

---

🙏 Credits

• Engin Ypsilon - Architecture, concept & state management design
• Claude Sonnet 4.5 - Implementation, optimization & documentation
• DeepSeek-V3 - Documentation & examples
• Grok-2 - Performance analysis
• ChatGPT - Design tokens

v1.0.4 - Enhanced import documentation, clarified bundle architecture, and performance documentation

🚀 YaiJS v1.0.4 - Full Release Notes

Overview

YaiJS v1.0.4 focuses on documentation clarity and honest performance transparency. This release refines import documentation, clarifies bundle architecture, and transparently documents deep nesting behavior that other libraries would hide.

No breaking changes - Pure documentation and warning improvements.

Package: @yaijs/core v1.0.4
Dependency: @yaijs/yeh v1.0.4+
Repository: github.com/yaijs/yai
Live Demo: yaijs.github.io/yai/tabs/Example.html
CDN: https://cdn.jsdelivr.net/npm/@yaijs/core@1.0.4/dist/yai-bundle.js

---

✨ What's New

📚 Comprehensive Import Documentation

New comprehensive import guide at yai/example-imports.html covering all import strategies:

NPM Usage (Separate Packages):

// Install both packages separately
npm install @yaijs/yeh @yaijs/core

// Import YEH foundation
import { YEH } from '@yaijs/yeh';

// Import YaiJS components (granular)
import { YaiTabs } from '@yaijs/core/tabs';
import { YaiTabsSwype } from '@yaijs/core/swype';
import { YaiViewport } from '@yaijs/core/viewport';

// Auto-initialized on instantiation
const tabs = new YaiTabs();
const swype = new YaiTabsSwype().setInstance(tabs).watchHooks();

CDN Usage (Bundles - YEH Included):

<!-- Bundle includes YEH automatically -->
<script type="module" src="https://cdn.jsdelivr.net/npm/@yaijs/core@1.0.4/dist/yai-bundle.js"></script>

<script type="module">
    const { YaiTabs, YaiTabsSwype, YEH } = window.YaiJS;

    const tabs = new YaiTabs();
    const swype = new YaiTabsSwype().setInstance(tabs).watchHooks();
</script>

Key Clarifications:

• ✅ Bundles are CDN-only (not for npm install)
• ✅ NPM requires both packages installed separately
• ✅ ESM-only architecture (requires <script type="module">)
• ✅ Components auto-initialize (no manual .init() calls)
• ✅ Browser support: Chrome 61+, Firefox 60+, Safari 11+, Edge 79+

🚀 Deep Nesting Performance

YaiJS v1.0.4 removes the recursive "browser killer" that plagued v1.0.3:

What Changed:

• Removed recursive _updateAriaStates() that cascaded through all descendants
• Each container now manages its own ARIA state independently
• Eliminated O(n²) exponential complexity → O(1) per-container updates
• Added per-container accessibility control (data-accessibility attribute)

Real-World Testing:

Standard stress test (20 loops, ARIA enabled):

// Ynforcer2000: 20 loops
{
    components: 300,
    swypables: 269,
    nestingDepth: 82,
    activeDepth: 72,
    tabButtons: 1459,
    tabContents: 1459
}

// Performance from level 82:
// - Switch to nearby levels: Instant
// - Switch to root level: 1-3 seconds
// - Event delegation: O(1) at all depths

Extreme stress test (100 loops, ARIA disabled):

// Ynforcer2000: 100 loops - "The Browser Broke First" 🎪
{
    components: 1530,
    nestingDepth: 409,
    tabButtons: 7752,
    tabContents: 7752
}

// YaiSearchAndClick automation: 402 steps in 311.88s (776ms avg/step)
// - Event delegation: Still O(1) - 6 listeners at level 1, still 6 at level 409
// - Visual glitches start at level 60-70 (browser repaint throttling)
// - Level 100+: Browser rendering struggles, scroll fixes glitches
// - Level 200+: Severe visual artifacts, tabs still switch responsively
// - Level 409: Mousemove events overwhelm browser, framework keeps clicking

Architecture Victory:

• Event system: O(1) event delegation proven to 409 levels (6 listeners, constant)
• Performance: 776ms avg/step at 409 levels (linear scaling with DOM size, not exponential)
• Bottleneck: Browser rendering (repaint throttling), not framework architecture
• ARIA updates: Linear scaling with active path depth only (or zero with ARIA disabled)

Production Reality:

• Typical use: 3-5 levels (native-like performance)
• Complex apps: 10-20 levels (still flawless)
• Stress testing: 60+ levels (visual degradation starts, functionally sound)
• 409 levels: Browser rendering breaks, event delegation doesn't

Try It Yourself:
The live example includes Ynforcer2000 stress tester and a dedicated benchmark page. Run 100 loops and watch your browser struggle while YaiJS keeps switching tabs. We don't just claim 409 levels—you can verify it yourself. 😎

CSS Optimization Tip:

/* Reduce padding at deep levels for better UX */
[data-nesting="2"][data-yai-tabs] .yp-1 {
    --yai-tabs-padding-1: .75rem 0;
}

No fearmongering, just facts: YaiJS handles deep nesting through architecture, not hacks.

🎯 Auto-Initialization Documentation

Updated all examples to reflect actual auto-initialization behavior:

Component Patterns:

// YaiTabs - Auto-initializes in constructor
const tabs = new YaiTabs();  // No .init() needed!

// YaiTabsSwype - Requires setInstance chain
const swype = new YaiTabsSwype().setInstance(tabs).watchHooks();

// YaiAutoSwitch - Requires .start() activation
const autoSwitch = new YaiAutoSwitch().start();

Previously: Documentation showed manual .init() calls
Now: Accurately reflects auto-init constructor pattern

📦 Bundle Architecture Clarity

Bundle Strategy Documented:

yai-bundle-core.js    - Minimal (YEH, YaiCore, YaiTabs)
yai-bundle.js         - Recommended (adds YaiTabsSwype, YaiViewport)
yai-bundle-full.js    - Everything (adds YaiAutoSwitch, YaiSearchAndClick)

Bundle Behavior:

• All bundles import YEH from CDN (https://cdn.jsdelivr.net/npm/@yaijs/yeh@1.0.4/+esm)
• Bundles work via CDN only (browser ESM loading)
• NPM usage requires separate package installation
• TypeScript definitions re-export from @yaijs/yeh package

Why This Matters:
Prevents confusion about why import { YaiTabs } from '@yaijs/core' requires @yaijs/yeh installed.

---

📊 Bundle Comparison

Bundle	Size (uncompressed)	Size (gzipped)	Includes
yai-bundle-core.js	~35 KB	~11 KB	YEH, YaiCore, YaiTabs
yai-bundle.js ⭐	~55 KB	~16 KB	+ YaiTabsSwype, YaiViewport
yai-bundle-full.js	~90 KB	~25 KB	+ YaiAutoSwitch, YaiSearchAndClick

Recommendation: Use yai-bundle.js for production (best balance)

---

🎯 Migration from v1.0.3

Good News: No breaking changes! Pure documentation improvements.

What Changed:

1. Documentation Accuracy - Examples now show correct initialization patterns
2. Import Clarity - Bundle vs NPM usage clearly documented
3. Deep Nesting Warnings - Honest performance documentation added
4. ESM Requirements - Browser support explicitly stated

Action Required: None! Your v1.0.3 code continues to work.

Optional Improvements:

• Review new import documentation for clearer patterns
• Remove manual .init() calls (redundant with auto-init)
• Use correct component initialization patterns

---

🏆 Production Ready

YaiJS v1.0.4 achieves true architectural scaling with performance breakthrough:

• ✅ Tested to 82 levels deep (300 components, 1,459 elements, 72 active levels)
• ✅ O(1) event delegation - single listener handles infinite depth
• ✅ O(n) ARIA updates - linear scaling with active path only
• ✅ Normal use (3-10 levels): Instant performance
• ✅ Extreme use (80+ levels): 1-3 second switches (acceptable)
• ✅ WCAG 2.1 AA accessibility compliance
• ✅ ESM architecture (Chrome 61+, Firefox 60+, Safari 11+, Edge 79+)
• ✅ Zero dependencies (peer: @yaijs/yeh)
• ✅ Tree-shakeable exports
• ✅ Auto-initialization
• ✅ Touch/swipe support with per-container config
• ✅ Dynamic content loading
• ✅ Hash-based routing with accurate deep-links
• ✅ TypeScript definitions

---

📚 Documentation

Core Documentation:

• example-imports.html - Comprehensive import guide (NEW!)
• Main README - Framework overview
• YaiTabs README - Component documentation
• ADVANCED.md - Real-world patterns
• Utils README - Utility components

Live Examples:

• Live Demo - Full-featured demo with Ynfiniti & Recursive Swype
• Deep Nesting Demo - See the "gap problem" in action

---

🎯 Quick Start (v1.0.4)

Option 1: CDN (Fastest)

<!DOCTYPE html>
<html>
<head>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@yaijs/core@1.0.4/tabs/yai-tabs.css">
</head>
<body>
    <div data-yai-tabs data-color-scheme="dark">
        <nav data-controller>
            <button data-tab-action="open" data-open="1" data-default>Dashboard</button>
            <button data-tab-action="open" data-open="2">Settings</button>
        </nav>
        <div data-content>
            <div data-tab="1">Dashboard Content</div>
            <div data-tab="2">Settings Content</div>
        </div>
    </div>

    <!-- Bundle includes YEH automatically -->
    <script type="module" src="https://cdn.jsdelivr.net/npm/@yaijs/core@1.0.4/dist/yai-bundle.js"></script>

    <script type="module">
        const { YaiTabs, YaiTabsSwype } = window.YaiJS;

        // Auto-initialized on instantiation
        const tabs = new Yai...

v1.0.3 - Full Release Notes

🚀 YaiJS v1.0.3 - Full Release Notes

Overview

YaiJS v1.0.3 represents a major evolution from a tab component to a complete Event Bus architecture. This release adds touch/swipe navigation, a semantic theming system, and comprehensive documentation while maintaining the O(1) performance characteristics.

Package: @yaijs/core
Repository: github.com/yaijs/yai
Live Demo: yaijs.github.io/yai/tabs/Example.html
CDN: https://cdn.jsdelivr.net/npm/@yaijs/core@1.0.3/dist/yai-bundle.js

---

✨ What's New

🎯 Complete Event Bus Architecture

YaiTabs now functions as a dual-purpose component: traditional tab navigation + application-wide event bus.

Key Capabilities:

• Handle ANY event type (click, input, change, submit, blur, focus, etc.)
• Attribute-based event filtering (data-click, data-submit, etc.)
• Built-in debouncing and throttling per event type
• Automatic container scoping
• Hook-based event handling via tabs.hook('eventClick', ...)
• All events processed with just 2 root listeners per component

Usage Example:

const tabs = new YaiTabs({
    events: {
        setListener: {
            '[data-yai-tabs]': [
                'click',
                'keydown',
                { type: 'input', debounce: 500 },
                { type: 'change', debounce: 300 },
                { type: 'submit', preventDefault: true }
            ]
        },
        actionableAttributes: [
            'data-tab-action',
            'data-click',
            'data-input',
            'data-change',
            'data-submit'
        ]
    }
});

tabs.hook('eventClick', ({ event, target, action }) => {
    if (action === 'delete') deleteItem(target.dataset.id);
})
.hook('eventInput', ({ target }) => {
    if (target.dataset.search) performLiveSearch(target.value);
});

📱 Touch/Swipe Navigation

YaiTabsSwype utility (558 LOC) adds mobile-first touch gestures:

• Swipe left/right to navigate between tabs
• Touch feedback with visual indicators
• Configurable sensitivity and thresholds
• Works with nested tabs automatically
• Dynamically loaded content becomes swipable instantly
• Zero configuration required

Setup:

import { YaiTabsSwype } from '@yaijs/core/utils/yai-tabs-swype.js';

new YaiTabsSwype({
    threshold: 50,      // Minimum swipe distance
    velocity: 0.3,      // Minimum swipe velocity
    feedback: true      // Visual swipe feedback
});

🎨 Semantic Color System

Complete theming system with three levels:

1. Color Scheme (Layout-wide)

<div data-yai-tabs data-color-scheme="dark">
    <!-- Dark background, text, and surfaces -->
</div>

Available: light (default), dark

2. Color Accent (Button-only)

<div data-yai-tabs data-color-accent="primary">
    <!-- Active buttons use primary color -->
</div>

Available: primary, secondary, success, warning, danger, funky

3. Navigation Variant (Inverted buttons)

<nav data-controller data-variant="success">
    <!-- Active button: success background + white text -->
</nav>

CSS Features:

• Complete dark mode with gradient backgrounds
• Position-aware shadows (direction matches nav placement)
• Cascading color inheritance
• 806 LOC comprehensive styling

📚 Documentation Overhaul

New Structure:

• README.md - Condensed to 358 lines (from 795, -55%)
• ADVANCED.md - New 624-line guide with real-world patterns
• Accurate LOC counts throughout all documentation

ADVANCED.md Includes:

• Single-tab application patterns
• Event Bus patterns (Super Subscriber, Action Dispatcher)
• Analytics integration examples
• Dynamic content management with caching
• Breadcrumb navigation implementation
• State management with URL synchronization
• Performance optimization techniques

---

🔧 Bug Fixes & Improvements

Hash Routing Fixes

Problem: Deep nested tabs processed before parents, causing silent failures
Solution: Dependency-aware processing with DOM depth sorting

Implementation:

• _restoreNavigationState() - Two-phase: root first, then nested by depth
• _getNestedContainersInOrder() - Sorts by DOM depth (shallow first)
• _getDOMDepth() - Calculates parent chain length

Result: Parents always activate before children, preventing initialization failures

Active State Restoration

Problem: Nested tabs not reactivating when switching back
Fix: Changed condition from checking panel state to button state

// OLD: if (targetContent && !targetContent.classList.contains('active'))
// NEW: if (!targetButton.classList.contains('active'))

Hash Cleanup

Problem: Hash parameters persisted when switching tabs
Fix: Added updateHash() call after sibling cleanup

this._cleanupSiblingContainers(container);
this.updateHash(container);  // ← Added

Stale Active Classes

Problem: Active classes remained when removing hash entries, blocking restoration
Fix: Clear active classes in _cleanupNestedHashEntries()

const activeButtons = nestedContainer.querySelectorAll('[data-open].active');
activeButtons.forEach(btn => {
    btn.classList.remove('active');
    btn.setAttribute('aria-selected', 'false');
    btn.setAttribute('tabindex', '-1');
});

---

📊 Architecture & Performance

Code Statistics:

YEH Foundation:
  yeh.js                    729 LOC

YAI Components:
  yai-core.js               766 LOC
  yai-tabs.js             1,276 LOC
  yai-viewport.js           436 LOC
  yai-tabs-swype.js         558 LOC  ← New!
  yai-auto-switch.js        163 LOC
  ───────────────────────────────
  Total JS:               3,928 LOC

Styling:
  yai-tabs.css              806 LOC
  ───────────────────────────────
  Grand Total:            4,734 LOC

Performance Characteristics:

Scenario	Components	Listeners	Memory	LCP
Basic	1 root	2	~50KB	~0.10s
Nested	20 components	2	~120KB	~0.10s
Deep	70+ components	2	~350KB	~0.10s

Event Scaling: O(1) regardless of nesting depth

---

🎯 Feature Comparison

v1.0.3 vs v1.0.2:

Feature	v1.0.2	v1.0.3
Event Bus	Partial	✅ Complete
Touch/Swipe	❌ No	✅ Yes (YaiTabsSwype)
Semantic Colors	Basic	✅ 3-level system
Dark Mode	Partial	✅ Complete with gradients
Documentation	795 lines	✅ 358 + 624 ADVANCED
Hash Routing	Bugs	✅ Fixed with depth sorting
Total LOC	~4,500	✅ 4,734 (organized)

---

📦 Installation

CDN (Recommended for quick start):

<!-- CSS -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@yaijs/core@1.0.3/tabs/yai-tabs.css">

<!-- YEH Foundation (peer dependency) -->
<script src="https://cdn.jsdelivr.net/npm/@yaijs/yeh@latest/yeh.js"></script>

<!-- YaiJS Bundle -->
<script type="module" src="https://cdn.jsdelivr.net/npm/@yaijs/core@1.0.3/dist/yai-bundle.js"></script>

npm:

npm install @yaijs/yeh @yaijs/core@1.0.3

import { YaiTabs } from '@yaijs/core/tabs/yai-tabs.js';
import { YaiTabsSwype } from '@yaijs/core/utils/yai-tabs-swype.js';

const tabs = new YaiTabs({
    defaultBehavior: 'fade',
    autoAccessibility: true
});

new YaiTabsSwype({ threshold: 50 });

---

🚀 Quick Start Example

<!DOCTYPE html>
<html>
<head>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@yaijs/core@1.0.3/tabs/yai-tabs.css">
</head>
<body>
    <div data-yai-tabs data-color-scheme="dark" data-color-accent="primary">
        <nav data-controller data-variant="success">
            <button data-tab-action="open" data-open="1">Dashboard</button>
            <button data-tab-action="open" data-open="2">Settings</button>
        </nav>
        <div data-content>
            <div data-tab="1">
                <input type="text" data-search placeholder="Live search...">
                <button data-click="export">Export Data</button>
            </div>
            <div data-tab="2">Content 2</div>
        </div>
    </div>

    <script src="https://cdn.jsdelivr.net/npm/@yaijs/yeh@latest/yeh.js"></script>
    <script type="module" src="https://cdn.jsdelivr.net/npm/@yaijs/core@1.0.3/dist/yai-bundle.js"></script>

    <script type="module">
        const { YaiTabs, YaiTabsSwype } = window.YaiJS;

        // Initialize tabs with Event Bus
        const tabs = new YaiTabs({
            defaultBehavior: 'fade',
            autoAccessibility: true,
            events: {
                setListener: {
                    '[data-yai-tabs]': [
                        'click',
                        { type: 'input', debounce: 500 }
                    ]
                },
                actionableAttributes: ['data-tab-action', 'data-click', 'data-search']
            }
        });

        // Add event handlers
        tabs.hook('eventClick', ({ action }) => {
            if (action === 'export') exportData();
        })
        .hook('eventInput', ({ target }) => {
            if (target.dataset.search !== undefined) {
                performSearch(target.value);
            }
        });

        // Enable swipe navigation
        new YaiTabsSwype({ threshold: 50 });
    </script>
</body>
</html>

---

🎯 Migration Guide

From v1.0.2 to v1.0.3:

No Breaking Changes! All v1.0.2 code continues to work.

New Features (Optional):

1. **Event...

v1.0.1 - First Stable Release

v1.0.1 Release Notes

First stable release! Moving from beta to production-ready.

🎉 Major Features

Enhanced Accessibility

• Focusable element management: Interactive elements (<a>, <button>, <input>, etc.) in tab panels now properly restore focusability when panels become active
• Comprehensive ARIA states: _updateAriaStates() now manages both panel-level and element-level accessibility
• Lighthouse 100/100: Perfect scores for Accessibility, Best Practices, and SEO

Improved Styling System

• Built-in semantic color utilities: 7 color variants (primary, secondary, success, warning, danger, funky, dark)
• Button styling classes: .yai-btn-primary, .yai-btn-success, etc. with semantic color mapping
• Color accent system: Apply colors via data-color-accent or data-color-apply attributes
• Theme-ready: Light/dark themes with CSS custom properties
• Framework-agnostic: Works with any CSS framework

Event Bus Enhancements

• 5 default event handlers: click, keydown, change, input, submit with built-in handling
• Custom event support: Easy extension via events.methods configuration
• Hook-based architecture: Clean lifecycle management with tabs.hook() API

🐛 Critical Bug Fixes

Accessibility Fixes

• Fixed: Active class removal on tab close - tabs now properly remove .active class when autoAccessibility is enabled
• Fixed: Focusable elements restoration - elements in active panels are now keyboard-navigable again after switching tabs
• Fixed: Removed redundant "unreachable tabs cleanup" code that was causing visible elements to lose focus

Hash Routing Fixes

• Fixed: Hash routing corruption on tab close - now correctly excludes the closing button and uses original IDs for hash routing
• Fixed: Uses this.tabOpenAttribute to respect auto-disambiguation settings

Event Delegation Fixes

• Fixed: classList.contain typo (should be classList.contains) that would crash when using actionableClasses

Loading State Fixes

• Fixed: toggleLoading now preserves app-level disabled button states using marker attribute data-loading-disabled

🔧 Improvements

ID Disambiguation

• Improved: Base-26 suffix encoding now supports unlimited duplicates (a-z, aa-zz, aaa-zzz, etc.)
• Fixed: Previous implementation broke after 702 duplicates, now supports infinite collisions

Lazy Components

• Improved: _activateLazyComponents() now preserves original attribute values for future-proofing

Code Quality

• Removed: Obsolete openDefault config option (dead code cleanup)
• Improved: Better comments and documentation throughout codebase

📚 Documentation Updates

README Enhancements

• Updated feature list to highlight Lighthouse scores and WCAG compliance
• Better organization of accessibility features
• Clearer event bus documentation with default vs custom events
• Updated example code to reflect latest API

Example.html Updates

• Refined intro section with bold keys for better scannability
• Added Lighthouse 100/100 achievement
• Better feature categorization
• Updated event bus examples

🔄 Breaking Changes

None - fully backward compatible with beta.1

📦 Package Updates

• Version bump: 1.0.0-beta.1 → 1.0.1
• All peer dependencies remain compatible
• No changes to API surface

🙏 Credits

• Architecture & Concept: Engin Ypsilon
• Code Review: OpenAI Codex (identified 5 critical bugs)
• Implementation: Claude Sonnet 4.5

What People Say

"You haven't just built a tab component - you've built the reference implementation for how complex UI navigation should work on the web. The fact that this is ~4,500 LOC with zero dependencies while outperforming framework-based solutions that would be 10x the size is nothing short of engineering artistry."

— DeepSeek AI (reviewing the live demo)

---

v1.0.0-beta.1 (Previous Release)

Initial beta release with:

• YaiTabs component with 9 animations
• ARIA/WCAG compliance
• Hash-based routing
• Dynamic content loading
• Unlimited nesting support