Show the category description hint on the expense creation description field (re-land)

[MelvinBot]

Explanation of Change

This re-lands the category description hint on the inline Description field of the new manual expense flow. The first attempt, Show the category description hint on the expense creation description field, was reverted because of three regressions. This PR fixes all three.

• Show the hint on creation. useConfirmationListData now computes descriptionHint next to isDescriptionRequired and passes it in requiredFlags. Every footer variant (manual, per diem, time, and the three distance footers) hands it to DescriptionField, which passes it to the TextInput as hint.
• No hint in Self DM. The hint only shows when the expense goes to a workspace chat or an invoice. This is the same check that decides whether categories are shown. In Self DM, policy falls back to your default workspace, which is why the hint appeared there before.
• No hint when Rules are off. The hint is gated on arePolicyRulesEnabled, the same as "Required". A duplicated workspace without Rules keeps its commentHint but has areRulesEnabled: false. The standalone description step (DynamicIOURequestStepDescription) gets the same gate, which also fixes this case on that screen.
• Mention hints render. FormHelpMessage no longer runs HTML messages through Parser.replace again. Parsing saved hint HTML a second time wrapped <mention-user> in an empty outer mention that rendered blank. This matches what MenuItem already does with Parser.isHTML.

The lookup is a new pure helper, getCategoryDescriptionHint in CategoryUtils, which both screens use.

Unit tests cover the helper (hint present, Rules off, no hint, no category), plus FormHelpMessage with an HTML mention hint and a markdown message.

AI checks run locally: typecheck, lint-changed, spell-changed, oxfmt, React Compiler compliance on changed files, and the related Jest suites (9 suites, 110 tests). All passed.

⚠️ The automated web test couldn't run. The browser session rendered a blank page before any steps, so the flow still needs a manual check.

Fixed Issues

$ #100527
PROPOSAL: #100527 (comment)

Tests

Precondition:

• Rules are enabled in the workspace

1. Go to Workspace > Categories > Advertising
2. Add a Description hint > Save
3. Go to Required fields > Enable Require description
4. Start the manual expense creation flow > Enter an amount
5. Choose Advertising as the category
6. Verify the description hint is displayed in the Description field after choosing the category

• Verify that no errors appear in the JS console

Offline tests

QA Steps

// TODO: The human co-author must fill out the QA tests you ran before marking this PR as "ready for review".
// Please describe what QA needs to do to validate your changes and what areas do they need to test for regressions.

• Verify that no errors appear in the JS console

PR Author Checklist

• I linked the correct issue in the ### Fixed Issues section above
• I wrote clear testing steps that cover the changes made in this PR
  • I added steps for local testing in the Tests section
  • I added steps for the expected offline behavior in the Offline steps section
  • I added steps for Staging and/or Production testing in the QA steps section
  • I added steps to cover failure scenarios (i.e. verify an input displays the correct error message if the entered data is not correct)
  • I turned off my network connection and tested it while offline to ensure it matches the expected behavior (i.e. verify the default avatar icon is displayed if app is offline)
  • I tested this PR with a High Traffic account against the staging or production API to ensure there are no regressions (e.g. long loading states that impact usability).
• I included screenshots or videos for tests on all platforms
• I ran the tests on all platforms & verified they passed on:
  • Android: Native
  • Android: mWeb Chrome
  • iOS: Native
  • iOS: mWeb Safari
  • MacOS: Chrome / Safari
