deskforge 1.0.0 → 1.0.1

package/QUICK_REFERENCE.md

@@ -0,0 +1,352 @@
+/**
+ * DeskForge Components - Quick Reference Card
+ * 
+ * One-page cheat sheet for all components and patterns
+ */
+
+# DeskForge UI - Quick Reference
+
+## Import
+```typescript
+import {
+  View, Text, Pressable, Button, TouchableOpacity, Image, TextInput,
+  ScrollView, FlatList, SectionList,
+  SafeAreaView, KeyboardAvoidingView,
+  Modal, ActivityIndicator,
+  Switch, Slider, CheckBox,
+  StatusBar, Platform,
+  StyleSheet,
+} from 'deskforge'
+
+import { State, Computed, Watch, Effect } from 'deskforge/state'
+```
+
+---
+
+## Components at a Glance
+
+### Containers
+```typescript
+// Flex container
+View({ flex: 1 }, [children])
+
+// Scroll content
+ScrollView({ flex: 1 }, [children])
+
+// Safe areas
+SafeAreaView({ flex: 1 }, [children])
+KeyboardAvoidingView({ flex: 1 }, [children])
+
+// Full-screen overlay
+Modal(visible, onClose, style, [children])
+```
+
+### Text & Input
+```typescript
+// Static text
+Text('Hello', { fontSize: 16 })
+
+// Text input
+TextInput({ flex: 1 }, { placeholder, value, onChangeText })
+
+// Password
+TextInput({ flex: 1 }, { secureTextEntry: true })
+```
+
+### Buttons & Touch
+```typescript
+// Tappable
+Pressable(style, { onPress, onLongPress, disabled }, [children])
+
+// Quick button
+Button('Click', style, { onPress })
+
+// With opacity animation
+TouchableOpacity(style, { onPress }, [children])
+```
+
+### Lists
+```typescript
+// Simple list
+FlatList(data, (item) => renderItem(item), style)
+
+// With config
+FlatList(data, renderItem, style, {
+  onEndReached: () => loadMore(),
+  ItemSeparatorComponent: () => Separator(),
+})
+
+// Grouped
+SectionList(sections, renderItem, renderSectionHeader, style)
+```
+
+### Media
+```typescript
+// Images
+Image('/path/file.jpg', { width: 100, height: 100 })
+Image({ uri: 'https://...' }, { width: 100 })
+
+// Loading
+ActivityIndicator({ margin: 20 }, { size: 'large' })
+```
+
+### Inputs
+```typescript
+// Toggle
+Switch(value, onChange, { onTintColor: '#0077ff' })
+
+// Slider
+Slider({ width: 200 }, {
+  value: 50,
+  minimumValue: 0,
+  maximumValue: 100,
+  onValueChange: (v) => setState(v),
+})
+
+// Checkbox
+CheckBox(checked, onChange)
+```
+
+### Platform
+```typescript
+// Detect OS
+Platform.OS  // 'ios' | 'android' | 'windows' | 'macos' | 'linux'
+
+// Select by platform
+Platform.select({ ios: 'x', android: 'y', default: 'z' })
+
+// Conditional render
+Platform.mobile(node)   // null on desktop
+Platform.desktop(node)  // null on mobile
+```
+
+---
+
+## Styles
+
+```typescript
+const styles = StyleSheet.create({
+  // Layout
+  flex: 1,
+  flexDirection: 'row' | 'column',
+  justifyContent: 'center' | 'flex-start' | 'flex-end' | 'space-between',
+  alignItems: 'center',
+  gap: 12,
+  
+  // Spacing
+  padding: 16,
+  margin: 8,
+  paddingHorizontal: 12,
+  marginVertical: 4,
+  
+  // Size
+  width: 100,
+  height: 200,
+  
+  // Visual
+  backgroundColor: '#fff',
+  borderRadius: 8,
+  borderWidth: 1,
+  borderColor: '#ddd',
+  
+  // Text
+  fontSize: 16,
+  fontWeight: 'bold' | '600',
+  color: '#000',
+  textAlign: 'center',
+  
+  // Shadow
+  shadowColor: '#000',
+  shadowOpacity: 0.1,
+  shadowRadius: 4,
+  elevation: 2,
+})
+```
+
+---
+
+## State Management
+
+```typescript
+// Reactive state - mutate directly
+const state = State({ count: 0, items: [] })
+state.count++
+state.items.push(item)
+
+// Computed value - auto-updates
+const doubled = Computed(() => state.count * 2)
+Text(`${doubled.value}`)
+
+// Side effects
+Effect(() => {
+  console.log('count changed')
+  return () => console.log('cleanup')
+})
+
+// Watch specific value
+Watch(() => state.count, (newVal, oldVal) => {
+  console.log(`${oldVal} -> ${newVal}`)
+})
+```
+
+---
+
+## Common Patterns
+
+### Conditional Rendering
+```typescript
+View({}, [
+  state.loading ? ActivityIndicator() : Content(),
+  state.error ? Error(state.error) : null,
+].filter(Boolean))
+```
+
+### List with Delete
+```typescript
+FlatList(state.items, (item) =>
+  Pressable({ padding: 12 }, {}, [
+    Text(item.name),
+    Pressable({ padding: 4 }, {
+      onPress: () => {
+        const idx = state.items.indexOf(item)
+        state.items.splice(idx, 1)
+      },
+    }, [Text('×')]),
+  ])
+)
+```
+
+### Form Validation
+```typescript
+const state = State({ email: '', errors: {} })
+
+const validate = () => {
+  state.errors = {}
+  if (!state.email) state.errors.email = 'Required'
+  return Object.keys(state.errors).length === 0
+}
+
+Pressable({ padding: 12 }, {
+  onPress: () => validate() && submit(),
+}, [Text('Submit')])
+```
+
+### Data Loading
+```typescript
+Effect(() => {
+  state.loading = true
+  fetch('/api/items')
+    .then(r => r.json())
+    .then(data => state.items = data)
+    .catch(e => state.error = e.message)
+    .finally(() => state.loading = false)
+})
+```
+
+---
+
+## Common Properties
+
+### Pressable Handlers
+```typescript
+{
+  onPress: () => {},           // Tap/click
+  onLongPress: () => {},       // 500ms hold
+  onPressIn: () => {},         // Press starts
+  onPressOut: () => {},        // Press ends
+  disabled: false,             // Block handlers
+}
+```
+
+### TextInput Props
+```typescript
+{
+  value: '',
+  placeholder: '',
+  onChangeText: (text) => {},
+  keyboardType: 'default' | 'numeric' | 'email-address' | 'phone-pad',
+  multiline: false,
+  maxLength: 100,
+  secureTextEntry: false,
+}
+```
+
+### FlatList Props
+```typescript
+{
+  ItemSeparatorComponent: () => Separator(),
+  ListHeaderComponent: Header(),
+  ListFooterComponent: Footer(),
+  ListEmptyComponent: EmptyState(),
+  onEndReached: () => loadMore(),
+  onEndReachedThreshold: 0.5,
+  horizontal: false,
+  numColumns: 1,
+}
+```
+
+---
+
+## Quick Rules
+
+1. ✅ All components return DFNode
+2. ✅ All styles use StyleSheet.create()
+3. ✅ State mutations are direct (no setState)
+4. ✅ Children always in array
+5. ✅ Style is always first arg
+6. ✅ Handlers go in object
+7. ✅ Platform.OS detects environment
+8. ✅ Use Computed for derived values
+9. ✅ Use Effect for side effects
+10. ✅ Filter booleans with .filter(Boolean)
+
+---
+
+## Anti-Patterns
+
+❌ Don't use JSX  
+❌ Don't use useState/useEffect  
+❌ Don't mutate state with setState  
+❌ Don't use CSS/className  
+❌ Don't return plain JSX elements  
+❌ Don't forget style object  
+❌ Don't forget children array  
+❌ Don't use any type  
+❌ Don't create new state objects  
+❌ Don't use manual renders over FlatList  
+
+---
+
+## Getting Help
+
+- **Full Guide:** See `IMPLEMENTATION_GUIDE.md`
+- **API Reference:** See `COMPONENT_API.md`
+- **Examples:** See `examples/deskforge-app/screens/`
+- **Getting Started:** See `UI_GETTING_STARTED.md`
+
+---
+
+## Template
+
+```typescript
+import { View, Text, Pressable, StyleSheet } from 'deskforge'
+import { State } from 'deskforge/state'
+
+const styles = StyleSheet.create({
+  container: { flex: 1, padding: 16 },
+  button: { backgroundColor: '#0077ff', padding: 12, borderRadius: 8 },
+})
+
+export const MyComponent = () => {
+  const state = State({ count: 0 })
+  
+  return View(styles.container, [
+    Text(`Count: ${state.count}`, { fontSize: 20 }),
+    Pressable(styles.button, {
+      onPress: () => state.count++,
+    }, [
+      Text('Increment'),
+    ]),
+  ])
+}
+```

