@zag-js/toc 1.37.0

package/dist/toc.machine.js

@@ -0,0 +1,219 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/toc.machine.ts
+var toc_machine_exports = {};
+__export(toc_machine_exports, {
+  machine: () => machine
+});
+module.exports = __toCommonJS(toc_machine_exports);
+var import_core = require("@zag-js/core");
+var import_dom_query = require("@zag-js/dom-query");
+var import_utils = require("@zag-js/utils");
+var dom = __toESM(require("./toc.dom.js"));
+var { createMachine } = (0, import_core.setup)();
+var machine = createMachine({
+  props({ props }) {
+    return {
+      dir: "ltr",
+      rootMargin: "-20px 0% -40% 0%",
+      threshold: 0,
+      autoScroll: true,
+      scrollBehavior: "smooth",
+      items: [],
+      ...props
+    };
+  },
+  initialState() {
+    return "idle";
+  },
+  context({ prop, bindable }) {
+    return {
+      activeIds: bindable(() => ({
+        defaultValue: prop("defaultActiveIds") ?? [],
+        value: prop("activeIds")
+      })),
+      indicatorRect: bindable(() => ({
+        defaultValue: null
+      }))
+    };
+  },
+  refs() {
+    return {
+      visibilityMap: /* @__PURE__ */ new Map(),
+      indicatorCleanup: null
+    };
+  },
+  computed: {
+    activeItems({ context, prop }) {
+      const ids = context.get("activeIds");
+      return prop("items").filter((item) => ids.includes(item.value));
+    }
+  },
+  watch({ context, track, action }) {
+    track([() => context.get("activeIds").join()], () => {
+      action(["autoScrollToc", "syncIndicatorRect"]);
+    });
+  },
+  entry: ["syncIndicatorRect"],
+  exit: ["cleanupIndicatorObserver"],
+  on: {
+    "ACTIVE_IDS.SET": {
+      actions: ["setActiveIds"]
+    }
+  },
+  states: {
+    idle: {
+      effects: ["trackHeadingVisibility"]
+    }
+  },
+  implementations: {
+    actions: {
+      setActiveIds(params) {
+        const { context, event } = params;
+        context.set("activeIds", event.value);
+        invokeOnActiveChange(params);
+      },
+      autoScrollToc({ context, scope, prop }) {
+        if (!prop("autoScroll")) return;
+        const tocItemEl = dom.getItemEl(scope, (0, import_utils.first)(context.get("activeIds")));
+        tocItemEl?.scrollIntoView({
+          behavior: prop("scrollBehavior"),
+          block: "nearest"
+        });
+      },
+      cleanupIndicatorObserver({ refs }) {
+        refs.get("indicatorCleanup")?.();
+      },
+      syncIndicatorRect({ context, refs, scope }) {
+        refs.get("indicatorCleanup")?.();
+        const indicatorEl = dom.getIndicatorEl(scope);
+        if (!indicatorEl) return;
+        const activeIds = context.get("activeIds");
+        if (activeIds.length === 0) {
+          context.set("indicatorRect", null);
+          return;
+        }
+        const exec = () => {
+          const ids = context.get("activeIds");
+          if (ids.length === 0) {
+            context.set("indicatorRect", null);
+            return;
+          }
+          const firstEl = dom.getItemEl(scope, (0, import_utils.first)(ids));
+          const lastEl = dom.getItemEl(scope, (0, import_utils.last)(ids));
+          if (!firstEl) return;
+          const listEl = dom.getListEl(scope);
+          const listRect = listEl?.getBoundingClientRect();
+          const firstRect = firstEl.getBoundingClientRect();
+          const offsetY = listRect ? firstRect.top - listRect.top + listEl.scrollTop : firstRect.top;
+          const offsetX = listRect ? firstRect.left - listRect.left + listEl.scrollLeft : firstRect.left;
+          let height;
+          if (lastEl && lastEl !== firstEl) {
+            const lastRect = lastEl.getBoundingClientRect();
+            height = lastRect.top + lastRect.height - firstRect.top;
+          } else {
+            height = firstRect.height;
+          }
+          const nextRect = {
+            x: offsetX,
+            y: offsetY,
+            width: firstRect.width,
+            height
+          };
+          context.set("indicatorRect", (prev) => (0, import_utils.isEqual)(prev, nextRect) ? prev : nextRect);
+        };
+        exec();
+        const cleanups = [];
+        for (const id of activeIds) {
+          const el = dom.getItemEl(scope, id);
+          if (el) {
+            cleanups.push(import_dom_query.resizeObserverBorderBox.observe(el, exec));
+          }
+        }
+        refs.set("indicatorCleanup", () => (0, import_utils.callAll)(...cleanups));
+      }
+    },
+    effects: {
+      trackHeadingVisibility(params) {
+        const { scope, prop, context, refs } = params;
+        const items = prop("items");
+        if (items.length === 0) return;
+        const visibilityMap = refs.get("visibilityMap");
+        const observerOptions = {
+          rootMargin: prop("rootMargin"),
+          threshold: prop("threshold")
+        };
+        const scrollEl = prop("getScrollEl")?.();
+        if (scrollEl) {
+          observerOptions.root = scrollEl;
+        }
+        const win = scope.getWin();
+        const observer = new win.IntersectionObserver((entries) => {
+          for (const entry of entries) {
+            visibilityMap.set(entry.target.id, entry.isIntersecting);
+          }
+          const nextActiveIds = [];
+          for (const item of items) {
+            if (visibilityMap.get(item.value)) {
+              nextActiveIds.push(item.value);
+            }
+          }
+          if (nextActiveIds.length === 0) return;
+          const currentActiveIds = context.get("activeIds");
+          if (!(0, import_utils.isEqual)(currentActiveIds, nextActiveIds)) {
+            context.set("activeIds", nextActiveIds);
+            invokeOnActiveChange(params);
+          }
+        }, observerOptions);
+        for (const item of items) {
+          const headingEl = dom.getHeadingEl(scope, item.value);
+          if (headingEl) {
+            observer.observe(headingEl);
+          }
+        }
+        return () => {
+          observer.disconnect();
+          visibilityMap.clear();
+        };
+      }
+    }
+  }
+});
+function invokeOnActiveChange(params) {
+  const { context, computed, prop } = params;
+  prop("onActiveChange")?.({
+    activeIds: context.get("activeIds"),
+    activeItems: computed("activeItems")
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  machine
+});

package/dist/toc.machine.mjs

@@ -0,0 +1,184 @@
+// src/toc.machine.ts
+import { setup } from "@zag-js/core";
+import { resizeObserverBorderBox } from "@zag-js/dom-query";
+import { callAll, first, isEqual, last } from "@zag-js/utils";
+import * as dom from "./toc.dom.mjs";
+var { createMachine } = setup();
+var machine = createMachine({
+  props({ props }) {
+    return {
+      dir: "ltr",
+      rootMargin: "-20px 0% -40% 0%",
+      threshold: 0,
+      autoScroll: true,
+      scrollBehavior: "smooth",
+      items: [],
+      ...props
+    };
+  },
+  initialState() {
+    return "idle";
+  },
+  context({ prop, bindable }) {
+    return {
+      activeIds: bindable(() => ({
+        defaultValue: prop("defaultActiveIds") ?? [],
+        value: prop("activeIds")
+      })),
+      indicatorRect: bindable(() => ({
+        defaultValue: null
+      }))
+    };
+  },
+  refs() {
+    return {
+      visibilityMap: /* @__PURE__ */ new Map(),
+      indicatorCleanup: null
+    };
+  },
+  computed: {
+    activeItems({ context, prop }) {
+      const ids = context.get("activeIds");
+      return prop("items").filter((item) => ids.includes(item.value));
+    }
+  },
+  watch({ context, track, action }) {
+    track([() => context.get("activeIds").join()], () => {
+      action(["autoScrollToc", "syncIndicatorRect"]);
+    });
+  },
+  entry: ["syncIndicatorRect"],
+  exit: ["cleanupIndicatorObserver"],
+  on: {
+    "ACTIVE_IDS.SET": {
+      actions: ["setActiveIds"]
+    }
+  },
+  states: {
+    idle: {
+      effects: ["trackHeadingVisibility"]
+    }
+  },
+  implementations: {
+    actions: {
+      setActiveIds(params) {
+        const { context, event } = params;
+        context.set("activeIds", event.value);
+        invokeOnActiveChange(params);
+      },
+      autoScrollToc({ context, scope, prop }) {
+        if (!prop("autoScroll")) return;
+        const tocItemEl = dom.getItemEl(scope, first(context.get("activeIds")));
+        tocItemEl?.scrollIntoView({
+          behavior: prop("scrollBehavior"),
+          block: "nearest"
+        });
+      },
+      cleanupIndicatorObserver({ refs }) {
+        refs.get("indicatorCleanup")?.();
+      },
+      syncIndicatorRect({ context, refs, scope }) {
+        refs.get("indicatorCleanup")?.();
+        const indicatorEl = dom.getIndicatorEl(scope);
+        if (!indicatorEl) return;
+        const activeIds = context.get("activeIds");
+        if (activeIds.length === 0) {
+          context.set("indicatorRect", null);
+          return;
+        }
+        const exec = () => {
+          const ids = context.get("activeIds");
+          if (ids.length === 0) {
+            context.set("indicatorRect", null);
+            return;
+          }
+          const firstEl = dom.getItemEl(scope, first(ids));
+          const lastEl = dom.getItemEl(scope, last(ids));
+          if (!firstEl) return;
+          const listEl = dom.getListEl(scope);
+          const listRect = listEl?.getBoundingClientRect();
+          const firstRect = firstEl.getBoundingClientRect();
+          const offsetY = listRect ? firstRect.top - listRect.top + listEl.scrollTop : firstRect.top;
+          const offsetX = listRect ? firstRect.left - listRect.left + listEl.scrollLeft : firstRect.left;
+          let height;
+          if (lastEl && lastEl !== firstEl) {
+            const lastRect = lastEl.getBoundingClientRect();
+            height = lastRect.top + lastRect.height - firstRect.top;
+          } else {
+            height = firstRect.height;
+          }
+          const nextRect = {
+            x: offsetX,
+            y: offsetY,
+            width: firstRect.width,
+            height
+          };
+          context.set("indicatorRect", (prev) => isEqual(prev, nextRect) ? prev : nextRect);
+        };
+        exec();
+        const cleanups = [];
+        for (const id of activeIds) {
+          const el = dom.getItemEl(scope, id);
+          if (el) {
+            cleanups.push(resizeObserverBorderBox.observe(el, exec));
+          }
+        }
+        refs.set("indicatorCleanup", () => callAll(...cleanups));
+      }
+    },
+    effects: {
+      trackHeadingVisibility(params) {
+        const { scope, prop, context, refs } = params;
+        const items = prop("items");
+        if (items.length === 0) return;
+        const visibilityMap = refs.get("visibilityMap");
+        const observerOptions = {
+          rootMargin: prop("rootMargin"),
+          threshold: prop("threshold")
+        };
+        const scrollEl = prop("getScrollEl")?.();
+        if (scrollEl) {
+          observerOptions.root = scrollEl;
+        }
+        const win = scope.getWin();
+        const observer = new win.IntersectionObserver((entries) => {
+          for (const entry of entries) {
+            visibilityMap.set(entry.target.id, entry.isIntersecting);
+          }
+          const nextActiveIds = [];
+          for (const item of items) {
+            if (visibilityMap.get(item.value)) {
+              nextActiveIds.push(item.value);
+            }
+          }
+          if (nextActiveIds.length === 0) return;
+          const currentActiveIds = context.get("activeIds");
+          if (!isEqual(currentActiveIds, nextActiveIds)) {
+            context.set("activeIds", nextActiveIds);
+            invokeOnActiveChange(params);
+          }
+        }, observerOptions);
+        for (const item of items) {
+          const headingEl = dom.getHeadingEl(scope, item.value);
+          if (headingEl) {
+            observer.observe(headingEl);
+          }
+        }
+        return () => {
+          observer.disconnect();
+          visibilityMap.clear();
+        };
+      }
+    }
+  }
+});
+function invokeOnActiveChange(params) {
+  const { context, computed, prop } = params;
+  prop("onActiveChange")?.({
+    activeIds: context.get("activeIds"),
+    activeItems: computed("activeItems")
+  });
+}
+export {
+  machine
+};

package/dist/toc.props.d.mts

@@ -0,0 +1,10 @@
+import { TocProps, ItemProps } from './toc.types.mjs';
+import '@zag-js/core';
+import '@zag-js/types';
+
+declare const props: (keyof TocProps)[];
+declare const splitProps: <Props extends Partial<TocProps>>(props: Props) => [Partial<TocProps>, Omit<Props, keyof TocProps>];
+declare const itemProps: "item"[];
+declare const splitItemProps: <Props extends ItemProps>(props: Props) => [ItemProps, Omit<Props, "item">];
+
+export { itemProps, props, splitItemProps, splitProps };

package/dist/toc.props.d.ts

@@ -0,0 +1,10 @@
+import { TocProps, ItemProps } from './toc.types.js';
+import '@zag-js/core';
+import '@zag-js/types';
+
+declare const props: (keyof TocProps)[];
+declare const splitProps: <Props extends Partial<TocProps>>(props: Props) => [Partial<TocProps>, Omit<Props, keyof TocProps>];
+declare const itemProps: "item"[];
+declare const splitItemProps: <Props extends ItemProps>(props: Props) => [ItemProps, Omit<Props, "item">];
+
+export { itemProps, props, splitItemProps, splitProps };

package/dist/toc.props.js

@@ -0,0 +1,55 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+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.props.ts
+var toc_props_exports = {};
+__export(toc_props_exports, {
+  itemProps: () => itemProps,
+  props: () => props,
+  splitItemProps: () => splitItemProps,
+  splitProps: () => splitProps
+});
+module.exports = __toCommonJS(toc_props_exports);
+var import_types = require("@zag-js/types");
+var import_utils = require("@zag-js/utils");
+var props = (0, import_types.createProps)()([
+  "activeIds",
+  "autoScroll",
+  "defaultActiveIds",
+  "dir",
+  "getRootNode",
+  "id",
+  "ids",
+  "items",
+  "onActiveChange",
+  "rootMargin",
+  "scrollBehavior",
+  "getScrollEl",
+  "threshold"
+]);
+var splitProps = (0, import_utils.createSplitProps)(props);
+var itemProps = (0, import_types.createProps)()(["item"]);
+var splitItemProps = (0, import_utils.createSplitProps)(itemProps);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  itemProps,
+  props,
+  splitItemProps,
+  splitProps
+});

package/dist/toc.props.mjs

@@ -0,0 +1,27 @@
+// src/toc.props.ts
+import { createProps } from "@zag-js/types";
+import { createSplitProps } from "@zag-js/utils";
+var props = createProps()([
+  "activeIds",
+  "autoScroll",
+  "defaultActiveIds",
+  "dir",
+  "getRootNode",
+  "id",
+  "ids",
+  "items",
+  "onActiveChange",
+  "rootMargin",
+  "scrollBehavior",
+  "getScrollEl",
+  "threshold"
+]);
+var splitProps = createSplitProps(props);
+var itemProps = createProps()(["item"]);
+var splitItemProps = createSplitProps(itemProps);
+export {
+  itemProps,
+  props,
+  splitItemProps,
+  splitProps
+};

package/dist/toc.types.d.mts

@@ -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 };