Add actions and group row actions

An assisted action is a thing on an assisted page the assistant presses as the user would click it. Render it inside an AssistedPage. Outside one, it throws.

Wrap one element

Wrap the element in AssistedAction with a name and a label. The label says what pressing does. From examples/app/app/orders/page.tsx:

<AssistedAction name="new_order" label="Open the New order dialog">
  <Button size="sm" className="ms-auto" onClick={() => setCreating(true)}>
    New order
  </Button>
</AssistedAction>

AssistedAction takes one child and attaches a ref to it. The child must pass that ref to a DOM element. shadcn’s Button does.

A press answers with Pressed "<label>". and the page’s note as the press left it.

Group row actions

Give every row the same name and its own id. The assistant sees one tool that picks a row by id, and the ids follow the rows as they mount and unmount. From examples/app/app/orders/page.tsx:

<AssistedAction
  name="ship_order"
  id={order.id}
  label={`Ship ${order.customer}'s order #${order.id}`}
>
  <Button size="sm" onClick={() => shop.call("shipOrder", [order.id])}>
    Ship
  </Button>
</AssistedAction>

Use ids the page’s content also returns, so the assistant can match a row it read to the row it presses. In a group, give every row an id.

Let disabled mean disabled

A press checks the element first. A native disabled or aria-disabled="true" answers that the action is disabled right now, and nothing is clicked. From examples/app/app/orders/[id]/page.tsx:

<AssistedAction name="save_note" label="Save the note">
  <Button
    disabled={draft === order.note}
    onClick={() => shop.call("saveNote", [order.id, draft])}
  >
    Save note
  </Button>
</AssistedAction>

Use the hook instead

When wrapping does not fit, call useAssistedAction and attach the ref it returns:

export function ShipButton({ id, onShip }: { id: string; onShip: () => void }) {
  const ref = useAssistedAction<HTMLButtonElement>({
    name: "ship_order",
    id,
    label: `Ship order #${id}`,
  });
  return (
    <button ref={ref} onClick={onShip}>
      Ship
    </button>
  );
}

To have the user press it instead, see Make an action consequential.