@zag-js/toc 1.37.0

package/dist/toc.types.d.ts

@@ -0,0 +1,159 @@
+import { Machine, EventObject, Service } from '@zag-js/core';
+import { PropTypes, RequiredBy, DirectionProperty, CommonProperties, Rect } from '@zag-js/types';
+
+interface TocItem {
+    /**
+     * The slug/id of the heading element in the document
+     */
+    value: string;
+    /**
+     * The nesting depth (e.g., 2 for h2, 3 for h3)
+     */
+    depth: number;
+}
+interface ActiveChangeDetails {
+    /**
+     * All currently active (visible) heading ids
+     */
+    activeIds: string[];
+    /**
+     * The active (visible) TOC items
+     */
+    activeItems: TocItem[];
+}
+type ElementIds = Partial<{
+    root: string;
+    title: string;
+    list: string;
+    item: (value: string) => string;
+    link: (value: string) => string;
+    indicator: string;
+}>;
+interface TocProps extends DirectionProperty, CommonProperties {
+    /**
+     * The ids of the elements in the TOC. Useful for composition.
+     */
+    ids?: ElementIds | undefined;
+    /**
+     * The TOC items with `value` (slug/id) and `depth` (heading level).
+     */
+    items: TocItem[];
+    /**
+     * The root margin for the IntersectionObserver.
+     * Controls the effective viewport area for determining active headings.
+     *
+     * @default "-20px 0px -40% 0px"
+     */
+    rootMargin?: string | undefined;
+    /**
+     * The IntersectionObserver threshold. A value of `0` means the heading is
+     * active as soon as even one pixel is visible within the root margin area.
+     * @default 0
+     */
+    threshold?: number | number[] | undefined;
+    /**
+     * Function that returns the scroll container element to observe within.
+     * Defaults to the document/viewport.
+     */
+    getScrollEl?: (() => HTMLElement | null) | undefined;
+    /**
+     * Whether to auto-scroll the TOC container so the first active item
+     * is visible when active headings change.
+     * @default true
+     */
+    autoScroll?: boolean | undefined;
+    /**
+     * The scroll behavior for auto-scrolling the TOC container.
+     * @default "smooth"
+     */
+    scrollBehavior?: ScrollBehavior | undefined;
+    /**
+     * Callback when the active (visible) headings change.
+     */
+    onActiveChange?: ((details: ActiveChangeDetails) => void) | undefined;
+    /**
+     * The controlled active heading ids.
+     */
+    activeIds?: string[] | undefined;
+    /**
+     * The default active heading ids when rendered.
+     * Use when you don't need to control the active headings.
+     */
+    defaultActiveIds?: string[] | undefined;
+}
+type PropsWithDefault = "rootMargin" | "threshold" | "autoScroll" | "scrollBehavior" | "items";
+interface TocSchema {
+    state: "idle";
+    props: RequiredBy<TocProps, PropsWithDefault>;
+    context: {
+        activeIds: string[];
+        indicatorRect: Rect | null;
+    };
+    refs: {
+        visibilityMap: Map<string, boolean>;
+        indicatorCleanup: VoidFunction | null;
+    };
+    computed: {
+        activeItems: TocItem[];
+    };
+    action: string;
+    guard: string;
+    effect: string;
+    event: EventObject;
+}
+type TocService = Service<TocSchema>;
+type TocMachine = Machine<TocSchema>;
+interface ItemProps {
+    /**
+     * The TOC item
+     */
+    item: TocItem;
+}
+interface ItemState {
+    /**
+     * Whether this heading is currently visible/active
+     */
+    active: boolean;
+    /**
+     * Whether this is the first active heading
+     */
+    first: boolean;
+    /**
+     * Whether this is the last active heading
+     */
+    last: boolean;
+    /**
+     * The depth of this heading (for indentation)
+     */
+    depth: number;
+}
+interface TocApi<T extends PropTypes = PropTypes> {
+    /**
+     * All currently active (visible) heading ids
+     */
+    activeIds: string[];
+    /**
+     * The active (visible) TOC items
+     */
+    activeItems: TocItem[];
+    /**
+     * The resolved items list
+     */
+    items: TocItem[];
+    /**
+     * Manually set the active heading ids
+     */
+    setActiveIds(value: string[]): void;
+    /**
+     * Returns the state of a TOC item
+     */
+    getItemState(props: ItemProps): ItemState;
+    getRootProps(): T["element"];
+    getTitleProps(): T["element"];
+    getListProps(): T["element"];
+    getItemProps(props: ItemProps): T["element"];
+    getLinkProps(props: ItemProps): T["element"];
+    getIndicatorProps(): T["element"];
+}
+
+export type { ActiveChangeDetails, ElementIds, ItemProps, ItemState, TocApi, TocItem, TocMachine, TocProps, TocSchema, TocService };

package/dist/toc.types.js

@@ -0,0 +1,18 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/toc.types.ts
+var toc_types_exports = {};
+module.exports = __toCommonJS(toc_types_exports);

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@zag-js/toc",
+  "version": "1.37.0",
+  "description": "Core logic for the table of contents widget implemented as a state machine",
+  "keywords": [
+    "js",
+    "machine",
+    "xstate",
+    "statechart",
+    "component",
+    "chakra-ui",
+    "toc",
+    "table-of-contents",
+    "scroll-spy"
+  ],
+  "author": "Segun Adebayo <sage@adebayosegun.com>",
+  "homepage": "https://github.com/chakra-ui/zag#readme",
+  "license": "MIT",
+  "repository": "https://github.com/chakra-ui/zag/tree/main/packages/toc",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bugs": {
+    "url": "https://github.com/chakra-ui/zag/issues"
+  },
+  "dependencies": {
+    "@zag-js/anatomy": "1.37.0",
+    "@zag-js/dom-query": "1.37.0",
+    "@zag-js/utils": "1.37.0",
+    "@zag-js/core": "1.37.0",
+    "@zag-js/types": "1.37.0"
+  },
+  "devDependencies": {
+    "clean-package": "2.2.0"
+  },
+  "clean-package": "./clean-package.config.json",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./anatomy": {
+      "import": {
+        "types": "./dist/toc.anatomy.d.mts",
+        "default": "./dist/toc.anatomy.mjs"
+      },
+      "require": {
+        "types": "./dist/toc.anatomy.d.ts",
+        "default": "./dist/toc.anatomy.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsup",
+    "lint": "eslint src",
+    "typecheck": "tsc --noEmit"
+  }
+}