@inversestudio/neptune-components 1.0.0

package/components/inputs/PillSelect.jsx

@@ -0,0 +1,175 @@
+import { useState, useRef, useEffect, cloneElement, isValidElement } from "react";
+import { ChevronDown, Check } from "lucide-react";
+
+/**
+ * PillSelect — Pill-shaped dropdown select for compact option picking
+ *
+ * Styles are in neptune-components.css. Only pass `style` for truly dynamic overrides.
+ *
+ * Renders a small pill trigger that opens an upward dropdown menu. Used in
+ * the Naia chat input footer for mode, model, and autonomy selectors.
+ * Options can carry custom colors (for mode pill), descriptions, badges,
+ * and icons. Theme-aware via --npt- tokens.
+ *
+ * @component
+ * @param {Object} props
+ * @param {string} props.value - Currently selected option id
+ * @param {Array<{id: string, label: string, desc?: string, badge?: string, icon?: React.ReactNode, color?: string, colorBg?: string, colorText?: string}>} props.options - Selectable options
+ * @param {Function} props.onChange - Called with selected option id
+ * @param {React.ReactNode} [props.icon] - Optional icon rendered before the label in the trigger
+ * @param {"left"|"right"} [props.align="left"] - Dropdown horizontal alignment
+ * @param {string} [props.className] - Additional CSS classes
+ * @param {React.CSSProperties} [props.style] - Additional inline styles
+ * @returns {JSX.Element} PillSelect component
+ *
+ * @example
+ * <PillSelect
+ *   value="code"
+ *   options={[
+ *     { id: "code", label: "Code", colorBg: "var(--npt-accent-secondary)", colorText: "var(--npt-accent-secondary)" },
+ *     { id: "plan", label: "Plan" },
+ *   ]}
+ *   onChange={(id) => setMode(id)}
+ * />
+ *
+ * @example
+ * // With icon and right-aligned dropdown
+ * <PillSelect
+ *   value="opus"
+ *   icon={<NaiaLogo size={12} />}
+ *   align="right"
+ *   options={[{ id: "opus", label: "Opus 4.6" }, { id: "sonnet", label: "Sonnet 4" }]}
+ *   onChange={setModel}
+ * />
+ */
+export default function PillSelect({
+  value,
+  options = [],
+  onChange,
+  icon,
+  align = "left",
+  className = "",
+  style = {},
+}) {
+  const [open, setOpen] = useState(false);
+  const containerRef = useRef(null);
+
+  const selected = options.find((o) => o.id === value);
+
+  // Close on outside click
+  useEffect(() => {
+    if (!open) return;
+    const handleClick = (e) => {
+      if (containerRef.current && !containerRef.current.contains(e.target)) {
+        setOpen(false);
+      }
+    };
+    document.addEventListener("mousedown", handleClick);
+    return () => document.removeEventListener("mousedown", handleClick);
+  }, [open]);
+
+  // Close on Escape
+  useEffect(() => {
+    if (!open) return;
+    const handleKey = (e) => {
+      if (e.key === "Escape") setOpen(false);
+    };
+    document.addEventListener("keydown", handleKey);
+    return () => document.removeEventListener("keydown", handleKey);
+  }, [open]);
+
+  const hasCustomColors = selected?.colorBg && selected?.colorText;
+
+  // Dynamic trigger styles only for custom colors — otherwise CSS handles it
+  const triggerDynamicStyle = hasCustomColors
+    ? {
+        background: selected.colorBg,
+        color: selected.colorText,
+        borderColor: `color-mix(in srgb, ${selected.colorText} 40%, transparent)`,
+        ...style,
+      }
+    : style;
+
+  const handleSelect = (id) => {
+    if (onChange) onChange(id);
+    setOpen(false);
+  };
+
+  return (
+    <div
+      ref={containerRef}
+      className={`neptune-pill-select ${className}`}
+    >
+      {/* Trigger */}
+      <button
+        className="neptune-pill-select__trigger"
+        style={triggerDynamicStyle}
+        onClick={() => setOpen((prev) => !prev)}
+        aria-haspopup="listbox"
+        aria-expanded={open}
+        aria-label={selected ? `${selected.label} selected` : "Select option"}
+      >
+        {icon && <span className="neptune-pill-select__trigger-icon">{
+          isValidElement(icon) && selected?.colorText
+            ? cloneElement(icon, { color: selected.colorText })
+            : icon
+        }</span>}
+        <span className="neptune-pill-select__trigger-label">
+          {selected?.label ?? "Select"}
+        </span>
+        <ChevronDown
+          size={10}
+          className={`neptune-pill-select__chevron ${open ? "neptune-pill-select__chevron--open" : ""}`}
+        />
+      </button>
+
+      {/* Dropdown menu */}
+      {open && (
+        <div className={`neptune-pill-select__dropdown neptune-pill-select__dropdown--${align}`} role="listbox">
+          {options.map((opt) => {
+            const isSelected = opt.id === value;
+
+            return (
+              <button
+                key={opt.id}
+                role="option"
+                aria-selected={isSelected}
+                className={`neptune-pill-select__item ${isSelected ? "neptune-pill-select__item--selected" : ""}`}
+                onClick={() => handleSelect(opt.id)}
+              >
+                {/* Check icon column */}
+                <span className="neptune-pill-select__item-check">
+                  <Check size={10} />
+                </span>
+
+                {/* Label + desc column */}
+                <span className="neptune-pill-select__item-content">
+                  <span className="neptune-pill-select__item-label-row">
+                    {opt.icon && (
+                      <span className="neptune-pill-select__item-icon">
+                        {opt.icon}
+                      </span>
+                    )}
+                    <span className="neptune-pill-select__item-label">
+                      {opt.label}
+                    </span>
+                    {opt.badge && (
+                      <span className="neptune-pill-select__item-badge">
+                        {opt.badge}
+                      </span>
+                    )}
+                  </span>
+                  {opt.desc && (
+                    <span className="neptune-pill-select__item-desc">
+                      {opt.desc}
+                    </span>
+                  )}
+                </span>
+              </button>
+            );
+          })}
+        </div>
+      )}
+    </div>
+  );
+}

