@majkapp/plugin-kit 3.2.1 → 3.3.1

package/docs/HOOKS.md

@@ -0,0 +1,532 @@
+# Generated Hooks
+
+The plugin-kit auto-generates React hooks from your functions. Run `npm run build` to generate hooks in `ui/src/generated/`.
+
+## Query Hooks (Auto-Fetch)
+
+Query hooks automatically fetch data when the component mounts.
+
+```typescript
+// From this function definition:
+.function('health', {
+  description: 'Check plugin health status',
+  input: {
+    type: 'object',
+    properties: {},
+    additionalProperties: false
+  },
+  output: {
+    type: 'object',
+    properties: {
+      status: { type: 'string' },
+      timestamp: { type: 'string' }
+    }
+  },
+  handler: async (input, ctx) => {
+    return {
+      status: 'ok',
+      timestamp: new Date().toISOString()
+    };
+  }
+})
+
+// Generates this hook:
+export function useHealth(
+  input?: HealthInput,
+  options?: { enabled?: boolean; refetchInterval?: number }
+): UseQueryResult<HealthOutput>
+```
+
+### Basic Usage
+
+```typescript
+// ui/src/components/DashboardPage.tsx
+import { useHealth } from '../generated/hooks';
+
+export function DashboardPage() {
+  // Auto-fetches on mount
+  const { data, error, loading, refetch } = useHealth();
+
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <div>
+      <div data-majk-id="healthStatus">{data.status}</div>
+      <button onClick={refetch} data-majk-id="refreshButton">
+        Refresh
+      </button>
+    </div>
+  );
+}
+```
+
+### With Input Parameters
+
+```typescript
+// Function with parameters
+.function('getAnalytics', {
+  description: 'Get analytics for time period',
+  input: {
+    type: 'object',
+    properties: {
+      period: { type: 'string', enum: ['24h', '7d', '30d'] }
+    },
+    required: ['period']
+  },
+  output: { /* ... */ }
+})
+
+// Generated hook
+export function useGetAnalytics(
+  input: GetAnalyticsInput,
+  options?: { enabled?: boolean; refetchInterval?: number }
+): UseQueryResult<GetAnalyticsOutput>
+```
+
+Usage:
+
+```typescript
+import { useGetAnalytics } from '../generated/hooks';
+
+export function AnalyticsPage() {
+  // Pass input as first parameter
+  const { data, loading, error } = useGetAnalytics({ period: '7d' });
+
+  return (
+    <div data-majk-id="analyticsContainer">
+      {loading && <div data-majk-state="loading">Loading...</div>}
+      {!loading && data && (
+        <div data-majk-state="populated">
+          <div data-majk-id="activeUsersCount">{data.metrics.activeUsers}</div>
+          <div data-majk-id="totalSessions">{data.metrics.totalSessions}</div>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### Auto-Refresh
+
+```typescript
+export function LiveDashboard() {
+  // Refetch every 30 seconds
+  const { data } = useHealth({}, {
+    refetchInterval: 30000  // milliseconds
+  });
+
+  return <div data-majk-id="liveStatus">{data?.status}</div>;
+}
+```
+
+### Conditional Fetching
+
+```typescript
+export function ConditionalData() {
+  const [fetchEnabled, setFetchEnabled] = useState(false);
+
+  // Only fetch when enabled is true
+  const { data, loading } = useGetAnalytics(
+    { period: '7d' },
+    { enabled: fetchEnabled }
+  );
+
+  return (
+    <div>
+      <button
+        onClick={() => setFetchEnabled(true)}
+        data-majk-id="loadDataButton"
+      >
+        Load Data
+      </button>
+      {fetchEnabled && loading && <div>Loading...</div>}
+      {data && <div>{JSON.stringify(data)}</div>}
+    </div>
+  );
+}
+```
+
+## Mutation Hooks (Manual Trigger)
+
+Mutation hooks don't auto-fetch. Call `.mutate(input)` manually.
+
+```typescript
+// From this function (mutation - modifies state):
+.function('clearEvents', {
+  description: 'Clear all logged events',
+  input: {
+    type: 'object',
+    properties: {},
+    additionalProperties: false
+  },
+  output: {
+    type: 'object',
+    properties: {
+      success: { type: 'boolean' },
+      clearedCount: { type: 'number' }
+    }
+  },
+  handler: async (input, ctx) => {
+    const events = await ctx.storage.get('events') || [];
+    await ctx.storage.set('events', []);
+    return { success: true, clearedCount: events.length };
+  }
+})
+
+// Generates this hook:
+export function useClearEvents(): UseMutationResult<ClearEventsInput, ClearEventsOutput>
+```
+
+### Basic Usage
+
+```typescript
+import { useClearEvents } from '../generated/hooks';
+
+export function EventsPage() {
+  const { mutate: clearEvents, data, loading, error } = useClearEvents();
+
+  const handleClear = async () => {
+    try {
+      const result = await clearEvents({});  // Call mutate with input
+      console.log(`Cleared ${result.clearedCount} events`);
+    } catch (err) {
+      console.error('Failed to clear events:', err);
+    }
+  };
+
+  return (
+    <button
+      onClick={handleClear}
+      disabled={loading}
+      data-majk-id="clearEventsButton"
+      data-majk-state={loading ? 'clearing' : 'idle'}
+    >
+      {loading ? 'Clearing...' : 'Clear Events'}
+    </button>
+  );
+}
+```
+
+### With Input Parameters
+
+```typescript
+// Function with input
+.function('updateSettings', {
+  description: 'Update plugin settings',
+  input: {
+    type: 'object',
+    properties: {
+      theme: { type: 'string', enum: ['light', 'dark'] },
+      notifications: { type: 'boolean' }
+    },
+    required: ['theme']
+  },
+  output: { /* ... */ }
+})
+```
+
+Usage:
+
+```typescript
+import { useUpdateSettings } from '../generated/hooks';
+
+export function SettingsPage() {
+  const { mutate: updateSettings, loading, error } = useUpdateSettings();
+
+  const handleSave = async () => {
+    try {
+      await updateSettings({
+        theme: 'dark',
+        notifications: true
+      });
+      alert('Settings saved!');
+    } catch (err) {
+      alert(`Error: ${err.message}`);
+    }
+  };
+
+  return (
+    <button
+      onClick={handleSave}
+      disabled={loading}
+      data-majk-id="saveSettingsButton"
+    >
+      Save
+    </button>
+  );
+}
+```
+
+### Tracking Mutation State
+
+```typescript
+export function DeleteButton({ itemId }: { itemId: string }) {
+  const { mutate: deleteItem, loading, data, error } = useDeleteItem();
+
+  return (
+    <div>
+      <button
+        onClick={() => deleteItem({ id: itemId })}
+        disabled={loading}
+        data-majk-id="deleteButton"
+        data-majk-state={loading ? 'deleting' : error ? 'error' : data ? 'success' : 'idle'}
+      >
+        {loading ? 'Deleting...' : 'Delete'}
+      </button>
+
+      {error && (
+        <div data-majk-id="errorMessage" data-majk-state="error">
+          Error: {error.message}
+        </div>
+      )}
+
+      {data?.success && (
+        <div data-majk-id="successMessage" data-majk-state="success">
+          Deleted successfully!
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+## uiLog Hook Pattern
+
+**Best practice:** Use `useUiLog` hook for logging throughout your UI.
+
+```typescript
+// Define uiLog function in plugin
+.function('uiLog', {
+  description: 'Log messages from UI for debugging',
+  input: {
+    type: 'object',
+    properties: {
+      level: { type: 'string', enum: ['debug', 'info', 'warn', 'error'] },
+      component: { type: 'string' },
+      message: { type: 'string' },
+      data: { type: 'object' }
+    },
+    required: ['level', 'component', 'message']
+  },
+  output: {
+    type: 'object',
+    properties: { success: { type: 'boolean' } }
+  },
+  handler: async (input, ctx) => {
+    ctx.logger[input.level](`[UI:${input.component}] ${input.message}`, input.data);
+    return { success: true };
+  }
+})
+```
+
+Use in every component:
+
+```typescript
+import { useUiLog } from '../generated/hooks';
+import { useEffect } from 'react';
+
+export function DashboardPage() {
+  const { mutate: uiLog } = useUiLog();
+
+  // Log lifecycle events
+  useEffect(() => {
+    uiLog({
+      level: 'info',
+      component: 'DashboardPage',
+      message: 'Component mounted'
+    });
+
+    return () => {
+      uiLog({
+        level: 'info',
+        component: 'DashboardPage',
+        message: 'Component unmounting'
+      });
+    };
+  }, [uiLog]);
+
+  // Log user actions
+  const handleButtonClick = () => {
+    uiLog({
+      level: 'info',
+      component: 'DashboardPage',
+      message: 'Button clicked',
+      data: { button: 'refresh', timestamp: Date.now() }
+    });
+    // ... handle click
+  };
+
+  // Log errors
+  const handleOperation = async () => {
+    try {
+      await riskyOperation();
+    } catch (error) {
+      uiLog({
+        level: 'error',
+        component: 'DashboardPage',
+        message: 'Operation failed',
+        data: {
+          error: error.message,
+          stack: error.stack
+        }
+      });
+    }
+  };
+
+  return <div>...</div>;
+}
+```
+
+## Hook Return Types
+
+### UseQueryResult
+
+```typescript
+interface UseQueryResult<T> {
+  data: T | undefined;          // Function output (undefined until loaded)
+  error: Error | undefined;     // Error if fetch failed
+  loading: boolean;             // True while fetching
+  refetch: () => void;          // Manually trigger re-fetch
+}
+```
+
+### UseMutationResult
+
+```typescript
+interface UseMutationResult<TInput, TOutput> {
+  mutate: (input: TInput) => Promise<TOutput>;  // Call to execute function
+  data: TOutput | undefined;                     // Last successful result
+  error: Error | undefined;                      // Last error
+  loading: boolean;                              // True while executing
+}
+```
+
+## Common Patterns
+
+### Loading States
+
+```typescript
+export function DataDisplay() {
+  const { data, loading, error } = useGetData();
+
+  return (
+    <div data-majk-id="dataContainer" data-majk-state={
+      loading ? 'loading' :
+      error ? 'error' :
+      data ? 'populated' : 'empty'
+    }>
+      {loading && <Spinner data-majk-id="spinner" />}
+      {error && <ErrorMessage data-majk-id="error" error={error} />}
+      {data && <DataView data={data} />}
+    </div>
+  );
+}
+```
+
+### Dependent Queries
+
+```typescript
+export function UserProfile({ userId }: { userId: string }) {
+  // First query
+  const { data: user, loading: userLoading } = useGetUser({ id: userId });
+
+  // Second query depends on first
+  const { data: projects, loading: projectsLoading } = useGetUserProjects(
+    { userId },
+    { enabled: !!user }  // Only fetch when user exists
+  );
+
+  if (userLoading) return <div>Loading user...</div>;
+  if (!user) return <div>User not found</div>;
+
+  return (
+    <div>
+      <div data-majk-id="userName">{user.name}</div>
+      {projectsLoading ? (
+        <div data-majk-state="loading">Loading projects...</div>
+      ) : (
+        <div data-majk-state="populated">
+          {projects?.map(p => <div key={p.id}>{p.name}</div>)}
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### Optimistic Updates
+
+```typescript
+export function TodoList() {
+  const { data: todos, refetch } = useGetTodos();
+  const { mutate: completeTodo } = useCompleteTodo();
+
+  const handleComplete = async (todoId: string) => {
+    // Optimistically update UI
+    const optimisticTodos = todos?.map(t =>
+      t.id === todoId ? { ...t, completed: true } : t
+    );
+
+    // Update backend
+    try {
+      await completeTodo({ id: todoId });
+      refetch();  // Refetch to get source of truth
+    } catch (error) {
+      // Revert on error (or refetch)
+      refetch();
+    }
+  };
+
+  return <div>...</div>;
+}
+```
+
+## Testing with Generated Hooks
+
+Hooks are tested through UI tests:
+
+```typescript
+// tests/plugin/ui/unit/dashboard.test.js
+import { test, bot, mock } from '@majkapp/plugin-test';
+
+test('dashboard uses hooks correctly', async () => {
+  const context = mock()
+    .withMockHandler('health', async () => ({
+      status: 'ok',
+      timestamp: new Date().toISOString()
+    }))
+    .build();
+
+  const b = await bot(context);
+  await b.goto('/plugin-screens/my-plugin/dashboard');
+
+  // Wait for useHealth() to fetch and render
+  await b.waitForSelector('[data-majk-id="healthStatus"][data-majk-state="populated"]');
+
+  const text = await b.getText('[data-majk-id="healthStatus"]');
+  assert.ok(text.includes('ok'));
+
+  await b.close();
+});
+```
+
+## Hook Generation
+
+Hooks are generated by running your build:
+
+```bash
+npm run build
+```
+
+Generated files (DO NOT EDIT manually):
+- `ui/src/generated/hooks.ts` - React hooks
+- `ui/src/generated/client.ts` - RPC client
+- `ui/src/generated/types.ts` - TypeScript types
+- `ui/src/generated/index.ts` - Barrel export
+
+## Next Steps
+
+Run `npx @majkapp/plugin-kit --context` - ctx API for accessing MAJK
+Run `npx @majkapp/plugin-kit --testing` - Test your hooks
+Run `npx @majkapp/plugin-kit --config` - Build configuration