Skip to main content

UI SDK and panel bridge

A custom panel is a sandboxed-web component with HTML and bundled assets. Glixo injects window.glixoExtension into the installed surface. Your panel uses that bridge to receive theme/locale and invoke its declared actions; the action's WebAssembly component performs protected operations. Custom panels are Preview on Windows and unavailable on Linux/mobile.

Get the UI helpers

The @glixo/extension-ui helper is not published on npm. Its public source is included in SDK source and UI download under references/accessible-theme/src/, with theme.ts, components.ts, index.ts and extension-ui.css. Copy these to your panel's source folder and bundle them into the web artifact using your frontend compiler. Use local imports, not an unavailable npm package. The public index exports theme functions and custom elements.

The complete Accessible Theme HTML is self-contained and can run without those helpers. Start with the panel tutorial and download for the manifest, Save action, tests, signing and installation. Declare each bundled file as required by that manifest; a source .ts file is not executable browser JavaScript.

Bridge API

Property or method Meaning
theme Readonly host theme values. Updates arrive as glixo-theme events.
locale Host language; updates arrive as glixo-locale.
styleNonce Host-provided style nonce for panel styling; it is not permission or a secret.
ready(): Promise<Record<string,unknown>> Acknowledge the bridge after host initialization. Catch failure and keep actions disabled.
invoke(actionId,payload?): Promise<Record<string,unknown>> Invoke a declared action with JSON object input. Glixo checks surface/action permissions and input schema.

Source: public bridge type and helpers. A normal browser preview has no bridge. Show an explanatory status and disable protected buttons when window.glixoExtension is missing. The browser cannot manufacture an approved workspace or credential handle.

Initialize and invoke

With the extracted helpers in src/glixo-ui/, use a panel entry module like this:

import { installGlixoExtensionUi, connectTheme, invoke }
  from './glixo-ui/index.js';

installGlixoExtensionUi();
const disconnect = connectTheme();
const save = document.querySelector<HTMLButtonElement>('#save')!;
const status = document.querySelector<HTMLOutputElement>('#status')!;
const host = window.glixoExtension;
save.disabled = true;

if (!host) {
  status.textContent = 'Open this installed panel in Glixo.';
} else {
  window.addEventListener('glixo-theme', () => {
    void host.ready().then(() => {
      save.disabled = false;
      status.textContent = 'Connected.';
    }).catch(() => { status.textContent = 'The bridge could not connect.'; });
  }, {once: true});
}

save.addEventListener('click', async () => {
  save.disabled = true;
  try {
    const result = await invoke('save-preferences', {
      accent: '#10b981', largeControls: false,
    });
    status.textContent = result.completed === true ? 'Saved.' : 'Action completed.';
  } catch {
    status.textContent = 'The preference could not be saved.';
  } finally {
    save.disabled = !host;
  }
});
window.addEventListener('pagehide', disconnect, {once: true});

The HTML needs <button id="save" disabled>Save</button> and <output id="status" role="status" aria-live="polite"></output>. Bundle this module locally. Match save-preferences to your manifest action and handler; changing its name in only one file breaks dispatch. This example saves fixed values; the complete panel reads actual user controls. Initialization follows the public panel's theme event handshake. The helper's connectTheme also requests ready after its first theme event; ready is safe to acknowledge again.

Theme functions and tokens

Function Behavior
installGlixoExtensionUi() Registers all helper custom elements once, skipping names already registered.
registerGlixoElements(registry?) Registers controls in the supplied or global custom-element registry.
currentTheme() Returns the helper's current normalized theme snapshot.
subscribeTheme(listener) Immediately calls the listener, then on changes; returns an unsubscribe function.
applyTheme(tokens?,root?) Applies recognized safe values as CSS properties on the root element.
connectTheme(root?) Reads the bridge theme, subscribes to theme/locale events and returns a disconnect function.
invoke(actionId,payload?) Checks action ID format and bridge presence, then forwards to the host.

Theme values are partial: provide sensible local defaults for missing tokens. applyTheme skips long values, markup/semicolon characters and url()/expression() constructs. Use host CSS properties in your own controls:

Token CSS property
background, panel, surface --glixo-color-background, --glixo-color-panel, --glixo-color-surface
text, muted, accent, border Matching --glixo-color-* properties
danger, warning, success Matching --glixo-color-* status properties
fontFamily --glixo-font-family
radius --glixo-radius-control
spacing --glixo-space-scale

Respond to live light/dark and locale changes. Theme values style your panel; they do not alter Glixo's app appearance. See the theme implementation and shared stylesheet.

The helper exports GlixoThemeTokens (the token interface) and GlixoTheme (a readonly partial token set) alongside these functions.

Custom elements

All controls are framework-independent custom elements with shadow DOM. Their exported constructors are GlixoButton, GlixoTextField, GlixoSwitch, GlixoBadge, GlixoCard, GlixoNotice, GlixoProgress, GlixoSelect and GlixoDialog. Source: components.ts.

Element Attributes and events
glixo-button disabled, variant (primary, quiet, danger), type; slotted label and native click.
glixo-text-field label, value, placeholder, autocomplete, required, disabled; glixo-input with detail.value.
glixo-switch label, checked, disabled; checked property; change with detail.checked.
glixo-badge Slotted compact label.
glixo-card Slotted content in a themed container.
glixo-notice tone (info, warning, error); status role or alert for errors.
glixo-progress value, max, label; values clamped to the range.
glixo-select label, value, disabled; options property of {value,label,disabled?}; change with detail.value.
glixo-dialog open, label; show() / close(); slotted content.

Set glixo-select.options before connecting the element (or before an observed attribute triggers its render); changing the property alone does not rerender it. Boolean attributes are present/absent: use toggleAttribute('disabled',condition), not disabled="false". The dialog primitive does not implement a complete focus trap, Escape handling or focus return; add those when building a modal. Test keyboard navigation and accessible names on your panel's actual controls.

Permissions and tests

Declare ui.surface for the surface ID, host.action for action IDs, and any state/network permissions needed by the action. The complete manifest shows their scopes. Bridge invocation supplies only your payload; host identity and resource handles come from Glixo. Treat action errors as failures and don't claim a save succeeded without the returned confirmation.

Test the panel with no bridge, successful ready, failed ready, theme/locale changes, action denial and repeated clicks. Test the handler separately for invalid input and state failures. Then open the installed Windows panel, approve permissions and check save/restart behavior. A browser HTML preview verifies rendering; it cannot verify the sandbox's grants or native bridge. Use the installed-panel checklist.