@clayer/dashboard-layout 1.0.0

package/README.md

@@ -0,0 +1,164 @@
+# `@clayer/dashboard-layout`
+
+Reusable dashboard shell for React applications built on top of:
+
+- `@clayer/theme`
+- `@clayer/utils`
+
+This package intentionally does **not** depend on `@clayer/ui` yet.
+
+## Current Scope
+
+The package currently provides:
+
+- `DashboardLayout`
+- `DashboardShell`
+- `DashboardHeader`
+- `DashboardContent`
+- `DashboardFooter`
+- `DashboardMobileNav`
+- `DashboardUserMenu`
+- `DashboardBreadcrumbs`
+- `DashboardActionGroup`
+- `DashboardSidebar`
+- `SidebarNav`
+- `SidebarNavItem`
+- `SidebarNavGroup`
+
+## Architecture
+
+Dependency direction:
+
+```txt
+@clayer/utils
+@clayer/theme
+    ↓
+@clayer/dashboard-layout
+```
+
+The layout package is theme-aware and slot-style aware, but keeps ownership of:
+
+- responsive shell composition
+- sidebar behavior
+- header and breadcrumb behavior
+- mobile drawer / bottom-nav behavior
+
+Consumer apps own:
+
+- routes
+- business data
+- theme preset selection
+- custom background components
+- custom mobile utility items
+
+## Main Behaviors
+
+### Sidebar
+
+- config-based links, groups, dividers
+- active route detection
+- parent group active state when a child route is active
+- desktop collapse / expand
+- collapsed rail expands only on explicit click, not on hover
+- clicking a nav item or group while collapsed expands the sidebar first
+- collapsed rail tooltips render as a fixed overlay, not inside the scroll container
+- sticky bottom panel is hidden while the desktop sidebar is collapsed
+
+### Header and Breadcrumbs
+
+- title and subtitle
+- sticky header
+- breadcrumb row rendered below the main header row
+- optional scroll-aware breadcrumb hide/show
+- hysteresis-based breadcrumb behavior to avoid flicker on small scroll movement
+
+### Background Model
+
+Two background paths exist:
+
+1. `layout.background`
+2. `layout.backgroundComponents`
+
+Rules:
+
+- `layout.background` is the default path
+- `layout.backgroundComponents.<surface>` overrides `layout.background.<surface>`
+- `background` supports `"transparent"` and `"inherit"` semantics
+
+Supported surfaces:
+
+- `root`
+- `shell`
+- `sidebar`
+- `header`
+- `breadcrumb`
+- `main`
+- `content`
+- `footer`
+- `mobileBottomNav`
+
+### Mobile
+
+Mobile behavior is intentionally different from desktop:
+
+- mobile header shows page title / subtitle and breadcrumbs
+- header actions are hidden on mobile
+- user menu is hidden from the mobile header
+- when mobile bottom nav is enabled, the header sidebar toggle is removed from the header
+- bottom nav supports:
+  - primary nav items on the left
+  - utility controls on the right
+
+Current mobile utility item types:
+
+- `sidebar-toggle`
+- `user-menu`
+- `custom`
+
+`mobile.utilityItems` can be used to extend the right-side mobile controls.
+
+## Theme Integration
+
+This package consumes `@clayer/theme` slot styles through:
+
+- `theme.layout.DashboardLayout`
+
+Current practice in the playground:
+
+- CSS variables define token values
+- theme presets switch token values at the app boundary
+- `ThemeProvider` merges slot classes
+- background animation or branded visuals are provided through `layout.backgroundComponents`
+
+## Playground Context
+
+`apps/playground` currently demonstrates:
+
+- route-based navigation using `window.history.pushState`
+- multiple theme presets:
+  - `Day`
+  - `Lemonade`
+  - `Midnight`
+  - `Evergreen`
+- midnight-only Neat animated root background via `@firecms/neat`
+- configurable mobile utility items
+- config-driven shell backgrounds and styles
+
+## Important Current Decisions
+
+- no `@clayer/ui` dependency yet
+- collapsed sidebar does not expand on hover
+- sticky sidebar bottom panel is hidden when the desktop sidebar is collapsed
+- mobile header is content-focused; utilities live in the bottom nav
+- background animation belongs at the app layer, not inside the package core
+
+## Validation
+
+Typical validation commands:
+
+```bash
+pnpm --filter @clayer/dashboard-layout typecheck
+pnpm --filter @clayer/dashboard-layout build
+pnpm --filter playground typecheck
+pnpm --filter playground build
+```