package/components/inputs/PropertyField.jsx

@@ -0,0 +1,58 @@
+/**
+ * PropertyField — Label + monospace input for property editors
+ *
+ * Styles are in neptune-components.css. Only pass `style` for truly dynamic overrides.
+ *
+ * Used in settings panels and modals for editing key-value pairs.
+ * Supports a highlight state for modified/active properties.
+ *
+ * @component
+ * @param {Object} props
+ * @param {string} props.label - Property name/label
+ * @param {string} [props.value=''] - Current value
+ * @param {Function} [props.onChange] - Change handler, receives event
+ * @param {boolean} [props.highlight=false] - Whether to show accent highlight (modified state)
+ * @param {number} [props.labelWidth=144] - Label width in px
+ * @param {boolean} [props.disabled=false]
+ * @param {string} [props.className]
+ * @param {Object} [props.style]
+ *
+ * @example
+ * <PropertyField label="Name" value="OrderList" onChange={handleChange} />
+ *
+ * @example
+ * <PropertyField label="title" value="Home" highlight />
+ */
+export default function PropertyField({
+  label,
+  value = "",
+  onChange,
+  highlight = false,
+  labelWidth = 144,
+  disabled = false,
+  className = "",
+  style = {},
+}) {
+  return (
+    <div
+      className={`neptune-property-field ${highlight ? "neptune-property-field--highlight" : ""} ${
+        disabled ? "neptune-property-field--disabled" : ""
+      } ${className}`}
+      style={style}
+    >
+      <span
+        className="neptune-property-field__label"
+        style={{ width: `${labelWidth}px` }}
+      >
+        {label}
+      </span>
+      <input
+        type="text"
+        defaultValue={value}
+        onChange={onChange}
+        disabled={disabled}
+        className="neptune-property-field__input"
+      />
+    </div>
+  );
+}

package/components/inputs/SuggestionPill.jsx

@@ -0,0 +1,28 @@
+/**
+ * SuggestionPill — Chip button for AI quick-action suggestions
+ *
+ * Styles are in neptune-components.css. Only pass `style` for truly dynamic overrides.
+ *
+ * @component
+ * @param {Object} props
+ * @param {React.ReactNode} props.children - Pill label text
+ * @param {Function} [props.onClick]
+ * @param {string} [props.className]
+ * @param {Object} [props.style] - Dynamic inline overrides only
+ */
+export default function SuggestionPill({
+  children,
+  onClick,
+  className = "",
+  style = {},
+}) {
+  return (
+    <button
+      className={`neptune-suggestion-pill ${className}`}
+      style={style}
+      onClick={onClick}
+    >
+      {children}
+    </button>
+  );
+}

