rich-react-component 0.2.0 → 0.3.1

package/dist/base/AppearanceMenu.d.ts

@@ -0,0 +1,65 @@
+import { SidebarPresentation, SidebarTone, ThemeMode } from './Appearance';
+import { ColorScheme } from './appearanceSchemes';
+/**
+ * Every visible string is supplied by the caller — this component ships no
+ * built-in copy in any language, so it can be dropped into an application that
+ * owns its own localization.
+ */
+export interface AppearanceMenuLabels {
+    presentation: {
+        title: string;
+        compact: string;
+        grouped: string;
+    };
+    mode: {
+        title: string;
+        light: string;
+        dark: string;
+        system: string;
+    };
+    tone: {
+        title: string;
+        light: string;
+        dark: string;
+        auto: string;
+    };
+    /** `options` maps a registered scheme id to its display name. */
+    colorScheme: {
+        title: string;
+        options: Record<string, string>;
+    };
+}
+/** Each section is hideable on its own. Omitted entries default to visible. */
+export interface AppearanceMenuSections {
+    presentation?: boolean;
+    mode?: boolean;
+    tone?: boolean;
+    colorScheme?: boolean;
+}
+export interface AppearanceMenuProps {
+    labels: AppearanceMenuLabels;
+    sections?: AppearanceMenuSections;
+    className?: string;
+    /** Controlled values. When given, the provider is not written to for that setting. */
+    mode?: ThemeMode;
+    onModeChange?: (mode: ThemeMode) => void;
+    sidebarPresentation?: SidebarPresentation;
+    onSidebarPresentationChange?: (presentation: SidebarPresentation) => void;
+    sidebarTone?: SidebarTone;
+    onSidebarToneChange?: (tone: SidebarTone) => void;
+    colorSchemeId?: string;
+    onColorSchemeIdChange?: (id: string) => void;
+    /** Restrict/order the offered schemes. Defaults to every registered scheme. */
+    colorSchemes?: ColorScheme[];
+}
+/**
+ * Composable appearance selector. Drop it into a `Navbar` slot, a `Popover`,
+ * a `Menu` trigger's content, a settings drawer, or any application-owned
+ * container.
+ *
+ * Deliberately NOT a Metronic Layout Builder: it exposes exactly four
+ * independent settings and nothing else. It forces no persistence, mutates no
+ * global DOM, and makes no decision about who is allowed to change branding —
+ * those belong to the application.
+ */
+export declare function AppearanceMenu({ labels, sections, className, mode, onModeChange, sidebarPresentation, onSidebarPresentationChange, sidebarTone, onSidebarToneChange, colorSchemeId, onColorSchemeIdChange, colorSchemes, }: AppearanceMenuProps): import("react").JSX.Element;

package/dist/base/Badge.d.ts

@@ -1,9 +1,16 @@
 import { ReactNode } from 'react';
 export type BadgeVariant = "primary" | "secondary" | "success" | "danger" | "warning" | "info" | "light" | "dark";
+/**
+ * How the variant colour is applied. Additive: `solid` is the existing
+ * behaviour and stays the default, so no current rendering changes.
+ */
+export type BadgeAppearance = "solid" | "light" | "outline";
 export interface BadgeProps {
     variant?: BadgeVariant;
+    /** `light` and `outline` are the restrained forms for ordinary metadata. */
+    appearance?: BadgeAppearance;
     pill?: boolean;
     className?: string;
     children: ReactNode;
 }
-export declare function Badge({ variant, pill, className, children }: BadgeProps): import("react").JSX.Element;
+export declare function Badge({ variant, appearance, pill, className, children }: BadgeProps): import("react").JSX.Element;

package/dist/base/Button.d.ts

@@ -1,5 +1,13 @@
 import { ButtonHTMLAttributes, ReactNode } from 'react';
