deskforge 1.0.0 → 1.0.1

package/packages/ui/src/list/ScrollView.ts

@@ -0,0 +1,80 @@
+/**
+ * ScrollView Component
+ * 
+ * Scrollable container for content that exceeds viewport.
+ * Accepts style and children array. Returns DFNode.
+ * 
+ * No JSX. No HTML. No XML. Pure functional TypeScript.
+ */
+
+import { createNode } from '@deskforge/core'
+import type { DFNode, StyleObject } from '@deskforge/core'
+
+/**
+ * ScrollView configuration properties
+ */
+export interface ScrollViewProps {
+  /** Scroll in horizontal direction */
+  horizontal?: boolean
+  /** Show scroll indicator */
+  showsVerticalScrollIndicator?: boolean
+  /** Show horizontal scroll indicator */
+  showsHorizontalScrollIndicator?: boolean
+  /** Bounce effect on iOS */
+  bounces?: boolean
+  /** Scroll with deceleration */
+  decelerationRate?: number | 'fast' | 'normal'
+  /** Enable paging */
+  pagingEnabled?: boolean
+  /** Scroll event callback */
+  onScroll?: (offset: { x: number; y: number }) => void
+}
+
+/**
+ * ScrollView - Scrollable container component
+ * 
+ * Renders a scrollable container for content overflow scenarios. Supports
+ * vertical and horizontal scrolling with configurable behavior.
+ * 
+ * @param style - StyleObject for sizing and appearance
+ * @param children - Array of DFNode children to render inside
+ * @param props - Optional ScrollViewProps configuration
+ * @returns DFNode object with type 'ScrollView'
+ * 
+ * @example
+ * ScrollView({ flex: 1 }, [
+ *   Text('Item 1', { padding: 16 }),
+ *   Text('Item 2', { padding: 16 }),
+ *   Text('Item 3', { padding: 16 })
+ * ])
+ * 
+ * ScrollView({ flex: 1 }, [
+ *   View({ height: 200, backgroundColor: '#f0f0f0' }, [])
+ * ], {
+ *   horizontal: true,
+ *   showsHorizontalScrollIndicator: false,
+ *   pagingEnabled: true
+ * })
+ */
+export function ScrollView(
+  style: StyleObject,
+  children: DFNode[] = [],
+  props: ScrollViewProps = {}
+): DFNode {
+  return createNode(
+    'ScrollView',
+    {
+      style,
+      horizontal: props.horizontal ?? false,
+      showsVerticalScrollIndicator: props.showsVerticalScrollIndicator ?? true,
+      showsHorizontalScrollIndicator: props.showsHorizontalScrollIndicator ?? true,
+      bounces: props.bounces ?? true,
+      decelerationRate: props.decelerationRate ?? 'normal',
+      pagingEnabled: props.pagingEnabled ?? false,
+      onScroll: props.onScroll,
+    } as Record<string, unknown>,
+    children
+  )
+}
+
+export type { StyleObject }

package/packages/ui/src/list/SectionList.ts

