feat: doc update + add button bar and debug-related components

README.md

@@ -1,28 +1,37 @@
 # Molstar Svelte Library
 
-This is a collection of [Svelte](https://svelte.dev) components for [Mol\*](https://molstar.org) visualizations.
+*A collection of [Svelte](https://svelte.dev) components for [Mol\*](https://molstar.org)-based visualizations*
 
-![build status badge](https://github.com/0gust1/molstar-svelte/actions/workflows/build.yml/badge.svg?event=push) ![deploy status badge](https://github.com/0gust1/molstar-svelte/actions/workflows/deploy.yml/badge.svg?event=push) ![publish status badge](https://github.com/0gust1/molstar-svelte/actions/workflows/publish.yml/badge.svg?event=release)
 
+![build status badge](https://github.com/0gust1/molstar-svelte/actions/workflows/build.yml/badge.svg?event=push) ![deploy status badge](https://github.com/0gust1/molstar-svelte/actions/workflows/deploy.yml/badge.svg?event=push) ![publish status badge](https://github.com/0gust1/molstar-svelte/actions/workflows/publish.yml/badge.svg?event=release)
 
 ## Goals 
 - **Provide a set of composable components** that can be used to build web applications, websites or components enabling visualization and analysis of biomolecular structures.
 - **Provide a set of examples** of how to use the components in a Svelte application.
-- **Keep the components as simple as possible**, and let the user decide how to use them:  The goal **is not** to provide a full set of components with extensive Molstar API coverage, but rather a set of building blocks (and examples/inspirations) that can be used to build a custom application.
+- **Keep the components as simple as possible**, and let the user decide how to use them.
+- **The goal is not** to redo the Molstar Viewer in Svelte.
+- **The goal is not** to provide a full set of components with extensive Molstar API coverage, but rather a set of building blocks (and examples/inspirations) that can be used to build a custom application.
+
 
-The components are designed to be used in a [Svelte](https://svelte.dev) application, ~~but could be used in any framework that supports [Web Components](https://developer.mozilla.org/en-US/docs/Web/Web_Components)~~ (later).
+The components are designed to be used in a [Svelte](https://svelte.dev) or [SvelteKit](https://kit.svelte.dev/) application. ~~They could be also be used in any framework that supports [Web Components](https://developer.mozilla.org/en-US/docs/Web/Web_Components)~~ (later).
 
-## Please Note
+## Please Note!
 
-This package is still in early development, and the API is not stable. Until it reaches version 1.0.0, breaking changes may be introduced in any versions.
+**This package is still in early development, and the API is not stable.** Until it reaches version 1.0.0, breaking changes may be introduced in any versions.
 
-__Pin your dependencies__ if you're bold enough to use it! (and drop me a message, I'd love to hear about it!).
+**Pin your dependencies if you're bold enough to use it!** (and drop me a message, I'd really love to hear about it!).
 
-## Getting Started, Documentation, Showcase
+## Usage, Getting Started, Documentation, Showcase
 
 [https://0gust1.github.io/molstar-svelte/](https://0gust1.github.io/molstar-svelte/)
 
-## Development
+See the dedicated [Get started](https://0gust1.github.io/molstar-svelte/getting-started) page.
+
+## Feedback, issues, contributions, questions
+
+Feel free to initiate a discussion in the [Repository Discussions](https://github.com/0gust1/molstar-svelte/discussions) or [Repository Issues](https://github.com/0gust1/molstar-svelte/issues).
+
+## Library Development
 
 Install the dependencies...
 
@@ -37,7 +46,7 @@ npm run dev -- --open
 
 Everything inside `src/lib` is part of the library, everything inside `src/routes` is used to generate the documentation/showcase/e2e website.
 
-## Building
+### Building
 
 To build the library:
 
@@ -53,10 +62,19 @@ npm run build
 
 You can preview the production build with `npm run preview`.
 
-## Updating the documentation/showcase
+### Updating the documentation/showcase website
 
 Website/doc deployment is done through github actions, on push on `master` 
 
-## Publishing
+### Publishing on npmjs.com
 
 Publishing is done through github actions, on release creation on `master`.
+
+## Licensing and attributions
+
+`molstar-svelte` is licensed under the [MIT License](https://opensource.org/license/mit/).
+
+**Mol\*:**
+> David Sehnal, Sebastian Bittrich, Mandar Deshpande, Radka Svobodová, Karel Berka, Václav Bazgier, Sameer Velankar, Stephen K Burley, Jaroslav Koča, Alexander S Rose:  
+> [Mol* Viewer: modern web app for 3D visualization and analysis of large biomolecular structures, Nucleic Acids Research, 2021; 10.1093/nar/gkab31](https://academic.oup.com/nar/article/49/W1/W431/6270780).  
+In memory of Jaroslav Koča. 

src/app.d.ts

@@ -5,7 +5,14 @@ declare global {
 		// interface Error {}
 		// interface Locals {}
 		// interface PageData {}
-		// interface Platform {
+		// interface Platform {}
+
+		interface MdsvexFile {
+			default: import('svelte/internal').SvelteComponent;
+			metadata: Record<string, string>;
+		}
+
+		type MdsvexResolver = () => Promise<MdsvexFile>;
 	}
 	declare const __PKG_VERSION__: string;
 	declare const __PKG_NAME__: string;

src/lib/controls/ButtonBar.svelte

@@ -0,0 +1,54 @@
+<script lang="ts">
+	/**
+	 * Component to display a button bar giving some action over a Molstar plugin instance.
+	 */
+
+	import { getContext } from 'svelte';
+	import { PluginCommands } from 'molstar/lib/mol-plugin/commands';
+	import type { PluginContext } from 'molstar/lib/mol-plugin/context';
+	import { ViewportScreenshotHelper } from 'molstar/lib/mol-plugin/util/viewport-screenshot';
+
+	export { clazz as class };
+	let clazz = '';
+	const plugin = getContext<{ getPlugin: () => PluginContext }>('molstar').getPlugin();
+
+	const resetCamera = () => {
+		PluginCommands.Camera.Reset(plugin);
+	};
+
+	const screenshotToClipBoard = () => {
+		const vpsh = new ViewportScreenshotHelper(plugin);
+		vpsh.copyToClipboard();
+	};
+
+	const screenshotDownload = () => {
+		const vpsh = new ViewportScreenshotHelper(plugin);
+		vpsh.download('screenshot.png');
+	};
+</script>
+
+<div class="button-bar {clazz || ''}">
+	<ul>
+		<li>
+			<button type="button" on:click={resetCamera}>Reset Camera</button>
+		</li>
+		<li>
+			<button type="button" on:click={screenshotToClipBoard}>Screenshot (to clipboard)</button>
+		</li>
+		<li><button type="button" on:click={screenshotDownload}>Screenshot (save)</button></li>
+	</ul>
+</div>
+
+<style lang="postcss">
+	.button-bar {
+	}
+	.button-bar ul {
+		@apply flex gap-1 bg-slate-700 text-xs text-slate-50 p-1;
+	}
+	.button-bar li {
+		@apply gap-1;
+	}
+	.button-bar button {
+		@apply bg-slate-400 px-2 py-1 rounded border border-slate-500;
+	}
+</style>

src/lib/controls/debug/CollapsableDebugDetail.svelte

@@ -0,0 +1,28 @@
+<script lang="ts">
+	export let title: string;
+	export let dataToDisplay: any;
+	export let isOpen = false;
+</script>
+
+<details class="text-xs my-2" bind:open={isOpen}>
+	<summary class="font-medium">{title}</summary>
+
+	<div class=" text-green-200 bg-slate-500 bg-opacity-60 p-2">
+		{#if isOpen}
+			<slot>
+				<pre>
+{JSON.stringify(dataToDisplay, null, 2)}
+</pre>
+			</slot>
+		{/if}
+	</div>
+</details>
+
+<style lang="postcss">
+	details summary {
+		@apply cursor-pointer;
+	}
+	details summary:hover {
+		@apply bg-orange-500 bg-opacity-20;
+	}
+</style>

src/lib/controls/debug/DebugPanel.svelte

@@ -0,0 +1,90 @@
+<script lang="ts">
+	import { getContext } from 'svelte';
+	import type { PluginContext } from 'molstar/lib/mol-plugin/context';
+	import CollapsableDebugDetail from './CollapsableDebugDetail.svelte';
+	import { SyncBehaviors } from 'molstar/lib/mol-plugin/behavior/static/state';
+	import { Interactions } from 'molstar/lib/mol-plugin/behavior/dynamic/custom-props';
+
+	const plugin = getContext<{ getPlugin: () => PluginContext }>('molstar').getPlugin();
+
+	const closedS = plugin.events.canvas3d.settingsUpdated;
+	const proS = plugin.events.task.progress;
+	const finS = plugin.events.task.finished;
+	const interClickS = plugin.behaviors.interaction.click;
+	const interDragS = plugin.behaviors.interaction.drag;
+	const molstarLogEventsS = plugin.events.log;
+	const didDrawS = plugin.canvas3d?.didDraw;
+	const reprCount = plugin.canvas3d?.reprCount;
+	const stateChangedS = plugin.canvas3d?.camera.stateChanged;
+	const highlightS = plugin.behaviors.labels.highlight;
+	const dragS = plugin.behaviors.interaction.drag.asObservable();
+
+	//const data1S = plugin.canvas3d?.camera.po
+
+	export let panelOpen = true;
+
+	let logs = plugin.log.entries;
+
+	$: logs = molstarLogEventsS ? plugin.log.entries : '';
+</script>
+
+<section class="bg-slate-400 text-slate-100 bg-opacity-70 p-2">
+	<p class="text-right">
+		<button
+			type="button"
+			class="text-xs bg-slate-400 px-2 py-1 rounded border border-slate-500"
+			on:click={() => {
+				panelOpen = !panelOpen;
+			}}>{panelOpen ? 'Hide' : 'Show'} debug panel</button
+		>
+	</p>
+	<div class:open={panelOpen} class="hidden mt-2">
+		<h1 class="font-medium">Molstar instance debug</h1>
+		<button
+			type="button"
+			class="text-xs p-1 border border-slate-300"
+			on:click={() => {
+				console.dir(plugin);
+			}}>Log in browser console</button
+		>
+		<CollapsableDebugDetail
+			title="plugin.events.canvas3d.settingsUpdated"
+			dataToDisplay={$closedS}
+		/>
+
+		<h2 class="font-medium">Logs</h2>
+
+		<CollapsableDebugDetail title="logs" dataToDisplay={null}>
+			<div class="max-h-screen overflow-y-auto">
+				{#each [...logs] as log}
+					<p>{log.type} - {log.message}</p>
+				{/each}
+			</div>
+		</CollapsableDebugDetail>
+
+		<h2 class="font-medium">plugin.events.task</h2>
+		<CollapsableDebugDetail title="plugin.events.task.progress" dataToDisplay={$proS} />
+
+		<CollapsableDebugDetail title="plugin.events.task.finished" dataToDisplay={$finS} />
+
+		<h2 class="font-medium">Behavior</h2>
+		<CollapsableDebugDetail title="Drag behav. modifiers" dataToDisplay={$interDragS.modifiers} />
+
+		<CollapsableDebugDetail title="Click behav. modifiers" dataToDisplay={$interClickS.modifiers} />
+
+		<CollapsableDebugDetail title="DidDraw" dataToDisplay={$didDrawS} />
+		<CollapsableDebugDetail title="reprCount" dataToDisplay={$reprCount} />
+		<CollapsableDebugDetail title="stateChanged" dataToDisplay={$stateChangedS} />
+		<CollapsableDebugDetail title="highlights" dataToDisplay={$highlightS} />
+		<CollapsableDebugDetail title="drag" dataToDisplay={$dragS} />
+	</div>
+</section>
+
+<style lang="postcss">
+	.open {
+		@apply block;
+	}
+	pre {
+		@apply border border-slate-700;
+	}
+</style>

src/routes/+page.svelte

@@ -0,0 +1,8 @@
+<script lang="ts">
+	import type { SvelteComponentTyped } from 'svelte/internal';
+	export let data;
+	type C = $$Generic<typeof SvelteComponentTyped<any, any, any>>;
+	$: component = data.content as unknown as C;
+</script>
+
+<svelte:component this={component} />

src/routes/+page.ts

@@ -0,0 +1,9 @@
+export const load = async () => {
+	const readmeComponentImporter = (await import.meta.glob('../../README.md')) as unknown as Record<
+		string,
+		App.MdsvexResolver
+	>;
+	const postResolver = await readmeComponentImporter['../../README.md']();
+	const post = await postResolver.default;
+	return { content: post };
+};