@supersoniks/concorde 3.1.76 → 3.1.78

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,39 @@
+# Introduction
+
+## What is Concorde ? 
+
+Based on **[lit.dev](https://lit.dev)**, Concorde is a collection of webcomponents made to build shared apps or websites.  
+Develop user interfaces without thinking about the implementation context, where everything is scoped, but preserving graphic consistency by setting the strict minimum of css variables.
+
+## Why and use case
+
+In 2022, Supersoniks wanted to create a new version of his ticketing app, in production un nearly 100 websites. We needed shared components which could be implemented in mobile apps, modern websites, and also old ones made in php, without bundlers or whatever.  
+Instead of building a new app for each type of project, which would become impossible to maintain, we've decided to create one app, composed by a few webcomponents wich could easily be recomposed on any website.
+Webcomponents appeared to be a the perfect solution to guarantee that compatibility with all past, present and futures environment, and lit seemed to be the best choice to build them.
+
+### Stack
+
+* Lit
+* Typescript
+* Vite
+* Tailwind, not in the core, but in the starter kit
+
+### Functionnal features and components
+
+* Data management with Publisher / Subscriber pattern
+* Form management
+* Fetching data, lists, queue with lazyload
+* Data binding
+* Simple router, state component, ...
+* And all ui component, with status variants to build an app with a consistent design
+
+
+## Start a new project easily 
+
+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`.