Merge pull request #473 from objectstack-ai/copilot/complete-development-roadmap-another-one

Author: hotlong

MIGRATION_GUIDE.md

@@ -0,0 +1,230 @@
+# Migration Guide
+
+## Migrating to v3.0.0
+
+This guide covers migrating from `@objectstack/spec` v2.x to v3.0.0 and from `@objectstack/client` v2.x to v3.0.0. These are the upstream dependencies that ObjectUI builds on — if you use ObjectUI with ObjectStack, follow these steps when upgrading.
+
+> **Tip:** The v3.0.0 migration in ObjectUI is complete (see [CHANGELOG.md](./CHANGELOG.md)). This guide helps you migrate your own application code.
+
+---
+
+### Breaking Changes
+
+| Change | v2.x | v3.0.0 |
+|--------|------|--------|
+| **Namespace rename** | `Hub` | `Cloud` |
+| **Plugin definition** | `definePlugin()` | Removed — use `defineStack()` only |
+| **Paginated results** | `.value` / `.count` | `.records` / `.total` (+ `.hasMore`) |
+| **Metadata API** | `client.meta.getObject(name)` | `client.meta.getItem('object', name)` |
+| **New modules** | — | `contracts`, `integration`, `security`, `studio` |
+
+---
+
+### Step-by-Step Migration
+
+#### 1. Update Dependencies
+
+```bash
+# Update all @objectstack packages to v3.0.0
+npm install @objectstack/spec@^3.0.0 @objectstack/client@^3.0.0
+# or with pnpm
+pnpm add @objectstack/spec@^3.0.0 @objectstack/client@^3.0.0
+```
+
+#### 2. Replace Hub → Cloud Namespace
+
+Search your codebase for `Hub` namespace references and replace with `Cloud`:
+
+```typescript
+// ❌ v2.x
+import { Hub } from '@objectstack/spec';
+
+// ✅ v3.0.0
+import { Cloud } from '@objectstack/spec';
+```
+
+#### 3. Replace definePlugin → defineStack
+
+`definePlugin()` has been removed. Use `defineStack()` for all configuration, including plugins, apps, objects, and dashboards.
+
+```typescript
+// ❌ v2.x
+import { definePlugin } from '@objectstack/spec';
+export default definePlugin({ name: 'my-plugin', objects: [/* ... */] });
+
+// ✅ v3.0.0
+import { defineStack } from '@objectstack/spec';
+export default defineStack({
+  manifest: { id: 'my-app', name: 'my_app', version: '1.0.0', type: 'app' },
+  objects: [/* ... */],
+  apps: [/* ... */],
+});
+```
+
+#### 4. Update PaginatedResult Fields
+
+All paginated responses now use `.records` and `.total` instead of `.value` and `.count`. The new `.hasMore` boolean simplifies infinite-scroll patterns.
+
+```typescript
+// ❌ v2.x
+const result = await client.data.find('accounts', query);
+const items = result.value;    // array of records
+const count = result.count;    // total count
+
+// ✅ v3.0.0
+const result = await client.data.find('accounts', query);
+const items = result.records;  // array of records
+const count = result.total;    // total count
+const more = result.hasMore;   // boolean — are there more pages?
+```
+
+If you have custom data adapters, update all references:
+
+```typescript
+// ❌ v2.x adapter
+return { data: response.value, total: response.count };
+
+// ✅ v3.0.0 adapter
+return { data: response.records, total: response.total };
+```
+
+#### 5. Update Metadata API Calls
+
+The `meta.getObject()` convenience method is replaced by the unified `meta.getItem()` API.
+
+```typescript
+// ❌ v2.x
+const schema = await client.meta.getObject('account');
+
+// ✅ v3.0.0
+const schema = await client.meta.getItem('object', 'account');
+```
+
+Other metadata patterns:
+
+```typescript
+const view = await client.meta.getItem('account', 'views/list');  // view definition
+const app = await client.meta.getItem('apps', 'crm');             // app definition
+```
+
+---
+
+### API Quick Reference
+
+```typescript
+// Hub → Cloud
+Hub.*                  → Cloud.*
+
+// definePlugin → defineStack
+definePlugin({ ... })  → defineStack({ manifest: { ... }, objects: [...] })
+
+// PaginatedResult
+result.value           → result.records
+result.count           → result.total
+/* new */                 result.hasMore
+
+// Metadata API
+meta.getObject(name)   → meta.getItem('object', name)
+```
+
+---
+
+### New Features in v3.0.0
+
+#### Contracts Module
+
+Validate plugin contracts and generate manifests for the marketplace:
+
+```typescript
+import { validatePluginContract, generateContractManifest } from './contracts';
+
+const result = validatePluginContract({
+  name: 'my-plugin',
+  version: '1.0.0',
+  exports: [{ name: 'GridView', type: 'component' }],
+  permissions: ['data.read'],
+});
+// result.valid === true, result.errors === []
+```
+
+#### Integration Module
+
+Register external service integrations with event-driven triggers:
+
+```typescript
+import { IntegrationManager } from './integration';
+
+const manager = new IntegrationManager();
+manager.register('slack-notify', {
+  provider: 'slack',
+  enabled: true,
+  config: { webhookUrl: 'https://hooks.slack.com/...' },
+  triggers: [{ event: 'record.created' }],
+});
+```
+
+#### Security Module
+
+CSP headers, audit logging, and field-level data masking:
+
+```typescript
+import { SecurityManager } from './security';
+
+const security = new SecurityManager({
+  csp: { scriptSrc: ["'self'"], connectSrc: ["'self'", 'https://api.example.com'] },
+  dataMasking: {
+    rules: [
+      { field: 'ssn', strategy: 'partial', visibleChars: 4 },
+      { field: 'password', strategy: 'redact' },
+    ],
+  },
+});
+const masked = security.maskRecord({ ssn: '123-45-6789', password: 'secret' });
+// masked.ssn === '123-*******', masked.password === '[REDACTED]'
+```
+
+#### Studio Module
+
+Canvas configuration helpers for visual designers:
+
+```typescript
+import { createDefaultCanvasConfig, snapToGrid } from './studio';
+
+const canvas = createDefaultCanvasConfig({ width: 1600, showMinimap: true });
+const snapped = snapToGrid(13, 27, 8); // { x: 16, y: 24 }
+```
+
+---
+
+### Troubleshooting
+
+#### `definePlugin is not a function`
+
+`definePlugin` was removed in v3.0.0. Replace all usages with `defineStack()`. See [Step 3](#3-replace-defineplugin--definestack) above.
+
+#### `result.value is undefined` in data grids
+
+Paginated results no longer have `.value`. Update to `.records`:
+
+```bash
+grep -rn '\.value' --include='*.ts' --include='*.tsx' | grep -i 'result\|response\|paginated'
+```
+
+#### `client.meta.getObject is not a function`
+
+The `getObject()` method was replaced by the unified `getItem()` API. See [Step 5](#5-update-metadata-api-calls).
+
+#### TypeScript errors after upgrade
+
+Ensure all `@objectstack/*` packages are on v3.0.0. Mixing v2 and v3 packages causes type conflicts:
+
+```bash
+npm ls @objectstack/spec @objectstack/client
+```
+
+#### Further Resources
+
+- [CHANGELOG.md](./CHANGELOG.md) — Full list of changes in each release
+- [ROADMAP.md](./ROADMAP.md) — Current development priorities
+- [SPEC_COMPLIANCE_EVALUATION.md](./SPEC_COMPLIANCE_EVALUATION.md) — Per-package v3.0.0 compliance status
+- [OBJECTSTACK_CLIENT_EVALUATION.md](./OBJECTSTACK_CLIENT_EVALUATION.md) — Client SDK evaluation

ROADMAP.md

@@ -135,23 +135,23 @@ All 4 phases complete across 5 designers (Page, View, DataModel, Process, Report
 **Goal:** A developer can go from `git clone` to a running app in under 5 minutes, with discoverable APIs, helpful errors, and complete documentation at every step.
 
 #### P1.1 Zero-Friction Onboarding
-- [ ] Create MIGRATION_GUIDE.md at repo root (currently referenced in README but missing)
+- [x] Create MIGRATION_GUIDE.md at repo root (currently referenced in README but missing)
 - [ ] Streamline `npx create-objectui-app` scaffolding with working Vite + Tailwind templates
 - [ ] Ensure `pnpm install && pnpm dev` starts the console with zero additional configuration
-- [ ] Add a standalone "Hello World" example (5-file, <50 lines total) demonstrating JSON → UI flow
+- [x] Add a standalone "Hello World" example (5-file, <50 lines total) demonstrating JSON → UI flow
 - [ ] Provide copy-paste-ready schema examples in the root README for instant gratification
 
 #### P1.2 API Discoverability & JSDoc
-- [ ] Add JSDoc comments to all 20+ exported React hooks (`useExpression`, `useActionRunner`, `useViewData`, `useDynamicApp`, `usePerformance`, `useCrudShortcuts`, etc.)
-- [ ] Add JSDoc with usage examples to key types in `@object-ui/types` (`SchemaNode`, `FieldMetadata`, `ViewSchema`, `ActionSchema`, etc.)
+- [x] Add JSDoc comments to all 20+ exported React hooks (`useExpression`, `useActionRunner`, `useViewData`, `useDynamicApp`, `usePerformance`, `useCrudShortcuts`, etc.)
+- [x] Add JSDoc with usage examples to key types in `@object-ui/types` (`SchemaNode`, `FieldMetadata`, `ViewSchema`, `ActionSchema`, etc.)
 - [ ] Document all context providers (`ThemeContext`, `AuthContext`, `I18nContext`, `NotificationContext`, `DndContext`) with usage examples
 - [ ] Ensure TypeScript autocompletion works smoothly for all schema types via strict discriminated unions
 
 #### P1.3 Error Messages & Debugging
-- [ ] Create error code system (`OBJUI-001`, `OBJUI-002`, etc.) with documentation links
-- [ ] Improve SchemaErrorBoundary to show actionable fix suggestions in dev mode (e.g., "Missing field 'type'. Did you mean to use a PageSchema?")
-- [ ] Replace generic `console.warn()` calls in core with structured error factory
-- [ ] Add `OBJECTUI_DEBUG=true` mode with schema resolution tracing and component render timing
+- [x] Create error code system (`OBJUI-001`, `OBJUI-002`, etc.) with documentation links
+- [x] Improve SchemaErrorBoundary to show actionable fix suggestions in dev mode (e.g., "Missing field 'type'. Did you mean to use a PageSchema?")
+- [x] Replace generic `console.warn()` calls in core with structured error factory
+- [x] Add `OBJECTUI_DEBUG=true` mode with schema resolution tracing and component render timing
 - [ ] Ensure console warnings for deprecated APIs include migration code snippets
 
 #### P1.4 CLI Tooling Polish
@@ -162,16 +162,16 @@ All 4 phases complete across 5 designers (Page, View, DataModel, Process, Report
 - [ ] Resolve 8 TODO/FIXME items in CLI code (`doctor.ts`, `dev.ts`, `check.ts`)
 
 #### P1.5 Package READMEs (10 Missing)
-- [ ] Add README for `@object-ui/auth` — authentication guards, login/register forms, AuthContext
-- [ ] Add README for `@object-ui/tenant` — multi-tenancy support, TenantProvider, branding
-- [ ] Add README for `@object-ui/permissions` — RBAC, PermissionGuard, usePermissions hook
-- [ ] Add README for `@object-ui/i18n` — 11 locales, RTL support, I18nProvider, formatting utilities
-- [ ] Add README for `@object-ui/mobile` — responsive hooks, gesture support, touch optimization
-- [ ] Add README for `@object-ui/collaboration` — live cursors, presence, comment threads, conflict resolution
-- [ ] Add README for `@object-ui/plugin-ai` — AI form assistance, recommendations, NL query
-- [ ] Add README for `@object-ui/plugin-designer` — 5 visual designers (Page, View, DataModel, Process, Report)
-- [ ] Add README for `@object-ui/plugin-workflow` — approval processes, workflow designer
-- [ ] Add README for `@object-ui/plugin-report` — report builder, viewer, exporter, scheduling
+- [x] Add README for `@object-ui/auth` — authentication guards, login/register forms, AuthContext
+- [x] Add README for `@object-ui/tenant` — multi-tenancy support, TenantProvider, branding
+- [x] Add README for `@object-ui/permissions` — RBAC, PermissionGuard, usePermissions hook
+- [x] Add README for `@object-ui/i18n` — 11 locales, RTL support, I18nProvider, formatting utilities
+- [x] Add README for `@object-ui/mobile` — responsive hooks, gesture support, touch optimization
+- [x] Add README for `@object-ui/collaboration` — live cursors, presence, comment threads, conflict resolution
+- [x] Add README for `@object-ui/plugin-ai` — AI form assistance, recommendations, NL query
+- [x] Add README for `@object-ui/plugin-designer` — 5 visual designers (Page, View, DataModel, Process, Report)
+- [x] Add README for `@object-ui/plugin-workflow` — approval processes, workflow designer
+- [x] Add README for `@object-ui/plugin-report` — report builder, viewer, exporter, scheduling
 
 ---
 
@@ -180,10 +180,10 @@ All 4 phases complete across 5 designers (Page, View, DataModel, Process, Report
 **Goal:** Every interaction in the Console and rendered UIs is fast, polished, accessible, and works flawlessly in all supported languages.
 
 #### P2.1 Console i18n Completeness
-- [ ] Migrate hardcoded strings in `LoadingScreen.tsx` to i18n keys ("ObjectStack Console", "Initializing application...")
-- [ ] Migrate hardcoded strings in `KeyboardShortcutsDialog.tsx` to i18n keys
+- [x] Migrate hardcoded strings in `LoadingScreen.tsx` to i18n keys ("ObjectStack Console", "Initializing application...")
+- [x] Migrate hardcoded strings in `KeyboardShortcutsDialog.tsx` to i18n keys
 - [ ] Audit all `apps/console/src/components/` for remaining hardcoded UI strings
-- [ ] Remove all Chinese UI strings; enforce English-only with i18n key lookups
+- [x] Remove all Chinese UI strings; enforce English-only with i18n key lookups
 - [ ] Add locale switcher to Console settings panel
 
 #### P2.2 Console Architecture Cleanup

apps/console/package.json

@@ -34,6 +34,7 @@
     "@object-ui/example-kitchen-sink": "workspace:*",
     "@object-ui/example-todo": "workspace:*",
     "@object-ui/fields": "workspace:*",
+    "@object-ui/i18n": "workspace:*",
     "@object-ui/layout": "workspace:*",
     "@object-ui/plugin-calendar": "workspace:*",
     "@object-ui/plugin-charts": "workspace:*",

apps/console/src/__tests__/KeyboardShortcuts.test.tsx

@@ -15,6 +15,34 @@ vi.mock('@object-ui/components', () => ({
   DialogDescription: ({ children }: any) => <p>{children}</p>,
 }));
 
+// Mock i18n — return the key's last segment as display text
+vi.mock('@object-ui/i18n', () => ({
+  useObjectTranslation: () => ({
+    t: (key: string) => {
+      const translations: Record<string, string> = {
+        'console.shortcuts.title': 'Keyboard Shortcuts',
+        'console.shortcuts.description': 'Quick reference for all available keyboard shortcuts.',
+        'console.shortcuts.groups.general': 'General',
+        'console.shortcuts.groups.navigation': 'Navigation',
+        'console.shortcuts.groups.dataViews': 'Data Views',
+        'console.shortcuts.groups.preferences': 'Preferences',
+        'console.shortcuts.openCommandPalette': 'Open command palette',
+        'console.shortcuts.showShortcuts': 'Show keyboard shortcuts',
+        'console.shortcuts.closeDialog': 'Close dialog / panel',
+        'console.shortcuts.toggleSidebar': 'Toggle sidebar',
+        'console.shortcuts.focusSearch': 'Focus search',
+        'console.shortcuts.createRecord': 'Create new record',
+        'console.shortcuts.refreshData': 'Refresh data',
+        'console.shortcuts.editRecord': 'Edit selected record',
+        'console.shortcuts.toggleDarkMode': 'Toggle dark mode',
+      };
+      return translations[key] ?? key;
+    },
+    language: 'en',
+    direction: 'ltr',
+  }),
+}));
+
 describe('KeyboardShortcutsDialog', () => {
   it('renders without errors', () => {
     const { container } = render(<KeyboardShortcutsDialog />);