-export type ButtonVariant = "primary" | "secondary" | "success" | "danger" | "warning" | "info" | "light" | "dark" | "link" | "outline-primary" | "outline-secondary";
+export type ButtonVariant = "primary" | "secondary" | "success" | "danger" | "warning" | "info" | "light" | "dark" | "link" | "outline-primary" | "outline-secondary"
+/**
+ * Contextual light variants — a soft tinted surface with the contextual
+ * foreground, the Metronic Bootstrap signature for a secondary action.
+ * Added additively; Bootstrap has no `btn-light-*` rule of its own, so these
+ * render as a plain button until `rich-react-component/style.css` is
+ * imported, and no existing variant changed.
+ */
+ | "light-primary" | "light-secondary" | "light-success" | "light-danger" | "light-warning" | "light-info";
 export interface ButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "className" | "type" | "disabled"> {
     variant?: ButtonVariant;
     size?: "sm" | "lg";

package/dist/base/Sidebar.d.ts

@@ -1,31 +1,121 @@
-import { ReactNode } from 'react';
-export interface SidebarLeafItem {
-    key: string;
-    label: ReactNode;
-    icon?: ReactNode;
-    href?: string;
-    onClick?: () => void;
-    active?: boolean;
-    disabled?: boolean;
+import { CSSProperties, MouseEvent, ReactNode } from 'react';
+import { SidebarPresentation, SidebarTone } from './Appearance';
+import { SidebarExpandMode, SidebarItem, SidebarLinkItem, SidebarSection, SidebarSelectHandler } from './sidebarModel';
+export type { SidebarActionItem, SidebarCollapsibleItem, SidebarDividerItem, SidebarExpandMode, SidebarGroup, SidebarGroupItem, SidebarItem, SidebarLeafItem, SidebarLinkItem, SidebarParentItem, SidebarSection, SidebarSelectHandler, } from './sidebarModel';
+export { isSidebarExpandable, isSidebarParent, legacyActiveKey, legacyDefaultExpandedKeys, toSidebarItems } from './sidebarModel';
+/**
+ * How the current route may change which branches are open.
+ *
+ * - `never` — the active route never touches expansion.
+ * - `on-active-change` — the active branch opens on mount and again whenever
+ *   `activeKey` changes, and the user may close it afterwards. This is what
+ *   `expandActivePath` means.
+ * - `always` — active ancestors are forced open on every render, so the active
+ *   branch cannot be closed. Kept because it was the behaviour `expandActivePath`
+ *   used to have; it is not the default and not recommended.
+ */
+export type SidebarActivePathExpansion = "never" | "on-active-change" | "always";
+/**
+ * `grouped` is the presentation this component has always rendered and stays
+ * the default. Alias of the appearance layer's `SidebarPresentation` so the
+ * two can never drift apart.
+ */
+export type SidebarVariant = SidebarPresentation;
+export interface SidebarLinkRenderProps {
+    item: SidebarLinkItem;
+    href: string;
+    className: string;
+    style: CSSProperties;
+    children: ReactNode;
+    onClick: (event: MouseEvent<HTMLAnchorElement>) => void;
+    "aria-current": "page" | undefined;
+    "aria-disabled": true | undefined;
+    "aria-label": string | undefined;
+    "data-active-ancestor": "true" | undefined;
+    target: string | undefined;
+    rel: string | undefined;
 }
-export interface SidebarGroup {
-    key: string;
+/**
+ * Lets the application swap the anchor for its own router link. Base stays
+ * routing-agnostic: no router package is imported and no route matching
+ * happens here (doc section 22).
+ */
+export type SidebarLinkRenderer = (props: SidebarLinkRenderProps) => ReactNode;
+export interface SidebarCollapseControlProps {
+    collapsed: boolean;
+    toggle: () => void;
     label: string;
-    items: SidebarLeafItem[];
-    defaultOpen?: boolean;
 }
-export type SidebarSection = SidebarLeafItem | SidebarGroup;
 export interface SidebarProps {
-    sections: SidebarSection[];
+    /** Recursive navigation model. Takes precedence over `sections` when both are given. */
+    items?: SidebarItem[];
+    /** @deprecated Legacy flat/one-level model. Still fully supported; normalized onto `items`. */
+    sections?: SidebarSection[];
+    /** `grouped` (default, the historical presentation) or the compact Metronic-style aside. */
+    variant?: SidebarVariant;
+    /** Surface tone. `auto` inherits the page theme; `light`/`dark` scope Bootstrap 5.3's own `data-bs-theme`. */
+    tone?: SidebarTone;
+    /** The one authoritative active identity. Ancestors are derived, not passed in. */
+    activeKey?: string;
+    /**
+     * Open the branch leading to `activeKey`. Off by default, so legacy rendering
+     * is unchanged. Shorthand for `activePathExpansion="on-active-change"`: the
+     * path opens on mount and whenever `activeKey` changes, and stays closable by
+     * hand in between.
+     */
+    expandActivePath?: boolean;
+    /** Explicit strategy. Wins over `expandActivePath` when both are given. */
+    activePathExpansion?: SidebarActivePathExpansion;
+    expandedKeys?: string[];
+    defaultExpandedKeys?: string[];
+    onExpandedKeysChange?: (keys: string[]) => void;
+    /** `multiple` (default) reproduces the legacy independent-groups behavior. */
+    expandMode?: SidebarExpandMode;
+    collapsed?: boolean;
+    defaultCollapsed?: boolean;
+    onCollapsedChange?: (collapsed: boolean) => void;
+    /** Render the collapse/expand control. */
+    collapsible?: boolean;
+    renderCollapseControl?: (props: SidebarCollapseControlProps) => ReactNode;
+    /** Accessible name of the control while expanded (i.e. the action it performs). */
+    collapseLabel?: string;
+    /** Accessible name of the control while collapsed. */
+    expandLabel?: string;
+    mobileOpen?: boolean;
+    defaultMobileOpen?: boolean;
+    onMobileOpenChange?: (open: boolean) => void;
+    /** Accessible name for the mobile drawer dialog. Falls back to `navLabel`. */
+    mobileLabel?: string;
+    /** Close the mobile drawer when a link or action is selected. */
+    closeMobileOnSelect?: boolean;
     header?: ReactNode;
     footer?: ReactNode;
+    /**
+     * Footer presentation while collapsed. A footer sized for the expanded aside
+     * cannot survive a ~58px rail — a select or an input would simply be clipped —
+     * and CSS alone cannot turn one control into another. Supply a compact
+     * icon-sized control here. Additive: when it is omitted the footer region is
+     * not rendered while collapsed, so nothing is clipped and no focusable
+     * control is left in a region the user cannot read.
+     */
+    collapsedFooter?: ReactNode;
     className?: string;
+    /** Accessible name of the navigation landmark. */
+    navLabel?: string;
+    onSelect?: SidebarSelectHandler;
+    renderLink?: SidebarLinkRenderer;
 }
 /**
- * Persistent vertical navigation. Leaf entries render as plain nav links;
- * grouped/collapsible sections reuse Accordion (doc section 20 — no second
- * independent collapse implementation) instead of reimplementing open/close
- * state. Active-state comes from the `active` flag the caller passes in —
- * routing/URL matching is the consuming app's job (doc section 22).
+ * Persistent vertical navigation.
+ *
+ * One recursive tree, one authoritative expansion state and one authoritative
+ * `activeKey` — no per-group Accordion instance and no per-item `active`
+ * boolean to keep in sync. The legacy `sections` shape is normalized onto the
+ * same model (`toSidebarItems`) so there is a single rendering path
+ * (doc section 20).
+ *
+ * Routing stays out of Base: real destinations render as anchors (or the
+ * consumer's `renderLink`), commands render as buttons, and URL matching
+ * remains the application's job (doc section 22).
  */
-export declare function Sidebar({ sections, header, footer, className }: SidebarProps): import("react").JSX.Element;
+export declare function Sidebar({ items, sections, variant, tone, activeKey, expandActivePath, activePathExpansion, expandedKeys, defaultExpandedKeys, onExpandedKeysChange, expandMode, collapsed, defaultCollapsed, onCollapsedChange, collapsible, renderCollapseControl, collapseLabel, expandLabel, mobileOpen, defaultMobileOpen, onMobileOpenChange, mobileLabel, closeMobileOnSelect, header, footer, collapsedFooter, className, navLabel, onSelect, renderLink, }: SidebarProps): import("react").JSX.Element;

package/dist/base/Tag.d.ts

@@ -1,7 +1,9 @@
 import { ReactNode } from 'react';
-import { BadgeVariant } from './Badge';
+import { BadgeAppearance, BadgeVariant } from './Badge';
 export interface TagProps {
     variant?: BadgeVariant;
+    /** Same additive contract as Badge; `solid` stays the default. */
+    appearance?: BadgeAppearance;
     onRemove?: () => void;
     className?: string;
     children: ReactNode;
@@ -11,4 +13,4 @@ export interface TagProps {
  * from Badge is purely behavioral: Tag is removable/interactive, Badge is
  * static.
  */
-export declare function Tag({ variant, onRemove, className, children }: TagProps): import("react").JSX.Element;
+export declare function Tag({ variant, appearance, onRemove, className, children }: TagProps): import("react").JSX.Element;

package/dist/base/Tooltip.d.ts

@@ -4,6 +4,13 @@ export interface TooltipProps {
     children: ReactNode;
     placement?: "top" | "bottom";
     className?: string;
+    /**
+     * Class for the trigger wrapper. The wrapper is inline-block by default,
+     * which is right for an inline trigger but wrong for a full-width row (e.g.
+     * a collapsed Sidebar item), so callers can override the display here
+     * instead of reimplementing a second tooltip.
+     */
+    wrapperClassName?: string;
 }
 /**
  * Reuses the existing Popup primitive (open/close, escape-to-close, outside
@@ -18,4 +25,4 @@ export interface TooltipProps {
  * conservative choice here, not less (doc section 18: "do NOT introduce
  * another positioning library unless actually necessary").
  */
-export declare function Tooltip({ content, children, placement, className }: TooltipProps): import("react").JSX.Element;
+export declare function Tooltip({ content, children, placement, className, wrapperClassName }: TooltipProps): import("react").JSX.Element;

package/dist/base/appearanceSchemes.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Semantic color schemes.
+ *
+ * A scheme is deliberately NOT a single raw color. Changing only the primary
+ * hue leaves buttons, active components and menu states inconsistent, so a
+ * scheme is a complete coordinated token family that is validated before it
+ * can be registered or applied.
+ *
+ * Variable mapping (verified against the repository's real styling stack —
+ * `bootstrap@5.3.8`, which is this package's peer dependency):
+ *
+ * - `--bs-primary` and `--bs-primary-rgb` genuinely exist in Bootstrap 5.3 and
+ *   are written directly, so Bootstrap's own components follow the scheme.
+ * - `--bs-primary-active`, `--bs-primary-light`, `--bs-primary-inverse`,
+ *   `--bs-component-*` and `--bs-menu-link-color-*` do NOT exist in Bootstrap.
+ *   They are Metronic's names. They are emitted anyway so that an application
+ *   that really does ship Metronic gets a coordinated result instead of a
+ *   half-recolored theme.
+ * - `--rrc-*` are this repository's own tokens, which are what this library's
+ *   stylesheet actually consumes. Each one falls back to the Bootstrap or
+ *   Metronic variable when present, so the mapping works with Metronic, with
+ *   plain Bootstrap, and with neither.
+ */
+/** The full token family a scheme must define. */
+export interface ColorSchemeTokens {
+    primary: string;
+    primaryActive: string;
+    primaryLight: string;
+    /** Foreground placed on top of `primary` — the scheme's contrast value. */
+    primaryInverse: string;
+    /** Comma-separated channels of `primary`, e.g. "13, 110, 253". */
+    primaryRgb: string;
+    componentActiveColor: string;
+    componentActiveBg: string;
+    componentHoverColor: string;
+    componentHoverBg: string;
+    componentCheckedColor: string;
+    componentCheckedBg: string;
+    menuLinkColorHover: string;
+    menuLinkColorShow: string;
+    menuLinkColorHere: string;
+    menuLinkColorActive: string;
+}
+export interface ColorScheme {
+    id: string;
+    tokens: ColorSchemeTokens;
+    /**
+     * Optional swatch color for a selector UI. Defaults to `tokens.primary`.
+     * Never the scheme's identity — selection must be indicated by more than
+     * color alone, so the selector also renders a real label and a checked state.
+     */
+    swatch?: string;
+}
+export declare const COLOR_SCHEME_TOKEN_KEYS: readonly (keyof ColorSchemeTokens)[];
+/** True only when every required token is present and non-empty. */
+export declare function isValidColorScheme(value: unknown): value is ColorScheme;
+export interface ColorSchemeSeed {
+    id: string;
+    primary: string;
+    primaryActive: string;
+    primaryLight: string;
+    primaryInverse: string;
+    primaryRgb: string;
+    swatch?: string;
+}
+/**
+ * Derives the coordinated component/menu tokens from the four primary shades,
+ * so a scheme author cannot accidentally register a half-defined family.
+ * Callers that need full control can build a `ColorScheme` literal instead.
+ */
+export declare function createColorScheme(seed: ColorSchemeSeed): ColorScheme;
+/** The scheme applied when nothing else is selected — Bootstrap's own primary. */
+export declare const DEFAULT_COLOR_SCHEME_ID = "blue";
+/**
+ * Registers an application-owned scheme. Rejects an incomplete family rather
+ * than applying a partially recolored theme.
+ */
+export declare function registerColorScheme(scheme: ColorScheme): void;
+export declare function getColorScheme(id: string): ColorScheme | undefined;
+/** Registered schemes in registration order — built-ins first. */
+export declare function listColorSchemes(): ColorScheme[];
+/**
+ * Resolves an identifier to a scheme, falling back to the default rather than
+ * throwing, so an unknown persisted value degrades safely.
+ */
+export declare function resolveColorScheme(id: string | undefined): ColorScheme;
+/**
+ * The scheme as CSS custom properties, ready to spread into a `style` object
+ * or write onto a DOM node. Emits the real Bootstrap variables, the
+ * Metronic-compatible names, and this repository's own `--rrc-*` tokens.
+ */
+export declare function colorSchemeCssVariables(scheme: ColorScheme): Record<string, string>;

package/dist/base/index.d.ts

@@ -53,6 +53,10 @@ export * from './IconButton';
 export * from './ListItem';
 export * from './Sparkline';
 export * from './Statistic';
+export { AppearanceProvider, useAppearance, createAppearanceInitScript, THEME_MODES, SIDEBAR_PRESENTATIONS, SIDEBAR_TONES } from './Appearance';
+export type { AppearanceContextValue, AppearanceInitScriptOptions, AppearanceProviderProps, AppearanceSettings, AppearanceStorage, ResolvedTheme, SidebarPresentation, SidebarTone, ThemeMode, } from './Appearance';
+export * from './appearanceSchemes';
+export * from './AppearanceMenu';
 export { Popup } from './shared/Popup';
 export type { PopupProps } from './shared/Popup';
 export { Label } from './shared/Label';

package/dist/base/sidebarModel.d.ts

@@ -0,0 +1,171 @@
+import { MouseEvent, ReactNode } from 'react';
+/**
+ * @deprecated Use the recursive `SidebarItem` model (`SidebarLinkItem` /
+ * `SidebarActionItem`) via `Sidebar.items`. Still accepted by
+ * `Sidebar.sections` and normalized internally — see `toSidebarItems`.
+ */
+export interface SidebarLeafItem {
+    key: string;
+    label: ReactNode;
+    icon?: ReactNode;
+    href?: string;
+    onClick?: () => void;
+    active?: boolean;
+    disabled?: boolean;
+}
+/**
+ * @deprecated Use `SidebarGroupItem` (`type: "group"`, `collapsible: true`)
+ * via `Sidebar.items`. Still accepted by `Sidebar.sections`.
+ */
+export interface SidebarGroup {
+    key: string;
+    label: string;
+    items: SidebarLeafItem[];
+    defaultOpen?: boolean;
+}
+/** @deprecated Use `SidebarItem`. */
+export type SidebarSection = SidebarLeafItem | SidebarGroup;
+/**
+ * Fired for the two item kinds that represent a destination or a command.
+ * The original React event is passed through so the consuming app can decide
+ * for itself whether to take over navigation (`event.preventDefault()` plus a
+ * router push). The Base layer never calls `preventDefault()` for an enabled
+ * real link, so modified clicks (ctrl/cmd/middle-click, "open in new tab")
+ * keep working (doc section 22: Base must not know routing).
+ */
+export type SidebarSelectHandler = (item: SidebarLinkItem | SidebarActionItem, event: MouseEvent<HTMLAnchorElement | HTMLButtonElement>) => void;
+interface SidebarItemBase {
+    /** Stable identity. Never derived from an array index; must be unique in the tree. */
+    key: string;
+    label: ReactNode;
+    /** Any React node — an `<Icon />`, an `<img>`, an emoji. Icon-set agnostic (doc section 15). */
+    icon?: ReactNode;
+    badge?: ReactNode;
+    disabled?: boolean;
+    className?: string;
+    /**
+     * Accessible name, required whenever `label` is not plain readable text.
+     * Also used as the accessible name and the tooltip text while the Sidebar
+     * is collapsed to icons only.
+     */
+    ariaLabel?: string;
+}
+/** A real destination. Renders an anchor, or the consumer's `renderLink`. */
+export interface SidebarLinkItem extends SidebarItemBase {
+    type: "link";
+    /** Required — an item without a destination is an `action`, not a `link`. */
+    href: string;
+    target?: string;
+    rel?: string;
+    onSelect?: SidebarSelectHandler;
+}
+/** A command with no destination. Renders a native button, never an empty-fragment anchor. */
+export interface SidebarActionItem extends SidebarItemBase {
+    type: "action";
+    onSelect?: SidebarSelectHandler;
+}
+/** A parent whose children open and close. Renders an explicit toggle button. */
+export interface SidebarCollapsibleItem extends SidebarItemBase {
+    type: "collapsible";
+    children: SidebarItem[];
+}
+/**
+ * A visual section. Presentation only: never navigable, and only participates
+ * in expansion when `collapsible` is explicitly set — which is what the legacy
+ * `SidebarGroup` normalizes to.
+ */
+export interface SidebarGroupItem extends SidebarItemBase {
+    type: "group";
+    children: SidebarItem[];
+    collapsible?: boolean;
+}
+export interface SidebarDividerItem {
+    type: "divider";
+    key: string;
+    className?: string;
+}
+export type SidebarItem = SidebarLinkItem | SidebarActionItem | SidebarCollapsibleItem | SidebarGroupItem | SidebarDividerItem;
+/** Items that own a `children` array and therefore can contain a branch. */
+export type SidebarParentItem = SidebarCollapsibleItem | SidebarGroupItem;
+export declare function isSidebarParent(item: SidebarItem): item is SidebarParentItem;
+/**
+ * A `group` is expandable only when the consumer asked for it; a `collapsible`
+ * always is. Deliberately a plain boolean and not a type predicate: this is a
+ * runtime capability question, not a narrowing one — a non-expandable group is
+ * still a `SidebarParentItem`.
+ */
+export declare function isSidebarExpandable(item: SidebarItem): boolean;
+/**
+ * Additive adapter: turns the legacy `sections` shape into the recursive
+ * model so there is exactly one rendering path (doc section 20 — the Sidebar
+ * must not grow a second independent implementation for legacy input).
+ *
+ * A legacy leaf carrying a real `href` becomes a `link`; one without a
+ * destination becomes an `action` and renders as a button rather than the
+ * previous placeholder anchor (defect 8 — see the README migration notes).
+ */
+export declare function toSidebarItems(sections: readonly SidebarSection[]): SidebarItem[];
+/** Legacy `defaultOpen` groups, in declaration order, as Sidebar-level expanded keys. */
+export declare function legacyDefaultExpandedKeys(sections: readonly SidebarSection[]): string[];
+/**
+ * Legacy per-item `active` flags collapse into the single authoritative
+ * `activeKey`. Deliberately deterministic: the first flagged item in
+ * declaration order wins, so inconsistent caller-supplied flags degrade
+ * predictably instead of producing two simultaneously "active" rows.
+ */
+export declare function legacyActiveKey(sections: readonly SidebarSection[]): string | undefined;
+export interface SidebarNode {
+    item: SidebarItem;
+    key: string;
+    depth: number;
+    /** Ancestor keys, outermost first. */
+    ancestors: string[];
+    children: SidebarNode[];
+}
+export interface SidebarTree {
+    roots: SidebarNode[];
+    byKey: Map<string, SidebarNode>;
+    /** Every key in pre-order — the single source of deterministic key ordering. */
+    order: string[];
+    duplicateKeys: string[];
+}
+export declare function buildSidebarTree(items: readonly SidebarItem[]): SidebarTree;
+/** Orders arbitrary keys by their position in the tree, so callbacks are reproducible. */
+export declare function sortKeysByTreeOrder(order: readonly string[], keys: Iterable<string>): string[];
+export type SidebarExpandMode = "single" | "multiple";
+/**
+ * Authoritative expansion transition for the whole tree.
+ *
+ * - `multiple`: independent branches, which is exactly what the legacy
+ *   one-Accordion-per-group layout produced, so it stays the default.
+ * - `single`: opening a branch keeps only that branch's own ancestor chain,
+ *   closing every competing sibling at every level.
+ *
+ * Collapsing a branch also drops its descendants, so `expandedKeys` never
+ * reports a branch as open while that branch is not visible.
+ */
+export declare function toggleExpandedKey(tree: SidebarTree, current: readonly string[], key: string, mode: SidebarExpandMode): string[];
+/**
+ * Opens an ancestor chain without toggling anything.
+ *
+ * Used for route-driven expansion, which is a one-way "make this visible"
+ * request rather than a user toggle: it must never close the branch it was
+ * asked to open. `single` keeps only the requested chain, matching what
+ * `toggleExpandedKey` does when a branch is opened by hand, so a route change
+ * and a click leave the tree in the same shape.
+ */
+export declare function expandPath(tree: SidebarTree, current: readonly string[], path: readonly string[], mode: SidebarExpandMode): string[];
+/** True when two key lists describe the same expansion, order included. */
+export declare function sameExpandedKeys(a: readonly string[], b: readonly string[]): boolean;
+/** Ancestor keys of the active item — the "active branch" the UI highlights. */
+export declare function activeAncestorKeys(tree: SidebarTree, activeKey: string | undefined): string[];
+/**
+ * The subset of the active branch that can actually be opened.
+ *
+ * A non-interactive visual group is a caption, not a level of expansion: it has
+ * no toggle, no `aria-expanded` and no place in `expandedKeys`. Route-driven
+ * expansion therefore asks for this list, while highlighting still uses the
+ * full ancestor list above.
+ */
+export declare function activeExpandablePath(tree: SidebarTree, activeKey: string | undefined): string[];
+export {};