dockview-svelte 0.0.1

package/dist/components/DvWidget.svelte

@@ -0,0 +1,120 @@
+<script lang="ts">
+import { DEV } from 'esm-env'
+import type { Snippet } from 'svelte'
+import { getContext } from 'svelte'
+import { DOCKVIEW_CONTEXT_KEY } from '../core/context.js'
+
+/**
+ * Props for `<DvWidget>`.
+ *
+ * The `children` snippet receives the panel's shared `state` object — the same
+ * object a `widgets`-registry component receives as its `state` prop — and its
+ * output is rendered into the panel body (and tab/header, when given).
+ * `tab` / `header` snippets receive the same `state`.
+ *
+ * > **Type note:** the snippet parameter defaults to `never` on purpose — it
+ * > cannot be inferred per-widget, so annotate it with your panel's state type
+ * > (e.g. `{#snippet children(state: PanelState<{ id: number }>)}`). The
+ * > annotation is what gives you typed `state.params`.
+ *
+ * Usage:
+ *
+ * ```svelte
+ * <Dockview>
+ * 	<DvWidget name="chat" title="Chat">
+ * 		{#snippet children(state)}
+ * 			<ChatWidget {state} />
+ * 		{/snippet}
+ * 	</DvWidget>
+ * </Dockview>
+ * ```
+ */
+interface Props {
+	/** Widget key this instance registers under. */
+	name: string
+	/** Body content, called with the shared `state`. */
+	children: Snippet<[state: never]>
+	/** Dockview tab override, called with the shared `PanelState` (Dockview only). */
+	tab?: Snippet<[state: never]>
+	/** Paneview header override, called with the shared `PaneviewState` (Paneview only). */
+	header?: Snippet<[state: never]>
+	/** Default title for this widget (tier 2 in the resolution chain). */
+	title?: string
+}
+
+let { name, children, tab, header, title }: Props = $props()
+
+const ctx = getContext<{
+	kind: 'dockview' | 'splitview' | 'gridview' | 'paneview'
+	registerWidget: (key: string, def: Record<string, unknown>) => void
+	unregisterWidget: (key: string) => void
+} | null>(DOCKVIEW_CONTEXT_KEY)
+if (!ctx) {
+	throw new Error(
+		'dockview-svelte: <DvWidget> must be a child of Dockview/Splitview/Gridview/Paneview'
+	)
+}
+
+// Snippets only apply to specific layouts; warn on inapplicable ones instead
+// of silently dropping them (the per-layout registry ignores unknown keys).
+$effect(() => {
+	if (!DEV) return
+	if (tab && ctx.kind !== 'dockview') {
+		console.warn(
+			`dockview-svelte: <DvWidget tab> is only supported by <Dockview>; ignored inside <${ctx.kind}>`
+		)
+	}
+	if (header && ctx.kind !== 'paneview') {
+		console.warn(
+			`dockview-svelte: <DvWidget header> is only supported by <Paneview>; ignored inside <${ctx.kind}>`
+		)
+	}
+	if (title !== undefined && ctx.kind !== 'dockview' && ctx.kind !== 'paneview') {
+		console.warn(
+			`dockview-svelte: <DvWidget title> is only supported by <Dockview>/<Paneview>; ignored inside <${ctx.kind}>`
+		)
+	}
+})
+
+/**
+ * Build a plain-function component around a snippet. The factories call
+ * `mount(component, { target, props: { state } })`, so the wrapper only needs
+ * to accept `{ state }` and invoke the snippet with the dockview-owned anchor.
+ * A plain function works because Svelte 5 `mount` invokes
+ * `Component(anchor, props)` directly (see `_mount` in `svelte/internal/client`).
+ *
+ * Compiled snippets are `(anchor, ...args)` functions where each arg is a
+ * getter thunk (see `svelte/compiler` output: `children($$anchor, () =>
+ * myState)`). Passing a thunk over the live `state` keeps reactive reads
+ * tracked.
+ */
+function snippetComponent(snippet: Snippet<[state: never]>) {
+	return (anchor: Node, props: { state: never }) => {
+		;(snippet as unknown as (node: Node, getState: () => never) => void)(anchor, () => props.state)
+	}
+}
+
+const component = $derived(snippetComponent(children as Snippet<[state: never]>))
+const tabComponent = $derived(tab ? snippetComponent(tab as Snippet<[state: never]>) : undefined)
+const headerComponent = $derived(
+	header ? snippetComponent(header as Snippet<[state: never]>) : undefined
+)
+
+// Register on mount and on every prop change; the cleanup unregisters the
+// current key first, so a changed `name` never leaves a stale entry behind.
+// `widgets`-prop entries with the same key win on re-seed — declarative
+// children are the override path, not the base.
+// Only include snippets that apply to the parent layout (`tab` → Dockview,
+// `header` → Paneview, `title` → Dockview/Paneview) so the dev warning above is
+// accurate and the inapplicable keys never reach the registry.
+$effect(() => {
+	const def: Record<string, unknown> = { component }
+	if (tabComponent && ctx.kind === 'dockview') def.tab = tabComponent
+	if (headerComponent && ctx.kind === 'paneview') def.header = headerComponent
+	if (title !== undefined && (ctx.kind === 'dockview' || ctx.kind === 'paneview')) {
+		def.title = title
+	}
+	ctx.registerWidget(name, def)
+	return () => ctx.unregisterWidget(name)
+})
+</script>

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

