@rozenite/controls-plugin 1.4.0

package/src/__tests__/serialization.test.ts

@@ -0,0 +1,210 @@
+import { describe, expect, it, vi } from 'vitest';
+import { buildActionRegistry, getActionRegistryKey, serializeSections } from '../shared/serialization';
+import { createSection } from '../shared/types';
+
+describe('controls serialization', () => {
+  it('omits callbacks from snapshots', () => {
+    const sections = [
+      createSection({
+        id: 'diagnostics',
+        title: 'Diagnostics',
+        items: [
+          {
+            id: 'status',
+            type: 'text',
+            title: 'Status',
+            value: 'ready',
+          },
+          {
+            id: 'enabled',
+            type: 'toggle',
+            title: 'Enabled',
+            value: true,
+            validate: vi.fn(() => ({ valid: true as const })),
+            onUpdate: vi.fn(),
+          },
+          {
+            id: 'reset',
+            type: 'button',
+            title: 'Reset',
+            onPress: vi.fn(),
+          },
+          {
+            id: 'environment',
+            type: 'select',
+            title: 'Environment',
+            value: 'staging',
+            options: [
+              { label: 'Local', value: 'local' },
+              { label: 'Staging', value: 'staging' },
+            ],
+            validate: vi.fn(() => ({ valid: true as const })),
+            onUpdate: vi.fn(),
+          },
+          {
+            id: 'release-label',
+            type: 'input',
+            title: 'Release Label',
+            value: 'build-001',
+            placeholder: 'build-001',
+            applyLabel: 'Apply',
+            validate: vi.fn(() => ({ valid: true as const })),
+            onUpdate: vi.fn(),
+          },
+        ],
+      }),
+    ];
+
+    expect(serializeSections(sections)).toEqual([
+      {
+        id: 'diagnostics',
+        title: 'Diagnostics',
+        description: undefined,
+        items: [
+          {
+            id: 'status',
+            type: 'text',
+            title: 'Status',
+            value: 'ready',
+          },
+          {
+            id: 'enabled',
+            type: 'toggle',
+            title: 'Enabled',
+            value: true,
+            description: undefined,
+            disabled: undefined,
+          },
+          {
+            id: 'reset',
+            type: 'button',
+            title: 'Reset',
+            actionLabel: undefined,
+            description: undefined,
+            disabled: undefined,
+          },
+          {
+            id: 'environment',
+            type: 'select',
+            title: 'Environment',
+            value: 'staging',
+            options: [
+              { label: 'Local', value: 'local' },
+              { label: 'Staging', value: 'staging' },
+            ],
+            description: undefined,
+            disabled: undefined,
+          },
+          {
+            id: 'release-label',
+            type: 'input',
+            title: 'Release Label',
+            value: 'build-001',
+            placeholder: 'build-001',
+            applyLabel: 'Apply',
+            description: undefined,
+            disabled: undefined,
+          },
+        ],
+      },
+    ]);
+  });
+
+  it('builds an action registry for interactive items', async () => {
+    const onUpdateToggle = vi.fn();
+    const onPress = vi.fn();
+    const onUpdateSelect = vi.fn();
+    const onUpdateInput = vi.fn();
+    const validateToggle = vi.fn(() => ({ valid: true as const }));
+    const validateSelect = vi.fn(() => ({ valid: true as const }));
+    const validateInput = vi.fn(() => ({ valid: true as const }));
+
+    const sections = [
+      createSection({
+        id: 'controls',
+        title: 'Controls',
+        items: [
+          {
+            id: 'flag',
+            type: 'toggle',
+            title: 'Flag',
+            value: false,
+            validate: validateToggle,
+            onUpdate: onUpdateToggle,
+          },
+          {
+            id: 'refresh',
+            type: 'button',
+            title: 'Refresh',
+            onPress,
+          },
+          {
+            id: 'environment',
+            type: 'select',
+            title: 'Environment',
+            value: 'local',
+            options: [
+              { label: 'Local', value: 'local' },
+              { label: 'Staging', value: 'staging' },
+            ],
+            validate: validateSelect,
+            onUpdate: onUpdateSelect,
+          },
+          {
+            id: 'release-label',
+            type: 'input',
+            title: 'Release Label',
+            value: 'build-001',
+            placeholder: 'build-001',
+            applyLabel: 'Apply',
+            validate: validateInput,
+            onUpdate: onUpdateInput,
+          },
+        ],
+      }),
+    ];
+
+    const registry = buildActionRegistry(sections);
+
+    const toggleEntry = registry.get(getActionRegistryKey('controls', 'flag'));
+    const buttonEntry = registry.get(getActionRegistryKey('controls', 'refresh'));
+    const selectEntry = registry.get(
+      getActionRegistryKey('controls', 'environment')
+    );
+    const inputEntry = registry.get(
+      getActionRegistryKey('controls', 'release-label')
+    );
+
+    expect(toggleEntry?.type).toBe('toggle');
+    expect(buttonEntry?.type).toBe('button');
+    expect(selectEntry?.type).toBe('select');
+    expect(inputEntry?.type).toBe('input');
+
+    if (toggleEntry?.type === 'toggle') {
+      expect(toggleEntry.validate?.(true)).toEqual({ valid: true });
+      await toggleEntry.onUpdate(true);
+    }
+
+    if (buttonEntry?.type === 'button') {
+      await buttonEntry.onPress();
+    }
+
+    if (selectEntry?.type === 'select') {
+      expect(selectEntry.validate?.('staging')).toEqual({ valid: true });
+      await selectEntry.onUpdate('staging');
+    }
+
+    if (inputEntry?.type === 'input') {
+      expect(inputEntry.validate?.('build-002')).toEqual({ valid: true });
+      await inputEntry.onUpdate('build-002');
+    }
+
+    expect(validateToggle).toHaveBeenCalledWith(true);
+    expect(onUpdateToggle).toHaveBeenCalledWith(true);
+    expect(onPress).toHaveBeenCalledTimes(1);
+    expect(validateSelect).toHaveBeenCalledWith('staging');
+    expect(onUpdateSelect).toHaveBeenCalledWith('staging');
+    expect(validateInput).toHaveBeenCalledWith('build-002');
+    expect(onUpdateInput).toHaveBeenCalledWith('build-002');
+  });
+});

