@planningcenter/react-beautiful-dnd 13.2.0

package/src/types.js

@@ -0,0 +1,542 @@
+// @flow
+import type { BoxModel, Rect, Position, Spacing } from 'css-box-model';
+
+export type Id = string;
+export type DraggableId = Id;
+export type DroppableId = Id;
+export type TypeId = Id;
+export type ContextId = Id;
+export type ElementId = Id;
+
+export type DroppableMode = 'standard' | 'virtual';
+export type DroppableDescriptor = {|
+  id: DroppableId,
+  type: TypeId,
+  mode: DroppableMode,
+|};
+
+export type DraggableDescriptor = {|
+  id: DraggableId,
+  index: number,
+  // Inherited from Droppable
+  droppableId: DroppableId,
+  // This is technically redundant but it avoids
+  // needing to look up a parent droppable just to get its type
+  type: TypeId,
+|};
+
+export type DraggableOptions = {|
+  canDragInteractiveElements: boolean,
+  shouldRespectForcePress: boolean,
+  isEnabled: boolean,
+|};
+
+export type Direction = 'horizontal' | 'vertical';
+
+export type VerticalAxis = {|
+  direction: 'vertical',
+  line: 'y',
+  start: 'top',
+  end: 'bottom',
+  size: 'height',
+  crossAxisLine: 'x',
+  crossAxisStart: 'left',
+  crossAxisEnd: 'right',
+  crossAxisSize: 'width',
+|};
+
+export type HorizontalAxis = {|
+  direction: 'horizontal',
+  line: 'x',
+  start: 'left',
+  end: 'right',
+  size: 'width',
+  crossAxisLine: 'y',
+  crossAxisStart: 'top',
+  crossAxisEnd: 'bottom',
+  crossAxisSize: 'height',
+|};
+
+export type Axis = VerticalAxis | HorizontalAxis;
+
+export type ScrollSize = {|
+  scrollHeight: number,
+  scrollWidth: number,
+|};
+
+export type ScrollDetails = {|
+  initial: Position,
+  current: Position,
+  // the maximum allowable scroll for the frame
+  max: Position,
+  diff: {|
+    value: Position,
+    // The actual displacement as a result of a scroll is in the opposite
+    // direction to the scroll itself. When scrolling down items are displaced
+    // upwards. This value is the negated version of the 'value'
+    displacement: Position,
+  |},
+|};
+
+export type AxisScrollConditions = {|
+  inThresholdStart: boolean,
+  inThresholdEnd: boolean,
+  draggedTowardsStart: boolean,
+  draggedTowardsEnd: boolean,
+  scrolledTowardsStart: boolean,
+  scrolledTowardsEnd: boolean,
+|};
+
+export type ScrollConditions = {|
+  xAxis: AxisScrollConditions,
+  yAxis: AxisScrollConditions,
+|};
+
+export type Placeholder = {|
+  client: BoxModel,
+  tagName: string,
+  display: string,
+|};
+
+export type DraggableDimension = {|
+  descriptor: DraggableDescriptor,
+  // the placeholder for the draggable
+  placeholder: Placeholder,
+  // relative to the viewport when the drag started
+  client: BoxModel,
+  // relative to the whole page
+  page: BoxModel,
+  // how much displacement the draggable causes
+  // this is the size of the marginBox
+  displaceBy: Position,
+|};
+
+export type Scrollable = {|
+  // This is the window through which the droppable is observed
+  // It does not change during a drag
+  pageMarginBox: Rect,
+  // Used for comparision with dynamic recollecting
+  frameClient: BoxModel,
+  scrollSize: ScrollSize,
+  // Whether or not we should clip the subject by the frame
+  // Is controlled by the ignoreContainerClipping prop
+  shouldClipSubject: boolean,
+  scroll: ScrollDetails,
+|};
+
+export type PlaceholderInSubject = {|
+  // might not actually be increased by
+  // placeholder if there is no required space
+  increasedBy: ?Position,
+  placeholderSize: Position,
+  // max scroll before placeholder added
+  // will be null if there was no frame
+  oldFrameMaxScroll: ?Position,
+|};
+
+export type DroppableSubject = {|
+  // raw, unchanging
+  page: BoxModel,
+  withPlaceholder: ?PlaceholderInSubject,
+  // The hitbox for a droppable
+  // - page margin box
+  // - with scroll changes
+  // - with any additional droppable placeholder
+  // - clipped by frame
+  // The subject will be null if the hit area is completely empty
+  active: ?Rect,
+|};
+
+export type DroppableDimension = {|
+  descriptor: DroppableDescriptor,
+  axis: Axis,
+  isEnabled: boolean,
+  isCombineEnabled: boolean,
+  // relative to the current viewport
+  client: BoxModel,
+  // relative to the whole page
+  isFixedOnPage: boolean,
+  // relative to the page
+  page: BoxModel,
+  // The container of the droppable
+  frame: ?Scrollable,
+  // what is visible through the frame
+  subject: DroppableSubject,
+|};
+export type DraggableLocation = {|
+  droppableId: DroppableId,
+  index: number,
+|};
+
+export type DraggableIdMap = {
+  [id: DraggableId]: true,
+};
+
+export type DroppableIdMap = {
+  [id: DroppableId]: true,
+};
+
+export type DraggableDimensionMap = { [key: DraggableId]: DraggableDimension };
+export type DroppableDimensionMap = { [key: DroppableId]: DroppableDimension };
+
+export type Displacement = {|
+  draggableId: DraggableId,
+  shouldAnimate: boolean,
+|};
+
+export type DisplacementMap = { [key: DraggableId]: Displacement };
+
+export type DisplacedBy = {|
+  value: number,
+  point: Position,
+|};
+
+export type Combine = {|
+  draggableId: DraggableId,
+  droppableId: DroppableId,
+|};
+export type DisplacementGroups = {|
+  all: DraggableId[],
+  visible: DisplacementMap,
+  invisible: DraggableIdMap,
+|};
+
+export type ReorderImpact = {|
+  type: 'REORDER',
+  destination: DraggableLocation,
+|};
+
+export type CombineImpact = {|
+  type: 'COMBINE',
+  combine: Combine,
+|};
+
+export type ImpactLocation = ReorderImpact | CombineImpact;
+
+export type Displaced = {|
+  forwards: DisplacementGroups,
+  backwards: DisplacementGroups,
+|};
+
+export type DragImpact = {|
+  displaced: DisplacementGroups,
+  displacedBy: DisplacedBy,
+  at: ?ImpactLocation,
+|};
+
+export type ClientPositions = {|
+  // where the user initially selected
+  // This point is not used to calculate the impact of a dragging item
+  // It is used to calculate the offset from the initial selection point
+  selection: Position,
+  // the current center of the item
+  borderBoxCenter: Position,
+  // how far the item has moved from its original position
+  offset: Position,
+|};
+
+export type PagePositions = {|
+  selection: Position,
+  borderBoxCenter: Position,
+  // how much the page position has changed from the initial
+  offset: Position,
+|};
+
+// There are two seperate modes that a drag can be in
+// FLUID: everything is done in response to highly granular input (eg mouse)
+// SNAP: items move in response to commands (eg keyboard);
+export type MovementMode = 'FLUID' | 'SNAP';
+
+export type DragPositions = {|
+  client: ClientPositions,
+  page: PagePositions,
+|};
+
+export type DraggableRubric = {|
+  draggableId: DraggableId,
+  type: TypeId,
+  source: DraggableLocation,
+|};
+
+// Published in onBeforeCapture
+// We cannot give more information as things might change in the
+// onBeforeCapture responder!
+export type BeforeCapture = {|
+  draggableId: DraggableId,
+  mode: MovementMode,
+|};
+
+// published when a drag starts
+export type DragStart = {|
+  ...DraggableRubric,
+  mode: MovementMode,
+|};
+
+export type DragUpdate = {|
+  ...DragStart,
+  // may not have any destination (drag to nowhere)
+  destination: ?DraggableLocation,
+  // populated when a draggable is dragging over another in combine mode
+  combine: ?Combine,
+|};
+
+export type DropReason = 'DROP' | 'CANCEL';
+
+// published when a drag finishes
+export type DropResult = {|
+  ...DragUpdate,
+  reason: DropReason,
+|};
+
+export type ScrollOptions = {|
+  shouldPublishImmediately: boolean,
+|};
+
+// all in pixels
+export type DistanceThresholds = {|
+  startScrollingFrom: number,
+  maxScrollValueAt: number,
+|};
+
+// all in ms
+export type DurationDampening = {|
+  stopDampeningAt?: number,
+  accelerateAt?: number,
+|};
+
+export type FluidScrollerConfigOverride = {|
+  // percentage distance from edge of container, decimal
+  startFromPercentage?: number,
+  maxScrollAtPercentage?: number,
+  // pixels per frame
+  ease?: (percentage: number) => number,
+  maxPixelScroll?: number,
+  durationDampening?: DurationDampening,
+|};
+
+export type FluidScrollerOptions = {|
+  // opt into new autoscroll behavior: if the draggable originates inside a scroll threshold
+  // don't autoscroll in that threshold's direction until dragged in that direction
+  bufferThresholds?: boolean,
+  // the distance required to cause a scroll to occur inside a buffered threshold
+  bufferMinScroll?: number,
+  configOverride?: FluidScrollerConfigOverride,
+  // customize your own fluid scroll logic
+  thruGetScroll?: (args: {|
+    center: Position,
+    centerInitial: Position,
+    container: Rect,
+    containerScroll: ScrollDetails,
+    distanceToEdges: Spacing,
+    scroll: Position,
+    thresholdsHorizontal: DistanceThresholds,
+    thresholdsVertical: DistanceThresholds,
+    windowScrollOffset: Position,
+  |}) => Position,
+|};
+
+// using the draggable id rather than the descriptor as the descriptor
+// may change as a result of the initial flush. This means that the lift
+// descriptor may not be the same as the actual descriptor. To avoid
+// confusion the request is just an id which is looked up
+// in the dimension-marshal post-flush
+// Not including droppableId as it might change in a drop flush
+export type LiftRequest = {|
+  draggableId: DraggableId,
+  scrollOptions: ScrollOptions,
+|};
+
+export type Critical = {|
+  draggable: DraggableDescriptor,
+  droppable: DroppableDescriptor,
+|};
+
+export type Viewport = {|
+  // live updates with the latest values
+  frame: Rect,
+  scroll: ScrollDetails,
+|};
+
+export type LiftEffect = {|
+  inVirtualList: boolean,
+  effected: DraggableIdMap,
+  displacedBy: DisplacedBy,
+|};
+
+export type DimensionMap = {|
+  draggables: DraggableDimensionMap,
+  droppables: DroppableDimensionMap,
+|};
+
+export type DroppablePublish = {|
+  droppableId: DroppableId,
+  scroll: Position,
+|};
+export type Published = {|
+  additions: DraggableDimension[],
+  removals: DraggableId[],
+  modified: DroppablePublish[],
+|};
+
+export type CompletedDrag = {|
+  critical: Critical,
+  result: DropResult,
+  impact: DragImpact,
+  afterCritical: LiftEffect,
+|};
+
+export type IdleState = {|
+  phase: 'IDLE',
+  completed: ?CompletedDrag,
+  shouldFlush: boolean,
+|};
+
+export type DraggingState = {|
+  phase: 'DRAGGING',
+  isDragging: true,
+  critical: Critical,
+  movementMode: MovementMode,
+  dimensions: DimensionMap,
+  initial: DragPositions,
+  current: DragPositions,
+  impact: DragImpact,
+  viewport: Viewport,
+  afterCritical: LiftEffect,
+  onLiftImpact: DragImpact,
+  // when there is a fixed list we want to opt out of this behaviour
+  isWindowScrollAllowed: boolean,
+  // if we need to jump the scroll (keyboard dragging)
+  scrollJumpRequest: ?Position,
+  // whether or not draggable movements should be animated
+  forceShouldAnimate: ?boolean,
+|};
+
+// While dragging we can enter into a bulk collection phase
+// During this phase no drag updates are permitted.
+// If a drop occurs during this phase, it must wait until it is
+// completed before continuing with the drop
+// TODO: rename to BulkCollectingState
+export type CollectingState = {|
+  ...DraggingState,
+  phase: 'COLLECTING',
+|};
+
+// If a drop action occurs during a bulk collection we need to
+// wait for the collection to finish before performing the drop.
+// This is to ensure that everything has the correct index after
+// a drop
+export type DropPendingState = {|
+  ...DraggingState,
+  phase: 'DROP_PENDING',
+  isWaiting: boolean,
+  reason: DropReason,
+|};
+
+// An optional phase for animating the drop / cancel if it is needed
+export type DropAnimatingState = {|
+  phase: 'DROP_ANIMATING',
+  completed: CompletedDrag,
+  newHomeClientOffset: Position,
+  dropDuration: number,
+  // We still need to render placeholders and fix the dimensions of the dragging item
+  dimensions: DimensionMap,
+|};
+
+export type State =
+  | IdleState
+  | DraggingState
+  | CollectingState
+  | DropPendingState
+  | DropAnimatingState;
+
+export type StateWhenUpdatesAllowed = DraggingState | CollectingState;
+
+export type Announce = (message: string) => void;
+
+export type InOutAnimationMode = 'none' | 'open' | 'close';
+
+export type ResponderProvided = {|
+  announce: Announce,
+|};
+
+export type OnBeforeCaptureResponder = (before: BeforeCapture) => mixed;
+export type OnBeforeDragStartResponder = (start: DragStart) => mixed;
+export type OnDragStartResponder = (
+  start: DragStart,
+  provided: ResponderProvided,
+) => mixed;
+export type OnDragUpdateResponder = (
+  update: DragUpdate,
+  provided: ResponderProvided,
+) => mixed;
+export type OnDragEndResponder = (
+  result: DropResult,
+  provided: ResponderProvided,
+) => mixed;
+
+export type Responders = {|
+  onBeforeCapture?: OnBeforeCaptureResponder,
+  onBeforeDragStart?: OnBeforeDragStartResponder,
+  onDragStart?: OnDragStartResponder,
+  onDragUpdate?: OnDragUpdateResponder,
+  // always required
+  onDragEnd: OnDragEndResponder,
+|};
+
+// ## Sensors
+export type StopDragOptions = {|
+  shouldBlockNextClick: boolean,
+|};
+
+type DragActions = {|
+  drop: (args?: StopDragOptions) => void,
+  cancel: (args?: StopDragOptions) => void,
+  isActive: () => boolean,
+  shouldRespectForcePress: () => boolean,
+|};
+
+export type FluidDragActions = {|
+  ...DragActions,
+  move: (clientSelection: Position) => void,
+|};
+
+export type SnapDragActions = {|
+  ...DragActions,
+  moveUp: () => void,
+  moveDown: () => void,
+  moveRight: () => void,
+  moveLeft: () => void,
+|};
+
+export type PreDragActions = {|
+  // discover if the lock is still active
+  isActive: () => boolean,
+  // whether it has been indicated if force press should be respected
+  shouldRespectForcePress: () => boolean,
+  // lift the current item
+  fluidLift: (clientSelection: Position) => FluidDragActions,
+  snapLift: () => SnapDragActions,
+  // cancel the pre drag without starting a drag. Releases the lock
+  abort: () => void,
+|};
+
+export type TryGetLockOptions = {
+  sourceEvent?: Event,
+};
+
+export type TryGetLock = (
+  draggableId: DraggableId,
+  forceStop?: () => void,
+  options?: TryGetLockOptions,
+) => ?PreDragActions;
+
+export type SensorAPI = {|
+  tryGetLock: TryGetLock,
+  canGetLock: (id: DraggableId) => boolean,
+  isLockClaimed: () => boolean,
+  tryReleaseLock: () => void,
+  findClosestDraggableId: (event: Event) => ?DraggableId,
+  findOptionsForDraggable: (id: DraggableId) => ?DraggableOptions,
+|};
+
+export type Sensor = (api: SensorAPI) => void;

