@lostgradient/cinder 0.6.0 → 0.8.0

package/src/components/autocomplete/autocomplete.schema.ts

@@ -0,0 +1,90 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description:
+        'HTML `id` for the underlying input, used to associate the `<label>` and ARIA attributes.',
+    },
+    value: {
+      type: 'string',
+      description: 'Bindable current text value of the input.',
+    },
+    label: {
+      type: 'string',
+      description: 'Visible label text rendered above the input and linked via `for`/`id`.',
+    },
+    description: {
+      type: 'string',
+      description: 'Helper text rendered below the input and associated via `aria-describedby`.',
+    },
+    error: {
+      type: 'string',
+      description: 'Error message rendered below the input; also sets `aria-invalid` on the input.',
+    },
+    minQueryLength: {
+      type: 'number',
+      description:
+        'Minimum number of characters the user must type before suggestions are requested. Default `1`.',
+    },
+    maxVisibleSuggestions: {
+      type: 'number',
+      description: 'Maximum number of suggestions rendered in the listbox at once. Default `50`.',
+    },
+    placeholder: {
+      type: 'string',
+      description: 'Placeholder text shown inside the input when it is empty.',
+    },
+    disabled: {
+      type: 'boolean',
+      description:
+        'When true, disables the input and prevents interaction, matching the native `disabled` attribute.',
+    },
+    required: {
+      type: 'boolean',
+      description:
+        'Marks the input as required for form validation, matching the native `required` attribute.',
+    },
+    readonly: {
+      type: 'boolean',
+      description:
+        'When true, the input value cannot be changed by the user, matching the native `readonly` attribute.',
+    },
+    emptyMessage: {
+      type: 'string',
+      description:
+        'Message shown in the listbox when the suggestion source returns no results. Default `"No suggestions"`.',
+    },
+    loadingMessage: {
+      type: 'string',
+      description:
+        'Message shown in the listbox while the suggestion source is fetching results. Default `"Loading suggestions"`.',
+    },
+    class: {
+      type: 'string',
+      description: 'Additional class names merged onto the root wrapper element.',
+    },
+  },
+  additionalProperties: false,
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'oncomplete',
+        reason: 'function-or-snippet',
+      },
+      {
+        name: 'oninput',
+        reason: 'function-or-snippet',
+      },
+      {
+        name: 'suggestionSource',
+        reason: 'function-or-snippet',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

package/src/components/autocomplete/autocomplete.svelte

@@ -0,0 +1,488 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts">
+import { devWarn } from '../../utilities/dev-warn.ts';
+import { resolveFieldControl } from '../../_internal/field-control.ts';
+import { getFormFieldContext } from '../../_internal/form-field-context.ts';
+import { pushEscapeHandler } from '../../_internal/overlay.ts';
+import { classNames } from '../../utilities/class-names.ts';
+import Popover from '../popover/popover.svelte';
+import VisuallyHiddenLiveRegion from '../_visually-hidden-live-region.svelte';
+let { id, value = $bindable(''), suggestionSource, label, description, error, minQueryLength = 1, maxVisibleSuggestions = 50, placeholder, disabled, required, readonly = false, emptyMessage = 'No suggestions', loadingMessage = 'Loading suggestions', class: className, oninput, oncomplete, 'aria-describedby': consumerDescribedBy, 'aria-invalid': consumerInvalid, ...rest } = $props();
+const context = getFormFieldContext();
+const generatedId = $props.id();
+const field = $derived(resolveFieldControl({
+    ...(id !== undefined ? { id } : {}),
+    generatedId,
+    context,
+    hasDescription: !!description,
+    hasError: !!error,
+    localIdNamespace: 'control',
+    consumerDescribedBy,
+    consumerInvalid,
+    required,
+    disabled,
+}));
+const resolvedId = $derived(field.id);
+const listboxId = $derived(`${resolvedId}-listbox`);
+const resolvedMinQueryLength = $derived(toNonNegativeInteger(minQueryLength, 1));
+const resolvedMaxVisibleSuggestions = $derived(toNonNegativeInteger(maxVisibleSuggestions, 50));
+$effect(() => {
+    if (context && id && context.controlId !== id) {
+        devWarn(`[cinder/Autocomplete] id mismatch: Autocomplete id="${id}" but wrapping FormField expects controlId="${context.controlId}". Set the same id on both.`);
+    }
+});
+let inputElement = $state(null);
+let open = $state(false);
+let loading = $state(false);
+let composing = $state(false);
+let inputFocused = $state(false);
+let suggestions = $state([]);
+// rawActiveIndex tracks the user's chosen index; activeIndex clamps it from
+// enabledIndexes so no write-back $effect is needed when renderedSuggestions
+// changes (e.g. when maxVisibleSuggestions is updated by the consumer).
+let rawActiveIndex = $state(null);
+let suppressNextQuery = false;
+let ignoreSyntheticInput = false;
+let completionPointerIndex = $state(null);
+let pendingRequestController = null;
+let previousOpen = false;
+let autocompleteDismissed = true;
+let requestVersion = 0;
+const renderedSuggestions = $derived(suggestions.slice(0, resolvedMaxVisibleSuggestions));
+const enabledIndexes = $derived(getEnabledIndexes(renderedSuggestions));
+// activeIndex is always valid for the current renderedSuggestions: if
+// rawActiveIndex is not in the enabled set, fall back to the first enabled
+// index (or null when the list is empty). This replaces the write-back
+// $effect that previously called clampActiveIndex on every suggestions change.
+const activeIndex = $derived.by(() => {
+    if (enabledIndexes.length === 0)
+        return null;
+    if (rawActiveIndex !== null && enabledIndexes.includes(rawActiveIndex))
+        return rawActiveIndex;
+    return enabledIndexes[0] ?? null;
+});
+const activeDescendant = $derived(activeIndex === null ? undefined : `${resolvedId}-option-${activeIndex}`);
+// Persistent live-region status for screen readers. The loading/empty messaging
+// shown inside the popover is portaled and freshly-mounted, so NVDA/JAWS do not
+// reliably announce it. Mirror it into an always-present visually-hidden region
+// outside the popover (see PLATFORM-POLICY § Live regions).
+const statusMessage = $derived(loading ? loadingMessage : open && renderedSuggestions.length === 0 ? emptyMessage : '');
+function isEligibleQuery(query) {
+    return (!field.disabled && !readonly && !!suggestionSource && query.length >= resolvedMinQueryLength);
+}
+function toNonNegativeInteger(value, fallback) {
+    if (!Number.isFinite(value))
+        return fallback;
+    return Math.max(0, Math.trunc(value));
+}
+function getEnabledIndexes(list) {
+    const indexes = [];
+    list.forEach((suggestion, index) => {
+        if (!suggestion.disabled)
+            indexes.push(index);
+    });
+    return indexes;
+}
+$effect(() => {
+    const wasOpen = previousOpen;
+    previousOpen = open;
+    if (!open || !wasOpen)
+        return;
+    pendingRequestController?.abort();
+    pendingRequestController = null;
+    requestVersion += 1;
+    autocompleteDismissed = true;
+    loading = false;
+    rawActiveIndex = null;
+    suggestions = [];
+});
+function closePopup() {
+    pendingRequestController?.abort();
+    pendingRequestController = null;
+    requestVersion += 1;
+    autocompleteDismissed = true;
+    open = false;
+    loading = false;
+    rawActiveIndex = null;
+    suggestions = [];
+}
+function handleEscape(event = undefined) {
+    const wasOpen = open;
+    closePopup();
+    if (wasOpen)
+        event?.preventDefault();
+}
+$effect(() => {
+    if (!open)
+        return;
+    return pushEscapeHandler(handleEscape);
+});
+$effect(() => {
+    const query = value;
+    const source = suggestionSource;
+    const isFocused = inputFocused;
+    if (suppressNextQuery) {
+        suppressNextQuery = false;
+        return;
+    }
+    if (!isFocused || !isEligibleQuery(query) || !source) {
+        suggestions = [];
+        closePopup();
+        return;
+    }
+    const currentVersion = ++requestVersion;
+    const controller = new AbortController();
+    autocompleteDismissed = false;
+    pendingRequestController = controller;
+    loading = true;
+    open = true;
+    suggestions = [];
+    rawActiveIndex = null;
+    let result;
+    try {
+        if (controller.signal.aborted || currentVersion !== requestVersion)
+            return;
+        result = source(query, { signal: controller.signal });
+    }
+    catch (errorValue) {
+        if (controller.signal.aborted || currentVersion !== requestVersion)
+            return;
+        suggestions = [];
+        closePopup();
+        devWarn('[cinder/autocomplete] suggestionSource failed.', errorValue);
+        return;
+    }
+    Promise.resolve(result)
+        .then((nextSuggestions) => {
+        if (controller.signal.aborted ||
+            currentVersion !== requestVersion ||
+            autocompleteDismissed) {
+            return;
+        }
+        // Deduplicate the ENTIRE suggestion list by value (first occurrence
+        // wins), not just the visible window. `renderedSuggestions` re-slices
+        // `suggestions` by maxVisibleSuggestions, so a duplicate anywhere in the
+        // stored list could surface in the keyed {#each} if the window widens or
+        // a tail value collides with the visible prefix — both crash with
+        // each_key_duplicate. Deduping the whole list makes the key globally
+        // unique regardless of window size.
+        const seen = new Set();
+        const deduped = [];
+        let hasDuplicates = false;
+        for (const suggestion of nextSuggestions) {
+            if (seen.has(suggestion.value)) {
+                hasDuplicates = true;
+            }
+            else {
+                seen.add(suggestion.value);
+                deduped.push(suggestion);
+            }
+        }
+        if (hasDuplicates) {
+            devWarn('[cinder/Autocomplete] Duplicate suggestion values detected. Each rendered suggestion must have a unique value. Duplicates were removed; only the first occurrence of each value is shown.');
+        }
+        suggestions = deduped;
+        loading = false;
+        open = true;
+        // rawActiveIndex is reset to null when the query starts; activeIndex is
+        // $derived to auto-clamp, so no explicit clampActiveIndex call is needed.
+    })
+        .catch((errorValue) => {
+        if (controller.signal.aborted ||
+            currentVersion !== requestVersion ||
+            autocompleteDismissed) {
+            return;
+        }
+        suggestions = [];
+        closePopup();
+        devWarn('[cinder/autocomplete] suggestionSource failed.', errorValue);
+    })
+        .finally(() => {
+        if (pendingRequestController === controller) {
+            pendingRequestController = null;
+        }
+    });
+    return () => {
+        controller.abort();
+        if (pendingRequestController === controller) {
+            pendingRequestController = null;
+        }
+    };
+});
+function highlightParts(text, query) {
+    if (!query)
+        return null;
+    const normalizedQuery = query.trim();
+    if (!normalizedQuery)
+        return null;
+    const matchIndex = text.toLowerCase().indexOf(normalizedQuery.toLowerCase());
+    if (matchIndex < 0)
+        return null;
+    const before = text.slice(0, matchIndex);
+    const match = text.slice(matchIndex, matchIndex + normalizedQuery.length);
+    const after = text.slice(matchIndex + normalizedQuery.length);
+    return [before, match, after];
+}
+function moveActive(direction) {
+    if (enabledIndexes.length === 0)
+        return;
+    open = true;
+    if (activeIndex === null) {
+        rawActiveIndex =
+            direction === 1 ? (enabledIndexes[0] ?? null) : (enabledIndexes.at(-1) ?? null);
+        return;
+    }
+    const currentPosition = enabledIndexes.indexOf(activeIndex);
+    const nextPosition = currentPosition < 0
+        ? 0
+        : (currentPosition + direction + enabledIndexes.length) % enabledIndexes.length;
+    rawActiveIndex = enabledIndexes[nextPosition] ?? null;
+}
+function moveToBoundary(direction) {
+    if (!open)
+        return;
+    if (enabledIndexes.length === 0)
+        return;
+    rawActiveIndex =
+        direction === 'start' ? (enabledIndexes[0] ?? null) : (enabledIndexes.at(-1) ?? null);
+}
+function dispatchCompletionInputEvent() {
+    if (!inputElement)
+        return;
+    ignoreSyntheticInput = true;
+    inputElement.dispatchEvent(new Event('input', { bubbles: true }));
+}
+function completeSuggestion(suggestion) {
+    if (!suggestion || suggestion.disabled)
+        return;
+    suppressNextQuery = true;
+    value = suggestion.value;
+    if (inputElement)
+        inputElement.value = suggestion.value;
+    closePopup();
+    oninput?.(suggestion.value);
+    oncomplete?.(suggestion);
+    dispatchCompletionInputEvent();
+}
+function handleInput(event) {
+    if (ignoreSyntheticInput) {
+        ignoreSyntheticInput = false;
+        return;
+    }
+    autocompleteDismissed = false;
+    inputFocused = true;
+    const target = event.currentTarget;
+    value = target.value;
+    oninput?.(target.value);
+}
+function handleFocus() {
+    autocompleteDismissed = false;
+    inputFocused = true;
+    if (isEligibleQuery(value)) {
+        open = true;
+    }
+}
+function handleBlur() {
+    inputFocused = false;
+    closePopup();
+}
+function handleKeyDown(event) {
+    if (event.key === 'ArrowDown') {
+        if (enabledIndexes.length === 0)
+            return;
+        event.preventDefault();
+        moveActive(1);
+        return;
+    }
+    if (event.key === 'ArrowUp') {
+        if (enabledIndexes.length === 0)
+            return;
+        event.preventDefault();
+        moveActive(-1);
+        return;
+    }
+    if (event.key === 'Home') {
+        if (!open || enabledIndexes.length === 0)
+            return;
+        event.preventDefault();
+        moveToBoundary('start');
+        return;
+    }
+    if (event.key === 'End') {
+        if (!open || enabledIndexes.length === 0)
+            return;
+        event.preventDefault();
+        moveToBoundary('end');
+        return;
+    }
+    if (event.key === 'Escape' && open) {
+        if (event.defaultPrevented)
+            return;
+        handleEscape(event);
+        return;
+    }
+    if (event.key === 'Enter' && open && !composing) {
+        const suggestion = activeIndex === null ? undefined : renderedSuggestions[activeIndex];
+        if (suggestion && !suggestion.disabled) {
+            event.preventDefault();
+            completeSuggestion(suggestion);
+        }
+    }
+}
+function handlePointerComplete(event, index) {
+    event.preventDefault();
+    completionPointerIndex = index;
+    completeSuggestion(renderedSuggestions[index]);
+    queueMicrotask(() => {
+        if (completionPointerIndex === index)
+            completionPointerIndex = null;
+    });
+}
+function handleMouseDownFallback(event, index) {
+    if (completionPointerIndex === index) {
+        completionPointerIndex = null;
+        return;
+    }
+    event.preventDefault();
+    completeSuggestion(renderedSuggestions[index]);
+}
+</script>
+
+<div
+  class={classNames('cinder-autocomplete', className)}
+  data-disabled={field.disabled ? '' : undefined}
+  data-invalid={field.ariaInvalid === 'true' ? '' : undefined}
+>
+  {#if label}
+    <label
+      for={resolvedId}
+      class="cinder-autocomplete__label"
+      data-disabled={field.disabled || undefined}
+    >
+      {label}
+      {#if field.required}
+        <span class="cinder-_required-marker" aria-hidden="true">*</span>
+      {/if}
+    </label>
+  {/if}
+
+  <input
+    bind:this={inputElement}
+    {...rest}
+    id={resolvedId}
+    type="text"
+    class="cinder-autocomplete__input"
+    {value}
+    {placeholder}
+    disabled={field.disabled}
+    required={field.required}
+    {readonly}
+    autocomplete={rest.autocomplete ?? 'off'}
+    role="combobox"
+    aria-autocomplete="list"
+    aria-expanded={open}
+    aria-haspopup="listbox"
+    aria-controls={open ? listboxId : undefined}
+    aria-activedescendant={activeDescendant}
+    aria-invalid={field.ariaInvalid}
+    aria-describedby={field.describedBy}
+    oninput={handleInput}
+    onfocus={handleFocus}
+    onblur={handleBlur}
+    onkeydown={handleKeyDown}
+    oncompositionstart={() => {
+      composing = true;
+    }}
+    oncompositionend={() => {
+      composing = false;
+    }}
+  />
+
+  {#if description}
+    <p id={field.ownDescriptionId} class="cinder-autocomplete__description">{description}</p>
+  {/if}
+
+  {#if error}
+    <p id={field.ownErrorId} class="cinder-autocomplete__error" aria-live="polite">{error}</p>
+  {/if}
+
+  <!-- Persistent status announcer (loading / no-results), outside the portaled
+       popover so screen readers reliably hear it. -->
+  <VisuallyHiddenLiveRegion message={statusMessage} />
+</div>
+
+<Popover
+  bind:open
+  id={listboxId}
+  triggerRef={inputElement}
+  role="listbox"
+  focusManagement="preserve"
+  wireTriggerAria={false}
+  closeOnEscape={false}
+  widthMode="match-anchor"
+  class="cinder-autocomplete__panel"
+>
+  {#if loading}
+    <div
+      id={`${resolvedId}-status-loading`}
+      role="option"
+      tabindex="-1"
+      class="cinder-_option-row cinder-autocomplete__option cinder-autocomplete__status"
+      aria-selected="false"
+      aria-disabled="true"
+    >
+      {loadingMessage}
+    </div>
+  {:else if renderedSuggestions.length === 0}
+    <div
+      id={`${resolvedId}-status-empty`}
+      role="option"
+      tabindex="-1"
+      class="cinder-_option-row cinder-autocomplete__option cinder-autocomplete__status"
+      aria-selected="false"
+      aria-disabled="true"
+    >
+      {emptyMessage}
+    </div>
+  {:else}
+    {#each renderedSuggestions as suggestion, index (suggestion.value)}
+      {@const suggestionLabel = suggestion.label ?? suggestion.value}
+      {@const parts = highlightParts(suggestionLabel, value)}
+      <div
+        id={`${resolvedId}-option-${index}`}
+        role="option"
+        tabindex="-1"
+        class="cinder-_option-row cinder-autocomplete__option"
+        aria-selected={index === activeIndex}
+        aria-disabled={suggestion.disabled || undefined}
+        data-cinder-active={index === activeIndex || undefined}
+        data-cinder-disabled={suggestion.disabled || undefined}
+        onpointerdown={(event) => {
+          handlePointerComplete(event, index);
+        }}
+        onmousedown={(event) => {
+          handleMouseDownFallback(event, index);
+        }}
+        onmouseenter={() => {
+          if (!suggestion.disabled) rawActiveIndex = index;
+        }}
+      >
+        <span class="cinder-autocomplete__option-text">
+          <span class="cinder-autocomplete__option-label">
+            {#if parts}
+              {parts[0]}<mark class="cinder-autocomplete__match">{parts[1]}</mark>{parts[2]}
+            {:else}
+              {suggestionLabel}
+            {/if}
+          </span>
+          {#if suggestion.description}
+            <span class="cinder-autocomplete__option-description">{suggestion.description}</span>
+          {/if}
+        </span>
+      </div>
+    {/each}
+  {/if}
+</Popover>

package/src/components/autocomplete/autocomplete.types.ts

@@ -0,0 +1,74 @@
+import type { HTMLInputAttributes } from 'svelte/elements';
+
+export type AutocompleteSuggestion = {
+  /** Text committed into the input when this suggestion is completed. */
+  value: string;
+  /** Visible primary label. Defaults to `value` when omitted. */
+  label?: string;
+  /** Optional secondary text rendered under the label. */
+  description?: string;
+  /** When true, the suggestion is rendered but cannot be completed. */
+  disabled?: boolean;
+};
+
+export type AutocompleteSuggestionSourceContext = {
+  /** Aborted when a newer query supersedes this request or the component is destroyed. */
+  signal: AbortSignal;
+};
+
+export type AutocompleteSuggestionSource = (
+  query: string,
+  context: AutocompleteSuggestionSourceContext,
+) => AutocompleteSuggestion[] | Promise<AutocompleteSuggestion[]>;
+
+export type AutocompleteSchemaProps = {
+  /** HTML `id` for the underlying input, used to associate the `<label>` and ARIA attributes. */
+  id?: string;
+  /** Bindable current text value of the input. */
+  value?: string;
+  suggestionSource?: AutocompleteSuggestionSource;
+  /** Visible label text rendered above the input and linked via `for`/`id`. */
+  label?: string;
+  /** Helper text rendered below the input and associated via `aria-describedby`. */
+  description?: string;
+  /** Error message rendered below the input; also sets `aria-invalid` on the input. */
+  error?: string;
+  /** Minimum number of characters the user must type before suggestions are requested. Default `1`. */
+  minQueryLength?: number;
+  /** Maximum number of suggestions rendered in the listbox at once. Default `50`. */
+  maxVisibleSuggestions?: number;
+  /** Placeholder text shown inside the input when it is empty. */
+  placeholder?: string;
+  /** When true, disables the input and prevents interaction, matching the native `disabled` attribute. */
+  disabled?: boolean;
+  /** Marks the input as required for form validation, matching the native `required` attribute. */
+  required?: boolean;
+  /** When true, the input value cannot be changed by the user, matching the native `readonly` attribute. */
+  readonly?: boolean;
+  /** Message shown in the listbox when the suggestion source returns no results. Default `"No suggestions"`. */
+  emptyMessage?: string;
+  /** Message shown in the listbox while the suggestion source is fetching results. Default `"Loading suggestions"`. */
+  loadingMessage?: string;
+  /** Additional class names merged onto the root wrapper element. */
+  class?: string;
+  oninput?: (value: string) => void;
+  oncomplete?: (suggestion: AutocompleteSuggestion) => void;
+};
+
+export type AutocompleteProps = Omit<
+  HTMLInputAttributes,
+  | 'type'
+  | 'value'
+  | 'oninput'
+  | 'onchange'
+  | 'onkeydown'
+  | 'onfocus'
+  | 'onblur'
+  | 'oncompositionstart'
+  | 'oncompositionend'
+  | 'disabled'
+  | 'required'
+  | 'readonly'
+  | 'role'
+> &
+  AutocompleteSchemaProps;

package/src/components/autocomplete/autocomplete.variables.ts

@@ -0,0 +1,3 @@
+const variables: readonly string[] = [];
+
+export default variables;

package/src/components/autocomplete/index.ts

@@ -0,0 +1,11 @@
+import './autocomplete.css';
+import Autocomplete from './autocomplete.svelte';
+
+export default Autocomplete;
+export type {
+  AutocompleteProps,
+  AutocompleteSchemaProps,
+  AutocompleteSuggestion,
+  AutocompleteSuggestionSource,
+  AutocompleteSuggestionSourceContext,
+} from './autocomplete.types.ts';