@fairgarden/design 0.1.0-alpha.1 → 0.1.0-alpha.2

package/navigation/table-of-contents/TableOfContents.js

@@ -0,0 +1,211 @@
+'use client';
+import * as React from 'react';
+import { Popover as BasePopover } from '@base-ui/react/popover';
+import { cva } from 'class-variance-authority';
+import { Link } from '../../actions/link';
+import { Icon, iconHost } from '../../foundations/icon';
+import { OutlineMorphFrame, useOutlineMorph } from '../../foundations/outline-morph';
+import { cx } from '../../utils/className';
+import { OVERLAY_COLLISION_PADDING, OVERLAY_SIDE_OFFSET, OverlayScope, overlayAttributes, overlayScaleClassName, } from '../../utils/overlay';
+import { primaryScaleVariants, secondaryScaleVariants } from '../../utils/scales';
+import { useScopeAttributes } from '../../utils/scope';
+import styles from './table-of-contents.module.css';
+/*
+ * Table of Contents (§9.16) [D202, D203]: the page's "On this page" list,
+ * the docs layout's right column; and, as `kind="bar"`, the compact bar
+ * the layout pins at the top of the page below that column's threshold.
+ *
+ * Implementation (CSS Modules + CVA)
+ * - Module: table-of-contents.module.css; CVA function `tableOfContents`.
+ * - Axes: `kind` → list | bar → kindList, kindBar (the root: the nav, or
+ *   the bar's box); `primary`, `secondary` → scales module classes.
+ * - Compound variants: none. Defaults: kind list; color axes none.
+ * - Color fallback: inherits the scope; the bar's panel is a portaled
+ *   `white` overlay scope (§10.1).
+ * - States: entries are Link `kind="nav"` with `list`: `:hover` →
+ *   --role-link-hover only (plus the underline where it is --primary12)
+ *   [D181]; `aria-current="location"` (the section in view, `activeId`) →
+ *   the --border-size-2-25 start-edge bar over the guide and weight 700,
+ *   whose box every entry reserves, so scrollspy never rewraps a line;
+ *   `:focus-visible` → the ring, inset inside the row. Bar trigger:
+ *   `:hover` → the field edge steps to --primary12 [D140];
+ *   `data-popup-open` → the edge --primary12 and the chevron turned;
+ *   `:focus-visible` → the ring. The panel opens and closes by the outline
+ *   morph or at once [D205]; `data-outline-morph` → its edge takes its face
+ *   while the morph draws the frame [D204].
+ * - Parts: base (the nav, or the bar's box), heading, list, item, link,
+ *   label, labelText; the bar's trigger, barLabel, barTitle, barChevron,
+ *   positioner, panel, panelScroll, visuallyHidden.
+ * - Scope: none; the panel declares the overlay's `white` scope.
+ * - Container: none; its host sets its width (the docs layout's column, or
+ *   the page column for the bar).
+ * - Data: `items` is plain data ({ id, title, level }), the page's
+ *   headings, so it can come from the docs engine (utils/docs, planned) or
+ *   from the rendered page.
+ * - Outline morph [D204]: with `kind="bar"`, on by default (`morph={false}`
+ *   opts out; `--fgd-outline-morph: none` for a subtree): the bar's ring
+ *   or edge grows into the panel's frame and back
+ *   (foundations/outline-morph), as the Select and the Section Bar's Jump
+ *   to do.
+ */
+export const tableOfContents = cva(styles.base, {
+    variants: {
+        kind: {
+            list: styles.kindList,
+            bar: styles.kindBar,
+        },
+        // Color axes: never defaulted, so an omitted prop inherits the scope [D133].
+        primary: primaryScaleVariants,
+        secondary: secondaryScaleVariants,
+    },
+    defaultVariants: {
+        kind: 'list',
+    },
+});
+/** Provided by a host of the contents, such as the docs layout. */
+export const TableOfContentsContext = React.createContext({});
+TableOfContentsContext.displayName = 'TableOfContentsContext';
+/** Nests the flat heading list: each entry under the nearest shallower one before it. */
+function toTree(items) {
+    const roots = [];
+    const stack = [];
+    for (const item of items) {
+        const node = { item, children: [] };
+        while (stack.length > 0 && stack[stack.length - 1].item.level >= item.level)
+            stack.pop();
+        const parent = stack[stack.length - 1];
+        if (parent)
+            parent.children.push(node);
+        else
+            roots.push(node);
+        stack.push(node);
+    }
+    return roots;
+}
+/** The heading a followed entry lands on, made focusable (as the Section Bar's Jump list does). */
+function headingFor(id) {
+    if (typeof document === 'undefined')
+        return null;
+    const target = document.getElementById(id);
+    if (target == null)
+        return null;
+    if (!target.hasAttribute('tabindex') && !target.matches('a[href], button, input, select, textarea')) {
+        target.setAttribute('tabindex', '-1');
+    }
+    return target;
+}
+/** The list: a `nav` named by its heading (or `aria-label`), over the nested `ol` of entries. */
+function ContentsList(props) {
+    const { items, activeId, label, labelHidden, renderLink, onFollow, className, rootProps } = props;
+    const headingId = React.useId();
+    const tree = React.useMemo(() => toTree(items), [items]);
+    const renderNodes = (nodes) => (React.createElement("ol", { className: styles.list }, nodes.map(({ item, children }) => {
+        const href = `#${item.id}`;
+        return (React.createElement("li", { key: item.id, className: styles.item },
+            React.createElement(Link, { kind: "nav", list: true, href: href, render: renderLink?.(href), "aria-current": item.id === activeId ? 'location' : undefined, onClick: onFollow ? () => onFollow(item.id) : undefined, className: styles.link },
+                React.createElement("span", { className: styles.label, "data-label": item.title },
+                    React.createElement("span", { className: styles.labelText }, item.title))),
+            children.length > 0 ? renderNodes(children) : null));
+    })));
+    return (React.createElement("nav", { ...rootProps, ...(labelHidden ? { 'aria-label': label } : { 'aria-labelledby': headingId }), className: className },
+        labelHidden ? null : (React.createElement("p", { id: headingId, className: styles.heading }, label)),
+        renderNodes(tree)));
+}
+/**
+ * The page's contents [D202, D203].
+ *
+ * `kind="list"` (default): a `nav` named by its caps heading (`type-label`)
+ * over an `ol` of in-page links in `type-caption`, H2s at the top level and
+ * H3 and H4 nested on the --role-hairline guide. The section in view
+ * (`activeId`) takes `aria-current="location"`, the --border-size-2-25
+ * start-edge bar and weight 700; every entry reserves that weight's box, so
+ * marking a section never moves the list.
+ *
+ * `kind="bar"`: one field-box line, "On this page" and the section in view
+ * (the first before scrollspy runs), truncated, with a chevron. It opens
+ * the same list in an anchored panel about a third of the viewport tall,
+ * scrolled inside so the section in view sits centered and marked, with
+ * focus on it; following an entry goes to its heading and closes the
+ * panel; Escape and an outside press close it and focus returns to the
+ * bar. The bar's ring or edge morphs into the panel's frame [D204].
+ *
+ * Presentational: pair it with `useActiveHeading` for scrollspy. The docs
+ * layout shows the list in a sticky column from --xl-n-above and the bar,
+ * pinned under the header, below. With no items it renders nothing. Hidden
+ * in print.
+ */
+export function TableOfContents(props) {
+    const { items, activeId, label = 'On this page', kind: kindProp, morph = true, renderLink, primary, secondary, className, ref, ...rest } = props;
+    const scope = useScopeAttributes();
+    const context = React.useContext(TableOfContentsContext);
+    const kind = kindProp ?? context.kind ?? 'list';
+    if (items.length === 0)
+        return null;
+    if (kind === 'bar') {
+        return (React.createElement(ContentsBar, { items: items, activeId: activeId, label: label, morph: morph, renderLink: renderLink, className: tableOfContents({ kind, primary, secondary, className }), scope: scope, rootRef: ref, rootProps: rest }));
+    }
+    return (React.createElement(ContentsList, { items: items, activeId: activeId, label: label, labelHidden: context.labelHidden ?? false, renderLink: renderLink, className: tableOfContents({ kind, primary, secondary, className }), rootProps: { ...rest, ...scope, ref } }));
+}
+/** `kind="bar"`: the one-line trigger and its anchored panel. */
+function ContentsBar(props) {
+    const { items, activeId, label, morph, renderLink, className, scope, rootRef, rootProps } = props;
+    const [open, setOpen] = React.useState(false);
+    const refs = useOutlineMorph({ open, enabled: morph });
+    const panelId = React.useId();
+    const scrollRef = React.useRef(null);
+    const pendingFocus = React.useRef(null);
+    // Before scrollspy runs (and on the server), the first section.
+    const current = items.find((item) => item.id === activeId) ?? items[0];
+    const follow = React.useCallback((id) => {
+        pendingFocus.current = headingFor(id);
+        setOpen(false);
+    }, []);
+    return (React.createElement("div", { ...rootProps, ...scope, ref: rootRef, className: className },
+        React.createElement(BasePopover.Root, { open: open, onOpenChange: (next) => setOpen(next) },
+            React.createElement(BasePopover.Trigger, { ref: morph ? refs.sourceRef : undefined, "aria-controls": open ? panelId : undefined, className: cx(styles.trigger, iconHost) },
+                React.createElement("span", { className: styles.barLabel }, label),
+                React.createElement("span", { className: styles.visuallyHidden }, ": "),
+                React.createElement("span", { className: styles.barTitle }, current.title),
+                React.createElement(Icon, { name: "expand_more", weight: "interactive", className: styles.barChevron })),
+            React.createElement(BasePopover.Portal, null,
+                React.createElement(BasePopover.Positioner, { className: styles.positioner, side: "bottom", align: "start", sideOffset: OVERLAY_SIDE_OFFSET, collisionPadding: OVERLAY_COLLISION_PADDING },
+                    React.createElement(BasePopover.Popup, { ref: morph ? refs.targetRef : undefined, id: panelId, ...overlayAttributes, "aria-label": label, className: cx(styles.panel, overlayScaleClassName), initialFocus: () => {
+                            const scroller = scrollRef.current;
+                            return (scroller?.querySelector('a[aria-current="location"]') ??
+                                scroller?.querySelector('a[href]') ??
+                                true);
+                        }, finalFocus: () => {
+                            const element = pendingFocus.current;
+                            pendingFocus.current = null;
+                            return element ?? true;
+                        } },
+                        React.createElement(OverlayScope, null,
+                            React.createElement(PanelScroll, { scrollRef: scrollRef },
+                                React.createElement(ContentsList, { items: items, activeId: current.id, label: label, labelHidden: true, renderLink: renderLink, onFollow: follow, className: cx(styles.base, styles.kindList) })))),
+                    morph ? React.createElement(OutlineMorphFrame, { ref: refs.frameRef }) : null))),
+        React.createElement("span", { className: styles.visuallyHidden, "aria-live": "polite", "aria-atomic": "true" }, current.title)));
+}
+/**
+ * The panel's scroller. On mount it scrolls itself, never the page, so the
+ * section in view sits centered; the panel's height is final before it
+ * paints (its fallback cap), and a second pass a frame later follows the
+ * positioner's measured room.
+ */
+function PanelScroll({ scrollRef, children, }) {
+    React.useLayoutEffect(() => {
+        const center = () => {
+            const scroller = scrollRef.current;
+            const link = scroller?.querySelector('a[aria-current="location"]');
+            if (scroller == null || link == null)
+                return;
+            const box = scroller.getBoundingClientRect();
+            const target = link.getBoundingClientRect();
+            scroller.scrollTop += target.top - box.top - (box.height - target.height) / 2;
+        };
+        center();
+        const frame = window.requestAnimationFrame(center);
+        return () => window.cancelAnimationFrame(frame);
+    }, [scrollRef]);
+    return (React.createElement("div", { ref: scrollRef, className: styles.panelScroll }, children));
+}
+//# sourceMappingURL=TableOfContents.js.map

