Skip to content
daguanren21Public

About

面向 H5 与微信小程序的 Vue/Wevu 组件系统、Headless primitives 与 AI Agent UI

Topics

Resources

Stars

3 stars

Watchers

0 watching

Forks

Latest commit

 

History

215 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Varo

English | 简体中文

Documentation · DeepWiki · GitHub Release · npm organization

Varo provides components and Blocks for Vue 3 mobile H5 applications and weapp-vite mini programs. Install source for your target through the Registry, then edit and maintain it in your application.

Published packages

  • @varo-ui/cli — installs editable Registry source for the selected deployment profile
  • @varo-ui/headless — framework- and DOM-neutral state machines, events, controlled-state contracts, and utilities
  • @varo-ui/h5 — tree-shakeable Vue components for mobile H5 products
  • @varo-ui/weapp — native Wevu .vue source and a resolver for the weapp-vite compiler, not a Vue render runtime
  • @varo-ui/theme — shared theme tokens and providers
  • @varo-ui/ai — safe Markdown models, text pacing, and thread-version helpers; chat state and transport come directly from TanStack AI

Current capabilities

  • H5 components: styled Vue components and DOM primitives, with editable Registry source
  • Native components: target-specific Wevu SFCs; npm and Registry installations derive from the same authored source
  • Agent Core: safe incremental Markdown AST, Markstream text pacing on H5, timed-frame text pacing on mini programs, and thread-version helpers only
  • Agent UI: conversation, workspace, advanced, and RAG source units plus Agent Chat and Agent Workspace Blocks for scoped context, retrieval, tasks, thread versions, streaming, tools, approvals, code, diffs, citations, media, tables, and workflows
  • Dual-target Blocks: Login Form, Profile Card, Profile Edit, Product List, Order Filter, Agent Chat, and Agent Workspace
  • AI commerce demo: explicitly local TanStack AG-UI streams, reasoning and tool presentation, purchase/return approval UI, order history, and address configuration; not a live provider integration
  • Renderer families: h5 and weapp; deployment profiles are listed below
  • Mini-program styling: Tailwind CSS v4, weapp-tailwindcss, and @weapp-tailwindcss/merge
  • Mini-program debugging: built-in MCP, DevTools console bridge, Automator screenshots, and runtime smoke checks

Product boundary

  • The core Weapp Registry components draw on features shared by Vant Weapp, NutUI, TDesign Mobile Vue, and TDesign MiniProgram.
  • Motion and Agent interaction patterns reference Beautiful UI and beUI, while production code remains native to Vue and mini-program runtimes.
  • A component's supported platforms are declared in its registry/**/registry.json manifest and those of all its dependencies. An H5 catalog entry or browser example does not establish native support.
  • TanStack AI owns AG-UI events, active messages, stream state, and aborts. H5 uses @tanstack/ai-vue; native uses @tanstack/ai-client with Wevu. Varo's Markdown and text pacing are presentation-only: H5 uses Markstream Core, while mini programs use the same safe AST with timed scheduling independent of requestAnimationFrame.
  • registry/component-tiers.v0.1.json records product tiers. The manifests and profile table in packages/registry/src/index.ts determine which platforms an installation supports.

Source ownership