@@ -0,0 +1,120 @@
+/**
+ * SectionList Component
+ * 
+ * Grouped/sectioned list renderer with section headers.
+ * Optimized for displaying categorized data.
+ * 
+ * No JSX. No HTML. No XML. Pure functional TypeScript.
+ */
+
+import { createNode } from '@deskforge/core'
+import type { DFNode, StyleObject } from '@deskforge/core'
+
+/**
+ * Section configuration for SectionList
+ */
+export interface Section<T> {
+  /** Section title/key */
+  title: string
+  /** Items in this section */
+  data: T[]
+}
+
+/**
+ * SectionList configuration properties
+ */
+export interface SectionListProps {
+  /** Item separator component renderer */
+  ItemSeparatorComponent?: () => DFNode
+  /** Section separator component */
+  SectionSeparatorComponent?: () => DFNode
+  /** Rendered at start of list */
+  ListHeaderComponent?: DFNode
+  /** Rendered at end of list */
+  ListFooterComponent?: DFNode
+  /** Rendered when list is empty */
+  ListEmptyComponent?: DFNode
+  /** Number of items to render at once */
+  initialNumToRender?: number
+  /** Scroll callback */
+  onScroll?: (offset: { x: number; y: number }) => void
+  /** Bounce effect */
+  bounces?: boolean
+  /** Show scroll indicators */
+  showsVerticalScrollIndicator?: boolean
+}
+
+/**
+ * SectionList - Grouped list renderer component
+ * 
+ * High-performance list with section support. Groups related items under
+ * section headers. Generic over item type.
+ * 
+ * @param sections - Array of Section objects containing title and data
+ * @param renderItem - Function that renders each item
+ * @param renderSectionHeader - Function that renders section headers
+ * @param style - Optional StyleObject for sizing
+ * @param props - Optional SectionListProps configuration
+ * @returns DFNode object with type 'SectionList'
+ * 
+ * @example
+ * SectionList(
+ *   [
+ *     { title: 'Fruits', data: ['Apple', 'Banana'] },
+ *     { title: 'Vegetables', data: ['Carrot', 'Lettuce'] }
+ *   ],
+ *   (item) => Text(item, { padding: 12 }),
+ *   (title) => Text(title, { fontSize: 18, fontWeight: 'bold', padding: 8 }),
+ *   { flex: 1 }
+ * )
+ * 
+ * SectionList(
+ *   groupedContacts,
+ *   (contact) => Pressable(
+ *     { padding: 12 },
+ *     { onPress: () => openContact(contact.id) },
+ *     [Text(contact.name)]
+ *   ),
+ *   (letter) => Text(letter, { fontSize: 16, fontWeight: 'bold', backgroundColor: '#f0f0f0', padding: 8 }),
+ *   { flex: 1 },
+ *   { ItemSeparatorComponent: () => View({ height: 1, backgroundColor: '#eee' }, []) }
+ * )
+ */
+export function SectionList<T>(
+  sections: Section<T>[],
+  renderItem: (item: T) => DFNode,
+  renderSectionHeader: (title: string) => DFNode,
+  style?: StyleObject,
+  props: SectionListProps = {}
+): DFNode {
+  const items: DFNode[] = []
+
+  for (const section of sections) {
+    items.push(renderSectionHeader(section.title))
+    for (const item of section.data) {
+      items.push(renderItem(item))
+    }
+  }
+
+  return createNode(
+    'SectionList',
+    {
+      style: style ?? {},
+      sections,
+      renderItem,
+      renderSectionHeader,
+      ItemSeparatorComponent: props.ItemSeparatorComponent,
+      SectionSeparatorComponent: props.SectionSeparatorComponent,
+      ListHeaderComponent: props.ListHeaderComponent,
+      ListFooterComponent: props.ListFooterComponent,
+      ListEmptyComponent: props.ListEmptyComponent,
+      initialNumToRender: props.initialNumToRender ?? 10,
+      onScroll: props.onScroll,
+      bounces: props.bounces ?? true,
+      showsVerticalScrollIndicator: props.showsVerticalScrollIndicator ?? true,
+    } as Record<string, unknown>,
+    items
+  )
+}
+
+export type { StyleObject, Section }

package/packages/ui/src/overlay/ActivityIndicator.ts

@@ -0,0 +1,70 @@
+/**
+ * ActivityIndicator Component
+ * 
+ * Spinning loading indicator showing progress/loading state.
+ * Animated automatically, no manual control needed.
+ * 
+ * No JSX. No HTML. No XML. Pure functional TypeScript.
+ */
+
+import { createNode } from '@deskforge/core'
+import type { DFNode, StyleObject } from '@deskforge/core'
+
+/**
+ * ActivityIndicator configuration properties
+ */
+export interface ActivityIndicatorProps {
+  /** Indicator color */
+  color?: string
+  /** Size: 'small' | 'large' | number */
+  size?: 'small' | 'large' | number
+  /** Hide indicator when not animating */
+  hidesWhenStopped?: boolean
+  /** Animation running state */
+  animating?: boolean
+}
+
+/**
+ * ActivityIndicator - Loading spinner component
+ * 
+ * Displays an animated loading spinner. Automatically animates when mounted.
+ * Useful for showing loading states during async operations.
+ * 
+ * @param style - Optional StyleObject for sizing and positioning
+ * @param props - Optional ActivityIndicatorProps configuration
+ * @returns DFNode object with type 'ActivityIndicator'
+ * 
+ * @example
+ * ActivityIndicator({ margin: 20 }, {
+ *   color: '#0077ff',
+ *   size: 'large'
+ * })
+ * 
+ * ActivityIndicator({
+ *   flex: 1,
+ *   justifyContent: 'center',
+ *   alignItems: 'center'
+ * }, {
+ *   animating: isLoading,
+ *   hidesWhenStopped: true,
+ *   size: 40
+ * })
+ */
+export function ActivityIndicator(
+  style?: StyleObject,
+  props: ActivityIndicatorProps = {}
+): DFNode {
+  return createNode(
+    'ActivityIndicator',
+    {
+      style: style ?? {},
+      color: props.color ?? '#0077ff',
+      size: props.size ?? 'large',
+      hidesWhenStopped: props.hidesWhenStopped ?? true,
+      animating: props.animating ?? true,
+    } as Record<string, unknown>,
+    []
+  )
+}
+
+export type { StyleObject }

