# Reading Tools Agents: start with [Workspace for Agents](https://workspace.socra.com/solutions/agents.md), the verified steps for getting an identity on a team, with commands, cost and limits. Socra: Fill the roles your team needs with proactive AI teammates, each with its own computer, identity and role. Canonical: https://socra.design/navigation/docs-reading-tools ## Governing rules [Building with Socra components](https://socra.design/agents.md) explains setup, consumption rules and verification. Semantic owner: Flash Module `workspace-reading-shell` in Socra Cortex when available. It supplies current intent and prerequisite rules; the public API below supplies exact code names and values. Use published property names, not inspector labels. Composition and preview settings are not component props. Public styling escape hatches do not permit product-local presentation overrides. Documentation navigation, Markdown actions, related pages, and reader feedback. Use the shared documentation article to keep orientation, navigation, and portable content consistent on every documentation page. Status: partial. The specimen consumes the published documentation package. Feedback uses a local demonstration action; submission security belongs to the host service. Library: @socra/web-docs ## Anatomy - Breadcrumb before the title - Documentation navigation button - Copy for LLM and View as Markdown actions directly below the title - Icon-only On this page menu beside the breadcrumb at every width - Related documentation after the article - Reader feedback with a host-owned submission action ## States - **Rest:** The breadcrumb identifies the document location. Both Markdown actions remain visible. - **Hover:** Available navigation and page actions show the shared hover treatment. - **Focus:** The navigation drawer and outline preserve keyboard access and return focus when dismissed. - **Pressed:** Navigation opens the selected document. Copy sends the complete portable Markdown to the clipboard. - **Selected:** The navigation marks the current document, and the desktop outline marks the current section. - **Disabled:** The copy action prevents a duplicate request while the clipboard operation is pending. - **Loading:** Copy feedback keeps the action geometry stable until the request completes. - **Error:** A clipboard failure leaves the Markdown link available as a recovery path. ## Motion Navigation and outline overlays use the shared dismissal and reduced-motion behavior. Opening a control does not move the article. ## Usage - Use one document source. The rendered article, copied text, and Markdown destination must describe the same document. ## Avoid - Keep navigation out of the copied document. Portable Markdown contains the document content and useful source links. ## Properties [Complete public API, including inherited properties and event signatures](https://socra.design/navigation/docs-reading-tools/api.md) ### Setup - Use the host-selected compatible Socra theme provider and published component styles. Keep one compatible provider instance across shared packages. - Import @socra/web-docs/styles.css and mount the required TanStack Router and DocsProvider configuration. The catalog memory router is a preview host; products supply their router. ### DocsArticle Import: `import { DocsArticle } from '@socra/web-docs';` | Property | Type or permitted values | Default / omission | Required | Meaning and behavior | Inspector | | --- | --- | --- | --- | --- | --- | | `onOptionChange` | `((group: string, value: string) => void) \| undefined` | Omitted; no declared default | no | | Direct API | | `page` | `DocPage` | Required input | yes | | Direct API | | `values` | `Record \| undefined` | Omitted; no declared default | no | | Direct API | ### DocsProvider Import: `import { DocsProvider } from '@socra/web-docs';` | Property | Type or permitted values | Default / omission | Required | Meaning and behavior | Inspector | | --- | --- | --- | --- | --- | --- | | `children` | `ReactNode` | Required input | yes | | Direct API | | `config` | `DocsConfig` | Required input | yes | | Direct API | ### DocsSearchProvider Import: `import { DocsSearchProvider } from '@socra/web-docs';` | Property | Type or permitted values | Default / omission | Required | Meaning and behavior | Inspector | | --- | --- | --- | --- | --- | --- | | `area` | `string \| undefined` | Omitted; no declared default | no | | Direct API | | `children` | `ReactNode` | Required input | yes | | Direct API | ### ReadingFrame Import: `import { ReadingFrame } from '@socra/web-docs';` | Property | Type or permitted values | Default / omission | Required | Meaning and behavior | Inspector | | --- | --- | --- | --- | --- | --- | | `children` | `ReactNode` | Required input | yes | | Direct API | | `contentInset` | `"none"`, `"page"` | `"page"` | no | | Direct API | | `externalHeader` | `false`, `true` | `false` | no | | Direct API | | `footer` | `ReactNode` | Omitted; no declared default | no | | Direct API | | `headings` | `DocHeading[] \| undefined` | Omitted; no declared default | no | | Direct API | | `sidebar` | `ReactNode` | Required input | yes | | Direct API | | `sidebarLabel` | `string` | Required input | yes | | Direct API | | `wide` | `false`, `true` | `false` | no | | Direct API | ### ReadingSidebar Import: `import { ReadingSidebar } from '@socra/web-docs';` | Property | Type or permitted values | Default / omission | Required | Meaning and behavior | Inspector | | --- | --- | --- | --- | --- | --- | | `actions` | `ReactNode` | Omitted; no declared default | no | | Direct API | | `children` | `ReactNode` | Required input | yes | | Direct API | | `compact` | `false`, `true` | `false` | no | | Direct API | | `header` | `ReactNode` | Omitted; no declared default | no | | Direct API | | `label` | `string` | Required input | yes | | Direct API | | `search` | `ReactNode` | Omitted; no declared default | no | | Direct API | | `selection` | `ReactNode` | Omitted; no declared default | no | | Direct API | ### ReadingBreadcrumbs Import: `import { ReadingBreadcrumbs } from '@socra/web-docs';` | Property | Type or permitted values | Default / omission | Required | Meaning and behavior | Inspector | | --- | --- | --- | --- | --- | --- | | `headings` | `DocHeading[] \| undefined` | `[]` | no | | Direct API | | `home` | `{ href: string; label: string; mark: ReactNode; } \| undefined` | Omitted; no declared default | no | | Direct API | | `items` | `readonly ReadingBreadcrumb[]` | Required input | yes | | Direct API | | `navigation` | `ReactNode` | Omitted; no declared default | no | | Direct API | ### ReadingNavigationDrawer Import: `import { ReadingNavigationDrawer } from '@socra/web-docs';` | Property | Type or permitted values | Default / omission | Required | Meaning and behavior | Inspector | | --- | --- | --- | --- | --- | --- | | `children` | `(header: ReactNode, onNavigate: () => void) => ReactNode` | Required input | yes | | Direct API | | `description` | `string` | Required input | yes | | Direct API | | `label` | `string` | Required input | yes | | Direct API | | `onOpenChange` | `((open: boolean) => void) \| undefined` | Omitted; no declared default | no | An effect reports the Sidebar provider mobile-open state, including its initial state. A supplied open synchronizes provider state; route pathname changes close the drawer. | Direct API | | `open` | `false`, `true` | Omitted; no declared default | no | | Direct API | | `restoreFocus` | `false`, `true` | `true` | no | When desktop replaces the mobile trigger, restoration falls back to the first visible reading-trail link. | Direct API | | `triggerRef` | `RefObject \| undefined` | Omitted; no declared default | no | | Direct API | ### MarkdocDocument Import: `import { MarkdocDocument } from '@socra/web-docs';` | Property | Type or permitted values | Default / omission | Required | Meaning and behavior | Inspector | | --- | --- | --- | --- | --- | --- | | `afterIntroduction` | `ReactNode` | Omitted; no declared default | no | | Direct API | | `onOptionChange` | `(group: string, value: string) => void` | Required input | yes | | Direct API | | `source` | `string` | Required input | yes | | Direct API | | `values` | `OptionValues` | Required input | yes | | Direct API | ### DocsPageActions Import: `import { DocsPageActions } from '@socra/web-docs';` | Property | Type or permitted values | Default / omission | Required | Meaning and behavior | Inspector | | --- | --- | --- | --- | --- | --- | | `markdown` | `string` | Required input | yes | | Direct API | | `markdownPath` | `string` | Required input | yes | | Direct API | ### docsHeadings Import: `import { docsHeadings } from '@socra/web-docs/content';` | Parameter | Type or permitted values | Default / omission | Required | Meaning and behavior | Inspector | | --- | --- | --- | --- | --- | --- | | `source` | `string` | Required input | yes | | Direct API | Returns `DocHeading[]`. ### NavGroup Import: `import { NavGroup } from '@socra/ui-web-navigation';` | Property | Type or permitted values | Default / omission | Required | Meaning and behavior | Inspector | | --- | --- | --- | --- | --- | --- | | `children` | `ReactNode` | Required input | yes | Navigation rows or a nested NavGroup for one further information level. | Direct API | | `collapsible` | `false`, `true` | `false` | no | Allow the labelled group to be expanded and collapsed. | Direct API | | `defaultExpanded` | `false`, `true` | `true` | no | Initial expansion state when the group is collapsible. | Direct API | | `disabled` | `false`, `true` | `false` | no | | Direct API | | `expanded` | `false`, `true` | Omitted; no declared default | no | Controlled expansion state for a collapsible group. Products that keep a destination's group held open (e.g. the group owning the current route) own the state; omit for the self-managed default. | Direct API | | `label` | `string` | Required input | yes | | Direct API | | `onExpandedChange` | `((expanded: boolean) => void) \| undefined` | Omitted; no declared default | no | Fires with the requested state when the user toggles a controlled group. | Direct API | ### NavItem Import: `import { NavItem } from '@socra/ui-web-navigation';` | Property | Type or permitted values | Default / omission | Required | Meaning and behavior | Inspector | | --- | --- | --- | --- | --- | --- | | `badge` | `number \| undefined` | Omitted; no declared default | no | New message/notification count; never a directory or object total. | Direct API | | `badgeLabel` | `string \| undefined` | Omitted; no declared default | no | Complete count meaning, including counts larger than the visible cap. | Direct API | | `badgeTone` | `"neutral"`, `"attention"` | Omitted; no declared default | no | Ordinary activity is neutral; direct attention keeps the emphasized treatment. | Direct API | | `chevron` | `false`, `true` | Omitted; no declared default | no | Trailing disclosure affordance. | Direct API | | `disabled` | `false`, `true` | `false` | no | | Direct API | | `href` | `undefined \| string` | Omitted; no declared default | no | | Direct API | | `icon` | `ReactElement> \| undefined` | Omitted; no declared default | no | The resting glyph. | Direct API | | `label` | `string` | Required input | yes | | Direct API | | `onNavigate` | `undefined \| MouseEventHandler \| undefined` | Omitted; no declared default | no | | Direct API | | `onSelect` | `() => void \| undefined` | Omitted; no declared default | no | | Direct API | | `selected` | `false`, `true` | `false` | no | | Direct API | | `selectedIcon` | `ReactElement> \| undefined` | Omitted; no declared default | no | The authored filled glyph for the current destination. New navigation configurations supply it whenever they supply an icon. The optional input preserves runtime compatibility for older consumers during migration. | Direct API | | `target` | `"_self"`, `"_blank"` | Omitted; no declared default | no | | Direct API | ### Behavior and constraints - Article mode uses DocsArticle; Collection mode composes the public reading parts. Host content and destinations remain local fictional examples. Feedback success/pending/failure is simulated locally and does not establish ingestion. ### Inspector mappings | Setting | Initial preview value | Consumed code | | --- | --- | --- | | Viewport | `390` | preview: Set the embedded browser viewport width in CSS pixels; this is not a component width prop. | | Theme | `dark` | preview: Set the embedded document theme provider; does not change document content. | | Document | `article` | composition: Select a fixture document or the Collection composition; the host supplies the public page/headings/navigation data. | | Feedback submission | `success` | preview: Choose local feedback callback result: resolve, remain pending, or reject; only article mode offers feedback. | ## Example ```tsx import { DocsArticle, DocsProvider, DocsSearchProvider, type DocPage, type DocsConfig } from '@socra/web-docs'; import '@socra/web-docs/styles.css'; // Render inside the host router and compatible shared theme providers. // config supplies areas, pages, and groups from the documentation source. export function Document({ config, page }: { config: DocsConfig; page: DocPage }) { return ( ); } ```