@app-studio/web 0.9.20 → 0.9.22

package/docs/README.md

@@ -1,24 +1,31 @@
 # App Studio Web Component Library Documentation
 
-Welcome to the documentation for the App Studio Web Component Library. This documentation provides comprehensive guides, API references, and examples to help you build high-quality components and applications using our library.
+Welcome to the comprehensive documentation for the App Studio Web Component Library. This documentation provides guides, API references, and examples to help you build high-quality components and applications.
 
-## Documentation Structure
+## 📖 Documentation Structure
 
-- **Getting Started**: Quick start guides to help you begin using the library
-- **Component Development**: Detailed guides for building components
-- **Design System**: Information about the design system, theming, and styling
-- **API Reference**: Detailed API documentation for all components
-- **Tutorials**: Step-by-step tutorials for common tasks
-- **Contributing**: Guidelines for contributing to the library
+### Core Documentation
+- **[Getting Started](./getting-started/introduction.md)** - Quick introduction and setup
+- **[Component Development](./component-development/guide.md)** - Building and contributing components
+- **[API Integration](./api-integration.md)** - Backend integration patterns
+- **[Design System](./design-system/theming.md)** - Theming and styling guidelines
 
-## Using This Documentation
+### Specialized Documentation
+- **[ADK Components](../README-ADK.md)** - Agent Development Kit integration
+- **[API Reference](./api-reference/README.md)** - Detailed component APIs
+- **[Tutorials](./tutorials/README.md)** - Step-by-step guides
+- **[Contributing](./contributing/documentation.md)** - Contribution guidelines
 
-The documentation is organized to support different learning styles and needs:
+## 🚀 Quick Navigation
 
-- If you're new to the library, start with the [Getting Started](./getting-started/introduction.md) guide
-- If you're building components, refer to the [Component Development Guide](./component-development/guide.md)
-- If you need detailed API information, check the [API Reference](./api-reference/README.md)
-- If you want to learn through examples, explore the [Tutorials](./tutorials/README.md)
+### For New Users
+Start with the [Getting Started Guide](./getting-started/introduction.md) to understand the library basics and setup process.
+
+### For Developers
+Refer to the [Component Development Guide](./component-development/guide.md) for building and customizing components.
+
+### For ADK Integration
+Check the [ADK Components documentation](../README-ADK.md) for agent-specific functionality.
 
 ## Documentation Tools
 

package/docs/adk-customization-guide.md

