@aiderdesk/aiderdesk 0.67.0 → 0.69.0

package/out/resources/skills/extension-creator/references/external-libraries.md

@@ -0,0 +1,159 @@
+# External Libraries in UI Components
+
+Extensions can load third-party npm packages and use them in their UI component JSX. This is useful when you need a rich component library (e.g., charts, kanban boards, calendars) that isn't available through the built-in `ui` prop.
+
+## How It Works
+
+1. **Declare** — Implement `getUIComponentsLibraries()` returning a map of arbitrary keys to npm package specs.
+2. **Resolve** — AiderDesk resolves each package via [esm.sh](https://esm.sh) (React and React-DOM are externalized to avoid duplicate instances). Resolved sources are cached to `~/.aider-desk/cache/extension-libraries/` for offline reuse.
+3. **Access** — Resolved libraries are passed to your JSX as `props.libraries.<key>`.
+
+## Declaring Libraries
+
+```typescript
+getUIComponentsLibraries(): Record<string, string> {
+  return {
+    chart: 'recharts@^2.12.0',
+    lodash: 'lodash@^4.17.0',
+  };
+}
+```
+
+- **Key** — camelCase identifier you'll use to access the library in JSX (e.g., `props.libraries.chart`).
+- **Value** — npm package name with a semver range, exactly as you'd list it in `package.json` (e.g., `'recharts@^2.12.0'`).
+
+## Accessing in JSX
+
+Libraries arrive as `props.libraries.<key>`. Each value is the module's resolved exports — you can destructure named exports or use the default:
+
+```jsx
+(props) => {
+  var chartLib = props.libraries.chart;
+  if (!chartLib) return <span>Loading chart library…</span>;
+
+  var LineChart = chartLib.LineChart;
+  var Line = chartLib.Line;
+  // ... use them
+}
+```
+
+## Loading State
+
+Libraries are loaded asynchronously. On first render `props.libraries.<key>` will be `undefined`. Always check for availability before using a library:
+
+```jsx
+(props) => {
+  var chartLib = props.libraries.chart;
+
+  if (!chartLib) {
+    return <span className="text-text-secondary text-sm">Loading…</span>;
+  }
+
+  var LineChart = chartLib.LineChart;
+  return <LineChart data={props.data} />;
+}
+```
+
+If you want to show an error after a timeout, use `useEffect` with a flag:
+
+```jsx
+(props) => {
+  var useState = React.useState;
+  var useEffect = React.useEffect;
+  var chartLib = props.libraries.chart;
+
+  var _e = useState(false);
+  var loadError = _e[0];
+  var setLoadError = _e[1];
+
+  useEffect(function () {
+    if (!chartLib && !loadError) {
+      var t = setTimeout(function () { setLoadError(true); }, 15000);
+      return function () { clearTimeout(t); };
+    }
+    setLoadError(false);
+  }, [chartLib, loadError]);
+
+  if (loadError && !chartLib) {
+    return <span className="text-red-400 text-sm">Failed to load library.</span>;
+  }
+  if (!chartLib) {
+    return <span className="text-text-secondary text-sm">Loading…</span>;
+  }
+
+  var LineChart = chartLib.LineChart;
+  return <LineChart data={props.data} />;
+}
+```
+
+## Important Notes
+
+- **React is externalized** — AiderDesk's React instance is used automatically. Never bundle or import React inside the library spec; it is already available globally. The esm.sh resolution uses `?external=react,react-dom,react/jsx-runtime,react/jsx-dev-runtime` to prevent duplicate React instances.
+- **Internet required on first load** — Libraries are fetched from esm.sh on first use, then cached to disk. Subsequent loads work offline.
+- **Single-file extensions** — `getUIComponentsLibraries()` works in both single-file and folder extensions.
+- **Key naming** — Use camelCase keys. A key like `chart` becomes `props.libraries.chart`. Avoid dots or special characters in keys.
+- **Multiple libraries** — You can declare as many libraries as needed. Each is loaded independently.
+
+## Minimal Example
+
+```typescript
+// chart-demo.ts
+import type { Extension, ExtensionContext, UIComponentDefinition } from '@aiderdesk/extensions';
+
+const chartJsx = `
+(props) => {
+  var chartLib = props.libraries.chart;
+  var Button = props.ui.Button;
+
+  if (!chartLib) {
+    return <span className="text-text-secondary text-xs">Loading chart…</span>;
+  }
+
+  var PieChart = chartLib.PieChart;
+  var Pie = chartLib.Pie;
+
+  var data = [
+    { name: 'A', value: 40 },
+    { name: 'B', value: 60 },
+  ];
+
+  return (
+    <div className="p-2">
+      <PieChart width={200} height={200}>
+        <Pie data={data} dataKey="value" nameKey="name" cx="50%" cy="50%" outerRadius={80} />
+      </PieChart>
+    </div>
+  );
+}
+`;
+
+export default class ChartDemoExtension implements Extension {
+  static metadata = {
+    name: 'Chart Demo',
+    version: '1.0.0',
+    description: 'Demonstrates loading a third-party npm library (recharts) in an extension',
+    author: 'my_git_name',
+    capabilities: ['ui', 'example'],
+  };
+
+  async onLoad(context: ExtensionContext): Promise<void> {
+    context.log('Chart Demo loaded', 'info');
+  }
+
+  getUIComponents(_context: ExtensionContext): UIComponentDefinition[] {
+    return [
+      {
+        id: 'chart-demo',
+        placement: 'task-status-bar-left',
+        jsx: chartJsx,
+      },
+    ];
+  }
+
+  getUIComponentsLibraries(): Record<string, string> {
+    return {
+      chart: 'recharts@^2.12.0',
+    };
+  }
+}
+```

package/out/resources/skills/extension-creator/references/ui-components.md

@@ -28,6 +28,7 @@ getUIComponents(context: ExtensionContext): UIComponentDefinition[] {
 
 - **id** (string, required): Unique identifier for the component
 - **placement** (UIComponentPlacement, required): Where to render the component
+- **name** (string, optional): Display name for the component (used as floating panel title)
 - **jsx** (string, required): JSX/TSX component code as a string
 - **loadData** (boolean, optional): Whether to load data via `getUIExtensionData()` (default: false)
 - **noDataCache** (boolean, optional): Always fetch fresh data on render (default: false)
@@ -140,6 +141,16 @@ UI components can be placed in various locations throughout the AiderDesk interf
   - *Layout*: Full page layout
   - *Note*: Replaces default welcome screen entirely
 
+### Floating Panels
+
+- **floating**: Draggable, resizable floating panel rendered as a React portal
+  - *Use for*: Side-by-side tools that need to coexist with the chat (inspectors, previews, dashboards, scratchpads)
+  - *Layout*: Free-form floating panel — extension JSX is the panel content, panel chrome (title bar, resize handles) is automatic
+  - *Portal*: Rendered inside the project area via a portal host — has access to current task context
+  - *Title*: Set via the `name` property on `UIComponentDefinition` — used as the floating panel title
+  - *Behavior*: Draggable by title bar, resizable from edges, minimizable. Position and size are persisted in local storage
+  - *Note*: Extension JSX should only contain the inner content — never wrap in a panel component
+
 ## Component Props
 
 All UI components receive these props via the `data` prop passed by `string-to-react-component`.
@@ -208,6 +219,9 @@ All UI components receive these props via the `data` prop passed by `string-to-r
   // Extension action executor
   executeExtensionAction: (action: string, ...args: unknown[]) => Promise<unknown>,
   
+  // External libraries loaded via getUIComponentsLibraries()
+  libraries: Record<string, Record<string, unknown>>,
+  
   // Data returned from getUIExtensionData() (if loadData: true)
   data?: unknown,
 }
@@ -427,6 +441,27 @@ The `icons` prop provides access to all react-icons libraries:
 }
 ```
 
+## Using External Libraries
+
+The `libraries` prop provides access to third-party npm packages declared via `getUIComponentsLibraries()`. Each key in the returned Record becomes a property on `props.libraries`.
+
+Libraries are loaded asynchronously — on first render, `props.libraries.<key>` will be `undefined`. Always check availability before use:
+
+```jsx
+(props) => {
+  var chartLib = props.libraries.chart;
+
+  if (!chartLib) {
+    return <span className="text-text-secondary text-sm">Loading chart…</span>;
+  }
+
+  var LineChart = chartLib.LineChart;
+  return <LineChart data={props.data} />;
+}
+```
+
+For full documentation on declaring and using external libraries, see [external-libraries.md](external-libraries.md).
+
 ## Providing Data to Components
 
 When `loadData: true`, implement `getUIExtensionData()`: