@supersoniks/concorde 2.0.6 → 3.0.0

package/src/core/components/functional/sdui/sdui.md

@@ -0,0 +1,356 @@
+# SDUI
+
+## What is SDUI?
+
+SDUI stands for `Server Driven User Interfaces`.
+Basically, it generates a user interface based on a JSON SDUI Descriptor.
+
+### Subscriber extension:
+
+SDUI extends the mixin [Subscriber](#docs/_core-concept/subscriber.md/subscriber).
+This means that you must set a dataProvider with an id pointing to the publisher that will hold your SDUI Descriptor.
+This also means that it has a reactive property named `props` that you can set with the JSON SDUI Descriptor in order to configure it.
+
+### Fetcher extension:
+
+SDUI extends the mixin Fetcher as [Fetch](#core/components/functional/fetch/fetch.md/fetch) and [List](#core/components/functional/list/list.md/list).
+
+In this case, it will parse the JSON coming from the request.
+The JSON must comply with the SDUI descriptor format.
+
+As a fetcher, invalidating the publisher or updating the endpoint will trigger a new fetch and update accordingly.
+
+### Rendering:
+
+It has no shadowdom, and its display style is set to `contents`, so an empty SDUI has the fewest impact on the layout.
+
+## SDUI descriptor
+
+### TypeScript definition:
+<sonic-code language="typescript">
+  <template>
+    export type SDUIDescriptor = {
+      js?: Array&lt;string&gt;;
+      css?: Array&lt;string&gt;;
+      library?: Record&lt;string, SDUINode&gt;;
+      nodes?: Array&lt;SDUINode&gt;;
+    };
+  </template>
+</sonic-code>
+
+### Meaning of the keys:
+
+* **js**: An array of URLs pointing to JavaScript files to load.
+* **css**: An array of URLs pointing to CSS files to load.
+* **library**: A record of SDUINode definitions intended to be used as a model for other nodes. The keys of the record can be used as the libraryKey of the node. This node will then specialize the model with its own descriptor.
+* **nodes**: An array of SDUINode descriptors. Each SDUINode will result in an HTMLElement added to the root of the component.
+
+## SDUINode
+
+### Descriptor
+
+An SDUINode represents an HTMLElement.
+
+TypeScript definition:
+
+<sonic-code language="typescript">
+  <template>
+    export type SDUINode = {
+      markup?: string;
+      tagName?: string;
+      attributes?: Record&lt;string, string&gt;;
+      nodes?: Array&lt;SDUINode&gt;;
+      innerHTML?: string;
+      prefix?: string;
+      suffix?: string;
+      libraryKey?: string;
+      contentElementSelector?: string;
+      parentElementSelector?: string;
+    };
+  </template>
+</sonic-code>
+
+Summary of properties:
+* **markup**: Use it if you prefer to define your node entirely using an HTML string.
+* **tagName**: The tag name of the HTML element.
+* **attributes**: A string key/value pair storing each attribute name/value of the HTML element created.
+* **nodes**: An array of SDUINode descriptors. The children of the HTMLElement are created this way.
+* **innerHTML**: The inner HTML of the current node is defined here if needed.
+* **prefix**: Use it if you want to wrap the component with some HTML string in conjunction with the suffix.
+* **suffix**: Use it if you want to wrap the component with some HTML string in conjunction with the prefix.
+* **libraryKey**: An identifier that points to an SDUINode to be used as a model for this node.
+* **contentElementSelector**: For SDUINodes defined in the library only. It is a CSS selector that defines where child nodes are added.
+* **parentElementSelector**: If the current node, as a future child, has a `parentElementSelector` attribute, it is added to the node corresponding to the associated CSS selector rather than directly to the element.
+
+### Markup
+Use it if you prefer to define your node entirely using an HTML string.
+
+<sonic-code>
+  <template>
+    <sonic-sdui 
+      dataProvider="sdui-markup-example" 
+      props='{
+          "nodes":[
+            {
+              "markup":"keep shouting <sonic-badge>foo</sonic-badge> <sonic-badge>bar</sonic-badge> !"
+            }
+          ]}'
+    ></sonic-sdui>
+  </template>
+</sonic-code>
+
+### Tag name
+Here we use the field `tagName` of SDUINode to create an element with tag name `sonic-input`.
+
+<sonic-code>
+  <template>
+    <sonic-sdui 
+      dataProvider="sdui-tagName-example" 
+      props='{
+          "nodes":[
+            {
+              "tagName":"sonic-input"
+            }
+          ]}'
+    ></sonic-sdui>
+  </template>
+</sonic-code>
+
+### Attributes
+A string key/value pair storing each attribute name/value of the HTML element created.
+As no tag name is defined, a div element is created.
+Here we define the style attribute to create a tiny red square.
+
+<sonic-code>
+  <template>
+    <sonic-sdui 
+      dataProvider="sdui-attributes-example" 
+      props='{
+        "nodes":[{
+          "attributes":{
+            "style":"width:50px;height:10px;background:red;"
+          }
+        }]
+      }'
+    ></sonic-sdui>
+  </template>
+</sonic-code>
+
+### Nodes
+Children of the current node can be added using the field `nodes` recursively.
+
+<sonic-code>
+  <template>
+    <sonic-sdui 
+      dataProvider="sdui-nodes-example" 
+      props='{
+        "nodes":[{
+          "nodes":[
+            {"innerHTML":"A"},
+            {
+              "prefix":"B",
+              "nodes":[
+                {"innerHTML":"👉 B.1"},
+                {"innerHTML":"👉 B.2"}
+              ]
+            }
+          ]
+        }]
+      }'
+    ></sonic-sdui>
+  </template>
+</sonic-code>
+
+### InnerHTML
+As no tag name is defined, a div element is created, and then we use `innerHTML` to add content to it.
+
+<sonic-code>
+  <template>
+    <sonic-sdui 
+      dataProvider="sdui-html-example" 
+      props='{
+        "nodes":[{
+          "innerHTML":"keep shouting <sonic-badge>foo</sonic-badge> <sonic-badge>bar</sonic-badge> !"
+        }]
+      }'
+    ></sonic-sdui>
+  </template>
+</sonic-code>
+
+### Prefix and suffix
+Use them if you want to wrap the component with some HTML string.
+
+<sonic-code>
+  <template>
+    <sonic-sdui 
+      dataProvider="sdui-prefixSuffix-example" 
+      props='{
+        "nodes":[{
+          "prefix":"👇",
+          "suffix":"☝️",
+          "innerHTML":"The node content"
+        }]
+      }'
+    ></sonic-sdui>
+  </template>
+</sonic-code>
+
+### Library key and contentElementSelector
+The libraryKey of SDUINode is an identifier that points to an SDUINode description in the library to be used as a model for this node.
+
+Note that the SDUI has a default library containing some basic component definitions useful for form declaration (see default-library.json).
+
+This example uses the library key `submit` which points to a `sonic-submit` containing a button also coming from the library.
+
+The element named `button` in the library is a `sonic-button` of type `success` containing a check icon as a prefix.
+
+Since the `submit` library element contains an attribute `contentElementSelector` with the value `sonic-button`, the "injected content" is put inside the button.
+
+We used `innerHTML` for the sake of simplicity, but you can use nodes to add any complex content.
+
+<sonic-code>
+  <template>
+    <sonic-sdui dataProvider="sdui-library-example" props='
+          {
+            "nodes":[
+              {
+                "libraryKey":"submit",
+                "innerHTML":"Injected content"
+              }
+            ]
+          }
+    '></sonic-sdui>
+  </template>
+</sonic-code>
+
+### parentElementSelector
+
+This special field lets you inject the content at any place in the HTML flow already set inside the parent SDUI component by using a CSS selector.
+
+⚠️ Note that it doesn't work with top-level nodes.
+
+<sonic-code>
+  <template>
+    <sonic-sdui dataProvider="sdui-parentElementSelector-example" props='
+          {
+            "nodes":[
+              {
+                "nodes":[
+                  {
+                    "prefix":"👇 Selected parent element",
+                    "suffix":"☝️ End of selected parent element",
+                    "tagName":"span"
+                  },
+                  {
+                    "parentElementSelector":"span",
+                    "innerHTML":"Content having a parentElementSelector attribute"
+                  }
+                ]
+              }
+            ]
+          }
+    '></sonic-sdui>
+  </template>
+</sonic-code>
+
+### Fetch example:
+
+<sonic-code>
+  <template>
+    <sonic-sdui dataProvider="sdui-fetch-example" endPoint="/src/core/components/functional/sdui/example.json"></sonic-sdui>
+  </template>
+</sonic-code>
+
+## Transformers:
+
+The transformers let you transform the structure of the SDUI Descriptor into a new one before parsing and rendering it.
+
+To enable it, you must fill the `transformation` attribute of the component with a URL pointing to a Transform descriptor.
+
+<sonic-code language="typescript">
+  <template>
+  export type SDUITransformDescription = {
+    library?: Record&lt;string, SDUINode&gt;;
+    transforms: Array&lt;SDUITransformAction&gt;;
+  };
+  </template>
+</sonic-code>
+
+### The library:
+
+Each key of the library will be merged with the current library in the SDUI Descriptor, by replacing or creating items library key by key.
+
+### The transform actions:
+
+Each transform represents an action that will be done on the SDUI descriptor before the creation of the entire UI.
+
+<sonic-code language="typescript">
+  <template>
+export type SDUITransformAction = {
+  action: SDUITransformActionName;
+  patterns?: Array&lt;SDUINode&gt;;
+  after?: SDUINode;
+  before?: SDUINode;
+  in?: SDUINode;
+  ui?: SDUINode;
+};
+  </template>
+</sonic-code>
+
+The action that will be done is a verb:
+
+<sonic-code language="typescript">
+  <template>
+export type SDUITransformActionName = "remap" | "unwrap" | "wrap" | "delete" | "insert" | "move";
+  </template>
+</sonic-code>
+
+* **remap**: The properties (tagName, innerHTML, etc.) of the targeted SDUINode will be created/changed according to their presence in the `ui` (SDUINode) property of the transformAction.
+* **unwrap**: Replaces the targeted SDUINode in place with its children.
+* **wrap**: Groups all SDUINodes targeted by the patterns into the new SDUINode described in the `ui` prop of the transformAction.
+* **delete**: Deletes the targeted item.
+* **insert**: Inserts a new SDUINode described by the `ui` prop into the flow. The position of insertion depends on the presence of the attributes `before`, `after`, `in`, which is a pattern to target an existing SDUINode.
+
+## Misc Tricks:
+
+### sduiKey
+
+This is an HTML attribute to set on the component if needed. In this case, the component will not treat its props value directly as an SDUI descriptor. Internally, it will basically extract the SDUIDescriptor by doing something like this: `const sduiDescriptor = this.props[this.sduikey]`.
+
+### messageKey
+
+This is an HTML attribute to set on the component if needed. In this case, the component will automatically create a `sonic-toast-message-subscriber` component. The data found in `props[messageKey]` will be treated as the data expected by the `sonic-toast-message-subscriber`. So, by respecting the format of data supported by this component, you will be able to show multiple toasts in the result of a request.
+
+Example of JSON with `messageKey`=`messages`:
+<sonic-code language="typescript">
+  <template>
+{
+  "messages": [{
+    "content": "The product has been added to your cart", 
+    "status": "success", 
+    "type": "public"
+  }]
+}
+  </template>
+</sonic-code>
+
+### library
+
+This is an HTML attribute to set on the component if needed. You can set a URL pointing to a JSON describing a library with the same structure as the library in the SDUIDescriptor. The component will simply override its library with the given one.
+
+## Playground
+
+Here is a little playground to let you test some simple tricks.
+
+<sonic-code>
+  <template>
+    <sonic-textarea 
+    rows="10" 
+    onChange="SonicPublisherManager.get('sdui-playground').set(JSON.parse(this.value))" 
+    value='{"nodes":[{"tagName":"div", "innerHTML":"test"}]}'
+    >
+    </sonic-textarea>
+    <sonic-sdui dataProvider="sdui-playground" props='{"nodes":[{"tagName":"div", "innerHTML":"test"}]}'>
+    </sonic-sdui>
+  </template>
+</sonic-code>

