Run any Skill in Manus with one click

component-mapping-matrix

Stars5

Forks0

UpdatedApril 15, 2026 at 13:35

Comprehensive cross-platform UI component mapping matrix showing how every common UI pattern maps across Crystal UI::View, SwiftUI, UIKit, AppKit, Jetpack Compose, Android Views, and Web HTML/CSS. Implementation priority guide for expanding the asset_pipeline cross-platform component system.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

amberframework

amberframework/asset_pipeline

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

Component Mapping Matrix

This is the master reference for expanding the asset_pipeline cross-platform UI component system. Every row represents one component and shows its exact native equivalent on every supported platform.

1. How to Read This Matrix

Columns

Column	Meaning
Crystal UI::View	The abstract class name in `src/ui/views/`. This is what app developers write.
Priority	P0 = done/implemented, P3 = specialized stubs being upgraded. See Section 3.
SwiftUI	Apple's declarative framework equivalent. Useful for cross-referencing SwiftUI docs when designing the Crystal API.
UIKit	The imperative iOS class our ObjC bridge instantiates on `flag?(:ios)`. Exact class names for `objc_getClass()`.
AppKit	The imperative macOS class our ObjC bridge instantiates on `flag?(:macos)`. Exact class names for `objc_getClass()`.
Compose	Android Jetpack Compose function equivalent. Reference for the future declarative Android renderer.
Android View	The imperative Android class our JNI bridge instantiates on `flag?(:android)`. Exact class names for JNI `FindClass()`.
Web HTML/CSS	The HTML element and CSS our `Web::Renderer` emits.

Priority Tiers

P0 — Fully implemented. Working and tested across all 4 platform renderers.
Implemented — Class exists with full API; P3 stubs being upgraded to full renderer support in parallel.

Using This Matrix for Implementation

When adding a new component, use this matrix to:

Confirm all 4 platform equivalents before writing any Crystal code.
Note any platform divergences in the "Notes" column before designing the abstract API.
Track implementation status by updating the priority to P0 once all renderers are complete.
Identify which renderer visit methods to add (abstract def visit(view : NewView) in PlatformVisitor).

2. Complete Mapping Matrix

Text Display

Crystal UI::View	Priority	SwiftUI	UIKit	AppKit	Compose	Android View	Web HTML/CSS	Notes
`UI::Label`	P0	`Text`	`UILabel`	`NSTextField` (non-editable, no bezel, no background)	`Text()`	`TextView`	`<span>` with inline font/color styles	Done. AppKit uses NSTextField configured as a label, not NSText.
`UI::RichText`	P0	`Text` with `.attributedString`	`UITextView` (non-editable)	`NSTextView` (non-editable)	`AnnotatedString` in `Text()`	`TextView` with `SpannableString`	`<p>` or `<div>` with inner HTML	`Span` records with bold/italic/underline/strikethrough/link. `add_span()` builder. `plain_text` helper.
`UI::TextEditor`	P0	`TextEditor`	`UITextView` (editable)	`NSTextView` (editable)	`TextField(minLines=3)` or `BasicTextField`	`EditText` (multiline)	`<textarea>`	Multiline editor with optional line numbers and syntax highlighting hint.

Text Input

Crystal UI::View	Priority	SwiftUI	UIKit	AppKit	Compose	Android View	Web HTML/CSS	Notes
`UI::TextField`	P0	`TextField`	`UITextField`	`NSTextField` (editable) / `NSSecureTextField` for `secure_entry`	`TextField()` / `OutlinedTextField()`	`EditText`	`<input type="text">` or `<input type="password">`	Done. `secure_entry` property switches to NSSecureTextField / UITextField secureTextEntry / EditText inputType=textPassword.
`UI::SecureField`	P0	`SecureField`	`UITextField` (secureTextEntry=true)	`NSSecureTextField`	`TextField(visualTransformation=PasswordVisualTransformation)`	`EditText` (inputType=textPassword)	`<input type="password">`	Dedicated type for type-safe visitor dispatch. Always secure.
`UI::SearchField`	P0	`searchable()` modifier + `TextField`	`UISearchBar` or `UISearchTextField` (iOS 13+)	`NSSearchField`	`SearchBar()` or `DockedSearchBar()`	`SearchView`	`<input type="search">`	Has `on_submit` and `on_cancel` callbacks in addition to `on_change`.
`UI::TextArea`	P0	`TextEditor`	`UITextView` (editable)	`NSTextView` (editable)	`TextField(minLines=N)`	`EditText` (multiline, scrollbars)	`<textarea rows="N">`	Multiline text input with `line_limit`, `is_editable`, `is_scrollable`.

Buttons and Actions

