tyrell-react 1.0.0-RC10

package/src/components/TyInput.tsx

@@ -0,0 +1,239 @@
+import React, { useEffect, useRef, useCallback } from 'react';
+import { needsPropertyBridge } from '../utils/react-version';
+import { useBooleanProperty } from '../utils/use-boolean-prop';
+
+// Event detail structure for ty-input events
+export interface TyInputEventDetail {
+  value: any; // shadow value (processed/parsed)
+  formattedValue: string; // user-visible formatted value
+  rawValue: string; // raw input value
+  originalEvent: Event; // original DOM event
+}
+
+export interface TyInputCSSProperties extends React.CSSProperties {
+  '--input-bg'?: string;
+  '--input-color'?: string;
+  '--input-border'?: string;
+  '--input-border-hover'?: string;
+  '--input-border-focus'?: string;
+  '--input-shadow-focus'?: string;
+  '--input-placeholder'?: string;
+  '--input-disabled-bg'?: string;
+  '--input-disabled-border'?: string;
+  '--input-disabled-color'?: string;
+}
+
+// Type definitions for Ty Input component
+export interface TyInputProps extends Omit<React.HTMLAttributes<HTMLElement>, 'onChange' | 'onFocus' | 'onBlur' | 'style'> {
+  style?: TyInputCSSProperties;
+  /** Input type */
+  type?: 'text' | 'email' | 'password' | 'number' | 'tel' | 'url' | 'search'
+  | 'currency' | 'percent' | 'compact';
+
+  /** Semantic styling variant */
+  flavor?: 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'neutral';
+
+  /** Input size */
+  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+  /** Input value */
+  value?: string;
+
+  /** Placeholder text */
+  placeholder?: string;
+
+  /** Input label */
+  label?: string;
+
+  /** Error message */
+  error?: string;
+
+  /** Disable the input */
+  disabled?: boolean;
+
+  /** Required field */
+  required?: boolean;
+
+  /** Form field name for form submission */
+  name?: string;
+
+  /** Checked state for checkbox inputs */
+  checked?: boolean;
+
+  // Numeric formatting props
+  currency?: string;
+  locale?: string;
+  precision?: string | number;
+
+  /** Debounce in milliseconds (0-5000) */
+  debounce?: number;
+
+  // React event handlers - override with our custom types
+  /**
+   * Fires on every keystroke (React convention)
+   * Maps to native 'input' event from ty-input
+   */
+  onChange?: (event: CustomEvent<TyInputEventDetail>) => void;
+
+  /**
+   * Fires on blur if value changed (native DOM behavior)
+   * Maps to native 'change' event from ty-input
+   */
+  onChangeCommit?: (event: CustomEvent<TyInputEventDetail>) => void;
+
+  /** Standard focus event */
+  onFocus?: (event: FocusEvent) => void;
+
+  /** Standard blur event */
+  onBlur?: (event: FocusEvent) => void;
+}
+
+// One-time global warning flags so we don't spam the console.
+let _warnedOnInputProp = false;
+
+// React wrapper for ty-input web component
+export const TyInput = React.forwardRef<HTMLElement, TyInputProps>(
+  ({ onChange, onChangeCommit, onFocus, onBlur, disabled, required, name, checked, debounce, ...props }, ref) => {
+    const elementRef = useRef<HTMLElement>(null);
+
+    // Catch the most common mistake: passing `onInput` (React's prop) instead
+    // of `onChange` (our wrapper's prop). React's synthetic-event system
+    // strips event.detail, so the user's handler crashes on `e.detail.value`.
+    // Forward to onChange and log a one-shot warning.
+    const onInputProp = (props as any).onInput as ((e: any) => void) | undefined;
+    if (onInputProp && !onChange) {
+      if (!_warnedOnInputProp) {
+        _warnedOnInputProp = true;
+        console.warn(
+          '[tyrell-react] <TyInput> received `onInput`. ' +
+          'React strips event.detail; use `onChange` instead — it receives the raw CustomEvent. ' +
+          'Forwarding for now, but please rename the prop.'
+        );
+      }
+      onChange = onInputProp;
+    }
+    // Either way, drop onInput from spread so React doesn't double-wire it.
+    delete (props as any).onInput;
+
+    // Map onChange to input event (React convention)
+    const handleInput = useCallback((event: CustomEvent<TyInputEventDetail>) => {
+      if (onChange) {
+        onChange(event);
+      }
+    }, [onChange]);
+
+    // Map onChangeCommit to change event (blur behavior)
+    const handleChangeCommit = useCallback((event: CustomEvent<TyInputEventDetail>) => {
+      if (onChangeCommit) {
+        onChangeCommit(event);
+      }
+    }, [onChangeCommit]);
+
+    const handleFocus = useCallback((event: FocusEvent) => {
+      if (onFocus) {
+        onFocus(event);
+      }
+    }, [onFocus]);
+
+    const handleBlur = useCallback((event: FocusEvent) => {
+      if (onBlur) {
+        onBlur(event);
+      }
+    }, [onBlur]);
+
+    useEffect(() => {
+      const element = elementRef.current;
+      if (!element) return;
+
+      // Listen for custom input/change events from ty-input
+      // Map onChange → input event (React convention)
+      if (onChange) {
+        element.addEventListener('input', handleInput as EventListener);
+      }
+
+      // Map onChangeCommit → change event (blur behavior)
+      if (onChangeCommit) {
+        element.addEventListener('change', handleChangeCommit as EventListener);
+      }
+
+      // Listen for standard focus/blur events
+      if (onFocus) {
+        element.addEventListener('focus', handleFocus as EventListener);
+      }
+
+      if (onBlur) {
+        element.addEventListener('blur', handleBlur as EventListener);
+      }
+
+      return () => {
+        if (onChange) {
+          element.removeEventListener('input', handleInput as EventListener);
+        }
+        if (onChangeCommit) {
+          element.removeEventListener('change', handleChangeCommit as EventListener);
+        }
+        if (onFocus) {
+          element.removeEventListener('focus', handleFocus as EventListener);
+        }
+        if (onBlur) {
+          element.removeEventListener('blur', handleBlur as EventListener);
+        }
+      };
+    }, [handleInput, handleChangeCommit, handleFocus, handleBlur, onChange, onChangeCommit, onFocus, onBlur]);
+
+    // Handle ref forwarding
+    useEffect(() => {
+      if (ref && elementRef.current) {
+        if (typeof ref === 'function') {
+          ref(elementRef.current);
+        } else {
+          ref.current = elementRef.current;
+        }
+      }
+    }, [ref]);
+
+    // Imperatively sync `value` to the underlying element's property whenever
+    // the React prop changes. React 18's prop-to-property bridging for custom
+    // elements is unreliable for empty strings, so we set the property directly
+    // to guarantee resets (`value=""`) clear the visible content. React 19+
+    // handles this natively, so the effect short-circuits there.
+    useEffect(() => {
+      if (!needsPropertyBridge) return;
+      const element = elementRef.current as any;
+      if (!element) return;
+      const next = (props as any).value ?? '';
+      if (element.value !== next) {
+        element.value = next;
+      }
+    }, [(props as any).value]);
+
+    // Imperative property sync for boolean props (see use-boolean-prop.ts).
+    const isDisabled = useBooleanProperty(elementRef, 'disabled', disabled);
+    const isRequired = useBooleanProperty(elementRef, 'required', required);
+    const isChecked = useBooleanProperty(elementRef, 'checked', checked);
+
+    // Convert React props to web component attributes
+    const webComponentProps: Record<string, any> = {
+      ...props,
+      ref: elementRef,
+    };
+
+    // Add conditional attributes
+    if (isDisabled) webComponentProps.disabled = '';
+    if (isRequired) webComponentProps.required = '';
+    if (isChecked) webComponentProps.checked = '';
+
+    // Add string attributes
+    if (name) webComponentProps.name = name;
+
+    // Add debounce attribute
+    if (debounce !== undefined) webComponentProps.debounce = debounce;
+
+    return React.createElement(
+      'ty-input',
+      webComponentProps
+    );
+  }
+);
+
+TyInput.displayName = 'TyInput';

