tyrell-components 1.0.0-RC12 → 1.0.0-RC13

package/lib/components/select.js

@@ -13,7 +13,7 @@
  *   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-tags>)
+ *   <ty-selected-options>)
  * - slot="trigger": consumer skin — replaces field/compact chrome entirely,
  *   behavior/ARIA/form participation unchanged
  *
@@ -35,14 +35,16 @@
  *
  * <!-- Multi select, compact skin + out-of-band chips -->
  * <ty-select multiple compact label="Robots" name="robots" id="robots">...</ty-select>
- * <ty-selected-tags for="robots"></ty-selected-tags>
+ * <ty-selected-options for="robots"></ty-selected-options>
  * ```
  */
 import { ensureStyles } from "../utils/styles.js";
-import { multiselectStyles } from "../styles/multiselect.js";
+import { syncCustomFlavorSheet } from "../utils/flavor-sheet.js";
+import { selectBaseStyles, selectCustomFlavorCss } from "../styles/select-base.js";
 import { selectStyles } from "../styles/select.js";
 import { getLoaderSvg } from "../utils/loader-registry.js";
 import { lockScroll, unlockScroll } from "../utils/scroll-lock.js";
+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";
@@ -76,10 +78,7 @@ function getElementHash(element) {
 // ============================================================================
 // SVG Icons
 // ============================================================================
-/**
- * Required indicator SVG icon (from Lucide)
- */
-const REQUIRED_ICON_SVG = `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-asterisk"><path d="M12 6v12"/><path d="M17.196 9 6.804 15"/><path d="m6.804 9 10.392 6"/></svg>`;
+import { REQUIRED_ICON_SVG } from "../utils/icons.js";
 /**
  * Chevron down icon SVG
  */