@@ -0,0 +1,204 @@
+# ADK Components Customization Guide
+
+This guide demonstrates how to customize ADK components using the enhanced `views` prop and `containerProps` for complete control over appearance and behavior.
+
+## Overview
+
+All ADK components now support comprehensive customization through:
+
+1. **Enhanced `views` prop** - Granular control over individual component parts
+2. **Container props** - Direct styling of the main container
+3. **Theme props** - Built-in color schemes and layout options
+4. **Responsive design** - Automatic adaptation across devices
+
+## Component Customization
+
+### AgentChat Component
+
+The AgentChat component supports extensive customization of all its parts:
+
+```tsx
+<AgentChat
+  appName="my-agent"
+  userId="user123"
+  colorScheme="purple"
+  compact={false}
+  rounded={true}
+  containerProps={{
+    backgroundColor: 'color.purple.25',
+    border: '2px solid',
+    borderColor: 'color.purple.300',
+  }}
+  views={{
+    // Main areas
+    container: { backgroundColor: 'color.purple.25' },
+    header: { backgroundColor: 'color.purple.500', color: 'white' },
+    messageList: { backgroundColor: 'color.white', padding: '20px' },
+    inputArea: { backgroundColor: 'color.purple.50', padding: '16px' },
+    
+    // Message styling
+    userMessage: {
+      backgroundColor: 'color.purple.500',
+      color: 'white',
+      borderRadius: '18px 18px 4px 18px',
+      padding: '12px 16px',
+    },
+    botMessage: {
+      backgroundColor: 'color.purple.100',
+      color: 'color.purple.900',
+      borderRadius: '18px 18px 18px 4px',
+      padding: '12px 16px',
+    },
+    
+    // Input components
+    inputField: {
+      borderRadius: '24px',
+      border: '2px solid',
+      borderColor: 'color.purple.200',
+    },
+    sendButton: {
+      backgroundColor: 'color.purple.500',
+      borderRadius: '50%',
+    },
+    
+    // State indicators
+    typingIndicator: {
+      color: 'color.purple.600',
+      backgroundColor: 'color.purple.100',
+      borderRadius: '16px',
+    },
+    
+    // Function calls and code
+    functionCall: {
+      backgroundColor: 'color.purple.50',
+      border: '1px solid',
+      borderColor: 'color.purple.200',
+      borderRadius: '8px',
+    },
+    codeBlock: {
+      backgroundColor: 'color.gray.900',
+      color: 'color.gray.100',
+      borderRadius: '8px',
+    },
+  }}
+/>
+```
+
+### AgentSession Component
+
+The AgentSession component provides comprehensive session management customization:
+
+```tsx
+<AgentSession
+  appName="my-agent"
+  userId="user123"
+  colorScheme="green"
+  layout="list"
+  showPreviews={true}
+  enableBulkOperations={true}
+  containerProps={{
+    backgroundColor: 'color.green.25',
+    border: '2px solid',
+    borderColor: 'color.green.300',
+  }}
+  views={{
+    // Main areas
+    container: { backgroundColor: 'color.green.25' },
+    header: { backgroundColor: 'color.green.500', color: 'white' },
+    sessionList: { backgroundColor: 'color.white', padding: '16px' },
+    
+    // Session items
+    sessionItem: {
+      backgroundColor: 'color.green.50',
+      borderRadius: '8px',
+      padding: '12px',
+      border: '1px solid',
+      borderColor: 'color.green.200',
+    },
+    activeSessionItem: {
+      backgroundColor: 'color.green.100',
+      borderColor: 'color.green.500',
+      borderWidth: '2px',
+    },
+    
+    // Session content
+    sessionTitle: { fontWeight: '600', color: 'color.green.900' },
+    sessionDescription: { color: 'color.green.700' },
+    sessionTimestamp: { color: 'color.green.600', fontSize: '12px' },
+    
+    // Action buttons
+    createButton: {
+      backgroundColor: 'color.green.500',
+      color: 'white',
+      borderRadius: '8px',
+    },
+    deleteButton: {
+      backgroundColor: 'color.red.500',
+      color: 'white',
+      borderRadius: '6px',
+    },
+    
+    // Search and filters
+    searchInput: {
+      borderRadius: '20px',
+      border: '2px solid',
+      borderColor: 'color.green.200',
+    },
+  }}
+/>
+```
+
+## Available Views Properties
+
+### AgentChat Views
+
+- **Main Areas**: `container`, `header`, `messageList`, `inputArea`, `attachmentArea`
+- **Messages**: `message`, `userMessage`, `botMessage`, `systemMessage`, `messageContent`, `messageTimestamp`, `messageAvatar`, `messageActions`
+- **Input**: `inputField`, `sendButton`, `attachButton`, `recordButton`, `inputToolbar`
+- **States**: `loadingIndicator`, `typingIndicator`, `errorMessage`, `emptyState`
+- **Features**: `functionCall`, `functionResponse`, `codeBlock`, `codeOutput`, `thoughtBubble`
+- **Attachments**: `attachmentPreview`, `attachmentItem`, `attachmentRemoveButton`
+
+### AgentSession Views
+
+- **Main Areas**: `container`, `header`, `toolbar`, `sessionList`, `sessionActions`, `filtersPanel`
+- **Session Items**: `sessionItem`, `activeSessionItem`, `sessionInfo`, `sessionTitle`, `sessionDescription`, `sessionMetadata`, `sessionTimestamp`, `sessionTags`, `sessionStats`
+- **Actions**: `createButton`, `deleteButton`, `exportButton`, `importButton`, `refreshButton`, `selectButton`, `duplicateButton`
+- **Search/Filter**: `searchInput`, `filterDropdown`, `sortDropdown`, `dateRangePicker`, `tagFilter`
+- **States**: `emptyState`, `loadingState`, `errorState`
+- **Bulk Operations**: `bulkActions`, `selectAllCheckbox`, `bulkDeleteButton`, `bulkExportButton`
+
+## Theme Options
+
+### Color Schemes
+- `blue` (default)
+- `purple`
+- `green`
+- `orange`
+- `red`
+- `gray`
+
+### Layout Options
+
+**AgentSession Layouts:**
+- `list` - Vertical list layout
+- `grid` - Grid layout for sessions
+- `compact` - Condensed view
+
+**AgentTrace Layouts:**
+- `timeline` - Timeline visualization
+- `tree` - Tree structure
+- `table` - Tabular view
+- `graph` - Graph visualization
+
+## Best Practices
+
+1. **Consistent Color Schemes**: Use the same color scheme across related components
+2. **Responsive Design**: Test customizations across different screen sizes
+3. **Accessibility**: Ensure sufficient color contrast and readable fonts
+4. **Performance**: Avoid overly complex styling that might impact performance
+5. **Maintainability**: Use design tokens from the app-studio color system
+
+## Examples
+
+See the enhanced examples in each component's `examples/default.tsx` file for comprehensive demonstrations of all customization options.