package/navigation/table-of-contents/TableOfContents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TableOfContents.js","sourceRoot":"","sources":["../../src/navigation/table-of-contents/TableOfContents.tsx"],"names":[],"mappings":"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"}

package/navigation/table-of-contents/index.d.ts

@@ -0,0 +1,3 @@
+export * from './TableOfContents';
+export * from './useActiveHeading';
+//# sourceMappingURL=index.d.ts.map

package/navigation/table-of-contents/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/navigation/table-of-contents/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA"}

package/navigation/table-of-contents/index.js

@@ -0,0 +1,3 @@
+export * from './TableOfContents';
+export * from './useActiveHeading';
+//# sourceMappingURL=index.js.map

package/navigation/table-of-contents/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/navigation/table-of-contents/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA"}

package/navigation/table-of-contents/table-of-contents.module.css

@@ -0,0 +1,322 @@
+/*
+ * Table of Contents (§9.16). CVA function `tableOfContents` in
+ * TableOfContents.tsx.
+ *
+ * Parts: base (the nav, or the bar's box; `kindList`, `kindBar`), heading,
+ * list, item, link, label, labelText; the bar's trigger, barLabel,
+ * barTitle, barChevron, positioner, panel (the Popover Popup),
+ * panelScroll, visuallyHidden.
+ *
+ * Line-based [D202]: the entries hang on a --border-size-1 --role-hairline
+ * guide at the list's start edge, H3 and H4 one step in on their own
+ * guide; the section in view draws the --border-size-2-25 --primary12 bar
+ * over it, the current-item grammar of the drawer, tab strip and Jump list.
+ * No fills, no shadows. Colors are role variables only; there are no local
+ * custom properties.
+ *
+ * The bar (`kind="bar"`) [D203]: one §10.1 field-box line, fixed at
+ * --fgd-size-control-md with a --fgd-size-hit target, whose words never
+ * change its size (the title truncates). Its panel is the anchored overlay
+ * surface (§10.1): a portaled `white` scope, --primary1 face, --border-size-2
+ * --primary12 frame at --radius-2-25, a third of the viewport tall (at
+ * least --size-px-13, at most the room below the bar), scrolling natively
+ * inside a --size-px-1 inset, which keeps the scrollbar clear of the
+ * rounded corners (≥ 0.293 × the 6 px inner radius). With the outline
+ * morph (the default) the panel answers `data-outline-morph` [D204].
+ */
+
+/* Composition sits in top-level rules, outside the layers: Lightning CSS
+ * (Next.js with Turbopack) rejects `composes` inside @layer or any nesting.
+ * The composed classes keep their own layers. */
+.heading {
+  composes: typeLabel from '../../utils/type.module.css';
+}
+
+.link {
+  composes: typeCaption from '../../utils/type.module.css';
+}
+
+.barLabel {
+  composes: typeLabel typeMuted from '../../utils/type.module.css';
+}
+
+.barTitle {
+  composes: typeBodyUi from '../../utils/type.module.css';
+}
+
+@layer base {
+  .base {
+    display: block;
+    min-inline-size: 0;
+  }
+
+  /* The list (`kind="list"`, the default): a block in its column. */
+  .kindList {
+    display: block;
+  }
+
+  /* The caps heading on a 44 px row, level with the sidebar's first group heading. */
+  .heading {
+    display: flex;
+    align-items: center;
+    min-block-size: var(--fgd-size-hit);
+    margin: 0;
+    color: var(--primary12);
+  }
+
+  .list {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+    border-inline-start: var(--border-size-1) solid var(--role-hairline);
+  }
+
+  /* H3 and H4: one step in, on their own guide. */
+  .list .list {
+    margin-inline-start: var(--size-px-3);
+  }
+
+  .item {
+    display: block;
+  }
+
+  /* An entry: type-caption at weight 400 on a 44 px row, --size-px-3 off the guide. */
+  .link {
+    position: relative;
+    display: flex;
+    align-items: center;
+    box-sizing: border-box;
+    min-block-size: var(--fgd-size-hit);
+    padding-block: var(--size-px-2);
+    padding-inline: var(--size-px-3) 0;
+    color: var(--primary12);
+    text-decoration-line: none;
+  }
+
+  /* The current bar, over the guide: a border, so it survives forced colors. */
+  .link::before {
+    content: '';
+    position: absolute;
+    inset-block: 0;
+    inset-inline-start: calc(-1 * var(--border-size-1));
+    border-inline-start: 0 solid var(--primary12);
+    pointer-events: none;
+  }
+
+  /*
+   * The label reserves its weight-700 box: a hidden copy of its words at
+   * --font-weight-7 (`data-label`) shares the one grid cell, so scrollspy
+   * never widens or rewraps an entry (no layout shift while scrolling).
+   */
+  .label {
+    display: grid;
+    min-inline-size: 0;
+  }
+
+  .label::after {
+    content: attr(data-label);
+    grid-area: 1 / 1;
+    font-weight: var(--font-weight-7);
+    visibility: hidden;
+    pointer-events: none;
+    user-select: none;
+  }
+
+  .labelText {
+    grid-area: 1 / 1;
+  }
+
+  /* ── The bar (`kind="bar"`) ───────────────────────────────────────── */
+
+  .kindBar {
+    inline-size: 100%;
+  }
+
+  /*
+   * The trigger: the §10.1 field box, one line, --fgd-size-control-md tall
+   * with a --fgd-size-hit target; the label, a hairline, the section in view
+   * (truncated) and the chevron. Its size never depends on its words.
+   */
+  .trigger {
+    position: relative;
+    display: flex;
+    align-items: center;
+    gap: var(--size-px-2);
+    box-sizing: border-box;
+    inline-size: 100%;
+    min-inline-size: 0;
+    block-size: var(--fgd-size-control-md);
+    margin: 0;
+    padding-block: 0;
+    padding-inline: var(--size-px-2-5) var(--size-px-2);
+    border: var(--border-size-1) solid var(--role-rule);
+    border-radius: var(--radius-1);
+    background: none;
+    color: var(--primary12);
+    text-align: start;
+    cursor: pointer;
+    appearance: none;
+  }
+
+  .trigger::after {
+    content: '';
+    position: absolute;
+    inset-inline: 0;
+    inset-block: calc((var(--fgd-size-control-md) - var(--fgd-size-hit)) / 2);
+  }
+
+  .barLabel {
+    flex: none;
+    padding-inline-end: var(--size-px-2);
+    border-inline-end: var(--border-size-1) solid var(--role-hairline);
+    white-space: nowrap;
+  }
+
+  .barTitle {
+    flex: 1 1 auto;
+    min-inline-size: 0;
+    overflow: hidden;
+    font-weight: var(--font-weight-6);
+    white-space: nowrap;
+    text-overflow: ellipsis;
+  }
+
+  /* The chevron: expand_more, inline tier; it turns while open, as the Select's [D166]. */
+  .barChevron {
+    flex: none;
+  }
+
+  .visuallyHidden {
+    position: absolute;
+    inline-size: var(--border-size-1);
+    block-size: var(--border-size-1);
+    margin: calc(-1 * var(--border-size-1));
+    padding: 0;
+    border: 0;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+  }
+
+  /* Below 360 px the label drops from view to leave the title room; it stays in the name [D73]. */
+  @media (max-width: 359.98px) {
+    .barLabel {
+      position: absolute;
+      inline-size: var(--border-size-1);
+      block-size: var(--border-size-1);
+      margin: calc(-1 * var(--border-size-1));
+      padding: 0;
+      border: 0;
+      overflow: hidden;
+      clip-path: inset(50%);
+    }
+  }
+
+  /* The panel sits --fgd-popup-offset below the bar on --layer-3. */
+  .positioner {
+    z-index: var(--layer-3);
+    outline: 0;
+  }
+
+  /*
+   * The overlay face (§10.1): the bar's width, a third of the viewport tall
+   * with a --size-px-13 floor and the room below the bar as its ceiling
+   * (the fallback holds before the positioner measures, so the panel's
+   * height is final when it first paints and its list can be centered).
+   */
+  .panel {
+    display: flex;
+    flex-direction: column;
+    box-sizing: border-box;
+    inline-size: min(var(--anchor-width, 100%), 100vw - 2 * var(--fgd-space-margin));
+    max-block-size: min(max(33svh, var(--size-px-13)), var(--available-height, 100dvh));
+    padding: var(--size-px-1);
+    border: var(--border-size-2) solid var(--primary12);
+    border-radius: var(--radius-2-25);
+    background-color: var(--primary1);
+    color: var(--primary12);
+    clip-path: inset(0);
+    outline: 0;
+  }
+
+  /* The native scrollbar, inset --size-px-1 from the frame's inner edge on every side. */
+  .panelScroll {
+    flex: 1 1 auto;
+    min-block-size: 0;
+    padding-block: var(--size-px-1);
+    padding-inline: var(--size-px-2);
+    overflow-y: auto;
+    overscroll-behavior: contain;
+  }
+
+  @media (prefers-reduced-motion: no-preference) {
+    .trigger {
+      transition-property: border-color;
+      transition-duration: var(--fgd-duration-quick);
+      transition-timing-function: var(--ease-out-3);
+    }
+
+    .barChevron {
+      transition: rotate var(--fgd-duration-quick) var(--ease-out-3);
+    }
+  }
+}
+
+@layer compounds {
+  /* Entries fill their row: a block flex box, over Link's inline `nav` row. */
+  .link {
+    display: flex;
+  }
+}
+
+@layer states {
+  .list .link:focus-visible {
+    outline: var(--border-size-2) solid var(--primary12);
+    outline-offset: calc(-1 * var(--border-size-2));
+  }
+
+  /* The section in view: the --border-size-2-25 start-edge bar and weight 700 [D15]. */
+  .list .link[aria-current='location']::before {
+    border-inline-start-width: var(--border-size-2-25);
+  }
+
+  .list .link[aria-current='location'] {
+    font-weight: var(--font-weight-7);
+  }
+
+  /* The bar: the field edge steps to --primary12 on hover and while open [D140]. */
+  .trigger:hover,
+  .trigger[data-popup-open] {
+    border-color: var(--primary12);
+  }
+
+  .trigger[data-popup-open] .barChevron {
+    rotate: 180deg;
+  }
+
+  /* Focus: keyboard only, the ring the outline morph grows from [D45, D204]. */
+  .trigger:focus-visible {
+    outline: var(--border-size-2) solid var(--primary12);
+    outline-offset: var(--border-size-2);
+  }
+
+  /*
+   * Outline morph [D204] (`morph`, the default): while the overlay draws the
+   * frame, the panel's own edge takes its face. Without the morph the panel
+   * opens and closes at once [D205].
+   */
+  .panel[data-outline-morph] {
+    border-color: var(--primary1);
+    transition: none;
+  }
+}
+
+@layer print {
+  @media print {
+    /* Screen wayfinding: the document's own headings carry its structure (§7.7). */
+    .base,
+    .positioner {
+      display: none;
+    }
+  }
+}

