@sveltia/ui 0.64.0 → 0.65.1

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

@@ -24,7 +24,7 @@ declare const Drawer: import("svelte").Component<ModalProps & {
     /**
      * Position of the drawer.
      */
-    position?: "top" | "right" | "bottom" | "left" | undefined;
+    position?: "top" | "left" | "right" | "bottom" | undefined;
     /**
      * Width or height of the
      * drawer.
@@ -75,7 +75,7 @@ type Props = {
     /**
      * Position of the drawer.
      */
-    position?: "top" | "right" | "bottom" | "left" | undefined;
+    position?: "top" | "left" | "right" | "bottom" | undefined;
     /**
      * Width or height of the
      * drawer.

package/dist/components/emoji/cache.d.ts

@@ -0,0 +1,3 @@
+export function getCachedEmojiData(): Promise<EmojiData | undefined>;
+export function cacheEmojiData(data: EmojiData): Promise<void>;
+import type { EmojiData } from '../../typedefs';

package/dist/components/emoji/cache.js

@@ -0,0 +1,96 @@
+import { IndexedDB } from '@sveltia/utils/storage';
+import { EMOJILIB_VERSION } from './loader.js';
+
+/**
+ * @import { EmojiData } from '../../typedefs';
+ */
+
+/**
+ * Client-side cache for the emoji data.
+ *
+ * The data is a few hundred kilobytes fetched from a CDN, and it never changes for a given version,
+ * so it’s worth keeping locally rather than going back to the network on every page load. IndexedDB
+ * is used rather than local storage because the payload is large enough to matter against the local
+ * storage quota, and because writing it there would block the main thread.
+ */
+
+const DATABASE_NAME = 'sveltia-ui';
+const STORE_NAME = 'emoji';
+/** Key of the sole entry, scoped to the version the data came from. */
+const KEY = `${EMOJILIB_VERSION}/data`;
+/** @type {IndexedDB | undefined | null} `null` once the store is known to be unusable. */
+let database;
+/** @type {Promise<void> | undefined} */
+let purgePromise;
+
+/**
+ * Get the store, or `null` when IndexedDB is unavailable, as in a server-side render or with
+ * storage blocked.
+ * @returns {IndexedDB | null} Store.
+ */
+const getDatabase = () => {
+  if (database === undefined) {
+    database = typeof indexedDB === 'undefined' ? null : new IndexedDB(DATABASE_NAME, STORE_NAME);
+  }
+
+  return database;
+};
+
+/**
+ * Drop anything cached for a different version, once per session. A version bump changes the key,
+ * so the old payload would otherwise linger forever.
+ * @param {IndexedDB} db Store.
+ * @returns {Promise<void>} Nothing.
+ */
+const purgeStaleVersions = async (db) => {
+  purgePromise ??= (async () => {
+    const stale = (await db.keys()).filter((key) => key !== KEY);
+
+    if (stale.length) {
+      await db.deleteEntries(stale);
+    }
+  })();
+
+  return purgePromise;
+};
+
+/**
+ * Read the cached emoji data.
+ * @returns {Promise<EmojiData | undefined>} Cached data, or `undefined` when not cached or
+ * unreadable.
+ */
+export const getCachedEmojiData = async () => {
+  const db = getDatabase();
+
+  if (!db) {
+    return undefined;
+  }
+
+  try {
+    await purgeStaleVersions(db);
+
+    return await db.get(KEY);
+  } catch {
+    // A failed cache read just means fetching again
+    return undefined;
+  }
+};
+
+/**
+ * Store the emoji data.
+ * @param {EmojiData} data Emoji data.
+ * @returns {Promise<void>} Nothing.
+ */
+export const cacheEmojiData = async (data) => {
+  const db = getDatabase();
+
+  if (!db) {
+    return;
+  }
+
+  try {
+    await db.set(KEY, data);
+  } catch {
+    // Out of quota or storage blocked: not worth failing over, the data is already in hand
+  }
+};

package/dist/components/emoji/caret.d.ts

@@ -0,0 +1,2 @@
+export function getFieldCaretRect(element: HTMLInputElement | HTMLTextAreaElement, start: number, end: number): EmojiAnchorRect | undefined;
+import type { EmojiAnchorRect } from '../../typedefs';

package/dist/components/emoji/caret.js

@@ -0,0 +1,106 @@
+/**
+ * @import { EmojiAnchorRect } from '../../typedefs';
+ */
+
+/**
+ * CSS properties copied from the field onto the mirror element, so the mirror wraps and spaces the
+ * text exactly as the field does. Anything that affects the position of a character has to be here.
+ */
+const MIRROR_STYLE_PROPERTIES = [
+  'boxSizing',
+  'width',
+  'borderTopWidth',
+  'borderRightWidth',
+  'borderBottomWidth',
+  'borderLeftWidth',
+  'paddingTop',
+  'paddingRight',
+  'paddingBottom',
+  'paddingLeft',
+  'fontFamily',
+  'fontSize',
+  'fontStretch',
+  'fontStyle',
+  'fontVariant',
+  'fontWeight',
+  'letterSpacing',
+  'lineHeight',
+  'tabSize',
+  'textAlign',
+  'textIndent',
+  'textTransform',
+  'wordBreak',
+  'wordSpacing',
+  'overflowWrap',
+  'direction',
+];
+
+/**
+ * Get the viewport-relative bounds of a range of characters within a text field.
+ *
+ * An `<input>` or `<textarea>` gives no way to ask where a character sits, so the field is
+ * replicated with a hidden element carrying the same text and the same typography, and the range is
+ * measured there. Only the offset within the mirror is used, which is then applied to the field’s
+ * own position, so neither element has to be positioned relative to the other.
+ * @param {HTMLInputElement | HTMLTextAreaElement} element Text field.
+ * @param {number} start Index of the first character.
+ * @param {number} end Index just past the last character.
+ * @returns {EmojiAnchorRect | undefined} Bounds, or `undefined` if the field isn’t laid out.
+ * @see https://github.com/component/textarea-caret-position
+ */
+export const getFieldCaretRect = (element, start, end) => {
+  const fieldRect = element.getBoundingClientRect();
+
+  // The field is hidden or detached, so there is nothing to anchor to
+  if (!fieldRect.width && !fieldRect.height) {
+    return undefined;
+  }
+
+  const style = globalThis.getComputedStyle(element);
+  const singleLine = element.tagName === 'INPUT';
+  const mirror = document.createElement('div');
+  const marker = document.createElement('span');
+
+  MIRROR_STYLE_PROPERTIES.forEach((property) => {
+    /** @type {Record<string, any>} */ (mirror.style)[property] =
+      /** @type {Record<string, any>} */ (style)[property];
+  });
+
+  Object.assign(mirror.style, {
+    position: 'absolute',
+    top: '0',
+    left: '0',
+    height: 'auto',
+    minHeight: '0',
+    maxHeight: 'none',
+    overflow: 'hidden',
+    visibility: 'hidden',
+    pointerEvents: 'none',
+    // A single-line field never wraps, however long the value is
+    whiteSpace: singleLine ? 'pre' : 'pre-wrap',
+  });
+
+  mirror.setAttribute('aria-hidden', 'true');
+  mirror.textContent = element.value.slice(0, start);
+  // A zero-width space keeps the marker measurable when the range is empty
+  marker.textContent = element.value.slice(start, end) || '\u200B';
+  mirror.append(marker);
+  document.body.append(mirror);
+
+  const mirrorRect = mirror.getBoundingClientRect();
+  const markerRects = marker.getClientRects();
+  // A wrapped range spans several lines; the last one is where the caret is
+  const markerRect = markerRects[markerRects.length - 1] ?? marker.getBoundingClientRect();
+  const offsetTop = markerRect.top - mirrorRect.top;
+  const offsetLeft = markerRect.left - mirrorRect.left;
+  const offsetRight = markerRect.right - mirrorRect.left;
+  const height = markerRect.height || Number.parseFloat(style.lineHeight) || 0;
+
+  mirror.remove();
+
+  const top = fieldRect.top + offsetTop - element.scrollTop;
+  const left = fieldRect.left + offsetLeft - element.scrollLeft;
+  const right = fieldRect.left + offsetRight - element.scrollLeft;
+
+  return { top, bottom: top + height, left, right };
+};

package/dist/components/emoji/emoji-suggestions.svelte

@@ -0,0 +1,424 @@
+<!--
+  @component
+  The dropdown shown while an emoji shortcode is being typed, along with the state behind it. This
+  knows nothing about where the text is being typed; a host component detects the shortcode, feeds
+  it in with {@link update} and applies the chosen emoji through the `onSelect` callback.
+
+  The list is rendered in the top layer with the Popover API, so it’s never clipped by whatever
+  contains the field, and it never takes the focus, so the user can keep typing to narrow down the
+  suggestions.
+  @see https://developer.mozilla.org/en-US/docs/Web/API/Popover_API
+-->
+<script>
+  import { _ } from '@sveltia/i18n';
+  import { onMount } from 'svelte';
+  import { loadEmojiList, searchEmojis } from './emoji.js';
+
+  /**
+   * @import { EmojiAnchorRect, EmojiEntry, EmojiTrigger } from '../../typedefs';
+   */
+
+  /**
+   * @typedef {object} Props
+   * @property {(trigger: EmojiTrigger) => EmojiAnchorRect | undefined} getAnchorRect Get the
+   * viewport-relative bounds of the shortcode being typed, which the dropdown is anchored to.
+   * @property {(entry: EmojiEntry, trigger: EmojiTrigger) => void} onSelect Called with the emoji
+   * the user picked and the shortcode it should replace.
+   * @property {HTMLElement} [ariaOwner] The element holding the caret, which is labelled with the
+   * highlighted suggestion because the focus never moves to the dropdown.
+   */
+
+  /**
+   * @type {Props}
+   */
+  let {
+    /* eslint-disable prefer-const */
+    getAnchorRect,
+    onSelect,
+    ariaOwner = undefined,
+    /* eslint-enable prefer-const */
+  } = $props();
+
+  /**
+   * Estimated size of the dropdown, used to decide whether it fits below the caret. The width is
+   * also enforced in the stylesheet below.
+   */
+  const LIST_WIDTH = 280;
+  const LIST_MAX_HEIGHT = 280;
+  /**
+   * Gap between the dropdown and the caret, and the minimum margin to the viewport edges.
+   */
+  const LIST_OFFSET = 4;
+  const VIEWPORT_MARGIN = 8;
+
+  const listId = $props.id();
+
+  /**
+   * The shortcode currently being typed, if any.
+   * @type {EmojiTrigger | undefined}
+   */
+  let trigger = $state();
+  /**
+   * Emojis matching the {@link trigger}’s query.
+   * @type {EmojiEntry[]}
+   */
+  let candidates = $state([]);
+  /**
+   * Index of the highlighted candidate.
+   * @type {number}
+   */
+  let selectedIndex = $state(0);
+  /**
+   * Viewport-relative bounds of the shortcode being typed.
+   * @type {EmojiAnchorRect | undefined}
+   */
+  let anchorRect = $state();
+  /**
+   * A reference to the dropdown element, which is only mounted while suggestions are shown.
+   * @type {HTMLElement | undefined}
+   */
+  let listElement = $state();
+  /**
+   * Monotonically increasing counter used to discard the result of a search that has been
+   * superseded while the emoji list was being loaded.
+   * @type {number}
+   */
+  let searchGeneration = 0;
+  /**
+   * Identifier of the shortcode the user has dismissed with the Escape key, so the suggestions
+   * don’t come back while they keep typing it.
+   * @type {string | undefined}
+   */
+  let dismissedShortcodeId = $state();
+
+  const open = $derived(!!trigger && !!candidates.length);
+
+  /**
+   * Position of the dropdown, flipped above the caret and clamped to the viewport as needed.
+   *
+   * The dropdown grows away from the start of the line, so it follows the reading direction rather
+   * than reaching back across the text: in a right-to-left layout it hangs from the shortcode’s
+   * right edge and extends leftwards, mirroring what `activatePopup()` does for anchored popups.
+   */
+  const position = $derived.by(() => {
+    if (!anchorRect) {
+      return undefined;
+    }
+
+    const { innerWidth, innerHeight } = window;
+    const spaceBelow = innerHeight - anchorRect.bottom;
+    const spaceAbove = anchorRect.top;
+    const flipped = spaceBelow < LIST_MAX_HEIGHT + VIEWPORT_MARGIN && spaceAbove > spaceBelow;
+    const rtl = document.dir === 'rtl';
+    const anchorLeft = rtl ? anchorRect.right - LIST_WIDTH : anchorRect.left;
+
+    return {
+      top: flipped ? undefined : `${Math.round(anchorRect.bottom + LIST_OFFSET)}px`,
+      bottom: flipped ? `${Math.round(innerHeight - anchorRect.top + LIST_OFFSET)}px` : undefined,
+      left: `${Math.round(
+        Math.max(VIEWPORT_MARGIN, Math.min(anchorLeft, innerWidth - LIST_WIDTH - VIEWPORT_MARGIN)),
+      )}px`,
+      maxHeight: `${Math.round(
+        Math.min(
+          LIST_MAX_HEIGHT,
+          (flipped ? spaceAbove : spaceBelow) - LIST_OFFSET - VIEWPORT_MARGIN,
+        ),
+      )}px`,
+    };
+  });
+
+  /**
+   * Whether any suggestions are currently shown.
+   * @returns {boolean} Result.
+   */
+  export const isOpen = () => open;
+
+  /**
+   * Close the list and forget the current shortcode.
+   * @param {boolean} [dismissed] Whether the user has dismissed the list, in which case it stays
+   * closed until they move on to another shortcode.
+   */
+  export const close = (dismissed = false) => {
+    dismissedShortcodeId = dismissed && trigger ? trigger.id : undefined;
+    trigger = undefined;
+    candidates = [];
+    selectedIndex = 0;
+    anchorRect = undefined;
+    searchGeneration += 1;
+  };
+
+  /**
+   * Feed the shortcode being typed into the list, or nothing to close it.
+   * @param {EmojiTrigger} [newTrigger] Shortcode state.
+   */
+  export const update = async (newTrigger) => {
+    if (!newTrigger) {
+      if (trigger || dismissedShortcodeId) {
+        close();
+      }
+
+      return;
+    }
+
+    // The user has dismissed this very shortcode with the Escape key
+    if (dismissedShortcodeId === newTrigger.id) {
+      return;
+    }
+
+    const { id, query } = newTrigger;
+
+    dismissedShortcodeId = undefined;
+    anchorRect = getAnchorRect(newTrigger);
+
+    // The caret may have moved without the query changing, e.g. with an undo; keep the existing
+    // suggestions in that case, so the highlighted item doesn’t jump back to the top
+    if (trigger?.id === id && trigger.query === query) {
+      trigger = newTrigger;
+
+      return;
+    }
+
+    trigger = newTrigger;
+    searchGeneration += 1;
+
+    const generation = searchGeneration;
+
+    await loadEmojiList();
+
+    // Bail out if the user has kept typing in the meantime
+    if (generation !== searchGeneration) {
+      return;
+    }
+
+    candidates = searchEmojis(query);
+    selectedIndex = 0;
+  };
+
+  /**
+   * Move the highlight by the given amount, wrapping around at both ends.
+   * @param {number} delta Number of items to move.
+   */
+  export const moveSelection = (delta) => {
+    const { length } = candidates;
+
+    if (length) {
+      selectedIndex = (selectedIndex + delta + length) % length;
+    }
+  };
+
+  /**
+   * Apply the highlighted suggestion and close the list.
+   */
+  export const selectHighlighted = () => {
+    const entry = candidates[selectedIndex];
+
+    if (entry && trigger) {
+      onSelect(entry, trigger);
+    }
+
+    close();
+  };
+
+  /**
+   * Handle a `keydown` event on the field the list is attached to.
+   * @param {KeyboardEvent} event `keydown` event.
+   * @returns {boolean} `true` if the list consumed the event, in which case the field should
+   * ignore it.
+   */
+  export const handleKeyDown = (event) => {
+    const { key, altKey, ctrlKey, metaKey, shiftKey } = event;
+
+    if (!open || altKey || ctrlKey || metaKey) {
+      return false;
+    }
+
+    if (key === 'ArrowDown' || key === 'ArrowUp') {
+      moveSelection(key === 'ArrowDown' ? 1 : -1);
+    } else if ((key === 'Enter' || key === 'Tab') && !shiftKey) {
+      selectHighlighted();
+    } else if (key === 'Escape') {
+      close(true);
+    } else {
+      return false;
+    }
+
+    event.preventDefault();
+
+    return true;
+  };
+
+  // Move the dropdown to the top layer, so it’s not clipped by anything around the field
+  $effect(() => {
+    if (listElement && !listElement.matches(':popover-open')) {
+      listElement.showPopover?.();
+    }
+  });
+
+  // Advertise that typing here can bring up predictions, for as long as the autocomplete is
+  // attached. `aria-autocomplete` applies to a textbox as much as to a combobox, so the field keeps
+  // whatever role it already had rather than being relabelled — a rich text editor is not a
+  // combobox, and neither is a comment field. `list` says the predictions appear in a popup rather
+  // than being completed inline.
+  // @see https://w3c.github.io/aria/#aria-autocomplete
+  $effect(() => {
+    if (!ariaOwner) {
+      return undefined;
+    }
+
+    const owner = ariaOwner;
+
+    owner.setAttribute('aria-autocomplete', 'list');
+    owner.setAttribute('aria-haspopup', 'listbox');
+
+    return () => {
+      owner.removeAttribute('aria-autocomplete');
+      owner.removeAttribute('aria-haspopup');
+    };
+  });
+
+  // Point at the highlighted suggestion, given the focus stays in the field. The list is only in
+  // the DOM while open, so it can only be referenced while it is. There is deliberately no
+  // `aria-expanded`, which a textbox doesn’t support; the active descendant appearing and
+  // disappearing is what conveys the list opening and closing.
+  $effect(() => {
+    if (!ariaOwner) {
+      return undefined;
+    }
+
+    const owner = ariaOwner;
+
+    if (open) {
+      owner.setAttribute('aria-controls', listId);
+      owner.setAttribute('aria-activedescendant', `${listId}-option-${selectedIndex}`);
+    } else {
+      owner.removeAttribute('aria-controls');
+      owner.removeAttribute('aria-activedescendant');
+    }
+
+    return () => {
+      owner.removeAttribute('aria-controls');
+      owner.removeAttribute('aria-activedescendant');
+    };
+  });
+
+  // Keep the highlighted suggestion visible while the user arrows through a long list
+  $effect(() => {
+    void selectedIndex;
+
+    listElement?.querySelector('[aria-selected="true"]')?.scrollIntoView({ block: 'nearest' });
+  });
+
+  onMount(() => {
+    // Warm the data up front, so the first shortcode the user types shows suggestions straight away
+    // rather than waiting on the network. The loader memoizes, so this costs one request per page
+    // however many fields are on it, and nothing at all once it’s cached.
+    loadEmojiList();
+
+    /**
+     * Follow the caret when the page or an ancestor is scrolled or the window is resized.
+     */
+    const reposition = () => {
+      if (trigger) {
+        anchorRect = getAnchorRect(trigger);
+      }
+    };
+
+    window.addEventListener('scroll', reposition, { capture: true, passive: true });
+    window.addEventListener('resize', reposition, { passive: true });
+
+    return () => {
+      window.removeEventListener('scroll', reposition, { capture: true });
+      window.removeEventListener('resize', reposition);
+    };
+  });
+</script>
+
+{#if open && position}
+  <div
+    bind:this={listElement}
+    id={listId}
+    role="listbox"
+    class="sui emoji-suggestions"
+    aria-label={_('_sui.emoji_suggestions')}
+    popover="manual"
+    style:top={position.top}
+    style:bottom={position.bottom}
+    style:left={position.left}
+    style:max-height={position.maxHeight}
+  >
+    {#each candidates as entry, index (entry.emoji)}
+      <div
+        id="{listId}-option-{index}"
+        role="option"
+        class="option"
+        tabindex="-1"
+        aria-selected={index === selectedIndex}
+        onmouseenter={() => {
+          selectedIndex = index;
+        }}
+        onmousedown={(event) => {
+          // Keep the focus and the caret where they are, so the shortcode can be replaced
+          event.preventDefault();
+          selectedIndex = index;
+          selectHighlighted();
+        }}
+      >
+        <span role="none" class="emoji">{entry.emoji}</span>
+        <span role="none" class="name">:{entry.name}:</span>
+      </div>
+    {/each}
+  </div>
+{/if}
+
+<style>.emoji-suggestions {
+  position: fixed;
+  inset: auto;
+  z-index: 1000;
+  display: flex;
+  flex-direction: column;
+  overflow-y: auto;
+  margin: 0;
+  border-width: var(--sui-listbox-border-width, 1px);
+  border-style: var(--sui-listbox-border-style, solid);
+  border-color: var(--sui-listbox-border-width, var(--sui-secondary-border-color));
+  border-radius: var(--sui-listbox-border-radius, 4px);
+  padding: var(--sui-listbox-padding, 4px);
+  width: 280px;
+  color: var(--sui-primary-foreground-color);
+  background-color: var(--sui-secondary-background-color-translucent);
+  box-shadow: 0 8px 16px var(--sui-popup-shadow-color);
+  -webkit-backdrop-filter: blur(16px);
+  backdrop-filter: blur(16px);
+  font-family: var(--sui-control-font-family);
+  font-size: var(--sui-control-font-size);
+  line-height: var(--sui-control-line-height);
+  -webkit-user-select: none;
+  user-select: none;
+}
+
+.option {
+  flex: none;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  border-radius: var(--sui-option-border-radius);
+  padding: var(--sui-option-padding);
+  min-height: var(--sui-option-height);
+  cursor: default;
+}
+.option[aria-selected=true] {
+  color: var(--sui-highlight-foreground-color);
+  background-color: var(--sui-hover-background-color);
+}
+.option .emoji {
+  flex: none;
+  width: 1.5em;
+  font-size: var(--sui-font-size-large);
+  text-align: center;
+}
+.option .name {
+  flex: auto;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}</style>