package/docs/adk-customization-summary.md

@@ -0,0 +1,157 @@
+# ADK Components Customization Enhancement Summary
+
+## Overview
+
+The ADK components have been enhanced with comprehensive customization capabilities through expanded `views` props and new container customization options. This provides developers with granular control over every aspect of the component appearance and behavior.
+
+## Key Enhancements
+
+### 1. Enhanced Views Props
+
+All ADK components now support significantly more granular customization through expanded `views` interfaces:
+
+#### AgentChat Views (40+ customizable parts)
+- **Main Areas**: container, header, messageList, inputArea, attachmentArea
+- **Message Components**: userMessage, botMessage, systemMessage, messageContent, messageTimestamp, messageAvatar, messageActions
+- **Input Components**: inputField, sendButton, attachButton, recordButton, inputToolbar
+- **State Indicators**: loadingIndicator, typingIndicator, errorMessage, emptyState
+- **Feature Components**: functionCall, functionResponse, codeBlock, codeOutput, thoughtBubble
+- **Attachment Components**: attachmentPreview, attachmentItem, attachmentRemoveButton
+
+#### AgentSession Views (40+ customizable parts)
+- **Main Areas**: container, header, toolbar, sessionList, sessionActions, filtersPanel
+- **Session Items**: sessionItem, activeSessionItem, sessionInfo, sessionTitle, sessionDescription, sessionMetadata, sessionTimestamp, sessionTags, sessionStats
+- **Action Buttons**: createButton, deleteButton, exportButton, importButton, refreshButton, selectButton, duplicateButton
+- **Search/Filter**: searchInput, filterDropdown, sortDropdown, dateRangePicker, tagFilter
+- **Bulk Operations**: bulkActions, selectAllCheckbox, bulkDeleteButton, bulkExportButton
+
+#### AgentEval Views (50+ customizable parts)
+- **Main Areas**: container, header, toolbar, evaluationList, createPanel, resultsPanel, metricsPanel
+- **Evaluation Items**: evaluationItem, activeEvaluationItem, evaluationTitle, evaluationStatus, evaluationProgress
+- **Test Cases**: testCaseList, testCaseItem, testCaseInput, testCaseOutput, testCaseResult
+- **Progress/Status**: progressBar, statusIndicator, statusBadge, scoreDisplay, durationDisplay
+- **Visualization**: chartContainer, metricsChart, resultsTable, summaryCard
+
+#### AgentTrace Views (50+ customizable parts)
+- **Main Areas**: container, header, toolbar, timeline, eventList, detailsPanel, metricsPanel
+- **Event Components**: eventItem, selectedEventItem, eventHeader, eventContent, eventMetadata
+- **Timeline**: timelineContainer, timelineAxis, timelineEvent, timelineSpan, timelineMarker
+- **Metrics**: metricsCard, performanceChart, errorRateChart, latencyChart, throughputChart
+- **Visualization**: flowDiagram, dependencyGraph, heatmap
+
+### 2. Container Props Support
+
+All components now accept `containerProps` for direct styling of the main container:
+
+```tsx
+<AgentChat
+  containerProps={{
+    backgroundColor: 'color.purple.25',
+    border: '2px solid',
+    borderColor: 'color.purple.300',
+    borderRadius: '12px',
+  }}
+/>
+```
+
+### 3. Theme and Appearance Props
+
+New theme-related props for consistent styling:
+
+- **colorScheme**: `'blue' | 'purple' | 'green' | 'orange' | 'red' | 'gray'`
+- **layout**: Component-specific layout options
+- **compact**: Boolean for condensed layouts
+- **rounded**: Boolean for rounded corners
+- **showPreviews**: Boolean for preview features
+
+### 4. Dynamic Styling
+
+Components now include dynamic styling functions that apply theme-based styles automatically:
+
+```tsx
+const getThemeStyles = () => {
+  const colorStyles = {
+    blue: { borderColor: 'color.blue.200' },
+    purple: { borderColor: 'color.purple.200' },
+    // ... other colors
+  };
+  return colorStyles[colorScheme];
+};
+```
+
+## Implementation Details
+
+### File Changes
+
+1. **Props Interfaces Enhanced**:
+   - `AgentChat/AgentChat.props.ts` - Expanded AgentChatViews interface
+   - `AgentSession/AgentSession.props.ts` - Expanded AgentSessionViews interface
+   - `AgentEval/AgentEval.props.ts` - Expanded AgentEvalViews interface
+   - `AgentTrace/AgentTrace.props.ts` - Expanded AgentTraceViews interface
+
+2. **View Components Updated**:
+   - `AgentChat/AgentChat.view.tsx` - Added theme support and containerProps
+   - `AgentSession/AgentSession.view.tsx` - Added theme support and containerProps
+
+3. **Examples Enhanced**:
+   - `AgentChat/examples/default.tsx` - Comprehensive customization example
+   - `AgentSession/examples/default.tsx` - Enhanced customization example
+
+4. **Documentation Created**:
+   - `docs/adk-customization-guide.md` - Complete customization guide
+   - `docs/adk-customization-summary.md` - This summary document
+
+## Usage Examples
+
+### Basic Customization
+```tsx
+<AgentChat
+  appName="my-agent"
+  userId="user123"
+  colorScheme="purple"
+  views={{
+    userMessage: { backgroundColor: 'color.purple.500' },
+    botMessage: { backgroundColor: 'color.purple.100' },
+  }}
+/>
+```
+
+### Advanced Customization
+```tsx
+<AgentSession
+  appName="my-agent"
+  userId="user123"
+  colorScheme="green"
+  layout="grid"
+  containerProps={{ backgroundColor: 'color.green.25' }}
+  views={{
+    sessionItem: {
+      backgroundColor: 'color.green.50',
+      borderRadius: '8px',
+      padding: '12px',
+    },
+    activeSessionItem: {
+      backgroundColor: 'color.green.100',
+      borderColor: 'color.green.500',
+    },
+  }}
+/>
+```
+
+## Benefits
+
+1. **Complete Control**: Developers can customize every visual aspect of the components
+2. **Consistent Theming**: Built-in color schemes ensure visual consistency
+3. **Responsive Design**: Components adapt to different layouts and screen sizes
+4. **Maintainable**: Uses app-studio design tokens for consistent styling
+5. **Flexible**: Supports both simple theme-based and complex custom styling
+
+## Next Steps
+
+The enhanced customization system provides a solid foundation for:
+- Creating branded component themes
+- Building custom layouts and designs
+- Implementing responsive component behaviors
+- Maintaining visual consistency across applications
+
+All components are now ready for comprehensive customization while maintaining their core functionality and accessibility features.