package/src/view/animate-in-out/animate-in-out.jsx

@@ -0,0 +1,95 @@
+// @flow
+import React, { type Node } from 'react';
+import type { InOutAnimationMode } from '../../types';
+
+export type AnimateProvided = {|
+  onClose: () => void,
+  animate: InOutAnimationMode,
+  data: mixed,
+|};
+
+type Props = {|
+  on: mixed,
+  shouldAnimate: boolean,
+  children: (provided: AnimateProvided) => Node,
+|};
+
+type State = {|
+  data: mixed,
+  isVisible: boolean,
+  animate: InOutAnimationMode,
+|};
+
+// Using a class here rather than hooks because
+// getDerivedStateFromProps results in far less renders.
+// Using hooks to implement this was quite messy and resulted in lots of additional renders
+
+export default class AnimateInOut extends React.PureComponent<Props, State> {
+  state: State = {
+    isVisible: Boolean(this.props.on),
+    data: this.props.on,
+    // not allowing to animate close on mount
+    animate: this.props.shouldAnimate && this.props.on ? 'open' : 'none',
+  };
+
+  static getDerivedStateFromProps(props: Props, state: State): State {
+    if (!props.shouldAnimate) {
+      return {
+        isVisible: Boolean(props.on),
+        data: props.on,
+        animate: 'none',
+      };
+    }
+
+    // need to animate in
+    if (props.on) {
+      return {
+        isVisible: true,
+        // have new data to animate in with
+        data: props.on,
+        animate: 'open',
+      };
+    }
+
+    // need to animate out if there was data
+
+    if (state.isVisible) {
+      return {
+        isVisible: true,
+        // use old data for animating out
+        data: state.data,
+        animate: 'close',
+      };
+    }
+
+    // close animation no longer visible
+    return {
+      isVisible: false,
+      animate: 'close',
+      data: null,
+    };
+  }
+
+  onClose = () => {
+    if (this.state.animate !== 'close') {
+      return;
+    }
+
+    this.setState({
+      isVisible: false,
+    });
+  };
+
+  render() {
+    if (!this.state.isVisible) {
+      return null;
+    }
+
+    const provided: AnimateProvided = {
+      onClose: this.onClose,
+      data: this.state.data,
+      animate: this.state.animate,
+    };
+    return this.props.children(provided);
+  }
+}

