ListView docs by reidbarber · Pull Request #2734 · adobe/react-spectrum

reidbarber · 2022-01-07T00:21:08Z

Closes #2730

✅ Pull Request Checklist:

Included link to corresponding React Spectrum GitHub Issue.
Added/updated unit tests and storybook for this change (for new code or code which already has tests).
Filled out test instructions.
Updated documentation (if it already exists for this component).
Looked at the Accessibility Practices for this feature - Aria Practices

📝 Test Instructions:

Open ListView page of docs (react-spectrum/ListView.html). New link is in Collections section of sidenav.

🧢 Your Project:

RSP

adobe-bot · 2022-01-07T00:25:21Z

Build successful! 🎉

adobe-bot · 2022-01-07T00:30:08Z

Build successful! 🎉

adobe-bot · 2022-01-07T17:10:17Z

Build successful! 🎉

adobe-bot · 2022-01-11T00:09:08Z

Build successful! 🎉

LFDanLu

Partial review, will followup tmrw

packages/@react-spectrum/list/docs/ListView.mdx

adobe-bot · 2022-01-12T17:26:51Z

Build successful! 🎉

packages/@react-spectrum/list/src/ListView.tsx

packages/@react-spectrum/list/docs/ListView.mdx

LFDanLu · 2022-06-06T21:34:04Z

packages/@react-spectrum/list/docs/ListView.mdx

+    getDropOperation(target, types) {
+      let typesSet = types.types ? types.types : types;
+      let draggedTypes = [...typesSet.values()];


Note that this has a typescript error since the type for types doesn't actually have types.type. There is a ticket for investigating why types returns a Set or a object with a types property that is a Set and either fixing that or updating the typescript type.

adobe-bot · 2022-06-06T21:36:56Z

Build successful! 🎉

LFDanLu · 2022-06-06T21:43:29Z

packages/@react-spectrum/list/docs/ListView.mdx

+      for (let item of e.items) {
+        for (let acceptedType of acceptedDragTypes) {
+          if (item.kind === 'text' && item.types.has(acceptedType)) {
+            let {id} = JSON.parse(await item.getText(acceptedType));
+            keysToMove.push(id);
+          }
+        }
+      }


Ideally I would've liked to exit the inner loop early upon finding the matching acceptedType but e.items can either be an array of length X, where X is the number of dragged items OR is an array of a single item with a types key that is a Set of size X. The second case happens specifically if dragging multiple items that have different types via mouse.

Still digging into why this is and whether or not it is expected

Looks to be due to

react-spectrum/packages/@react-aria/dnd/src/utils.ts

Lines 111 to 126 in 26990c2

for (let [type, items] of groupedByType) {

if (NATIVE_DRAG_TYPES.has(type)) {

// Only one item of a given type can be set on a data transfer.

// Join all of the items together separated by newlines.

let data = items.join('\n');

dataTransfer.items.add(data, type);

} else {

// Set data to the first item so we have access to the list of types.

dataTransfer.items.add(items[0], type);

}

}

if (needsCustomData) {

let data = JSON.stringify(customData);

dataTransfer.items.add(data, CUSTOM_DRAG_TYPE);

}

When there are multiple items w/ the same type or a item with multiple types present in the drag operation, we enter the custom data path, but if you drag a single folder + single item then we hit this path:

react-spectrum/packages/@react-aria/dnd/src/utils.ts

Lines 117 to 120 in 26990c2

} else {

// Set data to the first item so we have access to the list of types.

dataTransfer.items.add(items[0], type);

}

resulting in a DataTransferItemList of two DataTransferItems

This will then hit the non-custom data path in readFromDataTransfer, eventually cumulating to

react-spectrum/packages/@react-aria/dnd/src/utils.ts

Lines 231 to 238 in 26990c2

// All string items are different representations of the same item. There's no way to have

// multiple string items at once in the current DataTransfer API.

