docs: comprehensive documentation improvements with Dart examples #436
Conversation
- Fix broken links and code errors in quickstart, get_started, introduction - Add 4 new widget docs: hero, divider, conditional, set_value - Add StacSetValueAction documentation - Add 8 new style docs: edge_insets, alignment, gradient, box_decoration, text_style, shape_borders, box_constraints, box_shadow - Add new guides: state_management, migration, troubleshooting, changelog - Expand project_structure.mdx with detailed structure - Standardize widget descriptions and add Dart DSL examples to all docs - Update docs.json navigation with new Styles tab and Guides group
|
Important Review skippedToo many files! This PR contains 122 files, which is 22 over the limit of 100. You can disable this status message by setting the
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
Note
Due to the large number of review comments, Critical, Major severity comments were prioritized as inline comments.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (18)
docs/quickstart.mdx (1)
193-193: Inconsistent import path in the full example.The quickstart guide creates a project named
stac_demo(line 16), and the earlier code block correctly imports frompackage:stac_demo/...(line 171). However, this full example imports frompackage:example_app/..., which would cause confusion for users following along.📝 Suggested fix
-import 'package:example_app/default_stac_options.dart'; +import 'package:stac_demo/default_stac_options.dart';docs/widgets/linear_progress_indicator.mdx (1)
26-44: InconsistentbackgroundColorvalues between Dart and JSON examples.The Dart example uses
StacColors.amberwhile the JSON example uses"#FFD700"(which is Gold, not Amber). For documentation clarity, these should represent the same color value so users can understand the mapping between the DSL representations.Consider aligning them:
📝 Suggested fix
Either update the JSON to use Amber's hex value:
- "backgroundColor": "#FFD700", + "backgroundColor": "#FFBF00",Or update the Dart to match the JSON's Gold color:
- backgroundColor: StacColors.amber, + backgroundColor: '#FFD700',docs/widgets/outlined_button.mdx (1)
24-57: Align Dart and JSON examples for consistency.The Dart example only includes
onPressed, while the JSON example includesonPressed,onLongPress,onHover, andonFocusChange(all set to empty objects). This inconsistency may confuse users trying to understand the mapping between the two formats.Consider either:
- Making both examples equivalent by including/excluding the same properties
- Adding a note explaining that the JSON shows all available callback properties while the Dart shows minimal usage
docs/widgets/positioned.mdx (2)
54-117: Normalize example heading levels and formatting.The example headings mix
##and###, and “fromRect” lacks inline code formatting. This makes the doc hierarchy harder to scan. Consider using a consistent heading level and backticks for widget variants.Suggested tweak
-## Example for `directional` +## Example for `directional` -### Example for `fill` +## Example for `fill` -### Example for fromRect +## Example for `fromRect`
20-23: Documentation describes non-existent API—rewrite positioned.mdx to match actual implementation.The properties table and examples describe features (
positionedType,start,end,textDirection,rect) that are not implemented inStacPositioned. The actual class only supports:left,top,right,bottom,width,height, andchild. Update the documentation to reflect the current API.docs/widgets/gesture_detector.mdx (1)
229-272: Inconsistency between Dart and JSON dialog content.The Dart example uses
content: StacText(data: '...')(a widget), while the JSON example uses"content": "..."(a plain string). This inconsistency may confuse readers about the expected format for dialog content.Option A: Align JSON to use a text widget
"onLongPress": { "actionType": "showDialog", "title": "Long Press Detected", - "content": "You performed a long press on the widget." + "content": { + "type": "text", + "data": "You performed a long press on the widget." + } },Option B: Align Dart to use a plain string (if supported)
onLongPress: StacDialogAction( title: 'Long Press Detected', - content: StacText(data: 'You performed a long press on the widget.'), + content: 'You performed a long press on the widget.', ),docs/introduction.mdx (1)
37-56: Update widget count to reflect actual count.
The documentation currently claims "90+" widgets, but there are 84 widget doc files indocs/widgets. Update the count to "84" or use timeless phrasing like "80+ built-in widgets." The Core Concepts route/concepts/custom_widgetsis valid and resolves correctly to an existing documentation file.docs/widgets/fitted_box.mdx (1)
16-16: Type inconsistency between properties table and Dart example.The properties table (line 16) specifies the
alignmenttype asStacAlignmentDirectional, but the Dart example (line 28) usesStacAlignment.center. Please verify which type is correct and update either the table or the example for consistency.Also applies to: 28-28
docs/widgets/filled_button.mdx (1)
38-55: Use{"actionType": "none"}for action callbacks instead of empty objects.The JSON example uses
{}for callbacks (onPressed, onLongPress, onHover, onFocusChange), but the canonical action schema specifies{"actionType": "none"}(see docs/actions/none.mdx). Update the JSON callbacks to match both the schema and the Dart equivalentStacNoneAction(). This pattern appears in multiple widget documentation files (text_button.mdx, outlined_button.mdx, elevated_button.mdx, floating_action_button.mdx, icon_button.mdx).docs/widgets/sliver_padding.mdx (1)
17-63: Fix JSON padding to use explicit EdgeInsets object format.The JSON example uses a numeric value (
"padding": 16.0), butStacEdgeInsets.fromJson()expects an object with individual edge fields. The correct format is:Corrected JSON example
{ "type": "sliverPadding", "padding": { "left": 16.0, "top": 16.0, "right": 16.0, "bottom": 16.0 }, "sliver": { "type": "sliverToBoxAdapter", "child": { "type": "container", "height": 150, "color": "#4CAF50", "child": { "type": "center", "child": { "type": "text", "data": "I am a Box inside a SliverPadding!", "style": { "color": "#FFFFFF", "fontWeight": "bold" } } } } } }docs/styles/border.mdx (1)
219-220: Update links to.mdxextension for correct resolution.The "See Also" links reference
.mdfiles (border_side.md,border_radius.md) but the actual documentation files use.mdxextension (border_side.mdx,border_radius.mdx). Update both links to use.mdxfor consistency and to ensure they resolve correctly.docs/widgets/row.mdx (1)
24-65: Align Dart/JSON image URLs for parity. The Dart snippet uses base URLs, while the JSON block includes query parameters (Line 30–39 vs Line 54–65). Sync them so readers get consistent results.✅ Suggested fix (update Dart URLs to match JSON)
- StacImage( - src: 'https://images.pexels.com/photos/2718416/pexels-photo-2718416.jpeg', - width: 100, - ), + StacImage( + src: 'https://images.pexels.com/photos/2718416/pexels-photo-2718416.jpeg?auto=compress&cs=tinysrgb&w=1260&h=750&dpr=2', + width: 100, + ), StacImage( - src: 'https://images.pexels.com/photos/121629/pexels-photo-121629.jpeg', + src: 'https://images.pexels.com/photos/121629/pexels-photo-121629.jpeg?auto=compress&cs=tinysrgb&w=1260&h=750&dpr=2', width: 100, ), StacImage( - src: 'https://images.pexels.com/photos/1414642/pexels-photo-1414642.jpeg', + src: 'https://images.pexels.com/photos/1414642/pexels-photo-1414642.jpeg?auto=compress&cs=tinysrgb&w=1260&h=750&dpr=2', width: 100, ),docs/widgets/listview.mdx (1)
33-269: Keep examples in sync & remove stray fence. The Dart example shows two items plus a comment (Line 38–86) while the JSON block includes three items (Line 98–263). Also, there’s a trailing ``` after</CodeGroup>(Line 269) that renders an empty code block.✅ Suggested fix (align to 2 items and drop the stray fence)
@@ - { - "type": "listTile", - "leading": { - "type": "container", - "height": 50, - "width": 50, - "color": "#165FC7", - "child": { - "type": "column", - "mainAxisAlignment": "center", - "crossAxisAlignment": "center", - "children": [ - { - "type": "text", - "data": "3", - "style": { - "fontSize": 21 - } - } - ] - } - }, - "title": { - "type": "padding", - "padding": { - "top": 10 - }, - "child": { - "type": "text", - "data": "Item 3", - "style": { - "fontSize": 18 - } - } - }, - "subtitle": { - "type": "padding", - "padding": { - "top": 10 - }, - "child": { - "type": "text", - "data": "Item description", - "style": { - "fontSize": 14 - } - } - }, - "trailing": { - "type": "icon", - "iconType": "material", - "icon": "more_vert", - "size": 24 - } - } + { + "type": "listTile", + "leading": { + "type": "container", + "height": 50, + "width": 50, + "color": "#165FC7", + "child": { + "type": "column", + "mainAxisAlignment": "center", + "crossAxisAlignment": "center", + "children": [ + { + "type": "text", + "data": "2", + "style": { + "fontSize": 21 + } + } + ] + } + }, + "title": { + "type": "padding", + "padding": { + "top": 10 + }, + "child": { + "type": "text", + "data": "Item 2", + "style": { + "fontSize": 18 + } + } + }, + "subtitle": { + "type": "padding", + "padding": { + "top": 10 + }, + "child": { + "type": "text", + "data": "Item description", + "style": { + "fontSize": 14 + } + } + }, + "trailing": { + "type": "icon", + "iconType": "material", + "icon": "more_vert", + "size": 24 + } + } @@ -```` +docs/get_started.mdx (1)
112-125: Remove thecontextparameter fromStac.fromAssets()call—the method does not accept it.The method name
Stac.fromAssetsis correct, but the signature isStac.fromAssets(String assetPath, { LoadingWidgetBuilder? loadingWidget, ErrorWidgetBuilder? errorWidget }). The second argumentcontextis not a valid parameter. Update the code to:Stac.fromAssets('assets/ui.json').docs/styles/colors.mdx (1)
80-97: Inconsistency between Dart and JSON examples for Name color.The Dart example uses
StacColors.blackwhile the JSON example uses"black45"(black with 45% opacity). These represent different colors - the Dart code suggests full black, but the JSON shows a partially transparent black.Consider aligning them:
📝 Option A: Update Dart to match JSON (black45)
StacText( data: 'Hello World!', - style: StacTextStyle(color: StacColors.black), + style: StacTextStyle(color: StacColors.black45), )📝 Option B: Update JSON to match Dart (black)
"style": { - "color": "black45" + "color": "black" }docs/widgets/list_tile.mdx (1)
30-30: Documentation errors:autofocusshould bebool, notString; also fix property name casing.The documentation lists this property as
autoFocuswith typeString, but the actual implementation defines it asautofocuswith typebool?. The description "True if this widget will be selected as the initial focus..." confirms it should be a boolean value.📝 Proposed fix
-| autoFocus | `String` | True if this widget will be selected as the initial focus when no other node in its scope is currently focused. | +| autofocus | `bool` | Whether this widget should automatically gain focus when it is visible. |docs/widgets/dynamic_view.mdx (2)
598-610: Duplicate best practice item.Items 5 and 10 are identical: "Keep templates modular and reusable when possible". Remove the duplicate to clean up the list.
📝 Suggested fix
1. Use `targetPath` to extract only the data you need from complex API responses 2. For list data, always use the `itemTemplate` property to define how each item should be rendered 3. **Always provide an `emptyTemplate`** for list-based views to handle empty API responses gracefully 4. Design empty states that are informative and actionable - include clear messaging and relevant actions like refresh buttons 5. Keep templates modular and reusable when possible 6. Use appropriate error handling in your UI design for cases when the API request fails 7. For empty states, use appropriate icons and colors that match your app's design system 8. Provide custom `loaderWidget` and `errorWidget` for better user experience 9. Use `resultTarget` when you need to reference the data with a specific name in your template -10. Keep templates modular and reusable when possible
258-393: Minor Dart/JSON discrepancy in emptyTemplate example.In the Dart example (lines 283, 288, 293),
StacSizedBoxis used for spacing. However, in the JSON example (lines 349, 363, 375),"type": "container"is used instead of"type": "sizedBox". While both achieve similar results, this inconsistency could confuse readers expecting a 1:1 mapping.📝 Suggested fix for JSON
{ - "type": "container", + "type": "sizedBox", "height": 16 }, ... { - "type": "container", + "type": "sizedBox", "height": 8 }, ... { - "type": "container", + "type": "sizedBox", "height": 24 },
🤖 Fix all issues with AI agents
In `@docs/styles/edge_insets.mdx`:
- Around line 71-96: Update the docs to remove unsupported JSON shorthands and
show only formats StacEdgeInsets.fromJson actually accepts: replace the `{
"horizontal": 16.0 }` and `{ "vertical": 16.0 }` examples with the supported
JSON object form that specifies individual edges (left/top/right/bottom), and
add a note that horizontal() and vertical() are Dart-only convenience
constructors (referencing StacEdgeInsets.horizontal and StacEdgeInsets.vertical)
so readers don’t expect those JSON keys to deserialize.
In `@docs/styles/stac_alignment_directional.mdx`:
- Around line 24-35: The example in stac_alignment_directional.mdx is missing
the required child and will crash because StacFittedBoxParser invokes
model.child.parse(context) (not null-safe); update the Dart and JSON examples
for StacFittedBox (and StacAlignmentDirectional.center usage) to include a
concrete child (e.g., a Text or Container) so model.child is non-null—mirror the
structure used in examples/stac_gallery/assets/json/fitted_box_example.json to
ensure the parser receives a valid child.
In `@docs/widgets/wrap.mdx`:
- Line 45: The Dart and JSON examples use different colors — the Dart example
uses StacColors.purple while the JSON example uses "#E1BEE7" — causing
mismatched rendering; fix by making the two examples use the same color
representation: either replace StacColors.purple with the hex "#E1BEE7" in the
Dart example or change the JSON color value to the hex for StacColors.purple
(e.g., "#9C27B0"), and if you choose to keep a named constant, confirm the JSON
parser accepts color names before switching the JSON to "purple" or a StacColors
reference; update both the Dart snippet (StacColors.purple) and the JSON snippet
("#E1BEE7") so they match.
🟡 Minor comments (18)
docs/widgets/opacity.mdx-6-8 (1)
6-8: Fix incorrect widget reference (Slider → Opacity).Line 7 links to the Opacity docs but says “Slider widget,” which is confusing. Please update the text to “Opacity widget.”
docs/widgets/circular_progress_indicator.mdx-27-31 (1)
27-31: AlignbackgroundColortype with the documentedStringtype.The properties table says
backgroundColoris aString, but the Dart example usesStacColors.amber. Either update the Dart example to use a hex string or clarify in the table that the Dart DSL acceptsStacColors(orColor) in addition to JSON hex strings.💡 Suggested doc alignment (example-only)
StacCircularProgressIndicator( color: '#541204', strokeWidth: 6, - backgroundColor: StacColors.amber, + backgroundColor: '#FFD700', strokeCap: StacStrokeCap.round, )docs/widgets/divider.mdx-15-16 (1)
15-16: Tighten wording in properties table.“empty space” is redundant; “space” reads cleaner and is standard in Flutter docs.
✍️ Suggested edit
-| indent | `double?` | The amount of empty space to the leading edge. | -| endIndent | `double?` | The amount of empty space to the trailing edge. | +| indent | `double?` | The amount of space to the leading edge. | +| endIndent | `double?` | The amount of space to the trailing edge. |docs/widgets/floating_action_button.mdx-42-42 (1)
42-42: Update properties table:buttonTypetype should beStacFloatingActionButtonType.The properties table documents the
buttonTypeasFloatingActionButtonType, but the Dart example and actual class definition useStacFloatingActionButtonType. Update the properties table on line 15 to reflect the correct type name.docs/widgets/radio_group.mdx-56-59 (1)
56-59: Correct the JSON property name from"align"to"textAlign".The Dart example correctly uses
textAlign: StacTextAlign.center(line 58), but the JSON examples use"align": "center"(lines 108, 125, 142). This is inconsistent with the documented StacText widget property (textAlign) and contradicts the JSON mappings used in other widget documentation (e.g.,text_field.mdx,ink_well.mdx). The JSON property should be"textAlign"to match the Dart property name and other examples in the documentation.docs/widgets/gesture_detector.mdx-193-204 (1)
193-204: Correct the Dart DSL action pattern for consistency.Line 195 uses a raw map literal
{'actionType': 'handleSwipe'}instead of wrapping it inStacAction. Other documented examples consistently use typed action classes likeStacNavigateAction,StacSnackBarAction, andStacDialogAction. For consistency with the framework's patterns, custom actions should also be wrapped:Suggested fix
StacGestureDetector( - onHorizontalDragEnd: {'actionType': 'handleSwipe'}, + onHorizontalDragEnd: StacAction(jsonData: {'actionType': 'handleSwipe'}), child: StacContainer(docs/styles/alignment.mdx-69-90 (1)
69-90: Remove//comments inside JSON blocks.Those comment lines make the JSON invalid for copy‑paste. Prefer plain JSON and keep labels outside the code block.
🧾 Minimal fix (keep valid JSON)
-// Top Left { "type": "align", "alignment": "topLeft", "child": { "type": "text", "data": "Top Left" } } -// Top Center { "type": "align", "alignment": "topCenter", "child": { "type": "text", "data": "Top Center" } } -// Top Right { "type": "align", "alignment": "topRight", "child": { "type": "text", "data": "Top Right" } }docs/widgets/dropdown_menu.mdx-59-60 (1)
59-60: Property name mismatch between Dart and JSON examples.The Dart example uses
icon:parameter while the JSON example uses"iconData":. This inconsistency could confuse users trying to understand the property mapping between Dart and JSON representations.// Dart (line 59) leadingIcon: StacIcon(icon: 'home'),// JSON (line 88-91) "leadingIcon": { "type": "icon", "iconData": "home" }Please verify which property name is correct and update the examples to be consistent.
Also applies to: 88-91
docs/widgets/tab_bar.mdx-88-92 (1)
88-92: Align tab labels with content colors.All three tabs are labeled “Red,” but the TabBarView uses grey/orange/grey content. Updating the labels (or colors) will make the example clearer.
💡 Suggested fix
- StacTab(text: 'Red'), - StacTab(text: 'Red'), - StacTab(text: 'Red'), + StacTab(text: 'Grey'), + StacTab(text: 'Orange'), + StacTab(text: 'Grey'),- "text": "Red" + "text": "Grey" ... - "text": "Red" + "text": "Orange" ... - "text": "Red" + "text": "Grey"Also applies to: 121-131
docs/widgets/elevated_button.mdx-26-35 (1)
26-35: Keep Dart and JSON examples in sync for callbacks.The JSON includes
onHoverandonFocusChange, but the Dart example omits them. Aligning the two avoids confusion for readers copying snippets.💡 Suggested fix
onPressed: StacNoneAction(), onLongPress: StacNoneAction(), + onHover: StacNoneAction(), + onFocusChange: StacNoneAction(), style: StacButtonStyle(Also applies to: 42-46
docs/styles/text_style.mdx-10-24 (1)
10-24: Document thedecorationproperty in the table.The examples use
decoration, but it’s missing from the properties list, which can mislead readers.💡 Suggested fix
| height | `double?` | Line height as multiple of font size. | +| decoration | `String?` | Text decoration: underline, lineThrough, overline. | | decorationColor | `String?` | Color for text decorations. |docs/widgets/hero.mdx-74-105 (1)
74-105: JSON example should be valid JSON (single root, no comments).
Thejsonblock includes comments and two root objects, which breaks copy/paste and tooling. Consider wrapping both examples in a single JSON object (or split into two separate JSON blocks).🛠 Proposed fix: wrap list/detail JSON into a single valid object
-```json JSON -// List Item -{ - "type": "gestureDetector", - "onTap": { - "actionType": "navigate", - "routeName": "/detail" - }, - "child": { - "type": "hero", - "tag": "product-1", - "child": { - "type": "image", - "network": "https://example.com/product.png", - "width": 100.0, - "height": 100.0 - } - } -} - -// Detail Page -{ - "type": "hero", - "tag": "product-1", - "child": { - "type": "image", - "network": "https://example.com/product.png", - "width": 300.0, - "height": 300.0 - } -} -``` +```json JSON +{ + "listItem": { + "type": "gestureDetector", + "onTap": { + "actionType": "navigate", + "routeName": "/detail" + }, + "child": { + "type": "hero", + "tag": "product-1", + "child": { + "type": "image", + "network": "https://example.com/product.png", + "width": 100.0, + "height": 100.0 + } + } + }, + "detailPage": { + "type": "hero", + "tag": "product-1", + "child": { + "type": "image", + "network": "https://example.com/product.png", + "width": 300.0, + "height": 300.0 + } + } +} +```docs/guides/migration.mdx-212-212 (1)
212-212: Hyphenate the compound adjective in the heading.“Full-screen” should be hyphenated when used adjectivally.
✏️ Proposed fix
-## Full Screen Migration Example +## Full-screen Migration Exampledocs/guides/troubleshooting.mdx-115-124 (1)
115-124: Avoid comments inside JSON snippet.The
jsonblock includes//comments, which makes it invalid JSON and can break copy/paste. Consider moving the annotations outside the block or using a valid JSON-only snippet.🛠️ Suggested edit to keep JSON valid
-```json -// Correct -"actionType": "navigate" - -// Wrong -"type": "navigate" -"action": "navigate" -``` +Correct: +```json +{ "actionType": "navigate" } +``` +Incorrect: `{ "type": "navigate" }`, `{ "action": "navigate" }`docs/widgets/slider.mdx-43-48 (1)
43-48: Use double literals forvalueandmaxparameters.The
valueandmaxfields inStacSliderare explicitly typed asdouble, so the example must use double literals20.0and100.0instead of20and100. Thedivisionsparameter (correctly5as an int) requires no change.Suggested edit
child: StacSlider( id: 'example_slider', sliderType: StacSliderType.material, - value: 20, + value: 20.0, max: 100, + max: 100.0, divisions: 5,docs/changelog.mdx-8-12 (1)
8-12: Update v1.0.0 release date to the correct date."Release Date: 2024" is incorrect. The v1.0.0 release was published on 2021-05-25. Update to the specific date format (YYYY‑MM‑DD).
docs/styles/shape_borders.mdx-10-16 (1)
10-16: Missing documentation section forStacContinuousRectangleBorder.The table lists
StacContinuousRectangleBorderas an available shape border, but there's no corresponding Properties/Example section for it below. Consider adding documentation for this class to maintain consistency.Would you like me to help draft the missing section for
StacContinuousRectangleBorder?docs/actions/multi_action.mdx-13-13 (1)
13-13: Fix typo: "syncronous" should be "synchronous".📝 Proposed fix
-| sync | `bool` | Whether to execute the actions in syncronous or parallel. Defaults to `false`. | +| sync | `bool` | Whether to execute the actions in synchronous or parallel. Defaults to `false`. |
🧹 Nitpick comments (4)
docs/widgets/radio_group.mdx (1)
47-48: Consider addingidproperty to the example.The RadioGroup Properties table states that
id"will be used to save the selected value of radio," but the examples omit it. Addingidwould make the example more complete and help users understand how to persist the selected value.📝 Suggested addition for Dart
StacRadioGroup( + id: 'gender_selection', child: StacColumn(📝 Suggested addition for JSON
{ "type": "radioGroup", + "id": "gender_selection", "child": {Also applies to: 92-94
docs/styles/alignment.mdx (1)
6-6: Use the actual class name “StacAlignment” in the intro.Minor clarity tweak: the class name is camel‑cased in code, so matching it here reduces ambiguity.
✏️ Suggested wording
-The Stac Alignment class represents a point within a rectangle. It's used to align child widgets within their parent. +The StacAlignment class represents a point within a rectangle. It's used to align child widgets within their parent.docs/styles/box_constraints.mdx (1)
155-181: Consider clarifying the section title.This section demonstrates button-specific size constraints using
StacSizewithminimumSize/maximumSizeproperties, which is conceptually related but distinct fromStacBoxConstraints. The current title "With Button Style" is acceptable, but adding a brief note explaining that button styling usesStacSizerather thanStacBoxConstraintsdirectly would help readers understand the distinction.docs/widgets/scaffold.mdx (1)
45-48: Minor: Consider using a Stac action class for consistency.The
onPressedhandler uses a raw Map literal instead of a Stac action class. Other documentation files in this PR (e.g.,form.mdx) use typed action classes likeStacFormValidateAction. For consistency, consider using the appropriate Stac action class if one exists for function callbacks.
…set parser, and update changelog with new versions.
divyanshub024
changed the title
…nd action parameters across documentation files.
… levels for improved clarity.
2 participants
Description
Related Issues
Closes #
Type of Change