@supersoniks/concorde 3.2.1 → 3.2.3

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

@@ -1,143 +0,0 @@
-# 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

@@ -1,137 +0,0 @@
-# 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

@@ -1,174 +0,0 @@
-# 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>

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

@@ -1,150 +0,0 @@
-# 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

@@ -1,39 +0,0 @@
-# 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>