deskforge 1.0.0

package/packages/ui/src/layout/Box.ts

@@ -0,0 +1,94 @@
+// Box.ts
+// Generic container component.
+// The most flexible layout primitive.
+// Use when Column and Row do not fit the need.
+// Accepts any style and renders children inside.
+
+import { createNode } from '@deskforge/core/'
+import type { DFNode } from '@deskforge/core/'
+import type { DFStyle } from '@deskforge/theme/'
+
+// Props for the Box component
+interface BoxProps {
+  // Inner padding
+  padding?:    number | string
+
+  // Outer margin
+  margin?:     number | string
+
+  // Background color or theme token
+  background?: string
+
+  // Border radius
+  radius?:     number | string
+
+  // Shadow token
+  shadow?:     string
+
+  // Border definition
+  border?:     string
+
+  // Width constraint
+  width?:      number | string
+
+  // Height constraint
+  height?:     number | string
+
+  // Minimum width
+  minWidth?:   number
+
+  // Maximum width
+  maxWidth?:   number
+
+  // Minimum height
+  minHeight?:  number
+
+  // Maximum height
+  maxHeight?:  number
+
+  // Flex weight
+  flex?:       number
+
+  // Opacity 0 to 1
+  opacity?:    number
+
+  // Whether box clips overflow content
+  clip?:       boolean
+
+  // Full style object override
+  style?:      DFStyle
+
+  // Click handler
+  onClick?:    () => void
+}
+
+// Creates a generic container node
+// children — any DFNode children
+// props — box styling and constraints
+function Box(
+  children: DFNode[],
+  props:    BoxProps = {}
+): DFNode {
+  return createNode('Box', {
+    padding:    props.padding    ?? 0,
+    margin:     props.margin     ?? 0,
+    background: props.background ?? 'transparent',
+    radius:     props.radius     ?? 0,
+    shadow:     props.shadow,
+    border:     props.border,
+    width:      props.width,
+    height:     props.height,
+    minWidth:   props.minWidth,
+    maxWidth:   props.maxWidth,
+    minHeight:  props.minHeight,
+    maxHeight:  props.maxHeight,
+    flex:       props.flex,
+    opacity:    props.opacity    ?? 1,
+    clip:       props.clip       ?? false,
+    style:      props.style,
+    onClick:    props.onClick,
+  } as Record<string, unknown>, children)
+}
+
+export type { BoxProps }
+export { Box }

package/packages/ui/src/layout/Column.ts

@@ -0,0 +1,86 @@
+// Column.ts
+// Vertical stack layout component.
+// Arranges children top to bottom.
+// The most commonly used layout in DeskForge.
+// Gap and padding use theme spacing tokens.
+
+import { createNode } from '@deskforge/core/'
+import type { DFNode } from '@deskforge/core/'
+import type { DFStyle } from '@deskforge/theme/'
+
+// Props for the Column component
+interface ColumnProps {
+  // Space between children
+  gap?:        number | string
+
+  // Inner padding
+  padding?:    number | string |
+               [number, number] |
+               [number, number, number, number]
+
+  // Child alignment on horizontal axis
+  align?:      'start' | 'center' | 'end' | 'stretch'
+
+  // Child distribution on vertical axis
+  justify?:    'start' | 'center' | 'end' |
+               'space-between' | 'space-around'
+
+  // Background color or theme token
+  background?: string
+
+  // Border radius or theme token
+  radius?:     number | string
+
+  // Shadow token
+  shadow?:     string
+
+  // Border definition
+  border?:     string
+
+  // Flex weight — how much space to take
+  flex?:       number
+
+  // Width constraint
+  width?:      number | string
+
+  // Height constraint
+  height?:     number | string
+
+  // Whether content wraps
+  wrap?:       boolean
+
+  // Full style object override
+  style?:      DFStyle
+
+  // Scroll direction if content overflows
+  scroll?:     'vertical' | 'none'
+}
+
+// Creates a vertical stack of child nodes
+// children — array of DFNode to stack vertically
+// props — layout configuration
+function Column(
+  children: DFNode[],
+  props:    ColumnProps = {}
+): DFNode {
+  return createNode('Column', {
+    gap:        props.gap        ?? 0,
+    padding:    props.padding    ?? 0,
+    align:      props.align      ?? 'stretch',
+    justify:    props.justify    ?? 'start',
+    background: props.background ?? 'transparent',
+    radius:     props.radius     ?? 0,
+    shadow:     props.shadow,
+    border:     props.border,
+    flex:       props.flex,
+    width:      props.width,
+    height:     props.height,
+    wrap:       props.wrap       ?? false,
+    scroll:     props.scroll     ?? 'none',
+    style:      props.style,
+    direction:  'column',
+  } as Record<string, unknown>, children)
+}
+
+export type { ColumnProps }
+export { Column }