package/src/components/TyModal.tsx

@@ -0,0 +1,195 @@
+import React, { useEffect, useRef, useImperativeHandle } from 'react';
+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;
+}
+
+/**
+ * Detail for the `beforeclose` event — fired *before* the modal closes,
+ * cancellable. Call `event.preventDefault()` to abort the close and render
+ * your own confirm UI; once the user consents, call `ref.current?.hide({ force: true })`
+ * to actually close (or just toggle your controlled `open` state to `false`).
+ */
+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;
+
+  /** Show backdrop behind modal (default: true) */
+  backdrop?: boolean;
+
+  /** Allow closing modal by clicking backdrop (default: true) */
+  closeOnOutsideClick?: boolean;
+
+  /** Allow closing modal with Escape key (default: true) */
+  closeOnEscape?: boolean;
+
+  /** React event handlers */
+  onOpen?: (event: CustomEvent<TyModalEventDetail>) => void;
+  onClose?: (event: CustomEvent<TyModalEventDetail>) => void;
+  /**
+   * Fires before the modal closes. Cancellable — call `event.preventDefault()`
+   * to abort. Use this for "discard changes?" flows with custom UI.
+   */
+  onBeforeClose?: (event: CustomEvent<TyModalBeforeCloseDetail>) => void;
+
+  /** Modal content */
+  children?: React.ReactNode;
+}
+
+// Ref interface for imperative methods
+export interface TyModalRef {
+  show: () => void;
+  /**
+   * Close the modal. Without `force`, fires `beforeclose` first (consumer can
+   * cancel). With `force: true`, bypasses `beforeclose` — call this once your
+   * custom confirm UI has captured user consent.
+   */
+  hide: (opts?: { force?: boolean }) => void;
+  element: HTMLElement | null;
+}
+
+// React wrapper for ty-modal web component
+export const TyModal = React.forwardRef<TyModalRef, TyModalProps>(
+  ({
+    open,
+    backdrop,
+    closeOnOutsideClick,
+    closeOnEscape,
+    onOpen,
+    onClose,
+    onBeforeClose,
+    children,
+    ...props
+  }, ref) => {
+    const elementRef = useRef<HTMLElement>(null);
+
+    // Expose imperative methods through ref
+    useImperativeHandle(ref, () => ({
+      show: () => {
+        if (elementRef.current && typeof (elementRef.current as any).show === 'function') {
+          (elementRef.current as any).show();
+        }
+      },
+      hide: (opts?: { force?: boolean }) => {
+        if (elementRef.current && typeof (elementRef.current as any).hide === 'function') {
+          (elementRef.current as any).hide(opts);
+        }
+      },
+      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.
+    useEffect(() => {
+      const element = elementRef.current;
+      if (!element) return;
+
+      const handleOpen = (event: CustomEvent<TyModalEventDetail>) => {
+        if (event.target !== element) return;
+        if (onOpen) onOpen(event);
+      };
+
+      const handleClose = (event: CustomEvent<TyModalEventDetail>) => {
+        if (event.target !== element) return;
+        if (onClose) onClose(event);
+      };
+
+      const handleBeforeClose = (event: CustomEvent<TyModalBeforeCloseDetail>) => {
+        if (event.target !== element) return;
+        if (onBeforeClose) onBeforeClose(event);
+      };
+
+      // Listen for custom modal events
+      if (onOpen) {
+        element.addEventListener('open', handleOpen as EventListener);
+      }
+
+      if (onClose) {
+        element.addEventListener('close', handleClose as EventListener);
+      }
+
+      if (onBeforeClose) {
+        element.addEventListener('beforeclose', handleBeforeClose as EventListener);
+      }
+
+      return () => {
+        if (onOpen) {
+          element.removeEventListener('open', handleOpen as EventListener);
+        }
+        if (onClose) {
+          element.removeEventListener('close', handleClose as EventListener);
+        }
+        if (onBeforeClose) {
+          element.removeEventListener('beforeclose', handleBeforeClose as EventListener);
+        }
+      };
+    }, [onOpen, onClose, onBeforeClose]);
+
+    // Imperative property sync for boolean props (see use-boolean-prop.ts).
+    // Without this, flipping `open` from `true` to `false` on React 18 leaves
+    // the `open` attribute on the element and the modal stays open.
+    const isOpen = useBooleanProperty(elementRef, 'open', open);
+
+    // For default-true booleans (backdrop, closeOn*), only the explicit-false
+    // case is interesting — bridge it imperatively too so it propagates.
+    useEffect(() => {
+      if (!needsPropertyBridge) return;
+      const el = elementRef.current as any;
+      if (!el) return;
+      const setIf = (prop: string, raw: unknown) => {
+        if (raw === undefined) return;
+        const next = coerceBool(raw);
+        if (Boolean(el[prop]) !== next) el[prop] = next;
+      };
+      setIf('backdrop', backdrop);
+      setIf('closeOnOutsideClick', closeOnOutsideClick);
+      setIf('closeOnEscape', closeOnEscape);
+    }, [backdrop, closeOnOutsideClick, closeOnEscape]);
+
+    // Convert React props to web component attributes
+    const webComponentProps: Record<string, any> = {
+      ...props,
+      ref: elementRef,
+    };
+
+    if (isOpen) webComponentProps.open = '';
+
+    // Default-true booleans use "false" string on the attribute side; the
+    // core's parseBoolAttr handles it correctly.
+    if (backdrop !== undefined && !coerceBool(backdrop)) {
+      webComponentProps.backdrop = 'false';
+    }
+    if (closeOnOutsideClick !== undefined && !coerceBool(closeOnOutsideClick)) {
+      webComponentProps['close-on-outside-click'] = 'false';
+    }
+    if (closeOnEscape !== undefined && !coerceBool(closeOnEscape)) {
+      webComponentProps['close-on-escape'] = 'false';
+    }
+
+    return React.createElement(
+      'ty-modal',
+      webComponentProps,
+      children
+    );
+  }
+);
+
+TyModal.displayName = 'TyModal';

package/src/components/TyMultiselect.tsx

@@ -0,0 +1,208 @@
+import React, { useEffect, useRef, useCallback } from 'react';
+import { needsPropertyBridge } from '../utils/react-version';
+import { useBooleanProperty } from '../utils/use-boolean-prop';
+
+// Type definitions for Ty Multiselect component
+export interface TyMultiselectEventDetail {
+  /** Array of currently selected values */
+  values: string[];
+  /** Action that triggered the change: "add" | "remove" */
+  action: 'add' | 'remove';
+  /** The specific item that was added or removed */
+  item: string;
+}
+
+export interface TyMultiselectProps extends Omit<React.HTMLAttributes<HTMLElement>, 'onChange' | 'style'> {
+  style?: import('./TyInput').TyInputCSSProperties;
+  /** Current selected values as comma-separated string or array */
+  value?: string | string[];
+  
+  /** Placeholder text when no items are selected */
+  placeholder?: string;
+  
+  /** Disable the multiselect component */
+  disabled?: boolean;
+
+  /**
+   * Loading state — replaces the available-options area with a centered
+   * spinner. Search input stays usable. Pair with `externalSearch` while
+   * fetching results from a parent-owned data source.
+   */
+  loading?: boolean;
+
+  /** Make the multiselect read-only */
+  readonly?: boolean;
+  
+  /** Semantic styling variant */
+  flavor?: 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'neutral';
+  
+  /** Label text for the multiselect */
+  label?: string;
+  
+  /** Mark the field as required */
+  required?: boolean;
+
+  /**
+   * Switch to external (remote) search mode. Default is `false` — the
+   * multiselect filters its own children client-side. Set to `true` when you
+   * want to handle filtering yourself (e.g. server-side): the component will
+   * dispatch `search` events on each keystroke, and you must update the children
+   * in response. The `onSearch` prop receives those events.
+   */
+  externalSearch?: boolean;
+
+  /** Debounce in milliseconds (0-5000) */
+  debounce?: number;
+  
+  /** Mobile section label for selected items */
+  selectedLabel?: string;
+  
+  /** Form field name for form submission */
+  name?: string;
+  
+  /** Callback when selection changes */
+  onChange?: (event: CustomEvent<TyMultiselectEventDetail>) => void;
+
+  /** Callback fired on each search input change (debounced by `debounce`). Use for external/server-side filtering. */
+  onSearch?: (event: CustomEvent<{ query: string; element: HTMLElement }>) => void;
+
+  /** Children should be TyTag components, not TyOption */
+  children?: React.ReactNode;
+}
+
+// React wrapper for ty-multiselect web component
+export const TyMultiselect = React.forwardRef<HTMLElement, TyMultiselectProps>(
+  ({
+    value,
+    placeholder,
+    disabled,
+    loading,
+    readonly,
+    flavor,
+    label,
+    required,
+    externalSearch,
+    debounce,
+    selectedLabel,
+    name,
+    onChange,
+    onSearch,
+    children,
+    ...props
+  }, ref) => {
+    const elementRef = useRef<HTMLElement>(null);
+
+    // Handle ref forwarding
+    useEffect(() => {
+      if (ref && elementRef.current) {
+        if (typeof ref === 'function') {
+          ref(elementRef.current);
+        } else {
+          ref.current = elementRef.current;
+        }
+      }
+    }, [ref]);
+
+    // Imperatively sync `value` to the underlying property so resets
+    // (`value=""` or null) reliably clear the visible selection.
+    // React 18 workaround; React 19+ handles this natively.
+    useEffect(() => {
+      if (!needsPropertyBridge) return;
+      const element = elementRef.current as any;
+      if (!element) return;
+      const next = (props as any).value ?? '';
+      if (element.value !== next) {
+        element.value = next;
+      }
+    }, [(props as any).value]);
+
+    // Handle change events
+    const handleChange = useCallback((event: Event) => {
+      const customEvent = event as CustomEvent<TyMultiselectEventDetail>;
+      if (onChange) {
+        onChange(customEvent);
+      }
+    }, [onChange]);
+
+    const handleSearch = useCallback((event: Event) => {
+      const customEvent = event as CustomEvent<{ query: string; element: HTMLElement }>;
+      if (onSearch) {
+        onSearch(customEvent);
+      }
+    }, [onSearch]);
+
+    // Set up event listeners
+    useEffect(() => {
+      const element = elementRef.current;
+      if (!element) return;
+
+      if (onChange) element.addEventListener('change', handleChange);
+      if (onSearch) element.addEventListener('search', handleSearch);
+
+      return () => {
+        if (onChange) element.removeEventListener('change', handleChange);
+        if (onSearch) element.removeEventListener('search', handleSearch);
+      };
+    }, [handleChange, handleSearch, onChange, onSearch]);
+
+    // Imperative property sync for boolean props (see use-boolean-prop.ts).
+    const isDisabled = useBooleanProperty(elementRef, 'disabled', disabled);
+    const isLoading = useBooleanProperty(elementRef, 'loading', loading);
+    const isReadonly = useBooleanProperty(elementRef, 'readonly', readonly);
+    const isRequired = useBooleanProperty(elementRef, 'required', required);
+    const isExternalSearch = useBooleanProperty(elementRef, 'externalSearch', externalSearch);
+
+    // Convert React props to web component attributes
+    const webComponentProps: Record<string, any> = {
+      ...props,
+      ref: elementRef,
+    };
+
+    // Handle value conversion (array to comma-separated string)
+    if (value !== undefined) {
+      const valueString = Array.isArray(value) ? value.join(',') : value;
+      webComponentProps.value = valueString;
+    }
+
+    // Add optional attributes only if they have values
+    if (placeholder) {
+      webComponentProps.placeholder = placeholder;
+    }
+
+    if (isLoading) webComponentProps.loading = '';
+    if (isDisabled) webComponentProps.disabled = '';
+    if (isReadonly) webComponentProps.readonly = '';
+    if (isRequired) webComponentProps.required = '';
+    if (isExternalSearch) webComponentProps['external-search'] = '';
+
+    if (flavor) {
+      webComponentProps.flavor = flavor;
+    }
+
+    if (label) {
+      webComponentProps.label = label;
+    }
+
+    if (name) {
+      webComponentProps.name = name;
+    }
+
+    // Add debounce attribute
+    if (debounce !== undefined) {
+      webComponentProps.debounce = debounce;
+    }
+    
+    // Add selectedLabel attribute
+    if (selectedLabel) {
+      webComponentProps['selected-label'] = selectedLabel;
+    }
+
+    return React.createElement(
+      'ty-multiselect',
+      webComponentProps,
+      children
+    );
+  }
+);
+
+TyMultiselect.displayName = 'TyMultiselect';

package/src/components/TyOption.tsx

@@ -0,0 +1,47 @@
+import React, { useEffect, useRef } from 'react';
+import { useBooleanProperty } from '../utils/use-boolean-prop';
+
+// Type definitions for Ty Option component
+export interface TyOptionProps extends React.HTMLAttributes<HTMLElement> {
+  value?: string;
+  disabled?: boolean;
+  selected?: boolean;
+  hidden?: boolean;
+  children?: React.ReactNode;
+}
+
+// React wrapper for ty-option web component
+export const TyOption = React.forwardRef<HTMLElement, TyOptionProps>(
+  ({ children, disabled, selected, hidden, ...props }, ref) => {
+    const elementRef = useRef<HTMLElement>(null);
+
+    // Handle ref forwarding
+    useEffect(() => {
+      if (ref && elementRef.current) {
+        if (typeof ref === 'function') {
+          ref(elementRef.current);
+        } else {
+          ref.current = elementRef.current;
+        }
+      }
+    }, [ref]);
+
+    const isDisabled = useBooleanProperty(elementRef, 'disabled', disabled);
+    const isSelected = useBooleanProperty(elementRef, 'selected', selected);
+    const isHidden = useBooleanProperty(elementRef, 'hidden', hidden);
+
+    return React.createElement(
+      'ty-option',
+      {
+        ...props,
+        ...(isDisabled && { disabled: "" }),
+        ...(isSelected && { selected: "" }),
+        ...(isHidden && { hidden: "" }),
+        ref: elementRef,
+      },
+      children
+    );
+  }
+);
+
+TyOption.displayName = 'TyOption';