platformcommons-web-lib 1.0.0

package/src/lib/modules/smart-form/models/form-schema.model.ts

@@ -0,0 +1,700 @@
+import { ButtonVariant } from '../../button/button.models';
+
+export interface FormSchema {
+  entityType: string;
+  label: string;
+  formType: 'SECTION' | 'STEPPER';
+  showTitle?: boolean;
+  showDescription?: boolean;
+  description?: string;
+  metadata?: { [key: string]: any };
+  /**
+   * When true, top-level GROUP children of sectionConfig are rendered as
+   * a horizontal stepper at the top, showing one section at a time.
+   * Navigate between sections via the Next/Previous buttons in the host app.
+   */
+  sectionStepper?: boolean;
+  sectionConfig?: SectionConfig;
+  stepperConfig?: StepperConfig;
+  submitConfig?: SubmitConfig;
+  /**
+   * Configures the action bar shown at the bottom of the form.
+   * Supports Cancel, Save as Draft, and Submit buttons with flexible layout.
+   * If omitted, the default Submit (and stepper Prev/Next) behaviour is unchanged.
+   */
+  actionBarConfig?: ActionBarConfig;
+  showActions?: boolean;
+  /** Full token string passed to all library API calls (e.g. "Bearer eyJ…") */
+  token?: string;
+  /** HTTP header name to use for the token (default: "Authorization") */
+  tokenHeader?: string;
+  /** Custom label keys for form actions */
+  labels?: FormLabels;
+  /** Config for form editing (GET to load, PATCH/PUT to submit) */
+  editConfig?: EditConfig;
+}
+
+export interface FormLabels {
+  nextLabel?: string;
+  submitLabel?: string;
+  previousLabel?: string;
+  addLabel?: string;
+  removeLabel?: string;
+  /** File upload error messages. Supports placeholders: {fileName}, {maxSizeMB}, {maxFiles} */
+  fileTypeError?: string;
+  fileSizeError?: string;
+  maxFilesError?: string;
+  fileUploadFailed?: string;
+  fileDeleteFailed?: string;
+}
+
+export interface SubmitConfig {
+  apiUrl: string;
+  method?: 'POST' | 'PUT' | 'PATCH';
+  successMessage?: string;
+  errorMessage?: string;
+  redirectUrl?: string; // Redirect after success
+  extraPayload?: { [key: string]: any }; // Static extra fields for payload
+  snackbarConfig?: {
+    duration?: number;
+    horizontalPosition?: 'start' | 'center' | 'end' | 'left' | 'right';
+    verticalPosition?: 'top' | 'bottom';
+    showCloseButton?: boolean;
+  };
+}
+
+// ─── Action Bar ──────────────────────────────────────────────────────────────
+
+/**
+ * Describes what happens when an action bar button is clicked.
+ * One ActionConfig shape works for every button.
+ */
+export interface ActionConfig {
+  /**
+   * Action kind.
+   * 'submit'   -> Validates and submits form using submitConfig/editConfig.
+   * 'draft'    -> Saves form data without full validation.
+   * 'navigate' -> Navigates to redirectUrl.
+   * 'api'      -> Fires an API call then optionally navigates.
+   * 'emit'     -> Emits actionClick event for custom handling.
+   * 'next'     -> Advances to next step (stepper only).
+   * 'prev'     -> Goes back to previous step (stepper only).
+   */
+  kind: 'submit' | 'draft' | 'navigate' | 'api' | 'emit' | 'next' | 'prev';
+  /** URL for 'navigate' or 'api' callbacks. */
+  redirectUrl?: string;
+  /** API endpoint for 'api' actions. */
+  apiUrl?: string;
+  /** HTTP method for 'api' actions. @default 'POST' */
+  method?: 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  /** Static extra payload merged into 'api' or 'draft' requests. */
+  extraPayload?: { [key: string]: any };
+  /** Snackbar messages for 'api' or 'submit'/'draft' actions. */
+  successMessage?: string;
+  errorMessage?: string;
+  snackbarConfig?: {
+    duration?: number;
+    horizontalPosition?: 'start' | 'center' | 'end' | 'left' | 'right';
+    verticalPosition?: 'top' | 'bottom';
+    showCloseButton?: boolean;
+  };
+}
+
+/**
+ * Button configuration focusing on visuals and layout.
+ * All logic is delegated to the 'action' property.
+ */
+export interface ActionButtonConfig {
+  /** Unique identifier for the button. */
+  id: string;
+  /** Label (i18n key or text). */
+  label?: string;
+  /** Button style variant. */
+  variant?: ButtonVariant | string;
+  /** Bar alignment. @default 'right' */
+  alignment?: 'left' | 'right';
+  /** Display order (lower = first). */
+  order?: number;
+  /** Visibility. @default false */
+  hidden?: boolean;
+  /** State. @default false */
+  disabled?: boolean;
+  /**
+   * When true and sectionStepper is active, this button is only visible
+   * on the last step. Use this for Submit buttons that should not appear
+   * on intermediate steps.
+   */
+  showOnLastStepOnly?: boolean;
+  /** Action logic. */
+  action: ActionConfig;
+}
+
+/**
+ * Action bar configuration.
+ */
+export interface ActionBarConfig {
+  /** Flexibly ordered list of action buttons. */
+  buttons: ActionButtonConfig[];
+}
+
+
+export interface EditConfig {
+  loadApiUrl: string;       // Custom GET API to load existing form data
+  submitApiUrl: string;     // PATCH/PUT/POST API for updating
+  submitMethod?: 'PATCH' | 'PUT' | 'POST';
+  successMessage?: string;
+  errorMessage?: string;
+  redirectUrl?: string;
+  extraPayload?: { [key: string]: any };
+  snackbarConfig?: {
+    duration?: number;
+    horizontalPosition?: 'start' | 'center' | 'end' | 'left' | 'right';
+    verticalPosition?: 'top' | 'bottom';
+    showCloseButton?: boolean;
+  };
+}
+
+export interface SectionConfig {
+  children: FieldConfig[];
+  allowMulti?: boolean;
+  name?: string;
+  label?: string;
+  /** Configuration for the card-based multi-save UI (FAQ style) */
+  multiSaveConfig?: MultiSaveConfig;
+  isEnabled?: boolean;
+}
+
+export interface MultiSaveConfig {
+  /** If TRUE, enable the Save/Cancel card-based flow for this repeater */
+  active?: boolean;
+  /** 
+   * The name of the field to show as the main 'heading' in the collapsed card.
+   * Typically matches the question or name.
+   */
+  summaryField?: string;
+  /** 
+   * Optional name of the field to show as the sub-text in the collapsed card.
+   * Typically matches the answer or description.
+   */
+  descriptionField?: string;
+  /**
+   * Custom label key for the 'Add' button. If omitted, defaults to 
+   * '+ Add a [label]'.
+   */
+  addLabel?: string;
+}
+
+export interface StepperConfig {
+  children: FieldConfig[];
+  showStep?: boolean;
+  isHorizontal?: boolean;
+}
+
+/**
+ * Describes a clickable action icon rendered as a suffix inside a TEXT_INPUT
+ * or NUMBER_INPUT field. Multiple icons can be shown side-by-side.
+ * When clicked, the field name and actionId are emitted via the
+ * SmartFormComponent's `suffixActionClick` output.
+ */
+export interface SuffixActionIcon {
+  /** Material icon name (e.g. 'edit', 'refresh', 'check', 'lock') */
+  icon: string;
+  /** Unique action identifier emitted on click (e.g. 'enable_edit', 'reset_code') */
+  actionId: string;
+  /** Optional tooltip shown on hover */
+  tooltip?: string;
+  /** Optional custom color override (e.g. '#16A34A' for a green check icon) */
+  color?: string;
+}
+
+export interface FieldConfig {
+  name?: string;
+  label?: string;
+  type: string;
+  subType?: string;
+  visible?: boolean;
+  visibilityExpression?: string;
+  isEnabled?: boolean;
+  required?: boolean;
+  disabled?: boolean;
+  defaultValue?: any;
+  placeholder?: string;
+  hint?: string;
+  /** Dot-notation path for nested payload mapping (e.g., 'status.code') */
+  payloadPath?: string;
+  /**
+   * Column span in a 12-column grid (1–12).
+   * Use this on any field or ROW to control its width.
+   * Examples: 3 = 25%, 4 = 33%, 6 = 50%, 12 = 100% (default).
+   * When a field is inside a ROW, the ROW children share space via colSpan.
+   * When a field is a direct section child (not inside a ROW), colSpan wraps
+   * it in the section-level 12-col grid automatically.
+   */
+  colSpan?: number;
+  /** Custom CSS class for the field container */
+  className?: string;
+  /** Unit or symbol shown before the input */
+  prefix?: string;
+  /** Unit or symbol shown after the input (e.g. "%", "Students") */
+  suffix?: string;
+  /** Whether the field is read-only (shows lock icon) */
+  readonly?: boolean;
+  /**
+   * Clickable action icons rendered as suffixes inside the input.
+   * Ignored when `readonly` is true (the built-in lock icon takes precedence).
+   * Each icon emits a `suffixActionClick` event with `{ fieldName, actionId }`.
+   */
+  suffixActionIcons?: SuffixActionIcon[];
+  sectionConfig?: SectionConfig;
+  /**
+   * Cross-field validation config for SUBFIELDS groups.
+   * Applied as a group-level validator on the nested FormGroup.
+   */
+  onChange?: string;
+  onValidate?: string;
+  errorMessage?: string;
+  textConfig?: TextConfig;
+  emailConfig?: EmailConfig;
+  phoneConfig?: PhoneConfig;
+  numberConfig?: NumberConfig;
+  dateConfig?: DateConfig;
+  timeConfig?: TimeConfig;
+  optionConfig?: OptionConfig;
+  autocompleteConfig?: AutocompleteConfig;
+  generatedConfig?: GeneratedConfig;
+  rangeConfig?: RangeConfig;
+  attachmentConfig?: AttachmentConfig;
+  locationConfig?: LocationConfig;
+  ratingConfig?: RatingConfig;
+  richTextConfig?: RichTextConfig;
+  children?: FieldConfig[];
+}
+
+export interface TextConfig {
+  length?: LengthConstraint;
+  pattern?: string;
+  patternMessage?: string;
+  inputType?: string;
+  /**
+   * Name of another field in the same FormGroup whose value must equal this
+   * field's value (e.g. "password" on a confirmPassword field).
+   * Validation runs bi-directionally: whichever field changes last triggers
+   * the check on the field that carries matchField config.
+   */
+  matchField?: string;
+  showCharCount?: boolean;
+}
+
+export interface LengthConstraint {
+  min?: number;
+  max?: number;
+}
+
+export interface NumberConfig {
+  min?: number;
+  max?: number;
+  precision?: number;
+  step?: number;
+}
+
+export interface DateConfig {
+  allowFuture?: boolean;
+  /** When false, dates before today are disabled (today is the minimum). When true (default), all past dates are allowed. */
+  allowPast?: boolean;
+  minDate?: string;
+  maxDate?: string;
+  /** When true, the text input is readonly (picker-only, no keyboard entry). */
+  inputReadonly?: boolean;
+  /** Name of a sibling field whose value is used as the dynamic minimum date. */
+  minDateField?: string;
+}
+
+export interface TimeConfig {
+  /** Explicit minimum time in "HH:mm" 24-hour format (e.g. "09:00"). */
+  minTime?: string;
+  /** Explicit maximum time in "HH:mm" 24-hour format (e.g. "18:00"). */
+  maxTime?: string;
+  /** When true, the input is readonly. */
+  inputReadonly?: boolean;
+  /**
+   * Name of a sibling TIME field whose value is used as the dynamic minimum time.
+   * When the sibling changes, this field's minimum updates and any now-invalid
+   * value (earlier than the new minimum) is cleared. Mirrors DateConfig.minDateField.
+   */
+  minTimeField?: string;
+}
+
+export interface OptionConfig {
+  optionClass?: string;
+  optionUrl?: string; // Legacy API URL
+  apiUrl?: string;    // Preferred API URL
+  apiUrls?: string[]; // Multiple API URLs to merge
+  dataPath?: string;  // Path to array in response (e.g. 'data.items')
+  labelPath?: string; // Path to label (e.g. 'name[0].text')
+  valuePath?: string; // Path to value (e.g. 'data.code')
+  dependencies?: { [queryParam: string]: string }; // Map query param to field name (e.g. { 'parentId': 'parentField' })
+  sortBy?: string;    // Path to field to sort by (e.g. 'name.text')
+  sortDirection?: 'ASC' | 'DESC'; // Sort direction (default: 'ASC')
+  layout?: 'row' | 'column'; // Layout for options (default: 'row')
+  optionList?: OptionItem[];
+}
+
+// ── Autocomplete Display Field ────────────────────────────────────────────────
+
+export interface AutocompleteDisplayField {
+  /** Dot-notation path to the value in the API response item (e.g. 'login', 'contact.phone'). */
+  path: string;
+  /** 
+   * How to render the value. 
+   * Built-in: 'text' | 'email' | 'phone' | 'image'.
+   * Can be any string for custom logic/styling.
+   */
+  type?: 'text' | 'email' | 'phone' | 'image' | string;
+  /** Optional Material Icon name to show (e.g. 'location_on', 'calendar_today', 'person'). */
+  icon?: string;
+  /** Optional label prefix shown before the value (e.g. 'Email: '). */
+  label?: string;
+  /** Custom CSS class to apply to this display item. */
+  className?: string;
+}
+
+// ── Autocomplete Config ───────────────────────────────────────────────────────
+
+/**
+ * Configuration specific to the AUTOCOMPLETE field type.
+ * For detailed documentation and examples, see documentation/smart-form.md.
+ */
+export interface AutocompleteConfig {
+  // ── HTTP Request Configuration ─────────────────────────────────────────
+  /** HTTP method for the options API. Defaults to 'GET'. */
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH';
+  /** Static request body sent with POST/PUT/PATCH requests. */
+  body?: any;
+  /** Static query parameters to append to the API URL on every request. */
+  queryParams?: { [key: string]: any };
+  /** Custom HTTP headers to send with the API request (e.g. Authorization, X-TENANT). */
+  headers?: { [key: string]: string };
+
+  // ── Label Building ────────────────────────────────────────────────────
+  /**
+   * Template string for building a composite label from multiple fields.
+   * Use {fieldName} placeholders. E.g. '{firstName} {lastName} ({login})'.
+   * Takes precedence over optionConfig.labelPath if both are set.
+   */
+  labelTemplate?: string;
+
+  // ── Extra Fields Shown in the Dropdown Option ─────────────────────────
+  /**
+   * One or more extra fields to render below the main label inside each dropdown option.
+   *
+   * Accepts:
+   *  - A plain string  → treated as a single dot-notation path rendered as 'text'.
+   *    Backward-compatible with the old `displayPath` string.
+   *  - An array of AutocompleteDisplayField objects → full control over icon,
+   *    type (text | email | phone | image), and optional label prefix.
+   *
+   * Examples:
+   *   "displayFields": "login"
+   *   "displayFields": [
+   *     { "path": "login",    "type": "email" },
+   *     { "path": "phone",    "type": "phone" },
+   *     { "path": "photoUrl", "type": "image" }
+   *   ]
+   */
+  displayFields?: string | AutocompleteDisplayField[];
+
+  // ── Server-side Search ────────────────────────────────────────────────
+  /** Query parameter key appended to the URL when the user types (e.g. 'searchTerm', 'q'). */
+  searchParam?: string;
+  /** Alias for 'searchParam'. */
+  searchKey?: string;
+  /** Minimum characters to type before a server request fires (default: 1). */
+  searchMinLength?: number;
+  /** Debounce delay in ms before firing the search request (default: 300ms server-side, 150ms local). */
+  searchDebounce?: number;
+}
+
+export interface EmailConfig {
+  defaultDomain?: string;
+  allowedDomains?: string[];
+  blockedDomains?: string[];
+}
+
+export interface PhoneConfig {
+  prefixCountryCode?: boolean;
+  defaultCountryCode?: string;
+  supportedCountryCodeLocale?: string[];
+}
+
+export interface OptionItem {
+  label: string;
+  code: any;
+  value?: any;
+  hint?: string; // Hint text for the option
+  colSpan?: number; // Grid column span
+}
+export interface GeneratedConfig {
+  formula: string;
+  variables?: string[];
+}
+
+export interface RangeConfig {
+  min?: number;
+  max?: number;
+  step?: number;
+  minDate?: string;
+  maxDate?: string;
+}
+
+
+/**
+ * Describes a single query-parameter for a parameterised API URL.
+ * Supports static values (baked into the JSON config) and dynamic values
+ * resolved at runtime from a context object via dot-notation `sourcePath`.
+ *
+ * Used inside `LibraryUploadConfig.params` to declaratively list all
+ * query params the library-image sync API needs.
+ */
+export interface ApiQueryParam {
+  /** The query-param key sent to the backend (e.g. 'entityType', 'completeUrl'). */
+  key: string;
+  /**
+   * A static value baked into the JSON config
+   * (e.g. 'ENTITY_TYPE.OPPORTUNITY_GALLERY').
+   * Leave unset when the value must be resolved dynamically at runtime.
+   */
+  staticValue?: string;
+  /**
+   * A dot-notation path resolved against a runtime context object
+   * (e.g. 'libraryItem.url'). Takes precedence over `staticValue`
+   * when the context provides a non-null value.
+   */
+  sourcePath?: string;
+  /**
+   * When true the HTTP request is aborted if this param cannot be resolved
+   * to a non-empty value.
+   */
+  required?: boolean;
+}
+
+/**
+ * Structured config for the library-image sync POST API.
+ * Declare each query param as an `ApiQueryParam` so the set can grow
+ * without any code changes.
+ *
+ * Example:
+ * {
+ *   "baseUrl": "gateway/commons-opportunity-service/api/v1/attachments/upload-url",
+ *   "params": [
+ *     { "key": "entityType", "staticValue": "ENTITY_TYPE.OPPORTUNITY_GALLERY", "required": true },
+ *     { "key": "completeUrl", "sourcePath": "libraryItem.url", "required": true }
+ *   ]
+ * }
+ */
+export interface LibraryUploadConfig {
+  /** Base URL without any query string. */
+  baseUrl: string;
+  /**
+   * Declared query params. Static values are embedded in the config;
+   * dynamic values (e.g. `completeUrl`) are resolved at call time from
+   * a runtime context object using `sourcePath`.
+   */
+  params?: ApiQueryParam[];
+}
+
+/**
+ * All library-image picker settings grouped under one roof.
+ * Used as the `libraryConfig` key inside `AttachmentConfig`.
+ *
+ * Example:
+ * {
+ *   "apiUrl": "gateway/.../attachments/bulk/public?entityIds=1&entityType=...",
+ *   "dataPath": "data",
+ *   "urlPath": "completeURL",
+ *   "idPath": "id",
+ *   "uploadConfig": {
+ *     "baseUrl": "gateway/.../attachments/upload-url",
+ *     "params": [
+ *       { "key": "entityType", "staticValue": "ENTITY_TYPE.OPPORTUNITY_GALLERY", "required": true },
+ *       { "key": "completeUrl", "sourcePath": "libraryItem.url", "required": true }
+ *     ]
+ *   }
+ * }
+ */
+export interface LibraryConfig {
+  /** API endpoint (GET) to load the library image list. */
+  apiUrl: string;
+  /** Dot-notation path to the image array in the API response (e.g. 'data.items'). */
+  dataPath?: string;
+  /** Dot-notation path to the image URL within each item (e.g. 'completeURL'). */
+  urlPath?: string;
+  /** Dot-notation path to the image ID within each item (e.g. 'id'). */
+  idPath?: string;
+  /**
+   * Structured config for the library-image sync POST API.
+   * Declare each query param as an `ApiQueryParam` so the set can
+   * grow without any code changes.
+   */
+  uploadConfig?: LibraryUploadConfig;
+}
+
+/**
+ * Unified attachment / file-upload configuration.
+ * Used by FILE_UPLOAD fields for any kind of upload — images, documents, PDFs, etc.
+ */
+export interface AttachmentConfig {
+  /** Allow multiple file selection (default: false) */
+  multiple?: boolean;
+  /** Max number of files when multiple=true (default: 10) */
+  maxFiles?: number;
+  /** Max file size per file in MB (default: 10) */
+  maxSizeMB?: number;
+  /** Accepted MIME types or extensions, e.g. '.pdf,.jpg,image/*' */
+  accept?: string;
+  /** Human-readable hint shown in the drop zone, e.g. 'JPG, PNG, PDF (max 5 MB)' */
+  acceptLabel?: string;
+  /** Legacy: explicit list of allowed extensions (e.g. ['.pdf', '.jpg']) */
+  allowedExtensions?: string[];
+  /**
+   * API endpoint to upload the file to. When provided, the file is POSTed as
+   * multipart/form-data and the returned URL is stored as dataUrl instead of
+   * the base64 data URL produced by FileReader.
+   */
+  uploadUrl?: string;
+  /**
+   * Entity type sent along with the upload request (e.g. 'ENTITY_TYPE.SESSION').
+   * Only relevant when uploadUrl is set.
+   */
+  entityType?: string;
+  /**
+   * API endpoint to delete the file. Called when an uploaded file with an ID != 0 is removed.
+   */
+  deleteUrl?: string;
+  /**
+   * All library-image picker settings (API, response paths, sync upload).
+   * Replaces the former flat `libraryApiUrl`, `libraryDataPath`,
+   * `libraryUrlPath`, `libraryIdPath`, and `libraryUploadConfig` fields.
+   */
+  libraryConfig?: LibraryConfig;
+  /** Optional description shown in the left info panel for media upload */
+  description?: string;
+  /** Optional bullet-point feature lines shown in the left info panel for media upload */
+  features?: string[];
+}
+
+export interface LocationConfig {
+  /** Default active tab (e.g. 'VENUE', 'ONLINE', 'TBA'). Defaults to 'VENUE' when not provided. */
+  defaultTab?: string;
+  /** Allow multiple locations. Replaces the need for maxLocations. */
+  allowMulti?: boolean;
+  /** Maximum number of venue locations allowed. Defaults to 5 if allowMulti is true. */
+  maxLocations?: number;
+  /** Placeholder for the venue search input */
+  venuePlaceholder?: string;
+  /** Google Maps API Key – required for map rendering and autocomplete */
+  googleMapsApiKey?: string;
+  /** Height of the embedded Google Map. Defaults to '300px'. */
+  mapHeight?: string;
+  /** Default map center latitude when no locations are added (e.g., India: 20.5937) */
+  defaultLat?: number;
+  /** Default map center longitude when no locations are added (e.g., India: 78.9629) */
+  defaultLng?: number;
+  /** Default zoom level when no locations are added (e.g., 4) */
+  defaultZoom?: number;
+  /** Placeholder for the online event URL input */
+  onlinePlaceholder?: string;
+  /** Show map preview after locations are added (default: true) */
+  showMap?: boolean;
+  /** Whether the current location button is enabled inside venue tab */
+  enableCurrentLocation?: boolean;
+  /** @deprecated Use showMap instead */
+  enableMapPicker?: boolean;
+}
+
+
+/** A single venue location picked from Google Places autocomplete. */
+export interface LocationItem {
+  uuid?: string;
+  isActive?: boolean;
+  id?: number;
+  locationCode?: string;
+  latitude?: number;
+  longitude?: number;
+  address?: string;
+  name?: string;
+  cityLabel?: string;
+  stateLabel?: string;
+  countryLabel?: string;
+  placeId?: string;
+  type?: string;
+
+  /** Legacy field for UI binding */
+  description?: string;
+}
+
+/**
+ * Value shape stored in the FormControl for a LOCATION field.
+ * `tab` indicates which mode is active.
+ */
+export interface LocationFieldValue {
+  /** Active location tab (e.g. 'VENUE', 'ONLINE', 'TBA'). Defaults to 'VENUE'. */
+  tab: string;
+  /** Array of venue locations (only valid when tab === 'VENUE') */
+  venues?: LocationItem[];
+  /** Event URL (only valid when tab === 'ONLINE') */
+  onlineUrl?: string;
+}
+
+export interface RatingConfig {
+  maxRating?: number;
+  allowHalf?: boolean;
+}
+
+export interface RichTextConfig {
+  height?: string;
+  placeholder?: string;
+  maxLength?: number;
+  showCharCount?: boolean;
+}
+
+export interface ValidationResult {
+  isValid: boolean;
+  errorMessage?: string;
+  fieldErrors?: { [key: string]: string };
+}
+
+/** A single uploaded file entry stored in the control value array */
+export interface UploadedFile {
+  id?: number;
+  name: string;
+  size: number;
+  type: string;
+  /** base64 data URL, remote URL returned by upload API, or object URL – used for preview */
+  dataUrl?: string;
+  /** Raw File handle */
+  file: File;
+  /** True while the file is being uploaded to the server via uploadUrl */
+  isUploading?: boolean;
+}
+
+/**
+ * A single media item stored in the MEDIA_UPLOAD field value array.
+ * Can represent an uploaded image (from device or library) or a YouTube video.
+ */
+export interface MediaItem {
+  /** Server-assigned ID (for pre-filled items) */
+  id?: number;
+  /** Media type (e.g. 'image', 'youtube'). Defaults to 'image'. */
+  mediaType: string;
+  /** Remote URL of the image returned by the upload API, or the YouTube embed URL */
+  url: string;
+  /** Thumbnail URL (for YouTube previews) */
+  thumbnailUrl?: string;
+  /** MIME type returned by the upload API (e.g. 'image/png') */
+  mimeType?: string;
+  /** File name returned by the upload API */
+  fileName?: string;
+  /** True while the file is being uploaded */
+  isUploading?: boolean;
+}
+