component-api

# Component API Reference Complete API reference for the cross-platform `UI::View` hierarchy defined in `src/ui/`. --- ## Value Types ### `UI::Color` RGBA color with floating-point components in the range 0.0 to 1.0. ```crystal record Color, r : Float64, g : Float64, b : Float64, a : Float64 = 1.0 ``` **Usage:** ```crystal red = UI::Color.new(r: 1.0, g: 0.0, b: 0.0) white = UI::Color.new(r: 1.0, g: 1.0, b: 1.0) semi = UI::Color.new(r: 0.0, g: 0.0, b: 0.0, a: 0.5) ``` ### `UI::Font` Font specification with family, size, weight, and italic flag. ```crystal record Font, family : String = "system", size : Float64 = 17.0, weight : Symbol = :regular, italic : Bool = false ``` **Weight values:** `:ultralight`, `:thin`, `:light`, `:regular`, `:medium`, `:semibold`, `:bold`, `:heavy`, `:black` **Usage:** ```crystal heading = UI::Font.new(size: 24.0, weight: :bold) mono = UI::Font.new(family: "monospace", size: 14.0) italic = UI::Font.new(weight: :medium, italic: true) default = UI::Font.new # system font, 17pt, regular ``` ### `UI::EdgeInsets` Edge insets for padding or margin values, in points. ```crystal record EdgeInsets, top : Float64 = 0.0, trailing : Float64 = 0.0, bottom : Float64 = 0.0, leading : Float64 = 0.0 ``` Note: Uses `leading`/`trailing` (not `left`/`right`) for RTL language support. **Usage:** ```crystal uniform = UI::EdgeInsets.new(top: 16.0, trailing: 16.0, bottom: 16.0, leading: 16.0) vertical = UI::EdgeInsets.new(top: 8.0, bottom: 8.0) none = UI::EdgeInsets.new # all zeros ``` ### `UI::ThemeColor` Semantic color in `UI::Theme`. Same RGBA structure as `UI::Color` but semantically scoped to theme roles. ```crystal record ThemeColor, r : Float64, g : Float64, b : Float64, a : Float64 = 1.0 ``` --- ## Enums ### `UI::Alignment` Controls alignment of children within stack layouts. ```crystal enum Alignment Leading # Left-aligned (or start, in RTL) Center # Center-aligned Trailing # Right-aligned (or end, in RTL) Top # Top-aligned (for HStack vertical alignment) Bottom # Bottom-aligned (for HStack vertical alignment) Fill # Stretch to fill available space end ``` - **VStack** uses `Leading`, `Center`, `Trailing`, `Fill` for horizontal alignment of children - **HStack** uses `Top`, `Center`, `Bottom`, `Fill` for vertical alignment of children - **ZStack** uses `Leading`, `Center`, `Trailing`, `Top`, `Bottom` for overlay positioning ### `UI::ContentMode` Controls how an image is scaled to fit its bounds. ```crystal enum ContentMode Fit # Scale to fit within bounds, preserving aspect ratio (may letterbox) Fill # Scale to fill bounds, preserving aspect ratio (may crop) Stretch # Scale to exactly fill bounds (may distort) end ``` ### `UI::KeyboardType` Hint for the platform's virtual keyboard type on mobile. ```crystal enum KeyboardType Default # Standard text keyboard EmailAddress # Keyboard optimized for email input (@ key prominent) NumberPad # Numeric-only keyboard PhonePad # Phone number keyboard URL # Keyboard optimized for URL input end ``` ### `UI::ToggleStyle` Visual style for `UI::Toggle`. ```crystal enum ToggleStyle Switch # iOS-style toggle switch (thumb that slides) Checkbox # Standard checkbox end ``` ### `UI::PickerStyle` Visual style for `UI::Picker`. ```crystal enum PickerStyle Wheel # Spinning wheel picker (iOS UIPickerView style) Segmented # Segmented control inline Menu # Dropdown/popup menu (default) Inline # Expanded inline end ``` ### `UI::DatePickerMode` What components the date picker shows. ```crystal enum DatePickerMode Date # Date only Time # Time only DateAndTime # Both date and time end ``` ### `UI::ProgressStyle` Visual style for `UI::ProgressView`. ```crystal enum ProgressStyle Linear # Horizontal progress bar Circular # Spinning circular progress end ``` ### `UI::ListStyle` Visual style for `UI::ListView`. ```crystal enum ListStyle Plain # No grouping, no separators between sections Inset # Rounded group sections with insets Grouped # Grouped with section headers InsetGrouped # Rounded grouped sections Sidebar # macOS-style sidebar list end ``` --- ## Abstract Base: `UI::View` **File:** `src/ui/view.cr` All concrete view types inherit from this abstract class. ```crystal abstract class UI::View # Identity & accessibility property id : String? = nil property accessibility_label : String? = nil # Layout property padding : EdgeInsets = EdgeInsets.new property background : Color? = nil property hidden : Bool = false property opacity : Float64 = 1.0 # Shape modifiers property corner_radius : Float64 = 0.0 property clip_to_bounds : Bool = false # Shadow modifier property shadow_radius : Float64 = 0.0 property shadow_color : Color? = nil property shadow_offset_x : Float64 = 0.0 property shadow_offset_y : Float64 = 0.0 # Border modifier property border_width : Float64 = 0.0 property border_color : Color? = nil # Blur modifier property blur_radius : Float64 = 0.0 # Size constraints property minimum_width : Float64? = nil property minimum_height : Float64? = nil property maximum_width : Float64? = nil property maximum_height : Float64? = nil abstract def accept(visitor : PlatformVisitor) end ``` | Property | Type | Default | Description | |----------|------|---------|-------------| | `id` | `String?` | `nil` | Optional identifier for lookup and testing | | `accessibility_label` | `String?` | `nil` | Screen reader label | | `padding` | `EdgeInsets` | all zeros | Content padding | | `background` | `Color?` | `nil` | Background color (nil = transparent/inherited) | | `hidden` | `Bool` | `false` | Whether the view is hidden from display | | `opacity` | `Float64` | `1.0` | Opacity from 0.0 (transparent) to 1.0 (opaque) | | `corner_radius` | `Float64` | `0.0` | Corner radius in points | | `clip_to_bounds` | `Bool` | `false` | Clip children to bounds | | `shadow_radius` | `Float64` | `0.0` | Shadow blur radius (0 = no shadow) | | `shadow_color` | `Color?` | `nil` | Shadow color | | `shadow_offset_x` | `Float64` | `0.0` | Shadow horizontal offset | | `shadow_offset_y` | `Float64` | `0.0` | Shadow vertical offset | | `border_width` | `Float64` | `0.0` | Border stroke width (0 = no border) | | `border_color` | `Color?` | `nil` | Border stroke color | | `blur_radius` | `Float64` | `0.0` | Blur radius (0 = no blur) | | `minimum_width` | `Float64?` | `nil` | Minimum width constraint | | `minimum_height` | `Float64?` | `nil` | Minimum height constraint | | `maximum_width` | `Float64?` | `nil` | Maximum width constraint | | `maximum_height` | `Float64?` | `nil` | Maximum height constraint | --- ## Concrete View Types ### P0 Base Views --- ### `UI::Label` **File:** `src/ui/views/label.cr` Read-only text display. ```crystal class UI::Label < UI::View property text : String property font : Font = Font.new property text_color : Color = Color.new(r: 0.0, g: 0.0, b: 0.0) property text_alignment : Alignment = Alignment::Leading property number_of_lines : Int32 = 0 def initialize(@text : String) end ``` | Property | Type | Default | Description | |----------|------|---------|-------------| | `text` | `String` | (required) | The displayed text content | | `font` | `Font` | system 17pt | Font specification | | `text_color` | `Color` | black | Text foreground color | | `text_alignment` | `Alignment` | `Leading` | Horizontal text alignment | | `number_of_lines` | `Int32` | `0` | Max lines to display (0 = unlimited) | **Example:** ```crystal title = UI::Label.new("Welcome Back") title.font = UI::Font.new(size: 28.0, weight: :bold) title.text_color = UI::Color.new(r: 0.2, g: 0.2, b: 0.2) title.text_alignment = UI::Alignment::Center ``` --- ### `UI::Button` **File:** `src/ui/views/button.cr` A tappable button with a text label. ```crystal class UI::Button < UI::View property label : String property font : Font = Font.new property foreground_color : Color = Color.new(r: 0.0, g: 0.478, b: 1.0) property disabled : Bool = false property on_tap : Proc(Nil)? = nil def initialize(@label : String) def initialize(@label : String, &block : -> Nil) end ``` | Property | Type | Default | Description | |----------|------|---------|-------------| | `label` | `String` | (required) | Button display text | | `font` | `Font` | system 17pt | Label font | | `foreground_color` | `Color` | system blue | Label and tint color | | `disabled` | `Bool` | `false` | Whether interaction is disabled | | `on_tap` | `Proc(Nil)?` | `nil` | Callback invoked on tap | **Example:** ```crystal save = UI::Button.new("Save") { puts "Saved!"; nil } delete = UI::Button.new("Delete") delete.foreground_color = UI::Color.new(r: 1.0, g: 0.0, b: 0.0) delete.on_tap = ->{ handle_delete; nil } ``` --- ### `UI::VStack` **File:** `src/ui/views/vstack.cr` Vertical stack layout. ```crystal class UI::VStack < UI::View property spacing : Float64 = 8.0 property alignment : Alignment = Alignment::Center getter children : Array(View) = [] of View def initialize(@spacing : Float64 = 8.0, @alignment : Alignment = Alignment::Center) def <<(child : View) : self end ``` --- ### `UI::HStack` **File:** `src/ui/views/hstack.cr` Horizontal stack layout. ```crystal class UI::HStack < UI::View property spacing : Float64 = 8.0 property alignment : Alignment = Alignment::Center getter children : Array(View) = [] of View def initialize(@spacing : Float64 = 8.0, @alignment : Alignment = Alignment::Center) def <<(child : View) : self end ``` ---