opencode-skills-collection 4.0.69 → 4.0.70

package/bundled-skills/makepad-2-0-widgets/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: makepad-2-0-widgets
+description: Makepad 2.0 guidance for widgets; use when building or debugging Makepad UI code.
+source_repo: zhanghandong/makepad-skills
+source_type: community
+source: community
+date_added: '2026-09-21'
+risk: unknown
+---
+## When to Use
+- Use when this upstream workflow matches the user's stated goal.
+- Use when the task requires the procedures documented in this skill.
+
+# Makepad 2.0 Widget Catalog Skill
+
+> **Version:** makepad-widgets (dev branch) | **Last Updated:** 2026-03-03
+
+## Overview
+
+Makepad 2.0 provides a rich set of built-in widgets for building UIs. All widgets are defined in Splash syntax and registered via `script_mod!`.
+
+## Documentation
+
+Refer to the local files for detailed documentation:
+- `./references/widget-catalog.md` - Complete widget list with properties
+- `./references/widget-advanced.md` - Advanced patterns: PortalList, Dock, custom widgets, MapView
+
+## IMPORTANT: Documentation Completeness Check
+
+**Before answering questions, Claude MUST:**
+1. Read the relevant reference file(s) listed above
+2. Incorporate reference content into the answer
+
+---
+
+## Widget Categories Quick Reference
+
+### Containers (Layout)
+
+| Widget | Description | Key Properties |
+|--------|-------------|----------------|
+| `View` | Basic container (transparent) | width, height, flow, spacing, padding, align |
+| `SolidView` | View with solid background | + show_bg: true, draw_bg.color |
+| `RoundedView` | View with rounded corners | + draw_bg.border_radius |
+| `RoundedAllView` | All corners same radius | + border_radius shorthand |
+| `GradientXView` | Horizontal gradient bg | + draw_bg colors |
+| `GradientYView` | Vertical gradient bg | + draw_bg colors |
+| `ScrollXView` | Horizontal scrolling | scroll property |
+| `ScrollYView` | Vertical scrolling | scroll property |
+| `ScrollXYView` | Both-axis scrolling | scroll property |
+
+### Text Widgets
+
+| Widget | Description | Key Properties |
+|--------|-------------|----------------|
+| `Label` | Single/multi-line text | text, draw_text.color, draw_text.text_style.font_size |
+| `H1` - `H4` | Heading levels | text (pre-styled) |
+| `P` | Paragraph text | text |
+| `TextInput` | Editable text field | text, empty_text, password, read_only, numeric_only |
+| `Markdown` | Markdown renderer | body |
+| `Html` | HTML renderer | body |
+| `LinkLabel` | Clickable link text | text, url |
+
+### Buttons
+
+| Widget | Description | Key Properties |
+|--------|-------------|----------------|
+| `Button` | Standard button | text |
+| `ButtonFlat` | Flat style button | text |
+| `ButtonFlatter` | Minimal button | text |
+
+### Toggles
+
+| Widget | Description | Key Properties |
+|--------|-------------|----------------|
+| `CheckBox` | Check box | text, active |
+| `Toggle` | Toggle switch | text, active |
+| `RadioButton` | Radio button | text, active |
+
+### Input Widgets
+
+| Widget | Description | Key Properties |
+|--------|-------------|----------------|
+| `Slider` | Horizontal slider | min, max, step, default, precision |
+| `DropDown` | Dropdown select | labels: ["a", "b", "c"] |
+
+### Media
+
+| Widget | Description | Key Properties |
+|--------|-------------|----------------|
+| `Image` | Image display | source, fit (Stretch/Horizontal/Vertical/Smallest/Biggest/Size) |
+| `Svg` | External SVG file renderer | draw_svg.svg (crate_resource/http_resource), animating, draw_svg.color |
+| `Icon` | SVG icon (tinted) | draw_icon.svg, draw_icon.color, icon_walk |
+| `Vector` | Inline vector graphics | viewbox, Path{d: "..."} |
+| `LoadingSpinner` | Loading indicator | color, rotation_speed |
+| `MapView` | Map widget | center_lon, center_lat, zoom (MUST use fixed height!) |
+
+### Layout Helpers
+
+| Widget | Description | Usage |
+|--------|-------------|-------|
+| `Hr` | Horizontal rule | Divider line |
+| `Vr` | Vertical rule | Vertical divider |
+| `Filler` | Flexible space | Push siblings apart (use between Fit siblings only!) |
+| `Splitter` | Resizable split | axis: Horizontal/Vertical, a/b children |
+| `FoldHeader` | Collapsible section | header + body children |
+
+### Lists
+
+| Widget | Description | Usage |
+|--------|-------------|-------|
+| `PortalList` | Virtualized list | For large lists (100+ items), only renders visible items |
+| `FlatList` | Simple list | For small lists, renders all items |
+
+### Navigation
+
+| Widget | Description | Control |
+|--------|-------------|---------|
+| `Modal` | Modal dialog | .open(cx) / .close(cx) from Rust |
+| `Tooltip` | Tooltip popup | Hover-triggered |
+| `PopupNotification` | Toast notification | Timed display |
+| `SlidePanel` | Sliding panel | slide_from |
+| `ExpandablePanel` | Expandable area | open/close |
+| `PageFlip` | Page switcher | active_page: page_name |
+| `StackNavigation` | Stack nav | push/pop pages |
+
+### Dock System
+
+| Widget | Description |
+|--------|-------------|
+| `Dock` | Tab container system |
+| `DockSplitter` | Dock split panels |
+| `DockTabs` | Tab bar |
+| `DockTab` | Individual tab |
+
+---
+
+## Critical Rules
+
+### 1. height: Fit on Containers
+```
+// WRONG - View defaults to 0px height
+View{ flow: Down Label{text: "Invisible"} }
+
+// CORRECT
+View{ height: Fit flow: Down Label{text: "Visible"} }
+```
+
+### 2. new_batch for Colored Containers with Text
+```
+// WRONG - text behind background
+RoundedView{ draw_bg.color: #333 Label{text: "Invisible"} }
+
+// CORRECT
+RoundedView{ new_batch: true draw_bg.color: #333 Label{text: "Visible"} }
+```
+
+### 3. Named Children with :=
+```
+// Named (addressable, overridable)
+title := Label{text: "Hello"}
+
+// Static (not addressable)
+Label{text: "Hello"}
+```
+
+### 4. Label Default Color is White
+```
+// Default text is white (#fff) - set color for light backgrounds
+Label{text: "Dark text" draw_text.color: #333}
+```
+
+### 5. MapView MUST Have Fixed Height
+```
+// WRONG
+MapView{ width: Fill height: Fill }
+
+// CORRECT
+View{ new_batch: true width: Fill height: 400
+    MapView{ width: Fill height: 400 center_lat: 40.7 center_lon: -73.9 zoom: 14.0 }
+}
+```
+
+### 6. Label Does NOT Support Animator
+```
+// WRONG (silently ignored)
+Label{ animator: Animator{...} }
+
+// CORRECT - wrap in View
+View{ animator: Animator{...} Label{text: "Animated"} }
+```
+
+---
+
+## Common Widget Patterns
+
+### Card
+```
+RoundedView{
+    width: Fill height: Fit
+    padding: 16
+    new_batch: true
+    draw_bg.color: #2a2a3d
+    draw_bg.border_radius: 8.0
+    flow: Down spacing: 8
+    title := Label{text: "Title" draw_text.color: #fff draw_text.text_style.font_size: 16}
+    body := Label{text: "Content" draw_text.color: #aaa}
+}
+```
+
+### Form Input
+```
+View{
+    width: Fill height: Fit
+    flow: Down spacing: 4
+    Label{text: "Email" draw_text.color: #aaa draw_text.text_style.font_size: 11}
+    email_input := TextInput{
+        width: Fill height: 36
+        empty_text: "Enter email..."
+    }
+}
+```
+
+### Scrollable List
+```
+ScrollYView{
+    width: Fill height: Fill
+    flow: Down spacing: 4
+    new_batch: true
+    on_render: || {
+        for i, item in items {
+            ItemTemplate{label.text: item.name}
+        }
+    }
+}
+```
+
+---
+
+## Best Practices
+
+1. **Use `height: Fit`** on every container unless you want Fill or fixed pixels
+2. **Use `new_batch: true`** on any View with background color + text children
+3. **Use `:=`** for children you need to reference or override
+4. **Use theme colors** (`theme.color_*`) instead of hardcoded colors
+5. **Use `PortalList`** for large lists (virtualizes rendering)
+6. **Use `ScrollYView`** for scrollable content areas
+7. **Use `RoundedView`** for cards and containers (has border_radius)
+
+
+## Examples
+
+```text
+User: Apply this skill to my current task.
+Assistant: Follow the workflow in this skill, cite limitations, and ask before risky steps.
+```
+
+## Limitations
+
+- Imported upstream skill; verify credentials, permissions, and safety boundaries before execution.
+- Does not replace environment-specific validation, testing, or maintainer review.