@syscore/ui-library 2.0.0-beta-publish-workflow-beta.10 → 2.0.0-beta-publish-workflow-beta.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/client/components/ui/avatar-identity.tsx +16 -3
  2. package/client/components/ui/avatar.tsx +32 -4
  3. package/client/components/ui/back-link.tsx +35 -0
  4. package/client/components/ui/button.tsx +3 -0
  5. package/client/components/ui/card.tsx +20 -3
  6. package/client/components/ui/centered-page.tsx +27 -0
  7. package/client/components/ui/checkbox-field.tsx +57 -0
  8. package/client/components/ui/data-grid.tsx +258 -0
  9. package/client/components/ui/dialog.tsx +6 -0
  10. package/client/components/ui/icon-button.tsx +45 -0
  11. package/client/components/ui/layout.tsx +32 -5
  12. package/client/components/ui/modal-panel.tsx +35 -4
  13. package/client/components/ui/outline-node.tsx +112 -0
  14. package/client/components/ui/radio-card.tsx +54 -0
  15. package/client/components/ui/resource-thumbnail.tsx +12 -1
  16. package/client/components/ui/side-nav.tsx +280 -0
  17. package/client/components/ui/status-pill.tsx +37 -4
  18. package/client/components/ui/table.tsx +26 -4
  19. package/client/components/ui/typography.tsx +33 -2
  20. package/client/global.css +980 -4
  21. package/client/ui/Avatar.stories.tsx +78 -0
  22. package/client/ui/BackLink.stories.tsx +50 -0
  23. package/client/ui/Button.stories.tsx +26 -0
  24. package/client/ui/Card.stories.tsx +30 -0
  25. package/client/ui/CenteredPage.stories.tsx +43 -0
  26. package/client/ui/CheckboxField.stories.tsx +68 -0
  27. package/client/ui/DataGrid.stories.tsx +114 -0
  28. package/client/ui/Dialog.stories.tsx +31 -0
  29. package/client/ui/IconButton.stories.tsx +77 -0
  30. package/client/ui/OutlineNode.stories.tsx +106 -0
  31. package/client/ui/RadioCard.stories.tsx +75 -0
  32. package/client/ui/SideNav.stories.tsx +105 -0
  33. package/client/ui/StatusPill.stories.tsx +78 -0
  34. package/client/ui/Table/Table.stories.tsx +32 -0
  35. package/dist/index.cjs.js +1 -1
  36. package/dist/index.d.ts +105 -0
  37. package/dist/index.es.js +653 -40
  38. package/package.json +3 -1
@@ -382,6 +382,7 @@ GridSpan.displayName = "GridSpan";
382
382
 
383
383
  type ColumnsPreset =
384
384
  | "sidebar"
385
+ | "main-aside"
385
386
  | "sidebar-right"
386
387
  | "wide-sidebar"
387
388
  | "narrow-sidebar"
@@ -391,7 +392,7 @@ type ColumnsPreset =
391
392
  | "1-3"
392
393
  | "3-1";
393
394
 
394
- type ColumnsCollapse = "sm" | "md" | "lg";
395
+ type ColumnsCollapse = "sm" | "md" | "lg" | "xl";
395
396
 