package/src/react-native/useRozeniteControlsPlugin.ts

@@ -0,0 +1,215 @@
+import { useRozeniteDevToolsClient } from '@rozenite/plugin-bridge';
+import { useEffect, useMemo, useRef } from 'react';
+import type {
+  ControlsEventMap,
+  ControlsInvokeActionEvent,
+  ControlsUpdateRequestEvent,
+} from '../shared/messaging';
+import type { RozeniteControlsPluginOptions } from '../shared/types';
+import {
+  buildActionRegistry,
+  getActionRegistryKey,
+  serializeSections,
+  validateValue,
+} from '../shared/serialization';
+
+export const useRozeniteControlsPlugin = ({
+  sections,
+}: RozeniteControlsPluginOptions) => {
+  const client = useRozeniteDevToolsClient<ControlsEventMap>({
+    pluginId: '@rozenite/controls-plugin',
+  });
+
+  const snapshot = useMemo(() => serializeSections(sections), [sections]);
+  const actionRegistry = useMemo(() => buildActionRegistry(sections), [sections]);
+  const actionRegistryRef = useRef(actionRegistry);
+
+  useEffect(() => {
+    actionRegistryRef.current = actionRegistry;
+  }, [actionRegistry]);
+
+  useEffect(() => {
+    if (!client) {
+      return;
+    }
+
+    client.send('snapshot', {
+      type: 'snapshot',
+      sections: snapshot,
+    });
+  }, [client, snapshot]);
+
+  useEffect(() => {
+    if (!client) {
+      return;
+    }
+
+    const handleUpdateRequest = async ({
+      requestId,
+      sectionId,
+      itemId,
+      value,
+    }: ControlsUpdateRequestEvent) => {
+      const key = getActionRegistryKey(sectionId, itemId);
+      const entry = actionRegistryRef.current.get(key);
+
+      if (!entry || entry.type === 'button') {
+        client.send('update-result', {
+          type: 'update-result',
+          requestId,
+          sectionId,
+          itemId,
+          status: 'error',
+          message: 'Update target not found.',
+        });
+        return;
+      }
+
+      try {
+        if (entry.type === 'toggle') {
+          if (typeof value !== 'boolean') {
+            client.send('update-result', {
+              type: 'update-result',
+              requestId,
+              sectionId,
+              itemId,
+              status: 'error',
+              message: 'Invalid toggle value.',
+            });
+            return;
+          }
+
+          const result = validateValue(entry.validate, value);
+          if (!result.valid) {
+            client.send('update-result', {
+              type: 'update-result',
+              requestId,
+              sectionId,
+              itemId,
+              status: 'error',
+              message: result.message,
+            });
+            return;
+          }
+
+          await entry.onUpdate(value);
+          client.send('update-result', {
+            type: 'update-result',
+            requestId,
+            sectionId,
+            itemId,
+            status: 'ok',
+          });
+          return;
+        }
+
+        if (typeof value !== 'string') {
+          client.send('update-result', {
+            type: 'update-result',
+            requestId,
+            sectionId,
+            itemId,
+            status: 'error',
+            message: `Invalid ${entry.type} value.`,
+          });
+          return;
+        }
+
+        const result = validateValue(entry.validate, value);
+        if (!result.valid) {
+          client.send('update-result', {
+            type: 'update-result',
+            requestId,
+            sectionId,
+            itemId,
+            status: 'error',
+            message: result.message,
+          });
+          return;
+        }
+
+        await entry.onUpdate(value);
+        client.send('update-result', {
+          type: 'update-result',
+          requestId,
+          sectionId,
+          itemId,
+          status: 'ok',
+        });
+      } catch (error) {
+        console.warn(
+          `[Rozenite] Controls Plugin: Update failed for ${sectionId}/${itemId}.`,
+          error
+        );
+        client.send('update-result', {
+          type: 'update-result',
+          requestId,
+          sectionId,
+          itemId,
+          status: 'error',
+          message: 'Update failed on the device.',
+        });
+      }
+    };
+
+    const handleInvokeAction = async ({
+      sectionId,
+      itemId,
+      action,
+    }: ControlsInvokeActionEvent) => {
+      if (action !== 'press') {
+        console.warn(
+          `[Rozenite] Controls Plugin: Unsupported action "${action}" for ${sectionId}/${itemId}.`
+        );
+        return;
+      }
+
+      const key = getActionRegistryKey(sectionId, itemId);
+      const entry = actionRegistryRef.current.get(key);
+
+      if (!entry) {
+        console.warn(
+          `[Rozenite] Controls Plugin: Action target not found for ${sectionId}/${itemId}.`
+        );
+        return;
+      }
+
+      try {
+        if (entry.type !== 'button') {
+          console.warn(
+            `[Rozenite] Controls Plugin: Invalid press action payload for ${sectionId}/${itemId}.`
+          );
+          return;
+        }
+
+        await entry.onPress();
+      } catch (error) {
+        console.warn(
+          `[Rozenite] Controls Plugin: Action failed for ${sectionId}/${itemId}.`,
+          error
+        );
+      }
+    };
+
+    const subscriptions = [
+      client.onMessage('get-snapshot', () => {
+        client.send('snapshot', {
+          type: 'snapshot',
+          sections: snapshot,
+        });
+      }),
+      client.onMessage('update-request', (event: ControlsUpdateRequestEvent) => {
+        void handleUpdateRequest(event);
+      }),
+      client.onMessage('invoke-action', (event: ControlsInvokeActionEvent) => {
+        void handleInvokeAction(event);
+      }),
+    ];
+
+    return () => {
+      subscriptions.forEach((subscription) => subscription.remove());
+    };
+  }, [client, snapshot]);
+
+  return client;
+};

package/src/shared/messaging.ts

@@ -0,0 +1,45 @@
+import type { ControlsSectionSnapshot } from './types';
+
+export type ControlsSnapshotEvent = {
+  type: 'snapshot';
+  sections: ControlsSectionSnapshot[];
+};
+
+export type ControlsGetSnapshotEvent = {
+  type: 'get-snapshot';
+};
+
+export type ControlsUpdateRequestEvent = {
+  type: 'update-request';
+  requestId: string;
+  sectionId: string;
+  itemId: string;
+  value: boolean | string;
+};
+
+export type ControlsUpdateResultEvent = {
+  type: 'update-result';
+  requestId: string;
+  sectionId: string;
+  itemId: string;
+  status: 'ok' | 'error';
+  message?: string;
+};
+
+export type ControlsInvokeActionEvent = {
+  type: 'invoke-action';
+  sectionId: string;
+  itemId: string;
+  action: 'press';
+};
+
+export type ControlsEvent =
+  | ControlsSnapshotEvent
+  | ControlsGetSnapshotEvent
+  | ControlsUpdateRequestEvent
+  | ControlsUpdateResultEvent
+  | ControlsInvokeActionEvent;
+
+export type ControlsEventMap = {
+  [K in ControlsEvent['type']]: Extract<ControlsEvent, { type: K }>;
+};

