diff --git a/README.md b/README.md index dbd36330f..530900f56 100644 --- a/README.md +++ b/README.md @@ -318,36 +318,57 @@ class MyCustomDataSource implements DataSource { ## ๐Ÿ“š Documentation +Visit [**objectui.org**](https://www.objectui.org) for complete documentation. + ### Getting Started -- [Introduction](./docs/guide/introduction.md) - Learn what Object UI is and why it exists - [Quick Start](./docs/guide/quick-start.md) - Build your first app in 5 minutes - [Installation](./docs/guide/installation.md) - Detailed setup instructions -- [Visual Studio](./docs/guide/studio.md) - Use the drag-and-drop designer +- [Showcase](./docs/guide/showcase.md) - Interactive component gallery +- [CLI Guide](./docs/guide/cli/getting-started.md) - Using the ObjectUI CLI +- [Visual Studio](./docs/guide/studio.md) - Drag-and-drop designer ### Core Concepts -- [Schema Rendering](./docs/spec/schema-rendering.md) - Understand the rendering system -- [Architecture](./docs/spec/architecture.md) - Technical architecture overview -- [Component System](./docs/spec/component.md) - How components work - -### Data Integration -- [ObjectQL Integration](./docs/integration/objectql.md) - Connect to ObjectQL backends -- [Custom Data Sources](./packages/types/examples/rest-data-source.ts) - Build your own adapters +- [Schema Rendering](./docs/concepts/schema-rendering.md) - How the rendering system works +- [Expressions](./docs/concepts/expressions.md) - Dynamic values and conditions +- [Data Sources](./docs/concepts/data-source.md) - Connecting to APIs +- [Component Registry](./docs/concepts/component-registry.md) - Registering custom components +- [Plugins](./docs/concepts/plugins.md) - Extending ObjectUI -### Protocol Specifications -- [Protocol Overview](./docs/protocol/overview.md) - Complete protocol reference -- [Form Protocol](./docs/protocol/form.md) - Form schema specification -- [View Protocol](./docs/protocol/view.md) - Data view specifications -- [Page Protocol](./docs/protocol/page.md) - Page layout specifications +### Components & Plugins +- [Component Library](./docs/components/) - Browse all available components +- [Charts Plugin](./docs/plugins/plugin-charts.mdx) - Chart components +- [Kanban Plugin](./docs/plugins/plugin-kanban.mdx) - Kanban boards ### API Reference -- [Core API](./docs/api/core.md) - `@object-ui/core` API reference -- [React API](./docs/api/react.md) - `@object-ui/react` API reference -- [Components API](./docs/api/components.md) - Component library reference -- [Designer API](./docs/api/designer.md) - Visual designer API +- [Core API](./docs/reference/api/core.md) - `@object-ui/core` API +- [React API](./docs/reference/api/react.md) - `@object-ui/react` API +- [Components API](./docs/reference/api/components.md) - Component library API +- [Designer API](./docs/reference/api/designer.md) - Visual designer API -### Advanced -- [Lazy-Loaded Plugins](./docs/lazy-loaded-plugins.md) - Plugin architecture -- [Component Packages](./docs/spec/component-package.md) - Creating custom components +### Protocol Specifications +- [Protocol Overview](./docs/reference/protocol/overview.md) - Complete protocol reference +- [Page Protocol](./docs/reference/protocol/page.md) - Page schema specification +- [Form Protocol](./docs/reference/protocol/form.md) - Form schema specification +- [View Protocol](./docs/reference/protocol/view.md) - Data view specifications +- [CRUD Protocol](./docs/reference/protocol/crud.md) - CRUD operations + +### Architecture & Advanced +- [Architecture](./docs/architecture/architecture.md) - System architecture overview +- [Project Structure](./docs/architecture/project-structure.md) - Code organization +- [Component System](./docs/architecture/component.md) - How components work +- [Rendering Specification](./docs/architecture/rendering-specification.md) - Technical rendering spec + +### Ecosystem & Integration +- [ObjectQL Integration](./docs/ecosystem/objectql.md) - Connect to ObjectQL backends +- [API Integration](./docs/ecosystem/api.md) - REST API integration +- [Deployment](./docs/ecosystem/deployment/showcase-deployment.md) - Deploy to production + +### Support & Resources +- [FAQ](./docs/faq.md) - Frequently asked questions +- [Troubleshooting](./docs/troubleshooting/index.md) - Common issues and solutions +- [Security](./docs/security.md) - Security best practices +- [Migration Guide](./docs/migration/from-objectstack.md) - Migrating from ObjectStack +- [Examples](./docs/examples.md) - Learn from real-world examples ## ๐ŸŽฏ What Can You Build? @@ -405,7 +426,7 @@ pnpm designer ## ๐Ÿ›ฃ๏ธ Roadmap -See our [detailed roadmap](./docs/ROADMAP.md) for upcoming features and release timeline. +See our [detailed roadmap](./docs/community/roadmap.md) for upcoming features and release timeline. **Q1 2026** (Available March 2026): - โœ… Core schema rendering @@ -425,8 +446,9 @@ We welcome contributions! Please read our [Contributing Guide](./CONTRIBUTING.md ### For Developers -- ๐Ÿ“– [Quick Start for Developers](./docs/quick-start-dev.md) - Get started in 5 minutes -- ๐Ÿ“‹ [Development Plan](./docs/development-plan.md) - Current priorities and roadmap +- ๐Ÿ“– [Contributing Guide](./CONTRIBUTING.md) - How to contribute to the project +- ๐Ÿ—๏ธ [Architecture](./docs/architecture/architecture.md) - Technical architecture +- ๐Ÿ“š [Best Practices](./docs/community/best-practices.md) - Code quality guidelines ### Development Setup diff --git a/docs/community/architecture/specs/architecture.md b/docs/architecture/architecture.md similarity index 100% rename from docs/community/architecture/specs/architecture.md rename to docs/architecture/architecture.md diff --git a/docs/community/architecture/specs/base-components.md b/docs/architecture/base-components.md similarity index 100% rename from docs/community/architecture/specs/base-components.md rename to docs/architecture/base-components.md diff --git a/docs/community/architecture/specs/component-library.md b/docs/architecture/component-library.md similarity index 100% rename from docs/community/architecture/specs/component-library.md rename to docs/architecture/component-library.md diff --git a/docs/community/architecture/specs/component-package.md b/docs/architecture/component-package.md similarity index 100% rename from docs/community/architecture/specs/component-package.md rename to docs/architecture/component-package.md diff --git a/docs/community/architecture/specs/component.md b/docs/architecture/component.md similarity index 100% rename from docs/community/architecture/specs/component.md rename to docs/architecture/component.md diff --git a/docs/architecture/meta.json b/docs/architecture/meta.json new file mode 100644 index 000000000..c801f7923 --- /dev/null +++ b/docs/architecture/meta.json @@ -0,0 +1,12 @@ +{ + "title": "Architecture", + "pages": [ + "architecture", + "project-structure", + "rendering-specification", + "component", + "component-library", + "component-package", + "base-components" + ] +} diff --git a/docs/community/architecture/specs/project-structure.md b/docs/architecture/project-structure.md similarity index 100% rename from docs/community/architecture/specs/project-structure.md rename to docs/architecture/project-structure.md diff --git a/docs/community/architecture/specs/schema-rendering.md b/docs/architecture/rendering-specification.md similarity index 100% rename from docs/community/architecture/specs/schema-rendering.md rename to docs/architecture/rendering-specification.md diff --git a/docs/community/architecture/objectstack-spec-integration.md b/docs/community/architecture/objectstack-spec-integration.md deleted file mode 100644 index 0b841d973..000000000 --- a/docs/community/architecture/objectstack-spec-integration.md +++ /dev/null @@ -1,247 +0,0 @@ ---- -title: "Architecture: ObjectStack Spec Integration" ---- - -## Overview - -This document explains how ObjectUI integrates with `@objectstack/spec` (v0.1.1) as the foundational protocol for all UI components. - -## The Inheritance Chain - -``` -@objectstack/spec (v0.1.1) โ† The "Highest Law" - Universal Protocol - โ†“ -UIComponent โ† Base interface for all UI components - โ†“ -BaseSchema (@object-ui/types) โ† ObjectUI-specific extensions - โ†“ -Specific Schemas โ† Component implementations - โ†“ -Component Renderers โ† UI implementations -``` - -### 1. UIComponent (@objectstack/spec) - -The foundational interface that defines the core protocol for schema-driven UI: - -```typescript -interface UIComponent { - type: string; // Component type discriminator - id?: string; // Unique identifier - props?: Record; // Component-specific properties - children?: SchemaNode | SchemaNode[]; // Child content - [key: string]: any; // Extensibility -} -``` - -**Why this is the "highest law":** -- Defines the universal contract for all UI components -- Ensures interoperability across the ObjectStack ecosystem -- Provides the type discriminator pattern -- Enables JSON serialization - -### 2. BaseSchema (@object-ui/types) - -Extends `UIComponent` with ObjectUI-specific rendering logic: - -```typescript -interface BaseSchema extends UIComponent { - // Inherited from UIComponent - type: string; - id?: string; - children?: SchemaNode | SchemaNode[]; - - // ObjectUI extensions - className?: string; // Tailwind CSS classes - visible?: boolean; // Static visibility - visibleOn?: string; // Dynamic visibility (expression) - hidden?: boolean; // Static hiding - hiddenOn?: string; // Dynamic hiding (expression) - disabled?: boolean; // Static disabled state - disabledOn?: string; // Dynamic disabled state (expression) - - // Additional ObjectUI properties - name?: string; - label?: string; - description?: string; - placeholder?: string; - style?: Record; - data?: any; - body?: SchemaNode | SchemaNode[]; - testId?: string; - ariaLabel?: string; -} -``` - -### 3. Specific Schemas (e.g., ChartSchema) - -Component-specific interfaces that extend `BaseSchema`: - -```typescript -interface ChartSchema extends BaseSchema { - type: 'chart'; // Type discriminator - chartType: ChartType; // Chart-specific property - title?: string; - description?: string; - categories?: string[]; - series: ChartSeries[]; - height?: string | number; - showLegend?: boolean; - showGrid?: boolean; - animate?: boolean; - config?: Record; -} -``` - -## Data Display Components - -The following components are defined in `@object-ui/types/data-display`: - -| Type | Component | Schema Interface | Key Properties | -|------|-----------|-----------------|----------------| -| `alert` | Alert | `AlertSchema` | title, description, variant, icon, dismissible | -| `statistic` | Metric Card | `StatisticSchema` | label, value, trend, description, icon | -| `badge` | Badge | `BadgeSchema` | label, variant, icon | -| `avatar` | Avatar | `AvatarSchema` | src, alt, fallback, size, shape | -| `list` | List | `ListSchema` | items, ordered, dividers | -| `table` | Basic Table | `TableSchema` | columns, data, caption, hoverable | -| `data-table` | Data Grid | `DataTableSchema` | pagination, searchable, rowActions, selectable | -| `chart` | Chart | `ChartSchema` | chartType, series, categories, showLegend | -| `timeline` | Timeline | `TimelineSchema` | events, orientation, position | -| `tree-view` | Tree View | `TreeViewSchema` | data, multiSelect, showLines | -| `markdown` | Markdown | `MarkdownSchema` | content, sanitize | -| `html` | Raw HTML | `HtmlSchema` | html | - -## Usage Examples - -### 1. Simple Component (Compliant with UIComponent) - -```json -{ - "type": "badge", - "id": "status-badge", - "label": "New", - "variant": "default" -} -``` - -### 2. Component with ObjectUI Extensions - -```json -{ - "type": "alert", - "id": "welcome-alert", - "title": "Welcome!", - "description": "Thank you for using ObjectUI", - "variant": "default", - "icon": "info", - "dismissible": true, - "visibleOn": "${user.isNewUser}", - "className": "mb-4" -} -``` - -### 3. Complex Component with Children - -```json -{ - "type": "flex", - "id": "user-profile", - "props": { - "direction": "col", - "gap": 4 - }, - "children": [ - { - "type": "avatar", - "src": "https://github.com/shadcn.png", - "fallback": "JD", - "size": "lg" - }, - { - "type": "statistic", - "label": "Followers", - "value": "1,234", - "trend": "up" - }, - { - "type": "badge", - "label": "Pro Member", - "variant": "default" - } - ] -} -``` - -### 4. Data Display with Chart - -```json -{ - "type": "chart", - "id": "sales-chart", - "chartType": "bar", - "title": "Monthly Sales", - "categories": ["Jan", "Feb", "Mar", "Apr", "May", "Jun"], - "series": [ - { - "name": "Revenue", - "data": [12000, 15000, 18000, 14000, 22000, 25000], - "color": "#3b82f6" - } - ], - "showLegend": true, - "height": 400 -} -``` - -## Protocol Compliance Rules - -When creating or using components: - -1. โœ… **MUST** extend from `UIComponent` (directly or indirectly via `BaseSchema`) -2. โœ… **MUST** include a `type` field (the discriminator) -3. โœ… **MUST** use the correct type value from the component registry -4. โœ… **SHOULD** place component-specific properties at the top level (not in props) -5. โœ… **SHOULD** use `props` for standard HTML attributes (role, aria-*, data-*) -6. โœ… **SHOULD** support `children` for composable components -7. โœ… **SHOULD** support `id` for unique identification -8. โœ… **MAY** use ObjectUI extensions (className, visibleOn, etc.) - -### Property Placement Guide - -**Component-specific properties** โ†’ Top level: -```json -{ - "type": "alert", - "title": "Welcome", // โœ… Component-specific - "variant": "default", // โœ… Component-specific - "dismissible": true // โœ… Component-specific -} -``` - -**Standard HTML/ARIA attributes** โ†’ props object: -```json -{ - "type": "alert", - "title": "Welcome", - "props": { - "role": "alert", // โœ… HTML attribute - "aria-live": "polite", // โœ… ARIA attribute - "data-testid": "alert" // โœ… Data attribute - } -} -``` - -## Related Packages - -- **[@objectstack/spec](../../packages/objectstack-spec)** - Universal UI component specification -- **[@object-ui/types](../../packages/types)** - ObjectUI protocol extensions -- **[@object-ui/core](../../packages/core)** - Schema validation and expression engine -- **[@object-ui/react](../../packages/react)** - React renderer -- **[@object-ui/components](../../packages/components)** - Shadcn/Tailwind implementation - -## References - -- [ObjectStack Spec README](../../packages/objectstack-spec/README.md) -- [Object UI Types README](../../packages/types/README.md) -- [Data Display Examples](../../packages/types/examples/data-display-examples.json) diff --git a/docs/community/contributing/best-practices.md b/docs/community/best-practices.md similarity index 100% rename from docs/community/contributing/best-practices.md rename to docs/community/best-practices.md diff --git a/docs/community/contributing.md b/docs/community/contributing.md new file mode 100644 index 000000000..b63dd6350 --- /dev/null +++ b/docs/community/contributing.md @@ -0,0 +1,621 @@ +--- +title: "Contributing to ObjectUI" +description: "Guidelines and instructions for contributing to the ObjectUI project" +--- + +# Contributing to Object UI + +Thank you for your interest in contributing to Object UI! This document provides guidelines and instructions for contributing to the project. + +## Table of Contents + +- [Getting Started](#getting-started) +- [Development Setup](#development-setup) +- [Development Workflow](#development-workflow) +- [Architecture Overview](#architecture-overview) +- [Writing Tests](#writing-tests) +- [Code Style](#code-style) +- [Commit Guidelines](#commit-guidelines) +- [Pull Request Process](#pull-request-process) +- [Documentation](#documentation) +- [Adding Components](#adding-components) +- [Questions & Support](#questions--support) + +## Getting Started + +### Prerequisites + +- **Node.js** 18.0 or higher +- **pnpm** (recommended package manager) +- **Git** for version control +- Basic knowledge of React, TypeScript, and Tailwind CSS + +### Fork and Clone + +1. Fork the repository on GitHub +2. Clone your fork: + ```bash + git clone https://github.com/YOUR_USERNAME/objectui.git + cd objectui + ``` +3. Add upstream remote: + ```bash + git remote add upstream https://github.com/objectstack-ai/objectui.git + ``` + +## Development Setup + +### Install Dependencies + +```bash +# Install pnpm if you haven't +npm install -g pnpm + +# Install project dependencies +pnpm install +``` + +### Configure Git Merge Driver for pnpm-lock.yaml + +To prevent merge conflicts in `pnpm-lock.yaml`, configure the custom merge driver: + +```bash +# Set the merge driver name +git config merge.pnpm-merge.name "pnpm-lock.yaml merge driver" + +# Set the merge driver command +git config merge.pnpm-merge.driver "pnpm install" +``` + +This configuration allows Git to automatically resolve conflicts in `pnpm-lock.yaml` by regenerating the lockfile using `pnpm install` instead of attempting a manual merge. + +### Create a Branch + +```bash +# Sync with upstream +git fetch upstream +git checkout main +git merge upstream/main + +# Create a feature branch +git checkout -b feature/your-feature-name +``` + +## Development Workflow + +### Running Development Servers + +```bash +# Run the visual designer demo +pnpm designer + +# Run the prototype example +pnpm prototype + +# Run documentation site +pnpm docs:dev +``` + +### Building + +```bash +# Build all packages +pnpm build + +# Build specific package +cd packages/core && pnpm build +``` + +### Testing + +```bash +# Run all tests +pnpm test + +# Run tests in watch mode +pnpm test:watch + +# Run tests with UI (interactive) +pnpm test:ui + +# Generate coverage report +pnpm test:coverage +``` + +### Linting + +```bash +# Lint all packages +pnpm lint + +# Lint specific package +cd packages/react && pnpm lint +``` + +## Architecture Overview + +Object UI follows a modular monorepo architecture: + +``` +packages/ +โ”œโ”€โ”€ types/ # TypeScript type definitions (Zero dependencies) +โ”œโ”€โ”€ core/ # Core logic, validation, registry (Zero React) +โ”œโ”€โ”€ react/ # React bindings and SchemaRenderer +โ”œโ”€โ”€ components/ # UI components (Tailwind + Shadcn) +โ”œโ”€โ”€ designer/ # Visual schema editor +โ”œโ”€โ”€ plugin-charts/ # Chart components plugin +โ””โ”€โ”€ plugin-editor/ # Rich text editor plugin +``` + +### Key Principles + +1. **Protocol Agnostic**: Core never depends on specific backends +2. **Tailwind Native**: All styling via Tailwind utility classes +3. **Type Safety**: Strict TypeScript everywhere +4. **Tree Shakable**: Modular imports, no monolithic bundles +5. **Zero React in Core**: Core package has no React dependencies + +See [Architecture Documentation](./docs/spec/architecture.md) for details. + +## Writing Tests + +### Test Structure + +All tests should be placed in `__tests__` directories within the source code. We use **Vitest** and **React Testing Library**. + +```typescript +import { describe, it, expect } from 'vitest' +import { render, screen } from '@testing-library/react' +import { MyComponent } from './MyComponent' + +describe('MyComponent', () => { + it('should render correctly', () => { + render() + expect(screen.getByText('Expected Text')).toBeInTheDocument() + }) + + it('should handle user interaction', async () => { + const { user } = render() + await user.click(screen.getByRole('button')) + expect(screen.getByText('Clicked')).toBeInTheDocument() + }) +}) +``` + +### Testing Best Practices + +- Write tests for all new features +- Test user interactions, not implementation details +- Use meaningful test descriptions +- Aim for 80%+ code coverage +- Test edge cases and error states + +## Code Style + +### TypeScript Guidelines + +```typescript +// โœ… Good: Explicit types, clear naming +interface UserData { + id: string + name: string + email: string +} + +function getUserById(id: string): UserData | null { + // implementation +} + +// โŒ Bad: Implicit any, unclear naming +function get(x) { + // implementation +} +``` + +### React Component Guidelines + +```tsx +// โœ… Good: TypeScript, named exports, clear props +interface ButtonProps { + label: string + onClick: () => void + variant?: 'primary' | 'secondary' +} + +export function Button({ label, onClick, variant = 'primary' }: ButtonProps) { + return ( + + ) +} + +// โŒ Bad: No types, default export, inline styles +export default function Button(props) { + return +} +``` + +### Styling Guidelines + +- **Always use Tailwind**: Never use inline styles or CSS modules +- **Use `cn()` utility**: For conditional classes +- **Extract repeated classes**: Create reusable class combinations +- **Follow Shadcn patterns**: Match the style of existing components + +```tsx +// โœ… Good +
+ {children} +
+ +// โŒ Bad +
+ {children} +
+``` + +### General Guidelines + +- Use meaningful variable and function names +- Keep functions small and focused (< 50 lines) +- Add JSDoc comments for public APIs +- Avoid deep nesting (max 3 levels) +- Use early returns to reduce complexity + +## Commit Guidelines + +We follow [Conventional Commits](https://www.conventionalcommits.org/): + +### Commit Types + +- `feat:` - New features +- `fix:` - Bug fixes +- `docs:` - Documentation changes +- `test:` - Adding or updating tests +- `chore:` - Maintenance tasks (deps, config) +- `refactor:` - Code refactoring (no behavior change) +- `perf:` - Performance improvements +- `style:` - Code style changes (formatting) + +### Examples + +```bash +feat: add date picker component +fix: resolve schema validation error +docs: update installation guide +test: add tests for SchemaRenderer +chore: update dependencies +refactor: simplify expression evaluator +``` + +### Commit Message Format + +``` +: + + + +