From 50834e6129256ff4483dc2e226ed702737c038b1 Mon Sep 17 00:00:00 2001 From: Quang Phan Date: Thu, 11 Jul 2024 13:54:26 +0700 Subject: [PATCH] chore(toc): re-expose public typedef --- .changeset/chatty-bananas-protect.md | 5 ++++ packages/toc/src/actions/actions.d.ts | 13 ++++++++ packages/toc/src/actions/internals.js | 13 ++++---- packages/toc/src/actions/link.svelte.js | 4 +-- packages/toc/src/actions/root.svelte.js | 10 +++---- packages/toc/src/actions/types.d.ts | 20 ------------- .../toc/src/{attributes => }/attributes.d.ts | 11 ++++--- packages/toc/src/attributes/index.js | 26 ---------------- packages/toc/src/constants.js | 30 +++++++++++++++++-- packages/toc/src/index.js | 2 ++ packages/toc/src/toc.svelte.js | 8 ++--- .../toc/src/{types.d.ts => types.public.d.ts} | 4 +++ packages/toc/src/types.public.js | 3 ++ 13 files changed, 78 insertions(+), 71 deletions(-) create mode 100644 .changeset/chatty-bananas-protect.md create mode 100644 packages/toc/src/actions/actions.d.ts delete mode 100644 packages/toc/src/actions/types.d.ts rename packages/toc/src/{attributes => }/attributes.d.ts (94%) delete mode 100644 packages/toc/src/attributes/index.js rename packages/toc/src/{types.d.ts => types.public.d.ts} (98%) create mode 100644 packages/toc/src/types.public.js diff --git a/.changeset/chatty-bananas-protect.md b/.changeset/chatty-bananas-protect.md new file mode 100644 index 00000000..46864914 --- /dev/null +++ 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 new file mode 100644 index 00000000..f94e0aef --- /dev/null +++ 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 index 36efa0d3..4b3d8ea5 100644 --- 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} 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} */ + /** @type {Exclude} */ 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 index cb868663..3897b634 100644 --- 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 index 3d189c07..2ae7f5cf 100644 --- 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[]} */ + /** @type {Promise[]} */ 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 deleted file mode 100644 index 57b5bc6f..00000000 --- a/packages/toc/src/actions/types.d.ts +++ /dev/null @@ -1,20 +0,0 @@ -import type { Toc } from '../toc.svelte'; -import type { TocItem } from '../types'; - -/** - * @package - */ -export type TocCacheItem = { - items: Map; - activeTocItemId?: string; - observeThrottled: boolean; -}; - -export interface TocRootEventAttributes { - ontocinit?: (event: CustomEvent) => void; - ontocchange?: (event: CustomEvent) => void; -} - -export type TocRootAction = import('svelte/action').Action; -export type TocLinkAction = import('svelte/action').Action; - diff --git a/packages/toc/src/attributes/attributes.d.ts b/packages/toc/src/attributes.d.ts similarity index 94% rename from packages/toc/src/attributes/attributes.d.ts rename to packages/toc/src/attributes.d.ts index 1d1f7acd..7533a43c 100644 --- a/packages/toc/src/attributes/attributes.d.ts +++ b/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) => void; ontocchange?: (event: CustomEvent) => void; } + diff --git a/packages/toc/src/attributes/index.js b/packages/toc/src/attributes/index.js deleted file mode 100644 index 4e05fdb7..00000000 --- a/packages/toc/src/attributes/index.js +++ /dev/null @@ -1,26 +0,0 @@ -/** - * all relevant data attribute name literals - * @package - */ -export const ATTRIBUTES = /** @type {Record} */({ - // 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', -}); diff --git a/packages/toc/src/constants.js b/packages/toc/src/constants.js index 3fbd7908..dc7eb11d 100644 --- 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} */({ + // 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 index efdaf757..a3b6fe7c 100644 --- 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 index 1b3d55ec..c66c6160 100644 --- 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} + * @type {SvelteMap} */ 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 b/packages/toc/src/types.public.d.ts similarity index 98% rename from packages/toc/src/types.d.ts rename to packages/toc/src/types.public.d.ts index bff42e12..bde9b1e3 100644 --- a/packages/toc/src/types.d.ts +++ b/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 new file mode 100644 index 00000000..710b17ee --- /dev/null +++ b/packages/toc/src/types.public.js @@ -0,0 +1,3 @@ +/** to provide typing only, see types.public.d.ts */ +export {}; +