@things-factory/dataset 9.1.17 → 9.1.19

package/FRONTEND_ARCHITECTURE.md

@@ -0,0 +1,732 @@
+# Things-Factory Dataset Client-Side Architecture Analysis
+
+## Overview
+The Things-Factory dataset client uses a **component-based architecture** with Lit Web Components to render data entry forms. The frontend leverages the `@operato/dataset` package which provides core components like `OxDataEntryForm`, while `@operato/input` provides specialized input components.
+
+---
+
+## 1. Input Component Architecture
+
+### 1.1 Current Input Component Pattern
+
+**Base Class: OxFormField**
+- Location: `@operato/input/dist/src/ox-form-field.d.ts`
+- Extends: `LitElement`
+- Properties:
+  - `name?: string` - Form field name
+  - `disabled?: boolean` - Disabled state
+  - `value?: T` - Generic value type
+  - `protected _form: HTMLFormElement | null` - Parent form reference
+- Methods:
+  - `connectedCallback()` - Register with parent form
+  - `disconnectedCallback()` - Unregister from parent form
+  - `appendFormData()` - Append to FormDataEvent
+
+### 1.2 Existing Input Components
+
+**Examples from @operato/input package:**
+
+1. **OxInputFile** - File upload component
+   - Path: `@operato/input/dist/src/ox-input-file.js`
+   - Features:
+     - Drag-and-drop support
+     - Multiple file selection
+     - File list display with delete action
+     - Icon and description customization
+     - Hidden file list option
+   - Key Properties:
+     - `multiple?: boolean` - Allow multiple files
+     - `accept?: string` - MIME type filter
+     - `icon?: string` - Custom icon (default: 'upload')
+     - `label?: string` - Button label
+     - `description?: string` - Placeholder text
+     - `hideFileList: boolean` - Toggle file list display
+     - `attachFileList: boolean` - Attach list to component
+   - Implementation Details:
+     - Uses `FileDropHelper` from @operato/utils
+     - Extends OxFormField
+     - Styled with Material Design tokens
+     - Handles FormDataEvent for form submission
+
+2. **OxInputImage** - Image upload component
+   - Path: `@operato/input/dist/src/ox-input-image.js`
+   - Similar structure to OxInputFile
+   - Single file selection (typically)
+
+3. **Other Specialized Components:**
+   - ox-input-signature (digital signature)
+   - ox-input-color
+   - ox-input-barcode
+   - ox-input-code
+   - And 50+ more...
+
+---
+
+## 2. Data Entry Form System
+
+### 2.1 OxDataEntryForm Component
+
+**Location:** `@operato/dataset/dist/src/ox-data-entry-form.js`
+
+**Purpose:** Renders a form based on a DataSet definition
+
+**Key Methods:**
+
+1. **render()** - Main rendering method
+   - Creates a `<form>` element with dataset name and description
+   - Calls `buildInputs()` to generate form fields
+
+2. **buildInputs()** - Builds input elements for all active data items
+   - Filters active items: `dataItems.filter(item => item.active)`
+   - Groups items by "group" property
+   - Returns array of Lit TemplateResults
+
+3. **buildInputsForSubgroup()** - Handles grouped data items
+   - Renders `<ox-data-entry-subgroup-form>` for groups
+   - Passes dataItems and values to subgroup component
+   - Listens to 'change' events
+
+4. **buildInputsForNonGrouped()** - Handles non-grouped items
+   - Maps each dataItem to input element
+   - Uses `OxDataInputFactory.createInputElement()` for rendering
+   - Supports quota (multiple inputs per field)
+   - Structure:
+     ```html
+     <div label>
+       <div name>${name}${unit ? ` (${unit})` : ''}</div>
+       <div description><md-icon>info</md-icon> ${description}</div>
+       <div elements>
+         <!-- Input elements -->
+       </div>
+     </div>
+     ```
+
+5. **buildValue()** - Extracts and returns form values
+   - Combines non-grouped values and subgroup values
+   - Returns object: `{ [tag: string]: any }`
+
+6. **extractValuesFromInputs()** - Gets values from DOM inputs
+   - Queries inputs by name attribute: `[name=${tag}]`
+   - Handles boolean (checked) and other types (value)
+   - Returns array of values for each field
+
+### 2.2 OxDataInputFactory - Type-to-Component Mapping
+
+**Location:** `@operato/dataset/dist/src/ox-data-input-factory.js`
+
+**Core Method: createInputElement()**
+
+This is the **KEY MAPPING FUNCTION** that determines which component to render for each data type:
+
+```javascript
+static createInputElement(type, tag, value, options = {}, idx = 0) {
+  switch (type) {
+    case 'select':
+      return this.createSelect(tag, value, options);
+    case 'radio':
+      return this.createRadio(tag, value, options, idx);
+    case 'boolean':
+      return html`<input type="checkbox" name=${tag} .checked=${value} />`;
+    case 'number':
+      return html`<input type="number" name=${tag} .value=${value} />`;
+    case 'date':
+      return html`<input type="date" name=${tag} .value=${value} />`;
+    case 'datetime':
+      return html`<input type="datetime-local" name=${tag} .value=${value} />`;
+    case 'file':
+      return html`<ox-input-file name=${tag} multiple .value=${value}></ox-input-file>`;
+    case 'signature':
+      return html`<ox-input-signature name=${tag} .value=${value}></ox-input-signature>`;
+    case 'employee':
+      return this.createEmployee(tag, value, options);
+    case 'string':
+    default:
+      return html`<input type="text" name=${tag} .value=${value || ''} />`;
+  }
+}
+```
+
+**IMPORTANT: Image, video, and audio types are NOT currently handled!**
+
+---
+
+## 3. DataItemType Definition
+
+**Location:** `packages/dataset/server/service/data-set/data-item-type.ts`
+
+**Enum Values:**
+```typescript
+enum DataItemType {
+  number = 'number',
+  text = 'text',
+  boolean = 'boolean',
+  select = 'select',
+  radio = 'radio',
+  date = 'date',
+  datetime = 'datetime',
+  file = 'file',
+  image = 'image',      // DEFINED BUT NOT IMPLEMENTED IN FACTORY
+  video = 'video',      // DEFINED BUT NOT IMPLEMENTED IN FACTORY
+  audio = 'audio',      // DEFINED BUT NOT IMPLEMENTED IN FACTORY
+  signature = 'signature'
+}
+```
+
+**DataItem Object Structure:**
+```typescript
+class DataItem {
+  name: string                      // Display name
+  description?: string              // Field help text
+  tag?: string                      // Unique identifier for data
+  group?: string                    // Group identifier
+  subgroup?: string                 // Subgroup identifier
+  active?: boolean                  // Active/inactive toggle
+  hidden?: boolean                  // Visibility toggle
+  type?: DataItemType               // Field type
+  options?: { [option: string]: any } // Type-specific options
+  stat?: DataItemStatType           // Statistical aggregation
+  agg?: DataItemStatType            // Aggregation function
+  unit?: string                     // Unit of measurement
+  quota?: number                    // Max values allowed (default: 1)
+  spec?: { [key: string]: any }     // Validation specs
+}
+```
+
+---
+
+## 4. Data Entry Components Architecture
+
+### 4.1 Component Hierarchy
+
+```
+data-entry-form (LitElement)
+├── ox-data-entry-form (@operato/dataset)
+│   ├── ox-data-entry-subgroup-form (for grouped items)
+│   │   └── ox-grist (data grid, for subgroups)
+│   │       └── OxDataInputFactory.mapGristType()
+│   └── OxDataInputFactory.createInputElement() (for non-grouped items)
+│       ├── ox-input-file
+│       ├── ox-input-signature
+│       ├── ox-input-text
+│       ├── ox-input-checkbox
+│       └── ... (native HTML inputs)
+```
+
+### 4.2 Client-Side Data Entry Forms
+
+**Location:** `packages/dataset/client/components/`
+
+#### data-entry-form.ts
+- **Purpose:** Wrapper component for standard data entry
+- **Key Properties:**
+  - `dataSet: DataSet & { id: string; entryType?: string }`
+  - `dataSample?: { id: string; collectedAt: Date }`
+- **Methods:**
+  - `updateDataItems()` - GraphQL mutation to save data
+  - Uses `@query('ox-data-entry-form')` decorator to access ox-data-entry-form
+  - Calls `buildValue()` to extract form data
+  - GraphQL Context: `hasUpload: true` - enables file upload support
+
+#### checklist-entry-form.ts
+- **Purpose:** Wrapper for checklist-style data entry
+- Similar structure to data-entry-form
+- Uses `ox-checklist-entry-form` component
+
+### 4.3 Activity Integration
+
+**Location:** `packages/dataset/client/activities/activity-data-collect-edit.ts`
+
+- **Purpose:** Workflow activity for data collection
+- **Entry Types Supported:**
+  - 'generated' → OxDataEntryForm
+  - 'checklist' → OxChecklistEntryForm
+  - 'board' → (not implemented)
+  - 'page' → (not implemented)
+- **Properties:**
+  - `input: { dataSetId: string }` - Input from workflow
+  - `output: { [tag: string]: any }` - Form values
+  - Dispatches 'change' events on form update
+
+---
+
+## 5. File Upload Handling
+
+### 5.1 GraphQL Mutation Context
+
+**in data-entry-form.ts (lines 93-94):**
+```typescript
+context: {
+  hasUpload: true  // Enables multipart/form-data
+}
+```
+
+This flag tells Apollo Client to use form-data encoding for file uploads.
+
+### 5.2 Backend File Processing
+
+**Location:** `packages/dataset/server/controllers/create-data-sample.ts`
+
+**File Upload Flow (lines 109-189):**
+
+1. **Iteration through dataItems:**
+   - Checks if type is file or media: `isFileOrMediaType(dataItem.type)`
+   - Gets the files array: `data[tag]`
+
+2. **For Each File (if media type):**
+   - **Validation** (lines 136-152):
+     ```typescript
+     if (isMediaType(dataItem.type)) {
+       const validation = validateMediaFile(
+         {
+           mimetype: file.file.mimetype,
+           size: file.file.size,
+           name: file.file.filename
+         },
+         dataItem.type,
+         dataItem.options
+       )
+       if (!validation.valid) {
+         throw new Error(`Media validation failed...`)
+       }
+     }
+     ```
+
+3. **Attachment Creation** (lines 154-176):
+   - Creates attachment record
+   - Returns attachment with: `id, mimetype, name, fullpath`
+
+4. **Store in Data Sample:**
+   - Replaces file objects with path info
+   - `data[tag] = pathsArray` - Array of path objects
+
+### 5.3 Media Validation Utilities
+
+**Location:** `packages/dataset/server/utils/media-validation.ts`
+
+**Key Functions:**
+
+1. **validateMediaFile()** - Main validation function
+   - Checks MIME type against allowed types
+   - Validates file extension (if accept option specified)
+   - Validates file size (if maxSize option specified)
+   - Returns: `{ valid: boolean, errors: string[] }`
+
+2. **MIME Type Mappings:**
+   ```typescript
+   const MEDIA_MIME_TYPES = {
+     image: ['image/jpeg', 'image/png', 'image/gif', ...],
+     video: ['video/mp4', 'video/webm', ...],
+     audio: ['audio/mpeg', 'audio/wav', ...]
+   }
+   ```
+
+3. **Helper Functions:**
+   - `isValidMimeType()` - Check MIME type validity
+   - `isAcceptedFormat()` - Check file extension
+   - `isValidFileSize()` - Check file size constraint
+   - `isMediaType()` - Check if type is media
+   - `isFileOrMediaType()` - Check if file or media type
+
+---
+
+## 6. Component Registration & Bootstrap
+
+### 6.1 Bootstrap File
+
+**Location:** `packages/dataset/client/bootstrap.ts`
+
+**Registers:**
+- Custom Grist editors and renderers
+- Data item spec editor
+- Signature editor/renderer
+- Partition keys editor/renderer
+
+**Note:** OxDataEntryForm is auto-registered through imports in wrapper components.
+
+### 6.2 Component Import Pattern
+
+Components are registered via ES6 imports:
+
+```typescript
+import '@operato/dataset/ox-data-entry-form.js'
+import '@operato/dataset/ox-checklist-entry-form.js'
+```
+
+When imported, the `@customElement('ox-data-entry-form')` decorator registers them globally.
+
+---
+
+## 7. Subgroup Form System
+
+### 7.1 OxDataEntrySubgroupForm
+
+**Location:** `@operato/dataset/dist/src/ox-data-entry-subgroup-form.js`
+
+**Purpose:** Render grouped data items in a Grist data grid (table)
+
+**Key Methods:**
+
+1. **buildGristConfiguration()** - Creates grid config
+   - Maps DataItemType to Grist column types using `OxDataInputFactory.mapGristType()`
+   - Returns columns with editing properties
+   - Uses `OxDataInputFactory.getGristRecordOptions()` for column-specific options
+
+2. **mapGristType()** - Maps form types to Grist types
+   ```javascript
+   case 'radio': return 'select';
+   case 'select': return 'select';
+   case 'boolean': return 'boolean';
+   case 'number': return 'number';
+   case 'date': return 'date';
+   case 'datetime': return 'datetime';
+   case 'file': return 'file';
+   case 'signature': return 'signature';
+   case 'string': return 'text';
+   ```
+
+3. **getGristRecordOptions()** - Column configuration
+   ```javascript
+   case 'select': return { options: [...] };
+   case 'boolean': return { align: 'center' };
+   case 'number': return { align: 'right' };
+   case 'file': return { multiple: true };
+   ```
+
+---
+
+## 8. File/Media Options Schema
+
+**Defined in:** `data-item-type.ts` (lines 174-429)
+
+### 8.1 Image Type Options Example
+```typescript
+{
+  type: 'image',
+  options: {
+    accept: ['jpeg', 'png', 'webp'],       // Allowed formats
+    maxSize: 10485760,                     // 10MB
+    maxWidth: 4096,                        // pixels
+    maxHeight: 4096,                       // pixels
+    minWidth: 224,                         // pixels
+    minHeight: 224,                        // pixels
+    multiple: true,                        // Allow multiple
+    maxFiles: 10,                          // Max number
+    thumbnail: {
+      enabled: true,
+      width: 200,
+      height: 200,
+      format: 'jpeg',
+      quality: 85
+    },
+    preview: {
+      enabled: true,
+      maxWidth: 1024,
+      maxHeight: 1024
+    },
+    metadata: {
+      extractExif: true,
+      extractDimensions: true,
+      extractFormat: true,
+      extractColorProfile: true
+    },
+    compression: {
+      enabled: true,
+      format: 'webp',
+      quality: 85,
+      maxDimension: 2048
+    }
+  }
+}
+```
+
+### 8.2 Video Type Options Example
+```typescript
+{
+  type: 'video',
+  options: {
+    accept: ['mp4', 'webm'],
+    maxSize: 104857600,                    // 100MB
+    maxDuration: 300,                      // 5 minutes
+    maxWidth: 1920,
+    maxHeight: 1080,
+    multiple: false,
+    maxFiles: 1,
+    thumbnail: {
+      enabled: true,
+      width: 320,
+      height: 180,
+      format: 'jpeg',
+      quality: 85,
+      captureTime: 1                       // At 1 second
+    },
+    preview: {
+      enabled: true,
+      maxWidth: 640,
+      maxHeight: 480,
+      controls: true,
+      autoplay: false,
+      muted: true
+    },
+    metadata: {
+      extractDuration: true,
+      extractResolution: true,
+      extractFormat: true,
+      extractCodec: true,
+      extractFrameRate: true,
+      extractBitrate: true
+    },
+    transcoding: {
+      enabled: true,
+      format: 'mp4',
+      codec: 'h264',
+      quality: 'medium',
+      maxDimension: 1280
+    }
+  }
+}
+```
+
+### 8.3 Audio Type Options Example
+```typescript
+{
+  type: 'audio',
+  options: {
+    accept: ['mp3', 'wav', 'ogg'],
+    maxSize: 52428800,                     // 50MB
+    maxDuration: 600,                      // 10 minutes
+    multiple: false,
+    maxFiles: 1,
+    waveform: {
+      enabled: true,
+      width: 800,
+      height: 100,
+      color: '#3498db'
+    },
+    preview: {
+      enabled: true,
+      controls: true,
+      autoplay: false,
+      visualizer: true
+    },
+    metadata: {
+      extractDuration: true,
+      extractFormat: true,
+      extractCodec: true,
+      extractBitrate: true,
+      extractSampleRate: true,
+      extractChannels: true,
+      extractID3Tags: true
+    },
+    transcoding: {
+      enabled: true,
+      format: 'mp3',
+      codec: 'mp3',
+      bitrate: 128,
+      sampleRate: 44100,
+      channels: 2
+    }
+  }
+}
+```
+
+---
+
+## 9. Implementation Guide: Adding Media Components
+
+### 9.1 Where to Add New Components
+
+**For OxInputImage, OxInputVideo, OxInputAudio:**
+- These should be added to **@operato/input** package (not dataset)
+- But you can create them in **Things-Factory dataset** package first as extensions
+
+**Suggested Location:**
+```
+packages/dataset/client/
+└── components/
+    ├── ox-input-image.ts      (NEW)
+    ├── ox-input-video.ts      (NEW)
+    ├── ox-input-audio.ts      (NEW)
+    ├── data-entry-form.ts     (existing)
+    └── checklist-entry-form.ts (existing)
+```
+
+### 9.2 Component Pattern (Example: OxInputImage)
+
+Based on OxInputFile implementation:
+
+```typescript
+import { css, html } from 'lit'
+import { customElement, property, query } from 'lit/decorators.js'
+import { OxFormField } from '@operato/input'
+
+@customElement('ox-input-image')
+export class OxInputImage extends OxFormField {
+  static styles = [
+    // CSS styles
+  ]
+
+  @property({ type: Boolean }) multiple? = false
+  @property({ type: String }) accept? = 'image/*'
+  @property({ type: String }) icon? = 'image'
+  @property({ type: String }) label? = 'Select images'
+  @property({ type: String }) description? = 'drop images here!'
+
+  @query('#input-file') fileInput?: HTMLInputElement
+
+  render() {
+    // Similar to OxInputFile but with image-specific styling
+  }
+
+  // Implement required methods: updated, firstUpdated, _onChangeValue, _notifyChange
+}
+```
+
+### 9.3 Update OxDataInputFactory
+
+**File:** `@operato/dataset` source (need to find source repo)
+
+**Add to createInputElement() switch:**
+```typescript
+case 'image':
+  return html`<ox-input-image name=${tag} .value=${value} .options=${options}></ox-input-image>`;
+case 'video':
+  return html`<ox-input-video name=${tag} .value=${value} .options=${options}></ox-input-video>`;
+case 'audio':
+  return html`<ox-input-audio name=${tag} .value=${value} .options=${options}></ox-input-audio>`;
+```
+
+**Add to mapGristType():**
+```typescript
+case 'image': return 'image';
+case 'video': return 'video';
+case 'audio': return 'audio';
+```
+
+**Add to getGristRecordOptions():**
+```typescript
+case 'image':
+case 'video':
+case 'audio':
+  return { multiple: options.multiple || false };
+```
+
+### 9.4 Update Component Imports
+
+**In wrapper components that import from @operato/dataset:**
+```typescript
+import '@operato/dataset/ox-input-image.js'
+import '@operato/dataset/ox-input-video.js'
+import '@operato/dataset/ox-input-audio.js'
+```
+
+Or add to ox-data-entry-form.js imports:
+```typescript
+import './ox-input-image.js'
+import './ox-input-video.js'
+import './ox-input-audio.js'
+```
+
+---
+
+## 10. Current Usage Flow
+
+### 10.1 Complete Data Collection Flow
+
+1. **Workflow Activity Triggered**
+   - `activity-data-collect-edit` receives dataSetId
+
+2. **DataSet Fetched**
+   - GraphQL query fetches DataSet with dataItems
+
+3. **Form Rendered**
+   - `OxDataEntryForm` renders based on DataSet
+   - `OxDataInputFactory.createInputElement()` creates inputs
+   - For subgroups: `OxDataEntrySubgroupForm` renders Grist table
+
+4. **User Enters Data**
+   - Files selected via native file inputs or ox-input-file
+   - Form tracks changes via @change events
+
+5. **Data Submitted**
+   - `buildValue()` extracts form values
+   - GraphQL mutation sends to server with `hasUpload: true`
+
+6. **Server Processing**
+   - `create-data-sample` controller processes files
+   - Media validation occurs for image/video/audio
+   - Attachments created and linked to DataSample
+   - File paths stored in data
+
+---
+
+## 11. Key Integration Points for Media Components
+
+### 11.1 Client-Side
+1. **OxDataInputFactory** - Add case statements for 'image', 'video', 'audio'
+2. **OxInputImage, OxInputVideo, OxInputAudio** - Create new components
+3. **Package.json** - Ensure proper dependencies
+
+### 11.2 Server-Side (Already Implemented)
+1. ✓ DataItemType enum includes image, video, audio
+2. ✓ Media validation utilities ready
+3. ✓ File/media options schema documented
+4. ✓ create-data-sample handles media validation and attachment
+
+### 11.3 Bootstrap
+- Import new components in bootstrap.ts or individual wrapper components
+
+---
+
+## 12. Directory Structure Summary
+
+```
+things-factory/packages/
+├── dataset/
+│   ├── client/
+│   │   ├── components/
+│   │   │   ├── data-entry-form.ts          (Form wrapper)
+│   │   │   ├── checklist-entry-form.ts     (Checklist wrapper)
+│   │   │   ├── ox-input-image.ts           (NEW - to create)
+│   │   │   ├── ox-input-video.ts           (NEW - to create)
+│   │   │   └── ox-input-audio.ts           (NEW - to create)
+│   │   ├── activities/
+│   │   │   └── activity-data-collect-edit.ts (Entry point)
+│   │   ├── bootstrap.ts                    (Component registration)
+│   │   └── index.ts
+│   │
+│   └── server/
+│       ├── service/data-set/
+│       │   └── data-item-type.ts           (DataItemType enum & schema)
+│       ├── utils/
+│       │   └── media-validation.ts         (Media validation utils)
+│       └── controllers/
+│           └── create-data-sample.ts       (File upload handling)
+│
+└── operato-dataset/ (Node modules dependency)
+    └── node_modules/@operato/dataset/
+        └── dist/src/
+            ├── ox-data-entry-form.js       (Main form component)
+            ├── ox-data-entry-subgroup-form.js (Grouped items)
+            └── ox-data-input-factory.js    (Type mapping factory)
+```
+
+---
+
+## Summary
+
+**Current State:**
+- File type has OxInputFile component for general file upload
+- Signature type has OxInputSignature
+- Image, video, audio types are DEFINED but NOT RENDERED
+
+**What Needs Implementation:**
+1. Create OxInputImage, OxInputVideo, OxInputAudio components
+2. Update OxDataInputFactory to handle these types
+3. Import components in appropriate locations
+4. Backend is already ready for media handling
+
+**Key Architecture Pattern:**
+- All components extend OxFormField
+- Input factory uses switch statement for type routing
+- Form values extracted via name attribute selectors
+- File upload via GraphQL multipart/form-data (hasUpload: true context)