@app-studio/web 0.9.80 → 0.9.82

package/docs/components/Chart.mdx

@@ -1,342 +1,117 @@
 # Chart
 
-A component for visualizing data in various chart formats.
+A comprehensive charting component for visualizing data in various formats including bar, line, area, pie, and donut charts.
 
 ### **Import**
-  ```tsx
-  import { Chart, CHART_COLORS } from '@app-studio/web';
-  ```
-
-### **Bar Chart**
 ```tsx
-import React from 'react';
-import { Chart, CHART_COLORS, View } from '@app-studio/web';
-
-export const BarChartDemo = () => {
-  const data = {
-    labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'],
-    series: [
-      {
-        name: 'Revenue',
-        data: [30, 40, 35, 50, 49, 60],
-        color: CHART_COLORS.blue,
-      },
-      {
-        name: 'Expenses',
-        data: [20, 25, 30, 35, 30, 40],
-        color: CHART_COLORS.green,
-      },
-      {
-        name: 'Profit',
-        data: [10, 15, 5, 15, 19, 20],
-        color: CHART_COLORS.purple,
-      },
-    ],
-  };
-
-  return (
-    <View height="300px" width="100%">
-      <Chart
-        type="bar"
-        data={data}
-        title="Monthly Revenue vs Expenses"
-        showGrid
-        animated
-        onSeriesClick={(seriesName, index) => {
-          console.log(`Clicked on ${seriesName} at index ${index}`);
-        }}
-      />
-    </View>
-  );
-};
+import { Chart, CHART_COLORS } from '@app-studio/web';
 ```
 
-### **Line Chart**
+### **Quick Start (Bar Chart)**
 ```tsx
 import React from 'react';
 import { Chart, CHART_COLORS, View } from '@app-studio/web';
 
-export const LineChartDemo = () => {
-  const data = {
-    labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'],
-    series: [
-      {
-        name: 'Users',
-        data: [500, 800, 1200, 1800, 2500, 3000],
-        color: CHART_COLORS.purple,
-      },
-      {
-        name: 'Sessions',
-        data: [1000, 1600, 2400, 3600, 5000, 6000],
-        color: CHART_COLORS.teal,
-      },
-    ],
-  };
-
-  return (
-    <View height="300px" width="100%">
-      <Chart
-        type="line"
-        data={data}
-        title="Website Traffic"
-        showGrid
-        animated
-        legendPosition="top"
-      />
+export const SimpleBarChart = () => (
+    <View height="300px">
+        <Chart
+            type="bar"
+            title="Monthly Sales"
+            data={{
+                labels: ['Jan', 'Feb', 'Mar'],
+                series: [{ name: 'Sales', data: [30, 50, 40], color: CHART_COLORS.blue }]
+            }}
+        />
     </View>
-  );
-};
+);
 ```
 
-### **Area Chart**
-```tsx
-import React from 'react';
-import { Chart, CHART_COLORS, View } from '@app-studio/web';
+### **Chart Types**
 
-export const AreaChartDemo = () => {
-  const data = {
-    labels: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
-    series: [
-      {
-        name: 'This Week',
-        data: [10, 15, 12, 20, 18, 25, 22],
-        color: CHART_COLORS.green,
-      },
-      {
-        name: 'Last Week',
-        data: [8, 12, 10, 15, 14, 20, 17],
-        color: CHART_COLORS.blue,
-      },
-    ],
-  };
+#### **Line & Area Charts**
+Useful for showing trends over time.
 
-  return (
-    <View height="300px" width="100%">
-      <Chart
-        type="area"
-        data={data}
-        title="Weekly Performance"
-        showGrid
-        animated
-      />
-    </View>
-  );
-};
-```
-
-### **Pie Chart**
 ```tsx
-import React from 'react';
-import { Chart, CHART_COLORS, View } from '@app-studio/web';
-
-export const PieChartDemo = () => {
-  const dataPoints = [
-    { label: 'Mobile', value: 45, color: CHART_COLORS.blue },
-    { label: 'Desktop', value: 30, color: CHART_COLORS.green },
-    { label: 'Tablet', value: 15, color: CHART_COLORS.purple },
-    { label: 'Other', value: 10, color: CHART_COLORS.orange },
-  ];
-
-  return (
-    <View height="300px" width="100%">
-      <Chart
-        type="pie"
-        dataPoints={dataPoints}
-        title="Device Distribution"
-        animated
-        onDataPointClick={(dataPoint, index) => {
-          console.log(`Clicked on ${dataPoint?.label} at index ${index}`);
+<View height="300px">
+    <Chart
+        type="line" // or "area"
+        title="User Growth"
+        showGrid
+        showTooltips
+        data={{
+            labels: ['Q1', 'Q2', 'Q3', 'Q4'],
+            series: [
+                { name: '2023', data: [100, 120, 140, 180], color: CHART_COLORS.purple },
+                { name: '2024', data: [150, 190, 220, 280], color: CHART_COLORS.teal }
+            ]
         }}
-      />
-    </View>
-  );
-};
+    />
+</View>
 ```
 
