gufi-cli 0.1.49 → 0.1.51

package/docs/dev-guide/3-01-custom-views.md

@@ -0,0 +1,555 @@
+---
+id: custom-views
+title: "Custom Views Development"
+description: "Build custom views for the Marketplace"
+icon: Store
+category: dev
+part: 3
+---
+
+# Custom Views Development
+
+Build custom views for the Marketplace
+
+## Overview
+
+Custom views are React components that extend Gufi's functionality. They can:
+
+- Display data in unique ways (dashboards, charts, maps)
+- Provide specialized workflows
+- Integrate with external services
+- Offer industry-specific features
+
+## View Structure
+
+### Standard Directory Layout
+
+```
+my_view/
+├── index.tsx           # Main export + featureConfig
+├── types.ts            # TypeScript types
+├── core/
+│   ├── dataSources.ts  # Data sources (REQUIRED)
+│   ├── automations.ts  # Automations declaration (if using automations)
+│   └── index.tsx       # featureConfig
+├── metadata/
+│   ├── seedData.ts     # Demo data for preview
+│   ├── inputs.ts       # User-configurable fields
+│   └── migrations.ts   # SQL migrations
+├── components/         # UI components
+│   ├── Header.tsx
+│   ├── Dashboard.tsx
+│   └── ...
+└── plugin/             # Optional: ViewPlugin for native
+    └── MyViewPlugin.tsx
+```
+
+### Main Entry (index.tsx)
+
+```typescript
+import React from 'react';
+import type { FullGufiContext } from '@/sdk';
+import { featureConfig } from './core/dataProvider';
+import { MyDashboard } from './components/Dashboard';
+
+interface Props {
+  id: string;
+  gufi: FullGufiContext;
+}
+
+export default function MyView({ id, gufi }: Props) {
+  return <MyDashboard id={id} gufi={gufi} />;
+}
+
+export { featureConfig };
+```
+
+## Feature Configuration
+
+### Basic Config
+
+```typescript
+// core/dataProvider.ts
+import type { FeatureConfig } from '@/sdk';
+
+export const featureConfig: FeatureConfig = {
+  id: 'my-analytics-view',
+  name: 'My Analytics',
+  description: 'Analytics dashboard for sales data',
+  version: '1.0.0',
+  author: 'Your Name',
+  icon: 'BarChart3',
+
+  // Data requirements
+  dataSources: [
+    {
+      key: 'ordersTable',
+      name: 'Orders',
+      description: 'Table containing orders',
+      required: true
+    },
+    {
+      key: 'productsTable',
+      name: 'Products',
+      description: 'Products catalog',
+      required: false
+    }
+  ],
+
+  // User inputs (shown in settings)
+  inputs: [
+    {
+      key: 'defaultPeriod',
+      type: 'select',
+      label: 'Default Period',
+      options: ['week', 'month', 'quarter', 'year'],
+      default: 'month'
+    }
+  ]
+};
+```
+
+### Data Sources
+
+Define what tables your view needs:
+
+```typescript
+dataSources: [
+  {
+    key: 'ordersTable',      // Reference key
+    name: 'Orders Table',     // Display name
+    description: 'Sales orders', // Help text
+    required: true,           // Must be mapped
+    columns: [                // Optional: required columns
+      { name: 'total', type: 'currency' },
+      { name: 'status', type: 'select' }
+    ]
+  }
+]
+```
+
+### User Inputs
+
+Configuration options shown to users:
+
+```typescript
+inputs: [
+  {
+    key: 'theme',
+    type: 'select',
+    label: 'Color Theme',
+    options: ['purple', 'blue', 'green'],
+    default: 'purple'
+  },
+  {
+    key: 'showTrends',
+    type: 'checkbox',
+    label: 'Show Trend Lines',
+    default: true
+  },
+  {
+    key: 'apiEndpoint',
+    type: 'text',
+    label: 'External API URL',
+    placeholder: 'https://api.example.com'
+  }
+]
+```
+
+## The gufi Context
+
+### What's Available
+
+Every view receives the `gufi` context:
+
+```typescript
+interface FullGufiContext {
+  // Data Provider
+  dataProvider: {
+    getList: (params) => Promise<{ data, total }>;
+    getOne: (params) => Promise<{ data }>;
+    create: (params) => Promise<{ data }>;
+    update: (params) => Promise<{ data }>;
+    delete: (params) => Promise<void>;
+  };
+
+  // Automations (con acceso a api.stripe.*, api.nayax.*, etc.)
+  automation: (name: string, input?: object) => Promise<any>;
+
+  // WebSocket
+  websocket: {
+    subscribeToTable: (tableId, callback) => () => void;
+    broadcastToView: (event, data) => void;
+    isConnected: () => boolean;
+  };
+
+  // Context Info
+  context: {
+    schema: CompanySchema;
+    user: { id, name, email };
+    activeCompany: { id, name };
+    lang: 'es' | 'en';
+    viewSpec: Record<string, string>;  // Table mappings
+    seedData: SeedDataConfig;
+    isPreview: boolean;
+    isDev: boolean;
+  };
+
+  // Utilities
+  utils: {
+    // Translations
+    tUI: (key) => string;
+    getLang: () => 'es' | 'en';
+
+    // Notifications
+    toastSuccess: (msg) => void;
+    toastError: (msg) => void;
+    toastInfo: (msg) => void;
+
+    // Formatting
+    formatNumber: (n) => string;
+    formatCurrency: (n) => string;
+    formatDate: (d) => string;
+    formatDateTime: (d) => string;
+
+    // Data helpers
+    groupBy: (arr, key) => Record;
+    sumBy: (arr, key) => number;
+    sortBy: (arr, key, order) => array;
+
+    // Other
+    resolveTableName: (schema, ref) => string;
+    navigate: (path) => void;
+    cn: (...classes) => string;
+  };
+
+  // Device Info
+  device: {
+    isHandheld: boolean;
+    isDesktop: boolean;
+    isMobile: boolean;
+  };
+}
+```
+
+### Using the Context
+
+```typescript
+export default function MyView({ id, gufi }: Props) {
+  const { dataProvider, utils, context, device } = gufi;
+  const { tUI, toastSuccess, formatCurrency } = utils;
+
+  // Get table ID from viewSpec mapping
+  const ordersTable = context.viewSpec?.ordersTable;
+
+  // Load data
+  const { data: orders } = useViewData({
+    gufi,
+    tableKey: 'ordersTable'
+  });
+
+  // Responsive layout
+  if (device.isHandheld) {
+    return <MobileLayout orders={orders} />;
+  }
+
+  return <DesktopLayout orders={orders} />;
+}
+```
+
+## Seed Data (Preview Mode)
+
+### Defining Demo Data
+
+```typescript
+// metadata/seedData.ts
+import type { SeedDataConfig } from '@/sdk';
+
+export const seedData: SeedDataConfig = {
+  ordersTable: [
+    {
+      id: '@ref:ordersTable.0',
+      customer_name: 'Acme Corp',
+      total: { currency: 'EUR', amount: 1500 },
+      status: 'completed',
+      created_at: '@today'
+    },
+    {
+      id: '@ref:ordersTable.1',
+      customer_name: 'Beta Inc',
+      total: { currency: 'EUR', amount: 800 },
+      status: 'pending',
+      created_at: '@today'
+    }
+  ],
+  productsTable: [
+    {
+      id: '@ref:productsTable.0',
+      name: 'Widget Pro',
+      price: { currency: 'EUR', amount: 99.99 },
+      stock: 150
+    }
+  ]
+};
+```
+
+### Special Tokens
+
+| Token | Value |
+|---|---|
+| `@ref:tableName.index` | Auto-generated ID |
+| `@today` | Current date |
+| `@currentUser` | Current user ID |
+| `@now` | Current timestamp |
+
+### Using Seed Data
+
+The SDK automatically uses seed data in preview mode:
+
+```typescript
+const { data, loading, usingSeedData } = useViewData({
+  gufi,
+  tableKey: 'ordersTable'
+});
+
+// usingSeedData is true when in preview
+if (usingSeedData) {
+  console.log('Showing demo data');
+}
+```
+
+## Automations
+
+### Declaring Automations
+
+If your view needs to call automations (for Stripe payments, email sending, etc.), you must declare them in `core/automations.ts`:
+
+```typescript
+// core/automations.ts
+export const automations = [
+  { name: 'stripe_checkout', description: 'Create Stripe payment session' },
+  { name: 'send_confirmation', description: 'Send confirmation email' },
+] as const;
+```
+
+**Important:**
+- Automations must be declared BEFORE they can be called from the view
+- On `gufi view:push`, declared automations are registered in `__automation_meta__` with `trigger_event='CUSTOM'`
+- Only declared automations can be executed via `gufi.automation()`
+
+### Calling Automations
+
+```typescript
+const handlePayment = async () => {
+  try {
+    // Only works if 'stripe_checkout' is declared in core/automations.ts
+    const result = await gufi.automation('stripe_checkout', {
+      amount: 1999,
+      customer_email: 'user@example.com',
+    });
+
+    if (result.url) {
+      window.location.href = result.url;
+    }
+  } catch (err) {
+    gufi.utils.toastError('Payment failed');
+  }
+};
+```
+
+### Workflow
+
+1. **Create script:** `gufi automation:create stripe_checkout script.js -c 116`
+2. **Declare in view:** Add to `core/automations.ts`
+3. **Push view:** `gufi view:push` → Registers in `__automation_meta__`
+4. **Use in view:** `gufi.automation('stripe_checkout', input)`
+
+## Migrations
+
+### Version Updates
+
+When your view schema changes:
+
+```typescript
+// metadata/migrations.ts
+export const migrations = [
+  {
+    version: '1.1.0',
+    description: 'Add status column',
+    up: `
+      ALTER TABLE {tableName}
+      ADD COLUMN IF NOT EXISTS status VARCHAR(50) DEFAULT 'active';
+    `,
+    down: `
+      ALTER TABLE {tableName}
+      DROP COLUMN IF EXISTS status;
+    `
+  },
+  {
+    version: '1.2.0',
+    description: 'Add priority field',
+    up: `
+      ALTER TABLE {tableName}
+      ADD COLUMN IF NOT EXISTS priority INTEGER DEFAULT 0;
+    `,
+    down: `
+      ALTER TABLE {tableName}
+      DROP COLUMN IF EXISTS priority;
+    `
+  }
+];
+```
+
+### Placeholders
+
+| Placeholder | Value |
+|---|---|
+| `{tableName}` | Physical table name |
+| `{entityId}` | Entity ID |
+| `{companyId}` | Company ID |
+| `{schemaName}` | Company schema |
+
+## Best Practices
+
+### Data Loading
+
+```typescript
+// Good: Use SDK hooks
+const { data, loading, error, refetch } = useViewData({
+  gufi,
+  tableKey: 'ordersTable',
+  filters: { status: 'active' }
+});
+
+// Bad: Direct store access
+import { useCompanySchemaStore } from '@/stores'; // Don't do this
+```
+
+### Error Handling
+
+```typescript
+if (error) {
+  return (
+    <div className="p-4 text-red-600">
+      <AlertCircle className="w-5 h-5" />
+      <span>{utils.tUI('common.error')}: {error.message}</span>
+    </div>
+  );
+}
+```
+
+### Loading States
+
+```typescript
+if (loading) {
+  return (
+    <div className="animate-pulse">
+      <div className="h-8 bg-zinc-200 rounded" />
+      <div className="h-32 bg-zinc-100 rounded mt-4" />
+    </div>
+  );
+}
+```
+
+### Responsive Design
+
+```typescript
+const { device } = gufi;
+
+return (
+  <div className={device.isHandheld ? 'p-2' : 'p-6'}>
+    {device.isDesktop && <Sidebar />}
+    <MainContent />
+  </div>
+);
+```
+
+## Development Workflow
+
+### Local Development
+
+```bash
+# 1. Pull view for editing
+gufi pull 55
+cd view_55/
+
+# 2. Start watch mode
+gufi watch
+
+# 3. Make changes - auto syncs
+
+# 4. View logs
+gufi logs
+
+# 5. Test in LivePreview
+# Open view in Gufi web interface
+```
+
+### Publishing
+
+```bash
+# 1. Add to package
+gufi package:add-view 14 55
+
+# 2. Check changes
+gufi package:check 14
+
+# 3. Sync version
+gufi package:sync 14
+
+# 4. Publish
+gufi package:publish 14
+```
+
+## Common Patterns
+
+### Dashboard with KPIs
+
+```typescript
+import { ViewLayout, ViewKPIGrid, ViewKPI, ViewCard } from '@/shared/views';
+
+export function Dashboard({ gufi }: Props) {
+  const { data } = useViewData({ gufi, tableKey: 'ordersTable' });
+
+  const totalRevenue = gufi.utils.sumBy(data, 'total.amount');
+  const orderCount = data.length;
+
+  return (
+    <ViewLayout>
+      <ViewKPIGrid>
+        <ViewKPI
+          title="Total Revenue"
+          value={gufi.utils.formatCurrency(totalRevenue)}
+          trend="+12%"
+          trendUp
+        />
+        <ViewKPI
+          title="Orders"
+          value={orderCount}
+        />
+      </ViewKPIGrid>
+
+      <ViewCard title="Recent Orders">
+        <OrdersTable orders={data} />
+      </ViewCard>
+    </ViewLayout>
+  );
+}
+```
+
+### Real-Time Updates
+
+```typescript
+useEffect(() => {
+  const tableId = context.viewSpec?.ordersTable;
+  if (!tableId) return;
+
+  const unsubscribe = gufi.websocket.subscribeToTable(tableId, (event) => {
+    if (event.type === 'INSERT' || event.type === 'UPDATE') {
+      refetch();
+    }
+  });
+
+  return () => unsubscribe();
+}, [context.viewSpec?.ordersTable]);
+```