feat(draw): hand one drawn area or line back to the application

createApplicationTools returns drawShape({ shape, signal }): it opens Draw
for one area or line and resolves with its Polygon or LineString without
placing a mark, or null when draw mode is left, the signal aborts, a newer
request replaces it, the pointer is held elsewhere or the tool goes. The
shape controls cannot change the asked-for shape, and a shape across the
antimeridian is refused as a row's actions refuse it and drawn again. It
also returns pointerFree, so an application's own click handlers yield to a
tool holding the pointer, as the layers' do.

src/annotations/drawToolBehaviour.test.mjs

@@ -704,6 +704,158 @@ test('what a row action answers is its row\'s note; the row is busy until then,
   }
 });
 
+test('drawShape hands back the drawn area as a polygon and places no mark', async () => {
+  const h = harness();
+  try {
+    h.act('setDrawShape', 'line');
+    const drawn = h.tool.drawShape({ shape: 'area' });
+    assert.equal(h.tool.active, true, 'it opens draw mode');
+    assert.equal(h.tool.shape, 'area');
+    h.tool.addVertex(-97.75, 30.26);
+    h.tool.addVertex(-97.74, 30.26);
+    h.tool.addVertex(-97.74, 30.27);
+    h.documentDouble.emit('keydown', {
+      key: 'Enter',
+      target: h.documentDouble.body,
+    });
+    const geometry = await drawn;
+    assert.deepEqual(geometry, {
+      type: 'Polygon',
+      coordinates: [
+        [
+          [-97.75, 30.26],
+          [-97.74, 30.26],
+          [-97.74, 30.27],
+          [-97.75, 30.26],
+        ],
+      ],
+    });
+    assert.equal(h.annotations.calls.annotate.length, 0, 'no mark is placed');
+    assert.equal(h.tool.active, false, 'draw mode ends');
+    assert.equal(isPointerFree(), true);
+    assert.equal(h.tool.shape, 'line', 'the shape chosen before comes back');
+  } finally {
+    h.restore();
+  }
+});
+
+test('drawShape hands back a line as a LineString', async () => {
+  const h = harness();
+  try {
+    const drawn = h.tool.drawShape({ shape: 'line' });
+    h.tool.addVertex(-97.75, 30.26);
+    h.tool.addVertex(-97.74, 30.26);
+    h.documentDouble.emit('keydown', {
+      key: 'Enter',
+      target: h.documentDouble.body,
+    });
+    assert.deepEqual(await drawn, {
+      type: 'LineString',
+      coordinates: [
+        [-97.75, 30.26],
+        [-97.74, 30.26],
+      ],
+    });
+  } finally {
+    h.restore();
+  }
+});
+
+test('drawShape resolves null on Escape, on abort, on a newer request and when the pointer is taken', async () => {
+  const h = harness();
+  try {
+    // Escape with a shape started clears it; a second Escape leaves.
+    const escaped = h.tool.drawShape({ shape: 'area' });
+    h.tool.addVertex(-97.75, 30.26);
+    h.documentDouble.emit('keydown', {
+      key: 'Escape',
+      target: h.documentDouble.body,
+    });
+    assert.equal(h.tool.active, true, 'the first Escape only clears the shape');
+    h.documentDouble.emit('keydown', {
+      key: 'Escape',
+      target: h.documentDouble.body,
+    });
+    assert.equal(await escaped, null);
+    assert.equal(h.tool.active, false);
+
+    const controller = new AbortController();
+    const aborted = h.tool.drawShape({
+      shape: 'area',
+      signal: controller.signal,
+    });
+    controller.abort();
+    assert.equal(await aborted, null);
+    assert.equal(isPointerFree(), true, 'an abort gives the pointer back');
+
+    const first = h.tool.drawShape({ shape: 'area' });
+    const second = h.tool.drawShape({ shape: 'line' });
+    assert.equal(await first, null, 'a newer request ends the older one');
+    h.act('toggleDraw');
+    assert.equal(await second, null, 'leaving draw mode ends it');
+
+    const done = new AbortController();
+    done.abort();
+    assert.equal(await h.tool.drawShape({ signal: done.signal }), null);
+
+    const other = claimPointer('directions');
+    assert.equal(
+      await h.tool.drawShape({ shape: 'area' }),
+      null,
+      'a held pointer refuses it',
+    );
+    releasePointer(other);
+
+    // Drawing by hand afterwards places marks as before.
+    h.act('toggleDraw');
+    h.tool.addVertex(-97.75, 30.26);
+    h.tool.addVertex(-97.74, 30.26);
+    h.tool.addVertex(-97.74, 30.27);
+    h.documentDouble.emit('keydown', {
+      key: 'Enter',
+      target: h.documentDouble.body,
+    });
+    await Promise.resolve();
+    assert.equal(h.annotations.calls.annotate.length, 1);
+  } finally {
+    h.restore();
+  }
+});
+
+test('drawShape keeps its shape, and a shape across the antimeridian is drawn again', async () => {
+  const h = harness();
+  try {
+    const drawn = h.tool.drawShape({ shape: 'line' });
+    h.act('setDrawShape', 'pin');
+    assert.equal(h.tool.shape, 'line', 'the controls cannot change the asked-for shape');
+    h.tool.addVertex(179.5, 10);
+    h.tool.addVertex(-179.5, 10);
+    h.documentDouble.emit('keydown', { key: 'Enter', target: h.documentDouble.body });
+    assert.equal(h.tool.active, true, 'still drawing');
+    assert.equal(h.tool.session.vertices.length, 0, 'drawn again from the start');
+    assert.equal(h.shown.view.hint, 'That shape could not be placed.');
+    h.tool.addVertex(29, 41);
+    h.tool.addVertex(29.1, 41);
+    h.documentDouble.emit('keydown', { key: 'Enter', target: h.documentDouble.body });
+    assert.equal((await drawn).type, 'LineString');
+    h.act('setDrawShape', 'pin');
+    assert.equal(h.tool.shape, 'pin', 'after it, the controls choose again');
+  } finally {
+    h.restore();
+  }
+});
+
+test('destroy ends a drawShape request with null', async () => {
+  const h = harness();
+  try {
+    const drawn = h.tool.drawShape({ shape: 'area' });
+    h.tool.destroy();
+    assert.equal(await drawn, null);
+  } finally {
+    h.restore();
+  }
+});
+
 test('Backspace on the page removes the last vertex', () => {
   const h = harness();
   try {