@inversestudio/neptune-components 1.0.0

package/components/layout/Toolbar.jsx

@@ -0,0 +1,89 @@
+import Button from "../inputs/Button.jsx";
+import IconButton from "../inputs/IconButton.jsx";
+
+/**
+ * Toolbar component - Application toolbar with actions
+ *
+ * Styles are in neptune-components.css. Only pass `style` for truly dynamic overrides.
+ *
+ * Displays a labeled toolbar with optional badge and action buttons.
+ * Uses Button and IconButton from the design system for all actions.
+ *
+ * @component
+ * @param {Object} props - Component props
+ * @param {string} [props.label="Application"] - Toolbar label text
+ * @param {Object} [props.badge] - Badge object with {text} properties
+ * @param {string} [props.badge.text] - Badge text content
+ * @param {Array} [props.actions=[]] - Array of action objects
+ * @param {string} [props.actions[].label] - Action button label (if absent, renders icon-only)
+ * @param {React.ReactNode} [props.actions[].icon] - Icon component for button
+ * @param {string} [props.actions[].variant] - Button variant: 'primary' | 'secondary' | 'tertiary' | 'icon' | 'icon-outline'
+ * @param {Function} [props.actions[].onClick] - Click handler for action
+ * @param {React.ReactNode} [props.left] - Custom left-side content (overrides label+badge)
+ * @param {React.ReactNode} [props.right] - Custom right-side content (overrides actions)
+ * @param {React.ReactNode} [props.children] - Additional content
+ * @returns {JSX.Element} Toolbar component
+ */
+export default function Toolbar({
+  label = "Application",
+  badge,
+  actions = [],
+  left,
+  right,
+  children,
+}) {
+  return (
+    <div className="neptune-toolbar">
+      {/* Left side */}
+      {left || (
+        <div className="neptune-toolbar__left">
+          <span className="neptune-toolbar__label">
+            {label}
+          </span>
+          {badge && (
+            <span className="neptune-toolbar__badge">
+              {badge.text}
+            </span>
+          )}
+        </div>
+      )}
+
+      {/* Middle */}
+      {children}
+
+      {/* Right side */}
+      {right || (
+        <div className="neptune-toolbar__right">
+          {actions.map((action, index) => {
+            const r6 = { borderRadius: "6px" };
+            if (action.variant === "icon" || action.variant === "icon-outline") {
+              return (
+                <IconButton
+                  key={index}
+                  variant={action.variant === "icon-outline" ? "outline" : "subtle"}
+                  icon={action.icon}
+                  title={action.label}
+                  size="sm"
+                  onClick={action.onClick}
+                  style={r6}
+                />
+              );
+            }
+            return (
+              <Button
+                key={index}
+                variant={action.variant || "secondary"}
+                size="sm"
+                icon={action.icon}
+                onClick={action.onClick}
+                style={r6}
+              >
+                {action.label}
+              </Button>
+            );
+          })}
+        </div>
+      )}
+    </div>
+  );
+}

package/components/navigation/Breadcrumb.jsx

@@ -0,0 +1,43 @@
+/**
+ * Breadcrumb — Navigation breadcrumb trail
+ *
+ * Styles are in neptune-components.css. Only pass `style` for truly dynamic overrides.
+ *
+ * @component
+ * @param {Object} props
+ * @param {Array<{label: string, icon?: React.ReactNode, onClick?: Function}>} props.items - Breadcrumb items, last one is active
+ * @param {string} [props.className]
+ * @param {Object} [props.style]
+ *
+ * @example
+ * <Breadcrumb items={[
+ *   { label: "Cockpit", onClick: () => navigate("/") },
+ *   { label: "Application", icon: <FolderOpen size={13} /> },
+ * ]} />
+ */
+export default function Breadcrumb({
+  items = [],
+  className = "",
+  style = {},
+}) {
+  return (
+    <nav className={`neptune-breadcrumb ${className}`} style={style} aria-label="Breadcrumb">
+      {items.map((item, i) => {
+        const isLast = i === items.length - 1;
+        return (
+          <span key={i} style={{ display: "contents" }}>
+            {i > 0 && <span className="neptune-breadcrumb__separator">/</span>}
+            <button
+              className={`neptune-breadcrumb__item ${isLast ? "neptune-breadcrumb__item--active" : ""}`}
+              onClick={!isLast ? item.onClick : undefined}
+              aria-current={isLast ? "page" : undefined}
+            >
+              {item.icon}
+              <span>{item.label}</span>
+            </button>
+          </span>
+        );
+      })}
+    </nav>
+  );
+}

