@rqdhw3n/react-admin-layout 1.0.0 → 1.0.2

package/dist/index.d.cts

@@ -0,0 +1,327 @@
+import { ClassValue } from 'clsx';
+import { CSSProperties } from 'react';
+import { JSX } from 'react/jsx-runtime';
+import { LucideIcon } from 'lucide-react';
+import { ReactNode } from 'react';
+
+export declare function AdminLayout(props: AdminLayoutProps): JSX.Element;
+
+export declare interface AdminLayoutColors {
+    primary?: string;
+    secondary?: string;
+    background?: string;
+    surface?: string;
+    text?: string;
+    textSecondary?: string;
+    sidebarBackground?: string;
+    sidebarText?: string;
+    headerBackground?: string;
+    headerText?: string;
+    hoverBackground?: string;
+    hoverText?: string;
+    activeBackground?: string;
+    activeText?: string;
+    border?: string;
+    /** Foreground on brand-colored logos and avatars. */
+    onPrimary?: string;
+    danger?: string;
+    onDanger?: string;
+    overlay?: string;
+}
+
+export declare const adminLayoutPresets: Readonly<Record<AdminLayoutStyle, Readonly<AdminLayoutTheme>>>;
+
+export declare type AdminLayoutProps = {
+    children: ReactNode;
+    sidebarItems: SidebarItemType[];
+    appName?: string;
+    appLogo?: ReactNode;
+    user?: AdminUser;
+    notifications?: NotificationItem[];
+    permissions?: PermissionsMap;
+    breadcrumbs?: BreadcrumbItem[];
+    footer?: ReactNode;
+    showFooter?: boolean;
+    showSearch?: boolean;
+    searchPlaceholder?: string;
+    onSearch?: (query: string) => void;
+    defaultCollapsed?: boolean;
+    initialDarkMode?: boolean;
+    theme?: AdminLayoutTheme;
+    /** Required to let ThemeToggle change a controlled theme.mode. */
+    onThemeModeChange?: (mode: AdminLayoutThemeMode) => void;
+    storageKey?: string;
+    className?: string;
+    contentClassName?: string;
+    activePath?: string;
+    onNavigate?: (path: string) => void;
+    LinkComponent?: SidebarProps['LinkComponent'];
+    enableRouter?: boolean;
+};
+
+export declare type AdminLayoutResolvedMode = Exclude<AdminLayoutThemeMode, 'system'>;
+
+export declare function AdminLayoutRouterSync({ children }: AdminLayoutRouterSyncProps): JSX.Element;
+
+declare type AdminLayoutRouterSyncProps = {
+    children: ReactNode;
+};
+
+export declare type AdminLayoutStyle = 'modern' | 'minimal' | 'compact';
+
+export declare interface AdminLayoutTheme {
+    mode?: AdminLayoutThemeMode;
+    style?: AdminLayoutStyle;
+    colors?: AdminLayoutColors;
+    light?: AdminLayoutColors;
+    dark?: AdminLayoutColors;
+}
+
+export declare type AdminLayoutThemeMode = 'light' | 'dark' | 'system';
+
+export declare type AdminUser = {
+    name: string;
+    email: string;
+    avatar?: string;
+};
+
+export declare type BreadcrumbItem = {
+    label: string;
+    path?: string;
+};
+
+export declare function Breadcrumbs({ items, className, LinkComponent, onNavigate, }: BreadcrumbsProps): JSX.Element | null;
+
+export declare type BreadcrumbsProps = {
+    items: BreadcrumbItem[];
+    className?: string;
+    LinkComponent?: React.ComponentType<{
+        to: string;
+        className?: string;
+        children: React.ReactNode;
+    }>;
+    onNavigate?: (path: string) => void;
+};
+
+export declare function cn(...inputs: ClassValue[]): string;
+
+export declare const darkThemeColors: Readonly<Required<AdminLayoutColors>>;
+
+export declare function filterSidebarByPermissions(items: SidebarItemType[], permissions: PermissionsMap): SidebarItemType[];
+
+export declare function Footer({ children, className }: FooterProps): JSX.Element;
+
+export declare type FooterProps = {
+    children?: React.ReactNode;
+    className?: string;
+};
+
+export declare function generateBreadcrumbsFromPath(pathname: string): BreadcrumbItem[];
+
+export declare function hasPermission(permissions: PermissionsMap, permission?: string): boolean;
+
+export declare type LayoutContextValue = LayoutState & {
+    toggleSidebar: () => void;
+    setSidebarCollapsed: (v: boolean) => void;
+    toggleMobile: () => void;
+    setMobileOpen: (v: boolean) => void;
+    toggleDarkMode: () => void;
+    setDarkMode: (v: boolean) => void;
+    permissions: PermissionsMap;
+    breadcrumbs: BreadcrumbItem[];
+    setBreadcrumbs: (items: BreadcrumbItem[]) => void;
+    activePath: string;
+    setActivePath: (path: string) => void;
+};
+
+export declare function LayoutProvider({ children, storageKey, defaultCollapsed, permissions, initialBreadcrumbs, initialActivePath, initialDarkMode, theme, onThemeModeChange, }: LayoutProviderProps): JSX.Element;
+
+export declare type LayoutProviderProps = {
+    children: ReactNode;
+    storageKey?: string;
+    defaultCollapsed?: boolean;
+    permissions?: PermissionsMap;
+    initialBreadcrumbs?: BreadcrumbItem[];
+    initialActivePath?: string;
+    initialDarkMode?: boolean;
+    theme?: AdminLayoutTheme;
+    onThemeModeChange?: (mode: AdminLayoutThemeMode) => void;
+};
+
+export declare type LayoutState = {
+    sidebarCollapsed: boolean;
+    mobileOpen: boolean;
+    darkMode: boolean;
+};
+
+export declare const lightThemeColors: Readonly<Required<AdminLayoutColors>>;
+
+export declare function MobileSidebar({ items, appName, appLogo, onNavigate, activePath: activePathProp, LinkComponent, }: MobileSidebarProps): JSX.Element | null;
+
+export declare type MobileSidebarProps = SidebarProps;
+
+export declare function Navbar({ user, notifications, onSearch, searchPlaceholder, showSearch, className, breadcrumbs, onMenuClick, sidebarCollapsed, onToggleSidebar, }: NavbarProps): JSX.Element;
+
+export declare type NavbarProps = {
+    appName?: string;
+    user?: AdminUser;
+    notifications?: NotificationItem[];
+    onSearch?: (query: string) => void;
+    searchPlaceholder?: string;
+    showSearch?: boolean;
+    className?: string;
+    breadcrumbs?: BreadcrumbItem[];
+    onMenuClick?: () => void;
+    sidebarCollapsed?: boolean;
+    onToggleSidebar?: () => void;
+};
+
+export declare function NavbarSearch({ placeholder, onSearch, className, }: NavbarSearchProps): JSX.Element;
+
+export declare type NavbarSearchProps = {
+    placeholder?: string;
+    onSearch?: (query: string) => void;
+    className?: string;
+};
+
+export declare type NotificationItem = {
+    id: string;
+    title: string;
+    description?: string;
+    time?: string;
+    read?: boolean;
+};
+
+export declare function NotificationMenu({ notifications, className }: NotificationMenuProps): JSX.Element;
+
+export declare type NotificationMenuProps = {
+    notifications?: NotificationItem[];
+    className?: string;
+};
+
+export declare type PermissionsMap = Record<string, string[]>;
+
+export declare interface ResolvedAdminLayoutTheme {
+    mode: AdminLayoutResolvedMode;
+    style: AdminLayoutStyle;
+    colors: Required<AdminLayoutColors>;
+}
+
+/** Defaults < generic colors < selected mode colors. Undefined values never erase defaults. */
+export declare function resolveTheme(theme?: AdminLayoutTheme, systemMode?: AdminLayoutResolvedMode): ResolvedAdminLayoutTheme;
+
+export declare function RouterLink({ to, className, children, onClick }: RouterLinkProps): JSX.Element;
+
+declare type RouterLinkProps = {
+    to: string;
+    className?: string;
+    children: ReactNode;
+    onClick?: () => void;
+};
+
+export declare function Sidebar({ items, collapsed: collapsedProp, appName, appLogo, className, onNavigate, activePath: activePathProp, LinkComponent, }: SidebarProps): JSX.Element;
+
+export declare function SidebarGroup({ label, children, collapsed, className }: SidebarGroupProps): JSX.Element;
+
+export declare type SidebarGroupProps = {
+    label?: string;
+    children: ReactNode;
+    collapsed?: boolean;
+    className?: string;
+};
+
+export declare function SidebarItem({ item, collapsed, depth, activePath, onNavigate, LinkComponent, onItemClick, }: SidebarItemProps): JSX.Element;
+
+export declare type SidebarItemProps = {
+    item: SidebarItemType;
+    collapsed?: boolean;
+    depth?: number;
+    activePath?: string;
+    onNavigate?: (path: string) => void;
+    LinkComponent?: React.ComponentType<{
+        to: string;
+        className?: string;
+        children: React.ReactNode;
+        onClick?: () => void;
+    }>;
+    onItemClick?: () => void;
+};
+
+export declare type SidebarItemType = {
+    label: string;
+    path?: string;
+    icon?: LucideIcon;
+    badge?: number | string;
+    permission?: string;
+    children?: SidebarItemType[];
+    disabled?: boolean;
+};
+
+export declare type SidebarProps = {
+    items: SidebarItemType[];
+    collapsed?: boolean;
+    appName?: string;
+    appLogo?: ReactNode;
+    className?: string;
+    onNavigate?: (path: string) => void;
+    activePath?: string;
+    LinkComponent?: React.ComponentType<{
+        to: string;
+        className?: string;
+        children: ReactNode;
+        onClick?: () => void;
+    }>;
+};
+
+/** Apply once at a layout boundary; every descendant inherits the palette. */
+export declare function themeToCSSVariables(theme: ResolvedAdminLayoutTheme): CSSProperties;
+
+export declare function ThemeToggle({ className }: ThemeToggleProps): JSX.Element;
+
+export declare type ThemeToggleProps = {
+    className?: string;
+};
+
+export declare function useAdminLayoutTheme(): {
+    mode: AdminLayoutThemeMode;
+    resolvedMode: AdminLayoutResolvedMode;
+    style: AdminLayoutStyle;
+    colors: Required<AdminLayoutColors>;
+    setMode: (mode: AdminLayoutThemeMode) => void;
+};
+
+export declare function useBreadcrumbs(): {
+    items: BreadcrumbItem[];
+    setBreadcrumbs: (items: BreadcrumbItem[]) => void;
+};
+
+export declare function useDarkMode(): {
+    isDark: boolean;
+    toggle: () => void;
+    setDarkMode: (v: boolean) => void;
+};
+
+export declare function useLayoutContext(): LayoutContextValue;
+
+export declare function useLayoutState(): LayoutContextValue;
+
+export declare function UserMenu({ user, onLogout, onSettings, className }: UserMenuProps): JSX.Element;
+
+export declare type UserMenuProps = {
+    user: AdminUser;
+    onLogout?: () => void;
+    onSettings?: () => void;
+    className?: string;
+};
+
+export declare function useSidebar(): {
+    collapsed: boolean;
+    mobileOpen: boolean;
+    toggle: () => void;
+    setCollapsed: (v: boolean) => void;
+    toggleMobile: () => void;
+    setMobileOpen: (v: boolean) => void;
+    closeMobile: () => void;
+};
+
+export { }

