KQ-2064 · SCOPE/WHEEL

Scope Wheel

A composer with a thumbwheel at its left edge choosing where the assistant looks — this page, this project, the workspace, the open web. The drum rolls 1:1 under a vertical drag (shaped toward the nearest detent by detents) and settles into the detent the throw was heading for on springs.snap with the release velocity; as the scope lands, an outline of the searched area sweeps across a mini map of the workspace on springs.glide with a scan line running over it, the count of searchable items rolls digit by digit on snap, and the placeholder rewrites itself from the shared prefix. The wheel is a radiogroup on the arrow keys with Cmd or Ctrl and 1 to 4 from the field, locked scopes roll back with a note, and on a phone the map hides and the wheel becomes a pill menu.

KQ-2064 · SCOPE/WHEEL

Fieldline · Larch Street · Site notes

This project · Larch Street0123456789,012345678901234567890123456789items

this project · 1,284 items · fieldline workspace

Open it on the Canvas stage

Install

One command — the source lands in your repo. Or copy it from the Code tab.

$ pnpm dlx shadcn@latest add @kinetiq/scope-wheel

Props

detents: number; default 0.6; How notchy the wheel is, 0 to 1: 0 rolls freely and snaps on release, 1 clicks from detent to detent as you drag; the housing's notches deepen with it.
mapStyle: "blocks" | "wire" | "dots"; default "blocks"; The map's drawing: filled tiles, a hairline blueprint, or dot-matrix tiles.
accent: string; default "var(--accent-bright)"; Outline, notches, count and Send — any CSS colour.
scopes: ScopeWheelScope[]; default defaultScopeWheelScopes; The scopes on the wheel, nearest first: label, short label, area (page, section, workspace, web), count, unit, placeholder, locked and lockedNote.
map: ScopeWheelMap; default defaultScopeWheelMap; The workspace the map draws: its sections and pages, and where the user is.
scope / defaultScope: string; default — / "project"; The chosen scope's id, controlled or initial.
onScopeChange: (id: string) => void; default —; Fires from the turn, key, wheel or menu that changed the scope.
draft / defaultDraft: string; default — / ""; The question, controlled or initial.
onDraftChange: (draft: string) => void; default —; Fires from every edit.
onSubmit: (ask: { text, scope }) => void; default —; Enter or Send: the question and where to look.
onLockedPick: (scope: ScopeWheelScope) => void; default —; A locked scope was reached for; the wheel rolls back and shows its note.
showMap: boolean; default true; Draw the workspace map above the field (always hidden on a phone).
status: "ready" | "counting" | "error"; default "ready"; Whether the counts are known: counting shows a spinner, error says the count is unavailable.
busy: boolean; default false; An answer is being written: Send holds and spins.
label: string; default "Ask Fieldline"; The field's accessible name.
disabled: boolean; default false; Nothing can be typed, turned or sent.
className: string; default —; Classes for the outer surface.

Prop	Type	Default	Description
detents	number	0.6	How notchy the wheel is, 0 to 1: 0 rolls freely and snaps on release, 1 clicks from detent to detent as you drag; the housing's notches deepen with it.
mapStyle	"blocks" \| "wire" \| "dots"	"blocks"	The map's drawing: filled tiles, a hairline blueprint, or dot-matrix tiles.
accent	string	"var(--accent-bright)"	Outline, notches, count and Send — any CSS colour.
scopes	ScopeWheelScope[]	defaultScopeWheelScopes	The scopes on the wheel, nearest first: label, short label, area (page, section, workspace, web), count, unit, placeholder, locked and lockedNote.
map	ScopeWheelMap	defaultScopeWheelMap	The workspace the map draws: its sections and pages, and where the user is.
scope / defaultScope	string	— / "project"	The chosen scope's id, controlled or initial.
onScopeChange	(id: string) => void	—	Fires from the turn, key, wheel or menu that changed the scope.
draft / defaultDraft	string	— / ""	The question, controlled or initial.
onDraftChange	(draft: string) => void	—	Fires from every edit.
onSubmit	(ask: { text, scope }) => void	—	Enter or Send: the question and where to look.
onLockedPick	(scope: ScopeWheelScope) => void	—	A locked scope was reached for; the wheel rolls back and shows its note.
showMap	boolean	true	Draw the workspace map above the field (always hidden on a phone).
status	"ready" \| "counting" \| "error"	"ready"	Whether the counts are known: counting shows a spinner, error says the count is unavailable.
busy	boolean	false	An answer is being written: Send holds and spins.
label	string	"Ask Fieldline"	The field's accessible name.
disabled	boolean	false	Nothing can be typed, turned or sent.
className	string	—	Classes for the outer surface.