package/components/inputs/TextInput.jsx

@@ -0,0 +1,96 @@
+import { Search } from "lucide-react";
+
+/**
+ * TextInput component for text entry
+ * Supports search variant with optional keyboard shortcut hint display
+ *
+ * Styles are in neptune-components.css. Only pass `style` for truly dynamic overrides.
+ *
+ * @component
+ * @param {Object} props - Component props
+ * @param {string} [props.value] - Current input value
+ * @param {Function} [props.onChange] - Change handler that receives the event
+ * @param {string} [props.placeholder=''] - Placeholder text
+ * @param {string} [props.label] - Optional label text displayed above input
+ * @param {string} [props.variant='default'] - Input style: 'default' | 'search'
+ * @param {string} [props.shortcutHint] - Keyboard shortcut hint (e.g., '⌘K') displayed in search variant
+ * @param {boolean} [props.disabled=false] - Whether the input is disabled
+ * @param {string} [props.className] - Additional CSS classes
+ * @param {Object} [props.style] - Inline styles
+ * @returns {JSX.Element} Styled input element with optional label
+ *
+ * @example
+ * // Basic input
+ * <TextInput
+ *   placeholder="Enter text..."
+ *   value={text}
+ *   onChange={(e) => setText(e.target.value)}
+ * />
+ *
+ * @example
+ * // Search input with shortcut hint
+ * <TextInput
+ *   variant="search"
+ *   placeholder="Search..."
+ *   shortcutHint="⌘K"
+ *   value={search}
+ *   onChange={(e) => setSearch(e.target.value)}
+ * />
+ *
+ * @example
+ * // Input with label
+ * <TextInput
+ *   label="Email Address"
+ *   placeholder="user@example.com"
+ *   value={email}
+ *   onChange={(e) => setEmail(e.target.value)}
+ * />
+ */
+export default function TextInput({
+  value,
+  onChange,
+  placeholder = "",
+  label,
+  variant = "default",
+  shortcutHint,
+  disabled = false,
+  className = "",
+  style = {},
+  ...props
+}) {
+  return (
+    <div className={`neptune-text-input neptune-text-input--${variant} ${disabled ? "neptune-text-input--disabled" : ""} ${className}`}>
+      {label && (
+        <label className="neptune-text-input__label">
+          {label}
+        </label>
+      )}
+
+      <div className="neptune-text-input__wrapper">
+        {variant === "search" && (
+          <Search
+            size={16}
+            className="neptune-text-input__search-icon"
+          />
+        )}
+
+        <input
+          type="text"
+          value={value}
+          onChange={onChange}
+          placeholder={placeholder}
+          disabled={disabled}
+          className="neptune-text-input__field"
+          style={style}
+          {...props}
+        />
+
+        {variant === "search" && shortcutHint && (
+          <span className="neptune-text-input__shortcut-hint">
+            {shortcutHint}
+          </span>
+        )}
+      </div>
+    </div>
+  );
+}

package/components/inputs/Toggle.jsx

@@ -0,0 +1,73 @@
+/**
+ * Toggle switch component for boolean state control
+ *
+ * Styles are in neptune-components.css. Only pass `style` for truly dynamic overrides.
+ *
+ * Active state uses green (success) in base theme. In a data-theme="naia"
+ * container, active state automatically uses purple via accent-primary.
+ *
+ * @component
+ * @param {Object} props - Component props
+ * @param {boolean} [props.checked=false] - Whether the toggle is in the on state
+ * @param {Function} [props.onChange] - Change handler that receives the new boolean value
+ * @param {string} [props.label] - Optional label text displayed next to toggle
+ * @param {boolean} [props.disabled=false] - Whether the toggle is disabled
+ * @param {string} [props.className] - Additional CSS classes
+ * @param {Object} [props.style] - Inline styles
+ * @returns {JSX.Element} Styled toggle switch element
+ *
+ * @example
+ * <Toggle checked={isEnabled} onChange={setIsEnabled} />
+ *
+ * @example
+ * <Toggle label="Dark mode" checked={isDark} onChange={setIsDark} />
+ *
+ * @example
+ * // Naia-themed: purple active state
+ * <div data-theme="naia">
+ *   <Toggle checked={true} onChange={fn} />
+ * </div>
+ */
+export default function Toggle({
+  checked = false,
+  onChange,
+  label,
+  size = "default",
+  disabled = false,
+  className = "",
+  style = {},
+  ...props
+}) {
+  const handleToggle = () => {
+    if (!disabled && onChange) {
+      onChange(!checked);
+    }
+  };
+
+  return (
+    <label
+      className={`neptune-toggle ${size === "sm" ? "neptune-toggle--sm" : ""} ${
+        checked ? "neptune-toggle--checked" : ""
+      } ${disabled ? "neptune-toggle--disabled" : ""} ${className}`}
+      style={style}
+      {...props}
+    >
+      <button
+        className="neptune-toggle__switch"
+        onClick={handleToggle}
+        disabled={disabled}
+        role="switch"
+        aria-checked={checked}
+        type="button"
+      >
+        <span className="neptune-toggle__thumb" />
+      </button>
+
+      {label && (
+        <span className="neptune-toggle__label">
+          {label}
+        </span>
+      )}
+    </label>
+  );
+}