@@ -91,6 +90,19 @@ const CHEVRON_DOWN_SVG = `<svg viewBox="0 0 20 20" fill="currentColor">
  * 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()
+        .toLowerCase()
+        .replace(/\s+/g, "_")
+        .replace(/[^a-z0-9_]/g, "")
+        .replace(/_+/g, "_")
+        .replace(/^_|_$/g, "");
+}
 /**
  * Search (magnifier) icon SVG — popup search input adornment (from Lucide)
  */
@@ -98,7 +110,15 @@ const SEARCH_ICON_SVG = `<svg viewBox="0 0 24 24" fill="none" stroke="currentCol
   <circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/>
 </svg>`;
 /**
- * Ty Multiselect Component
+ * Clear (X) icon SVG — .select-clear button, shown in the trigger's fallback
+ * chrome (default/compact skins) when clearable and something is selected.
+ */
+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>`;
+/**
+ * Ty Select Component
  */
 export class TySelect extends TyComponent {
     constructor() {
@@ -114,7 +134,10 @@ 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";
         this._searchable = "auto";
         this._loading = false;
         this._scrollLockId = null;
@@ -147,8 +170,9 @@ export class TySelect extends TyComponent {
         // 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: multiselectStyles, id: "ty-select-base" });
+        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
@@ -179,6 +203,7 @@ export class TySelect extends TyComponent {
         // (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);
             }
@@ -188,8 +213,25 @@ export class TySelect extends TyComponent {
             // 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
@@ -244,6 +286,9 @@ export class TySelect extends TyComponent {
                 case "name":
                     this._name = newValue || "";
                     break;
+                case "flavor":
+                    this._syncCustomFlavor();
+                    break;
                 case "multiple":
                     this._multiple = newValue;
                     // Dropping to single with a multi selection: keep only the first
@@ -271,6 +316,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;
@@ -279,6 +329,14 @@ export class TySelect extends TyComponent {
                     if (this.isConnected && this.shadowRoot)
                         this.updateSearchVisibility();
                     break;
+                case "allowCreate":
+                    this._allowCreate = newValue;
+                    if (this.isConnected && this.shadowRoot)
+                        this.updateSearchVisibility();
+                    break;
+                case "createTransform":
+                    this._createTransform = newValue;
+                    break;
                 case "size":
                     this._size = newValue;
                     break;
@@ -342,7 +400,7 @@ export class TySelect extends TyComponent {
         return null;
     }
     /**
-     * Parse multiselect value (comma-separated string to array)
+     * Parse select value (comma-separated string to array)
      */
     parseValue(value) {
         // Defensive check: ensure value is actually a string before calling .trim()
@@ -410,7 +468,7 @@ export class TySelect extends TyComponent {
     }
     /**
      * Select an option - attribute only. The option stays in the list with
-     * selected styling; chips are rendered out-of-band (ty-selected-tags).
+     * selected styling; chips are rendered out-of-band (ty-selected-options).
      */
     selectTag(tag) {
         tag.setAttribute("selected", "");
@@ -446,6 +504,24 @@ 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"))
+                tag.setAttribute("role", "option");
+            if (!tag.hasAttribute("aria-selected"))
+                tag.setAttribute("aria-selected", "false");
         });
     }
     /**
@@ -463,6 +539,10 @@ export class TySelect extends TyComponent {
             // 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({
@@ -499,13 +579,11 @@ export class TySelect extends TyComponent {
      */
     calculatePosition() {
         const shadow = this.shadowRoot;
-        const stub = shadow.querySelector(".multiselect-stub");
+        const stub = shadow.querySelector(".select-stub");
         const dialog = shadow.querySelector(".dropdown-dialog");
         if (!stub || !dialog)
             return;
         const stubRect = stub.getBoundingClientRect();
-        const viewportHeight = window.innerHeight;
-        const viewportWidth = window.innerWidth;
         // 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.
@@ -513,7 +591,6 @@ export class TySelect extends TyComponent {
         const MAX_POPUP_ESTIMATE = 440;
         const dialogRect = dialog.getBoundingClientRect();
         const estimatedHeight = Math.min(dialogRect.height || 200, MAX_POPUP_ESTIMATE);
-        const padding = 8;
         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.
@@ -521,20 +598,16 @@ export class TySelect extends TyComponent {
         const popupWidth = !isNaN(cssWidth)
             ? cssWidth
             : Math.max(stubRect.width, 320);
-        // Available space calculations
-        const spaceBelow = viewportHeight - stubRect.bottom;
-        const spaceAbove = stubRect.top;
-        // Smart direction logic: below when it fits — and when neither side
-        // fits, take the side with MORE room instead of blindly flipping up
-        // (a field near the viewport top used to clip the popup off-screen).
-        const positionBelow = spaceBelow >= estimatedHeight + padding || spaceBelow >= spaceAbove;
-        // Anchor to the trigger's left edge, clamped into the viewport
-        const x = Math.max(padding - wrapPadding, Math.min(stubRect.left - wrapPadding, viewportWidth - popupWidth - wrapPadding - padding));
-        // Open below (or above) the trigger — never covering it
-        const gap = 4;
-        const y = positionBelow
-            ? stubRect.bottom + gap - wrapPadding
-            : viewportHeight - stubRect.top + gap - wrapPadding;
+        const pos = computeAnchoredPosition({
+            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`);
@@ -596,8 +669,11 @@ export class TySelect extends TyComponent {
         const dialog = shadow.querySelector(".dropdown-dialog");
         if (!dialog)
             return;
+        const stubEl = shadow.querySelector(".select-stub");
+        if (stubEl)
+            stubEl.setAttribute("aria-expanded", "true");
         // Lock body scroll while dropdown is open
-        const lockId = `multiselect-${this.id || "anon"}-${getElementHash(this)}`;
+        const lockId = `select-${this.id || "anon"}-${getElementHash(this)}`;
         this._scrollLockId = lockId;
         lockScroll(lockId);
         // Show modal
@@ -638,6 +714,9 @@ export class TySelect extends TyComponent {
         const dialog = shadow.querySelector(".dropdown-dialog");
         if (!dialog)
             return;
+        const stubEl = shadow.querySelector(".select-stub");
+        if (stubEl)
+            stubEl.setAttribute("aria-expanded", "false");
         // Destroy custom scrollbar
         this._destroyOptionsScrollbar();
         // Close dialog
@@ -699,8 +778,11 @@ export class TySelect extends TyComponent {
         const dialog = shadow.querySelector(".mobile-dialog");
         if (!dialog)
             return;
+        const stubEl = shadow.querySelector(".select-stub");
+        if (stubEl)
+            stubEl.setAttribute("aria-expanded", "true");
         // Lock body scroll while mobile modal is open
-        const lockId = `multiselect-${this.id || "anon"}-${getElementHash(this)}`;
+        const lockId = `select-${this.id || "anon"}-${getElementHash(this)}`;
         this._scrollLockId = lockId;
         lockScroll(lockId);
         // Show dialog using native API (handles z-index automatically)
@@ -708,15 +790,28 @@ export class TySelect extends TyComponent {
         dialog.classList.add("open");
         // Update component state
         this._state.open = true;
-        // Initialize options state
+        // 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;
-        // Focus search input (when the search row is shown)
-        const searchInput = shadow.querySelector(".mobile-search-input");
-        if (searchInput && this.shouldShowSearch()) {
-            // Small delay to ensure dialog is ready
-            setTimeout(() => searchInput.focus(), 100);
-        }
+        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();
@@ -733,6 +828,9 @@ export class TySelect extends TyComponent {
         const dialog = shadow.querySelector(".mobile-dialog");
         if (!dialog)
             return;
+        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();
@@ -781,6 +879,34 @@ export class TySelect extends TyComponent {
         }
         this.openDropdown();
     }
+    /**
+     * .select-clear click — must stop propagation before it bubbles to the
+     * stub's own click handler (which would otherwise also open the dropdown).
+     */
+    handleClearClick(e) {
+        e.preventDefault();
+        e.stopPropagation();
+        if (this._disabled || this._readonly) {
+            return;
+        }
+        this.clear();
+    }
+    /**
+     * 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.
+     */
+    handleStubKeydown(e) {
+        if (this._disabled || this._readonly || this._state.open)
+            return;
+        if (e.key === "Enter" || e.key === " " || e.key === "ArrowDown") {
+            e.preventDefault();
+            this.openDropdown();
+        }
+    }
     handleTagClick(e) {
         const target = e.target;
         // Find the option element (ty-option or ty-tag)
@@ -789,6 +915,16 @@ export class TySelect extends TyComponent {
             return;
         e.preventDefault();
         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
@@ -812,6 +948,88 @@ 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;
+        const query = (this._state.search || "").trim();
+        if (!query)
+            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) {
+            this.selectByTag(existing.element);
+            return true;
+        }
+        const rawLabel = query;
+        const defaultValue = this._createTransform === "slug" ? slugify(rawLabel) : rawLabel;
+        if (!defaultValue)
+            return true; // slugified to nothing — handled no-op
+        const detail = { value: defaultValue, label: rawLabel };
+        const event = new CustomEvent("create", {
+            detail,
+            bubbles: true,
+            composed: true,
+            cancelable: true,
+        });
+        this.dispatchEvent(event);
+        if (event.defaultPrevented)
+            return true; // consumer takes over entirely
+        const finalValue = detail.value;
+        const option = document.createElement("ty-option");
+        option.setAttribute("value", finalValue);
+        option.textContent = rawLabel;
+        this.appendChild(option);
+        if (!this._multiple) {
+            this.updateComponentValue([finalValue], true, "create", finalValue);
+            if (this._state.mode === "mobile") {
+                this.closeMobileModal();
+            }
+            else {
+                this.closeDropdown();
+            }
+            return true;
+        }
+        const currentValues = this.getSelectedValues();
+        this.updateComponentValue([...currentValues, finalValue], true, "create", finalValue);
+        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;
+        const shadow = this.shadowRoot;
+        if (!shadow)
+            return;
+        const desktopInput = shadow.querySelector(".dropdown-search-input");
+        const mobileInput = shadow.querySelector(".mobile-search-input");
+        if (desktopInput)
+            desktopInput.value = "";
+        if (mobileInput)
+            mobileInput.value = "";
+        const allTags = this.getTagElements().map((el) => this.getTagData(el));
+        this._state.filteredTags = allTags;
+        this.updateTagVisibility(allTags, allTags);
+        this.updateOptionsVisibility(true);
+        this.clearHighlights(allTags);
+        this.updateMobileSelectedState();
+        (desktopInput ?? mobileInput)?.focus();
+    }
     blockSearchClick(e) {
         e.stopPropagation();
         e.preventDefault();
@@ -868,11 +1086,14 @@ export class TySelect extends TyComponent {
             case "Enter":
                 e.preventDefault();
                 e.stopPropagation();
-                // Select highlighted tag if any
+                // 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) {
-                    const tag = filteredTags[currentHighlightedIndex];
-                    this.handleTagClick({ target: tag.element });
+                    this.selectByTag(filteredTags[currentHighlightedIndex].element);
+                }
+                else {
+                    this.tryCreateFromSearch();
                 }
                 break;
             case "ArrowUp":
@@ -1071,6 +1292,28 @@ export class TySelect extends TyComponent {
         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({});
+            return;
+        }
+        if (this.required && this.getSelectedValues().length === 0) {
+            const stub = this.shadowRoot?.querySelector(".select-stub");
+            this._internals.setValidity({ valueMissing: true }, "Please select a value", stub ?? undefined);
+        }
+        else {
+            this._internals.setValidity({});
+        }
     }
     /**
      * When a consumer slots their own trigger (slot="trigger"), strip the
@@ -1078,7 +1321,7 @@ export class TySelect extends TyComponent {
      */
     setupTriggerSlot() {
         const shadow = this.shadowRoot;
-        const stub = shadow.querySelector(".multiselect-stub");
+        const stub = shadow.querySelector(".select-stub");
         const slot = shadow.querySelector('slot[name="trigger"]');
         if (!stub || !slot)
             return;
@@ -1091,13 +1334,16 @@ export class TySelect extends TyComponent {
      */
     setupEventListeners() {
         const shadow = this.shadowRoot;
-        const stub = shadow.querySelector(".multiselect-stub");
+        const stub = shadow.querySelector(".select-stub");
         const optionsSlot = shadow.querySelector("#options-slot");
         const searchInput = shadow.querySelector(".dropdown-search-input");
         if (stub) {
             this._stubClickHandler = this.handleStubClick.bind(this);
             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) {
@@ -1143,11 +1389,13 @@ export class TySelect extends TyComponent {
     renderDesktop() {
         const shadow = this.shadowRoot;
         // Only set innerHTML and setup listeners if container doesn't exist
-        if (!shadow.querySelector(".multiselect-container")) {
+        if (!shadow.querySelector(".select-container")) {
             const stubClasses = this.buildStubClasses();
+            const listboxId = `select-listbox-${getElementHash(this)}`;
+            const labelId = `select-label-${getElementHash(this)}`;
             const labelHtml = this._label
                 ? `
-        <label class="ty-field-label">
+        <label class="ty-field-label" id="${labelId}">
           ${this._label}
           ${this._required ? `<span class="required-icon">${REQUIRED_ICON_SVG}</span>` : ""}
         </label>
@@ -1155,17 +1403,26 @@ export class TySelect extends TyComponent {
                 : "";
             const searchPlaceholder = "Search...";
             shadow.innerHTML = `
-        <div class="multiselect-container dropdown-mode-desktop">
+        <div class="select-container dropdown-mode-desktop">
           ${labelHtml}
           <div class="dropdown-wrapper">
-            <div class="dropdown-stub multiselect-stub ${stubClasses}"
-                 ${this._disabled ? "disabled" : ""}>
+            <div class="dropdown-stub select-stub ${stubClasses}"
+                 role="combobox"
+                 aria-haspopup="listbox"
+                 aria-expanded="false"
+                 aria-controls="${listboxId}"
+                 ${this._label ? `aria-labelledby="${labelId}"` : ""}
+                 tabindex="${this._disabled ? "-1" : "0"}"
+                 ${this._disabled ? 'disabled aria-disabled="true"' : ""}>
               <slot name="trigger">
                 <slot name="start"></slot>
                 <slot name="selected"></slot>
                 <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>
@@ -1187,7 +1444,7 @@ export class TySelect extends TyComponent {
                 </div>
               </div>
               <div class="dropdown-options-wrapper">
-                <div class="dropdown-options">
+                <div class="dropdown-options" id="${listboxId}" role="listbox" ${this._multiple ? 'aria-multiselectable="true"' : ""}>
                   <slot id="options-slot"></slot>
                 </div>
                 <div class="dropdown-loading" aria-hidden="true">
@@ -1216,11 +1473,13 @@ export class TySelect extends TyComponent {
     renderMobile() {
         const shadow = this.shadowRoot;
         // Only set innerHTML and setup listeners if container doesn't exist
-        if (!shadow.querySelector(".multiselect-container")) {
+        if (!shadow.querySelector(".select-container")) {
             const stubClasses = this.buildStubClasses();
+            const listboxId = `select-listbox-${getElementHash(this)}`;
+            const labelId = `select-label-${getElementHash(this)}`;
             const labelHtml = this._label
                 ? `
-        <label class="ty-field-label">
+        <label class="ty-field-label" id="${labelId}">
           ${this._label}
           ${this._required ? `<span class="required-icon">${REQUIRED_ICON_SVG}</span>` : ""}
         </label>
@@ -1247,6 +1506,7 @@ export class TySelect extends TyComponent {
               class="mobile-search-input ${this._size}"
               type="text"
               placeholder="${searchPlaceholder}"
+              autofocus
               ${this._disabled ? "disabled" : ""}
             />
             <button class="mobile-close-button" type="button" aria-label="Close">
@@ -1256,17 +1516,26 @@ export class TySelect extends TyComponent {
         </div>
       `;
             shadow.innerHTML = `
-        <div class="multiselect-container dropdown-mode-mobile">
+        <div class="select-container dropdown-mode-mobile">
           ${labelHtml}
           <div class="dropdown-wrapper">
-            <div class="dropdown-stub multiselect-stub ${stubClasses}"
-                 ${this._disabled ? "disabled" : ""}>
+            <div class="dropdown-stub select-stub ${stubClasses}"
+                 role="combobox"
+                 aria-haspopup="listbox"
+                 aria-expanded="false"
+                 aria-controls="${listboxId}"
+                 ${this._label ? `aria-labelledby="${labelId}"` : ""}
+                 tabindex="${this._disabled ? "-1" : "0"}"
+                 ${this._disabled ? 'disabled aria-disabled="true"' : ""}>
               <slot name="trigger">
                 <slot name="start"></slot>
                 <slot name="selected"></slot>
                 <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>
@@ -1287,7 +1556,7 @@ export class TySelect extends TyComponent {
                     <div class="section-header">
                       <span class="section-title">${this._availableLabel}</span>
                     </div>
-                    <div class="section-content dropdown-options-wrapper">
+                    <div class="section-content dropdown-options-wrapper" id="${listboxId}" role="listbox" ${this._multiple ? 'aria-multiselectable="true"' : ""}>
                       <slot id="options-slot"></slot>
                       <div class="empty-state">${this._noOptionsMessage}</div>
                       <div class="dropdown-loading" aria-hidden="true">
@@ -1317,14 +1586,17 @@ export class TySelect extends TyComponent {
      */
     setupMobileEventListeners() {
         const shadow = this.shadowRoot;
-        const stub = shadow.querySelector(".multiselect-stub");
+        const stub = shadow.querySelector(".select-stub");
         const optionsSlot = shadow.querySelector("#options-slot");
         const searchInput = shadow.querySelector(".mobile-search-input");
         const closeButton = shadow.querySelector(".mobile-close-button");
         const dialog = shadow.querySelector(".mobile-dialog");
         if (stub) {
             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) {
@@ -1365,6 +1637,15 @@ 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;
+        if (e.key === "Enter" || e.key === " " || e.key === "ArrowDown") {
+            e.preventDefault();
+            this.openMobileModal();
+        }
+    }
     /**
      * Handle mobile tag click - select and potentially close
      */
@@ -1403,6 +1684,9 @@ export class TySelect extends TyComponent {
     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")
             return true;
         if (this._searchable === "never")
@@ -1438,7 +1722,7 @@ export class TySelect extends TyComponent {
      */
     updateSelectionDisplay() {
         const shadow = this.shadowRoot;
-        const stub = shadow.querySelector(".multiselect-stub");
+        const stub = shadow.querySelector(".select-stub");
         if (!stub)
             return;
         // Selection comes from STATE, not from scanning option elements —
@@ -1453,6 +1737,10 @@ export class TySelect extends TyComponent {
             badge.textContent = String(count);
             badge.hidden = count === 0 || !this._multiple || !this._compact;
         }
+        const clearBtn = stub.querySelector(".select-clear");
+        if (clearBtn) {
+            clearBtn.hidden = !(count > 0 && this._clearable && !this._disabled && !this._readonly);
+        }
         // Single select: project the selected option into the stub as a clone
         // (rich HTML content survives — same mechanism as ty-dropdown).
         const wantClone = !this._multiple && count > 0 ? values[0] : null;
@@ -1515,7 +1803,7 @@ export class TySelect extends TyComponent {
     // ============================================================================
     /**
      * Deselect a value programmatically WITH a change event.
-     * Used by out-of-band chip displays (ty-selected-tags) so dismissing a chip
+     * 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) {
@@ -1524,6 +1812,15 @@ export class TySelect extends TyComponent {
             return;
         this.updateComponentValue(current.filter((v) => v !== value), true, "remove", value);
     }
+    /**
+     * 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() {
+        this.updateComponentValue([], true, "clear", null);
+    }
     get value() {
         // Always read from DOM - tags with 'selected' attribute are source of truth
         return this.getSelectedValues().join(",");
@@ -1579,6 +1876,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");
     }
@@ -1610,6 +1913,18 @@ 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");
+    }
+    set flavor(value) {
+        this.setProperty("flavor", value);
+    }
     get form() {
         return this._internals.form;
     }
@@ -1679,12 +1994,40 @@ TySelect.properties = {
         visual: true,
         default: false,
     },
+    // Built-in × clear button in the default/compact trigger, shown once
+    // something is selected. Automatically absent under slot="trigger" —
+    // it lives in the slot's fallback content, same mechanism that already
+    // hides the chevron there. Default true matches ty-date-picker.
+    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,
+        default: "none",
+        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).
@@ -1700,12 +2043,29 @@ TySelect.properties = {
             return "auto";
         },
     },
+    // Horizontal anchor for the popup: "start" (default) matches the
+    // trigger's left edge, "end" matches its right edge — either way
+    // clamped into the viewport. Useful with slot="trigger" custom
+    // triggers whose own position makes left-anchoring look wrong (e.g.
+    // an icon button at the right edge of a toolbar).
+    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")
+                return "sm";
+            if (v === "xl")
+                return "lg";
             if (!["sm", "md", "lg"].includes(v)) {
                 console.warn(`[ty-select] Invalid size. Using md.`);
                 return "md";
@@ -1739,6 +2099,14 @@ 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")) {