package/packages/ui/src/layout/Divider.ts

@@ -0,0 +1,50 @@
+// Divider.ts
+// Visual separator line between content sections.
+// Can be horizontal or vertical.
+// Thickness, color, and margin are configurable.
+// Rendered by Skia as a single line draw call.
+
+import { createNode } from '@deskforge/core/'
+import type { DFNode } from '@deskforge/core/'
+
+// Props for the Divider component
+interface DividerProps {
+  // Line direction
+  direction?: 'horizontal' | 'vertical'
+
+  // Line color or theme token
+  color?:     string
+
+  // Line thickness in pixels
+  thickness?: number
+
+  // Space around the divider
+  margin?:    number | string
+
+  // Line opacity 0 to 1
+  opacity?:   number
+
+  // Dashed line style
+  dashed?:    boolean
+
+  // Length as percentage or pixels
+  // Defaults to 100%
+  length?:    number | string
+}
+
+// Creates a visual separator line
+// Used between sections, list items, and form groups
+function Divider(props: DividerProps = {}): DFNode {
+  return createNode('Divider', {
+    direction: props.direction ?? 'horizontal',
+    color:     props.color     ?? 'border',
+    thickness: props.thickness ?? 1,
+    margin:    props.margin    ?? 0,
+    opacity:   props.opacity   ?? 1,
+    dashed:    props.dashed    ?? false,
+    length:    props.length    ?? '100%',
+  } as Record<string, unknown>, [])
+}
+
+export type { DividerProps }
+export { Divider }

package/packages/ui/src/layout/Grid.ts

@@ -0,0 +1,62 @@
+// Grid.ts
+// Fixed column grid layout.
+// Arranges children in equal-width columns.
+// Used for card grids, image galleries, dashboards.
+
+import { createNode } from '@deskforge/core/'
+import type { DFNode } from '@deskforge/core/'
+import type { DFStyle } from '@deskforge/theme/'
+
+// Props for the Grid component
+interface GridProps {
+  // Number of columns
+  columns:     number
+
+  // Space between grid items
+  gap?:        number | string
+
+  // Space between rows specifically
+  rowGap?:     number | string
+
+  // Space between columns specifically
+  columnGap?:  number | string
+
+  // Inner padding
+  padding?:    number | string
+
+  // Background color
+  background?: string
+
+  // Border radius
+  radius?:     number | string
+
+  // Width constraint
+  width?:      number | string
+
+  // Full style object override
+  style?:      DFStyle
+}
+
+// Creates a fixed column grid layout
+// children — items to place in the grid
+// props — grid configuration
+function Grid(
+  children: DFNode[],
+  props:    GridProps
+): DFNode {
+  return createNode('Grid', {
+    columns:    props.columns,
+    gap:        props.gap        ?? 0,
+    rowGap:     props.rowGap     ?? props.gap ?? 0,
+    columnGap:  props.columnGap  ?? props.gap ?? 0,
+    padding:    props.padding    ?? 0,
+    background: props.background ?? 'transparent',
+    radius:     props.radius     ?? 0,
+    width:      props.width,
+    style:      props.style,
+    direction:  'grid',
+  } as Record<string, unknown>, children)
+}
+
+export type { GridProps }
+export { Grid }