package/src/view/animate-in-out/index.js

@@ -0,0 +1,2 @@
+// @flow
+export { default } from './animate-in-out';

package/src/view/check-is-valid-inner-ref.js

@@ -0,0 +1,15 @@
+// @flow
+import { invariant } from '../invariant';
+import isHtmlElement from './is-type-of-element/is-html-element';
+
+export default function checkIsValidInnerRef(el: ?HTMLElement) {
+  invariant(
+    el && isHtmlElement(el),
+    `
+    provided.innerRef has not been provided with a HTMLElement.
+
+    You can find a guide on using the innerRef callback functions at:
+    https://github.com/atlassian/react-beautiful-dnd/blob/master/docs/guides/using-inner-ref.md
+  `,
+  );
+}

package/src/view/context/app-context.js

@@ -0,0 +1,19 @@
+// @flow
+import React from 'react';
+import type { DraggableId, ContextId, ElementId } from '../../types';
+import type { DimensionMarshal } from '../../state/dimension-marshal/dimension-marshal-types';
+import type { FocusMarshal } from '../use-focus-marshal/focus-marshal-types';
+import type { Registry } from '../../state/registry/registry-types';
+
+export type AppContextValue = {|
+  focus: FocusMarshal,
+  contextId: ContextId,
+  canLift: (id: DraggableId) => boolean,
+  isMovementAllowed: () => boolean,
+  dragHandleUsageInstructionsId: ElementId,
+  marshal: DimensionMarshal,
+  registry: Registry,
+  fluidScrollerOptions: Object,
+|};
+
+export default React.createContext<?AppContextValue>(null);

package/src/view/context/droppable-context.js

@@ -0,0 +1,11 @@
+// @flow
+import React from 'react';
+import type { DraggableId, DroppableId, TypeId } from '../../types';
+
+export type DroppableContextValue = {|
+  isUsingCloneFor: ?DraggableId,
+  droppableId: DroppableId,
+  type: TypeId,
+|};
+
+export default React.createContext<?DroppableContextValue>(null);

package/src/view/context/store-context.js

@@ -0,0 +1,5 @@
+// @flow
+import React from 'react';
+import type { Store } from '../../state/store-types';
+
+export default React.createContext<?Store>(null);