@skyledge/widget-api

TypeScript types for building widgets and web components that run inside Sky Ledge Control Rooms: the widget context, the skyledge host API, the slc-* elements and the domain models they use.

The package contains types only, so import it with import type.

Using it in a widget repo

npm install --save-dev @skyledge/widget-api        # types for what production runs
npm install --save-dev @skyledge/widget-api@next   # types for what staging runs

import type { PopupView, WidgetContext, WidgetSkyledgeInterface } from '@skyledge/widget-api';

export async function loadAssets(context: WidgetContext<PopupView>, skyledge: WidgetSkyledgeInterface) {
  return skyledge.api.queryAssets(context.controlRoomId ?? '', { filters: [], page: 0, size: 20 });
}

The package also declares the slc-* elements on HTMLElementTagNameMap and the global JSX.IntrinsicElements. In a Stencil project, add them to Stencil's JSX namespace:

import type { SkyLedgeIntrinsicElements } from '@skyledge/widget-api';

declare module '@stencil/core' {
  export namespace JSX {
    interface IntrinsicElements extends SkyLedgeIntrinsicElements {}
  }
}

Depend on ^1.x normally: it follows production and never picks up next prereleases. Use @next only while building against a host feature that is on staging, and don't ship that widget to production until Control Rooms production has the feature. The types are compile-time only, so a widget calling a host API production doesn't have yet fails at runtime.

How releases work

The package is released alongside Control Rooms, following the same branch-to-environment mapping:

| In control-rooms | Control Rooms | @skyledge/widget-api | | ----------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | PR opened | Tests run | If the PR touches the contract, a check builds the package and comments the API diff with a suggested version bump. Nothing is published. | | Merged to main | Deploys to staging | Publishes x.y.z-next.N under next if the types changed. | | main merged to production | Deploys to prod | Publishes x.y.z under latest if the types changed. | | Pushed to dev | Deploys to dev | Nothing is published. |

So next always describes what staging runs and latest what production runs. Nothing is published when a build or deploy fails, or when a merge doesn't change the public types.

Version numbers

The x.y.z in a next prerelease is the version production will release. It's a patch bump unless a PR merged since the last prerelease has [widget-api:minor] or [widget-api:major] in its title. A release cycle looks like this:

| Event | Published | | ----------------------------------------------------------------- | -------------------------------------- | | PR adds a new host API, [widget-api:minor] in its title, merged | 1.1.0-next.0 under next | | Another PR fixes a type, no marker, merged | 1.1.0-next.1: the target stays 1.1.0 | | main → production | 1.1.0 under latest | | Next merge to main that changes the types | 1.1.1-next.0 or higher: a new cycle |

Production releases the version of the prerelease with exactly the same types, so a release never claims changes that are only on staging. A production hotfix with types no prerelease had is released as a patch.

Changing the contract

The types are written in the Control Rooms web app, mostly in webapp/web/src/app/core and webapp/web/src/app/web-components. src/index.ts lists what widget authors can import; everything those exports reference is included automatically.

1. Change the types in the web app. If widgets need to import a new type by name, export it from src/index.ts.
2. Run npm run check here (see Local setup).
3. Open the PR. The widget-api comment shows the API diff and suggests a bump: add [widget-api:minor] to the PR title for additions, or [widget-api:major] for breaking changes. For example feat(widgets): add queryTrips [widget-api:minor]. Put it in the title before merging; no marker means a patch.
4. Merge. Staging gets the prerelease, and production gets the release when main is deployed to production.

npm run check fails with one of these messages when the contract needs fixing:

| Message | Fix | | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | | imports '<package>', which widget authors don't have | A contract type uses an app-only type, often from Angular. Replace it with a type the contract owns. | | '<Name>' is used by the API but not exported | Export it from src/index.ts. | | '<Name>' collides with another type | Two app modules export the same name. Re-export one under a module-specific alias, like ControlRoomDateFilter and CycleDateFilter. | | consumer type-check failed | The types don't compile in a strict widget project; the TypeScript errors above it say where. |

Local setup

Run npm ci in webapp/web and in packages/widget-api: the build compiles the app's source files, so it needs the app's dependencies. Then, from packages/widget-api:

| Script | What it does | | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | npm run check | Builds dist/index.d.ts and runs every check CI runs | | npm run api-diff | Shows the API diff against next, as in the PR comment | | npm run release -- --channel next | Shows the version CI would publish from this build (--channel latest for production) | | npm run sync-local -- <consumer-dir> | Copies a local build into a widget repo's node_modules, e.g. ../../../skyledge-official-web-components/fleets |

Where things live

| Path | Purpose | | ------------------------------------------ | -------------------------------------------------------------------------------- | | packages/widget-api/src/index.ts | The public API | | packages/widget-api/scripts/ | Build checks, API diff, version rules and packing (release.mjs) | | packages/widget-api/test/ | Version-rule tests and the strict consumer project | | .github/workflows/test-widget-api.yml | The PR check and diff comment, called from pr.yml | | .github/workflows/publish-widget-api.yml | Picks the version, packs and publishes; called from ci-cd.yml after the deploy |

Publishing uses npm trusted publishing, so CI holds no npm token. On npmjs.com the trusted publisher is GitHub Actions, repository skyledge/control-rooms, workflow ci-cd.yml, environment npm-publish; that GitHub environment only allows the main and production branches.