@supersoniks/concorde 4.5.2 → 4.7.0

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

@@ -1,199 +1,65 @@
 # 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>
+> **Try offline:** `serviceURL="/docs-mock-api"` and `dataProvider="api/users"` with `key="data"` — see [Local API demos](#docs/_misc/docs-mock-api.md/docs-mock-api). Recommended patterns: [Data flow](#docs/_core-concept/dataFlow.md/dataFlow).
+
+The **sonic-list** component renders one row per entry in **`props`** (array from fetch or set on the element).
+
+List extends [Subscriber](#docs/_core-concept/subscriber.md/subscriber) and **Fetcher**:
+* **Subscriber** — `props` + `dataProvider`
+* **Fetcher** — optional `fetch` + `serviceURL` / `key` (see [Fetch](#core/components/functional/fetch/fetch.md/fetch))
+
+## Row renderer (`items`) — recommended
+
+From a **Lit** parent, pass a function on the **`items`** property (`ListItems`). Each row is wrapped in a `sonic-subscriber` with `dataProvider="…/list-item/n"` (hover rows with `debug`).
+
+```typescript
+private items = ({ first_name, last_name, email, avatar }) => html`
+  <sonic-image src=${avatar} …></sonic-image>
+  <div>${first_name} <b>${last_name}</b></div>
+  <div>${email}</div>
+`;
+
+html`<sonic-list
+  fetch
+  dataProvider="api/users"
+  key="data"
+  serviceURL="/docs-mock-api"
+  .items=${this.items}
+></sonic-list>`;
+```
+
+Use **`.items=${fn}`** (property binding): Lit passes functions only as properties, not as HTML attributes — `@property({ type: Function })` does not change that. Same for **`.noItems`**, **`.separator`**, **`.skeleton`**. The callback receives each row object (replacing `data-bind` / `<sonic-value>` in a `<template>`).
+
+Live demo + TypeScript source (one file, no Markdown copy):
+
+<docs-lit-demo for="docs-users-list"></docs-lit-demo>
+
+Implementation: `src/docs/example/docs-users-list.ts` — row markup in the **`items`** callback (`item.first_name`, …), same idea as replacing `data-bind` / `<sonic-value>` in a `<template>`.
+
+## Alternating row layouts
+
+Use **`metadata`** (`even`, `odd`, `firstChild`, …) or fields on each item (e.g. `tpl` with `templateKey`):
+
+<docs-lit-demo for="docs-list-alternate-demo"></docs-lit-demo>
+
+<docs-lit-demo for="docs-list-template-key-demo"></docs-lit-demo>
+
+## Separator and empty list
+
+<docs-lit-demo for="docs-list-separator-demo"></docs-lit-demo>
+
+## Fetch + `extractValues`
+
+<docs-lit-demo for="docs-list-extract-values-demo"></docs-lit-demo>
+
+## HTML `<template>` children (integration without Lit)
+
+For **plain HTML** hosts, you can still declare **`<template>`** children (and `data-value` for `templateKey`, `separator`, `no-item`). That path is for [HTML integration](#docs/_misc/html-integration.md/html-integration) — not used in Concorde doc live demos.
+
+Each list row still gets `dataProvider="[list]/list-item/[index]"`.
 
 ## 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> -->
+* If the request returns an object, it is wrapped in an array (unless `extractValues` is set).
+* Call **`invalidate()`** on the list publisher to reload fetch data.
+* Each row publisher exposes **`_parent_`** pointing at the list publisher.

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

@@ -21,7 +21,7 @@ const tagName = "sonic-list";
  * Voir [fetcher](./?path=/docs/core-components-functional-fetch--basic) pour la configuration des autres attributs.
  * * Chaque élément créé est englobé dans un objet [Subscriber](./?path=/docs/miscallenous-🔔-subscriber--page).<br>
  *  Un dataProvider y est associé a l'adresse suivante *dataProvider-de-la-liste$/*index-de-la-ligne-courante*
- *  Les données de la ligne sont donc disponible pour les élements internes (subscribers, data-binding)
+ *  Les données de la ligne sont donc disponible pour les élements internes (subscribers)
  *  * Lors du chargement un objet loader inline est affiché.
  *  * Si le résultat de la requête est un objet, il est imbriqué dans un tableau pour garantir le fonctionnement.<br>
  * Cependant, si l'attribut `extractValues` est présent, les valeurs des propriétés de l'objet sont mises dans  dans un tableau pour le rendu.
@@ -48,7 +48,7 @@ export type ListItemMetadata = {
 // Simplifier le type ListItems pour n'être qu'une fonction
 export type ListItems = (
   item: any,
-  metadata: ListItemMetadata
+  metadata: ListItemMetadata,
 ) => DirectiveResult;
 
 @customElement(tagName)
@@ -73,6 +73,7 @@ export class List extends Fetcher(Subscriber(TemplatesContainer(LitElement))) {
 
   @property({
     type: Function,
+    attribute: false,
   }) /**add a getter setter check if the value is a ListItems befor assignation */
   get items(): ListItems | undefined {
     return this._items;
@@ -83,9 +84,9 @@ export class List extends Fetcher(Subscriber(TemplatesContainer(LitElement))) {
     this.requestUpdate();
   }
 
-  @property({ type: Function }) noItems?: () => DirectiveResult;
-  @property({ type: Function }) skeleton?: () => DirectiveResult;
-  @property({ type: Function }) separator?: () => DirectiveResult;
+  @property({ type: Function, attribute: false }) noItems?: () => DirectiveResult;
+  @property({ type: Function, attribute: false }) skeleton?: () => DirectiveResult;
+  @property({ type: Function, attribute: false }) separator?: () => DirectiveResult;
 
   connectedCallback() {
     this.noShadowDom = "";
@@ -245,7 +246,7 @@ export class List extends Fetcher(Subscriber(TemplatesContainer(LitElement))) {
   private handleProgrammaticTemplates(
     item: any,
     metadata: ListItemMetadata,
-    key: string | number
+    key: string | number,
   ): DirectiveResult | null {
     if (!this.items) return null;
 
@@ -347,7 +348,7 @@ export class List extends Fetcher(Subscriber(TemplatesContainer(LitElement))) {
         const programmaticTemplate = this.handleProgrammaticTemplates(
           item,
           metadata,
-          key
+          key,
         );
         if (programmaticTemplate) {
           return html`${programmaticTemplate}${!isLastChild

package/src/core/components/functional/queue/queue.demo.ts

@@ -24,7 +24,7 @@ export class QueueDemo extends LitElement {
     return html`
       <sonic-queue
         class="grid grid-cols-3 gap-3"
-        serviceurl="https://geo.api.gouv.fr/"
+        serviceurl="/docs-mock-api/geo/"
         dataproviderexpression="communes?limit=$limit"
         limit="30"
         .items=${this.items}

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

@@ -1,87 +1,72 @@
 # 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>
+> **Try offline:** `serviceURL="/docs-mock-api"` — see [Local API demos](#docs/_misc/docs-mock-api.md/docs-mock-api). Row rendering: [Data flow](#docs/_core-concept/dataFlow.md/dataFlow) (`.items` property binding).
+
+**sonic-queue** loads data in **batches**. Each batch is an internal [List](#core/components/functional/list/list.md/list) with its own `dataProvider` (`…/list-item/0`, `…/1`, …).
+
+| Mechanism | Role |
+|-----------|------|
+| **`dataProviderExpression`** | API path template; `$offset` and `$limit` are replaced per batch |
+| **`lazyload`** | Load the next batch when the user scrolls near the end |
+| **`dataFilterProvider`** | Publisher id of a form (`formDataProvider`); field values are merged into the request query string |
+| **`filteredFields`** | Optional list of form field names to **exclude** from the query (space-separated) — omit when every field should be sent |
+| **`.items`**, **`.noItems`**, **`.separator`**, **`.skeleton`** | Lit callbacks forwarded to each batch list (use the **dot** — functions are properties, not attributes) |
+
+## Lazy load — `$offset` and `$limit`
+
+When the expression contains **`$offset`** and **`$limit`**, the queue:
+
+1. Fetches the first batch with `offset=0` (or the initial `offset` attribute) and `per_page=$limit`.
+2. On scroll, appends a batch with `offset` increased by the previous batch size.
+3. Stops when a batch returns fewer rows than `limit` (or none).
+
+The doc mock implements this on `GET /docs-mock-api/api/users?offset=…&per_page=…` (`paginateUsers` in `src/docs/mock-api/router.ts`).
+
+<docs-lit-demo for="docs-queue-users-demo"></docs-lit-demo>
+
+Wrap the queue in a **fixed height** with **`overflow-y-auto`** so lazy load triggers when scrolling inside the box (same layout as the [TS starter](https://github.com/supersoniks/create-concorde-ts-starter) `demo-queue-templates`).
+
+Try scrolling after load — batches of 4 users. Search e.g. `George`, `Bluth`, or `zzz` for empty results.
+
+### Expression example
+
+```typescript
+html`<sonic-queue
+  lazyload
+  serviceURL="/docs-mock-api"
+  dataProviderExpression="api/users?offset=$offset&limit=$limit"
+  key="data"
+  limit="4"
+  class="grid max-h-96 overflow-y-auto"
+  .items=${this.renderUser}
+></sonic-queue>`;
+```
+
+Without **`$offset`** in the expression, the queue behaves like a single list (one batch), e.g. geo communes below.
+
+## Filter — `dataFilterProvider` + `q`
+
+One search field (`name="q"`) on `formDataProvider="filter"`. The queue listens via **`dataFilterProvider="filter"`** and, on change:
+
+1. Resets loaded batches.
+2. Appends each non-empty form field to the query (here only **`q`** — no `filteredFields` needed).
+3. Fetches again from offset `0`.
+
+Use **`filteredFields`** only when the form has extra fields that must **not** be sent to the API (e.g. `filteredFields="rememberMe internalId"`).
+
+The mock API filters before pagination — same haystack logic as the starter (`filterDocsUsers` in `src/docs/mock-api/fixtures.ts`, used by `paginateUsers` in `router.ts` / Service Worker):
+
+```typescript
+const haystack = `${first_name} ${last_name} ${email}`.toLowerCase();
+return haystack.includes(q);
+```
+
+## Simple batch (no lazy scroll)
+
+Geo communes: expression uses **`$limit` only** (no `$offset`) — one request, one batch.
+
+<docs-lit-demo for="docs-queue-geo-demo"></docs-lit-demo>
+
+## HTML `<template>` children
+
+Optional for hosts without Lit — see [HTML integration](#docs/_misc/html-integration.md/html-integration).

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

@@ -32,9 +32,9 @@ const tagName = "sonic-queue";
 export default class Queue extends Subscriber(LitElement, {} as QueueProps) {
   @property({ type: Array }) templates: Array<HTMLTemplateElement> | null =
     null;
-  @property({ type: Function }) items: ListItems | null = null;
-  @property({ type: Function }) noItems: ListItems | null = null;
-  @property({ type: Function }) skeleton: ListItems | null = null;
+  @property({ type: Function, attribute: false }) items: ListItems | null = null;
+  @property({ type: Function, attribute: false }) noItems: ListItems | null = null;
+  @property({ type: Function, attribute: false }) skeleton: ListItems | null = null;
   lastRequestTime = 0;
   key = "";
 
@@ -151,7 +151,7 @@ export default class Queue extends Subscriber(LitElement, {} as QueueProps) {
       if (Array.isArray(value))
         value = value.filter((v: string | null) => v !== null);
       if (
-        (this.filteredFields && !filteredFieldsArray.includes(f)) ||
+        (this.filteredFields && filteredFieldsArray.includes(f)) ||
         value == null ||
         value.toString() === ""
       )