package/src/core/components/functional/sdui/sdui.ts

@@ -0,0 +1,230 @@
+import default_library from "@supersoniks/concorde/core/components/functional/sdui/default-library.json";
+import SDUIDescriptorTransformer from "@supersoniks/concorde/core/components/functional/sdui/SDUIDescriptorTransformer";
+import {
+  SDUIDescriptor,
+  SDUINode,
+  SDUITransformDescription,
+} from "@supersoniks/concorde/core/components/functional/sdui/types";
+import {Fetcher, Subscriber} from "@supersoniks/concorde/mixins";
+
+import {HTML, Objects} from "@supersoniks/concorde/utils";
+import {LitElement, PropertyValues} from "lit";
+import {customElement, property} from "lit/decorators.js";
+const tagName = "sonic-sdui"; // For Astro.build
+/**
+ *  ### sonic-sdui (Server Driven User Interface) est un fetcher chargant un JSON décrivant une interface utilisateur
+ *
+ * Extends mixins : Fetcher, [Subscriber](./?path=/docs/miscallenous-🔔-subscriber--page)
+ *
+ * * Si le composant possède un attribut *fetch*, il charge un contenu via un appel d'api web.<br>
+ * Voir [fetcher](./?path=/docs/core-components-functional-fetch--basic) pour la configuration des autres attributs.
+ * * Le format du JSON est décrit par le type SDUIDescriptor
+ * * Un attribut supplémentaire `transformation` permet de transformer le json reçu avant la génération de l'interface utilisateur<br>
+ * Son format est décrit par le type SDUITransformDescription
+ *
+ *  * Si le résultat de la requête est un objet, il est imbriqué dans un tableau pour garantir le fonctionnement.<br>
+ * *
+ */
+@customElement(tagName)
+export class SonicSDUI extends Fetcher(Subscriber(LitElement)) {
+  connectedCallback(): void {
+    this.noShadowDom = "";
+    this.displayContents = true;
+    this.isFetchEnabled = this.hasAttribute("fetch");
+    super.connectedCallback();
+  }
+
+  @property() sduiKey?: string;
+  @property() messagesKey?: string;
+  private sduiDescriptor: SDUIDescriptor = {};
+
+  /**
+   * On peut passer la description sous form de props, sinon il faut utiliser l'attribut fetch
+   */
+
+  willUpdate(changedProperties: PropertyValues): void {
+    if (this.props == null) {
+      this.sduiDescriptor = {};
+    }
+    {
+      const newSduiDescriptor = this.sduiKey
+        ? (this.props as Record<string, SDUIDescriptor>)[this.sduiKey]
+        : (this.props as SDUIDescriptor);
+      if (this.sduiDescriptor == newSduiDescriptor) return;
+      this.sduiDescriptor = newSduiDescriptor;
+      this.updateContents();
+    }
+    super.willUpdate(changedProperties);
+  }
+
+  /**
+   * updateContents est déclenché quand les sduiDescriptor sont renseignées
+   * Le contenu du composant est regénéré en fonction du descripteur fourni
+   */
+  async updateContents() {
+    if (!this.sduiDescriptor) return;
+    const library: Record<string, SDUINode> = {};
+    Object.assign(library, default_library, this.sduiDescriptor.library);
+    this.sduiDescriptor.library = library;
+    this.loadAssets();
+    await this.loadLibrary();
+    await this.transformSDUIDescriptor();
+    this.parseRootNodes();
+  }
+  /**
+   * Suppressiond du contenu du composant avant le génération de la nouvelle ui
+   */
+  private removeChildren() {
+    while ([...this.children].filter((elt) => elt.nodeName != "SLOT").length > 0) {
+      this.removeChild(this.children[0]);
+    }
+  }
+  /**
+   * Chargement de fichiers js et css associés si besoin
+   **/
+  private loadAssets() {
+    if (!this.sduiDescriptor) return;
+    if (this.sduiDescriptor.js) {
+      for (const src of this.sduiDescriptor.js) HTML.loadJS(src);
+    }
+    if (this.sduiDescriptor.css) {
+      for (const src of this.sduiDescriptor.css) HTML.loadCSS(src);
+    }
+  }
+  /**
+   * Transformation de la data fournie via sduiDescriptor si il y a un attribut transformation
+   * */
+  private async transformSDUIDescriptor() {
+    if (!this.hasAttribute("transformation")) return;
+    const result = await fetch(this.getAttribute("transformation"));
+    const json: SDUITransformDescription = await result.json();
+    const transformer = new SDUIDescriptorTransformer();
+    await transformer.transform(this.sduiDescriptor, json);
+  }
+  /**
+   * Charge la library à utiliser
+   * */
+  private async loadLibrary() {
+    if (!this.hasAttribute("library")) return;
+    const result = await fetch(this.getAttribute("library"));
+    const json: Record<string, SDUINode> = await result.json();
+    this.sduiDescriptor.library = json;
+  }
+  /**
+   * Point d'entrée : transformation des noeuds fournis en éléments graphiques
+   **/
+  private parseRootNodes() {
+    this.removeChildren();
+    if (!this.sduiDescriptor) return;
+    let nodes = this.sduiDescriptor.nodes;
+    if (!nodes) nodes = [];
+    const messageProvider = {tagName: "sonic-toast-message-subscriber", attributes: {}};
+    if (this.messagesKey) {
+      messageProvider.attributes = {subDataProvider: this.messagesKey};
+    }
+    nodes.push(messageProvider);
+    nodes.forEach((node) => this.appendChild(this.parseChild(node)));
+  }
+  /**
+   * On parse un noeud ce qui crée un éléments graphique et ses enfants par recursivité via `handleChildNodes`
+   */
+  private parseChild(node: SDUINode) {
+    const tagName = node.tagName || "div";
+    let {element, contentElement} = this.handleLibrary(node, tagName);
+    this.handleAttributes(node, element);
+    element = this.handleMarkup(node, element);
+    if (!contentElement) contentElement = element;
+    this.handleChildNodes(node, contentElement, element);
+    this.handleInnerHTML(node, contentElement);
+    if (node.prefix || node.suffix) {
+      const container = this.handlePrefixSuffix(node, element);
+      return container;
+    }
+    return element;
+  }
+  /**
+   * Si le noeud courant a des propriétés prefix et ou suffix il est entouré des markups fournis dans ces sduiDescriptor.
+   * Le tout est inclu dans une div en display contents
+   */
+  private handlePrefixSuffix(node: SDUINode, element: HTMLElement) {
+    const container = document.createElement("div");
+    container.innerHTML = (node.prefix || "") + element.outerHTML + (node.suffix || "");
+    container.style.display = "contents";
+    return container;
+  }
+  /**
+   * Création des enfants du noeud courant
+   * Si l'enfant à un attribut parentElementSelector, il est ajouté dans le noeud correspondant au sélecteur css associé et non pas dans l'élément directement.
+   */
+  private handleChildNodes(node: SDUINode, contentElement: HTMLElement, element: HTMLElement) {
+    if (node.nodes) {
+      const children: Array<SDUINode> = node.nodes;
+      for (const child of children) {
+        const childElement = this.parseChild(child);
+        let nodeToAppendOn = contentElement;
+        if (child.parentElementSelector) {
+          nodeToAppendOn = element.querySelector(child.parentElementSelector) || contentElement;
+        }
+        if (nodeToAppendOn.shadowRoot) nodeToAppendOn.shadowRoot.appendChild(childElement);
+        else if (nodeToAppendOn.tagName.toLocaleLowerCase() == "template") {
+          const template: HTMLTemplateElement = nodeToAppendOn as HTMLTemplateElement;
+          template.content.appendChild(childElement);
+        } else nodeToAppendOn.appendChild(childElement);
+      }
+    }
+  }
+  /**
+   * Gestion de librarie :
+   * * Si l'élément référence un élément de la librairie, on se sert de cet élément comme model pour créer le composant graphique.
+   * * Sa propriété contentElement retournée vaut element par défaut.
+   * * Si contentElementSelector est definit, alors contentElement correspond à l'élément obtenu par selection css d'après la valeurs de contentElementSelector
+   * * Les éléments enfants seront ensuite ajoutés dans contentElement
+   */
+  private handleLibrary(node: SDUINode, tagName: string) {
+    let element: HTMLElement;
+    let contentElement: HTMLElement | undefined;
+    if (node.libraryKey && this.sduiDescriptor.library) {
+      element = this.parseChild(this.sduiDescriptor.library[node.libraryKey] || {tagName: "div"});
+      const selector = (this.sduiDescriptor.library[node.libraryKey] || {}).contentElementSelector;
+      if (selector) contentElement = element.querySelector(selector) as HTMLElement;
+    } else element = document.createElement(tagName) as HTMLElement;
+    return {element, contentElement};
+  }
+  /**
+   * Remplissage des attributs html avec les attributs fournis dans le noeud
+   */
+  private handleAttributes(node: SDUINode, element: HTMLElement) {
+    const attributes = node.attributes;
+    for (const k in attributes) {
+      const attrData: object | string = attributes[k];
+      const attr: string = Objects.isObject(attrData) ? JSON.stringify(attrData) : attrData;
+      element.setAttribute(k, attr);
+    }
+  }
+  /**
+   * Si une propriété markup est fournie, l'élément est créé à partir de la chaine html fournie avant d'être configuré
+   */
+  private handleMarkup(node: SDUINode, element: HTMLElement) {
+    if (node.markup) {
+      element = document.createElement("div");
+      element.style.display = "contents";
+      element.innerHTML = node.markup;
+    }
+    return element;
+  }
+
+  /**
+   * si le noeud à une propriété innerHTML, on l'ajout ay innerHTML de l'élément html en cours de création
+   */
+  private handleInnerHTML(node: SDUINode, contentElement: HTMLElement | undefined) {
+    if (!node.innerHTML) return;
+    if (node.innerHTML.indexOf("wording_") != -1) {
+      const wordingProvider = this.getAncestorAttributeValue("wordingProvider");
+      this.api?.post(wordingProvider, {labels: [node.innerHTML.substring(8)]}).then((value) => {
+        if (contentElement) contentElement.innerHTML += value;
+      });
+    } else if (contentElement) {
+      contentElement.innerHTML += node.innerHTML;
+    }
+  }
+}