Crystal UI::View	Priority	SwiftUI	UIKit	AppKit	Compose	Android View	Web HTML/CSS	Notes
`UI::Button`	P0	`Button`	`UIButton` (system style)	`NSButton` (bezelStyle=rounded)	`Button()` / `ElevatedButton()`	`MaterialButton` / `Button`	`<button type="button">`	Done. Foreground color, disabled state, on_tap callback.
`UI::IconButton`	P0	`Button { Image(...) }`	`UIButton` with `setImage:forState:`	`NSButton` with image + no title	`IconButton()`	`ImageButton`	`<button><img src=...></button>` or `<button class="icon-btn">`	SF Symbol / material icon / CSS icon class by platform. `icon_size`, `tint_color`, `disabled`.
`UI::LinkButton`	P0	`Link`	`UIButton` with URL action	`NSButton` + `NSWorkspace.openURL:`	`TextButton()` styled as link, or `ClickableText`	`Button` with URL intent	`<a href="...">`	`url` property. `opens_in_browser` flag. Optional `on_tap` override.
`UI::MenuButton`	P0	`Menu`	`UIMenu` + `UIButton` (iOS 14+ `menu` property)	`NSPopUpButton`	`DropdownMenu { ... }`	`PopupMenu` or `DropdownMenu`	`<select>` or custom `<div>` dropdown	`MenuItem` records with `is_destructive` flag. `add_item()` builder methods.
`UI::ToggleButton`	P0	`Toggle` (button style)	`UIButton` (checkboxConfiguration / selected state)	`NSButton` (buttonType=switch or toggle)	`FilledTonalButton()` with toggle state	`ToggleButton`	`<button aria-pressed="true/false">`	`is_selected`, `icon`, `on_toggle : Proc(Bool, Nil)`. `toggle()` convenience method.

Layout Containers

Crystal UI::View	Priority	SwiftUI	UIKit	AppKit	Compose	Android View	Web HTML/CSS	Notes
`UI::VStack`	P0	`VStack`	`UIStackView` (axis=.vertical)	`NSStackView` (orientation=vertical, 1)	`Column()`	`LinearLayout` (orientation=VERTICAL)	`<div style="display:flex;flex-direction:column">`	Done. Spacing and alignment supported.
`UI::HStack`	P0	`HStack`	`UIStackView` (axis=.horizontal)	`NSStackView` (orientation=horizontal, 0)	`Row()`	`LinearLayout` (orientation=HORIZONTAL)	`<div style="display:flex;flex-direction:row">`	Done.
`UI::ZStack`	P0	`ZStack`	`UIView` + Auto Layout constraints (or manual frames)	`NSView` + addSubview + autoresizing mask	`Box()`	`FrameLayout`	`<div style="position:relative">` with children `position:absolute`	Done. Children stack back-to-front in document order.
`UI::ScrollView`	P0	`ScrollView`	`UIScrollView`	`NSScrollView`	`LazyColumn()` / `LazyRow()` / `ScrollableColumn()`	`ScrollView` (vertical only) / `HorizontalScrollView`	`<div style="overflow:auto">`	Done. scroll_horizontal + scroll_vertical properties. Android ScrollView only scrolls one axis; HorizontalScrollView for horizontal.
`UI::Spacer`	P0	`Spacer`	`UILayoutGuide` (flexible space) or `UIView` with low compression	NSView with low hugging priority inside NSStackView	`Spacer()`	`Space` with `layout_weight=1`	`<div style="flex:1 1 0%">`	Done. min_length property sets minimum size.
`UI::Grid`	P0	`LazyVGrid` / `LazyHGrid`	`UICollectionView` with `UICollectionViewFlowLayout`	`NSCollectionView` with `NSCollectionViewGridLayout`	`LazyVerticalGrid()` / `LazyHorizontalGrid()`	`RecyclerView` with `GridLayoutManager`	CSS Grid: `<div style="display:grid;grid-template-columns:...">`	`Column` records with alignment + minimum_width. `add_row()` builder. `row_count`/`column_count` helpers.
`UI::ListView`	P0	`List`	`UITableView` or `UICollectionView` (iOS 14+ list)	`NSTableView` or `NSOutlineView`	`LazyColumn { items(...) }`	`RecyclerView` with `LinearLayoutManager`	`<ul>` or `<div>` with repeated child elements	`Section` records with header/footer. `ListView.flat()` convenience constructor. `on_item_tap : Proc(Int32, Int32, Nil)`.
`UI::Form`	P0	`Form`	`UITableView` (grouped / inset-grouped style)	`NSForm` or sectioned `NSTableView`	`Column()` with Section grouping	`RecyclerView` with section headers	`<form>` with fieldsets or Material-style card groupings	`FormSection` + `Field` records. `add_section()` builder. `field_count` helper.

Navigation

