deskforge 1.0.0 → 1.0.1

package/UI_GETTING_STARTED.md

@@ -0,0 +1,523 @@
+/**
+ * DeskForge UI Components - Migration & Getting Started Guide
+ */
+
+# DeskForge UI Components - Getting Started
+
+## What Changed
+
+DeskForge UI has been completely rewritten to use **pure functional syntax without JSX**.
+
+### Before (Old Syntax)
+```tsx
+// Old JSX-based approach (NOT USED)
+export const MyComponent = () => {
+  const [count, setCount] = useState(0)
+  
+  return (
+    <View style={styles.container}>
+      <Text style={styles.title}>Count: {count}</Text>
+      <Pressable onPress={() => setCount(count + 1)}>
+        <Text>Increment</Text>
+      </Pressable>
+    </View>
+  )
+}
+```
+
+### After (New Syntax)
+```typescript
+// New pure functional approach
+const MyComponent = () => {
+  const state = State({ count: 0 })
+  
+  return View(styles.container, [
+    Text(`Count: ${state.count}`, styles.title),
+    Pressable({ padding: 12 }, {
+      onPress: () => state.count++,
+    }, [
+      Text('Increment'),
+    ]),
+  ])
+}
+```
+
+## Key Differences
+
+| Aspect | Old | New |
+|--------|-----|-----|
+| **Syntax** | JSX/TSX with angle brackets | Pure function calls |
+| **State** | `useState()` with `setState()` | `State()` with direct mutations |
+| **Hooks** | `useState`, `useEffect`, etc | `State()`, `Effect()`, `Computed()` |
+| **Styling** | CSS classes or inline style objects | StyleObject only (React Native props) |
+| **Returns** | JSX elements | DFNode objects |
+| **Files** | `.tsx` or `.jsx` | `.ts` (pure TypeScript) |
+
+## Installation
+
+```bash
+npm install @deskforge/ui @deskforge/state @deskforge/core
+# or
+yarn add @deskforge/ui @deskforge/state @deskforge/core
+# or monorepo
+yarn workspaces run build
+```
+
+## Quick Start
+
+### 1. Import Components
+
+```typescript
+import {
+  View, Text, Pressable, Button,
+  FlatList, TextInput, Modal,
+  StyleSheet, Platform,
+} from 'deskforge'
+
+import { State, Computed, Effect } from 'deskforge/state'
+```
+
+### 2. Create Styles
+
+```typescript
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    backgroundColor: '#f8f9fc',
+    padding: 16,
+  },
+  button: {
+    backgroundColor: '#0077ff',
+    borderRadius: 8,
+    paddingVertical: 12,
+    paddingHorizontal: 16,
+  },
+  buttonText: {
+    color: '#ffffff',
+    fontWeight: 'bold',
+  },
+})
+```
+
+### 3. Create State
+
+```typescript
+const state = State({
+  count: 0,
+  name: '',
+  items: [],
+})
+```
+
+### 4. Build UI
+
+```typescript
+export const MyApp = () => {
+  return View(styles.container, [
+    Text(`Count: ${state.count}`, { fontSize: 20 }),
+    
+    Button('Increment', styles.button, {
+      onPress: () => state.count++,
+    }),
+  ])
+}
+```
+
+## Component Syntax
+
+### View (Container)
+```typescript
+View(
+  { flex: 1, backgroundColor: '#fff' },  // style
+  [                                       // children
+    Text('Content'),
+    Text('More content'),
+  ]
+)
+```
+
+### Text
+```typescript
+Text('Hello', { fontSize: 16, color: '#000' })
+Text(42)  // Numbers work too
+```
+
+### Pressable (Button-like)
+```typescript
+Pressable(
+  { padding: 12 },                    // style
+  {                                    // handlers
+    onPress: () => handlePress(),
+    onLongPress: () => handleLongPress(),
+    disabled: false,
+  },
+  [Text('Press me')]                   // children
+)
+```
+
+### Button (Quick)
+```typescript
+Button(
+  'Click Me',                          // title
+  { backgroundColor: '#0077ff' },     // style
+  { onPress: () => handleClick() }    // handlers
+)
+```
+
+### TextInput
+```typescript
+TextInput(
+  { flex: 1, borderWidth: 1, padding: 12 },  // style
+  {                                            // props
+    placeholder: 'Enter text',
+    value: state.text,
+    onChangeText: (text) => state.text = text,
+  }
+)
+```
+
+### FlatList (Lists)
+```typescript
+FlatList(
+  items,                                           // data
+  (item) => Text(item.name),                      // renderItem
+  { flex: 1 },                                     // style
+  { onEndReached: () => loadMore() }              // optional props
+)
+```
+
+### Switch (Toggle)
+```typescript
+Switch(
+  state.darkMode,                          // value
+  (value) => state.darkMode = value,       // onValueChange
+  { onTintColor: '#0077ff' }               // optional props
+)
+```
+
+### Slider (Range)
+```typescript
+Slider({ width: 200 }, {
+  value: state.volume,
+  minimumValue: 0,
+  maximumValue: 100,
+  onValueChange: (v) => state.volume = v,
+})
+```
+
+### Image
+```typescript
+Image('/assets/logo.png', { width: 100, height: 100 })
+Image({ uri: 'https://example.com/image.jpg' })
+```
+
+### Modal (Overlay)
+```typescript
+Modal(
+  state.isOpen,                           // visible
+  () => state.isOpen = false,             // onClose
+  { flex: 1, justifyContent: 'center' }, // style
+  [                                        // children
+    View({}, [Text('Modal content')])
+  ]
+)
+```
+
+## State Management
+
+### Basic State
+```typescript
+const state = State({
+  count: 0,
+  name: '',
+})
+
+// Mutate directly
+state.count++
+state.name = 'John'
+```
+
+### Computed Values
+```typescript
+import { Computed } from 'deskforge/state'
+
+const doubled = Computed(() => state.count * 2)
+
+// Use it
+Text(`Doubled: ${doubled.value}`)  // Auto-updates when count changes
+```
+
+### Effects (Side Effects)
+```typescript
+import { Effect } from 'deskforge/state'
+
+Effect(() => {
+  console.log('Count changed:', state.count)
+  
+  // Optional cleanup
+  return () => console.log('Cleanup')
+})
+```
+
+### Watch (Specific Values)
+```typescript
+import { Watch } from 'deskforge/state'
+
+Watch(
+  () => state.count,
+  (newValue, oldValue) => {
+    console.log(`Count: ${oldValue} -> ${newValue}`)
+  }
+)
+```
+
+## Styling
+
+All styles use **React Native property names**:
+
+```typescript
+const styles = StyleSheet.create({
+  container: {
+    // Layout
+    flex: 1,
+    flexDirection: 'column',
+    justifyContent: 'center',
+    alignItems: 'center',
+    gap: 12,
+    
+    // Spacing
+    padding: 16,
+    marginBottom: 8,
+    
+    // Dimensions
+    width: 100,
+    height: 200,
+    
+    // Appearance
+    backgroundColor: '#ffffff',
+    borderRadius: 8,
+    borderWidth: 1,
+    borderColor: '#e2e8f0',
+    
+    // Typography
+    fontSize: 16,
+    fontWeight: 'bold',
+    color: '#000000',
+    
+    // Shadow
+    shadowColor: '#000',
+    shadowOpacity: 0.1,
+    shadowRadius: 4,
+    elevation: 2,
+  },
+})
+```
+
+## Cross-Platform
+
+Use `Platform` for OS detection:
+
+```typescript
+import { Platform } from 'deskforge'
+
+// Detect current OS
+if (Platform.OS === 'ios') { }
+if (Platform.OS === 'android') { }
+if (Platform.OS === 'windows') { }
+
+// Select value by platform
+const behavior = Platform.select({
+  ios: 'padding',
+  android: 'height',
+  default: 'padding',
+})
+
+// Render platform-specific components
+Platform.mobile(MobileComponent)    // null on desktop
+Platform.desktop(DesktopComponent)  // null on mobile
+Platform.any(AlwaysShow)            // always renders
+```
+
+## Common Patterns
+
+### Conditional Rendering
+```typescript
+View({}, [
+  state.loading ? ActivityIndicator() : null,
+  state.error ? Text(state.error, { color: 'red' }) : null,
+  Text('Content'),
+].filter(Boolean))
+```
+
+### List with Operations
+```typescript
+FlatList(
+  state.items,
+  (item) => Pressable(
+    { padding: 12, borderBottomWidth: 1, borderBottomColor: '#eee' },
+    { onPress: () => selectItem(item) },
+    [
+      Text(item.name, { fontWeight: 'bold' }),
+      Pressable({ padding: 4 }, {
+        onPress: () => {
+          const idx = state.items.indexOf(item)
+          state.items.splice(idx, 1)
+        },
+      }, [Text('×', { color: 'red' })])
+    ]
+  ),
+  { flex: 1 }
+)
+```
+
+### Forms with Validation
+```typescript
+const state = State({
+  email: '',
+  password: '',
+  errors: {} as Record<string, string>,
+})
+
+const handleSubmit = () => {
+  state.errors = {}
+  
+  if (!state.email) state.errors.email = 'Required'
+  if (!state.password) state.errors.password = 'Required'
+  
+  if (Object.keys(state.errors).length === 0) {
+    submitForm(state.email, state.password)
+  }
+}
+
+// In render
+View({}, [
+  TextInput({ flex: 1 }, {
+    placeholder: 'Email',
+    value: state.email,
+    onChangeText: (v) => state.email = v,
+  }),
+  state.errors.email 
+    ? Text(state.errors.email, { color: 'red', fontSize: 12 })
+    : null,
+])
+```
+
+### Database Integration
+```typescript
+const state = State({
+  items: [],
+  loading: false,
+})
+
+// Load on mount
+Effect(() => {
+  state.loading = true
+  DB.query('items')
+    .all()
+    .then(items => state.items = items)
+    .finally(() => state.loading = false)
+})
+
+// Add item
+const addItem = (name: string) => {
+  DB.insert('items', { name })
+    .then(item => state.items.unshift(item))
+}
+
+// Delete item
+const deleteItem = (id: string) => {
+  DB.delete('items', id)
+    .then(() => {
+      state.items = state.items.filter(i => i.id !== id)
+    })
+}
+```
+
+## Migration Checklist
+
+If migrating from old JSX syntax:
+
+- [ ] Rename files from `.tsx` to `.ts`
+- [ ] Remove all `<>` JSX brackets
+- [ ] Replace `useState()` with `State()`
+- [ ] Replace `useEffect()` with `Effect()`
+- [ ] Replace `setState()` with direct mutations
+- [ ] Convert component returns to function calls
+- [ ] Update styles to use StyleSheet.create()
+- [ ] Replace all CSS/classNames with StyleObject
+- [ ] Test all interactions and state changes
+- [ ] Verify cross-platform compatibility
+
+## Examples
+
+See the following files for complete working examples:
+
+1. **[NotesApp.ts](examples/deskforge-app/screens/NotesApp.ts)** - FlatList, Modal, TextInput, DB
+2. **[CounterApp.ts](examples/deskforge-app/screens/CounterApp.ts)** - Simple State, Computed
+3. **[SettingsApp.ts](examples/deskforge-app/screens/SettingsApp.ts)** - Switch, Slider, Platform
+4. **[TodoApp.ts](examples/deskforge-app/screens/TodoApp.ts)** - FlatList, CheckBox, Array ops
+5. **[GalleryApp.ts](examples/deskforge-app/screens/GalleryApp.ts)** - Image, Modal preview
+
+## Troubleshooting
+
+### "style is required"
+All components need a style object. Use empty `{}` if no style needed.
+
+```typescript
+// ❌ Wrong
+Text('Hello')
+
+// ✅ Correct
+Text('Hello', { fontSize: 16 })
+Text('Hello', {})  // Empty style okay
+```
+
+### "children is required"
+Container components need children array (even if empty).
+
+```typescript
+// ❌ Wrong
+View({ flex: 1 })
+
+// ✅ Correct
+View({ flex: 1 }, [])
+View({ flex: 1 }, [Text('Content')])
+```
+
+### State not updating
+Make sure you're mutating state directly, not creating new objects.
+
+```typescript
+// ❌ Wrong
+state.items = [...state.items, newItem]
+
+// ✅ Correct
+state.items.push(newItem)
+state.items.unshift(newItem)
+```
+
+### Styles not applying
+Check that you're using React Native style property names, not CSS.
+
+```typescript
+// ❌ Wrong
+{ className: 'my-class', color: 'red', fontSize: '16px' }
+
+// ✅ Correct
+{ color: '#ff0000', fontSize: 16 }
+```
+
+## Next Steps
+
+1. ✅ Read [IMPLEMENTATION_GUIDE.md](IMPLEMENTATION_GUIDE.md) for detailed patterns
+2. ✅ Read [COMPONENT_API.md](COMPONENT_API.md) for all component signatures
+3. ✅ Review the example apps in [examples/deskforge-app/screens/](examples/deskforge-app/screens/)
+4. ✅ Start building your app!
+
+## Support
+
+Questions? See:
+- Component API: [COMPONENT_API.md](COMPONENT_API.md)
+- Implementation patterns: [IMPLEMENTATION_GUIDE.md](IMPLEMENTATION_GUIDE.md)
+- Working examples: [examples/deskforge-app/screens/](examples/deskforge-app/screens/)
+- Main README: [README.md](README.md)

