deskforge 1.0.0

package/packages/ui/src/display/Avatar.ts

@@ -0,0 +1,93 @@
+// Avatar.ts
+// User profile image component.
+// Shows image if src provided.
+// Falls back to initials if no image.
+// Online status indicator supported.
+// Circle shape by default.
+
+import { createNode } from '@deskforge/core/'
+import type { DFNode } from '@deskforge/core/'
+
+// Online status indicator options
+type AvatarStatus = 'online' | 'offline' | 'away' | 'busy'
+
+// Avatar size presets in pixels
+const AVATAR_SIZES = {
+  xs: 24,
+  sm: 32,
+  md: 48,
+  lg: 64,
+  xl: 96,
+}
+
+// Props for the Avatar component
+interface AvatarProps {
+  // Image source path or URL
+  src?:         string
+
+  // User name — used to generate initials fallback
+  name?:        string
+
+  // Size preset or exact pixel size
+  size?:        'xs' | 'sm' | 'md' | 'lg' | 'xl' | number
+
+  // Border radius — 999 for circle
+  radius?:      number
+
+  // Online status dot shown at bottom right
+  status?:      AvatarStatus
+
+  // Background color for initials fallback
+  background?:  string
+
+  // Text color for initials
+  color?:       string
+
+  // Border around avatar
+  border?:      string
+
+  // Called when avatar is tapped
+  onClick?:     () => void
+}
+
+// Extracts initials from a name string
+// 'Kofi Boakye' → 'KB'
+// 'Kofi'        → 'K'
+function getInitials(name: string): string {
+  const parts = name.trim().split(' ')
+  if (parts.length === 1) {
+    return (parts[0]?.[0] ?? '?').toUpperCase()
+  }
+  return (
+    (parts[0]?.[0] ?? '') +
+    (parts[parts.length - 1]?.[0] ?? '')
+  ).toUpperCase()
+}
+
+// Creates an avatar node
+// props — avatar configuration
+function Avatar(props: AvatarProps = {}): DFNode {
+  const sizeValue = typeof props.size === 'number'
+    ? props.size
+    : AVATAR_SIZES[props.size ?? 'md']
+
+  const initials = props.name
+    ? getInitials(props.name)
+    : '?'
+
+  return createNode('Avatar', {
+    src:        props.src,
+    name:       props.name,
+    initials,
+    size:       sizeValue,
+    radius:     props.radius     ?? 999,
+    status:     props.status,
+    background: props.background ?? 'primary',
+    color:      props.color      ?? 'white',
+    border:     props.border,
+    onClick:    props.onClick,
+  } as Record<string, unknown>, [])
+}
+
+export type { AvatarStatus, AvatarProps }
+export { Avatar, getInitials }

package/packages/ui/src/display/Badge.ts

@@ -0,0 +1,72 @@
+// Badge.ts
+// Small label component for counts and status.
+// Commonly placed on icons to show notification count.
+// Automatically sizes to content.
+// Pill shape by default.
+
+import { createNode } from '@deskforge/core/'
+import type { DFNode } from '@deskforge/core/'
+
+// Badge visual variants
+type BadgeVariant = 'filled' | 'outline' | 'subtle'
+
+// Props for the Badge component
+interface BadgeProps {
+  // Text or number displayed in badge
+  label:       string | number
+
+  // Background color or theme token
+  color?:      string
+
+  // Text color
+  textColor?:  string
+
+  // Visual variant
+  variant?:    BadgeVariant
+
+  // Size preset
+  size?:       'sm' | 'md' | 'lg'
+
+  // Border radius — full for pill shape
+  radius?:     number | string
+
+  // Whether badge pulses to draw attention
+  pulse?:      boolean
+
+  // Maximum number shown
+  // Numbers above this show as max+
+  // e.g. maxCount: 99 shows '99+' for 100
+  maxCount?:   number
+
+  // Called when badge is tapped
+  onClick?:    () => void
+}
+
+// Creates a badge label node
+// props — badge configuration
+function Badge(props: BadgeProps): DFNode {
+  // Format label — apply maxCount if number
+  let displayLabel: string = String(props.label)
+
+  if (
+    typeof props.label === 'number' &&
+    props.maxCount !== undefined &&
+    props.label > props.maxCount
+  ) {
+    displayLabel = `${props.maxCount}+`
+  }
+
+  return createNode('Badge', {
+    label:     displayLabel,
+    color:     props.color     ?? 'danger',
+    textColor: props.textColor ?? 'white',
+    variant:   props.variant   ?? 'filled',
+    size:      props.size      ?? 'md',
+    radius:    props.radius    ?? 'full',
+    pulse:     props.pulse     ?? false,
+    onClick:   props.onClick,
+  } as Record<string, unknown>, [])
+}
+
+export type { BadgeVariant, BadgeProps }
+export { Badge }