package/src/shared/serialization.ts

@@ -0,0 +1,153 @@
+import type {
+  ControlsButtonItem,
+  ControlsInputItem,
+  ControlsItem,
+  ControlsItemSnapshot,
+  ControlsMutableItemBase,
+  ControlsSelectItem,
+  ControlsSection,
+  ControlsSectionSnapshot,
+  ControlsToggleItem,
+  ControlsValidationResult,
+} from './types';
+
+export type ActionRegistryEntry =
+  | {
+      type: 'toggle';
+      validate?: ControlsToggleItem['validate'];
+      onUpdate: ControlsToggleItem['onUpdate'];
+    }
+  | {
+      type: 'button';
+      onPress: ControlsButtonItem['onPress'];
+    }
+  | {
+      type: 'select';
+      validate?: ControlsSelectItem['validate'];
+      onUpdate: ControlsSelectItem['onUpdate'];
+    }
+  | {
+      type: 'input';
+      validate?: ControlsInputItem['validate'];
+      onUpdate: ControlsInputItem['onUpdate'];
+    };
+
+const validateValue = <TValue>(
+  validate: ControlsMutableItemBase<TValue>['validate'],
+  value: TValue
+): ControlsValidationResult => {
+  if (!validate) {
+    return { valid: true };
+  }
+
+  return validate(value);
+};
+
+const toSnapshotItem = (item: ControlsItem): ControlsItemSnapshot => {
+  if (item.type === 'text') {
+    return item;
+  }
+
+  if (item.type === 'toggle') {
+    return {
+      id: item.id,
+      type: item.type,
+      title: item.title,
+      value: item.value,
+      description: item.description,
+      disabled: item.disabled,
+    };
+  }
+
+  if (item.type === 'button') {
+    return {
+      id: item.id,
+      type: item.type,
+      title: item.title,
+      actionLabel: item.actionLabel,
+      description: item.description,
+      disabled: item.disabled,
+    };
+  }
+
+  if (item.type === 'select') {
+    return {
+      id: item.id,
+      type: item.type,
+      title: item.title,
+      value: item.value,
+      options: item.options,
+      description: item.description,
+      disabled: item.disabled,
+    };
+  }
+
+  return {
+    id: item.id,
+    type: item.type,
+    title: item.title,
+    value: item.value,
+    placeholder: item.placeholder,
+    applyLabel: item.applyLabel,
+    description: item.description,
+    disabled: item.disabled,
+  };
+};
+
+export const serializeSections = (
+  sections: ControlsSection[]
+): ControlsSectionSnapshot[] =>
+  sections.map((section) => ({
+    id: section.id,
+    title: section.title,
+    description: section.description,
+    items: section.items.map(toSnapshotItem),
+  }));
+
+export const buildActionRegistry = (sections: ControlsSection[]) => {
+  const registry = new Map<string, ActionRegistryEntry>();
+
+  sections.forEach((section) => {
+    section.items.forEach((item) => {
+      const key = `${section.id}:${item.id}`;
+
+      if (item.type === 'toggle') {
+        registry.set(key, {
+          type: 'toggle',
+          validate: item.validate,
+          onUpdate: item.onUpdate,
+        });
+      }
+
+      if (item.type === 'button') {
+        registry.set(key, {
+          type: 'button',
+          onPress: item.onPress,
+        });
+      }
+
+      if (item.type === 'select') {
+        registry.set(key, {
+          type: 'select',
+          validate: item.validate,
+          onUpdate: item.onUpdate,
+        });
+      }
+
+      if (item.type === 'input') {
+        registry.set(key, {
+          type: 'input',
+          validate: item.validate,
+          onUpdate: item.onUpdate,
+        });
+      }
+    });
+  });
+
+  return registry;
+};
+
+export const getActionRegistryKey = (sectionId: string, itemId: string) =>
+  `${sectionId}:${itemId}`;
+
+export { validateValue };