package/components/navigation/Dropdown.jsx

@@ -0,0 +1,104 @@
+import { Check } from "lucide-react";
+
+/**
+ * Dropdown component for menu selection with check mark on active item
+ * Displays a list of selectable items with visual indication of the selected item.
+ * Supports both simple string items and rich object items with subtitles and extras.
+ *
+ * Styles are in neptune-components.css. Only pass `style` for truly dynamic overrides.
+ *
+ * @component
+ * @param {Object} props - Component props
+ * @param {Array<string | {id: string, label: string, subtitle?: string, extra?: React.ReactNode}>} props.items - Array of item labels (strings) or rich item objects
+ * @param {number} [props.selectedIndex=0] - Index of the currently selected item
+ * @param {Function} props.onSelect - Callback fired when an item is selected, receives the item index
+ * @param {Function} [props.renderItem] - Custom render function: (item, index, isSelected) => ReactNode. Overrides default rendering when provided.
+ * @param {boolean} [props.open=true] - Whether the dropdown is visible
+ * @param {string} [props.className] - Additional CSS classes
+ * @param {Object} [props.style] - Inline styles
+ * @returns {JSX.Element} Styled dropdown menu
+ *
+ * @example
+ * // Basic dropdown with strings (backward compatible)
+ * const [selected, setSelected] = useState(0);
+ * <Dropdown
+ *   items={['Option A', 'Option B', 'Option C']}
+ *   selectedIndex={selected}
+ *   onSelect={setSelected}
+ * />
+ *
+ * @example
+ * // Rich items with subtitles
+ * <Dropdown
+ *   items={[
+ *     { id: 'a', label: 'Option A', subtitle: 'Description of A' },
+ *     { id: 'b', label: 'Option B', subtitle: 'Description of B', extra: <Badge label="New" /> },
+ *   ]}
+ *   selectedIndex={0}
+ *   onSelect={setSelected}
+ * />
+ *
+ * @example
+ * // Custom renderItem
+ * <Dropdown
+ *   items={myItems}
+ *   selectedIndex={0}
+ *   onSelect={setSelected}
+ *   renderItem={(item, index, isSelected) => (
+ *     <div>{item.label} {isSelected && '(selected)'}</div>
+ *   )}
+ * />
+ */
+export default function Dropdown({
+  items = [],
+  selectedIndex = 0,
+  onSelect,
+  renderItem,
+  open = true,
+  className = "",
+  style = {},
+  ...props
+}) {
+  return (
+    <div
+      className={`neptune-dropdown ${!open ? "neptune-dropdown--closed" : ""} ${className}`}
+      style={style}
+      {...props}
+    >
+      {items.map((item, index) => {
+        const isSelected = index === selectedIndex;
+        const isString = typeof item === "string";
+        const label = isString ? item : item.label;
+        const subtitle = isString ? undefined : item.subtitle;
+        const extra = isString ? undefined : item.extra;
+
+        return (
+          <button
+            key={isString ? index : (item.id || index)}
+            className={`neptune-dropdown__item ${isSelected ? "neptune-dropdown__item--selected" : ""}`}
+            onClick={() => onSelect && onSelect(index)}
+          >
+            {renderItem ? (
+              renderItem(item, index, isSelected)
+            ) : (
+              <>
+                <div className="neptune-dropdown__item-content">
+                  <span className="neptune-dropdown__item-label">{label}</span>
+                  {subtitle && <span className="neptune-dropdown__item-subtitle">{subtitle}</span>}
+                </div>
+                <div className="neptune-dropdown__item-right">
+                  {extra && <span className="neptune-dropdown__item-extra">{extra}</span>}
+                  {isSelected && (
+                    <span className="neptune-dropdown__item-check">
+                      <Check size={16} />
+                    </span>
+                  )}
+                </div>
+              </>
+            )}
+          </button>
+        );
+      })}
+    </div>
+  );
+}

package/components/navigation/SidebarNav.jsx

@@ -0,0 +1,82 @@
+/**
+ * SidebarNav component for main navigation sidebar with expanded and collapsed modes
+ * Supports both icon + label display (expanded) and icon-only (collapsed) layouts.
+ * Items can include dividers via `{type: "divider"}` to visually separate nav sections.
+ * Optional header and footer props for logo/branding and bottom-anchored controls.
+ *
+ * Styles are in neptune-components.css. Only pass `style` for truly dynamic overrides.
+ *
+ * @component
+ * @param {Object} props - Component props
+ * @param {Array<{label: string, icon: React.ReactNode, active?: boolean} | {type: "divider"}>} props.items - Navigation items with labels and icons, or divider objects
+ * @param {boolean} [props.collapsed=false] - Whether sidebar is in collapsed mode (icon-only)
+ * @param {Function} [props.onItemClick] - Callback fired when a nav item is clicked, receives (item, index)
+ * @param {React.ReactNode} [props.header] - Content rendered at the top of the nav (e.g. logo area)
+ * @param {React.ReactNode} [props.footer] - Content rendered at the bottom of the nav (e.g. settings, collapse toggle)
+ * @param {string} [props.className] - Additional CSS classes
+ * @param {Object} [props.style] - Inline styles
+ * @returns {JSX.Element} Styled sidebar navigation component
+ *
+ * @example
+ * // With header and footer
+ * <SidebarNav
+ *   items={[
+ *     { label: 'Home', icon: <HomeIcon />, active: true },
+ *     { label: 'Projects', icon: <AppWindowIcon /> },
+ *     { type: 'divider' },
+ *     { label: 'Settings', icon: <SettingsIcon /> },
+ *   ]}
+ *   header={<div className="logo-area">Neptune</div>}
+ *   footer={<button>Collapse</button>}
+ *   collapsed={false}
+ *   onItemClick={(item, index) => console.log(item.label)}
+ * />
+ */
+export default function SidebarNav({
+  items = [],
+  collapsed = false,
+  onItemClick,
+  header,
+  footer,
+  className = "",
+  style = {},
+  ...props
+}) {
+  return (
+    <nav
+      className={`neptune-sidebar-nav ${collapsed ? "neptune-sidebar-nav--collapsed" : ""} ${className}`}
+      style={style}
+      {...props}
+    >
+      {header && (
+        <div className="neptune-sidebar-nav__header">{header}</div>
+      )}
+      <div className="neptune-sidebar-nav__items">
+        {items.map((item, index) => {
+          if (item.type === "divider") {
+            return <div key={`divider-${index}`} className="neptune-sidebar-nav__divider" />;
+          }
+          const isActive = item.active ?? false;
+          return (
+            <button
+              key={index}
+              className={`neptune-sidebar-nav__item ${isActive ? "neptune-sidebar-nav__item--active" : ""}`}
+              onClick={() => onItemClick && onItemClick(item, index)}
+              title={collapsed ? item.label : undefined}
+            >
+              <span className="neptune-sidebar-nav__icon">
+                {item.icon}
+              </span>
+              {!collapsed && (
+                <span className="neptune-sidebar-nav__label">{item.label}</span>
+              )}
+            </button>
+          );
+        })}
+      </div>
+      {footer && (
+        <div className="neptune-sidebar-nav__footer">{footer}</div>
+      )}
+    </nav>
+  );
+}

package/components/navigation/SidebarTabs.jsx

@@ -0,0 +1,99 @@
+/**
+ * SidebarTabs component for tab switching within sidebar panels
+ * Displays tabs in horizontal pill-style layout when expanded,
+ * and as a vertical icon column when collapsed.
+ * Tabs can be simple strings or objects with icon, label, activeColor, and badge.
+ *
+ * Styles are in neptune-components.css. Only pass `style` for truly dynamic overrides.
+ *
+ * @component
+ * @param {Object} props - Component props
+ * @param {Array<string | {label: string, icon?: React.ReactNode, activeColor?: string, badge?: React.ReactNode}>} props.tabs
+ *   Array of tab labels (strings) or objects with label, optional icon, optional activeColor, optional badge
+ * @param {number} [props.activeIndex=0] - Index of the currently active tab
+ * @param {Function} props.onChange - Callback fired when a tab is clicked, receives the new index
+ * @param {boolean} [props.collapsed=false] - Whether sidebar is in collapsed mode (icon-only vertical)
+ * @param {string} [props.className] - Additional CSS classes
+ * @param {Object} [props.style] - Inline styles
+ * @returns {JSX.Element} Styled sidebar tab switcher
+ *
+ * @example
+ * // String tabs (backward compatible)
+ * const [activeTab, setActiveTab] = useState(0);
+ * <SidebarTabs
+ *   tabs={['Files', 'Pages', 'Components']}
+ *   activeIndex={activeTab}
+ *   onChange={setActiveTab}
+ *   collapsed={false}
+ * />
+ *
+ * @example
+ * // Tabs with icons, custom active color, and badges
+ * <SidebarTabs
+ *   tabs={[
+ *     { label: 'Naia', icon: <NaiaLogo size={11} />, activeColor: 'var(--npt-accent-secondary)' },
+ *     { label: 'More Agents', icon: <BotIcon size={11} /> },
+ *     { label: 'Versions', icon: <HistoryIcon size={11} />, badge: '5' },
+ *   ]}
+ *   activeIndex={activeTab}
+ *   onChange={setActiveTab}
+ * />
+ */
+export default function SidebarTabs({
+  tabs = [],
+  activeIndex = 0,
+  onChange,
+  collapsed = false,
+  className = "",
+  style = {},
+  ...props
+}) {
+  return (
+    <div
+      className={`neptune-sidebar-tabs ${collapsed ? "neptune-sidebar-tabs--collapsed" : ""} ${className}`}
+      style={style}
+      {...props}
+    >
+      {tabs.map((tab, index) => {
+        const isString = typeof tab === "string";
+        const label = isString ? tab : tab.label;
+        const icon = isString ? undefined : tab.icon;
+        const activeColor = isString ? undefined : tab.activeColor;
+        const badge = isString ? undefined : tab.badge;
+        const isActive = index === activeIndex;
+
+        // If this tab has a custom activeColor and is active, apply it to the bottom border
+        const tabStyle = isActive && activeColor
+          ? { borderBottomColor: activeColor }
+          : undefined;
+
+        // For the icon, apply activeColor when active
+        const iconStyle = isActive && activeColor
+          ? { color: activeColor }
+          : undefined;
+
+        return (
+          <button
+            key={index}
+            className={`neptune-sidebar-tabs__tab ${isActive ? "neptune-sidebar-tabs__tab--active" : ""}`}
+            style={tabStyle}
+            onClick={() => onChange && onChange(index)}
+            title={collapsed ? label : undefined}
+          >
+            {collapsed ? (
+              icon || label.charAt(0).toUpperCase()
+            ) : (
+              <>
+                {icon && <span className="neptune-sidebar-tabs__icon" style={iconStyle}>{icon}</span>}
+                {label}
+                {badge != null && (
+                  <span className="neptune-sidebar-tabs__badge">{badge}</span>
+                )}
+              </>
+            )}
+          </button>
+        );
+      })}
+    </div>
+  );
+}

package/components/navigation/TabBar.jsx

@@ -0,0 +1,61 @@
+/**
+ * TabBar component for horizontal tab navigation with underline active indicator
+ * Displays a row of tabs with visual indication of the active tab.
+ * Tabs can be simple strings or objects with icon and label.
+ *
+ * Styles are in neptune-components.css. Only pass `style` for truly dynamic overrides.
+ *
+ * @component
+ * @param {Object} props - Component props
+ * @param {Array<string | {label: string, icon?: React.ReactNode}>} props.tabs - Array of tab labels (strings) or objects with label and optional icon
+ * @param {number} [props.activeIndex=0] - Index of the currently active tab
+ * @param {Function} props.onChange - Callback fired when a tab is clicked, receives the new index
+ * @param {string} [props.className] - Additional CSS classes
+ * @param {Object} [props.style] - Inline styles
+ * @returns {JSX.Element} Styled horizontal tab bar with underline indicator
+ *
+ * @example
+ * // Basic usage with strings (backward compatible)
+ * const [activeTab, setActiveTab] = useState(0);
+ * <TabBar tabs={['Overview', 'Details', 'Settings']} activeIndex={activeTab} onChange={setActiveTab} />
+ *
+ * @example
+ * // Tabs with icons
+ * <TabBar
+ *   tabs={[
+ *     { label: 'Pages', icon: <LayoutIcon size={13} /> },
+ *     { label: 'Scripts', icon: <CodeIcon size={13} /> },
+ *   ]}
+ *   activeIndex={activeTab}
+ *   onChange={setActiveTab}
+ * />
+ */
+export default function TabBar({
+  tabs = [],
+  activeIndex = 0,
+  onChange,
+  className = "",
+  style = {},
+  ...props
+}) {
+  return (
+    <div className={`neptune-tabbar ${className}`} style={style} {...props}>
+      {tabs.map((tab, index) => {
+        const isString = typeof tab === "string";
+        const label = isString ? tab : tab.label;
+        const icon = isString ? undefined : tab.icon;
+
+        return (
+          <button
+            key={index}
+            className={`neptune-tabbar__tab ${index === activeIndex ? "neptune-tabbar__tab--active" : ""}`}
+            onClick={() => onChange && onChange(index)}
+          >
+            {icon && <span className="neptune-tabbar__icon">{icon}</span>}
+            {label}
+          </button>
+        );
+      })}
+    </div>
+  );
+}

package/components/overlays/Modal.jsx

@@ -0,0 +1,101 @@
+import { useEffect, useCallback } from "react";
+
+/**
+ * Modal — General-purpose modal overlay
+ *
+ * Styles are in neptune-components.css. Only pass `style` for truly dynamic overrides.
+ *
+ * A centered overlay dialog with a backdrop, rounded panel, header with title
+ * and close button. Closes on Escape key press and backdrop click.
+ * Uses surface-overlay for background, border-default for the border, and
+ * shadow-xl for elevation.
+ *
+ * @component
+ * @param {Object} props - Component props
+ * @param {boolean} [props.open=false] - Whether the modal is visible
+ * @param {Function} [props.onClose] - Called when the modal should close (Escape, backdrop, close button)
+ * @param {string} [props.title] - Header title text
+ * @param {React.ReactNode} [props.children] - Modal body content
+ * @param {string} [props.width='480px'] - Panel width (CSS value)
+ * @param {string} [props.className] - Additional CSS classes for the panel
+ * @param {React.CSSProperties} [props.style] - Additional inline styles for the panel
+ * @returns {JSX.Element|null} Modal component or null when closed
+ *
+ * @example
+ * <Modal open={isOpen} onClose={() => setIsOpen(false)} title="Confirm">
+ *   <p>Are you sure?</p>
+ * </Modal>
+ *
+ * @example
+ * <Modal open={true} onClose={handleClose} title="Settings" width="600px">
+ *   <SettingsForm />
+ * </Modal>
+ */
+export default function Modal({
+  open = false,
+  onClose,
+  title,
+  children,
+  width = "480px",
+  className = "",
+  style = {},
+}) {
+  const handleKeyDown = useCallback(
+    (e) => {
+      if (e.key === "Escape" && onClose) {
+        onClose();
+      }
+    },
+    [onClose]
+  );
+
+  useEffect(() => {
+    if (open) {
+      document.addEventListener("keydown", handleKeyDown);
+      return () => document.removeEventListener("keydown", handleKeyDown);
+    }
+  }, [open, handleKeyDown]);
+
+  if (!open) return null;
+
+  const handleBackdropClick = (e) => {
+    if (e.target === e.currentTarget && onClose) {
+      onClose();
+    }
+  };
+
+  return (
+    <div
+      className="neptune-modal-backdrop"
+      onClick={handleBackdropClick}
+      role="dialog"
+      aria-modal="true"
+      aria-label={title || "Dialog"}
+    >
+      <div
+        className={`neptune-modal ${className}`}
+        style={{ width, ...style }}
+      >
+        {title && (
+          <div className="neptune-modal__header">
+            <h2 className="neptune-modal__title">{title}</h2>
+            <button
+              className="neptune-modal__close"
+              onClick={onClose}
+              aria-label="Close dialog"
+              title="Close"
+            >
+              <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+                <line x1="18" y1="6" x2="6" y2="18" />
+                <line x1="6" y1="6" x2="18" y2="18" />
+              </svg>
+            </button>
+          </div>
+        )}
+        <div className="neptune-modal__body">
+          {children}
+        </div>
+      </div>
+    </div>
+  );
+}