Write components in registry/components/**, Blocks in registry/blocks/**, and styles in registry/themes/**. Run pnpm sync:registry to generate packages/ui-h5/src, packages/ui-weapp/native, playground copies, and the docs Agent source and support catalog. Make changes in the Registry source; generated files should not be edited directly.

packages/shared defines the shared ReactiveRuntime interface. @varo-ui/headless provides framework- and platform-neutral interaction logic. H5 handles DOM rendering, focus, and body-scroll locking; native SFCs use the headless logic through wevu, without Vue render primitives.

themes/base contains tokens and foundation rules. Each component's manifest declares its CSS; Agent tokens and helpers come from the optional themes/agent dependency. H5 source imports all CSS needed by the component and its dependencies. Native apply-shared components load those styles through the application stylesheet.

Deployment profiles

Install target Renderer Compiler platform Host / maturity
h5 h5 Browser build Browser / stable
weapp weapp weapp WeChat mini program / stable
alipay weapp alipay Alipay mini program / experimental
tt weapp tt Douyin mini program / experimental
xhs weapp xhs Xiaohongshu mini program / experimental
donut-android weapp weapp Donut Android / experimental
donut-ios weapp weapp Donut iOS / experimental
donut-ohos weapp weapp Donut OpenHarmony / experimental

To install one of the six experimental profiles, the selected components and every dependency must explicitly support it. If any item does not, the CLI fails before writing files instead of falling back to Weapp. Representative supported components are button, input, input-otp, form, checkbox, switch, drawer, card, and icon, with their required utilities and themes. Check the manifests for the exact list. This does not certify the full catalog or Agent UI on those platforms.

Native AI clients enable the Web Runtime configuration: weapp.appPrelude.webRuntime: { enabled: true, networkDefaults: { request: { enableChunked: true } } }. Use TanStack's standard fetch adapter, not a bespoke wx.request transport. Streaming requires real status, headers, and incremental chunks from the host. Donut uses the WeChat compiler and selects its host through mini-android, mini-ios, or mini-ohos metadata, not a separate compiler target. See runtime evidence limits for SDK, IDE, AppID, signing, and device requirements.

Install editable source

# Native mini-program SFCs
pnpm dlx @varo-ui/cli add --target weapp button input card

# H5 source
pnpm dlx @varo-ui/cli add --target h5 button input card

# Experimental profile: only explicitly admitted source
pnpm dlx @varo-ui/cli add --target alipay button input input-otp form checkbox switch drawer card

# Dual-target business Block
pnpm dlx @varo-ui/cli add --target weapp blocks/product-list

# Dual-target Agent Chat Block
pnpm dlx @varo-ui/cli add --target weapp blocks/agent-chat
pnpm dlx @varo-ui/cli add --target h5 blocks/agent-chat

# Deliberately install the full Agent UI suite
pnpm dlx @varo-ui/cli add --target weapp components/agent-ui
pnpm dlx @varo-ui/cli add --target h5 components/agent-ui

# High-consensus mini-program components
pnpm dlx @varo-ui/cli add --target weapp action-sheet collapse dialog list notice-bar popover skeleton steps

Install the npm dependencies listed by the CLI yourself. Existing files are kept by default. Review local customizations before using --force, which replaces files without merging your changes.

For native source installs, load every installed src/styles/*.css file globally using weapp.styles entries with include: 'app.vue', with varo.css first. Do not import these global styles from component-local WXSS: page tokens and global selectors do not belong there. Native npm consumers put @import "@varo-ui/weapp/style.css"; in local src/package.css and register { source: 'package.css', include: 'app.vue' } globally, not an absolute package path. See the native package setup and apps/platform-smoke/vite.config.mjs.

API and runtime contracts

  1. Native rendering: @varo-ui/weapp exports native SFCs compiled by Wevu/weapp-vite, not Vue render functions. Direct imports such as @varo-ui/weapp/components/v-button.vue are supported. @varo-ui/weapp/resolver resolves locally installed Registry SFCs; there is no @varo-ui/weapp/primitives entry.
  2. H5 imports: use @varo-ui/h5 or @varo-ui/h5/primitives. For editable code, install Registry source. @varo-ui/h5/style.css and the CSS-only @varo-ui/h5/source/style.css are public; @varo-ui/h5/source is not a TypeScript entry.
  3. Neutral behavior: import state/form contracts from @varo-ui/headless; useBodyScrollLock belongs to @varo-ui/h5/primitives in H5 code only. Do not emulate DOM locking on native hosts. Form submit/failed handlers receive SubmitPayload (FormSubmitPayload in form source exports), containing values, errors, and optional platform-specific event, not a raw DOM event.
  4. Styles: themes/base contains tokens and foundation rules, not all component/Agent styles. Load the complete dependency CSS closure using the native global rule above; H5 installed source imports its dependency styles.
  5. Agent installs: choose components/agent-conversation, components/agent-workspace, components/agent-advanced, or components/agent-rag as needed. components/agent-presentation owns pure shared types/helpers. blocks/agent-chat selects conversation dependencies, not advanced/RAG/fine-tuning UI; components/agent-ui deliberately selects the full suite. Approval, network, retry, and cancellation execution policy remains application-owned.
  6. Agent SDK: import UIMessage / AG-UI chunks from @tanstack/ai, ChatClientSnapshot / ChatClient from @tanstack/ai-client, and H5 useChat from @tanstack/ai-vue. Varo provides no private protocol, stream controller, channel, SSE decoder, or event parser. Snapshot props take the actual SDK snapshot; static history uses AgentConversationMessage[]. AgentPartStatus, AgentStreamStatus, and AgentToolPart live in installed components/agent-ui/types and describe display only, not SDK states (ready, submitted, streaming, error). Renderer approval/rejection events carry interrupt IDs: the application resolves the matching tool-approval from client.getInterrupts() with true / false. Business authorization and execution remain application-owned. See the AI integration guide.

Input rejects edits while disabled or readonly. It notifies once when a value changes and sends no change event when the value stays the same. Cancel Drawer openChange synchronously in the handler to prevent the subsequent state change, model update, and close notification.

Playground

pnpm dev:playground-h5
pnpm --filter @varo/playground-weapp dev:ai

dev:ai prepares the WeChat DevTools project, starts the MCP HTTP service, and forwards DevTools console output and uncaught errors to the active terminal.

Native Blocks used only by blocks-lab are generated in apps/playground-weapp/src/blocks-lab/components/blocks/. Shared UI, Agent components, and helpers stay in the main source tree. pnpm sync:registry handles these paths and import changes; public Registry installations still use src/components/blocks/. The production build rejects a main package above 2 MiB or a synchronous reference to an unavailable sibling subpackage.

After native compilation, localize-native-components.mjs places subpackage-only component artifacts beside their consumers while keeping shared scripts and assets at their existing paths. CSS url(...) and quoted or URL-form @import references are decoded before resolving files and escaped when rebased, including CSS hexadecimal escapes, spaces, quotes, parentheses, and query/hash suffixes. External and data URLs retain their spelling. Missing dependencies and destination conflicts reject before any compiler output is changed; the production and exported-starter style verifiers use the same CSS reference parser.

Documentation development

pnpm run docs:dev

This starts VitePress at http://localhost:5173 and prepares the native preview artifacts. The H5 and Mini Program tabs share device framing, example cases, language, and theme. Mini Program examples run compiled Wevu SFCs through glass-easel; their editable source remains available under View code. H5-only components retain explicit platform support boundaries.

For native slot context on WeChat, enable weapp.vue.template.nativeSlotContext: true and scopedSlotsRequireProps: true with default attached setup. Preview and headless observation limits are documented in the installation guide.

Verification

pnpm sync:registry
pnpm check:generated
pnpm check:architecture
pnpm typecheck
pnpm test
pnpm build
pnpm check:consumers
pnpm check:platforms
  • sync:registry generates files; check:generated checks for drift, including obsolete outputs in scripts/registry-projections.json, without writing. Sync deletes obsolete files only if their bytes match the recorded digest. If an obsolete output was edited, or a new output path conflicts with an authored file, that generator fails before writing. Authored renderers receiving style imports are never deleted. Preflight applies per generator, without a transaction across all three scripts or disk-failure rollback. Do not run writers concurrently or delete the inventory to bypass conflicts.
  • check:architecture checks imports between shared logic, runtime code, and tooling, rejecting old Vue-native renderer imports.
  • After generation and builds, check:consumers checks packed packages and fresh CLI installations in isolated projects: dependency/entrypoint isolation, H5/native compilation, complete source/style dependencies, minimal Agent Chat installs, and profile roundtrips with rejection of unsupported profiles. It does not run devices.
  • check:platforms builds and checks seven native profiles. Use pnpm --filter @varo/platform-smoke build:alipay for one platform; verify:alipay checks existing artifacts.
  • test:e2e:runner checks runner gates and native locator semantics. aria-hidden excludes nodes and descendants from role queries without hiding their pixels or blocking explicit XPath actions; visually hidden and disabled controls remain non-actionable.
  • Native custom-event listeners must preserve the declared event spelling, such as @update:modelValue. Wevu normalizes colon events to lowercase with : replaced by -; adding a hyphen inside modelValue changes the event name and prevents the model update.

Native artifacts are in apps/platform-smoke/.generated/<profile>/dist/<compilerPlatform>, with application files in the nested dist/. Checks cover component references, templates and events, complete global styles, IDE paths, and Donut host metadata. To use open:<profile>, supply a registered AppID and vendor tools; missing prerequisites fail the command.

Realworld creates its manager with createAedPinia() in src/store/manager.ts. Install it before creating stores: call use(pinia) in native app.vue or createApp({}).use(manager) in local consumers. Through $subscribe, the plugin persists only the AED store in realworld-weapp-state format, including nested updates. Navigation data stays transient; disposing the store or manager releases subscriptions. Keep this configuration for persistence, rather than a setup-local deep watch or bare createPinia(). Local checks do not run wx.login, update checks, or device launch.

Use the Node and pnpm versions declared in the root package.json (engines and packageManager). Manifests and the lockfile record tooling versions.

Workspace test scripts explicitly select the shared root configuration and restrict discovery to the current package. The Weapp playground selects its native-SFC test configuration with jsdom; the standalone Realworld app uses its local configuration.

H5 uses vite-plugin-dts bundleTypes with an explicit @microsoft/api-extractor dependency so both published type entrypoints include their bundled private workspace types rather than referencing monorepo source paths.

See RELEASING.md for the repoctl, npm OIDC, and documentation deployment workflow.

About

面向 H5 与微信小程序的 Vue/Wevu 组件系统、Headless primitives 与 AI Agent UI

Topics

Resources

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages