component-mapping-matrix

# 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. ### See also: Apple Platform Guide For each `UI::View` below, the **`apple-platform-guide` skill** contains a developer-facing usage doc at `components/<slug>.md` covering: feel-of-the-flow, Quickstart code, Customization table (all knobs + theme tokens), feel recipes, platform behavior, and HIG citations. The slug is the HIG page slug (e.g. `UI::Button` → `components/buttons.md`; `UI::MenuButton` → `components/pop-up-buttons.md`). When this matrix tells you *what to map*, the platform guide tells you *how to use it and why*. Raw HIG markdown for every component lives in the **`apple-hig` skill** at `pages/<slug>.md`. --- ## 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: 1. Confirm all 4 platform equivalents before writing any Crystal code. 2. Note any platform divergences in the "Notes" column before designing the abstract API. 3. Track implementation status by updating the priority to P0 once all renderers are complete. 4. 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)`. |