MiReorderList

The MiReorderList component is a stateless Flutter widget that displays a list of items which can be reordered by the user using drag and drop. It leverages Flutter's ReorderableListView to provide a user-friendly interface for list reordering, and it updates the underlying data list bound to the component when the order changes.

Overview

MiReorderList is designed to present lists where the order of items is important and user-adjustable. Key features include:

• Reorderable List: Allows users to reorder list items by dragging and dropping them within the list.
• Data Binding: Binds to a list in the application's data model, and automatically updates this list when items are reordered in the UI.
• Customizable Item Display: Uses a Container with basic styling to represent each item, and allows customization of the text displayed in each item card via parameters.
• Visual Feedback: Provides visual feedback during reordering with a scale animation on the dragged item.
• No API Interaction: MiReorderList itself is purely a UI component for displaying and reordering local data. It does not handle API calls directly. For use cases requiring data persistence or fetching, it's typically used within a page or component that manages API interactions.
• Efficient Reordering: Uses ReorderableListView for smooth and performant reordering even with long lists.

Component Name: reorderListView

JSON key: "component": "reorderListView".

Parameters

Parameter Key	JSON Value Type	Flutter Type	Description	Default Value	Nullable	Requires Build
listKey	String	List<dynamic>	List Data Key: Key to access the list of data items in the application's state that will be displayed and reordered in the MiReorderList. The component directly manipulates the list referenced by this key to reflect reordering changes.	null	Yes	No
pageItemCardLine1	String	String	Item Card Line 1 Key: Key to the item property (within each object in the listKey list) to be displayed as the primary text line in each reorderable item card.	null	Yes	No
pageItemCardLine2	String	String	Item Card Line 2 Key: Key to the item property (within each object in the listKey list) to be displayed as the secondary text line in each reorderable item card, appearing below pageItemCardLine1.	null	Yes	No
padding	List<num>	EdgeInsets	Padding: Padding around the MiReorderList widget itself. Inherited from MiStatelessWidget.	null	Yes	No
margin	List<num>	EdgeInsets	Margin: Margin around the MiReorderList widget. Inherited from MiStatelessWidget.	null	Yes	No
alignment	String	AlignmentGeometry	Alignment: Alignment of the MiReorderList widget within its parent. Inherited from MiStatelessWidget.	"topLeft"	Yes	No
color	String	Color	Item Card Color: Background color of each reorderable item card in the list.	Theme's white color	Yes	No
width	num	double	Width: Fixed width of the MiReorderList widget. Inherited from MiStatelessWidget.	null	Yes	No
height	num	double	Height: Fixed height of the MiReorderList widget. Inherited from MiStatelessWidget.	null	Yes	No

Note:

• Reordering Mechanism: Users reorder items by long-pressing and dragging an item to its desired new position in the list. The component visually highlights the dragged item and updates the list order in real-time.
• Data List Update: When an item is reordered, the MiReorderList directly modifies the list of data in the application state that is associated with the listKey. This means that any other components or parts of the application bound to the same data list will automatically reflect the new order.
• Item Card Styling: Each item in the MiReorderList is rendered within a Container that provides a card-like appearance with rounded corners, a white background (by default, customizable via color), and a subtle shadow. The content of the card is determined by pageItemCardLine1 and pageItemCardLine2.
• Visual Proxy Decorator: During the reordering process, a proxyDecorator is used to provide visual feedback by scaling up the dragged item slightly, enhancing the user experience.
• Empty List Handling: If the list bound to listKey is empty or null, MiReorderList will display a simple "No items" message to indicate that there is no data to display.
• Usage within Pages: MiReorderList is often used within a page layout, especially in scenarios where you need a dedicated screen for reordering items. The provided MiReorderListPage is an example of a page component that embeds MiReorderList and adds a "Save" button to potentially persist the reordered list (though the save action itself is not part of MiReorderList).

Example JSON Configuration

{
  "component": "reorderListView",
  "listKey": "${ORDERED_TASKS}",
  "pageItemCardLine1": "${TASK_NAME}",
  "pageItemCardLine2": "${TASK_DESCRIPTION}",
  "margin": [0, 16, 0, 16]
}

Explanation of Example:

• "component": "reorderListView": Specifies the component as MiReorderList.
• "listKey": "${ORDERED_TASKS}": Binds the MiReorderList to the data list located at the key ORDERED_TASKS in the application's state. This list will be displayed and updated when reordering occurs.
• "pageItemCardLine1": "${TASK_NAME}": Configures the first line of each item card to display the value of the TASK_NAME property from each item in the ORDERED_TASKS list.
• "pageItemCardLine2": "${TASK_DESCRIPTION}": Configures the second line of each item card to display the value of the TASK_DESCRIPTION property.
• "margin": [0, 16, 0, 16]: Adds vertical margins (16 logical pixels top and bottom) around the MiReorderList widget to space it from surrounding content.

This configuration will render a reorderable list of tasks. Each item in the list will display the task name as the primary line and the task description as the secondary line. Users can drag and drop tasks to change their order, and this reordering will directly update the ORDERED_TASKS list in the application's data.