Caseflow: Document Viewer | Categories: associate document to category

[abbyraskinUSDS]

Story
When reviewing a document, I want to select a category so I can filter by similar documents when writing a decision.

Dev Notes

• Includes persisting category selection to server

Acceptance Criteria

• Validate that there are 3 category checkboxes with label icons and the words associated with each color under Receipt Date
  

  • Procedural SVG Hex #4A90E2
  • Medical SVG Hex #FF6868
  • Other evidence SVG Hex #5BD998

• The checkbox styling should reflect the one we have on style guide https://dsva-appeals-certification-dev-1895622301.us-gov-west-1.elb.amazonaws.com/styleguide

• Validate that when clicking on a category checkbox, the color icon associated with the checkbox displays to the left of the Document Type in the top toolbar of the PDF viewer
• Validate by deselecting a checkbox, the label icon is removed from the top toolbar of the document
• Validate that a user can add multiple categories to each document
• Validate that when I navigate to the Documents List page, the category I just associated with a document displays in the Categories column in that document's row
• Validate that on the document toolbar at the top, the category icons go in the order of procedural (blue), medical (pink), and others (green).
• Validate that they are always located on the right of the document name and always start there
• Validate that after you set and unset categories for a document, this state persists after you refresh the page.

Mockup

For the order of category labels

Invision Prototype

[gnakm]

@abbyraskin Please audit + add love !

[abbyraskinUSDS]

note: we need svgs for category icons

[NickHeiner]

note: we need svgs for category icons

We have those SVGs.

Does this include the filtering by category functionality in the PDF List view?

[NickHeiner]

@abbyraskin @gnakm what do you think about this? Do we want the category icons to always appear in the same columns? (eg green is always on the far right, even if there are no other categories.) I can explain in person if this is not making sense.

[abbyraskinUSDS]

Does this include the filtering by category functionality in the PDF List view?

@NickHeiner this ticket is only intended to cover adding categories to a PDF - category filtering functionality is documented in #1432

Do we want the category icons to always appear in the same columns? (eg green is always on the far right, even if there are no other categories.)

Goooood question. I think we'd want each color to have a predefined "position" (e.g., green on the far right) so it's a little easier on the eyes when scanning through a long list. What do you think @gnakm? As to what those specific positions should be for each color, I have zero opinions.

[abbyraskinUSDS]

Hmm, caveat to suggestion above: I think they will generally only use one category (note: this is an assumption to test in the pilot!), so having them default to one position (e.g., far left) might make more sense. I defer to Gina's wisdom on this one.

[gnakm]

@abbyraskin @NickHeiner

Fun question. I like keeping it in the order so, procedural(blue), med(pink), others(green) but always starting from the far left as Abigail mentioned. They don't have the be in the same column but in the same order. The screenshot that Nick posted 3 comments above reflects that! I don't think this will really effects the UX for users. This is actually more beneficial to us but that's just my guess.

The color order would be the same for the document toolbar but the difference would be that it will always start on the left of the document name.

I will add these changes to the AC across issues now.

[NickHeiner]

:+1: sounds good. I already had it in a consistent order, so I'll keep it that way, but I won't worry about making the columns be the same for now.

[NickHeiner]

Does this ticket include persisting the category selection for a document to the server?

[abbyraskinUSDS]

@NickHeiner in my mind, yes. but if you think it should be broken out separately let me know...

[NickHeiner]

Nope, that's fine, just wanted to clarify.

[abbyraskinUSDS]

@NickHeiner I added a dev note at the top (feel free to reword/edit if needed)

[NickHeiner]

👍 sounds good.

Is there a UI spec for what happens if the persisting to the server fails? Or an indicator that the save completed successfully?

[NickHeiner]

I think they will generally only use one category

@abbyraskin it would make things simpler if each doc could only have a single category. What if we said for now, that's a constraint, and we can open it up to having multiple categories if that need arises?

[abbyraskinUSDS]

Is there a UI spec for what happens if the persisting to the server fails? Or an indicator that the save completed successfully?

re: error state...paging @gnakm!

we should probably have as subtle a handling here as possible, perhaps some sort of inline message/call to retry rather than one of the larger alert messages?

@NickHeiner as far as providing users with feedback it succeeded...is it possible to only show the bookmark in the toolbar (next to the document type) only if/after saving it to the db succeeds? or would that heavily delay things? i don't think we need a separate "success" otherwise, but should definitely consider error scenarios.

[abbyraskinUSDS]

@NickHeiner just to make sure...we're specifically talking about the call that is made when the category checkbox is selected in the PDF viewer?

[abbyraskinUSDS]

Also, we'll need to consider handling for comments and issue tags as well

[NickHeiner]

we're specifically talking about the call that is made when the category checkbox is selected in the PDF viewer?

Yes.

Wondering if it's enough feedback to just not have the checkboxes select until it sends, or if that could be frustrating...

is it possible to only show the bookmark in the toolbar (next to the document type) only if/after saving it to the db succeeds? or would that heavily delay things?

I would recommend against this. I think you're right that it'll make the UI feel sluggish. The typical best practice is to optimistically update the UI, assuming that the backend call will work.

We could not show anything for success, and just have that be the assumed state. Or we could have a little spinner / checkmark that says something like "saving changes ... all changes saved" that applies to any changes. (This is what Google Docs does.)

[gnakm]

I don't think we need to show anything for successes. We tested with users without them and it was the assumed state. For the Categories, success is assumed when user sees the icons change in the toolbar, for issue tags, the issues in a box and for saved comments, a new comment box added to the list.

I do see that we may need something for latency. :cringe:

As for straight up errors, what about having what Abby and I call, Error Lites pop above each section.

Ex. If checkbox doesn't work,

[gnakm]

@NickHeiner I thought about your Google doc "saving..." idea. We currently have loading buttons on the style guide. For Categories and Issues, I wonder if we could have it not in a box and just text with spinner and for the Save button in comment, we can have the button version.

/cc: @abbyraskin

[NickHeiner]

I agree with your idea that success is the assumed state. How about we say:

1. User changes the checkbox.
2. Client fires a request to save to the server.
3. Client immediately updates the UI to make it look like the UI succeeded.
4. If the request succeeds: nothing happens
5. If the request fails: the checkbox goes back to its original state, and the Error Lite appears.

[gnakm]

I moved the Error Lite issue here #1573

[ghost]

PASSED
checked on preprod
values persist upon reload

[ghost]

added a related bug issue: #1613