chore(toc): re-expose public typedef

vnphanquang · Jul 11, 2024 · 50834e6 · 50834e6
1 parent 2414af5
commit 50834e6
Show file tree

Hide file tree

Showing 13 changed files with 78 additions and 71 deletions.
diff --git a/.changeset/chatty-bananas-protect.md b/.changeset/chatty-bananas-protect.md
@@ -0,0 +1,5 @@
+---
+'@svelte-put/toc': patch
+---
+
+re-expose public typedef (following https://github.com/Rich-Harris/dts-buddy/pull/82)
diff --git a/packages/toc/src/actions/actions.d.ts b/packages/toc/src/actions/actions.d.ts
@@ -0,0 +1,13 @@
+import { TocRootEventAttributes } from '../attributes';
+import { TocItem } from '../types.public';
+
+export type TocRootAction = import('svelte/action').Action<
+	HTMLElement,
+	undefined,
+	TocRootEventAttributes
+>;
+export type TocLinkAction = import('svelte/action').Action<
+	HTMLAnchorElement,
+	TocItem | string | undefined
+>;
+
diff --git a/packages/toc/src/actions/internals.js b/packages/toc/src/actions/internals.js
@@ -1,9 +1,9 @@
-import { ATTRIBUTES } from '../attributes/index.js';
+import { ATTRIBUTES } from '../constants.js';
 
 /**
  * @package
  * @param {HTMLElement} element
- * @param {import('../types').TocAnchorConfig} anchor
+ * @param {import('../types.public').TocAnchorConfig} anchor
  * @param {string} tocId
  * @returns {HTMLAnchorElement | undefined}
  */
@@ -104,19 +104,19 @@ export function processAnchor(element, anchor, tocId) {
 /**
  * @package
  * @param {HTMLElement} element
- * @param {import('../types').TocObserveConfig} observe
+ * @param {import('../types.public').TocObserveConfig} observe
  * @param {string} tocId
  * @param {(activeTocItemId?: string) => void} updateActiveTocItem
  * @param {Record<number, IntersectionObserver>} observerPool
- * @returns {import('../types').TocItem['observe']}
+ * @returns {import('../types.public').TocItem['observe']}
  */
 export function processObserve(element, observe, tocId, updateActiveTocItem, observerPool) {
 	if (!observe.enabled) return undefined;
 	const parentElement = element.parentElement;
-	/** @type {Exclude<import('../types').TocObserveConfig['strategy'], 'auto'>} */
+	/** @type {Exclude<import('../types.public').TocObserveConfig['strategy'], 'auto'>} */
 	let rStrategy;
 	const userDefinedStrategy =
-		/** @type {import('../types').TocObserveConfig['strategy']} */ (
+		/** @type {import('../types.public').TocObserveConfig['strategy']} */ (
 			element.getAttribute(ATTRIBUTES.strategy)
 		) || observe.strategy;
 	if (typeof userDefinedStrategy !== 'number' && userDefinedStrategy !== 'auto') {
@@ -249,3 +249,4 @@ function slugify(text) {
 		.replace(/^-+/, '')
 		.replace(/-+/g, '-');
 }
+
diff --git a/packages/toc/src/actions/link.svelte.js b/packages/toc/src/actions/link.svelte.js
@@ -1,10 +1,10 @@
 import { on } from 'svelte/events';
 
-import { ATTRIBUTES } from '../attributes/index.js';
+import { ATTRIBUTES } from '../constants.js';
 
 /**
  * @param {import('../toc.svelte.js').Toc} toc
- * @returns {import('./types.js').TocLinkAction}
+ * @returns {import('./actions').TocLinkAction}
  */
 export function createTocLinkAction(toc) {
 	// eslint-disable-next-line no-undef

diff --git a/packages/toc/src/actions/root.svelte.js b/packages/toc/src/actions/root.svelte.js
@@ -1,7 +1,6 @@
 import { tick } from 'svelte';
 
-import { ATTRIBUTES } from '../attributes/index.js';
-import { DEFAULT_TOC_CONFIG } from '../constants.js';
+import { DEFAULT_TOC_CONFIG, ATTRIBUTES } from '../constants.js';
 
 import {
 	extractElementText,
@@ -12,7 +11,7 @@ import {
 
 /**
  * @param {import('../toc.svelte.js').Toc} toc
- * @returns {import('./types.js').TocRootAction}
+ * @returns {import('./actions').TocRootAction}
  */
 export function createTocRootAction(toc) {
 	// eslint-disable-next-line no-undef
@@ -91,7 +90,7 @@ export function createTocRootAction(toc) {
 			const { anchor, observe, scrollMarginTop } = toc.config;
 			/** @type {HTMLElement[]} */
 			const elements = Array.from(node.querySelectorAll(selector));
-			/** @type {Promise<import('../types').TocItem['observe']>[]} */
+			/** @type {Promise<import('../types.public').TocItem['observe']>[]} */
 			const observePromises = [];
 
 			node.toggleAttribute(ATTRIBUTES.observeActiveId, true);
@@ -121,7 +120,7 @@ export function createTocRootAction(toc) {
 						new Promise((resolve) => {
 							const rObserve = processObserve(element, observe, tocId, updateActiveTocItem, intersectionObservers);
 							if (toc.items.has(tocId)) {
-								const tocItem = /** @type {import('../types').TocItem} */ (toc.items.get(tocId));
+								const tocItem = /** @type {import('../types.public').TocItem} */ (toc.items.get(tocId));
 								toc.items.set(tocId, { ...tocItem, observe: rObserve });
 							}
 
@@ -157,3 +156,4 @@ export function createTocRootAction(toc) {
 		};
 	};
 }
+
diff --git a/packages/toc/src/actions/types.d.ts b/packages/toc/src/actions/types.d.ts
diff --git a/packages/toc/src/attributes/attributes.d.ts → packages/toc/src/attributes.d.ts b/packages/toc/src/attributes/attributes.d.ts → packages/toc/src/attributes.d.ts
@@ -1,9 +1,8 @@
-import type { Toc } from '../toc.svelte.js';
-import type { TocObserveConfig } from '../types';
+import type { Toc } from './toc.svelte.js';
+import type { TocObserveConfig } from './types.public';
 
 /**
  * Data attributes to override `toc` behavior per matching element
- *
  */
 export interface TocElementDataAttributes {
 	/** whether to ignore this element when searching for matching elements */
@@ -96,10 +95,10 @@ export interface TocReferenceMarkerDataAttributes {
 export interface TocDataAttributes extends TocElementDataAttributes, TocObserveDataAttributes, TocReferenceMarkerDataAttributes {}
 
 /**
- * ambient typing for `toc` event handlers
- *
+ * event attributes on toc root, set by `toc.actions.root`
  */
-export interface TocEventAttributes {
+export interface TocRootEventAttributes {
 	ontocinit?: (event: CustomEvent<Toc>) => void;
 	ontocchange?: (event: CustomEvent<Toc>) => void;
 }
+
diff --git a/packages/toc/src/attributes/index.js b/packages/toc/src/attributes/index.js
diff --git a/packages/toc/src/constants.js b/packages/toc/src/constants.js
@@ -1,9 +1,34 @@
-import { ATTRIBUTES } from './attributes/index.js';
+/**
+ * all relevant data attribute name literals
+ * @package
+ */
+export const ATTRIBUTES = /** @type {Record<string, keyof (import('./attributes').TocDataAttributes)>} */({
+	// markers from `@svelte-put/preprocess-auo-slug`
+	autoslug: 'data-auto-slug',
+	autoSlugAnchor: 'data-auto-slug-anchor',
+	autoSlugAnchorPosition: 'data-auto-slug-anchor-position',
+	// markers
+	toc: 'data-toc',
+	anchor: 'data-toc-anchor',
+	root: 'data-toc-root',
+	// customization per matching element
+	id: 'data-toc-id',
+	ignore: 'data-toc-ignore',
+	strategy: 'data-toc-strategy',
+	threshold: 'data-toc-threshold',
+	// tracking information for `IntersectionObserver`
+	observeFor: 'data-toc-observe-for',
+	observeThrottled: 'data-toc-observe-throttled',
+	observeActiveId: 'data-toc-observe-active-id',
+	// for elements that `use:toclink`
+	linkFor: 'data-toc-link-for',
+	linkActive: 'data-toc-link-active',
+});
 
 /**
  * The default {@link TocConfig} for `toc` action
  */
-export const DEFAULT_TOC_CONFIG = /** @satisfies {import('./types.js').TocConfig} */ ({
+export const DEFAULT_TOC_CONFIG = /** @satisfies {import('./types.public').TocConfig} */ ({
 	selector: ':where(h1, h2, h3, h4, h5, h6)',
 	ignore: '.toc-exclude',
 	scrollMarginTop: 0,
@@ -28,3 +53,4 @@ export const DEFAULT_TOC_CONFIG = /** @satisfies {import('./types.js').TocConfig
 		},
 	},
 });
+
diff --git a/packages/toc/src/index.js b/packages/toc/src/index.js
@@ -1,3 +1,5 @@
 // Copyright (c) Quang Phan. All rights reserved. Licensed under the MIT license.
 
 export { Toc } from './toc.svelte.js';
+export * from './types.public.js';
+
diff --git a/packages/toc/src/toc.svelte.js b/packages/toc/src/toc.svelte.js
@@ -14,20 +14,20 @@ export class Toc {
 
 	/**
 	 * the extracted toc items, populated on mount (`tocinit`)
-	 * @type {SvelteMap<string, import('./types.js').TocItem>}
+	 * @type {SvelteMap<string, import('./types.public').TocItem>}
 	 */
 	items = new SvelteMap();
 
 	/**
 	 * the active toc items, set on update (`tocchange`) if `observer` is set to true
-	 * @type {import('./types.js').TocItem | undefined}
+	 * @type {import('./types.public').TocItem | undefined}
 	 */
 	// eslint-disable-next-line no-undef
 	activeItem = $state(undefined);
 
 	/**
 	 * configuration for `toc` behavior
-	 * @type {import('./types.js').TocConfig}
+	 * @type {import('./types.public').TocConfig}
 	 */
 	// eslint-disable-next-line no-undef
 	config = $state(DEFAULT_TOC_CONFIG);
@@ -57,7 +57,7 @@ export class Toc {
 	observeThrottled = $state(false);
 
 	/**
-	 * @param {import('./types.js').TocInit} [init]
+	 * @param {import('./types.public').TocInit} [init]
 	 */
 	constructor(init) {
 		if (init) {

diff --git a/packages/toc/src/types.d.ts → packages/toc/src/types.public.d.ts b/packages/toc/src/types.d.ts → packages/toc/src/types.public.d.ts
@@ -186,3 +186,7 @@ export interface TocItem {
 		element: HTMLElement;
 	};
 }
+
+export * from './attributes';
+export * from './actions/actions';
+
diff --git a/packages/toc/src/types.public.js b/packages/toc/src/types.public.js
@@ -0,0 +1,3 @@
+/** to provide typing only, see types.public.d.ts */
+export {};
+
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		/** to provide typing only, see types.public.d.ts */
		export {};