package/packages/ui/src/overlay/Modal.ts

@@ -47,12 +47,36 @@ interface ModalProps {
 }
 
 // Creates a modal dialog overlay node
-// children — content displayed inside modal
-// props — modal configuration
+// Accepts multiple parameter combinations for flexibility
+// Modal(children, props) - new API
+// Modal(visible, onClose, style, children) - backward compatible
 function Modal(
-  children: DFNode[],
-  props:    ModalProps
+  childrenOrVisible?: DFNode[] | boolean,
+  propsOrOnClose?: ModalProps | (() => void),
+  styleOrUndefined?: any,
+  childrenFallback?: DFNode[]
 ): DFNode {
+  let children: DFNode[] = []
+  let props: ModalProps = { open: false, onClose: () => {} }
+
+  // New API: Modal(children, props)
+  if (Array.isArray(childrenOrVisible)) {
+    children = childrenOrVisible
+    if (propsOrOnClose && typeof propsOrOnClose === 'object' && !Array.isArray(propsOrOnClose)) {
+      props = { ...props, ...propsOrOnClose as ModalProps }
+    }
+  }
+  // Old API: Modal(visible, onClose, style, children)
+  else if (typeof childrenOrVisible === 'boolean') {
+    props.open = childrenOrVisible
+    if (typeof propsOrOnClose === 'function') {
+      props.onClose = propsOrOnClose
+    }
+    if (Array.isArray(childrenFallback)) {
+      children = childrenFallback
+    }
+  }
+
   return createNode('Modal', {
     open:            props.open,
     onClose:         props.onClose,
@@ -66,8 +90,6 @@ function Modal(
     closeOnBackdrop: props.closeOnBackdrop ?? true,
     closeOnEscape:   props.closeOnEscape   ?? true,
     padding:         props.padding         ?? 24,
-
-    // Scale in animation from center
     animationType: 'scaleIn',
   } as Record<string, unknown>, children)
 }

package/packages/ui/src/platform/Platform.ts

@@ -0,0 +1,119 @@
+/**
+ * Platform Module
+ * 
+ * Cross-platform utilities for OS detection and platform-specific components.
+ * Provides OS constant and selection utilities.
+ * 
+ * No JSX. No HTML. No XML. Pure functional TypeScript.
+ */
+
+import type { DFNode } from '@deskforge/core'
+
+/**
+ * Supported platform OS types
+ */
+export type PlatformOS = 'windows' | 'macos' | 'linux' | 'ios' | 'android'
+
+/**
+ * Platform configuration options for select()
+ */
+export interface PlatformSelectOptions<T> {
+  ios?: T
+  android?: T
+  windows?: T
+  macos?: T
+  linux?: T
+  web?: T
+  native?: T
+  default?: T
+}
+
+/**
+ * Platform - Cross-platform utilities
+ * 
+ * Provides OS detection and platform-specific component/value selection.
+ * Enables building truly universal apps with single codebase.
+ */
+export const Platform = {
+  /**
+   * Get current operating system
+   * 
+   * @returns Current platform OS: 'windows' | 'macos' | 'linux' | 'ios' | 'android'
+   */
+  get OS(): PlatformOS {
+    if (typeof globalThis !== 'undefined') {
+      if (globalThis.navigator?.userAgent?.includes('iPhone')) return 'ios'
+      if (globalThis.navigator?.userAgent?.includes('Android')) return 'android'
+      if (globalThis.navigator?.userAgent?.includes('Windows')) return 'windows'
+      if (globalThis.navigator?.userAgent?.includes('Macintosh')) return 'macos'
+      if (globalThis.navigator?.userAgent?.includes('Linux')) return 'linux'
+    }
+    return 'linux' // default fallback
+  },
+
+  /**
+   * Select value based on platform
+   * 
+   * @param options - Object with platform keys and values
+   * @returns Value for current platform
+   * 
+   * @example
+   * Platform.select({
+   *   ios: 'padding',
+   *   android: 'height',
+   *   default: 'padding'
+   * })
+   */
+  select<T>(options: PlatformSelectOptions<T>): T {
+    const os = Platform.OS
+
+    if (os === 'ios' && options.ios !== undefined) return options.ios
+    if (os === 'android' && options.android !== undefined) return options.android
+    if (os === 'windows' && options.windows !== undefined) return options.windows
+    if (os === 'macos' && options.macos !== undefined) return options.macos
+    if (os === 'linux' && options.linux !== undefined) return options.linux
+
+    if (options.native !== undefined) return options.native
+    if (options.default !== undefined) return options.default
+
+    throw new Error(`No value provided for platform: ${os}`)
+  },
+
+  /**
+   * Render component on desktop platforms only (Windows, macOS, Linux)
+   * 
+   * @param node - DFNode to render on desktop
+   * @returns Node if on desktop, null otherwise
+   */
+  desktop(node: DFNode): DFNode | null {
+    const os = Platform.OS
+    if (os === 'windows' || os === 'macos' || os === 'linux') {
+      return node
+    }
+    return null
+  },
+
+  /**
+   * Render component on mobile platforms only (iOS, Android)
+   * 
+   * @param node - DFNode to render on mobile
+   * @returns Node if on mobile, null otherwise
+   */
+  mobile(node: DFNode): DFNode | null {
+    const os = Platform.OS
+    if (os === 'ios' || os === 'android') {
+      return node
+    }
+    return null
+  },
+
+  /**
+   * Render component on any platform
+   * 
+   * @param node - DFNode to always render
+   * @returns Node (always)
+   */
+  any(node: DFNode): DFNode {
+    return node
+  },
+}

package/packages/ui/src/platform/StatusBar.ts

@@ -0,0 +1,63 @@
+/**
+ * StatusBar Component
+ * 
+ * Controls platform status bar (mobile) styling and visibility.
+ * Platform-specific implementation handled by runtime.
+ * 
+ * No JSX. No HTML. No XML. Pure functional TypeScript.
+ */
+
+import { createNode } from '@deskforge/core'
+import type { DFNode } from '@deskforge/core'
+
+/**
+ * StatusBar configuration properties
+ */
+export interface StatusBarProps {
+  /** Status bar background color */
+  backgroundColor?: string
+  /** Status bar icon/text color: 'light-content' | 'dark-content' */
+  barStyle?: 'light-content' | 'dark-content'
+  /** Hidden state */
+  hidden?: boolean
+  /** Translucent (iOS) */
+  translucent?: boolean
+  /** Network activity indicator visible (iOS) */
+  networkActivityIndicatorVisible?: boolean
+}
+
+/**
+ * StatusBar - Platform status bar component
+ * 
+ * Configures the system status bar appearance. Platform-specific
+ * implementation on iOS and Android. Has no visual output on desktop.
+ * 
+ * @param props - StatusBarProps configuration
+ * @returns DFNode object with type 'StatusBar'
+ * 
+ * @example
+ * StatusBar({
+ *   backgroundColor: '#0077ff',
+ *   barStyle: 'light-content',
+ *   hidden: false
+ * })
+ * 
+ * StatusBar({
+ *   backgroundColor: '#fff',
+ *   barStyle: 'dark-content',
+ *   translucent: true
+ * })
+ */
+export function StatusBar(props: StatusBarProps = {}): DFNode {
+  return createNode(
+    'StatusBar',
+    {
+      backgroundColor: props.backgroundColor ?? '#000',
+      barStyle: props.barStyle ?? 'light-content',
+      hidden: props.hidden ?? false,
+      translucent: props.translucent ?? false,
+      networkActivityIndicatorVisible: props.networkActivityIndicatorVisible ?? false,
+    } as Record<string, unknown>,
+    []
+  )
+}