package/dist/index.d.ts

@@ -0,0 +1,473 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, CSSProperties, ComponentType, HTMLAttributes } from 'react';
+
+type DashboardIcon = ComponentType<{
+    className?: string;
+    "aria-hidden"?: boolean;
+}>;
+type DashboardNavItem = DashboardNavLink | DashboardNavGroup | DashboardNavDivider;
+type DashboardNavLink = {
+    type?: "link";
+    label: string;
+    href: string;
+    icon?: DashboardIcon;
+    badge?: string | number;
+    disabled?: boolean;
+    external?: boolean;
+    exact?: boolean;
+    permission?: string;
+    hidden?: boolean;
+    pinned?: boolean;
+    onClick?: () => void;
+};
+type DashboardNavGroup = {
+    type: "group";
+    label: string;
+    icon?: DashboardIcon;
+    badge?: string | number;
+    defaultOpen?: boolean;
+    permission?: string;
+    hidden?: boolean;
+    children: DashboardNavLink[];
+};
+type DashboardNavDivider = {
+    type: "divider";
+    label?: string;
+};
+type HeaderAction = {
+    type: "button";
+    label: string;
+    icon?: DashboardIcon;
+    variant?: "solid" | "outline" | "ghost" | "soft";
+    tone?: "primary" | "neutral" | "danger";
+    onClick?: () => void;
+} | {
+    type: "icon";
+    label: string;
+    icon: DashboardIcon;
+    badge?: string | number;
+    onClick?: () => void;
+} | {
+    type: "dropdown";
+    label: string;
+    icon?: DashboardIcon;
+    items: {
+        label: string;
+        icon?: DashboardIcon;
+        onClick?: () => void;
+    }[];
+} | {
+    type: "custom";
+    render: ReactNode;
+};
+type DashboardUserMenuItem = {
+    type?: "item";
+    label: string;
+    href?: string;
+    icon?: DashboardIcon;
+    onClick?: () => void;
+} | {
+    type: "divider";
+};
+type DashboardUser = {
+    name?: string;
+    email?: string;
+    role?: string;
+    avatarUrl?: string;
+    initials?: string;
+    icon?: DashboardIcon;
+    menuItems?: DashboardUserMenuItem[];
+};
+type DashboardHeaderConfig = {
+    title?: ReactNode;
+    subtitle?: ReactNode;
+    sticky?: boolean;
+    height?: number | string;
+    showSidebarToggle?: boolean;
+    showBreadcrumbs?: boolean;
+    breadcrumbBehavior?: "static" | "hide-on-scroll";
+    userMenu?: {
+        bordered?: boolean;
+        background?: "transparent" | "background" | "muted";
+        radius?: "none" | "sm" | "md" | "lg" | "full";
+        padding?: "none" | "sm" | "md";
+        shadow?: "none" | "sm" | "md";
+        showRole?: boolean;
+    };
+    breadcrumbs?: {
+        label: string;
+        href?: string;
+    }[];
+    actions?: HeaderAction[];
+};
+type DashboardSidebarConfig = {
+    collapsible?: boolean;
+    defaultCollapsed?: boolean;
+    collapsed?: boolean;
+    onCollapsedChange?: (collapsed: boolean) => void;
+    width?: number;
+    collapsedWidth?: number;
+    showTooltipsWhenCollapsed?: boolean;
+    closeOnNavigateMobile?: boolean;
+};
+type DashboardMobileConfig = {
+    drawer?: boolean;
+    bottomNav?: boolean;
+    bottomNavItems?: DashboardNavLink[];
+    utilityItems?: DashboardMobileUtilityItem[];
+    breakpoint?: "sm" | "md" | "lg";
+    showHeader?: boolean;
+    showBottomSafeArea?: boolean;
+};
+type DashboardMobileUtilityItem = {
+    type: "sidebar-toggle";
+    label?: string;
+    icon?: DashboardIcon;
+} | {
+    type: "user-menu";
+    label?: string;
+} | {
+    type: "custom";
+    key: string;
+    render: ReactNode;
+};
+type DashboardContentConfig = {
+    padded?: boolean;
+    maxWidth?: "none" | "screen-xl" | "screen-2xl" | "7xl";
+    centered?: boolean;
+};
+type DashboardBackgroundComponent = ReactNode | {
+    content: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+    /**
+     * Background components are pointer-events-none by default.
+     * Set interactive when the component needs to receive pointer events.
+     */
+    interactive?: boolean;
+};
+type DashboardSidebarBottomPanelConfig = {
+    /**
+     * Optional panel title. When collapsible, this appears in the panel header.
+     */
+    title?: ReactNode;
+    /**
+     * Panel content shown when the sidebar is expanded, and in the mobile drawer.
+     */
+    content: ReactNode;
+    /**
+     * Optional compact content shown when the desktop sidebar is collapsed.
+     */
+    collapsedContent?: ReactNode;
+    /**
+     * Fixed panel height. Number values are treated as px.
+     */
+    height?: number | string;
+    /**
+     * If false, the panel is hidden while the desktop sidebar is collapsed.
+     */
+    showWhenCollapsed?: boolean;
+    /**
+     * Allows the panel body to collapse independently from the sidebar.
+     */
+    collapsible?: boolean;
+    /**
+     * Initial collapsed state for uncontrolled usage.
+     */
+    defaultCollapsed?: boolean;
+    /**
+     * Controlled collapsed state for the panel body.
+     */
+    collapsed?: boolean;
+    /**
+     * Called when the panel body collapse state changes.
+     */
+    onCollapsedChange?: (collapsed: boolean) => void;
+    /**
+     * Fixed panel height while the panel body is collapsed. Number values are px.
+     */
+    collapsedHeight?: number | string;
+    /**
+     * Accessible label for the panel collapse toggle.
+     */
+    collapseButtonLabel?: string;
+    /**
+     * If true, keeps the panel pinned below the scrollable nav area.
+     */
+    sticky?: boolean;
+    /**
+     * Adds the default separator border above the panel.
+     */
+    bordered?: boolean;
+    /**
+     * Local className for the panel root.
+     */
+    className?: string;
+};
+type DashboardLayoutConfig = {
+    /**
+     * Controls the viewport wrapper spacing around the dashboard shell.
+     * Useful for floating/admin-console layouts.
+     */
+    padding?: "none" | "sm" | "md" | "lg";
+    /**
+     * Adds a border around the complete dashboard shell.
+     */
+    bordered?: boolean;
+    /**
+     * Controls shell corner radius. Mobile remains square by default where appropriate.
+     */
+    radius?: "none" | "sm" | "md" | "lg" | "xl";
+    /**
+     * Adds shell elevation.
+     */
+    shadow?: "none" | "sm" | "md" | "lg";
+    /**
+     * Controls whether the header, sidebar, and footer render separator borders.
+     */
+    borders?: {
+        sidebar?: boolean;
+        header?: boolean;
+        footer?: boolean;
+        mobileBottomNav?: boolean;
+    };
+    /**
+     * Common class-based background hooks for layout-level surfaces.
+     * These are the default styling path.
+     * Use values like:
+     * - "bg-background"
+     * - "bg-transparent"
+     * - "bg-inherit"
+     * - any custom utility/class string
+     *
+     * When a matching `backgroundComponents` entry is provided for the same
+     * surface, that component takes precedence and the class-based background
+     * is not applied for that surface.
+     */
+    background?: {
+        root?: string;
+        shell?: string;
+        sidebar?: string;
+        header?: string;
+        breadcrumb?: string;
+        main?: string;
+        content?: string;
+        footer?: string;
+        mobileBottomNav?: string;
+    };
+    /**
+     * Render one arbitrary full-size background component behind each major
+     * dashboard surface. Use this for images, animations, canvas/video,
+     * overlays, solid blocks, or transparent branded backgrounds.
+     *
+     * These override `background` for the same surface.
+     */
+    backgroundComponents?: {
+        root?: DashboardBackgroundComponent;
+        shell?: DashboardBackgroundComponent;
+        sidebar?: DashboardBackgroundComponent;
+        header?: DashboardBackgroundComponent;
+        breadcrumb?: DashboardBackgroundComponent;
+        main?: DashboardBackgroundComponent;
+        content?: DashboardBackgroundComponent;
+        footer?: DashboardBackgroundComponent;
+        mobileBottomNav?: DashboardBackgroundComponent;
+    };
+};
+type DashboardLayoutStyles = {
+    root?: string;
+    shell?: string;
+    sidebar?: string;
+    sidebarInner?: string;
+    sidebarHeader?: string;
+    sidebarLogo?: string;
+    sidebarToggle?: string;
+    sidebarNav?: string;
+    sidebarNavSection?: string;
+    sidebarNavItem?: string;
+    sidebarNavItemActive?: string;
+    sidebarNavItemIcon?: string;
+    sidebarNavItemLabel?: string;
+    sidebarNavItemBadge?: string;
+    sidebarGroup?: string;
+    sidebarGroupTrigger?: string;
+    sidebarGroupContent?: string;
+    sidebarGroupChildItem?: string;
+    sidebarFooter?: string;
+    header?: string;
+    headerInner?: string;
+    headerLeft?: string;
+    headerTitle?: string;
+    headerSubtitle?: string;
+    headerBreadcrumbs?: string;
+    headerActions?: string;
+    headerActionButton?: string;
+    headerUserMenu?: string;
+    main?: string;
+    content?: string;
+    pageContainer?: string;
+    footer?: string;
+    mobileHeader?: string;
+    mobileDrawer?: string;
+    mobileBottomNav?: string;
+};
+type DashboardRenderLinkProps = {
+    href: string;
+    children: ReactNode;
+    className?: string;
+    onClick?: () => void;
+    external?: boolean;
+    "aria-current"?: "page";
+};
+type DashboardLayoutProps = {
+    children: ReactNode;
+    logo?: ReactNode;
+    sidebarItems?: DashboardNavItem[];
+    currentPath?: string;
+    isItemActive?: (item: DashboardNavLink, currentPath?: string) => boolean;
+    renderLink?: (props: DashboardRenderLinkProps) => ReactNode;
+    user?: DashboardUser;
+    header?: DashboardHeaderConfig;
+    sidebar?: DashboardSidebarConfig;
+    mobile?: DashboardMobileConfig;
+    content?: DashboardContentConfig;
+    layout?: DashboardLayoutConfig;
+    headerActions?: ReactNode;
+    sidebarBottomPanel?: DashboardSidebarBottomPanelConfig;
+    /**
+     * @deprecated Use sidebarBottomPanel.content for configurable bottom content.
+     */
+    sidebarFooter?: ReactNode;
+    sidebarHeader?: ReactNode;
+    footer?: ReactNode;
+    variant?: "classic" | "floating" | "compact" | "mini";
+    density?: "compact" | "comfortable" | "spacious";
+    styles?: DashboardLayoutStyles;
+    className?: string;
+    style?: CSSProperties;
+};
+
+declare const defaultSidebar: Required<Pick<DashboardSidebarConfig, "collapsible" | "defaultCollapsed" | "width" | "collapsedWidth" | "showTooltipsWhenCollapsed" | "closeOnNavigateMobile">>;
+declare const densityClasses: {
+    compact: {
+        header: string;
+        content: string;
+        navItem: string;
+        childItem: string;
+    };
+    comfortable: {
+        header: string;
+        content: string;
+        navItem: string;
+        childItem: string;
+    };
+    spacious: {
+        header: string;
+        content: string;
+        navItem: string;
+        childItem: string;
+    };
+};
+type ResolvedDashboardLayoutConfig = {
+    padding: NonNullable<DashboardLayoutConfig["padding"]>;
+    bordered: boolean;
+    radius: NonNullable<DashboardLayoutConfig["radius"]>;
+    shadow: NonNullable<DashboardLayoutConfig["shadow"]>;
+    borders: {
+        sidebar: boolean;
+        header: boolean;
+        footer: boolean;
+        mobileBottomNav: boolean;
+    };
+    background: NonNullable<DashboardLayoutConfig["background"]>;
+    backgroundComponents: NonNullable<DashboardLayoutConfig["backgroundComponents"]>;
+};
+declare function SidebarNav({ items, collapsed, currentPath, isItemActive, closeMobile, onExpandPersist, onCollapsedTooltipChange, renderLink, styles, density }: {
+    items: DashboardNavItem[];
+    collapsed: boolean;
+    currentPath?: string;
+    isItemActive: (item: DashboardNavLink, currentPath?: string) => boolean;
+    closeMobile?: () => void;
+    onExpandPersist?: () => void;
+    onCollapsedTooltipChange?: (tooltip: {
+        label: string;
+        top: number;
+        left: number;
+    } | null) => void;
+    renderLink: (props: DashboardRenderLinkProps) => ReactNode;
+    styles?: DashboardLayoutStyles;
+    density: keyof typeof densityClasses;
+}): react_jsx_runtime.JSX.Element;
+declare function DashboardSidebar({ logo, sidebarHeader, sidebarBottomPanel, sidebarFooter, items, collapsed, onCollapsedChange, sidebar, currentPath, isItemActive, closeMobile, renderLink, styles, density, layout, mobile }: {
+    logo?: ReactNode;
+    sidebarHeader?: ReactNode;
+    sidebarBottomPanel?: DashboardSidebarBottomPanelConfig;
+    sidebarFooter?: ReactNode;
+    items: DashboardNavItem[];
+    collapsed: boolean;
+    onCollapsedChange: (collapsed: boolean) => void;
+    sidebar: typeof defaultSidebar;
+    currentPath?: string;
+    isItemActive: (item: DashboardNavLink, currentPath?: string) => boolean;
+    closeMobile?: () => void;
+    renderLink: (props: DashboardRenderLinkProps) => ReactNode;
+    styles?: DashboardLayoutStyles;
+    density: keyof typeof densityClasses;
+    layout: ResolvedDashboardLayoutConfig;
+    mobile?: boolean;
+}): react_jsx_runtime.JSX.Element;
+declare function DashboardBreadcrumbs({ breadcrumbs, renderLink, styles, }: {
+    breadcrumbs?: DashboardHeaderConfig["breadcrumbs"];
+    renderLink: (props: DashboardRenderLinkProps) => ReactNode;
+    styles?: DashboardLayoutStyles;
+}): react_jsx_runtime.JSX.Element | null;
+declare function DashboardUserMenu({ user, config, styles, placement, triggerClassName, menuClassName }: {
+    user?: DashboardUser;
+    config?: DashboardHeaderConfig["userMenu"];
+    styles?: DashboardLayoutStyles;
+    placement?: "top" | "bottom";
+    triggerClassName?: string;
+    menuClassName?: string;
+}): react_jsx_runtime.JSX.Element | null;
+declare function DashboardHeader({ header, user, mobile, mobileOpen, setMobileOpen, renderLink, headerActions, styles, density, layout, breadcrumbsVisible }: {
+    header?: DashboardHeaderConfig;
+    user?: DashboardUser;
+    mobile?: DashboardMobileConfig;
+    mobileOpen: boolean;
+    setMobileOpen: (open: boolean) => void;
+    renderLink: (props: DashboardRenderLinkProps) => ReactNode;
+    headerActions?: ReactNode;
+    styles?: DashboardLayoutStyles;
+    density: keyof typeof densityClasses;
+    layout: ResolvedDashboardLayoutConfig;
+    breadcrumbsVisible: boolean;
+}): react_jsx_runtime.JSX.Element;
+declare function DashboardContent({ children, content, styles, density, layout }: {
+    children: ReactNode;
+    content?: DashboardContentConfig;
+    styles?: DashboardLayoutStyles;
+    density: keyof typeof densityClasses;
+    layout: ResolvedDashboardLayoutConfig;
+}): react_jsx_runtime.JSX.Element;
+declare function MobileBottomNav({ items, currentPath, isItemActive, renderLink, user, userMenuConfig, mobileOpen, setMobileOpen, utilityItems, styles, layout }: {
+    items?: DashboardNavLink[];
+    currentPath?: string;
+    isItemActive: (item: DashboardNavLink, currentPath?: string) => boolean;
+    renderLink: (props: DashboardRenderLinkProps) => ReactNode;
+    user?: DashboardUser;
+    userMenuConfig?: DashboardHeaderConfig["userMenu"];
+    mobileOpen: boolean;
+    setMobileOpen: (open: boolean) => void;
+    utilityItems?: DashboardMobileUtilityItem[];
+    styles?: DashboardLayoutStyles;
+    layout: ResolvedDashboardLayoutConfig;
+}): react_jsx_runtime.JSX.Element | null;
+declare function DashboardLayout({ children, logo, sidebarItems, currentPath, isItemActive, renderLink, user, header, sidebar: sidebarConfig, mobile, content, layout: layoutConfig, headerActions, sidebarBottomPanel, sidebarFooter, sidebarHeader, footer, variant, density, styles, className, style }: DashboardLayoutProps): react_jsx_runtime.JSX.Element;
+declare function DashboardShell({ className, ...props }: HTMLAttributes<HTMLDivElement>): react_jsx_runtime.JSX.Element;
+declare function DashboardMain({ className, ...props }: HTMLAttributes<HTMLElement>): react_jsx_runtime.JSX.Element;
+declare function DashboardFooter({ className, ...props }: HTMLAttributes<HTMLElement>): react_jsx_runtime.JSX.Element;
+declare function DashboardActionGroup({ className, ...props }: HTMLAttributes<HTMLDivElement>): react_jsx_runtime.JSX.Element;
+declare function SidebarNavItem({ className, ...props }: HTMLAttributes<HTMLLIElement>): react_jsx_runtime.JSX.Element;
+declare function SidebarNavGroup({ className, ...props }: HTMLAttributes<HTMLLIElement>): react_jsx_runtime.JSX.Element;
+
+export { DashboardActionGroup, type DashboardBackgroundComponent, DashboardBreadcrumbs, DashboardContent, type DashboardContentConfig, DashboardFooter, DashboardHeader, type DashboardHeaderConfig, type DashboardIcon, DashboardLayout, type DashboardLayoutConfig, type DashboardLayoutProps, type DashboardLayoutStyles, DashboardMain, type DashboardMobileConfig, MobileBottomNav as DashboardMobileNav, type DashboardMobileUtilityItem, type DashboardNavDivider, type DashboardNavGroup, type DashboardNavItem, type DashboardNavLink, type DashboardRenderLinkProps, DashboardShell, DashboardSidebar, type DashboardSidebarBottomPanelConfig, type DashboardSidebarConfig, type DashboardUser, DashboardUserMenu, type DashboardUserMenuItem, type HeaderAction, SidebarNav, SidebarNavGroup, SidebarNavItem };