package/packages/ui/src/layout/Row.ts

@@ -0,0 +1,77 @@
+// Row.ts
+// Horizontal stack layout component.
+// Arranges children left to right.
+// Used for toolbars, form rows, and inline content.
+
+import { createNode } from '@deskforge/core/'
+import type { DFNode } from '@deskforge/core/'
+import type { DFStyle } from '@deskforge/theme/'
+
+// Props for the Row component
+interface RowProps {
+  // Space between children
+  gap?:        number | string
+
+  // Inner padding
+  padding?:    number | string |
+               [number, number] |
+               [number, number, number, number]
+
+  // Child alignment on vertical axis
+  align?:      'start' | 'center' | 'end' | 'stretch'
+
+  // Child distribution on horizontal axis
+  justify?:    'start' | 'center' | 'end' |
+               'space-between' | 'space-around'
+
+  // Background color or theme token
+  background?: string
+
+  // Border radius
+  radius?:     number | string
+
+  // Shadow token
+  shadow?:     string
+
+  // Whether children wrap to next line
+  wrap?:       boolean
+
+  // Flex weight
+  flex?:       number
+
+  // Width constraint
+  width?:      number | string
+
+  // Height constraint
+  height?:     number | string
+
+  // Full style object override
+  style?:      DFStyle
+}
+
+// Creates a horizontal stack of child nodes
+// children — array of DFNode to arrange horizontally
+// props — layout configuration
+function Row(
+  children: DFNode[],
+  props:    RowProps = {}
+): DFNode {
+  return createNode('Row', {
+    gap:        props.gap        ?? 0,
+    padding:    props.padding    ?? 0,
+    align:      props.align      ?? 'center',
+    justify:    props.justify    ?? 'start',
+    background: props.background ?? 'transparent',
+    radius:     props.radius     ?? 0,
+    shadow:     props.shadow,
+    wrap:       props.wrap       ?? false,
+    flex:       props.flex,
+    width:      props.width,
+    height:     props.height,
+    style:      props.style,
+    direction:  'row',
+  } as Record<string, unknown>, children)
+}
+
+export type { RowProps }
+export { Row }

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

@@ -0,0 +1,64 @@
+// ScrollView.ts
+// Scrollable container for content that exceeds bounds.
+// Shows scrollbar automatically when content overflows.
+// Works on desktop with mouse wheel and mobile with touch.
+
+import { createNode } from '@deskforge/core/'
+import type { DFNode } from '@deskforge/core/'
+import type { DFStyle } from '@deskforge/theme/'
+
+// Scroll direction options
+type ScrollDirection = 'vertical' | 'horizontal' | 'both'
+
+// Props for the ScrollView component
+interface ScrollViewProps {
+  // Which direction scrolling is allowed
+  direction?:      ScrollDirection
+
+  // Whether to show the scrollbar
+  showScrollbar?:  boolean
+
+  // Whether to show scrollbar only on hover
+  hideScrollbar?:  boolean
+
+  // Padding inside the scroll area
+  padding?:        number | string
+
+  // Background color
+  background?:     string
+
+  // Width constraint
+  width?:          number | string
+
+  // Height constraint — required for vertical scroll
+  height?:         number | string
+
+  // Called when scroll position changes
+  onScroll?:       (x: number, y: number) => void
+
+  // Full style object override
+  style?:          DFStyle
+}
+
+// Creates a scrollable container
+// children — content that may overflow and scroll
+// props — scroll configuration
+function ScrollView(
+  children: DFNode[],
+  props:    ScrollViewProps = {}
+): DFNode {
+  return createNode('ScrollView', {
+    direction:     props.direction     ?? 'vertical',
+    showScrollbar: props.showScrollbar ?? true,
+    hideScrollbar: props.hideScrollbar ?? false,
+    padding:       props.padding       ?? 0,
+    background:    props.background    ?? 'transparent',
+    width:         props.width,
+    height:        props.height,
+    onScroll:      props.onScroll,
+    style:         props.style,
+  } as Record<string, unknown>, children)
+}
+
+export type { ScrollDirection, ScrollViewProps }
+export { ScrollView }

