diff --git a/packages/design/README.md b/packages/design/README.md index 954ffec..45b0451 100644 --- a/packages/design/README.md +++ b/packages/design/README.md @@ -88,7 +88,7 @@ directives) plus, recommended, `@unocss/eslint-plugin` for the feedback loop. | `./components/*` | one readable `.vue` per component (e.g. `./components/Display/DisplayBadge.vue`) | | `./unocss` | the single `presetAnthonyDesign` preset | | `./utils` | color, format, path, semver, contrast, keybinding helpers (pure, stateless) | -| `./composables/*` | Vue helpers: `colorScheme` (opt-in scheme context) and `toast` (`useToast` queue) | +| `./composables/*` | Vue helpers: `colorScheme` (opt-in scheme context), `toast` (`useToast` queue), and `agent` (agent bridge) | | `./a11y` | programmatic color-contrast scan | | `./styles.css`, `./styles/*` | all styles, or per-concern files | | `./splitpanes.d.ts` | opt-in fallback types for older `splitpanes` (v4.1.2+ ships its own) | @@ -103,6 +103,40 @@ directives) plus, recommended, `@unocss/eslint-plugin` for the feedback loop. > `useToast()` (from `@antfu/design/composables/toast`) owns a toast queue for > `FeedbackToasts`. Both only read state you own. +### Agent bridge + +AI agents can read and drive the form controls (`FormTextInput`, `FormTextarea`, +`FormNumberInput`, `FormSelect`, `FormCombobox`, `FormSwitch`, `FormCheckbox`, +`FormRadioGroup`, `FormSegmentedControl`) and `LayoutTabs` through their own +APIs. They don't need screenshots or simulated clicks. + +```ts +import { createAgent, getChangeSource } from '@antfu/design/composables/agent' + +const agent = createAgent({ + // Optional: approve or reject each step. + allow: step => step.action !== 'clear', +}) +app.use(agent) // or `provideAgent(agent)` in a component to scope it to a subtree + +agent.snapshot() +// [{ ref: 'c1', component: 'text-input', label: 'Project name', value: 'Apollo', actions: ['setValue', 'clear'] }, …] + +await agent.act({ steps: [{ ref: 'Project name', action: 'setValue', args: ['Atlas'] }] }) +// → { results: [{ step, ok: true }], snapshot: [...] } +``` + +- A control's label comes from its `label` prop, then `aria-label`, then the + enclosing `FormField` label, then `placeholder`. +- Actions run through `v-model`, so the same validation applies as for a user. + For example, `setValue` on a select only accepts enabled options, and + `FormNumberInput` clamps to `min`/`max`. +- Inside an `@update:modelValue` handler, `getChangeSource()` returns `'agent'` + for changes made by the agent. +- `agent.tools()` returns `ui_snapshot` / `ui_act` tool definitions, which you + can register with WebMCP or pass to any agent SDK. +- If no bridge is installed, the components don't register at all. + ## Migrating an existing app If your app predates the design system, adoption is mostly **deletion**: diff --git a/packages/design/components/Form/FormCheckbox.vue b/packages/design/components/Form/FormCheckbox.vue index 8351aff..e836bee 100644 --- a/packages/design/components/Form/FormCheckbox.vue +++ b/packages/design/components/Form/FormCheckbox.vue @@ -1,15 +1,27 @@ diff --git a/packages/design/components/Form/FormCombobox.vue b/packages/design/components/Form/FormCombobox.vue index 553f911..dd6c9dc 100644 --- a/packages/design/components/Form/FormCombobox.vue +++ b/packages/design/components/Form/FormCombobox.vue @@ -1,6 +1,7 @@ diff --git a/packages/design/components/Form/FormNumberInput.vue b/packages/design/components/Form/FormNumberInput.vue index 8546bba..40ed7ab 100644 --- a/packages/design/components/Form/FormNumberInput.vue +++ b/packages/design/components/Form/FormNumberInput.vue @@ -2,6 +2,7 @@ diff --git a/packages/design/components/Form/FormRadioGroup.vue b/packages/design/components/Form/FormRadioGroup.vue index 43db4ce..2bff5d2 100644 --- a/packages/design/components/Form/FormRadioGroup.vue +++ b/packages/design/components/Form/FormRadioGroup.vue @@ -1,6 +1,7 @@ diff --git a/packages/design/components/Form/FormSegmentedControl.vue b/packages/design/components/Form/FormSegmentedControl.vue index a76fdfe..addbac7 100644 --- a/packages/design/components/Form/FormSegmentedControl.vue +++ b/packages/design/components/Form/FormSegmentedControl.vue @@ -1,6 +1,7 @@ diff --git a/packages/design/components/Form/FormSelect.vue b/packages/design/components/Form/FormSelect.vue index 99df714..b12fc54 100644 --- a/packages/design/components/Form/FormSelect.vue +++ b/packages/design/components/Form/FormSelect.vue @@ -1,6 +1,7 @@ diff --git a/packages/design/components/Form/FormSwitch.vue b/packages/design/components/Form/FormSwitch.vue index 87fda9c..36d0c07 100644 --- a/packages/design/components/Form/FormSwitch.vue +++ b/packages/design/components/Form/FormSwitch.vue @@ -1,13 +1,25 @@ diff --git a/packages/design/components/Form/FormTextInput.vue b/packages/design/components/Form/FormTextInput.vue index e40313b..99255a6 100644 --- a/packages/design/components/Form/FormTextInput.vue +++ b/packages/design/components/Form/FormTextInput.vue @@ -1,6 +1,8 @@ diff --git a/packages/design/components/Form/FormTextarea.vue b/packages/design/components/Form/FormTextarea.vue index f683f7e..89eefc0 100644 --- a/packages/design/components/Form/FormTextarea.vue +++ b/packages/design/components/Form/FormTextarea.vue @@ -1,6 +1,8 @@ diff --git a/packages/design/components/Layout/LayoutTabs.vue b/packages/design/components/Layout/LayoutTabs.vue index 9375e98..860dc98 100644 --- a/packages/design/components/Layout/LayoutTabs.vue +++ b/packages/design/components/Layout/LayoutTabs.vue @@ -1,6 +1,7 @@ diff --git a/packages/design/components/Overview.mdx b/packages/design/components/Overview.mdx index 63d6181..ae88023 100644 --- a/packages/design/components/Overview.mdx +++ b/packages/design/components/Overview.mdx @@ -63,6 +63,7 @@ import * as OverlayDropdownItem from './Overlay/OverlayDropdownItem.stories' import * as OverlayHoverCard from './Overlay/OverlayHoverCard.stories' import * as OverlayModal from './Overlay/OverlayModal.stories' import * as OverlayTooltip from './Overlay/OverlayTooltip.stories' +import * as AgentBridge from './Utility/AgentBridge.stories' import * as ScrollFade from './Utility/ScrollFade.stories' import * as ShadowRoot from './Utility/ShadowRoot.stories' import * as Shimmer from './Utility/Shimmer.stories' @@ -447,6 +448,10 @@ A composable, token-driven design system for devtools-style Vue apps. Each tile ## Utility +### [AgentBridge](/?path=/docs/utility-agentbridge--docs) + + + ### [ScrollFade](/?path=/docs/utility-scrollfade--docs) diff --git a/packages/design/components/Utility/AgentBridge.stories.ts b/packages/design/components/Utility/AgentBridge.stories.ts new file mode 100644 index 0000000..f2aa409 --- /dev/null +++ b/packages/design/components/Utility/AgentBridge.stories.ts @@ -0,0 +1,113 @@ +import type { Meta, StoryObj } from '@storybook/vue3-vite' +import type { AgentControlSnapshot, AgentStepResult } from '../../composables/agent' +import { defineComponent, nextTick, onMounted, ref, shallowRef } from 'vue' +import { createAgent, getChangeSource, provideAgent } from '../../composables/agent' +import ActionButton from '../Action/ActionButton.vue' +import FormField from '../Form/FormField.vue' +import FormNumberInput from '../Form/FormNumberInput.vue' +import FormSegmentedControl from '../Form/FormSegmentedControl.vue' +import FormSelect from '../Form/FormSelect.vue' +import FormSwitch from '../Form/FormSwitch.vue' +import FormTextInput from '../Form/FormTextInput.vue' + +// An agent fills in a settings form through the bridge: no screenshots, no +// clicks. The right pane is exactly what `agent.snapshot()` hands the model. + +const sampleSteps = [ + { ref: 'Project name', action: 'setValue', args: ['Atlas'] }, + { ref: 'Region', action: 'setValue', args: ['eu'] }, + { ref: 'Replicas', action: 'increment' }, + { ref: 'Visibility', action: 'setValue', args: ['public'] }, + { ref: 'Notifications', action: 'toggle' }, +] + +const Demo = defineComponent({ + components: { ActionButton, FormField, FormNumberInput, FormSegmentedControl, FormSelect, FormSwitch, FormTextInput }, + setup() { + const agent = createAgent({ + // Example guard: the agent may never turn the project private. + allow: step => !(step.ref === 'Visibility' && step.args?.[0] === 'private'), + }) + provideAgent(agent) + + const name = ref('Apollo') + const region = ref('us') + const replicas = ref(2) + const visibility = ref('internal') + const notify = ref(false) + const lastSource = ref('—') + const snapshot = shallowRef([]) + const results = shallowRef([]) + + const refresh = (): void => { + snapshot.value = agent.snapshot() + } + const track = (): void => { + lastSource.value = getChangeSource() + } + onMounted(() => nextTick(refresh)) + + async function run(steps = sampleSteps): Promise { + const out = await agent.act({ steps }) + results.value = out.results + snapshot.value = out.snapshot + } + + return { + name, + region, + replicas, + visibility, + notify, + lastSource, + snapshot, + results, + refresh, + track, + run, + regions: [{ value: 'us', label: 'US East' }, { value: 'eu', label: 'EU West' }, { value: 'ap', label: 'Asia Pacific', disabled: true }], + visibilities: [{ value: 'private' }, { value: 'internal' }, { value: 'public' }], + forbidden: [{ ref: 'Visibility', action: 'setValue', args: ['private'] }], + } + }, + template: ` + + + + + + + Last change by: {{ lastSource }} + + Run agent steps + Try a forbidden step + Refresh snapshot + + + + agent.snapshot() + {{ JSON.stringify(snapshot, null, 2) }} + + act() results + + + + {{ r.step.ref }} · {{ r.step.action }} + {{ r.error }} + + + + + `, +}) + +const meta = { + title: 'Utilities/AgentBridge', + component: Demo, + tags: ['autodocs'], +} satisfies Meta + +export default meta +type Story = StoryObj + +export const Default: Story = {} diff --git a/packages/design/composables/agent.ts b/packages/design/composables/agent.ts new file mode 100644 index 0000000..a3eb709 --- /dev/null +++ b/packages/design/composables/agent.ts @@ -0,0 +1,262 @@ +/** + * Agent bridge: let an AI agent read and drive the UI through component APIs + * instead of screenshots or accessibility-tree clicking. + * + * Create one bridge and install it with `app.use(agent)`, or scope it to a + * subtree with `provideAgent(agent)`. Instrumented form controls and + * `LayoutTabs` then register themselves. `snapshot()` lists their state and + * actions, and `act()` runs actions through the same `v-model` path a user's + * input takes. + * Without an installed bridge, the components skip registration entirely. + * + * While an action runs, {@link getChangeSource} returns `'agent'`, so an + * `@update:modelValue` handler can tell agent changes from user changes. + * + * @example + * const agent = createAgent({ allow: step => step.action !== 'clear' }) + * app.use(agent) + * agent.snapshot() + * // [{ ref: 'c1', component: 'text-input', label: 'Project name', value: 'Apollo', actions: ['setValue', 'clear'] }] + * await agent.act({ steps: [{ ref: 'Project name', action: 'setValue', args: ['Atlas'] }] }) + */ +import type { App, InjectionKey } from 'vue' +import { getCurrentInstance, inject, nextTick, onBeforeUnmount, onMounted, provide } from 'vue' + +/** One control as an agent sees it. */ +export interface AgentControlSnapshot { + /** Stable id for this mount, e.g. `c3`. */ + ref: string + /** Control kind, e.g. `text-input`, `switch`, `select`. */ + component: string + label?: string + value: unknown + disabled?: boolean + /** Allowed values, for controls that pick from a list. */ + options?: unknown[] + actions: string[] +} + +export interface AgentStep { + /** A control `ref` or its exact `label`. */ + ref: string + action: string + args?: unknown[] +} + +export interface AgentStepResult { + step: AgentStep + ok: boolean + error?: string +} + +export interface AgentActResult { + results: AgentStepResult[] + /** The state after all steps ran. */ + snapshot: AgentControlSnapshot[] +} + +export interface AgentBridgeOptions { + /** Approve or reject each step before it runs. Defaults to allowing all. */ + allow?: (step: AgentStep, control: AgentControlSnapshot) => boolean | Promise +} + +/** A tool shape that works for WebMCP (`navigator.modelContext`) or any agent SDK. */ +export interface AgentTool { + name: string + description: string + inputSchema: Record + execute: (input: any) => Promise +} + +export interface AgentBridge { + snapshot: () => AgentControlSnapshot[] + /** Run steps in order. Stops at the first failed step. */ + act: (input: { steps: AgentStep[] }) => Promise + /** `snapshot` and `act` as tool definitions. */ + tools: () => AgentTool[] + /** Vue plugin hook, so `app.use(bridge)` works. */ + install: (app: App) => void +} + +/** What a component passes to {@link useAgentControl}. */ +export interface AgentControlDefinition { + component: string + label?: () => string | undefined + value: () => unknown + disabled?: () => boolean | undefined + options?: () => unknown[] | undefined + actions: Record void> +} + +interface Registry { + register: (def: AgentControlDefinition) => () => void +} + +const AgentKey: InjectionKey = Symbol('antfu-design-agent') +const registries = new WeakMap() +const FieldLabelKey: InjectionKey<() => string | undefined> = Symbol('antfu-design-field-label') + +let source: 'agent' | 'user' = 'user' + +/** + * Who caused the change being handled right now. Read it synchronously inside + * an `@update:modelValue` (or watcher with `flush: 'sync'`) handler. + */ +export function getChangeSource(): 'agent' | 'user' { + return source +} + +export function createAgent(options: AgentBridgeOptions = {}): AgentBridge { + const controls = new Map() + let counter = 0 + + const registry: Registry = { + register(def) { + const ref = `c${++counter}` + controls.set(ref, def) + return () => controls.delete(ref) + }, + } + + function describe(ref: string, def: AgentControlDefinition): AgentControlSnapshot { + const snap: AgentControlSnapshot = { + ref, + component: def.component, + label: def.label?.(), + value: def.value(), + actions: Object.keys(def.actions), + } + if (def.disabled?.()) + snap.disabled = true + const opts = def.options?.() + if (opts) + snap.options = opts + return snap + } + + function snapshot(): AgentControlSnapshot[] { + return [...controls].map(([ref, def]) => describe(ref, def)) + } + + function resolve(target: string): [string, AgentControlDefinition] { + const byRef = controls.get(target) + if (byRef) + return [target, byRef] + const matches = [...controls].filter(([, def]) => def.label?.() === target) + if (matches.length === 1) + return matches[0]! + throw new Error(matches.length ? `Label "${target}" matches ${matches.length} controls; use a ref` : `No control "${target}"`) + } + + async function runStep(step: AgentStep): Promise { + const [ref, def] = resolve(step.ref) + const snap = describe(ref, def) + if (snap.disabled) + throw new Error(`Control "${step.ref}" is disabled`) + const action = def.actions[step.action] + if (!action) + throw new Error(`Unknown action "${step.action}"; available: ${snap.actions.join(', ')}`) + if (options.allow && !(await options.allow(step, snap))) + throw new Error('Rejected by allow()') + source = 'agent' + try { + action(...(step.args ?? [])) + } + finally { + source = 'user' + } + await nextTick() + } + + async function act({ steps }: { steps: AgentStep[] }): Promise { + const results: AgentStepResult[] = [] + for (const step of steps) { + try { + await runStep(step) + results.push({ step, ok: true }) + } + catch (error) { + results.push({ step, ok: false, error: (error as Error).message }) + break + } + } + return { results, snapshot: snapshot() } + } + + const stepSchema = { + type: 'object', + properties: { + ref: { type: 'string', description: 'Control ref (e.g. "c1") or exact label' }, + action: { type: 'string' }, + args: { type: 'array' }, + }, + required: ['ref', 'action'], + } + + const bridge: AgentBridge = { + snapshot, + act, + tools: () => [ + { + name: 'ui_snapshot', + description: 'List the UI controls on the page with their label, value, options, and available actions.', + inputSchema: { type: 'object', properties: {} }, + execute: async () => snapshot(), + }, + { + name: 'ui_act', + description: 'Run actions on UI controls in order. Returns per-step results and the new snapshot.', + inputSchema: { type: 'object', properties: { steps: { type: 'array', items: stepSchema } }, required: ['steps'] }, + execute: input => act(input), + }, + ], + install(app) { + app.provide(AgentKey, registry) + }, + } + registries.set(bridge, registry) + return bridge +} + +/** Scope a bridge to the calling component's subtree instead of the whole app. */ +export function provideAgent(agent: AgentBridge): void { + provide(AgentKey, registries.get(agent)!) +} + +/** + * Register the calling component with the installed agent bridge, if any. + * A no-op when no bridge is installed. + */ +export function useAgentControl(def: AgentControlDefinition): void { + const registry = inject(AgentKey, null) + if (!registry) + return + const instance = getCurrentInstance() + const fieldLabel = inject(FieldLabelKey, null) + const label = (): string | undefined => + def.label?.() + || (instance?.attrs['aria-label'] as string | undefined) + || fieldLabel?.() + || (instance?.props.placeholder as string | undefined) + || undefined + + let unregister: (() => void) | undefined + onMounted(() => { + unregister = registry.register({ ...def, label }) + }) + onBeforeUnmount(() => unregister?.()) +} + +/** + * Throw unless `value` is one of `allowed`. For pick-from-a-list actions, so an + * agent can't set a value the user couldn't pick. + */ +export function assertAgentOption(allowed: unknown[], value: unknown): void { + if (!allowed.includes(value)) + throw new Error(`${JSON.stringify(value)} is not one of: ${allowed.map(v => JSON.stringify(v)).join(', ')}`) +} + +/** Lets `FormField` name the control it wraps. */ +export function provideAgentFieldLabel(label: () => string | undefined): void { + provide(FieldLabelKey, label) +} diff --git a/packages/design/composables/index.ts b/packages/design/composables/index.ts index b0d60fa..8e9729d 100644 --- a/packages/design/composables/index.ts +++ b/packages/design/composables/index.ts @@ -1,3 +1,4 @@ +export * from './agent' export * from './colorScheme' export * from './portalTarget' export * from './toast' diff --git a/packages/design/test/agent.test.ts b/packages/design/test/agent.test.ts new file mode 100644 index 0000000..78238fa --- /dev/null +++ b/packages/design/test/agent.test.ts @@ -0,0 +1,217 @@ +import { mount } from '@vue/test-utils' +import { describe, expect, it, vi } from 'vitest' +import { defineComponent, h, ref } from 'vue' +import FormCheckbox from '../components/Form/FormCheckbox.vue' +import FormCombobox from '../components/Form/FormCombobox.vue' +import FormField from '../components/Form/FormField.vue' +import FormNumberInput from '../components/Form/FormNumberInput.vue' +import FormRadioGroup from '../components/Form/FormRadioGroup.vue' +import FormSearchField from '../components/Form/FormSearchField.vue' +import FormSegmentedControl from '../components/Form/FormSegmentedControl.vue' +import FormSelect from '../components/Form/FormSelect.vue' +import FormSwitch from '../components/Form/FormSwitch.vue' +import FormTextarea from '../components/Form/FormTextarea.vue' +import FormTextInput from '../components/Form/FormTextInput.vue' +import LayoutTabs from '../components/Layout/LayoutTabs.vue' +import { createAgent, getChangeSource } from '../composables/agent' + +function setup(options?: Parameters[0]) { + const agent = createAgent(options) + const state = { + name: ref('Apollo'), + notify: ref(false), + archived: ref(false), + region: ref('us'), + tab: ref('general'), + disabledName: ref('x'), + } + const sources: string[] = [] + const App = defineComponent(() => () => h('div', [ + h(FormField, { label: 'Project name' }, () => h(FormTextInput, { + 'modelValue': state.name.value, + 'onUpdate:modelValue': (v: string) => { + sources.push(getChangeSource()) + state.name.value = v + }, + })), + h(FormSwitch, { 'label': 'Notifications', 'modelValue': state.notify.value, 'onUpdate:modelValue': (v: boolean) => state.notify.value = v }), + h(FormCheckbox, { 'label': 'Archived', 'modelValue': state.archived.value, 'onUpdate:modelValue': (v: boolean) => state.archived.value = v }), + h(FormSelect, { + 'aria-label': 'Region', + 'options': [{ value: 'us' }, { value: 'eu' }, { value: 'ap', disabled: true }], + 'modelValue': state.region.value, + 'onUpdate:modelValue': (v: string | undefined) => state.region.value = v!, + }), + h(LayoutTabs, { + 'aria-label': 'Sections', + 'tabs': [{ value: 'general' }, { value: 'danger' }], + 'modelValue': state.tab.value, + 'onUpdate:modelValue': (v: string | undefined) => state.tab.value = v!, + }), + h(FormTextInput, { placeholder: 'Locked', disabled: true, modelValue: state.disabledName.value }), + ])) + const wrapper = mount(App, { global: { plugins: [agent] } }) + return { agent, state, sources, wrapper } +} + +describe('agent bridge', () => { + it('snapshots instrumented controls', () => { + const { agent } = setup() + expect(agent.snapshot()).toEqual([ + { ref: 'c1', component: 'text-input', label: 'Project name', value: 'Apollo', actions: ['setValue', 'clear'] }, + { ref: 'c2', component: 'switch', label: 'Notifications', value: false, actions: ['setValue', 'toggle'] }, + { ref: 'c3', component: 'checkbox', label: 'Archived', value: false, actions: ['setValue', 'toggle'] }, + { ref: 'c4', component: 'select', label: 'Region', value: 'us', options: ['us', 'eu'], actions: ['setValue'] }, + { ref: 'c5', component: 'tabs', label: 'Sections', value: 'general', options: ['general', 'danger'], actions: ['select'] }, + { ref: 'c6', component: 'text-input', label: 'Locked', value: 'x', disabled: true, actions: ['setValue', 'clear'] }, + ]) + }) + + it('acts through v-model and tags the source', async () => { + const { agent, state, sources, wrapper } = setup() + const { results } = await agent.act({ + steps: [ + { ref: 'Project name', action: 'setValue', args: ['Atlas'] }, + { ref: 'Notifications', action: 'toggle' }, + { ref: 'c3', action: 'setValue', args: [true] }, + { ref: 'Region', action: 'setValue', args: ['eu'] }, + { ref: 'Sections', action: 'select', args: ['danger'] }, + ], + }) + expect(results.every(r => r.ok)).toBe(true) + expect(state.name.value).toBe('Atlas') + expect(state.notify.value).toBe(true) + expect(state.archived.value).toBe(true) + expect(state.region.value).toBe('eu') + expect(state.tab.value).toBe('danger') + expect(sources).toEqual(['agent']) + expect(wrapper.find('input').element.value).toBe('Atlas') + expect(getChangeSource()).toBe('user') + }) + + it('stops at the first failing step', async () => { + const { agent, state } = setup() + const { results } = await agent.act({ + steps: [ + { ref: 'Region', action: 'setValue', args: ['ap'] }, + { ref: 'Notifications', action: 'toggle' }, + ], + }) + expect(results).toHaveLength(1) + expect(results[0]).toMatchObject({ ok: false, error: '"ap" is not one of: "us", "eu"' }) + expect(state.notify.value).toBe(false) + }) + + it('rejects disabled controls, unknown targets, and unknown actions', async () => { + const { agent } = setup() + const errors: (string | undefined)[] = [] + for (const step of [ + { ref: 'Locked', action: 'clear' }, + { ref: 'Nope', action: 'clear' }, + { ref: 'Notifications', action: 'explode' }, + ]) + errors.push((await agent.act({ steps: [step] })).results[0]!.error) + expect(errors).toEqual([ + 'Control "Locked" is disabled', + 'No control "Nope"', + 'Unknown action "explode"; available: setValue, toggle', + ]) + }) + + it('honors the allow guard', async () => { + const allow = vi.fn((step: { action: string }) => step.action !== 'clear') + const { agent, state } = setup({ allow }) + const { results } = await agent.act({ steps: [{ ref: 'Project name', action: 'clear' }] }) + expect(results[0]).toMatchObject({ ok: false, error: 'Rejected by allow()' }) + expect(allow).toHaveBeenCalledWith( + { ref: 'Project name', action: 'clear' }, + expect.objectContaining({ ref: 'c1', label: 'Project name' }), + ) + expect(state.name.value).toBe('Apollo') + }) + + it('exposes snapshot/act as tools', async () => { + const { agent, state } = setup() + const tools = Object.fromEntries(agent.tools().map(t => [t.name, t])) + expect((await tools.ui_snapshot!.execute({}) as unknown[]).length).toBe(6) + await tools.ui_act!.execute({ steps: [{ ref: 'Notifications', action: 'toggle' }] }) + expect(state.notify.value).toBe(true) + }) + + it('unregisters on unmount and is inert without a bridge', () => { + const { agent, wrapper } = setup() + wrapper.unmount() + expect(agent.snapshot()).toEqual([]) + expect(() => mount(FormSwitch, { props: { label: 'x' } })).not.toThrow() + }) +}) + +describe('agent bridge: more controls', () => { + function mountWith(vnode: () => ReturnType) { + const agent = createAgent() + mount(defineComponent(() => () => h('div', vnode())), { global: { plugins: [agent] } }) + return agent + } + + function bound(initial: T) { + const value = ref(initial) + return { value, props: () => ({ 'modelValue': value.value, 'onUpdate:modelValue': (v: T) => value.value = v }) } + } + + it('drives combobox, radio group, segmented control, textarea, and search field', async () => { + const combo = bound(undefined) + const radio = bound('a') + const seg = bound(null) + const notes = bound('hi') + const search = bound('') + const agent = mountWith(() => [ + h(FormCombobox, { 'aria-label': 'Framework', 'options': [{ value: 'vue' }, { value: 'svelte' }], ...combo.props() }), + h(FormRadioGroup, { 'aria-label': 'Plan', 'options': [{ value: 'a' }, { value: 'b' }, { value: 'c', disabled: true }], ...radio.props() }), + h(FormSegmentedControl, { 'aria-label': 'Size', 'options': [{ value: null, label: 'Any' }, { value: 1 }, { value: 2 }], ...seg.props() }), + h(FormField, { label: 'Notes' }, () => h(FormTextarea, notes.props())), + h(FormSearchField, search.props()), + ] as any) + + expect(agent.snapshot().map(c => [c.component, c.label, c.options])).toEqual([ + ['combobox', 'Framework', ['vue', 'svelte']], + ['radio-group', 'Plan', ['a', 'b']], + ['segmented-control', 'Size', [null, 1, 2]], + ['textarea', 'Notes', undefined], + ['text-input', 'Search…', undefined], + ]) + + const { results } = await agent.act({ + steps: [ + { ref: 'Framework', action: 'setValue', args: ['svelte'] }, + { ref: 'Plan', action: 'setValue', args: ['b'] }, + { ref: 'Size', action: 'setValue', args: [2] }, + { ref: 'Notes', action: 'clear' }, + { ref: 'Search…', action: 'setValue', args: ['button'] }, + ], + }) + expect(results.every(r => r.ok)).toBe(true) + expect([combo.value.value, radio.value.value, seg.value.value, notes.value.value, search.value.value]) + .toEqual(['svelte', 'b', 2, '', 'button']) + + const rejected = await agent.act({ steps: [{ ref: 'Plan', action: 'setValue', args: ['c'] }] }) + expect(rejected.results[0]!.ok).toBe(false) + expect(radio.value.value).toBe('b') + }) + + it('clamps and steps the number input like the user path', async () => { + const count = bound(5) + const agent = mountWith(() => h(FormNumberInput, { 'aria-label': 'Count', 'min': 0, 'max': 10, 'step': 2, ...count.props() })) + + await agent.act({ steps: [{ ref: 'Count', action: 'setValue', args: [42] }] }) + expect(count.value.value).toBe(10) + await agent.act({ steps: [{ ref: 'Count', action: 'decrement' }] }) + expect(count.value.value).toBe(8) + await agent.act({ steps: [{ ref: 'Count', action: 'increment' }, { ref: 'Count', action: 'increment' }] }) + expect(count.value.value).toBe(10) + + const { results } = await agent.act({ steps: [{ ref: 'Count', action: 'setValue', args: ['7'] }] }) + expect(results[0]!.error).toBe('"7" is not a number') + await agent.act({ steps: [{ ref: 'Count', action: 'clear' }] }) + expect(count.value.value).toBeUndefined() + }) +}) diff --git a/skills/antfu-design/references/core-components.md b/skills/antfu-design/references/core-components.md index 93ccd31..dacabdd 100644 --- a/skills/antfu-design/references/core-components.md +++ b/skills/antfu-design/references/core-components.md @@ -112,6 +112,15 @@ splitpanes — all themed through the shipped CSS overrides. ## Composables & utils - `@antfu/design/composables` — `useInputFocus`, `provideNotification` / `useNotification`. +- `@antfu/design/composables/agent` — the agent bridge. `createAgent({ allow? })` + + `app.use(agent)` (or `provideAgent(agent)` for a subtree). Then call + `agent.snapshot()` and `agent.act({ steps: [{ ref, action, args }] })`, or use + `agent.tools()` (`ui_snapshot` / `ui_act`). Form controls and `LayoutTabs` + register automatically. Give each control a name: its `label` prop, + `aria-label`, or a wrapping `FormField label`. Use `getChangeSource()` inside + an update handler to tell `'agent'` changes from `'user'` changes. A custom + control can register itself with `useAgentControl({ component, value, actions })`; + use `assertAgentOption()` for pick-from-a-list actions. (Dark mode, clipboard and persisted state are **not** wrapped — use the app's own state and VueUse `useClipboard` / `useLocalStorage` directly.) - `@antfu/design/utils` — `getHashColorFromString`, `getPluginColor`, `labelStyle`
Last change by: {{ lastSource }}
agent.snapshot()
{{ JSON.stringify(snapshot, null, 2) }}
act() results