Table of Contents Tool

Overview

The Table of Contents tool automatically generates an interactive, draggable navigation panel based on page headings. It intelligently scans for heading elements (H1-H6) within the main content area, excludes navigational headers, and creates a clickable list that allows users to quickly jump to different sections of the page.

Features

• Smart Heading Detection: Automatically finds headings in main content, excluding navigation areas
• Hierarchical Display: Shows all heading levels with clear visual structure
• Smooth Scrolling: Animated navigation to selected sections with header offset compensation
• Draggable Interface: Moveable panel that can be positioned on left or right side
• Responsive Design: Adapts to mobile devices with touch-friendly interactions
• Auto-positioning: Remembers user's preferred side placement
• Empty State Handling: Graceful messaging when no headings are found
• Dynamic Content Support: Works with single-page applications and dynamic content

Settings

Level	Description
Disabled	Table of contents panel is hidden
Enabled	Interactive TOC panel is displayed and functional

Usage

1. Click the Table of Contents button in the accessibility toolbar
2. A draggable panel appears showing all page headings from main content
3. Click any heading in the TOC to smoothly scroll to that section
4. On desktop: Drag the panel header to reposition it to left or right side
5. On mobile: Panel is fixed and optimized for touch interaction
6. Click the close button (×) or toggle the tool button to hide the panel

Accessibility Benefits

• Page Navigation: Quick access to all content sections
• Document Structure: Visual overview of content organization
• Skip Navigation: Bypass repetitive content to reach desired sections
• Keyboard Accessible: Full keyboard navigation support with proper focus management
• Screen Reader Friendly: Properly labeled navigation region with ARIA attributes
• Cognitive Support: Helps users understand and navigate complex document structures
• Header Awareness: Automatically compensates for fixed headers when scrolling

Panel Features

Interactive Elements

• Heading Links: Click to scroll to section with smooth animation
• Flat Structure: Simple list format for easy scanning
• Drag Handle: Desktop users can drag header to reposition panel
• Close Button: Quick access to hide panel
• Auto-positioning: Snaps to left or right side based on drag position

Smart Detection

• Content Area Focus: Scans main content, excludes nav/header/footer/aside elements
• Heading Recognition: Automatically finds H1-H6 elements up to configured level
• Text Extraction: Cleans heading text, removes decorative elements
• ID Generation: Creates unique anchors for headings without existing IDs
• Visibility Check: Only includes visible headings in the navigation

Technical Features

• Header Offset Calculation: Detects fixed/sticky headers and adjusts scroll position
• Common Container Detection: Finds the main content area to scope heading search
• Responsive Behavior: Disables dragging on mobile, optimizes for touch
• Locale Support: Updates content when language changes

Technical Implementation

The tool uses JavaScript to intelligently scan the DOM for heading elements within the main content area, generates a flat navigation structure, implements smooth scrolling with automatic header offset compensation, and provides drag-and-drop positioning on desktop devices.

API Usage Example

The Table of Contents tool can be programmatically controlled using the widget API. Here's how to enable and customize the tool:

// Basic activation
window.BrowseAidWidget.api.enableTool('table-of-contents');

// Enable with custom settings
window.BrowseAidWidget.api.enableTool('table-of-contents', {
  maxLevel: 4,              // Maximum heading level to include (1-6, default: 6)
  position: 'right'         // Panel position: 'left' or 'right' (default: 'left')
});

// Update tool settings
window.BrowseAidWidget.api.updateTool('table-of-contents', {
  enabled: true,
  maxLevel: 3,
  position: 'left'
});

// Toggle the tool on/off
const isEnabled = window.BrowseAidWidget.api.toggleTool('table-of-contents');
console.log('Table of Contents is now:', isEnabled ? 'enabled' : 'disabled');

// Get current settings
const settings = window.BrowseAidWidget.api.getToolState('table-of-contents');
console.log('Current TOC settings:', settings);

// Disable the tool
window.BrowseAidWidget.api.disableTool('table-of-contents');

// Listen for tool changes
const unsubscribe = window.BrowseAidWidget.api.onToolChange((toolName, settings) => {
  if (toolName === 'table-of-contents') {
    console.log('Table of Contents settings changed:', settings);
  }
});

Configuration Options

Option	Type	Values	Default	Description
enabled	boolean	true/false	false	Enables or disables the tool
maxLevel	number	1-6	6	Maximum heading level to include in TOC
position	string	'left', 'right'	'left'	Panel position on screen

Heading Level Examples

• maxLevel: 2 - Only show H1 and H2 headings
• maxLevel: 4 - Show H1, H2, H3, and H4 headings
• maxLevel: 6 - Show all heading levels (default)

Usage Patterns

// Article navigation - focus on main sections
window.BrowseAidWidget.api.enableTool('table-of-contents', {
  maxLevel: 3,
  position: 'right'
});

// Documentation mode - show detailed structure
window.BrowseAidWidget.api.enableTool('table-of-contents', {
  maxLevel: 4,
  position: 'left'
});

// Overview mode - major sections only
window.BrowseAidWidget.api.enableTool('table-of-contents', {
  maxLevel: 2,
  position: 'right'
});

// Check if headings are available before enabling
function enableTOCIfHeadingsExist() {
  const headings = document.querySelectorAll('h1, h2, h3, h4, h5, h6');
  const mainContentHeadings = Array.from(headings).filter(h =>
    !h.closest('nav, header, footer, aside')
  );

  if (mainContentHeadings.length > 0) {
    window.BrowseAidWidget.api.enableTool('table-of-contents', {
      maxLevel: 4,
      position: 'right'
    });
    return true;
  }
  return false;
}

Integration Notes

• Tool automatically excludes headings from navigation areas (nav, header, footer, aside)
• Generates unique IDs for headings that don't have them
• Compensates for fixed/sticky headers when scrolling
• Responsive design adapts for mobile devices
• Supports dynamic content updates and locale changes
• Uses semantic HTML and ARIA attributes for accessibility