package/dist/index.d.ts

@@ -1,10 +1,36 @@
 import { ClassValue } from 'clsx';
+import { CSSProperties } from 'react';
 import { JSX } from 'react/jsx-runtime';
 import { LucideIcon } from 'lucide-react';
 import { ReactNode } from 'react';
 
 export declare function AdminLayout(props: AdminLayoutProps): JSX.Element;
 
+export declare interface AdminLayoutColors {
+    primary?: string;
+    secondary?: string;
+    background?: string;
+    surface?: string;
+    text?: string;
+    textSecondary?: string;
+    sidebarBackground?: string;
+    sidebarText?: string;
+    headerBackground?: string;
+    headerText?: string;
+    hoverBackground?: string;
+    hoverText?: string;
+    activeBackground?: string;
+    activeText?: string;
+    border?: string;
+    /** Foreground on brand-colored logos and avatars. */
+    onPrimary?: string;
+    danger?: string;
+    onDanger?: string;
+    overlay?: string;
+}
+
+export declare const adminLayoutPresets: Readonly<Record<AdminLayoutStyle, Readonly<AdminLayoutTheme>>>;
+
 export declare type AdminLayoutProps = {
     children: ReactNode;
     sidebarItems: SidebarItemType[];
@@ -21,6 +47,9 @@ export declare type AdminLayoutProps = {
     onSearch?: (query: string) => void;
     defaultCollapsed?: boolean;
     initialDarkMode?: boolean;
+    theme?: AdminLayoutTheme;
+    /** Required to let ThemeToggle change a controlled theme.mode. */
+    onThemeModeChange?: (mode: AdminLayoutThemeMode) => void;
     storageKey?: string;
     className?: string;
     contentClassName?: string;
@@ -30,12 +59,26 @@ export declare type AdminLayoutProps = {
     enableRouter?: boolean;
 };
 
+export declare type AdminLayoutResolvedMode = Exclude<AdminLayoutThemeMode, 'system'>;
+
 export declare function AdminLayoutRouterSync({ children }: AdminLayoutRouterSyncProps): JSX.Element;
 
 declare type AdminLayoutRouterSyncProps = {
     children: ReactNode;
 };
 
+export declare type AdminLayoutStyle = 'modern' | 'minimal' | 'compact';
+
+export declare interface AdminLayoutTheme {
+    mode?: AdminLayoutThemeMode;
+    style?: AdminLayoutStyle;
+    colors?: AdminLayoutColors;
+    light?: AdminLayoutColors;
+    dark?: AdminLayoutColors;
+}
+
+export declare type AdminLayoutThemeMode = 'light' | 'dark' | 'system';
+
 export declare type AdminUser = {
     name: string;
     email: string;
@@ -62,6 +105,8 @@ export declare type BreadcrumbsProps = {
 
 export declare function cn(...inputs: ClassValue[]): string;
 
+export declare const darkThemeColors: Readonly<Required<AdminLayoutColors>>;
+
 export declare function filterSidebarByPermissions(items: SidebarItemType[], permissions: PermissionsMap): SidebarItemType[];
 
 export declare function Footer({ children, className }: FooterProps): JSX.Element;
@@ -89,9 +134,9 @@ export declare type LayoutContextValue = LayoutState & {
     setActivePath: (path: string) => void;
 };
 
-export declare function LayoutProvider({ children, storageKey, defaultCollapsed, permissions, initialBreadcrumbs, initialActivePath, initialDarkMode, }: LayoutProviderProps): JSX.Element;
+export declare function LayoutProvider({ children, storageKey, defaultCollapsed, permissions, initialBreadcrumbs, initialActivePath, initialDarkMode, theme, onThemeModeChange, }: LayoutProviderProps): JSX.Element;
 
-declare type LayoutProviderProps = {
+export declare type LayoutProviderProps = {
     children: ReactNode;
     storageKey?: string;
     defaultCollapsed?: boolean;
@@ -99,6 +144,8 @@ declare type LayoutProviderProps = {
     initialBreadcrumbs?: BreadcrumbItem[];
     initialActivePath?: string;
     initialDarkMode?: boolean;
+    theme?: AdminLayoutTheme;
+    onThemeModeChange?: (mode: AdminLayoutThemeMode) => void;
 };
 
 export declare type LayoutState = {
@@ -107,6 +154,8 @@ export declare type LayoutState = {
     darkMode: boolean;
 };
 
+export declare const lightThemeColors: Readonly<Required<AdminLayoutColors>>;
+
 export declare function MobileSidebar({ items, appName, appLogo, onNavigate, activePath: activePathProp, LinkComponent, }: MobileSidebarProps): JSX.Element | null;
 
 export declare type MobileSidebarProps = SidebarProps;
@@ -152,6 +201,15 @@ export declare type NotificationMenuProps = {
 
 export declare type PermissionsMap = Record<string, string[]>;
 
+export declare interface ResolvedAdminLayoutTheme {
+    mode: AdminLayoutResolvedMode;
+    style: AdminLayoutStyle;
+    colors: Required<AdminLayoutColors>;
+}
+
+/** Defaults < generic colors < selected mode colors. Undefined values never erase defaults. */
+export declare function resolveTheme(theme?: AdminLayoutTheme, systemMode?: AdminLayoutResolvedMode): ResolvedAdminLayoutTheme;
+
 export declare function RouterLink({ to, className, children, onClick }: RouterLinkProps): JSX.Element;
 
 declare type RouterLinkProps = {
@@ -215,12 +273,23 @@ export declare type SidebarProps = {
     }>;
 };
 
+/** Apply once at a layout boundary; every descendant inherits the palette. */
+export declare function themeToCSSVariables(theme: ResolvedAdminLayoutTheme): CSSProperties;
+
 export declare function ThemeToggle({ className }: ThemeToggleProps): JSX.Element;
 
 export declare type ThemeToggleProps = {
     className?: string;
 };
 
+export declare function useAdminLayoutTheme(): {
+    mode: AdminLayoutThemeMode;
+    resolvedMode: AdminLayoutResolvedMode;
+    style: AdminLayoutStyle;
+    colors: Required<AdminLayoutColors>;
+    setMode: (mode: AdminLayoutThemeMode) => void;
+};
+
 export declare function useBreadcrumbs(): {
     items: BreadcrumbItem[];
     setBreadcrumbs: (items: BreadcrumbItem[]) => void;