package/packages/ui/src/layout/Spacer.ts

@@ -0,0 +1,34 @@
+// Spacer.ts
+// Fills available space in a Row or Column.
+// Pushes siblings to opposite ends.
+// Like CSS flex: 1 on an empty element.
+// Use between items to spread them apart.
+
+import { createNode } from '@deskforge/core/'
+import type { DFNode } from '@deskforge/core/'
+
+// Props for the Spacer component
+interface SpacerProps {
+  // Fixed size in pixels
+  // If not provided — fills all available space
+  size?: number
+
+  // Direction of the spacer
+  // Defaults to match parent direction
+  direction?: 'horizontal' | 'vertical'
+}
+
+// Creates a flexible space filler
+// With no size — takes all remaining space in parent
+// With size — acts as a fixed gap of that size
+function Spacer(props: SpacerProps = {}): DFNode {
+  return createNode('Spacer', {
+    size:      props.size,
+    direction: props.direction,
+    // flex: 1 when no fixed size — fills remaining space
+    flex:      props.size ? undefined : 1,
+  } as Record<string, unknown>, [])
+}
+
+export type { SpacerProps }
+export { Spacer }

package/packages/ui/src/layout/Stack.ts

@@ -0,0 +1,54 @@
+// Stack.ts
+// Overlapping layer layout — z-axis stacking.
+// Children are placed on top of each other.
+// Used for overlays, badges on avatars,
+// background images with text on top.
+
+import { createNode } from '@deskforge/core/'
+import type { DFNode } from '@deskforge/core/'
+import type { DFStyle } from '@deskforge/theme/'
+
+// Props for the Stack component
+interface StackProps {
+  // How to align overlapping children
+  align?:      'top-left'    | 'top-center'    | 'top-right'    |
+               'center-left' | 'center'        | 'center-right' |
+               'bottom-left' | 'bottom-center' | 'bottom-right'
+
+  // Width of the stack
+  width?:      number | string
+
+  // Height of the stack
+  height?:     number | string
+
+  // Background color
+  background?: string
+
+  // Border radius
+  radius?:     number | string
+
+  // Full style object override
+  style?:      DFStyle
+}
+
+// Creates an overlapping layer layout
+// First child is at the bottom — last child is on top
+// children — nodes to stack on top of each other
+// props — stack configuration
+function Stack(
+  children: DFNode[],
+  props:    StackProps = {}
+): DFNode {
+  return createNode('Stack', {
+    align:      props.align      ?? 'center',
+    width:      props.width,
+    height:     props.height,
+    background: props.background ?? 'transparent',
+    radius:     props.radius     ?? 0,
+    style:      props.style,
+    direction:  'stack',
+  } as Record<string, unknown>, children)
+}
+
+export type { StackProps }
+export { Stack }

package/packages/ui/src/layout/index.ts

@@ -0,0 +1,11 @@
+// index.ts
+// Public door into the layout components.
+
+export * from './Column'
+export * from './Row'
+export * from './Grid'
+export * from './Stack'
+export * from './ScrollView'
+export * from './Box'
+export * from './Spacer'
+export * from './Divider'

package/packages/ui/src/navigation/BottomNav.ts

