xcs-horizontal-builder

Vue 3 horizontal condition builder packaged as a web component (<xcs-horizontal-builder>). Feature UI is built with Vue SFCs; Apollo Core (@xplortech/apollo-core) provides Stencil xpl-* primitives, wrapped in this repo by thin Apollo*.vue components.

Documentation map

| Doc | Contents | |-----|----------| | This README | Setup, Node requirements, install, build, test (Vitest, Cypress E2E only — no Cypress component runner), lint / lint:check, format / format:check, IDE pointers, troubleshooting (npm ci, Node), links to .nvmrc and editor config. | | AGENTS.md | Directory structure (per-path roles), architecture and design patterns (Vue 3, Vite, web component build, Apollo Core integration), coding conventions beyond editor files, and full npm scripts. | | CONTRIBUTING.md | How to contribute, editor expectations, quality checks before PRs. | | RELEASING.md | How to publish releases to npm: version management, npm release workflow triggers, OIDC authentication setup, and troubleshooting. | | CHANGELOG.md | Package release notes for @xplortech/xhb-embed (including TypeScript types for host embeds). |

Repository layout (overview)

| Path | Purpose | |------|---------| | src/ | Application source: components, Apollo xpl-* wrappers (src/components/lib/), API client, utils, types; src/index.ts is the web component library entry. | | tests/ | Vitest specs, setup, and test helpers (unit and component-level tests in Vue/jsdom). | | e2e/ | Cypress E2E specs (*.cy.ts), support, helpers, and fixtures (cypress.config.ts at repo root). | | mocks/ | Shared mock data for Vitest. | | demo/ | Demo page for the built custom element bundle. | | docusaurus/ | Docs site npm workspace. |

Full breakdown: AGENTS.md → Directory structure.

Prerequisites

• Node >=24.10.0 — enforced in package.json → engines. [.nvmrc](./.nvmrc) is set to lts/krypton so local installs align with the expected LTS line when you run nvm use.
• @xplortech packages may need registry/auth per your organization.

Project setup

npm install

Cypress binary (E2E only)

End-to-end tests use Cypress. The binary is installed automatically via the prepare script after npm install; if needed, run:

npm run prepare

Build, test, and lint

| Command | Description | |--------|-------------| | npm run dev | App shell dev server (Vite). | | npm run build | type:check + production Vite app build. | | npm run build:wc | type:check + web component library build (dist/). | | npm run build:wc:demo | Build WC and run demo (vite.demo.config.ts). | | npm run preview | Preview an existing production build (port 4173). | | npm run type:check | Vue/TS project type-check (vue-tsc --build). | | npm run test | Vitest (single run). | | npm run test:unit | Vitest (watch mode). | | npm run test:coverage | Vitest with v8 coverage (thresholds in vitest.config.ts). | | npm run test:e2e | Cypress E2E (headless): vite build, then vite preview on 4173, then cypress run --e2e. | | npm run test:e2e:dev | Cypress E2E (interactive): Vite dev on 4173 + cypress open --e2e. | | npm run lint | ESLint with auto-fix (--fix --cache). | | npm run lint:check | ESLint without fix — fails on issues; use in CI or to verify a clean tree (--max-warnings=0). | | npm run format | Prettier write on src/. | | npm run format:check | Prettier check only (-c) — no file changes; use in CI. | | npm run docs:dev / docs:build | Docusaurus workspace (see docusaurus/). |

IDE and editor conventions

• VS Code — Install Vue (Volar); disable Vetur if present. Optional: Vue DevTools for the app shell.
• Repo-wide editor rules — .editorconfig (charset, indent, EOL, trim, newline).
• VS Code workspace defaults — .vscode/settings.json (format on save, Prettier as default formatter, ESLint code actions).
• Suggested extensions — .vscode/extensions.json (Volar, Vitest, ESLint, EditorConfig, Prettier).

Vue/TS formatting in committed source follows Prettier (.prettierrc.json) and ESLint (eslint.config.ts); see AGENTS.md → Coding conventions.

Troubleshooting

npm ci fails (lockfile / workspace)

The root package-lock.json must include all npm workspaces (e.g. docusaurus). If npm ci errors such as a package “missing from lock file”, run npm install at the repo root (Node 24+ per engines, plus GitHub/auth for @xplortech if required), then commit the updated package-lock.json. Retry npm ci.

Build, lint, or tests fail unexpectedly

1. Check Node: node -v must match engines in package.json. With nvm: nvm use (reads .nvmrc).
2. Reinstall deps: rm -rf node_modules && npm install.
3. Run npm run type:check and npm run lint for actionable errors.

Vite / Vue configuration

Vite config reference. This repo sets @ → src/, client env prefix XCS, and treats xpl-* as custom elements in vite.config.ts. Details: AGENTS.md.