docs(*/README): add quick start section for better impression on npm

vnphanquang · Feb 6, 2023 · 227e8dc · 227e8dc · vercel · Feb 6, 2023
1 parent 2bd5765
commit 227e8dc
Show file tree

Hide file tree

Showing 12 changed files with 251 additions and 70 deletions.
diff --git a/.changeset/tasty-numbers-peel.md b/.changeset/tasty-numbers-peel.md
@@ -0,0 +1,15 @@
+---
+'@svelte-put/preprocess-auto-slug': patch
+'@svelte-put/clickoutside': patch
+'@svelte-put/dragscroll': patch
+'@svelte-put/intersect': patch
+'@svelte-put/shortcut': patch
+'@svelte-put/movable': patch
+'@svelte-put/resize': patch
+'@svelte-put/copy': patch
+'@svelte-put/toc': patch
+'@svelte-put/avatar': patch
+'@svelte-put/modal': patch
+---
+
+add "Quick Start" section in package README
diff --git a/packages/actions/clickoutside/README.md b/packages/actions/clickoutside/README.md
@@ -10,13 +10,27 @@ Svelte action `use:clickoutside` - event for clicking outside a node
 
 </div>
 
+## `svelte-put`
+
+This package is part of the [@svelte-put][github.monorepo] family. For contributing guideline and more, refer to its [readme][github.monorepo].
+
 ## Usage & Documentation
 
 [See the dedicated documentation page here][docs].
 
-## `svelte-put`
+## Quick Start
 
-This package is part of the [@svelte-put][github.monorepo] family. For contributing guideline and more, refer to its [readme][github.monorepo].
+```html
+<script lang="ts">
+  import { clickoutside } from '@svelte-put/clickoutside';
+
+  function doSomething(e: CustomEvent<MouseEvent>) {
+    console.log(e.target);
+  }
+</script>
+
+<div use:clickoutside on:clickoutside="{doSomething}" />
+```
 
 ## [Changelog][github.changelog]
 

diff --git a/packages/actions/copy/README.md b/packages/actions/copy/README.md
@@ -8,13 +8,27 @@ Svelte action `use:copy` and utility for copying text to clipboard
 
 </div>
 
+## `svelte-put`
+
+This package is part of the [@svelte-put][github.monorepo] family. For contributing guideline and more, refer to its [readme][github.monorepo].
+
 ## Usage & Documentation
 
 [See the dedicated documentation page here][docs].
 
-## `svelte-put`
+## Quick Start
 
-This package is part of the [@svelte-put][github.monorepo] family. For contributing guideline and more, refer to its [readme][github.monorepo].
+```html
+<script lang="ts">
+  import { copy, type CopyDetail } from '@svelte-put/copy';
+
+  function handleCopied(e: CustomEvent<CopyDetail>) {
+    console.log('Text copied:', e.detail.text);
+  }
+</script>
+
+<button type="button" use:copy on:copied="{handleCopied}">Click to copy this</button>
+```
 
 ## [Changelog][github.changelog]
 

diff --git a/packages/actions/dragscroll/README.md b/packages/actions/dragscroll/README.md
@@ -2,51 +2,31 @@
 
 # `@svelte-put/dragscroll`
 
-[![npm.badge]][npm] [![bundlephobia.badge]][bundlephobia] [![repl.badge]][repl]
+[![npm.badge]][npm] [![bundlephobia.badge]][bundlephobia] [![docs.badge]][docs]
 
 Svelte action `use:dragscroll` for pointer drag-to-scroll behavior
 
 </div>
 