package/components/layout/AppHeader.jsx

@@ -0,0 +1,56 @@
+/**
+ * AppHeader — Top-level application header bar
+ *
+ * Styles are in neptune-components.css. Only pass `style` for truly dynamic overrides.
+ *
+ * Flexible slot-based layout: left (logo + breadcrumb), right (actions + avatar),
+ * and children (middle content). All content is passed as props — the component
+ * provides the container styling only.
+ *
+ * @component
+ * @param {Object} props
+ * @param {React.ReactNode} props.left - Left content (logo, breadcrumb, title)
+ * @param {React.ReactNode} [props.right] - Right content (buttons, icons, avatar)
+ * @param {React.ReactNode} [props.children] - Middle content (optional)
+ * @param {string} [props.variant='default'] - 'default' | 'builder' (adjusts padding)
+ * @param {string} [props.className]
+ * @param {Object} [props.style]
+ *
+ * @example
+ * <AppHeader
+ *   variant="builder"
+ *   left={<><NeptuneLogo size={28} /><Breadcrumb items={[...]} /></>}
+ *   right={<>
+ *     <Button variant="ghost" size="sm" icon={<Info size={10} />}>Learning Hub</Button>
+ *     <IconButton variant="subtle" icon={<Search size={14} />} title="Search" />
+ *     <Avatar initials="M" />
+ *   </>}
+ * />
+ */
+export default function AppHeader({
+  left,
+  right,
+  children,
+  variant = "default",
+  className = "",
+  style = {},
+}) {
+  return (
+    <header
+      className={`neptune-app-header ${variant === "builder" ? "neptune-app-header--builder" : ""} ${className}`}
+      style={style}
+    >
+      <div className="neptune-app-header__left">
+        {left}
+      </div>
+
+      {children}
+
+      {right && (
+        <div className="neptune-app-header__right">
+          {right}
+        </div>
+      )}
+    </header>
+  );
+}

package/components/layout/BottomBar.jsx

@@ -0,0 +1,81 @@
+import StatusDot from "../feedback/StatusDot.jsx";
+
+/**
+ * BottomBar — Bottom status bar with breakpoint and theme toggles
+ *
+ * Styles are in neptune-components.css. Only pass `style` for truly dynamic overrides.
+ *
+ * Breakpoints and themes accept either strings ("Mobile") or objects
+ * ({ id: "tablet", icon: <TabletIcon />, label: "Tablet" }) for icon-only buttons.
+ *
+ * @component
+ * @param {Object} props
+ * @param {Object} [props.status] - Status indicator { label, status, pulse, color }
+ * @param {Array} [props.breakpoints=[]] - Breakpoint items (string or { id, icon, label })
+ * @param {string} [props.activeBreakpoint] - Currently active breakpoint id/name
+ * @param {Function} [props.onBreakpointChange] - Callback(id)
+ * @param {Array} [props.themes=[]] - Theme items (string or { id, icon, label })
+ * @param {string} [props.activeTheme] - Currently active theme id/name
+ * @param {Function} [props.onThemeChange] - Callback(id)
+ * @param {string} [props.className]
+ * @param {Object} [props.style]
+ */
+export default function BottomBar({
+  status,
+  breakpoints = [],
+  activeBreakpoint,
+  onBreakpointChange,
+  themes = [],
+  activeTheme,
+  onThemeChange,
+  className = "",
+  style = {},
+}) {
+  const renderItem = (item, activeId, onChange) => {
+    const isObj = typeof item === "object" && item !== null;
+    const id = isObj ? item.id : item;
+    const label = isObj ? item.label : item;
+    const icon = isObj ? item.icon : null;
+    const isActive = activeId === id;
+
+    return (
+      <button
+        key={id}
+        className={`neptune-bottom-bar__btn ${isActive ? "neptune-bottom-bar__btn--active" : ""}`}
+        onClick={() => onChange && onChange(id)}
+        title={label}
+      >
+        {icon || label}
+      </button>
+    );
+  };
+
+  return (
+    <div className={`neptune-bottom-bar ${className}`} style={style}>
+      {status && (
+        <div className="neptune-bottom-bar__status">
+          <StatusDot
+            status={status.status || "success"}
+            pulse={status.pulse}
+            color={status.color}
+          />
+          <span className="neptune-bottom-bar__status-label">
+            {status.label}
+          </span>
+        </div>
+      )}
+
+      {breakpoints.length > 0 && (
+        <div className="neptune-bottom-bar__group">
+          {breakpoints.map((bp) => renderItem(bp, activeBreakpoint, onBreakpointChange))}
+        </div>
+      )}
+
+      {themes.length > 0 && (
+        <div className="neptune-bottom-bar__group">
+          {themes.map((th) => renderItem(th, activeTheme, onThemeChange))}
+        </div>
+      )}
+    </div>
+  );
+}

