@cloudvoyant/helical-svelte 0.20.1 → 0.21.0

package/dist/which-key/WhichKey.svelte

@@ -0,0 +1,197 @@
+<!-- libs/helical-svelte/src/which-key/WhichKey.svelte -->
+<script lang="ts">
+  import { Portal } from '@ark-ui/svelte/portal';
+  import { Presence } from '@ark-ui/svelte/presence';
+  import {
+    cn,
+    jumpBadgeMatchedPrefixBase,
+    jumpBadgeVariants,
+    jumpOverlayRootBase,
+    whichKeyBodyVariants,
+    whichKeyBreadcrumbBase,
+    whichKeyFooterBase,
+    whichKeyHeaderBase,
+    whichKeyItemBase,
+    whichKeyItemLabelBase,
+    whichKeyTitleBase,
+    whichKeyVariants,
+    type WhichKeyProps as CoreWhichKeyProps,
+  } from '@cloudvoyant/helical-ui';
+  import Kbd from '../Kbd.svelte';
+  import Row from '../Row.svelte';
+  import Scroll from '../Scroll.svelte';
+  import { getOptionalWhichKeyContext } from './context.svelte';
+  import WhichKeyExplorer from './WhichKeyExplorer.svelte';
+  import WhichKeyMode from './WhichKeyMode.svelte';
+
+  type Props = Omit<CoreWhichKeyProps, 'className'> & {
+    class?: string;
+    className?: string;
+  };
+
+  let {
+    variant = 'helix',
+    showModeBadge = true,
+    showExplorer = true,
+    class: className = '',
+    className: reactClassName = '',
+  }: Props = $props();
+
+  const ctx = getOptionalWhichKeyContext();
+
+  let panelRef: HTMLDivElement | null = $state(null);
+  let jumpOverlayRef: HTMLDivElement | null = $state(null);
+
+  $effect(() => {
+    if (!ctx?.state.isOpen) return;
+    return ctx.controller.trackBranchElement(() => panelRef);
+  });
+
+  $effect(() => {
+    if (ctx?.state.mode !== 'jump') return;
+    return ctx.controller.trackBranchElement(() => jumpOverlayRef);
+  });
+</script>
+
+{#if ctx}
+  <Portal>
+    <Presence present={ctx.state.isOpen} lazyMount unmountOnExit>
+      <div
+        bind:this={panelRef}
+        role="region"
+        aria-label={ctx.state.title || 'WhichKey commands'}
+        data-which-key-root="true"
+        data-testid="which-key-panel"
+        data-variant={variant}
+        data-preset={ctx.state.preset}
+        data-mode={ctx.state.mode}
+        data-sticky={ctx.state.sticky ? 'true' : 'false'}
+        class={cn(whichKeyVariants({ variant }), className, reactClassName)}
+      >
+        <div class={whichKeyHeaderBase}>
+          <div class={whichKeyTitleBase}>
+            {#if showModeBadge}
+              <WhichKeyMode mode={ctx.state.mode} sticky={ctx.state.sticky} />
+            {/if}
+            <span data-testid="which-key-title">
+              {ctx.state.title === 'Space' ? 'Leader' : ctx.state.title}
+            </span>
+            {#if ctx.state.countBuffer}
+              <span
+                data-testid="which-key-count"
+                class="rounded bg-muted px-1 font-mono text-[10px]"
+              >
+                {ctx.state.countBuffer}×
+              </span>
+            {/if}
+          </div>
+          <div
+            data-testid="which-key-breadcrumb"
+            class={whichKeyBreadcrumbBase}
+          >
+            <span>{ctx.state.breadcrumb.join(' » ')}</span>
+          </div>
+        </div>
+
+        <Scroll class="max-h-72" viewportClass="max-h-72">
+          <div
+            data-testid="which-key-items"
+            class={whichKeyBodyVariants({ variant })}
+          >
+            {#each ctx.state.items as node (node.key)}
+              {@const isGroup = Boolean(
+                node.children || node.proxy || node.expand || node.label.startsWith('+'),
+              )}
+              <button
+                type="button"
+                data-testid="which-key-item"
+                data-key={node.key}
+                data-group={isGroup ? 'true' : 'false'}
+                onclick={(e: MouseEvent) => {
+                  e.preventDefault();
+                  e.stopPropagation();
+                  ctx.controller.triggerKey(node.key);
+                }}
+                class={whichKeyItemBase}
+              >
+                <span
+                  data-group={isGroup ? 'true' : 'false'}
+                  class={whichKeyItemLabelBase}
+                >
+                  {node.label}
+                </span>
+                <Kbd
+                  size="sm"
+                  variant={isGroup ? 'subtle' : 'outline'}
+                  hotkey={node.key}
+                />
+              </button>
+            {/each}
+          </div>
+        </Scroll>
+
+        <div class={whichKeyFooterBase}>
+          <Row class="items-center gap-2">
+            {#if ctx.state.breadcrumb.length > 1}
+              <button
+                type="button"
+                onclick={() => ctx.controller.stepBackPrefix()}
+                class="inline-flex items-center gap-1 hover:text-foreground"
+              >
+                <Kbd size="sm">⌫</Kbd>
+                <span>Back</span>
+              </button>
+            {/if}
+            <button
+              type="button"
+              onclick={() => ctx.controller.closePrefix()}
+              class="inline-flex items-center gap-1 hover:text-foreground"
+            >
+              <Kbd size="sm">Esc</Kbd>
+              <span>Close</span>
+            </button>
+          </Row>
+          <span class="font-mono uppercase opacity-75">
+            {ctx.state.preset}
+          </span>
+        </div>
+      </div>
+    </Presence>
+  </Portal>
+
+  <Portal>
+    <Presence
+      present={ctx.state.mode === 'jump' && ctx.state.jumpTargets.length > 0}
+      lazyMount
+      unmountOnExit
+    >
+      <div
+        bind:this={jumpOverlayRef}
+        data-which-key-jump-overlay="true"
+        data-testid="which-key-jump-overlay"
+        data-jump-action={ctx.state.jumpAction}
+        class={jumpOverlayRootBase}
+      >
+        {#each ctx.state.jumpTargets as target (target.id)}
+          <span
+            data-testid="which-key-jump-badge"
+            data-jump-label={target.label}
+            style={`top: ${Math.max(4, target.rect.top - 4)}px; left: ${Math.max(4, target.rect.left - 4)}px;`}
+            class={jumpBadgeVariants({ action: ctx.state.jumpAction })}
+          >
+            {#if target.matchedPrefix}
+              <span class={jumpBadgeMatchedPrefixBase}>
+                {target.matchedPrefix}
+              </span>
+            {/if}
+            <span>{target.remainingLabel}</span>
+          </span>
+        {/each}
+      </div>
+    </Presence>
+  </Portal>
+
+  {#if showExplorer}
+    <WhichKeyExplorer />
+  {/if}
+{/if}

package/dist/which-key/WhichKey.svelte.d.ts

@@ -0,0 +1,8 @@
+import { type WhichKeyProps as CoreWhichKeyProps } from '@cloudvoyant/helical-ui';
+type Props = Omit<CoreWhichKeyProps, 'className'> & {
+    class?: string;
+    className?: string;
+};
+declare const WhichKey: import("svelte").Component<Props, {}, "">;
+type WhichKey = ReturnType<typeof WhichKey>;
+export default WhichKey;

package/dist/which-key/WhichKeyExplorer.svelte

@@ -0,0 +1,269 @@
+<!-- libs/helical-svelte/src/which-key/WhichKeyExplorer.svelte -->
+<script lang="ts">
+  import { Highlight } from '@ark-ui/svelte/highlight';
+  import { createListCollection } from '@ark-ui/svelte/listbox';
+  import {
+    cn,
+    whichKeyExplorerContentBase,
+    whichKeyExplorerHeaderBase,
+    whichKeyExplorerHighlightMarkBase,
+    whichKeyExplorerInputBase,
+    whichKeyExplorerItemBase,
+    whichKeyExplorerListboxBase,
+    whichKeyExplorerListContentBase,
+    whichKeyModeBadgeVariants,
+    type KeymapExplorerEntry,
+    type WhichKeyExplorerProps as CoreWhichKeyExplorerProps,
+  } from '@cloudvoyant/helical-ui';
+  import {
+    Dialog,
+    DialogBackdrop,
+    DialogContent,
+    DialogDismiss,
+    DialogHeader,
+    DialogTitle,
+  } from '../dialog';
+  import Kbd from '../Kbd.svelte';
+  import {
+    Listbox,
+    ListboxContent,
+    ListboxEmpty,
+    ListboxInput,
+    ListboxItem,
+    ListboxItemGroup,
+    ListboxItemGroupLabel,
+    ListboxItemText,
+  } from '../listbox';
+  import Row from '../Row.svelte';
+  import Scroll from '../Scroll.svelte';
+  import { getOptionalWhichKeyContext } from './context.svelte';
+
+  type Props = Omit<CoreWhichKeyExplorerProps, 'className'> & {
+    class?: string;
+    className?: string;
+  };
+
+  let {
+    open: controlledOpen,
+    onOpenChange,
+    placeholder = 'Search keybindings...',
+    class: className = '',
+    className: reactClassName = '',
+  }: Props = $props();
+
+  const ctx = getOptionalWhichKeyContext();
+
+  const isOpen = $derived(controlledOpen ?? Boolean(ctx?.state.explorerOpen));
+  const explorerEntries = $derived(ctx?.state.explorerEntries ?? []);
+  const explorerQuery = $derived(ctx?.state.explorerQuery ?? '');
+  const preset = $derived(ctx?.state.preset ?? 'helix');
+
+  let highlightedId = $state<string | null>(null);
+
+  const groupedEntries = $derived.by((): Array<[string, KeymapExplorerEntry[]]> => {
+    const groups = new Map<string, KeymapExplorerEntry[]>();
+    for (const entry of explorerEntries) {
+      const groupName = entry.group || 'General';
+      const list = groups.get(groupName) ?? [];
+      list.push(entry);
+      groups.set(groupName, list);
+    }
+    return Array.from(groups.entries());
+  });
+
+  const orderedEntries = $derived(groupedEntries.flatMap(([, entries]) => entries));
+
+  const effectiveHighlightedId = $derived.by((): string | null => {
+    if (orderedEntries.length === 0) return null;
+    if (highlightedId && orderedEntries.some((e) => e.id === highlightedId)) {
+      return highlightedId;
+    }
+    return orderedEntries[0]!.id;
+  });
+
+  const collection = $derived(
+    createListCollection({
+      items: orderedEntries.map((entry) => ({
+        value: entry.id,
+        label: entry.label,
+        entry,
+      })),
+    }),
+  );
+
+  $effect(() => {
+    if (!isOpen || typeof document === 'undefined') return;
+    const focusInput = () => {
+      const input = document.querySelector<HTMLInputElement>(
+        '[data-which-key-explorer] [data-testid="which-key-explorer-input"]',
+      );
+      input?.focus();
+    };
+    focusInput();
+    const raf = requestAnimationFrame(focusInput);
+    return () => cancelAnimationFrame(raf);
+  });
+
+  function scrollItemIntoView(id: string) {
+    requestAnimationFrame(() => {
+      if (typeof document === 'undefined') return;
+      const items = Array.from(
+        document.querySelectorAll<HTMLElement>(
+          '[data-which-key-explorer] [data-part="item"]',
+        ),
+      );
+      for (const el of items) {
+        if (el.getAttribute('data-value') === id) {
+          el.scrollIntoView({ block: 'nearest' });
+          break;
+        }
+      }
+    });
+  }
+
+  function handleOpenChange(details: { open: boolean }) {
+    if (!ctx) return;
+    if (details.open) {
+      ctx.controller.openExplorer();
+    } else {
+      ctx.controller.closeExplorer();
+    }
+    onOpenChange?.(details.open);
+  }
+</script>
+
+{#if ctx && isOpen}
+  <Dialog
+    open={isOpen}
+    lazyMount
+    unmountOnExit
+    initialFocusEl={() =>
+      typeof document !== 'undefined'
+        ? document.querySelector<HTMLElement>(
+            '[data-which-key-explorer] [data-testid="which-key-explorer-input"]',
+          )
+        : null}
+    onOpenChange={handleOpenChange}
+  >
+    <DialogBackdrop />
+    <DialogContent
+      data-which-key-explorer="true"
+      data-testid="which-key-explorer"
+      class={cn(whichKeyExplorerContentBase, className, reactClassName)}
+    >
+      <DialogHeader class={whichKeyExplorerHeaderBase}>
+        <Row class="items-center gap-2">
+          <DialogTitle class="text-sm font-semibold">Keybindings</DialogTitle>
+          <span class={whichKeyModeBadgeVariants({ mode: 'normal' })}>
+            {preset}
+          </span>
+        </Row>
+        <DialogDismiss
+          tabindex={-1}
+          class="static opacity-80 hover:opacity-100 focus:ring-0"
+        >
+          {#snippet children()}
+            <Kbd size="sm">Esc</Kbd>
+          {/snippet}
+        </DialogDismiss>
+      </DialogHeader>
+
+      <Listbox
+        {collection}
+        selectionMode="single"
+        highlightedValue={effectiveHighlightedId}
+        onHighlightChange={(details) => {
+          if (details.highlightedValue) {
+            highlightedId = details.highlightedValue;
+          }
+        }}
+        onSelect={(details) => {
+          ctx.controller.executeExplorerEntry(details.value);
+        }}
+        class={whichKeyExplorerListboxBase}
+      >
+        <ListboxInput
+          autofocus
+          autoHighlight
+          data-testid="which-key-explorer-input"
+          {placeholder}
+          value={explorerQuery}
+          oninput={(e: Event) => {
+            ctx.controller.setExplorerQuery((e.currentTarget as HTMLInputElement).value);
+          }}
+          onkeydown={(e: KeyboardEvent) => {
+            if (orderedEntries.length === 0) return;
+            if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
+              e.preventDefault();
+              e.stopPropagation();
+              const delta = e.key === 'ArrowDown' ? 1 : -1;
+              const currentIdx = orderedEntries.findIndex(
+                (item) => item.id === effectiveHighlightedId,
+              );
+              const nextIdx =
+                currentIdx === -1
+                  ? 0
+                  : (currentIdx + delta + orderedEntries.length) %
+                    orderedEntries.length;
+              const nextId = orderedEntries[nextIdx]!.id;
+              highlightedId = nextId;
+              scrollItemIntoView(nextId);
+              return;
+            }
+            if (e.key === 'Enter') {
+              const itemVal = effectiveHighlightedId ?? orderedEntries[0]?.id;
+              if (itemVal) {
+                e.preventDefault();
+                e.stopPropagation();
+                ctx.controller.executeExplorerEntry(itemVal);
+              }
+            }
+          }}
+          class={whichKeyExplorerInputBase}
+        />
+        <Scroll class="max-h-96 min-h-0 flex-1" viewportClass="max-h-96">
+          {#snippet children()}
+            <ListboxContent
+              data-testid="which-key-explorer-list"
+              class={whichKeyExplorerListContentBase}
+            >
+              {#each groupedEntries as [groupName, entries] (groupName)}
+                <ListboxItemGroup>
+                  <ListboxItemGroupLabel>{groupName}</ListboxItemGroupLabel>
+                  {#each entries as entry (entry.id)}
+                    <ListboxItem
+                      item={{
+                        value: entry.id,
+                        label: entry.label,
+                      }}
+                      data-testid="which-key-explorer-item"
+                      data-command-id={entry.commandId}
+                      onclick={() => ctx.controller.executeExplorerEntry(entry)}
+                      class={whichKeyExplorerItemBase}
+                    >
+                      <ListboxItemText class="min-w-0 flex-1 truncate font-medium text-foreground">
+                        <Highlight
+                          text={entry.label}
+                          query={explorerQuery}
+                          ignoreCase
+                          matchAll
+                          class={whichKeyExplorerHighlightMarkBase}
+                        />
+                      </ListboxItemText>
+                      <Row class="shrink-0 items-center gap-1">
+                        <Kbd size="sm" hotkey={entry.chords} />
+                      </Row>
+                    </ListboxItem>
+                  {/each}
+                </ListboxItemGroup>
+              {/each}
+              {#if groupedEntries.length === 0}
+                <ListboxEmpty>No matching keybindings found.</ListboxEmpty>
+              {/if}
+            </ListboxContent>
+          {/snippet}
+        </Scroll>
+      </Listbox>
+    </DialogContent>
+  </Dialog>
+{/if}

package/dist/which-key/WhichKeyExplorer.svelte.d.ts

@@ -0,0 +1,8 @@
+import { type WhichKeyExplorerProps as CoreWhichKeyExplorerProps } from '@cloudvoyant/helical-ui';
+type Props = Omit<CoreWhichKeyExplorerProps, 'className'> & {
+    class?: string;
+    className?: string;
+};
+declare const WhichKeyExplorer: import("svelte").Component<Props, {}, "">;
+type WhichKeyExplorer = ReturnType<typeof WhichKeyExplorer>;
+export default WhichKeyExplorer;

package/dist/which-key/WhichKeyMode.svelte

@@ -0,0 +1,44 @@
+<!-- libs/helical-svelte/src/which-key/WhichKeyMode.svelte -->
+<script lang="ts">
+  import {
+    cn,
+    whichKeyModeBadgeVariants,
+    type WhichKeyModeProps as CoreWhichKeyModeProps,
+  } from '@cloudvoyant/helical-ui';
+  import type { HTMLAttributes } from 'svelte/elements';
+  import { useWhichKey } from './context.svelte';
+
+  type Props = Omit<CoreWhichKeyModeProps, 'className'> &
+    Omit<HTMLAttributes<HTMLSpanElement>, 'children'> & {
+      class?: string;
+      className?: string;
+    };
+
+  let {
+    mode: modeProp,
+    sticky: stickyProp,
+    showPreset = false,
+    size = 'sm',
+    class: className = '',
+    className: reactClassName = '',
+    ...rest
+  }: Props = $props();
+
+  const wk = useWhichKey();
+  const resolvedMode = $derived(modeProp ?? wk.mode);
+  const resolvedSticky = $derived(stickyProp ?? wk.sticky);
+  const modeLabel = $derived(resolvedSticky ? `${resolvedMode}·lock` : resolvedMode);
+  const label = $derived(showPreset ? `${wk.preset} · ${modeLabel}` : modeLabel);
+</script>
+
+<span
+  data-slot="which-key-mode"
+  data-testid="which-key-mode-badge"
+  data-mode={resolvedMode}
+  data-sticky={resolvedSticky ? 'true' : 'false'}
+  data-preset={wk.preset}
+  class={cn(whichKeyModeBadgeVariants({ mode: resolvedMode, size }), className, reactClassName)}
+  {...rest}
+>
+  {label}
+</span>

package/dist/which-key/WhichKeyMode.svelte.d.ts

@@ -0,0 +1,9 @@
+import { type WhichKeyModeProps as CoreWhichKeyModeProps } from '@cloudvoyant/helical-ui';
+import type { HTMLAttributes } from 'svelte/elements';
+type Props = Omit<CoreWhichKeyModeProps, 'className'> & Omit<HTMLAttributes<HTMLSpanElement>, 'children'> & {
+    class?: string;
+    className?: string;
+};
+declare const WhichKeyMode: import("svelte").Component<Props, {}, "">;
+type WhichKeyMode = ReturnType<typeof WhichKeyMode>;
+export default WhichKeyMode;

package/dist/which-key/WhichKeyProvider.svelte

@@ -0,0 +1,136 @@
+<!-- libs/helical-svelte/src/which-key/WhichKeyProvider.svelte -->
+<script lang="ts">
+  import { untrack, type Snippet } from 'svelte';
+  import { useEnvironmentContext } from '@ark-ui/svelte/environment';
+  import { HotkeysProvider } from '@tanstack/svelte-hotkeys';
+  import {
+    createWhichKeyController,
+    type WhichKeyControllerOptions,
+    type WhichKeyState,
+  } from '@cloudvoyant/helical-ui';
+  import { setWhichKeyContext } from './context.svelte';
+
+  type Props = WhichKeyControllerOptions & {
+    scoped?: boolean;
+    children?: Snippet;
+  };
+
+  let {
+    preset,
+    defaultMode = 'normal',
+    leaderKey = 'Space',
+    jumpAction,
+    jumpAlphabet,
+    storageKey,
+    keymap,
+    commands,
+    enabled = true,
+    disableOnMobile = true,
+    scoped = true,
+    onPresetChange,
+    onModeChange,
+    onJumpActionChange,
+    onCommand,
+    onYank,
+    children,
+  }: Props = $props();
+
+  const env = useEnvironmentContext();
+  let scopeEl: HTMLDivElement | null = $state(null);
+
+  const controller = untrack(() =>
+    createWhichKeyController({
+      preset,
+      defaultMode,
+      leaderKey,
+      jumpAction,
+      jumpAlphabet,
+      storageKey,
+      keymap,
+      commands,
+      enabled,
+      disableOnMobile,
+      getDocument: () => {
+        try {
+          return env?.().getDocument?.() ?? document;
+        } catch {
+          return document;
+        }
+      },
+      getScopeElement: () => (scoped ? scopeEl : null),
+      onPresetChange: (next) => onPresetChange?.(next),
+      onModeChange: (next) => onModeChange?.(next),
+      onJumpActionChange: (next) => onJumpActionChange?.(next),
+      onCommand: (id, ctx) => onCommand?.(id, ctx),
+      onYank: (text, ctx) => onYank?.(text, ctx),
+    }),
+  );
+
+  let reactiveState: WhichKeyState = $state(controller.getState());
+
+  setWhichKeyContext({
+    controller,
+    get state() {
+      return reactiveState;
+    },
+  });
+
+  $effect(() => {
+    const unsubscribe = controller.subscribe(() => {
+      reactiveState = controller.getState();
+    });
+    return () => {
+      unsubscribe();
+    };
+  });
+
+  $effect(() => {
+    if (preset !== undefined) {
+      controller.setPreset(preset);
+    }
+  });
+
+  $effect(() => {
+    if (jumpAction !== undefined) {
+      controller.setJumpAction(jumpAction);
+    }
+  });
+
+  $effect(() => {
+    if (!enabled) return;
+    let doc: Document | undefined;
+    try {
+      doc = env?.().getDocument?.();
+    } catch {
+      doc = typeof document !== 'undefined' ? document : undefined;
+    }
+    return controller.attach(doc);
+  });
+
+  $effect(() => {
+    if (!keymap) return;
+    return controller.registerKeymap('__provider_keymap__', keymap, {
+      enabled: true,
+    });
+  });
+
+  $effect(() => {
+    if (!commands) return;
+    const cleanups = Object.entries(commands).map(([id, handler]) =>
+      controller.registerCommand(id, handler),
+    );
+    return () => {
+      for (const fn of cleanups) fn();
+    };
+  });
+</script>
+
+<HotkeysProvider>
+  {#if scoped}
+    <div bind:this={scopeEl} data-which-key-scope class="contents">
+      {@render children?.()}
+    </div>
+  {:else}
+    {@render children?.()}
+  {/if}
+</HotkeysProvider>

package/dist/which-key/WhichKeyProvider.svelte.d.ts

@@ -0,0 +1,9 @@
+import { type Snippet } from 'svelte';
+import { type WhichKeyControllerOptions } from '@cloudvoyant/helical-ui';
+type Props = WhichKeyControllerOptions & {
+    scoped?: boolean;
+    children?: Snippet;
+};
+declare const WhichKeyProvider: import("svelte").Component<Props, {}, "">;
+type WhichKeyProvider = ReturnType<typeof WhichKeyProvider>;
+export default WhichKeyProvider;