fix(types): correct TypeScript type resolution (fixes #14) (#16)

Fixes TS type resolution & improves DX. Updates `demo`. Adds `.astro/` to .gitignore.

Fixes #14

Author: theisel

.changeset/bitter-cats-camp.md

@@ -0,0 +1,5 @@
+---
+"astro-toc": patch
+---
+
+Fix TypeScript resolution by centralizing definitions in `types.ts` and refactoring the entry point (`index.ts`). Adds type safety and improves DX for TS users.

.gitignore

@@ -1,4 +1,5 @@
 node_modules
 dist
 *.log
+.astro/
 packages/**/env.d.ts

demo/src/components/Card.astro

@@ -1,10 +1,7 @@
 ---
-import type { TOC } from "astro-toc";
+import type { TocItem } from "astro-toc";
 
-export interface Props {
-  title: string;
-  url?: string;
-}
+type Props = TocItem;
 
 const { title, url, depth, ...attrs } = Astro.props;
 ---

demo/src/pages/index.astro

@@ -44,7 +44,7 @@ const toc = [
     </div>
     <hr />
     <h2>Max Depth (maxDepth="1")</h2>
-    <TOC toc={toc} maxDepth="1" />
+    <TOC toc={toc} maxDepth={1} />
     <style is:global>
       * {
         box-sizing: border-box;

packages/astro-toc/lib/TOC.astro

@@ -1,39 +1,19 @@
 ---
-type BaseProps<T> = {
-  toc: (T & {
-    depth: number;
-  })[];
-  as?: "bullet" | "number" | "menu";
-  depth?: number;
-  maxDepth?: number;
-  use: (props: any) => any;
-};
+import type { TocProps } from "./types";
 
-type ClassicProps = BaseProps<{
-  title: string;
-  url?: string;
-}>;
+type Props = TocProps & astroHTML.JSX.HTMLAttributes;
 
-type UseComponentProps = BaseProps<{
-  [key: string]: any;
-}>;
-
-export type Props = ClassicProps | UseComponentProps;
-
-const { toc, depth = 1, ...props } = Astro.props as Props;
-const { as = "bullet", use: Cmp, maxDepth, ...styleProps } = props; /* styleProps; `class` & `data-astro-cid-*` */
+const { toc, depth = 1, ...props } = Astro.props;
+const { as = "bullet", use: Cmp, maxDepth, ...attrs } = props;
 const headings = toc.filter((it) => it.depth === depth);
 const Tag = "bullet" === as ? "ul" : "number" === as ? "ol" : "menu";
 ---
 
-<Tag data-astro-toc={depth} {...depth === 1 ? styleProps : {}}>
+<Tag data-astro-toc={depth} {...depth === 1 ? attrs : {}}>
   {
     headings.map((it, idx) => {
       const nextHeading = headings[idx + 1];
-      const subHeadings = toc.slice(
-        (toc as any).indexOf(it) + 1,
-        nextHeading ? (toc as any).indexOf(nextHeading) : undefined
-      );
+      const subHeadings = toc.slice(toc.indexOf(it) + 1, nextHeading ? toc.indexOf(nextHeading) : undefined);
       const shouldRenderSubHeadings = maxDepth ? maxDepth > it.depth : subHeadings.length > 0;
 
       return (

packages/astro-toc/lib/index.js packages/astro-toc/lib/index.tspackages/astro-toc/lib/index.js renamed to packages/astro-toc/lib/index.ts

@@ -1 +1,2 @@
 export { default as TOC } from "./TOC.astro";
+export type * from "./types.ts";

packages/astro-toc/lib/types.ts

@@ -0,0 +1,49 @@
+/**
+ * Represents a single item in a Table of Contents (TOC).
+ */
+export interface TocItem {
+  /**
+   * Source heading level (1=<h1>, 2=<h2>, ...).
+   */
+  depth: number;
+  /**
+   * The visible text of the heading.
+   */
+  title: string;
+  /**
+   * Optional URL fragment (`#id`) for linking to the heading.
+   */
+  url?: string;
+}
+
+/**
+ * Props for a component rendering a Table of Contents (TOC).
+ *
+ * @typeParam T - The shape of items in the TOC array, extending {@link TocItem}.
+ */
+export type TocProps<T extends TocItem = TocItem> = {
+  /**
+   * List style type: unordered list (`bullet`), ordered list (`number`), or semantic menu.
+   *
+   * Default is `bullet`.
+   */
+  as?: "bullet" | "number" | "menu";
+  /**
+   * Minimum heading depth to include (inclusive).
+   *
+   * Default is `1`.
+   */
+  depth?: number;
+  /**
+   * Maximum heading depth to include (inclusive).
+   */
+  maxDepth?: number;
+  /**
+   *  Array of TOC items to render.
+   */
+  toc: T[];
+  /**
+   * Optional custom render function or component for TOC items.
+   */
+  use?: (item: T) => any;
+};

packages/astro-toc/package.json

@@ -4,7 +4,7 @@
   "version": "0.1.3",
   "type": "module",
   "exports": {
-    ".": "./lib/index.js"
+    ".": "./lib/index.ts"
   },
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"