@bensdev/react-sidebar 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,262 @@
+import * as React from 'react';
+
+interface SidebarBadge {
+    content: React.ReactNode;
+    tone?: 'default' | 'accent' | 'danger' | 'success';
+    className?: string;
+}
+interface SidebarItemBase {
+    /** Stable key. Falls back to `href`, then to an index-based key. */
+    id?: string;
+    label?: React.ReactNode;
+    icon?: React.ReactNode;
+    /** A number/node renders as-is; a shaped badge gets tone-based coloring. */
+    badge?: React.ReactNode | SidebarBadge;
+    disabled?: boolean;
+    /** Removes the item from render entirely — the standard way to do role gating. */
+    hidden?: boolean;
+    /** Overrides the tooltip text shown in collapsed mode. `false` disables it. */
+    tooltip?: React.ReactNode | false;
+    className?: string;
+    /** Arbitrary payload echoed back in render callbacks. */
+    meta?: Record<string, unknown>;
+}
+interface ActiveContext {
+    currentPath: string;
+    item: SidebarLinkItem | SidebarGroupItem;
+    defaultIsActive: boolean;
+}
+interface SidebarLinkItem extends SidebarItemBase {
+    type?: 'link';
+    href: string;
+    /** Exact-match only, mirrors react-router's NavLink `end`. */
+    end?: boolean;
+    isActive?: boolean | ((ctx: ActiveContext) => boolean);
+    target?: React.HTMLAttributeAnchorTarget;
+    rel?: string;
+    /** Extra props forwarded to `linkComponent` (e.g. `{ replace: true }`, `{ prefetch: false }`). */
+    linkProps?: Record<string, unknown>;
+    onClick?: (e: React.MouseEvent<HTMLElement>) => void;
+}
+interface SidebarActionItem extends SidebarItemBase {
+    type: 'action';
+    onSelect: (e: React.MouseEvent<HTMLButtonElement>) => void;
+    selected?: boolean;
+}
+interface SidebarGroupItem extends SidebarItemBase {
+    type: 'group';
+    items: SidebarItem[];
+    /** `false` renders a static section: label as heading, children always visible. */
+    collapsible?: boolean;
+    defaultOpen?: boolean;
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    href?: string;
+    end?: boolean;
+    isActive?: boolean | ((ctx: ActiveContext) => boolean);
+}
+interface SidebarHeadingItem {
+    type: 'heading';
+    id?: string;
+    label: React.ReactNode;
+    hidden?: boolean;
+    className?: string;
+}
+interface SidebarDividerItem {
+    type: 'divider';
+    id?: string;
+    hidden?: boolean;
+    className?: string;
+}
+interface SidebarCustomItem {
+    type: 'custom';
+    id?: string;
+    hidden?: boolean;
+    render: (ctx: SidebarRenderContext) => React.ReactNode;
+}
+type SidebarItem = SidebarLinkItem | SidebarActionItem | SidebarGroupItem | SidebarHeadingItem | SidebarDividerItem | SidebarCustomItem;
+interface SidebarRenderContext {
+    collapsed: boolean;
+    isMobile: boolean;
+    colorScheme: 'light' | 'dark';
+    currentPath: string;
+    toggleCollapsed: () => void;
+    closeMobile: () => void;
+}
+interface RenderLinkArgs {
+    item: SidebarLinkItem;
+    href: string;
+    isActive: boolean;
+    className: string;
+    children: React.ReactNode;
+    props: React.AnchorHTMLAttributes<HTMLAnchorElement> & Record<string, unknown>;
+    ctx: SidebarRenderContext;
+}
+type SidebarSlot = 'root' | 'aside' | 'header' | 'brand' | 'logo' | 'title' | 'subtitle' | 'headerBadge' | 'nav' | 'list' | 'item' | 'itemActive' | 'itemDisabled' | 'itemIcon' | 'itemLabel' | 'badge' | 'group' | 'groupTrigger' | 'groupPanel' | 'groupChevron' | 'heading' | 'divider' | 'tooltip' | 'footer' | 'user' | 'avatar' | 'userName' | 'userMeta' | 'footerAction' | 'toggle' | 'backdrop' | 'drawer' | 'drawerClose';
+type SidebarClassNames = Partial<Record<SidebarSlot, string>>;
+interface SidebarSlots {
+    header?: React.ReactNode | ((ctx: SidebarRenderContext) => React.ReactNode);
+    footer?: React.ReactNode | ((ctx: SidebarRenderContext) => React.ReactNode);
+    navTop?: React.ReactNode | ((ctx: SidebarRenderContext) => React.ReactNode);
+    navBottom?: React.ReactNode | ((ctx: SidebarRenderContext) => React.ReactNode);
+    collapseIcon?: (collapsed: boolean) => React.ReactNode;
+    groupChevron?: (open: boolean) => React.ReactNode;
+    closeIcon?: React.ReactNode;
+    tooltip?: (item: SidebarItem) => React.ReactNode;
+    badge?: (badge: SidebarBadge, item: SidebarItem) => React.ReactNode;
+}
+interface StorageAdapter {
+    getItem: (key: string) => string | null;
+    setItem: (key: string, value: string) => void;
+    subscribe?: (cb: () => void) => () => void;
+}
+interface SidebarBrand {
+    /** Node placed inside the default 32px logo tile (e.g. a single letter). */
+    logo?: React.ReactNode;
+    /** Replaces the logo tile entirely with a custom node (e.g. an <img>). */
+    logoNode?: React.ReactNode;
+    title?: React.ReactNode;
+    subtitle?: React.ReactNode;
+    badge?: React.ReactNode | SidebarBadge;
+    href?: string;
+    onClick?: () => void;
+}
+interface SidebarUser {
+    name?: React.ReactNode;
+    email?: React.ReactNode;
+    avatarUrl?: string;
+    avatar?: React.ReactNode;
+    /** Initials shown when there's no avatar and `name` isn't derivable (e.g. a ReactNode name). */
+    fallbackInitials?: string;
+}
+interface SidebarFooterAction {
+    icon: React.ReactNode;
+    label: string;
+    onClick: () => void;
+}
+type SidebarTokens = Partial<Record<string, string | number>>;
+interface SidebarTheme {
+    light?: SidebarTokens;
+    dark?: SidebarTokens;
+    [key: string]: string | number | SidebarTokens | undefined;
+}
+interface SidebarHandle {
+    collapse(): void;
+    expand(): void;
+    toggleCollapsed(): void;
+    openMobile(): void;
+    closeMobile(): void;
+    element: HTMLElement | null;
+}
+interface SidebarProps {
+    items: SidebarItem[];
+    /** Full per-item override. Return `undefined` to fall through to the default row. */
+    renderItem?: (item: SidebarItem, ctx: SidebarRenderContext, defaultNode: React.ReactNode) => React.ReactNode | undefined;
+    slots?: SidebarSlots;
+    classNames?: SidebarClassNames;
+    currentPath?: string;
+    linkComponent?: React.ElementType;
+    hrefProp?: string;
+    renderLink?: (args: RenderLinkArgs) => React.ReactNode;
+    isItemActive?: (item: SidebarLinkItem, ctx: ActiveContext) => boolean | undefined;
+    exact?: boolean;
+    onItemClick?: (item: SidebarItem, e: React.MouseEvent) => void;
+    closeOnNavigate?: boolean;
+    collapsible?: boolean;
+    collapsed?: boolean;
+    defaultCollapsed?: boolean;
+    onCollapsedChange?: (collapsed: boolean) => void;
+    persistCollapse?: boolean | string | StorageAdapter;
+    expandOnHover?: boolean;
+    showCollapseToggle?: boolean;
+    collapsedIconAlign?: 'start' | 'center';
+    collapsedFooter?: 'avatar' | 'stack' | 'hidden';
+    openGroups?: string[];
+    defaultOpenGroups?: string[];
+    onOpenGroupsChange?: (ids: string[]) => void;
+    accordion?: boolean;
+    autoOpenActiveGroup?: boolean;
+    collapsedGroupBehavior?: 'flyout' | 'expand' | 'ignore';
+    mobileOpen?: boolean;
+    onMobileClose?: () => void;
+    onMobileOpenChange?: (open: boolean) => void;
+    breakpoint?: number | string;
+    responsive?: boolean;
+    drawerWidth?: number | string;
+    closeOnEscape?: boolean;
+    closeOnBackdropClick?: boolean;
+    trapFocus?: boolean;
+    lockScroll?: boolean;
+    restoreFocus?: boolean;
+    portalTarget?: Element | (() => Element | null) | null;
+    disablePortal?: boolean;
+    brand?: SidebarBrand | React.ReactNode | ((ctx: SidebarRenderContext) => React.ReactNode);
+    user?: SidebarUser;
+    footerAction?: SidebarFooterAction | SidebarFooterAction[] | null;
+    header?: React.ReactNode | ((ctx: SidebarRenderContext) => React.ReactNode);
+    footer?: React.ReactNode | ((ctx: SidebarRenderContext) => React.ReactNode);
+    theme?: SidebarTheme;
+    colorScheme?: 'light' | 'dark' | 'auto';
+    width?: number | string;
+    collapsedWidth?: number | string;
+    position?: 'left' | 'right';
+    bordered?: boolean;
+    tooltips?: boolean;
+    reduceMotion?: boolean | 'auto';
+    toggleStrategy?: 'absolute' | 'fixed';
+    as?: React.ElementType;
+    id?: string;
+    className?: string;
+    style?: React.CSSProperties;
+    'aria-label'?: string;
+}
+
+declare const Sidebar: React.ForwardRefExoticComponent<SidebarProps & React.RefAttributes<SidebarHandle>>;
+
+declare function normalizePath(path: string): string;
+/** Reproduces react-router NavLink's `end` semantics without depending on react-router. */
+declare function defaultIsActive(href: string, currentPath: string, end?: boolean): boolean;
+/**
+ * Resolves whether a link or group item is active, honoring (in order):
+ * 1. `item.isActive` (boolean or predicate) — always wins.
+ * 2. `isItemActive` prop, if it returns something other than `undefined`.
+ * 3. `defaultIsActive(item.href, currentPath, item.end ?? exact)`.
+ */
+declare function resolveIsActive(item: SidebarLinkItem | SidebarGroupItem, currentPath: string, exact: boolean, isItemActive?: (item: SidebarLinkItem, ctx: ActiveContext) => boolean | undefined): boolean;
+
+/** Flattens a `theme` prop (with optional `light`/`dark` overrides) into inline CSS custom properties. */
+declare function themeToStyle(theme: SidebarTheme | undefined, scheme: 'light' | 'dark'): React.CSSProperties;
+
+/**
+ * `slate` is the identity theme — it matches the stylesheet's built-in defaults exactly.
+ * Useful for explicitness (`theme={slate}`) or as a base to spread over (`{ ...slate, ... }`).
+ */
+declare const slate: SidebarTheme;
+/**
+ * `greenMist` reproduces the original B-Lines sidebar palette pixel-for-pixel, including
+ * the app-wide dark-mode rule that softened `text-white` to `#e2e2e2`, and the project's
+ * custom border-radius scale (`rounded-lg` = 16px, `rounded-md` = 10px here, not Tailwind's
+ * defaults).
+ */
+declare const greenMist: SidebarTheme;
+/** A neutral dark theme — same shape language, palette independent of B-Lines. */
+declare const midnight: SidebarTheme;
+declare const themes: {
+    readonly slate: SidebarTheme;
+    readonly greenMist: SidebarTheme;
+    readonly midnight: SidebarTheme;
+};
+type ThemeName = keyof typeof themes;
+/** Identity helper — gives autocomplete/type-checking to a hand-written theme object. */
+declare function defineTheme(theme: SidebarTheme): SidebarTheme;
+
+interface IconProps extends React.SVGProps<SVGSVGElement> {
+    size?: number;
+}
+declare function ChevronLeftIcon({ size, ...rest }: IconProps): React.JSX.Element;
+declare function ChevronRightIcon({ size, ...rest }: IconProps): React.JSX.Element;
+declare function ChevronDownIcon({ size, ...rest }: IconProps): React.JSX.Element;
+declare function CloseIcon({ size, ...rest }: IconProps): React.JSX.Element;
+declare function MenuIcon({ size, ...rest }: IconProps): React.JSX.Element;
+
+export { type ActiveContext, ChevronDownIcon, ChevronLeftIcon, ChevronRightIcon, CloseIcon, MenuIcon, type RenderLinkArgs, Sidebar, type SidebarActionItem, type SidebarBadge, type SidebarBrand, type SidebarClassNames, type SidebarCustomItem, type SidebarDividerItem, type SidebarFooterAction, type SidebarGroupItem, type SidebarHandle, type SidebarHeadingItem, type SidebarItem, type SidebarLinkItem, type SidebarProps, type SidebarRenderContext, type SidebarSlot, type SidebarSlots, type SidebarTheme, type SidebarTokens, type SidebarUser, type StorageAdapter, type ThemeName, defaultIsActive, defineTheme, greenMist, midnight, normalizePath, resolveIsActive, slate, themeToStyle, themes };