Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

TreeGrid: Convert to TypeScript #47516

Merged
merged 20 commits into from
Feb 3, 2023
Merged
Show file tree
Hide file tree
Changes from 17 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions packages/components/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@
([#47384](https://github.com/WordPress/gutenberg/pull/47384)).
- `Button`: Convert to TypeScript ([#46997](https://github.com/WordPress/gutenberg/pull/46997)).
- `QueryControls`: Convert to TypeScript ([#46721](https://github.com/WordPress/gutenberg/pull/46721)).
- `TreeGrid`: Convert to TypeScript ([#47516](https://github.com/WordPress/gutenberg/pull/47516)).
- `Notice`: refactor to TypeScript ([47118](https://github.com/WordPress/gutenberg/pull/47118)).

### Bug Fix
Expand Down
76 changes: 18 additions & 58 deletions packages/components/src/tree-grid/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ This feature is still experimental. “Experimental” means this is an early im

## Development guidelines

`TreeGrid`, `TreeGridRow`, and `TreeGridCell` are components used to create a tree hierarchy. They're not visually styled components, but instead help with adding keyboard navigation and roving tab index behaviors to tree grid structures.
`TreeGrid`, `TreeGridRow`, and `TreeGridCell` are components used to create a tree hierarchy. They're not visually styled components, but instead help with adding keyboard navigation and roving tabindex behaviors to tree grid structures.

A tree grid is a hierarchical 2 dimensional UI component, for example it could be used to implement a file system browser.

Expand All @@ -31,69 +31,36 @@ function TreeMenu() {
<TreeGridRow level={ 1 } positionInSet={ 1 } setSize={ 2 }>
<TreeGridCell>
{ ( props ) => (
<Button onClick={ onSelect } { ...props }>
Select
</Button>
<Button onClick={ onSelect } { ...props }>Select</Button>
) }
</TreeGridCell>
<TreeGridCell>
{ ( props ) => (
<Button onClick={ onMoveUp } { ...props }>
Move Up
</Button>
) }
</TreeGridCell>
<TreeGridCell>
{ ( props ) => (
<Button onClick={ onMoveDown } { ...props }>
Move Down
</Button>
Comment on lines -41 to -50
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simplified this code snippet a bit to cut down on the number of lines.

<Button onClick={ onMove } { ...props }>Move</Button>
) }
</TreeGridCell>
</TreeGridRow>
<TreeGridRow level={ 1 } positionInSet={ 2 } setSize={ 2 }>
<TreeGridCell>
{ ( props ) => (
<Button onClick={ onSelect } { ...props }>
Select
</Button>
) }
</TreeGridCell>
<TreeGridCell>
{ ( props ) => (
<Button onClick={ onMoveUp } { ...props }>
Move Up
</Button>
<Button onClick={ onSelect } { ...props }>Select</Button>
) }
</TreeGridCell>
<TreeGridCell>
{ ( props ) => (
<Button onClick={ onMoveDown } { ...props }>
Move Down
</Button>
<Button onClick={ onMove } { ...props }>Move</Button>
) }
</TreeGridCell>
</TreeGridRow>
<TreeGridRow level={ 2 } positionInSet={ 1 } setSize={ 1 }>
<TreeGridCell>
{ ( props ) => (
<Button onClick={ onSelect } { ...props }>
Select
</Button>
) }
</TreeGridCell>
<TreeGridCell>
{ ( props ) => (
<Button onClick={ onMoveUp } { ...props }>
Move Up
</Button>
<Button onClick={ onSelect } { ...props }>Select</Button>
) }
</TreeGridCell>
<TreeGridCell>
{ ( props ) => (
<Button onClick={ onMoveDown } { ...props }>
Move Down
</Button>
<Button onClick={ onMove } { ...props }>Move</Button>
) }
</TreeGridCell>
</TreeGridRow>
Expand All @@ -112,27 +79,24 @@ Aside from the documented callback functions, any props specified will be passed

`TreeGrid` should always have children.

###### onFocusRow( event: Event, startRow: HTMLElement, destinationRow: HTMLElement )
###### `onFocusRow`: `( event: KeyboardEvent, startRow: Element, destinationRow: Element ) => void`

Callback that fires when focus is shifted from one row to another via the Up and Down keys. Callback is also fired on Home and End keys which move focus from the beginning row to the end row.
The callback is passed the event, the start row element that the focus was on originally, and
the destination row element after the focus has moved.

- Type: `Function`
- Required: No

###### onCollapseRow( row: HTMLElement )
###### `onCollapseRow`: `( row: Element ) => void`

A callback that passes in the row element to be collapsed.

- Type: `Function`
- Required: No

###### onExpandRow( row: HTMLElement )
###### `onExpandRow`: `( row: Element ) => void`

A callback that passes in the row element to be expanded.

- Type: `Function`
- Required: No

#### TreeGridRow
Expand All @@ -141,32 +105,28 @@ A callback that passes in the row element to be expanded.

Additional props other than those specified below will be passed to the `tr` element rendered by `TreeGridRow`, so for example, it is possible to also set a `className` on a row.

###### level
###### `level`: `number`

An integer value designating the level in the hierarchical tree structure. Counting starts at 1. A value of `1` indicates the root level of the structure.

- Type: `Number`
- Required: Yes

###### positionInSet
###### `positionInSet`: `number`

An integer value that represents the position in the set. A set is the count of elements at a specific level. Counting starts at 1.

- Type: `Number`
- Required: Yes

###### setSize
###### `setSize`: `number`

An integer value that represents the total number of items in the set ... that is the total number of items at this specific level of the hierarchy.
An integer value that represents the total number of items in the set, at this specific level of the hierarchy.

- Type: `Number`
- Required: Yes

###### isExpanded
###### `isExpanded`: `boolean`

An optional value that designates whether a row is expanded or collapsed. Currently this value only sets the correct aria-expanded property on a row, it has no other built-in behavior.

- Type: `Boolean`
- Required: No

### TreeGridCell
Expand All @@ -182,14 +142,14 @@ An optional value that designates whether a row is expanded or collapsed. Curren
```jsx
<TreeGridCell>
{ ( props ) => (
<Button onClick={ onMoveDown } { ...props }>
Move Down
<Button onClick={ doSomething } { ...props }>
Do something
</Button>
) }
</TreeGridCell>
```

Props passed as an argument to the render prop must be passed to the child focusable component/element within the cell. If a component is used, it must correctly handle the `onFocus`, `tabIndex`, and `ref` props, passing these to the element it renders. These props are used to handle the roving tab index functionality of the tree grid.
Props passed as an argument to the render prop must be passed to the child focusable component/element within the cell. If a component is used, it must correctly handle the `onFocus`, `tabIndex`, and `ref` props, passing these to the element it renders. These props are used to handle the roving tabindex functionality of the tree grid.

## Related components

Expand Down
24 changes: 0 additions & 24 deletions packages/components/src/tree-grid/cell.js

This file was deleted.

41 changes: 41 additions & 0 deletions packages/components/src/tree-grid/cell.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
/**
* WordPress dependencies
*/
import { forwardRef } from '@wordpress/element';

/**
* Internal dependencies
*/
import TreeGridItem from './item';
import type { WordPressComponentProps } from '../ui/context';
import type { TreeGridCellProps } from './types';

function UnforwardedTreeGridCell(
{
children,
withoutGridItem = false,
...props
}: WordPressComponentProps< TreeGridCellProps, 'td', false >,
ref: React.ForwardedRef< any >
) {
return (
<td { ...props } role="gridcell">
{ withoutGridItem ? (
<>{ children }</>
) : (
<TreeGridItem ref={ ref }>{ children }</TreeGridItem>
) }
</td>
);
}

/**
* `TreeGridCell` is used to create a tree hierarchy.
* It is not a visually styled component, but instead helps with adding
* keyboard navigation and roving tab index behaviors to tree grid structures.
*
* @see {@link https://www.w3.org/TR/wai-aria-practices/examples/treegrid/treegrid-1.html}
*/
export const TreeGridCell = forwardRef( UnforwardedTreeGridCell );

export default TreeGridCell;
Loading