CngxToc
projects/ui/toc/toc.component.ts
Import#
import { CngxToc } from '@cngx/ui/toc'
Description#
"On this page" navigation rail. Renders a <nav> of anchor links from a
CngxTocItem outline, tracks the most-visible section through an
internal CngxScrollSpy, and communicates the active link via
aria-current inside the computed() graph. Nested items render as
indented sub-lists; native link semantics and tab order stay intact (a toc
is a navigation landmark of links, not a treeview).
Composition over configuration: the spy is bound in this component's own
template rather than via hostDirectives, because the organism - not the
consumer - owns the flat id list the spy observes, and [cngxScrollSpy] is
a required input. The spy resolves its targets through getElementById, so
its host placement is irrelevant to its function.
Metadata#
Providers#
CNGX_TOC- useExisting
CngxToc
Relationships
Index#
Inputs#
Derive the outline from the heading elements under contentRoot instead
of a hand-maintained [items] array. Headings nest by their level
(h2 > h3), and a heading with no id gets a slugified one written onto
it so the link can target it. Scans once after the first render; call
refresh after you inject or remove sections at runtime.
false, { transform: booleanAttribute }string | nullCSS selector for the scroll container the spy observes. null (default)
uses the viewport. Forwarded to the spy's [root]; also the root the
[autoDiscover] scan walks for headings.
nullWhich headings [autoDiscover] collects, in CSS-selector form.
'h2, h3'The outline to render. Tree-shaped; nested children become sub-lists.
Ignored when [autoDiscover] is set - the headings under contentRoot
become the outline instead.
EMPTY_ITEMSRoot margin forwarded to the spy. Defaults to the config cascade.
this.cfg.spy?.rootMargin ?? '0px'Outputs#
Methods#
handleActivate(item: CngxTocItem, event?: Event)Click / Enter handler: takes over the native anchor jump, scrolls, and announces the activation.
Re-run the [autoDiscover] heading scan. No-op unless [autoDiscover] is
set and we are on the browser. Call it after injecting or removing sections
at runtime - discovery is one-shot by design, not a live observer.
scrollTo(id: string)Scroll the section with this id into view and move focus to it. Honours
prefers-reduced-motion - the configured scrollBehavior is swapped for
'auto' (instant) whenever reduced motion is requested. A visual-only
jump is a silent state change for screen-reader users, so focus follows
the scroll (Pillar 2).