Add ability to programmatically control focus on list and grid

Author: Exidex

dev_plugin/src/test-grid-focus.tsx

@@ -1,27 +1,43 @@
-import { ReactElement } from "react";
-import { Grid } from "@project-gauntlet/api/components";
+import { ReactElement, useState } from "react";
+import { Action, ActionPanel, Grid } from "@project-gauntlet/api/components";
 
 export default function Main(): ReactElement {
-    const content = (
+    const [id, setId] = useState<string | null>(null);
+
+    const content = (id: string) => (
         <Grid.Item.Content>
             <Grid.Item.Content.Paragraph>
-                Test
+                {id}
             </Grid.Item.Content.Paragraph>
         </Grid.Item.Content>
     );
-    
+
     return (
-        <Grid onItemFocusChange={(id: string | null) => console.log("onItemFocusChange", id)}>
-            <Grid.Item id="adarian" title="Adarian">{content}</Grid.Item>
-            <Grid.Item id="aruzan" title="Aruzan">{content}</Grid.Item>
-            <Grid.Item id="blutopian" title="Blutopian">{content}</Grid.Item>
-            <Grid.Item id="caphex" title="Caphex">{content}</Grid.Item>
-            <Grid.Item id="condluran" title="Condluran">{content}</Grid.Item>
-            <Grid.Item id="frozian" title="Frozian">{content}</Grid.Item>
-            <Grid.Item id="evereni" title="Evereni">{content}</Grid.Item>
-            <Grid.Item id="ezaraa" title="Ezaraa">{content}</Grid.Item>
-            <Grid.Item id="houk" title="Houk">{content}</Grid.Item>
-            <Grid.Item id="inleshat" title="Inleshat">{content}</Grid.Item>
+        <Grid
+            onItemFocusChange={setId}
+            focusedItemId={id}
+            actions={
+                <ActionPanel>
+                    <Action
+                        label={`Focused: ${id}`}
+                        onAction={(id) => {
+                            console.log(id)
+                            setId("condluran")
+                        }}
+                    />
+                </ActionPanel>
+            }
+        >
+            <Grid.Item id="adarian" title="Adarian">{content("adarian")}</Grid.Item>
+            <Grid.Item id="aruzan" title="Aruzan">{content("aruzan")}</Grid.Item>
+            <Grid.Item id="blutopian" title="Blutopian">{content("blutopian")}</Grid.Item>
+            <Grid.Item id="caphex" title="Caphex">{content("caphex")}</Grid.Item>
+            <Grid.Item id="condluran" title="Condluran">{content("condluran")}</Grid.Item>
+            <Grid.Item id="frozian" title="Frozian">{content("frozian")}</Grid.Item>
+            <Grid.Item id="evereni" title="Evereni">{content("evereni")}</Grid.Item>
+            <Grid.Item id="ezaraa" title="Ezaraa">{content("ezaraa")}</Grid.Item>
+            <Grid.Item id="houk" title="Houk">{content("houk")}</Grid.Item>
+            <Grid.Item id="inleshat" title="Inleshat">{content("inleshat")}</Grid.Item>
         </Grid>
     )
 }

dev_plugin/src/test-list-focus.tsx

@@ -5,7 +5,7 @@ export default function Main(): ReactElement {
     const [id, setId] = useState<string | null>(null);
 
     return (
-        <List onItemFocusChange={setId}>
+        <List onItemFocusChange={setId} focusedItemId={id}>
             <List.Item id="adarian" title="Adarian"/>
             <List.Item id="aruzan" title="Aruzan"/>
             <List.Item id="blutopian" title="Blutopian"/>

docs/js/components/grid/props/focusedItemId.md

@@ -0,0 +1 @@
+Sets item with specified id to be the one that is focused

docs/js/components/list/props/focusedItemId.md

@@ -0,0 +1 @@
+Sets item with specified id to be the one that is focused

js/api/src/gen/components.tsx

@@ -151,6 +151,7 @@ declare global {
                 children?: ElementComponent<typeof ActionPanel | typeof ListItem | typeof ListSection | typeof SearchBar | typeof EmptyView | typeof Detail>;
                 isLoading?: boolean;
                 onItemFocusChange?: (itemId: string | null) => void;
+                focusedItemId?: string | null;
             };
             ["gauntlet:grid_item"]: {
                 children?: ElementComponent<typeof IconAccessory | typeof Content>;
@@ -169,6 +170,7 @@ declare global {
                 isLoading?: boolean;
                 columns?: number;
                 onItemFocusChange?: (itemId: string | null) => void;
+                focusedItemId?: string | null;
             };
         }
     }
@@ -700,6 +702,7 @@ export interface ListProps {
     actions?: ElementComponent<typeof ActionPanel>;
     isLoading?: boolean;
     onItemFocusChange?: (itemId: string | null) => void;
+    focusedItemId?: string | null;
 }
 export const List: FC<ListProps> & {
     Item: typeof ListItem;
@@ -708,7 +711,7 @@ export const List: FC<ListProps> & {
     EmptyView: typeof EmptyView;
     Detail: typeof Detail;
 } = (props: ListProps): ReactNode => {
-    return <gauntlet:list isLoading={props.isLoading} onItemFocusChange={props.onItemFocusChange}>{props.actions as any}{props.children}</gauntlet:list>;
+    return <gauntlet:list isLoading={props.isLoading} onItemFocusChange={props.onItemFocusChange} focusedItemId={props.focusedItemId}>{props.actions as any}{props.children}</gauntlet:list>;
 };
 List.Item = ListItem;
 List.Section = ListSection;
@@ -746,14 +749,15 @@ export interface GridProps {
     actions?: ElementComponent<typeof ActionPanel>;
     columns?: number;
     onItemFocusChange?: (itemId: string | null) => void;
+    focusedItemId?: string | null;
 }
 export const Grid: FC<GridProps> & {
     Item: typeof GridItem;
     Section: typeof GridSection;
     SearchBar: typeof SearchBar;
     EmptyView: typeof EmptyView;
 } = (props: GridProps): ReactNode => {
-    return <gauntlet:grid isLoading={props.isLoading} columns={props.columns} onItemFocusChange={props.onItemFocusChange}>{props.actions as any}{props.children}</gauntlet:grid>;
+    return <gauntlet:grid isLoading={props.isLoading} columns={props.columns} onItemFocusChange={props.onItemFocusChange} focusedItemId={props.focusedItemId}>{props.actions as any}{props.children}</gauntlet:grid>;
 };
 Grid.Item = GridItem;
 Grid.Section = GridSection;

rust/client/src/ui/scroll_handle.rs

@@ -65,6 +65,13 @@ impl ScrollHandle {
         }
     }
 
+    pub fn from(scroll_handle: &ScrollHandle, current_item_id: Option<container::Id>) -> ScrollHandle {
+        ScrollHandle {
+            scrollable_id: scroll_handle.scrollable_id.clone(),
+            current_item_id,
+        }
+    }
+
     pub fn get<'a, T>(&self, items: &'a ScrollContent<T>) -> Option<&'a T> {
         self.get_by_id(items, self.current_item_id.clone())
     }
