servoy-extra-components

Imported from Servoy/servoy-extra-components (AGENTS.md). Install upstream with npx skills add Servoy/servoy-extra-components. Copyright stays with the author.

AGENTS.md — Servoy Extra Components

Project overview

This repository contains the Servoy Extra Components package — a set of specialized Angular UI components for the Servoy NGClient runtime. Components are built as an Angular library and deployed as a Servoy web package (.zip).

Repository: https://github.com/Servoy/servoy-extra-components Package name: @servoy/servoyextracomponents Current version: 2026.6.0

Technology stack

Working directory

All npm/ng commands must be run from the components/ directory:

cd components

Build commands

Lint & typecheck

npx ng lint

This runs ESLint with the Angular and TypeScript plugins. All rules emit warnings (via eslint-plugin-only-warn), but warnings should still be addressed.

The build (npm run build) performs full TypeScript type checking via ng-packagr. A successful build confirms type correctness.

Testing

Run a specific component's tests:

npx ng test @servoy/servoyextracomponents --no-watch --include "projects/servoyextracomponents/src/<component>/<component>.spec.ts"

Test conventions

• Framework: Vitest (via @angular/build:unit-test)
• Config: angular.json test target + vitest-base.config.ts
• Pattern: **/*.spec.ts
• Each component has a test file alongside its implementation
• Tests use direct TestBed.createComponent(TheComponent) pattern
• Use fixture.componentRef.setInput('name', value) for signal inputs
• Use NO_ERRORS_SCHEMA to suppress unknown directive warnings
• Import ServoyPublicTestingModule from @servoy/public
• DO NOT import ServoyExtraComponentsModule in tests (causes dependency issues)

Critical: Global Mocking Rules

• NEVER use vi.stubGlobal('document', ...) or vi.stubGlobal('window', ...) — this replaces the entire jsdom DOM and breaks ALL subsequent tests in the same fork/thread. The error manifests as this.doc.querySelector is not a function in Angular's renderer.
• Instead, mock individual methods and restore them:

  let originalMethod: typeof document.elementFromPoint;
  beforeEach(() => {
    originalMethod = document.elementFromPoint;
    document.elementFromPoint = vi.fn() as any;
  });
  afterEach(() => {
    document.elementFromPoint = originalMethod;
  });

• Similarly, never replace window.location, window.navigator etc. via stubGlobal — use vi.spyOn or direct property assignment with restore.

Debugging: Log First, Fix Later

When facing unclear test failures (locally or on CI), do NOT spend multiple rounds guessing root causes. Instead:

1. Add diagnostic logging immediately — log the state of the failing object (e.g. typeof, constructor.name, Object.keys(), JSON.stringify) at the point of failure
2. Run (or push and let CI run) — get real data from the actual environment
3. Fix based on evidence — one log statement that shows actual state is worth more than three speculative fixes

Architecture

Dual-layer component structure

Each component exists in two layers that must stay in sync:

Layer 1 — Servoy Spec (components/<name>/):

• <name>.spec — JSON file defining the Servoy component contract (model properties, handlers, API methods, custom types). This is NOT a test file.
• <name>.js / <name>.html / <name>.css — Legacy AngularJS implementation
• <name>_server.js — Optional server-side scripting
• Icons (.png, @2x.png variants)

Layer 2 — Angular Implementation (components/projects/servoyextracomponents/src/<name>/):

• <name>.ts — Angular component class
• <name>.html — Angular template
• <name>.spec.ts — Vitest component test

Components

collapse, dbtreeview, fileupload, gauge, htmlarea, imagelabel, lightboxgallery, multifileupload, select2tokenizer, sidenav, slider, spinner, splitpane, table, textfieldgroup, treeview, youtubevideoembedder

Angular component conventions

• Signal-based inputs: myProp = input<string>() — NOT @Input()
• Signal-based outputs: onAction = output<Event>() — NOT @Output()
• Change detection: ChangeDetectionStrategy.OnPush on every component
• Base class: Extend ServoyBaseComponent<HTMLDivElement> from @servoy/public
• Standalone: false — all components declared in ServoyExtraComponentsModule
• Selector prefix: servoyextra- (kebab-case, enforced by ESLint)
• Directive selector prefix: servoyextra (camelCase)

Module registration

When adding a new component:

1. Declare in servoyextra.module.ts
2. Export in public-api.ts
3. Create Servoy .spec file in components/<name>/

Code style

• Single quotes (enforced by @stylistic/ts/quotes)
• Max line length: 200 characters
• Brace style: 1TBS (if (x) {)
• Static readonly properties: UPPER_CASE
• No component class suffix required (@angular-eslint/component-class-suffix: off)
• No console.log in production code
• Use @servoy/public utilities and lodash-es — don't reinvent

Key dependencies

Project structure

servoy-extra-components/
├── AGENTS.md                            # This file
├── README.md                            # Basic setup instructions
├── webpackage.json                      # Servoy package manifest & release history
├── components/                          # Main working directory
│   ├── opencode.json                    # opencode configuration
│   ├── angular.json                     # Angular workspace config
│   ├── package.json                     # npm dependencies & scripts
│   ├── tsconfig.json                    # Root TypeScript config (strict)
│   ├── .eslintrc.json                   # ESLint config
│   ├── vitest-base.config.ts            # Vitest configuration (deps.inline workarounds)
│   ├── scripts/build.js                 # Release packaging (creates .zip)
│   ├── projects/
│   │   ├── servoyextracomponents/       # Angular library
│   │   │   ├── ng-package.json          # ng-packagr config
│   │   │   ├── tsconfig.lib.json        # Library TS config
│   │   │   ├── tsconfig.lib.prod.json   # Production TS config
│   │   │   ├── tsconfig.spec.json       # Test TS config
│   │   │   └── src/
│   │   │       ├── public-api.ts        # Library exports
│   │   │       ├── servoyextra.module.ts # NgModule declarations
│   │   │       ├── testingutils.ts      # Test utilities
│   │   │       └── <component>/         # Angular component implementation
│   │   └── dummy/                       # Dummy app (dev/testing scaffold)
│   ├── <component>/                     # Servoy spec + legacy files (per component)
│   ├── dist/                            # Build output (gitignored)
│   └── node_modules/                    # Dependencies (gitignored)
├── servoyExtraComponentExample/         # Example Servoy solution
└── .opencode/                           # opencode skills & plugins
    ├── skills/sdd/                      # Spec-Driven Development pipeline
    └── plugins/commit-lint.ts           # Commit message validation

Workflow

Post-edit checklist

After making code changes, always verify:

1. npm run build — must compile without errors
2. npm run lint — check for lint warnings
3. Run relevant tests: npm run test or target a specific component
4. If package.json dependencies were changed, verify distribution package is in sync: compare components/package.json dependencies with components/projects/servoyextracomponents/package.json peer/dependencies

Commit message format

<JIRA_KEY> <short description> [ai]

- bullet points summarising changes

Co-Authored-By: opencode <noreply@opencode.ai>

Example: SVY-21080 add sidenav collapse animation support [ai]

Adding a new component

1. Create the Servoy spec directory: components/<name>/
   • <name>.spec (JSON component contract)
   • <name>.js, <name>.html, <name>.css (legacy implementation)
   • Icon files (.png, @2x.png)
2. Create Angular implementation: components/projects/servoyextracomponents/src/<name>/
   • <name>.ts (component class)
   • <name>.html (template)
3. Register in servoyextra.module.ts (declarations + exports)
4. Export in public-api.ts
5. Create Vitest test: <name>.spec.ts
6. Build and verify: npm run build

Modifying a component

When changing component properties, handlers, or API:

1. Update the .spec file (JSON contract) in components/<name>/
2. Update the Angular component in projects/servoyextracomponents/src/<name>/
3. Both layers must stay in sync

Spec property tags: serveronly

• If a spec property is handled only on the server (not sent to the client, no @Input in Angular), add "tags": { "serveronly": true } to its definition.
• The serveronly tag prevents the property from being generated in the Angular template AND from being sent over the websocket.
• Every spec model property MUST have a corresponding @Input (signal input) in the Angular component, unless it is tagged serveronly.
• When adding or modifying spec properties, always verify this alignment.

Gotchas

• .spec files are NOT tests. They're Servoy component specification JSON files.
• Signal inputs, not decorators. Use input<T>() / output<T>(), not @Input() / @Output().
• Signal inputs with defaults: Servoy form templates bind ALL model properties ([prop]="model.prop"). If the server never sends a value, the expression evaluates to undefined, overriding input(30). Use a transform to preserve defaults:

  readonly pane1MinSize = input(30, { transform: (v: any) => v ?? 30 });

• OnPush everywhere. All components use ChangeDetectionStrategy.OnPush.
• @servoy/public version coupling. Must match the target Servoy runtime version.
• Legacy files still active. The AngularJS files in top-level dirs are still used by older Servoy runtimes. Don't delete them.
• No standalone components. All are standalone: false, declared in the shared module.

Cross-Session Knowledge

At the start of a new session, list stored memory keys (memory_listMemories) to discover reusable migration patterns, conventions, and lessons learned from previous sessions on Servoy Angular projects.