package/components/layout/Card.jsx

@@ -0,0 +1,57 @@
+/**
+ * Card — Generic card container with optional interactivity
+ *
+ * Styles are in neptune-components.css. Only pass `style` for truly dynamic overrides.
+ *
+ * A versatile card component with surface-raised background, subtle border,
+ * and rounded corners. When `interactive` is true and `onClick` is provided,
+ * the card gains a hover shadow and pointer cursor, making it suitable for
+ * clickable list items, selection cards, or dashboard tiles.
+ *
+ * Different from Panel (which is a simpler wrapper). Card supports hover
+ * elevation and click interactions.
+ *
+ * @component
+ * @param {Object} props - Component props
+ * @param {React.ReactNode} [props.children] - Card content
+ * @param {Function} [props.onClick] - Click handler (only effective when interactive)
+ * @param {boolean} [props.interactive=false] - Enables hover effects and pointer cursor
+ * @param {string} [props.className] - Additional CSS classes
+ * @param {React.CSSProperties} [props.style] - Additional inline styles
+ * @returns {JSX.Element} Card component
+ *
+ * @example
+ * // Static card
+ * <Card>
+ *   <h3>Dashboard</h3>
+ *   <p>Overview of your metrics.</p>
+ * </Card>
+ *
+ * @example
+ * // Interactive card
+ * <Card interactive onClick={() => navigate("/details")}>
+ *   <h3>Project Alpha</h3>
+ *   <p>Click to view details</p>
+ * </Card>
+ */
+export default function Card({
+  children,
+  onClick,
+  interactive = false,
+  className = "",
+  style = {},
+}) {
+  const isClickable = interactive && onClick;
+  const Tag = isClickable ? "button" : "div";
+
+  return (
+    <Tag
+      className={`neptune-card ${interactive ? "neptune-card--interactive" : ""} ${className}`}
+      style={style}
+      onClick={isClickable ? onClick : undefined}
+      {...(isClickable ? { type: "button" } : {})}
+    >
+      {children}
+    </Tag>
+  );
+}

package/components/layout/Panel.jsx

@@ -0,0 +1,26 @@
+/**
+ * Panel component - General purpose panel/card wrapper
+ *
+ * Styles are in neptune-components.css. Only pass `style` for truly dynamic overrides.
+ *
+ * A versatile container component used throughout the Neptune UI
+ * for grouping and displaying content with consistent styling.
+ * Provides padding, border, background, and shadow using design tokens.
+ *
+ * @component
+ * @param {Object} props - Component props
+ * @param {React.ReactNode} props.children - Panel content
+ * @param {React.CSSProperties} [props.style] - Additional inline styles
+ * @param {string} [props.className] - Additional CSS classes
+ * @returns {JSX.Element} Panel component
+ */
+export default function Panel({ children, style, className = "" }) {
+  return (
+    <div
+      className={`neptune-panel ${className}`}
+      style={style}
+    >
+      {children}
+    </div>
+  );
+}