@@ -121,7 +128,8 @@ impl ScrollHandle {
         grid: Vec<Vec<container::Id>>,
     ) -> (Option<container::Id>, Option<Task<AppMsg>>) {
         let Some(current_item_id) = &self.current_item_id else {
-            return (None, self.focus_target(behavior.unfocused(grid)));
+            let target_item_id = behavior.unfocused(grid);
+            return (target_item_id.clone(), self.focus_target(target_item_id));
         };
 
         let Some((row_index, row)) = grid.iter().find_position(|row| row.contains(&current_item_id)) else {

rust/client/src/ui/widget/data.rs

@@ -6,6 +6,7 @@ use gauntlet_common::model::ActionPanelWidgetOrderedMembers;
 use gauntlet_common::model::GridSectionWidgetOrderedMembers;
 use gauntlet_common::model::GridWidget;
 use gauntlet_common::model::GridWidgetOrderedMembers;
+use gauntlet_common::model::JsOption;
 use gauntlet_common::model::ListSectionWidgetOrderedMembers;
 use gauntlet_common::model::ListWidget;
 use gauntlet_common::model::ListWidgetOrderedMembers;
@@ -27,7 +28,6 @@ use crate::ui::widget::action_panel::convert_action_panel;
 use crate::ui::widget::data_mut::ComponentWidgetsMut;
 use crate::ui::widget::events::ComponentWidgetEvent;
 use crate::ui::widget::state::ComponentWidgetStateContainer;
-use crate::ui::widget::state::ScrollableRootState;
 use crate::ui::widget::state::TextFieldState;
 
 #[derive(Debug)]
@@ -115,20 +115,34 @@ impl<'b> ComponentWidgets<'b> {
             RootWidgetMembers::Form(_) => None,
             RootWidgetMembers::Inline(_) => None,
             RootWidgetMembers::List(widget) => {
-                let ScrollableRootState {
-                    scroll_handle: focused_item,
-                    ..
-                } = self.state.scrollable_root_state(widget.__id__);
-
-                self.list_focused_item_id(focused_item, focused_item.current_item_id.clone(), widget)
+                match &widget.focused_item_id {
+                    JsOption::Undefined => {
+                        let state = self.state.scrollable_root_state(widget.__id__);
+
+                        self.list_focused_item_id(
+                            &state.scroll_handle,
+                            state.scroll_handle.current_item_id.clone(),
+                            widget,
+                        )
+                    }
+                    JsOption::Null => None,
+                    JsOption::Value(value) => Some(value.clone()),
+                }
             }
             RootWidgetMembers::Grid(widget) => {
-                let ScrollableRootState {
-                    scroll_handle: focused_item,
-                    ..
-                } = self.state.scrollable_root_state(widget.__id__);
-
-                self.grid_focused_item_id(focused_item, focused_item.current_item_id.clone(), widget)
+                match &widget.focused_item_id {
+                    JsOption::Undefined => {
+                        let state = self.state.scrollable_root_state(widget.__id__);
+
+                        self.grid_focused_item_id(
+                            &state.scroll_handle,
+                            state.scroll_handle.current_item_id.clone(),
+                            widget,
+                        )
+                    }
+                    JsOption::Null => None,
+                    JsOption::Value(value) => Some(value.clone()),
+                }
             }
         }
     }

rust/client/src/ui/widget/data_mut.rs

@@ -5,6 +5,7 @@ use std::sync::Arc;
 use gauntlet_common::model::GridSectionWidgetOrderedMembers;
 use gauntlet_common::model::GridWidget;
 use gauntlet_common::model::GridWidgetOrderedMembers;
+use gauntlet_common::model::JsOption;
 use gauntlet_common::model::ListSectionWidgetOrderedMembers;
 use gauntlet_common::model::ListWidget;
 use gauntlet_common::model::ListWidgetOrderedMembers;
@@ -20,6 +21,7 @@ use iced::widget::text_input;
 use itertools::Itertools;
 
 use crate::ui::AppMsg;
+use crate::ui::scroll_handle::ScrollHandle;
 use crate::ui::widget::data::ComponentWidgets;
 use crate::ui::widget::grid::grid_width;
 use crate::ui::widget::state::ComponentWidgetStateContainer;
@@ -172,8 +174,8 @@ impl<'b> ComponentWidgetsMut<'b> {
             RootWidgetMembers::Inline(_) => Task::none(),
             RootWidgetMembers::List(widget) => {
                 let ids = self.list_collect_ids(&widget);
-                let state = self.state.scrollable_root_state_mut(widget.__id__);
-                let (next_item, Some(focus_task)) = state.scroll_handle.list_focus_up(ids) else {
+                let mut scroll_handle = self.list_scroll_handle(widget);
+                let (next_item, Some(focus_task)) = scroll_handle.list_focus_up(ids) else {
                     return Task::none();
                 };
 
@@ -189,8 +191,8 @@ impl<'b> ComponentWidgetsMut<'b> {
             }
             RootWidgetMembers::Grid(widget) => {
                 let ids = self.grid_collect_ids(widget);
-                let state = self.state.scrollable_root_state_mut(widget.__id__);
-                let (next_item, Some(focus_task)) = state.scroll_handle.grid_focus_up(ids) else {
+                let mut scroll_handle = self.grid_scroll_handle(widget);
+                let (next_item, Some(focus_task)) = scroll_handle.grid_focus_up(ids) else {
                     return Task::none();
                 };
 
@@ -221,8 +223,8 @@ impl<'b> ComponentWidgetsMut<'b> {
             RootWidgetMembers::Form(_) => Task::none(),
             RootWidgetMembers::List(widget) => {
                 let ids = self.list_collect_ids(widget);
-                let state = self.state.scrollable_root_state_mut(widget.__id__);
-                let (next_item, Some(focus_task)) = state.scroll_handle.list_focus_down(ids) else {
+                let mut scroll_handle = self.list_scroll_handle(widget);
+                let (next_item, Some(focus_task)) = scroll_handle.list_focus_down(ids) else {
                     return Task::none();
                 };
 
@@ -243,8 +245,8 @@ impl<'b> ComponentWidgetsMut<'b> {
                 };
 
                 let ids = self.grid_collect_ids(widget);
-                let state = self.state.scrollable_root_state_mut(widget.__id__);
-                let (next_item, Some(focus_task)) = state.scroll_handle.grid_focus_down(ids) else {
+                let mut scroll_handle = self.grid_scroll_handle(widget);
+                let (next_item, Some(focus_task)) = scroll_handle.grid_focus_down(ids) else {
                     return Task::none();
                 };
 
@@ -278,8 +280,8 @@ impl<'b> ComponentWidgetsMut<'b> {
             RootWidgetMembers::List(_) => Task::none(),
             RootWidgetMembers::Grid(widget) => {
                 let ids = self.grid_collect_ids(widget);
-                let state = self.state.scrollable_root_state_mut(widget.__id__);
-                let (next_item, Some(focus_task)) = state.scroll_handle.grid_focus_left(ids) else {
+                let mut scroll_handle = self.grid_scroll_handle(widget);
+                let (next_item, Some(focus_task)) = scroll_handle.grid_focus_left(ids) else {
                     return Task::none();
                 };
 
@@ -312,8 +314,8 @@ impl<'b> ComponentWidgetsMut<'b> {
             RootWidgetMembers::List(_) => Task::none(),
             RootWidgetMembers::Grid(widget) => {
                 let ids = self.grid_collect_ids(widget);
-                let state = self.state.scrollable_root_state_mut(widget.__id__);
-                let (next_item, Some(focus_task)) = state.scroll_handle.grid_focus_right(ids) else {
+                let mut scroll_handle = self.grid_scroll_handle(widget);
+                let (next_item, Some(focus_task)) = scroll_handle.grid_focus_right(ids) else {
                     return Task::none();
                 };
 
@@ -443,4 +445,80 @@ impl<'b> ComponentWidgetsMut<'b> {
 
         result
     }
+
+    pub fn list_id_for_id(&self, widget: &ListWidget, target_item_id: &String) -> Option<container::Id> {
+        for members in &widget.content.ordered_members {
+            match &members {
+                ListWidgetOrderedMembers::ListItem(item) => {
+                    let state = self.state.scrollable_item_state(item.__id__);
+                    if &item.id == target_item_id {
+                        return Some(state.id.clone());
+                    }
+                }
+                ListWidgetOrderedMembers::ListSection(section) => {
+                    for members in &section.content.ordered_members {
+                        match &members {
+                            ListSectionWidgetOrderedMembers::ListItem(item) => {
+                                let state = self.state.scrollable_item_state(item.__id__);
+                                if &item.id == target_item_id {
+                                    return Some(state.id.clone());
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+
+        None
+    }
+
+    pub fn grid_id_for_id(&self, widget: &GridWidget, target_item_id: &String) -> Option<container::Id> {
+        for members in &widget.content.ordered_members {
+            match &members {
+                GridWidgetOrderedMembers::GridItem(item) => {
+                    let state = self.state.scrollable_item_state(item.__id__);
+                    if &item.id == target_item_id {
+                        return Some(state.id.clone());
+                    }
+                }
+                GridWidgetOrderedMembers::GridSection(section) => {
+                    for members in &section.content.ordered_members {
+                        match &members {
+                            GridSectionWidgetOrderedMembers::GridItem(item) => {
+                                let state = self.state.scrollable_item_state(item.__id__);
+                                if &item.id == target_item_id {
+                                    return Some(state.id.clone());
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+
+        None
+    }
+
+    fn grid_scroll_handle(&self, widget: &GridWidget) -> ScrollHandle {
+        let state = self.state.scrollable_root_state(widget.__id__);
+        match &widget.focused_item_id {
+            JsOption::Undefined => state.scroll_handle.clone(),
+            JsOption::Null => ScrollHandle::from(&state.scroll_handle, None),
+            JsOption::Value(focused_item_id) => {
+                ScrollHandle::from(&state.scroll_handle, self.grid_id_for_id(widget, focused_item_id))
+            }
+        }
+    }
+
+    fn list_scroll_handle(&self, widget: &ListWidget) -> ScrollHandle {
+        let state = self.state.scrollable_root_state(widget.__id__);
+        match &widget.focused_item_id {
+            JsOption::Undefined => state.scroll_handle.clone(),
+            JsOption::Null => ScrollHandle::from(&state.scroll_handle, None),
+            JsOption::Value(focused_item_id) => {
+                ScrollHandle::from(&state.scroll_handle, self.list_id_for_id(widget, focused_item_id))
+            }
+        }
+    }
 }