Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
5.2 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
export const docs = {
  name: 'useDragToSnapPoints',
  displayName: 'useDragToSnapPoints',
  keywords: [
    'drag',
    'snap',
    'snap points',
    'detents',
    'drawer',
    'flick',
    'swipe',
    'gesture',
  ],
  params: [
    {
      name: 'ref',
      type: 'RefObject<HTMLElement | null>',
      description: 'A ref to the element a drag moves, along `axis` only.',
      required: true,
    },
    {
      name: 'options.axis',
      type: "'x' | 'y'",
      description:
        'The axis the element moves along. A new one creates the drag again, starting where the element is.',
      required: true,
    },
    {
      name: 'options.snapPoints',
      type: 'number[]',
      description:
        "Offsets in px along `axis` from the element's resting position, such as `[0, 240, 480]`, sorted before use (`onSettle` and `settleTo` count in that order); an empty list makes the drag do nothing. Unlike BottomSheet's `snapPoints`, they are not fractions of the viewport. New ones create the drag again and nothing more: the element stays where it is, a settle in flight included, and the next drag or `settleTo` starts there.",
      required: true,
    },
    {
      name: 'options.flickThreshold',
      type: 'number',
      description:
        "A release faster than this, in px/s, carries to the next snap point in its direction. The default is the flick speed measured for UIKit's sheet. A new one creates the drag again, as new snap points do.",
      default: '1008',
      required: false,
    },
    {
      name: 'options.onSettle',
      type: '(index: number) => void',
      description:
        "Called with the snap point's index once the element settles on it. The latest function is the one called, so it may be new on every render.",
      required: true,
    },
  ],
  returns: [
    {
      name: 'settleTo',
      type: '(index: number) => void',
      description:
        'Settles the element on the snap point at `index` without a drag: the keyboard path. The same function on every render.',
    },
  ],
  usage: {
    description:
      "Lets a drag move an element along one axis and settles it on snap points when the finger lifts, the way an iOS sheet settles on its detents: on the nearest snap point to where it is, on the next one in its direction after a quick flick, and back where it started when the finger was moving back. The settle continues the release's velocity. For a bottom sheet, use BottomSheet's `snapPoints`; for a scrolling row, Carousel's `hasSnap`. Outside React, use `createDragToSnapPoints`.",
    bestPractices: [
      {
        guidance: true,
        description:
          'Offer the same positions without a drag: buttons or keys that call `settleTo`.',
      },
      {
        guidance: true,
        description:
          'Keep the settled index in state from `onSettle`, and render what the position means from it.',
      },
      {
        guidance: false,
        description:
          'Use it for a sheet or a carousel: their own props already settle the way people expect.',
      },
    ],
    accessibility: [
      {
        name: 'Keyboard and assistive technology',
        category: 'Keyboard',
        description:
          'A drag is one way in, never the only one. Give each snap point a control a keyboard and a screen reader can reach, such as Expand and Collapse buttons, and call `settleTo` from it. When a position changes what the element shows, announce the change.',
      },
      {
        name: 'Reduce Motion',
        category: 'Content',
        criterion: '2.3.3 Animation from Interactions',
        description:
          'When the person asks for reduced motion, the settle after a touch drag becomes a short cross-fade into the snap point, as does any settle on a device whose primary pointer is coarse, such as a tablet; after a mouse or pen drag elsewhere it lands at once. `settleTo` fades on such a device and lands at once with a fine primary pointer. While the finger is down, the element still follows it.',
      },
    ],
  },
  relatedComponents: ['BottomSheet', 'Carousel'],
  relatedHooks: ['usePanGesture', 'useAnimator'],
  importPath: '@astryxdesign/core/hooks',
  category: 'interaction',
};

/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
export const docsDense = {
  description:
    'A drag that settles the element at ref on snap points (px offsets): {settleTo}.',
  paramDescriptions: {
    ref: 'Ref to the dragged element.',
    'options.axis': "'x' or 'y'.",
    'options.snapPoints': 'Ascending px offsets from the resting position.',
    'options.flickThreshold':
      'px/s past which a release carries one snap point; 1008.',
    'options.onSettle': '(index) once settled; latest one is called.',
  },
  returnDescriptions: {
    settleTo: '(index) settles without a drag; stable.',
  },
  usage: {
    description:
      'Nearest snap point, the next on a flick, the start when moving back; the settle keeps the release velocity. Sheets and carousels: use their props.',
    bestPractices: [
      {guidance: true, description: 'Wire settleTo to buttons and keys.'},
      {guidance: false, description: 'Rebuild a sheet or carousel with it.'},
    ],
  },
};