Crystal UI::View	Priority	SwiftUI	UIKit	AppKit	Compose	Android View	Web HTML/CSS	Notes
`UI::NavigationStack`	P0	`NavigationStack`	`UINavigationController`	`No direct equivalent` — use `NSWindowController` or `NSViewController` stack	`NavHost` + `NavController`	`FragmentManager` + back stack, or Navigation Component	Browser history + `<div>` visibility toggle	`push(view)`, `pop`, `pop_to_root`, `current_view`. `large_title`, `shows_navigation_bar` properties.
`UI::TabView`	P0	`TabView`	`UITabBarController`	`NSTabViewController`	`TabRow()` + `Scaffold(bottomBar=...)`	`BottomNavigationView` or `TabLayout` + `ViewPager2`	`<nav>` with tab styling or custom CSS tabs	`Tab` record with label/icon/content. `current_content` helper. `on_change : Proc(Int32, Nil)`.
`UI::NavigationSplitView`	P0	`NavigationSplitView`	`UISplitViewController`	`NSSplitViewController`	`NavigationSuiteScaffold`	`SlidingPaneLayout` or `NavigationDrawer`	CSS two-column layout or `<aside>` + `<main>`	sidebar/content/detail columns. `sidebar_width`, `shows_sidebar`, `column_visibility` (`:all`, `:double_column`, `:detail_only`).
`UI::NavigationLink`	P0	`NavigationLink`	`UINavigationController.pushViewController:`	No direct equivalent — trigger `NSViewController` presentation	`navController.navigate("route")`	`startActivity()` or `navController.navigate()`	`<a href="...">` or JS router `navigate()`	`label`, `destination`, `icon`, `shows_disclosure`. Pairs with NavigationStack.
`UI::Toolbar`	P0	`.toolbar {}` modifier	`UINavigationItem` toolbar / `UIToolbar`	`NSToolbar`	`TopAppBar()` / `CenterAlignedTopAppBar()`	`Toolbar` (androidx.appcompat)	`<header>` or `<nav>` with action buttons	`ToolbarItem` records. `add_item()` builder. `title`, `shows_title`.

Selection Controls

Crystal UI::View	Priority	SwiftUI	UIKit	AppKit	Compose	Android View	Web HTML/CSS	Notes
`UI::Toggle`	P0	`Toggle`	`UISwitch`	`NSButton` (buttonType=switch, setButtonType: 6)	`Switch()`	`SwitchMaterial` / `Switch` (androidx)	`<input type="checkbox" role="switch">`	`ToggleStyle` enum: `:Switch` or `:Checkbox`. `is_on`, `label`, `tint_color`, `on_change : Proc(Bool, Nil)`.
`UI::Checkbox`	P0	`Toggle` (checkbox style via `.toggleStyle(.checkbox)`)	No native UICheckbox — use `UIButton` with custom checkmark image	`NSButton` (buttonType=check, setButtonType: 3)	`Checkbox()`	`CheckBox` (android.widget)	`<input type="checkbox">`	`is_checked`, `label`, `on_change : Proc(Bool, Nil)`.
`UI::RadioGroup`	P0	`Picker` with `.pickerStyle(.radioGroup)`	No native UIRadioButton — use `UIButton` with selection state management	`NSButton` (buttonType=radio, setButtonType: 4)	`RadioButton()` inside `RadioGroup`	`RadioButton` + `RadioGroup`	`<input type="radio" name="group">`	`options : Array(String)`, `selected_index`, `on_change : Proc(Int32, Nil)`. Self-contained group.
`UI::Slider`	P0	`Slider`	`UISlider`	`NSSlider`	`Slider()`	`SeekBar` or `Slider` (material)	`<input type="range">`	`minimum`, `maximum`, `value`, `step` (0 = continuous), `label`, `tint_color`, `on_change : Proc(Float64, Nil)`.
`UI::Stepper`	P0	`Stepper`	`UIStepper`	`NSStepper`	No direct Compose equivalent — `Row` with `-`/`+` buttons	No native stepper — compose from `Button` + `TextView` + `Button`	`<input type="number">` or custom `-`/`+` buttons	`value`, `minimum`, `maximum`, `step_value`, `wraps`, `label`, `on_change`. `increment()`/`decrement()` helpers.
`UI::SegmentedControl`	P0	`Picker` with `.pickerStyle(.segmented)`	`UISegmentedControl`	`NSSegmentedControl`	`SegmentedButton()` (Material 3)	`RadioGroup` styled, or Material `SegmentedButton`	Custom CSS button group	`segments : Array(String)`, `selected_index`, `on_change`. `selected_segment` helper.

Pickers

