@stratakit/structures/dist/NavigationRail.d.ts

Medium-sized component structures for the Strata design system

import * as React from "react";
import type { BaseProps, FocusableProps } from "@stratakit/foundations/secret-internals";
interface NavigationRailRootInnerProps extends BaseProps<"nav"> {
}
interface NavigationRailRootProps extends NavigationRailRootInnerProps {
    /**
     * The initial expanded state of the `NavigationRail` when it is first rendered.
     *
     * This prop is recommended over `expanded` when you don't need to fully control the expanded
     * state from the outside.
     *
     * This prop will be ignored if the `expanded` prop is provided.
     *
     * @default false
     */
    defaultExpanded?: boolean;
    /**
     * Control whether the `NavigationRail` is expanded or collapsed.
     *
     * When `true`, the `NavigationRail` shows both icons and labels for its items.
     * When `false`, it shows only icons, with labels available as tooltips.
     *
     * This prop is optional; if not provided, the `NavigationRail` will manage its own state internally.
     *
     * This should be used in conjunction with the `setExpanded` prop to reflect internal state changes.
     */
    expanded?: boolean;
    /**
     * Callback that is called when the expanded state of the `NavigationRail` changes.
     *
     * This is useful for syncing the internal state of the `NavigationRail` with external state.
     */
    setExpanded?: (expanded: boolean) => void;
}
/**
 * The `NavigationRail` presents top-level navigation items in a vertical orientation.
 *
 * Example:
 * ```tsx
 * <NavigationRail.Root>
 *   <NavigationRail.Header>
 *     <IconButton label="Home" render={<a href="/" />}>
 *       <Icon href={applicationIcon} />
 *     </IconButton>
 *     <NavigationRail.ToggleButton />
 *   </NavigationRail.Header>
 *
 *   <NavigationRail.Content>
 *     <NavigationRail.List>
 *       <NavigationRail.ListItem>
 *         <NavigationRail.Anchor label="Dashboard" icon={dashboardIcon} href="/dashboard" />
 *       </NavigationRail.ListItem>
 *       <NavigationRail.ListItem>
 *         <NavigationRail.Anchor label="Projects" icon={projectsIcon} href="/projects" />
 *       </NavigationRail.ListItem>
 *       <NavigationRail.ListItem>
 *         <NavigationRail.Anchor label="Reports" icon={reportsIcon} href="/reports" />
 *       </NavigationRail.ListItem>
 *     </NavigationRail.List>
 *
 *     <NavigationRail.Footer>
 *       <NavigationRail.List>
 *         <NavigationRail.ListItem>
 *           <NavigationRail.Button label="Help" icon={helpIcon} onClick={…} />
 *         </NavigationRail.ListItem>
 *         <NavigationRail.ListItem>
 *           <NavigationRail.Button label="Settings" icon={settingsIcon} onClick={…} />
 *         </NavigationRail.ListItem>
 *         <NavigationRail.ListItem>
 *           <NavigationRail.Button label="Profile" icon={userIcon} onClick={…} />
 *         </NavigationRail.ListItem>
 *       </NavigationRail.List>
 *    </NavigationRail.Footer>
 *   </NavigationRail.Content>
 * </NavigationRail.Root>
 * ```
 */
declare const NavigationRailRoot: React.ForwardRefExoticComponent<NavigationRailRootProps & React.RefAttributes<HTMLElement>>;
interface NavigationRailHeaderProps extends BaseProps<"header"> {
}
/**
 * `NavigationRail.Header` represents the header (i.e. top) section of the `NavigationRail` and is
 * visually aligned with the page header next to it.
 *
 * Can contain a logo and a `NavigationRail.ToggleButton` to collapse/expand the `NavigationRail`.
 *
 * **Note**: This component is expected to hug the top edge of the page.
 */
declare const NavigationRailHeader: React.ForwardRefExoticComponent<NavigationRailHeaderProps & React.RefAttributes<HTMLElement>>;
interface NavigationRailToggleButtonProps extends Omit<FocusableProps<"button">, "children"> {
    /**
     * Customize the accessible label of the toggle button.
     *
     * @default "Expand navigation".
     */
    label?: string;
}
/**
 * `NavigationRail.ToggleButton` toggles the expanded/collapsed state of the `NavigationRail`.
 * It is typically placed inside `NavigationRail.Header`, next to the logo.
 *
 * When this button is clicked, it toggles the internal expanded state of the `NavigationRail`,
 * and also calls the `setExpanded` callback prop if provided, to allow syncing with external state.
 */
declare const NavigationRailToggleButton: React.ForwardRefExoticComponent<NavigationRailToggleButtonProps & React.RefAttributes<HTMLElement | HTMLButtonElement>>;
interface NavigationRailContentProps extends BaseProps {
}
/**
 * `NavigationRail.Content` is a wraps the main content of the `NavigationRail`, including
 * the primary navigation list and an optional footer.
 *
 * Example:
 * ```tsx
 * <NavigationRail.Content>
 *   <NavigationRail.List>…</NavigationRail.List>
 *
 *   <NavigationRail.Footer>
 *     <NavigationRail.List>…</NavigationRail.List>
 *   </NavigationRail.Footer>
 * </NavigationRail.Content>
 * ```
 */