package/src/core/components/functional/sdui/types.ts

@@ -0,0 +1,34 @@
+export type SDUIDescriptor = {
+  js?: Array<string>;
+  css?: Array<string>;
+  library?: Record<string, SDUINode>;
+  nodes?: Array<SDUINode>;
+};
+export type SDUINode = {
+  libraryKey?: string;
+  markup?: string;
+  tagName?: string;
+  attributes?: Record<string, string>;
+  nodes?: Array<SDUINode>;
+  innerHTML?: string;
+  prefix?: string;
+  suffix?: string;
+  contentElementSelector?: string;
+  parentElementSelector?: string;
+};
+
+export type SDUITransformDescription = {
+  library?: Record<string, SDUINode>;
+  transforms: Array<SDUITransformAction>;
+};
+export type SDUITransformActionName = "remap" | "unwrap" | "wrap" | "delete" | "insert" | "move";
+export type SDUITransformActionFunction = (transformAction: SDUITransformAction, list: SDUITransformList) => void;
+export type SDUITransformAction = {
+  action: SDUITransformActionName;
+  patterns?: Array<SDUINode>;
+  after?: SDUINode;
+  before?: SDUINode;
+  in?: SDUINode;
+  ui?: SDUINode;
+};
+export type SDUITransformList = Array<{parent: SDUINode; child: SDUINode; index: number}>;

package/src/core/components/functional/sonic-scope/sonic-scope.ts

@@ -0,0 +1,13 @@
+import {html, LitElement} from "lit";
+import {customElement} from "lit/decorators.js";
+const tagName = "sonic-scope";
+
+@customElement(tagName)
+export class SonicScope extends LitElement {
+  protected createRenderRoot() {
+    return this;
+  }
+  render() {
+    return html`<slot></slot>`;
+  }
+}