-### **Donut Chart**
-```tsx
-import React from 'react';
-import { Chart, CHART_COLORS, View } from '@app-studio/web';
-
-export const DonutChartDemo = () => {
-  const dataPoints = [
-    { label: 'Completed', value: 65, color: CHART_COLORS.green },
-    { label: 'In Progress', value: 25, color: CHART_COLORS.blue },
-    { label: 'Pending', value: 10, color: CHART_COLORS.orange },
-  ];
-
-  return (
-    <View height="300px" width="100%">
-      <Chart
-        type="donut"
-        dataPoints={dataPoints}
-        title="Task Status"
-        animated
-      />
-    </View>
-  );
-};
-```
+#### **Pie & Donut Charts**
+Useful for showing proportional data.
 
-### **Custom Styling**
 ```tsx
-import React from 'react';
-import { Chart, CHART_COLORS, View } from '@app-studio/web';
-
-export const CustomChartDemo = () => {
-  const data = {
-    labels: ['Q1', 'Q2', 'Q3', 'Q4'],
-    series: [
-      {
-        name: 'Sales',
-        data: [120, 180, 150, 210],
-        color: CHART_COLORS.blue,
-      },
-    ],
-  };
-
-  return (
-    <View height="300px" width="100%">
-      <Chart
-        type="bar"
-        data={data}
-        title="Quarterly Sales"
-        animated
-        views={{
-          container: {
-            backgroundColor: 'color.gray.50',
-            padding: '16px',
-            borderRadius: '8px',
-            boxShadow: '0 2px 8px rgba(0, 0, 0, 0.1)',
-          },
-          chart: {
-            margin: '16px 0',
-          },
-          bar: {
-            rx: '4px',
-            ry: '4px',
-            fill: 'color.blue',
-          },
-          grid: {
-            stroke: 'color.gray.300',
-            strokeDasharray: '4',
-          },
-          axis: {
-            stroke: 'color.gray.400',
-            strokeWidth: '2px',
-          },
-          legend: {
-            backgroundColor: 'color.white',
-            padding: '8px',
-            borderRadius: '4px',
-          },
-        }}
-      />
-    </View>
-  );
-};
+<View height="300px">
+    <Chart
+        type="donut" // or "pie"
+        title="Device Usage"
+        dataPoints={[
+            { label: 'Mobile', value: 60, color: CHART_COLORS.indigo },
+            { label: 'Desktop', value: 30, color: CHART_COLORS.cyan },
+            { label: 'Tablet', value: 10, color: CHART_COLORS.gray }
+        ]}
+        onDataPointClick={(point, index) => alert(`Clicked ${point.label}`)}
+    />
+</View>
 ```
 
