@freighttech/ui 0.13.18

package/src/backend/injection/useOperationProgress.ts

@@ -0,0 +1,105 @@
+"use client"
+import { useState, useRef, useEffect } from 'react'
+import type { OperationProgressEvent } from '@open-mercato/shared/modules/widgets/injection-progress'
+import type { AppEventPayload } from '@open-mercato/shared/modules/widgets/injection'
+import { useAppEvent } from './useAppEvent'
+
+type ProgressStatus = 'idle' | 'running' | 'completed' | 'failed' | 'cancelled'
+
+interface OperationProgressState {
+  status: ProgressStatus
+  progress: number
+  processedCount: number
+  totalCount: number
+  currentStep?: string
+  errors: number
+  startedAt?: number
+  elapsedMs: number
+}
+
+const IDLE_STATE: OperationProgressState = {
+  status: 'idle',
+  progress: 0,
+  processedCount: 0,
+  totalCount: 0,
+  errors: 0,
+  elapsedMs: 0,
+}
+
+/**
+ * React hook that tracks long-running operation progress via the DOM Event Bridge.
+ *
+ * Listens for progress events matching the given pattern and aggregates state.
+ * When `operationId` is provided, only events for that specific operation are tracked.
+ *
+ * @param operationPattern - Event pattern to listen for (e.g., 'integration.sync.progress')
+ * @param operationId - Optional filter for a specific operation instance
+ *
+ * @example
+ * const progress = useOperationProgress('integration.sync.progress', syncRunId)
+ * if (progress.status === 'running') {
+ *   return <ProgressBar value={progress.progress} />
+ * }
+ */
+export function useOperationProgress(
+  operationPattern: string,
+  operationId?: string,
+): OperationProgressState {
+  const [state, setState] = useState<OperationProgressState>(IDLE_STATE)
+  const timerRef = useRef<ReturnType<typeof setInterval> | null>(null)
+  const startedAtRef = useRef<number | undefined>(undefined)
+
+  useEffect(() => {
+    return () => {
+      if (timerRef.current) {
+        clearInterval(timerRef.current)
+        timerRef.current = null
+      }
+    }
+  }, [])
+
+  useAppEvent(
+    operationPattern,
+    (event: AppEventPayload) => {
+      const payload = event.payload as unknown as OperationProgressEvent
+      if (!payload || typeof payload.status !== 'string') return
+      if (operationId && payload.operationId !== operationId) return
+
+      startedAtRef.current = payload.startedAt
+
+      const newState: OperationProgressState = {
+        status: payload.status,
+        progress: payload.progress,
+        processedCount: payload.processedCount,
+        totalCount: payload.totalCount,
+        currentStep: payload.currentStep,
+        errors: payload.errors,
+        startedAt: payload.startedAt,
+        elapsedMs: payload.startedAt ? Date.now() - payload.startedAt : 0,
+      }
+
+      setState(newState)
+
+      // Start elapsed time ticker when running
+      if (payload.status === 'running' && !timerRef.current) {
+        timerRef.current = setInterval(() => {
+          if (startedAtRef.current) {
+            setState((prev) => ({
+              ...prev,
+              elapsedMs: Date.now() - startedAtRef.current!,
+            }))
+          }
+        }, 1000)
+      }
+
+      // Clear ticker when operation ends
+      if (payload.status !== 'running' && timerRef.current) {
+        clearInterval(timerRef.current)
+        timerRef.current = null
+      }
+    },
+    [operationId],
+  )
+
+  return state
+}

package/src/backend/injection/useRegisteredComponent.tsx

