Enhance Phase 2 schema documentation with use cases and improved overview

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

content/docs/core/app-schema.mdx

@@ -287,6 +287,16 @@ Use expression syntax to show/hide menu items based on user permissions:
 }
 ```
 
+## Use Cases
+
+AppSchema is ideal for:
+
+- **Multi-page applications** - Configure complex application structures with multiple routes
+- **Admin dashboards** - Create comprehensive admin panels with role-based navigation
+- **CRM systems** - Build customer relationship management interfaces
+- **Internal tools** - Develop enterprise internal tools with centralized navigation
+- **SaaS products** - Configure multi-tenant applications with customizable layouts
+
 ## Best Practices
 
 1. **Use semantic icons** - Choose Lucide icons that clearly represent the section

content/docs/core/enhanced-actions.mdx

@@ -403,6 +403,17 @@ if (result.success) {
 }
 ```
 
+## Use Cases
+
+Enhanced Actions are ideal for:
+
+- **API integration** - Connect to backend services and external APIs
+- **Multi-step processes** - Execute complex workflows with multiple stages
+- **Form submissions** - Handle form data with validation and callbacks
+- **Confirmation dialogs** - Add safety checks for critical operations
+- **Event tracking** - Monitor user interactions for analytics
+- **Batch operations** - Process multiple items in sequence or parallel
+
 ## Best Practices
 
 1. **Use confirm for destructive actions** - Always confirm delete, archive, etc.

content/docs/core/report-schema.mdx

@@ -391,6 +391,17 @@ if (result.success) {
 }
 ```
 
+## Use Cases
+
+ReportSchema is perfect for:
+
+- **Analytics dashboards** - Display key business metrics and KPIs
+- **Business intelligence** - Generate insights from operational data
+- **Automated reporting** - Schedule regular reports for stakeholders
+- **Data exports** - Provide data in multiple formats (PDF, Excel, CSV)
+- **Compliance reporting** - Generate audit trails and regulatory reports
+- **Executive summaries** - Create high-level overviews for management
+
 ## Best Practices
 
 1. **Use meaningful aggregations** - Choose aggregation types that make sense for the data

content/docs/core/theme-schema.mdx

@@ -352,6 +352,16 @@ if (result.success) {
 }
 ```
 
+## Use Cases
+
+ThemeSchema is perfect for:
+
+- **Brand consistency** - Maintain consistent visual identity across applications
+- **White-labeling** - Enable multi-tenant applications with custom branding
+- **Accessibility** - Provide light/dark modes for user preference
+- **Design systems** - Implement comprehensive design tokens
+- **A/B testing** - Test different color schemes and typography
+
 ## Best Practices
 
 1. **Use semantic colors** - Stick to the semantic color tokens for consistency

content/docs/guide/phase2-schemas.md

@@ -1,13 +1,23 @@
 ---
-title: "Phase 2 Schema Reference"
-description: "Complete reference for ObjectUI Phase 2 schemas including App, Theme, Reports, Blocks, and Enhanced Actions"
+title: "Phase 2 Schemas Overview"
+description: "Comprehensive overview of ObjectUI Phase 2 schemas for building enterprise applications"
 ---
 
-# Phase 2 Schema Reference
+# Phase 2 Schemas Overview
 
-ObjectUI Phase 2 introduces advanced schemas for enterprise applications, providing comprehensive solutions for theming, reporting, reusable components, and complex action workflows.
+ObjectUI Phase 2 introduces powerful new schemas that enable you to build sophisticated enterprise applications with advanced features like theming, reporting, reusable components, and complex workflows. This guide provides an overview of all Phase 2 schemas and helps you get started quickly.
 
-## New Schemas
+## What's New in Phase 2?
+
+Phase 2 brings enterprise-grade capabilities to ObjectUI, making it easier to build production-ready applications:
+
+- **Application Structure** - Define complete multi-page applications with navigation
+- **Dynamic Theming** - Brand your applications with custom themes and light/dark modes
+- **Advanced Actions** - Build complex workflows with API calls, chaining, and conditions
+- **Enterprise Reporting** - Generate, schedule, and export comprehensive reports
+- **Reusable Components** - Create and share component blocks across projects
+
+## Core Schemas
 
 ### Application Configuration
 
