chore(toc): expose toclink parameters type in public api

Quang Phan · Quang Phan · commit 87d94dfc5840 · 2023-01-30T08:47:52.000+07:00
diff --git a/.changeset/metal-buckets-protect.md b/.changeset/metal-buckets-protect.md
@@ -0,0 +1,5 @@
+---
+'@svelte-put/toc': patch
+---
+
+expose `toclink` parameters types in build output
diff --git a/apps/docs/src/routes/(main)/docs/(pkg)/toc/+page.svelte b/apps/docs/src/routes/(main)/docs/(pkg)/toc/+page.svelte
@@ -40,7 +40,7 @@
     </ConnectedListItem>
     <ConnectedListItem>
       <p>
-        generate <code>id</code> attribute from element content,
+        generate <code>id</code> attribute from element <code>textContent</code>,
       </p>
     </ConnectedListItem>
     <ConnectedListItem>
@@ -77,22 +77,20 @@
   </p>
 
   <p class="c-callout-info">
-    The table of contents on this documentation site is generated by <code>toc</code> itself. Check
+    The table of contents in this documentation site is generated by <code>toc</code> itself. Check
     out the
     <ResourceLink
-      href="https://github.com/vnphanquang/svelte-put/blob/main/apps/docs/src/routes/(main)/+layout.svelte#L223-L227"
+      href="https://github.com/vnphanquang/svelte-put/blob/main/apps/docs/src/routes/(main)/+layout.svelte"
     >
-      source code here.
-    </ResourceLink>
+      source code here
+    </ResourceLink> (search for <code>tocStore</code>).
   </p>
 </section>
 
 <section>
   <h2 id="quick-start">Quick Start</h2>
   <p>
-    Given the following svelte component, let's see how <code>toc</code> searches for all headings,
-    generates id based on <code>textContent</code>, adds anchor tag, and tracks active element on
-    screen.
+    Given the following svelte component, let's see how <code>toc</code> does it job.
   </p>
   <Code code={codes.quickStart.input} title="quick start - input" />
   <p>
@@ -263,10 +261,10 @@
     <Code code={codes.caveat.prefer} title="think in terms of section" icon="info" />
     <Code code={codes.caveat.avoid} title="rather than flat individual elements" icon="error" />
     <p>
-      You might also find that when an anchor linked to a matching toc element being clicked on (to
-      scroll to said element), the toc element might not be the active one. This is explained with
-      with idiomatic solution in <ResourceLink id="complementary-toclink-action"
-        >toclink</ResourceLink
+      You might also find that when an anchor linked to its matching toc element is clicked on (to
+      scroll to said element), <code>toc</code> might not set that element as the active one. This
+      is explained and an idiomatic solution is provided in <ResourceLink
+        id="complementary-toclink-action">toclink</ResourceLink
       >.
     </p>
   </section>
@@ -332,11 +330,12 @@
   <p>Regarding markup, this is essentially the same as:</p>
   <Code code={codes.toclink.equivalence} title="toclink - markup equivalence" />
   <p>
-    However, <code>toclink</code> provides additional click listener that makes sure the toc item being
-    clicked on will be the active one.
+    However, <code>toclink</code> provides an additional click listener that makes sure the toc item
+    being clicked on will be the active one.
   </p>
   <p class="c-callout-warning">
-    This is not always guaranteed otherwise, because toc relies on
+    This is not always guaranteed otherwise (when not using <code>toclink</code>), because toc
+    relies on
     <code>IntersectionObserver</code>, and when a matching toc element is scrolled into view, the
     next one might already intersects with the viewport and become the active one.
   </p>
diff --git a/packages/actions/toc/api/docs/toc.md b/packages/actions/toc/api/docs/toc.md
@@ -23,6 +23,8 @@ Svelte action `use:toc` for building table of contents
 |  [TocEventDetails](./toc.toceventdetails.md) |  |
 |  [TocInitEventDetails](./toc.tociniteventdetails.md) | <code>event.detail</code> of <code>on:tocinit</code> |
 |  [TocItem](./toc.tocitem.md) | information about an extracted toc item |
+|  [TocLinkObserveParameters](./toc.toclinkobserveparameters.md) | configure relationship between the <code>observe</code> functionality of <code>toc</code> and <code>toclink</code> |
+|  [TocLinkParameters](./toc.toclinkparameters.md) | options to configure the behavior of the <code>toclink</code> svelte action |
 |  [TocObserveParameters](./toc.tocobserveparameters.md) | options to config how <code>toc</code> action create <code>IntersectionObserver</code> for each matching toc element |
 |  [TocParameters](./toc.tocparameters.md) |  |
 