@@ -0,0 +1,106 @@
+'use client'
+
+import * as React from 'react'
+import type { ComponentType } from 'react'
+import { getComponentEntry, getComponentOverrides } from '@open-mercato/shared/modules/widgets/component-registry'
+import { useOverrideUserFeatures } from './ComponentOverrideProvider'
+
+class ReplacementErrorBoundary extends React.Component<
+  { fallback: React.ReactNode; onError: (error: unknown) => void; children: React.ReactNode },
+  { hasError: boolean }
+> {
+  constructor(props: { fallback: React.ReactNode; onError: (error: unknown) => void; children: React.ReactNode }) {
+    super(props)
+    this.state = { hasError: false }
+  }
+
+  static getDerivedStateFromError(): { hasError: boolean } {
+    return { hasError: true }
+  }
+
+  componentDidCatch(error: unknown): void {
+    this.props.onError(error)
+  }
+
+  render() {
+    if (this.state.hasError) return this.props.fallback
+    return this.props.children
+  }
+}
+
+export function useRegisteredComponent<TProps>(
+  componentId: string,
+  fallback?: ComponentType<TProps>,
+): ComponentType<TProps> {
+  const userFeatures = useOverrideUserFeatures()
+  return React.useMemo(() => {
+    const entry = getComponentEntry(componentId)
+    const original = (entry?.component as ComponentType<TProps> | undefined) ?? fallback ?? null
+    if (!original) {
+      if (process.env.NODE_ENV !== 'production' && !fallback) {
+        console.warn(`[UMES] Component "${componentId}" is not registered.`)
+      }
+      const Missing = () => null
+      return Missing as ComponentType<TProps>
+    }
+    const overrides = getComponentOverrides(componentId, userFeatures)
+    const replacementOverrides = overrides.filter((override) => 'replacement' in override)
+    if (process.env.NODE_ENV !== 'production' && replacementOverrides.length > 1) {
+      console.warn(
+        `[UMES] Multiple replacements registered for "${componentId}". Highest-priority replacement is applied.`,
+      )
+    }
+
+    let replacement: ComponentType<TProps> | null = null
+    let replacementOverride: (typeof overrides)[number] | null = null
+    const wrappers: Array<(Original: ComponentType<TProps>) => ComponentType<TProps>> = []
+    const transforms: Array<(props: TProps) => TProps> = []
+
+    for (const override of overrides) {
+      if ('replacement' in override) {
+        replacement = override.replacement as ComponentType<TProps>
+        replacementOverride = override
+      }
+      if ('wrapper' in override) wrappers.push(override.wrapper as (Original: ComponentType<TProps>) => ComponentType<TProps>)
+      if ('propsTransform' in override) transforms.push(override.propsTransform as (props: TProps) => TProps)
+    }
+
+    const base = replacement ?? original
+    const wrapped = wrappers.reduce<ComponentType<TProps>>((acc, wrapper) => wrapper(acc), base)
+
+    const Resolved = (props: TProps) => {
+      const transformed = transforms.reduce((current, transform) => transform(current), props)
+      const Fallback = React.createElement(original as React.ComponentType<Record<string, unknown>>, transformed as Record<string, unknown>)
+      if (
+        process.env.NODE_ENV !== 'production'
+        && replacementOverride
+        && 'replacement' in replacementOverride
+      ) {
+        const validation = replacementOverride.propsSchema.safeParse(transformed)
+        if (!validation.success) {
+          console.error(
+            `[UMES] Props schema validation failed for replacement "${componentId}" from module "${replacementOverride.metadata?.module ?? 'unknown'}"`,
+            validation.error.format(),
+          )
+          return Fallback
+        }
+      }
+      return (
+        <ReplacementErrorBoundary
+          fallback={Fallback}
+          onError={(error) => {
+            const replacementModule = overrides.find((override) => 'replacement' in override)?.metadata?.module ?? 'unknown'
+            console.error(`[UMES] Component replacement failed for "${componentId}" from module "${replacementModule}"`, error)
+          }}
+        >
+          {React.createElement(wrapped as React.ComponentType<Record<string, unknown>>, transformed as Record<string, unknown>)}
+        </ReplacementErrorBoundary>
+      )
+    }
+
+    Resolved.displayName = `RegisteredComponent(${componentId})`
+    return Resolved
+  }, [componentId, fallback, userFeatures])
+}
+
+export default useRegisteredComponent

package/src/backend/injection/useWidgetSharedState.ts

@@ -0,0 +1,28 @@
+'use client'
+
+import * as React from 'react'
+import { getWidgetSharedState } from './WidgetSharedState'
+
+export function useWidgetSharedState<T>(key: string, namespace = 'global'): [T | undefined, (value: T) => void] {
+  const store = React.useMemo(() => getWidgetSharedState(namespace), [namespace])
+
+  const subscribe = React.useCallback(
+    (onStoreChange: () => void) => {
+      const unsubscribe = store.subscribe(key, () => onStoreChange())
+      return unsubscribe
+    },
+    [key, store],
+  )
+
+  const getSnapshot = React.useCallback(() => store.get<T>(key), [key, store])
+  const value = React.useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+
+  const setValue = React.useCallback(
+    (nextValue: T) => {
+      store.set<T>(key, nextValue)
+    },
+    [key, store],
+  )
+
+  return [value, setValue]
+}

