@inversestudio/neptune-components 1.0.0

package/README.md

@@ -0,0 +1,2 @@
+# neptune-design-system
+Design System for Neptune Cockpit 2.0

package/components/data-display/AppPreview.jsx

@@ -0,0 +1,150 @@
+import { useRef } from "react";
+
+/**
+ * AppPreview — Mock application preview for the builder workspace
+ *
+ * Styles are in neptune-components.css. Only pass `style` for truly dynamic overrides.
+ *
+ * Renders a skeleton wireframe of a typical app page (title bar, filter bar,
+ * data table rows). Uses neutral greys independent of the main theme so the
+ * preview looks like an actual embedded app, not part of the cockpit chrome.
+ *
+ * @component
+ * @param {Object} props
+ * @param {string} [props.title='Filterable List'] - App bar title
+ * @param {string} [props.breakpoint='browser'] - 'browser' | 'tablet' | 'phone'
+ * @param {string} [props.theme='dark'] - 'dark' | 'light' — independent of parent theme
+ * @param {string[]} [props.columns] - Column headers for the table
+ * @param {number} [props.rows=8] - Number of skeleton rows
+ * @param {React.ReactNode} [props.badge] - Optional badge in the title bar (e.g. "Modified by Naia")
+ * @param {string} [props.className]
+ * @param {Object} [props.style]
+ *
+ * @example
+ * <AppPreview title="Order List" breakpoint="browser" theme="dark" />
+ *
+ * @example
+ * <AppPreview breakpoint="phone" theme="light" columns={["ID", "Name"]} rows={6} />
+ */
+export default function AppPreview({
+  title = "Filterable List",
+  breakpoint = "browser",
+  theme = "dark",
+  columns,
+  rows = 8,
+  badge,
+  className = "",
+  style = {},
+}) {
+  const isDark = theme === "dark";
+  const containerRef = useRef(null);
+
+  // Neutral grey palette from --npt-neutral-* tokens
+  const bg      = isDark ? "var(--npt-neutral-900)" : "var(--npt-neutral-50)";
+  const surface = isDark ? "var(--npt-neutral-800)" : "var(--npt-neutral-50)";
+  const dim     = isDark ? "var(--npt-neutral-700)" : "var(--npt-neutral-150)";
+  const border  = isDark ? "var(--npt-neutral-650)" : "var(--npt-neutral-200)";
+  const text    = isDark ? "var(--npt-neutral-150)" : "var(--npt-neutral-900)";
+  const textDim = isDark ? "var(--npt-neutral-400)" : "var(--npt-neutral-400)";
+  const accent  = isDark ? "var(--npt-orange-350)"  : "var(--npt-orange-500)";
+
+  const statusColors = [
+    isDark ? "color-mix(in srgb, var(--npt-green-400) 15%, transparent)"   : "color-mix(in srgb, var(--npt-green-550) 12%, transparent)",
+    isDark ? "color-mix(in srgb, var(--npt-orange-300) 15%, transparent)"  : "color-mix(in srgb, var(--npt-orange-550) 12%, transparent)",
+    isDark ? "color-mix(in srgb, var(--npt-purple-300) 15%, transparent)"  : "color-mix(in srgb, var(--npt-purple-500) 12%, transparent)",
+  ];
+
+  const defaultColumns = breakpoint === "phone"
+    ? []
+    : breakpoint === "tablet"
+      ? ["Order ID", "Customer", "Date"]
+      : ["Order ID", "Customer", "Date", "Amount", "Status"];
+
+  const cols = columns || defaultColumns;
+  const rowCount = breakpoint === "phone" ? Math.min(rows, 6) : rows;
+
+  return (
+    <div
+      ref={containerRef}
+      className={`neptune-app-preview ${className}`}
+      style={{ backgroundColor: bg, ...style }}
+    >
+      <div
+        className={`neptune-app-preview__frame neptune-app-preview__frame--${breakpoint}`}
+        style={{
+          backgroundColor: surface,
+          borderColor: border,
+        }}
+      >
+        {/* App bar */}
+        <div
+          className="neptune-app-preview__titlebar"
+          style={{ backgroundColor: dim, borderColor: border }}
+        >
+          <span style={{ fontSize: 14, fontWeight: 500, color: text }}>{title}</span>
+          {badge}
+        </div>
+
+        {/* Filter bar */}
+        <div
+          className="neptune-app-preview__filterbar"
+          style={{ borderColor: border }}
+        >
+          <div style={{ height: 28, flex: 1, borderRadius: 4, backgroundColor: dim }} />
+          <div style={{ height: 28, width: breakpoint === "phone" ? 60 : 80, borderRadius: 4, backgroundColor: dim }} />
+          {breakpoint !== "phone" && (
+            <div style={{ height: 28, width: 80, borderRadius: 4, backgroundColor: dim }} />
+          )}
+        </div>
+
+        {/* Table header */}
+        <div className="neptune-app-preview__table">
+          {cols.length > 0 && (
+            <div
+              className="neptune-app-preview__row"
+              style={{ borderColor: border }}
+            >
+              {cols.map((col) => (
+                <div key={col} style={{ flex: 1 }}>
+                  <span style={{ fontSize: 12, fontWeight: 500, color: textDim }}>{col}</span>
+                </div>
+              ))}
+            </div>
+          )}
+
+          {/* Skeleton rows */}
+          {[...Array(rowCount)].map((_, i) => (
+            <div
+              key={i}
+              className="neptune-app-preview__row"
+              style={{ borderColor: border }}
+            >
+              {breakpoint === "phone" ? (
+                <div style={{ flex: 1, display: "flex", flexDirection: "column", gap: 6 }}>
+                  <div style={{ height: 8, borderRadius: 4, backgroundColor: dim, width: "70%" }} />
+                  <div style={{ height: 8, borderRadius: 4, backgroundColor: dim, width: "45%" }} />
+                </div>
+              ) : (
+                cols.map((col, j) => (
+                  <div key={j} style={{ flex: 1 }}>
+                    {col === "Status" ? (
+                      <div style={{ height: 16, width: 56, borderRadius: 4, backgroundColor: statusColors[i % 3] }} />
+                    ) : (
+                      <div style={{
+                        height: 8,
+                        borderRadius: 4,
+                        backgroundColor: i === 0 && j === 0 ? accent : dim,
+                        width: j === 0 ? "60%" : j === 1 ? "75%" : j === 2 ? "50%" : "40%",
+                        opacity: i === 0 && j === 0 ? 0.6 : 1,
+                      }} />
+                    )}
+                  </div>
+                ))
+              )}
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}

package/components/data-display/DataTable.jsx

@@ -0,0 +1,65 @@
+/**
+ * DataTable component - Tabular data display with columns and rows
+ *
+ * Styles are in neptune-components.css. Only pass `style` for truly dynamic overrides.
+ *
+ * Renders a data table with headers and rows. Supports custom cell rendering
+ * via renderCell function. Includes proper borders, spacing, and typography.
+ *
+ * @component
+ * @param {Object} props - Component props
+ * @param {string[]} props.columns - Array of column header names
+ * @param {Object[]} props.rows - Array of row objects with data values
+ * @param {Function} [props.renderCell] - Optional function(row, column, index) to customize cell rendering
+ * @returns {JSX.Element} Styled data table
+ *
+ * @example
+ * const columns = ['Name', 'Status', 'Updated'];
+ * const rows = [
+ *   { Name: 'API Service', Status: 'Running', Updated: '2 min ago' },
+ *   { Name: 'Database', Status: 'Running', Updated: '5 min ago' }
+ * ];
+ * <DataTable columns={columns} rows={rows} />
+ */
+export default function DataTable({
+  columns = [],
+  rows = [],
+  renderCell,
+  ...props
+}) {
+  return (
+    <div
+      className="neptune-data-table"
+      {...props}
+    >
+      <table>
+        <thead>
+          <tr>
+            {columns.map((column, idx) => (
+              <th key={idx}>
+                {column}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {rows.map((row, rowIdx) => (
+            <tr key={rowIdx}>
+              {columns.map((column, colIdx) => {
+                const cellContent = renderCell
+                  ? renderCell(row, column, rowIdx)
+                  : row[column];
+
+                return (
+                  <td key={`${rowIdx}-${colIdx}`}>
+                    {cellContent}
+                  </td>
+                );
+              })}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}

package/components/data-display/FileTree.jsx

@@ -0,0 +1,123 @@
+import { useState } from "react";
+import { ChevronDown, ChevronRight, FolderOpen, FileText } from "lucide-react";
+
+/**
+ * FileTreeNode — recursive internal component for rendering tree nodes
+ */
+function FileTreeNode({ item, depth = 0, selectedName, onSelect, parents = [] }) {
+  const [open, setOpen] = useState(item.defaultOpen || item.open || false);
+  const isFolder = !!item.children;
+  const isSelected = !isFolder && selectedName != null && item.name === selectedName;
+
+  function handleClick() {
+    if (isFolder) {
+      setOpen(!open);
+    }
+    if (onSelect) {
+      onSelect(item, { depth, parents, isFolder });
+    }
+  }
+
+  return (
+    <div>
+      <button
+        className={[
+          "neptune-file-tree__item",
+          isFolder && "neptune-file-tree__item--folder",
+          isSelected && "neptune-file-tree__item--active",
+        ].filter(Boolean).join(" ")}
+        style={{ paddingLeft: `${depth * 14 + 10}px` }}
+        onClick={handleClick}
+      >
+        {isFolder
+          ? (open
+            ? <ChevronDown size={12} className="neptune-file-tree__chevron" />
+            : <ChevronRight size={12} className="neptune-file-tree__chevron" />)
+          : <span className="neptune-file-tree__chevron" />}
+        {item.icon ? (
+          <span className="neptune-file-tree__icon">{item.icon}</span>
+        ) : isFolder ? (
+          <FolderOpen size={12} className="neptune-file-tree__icon" />
+        ) : (
+          <FileText size={12} className="neptune-file-tree__icon" />
+        )}
+        <span className="neptune-file-tree__label">{item.name}</span>
+      </button>
+      {isFolder && open && item.children.map((child, i) => (
+        <FileTreeNode
+          key={i}
+          item={child}
+          depth={depth + 1}
+          selectedName={selectedName}
+          onSelect={onSelect}
+          parents={[...parents, item.name]}
+        />
+      ))}
+    </div>
+  );
+}
+
+/**
+ * FileTree component - Hierarchical file and folder tree display with recursive folder support
+ *
+ * Styles are in neptune-components.css. Only pass `style` for truly dynamic overrides.
+ *
+ * Renders a nested file/folder structure with proper indentation based on depth.
+ * Items with `children` arrays are treated as folders that can be opened/closed.
+ * Manages open/close state internally. Supports `defaultOpen` or `open` per item.
+ * Depth-based padding is computed dynamically as an inline style.
+ *
+ * @component
+ * @param {Object} props - Component props
+ * @param {Object[]} props.items - Array of tree items (recursive), each with:
+ *   - {string} name - Item display name
+ *   - {Object[]} [children] - Child items (presence makes it a folder)
+ *   - {boolean} [defaultOpen] - Whether folder starts open (alias: `open`)
+ *   - {React.ReactNode} [icon] - Custom icon to override the default file/folder icon
+ * @param {Function} [props.onSelect] - Callback when an item is clicked: (item, meta)
+ *   - meta: { depth, parents, isFolder }
+ * @param {string} [props.selectedName] - Name of the currently selected item (highlights matching)
+ * @param {string} [props.className] - Additional CSS classes
+ * @param {Object} [props.style] - Inline style overrides
+ * @returns {JSX.Element} Styled file tree
+ *
+ * @example
+ * const items = [
+ *   { name: 'src', children: [
+ *     { name: 'components', children: [
+ *       { name: 'Button.jsx' },
+ *       { name: 'Input.jsx' },
+ *     ], defaultOpen: true },
+ *     { name: 'index.js' },
+ *   ], defaultOpen: true },
+ *   { name: 'package.json' },
+ * ];
+ * <FileTree items={items} selectedName="Button.jsx" onSelect={(item) => console.log(item.name)} />
+ */
+export default function FileTree({
+  items = [],
+  onSelect,
+  selectedName,
+  className = "",
+  style = {},
+  ...props
+}) {
+  return (
+    <div
+      className={`neptune-file-tree ${className}`}
+      style={style}
+      {...props}
+    >
+      {items.map((item, idx) => (
+        <FileTreeNode
+          key={idx}
+          item={item}
+          depth={0}
+          selectedName={selectedName}
+          onSelect={onSelect}
+          parents={[]}
+        />
+      ))}
+    </div>
+  );
+}

package/components/data-display/KpiCard.jsx

@@ -0,0 +1,57 @@
+/**
+ * KpiCard component - Key Performance Indicator card display
+ *
+ * Styles are in neptune-components.css. Only pass `style` for truly dynamic overrides.
+ *
+ * Displays a metric or KPI with an icon, large value, label, and optional subtitle.
+ * Commonly used in dashboards to highlight important metrics and statistics.
+ *
+ * @component
+ * @param {Object} props - Component props
+ * @param {React.ComponentType} props.icon - Icon component to display (receives size prop)
+ * @param {string|number} props.value - The primary value to display prominently
+ * @param {string} props.label - Label describing what the KPI measures
+ * @param {string} [props.subtitle] - Optional additional context or description
+ * @returns {JSX.Element} Styled KPI card
+ *
+ * @example
+ * import { Activity } from 'lucide-react';
+ * <KpiCard
+ *   icon={Activity}
+ *   value="1,234"
+ *   label="Active Deployments"
+ *   subtitle="Up 12% from last week"
+ * />
+ */
+export default function KpiCard({
+  icon: Icon,
+  value,
+  label,
+  subtitle,
+  ...props
+}) {
+  return (
+    <div
+      className="neptune-kpi-card"
+      {...props}
+    >
+      <div className="neptune-kpi-card__icon-wrapper">
+        {Icon && <Icon size={20} />}
+      </div>
+
+      <div className="neptune-kpi-card__content">
+        <div className="neptune-kpi-card__value">
+          {value}
+        </div>
+        <div className="neptune-kpi-card__label">
+          {label}
+        </div>
+        {subtitle && (
+          <div className="neptune-kpi-card__subtitle">
+            {subtitle}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

package/components/data-display/VersionRow.jsx

@@ -0,0 +1,103 @@
+/**
+ * VersionRow — Row item for version/history lists
+ *
+ * Styles are in neptune-components.css. Only pass `style` for truly dynamic overrides.
+ *
+ * A clickable row that displays a version description, author, and timestamp.
+ * Supports an expandable detail section that slides open when toggled.
+ * An optional `actions` slot renders controls (buttons, menus) on the right side.
+ *
+ * Uses the naia-row hover pattern (surface-raised on hover) and surface-sunken
+ * for the expanded detail area.
+ *
+ * @component
+ * @param {Object} props - Component props
+ * @param {string} [props.description] - Version description text
+ * @param {string} [props.author] - Author name
+ * @param {string} [props.time] - Timestamp or relative time string
+ * @param {React.ReactNode} [props.actions] - Optional action buttons rendered on the right
+ * @param {boolean} [props.expanded=false] - Whether the detail section is open
+ * @param {Function} [props.onToggle] - Called when the row is clicked to expand/collapse
+ * @param {React.ReactNode} [props.detail] - Content shown in the expanded detail area
+ * @param {string} [props.className] - Additional CSS classes
+ * @param {React.CSSProperties} [props.style] - Additional inline styles
+ * @returns {JSX.Element} VersionRow component
+ *
+ * @example
+ * <VersionRow
+ *   description="Updated hero banner copy"
+ *   author="Jane D."
+ *   time="2 hours ago"
+ *   onToggle={() => setExpanded(!expanded)}
+ *   expanded={expanded}
+ *   detail={<p>Changed headline from "Welcome" to "Get Started"</p>}
+ * />
+ *
+ * @example
+ * // With action buttons
+ * <VersionRow
+ *   description="Published v2.1.0"
+ *   author="Deploy Bot"
+ *   time="Yesterday"
+ *   actions={<Button size="sm" variant="tertiary">Restore</Button>}
+ * />
+ */
+export default function VersionRow({
+  description,
+  author,
+  time,
+  actions,
+  expanded = false,
+  onToggle,
+  detail,
+  className = "",
+  style = {},
+}) {
+  return (
+    <div className={`neptune-version-row ${expanded ? "neptune-version-row--expanded" : ""} ${className}`}>
+      <div
+        className="neptune-version-row__header"
+        style={style}
+        onClick={onToggle}
+        role={onToggle ? "button" : undefined}
+        tabIndex={onToggle ? 0 : undefined}
+        aria-expanded={onToggle ? expanded : undefined}
+        onKeyDown={
+          onToggle
+            ? (e) => {
+                if (e.key === "Enter" || e.key === " ") {
+                  e.preventDefault();
+                  onToggle();
+                }
+              }
+            : undefined
+        }
+      >
+        {onToggle && (
+          <svg className="neptune-version-row__chevron" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+            <polyline points="9 18 15 12 9 6" />
+          </svg>
+        )}
+        <span className="neptune-version-row__description">{description}</span>
+        <span className="neptune-version-row__meta">
+          {author && <span>{author}</span>}
+          {author && time && <span>·</span>}
+          {time && <span>{time}</span>}
+        </span>
+        {actions && (
+          <span
+            className="neptune-version-row__actions"
+            onClick={(e) => e.stopPropagation()}
+          >
+            {actions}
+          </span>
+        )}
+      </div>
+      {expanded && detail && (
+        <div className="neptune-version-row__detail">
+          {detail}
+        </div>
+      )}
+    </div>
+  );
+}

package/components/feedback/Avatar.jsx

@@ -0,0 +1,28 @@
+/**
+ * Avatar — Circular user avatar with initials or image
+ *
+ * Styles are in neptune-components.css. Only pass `style` for truly dynamic overrides.
+ *
+ * @component
+ * @param {Object} props
+ * @param {string} [props.initials] - One or two letter initials
+ * @param {string} [props.src] - Image URL (overrides initials)
+ * @param {string} [props.alt] - Alt text for image
+ * @param {"sm"|"default"|"lg"} [props.size="default"]
+ * @param {string} [props.className]
+ * @param {Object} [props.style] - Dynamic inline overrides only
+ */
+export default function Avatar({
+  initials,
+  src,
+  alt = "",
+  size = "default",
+  className = "",
+  style = {},
+}) {
+  return (
+    <div className={`neptune-avatar neptune-avatar--${size} ${className}`} style={style}>
+      {src ? <img src={src} alt={alt} /> : initials}
+    </div>
+  );
+}

package/components/feedback/Badge.jsx

@@ -0,0 +1,32 @@
+/**
+ * Badge — Multi-purpose badge/tag for status, environment, and module indication
+ *
+ * Styles are in neptune-components.css. Only pass `style` for truly dynamic overrides.
+ *
+ * @component
+ * @param {Object} props
+ * @param {string} props.label - Text to display
+ * @param {string} [props.variant='default'] - 'default' | 'success' | 'warning' | 'error' | 'info' |
+ *   'env-prod' | 'env-qa' | 'env-dev' | 'module-ui' | 'module-script' | 'module-api' | 'module-data'
+ * @param {string} [props.size='default'] - 'default' | 'sm'
+ * @param {string} [props.className]
+ * @param {Object} [props.style] - Dynamic inline overrides only
+ */
+export default function Badge({
+  label,
+  variant = "default",
+  size = "default",
+  className = "",
+  style = {},
+  ...props
+}) {
+  return (
+    <span
+      className={`neptune-badge neptune-badge--${variant} neptune-badge--${size === "sm" ? "sm" : "default-size"} ${className}`}
+      style={style}
+      {...props}
+    >
+      {label}
+    </span>
+  );
+}

package/components/feedback/ChatMessage.jsx

@@ -0,0 +1,42 @@
+/**
+ * ChatMessage component - Chat message bubble for Naia AI conversations
+ *
+ * Styles are in neptune-components.css. Only pass `style` for truly dynamic overrides.
+ *
+ * Displays a message bubble styled differently for user and Naia messages.
+ * Naia messages appear left-aligned with aubergine text, user messages
+ * appear right-aligned with white text on aubergine background.
+ *
+ * @component
+ * @param {Object} props - Component props
+ * @param {string} props.message - The message text content
+ * @param {string} [props.sender='user'] - Sender type: 'user' or 'naia'
+ * @returns {JSX.Element} Styled chat message bubble
+ *
+ * @example
+ * <ChatMessage message="Hello, how can I help?" sender="naia" />
+ * <ChatMessage message="I need assistance with my deployment" sender="user" />
+ */
+export default function ChatMessage({
+  message,
+  sender = "user",
+  className = "",
+  style = {},
+  ...props
+}) {
+  const lines = typeof message === "string" ? message.split("\n") : null;
+
+  return (
+    <div
+      className={`neptune-chat-message neptune-chat-message--${sender} ${className}`}
+      style={style}
+      {...props}
+    >
+      <div className="neptune-chat-message__bubble">
+        {lines
+          ? lines.map((line, i) => <div key={i}>{line || <br />}</div>)
+          : message}
+      </div>
+    </div>
+  );
+}

package/components/feedback/StatusDot.jsx

@@ -0,0 +1,55 @@
+/**
+ * StatusDot — Animated status indicator dot
+ *
+ * Styles are in neptune-components.css. Only pass `style` for truly dynamic overrides.
+ *
+ * A small colored circle that optionally pulses to indicate live/active status.
+ * Used in the BottomBar for "Live Preview" and in status indicators throughout
+ * the cockpit.
+ *
+ * @component
+ * @param {Object} props
+ * @param {string} [props.status='success'] - Status type: 'success' | 'warning' | 'error' | 'info'
+ * @param {boolean} [props.pulse=false] - Whether the dot should animate with a pulse
+ * @param {number} [props.size=8] - Diameter in pixels
+ * @param {string} [props.color] - Override color (CSS value). If set, ignores status prop for color.
+ * @param {string} [props.className]
+ * @param {React.CSSProperties} [props.style]
+ *
+ * @example
+ * // Pulsing green dot for live status
+ * <StatusDot status="success" pulse />
+ *
+ * @example
+ * // Static error dot
+ * <StatusDot status="error" />
+ *
+ * @example
+ * // Custom color and size
+ * <StatusDot color="var(--npt-accent-primary)" size={6} />
+ */
+export default function StatusDot({
+  status = "success",
+  pulse = false,
+  size = 8,
+  color,
+  className = "",
+  style = {},
+}) {
+  // Dynamic inline styles only for custom size and color override
+  const dynamicStyle = {
+    width: `${size}px`,
+    height: `${size}px`,
+    ...(color ? { backgroundColor: color } : {}),
+    ...style,
+  };
+
+  return (
+    <span
+      className={`neptune-status-dot ${!color ? `neptune-status-dot--${status}` : ""} ${pulse ? "neptune-status-dot--pulse" : ""} ${className}`}
+      style={dynamicStyle}
+      role="status"
+      aria-label={`${status} status${pulse ? " (active)" : ""}`}
+    />
+  );
+}