Could we possibly introduce a more descriptive documentation for "setKey"

[dkozar]

I believe we could possibly provide more detailed documentation around:

• DetailsList selection,
• using arbitrary field as a key (and not the "key" field)
• persisting selection upon grid reload (due to filtering, sorting)
• mystic (but necessary for the selection to work) setKey prop

I struggled to understand why the selection on DetailsList doesn't work. The problem was: I didn't assign the setKey prop:

<DetailsList
  getKey={getKey}
  setKey="some-string" // <-- here
  items={items}
  columns={columns} />

The only documentation available for setKey is:

(property) IDetailsListProps.setKey?: string
A key that uniquely identifies the given items. If provided, the selection will be reset when the key changes.

https://docs.microsoft.com/en-us/javascript/api/react/idetailslistprops?view=office-ui-fabric-react-latest#@fluentui-react-idetailslistprops-setkey-member

The same is true for Intellisense in the editor:

Even with this explanation, I was struggling to understand why I have to assign any string to it.

Since we have the getKey method, setKey seemed like a setter for the thing for which the getKey is getter.

However, these two are not related. Rather, setKey means "the key of the set", where the set is currently loaded data to DetailsList.
Whenever the setKey is changed, grid selection is cleared. So you would probably want to update the setKey with each grid reload (if you don't want to keep the previous selection). Probably using a counter (of reloads), or generated GUID (upon each reload).

I missed the word "items" (so it's not a single item, but many items at once - "a set"):

A key that uniquely identifies the given **items**.

Furthermore, if one doesn't assign the getKey callback, then the default key will be "key". This variable name could sometimes exist in the retrieved data (API response), so we must use another key. And that's what the getKey is for.

If one wants to use some variable name that won't clash (for instance __id__), then they have to assign it to every data row:

export const useItemsWithKeys = (rows: DataTableRow[]): DataTableRow[] =>
  useMemo<DataTableRow[]>(() => rows.map((item) => ({ ...item, __id__: generateGuid() })), [rows]);

Then, the corresponding getKey method should be:

export const getKey = (item: any /*, _index: number*/): string => {
  return item.__id__;
};

This method should then be used both by Selection object, and by DetailsList (for using it as a key in React).

Selection (custom hook):

export const useSelection = (onSelectionChange?: SelectionChangeHandler, selectionMode?: SelectionMode): Selection => {
  const selection = useMemo<Selection>(() => {
    return new Selection({
      onSelectionChanged: () => {
        onSelectionChange?.(selection.getSelection());
      },
      selectionMode,
      getKey, // <-- here
    });
  }, [onSelectionChange, selectionMode]);

  return selection;
};

DetailsList:

<DetailsList
  getKey={getKey} // <-- here
  setKey={setKey}
  selection={selection}
  // ...

[spmonahan]

Thanks for the suggestion and extensive documentation! I think this would be great addition to the docs for DetailsList.

Are you open to submitting a PR to update the docs? I can help you through the process.