@supersoniks/concorde 3.1.76 → 3.1.78

package/docs/src/core/components/functional/fetch/fetch.md

@@ -0,0 +1,117 @@
+# Fetch
+The **sonic-fetch** component is used to request and store data from an API.
+Fetch extends the mixins Fetcher and [Subscriber](#docs/_core-concept/subscriber.md/subscriber)
+
+## Basic usage
+In order to work properly the <b>sonic-fetch</b> component needs at least the following attributes.  
+- **serviceURL** : A base service url. This attribute can be inherited from an ancestor.
+  *ex : https://reqres.in*
+- **endPoint** : the specific location where requests for information are sent (see the api docs).  
+  *ex : api/users | api/users?page=2 | api/users/2*
+- **dataProvider *(Required)*** : An ID that is used as a reference to the object storing the data returned by the API.
+This attribute can be inherited from an ancestor.
+
+<sonic-code>
+  <template>
+    <sonic-fetch serviceURL="https://reqres.in" endPoint="api/users?page=2" dataProvider="myDataObj"></sonic-fetch>
+    <sonic-button dataProvider="myDataObj" debug>Hover to see the data</sonic-button>
+  </template>
+</sonic-code>
+
+## DataProvider as an endPoint
+If no **endPoint** is specified it will be filled by the **dataProvider ID** instead  
+
+<sonic-code>
+  <template>
+    <sonic-fetch serviceURL="https://reqres.in" dataProvider="api/users?page=2" ></sonic-fetch>
+    <sonic-button dataProvider="api/users?page=2" debug>Hover to see the data</sonic-button>
+  </template>
+</sonic-code>
+
+## HeadersDataProvider
+
+<sonic-alert status="error" background>Deprecated</sonic-alert>
+
+## Key
+When the **key** attribute is present, only a sub-part of the data received is injected into the **dataProvider**.
+We can use the dot syntax to target what we want to keep.
+
+For example if the data is `{my:{data:{a:1,b:2}}}` and the key is `key="my.data"`, the data available in the **dataProvider** will be `{a:1 , b:2}`
+
+<sonic-code>
+  <template>
+    <sonic-fetch serviceURL="https://reqres.in" dataProvider="api/users/2" ></sonic-fetch>
+    <sonic-button dataProvider="api/users/2" debug>dataProvider object</sonic-button>
+    <!-- Get the user ID -->
+    <sonic-fetch serviceURL="https://reqres.in" dataProvider="id" endPoint="api/users/2" key="data.id"></sonic-fetch>
+    <sonic-button dataProvider="id" debug>data.id</sonic-button>
+    <!-- Get the user First name -->
+    <sonic-fetch serviceURL="https://reqres.in" dataProvider="first_name" endPoint="api/users/2" key="data.first_name"></sonic-fetch>
+    <sonic-button dataProvider="first_name" debug>data.first_name</sonic-button>
+    <!-- Get the user Last name -->
+    <sonic-fetch serviceURL="https://reqres.in" dataProvider="last_name" endPoint="api/users/2" key="data.last_name"></sonic-fetch>
+    <sonic-button dataProvider="last_name" debug>data.last_name</sonic-button>
+    <!-- Get the user email -->
+    <sonic-fetch serviceURL="https://reqres.in" dataProvider="email" endPoint="api/users/2" key="data.email"></sonic-fetch>
+    <sonic-button dataProvider="email" debug>data.email</sonic-button>
+  </template>
+</sonic-code>
+
+## Text mode
+
+if the mime type of the content returned by the service begins with **text/**, then the dataProvider has a key named "text" which contains the text returned by the service.
+
+<sonic-code>
+  <template>
+    <sonic-fetch endPoint="README.md" dataProvider="fetchText"></sonic-fetch>
+    <sonic-button dataProvider="fetchText" debug>Hover to see the data</sonic-button>
+  </template>
+</sonic-code>
+
+## NoLoader
+
+The noLoader attribute disables display of the default loader
+
+<sonic-code>
+  <template>
+    <sonic-fetch noLoader serviceURL="https://reqres.in" endPoint="api/users?page=2" dataProvider="myDataObj"></sonic-fetch>
+    <sonic-button dataProvider="myDataObj" debug>Basic fetch with noLoader attribute</sonic-button>
+  </template>
+</sonic-code>
+
+
+
+
+<!--
+ ## Summary
+ Extends mixins : Fetcher, [Subscriber](#core/components/functional/subscriber/subscriber.md/subscriber)
+ 
+ ### Configuration via les attributs
+
+| nom          | sur quelle balise | Description | Exemple de valeur | défaut / requis |
+|-----|-----|---|---|---|
+| serviceURL   |Fetcher ou un de ses parents | URL de base des services. | http://la-billetterie.net/api/v2 | domain du site |
+| endpoint   |Fetcher | point d'accès d'un service | user/2 | valeur de l'attribut dataProvider |
+| dataProvider  |Fetcher ou un de ses parents | Identifiant d'un publisher qui stock les données, voir [subscriber](#core/components/functional/subscriber/subscriber.md/subscriber). | billetterie/user/2 | *REQUIS* |
+| headersDataProvider  |Fetcher ou un de ses parents | Identifiant d'un publisher qui stock les données destinées à être envoyées en entêtes de la requetes | MyCoockieHEaders | null |
+| key  |Fetcher  | extrait une sous propriété de la donnée chargée avant de l'assignée à son publisher | ma.data | null |
+
+ *Si la données est `{ma:{data:{a:1,b:2}}}` et `key="ma.data"`, la données disponible dans le composant sera `{a:1, b:2}`*
+ 
+ ### Intégration auto de basic auth (pour tester une api qui nécessite une authentification) 
+
+ Fetch utilise le service pour générer le token et l'ajoute au header de l'appel qui récupère les données.
+
+| nom           | sur quelle balise | Description | Exemple de valeur | défaut / requis |
+|-----|-----|---|---|---|
+| userName      | Fetcher ou un de ses parents | Nom de l'utilisateur | DjuDju | null |
+| password      | Fetcher ou un de ses parents | mot de passe | pom_549 | null |
+| tokenProvider | Fetcher ou un de ses parents | point d'accès du service fournissant le token | auth | null |
+| token | Fetcher ou un de ses parents | A fournir à la place des autres attributs si on le possède | q<d34gb | null |
+
+ ### Autres choses utiles
+ L'attribut *noLoader* du composant permet de désactiver l'affichage du loader par défaut.
+ On peut appeler la methode invalidate() sur le publisher associé au  composant pour declencher le rechargement des données.
+ endPoint est une propriété réctive, par conséquent, sa modification, manuelle via template ou data binbding provoque la mise à jour du contenu.
+-->
+

package/docs/src/core/components/functional/if/if.md

@@ -0,0 +1,16 @@
+# if
+
+The **sonic-if** component shows its content based on the value of its reactive property names **condition**
+
+<sonic-code>
+  <template>
+<div dataProvider="visibilitySettings" formDataProvider="visibilitySettings">
+  <sonic-checkbox label="Show evacuation plan" name="togglePlan" unique checked value="true"></sonic-checkbox>
+  <sonic-if  data-bind ::condition="$togglePlan" class="mt-4 block">
+  <sonic-image src="https://www.thebaron.info/assets/mail/concorde-evacuation.jpg" rounded="md" ratio="654/463"></sonic-image>
+  </sonic-if>
+</div>
+  </template>
+</sonic-code>
+
+

package/docs/src/core/components/functional/list/list.md

@@ -0,0 +1,199 @@
+# List
+
+The **sonic-list** component creates list items.
+
+
+List extends the mixins  [Subscriber](#docs/_core-concept/subscriber.md/subscriber) and Fetcher : 
+* As a Subscriber it as a **props** reactive property (basically an array of data) and its data is associated to a publisher via its dataProvider attribute.
+* List doesn't Fetch by default (see below for activation).
+
+
+## Template
+
+The list component loops over its template children to render each items of its props data.  
+Consider the following example using **2 templates** and **9 items** :    
+- First template will render the first item.  
+- Second template will render the second item.  
+- Then back to the first template and so on and so forth.
+
+Note that for each line there is a dataProvider found at *[list dataProvider name]/liste-item/[line index or key]*
+You can hover the list items in the examples to see it.
+
+<sonic-code>
+  <template>
+     <sonic-list dataProvider="listTemplateExample" class="grid grid-cols-3 gap-4" props='[{"id": "1"}, {"id": "2"}, {"id": "3"}, {"id": "4"}, {"id": "5"}, {"id": "6"}, {"id": "7"}, {"id": "8"}, {"id": "9"}]' debug>      
+     <template>
+        <div class="bg-neutral-100 text-center p-3">
+          <sonic-value key="id"></sonic-value>
+          <div class="text-xs">1st template</div>
+        </div>
+      </template>
+      <template>
+        <div class="bg-neutral-100 text-info text-center p-3">
+          <sonic-value key="id"></sonic-value>
+          <div class="text-xs">2nd template</div>
+        </div>
+      </template>
+    </sonic-list>
+  </template>
+</sonic-code>
+
+
+
+## TemplateKey / data-value
+
+The **templateKey** attribute allows you to bind a template to a props item.  
+Consider the following example :  
+- The list **templateKey** attribute is set to the value **tpl** (any name would do)
+- Items 4,5 and 6 are each one **referencing** a templates with a matching **data-value** attribute
+
+<sonic-code>
+  <template>
+    <sonic-list
+      templateKey="tpl"
+      class="grid gap-3"
+      dataProvider="TemplateKeyExample"
+      props='[
+        {"id":"1", "default": "The first template with no data-value is used"},
+        {"id":"2", "default": "The second template with no data-value is used"},
+        {"id":"3", "default": "Back to the first template with no data-value"},
+        {"id":"4", "tpl":"custom-tpl-danger"},
+        {"id":"5", "tpl":"custom-tpl-info"},
+        {"id":"6", "tpl":"custom-tpl-success"},
+        {"id":"7", "tpl": "Non-valid tpl name, Back to the first template with no data-value"}
+      ]'
+      debug
+    >
+      <template>
+        <div class="p-2 border rounded text-neutral-900">
+          <sonic-value key="id"> : </sonic-value>
+          <b>First</b> template with no <b>data-value</b> attribute
+        </div>
+      </template>
+      <template data-value="custom-tpl-danger">
+        <div class="p-2 border rounded text-danger">
+          <sonic-value key="id"> : </sonic-value>
+          data-value : <b>custom-tpl-danger</b>
+        </div>
+      </template>
+      <template data-value="custom-tpl-info">
+        <div class="p-2 border rounded text-info">
+          <sonic-value key="id"> : </sonic-value>
+          data-value : <b>custom-tpl-info</b>
+        </div>
+      </template>
+      <template data-value="custom-tpl-success">
+        <div class="p-2 border rounded text-success">
+          <sonic-value key="id"> : </sonic-value>
+          data-value : <b>custom-tpl-success</b>
+        </div>
+      </template>
+      <template>
+        <div class="p-2 border rounded text-neutral-400">
+          <sonic-value key="id"> : </sonic-value>
+          <b>Second</b> template with no <b>data-value</b> attribute <br>
+          This one is used if it <b>follows another data-item</b> with <b>no tpl</b> specified in the props
+        </div>
+      </template>
+    </sonic-list>
+  </template>
+</sonic-code>
+
+## Special templates : list item separator / empty list view
+
+A special template with attribute **data-value="separator"** will act as a separator between each list item
+
+<sonic-code>
+  <template>
+    <sonic-list props='[{"id":"1"},{"id":"2"},{"id":"3"}]' dataProvider="ListSeparatorDemo">
+      <template><sonic-value key="id"></sonic-value></template>
+      <template data-value="separator"> 🤜 </template>
+    </sonic-list>
+  </template>
+</sonic-code>
+
+The same principle can be used to handle empty lists using a template with attribute **data-value="no-item"**
+
+
+## Fetch
+
+Enables the list to get data from an external API in order to fill its **props** attribute with an **array of items**
+See the [Fetch] web component(#core/components/functional/fetch/fetch.md/fetch)
+<sonic-code>
+  <template>
+    <sonic-list 
+    props='["a", "b", "c"]' fetch
+    serviceURL="https://reqres.in"
+    dataProvider="api/users" 
+    key="data"
+    class="grid grid-cols-1" debug>
+        <template>
+          <docs-user></docs-user>
+        </template>
+    </sonic-list>
+  </template>
+</sonic-code>
+
+## Extract Values
+
+Example of using the `extractValues` attribute with a service.
+As in the previous example, the `fetch` attribute indicates that a service call should be made.
+Note that we use:
+* the property `_metadata_` added by the list component to display the key of the extracted value
+* the special property `_self_` that allows targeting the item itself. This is useful here because there is no sub-property; we are directly dealing with a string.
+<sonic-code>
+  <template>
+   <sonic-list
+      debug
+      fetch
+      serviceURL="https://reqres.in"
+      dataProvider="list-extract-values-test"
+      endPoint="api/users/2"
+      key="data"
+      extractValues
+    >
+      <template>
+        <div class="flex items-center">
+          <span data-bind ::inner-html="$_metadata_.key  : " class="bold w-24"></span>
+          <span data-bind ::inner-html="$_self_"></span>
+          <sonic-if data-bind ::condition="|'$_metadata_.key' == 'avatar'">
+            <sonic-image data-bind ::src="$_self_" rounded="full" ratio="1/1" class="w-20 block"></sonic-image>
+          </sonic-if>
+        </div>
+      </template>
+    </sonic-list>
+  </template>
+</sonic-code>
+
+## Additionnal tips
+
+* If the result of the request is an object, it is nested within an array to ensure functionality.
+* The invalidate() method can be called on its publisher to trigger data reloading.
+* Each list item publisher has a "_parent_" property pointing to the list publisher
+
+
+
+<!-- 
+## FormDataProvider
+
+<sonic-alert status="error" background>À déplacer dans la bonne doc</sonic-alert>
+
+<sonic-code>
+  <template>
+  <div formDataProvider="profileInfos">
+    <form>
+      <sonic-fieldset label="Edit profile">
+        <sonic-form-layout>
+          <sonic-input label="First name" type="text" name="first_name" value="Sponge" size="sm"></sonic-input>
+          <sonic-input label="Last name" type="text" name="last_name" value="Bob" size="sm"></sonic-input>
+          <sonic-input label="email" type="email" name="email" value="bob@krustykrab.com" size="sm"></sonic-input>
+          <sonic-input label="Image url" type="text" name="avatar" value="http://www.bobleponge.fr/goodies/avatars/avatar-bob-eponge_Bob-Eponge-coiffure.jpg" size="sm"></sonic-input>
+        </sonic-form-layout>
+      </sonic-fieldset>
+    </form>
+  </div>
+  <sonic-card  dataProvider="profileInfos">
+    <docs-user ></docs-user>
+  </sonic-card>
+  </template>
+</sonic-code> -->

package/docs/src/core/components/functional/mix/mix.md

@@ -0,0 +1,41 @@
+# Mix
+
+Mix allows you to mix several subsets of dataProvider in a new key/value structure which is itself associated with a new dataProvider. The data update is then bidirectional.
+
+Dot notation is supported to extract a sub-part of the data.
+
+For example, if we declare dataproviders as follows :
+<sonic-code>
+  <template>
+    <sonic-subscriber dataProvider="dataToMixA" props='{"foo":{"bar":2}}'></sonic-subscriber>
+    <sonic-subscriber dataProvider="dataToMixB" props='{"baz":3}'></sonic-subscriber>
+  </template>
+</sonic-code>
+We can rearrange the data as follows
+<sonic-code>
+  <template>
+    <sonic-mix dataProvider="mixedData" composition='{"either":"dataToMixB","orThat":"dataToMixA.foo.bar"}'>
+      <div>Value of dataToMixA.foo.bar and mixedData.orThat : <sonic-value key="orThat"></sonic-value></div>
+      <div>Value of dataToMixB.baz and mixedData.either.baz : <sonic-value key="either.baz"></sonic-value></div>
+    </sonic-mix>
+  </template>
+</sonic-code>
+Then we can change values in both dataProviders programaticaly this way, they will stay in sync
+<sonic-code language="javascript">
+  <template>
+  SonicPublisherManager.get("mixedData").either.baz=6;
+  SonicPublisherManager.get("dataToMixB").baz=8;
+  SonicPublisherManager.get("dataToMixA").foo.bar=8;
+  SonicPublisherManager.get("mixedData").orThat=6;
+  </template>
+</sonic-code>
+Or by using a form element
+<sonic-code>
+<template>
+<sonic-input label="mixedData.orThat" formDataProvider="mixedData" name="orThat"></sonic-input>
+</template>
+</sonic-code>
+
+
+
+

package/docs/src/core/components/functional/queue/queue.md

@@ -0,0 +1,87 @@
+# Queue
+
+**sonic-queue** loads content in batches based on the expression provided in the dataProviderExpression attribute.
+
+* Each batch is loaded by a [List component](#core/components/functional/list/list.md/list) whose dataProvider is created from the dataProviderExpression attribute.
+* Upon initialization, it looks at the dataFilterProvider attribute, which provides the address of a publisher.
+If this attribute is found, Queue listens to the provided publisher and resets itself whenever the content of the publisher is modified.
+The values provided in this publisher are added as parameters to each request.
+* The key property can be used to target a specific property in the API response as fetch does.
+ 
+List extends the mixin [Subscriber](#docs/_core-concept/subscriber.md/subscriber)
+
+
+<sonic-code>
+  <template>
+    <sonic-queue
+        class="grid grid-cols-3 gap-3"
+        dataProviderExpression="communes?limit=$limit"
+        limit="30"
+        serviceURL="https://geo.api.gouv.fr/"
+        debug
+      >
+      <template>
+        <div data-bind ::inner-html="$nom" class="bg-neutral-100 p-2">
+          queue
+        </div>
+      </template>
+    </sonic-queue>
+  </template>
+</sonic-code>
+
+<sonic-code>
+  <template>
+    <sonic-queue
+      lazyload
+      dataProviderExpression="api/users?page=$offset&per_page=$limit"
+      offset="2"
+      limit="5"
+      dataFilterProvider="filter"
+      targetRequestDuration="500"
+      serviceURL="https://reqres.in"
+      key="data"
+      debug
+    >
+        <template>
+          <div class="flex px-4 py-3 items-center gap-4">
+            <sonic-image data-bind ::src="$avatar" rounded="full" ratio="1/1" class="w-20 block"></sonic-image>
+            <div>
+              <div class="text-bold text-2xl mb-2">
+                <span data-bind ::inner-html="$first_name"></span>
+                <span data-bind ::inner-html="$last_name"></span>
+              </div>
+              <sonic-button data-bind ::href="mailto|$email" size="xs" variant="outline"> Contact </sonic-button>
+            </div>
+          </div>
+          <div class="border-0 border-t-2 border-t-neutral-200 w-full border-solid"></div>
+        </template>
+    </sonic-queue>
+  </template>
+</sonic-code>
+
+<sonic-code>
+  <template>
+    <sonic-list
+      lazyload
+      fetch
+      dataProvider="api/users?page=2&per_page=5"
+      serviceURL="https://reqres.in"
+      key="data"
+      debug
+    >
+      <template>
+        <div class="flex px-4 py-3 items-center gap-4">
+          <sonic-image data-bind ::src="$avatar" rounded="full" ratio="1/1" class="w-20 block"></sonic-image>
+          <div>
+            <div class="text-bold text-2xl mb-2">
+              <span data-bind ::inner-html="$first_name"></span>
+              <span data-bind ::inner-html="$last_name"></span>
+            </div>
+            <sonic-button data-bind ::href="mailto|$email" size="xs" variant="outline"> Contact </sonic-button>
+          </div>
+        </div>
+        <div class="border-0 border-t-2 border-t-neutral-200 w-full border-solid"></div>
+      </template>
+    </sonic-list>
+  </template>
+</sonic-code>

package/docs/src/core/components/functional/router/router.md

@@ -0,0 +1,108 @@
+# Router
+
+The router observes the document.location changes and updates its view as follows
+
+## Data-route / Basic
+
+When the data-route attribute of a template matches the current url, the content of this template is rendered
+
+<sonic-code>
+  <template>
+    <div class="flex gap-2 items-center">
+      <sonic-button href="#core/components/functional/router/router.md/router#home" size="xs">Home</sonic-button>
+      <sonic-button href="#core/components/functional/router/router.md/router#about" size="xs">About</sonic-button>
+      <sonic-button href="#core/components/functional/router/router.md/router#work" size="xs">Work</sonic-button>
+      <sonic-button href="#core/components/functional/router/router.md/router#contact" size="xs">Contact</sonic-button>
+    </div>
+    <sonic-router>
+      <template data-route="#home">
+        <div class="text-center text-neutral-700 border rounded text-4xl  my-6 p-3 ">Home</div>
+      </template>
+      <template data-route="#about">
+        <div class="text-center text-neutral-700 border rounded text-4xl  my-6 p-3 ">About</div>
+      </template>
+      <template data-route="#work">
+        <div class="text-center text-neutral-700 border rounded text-4xl  my-6 p-3 ">Work</div>
+      </template>
+      <template data-route="#contact">
+        <div class="text-center text-neutral-700 border rounded text-4xl  my-6 p-3 ">Contact</div>
+      </template>
+    </sonic-router>
+  </template>
+</sonic-code>
+
+## Data-route / Regexp
+
+You can use any RegExp in the data-route attribute of your templates to match the current location and to extract variables from it using capturing groups.
+A dataProvider attribute is generated using the dataProviderExpression where $1, $2... are replaced with this variables.
+
+**e.g.**, data-route="#couleur_<b class="text-danger">(\d+)</b>" => dataProviderExpression="api/unknown/<b class="text-danger">$1</b>"
+
+The rendered content of the matching template is scoped with this  **dataProvider**.
+You can make creative usage on this feature to generate dynamic content based on services.
+
+<sonic-code>
+  <template>
+    <sonic-list fetch dataProvider="api/unknown" key="data" class="flex gap-2 items-center" >
+      <template>
+        <sonic-button radio size="xs" data-bind ::href="#core/components/functional/router/router.md/router#couleur_$id">
+          <span data-bind ::inner-html="ucFirst|$name"></span>
+        </sonic-button>
+      </template>
+    </sonic-list>
+    <sonic-router>
+      <template data-route="#couleur_(\d+)" dataProviderExpression="api/unknown/$1">
+        <sonic-fetch>
+          <input type="color" disabled data-bind ::value="$data.color" class=" w-full h-10 my-3" />
+        </sonic-fetch>
+      </template>
+    </sonic-router>
+  </template>
+</sonic-code>
+
+## Data-route / Url-pattern
+
+Same as RegExp but using <a href="https://www.npmjs.com/package/url-pattern" target="_blank">url patterns</a>  
+**e.g.**, data-route="#couleur_<b class="text-danger">:id</b>" => dataProviderExpression="api/unknown/<b class="text-danger">:id</b>"
+
+<sonic-code>
+  <template>
+    <sonic-list fetch dataProvider="api/unknown" key="data" class="flex gap-2 items-center" >
+      <template>
+        <sonic-button radio size="xs" data-bind ::href="#core/components/functional/router/router.md/router#couleur_$id">
+          <span data-bind ::inner-html="ucFirst|$name"></span>
+        </sonic-button>
+      </template>
+    </sonic-list>
+    <sonic-router>
+      <template data-route="/*#couleur_:id" dataProviderExpression="api/unknown/:id">
+        <sonic-fetch>
+          <input type="color" disabled data-bind ::value="$data.color" class=" w-full h-10 my-3" />
+        </sonic-fetch>
+      </template>
+    </sonic-router>
+  </template>
+</sonic-code>
+
+## Redirect
+
+Redirect allows to redirect to a url when a data is provided.
+Here Redirect waits that a data is available in the property *theData* of the dataProvider *stupid-data-set-id*
+We are then redirected to the url *#data-is-set* which does nothing in itself.
+
+<sonic-code>
+  <template>
+    <sonic-redirect to="#core/components/functional/router/router.md/router#data-is-set" dataProvider="stupid-data-set-id" onData="theData"></sonic-redirect>
+    <div class="flex gap-2 mb-4" formDataProvider="stupid-data-set-id">
+      <sonic-button radio name="theData" value="Some Data" size="xs">
+        Enter data
+      </sonic-button>
+      <sonic-button radio name="theData" value="" href="javascript:history.back();" size="xs">
+        Delete the data and do a history.back()
+      </sonic-button>
+    </div>
+    
+  </template>
+</sonic-code>
+
+Example of use : use with a router and a submit to manage the steps of login/logout, display of user info.