@viamrobotics/test-widgets 0.6.0 → 0.7.0

package/README.md

@@ -10,7 +10,7 @@ The playground (`pnpm dev`) can be used to develop the test-cards against prod r
 
 This is useful if you need to validate the sdk against specific behavior of modules or need to replicate a bug from another robot (why replicate locally when you could just develop directly against the robot with the bug?).
 
-To setup your playground, create a `.env.local` in the test-cards directory with the following format (no need to create two robots):
+To setup your playground, create a `.env.local` in the test-widgets directory with the following format (no need to create two robots):
 
 ```json
 VITE_PLAYGROUND_ROBOTS='

package/dist/api-docs-href.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Returns the docs URL for a given resource API + method, or undefined
+ * when the method has no dedicated anchor (e.g. GetStatus, GetSourceNames).
+ *
+ * @param api  - RDK API string, e.g. "rdk:component:movement_sensor"
+ * @param method - camelCase method name, e.g. "getPosition"
+ */
+export declare const apiDocsHref: (api: string, method: string) => string | undefined;

package/dist/api-docs-href.js

@@ -0,0 +1,17 @@
+const NO_LINK_METHODS = new Set(['getStatus', 'getSourceNames']);
+/**
+ * Returns the docs URL for a given resource API + method, or undefined
+ * when the method has no dedicated anchor (e.g. GetStatus, GetSourceNames).
+ *
+ * @param api  - RDK API string, e.g. "rdk:component:movement_sensor"
+ * @param method - camelCase method name, e.g. "getPosition"
+ */
+export const apiDocsHref = (api, method) => {
+    if (NO_LINK_METHODS.has(method))
+        return undefined;
+    const isService = api.includes(':service:');
+    // RDK API strings use underscores (movement_sensor); docs URLs use hyphens (movement-sensor)
+    const subtype = api.split(':').at(-1).replaceAll('_', '-');
+    const kind = isService ? 'services' : 'components';
+    return `https://docs.viam.com/reference/apis/${kind}/${subtype}/#${method.toLowerCase()}`;
+};

package/dist/components/angle-unit-toggle.svelte

@@ -15,10 +15,7 @@
 		aria-label={useRadians ? 'Switch to Degrees' : 'Switch to Radians'}
 		class="text-gray-6 hover:border-medium hover:bg-medium active:bg-gray-2 justify-items-end p-0.5"
 	>
-		<Icon
-			name="sync"
-			size="xs"
-		/>
+		<Icon name="sync" />
 	</button>
 
 	<span slot="description">

package/dist/components/api-section.svelte

@@ -2,14 +2,17 @@
 	import type { Snippet } from 'svelte'
 	import type { HTMLAttributes } from 'svelte/elements'
 
-	import { Icon, Tooltip } from '@viamrobotics/prime-core'
 	import { twMerge } from 'tailwind-merge'
 
+	import SectionTitle from './section-title.svelte'
+
 	interface Props extends HTMLAttributes<HTMLElement> {
 		title?: string | undefined
 		tooltip?: string | undefined
 		description?: string | undefined
 		bottomText?: string | undefined
+		/** RDK API string; presence renders the title as a linked monospace method name */
+		api?: string | undefined
 		class?: string
 		children?: Snippet
 	}
@@ -19,6 +22,7 @@
 		tooltip,
 		description,
 		bottomText,
+		api,
 		class: className = '',
 		children,
 		...rest
@@ -29,32 +33,26 @@
 
 <section
 	class={twMerge('flex grow flex-col gap-4 p-4', className)}
