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.

Sign up for GitHub

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

Update DndContext Props definition, references to "accessibility" prop #15

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Update DndContext Props definition, references to "accessibility" prop #15

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d924d1e
update DndContext Props definition
sanrafa Sep 25, 2022
fb76ce8
update refs to accessibility prop in accessibility.md
sanrafa Sep 25, 2022
c955255
add screen reader instructions example to accessibility guide
sanrafa Sep 25, 2022
bf7c90c
update refs to accessibility prop in DndContext README
sanrafa Sep 25, 2022
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
80 changes: 41 additions & 39 deletions api-documentation/context-provider/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,17 +4,17 @@

### Context provider

In order for your your [Droppable](../droppable/) and [Draggable](../draggable/) components to interact with each other, you'll need to make sure that the part of your React tree that uses them is nested within a parent `<DndContext>` component. The `<DndContext>` provider makes use of the [React Context API](https://reactjs.org/docs/context.html) to share data between draggable and droppable components and hooks.
In order for your your [Droppable](../droppable/) and [Draggable](../draggable/) components to interact with each other, you'll need to make sure that the part of your React tree that uses them is nested within a parent `<DndContext>` component. The `<DndContext>` provider makes use of the [React Context API](https://reactjs.org/docs/context.html) to share data between draggable and droppable components and hooks.

> React context provides a way to pass data through the component tree without having to pass props down manually at every level.

Therefore, components that use [`useDraggable`](../draggable/usedraggable.md), [`useDroppable`](../droppable/usedroppable.md) or [`DragOverlay`](../draggable/drag-overlay.md) will need to be nested within a `DndContext` provider.
Therefore, components that use [`useDraggable`](../draggable/usedraggable.md), [`useDroppable`](../droppable/usedroppable.md) or [`DragOverlay`](../draggable/drag-overlay.md) will need to be nested within a `DndContext` provider.

They don't need to be direct descendants, but, there does need to be a parent `<DndContext>` provider somewhere higher up in the tree.
They don't need to be direct descendants, but, there does need to be a parent `<DndContext>` provider somewhere higher up in the tree.

```jsx
import React from 'react';
import {DndContext} from '@dnd-kit/core';
import React from "react";
import { DndContext } from "@dnd-kit/core";

function App() {
return (
Expand All @@ -30,18 +30,16 @@ function App() {
You may also nest `<DndContext>` providers within other `<DndContext>` providers to achieve nested draggable/droppable interfaces that are independent of one another.

```jsx
import React from 'react';
import {DndContext} from '@dnd-kit/core';
import React from "react";
import { DndContext } from "@dnd-kit/core";