Crystal UI::View	Priority	SwiftUI	UIKit	AppKit	Compose	Android View	Web HTML/CSS	Notes
`UI::Picker`	P0	`Picker` (default / wheel / menu style)	`UIPickerView` (wheel) or `UIButton` + `UIMenu`	`NSPopUpButton`	`ExposedDropdownMenuBox()`	`Spinner` or `AutoCompleteTextView` (dropdown)	`<select>`	`PickerStyle` enum: `Wheel`, `Segmented`, `Menu`, `Inline`. `selected_option` helper.
`UI::DatePicker`	P0	`DatePicker`	`UIDatePicker` (inline / compact / wheels styles)	`NSDatePicker` (text / stepper / clock display modes)	`DatePicker()` (Material dialogs)	`DatePickerDialog` or Material `DatePicker`	`<input type="date">`	`DatePickerMode` enum: `Date`, `Time`, `DateAndTime`. `minimum_date`/`maximum_date` bounds. `on_change : Proc(Time, Nil)`.
`UI::TimePicker`	P0	`DatePicker` (displayedComponents: .hourAndMinute)	`UIDatePicker` (.countDownTimer or hourAndMinute mode)	`NSDatePicker` (hour/minute display mode)	`TimePicker()` (Material dialogs)	`TimePickerDialog` or Material `TimePicker`	`<input type="time">`	`shows_24_hour`, `minute_interval`, `on_change : Proc(Time, Nil)`.
`UI::ColorPicker`	Implemented	`ColorPicker`	No native UIColorPicker in older iOS — use `UIColorPickerViewController` (iOS 14+)	`NSColorPanel` (singleton) or `NSColorWell`	No native Compose equivalent — custom or third-party	No native Android color picker — third-party library typically used	`<input type="color">`	`selected_color : Color`, `on_change : Proc(Color, Nil)`. P3 stub being upgraded.

Progress and Activity

Crystal UI::View	Priority	SwiftUI	UIKit	AppKit	Compose	Android View	Web HTML/CSS	Notes
`UI::ProgressView`	P0	`ProgressView(value:total:)`	`UIProgressView`	`NSProgressIndicator` (style=bar, indeterminate=false)	`LinearProgressIndicator()`	`ProgressBar` (horizontal style, android.widget)	`<progress value="X" max="Y">`	`ProgressStyle` enum: `Linear`, `Circular`. `value : Float64?` (nil = indeterminate). `tint_color`, `label`.
`UI::ActivityIndicator`	P0	`ProgressView()` (no value, spinner style)	`UIActivityIndicatorView`	`NSProgressIndicator` (style=spinning, indeterminate=true)	`CircularProgressIndicator()`	`ProgressBar` (circular / indeterminate style)	`<div class="spinner">` with CSS animation	`is_animating`, `size : Symbol` (`:small`, `:medium`, `:large`), `color`.

Images and Media

Crystal UI::View	Priority	SwiftUI	UIKit	AppKit	Compose	Android View	Web HTML/CSS	Notes
`UI::Image`	P0	`Image`	`UIImageView`	`NSImageView`	`Image()` (via `AsyncImage` or `painterResource`)	`ImageView`	`<img src="...">`	Done. source, content_mode, tint_color supported.
`UI::AsyncImage`	P0	`AsyncImage`	`UIImageView` + async download via `URLSession`	`NSImageView` + async download	`AsyncImage()` (Coil library integration)	`ImageView` + Glide / Coil / Picasso	`<img>` with lazy loading attribute, or CSS `background-image` loaded via JS fetch	`url`, `placeholder : View?`, `content_mode`, `is_loading`, `error_message`, `on_load`, `on_error : Proc(String, Nil)`.
`UI::VideoPlayer`	Implemented	`VideoPlayer` (AVKit)	`AVPlayerViewController` or `AVPlayerLayer`	`AVPlayerView` (AVKit on macOS)	`VideoPlayer()` (Media3 / ExoPlayer)	`VideoView` or `PlayerView` (Media3/ExoPlayer)	`<video src="...">`	`url`, `is_playing`, `shows_controls`. P3 stub being upgraded.

Visual Effects

