Added documentation for conditional rendering in Stac #411
Conversation
Summary Created documentation for conditional rendering in Stac. Created Documentation File Location: docs/concepts/conditional_rendering.mdx Content: Covers: What conditional rendering is — overview of the conditional widget and its purpose Supported conditions and operators — tables for: Comparison operators (==, !=, >, <, >=, <=) Logical operators (&&, ||) Mathematical operations (+, -, *, /, %) Supported values (numbers, booleans, strings, null) How conditions are evaluated at runtime — explanation of the ExpressionResolver evaluation process Usage examples — including: Basic boolean comparisons String comparisons Mathematical expressions Logical operators Nested conditionals Real-world examples (authentication, feature flags) Updated Navigation Added the new documentation page to docs/docs.json in the Concepts section The documentation includes: Overview and explanation of how conditional rendering works Complete operator reference with examples Multiple usage examples from simple to advanced JSON schema reference Best practices and limitations Error handling information The documentation is ready and integrated into the Stac documentation site. Users can find it in the Concepts section alongside other core concepts like theming, caching, and custom widgets.
|
|
📝 WalkthroughWalkthroughAdds new documentation for Stac's conditional rendering feature, updates docs navigation to include the new page, and extends the Stac package README with a DSL/Dart example. No code or runtime behavior changes. Changes
Sequence Diagram(s)(omitted — changes are documentation-only and do not modify runtime control flow) Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related issues
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 📜 Recent review detailsConfiguration used: defaults Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
✏️ Tip: You can disable this entire section by setting 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: 2
🤖 Fix all issues with AI agents
In @docs/concepts/conditional_rendering.mdx:
- Around line 308-312: The "Limitations" section currently claims conditions
cannot access app state, which contradicts the examples using user.isLoggedIn ==
true and featureFlags.newUI == true; update the Limitations paragraph to clarify
that condition expressions can reference variables from the evaluation context
(e.g., user.isLoggedIn, featureFlags.newUI) and describe the
substitution/evaluation behavior (what scope is available and any restrictions),
or alternatively change the examples to show explicit variable substitution
before evaluation — ensure you mention the example patterns user.isLoggedIn ==
true and featureFlags.newUI == true so readers see the clarified behavior.
- Line 99: Update the example so the "condition" property uses quoted string
operands consistent with the documented format: inside the condition string wrap
each string operand in quotes (double or single) rather than leaving them
unquoted, so the expression follows the documented `"hello"`/`'world'` style;
change the example value assigned to the "condition" key accordingly and keep
the surrounding JSON string syntax intact.
🧹 Nitpick comments (1)
docs/concepts/conditional_rendering.mdx (1)
311-311: Clarify "built-in math functions" statement.The parenthetical "(except built-in math functions)" is vague. If there are built-in functions available, they should be documented in the "Supported Conditions and Operators" section. If there are none, consider removing this exception clause.
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs/concepts/conditional_rendering.mdxdocs/docs.json
🧰 Additional context used
🪛 LanguageTool
docs/concepts/conditional_rendering.mdx
[style] ~298-~298: To elevate your writing, try using a synonym here.
Context: ...ns simple**: Complex expressions can be hard to debug. Consider breaking them into n...
(HARD_TO)
🔇 Additional comments (2)
docs/concepts/conditional_rendering.mdx (1)
1-328: Overall documentation is comprehensive and well-structured.The documentation covers the essential aspects of conditional rendering including operators, usage examples, JSON schema, best practices, and error handling. The examples progress logically from basic to advanced usage.
docs/docs.json (1)
41-41: Navigation entry correctly added.The new page entry aligns with the documentation file path and is logically placed in the Concepts group after the rendering widgets concept.
|
Hey @Chidwan3578!! Thank you for the quick contribution 🎉 |
|
Done ;) |
divyanshub024
left a comment
divyanshub024
left a comment
There was a problem hiding this comment.
Hey @Chidwan3578!!
Thank you for this amazing PR. Can you please check my suggestions.
Also, can you please update the PR title and a proper description.
| ```json | ||
| { | ||
| "type": "conditional", | ||
| "condition": "5 > 3", | ||
| "ifTrue": { | ||
| "type": "text", | ||
| "data": "5 is greater than 3" | ||
| }, | ||
| "ifFalse": { | ||
| "type": "text", | ||
| "data": "5 is not greater than 3" | ||
| } | ||
| } |
There was a problem hiding this comment.
Can you also add the Stac DSL/Dart example as well. Since it's the recommended way for Stac.
There was a problem hiding this comment.
added an example for DSL/Dart.
There was a problem hiding this comment.
Can we add the Dart example for all JSONs?
| }, | ||
| "body": { | ||
| "type": "conditional", | ||
| "condition": "user.isLoggedIn == true", |
There was a problem hiding this comment.
The variables in stac are used like this {{user.isLoggedIn}}
|
|
||
| ## Limitations | ||
|
|
||
| - **No variable access**: Currently, conditions cannot access app state or variables directly. They evaluate static expressions only. |
There was a problem hiding this comment.
This is not fully true. It can access variables from the network request.
There was a problem hiding this comment.
Updated the documentation to clarify that conditions can access variables from resolved data sources (e.g. network responses), while still not supporting local widget state or arbitrary Dart variables.
|
|
||
| - **No variable access**: Currently, conditions cannot access app state or variables directly. They evaluate static expressions only. | ||
| - **No function calls**: Custom functions cannot be called within conditions (except built-in math functions). | ||
| - **String operations**: String concatenation is supported, but other string operations are limited. |
There was a problem hiding this comment.
Can you please eleborate on this?
There was a problem hiding this comment.
Added more detailed explanations for each limitation to clarify what is and isn’t supported in conditional expressions.
Changed according to requests
Chidwan3578
changed the title
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@packages/stac/README.md`:
- Around line 40-62: Move the entire "Stac DSL/Dart Example" section (the
heading "## Stac DSL/Dart Example" and its Dart code block plus the "For more
details..." line) out of the middle of the Features list and place it after the
existing feature bullets (i.e., after the block that continues on line ~66) so
all feature bullets remain contiguous under "Features" and the example becomes
its own standalone section; update surrounding spacing so the Features list is
uninterrupted and the relocated section has a blank line before and after.
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs/concepts/conditional_rendering.mdxpackages/stac/README.md
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/concepts/conditional_rendering.mdx
✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.
|
|
||
| ## Stac DSL/Dart Example | ||
|
|
||
| The Stac DSL allows you to define widgets directly in Dart, which is then compiled to JSON. Here's a simple example: | ||
|
|
||
| ```dart | ||
| import 'package:stac/stac.dart'; | ||
| @StacWidget() | ||
| class MyButton extends StatelessWidget { | ||
| const MyButton({super.key}); | ||
| @override | ||
| Widget build(BuildContext context) { | ||
| return ElevatedButton( | ||
| onPressed: () {}, | ||
| child: const Text('Click me'), | ||
| ); | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| For more details, see the [documentation](https://docs.stac.dev/). |
There was a problem hiding this comment.
Relocate section to fix document structure.
The "Stac DSL/Dart Example" section is inserted in the middle of the Features list, breaking the document's logical flow. Lines 37-39 contain feature bullets, this section interrupts them, and lines 63-66 continue with more feature bullets.
📝 Suggested relocation
Move this entire section (lines 40-62) to appear after line 66, so all feature bullets remain together under the Features heading:
## Features
- 🚀 Instant updates: Ship UI without app store releases.
- 🧩 JSON‑driven UI: Define widgets in JSON; render natively.
- 📦 Dart to JSON: Write Stac widgets in Dart and deploy to Stac Cloud.
-
-## Stac DSL/Dart Example
-
-The Stac DSL allows you to define widgets directly in Dart, which is then compiled to JSON. Here's a simple example:
-
-```dart
-import 'package:stac/stac.dart';
-
-@StacWidget()
-class MyButton extends StatelessWidget {
- const MyButton({super.key});
-
- `@override`
- Widget build(BuildContext context) {
- return ElevatedButton(
- onPressed: () {},
- child: const Text('Click me'),
- );
- }
-}
-```
-
-For more details, see the [documentation](https://docs.stac.dev/).
- 🎛 Actions & navigation: Control routes and API calls from the backend.
- 📝 Forms & validation: Built-in form state and validation rules.
- 🎨 Theming: Brand and layout via JSON with Stac Theme.
- 🔌 Extensible: Add custom widgets, actions, and native integrations.
+
+## Stac DSL/Dart Example
+
+The Stac DSL allows you to define widgets directly in Dart, which is then compiled to JSON. Here's a simple example:
+
+```dart
+import 'package:stac/stac.dart';
+
+@StacWidget()
+class MyButton extends StatelessWidget {
+ const MyButton({super.key});
+
+ `@override`
+ Widget build(BuildContext context) {
+ return ElevatedButton(
+ onPressed: () {},
+ child: const Text('Click me'),
+ );
+ }
+}
+```
+
+For more details, see the [documentation](https://docs.stac.dev/).🤖 Prompt for AI Agents
In `@packages/stac/README.md` around lines 40 - 62, Move the entire "Stac DSL/Dart
Example" section (the heading "## Stac DSL/Dart Example" and its Dart code block
plus the "For more details..." line) out of the middle of the Features list and
place it after the existing feature bullets (i.e., after the block that
continues on line ~66) so all feature bullets remain contiguous under "Features"
and the example becomes its own standalone section; update surrounding spacing
so the Features list is uninterrupted and the relocated section has a blank line
before and after.
|
|
||
| ## Stac DSL/Dart Example | ||
|
|
||
| The Stac DSL allows you to define widgets directly in Dart, which is then compiled to JSON. Here's a simple example: | ||
|
|
||
| ```dart | ||
| import 'package:stac/stac.dart'; | ||
| @StacWidget() | ||
| class MyButton extends StatelessWidget { | ||
| const MyButton({super.key}); | ||
| @override | ||
| Widget build(BuildContext context) { | ||
| return ElevatedButton( | ||
| onPressed: () {}, | ||
| child: const Text('Click me'), | ||
| ); | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| For more details, see the [documentation](https://docs.stac.dev/). |
There was a problem hiding this comment.
Hey, this change is not required.
3 participants
Summary
Created documentation for conditional rendering in Stac. Created Documentation File
Location: docs/concepts/conditional_rendering.mdx
Content: Covers:
What conditional rendering is — overview of the conditional widget and its purpose Supported conditions and operators — tables for:
Comparison operators (==, !=, >, <, >=, <=)
Logical operators (&&, ||)
Mathematical operations (+, -, *, /, %)
Supported values (numbers, booleans, strings, null) How conditions are evaluated at runtime — explanation of the ExpressionResolver evaluation process Usage examples — including:
Basic boolean comparisons
String comparisons
Mathematical expressions
Logical operators
Nested conditionals
Real-world examples (authentication, feature flags) Updated Navigation
Added the new documentation page to docs/docs.json in the Concepts section The documentation includes:
Overview and explanation of how conditional rendering works Complete operator reference with examples
Multiple usage examples from simple to advanced
JSON schema reference
Best practices and limitations
Error handling information
The documentation is ready and integrated into the Stac documentation site. Users can find it in the Concepts section alongside other core concepts like theming, caching, and custom widgets.
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.