Schema Editor (VS Code Extension)

The Kalp Schema Editor is a VS Code extension (kalp-schema-editor) that provides a graphical, Guidewire PCF-style screen designer for PolicyOne screens. Open it with Cmd+Shift+P → "Kalp: Open Schema Editor".

All screen definitions live in co-located _screen.meta.ts files next to each page component. The extension reads and writes these files directly. Changes are buffered in memory and only written to disk when you explicitly click Save — there is no auto-save.

Concepts

Interface Overview

Screen Sidebar (left panel)

Lists all _screen.meta.ts files found in apps/policyone/app. Screens are grouped by the first segment of their route (e.g. all /submissions/... screens appear under Submissions). Each entry shows the screen title and a layout badge (wizard, form, detail, list).

Click a screen to select it and load it into the main panel.

Header buttons:

• ↻ Refresh — re-reads all _screen.meta.ts files from disk, discarding any unsaved in-memory edits
• Open File — opens the selected screen's _screen.meta.ts directly in the VS Code editor
• Save Changes — writes the current in-memory state back to the _screen.meta.ts file on disk. A ● dot appears next to "Save Changes" whenever there are unsaved edits.

Preview / Schema Toggle

The header has a two-button toggle:

Preview Mode

Preview mode renders the screen using the same layout rules as the actual app. Click any element to inspect and edit it.

Layout Rendering

Working with Fields

• Select a field — click anywhere on the field wrapper. The inspector panel opens on the right and switches to the Field tab.
• Reorder fields — grab the ⠿ drag handle on the left of any field wrapper and drag it up or down within the same section. Drop position is indicated by a blue line.
• Delete a field — click the ✕ button that appears on the right of the field wrapper (visible on hover).
• Add a field — click the + Add Field button at the bottom of any section. A new text field is appended and immediately selected in the inspector so you can set its properties.

Working with Sections

• Select a section — click the section title bar. The inspector switches to the Section tab.
• Delete a section — click ✕ on the right of the section title bar.
• Add a section — click + Add Section at the bottom of the page content area. Sections are always added to the current step (wizard) or to the flat section list (form/detail).

Interactive Preview Widgets

radio-cards, pill-toggle, and select fields are fully interactive in preview mode — clicking them updates the live visibleFor simulation without a reload (see Live visibleFor Simulation).

Schema (Table) Mode

Schema mode shows all sections as tabs across the top. Each tab renders a table of that section's fields:

Inline editing: click any ID or Label cell to edit it in place. Changes are committed when focus leaves the cell.

Add Field form at the bottom of each section: enter an ID, label, and type and click Add. The new field is appended to the section and the table re-renders.

Inspector Tabs

The inspector panel (right side, Preview mode only) has three tabs:

Field Tab

Click any field in the preview to open this tab.

All changes in the Field tab take effect instantly in the preview and are buffered in memory until saved.

Section Tab

Click a section title bar to open this tab.

⚙ Page Tab

Always accessible — shows screen-level metadata. This tab is the default when no field or section is selected.

Changes on the Page tab update the screen sidebar title immediately.

Field Types

Live visibleFor Simulation

The preview evaluates visibleFor conditions in real time — no reload or save needed.

Syntax:

Both section-level and field-level visibleFor are evaluated. When a condition is not met the section or field is hidden instantly. A ◎ condition badge appears next to the section title or field label to indicate it is conditional.

When you click an interactive field (radio-cards, pill-toggle, select), the selection is recorded and all visibleFor conditions across the entire screen are re-evaluated immediately.

Note: Field values reset to defaults when you switch to a different screen.

Wizard Step Management

In wizard screens the left sidebar shows the step list and supports full CRUD:

The current step indicator in the transaction toolbar (e.g. "Draft · Step 2 of 4") updates automatically as you add, remove, and navigate steps.

Transaction Toolbar

Wizard screens automatically show a color-coded transaction toolbar above the content area. The transaction type is detected from the screen's id:

The toolbar also shows the current step count (e.g. "Draft · Step 1 of 3"). All buttons are display-only in the editor preview — they do not trigger any server action.

Repeater Columns

When a field's type is repeater, the Field inspector shows a Columns editor below the standard properties:

Use + Add to append a column and ✕ to remove one. The preview renders the repeater as a mini inline table with column headers, 2 skeleton data rows, and a disabled "+ Add Row" button.

Save and File Workflow

1. Make edits in the editor (preview or schema view).
2. The Save Changes ● button in the header gets a ● dot indicating unsaved changes.
3. Click Save Changes (or your keyboard shortcut) to write the updated _screen.meta.ts to disk.
4. A success toast confirms the save. The ● dot clears.
5. Click Open File to jump to the raw _screen.meta.ts in the VS Code editor if you need to make changes outside the UI.
6. Click ↻ Refresh to discard all in-memory edits and re-read from disk.

Changes written to disk take effect immediately in the running Next.js dev server — Next.js hot-reloads the updated _screen.meta.ts module automatically.

ScreenMeta File Format

Every screen has a _screen.meta.ts file co-located with its page component:

import type { ScreenMeta } from '@/lib/screen-meta/types'