Crystal UI::View	Priority	SwiftUI	UIKit	AppKit	Compose	Android View	Web HTML/CSS	Notes
`UI::GlassBackground`	P0	`.background(.ultraThinMaterial)` modifier	`UIVisualEffectView` (UIBlurEffect)	`NSVisualEffectView`	No direct equivalent — `BlurMask` modifier	No native blur/glass — compose with `RenderScript` or `BlurMaskFilter` (deprecated)	`backdrop-filter: blur(Xpx); background: rgba(...,0.5)`	`material` (`:thin`, `:ultra_thin`, `:regular`, `:thick`, `:chrome`), `is_vibrant`, `content`.
Shadow (base modifier)	P0	`.shadow(color:radius:x:y:)` modifier	`.layer.shadowColor`, `.layer.shadowRadius`, `.layer.shadowOffset`	`NSShadow` + `setShadow:`	`Modifier.shadow(elevation:)`	`setElevation()` for Material shadows or custom `Paint.setShadowLayer()`	`box-shadow: X Y blur spread color`	`shadow_radius`, `shadow_color`, `shadow_offset_x`, `shadow_offset_y` on `UI::View` base class.
Blur (base modifier)	P0	`.blur(radius:)` modifier	`UIVisualEffectView` or `CIFilter` blur on layer	`CIFilter` blur via Core Image	`Modifier.blur(radius:)`	`RenderEffect.createBlurEffect()` (Android 12+)	`filter: blur(Xpx)` on the element	`blur_radius` on `UI::View` base class.
Border (base modifier)	P0	`.border(_:width:)` modifier	`layer.borderColor` + `layer.borderWidth`	`NSView.layer.borderColor/Width`	`Modifier.border(width, color, shape)`	`setBackground(GradientDrawable)` with border	`border: Xpx solid color` CSS	`border_width`, `border_color` on `UI::View` base class.
Corner Radius (base modifier)	P0	`.cornerRadius(_:)` modifier	`layer.cornerRadius`	`layer.cornerRadius`	`Modifier.clip(RoundedCornerShape(...))`	`setBackground(GradientDrawable)` with corner radius	`border-radius: Xpx` CSS	`corner_radius`, `clip_to_bounds` on `UI::View` base class.
Opacity (base property)	P0	`.opacity(_:)` modifier	`.alpha` property on UIView	`setAlphaValue:` on NSView	`Modifier.alpha(alpha:)`	`setAlpha()` on View	`opacity: X` CSS property	`opacity` on `UI::View` base class.

Modals and Overlays

Crystal UI::View	Priority	SwiftUI	UIKit	AppKit	Compose	Android View	Web HTML/CSS	Notes
`UI::Alert`	P0	`Alert` via `.alert(...)` modifier	`UIAlertController` (style=alert)	`NSAlert`	`AlertDialog()`	`AlertDialog.Builder`	`<dialog>` element or custom modal overlay	`AlertButton` records with `label`, `style` (`:default`, `:destructive`, `:cancel`), `action`. `add_button()` builder. `is_presented`.
`UI::Sheet`	P0	`.sheet(isPresented:)` modifier	`UIViewController.present(_:animated:)` with `UISheetPresentationController`	`NSPanel` or `NSWindowController.beginSheet:`	`ModalBottomSheet()`	`BottomSheetDialogFragment`	Custom CSS overlay sliding up from bottom	`detents : Array(Symbol)` (`:small`, `:medium`, `:large`, `:custom`). `shows_drag_indicator`. Companion: `SheetPresenter`.
`UI::Popover`	P0	`.popover(isPresented:)` modifier	`UIPopoverPresentationController`	`NSPopover`	`Popup()` or custom positioned `Box`	`PopupWindow`	`<div>` positioned absolutely relative to anchor, or Popover API	`arrow_edge` (`:top`, `:bottom`, `:leading`, `:trailing`). `preferred_width/height`. Companion: `PopoverPresenter`.
`UI::ConfirmationDialog`	P0	`confirmationDialog(...)` modifier	`UIAlertController` (style=actionSheet)	`NSAlert` with multiple buttons	`AlertDialog()` with multiple actions	`AlertDialog.Builder` with multiple buttons	Custom `<dialog>` or modal with action buttons	`confirm_label`, `cancel_label`, `confirm_style` (`:default`, `:destructive`). `on_confirm`/`on_cancel` callbacks.
`UI::Snackbar`	P0	No direct SwiftUI equivalent — custom overlay	No native iOS Snackbar — custom view or third-party	No native macOS Snackbar — custom overlay	`SnackbarHost` + `Snackbar()`	`Snackbar` (Material, com.google.android.material)	Custom `<div>` with CSS animation, positioned at bottom	`message`, `action_label`, `duration` (seconds), `on_action`/`on_dismiss`. Companion: `SnackbarPresenter`.
`UI::Tooltip`	Implemented	`.help(...)` modifier (desktop only)	No standard iOS tooltip — `UITooltipInteraction` (iOS 17+)	`NSView.toolTip` property	`TooltipBox()` (experimental in Compose Multiplatform)	`TooltipCompat` (AppCompat, limited)	`title` attribute or custom CSS `:hover` tooltip	`text`, `content : View?`. P3 stub being upgraded.

Cards and Containers

Crystal UI::View	Priority	SwiftUI	UIKit	AppKit	Compose	Android View	Web HTML/CSS	Notes
`UI::Card`	P0	No named Card view — use `.background(.background, in: RoundedRectangle(...))`	No native UICard — compose from `UIView` with layer shadow + corner radius	No native NSCard — compose from `NSBox` or styled `NSView`	`Card()`	`MaterialCardView` (com.google.android.material)	`<div class="card">` with border-radius, shadow, background	`content : View?`, `elevation : Float64`, `is_outlined : Bool`.
`UI::Surface`	P0	No direct equivalent — use `background` modifier with `.background` style	`UIView` with background color and optional shadow	`NSBox` (titlePosition=none for a plain panel)	`Surface()`	`CardView` or plain `ViewGroup` with background	`<div>` with background color and optional border	`content`, `elevation`, `tonal_elevation`, `shape` (`:rectangle`, `:rounded`, `:circle`). Material Design Surface concept.
`UI::Divider`	P0	`Divider`	`UIView` with height=1 and background color	`NSBox` (boxType=separator)	`Divider()`	`View` with height=1dp and background color, or `DividerItemDecoration` in lists	`<hr>` or `<div style="height:1px;background:...">`	`color`, `thickness`, `orientation` (`:horizontal`, `:vertical`).

Shapes and Drawing

Crystal UI::View	Priority	SwiftUI	UIKit	AppKit	Compose	Android View	Web HTML/CSS	Notes
`UI::Circle`	Implemented	`Circle()`	`UIView` with `layer.cornerRadius = width/2`	`NSView` with oval `bezierPath` in `draw:`	`CircleShape` or `Box(Modifier.clip(CircleShape))`	`ShapeableImageView` or custom View with canvas draw	`<div style="border-radius:50%">` or SVG `<circle>`	`fill_color`, `stroke_color`, `stroke_width`, `size`. P3 stub being upgraded.
`UI::Rectangle`	Implemented	`Rectangle()`	`UIView` with rectangular frame	`NSView` with rectangle draw	`RectangleShape` or plain `Box`	Plain `View` with background color	`<div>` with dimensions	`fill_color`, `stroke_color`, `stroke_width`, `width`, `height`. P3 stub being upgraded.
`UI::RoundedRectangle`	Implemented	`RoundedRectangle(cornerRadius:)`	`UIView` with `layer.cornerRadius`	`NSView` with `NSBezierPath(roundedRect:xRadius:yRadius:)`	`RoundedCornerShape`	`ShapeableImageView` or `MaterialShapeDrawable`	`<div style="border-radius:Xpx">`	`corner_radius`, `corner_style` (`:continuous`, `:circular`), `width`, `height`, `fill_color`, `stroke_color`, `stroke_width`. P3 stub being upgraded.
`UI::Capsule`	Implemented	`Capsule()`	`UIView` with `layer.cornerRadius = min(width,height)/2`	`NSView` with capsule bezier path	`CapsuleShape`	`ShapeableImageView` with `CornerSize(50%)`	`<div style="border-radius:9999px">`	`fill_color`, `stroke_color`, `stroke_width`, `width`, `height`. P3 stub being upgraded.
`UI::Canvas`	Implemented	`Canvas { context, size in ... }`	Custom `UIView` subclass overriding `draw(_ rect:)`	Custom `NSView` subclass overriding `draw(_ dirtyRect:)`	`Canvas { drawScope -> ... }`	Custom `View` subclass overriding `onDraw(canvas:)`	`<canvas>` with 2D context API	`DrawCommand` enum. `CanvasOp` records. `move_to`, `line_to`, `arc`, `fill`, `stroke`, `begin_path`, `close_path` methods. P3 stub being upgraded.
`UI::PathView`	Implemented	`Path { path in ... }`	`UIBezierPath`	`NSBezierPath`	`Path()` with path builder	`Path` (android.graphics)	SVG `<path>` or Canvas path commands	Stub — API to be defined. P3 stub being upgraded.

Advanced and Specialized

Crystal UI::View	Priority	SwiftUI	UIKit	AppKit	Compose	Android View	Web HTML/CSS	Notes
`UI::MapView`	Implemented	`Map` (MapKit)	`MKMapView` (MapKit)	`MKMapView` (MapKit on macOS)	`GoogleMap()` (Maps SDK) or `MapLibre`	`SupportMapFragment` (Google Maps) or `MapView`	`<div id="map">` + Leaflet.js / Google Maps JS API / Mapbox	`latitude`, `longitude`, `zoom_level`. P3 stub being upgraded.
`UI::ChartView`	Implemented	`Chart` (Swift Charts, iOS 16+/macOS 13+)	`DKLineChartView` or third-party	Same as iOS via Swift Charts	`Canvas` with custom draw or Vico / MPAndroidChart library	`MPAndroidChart` or Vico library	Chart.js, D3.js, or native `<canvas>`	`chart_type : Symbol` (`:bar`, `:line`, `:pie`). P3 stub being upgraded.
`UI::WebViewComponent`	Implemented	`WebView` (WebKit, macOS/iOS only)	`WKWebView` (WebKit)	`WKWebView` (WebKit on macOS)	`AndroidView { WebView(context) }`	`WebView` (android.webkit)	`<iframe>` or direct page content	`url`. Note: class name is `WebViewComponent` (not `WebView`). P3 stub being upgraded.

3. Implementation Status

Fully Implemented (P0) — 47 components + 5 base modifier groups

All of the following have classes in src/ui/views/, visit methods in PlatformVisitor, and are implemented across all four renderer files.

P0 Base (9): Label, Button, VStack, HStack, ZStack, Image, TextField, ScrollView, Spacer

P0 Selection (6): Toggle, Checkbox, RadioGroup, Slider, Stepper, SegmentedControl

P0 Navigation (5): NavigationStack, NavigationLink, TabView, NavigationSplitView, Toolbar

P0 Feedback & Input (10): ProgressView, ActivityIndicator, Alert, Picker, IconButton, ListView, SecureField, SearchField, TextArea, TextEditor

P0 Advanced Controls (8): DatePicker, TimePicker, Form, Grid, AsyncImage, RichText, LinkButton, MenuButton, ToggleButton

P0 Containers & Visual (9): Sheet, Popover, ConfirmationDialog, Snackbar, Card, Surface, Divider, GlassBackground

P0 Base Class Modifiers (5 groups): shadow_*, blur_radius, border_*, corner_radius/clip_to_bounds, opacity

Presenter Companions (3): SheetPresenter, PopoverPresenter, SnackbarPresenter

Theme System: UI::Theme with apple_default and material_baseline factory methods, full ThemeColor semantic roles, typography, shape scales, and to_css_custom_properties.

Implemented (Stubs Being Upgraded) — 12 P3 components

View	Crystal Class	File
Circle	`UI::Circle`	`src/ui/views/circle.cr`
Rectangle	`UI::Rectangle`	`src/ui/views/rectangle.cr`
RoundedRectangle	`UI::RoundedRectangle`	`src/ui/views/rounded_rectangle.cr`
Capsule	`UI::Capsule`	`src/ui/views/capsule.cr`
Canvas	`UI::Canvas`	`src/ui/views/canvas.cr`
PathView	`UI::PathView`	`src/ui/views/path_view.cr`
MapView	`UI::MapView`	`src/ui/views/map_view.cr`
ChartView	`UI::ChartView`	`src/ui/views/chart_view.cr`
WebViewComponent	`UI::WebViewComponent`	`src/ui/views/web_view.cr`
ColorPicker	`UI::ColorPicker`	`src/ui/views/color_picker.cr`
VideoPlayer	`UI::VideoPlayer`	`src/ui/views/video_player.cr`
Tooltip	`UI::Tooltip`	`src/ui/views/tooltip.cr`

4. Platform Divergence Notes

These are the cases where the same logical component concept requires meaningfully different approaches per platform. Understanding these divergences before implementing is critical to designing the right Crystal abstraction.

Navigation — The Biggest Divergence

Navigation is the single most platform-divergent UI concept.

Platform	Navigation Paradigm	Root Container	Back Navigation
iOS	Push/pop stack	`UINavigationController`	Swipe right or Back button in `UINavigationBar`
macOS	No standard push nav — windowed model	`NSWindowController` / view controller presentation	Close window, or custom back button in toolbar
Android	Fragment back stack or Navigation Component	`NavHostFragment`	System back button or gesture
Web	URL routing + browser history	`<div>` visibility or JS router	Browser back button / `history.back()`

Crystal Strategy: UI::NavigationStack owns a stack of UI::View bodies and exposes push(view) / pop() / pop_to_root / current_view. Each renderer translates this to the platform pattern.

Tab Navigation

Platform	Tab Position	Root Container	Behavior
iOS	Bottom (UITabBar)	`UITabBarController`	System-managed, touch targets, badge support
macOS	Top or segmented (NSTabViewController)	`NSTabViewController`	Top-of-window tabs or segmented control look
Android	Bottom (Material 3) or Top (Material 2)	`BottomNavigationView` or `TabLayout`	Bottom nav or sliding tabs
Web	Flexible — any position	Custom CSS	No system chrome

Modals

Platform	Alert	Sheet	Action Sheet
iOS	Centered dialog	Slides up from bottom (detents)	Slides up from bottom
macOS	Centered NSAlert panel	Slides down from title bar	NSAlert with multiple buttons
Android	`AlertDialog` (centered)	`BottomSheetDialogFragment`	`AlertDialog` with button list
Web	`<dialog>` element or custom	Custom overlay	Custom menu

Date/Time Pickers

Platform	Date Picker Style	Presentation
iOS	Inline calendar / compact tappable field / wheel	Inline or popover
macOS	Text field with stepper / calendar / clock face	Inline as a view widget
Android	Material DatePicker dialog	Modal dialog
Web	`<input type="date">`	Browser native UI

The UI::DatePicker mode property (DatePickerMode::Date, DatePickerMode::Time, DatePickerMode::DateAndTime) lets each renderer map to the closest available native presentation.

Progress Indicators

Both UI::ProgressView (determinate or indeterminate depending on value) and UI::ActivityIndicator (always indeterminate spinner) map to a single class on macOS — NSProgressIndicator — with different isIndeterminate and style settings.

Glass / Blur Effects

