@supersoniks/concorde 3.1.77 → 3.1.78

package/docs/src/docs/_core-concept/overview.md

@@ -0,0 +1,57 @@
+# lit + tailwind + vite
+
+**Some notes for an overview of Concorde's functioning**
+
+## Standard Web components
+A web component is simply a **custom HTML element** created using web standards:
+
+**web component** = [Custom Elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) + [shadowDom](https://developer.mozilla.org/fr/docs/Web/Web_Components/Using_shadow_DOM) + [HTML templates](https://developer.mozilla.org/fr/docs/Web/HTML/Element/template)
+
+## Lit Library
+
+Concorde components are written using the lightweight Lit library: https://lit.dev/.
+
+A good portion of the elements documented on the Lit website are standard JavaScript concepts (e.g., [mixins](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes#mix-ins), [tagged template literals](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Template_literals#gabarits_%C3%A9tiquet%C3%A9s)).
+
+The **library simplifies the writing of web components** by automating certain tasks:
+
+- Creation of an **open mode shadow DOM** (the component is accessible from the outside via its shadow root property).
+- [Rendering function](https://lit.dev/docs/components/rendering/) based on [tagged template literals](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Template_literals#gabarits_%C3%A9tiquet%C3%A9s)
+- [Reactive properties](https://lit.dev/docs/components/properties/) that trigger rendering when modified.
+
+Our use of Lit rarely goes beyond this [hello world](https://lit.dev/playground/#sample=examples/hello-world)
+
+## Typescript Language
+
+We write the components in [TypeScript](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html), which is then compiled into JS.
+
+Static and inferred typing provides stronger validation of the program's functioning during compilation.
+However, we often use the "any" type due to time constraints.
+
+Lit uses TypeScript to simplify development through metadata:
+- Simplified declaration of `custom elements` via @customElement
+- Generation of `reactive properties` via @property.
+
+☢️**Warning**:
+- During development, we operate in interpreted mode, which is faster but allows errors that won't pass during the build.
+- It is important to **build a distribution before pushing the code** to ensure everything is fine.
+
+## Compatibility with Classic JS Libraries
+
+Compatibility issues may arise when using JS libraries, particularly regarding DOM traversal.
+This is because these libraries are blocked from traversing the DOM due to the presence of the shadow DOM.
+Here are some examples of things that may cause problems:
+
+- Latest FontAwesome in SVG mode, icons are not replaced
+- Libraries associated with jQuery
+- document.getElementById
+- ...
+
+## Topics to Explore for Further Learning
+
+
+[🧱 Creating components](#docs/_getting-started/create-a-component.md/create-a-component)
+
+[🎨 Adding styles](#docs/_getting-started/theming.md/theming)
+
+[🥨 Sharing data](#docs/_getting-started/pubsub.md/pubsub)

package/docs/src/docs/_core-concept/subscriber.md

@@ -0,0 +1,76 @@
+# The subscriber mixin
+
+This is a mixin that is commonly extended by Concorde core components and destination components. Pure UI components usually don't extend it, especially those outside of form components.
+
+## DataProvider Attribute: Automatic Filling of Subscriber Properties
+
+Upon being added to the DOM (connectedCallback), subscribers search for the first occurrence of the `dataProvider` attribute in their parent's HTML structure.
+
+The value of this attribute is used to obtain a publisher via the PublisherManager (see [🥨 Sharing Data](#docs/_getting-started/pubsub.md/pubsub)).
+
+The subscriber then subscribes to the publisher as a data template to be filled.
+
+The reactive properties of the component reflect in real-time the properties with the same name in the publisher.
+
+This functionality is commonly used in the generic components [fetch](#core/components/functional/fetch/fetch.md/fetch), [queue](#core/components/functional/queue/queue.md/queue), and [list](#core/components/functional/list/list.md/list).
+
+If the subscriber is inside another subscriber, it can subscribe to a data of its parent using the attribute `subDataProvider = 'address.of.my.data'` instead of the parent's data. This allows for dynamic behavior.
+
+## Automated Translation
+
+In a similar manner, searching for ancestor attributes can be used to configure automatic translation for any property starting with "wording" and ending with a label identifier recognized by the wordingProvider API.
+
+Normally, this API is globally configured and not within the component. Therefore, remember to prefix translatable label identifiers present in the ticketing system, for example, with "wording".
+
+## Reactive Property `props`
+
+The value of this property can be provided as a JSON object or any other value. This value is then assigned to the associated publisher via the `dataProvider` attribute. As a result, the reactive properties of all subscribers associated with the same `dataProvider` are filled as mentioned above.
+
+## Disabling Automatic Filling of Reactive Properties
+
+It is possible to disable the automatic filling of reactive properties in a particular component. To do so, set the variable `noAutoFill = true` in the component's class. However, the reactive property `props` will still be updated.
+
+For example, `sonic-subscriber` and `sonic-fetch` have this attribute because they do not have reactive properties.
+
+**☢ CAUTION:** When creating an object of type Subscriber or Fetcher, make sure to use the mixins and not directly extend the concrete fetch component (`sonic-fetch`) and subscriber component (`sonic-subscriber`). This is because the `noAutofill = true` attribute is set in those components.
+
+**TIPS:** 
+If you disable automatic filling, you will likely make the rendering dynamic by writing expressions like `this.props.my.subproperty`. If `props` is updated, the rendering will be triggered. However, if `this.props.my.subproperty` is directly modified, the rendering will not be triggered. To achieve more reactivity, you can enable rendering when any subproperty is modified. Simply set the variable `renderOnPropsInternalChange = true` in the class that implements the corresponding mixin.
+
+## Data Binding
+
+Suppose that:
+
+- You have a subscriber subscribed to a publisher via its `dataProvider` attribute.
+- The published data has the following structure:
+
+<sonic-code language="javascript">
+  <template>
+    {"img": { "avatar": "my-avatar.jpg", "caption": "look at my smile" }, "email": "an.email@example.com" }
+  </template>
+</sonic-code>
+- We want to keep the display of an image and its `title` attribute up to date, as well as a "contact" button to email the person in the photo. The content of the subscriber could be as follows:
+
+<sonic-code language="html">
+  <template>
+<img data-bind ::src="$img.avatar" ::title="ucFirst|$img.caption" />
+<a data-bind ::href="mailto:$email" ::inner-html="$email"></a>
+  </template>
+</sonic-code>
+
+This example also illustrates:
+
+- Binding to subproperties using dot syntax, as done for the `src` attribute of the `img` tag.
+- Using a simple expression to include the property within a string, as in creating a `mailto` link.
+- Using formatting functions, as in the `title` attribute of the `img` tag. You can find (and add) formatting functions in the `core/utils/Format.ts` file.
+- Writing for properties that are in camel case. Convert everything to lowercase and add hyphens. Note that `innerHTML` (or `outerHTML`) is a special case where no hyphens are added between each letter.
+
+**Note:** Data binding implies that updating the `img.src` data via the publisher will change the photo without any additional calls.
+
+**Special Variables:**
+- `_self_` targets the root of the data. This is useful, for example, when the data is a pure string.
+- `_parent_` targets the parent publisher of the current publisher, if any. For example, the subscribers of lists have the complete data of the list as their parent.
+- `_metadata_` is only used in the case of *sonic-list* at the moment. In a simple list, `_metadata_` see the (list)[] component for further details
+
+**Disabling this functionality:**
+You can disable data binding if it is not needed by calling `DataBinding.disable()`.

package/docs/src/docs/_getting-started/concorde-outside.md

@@ -0,0 +1,143 @@
+# Installation
+
+## Starter
+
+The easiest way to use Concorde is by using the Concorde starter.  
+The following command creates a new Vite project in TypeScript mode with Tailwind and an example component to get started.
+
+<sonic-code language="shell">
+  <template>
+npx @supersoniks/create-concorde-ts-starter "project_name"
+  </template>
+</sonic-code>
+
+## Brand New Vite Project
+
+
+For a more manual configuration, you can refer to the following sections. <br/>
+However, the Tailwind configuration is not mentioned at the moment.
+
+
+### Creating the Project
+
+<sonic-code language="shell">
+  <template>
+# Pure JavaScript project
+yarn create vite --template vanilla-js
+# TypeScript project
+# (it is recommended to use this approach, which installs Lit separately if needed, via "yarn add lit")
+yarn create vite --template vanilla-ts
+# TypeScript + Lit project
+# (creating new web components, for example, to extend the fetch or subscriber mixins)
+yarn create vite --template lit-ts
+  </template>
+</sonic-code>
+
+Using Lit with TypeScript requires the following configuration in the "compilerOptions" section of the `tsconfig.json` file:
+
+<sonic-code language="json">
+  <template>
+"experimentalDecorators": true,
+"useDefineForClassFields": false
+  </template>
+</sonic-code>
+
+### Installing Concorde
+
+Navigate to the project folder created and perform the installation:
+
+<sonic-code language="shell">
+  <template>
+yarn add @supersoniks/concorde
+  </template>
+</sonic-code>
+
+### Development / Build
+
+<sonic-code language="shell">
+  <template>
+# Development (you can add `--host` after the command chain in package.json's dev script instead of typing it each time as shown below)
+yarn dev --host
+# Build
+yarn build
+  </template>
+</sonic-code>
+
+## Shortcut Imports
+
+Shortcut imports work by default in JavaScript, but in TypeScript, they are activated by choice as they inject data into *tsconfig.json*. Here is the command:
+
+<sonic-code language="shell">
+  <template>
+npx concorde enable-short-paths
+  </template>
+</sonic-code>
+
+Shortcut imports replace the actual paths with aliases as follows:
+
+* `@supersoniks/concorde/core/components/functional_or_ui/component/component` becomes `@supersoniks/concorde/functional_or_ui/component`
+* `@supersoniks/concorde/core/mixins_or_utils/class_name` becomes `@supersoniks/concorde/mixins_or_utils/class_name`
+
+The original paths remain accessible. Shortcut imports are used for the examples later in this documentation.
+
+## Usage
+
+### Simple Integration in HTML
+
+Import needed component in `main.ts` or wherever you want to use it:
+
+<sonic-code language="typescript">
+  <template>
+import "@supersoniks/concorde/ui/button";
+  </template>
+</sonic-code>
+
+Then in the render function ofyour component or in the HTML of the web page that includes the compiled JS, use the component as follows:
+
+<sonic-code>
+  <template>
+<sonic-button variant="outline">My button</sonic-button>
+  </template>
+</sonic-code>
+
+### Using a Mixin to Create a New Lit Component
+
+For example, create a file `my-element.ts` at the root:
+
+<sonic-code language="typescript">
+  <template>
+import { html, LitElement } from "lit";
+import { customElement, property } from "lit/decorators.js";
+import Fetcher from "@supersoniks/concorde/mixins/Fetcher";
+import Subscriber from "@supersoniks/concorde/mixins/Subscriber";
+
+@customElement("my-element")
+export class SonicComponent extends Fetcher(Subscriber(LitElement)) {
+  @property() email = "";
+  @property() first_name = "";
+  @property() last_name = "";
+
+  render() {
+    return html`<div>
+      ${this.first_name} ${this.last_name} : ${this.email}
+    </div>`;
+  }
+}
+  </template>
+</sonic-code>
+
+Import component `main.ts` or `main.js` or any other component that uses it to be compiled
+
+<sonic-code language="typescript">
+  <template>
+import "./my-element";
+  </template>
+</sonic-code>
+
+In the HTML of a JS or TS component or in the HTML of the web page containing the compiled JS:
+
+<sonic-code language="html">
+  <template>
+<my-element serviceURL="https://reqres.in" dataProvider="api/users/2" key="data"></my-element>
+  </template>
+</sonic-code>

package/docs/src/docs/_getting-started/create-a-component.md

@@ -0,0 +1,137 @@
+# Creating components
+
+## Where to put it?
+
+In this document, we consider the src directory of the project as the root.<br>
+We describe how we organize our components as an example, however it depends on your project.
+
+In concorde each component is currently organized in the following directory structure (at least we try):
+
+- **/core/components/functional/component-name/component-name.ts**  
+  Generic/functional/generally unstyled component.
+  The component usually doesn't use any other concrete components.
+- **/core/components/ui/component-name/component-name.ts**  
+  Generic but UI-oriented component.
+  The component usually only uses generic components and other UI components.
+- **la-billetterie/components/atoms/component-name/component-name.ts**  
+  The component is intended to have a concrete usage within our ticketing system **"la-billetterie"**.
+  It usually only uses generic components from `core` and possibly other atoms.
+- **la-billetterie/components/concrete-destination/component-name/component-name.ts**  
+  The component has a specific destination: (event / cart / gift card): `/components/destination/`
+  The component uses various components, usually from the `/components/atoms` directory.
+  It does not use components at the same level in the file hierarchy.
+
+## Starting from a Simple Model
+
+You can copy `example.ts` from the source to the desired destination to start with.
+This file contains a web component in the form of a class that extends the `Subscriber` mixin, with a reactive property and a render function.
+
+<sonic-code language="javascript">
+  <template>
+import { html, LitElement } from "lit";
+import { customElement, property } from "lit/decorators.js";
+import Subscriber from "@supersoniks/concorde/core/mixins/Subscriber";
+
+@customElement("sonic-example")
+export class SonicComponent extends Subscriber(LitElement) {
+  @property() text = "Example";
+  render() {
+    return html`${this.text}`;
+  }
+}
+  </template>
+</sonic-code>
+
+**You can remove the dependency on `Subscriber`** if automatic population of the component with external data is not required.
+For example, for a UI component:
+
+
+<sonic-code language="javascript">
+  <template>
+import { html, LitElement } from "lit";
+import { customElement, property } from "lit/decorators.js";
+
+@customElement("sonic-example")
+export class SonicComponent extends LitElement {
+  @property() text = "Example";
+  render() {
+    return html`${this.text}`;
+  }
+}
+  </template>
+</sonic-code>
+
+Regarding `Subscriber`, see:
+
+- [🔔 Subscriber](#docs/_core-concept/subscriber.md/subscriber)
+- [🥨 Sharing Data](#docs/_getting-started/pubsub.md/pubsub)
+
+### Naming the Component
+
+The class name is not necessarily important. However, it is important to **give it a component name prefixed with "sonic"** (or a prefix of your own) using the dedicated metadata already present in the copied document. For example, a button component would be named as follows:
+
+
+<sonic-code language="typescript">
+  <template>
+@customElement("sonic-button")
+  </template>
+</sonic-code>
+
+For less generic components with a specific destination, we advise to include the destination in the name.
+For example, for a "title" component in the "event" destination, the name would be simply:
+
+
+<sonic-code language="typescript">
+  <template>
+@customElement("sonic-event-title")
+  </template>
+</sonic-code>
+
+
+## Modifying It
+
+#### Creating Reactive Properties and Modifying the Render Function
+
+To do this, study the functioning of https://lit.dev and also refer to [Subscriber](#docs/_core-concept/subscriber.md/subscriber).
+
+#### HTML Structure of a Component
+
+The HTML structure of a component should remain as simple as possible.
+
+Ideally, there should be only one additional level of elements in addition to slots.
+
+- **The main component is already a wrapper**.
+  It receives classes to manage its layout, but it should not style internal elements.
+- **Slots handle the visual organization** of elements.
+- **The specificity of the component is expressed in this additional level** by adding a list, a functional native element (e.g., button), or another component.
+
+This leads to the creation of more components and thus raises questions about the hierarchical organization of files. However, this tends to atomize their roles.
+
+## Referencing It
+
+To compile the component, it needs to be referenced somewhere through an import statement. In particular, it is important to reference it in any component that uses it.
+
+In the case where it can be directly used in a page, it should also be globally referenced, especially considering the creation of **specific bundles** in the future.
+
+Here's where we add imports based on the component's location inside concorde as an example
+
+- **/core/components/functional/component-name/component-name.ts**  
+  In `/core/components/functional/functional.ts`, which is referenced in core.ts and imported in `index.ts`.
+- **/core/components/ui/component-name/component-name.ts**  
+  In `/core/components/ui/ui.ts`, which is referenced in core.ts and imported in `index.ts`.
+- **la-billetterie/components/atoms/component-name/component-name.ts**  
+  Nowhere else but where it will be used, except for possible **temporary** tests, for example, in `index.ts`.
+- **la-billetterie/components/concrete-destination/component-name/component-name.ts**  
+  In `la-billetterie/components/concrete-destination/destination-concrete.ts`. 
+  If it's a new destination, you'll need to create the corresponding import .ts file and import it in `la-billetterie.ts`.
+
+## Using It
+
+As a reminder, the component is simply integrated into the context by adding a tag with the component's name, for example:
+
+
+<sonic-code language="html">
+  <template>
+<sonic-event-title></sonic-event-title>
+  </template>
+</sonic-code>

package/docs/src/docs/_getting-started/my-first-subscriber.md

@@ -0,0 +1,174 @@
+# My first subscriber component
+
+Learn how to build a subscriber component, styled with tailwind, 
+which could be used as a regular component or could be filled from a dataprovider.
+
+## Create a classic lit component
+
+<sonic-code language="javascript" >
+  <template>
+  import { html, LitElement, nothing } from "lit";
+  import { customElement, property } from "lit/decorators.js";
+  // name component
+  @customElement("docs-user")
+  export class user extends LitElement {
+    // set a few props
+    @property({ type: String }) first_name = "";
+    @property({ type: String }) last_name = "";
+    @property({ type: String }) avatar = "";
+    @property({ type: String }) email = "";
+    // output
+    render() {
+      return html`
+        <img src="${this.avatar}"  /> <br>
+        ${this.first_name} ${this.last_name} <br>
+        ${this.email}`;
+    }
+  }
+  </template>
+</sonic-code>
+
+
+### Style with tailwind and ui components
+
+First export tailwind, in a tailwind.ts file, stylesheet to add it in our component when needed.
+
+<sonic-code language="javascript">
+  <template>
+  import { css, unsafeCSS } from "lit";
+  import tailwindImport from "./css/tailwind.css?inline";
+  export const tailwind = css`${unsafeCSS(tailwindImport)}`;
+  </template>
+</sonic-code>
+
+<sonic-code language="javascript">
+  <template>
+    import { html, LitElement, nothing } from "lit";
+    import { customElement, property } from "lit/decorators.js";
+    // add tailwind and needed components
+    import { tailwind } from "../tailwind";
+    import '@supersoniks/concode/ui/image'
+    import '@supersoniks/concode/ui/button'
+    import '@supersoniks/concode/ui/icon'
+    //
+    @customElement("docs-user")
+    export class user extends LitElement {
+      // add tailwind stylesheed
+      static styles = [tailwind];
+      @property({ type: String }) first_name = "";
+      @property({ type: String }) last_name = "";
+      @property({ type: String }) avatar = "";
+      @property({ type: String }) email = "";
+      // use utility class in your markup
+      render() {
+        return html`<div
+          class="flex items-center gap-3 rounded-md hover:bg-neutral-50 -mx-2 p-2"
+        >
+          <sonic-image
+            src=${this.avatar}
+            rounded="md"
+            ratio="1/1"
+            class="w-16 block"
+          ></sonic-image>
+          <div>
+            <div>
+              ${this.first_name} <span class="font-bold">${this.last_name}</span>
+            </div>
+            <div class="text-sm text-neutral-400">${this.email}</div>
+          </div>
+          <div class="ml-auto relative">
+            <sonic-button
+              href="mailto:${this.email}"
+              size="sm"
+              variant="outline"
+              shape="circle"
+              class="relative"
+              icon
+            >
+              <sonic-icon library="iconoir" name="chat-bubble"></sonic-icon>
+            </sonic-button>
+          </div>
+        </div>`;
+      }
+    }
+  </template>
+</sonic-code>
+
+### Basic usage
+
+Reactive properties can be filled by its attributes as a simple lit component.
+
+<sonic-code>
+<template>
+<docs-user
+  first_name="Paul"
+  last_name="Metrand"
+  avatar="/img/paul_metrand_xs.jpg"
+  email="paulmetrand@concorde.fr"
+  ></docs-user>
+</template>
+</sonic-code>
+
+## Add Subscriber mixin
+
+Import Subscriber mixin, and add it around LitElement.
+<sonic-code language="javascript">
+  <template>
+    import { html, LitElement, nothing } from "lit";
+    import { customElement, property } from "lit/decorators.js";
+    import { tailwind } from "../tailwind";
+    import Subscriber from "@supersoniks/concorde/core/mixins/Subscriber";
+    @customElement("docs-user")
+    export class user extends Subscriber(LitElement) {
+      //...
+    }
+  </template>
+</sonic-code>
+
+## Autofill properties from a dataProvider
+
+Without a dataProvider attribute, a subscriber set its own dataprovider from first ancestor found, and then reactive properties automatically filled and update from it.
+A fetcher is a simple component which set its fetch result to props of its dataprovider.
+<sonic-code >
+<template>
+<sonic-fetch 
+    serviceURL="https://reqres.in"
+    dataProvider="api/users/3" 
+    key="data">
+     <docs-user></docs-user>
+</sonic-fetch>
+</template>
+</sonic-code>
+
+A subscriber can subscribe data from anywhere in the DOM, with its dataprovider set as a provider id.  
+<sonic-code >
+<template>
+<sonic-fetch 
+    serviceURL="https://reqres.in"
+    dataProvider="api/users/2" 
+    key="data"></sonic-fetch>
+<docs-user dataProvider="api/users/2" ></docs-user>
+<docs-user dataProvider="api/users/2" ></docs-user>
+<docs-user dataProvider="api/users/2" ></docs-user>
+</template>
+</sonic-code>
+
+
+<sonic-code >
+<template>
+
+<div class="grid grid-cols-1 gap-4">
+<form formDataProvider="userPreview" class="grid grid-cols-4 gap-3" >
+  <sonic-input label="First name" type="text" name="first_name" placeholder="John" value="Paul"></sonic-input>
+  <sonic-input label="Last name" type="text" name="last_name" placeholder="Doe" value="Metrand"></sonic-input>
+  <sonic-input class="col-span-2"  label="email" type="text" name="email" placeholder="johndoe@concorde.fr" value="paulmetrand@concorde.fr"></sonic-input>
+  <sonic-input type="file" name="avatar" value="/img/paul_metrand_xs.jpg"></sonic-input>
+</form>
+<sonic-divider align="left">Preview before submit</sonic-divider>
+<docs-user dataProvider="userPreview" ></docs-user>
+<sonic-button onClick="alert(JSON.stringify(SonicPublisherManager.get('userPreview').get()))">
+  Update data
+</sonic-button>
+</div>
+</template>
+</sonic-code>