beez-ui 0.9.1 → 0.11.0

package/dist/components/sidebar.d.ts

@@ -1,71 +1,195 @@
+/**
+ * Animated application sidebar adapted from beui.dev/components/motion/animated-sidebar: the rail
+ * morphs its width with a spring, labels fade out of the icon rail, a shared pill follows the
+ * hovered and active items, submenus unfold with a stagger, and small screens get a focus-trapped
+ * sheet. Links route through the `BeezUIProvider` adapter and the open state keeps the
+ * `sidebar_state` cookie contract read by server entrypoints.
+ */
 import * as React from "react";
-import { type VariantProps } from "class-variance-authority";
-import { Button } from "./button.js";
-import { Input } from "./input.js";
-import { Separator } from "./separator.js";
-import { TooltipContent } from "./tooltip.js";
-type SidebarContextProps = {
-    state: "expanded" | "collapsed";
+import { type HTMLMotionProps } from "motion/react";
+import { type SidebarPanelState } from "./sidebar-panel-context.js";
+type SidebarState = "expanded" | "collapsed";
+type SidebarSide = "left" | "right";
+type SidebarVariant = "sidebar" | "floating" | "inset";
+type SidebarCollapsible = "offcanvas" | "icon" | "none";
+type SidebarLinkTarget = "_blank" | "_self" | "_parent" | "_top";
+type SidebarContextValue = {
+    isMobile: boolean;
+    layoutId: string;
+    /** Sheet width; the sheet is portaled outside the wrapper that declares the CSS variables. */
+    mobileWidth: string;
     open: boolean;
-    setOpen: (open: boolean) => void;
     openMobile: boolean;
+    reduce: boolean;
+    setOpen: (open: boolean) => void;
     setOpenMobile: (open: boolean) => void;
-    isMobile: boolean;
+    state: SidebarState;
     toggleSidebar: () => void;
+    triggerRef: React.RefObject<HTMLButtonElement | null>;
 };
-declare function useSidebar(): SidebarContextProps;
-declare function SidebarProvider({ defaultOpen, storageKey, open: openProp, onOpenChange: setOpenProp, className, style, children, ...props }: React.ComponentProps<"div"> & {
+/**
+ * Reads the sidebar state shared by `SidebarProvider`.
+ * @returns Open state for desktop and mobile, viewport and motion flags, and state setters.
+ */
+declare function useSidebar(): SidebarContextValue;
+/**
+ * Reads the state of the enclosing `Sidebar` panel, so product content can adapt to the icon rail
+ * without depending on its DOM attributes.
+ * @returns Whether the panel is collapsed to its icon rail (always false in the mobile sheet), its
+ * collapse mode and its side.
+ */
+declare function useSidebarPanel(): SidebarPanelState;
+type SidebarProviderStyle = React.CSSProperties & {
+    "--sidebar-width"?: string;
+    "--sidebar-width-icon"?: string;
+    "--sidebar-width-mobile"?: string;
+};
+export type SidebarProviderProps = React.ComponentProps<"div"> & {
+    /** Controlled desktop state. */
+    open?: boolean;
+    /** Desktop state before any interaction; server entrypoints pass the `sidebar_state` cookie here. */
     defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** Controlled state of the small-screen sheet. */
+    openMobile?: boolean;
+    defaultOpenMobile?: boolean;
+    onOpenMobileChange?: (open: boolean) => void;
     /** Opts into local persistence without changing the shared SSR cookie contract. */
     storageKey?: string;
-    open?: boolean;
-    onOpenChange?: (open: boolean) => void;
-}): React.JSX.Element;
-declare function Sidebar({ side, variant, collapsible, className, children, dir, ...props }: React.ComponentProps<"div"> & {
-    side?: "left" | "right";
-    variant?: "sidebar" | "floating" | "inset";
-    collapsible?: "offcanvas" | "icon" | "none";
-}): React.JSX.Element;
-declare function SidebarTrigger({ className, onClick, ...props }: React.ComponentProps<typeof Button>): React.JSX.Element;
-declare function SidebarRail({ className, ...props }: React.ComponentProps<"button">): React.JSX.Element;
-declare function SidebarInset({ className, ...props }: React.ComponentProps<"main">): React.JSX.Element;
-declare function SidebarInput({ className, ...props }: React.ComponentProps<typeof Input>): React.JSX.Element;
+    /** Cookie that keeps the desktop state for server entrypoints; defaults to `sidebar_state`. */
+    cookieName?: string;
+    /** Lifetime of that cookie in seconds; defaults to seven days. */
+    cookieMaxAge?: number;
+    style?: SidebarProviderStyle;
+};
+/**
+ * Owns the open state of the sidebar, the ⌘B / Ctrl+B shortcut and the layout wrapper.
+ * @param props - Controlled or default state for both viewports, persistence options and wrapper attributes.
+ * @returns The wrapper that lays out the sidebar next to its inset.
+ */
+declare function SidebarProvider({ children, open: openProp, defaultOpen, onOpenChange, openMobile: openMobileProp, defaultOpenMobile, onOpenMobileChange, storageKey, cookieName, cookieMaxAge, className, style, ...props }: SidebarProviderProps): React.JSX.Element;
+export type SidebarProps = Omit<HTMLMotionProps<"aside">, "children"> & {
+    children?: React.ReactNode;
+    side?: SidebarSide;
+    variant?: SidebarVariant;
+    /** `icon` shrinks to an icon rail, `offcanvas` slides away, `none` stays expanded on every viewport. */
+    collapsible?: SidebarCollapsible;
+    ariaLabel?: string;
+    /** Classes of the inner panel that paints the sidebar surface. */
+    panelClassName?: string;
+};
+/**
+ * Renders the sidebar: a width-morphing rail on desktop and a sheet on small screens.
+ * @param props - Side, variant, collapse mode, accessible name and panel classes.
+ * @returns The desktop rail, the mobile sheet portal, or an always-expanded panel.
+ */
+declare function Sidebar({ side, variant, collapsible, ariaLabel, children, className, panelClassName, style, ...props }: SidebarProps): React.JSX.Element;
+/**
+ * Button that toggles the desktop rail or the mobile sheet; shows a panel icon unless given children.
+ * @param props - Native button attributes.
+ * @returns The toggle button.
+ */
+declare function SidebarTrigger({ children, className, onClick, ref, type, ...props }: React.ComponentProps<"button">): React.JSX.Element;
+/**
+ * Button that closes the sidebar on the current viewport.
+ * @param props - Native button attributes; the content is the consumer's icon or text.
+ * @returns The close button.
+ */
+declare function SidebarClose({ className, onClick, type, ...props }: React.ComponentProps<"button">): React.JSX.Element;
+/**
+ * Thin hit area on the sidebar edge that toggles it with the pointer.
+ * @param props - Native button attributes.
+ * @returns The rail button, outside the tab order.
+ */
+declare function SidebarRail({ className, onClick, type, ...props }: React.ComponentProps<"button">): React.JSX.Element;
+/**
+ * Main content area laid out next to the sidebar.
+ * @param props - Motion-enabled `main` attributes.
+ * @returns The content landmark.
+ */
+declare function SidebarInset({ className, ...props }: HTMLMotionProps<"main">): React.JSX.Element;
 declare function SidebarHeader({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
-declare function SidebarFooter({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
-declare function SidebarSeparator({ className, ...props }: React.ComponentProps<typeof Separator>): React.JSX.Element;
 declare function SidebarContent({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
-declare function SidebarGroup({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
-declare function SidebarGroupLabel({ className, asChild, ...props }: React.ComponentProps<"div"> & {
-    asChild?: boolean;
-}): React.JSX.Element;
-declare function SidebarGroupAction({ className, asChild, ...props }: React.ComponentProps<"button"> & {
+declare function SidebarFooter({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+export type SidebarLabelProps = React.ComponentProps<"span"> & {
+    /** Renders the child element instead of a `span`, for example a paragraph. */
     asChild?: boolean;
-}): React.JSX.Element;
+};
+/**
+ * Product text that only makes sense in the expanded sidebar, such as a workspace name or an empty
+ * state: it leaves the layout while the panel is the icon rail and always shows in the mobile sheet.
+ * @param props - Span attributes, or `asChild` to keep the child element.
+ * @returns The content, or nothing in the icon rail.
+ */
+declare function SidebarLabel({ asChild, ...props }: SidebarLabelProps): React.JSX.Element | null;
+export type SidebarBrandButtonProps = React.ComponentProps<"button"> & {
+    /** Square tile such as a logo or initials; it stays visible in the icon rail. */
+    icon: React.ReactNode;
+    /** Trailing affordance such as a chevron, hidden in the icon rail. */
+    trailing?: React.ReactNode;
+};
+/**
+ * Header row that identifies the workspace, often the trigger of a workspace switcher. It forwards
+ * its props and ref to the `button`, so it works as `DropdownMenuTrigger asChild`, and keeps its tile
+ * on the menu icon column while the label and trailing content leave in the icon rail.
+ * @param props - Tile, label, trailing content and native button attributes.
+ * @returns The brand button.
+ */
+declare function SidebarBrandButton({ icon, trailing, children, className, type, ...props }: SidebarBrandButtonProps): React.JSX.Element;
+declare function SidebarGroup({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+/** Section heading that fades out of the icon rail and is hidden from assistive technology there. */
+declare function SidebarGroupLabel({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
 declare function SidebarGroupContent({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+/** Menu list whose items share a hover pill that glides between them. */
 declare function SidebarMenu({ className, ...props }: React.ComponentProps<"ul">): React.JSX.Element;
-declare function SidebarMenuItem({ className, ...props }: React.ComponentProps<"li">): React.JSX.Element;
-declare const sidebarMenuButtonVariants: (props?: ({
-    variant?: "default" | "outline" | null | undefined;
-    size?: "default" | "lg" | "sm" | null | undefined;
-} & import("class-variance-authority/types").ClassProp) | undefined) => string;
-declare function SidebarMenuButton({ asChild, isActive, variant, size, tooltip, className, ...props }: React.ComponentProps<"button"> & {
-    asChild?: boolean;
-    isActive?: boolean;
-    tooltip?: string | React.ComponentProps<typeof TooltipContent>;
-} & VariantProps<typeof sidebarMenuButtonVariants>): React.JSX.Element;
-declare function SidebarMenuAction({ className, asChild, showOnHover, ...props }: React.ComponentProps<"button"> & {
-    asChild?: boolean;
-    showOnHover?: boolean;
-}): React.JSX.Element;
-declare function SidebarMenuBadge({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
-declare function SidebarMenuSkeleton({ className, showIcon, ...props }: React.ComponentProps<"div"> & {
-    showIcon?: boolean;
-}): React.JSX.Element;
-declare function SidebarMenuSub({ className, ...props }: React.ComponentProps<"ul">): React.JSX.Element;
-declare function SidebarMenuSubItem({ className, ...props }: React.ComponentProps<"li">): React.JSX.Element;
-declare function SidebarMenuSubButton({ asChild, size, isActive, className, ...props }: React.ComponentProps<"a"> & {
-    asChild?: boolean;
-    size?: "sm" | "md";
+declare function SidebarMenuItem({ className, ...props }: HTMLMotionProps<"li">): React.JSX.Element;
+export type SidebarMenuSubProps = Omit<HTMLMotionProps<"ul">, "children"> & {
+    /** Whether the submenu is unfolded; it never renders inside the icon rail. */
+    open: boolean;
+    children?: React.ReactNode;
+};
+/**
+ * Nested list that unfolds with a clip and staggered items.
+ * @param props - Open state and motion-enabled list attributes.
+ * @returns The submenu while open and the sidebar is expanded.
+ */
+declare function SidebarMenuSub({ open, children, className, ...props }: SidebarMenuSubProps): React.JSX.Element;
+declare function SidebarMenuSubItem({ className, ...props }: HTMLMotionProps<"li">): React.JSX.Element;
+type SidebarActionProps = {
+    children: React.ReactNode;
+    icon?: React.ReactNode;
+    /** Renders a link through the `BeezUIProvider` routing adapter instead of a button. */
+    href?: string;
     isActive?: boolean;
-}): React.JSX.Element;
-export { Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupAction, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInput, SidebarInset, SidebarMenu, SidebarMenuAction, SidebarMenuBadge, SidebarMenuButton, SidebarMenuItem, SidebarMenuSkeleton, SidebarMenuSub, SidebarMenuSubButton, SidebarMenuSubItem, SidebarProvider, SidebarRail, SidebarSeparator, SidebarTrigger, useSidebar, };
+    disabled?: boolean;
+    target?: SidebarLinkTarget;
+    rel?: string;
+    onSelect?: () => void;
+    className?: string;
+};
+export type SidebarMenuSubButtonProps = SidebarActionProps & {
+    /** Closes the mobile sheet after selecting; on by default. */
+    closeOnSelect?: boolean;
+};
+/**
+ * Submenu entry; shows a dot when no icon is given.
+ * @param props - Label, icon, link or select handler, active and disabled state.
+ * @returns The submenu link or button.
+ */
+declare function SidebarMenuSubButton({ children, icon, href, isActive, disabled, closeOnSelect, target, rel, onSelect, className, }: SidebarMenuSubButtonProps): React.JSX.Element;
+export type SidebarMenuButtonProps = SidebarActionProps & {
+    /** Trailing content such as a counter, hidden in the icon rail. */
+    badge?: React.ReactNode;
+    /** Marks the button as a submenu toggle and shows a rotating chevron. */
+    ariaExpanded?: boolean;
+    /** Closes the mobile sheet after selecting; defaults to on, except for submenu toggles. */
+    closeOnSelect?: boolean;
+};
+/**
+ * Top-level menu entry: the active one carries a pill that glides between entries, and the label
+ * fades out of the icon rail, leaving a string label as accessible name and native tooltip.
+ * @param props - Label, icon, badge, link or select handler, submenu and active state.
+ * @returns The menu link or button.
+ */
+declare function SidebarMenuButton({ children, icon, badge, href, isActive, ariaExpanded, disabled, closeOnSelect, target, rel, onSelect, className, }: SidebarMenuButtonProps): React.JSX.Element;
+export { Sidebar, SidebarBrandButton, SidebarClose, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInset, SidebarLabel, SidebarMenu, SidebarMenuButton, SidebarMenuItem, SidebarMenuSub, SidebarMenuSubButton, SidebarMenuSubItem, SidebarProvider, SidebarRail, SidebarTrigger, useSidebar, useSidebarPanel, };