@supersoniks/concorde 3.0.3 → 3.0.4

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

@@ -0,0 +1,141 @@
+# 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>
+
+For a more manual configuration, you can refer to the following sections. <br/>
+However, the Tailwind configuration is not mentioned at the moment.
+
+## Brand New Vite Project
+
+### 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
+
+For example, to use a button:
+In `main.ts` or `main.js` to be compiled:
+
+<sonic-code language="typescript">
+  <template>
+import "@supersoniks/concorde/ui/button";
+  </template>
+</sonic-code>
+
+In the HTML of a JS or TS component or in the HTML of the web page that includes the compiled JS:
+
+<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>
+
+In `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/pubsub.md

@@ -0,0 +1,150 @@
+# 🥨 Sharing data
+
+This section describes how we share data between graphical and non graphical components and classes.
+
+Especialy, graphical components should not reference each other in order to **remain decoupled**.
+
+Thats why we use **publish/subscribe** paradigm to addresse this issue.
+
+
+## The Publisher
+
+### Principle
+
+* The **publisher** is a [JavaScript proxy](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Global_Objects/Proxy) that contains some data.<br>**
+Example of data : `{foo:{hello:["world"]}, bar:"baz"}`
+
+* if a property of the **publisher** (dot syntax / array access), it returns another **publisher**.
+Using the previous example `myPublisher.foo.hello` is also a publisher containing `["world"]`
+
+* If the property doesn't exist at the time of the request, a publisher is created. its internal data is set to `null`.<br>
+The value that can then be provided later.
+
+* **Subscribers** can subscribe to the publisher's modifications and be updated in different ways (see : onAssign, onInternalMutation, startTemplateFilling).
+
+* Data inside the publisher is updated by modifying the publisher itself, for example `myPublisher.foo.hello = ["Joey", "Smith"]`
+  
+* The publisher publishes modifications to any of its **Subscribers**.
+
+
+❇️ The order of data creation and subscription theoretically has no importance.
+
+### Methods
+
+* **set (complete replacement):** Assign/modifies the internal value of the publisher.
+  <sonic-code language="javascript">
+  <template>
+  publisher.set({foo:{hello:["world"]}, bar:"baz"});  
+  </template>
+</sonic-code>
+* **get:** Get the internal value of the publisher.
+ <sonic-code language="javascript">
+  <template>
+  publisher.get() //{foo:{hello:["world"]}, bar:"baz"};
+  </template>
+</sonic-code>
+* **onAssign/offAssign:** Subscribe/unsubscribe to value assignments (via `set`) of the publisher.
+<sonic-code language="javascript">
+  <template>
+  publisher.a.b.onAssign(console.log);
+  //indirect
+  publisher.a = {b:"dramatic change"}; //log: "dramatic change"
+  //via set
+  publisher.a.b.set(["Hello"]) //log: ["Hello"]
+  </template>
+</sonic-code>
+* **onInternalMutation/offInternalMutation:** Listen to any internal mutation regardless of its depth level.
+<sonic-code language="javascript">
+  <template>
+  function save(){
+  	console.log("Something has changed, let's save");
+  }
+  publisher.onInternalMutation(save);
+  publisher.a.b[0] = "e";
+  </template>
+</sonic-code>
+* **startTemplateFilling/stopTemplateFilling:** Fill an object model, a principle used with the Subscriber mixin on which most Concorde components rely.
+<sonic-code language="javascript">
+  <template>
+  const fillableTemplate =  { title: "A title to be replaced"};
+  publisher.startTemplateFilling(fillableTemplate);
+  state.title = "Good morning";
+  publisher.stopTemplateFilling(fillableTemplate);
+  state.title = "Oops";
+  console.log(fillableTemplate);
+  </template>
+</sonic-code>
+* **invalidate:** Flag the data as invalid. Used by sonic-fetch and sonic-list to trigger data reloading.
+<sonic-code language="javascript">
+  <template>
+publisher.invalidate();
+  </template>
+</sonic-code>
+* **onInvalidate/offInvalidate:** Subscribe/unsubscribe to data invalidation of the publisher. Used by sonic-fetch and sonic-list to trigger data reloading.
+<sonic-code language="javascript">
+  <template>
+function reloadData(){
+  console.log("Reload data to inject it again into the publisher");
+}
+publisher.onInvalidate(reloadData);
+  </template>
+</sonic-code>
+
+## DataProvider
+
+Denotes the identifier of a publisher as referenced in the PublisherManager (see below).
+Uses the dataProvider attribut in html tags to scop the content with some data.
+see [Subscribers](#docs/_core-concept/subscriber.md/subscriber).
+
+
+## PublisherManager
+
+The **PublisherManager** is a utility class to get publishers
+
+It plays a central role in the components, especially through the "subscriber" mixin.<br>
+Automatic data communication between components in concorde uses this principle in conjunction with Lit's reactive properties. <br>
+Refer to the documentation for [Subscriber](#docs/_core-concept/subscriber.md/subscriber).
+
+<sonic-code language="javascript">
+  <template>
+import { PublisherManager } from "publisherproxy";
+let dataProvider = "cart";
+let publisher = PublisherManager.get(dataProvider);
+
+  </template>
+</sonic-code>
+
+It is declared on the `window` object to allow usage in a web page, so the equivalent one-liner would be:
+
+<sonic-code language="javascript">
+  <template>
+let dataProvider = "cart";
+let publisher = SonicPublisherManager.get(dataProvider);
+
+  </template>
+</sonic-code>
+
+
+## Basic Example
+
+This example can be tested in a console when Concorde is loaded on the page (for example, in a ticketing system).
+In a component, you will need to perform an `import` as explained earlier.
+
+<sonic-code language="javascript">
+  <template>
+// Anywhere, anytime
+SonicPublisherManager.get("mySubject").title.onAssign(console.log) 
+
+  </template>
+</sonic-code>
+
+<sonic-code language="javascript">
+  <template>
+// Anywhere, anytime
+let publisher = SonicPublisherManager.get("mySubject");
+// ...
+publisher.set({title: "A title"});
+publisher.title.set("A second title");
+
+  </template>
+</sonic-code>

package/docs/src/docs/_getting-started/start.md

@@ -0,0 +1,37 @@
+# Introduction
+
+## What is Concorde ? 
+
+Based on [lit.dev](https://lit.dev), Concorde is a collection of functional & UI webcomponents, created to build easily shared components, beetween apps and websites. Or even to build a website or an app from scratch.
+It's like a toolbox to build user interfaces, faster, where everything is scoped, but preserving graphical consistency in set a few css variables.
+
+## Why and use case
+
+At Supersoniks, we've created a ticketing management system that needs shared components which could be implemented in mobile apps, modern websites, and also old ones made in php, without bundlers or whatever.  
+Instead of creating a new library for each type of project, which would become hard to maintain, we've decided to create one shared library, that could be used in any environment and pre-bundled for legacy environment.
+Webcomponents appeared to be a the perfect solution to guarantee that compatibility with all past, present and futures stacks.
+
+### Functionnal features
+
+* Fetching data, lists, queue with lazyload, etc.
+* Data management with Publisher / Subscriber pattern
+* Data binding
+* Form management ("doux Jésus")
+* Simple router, state component,...
+
+### Tools
+
+* Lit, of course
+* Typescript
+* Vite
+* Tailwind (not in the core, but in the starter kit)
+
+## Start a new project from scratch ? 
+
+A new project with Vite, Typescript and Tailwind already configured and a simple example of a subscriber component :  
+
+<sonic-code language="bash">
+  <template>
+  npx @supersoniks/create-concorde-ts-starter "project_name"
+  </template>
+</sonic-code>

package/docs/src/docs/_getting-started/theming.md

@@ -0,0 +1,91 @@
+# Adding styles
+
+## Normal Behavior
+
+No style crosses the shadow root of a component, except for inheritable properties (which have the "inherit" property possible) and CSS variables.
+Properties integrated via a "[slot](https://developer.mozilla.org/en/docs/Web/HTML/Element/slot)" remain stylizable in a conventional way.
+
+- **During creation / from the inside:**
+  - We edit the [static "styles" property of the lit component](https://lit.dev/docs/components/styles/), which can also reference shared and dynamic styles.
+    These styles are scoped and do not impact the outside.
+  - We use CSS variables as the value of properties intended to be customized from the outside.
+    For each variable, we define a default value to have a simple but consistent base style.
+  - We only rewrite inheritable properties with hard values if they are truly specific to the component.
+  - The `<style>` tag as a direct child can be used as a last resort, especially if there is a need for particularly dynamic customization. Performance is reduced.
+- **During use / from the outside:**
+  We define values for **inheritable CSS properties** (e.g., font-\_, color...) using tools like Tailwind.
+  We modify the value of **CSS variables** used by the component.
+
+## Choosing Style Presets via Reactive Properties:
+
+The declaration of reactive properties is useful for selecting a particular configuration that mostly affects a set of properties.
+
+For example, a `size` property (xs, sm, md, xl) will affect margins, font, line heights to align them with the corresponding CSS vars, which can be customized using the methods mentioned earlier if necessary.
+
+It is recommended to use the `{reflect: true}` property for reactive properties that have an associated style on the `:host()`. For example: `:host([type='primary']){...}`
+
+☢️ **Caution:** Passing class names via reactive properties / HTML attributes of the component should be avoided as it can quickly lead to difficult-to-manage situations.
+
+#### CSS "display" Property
+
+By default, the display property is `inline`.
+Therefore, be careful to define it according to the needs, as one might mistakenly expect it to be `block` as with a regular `<div>`.
+
+☢️ **Caution:** Defining the `display` property as `contents` may seem attractive at first, but:
+
+- It almost always leads to the creation of wrappers to style the content (instead of using `:host`).
+- It is no longer possible to directly add classes to the component or style it from the outside.
+  Ultimately, the amount of code to write increases significantly.
+
+## TAILWIND Functional Classes
+
+[tailwind](https://tailwindcss.com/) has been integrated into Concorde and is available in scoped components (with Shadow DOM).
+To use it, you need to import the following:
+
+<sonic-code language="javascript">
+  <template>
+import { tailwind } from "@supersoniks/concorde/la-billetterie/ui/theme/theme";
+  </template>
+</sonic-code>
+
+Then include the `tailwind` style in the static `styles` property of the component:
+
+<sonic-code language="javascript">
+  <template>
+static styles = [tailwind];
+  </template>
+</sonic-code>
+
+Finally, use it in the HTML within the render function:
+
+<sonic-code language="html">
+  <template>
+<p class="m-2">A paragraph with margin</p>
+  </template>
+</sonic-code>
+
+The colors from Concorde's theme are referenced in Tailwind's theme.
+
+## Operation without Shadow DOM
+
+### Usefulness
+
+This operation is particularly useful when it comes to **adding behavior to a simple existing element**.
+It may also become necessary to establish **compatibility with a traditional JS library**.
+
+For example, with a text input:
+
+- Trigger automatic data or filter update when typing text.
+- Automatic formatting.
+- Constraints that cannot be handled by native methods.
+
+### Consequences
+
+If there is no shadow DOM (see the **noShadowDom** property of **Subscriber**):
+
+- Styling using the static "styles" property of the lit component will not be applied.
+- The element and its content can be styled in a traditional manner.
+
+For example, the components `queue`, `list`, and `fetch` do not have a shadow DOM.
+
+ℹ️ **Note:** Specifically in this case, it may be useful to set the `display` property to `contents`.