@andreyshpigunov/x 0.3.89 → 0.4.0

package/src/components/x/sheets.js

@@ -51,21 +51,38 @@
  *     <div x-sheet="b1">Content B1</div>
  *   </div>
  *
+ * Events:
+ *   const sheetsContainer = document.querySelector('#mySheets');
+ *
+ *   sheetsContainer.addEventListener('sheets:ready', (e) => {
+ *     console.log('Sheets initialized', e.detail);
+ *   });
+ *
+ *   sheetsContainer.addEventListener('sheets:selected', (e) => {
+ *     console.log('Tab selected:', e.detail.sheet);
+ *   });
+ *
+ *   sheetsContainer.addEventListener('sheets:destroy', (e) => {
+ *     console.log('Sheets destroyed', e.detail);
+ *   });
+ *
  * Public API:
  *
  * @method init() - Initializes all [x-sheets] components on the page.
  *   Binds click events to [x-sheet-open] elements and activates tabs with .active class.
  *   Safe for multiple calls - automatically destroys previous listeners.
+ *   Dispatches 'sheets:ready' event on each container when done.
  *   @example
  *     sheets.init();
  *
  * @method destroy() - Removes all sheets-related event listeners and resets state.
- *   Safe to call multiple times.
+ *   Safe to call multiple times. Dispatches 'sheets:destroy' event on each container.
  *   @example
  *     sheets.destroy();
  *
  * @method show(xSheet) - Programmatically switches to a specific sheet.
  *   Activates the tab and corresponding content block by matching x-sheet value.
+ *   Dispatches 'sheets:selected' event on the container when tab changes.
  *   @param {string} xSheet - The value of x-sheet and x-sheet-open to activate.
  *   @example
  *     sheets.show('tab2');
@@ -108,8 +125,26 @@
  * - Test nested sheets behavior
  * - Handle errors gracefully
  *
+ * @example
+ * // Vanilla JS — plain HTML
+ * // index.html:
+ * // <div x-sheets id="mySheets">
+ * //   <nav>
+ * //     <button type="button" x-sheet-open="tab1" class="active">Tab 1</button>
+ * //     <button type="button" x-sheet-open="tab2">Tab 2</button>
+ * //   </nav>
+ * //   <section x-sheet="tab1" class="active">Content 1</section>
+ * //   <section x-sheet="tab2">Content 2</section>
+ * // </div>
+ * //
+ * // <script type="module">
+ * //   import { sheets } from './src/components/x/sheets.js';
+ * //   window.addEventListener('DOMContentLoaded', () => sheets.init());
+ * //   window.addEventListener('pagehide', () => sheets.destroy());
+ * // </script>
+ *
  * @author Andrey Shpigunov
- * @version 0.3
+ * @version 0.4
  * @since 2025-07-18
  */
 
@@ -130,7 +165,7 @@ class Sheets {
      * @private
      */
     this._handlers = new Map();
-
+    
     /**
      * Initialization flag to control safe reinitialization.
      * @type {boolean}
@@ -138,7 +173,23 @@ class Sheets {
      */
     this._initialized = false;
   }