package/navigation/table-of-contents/useActiveHeading.d.ts

@@ -0,0 +1,37 @@
+import * as React from 'react';
+/** Options for useActiveHeading. */
+export interface UseActiveHeadingOptions {
+    /**
+     * The scroll container the headings move in. Default: the viewport. Pass
+     * a ref when the content scrolls inside its own box (a panel, a demo).
+     */
+    root?: React.RefObject<Element | null>;
+    /**
+     * Where a heading becomes current: the activation line's distance below
+     * the root's top edge, in `px` (`'80px'`) or as a percentage of the
+     * root's height (`'25%'`). Default `'25%'`: a heading is current once
+     * its top has passed the top quarter of the view, and stays current
+     * until the next one passes.
+     */
+    line?: string;
+    /** `false` pauses the hook (it then returns `undefined`). Default `true`. */
+    enabled?: boolean;
+}
+/**
+ * Scrollspy for a table of contents [D202]: the id of the heading whose
+ * section is in view, for `TableOfContents`' `activeId`. An
+ * IntersectionObserver watches the headings against a band from the root's
+ * top edge down to `line`; each time one crosses the line the hook takes
+ * the last heading above it (the first while none has passed, the last
+ * once the root is scrolled to its end). The heading a link just landed on
+ * (the URL's hash) stays current while it sits above the line, so a short
+ * section chosen from the contents is the one marked. A `scrollend` pass
+ * re-reads the positions after jumps that cross no line.
+ *
+ * It only reads layout and returns an id: nothing it drives changes size
+ * (the list reserves each entry's current weight), so it causes no layout
+ * shift. It returns `undefined` on the server and before the first
+ * observation, so the server HTML marks no section.
+ */
+export declare function useActiveHeading(ids: readonly string[], options?: UseActiveHeadingOptions): string | undefined;
+//# sourceMappingURL=useActiveHeading.d.ts.map

package/navigation/table-of-contents/useActiveHeading.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useActiveHeading.d.ts","sourceRoot":"","sources":["../../src/navigation/table-of-contents/useActiveHeading.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,oCAAoC;AACpC,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,IAAI,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,OAAO,GAAG,IAAI,CAAC,CAAA;IACtC;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,6EAA6E;IAC7E,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAWD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,SAAS,MAAM,EAAE,EACtB,OAAO,GAAE,uBAA4B,GACpC,MAAM,GAAG,SAAS,CAoFpB"}