feat(elements): add eco-provider-frame and dataprovider interfaces; improve virtual keyboard interactions; add demos, exports and bump dev dependencies

ts_web/elements/interfaces/dataprovider.ts

@@ -0,0 +1,158 @@
+/**
+ * Data Provider System Interfaces
+ *
+ * Data providers are external web apps that can be registered to provide
+ * or receive data from ecobridge applications. They communicate via
+ * postMessage API in sandboxed iframes.
+ */
+
+// Provider feature types - what capabilities a provider can offer
+export type TProviderFeature =
+  | 'scan-destination'    // Can receive scanned documents
+  | 'media-source'        // Can provide media URLs for playback
+  | 'document-storage'    // Can store/retrieve documents
+  | 'print-destination';  // Can receive print jobs
+
+// Provider connection status
+export type TProviderStatus = 'connected' | 'disconnected' | 'loading' | 'error';
+
+/**
+ * Data Provider configuration and state
+ */
+export interface IDataProvider {
+  id: string;
+  name: string;
+  url: string;
+  features: TProviderFeature[];          // Features declared by provider
+  confirmedFeatures: TProviderFeature[]; // Features user has approved
+  icon?: string;                          // Base64 data URL or icon URL
+  lastSeen: Date;
+  status: TProviderStatus;
+  enabled: boolean;
+}
+
+/**
+ * Provider registration payload (sent by provider on ready)
+ */
+export interface IProviderRegistration {
+  name: string;
+  features: TProviderFeature[];
+  icon?: string;
+  version?: string;
+}
+
+/**
+ * Message types from Provider to Ecobridge
+ */
+export type TProviderToEcobridgeMessageType =
+  | 'provider-ready'      // Provider loaded and declaring features
+  | 'provider-features'   // Provider updating its features
+  | 'provider-response'   // Response to an ecobridge request
+  | 'provider-error'      // Error occurred in provider
+  | 'data-offer';         // Provider offering data (e.g., media URL)
+
+/**
+ * Message from Provider to Ecobridge
+ */
+export interface IProviderMessage {
+  type: TProviderToEcobridgeMessageType;
+  providerId: string;
+  requestId?: string;     // For responses to specific requests
+  payload: unknown;
+}
+
+/**
+ * Provider ready message payload
+ */
+export interface IProviderReadyPayload {
+  name: string;
+  features: TProviderFeature[];
+  icon?: string;
+  version?: string;
+}
+
+/**
+ * Provider response payload
+ */
+export interface IProviderResponsePayload {
+  success: boolean;
+  data?: unknown;
+  error?: string;
+}
+
+/**
+ * Provider data offer payload (e.g., for media-source)
+ */
+export interface IProviderDataOfferPayload {
+  type: 'media-url' | 'document' | 'file-list';
+  data: unknown;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Message types from Ecobridge to Provider
+ */
+export type TEcobridgeToProviderMessageType =
+  | 'request-features'    // Ask provider to declare features
+  | 'send-data'           // Send data to provider (e.g., scan)
+  | 'request-data'        // Request data from provider (e.g., media URL)
+  | 'ping';               // Health check
+
+/**
+ * Message from Ecobridge to Provider
+ */
+export interface IEcobridgeMessage {
+  type: TEcobridgeToProviderMessageType;
+  requestId: string;
+  payload?: unknown;
+}
+
+/**
+ * Send data payload (e.g., sending scan to provider)
+ */
+export interface ISendDataPayload {
+  dataType: 'scan' | 'document' | 'print-job';
+  data: string;           // Base64 encoded data
+  format: string;         // File format (pdf, jpeg, etc.)
+  filename?: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Request data payload (e.g., requesting media from provider)
+ */
+export interface IRequestDataPayload {
+  dataType: 'media-url' | 'document' | 'file-list';
+  filter?: Record<string, unknown>;
+}
+
+/**
+ * Feature change event - when provider's features differ from confirmed
+ */
+export interface IFeatureChangeRequest {
+  providerId: string;
+  providerName: string;
+  addedFeatures: TProviderFeature[];
+  removedFeatures: TProviderFeature[];
+  currentFeatures: TProviderFeature[];
+}
+
+/**
+ * Provider store schema for persistence
+ */
+export interface IProviderStore {
+  providers: IDataProvider[];
+  lastUpdated: Date;
+}
+
+/**
+ * Events dispatched by eco-provider-frame
+ */
+export interface IProviderFrameEvents {
+  'provider-ready': CustomEvent<{ provider: IDataProvider }>;
+  'provider-features-changed': CustomEvent<{ request: IFeatureChangeRequest }>;
+  'provider-response': CustomEvent<{ requestId: string; response: IProviderResponsePayload }>;
+  'provider-data-offer': CustomEvent<{ offer: IProviderDataOfferPayload }>;
+  'provider-error': CustomEvent<{ error: string }>;
+  'provider-disconnected': CustomEvent<{ providerId: string }>;
+}