From 706189e6350afdf94e761ce8f53cdee1c8fbc206 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 22 Jan 2026 08:45:07 +0000 Subject: [PATCH 1/6] Initial plan From ce779c7ea5a0811d759fe01fa08bf243693d8023 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 22 Jan 2026 08:53:52 +0000 Subject: [PATCH 2/6] docs: Major documentation structure optimization - Reorganize docs following industry best practices (Microsoft Docs, Stripe Docs) - Move architecture specs from community to dedicated /architecture folder - Create essential missing docs: FAQ, Troubleshooting, Security - Add Migration guide section - Simplify guide structure by removing redundant files - Update all meta.json files for better navigation - Consolidate community section - Improve main index page with clear navigation Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com> --- .../specs => architecture}/architecture.md | 0 .../specs => architecture}/base-components.md | 0 .../component-library.md | 0 .../component-package.md | 0 .../specs => architecture}/component.md | 0 docs/architecture/meta.json | 12 + .../project-structure.md | 0 .../rendering-specification.md} | 0 .../objectstack-spec-integration.md | 247 ----- .../{contributing => }/best-practices.md | 0 docs/community/contributing.md | 616 +++++++++++ docs/community/contributing/ai-guide.md | 148 --- .../contributing/development-plan.md | 849 ---------------- docs/community/contributing/pr-summary.md | 260 ----- docs/community/contributing/project-status.md | 409 -------- .../community/contributing/quick-start-dev.md | 224 ---- docs/community/meta.json | 3 +- docs/community/{contributing => }/roadmap.md | 0 docs/ecosystem/index.md | 274 +++++ docs/ecosystem/meta.json | 1 + docs/faq.md | 319 ++++++ docs/guide/components.md | 956 ------------------ docs/guide/interactive-demos.md | 216 ---- docs/guide/interactive-showcase.md | 572 ----------- docs/guide/meta.json | 6 +- docs/guide/try-it-online.md | 410 -------- docs/index.md | 338 +++---- docs/meta.json | 17 +- docs/migration/from-objectstack.md | 162 +++ docs/migration/meta.json | 6 + docs/reference/meta.json | 8 +- docs/security.md | 496 +++++++++ docs/troubleshooting/index.md | 552 ++++++++++ docs/troubleshooting/meta.json | 6 + 34 files changed, 2597 insertions(+), 4510 deletions(-) rename docs/{community/architecture/specs => architecture}/architecture.md (100%) rename docs/{community/architecture/specs => architecture}/base-components.md (100%) rename docs/{community/architecture/specs => architecture}/component-library.md (100%) rename docs/{community/architecture/specs => architecture}/component-package.md (100%) rename docs/{community/architecture/specs => architecture}/component.md (100%) create mode 100644 docs/architecture/meta.json rename docs/{community/architecture/specs => architecture}/project-structure.md (100%) rename docs/{community/architecture/specs/schema-rendering.md => architecture/rendering-specification.md} (100%) delete mode 100644 docs/community/architecture/objectstack-spec-integration.md rename docs/community/{contributing => }/best-practices.md (100%) create mode 100644 docs/community/contributing.md delete mode 100644 docs/community/contributing/ai-guide.md delete mode 100644 docs/community/contributing/development-plan.md delete mode 100644 docs/community/contributing/pr-summary.md delete mode 100644 docs/community/contributing/project-status.md delete mode 100644 docs/community/contributing/quick-start-dev.md rename docs/community/{contributing => }/roadmap.md (100%) create mode 100644 docs/ecosystem/index.md create mode 100644 docs/faq.md delete mode 100644 docs/guide/components.md delete mode 100644 docs/guide/interactive-demos.md delete mode 100644 docs/guide/interactive-showcase.md delete mode 100644 docs/guide/try-it-online.md create mode 100644 docs/migration/from-objectstack.md create mode 100644 docs/migration/meta.json create mode 100644 docs/security.md create mode 100644 docs/troubleshooting/index.md create mode 100644 docs/troubleshooting/meta.json 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..996422725 --- /dev/null +++ b/docs/community/contributing.md @@ -0,0 +1,616 @@ +# 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 + +``` +: + + + +