-## Table of Contents
-
-<details open>
-  <summary>Show / hide</summary>
-
-- [`@svelte-put/dragscroll`](#svelte-putdragscroll)
-  - [Table of Contents](#table-of-contents)
-  - [`svelte-put`](#svelte-put)
-  - [Changelog](#changelog)
-  - [Installation](#installation)
-  - [Documentation](#documentation)
-
-</details>
-
 ## `svelte-put`
 
 This package is part of the [@svelte-put][github.monorepo] family. For contributing guideline and more, refer to its [readme][github.monorepo].
 
-## [Changelog][github.changelog]
+## Usage & Documentation
 
-## Installation
+[See the dedicated documentation page here][docs].
 
-```bash
-npm install -D @svelte-put/dragscroll
-```
+## Quick Start
 
-```bash
-yarn add -D @svelte-put/dragscroll
-```
+```html
+<script>
+  import { dragscroll } from '@svelte-put/dragscroll';
+</script>
 
-```bash
-pnpm add -D @svelte-put/dragscroll
+<div use:dragscroll>...</div>
 ```
 
-</details>
-
-## Documentation
-
-For detailed documentation, see the [extracted API][github.api].
+## [Changelog][github.changelog]
 
 <p align="center">
   <a href="https://www.buymeacoffee.com/vnphanquang" target="_blank">
@@ -64,13 +44,12 @@ For detailed documentation, see the [extracted API][github.api].
 [github.monorepo]: https://github.com/vnphanquang/svelte-put
 [github.changelog]: https://github.com/vnphanquang/svelte-put/blob/main/packages/actions/dragscroll/CHANGELOG.md
 [github.issues]: https://github.com/vnphanquang/svelte-put/issues?q=
-[github.api]: https://github.com/vnphanquang/svelte-put/blob/main/packages/actions/dragscroll/api/docs/index.md
 
 <!-- heading badge -->
 
 [npm.badge]: https://img.shields.io/npm/v/@svelte-put/dragscroll
 [npm]: https://www.npmjs.com/package/@svelte-put/dragscroll
 [bundlephobia.badge]: https://img.shields.io/bundlephobia/minzip/@svelte-put/dragscroll?label=minzipped
 [bundlephobia]: https://bundlephobia.com/package/@svelte-put/dragscroll
-[repl]: https://svelte.dev/repl/835eacce6ac44aff95a7cb0bb5ca200d
-[repl.badge]: https://img.shields.io/static/v1?label=&message=Svelte+REPL&logo=svelte&logoColor=fff&color=ff3e00
+[docs]: https://svelte-put.vnphanquang.com/docs/dragscroll
+[docs.badge]: https://img.shields.io/badge/-Docs%20Site-blue
diff --git a/packages/actions/intersect/README.md b/packages/actions/intersect/README.md
@@ -10,13 +10,29 @@ Svelte action `use:intersect` - wrapper for [IntersectionObserver](https://devel
 
 </div>
 
+## `svelte-put`
+
+This package is part of the [@svelte-put][github.monorepo] family. For contributing guideline and more, refer to its [readme][github.monorepo].
+
 ## Usage & Documentation
 
 [See the dedicated documentation page here][docs].
 
-## `svelte-put`
+## Quick Start
 
-This package is part of the [@svelte-put][github.monorepo] family. For contributing guideline and more, refer to its [readme][github.monorepo].
+```html
+<script lang="ts">
+  import { intersect, type IntersectDetail } from '@svelte-put/intersect';
+  function onIntersect(e: CustomEvent<IntersectDetail>) {
+    const { observer, entries, direction } = e.detail;
+    console.log('the observer itself', observer);
+    console.log('scrolling direction:', direction);
+    console.log('intersecting:', entries[0]?.isIntersecting ? 'entering' : 'leaving');
+  }
+</script>
+
+<div use:intersect on:intersect="{onIntersect}" on:intersectonce />
+```
 
 ## [Changelog][github.changelog]
 

diff --git a/packages/actions/movable/README.md b/packages/actions/movable/README.md
@@ -10,13 +10,23 @@ Svelte action `use:movable` - make a node move on mousedown & mousemove
 
 </div>
 
+## `svelte-put`
+
+This package is part of the [@svelte-put][github.monorepo] family. For contributing guideline and more, refer to its [readme][github.monorepo].
+
 ## Usage & Documentation
 
 [See the dedicated documentation page here][docs].
 
-## `svelte-put`
+## Quick Start
 
-This package is part of the [@svelte-put][github.monorepo] family. For contributing guideline and more, refer to its [readme][github.monorepo].
+```html
+<script lang="ts">
+  import { movable } from '@svelte-put/movable';
+</script>
+
+<div class="h-20 w-20" use:movable>...</div>
+```
 
 ## [Changelog][github.changelog]
 

diff --git a/packages/actions/resize/README.md b/packages/actions/resize/README.md
@@ -2,7 +2,7 @@
 
 # `@svelte-put/resize`
 
-[![npm.badge]][npm] [![bundlephobia.badge]][bundlephobia]
+[![npm.badge]][npm] [![bundlephobia.badge]][bundlephobia] [![docs.badge]][docs]
 
 Svelte action `use:resize` for pointer drag-to-scroll behavior
 
@@ -12,27 +12,26 @@ Svelte action `use:resize` for pointer drag-to-scroll behavior
 
 This package is part of the [@svelte-put][github.monorepo] family. For contributing guideline and more, refer to its [readme][github.monorepo].
 
-## [Changelog][github.changelog]
+## Usage & Documentation
 
-## Installation
+[See the dedicated documentation page here][docs].
 
-```bash
-npm install -D @svelte-put/resize
-```
+## Quick Start
 
-```bash
-yarn add -D @svelte-put/resize
-```
+```html
+<script lang="ts">
+  import { resize } from '@svelte-put/resize';
+  import type { ResizeDetail } from '@svelte-put/resize';
 
-```bash
-pnpm add -D @svelte-put/resize
-```
+  function onResized(e: CustomEvent<ResizeDetail>) {
+    console.log(e.detail);
+  }
+</script>
 
-</details>
-
-## Documentation
+<div use:resize on:resized="{onResized}" />
+```
 
-For detailed documentation, see the [extracted API][github.api].
+## [Changelog][github.changelog]
 
 <p align="center">
   <a href="https://www.buymeacoffee.com/vnphanquang" target="_blank">
@@ -50,11 +49,12 @@ For detailed documentation, see the [extracted API][github.api].
 [github.monorepo]: https://github.com/vnphanquang/svelte-put
 [github.changelog]: https://github.com/vnphanquang/svelte-put/blob/main/packages/actions/resize/CHANGELOG.md
 [github.issues]: https://github.com/vnphanquang/svelte-put/issues?q=
-[github.api]: https://github.com/vnphanquang/svelte-put/blob/main/packages/actions/resize/api/docs/index.md
 
 <!-- heading badge -->
 
 [npm.badge]: https://img.shields.io/npm/v/@svelte-put/resize
 [npm]: https://www.npmjs.com/package/@svelte-put/resize
 [bundlephobia.badge]: https://img.shields.io/bundlephobia/minzip/@svelte-put/resize?label=minzipped
 [bundlephobia]: https://bundlephobia.com/package/@svelte-put/resize
+[docs]: https://svelte-put.vnphanquang.com/docs/resize
+[docs.badge]: https://img.shields.io/badge/-Docs%20Site-blue
diff --git a/packages/actions/shortcut/README.md b/packages/actions/shortcut/README.md
@@ -8,13 +8,29 @@ Svelte action `use:shortcut` - add event listener for keyboard shortcuts
 
 </div>
 
+## `svelte-put`
+
+This package is part of the [@svelte-put][github.monorepo] family. For contributing guideline and more, refer to its [readme][github.monorepo].
+
 ## Usage & Documentation
 
 [See the dedicated documentation page here][docs].
 
-## `svelte-put`
+## Quick Start
 
-This package is part of the [@svelte-put][github.monorepo] family. For contributing guideline and more, refer to its [readme][github.monorepo].
+```html
+<script lang="ts">
+  import { shortcut, type ShortcutEventDetails } from '@svelte-put/shortcut';
+
+  function handleK(detail: ShortcutEventDetails) {
+    console.log('attached node:', detail.node);
+    console.log('original trigger config:', detail.trigger);
+  }
+</script>
+
+<svelte:window use:shortcut={{ trigger: { key: 'k', modifier: ['ctrl', 'meta'], callback: handleK,
+}, }} />
+```
 
 ## [Changelog][github.changelog]
 

diff --git a/packages/actions/toc/README.md b/packages/actions/toc/README.md
@@ -8,13 +8,51 @@ Svelte `use:toc` action for building table of contents
 
 </div>
 
+## `svelte-put`
+
+This package is part of the [@svelte-put][github.monorepo] family. For contributing guideline and more, refer to its [readme][github.monorepo].
+
 ## Usage & Documentation
 
 [See the dedicated documentation page here][docs].
 
-## `svelte-put`
-
-This package is part of the [@svelte-put][github.monorepo] family. For contributing guideline and more, refer to its [readme][github.monorepo].
+## Quick Start
+
+```html
+<script>
+  import { toc, createTocStore, toclink } from '@svelte-put/toc';
+  const tocStore = createTocStore();
+</script>
+
+<main use:toc={{ store: tocStore, observe: true }}>
+  <h1>Page Heading</h1>
+
+  <section>
+    <h2>Table of Contents</h2>
+    {#if Object.values($tocStore.items).length}
+      <ul>
+        {#each Object.values($tocStore.items) as tocItem}
+          <li>
+            <!-- svelte-ignore a11y-missing-attribute -->
+            <a use:toclink={{ store: tocStore, tocItem, observe: true }} />
+          </li>
+        {/each}
+      </ul>
+    {/if}
+  </section>
+
+  <section>
+    <h2>Section Heading Level 2</h2>
+    <p>...</p>
+  </section>
+
+  <section>
+    <h3>Section Heading Level 3</h3>
+    <p>...</p>
+  </section>
+  <!-- ... -->
+</main>
+```
 
 ## Acknowledgement