if (stringItems.size > 0) {

items.push({

kind: 'text',

types: new Set(stringItems.keys()),

getText: (type) => Promise.resolve(stringItems.get(type))

});

which will transform a stringItems list of

stringItems Map(2) {'file' => 'Adobe Photoshop', 'folder' => 'Documents'}

to a single item representation of

This feels like it is intentional due to limitations in the current DataTransferAPI, but the comment "All string items are different representations of the same item" sounds incorrect here? Not entirely sure what that means tbh, need to dig more into the DataTransferApi

All in all, it feels hard to tell between a drag + drop operation of a single file + folder and a drag + drop operation of a single item that has multiple types tied to it

…docs

adobe-bot · 2022-06-07T17:54:18Z

Build successful! 🎉

snowystinger · 2022-06-07T20:36:23Z

I think one concern I have is, what is the difference between ListBox and ListView, how do I (a user) know which one I should be using?

snowystinger · 2022-06-07T20:41:11Z

packages/@react-spectrum/list/docs/ListView.mdx

+<details>
+  <summary style={{fontWeight: 'bold'}}><ChevronRight size="S" /> Show code</summary>
+
+```tsx example export=true render=false


this example is a bit strange, you can empty the list, but once you do, you can't drag anything into it because root drop is not allowed. Until that point you can drag back and forth all you like.

reidbarber

Some super-nit suggestions (probably some are my typos tbh)

packages/@react-spectrum/list/docs/ListView.mdx

devongovett · 2022-06-08T00:48:27Z

packages/@react-spectrum/list/docs/ListView.mdx

+By default, ListView uses the checkbox selection style, which includes a checkbox in each row for selection. When the `selectionStyle` prop is set to `"highlight"`, the checkboxes are hidden,
+and the selected rows are displayed with a highlighted background instead.
+
+In addition to changing the appearance, the selection behavior also changes depending on the `selectionStyle` prop. In the default checkbox selection style, clicking, tapping,
+or pressing the <Keyboard>Space</Keyboard> or <Keyboard>Enter</Keyboard> keys toggles selection for the focused row. Using the arrow keys moves focus but does not change selection.
+
+In the highlight selection style, however, clicking a row with the mouse _replaces_ the selection with only that row. Using the arrow keys moves both focus and selection.
+To select multiple rows, modifier keys such as <Keyboard>Ctrl</Keyboard>, <Keyboard>Cmd</Keyboard>, and <Keyboard>Shift</Keyboard> can be used.  To move focus without moving
+selection, the <Keyboard>Ctrl</Keyboard> key on Windows or the <Keyboard>Option</Keyboard> key on macOS can be held while pressing the arrow keys. Holding this modifier while pressing
+the <Keyboard>Space</Keyboard> key toggles selection for the focused row, which allows multiple selection of non-contiguous items. On touch screen devices, selection always behaves as toggle
+since modifier keys may not be available. This behavior emulates native platforms such as macOS and Windows.


I think we can simplify with something like this:

By default, ListView uses the checkbox selection style, which includes a checkbox in each row for selection. When the selectionStyle prop is set to "highlight", the checkboxes are hidden, and the selected rows are displayed with a highlighted background instead.

In addition to changing the appearance, the selection behavior also changes depending on the selectionStyle prop. In the default checkbox selection style, clicking, tapping, or pressing the Space or Enter keys toggles selection for the focused row. Using the arrow keys moves focus but does not change selection.

In the highlight selection style, however, clicking a row with the mouse replaces the selection with only that row. Using the arrow keys moves both focus and selection. To select multiple rows, modifier keys such as Ctrl, Cmd, and Shift can be used. On touch screen devices, selection always behaves as toggle since modifier keys may not be available.

These selection styles implement the behaviors defined in Aria Practices.

Mostly the same except the last paragraph, which includes a bit fewer nitty gritty details that are defined in the Aria practices link.

devongovett · 2022-06-08T00:50:13Z

packages/@react-spectrum/list/docs/ListView.mdx

+On touch devices, `onAction` is always the primary tap interaction, and tapping on the row's checkbox or long pressing the row will select the row. In highlight selection, a long press will also shift the ListView into selection mode,
+which displays checkboxes to perform selection. While the ListView is in this state, tapping the row will toggle selection instead of triggering `onAction`. Deselecting all items exits selection mode and hides the checkboxes.
+Double clicking matches the behavior of desktop platforms like macOS and Windows, and a separate selection mode matches mobile platforms like iOS and Android.
+


I think I would suggest to flip this around a bit to describe the different modes rather than by interaction method:

ListView supports row actions via the onAction prop, which is useful for functionality such as navigation. When nothing is selected, the ListView performs actions by default when clicking or tapping a row. Items may be selected using the checkbox, or by long pressing on touch devices. When at least one item is selected, the ListView is in selection mode, and clicking or tapping a row toggles the selection. Actions may also be triggered via the Enter key, and selection using the Space key.

This behavior is slightly different in the highlight selection style, where single clicking selects the row and actions are performed via double click. Touch and keyboard behaviors are unaffected.

devongovett · 2022-06-08T00:51:17Z

packages/@react-spectrum/list/docs/ListView.mdx

+please see the [drag and drop documentation](dragAndDrop.html).
+
+The example below demonstrates how to create a draggable ListView and a droppable ListView.
+


The dnd examples are good. We should probably do some API work separately so they can be simplified though. They are a bit overwhelming, and since many of these use cases are so common, we might be able to provide some helpers to make things easier.

Sounds good, I'll write a ticket

devongovett · 2022-06-08T01:57:48Z

I think the anatomy diagram is a bit large, and I think only the first part showing the parts of the item are necessary rather than the whole listview. Also the font looks off... Gonna push an update for this, hope that's ok.

adobe-bot · 2022-06-08T02:04:45Z

Build successful! 🎉

…docs

adobe-bot · 2022-06-08T21:08:15Z

Build successful! 🎉

devongovett · 2022-06-15T21:57:29Z

packages/@react-spectrum/list/docs/ListView.mdx

+```tsx example
+// Using the same list as above
+<PokemonList disabledKeys={[3]} aria-label="ListView with disabled rows" />
+```


Realized we don't cover disabledBehavior here. Probably a good followup item.

…docs # Conflicts: # packages/@react-spectrum/list/package.json

…ListView-docs

adobe-bot · 2022-06-15T22:35:45Z

Build successful! 🎉

adobe-bot · 2022-06-15T22:51:31Z

Build successful! 🎉

initial ListView docs

7dec7a0

reidbarber requested review from dannify, devongovett and snowystinger as code owners January 7, 2022 00:21

remove unused imports

87c09d2

reidbarber added 4 commits January 7, 2022 10:17

formatting

b22b74c

remove widths

3af4592

content cleanup

a7b30ff

add complex items example

b954cb4

reidbarber added 3 commits January 10, 2022 11:15

move Complex Items example

aee76ef

improve complex items example

1361cb8

add label do density example

c72c742

LFDanLu requested changes Jan 12, 2022

View reviewed changes

reidbarber added 4 commits January 12, 2022 10:45

add better data to examples

e490094

remove hasChildItems from examples

2ffc452

remove 2nd link example

ca9d47b

add description to listview

aa2120c

reidbarber commented Jan 12, 2022

View reviewed changes

packages/@react-spectrum/list/src/ListView.tsx Outdated Show resolved Hide resolved

reidbarber commented Jan 12, 2022

View reviewed changes

packages/@react-spectrum/list/docs/ListView.mdx Outdated Show resolved Hide resolved

reidbarber commented Jan 12, 2022

View reviewed changes

packages/@react-spectrum/list/docs/ListView.mdx Outdated Show resolved Hide resolved

LFDanLu reviewed Jan 12, 2022

View reviewed changes

packages/@react-spectrum/list/docs/ListView.mdx Outdated Show resolved Hide resolved

packages/@react-spectrum/list/docs/ListView.mdx Outdated Show resolved Hide resolved

packages/@react-spectrum/list/docs/ListView.mdx Outdated Show resolved Hide resolved

reidbarber added 4 commits January 12, 2022 13:00

rename list to items for consistency

c83e473

remove key from pokemon list item

cad49fc

fix selection example to match controlled

7cef4b6

add missing descriptions to props

5ffb901

LFDanLu reviewed Jun 6, 2022

View reviewed changes

Merge branch 'main' of github.com:adobe/react-spectrum into ListView-…

7a8f93c

…docs

snowystinger reviewed Jun 7, 2022

View reviewed changes

reidbarber commented Jun 7, 2022

View reviewed changes

devongovett reviewed Jun 8, 2022

View reviewed changes

Update anatomy diagram

4d44d2a

LFDanLu added 4 commits June 8, 2022 11:25

Merge branch 'main' of github.com:adobe/react-spectrum into ListView-…

3140bbf

…docs

adding blurb about ListView vs ListBox

6b11f81

making drag between list example root droppable

cd5e082

simplifying sections as per review

d1c8ba3

snowystinger previously approved these changes Jun 8, 2022

View reviewed changes

devongovett reviewed Jun 15, 2022

View reviewed changes

devongovett added 3 commits June 15, 2022 15:21

Merge branch 'main' of github.com:adobe/react-spectrum into ListView-…

5baee9f

…docs # Conflicts: # packages/@react-spectrum/list/package.json

Temporarily hide drag and drop related docs

b551cfb

Merge branch 'ListView-docs' of github.com:adobe/react-spectrum into …

2083a86

…ListView-docs

devongovett dismissed snowystinger’s stale review via 2083a86 June 15, 2022 22:29

Remove after_version

2758efa

dannify approved these changes Jun 15, 2022

View reviewed changes

devongovett approved these changes Jun 15, 2022

View reviewed changes

devongovett merged commit 9b22962 into main Jun 15, 2022

devongovett deleted the ListView-docs branch June 15, 2022 22:58

	for (let [type, items] of groupedByType) {
	if (NATIVE_DRAG_TYPES.has(type)) {
	// Only one item of a given type can be set on a data transfer.
	// Join all of the items together separated by newlines.
	let data = items.join('\n');
	dataTransfer.items.add(data, type);
	} else {
	// Set data to the first item so we have access to the list of types.
	dataTransfer.items.add(items[0], type);
	}
	}

	if (needsCustomData) {
	let data = JSON.stringify(customData);
	dataTransfer.items.add(data, CUSTOM_DRAG_TYPE);
	}

	// All string items are different representations of the same item. There's no way to have
	// multiple string items at once in the current DataTransfer API.
	if (stringItems.size > 0) {
	items.push({
	kind: 'text',
	types: new Set(stringItems.keys()),
	getText: (type) => Promise.resolve(stringItems.get(type))
	});

		please see the [drag and drop documentation](dragAndDrop.html).

		The example below demonstrates how to create a draggable ListView and a droppable ListView.

Conversation

reidbarber commented Jan 7, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Pull Request Checklist:

📝 Test Instructions:

🧢 Your Project:

Uh oh!

adobe-bot commented Jan 7, 2022

Uh oh!

adobe-bot commented Jan 7, 2022

Uh oh!

adobe-bot commented Jan 7, 2022

Uh oh!

adobe-bot commented Jan 11, 2022

Uh oh!

LFDanLu left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

adobe-bot commented Jan 12, 2022

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adobe-bot commented Jun 6, 2022

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adobe-bot commented Jun 7, 2022

Uh oh!

snowystinger commented Jun 7, 2022

Uh oh!

Choose a reason for hiding this comment

Uh oh!

reidbarber left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

devongovett commented Jun 8, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

adobe-bot commented Jun 8, 2022

Uh oh!

adobe-bot commented Jun 8, 2022

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adobe-bot commented Jun 15, 2022

Uh oh!

adobe-bot commented Jun 15, 2022

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

reidbarber commented Jan 7, 2022 •

edited

Loading

devongovett commented Jun 8, 2022 •

edited

Loading