@farthershore/farthershore-js/components/docs-chrome exports
Every public export and declaration from @farthershore/farthershore-js/components/docs-chrome.
Every public export and declaration from @farthershore/farthershore-js/components/docs-chrome.
Import from @farthershore/farthershore-js/components/docs-chrome. This reference is extracted from the published declaration surface for version 0.32.0. Read the collection's guides for workflows, prerequisites and failure handling.
Normalize an arbitrary tab label/prop to a canonical language id, or `null`
when the tab is auxiliary (a response/rotate/json strip — NOT a language
variant). Matching is case-insensitive and alias-aware.
When `languages` is provided the info-string is matched against the declared
set first: a match on `id` or any of a language's `aliases` (case-insensitive)
wins and returns that language's `id`. Auxiliary labels always return `null`
regardless. When no declared set is provided the built-in alias table is used
as a fallback (js→node, py→python, golang→go) so existing callers are
unaffected.
Declaration source: packages/farthershore-js/dist/components/docs-chrome/language.d.ts#L27.
export declare function classifyTabLanguage(labelOrProp: string, languages?: ReadonlyArray<DocsLanguage>): string | null;
A selectable documentation collection (a self-contained docs bundle).
Declaration source: packages/farthershore-js/dist/components/docs-chrome/collections.d.ts#L2.
export type DocsCollection = {
/** Stable id: URL segment, R2 key prefix, storage key, and matching (e.g. "api"). */
id: string;
/** Human label for the selector/tab (e.g. "API reference"). */
label: string;
/** Optional tab image URL. The default selector renders it as an `<img src>`,
* so it must be an absolute/root-relative URL or data: URI. */
icon?: string;
};
Public export DocsCollectionsContextValue.
Declaration source: packages/farthershore-js/dist/components/docs-chrome/collections-context.d.ts#L2.
export type DocsCollectionsContextValue = {
/** The resolved active collection id, or null when there are no collections. */
activeCollection: string | null;
/** The full collection list (empty when unprovided / single bundle). */
collections: ReadonlyArray<DocsCollection>;
/** Switch the active collection (persists + lets the host navigate to it). */
setCollection: (id: string) => void;
};
Unstyled collection switcher — a `<button>` per collection (the host styles it
into a tab bar). Hidden entirely when there are ≤1 collections (a single-bundle
doc shows no control). Reads/writes through the docs collection context, so it
is a drop-in once a `<DocsCollectionsProvider>` is in scope. Ships NO CSS:
the active tab is exposed via `aria-pressed` for the host to style.
Declaration source: packages/farthershore-js/dist/components/docs-chrome/collections-context.d.ts#L51.
export declare function DocsCollectionSelector({ className, }?: DocsCollectionSelectorProps): import("react").JSX.Element | null;
Public export DocsCollectionSelectorProps.
Declaration source: packages/farthershore-js/dist/components/docs-chrome/collections-context.d.ts#L41.
export type DocsCollectionSelectorProps = {
className?: string;
};
Public export DocsCollectionsProvider.
Declaration source: packages/farthershore-js/dist/components/docs-chrome/collections-context.d.ts#L10.
declare const DocsCollectionsProvider: import("react").Provider<DocsCollectionsContextValue>;
A selectable documentation language (an SDK/runtime target).
Declaration source: packages/farthershore-js/dist/components/docs-chrome/language.d.ts#L2.
export type DocsLanguage = {
/** Stable id used in `?lang=`, storage, and tab/page matching (e.g. "node"). */
id: string;
/** Human label for the selector (e.g. "Node.js"). */
label: string;
/** Optional icon key (renderer maps it to a glyph). */
icon?: string;
/**
* Additional spellings that should map to this language id (e.g. `["rb"]` for
* Ruby, `["ts"]` for TypeScript). Matching is case-insensitive.
*/
aliases?: string[];
};
Public export DocsLanguageContextValue.
Declaration source: packages/farthershore-js/dist/components/docs-chrome/language-context.d.ts#L3.
export type DocsLanguageContextValue = {
/** The resolved active language id, or null when there is no language concept. */
activeLanguage: string | null;
/** The full language list (empty when unprovided / single-language). */
languages: ReadonlyArray<DocsLanguage>;
/** Switch the active language (persists + reflects into `?lang=`). */
setLanguage: (id: string) => void;
};
Public export DocsLanguageProvider.
Declaration source: packages/farthershore-js/dist/components/docs-chrome/language-context.d.ts#L11.
declare const DocsLanguageProvider: import("react").Provider<DocsLanguageContextValue>;
A docs page that may be scoped to a subset of languages.
Declaration source: packages/farthershore-js/dist/components/docs-chrome/language.d.ts#L74.
export type DocsLanguageScopedPage = {
/** When present, the page only exists for these languages. */
languages?: ReadonlyArray<string> | null;
};
Native `<select>` language switcher — the language analogue of the docs
version selector. Hidden entirely when there are ≤1 languages (a
single-language doc shows no control). Reads/writes through the docs language
context, so it is a drop-in once a `<DocsLanguageProvider>` is in scope.
When any language declares an `icon`, the selector renders a custom
button-list so the icon can appear alongside the label. When no icons are
declared the native `<select>` is used (lighter, more accessible on mobile).
Declaration source: packages/farthershore-js/dist/components/docs-chrome/language-context.d.ts#L47.
export declare function DocsLanguageSelector({ className, }?: DocsLanguageSelectorProps): import("react").JSX.Element | null;
Public export DocsLanguageSelectorProps.
Declaration source: packages/farthershore-js/dist/components/docs-chrome/language-context.d.ts#L34.
export type DocsLanguageSelectorProps = {
className?: string;
};
A docs code tab — language variants carry a `lang`, aux tabs do not.
Declaration source: packages/farthershore-js/dist/components/docs-chrome/language.d.ts#L50.
export type DocsLanguageTab = {
label: string;
/**
* The tab's language id. When absent it is derived from the label via
* {@link classifyTabLanguage} (so existing tab shapes need no change).
*/
lang?: string | null;
};
Whether a page is visible for the active language. A page with no
`languages` (the common case) is universal — visible for every language and
when no language is selected. A scoped page is visible only when its list
includes the active language (and is hidden when no language is selected,
since it was explicitly scoped).
Declaration source: packages/farthershore-js/dist/components/docs-chrome/language.d.ts#L85.
export declare function isPageVisibleForLanguage(page: DocsLanguageScopedPage, activeLanguage: string | null): boolean;
Render `children` only when the active docs language matches `lang` (a single
id or a comma-separated allow-list). With no active language (single-language
/ unprovided) NOTHING is rendered — `<LangBlock>` is inherently a
multi-language affordance, so it stays inert until a language is chosen.
Declaration source: packages/farthershore-js/dist/components/docs-chrome/language-context.d.ts#L59.
export declare function LangBlock({ lang, children }: LangBlockProps): import("react").JSX.Element | null;
Public export LangBlockProps.
Declaration source: packages/farthershore-js/dist/components/docs-chrome/language-context.d.ts#L48.
export type LangBlockProps = {
/** One language id or a comma-separated list (e.g. "go,node"). */
lang: string;
children?: ReactNode;
};
Resolve the active collection id following the precedence:
explicit route → stored → defaultCollection → collections[0] → null
A candidate only wins when it is actually one of `collections` (an unknown
route segment or a stale stored value is ignored, falling through to the next
source). With no collections at all the result is `null` — the "single
bundle / no collections" sentinel every consumer treats as "render the one
bundle, show no tab bar".
Declaration source: packages/farthershore-js/dist/components/docs-chrome/collections.d.ts#L32.
export declare function resolveActiveCollection(input: ResolveActiveCollectionInput): string | null;
Inputs to {@link resolveActiveCollection} — every source is optional.
Declaration source: packages/farthershore-js/dist/components/docs-chrome/collections.d.ts#L12.
export type ResolveActiveCollectionInput = {
/** Explicit selection from the route (first path segment); highest precedence. */
explicit?: string | null;
/** Last persisted selection (scoped localStorage). */
stored?: string | null;
/** The doc's declared default collection. */
defaultCollection?: string | null;
/** The doc's full collection list. */
collections?: ReadonlyArray<DocsCollection> | null;
};
Resolve the active language id following the precedence:
explicit `?lang=` → stored → defaultLanguage → languages[0] → null
A candidate only wins when it is actually one of `languages` (an unknown
`?lang=` or a stale stored value is ignored, falling through to the next
source). With no languages at all the result is `null` — the "no language
concept" sentinel every consumer treats as "render everything".
Declaration source: packages/farthershore-js/dist/components/docs-chrome/language.d.ts#L48.
export declare function resolveActiveLanguage(input: ResolveActiveLanguageInput): string | null;
Inputs to {@link resolveActiveLanguage} — every source is optional.
Declaration source: packages/farthershore-js/dist/components/docs-chrome/language.d.ts#L29.
export type ResolveActiveLanguageInput = {
/** Explicit selection from the URL (`?lang=`); highest precedence. */
explicit?: string | null;
/** Last persisted selection (scoped localStorage). */
stored?: string | null;
/** The doc's declared default language. */
defaultLanguage?: string | null;
/** The doc's full language list. */
languages?: ReadonlyArray<DocsLanguage> | null;
};
Partition `tabs` into language variants vs auxiliary tabs and keep only the
active language's variant (plus every aux tab), in original order.
Byte-identical guarantee: if there is ≤1 language tab, OR `activeLanguage`
is `null`, the input is returned UNCHANGED (same array, same order) — a
single-language / no-language page never sees filtering. Otherwise the
active-language tab is kept (falling back to the FIRST language tab when the
active language has no variant here, so the card is never blank), followed by
all aux tabs.
When `languages` is provided it is forwarded to {@link classifyTabLanguage}
so that builder-declared languages (with custom aliases) are recognized.
Declaration source: packages/farthershore-js/dist/components/docs-chrome/language.d.ts#L72.
export declare function selectLanguageTabs<T extends DocsLanguageTab>(tabs: ReadonlyArray<T>, activeLanguage: string | null, languages?: ReadonlyArray<DocsLanguage>): ReadonlyArray<T>;
Minimal heading shape both renderers share (depth-tagged TOC entries).
Declaration source: packages/farthershore-js/dist/components/docs-chrome/nav-hooks.d.ts#L22.
export type SpyHeading = {
id: string;
depth: number;
};
Read the active docs collection. Unprovided → `{ activeCollection: null, … }`.
Declaration source: packages/farthershore-js/dist/components/docs-chrome/collections-context.d.ts#L12.
export declare function useDocsCollections(): DocsCollectionsContextValue;
Derives the active-collection context value from the route: the URL segment
is the source of truth (see `resolveActiveCollection` precedence), so there is
no separate persisted state — a bare `/docs` falls back to `defaultCollection`
then `collections[0]`. `setCollection` invokes `onSelect` so the host
navigates; the resulting route change re-derives `activeCollection`. SSR-safe:
a pure derivation from props, no window access.
Declaration source: packages/farthershore-js/dist/components/docs-chrome/collections-context.d.ts#L40.
export declare function useDocsCollectionsState(options: UseDocsCollectionsStateOptions): DocsCollectionsContextValue;
Public export UseDocsCollectionsStateOptions.
Declaration source: packages/farthershore-js/dist/components/docs-chrome/collections-context.d.ts#L13.
export type UseDocsCollectionsStateOptions = {
/** The doc's full collection list. */
collections: ReadonlyArray<DocsCollection>;
/** The doc's declared default collection. */
defaultCollection?: string | null;
/**
* The collection id encoded in the current route (first path segment). The
* URL is the source of truth for this route-bearing axis, so it wins;
* `defaultCollection` then `collections[0]` are the fallbacks for a bare
* `/docs`.
*/
routeCollection?: string | null;
/**
* Called when the user picks a DIFFERENT collection, so the host can navigate
* to its landing page. Keeps this layer router-agnostic (no product-docs /
* router dependency); the route change is what actually flips the active tab.
*/
onSelect?: (collection: DocsCollection) => void;
};
Read the active docs language. Unprovided → `{ activeLanguage: null, … }`.
Declaration source: packages/farthershore-js/dist/components/docs-chrome/language-context.d.ts#L13.
export declare function useDocsLanguage(): DocsLanguageContextValue;
Owns the active-language state for a docs surface: resolves the initial value
(explicit `?lang=` → stored → defaultLanguage → languages[0] → null),
persists changes to a scope-namespaced localStorage key, and reflects the
choice into `?lang=` (merging, never clobbering `?v=`/`?view=`). Returns the
context value to feed `<DocsLanguageProvider>`.
SSR-safe: the initial state ignores window on the server (resolves from the
declared default/list only); the explicit/stored sources are merged on the
client in an effect, so the first hydration matches the server snapshot.
Declaration source: packages/farthershore-js/dist/components/docs-chrome/language-context.d.ts#L33.
export declare function useDocsLanguageState(options: UseDocsLanguageStateOptions): DocsLanguageContextValue;
Public export UseDocsLanguageStateOptions.
Declaration source: packages/farthershore-js/dist/components/docs-chrome/language-context.d.ts#L14.
export type UseDocsLanguageStateOptions = {
/** The doc's full language list. */
languages: ReadonlyArray<DocsLanguage>;
/** The doc's declared default language. */
defaultLanguage?: string | null;
/** Namespaces the localStorage key so different docs don't share a choice. */
scopeKey?: string | null;
};
Track which h2 (`depth === 2`) heading is currently in view, for the active
sidebar sub-tree highlight. Observes every h2 element by id with a bottom
root-margin so a heading counts as "active" once it scrolls near the top,
and seeds the active id to the first h2 so something is highlighted before
the first scroll. Re-runs when the heading set or `key` (the current slug)
changes. Returns `[activeHeadingId, setActiveHeadingId]` — the setter lets a
sub-tree link mark itself active on click (both renderers do this).
Declaration source: packages/farthershore-js/dist/components/docs-chrome/nav-hooks.d.ts#L35.
export declare function useHeadingSpy(headings: ReadonlyArray<SpyHeading>, key: string): [string | null, Dispatch<SetStateAction<string | null>>];
Multi-open accordion state for docs nav groups. The group holding the current
page (`activeGroupTitle`) opens by default, navigating to a page in another
group ADDS that group (never collapsing one the reader opened), and the open
set persists across the per-navigation shell remount via `openGroupsMemory`.
Own this ONCE per shell and share the result across the sidebar + mobile
drawer nav instances — two states writing the shared memory would race
last-writer-wins and drop a group opened in the other pane.
Declaration source: packages/farthershore-js/dist/components/docs-chrome/nav-hooks.d.ts#L20.
export declare function useOpenGroups(activeGroupTitle: string | null): UseOpenGroupsResult;
Public export UseOpenGroupsResult.
Declaration source: packages/farthershore-js/dist/components/docs-chrome/nav-hooks.d.ts#L4.
export type UseOpenGroupsResult = {
/** The currently-expanded group titles. */
openGroups: Set<string>;
/** Toggle one group open/closed (multi-open: never collapses the others). */
toggleGroup: (title: string) => void;
};
These declarations explain types reachable from the public exports above. They are source evidence, not supported package imports. Suffixed names are documentation identifiers that preserve distinct lexical bindings. Standard-library and third-party types (for example Promise, React and Zod) remain external boundaries; their implementation declarations are not expanded here.