エージェントが作り、エージェントが使う Vercel の UI SDK と AI 時代のヘッドレス UI

npm install @ui-sdk/[email protected] @ui-sdk/[email protected]

npx skills add vercel-labs/ui --skill ui-sdk

ui-sdk スキルを使って、React でトランスファーリストを作ってください。
 
左に「未割り当て」、右に「割り当て済み」の 2 つのリストがあり、プロジェクトのメンバーを左右に移動できるコンポーネントです。
 
- 各リストには Tab で 1 回だけフォーカスが入り、上下の矢印キーで項目間を移動する
- Space で項目を選択・選択解除でき、複数の項目を選択できる
- 2 つのリストの間にある「割り当てる」「外す」ボタンで、選択中の項目を反対側のリストへ移動する
- 移動後もフォーカスを見失わないようにする。移動元のリストに項目が残っていれば、そのリストにフォーカスを戻す
- 移動した件数をスクリーンリーダーに読み上げる
- 割り当て済みの値は親コンポーネントが持ち、変更を受け取れるようにする
- エージェントが createAgent を通じてメンバーを割り当てたり外したりできるようにする
 
固定の 6 人のメンバーと、1 つの例のページから始めてください。スタイルは最小限で構いません。
 
キーボード操作、フォーカス、ARIA をテストし、typecheck と関連するテストを実行してください。開発サーバーは起動しないでください。最後に、実行したコマンドと結果、確認できなかったことを報告してください。

import {
  announce,
  createChange,
  createFocusRecovery,
  createRovingFocus,
  createSelection,
  definePrimitive,
  type ChangeDetails,
} from "@ui-sdk/core";
 
// 型（TransferListOptions、TransferListState など）と補助関数は省略
 
const transferList = definePrimitive({
  // コンポーネントの名前。スナップショットの component にもこの名前が入る
  name: "transfer-list",
  // コンポーネントが受け取るオプションと、その種類
  options: {
    items: "value",
    value: "list",
    defaultValue: "list",
    onValueChange: "callback",
  },
  // 親が value、defaultValue、onValueChange で制御できる状態
  controlled: ["value"],
  // 状態の初期値
  state: (options: TransferListOptions): TransferListState => ({
    items: options.items ?? [],
    value: options.value ?? options.defaultValue ?? [],
    selected: [],
    focusedAvailable: null,
    focusedAssigned: null,
  }),
  // オプションが変わるたびに、制御されている値を状態へ反映する（省略）
  sync: (options) => ({ /* ... */ }),
  // コンポーネントの操作。behavior はここで生成する
  api: (context) => { /* ... */ },
  // DOM 要素の単位であるパーツ
  slots: (slot) => { /* ... */ },
  // エージェントに公開する操作
  agent: { actions: ["assign", "unassign"], items: (api) => api.items() },
});

api: (context) => {
  const { store } = context;
  const change = createChange(context);
  const selection = createSelection(context, {
    key: "selected",
    multiple: () => true,
    // set、order は省略
  });
 
  // 左右のリストごとに、フォーカスの移動と回復の behavior を作る
  const block = (side: Side) => ({
    roving: createRovingFocus<TransferListState, OptionProps>(context, {
      slot: optionSlot[side], // "availableOption" か "assignedOption"
      key: focusKey[side], // "focusedAvailable" か "focusedAssigned"
    }),
    recovery: createFocusRecovery<OptionProps>({
      fallback: (lost) => {
        // 消えた項目に最も近い、同じリストの項目を返す（省略）
      },
    }),
  });
  const blocks = {
    available: block("available"),
    assigned: block("assigned"),
  };
 
  const move = (to: Side, requested: string[] | undefined, event?: Event) => {
    // 後述
  };
 
  return {
    selection,
    blocks,
    assign: (ids?: string[], event?: Event) => move("assigned", ids, event),
    unassign: (ids?: string[], event?: Event) => move("available", ids, event),
    items: () =>
      store.get().items.map((item) => ({ value: item.id, label: item.label })),
  };
},

const move = (to: Side, requested: string[] | undefined, event?: Event) => {
  // 移動元のリスト（from）、移動する項目の id（ids）、
  // 移動後の割り当て済みの値（value）を求める（省略）
 
  if (
    !change("value", value, {
      reason: to === "assigned" ? "assign" : "unassign",
      event,
    })
  ) {
    return false;
  }
 
  store.set({ selected: state.selected.filter((id) => !moved.has(id)) });
  announce(
    to === "assigned"
      ? `${ids.length} 人を割り当てました`
      : `${ids.length} 人を外しました`,
  );
 
  // 移動元のリストに残った項目のうち、移動した項目に最も近いもの
  const stay = nearest(
    state.items.map((item) => item.id),
    (id) => pool.includes(id) && !moved.has(id),
    ids[0],
  );
  const target = stay
    ? { side: from, key: stay }
    : { side: to, key: ids[0] };
  blocks[target.side].roving.focus(target.key);
  return true;
};

