Manipulation Surface

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

Import ManipulationSurface, ManipulationSurfaceAxis, ManipulationSurfaceTracking, ManipulationSurfaceType from @prepared911/ui/manipulation-surface.

Export	Role
`ManipulationSurface`	The manipulation surface
`ManipulationSurfaceType`	`Slider` (default), `Separator`, `Surface`
`ManipulationSurfaceAxis`	`Inline` (default) or `Block`
`ManipulationSurfaceTracking`	`Relative` (default) or `Absolute`
`ManipulationSurfaceProps`	Props type for manipulation surfaces

InteractableProps (src/models/interactable.ts) is the separate native-control contract Button and Link extend. A future Interactable component in this package will wrap polymorphic click targets like ui-core's Interactable; it does not replace ManipulationSurface.

Props

Prop	Type	Default
`type`	`ManipulationSurfaceType`	`Slider`
`axis`	`ManipulationSurfaceAxis`	`Inline`
`role`	`string`, read only for `Surface`	none
`value`, `defaultValue`	`number`	none
`min`, `max`	`number`	`0`, `100`
`step`, `largeStep`	`number`	`1`, `10`
`reversed`	`boolean`	`false`
`tracking`	`ManipulationSurfaceTracking`	`Relative`
`trackRef`	`RefObject<HTMLElement \| null>`	parent (`Relative`), host (`Absolute`)
`pixelsPerStep`	`number`	none
`holdDelay`	`number` (ms)	`500`
`disabled`	`boolean`	`false`
`onValueChange`	`(value, ChangeDetails<ManipulationSurfaceValueChangeReason>)`	none
`onDraggingChange`	`(dragging, ChangeDetails<ManipulationSurfaceValueChangeReason>)`	none
`onHold`	`(ChangeDetails<ChangeReason.PressHold>)`	none
`render`	element or function	`div`

An accessible name is required: aria-label (LocalizedMessage) or aria-labelledby. style, className, tabIndex, and dir are excluded; role is excluded unless type is Surface. Reasons: Drag, KeyboardStep, DragCancel for values; PressHold for onHold. DragCancel restores the value from when the gesture began and is never cancelable.

Props

Name	Type	Default	Description
`aria-description`	`LocalizedMessage`	—	Extended description for assistive tech.
`aria-label`	`LocalizedMessage`	—	Accessible name.
`aria-labelledby`	`string`	—	Id of the element that names this surface.
`aria-placeholder`	`LocalizedMessage`	—	Hint for an empty control.
`aria-valuetext`	`LocalizedMessage`	—	Human readable form of the value for assistive technology.
`axis`	`ManipulationSurfaceAxis`	—	Logical axis the value moves along. Defaults to {@link ManipulationSurfaceAxis.Inline}.
`children`	`ReactNode`	—	Content of the host, such as a thumb.
`defaultValue`	`number`	—	Initial value when uncontrolled.
`disabled`	`boolean`	—	Ignores every gesture and key. The host stays focusable and writes `aria-disabled`.
`holdDelay`	`number`	—	Milliseconds a pointer or `Enter` or `Space` is held before `onHold` fires. Defaults to `500`.
`largeStep`	`number`	—	`Shift` with an arrow, `PageUp` and `PageDown` step. Defaults to `10`.
`max`	`number`	—	Upper bound. Defaults to `100`.
`min`	`number`	—	Lower bound. Defaults to `0`.
`onDraggingChange`	`((dragging: boolean, details: ChangeDetails<ManipulationSurfaceValueChangeReason>) => void)`	—	Called when a pointer gesture starts (`true`, reason `Drag`), ends with the value kept (`false`, `Drag`), or is abandoned (`false`, `DragCancel`).
`onHold`	`((details: ChangeDetails<ChangeReason.PressHold>) => void)`	—	Called once when a pointer or `Enter` or `Space` is held for `holdDelay`. Arms the hold gesture.
`onValueChange`	`((value: number, details: ChangeDetails<ManipulationSurfaceValueChangeReason>) => void)`	—	Called for every value change with the next value. Cancel a cancelable change with `details.cancel()`; `DragCancel` restores the gesture's start value and is not cancelable.
`pixelsPerStep`	`number`	—	One `step` per this many pixels of travel, used in place of the track for a list with fixed row height.
`ref`	`Ref<HTMLElement>`	—	Ref to the rendered host.
`render`	`RenderProp<Record<string, unknown>, StateAttributesInput>`	—	Replaces the default `div` host.
`reversed`	`boolean`	—	When true the value grows toward inline-start or block-start (a vertical slider with its minimum at the bottom).
`role`	`string`	—	ARIA role. Read only when `type` is {@link ManipulationSurfaceType.Surface}.
`step`	`number`	—	Arrow-key step and the grid pointer travel snaps to. Defaults to `1`.
`title`	`LocalizedMessage`	—	Native tooltip; accessibility hint, not visible UI title text.
`tracking`	`ManipulationSurfaceTracking`	—	How pointer position maps to the value. Defaults to {@link ManipulationSurfaceTracking.Relative}.
`trackRef`	`RefObject<HTMLElement \| null>`	—	Element whose logical size maps to `max - min`. Defaults to the host's parent for {@link ManipulationSurfaceTracking.Relative} and to the host for {@link ManipulationSurfaceTracking.Absolute}.
`type`	`ManipulationSurfaceType`	—	Semantics of the host. Defaults to {@link ManipulationSurfaceType.Slider}.
`value`	`number`	—	Controlled value. Give `value` or `defaultValue` to give the surface a value model.

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

