deskforge 1.0.0 → 1.0.1

package/COMPONENT_API.md

@@ -0,0 +1,529 @@
+/**
+ * Component API Reference
+ * 
+ * Quick reference for all DeskForge UI component signatures.
+ */
+
+# DeskForge UI Components - API Reference
+
+## Base Components
+
+### View
+
+Primary flex container. All layout uses View.
+
+```typescript
+View(style: StyleObject, children: DFNode[]): DFNode
+```
+
+**Example:**
+```typescript
+View({ flex: 1, backgroundColor: '#fff' }, [
+  Text('Hello'),
+])
+```
+
+---
+
+### Text
+
+Renders text content.
+
+```typescript
+Text(content: string | number, style?: StyleObject): DFNode
+```
+
+**Example:**
+```typescript
+Text('Hello World', { fontSize: 16, fontWeight: 'bold' })
+Text(42, { color: '#0077ff' })
+```
+
+---
+
+### Pressable
+
+Tappable container with press handlers.
+
+```typescript
+Pressable(
+  style: StyleObject,
+  handlers: PressHandlers,
+  children: DFNode[]
+): DFNode
+```
+
+**Handlers:**
+- `onPress: () => void` — Fired on tap
+- `onLongPress: () => void` — Fired after 500ms hold
+- `onPressIn: () => void` — Press starts
+- `onPressOut: () => void` — Press ends
+- `disabled: boolean` — Disable all handlers
+
+**Example:**
+```typescript
+Pressable({ padding: 12 }, {
+  onPress: () => console.log('tapped'),
+}, [
+  Text('Press me'),
+])
+```
+
+---
+
+### Button
+
+Quick button shorthand combining Text + Pressable.
+
+```typescript
+Button(
+  title: string,
+  style: StyleObject,
+  handlers: PressHandlers
+): DFNode
+```
+
+**Example:**
+```typescript
+Button('Submit', { backgroundColor: '#0077ff', padding: 12 }, {
+  onPress: () => handleSubmit(),
+})
+```
+
+---
+
+### TouchableOpacity
+
+Like Pressable with opacity anProperty 'navigate' does not exist on type 'typeof Router'.imation.
+
+```typescript
+TouchableOpacity(
+  style: StyleObject,
+  handlers: PressHandlers,
+  children: DFNode[]
+): DFNode
+```
+
+---
+
+### Image
+
+Display image from path or URI.
+
+```typescript
+Image(source: string | { uri: string }, style?: StyleObject): DFNode
+```
+
+**Example:**
+```typescript
+Image('/assets/logo.png', { width: 100, height: 100 })
+Image({ uri: 'https://example.com/image.png' }, { width: 200 })
+```
+
+---
+
+### TextInput
+
+Text input field.
+
+```typescript
+TextInput(style: StyleObject, props: TextInputProps): DFNode
+```
+
+**Props:**
+- `value?: string` — Current value
+- `placeholder?: string` — Placeholder text
+- `onChangeText?: (text: string) => void` — Text change callback
+- `keyboardType?: 'default' | 'numeric' | 'email-address' | 'phone-pad'`
+- `multiline?: boolean` — Allow multiple lines
+- `maxLength?: number` — Max characters
+- `secureTextEntry?: boolean` — Hide text (password)
+
+**Example:**
+```typescript
+TextInput({ flex: 1, padding: 12, borderWidth: 1, borderColor: '#ccc' }, {
+  placeholder: 'Enter email',
+  keyboardType: 'email-address',
+  value: email,
+  onChangeText: setEmail,
+})
+```
+
+---
+
+## List Components
+
+### ScrollView
+
+Scrollable container.
+
+```typescript
+ScrollView(
+  style: StyleObject,
+  children: DFNode[],
+  props?: ScrollViewProps
+): DFNode
+```
+
+**Props:**
+- `horizontal?: boolean` — Horizontal scroll
+- `bounces?: boolean` — Bounce effect
+
+---
+
+### FlatList
+
+Virtualized list for performance.
+
+```typescript
+FlatList<T>(
+  data: T[],
+  renderItem: (item: T, index: number) => DFNode,
+  style?: StyleObject,
+  props?: FlatListProps
+): DFNode
+```
+
+**Props:**
+- `ItemSeparatorComponent?: () => DFNode` — Separator between items
+- `ListHeaderComponent?: DFNode` — Header component
+- `ListFooterComponent?: DFNode` — Footer component
+- `ListEmptyComponent?: DFNode` — Empty state
+- `onEndReached?: () => void` — Fired at end of list
+- `onEndReachedThreshold?: number` — Distance to trigger onEndReached
+- `horizontal?: boolean` — Horizontal scroll
+- `numColumns?: number` — Column count for grid
+
+**Example:**
+```typescript
+FlatList(
+  items,
+  (item) => Text(item.name, { padding: 12 }),
+  { flex: 1 },
+  {
+    onEndReached: () => loadMore(),
+    numColumns: 2,
+  }
+)
+```
+
+---
+
+### SectionList
+
+Grouped/sectioned list.
+
+```typescript
+SectionList<T>(
+  sections: Section<T>[],
+  renderItem: (item: T) => DFNode,
+  renderSectionHeader: (title: string) => DFNode,
+  style?: StyleObject,
+  props?: SectionListProps
+): DFNode
+```
+
+---
+
+## Layout Components
+
+### SafeAreaView
+
+Respects notch and safe areas on mobile.
+
+```typescript
+SafeAreaView(
+  style: StyleObject,
+  children: DFNode[],
+  props?: SafeAreaViewProps
+): DFNode
+```
+
+---
+
+### KeyboardAvoidingView
+
+Adjusts layout when keyboard appears.
+
+```typescript
+KeyboardAvoidingView(
+  style: StyleObject,
+  children: DFNode[],
+  props?: KeyboardAvoidingViewProps
+): DFNode
+```
+
+**Props:**
+- `behavior?: 'height' | 'padding' | 'position'`
+- `enabled?: boolean`
+- `keyboardVerticalOffset?: number`
+
+---
+
+## Overlay Components
+
+### Modal
+
+Full-screen overlay modal.
+
+```typescript
+Modal(
+  visible: boolean,
+  onClose: () => void,
+  style: StyleObject,
+  children: DFNode[],
+  props?: ModalProps
+): DFNode
+```
+
+**Props:**
+- `animationType?: 'fade' | 'slide' | 'none'`
+- `transparent?: boolean`
+
+---
+
+### ActivityIndicator
+
+Loading spinner.
+
+```typescript
+ActivityIndicator(
+  style?: StyleObject,
+  props?: ActivityIndicatorProps
+): DFNode
+```
+
+**Props:**
+- `color?: string` — Indicator color
+- `size?: 'small' | 'large' | number` — Size
+- `animating?: boolean` — Animation state
+- `hidesWhenStopped?: boolean` — Hide when not animating
+
+---
+
+## Input Components
+
+### Switch
+
+Toggle on/off switch.
+
+```typescript
+Switch(
+  value: boolean,
+  onValueChange: (value: boolean) => void,
+  props?: SwitchProps
+): DFNode
+```
+
+**Props:**
+- `onTintColor?: string` — Color when on
+- `offTintColor?: string` — Color when off
+
+---
+
+### Slider
+
+Range input slider.
+
+```typescript
+Slider(
+  style: StyleObject,
+  props: SliderProps
+): DFNode
+```
+
+**Props:**
+- `value?: number` — Current value
+- `minimumValue?: number` — Min value
+- `maximumValue?: number` — Max value
+- `step?: number` — Step size
+- `onValueChange?: (value: number) => void` — Drag callback
+- `onSlidingComplete?: (value: number) => void` — Release callback
+
+---
+
+### CheckBox
+
+Checkbox input.
+
+```typescript
+CheckBox(
+  value: boolean,
+  onValueChange: (value: boolean) => void,
+  style?: StyleObject,
+  props?: CheckBoxProps
+): DFNode
+```
+
+---
+
+## Platform Components
+
+### StatusBar
+
+System status bar (mobile).
+
+```typescript
+StatusBar(props: StatusBarProps): DFNode
+```
+
+**Props:**
+- `backgroundColor?: string` — Bar color
+- `barStyle?: 'light-content' | 'dark-content'` — Icon color
+- `hidden?: boolean` — Hide status bar
+
+---
+
+### Platform
+
+Cross-platform utilities.
+
+```typescript
+Platform.OS: 'windows' | 'macos' | 'linux' | 'ios' | 'android'
+
+Platform.select<T>(options: {
+  ios?: T
+  android?: T
+  windows?: T
+  macos?: T
+  linux?: T
+  default?: T
+}): T
+
+Platform.desktop(node: DFNode): DFNode | null
+Platform.mobile(node: DFNode): DFNode | null
+Platform.any(node: DFNode): DFNode
+```
+
+**Example:**
+```typescript
+if (Platform.OS === 'ios') { /* iOS code */ }
+
+const padding = Platform.select({
+  ios: 12,
+  android: 8,
+  default: 10,
+})
+
+Platform.desktop(DesktopOnlyComponent)
+Platform.mobile(MobileOnlyComponent)
+```
+
+---
+
+## Style Object
+
+All style properties from React Native are supported:
+
+```typescript
+interface StyleObject {
+  // Layout
+  flex?: number
+  flexDirection?: 'row' | 'column'
+  justifyContent?: 'flex-start' | 'center' | 'flex-end' | 'space-between' | 'space-around'
+  alignItems?: 'flex-start' | 'center' | 'flex-end' | 'stretch'
+  gap?: number
+  
+  // Spacing
+  margin?: number
+  marginHorizontal?: number
+  marginVertical?: number
+  padding?: number
+  paddingHorizontal?: number
+  paddingVertical?: number
+  
+  // Dimensions
+  width?: number | string
+  height?: number | string
+  
+  // Appearance
+  backgroundColor?: string
+  borderRadius?: number
+  borderWidth?: number
+  borderColor?: string
+  opacity?: number
+  
+  // Typography
+  fontSize?: number
+  fontWeight?: 'normal' | 'bold' | '100' | '200' | ... | '900'
+  color?: string
+  textAlign?: 'left' | 'center' | 'right'
+  
+  // Position
+  position?: 'absolute' | 'relative'
+  top?: number
+  bottom?: number
+  left?: number
+  right?: number
+  
+  // Shadow
+  shadowColor?: string
+  shadowOpacity?: number
+  shadowRadius?: number
+  elevation?: number
+}
+```
+
+---
+
+## State Management
+
+```typescript
+import { State, Computed, Watch, Effect, Ref } from 'deskforge/state'
+
+// Reactive state - direct mutations
+const state = State({ count: 0 })
+state.count++  // Automatic update
+
+// Computed derived values
+const doubled = Computed(() => state.count * 2)
+
+// Watch changes
+Watch(() => state.count, (newVal, oldVal) => {})
+
+// Side effects
+Effect(() => {
+  console.log('count changed')
+  return () => console.log('cleanup')
+})
+
+// Immutable ref
+const ref = Ref(initialValue)
+ref.value = newValue
+```
+
+---
+
+## StyleSheet
+
+```typescript
+import { StyleSheet } from 'deskforge'
+
+const styles = StyleSheet.create({
+  container: { flex: 1, backgroundColor: '#fff' },
+  title: { fontSize: 20, fontWeight: 'bold' },
+})
+
+// Use styles
+View(styles.container, [...])
+Text('Title', styles.title)
+```
+
+---
+
+## Complete Import
+
+```typescript
+import {
+  View, Text, Pressable, Button, TouchableOpacity,
+  Image, TextInput,
+  ScrollView, FlatList, SectionList,
+  SafeAreaView, KeyboardAvoidingView,
+  Modal, ActivityIndicator,
+  Switch, Slider, CheckBox,
+  StatusBar, Platform,
+  StyleSheet, createNode,
+} from 'deskforge'
+
+import { State, Computed, Watch, Effect, Ref } from 'deskforge/state'
+```