diff --git a/packages/actions/toc/api/docs/toc.toclinkobserveparameters.attribute.md b/packages/actions/toc/api/docs/toc.toclinkobserveparameters.attribute.md
@@ -0,0 +1,24 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@svelte-put/toc](./toc.md) &gt; [TocLinkObserveParameters](./toc.toclinkobserveparameters.md) &gt; [attribute](./toc.toclinkobserveparameters.attribute.md)
+
+## TocLinkObserveParameters.attribute property
+
+boolean attribute(s) to indicate if this is linking to the active toc item
+
+<b>Signature:</b>
+
+```typescript
+attribute?: string | string[] | boolean;
+```
+
+## Remarks
+
+For this to work, it is required that `tocItem` be provided or the href is in the form `'#<toc-item-id>'`
+
+By default, `toclink` uses [MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) . For better performance, provide `store`
+
+Set `false` to disable this behavior
+
+Default to: `'data-toc-link-active'`
+
diff --git a/packages/actions/toc/api/docs/toc.toclinkobserveparameters.enabled.md b/packages/actions/toc/api/docs/toc.toclinkobserveparameters.enabled.md
@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@svelte-put/toc](./toc.md) &gt; [TocLinkObserveParameters](./toc.toclinkobserveparameters.md) &gt; [enabled](./toc.toclinkobserveparameters.enabled.md)
+
+## TocLinkObserveParameters.enabled property
+
+whether to enable this configuration Default to: `false`
+
+<b>Signature:</b>
+
+```typescript
+enabled?: boolean;
+```
diff --git a/packages/actions/toc/api/docs/toc.toclinkobserveparameters.md b/packages/actions/toc/api/docs/toc.toclinkobserveparameters.md
@@ -0,0 +1,22 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@svelte-put/toc](./toc.md) &gt; [TocLinkObserveParameters](./toc.toclinkobserveparameters.md)
+
+## TocLinkObserveParameters interface
+
+configure relationship between the `observe` functionality of `toc` and `toclink`
+
+<b>Signature:</b>
+
+```typescript
+export interface TocLinkObserveParameters 
+```
+
+## Properties
+
+|  Property | Modifiers | Type | Description |
+|  --- | --- | --- | --- |
+|  [attribute?](./toc.toclinkobserveparameters.attribute.md) |  | string \| string\[\] \| boolean | <i>(Optional)</i> boolean attribute(s) to indicate if this is linking to the active toc item |
+|  [enabled?](./toc.toclinkobserveparameters.enabled.md) |  | boolean | <i>(Optional)</i> whether to enable this configuration Default to: <code>false</code> |
+|  [throttleOnClick?](./toc.toclinkobserveparameters.throttleonclick.md) |  | number | <i>(Optional)</i> throttle the observe of <code>use:toc</code> on click |
+
diff --git a/packages/actions/toc/api/docs/toc.toclinkobserveparameters.throttleonclick.md b/packages/actions/toc/api/docs/toc.toclinkobserveparameters.throttleonclick.md
@@ -0,0 +1,22 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@svelte-put/toc](./toc.md) &gt; [TocLinkObserveParameters](./toc.toclinkobserveparameters.md) &gt; [throttleOnClick](./toc.toclinkobserveparameters.throttleonclick.md)
+
+## TocLinkObserveParameters.throttleOnClick property
+
+throttle the observe of `use:toc` on click
+
+<b>Signature:</b>
+
+```typescript
+throttleOnClick?: number;
+```
+
+## Remarks
+
+This ensures that the active toc item will be the same one that this link is pointing to. Otherwise, it is not guaranteed so, because `observe` is handled with `IntersectionObserver` the next items might already comes into viewport when this link is clicked.
+
+Set to 0 to disable throttling.
+
+Default to: `500`
+
diff --git a/packages/actions/toc/api/docs/toc.toclinkparameters.md b/packages/actions/toc/api/docs/toc.toclinkparameters.md
@@ -0,0 +1,23 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@svelte-put/toc](./toc.md) &gt; [TocLinkParameters](./toc.toclinkparameters.md)
+
+## TocLinkParameters interface
+
+options to configure the behavior of the `toclink` svelte action
+
+<b>Signature:</b>
+
+```typescript
+export interface TocLinkParameters 
+```
+
+## Properties
+
+|  Property | Modifiers | Type | Description |
+|  --- | --- | --- | --- |
+|  [observe?](./toc.toclinkparameters.observe.md) |  | [TocLinkObserveParameters](./toc.toclinkobserveparameters.md) \| boolean | <i>(Optional)</i> connect and reflect the <code>observe</code> functionality of <code>toc</code> |
+|  [store?](./toc.toclinkparameters.store.md) |  | [TocStore](./toc.tocstore.md) | <i>(Optional)</i> svelte store as used in <code>use:toc</code> |
+|  [tocId?](./toc.toclinkparameters.tocid.md) |  | string | <i>(Optional)</i> the ID of the toc operations. If not provided will search for the closest toc root (where <code>use:toc</code> is used) |
+|  [tocItem?](./toc.toclinkparameters.tocitem.md) |  | string \| [TocItem](./toc.tocitem.md) | <i>(Optional)</i> the matching toc item or its id to link to |
+
diff --git a/packages/actions/toc/api/docs/toc.toclinkparameters.observe.md b/packages/actions/toc/api/docs/toc.toclinkparameters.observe.md
@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@svelte-put/toc](./toc.md) &gt; [TocLinkParameters](./toc.toclinkparameters.md) &gt; [observe](./toc.toclinkparameters.observe.md)
+
+## TocLinkParameters.observe property
+
+connect and reflect the `observe` functionality of `toc`
+
+<b>Signature:</b>
+
+```typescript
+observe?: TocLinkObserveParameters | boolean;
+```
diff --git a/packages/actions/toc/api/docs/toc.toclinkparameters.store.md b/packages/actions/toc/api/docs/toc.toclinkparameters.store.md
@@ -0,0 +1,18 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@svelte-put/toc](./toc.md) &gt; [TocLinkParameters](./toc.toclinkparameters.md) &gt; [store](./toc.toclinkparameters.store.md)
+
+## TocLinkParameters.store property
+
+svelte store as used in `use:toc`
+
+<b>Signature:</b>
+
+```typescript
+store?: TocStore;
+```
+
+## Remarks
+
+recommended as an optimization when `observe.current` is enabled
+
diff --git a/packages/actions/toc/api/docs/toc.toclinkparameters.tocid.md b/packages/actions/toc/api/docs/toc.toclinkparameters.tocid.md
@@ -0,0 +1,22 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@svelte-put/toc](./toc.md) &gt; [TocLinkParameters](./toc.toclinkparameters.md) &gt; [tocId](./toc.toclinkparameters.tocid.md)
+
+## TocLinkParameters.tocId property
+
+the ID of the toc operations. If not provided will search for the closest toc root (where `use:toc` is used)
+
+<b>Signature:</b>
+
+```typescript
+tocId?: string;
+```
+
+## Remarks
+
+In case where the element of `use:toc` and element of `use:toclink` live in 2 different DOM subtrees, this is required otherwise `toclink` will not take no effect.
+
+This option is recommended where possible as an optimization to skip the search for the closest toc root.
+
+Alternatively, this can be skipped if the `store` option is provided
+
diff --git a/packages/actions/toc/api/docs/toc.toclinkparameters.tocitem.md b/packages/actions/toc/api/docs/toc.toclinkparameters.tocitem.md
@@ -0,0 +1,18 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@svelte-put/toc](./toc.md) &gt; [TocLinkParameters](./toc.toclinkparameters.md) &gt; [tocItem](./toc.toclinkparameters.tocitem.md)
+
+## TocLinkParameters.tocItem property
+
+the matching toc item or its id to link to
+
+<b>Signature:</b>
+
+```typescript
+tocItem?: string | TocItem;
+```
+
+## Remarks
+
+if provided, href will be added automatically if not already there Otherwise, you have to do that manually.
+
diff --git a/packages/actions/toc/api/toc.api.md b/packages/actions/toc/api/toc.api.md
@@ -76,11 +76,24 @@ export interface TocItem {
     text: string;
 }
 