package/README.md

@@ -27,7 +27,8 @@ This model is intentionally simple and close to the rendering pipeline used by m
 ### Core principles
 
 - Declarative UI composition using node trees
-- Screen-based navigation with route registration
+- Screen-based navigation with automatic route discovery
+- App.ts as the landing entry for the app shell and screen tree
 - Renderer-driven output for images and visual artifacts
 - Modular packages that can be used independently
 
@@ -81,9 +82,233 @@ You can also add the UI package:
 npm install @deskforge/ui
 ```
 
-## 4. Quick start: File-based routing
+To scaffold a new app from the published CLI:
 
-DeskForge now includes a file-based router similar to **Expo Router** and **Next.js**. No need to register routes manually—your file structure becomes your routes:
+```bash
+npx create-deskforge-app my-app
+cd my-app
+npm install
+npm run start
+```
+
+## 4. Current authoring syntax
+
+The current DeskForge examples use a functional, no-JSX authoring style. Components are written as pure functions that return a DFNode tree created with helpers such as createNode and the built-in UI primitives.
+
+```ts
+import {
+  View,
+  Text,
+  StyleSheet,
+  Button,
+} from '@deskforge/ui/src'
+import { State } from '@deskforge/state/src'
+
+const styles = StyleSheet.create({
+  container: { flex: 1, padding: 24, justifyContent: 'center' },
+  title: { fontSize: 24, fontWeight: '600', marginBottom: 12 },
+})
+
+export function CounterScreen() {
+  const state = State({ count: 0 })
+
+  return View(styles.container, [
+    Text(`Count: ${state.count}`, styles.title),
+    Button('Increment', { padding: 12 }, {
+      onPress: () => {
+        state.count += 1
+      },
+    }),
+  ])
+}
+```
+
+Key patterns in the current codebase:
+
+- No JSX or HTML-style tags are used.
+- UI is composed with functional helpers such as View, Text, Pressable, ScrollView, TextInput and Modal.
+- State is created with State(...) and updated directly.
+- Styling is declared with StyleSheet.create(...) using React Native-style objects.
+- Theme usage is imported from @deskforge/theme/src and applied with Theme.apply(...).
+
+## 5. Packages and what they are for
+
+DeskForge is organized as a set of focused packages. Each package can be used independently, and they work together through the core node-tree model.
+
+### Core packages
+
+- @deskforge/core
+  - Core node model, createNode, diff engine, scheduler, and component primitives.
+  - Use this when you want to build a UI tree or define custom components.
+
+```ts
+import { createNode } from '@deskforge/core'
+
+const node = createNode('view', { style: { padding: 16 } }, [])
+```
+
+- @deskforge/renderer
+  - Renders node trees to a canvas-style surface and exports to image/buffer output.
+  - Use this to display or export your UI.
+
+```ts
+import { Renderer } from '@deskforge/renderer'
+
+const renderer = new Renderer({ width: 800, height: 600, backgroundColor: '#fff' })
+renderer.renderNode(node)
+await renderer.saveAs('./dist/output.png')
+```
+
+- @deskforge/router
+  - Screen routing, navigation helpers, and automatic file-based route discovery.
+  - Use this when your app needs multiple screens and navigation.
+
+```ts
+import { Router } from '@deskforge/router'
+
+// routes are discovered from the file structure automatically
+Router.start()
+```
+
+- @deskforge/ui
+  - A modern set of functional UI primitives for layout, text, input, lists, overlays, feedback, and platform-aware controls.
+  - The current examples use the monorepo entry point with /src imports, including View, Text, Pressable, Button, TouchableOpacity, Image, TextInput, ScrollView, FlatList, SectionList, SafeAreaView, KeyboardAvoidingView, Modal, ActivityIndicator, Switch, Slider, CheckBox, StatusBar, and Platform.
+
+```ts
+import {
+  View,
+  Text,
+  ScrollView,
+  Modal,
+  StyleSheet,
+} from '@deskforge/ui/src'
+```
+
+### State and styling packages
+
+- @deskforge/state
+  - Reactive state helpers for local app state and component state.
+
+```ts
+import { State } from '@deskforge/state'
+
+const state = State({ count: 0 })
+```
+
+- @deskforge/theme
+  - Theme tokens, color palettes, spacing, animation helpers, and a simple Theme API for switching modes and applying theme preferences.
+
+```ts
+import { Theme } from '@deskforge/theme/src'
+
+Theme.apply({ isDark: true })
+```
+
+### Device and platform integrations
+
+- @deskforge/device
+  - Device APIs such as camera, contacts, sensors, and media helpers.
+
+```ts
+import { Camera, Contacts } from '@deskforge/device'
+```
+
+- @deskforge/file
+  - File system helpers for reading and writing files.
+
+```ts
+import { readFile, writeFile } from '@deskforge/file'
+```
+
+- @deskforge/network
+  - Peer-to-peer networking helpers, mDNS discovery, and TCP transfer utilities.
+
+```ts
+import { discoverPeers } from '@deskforge/network'
+```
+
+- @deskforge/notifications
+  - Toasts, push notifications, SMS, email, and notification helpers.
+
+```ts
+import { Notify } from '@deskforge/notifications'
+```
+
+- @deskforge/security
+  - Biometric helpers and encryption utilities.
+
+```ts
+import { encrypt } from '@deskforge/security'
+```
+
+### AI, data, and app platform packages
+
+- @deskforge/ai
+  - Local AI helpers and brain-style node creation for on-device reasoning.
+
+```ts
+import { createBrain } from '@deskforge/ai'
+```
+
+- @deskforge/db
+  - Database adapters for SQLite, Postgres, MySQL, and MongoDB.
+
+```ts
+import { connect } from '@deskforge/db'
+```
+
+- @deskforge/background
+  - Background tasks and scheduling helpers.
+
+```ts
+import { BackgroundTask } from '@deskforge/background'
+```
+
+- @deskforge/updater
+  - Self-hosted automatic update helpers.
+
+```ts
+import { Updater } from '@deskforge/updater'
+```
+
+- @deskforge/payments
+  - Unified payment wrapper with failover support for common providers.
+
+```ts
+import { Pay } from '@deskforge/payments'
+```
+
+- @deskforge/i18n
+  - Localization helpers with African language support.
+
+```ts
+import { t } from '@deskforge/i18n'
+```
+
+- @deskforge/logger
+  - Structured logging helpers for the framework and app code.
+
+```ts
+import { logger } from '@deskforge/logger'
+```
+
+- @deskforge/bridge
+  - Language bridge for calling code written in Python, Go, Rust, PHP, C, Kotlin, or Swift.
+
+```ts
+import { callPython } from '@deskforge/bridge'
+```
+
+- @deskforge/cli
+  - Command-line tools for scaffolding and app management.
+
+```bash
+npx create-deskforge-app my-app
+```
+
+## 5. Quick start: File-based routing
+
+DeskForge now includes a file-based router similar to **Expo Router** and **Next.js**. Routes are discovered automatically from your screen files, so you do not manually register them. Your App.ts file acts as the landing page and app shell for the discovered screens:
 
 ```ts
 import { FileRouter, ManifestBuilder, Screen } from '@deskforge/router'
@@ -171,7 +396,7 @@ await renderer.saveAs('./dist/output.png')
 
 ### 5.3 Screens and routes
 
-DeskForge uses routes mapping to screen components. A screen is simply a function that returns a node tree, and it can also carry Expo-style metadata such as a title and layout.
+DeskForge uses automatic route discovery from a screen folder structure. A screen is simply a function that returns a node tree, and it can also carry metadata such as a title and layout. The App.ts entry file becomes the landing page that hosts the app shell and initial screen.
 
 ```ts
 import { Screen } from '@deskforge/router'
@@ -185,14 +410,12 @@ function HomeScreen() {
 const HomeRoute = Screen(HomeScreen, { title: 'Home', layout: 'app' })
 ```
 
-You register screens with `Router`:
+The router discovers screens automatically from the file structure:
 
 ```ts
 import { Router } from '@deskforge/router'
 
-Router({
-  home: HomeRoute,
-})
+Router.start()
 ```
 
 And navigate with:
@@ -207,8 +430,8 @@ Router.go('home')
 
 The simplest app has three parts:
 
-1. an entry point file, usually `App.ts`
-2. one or more screen files
+1. an entry point file, usually `App.ts`, which acts as the landing page and app shell
+2. one or more screen files discovered automatically by the router
 3. a small UI helper layer for creating views and text blocks
 
 The example app in `examples/deskforge-app` follows this pattern.