-### **Chart States**
-
-The Chart component supports loading, error, and no data states:
+### **States (Loading, Error, No Data)**
+Handle various UI states gracefully with built-in props.
 
 ```tsx
 import React, { useState } from 'react';
-import { Chart, CHART_COLORS, View, Button, Horizontal } from '@app-studio/web';
-
-export const ChartStatesDemo = () => {
-  const [state, setState] = useState<'normal' | 'loading' | 'error' | 'noData'>('normal');
-
-  const data = {
-    labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'],
-    series: [
-      {
-        name: 'Revenue',
-        data: [30, 40, 35, 50, 49, 60],
-        color: CHART_COLORS.blue,
-      },
-    ],
-  };
-
-  return (
-    <View>
-      <Horizontal gap="8px" marginBottom="16px">
-        <Button onClick={() => setState('normal')}>Normal</Button>
-        <Button onClick={() => setState('loading')}>Loading</Button>
-        <Button onClick={() => setState('error')}>Error</Button>
-        <Button onClick={() => setState('noData')}>No Data</Button>
-      </Horizontal>
-
-      <View height="300px" width="100%">
-        <Chart
-          type="bar"
-          data={data}
-          title="Revenue Chart"
-          showGrid
-          animated
-          isLoading={state === 'loading'}
-          error={state === 'error' ? 'Failed to load chart data' : undefined}
-          noData={state === 'noData'}
-        />
-      </View>
-    </View>
-  );
-};
-```
-
-### **Zero Values**
-
-The Chart component handles cases where all values are zero by displaying the axes with a default scale, ensuring the chart structure remains visible.
-
-```tsx
-import React from 'react';
-import { Chart, CHART_COLORS, View } from '@app-studio/web';
-
-export const ZeroValuesDemo = () => {
-  const data = {
-    labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'],
-    series: [
-      {
-        name: 'Revenue',
-        data: [0, 0, 0, 0, 0, 0],
-        color: CHART_COLORS.blue,
-      },
-    ],
-  };
-
-  return (
-    <View height="300px" width="100%">
-      <Chart
-        type="bar"
-        data={data}
-        title="Zero Revenue Chart"
-        showGrid
-        animated
-      />
-    </View>
-  );
+import { Chart, Button, Vertical, Horizontal } from '@app-studio/web';
+
+export const ChartStateDemo = () => {
+    const [status, setStatus] = useState('normal'); 
+
+    return (
+        <Vertical gap={20}>
+            <Horizontal gap={10}>
+                <Button onClick={() => setStatus('loading')}>Load</Button>
+                <Button onClick={() => setStatus('error')}>Error</Button>
+                <Button onClick={() => setStatus('empty')}>Empty</Button>
+            </Horizontal>
+
+            <View height="300px">
+                <Chart
+                    type="bar"
+                    title="Revenue"
+                    isLoading={status === 'loading'}
+                    error={status === 'error' ? 'Connection Failed' : undefined}
+                    noData={status === 'empty'}
+                    data={{ labels: ['A', 'B'], series: [{ name: 'Val', data: [1, 2] }] }}
+                />
+            </View>
+        </Vertical>
+    );
 };
 ```
 
-### **Available Colors**
-
-The Chart component provides a set of predefined colors through `CHART_COLORS`:
+### **Interactive Events**
+- **onSeriesClick**: Called when a bar (bar chart) or point (line/area) is clicked.
+- **onDataPointClick**: Called when a slice (pie/donut) is clicked.
 
 ```tsx
-import { CHART_COLORS } from '@app-studio/web';
-
-// Available colors:
-CHART_COLORS.blue      // 'color.blue.500'
-CHART_COLORS.green     // 'color.green.500'
-CHART_COLORS.purple    // 'color.purple.500'
-CHART_COLORS.orange    // 'color.orange.500'
-CHART_COLORS.red       // 'color.red.500'
-CHART_COLORS.teal      // 'color.teal.500'
-CHART_COLORS.pink      // 'color.pink.500'
-CHART_COLORS.indigo    // 'color.indigo.500'
-CHART_COLORS.yellow    // 'color.yellow.500'
-CHART_COLORS.cyan      // 'color.cyan.500'
+<Chart
+    type="bar"
+    data={data}
+    onSeriesClick={(seriesName, index) => {
+        console.log(`Series: ${seriesName}, Index: ${index}`);
+    }}
+/>
 ```
 
 ### **Props Reference**
@@ -348,64 +123,14 @@ CHART_COLORS.cyan      // 'color.cyan.500'
 | `dataPoints` | `ChartDataPoint[]` | - | Data points for single series charts (pie, donut) |
 | `title` | `string` | - | The title of the chart |
 | `showLegend` | `boolean` | `true` | Whether to show the legend |