@@ -0,0 +1,41 @@
+import type { Snippet } from 'svelte';
+/**
+ * Props for `<DvWidget>`.
+ *
+ * The `children` snippet receives the panel's shared `state` object — the same
+ * object a `widgets`-registry component receives as its `state` prop — and its
+ * output is rendered into the panel body (and tab/header, when given).
+ * `tab` / `header` snippets receive the same `state`.
+ *
+ * > **Type note:** the snippet parameter defaults to `never` on purpose — it
+ * > cannot be inferred per-widget, so annotate it with your panel's state type
+ * > (e.g. `{#snippet children(state: PanelState<{ id: number }>)}`). The
+ * > annotation is what gives you typed `state.params`.
+ *
+ * Usage:
+ *
+ * ```svelte
+ * <Dockview>
+ * 	<DvWidget name="chat" title="Chat">
+ * 		{#snippet children(state)}
+ * 			<ChatWidget {state} />
+ * 		{/snippet}
+ * 	</DvWidget>
+ * </Dockview>
+ * ```
+ */
+interface Props {
+    /** Widget key this instance registers under. */
+    name: string;
+    /** Body content, called with the shared `state`. */
+    children: Snippet<[state: never]>;
+    /** Dockview tab override, called with the shared `PanelState` (Dockview only). */
+    tab?: Snippet<[state: never]>;
+    /** Paneview header override, called with the shared `PaneviewState` (Paneview only). */
+    header?: Snippet<[state: never]>;
+    /** Default title for this widget (tier 2 in the resolution chain). */
+    title?: string;
+}
+declare const DvWidget: import("svelte").Component<Props, {}, "">;
+type DvWidget = ReturnType<typeof DvWidget>;
+export default DvWidget;

package/dist/components/Gridview.svelte

@@ -0,0 +1,341 @@
+<script lang="ts" generics="const W extends GridviewWidgets">
+import type {
+	GridviewApi,
+	GridviewComponentOptions,
+	IGridviewPanel,
+	SerializedGridviewComponent,
+} from 'dockview'
+import { createGridview, Orientation } from 'dockview'
+import { onMount, type Snippet, setContext } from 'svelte'
+import { DOCKVIEW_CONTEXT_KEY, type GridviewContext } from '../core/context.js'
+import { createGridviewFactory } from '../core/gridview.svelte.js'
+import { GridviewWidgetRegistry } from '../core/registry.js'
+import type {
+	GridviewHandle,
+	GridviewMoveOptions,
+	GridviewOpenPanelOptions,
+	GridviewPanelHandle,
+	GridviewParamsOf,
+	GridviewWidgetDefinition,
+	GridviewWidgets,
+} from '../core/types.js'
+import { deepEqual } from '../core/utils.js'
+
+interface Props<W extends GridviewWidgets> {
+	/** Widget registry: `{ [key]: { component } }` — no tabs or titles, grid cells have no headers. */
+	widgets?: W
+	/**
+	 * `GridviewComponentOptions` passthrough (proportionalLayout, …).
+	 * `orientation` defaults to `HORIZONTAL` (required by dockview).
+	 *
+	 * `createComponent` is owned by the library (Svelte `mount` factory
+	 * backed by the `widgets` registry) and cannot be overridden.
+	 */
+	options?: Omit<GridviewComponentOptions, 'createComponent'> & { orientation?: Orientation }
+	/** `bind:layout` — gridview JSON (`toJSON`/`fromJSON` shape). */
+	layout?: SerializedGridviewComponent
+	/** `bind:handle` — `{ api, openPanel, registerWidget, removePanel, movePanel, setVisible, setActive }`. */
+	handle?: GridviewHandle<W>
+	/**
+	 * `bind:panels` — reactive list of current cells (`api.panels` snapshot).
+	 * Refreshed on layout/add/remove/FromJSON, so `panels.length` is the
+	 * sveltish cell count — no manual `onDidAddPanel` counting needed.
+	 */
+	panels?: IGridviewPanel[]
+	/**
+	 * `bind:activePanel` — the currently active cell. Derived from the
+	 * per-panel `api.onDidActiveChange` (via the factory) plus explicit sync
+	 * on the open/remove paths — `GridviewApi.onDidActivePanelChange` only
+	 * fires on focus-driven activation, never on programmatic adds.
+	 */
+	activePanel?: IGridviewPanel | undefined
+	/** Extra classes for the root container. */
+	class?: string
+	/** Declarative widgets (`<DvWidget>` children) — alternative to the `widgets` prop. */
+	children?: Snippet
+	/** Fired once the component is mounted and `api` is ready. */
+	onReady?: (event: { api: GridviewApi; handle: GridviewHandle<W> }) => void
+	onDidLayoutChange?: () => void
+	onDidLayoutFromJSON?: () => void
+	onDidAddPanel?: (panel: IGridviewPanel) => void
+	onDidRemovePanel?: (panel: IGridviewPanel) => void
+	onDidActivePanelChange?: (panel: IGridviewPanel | undefined) => void
+}
+
+let {
+	widgets = {} as W,
+	options = {} as Omit<GridviewComponentOptions, 'createComponent'> & {
+		orientation?: Orientation
+	},
+	layout = $bindable(),
+	handle = $bindable(),
+	panels = $bindable([]),
+	activePanel = $bindable(undefined),
+	class: className = '',
+	children,
+	onReady,
+	onDidLayoutChange,
+	onDidLayoutFromJSON,
+	onDidAddPanel,
+	onDidRemovePanel,
+	onDidActivePanelChange,
+}: Props<W> = $props()
+
+let container: HTMLElement
+let api = $state<GridviewApi | undefined>(undefined)
+
+const registry = new GridviewWidgetRegistry()
+const counters = new Map<string, number>()
+
+// Stable `registerWidget`, shared by context and handle.
+function registerWidget(key: string, def: GridviewWidgetDefinition): void {
+	registry.register(key, def)
+}
+
+function unregisterWidget(key: string): void {
+	registry.unregister(key)
+}
+
+// Context for descendant widgets (api is populated after mount).
+const context = $state<GridviewContext>({
+	api: undefined,
+	registerWidget,
+	unregisterWidget,
+	kind: 'gridview',
+})
+setContext(DOCKVIEW_CONTEXT_KEY, context)
+
+// Seed the registry from the `widgets` prop (additive).
+$effect(() => {
+	registry.seed(widgets)
+})
+
+function nextId(key: string): string {
+	const n = (counters.get(key) ?? 0) + 1
+	counters.set(key, n)
+	return `${key}-${n}`
+}
+
+/** `bind:layout` loop-break: the JSON we last emitted to the parent. */
+let lastEmitted: SerializedGridviewComponent | undefined
+
+/** Serialize the current layout and push it to the bound `layout`. */
+function emitLayout(): void {
+	if (!api) return
+	const json = api.toJSON()
+	lastEmitted = json
+	layout = json
+	refreshPanels()
+}
+
+/** Refresh `bind:panels` from the live cells. */
+function refreshPanels(): void {
+	if (!api) return
+	panels = [...api.panels]
+}
+
+/**
+ * Set `bind:activePanel` + fire `onDidActivePanelChange`, deduped on panel
+ * id. Per-panel `onDidActiveChange` fires on both the deactivated and the
+ * activated cell, so the guard keeps a single update per activation.
+ */
+function setActivePanel(panel: IGridviewPanel | undefined): void {
+	if (activePanel?.id === panel?.id) return
+	activePanel = panel
+	onDidActivePanelChange?.(panel)
+}
+
+function getPanelOrThrow(id: string): import('dockview').GridviewPanel {
+	const panel = api!.getPanel(id)
+	if (!panel) {
+		throw new Error(`dockview-svelte: unknown panel "${id}"`)
+	}
+	return panel as import('dockview').GridviewPanel
+}
+
+function openPanel<K extends keyof W & string>(
+	key: K,
+	opts?: GridviewOpenPanelOptions<GridviewParamsOf<W[K]['component']>>
+): GridviewPanelHandle<GridviewParamsOf<W[K]['component']>> {
+	if (!api) {
+		throw new Error('dockview-svelte: Gridview is not mounted yet')
+	}
+	const def = registry.get(key)
+	if (!def) {
+		throw new Error(`dockview-svelte: unknown widget "${key}"`)
+	}
+
+	const id = opts?.id ?? nextId(key)
+	const panel = api.addPanel({
+		...(opts ?? {}),
+		id,
+		component: key,
+		params: opts?.params ?? {},
+	})
+	// `addPanel` fires no event the component observes for the open path
+	// itself (events cover external mutations) — refresh the bound
+	// panels/layout directly so `bind:panels` reflects the new cell.
+	// `doSetGroupActive` inside `addPanel` fires per-panel
+	// `onDidActiveChange`, which the factory mirrors to `state.active`
+	// but the component does not observe — so sync `bind:activePanel`
+	// explicitly.
+	emitLayout()
+	setActivePanel(panel)
+
+	const state = factory?.getState(id)
+	// `state` is `GridviewState<Record<string, unknown>>` at the factory
+	// boundary; `GridviewState<P>` is invariant in `P` (params is read/write),
+	// so the runtime-known `P` requires an `unknown` bridge.
+	return { id, panel, api: panel.api, state: state! } as unknown as GridviewPanelHandle<
+		GridviewParamsOf<W[K]['component']>
+	>
+}
+
+/** Remove a cell by panel id. */
+function removePanel(id: string): void {
+	if (!api) {
+		throw new Error('dockview-svelte: Gridview is not mounted yet')
+	}
+	const removed = getPanelOrThrow(id)
+	const wasActive = activePanel?.id === removed.id
+	api.removePanel(removed)
+	// Removal fires no active event either — fall back to the last
+	// remaining cell when the active one was removed.
+	if (wasActive) setActivePanel(api.panels.at(-1))
+}
+
+/** Move a cell relative to a reference panel. */
+function movePanel(id: string, move: GridviewMoveOptions): void {
+	if (!api) {
+		throw new Error('dockview-svelte: Gridview is not mounted yet')
+	}
+	api.movePanel(getPanelOrThrow(id), {
+		direction: move.direction,
+		reference: move.reference,
+		size: move.size,
+	})
+}
+
+/** Show or hide a cell by id (via the panel api — `panel.setVisible` only fires `onDidVisibilityChange` without touching the layout). */
+function setVisible(id: string, visible: boolean): void {
+	if (!api) {
+		throw new Error('dockview-svelte: Gridview is not mounted yet')
+	}
+	getPanelOrThrow(id).api.setVisible(visible)
+}
+
+/** Activate a cell by id (via the panel api — `panel.setActive` only fires `onDidActiveChange`). */
+function setActive(id: string): void {
+	if (!api) {
+		throw new Error('dockview-svelte: Gridview is not mounted yet')
+	}
+	getPanelOrThrow(id).api.setActive()
+}
+
+let factory: ReturnType<typeof createGridviewFactory> | undefined
+
+// External `layout` changes → apply via `fromJSON` (loop-break via `lastEmitted`).
+$effect(() => {
+	const current = api
+	if (!current || !layout) return
+	if (deepEqual(lastEmitted, layout)) return
+	current.fromJSON(layout)
+})
+
+// Live `options` changes (orientation, etc.) → apply via `updateOptions`.
+// NOTE: `opts` must be read before the `api` guard — otherwise the
+// initial run returns early without tracking `options`, and later changes
+// never re-trigger the effect.
+$effect(() => {
+	const opts = options
+	if (!api) return
+	api.updateOptions(opts)
+})
+
+onMount(() => {
+	factory = createGridviewFactory(registry, context, {
+		onDidActivePanelChange: (panel) => setActivePanel(panel as unknown as IGridviewPanel),
+	})
+	const createdApi = createGridview(container, {
+		...options,
+		orientation: options.orientation ?? Orientation.HORIZONTAL,
+		createComponent: factory.createComponent,
+	})
+	// Apply a pre-existing `bind:layout` before exposing the api.
+	if (layout) {
+		createdApi.fromJSON(layout)
+		lastEmitted = createdApi.toJSON()
+		layout = lastEmitted
+	}
+	api = createdApi
+	context.api = createdApi
+
+	const createdHandle: GridviewHandle<W> = {
+		api: createdApi,
+		openPanel,
+		registerWidget,
+		removePanel,
+		movePanel,
+		setVisible,
+		setActive,
+	}
+	handle = createdHandle
+
+	// Bridge gridview events to callbacks, disposing on teardown.
+	const subscriptions = [
+		createdApi.onDidLayoutChange(() => {
+			emitLayout()
+			onDidLayoutChange?.()
+		}),
+		createdApi.onDidLayoutFromJSON(() => {
+			refreshPanels()
+			onDidLayoutFromJSON?.()
+		}),
+		createdApi.onDidAddPanel((panel: IGridviewPanel) => {
+			refreshPanels()
+			// External adds (e.g. `api.addPanel` escape hatch) activate the
+			// new cell without a component-level event — same sync as the
+			// `openPanel` path.
+			setActivePanel(panel)
+			onDidAddPanel?.(panel)
+		}),
+		createdApi.onDidRemovePanel((panel: IGridviewPanel) => {
+			refreshPanels()
+			if (activePanel?.id === panel.id) setActivePanel(createdApi.panels.at(-1))
+			onDidRemovePanel?.(panel)
+		}),
+		createdApi.onDidActivePanelChange((panel: IGridviewPanel | undefined) => {
+			// Focus-driven activation path (`registerPanel` wires
+			// `onDidFocusChange` → `doSetGroupActive`). Programmatic
+			// activation (`api.setActive`, `addPanel`) only fires the
+			// per-panel event, handled via the factory hook below.
+			setActivePanel(panel)
+		}),
+	]
+	// Seed the initial panels before exposing the handle.
+	refreshPanels()
+	onReady?.({ api: createdApi, handle: createdHandle })
+
+	return () => {
+		for (const disposable of subscriptions) disposable.dispose()
+		createdApi.dispose()
+		api = undefined
+		factory = undefined
+		lastEmitted = undefined
+	}
+})
+</script>
+
+<div class="dv-svelte-gridview-root {className}" bind:this={container}>
+	{#if children}
+		{@render children()}
+	{/if}
+</div>
+
+<style>
+	.dv-svelte-gridview-root {
+		width: 100%;
+		height: 100%;
+		position: relative;
+	}
+</style>

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

@@ -0,0 +1,73 @@
+import type { GridviewApi, GridviewComponentOptions, IGridviewPanel, SerializedGridviewComponent } from 'dockview';
+import { Orientation } from 'dockview';
+import { type Snippet } from 'svelte';
+import type { GridviewHandle, GridviewWidgets } from '../core/types.js';
+interface Props<W extends GridviewWidgets> {
+    /** Widget registry: `{ [key]: { component } }` — no tabs or titles, grid cells have no headers. */
+    widgets?: W;
+    /**
+     * `GridviewComponentOptions` passthrough (proportionalLayout, …).
+     * `orientation` defaults to `HORIZONTAL` (required by dockview).
+     *
+     * `createComponent` is owned by the library (Svelte `mount` factory
+     * backed by the `widgets` registry) and cannot be overridden.
+     */
+    options?: Omit<GridviewComponentOptions, 'createComponent'> & {
+        orientation?: Orientation;
+    };
+    /** `bind:layout` — gridview JSON (`toJSON`/`fromJSON` shape). */
+    layout?: SerializedGridviewComponent;
+    /** `bind:handle` — `{ api, openPanel, registerWidget, removePanel, movePanel, setVisible, setActive }`. */
+    handle?: GridviewHandle<W>;
+    /**
+     * `bind:panels` — reactive list of current cells (`api.panels` snapshot).
+     * Refreshed on layout/add/remove/FromJSON, so `panels.length` is the
+     * sveltish cell count — no manual `onDidAddPanel` counting needed.
+     */
+    panels?: IGridviewPanel[];
+    /**
+     * `bind:activePanel` — the currently active cell. Derived from the
+     * per-panel `api.onDidActiveChange` (via the factory) plus explicit sync
+     * on the open/remove paths — `GridviewApi.onDidActivePanelChange` only
+     * fires on focus-driven activation, never on programmatic adds.
+     */
+    activePanel?: IGridviewPanel | undefined;
+    /** Extra classes for the root container. */
+    class?: string;
+    /** Declarative widgets (`<DvWidget>` children) — alternative to the `widgets` prop. */
+    children?: Snippet;
+    /** Fired once the component is mounted and `api` is ready. */
+    onReady?: (event: {
+        api: GridviewApi;
+        handle: GridviewHandle<W>;
+    }) => void;
+    onDidLayoutChange?: () => void;
+    onDidLayoutFromJSON?: () => void;
+    onDidAddPanel?: (panel: IGridviewPanel) => void;
+    onDidRemovePanel?: (panel: IGridviewPanel) => void;
+    onDidActivePanelChange?: (panel: IGridviewPanel | undefined) => void;
+}
+declare function $$render<const W extends GridviewWidgets>(): {
+    props: Props<W>;
+    exports: {};
+    bindings: "layout" | "handle" | "panels" | "activePanel";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<const W extends GridviewWidgets> {
+    props(): ReturnType<typeof $$render<W>>['props'];
+    events(): ReturnType<typeof $$render<W>>['events'];
+    slots(): ReturnType<typeof $$render<W>>['slots'];
+    bindings(): "layout" | "handle" | "panels" | "activePanel";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <const W extends GridviewWidgets>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<W>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<W>['props']>, ReturnType<__sveltets_Render<W>['events']>, ReturnType<__sveltets_Render<W>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<W>['bindings']>;
+    } & ReturnType<__sveltets_Render<W>['exports']>;
+    <const W extends GridviewWidgets>(internal: unknown, props: ReturnType<__sveltets_Render<W>['props']> & {}): ReturnType<__sveltets_Render<W>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const Gridview: $$IsomorphicComponent;
+type Gridview<const W extends GridviewWidgets> = InstanceType<typeof Gridview<W>>;
+export default Gridview;