@spaethtech/svelte-ui 0.1.10

package/dist/components/List/List.svelte

@@ -0,0 +1,580 @@
+<script lang="ts">
+  import { untrack } from 'svelte';
+  import type { Snippet } from 'svelte';
+
+  type Option = Record<string, any> & {
+    value: string;
+    label: string;
+  };
+
+  interface Props {
+    options: Option[];
+    value?: string | string[]; // Bindable selected value - string[] when multiSelect is true
+    multiSelect?: boolean; // Enable multi-select mode
+    showCheckboxes?: boolean; // Show checkboxes for selection (implies multiSelect)
+    maxVisibleItems?: number; // When not set, grows to fit all items
+    itemHeight?: number;
+    minHeight?: number; // Minimum height in pixels (default 32px)
+    class?: string;
+    dropdownClass?: string;
+    itemClass?: string;
+    itemSnippet?: Snippet<[Option, number, boolean, boolean]>; // option, index, isSelected, isFocused
+    disabled?: boolean;
+    // API integration
+    url?: string;
+    searchParam?: string;
+    transform?: (apiResponse: any) => Option[];
+    debounceMs?: number;
+    maxResults?: number;
+    headers?: Record<string, string>;
+    searchTerm?: string;
+    showLoading?: boolean;
+    loadingText?: string;
+    showError?: boolean;
+    errorText?: string;
+    emptyText?: string;
+    onError?: (error: Error) => void;
+    onLoadStart?: () => void;
+    onLoadEnd?: () => void;
+    onSelection?: (option: Option) => void;
+  }
+
+  let {
+    options = [],
+    value = $bindable(),
+    multiSelect = false,
+    showCheckboxes = false,
+    maxVisibleItems, // Optional - when not set, grows to fit all items
+    itemHeight = 28, // Default: var(--ui-height) - (var(--ui-border) * 2) = 32px - 4px = 28px
+    minHeight = 32, // Should match var(--ui-height) for standard UI element height
+    class: className = "",
+    dropdownClass = "",
+    itemClass = "",
+    itemSnippet,
+    disabled = false,
+    // API integration props
+    url,
+    searchParam,
+    transform,
+    debounceMs = 300,
+    maxResults,
+    headers = {},
+    searchTerm = $bindable(""),
+    showLoading = true,
+    loadingText = "Loading...",
+    showError = true,
+    errorText = "Failed to load data",
+    emptyText = "No data",
+    onError,
+    onLoadStart,
+    onLoadEnd,
+    onSelection
+  }: Props = $props();
+
+  // showCheckboxes implies multiSelect
+  const effectiveMultiSelect = multiSelect || showCheckboxes;
+  
+  // Initialize value based on multiSelect mode
+  if (value === undefined) {
+    value = effectiveMultiSelect ? [] : "";
+  }
+
+  // Helper functions for multi-select
+  function isSelected(optionValue: string): boolean {
+    if (effectiveMultiSelect) {
+      return Array.isArray(value) && value.includes(optionValue);
+    }
+    return value === optionValue;
+  }
+
+  function toggleSelection(optionValue: string) {
+    if (effectiveMultiSelect && Array.isArray(value)) {
+      if (value.includes(optionValue)) {
+        value = value.filter(v => v !== optionValue);
+      } else {
+        value = [...value, optionValue];
+      }
+    } else {
+      value = optionValue;
+    }
+  }
+
+  // API integration state
+  let isLoading = $state(false);
+  let hasError = $state(false);
+  let currentError = $state<Error | null>(null);
+  let apiOptions = $state<Option[]>([]);
+  let lastSearchTerm = $state("");
+  let abortController = $state<AbortController | null>(null);
+
+  // Combine static options with API options
+  const allOptions = $derived(() => {
+    if (url && apiOptions.length > 0) {
+      // When using API, prioritize API results
+      return apiOptions;
+    }
+    // Use static options (default behavior)
+    return options;
+  });
+
+  // Get actual item heights from DOM elements when using custom snippets
+  const getActualItemHeight = $derived(() => {
+    if (itemSnippet && itemElements.length > 0) {
+      // Use the actual height of the first rendered item
+      const firstItem = itemElements[0];
+      return firstItem ? firstItem.offsetHeight : itemHeight;
+    }
+    return itemHeight;
+  });
+
+  // Calculate height - grows to fit all items when maxVisibleItems is not set
+  // Always respects minHeight (32px standard)
+  const maxHeight = $derived(() => {
+    const options = allOptions();
+    const actualItemHeight = getActualItemHeight();
+    let calculatedHeight;
+    
+    // Account for border: var(--ui-border) * 2 for normal state, 1px * 2 for disabled
+    const borderOffset = disabled ? 2 : 4; // TODO: Use CSS var(--ui-border) when possible
+    
+    if (maxVisibleItems !== undefined) {
+      // Fixed height mode - use maxVisibleItems
+      calculatedHeight = Math.min(options.length, maxVisibleItems) * actualItemHeight + borderOffset;
+    } else {
+      // Auto-grow mode - fit all items
+      calculatedHeight = options.length * actualItemHeight + borderOffset;
+    }
+    
+    // Ensure minimum height is respected
+    return Math.max(calculatedHeight, minHeight);
+  });
+
+  let listElement = $state<HTMLDivElement>();
+  let scrollThumb = $state<HTMLDivElement>();
+  let isDragging = $state(false);
+  let dragStartY = $state(0);
+  let dragStartScrollTop = $state(0);
+  let scrollTop = $state(0);
+  let thumbTop = $state(0);
+  let thumbHeight = $state(20);
+  let focusedIndex = $state(-1);
+  let keyboardCursor = $state(-1); // Tracks last interaction position for keyboard navigation
+  let itemElements = $state<HTMLElement[]>([]);
+
+  function selectOption(optionValue: string, event: MouseEvent) {
+    if (disabled) return;
+    
+    event.stopPropagation();
+    
+    // Update keyboard cursor to the clicked item
+    const clickedIndex = allOptions().findIndex(option => option.value === optionValue);
+    if (clickedIndex >= 0) {
+      keyboardCursor = clickedIndex;
+    }
+    
+    // Update bindable value
+    toggleSelection(optionValue);
+    
+    // Call onSelection callback with the full option object
+    const selectedOption = allOptions().find(option => option.value === optionValue);
+    if (selectedOption && onSelection) {
+      onSelection(selectedOption);
+    }
+  }
+  
+  // Handle list focus - restore keyboard cursor position and scroll into view
+  function handleListFocus() {
+    // Set keyboard cursor to first item if none exists and options are available
+    if (keyboardCursor < 0 && allOptions().length > 0) {
+      keyboardCursor = 0;
+    }
+    
+    // If we have a keyboard cursor position, restore focus highlighting and scroll into view
+    if (keyboardCursor >= 0) {
+      focusedIndex = keyboardCursor;
+      
+      // Scroll into view if the list is scrollable
+      if (listElement) {
+        const actualItemHeight = getActualItemHeight();
+        const itemTop = keyboardCursor * actualItemHeight;
+        const itemBottom = itemTop + actualItemHeight;
+        const viewTop = listElement.scrollTop;
+        const currentMaxHeight = maxHeight();
+        const viewBottom = viewTop + currentMaxHeight;
+        
+        if (itemTop < viewTop || itemBottom > viewBottom) {
+          // Keyboard cursor is not visible, scroll it into view
+          listElement.scrollTop = Math.max(0, itemTop - (currentMaxHeight - actualItemHeight) / 2);
+        }
+      }
+    } else {
+      // No options available, reset focused index
+      focusedIndex = -1;
+    }
+  }
+  
+  // Handle list blur - reset focused index
+  function handleListBlur() {
+    focusedIndex = -1;
+  }
+  
+  // API fetch function
+  async function fetchOptions(searchQuery: string) {
+    if (!url) {
+      apiOptions = [];
+      return;
+    }
+
+    // If no searchParam is provided, fetch all data (ignore searchQuery)
+    // If searchParam is provided but searchQuery is empty, clear results
+    if (searchParam && !searchQuery.trim()) {
+      apiOptions = [];
+      return;
+    }
+
+    // Cancel previous request
+    if (abortController) {
+      abortController.abort();
+    }
+    
+    abortController = new AbortController();
+    
+    try {
+      isLoading = true;
+      onLoadStart?.();
+      
+      // Build URL with optional search parameter
+      const apiUrl = new URL(url, window.location.origin);
+      if (searchParam && searchQuery.trim()) {
+        apiUrl.searchParams.set(searchParam, searchQuery);
+      }
+      
+      const response = await fetch(apiUrl.toString(), {
+        signal: abortController.signal,
+        headers: {
+          'Content-Type': 'application/json',
+          ...headers
+        }
+      });
+      
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+      
+      const data = await response.json();
+      
+      // Transform the response using provided transform function
+      let transformedOptions = transform ? transform(data) : data;
+      
+      // Apply maxResults limit if specified
+      if (maxResults && transformedOptions.length > maxResults) {
+        transformedOptions = transformedOptions.slice(0, maxResults);
+      }
+      
+      apiOptions = transformedOptions;
+      lastSearchTerm = searchQuery;
+      
+    } catch (error) {
+      if (error instanceof Error && error.name !== 'AbortError') {
+        console.error('List API fetch error:', error);
+        hasError = true;
+        currentError = error;
+        onError?.(error);
+        apiOptions = [];
+      }
+    } finally {
+      isLoading = false;
+      onLoadEnd?.();
+      abortController = null;
+    }
+  }
+
+  // API fetch effect for search functionality
+  $effect(() => {
+    if (url && searchParam) {
+      // If searchParam is provided, use debounced search
+      if (searchTerm.trim() && searchTerm !== lastSearchTerm) {
+        const timeoutId = setTimeout(() => {
+          fetchOptions(searchTerm);
+        }, debounceMs);
+        
+        return () => clearTimeout(timeoutId);
+      } else if (!searchTerm.trim()) {
+        // Clear results when search term is empty
+        apiOptions = [];
+      }
+    }
+  });
+
+  // Initial API fetch for static data (no search) - run once on mount
+  $effect(() => {
+    // Only run if we have a URL but no search parameter (static data load)
+    if (url && !searchParam) {
+      // Use untrack to prevent reactivity and only run once
+      untrack(() => fetchOptions(""));
+    }
+  });
+
+  // Clear error state when search term changes
+  $effect(() => {
+    if (searchTerm !== lastSearchTerm) {
+      hasError = false;
+      currentError = null;
+    }
+  });
+
+  // Handle keyboard navigation within list
+  function handleListKeydown(event: KeyboardEvent) {
+    if (disabled) return;
+    
+    if (event.key === 'Tab') {
+      // Allow normal tab navigation to move to next element
+      return;
+    }
+    
+    if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+      event.preventDefault();
+      event.stopPropagation(); // Prevent parent dialog from scrolling
+      
+      // If no item is focused yet, start from keyboard cursor position and move from there
+      if (focusedIndex === -1) {
+        // Start from keyboard cursor if available, otherwise start from beginning
+        const startIndex = keyboardCursor >= 0 ? keyboardCursor : 0;
+        
+        if (event.key === 'ArrowDown') {
+          focusedIndex = Math.min(startIndex + 1, allOptions().length - 1);
+        } else {
+          focusedIndex = Math.max(startIndex - 1, 0);
+        }
+      } else {
+        // Normal navigation
+        if (event.key === 'ArrowDown') {
+          focusedIndex = Math.min(focusedIndex + 1, allOptions().length - 1);
+        } else {
+          focusedIndex = Math.max(focusedIndex - 1, 0);
+        }
+      }
+      
+      // Update keyboard cursor to track current navigation position
+      keyboardCursor = focusedIndex;
+      
+      // Scroll to keep focused item visible (only needed when maxVisibleItems is set)
+      if (listElement && maxVisibleItems !== undefined) {
+        const actualItemHeight = getActualItemHeight();
+        const itemTop = focusedIndex * actualItemHeight;
+        const itemBottom = itemTop + actualItemHeight;
+        const viewTop = listElement.scrollTop;
+        const currentMaxHeight = maxHeight();
+        const viewBottom = viewTop + currentMaxHeight;
+        
+        if (itemTop < viewTop) {
+          // Item is above visible area
+          listElement.scrollTop = itemTop;
+        } else if (itemBottom > viewBottom) {
+          // Item is below visible area
+          listElement.scrollTop = itemBottom - currentMaxHeight;
+        }
+      }
+    } else if (event.key === ' ') {
+      event.preventDefault();
+      event.stopPropagation(); // Prevent page scroll
+      if (focusedIndex >= 0 && focusedIndex < allOptions().length) {
+        const selectedOption = allOptions()[focusedIndex];
+        
+        // Update bindable value using toggle logic
+        toggleSelection(selectedOption.value);
+        
+        // Call onSelection callback
+        if (onSelection) {
+          onSelection(selectedOption);
+        }
+      }
+    }
+  }
+
+  // Custom scrollbar functions
+  const scrollThumbHeight = $derived(() => {
+    if (!listElement || maxVisibleItems === undefined) return 20;
+    const actualItemHeight = getActualItemHeight();
+    const totalContentHeight = allOptions().length * actualItemHeight;
+    const currentMaxHeight = maxHeight();
+    const visibleRatio = currentMaxHeight / totalContentHeight;
+    return Math.max(20, Math.min(currentMaxHeight - 4, visibleRatio * currentMaxHeight)); // Minimum 20px, max container height - 4px
+  });
+
+  function handleThumbMouseDown(event: MouseEvent) {
+    if (!listElement) return;
+    event.preventDefault();
+    isDragging = true;
+    dragStartY = event.clientY;
+    dragStartScrollTop = listElement.scrollTop;
+    
+    document.addEventListener('mousemove', handleThumbMouseMove);
+    document.addEventListener('mouseup', handleThumbMouseUp);
+  }
+
+  function handleThumbMouseMove(event: MouseEvent) {
+    if (!isDragging || !listElement || maxVisibleItems === undefined) return;
+    
+    const deltaY = event.clientY - dragStartY;
+    const currentMaxHeight = maxHeight();
+    const scrollRatio = deltaY / (currentMaxHeight - scrollThumbHeight());
+    const maxScrollTop = listElement.scrollHeight - listElement.clientHeight;
+    
+    listElement.scrollTop = Math.max(0, Math.min(maxScrollTop, dragStartScrollTop + scrollRatio * maxScrollTop));
+  }
+
+  function handleThumbMouseUp() {
+    isDragging = false;
+    document.removeEventListener('mousemove', handleThumbMouseMove);
+    document.removeEventListener('mouseup', handleThumbMouseUp);
+  }
+
+  // Update scroll thumb position on scroll
+  function handleScroll() {
+    if (listElement) {
+      scrollTop = listElement.scrollTop;
+    }
+  }
+
+  // Watch for scroll changes with an effect
+  $effect(() => {
+    if (listElement && maxVisibleItems !== undefined) {
+      const updateScrollPosition = () => {
+        if (!listElement || maxVisibleItems === undefined) return;
+        
+        const trackPadding = 4; // 4px padding on top and bottom
+        const actualItemHeight = getActualItemHeight();
+        const totalContentHeight = allOptions().length * actualItemHeight;
+        const currentMaxHeight = maxHeight();
+        const visibleRatio = currentMaxHeight / totalContentHeight;
+        thumbHeight = Math.max(20, Math.min(currentMaxHeight - (trackPadding * 2) - 4, visibleRatio * currentMaxHeight));
+        
+        const maxScrollTop = listElement.scrollHeight - listElement.clientHeight;
+        if (maxScrollTop > 0) {
+          const scrollRatio = listElement.scrollTop / maxScrollTop;
+          const trackHeight = currentMaxHeight - thumbHeight - (trackPadding * 2);
+          thumbTop = trackPadding + (scrollRatio * trackHeight);
+        }
+        
+        scrollTop = listElement.scrollTop;
+      };
+      
+      // Initial calculation
+      setTimeout(updateScrollPosition, 10);
+      
+      listElement.addEventListener('scroll', updateScrollPosition);
+      return () => {
+        if (listElement) {
+          listElement.removeEventListener('scroll', updateScrollPosition);
+        }
+      };
+    }
+  });
+</script>
+
+<div class="relative {className}">
+  <div class="relative">
+    <div 
+      bind:this={listElement}
+      class="{disabled ? '[background-color:color-mix(in_srgb,var(--color-text)_5%,transparent)] [border-color:color-mix(in_srgb,var(--color-secondary)_50%,transparent)] border cursor-not-allowed' : '[background-color:var(--color-background)] [border-color:var(--color-secondary)] hover:[border-color:color-mix(in_srgb,var(--color-secondary)_80%,black)] focus:[border-color:color-mix(in_srgb,var(--color-secondary)_90%,black)] focus:[outline:2px_solid_color-mix(in_srgb,currentColor_70%,transparent)] focus:[outline-offset:0px]'} rounded-md overflow-y-scroll custom-list {dropdownClass}"
+      style="height: {maxHeight()}px; scrollbar-width: none; -ms-overflow-style: none; overscroll-behavior: contain; {disabled ? 'border-width: 1px;' : 'border-width: var(--ui-border);'}"
+      onscroll={handleScroll}
+      onkeydown={handleListKeydown}
+      onfocus={handleListFocus}
+      onblur={handleListBlur}
+      tabindex={disabled ? -1 : 0}
+      role="listbox"
+      aria-label="List of options"
+      aria-busy={isLoading}
+      aria-disabled={disabled}
+    >
+    {#if isLoading && showLoading}
+      <div class="flex items-center justify-center py-4 [color:var(--color-secondary)]">
+        <div class="animate-spin rounded-full h-4 w-4 border-b-2 [border-color:var(--color-secondary)] mr-2"></div>
+        {loadingText}
+      </div>
+    {:else if hasError && showError}
+      <div class="flex items-center justify-center py-4 [color:var(--color-danger)]">
+        <span class="text-sm [color:var(--color-danger)]">{errorText}</span>
+      </div>
+    {:else if allOptions().length === 0}
+      <div class="flex items-center justify-center [color:var(--color-secondary)] select-none" style="height: {itemHeight}px;">
+        <span class="px-4 text-sm [color:var(--color-secondary)]">{emptyText}</span>
+      </div>
+    {:else}
+      {#each allOptions() as option, index (option.value)}
+        <button
+          bind:this={itemElements[index]}
+          type="button"
+          class="w-full text-left focus:outline-none flex items-center {disabled ? 'cursor-not-allowed [color:color-mix(in_srgb,var(--color-text)_40%,transparent)]' : 'cursor-pointer [color:var(--color-text)]'} {showCheckboxes ? (focusedIndex === index ? '[background-color:var(--color-secondary)] hover:[background-color:var(--color-secondary)] focus:[background-color:var(--color-secondary)]' : 'bg-transparent hover:[background-color:var(--color-secondary)] focus:[background-color:var(--color-secondary)]') : (isSelected(option.value) ? '[background-color:color-mix(in_srgb,var(--color-secondary)_80%,black)] [color:var(--color-text)] hover:[background-color:color-mix(in_srgb,var(--color-secondary)_80%,black)] focus:[background-color:color-mix(in_srgb,var(--color-secondary)_80%,black)]' : focusedIndex === index ? '[background-color:var(--color-secondary)] hover:[background-color:var(--color-secondary)] focus:[background-color:var(--color-secondary)]' : 'bg-transparent hover:[background-color:var(--color-secondary)] focus:[background-color:var(--color-secondary)]')} {itemClass}"
+          style="border: none; border-radius: 0; justify-content: flex-start; {itemSnippet ? '' : `height: ${itemHeight}px;`}"
+          onmousedown={(event) => selectOption(option.value, event)}
+          tabindex="-1"
+          role="option"
+          aria-selected={isSelected(option.value)}
+          aria-label={option.label}
+          disabled={disabled}
+        >
+          {#if itemSnippet}
+            {@render itemSnippet(option, index, isSelected(option.value), focusedIndex === index)}
+          {:else if showCheckboxes}
+            <div class="flex items-center gap-3 px-2 py-2 w-full">
+              <div class="relative">
+                <input
+                  type="checkbox"
+                  checked={isSelected(option.value)}
+                  disabled={disabled}
+                  class="w-4 h-4 rounded [border-color:var(--color-secondary)] {isSelected(option.value) ? '[background-color:var(--color-primary)] [border-color:var(--color-primary)]' : '[background-color:var(--color-background)]'} {disabled ? 'opacity-50 cursor-not-allowed' : 'cursor-pointer'}"
+                  tabindex="-1"
+                  readonly
+                />
+                {#if isSelected(option.value)}
+                  <svg class="absolute inset-0 w-4 h-4 text-white pointer-events-none" fill="currentColor" viewBox="0 0 20 20">
+                    <path fill-rule="evenodd" d="M16.707 5.293a1 1 0 010 1.414l-8 8a1 1 0 01-1.414 0l-4-4a1 1 0 011.414-1.414L8 12.586l7.293-7.293a1 1 0 011.414 0z" clip-rule="evenodd" />
+                  </svg>
+                {/if}
+              </div>
+              <span class="flex-1 text-left text-sm">{option.label}</span>
+            </div>
+          {:else}
+            <span class="px-2 w-full text-sm leading-tight">{option.label}</span>
+          {/if}
+        </button>
+      {/each}
+    {/if}
+    </div>
+    
+    <!-- Custom scrollbar thumb - only show when maxVisibleItems is set and exceeded -->
+    {#if maxVisibleItems !== undefined && allOptions().length > maxVisibleItems && !isLoading && !hasError}
+      <div 
+        class="absolute right-1 [background-color:color-mix(in_srgb,var(--color-text)_60%,transparent)] rounded cursor-default hover:[background-color:color-mix(in_srgb,var(--color-text)_80%,transparent)] transition-colors z-10"
+        style="top: {thumbTop}px; height: {thumbHeight}px; width: 6px;"
+        bind:this={scrollThumb}
+        onmousedown={handleThumbMouseDown}
+        role="scrollbar"
+        aria-orientation="vertical"
+        aria-controls="custom-list"
+        aria-valuenow={listElement ? Math.round((listElement.scrollTop / (listElement.scrollHeight - listElement.clientHeight)) * 100) : 0}
+        aria-valuemin="0"
+        aria-valuemax="100"
+        tabindex="-1"
+        aria-label="Scroll thumb"
+      ></div>
+    {/if}
+  </div>
+</div>
+
+<style>
+  /* Hide default scrollbar */
+  .custom-list::-webkit-scrollbar {
+    display: none;
+  }
+  
+  .custom-list {
+    scrollbar-width: none;
+    -ms-overflow-style: none;
+    /* Prevent scroll chaining to parent elements */
+    overscroll-behavior: contain;
+  }
+</style>

package/dist/components/List/List.svelte.d.ts

@@ -0,0 +1,38 @@
+import type { Snippet } from 'svelte';
+type Option = Record<string, any> & {
+    value: string;
+    label: string;
+};
+interface Props {
+    options: Option[];
+    value?: string | string[];
+    multiSelect?: boolean;
+    showCheckboxes?: boolean;
+    maxVisibleItems?: number;
+    itemHeight?: number;
+    minHeight?: number;
+    class?: string;
+    dropdownClass?: string;
+    itemClass?: string;
+    itemSnippet?: Snippet<[Option, number, boolean, boolean]>;
+    disabled?: boolean;
+    url?: string;
+    searchParam?: string;
+    transform?: (apiResponse: any) => Option[];
+    debounceMs?: number;
+    maxResults?: number;
+    headers?: Record<string, string>;
+    searchTerm?: string;
+    showLoading?: boolean;
+    loadingText?: string;
+    showError?: boolean;
+    errorText?: string;
+    emptyText?: string;
+    onError?: (error: Error) => void;
+    onLoadStart?: () => void;
+    onLoadEnd?: () => void;
+    onSelection?: (option: Option) => void;
+}
+declare const List: import("svelte").Component<Props, {}, "value" | "searchTerm">;
+type List = ReturnType<typeof List>;
+export default List;

package/dist/components/List/index.d.ts

@@ -0,0 +1 @@
+export { default } from './List.svelte';

package/dist/components/List/index.js

@@ -0,0 +1 @@
+export { default } from './List.svelte';