A Finder for the web, over any filesystem

import { Finder, memoryFS, modernMonacoFS, justBashFS } from 'svelte-finder'
import type { FinderEntry, FinderFS, FinderView } from 'svelte-finder'

<script lang="ts">
  import { Finder, memoryFS } from 'svelte-finder';

  const fs = memoryFS({
    'README.md': '# Hello\n',
    src: {
      'app.ts': 'export {};\n',
      lib: { 'util.ts': 'export const id = <T>(x: T) => x;\n' }
    },
    'logo.png': new Uint8Array(2048)
  });
</script>

<div style="height: 420px">
  <Finder {fs} />
</div>

fs.write('/src/lib/new.ts', 'export {};\n'); // parents are created
fs.mkdir('/docs');
await fs.move('/docs', '/src/docs');
fs.remove('/logo.png');
await fs.read('/README.md'); // the bytes of '# Hello\n'

<script lang="ts">
	import { onMount } from 'svelte';
	import { Finder, memoryFS, type FinderView } from 'svelte-finder';

	import Demo from './Demo.svelte';
	import { addPhotos, project } from './project.js';
	import Button from './ui/Button.svelte';
	import ToggleGroup from './ui/ToggleGroup.svelte';

	// spread the files over the last few years so date grouping has something to show
	const DAYS_AGO = [0, 1, 4, 12, 45, 120, 400, 900];
	const NOW = Date.now();
	const modified = (path: string) =>
		NOW -
		DAYS_AGO[[...path].reduce((sum, c) => sum + c.charCodeAt(0), 0) % DAYS_AGO.length] * 86_400_000;
	const fs = memoryFS(project, { modified });
	onMount(() => addPhotos(fs, modified));
	const VIEWS: FinderView[] = ['icons', 'list', 'columns'];

	let view = $state<FinderView>('icons');
	let path = $state('/static/images');
	let grouped = $state(false);
</script>

<Demo>
	{#snippet controls()}
		<ToggleGroup label="View" items={VIEWS} bind:value={view} />
		<Button
			variant="ghost"
			size="sm"
			aria-pressed={grouped}
			onclick={() => {
				grouped = !grouped;
				if (grouped) view = 'list';
			}}>By date</Button
		>
		<code class="ml-auto truncate px-2 font-mono text-[12.5px] text-muted-foreground">{path}</code>
	{/snippet}
	<Finder
		{fs}
		rootLabel="field-notes"
		bind:view
		bind:path
		group={grouped ? 'modified' : null}
		class="h-full"
	/>
</Demo>

<script lang="ts">
	import { onMount } from 'svelte';
	import { Finder, memoryFS, type FinderEntry } from 'svelte-finder';

	import Demo from './Demo.svelte';
	import { addPhotos, project } from './project.js';
	import Button from './ui/Button.svelte';

	const fs = memoryFS(project);
	onMount(() => addPhotos(fs));
	const decoder = new TextDecoder();

	let finder = $state<Finder<FinderEntry>>();
	let selected = $state<string | null>(null);

	const paths = $derived(finder?.history.paths ?? []);
	const index = $derived(finder?.history.index ?? -1);
</script>

<Demo tall>
	<Finder
		bind:this={finder}
		{fs}
		rootLabel="field-notes"
		path="/src/lib/utils"
		bind:selected
		class="h-full"
	>
		{#snippet preview(entry, folder)}
			<div class="flex h-full flex-col gap-3 p-4">
				<strong class="truncate font-mono text-[13px] font-medium">{entry?.name ?? folder}</strong>
				{#if entry}
					{#await fs.read(entry.path) then bytes}
						{#if bytes.includes(0)}
							<p class="text-[12.5px] text-muted-foreground">Binary, {bytes.length} bytes</p>
						{:else}
							<pre
								class="m-0 min-h-0 flex-1 overflow-auto bg-well p-3 font-mono text-[11.5px] leading-[1.6] whitespace-pre-wrap">{decoder.decode(
									bytes
								)}</pre>
						{/if}
					{/await}
				{:else}
					<p class="text-[12.5px] text-muted-foreground">Select a file to read it here.</p>
				{/if}
			</div>
		{/snippet}
	</Finder>
	{#snippet footer()}
		<div class="flex items-center gap-1 px-2 py-2 text-[13px]">
			<Button variant="ghost" size="sm" disabled={index <= 0} onclick={() => finder?.back()}
				>Back</Button
			>
			<Button
				variant="ghost"
				size="sm"
				disabled={index >= paths.length - 1}
				onclick={() => finder?.forward()}>Forward</Button
			>
			<ol class="flex min-w-0 flex-1 gap-1 overflow-x-auto" aria-label="History">
				{#each paths as path, i (i)}
					<li class="shrink-0">
						<button
							type="button"
							class={[
								'px-2 py-1 font-mono text-[12.5px] hover:bg-muted',
								i === index ? 'bg-muted text-foreground' : 'text-muted-foreground'
							]}
							aria-current={i === index ? 'step' : undefined}
							onclick={() => finder?.go(i)}>{path}</button
						>
					</li>
				{/each}
			</ol>
		</div>
	{/snippet}
</Demo>

interface FinderFS {
  // Entries of the directory at path, in any order; reject if it is not a directory.
  list(path: string): Promise<FinderEntry[]>;
  // Optional: call onChange when anything at or below path changes; return an unsubscribe.
  watch?(path: string, onChange: () => void): () => void;
  // Optional: your own search under root; the signal aborts when the query changes.
  search?(query: string, root: string, opts: { signal: AbortSignal }): Promise<FinderEntry[]>;
  // Optional: the file's bytes; the built-in preview shows images and the start of text files.
  read?(path: string): Promise<Uint8Array>;
  // Optional: move from to its new full path, rejecting if that exists; entries become draggable.
  move?(from: string, to: string): Promise<void>;
}

interface FinderEntry {
  name: string; // base name, no slashes
  path: string; // absolute: '/', '/src', '/src/app.ts'
  kind: 'file' | 'directory';
  size?: number; // bytes
  modified?: number; // epoch milliseconds
  symlink?: boolean; // a link; kind is what it points at
}

import { joinPath, type FinderFS } from 'svelte-finder';

// A read-only Finder over an API that answers GET /ls?path=/src with
// [{ "name": "app.ts", "dir": false, "bytes": 812, "mtime": "2026-10-01T09:00:00Z" }]
export const httpFS = (base: string): FinderFS => ({
  async list(path) {
    const response = await fetch(`${base}/ls?path=${encodeURIComponent(path)}`);
    if (!response.ok) throw new Error(`${path}: ${response.status}`);
    const rows: { name: string; dir: boolean; bytes: number; mtime: string }[] = await response.json();
    return rows.map((row) => ({
      name: row.name,
      path: joinPath(path, row.name),
      kind: row.dir ? 'directory' : 'file',
      size: row.bytes,
      modified: Date.parse(row.mtime)
    }));
  }
});

<script lang="ts">
	import { Finder, modernMonacoFS } from 'svelte-finder';
	import { Workspace } from 'modern-monaco';
	import { MonacoEditor, WorkspaceState } from 'modern-monaco-svelte';

	import { isDark } from './dark.js';
	import Demo from './Demo.svelte';

	// Lives in IndexedDB: your edits survive a reload, initialFiles only seed it once.
	const workspace = new Workspace({
		name: 'svelte-finder-demo',
		initialFiles: {
			'README.md': '# Workspace\n\nDouble-click a file in the Finder to open it here.\n',
			'src/main.ts': "import { greet } from './greet';\n\nconsole.log(greet('Finder'));\n",
			'src/greet.ts': 'export const greet = (name: string) => `Hello, ${name}!`;\n',
			'styles/app.css': 'body {\n\tmargin: 0;\n\tfont-family: system-ui, sans-serif;\n}\n'
		},
		entryFile: 'README.md'
	});
	const fs = modernMonacoFS(workspace.fs);
	// the open file lives in the workspace's history: onopen pushes onto it, the editor follows
	const files = new WorkspaceState(workspace);
	$effect(() => () => files.dispose());
</script>

<Demo tall>
	<div
		class="grid h-full grid-rows-2 gap-2.5 min-[700px]:grid-cols-[minmax(0,2fr)_minmax(0,3fr)] min-[700px]:grid-rows-1"
	>
		<Finder
			{fs}
			rootLabel="workspace"
			view="list"
			searchable={false}
			selected={files.current ? `/${files.current}` : null}
			onopen={(entry) => files.open(entry.path.slice(1))}
			class="h-full"
		/>
		<MonacoEditor
			{workspace}
			file={files.current}
			followHistory
			dark={isDark()}
			options={{ minimap: { enabled: false }, fontSize: 13 }}
			class="h-full border"
		/>
	</div>
</Demo>

<script lang="ts">
	import { Finder, justBashFS, withChangeFeed } from 'svelte-finder';
	import { Bash } from 'just-bash/browser';

	import Demo from './Demo.svelte';
	import Shell from './Shell.svelte';

	const bash = new Bash({
		cwd: '/project',
		files: {
			'/project/README.md': '# project\n',
			'/project/src/index.ts': "export * from './lib';\n",
			'/project/src/lib.ts': 'export const answer = 42;\n'
		}
	});
	// just-bash has no change events: withChangeFeed adds a watch that fires on notify().
	const fs = withChangeFeed(justBashFS(bash.fs));

	async function run(line: string) {
		const { stdout, stderr } = await bash.exec(line);
		fs.notify();
		return stdout + stderr;
	}
</script>

<Demo tall>
	<Finder {fs} root="/project" rootLabel="project" view="list" class="h-full" />
	{#snippet footer()}
		<Shell
			class="h-66 sm:h-50"
			{run}
			empty="Output appears here."
			examples={[
				'mkdir -p docs/notes',
				'touch docs/todo.md',
				'echo "hello" > hello.txt',
				'rm -r src',
				'ls -la'
			]}
		/>
	{/snippet}
</Demo>

<script lang="ts">
	import { onMount } from 'svelte';
	import { Finder, memoryFS } from 'svelte-finder';

	import Demo from './Demo.svelte';
	import { addPhotos, project } from './project.js';

	const fs = memoryFS(project);
	onMount(() => addPhotos(fs));
</script>

<Demo>
	<div class="darkroom">
		<Finder {fs} rootLabel="field-notes" path="/static/images" />
	</div>
</Demo>

<style>
	.darkroom {
		--finder-bg: #2b211b;
		--finder-fg: #f3e7d6;
		--finder-muted-fg: #b09a86;
		--finder-border: #f3e7d61f;
		--finder-hover-bg: #3a2d25;
		--finder-selected-bg: #e2a55a;
		--finder-selected-fg: #2b211b;
		--finder-accent: #e2a55a66;
		--finder-font: 'Iowan Old Style', Charter, Georgia, serif;
		--finder-mono: 'Iowan Old Style', Charter, Georgia, serif;
		--finder-radius: 6px;
		--finder-column-width: 13rem;
		--finder-icon-size: 4rem;

		height: 100%;
		border-radius: 10px;
		overflow: hidden;
	}
</style>

/* app.css */

/* The root carries the view: 'icons' | 'list' | 'columns'. */
.finder[data-view='list'] {
  font-size: 13px;
}

/* Every row, tile and column item says what it is and where it lives. */
.finder [data-kind='directory'] {
  font-weight: 500;
}
.finder [data-path$='.md'] {
  color: steelblue;
}

/* 'true' on the selected entry; in columns also on each folder you came through. */
.finder [data-selected='true'] {
  outline: 1px solid currentColor;
}
.finder [data-open='true'] {
  font-style: italic;
}