@vention/machine-apps-components 0.2.8

package/README.md

@@ -0,0 +1,819 @@
+# Machine Apps Components
+
+Reusable components for machine applications.
+
+## Components
+
+### NavigationBar
+
+A navigation bar component with support for:
+
+- Multiple navigation items with icons
+- Control Center button
+- Support button
+- Optional timer display
+
+#### Props
+
+```typescript
+interface NavigationItem {
+  label: string
+  path: string
+  icon: ReactNode
+  onClick?: () => void // Optional: Custom click handler (overrides default navigation)
+}
+
+interface NavigationBarProps {
+  navigationItems: NavigationItem[]
+  showTimer?: boolean // Default: true
+}
+```
+
+#### Example Usage
+
+##### Basic Usage
+
+```tsx
+import { NavigationBar } from "@vention/machine-apps-components"
+import { VentionIcon } from "@ventionco/machine-ui"
+
+const NAV_ITEMS = [
+  {
+    label: "Operation",
+    path: "/operation",
+    icon: <VentionIcon size={32} type="category-filled" color="white" />,
+  },
+  {
+    label: "Settings",
+    path: "/settings",
+    icon: <VentionIcon size={32} type="tool-1" color="white" />,
+  },
+]
+
+// With timer (default)
+<NavigationBar navigationItems={NAV_ITEMS} />
+
+// Without timer
+<NavigationBar navigationItems={NAV_ITEMS} showTimer={false} />
+```
+
+##### Custom Click Handlers
+
+You can override the default navigation behavior by providing custom click handlers:
+
+```tsx
+// Custom handler for navigation items
+const NAV_ITEMS = [
+  {
+    label: "Settings",
+    path: "/settings",
+    icon: <VentionIcon size={32} type="tool-1" color="white" />,
+    onClick: () => {
+      // Show confirmation before navigating
+      if (confirm("You have unsaved changes. Continue?")) {
+        navigate("/settings")
+      }
+    },
+  },
+  {
+    label: "Logs",
+    path: "/logs",
+    icon: <VentionIcon size={32} type="alarm-bell-filled" color="white" />,
+    onClick: () => {
+      // Do something before navigating
+      localStorage.setItem("lastView", "operation")
+      navigate("/logs")
+    },
+  },
+]
+```
+
+**Note:** When a custom `onClick` handler is provided, it completely overrides the default navigation behavior. The handler is responsible for any navigation logic if needed.
+
+### StatusTopBar
+
+A status bar component positioned at the top of the screen that displays:
+
+- Status indicator with label and colored dot
+- Configurable action buttons that can be shown/hidden
+- Button enable/disable states
+- Custom styling for buttons
+
+#### Props
+
+```typescript
+interface ButtonConfig {
+  id: string // Unique identifier for the button
+  label: string // Button text
+  onClick?: () => void // Click handler
+  backgroundColor?: string // Button background color (e.g., "#4CAF50")
+  backgroundColorHover?: string // Hover background color
+  borderColor?: string // Border color
+  textColor?: string // Text color
+  width?: number // Button width in pixels (default: 208)
+  height?: number // Button height in pixels (default: 80)
+  icon?: ReactNode // Icon to display when enabled
+  iconDisabled?: ReactNode // Icon to display when disabled
+}
+
+interface StatusTopBarProps {
+  statusLabel?: string // Label for the status indicator
+  dotColor?: string // Color of the status dot
+  buttonConfigs?: ButtonConfig[] // Array of button configurations
+  visibleButtons?: string[] // Button IDs to show (controlled)
+  disabledButtons?: string[] // Button IDs to disable (controlled)
+}
+```
+
+#### API Methods (via ref)
+
+```typescript
+interface StatusTopBarHandle {
+  showButtons: (buttonIds: string[]) => void // Show specific buttons
+  hideAllButtons: () => void // Hide all buttons
+  disableButton: (buttonId: string) => void // Disable a specific button
+  enableButton: (buttonId: string) => void // Enable a specific button
+  disableAllButtons: () => void // Disable all buttons
+  enableAllButtons: () => void // Enable all buttons
+}
+```
+
+#### Example Usage
+
+##### Basic Usage
+
+```tsx
+import { StatusTopBar } from "@vention/machine-apps-components"
+import { useRef } from "react"
+import type { StatusTopBarHandle } from "@vention/machine-apps-components"
+
+const BUTTON_CONFIGS = [
+  {
+    id: "enableFreeDrive",
+    label: "Enable Free Drive",
+    onClick: () => console.log("Free Drive enabled"),
+    backgroundColor: "#4CAF50",
+    backgroundColorHover: "#45A049",
+    textColor: "#FFFFFF",
+  },
+  {
+    id: "start",
+    label: "Start",
+    onClick: () => console.log("Start clicked"),
+    backgroundColor: "#2196F3",
+    textColor: "#FFFFFF",
+  },
+  {
+    id: "stop",
+    label: "Stop",
+    onClick: () => console.log("Stop clicked"),
+    backgroundColor: "#F44336",
+    textColor: "#FFFFFF",
+  },
+]
+
+function App() {
+  const statusBarRef = useRef<StatusTopBarHandle>(null)
+
+  return (
+    <StatusTopBar
+      ref={statusBarRef}
+      statusLabel="Ready"
+      dotColor="#4CAF50"
+      buttonConfigs={BUTTON_CONFIGS}
+      visibleButtons={["start"]}
+    />
+  )
+}
+```
+
+##### Controlling Buttons Programmatically
+
+```tsx
+const statusBarRef = useRef<StatusTopBarHandle>(null)
+
+// Show specific buttons
+statusBarRef.current?.showButtons(["enableFreeDrive", "start"])
+
+// Hide all buttons
+statusBarRef.current?.hideAllButtons()
+
+// Disable a specific button
+statusBarRef.current?.disableButton("start")
+
+// Enable a specific button
+statusBarRef.current?.enableButton("start")
+
+// Disable all buttons
+statusBarRef.current?.disableAllButtons()
+
+// Enable all buttons
+statusBarRef.current?.enableAllButtons()
+```
+
+#### Console Testing Commands
+
+For development and debugging, the StatusTopBar component exposes its API methods on the `window` object. You can test button visibility and states directly from the browser console:
+
+##### StatusTopBar Commands
+
+```javascript
+// Show specific buttons (pass an array of button IDs)
+window.showButtons(["enableFreeDrive", "start"])
+
+// Show a single button
+window.showButtons(["enableFreeDrive"])
+
+// Hide all buttons
+window.hideAllButtons()
+
+// Disable a specific button
+window.disableButton("start")
+
+// Enable a specific button
+window.enableButton("start")
+
+// Disable all buttons
+window.disableAllButtons()
+
+// Enable all buttons
+window.enableAllButtons()
+```
+
+**Important:** The `showButtons` function requires an **array** of button IDs, not a single string. This is a common mistake when testing in the console.
+
+✅ **Correct:**
+
+```javascript
+window.showButtons(["enableFreeDrive"])
+window.showButtons(["enableFreeDrive", "start", "stop"])
+```
+
+❌ **Incorrect:**
+
+```javascript
+window.showButtons("enableFreeDrive") // Will cause "visibleButtons.map is not a function" error
+```
+
+##### NavigationBar Console Testing
+
+The NavigationBar doesn't expose window commands because it's controlled by React Router. To test navigation:
+
+```javascript
+// In browser console, navigate programmatically
+window.location.hash = "#/operation"
+window.location.hash = "#/settings"
+window.location.hash = "#/control-center"
+```
+
+Or use React Router's imperative navigation in your component:
+
+```tsx
+import { useNavigate } from "react-router-dom"
+
+const navigate = useNavigate()
+navigate("/operation")
+```
+
+### Logs
+
+Reusable logs components for filtering, sorting, and displaying machine logs.
+
+#### Exports
+
+```typescript
+import { LogsPanel, LogsTable, LogFilterForm, LogsPagination } from "@vention/machine-apps-components"
+import type {
+  LogEntry,
+  LogType,
+  LogFilterFormValues,
+  SortOrder,
+  LogsPanelHandle,
+  PaginationConfig,
+  PaginationMode,
+  FetchParams,
+  FetchResult,
+} from "@vention/machine-apps-components"
+```
+
+#### Types
+
+```typescript
+type LogType = "error" | "warning" | "info"
+
+interface LogEntry {
+  id: string
+  date: string // ISO or locale string parsable by Date
+  type: LogType
+  code: string
+  message: string
+  description: string
+}
+
+type SortOrder = "latest" | "oldest"
+
+interface LogFilterFormValues {
+  fromDate?: string // YYYY-MM-DD
+  toDate?: string // YYYY-MM-DD
+  logType?: LogType
+  sortOrder: SortOrder
+}
+
+type PaginationMode = "pagination" | "infinite-scroll" | "none"
+
+interface PaginationConfig {
+  mode: PaginationMode
+  pageSize?: number // Default: 10
+  initialPage?: number // Default: 1
+}
+
+// Parameters passed to the dataFetcher
+interface FetchParams {
+  filters: LogFilterFormValues // Current filter state
+  page: number // Current page number
+  pageSize: number // Items per page
+}
+
+// Expected return type from dataFetcher
+interface FetchResult {
+  logs: LogEntry[] // The log entries for this page
+  totalCount: number // Total number of logs (after filtering)
+  totalPages: number // Total number of pages
+  currentPage: number // Current page number
+  hasMore: boolean // Whether there are more pages available
+}
+
+// Type definition for data fetcher
+type DataFetcher = (params: FetchParams) => Promise<FetchResult>
+
+interface LogsPanelHandle {
+  refresh: () => Promise<void>
+  resetFilters: () => void
+  applyFilters: (filters: Partial<LogFilterFormValues>) => void
+  getCurrentFilters: () => LogFilterFormValues
+  exportLogs: () => LogEntry[]
+}
+```
+
+#### LogsPanel
+
+A composite component that combines filter UI and table display with loading states and error handling. The component is a **pure presentation component** - it displays data and manages UI state, while delegating all data operations (filtering, sorting, pagination) to your `dataFetcher` function.
+
+**Features:**
+
+- 🔄 Automatic loading state with spinner when fetching data
+- ❌ Built-in error display with VentionAlert
+- 🔍 Filter UI for date range and log type
+- ↕️ Sort UI for latest/oldest
+- 📅 Date formatting (YYYY-MM-DD h:mm:ssa)
+- 🎨 Type-based icons (error, warning, info)
+- 📄 Pagination support (standard pagination or infinite scroll)
+- 🎯 Imperative API for programmatic control
+- 🔔 Event callbacks for integration
+- 🎨 Customizable styling and empty states
+- ⚡ Performance optimized with React.memo
+
+##### How It Works
+
+The component calls your `dataFetcher` function whenever filters, sort order, or page changes. You implement the filtering, sorting, and pagination logic, and return the results:
+
+```tsx
+import { LogsPanel } from "@vention/machine-apps-components"
+import type { FetchParams, FetchResult } from "@vention/machine-apps-components"
+
+const fetchLogs = async (params: FetchParams): Promise<FetchResult> => {
+  // params contains:
+  // - params.filters.fromDate
+  // - params.filters.toDate
+  // - params.filters.logType
+  // - params.filters.sortOrder
+  // - params.page
+  // - params.pageSize
+
+  const response = await fetch(
+    `/api/logs?${new URLSearchParams({
+      fromDate: params.filters.fromDate || "",
+      toDate: params.filters.toDate || "",
+      logType: params.filters.logType || "",
+      sortOrder: params.filters.sortOrder,
+      page: params.page.toString(),
+      pageSize: params.pageSize.toString(),
+    })}`
+  )
+
+  const data = await response.json()
+
+  return {
+    logs: data.logs,
+    totalCount: data.total,
+    totalPages: Math.ceil(data.total / params.pageSize),
+    currentPage: params.page,
+    hasMore: params.page < Math.ceil(data.total / params.pageSize),
+  }
+}
+
+;<LogsPanel
+  dataFetcher={fetchLogs}
+  pagination={{
+    mode: "pagination",
+    pageSize: 20,
+  }}
+/>
+```
+
+**Important:** When using `dataFetcher`, you are responsible for:
+
+- ✅ Filtering logs by date range and type
+- ✅ Sorting logs by date (latest/oldest)
+- ✅ Paginating the results
+- ✅ Returning pagination metadata (totalCount, totalPages, hasMore)
+
+The component handles:
+
+- ✅ Rendering the filter UI
+- ✅ Managing filter state
+- ✅ Calling your `dataFetcher` when filters/page changes
+- ✅ Loading and error states
+- ✅ Displaying the results
+
+##### Complete Client-Side Example
+
+Here's a complete example showing how to implement filtering, sorting, and pagination on the client-side:
+
+```tsx
+import { useCallback, useMemo } from "react"
+import { LogsPanel } from "@vention/machine-apps-components"
+import type { FetchParams, FetchResult, LogEntry } from "@vention/machine-apps-components"
+import dayjs from "dayjs"
+
+function LogsPage() {
+  // Your data source (could come from props, context, etc.)
+  const allLogs: LogEntry[] = useMemo(
+    () => [
+      { id: "1", date: "2025-10-07T14:00:00Z", type: "error", code: "ERR_001", message: "Error", description: "..." },
+      { id: "2", date: "2025-10-07T13:00:00Z", type: "warning", code: "WARN_001", message: "Warning", description: "..." },
+      { id: "3", date: "2025-10-07T12:00:00Z", type: "info", code: "INFO_001", message: "Info", description: "..." },
+      // ... more logs
+    ],
+    []
+  )
+
+  const fetchLogs = useCallback(
+    async (params: FetchParams): Promise<FetchResult> => {
+      // Simulate network delay (optional)
+      await new Promise(resolve => setTimeout(resolve, 500))
+
+      // 1. Apply filtering
+      let filtered = [...allLogs]
+
+      // Filter by date range
+      if (params.filters.fromDate) {
+        const fromTimestamp = dayjs(params.filters.fromDate).valueOf()
+        filtered = filtered.filter(log => dayjs(log.date).valueOf() >= fromTimestamp)
+      }
+
+      if (params.filters.toDate) {
+        const toTimestamp = dayjs(params.filters.toDate).endOf("day").valueOf()
+        filtered = filtered.filter(log => dayjs(log.date).valueOf() <= toTimestamp)
+      }
+
+      // Filter by log type
+      if (params.filters.logType) {
+        filtered = filtered.filter(log => log.type === params.filters.logType)
+      }
+
+      // 2. Apply sorting
+      filtered.sort((a, b) => {
+        const aTime = dayjs(a.date).valueOf()
+        const bTime = dayjs(b.date).valueOf()
+        return params.filters.sortOrder === "latest" ? bTime - aTime : aTime - bTime
+      })
+
+      // 3. Apply pagination
+      const totalCount = filtered.length
+      const totalPages = Math.ceil(totalCount / params.pageSize)
+      const start = (params.page - 1) * params.pageSize
+      const end = start + params.pageSize
+      const paginated = filtered.slice(start, end)
+
+      // 4. Return result
+      return {
+        logs: paginated,
+        totalCount,
+        totalPages,
+        currentPage: params.page,
+        hasMore: end < totalCount,
+      }
+    },
+    [allLogs]
+  )
+
+  return (
+    <LogsPanel
+      dataFetcher={fetchLogs}
+      pagination={{
+        mode: "pagination",
+        pageSize: 10,
+      }}
+    />
+  )
+}
+```
+
+##### Props
+
+```typescript
+interface LogsPanelProps {
+  // Required - Data fetcher function
+  dataFetcher: (params: FetchParams) => Promise<FetchResult>
+
+  // Optional - Initial state
+  initialFilters?: Partial<LogFilterFormValues>
+
+  // Optional - Error handling
+  onError?: (error: unknown) => void
+
+  // Optional - Pagination
+  pagination?: PaginationConfig
+
+  // Optional - Event callbacks
+  onFilterChange?: (filters: LogFilterFormValues) => void
+  onLogClick?: (log: LogEntry) => void
+
+  // Optional - Customization
+  className?: string
+  tableHeight?: string | number
+  emptyStateMessage?: string
+  emptyStateIcon?: ReactNode
+}
+```
+
+##### States
+
+- **Loading**: Shows VentionSpinner with "Loading logs..." message
+- **Error**: Displays VentionAlert with error title and description
+- **Empty**: Shows customizable empty state message
+- **Success**: Renders filterable/sortable table with data
+
+##### Initial Filters
+
+```tsx
+<LogsPanel
+  data={logs}
+  initialFilters={{
+    fromDate: "2025-09-01",
+    toDate: "2025-09-30",
+    logType: "error",
+    sortOrder: "latest",
+  }}
+/>
+```
+
+##### Pagination
+
+```tsx
+// Standard pagination (default: 10 items per page)
+<LogsPanel
+  data={logs}
+  pagination={{
+    mode: "pagination",
+    pageSize: 20,
+    initialPage: 1,
+  }}
+/>
+
+// Infinite scroll (loads more as you scroll)
+<LogsPanel
+  data={logs}
+  pagination={{
+    mode: "infinite-scroll",
+    pageSize: 10,
+  }}
+/>
+
+// No pagination (show all logs)
+<LogsPanel
+  data={logs}
+  pagination={{ mode: "none" }}
+/>
+
+// Default behavior (no pagination prop = show all logs)
+<LogsPanel data={logs} />
+```
+
+##### Event Callbacks
+
+Get notified when user interacts with the component:
+
+```tsx
+import { LogsPanel } from "@vention/machine-apps-components"
+import type { LogEntry, LogFilterFormValues } from "@vention/machine-apps-components"
+;<LogsPanel
+  data={logs}
+  onFilterChange={(filters: LogFilterFormValues) => {
+    console.log("User changed filters:", filters)
+    // Track analytics, sync to URL params, etc.
+  }}
+  onLogClick={(log: LogEntry) => {
+    console.log("User clicked log:", log)
+    // Show details modal, navigate to details page, etc.
+  }}
+/>
+```
+
+##### Imperative API
+
+Control the component programmatically using a ref:
+
+```tsx
+import { useRef } from "react"
+import { LogsPanel } from "@vention/machine-apps-components"
+import type { LogsPanelHandle } from "@vention/machine-apps-components"
+
+function MyComponent() {
+  const logsPanelRef = useRef<LogsPanelHandle>(null)
+
+  const handleRefresh = async () => {
+    // Manually refresh async data
+    await logsPanelRef.current?.refresh()
+  }
+
+  const handleResetFilters = () => {
+    // Reset all filters to default
+    logsPanelRef.current?.resetFilters()
+  }
+
+  const handleShowErrors = () => {
+    // Programmatically apply filters
+    logsPanelRef.current?.applyFilters({ logType: "error" })
+  }
+
+  const handleExport = () => {
+    // Get current filtered/sorted logs
+    const logs = logsPanelRef.current?.exportLogs()
+    if (logs) {
+      // Export to CSV, JSON, etc.
+      downloadAsCSV(logs)
+    }
+  }
+
+  const handleGetFilters = () => {
+    // Get current filter state
+    const filters = logsPanelRef.current?.getCurrentFilters()
+    console.log("Current filters:", filters)
+  }
+
+  return (
+    <>
+      <div>
+        <button onClick={handleRefresh}>Refresh</button>
+        <button onClick={handleResetFilters}>Reset Filters</button>
+        <button onClick={handleShowErrors}>Show Errors Only</button>
+        <button onClick={handleExport}>Export Logs</button>
+      </div>
+      <LogsPanel ref={logsPanelRef} data={fetchLogs} />
+    </>
+  )
+}
+```
+
+**Available Methods:**
+
+- `refresh()` - Manually re-fetch data with current filters/page
+- `resetFilters()` - Reset all filters to their default values
+- `applyFilters(filters)` - Programmatically set filters
+- `getCurrentFilters()` - Get the current filter state
+- `exportLogs()` - Get currently displayed logs array
+
+##### Customization
+
+Customize the appearance and behavior:
+
+```tsx
+import { LogsPanel } from "@vention/machine-apps-components"
+import { VentionIcon } from "@ventionco/machine-ui"
+;<LogsPanel
+  data={logs}
+  className="my-custom-logs-panel"
+  tableHeight="600px"
+  emptyStateMessage="No logs match your filters"
+  emptyStateIcon={<VentionIcon type="inbox" size={48} color="gray" />}
+/>
+```
+
+**Customization Props:**
+
+- `className` - Add custom CSS class to the root container
+- `tableHeight` - Set custom table height (e.g., "500px", 600)
+- `emptyStateMessage` - Custom message when no logs (default: "You have no logs")
+- `emptyStateIcon` - Custom React node to display above empty message
+
+#### LogsTable
+
+Just the table component. Useful if you want to handle filtering/sorting yourself or compose your own custom layout with filters.
+
+```tsx
+import { LogsTable } from "@vention/machine-apps-components"
+import type { LogEntry } from "@vention/machine-apps-components"
+
+<LogsTable 
+  logs={logs} 
+  onLogClick={log => showDetailsModal(log)} 
+  tableHeight="500px" 
+  emptyStateMessage="No logs available" 
+/>
+```
+
+**Props:**
+
+```typescript
+interface LogsTableProps {
+  logs?: LogEntry[]
+  isLoading?: boolean
+  error?: string | null
+  onLoadMoreLogs?: () => void // For infinite scroll
+  hasMoreLogs?: boolean // For infinite scroll
+  onLogClick?: (log: LogEntry) => void
+  tableHeight?: string | number
+  emptyStateMessage?: string
+  emptyStateIcon?: ReactNode
+}
+```
+
+#### LogFilterForm
+
+Just the filter UI. Use this when you want full control over the filtering logic.
+
+```tsx
+import { LogFilterForm } from "@vention/machine-apps-components"
+import type { LogFilterFormValues } from "@vention/machine-apps-components"
+
+const handleFilterChange = (filters: LogFilterFormValues) => {
+  // Apply filters to your own data source
+  const filtered = myLogs.filter(log => {
+    // Your custom filter logic
+  })
+}
+
+const handleReset = () => {
+  // Handle reset
+}
+
+;<LogFilterForm onFilterChange={handleFilterChange} onReset={handleReset} initialFilters={{ logType: "error" }} />
+```
+
+#### LogsPagination
+
+Just the pagination controls. Use this for custom pagination implementations.
+
+```tsx
+import { LogsPagination } from "@vention/machine-apps-components"
+;<LogsPagination currentPage={currentPage} totalPages={totalPages} onPageChange={page => setCurrentPage(page)} />
+```
+
+## Development
+
+### Running Tests
+
+```bash
+# Run tests
+nx test machine-apps-components
+
+# Run tests with coverage
+nx test machine-apps-components --coverage
+
+# Run tests in watch mode
+cd projects/machine-code/libs/machine-apps-components
+npx vitest
+```
+
+### Testing Setup
+
+This library uses Vitest with jsdom environment for testing React components. Test utilities are provided in `src/test-utils.tsx` that wrap components with necessary providers:
+
+- `ThemeProvider` with `machineUiTheme`
+- `MemoryRouter` for routing
+
+Example test:
+
+```tsx
+import { renderWithProviders } from "../../test-utils"
+import { NavigationBar } from "./navigation-bar"
+
+it("should render correctly", () => {
+  renderWithProviders(<NavigationBar navigationItems={mockNavigationItems} />)
+  expect(screen.getByText("Operation")).toBeDefined()
+})
+```
+
+## Building
+
+```bash
+nx build machine-apps-components
+```
+
+## Linting
+
+```bash
+nx lint machine-apps-components
+```