@@ -0,0 +1,73 @@
+// BottomNav.ts
+// Bottom navigation bar for mobile apps.
+// Fixed at bottom of screen.
+// Active item indicator animates between items.
+// Standard mobile navigation pattern.
+
+import { createNode } from '@deskforge/core/'
+import type { DFNode } from '@deskforge/core/'
+import type { IconName } from '../display/Icon'
+
+// A single bottom nav item
+interface BottomNavItem {
+  // Display label below icon
+  label:     string
+
+  // Icon shown above label
+  icon:      IconName
+
+  // Route name to navigate to
+  screen?:   string
+
+  // Badge count shown on icon
+  badge?:    number
+
+  // Whether item is disabled
+  disabled?: boolean
+}
+
+// Props for the BottomNav component
+interface BottomNavProps {
+  // Navigation items
+  items:      BottomNavItem[]
+
+  // Currently active item index
+  active:     number
+
+  // Called when item is tapped
+  onChange:   (index: number) => void
+
+  // Active item color
+  color?:     string
+
+  // Inactive item color
+  inactiveColor?: string
+
+  // Background color
+  background?: string
+
+  // Whether to show labels
+  showLabels?: boolean
+
+  // Height of the nav bar
+  height?:    number
+}
+
+// Creates a bottom navigation bar node
+// Fixed at the bottom of the screen on mobile
+// props — bottom nav configuration
+function BottomNav(props: BottomNavProps): DFNode {
+  return createNode('BottomNav', {
+    items:         props.items,
+    active:        props.active,
+    onChange:      props.onChange,
+    color:         props.color         ?? 'primary',
+    inactiveColor: props.inactiveColor ?? 'textMuted',
+    background:    props.background    ?? 'surface',
+    showLabels:    props.showLabels    ?? true,
+    height:        props.height        ?? 64,
+  } as Record<string, unknown>, [])
+}
+
+export type { BottomNavItem, BottomNavProps }
+export { BottomNav }

package/packages/ui/src/navigation/Drawer.ts

@@ -0,0 +1,72 @@
+// Drawer.ts
+// Slide-in panel from screen edge.
+// Used for side menus and option sheets.
+// Backdrop dims the content behind it.
+// Slides in with spring animation automatically.
+
+import { createNode } from '@deskforge/core/'
+import type { DFNode } from '@deskforge/core/'
+
+// Which edge the drawer slides in from
+type DrawerPosition = 'left' | 'right' | 'top' | 'bottom'
+
+// Props for the Drawer component
+interface DrawerProps {
+  // Whether drawer is currently open
+  open:        boolean
+
+  // Called when drawer should close
+  // e.g. user taps backdrop or swipes away
+  onClose:     () => void
+
+  // Which edge to slide in from
+  position?:   DrawerPosition
+
+  // Width for left/right drawers
+  width?:      number | string
+
+  // Height for top/bottom drawers
+  height?:     number | string
+
+  // Background color of drawer panel
+  background?: string
+
+  // Backdrop opacity 0 to 1
+  backdropOpacity?: number
+
+  // Whether tapping backdrop closes drawer
+  closeOnBackdrop?: boolean
+
+  // Whether swipe gesture closes drawer
+  swipeToClose?: boolean
+
+  // Border radius on open edge
+  radius?:     number
+}
+
+// Creates a drawer slide-in panel node
+// children — content rendered inside the drawer
+// props — drawer configuration
+function Drawer(
+  children: DFNode[],
+  props:    DrawerProps
+): DFNode {
+  return createNode('Drawer', {
+    open:             props.open,
+    onClose:          props.onClose,
+    position:         props.position         ?? 'left',
+    width:            props.width            ?? 280,
+    height:           props.height           ?? '100%',
+    background:       props.background       ?? 'surface',
+    backdropOpacity:  props.backdropOpacity  ?? 0.5,
+    closeOnBackdrop:  props.closeOnBackdrop  ?? true,
+    swipeToClose:     props.swipeToClose     ?? true,
+    radius:           props.radius           ?? 0,
+
+    // Spring animation for slide
+    animationType: 'spring',
+  } as Record<string, unknown>, children)
+}
+
+export type { DrawerPosition, DrawerProps }
+export { Drawer }