Platform	Native Blur Support	Implementation
iOS	Excellent — `UIVisualEffectView`	System-integrated, composited by GPU
macOS	Excellent — `NSVisualEffectView`	System-integrated, window-aware
Android	No native solution pre-Android 12	`RenderEffect.createBlurEffect()` (API 31+); fallback: solid translucent color
Web	`backdrop-filter: blur()`	Wide support in modern browsers; GPU-accelerated

UI::GlassBackground uses the material property (:thin, :ultra_thin, :regular, :thick, :chrome) to hint at blur intensity. The Android renderer checks API level and uses RenderEffect when available, falling back to a translucent solid color on older devices.

Presenter Pattern for Modals

Sheet, Popover, and Snackbar use companion presenter classes rather than being placed directly in the view tree. This matches the platform paradigm where modals are presented imperatively:

sheet = UI::Sheet.new(content: my_form)
presenter = UI::SheetPresenter.new(sheet)
presenter.present    # → sheet.is_presented = true
presenter.dismiss    # → sheet.is_presented = false, fires on_dismiss

5. Implementation Strategy

Adding a New Renderer Visit Method (Step-by-Step)

For P3 components being upgraded from stubs to full implementations:

Verify the Crystal API — Read the existing class in src/ui/views/new_view.cr. API is already defined.
Add to PlatformVisitor — Add abstract def visit(view : NewView) to src/ui/platform_visitor.cr. This will cause compile errors in all renderer files until all visit methods are implemented — that is intentional.
Implement Web renderer — Add def visit(view : UI::NewView) to src/ui/renderers/web_renderer.cr. Web is usually the fastest to implement since it just emits HTML/CSS.
Implement AppKit renderer — Add def visit(view : UI::NewView) to src/ui/renderers/appkit_renderer.cr. Use objc_getClass("NSClassName") for the target class.
Implement UIKit renderer — Add def visit(view : UI::NewView) to src/ui/renderers/uikit_renderer.cr. Use objc_getClass("UIClassName") for the target class.
Implement Android renderer — Add def visit(view : UI::NewView) to src/ui/renderers/android_renderer.cr. Use JNI FindClass and GetMethodID for the target Android class.
Write specs — Add specs to spec/ui/views/new_view_spec.cr testing the Web renderer output at minimum.
Update this matrix — Change status from Implemented to P0 in this file.

Modifier System (Complete)

The UI::View base class already has a full modifier property set. All renderers apply these in their common-properties method:

# UI::View base class modifier properties (all implemented)
property corner_radius : Float64 = 0.0
property clip_to_bounds : Bool = false
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
property border_width : Float64 = 0.0
property border_color : Color? = nil
property blur_radius : Float64 = 0.0
property minimum_width : Float64? = nil
property minimum_height : Float64? = nil
property maximum_width : Float64? = nil
property maximum_height : Float64? = nil

6. Coverage Statistics

Current Coverage

Status	Count	Description
P0 (fully implemented)	47 views + 5 modifier groups + 3 presenters + Theme	Working across all 4 renderers
Implemented (stubs being upgraded)	12 views	Crystal API defined; renderer support in progress
Total view types	59	Full cross-platform component vocabulary

Coverage by Category

Category	Status	Views
Text Display	P0	Label, RichText, TextEditor
Text Input	P0	TextField, SecureField, SearchField, TextArea
Buttons	P0	Button, IconButton, LinkButton, MenuButton, ToggleButton
Layout	P0	VStack, HStack, ZStack, ScrollView, Spacer, Grid, ListView, Form
Navigation	P0	NavigationStack, NavigationLink, TabView, NavigationSplitView, Toolbar
Selection	P0	Toggle, Checkbox, RadioGroup, Slider, Stepper, SegmentedControl
Pickers	P0 (except ColorPicker)	Picker, DatePicker, TimePicker + ColorPicker (Implemented)
Progress	P0	ProgressView, ActivityIndicator
Images & Media	P0 (except VideoPlayer)	Image, AsyncImage + VideoPlayer (Implemented)
Visual Effects	P0	GlassBackground + base modifier groups
Modals	P0 (except Tooltip)	Alert, Sheet, Popover, ConfirmationDialog, Snackbar + Tooltip (Implemented)
Cards & Containers	P0	Card, Surface, Divider
Shapes & Drawing	Implemented	Circle, Rectangle, RoundedRectangle, Capsule, Canvas, PathView
Advanced & Specialized	Implemented	MapView, ChartView, WebViewComponent
Theme System	P0	UI::Theme with apple_default, material_baseline

name	component-mapping-matrix
description	Comprehensive cross-platform UI component mapping matrix showing how every common UI pattern maps across Crystal UI::View, SwiftUI, UIKit, AppKit, Jetpack Compose, Android Views, and Web HTML/CSS. Implementation priority guide for expanding the asset_pipeline cross-platform component system.
user-invocable	true
allowed-tools	Read, Write, Edit, Glob, Grep, Bash
version	2.0.0