Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 35 additions & 1 deletion packages/design/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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) |
Expand All @@ -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**:
Expand Down
14 changes: 13 additions & 1 deletion packages/design/components/Form/FormCheckbox.vue
Original file line number Diff line number Diff line change
@@ -1,15 +1,27 @@
<!-- @description a checkbox control bound with `v-model`. -->
<script setup lang="ts">
import { CheckboxIndicator, CheckboxRoot } from 'reka-ui'
import { useAgentControl } from '../../composables/agent'

defineOptions({ inheritAttrs: false })

defineProps<{
const props = defineProps<{
label?: string
disabled?: boolean
}>()

const model = defineModel<boolean>({ default: false })

useAgentControl({
component: 'checkbox',
label: () => props.label,
value: () => model.value,
disabled: () => props.disabled,
actions: {
setValue: (value: boolean) => { model.value = Boolean(value) },
toggle: () => { model.value = !model.value },
},
})
const root = 'outline-none border border-base rounded bg-raised flex h-4 w-4 transition items-center justify-center data-[state=checked]:border-primary-500 data-[state=checked]:bg-primary-500 focus-visible:ring-2 focus-visible:ring-primary-500/40'
</script>

Expand Down
16 changes: 16 additions & 0 deletions packages/design/components/Form/FormCombobox.vue
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
<!-- @description a searchable, filterable select (reka-ui `Combobox`) over an `options` list. -->
<script setup lang="ts">
import { ComboboxAnchor, ComboboxContent, ComboboxEmpty, ComboboxInput, ComboboxItem, ComboboxItemIndicator, ComboboxPortal, ComboboxRoot, ComboboxViewport } from 'reka-ui'
import { assertAgentOption, useAgentControl } from '../../composables/agent'
import { usePortalTarget } from '../../composables/portalTarget'

export interface ComboboxOption {
Expand Down Expand Up @@ -30,6 +31,21 @@ const model = defineModel<string>()

const portalTo = usePortalTarget(() => props.to)

const enabledValues = (): string[] => props.options.filter(o => !o.disabled).map(o => o.value)

useAgentControl({
component: 'combobox',
value: () => model.value,
disabled: () => props.disabled,
options: enabledValues,
actions: {
setValue: (value: string) => {
assertAgentOption(enabledValues(), value)
model.value = value
},
},
})

// reka-ui filters items by their `textValue` against the typed query, so we
// surface the visible label as the search text — this keeps filtering correct
// even when the `#option` slot customises rendering.
Expand Down
6 changes: 5 additions & 1 deletion packages/design/components/Form/FormField.vue
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
<!-- @description wraps a control with a `label`, `description`, and `error` (role="alert"), `required` marker. -->
<script setup lang="ts">
withDefaults(
import { provideAgentFieldLabel } from '../../composables/agent'

const props = withDefaults(
defineProps<{
/** Visible field label. Overridable via the `#label` slot. */
label?: string
Expand All @@ -15,6 +17,8 @@ withDefaults(
}>(),
{},
)

provideAgentFieldLabel(() => props.label)
</script>

<template>
Expand Down
17 changes: 17 additions & 0 deletions packages/design/components/Form/FormNumberInput.vue
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
<script setup lang="ts">
import { clamp } from '@antfu/utils'
import { computed } from 'vue'
import { useAgentControl } from '../../composables/agent'

const props = withDefaults(
defineProps<{
Expand Down Expand Up @@ -34,6 +35,22 @@ function stepBy(direction: number): void {
model.value = bounded((model.value ?? 0) + direction * props.step)
}

useAgentControl({
component: 'number-input',
value: () => model.value,
disabled: () => props.disabled,
actions: {
setValue: (value: number) => {
if (typeof value !== 'number' || Number.isNaN(value))
throw new Error(`${JSON.stringify(value)} is not a number`)
model.value = bounded(value)
},
increment: () => stepBy(1),
decrement: () => stepBy(-1),
clear: () => { model.value = undefined },
},
})

const atMin = computed(() => props.min != null && model.value != null && model.value <= props.min)
const atMax = computed(() => props.max != null && model.value != null && model.value >= props.max)
</script>
Expand Down
17 changes: 16 additions & 1 deletion packages/design/components/Form/FormRadioGroup.vue
Original file line number Diff line number Diff line change
@@ -1,14 +1,15 @@
<!-- @description a radio-button group bound with `v-model`. -->
<script setup lang="ts">
import { RadioGroupIndicator, RadioGroupItem, RadioGroupRoot } from 'reka-ui'
import { assertAgentOption, useAgentControl } from '../../composables/agent'

export interface RadioOption {
value: string
label?: string
disabled?: boolean
}

withDefaults(
const props = withDefaults(
defineProps<{
options: RadioOption[]
orientation?: 'horizontal' | 'vertical'
Expand All @@ -17,6 +18,20 @@ withDefaults(
)

const model = defineModel<string>()

const enabledValues = (): string[] => props.options.filter(o => !o.disabled).map(o => o.value)

useAgentControl({
component: 'radio-group',
value: () => model.value,
options: enabledValues,
actions: {
setValue: (value: string) => {
assertAgentOption(enabledValues(), value)
model.value = value
},
},
})
</script>

<template>
Expand Down
17 changes: 16 additions & 1 deletion packages/design/components/Form/FormSegmentedControl.vue
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
<!-- @description a single-select segmented control (reka-ui `RadioGroup`) over an `options` list, including a valid `null` segment. -->
<script setup lang="ts">
import { RadioGroupItem, RadioGroupRoot } from 'reka-ui'
import { assertAgentOption, useAgentControl } from '../../composables/agent'

export interface SegmentedOption {
/** The value this segment selects. `null` is valid (e.g. an "any"/unset segment). */
Expand All @@ -12,11 +13,25 @@ export interface SegmentedOption {
disabled?: boolean
}

defineProps<{
const props = defineProps<{
options: SegmentedOption[]
}>()

const model = defineModel<string | number | null>()

const enabledValues = (): SegmentedOption['value'][] => props.options.filter(o => !o.disabled).map(o => o.value)

useAgentControl({
component: 'segmented-control',
value: () => model.value,
options: enabledValues,
actions: {
setValue: (value: SegmentedOption['value']) => {
assertAgentOption(enabledValues(), value)
model.value = value
},
},
})
</script>

<template>
Expand Down
16 changes: 16 additions & 0 deletions packages/design/components/Form/FormSelect.vue
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
<!-- @description a native-feeling select bound with `v-model`. -->
<script setup lang="ts">
import { SelectContent, SelectIcon, SelectItem, SelectItemIndicator, SelectItemText, SelectPortal, SelectRoot, SelectTrigger, SelectValue, SelectViewport } from 'reka-ui'
import { assertAgentOption, useAgentControl } from '../../composables/agent'
import { usePortalTarget } from '../../composables/portalTarget'

export interface SelectOption {
Expand All @@ -25,6 +26,21 @@ const props = defineProps<{
const model = defineModel<string>()

const portalTo = usePortalTarget(() => props.to)

const enabledValues = (): string[] => props.options.filter(o => !o.disabled).map(o => o.value)

useAgentControl({
component: 'select',
value: () => model.value,
disabled: () => props.disabled,
options: enabledValues,
actions: {
setValue: (value: string) => {
assertAgentOption(enabledValues(), value)
model.value = value
},
},
})
</script>

<template>
Expand Down
14 changes: 13 additions & 1 deletion packages/design/components/Form/FormSwitch.vue
Original file line number Diff line number Diff line change
@@ -1,13 +1,25 @@
<!-- @description an on/off switch bound with `v-model`. -->
<script setup lang="ts">
import { SwitchRoot, SwitchThumb } from 'reka-ui'
import { useAgentControl } from '../../composables/agent'

defineProps<{
const props = defineProps<{
label?: string
disabled?: boolean
}>()

const model = defineModel<boolean>({ default: false })

useAgentControl({
component: 'switch',
label: () => props.label,
value: () => model.value,
disabled: () => props.disabled,
actions: {
setValue: (value: boolean) => { model.value = Boolean(value) },
toggle: () => { model.value = !model.value },
},
})
</script>

<template>
Expand Down
14 changes: 13 additions & 1 deletion packages/design/components/Form/FormTextInput.vue
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
<!-- @description a single-line text input, `icon`, `invalid` state. -->
<script setup lang="ts">
withDefaults(
import { useAgentControl } from '../../composables/agent'

const props = withDefaults(
defineProps<{
icon?: string
clearable?: boolean
Expand All @@ -15,6 +17,16 @@ withDefaults(
)

const model = defineModel<string>({ default: '' })

useAgentControl({
component: 'text-input',
value: () => model.value,
disabled: () => props.disabled,
actions: {
setValue: (value: string) => { model.value = String(value) },
clear: () => { model.value = '' },
},
})
</script>

<template>
Expand Down
14 changes: 13 additions & 1 deletion packages/design/components/Form/FormTextarea.vue
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
<!-- @description a multi-line text input, `rows`, `invalid` state, `resize` toggle. -->
<script setup lang="ts">
withDefaults(
import { useAgentControl } from '../../composables/agent'

const props = withDefaults(
defineProps<{
placeholder?: string
/** Visible rows. */
Expand All @@ -15,6 +17,16 @@ withDefaults(
)

const model = defineModel<string>({ default: '' })

useAgentControl({
component: 'textarea',
value: () => model.value,
disabled: () => props.disabled,
actions: {
setValue: (value: string) => { model.value = String(value) },
clear: () => { model.value = '' },
},
})
</script>

<template>
Expand Down
17 changes: 16 additions & 1 deletion packages/design/components/Layout/LayoutTabs.vue
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
<!-- @description underline/segment tabs, `count` chips. -->
<script setup lang="ts">
import { TabsContent, TabsIndicator, TabsList, TabsRoot, TabsTrigger } from 'reka-ui'
import { assertAgentOption, useAgentControl } from '../../composables/agent'

export interface TabItem {
value: string
Expand All @@ -13,7 +14,7 @@ export interface TabItem {
disabled?: boolean
}

withDefaults(
const props = withDefaults(
defineProps<{
tabs: TabItem[]
/** `underline` (default) or `segment` (pill switcher). */
Expand All @@ -29,6 +30,20 @@ withDefaults(
)

const model = defineModel<string>()

const enabledTabs = (): string[] => props.tabs.filter(t => !t.disabled && !t.href).map(t => t.value)

useAgentControl({
component: 'tabs',
value: () => model.value,
options: enabledTabs,
actions: {
select: (value: string) => {
assertAgentOption(enabledTabs(), value)
model.value = value
},
},
})
</script>

<template>
Expand Down
5 changes: 5 additions & 0 deletions packages/design/components/Overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand Down Expand Up @@ -447,6 +448,10 @@ A composable, token-driven design system for devtools-style Vue apps. Each tile

## Utility

### [AgentBridge](/?path=/docs/utility-agentbridge--docs)

<Canvas of={AgentBridge.Default} />

### [ScrollFade](/?path=/docs/utility-scrollfade--docs)

<Canvas of={ScrollFade.Vertical} />
Expand Down
Loading
Loading