-// Warning: (ae-forgotten-export) The symbol "TocLinkParameters" needs to be exported by the entry point index.d.ts
-//
 // @public
 export const toclink: Action<HTMLAnchorElement, TocLinkParameters>;
 
+// @public
+export interface TocLinkObserveParameters {
+    attribute?: string | string[] | boolean;
+    enabled?: boolean;
+    throttleOnClick?: number;
+}
+
+// @public
+export interface TocLinkParameters {
+    observe?: TocLinkObserveParameters | boolean;
+    store?: TocStore;
+    tocId?: string;
+    tocItem?: string | TocItem;
+}
+
 // @public
 export interface TocObserveParameters extends Omit<IntersectionObserverInit, 'threshold'> {
     enabled?: boolean;
diff --git a/packages/actions/toc/src/lib/index.ts b/packages/actions/toc/src/lib/index.ts
@@ -10,6 +10,12 @@ export * from './toc.action';
 export type { TocDataAttributes, TocEventAttributes } from './toc.attributes';
 export type { TocChangeEventDetails, TocEventDetails, TocInitEventDetails } from './toc.events';
 export type { TocItem } from './toc.item';
-export type { TocAnchorParameters, TocObserveParameters, TocParameters } from './toc.parameters';
+export type {
+  TocAnchorParameters,
+  TocObserveParameters,
+  TocParameters,
+  TocLinkParameters,
+  TocLinkObserveParameters,
+} from './toc.parameters';
 export type { TocStore, TocStoreValue } from './toc.store';
 export { createTocStore } from './toc.store';

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@svelte-put/toc': patch
 +---
++
 +expose `toclink` parameters types in build output