package/packages/ui/src/display/Card.ts

@@ -0,0 +1,82 @@
+// Card.ts
+// Surface container for grouped content.
+// The most commonly used display component.
+// Hover shadow elevation handled automatically by Skia.
+// Supports press animation for clickable cards.
+
+import { createNode } from '@deskforge/core/'
+import type { DFNode } from '@deskforge/core/'
+import type { DFStyle } from '@deskforge/theme/'
+
+// Props for the Card component
+interface CardProps {
+  // Inner padding
+  padding?:    number | string
+
+  // Border radius
+  radius?:     number | string
+
+  // Shadow elevation token
+  shadow?:     'none' | 'sm' | 'md' | 'lg' | 'xl'
+
+  // Background color or theme token
+  background?: string
+
+  // Border definition
+  border?:     string
+
+  // Width constraint
+  width?:      number | string
+
+  // Height constraint
+  height?:     number | string
+
+  // Flex weight
+  flex?:       number
+
+  // Opacity 0 to 1
+  opacity?:    number
+
+  // Whether card is clickable
+  // Adds hover and press animations automatically
+  clickable?:  boolean
+
+  // Called when card is tapped
+  onClick?:    () => void
+
+  // Full style object override
+  style?:      DFStyle
+}
+
+// Creates a card surface node
+// children — content displayed inside the card
+// props — card styling configuration
+function Card(
+  children: DFNode[],
+  props:    CardProps = {}
+): DFNode {
+  return createNode('Card', {
+    padding:    props.padding    ?? 16,
+    radius:     props.radius     ?? 'md',
+    shadow:     props.shadow     ?? 'sm',
+    background: props.background ?? 'surface',
+    border:     props.border,
+    width:      props.width,
+    height:     props.height,
+    flex:       props.flex,
+    opacity:    props.opacity    ?? 1,
+    clickable:  props.clickable  ?? (props.onClick !== undefined),
+    onClick:    props.onClick,
+    style:      props.style,
+
+    // Hover and press animations
+    // Applied automatically when clickable is true
+    hoverShadow:  'md',
+    hoverScale:   1.01,
+    pressScale:   0.99,
+    animDuration: 150,
+  } as Record<string, unknown>, children)
+}
+
+export type { CardProps }
+export { Card }

package/packages/ui/src/display/Icon.ts

@@ -0,0 +1,75 @@
+// Icon.ts
+// Vector icon component.
+// Uses a built-in icon set — no icon library needed.
+// Icons are SVG paths rendered by Skia.
+// Zero font loading. Zero external dependencies.
+
+import { createNode } from '@deskforge/core/'
+import type { DFNode } from '@deskforge/core/'
+
+// Built-in icon names
+// This list grows as the framework matures
+type IconName =
+  | 'home'       | 'search'     | 'settings'
+  | 'user'       | 'users'      | 'bell'
+  | 'heart'      | 'star'       | 'bookmark'
+  | 'share'      | 'download'   | 'upload'
+  | 'edit'       | 'trash'      | 'copy'
+  | 'cut'        | 'paste'      | 'save'
+  | 'file'       | 'folder'     | 'image'
+  | 'video'      | 'audio'      | 'code'
+  | 'link'       | 'mail'       | 'phone'
+  | 'map'        | 'pin'        | 'pin-filled'
+  | 'calendar'   | 'clock'      | 'timer'
+  | 'plus'       | 'minus'      | 'close'
+  | 'check'      | 'chevron-up' | 'chevron-down'
+  | 'chevron-left'| 'chevron-right'| 'arrow-left'
+  | 'arrow-right'| 'arrow-up'   | 'arrow-down'
+  | 'menu'       | 'more'       | 'grid'
+  | 'list'       | 'filter'     | 'sort'
+  | 'lock'       | 'unlock'     | 'eye'
+  | 'eye-off'    | 'info'       | 'warning'
+  | 'error'      | 'success'    | 'help'
+  | 'sun'        | 'moon'       | 'cloud'
+  | 'wifi'       | 'bluetooth'  | 'battery'
+  | 'send'       | 'inbox'      | 'archive'
+  | 'refresh'    | 'loading'    | 'drag'
+  | string       // custom icon names
+
+// Props for the Icon component
+interface IconProps {
+  // Icon name from built-in set
+  name:     IconName
+
+  // Size in pixels — width and height equal
+  size?:    number
+
+  // Icon color or theme token
+  color?:   string
+
+  // Opacity 0 to 1
+  opacity?: number
+
+  // Called when icon is tapped
+  onClick?: () => void
+
+  // Tooltip shown on hover
+  tooltip?: string
+}
+
+// Creates an icon node
+// Icon SVG path is looked up by name in renderer
+// props — icon configuration
+function Icon(props: IconProps): DFNode {
+  return createNode('Icon', {
+    name:    props.name,
+    size:    props.size    ?? 20,
+    color:   props.color   ?? 'text',
+    opacity: props.opacity ?? 1,
+    onClick: props.onClick,
+    tooltip: props.tooltip,
+  } as Record<string, unknown>, [])
+}
+
+export type { IconName, IconProps }
+export { Icon }