package/src/backend/injection/visibility-utils.ts

@@ -0,0 +1,31 @@
+import type { FieldContext, FieldVisibilityCondition, FieldVisibilityRule } from '@open-mercato/shared/modules/widgets/injection'
+
+export function evaluateVisibilityRule(rule: FieldVisibilityRule, formData: Record<string, unknown>): boolean {
+  const current = formData[rule.field]
+  switch (rule.operator) {
+    case 'eq':
+      return current === rule.value
+    case 'neq':
+      return current !== rule.value
+    case 'in':
+      return Array.isArray(rule.value) ? rule.value.includes(current) : false
+    case 'notIn':
+      return Array.isArray(rule.value) ? !rule.value.includes(current) : true
+    case 'truthy':
+      return Boolean(current)
+    case 'falsy':
+      return !current
+    default:
+      return true
+  }
+}
+
+export function evaluateInjectedVisibility(
+  condition: FieldVisibilityCondition | undefined,
+  values: Record<string, unknown>,
+  context: FieldContext,
+): boolean {
+  if (!condition) return true
+  if (typeof condition === 'function') return condition(values, context)
+  return evaluateVisibilityRule(condition, values)
+}

package/src/backend/injection/widgetRegistry.ts

@@ -0,0 +1,68 @@
+import type { ModuleInjectionWidgetEntry } from '@open-mercato/shared/modules/registry'
+import type { InjectionWidgetModule } from '@open-mercato/shared/modules/widgets/injection'
+
+type Entry = ModuleInjectionWidgetEntry
+
+// Registration pattern for publishable packages
+let _injectionWidgetEntries: Entry[] | null = null
+
+export function registerInjectionWidgets(entries: Entry[]) {
+  if (_injectionWidgetEntries !== null && process.env.NODE_ENV === 'development') {
+    console.debug('[Bootstrap] Injection widgets re-registered (this may occur during HMR)')
+  }
+  _injectionWidgetEntries = entries
+}
+
+export function getInjectionWidgets(): Entry[] {
+  if (!_injectionWidgetEntries) {
+    // On client-side, bootstrap doesn't run - return empty array gracefully
+    if (typeof window !== 'undefined') {
+      return []
+    }
+    throw new Error('[Bootstrap] Injection widgets not registered. Call registerInjectionWidgets() at bootstrap.')
+  }
+  return _injectionWidgetEntries
+}
+
+let entriesPromise: Promise<Entry[]> | null = null
+
+async function getEntries(): Promise<Entry[]> {
+  if (!entriesPromise) {
+    const promise = Promise.resolve().then(() => getInjectionWidgets())
+    entriesPromise = promise.catch((err) => {
+      // Clear cache on error so next call can retry after registration
+      if (entriesPromise === promise) {
+        entriesPromise = null
+      }
+      throw err
+    })
+  }
+  return entriesPromise
+}
+
+type LoadedWidgetModule = InjectionWidgetModule<any, any>
+
+const cache = new Map<string, Promise<LoadedWidgetModule>>()
+
+async function findEntry(loaderKey: string): Promise<Entry | undefined> {
+  const entries = await getEntries()
+  return entries.find((entry) => entry.key === loaderKey)
+}
+
+export async function loadInjectionWidgetModule(loaderKey: string): Promise<LoadedWidgetModule | null> {
+  const entry = await findEntry(loaderKey)
+  if (!entry) return null
+  if (!cache.has(loaderKey)) {
+    cache.set(
+      loaderKey,
+      entry
+        .loader()
+        .then((mod) => {
+          const candidate = mod as LoadedWidgetModule
+          const maybeDefault = (mod as { default?: LoadedWidgetModule }).default
+          return maybeDefault ?? candidate
+        })
+    )
+  }
+  return cache.get(loaderKey) ?? null
+}

package/src/backend/inputs/ComboboxInput.tsx

