openscd / open-scd-wizarding Goto Github PK

• Principle style/approach of wizarding (declaration of intend, component, leave it open to users, other....)

As a user of OpenSCD I want to know which child elements are allowed within a given element.

Requirements

• based on a provided schema
• return string array including all allowed child element tagNames
• in the correct sequence as defined in the standard

Proposed API

 function validChildTags(tagName: string, schema: XMLDocument): string[]

As a user of open-scd-core I want to have an algorithm that returns the definition attributes for a given SCL element including its restriction defined by a given SCL schema.

Background
When receiving a wizard event for an element that is not added to the wizard library, we need to have a fallback mode wizard. Such a wizard is constructed of inputs for each of the attitudes of the element. Each of the attributes can have restriction defined in the schema that shall be added of the inputs in the wizard.

Requirements

• return an object for each attribute of a given SCL element, including its restrictions based on a given schema

Proposed interfaces

function getAttributes(tagName: string, schema:XMLDocument): Record<string, Attribute>

interface Attribute {
  base: string;
  namespaceURI?: string;
  value?: string | null;
  defaultValue?: string;
  enumeration?: string[];
  required?: boolean;
  pattern?: string;
  maxLength?:string;
  minLength?: string;
}

As a user of OpenSCD core, I want to have a simple way to create my own wizards in my plugin.

Requirements

• allow multiple pages per dialog
• allow adding name and icon per page
• navigation buttons between pages
• render primary action button on the last page of the dialog
• check for inputs validation on page navigation and on primary action

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;

As a user of OpenSCD core, I want to know the parents' element tags for a given element and schema.

Requirement

• for a given schema and element tagName
• return all parents elements tagNames

Proposed API

 function validParentTags(tagName: string, schema: XMLDocument): string[]

Re-use the open-wc recommendation as used in open-scd-core except for importing open-scd from npm

Re-use CONTRIBUTING.md from open-scd-core

As a plugin author, I want to have a default wizard per given SCL element.

Requirements

• default input for wizard <oscd-attribute-input name="desc" attribute="{base: \"xs:normalizedString\"}">
• ....