tyrell-components 1.0.0-TC44 → 1.0.0-TC46

package/lib/components/select.js

@@ -1,43 +1,3 @@
-/**
- * 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>
- * ```
- */
 import { ensureStyles } from "../utils/styles.js";
 import { syncCustomFlavorSheet } from "../utils/flavor-sheet.js";
 import { selectBaseStyles, selectCustomFlavorCss } from "../styles/select-base.js";
@@ -48,25 +8,8 @@ import { computeAnchoredPosition } from "../utils/positioning.js";
 import { isMobileTouch } from "../utils/mobile.js";
 import { TyComponent } from "../base/ty-component.js";
 import { CustomScrollbar, isCustomScrollbarEnabled, } from "../utils/custom-scrollbar.js";
-// ============================================================================
-// Element Hash Utility (for consistent scroll lock IDs)
-// ============================================================================
-/**
- * Counter for generating unique element IDs
- */
 let elementIdCounter = 0;
-/**
- * WeakMap to store consistent element hashes
- * Automatically garbage collects when element is destroyed
- */
 const elementIds = new WeakMap();
-/**
- * Get a consistent unique ID for an element
- * Returns the same ID for the same element across multiple calls
- *
- * @param element - The element to hash
- * @returns A consistent numeric hash for the element
- */
 function getElementHash(element) {
     let id = elementIds.get(element);
     if (id === undefined) {
@@ -75,25 +18,11 @@ function getElementHash(element) {
     }
     return id;
 }
-// ============================================================================
-// SVG Icons
-// ============================================================================
 import { REQUIRED_ICON_SVG } from "../utils/icons.js";
-/**
- * Chevron down icon SVG
- */
 const CHEVRON_DOWN_SVG = `<svg viewBox="0 0 20 20" fill="currentColor">
   <path fill-rule="evenodd" d="M5.293 7.293a1 1 0 011.414 0L10 10.586l3.293-3.293a1 1 0 111.414 1.414l-4 4a1 1 0 01-1.414 0l-4-4a1 1 0 010-1.414z" clip-rule="evenodd" />
 </svg>`;
-/**
- * 'auto' searchable mode: option count above which the search row appears.
- * Short lists scan faster than they search — native <select> has no search.
- */
 const SEARCH_AUTO_THRESHOLD = 7;
-/**
- * create-transform="slug": lowercase, spaces → '_', strip anything else
- * non-alphanumeric, collapse/trim stray underscores.
- */
 function slugify(text) {
     return text
         .trim()
@@ -103,21 +32,16 @@ function slugify(text) {
         .replace(/_+/g, "_")
         .replace(/^_|_$/g, "");
 }
-/**
- * Search (magnifier) icon SVG — popup search input adornment (from Lucide)
- */
 const SEARCH_ICON_SVG = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
   <circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/>
 </svg>`;
-/**
- * Ty Select Component
- */
+const CLEAR_ICON_SVG = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+  <line x1="18" y1="6" x2="6" y2="18"></line>
+  <line x1="6" y1="6" x2="18" y2="18"></line>
+</svg>`;
 export class TySelect extends TyComponent {
     constructor() {
-        super(); // TyComponent handles attachInternals() and attachShadow()
-        // ============================================================================
-        // INTERNAL STATE
-        // ============================================================================
+        super();
         this._name = "";
         this._multiple = false;
         this._compact = false;
@@ -126,6 +50,7 @@ export class TySelect extends TyComponent {
         this._disabled = false;
         this._readonly = false;
         this._required = false;
+        this._clearable = true;
         this._externalSearch = false;
         this._allowCreate = false;
         this._createTransform = "none";
@@ -135,45 +60,30 @@ export class TySelect extends TyComponent {
         this._size = "md";
         this._availableLabel = "Available";
         this._noOptionsMessage = "No options available";
-        // Component state
         this._state = {
             open: false,
             search: "",
             highlightedIndex: -1,
             filteredTags: [],
             selectedValues: [],
-            mode: "desktop", // Updated dynamically on render via syncMode()
+            mode: "desktop",
         };
-        // Event handler references for cleanup
         this._stubClickHandler = null;
         this._tagClickHandler = null;
         this._searchInputHandler = null;
         this._blockSearchClick = null;
         this._keyboardHandler = null;
-        // Debounce properties for search event
         this._debounce = 0;
         this._searchDebounceTimer = null;
-        // Custom scrollbar for options list
         this._optionsScrollbar = null;
-        // MutationObserver for light-DOM children — re-syncs selected tags' visual
-        // state when consumers swap tag children (external-search refresh pattern).
         this._childObserver = null;
-        // Last single-select display clone — survives external-search option swaps
-        // that remove the matching option (and often the clone itself) from the DOM.
         this._selectedClone = null;
         this._customFlavorSheet = null;
         const shadow = this.shadowRoot;
         ensureStyles(shadow, { css: selectBaseStyles, id: "ty-select-base" });
         ensureStyles(shadow, { css: selectStyles, id: "ty-select" });
-        // DON'T render here - wait for onConnect() to initialize values first
-        // This matches dropdown.ts pattern and prevents showing empty state
     }
-    /**
-     * Called when component is connected to DOM
-     * TyComponent handles property capture automatically
-     */
     onConnect() {
-        // SAFETY: Close any open dialogs to prevent scroll locking
         const shadow = this.shadowRoot;
         const dialogs = shadow.querySelectorAll("dialog");
         dialogs.forEach((dialog) => {
@@ -182,54 +92,27 @@ export class TySelect extends TyComponent {
                 dialog.close();
             }
         });
-        // Render FIRST to create DOM structure
         this.render();
-        // THEN initialize and sync tags (after DOM exists)
         requestAnimationFrame(() => {
             this.initializeState();
-            // Visual updates happen automatically via onPropertiesChanged
         });
-        // Observe light-DOM children — re-sync selected state when consumers swap
-        // tag children (external-search refresh). syncSelectedTags is idempotent
-        // (only acts on tags whose desired-vs-actual selected state differs), so
-        // spurious firings caused by our own re-slot work are no-ops.
         this._childObserver = new MutationObserver(() => {
             this.ensureOptionRoles();
             if (this._state.selectedValues.length > 0) {
                 this.syncSelectedTags(this._state.selectedValues);
             }
-            // Option count may have crossed the 'auto' searchable threshold
             this.updateSearchVisibility();
-            // External-search consumers replace ALL ty-option children — often
-            // including our display clone. Rebuild the selection display (idempotent:
-            // a clone that already matches is left alone, so no observer loop).
             this.updateSelectionDisplay();
-            // Mobile's "Available (N)" count and empty-state come from
-            // updateMobileSelectedState(), which internal search filtering already
-            // triggers — but external-search bypasses internal filtering entirely
-            // (handleSearchInput returns early for it), so this was the only place
-            // left that could catch a child-list change and it didn't. Without
-            // this, .mobile-available-section[data-empty="true"] slot { display:
-            // none } stays stuck hidden after a consumer replaces the options —
-            // the new options are correctly in the DOM, just invisible.
             this.updateMobileSelectedState();
         });
         this._childObserver.observe(this, { childList: true });
-        // MutationObserver only fires on FUTURE mutations — cover the initial
-        // set of options too (the common case: none selected yet at connect).
         this.ensureOptionRoles();
         this._syncCustomFlavor();
     }
-    /** Custom (non-built-in) flavors — see utils/flavor-sheet.ts. */
     _syncCustomFlavor() {
         this._customFlavorSheet = syncCustomFlavorSheet(this.shadowRoot, this._customFlavorSheet, this.getProperty("flavor"), ({ base }) => selectCustomFlavorCss(base));
     }
-    /**
-     * Called when component is disconnected from DOM
-     * Clean up event listeners and timers
-     */
     onDisconnect() {
-        // CRITICAL: Close all dialogs to prevent scroll locking
         const shadow = this.shadowRoot;
         const dialogs = shadow.querySelectorAll("dialog");
         dialogs.forEach((dialog) => {
@@ -237,42 +120,31 @@ export class TySelect extends TyComponent {
                 dialog.close();
             }
         });
-        // Clean up document-level listeners
         if (this._keyboardHandler) {
             document.removeEventListener("keydown", this._keyboardHandler);
             this._keyboardHandler = null;
         }
-        // Clear any pending debounce timer
         if (this._searchDebounceTimer !== null) {
             clearTimeout(this._searchDebounceTimer);
             this._searchDebounceTimer = null;
         }
-        // Cleanup custom scrollbar
         this._destroyOptionsScrollbar();
-        // Disconnect children observer
         if (this._childObserver) {
             this._childObserver.disconnect();
             this._childObserver = null;
         }
     }
-    /**
-     * Called when properties change
-     * Handle state synchronization BEFORE render
-     */
     onPropertiesChanged(changes) {
         for (const { name, newValue } of changes) {
             switch (name) {
                 case "value":
                     const selectedValues = this.parseValue(newValue);
                     this._state.selectedValues = selectedValues;
-                    // CRITICAL: Only sync tags if we're connected and tags exist
-                    // During initial property setup (before onConnect), tags don't exist yet
                     if (this.isConnected && this.shadowRoot) {
                         this.syncSelectedTags(selectedValues);
                         this.updateSelectionDisplay();
                         this.updateMobileSelectedState();
                     }
-                    // (not-yet-connected: sync deferred to initializeState)
                     break;
                 case "name":
                     this._name = newValue || "";
@@ -282,7 +154,6 @@ export class TySelect extends TyComponent {
                     break;
                 case "multiple":
                     this._multiple = newValue;
-                    // Dropping to single with a multi selection: keep only the first
                     if (!newValue && this._state.selectedValues.length > 1) {
                         this.updateComponentValue([this._state.selectedValues[0]], false, "set", null);
                     }
@@ -307,6 +178,11 @@ export class TySelect extends TyComponent {
                 case "required":
                     this._required = newValue;
                     break;
+                case "clearable":
+                    this._clearable = newValue;
+                    if (this.isConnected && this.shadowRoot)
+                        this.updateSelectionDisplay();
+                    break;
                 case "externalSearch":
                     this._externalSearch = newValue;
                     break;
@@ -342,12 +218,6 @@ export class TySelect extends TyComponent {
             }
         }
     }
-    /**
-     * Toggle the loading visual state on the open popup.
-     * Replaces the available-options area with a centered spinner; search input stays usable.
-     * Pulls the latest registered loader SVG on each call so registry changes
-     * take effect on the next loading toggle.
-     */
     applyLoadingState() {
         const shadow = this.shadowRoot;
         if (!shadow)
@@ -366,17 +236,11 @@ export class TySelect extends TyComponent {
             }
         });
     }
-    /**
-     * Get the form value for this component
-     * Returns FormData with multiple entries (HTMX standard)
-     */
     getFormValue() {
         const selectedValues = this._state.selectedValues;
         if (this._name && selectedValues.length > 0) {
-            // Single select submits one plain entry
             if (!this._multiple)
                 return selectedValues[0];
-            // Multiple submits repeated `name=` entries (HTMX standard)
             const formData = new FormData();
             selectedValues.forEach((value) => {
                 formData.append(this._name, value);
@@ -385,11 +249,7 @@ export class TySelect extends TyComponent {
         }
         return null;
     }
-    /**
-     * Parse select value (comma-separated string to array)
-     */
     parseValue(value) {
-        // Defensive check: ensure value is actually a string before calling .trim()
         if (!value || typeof value !== "string" || value.trim() === "")
             return [];
         return value
@@ -397,86 +257,48 @@ export class TySelect extends TyComponent {
             .map((v) => v.trim())
             .filter((v) => v !== "");
     }
-    /**
-     * Initialize component state from attributes
-     * Reads from both property and attribute (like ClojureScript version)
-     */
     initializeState() {
         const initialValue = this.getProperty("value") || "";
         if (initialValue) {
-            // Explicit value provided - sync tags directly
-            // DON'T use updateComponentValue() because the property is already set!
             const selectedValues = this.parseValue(initialValue);
-            // Update internal state
             this._state.selectedValues = selectedValues;
-            // Sync the tags to match the property value
             this.syncSelectedTags(selectedValues);
-            // Update the visual display
             this.updateSelectionDisplay();
             this.updateMobileSelectedState();
         }
         else {
-            // No explicit value - check for pre-selected tags
             const allTags = this.getTagElements();
             const preSelectedTags = allTags
                 .filter((tag) => tag.hasAttribute("selected"))
                 .map((tag) => this.getTagData(tag).value);
             if (preSelectedTags.length > 0) {
-                // Set the property value and sync (updateComponentValue handles everything)
                 this.updateComponentValue(preSelectedTags, false);
             }
         }
     }
-    // ============================================================================
-    // TAG MANAGEMENT METHODS (Phase 2)
-    // ============================================================================
-    /**
-     * Get all option elements from the component (ty-option preferred, ty-tag accepted)
-     */
     getTagElements() {
-        // :not([cloned]) — the single-select display clone (slot="selected")
-        // lives in our light DOM too and must never count as an option
         return Array.from(this.querySelectorAll("ty-option:not([cloned]), ty-tag:not([cloned])"));
     }
-    /**
-     * Extract value and text from a ty-tag element
-     */
     getTagData(element) {
-        // Get value from either property or attribute
         const value = element.value ||
             element.getAttribute("value") ||
             element.textContent ||
             "";
-        // Display label: explicit label attribute wins over textContent —
-        // native <option label> semantics; lets rich options declare clean text
         const text = element.getAttribute("label") || element.textContent || "";
         return { value, text, element };
     }
-    /**
-     * Select an option - attribute only. The option stays in the list with
-     * selected styling; chips are rendered out-of-band (ty-selected-options).
-     */
     selectTag(tag) {
         tag.setAttribute("selected", "");
     }
-    /**
-     * Deselect an option - attribute only.
-     */
     deselectTag(tag) {
         tag.removeAttribute("selected");
     }
-    /**
-     * Get array of currently selected values from tags (ALWAYS reads from DOM)
-     */
     getSelectedValues() {
         return this.getTagElements()
             .filter((tag) => tag.hasAttribute("selected"))
             .map((tag) => this.getTagData(tag).value)
             .filter((value) => value !== "");
     }
-    /**
-     * Sync tag selection states with desired values
-     */
     syncSelectedTags(selectedValues) {
         const selectedSet = new Set(selectedValues);
         const tags = this.getTagElements();
@@ -490,18 +312,9 @@ export class TySelect extends TyComponent {
             else if (!shouldBeSelected && isSelected) {
                 this.deselectTag(tag);
             }
-            // ARIA listbox pattern: every option reports its live selected state,
-            // not just ones that changed this pass — cheap (idempotent setAttribute).
             tag.setAttribute("aria-selected", String(shouldBeSelected));
         });
     }
-    /**
-     * role="option" for every current option/tag — separate from
-     * syncSelectedTags (which only runs when the `value` property changes)
-     * so it also covers the "nothing selected yet, value never touched"
-     * startup case. Idempotent; cheap to call from the child MutationObserver
-     * on every light-DOM change.
-     */
     ensureOptionRoles() {
         this.getTagElements().forEach((tag) => {
             if (!tag.hasAttribute("role"))
@@ -510,29 +323,14 @@ export class TySelect extends TyComponent {
                 tag.setAttribute("aria-selected", "false");
         });
     }
-    /**
-     * Central update function - synchronizes everything
-     * Uses TyComponent's property system for proper lifecycle
-     */
     updateComponentValue(newValues, dispatchChange = false, action = "set", item = null) {
         const oldValues = this.getSelectedValues();
         const valueStr = newValues.join(",");
-        // Only update if changed
         if (JSON.stringify(newValues.sort()) !== JSON.stringify(oldValues.sort())) {
-            // Use TyComponent's property system - this will trigger:
-            // 1. onPropertiesChanged() → syncs tags via syncSelectedTags()
-            // 2. onPropertiesChanged() → updates placeholder via updateSelectionDisplay()
-            // 3. updateFormValue() → automatic (formValue: true in config)
-            // 4. render() → automatic if visual properties changed
             this.setProperty("value", valueStr);
-            // Explicit call, not just relying on render()'s cascade — `value` may
-            // not always be flagged as a "visual" property requiring a full
-            // re-render, and validity must update the moment selection changes.
             this.updateValidity();
-            // Dispatch change event (with rich items for out-of-band chip rendering)
             if (dispatchChange) {
                 this.dispatchChangeEvent({
-                    // Scalar for single select, array for multiple
                     value: this._multiple ? [...newValues] : (newValues[0] ?? null),
                     values: newValues,
                     items: this.getSelectedItems(newValues),
@@ -542,27 +340,17 @@ export class TySelect extends TyComponent {
             }
         }
     }
-    /**
-     * Build rich item info for values, read off the matching option elements
-     */
     getSelectedItems(values) {
         const byValue = new Map(this.getTagElements().map((el) => [this.getTagData(el).value, el]));
         return values.map((value) => {
             const el = byValue.get(value);
             return {
                 value,
-                // label attribute wins (native <option label> semantics)
                 label: el?.getAttribute("label") || el?.textContent?.trim() || value,
                 flavor: el?.getAttribute("flavor") ?? null,
             };
         });
     }
-    // ============================================================================
-    // DROPDOWN METHODS (Phase 3 & 4)
-    // ============================================================================
-    /**
-     * Calculate and set dropdown position with smart direction detection
-     */
     calculatePosition() {
         const shadow = this.shadowRoot;
         const stub = shadow.querySelector(".select-stub");
@@ -570,16 +358,10 @@ export class TySelect extends TyComponent {
         if (!stub || !dialog)
             return;
         const stubRect = stub.getBoundingClientRect();
-        // Get dialog dimensions (it's already shown with showModal).
-        // Cap the estimate: with hundreds of options the raw measurement can be
-        // the uncapped content height, which made "fits below?" always false.
-        // 440px ≈ options max-height (24rem) + search header.
         const MAX_POPUP_ESTIMATE = 440;
         const dialogRect = dialog.getBoundingClientRect();
         const estimatedHeight = Math.min(dialogRect.height || 200, MAX_POPUP_ESTIMATE);
         const wrapPadding = 20;
-        // Popup width is independent of the trigger — a small button trigger still
-        // gets a usable list. Overridable via --ty-select-popup-width.
         const cssWidth = parseFloat(getComputedStyle(this).getPropertyValue("--ty-select-popup-width"));
         const popupWidth = !isNaN(cssWidth)
             ? cssWidth
@@ -588,20 +370,18 @@ export class TySelect extends TyComponent {
             anchorRect: stubRect,
             popupWidth,
             popupHeight: estimatedHeight,
+            align: this.getProperty("align"),
         });
         const positionBelow = pos.below;
-        // Shift by the dialog's transparent wrap (room for shadows)
         const x = pos.x - wrapPadding;
         const y = (positionBelow ? pos.topY : pos.bottomY) - wrapPadding;
         const width = popupWidth + wrapPadding + wrapPadding;
-        // Set CSS variables for positioning
         this.style.setProperty("--dropdown-x", `${x}px`);
         this.style.setProperty("--dropdown-y", `${y}px`);
         this.style.setProperty("--dropdown-width", `${width}px`);
         this.style.setProperty("--dropdown-offset-x", "0px");
         this.style.setProperty("--dropdown-offset-y", "0px");
         this.style.setProperty("--dropdown-padding", `${wrapPadding}px`);
-        // Set direction classes for CSS styling
         if (positionBelow) {
             dialog.classList.add("position-below");
             dialog.classList.remove("position-above");
@@ -610,12 +390,8 @@ export class TySelect extends TyComponent {
             dialog.classList.add("position-above");
             dialog.classList.remove("position-below");
         }
-        // Optional: Store direction for debugging
         this.style.setProperty("--dropdown-direction", positionBelow ? "below" : "above");
     }
-    // ============================================================================
-    // CUSTOM SCROLLBAR FOR OPTIONS
-    // ============================================================================
     _setupOptionsScrollbar() {
         if (!isCustomScrollbarEnabled())
             return;
@@ -640,15 +416,6 @@ export class TySelect extends TyComponent {
             this._optionsScrollbar = null;
         }
     }
-    /**
-     * Open dropdown dialog (desktop mode)
-     *
-     * `<dialog>.showModal()` puts the dialog in the top layer with a backdrop, but
-     * does NOT prevent the page behind it from scrolling. We use the shared scroll
-     * lock utility (overflow:hidden on <html>) to keep wheel/touch scrolling from
-     * leaking through to the body — same behavior <ty-dropdown> and <ty-modal>
-     * implement.
-     */
     openDropdown() {
         const shadow = this.shadowRoot;
         const dialog = shadow.querySelector(".dropdown-dialog");
@@ -657,43 +424,30 @@ export class TySelect extends TyComponent {
         const stubEl = shadow.querySelector(".select-stub");
         if (stubEl)
             stubEl.setAttribute("aria-expanded", "true");
-        // Lock body scroll while dropdown is open
         const lockId = `select-${this.id || "anon"}-${getElementHash(this)}`;
         this._scrollLockId = lockId;
         lockScroll(lockId);
-        // Show modal
         dialog.showModal();
         dialog.classList.add("open");
-        // Position dropdown AFTER showing modal
         this.calculatePosition();
-        // Update component state
         this._state.open = true;
-        // Update visual states
         const chevron = shadow.querySelector(".dropdown-chevron");
         if (chevron)
             chevron.classList.add("open");
         const searchChevron = shadow.querySelector(".dropdown-search-chevron");
         if (searchChevron)
             searchChevron.classList.add("open");
-        // Initialize options state
         const tags = this.getTagElements().map((el) => this.getTagData(el));
         this._state.filteredTags = tags;
         this._state.highlightedIndex = -1;
-        // Ensure options area is visible (may have been hidden from previous search)
         this.updateOptionsVisibility(true);
-        // Setup custom scrollbar on options
         this._setupOptionsScrollbar();
-        // Focus search input (when the search row is shown)
         const searchInput = shadow.querySelector(".dropdown-search-input");
         if (searchInput && this.shouldShowSearch()) {
             setTimeout(() => searchInput.focus(), 100);
         }
-        // Lifecycle event (also fires empty search if external-search)
         this.fireOpenEvent();
     }
-    /**
-     * Close dropdown dialog (desktop mode)
-     */
     closeDropdown() {
         const shadow = this.shadowRoot;
         const dialog = shadow.querySelector(".dropdown-dialog");
@@ -702,29 +456,23 @@ export class TySelect extends TyComponent {
         const stubEl = shadow.querySelector(".select-stub");
         if (stubEl)
             stubEl.setAttribute("aria-expanded", "false");
-        // Destroy custom scrollbar
         this._destroyOptionsScrollbar();
-        // Close dialog
         dialog.classList.remove("open");
         dialog.classList.remove("position-above");
         dialog.classList.remove("position-below");
         dialog.close();
-        // Unlock body scroll (paired with the lock in openDropdown)
         if (this._scrollLockId) {
             unlockScroll(this._scrollLockId);
             this._scrollLockId = null;
         }
-        // Update state
         this._state.open = false;
         this._state.highlightedIndex = -1;
-        // Update visual states
         const chevron = shadow.querySelector(".dropdown-chevron");
         if (chevron)
             chevron.classList.remove("open");
         const searchChevron = shadow.querySelector(".dropdown-search-chevron");
         if (searchChevron)
             searchChevron.classList.remove("open");
-        // Reset search and restore all tags
         const hadQuery = this._state.search !== "";
         this._state.search = "";
         const searchInput = shadow.querySelector(".dropdown-search-input");
@@ -732,10 +480,6 @@ export class TySelect extends TyComponent {
             searchInput.value = "";
         }
         if (this._externalSearch) {
-            // External mode — notify consumer so it can reset its own filtered state.
-            // Bypass the debounce timer (which would delay the clear by `debounce` ms);
-            // close-time should be immediate so the consumer's filtered state syncs
-            // before the dropdown reopens. Only fire if there was actually a query.
             if (hadQuery) {
                 if (this._searchDebounceTimer !== null) {
                     clearTimeout(this._searchDebounceTimer);
@@ -745,19 +489,13 @@ export class TySelect extends TyComponent {
             }
         }
         else {
-            // Internal mode — restore visibility of all tags ourselves
             const allTags = this.getTagElements().map((el) => this.getTagData(el));
             this._state.filteredTags = allTags;
             this.updateTagVisibility(allTags, allTags);
             this.clearHighlights(allTags);
         }
-        // Lifecycle event
         this.fireCloseEvent();
     }
-    /**
-     * Open mobile modal (mobile mode)
-     * Now using <dialog> element for native z-index management
-     */
     openMobileModal() {
         const shadow = this.shadowRoot;
         const dialog = shadow.querySelector(".mobile-dialog");
@@ -766,48 +504,20 @@ export class TySelect extends TyComponent {
         const stubEl = shadow.querySelector(".select-stub");
         if (stubEl)
             stubEl.setAttribute("aria-expanded", "true");
-        // Lock body scroll while mobile modal is open
         const lockId = `select-${this.id || "anon"}-${getElementHash(this)}`;
         this._scrollLockId = lockId;
         lockScroll(lockId);
-        // Show dialog using native API (handles z-index automatically)
         dialog.showModal();
         dialog.classList.add("open");
-        // Update component state
         this._state.open = true;
-        // Initialize options state. Also ensure nothing stays hidden from a
-        // previous search — mirrors openDropdown()'s updateOptionsVisibility(true)
-        // ("may have been hidden from previous search"), which openMobileModal()
-        // never had a mobile-appropriate equivalent for: desktop hides the whole
-        // options container (a single display:none toggle, harmless to reset
-        // unconditionally), mobile hides individual options via their `hidden`
-        // attribute (updateTagVisibility), so the reset has to happen here.
         const tags = this.getTagElements().map((el) => this.getTagData(el));
         this._state.filteredTags = tags;
         this.updateTagVisibility(tags, tags);
-        // Focus the search input: the `autofocus` attribute on
-        // .mobile-search-input (see render template) handles this — showModal()
-        // itself runs the spec'd "dialog focusing steps" on every call, which
-        // look for an autofocus descendant and focus it natively, skipping it
-        // automatically if it's hidden (search disabled) in favor of the next
-        // focusable element. A manual searchInput.focus() call here, AFTER
-        // showModal() already ran its own focusing steps in the same task, was
-        // racing that native behavior — document.activeElement ended up back on
-        // the host element, not the input, which is why typing did nothing:
-        // keystrokes weren't reaching the search box at all despite it visually
-        // looking focused (cursor showing from the browser's own caret paint,
-        // not actual DOM focus).
-        // Update state after slots are ready
         requestAnimationFrame(() => {
             this.updateMobileSelectedState();
         });
-        // Lifecycle event (also fires empty search if external-search)
         this.fireOpenEvent();
     }
-    /**
-     * Close mobile modal (mobile mode)
-     * Now using <dialog> element for native management
-     */
     closeMobileModal() {
         const shadow = this.shadowRoot;
         const dialog = shadow.querySelector(".mobile-dialog");
@@ -816,18 +526,14 @@ export class TySelect extends TyComponent {
         const stubEl = shadow.querySelector(".select-stub");
         if (stubEl)
             stubEl.setAttribute("aria-expanded", "false");
-        // Close immediately — ::backdrop doesn't support transitions
         dialog.classList.remove("open");
         dialog.close();
-        // Unlock body scroll (paired with the lock in openMobileModal)
         if (this._scrollLockId) {
             unlockScroll(this._scrollLockId);
             this._scrollLockId = null;
         }
-        // Update state
         this._state.open = false;
         this._state.highlightedIndex = -1;
-        // Reset search
         const hadQuery = this._state.search !== "";
         this._state.search = "";
         const searchInput = shadow.querySelector(".mobile-search-input");
@@ -835,8 +541,6 @@ export class TySelect extends TyComponent {
             searchInput.value = "";
         }
         if (this._externalSearch) {
-            // External mode — notify consumer that the search was cleared on close
-            // (bypass debounce, see desktop close path for rationale).
             if (hadQuery) {
                 if (this._searchDebounceTimer !== null) {
                     clearTimeout(this._searchDebounceTimer);
@@ -846,16 +550,11 @@ export class TySelect extends TyComponent {
             }
         }
         else {
-            // Internal mode — unhide all tags ourselves
             const allTags = this.getTagElements();
             allTags.forEach((el) => el.removeAttribute("hidden"));
         }
-        // Lifecycle event
         this.fireCloseEvent();
     }
-    // ============================================================================
-    // EVENT HANDLERS (Phase 5 & 6)
-    // ============================================================================
     handleStubClick(e) {
         e.preventDefault();
         e.stopPropagation();
@@ -864,14 +563,14 @@ export class TySelect extends TyComponent {
         }
         this.openDropdown();
     }
-    /**
-     * Keyboard-open the (closed) stub. The stub is a plain div with
-     * tabindex="0", not a native <button> — Enter/Space don't turn into
-     * click events on their own the way they do for real form controls, and
-     * without this a keyboard-only user could Tab to the field but never
-     * open it. document-level handleKeyboard() only runs once already open
-     * (it early-returns on !this._state.open), so this is the other half.
-     */
+    handleClearClick(e) {
+        e.preventDefault();
+        e.stopPropagation();
+        if (this._disabled || this._readonly) {
+            return;
+        }
+        this.clear();
+    }
     handleStubKeydown(e) {
         if (this._disabled || this._readonly || this._state.open)
             return;
@@ -882,7 +581,6 @@ export class TySelect extends TyComponent {
     }
     handleTagClick(e) {
         const target = e.target;
-        // Find the option element (ty-option or ty-tag)
         const tag = target.closest("ty-option, ty-tag");
         if (!tag || tag.hasAttribute("disabled"))
             return;
@@ -890,18 +588,9 @@ export class TySelect extends TyComponent {
         e.stopPropagation();
         this.selectByTag(tag);
     }
-    /**
-     * Select/toggle a tag by element — the part of handleTagClick that has no
-     * dependency on a real DOM event, so keyboard/programmatic callers (Enter
-     * on a highlighted option, allow-create's exact-match dedup) can call it
-     * directly instead of faking an Event object just to satisfy
-     * preventDefault()/stopPropagation().
-     */
     selectByTag(tag) {
         const tagValue = this.getTagData(tag).value;
         const currentValues = this.getSelectedValues();
-        // Single select: picking replaces the selection and closes the popup
-        // (native <select> semantics — re-picking the same option just closes)
         if (!this._multiple) {
             this.updateComponentValue([tagValue], true, "set", tagValue);
             if (this._state.mode === "mobile") {
@@ -912,7 +601,6 @@ export class TySelect extends TyComponent {
             }
             return;
         }
-        // Multiple: toggle — clicking a selected option deselects it
         if (tag.hasAttribute("selected")) {
             const newValues = currentValues.filter((v) => v !== tagValue);
             this.updateComponentValue(newValues, true, "remove", tagValue);
@@ -921,13 +609,6 @@ export class TySelect extends TyComponent {
             this.updateComponentValue([...currentValues, tagValue], true, "add", tagValue);
         }
     }
-    /**
-     * allow-create: Enter with unmatched search text mints a new option.
-     * Returns true if it handled the key (created, or selected an existing
-     * exact match instead of duplicating) — false if there's nothing to do
-     * (blank query, or allow-create is off), so the caller's normal Enter
-     * handling (select highlighted, or no-op) proceeds.
-     */
     tryCreateFromSearch() {
         if (!this._allowCreate)
             return false;
@@ -936,8 +617,6 @@ export class TySelect extends TyComponent {
             return false;
         const queryLower = query.toLowerCase();
         const allTags = this.getTagElements().map((el) => this.getTagData(el));
-        // Dedup: typed text exactly matches an existing option (by value or
-        // display text) — select it instead of minting a duplicate.
         const existing = allTags.find((t) => t.value.toLowerCase() === queryLower ||
             t.text.toLowerCase() === queryLower);
         if (existing) {
@@ -947,7 +626,7 @@ export class TySelect extends TyComponent {
         const rawLabel = query;
         const defaultValue = this._createTransform === "slug" ? slugify(rawLabel) : rawLabel;
         if (!defaultValue)
-            return true; // slugified to nothing — handled no-op
+            return true;
         const detail = { value: defaultValue, label: rawLabel };
         const event = new CustomEvent("create", {
             detail,
@@ -957,7 +636,7 @@ export class TySelect extends TyComponent {
         });
         this.dispatchEvent(event);
         if (event.defaultPrevented)
-            return true; // consumer takes over entirely
+            return true;
         const finalValue = detail.value;
         const option = document.createElement("ty-option");
         option.setAttribute("value", finalValue);
@@ -978,11 +657,6 @@ export class TySelect extends TyComponent {
         this.clearSearchAfterCreate();
         return true;
     }
-    /**
-     * Multiple + allow-create: clear the search box and re-show the full
-     * (now-longer) option list so the next tag can be typed immediately —
-     * the tags-input pattern.
-     */
     clearSearchAfterCreate() {
         this._state.search = "";
         this._state.highlightedIndex = -1;
@@ -1010,28 +684,18 @@ export class TySelect extends TyComponent {
     handleSearchInput(e) {
         const target = e.target;
         const query = target.value;
-        // Update search state
         this._state.search = query;
         if (this._externalSearch) {
-            // External (remote) search: parent owns filtering — delegate via event.
-            // Tag visibility is left untouched; consumer is expected to update children.
             this.dispatchSearchEvent(query);
             return;
         }
-        // Internal search: filter ALL options locally — selected ones stay visible
-        // (with selected styling) so they can be toggled off while searching
         const allTags = this.getTagElements().map((el) => this.getTagData(el));
         const filtered = this.filterTags(allTags, query);
-        // Update state
         this._state.filteredTags = filtered;
         this._state.highlightedIndex = -1;
-        // Update visibility
         this.updateTagVisibility(filtered, allTags);
-        // Hide options area if no results (desktop)
         this.updateOptionsVisibility(filtered.length > 0);
-        // Refresh mobile count + empty-state to reflect filtered visibility
         this.updateMobileSelectedState();
-        // Clear highlights
         this.clearHighlights(allTags);
     }
     handleKeyboard(e) {
@@ -1040,13 +704,9 @@ export class TySelect extends TyComponent {
         const shadow = this.shadowRoot;
         const searchInput = shadow.querySelector(".dropdown-search-input");
         const target = e.target;
-        // Only handle navigation keys when dropdown is open and either:
-        // 1. Event comes from search input, OR
-        // 2. Event comes from document but search input is not focused
         const shouldHandle = target === searchInput || document.activeElement !== searchInput;
         if (!shouldHandle)
             return;
-        // Get current state values
         const filteredTags = this._state.filteredTags;
         const tagsCount = filteredTags.length;
         const currentHighlightedIndex = this._state.highlightedIndex;
@@ -1059,8 +719,6 @@ export class TySelect extends TyComponent {
             case "Enter":
                 e.preventDefault();
                 e.stopPropagation();
-                // A highlighted (arrowed-to) option always wins — the user picked
-                // it explicitly, so allow-create must not shadow it with a new one.
                 if (currentHighlightedIndex >= 0 &&
                     currentHighlightedIndex < tagsCount) {
                     this.selectByTag(filteredTags[currentHighlightedIndex].element);
@@ -1077,15 +735,12 @@ export class TySelect extends TyComponent {
                     newIndexUp = -1;
                 }
                 else if (currentHighlightedIndex === -1) {
-                    // Nothing highlighted, go to last tag
                     newIndexUp = tagsCount - 1;
                 }
                 else if (currentHighlightedIndex === 0) {
-                    // At first tag, wrap to last
                     newIndexUp = tagsCount - 1;
                 }
                 else {
-                    // Move up one
                     newIndexUp = currentHighlightedIndex - 1;
                 }
                 this._state.highlightedIndex = newIndexUp;
@@ -1099,15 +754,12 @@ export class TySelect extends TyComponent {
                     newIndexDown = -1;
                 }
                 else if (currentHighlightedIndex === -1) {
-                    // Nothing highlighted, go to first tag
                     newIndexDown = 0;
                 }
                 else if (currentHighlightedIndex === tagsCount - 1) {
-                    // At last tag, wrap to first
                     newIndexDown = 0;
                 }
                 else {
-                    // Move down one
                     newIndexDown = currentHighlightedIndex + 1;
                 }
                 this._state.highlightedIndex = newIndexDown;
@@ -1115,12 +767,6 @@ export class TySelect extends TyComponent {
                 break;
         }
     }
-    // ============================================================================
-    // SEARCH & FILTERING HELPERS (Phase 6)
-    // ============================================================================
-    /**
-     * Filter tags based on search query
-     */
     filterTags(tags, query) {
         if (!query || query.trim() === "") {
             return tags;
@@ -1128,9 +774,6 @@ export class TySelect extends TyComponent {
         const searchLower = query.toLowerCase();
         return tags.filter(({ text }) => text.toLowerCase().includes(searchLower));
     }
-    /**
-     * Update visibility of tags based on filtered list
-     */
     updateTagVisibility(filteredTags, allTags) {
         const visibleValues = new Set(filteredTags.map((tag) => tag.value));
         allTags.forEach(({ value, element }) => {
@@ -1142,9 +785,6 @@ export class TySelect extends TyComponent {
             }
         });
     }
-    /**
-     * Show/hide the dropdown options area
-     */
     updateOptionsVisibility(hasOptions) {
         const shadow = this.shadowRoot;
         const options = shadow.querySelector(".dropdown-options");
@@ -1152,23 +792,16 @@ export class TySelect extends TyComponent {
             options.style.display = hasOptions ? "" : "none";
         }
     }
-    /**
-     * Clear all tag highlights
-     */
     clearHighlights(tags) {
         tags.forEach(({ element }) => {
             element.removeAttribute("highlighted");
         });
     }
-    /**
-     * Highlight tag at specific index
-     */
     highlightTag(tags, index) {
         this.clearHighlights(tags);
         if (index >= 0 && index < tags.length) {
             const { element } = tags[index];
             element.setAttribute("highlighted", "");
-            // Scroll into view
             element.scrollIntoView({
                 behavior: "smooth",
                 block: "nearest",
@@ -1176,17 +809,11 @@ export class TySelect extends TyComponent {
             });
         }
     }
-    /**
-     * Dispatch search event for external search handling
-     * With optional debounce support
-     */
     dispatchSearchEvent(query) {
-        // Clear existing timer
         if (this._searchDebounceTimer !== null) {
             clearTimeout(this._searchDebounceTimer);
             this._searchDebounceTimer = null;
         }
-        // If debounce is set, debounce the event
         if (this._debounce > 0) {
             this._searchDebounceTimer = window.setTimeout(() => {
                 this.fireSearchEvent(query);
@@ -1194,13 +821,9 @@ export class TySelect extends TyComponent {
             }, this._debounce);
         }
         else {
-            // Fire immediately if no debounce
             this.fireSearchEvent(query);
         }
     }
-    /**
-     * Fire the actual search event
-     */
     fireSearchEvent(query) {
         this.dispatchEvent(new CustomEvent("search", {
             detail: {
@@ -1211,11 +834,6 @@ export class TySelect extends TyComponent {
             composed: true,
         }));
     }
-    /**
-     * Dispatch lifecycle events for popup open/close.
-     * On open with external-search, also fire a `search` event with an empty
-     * query so consumers have a clean hook to reset/refetch the option list.
-     */
     fireOpenEvent() {
         this.dispatchEvent(new CustomEvent("open", {
             detail: { mode: this._state.mode, element: this },
@@ -1233,12 +851,6 @@ export class TySelect extends TyComponent {
             composed: true,
         }));
     }
-    // ============================================================================
-    // CHANGE EVENT DISPATCHING (Phase 5)
-    // ============================================================================
-    /**
-     * Dispatch custom change event
-     */
     dispatchChangeEvent(detail) {
         this.dispatchEvent(new CustomEvent("change", {
             detail,
@@ -1246,15 +858,7 @@ export class TySelect extends TyComponent {
             cancelable: true,
         }));
     }
-    // ============================================================================
-    // RENDERING
-    // ============================================================================
-    /**
-     * Main render method (required by TyComponent)
-     * Delegates to mode-specific renderer
-     */
     render() {
-        // Sync mode on every render so rotation/resize is picked up
         this._state.mode = isMobileTouch() ? "mobile" : "desktop";
         if (this._state.mode === "mobile") {
             this.renderMobile();
@@ -1263,18 +867,9 @@ export class TySelect extends TyComponent {
             this.renderDesktop();
         }
         this.updateSearchVisibility();
-        // Loading wrapper is rendered dynamically — re-apply each render
         this.applyLoadingState();
-        // Reflect constraint validation (required) to the owning <form>.
         this.updateValidity();
     }
-    /**
-     * Reflect constraint validation to the owning <form> via ElementInternals.
-     * Without this `required` is only cosmetic — form.checkValidity() (and a
-     * real submit) never actually blocks on an empty required select. Mirrors
-     * ty-input's updateValidity(): empty + required => valueMissing; disabled
-     * fields are barred from constraint validation.
-     */
     updateValidity() {
         if (this.disabled) {
             this._internals.setValidity({});
@@ -1288,10 +883,6 @@ export class TySelect extends TyComponent {
             this._internals.setValidity({});
         }
     }
-    /**
-     * When a consumer slots their own trigger (slot="trigger"), strip the
-     * default field chrome so the trigger is styled entirely by the consumer.
-     */
     setupTriggerSlot() {
         const shadow = this.shadowRoot;
         const stub = shadow.querySelector(".select-stub");
@@ -1302,9 +893,6 @@ export class TySelect extends TyComponent {
         slot.addEventListener("slotchange", sync);
         sync();
     }
-    /**
-     * Setup event listeners
-     */
     setupEventListeners() {
         const shadow = this.shadowRoot;
         const stub = shadow.querySelector(".select-stub");
@@ -1315,37 +903,30 @@ export class TySelect extends TyComponent {
             stub.addEventListener("click", this._stubClickHandler);
             stub.addEventListener("keydown", this.handleStubKeydown.bind(this));
         }
+        const clearBtn = shadow.querySelector(".select-clear");
+        clearBtn?.addEventListener("click", this.handleClearClick.bind(this));
         this.setupTriggerSlot();
-        // Add tag click handler to slot
         if (optionsSlot) {
             this._tagClickHandler = this.handleTagClick.bind(this);
             optionsSlot.addEventListener("click", this._tagClickHandler);
         }
-        // Add search input handlers
         if (searchInput) {
             this._searchInputHandler = this.handleSearchInput.bind(this);
             this._blockSearchClick = this.blockSearchClick.bind(this);
             searchInput.addEventListener("input", this._searchInputHandler);
             searchInput.addEventListener("click", this._blockSearchClick);
-            // searchInput.addEventListener('blur', this._searchBlurHandler)
         }
-        // Setup dialog backdrop click handler
         const dialog = shadow.querySelector(".dropdown-dialog");
         if (dialog) {
             dialog.addEventListener("click", (e) => {
-                // Only close if clicking directly on the dialog (backdrop), not its children
                 if (e.target === dialog) {
                     this.closeDropdown();
                 }
             });
         }
-        // Setup keyboard handler
         this._keyboardHandler = this.handleKeyboard.bind(this);
         document.addEventListener("keydown", this._keyboardHandler);
     }
-    /**
-     * Build CSS class list for stub
-     */
     buildStubClasses() {
         const classes = [this._size];
         if (this._disabled)
@@ -1354,12 +935,8 @@ export class TySelect extends TyComponent {
             classes.push("compact");
         return classes.join(" ");
     }
-    /**
-     * Render desktop mode with dialog
-     */
     renderDesktop() {
         const shadow = this.shadowRoot;
-        // Only set innerHTML and setup listeners if container doesn't exist
         if (!shadow.querySelector(".select-container")) {
             const stubClasses = this.buildStubClasses();
             const listboxId = `select-listbox-${getElementHash(this)}`;
@@ -1391,6 +968,9 @@ export class TySelect extends TyComponent {
                 <span class="dropdown-placeholder">${this._placeholder}</span>
                 <span class="select-count" hidden></span>
                 <slot name="end"></slot>
+                <button class="select-clear" type="button" aria-label="Clear selection" hidden>
+                  ${CLEAR_ICON_SVG}
+                </button>
                 <div class="dropdown-chevron">
                   ${CHEVRON_DOWN_SVG}
                 </div>
@@ -1426,21 +1006,12 @@ export class TySelect extends TyComponent {
           </div>
         </div>
       `;
-            // Setup event listeners ONCE
             this.setupEventListeners();
-            // Don't initialize here - will be done in connectedCallback
-            // after properties are set and children are available
         }
-        // Always update placeholder visibility on re-render
         this.updateSelectionDisplay();
     }
-    /**
-     * Render mobile mode with full-screen modal
-     * Following dropdown.ts mobile structure
-     */
     renderMobile() {
         const shadow = this.shadowRoot;
-        // Only set innerHTML and setup listeners if container doesn't exist
         if (!shadow.querySelector(".select-container")) {
             const stubClasses = this.buildStubClasses();
             const listboxId = `select-listbox-${getElementHash(this)}`;
@@ -1453,16 +1024,13 @@ export class TySelect extends TyComponent {
         </label>
       `
                 : "";
-            // Close button SVG (X icon)
             const closeButtonSvg = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
         <line x1="18" y1="6" x2="6" y2="18"></line>
         <line x1="6" y1="6" x2="18" y2="18"></line>
       </svg>`;
-            // Search placeholder: "Search <label>..." or just "Search..."
             const searchPlaceholder = this._label
                 ? `Search ${this._label}...`
                 : "Search...";
-            // Search is always available — only the mode (internal vs external) varies.
             const searchHeaderHtml = `
         <div class="mobile-search-header">
           ${this._label ? `<span class="mobile-header-label">${this._label}</span>` : ""}
@@ -1501,6 +1069,9 @@ export class TySelect extends TyComponent {
                 <span class="dropdown-placeholder">${this._placeholder}</span>
                 <span class="select-count" hidden></span>
                 <slot name="end"></slot>
+                <button class="select-clear" type="button" aria-label="Clear selection" hidden>
+                  ${CLEAR_ICON_SVG}
+                </button>
                 <div class="dropdown-chevron">
                   ${CHEVRON_DOWN_SVG}
                 </div>
@@ -1539,16 +1110,10 @@ export class TySelect extends TyComponent {
           </div>
         </div>
       `;
-            // Setup event listeners ONCE
             this.setupMobileEventListeners();
         }
-        // Always update placeholder visibility
         this.updateSelectionDisplay();
     }
-    /**
-     * Setup event listeners for mobile mode
-     * Using <dialog> element - backdrop clicks handled natively
-     */
     setupMobileEventListeners() {
         const shadow = this.shadowRoot;
         const stub = shadow.querySelector(".select-stub");
@@ -1560,38 +1125,30 @@ export class TySelect extends TyComponent {
             stub.addEventListener("click", (e) => this.handleMobileStubClick(e));
             stub.addEventListener("keydown", (e) => this.handleMobileStubKeydown(e));
         }
+        const clearBtn = shadow.querySelector(".select-clear");
+        clearBtn?.addEventListener("click", this.handleClearClick.bind(this));
         this.setupTriggerSlot();
-        // Add tag click handler to slot
         if (optionsSlot) {
             optionsSlot.addEventListener("click", (e) => this.handleMobileTagClick(e));
         }
-        // Add search input handlers (if searchable)
         if (searchInput) {
             searchInput.addEventListener("input", (e) => this.handleSearchInput(e));
         }
-        // Close button click
         if (closeButton) {
             closeButton.addEventListener("click", () => this.closeMobileModal());
         }
-        // Backdrop click to close (native dialog behavior)
         if (dialog) {
             dialog.addEventListener("click", (e) => {
-                // Only close if clicking directly on the dialog element (backdrop)
-                // Not if clicking on its children (dialog-content)
                 if (e.target === dialog) {
                     this.closeMobileModal();
                 }
             });
-            // Also handle Escape key via cancel event
             dialog.addEventListener("cancel", (e) => {
-                e.preventDefault(); // Prevent default to handle it our way
+                e.preventDefault();
                 this.closeMobileModal();
             });
         }
     }
-    /**
-     * Handle mobile stub click - open modal
-     */
     handleMobileStubClick(e) {
         e.preventDefault();
         e.stopPropagation();
@@ -1600,7 +1157,6 @@ export class TySelect extends TyComponent {
         }
         this.openMobileModal();
     }
-    /** Keyboard-open the (closed) mobile stub — see handleStubKeydown for why this is needed. */
     handleMobileStubKeydown(e) {
         if (this._disabled || this._readonly || this._state.open)
             return;
@@ -1609,45 +1165,26 @@ export class TySelect extends TyComponent {
             this.openMobileModal();
         }
     }
-    /**
-     * Handle mobile tag click - select and potentially close
-     */
     handleMobileTagClick(e) {
-        // Use the same tag click handler as desktop
-        // It already handles mobile mode for auto-close
         this.handleTagClick(e);
     }
-    /**
-     * Update mobile options section state (count, empty state)
-     */
     updateMobileSelectedState() {
         if (this._state.mode !== "mobile")
             return;
         const shadow = this.shadowRoot;
         const availableSection = shadow.querySelector(".mobile-available-section");
         if (availableSection) {
-            // Count *visible* options — options hidden by search filtering count as 0
             const visibleAvailable = this.getTagElements().filter((tag) => !tag.hasAttribute("hidden")).length;
             availableSection.setAttribute("data-empty", String(visibleAvailable === 0));
-            // Update available header count
             const availableTitleSpan = shadow.querySelector(".mobile-available-section .section-title");
             if (availableTitleSpan) {
                 availableTitleSpan.textContent = `${this._availableLabel} (${visibleAvailable})`;
             }
         }
     }
-    /**
-     * 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
-     * only when the option list is long enough to need filtering.
-     */
     shouldShowSearch() {
         if (this._externalSearch)
             return true;
-        // allow-create's only input mechanism IS the search box.
         if (this._allowCreate)
             return true;
         if (this._searchable === "always")
@@ -1656,9 +1193,6 @@ export class TySelect extends TyComponent {
             return false;
         return this.getTagElements().length > SEARCH_AUTO_THRESHOLD;
     }
-    /**
-     * Toggle the search row (desktop header / mobile input) per shouldShowSearch.
-     */
     updateSearchVisibility() {
         const shadow = this.shadowRoot;
         if (!shadow)
@@ -1667,7 +1201,6 @@ export class TySelect extends TyComponent {
         const header = shadow.querySelector(".dropdown-header");
         if (header)
             header.hidden = !show;
-        // Mobile keeps its header (label + close button); only the input+icon hide
         const mobileInput = shadow.querySelector(".mobile-search-input");
         if (mobileInput)
             mobileInput.hidden = !show;
@@ -1675,22 +1208,11 @@ export class TySelect extends TyComponent {
         if (mobileIcon)
             mobileIcon.hidden = !show;
     }
-    /**
-     * Selection summary appropriate to cardinality × skin:
-     * - single (field or compact): the selected OPTION itself — cloned into
-     *   slot="selected" so rich HTML options display intact (dropdown parity);
-     *   placeholder when empty
-     * - multiple + field: joined labels (ellipsis via CSS), or placeholder
-     * - multiple + compact: placeholder + count badge
-     */
     updateSelectionDisplay() {
         const shadow = this.shadowRoot;
         const stub = shadow.querySelector(".select-stub");
         if (!stub)
             return;
-        // Selection comes from STATE, not from scanning option elements —
-        // external search replaces the option children, and the selection must
-        // survive even when the current results don't include the selected value.
         const values = this._state.selectedValues;
         const count = values.length;
         stub.classList.toggle("has-selection", count > 0);
@@ -1700,14 +1222,15 @@ export class TySelect extends TyComponent {
             badge.textContent = String(count);
             badge.hidden = count === 0 || !this._multiple || !this._compact;
         }
-        // Single select: project the selected option into the stub as a clone
-        // (rich HTML content survives — same mechanism as ty-dropdown).
+        const clearBtn = stub.querySelector(".select-clear");
+        if (clearBtn) {
+            clearBtn.hidden = !(count > 0 && this._clearable && !this._disabled && !this._readonly);
+        }
         const wantClone = !this._multiple && count > 0 ? values[0] : null;
         this.syncSelectedClone(wantClone);
         stub.classList.toggle("has-clone", wantClone !== null);
         const textEl = stub.querySelector(".dropdown-placeholder");
         if (textEl) {
-            // The clone replaces the text display entirely in single mode
             textEl.hidden = wantClone !== null;
             const showLabels = count > 0 && this._multiple && !this._compact;
             if (showLabels) {
@@ -1722,17 +1245,11 @@ export class TySelect extends TyComponent {
             }
         }
     }
-    /**
-     * Keep exactly one display clone (slot="selected", marked `cloned`) in our
-     * light DOM matching the given value — or none. The clone never counts as
-     * an option (getTagElements filters [cloned]) and ty-option's own
-     * :host([cloned]) styling strips its list-row chrome.
-     */
     syncSelectedClone(value) {
         const existing = this.querySelector(':scope > [cloned][slot="selected"]');
         if (existing?.getAttribute("value") === value) {
             this._selectedClone = existing;
-            return; // already right
+            return;
         }
         existing?.remove();
         if (value === null) {
@@ -1742,37 +1259,28 @@ export class TySelect extends TyComponent {
         const option = this.getTagElements().find((el) => this.getTagData(el).value === value);
         if (option) {
             const clone = option.cloneNode(true);
-            clone.removeAttribute("selected"); // no tick/selected styling in the stub
+            clone.removeAttribute("selected");
             clone.setAttribute("slot", "selected");
             clone.setAttribute("cloned", "true");
             this.appendChild(clone);
             this._selectedClone = clone;
         }
         else if (this._selectedClone?.getAttribute("value") === value) {
-            // The option list no longer contains the selection (external search
-            // swapped the children — possibly wiping our clone with them). Restore
-            // the saved display clone so the selection stays visible.
             const restored = this._selectedClone.cloneNode(true);
             this.appendChild(restored);
             this._selectedClone = restored;
         }
     }
-    // ============================================================================
-    // PUBLIC API - Getters/Setters
-    // ============================================================================
-    /**
-     * Deselect a value programmatically WITH a change event.
-     * Used by out-of-band chip displays (ty-selected-options) so dismissing a chip
-     * fires change like any in-popup interaction (HTMX hx-trigger="change" etc.).
-     */
     deselectValue(value) {
         const current = this.getSelectedValues();
         if (!current.includes(value))
             return;
         this.updateComponentValue(current.filter((v) => v !== value), true, "remove", value);
     }
+    clear() {
+        this.updateComponentValue([], true, "clear", null);
+    }
     get value() {
-        // Always read from DOM - tags with 'selected' attribute are source of truth
         return this.getSelectedValues().join(",");
     }
     set value(val) {
@@ -1826,6 +1334,12 @@ export class TySelect extends TyComponent {
     set readonly(value) {
         this.setProperty("readonly", value);
     }
+    get clearable() {
+        return this.getProperty("clearable");
+    }
+    set clearable(value) {
+        this.setProperty("clearable", value);
+    }
     get required() {
         return this.getProperty("required");
     }
@@ -1857,6 +1371,12 @@ export class TySelect extends TyComponent {
     set size(value) {
         this.setProperty("size", value);
     }
+    get align() {
+        return this.getProperty("align");
+    }
+    set align(value) {
+        this.setProperty("align", value);
+    }
     get flavor() {
         return this.getProperty("flavor");
     }
@@ -1867,9 +1387,6 @@ export class TySelect extends TyComponent {
         return this._internals.form;
     }
 }
-// ============================================================================
-// PROPERTY CONFIGURATION - Declarative property lifecycle
-// ============================================================================
 TySelect.properties = {
     value: {
         type: "string",
@@ -1878,15 +1395,12 @@ TySelect.properties = {
         emitChange: false,
         default: "",
         coerce: (v) => {
-            // Handle array input (from React, Reagent, etc.)
             if (Array.isArray(v)) {
                 return v.join(",");
             }
-            // Handle null/undefined
             if (v === null || v === undefined) {
                 return "";
             }
-            // String already
             return String(v);
         },
     },
@@ -1894,14 +1408,11 @@ TySelect.properties = {
         type: "string",
         default: "",
     },
-    // Cardinality — native <select> semantics: absent = single select
     multiple: {
         type: "boolean",
         visual: true,
         default: false,
     },
-    // Skin — absent = form field (matches ty-input); present = compact
-    // content-hugging trigger (toolbars, filter bars)
     compact: {
         type: "boolean",
         visual: true,
@@ -1932,23 +1443,24 @@ TySelect.properties = {
         visual: true,
         default: false,
     },
+    clearable: {
+        type: "boolean",
+        visual: true,
+        default: true,
+        aliases: { "not-clearable": false },
+    },
     externalSearch: {
         type: "boolean",
         visual: true,
         default: false,
         aliases: { "external-search": true },
     },
-    // Enter on unmatched search text mints a new <ty-option> — forces the
-    // search row on (same as external-search: the input IS the mechanism).
     allowCreate: {
         type: "boolean",
         visual: true,
         default: false,
         aliases: { "allow-create": true },
     },
-    // Opt-in normalizer for the value minted by allow-create (label/display
-    // text is always kept verbatim). 'none' (default): value === typed text.
-    // 'slug': lowercase, spaces → '_', strips anything else non-alphanumeric.
     createTransform: {
         type: "string",
         visual: false,
@@ -1956,9 +1468,6 @@ TySelect.properties = {
         aliases: { "create-transform": true },
         coerce: (v) => (v === "slug" ? "slug" : "none"),
     },
-    // Search row visibility: 'auto' (default) shows it only for long option
-    // lists; searchable / searchable="true" forces it on, searchable="false"
-    // off. external-search always shows it (the input IS the mechanism).
     searchable: {
         type: "string",
         visual: true,
@@ -1971,11 +1480,17 @@ TySelect.properties = {
             return "auto";
         },
     },
+    align: {
+        type: "string",
+        visual: true,
+        default: "start",
+        validate: (v) => ["start", "end"].includes(v),
+        coerce: (v) => (v === "end" ? "end" : "start"),
+    },
     size: {
         type: "string",
         visual: true,
         default: "md",
-        // Fields come in exactly three sizes; legacy xs/xl map to sm/lg.
         validate: (v) => ["sm", "md", "lg"].includes(v),
         coerce: (v) => {
             if (v === "xs")
@@ -2015,17 +1530,12 @@ TySelect.properties = {
         visual: true,
         default: false,
     },
-    // Any string is accepted: built-ins get static CSS, other identifiers
-    // become custom flavors (see _syncCustomFlavor), garbage degrades to
-    // the default look.
     flavor: {
         type: "string",
         visual: true,
         default: "neutral",
     },
 };
-// Register the custom element
 if (!customElements.get("ty-select")) {
     customElements.define("ty-select", TySelect);
 }
-//# sourceMappingURL=select.js.map