@displayduck/base

Type definitions and backend placeholders for DisplayDuck widget packs.

Install

npm install -D @displayduck/base

Purpose

This package is intentionally not the runtime implementation.

The real behavior for these APIs is provided by the DisplayDuck backend build/runtime pipeline:

• signal(...)
• effect(...)
• httpFetch(...)
• createWidgetClass(...)

This package exists so pack authors get:

• TypeScript types
• autocomplete
• stable imports for pack source code

Exports

• signal
• effect
• httpFetch
• invokeBackendCommand
• focusWidgetView
• createWidgetClass
• type Signal
• type WritableSignal
• type WidgetContext
• type WidgetPayload

Example

import { httpFetch, signal, type WidgetContext } from '@displayduck/base';

export class DisplayDuckWidget {
  public title = signal('Example');

  public constructor(private readonly ctx: WidgetContext) {}

  public async onInit(): Promise<void> {
    await httpFetch('https://example.com/feed.xml');
    this.ctx.setLoading(false);
  }

  public showMyView(): Promise<void> {
    return this.ctx.focusWidgetView();
  }

  public setNeedsFocus(required: boolean): Promise<void> {
    return this.ctx.setRequireFocus(required);
  }
}

focusWidgetView() requests the view containing the widget to become active. The request is honored only when the widget's Allow focus grab option is enabled. setRequireFocus(true) lets the app remember the current view, switch to the widget's view, and restore the previous view when setRequireFocus(false) is called.

If you execute these APIs outside the DisplayDuck pack runtime pipeline, the placeholder implementation will throw by design.