@@ -223,9 +446,7 @@ import { Renderer } from '@deskforge/renderer'
 import { Router } from '@deskforge/router'
 import { HomeScreen } from './src/screens'
 
-Router({
-  home: HomeScreen,
-})
+Router.start()
 
 function createRoot() {
   return createNode('view', {
@@ -269,18 +490,14 @@ export default function HomeScreen(params: ScreenParams = {}) {
 }
 ```
 
-### 6.3 Register screens
+### 6.3 App entry and automatic screen discovery
 
-In the entry file or a shared bootstrapping module, register all screens:
+The App.ts entry file serves as the landing page and initial app shell. Screen files under the app structure are discovered automatically and exposed by the router.
 
 ```ts
 import { Router } from '@deskforge/router'
-import { HomeScreen, DetailsScreen } from './src/screens'
 
-Router({
-  home: HomeRoute,
-  details: DetailsRoute,
-})
+Router.start()
 ```
 
 ### 6.4 Navigate between screens
@@ -296,6 +513,9 @@ The current router stores navigation history and exposes helpers such as:
 - `Router.forward()`
 - `Router.params()`
 - `Router.currentRoute()`
+- `Router.start()`
+
+For a React Navigation-like experience, DeskForge also supports a stack-style navigation model with screen components, route params, and a shared app shell defined in App.ts.
 
 ---
 
@@ -424,10 +644,10 @@ my-app/
 
 ### Suggested workflow
 
-1. Create a main `App.ts` file.
+1. Create a main `App.ts` file as the landing page and app shell.
 2. Create one file per screen.
 3. Create helper modules for common UI primitives.
-4. Register routes in one place.
+4. Let the router discover screens automatically.
 5. Render the current screen through the renderer.
 
 ---
@@ -460,15 +680,7 @@ import { Renderer } from '@deskforge/renderer'
 import { Router, Screen } from '@deskforge/router'
 import { Text, View, Window } from './src/ui/Responsive'
 
-Router({
-  home: () => Screen({ style: { background: '#f8fafc', padding: 24 } })
-    .add(
-      View({ style: { background: '#ffffff', borderRadius: 24, padding: 24 } }),
-      Text('DeskForge App', { style: { fontSize: 24, fontWeight: '700' } }),
-      Text('This is a simple DeskForge screen.', { style: { color: '#4b5563', fontSize: 16 } }),
-    )
-    .build(),
-})
+Router.start()
 
 function createRoot() {
   return Window({ style: { background: '#f7f8fb', padding: 24 } })
@@ -506,6 +718,8 @@ main().catch(console.error)
 - Use helper functions to hide repetitive node creation.
 - Keep route names stable and descriptive.
 - Keep rendering logic separate from navigation logic.
+- Use App.ts as the shared landing page and shell for the app.
+- Let the router discover screens automatically instead of manually registering them.
 - Use `dist/` for generated assets so your source stays clean.
 
 ---