deskforge 1.0.0 → 1.0.1

package/IMPORT_GUIDE.md

@@ -0,0 +1,404 @@
+/**
+ * DeskForge - Import Guide
+ * 
+ * Comprehensive guide to importing from DeskForge packages
+ */
+
+# DeskForge Import Guide
+
+## Monorepo Structure
+
+DeskForge is organized as a monorepo with scoped packages under `@deskforge`:
+
+```
+packages/
+├── core/        → @deskforge/core
+├── ui/          → @deskforge/ui
+├── state/       → @deskforge/state
+├── router/      → @deskforge/router
+├── db/          → @deskforge/db
+├── notifications/ → @deskforge/notifications
+├── theme/       → @deskforge/theme
+├── file/        → @deskforge/file
+├── network/     → @deskforge/network
+├── ai/          → @deskforge/ai
+├── security/    → @deskforge/security
+├── bridge/      → @deskforge/bridge
+├── background/  → @deskforge/background
+├── payments/    → @deskforge/payments
+├── i18n/        → @deskforge/i18n
+├── logger/      → @deskforge/logger
+├── updater/     → @deskforge/updater
+├── cli/         → @deskforge/cli
+└── deskforge/   → Main barrel export (re-exports everything)
+```
+
+---
+
+## Import Patterns
+
+### Option 1: Import Everything from Main Package ⭐ Recommended for Most Apps
+
+```typescript
+import {
+  // UI Components
+  View,
+  Text,
+  Button,
+  FlatList,
+  
+  // State Management
+  State,
+  Computed,
+  Effect,
+  
+  // Other packages
+  DB,
+  Toast,
+  Router,
+} from 'deskforge'
+```
+
+**Use Case:** Simple apps that use multiple packages. One import statement gets everything.
+
+---
+
+### Option 2: Import from Specific Packages ⭐ Recommended for Libraries/Large Apps
+
+```typescript
+// UI Components
+import { View, Text, Button, StyleSheet } from '@deskforge/ui'
+
+// State Management
+import { State, Computed, Effect, Watch } from '@deskforge/state'
+
+// Router
+import { Router, Screen } from '@deskforge/router'
+
+// Database
+import { DB } from '@deskforge/db'
+
+// Notifications
+import { Toast, Notify } from '@deskforge/notifications'
+
+// Theme
+import { Theme } from '@deskforge/theme'
+
+// File System
+import { File } from '@deskforge/file'
+
+// Networking
+import { Network, P2P } from '@deskforge/network'
+
+// AI
+import { createBrain } from '@deskforge/ai'
+
+// Security
+import { Biometric, Encrypt } from '@deskforge/security'
+
+// Bridge
+import { Bridge } from '@deskforge/bridge'
+
+// Background Tasks
+import { Background, Schedule } from '@deskforge/background'
+
+// Payments
+import { Payment } from '@deskforge/payments'
+
+// Internationalization
+import { i18n } from '@deskforge/i18n'
+
+// Logger
+import { Logger } from '@deskforge/logger'
+
+// Updater
+import { Updater } from '@deskforge/updater'
+
+// CLI (Node.js/CLI contexts only)
+import { CLI } from '@deskforge/cli'
+```
+
+**Use Case:**
+- Large applications where you want explicit imports
+- Libraries where you need specific features
+- When you want to avoid loading unused code
+
+---
+
+## Common Import Patterns
+
+### Simple App
+
+```typescript
+import { View, Text, Button, State, StyleSheet } from 'deskforge'
+
+const MyApp = () => {
+  const state = State({ count: 0 })
+  
+  return View({ flex: 1 }, [
+    Text(`Count: ${state.count}`),
+    Button('Increment', {}, { onPress: () => state.count++ }),
+  ])
+}
+```
+
+### Complex App with Multiple Packages
+
+```typescript
+import {
+  View,
+  Text,
+  FlatList,
+  StyleSheet,
+  Platform,
+} from '@deskforge/ui'
+
+import {
+  State,
+  Computed,
+  Effect,
+} from '@deskforge/state'
+
+import { DB } from '@deskforge/db'
+import { Toast } from '@deskforge/notifications'
+import { Router } from '@deskforge/router'
+import { Theme } from '@deskforge/theme'
+
+export const ComplexApp = () => {
+  const state = State({ items: [], loading: false })
+  const itemCount = Computed(() => state.items.length)
+  
+  Effect(() => {
+    // Load items on mount
+    DB.query('items').then(items => {
+      state.items = items
+    })
+  })
+  
+  return View({ flex: 1 }, [
+    Text(`Items: ${itemCount.value}`),
+    FlatList(state.items, item => renderItem(item)),
+  ])
+}
+```
+
+### Library Using Specific Packages
+
+```typescript
+// utils.ts - Utility library
+import type { DFNode, StyleObject } from '@deskforge/ui'
+import { View } from '@deskforge/ui'
+import { State } from '@deskforge/state'
+
+export const createCounter = () => {
+  const state = State({ count: 0 })
+  
+  return {
+    get: () => state.count,
+    increment: () => state.count++,
+    decrement: () => state.count--,
+  }
+}
+```
+
+---
+
+## Type Imports
+
+### Import Types from Specific Packages
+
+```typescript
+import type {
+  DFNode,
+  StyleObject,
+  PressHandlers,
+  TextInputProps,
+  FlatListProps,
+} from '@deskforge/ui'
+
+import type {
+  StateProxy,
+  ComputedRef,
+  WatchHandle,
+  EffectHandle,
+} from '@deskforge/state'
+
+// Use types in your code
+const handler: PressHandlers = {
+  onPress: () => console.log('pressed'),
+}
+
+const style: StyleObject = {
+  flex: 1,
+  backgroundColor: '#fff',
+}
+```
+
+### Import Types from Main Package
+
+```typescript
+import type {
+  DFNode,
+  StyleObject,
+  PressHandlers,
+} from 'deskforge'
+```
+
+---
+
+## Tree-Shaking Friendly
+
+All imports are tree-shaking friendly. Only the code you import will be included in your bundle:
+
+```typescript
+// Only View, Text, and State will be bundled
+import { View, Text, State } from 'deskforge'
+
+// Router, DB, and other unused packages won't be included
+```
+
+---
+
+## Package Purposes
+
+| Package | Purpose | Common Exports |
+|---------|---------|----------------|
+| **@deskforge/ui** | UI Components | View, Text, Button, FlatList, etc. |
+| **@deskforge/state** | State Management | State, Computed, Effect, Watch, Ref |
+| **@deskforge/router** | Navigation | Router, Screen, Navigation |
+| **@deskforge/db** | Database | DB, query, insert, update, delete |
+| **@deskforge/notifications** | Alerts & Toasts | Toast, Push, SMS, Email |
+| **@deskforge/theme** | Theming | Theme, useTheme |
+| **@deskforge/file** | File Operations | File, read, write, delete |
+| **@deskforge/network** | Networking | Network, P2P, mDNS |
+| **@deskforge/ai** | AI Integration | createBrain, chat |
+| **@deskforge/security** | Security | Biometric, Encrypt, Decrypt |
+| **@deskforge/bridge** | Language Bridge | Bridge, call C/Go/Rust/etc |
+| **@deskforge/background** | Background Tasks | Background, Schedule |
+| **@deskforge/payments** | Payments | Payment, processPayment |
+| **@deskforge/i18n** | Translations | i18n, t, locale |
+| **@deskforge/logger** | Logging | Logger, log, warn, error |
+| **@deskforge/updater** | App Updates | Updater, checkUpdate |
+| **@deskforge/cli** | CLI Tools | CLI, command (Node only) |
+| **@deskforge/core** | Core Utilities | createNode, StyleSheet, DFNode |
+
+---
+
+## Best Practices
+
+### ✅ DO
+
+```typescript
+// Group imports by package
+import { View, Text, Button } from '@deskforge/ui'
+import { State, Computed } from '@deskforge/state'
+
+// Use specific imports
+import { View } from '@deskforge/ui'  // Good
+import * as ui from '@deskforge/ui'   // Also fine
+```
+
+### ❌ DON'T
+
+```typescript
+// Don't mix import styles in same file
+import { View } from '@deskforge/ui'
+import * as state from 'deskforge/state'  // Inconsistent
+
+// Don't use unscoped imports
+import { View } from 'deskforge/ui'       // Wrong
+import { State } from 'deskforge/state'   // Wrong
+```
+
+---
+
+## Monorepo Development
+
+If you're developing within the DeskForge monorepo:
+
+### Building Package After Changes
+
+```bash
+# Build UI package after changes
+yarn build @deskforge/ui
+
+# Build all packages
+yarn build
+
+# Build and watch
+yarn dev
+```
+
+### Testing Package Changes
+
+```bash
+# Test UI package
+yarn test @deskforge/ui
+
+# Test all
+yarn test
+```
+
+### Publishing Changes
+
+```bash
+# Publish all changed packages
+yarn publish
+
+# Publish specific package
+yarn publish @deskforge/ui
+```
+
+---
+
+## Environment-Specific Imports
+
+### Browser/Mobile App
+
+```typescript
+// Works everywhere
+import { View, Text, State } from 'deskforge'
+```
+
+### Node.js/Backend
+
+```typescript
+// Regular imports work
+import { DB, Logger } from 'deskforge'
+
+// CLI-specific imports
+import { CLI } from '@deskforge/cli'
+```
+
+### Electron/Desktop
+
+```typescript
+// All desktop packages available
+import { View, File, Background, Bridge } from 'deskforge'
+```
+
+---
+
+## Quick Reference
+
+| Need | Import |
+|------|--------|
+| Quick app | `from 'deskforge'` |
+| Specific package | `from '@deskforge/package'` |
+| Types only | `import type { ... }` |
+| Multiple packages | Import from each `@deskforge/...` |
+| Build new component | Import from `@deskforge/ui` |
+| Manage state | Import from `@deskforge/state` |
+| Handle persistence | Import from `@deskforge/db` |
+| Show notifications | Import from `@deskforge/notifications` |
+| Navigate screens | Import from `@deskforge/router` |
+
+---
+
+## Summary
+
+- **For most apps:** `from 'deskforge'`
+- **For libraries:** `from '@deskforge/package'`
+- **For types:** `import type { ... }`
+- **Always use scoped:** `@deskforge` not `deskforge/package`
+- **Group related imports** by package for readability