tyrell-components 1.0.0-TC44 → 1.0.0-TC46

package/lib/components/resize-observer.js

@@ -1,25 +1,3 @@
-/**
- * TyResizeObserver Web Component
- *
- * Self-observing resize component that tracks its own dimensions
- * and stores them in a global registry accessible by element ID.
- *
- * @example
- * ```html
- * <ty-resize-observer id="parent-container">
- *   <div class="child">
- *     <!-- Child can query parent size via getSize('parent-container') -->
- *   </div>
- * </ty-resize-observer>
- * ```
- *
- * @example With debouncing
- * ```html
- * <ty-resize-observer id="container" debounce="100">
- *   <!-- Only updates after 100ms of no resize activity -->
- * </ty-resize-observer>
- * ```
- */
 import { ensureStyles } from '../utils/styles.js';
 import { resizeObserverStyles } from '../styles/resize-observer.js';
 import { updateSize, removeSize } from '../utils/resize-observer.js';
@@ -27,9 +5,6 @@ export class TyResizeObserver extends HTMLElement {
     static get observedAttributes() {
         return ['id', 'debounce'];
     }
-    /**
-     * Debounce in milliseconds (default: 0 = no debounce)
-     */
     get debounce() {
         return parseInt(this.getAttribute('debounce') || '0');
     }
@@ -40,10 +15,8 @@ export class TyResizeObserver extends HTMLElement {
         super();
         this._resizeObserver = null;
         this._debounceTimer = null;
-        // Setup shadow DOM with styles
         const shadow = this.attachShadow({ mode: 'open' });
         ensureStyles(shadow, { css: resizeObserverStyles, id: 'ty-resize-observer' });
-        // Simple slot for content
         shadow.innerHTML = '<slot></slot>';
     }
     connectedCallback() {
@@ -52,13 +25,9 @@ export class TyResizeObserver extends HTMLElement {
     disconnectedCallback() {
         this.cleanup();
     }
-    /**
-     * Setup ResizeObserver to watch this element
-     */
     setupObserver() {
         this._resizeObserver = new ResizeObserver((entries) => {
             if (this.debounce > 0) {
-                // Debounced handling
                 if (this._debounceTimer)
                     clearTimeout(this._debounceTimer);
                 this._debounceTimer = window.setTimeout(() => {
@@ -66,43 +35,29 @@ export class TyResizeObserver extends HTMLElement {
                 }, this.debounce);
             }
             else {
-                // Immediate handling
                 this.handleResize(entries);
             }
         });
-        // Observe the custom element itself (not shadow root)
         this._resizeObserver.observe(this);
     }
-    /**
-     * Handle resize events - update registry and notify callbacks
-     */
     handleResize(entries) {
         const { width, height } = entries[0].contentRect;
-        // Only update if element has an ID
         if (this.id) {
             updateSize(this.id, width, height);
         }
     }
-    /**
-     * Cleanup observer and remove from registry
-     */
     cleanup() {
-        // Disconnect observer
         if (this._resizeObserver) {
             this._resizeObserver.disconnect();
             this._resizeObserver = null;
         }
-        // Clear pending debounce timer
         if (this._debounceTimer) {
             clearTimeout(this._debounceTimer);
             this._debounceTimer = null;
         }
-        // Remove from registry
         if (this.id) {
             removeSize(this.id);
         }
     }
 }
-// Register custom element
 customElements.define('ty-resize-observer', TyResizeObserver);
-//# sourceMappingURL=resize-observer.js.map

package/lib/components/scroll-container.d.ts

@@ -1,15 +1,6 @@
 /**
- * TyScrollContainer Web Component
- *
- * A scroll container with shadow indicators and an optional custom-rendered scrollbar.
- * Uses the CustomScrollbar utility internally.
- *
- * @example Custom scrollbar
- * ```html
- * <ty-scroll-container max-height="300px" custom-scrollbar>
- *   <div>Long content...</div>
- * </ty-scroll-container>
- * ```
+ * TyScrollContainer Web Component - scroll wrapper with edge shadow indicators
+ * and an optional custom-rendered scrollbar (CustomScrollbar utility).
  */
 export declare class TyScrollContainer extends HTMLElement {
     private _scrollWrapper;
@@ -64,4 +55,3 @@ export declare class TyScrollContainer extends HTMLElement {
     scrollToElement(target: Element | string, smooth?: boolean): void;
     get scrollElement(): HTMLElement | null;
 }
-//# sourceMappingURL=scroll-container.d.ts.map

package/lib/components/scroll-container.js

@@ -1,16 +1,3 @@
-/**
- * TyScrollContainer Web Component
- *
- * A scroll container with shadow indicators and an optional custom-rendered scrollbar.
- * Uses the CustomScrollbar utility internally.
- *
- * @example Custom scrollbar
- * ```html
- * <ty-scroll-container max-height="300px" custom-scrollbar>
- *   <div>Long content...</div>
- * </ty-scroll-container>
- * ```
- */
 import { ensureStyles } from '../utils/styles.js';
 import { scrollContainerStyles } from '../styles/scroll-container.js';
 import { CustomScrollbar } from '../utils/custom-scrollbar.js';
@@ -18,7 +5,6 @@ export class TyScrollContainer extends HTMLElement {
     static get observedAttributes() {
         return ['shadow', 'max-height', 'hide-scrollbar', 'custom-scrollbar', 'overflow-x', 'scroll-anchoring'];
     }
-    // ============ Property Accessors ============
     get shadow() {
         return this.getAttribute('shadow') !== 'false';
     }
@@ -65,7 +51,6 @@ export class TyScrollContainer extends HTMLElement {
         else
             this.removeAttribute('overflow-x');
     }
-    /** Distance (px) from an edge at which nearstart/nearend fire. Default 100. */
     get nearEdgeThreshold() {
         const v = parseInt(this.getAttribute('near-edge-threshold') || '', 10);
         return Number.isFinite(v) ? v : 100;
@@ -76,8 +61,6 @@ export class TyScrollContainer extends HTMLElement {
         else
             this.setAttribute('near-edge-threshold', String(value));
     }
-    /** Preserve visual position when content is added above the viewport
-     *  (e.g. prepending older messages in a chat). Opt-in. */
     get scrollAnchoring() {
         return this.hasAttribute('scroll-anchoring');
     }
@@ -98,10 +81,8 @@ export class TyScrollContainer extends HTMLElement {
         this._resizeObserver = null;
         this._contentObserver = null;
         this._rafId = null;
-        // Edge-trigger state for nearstart/nearend (fire once on entering the zone).
         this._nearStartFired = false;
         this._nearEndFired = false;
-        // ============ Private: Scroll Handling ============
         this._onScroll = () => {
             if (this._rafId !== null)
                 return;
@@ -182,12 +163,6 @@ export class TyScrollContainer extends HTMLElement {
             this._setupAnchoring();
         }
     }
-    // ============ Private: Scroll Anchoring ============
-    // Preserve visual position when content is added ABOVE the viewport (chat
-    // "load older" prepends). A MutationObserver watches the host's children;
-    // any added node sitting above the visible area shifts everything down, so we
-    // add its (above-the-fold) height back to scrollTop. Append-at-bottom is
-    // untouched. CSS sets overflow-anchor:none so native anchoring doesn't fight us.
     _setupAnchoring() {
         if (this._contentObserver || !this.scrollAnchoring)
             return;
@@ -203,9 +178,9 @@ export class TyScrollContainer extends HTMLElement {
                         return;
                     const rect = n.getBoundingClientRect();
                     if (rect.bottom <= wrapTop)
-                        addedAbove += rect.height; // fully above
+                        addedAbove += rect.height;
                     else if (rect.top < wrapTop)
-                        addedAbove += wrapTop - rect.top; // partly above
+                        addedAbove += wrapTop - rect.top;
                 });
             }
             if (addedAbove > 0) {
@@ -219,11 +194,7 @@ export class TyScrollContainer extends HTMLElement {
         this._contentObserver?.disconnect();
         this._contentObserver = null;
     }
-    // ============ Private: Scrollbar Setup ============
     _setupScrollbar() {
-        // Idempotent: attributeChangedCallback (attrs set before insertion) and
-        // connectedCallback can both call this. Without the guard a second
-        // CustomScrollbar + track is created → two thumbs.
         if (this._scrollbar)
             return;
         if (!this._scrollWrapper || !this.customScrollbar)
@@ -232,7 +203,6 @@ export class TyScrollContainer extends HTMLElement {
             vertical: true,
             horizontal: this.overflowX
         });
-        // Append track elements to shadow DOM
         const shadowRoot = this.shadowRoot;
         if (this._scrollbar.trackY)
             shadowRoot.appendChild(this._scrollbar.trackY);
@@ -241,14 +211,12 @@ export class TyScrollContainer extends HTMLElement {
     }
     _destroyScrollbar() {
         if (this._scrollbar) {
-            // Remove track elements from DOM
             this._scrollbar.trackY?.remove();
             this._scrollbar.trackX?.remove();
             this._scrollbar.destroy();
             this._scrollbar = null;
         }
     }
-    // ============ Private: Max Height ============
     _updateMaxHeight() {
         if (this._scrollWrapper) {
             const maxHeight = this.maxHeight;
@@ -262,7 +230,6 @@ export class TyScrollContainer extends HTMLElement {
             }
         }
     }
-    // ============ Private: Shadow State ============
     _updateShadowState() {
         if (!this._scrollWrapper)
             return;
@@ -282,10 +249,6 @@ export class TyScrollContainer extends HTMLElement {
                 this._shadowRight.classList.toggle('visible', scrollLeft + clientWidth < scrollWidth - threshold);
             }
         }
-        // Near-edge events for infinite scroll (vertical). Edge-triggered: fire once
-        // when entering the zone, re-arm only after leaving it. Runs on scroll,
-        // slotchange and resize (all route through here), so loading more content
-        // re-arms naturally once it grows the scroll distance.
         const scrollable = scrollHeight - clientHeight;
         if (scrollable > 0) {
             const t = this.nearEdgeThreshold;
@@ -294,21 +257,18 @@ export class TyScrollContainer extends HTMLElement {
             this._nearStartFired = this._maybeEmitEdge('nearstart', scrollTop, t, this._nearStartFired, { distance: scrollTop, scrollTop, scrollHeight, clientHeight });
         }
         else {
-            // Not scrollable → re-arm both so they fire fresh once content overflows.
             this._nearStartFired = false;
             this._nearEndFired = false;
         }
     }
-    /** Edge-trigger one near-edge event; returns the new "fired" state. */
     _maybeEmitEdge(name, distance, threshold, fired, detail) {
         if (distance > threshold)
-            return false; // out of zone → re-arm
+            return false;
         if (!fired) {
             this.dispatchEvent(new CustomEvent(name, { detail, bubbles: true, composed: true }));
         }
         return true;
     }
-    // ============ Public API ============
     updateShadows() {
         this._updateShadowState();
         this._scrollbar?.update();
@@ -329,7 +289,6 @@ export class TyScrollContainer extends HTMLElement {
             this._scrollWrapper.scrollTo({ left: this._scrollWrapper.scrollWidth, behavior: smooth ? 'smooth' : 'auto' });
         }
     }
-    /** Scroll a slotted descendant (element or CSS selector) into view. */
     scrollToElement(target, smooth = true) {
         const el = typeof target === 'string' ? this.querySelector(target) : target;
         el?.scrollIntoView({ behavior: smooth ? 'smooth' : 'auto', block: 'nearest' });
@@ -338,6 +297,4 @@ export class TyScrollContainer extends HTMLElement {
         return this._scrollWrapper;
     }
 }
-// Register custom element
 customElements.define('ty-scroll-container', TyScrollContainer);
-//# sourceMappingURL=scroll-container.js.map

package/lib/components/select.d.ts

@@ -1,57 +1,17 @@
 /**
- * TySelect Web Component
- *
- * The select control — replaces ty-dropdown and ty-multiselect.
- *
- * Cardinality (native <select> semantics):
- * - default: SINGLE select — scalar value, picking an option closes the popup
- * - `multiple`: multi select — comma value / repeated FormData entries,
- *   options toggle and the popup stays open
- *
- * Skins:
- * - default: form FIELD — full width, --ty-input-* tokens, matches ty-input;
- *   shows the selected label(s) inline
- * - `compact`: content-hugging trigger for toolbars/filter bars; single shows
- *   the selected label, multiple shows placeholder + count badge (pair with
- *   <ty-selected-options>)
- * - slot="trigger": consumer skin — replaces field/compact chrome entirely,
- *   behavior/ARIA/form participation unchanged
- *
- * - ty-option children (ty-tag also accepted)
- * - Desktop popup with smart positioning, mobile full-screen modal
- * - Search / external-search / debounce, keyboard navigation
- * - Form association: single submits one entry, multiple submits repeated
- *   `name=` entries (HTMX-ready)
- * - change event detail: { value, values, items: [{value, label, flavor}], action, item }
- *   (`value` is a scalar for single, array for multiple)
- *
- * @example
- * ```html
- * <!-- Single select, field skin -->
- * <ty-select label="Robot" name="robot">
- *   <ty-option value="bobo">Bobo Robot</ty-option>
- *   <ty-option value="eywa">EYWA Dataset Example</ty-option>
- * </ty-select>
- *
- * <!-- Multi select, compact skin + out-of-band chips -->
- * <ty-select multiple compact label="Robots" name="robots" id="robots">...</ty-select>
- * <ty-selected-options for="robots"></ty-selected-options>
- * ```
+ * TySelect Web Component — THE select control (replaces ty-dropdown/ty-multiselect).
+ * Cardinality follows native <select>: default single (scalar value, picking closes
+ * the popup), `multiple` toggles options and submits repeated `name=` FormData entries.
+ * Skins: default form field, `compact` content-hugging trigger, slot="trigger" custom.
  */
 import type { Flavor, Size } from "../types/common.js";
 import { TyComponent } from "../base/ty-component.js";
 import type { PropertyChange } from "../utils/property-manager.js";
-/**
- * Tag data structure
- */
 interface TagData {
     value: string;
     text: string;
     element: HTMLElement;
 }
-/**
- * Component state structure
- */
 interface SelectState {
     open: boolean;
     search: string;
@@ -112,6 +72,14 @@ export declare class TySelect extends TyComponent<SelectState> {
             visual: boolean;
             default: boolean;
         };
+        clearable: {
+            type: "boolean";
+            visual: boolean;
+            default: boolean;
+            aliases: {
+                "not-clearable": boolean;
+            };
+        };
         externalSearch: {
             type: "boolean";
             visual: boolean;
@@ -143,6 +111,13 @@ export declare class TySelect extends TyComponent<SelectState> {
             default: string;
             coerce: (v: any) => "auto" | "always" | "never";
         };
+        align: {
+            type: "string";
+            visual: boolean;
+            default: string;
+            validate: (v: any) => boolean;
+            coerce: (v: any) => "start" | "end";
+        };
         size: {
             type: "string";
             visual: boolean;
@@ -185,6 +160,7 @@ export declare class TySelect extends TyComponent<SelectState> {
     private _disabled;
     private _readonly;
     private _required;
+    private _clearable;
     private _externalSearch;
     private _allowCreate;
     private _createTransform;
@@ -207,22 +183,12 @@ export declare class TySelect extends TyComponent<SelectState> {
     private _selectedClone;
     private _customFlavorSheet;
     constructor();
-    /**
-     * Called when component is connected to DOM
-     * TyComponent handles property capture automatically
-     */
+    /** TyComponent handles property capture automatically. */
     protected onConnect(): void;
     /** Custom (non-built-in) flavors — see utils/flavor-sheet.ts. */
     private _syncCustomFlavor;
-    /**
-     * Called when component is disconnected from DOM
-     * Clean up event listeners and timers
-     */
     protected onDisconnect(): void;
-    /**
-     * Called when properties change
-     * Handle state synchronization BEFORE render
-     */
+    /** Handle state synchronization BEFORE render. */
     protected onPropertiesChanged(changes: PropertyChange[]): void;
     /**
      * Toggle the loading visual state on the open popup.
@@ -231,27 +197,15 @@ export declare class TySelect extends TyComponent<SelectState> {
      * take effect on the next loading toggle.
      */
     private applyLoadingState;
-    /**
-     * Get the form value for this component
-     * Returns FormData with multiple entries (HTMX standard)
-     */
+    /** Form value: a plain entry for single, FormData with repeated entries for multiple (HTMX standard). */
     protected getFormValue(): FormDataEntryValue | FormData | null;
-    /**
-     * Parse select value (comma-separated string to array)
-     */
     private parseValue;
-    /**
-     * Initialize component state from attributes
-     * Reads from both property and attribute (like ClojureScript version)
-     */
+    /** Initialize component state from the value property / pre-selected children. */
     private initializeState;
     /**
      * Get all option elements from the component (ty-option preferred, ty-tag accepted)
      */
     private getTagElements;
-    /**
-     * Extract value and text from a ty-tag element
-     */
     private getTagData;
     /**
      * Select an option - attribute only. The option stays in the list with
@@ -266,9 +220,6 @@ export declare class TySelect extends TyComponent<SelectState> {
      * Get array of currently selected values from tags (ALWAYS reads from DOM)
      */
     private getSelectedValues;
-    /**
-     * Sync tag selection states with desired values
-     */
     private syncSelectedTags;
     /**
      * role="option" for every current option/tag — separate from
@@ -278,18 +229,12 @@ export declare class TySelect extends TyComponent<SelectState> {
      * on every light-DOM change.
      */
     private ensureOptionRoles;
-    /**
-     * Central update function - synchronizes everything
-     * Uses TyComponent's property system for proper lifecycle
-     */
+    /** Central update function — synchronizes everything via TyComponent's property system. */
     private updateComponentValue;
     /**
      * Build rich item info for values, read off the matching option elements
      */
     private getSelectedItems;
-    /**
-     * Calculate and set dropdown position with smart direction detection
-     */
     private calculatePosition;
     private _setupOptionsScrollbar;
     private _destroyOptionsScrollbar;
@@ -303,21 +248,16 @@ export declare class TySelect extends TyComponent<SelectState> {
      * implement.
      */
     private openDropdown;
-    /**
-     * Close dropdown dialog (desktop mode)
-     */
     private closeDropdown;
-    /**
-     * Open mobile modal (mobile mode)
-     * Now using <dialog> element for native z-index management
-     */
+    /** Open mobile modal — <dialog> handles z-index natively. */
     private openMobileModal;
-    /**
-     * Close mobile modal (mobile mode)
-     * Now using <dialog> element for native management
-     */
     private closeMobileModal;
     private handleStubClick;
+    /**
+     * .select-clear click — must stop propagation before it bubbles to the
+     * stub's own click handler (which would otherwise also open the dropdown).
+     */
+    private handleClearClick;
     /**
      * Keyboard-open the (closed) stub. The stub is a plain div with
      * tabindex="0", not a native <button> — Enter/Space don't turn into
@@ -353,34 +293,13 @@ export declare class TySelect extends TyComponent<SelectState> {
     private blockSearchClick;
     private handleSearchInput;
     private handleKeyboard;
-    /**
-     * Filter tags based on search query
-     */
     private filterTags;
-    /**
-     * Update visibility of tags based on filtered list
-     */
     private updateTagVisibility;
-    /**
-     * Show/hide the dropdown options area
-     */
     private updateOptionsVisibility;
-    /**
-     * Clear all tag highlights
-     */
     private clearHighlights;
-    /**
-     * Highlight tag at specific index
-     */
     private highlightTag;
-    /**
-     * Dispatch search event for external search handling
-     * With optional debounce support
-     */
+    /** Dispatch the search event for external search handling, with optional debounce. */
     private dispatchSearchEvent;
-    /**
-     * Fire the actual search event
-     */
     private fireSearchEvent;
     /**
      * Dispatch lifecycle events for popup open/close.
@@ -389,14 +308,7 @@ export declare class TySelect extends TyComponent<SelectState> {
      */
     private fireOpenEvent;
     private fireCloseEvent;
-    /**
-     * Dispatch custom change event
-     */
     private dispatchChangeEvent;
-    /**
-     * Main render method (required by TyComponent)
-     * Delegates to mode-specific renderer
-     */
     protected render(): void;
     /**
      * Reflect constraint validation to the owning <form> via ElementInternals.
@@ -411,45 +323,16 @@ export declare class TySelect extends TyComponent<SelectState> {
      * default field chrome so the trigger is styled entirely by the consumer.
      */
     private setupTriggerSlot;
-    /**
-     * Setup event listeners
-     */
     private setupEventListeners;
-    /**
-     * Build CSS class list for stub
-     */
     private buildStubClasses;
-    /**
-     * Render desktop mode with dialog
-     */
     private renderDesktop;
-    /**
-     * Render mobile mode with full-screen modal
-     * Following dropdown.ts mobile structure
-     */
     private renderMobile;
-    /**
-     * Setup event listeners for mobile mode
-     * Using <dialog> element - backdrop clicks handled natively
-     */
     private setupMobileEventListeners;
-    /**
-     * Handle mobile stub click - open modal
-     */
     private handleMobileStubClick;
     /** Keyboard-open the (closed) mobile stub — see handleStubKeydown for why this is needed. */
     private handleMobileStubKeydown;
-    /**
-     * Handle mobile tag click - select and potentially close
-     */
     private handleMobileTagClick;
-    /**
-     * Update mobile options section state (count, empty state)
-     */
     private updateMobileSelectedState;
-    /**
-     * Update selection display: count badge next to the placeholder
-     */
     /**
      * Should the popup show a search row? external-search always (the input is
      * the mechanism); searchable always/never wins otherwise; 'auto' shows it
@@ -482,6 +365,13 @@ export declare class TySelect extends TyComponent<SelectState> {
      * fires change like any in-popup interaction (HTMX hx-trigger="change" etc.).
      */
     deselectValue(value: string): void;
+    /**
+     * Clear the entire selection programmatically WITH a change event
+     * (action: 'clear'). No-op if nothing is selected. Exists so slot="trigger"
+     * consumers (custom chrome, built-in clear UI hidden by design) can wire
+     * their own clear icon's click handler to it.
+     */
+    clear(): void;
     get value(): string;
     set value(val: string);
     get name(): string;
@@ -500,6 +390,8 @@ export declare class TySelect extends TyComponent<SelectState> {
     set loading(value: boolean);
     get readonly(): boolean;
     set readonly(value: boolean);
+    get clearable(): boolean;
+    set clearable(value: boolean);
     get required(): boolean;
     set required(value: boolean);
     get searchable(): "auto" | "always" | "never";
@@ -510,9 +402,10 @@ export declare class TySelect extends TyComponent<SelectState> {
     set debounce(value: number | string);
     get size(): Size;
     set size(value: Size);
+    get align(): "start" | "end";
+    set align(value: "start" | "end");
     get flavor(): Flavor;
     set flavor(value: Flavor);
     get form(): HTMLFormElement | null;
 }
 export {};
-//# sourceMappingURL=select.d.ts.map