Finalize wizarding API

[ca-d]

We are thinking about radically changing the WizardEvent in order to turn it into a pure declaration of intent.

Instead of the API user saying

"Please open a wizard with exactly these inputs, page titles, button labels, icons, etc., and exactly this WizardAction committed at the end.",

the API user would then either say

"Please open some wizard allowing the user to edit this element I have here."

or

"Please open some wizard allowing the user to create a new element of this tagName as a child of this parent element I have here."

In order to enable the API user to add properties from an extension namespace defined in some custom schema, the API user can specify pairs of XML Schema documents and namespace prefix strings to take into consideration. All other work would be done automatically by the core editor.

This would mean reducing the scope of Wizards to creating or editing elements only, while other tasks (e.g. our "select" wizards) would then be done using regular modal dialogues. This makes for a clean, single-purpose API with a clearly defined upgrade path when new versions of the standard schema are released.

interface CustomNamespace {
  prefix: string,
  schema: XMLDocument
}

interface WizardEventDetail {
  element: Element,
  tagName?: string,
  custom?: CustomNamespace[],
  hidden?: string[],
  subWizard?: boolean
};

function newEditWizardEvent(element: Element, customNS?: CustomNamespace[]): WizardEvent;
function newCreateWizardEvent(parent: Element, tagName: string, customNS?: CustomNamespace[]): WizardEvent;

[Sander3003]

Create an ADR's:

• Content of wizarding library (define inputs/outputs)

Acceptance criteria:
Pull-request

[Sander3003]

See: https://github.com/openscd/open-scd/discussions/1230

[Sander3003]

Related: #10

[ca-d]

If we implement modular wizard libraries in open-scd-core, we don't actually need to take care of extension namespaces in the API any more, since these can be handled in purpose-built wizards for the same element. This is an alternative API we could use at that point.

export interface WizardBase {
  subWizard?: boolean;
}

export interface CreateWizard extends WizardBase {
  parent: Element;
  tagName: string;
}

export interface EditWizard extends WizardBase {
  element: Element;
}

export type Wizard = CreateWizard | EditWizard;

export function isCreateWizard(wizard: Wizard): wizard is CreateWizard {
  return 'parent' in wizard;
}

export function isEditWizard(wizard: Wizard): wizard is EditWizard {
  return 'element' in wizard;
}

export type WizardEvent = CustomEvent<Wizard>;

export function newWizardEvent(wizard: Wizard): WizardEvent {
  return new CustomEvent<Wizard>('oscd-wizard', {
    composed: true,
    bubbles: true,
    detail: wizard,
  });
}

declare global {
  interface ElementEventMap {
    ['oscd-wizard']: WizardEvent;
  }
}