tyrell-react 1.0.0-RC12 → 1.0.0-RC14

package/src/components/TyModal.tsx

@@ -1,8 +1,8 @@
 import React, { useEffect, useRef, useImperativeHandle } from 'react';
+import { hostProps } from '../utils/host-props';
 import { useBooleanProperty, coerceBool } from '../utils/use-boolean-prop';
 import { needsPropertyBridge } from '../utils/react-version';
 
-// Event detail structure for modal events
 export interface TyModalEventDetail {
   reason?: 'programmatic' | 'native' | 'backdrop' | 'escape' | 'close-button';
   returnValue?: string;
@@ -18,7 +18,6 @@ export interface TyModalBeforeCloseDetail {
   reason: 'programmatic' | 'backdrop' | 'escape' | 'close-button' | 'native';
 }
 
-// Type definitions for Ty Modal component
 export interface TyModalProps extends React.HTMLAttributes<HTMLElement> {
   /** Controls modal visibility */
   open?: boolean;
@@ -26,12 +25,34 @@ export interface TyModalProps extends React.HTMLAttributes<HTMLElement> {
   /** Show backdrop behind modal (default: true) */
   backdrop?: boolean;
 
-  /** Allow closing modal by clicking backdrop (default: true) */
+  /**
+   * @deprecated Use `preventOutsideClick` — string-boolean attrs are being
+   * phased out. Still works; prevent-* wins when both are set.
+   */
   closeOnOutsideClick?: boolean;
 
-  /** Allow closing modal with Escape key (default: true) */
+  /**
+   * @deprecated Use `preventEscape` — string-boolean attrs are being phased
+   * out. Still works; prevent-* wins when both are set.
+   */
   closeOnEscape?: boolean;
 
+  /** Backdrop clicks no longer close the modal (also hides the built-in ✕) */
+  preventOutsideClick?: boolean;
+
+  /**
+   * ESC no longer closes the modal (keydown is consumed, so the browser's
+   * double-ESC anti-trap never fires). A fully guarded modal must render its
+   * own close control — WCAG 2.1.2.
+   */
+  preventEscape?: boolean;
+
+  /**
+   * Accessible name — sets aria-label on the internal <dialog>. The dialog
+   * gets role="dialog" for free, but nothing names it unless you set this.
+   */
+  label?: string;
+
   /** React event handlers */
   onOpen?: (event: CustomEvent<TyModalEventDetail>) => void;
   onClose?: (event: CustomEvent<TyModalEventDetail>) => void;
@@ -45,7 +66,6 @@ export interface TyModalProps extends React.HTMLAttributes<HTMLElement> {
   children?: React.ReactNode;
 }
 
-// Ref interface for imperative methods
 export interface TyModalRef {
   show: () => void;
   /**
@@ -57,13 +77,15 @@ export interface TyModalRef {
   element: HTMLElement | null;
 }
 
-// React wrapper for ty-modal web component
 export const TyModal = React.forwardRef<TyModalRef, TyModalProps>(
   ({
     open,
     backdrop,
     closeOnOutsideClick,
     closeOnEscape,
+    preventOutsideClick,
+    preventEscape,
+    label,
     onOpen,
     onClose,
     onBeforeClose,
@@ -72,7 +94,6 @@ export const TyModal = React.forwardRef<TyModalRef, TyModalProps>(
   }, ref) => {
     const elementRef = useRef<HTMLElement>(null);
 
-    // Expose imperative methods through ref
     useImperativeHandle(ref, () => ({
       show: () => {
         if (elementRef.current && typeof (elementRef.current as any).show === 'function') {
@@ -87,17 +108,12 @@ export const TyModal = React.forwardRef<TyModalRef, TyModalProps>(
       element: elementRef.current,
     }), []);
 
-    // Handle modal events.
-    //
-    // ty-dropdown, ty-multiselect, ty-date-picker etc. dispatch their own
-    // `open`/`close` custom events with `bubbles: true, composed: true` when
-    // their internal popups toggle. Those events bubble up through the
-    // modal's slotted content and land on the ty-modal host — same event
-    // type, same listener. Without the `event.target === element` guard, an
-    // `onClose={() => setIsOpen(false)}` callback would fire every time the
-    // user closes a dropdown inside the modal, and the React state flip
-    // would close the modal. Core's modal.ts already applies the same guard
-    // on its internal <dialog>.onclose; this is the React-layer mirror.
+    // Popup lifecycle events (`open`/`close`, plus `beforeclose` on the modal)
+    // no longer bubble — core dispatches them non-composed on the element
+    // itself, like the native <dialog> events they mirror, so a dropdown or
+    // nested modal closing inside this one can't reach these listeners. The
+    // `event.target === element` guard stays as belt-and-braces for consumers
+    // pinned to an older tyrell-components.
     useEffect(() => {
       const element = elementRef.current;
       if (!element) return;
@@ -117,7 +133,6 @@ export const TyModal = React.forwardRef<TyModalRef, TyModalProps>(
         if (onBeforeClose) onBeforeClose(event);
       };
 
-      // Listen for custom modal events
       if (onOpen) {
         element.addEventListener('open', handleOpen as EventListener);
       }
@@ -162,11 +177,12 @@ export const TyModal = React.forwardRef<TyModalRef, TyModalProps>(
       setIf('backdrop', backdrop);
       setIf('closeOnOutsideClick', closeOnOutsideClick);
       setIf('closeOnEscape', closeOnEscape);
-    }, [backdrop, closeOnOutsideClick, closeOnEscape]);
+      setIf('preventOutsideClick', preventOutsideClick);
+      setIf('preventEscape', preventEscape);
+    }, [backdrop, closeOnOutsideClick, closeOnEscape, preventOutsideClick, preventEscape]);
 
-    // Convert React props to web component attributes
     const webComponentProps: Record<string, any> = {
-      ...props,
+      ...hostProps(props),
       ref: elementRef,
     };
 
@@ -183,6 +199,14 @@ export const TyModal = React.forwardRef<TyModalRef, TyModalProps>(
     if (closeOnEscape !== undefined && !coerceBool(closeOnEscape)) {
       webComponentProps['close-on-escape'] = 'false';
     }
+    // Presence booleans: render the bare attribute only when true
+    if (preventOutsideClick !== undefined && coerceBool(preventOutsideClick)) {
+      webComponentProps['prevent-outside-click'] = '';
+    }
+    if (preventEscape !== undefined && coerceBool(preventEscape)) {
+      webComponentProps['prevent-escape'] = '';
+    }
+    if (label) webComponentProps.label = label;
 
     return React.createElement(
       'ty-modal',

package/src/components/TyOption.tsx

@@ -1,19 +1,19 @@
 import React, { useEffect, useRef } from 'react';
+import { hostProps } from '../utils/host-props';
 import { useBooleanProperty } from '../utils/use-boolean-prop';
 
-// Type definitions for Ty Option component
 export interface TyOptionProps extends React.HTMLAttributes<HTMLElement> {
   value?: string;
 
   /**
    * Clean display text (native <option label> semantics) — used by ty-select
-   * for field summaries and by ty-selected-tags chips when the option's
+   * for field summaries and by ty-selected-options chips when the option's
    * children are rich HTML. data-* attributes feed chip templates.
    */
   label?: string;
 
-  /** Semantic flavor — carried onto ty-selected-tags chips */
-  flavor?: 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'neutral' | 'info';
+  /** Semantic flavor — carried onto ty-selected-options chips */
+  flavor?: 'primary' | 'success' | 'danger' | 'warning' | 'neutral' | 'info';
 
   disabled?: boolean;
   selected?: boolean;
@@ -21,12 +21,10 @@ export interface TyOptionProps extends React.HTMLAttributes<HTMLElement> {
   children?: React.ReactNode;
 }
 
-// React wrapper for ty-option web component
 export const TyOption = React.forwardRef<HTMLElement, TyOptionProps>(
   ({ children, label, flavor, disabled, selected, hidden, ...props }, ref) => {
     const elementRef = useRef<HTMLElement>(null);
 
-    // Handle ref forwarding
     useEffect(() => {
       if (ref && elementRef.current) {
         if (typeof ref === 'function') {
@@ -44,7 +42,7 @@ export const TyOption = React.forwardRef<HTMLElement, TyOptionProps>(
     return React.createElement(
       'ty-option',
       {
-        ...props,
+        ...hostProps(props),
         ...(label && { label }),
         ...(flavor && { flavor }),
         ...(isDisabled && { disabled: "" }),

package/src/components/TyPopup.tsx

@@ -1,10 +1,16 @@
 import React, { useEffect, useRef } from 'react';
+import { hostProps } from '../utils/host-props';
 import { useBooleanProperty } from '../utils/use-boolean-prop';
 
-// Type definitions for Ty Popup component
+type Placement =
+  | 'top-start' | 'top' | 'top-end'
+  | 'right-start' | 'right' | 'right-end'
+  | 'bottom-start' | 'bottom' | 'bottom-end'
+  | 'left-start' | 'left' | 'left-end';
+
 export interface TyPopupProps extends Omit<React.HTMLAttributes<HTMLElement>, 'onClose'> {
-  /** Preferred placement of the popup relative to anchor parent: "top" | "bottom" | "left" | "right" */
-  placement?: 'top' | 'bottom' | 'left' | 'right';
+  /** Preferred placement of the popup relative to anchor parent: a side plus an optional cross-axis alignment (e.g. "bottom-start") */
+  placement?: Placement;
 
   /** Distance offset from the anchor in pixels (default: 8) */
   offset?: number;
@@ -25,14 +31,12 @@ export interface TyPopupProps extends Omit<React.HTMLAttributes<HTMLElement>, 'o
   children?: React.ReactNode;
 }
 
-// Programmatic API for popup control
 export interface TyPopupElement extends HTMLElement {
   openPopup(): void;
   closePopup(): void;
   togglePopup(): void;
 }
 
-// React wrapper for ty-popup web component
 export const TyPopup = React.forwardRef<TyPopupElement, TyPopupProps>(
   ({
     placement,
@@ -46,7 +50,6 @@ export const TyPopup = React.forwardRef<TyPopupElement, TyPopupProps>(
   }, ref) => {
     const elementRef = useRef<TyPopupElement>(null);
 
-    // Handle ref forwarding
     useEffect(() => {
       if (ref && elementRef.current) {
         if (typeof ref === 'function') {
@@ -57,11 +60,8 @@ export const TyPopup = React.forwardRef<TyPopupElement, TyPopupProps>(
       }
     }, [ref]);
 
-    // Listen for popup open/close events.
-    // Guard with `event.target === element` so bubbled open/close events
-    // from popup-like descendants (ty-dropdown, ty-multiselect, ty-date-picker
-    // when slotted inside this popup) don't fire the consumer's onOpen/onClose.
-    // See TyModal.tsx for the same pattern + rationale.
+    // Listen for popup open/close events. See TyModal.tsx for why the
+    // `event.target === element` guard is still here.
     useEffect(() => {
       const element = elementRef.current;
       if (!element) return;
@@ -84,13 +84,11 @@ export const TyPopup = React.forwardRef<TyPopupElement, TyPopupProps>(
       };
     }, [onOpen, onClose]);
 
-    // Convert React props to web component attributes
     const webComponentProps: Record<string, any> = {
-      ...props,
+      ...hostProps(props),
       ref: elementRef,
     };
 
-    // Add optional attributes only if they have values
     if (placement) {
       webComponentProps.placement = placement;
     }

package/src/components/TyRadio.tsx

@@ -1,6 +1,10 @@
 import React, { useEffect, useRef } from 'react';
+import { hostProps } from '../utils/host-props';
 import { useBooleanProperty } from '../utils/use-boolean-prop';
 
+type BuiltinFlavor = 'primary' | 'success' | 'danger' | 'warning' | 'neutral';
+type ShadedFlavor = BuiltinFlavor | `${BuiltinFlavor}+` | `${BuiltinFlavor}-`;
+
 export interface TyRadioProps extends React.HTMLAttributes<HTMLElement> {
   /** Form field value (selected by parent ty-radio-group when matches its `value`) */
   value?: string;
@@ -18,7 +22,7 @@ export interface TyRadioProps extends React.HTMLAttributes<HTMLElement> {
   size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
 
   /** Semantic styling variant — typically inherited from the parent group */
-  flavor?: 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'neutral';
+  flavor?: ShadedFlavor | (string & {});
 
   /** Label content (wrap in a `<label>` for click delegation, see ty-radio docs) */
   children?: React.ReactNode;
@@ -43,7 +47,7 @@ export const TyRadio = React.forwardRef<HTMLElement, TyRadioProps>(
     const isDisabled = useBooleanProperty(elementRef, 'disabled', disabled);
 
     const webComponentProps: Record<string, any> = {
-      ...props,
+      ...hostProps(props),
       ref: elementRef,
     };
 

package/src/components/TyRadioGroup.tsx

@@ -1,6 +1,10 @@
 import React, { useEffect, useRef } from 'react';
+import { hostProps } from '../utils/host-props';
 import { useBooleanProperty } from '../utils/use-boolean-prop';
 
+type BuiltinFlavor = 'primary' | 'success' | 'danger' | 'warning' | 'neutral';
+type ShadedFlavor = BuiltinFlavor | `${BuiltinFlavor}+` | `${BuiltinFlavor}-`;
+
 export interface TyRadioGroupProps extends Omit<React.HTMLAttributes<HTMLElement>, 'onChange' | 'onInput'> {
   /** Currently selected value (matches one child `<TyRadio value="...">`) */
   value?: string;
@@ -27,7 +31,7 @@ export interface TyRadioGroupProps extends Omit<React.HTMLAttributes<HTMLElement
   size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
 
   /** Group flavor — propagates to all `<TyRadio>` children */
-  flavor?: 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'neutral';
+  flavor?: ShadedFlavor | (string & {});
 
   /**
    * Fires when selection changes (React convention)
@@ -103,7 +107,7 @@ export const TyRadioGroup = React.forwardRef<HTMLElement, TyRadioGroupProps>(
     const isRequired = useBooleanProperty(elementRef, 'required', required);
 
     const webComponentProps: Record<string, any> = {
-      ...props,
+      ...hostProps(props),
       ref: elementRef,
     };
 

package/src/components/TyResizeObserver.tsx

@@ -1,6 +1,6 @@
 import React, { useEffect, useRef } from 'react';
+import { hostProps } from '../utils/host-props';
 
-// Type definitions for Ty ResizeObserver component
 export interface TyResizeObserverProps extends React.HTMLAttributes<HTMLElement> {
   /** Required unique identifier for size registry */
   id: string;
@@ -12,7 +12,6 @@ export interface TyResizeObserverProps extends React.HTMLAttributes<HTMLElement>
   children?: React.ReactNode;
 }
 
-// React wrapper for ty-resize-observer web component
 export const TyResizeObserver = React.forwardRef<HTMLElement, TyResizeObserverProps>(
   ({
     children,
@@ -22,7 +21,6 @@ export const TyResizeObserver = React.forwardRef<HTMLElement, TyResizeObserverPr
   }, ref) => {
     const elementRef = useRef<HTMLElement>(null);
 
-    // Combine refs if needed
     useEffect(() => {
       if (ref && elementRef.current) {
         if (typeof ref === 'function') {
@@ -33,14 +31,12 @@ export const TyResizeObserver = React.forwardRef<HTMLElement, TyResizeObserverPr
       }
     }, [ref]);
 
-    // Convert React props to web component attributes
     const webComponentProps: Record<string, any> = {
-      ...props,
+      ...hostProps(props),
       ref: elementRef,
       id,
     };
 
-    // Add number attributes
     if (debounce !== undefined) webComponentProps.debounce = debounce;
 
     return React.createElement(

package/src/components/TyScrollContainer.tsx

@@ -1,4 +1,5 @@
 import React, { useEffect, useRef, useImperativeHandle } from 'react';
+import { hostProps } from '../utils/host-props';
 import { needsPropertyBridge } from '../utils/react-version';
 import { useBooleanProperty, coerceBool } from '../utils/use-boolean-prop';
 
@@ -10,7 +11,6 @@ export interface TyScrollNearEdgeDetail {
   clientHeight: number;
 }
 
-// Type definitions for Ty ScrollContainer component
 export interface TyScrollContainerProps extends React.HTMLAttributes<HTMLElement> {
   /** Maximum height of the scroll container */
   maxHeight?: string;
@@ -43,7 +43,6 @@ export interface TyScrollContainerProps extends React.HTMLAttributes<HTMLElement
   children?: React.ReactNode;
 }
 
-// Ref interface for imperative methods
 export interface TyScrollContainerRef {
   /** Force update shadows (useful after dynamic content changes) */
   updateShadows: () => void;
@@ -63,7 +62,6 @@ export interface TyScrollContainerRef {
   element: HTMLElement | null;
 }
 
-// React wrapper for ty-scroll-container web component
 export const TyScrollContainer = React.forwardRef<TyScrollContainerRef, TyScrollContainerProps>(
   ({
     children,
@@ -80,7 +78,6 @@ export const TyScrollContainer = React.forwardRef<TyScrollContainerRef, TyScroll
   }, ref) => {
     const elementRef = useRef<HTMLElement>(null);
 
-    // Expose imperative methods via ref
     useImperativeHandle(ref, () => ({
       updateShadows: () => { (elementRef.current as any)?.updateShadows?.(); },
       scrollToTop: (smooth = true) => { (elementRef.current as any)?.scrollToTop?.(smooth); },
@@ -108,7 +105,6 @@ export const TyScrollContainer = React.forwardRef<TyScrollContainerRef, TyScroll
     const isOverflowX = useBooleanProperty(elementRef, 'overflowX', overflowX);
     const isScrollAnchoring = useBooleanProperty(elementRef, 'scrollAnchoring', scrollAnchoring);
 
-    // Custom events → React callbacks
     useEffect(() => {
       const el = elementRef.current;
       if (!el) return;
@@ -124,17 +120,14 @@ export const TyScrollContainer = React.forwardRef<TyScrollContainerRef, TyScroll
       return () => bound.forEach(([n, h]) => el.removeEventListener(n, h));
     }, [onNearEnd, onNearStart]);
 
-    // Convert React props to web component attributes
     const webComponentProps: Record<string, any> = {
-      ...props,
+      ...hostProps(props),
       ref: elementRef,
     };
 
-    // String attributes
     if (maxHeight) webComponentProps['max-height'] = maxHeight;
     if (nearEdgeThreshold != null) webComponentProps['near-edge-threshold'] = String(nearEdgeThreshold);
 
-    // Boolean attributes
     if (shadow !== undefined && !coerceBool(shadow)) webComponentProps.shadow = 'false';
     if (isHideScrollbar) webComponentProps['hide-scrollbar'] = '';
     if (isCustomScrollbar) webComponentProps['custom-scrollbar'] = '';

package/src/components/TySelect.tsx

@@ -1,8 +1,16 @@
 import React, { useEffect, useRef, useCallback } from 'react';
+import { hostProps } from '../utils/host-props';
 import { needsPropertyBridge } from '../utils/react-version';
 import { useBooleanProperty } from '../utils/use-boolean-prop';
 
-// Type definitions for Ty Select component
+type BuiltinFlavor = 'primary' | 'success' | 'danger' | 'warning' | 'neutral';
+type ShadedFlavor = BuiltinFlavor | `${BuiltinFlavor}+` | `${BuiltinFlavor}-`;
+type Placement =
+  | 'top-start' | 'top' | 'top-end'
+  | 'right-start' | 'right' | 'right-end'
+  | 'bottom-start' | 'bottom' | 'bottom-end'
+  | 'left-start' | 'left' | 'left-end';
+
 export interface TySelectItem {
   value: string;
   label: string;
@@ -17,7 +25,7 @@ export interface TySelectEventDetail {
   /** Rich info per selected value — enough to render chips out-of-band */
   items: TySelectItem[];
   /** Action that triggered the change */
-  action: 'add' | 'remove' | 'clear' | 'set';
+  action: 'add' | 'remove' | 'clear' | 'set' | 'create';
   /** The specific value that changed */
   item: string | null;
 }
@@ -67,12 +75,40 @@ export interface TySelectProps extends Omit<React.HTMLAttributes<HTMLElement>, '
   /** Debounce for the search event in ms (0-5000) */
   debounce?: number;
 
+  /**
+   * Enter on unmatched search text mints a new <ty-option> (forces the
+   * search row on, same as externalSearch). Listen to onCreate to mutate
+   * the value before it's created, or preventDefault() to take over
+   * entirely (e.g. after a server round-trip).
+   */
+  allowCreate?: boolean;
+
+  /**
+   * Opt-in normalizer for the value allowCreate mints — the display label
+   * is always kept verbatim. 'slug': lowercase, spaces → '_', strips
+   * everything else non-alphanumeric. Default: value === typed text.
+   */
+  createTransform?: 'slug';
+
   /** Loading state — shows a spinner in the options area (external search in flight) */
   loading?: boolean;
 
   /** Size variant */
+  /** Field size — fields come in exactly three; legacy xs/xl map to sm/lg */
   size?: 'sm' | 'md' | 'lg';
 
+  /** Horizontal popup anchor: "start" (default, trigger's left edge), "center", or "end" (trigger's right edge) — clamped into the viewport either way. Useful with a custom slot="trigger" element. Ignored when `placement` is set. */
+  align?: 'start' | 'center' | 'end';
+
+  /** Full placement, same vocabulary as ty-popup/ty-tooltip: a side plus an optional cross-axis alignment (e.g. "bottom-end"). Takes precedence over `align` when set. */
+  placement?: Placement;
+
+  /** Built-in x clear button in the default/compact trigger, shown once something is selected. Default true. Not shown with slot="trigger" — use the ref's clear() method there instead. */
+  clearable?: boolean;
+
+  /** Visual flavor for the field border — built-in semantic, +/- shade, or a custom flavor backed by --ty-*-X tokens */
+  flavor?: ShadedFlavor | (string & {});
+
   /** Callback when selection changes */
   onChange?: (event: CustomEvent<TySelectEventDetail>) => void;
 
@@ -81,12 +117,23 @@ export interface TySelectProps extends Omit<React.HTMLAttributes<HTMLElement>, '
   onOpen?: (event: CustomEvent) => void;
   onClose?: (event: CustomEvent) => void;
 
+  /**
+   * Fired before allowCreate mints a new option — cancelable. Mutate
+   * `event.detail.value` to change the id that gets created (e.g. slugify
+   * it yourself), or call `event.preventDefault()` to create it yourself.
+   */
+  onCreate?: (event: CustomEvent<{ value: string; label: string }>) => void;
+
   /** TyOption children (plus optional slot="trigger" / slot="start" / slot="end" elements) */
   children?: React.ReactNode;
 }
 
-// React wrapper for ty-select web component
-export const TySelect = React.forwardRef<HTMLElement, TySelectProps>(
+/** The underlying custom element, typed with its imperative clear() method — useful with a ref, e.g. for slot="trigger" custom triggers that call it directly instead of relying on the built-in clear button. */
+export interface TySelectElement extends HTMLElement {
+  clear(): void;
+}
+
+export const TySelect = React.forwardRef<TySelectElement, TySelectProps>(
   ({
     value,
     multiple,
@@ -100,18 +147,24 @@ export const TySelect = React.forwardRef<HTMLElement, TySelectProps>(
     searchable,
     externalSearch,
     debounce,
+    allowCreate,
+    createTransform,
     loading,
     size,
+    align,
+    placement,
+    clearable,
+    flavor,
     onChange,
     onSearch,
     onOpen,
     onClose,
+    onCreate,
     children,
     ...props
   }, ref) => {
-    const elementRef = useRef<HTMLElement>(null);
+    const elementRef = useRef<TySelectElement>(null);
 
-    // Handle ref forwarding
     useEffect(() => {
       if (ref && elementRef.current) {
         if (typeof ref === 'function') {
@@ -134,7 +187,6 @@ export const TySelect = React.forwardRef<HTMLElement, TySelectProps>(
       }
     }, [value]);
 
-    // Handle events
     const handleChange = useCallback((event: Event) => {
       if (onChange) onChange(event as CustomEvent<TySelectEventDetail>);
     }, [onChange]);
@@ -145,8 +197,10 @@ export const TySelect = React.forwardRef<HTMLElement, TySelectProps>(
 
     const handleOpen = useCallback((event: Event) => { if (onOpen) onOpen(event as CustomEvent); }, [onOpen]);
     const handleClose = useCallback((event: Event) => { if (onClose) onClose(event as CustomEvent); }, [onClose]);
+    const handleCreate = useCallback((event: Event) => {
+      if (onCreate) onCreate(event as CustomEvent<{ value: string; label: string }>);
+    }, [onCreate]);
 
-    // Set up event listeners
     useEffect(() => {
       const element = elementRef.current;
       if (!element) return;
@@ -155,14 +209,16 @@ export const TySelect = React.forwardRef<HTMLElement, TySelectProps>(
       if (onSearch) element.addEventListener('search', handleSearch);
       if (onOpen) element.addEventListener('open', handleOpen);
       if (onClose) element.addEventListener('close', handleClose);
+      if (onCreate) element.addEventListener('create', handleCreate);
 
       return () => {
         if (onChange) element.removeEventListener('change', handleChange);
         if (onSearch) element.removeEventListener('search', handleSearch);
         if (onOpen) element.removeEventListener('open', handleOpen);
         if (onClose) element.removeEventListener('close', handleClose);
+        if (onCreate) element.removeEventListener('create', handleCreate);
       };
-    }, [handleChange, handleSearch, handleOpen, handleClose, onChange, onSearch, onOpen, onClose]);
+    }, [handleChange, handleSearch, handleOpen, handleClose, handleCreate, onChange, onSearch, onOpen, onClose, onCreate]);
 
     // Imperative property sync for boolean props (see use-boolean-prop.ts).
     const isMultiple = useBooleanProperty(elementRef, 'multiple', multiple);
@@ -172,14 +228,14 @@ export const TySelect = React.forwardRef<HTMLElement, TySelectProps>(
     const isRequired = useBooleanProperty(elementRef, 'required', required);
     const isLoading = useBooleanProperty(elementRef, 'loading', loading);
     const isExternalSearch = useBooleanProperty(elementRef, 'externalSearch', externalSearch);
+    const isAllowCreate = useBooleanProperty(elementRef, 'allowCreate', allowCreate);
+    const isClearable = useBooleanProperty(elementRef, 'clearable', clearable);
 
-    // Convert React props to web component attributes
     const webComponentProps: Record<string, any> = {
-      ...props,
+      ...hostProps(props),
       ref: elementRef,
     };
 
-    // Handle value conversion (array to comma-separated string)
     if (value !== undefined) {
       webComponentProps.value = Array.isArray(value) ? value.join(',') : value;
     }
@@ -191,12 +247,18 @@ export const TySelect = React.forwardRef<HTMLElement, TySelectProps>(
     if (isRequired) webComponentProps.required = '';
     if (isLoading) webComponentProps.loading = '';
     if (isExternalSearch) webComponentProps['external-search'] = '';
+    if (isAllowCreate) webComponentProps['allow-create'] = '';
 
     if (placeholder) webComponentProps.placeholder = placeholder;
     if (label) webComponentProps.label = label;
     if (name) webComponentProps.name = name;
     if (size) webComponentProps.size = size;
+    if (align) webComponentProps.align = align;
+    if (placement) webComponentProps.placement = placement;
+    if (isClearable) webComponentProps.clearable = '';
+    if (flavor) webComponentProps.flavor = flavor;
     if (debounce !== undefined) webComponentProps.debounce = debounce.toString();
+    if (createTransform) webComponentProps['create-transform'] = createTransform;
     if (searchable === 'always' || searchable === true) webComponentProps.searchable = 'true';
     else if (searchable === 'never' || searchable === false) webComponentProps.searchable = 'false';
     // 'auto' / undefined → omit (component default)
@@ -207,9 +269,9 @@ export const TySelect = React.forwardRef<HTMLElement, TySelectProps>(
 
 TySelect.displayName = 'TySelect';
 
-// ============================================================================
-// TySelectedTags — out-of-band chip display for a TySelect
-// ============================================================================
+// TySelectedOptions — out-of-band chip display for a TySelect
+// (ty-selected-tags below is the same element under its original tag name,
+// kept for backward compatibility.)
 
 export interface TySelectedTagsProps extends React.HTMLAttributes<HTMLElement> {
   /** id of the ty-select to display. Falls back to the previous element sibling. */
@@ -218,9 +280,8 @@ export interface TySelectedTagsProps extends React.HTMLAttributes<HTMLElement> {
   children?: React.ReactNode;
 }
 
-// React wrapper for ty-selected-tags web component
-export const TySelectedTags = React.forwardRef<HTMLElement, TySelectedTagsProps>(
-  ({ htmlFor, children, ...props }, ref) => {
+const selectedChipsComponent = (tag: 'ty-selected-options' | 'ty-selected-tags') =>
+  React.forwardRef<HTMLElement, TySelectedTagsProps>(({ htmlFor, children, ...props }, ref) => {
     const elementRef = useRef<HTMLElement>(null);
 
     useEffect(() => {
@@ -230,11 +291,16 @@ export const TySelectedTags = React.forwardRef<HTMLElement, TySelectedTagsProps>
       }
     }, [ref]);
 
-    const webComponentProps: Record<string, any> = { ...props, ref: elementRef };
+    const webComponentProps: Record<string, any> = { ...hostProps(props), ref: elementRef };
     if (htmlFor) webComponentProps.for = htmlFor;
 
-    return React.createElement('ty-selected-tags', webComponentProps, children);
-  }
-);
+    return React.createElement(tag, webComponentProps, children);
+  });
+
+/** React wrapper for the ty-selected-options web component. */
+export const TySelectedOptions = selectedChipsComponent('ty-selected-options');
+TySelectedOptions.displayName = 'TySelectedOptions';
 
+/** @deprecated Use `TySelectedOptions` — kept for backward compatibility. */
+export const TySelectedTags = selectedChipsComponent('ty-selected-tags');
 TySelectedTags.displayName = 'TySelectedTags';