-
+  
+  /**
+   * Dispatch custom event on specific container
+   * @param {HTMLElement} container - The x-sheets container element
+   * @param {string} eventName - Event name (without 'sheets:' prefix)
+   * @param {Object} detail - Event detail data
+   * @private
+   */
+  _dispatchEvent(container, eventName, detail = {}) {
+    const event = new CustomEvent(`sheets:${eventName}`, {
+      detail,
+      bubbles: true,
+      cancelable: false
+    });
+    container.dispatchEvent(event);
+  }
+  
   /**
    * Validates sheet value to prevent XSS attacks.
    * Only allows alphanumeric characters, hyphens, and underscores.
@@ -150,7 +201,7 @@ class Sheets {
     if (typeof value !== 'string' || !value) return false;
     return /^[a-zA-Z0-9_-]+$/.test(value);
   }
-
+  
   /**
    * Initializes all `[x-sheets]` components on the page.
    *
@@ -158,44 +209,47 @@ class Sheets {
    * - Activates the tab with `.active` class by default.
    * - SECURITY: Validates sheet values before use.
    * - Safe for multiple calls; previous listeners are removed.
+   * - Dispatches 'sheets:ready' event on each container when initialization is complete.
    */
   init() {
     if (this._initialized) {
       this.destroy();
     }
-
+    
     const sheets = lib.qsa('[x-sheets]');
-    if (!sheets.length) return;
-
+    if (!sheets.length) {
+      return;
+    }
+    
     for (const sheet of sheets) {
       if (!sheet) continue;
-
+      
       const tabs = lib.qsa('[x-sheet-open]:not([x-sheet-open] [x-sheet-open])', sheet);
-
+      
       for (const tab of tabs) {
         if (!tab) continue;
-
+        
         const sheetValue = tab.getAttribute('x-sheet-open');
         if (!sheetValue) {
           console.warn('sheets.init: Tab has x-sheet-open attribute but no value', tab);
           continue;
         }
-
+        
         // SECURITY: Validate sheet value
         if (!this._isValidSheetValue(sheetValue)) {
           console.error('sheets.init: Invalid sheet value (security check failed):', sheetValue);
           continue;
         }
-
+        
         const handler = (e) => {
           e.preventDefault();
           this.show(sheetValue);
         };
-
+        
         tab.addEventListener('click', handler);
         this._handlers.set(tab, handler);
       }
-
+      
       const active = lib.qs('[x-sheet-open].active', sheet);
       if (active) {
         const activeValue = active.getAttribute('x-sheet-open');
@@ -203,91 +257,157 @@ class Sheets {
           this.show(activeValue);
         }
       }
+      
+      // Dispatch ready event on this container
+      this._dispatchEvent(sheet, 'ready', {
+        container: sheet,
+        timestamp: Date.now(),
+        initialized: true
+      });
     }
-
+    
     this._initialized = true;
   }
-
+  
   /**
    * Removes all event listeners and resets internal state.
-   * Safe to call multiple times.
+   * Safe to call multiple times. Dispatches 'sheets:destroy' event on each container.
    */
   destroy() {
+    // Store containers before clearing handlers
+    const containers = new Set();
+    for (const [el] of this._handlers.entries()) {
+      const container = el.closest('[x-sheets]');
+      if (container) {
+        containers.add(container);
+      }
+    }
+    
+    // Remove all event listeners
     for (const [el, handler] of this._handlers.entries()) {
       el.removeEventListener('click', handler);
     }
-
+    
     this._handlers.clear();
     this._initialized = false;
+    
+    // Dispatch destroy event on each container
+    for (const container of containers) {
+      this._dispatchEvent(container, 'destroy', {
+        container: container,
+        timestamp: Date.now(),
+        wasInitialized: true
+      });
+    }
   }
-
+  
   /**
    * Activates a tab and its corresponding content block by `x-sheet` key.
    * SECURITY: Validates sheet value and uses CSS.escape() for selectors.
+   * Dispatches 'sheets:selected' event on the container when tab changes.
    *
    * @param {string} xSheet - The value of `x-sheet` and `x-sheet-open` to activate.
+   * @param {Object} options - Optional configuration.
+   * @param {boolean} options.silent - If true, prevents dispatching 'sheets:selected' event.
+   * @param {string} options.source - Source of the selection ('api' or 'user').
    */