slots: (slot) => {
  const option = (side: Side) =>
    slot<OptionProps>({
      role: "option",
      focus: "roving",
      props: { value: "string" },
      attrs: (state, part) => ({
        tabindex: part.api.blocks[side].roving.tabIndex(state, part),
        "aria-selected": String(state.selected.includes(part.key)),
        "data-selected": state.selected.includes(part.key) ? "" : undefined,
      }),
      // press、on.keydown、bind は省略
    });
  // リスト（listbox）と移動ボタン（button）のパーツも同じように定義する（省略）
 
  return {
    root: slot({ role: "group" }),
    available: list(),
    availableOption: option("available"),
    assigned: list(),
    assignedOption: option("assigned"),
    assign: mover("assigned"),
    unassign: mover("available"),
  };
},

agent: { actions: ["assign", "unassign"], items: (api) => api.items() },

import { createParts } from "@ui-sdk/react/primitive";
import { transferList } from "./primitive";
 
const parts = createParts(transferList, {
  root: "div",
  available: "ul",
  availableOption: "li",
  assigned: "ul",
  assignedOption: "li",
  assign: "button",
  unassign: "button",
});

import { useId } from "react";
import {
  listOf,
  type TransferItem,
  type TransferListOptions,
} from "./primitive";
 
type TransferListProps = {
  label: string;
  items: TransferItem[];
  value: string[];
  onValueChange: NonNullable<TransferListOptions["onValueChange"]>;
};
 
function TransferList({
  label,
  items,
  value,
  onValueChange,
}: TransferListProps) {
  const id = useId();
  const state = {
    items,
    value,
    selected: [],
    focusedAvailable: null,
    focusedAssigned: null,
  };
  // listOf は primitive.ts の関数で、value に含まれるかどうかで項目を左右に振り分ける
  const available = listOf(state, "available");
  const assigned = listOf(state, "assigned");
 
  return (
    <parts.Root
      aria-label={label}
      items={items}
      value={value}
      onValueChange={onValueChange}
    >
      <div>
        <h3 id={`${id}-available`}>未割り当て</h3>
        <parts.Available aria-labelledby={`${id}-available`}>
          {available.map((item) => (
            <parts.AvailableOption key={item.id} value={item.id}>
              {item.label}
            </parts.AvailableOption>
          ))}
        </parts.Available>
        {available.length === 0 && <p>メンバーはいません</p>}
      </div>
      <div>
        <parts.Assign>割り当てる</parts.Assign>
        <parts.Unassign>外す</parts.Unassign>
      </div>
      <div>
        <h3 id={`${id}-assigned`}>割り当て済み</h3>
        <parts.Assigned aria-labelledby={`${id}-assigned`}>
          {assigned.map((item) => (
            <parts.AssignedOption key={item.id} value={item.id}>
              {item.label}
            </parts.AssignedOption>
          ))}
        </parts.Assigned>
        {assigned.length === 0 && <p>メンバーはいません</p>}
      </div>
    </parts.Root>
  );
}
 
export { TransferList, type TransferListProps };

import { useState } from "react";
import { members } from "./members";
import { TransferList } from "./transfer-list/transfer-list";
 
function App() {
  const [assigned, setAssigned] = useState<string[]>(["aiko"]);
 
  return (
    <main>
      <h1>プロジェクトメンバー</h1>
      <TransferList
        label="プロジェクトメンバーの割り当て"
        items={members}
        value={assigned}
        onValueChange={setAssigned}
      />
      <p>
        割り当て済み:{" "}
        {members
          .filter((member) => assigned.includes(member.id))
          .map((member) => member.label)
          .join("、") || "なし"}
      </p>
    </main>
  );
}
 
export default App;

import { createAgent } from "@ui-sdk/react/agent";
 
const agent = createAgent();
 
Object.assign(window, { agent });
 
export { agent };

import "./agent";
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import App from "./App.tsx";
 
createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <App />
  </StrictMode>,
);

[
  {
    "ref": "c1",
    "component": "transfer-list",
    "actions": ["assign", "unassign"],
    "label": "プロジェクトメンバーの割り当て",
    "value": ["aiko", "chika", "emi"],
    "items": [
      { "value": "aiko", "label": "相沢 愛子" },
      { "value": "bunta", "label": "馬場 文太" },
      // 省略...
    ]
  }
]

await window.agent.act({
  steps: [
    { ref: "プロジェクトメンバーの割り当て", action: "assign", args: [["古川 文夫"]] },
    { ref: "プロジェクトメンバーの割り当て", action: "unassign", args: [["emi"]] },
  ],
});

{
  "ok": true,
  "steps": [
    {
      "step": 0,
      "ref": "c1",
      "changes": [
        {
          "component": "transfer-list",
          "label": "プロジェクトメンバーの割り当て",
          "key": "value",
          "value": ["aiko", "chika", "emi", "fumio"]
        }
      ]
    },
    // 2 つ目の手順（unassign）の結果は省略
  ],
  "appeared": [],
  "values": {
    "c1 プロジェクトメンバーの割り当て": ["aiko", "chika", "fumio"]
  }
}

await window.agent.act({
  steps: [{ ref: "プロジェクトメンバーの割り当て", action: "setValue", args: [["bunta"]] }],
});
// { ok: false, error: { step: 0, message: "transfer-list c1 takes no setValue now. It takes: assign, unassign." }, ... }

import { createAgent } from "@ui-sdk/react/agent";
 
const agent = createAgent({
  allow: ({ component, action }) =>
    !(component === "transfer-list" && action === "unassign"),
});