declare const NavigationRailContent: React.ForwardRefExoticComponent<NavigationRailContentProps & React.RefAttributes<HTMLDivElement | HTMLElement>>;
interface NavigationRailListProps extends BaseProps<"div"> {
}
/**
 * The `NavigationRail.List` represents a list of top-level navigation items.
 *
 * It should be used within `NavigationRail.Content` and should contain `NavigationRail.ListItem` elements,
 * which in turn can contain `NavigationRail.Anchor` or `NavigationRail.Button`.
 *
 * Example (with `NavigationRail.Anchor`):
 * ```tsx
 * <NavigationRail.List>
 *   <NavigationRail.ListItem>
 *     <NavigationRail.Anchor label="Home" icon={homeIcon} href="/" />
 *   </NavigationRail.ListItem>
 *   <NavigationRail.ListItem>
 *     <NavigationRail.Anchor label="Projects" icon={projectsIcon} href="/projects" />
 *   </NavigationRail.ListItem>
 * </NavigationRail.List>
 * ```
 *
 * Example (with `NavigationRail.Button`):
 * ```tsx
 * <NavigationRail.List>
 *   <NavigationRail.ListItem>
 *     <NavigationRail.Button label="Help" icon={helpIcon} onClick={…} />
 *   </NavigationRail.ListItem>
 *   <NavigationRail.ListItem>
 *     <NavigationRail.Button label="Settings" icon={settingsIcon} onClick={…}  />
 *   </NavigationRail.ListItem>
 * </NavigationRail.List>
 * ```
 *
 * Multiple `NavigationRail.List` elements can be used together and be separated by a [`Divider`](https://stratakit.bentley.com/docs/components/divider/).
 */
declare const NavigationRailList: React.ForwardRefExoticComponent<NavigationRailListProps & React.RefAttributes<HTMLDivElement | HTMLElement>>;
interface NavigationRailListItemProps extends BaseProps<"div"> {
}
/**
 * The `NavigationRail.Item` represents a single navigation list item, which should contain
 * either a `NavigationRail.Anchor` or a `NavigationRail.Button`.
 *
 * Example:
 * ```tsx
 * <NavigationRail.ListItem>
 *   <NavigationRail.Anchor label="Home" icon={homeIcon} href="/" />
 * </NavigationRail.ListItem>
 * // or
 * <NavigationRail.ListItem>
 *   <NavigationRail.Button label="Settings" icon={settingsIcon} onClick={…} />
 * </NavigationRail.ListItem>
 * ```
 *
 * **Note:** This is a non-interactive wrapper element and should not directly handle user interactions.
 */
declare const NavigationRailListItem: React.ForwardRefExoticComponent<NavigationRailListItemProps & React.RefAttributes<HTMLDivElement | HTMLElement>>;
interface NavigationRailItemActionOwnProps {
    /**
     * Label for the navigation item action.
     *
     * Exposed as a tooltip when the navigation rail is collapsed.
     */
    label: string;
    /**
     * Icon for the navigation item action.
     *
     * Can be a URL of an SVG from the `@stratakit/icons` package,
     * or a custom JSX icon.
     */
    icon: string | React.JSX.Element;
    /**
     * Additional non-interactive content displayed at the end of the navigation item action.
     *
     * Displayed in a tooltip when the navigation rail is collapsed.
     *
     * The suffix is included in the accessible name of the item action.
     */
    suffix?: React.ReactNode;
}
interface NavigationRailAnchorProps extends Omit<BaseProps<"a">, "children">, NavigationRailItemActionOwnProps {
    /**
     * Whether the anchor is currently active (i.e. represents the current page).
     */
    active?: boolean;
}
/**
 * `NavigationRail.Anchor` is used for top-level navigation items that link to major pages.
 *
 * Should be used inside `NavigationRail.ListItem` and must have a short `label` and a recognizable `icon`.
 * The `label` will be shown as a tooltip when the `NavigationRail` is collapsed.
 *
 * Example:
 * ```tsx
 * <NavigationRail.ListItem>
 *   <NavigationRail.Anchor label="Home" icon={homeIcon} href="/" />
 * </NavigationRail.ListItem>
 * ```
 */
declare const NavigationRailAnchor: React.ForwardRefExoticComponent<NavigationRailAnchorProps & React.RefAttributes<HTMLElement | HTMLAnchorElement>>;
interface NavigationRailButtonProps extends Omit<BaseProps<"button">, "children">, NavigationRailItemActionOwnProps {
}
/**
 * `NavigationRail.Button` is used for actions that do not navigate to a new page, but rather perform
 * an in-page action, such as opening a dialog or menu.
 *
 * Should be used inside `NavigationRail.ListItem` and must have a short `label` and a recognizable `icon`.
 * The `label` will be shown as a tooltip when the `NavigationRail` is collapsed.
 *
 * Example:
 * ```tsx
 * <NavigationRail.ListItem>
 *   <NavigationRail.Button label="Notifications" icon={notificationsIcon} onClick={showNotificationsDialog} />
 * </NavigationRail.ListItem>
 * ```
 */
declare const NavigationRailButton: React.ForwardRefExoticComponent<NavigationRailButtonProps & React.RefAttributes<HTMLElement | HTMLButtonElement>>;
interface NavigationRailFooterProps extends BaseProps<"footer"> {
}
/**
 * `NavigationRail.Footer` is typically used for grouping secondary actions list near the bottom
 * of the `NavigationRail`, away from the main navigation items.
 *
 * Example:
 * ```tsx
 * <NavigationRail.Content>
 *   <NavigationRail.List>…</NavigationRail.List>
 *
 *   <NavigationRail.Footer>
 *     <NavigationRail.List>…</NavigationRail.List>
 *   </NavigationRail.Footer>
 * </NavigationRail.Content>
 * ```
 */
declare const NavigationRailFooter: React.ForwardRefExoticComponent<NavigationRailFooterProps & React.RefAttributes<HTMLElement>>;
export { NavigationRailAnchor as Anchor, NavigationRailButton as Button, NavigationRailContent as Content, NavigationRailFooter as Footer, NavigationRailHeader as Header, NavigationRailList as List, NavigationRailListItem as ListItem, NavigationRailRoot as Root, NavigationRailToggleButton as ToggleButton, };