@urbicon-ui/blocks 6.1.4

package/dist/primitives/Select/Select.svelte

@@ -0,0 +1,704 @@
+<script lang="ts" generics="T extends string | number | boolean = string">
+  import { useBlocksI18n, mintRegistry } from '../..';
+  import { useFormField, getTierContext, useFloatingListbox } from '../../utils';
+  import { getBlocksConfig, mergeSlotClasses, resolvePresetSlotClasses } from '../../provider';
+  import { resolveIcon } from '../../icons';
+  import ChevronDownIconDefault from '../../icons/ChevronDownIcon.svelte';
+  import CheckIconDefault from '../../icons/CheckIcon.svelte';
+  import CloseIconDefault from '../../icons/CloseIcon.svelte';
+  import type { SelectProps, SelectOption } from './index';
+  import { selectVariants } from './select.variants';
+
+  const bt = useBlocksI18n();
+
+  const ChevronIcon = resolveIcon('chevronDown', ChevronDownIconDefault);
+  const CheckIcon = resolveIcon('check', CheckIconDefault);
+  const CloseIcon = resolveIcon('close', CloseIconDefault);
+
+  let {
+    options = [],
+    groups,
+    value = $bindable(null),
+    multiple = false,
+    selectionIndicator,
+    closeOnSelect,
+    multiPlaceholder,
+    placeholder = 'Select...',
+    label,
+    error,
+    helper,
+    clearable = false,
+    nullOption,
+    tier,
+    variant = 'outlined',
+    size = 'md',
+    disabled = false,
+    required = false,
+    name,
+    mint = 'none',
+    onValueChange,
+    open = $bindable(false),
+    usePortal = true,
+    syncWidth = true,
+    customTrigger,
+    customTriggerContent,
+    customItem,
+    closeOnEscape = true,
+    closeOnClickOutside = true,
+    onEscape,
+    onClickOutside,
+    class: className = '',
+    unstyled: unstyledProp = false,
+    slotClasses: slotClassesProp = {},
+    preset,
+    id: idProp,
+    ...restProps
+  }: SelectProps<T> = $props();
+
+  const tierCtx = getTierContext();
+  const effectiveTier = $derived(tier ?? tierCtx?.tier ?? 'modify');
+
+  // The exported `SelectProps<T>` is a discriminated union over `multiple`.
+  // Externally this lets `<Select multiple bind:value={x: T[]}>` and
+  // `<Select bind:value={x: T | null}>` narrow correctly. Internally we
+  // dispatch through a loose alias so the component code can hand either
+  // shape into `onValueChange` without per-branch casts at every call site.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- internal dispatch escape hatch (see comment above)
+  const dispatchValueChange = onValueChange as ((v: any) => void) | undefined;
+
+  /** Resolved null option config — `null` when prop is unset or `groups` is in use. */
+  const nullOptionConfig = $derived.by(() => {
+    if (!nullOption || groups || multiple) return null;
+    const label = typeof nullOption === 'string' ? nullOption : nullOption.label;
+    const disabledOpt = typeof nullOption === 'string' ? false : (nullOption.disabled ?? false);
+    return { label, disabled: disabledOpt };
+  });
+
+  /**
+   * Pseudo-option representing the null choice. We cast `null` to `T` for
+   * structural compatibility — the actual null is preserved at the boundary
+   * (selectOption / selectedOption / value), so consumers always see `T | null`.
+   */
+  const nullOptionAsOption = $derived(
+    nullOptionConfig
+      ? ({
+          label: nullOptionConfig.label,
+          value: null as unknown as T,
+          disabled: nullOptionConfig.disabled
+        } satisfies SelectOption<T>)
+      : null
+  );
+
+  const blocksConfig = getBlocksConfig();
+  const unstyled = $derived(unstyledProp || blocksConfig?.unstyled || false);
+  const slotClasses = $derived(
+    mergeSlotClasses(
+      blocksConfig?.defaults?.Select?.slotClasses,
+      resolvePresetSlotClasses(blocksConfig?.presets, 'Select', preset),
+      slotClassesProp
+    )
+  );
+
+  // ARIA wiring is shared with every form primitive — see XC-2.
+  // All IDs are `$derived` so they react if the consumer changes `idProp`
+  // or `label` after mount (e.g. dynamic form labels).
+  const propsId = $props.id();
+  const uid = $derived(idProp || `select-${propsId}`);
+  const triggerId = $derived(`${uid}-trigger`);
+  const listboxId = $derived(`${uid}-listbox`);
+  const labelId = $derived(label ? `${uid}-label` : undefined);
+  const ff = useFormField(() => ({
+    fieldId: uid,
+    hint: helper,
+    error,
+    required,
+    disabled
+  }));
+
+  let activeIndex = $state(-1);
+  let triggerRef = $state<HTMLElement>();
+  let listboxRef = $state<HTMLDivElement>();
+
+  function focusTrigger() {
+    if (customTrigger && triggerRef) {
+      const child = triggerRef.querySelector<HTMLElement>('button, a, [role="button"]');
+      (child ?? triggerRef).focus();
+    } else {
+      triggerRef?.focus();
+    }
+  }
+
+  // Effective close-on-select default: single closes, multi keeps open so
+  // users can tick multiple options without re-opening — matches established
+  // multi-select listbox UX.
+  const effectiveCloseOnSelect = $derived(closeOnSelect ?? !multiple);
+
+  // Default selection indicator: checkmark for single, checkbox for multi.
+  // Consumers using customItem typically want 'none' so their snippet owns
+  // the indicator placement.
+  const effectiveIndicator = $derived<'checkmark' | 'checkbox' | 'none'>(
+    selectionIndicator ?? (multiple ? 'checkbox' : 'checkmark')
+  );
+
+  const allOptions = $derived.by((): SelectOption<T>[] => {
+    if (groups) return groups.flatMap((g) => g.options);
+    if (nullOptionAsOption) return [nullOptionAsOption, ...options];
+    return options;
+  });
+
+  const enabledOptions = $derived(allOptions.filter((o) => !o.disabled));
+
+  /**
+   * Currently selected option(s), normalized to an array regardless of mode.
+   *
+   * Stale-value detection: when a bound `value` references an id that has no
+   * matching option (typically because options loaded later than the value,
+   * or an option was removed mid-session), we surface a `console.warn` in
+   * dev so the consumer notices the orphan. The orphan is also filtered out
+   * of the hidden form input, so the submitted form stays consistent with
+   * what the trigger shows.
+   */
+  const selectedOptions = $derived.by((): SelectOption<T>[] => {
+    if (multiple) {
+      const values = Array.isArray(value) ? value : [];
+      return values
+        .map((v) => {
+          const found = allOptions.find((o) => o.value === v);
+          if (!found && import.meta.env?.DEV) {
+            console.warn(
+              `[Select] value ${JSON.stringify(v)} has no matching option — dropped from selection.`
+            );
+          }
+          return found;
+        })
+        .filter((o): o is SelectOption<T> => o !== undefined);
+    }
+    if (value === null || value === undefined) return [];
+    const found = allOptions.find((o) => o.value === value);
+    if (!found && import.meta.env?.DEV) {
+      console.warn(
+        `[Select] value ${JSON.stringify(value)} has no matching option — trigger will fall back to placeholder.`
+      );
+    }
+    return found ? [found] : [];
+  });
+
+  /** Backward-compatible single-mode accessor. */
+  const selectedOption = $derived(multiple ? null : (selectedOptions[0] ?? null));
+
+  const styles = $derived(
+    selectVariants({
+      tier: effectiveTier,
+      variant,
+      size,
+      open: open || undefined,
+      disabled: disabled || undefined,
+      error: !!error || undefined,
+      required: required || undefined,
+      messageType: error ? 'error' : 'helper'
+    })
+  );
+
+  $effect(() => {
+    if (triggerRef && mint && mint !== 'none' && !disabled) {
+      return mintRegistry.apply(triggerRef, mint);
+    }
+  });
+
+  $effect(() => {
+    if (open && listboxRef) {
+      if (multiple) {
+        activeIndex = activeIndex >= 0 ? activeIndex : 0;
+      } else {
+        const selectedIdx = enabledOptions.findIndex((o) => o.value === value);
+        activeIndex = selectedIdx >= 0 ? selectedIdx : 0;
+      }
+    }
+  });
+
+  useFloatingListbox({
+    reference: () => triggerRef,
+    floating: () => listboxRef,
+    open: () => open,
+    portal: () => usePortal,
+    syncWidth: () => syncWidth
+  });
+
+  function toggle() {
+    if (disabled) return;
+    open = !open;
+    if (!open) activeIndex = -1;
+  }
+
+  function isOptionSelected(option: SelectOption<T>): boolean {
+    if (multiple) {
+      const values = Array.isArray(value) ? value : [];
+      return values.includes(option.value);
+    }
+    return option.value === value;
+  }
+
+  function selectOption(option: SelectOption<T>) {
+    if (option.disabled) return;
+    if (multiple) {
+      const values = Array.isArray(value) ? [...value] : [];
+      const idx = values.indexOf(option.value);
+      if (idx === -1) {
+        values.push(option.value);
+      } else {
+        values.splice(idx, 1);
+      }
+      value = values as T[];
+      dispatchValueChange?.(values);
+    } else {
+      // Null option carries `null as T`; preserve real `null` at the boundary.
+      const nextValue = option.value === (null as unknown as T) ? null : option.value;
+      value = nextValue;
+      dispatchValueChange?.(nextValue);
+    }
+    if (effectiveCloseOnSelect) {
+      open = false;
+      activeIndex = -1;
+      focusTrigger();
+    }
+  }
+
+  function clear(event?: MouseEvent) {
+    event?.stopPropagation();
+    if (multiple) {
+      value = [] as T[];
+      dispatchValueChange?.([]);
+    } else {
+      value = null;
+      dispatchValueChange?.(null);
+    }
+    focusTrigger();
+  }
+
+  // Focus-restoration policy follows the ARIA Listbox/Button pattern:
+  //   • selection → focus returns to the trigger button (`selectOption`)
+  //   • Escape    → focus returns to the trigger button (handleListboxKeydown)
+  //   • Tab       → focus moves naturally to the next tab stop (no restore)
+  //   • outside   → focus stays where the user clicked (no restore — user
+  //                  explicitly intent to focus elsewhere)
+  function dismissByEscape() {
+    if (!closeOnEscape) return false;
+    open = false;
+    activeIndex = -1;
+    onEscape?.();
+    return true;
+  }
+
+  function handleTriggerKeydown(event: KeyboardEvent) {
+    if (disabled) return;
+
+    switch (event.key) {
+      case 'Enter':
+      case ' ':
+      case 'ArrowDown':
+        event.preventDefault();
+        if (!open) open = true;
+        break;
+      case 'ArrowUp':
+        event.preventDefault();
+        if (!open) open = true;
+        break;
+      case 'Escape':
+        if (open && dismissByEscape()) {
+          event.preventDefault();
+        }
+        break;
+    }
+  }
+
+  function handleListboxKeydown(event: KeyboardEvent) {
+    switch (event.key) {
+      case 'ArrowDown':
+        event.preventDefault();
+        activeIndex = activeIndex < enabledOptions.length - 1 ? activeIndex + 1 : 0;
+        break;
+      case 'ArrowUp':
+        event.preventDefault();
+        activeIndex = activeIndex > 0 ? activeIndex - 1 : enabledOptions.length - 1;
+        break;
+      case 'Enter':
+      case ' ':
+        event.preventDefault();
+        if (activeIndex >= 0 && activeIndex < enabledOptions.length) {
+          selectOption(enabledOptions[activeIndex]);
+        }
+        break;
+      case 'Escape':
+        if (dismissByEscape()) {
+          event.preventDefault();
+          focusTrigger();
+        }
+        break;
+      case 'Tab':
+        // Tab always closes (focus is leaving the widget regardless),
+        // independent of closeOnEscape/closeOnClickOutside.
+        open = false;
+        activeIndex = -1;
+        break;
+      case 'Home':
+        event.preventDefault();
+        activeIndex = 0;
+        break;
+      case 'End':
+        event.preventDefault();
+        activeIndex = enabledOptions.length - 1;
+        break;
+    }
+  }
+
+  function handleClickOutside(event: MouseEvent) {
+    const target = event.target as Node;
+    if (
+      open &&
+      triggerRef &&
+      listboxRef &&
+      !triggerRef.contains(target) &&
+      !listboxRef.contains(target)
+    ) {
+      if (!closeOnClickOutside) return;
+      open = false;
+      activeIndex = -1;
+      onClickOutside?.();
+    }
+  }
+
+  function getOptionId(index: number) {
+    return `${uid}-option-${index}`;
+  }
+
+  /** Trigger label text for single + multi modes. */
+  const triggerText = $derived.by(() => {
+    if (multiple) {
+      if (selectedOptions.length === 0) return null;
+      if (typeof multiPlaceholder === 'function') return multiPlaceholder(selectedOptions);
+      if (typeof multiPlaceholder === 'string') return multiPlaceholder;
+      return selectedOptions.map((o) => o.label).join(', ');
+    }
+    return selectedOption?.label ?? null;
+  });
+
+  const hasSelection = $derived(multiple ? selectedOptions.length > 0 : selectedOption !== null);
+</script>
+
+<svelte:window onclick={handleClickOutside} />
+
+<div
+  class={unstyled
+    ? [slotClasses?.wrapper, className].filter(Boolean).join(' ')
+    : styles.wrapper({ class: [slotClasses?.wrapper, className] })}
+>
+  {#if label}
+    <label
+      id={labelId}
+      for={triggerId}
+      class={unstyled ? (slotClasses?.label ?? '') : styles.label({ class: slotClasses?.label })}
+    >
+      {label}
+    </label>
+  {/if}
+
+  <div
+    class={unstyled ? (slotClasses?.base ?? '') : styles.base({ class: slotClasses?.base })}
+    {...restProps}
+  >
+    {#if customTrigger}
+      <!-- svelte-ignore a11y_no_static_element_interactions -->
+      <span bind:this={triggerRef} class="inline-flex" onkeydown={handleTriggerKeydown}>
+        {@render customTrigger(selectedOptions, open, clear)}
+      </span>
+    {:else}
+      <button
+        bind:this={triggerRef}
+        id={triggerId}
+        type="button"
+        class={unstyled
+          ? (slotClasses?.trigger ?? '')
+          : styles.trigger({ class: slotClasses?.trigger })}
+        {disabled}
+        role="combobox"
+        aria-expanded={open}
+        aria-haspopup="listbox"
+        aria-controls={listboxId}
+        aria-labelledby={labelId}
+        aria-describedby={ff.describedBy}
+        aria-invalid={ff.invalid ? 'true' : undefined}
+        aria-activedescendant={activeIndex >= 0 ? getOptionId(activeIndex) : undefined}
+        onclick={toggle}
+        onkeydown={handleTriggerKeydown}
+      >
+        {#if customTriggerContent}
+          <span
+            class={unstyled
+              ? (slotClasses?.triggerText ?? '')
+              : styles.triggerText({ class: slotClasses?.triggerText })}
+          >
+            {@render customTriggerContent(selectedOptions)}
+          </span>
+        {:else if triggerText !== null}
+          <span
+            class={unstyled
+              ? (slotClasses?.triggerText ?? '')
+              : styles.triggerText({ class: slotClasses?.triggerText })}
+          >
+            {triggerText}
+          </span>
+        {:else}
+          <span
+            class={unstyled
+              ? (slotClasses?.placeholder ?? '')
+              : styles.placeholder({ class: slotClasses?.placeholder })}
+          >
+            {placeholder}
+          </span>
+        {/if}
+
+        {#if !(clearable && hasSelection)}
+          <ChevronIcon
+            class={unstyled
+              ? (slotClasses?.chevron ?? '')
+              : styles.chevron({ class: slotClasses?.chevron })}
+          />
+        {/if}
+      </button>
+
+      {#if clearable && hasSelection}
+        <button
+          type="button"
+          class={unstyled
+            ? (slotClasses?.clear ?? '')
+            : styles.clear({ class: slotClasses?.clear })}
+          onclick={clear}
+          aria-label={bt('accessibility.clearSelection')}
+          tabindex={disabled ? -1 : 0}
+          {disabled}
+        >
+          <CloseIcon />
+        </button>
+      {/if}
+    {/if}
+
+    <!--
+      Listbox stays mounted (with `popover="manual"`) so `bind:this`
+      and `aria-controls` are stable across open/close cycles. Native
+      `[popover]:not(:popover-open)` UA-rule hides it via display:none
+      until `showPopover()` runs in the effect above.
+
+      `tabindex={-1}` keeps the listbox programmatically focusable without
+      adding it to the tab order — the ARIA Listbox / `aria-activedescendant`
+      pattern keeps DOM focus on the trigger button while the visually
+      highlighted option moves with arrow keys.
+
+      `aria-multiselectable` is set in multi-mode so screenreaders announce
+      "listbox, multiselectable" — distinguishes it from single-select.
+    -->
+    <div
+      bind:this={listboxRef}
+      id={listboxId}
+      role="listbox"
+      popover={usePortal ? 'manual' : null}
+      aria-multiselectable={multiple || undefined}
+      tabindex={-1}
+      class={unstyled
+        ? (slotClasses?.listbox ?? '')
+        : styles.listbox({ class: slotClasses?.listbox })}
+      style={usePortal
+        ? 'position: fixed; margin: 0; inset: auto; overflow-y: auto;'
+        : open
+          ? 'position: absolute; overflow-y: auto;'
+          : 'display: none; position: absolute; overflow-y: auto;'}
+      aria-labelledby={labelId}
+      onkeydown={handleListboxKeydown}
+    >
+      {#if open}
+        {#if groups}
+          {#each groups as group (group.label)}
+            <div
+              class={unstyled
+                ? (slotClasses?.group ?? '')
+                : styles.group({ class: slotClasses?.group })}
+              role="group"
+              aria-label={group.label}
+            >
+              <div
+                class={unstyled
+                  ? (slotClasses?.groupLabel ?? '')
+                  : styles.groupLabel({ class: slotClasses?.groupLabel })}
+              >
+                {group.label}
+              </div>
+              {#each group.options as option (option.value)}
+                {@const optIdx = enabledOptions.indexOf(option)}
+                {@const isActive = optIdx === activeIndex}
+                {@const isSel = isOptionSelected(option)}
+                <!--
+                  ARIA Listbox pattern: options are explicitly NOT in the
+                  tab order. Activation happens through the trigger
+                  button's keydown handler via `aria-activedescendant`,
+                  not by moving DOM focus into the option. The two svelte
+                  a11y rules are intentionally silenced here.
+                -->
+                <!-- svelte-ignore a11y_interactive_supports_focus -->
+                <!-- svelte-ignore a11y_click_events_have_key_events -->
+                <div
+                  id={getOptionId(optIdx)}
+                  role="option"
+                  aria-selected={isSel}
+                  aria-disabled={option.disabled || undefined}
+                  class={unstyled
+                    ? (slotClasses?.option ?? '')
+                    : selectVariants({
+                        size,
+                        selected: isSel || undefined
+                      }).option({
+                        class: [
+                          slotClasses?.option,
+                          isActive ? 'bg-surface-hover' : '',
+                          option.disabled ? 'cursor-not-allowed opacity-50' : ''
+                        ]
+                      })}
+                  onclick={() => selectOption(option)}
+                  onmouseenter={() => {
+                    if (!option.disabled) activeIndex = optIdx;
+                  }}
+                >
+                  {#if customItem}
+                    {@render customItem(option, isSel, () => selectOption(option))}
+                  {:else}
+                    {#if effectiveIndicator === 'checkbox'}
+                      <span
+                        class={unstyled
+                          ? (slotClasses?.optionCheckbox ?? '')
+                          : selectVariants({ size, selected: isSel || undefined }).optionCheckbox({
+                              class: slotClasses?.optionCheckbox
+                            })}
+                        aria-hidden="true"
+                      >
+                        <CheckIcon />
+                      </span>
+                    {/if}
+                    <span class={unstyled ? '' : 'flex-1 truncate text-left'}>{option.label}</span>
+                    {#if effectiveIndicator === 'checkmark'}
+                      <CheckIcon
+                        class={unstyled
+                          ? (slotClasses?.optionCheck ?? '')
+                          : selectVariants({ size, selected: isSel || undefined }).optionCheck({
+                              class: slotClasses?.optionCheck
+                            })}
+                      />
+                    {/if}
+                  {/if}
+                </div>
+              {/each}
+            </div>
+          {/each}
+        {:else}
+          {#each allOptions as option (option.value)}
+            {@const optIdx = enabledOptions.indexOf(option)}
+            {@const isActive = optIdx === activeIndex}
+            {@const isSel = isOptionSelected(option)}
+            <!-- Options stay out of the tab order — see ARIA Listbox note above. -->
+            <!-- svelte-ignore a11y_interactive_supports_focus -->
+            <!-- svelte-ignore a11y_click_events_have_key_events -->
+            <div
+              id={getOptionId(optIdx)}
+              role="option"
+              aria-selected={isSel}
+              aria-disabled={option.disabled || undefined}
+              class={unstyled
+                ? (slotClasses?.option ?? '')
+                : selectVariants({
+                    size,
+                    selected: isSel || undefined
+                  }).option({
+                    class: [
+                      slotClasses?.option,
+                      isActive ? 'bg-surface-hover' : '',
+                      option.disabled ? 'cursor-not-allowed opacity-50' : ''
+                    ]
+                  })}
+              onclick={() => selectOption(option)}
+              onmouseenter={() => {
+                if (!option.disabled) activeIndex = optIdx;
+              }}
+            >
+              {#if customItem}
+                {@render customItem(option, isSel, () => selectOption(option))}
+              {:else}
+                {#if effectiveIndicator === 'checkbox'}
+                  <span
+                    class={unstyled
+                      ? (slotClasses?.optionCheckbox ?? '')
+                      : selectVariants({ size, selected: isSel || undefined }).optionCheckbox({
+                          class: slotClasses?.optionCheckbox
+                        })}
+                    aria-hidden="true"
+                  >
+                    <CheckIcon />
+                  </span>
+                {/if}
+                <span class={unstyled ? '' : 'flex-1 truncate text-left'}>{option.label}</span>
+                {#if effectiveIndicator === 'checkmark'}
+                  <CheckIcon
+                    class={unstyled
+                      ? (slotClasses?.optionCheck ?? '')
+                      : selectVariants({ size, selected: isSel || undefined }).optionCheck({
+                          class: slotClasses?.optionCheck
+                        })}
+                  />
+                {/if}
+              {/if}
+            </div>
+          {/each}
+        {/if}
+      {/if}
+    </div>
+  </div>
+
+  {#if name}
+    {#if multiple}
+      <!--
+        Multi-mode always emits zero-or-more inputs (one per *resolved*
+        value), never a single fallback input — that way the form payload
+        shape is consistent regardless of whether the user has touched the
+        field. Orphan values (no matching option) are filtered out via
+        `selectedOptions`, keeping the submitted form aligned with what
+        the trigger displays.
+      -->
+      {#each selectedOptions as opt, i (`${String(opt.value)}-${i}`)}
+        <input type="hidden" {name} value={String(opt.value)} />
+      {/each}
+    {:else}
+      <input
+        type="hidden"
+        {name}
+        value={selectedOptions[0] ? String(selectedOptions[0].value) : ''}
+      />
+    {/if}
+  {/if}
+
+  {#if ff.errorId}
+    <div
+      id={ff.errorId}
+      class={unstyled
+        ? (slotClasses?.message ?? '')
+        : styles.message({ class: slotClasses?.message })}
+      role="alert"
+    >
+      {error}
+    </div>
+  {:else if ff.hintId}
+    <div
+      id={ff.hintId}
+      class={unstyled
+        ? (slotClasses?.message ?? '')
+        : styles.message({ class: slotClasses?.message })}
+    >
+      {helper}
+    </div>
+  {/if}
+</div>