-| `legendPosition` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'bottom'` | Position of the legend |
-| `showGrid` | `boolean` | `true` | Whether to show grid lines |
-| `showTooltips` | `boolean` | `true` | Whether to show tooltips on hover |
-| `animated` | `boolean` | `true` | Whether the chart is animated |
-| `animationDuration` | `number` | `500` | Duration of the animation in milliseconds |
-| `responsive` | `boolean` | `true` | Whether the chart is responsive |
-| `aspectRatio` | `number` | `16/9` | The aspect ratio of the chart (width/height) |
-| `width` | `number \| string` | `200` | The width of the chart |
-| `height` | `number \| string` | `200` | The height of the chart |
-| `views` | `ChartStyles` | - | Custom styles for different parts of the chart |
-| `onDataPointClick` | `(dataPoint, index) => void` | - | Callback when a data point is clicked (pie/donut) |
-| `onSeriesClick` | `(seriesName, index) => void` | - | Callback when a series is clicked (bar/line/area) |
-| `isLoading` | `boolean` | `false` | If true, displays a loading indicator overlay |
-| `error` | `React.ReactNode` | - | If provided, displays an error message overlay |
-| `noData` | `boolean \| React.ReactNode` | - | If true, displays a "no data" message |
-| `loadingIndicator` | `React.ReactNode` | - | Custom placeholder for the loading state |
-| `errorIndicator` | `React.ReactNode` | - | Custom placeholder for the error state |
-| `noDataIndicator` | `React.ReactNode` | - | Custom placeholder for the no data state |
-| `aria-label` | `string` | - | Aria-label for the chart region (defaults to title) |
-
-### **Type Definitions**
-
-```tsx
-interface ChartData {
-  labels: string[];
-  series: ChartSeries[];
-}
-
-interface ChartSeries {
-  name: string;
-  data: number[];
-  color?: string;
-}
-
-interface ChartDataPoint {
-  label: string;
-  value: number;
-  color?: string;
-}
-
-interface ChartStyles {
-  container?: ViewProps;
-  chart?: ViewProps;
-  legend?: ViewProps;
-  legendItem?: ViewProps;
-  tooltip?: ViewProps;
-  axis?: ViewProps;
-  grid?: ViewProps;
-  bar?: ViewProps;
-  line?: ViewProps;
-  point?: ViewProps;
-  pie?: ViewProps;
-  area?: ViewProps;
-  axisLabel?: ViewProps;
-  axisLine?: ViewProps;
-  axisTick?: ViewProps;
-  loadingOverlay?: ViewProps;
-  errorOverlay?: ViewProps;
-  noDataOverlay?: ViewProps;
-}
-```
+| `showGrid` | `boolean` | `true` | Show background grid (cartesian charts) |
+| `showTooltips` | `boolean` | `true` | Show tooltips on hover |
+| `animated` | `boolean` | `true` | Animate entry |
+| `isLoading` | `boolean` | `false` | Show loading overlay |
+| `error` | `ReactNode` | - | Show error message overlay |
+| `noData` | `boolean \| ReactNode` | - | Show no data message overlay |
+| `height` / `width` | `number \| string` | `200` | Dimensions of the chart container |
+| `views` | `ChartStyles` | - | Custom styles override object |
+
+### **Available Colors (CHART_COLORS)**
+`blue`, `green`, `purple`, `orange`, `red`, `teal`, `pink`, `indigo`, `yellow`, `cyan`.

package/docs/components/ChatWidget.mdx

@@ -0,0 +1,106 @@
+---
+title: ChatWidget
+description: A comprehensive chat interface component with support for various message types, attachments, and context integration.
+---
+
+# ChatWidget
+
+The `ChatWidget` provides a polished, interactive chat UI. It supports user and assistant messages, rich content types (including reasoning blocks and tool outputs), file attachments, and context-aware inputs.
+
+## Usage
+
+```tsx
+import { ChatWidget } from 'app-studio';
+import { useState } from 'react';
+
+const MyChat = () => {
+  const [messages, setMessages] = useState([
+    { id: '1', role: 'assistant', content: 'Hello! How can I help you?', timestamp: new Date() }
+  ]);
+
+  const handleSend = (text: string) => {
+    // Add user message
+    const userMsg = { id: Date.now().toString(), role: 'user', content: text, timestamp: new Date() };
+    setMessages(prev => [...prev, userMsg]);
+    
+    // Simulate reponse
+    setTimeout(() => {
+        setMessages(prev => [...prev, { 
+            id: (Date.now() + 1).toString(), 
+            role: 'assistant', 
+            content: 'I received your message!', 
+            timestamp: new Date() 
+        }]);
+    }, 1000);
+  };
+
+  return (
+    <div style={{ height: 500, width: 400 }}>
+      <ChatWidget
+        messages={messages}
+        onSubmit={handleSend}
+        variant="default"
+        inputPlaceholder="Type a message..."
+      />
+    </div>
+  );
+};
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `messages` | `Message[]` | `[]` | Array of message objects to display. |
+| `inputValue` | `string` | - | Value for the message input (controlled mode). |
+| `onInputChange` | `(value: string) => void` | - | Callback when input value changes. |
+| `onSubmit` | `(message: string) => void` | - | Callback when a message is sent. |
+| `inputPlaceholder` | `string` | - | Placeholder text for the input area. |
+| `disableInput` | `boolean` | `false` | Whether the input area is disabled. |
+| `variant` | `'default' \| 'glassy' \| 'minimal'` | `'default'` | Visual style variant of the widget. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | General size scale of the widget. |
+| `showTimestamps` | `boolean` | `false` | Whether to display timestamps below messages. |
+| `enableAttachments` | `boolean` | `false` | Shows the attachment (paperclip) button. |
+| `enableContextPicker` | `boolean` | `false` | Shows the context picker (+ button) in the input area. |
+| `selectedContextElements` | `ContextElement[]` | `[]` | List of context elements currently selected/attached to the input. |
+| `isLoading` | `boolean` | `false` | Displays a loading indicator if true. |
+| `loadingText` | `string` | - | Text to display alongside the loading indicator. |
+| `maxHeight` | `string \| number` | - | Maximum height for the messages display area. |
+
+## Types
+
+### Message
+
+```typescript
+type MessageRole = 'user' | 'assistant';
+type MessageType = 'text' | 'error' | 'system' | 'tool';
+
+interface Message {
+  id: string;
+  role: MessageRole;
+  content: string;
+  timestamp: Date;
+  reasoning?: string; // Collapsible "thinking" process block
+  messageType?: MessageType; // Defaults to 'text'
+  attachments?: Attachment[];
+  contextElements?: ContextElement[];
+}
+```
+
+### ContextElement
+
+```typescript
+interface ContextElement {
+  id: string;
+  name: string;
+  tagName: string;
+  rect?: DOMRect;
+}
+```
+
+## Variants
+
+- **default**: Standard solid background appearance.
+- **glassy**: Semi-transparent background with blur effects (requires appropriate container/background).
+- **minimal**: Stripped down appearance, suitable for embedding in tighter spaces.
+