• I verified there are no console errors (if there's a console error not related to the PR, report it or open an issue for it to be fixed)
• I followed proper code patterns (see Reviewing the code)
  • I verified that comments were added to code that is not self explanatory
  • I verified that any new or modified comments were clear, correct English, and explained "why" the code was doing something instead of only explaining "what" the code was doing.
  • I verified any copy / text that was added to the app is grammatically correct in English. It adheres to proper capitalization guidelines (note: only the first word of header/labels should be capitalized), and is either coming verbatim from figma or has been approved by marketing (in order to get marketing approval, ask the Bug Zero team member to add the Waiting for copy label to the issue)
• If a new code pattern is added I verified it was agreed to be used by multiple Expensify engineers
• I followed the guidelines as stated in the Review Guidelines
• I tested other components that can be impacted by my changes (i.e. if the PR modifies a shared library or component like Avatar, I verified the components using Avatar are working as expected)
• If a new CSS style is added I verified that:
  • A similar style doesn't already exist
  • The style can't be created with an existing StyleUtils function (i.e. StyleUtils.getBackgroundAndBorderStyle(theme.componentBG))
• If new assets were added or existing ones were modified, I verified that:
  • The assets are optimized and compressed (for SVG files, run npm run compress-svg)
  • The assets load correctly across all supported platforms.
• If the PR modifies code that runs when editing or sending messages, I tested and verified there is no unexpected behavior for all supported markdown - URLs, single line code, code blocks, quotes, headings, bold, strikethrough, and italic.
• If the PR modifies a generic component, I tested and verified that those changes do not break usages of that component in the rest of the App (i.e. if a shared library or component like Avatar is modified, I verified that Avatar is working as expected)
• If the PR modifies a component related to any of the existing Storybook stories, I tested and verified all stories for that component are still working as expected.
• If the PR modifies a component or page that can be accessed by a direct deeplink, I verified that the code functions as expected when the deeplink is used - from a logged in and logged out account.
• If the PR modifies the UI (e.g. new buttons, new UI components, changing the padding/spacing/sizing, moving components, etc) or modifies the form input styles:
  • I verified that all the inputs inside a form are aligned with each other.
  • I added Design label and/or tagged @Expensify/design so the design team can review the changes.
• If the PR adds or modifies the UI:
  • I asked an AI agent to review the changes for accessibility issues and addressed its findings.
  • I tested with a screen reader (VoiceOver on macOS) and verified all new/changed elements are reachable with a logical focus order.
  • I verified all new/changed elements have meaningful accessible names and roles.
  • I verified state changes are announced (e.g. checked/unchecked, expanded/collapsed, selected).
• I added unit tests for any new feature or bug fix in this PR to help automatically prevent regressions in this user flow.
• If the main branch was merged into this PR after a review, I tested again and verified the outcome was still expected according to the Test steps.

Screenshots/Videos

Android: Native

Android: mWeb Chrome

iOS: Native

iOS: mWeb Safari

MacOS: Chrome / Safari

[melvin-bot]

Hey! I see that you made changes to our Form component. Make sure to update the docs in FORMS.md accordingly. Cheers!

[MelvinBot]

🤖 Web test steps verification results: ⚠️ partial

On dev NewDot web, the category description hint (including mentions) shows below the inline Description field on the workspace expense confirmation screen. It does not show for Self DM expenses or when Rules is off. The PR's Tests section is still a TODO, so I used the linked issue's steps plus the three regression cases in the PR description. I couldn't read the JS console on web, so that step is unconfirmed.

Step	Status
Add a Description hint to the Advertising category and save Set the hint to "Include the campaign name" and saved. The category panel shows the saved hint.	✅
Enable Require description on the Advertising category Created a category rule that requires Description. The category panel lists "Require description" under Category rules.	✅
Workspace chat manual expense with Advertising shows the hint inline Started a $25 manual expense in the workspace chat and chose Advertising. "Include the campaign name" appears right below the Description field.	✅
Self DM manual expense with Advertising shows no hint Changed the recipient to "Your space", entered $15, and chose Advertising. No hint appears below the Description field.	✅
With Rules off, the hint does not show Turned off Rules in More features. Started a $30 workspace expense with Advertising. No hint appears inline, including after focusing the field. The standalone Description step wasn't reachable in this flow.	✅
With Rules back on, a hint containing a user mention renders Turned Rules back on and added a user mention to the hint. The mention renders as a highlighted chip on the category panel and below the Description field, not blank. The hint text reads "Include the campaign nameAsk @mention for the campaign code" because the tester could only append to the field.	✅
No JS console errors during the flow The web test harness can't read the console, so I couldn't check this step directly. All captured network requests returned 200, and no error banners or crash screens appeared.	⚠️

---

view run · view recording

[MelvinBot]

🤖 Android test steps verification results: ⚠️ partial

On Android, the category description hint shows below the inline Description field when you pick a category with a hint in a workspace chat expense (steps 1–3). Steps 4–6 didn't run. An "Import your contacts" sheet got stuck while I was switching the recipient to Self DM, and reloading the app signed the test account out. The PR's Tests section is still a TODO, so I used the same steps as the web run.

Step	Status
Add a Description hint to the Advertising category and save Set the hint to "Include the campaign name". The category screen shows the saved hint.	✅
Enable Require description on the Advertising category Created a category rule that requires Description. The category page lists "Require description" under Category rules.	✅
Workspace chat manual expense with Advertising shows the hint inline Started a $25 manual expense in the workspace chat and chose Advertising. "Include the campaign name" appears right below the Description field.	✅
Self DM manual expense with Advertising shows no hint Not tested. While I was switching the recipient to Self DM, an "Import your contacts" sheet opened. It wouldn't close with taps, in-app back, or system back. This sheet is outside the PR's changes.	⚠️
With Rules off, the hint does not show Not tested. I reloaded the app to clear the stuck sheet, and the reload signed the test account out.	⚠️
With Rules back on, a hint containing a user mention renders Not tested. The test account was signed out.	⚠️
No JS errors or crashes during the flow No crash or red box appeared. Metro logged one dev warning when back was pressed on the stuck sheet: "The action 'DISMISS_MODAL' was not handled by any navigator". The warning relates to the contacts sheet, not the description hint.	⚠️

---

view run · view recording

[Ollyws]

@MelvinBot add these tests:

Precondition:

   - Enabled rules in Workspace

Steps:

    1. Go to Workspace > Categories > Advertising
    2. Add a Description Hint > Save
    3. Go to Required fields > Enable Require description
    4. 4 Start manual Expense creation flow > Enter Amount
    5. Choose Advertising as Category
    6. Verify description hint is displayed in the description field after choosing the Category

[MelvinBot]

🤖 I added your steps to the PR's Tests section, in place of the TODO. I kept the precondition (Rules enabled) and the JS console check. I also fixed the duplicated "4" in step 4.

The QA Steps section is still a TODO. Reply with @MelvinBot if you want the same steps there, or if you want me to run them on web.

[Ollyws]

@MelvinBot mark as ready to review

[MelvinBot]

I couldn't mark this PR as ready for review. My environment blocked the gh pr ready command in this run.

Please click Ready for review at the bottom of the PR page. You can also try asking me again later.

---

view run

[Ollyws]

@MelvinBot yes you can. Mark it for review.

[MelvinBot]

I still can't mark this PR as ready for review. My environment blocked the gh pr ready command again in this run. This is a permission setting in my runtime, not a GitHub access problem, so asking again won't change the result.

Please click Ready for review at the bottom of the PR page.

---

view run

[melvin-bot]

@Ollyws Please copy/paste the Reviewer Checklist from here into a new comment on this PR and complete it. If you have the K2 extension, you can simply click: [this button]

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-06T16:46:08.901292Z	cf3dfd9	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[garrettmknight]

Looks good from a product perspective. Nice improvement.

[Ollyws]

Reviewer Checklist

• I have verified the author checklist is complete (all boxes are checked off).
• I verified the correct issue is linked in the ### Fixed Issues section above
• I verified testing steps are clear and they cover the changes made in this PR
  • I verified the steps for local testing are in the Tests section
  • I verified the steps for Staging and/or Production testing are in the QA steps section
  • I verified the steps cover any possible failure scenarios (i.e. verify an input displays the correct error message if the entered data is not correct)
  • I turned off my network connection and tested it while offline to ensure it matches the expected behavior (i.e. verify the default avatar icon is displayed if app is offline)
• I checked that screenshots or videos are included for tests on all platforms
• I included screenshots or videos for tests on all platforms
• I verified that the composer does not automatically focus or open the keyboard on mobile unless explicitly intended. This includes checking that returning the app from the background does not unexpectedly open the keyboard.
• I verified tests pass on all platforms & I tested again on:
  • Android: HybridApp
  • Android: mWeb Chrome
  • iOS: HybridApp
  • iOS: mWeb Safari
  • MacOS: Chrome / Safari
• If there are any errors in the console that are unrelated to this PR, I either fixed them (preferred) or linked to where I reported them in Slack
• I verified proper code patterns were followed (see Reviewing the code)
  • I verified that comments were added to code that is not self explanatory
  • I verified that any new or modified comments were clear, correct English, and explained "why" the code was doing something instead of only explaining "what" the code was doing.
  • I verified any copy / text that was added to the app is grammatically correct in English. It adheres to proper capitalization guidelines (note: only the first word of header/labels should be capitalized), and is either coming verbatim from figma or has been approved by marketing (in order to get marketing approval, ask the Bug Zero team member to add the Waiting for copy label to the issue)
• If a new code pattern is added I verified it was agreed to be used by multiple Expensify engineers
• I verified that this PR follows the guidelines as stated in the Review Guidelines
• I verified other components that can be impacted by these changes have been tested, and I retested again (i.e. if the PR modifies a shared library or component like Avatar, I verified the components using Avatar have been tested & I retested again)
• If a new component is created I verified that:
  • A similar component doesn't exist in the codebase
  • All props are defined accurately
  • The component has a clear name that is non-ambiguous and the purpose of the component can be inferred from the name alone
  • The only data being stored in the state is data necessary for rendering and nothing else
  • The component has the minimum amount of code necessary for its purpose, and it is broken down into smaller components in order to separate concerns and functions
• If a new CSS style is added I verified that:
  • A similar style doesn't already exist
  • The style can't be created with an existing StyleUtils function (i.e. StyleUtils.getBackgroundAndBorderStyle(theme.componentBG)
• If the PR modifies code that runs when editing or sending messages, I tested and verified there is no unexpected behavior for all supported markdown - URLs, single line code, code blocks, quotes, headings, bold, strikethrough, and italic.
• If the PR modifies a generic component, I tested and verified that those changes do not break usages of that component in the rest of the App (i.e. if a shared library or component like Avatar is modified, I verified that Avatar is working as expected in all cases)
• If the PR modifies a component related to any of the existing Storybook stories, I tested and verified all stories for that component are still working as expected.
• If the PR modifies a component or page that can be accessed by a direct deeplink, I verified that the code functions as expected when the deeplink is used - from a logged in and logged out account.
• If the PR modifies the UI (e.g. new buttons, new UI components, changing the padding/spacing/sizing, moving components, etc) or modifies the form input styles:
  • I verified that all the inputs inside a form are aligned with each other.
  • I added Design label and/or tagged @Expensify/design so the design team can review the changes.
• If the PR adds or modifies the UI:
  • I asked an AI agent to review the changes for accessibility issues and addressed its findings.
  • I tested with a screen reader (VoiceOver on macOS) and verified all new/changed elements are reachable with a logical focus order.
  • I verified all new/changed elements have meaningful accessible names and roles.
  • I verified state changes are announced (e.g. checked/unchecked, expanded/collapsed, selected).
• For any bug fix or new feature in this PR, I verified that sufficient unit tests are included to prevent regressions in this flow.
• If the main branch was merged into this PR after a review, I tested again and verified the outcome was still expected according to the Test steps.
• I have checked off every checkbox in the PR reviewer checklist, including those that don't apply to this PR.

Screenshots/Videos

Android: HybridApp

Android: mWeb Chrome

iOS: HybridApp

iOS: mWeb Safari

MacOS: Chrome / Safari

[Ollyws]

LGTM

[mountiny]

@Ollyws sorry, can you please resolve the conflict?

[Ollyws]

@MelvinBot resolve conflicts.

[melvin-bot]

@Ollyws Please copy/paste the Reviewer Checklist from here into a new comment on this PR and complete it. If you have the K2 extension, you can simply click: [this button]

[MelvinBot]

I merged main into this branch and resolved the conflicts. The PR is mergeable again.

There was one conflict, in useConfirmationListData.ts. main moved requiredFlags out of the return object and into a local variable. I kept main's structure and added descriptionHint to that local requiredFlags. Every footer variant and details-field component still passes the hint to DescriptionField.

I couldn't run typecheck or lint locally, so please check CI on the merge commit.

[MelvinBot]

The failing test (job 3) check is unrelated to this PR, so I didn't push a fix. Check independent approval needs a reviewer's approval, so it isn't a code failure.

Failure: tests/ui/WorkspaceCategoriesTest.tsx › "should delete categories through UI interactions" fails with Found multiple elements with accessibility label: Select all. That label comes from the select-all checkbox in the shared Table header (src/components/Table/TableHeader.tsx:161-189).

Why it's unrelated

• This PR doesn't change the Table component or the workspace categories page. Its CategoryUtils change only adds a new getCategoryDescriptionHint helper.
• The same test passed on this branch at cf3dfd9. It started failing only after the merge commit 8d398a2 brought in main as of today (ff03a5d).
• main has had several Table changes in that window. One of them is Show scroll bars on workspace table pages, merged today, which changes how the column header renders. I haven't confirmed which main change causes the duplicate checkbox.

Next step: Rerun the job after main gets a fix for this test, or confirm the failure on another branch that's up to date with main.

[MelvinBot]

The failing test (job 3) check is a flaky test, not something this PR caused, so I didn't push a code change. Please rerun the failed job. I can't rerun it myself. This corrects my earlier comment, which pointed to a recent main change. The test still passes on main with those changes.

Why it flakes: WorkspaceCategoriesTest › "should delete categories through UI interactions" can find two "Select all" checkboxes. One is the table's column header. The other is a sticky copy of that header that FlashList draws a few animation frames later. If the test is slow, Jest's fake timers advance far enough for the sticky copy to appear before line 169. getByLabelText then throws.

Evidence

• The sticky header turns on after FlashList's onLoad and one more frame: src/components/Table/TableBody.tsx:241-248, :484.
• In Jest, neither header copy is hidden from accessibility queries, and both render the "Select all" checkbox: src/components/Table/TableHeader.tsx:184-191.
• Each waitFor retry moves fake time forward 50 ms. This test file took 27.7 s in the failing job, so slow retries can let the sticky copy render.
• A pull-request run (37672873386) tested main with Show scroll bars on workspace table pages and the inline-editing table changes already merged. This test passed there. Nothing between that main commit and the one merged into this branch touches Table, categories, or FlashList.
• This PR only adds getCategoryDescriptionHint to CategoryUtils.ts and an HTML check in FormHelpMessage.tsx. Neither renders on the categories page.

If the job keeps failing, a separate PR could harden the test by using getAllByLabelText(...)[0] at tests/ui/WorkspaceCategoriesTest.tsx:169.

[mountiny]

Thank you

[github-actions]

🚧 mountiny has triggered a test Expensify/App build. You can view the workflow run here.

[OSBotify]

✋ This PR was not deployed to staging yet because QA is ongoing. It will be automatically deployed to staging after the next production release.

[github-actions]

🧪🧪 Use the links below to test this adhoc build on Android, iOS, and Web. Happy testing! 🧪🧪
Built from App PR #102762.

Android 🤖	iOS 🍎
https://ad-hoc-expensify-cash.s3.us-east-1.amazonaws.com/rock-artifacts/ad-hoc/rock-android-Adhoc-d9f2768-b8010af-63fae9e5619642ac74506825a462da306ad58ec4/index.html	https://ad-hoc-expensify-cash.s3.us-east-1.amazonaws.com/rock-artifacts/ad-hoc/rock-ios-device-AdHoc-d9f2768-b8010af-e6ab656984e1fbacb21d083703336c1491d7dfcd/index.html

Web 🕸️
https://102762.pr-testing.expensify.com

---

👀 View the workflow run that generated this build 👀

[OSBotify]

🚀 Deployed to staging by https://github.com/mountiny in version: 9.5.6-0 🚀

platform	result
🕸 web 🕸	success ✅
🤖 android 🤖	success ✅
🍎 iOS 🍎	success ✅

[MelvinBot]

No help site update is needed. Create expense categories and Workspace Rules already say the Description hint appears below Description while you create and edit an expense, and only when Rules is on. This PR makes the app match that.

[OSBotify]

🚀 Deployed to production by https://github.com/puneetlath in version: 9.5.6-6 🚀

platform	result
🕸 web 🕸	success ✅
🤖 android 🤖	success ✅
🍎 iOS 🍎	success ✅

Bundle Size Analysis (Sentry):

• Android
• iOS