@@ -0,0 +1,272 @@
+"use client"
+
+import * as React from 'react'
+import { Button } from '../../primitives/button'
+
+export type ComboboxOption = {
+  value: string
+  label: string
+  description?: string | null
+}
+
+export type ComboboxInputProps = {
+  value: string
+  onChange: (next: string) => void
+  placeholder?: string
+  suggestions?: Array<string | ComboboxOption>
+  loadSuggestions?: (query?: string) => Promise<Array<string | ComboboxOption>>
+  resolveLabel?: (value: string) => string
+  resolveDescription?: (value: string) => string | null | undefined
+  autoFocus?: boolean
+  disabled?: boolean
+  allowCustomValues?: boolean
+}
+
+function normalizeOptions(input?: Array<string | ComboboxOption>): ComboboxOption[] {
+  if (!Array.isArray(input)) return []
+  return input
+    .map((option) => {
+      if (typeof option === 'string') {
+        const trimmed = option.trim()
+        if (!trimmed) return null
+        return { value: trimmed, label: trimmed }
+      }
+      const value = typeof option.value === 'string' ? option.value.trim() : ''
+      if (!value) return null
+      return {
+        value,
+        label: option.label?.trim() || value,
+        description: option.description ?? null,
+      }
+    })
+    .filter((option): option is ComboboxOption => !!option)
+}
+
+export function ComboboxInput({
+  value,
+  onChange,
+  placeholder,
+  suggestions,
+  loadSuggestions,
+  resolveLabel,
+  resolveDescription,
+  autoFocus,
+  disabled = false,
+  allowCustomValues = true,
+}: ComboboxInputProps) {
+  const [input, setInput] = React.useState('')
+  const [asyncOptions, setAsyncOptions] = React.useState<ComboboxOption[]>([])
+  const [loading, setLoading] = React.useState(false)
+  const [touched, setTouched] = React.useState(false)
+  const [showSuggestions, setShowSuggestions] = React.useState(false)
+  const [selectedIndex, setSelectedIndex] = React.useState(-1)
+  const inputRef = React.useRef<HTMLInputElement>(null)
+
+  const staticOptions = React.useMemo(() => normalizeOptions(suggestions), [suggestions])
+
+  const optionMap = React.useMemo(() => {
+    const map = new Map<string, ComboboxOption>()
+    const register = (option: ComboboxOption) => {
+      if (!map.has(option.value)) {
+        map.set(option.value, option)
+      }
+    }
+    staticOptions.forEach(register)
+    asyncOptions.forEach(register)
+    if (value) {
+      const existing = map.get(value)
+      if (!existing) {
+        map.set(value, {
+          value,
+          label: resolveLabel?.(value) ?? value,
+          description: resolveDescription?.(value) ?? null,
+        })
+      }
+    }
+    return map
+  }, [asyncOptions, resolveDescription, resolveLabel, staticOptions, value])
+
+  const availableOptions = React.useMemo(() => {
+    return Array.from(optionMap.values())
+  }, [optionMap])
+
+  const filteredSuggestions = React.useMemo(() => {
+    const query = input.toLowerCase().trim()
+    if (!query) return availableOptions
+    return availableOptions.filter((option) => {
+      const labelMatch = option.label.toLowerCase().includes(query)
+      const descMatch = option.description?.toLowerCase().includes(query)
+      return labelMatch || Boolean(descMatch)
+    })
+  }, [availableOptions, input])
+
+  React.useEffect(() => {
+    if (!loadSuggestions || !touched || disabled) return
+    const query = input.trim()
+    let cancelled = false
+    const handle = window.setTimeout(async () => {
+      setLoading(true)
+      try {
+        const items = await loadSuggestions(query)
+        if (!cancelled) {
+          setAsyncOptions(normalizeOptions(items))
+        }
+      } finally {
+        if (!cancelled) setLoading(false)
+      }
+    }, 200)
+    return () => {
+      cancelled = true
+      window.clearTimeout(handle)
+    }
+  }, [disabled, input, loadSuggestions, touched])
+
+  // Sync input with value when value changes externally and input is not focused
+  React.useEffect(() => {
+    if (document.activeElement !== inputRef.current) {
+      const option = optionMap.get(value)
+      setInput(option?.label ?? value ?? '')
+    }
+  }, [value, optionMap])
+
+  const selectValue = React.useCallback(
+    (nextValue: string) => {
+      if (disabled) return
+      const trimmed = nextValue.trim()
+      onChange(trimmed)
+      const option = optionMap.get(trimmed)
+      setInput(option?.label ?? trimmed)
+      setShowSuggestions(false)
+      setSelectedIndex(-1)
+    },
+    [disabled, onChange, optionMap]
+  )
+
+  const findOptionForInput = React.useCallback(
+    (raw: string): ComboboxOption | null => {
+      const query = raw.trim().toLowerCase()
+      if (!query) return null
+      for (const option of optionMap.values()) {
+        if (option.value === raw.trim()) return option
+        if (option.label.toLowerCase() === query) return option
+      }
+      return null
+    },
+    [optionMap]
+  )
+
+  const confirmSelection = React.useCallback(
+    (raw: string) => {
+      if (disabled) return
+      const option = findOptionForInput(raw)
+      if (option) {
+        selectValue(option.value)
+        return
+      }
+      if (!allowCustomValues) {
+        // Revert to current value if custom values not allowed
+        const currentOption = optionMap.get(value)
+        setInput(currentOption?.label ?? value ?? '')
+        setShowSuggestions(false)
+        return
+      }
+      selectValue(raw)
+    },
+    [allowCustomValues, disabled, findOptionForInput, optionMap, selectValue, value]
+  )
+
+  const handleKeyDown = React.useCallback(
+    (event: React.KeyboardEvent<HTMLInputElement>) => {
+      if (disabled) return
+
+      if (event.key === 'ArrowDown') {
+        event.preventDefault()
+        if (!showSuggestions) {
+          setShowSuggestions(true)
+          setSelectedIndex(0)
+        } else {
+          setSelectedIndex((prev) => Math.min(prev + 1, filteredSuggestions.length - 1))
+        }
+      } else if (event.key === 'ArrowUp') {
+        event.preventDefault()
+        setSelectedIndex((prev) => Math.max(prev - 1, -1))
+      } else if (event.key === 'Enter') {
+        event.preventDefault()
+        if (selectedIndex >= 0 && filteredSuggestions[selectedIndex]) {
+          selectValue(filteredSuggestions[selectedIndex].value)
+        } else {
+          confirmSelection(input)
+        }
+      } else if (event.key === 'Escape') {
+        event.preventDefault()
+        setShowSuggestions(false)
+        setSelectedIndex(-1)
+      }
+    },
+    [confirmSelection, disabled, filteredSuggestions, input, selectValue, selectedIndex, showSuggestions]
+  )
+
+  return (
+    <div className="relative w-full">
+      <input
+        ref={inputRef}
+        type="text"
+        className="w-full h-9 rounded border px-2 text-sm disabled:bg-muted disabled:text-muted-foreground disabled:cursor-not-allowed"
+        value={input}
+        placeholder={placeholder || 'Type to search...'}
+        autoFocus={autoFocus}
+        data-crud-focus-target=""
+        disabled={disabled}
+        onFocus={() => {
+          setTouched(true)
+          setShowSuggestions(true)
+        }}
+        onChange={(event) => {
+          setTouched(true)
+          setInput(event.target.value)
+          setShowSuggestions(true)
+          setSelectedIndex(-1)
+        }}
+        onKeyDown={handleKeyDown}
+        onBlur={() => {
+          // Delay to allow click on suggestions
+          setTimeout(() => {
+            if (disabled) return
+            confirmSelection(input)
+          }, 200)
+        }}
+      />
+
+      {showSuggestions && !disabled && (loading || filteredSuggestions.length > 0) && (
+        <div className="absolute z-50 w-full mt-1 rounded border bg-popover shadow-lg max-h-48 sm:max-h-60 overflow-auto">
+          {loading && touched ? (
+            <div className="px-3 py-2 text-xs text-muted-foreground">Loading suggestions…</div>
+          ) : (
+            filteredSuggestions.map((option, index) => (
+              <Button
+                key={option.value}
+                type="button"
+                variant="ghost"
+                size="sm"
+                className={[
+                  'w-full h-auto justify-start font-normal text-left flex flex-col items-start px-3 py-2',
+                  index === selectedIndex ? 'bg-accent' : '',
+                ]
+                  .filter(Boolean)
+                  .join(' ')}
+                onMouseDown={(event) => event.preventDefault()}
+                onClick={() => selectValue(option.value)}
+                onMouseEnter={() => setSelectedIndex(index)}
+              >
+                <span className="font-medium">{option.label}</span>
+                {option.description ? (
+                  <span className="text-xs text-muted-foreground">{option.description}</span>
+                ) : null}
+              </Button>
+            ))
+          )}
+        </div>
+      )}
+    </div>
+  )
+}