export const meta: ScreenMeta = {
  id:            'submissions.new',
  title:         'New Submission',
  route:         '/submissions/new',
  layout:        'wizard',
  componentFile: 'app/(shell)/submissions/new/page.tsx',
  serverAction:  'lib/actions/submissions.ts → createSubmission()',
  dataSource:    'packages/db/src/queries/submissions.ts → fetchProductCatalog()',

  steps: [
    {
      id:    'step_policy_type',
      title: 'Policy Type',
      sections: [
        {
          id:     'section_lob',
          title:  'Line of Business',
          fields: [
            {
              id:      'lob',
              label:   'What would you like to insure?',
              type:    'radio-cards',
              options: [
                { value: 'personal_auto', label: 'Personal Auto' },
                { value: 'homeowners',    label: 'Homeowners' },
              ],
            },
            {
              id:         'vehicleCount',
              label:      'Number of vehicles',
              type:       'number',
              visibleFor: 'lob:personal_auto',  // hidden unless lob = personal_auto
            },
          ],
        },
      ],
    },
    {
      id:    'step_named_insureds',
      title: 'Named Insureds',
      sections: [
        {
          id:     'section_drivers',
          title:  'Drivers',
          visibleFor: 'lob:personal_auto',  // entire section hidden for non-auto
          fields: [
            {
              id:      'drivers',
              label:   'Driver list',
              type:    'repeater',
              columns: [
                { id: 'firstName', label: 'First Name' },
                { id: 'lastName',  label: 'Last Name' },
                { id: 'dob',       label: 'Date of Birth', type: 'date' },
                { id: 'license',   label: 'License #' },
              ],
            },
          ],
        },
      ],
    },
  ],
}

Building the Extension

pnpm --filter kalp-schema-editor compile

Output is written to packages/schema-editor/out/. After every change to the extension source, run compile then use "Developer: Reload Window" in VS Code to pick up the new build.

Concepts

Field Types

Inspector Tabs

The inspector panel on the right has three tabs:

Field Tab

Edit the selected field's properties:

Section Tab

Edit the selected section's id, title, description, and visibleFor condition.

⚙ Page Tab

Edit screen-level metadata:

Live visibleFor Simulation

The preview evaluates visibleFor conditions in real time — no reload needed.

• Format: fieldId:value — e.g. partyType:person hides/shows the section or field based on the current radio-card or pill selection in the preview
• OR conditions: comma-separated — e.g. lob:auto,lob:home shows when either condition is met
• Role-based: a bare string with no : (e.g. carrier_admin) is always shown in preview since roles are not simulated

When you click a radio-cards, pill-toggle, or select widget in the preview, the extension instantly hides or reveals sections and fields whose visibleFor condition is or is not met. Both section-level and field-level visibleFor are supported.

Wizard Step Management

In wizard screens, the step sidebar supports full CRUD:

• Add step — click the "+ Add Step" button at the bottom of the step sidebar
• Rename step — double-click the step label to edit it inline; press Enter or Escape to commit/cancel
• Reorder steps — hover a step to reveal ↑ / ↓ arrow buttons
• Delete step — hover a step and click ✕ (the last remaining step cannot be deleted)

Transaction Toolbar

Wizard screens automatically show a color-coded transaction toolbar above the content area based on the screen's id:

The toolbar shows the transaction type chip, current step position (e.g. "Draft · Step 2 of 4"), and contextual action buttons (Save Draft, Quote, Bind / Issue, etc.). These buttons are display-only in the editor preview.

Repeater Columns

When a field's type is set to repeater, the Field inspector shows a Columns editor below the standard properties. Each column has:

The preview renders the repeater as a mini inline table with 2 skeleton rows and a disabled "+ Add Row" button.

ScreenMeta File Format

Every screen has a _screen.meta.ts file co-located with its page component:

import type { ScreenMeta } from '@/lib/screen-meta/types'

export const meta: ScreenMeta = {
  id:            'submissions.new',
  title:         'New Submission',
  route:         '/submissions/new',
  layout:        'wizard',
  componentFile: 'app/(shell)/submissions/new/page.tsx',
  serverAction:  'lib/actions/submissions.ts → createSubmission()',
  dataSource:    'packages/db/src/queries/submissions.ts → fetchProductCatalog()',

  steps: [
    {
      id:    'step_policy_type',
      title: 'Policy Type',
      sections: [
        {
          id:     'section_lob',
          title:  'Line of Business',
          fields: [
            {
              id:      'lob',
              label:   'What would you like to insure?',
              type:    'radio-cards',
              options: [
                { value: 'personal_auto', label: 'Personal Auto' },
                { value: 'homeowners',    label: 'Homeowners' },
              ],
            },
            {
              id:         'vehicleCount',
              label:      'Number of vehicles',
              type:       'number',
              visibleFor: 'lob:personal_auto',  // hidden unless lob = personal_auto
            },
          ],
        },
      ],
    },
  ],
}

Building the Extension

pnpm --filter kalp-schema-editor compile

Output is written to packages/schema-editor/out/. After every change to the extension source, run compile then use "Developer: Reload Window" in VS Code to pick up the new build.