From 67bf40d331c9254ebe5a62a358b1bac055da273d Mon Sep 17 00:00:00 2001 From: marufsharifi Date: Thu, 22 Oct 2026 15:01:22 +0430 Subject: [PATCH 1/2] Add UI-6 review rule: pin the pre-selected item in searchable lists --- .claude/skills/app-coding-standards/SKILL.md | 3 +- .../rules/ui-6-pin-initial-selection.md | 55 +++++++++++++++++++ contributingGuides/SELECTION_LIST.md | 11 ++++ 3 files changed, 68 insertions(+), 1 deletion(-) create mode 100644 .claude/skills/app-coding-standards/rules/ui-6-pin-initial-selection.md diff --git a/.claude/skills/app-coding-standards/SKILL.md b/.claude/skills/app-coding-standards/SKILL.md index c87d2d2d8714..e914edf6f452 100644 --- a/.claude/skills/app-coding-standards/SKILL.md +++ b/.claude/skills/app-coding-standards/SKILL.md @@ -15,7 +15,7 @@ Coding standards for the Expensify App. Each standard is a standalone file in `r | Performance | `PERF-*` | Render optimization, memo patterns, useEffect hygiene, data selection | | Consistency | `CONSISTENCY-*` | Platform checks, magic values, unused props, ESLint discipline, localization, file naming, JSDoc | | Clean React Patterns | `CLEAN-REACT-PATTERNS-*` | Composition, component ownership, state structure, prop typing, function components | -| UI | `UI-*` | Loading indicators, scrollable pages, styling conventions | +| UI | `UI-*` | Loading indicators, scrollable pages, styling conventions, selection-list ordering | ## Quick Reference @@ -80,6 +80,7 @@ Coding standards for the Expensify App. Each standard is a standalone file in `r - [UI-3](rules/ui-3-no-inline-styles.md) — Do not use inline style objects - [UI-4](rules/ui-4-layout-spacing-tokens.md) — Type and responsive insets come from tokens - [UI-5](rules/ui-5-reuse-existing-styles.md) — Reuse an existing style or StyleUtils helper instead of adding a new one +- [UI-6](rules/ui-6-pin-initial-selection.md) — Searchable selection lists show the pre-selected item at the top ## Usage diff --git a/.claude/skills/app-coding-standards/rules/ui-6-pin-initial-selection.md b/.claude/skills/app-coding-standards/rules/ui-6-pin-initial-selection.md new file mode 100644 index 000000000000..6597d1fc6200 --- /dev/null +++ b/.claude/skills/app-coding-standards/rules/ui-6-pin-initial-selection.md @@ -0,0 +1,55 @@ +--- +ruleId: UI-6 +title: Searchable selection lists show the pre-selected item at the top +--- + +## [UI-6] Searchable selection lists show the pre-selected item at the top + +### Reasoning + +A searchable picker focuses its search input on open, so on mobile the keyboard covers most of the list. If the saved choice stays in its natural (alphabetical) position, it is often hidden below the fold, and people search for something that is already selected. Snapshot the selection when the list opens and move it to the top of the full list before filtering, so it stays visible and a later tap on it does not reorder the list for a frame. + +### Incorrect + +```tsx +// The selected row stays wherever it falls alphabetically; on a long list it is hidden under the keyboard. + +``` + +### Correct + +```tsx +// Freeze the selection on open so later taps don't reorder the list, then pin it to the top before filtering. +const initialSelectedValue = useInitialValue(() => selectedValue); +const orderedOptions = moveInitialSelectionToTop(options, initialSelectedValue ? [initialSelectedValue] : []); +const data = filterBySearch(orderedOptions, searchValue); +``` + +`moveInitialSelectionToTop` no-ops for lists below `CONST.STANDARD_LIST_ITEM_LIMIT`, so short lists keep their natural order. Pages built on `SelectionScreen` get this for free from `useSelectionListSearch`, which pins the frozen selection and exposes `pinnedValues`. + +--- + +### Review Metadata + +Flag ONLY when ALL of these are true: + +- The changed code adds or changes a `SelectionList` / `SelectionScreen` that shows a search input (`textInputOptions` or `shouldShowTextInput`) +- An item can be pre-selected when the list opens (`isSelected`, `initiallyFocusedItemKey`, or `initiallyFocusedOptionKey` comes from a saved value) +- The list is not ordered with `moveInitialSelectionToTop`, `useSelectionListSearch`, a leading selected section, or an equivalent selected-first sort + +**DO NOT flag if:** + +- The list always has fewer than `CONST.STANDARD_LIST_ITEM_LIMIT` (12) items +- Nothing is pre-selected on open (for example, the focus key only sets keyboard focus in a create flow) +- The saved value seeds the search text instead of marking a row (for example, a search-as-you-type picker) +- The list has a fixed natural order that design asked to keep (for example, months) +- The code is a test, story, or debug-only page + +**Search Patterns** (hints for reviewers): +- `initiallyFocusedItemKey=` / `initiallyFocusedOptionKey=` next to `textInputOptions=` +- `isSelected:` in a list built for a searchable `SelectionList` +- `tokenizedSearch(` run on a list before any selected-first ordering diff --git a/contributingGuides/SELECTION_LIST.md b/contributingGuides/SELECTION_LIST.md index a994e2584dd9..cbb8d7083afe 100644 --- a/contributingGuides/SELECTION_LIST.md +++ b/contributingGuides/SELECTION_LIST.md @@ -74,6 +74,17 @@ There are two main components: /> ``` +## Pinning the pre-selected item + +A searchable list focuses its search input on open, so on mobile the keyboard covers most of the list. When the list can have a pre-selected item, pin that item to the top so it stays visible instead of hiding in its natural position below the fold. + +- Snapshot the selected value when the list opens (for example with `useInitialValue`) so a later tap does not reorder the list mid-interaction. +- Pin it to the top of the full list **before** filtering with `moveInitialSelectionToTop` (from `@libs/SelectionListOrderUtils`). It no-ops for lists below `CONST.STANDARD_LIST_ITEM_LIMIT`, so short lists keep their natural order. +- Any clear/"None" row belongs directly **below** the pinned selection. +- Pages built on `SelectionScreen` get this automatically from `useSelectionListSearch`, which pins the frozen selection and returns `pinnedValues` for callers that need to know what was pinned. + +This is enforced in review by [UI-6](../.claude/skills/app-coding-standards/rules/ui-6-pin-initial-selection.md). + ## Related Components - `SelectionScreen` - Wrapper component that includes screen layout (1 section) From 63f4787c626eb8cc08ecca7fde9d5ced83c3a30c Mon Sep 17 00:00:00 2001 From: marufsharifi Date: Tue, 10 Nov 2026 16:49:09 +0430 Subject: [PATCH 2/2] Remove UI-6 rule for pre-selected items in searchable selection lists --- .claude/skills/app-coding-standards/SKILL.md | 3 +- .../rules/ui-6-pin-initial-selection.md | 55 ------------------- 2 files changed, 1 insertion(+), 57 deletions(-) delete mode 100644 .claude/skills/app-coding-standards/rules/ui-6-pin-initial-selection.md diff --git a/.claude/skills/app-coding-standards/SKILL.md b/.claude/skills/app-coding-standards/SKILL.md index d563662b0dce..986c857bb925 100644 --- a/.claude/skills/app-coding-standards/SKILL.md +++ b/.claude/skills/app-coding-standards/SKILL.md @@ -20,7 +20,7 @@ Before committing, stage everything with `git add -A`. Then start a general-purp | Performance | `PERF-*` | Render optimization, memo patterns, useEffect hygiene, data selection | | Consistency | `CONSISTENCY-*` | Platform checks, magic values, unused props, lint discipline, localization, file naming, JSDoc | | Clean React Patterns | `CLEAN-REACT-PATTERNS-*` | Composition, component ownership, state structure, prop typing, function components | -| UI | `UI-*` | Loading indicators, scrollable pages, styling conventions, selection-list ordering | +| UI | `UI-*` | Loading indicators, scrollable pages, styling conventions | ## Quick Reference @@ -86,7 +86,6 @@ Before committing, stage everything with `git add -A`. Then start a general-purp - [UI-3](rules/ui-3-no-inline-styles.md) — Do not use inline style objects - [UI-4](rules/ui-4-layout-spacing-tokens.md) — Type and responsive insets come from tokens - [UI-5](rules/ui-5-reuse-existing-styles.md) — Reuse an existing style or StyleUtils helper instead of adding a new one -- [UI-6](rules/ui-6-pin-initial-selection.md) — Searchable selection lists show the pre-selected item at the top ### Onyx - [ONYX-1](rules/onyx-1-no-render-reachable-onyx-read.md) — Keep Onyx reads off the render path and out of a written tick diff --git a/.claude/skills/app-coding-standards/rules/ui-6-pin-initial-selection.md b/.claude/skills/app-coding-standards/rules/ui-6-pin-initial-selection.md deleted file mode 100644 index 6597d1fc6200..000000000000 --- a/.claude/skills/app-coding-standards/rules/ui-6-pin-initial-selection.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -ruleId: UI-6 -title: Searchable selection lists show the pre-selected item at the top ---- - -## [UI-6] Searchable selection lists show the pre-selected item at the top - -### Reasoning - -A searchable picker focuses its search input on open, so on mobile the keyboard covers most of the list. If the saved choice stays in its natural (alphabetical) position, it is often hidden below the fold, and people search for something that is already selected. Snapshot the selection when the list opens and move it to the top of the full list before filtering, so it stays visible and a later tap on it does not reorder the list for a frame. - -### Incorrect - -```tsx -// The selected row stays wherever it falls alphabetically; on a long list it is hidden under the keyboard. - -``` - -### Correct - -```tsx -// Freeze the selection on open so later taps don't reorder the list, then pin it to the top before filtering. -const initialSelectedValue = useInitialValue(() => selectedValue); -const orderedOptions = moveInitialSelectionToTop(options, initialSelectedValue ? [initialSelectedValue] : []); -const data = filterBySearch(orderedOptions, searchValue); -``` - -`moveInitialSelectionToTop` no-ops for lists below `CONST.STANDARD_LIST_ITEM_LIMIT`, so short lists keep their natural order. Pages built on `SelectionScreen` get this for free from `useSelectionListSearch`, which pins the frozen selection and exposes `pinnedValues`. - ---- - -### Review Metadata - -Flag ONLY when ALL of these are true: - -- The changed code adds or changes a `SelectionList` / `SelectionScreen` that shows a search input (`textInputOptions` or `shouldShowTextInput`) -- An item can be pre-selected when the list opens (`isSelected`, `initiallyFocusedItemKey`, or `initiallyFocusedOptionKey` comes from a saved value) -- The list is not ordered with `moveInitialSelectionToTop`, `useSelectionListSearch`, a leading selected section, or an equivalent selected-first sort - -**DO NOT flag if:** - -- The list always has fewer than `CONST.STANDARD_LIST_ITEM_LIMIT` (12) items -- Nothing is pre-selected on open (for example, the focus key only sets keyboard focus in a create flow) -- The saved value seeds the search text instead of marking a row (for example, a search-as-you-type picker) -- The list has a fixed natural order that design asked to keep (for example, months) -- The code is a test, story, or debug-only page - -**Search Patterns** (hints for reviewers): -- `initiallyFocusedItemKey=` / `initiallyFocusedOptionKey=` next to `textInputOptions=` -- `isSelected:` in a list built for a searchable `SelectionList` -- `tokenizedSearch(` run on a list before any selected-first ordering