deskforge 1.0.0 → 1.0.1

package/IMPLEMENTATION_GUIDE.md

@@ -0,0 +1,385 @@
+/**
+ * DeskForge UI Components - Implementation Guide
+ * 
+ * This document explains the core principles and usage patterns
+ * for building apps with DeskForge's functional UI components.
+ */
+
+# DeskForge UI Components - Implementation Guide
+
+## Core Philosophy
+
+DeskForge UI is built on a single principle:
+> **Everything is a pure function that returns a DFNode**
+
+No JSX, no HTML, no XML. No className strings. No CSS files. No hooks.
+
+## The Pattern
+
+Every UI component follows this exact pattern:
+
+```typescript
+import { createNode } from '@deskforge/core'
+import type { DFNode, StyleObject } from '@deskforge/core'
+
+export function ComponentName(
+  prop1: Type,
+  prop2?: Type,
+  children: DFNode[] = []
+): DFNode {
+  return createNode(
+    'ComponentType',
+    {
+      prop1,
+      prop2: prop2 ?? defaultValue,
+    } as Record<string, unknown>,
+    children
+  )
+}
+```
+
+## Usage Examples
+
+### View - Primary Container
+
+```typescript
+View({ flex: 1, backgroundColor: '#fff' }, [
+  Text('Hello World'),
+  Text('Second line'),
+])
+```
+
+### Text - Simple Text Rendering
+
+```typescript
+Text('Simple text', { fontSize: 16, fontWeight: 'bold' })
+Text(42, { color: '#0077ff' })  // Numbers auto-convert
+```
+
+### Pressable - Tappable Container
+
+```typescript
+Pressable(
+  { padding: 16, borderRadius: 8 },
+  {
+    onPress: () => handlePress(),
+    onLongPress: () => handleLongPress(),
+    disabled: false,
+  },
+  [
+    Text('Tap me', { color: '#0077ff' }),
+  ]
+)
+```
+
+### Button - Quick Button Shorthand
+
+```typescript
+Button('Submit', { backgroundColor: '#2ecc71', padding: 12 }, {
+  onPress: () => submitForm(),
+})
+```
+
+### TextInput - Text Input Field
+
+```typescript
+TextInput({ flex: 1, padding: 12, borderWidth: 1, borderColor: '#ccc' }, {
+  placeholder: 'Enter text',
+  value: state.text,
+  onChangeText: (text) => state.text = text,
+  keyboardType: 'email-address',
+  secureTextEntry: false,
+})
+```
+
+### FlatList - Efficient List Rendering
+
+```typescript
+// Simple list
+FlatList(
+  items,
+  (item) => Text(item.name),
+  { flex: 1 }
+)
+
+// List with configuration
+FlatList(
+  items,
+  (item, index) => Pressable(
+    { padding: 12, borderBottomWidth: 1, borderBottomColor: '#eee' },
+    { onPress: () => selectItem(item) },
+    [
+      Text(item.title, { fontSize: 16, fontWeight: 'bold' }),
+      Text(item.subtitle, { color: '#999' }),
+    ]
+  ),
+  { flex: 1 },
+  {
+    ItemSeparatorComponent: () => View({ height: 1, backgroundColor: '#f0f0f0' }, []),
+    onEndReached: () => loadMore(),
+    onEndReachedThreshold: 0.5,
+  }
+)
+```
+
+### Modal - Full-Screen Overlay
+
+```typescript
+Modal(
+  isOpen,
+  () => setIsOpen(false),
+  { flex: 1, backgroundColor: 'rgba(0,0,0,0.5)', justifyContent: 'center', alignItems: 'center' },
+  [
+    View({
+      backgroundColor: '#fff',
+      borderRadius: 12,
+      padding: 20,
+      width: '85%',
+    }, [
+      Text('Modal Title', { fontSize: 20, fontWeight: 'bold' }),
+      Text('Modal content here', { marginTop: 12, color: '#666' }),
+    ]),
+  ],
+  { animationType: 'fade' }
+)
+```
+
+### Switch - Toggle Control
+
+```typescript
+Switch(
+  isDarkMode,
+  (value) => setDarkMode(value),
+  {
+    onTintColor: '#0077ff',
+    thumbTintColor: '#fff',
+  }
+)
+```
+
+### Slider - Range Input
+
+```typescript
+Slider({ height: 40, padding: 20 }, {
+  value: volume,
+  minimumValue: 0,
+  maximumValue: 100,
+  step: 5,
+  onValueChange: (v) => setVolume(v),
+  minimumTrackTintColor: '#0077ff',
+})
+```
+
+### Image - Image Rendering
+
+```typescript
+// From file path
+Image('/assets/logo.png', { width: 100, height: 100 })
+
+// From URI
+Image({ uri: 'https://example.com/image.png' }, {
+  width: 200,
+  height: 200,
+  borderRadius: 12,
+})
+```
+
+### Platform - Cross-Platform Support
+
+```typescript
+// Detect OS
+if (Platform.OS === 'ios') {
+  // iOS-specific code
+}
+
+// Select value by platform
+const behavior = Platform.select({
+  ios: 'padding',
+  android: 'height',
+  default: 'padding',
+})
+
+// Render platform-specific components
+Platform.desktop(DesktopComponent)  // Returns node on desktop, null on mobile
+Platform.mobile(MobileComponent)    // Returns node on mobile, null on desktop
+Platform.any(AlwaysRender)          // Always returns node
+```
+
+## State Management
+
+DeskForge uses reactive state with direct mutations:
+
+```typescript
+import { State, Computed, Watch, Effect } from 'deskforge/state'
+
+// Create reactive state
+const state = State({
+  count: 0,
+  name: '',
+})
+
+// Mutate directly - NO setState needed
+state.count++
+state.name = 'John'
+
+// Computed values
+const doubled = Computed(() => state.count * 2)
+console.log(doubled.value)  // Automatically updates
+
+// Effects (like useEffect)
+Effect(() => {
+  console.log('Count changed:', state.count)
+  // Optional cleanup function
+  return () => console.log('Cleanup')
+})
+
+// Watch specific values
+Watch(
+  () => state.count,
+  (newValue, oldValue) => {
+    console.log(`Count: ${oldValue} -> ${newValue}`)
+  }
+)
+```
+
+## StyleSheet - Style Objects
+
+All styles use React Native property names via StyleObject:
+
+```typescript
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    backgroundColor: '#fff',
+    padding: 16,
+    justifyContent: 'center',
+    alignItems: 'center',
+  },
+  title: {
+    fontSize: 20,
+    fontWeight: 'bold',
+    color: '#111',
+    marginBottom: 8,
+  },
+  button: {
+    backgroundColor: '#0077ff',
+    borderRadius: 8,
+    paddingHorizontal: 16,
+    paddingVertical: 12,
+    elevation: 2,
+    shadowColor: '#000',
+    shadowOpacity: 0.1,
+    shadowRadius: 4,
+  },
+})
+
+// Use styles
+View(styles.container, [...])
+```
+
+## Style Properties
+
+### Layout
+`flex`, `flexDirection`, `justifyContent`, `alignItems`, `alignSelf`, `flexWrap`, `gap`, `rowGap`, `columnGap`
+
+### Spacing
+`margin`, `marginTop`, `marginBottom`, `marginLeft`, `marginRight`, `marginHorizontal`, `marginVertical`
+`padding`, `paddingTop`, `paddingBottom`, `paddingLeft`, `paddingRight`, `paddingHorizontal`, `paddingVertical`
+
+### Dimensions
+`width`, `height`, `minWidth`, `maxWidth`, `minHeight`, `maxHeight`
+
+### Appearance
+`backgroundColor`, `borderRadius`, `borderWidth`, `borderColor`, `opacity`, `overflow`, `zIndex`
+`shadowColor`, `shadowOpacity`, `shadowRadius`, `shadowOffset`, `elevation`
+
+### Typography
+`fontSize`, `fontWeight`, `fontFamily`, `color`, `textAlign`, `lineHeight`, `letterSpacing`, `textDecorationLine`
+
+### Position
+`position`, `top`, `bottom`, `left`, `right`
+
+## Key Patterns
+
+### Conditional Rendering
+
+```typescript
+View({ flex: 1 }, [
+  isLoading ? ActivityIndicator() : renderContent(),
+  state.error ? View({}, [Text(state.error, { color: 'red' })]) : null,
+].filter(Boolean))
+```
+
+### List Operations
+
+```typescript
+// Array filtering
+state.items = state.items.filter(item => item.id !== toDelete)
+
+// Array mutations
+state.items.unshift(newItem)
+state.items.push(newItem)
+state.items.splice(index, 1)
+
+// Array mapping with FlatList
+FlatList(
+  state.items,
+  (item) => renderItem(item),
+  { flex: 1 }
+)
+```
+
+### Nested Components
+
+```typescript
+const Header = (title: string) => View(
+  { padding: 16, backgroundColor: '#fff' },
+  [Text(title, { fontSize: 20, fontWeight: 'bold' })]
+)
+
+const Container = (children: DFNode[]) => View(
+  { flex: 1, backgroundColor: '#f8f9fc' },
+  children
+)
+
+// Usage
+Container([
+  Header('My App'),
+  Content(),
+])
+```
+
+### Error Handling
+
+```typescript
+const state = State({ error: null as string | null })
+
+Effect(() => {
+  DB.query('items')
+    .all()
+    .then(items => state.items = items)
+    .catch(err => state.error = err.message)
+})
+
+// In render
+state.error
+  ? View({ padding: 20 }, [Text(state.error, { color: '#e74c3c' })])
+  : renderContent()
+```
+
+## Best Practices
+
+1. **Use StyleSheet.create()** - Provides type safety and freezes styles
+2. **Name your styles** - Use descriptive names like `buttonPrimary`, not `button1`
+3. **Leverage State directly** - Mutate state, don't create new state objects
+4. **Use Computed for derived values** - Don't manually track computed state
+5. **Keep components small** - Extract common patterns into helper functions
+6. **Type your props** - Use TypeScript interfaces for component arguments
+7. **Document with JSDoc** - Add comments above functions
+8. **Use FlatList for lists** - Not manual maps; FlatList virtualizes for performance
+9. **Use Platform for OS detection** - Don't manually detect with userAgent
+10. **Combine Pressable + styles** - Create semantic button styles, don't hard-code
+
+## Complete Example
+
+See `NotesApp.ts`, `TodoApp.ts`, `SettingsApp.ts`, `CounterApp.ts`, and `GalleryApp.ts` for full working examples of all patterns combined.