package/examples/deskforge-app/App.ts

@@ -1,23 +1,19 @@
 import * as fs from 'fs'
 import { Renderer } from '@deskforge/renderer'
-import { createApp, ManifestBuilder } from '@deskforge/router'
+import { createNavigation } from '@deskforge/router'
 import { HomeRoute, DetailsRoute } from './src/screens'
 import { Text, View, Window } from './src/ui/Responsive'
 
-// Define routes using the manifest builder (Expo Router style).
-const routes = new ManifestBuilder()
-  .add('index.ts', HomeRoute.component)
-  .add('details.ts', DetailsRoute.component)
-  .build()
-
-const { router } = createApp({ manifest: routes })
+const navigation = createNavigation()
+navigation.register('home', HomeRoute)
+navigation.register('details', DetailsRoute)
 
 function createRoot() {
   return Window({ style: { background: '#f7f8fb', padding: 24 } })
     .add(
       View({ style: { background: '#ffffff', borderRadius: 32, padding: 24 } }),
       Text('DeskForge App Example', { style: { fontSize: 24, fontWeight: '700' } }),
-      router.render() ?? Text('No screen selected.', { style: { color: '#6b7280', fontSize: 16 } }),
+      navigation.render() ?? Text('No screen selected.', { style: { color: '#6b7280', fontSize: 16 } }),
     )
     .build()
 }
@@ -32,13 +28,13 @@ async function main() {
   })
 
   // Navigate to home and render
-  router.navigate('/')
+  navigation.navigate('home')
   renderer.renderNode(createRoot())
   await renderer.saveAs('./dist/deskforge-app-home.png')
   console.log('Rendered home screen to dist/deskforge-app-home.png')
 
   // Navigate to details and render
-  router.navigate('/details')
+  navigation.navigate('details', { noteId: 42 })
   renderer.renderNode(createRoot())
   await renderer.saveAs('./dist/deskforge-app-details.png')
   console.log('Rendered details screen to dist/deskforge-app-details.png')