package/packages/ui/src/display/Image.ts

@@ -0,0 +1,80 @@
+// Image.ts
+// Image display component.
+// Handles loading, error, and placeholder states.
+// Supports object-fit modes like CSS background-size.
+// Rendered by Skia with hardware acceleration.
+
+import { createNode } from '@deskforge/core/'
+import type { DFNode } from '@deskforge/core/'
+
+// How image fits its container
+type ImageFit = 'cover' | 'contain' | 'fill' | 'none'
+
+// Props for the Image component
+interface ImageProps {
+  // Image source path or URL
+  src:          string
+
+  // Accessibility description
+  alt?:         string
+
+  // Width in pixels or percentage
+  width?:       number | string
+
+  // Height in pixels or percentage
+  height?:      number | string
+
+  // How image fits its bounds
+  fit?:         ImageFit
+
+  // Border radius
+  radius?:      number | string
+
+  // Opacity 0 to 1
+  opacity?:     number
+
+  // Flex weight
+  flex?:        number
+
+  // Placeholder shown while loading
+  placeholder?: string
+
+  // Whether image is draggable
+  draggable?:   boolean
+
+  // Called when image finishes loading
+  onLoad?:      () => void
+
+  // Called when image fails to load
+  onError?:     () => void
+
+  // Called when image is tapped
+  onClick?:     () => void
+
+  // Whether to cache image in memory
+  cache?:       boolean
+}
+
+// Creates an image node
+// props — image configuration
+function Image(props: ImageProps): DFNode {
+  return createNode('Image', {
+    src:         props.src,
+    alt:         props.alt         ?? '',
+    width:       props.width,
+    height:      props.height,
+    fit:         props.fit         ?? 'cover',
+    radius:      props.radius      ?? 0,
+    opacity:     props.opacity     ?? 1,
+    flex:        props.flex,
+    placeholder: props.placeholder,
+    draggable:   props.draggable   ?? false,
+    onLoad:      props.onLoad,
+    onError:     props.onError,
+    onClick:     props.onClick,
+    cache:       props.cache       ?? true,
+  } as Record<string, unknown>, [])
+}
+
+export type { ImageFit, ImageProps }
+export { Image }

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

@@ -0,0 +1,8 @@
+// index.ts
+// Public door into the display components.
+
+export * from './Card'
+export * from './Avatar'
+export * from './Badge'
+export * from './Image'
+export * from './Icon'

package/packages/ui/src/feedback/EmptyState.ts

@@ -0,0 +1,56 @@
+// EmptyState.ts
+// Shown when a list or view has no content.
+// Icon, title, message, and optional action button.
+// Centered by default — fills available space.
+// Replaces blank white screens with helpful guidance.
+
+import { createNode } from '@deskforge/core/'
+import type { DFNode } from '@deskforge/core/'
+import type { IconName } from '../display/Icon'
+
+// Props for the EmptyState component
+interface EmptyStateProps {
+  // Icon shown at top
+  icon?:     IconName
+
+  // Main heading text
+  title:     string
+
+  // Descriptive message below title
+  message?:  string
+
+  // Optional action button
+  // e.g. Button('Create Note', { onClick: openCreate })
+  action?:   DFNode
+
+  // Icon size
+  iconSize?: number
+
+  // Icon color
+  iconColor?: string
+
+  // Text alignment
+  align?:    'left' | 'center' | 'right'
+
+  // Max width of content
+  maxWidth?: number
+}
+
+// Creates an empty state node
+// Shows when no content is available
+// props — empty state configuration
+function EmptyState(props: EmptyStateProps): DFNode {
+  return createNode('EmptyState', {
+    icon:      props.icon,
+    title:     props.title,
+    message:   props.message,
+    action:    props.action,
+    iconSize:  props.iconSize  ?? 48,
+    iconColor: props.iconColor ?? 'textMuted',
+    align:     props.align     ?? 'center',
+    maxWidth:  props.maxWidth  ?? 320,
+  } as Record<string, unknown>, [])
+}
+
+export type { EmptyStateProps }
+export { EmptyState }