@@ -172,19 +182,23 @@ Advanced filtering interface with multiple field types.
 ### [Sort UI](/docs/components/sort-ui)
 Sort configuration with multiple fields.
 
-## Getting Started
+## Installation & Setup
 
-### Installation
+### Package Installation
 
-All Phase 2 schemas are included in `@object-ui/types`:
+All Phase 2 schemas are included in `@object-ui/types`. Install it in your project:
 
 ```bash
 npm install @object-ui/types
 # or
 pnpm add @object-ui/types
+# or
+yarn add @object-ui/types
 ```
 
-### Basic Usage
+### TypeScript Usage
+
+Import the type definitions you need:
 
 ```typescript
 import type { 
@@ -198,7 +212,7 @@ import type {
 
 ### Runtime Validation
 
-Use Zod schemas for runtime validation:
+For runtime validation, use the included Zod schemas:
 
 ```typescript
 import { 
@@ -212,18 +226,21 @@ import {
 const result = AppSchema.safeParse(myConfig);
 if (result.success) {
   // Valid configuration
+  const app = result.data;
 } else {
   // Handle validation errors
+  console.error(result.error);
 }
 ```
 
-## Examples
+## Quick Start Example
 
-### Complete Application
+Here's a complete example showing how to build a simple CRM application using Phase 2 schemas:
 
 ```typescript
 import type { AppSchema, ThemeSchema } from '@object-ui/types';
 
+// Define your application structure
 const app: AppSchema = {
   type: 'app',
   name: 'enterprise-crm',
@@ -259,6 +276,7 @@ const app: AppSchema = {
   ]
 };
 
+// Configure your theme
 const theme: ThemeSchema = {
   type: 'theme',
   mode: 'system',
@@ -272,52 +290,96 @@ const theme: ThemeSchema = {
 };
 ```
 
-## Migration Guide
+This creates a professional-looking CRM application with:
+- A sidebar layout with navigation menu
+- Sales section with leads and deals
+- User menu with profile and logout options
+- Professional theme with light/dark mode support
 
-If you're upgrading from Phase 1, here's what's new:
+## Upgrading from Phase 1
 
-### ActionSchema Enhancements
-- ✅ New `ajax`, `confirm`, `dialog` action types
-- ✅ Action chaining with `chain` array
-- ✅ Conditional execution with `condition`
-- ✅ Callbacks with `onSuccess` and `onFailure`
-- ✅ Tracking with `tracking` config
+If you're currently using ObjectUI Phase 1, here's what's new and how to upgrade:
 
 ### New Top-Level Schemas
-- ✅ `AppSchema` - Application configuration
-- ✅ `ThemeSchema` - Theming system
-- ✅ `ReportSchema` - Reporting system
-- ✅ `BlockSchema` - Reusable blocks
 
-### View Enhancements
-- ✅ `DetailViewSchema` - Rich detail pages
-- ✅ `ViewSwitcherSchema` - View mode toggling
-- ✅ `FilterUISchema` - Enhanced filtering
-- ✅ `SortUISchema` - Sort configuration
+Phase 2 introduces four new top-level schemas:
+
+- **`AppSchema`** - Define your entire application structure (new in Phase 2)
+- **`ThemeSchema`** - Configure themes and color palettes (new in Phase 2)
+- **`ReportSchema`** - Create data reports with aggregation (new in Phase 2)
+- **`BlockSchema`** - Build reusable component blocks (new in Phase 2)
+
+### Enhanced ActionSchema
+
+The `ActionSchema` has been significantly enhanced with:
+
+- ✅ New action types: `ajax`, `confirm`, `dialog`
+- ✅ Action chaining via the `chain` array (sequential or parallel)
+- ✅ Conditional execution with the `condition` property
+- ✅ Success/failure callbacks: `onSuccess` and `onFailure`
+- ✅ Event tracking with the `tracking` configuration
+- ✅ Automatic retry logic
+
+### New View Components
+
+Phase 2 includes enhanced view components:
 
-## Resources
+- **`DetailViewSchema`** - Rich detail pages with sections and tabs
+- **`ViewSwitcherSchema`** - Toggle between list, grid, kanban, calendar views
+- **`FilterUISchema`** - Advanced filtering interface
+- **`SortUISchema`** - Multi-field sort configuration
+
+### Backward Compatibility
+
+Phase 2 is fully backward compatible with Phase 1 schemas. You can:
+
+- Continue using existing Phase 1 schemas
+- Gradually adopt Phase 2 features
+- Mix Phase 1 and Phase 2 schemas in the same application
+
+### Migration Steps
+
+1. **Update package** - Install latest `@object-ui/types`
+   ```bash
+   npm install @object-ui/types@latest
+   ```
+
+2. **Add AppSchema** - Wrap your pages in an application structure (optional)
+   
+3. **Configure theme** - Add a ThemeSchema for consistent styling (optional)
+
+4. **Enhance actions** - Update critical actions to use new features like `confirm` and callbacks
+
+5. **Test thoroughly** - Verify all existing functionality works as expected
+
+## Learning Resources
 
 ### Documentation
-- [PHASE2_IMPLEMENTATION.md](https://github.com/objectstack-ai/objectui/blob/main/packages/types/PHASE2_IMPLEMENTATION.md) - Complete implementation guide
-- [PHASE2_QUICK_START.md](https://github.com/objectstack-ai/objectui/blob/main/PHASE2_QUICK_START.md) - Quick start guide
+- **[Implementation Guide](https://github.com/objectstack-ai/objectui/blob/main/packages/types/PHASE2_IMPLEMENTATION.md)** - Complete implementation details and technical specifications
+- **[Quick Start Guide](https://github.com/objectstack-ai/objectui/blob/main/PHASE2_QUICK_START.md)** - Step-by-step tutorial for getting started with Phase 2
 
 ### API Reference
-- [TypeScript Types](https://github.com/objectstack-ai/objectui/tree/main/packages/types/src)
-- [Zod Validation](https://github.com/objectstack-ai/objectui/tree/main/packages/types/src/zod)
+- **[TypeScript Types](https://github.com/objectstack-ai/objectui/tree/main/packages/types/src)** - Browse all type definitions
+- **[Zod Validation Schemas](https://github.com/objectstack-ai/objectui/tree/main/packages/types/src/zod)** - Runtime validation schemas
 
-### Examples
-- [Test Suite](https://github.com/objectstack-ai/objectui/blob/main/packages/types/src/__tests__/phase2-schemas.test.ts) - 40+ example configurations
+### Code Examples
+- **[Test Suite](https://github.com/objectstack-ai/objectui/blob/main/packages/types/src/__tests__/phase2-schemas.test.ts)** - 40+ working examples demonstrating all Phase 2 features
 
-## Support
+## Getting Help
 
-Need help? Check out:
-- [GitHub Issues](https://github.com/objectstack-ai/objectui/issues)
-- [Discussions](https://github.com/objectstack-ai/objectui/discussions)
-- [Documentation](https://objectui.com/docs)
+### Community Support
+- **[GitHub Discussions](https://github.com/objectstack-ai/objectui/discussions)** - Ask questions and share ideas
+- **[GitHub Issues](https://github.com/objectstack-ai/objectui/issues)** - Report bugs and request features
+
+### Official Documentation
+- **[Documentation Site](https://objectui.com/docs)** - Full documentation and guides
+- **[Schema Reference](/docs/core)** - Detailed schema documentation
 
 ## Next Steps
 
-1. Review individual schema documentation
-2. Check out the [Quick Start Guide](https://github.com/objectstack-ai/objectui/blob/main/PHASE2_QUICK_START.md)
-3. Explore [test examples](https://github.com/objectstack-ai/objectui/blob/main/packages/types/src/__tests__/phase2-schemas.test.ts)
-4. Build your first Phase 2 application!
+Ready to build with Phase 2? Here's what to do next:
+
+1. **[Review schema documentation](/docs/core)** - Learn about each schema in detail
+2. **[Try the Quick Start](https://github.com/objectstack-ai/objectui/blob/main/PHASE2_QUICK_START.md)** - Build your first Phase 2 application
+3. **[Explore examples](https://github.com/objectstack-ai/objectui/blob/main/packages/types/src/__tests__/phase2-schemas.test.ts)** - See real-world usage patterns
+4. **[Join the community](https://github.com/objectstack-ai/objectui/discussions)** - Connect with other developers