package/docs/documentation-system.md

@@ -104,8 +104,50 @@ To update component documentation:
 2. Review the generated documentation
 3. Make any necessary manual adjustments
 
+## Documentation Maintenance Rules
+
+### Rule 1: Single Source of Truth
+- Each topic should have ONE authoritative documentation file
+- Avoid duplicating content across multiple files
+- Use cross-references instead of copying content
+- **Prohibited**: Creating multiple files covering the same topic
+
+### Rule 2: Clear File Responsibilities
+- **README.md**: Project overview, quick start, navigation to specialized docs
+- **README-ADK.md**: ADK-specific functionality ONLY
+- **docs/README.md**: Documentation hub and navigation
+- **docs/api-integration.md**: Backend integration patterns
+- **Component docs**: Individual component usage and APIs
+
+### Rule 3: Content Validation Checklist
+Before adding/updating documentation:
+- ✅ Check for existing content on the same topic
+- ✅ Verify all code examples work
+- ✅ Ensure links are valid and up-to-date
+- ✅ Follow consistent markdown formatting
+- ✅ Update related files if needed
+- ✅ Remove outdated information
+
+### Rule 4: Mandatory Updates
+Documentation MUST be updated when:
+- Adding new components or features
+- Changing component APIs or props
+- Modifying integration patterns
+- Updating dependencies or requirements
+- Changing project structure
+
+### Rule 5: Quality Standards
+- Use clear, concise language
+- Include practical, working examples
+- Follow consistent formatting and terminology
+- Link related documentation appropriately
+- Test all code examples before publishing
+- Include accessibility information where relevant
+- Document best practices and common pitfalls
+
 ## Documentation Best Practices
 
+### Content Organization
 - Keep documentation up-to-date with code changes
 - Include examples for all components and features
 - Use consistent formatting and terminology
@@ -114,6 +156,45 @@ To update component documentation:
 - Include accessibility information
 - Document best practices and common pitfalls
 
+### File Naming Conventions
+- Use kebab-case for file names: `component-development.md`
+- Use descriptive names that clearly indicate content
+- Avoid generic names like `guide.md` or `docs.md`
+
+## Documentation Maintenance Workflow
+
+### Before Making Changes
+1. **Audit existing documentation**:
+   ```bash
+   # Check for duplicate content
+   grep -r "your-search-term" docs/
+
+   # Find broken links
+   find docs/ -name "*.md" -exec grep -l "broken-link" {} \;
+   ```
+
+2. **Validate current structure**:
+   - Ensure no topic is covered in multiple files
+   - Check that all links work
+   - Verify code examples are current
+
+### After Making Changes
+1. **Update related documentation**:
+   - Update cross-references
+   - Check for outdated information
+   - Ensure consistency across files
+
+2. **Run documentation tools**:
+   ```bash
+   npm run create-docs
+   npm run bot-doc -- ComponentName src/components/ComponentName
+   ```
+
+### Regular Maintenance Tasks
+- **Weekly**: Check for broken links and outdated examples
+- **Monthly**: Review documentation structure for redundancies
+- **Per Release**: Update all version-specific information
+
 ## Troubleshooting
 
 If you encounter issues with the documentation system:
@@ -141,3 +222,12 @@ If MDX files are not rendering correctly:
 1. Check the MDX syntax
 2. Ensure the MDX file is in the correct location
 3. Check for errors in the console
+
+### Duplicate Content Issues
+
+If you find duplicate content:
+
+1. Identify the authoritative source
+2. Remove duplicate content
+3. Add cross-references to the authoritative source
+4. Update any links pointing to removed content

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@app-studio/web",
-  "version": "0.9.20",
+  "version": "0.9.22",
   "main": "dist/index.js",
   "typings": "dist/components/index.d.ts",
   "files": [
@@ -46,6 +46,7 @@
     "create-example": "ts-node scripts/create-example.ts",
     "page-imports": "ts-node scripts/generate-page-imports.ts",
     "create-pages": "npm run create-indices && ts-node scripts/create-pages.ts && npm run page-imports",
+    "validate-docs": "node scripts/validate-docs.js",
     "api:local": "react-api  --useUnionTypes --input http://localhost:3000/docs/swagger.json --output ./src/services/api  && prettier --write ./src/services/api"
   },
   "eslintConfig": {

package/dist/services/api/models/CreateApplicationParams.d.ts

@@ -1,10 +0,0 @@
-export declare type CreateApplicationParams = {
-    /**
-     * Grant Id to be assigned to the application to be created.
-     */
-    grantId?: string;
-    /**
-     * Project Id to be assigned to the application to be created.
-     */
-    projectId?: string;
-};

package/dist/services/api/models/CreateGrantParams.d.ts

@@ -1,10 +0,0 @@
-export declare type CreateGrantParams = {
-    /**
-     * The title of the grant to be created.
-     */
-    name: string;
-    /**
-     * The project Id of the grant
-     */
-    projectId: string;
-};

package/dist/services/api/models/CreateProjectParams.d.ts

@@ -1,10 +0,0 @@
-export declare type CreateProjectParams = {
-    /**
-     * The name of the project to be created.
-     */
-    name: string;
-    /**
-     * The description of the project to be created.
-     */
-    description?: string;
-};

package/dist/services/api/models/FindApplicationParams.d.ts

@@ -1,19 +0,0 @@
-export declare type FindApplicationParams = {
-    name?: string;
-    /**
-     * Order by field
-     */
-    sortField?: 'id' | 'userId' | 'name' | 'imageUrl' | 'image' | 'createdAt' | 'updatedAt';
-    /**
-     * Order sort
-     */
-    sortOrder?: 'asc' | 'desc';
-    /**
-     * Number or result to return
-     */
-    take?: number;
-    /**
-     * Number or result to skip
-     */
-    skip?: number;
-};

package/dist/services/api/models/FindPageParams.d.ts

@@ -1,22 +0,0 @@
-export declare type FindPageParams = {
-    /**
-     * Page Id
-     */
-    projectId: string;
-    /**
-     * Order by field
-     */
-    sortField?: string;
-    /**
-     * Order sort
-     */
-    sortOrder?: string;
-    /**
-     * Number or result to return
-     */
-    take?: number;
-    /**
-     * Number or result to skip
-     */
-    skip?: number;
-};

package/dist/services/api/models/FixPageParams.d.ts

@@ -1,10 +0,0 @@
-export declare type FixPageParams = {
-    /**
-     * User requirement
-     */
-    prompt: string;
-    /**
-     * Selected Html Element
-     */
-    html: string;
-};

package/dist/services/api/models/UpdateApplicationParams.d.ts

@@ -1,6 +0,0 @@
-export declare type UpdateApplicationParams = {
-    /**
-     * Application title
-     */
-    name: string;
-};

package/dist/services/api/models/UpdateComponentPropsParams.d.ts

@@ -1,10 +0,0 @@
-export declare type UpdateComponentPropsParams = {
-    /**
-     * Prompt
-     */
-    prompt: string;
-    /**
-     * Json Content
-     */
-    json: any;
-};

package/dist/services/api/models/UpdateGrantParams.d.ts

@@ -1,6 +0,0 @@
-export declare type UpdateGrantParams = {
-    /**
-     * Grant title
-     */
-    name: string;
-};

package/dist/services/api/models/UpdatePageParams.d.ts

@@ -1,14 +0,0 @@
-export declare type UpdatePageParams = {
-    /**
-     * The code to be associated with the page
-     */
-    code?: string;
-    /**
-     * The configs to be associated with the page
-     */
-    configs?: Array<string>;
-    /**
-     * The url to be associated with the page
-     */
-    urlPath?: string;
-};

package/dist/services/api/models/UpdateProjectParams.d.ts

@@ -1,10 +0,0 @@
-export declare type UpdateProjectParams = {
-    /**
-     * Project title
-     */
-    name: string;
-    /**
-     * Project workers
-     */
-    workers: Array<string>;
-};