@konstructio/ui/dist/lib/components/Sidebar/Sidebar.types.d.ts

A set of reusable and customizable React components built for konstruct.io

import { VariantProps } from 'class-variance-authority';
import { CSSProperties, FC, PropsWithChildren } from 'react';
import { ClassNames as DrawerClassNames } from '../../../components/Drawer/Drawer.types';
import { Theme } from '../../../domain/theme';
import { SidebarModeProp } from './hooks/useSidebarMode';
import { wrapperSiderbarVariants } from './Sidebar.variants';
import { FooterProps, LabelProps, LogoProps, NavigationGroupProps, NavigationOptionProps, NavigationProps, NavigationSeparatorProps } from './components';
/**
 * Props for the Sidebar component.
 * A compound component for building application sidebars with navigation.
 *
 * @example
 * ```tsx
 * <Sidebar canResize minWith={200} maxWith={400}>
 *   <Sidebar.Logo>
 *     <img src="/logo.svg" alt="Logo" />
 *   </Sidebar.Logo>
 *   <Sidebar.Navigation>
 *     <Sidebar.NavigationGroup label="Main">
 *       <Sidebar.NavigationOption href="/dashboard" icon={<Home />}>
 *         Dashboard
 *       </Sidebar.NavigationOption>
 *       <Sidebar.NavigationOption href="/settings" icon={<Settings />}>
 *         Settings
 *       </Sidebar.NavigationOption>
 *     </Sidebar.NavigationGroup>
 *   </Sidebar.Navigation>
 *   <Sidebar.Footer>v1.0.0</Sidebar.Footer>
 * </Sidebar>
 * ```
 */
export interface Props extends Omit<VariantProps<typeof wrapperSiderbarVariants>, 'mode'>, PropsWithChildren {
    /** Whether the sidebar can be resized by dragging (only in expanded mode) */
    canResize?: boolean;
    /** Additional CSS classes for the divider */
    dividerClassName?: string;
    /**
     * Viewport width in pixels below which the sidebar switches to `drawer` mode in `auto` mode (defaults to 640).
     */
    drawerBreakpoint?: number;
    /**
     * Maximum width in pixels for the drawer panel in `drawer` mode (defaults to 280).
     * The drawer width is `min(viewport, drawerMaxWidth)`, so on viewports narrower than
     * the cap it shrinks to fit instead of overflowing.
     */
    drawerMaxWidth?: number;
    /**
     * Viewport width in pixels at or above which the sidebar switches to `expanded` mode in `auto` mode (defaults to 1024).
     */
    expandedBreakpoint?: number;
    /**
     * When true, animates the hover-expand width transition with `motion`. Only takes effect
     * together with `expandOnHover`. Defaults to `true`.
     */
    animateOnHover?: boolean;
    /**
     * When true and the sidebar is in `collapsed` mode, hovering a navigation option
     * expands only that option (animated width) to reveal its label. The expanded
     * option overlays content to its right and does not push siblings. Defaults to `true`.
     */
    expandOnHover?: boolean;
    /** Initial width in pixels when entering expanded mode (defaults to 256, clamped to [minWith, maxWith]) */
    initialWidth?: number;
    /** Maximum width when resizing in pixels (defaults to 300) */
    maxWith?: number;
    /** Minimum width when resizing in pixels (defaults to 240) */
    minWith?: number;
    /** Additional CSS classes for the auto-injected separator between groups in collapsed mode */
    separatorClassName?: string;
    /** Additional CSS classes for the hamburger trigger button rendered in drawer mode */
    triggerClassName?: string;
    /**
     * Per-slot class overrides for the underlying `Drawer` rendered in
     * `drawer` mode. Mirrors `Drawer`'s `classNames` shape: `root`, `overlay`,
     * `panel`, `closeButton`, `content`, `header`, `body`, `footer`,
     * `resizeHandle`. Useful for tweaking the close-button position, removing
     * the panel's horizontal padding so dividers can span edge-to-edge,
     * raising the root `z-index` past higher-z layers, etc.
     *
     * The Sidebar already applies sensible defaults internally (root `z-[60]`,
     * panel uses `wrapperClassName`, content `gap-0`); user-provided classes
     * are appended via `cn`, so they win on conflicts.
     */
    drawerClassNames?: DrawerClassNames;
    /**
     * Controls the responsive mode of the sidebar.
     * - `auto` (default): derives the mode from the viewport width
     *   (`>=1024px` expanded, `640-1023px` collapsed, `<640px` drawer).
     * - `expanded`, `collapsed`, `drawer`: force a specific mode
     *   (useful for testing, stories, or manual control).
     */
    mode?: SidebarModeProp;
    /**
     * SSR / first-paint hint for `auto` mode. `useMediaQuery` cannot run on
     * the server, so the resolved mode flickers from the desktop default to
     * the actual viewport-derived mode after hydration. Pass the last-known
     * mode (e.g. read from a cookie written by a prior client visit) to
     * make the SSR markup match the actual viewport on subsequent loads.
     * Ignored when `mode` is anything other than `auto`.
     */
    initialMode?: Exclude<SidebarModeProp, 'auto'>;
    /** Theme override for this component */
    theme?: Theme;
    /** Additional CSS classes for the wrapper */
    wrapperClassName?: string;
    /**
     * Inline styles applied to the wrapper `<aside>` (or the drawer panel in
     * drawer mode). Useful for setting CSS custom properties that drive
     * theming via the protection stylesheet (e.g.
     * `--konstruct-sidebar-hover-bg`, `--konstruct-sidebar-active-bg`),
     * since inline styles outrank un-layered utilities shipped by federated
     * remote micro-frontends.
     */
    style?: CSSProperties;
}
/** @deprecated Use Props instead */
export type SidebarProps = Props;
/**
 * Sidebar compound component type with sub-components.
 */
export type SidebarChildrenProps = {
    Footer: FC<FooterProps>;
    Label: FC<LabelProps>;
    Logo: FC<LogoProps>;
    Navigation: FC<NavigationProps>;
    NavigationGroup: FC<NavigationGroupProps>;
    NavigationOption: FC<NavigationOptionProps>;
    NavigationSeparator: FC<NavigationSeparatorProps>;
};