@warkypublic/svelix 0.1.0

package/dist/components/VTree/VTree.svelte

@@ -0,0 +1,471 @@
+<script lang="ts">
+  import { onMount } from 'svelte';
+  import VTreeSearch from './VTreeSearch.svelte';
+  import VTreeVirtualViewport from './VTreeVirtualViewport.svelte';
+  import VTreeContextMenu from './VTreeContextMenu.svelte';
+  import type { VTreeFlatRow } from './VTree.models.js';
+  import type { VTreeContextMenuItem, VTreeProps, VTreeRecord } from './types.js';
+
+  export type Props<T extends VTreeRecord = VTreeRecord> = VTreeProps<T>;
+
+  const {
+    data = [],
+    adapter,
+    idField = 'id',
+    labelField = 'label',
+    descriptionField = 'description',
+    childrenField = 'children',
+    hasChildrenField = 'hasChildren',
+    height = 420,
+    rowHeight = 36,
+    indent = 18,
+    overscan = 8,
+    searchable = true,
+    searchPlaceholder = 'Search tree...',
+    searchValue = '',
+    serverSideSearch = false,
+    autoExpandSearchResults = true,
+    loadOnMount = true,
+    emptyMessage = 'Nothing here...',
+    loadingMessage = 'Loading...',
+    leftSection,
+    rightSection,
+    contextMenuItems,
+    onselect,
+    onclick,
+    ondoubleclick,
+    oncontext,
+    ontoggle,
+    onsearch,
+    onloaderror
+  }: Props = $props();
+
+  let viewportRef = $state<{ scrollToIndex: (index: number) => void } | undefined>(undefined);
+  let focusedIndex = $state(0);
+  let selectedId = $state<string | null>(null);
+  let searchQuery = $state('');
+  let loadingRoot = $state(false);
+
+  let rootNodes = $state<VTreeRecord[]>([]);
+  let searchNodes = $state<VTreeRecord[]>([]);
+  let childrenByParent = $state<Record<string, VTreeRecord[]>>({});
+  let expandedById = $state<Record<string, boolean>>({});
+  let loadingById = $state<Record<string, boolean>>({});
+  let loadedById = $state<Record<string, boolean>>({});
+  let errorsById = $state<Record<string, string>>({});
+
+  let lastSearchHandle: ReturnType<typeof setTimeout> | undefined;
+  let searchRunId = 0;
+  let contextOpen = $state(false);
+  let contextX = $state(0);
+  let contextY = $state(0);
+  let contextRow = $state<VTreeRecord | null>(null);
+  let contextItems = $state<VTreeContextMenuItem[]>([]);
+
+  function getNodeId(node: VTreeRecord): string {
+    const value = node?.[idField];
+    return String(value ?? '');
+  }
+
+  function getNodeLabel(node: VTreeRecord): string {
+    return String(node?.[labelField] ?? '');
+  }
+
+  function getNodeDescription(node: VTreeRecord): string {
+    const value = node?.[descriptionField];
+    return value === undefined || value === null ? '' : String(value);
+  }
+
+  function getNodeChildren(node: VTreeRecord): VTreeRecord[] {
+    const nodeId = getNodeId(node);
+    const remoteChildren = childrenByParent[nodeId];
+    if (remoteChildren) return remoteChildren;
+
+    const localChildren = node?.[childrenField];
+    return Array.isArray(localChildren) ? (localChildren as VTreeRecord[]) : [];
+  }
+
+  function nodeHasChildren(node: VTreeRecord): boolean {
+    const children = getNodeChildren(node);
+    if (children.length > 0) return true;
+    return typeof node?.[hasChildrenField] === 'boolean'
+      ? Boolean(node[hasChildrenField])
+      : false;
+  }
+
+  function normalizeRows(rows: VTreeRecord[]): VTreeRecord[] {
+    return Array.isArray(rows) ? rows : [];
+  }
+
+  async function loadRoot() {
+    if (!adapter) {
+      rootNodes = normalizeRows(data ?? []);
+      return;
+    }
+
+    loadingRoot = true;
+    try {
+      const rows = await adapter.readRoot();
+      rootNodes = normalizeRows(rows);
+      searchNodes = [];
+      errorsById = {};
+    } catch (error) {
+      onloaderror?.(error);
+    } finally {
+      loadingRoot = false;
+    }
+  }
+
+  async function loadChildren(node: VTreeRecord) {
+    if (!adapter) return;
+
+    const nodeId = getNodeId(node);
+    if (!nodeId || loadingById[nodeId] || loadedById[nodeId]) return;
+
+    loadingById = { ...loadingById, [nodeId]: true };
+    errorsById = { ...errorsById, [nodeId]: '' };
+
+    try {
+      const rows = await adapter.readChildren(node);
+      childrenByParent = { ...childrenByParent, [nodeId]: normalizeRows(rows) };
+      loadedById = { ...loadedById, [nodeId]: true };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unable to load node';
+      errorsById = { ...errorsById, [nodeId]: message };
+      onloaderror?.(error, node);
+    } finally {
+      loadingById = { ...loadingById, [nodeId]: false };
+    }
+  }
+
+  function matchesLocalSearch(node: VTreeRecord, query: string): boolean {
+    const q = query.toLowerCase();
+    return (
+      getNodeLabel(node).toLowerCase().includes(q) ||
+      getNodeDescription(node).toLowerCase().includes(q)
+    );
+  }
+
+  function toggleNode(node: VTreeRecord) {
+    const nodeId = getNodeId(node);
+    if (!nodeId) return;
+
+    const currentlyExpanded = Boolean(expandedById[nodeId]);
+    expandedById = { ...expandedById, [nodeId]: !currentlyExpanded };
+    ontoggle?.(node, !currentlyExpanded);
+
+    if (!currentlyExpanded && adapter && nodeHasChildren(node)) {
+      void loadChildren(node);
+    }
+  }
+
+  const displayRoots = $derived.by(() => {
+    if (adapter && serverSideSearch && searchQuery.trim().length > 0) return searchNodes;
+    return rootNodes;
+  });
+
+  const flattenedRows = $derived.by(() => {
+    const rows: VTreeFlatRow[] = [];
+    const activeSearch = searchQuery.trim().toLowerCase();
+    const useLocalSearch = activeSearch.length > 0 && !(adapter && serverSideSearch);
+
+    const walk = (
+      nodes: VTreeRecord[],
+      level: number,
+      parentId: string | null
+    ): { rows: VTreeFlatRow[]; matches: boolean } => {
+      const walkRows: VTreeFlatRow[] = [];
+      let hasAnyMatch = false;
+
+      for (const node of nodes) {
+        const id = getNodeId(node);
+        const children = getNodeChildren(node);
+        const childResult = walk(children, level + 1, id);
+        const selfMatch = useLocalSearch ? matchesLocalSearch(node, activeSearch) : false;
+        const childHasMatch = childResult.matches;
+        const includeNode = !useLocalSearch || selfMatch || childHasMatch;
+
+        if (!includeNode) continue;
+
+        hasAnyMatch = true;
+        const expanded = Boolean(expandedById[id]);
+        const forceExpanded = useLocalSearch && autoExpandSearchResults && childHasMatch;
+        walkRows.push({
+          id,
+          node,
+          level,
+          parentId,
+          expanded,
+          hasChildren: nodeHasChildren(node),
+          loading: Boolean(loadingById[id]),
+          error: errorsById[id] || undefined,
+          matched: selfMatch
+        });
+
+        if ((expanded || forceExpanded) && childResult.rows.length > 0) {
+          walkRows.push(...childResult.rows);
+        }
+      }
+
+      return { rows: walkRows, matches: hasAnyMatch };
+    };
+
+    for (const root of displayRoots) {
+      rows.push(...walk([root], 1, null).rows);
+    }
+    return rows;
+  });
+
+  const treeDataSnapshot = $derived.by(() => {
+    const buildTree = (nodes: VTreeRecord[]): VTreeRecord[] =>
+      nodes.map((node) => {
+        const children = getNodeChildren(node);
+        if (children.length === 0) {
+          return node;
+        }
+        return {
+          ...node,
+          [childrenField]: buildTree(children)
+        };
+      });
+
+    return buildTree(displayRoots);
+  });
+
+  function selectRow(index: number) {
+    const row = flattenedRows[index];
+    if (!row) return;
+
+    focusedIndex = index;
+    selectedId = row.id;
+    onselect?.(row.node);
+    viewportRef?.scrollToIndex(index);
+  }
+
+  function moveFocus(delta: number) {
+    if (flattenedRows.length === 0) return;
+    const next = Math.min(flattenedRows.length - 1, Math.max(0, focusedIndex + delta));
+    selectRow(next);
+  }
+
+  function handleTreeKeydown(event: KeyboardEvent) {
+    if (flattenedRows.length === 0) return;
+
+    const current = flattenedRows[focusedIndex];
+    if (!current) {
+      selectRow(0);
+      return;
+    }
+
+    if (event.key === 'ArrowDown') {
+      event.preventDefault();
+      moveFocus(1);
+      return;
+    }
+    if (event.key === 'ArrowUp') {
+      event.preventDefault();
+      moveFocus(-1);
+      return;
+    }
+    if (event.key === 'PageDown') {
+      event.preventDefault();
+      moveFocus(10);
+      return;
+    }
+    if (event.key === 'PageUp') {
+      event.preventDefault();
+      moveFocus(-10);
+      return;
+    }
+    if (event.key === 'Home') {
+      event.preventDefault();
+      selectRow(0);
+      return;
+    }
+    if (event.key === 'End') {
+      event.preventDefault();
+      selectRow(flattenedRows.length - 1);
+      return;
+    }
+    if (event.key === 'ArrowRight') {
+      event.preventDefault();
+      if (current.hasChildren && !current.expanded) {
+        toggleNode(current.node);
+      } else {
+        moveFocus(1);
+      }
+      return;
+    }
+    if (event.key === 'ArrowLeft') {
+      event.preventDefault();
+      if (current.expanded) {
+        toggleNode(current.node);
+      } else if (current.parentId) {
+        const parentIndex = flattenedRows.findIndex((row) => row.id === current.parentId);
+        if (parentIndex >= 0) selectRow(parentIndex);
+      }
+      return;
+    }
+    if (event.key === ' ' || event.key === 'Enter') {
+      event.preventDefault();
+      selectRow(focusedIndex);
+      if (current.hasChildren) {
+        toggleNode(current.node);
+      }
+    }
+  }
+
+  async function runServerSearch(query: string) {
+    if (!adapter || !serverSideSearch) return;
+    const runId = ++searchRunId;
+
+    if (!query.trim()) {
+      searchNodes = [];
+      return;
+    }
+
+    try {
+      const rows = await adapter.search(query.trim());
+      if (runId !== searchRunId) return;
+      searchNodes = normalizeRows(rows);
+      focusedIndex = 0;
+    } catch (error) {
+      if (runId !== searchRunId) return;
+      onloaderror?.(error);
+    }
+  }
+
+  function handleSearchInput(value: string) {
+    searchQuery = value;
+    onsearch?.(value);
+  }
+
+  function handleRowClick(index: number, event: MouseEvent) {
+    const row = flattenedRows[index];
+    if (!row) return;
+    selectRow(index);
+    onclick?.(row.node, treeDataSnapshot, event);
+  }
+
+  function handleRowDoubleClick(index: number, event: MouseEvent) {
+    const row = flattenedRows[index];
+    if (!row) return;
+    selectRow(index);
+    ondoubleclick?.(row.node, treeDataSnapshot, event);
+  }
+
+  function handleRowContext(index: number, event: MouseEvent) {
+    const row = flattenedRows[index];
+    if (!row) return;
+    event.preventDefault();
+    selectRow(index);
+    oncontext?.(row.node, treeDataSnapshot, event);
+
+    if (!contextMenuItems) return;
+    const items =
+      typeof contextMenuItems === 'function'
+        ? contextMenuItems(row.node, treeDataSnapshot)
+        : contextMenuItems;
+    contextItems = items ?? [];
+    contextRow = row.node;
+    contextX = event.clientX;
+    contextY = event.clientY;
+    contextOpen = contextItems.length > 0;
+  }
+
+  function handleViewportContext(event: MouseEvent) {
+    event.preventDefault();
+    oncontext?.(null, treeDataSnapshot, event);
+
+    if (!contextMenuItems) return;
+    const items =
+      typeof contextMenuItems === 'function'
+        ? contextMenuItems(null, treeDataSnapshot)
+        : contextMenuItems;
+    contextItems = items ?? [];
+    contextRow = null;
+    contextX = event.clientX;
+    contextY = event.clientY;
+    contextOpen = contextItems.length > 0;
+  }
+
+  function handleContextMenuItem(item: VTreeContextMenuItem) {
+    if (item.id !== '__close__' && contextRow) {
+      item.onselect?.(contextRow, treeDataSnapshot);
+    }
+    contextOpen = false;
+  }
+
+  $effect(() => {
+    if (!adapter) rootNodes = normalizeRows(data ?? []);
+  });
+
+  $effect(() => {
+    if (!adapter || !serverSideSearch) return;
+    clearTimeout(lastSearchHandle);
+    lastSearchHandle = setTimeout(() => {
+      void runServerSearch(searchQuery);
+    }, 250);
+    return () => clearTimeout(lastSearchHandle);
+  });
+
+  $effect(() => {
+    if (focusedIndex > flattenedRows.length - 1) {
+      focusedIndex = Math.max(flattenedRows.length - 1, 0);
+    }
+    if (!selectedId && flattenedRows.length > 0) {
+      selectedId = flattenedRows[0].id;
+    }
+  });
+
+  onMount(() => {
+    searchQuery = searchValue ?? '';
+
+    if (adapter && loadOnMount) {
+      void loadRoot();
+    } else {
+      rootNodes = normalizeRows(data ?? []);
+    }
+
+    return () => clearTimeout(lastSearchHandle);
+  });
+</script>
+
+<div class="card space-y-2 border border-surface-300-700 bg-surface-100-900 p-2">
+  {#if searchable}
+    <VTreeSearch value={searchQuery} placeholder={searchPlaceholder} oninputvalue={handleSearchInput} />
+  {/if}
+
+  <VTreeVirtualViewport
+    bind:this={viewportRef}
+    rows={flattenedRows}
+    {rowHeight}
+    {height}
+    {indent}
+    {overscan}
+    {focusedIndex}
+    {selectedId}
+    {loadingRoot}
+    {loadingMessage}
+    {emptyMessage}
+    {getNodeLabel}
+    {getNodeDescription}
+    {treeDataSnapshot}
+    {leftSection}
+    {rightSection}
+    onselectrow={handleRowClick}
+    onrowdoubleclick={handleRowDoubleClick}
+    onrowcontext={handleRowContext}
+    onviewportcontext={handleViewportContext}
+    ontogglerow={toggleNode}
+    ontreekeydown={handleTreeKeydown}
+  />
+
+  <VTreeContextMenu
+    open={contextOpen}
+    x={contextX}
+    y={contextY}
+    items={contextItems}
+    onselectitem={handleContextMenuItem}
+  />
+</div>

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

@@ -0,0 +1,5 @@
+import type { VTreeProps, VTreeRecord } from './types.js';
+export type Props<T extends VTreeRecord = VTreeRecord> = VTreeProps<T>;
+declare const VTree: import("svelte").Component<Props<VTreeRecord>, {}, "">;
+type VTree = ReturnType<typeof VTree>;
+export default VTree;

package/dist/components/VTree/VTreeContextMenu.svelte

@@ -0,0 +1,40 @@
+<script lang="ts">
+  import type { VTreeContextMenuItem, VTreeRecord } from './types.js';
+
+  export interface Props<T extends VTreeRecord = VTreeRecord> {
+    open: boolean;
+    x: number;
+    y: number;
+    items: VTreeContextMenuItem<T>[];
+    onselectitem?: (item: VTreeContextMenuItem<T>) => void;
+  }
+
+  const { open, x, y, items, onselectitem }: Props = $props();
+</script>
+
+{#if open}
+  <button
+    class="fixed inset-0 z-50"
+    type="button"
+    aria-label="Close context menu"
+    onclick={() => onselectitem?.({ id: '__close__', label: '' })}
+  ></button>
+  <div
+    class="fixed z-[60] min-w-44 overflow-hidden rounded border border-surface-300-700 bg-surface-100-900 shadow-xl"
+    style={`left:${x}px; top:${y}px;`}
+    role="menu"
+    aria-label="Row context menu"
+  >
+    {#each items as item (item.id)}
+      <button
+        class="block w-full px-3 py-2 text-left text-sm hover:bg-surface-200-800 disabled:cursor-not-allowed disabled:opacity-50"
+        disabled={item.disabled}
+        type="button"
+        role="menuitem"
+        onclick={() => onselectitem?.(item)}
+      >
+        {item.label}
+      </button>
+    {/each}
+  </div>
+{/if}

package/dist/components/VTree/VTreeContextMenu.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { VTreeContextMenuItem, VTreeRecord } from './types.js';
+export interface Props<T extends VTreeRecord = VTreeRecord> {
+    open: boolean;
+    x: number;
+    y: number;
+    items: VTreeContextMenuItem<T>[];
+    onselectitem?: (item: VTreeContextMenuItem<T>) => void;
+}
+declare const VTreeContextMenu: import("svelte").Component<Props<VTreeRecord>, {}, "">;
+type VTreeContextMenu = ReturnType<typeof VTreeContextMenu>;
+export default VTreeContextMenu;

package/dist/components/VTree/VTreeEventsDemo.svelte

@@ -0,0 +1,88 @@
+<script lang="ts">
+  // @ts-nocheck
+  import VTree from './VTree.svelte';
+  import type { VTreeContextMenuItem, VTreeRecord } from './types.js';
+
+  interface DemoNode extends VTreeRecord {
+    id: string;
+    label: string;
+    description?: string;
+    children?: DemoNode[];
+    hasChildren?: boolean;
+  }
+
+  const data: DemoNode[] = [
+    {
+      id: 'alpha',
+      label: 'Alpha Team',
+      description: 'Top-level group',
+      hasChildren: true,
+      children: [
+        { id: 'alpha-1', label: 'Alpha User 1', description: 'Owner' },
+        { id: 'alpha-2', label: 'Alpha User 2', description: 'Contributor' }
+      ]
+    },
+    {
+      id: 'beta',
+      label: 'Beta Team',
+      description: 'Top-level group',
+      hasChildren: true,
+      children: [
+        { id: 'beta-1', label: 'Beta User 1', description: 'Owner' },
+        { id: 'beta-2', label: 'Beta User 2', description: 'Contributor' }
+      ]
+    }
+  ];
+
+  let eventLog = $state('No row event yet.');
+
+  function printEvent(kind: string, row: DemoNode | null, treeData: DemoNode[]) {
+    eventLog = `${kind}: ${row?.label ?? 'null'} | tree roots: ${treeData.length}`;
+  }
+
+  const menuItems: VTreeContextMenuItem<DemoNode>[] = [
+    {
+      id: 'open',
+      label: 'Open',
+      onselect: (row) => {
+        eventLog = `menu: open -> ${row?.label ?? 'null'}`;
+      }
+    },
+    {
+      id: 'inspect',
+      label: 'Inspect Node',
+      onselect: (row, treeData) => {
+        eventLog = `menu: inspect -> ${row.id} (roots: ${treeData.length})`;
+      }
+    }
+  ];
+</script>
+
+{#snippet leftContent(args)}
+  <span class="inline-flex h-4 w-4 items-center justify-center rounded bg-surface-200-700 text-[10px]">
+    {args.level}
+  </span>
+{/snippet}
+
+{#snippet rightContent(args)}
+  <span class="text-[10px] text-surface-500-400-token">#{args.rowIndex + 1}</span>
+{/snippet}
+
+<div class="space-y-2">
+  <VTree
+    data={data}
+    height={300}
+    rowHeight={34}
+    searchable
+    leftSection={leftContent}
+    rightSection={rightContent}
+    contextMenuItems={menuItems}
+    onclick={(row, treeData) => printEvent('click', row, treeData)}
+    ondoubleclick={(row, treeData) => printEvent('double-click', row, treeData)}
+    oncontext={(row, treeData) => printEvent('context', row, treeData)}
+  />
+
+  <div class="card border border-surface-300-700 bg-surface-50-950 p-2 text-xs text-surface-700-200-token">
+    {eventLog}
+  </div>
+</div>

package/dist/components/VTree/VTreeEventsDemo.svelte.d.ts

@@ -0,0 +1,3 @@
+declare const VTreeEventsDemo: import("svelte").Component<Record<string, never>, {}, "">;
+type VTreeEventsDemo = ReturnType<typeof VTreeEventsDemo>;
+export default VTreeEventsDemo;

package/dist/components/VTree/VTreeResolveSpecAdapter.d.ts

@@ -0,0 +1,14 @@
+import type { Options } from '@warkypublic/resolvespec-js';
+import type { VTreeRecord, VTreeResolveSpecAdapterConfig, VTreeServerAdapter } from './types.js';
+export declare class VTreeResolveSpecAdapter<T extends VTreeRecord = VTreeRecord> implements VTreeServerAdapter<T> {
+    private readonly client;
+    private readonly isHeader;
+    private readonly config;
+    constructor(config: VTreeResolveSpecAdapterConfig<T>);
+    readRoot(options?: Partial<Options>): Promise<T[]>;
+    readChildren(node: T, options?: Partial<Options>): Promise<T[]>;
+    search(query: string, options?: Partial<Options>): Promise<T[]>;
+    private readWithOptions;
+    private mapRows;
+    private resolveFilters;
+}