Add HTMLElement children + create Element

Web/X - API JS-DOM/index.md

@@ -37,7 +37,9 @@ Sinon, vous pouvez soit :
       g[x] = getattr(window, x, None)
    ```
 
-# Sélectionner des éléments HTML
+# Manipulation du DOM
+
+## Sélectionner des éléments HTML
 
 - Sélectionner un élément à partir d'un sélecteur CSS :
   
@@ -75,7 +77,7 @@ Sinon, vous pouvez soit :
 document.querySelector<HTMLDivElement>($CSS_SELECTOR) // retourne un DIV
 ```
 
-# Modifier un élément HTML
+## Propriétés d'un élément HTML
 
 - Classes :
   
@@ -131,6 +133,216 @@ for name in $ELEM.getAttributeNames():
 
 📖 [Plus de méthodes disponibles dans la documentation.](https://developer.mozilla.org/en-US/docs/Web/API/Element)
 
+## Enfants d'un élément HTML
+
+- Ajouter un fils à un élément :
+  
+  ```javascript
+  $ELEM.append($CHILD_ELEM)
+  ```
+
+- Remplacer les fils d'un élément :
+  
+  ```javascript
+  $ELEM.replaceChildren($CHILD_ELEM_1 [,$CHILD_ELEM_2,...] );
+  ```
+
+- Retirer un élément du DOM (et donc de son parent) :
+  
+  ```javascript
+  $ELEM.remove()
+  ```
+
+- Obtenir la liste des enfants d'un élément :
+  
+  ```javascript
+  $ELEM.children   // seulement les Element.
+  $ELEM.childNodes // tous les Node (noeuds, e.g. texte).
+  ```
+
+- Obtenir le parent d'un élément :
+  
+  ```javascript
+  $ELEM.parentElement // returne le parent Element ou null.
+  ```
+
+## Créer un élément HTML
+
+- Cloner un élément :
+  
+  ```javascript
+  $ELEM.cloneNode(true) // retourne le clone.
+  ```
+
+- Créer un élément HTML à partir de son nom :
+  
+  ```javascript
+  document.createElement($TAGNAME) // e.g. "div".
+  ```
+
+- Créer un élément HTML en l'initialisant :
+  
+  ```typescript
+  // [TS] TypeScript
+  let elem = create("div", {
+      classes  : ["c1", "c2"],
+      listeners: {
+          click: (ev) => { ... }
+      }
+  });
+  ```
+  
+  ```python
+  # [🐍] Python
+  def clickHandler(ev):
+      pass
+  
+  elem = create("div",
+      classes  = ("c1", "c2"),
+      listeners= {
+          "click": clickHandler
+      }
+  });
+  ```
+
+- Créer un élément à partir d'un string (à éviter) :
+  
+  ```typescript
+  // [JS] Javascript
+  function str2df(str) {
+      const template = document.createElement('template');
+      template.innerHTML = str; // en général à éviter
+      return template.content;
+  }
+  function str2elem<T extends Element>(str): T {
+      return str2df(str).children[0] as T;
+  }
+  
+  str2df($HTML_STRING)   // retourne un DocumentFragment (hérite Node)
+  str2elem<$ELEM_TYPE>($HTML_STRING) // retourne un $ELEM_TYPE (hérite Element)
+  ```
+  
+  ```python
+  # [🐍] Python
+  def str2df(str):
+      const template = document.createElement('template');
+      template.innerHTML = str; # en général à éviter
+      return template.content;
+  
+  def str2elem(str):
+      return str2df(str).children[0];
+  
+  str2df($HTML_STRING)   # retourne un DocumentFragment (hérite Node)
+  str2elem($HTML_STRING) # retourne un Element
+  ```
+
+📖 [Plus d'informations dans la documentation.](https://developer.mozilla.org/fr/docs/Web/API/Element)
+
+### Implémentations de `create()`
+
+```typescript
+// [TS] TypeScript
+type CreateOpts = Partial<{
+      children   : readonly Element[],
+      textContent: string,
+      id         : string,
+      classes    : readonly string[],
+      attrs      : readonly Record<string, string>,
+      dataset    : readonly Record<string, string>,
+      cssvars    : readonly Record<string, string>,
+      listeners  : readonly Record<string, (ev: Event) => void>
+      parent     : Element
+}>;
+function create<T extends keyof HTMLElementTagNameMap>(tagname: T,
+                      {
+                          children    = null,
+                          textContent = null,
+                          id          = null,
+                          classes     = [],
+                          attrs       = {},
+                          dataset     = [],
+                          cssvars     = {},
+                          listeners   = {},
+                          parent      = null
+                      } = {}): HTMLElementTagNameMap[T] {
+
+  let elem = document.createElement(tagname) as HTMLElementTagNameMap[T];
+
+  if( children !== null )
+      elem.replaceChildren(...children);
+
+  if( textContent !== null )
+      elem.textContent = textContent;
+
+  if( id !== null )
+      elem.id = id;
+
+  elem.classList.add(...classes);
+
+  for(let attrname in attrs)
+      elem.setAttribute(attrname, attrs[attrname]);
+
+  for(let dataname in dataset)
+      elem.dataset[dataname] = dataset[dataname];
+
+  for(let cssvarname in cssvars)
+      elem.style.setProperty(`--${cssvarname}`, cssvars[cssvarname])
+
+  for(let event in listeners)
+      elem.addEventListener(event, listeners[event]);
+
+  if( parent !== null )
+      parent.append(elem);
+
+  return elem;
+}
+```
+
+```python
+# [🐍] Python
+def create( tagname,
+            *, # force kw args
+            children    = None,
+            textContent = None,
+            id          = None,
+            classes     = (),
+            attrs       = {},
+            cssvars     = {},
+            listeners   = {},
+            parent      = None ) {
+
+  elem = document.createElement(tagname);
+
+  if children is not None:
+      elem.replaceChildren(*children);
+
+  if textContent is not None:
+      elem.textContent = textContent;
+
+  if id is not None:
+      elem.id = id;
+
+  elem.classList.add(*classes);
+
+  for attrname in attrs:
+      elem.setAttribute(attrname, attrs[attrname]);
+
+  for dataname in dataset:
+      elem.dataset[dataname] = dataset[dataname];
+
+  for cssvarname in cssvars:
+      elem.style.setProperty(f"--{cssvarname}", cssvars[cssvarname])
+
+  for event in listeners:
+      elem.addEventListener(event, listeners[event]);
+
+  if parent is not None:
+      parent.append(elem);
+
+  return elem;
+}
+```
+
 # Événements
 
 ## Bubble vs Capture