Manipulation Surface / Usage

Manipulation Surface / Accessibility

On this page

Props

Storybook

Manipulation Surface

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

Import ManipulationSurface, ManipulationSurfaceAxis, ManipulationSurfaceTracking, ManipulationSurfaceType from @prepared911/ui/manipulation-surface.

Export	Role
`ManipulationSurface`	The manipulation surface
`ManipulationSurfaceType`	`Slider` (default), `Separator`, `Surface`
`ManipulationSurfaceAxis`	`Inline` (default) or `Block`
`ManipulationSurfaceTracking`	`Relative` (default) or `Absolute`
`ManipulationSurfaceProps`	Props type for manipulation surfaces

Props

Prop	Type	Default
`type`	`ManipulationSurfaceType`	`Slider`
`axis`	`ManipulationSurfaceAxis`	`Inline`
`role`	`string`, read only for `Surface`	none
`value`, `defaultValue`	`number`	none
`min`, `max`	`number`	`0`, `100`
`step`, `largeStep`	`number`	`1`, `10`
`reversed`	`boolean`	`false`
`tracking`	`ManipulationSurfaceTracking`	`Relative`
`trackRef`	`RefObject<HTMLElement \| null>`	parent (`Relative`), host (`Absolute`)
`pixelsPerStep`	`number`	none
`holdDelay`	`number` (ms)	`500`
`disabled`	`boolean`	`false`
`onValueChange`	`(value, ChangeDetails<ManipulationSurfaceValueChangeReason>)`	none
`onDraggingChange`	`(dragging, ChangeDetails<ManipulationSurfaceValueChangeReason>)`	none
`onHold`	`(ChangeDetails<ChangeReason.PressHold>)`	none
`render`	element or function	`div`

Props

Name	Type	Default	Description
`aria-description`	`LocalizedMessage`	—	Extended description for assistive tech.
`aria-label`	`LocalizedMessage`	—	Accessible name.
`aria-labelledby`	`string`	—	Id of the element that names this surface.
`aria-placeholder`	`LocalizedMessage`	—	Hint for an empty control.
`aria-valuetext`	`LocalizedMessage`	—	Human readable form of the value for assistive technology.
`axis`	`ManipulationSurfaceAxis`	—	Logical axis the value moves along. Defaults to {@link ManipulationSurfaceAxis.Inline}.
`children`	`ReactNode`	—	Content of the host, such as a thumb.
`defaultValue`	`number`	—	Initial value when uncontrolled.
`disabled`	`boolean`	—	Ignores every gesture and key. The host stays focusable and writes `aria-disabled`.
`holdDelay`	`number`	—	Milliseconds a pointer or `Enter` or `Space` is held before `onHold` fires. Defaults to `500`.
`largeStep`	`number`	—	`Shift` with an arrow, `PageUp` and `PageDown` step. Defaults to `10`.
`max`	`number`	—	Upper bound. Defaults to `100`.
`min`	`number`	—	Lower bound. Defaults to `0`.
`onDraggingChange`	`((dragging: boolean, details: ChangeDetails<ManipulationSurfaceValueChangeReason>) => void)`	—	Called when a pointer gesture starts (`true`, reason `Drag`), ends with the value kept (`false`, `Drag`), or is abandoned (`false`, `DragCancel`).
`onHold`	`((details: ChangeDetails<ChangeReason.PressHold>) => void)`	—	Called once when a pointer or `Enter` or `Space` is held for `holdDelay`. Arms the hold gesture.
`onValueChange`	`((value: number, details: ChangeDetails<ManipulationSurfaceValueChangeReason>) => void)`	—	Called for every value change with the next value. Cancel a cancelable change with `details.cancel()`; `DragCancel` restores the gesture's start value and is not cancelable.
`pixelsPerStep`	`number`	—	One `step` per this many pixels of travel, used in place of the track for a list with fixed row height.
`ref`	`Ref<HTMLElement>`	—	Ref to the rendered host.
`render`	`RenderProp<Record<string, unknown>, StateAttributesInput>`	—	Replaces the default `div` host.
`reversed`	`boolean`	—	When true the value grows toward inline-start or block-start (a vertical slider with its minimum at the bottom).
`role`	`string`	—	ARIA role. Read only when `type` is {@link ManipulationSurfaceType.Surface}.
`step`	`number`	—	Arrow-key step and the grid pointer travel snaps to. Defaults to `1`.
`title`	`LocalizedMessage`	—	Native tooltip; accessibility hint, not visible UI title text.
`tracking`	`ManipulationSurfaceTracking`	—	How pointer position maps to the value. Defaults to {@link ManipulationSurfaceTracking.Relative}.
`trackRef`	`RefObject<HTMLElement \| null>`	—	Element whose logical size maps to `max - min`. Defaults to the host's parent for {@link ManipulationSurfaceTracking.Relative} and to the host for {@link ManipulationSurfaceTracking.Absolute}.
`type`	`ManipulationSurfaceType`	—	Semantics of the host. Defaults to {@link ManipulationSurfaceType.Slider}.
`value`	`number`	—	Controlled value. Give `value` or `defaultValue` to give the surface a value model.

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

Manipulation Surface / Usage

Manipulation Surface / Accessibility

On this page

Props

Storybook