@platned/ui 0.3.0 → 0.6.0

package/dist/sidebar.d.ts

@@ -1,4 +1,8 @@
 import * as react from 'react';
+import { ReactNode, HTMLAttributes } from 'react';
+
+type NavItemSize = 'sm' | 'md';
+type NavItemVariant = 'card' | 'plain';
 
 interface NavTabItem {
     to: string;
@@ -19,14 +23,109 @@ interface NavTabsProps {
  *  Figma specifies for a tab rule, rather than the lighter `brand` border token. */
 declare function NavTabs({ items, className }: NavTabsProps): react.JSX.Element;
 
+interface SidebarNavItem {
+    to: string;
+    label: string;
+    /** Optional — a collapsed row without one falls back to a monogram of its label. */
+    icon?: ReactNode;
+    /** Red dot on the row — something new behind this destination. */
+    indicator?: boolean;
+    /** Match the path exactly rather than as a prefix. Needed for an index route. */
+    end?: boolean;
+}
+interface SidebarNavGroup {
+    /**
+     * Uppercase heading above the group. Omit for an ungrouped run of rows.
+     *
+     * Kept in the accessibility tree when the rail is collapsed rather than dropped: it is the
+     * only thing saying what the run of icons below it has in common.
+     */
+    title?: string;
+    items: SidebarNavItem[];
+}
 interface AppSidebarProps {
-    collapsed: boolean;
-    onToggle: () => void;
-    isAdmin?: boolean;
-    userName: string;
-    userRole: string;
+    /** The scrolling nav. One untitled group is a flat list. */
+    groups: SidebarNavGroup[];
+    /** Rows pinned below the scrolling nav — settings, help, a sign-out link. */
+    footerNav?: SidebarNavItem[];
+    /**
+     * Brand lockup. Given a function it receives `collapsed`, so the caller can swap a full
+     * lockup for a mark alone rather than having one squeezed into an 80px rail.
+     */
+    brand?: ReactNode | ((state: {
+        collapsed: boolean;
+    }) => ReactNode);
+    /** Bottom slot, below a divider — a user card, a version pill, nothing. */
+    footer?: ReactNode;
+    /**
+     * Whether the rail can collapse at all.
+     *
+     * `false` locks it open: no toggle button, and `collapsed` is ignored rather than half
+     * honoured. A collapsed rail is 80px of icons, so it only earns its place in a nav short
+     * enough and iconographic enough to survive the loss of its labels — a long text nav
+     * (the docs site's own, for one) is better off never offering it.
+     */
+    collapsible?: boolean;
+    collapsed?: boolean;
+    /** Omit and the collapse toggle is not rendered, though `collapsed` still applies. */
+    onToggle?: () => void;
+    size?: NavItemSize;
+    variant?: NavItemVariant;
+    /** Expanded width, as a Tailwind class. */
+    width?: string;
+    collapsedWidth?: string;
+    className?: string;
+}
+/**
+ * The application nav rail: brand, a grouped list of destinations, and a footer.
+ *
+ * Lives on its own entry point (`@platned/ui/sidebar`) because it uses `NavLink`, and
+ * `react-router-dom` is an optional peer dependency.
+ *
+ * Through 0.4.0 this was not a library component at all. It hardcoded ten product routes,
+ * their labels and their icons, an `SCIC` wordmark, and an `isAdmin` flag gating two of the
+ * rows — so the only app it could render was the one it was extracted from, and the docs
+ * site kept a second, unrelated sidebar of its own rather than use it. Everything
+ * app-specific is now a prop or a slot, and the docs site runs on this component.
+ *
+ * Width is an explicit prop rather than something `className` overrides: the width is
+ * conditional on `collapsed`, so a `className="w-64"` would tailwind-merge away the
+ * collapsed width too and break the collapse. Everything else about the shell is fair game
+ * for `className` — `rounded-none` to flatten it for a full-bleed layout, for instance.
+ */
+declare function AppSidebar({ groups, footerNav, brand, footer, collapsible, collapsed: collapsedProp, onToggle, size, variant, width, collapsedWidth, className, }: AppSidebarProps): react.JSX.Element;
+type SidebarSeparatorProps = HTMLAttributes<HTMLDivElement>;
+/**
+ * The rule between nav groups. `AppSidebar` draws one above every group after the first;
+ * this is exported so the same line can be used in the `footer` slot or in a hand-composed
+ * rail without anyone re-deriving `h-px bg-divider` and inevitably picking a different inset.
+ *
+ * Decorative by default. The grouping it marks is already carried semantically by each
+ * group's heading — which stays in the accessibility tree even when the rail is collapsed and
+ * the heading is visually hidden — so announcing the rule as well is redundant. Pass
+ * `role="separator"` through if you are using it somewhere that has no heading to lean on.
+ */
+declare function SidebarSeparator({ className, ...rest }: SidebarSeparatorProps): react.JSX.Element;
+interface SidebarUserCardProps {
+    name: string;
+    role: string;
     onLogout: () => void;
+    collapsed?: boolean;
+    /** Extra menu entries above Sign out. */
+    menu?: ReactNode;
+    className?: string;
 }
-declare function AppSidebar({ collapsed, onToggle, isAdmin, userName, userRole, onLogout }: AppSidebarProps): react.JSX.Element;
+/**
+ * The signed-in user block, for `AppSidebar`'s `footer` slot.
+ *
+ * Was private, and its props were on `AppSidebar` itself — which meant every consumer of the
+ * sidebar had to have a user, a role and a logout handler whether it had a concept of any
+ * of them or not. The docs site has none, and passes no footer.
+ *
+ * Its menu is `DropdownMenu` rather than the hand-rolled click-outside popover it was: that
+ * one had no keyboard contract and, being absolutely positioned, was clipped by the
+ * collapsed rail. `DropdownMenu` portals.
+ */
+declare function SidebarUserCard({ name, role, onLogout, collapsed, menu, className, }: SidebarUserCardProps): react.JSX.Element;
 
-export { AppSidebar, type NavTabItem, NavTabs, type NavTabsProps };
+export { AppSidebar, type AppSidebarProps, type NavTabItem, NavTabs, type NavTabsProps, type SidebarNavGroup, type SidebarNavItem, SidebarSeparator, type SidebarSeparatorProps, SidebarUserCard, type SidebarUserCardProps };