infaira-canvas 0.1.9

package/templates/ICan-Widget-Development-Guide.md

@@ -0,0 +1,500 @@
+# ICan Widget Development Guide
+
+> Reference for building **functional** ICan widgets — data fetching, configuration, localisation, roles, and multi-instance patterns.
+> For **styling** see `ICan-Widget-Styling-Patterns.md`. For the `--ican-*` CSS variable reference see `ICan-Widget-Theming-Guide.md`.
+
+---
+
+## 1. `icanContext` — what it is and the guard you must keep
+
+`icanContext` is your widget's connection to the portal. The portal injects it as a prop at runtime:
+
+```tsx
+const MyWidget: React.FC<IWidgetProps> = ({ icanContext }) => { ... }
+```
+
+**It is `undefined` in the dev harness until the harness is configured.** The scaffold always generates a guard for this reason:
+
+```tsx
+React.useEffect(() => {
+  if (!icanContext) {
+    setLoading(false);
+    return;           // ← this line is not dead code — remove it and the harness crashes
+  }
+  // safe to call icanContext.executeAction etc. here
+}, [icanContext]);
+```
+
+Never remove this guard. Calling `icanContext.executeAction(...)` without it will throw `Cannot read properties of undefined` on the first render in the dev harness.
+
+In the portal, `icanContext` is always defined — the widget is never mounted until the context is ready.
+
+**What's available on `icanContext`:**
+
+| Property / Method | Type | What it does |
+|---|---|---|
+| `environment` | `'dev' \| 'prod'` | `'dev'` in local harness, `'prod'` in portal |
+| `userKey` | `string` | Authenticated user's key |
+| `language` | `string` | Active language code, e.g. `'en'` |
+| `themeName` | `string \| undefined` | e.g. `'Dark'`, `'Glass Light'` |
+| `themeType` | `'Dark' \| 'Light' \| 'Glass-Dark' \| 'Glass-Light' \| undefined` | Structured theme type for chart colours |
+| `executeAction` | `(model, action, params?, options?) => Promise<unknown>` | Call an Orch model |
+| `fireEvent` | `(eventId) => Promise<void>` | Trigger a portal event |
+| `hasAppRole` | `(app, role) => boolean` | Check if the user has a role |
+| `$L` | `(code, params?) => string` | Translate a localisation key |
+
+---
+
+## 2. `environment` — returning mock data in dev
+
+Use `icanContext.environment` to skip real API calls during local development:
+
+```tsx
+React.useEffect(() => {
+  if (!icanContext) { setLoading(false); return; }
+
+  // Return mock data in the dev harness — no live backend needed
+  if (icanContext.environment === 'dev') {
+    setData([{ id: '1', name: 'Mock Item', value: 42 }]);
+    setLoading(false);
+    return;
+  }
+
+  // Only runs in the portal
+  icanContext
+    .executeAction('InventoryModel', 'GetAll', { limit: 20 }, { json: true })
+    .then((res) => { setData(res as Item[]); })
+    .catch((err) => { setError(String(err)); })
+    .finally(() => setLoading(false));
+}, [icanContext]);
+```
+
+The dev harness always sets `environment: 'dev'`. The portal always sets `environment: 'prod'`. The mock-data branch is never hit in production.
+
+---
+
+## 3. Widget settings panel — `IWidgetPropConfig`
+
+Widgets can expose a settings form in the portal. Users open it by clicking the ⚙ button on a widget cell in edit mode. You define the fields in `registerWidget`:
+
+```typescript
+registerWidget({
+  id: 'my-widget',
+  widget: MyWidget,
+  configs: {
+    layout: { w: 10, h: 8, minW: 4, minH: 4 },
+    props: [
+      {
+        name: 'title',
+        label: 'Widget Title',
+        type: 'text',
+        value: 'My Widget',
+        validate: { required: true, maxLength: 60 },
+      },
+      {
+        name: 'maxRows',
+        label: 'Max Rows',
+        type: 'number',
+        value: 10,
+        validate: { minVal: 1, maxVal: 100 },
+      },
+      {
+        name: 'refreshMode',
+        label: 'Refresh Mode',
+        type: 'select',
+        value: 'manual',
+        options: [
+          { label: 'Manual', value: 'manual' },
+          { label: 'Auto (30 s)', value: 'auto' },
+        ],
+      },
+      {
+        name: 'showFooter',
+        label: 'Show Footer',
+        type: 'toggle',
+        value: true,
+      },
+    ],
+  },
+});
+```
+
+Each saved value flows to your component as a **prop** — add it to `IWidgetProps` and the component signature:
+
+```tsx
+interface IWidgetProps {
+  icanContext?: IContextProvider;
+  title?: string;         // ← from configs.props
+  maxRows?: number;
+  refreshMode?: string;
+  showFooter?: boolean;
+  [key: string]: unknown;
+}
+
+const MyWidget: React.FC<IWidgetProps> = ({
+  icanContext,
+  title = 'My Widget',  // ← default matches configs.props[n].value
+  maxRows = 10,
+  refreshMode = 'manual',
+  showFooter = true,
+}) => { ... };
+```
+
+### `IWidgetPropConfig` field reference
+
+| Field | Required | Description |
+|---|---|---|
+| `name` | ✅ | Property name — becomes the prop key on your component |
+| `label` | ✅ | Human-readable label shown in the settings form |
+| `type` | ✅ | `'text'` `'string'` `'password'` `'number'` `'email'` `'checkbox'` `'toggle'` `'select'` `'date'` `'time'` `'json'` |
+| `value` | — | Default value used before the user configures the widget |
+| `placeholder` | — | Placeholder text for text-like inputs |
+| `options` | — | Required for `type: 'select'` — array of `{ label: string; value: string }` |
+| `validate.required` | — | Mark the field as required in the form |
+| `validate.minLength` / `maxLength` | — | String length bounds |
+| `validate.minVal` / `maxVal` | — | Numeric bounds |
+
+---
+
+## 4. `hasAppRole` — role-based UI
+
+Show or hide UI elements based on the user's role in the portal:
+
+```tsx
+const MyWidget: React.FC<IWidgetProps> = ({ icanContext }) => {
+  const canEdit  = icanContext?.hasAppRole('MyApp', 'editor') ?? false;
+  const isAdmin  = icanContext?.hasAppRole('MyApp', 'admin')  ?? false;
+
+  return (
+    <div className="my-widget">
+      <DataTable rows={rows} />
+      {canEdit  && <Button label="Edit"       onClick={handleEdit}   />}
+      {isAdmin  && <Button label="Delete All" onClick={handleDelete} variant="danger" />}
+    </div>
+  );
+};
+```
+
+The first argument is the **app name**, the second is the **role name** — both must match what is configured in the portal's role management screen. `hasAppRole` returns `false` (not an error) if the context is unavailable or the role doesn't exist, so the `?? false` fallback is safe to use everywhere.
+
+---
+
+## 5. `$L()` — localisation
+
+### Define keys in `localization.json`
+
+```json
+{
+  "widget.title": {
+    "en": "Revenue Dashboard",
+    "ar": "لوحة الإيرادات"
+  },
+  "widget.row-count": {
+    "en": "Showing {count} rows",
+    "ar": "عرض {count} صفوف"
+  }
+}
+```
+
+### Use `$L()` in your component
+
+```tsx
+const MyWidget: React.FC<IWidgetProps> = ({ icanContext }) => {
+  // Fallback to key passthrough when context is unavailable (dev harness)
+  const t = icanContext?.$L.bind(icanContext) ?? ((key: string) => key);
+
+  return (
+    <div className="my-widget">
+      <h3 className="my-widget__title">{t('widget.title')}</h3>
+      <p className="my-widget__count">
+        {t('widget.row-count', { count: String(rows.length) })}
+      </p>
+    </div>
+  );
+};
+```
+
+`$L(key, params?)` returns the translation for the portal's active language. `params` is a `Record<string, string>` — each key replaces a `{placeholder}` in the translation string. If a key is missing from `localization.json`, the raw key is returned.
+
+In the dev harness, `icanContext` is `undefined` so the `?? ((key) => key)` fallback returns the raw key — fine for development.
+
+---
+
+## 6. `instanceId` — multi-instance widgets
+
+The same widget can be placed on a dashboard more than once. Each placement is an independent **instance** with its own `instanceId` prop. The critical thing to understand is that **all instances share the same JavaScript module** — variables declared outside your component are shared by every instance.
+
+### The bug: module-level state
+
+```tsx
+// ❌ wrong — module-level variable, shared by ALL instances on the page
+let cachedData: unknown[] = [];
+
+const MyWidget = () => {
+  // Instance A and Instance B both read and write the same cachedData
+};
+```
+
+### The fix: React state is always instance-local
+
+```tsx
+// ✅ correct — useState creates independent state per instance
+const MyWidget = () => {
+  const [data, setData] = React.useState<unknown[]>([]);
+  // Instance A and Instance B each have their own data array
+};
+```
+
+Any variable declared **outside** the component function — including module-level caches, refs, or counters — is shared across every placement. Always use `React.useState`, `React.useRef`, or `React.useReducer` for anything that should be independent per instance.
+
+```tsx
+const MyWidget: React.FC<IWidgetProps> = ({ icanContext, instanceId }) => {
+  // instanceId is unique per placement, e.g. "dw_abc123" vs "dw_def456"
+  // Useful for logging, analytics, or keying external subscriptions
+};
+```
+
+---
+
+## 7. `cancelPrevious` and `key` — preventing overlapping calls
+
+When a user types in a search input, multiple requests can be in flight simultaneously. The last one to **respond** wins — not the last one **sent** — so results can jump out of order.
+
+Use `cancelPrevious: true` and `key` together to abort the previous call before firing a new one:
+
+```tsx
+const handleSearch = async (query: string): Promise<void> => {
+  if (!icanContext) return;
+  setLoading(true);
+  try {
+    const results = await icanContext.executeAction(
+      'SearchModel',
+      'Query',
+      { q: query },
+      {
+        json: true,
+        key: 'widget-search',     // identifies this "call slot"
+        cancelPrevious: true,     // cancels any in-flight call with the same key
+      }
+    );
+    setResults(results as SearchResult[]);
+  } catch {
+    // A cancelled call throws — swallow it
+  } finally {
+    setLoading(false));
+  }
+};
+```
+
+Use a distinct `key` per logical operation (`'search'`, `'load-table'`, `'refresh'`). `cancelPrevious` only cancels in-flight calls with the **same key** — other concurrent calls are unaffected.
+
+---
+
+## 8. Externalized dependencies — React and `ican/components`
+
+Both `react` and `ican/components` are **externalized** in `webpack.config.js`. This means:
+
+- They are **not bundled** into your `dist/main.js`
+- The portal provides them at runtime from its own copies
+- You cannot bundle a different version of React than the one the portal ships
+
+```bash
+# ✅ safe — externalised, portal provides at runtime
+import { useState } from 'react';
+import { Card, Button } from 'ican/components';
+
+# ❌ dangerous — if a library bundles its own React you get two Reacts running
+npm install some-ui-lib-that-bundles-react
+# → Silent crash: "Invalid hook call" or React Error #321
+```
+
+**Before installing any npm package**, check whether it externalises React:
+
+| Package type | Safe? |
+|---|---|
+| Utilities (`clsx`, `date-fns`, `lodash`, `zod`) | ✅ No React dependency |
+| Official React ecosystem (`swr`, `zustand`, `react-use`) | ✅ Peer-depend on React |
+| Most chart libs (`recharts`, `victory`, `nivo`) | ⚠️ Bundle their own React — may crash |
+| `@radix-ui/*`, `@floating-ui/*` | ✅ Peer-depend on React |
+
+If you need charts, prefer libraries with a pure SVG/data interface (D3, Visx) or use the chart components already provided by `ican/components`.
+
+---
+
+## 9. `bundle.json` full field reference
+
+```jsonc
+{
+  "id": "my-bundle",          // Unique bundle key — NEVER change after first upload
+  "name": "My Bundle",        // Display name in the Widget Library
+  "version": "1.0.0",         // SemVer — bump on every upload
+  "author": "your-name",
+
+  "widgets": [
+    {
+      "id": "my-widget",      // Widget identifier within this bundle
+      "name": "My Widget",    // Display name in the Add Widget modal
+      "description": "...",
+      "icon": "",             // Emoji or icon key
+      "tags": ["finance"],    // Used for filtering in the Widget Library
+      "category": "Analytics",
+      "isTemplate": false     // true = shown in the template gallery
+    }
+  ],
+
+  "sidebarLinks": [           // Links added to the portal sidebar nav
+    {
+      "id": "my-link",
+      "label": "My Tool",
+      "description": "Opens this widget's companion page",
+      "target": "/my-page",   // Portal-relative URL
+      "icon": "chart",
+      "roles": ["admin"]      // Empty array = visible to all roles
+    }
+  ],
+
+  "uis": [                    // Full-page UIs registered by this bundle
+    {
+      "id": "my-ui",
+      "label": "My Page",
+      "description": "Full-screen page for this bundle",
+      "roles": []
+    }
+  ],
+
+  "menuItems": [              // Items added to the portal top navigation menu
+    {
+      "id": "my-menu-item",
+      "title": "My Feature"
+    }
+  ]
+}
+```
+
+**Critical rule:** Never change `bundle.id` after the first upload. The portal uses it as the primary key. Changing it orphans every existing dashboard widget that references the old ID — they become unresolvable and show an error cell.
+
+---
+
+## 10. Versioning and re-upload
+
+| Scenario | Action |
+|---|---|
+| Bug fix / style change | Keep same `bundle.id` + `widget.id`. Bump `version`. Re-upload `dist/main.js` + `bundle.json`. All existing widget placements update automatically on next page load. |
+| Adding a new widget to an existing bundle | Keep same `bundle.id`. Add new entry to `widgets[]`. Bump `version`. Re-upload both files. |
+| Changing config props (adding/removing fields) | Keep same IDs. Bump `version`. Existing instances keep their old saved values; new or unconfigured fields use the `value` default from `configs.props`. |
+| Breaking change (completely new widget, different product) | Use a new `bundle.id`. Old placements are orphaned and must be removed manually from dashboards. |
+
+Re-uploading replaces the script atomically — users see the new version after their next page load or hard refresh.
+
+---
+
+## 11. AI-agent quick context block
+
+> Read this before generating any functional widget code.
+
+**Rules:**
+1. `icanContext` may be `undefined`. Always guard: `if (!icanContext) { setLoading(false); return; }`.
+2. `icanContext.environment === 'dev'` in the harness, `'prod'` in the portal. Always include a mock-data branch for `'dev'`.
+3. React and `ican/components` are externalized — never recommend a library that bundles its own React.
+4. Module-level variables are shared across all instances of the same widget on a dashboard. Always use `useState`/`useRef` for per-instance state.
+5. Never change `bundle.id` after first upload.
+
+**`registerWidget` must always include:**
+- `configs.layout` with sensible `w`, `h`, `minW`, `minH` values.
+- `configs.props` for every user-configurable value, typed to match the component's prop interface.
+- Default values in `configs.props[n].value` must match the component's TypeScript default.
+
+**`$L()` pattern:**
+```tsx
+const t = icanContext?.$L.bind(icanContext) ?? ((key: string) => key);
+```
+
+**`hasAppRole` pattern:**
+```tsx
+const isAdmin = icanContext?.hasAppRole('AppName', 'admin') ?? false;
+```
+
+**Full functional widget skeleton (copy-paste ready):**
+
+```tsx
+import * as React from 'react';
+import { Card, Button } from 'ican/components';
+import { registerWidget } from './ican';
+import type { IContextProvider } from './ican';
+import './styles.scss';
+
+interface IItem { id: string; name: string; }
+
+interface IWidgetProps {
+  icanContext?: IContextProvider;
+  instanceId?: string;
+  title?: string;
+  maxRows?: number;
+  [key: string]: unknown;
+}
+
+const MyWidget: React.FC<IWidgetProps> = ({
+  icanContext,
+  title = 'My Widget',
+  maxRows = 10,
+}) => {
+  const [data,    setData]    = React.useState<IItem[]>([]);
+  const [loading, setLoading] = React.useState(true);
+  const [error,   setError]   = React.useState<string | null>(null);
+
+  const t       = icanContext?.$L.bind(icanContext) ?? ((key: string) => key);
+  const canEdit = icanContext?.hasAppRole('MyApp', 'editor') ?? false;
+
+  React.useEffect(() => {
+    if (!icanContext) { setLoading(false); return; }
+
+    if (icanContext.environment === 'dev') {
+      setData([{ id: '1', name: 'Mock Item' }]);
+      setLoading(false);
+      return;
+    }
+
+    icanContext
+      .executeAction('MyModel', 'GetAll', { limit: maxRows }, { json: true })
+      .then((res) => { setData(res as IItem[]); })
+      .catch((err: unknown) => { setError(String(err)); })
+      .finally(() => setLoading(false));
+  }, [icanContext, maxRows]);
+
+  if (loading) return <div className="my-widget my-widget--loading"><div className="my-widget__spinner" /></div>;
+  if (error)   return <div className="my-widget my-widget--error"><p className="my-widget__error">{error}</p></div>;
+
+  return (
+    <div className="my-widget">
+      <Card>
+        <h3 className="my-widget__title">{title}</h3>
+        <ul className="my-widget__list">
+          {data.map((item) => (
+            <li key={item.id} className="my-widget__item">{item.name}</li>
+          ))}
+        </ul>
+        {canEdit && (
+          <Button variant="primary" label={t('widget.edit-btn')} onClick={() => {}} />
+        )}
+      </Card>
+    </div>
+  );
+};
+
+registerWidget({
+  id: 'my-widget',
+  widget: MyWidget,
+  configs: {
+    layout: { w: 10, h: 8, minW: 4, minH: 4 },
+    props: [
+      { name: 'title',   label: 'Widget Title', type: 'text',   value: 'My Widget' },
+      { name: 'maxRows', label: 'Max Rows',      type: 'number', value: 10,
+        validate: { minVal: 1, maxVal: 100 } },
+    ],
+  },
+});
+```
+
+---
+
+*Placed in your project root by `infaira-canvas init`. Applies to `infaira-canvas` v0.1.9+.*