function App() {
return (
<DndContext>
{/* Components that use `useDraggable`, `useDroppable` */}
<DndContext>
{/* ... */}
<DndContext>
{/* ... */}
</DndContext>
<DndContext>{/* ... */}</DndContext>
</DndContext>
</DndContext>
);
Expand All @@ -56,20 +54,25 @@ If multiple `DndContext` providers are listening for the same event, events will

```typescript
interface Props {
announcements?: Announcements;
autoScroll?: boolean;
id?: string;
accessibility?: {
announcements?: Announcements;
container?: Element;
restoreFocus?: boolean;
screenReaderInstructions?: ScreenReaderInstructions;
};
autoScroll?: boolean | AutoScrollOptions;
cancelDrop?: CancelDrop;
children?: React.ReactNode;
collisionDetection?: CollisionDetection;
layoutMeasuring?: Partial<LayoutMeasuring>;
measuring?: MeasuringConfiguration;
modifiers?: Modifiers;
screenReaderInstructions?: ScreenReaderInstructions;
sensors?: SensorDescriptor<any>[];
onDragStart?(event: DragStartEvent): void;
onDragMove?(event: DragMoveEvent): void;
onDragOver?(event: DragOverEvent): void;
onDragEnd?(event: DragEndEvent): void;
onDragCancel?(): void;
onDragCancel?(event: DragCancelEvent): void;
}
```

Expand All @@ -87,20 +90,20 @@ Fires when a drag event that meets the [activation constraints](../sensors/#conc

Fires anytime as the [draggable](../draggable/) item is moved. Depending on the activated [sensor](../sensors/#activators), this could for example be as the [Pointer](../sensors/pointer.md) is moved or the [Keyboard](../sensors/keyboard.md) movement keys are pressed.

#### `onDragOver`
#### `onDragOver`

Fires when a [draggable](../draggable/) item is moved over a [droppable](../droppable/) container, along with the unique identifier of that droppable container.

#### `onDragEnd`
#### `onDragEnd`

Fires after a draggable item is dropped.
Fires after a draggable item is dropped.

This event contains information about the active draggable `id` along with information on whether the draggable item was dropped `over`.
This event contains information about the active draggable `id` along with information on whether the draggable item was dropped `over`.

If there are no [collisions detected](collision-detection-algorithms.md) when the draggable item is dropped, the `over` property will be `null`. If a collision is detected, the `over` property will contain the `id` of the droppable over which it was dropped.

{% hint style="info" %}
It's important to understand that the `onDragEnd` event **does not move** [**draggable**](../draggable/) **items into** [**droppable**](../droppable/) **containers.**
It's important to understand that the `onDragEnd` event **does not move** [**draggable**](../draggable/) **items into** [**droppable**](../droppable/) **containers.**

Rather, it provides **information** about which draggable item was dropped and whether it was over a droppable container when it was dropped.

Expand All @@ -119,7 +122,7 @@ For more details and best practices around accessibility of draggable and droppa

#### Announcements

Use the `announcements` prop to customize the screen reader announcements that are announced in the live region when draggable items are picked up, moved over droppable regions, and dropped.
Use the `accessibility.announcements` prop to customize the screen reader announcements that are announced in the live region when draggable items are picked up, moved over droppable regions, and dropped.

The default announcements are:

Expand All @@ -145,14 +148,14 @@ const defaultAnnouncements = {
onDragCancel(id) {
return `Dragging was cancelled. Draggable item ${id} was dropped.`;
},
}
};
```

While these default announcements are sensible defaults that should cover most simple use cases, you know your application best, and we highly recommend that you customize these to provide a screen reader experience that is more tailored to the use case you are building.

#### Screen reader instructions

Use the `screenReaderInstructions` prop to customize the instructions that are read to screen readers when the focus is moved
Use the `accessibility.screenReaderInstructions` prop to customize the instructions that are read to screen readers when the focus is moved

### Autoscroll

Expand All @@ -162,15 +165,15 @@ Auto-scrolling may also be disabled on an individual sensor basis using the stat

### Collision detection

Use the `collisionDetection` prop to customize the collision detection algorithm used to detect collisions between draggable nodes and droppable areas within the`DndContext` provider.
Use the `collisionDetection` prop to customize the collision detection algorithm used to detect collisions between draggable nodes and droppable areas within the`DndContext` provider.

The default collision detection algorithm is the [rectangle intersection](collision-detection-algorithms.md#rectangle-intersection) algorithm.

The built-in collision detection algorithms are:

* [Rectangle intersection](collision-detection-algorithms.md#rectangle-intersection)
* [Closest center](collision-detection-algorithms.md#closest-center)
* [Closest corners](collision-detection-algorithms.md#closest-corners)
- [Rectangle intersection](collision-detection-algorithms.md#rectangle-intersection)
- [Closest center](collision-detection-algorithms.md#closest-center)
- [Closest corners](collision-detection-algorithms.md#closest-corners)

You may also build custom collision detection algorithms or compose existing ones.

Expand All @@ -180,7 +183,7 @@ To learn more, read the collision detection guide:

### Sensors

Sensors are an abstraction to detect different input methods in order to initiate drag operations, respond to movement and end or cancel the operation.
Sensors are an abstraction to detect different input methods in order to initiate drag operations, respond to movement and end or cancel the operation.

The default sensors used by `DndContext` are the [Pointer](../sensors/pointer.md) and [Keyboard](../sensors/keyboard.md) sensors.

Expand All @@ -192,34 +195,33 @@ To learn how to customize sensors or how to pass different sensors to `DndContex

Modifiers let you dynamically modify the movement coordinates that are detected by sensors. They can be used for a wide range of use cases, for example:

* Restricting motion to a single axis
* Restricting motion to the draggable node container's bounding rectangle
* Restricting motion to the draggable node's scroll container bounding rectangle
* Applying resistance or clamping the motion
- Restricting motion to a single axis
- Restricting motion to the draggable node container's bounding rectangle
- Restricting motion to the draggable node's scroll container bounding rectangle
- Applying resistance or clamping the motion

To learn more about how to use Modifiers, read the Modifiers guide:

{% page-ref page="../modifiers.md" %}

### Layout measuring

You can configure when and how often `DndContext` should measure its droppable elements by using the `layoutMeasuring` prop.
You can configure when and how often `DndContext` should measure its droppable elements by using the `layoutMeasuring` prop.

The `frequency` argument controls how frequently layouts should be measured. By default, layout measuring is set to `optimized`, which only measures layouts based on the `strategy`.

Specify one of the following strategies:

* `LayoutMeasuringStrategy.WhileDragging`: Default behavior, only measure droppable elements right after dragging has begun.
- `LayoutMeasuringStrategy.WhileDragging`: Default behavior, only measure droppable elements right after dragging has begun.

`LayoutMeasuringStrategy.BeforeDragging`: Measure droppable elements before dragging begins and right after it ends.
`LayoutMeasuringStrategy.BeforeDragging`: Measure droppable elements before dragging begins and right after it ends.

* `LayoutMeasuringStrategy.Always`: Measure droppable elements before dragging begins, right after dragging has begun, and after it ends.
- `LayoutMeasuringStrategy.Always`: Measure droppable elements before dragging begins, right after dragging has begun, and after it ends.

Example usage:

```jsx
import {DndContext, LayoutMeasuringStrategy} from '@dnd-kit/core';
import { DndContext, LayoutMeasuringStrategy } from "@dnd-kit/core";

<DndContext layoutMeasuring={{strategy: LayoutMeasuringStrategy.Always}} />
<DndContext layoutMeasuring={{ strategy: LayoutMeasuringStrategy.Always }} />;
```

Loading