396
397
  interface ColumnsProps extends React.HTMLAttributes<HTMLElement> {
397
398
  as?: React.ElementType;
@@ -404,11 +405,15 @@ interface ColumnsProps extends React.HTMLAttributes<HTMLElement> {
404
405
  columnGap?: SpaceInput;
405
406
  rowGap?: SpaceInput;
406
407
  collapse?: ColumnsCollapse;
408
+ /** Cross-axis alignment of the columns. `start` lets a short column (a sticky aside) keep its own height. */
409
+ align?: "stretch" | "start";
407
410
  }
408
411
 
409
412
  /** Sidebar widths reuse the panel scale so a Columns sidebar and a LayoutPanel match. */
410
413
  const ColumnsPresetMap: Record<ColumnsPreset, string> = {
411
414
  sidebar: "var(--layout-panel-width-default) 1fr",
415
+ // A flexible main column and a 20–27.5rem aside (a form beside its live summary).
416
+ "main-aside": "minmax(0, 1fr) minmax(20rem, 27.5rem)",
412
417
  "sidebar-right": "1fr var(--layout-panel-width-default)",
413
418
  "wide-sidebar": "var(--layout-panel-width-wide) 1fr",
414
419
  "narrow-sidebar": "var(--layout-panel-width-narrow) 1fr",
@@ -430,6 +435,7 @@ const Columns = React.forwardRef<HTMLElement, ColumnsProps>(
430
435
  columnGap,
431
436
  rowGap,
432
437
  collapse,
438
+ align,
433
439
  className,
434
440
  style,
435
441
  ...props
@@ -443,6 +449,7 @@ const Columns = React.forwardRef<HTMLElement, ColumnsProps>(
443
449
  className={cn(
444
450
  "columns-layout",
445
451
  collapse && `columns-layout--collapse-${collapse}`,
452
+ align === "start" && "columns-layout--align-start",
446
453
  className,
447
454
  )}
448
455
  style={{
@@ -612,7 +619,7 @@ type LayoutHeight = "fill" | "auto";
612
619
  type LayoutPanelPlacement = "start" | "end";
613
620
 
614
621
  /** Panel widths come from `--layout-panel-width-*`, never from app-side px. */
615
- type LayoutPanelWidth = "narrow" | "default" | "wide";
622
+ type LayoutPanelWidth = "rail" | "nav" | "narrow" | "default" | "wide";
616
623
  /** Content measures come from `--layout-measure-*`, never from app-side px. */
617
624
  type LayoutMeasure = "sm" | "md" | "lg" | "full";
618
625
 
@@ -633,7 +640,7 @@ function panelWidthVar(
633
640
  if (typeof width === "number") {
634
641
  warnOnce(
635
642
  `LayoutPanel: width={${width}} freezes ${width}px into this app. ` +
636
- `Use width="narrow" | "default" | "wide" so --layout-panel-width-* stays in control.`,
643
+ `Use width="rail" | "nav" | "narrow" | "default" | "wide" so --layout-panel-width-* stays in control.`,
637
644
  );
638
645
  return `${width}px`;
639
646
  }
@@ -686,13 +693,21 @@ function slotIdOf(element: React.ReactElement): LayoutSlotId | undefined {
686
693
  interface LayoutHeaderProps extends LayoutSlotHTMLProps {
687
694
  /** Kept narrow so the landmark cannot be lost by accident. */
688
695
  as?: "header" | "div";
696
+ /** Pin the header to the top of the window while the page scrolls underneath it. */
697
+ sticky?: boolean;
689
698
  }
690
699
 
691
700
  const LayoutHeader = markSlot(
692
701
  React.forwardRef<HTMLElement, LayoutHeaderProps>(
693
- ({ as = "header", ...props }, ref) => {
702
+ ({ as = "header", sticky = false, ...props }, ref) => {
694
703
  const Component = as as React.ElementType;
695
- return <Component ref={ref} className="layout-header" {...props} />;
704
+ return (
705
+ <Component
706
+ ref={ref}
707
+ className={cn("layout-header", sticky && "layout-header--sticky")}
708
+ {...props}
709
+ />
710
+ );
696
711
  },
697
712
  ),
698
713
  "header",
@@ -748,6 +763,14 @@ interface LayoutPanelProps extends LayoutSlotHTMLProps {
748
763
  placement?: LayoutPanelPlacement;
749
764
  /** Named width backed by `--layout-panel-width-*`. Default `default` (17.5rem). */
750
765
  width?: LayoutPanelWidth;
766
+ /**
767
+ * `nav` — a side navigation: pinned under a sticky `LayoutHeader`, as tall as the window,
768
+ * scrolling inside itself, no divider line. Pair it with `SideNav`; use `width="nav"` (or
769
+ * `"rail"` when collapsed). Default is the plain panel.
770
+ */
771
+ appearance?: "default" | "nav";
772
+ /** With `appearance="nav"`: the icon-only rail (hidden on phones). Pair it with `SideNav collapsed`. */
773
+ collapsed?: boolean;
751
774
  /** Named inset backed by `--layout-panel-padding`. Default `xl`. */
752
775
  padding?: SpaceName;
753
776
  isScrollable?: boolean;
@@ -761,6 +784,8 @@ const LayoutPanel = markSlot(
761
784
  placement = "start",
762
785
  width,
763
786
  padding,
787
+ appearance = "default",
788
+ collapsed = false,
764
789
  isScrollable = true,
765
790
  tabIndex,
766
791
  "aria-label": ariaLabel,
@@ -776,6 +801,7 @@ const LayoutPanel = markSlot(
776
801
  "layout-panel",
777
802
  `layout-panel--${placement}`,
778
803
  isScrollable && "layout-panel--scrollable",
804
+ appearance === "nav" && "layout-panel--nav",
779
805
  )}
780
806
  style={{
781
807
  ...(width != null
@@ -785,6 +811,7 @@ const LayoutPanel = markSlot(
785
811
  ? { ["--layout-panel-padding" as string]: tokenCss(padding) }
786
812
  : undefined),
787
813
  }}
814
+ data-collapsed={collapsed || undefined}
788
815
  tabIndex={tabIndex ?? (isScrollable ? 0 : undefined)}
789
816
  aria-label={
790
817
  ariaLabel ?? (placement === "end" ? "Details" : "Navigation")
@@ -1,5 +1,6 @@
1
1
  import * as React from "react";
2
2
  import { cn } from "@/lib/utils";
3
+ import type { SpaceName } from "./layout";
3
4
 
4
5
  interface ModalOverlayProps extends React.HTMLAttributes<HTMLDivElement> {
5
6
  zIndex?: number;
@@ -54,11 +55,21 @@ interface ModalCloseRowProps extends React.HTMLAttributes<HTMLDivElement> {
54
55
  onClose?: () => void;
55
56
  label?: string;
56
57
  icon?: React.ReactNode;
58
+ /** `roomy` sets the close button 16px from the panel's top and right edge (default is 8px). */
59
+ inset?: "default" | "roomy";
57
60
  }
58
61
 
59
62
  const ModalCloseRow = React.forwardRef<HTMLDivElement, ModalCloseRowProps>(
60
- ({ onClose, label = "Close", icon, className, ...props }, ref) => (
61
- <div ref={ref} className={cn("modal-close-row", className)} {...props}>
63
+ ({ onClose, label = "Close", icon, inset = "default", className, ...props }, ref) => (
64
+ <div
65
+ ref={ref}
66
+ className={cn(
67
+ "modal-close-row",
68
+ inset === "roomy" && "modal-close-row--roomy",
69
+ className,
70
+ )}
71
+ {...props}
72
+ >
62
73
  <button
63
74
  type="button"
64
75
  className="modal-close"
@@ -81,6 +92,12 @@ interface ModalPanelProps extends React.HTMLAttributes<HTMLDivElement> {
81
92
  align?: PanelAlign;
82
93
  angle?: number;
83
94
  height?: number;
95
+ /** Space between the panel's children, as a `--space-*` token. Default `xl` (24px). */
96
+ gap?: SpaceName;
97
+ /** Top inset, as a `--space-*` token. Default `xl` (24px). */
98
+ paddingTop?: SpaceName;
99
+ /** Bottom inset, as a `--space-*` token. Default `xl` (24px). */
100
+ paddingBottom?: SpaceName;
84
101
  }
85
102
 
86
103
  const ModalPanel = React.forwardRef<HTMLDivElement, ModalPanelProps>(
@@ -91,6 +108,9 @@ const ModalPanel = React.forwardRef<HTMLDivElement, ModalPanelProps>(
91
108
  align = "start",
92
109
  angle = 114.72731273771963,
93
110
  height,
111
+ gap,
112
+ paddingTop,
113
+ paddingBottom,
94
114
  className,
95
115
  style,
96
116
  ...props
@@ -111,6 +131,13 @@ const ModalPanel = React.forwardRef<HTMLDivElement, ModalPanelProps>(
111
131
  ? { ["--panel-gradient-angle" as string]: `${angle}deg` }
112
132
  : null),
113
133
  ...(height !== undefined ? { height } : null),
134
+ ...(gap ? { ["--modal-panel-gap" as string]: `var(--space-${gap})` } : null),
135
+ ...(paddingTop
136
+ ? { ["--modal-panel-padding-top" as string]: `var(--space-${paddingTop})` }
137
+ : null),
138
+ ...(paddingBottom
139
+ ? { ["--modal-panel-padding-bottom" as string]: `var(--space-${paddingBottom})` }
140
+ : null),
114
141
  ...style,
115
142
  } as React.CSSProperties
116
143
  }
@@ -122,11 +149,15 @@ ModalPanel.displayName = "ModalPanel";
122
149
 
123
150
  interface ModalTitleProps extends React.HTMLAttributes<HTMLHeadingElement> {
124
151
  as?: React.ElementType;
152
+ /** `large` — a 28px title for a welcome / landing panel. Default is the 20px modal title. */
153
+ size?: "default" | "large";
125
154
  }
126
155
 
127
156
  const ModalTitle = React.forwardRef<HTMLHeadingElement, ModalTitleProps>(
128
- ({ as: Component = "h2", children, className, ...props }, ref) => (
129
- <div className={cn("modal-title", className)}>
157
+ ({ as: Component = "h2", size = "default", children, className, ...props }, ref) => (
158
+ <div
159
+ className={cn("modal-title", size === "large" && "modal-title--large", className)}
160
+ >
130
161
  <Component ref={ref} className="modal-title__text heading-xxsmall" {...props}>
131
162
  {children}
132
163
  </Component>
@@ -0,0 +1,112 @@
1
+ import * as React from "react";
2
+ import { cva, type VariantProps } from "class-variance-authority";
3
+
4
+ import { cn } from "@/lib/utils";
5
+
6
+ /**
7
+ * OutlineNode — one row of an editable outline / tree (for example concept › feature ›
8
+ * requirement). The nesting is visual, driven by `level`; put child nodes inside the parent.
9
+ *
10
+ * <OutlineNode level="section">
11
+ * <OutlineNodeHead>
12
+ * <OutlineNodeTitle>Air · Clean air <OutlineNodeMeta>12 pts</OutlineNodeMeta></OutlineNodeTitle>
13
+ * <OutlineNodeControls>…icon buttons…</OutlineNodeControls>
14
+ * </OutlineNodeHead>
15
+ * <OutlineNode level="branch">…</OutlineNode>
16
+ * </OutlineNode>
17
+ *
18
+ * `OutlineNodeTitle` takes an optional bold `code` (`A02 · Air quality`).
19
+ * `section` is a bordered card, `branch` is indented with a guide line, `leaf` is a compact row
20
+ * with a hover highlight.
21
+ */
22
+ const outlineNodeVariants = cva("tree-node", {
23
+ variants: {
24
+ level: {
25
+ section: "tree-node--section",
26
+ branch: "tree-node--branch",
27
+ leaf: "tree-node--leaf",
28
+ },
29
+ },
30
+ defaultVariants: { level: "section" },
31
+ });
32
+
33
+ interface OutlineNodeProps
34
+ extends React.HTMLAttributes<HTMLDivElement>,
35
+ VariantProps<typeof outlineNodeVariants> {
36
+ /** Greyed out, for items that are hidden or switched off. */
37
+ inactive?: boolean;
38
+ }
39
+
40
+ const OutlineNode = React.forwardRef<HTMLDivElement, OutlineNodeProps>(
41
+ ({ className, level, inactive = false, ...props }, ref) => (
42
+ <div
43
+ ref={ref}
44
+ data-inactive={inactive || undefined}
45
+ className={cn(outlineNodeVariants({ level }), className)}
46
+ {...props}
47
+ />
48
+ ),
49
+ );
50
+ OutlineNode.displayName = "OutlineNode";
51
+
52
+ /** Title on the left, controls on the right; wraps on narrow widths. */
53
+ const OutlineNodeHead = React.forwardRef<
54
+ HTMLDivElement,
55
+ React.HTMLAttributes<HTMLDivElement>
56
+ >(({ className, ...props }, ref) => (
57
+ <div ref={ref} className={cn("tree-node__head", className)} {...props} />
58
+ ));
59
+ OutlineNodeHead.displayName = "OutlineNodeHead";
60
+
61
+ interface OutlineNodeTitleProps extends React.HTMLAttributes<HTMLDivElement> {
62
+ /** A bold code or prefix before the name (`A02`); a "·" separator is added after it. */
63
+ code?: React.ReactNode;
64
+ }
65
+
66
+ /** Inline group for the node's name and its badges. */
67
+ const OutlineNodeTitle = React.forwardRef<HTMLDivElement, OutlineNodeTitleProps>(
68
+ ({ className, code, children, ...props }, ref) => (
69
+ <div ref={ref} className={cn("tree-node__title", className)} {...props}>
70
+ {code != null ? (
71
+ <>
72
+ <strong className="tree-node__code">{code}</strong>
73
+ {"· "}
74
+ </>
75
+ ) : null}
76
+ {children}
77
+ </div>
78
+ ),
79
+ );
80
+ OutlineNodeTitle.displayName = "OutlineNodeTitle";
81
+
82
+ /** Small secondary text next to the name (points, counts). */
83
+ const OutlineNodeMeta = React.forwardRef<
84
+ HTMLSpanElement,
85
+ React.HTMLAttributes<HTMLSpanElement>
86
+ >(({ className, ...props }, ref) => (
87
+ <span ref={ref} className={cn("tree-node__meta", className)} {...props} />
88
+ ));
89
+ OutlineNodeMeta.displayName = "OutlineNodeMeta";
90
+
91
+ /** Row of icon buttons (move up / down, edit, delete). */
92
+ const OutlineNodeControls = React.forwardRef<
93
+ HTMLDivElement,
94
+ React.HTMLAttributes<HTMLDivElement>
95
+ >(({ className, ...props }, ref) => (
96
+ <div
97
+ ref={ref}
98
+ className={cn("tree-node__controls", className)}
99
+ {...props}
100
+ />
101
+ ));
102
+ OutlineNodeControls.displayName = "OutlineNodeControls";
103
+
104
+ export {
105
+ OutlineNode,
106
+ OutlineNodeHead,
107
+ OutlineNodeTitle,
108
+ OutlineNodeMeta,
109
+ OutlineNodeControls,
110
+ outlineNodeVariants,
111
+ };
112
+ export type { OutlineNodeProps, OutlineNodeTitleProps };
@@ -0,0 +1,54 @@
1
+ import * as React from "react";
2
+ import * as RadioGroupPrimitive from "@radix-ui/react-radio-group";
3
+
4
+ import { cn } from "@/lib/utils";
5
+
6
+ /**
7
+ * RadioCard — a single-choice picker where each option is a card with a title and a line of
8
+ * explanation (for example a role and what it allows). Built on Radix RadioGroup, so keyboard
9
+ * navigation, `value` and `onValueChange` work as in `RadioGroup`.
10
+ *
11
+ * <RadioCardGroup value={role} onValueChange={setRole}>
12
+ * <RadioCardItem value="admin" title="Admin" description="Can edit everything." />
13
+ * </RadioCardGroup>
14
+ */
15
+ const RadioCardGroup = React.forwardRef<
16
+ React.ElementRef<typeof RadioGroupPrimitive.Root>,
17
+ React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Root>
18
+ >(({ className, ...props }, ref) => (
19
+ <RadioGroupPrimitive.Root
20
+ ref={ref}
21
+ className={cn("radio-card-group", className)}
22
+ {...props}
23
+ />
24
+ ));
25
+ RadioCardGroup.displayName = "RadioCardGroup";
26
+
27
+ interface RadioCardItemProps
28
+ extends Omit<
29
+ React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Item>,
30
+ "title" | "children"
31
+ > {
32
+ title: React.ReactNode;
33
+ description?: React.ReactNode;
34
+ }
35
+
36
+ const RadioCardItem = React.forwardRef<
37
+ React.ElementRef<typeof RadioGroupPrimitive.Item>,
38
+ RadioCardItemProps
39
+ >(({ className, title, description, ...props }, ref) => (
40
+ <RadioGroupPrimitive.Item
41
+ ref={ref}
42
+ className={cn("radio-card", className)}
43
+ {...props}
44
+ >
45
+ <span className="radio-card__title">{title}</span>
46
+ {description ? (
47
+ <span className="radio-card__description">{description}</span>
48
+ ) : null}
49
+ </RadioGroupPrimitive.Item>
50
+ ));
51
+ RadioCardItem.displayName = "RadioCardItem";
52
+
53
+ export { RadioCardGroup, RadioCardItem };
54
+ export type { RadioCardItemProps };
@@ -1,17 +1,28 @@
1
1
  import * as React from "react";
2
+ import { cn } from "@/lib/utils";
2
3
 
3
4
  export interface ResourceThumbnailProps {
4
5
  src: string;
5
6
  alt?: string;
7
+ /**
8
+ * `default` fills its container at 16:9. `preview` keeps the image's own proportions, at most 160px
9
+ * tall (a live preview of a pasted URL). `thumb` is a 56 × 40 table thumbnail.
10
+ */
11
+ size?: "default" | "preview" | "thumb";
6
12
  }
7
13
 
8
14
  export function ResourceThumbnail({
9
15
  src,
10
16
  alt = "",
17
+ size = "default",
11
18
  }: ResourceThumbnailProps) {
12
19
  return (
13
20
  <img
14
- className="resource-thumbnail"
21
+ className={cn(
22
+ "resource-thumbnail",
23
+ size === "preview" && "resource-thumbnail--preview",
24
+ size === "thumb" && "resource-thumbnail--thumb",
25
+ )}
15
26
  src={src}
16
27
  alt={alt}
17
28
  loading="lazy"
@@ -0,0 +1,280 @@
1
+ import * as React from "react";
2
+ import { Slot, Slottable } from "@radix-ui/react-slot";
3
+ import { ChevronDown } from "lucide-react";
4
+
5
+ import { cn } from "@/lib/utils";
6
+
7
+ /**
8
+ * SideNav — grouped, icon-led navigation for an app shell's side panel
9
+ * (put it inside `LayoutPanel`; use `width="rail"` there when `collapsed`).
10
+ *
11
+ * <SideNav aria-label="Admin sections" collapsed={collapsed}>
12
+ * <SideNavGroup label="Overview">
13
+ * <SideNavItem icon={<LayoutDashboard />} active>Dashboard</SideNavItem>
14
+ * </SideNavGroup>
15
+ * </SideNav>
16
+ *
17
+ * `collapsed` hides group labels and item text and centres the icons. A collapsed item
18
+ * keeps its text as a `title` tooltip and an accessible name.
19
+ *
20
+ * Long menus fold: give a group `collapsible` (its label becomes a button with a chevron) and
21
+ * nest sub-pages under a `SideNavBranch`. Both open and close themselves, or are controlled with
22
+ * `open` / `onOpenChange`. In the collapsed rail every group is shown open and a branch shows
23
+ * only its icon (its `onClick` can take the user to the first sub-page).
24
+ */
25
+
26
+ interface SideNavContextValue {
27
+ collapsed: boolean;
28
+ }
29
+
30
+ const SideNavContext = React.createContext<SideNavContextValue>({
31
+ collapsed: false,
32
+ });
33
+
34
+ interface SideNavProps extends React.HTMLAttributes<HTMLElement> {
35
+ /** Icon-only rail. Default `false`. */
36
+ collapsed?: boolean;
37
+ }
38
+
39
+ const SideNav = React.forwardRef<HTMLElement, SideNavProps>(
40
+ ({ className, collapsed = false, children, ...props }, ref) => (
41
+ <SideNavContext.Provider value={{ collapsed }}>
42
+ <nav
43
+ ref={ref}
44
+ data-collapsed={collapsed || undefined}
45
+ className={cn("side-nav", collapsed && "side-nav--collapsed", className)}
46
+ {...props}
47
+ >
48
+ {children}
49
+ </nav>
50
+ </SideNavContext.Provider>
51
+ ),
52
+ );
53
+ SideNav.displayName = "SideNav";
54
+
55
+ /** Open state that the parent can control (`open` + `onOpenChange`) or leave to the component. */
56
+ function useDisclosure(
57
+ open: boolean | undefined,
58
+ defaultOpen: boolean,
59
+ onOpenChange?: (open: boolean) => void,
60
+ ) {
61
+ const [inner, setInner] = React.useState(defaultOpen);
62
+ const isOpen = open ?? inner;
63
+ const setOpen = (next: boolean) => {
64
+ if (open === undefined) setInner(next);
65
+ onOpenChange?.(next);
66
+ };
67
+ return [isOpen, setOpen] as const;
68
+ }
69
+
70
+ interface SideNavGroupProps
71
+ extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange"> {
72
+ /** Group heading, shown above the items (hidden when the nav is collapsed). */
73
+ label?: React.ReactNode;
74
+ /** Fold the group: the heading becomes a button that shows or hides its items. */
75
+ collapsible?: boolean;
76
+ /** Controlled open state (with `collapsible`). */
77
+ open?: boolean;
78
+ /** Initial open state when not controlled. Default `true`. */
79
+ defaultOpen?: boolean;
80
+ onOpenChange?: (open: boolean) => void;
81
+ }
82
+
83
+ const SideNavGroup = React.forwardRef<HTMLDivElement, SideNavGroupProps>(
84
+ (
85
+ {
86
+ className,
87
+ label,
88
+ collapsible = false,
89
+ open,
90
+ defaultOpen = true,
91
+ onOpenChange,
92
+ children,
93
+ ...props
94
+ },
95
+ ref,
96
+ ) => {
97
+ const { collapsed } = React.useContext(SideNavContext);
98
+ const headingId = React.useId();
99
+ const itemsId = React.useId();
100
+ const [isOpen, setOpen] = useDisclosure(open, defaultOpen, onOpenChange);
101
+
102
+ if (!collapsible) {
103
+ return (
104
+ <div
105
+ ref={ref}
106
+ role="group"
107
+ aria-labelledby={label ? headingId : undefined}
108
+ className={cn("side-nav__group", className)}
109
+ {...props}
110
+ >
111
+ {label ? (
112
+ <span id={headingId} className="side-nav__heading">
113
+ {label}
114
+ </span>
115
+ ) : null}
116
+ {children}
117
+ </div>
118
+ );
119
+ }
120
+
121
+ // In the icon rail there is no heading to fold, so every item stays reachable.
122
+ const shown = collapsed || isOpen;
123
+ return (
124
+ <div
125
+ ref={ref}
126
+ role="group"
127
+ aria-labelledby={label ? headingId : undefined}
128
+ className={cn("side-nav__group", className)}
129
+ {...props}
130
+ >
131
+ {label ? (
132
+ <button
133
+ type="button"
134
+ id={headingId}
135
+ className="side-nav__heading side-nav__heading--toggle"
136
+ aria-expanded={shown}
137
+ aria-controls={itemsId}
138
+ onClick={() => setOpen(!isOpen)}
139
+ >
140
+ <span>{label}</span>
141
+ <ChevronDown className="side-nav__chevron" aria-hidden="true" />
142
+ </button>
143
+ ) : null}
144
+ <div id={itemsId} className="side-nav__items" hidden={!shown}>
145
+ {children}
146
+ </div>
147
+ </div>
148
+ );
149
+ },
150
+ );
151
+ SideNavGroup.displayName = "SideNavGroup";
152
+
153
+ interface SideNavItemProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
154
+ /** Leading icon (a lucide icon element, for example). */
155
+ icon?: React.ReactNode;
156
+ /** The current page. Sets `aria-current="page"` and the highlighted look. */
157
+ active?: boolean;
158
+ /**
159
+ * Render the child element (an `<a>` or a router `<Link>`) instead of a `<button>`;
160
+ * the icon is placed inside it, before the child's own text.
161
+ */
162
+ asChild?: boolean;
163
+ }
164
+
165
+ const SideNavItem = React.forwardRef<HTMLButtonElement, SideNavItemProps>(
166
+ ({ className, icon, active = false, asChild = false, children, ...props }, ref) => {
167
+ const { collapsed } = React.useContext(SideNavContext);
168
+ const Comp = asChild ? Slot : "button";
169
+ const label = typeof children === "string" ? children : undefined;
170
+
171
+ return (
172
+ <Comp
173
+ ref={ref}
174
+ {...(asChild ? {} : { type: "button" })}
175
+ aria-current={active ? "page" : undefined}
176
+ aria-label={collapsed ? label : undefined}
177
+ title={collapsed ? label : undefined}
178
+ className={cn(
179
+ "side-nav__item",
180
+ active && "side-nav__item--active",
181
+ className,
182
+ )}
183
+ {...props}
184
+ >
185
+ {icon ? (
186
+ <span className="side-nav__icon" aria-hidden="true">
187
+ {icon}
188
+ </span>
189
+ ) : null}
190
+ {asChild ? (
191
+ <Slottable>{children}</Slottable>
192
+ ) : (
193
+ <span className="side-nav__label">{children}</span>
194
+ )}
195
+ </Comp>
196
+ );
197
+ },
198
+ );
199
+ SideNavItem.displayName = "SideNavItem";
200
+
201
+ interface SideNavBranchProps
202
+ extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange" | "onClick"> {
203
+ /** Leading icon. */
204
+ icon?: React.ReactNode;
205
+ /** The branch's own text. Its sub-pages (`SideNavItem`s) go in `children`. */
206
+ label: string;
207
+ /** A sub-page is the current page: the branch is highlighted even while folded. */
208
+ active?: boolean;
209
+ /** Controlled open state. */
210
+ open?: boolean;
211
+ /** Initial open state when not controlled. Default `false`. */
212
+ defaultOpen?: boolean;
213
+ onOpenChange?: (open: boolean) => void;
214
+ /** Runs when the branch is pressed in the collapsed icon rail (where it cannot unfold). */
215
+ onClick?: React.MouseEventHandler<HTMLButtonElement>;
216
+ }
217
+
218
+ /** An item that unfolds into sub-pages (Users → Users, Roles, Permissions). */
219
+ const SideNavBranch = React.forwardRef<HTMLDivElement, SideNavBranchProps>(
220
+ (
221
+ {
222
+ className,
223
+ icon,
224
+ label,
225
+ active = false,
226
+ open,
227
+ defaultOpen = false,
228
+ onOpenChange,
229
+ onClick,
230
+ children,
231
+ ...props
232
+ },
233
+ ref,
234
+ ) => {
235
+ const { collapsed } = React.useContext(SideNavContext);
236
+ const subId = React.useId();
237
+ const [isOpen, setOpen] = useDisclosure(open, defaultOpen, onOpenChange);
238
+
239
+ return (
240
+ <div ref={ref} className={cn("side-nav__branch", className)} {...props}>
241
+ <button
242
+ type="button"
243
+ className={cn(
244
+ "side-nav__item",
245
+ "side-nav__item--branch",
246
+ active && "side-nav__item--branch-active",
247
+ )}
248
+ aria-expanded={collapsed ? undefined : isOpen}
249
+ aria-controls={subId}
250
+ aria-label={collapsed ? label : undefined}
251
+ title={collapsed ? label : undefined}
252
+ onClick={(event) => {
253
+ if (collapsed) onClick?.(event);
254
+ else setOpen(!isOpen);
255
+ }}
256
+ >
257
+ {icon ? (
258
+ <span className="side-nav__icon" aria-hidden="true">
259
+ {icon}
260
+ </span>
261
+ ) : null}
262
+ <span className="side-nav__label">{label}</span>
263
+ <ChevronDown className="side-nav__chevron" aria-hidden="true" />
264
+ </button>
265
+ <div id={subId} className="side-nav__sub" hidden={collapsed || !isOpen}>
266
+ {children}
267
+ </div>
268
+ </div>
269
+ );
270
+ },
271
+ );
272
+ SideNavBranch.displayName = "SideNavBranch";
273
+
274
+ export { SideNav, SideNavGroup, SideNavItem, SideNavBranch };
275
+ export type {
276
+ SideNavProps,
277
+ SideNavGroupProps,
278
+ SideNavItemProps,
279
+ SideNavBranchProps,
280
+ };