@smilodon/core 1.1.9 → 1.2.1

package/dist/types/src/components/enhanced-select.d.ts

@@ -29,6 +29,7 @@ export declare class EnhancedSelect extends HTMLElement {
     private _errorMessage;
     private _boundArrowClick;
     private _arrowContainer?;
+    private _optionRenderer?;
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
@@ -43,6 +44,7 @@ export declare class EnhancedSelect extends HTMLElement {
     private _initializeStyles;
     private _attachEventListeners;
     private _initializeObservers;
+    private _initializeOptionRenderer;
     private _loadInitialSelectedItems;
     private _handleOpen;
     private _handleClose;

package/dist/types/src/components/native-select.d.ts

@@ -26,6 +26,25 @@ export declare class NativeSelectElement extends HTMLElement {
     get selectedItems(): unknown[];
     set optionTemplate(template: OptionTemplate | undefined);
     set optionRenderer(renderer: OptionRenderer | undefined);
+    /**
+     * Public API: setItems() method for compatibility with EnhancedSelect
+     * Accepts an array of items which can be:
+     * - Simple primitives (string, number)
+     * - Objects with {label, value} structure
+     * - Objects with {label, value, optionComponent} for custom rendering (v1.2.0+)
+     */
+    setItems(items: unknown[]): void;
+    /**
+     * Public API: setValue() method to programmatically select an item
+     * For single select: clears selection and selects the item matching the value
+     * For multi-select: adds to selection if not already selected
+     */
+    setValue(value: unknown): void;
+    /**
+     * Public API: getValue() method to get currently selected value(s)
+     * Returns single value for single-select, array for multi-select
+     */
+    getValue(): unknown | unknown[];
     render(): void;
     private _applyOptionAttrs;
     private _applyAriaToAll;

package/dist/types/src/index.d.ts

@@ -1,9 +1,9 @@
 export * from './types.js';
 export type { SelectEventDetail, OpenEventDetail, CloseEventDetail, SearchEventDetail, ChangeEventDetail, LoadMoreEventDetail, RemoveEventDetail, ErrorEventDetail, PageLoadedEventDetail, GroupedItem, RemoteConfig, Placement, Strategy, NativeSelectOptions, RendererHelpers, SelectEventsDetailMap, SelectEventName } from './types.js';
+export type { CustomOptionContract, CustomOptionContext, CustomOptionFactory, ExtendedSelectItem, OptionRendererMode, CustomOptionConfig, CustomOptionEvents } from './types/custom-option.js';
 export * from './renderers/contracts.js';
 export * from './components/native-select.js';
 export * from './components/enhanced-select.js';
-export { AngularEnhancedSelect } from './components/angular-enhanced-select.js';
 export * from './components/select-option.js';
 export * from './config/global-config.js';
 export { FenwickTree } from './utils/fenwick-tree.js';
@@ -11,6 +11,8 @@ export { DOMPool } from './utils/dom-pool.js';
 export { WorkerManager, getWorkerManager } from './utils/worker-manager.js';
 export { PerformanceTelemetry, getTelemetry, measureAsync, measureSync } from './utils/telemetry.js';
 export { Virtualizer } from './utils/virtualizer.js';
+export { OptionRenderer } from './utils/option-renderer.js';
+export { CustomOptionPool } from './utils/custom-option-pool.js';
 export { setHTMLSanitizer, getHTMLSanitizer, sanitizeHTML, createElement, setCSSProperties, CSPFeatures, detectEnvironment, containsSuspiciousPatterns, escapeHTML, escapeAttribute, validateTemplate, createTextNode, setTextContent } from './utils/security.js';
 export { applyClasses, toggleClass, setCustomProperties, getCustomProperty, removeCustomProperty, defaultTheme, applyDefaultTheme, shadowDOMStyles, injectShadowStyles, hasOverflowHiddenAncestor, warnCSPViolation } from './utils/csp-styles.js';
 export type { HTMLSanitizer, EnvironmentCapabilities } from './utils/security.js';

package/dist/types/src/types/custom-option.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Custom Option Rendering System
+ *
+ * This module provides types and contracts for rendering custom framework components
+ * as select options, enabling deep customization while maintaining performance and cohesion.
+ */
+/**
+ * Contract that custom option components must implement
+ *
+ * Custom components must expose these methods to integrate with the select system:
+ * - `mountOption()`: Called when the option is added to DOM
+ * - `unmountOption()`: Called when the option is removed from DOM
+ * - `updateSelected()`: Called when selection state changes
+ * - `getElement()`: Returns the root DOM element
+ */
+export interface CustomOptionContract {
+    /**
+     * Mount the component into the provided container
+     * @param container - The DOM element to mount into
+     * @param context - Context data including selection state and callbacks
+     */
+    mountOption(container: HTMLElement, context: CustomOptionContext): void;
+    /**
+     * Unmount and cleanup the component
+     */
+    unmountOption(): void;
+    /**
+     * Update the component when selection state changes
+     * @param selected - Whether this option is currently selected
+     */
+    updateSelected(selected: boolean): void;
+    /**
+     * Get the root DOM element of the component
+     * @returns The root element that receives click events
+     */
+    getElement(): HTMLElement;
+    /**
+     * Optional: Handle when the option becomes focused (keyboard navigation)
+     * @param focused - Whether this option has keyboard focus
+     */
+    updateFocused?(focused: boolean): void;
+    /**
+     * Optional: Handle when the option becomes disabled
+     * @param disabled - Whether this option is disabled
+     */
+    updateDisabled?(disabled: boolean): void;
+}
+/**
+ * Context provided to custom option components
+ */
+export interface CustomOptionContext {
+    /** The item data */
+    item: unknown;
+    /** The index of this option in the list */
+    index: number;
+    /** The value extracted from the item */
+    value: unknown;
+    /** The label extracted from the item */
+    label: string;
+    /** Whether this option is currently selected */
+    isSelected: boolean;
+    /** Whether this option currently has keyboard focus */
+    isFocused: boolean;
+    /** Whether the option is disabled */
+    isDisabled: boolean;
+    /** Callback to notify the select that this option was clicked */
+    onSelect: (index: number) => void;
+    /** Callback to notify custom events from the option */
+    onCustomEvent?: (eventName: string, data: unknown) => void;
+}
+/**
+ * Factory function signature for creating custom option instances
+ *
+ * @param item - The data item for this option
+ * @param index - The index in the list
+ * @returns A new instance implementing CustomOptionContract
+ */
+export type CustomOptionFactory = (item: unknown, index: number) => CustomOptionContract;
+/**
+ * Extended item type supporting custom components
+ *
+ * Items can now include:
+ * - Traditional: { label: string, value: any }
+ * - Custom Component: { label: string, value: any, optionComponent: CustomOptionFactory }
+ */
+export interface ExtendedSelectItem {
+    /** Display label (still required for accessibility and fallback) */
+    label: string;
+    /** Value used for selection */
+    value: unknown;
+    /** Optional: Custom component factory for rendering this option */
+    optionComponent?: CustomOptionFactory;
+    /** Optional: Whether this option is disabled */
+    disabled?: boolean;
+    /** Any additional data */
+    [key: string]: unknown;
+}
+/**
+ * Renderer mode for the select component
+ */
+export type OptionRendererMode = 'lightweight' | 'component';
+/**
+ * Configuration for custom option rendering
+ */
+export interface CustomOptionConfig {
+    /** Default renderer mode when no component specified */
+    defaultMode: OptionRendererMode;
+    /** Enable performance optimizations for component rendering */
+    enableVirtualization: boolean;
+    /** Recycle component instances when scrolling (for large lists) */
+    enableComponentRecycling: boolean;
+    /** Maximum component instances to keep in pool */
+    maxComponentPoolSize: number;
+}
+/**
+ * Events emitted by custom option components
+ */
+export interface CustomOptionEvents {
+    /** Custom component emitted an event */
+    'option:custom-event': {
+        index: number;
+        eventName: string;
+        data: unknown;
+    };
+    /** Component failed to mount */
+    'option:mount-error': {
+        index: number;
+        error: Error;
+    };
+    /** Component lifecycle event for debugging */
+    'option:lifecycle': {
+        index: number;
+        phase: 'mount' | 'unmount' | 'update';
+    };
+}

package/dist/types/src/utils/custom-option-pool.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Custom Option Component Pool
+ *
+ * Manages lifecycle and recycling of custom option components for optimal performance.
+ * Uses object pooling pattern to minimize allocation/deallocation overhead.
+ */
+import type { CustomOptionContract, CustomOptionContext, CustomOptionFactory } from '../types/custom-option';
+/**
+ * Manages a pool of reusable custom option component instances
+ */
+export declare class CustomOptionPool {
+    private _pool;
+    private _maxPoolSize;
+    private _activeComponents;
+    constructor(maxPoolSize?: number);
+    /**
+     * Get or create a component instance for the given index
+     *
+     * @param factory - Factory function to create new instances
+     * @param item - The data item
+     * @param index - The option index
+     * @param context - Context for mounting
+     * @param container - DOM container for mounting
+     * @returns Component instance
+     */
+    acquire(factory: CustomOptionFactory, item: unknown, index: number, context: CustomOptionContext, container: HTMLElement): CustomOptionContract;
+    /**
+     * Release a component back to the pool
+     *
+     * @param index - The index of the component to release
+     */
+    release(index: number): void;
+    /**
+     * Release all active components
+     */
+    releaseAll(): void;
+    /**
+     * Update selection state for a component
+     *
+     * @param index - The index of the component
+     * @param selected - Whether it's selected
+     */
+    updateSelection(index: number, selected: boolean): void;
+    /**
+     * Update focused state for a component
+     *
+     * @param index - The index of the component
+     * @param focused - Whether it has keyboard focus
+     */
+    updateFocused(index: number, focused: boolean): void;
+    /**
+     * Get active component at index
+     *
+     * @param index - The option index
+     * @returns The component instance or undefined
+     */
+    getComponent(index: number): CustomOptionContract | undefined;
+    /**
+     * Clear the entire pool
+     */
+    clear(): void;
+    /**
+     * Get pool statistics for debugging
+     */
+    getStats(): {
+        totalPooled: number;
+        activeComponents: number;
+        availableComponents: number;
+    };
+    /**
+     * Find an available component in the pool
+     */
+    private _findAvailableComponent;
+    /**
+     * Generate a unique key for a factory function
+     */
+    private _getFactoryKey;
+}

package/dist/types/src/utils/option-renderer.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Option Renderer
+ *
+ * Unified renderer that handles both lightweight (label/value) and
+ * custom component rendering with consistent performance characteristics.
+ */
+export interface OptionRendererConfig {
+    enableRecycling: boolean;
+    maxPoolSize: number;
+    getValue: (item: unknown) => unknown;
+    getLabel: (item: unknown) => string;
+    getDisabled?: (item: unknown) => boolean;
+    onSelect: (index: number) => void;
+    onCustomEvent?: (index: number, eventName: string, data: unknown) => void;
+    onError?: (index: number, error: Error) => void;
+}
+/**
+ * Manages rendering of both lightweight and custom component options
+ */
+export declare class OptionRenderer {
+    private _config;
+    private _pool;
+    private _mountedElements;
+    constructor(config: OptionRendererConfig);
+    /**
+     * Render an option (lightweight or custom component)
+     *
+     * @param item - The data item
+     * @param index - The option index
+     * @param isSelected - Whether the option is selected
+     * @param isFocused - Whether the option has keyboard focus
+     * @param uniqueId - Unique ID for the select instance
+     * @returns The rendered DOM element
+     */
+    render(item: unknown, index: number, isSelected: boolean, isFocused: boolean, uniqueId: string): HTMLElement;
+    /**
+     * Update selection state for an option
+     *
+     * @param index - The option index
+     * @param selected - Whether it's selected
+     */
+    updateSelection(index: number, selected: boolean): void;
+    /**
+     * Update focused state for an option
+     *
+     * @param index - The option index
+     * @param focused - Whether it has keyboard focus
+     */
+    updateFocused(index: number, focused: boolean): void;
+    /**
+     * Unmount and cleanup an option
+     *
+     * @param index - The option index
+     */
+    unmount(index: number): void;
+    /**
+     * Unmount all options
+     */
+    unmountAll(): void;
+    /**
+     * Get pool statistics
+     */
+    getStats(): {
+        totalPooled: number;
+        activeComponents: number;
+        availableComponents: number;
+    };
+    /**
+     * Render a lightweight option (traditional label/value)
+     */
+    private _renderLightweightOption;
+    /**
+     * Render a custom component option
+     */
+    private _renderCustomComponent;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smilodon/core",
-  "version": "1.1.9",
+  "version": "1.2.1",
   "description": "High-performance native select component with extreme-scale virtualization",
   "type": "module",
   "main": "./dist/index.cjs",