-	aria-labelledby={headingID}
+	aria-labelledby={title ? headingID : undefined}
 	{...rest}
 >
 	{#if title}
 		<div class="flex flex-col gap-0.5">
-			<h3
-				class="flex flex-row items-center gap-1 text-sm font-semibold"
-				id={headingID}
-			>
-				{title}
-				{#if tooltip}
-					<Tooltip>
-						<Icon
-							name="information-outline"
-							cx="text-gray-6"
-						/>
-
-						<p
-							slot="description"
-							class="text-xs whitespace-pre-line"
-						>
-							{tooltip}
-						</p>
-					</Tooltip>
-				{/if}
-			</h3>
+			{#if api}
+				<SectionTitle
+					{title}
+					{tooltip}
+					{api}
+					headingId={headingID}
+				/>
+			{:else}
+				<h3
+					class="flex flex-row items-center gap-1 text-sm font-semibold"
+					id={headingID}
+				>
+					{title}
+				</h3>
+			{/if}
 			{#if description}
 				<p class="text-subtle-2 text-xs">{description}</p>
 			{/if}

package/dist/components/api-section.svelte.d.ts

@@ -5,6 +5,8 @@ interface Props extends HTMLAttributes<HTMLElement> {
     tooltip?: string | undefined;
     description?: string | undefined;
     bottomText?: string | undefined;
+    /** RDK API string; presence renders the title as a linked monospace method name */
+    api?: string | undefined;
     class?: string;
     children?: Snippet;
 }

package/dist/components/index.d.ts

@@ -1,4 +1,5 @@
 export { default as ConnectionStatus } from './connection-status.svelte';
+export { default as SectionTitle } from './section-title.svelte';
 export { default as ArmWidget } from './widgets/arm/arm.svelte';
 export { default as ArmMoveToJointPositionsWidget } from './widgets/arm/move-to-joint-positions-widget.svelte';
 export { default as ArmMoveToPositionWidget } from './widgets/arm/move-to-position-widget.svelte';

package/dist/components/index.js

@@ -1,4 +1,5 @@
 export { default as ConnectionStatus } from './connection-status.svelte';
+export { default as SectionTitle } from './section-title.svelte';
 export { default as ArmWidget } from './widgets/arm/arm.svelte';
 export { default as ArmMoveToJointPositionsWidget } from './widgets/arm/move-to-joint-positions-widget.svelte';
 export { default as ArmMoveToPositionWidget } from './widgets/arm/move-to-position-widget.svelte';

package/dist/components/is-moving.svelte

@@ -33,10 +33,11 @@
 		client: Client
 		partID: string
 		resourceName: string
+		api: string
 		children?: Snippet
 	}
 
-	const { client: clientClass, partID, resourceName, children }: Props = $props()
+	const { client: clientClass, partID, resourceName, api, children }: Props = $props()
 
 	const client = $derived(
 		createResourceClient<Arm | Base | Gantry | Gripper | Motor | Servo>(
@@ -51,6 +52,7 @@
 
 <ApiSection
 	title="IsMoving"
+	{api}
 	bottomText="Updates automatically"
 	class="grow"
 >

package/dist/components/is-moving.svelte.d.ts

@@ -5,6 +5,7 @@ interface Props {
     client: Client;
     partID: string;
     resourceName: string;
+    api: string;
     children?: Snippet;
 }
 declare const IsMoving: import("svelte").Component<Props, {}, "">;

package/dist/components/mutation-section.svelte

@@ -1,16 +1,18 @@
 <script lang="ts">
 	import type { Snippet } from 'svelte'
 
-	import { Icon, Tooltip } from '@viamrobotics/prime-core'
 	import { twMerge } from 'tailwind-merge'
 
 	import ErrorDisplay from './error.svelte'
+	import SectionTitle from './section-title.svelte'
 
 	interface Props {
 		title: string
 		tooltip?: string | undefined
 		description?: string | undefined
 		lastError: Error | null
+		/** RDK API string; presence renders the title as a linked monospace method name */
+		api?: string | undefined
 		class?: string
 		titleInput?: Snippet
 		error?: Snippet
@@ -22,6 +24,7 @@
 		tooltip,
 		description,
 		lastError = null,
+		api,
 		class: className,
 		titleInput,
 		error,
@@ -37,27 +40,21 @@
 >
 	<div class={twMerge('flex grow flex-row flex-wrap gap-2', className)}>
 		<div class="flex max-w-[200px] grow flex-col gap-0.5 pr-4">
-			<h3
-				class="flex flex-row items-center gap-1 text-sm font-semibold"
-				id={headingID}
-			>
-				{title}
-				{#if tooltip}
-					<Tooltip>
-						<Icon
-							name="information-outline"
-							cx="text-gray-6"
-						/>
-
-						<p
-							slot="description"
-							class="text-xs whitespace-pre-line"
-						>
-							{tooltip}
-						</p>
-					</Tooltip>
-				{/if}
-			</h3>
+			{#if api}
+				<SectionTitle
+					{title}
+					{tooltip}
+					{api}
+					headingId={headingID}
+				/>
+			{:else}
+				<h3
+					class="flex flex-row items-center gap-1 text-sm font-semibold"
+					id={headingID}
+				>
+					{title}
+				</h3>
+			{/if}
 			{#if description}
 				<p class="text-subtle-2 text-xs">{description}</p>
 			{/if}

package/dist/components/mutation-section.svelte.d.ts

@@ -4,6 +4,8 @@ interface Props {
     tooltip?: string | undefined;
     description?: string | undefined;
     lastError: Error | null;
+    /** RDK API string; presence renders the title as a linked monospace method name */
+    api?: string | undefined;
     class?: string;
     titleInput?: Snippet;
     error?: Snippet;

package/dist/components/section-title.svelte

@@ -0,0 +1,63 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte'
+
+	import { Icon, Tooltip } from '@viamrobotics/prime-core'
+
+	import { apiDocsHref } from '../api-docs-href'
+
+	interface Props {
+		title: string
+		tooltip?: string | undefined
+		/** RDK API string, e.g. "rdk:component:camera". Required — SectionTitle is only for headers that map to an API method; the docs link is built from this plus the title. */
+		api: string
+		/** Optional external ID for the <h3>; generated internally if omitted */
+		headingId?: string | undefined
+		/** Inline content rendered after the title inside the <h3> (e.g. unit labels) */
+		suffix?: Snippet
+	}
+
+	const { title, tooltip, api, headingId, suffix }: Props = $props()
+
+	const generatedID = $props.id()
+	const id = $derived(headingId ?? generatedID)
+
+	// Method names are the camelCase form of the PascalCase title (GetPosition → getPosition).
+	const method = $derived(title.charAt(0).toLowerCase() + title.slice(1))
+	const href = $derived(apiDocsHref(api, method))
+</script>
+
+<h3
+	class="flex flex-row items-center gap-1 text-sm font-semibold"
+	{id}
+>
+	{#if href}
+		<a
+			{href}
+			target="_blank"
+			rel="noopener noreferrer external"
+			class="decoration-gray-5 hover:decoration-default font-mono underline underline-offset-3"
+		>
+			{title}
+		</a>
+	{:else}
+		<span class="font-mono">{title}</span>
+	{/if}
+	{#if suffix}
+		{@render suffix()}
+	{/if}
+	{#if tooltip}
+		<Tooltip>
+			<Icon
+				name="information-outline"
+				cx="text-gray-6"
+			/>
+
+			<p
+				slot="description"
+				class="text-xs whitespace-pre-line"
+			>
+				{tooltip}
+			</p>
+		</Tooltip>
+	{/if}
+</h3>

package/dist/components/section-title.svelte.d.ts

@@ -0,0 +1,14 @@
+import type { Snippet } from 'svelte';
+interface Props {
+    title: string;
+    tooltip?: string | undefined;
+    /** RDK API string, e.g. "rdk:component:camera". Required — SectionTitle is only for headers that map to an API method; the docs link is built from this plus the title. */
+    api: string;
+    /** Optional external ID for the <h3>; generated internally if omitted */
+    headingId?: string | undefined;
+    /** Inline content rendered after the title inside the <h3> (e.g. unit labels) */
+    suffix?: Snippet;
+}
+declare const SectionTitle: import("svelte").Component<Props, {}, "">;
+type SectionTitle = ReturnType<typeof SectionTitle>;
+export default SectionTitle;

package/dist/components/widgets/arm/arm.svelte

@@ -19,7 +19,6 @@
 	import { getJointPositionLimits, type KinematicsJSON } from './joint-position-limits'
 	import MoveToJointPositions from './move-to-joint-positions.svelte'
 	import MoveToPosition from './move-to-position.svelte'
-	import QuickMove from './quick-move.svelte'
 
 	interface Props {
 		partID: string
@@ -38,9 +37,9 @@
 	const jointPositionsQuery = createResourceQuery(client, 'getJointPositions', options)
 	const endPositionQuery = createResourceQuery(client, 'getEndPosition', options)
 	const kinematicsQuery = createResourceQuery(client, 'getKinematics', options)
+	const isMovingQuery = createResourceQuery(client, 'isMoving', options)
 
 	const moveToJointPosMutation = createResourceMutation(client, 'moveToJointPositions')
-	const quickMoveToJointPosMutation = createResourceMutation(client, 'moveToJointPositions')
 	const stopMutation = createResourceMutation(client, 'stop')
 	const moveToPosMutation = createResourceMutation(client, 'moveToPosition')
 
@@ -48,10 +47,6 @@
 		moveToJointPosMutation.mutate([jointPositionsList], {})
 	}
 
-	const quickMoveToJointPositions = (jointPositionsList: number[]) => {
-		quickMoveToJointPosMutation.mutate([jointPositionsList], {})
-	}
-
 	const moveToPosition = (position: Pose) => {
 		moveToPosMutation.mutate([position], {})
 	}
@@ -62,10 +57,11 @@
 		<div class="flex flex-col gap-4 lg:flex-row lg:gap-0 lg:divide-x">
 			<!-- Main control sections -->
 			<div
-				class="flex flex-col gap-4 lg:grid lg:grow lg:grid-cols-2 lg:gap-0 lg:divide-x xl:grid-cols-4"
+				class="flex flex-col gap-4 lg:grid lg:grow lg:grid-cols-2 lg:gap-0 lg:divide-x xl:grid-cols-3"
 			>
 				<ApiSection
 					title="GetJointPositions"
+					api="rdk:component:arm"
 					bottomText="Updates automatically"
 				>
 					<Query query={jointPositionsQuery}>
@@ -74,7 +70,10 @@
 						{/if}
 					</Query>
 				</ApiSection>
-				<ApiSection title="MoveToJointPositions">
+				<ApiSection
+					title="MoveToJointPositions"
+					api="rdk:component:arm"
+				>
 					<Queries queries={[jointPositionsQuery, kinematicsQuery]}>
 						{#if jointPositionsQuery.data && kinematicsQuery.data}
 							<MoveToJointPositions
@@ -82,11 +81,15 @@
 								{moveToJointPositions}
 								lastError={moveToJointPosMutation.error}
 								jointLimitsDegrees={getJointPositionLimits(kinematicsQuery.data as KinematicsJSON)}
+								isMoving={isMovingQuery.data ?? false}
 							/>
 						{/if}
 					</Queries>
 				</ApiSection>
-				<ApiSection title="MoveToPosition">
+				<ApiSection
+					title="MoveToPosition"
+					api="rdk:component:arm"
+				>
 					<Query query={endPositionQuery}>
 						{#if endPositionQuery.data}
 							<MoveToPosition
@@ -97,27 +100,16 @@
 						{/if}
 					</Query>
 				</ApiSection>
-				<ApiSection
-					title="Quick move"
-					bottomText="Press a button to execute"
-				>
-					<Query query={jointPositionsQuery}>
-						{#if jointPositionsQuery.data}
-							<QuickMove
-								positions={jointPositionsQuery.data.values}
-								moveToJointPositions={quickMoveToJointPositions}
-								lastError={quickMoveToJointPosMutation.error}
-							/>
-						{/if}
-					</Query>
-				</ApiSection>
 			</div>
 
 			<!-- Control actions sidebar -->
 			<div
 				class="flex flex-row gap-4 lg:ml-auto lg:w-full lg:max-w-40 lg:flex-col lg:gap-0 lg:divide-y"
 			>
-				<ApiSection title="Stop">
+				<ApiSection
+					title="Stop"
+					api="rdk:component:arm"
+				>
 					<StopButton
 						error={stopMutation.error}
 						onStop={() => {
@@ -127,6 +119,7 @@
 				</ApiSection>
 				<IsMoving
 					client={ArmClient}
+					api="rdk:component:arm"
 					{partID}
 					{resourceName}
 				/>

package/dist/components/widgets/arm/joint-position-editor.svelte

@@ -0,0 +1,89 @@
+<script lang="ts">
+	import { Button, Icon, Tooltip } from '@viamrobotics/prime-core'
+
+	import Table from '../../table.svelte'
+
+	import { type JointLimit } from './joint-position-limits'
+	import JointPositionSlider from './joint-position-slider.svelte'
+
+	interface Props {
+		desiredPositions: number[]
+		positions: number[]
+		jointLimitsDegrees: JointLimit[]
+		useRadians: boolean
+		moveToJointPositions: (jointPositions: number[]) => void
+	}
+
+	let {
+		desiredPositions = $bindable(),
+		positions,
+		jointLimitsDegrees,
+		useRadians,
+		moveToJointPositions,
+	}: Props = $props()
+
+	const getSliderMin = (index: number): number => jointLimitsDegrees[index]?.minDegrees ?? -180
+	const getSliderMax = (index: number): number => jointLimitsDegrees[index]?.maxDegrees ?? 180
+
+	const execute = () => {
+		moveToJointPositions([...desiredPositions])
+	}
+
+	const resetToZero = () => {
+		desiredPositions = positions.map(() => 0)
+	}
+
+	const resetToCurrent = () => {
+		desiredPositions = [...positions]
+	}
+</script>
+
+<Table>
+	<thead>
+		<tr>
+			<th>Joint</th>
+			<th>Position ({useRadians ? 'radians' : 'degrees'})</th>
+		</tr>
+	</thead>
+	<tbody>
+		{#each [...desiredPositions.keys()] as index (index)}
+			<tr>
+				<th scope="row">{index}</th>
+				<th>
+					<JointPositionSlider
+						bind:value={desiredPositions[index]}
+						minDegrees={getSliderMin(index)}
+						maxDegrees={getSliderMax(index)}
+						{useRadians}
+					/>
+				</th>
+			</tr>
+		{/each}
+	</tbody>
+</Table>
+
+<div class="mb-2 flex flex-col gap-2">
+	<span class="flex flex-row gap-2">
+		<h4 class="text-xs font-semibold">Quick set</h4>
+		<Tooltip>
+			<Icon
+				name="information-outline"
+				cx="text-gray-6"
+			/>
+			<span slot="description">Will update the slider values but will not execute</span>
+		</Tooltip>
+	</span>
+	<div class="flex flex-col gap-2 sm:flex-row">
+		<Button onclick={resetToZero}>Zero</Button>
+		<Button onclick={resetToCurrent}>Current position</Button>
+	</div>
+</div>
+
+<Button
+	class="mt-auto w-fit"
+	icon="play-circle-outline"
+	variant="dark"
+	onclick={execute}
+>
+	Execute
+</Button>

package/dist/components/widgets/arm/joint-position-editor.svelte.d.ts

@@ -0,0 +1,11 @@
+import { type JointLimit } from './joint-position-limits';
+interface Props {
+    desiredPositions: number[];
+    positions: number[];
+    jointLimitsDegrees: JointLimit[];
+    useRadians: boolean;
+    moveToJointPositions: (jointPositions: number[]) => void;
+}
+declare const JointPositionEditor: import("svelte").Component<Props, {}, "desiredPositions">;
+type JointPositionEditor = ReturnType<typeof JointPositionEditor>;
+export default JointPositionEditor;

package/dist/components/widgets/arm/joint-position-quick-move.svelte

@@ -0,0 +1,85 @@
+<script lang="ts">
+	import { Button, Icon, Tooltip } from '@viamrobotics/prime-core'
+
+	import Table from '../../table.svelte'
+	import { degreesToRadians, formatNumeric } from '../../../format'
+
+	const INCREMENT_DEGREES = 5
+
+	interface Props {
+		positions: number[]
+		moveToJointPositions: (jointPositions: number[]) => void
+		useRadians: boolean
+		isMoving: boolean
+	}
+
+	const { positions, moveToJointPositions, useRadians, isMoving }: Props = $props()
+
+	const toDisplayAngle = (degrees: number) => (useRadians ? degreesToRadians(degrees) : degrees)
+
+	const currentDisplayPositions = $derived(positions.map((degrees) => toDisplayAngle(degrees)))
+
+	const quickMove = (index: number, increment: number) => {
+		if (isMoving) {
+			return
+		}
+		const clonedPositions = positions.map((position, positionIndex) =>
+			positionIndex === index ? position + increment : position
+		)
+		moveToJointPositions(clonedPositions)
+	}
+</script>
+
+<Tooltip>
+	<span class="flex items-center gap-1 text-xs text-amber-600">
+		<Icon
+			name="alert"
+			size="sm"
+			cx="text-amber-600"
+		/>
+		Quick move executes immediately
+	</span>
+	<span slot="description">
+		Each ±5° button sends a move command as soon as it is pressed. Buttons are disabled while the
+		arm is moving.
+	</span>
+</Tooltip>
+
+<Table>
+	<thead>
+		<tr>
+			<th>Joint</th>
+			<th>Move (degrees)</th>
+		</tr>
+	</thead>
+	<tbody>
+		{#each positions as position, index (index)}
+			{@const currentValue = currentDisplayPositions[index] ?? position}
+			{@const unit = useRadians ? ' rad' : '°'}
+			<tr>
+				<th scope="row">{index}</th>
+				<th>
+					<div class="flex h-full max-h-6.5 w-full items-center justify-center gap-1.5">
+						<Button
+							aria-label="Decrease joint {index} by 5 degrees"
+							disabled={isMoving}
+							onclick={() => quickMove(index, -INCREMENT_DEGREES)}
+						>
+							−5°
+						</Button>
+						<span class="min-w-16 grow text-center text-xs text-gray-700 tabular-nums">
+							{formatNumeric(currentValue)}{unit}
+						</span>
+						<Button
+							aria-label="Increase joint {index} by 5 degrees"
+							disabled={isMoving}
+							onclick={() => quickMove(index, INCREMENT_DEGREES)}
+						>
+							+5°
+						</Button>
+					</div>
+				</th>
+			</tr>
+		{/each}
+	</tbody>
+</Table>

package/dist/components/widgets/arm/joint-position-quick-move.svelte.d.ts

@@ -0,0 +1,9 @@
+interface Props {
+    positions: number[];
+    moveToJointPositions: (jointPositions: number[]) => void;
+    useRadians: boolean;
+    isMoving: boolean;
+}
+declare const JointPositionQuickMove: import("svelte").Component<Props, {}, "">;
+type JointPositionQuickMove = ReturnType<typeof JointPositionQuickMove>;
+export default JointPositionQuickMove;