package/packages/ui/src/feedback/Skeleton.ts

@@ -0,0 +1,53 @@
+// Skeleton.ts
+// Loading placeholder component.
+// Shows animated shimmer while content loads.
+// Matches the shape of the content it replaces.
+// Renders as a shimmering rounded rectangle by Skia.
+
+import { createNode } from '@deskforge/core/'
+import type { DFNode } from '@deskforge/core/'
+
+// Props for the Skeleton component
+interface SkeletonProps {
+  // Width of skeleton placeholder
+  width?:     number | string
+
+  // Height of skeleton placeholder
+  height?:    number | string
+
+  // Border radius
+  radius?:    number | string
+
+  // Whether shimmer animation plays
+  animate?:   boolean
+
+  // Base color of skeleton
+  color?:     string
+
+  // Shimmer highlight color
+  shimmer?:   string
+
+  // Margin around skeleton
+  margin?:    number | string
+
+  // Flex weight
+  flex?:      number
+}
+
+// Creates a skeleton loading placeholder node
+// props — skeleton dimensions and styling
+function Skeleton(props: SkeletonProps = {}): DFNode {
+  return createNode('Skeleton', {
+    width:   props.width   ?? '100%',
+    height:  props.height  ?? 20,
+    radius:  props.radius  ?? 'sm',
+    animate: props.animate ?? true,
+    color:   props.color   ?? 'surfaceAlt',
+    shimmer: props.shimmer ?? 'surface',
+    margin:  props.margin  ?? 0,
+    flex:    props.flex,
+  } as Record<string, unknown>, [])
+}
+
+export type { SkeletonProps }
+export { Skeleton }

package/packages/ui/src/feedback/Spinner.ts

@@ -0,0 +1,61 @@
+// Spinner.ts
+// Loading indicator component.
+// Animated spinning circle rendered by Skia.
+// Uses spin animation from the animation system.
+// Shown automatically by Button when loading prop is true.
+
+import { createNode } from '@deskforge/core/'
+import type { DFNode } from '@deskforge/core/'
+
+// Spinner size presets in pixels
+const SPINNER_SIZES = {
+  xs: 12,
+  sm: 16,
+  md: 24,
+  lg: 32,
+  xl: 48,
+}
+
+// Props for the Spinner component
+interface SpinnerProps {
+  // Size preset or exact pixel size
+  size?:      'xs' | 'sm' | 'md' | 'lg' | 'xl' | number
+
+  // Spinner track color
+  color?:     string
+
+  // Background track color
+  trackColor?: string
+
+  // Track thickness in pixels
+  thickness?: number
+
+  // Animation speed in milliseconds per rotation
+  speed?:     number
+
+  // Opacity 0 to 1
+  opacity?:   number
+}
+
+// Creates a loading spinner node
+// props — spinner configuration
+function Spinner(props: SpinnerProps = {}): DFNode {
+  const sizeValue = typeof props.size === 'number'
+    ? props.size
+    : SPINNER_SIZES[props.size ?? 'md']
+
+  return createNode('Spinner', {
+    size:       sizeValue,
+    color:      props.color      ?? 'primary',
+    trackColor: props.trackColor ?? 'border',
+    thickness:  props.thickness  ?? Math.max(2, sizeValue / 8),
+    speed:      props.speed      ?? 800,
+    opacity:    props.opacity    ?? 1,
+
+    // Spin animation — handled by renderer
+    animate:    'spin',
+  } as Record<string, unknown>, [])
+}
+
+export type { SpinnerProps }
+export { Spinner }

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

@@ -0,0 +1,6 @@
+// index.ts
+// Public door into the feedback components.
+
+export * from './Spinner'
+export * from './Skeleton'
+export * from './EmptyState'

package/packages/ui/src/index.ts

@@ -0,0 +1,33 @@
+// index.ts
+// Public door into the entire UI package.
+// Import any component from here.
+
+// Layout components
+export * from './layout/index'
+
+// Typography components
+export * from './typography/index'
+
+// Input components
+export * from './input/index'
+
+// Display components
+export * from './display/index'
+
+// Feedback components
+export * from './feedback/index'
+
+// Navigation components
+export * from './navigation/index'
+
+// Overlay components
+export * from './overlay/index'
+
+// Data components
+export * from './data/index'
+
+// Chart components
+export * from './charts/index'
+
+// Add this line to packages/ui/src/index.ts
+export * from './conditional/If'