Merge branch 'main' into rewrite/ff-experts

docs/ff-concepts/design-system/design-system.md

@@ -239,9 +239,9 @@ To add a design system from a library, first, ensure that you [add a library dep
 
 ---
 
-## Loading Indicator
+## Loading Indicators
 
-To customize the loading indicators used in the app, you can make changes in this section. You have the option to specify the **Indicator Type**, **Color**, and **Radius**, and the preview of the changes will be displayed below.
+To customize the **Loading Indicators** used in the app, you can make changes in this section. You have the option to specify the **Indicator Type**, **Color**, and **Radius**, and the preview of the changes will be displayed below.
 
 <div style={{
     position: 'relative',
@@ -269,6 +269,10 @@ To customize the loading indicators used in the app, you can make changes in thi
 </div>
 <p></p>
 
+:::tip
+Avoid mis-sized loading indicators or components, which lead to jumping layouts. Ensure loading components match the size and position of the content they replace.
+:::
+
 If you prefer watching a video tutorial, here is the guide for you:
 
 <div style={{

docs/resources/data-representation/variables.md

@@ -34,7 +34,7 @@ When creating variables in FlutterFlow, there are a few important considerations
 Start by giving your variable a meaningful and descriptive name that reflects its purpose. This name will be used throughout your app to reference the variable, so it's important to keep it clear and consistent with your naming conventions. 
 
 :::tip[Recommended naming convention]
-We recommend the `lowerCamelCase` naming convention for variables.
+We recommend the `lowerCamelCase` naming convention for variables. Learn more about the **[recommended naming conventions](../style-guide.md)** used in FlutterFlow and Flutter projects. 
 :::
 
 ### Assigning a Data Type to a Variable

docs/resources/style-guide.md

@@ -0,0 +1,137 @@
+---
+slug: /resources/style-guide
+title: Naming Variables & Functions
+description: Naming conventions for FlutterFlow, including guidelines for widgets, components, state variables, constants, and more.
+tags: [Style Guide, Variables]
+keywords: [Style Guide, Variables]
+---
+
+# Naming Variables & Functions
+
+To make your code more maintainable, readable, and consistent, it’s essential to adopt clear naming conventions for variables, functions, and components.
+
+Best practices for naming conventions in app development (especially for projects using Flutter), aim to improve code readability, maintainability, and consistency across the application. Here are some general guidelines tailored for different aspects of a Flutter project:
+
+Various naming styles (as suggested by [Dart Effective Style Guide](https://dart.dev/effective-dart/style#identifiers)):
+
+- **UpperCamelCase** names capitalize the first letter of each word, including the first.
+
+- **lowerCamelCase** names capitalize the first letter of each word, except the first which is always lowercase, even if it's an acronym.
+
+- **lowercase_with_underscores** names use only lowercase letters, even for acronyms, and separate words with _.
+
+![various-naming-styles.png](imgs/various-naming-styles.png)
+
+**General Principles**
+- **Be Consistent:** Whatever conventions you choose, apply them consistently across the project.
+- **Be Descriptive:** Names should be self-explanatory, reducing the need for additional comments to explain what a variable, function, or class does.
+- **Avoid Abbreviations:** Unless it's a well-known abbreviation, spell out words to avoid confusion.
+
+
+## Variable Naming Convention
+This section outlines naming conventions for pages, components, state variables, custom data types, enums, and constants to ensure clarity and consistency throughout the project.
+
+
+### Pages & Components
+Use **UpperCamelCase** for all widgets, components, pages, and screen names to maintain consistency and readability. FlutterFlow ensures clarity by automatically adding "Widget" to widget names when generating code. For components, you can suffix the name with "Component" to clearly distinguish them. 
+
+Similarly, for pages and screens, include "Page" or "Screen" in the name to indicate their purpose. This approach aligns with Dart conventions for class names and ensures a well-organized project structure.
+
+:::tip[Do's]
+- **Use UpperCamelCase for Names:** Always use **UpperCamelCase** for widgets, components, pages, and screens. Examples: `CustomButton`, `UserProfilePage`, `MainViewComponent`.
+
+- **Include "Screen" or "Page" in Page Names:** Use "Screen" or "Page" in file names to identify UI screens or pages. Examples: `LoginScreen`, `SettingsPage`.
+
+- **Use Prefixes for Clarity When Necessary:** Add a prefix if it significantly improves clarity or prevents naming conflicts. Example: `AdminUserProfile` (to differentiate it from `CustomerUserProfile` or `UserProfile`).
+
+- **Be Descriptive and Clear in File Names:** Ensure names are descriptive enough to convey their purpose at a glance. Examples: `OrderConfirmationScreen`, `ProductDetailsPage`.
+:::
+
+:::danger[Don'ts]
+- **Don’t Use Unnecessary Prefixes:** Avoid prefixes that do not add clarity or are redundant. Bad Example: `AppPrimaryButton` (if `PrimaryButton` is sufficient).
+
+- **Don’t Add "Widget" Explicitly:** Avoid adding "Widget" to class or component names manually, as FlutterFlow already appends it during code generation. Bad Examples: `ButtonWidget`, `ProfileCardWidget`.
+
+- **Don’t Use LowerCamelCase for Class Names:** Reserve **lowerCamelCase** for variables and methods, not for components, or pages. Bad Examples: `loginButton`, `userProfile`.
+
+- **Don’t Mix Naming Conventions:** Maintain consistency with UpperCamelCase for all widgets, components, pages, and screens. Bad Examples: `userLogin`, `Profilecard`, `headerView`.
+
+- **Don’t Use Generic Names Without Purpose:** Avoid overly generic names that do not clearly convey the file’s intent. Bad Examples: `Main`, `View`, `Screen1`.
+
+:::
+
+
+Note that the style guidelines for Pages and Components also apply to **[Custom Widgets](../ff-concepts/adding-customization/custom-widgets.md)**, as Pages and Components created in FlutterFlow are internally generated as widgets.
+
+
+### Custom Data Types & Enums
+
+When naming custom data types and enums, use **UpperCamelCase** for consistency and clarity. Ensure that names are descriptive, providing a clear representation of the entity or purpose.
+
+:::tip[Do's]
+
+- **Use UpperCamelCase for Custom Data Types:** Name your custom data types using **UpperCamelCase**. Ensure that names are clear, concise, and descriptive, reflecting the entity they represent. Good Examples: `UserModel`, `ProductDetails`, `OrderItem`.
+
+- **Use consistent naming for Enum Names and Values:** Use **UpperCamelCase** for the enum name such as, `Status`, `ConnectionState`, `UserRole` and **lowerCamelCase** for its values e.g., `{active, inactive, pending}`. This approach aligns with Dart's enum naming guidelines and ensures consistency.
+
+- **Use Plural Names for Lists:** If the data type represents a List, use a plural name to clarify its purpose. Good Example: `OrderItems` (to represent multiple `OrderItem` objects).
+:::
+
+:::danger[Don'ts]
+
+- **Don’t Use All Lowercase or Mixed Case for Custom Data Types:** Avoid using all lowercase or inconsistent casing in data model class names, as it reduces readability. Bad Example: `usermodel`, `product_details`.
+
+- **Don’t Use Vague or Non-Descriptive Names**: Avoid using generic or unclear names that do not clearly describe the data entity. Bad Example: `DataModel`, `Entity`, `Item`.
+
+- **Don’t Mix Naming Conventions for Enums:** Maintain consistent capitalization between enum names and their values. Bad Example: `enum UserRole { Admin, EDITOR, viewer }`
+:::
+
+### Constants
+
+Flutter prefers using a lowercase `k` prefix for constants to indicate their immutability, especially for project-specific constants. This approach is more concise and aligns with Dart's common practices. Use **SCREAMING_SNAKE_CASE** only when contributing to global or legacy projects where it is already in use.
+
+:::tip[Do's]
+- **Start Constants with a k Prefix:** Always use a lowercase `k` followed by **UpperCamelCase** for constants in FlutterFlow projects.
+- **Use Descriptive and Contextual Names:** Clearly describe the purpose of the constant. Avoid using abbreviations unless they are widely understood. Examples: `kDefaultPadding`, `kMaxUploadSizeMb`
+:::
+
+:::danger[Don'ts]
+- **Don’t Omit the k Prefix for Constants:** Avoid using plain names for constants in a Flutter-specific project, as they might conflict with variables or methods. Bad Examples: `padding`, `uploadSize`.
+- **Don’t Use Vague or Generic Names:** Avoid using names that fail to describe the purpose of the constant. Bad Examples: `VALUE`, `DATA`, `X`, `Y`.
+:::
+
+### State Variables 
+
+State variable names follow the **lowerCamelCase** naming style to align with Dart's conventions.
+
+:::tip[Do's]
+- **Be Descriptive and Clear:** Use variable names that clearly describe their purpose, avoiding generic or vague terms. Examples: `isFormValid`, `errorMessage`, `availableProducts`.
+- **Prefix Boolean Variables with `is`, `has`, or `should`:** For readability, use prefixes that denote the variable's purpose when naming Boolean values. Examples: `isActive`, `hasErrors`, `shouldReload`.
+- **Use Consistent Prefixes to denote state:** When managing UI or asynchronous state, use prefixes like `current`, `selected`, or `pending` for better context. Examples: `currentTabIndex`, `selectedUserId`, `pendingAction`.
+:::
+
+:::danger[Don'ts]
+- **Don’t Use Abbreviations or Single Letters:** Avoid abbreviations or single-character names that obscure the variable's intent. Bad Examples: `usrNm`, `f`, `cnt`.
+- **Don’t Use Generic Names:** Avoid using generic terms that do not convey the variable’s purpose. Bad Examples: `data`, `value`, `temp`.
+- **Don’t Start State Variables with Uppercase:** Follow Dart conventions by starting variable names with lowercase. Bad Examples: `UserName`, `IsLoading`.
+:::
+
+## Function Naming Convention
+This section defines naming conventions for custom functions, actions, and action blocks to maintain consistency, readability, and ease of understanding across the codebase.
+
+### Custom Functions & Actions
+
+Custom functions and custom actions created in the Custom Code tab of FlutterFlow should follow the **lowerCamelCase** naming convention. These typically reflect an action or behavior.
+
+:::tip[Do's]
+- **Be descriptive and concise:** Use clear, meaningful names that describe the action or purpose of the function (e.g., `validateForm` instead of `doCheck`, or `fetchUserData` instead of `userData`).
+- **Use action-oriented names:** Start with verbs to indicate behavior (e.g., `submitForm`, `processPayment`).
+:::
+
+:::danger[Dont's]
+- **Avoid using underscores or spaces:** Names like `fetch_user_data` do not align with **lowerCamelCase** conventions.
+- **Avoid redundant prefixes or suffixes:** There’s no need to prefix with `custom` or suffix with `Func` unless absolutely necessary for clarity (e.g., `customSubmitFormFunc` is redundant).
+- **Don’t use overly generic names:** Avoid vague terms like `doSomething` or `functionOne`, which don’t provide context.
+:::
+
+Note that **[Action Blocks](../resources/control-flow/functions/action-blocks.md)** should follow the same naming convention as custom actions, as they are both technically Dart functions internally in the generated code.

docs/resources/ui/widgets/composing-widgets/list-grid.md

@@ -29,6 +29,10 @@ Axis sets the orientation of the ListView. You can select either "Vertical" or
 - **Items Spacing:** This defines the space between individual items in the ListView. You can
   specify the spacing in pixels.
 
+:::tip[Items Spacing vs Padding]
+Prefer “Items Spacing” set on the parent row or column instead of padding on individual elements. This ensures consistency, especially on non-dynamically generated lists.
+:::
+
 - **Apply to Start & End:** When enabled, the item spacing will also be applied to the start and the
   end of the ListView, adding a margin at the beginning and end of the list. This effectively adds padding at the start and end of the layout in addition to between the items.
 

docs/resources/ui/widgets/composing-widgets/rows-column-stack.md

@@ -30,6 +30,10 @@ depends on how you need to arrange your UI components:
 
 ![row-col-stack.png](../../imgs/row-col-stack.png)
 
+:::tip[Minimum Layout Nesting]
+Use the minimum amount of rows/columns necessary to achieve your layout to avoid unnecessary complexity. No page or component should nest more than 10 levels deep. Reaching this limit likely signals the need for **[converting a part of the widget tree into components](../../components/creating-components.md#convert-into-a-component)**.
+:::
+
 <!---TODO #### Choosing your parent widget
 link to quickstart for how to choose parent widget [Rows/Column/Stacks]
 with examples --->
@@ -218,6 +222,10 @@ incoming constraints and the scrolling movement, effectively managing overflow b
   Column. You can specify a static numerical value that determines the pixel spacing between 
   adjacent children or set it from a variable.
 
+:::tip[Items Spacing vs Padding]
+Prefer “Items Spacing” set on the parent row or column instead of padding on individual elements. This ensures consistency, especially on non-dynamically generated lists.
+:::
+
 - **Apply to Start & End:** When toggled on, this applies the specified item spacing to the 
   beginning and the end of the Row or Column. This effectively adds padding at the start and end of the layout in addition to between the items.
 

docs/resources/ui/widgets/widget-commonalities.md

@@ -47,7 +47,7 @@ com/embed/f510565b464c4fb8903c0b6993fc8c20?sid=ceb9de2e-af71-4ba0-b888-b6d4e47d6
 
 
 
-### Responsive
+### Responsive Properties
 
 When developing user interfaces with widgets, you'll notice certain properties and features that are universally applicable. This section provides guidance on adjusting these shared attributes across different widgets.
 
@@ -75,7 +75,7 @@ Here is how it is done:
   <figcaption class="centered-caption">Responsive visibility for web</figcaption>
 </figure>
 
-#### Customize responsive breakpoint
+#### Customize Responsive Breakpoint
 
 Sometimes, you might want to override the default responsive breakpoint to suit unique requirements; whether it's accommodating a specific device or catering to a particular user experience, having the flexibility to customize breakpoints can be advantageous.
 
@@ -154,7 +154,7 @@ com/embed/iMc1m-l7eyw" frameborder="0" allow="accelerometer; autoplay; clipboard
 
 
 
-### Adjust alignment
+### Adjust Alignment
 
 This property helps you position the widget in two ways.
 
@@ -179,11 +179,11 @@ com/embed/vuJ2fTnYyCM" frameborder="0" allow="accelerometer; autoplay; clipboard
 
 
 
-## Testing
+## Testing Widgets
 
 This property enables you to specify the **Value Key** for the current widget, which serves as a reference point during automated test runs. Please refer to the detailed guide provided [here](../../../testing-deployment-publishing/testing/automated-tests.md).
 
-## Changing the size
+## Set Width & Height Properties
 
 To change the size, navigate to the **Width** and **Height** properties, and then you have three choices for setting the size:
 
@@ -195,21 +195,21 @@ To change the size, navigate to the **Width** and **Height** properties, and the
 com/embed/aa1755b1b7b94ef3ac3a72da431d844f?sid=982c1f26-b768-4c8d-ab77-c085219ebab6" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe></div>
 
 
-## Change color
+## Change Color
 
 To change color for any widget property:
 
 1. Navigate to a widget property that allows you to set a color.
 2. Click on the currently selected color to either pick a new color or enter the Hex Code directly.
 3. By default, theme colors are displayed. Simply click on a color to apply it.
 4. For a custom color, switch to the **Custom Color** tab, select your desired color, and then click **Use Color**.
-5. You can also set a [color from variable](#setting-color-from-variable).
+5. You can also set a [color from variable](#set-color-from-variable).
 
 <div class="video-container"><iframe src="https://www.loom.
 com/embed/7fb8cd068bbb45c9ae34cfd4f325a3dc?sid=b3559d67-9e11-4501-8a17-7f4e92bd5847" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe></div>
 
 
-## Setting color from variable
+## Set Color From Variable
 
 You may want to apply dynamic colors to widget properties like Container backgrounds or Text colors, which can be achieved by assigning colors from a variable. For instance, you can display temperature color dynamically based on an app state variable, data from a Firestore document, responses from API calls, or other similar sources.
 
@@ -253,7 +253,7 @@ com/embed/6bffe7446e1d414f99baee759fda8fc0?sid=abfedd7c-3bc4-4eda-a9ab-341b72e4b
 
 You can also set the color from a [conditional value](../../../resources/control-flow/functions/conditional-logic.md#setting-widget-properties-with-conditional-logic).
 
-## Copy variable
+## Copy Variable
 
 If you have a complex variable value (e.g., using [Conditional Logic](../../../resources/control-flow/functions/conditional-logic.md)) and want to use the same logic in another variable value, you can do so by copying a variable.
 
@@ -283,7 +283,7 @@ com/embed/f3cdb87b927b46508a2f1c21c2524cfe?sid=bb94b178-cba5-4423-afd0-47a4669c2
 
 <p></p>
 
-## Add an image from Unsplash
+## Add Image from Unsplash
 
 You can also add images directly from the [Unsplash](https://unsplash.com/) right inside the properties panel. To do so, simply click on the search icon and search and select the image. **Tip**: You can also choose the size of the image to add (i.e., Small, Regular, Full).
 
@@ -292,13 +292,11 @@ com/embed/6954aafd8e494e74b52a2e89d4744e39?sid=8cd4d95b-e338-41f1-ae8a-912422f58
 
 <p></p>
 
-## UI builder display value
-
-For widgets like **Text** and **RichText**, when their content is coming from a variable, you have the option to set a placeholder value that will be displayed only in the app builder. Keep in mind that this display value is solely for visualization purposes within the canvas and will be replaced with the actual variable value when the app is running.
-
-This is helpful in assessing spacing and alignment without the need to remove variable bindings.
+## UI Builder Display Value
 
+For widgets like `Text` and `RichText`, when their content is set from a variable, you can set a placeholder value to be displayed only in the app builder. Keep in mind that this placeholder is solely for visualization purposes within the canvas and will be replaced by the actual variable value when the app runs.
 
+This feature is useful for assessing spacing and alignment without removing variable bindings.
 
 ![img_4.png](..%2Fimgs%2Fimg_4.png)
 ## Trigger action on selection change