@lostgradient/cinder 0.6.0 → 0.7.0

package/src/components/multi-select/multi-select.svelte

@@ -0,0 +1,529 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts" generics="T extends string = string">
+import { tick, untrack } from 'svelte';
+import { pushEscapeHandler } from '../../_internal/overlay.ts';
+import { resolveFieldControl } from '../../_internal/field-control.ts';
+import { getFormFieldContext } from '../../_internal/form-field-context.ts';
+import { classNames } from '../../utilities/class-names.ts';
+let { id, items, selectedIds = $bindable([]), name, label, placeholder = 'Select options', description, error, warning, disabled, readonly = false, required, filterable = false, filterItem, selectionFeedback = 'fixed', direction = 'down', class: className, 'aria-describedby': consumerDescribedBy, } = $props();
+const context = getFormFieldContext();
+const warningId = $derived(warning ? `${id}-warning` : undefined);
+const field = $derived(resolveFieldControl({
+    id,
+    generatedId: id,
+    context,
+    hasDescription: !!description,
+    hasError: !!error,
+    localIdNamespace: 'multi-select',
+    consumerDescribedBy,
+    additionalDescribedBy: [warningId],
+    required,
+    disabled,
+}));
+const stableLocalErrorId = $derived(context?.errorId === `${field.id}-error`
+    ? `${field.id}-multi-select-error`
+    : `${field.id}-error`);
+const listboxId = $derived(`${id}-listbox`);
+const filterId = $derived(`${id}-filter`);
+const filterLabelHintId = $derived(`${id}-filter-label-hint`);
+const labelId = $derived(label ? `${id}-label` : undefined);
+const listboxLabelledBy = $derived(labelId ?? context?.labelId);
+const itemIdSet = $derived(new Set(items.map((item) => item.id)));
+const uniqueSelectedIds = $derived.by(() => {
+    const seen = new Set();
+    const next = [];
+    for (const selectedId of selectedIds) {
+        if (!itemIdSet.has(selectedId) || seen.has(selectedId))
+            continue;
+        seen.add(selectedId);
+        next.push(selectedId);
+    }
+    return next;
+});
+const selectedSet = $derived(new Set(uniqueSelectedIds));
+const selectedCount = $derived(uniqueSelectedIds.length);
+let open = $state(false);
+let query = $state('');
+let activeIndex = $state(-1);
+let reorderAfterReopen = $state(false);
+let openedAtLeastOnce = $state(false);
+let triggerElement = $state(null);
+let controlElement = $state(null);
+let panelElement = $state(null);
+let filterElement = $state(null);
+let listboxElement = $state(null);
+let validityProxyElement = $state(null);
+let nativeError = $state('');
+let resetSyncTimeout;
+const triggerAriaInvalid = $derived(field.ariaInvalid ?? (nativeError ? true : undefined));
+const triggerDescribedBy = $derived.by(() => {
+    const ids = new Set((field.describedBy ?? '').split(/\s+/).filter(Boolean));
+    if (nativeError)
+        ids.add(field.ownErrorId ?? stableLocalErrorId);
+    const value = Array.from(ids).join(' ');
+    return value === '' ? undefined : value;
+});
+const filterAriaLabelledBy = $derived.by(() => {
+    if (!listboxLabelledBy)
+        return filterLabelHintId;
+    return `${listboxLabelledBy} ${filterLabelHintId}`;
+});
+const triggerSummary = $derived(selectedCount > 0 ? `${selectedCount} selected` : placeholder);
+const emptyListMessage = $derived(filterable ? 'No matching options' : 'No options');
+const initialSelectedIds = untrack(() => [...selectedIds]);
+const defaultFilter = (item, nextQuery) => {
+    if (!nextQuery)
+        return true;
+    const q = nextQuery.toLowerCase();
+    return (item.label.toLowerCase().includes(q) || (item.description?.toLowerCase().includes(q) ?? false));
+};
+const filteredItems = $derived.by(() => {
+    if (!filterable)
+        return items;
+    const fn = filterItem ?? defaultFilter;
+    return items.filter((item) => fn(item, query));
+});
+const visibleItems = $derived.by(() => {
+    const shouldPromoteSelected = selectionFeedback === 'top' ||
+        (selectionFeedback === 'top-after-reopen' && reorderAfterReopen);
+    if (!shouldPromoteSelected)
+        return filteredItems;
+    const selected = [];
+    const unselected = [];
+    for (const item of filteredItems) {
+        if (selectedSet.has(item.id))
+            selected.push(item);
+        else
+            unselected.push(item);
+    }
+    return [...selected, ...unselected];
+});
+const activeOptionId = $derived(activeIndex >= 0 && activeIndex < visibleItems.length
+    ? `${id}-option-${activeIndex}`
+    : undefined);
+function firstEnabledIndex(list) {
+    return list.findIndex((item) => !item.disabled);
+}
+function getLastEnabledIndex(list) {
+    for (let index = list.length - 1; index >= 0; index -= 1) {
+        if (!list[index]?.disabled)
+            return index;
+    }
+    return -1;
+}
+function openMenu(preferLast = false) {
+    if (field.disabled)
+        return;
+    open = true;
+    query = '';
+    reorderAfterReopen = selectionFeedback === 'top-after-reopen' && openedAtLeastOnce;
+    openedAtLeastOnce = true;
+    const nextIndex = preferLast
+        ? getLastEnabledIndex(visibleItems)
+        : firstEnabledIndex(visibleItems);
+    activeIndex = nextIndex;
+    void tick().then(() => {
+        if (filterable)
+            filterElement?.focus();
+        else
+            listboxElement?.focus();
+    });
+}
+function closeMenu(restoreFocus = true) {
+    open = false;
+    activeIndex = -1;
+    query = '';
+    if (restoreFocus)
+        triggerElement?.focus();
+}
+function setSelectedIds(next) {
+    selectedIds = [...next];
+}
+function toggleItem(item) {
+    if (field.disabled || readonly || item.disabled)
+        return;
+    const nextSelectedIds = selectedSet.has(item.id)
+        ? uniqueSelectedIds.filter((candidate) => candidate !== item.id)
+        : [...uniqueSelectedIds, item.id];
+    setSelectedIds(nextSelectedIds);
+    if (!open)
+        return;
+    queueMicrotask(() => {
+        const nextIndex = visibleItems.findIndex((candidate) => candidate.id === item.id);
+        if (nextIndex >= 0)
+            activeIndex = nextIndex;
+    });
+}
+function clearSelection(event) {
+    event?.stopPropagation();
+    if (field.disabled || readonly || selectedIds.length === 0)
+        return;
+    setSelectedIds([]);
+    triggerElement?.focus();
+}
+function moveActive(delta) {
+    if (visibleItems.length === 0) {
+        activeIndex = -1;
+        return;
+    }
+    const start = activeIndex < 0 ? (delta === 1 ? -1 : 0) : activeIndex;
+    for (let offset = 1; offset <= visibleItems.length; offset += 1) {
+        const index = (start + delta * offset + visibleItems.length) % visibleItems.length;
+        if (!visibleItems[index]?.disabled) {
+            activeIndex = index;
+            return;
+        }
+    }
+}
+function handleListNavigationKeydown(event) {
+    if (event.key === 'ArrowDown') {
+        event.preventDefault();
+        moveActive(1);
+        return;
+    }
+    if (event.key === 'ArrowUp') {
+        event.preventDefault();
+        moveActive(-1);
+        return;
+    }
+    if (event.key === 'Home') {
+        event.preventDefault();
+        activeIndex = firstEnabledIndex(visibleItems);
+        return;
+    }
+    if (event.key === 'End') {
+        event.preventDefault();
+        activeIndex = getLastEnabledIndex(visibleItems);
+        return;
+    }
+    if (event.key === 'Escape') {
+        event.preventDefault();
+        closeMenu();
+        return;
+    }
+    if (event.key === ' ' || event.key === 'Enter') {
+        event.preventDefault();
+        const item = visibleItems[activeIndex];
+        if (!item)
+            return;
+        toggleItem(item);
+    }
+}
+function handleTriggerKeydown(event) {
+    if (field.disabled)
+        return;
+    if ((event.key === 'Enter' || event.key === ' ') && !open) {
+        event.preventDefault();
+        openMenu();
+        return;
+    }
+    if (event.key === 'ArrowDown') {
+        event.preventDefault();
+        if (!open)
+            openMenu();
+        else
+            moveActive(1);
+        return;
+    }
+    if (event.key === 'ArrowUp') {
+        event.preventDefault();
+        if (!open)
+            openMenu(true);
+        else
+            moveActive(-1);
+        return;
+    }
+    if ((event.key === 'Backspace' || event.key === 'Delete') && selectedIds.length > 0) {
+        clearSelection(event);
+    }
+}
+function handleFilterInput(event) {
+    query = event.currentTarget.value;
+    activeIndex = firstEnabledIndex(visibleItems);
+}
+function handleFilterKeydown(event) {
+    if (event.isComposing)
+        return;
+    if (event.key === ' ')
+        return;
+    if (event.key === 'Home' || event.key === 'End')
+        return;
+    handleListNavigationKeydown(event);
+}
+function resetToInitialValue(event) {
+    if (resetSyncTimeout !== undefined)
+        clearTimeout(resetSyncTimeout);
+    resetSyncTimeout = setTimeout(() => {
+        resetSyncTimeout = undefined;
+        if (event.defaultPrevented)
+            return;
+        setSelectedIds(initialSelectedIds);
+        open = false;
+        activeIndex = -1;
+        query = '';
+    }, 0);
+}
+function handleProxyInvalid(event) {
+    event.preventDefault();
+    nativeError =
+        validityProxyElement?.validationMessage ||
+            (validityProxyElement?.validity.valueMissing ? 'Please select at least one option.' : '');
+    triggerElement?.focus();
+}
+$effect(() => {
+    const proxy = validityProxyElement;
+    if (!proxy)
+        return;
+    proxy.setCustomValidity(field.required && uniqueSelectedIds.length === 0 ? 'Please select at least one option.' : '');
+    if (proxy.validationMessage === '')
+        nativeError = '';
+});
+$effect(() => {
+    const proxy = validityProxyElement;
+    if (proxy === null)
+        return;
+    const form = proxy.form;
+    form?.addEventListener('reset', resetToInitialValue);
+    return () => {
+        form?.removeEventListener('reset', resetToInitialValue);
+        if (resetSyncTimeout !== undefined) {
+            clearTimeout(resetSyncTimeout);
+            resetSyncTimeout = undefined;
+        }
+    };
+});
+$effect(() => {
+    if (!open)
+        return;
+    if (activeIndex < 0 ||
+        activeIndex >= visibleItems.length ||
+        visibleItems[activeIndex]?.disabled) {
+        activeIndex = firstEnabledIndex(visibleItems);
+    }
+});
+$effect(() => {
+    if (!open)
+        return;
+    const handlePointerDown = (event) => {
+        const target = event.target;
+        if (target && controlElement?.contains(target))
+            return;
+        if (target && panelElement?.contains(target))
+            return;
+        closeMenu(false);
+    };
+    const handleFocusIn = (event) => {
+        const target = event.target;
+        if (target && controlElement?.contains(target))
+            return;
+        if (target && panelElement?.contains(target))
+            return;
+        closeMenu(false);
+    };
+    const releaseEscape = pushEscapeHandler((event) => {
+        if (event?.key === 'Escape') {
+            event?.preventDefault();
+            closeMenu();
+        }
+    });
+    document.addEventListener('mousedown', handlePointerDown, true);
+    document.addEventListener('focusin', handleFocusIn, true);
+    return () => {
+        releaseEscape();
+        document.removeEventListener('mousedown', handlePointerDown, true);
+        document.removeEventListener('focusin', handleFocusIn, true);
+    };
+});
+$effect(() => {
+    if (!open || activeIndex < 0)
+        return;
+    const activeOption = document.getElementById(`${id}-option-${activeIndex}`);
+    activeOption?.scrollIntoView?.({ block: 'nearest' });
+});
+</script>
+
+<div class={classNames('cinder-multi-select', className)}>
+  {#if label}
+    <label
+      id={labelId}
+      for={id}
+      class="cinder-multi-select__label"
+      data-disabled={field.disabled || undefined}
+    >
+      {label}
+      {#if field.required}
+        <span class="cinder-_required-marker" aria-hidden="true">*</span>
+      {/if}
+    </label>
+  {/if}
+
+  <div bind:this={controlElement} class="cinder-multi-select__control">
+    <!-- svelte-ignore a11y_role_supports_aria_props_implicit (the focusable picker trigger intentionally mirrors invalid state for assistive tech) -->
+    <button
+      bind:this={triggerElement}
+      type="button"
+      {id}
+      class="cinder-_input-frame cinder-multi-select__trigger"
+      disabled={field.disabled}
+      aria-invalid={triggerAriaInvalid}
+      aria-describedby={triggerDescribedBy}
+      aria-haspopup="listbox"
+      aria-expanded={open}
+      aria-controls={listboxId}
+      data-cinder-invalid={triggerAriaInvalid ? 'true' : undefined}
+      data-cinder-open={open || undefined}
+      data-cinder-has-clear={(selectedCount > 0 && !field.disabled && !readonly) || undefined}
+      data-cinder-readonly={readonly || undefined}
+      onclick={() => (open ? closeMenu() : openMenu())}
+      onkeydown={handleTriggerKeydown}
+    >
+      <span class="cinder-multi-select__summary cinder-_truncate">{triggerSummary}</span>
+      {#if selectedCount > 0}
+        <span class="cinder-multi-select__count" aria-hidden="true">{selectedCount}</span>
+      {/if}
+      <span class="cinder-multi-select__chevron" aria-hidden="true">▾</span>
+    </button>
+
+    {#if selectedCount > 0 && !field.disabled && !readonly}
+      <button
+        type="button"
+        class="cinder-multi-select__clear"
+        aria-label="Clear selected items"
+        onclick={clearSelection}
+      >
+        ×
+      </button>
+    {/if}
+
+    {#if open}
+      <div
+        bind:this={panelElement}
+        id={`${id}-popover`}
+        class="cinder-_floating-surface cinder-multi-select__panel"
+        data-cinder-direction={direction}
+        data-cinder-open
+      >
+        {#if filterable}
+          <input
+            bind:this={filterElement}
+            id={filterId}
+            class="cinder-_input-frame cinder-multi-select__filter"
+            type="text"
+            role="combobox"
+            placeholder="Filter options"
+            value={query}
+            aria-labelledby={filterAriaLabelledBy}
+            aria-autocomplete="list"
+            aria-haspopup="listbox"
+            aria-expanded={open}
+            aria-readonly={readonly || undefined}
+            {readonly}
+            aria-controls={listboxId}
+            aria-activedescendant={activeOptionId}
+            oninput={handleFilterInput}
+            onkeydown={handleFilterKeydown}
+          />
+        {/if}
+        <ul
+          bind:this={listboxElement}
+          id={listboxId}
+          role="listbox"
+          class="cinder-multi-select__listbox"
+          aria-multiselectable="true"
+          aria-labelledby={listboxLabelledBy}
+          aria-label={listboxLabelledBy ? undefined : 'Options'}
+          aria-required={field.required || undefined}
+          aria-readonly={readonly || undefined}
+          aria-activedescendant={filterable ? undefined : activeOptionId}
+          tabindex={filterable ? -1 : 0}
+          onkeydown={handleListNavigationKeydown}
+        >
+          {#each visibleItems as item, index (item.id)}
+            <li
+              id="{id}-option-{index}"
+              role="option"
+              class="cinder-_option-row cinder-multi-select__option"
+              aria-selected={selectedSet.has(item.id)}
+              aria-disabled={item.disabled || undefined}
+              data-cinder-active={activeIndex === index || undefined}
+              onmousedown={(event) => {
+                event.preventDefault();
+                if (item.disabled) return;
+                activeIndex = index;
+                toggleItem(item);
+              }}
+              onmouseenter={() => {
+                if (item.disabled) return;
+                activeIndex = index;
+              }}
+            >
+              <span class="cinder-multi-select__checkbox" aria-hidden="true">
+                {#if selectedSet.has(item.id)}✓{/if}
+              </span>
+              <span class="cinder-multi-select__option-text">
+                <span class="cinder-multi-select__option-label">{item.label}</span>
+                {#if item.description}
+                  <span class="cinder-multi-select__option-description">{item.description}</span>
+                {/if}
+              </span>
+            </li>
+          {:else}
+            <li
+              class="cinder-multi-select__empty"
+              role="option"
+              aria-disabled="true"
+              aria-selected="false"
+            >
+              {emptyListMessage}
+            </li>
+          {/each}
+        </ul>
+      </div>
+    {/if}
+  </div>
+
+  {#if filterable}
+    <p class="cinder-multi-select__sr-status" role="status" aria-live="polite">
+      {open && visibleItems.length === 0 ? emptyListMessage : ''}
+    </p>
+    <span id={filterLabelHintId} class="cinder-multi-select__sr-status">Filter options</span>
+  {/if}
+
+  <input
+    bind:this={validityProxyElement}
+    type="text"
+    tabindex="-1"
+    aria-hidden="true"
+    class="cinder-multi-select__validation-proxy"
+    value={selectedCount > 0 ? 'selected' : ''}
+    required={field.required}
+    disabled={field.disabled}
+    oninvalid={handleProxyInvalid}
+  />
+
+  {#if name}
+    {#each uniqueSelectedIds as selectedId (selectedId)}
+      <input type="hidden" {name} value={selectedId} disabled={field.disabled} />
+    {/each}
+  {/if}
+
+  {#if description}
+    <p id={field.ownDescriptionId} class="cinder-multi-select__description">{description}</p>
+  {/if}
+
+  {#if warning}
+    <p id={warningId} class="cinder-multi-select__warning">{warning}</p>
+  {/if}
+
+  <p
+    id={field.ownErrorId ?? stableLocalErrorId}
+    class="cinder-multi-select__error"
+    aria-live="polite"
+    data-cinder-error={!!error || !!nativeError || undefined}
+  >
+    {error ?? nativeError}
+  </p>
+</div>

package/src/components/multi-select/multi-select.types.ts

@@ -0,0 +1,53 @@
+export type MultiSelectItem<T extends string = string> = {
+  /** Submitted/stored identifier. */
+  id: T;
+  /** Visible option label. */
+  label: string;
+  /** Optional secondary line shown under the label. */
+  description?: string;
+  /** Non-selectable option row. */
+  disabled?: boolean;
+};
+
+export type MultiSelectSelectionFeedback = 'top' | 'fixed' | 'top-after-reopen';
+
+export type MultiSelectDirection = 'down' | 'up';
+
+export type MultiSelectProps<T extends string = string> = {
+  /** Unique identifier — required for label association and ARIA wiring. */
+  id: string;
+  /** Full option set. The sole inference source for T. */
+  items: readonly MultiSelectItem<T>[];
+  /** Bindable selected IDs. */
+  selectedIds?: NoInfer<T>[];
+  /** Native form field name. Emits one hidden input per selected id. */
+  name?: string;
+  /** Visible label rendered in a `<label>` associated via `for`. */
+  label?: string;
+  /** Placeholder text when nothing is selected. */
+  placeholder?: string;
+  /** Helper text displayed below the trigger; wired via aria-describedby. */
+  description?: string;
+  /** Validation error message; sets aria-invalid="true". */
+  error?: string;
+  /** Warning text rendered below the control and included in aria-describedby. */
+  warning?: string;
+  /** Disables the control. Inherited from a wrapping FormField when unset. */
+  disabled?: boolean;
+  /** Prevents changing selection while still allowing viewing current selections. */
+  readonly?: boolean;
+  /** Marks the field required and shows the required marker on the label. */
+  required?: boolean;
+  /** Enables the filter input rendered above the options list. */
+  filterable?: boolean;
+  /** Custom option filter callback. Defaults to case-insensitive label/description matching. */
+  filterItem?: (item: MultiSelectItem<T>, query: string) => boolean;
+  /** Selected-option ordering behavior when the menu is open. */
+  selectionFeedback?: MultiSelectSelectionFeedback;
+  /** Open direction for the floating panel. */
+  direction?: MultiSelectDirection;
+  /** Additional class names merged with `.cinder-multi-select`. */
+  class?: string;
+  /** External id(s) composed into aria-describedby. */
+  'aria-describedby'?: string;
+};

package/src/components/multi-select/multi-select.variables.ts

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

package/src/components/navigation-bar/index.ts

@@ -0,0 +1,14 @@
+import './navigation-bar.css';
+import NavigationBar from './navigation-bar.svelte';
+
+export default NavigationBar;
+export type {
+  NavigationBarItemsContext,
+  NavigationBarLabelVisibility,
+  NavigationBarMenuTogglePlacement,
+  NavigationBarPlacement,
+  NavigationBarProps,
+  NavigationBarToggleAttributes,
+  NavigationVariant,
+} from './navigation-bar.types.ts';
+export { NavigationBar };

package/src/components/navigation-bar/navigation-bar.schema.ts

@@ -0,0 +1,66 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    class: {
+      type: 'string',
+      description: 'Custom class merged onto the root `<nav>` element.',
+    },
+    placement: {
+      enum: ['top', 'bottom'],
+      description:
+        'Visual placement mode. `bottom` renders a mobile tab-bar composition, but\nstill does not fix or stick itself to the viewport.',
+      default: 'top',
+    },
+    showLabels: {
+      enum: ['always', 'active', 'never'],
+      description:
+        'Label visibility for mobile bottom-tab compositions. Hidden labels remain in\nthe accessibility tree when wrapped in `[data-cinder-navigation-label]`.',
+      default: 'always',
+    },
+    menuTogglePlacement: {
+      enum: ['after-brand', 'before-brand'],
+      description:
+        'Placement for the collapsible mobile menu toggle in top navigation bars.\nIgnored for `placement="bottom"`.',
+      default: 'after-brand',
+    },
+    mobileMenuOpen: {
+      type: 'boolean',
+      description: 'Two-way bindable open state of the mobile menu.',
+    },
+    label: {
+      type: 'string',
+      description:
+        "Accessible name for the <nav> landmark. Wins over any aria-label passed via rest. Default 'Main navigation'.",
+    },
+  },
+  additionalProperties: false,
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'actions',
+        reason: 'function-or-snippet',
+      },
+      {
+        name: 'brand',
+        reason: 'function-or-snippet',
+      },
+      {
+        name: 'items',
+        reason: 'function-or-snippet',
+        required: true,
+        description: 'Receives a context object with the current variant.',
+      },
+      {
+        name: 'menuToggle',
+        reason: 'function-or-snippet',
+        description:
+          'Snippet receiving toggle button attributes. Consumer renders the actual <button> and should mark decorative glyphs or icons inside it as aria-hidden so the button name comes from text or aria-label, not the ornament.',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;