-  show(xSheet) {
+  show(xSheet, options = { silent: false, source: 'api' }) {
     if (!xSheet || typeof xSheet !== 'string') {
       console.error('sheets.show: Sheet value is required and must be a string');
       return;
     }
-
+    
     // SECURITY: Validate sheet value
     if (!this._isValidSheetValue(xSheet)) {
       console.error('sheets.show: Invalid sheet value (security check failed):', xSheet);
       return;
     }
-
+    
     // SECURITY: Use CSS.escape() to prevent XSS in selectors
     const escapedValue = CSS.escape(xSheet);
     const targetBody = lib.qs(`[x-sheet="${escapedValue}"]`);
-
+    
     if (!targetBody) {
       console.warn('sheets.show: Target content not found:', xSheet);
       return;
     }
-
-    const sheets = targetBody.closest('[x-sheets]');
-    if (!sheets) {
+    
+    const container = targetBody.closest('[x-sheets]');
+    if (!container) {
       console.warn('sheets.show: Sheets container not found for:', xSheet);
       return;
     }
-
-    const selectedTab = lib.qs(`[x-sheet-open="${escapedValue}"]`, sheets);
-
+    
+    const selectedTab = lib.qs(`[x-sheet-open="${escapedValue}"]`, container);
+    
     if (!selectedTab) {
       console.warn('sheets.show: Tab not found:', xSheet);
       return;
     }
-
+    
     // Check if already active
     if (
       selectedTab.classList.contains('active') &&
       targetBody.classList.contains('active')
     ) {
+      // Dispatch selected event even if already active (for consistency)
+      if (!options.silent) {
+        this._dispatchEvent(container, 'selected', {
+          sheet: xSheet,
+          tab: selectedTab,
+          content: targetBody,
+          container: container,
+          previousSheet: xSheet,
+          previousTab: selectedTab,
+          previousContent: targetBody,
+          wasActive: true,
+          source: options.source || 'api',
+          timestamp: Date.now()
+        });
+      }
       return; // Already active
     }
-
+    
+    // Get previous active tab and body for event data
+    const previousTab = lib.qs('[x-sheet-open].active', container);
+    const previousBody = lib.qs('[x-sheet].active', container);
+    const previousSheet = previousTab ? previousTab.getAttribute('x-sheet-open') : null;
+    
     // Remove active class from all tabs and bodies in this container
-    const tabs = lib.qsa('[x-sheet-open]', sheets);
-    const bodies = lib.qsa('[x-sheet]', sheets);
-
+    const tabs = lib.qsa('[x-sheet-open]', container);
+    const bodies = lib.qsa('[x-sheet]', container);
+    
     for (const tab of tabs) {
       if (tab && tab.classList.contains('active')) {
         tab.classList.remove('active');
       }
     }
-
+    
     for (const body of bodies) {
       if (body && body.classList.contains('active')) {
         body.classList.remove('active');
       }
     }
-
+    
     // Add active class to selected tab and body
     selectedTab.classList.add('active');
     targetBody.classList.add('active');
+    
+    // Dispatch selected event on the container
+    if (!options.silent) {
+      this._dispatchEvent(container, 'selected', {
+        sheet: xSheet,
+        tab: selectedTab,
+        content: targetBody,
+        container: container,
+        previousSheet: previousSheet,
+        previousTab: previousTab,
+        previousContent: previousBody,
+        wasActive: false,
+        source: options.source || 'api',
+        timestamp: Date.now()
+      });
+    }
   }
 }
 

package/src/components/x/slider.css

@@ -1,3 +1,12 @@
+/*----------------------------------------
+slider.css
+Slider
+
+Created by Andrey Shpigunov at 13.04.2026
+All right reserved.
+----------------------------------------*/
+
+
 :root {
   --slider-point-color: #ffffff66;
   --slider-point-color-active: #fff;
@@ -22,7 +31,7 @@
   overscroll-behavior: contain;    /* не отдаём overscroll родителю */
 }
 .slider_touch {
-  touch-action: pan-y !important;  /* разрешаем только вертикальные жесты браузеру */
+  touch-action: pan-y;  /* разрешаем только вертикальные жесты браузеру */
 }
 .slider-wrapper {
   display: flex;

package/src/components/x/slider.js

@@ -122,6 +122,21 @@
  * - Touch events support for mobile devices
  * - CSS transforms and transitions
  *
+ * @example
+ * // Vanilla JS — plain HTML
+ * // index.html:
+ * // <div x-slider='{"gap":16,"rubber":true,"resetOnMouseout":true,"touch":true}'>
+ * //   <div><img data-src="slide1.jpg" alt="Slide 1"></div>
+ * //   <div><img data-src="slide2.jpg" alt="Slide 2"></div>
+ * //   <div><img data-src="slide3.jpg" alt="Slide 3"></div>
+ * // </div>
+ * //
+ * // <script type="module">
+ * //   import { slider } from './src/components/x/slider.js';
+ * //   window.addEventListener('DOMContentLoaded', () => slider.init());
+ * //   window.addEventListener('pagehide', () => slider.destroy());
+ * // </script>
+ *
  * @author Andrey Shpigunov
  * @version 0.3
  * @since 2025-07-18

package/src/components/x/space.css

@@ -7,13 +7,25 @@ All right reserved.
 ----------------------------------------*/
 
 
+/*
+  .space[0-10] (s,m,l,xl)   - vertical space
+*/
+
 @for $i from 0 to 10 {
   .space$(i) {
     height: var(--space-$(i));
   }
 }
 
-@media (--medium) {
+@media (min-width: 640px) {
+  @for $i from 0 to 10 {
+    .s\:space$(i) {
+      height: var(--space-$(i));
+    }
+  }
+}
+
+@media (min-width: 768px) {
   @for $i from 0 to 10 {
     .m\:space$(i) {
       height: var(--space-$(i));
@@ -21,10 +33,18 @@ All right reserved.
   }
 }
 
-@media (--large) {
+@media (min-width: 1024px) {
   @for $i from 0 to 10 {
     .l\:space$(i) {
       height: var(--space-$(i));
     }
   }
 }
+
+@media (min-width: 1280px) {
+  @for $i from 0 to 10 {
+    .xl\:space$(i) {
+      height: var(--space-$(i));
+    }
+  }
+}

package/src/components/x/sticky.css

@@ -7,25 +7,20 @@ All right reserved.
 ----------------------------------------*/
 
 
-/* !- Sticky */
-
-
-/* .sticky (m,l,xl) */
-
+/* .sticky (s,m,l,xl) */
 
 .sticky {
-  position: sticky !important;
-  top: 0;
+  position: sticky;
 }
-@media (--medium) {
-  .s\:sticky { position: sticky !important; top: 0 }
+@media (max-width: 640px) {
+  .s\:sticky { position: sticky }
 }
-@media (--medium) {
-  .m\:sticky { position: sticky !important; top: 0 }
+@media (min-width: 768px) {
+  .m\:sticky { position: sticky }
 }
-@media (--large) {
-  .l\:sticky { position: sticky !important; top: 0 }
+@media (min-width: 1024px) {
+  .l\:sticky { position: sticky }
 }
-@media (--xlarge) {
-  .xl\:sticky { position: sticky !important; top: 0 }
+@media (min-width: 1280px) {
+  .xl\:sticky { position: sticky }
 }

package/src/components/x/sticky.js

@@ -23,7 +23,7 @@
  *     top: 0;
  *     z-index: 100;
  *   }
- *   .sticky.sticky_on {
+ *   .sticky.sticky--on {
  *     box-shadow: 0 2px 4px rgba(0,0,0,0.1);
  *   }
  *
@@ -76,7 +76,7 @@
  * CSS classes:
  *
  * - `.sticky` - Required class to mark element for observation
- * - `.sticky_on` - Added when element is in sticky state (not fully visible)
+ * - `.sticky--on` - Added when element is in sticky state (not fully visible)
  * - Removed when element returns to normal flow
  *
  * How it works:
@@ -85,7 +85,7 @@
  * 2. Uses threshold: 1 (element must be fully visible)
  * 3. Uses rootMargin: '-1px 0px 0px 0px' (triggers when top edge leaves viewport)
  * 4. When intersectionRatio < 1, element is sticky
- * 5. Toggles `sticky_on` class and dispatches events
+ * 5. Toggles `sticky--on` class and dispatches events
  *
  * Observer configuration:
  *
@@ -114,6 +114,23 @@
  * - Modern browsers (Chrome 51+, Firefox 55+, Safari 12.1+, Edge 15+)
  * - Falls back gracefully if not supported (no errors, just no functionality)
  *
+ * @example
+ * // Vanilla JS — plain HTML
+ * // index.html:
+ * // <header class="sticky"><nav>Navigation</nav></header>
+ * // <main style="min-height: 200vh">Scroll content</main>
+ * //
+ * // <style>
+ * //   .sticky { position: sticky; top: 0; z-index: 100; }
+ * //   .sticky.sticky--on { box-shadow: 0 2px 4px rgba(0,0,0,0.1); }
+ * // </style>
+ * //
+ * // <script type="module">
+ * //   import { sticky } from './src/components/x/sticky.js';
+ * //   window.addEventListener('DOMContentLoaded', () => sticky.init());
+ * //   window.addEventListener('pagehide', () => sticky.destroy());
+ * // </script>
+ *
  * @author Andrey Shpigunov
  * @version 0.2
  * @since 2025-07-17
@@ -133,7 +150,7 @@ class Sticky {
      * Class to apply when sticky state is active.
      * @type {string}
      */
-    this.activeClass = 'sticky_on';
+    this.activeClass = 'sticky--on';
 
     /**
      * Root margin for IntersectionObserver.

package/src/components/x/typo.css

@@ -7,9 +7,6 @@ All right reserved.
 ----------------------------------------*/
 
 
-/* !- Typo */
-
-
 /*
   .h[1-6]
   .mono
@@ -22,7 +19,6 @@ All right reserved.
   .lh[0-9] (m,l,xl)  - values: 1.0-1.9
 */
 
-
 :root {
   --headers-margin-top: 1em;
   --headers-margin-bottom: .5em;
@@ -145,15 +141,15 @@ pre {
 
 /* !- Lists */
 
-ul, 
-ol, 
+ul,
+ol,
 dl {
   margin: var(--paragraph-margin) 0;
   padding-left: calc(var(--paragraph-margin) * 1.5);
   
-  & ul, 
-  & ol, 
-  & dl, 
+  & ul,
+  & ol,
+  & dl,
   & li {
     margin: var(--space-1) 0;
   }
@@ -210,19 +206,7 @@ table {
   .fw$(i) { font-weight: $(i) }
 }
 
-@media (--small) {
-  @for $i from 10 to 19 {
-    .s\:fs$(i) { font-size: calc($(i)rem / 10) }
-  }
-  @for $i from 20 to 64 by 2 {
-    .s\:fs$(i) { font-size: calc($(i)rem / 10) }
-  }
-  @for $i from 100 to 900 by 100 {
-    .s\:fw$(i) { font-weight: $(i) }
-  }
-}
-
-@media (--medium) {
+@media (min-width: 768px) {
   @for $i from 10 to 19 {
     .m\:fs$(i) { font-size: calc($(i)rem / 10) }
   }
@@ -234,7 +218,7 @@ table {
   }
 }
 
-@media (--large) {
+@media (min-width: 1024px) {
   @for $i from 10 to 19 {
     .l\:fs$(i) { font-size: calc($(i)rem / 10) }
   }
@@ -246,7 +230,7 @@ table {
   }
 }
 
-@media (--xlarge) {
+@media (min-width: 1280px) {
   @for $i from 10 to 19 {
     .xl\:fs$(i) { font-size: calc($(i)rem / 10) }
   }
@@ -265,22 +249,17 @@ table {
   .ls$(i) { letter-spacing: calc($(i)em * 0.625) }
 }
 
-@media (--small) {
-  @for $i from 0 to 4 {
-    .s\:ls$(i) { letter-spacing: calc($(i)em * 0.625) }
-  }
-}
-@media (--medium) {
+@media (min-width: 768px) {
   @for $i from 0 to 4 {
     .m\:ls$(i) { letter-spacing: calc($(i)em * 0.625) }
   }
 }
-@media (--large) {
+@media (min-width: 1024px) {
   @for $i from 0 to 4 {
     .l\:ls$(i) { letter-spacing: calc($(i)em * 0.625) }
   }
 }
-@media (--xlarge) {
+@media (min-width: 1280px) {
   @for $i from 0 to 4 {
     .xl\:ls$(i) { letter-spacing: calc($(i)em * 0.625) }
   }
@@ -293,22 +272,17 @@ table {
   .lh$(i)  { line-height: 1.$(i) }
 }
 
-@media (--small) {
-  @for $i from 0 to 9 {
-    .s\:lh$(i)  { line-height: 1.$(i) }
-  }
-}
-@media (--medium) {
+@media (min-width: 768px) {
   @for $i from 0 to 9 {
     .m\:lh$(i)  { line-height: 1.$(i) }
   }
 }
-@media (--large) {
+@media (min-width: 1024px) {
   @for $i from 0 to 9 {
     .l\:lh$(i)  { line-height: 1.$(i) }
   }
 }
-@media (--xlarge) {
+@media (min-width: 1280px) {
   @for $i from 0 to 9 {
     .xl\:lh$(i)  { line-height: 1.$(i) }
   }