package/docs/components/EditComponent.mdx

@@ -0,0 +1,76 @@
+---
+title: EditComponent
+description: A floating or overlay toolbar designed for contextual editing of elements, with support for custom tools and positioning.
+---
+
+# EditComponent
+
+The `EditComponent` is a versatile toolbar that positions itself relative to a target element. It is commonly used for inline editing interfaces, providing a set of tools (icons) that can trigger actions or open sub-panels.
+
+## Usage
+
+```tsx
+import { EditComponent } from 'app-studio';
+import { useRef, useState } from 'react';
+
+const MyComponent = () => {
+  const [target, setTarget] = useState<HTMLElement | null>(null);
+
+  return (
+    <>
+      <div 
+        onClick={(e) => setTarget(e.currentTarget)} 
+        style={{ width: 100, height: 100, background: 'red' }}
+      >
+        Click me
+      </div>
+
+      <EditComponent 
+        targetElement={target}
+        onClose={() => setTarget(null)}
+        side="right"
+        sideOffset={12}
+        variant="floating"
+        onToolAction={(toolId) => console.log('Action:', toolId)}
+      />
+    </>
+  );
+};
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `targetElement` | `HTMLElement \| null` | - | The DOM element to which the toolbar should be anchored. If `null`, the component is hidden. |
+| `defaultToolId` | `string` | - | The ID of the tool that should be active/open by default. |
+| `onClose` | `() => void` | - | Callback function triggered when the toolbar or its active panel requests to close. |
+| `side` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'right'` | The preferred side of the target element to place the toolbar. |
+| `sideOffset` | `number` | `12` | The distance (in pixels) between the target element and the toolbar. |
+| `variant` | `'floating' \| 'overlay'` | `'floating'` | The display mode. `'floating'` places the toolbar outside the element, while `'overlay'` positions it inside/on top of the element. |
+| `items` | `ToolbarItem[]` | `[...]` | Configuration for the toolbar items/icons. See `ToolbarItem` definition. |
+| `onToolAction` | `(id: string) => void` | - | Callback triggered when a tool with `actionOnly: true` is clicked. |
+
+### ToolbarItem Interface
+
+```typescript
+interface ToolbarItem {
+  id: string; // Unique identifier for the tool
+  icon: string; // Icon name to display
+  label?: string; // Optional tooltip label
+  special?: boolean; // If true, applies special styling (e.g., dark background)
+  actionOnly?: boolean; // If true, clicking triggers onToolAction without opening a panel
+}
+```
+
+## Positioning Behavior
+
+The component uses an intelligent positioning system (`useElementPosition`) that tracks the target element's position on scroll and resize.
+
+- **Floating**: Attempts to stick to the specified `side`. If there isn't enough space, it may flip or adjust (though currently typically locks to the initial best side upon opening).
+- **Overlay**: Fixed positioning relative to the top-left of the target element (plus offset).
+
+## Panels
+
+When a tool is selected (and is not `actionOnly`), the `EditComponent` renders an `EditPanel` component. This panel is positioned adjacent to the toolbar based on the toolbar's orientation and position.
+