tyrell-components 1.0.0-TC45 → 1.0.0-TC47

package/lib/components/tooltip.js

@@ -1,46 +1,16 @@
-/**
- * Tooltip Component
- *
- * Shows helpful content on hover/focus with smart positioning.
- * Follows the same shadow DOM pattern as other components.
- *
- * @example
- * <ty-tooltip placement="top" flavor="primary" delay="600">
- *   Helpful tooltip text
- * </ty-tooltip>
- */
-import { findBestPosition, placementPreferences } from '../utils/positioning.js';
+import { findBestPosition, preferenceChain } from '../utils/positioning.js';
 import { ensureStyles } from '../utils/styles.js';
 import { tooltipStyles } from '../styles/tooltip.js';
-// ============================================================================
-// WeakMaps for State Management
-// ============================================================================
 const autoUpdateCleanup = new WeakMap();
 const eventCleanup = new WeakMap();
 const timeoutState = new WeakMap();
 const popoverElements = new WeakMap();
-// Cached separately from getAnchorElement()/el.parentElement — by the time
-// disconnectedCallback fires the element has already been removed from the
-// DOM, so parentElement is null and cleanup() couldn't otherwise find the
-// anchor to strip its aria-describedby.
 const anchorElements = new WeakMap();
-// ============================================================================
-// Helper Functions
-// ============================================================================
-/**
- * Normalize the flavor attribute. Any plain identifier (with optional +/-
- * shade suffix) is accepted — built-ins and custom flavors alike get their
- * colors from tokens in applyFlavorStyles(). Anything else (including
- * would-be CSS injection through the attribute) falls back to 'dark'.
- */
 function validateFlavor(flavor) {
     const full = flavor || 'dark';
     const base = full.replace(/[+-]$/, '');
     return /^[A-Za-z][A-Za-z0-9_-]*$/.test(base) ? full : 'dark';
 }
-/**
- * Get timeout state for element
- */
 function getTimeoutState(el) {
     let state = timeoutState.get(el);
     if (!state) {
@@ -49,15 +19,9 @@ function getTimeoutState(el) {
     }
     return state;
 }
-/**
- * Parse boolean attribute
- */
 function parseBoolAttr(el, name) {
     return el.hasAttribute(name);
 }
-/**
- * Parse integer attribute
- */
 function parseIntAttr(el, name, defaultValue) {
     const value = el.getAttribute(name);
     if (value === null)
@@ -65,9 +29,6 @@ function parseIntAttr(el, name, defaultValue) {
     const parsed = parseInt(value, 10);
     return isNaN(parsed) ? defaultValue : parsed;
 }
-/**
- * Read all tooltip attributes from element
- */
 function getTooltipAttributes(el) {
     return {
         placement: (el.getAttribute('placement') || 'top'),
@@ -77,17 +38,9 @@ function getTooltipAttributes(el) {
         flavor: validateFlavor(el.getAttribute('flavor')),
     };
 }
-/**
- * Get the parent element (anchor)
- */
 function getAnchorElement(el) {
     return el.parentElement;
 }
-/**
- * Add `id` to the anchor's aria-describedby without clobbering a value the
- * consumer may already have set for something else (WAI-ARIA APG tooltip
- * pattern: append, don't overwrite).
- */
 function addDescribedBy(anchor, id) {
     const ids = (anchor.getAttribute('aria-describedby') || '').split(/\s+/).filter(Boolean);
     if (!ids.includes(id)) {
@@ -95,7 +48,6 @@ function addDescribedBy(anchor, id) {
         anchor.setAttribute('aria-describedby', ids.join(' '));
     }
 }
-/** Inverse of addDescribedBy — used on teardown. */
 function removeDescribedBy(anchor, id) {
     const ids = (anchor.getAttribute('aria-describedby') || '').split(/\s+/).filter((x) => x && x !== id);
     if (ids.length > 0) {
@@ -105,24 +57,14 @@ function removeDescribedBy(anchor, id) {
         anchor.removeAttribute('aria-describedby');
     }
 }
-/**
- * Get or create popover element using Popover API
- * The popover is created in document.body for top-layer placement
- */
 function getOrCreatePopover(el) {
     let popover = popoverElements.get(el);
     if (!popover) {
-        // Create popover element
         popover = document.createElement('div');
         popover.id = `ty-tooltip-${Math.random().toString(36).slice(2, 11)}`;
         popover.setAttribute('popover', 'manual');
-        // WAI-ARIA APG tooltip pattern: the popover needs role="tooltip" and
-        // the trigger needs aria-describedby pointing at it, or a keyboard/
-        // screen-reader user gets no indication the tooltip exists at all —
-        // hover-only visibility isn't enough on its own.
         popover.setAttribute('role', 'tooltip');
         popover.className = 'ty-tooltip-popover';
-        // Apply inline styles (since popover is outside shadow DOM, we need inline styles)
         const styles = `
       position: fixed;
       margin: 0;
@@ -141,51 +83,24 @@ function getOrCreatePopover(el) {
       pointer-events: none;
     `;
         popover.style.cssText = styles;
-        // Append to body
         document.body.appendChild(popover);
-        // Store reference
         popoverElements.set(el, popover);
         const anchor = anchorElements.get(el);
         if (anchor)
             addDescribedBy(anchor, popover.id);
     }
-    // Resync on every call (not just creation) — content and flavor can
-    // change between shows, and this is eagerly called from connectedCallback
-    // (see below) so a keyboard user tabbing straight to the trigger gets a
-    // real aria-describedby target immediately, not one that only exists
-    // after the (default 600ms) hover delay has already elapsed.
     const { flavor } = getTooltipAttributes(el);
     popover.setAttribute('data-flavor', flavor);
-    // innerHTML, not textContent — the tooltip's own docs promise "Content is
-    // any HTML nested inside the ty-tooltip element"; textContent silently
-    // stripped it. Relocating the developer's own authored markup between two
-    // elements they control isn't a new trust boundary (same model ty-select
-    // already uses to clone rich option HTML into its trigger).
     popover.innerHTML = el.innerHTML;
     applyFlavorStyles(popover, flavor);
     return popover;
 }
-/**
- * Apply flavor-specific styles to popover.
- *
- * dark / light / info are hand-written extras; every other flavor —
- * built-in semantic or custom — is one token formula, with neutral
- * fallbacks so a custom flavor with missing tokens degrades gracefully.
- * flavor has passed validateFlavor's identifier guard, so interpolating
- * it into var() names is safe.
- */
 function applyFlavorStyles(popover, flavor) {
-    // Reset to defaults first
     popover.style.removeProperty('background');
     popover.style.removeProperty('color');
     popover.style.removeProperty('border-color');
     switch (flavor) {
         case 'dark':
-            // Default look — theme-INDEPENDENT on purpose (matches Material/
-            // Bootstrap/Ant/Shoelace: a tooltip stays a fixed dark chip whether
-            // the page is light or dark, so it always pops). Routed through the
-            // --ty-tooltip-* tokens (defined once in :root, not redeclared in
-            // html.dark) so consumers can retheme without a flavor.
             popover.style.background = 'var(--ty-tooltip-bg, #262626)';
             popover.style.color = 'var(--ty-tooltip-color, #f5f5f5)';
             popover.style.borderColor = 'var(--ty-tooltip-border, #404040)';
@@ -211,9 +126,6 @@ function applyFlavorStyles(popover, flavor) {
         }
     }
 }
-/**
- * Update tooltip position based on current anchor/popover state
- */
 function updatePosition(el) {
     const { placement, offset } = getTooltipAttributes(el);
     const anchor = getAnchorElement(el);
@@ -222,26 +134,16 @@ function updatePosition(el) {
         console.warn('[ty-tooltip] updatePosition: missing anchor or popover');
         return;
     }
-    // Calculate preferences based on placement
-    const preferences = placement === 'top' ? placementPreferences.tooltip :
-        placement === 'bottom' ? ['bottom', 'top', 'left', 'right'] :
-            placement === 'left' ? ['left', 'right', 'top', 'bottom'] :
-                placement === 'right' ? ['right', 'left', 'top', 'bottom'] :
-                    placementPreferences.tooltip;
-    // Use positioning engine to find best position
+    const preferences = preferenceChain(placement);
     const position = findBestPosition({
         targetEl: anchor,
         floatingEl: popover,
         preferences,
         offset,
     });
-    // Apply position directly to popover
     popover.style.left = `${position.x}px`;
     popover.style.top = `${position.y}px`;
 }
-/**
- * Cleanup auto-update system
- */
 function cleanupAutoUpdate(el) {
     const cleanup = autoUpdateCleanup.get(el);
     if (cleanup) {
@@ -249,10 +151,6 @@ function cleanupAutoUpdate(el) {
         autoUpdateCleanup.delete(el);
     }
 }
-/**
- * Setup auto-update system for position tracking
- * Note: This does NOT calculate initial position - call updatePosition() separately
- */
 function setupAutoUpdate(el) {
     const anchor = getAnchorElement(el);
     const popover = popoverElements.get(el);
@@ -260,7 +158,6 @@ function setupAutoUpdate(el) {
         console.warn('[ty-tooltip] setupAutoUpdate: missing anchor or popover');
         return;
     }
-    // Debounced update function
     let timeoutId = null;
     const debouncedUpdate = () => {
         if (timeoutId !== null) {
@@ -271,11 +168,9 @@ function setupAutoUpdate(el) {
             updatePosition(el);
         }, 10);
     };
-    // Setup ResizeObserver for anchor and popover
     const resizeObserver = new ResizeObserver(debouncedUpdate);
     resizeObserver.observe(anchor);
     resizeObserver.observe(popover);
-    // Scroll handler with requestAnimationFrame
     let scrollRafId = null;
     const handleScroll = () => {
         if (scrollRafId === null) {
@@ -285,10 +180,8 @@ function setupAutoUpdate(el) {
             });
         }
     };
-    // Listen for scroll and resize
     window.addEventListener('scroll', handleScroll, true);
     window.addEventListener('resize', debouncedUpdate);
-    // Store cleanup function
     const cleanup = () => {
         resizeObserver.disconnect();
         window.removeEventListener('scroll', handleScroll, true);
@@ -302,9 +195,6 @@ function setupAutoUpdate(el) {
     };
     autoUpdateCleanup.set(el, cleanup);
 }
-/**
- * Clear all timeouts
- */
 function clearTimeouts(el) {
     const state = getTimeoutState(el);
     if (state.showTimeout !== null) {
@@ -316,20 +206,14 @@ function clearTimeouts(el) {
         state.hideTimeout = null;
     }
 }
-/**
- * Show tooltip immediately using Popover API
- */
 function showTooltip(el) {
     const { disabled } = getTooltipAttributes(el);
     if (disabled)
         return;
-    // Create popover if it doesn't exist
     const popover = getOrCreatePopover(el);
     try {
-        // Show using Popover API
         popover.showPopover();
         el._open = true;
-        // Position and setup observers
         updatePosition(el);
         setupAutoUpdate(el);
     }
@@ -337,9 +221,6 @@ function showTooltip(el) {
         console.warn('[ty-tooltip] Failed to show popover', e);
     }
 }
-/**
- * Hide tooltip immediately using Popover API
- */
 function hideTooltip(el) {
     const popover = popoverElements.get(el);
     if (!popover)
@@ -350,29 +231,19 @@ function hideTooltip(el) {
         cleanupAutoUpdate(el);
     }
     catch (e) {
-        // Already hidden, ignore
     }
 }
-/**
- * Schedule tooltip to show after delay
- */
 function scheduleShow(el) {
     const state = getTimeoutState(el);
     const { delay } = getTooltipAttributes(el);
     clearTimeouts(el);
     state.showTimeout = window.setTimeout(() => showTooltip(el), delay);
 }
-/**
- * Schedule tooltip to hide after delay
- */
 function scheduleHide(el) {
     const state = getTimeoutState(el);
     clearTimeouts(el);
     state.hideTimeout = window.setTimeout(() => hideTooltip(el), 200);
 }
-/**
- * Setup event listeners on anchor element
- */
 function setupEvents(el) {
     const anchor = getAnchorElement(el);
     if (!anchor)
@@ -382,12 +253,10 @@ function setupEvents(el) {
     const handleLeave = () => scheduleHide(el);
     const handleFocus = () => scheduleShow(el);
     const handleBlur = () => scheduleHide(el);
-    // Add event listeners
     anchor.addEventListener('mouseenter', handleEnter);
     anchor.addEventListener('mouseleave', handleLeave);
     anchor.addEventListener('focusin', handleFocus);
     anchor.addEventListener('focusout', handleBlur);
-    // Store cleanup function
     eventCleanup.set(el, () => {
         anchor.removeEventListener('mouseenter', handleEnter);
         anchor.removeEventListener('mouseleave', handleLeave);
@@ -395,9 +264,6 @@ function setupEvents(el) {
         anchor.removeEventListener('focusout', handleBlur);
     });
 }
-/**
- * Cleanup all resources including popover element
- */
 function cleanup(el) {
     clearTimeouts(el);
     cleanupAutoUpdate(el);
@@ -406,9 +272,6 @@ function cleanup(el) {
         eventsCleanup();
         eventCleanup.delete(el);
     }
-    // Strip aria-describedby before removing the popover it points at — by
-    // this point (disconnectedCallback) el.parentElement is already null, so
-    // this must use the cached anchor, not getAnchorElement(el).
     const popover = popoverElements.get(el);
     const anchor = anchorElements.get(el);
     if (popover && anchor) {
@@ -421,43 +284,25 @@ function cleanup(el) {
     anchorElements.delete(el);
     timeoutState.delete(el);
 }
-// ============================================================================
-// Component Definition
-// ============================================================================
-/**
- * TyTooltip Web Component
- */
 export class TyTooltip extends HTMLElement {
-    /** Observed attributes */
     static get observedAttributes() {
         return ['placement', 'offset', 'delay', 'disabled', 'flavor'];
     }
     constructor() {
         super();
-        /** Internal open state */
         this._open = false;
         this.attachShadow({ mode: 'open' });
     }
     connectedCallback() {
-        // Initialize open state
         this._open = false;
-        // Inject styles (for :host display: contents)
         ensureStyles(this.shadowRoot, tooltipStyles);
-        // Setup events on anchor
         setupEvents(this);
-        // Eagerly create the (hidden) popover so role="tooltip" + the anchor's
-        // aria-describedby exist from connect, not only after the first show —
-        // a keyboard user tabbing to the trigger must not wait out the hover
-        // delay just to get an accessible description.
         getOrCreatePopover(this);
     }
     disconnectedCallback() {
         cleanup(this);
     }
     attributeChangedCallback(name, _oldValue, newValue) {
-        // Restyle the popover on flavor change even while hidden — it's cached
-        // in popoverElements once created, so a change made while closed would
-        // otherwise be silently lost until the element is torn down.
         if (name === 'flavor') {
             const popover = popoverElements.get(this);
             if (popover) {
@@ -465,14 +310,11 @@ export class TyTooltip extends HTMLElement {
                 applyFlavorStyles(popover, flavor);
             }
         }
-        // Close tooltip if disabled
         if (name === 'disabled' && newValue !== null) {
             hideTooltip(this);
         }
     }
 }
-// Register the custom element
 if (!customElements.get('ty-tooltip')) {
     customElements.define('ty-tooltip', TyTooltip);
 }
-//# sourceMappingURL=tooltip.js.map

package/lib/components/wizard.d.ts

@@ -1,56 +1,8 @@
 /**
- * Wizard Component
- *
- * A carousel-based wizard/stepper component with smooth animations, progress tracking, and completion state.
- * Features horizontal sliding transitions between steps, animated progress line, and step completion tracking.
- * Behaves like tabs - a "dumb" component that only renders and fires events. All navigation and validation
- * is controlled by the user.
- *
- * Features:
- * - Carousel animation with smooth sliding transitions between steps
- * - Fixed dimensions prevent layout shift between steps
- * - Animated progress line showing completion status
- * - Step indicators with completed/active/pending states
- * - Rich indicator support via slots (icons, custom content)
- * - Independent panel scrolling with scroll position reset
- * - ResizeObserver for responsive percentage widths
- * - Smart rendering - only updates DOM when necessary
- * - Accessibility with ARIA roles and attributes
- * - Fires events on step clicks - user controls navigation
- *
- * @example
- * <!-- Basic wizard with text labels -->
- * <ty-wizard width="900px" height="600px" active="welcome">
- *   <ty-step id="welcome" label="Welcome">
- *     <div class="p-6">
- *       <h1>Welcome!</h1>
- *       <button onclick="goToStep('account')">Next</button>
- *     </div>
- *   </ty-step>
- *   <ty-step id="account" label="Account Setup">
- *     <div class="p-6">
- *       <h2>Account Setup</h2>
- *       <button onclick="goToStep('welcome')">Previous</button>
- *       <button onclick="goToStep('complete')">Next</button>
- *     </div>
- *   </ty-step>
- * </ty-wizard>
- *
- * @example
- * <!-- Wizard with custom indicators -->
- * <ty-wizard width="100%" height="700px" active="welcome" completed="welcome,account">
- *   <!-- Custom indicator icons -->
- *   <div slot="indicator-welcome">
- *     <ty-icon name="hand" size="sm"></ty-icon>
- *   </div>
- *   <div slot="indicator-account">
- *     <span class="text-lg font-bold">1</span>
- *   </div>
- *
- *   <ty-step id="welcome" label="Welcome">...</ty-step>
- *   <ty-step id="account" label="Account">...</ty-step>
- *   <ty-step id="profile" label="Profile">...</ty-step>
- * </ty-wizard>
+ * Wizard Component — carousel-based stepper with sliding transitions, an
+ * animated progress line, and step completion tracking. Expects `ty-step`
+ * children. "Dumb" like ty-tabs: it renders and fires events; all navigation
+ * and validation is the consumer's.
  */
 /**
  * Wizard container attributes configuration
@@ -76,11 +28,9 @@ export interface WizardStepChangeDetail {
  * TyWizard Web Component
  */
 export declare class TyWizard extends HTMLElement {
-    /** Observed attributes */
     static get observedAttributes(): string[];
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
 }
-//# sourceMappingURL=wizard.d.ts.map