Many teams decide to use Atomico for the development of their design systems thanks to its similarity with React, which greatly facilitates the incorporation of human talent into the development of design systems.

Why use Atomico to create design systems?

1. Atomico offers you Storybook 7 Support with superpowers, thanks to @atomico/storybook you can create stories without the need to declare the argTypes or args since @Atomico/storybook creates them for you

2. @atomico/vite makes it easy for you to build in NPM-friendly ESM format

3. @atomico/exports makes it easy for you to export your code by automatically adding the metadata so that it is optimally consumed as a package, @atomico/exports can even automatically create wrappers for React, Preact and Vue

4. @atomico/potscss-tokens makes it easy for you to maintain a token system efficiently and sustainably

Use cases

IBM IX

We thank IBM IX since they have shared their experience in the development of the design system for their client Barmer, you can follow this case through Discord or Github.

https://github.com/atomicojs/atomico/discussions/92

Thanks for being here and getting started with Atomico. Let's talk a little about what Atomico offers today:

1. Development agility, Atomico's functional approach simplifies code at all stages of development.

2. Lightweight inside and out, Atomico allows you to create a component with less code and with a low dependency impact. Approximately 3kb.

3. Really fast, Atomico has a in the browser and an agile development experience. Let's understand what a webcomponent created with Atomico looks like:

Let's analyze the code in parts ...

Import

What have we imported?

1. c: Function that transforms the functional component into a standard customElement.

2. html: Function to declare the template of our component, you can also use JSX.

3. css: Function that allows creating the CSSStyleSheet (CSS) for our component as long as it declares the shadowDom.

Webcomponent

Our component function receives all the props (Properties and Attributes) declared in component.props, the component function declares all the logic and template of the webcomponent. An important rule within Atomico is "every component created with Atomico must always return the tag".

Reactive properties and attributes of the webcomponent

Atomico detects the prop (Properties and Attributes) of the component thanks to the association of the props object, this through the use of index and value allows you to define:

1. index: Name of the property and attribute.

2. value: type of the prop.

From the example we can infer that Atomico will create in our webcomponent a property and attribute called message and this can only receive values of the String type.

Appearance of the webcomponent.

Atomico detects the static styles of your component thanks to the association of the styles property:

styles accepts individual or list CSSStyleSheet (CSS) values, the return from the css function is a standard CSSStyleSheet, so it can be shared outside of Atomico.

Definition of your webcomponent

To create our standard customElement we will have to deliver our functional component to the c function of the Atomico module, the c function will generate as a return a customElement that can be defined or extended.

Example

Atomico simplifies learning, workflow and maintenance when creating webcomponents and achieves it with:

1. Scalable and reusable interfaces: with Atomico the code is simpler and you can apply practices that facilitate the reuse of your code.

2. Open communication: with Atomico you can communicate states by events, properties or methods.

3. Agnostic: your custom Element will work in any web-compatible library, eg React, Vue, Svelte or Angular.

API

We invite you to discover part of the development experience you will get with Atomico:

Create really fast webcomponents

Quick components to write since with Atomico you will require fewer lines of code to declare your webcomponents which will help you to be more productive

Fast in performance, since Atomico sends less code to the client, making your interface load quickly

Create web components with less code

This is thanks to a functional orientation inherited from React hooks plus some internal optimization from Atomic that ease the process of shaking the tree at compile time, achieving in this way sending the client a highly optimized JS that only has what you really use

Create webcomponents with a functional orientation

This is thanks to Atomico's reliance on React hooks syntax plus the ability to completely eliminate the need for this when using webcomponents.

Create friendly webcomponents for React, Vue and other libraries

Atomic offers additional coverage for native behavior for React and Vue, allowing your component to be more embed-friendly, example React:

Creating sites with Atomico is really easy and SEO friendly because:

1. With Atomico you can perform SSR and SSG thanks to tools like Astro build, with Astro + Atomico you can send previously rendered components to the client, thus giving a result at the HTML level that is really friendly with search engines.

2. Atomico being really small (3kB) your sites will load fast, especially if you only apply SSG with Atomico.

3. Atomico not only supports SSR through Astro, you can SSR today with Atomico in Next.js, Express or any environment that supports ESM modules.

4. (Coming soon) Yes, with Atomico soon you will be able to create blocks for Gutenberg easily

We recommend for SSR or SSG based sites

we recommend you for new projects

We recommend the use of Astro build with the @atomico/astro plugin, with this you can create sites like atomicojs.dev

we recommend you for projects based on React

Preferably we recommend Astro + React + Atomico, but in case your project inherits the use of Next.js you can do SSR with Atomico in Next.js using @atomico/react.

Syntax

JSX

import { c } from "atomico";

function component() {
  const handlerClick = () => console.log("click!");
  return (
    <host shadowDom onclick={handlerClick}>
      <h1>content</h1>
      <slot></slot>
    </host>
  );
}

customElements.define("my-component", c(component));

Atomico supports jsx-runtime, alternatively you can import the h function to declare manual of the JSX pragma, eg:

/**@jsx h*/
import { h } from "atomico";

Template String

Atomico supports the use of template-string thanks to the use of the package htm.

import { c } from "atomico";
import html from "atomico/html";

function component() {
  const handlerClick = () => console.log("click!");
  return html`<host shadowDom onclick=${handlerClick}>
    <h1>content</h1>
    <slot></slot>
  </host>`;
}

customElements.define("my-component", c(component));

Return rule

function component() {
  // The webcomponent should always return the host tag
  return <host></host>;
}

An important rule of Atomico's virtualDOM is that every webcomponent must return the <host/> tag since it represents the state of the webcomponent's DOM, such as:

1. Enable the use of the shadowDOM by declaring the shadowDom property.

2. Association of events, attributes or properties.

3. Template of the webcomponent.

Template

Event Association

Atomico considers that a property must be associated as an event if it is of the function type and begins with the prefix 'on', eg:

<host onclick={() => console.log("click!")}></host>;
<host onMyEvent={() => console.log("MyEvent!")}></host>;
<input oninput={() => console.log("click!")} />;
<slot onslotchange={() => console.log("update slot!")} />;

Simple lists

<host>
  {[1, 2, 3].map((value) => (
    <span>{value}</span>
  ))}
</host>

Lists with keys

<host>
  {[1, 2, 3].map((value) => (
    <span key={value}>{value}</span>
  ))}
</host>

the key property can receive values of the type of any type that allows generating a reference to the node, eg:

<host>
  {listaInmutable.map((objeto) => (
    <span key={objeto}>{objeto.value}</span>
  ))}
</host>

Node references

A technique inherited from React, it allows obtaining the reference of the node to which the Ref object is associated through the ref property, example:

const ref = useRef();

<host ref={ref}></host>; // The reference will be the instance 
                         // of the custom Element

<input ref={ref}/>; // The reference will be the input

The references must be immutable objects, to create it there is the useRef hook that creates a reference for each instance of the webcomponent.

shadowDom property

This property allows you to declare the use of the shadowDom, eg:

<host shadowDom></host>;
// The use of shadow Dom is not exclusive to the host tag
// can be used for any node that supports it
<div shadowDom></div>;

Method association

You can declare a method by declaring a function in the host tag without using the prefix on in its name, eg:

// Template
<host myMethod={() => console.log("method!")}></host>;
// Use from the DOM
document.querySelector("my-component").myMethod();

If when creating or updating the DOM it does not detect the use of the property, it will be associated as a method of this, thus allowing it to be accessed from the DOM, eg:

const myElement = new MyElement();

await myElement.updated;

myElement.myMethod();

To access the DOM safely wait for the resolution of the updated property created by the render cycle.

Props is the Atomico recommended way to declare visible and accessible states at the instance level of your webcomponents, with props you can:

1. Access state via instance, example: document.querySelector("my-component").myStateProp.

2. Dispatch events on prop value change, example: document.querySelector("my-component").addEventListener("myPropChange",console.log).

3. Reflect attributes as prop, example: <my-component my-prop="...."> to document.querySelector("my-component").myProp.

4. define strict input types for props.

Syntax

Any function that represents the webcomponent will be able to associate the static object props for the declaration of reactive properties and attributes, for example:

import { c } from "atomico";

function component() {
  return <host />;
}

component.props = {
  // Simple statement
  value1: String,
  // Structured statement
  value2: {
    type: String,
    reflect: true,
    attr: "advaceprop",
    value: "default string",
    event: {
      type: "UpdateAdvanceProp",
      bubbles: true,
    },
  },
};

customElement.define("web-component", c(component));

Consider that:

1. The prop names in Camel Case format will be translated to for use as an attribute to the Kebab Case format, this behavior can be modified through the "attr" property when using a structured declaration.

2. Structured declarations require the "type" property minimally.

3. Not all types can use the "reflect" properties.

4. The declaration of the "value" property can vary depending on the type.

Simple statements

Simple statements allow setting just type validations.

component.props = {
  propString: String,
  propNumber: Number,
  propObject: Object,
  propArray: Array,
  propBool: Boolean,
  propCallback: Function,
};

Structured declaration

Improve the definition by adding utility declarations, allowing for example to reflect the property's value as attributes, automatically emit events or associate default values. Remember these types of declarations minimally require the use of the type property.

Prop.type

// valid declaration
component.props = { myName: String };
// valid declaration
component.props = { myName: { type: String } };

Prop.reflect

If the "reflect" property is set to true, its value is reflected as an attribute of the webcomponent, this is useful for the declaration of CSS states, example:

component.props = {
  checked: {
    type: Boolean,
    reflect: true,
  },
};

Prop.event

It allows dispatching an automatic event before the prop value change, example:

component.props = {
  value: {
    type: String,
    event: {
      type: "change",
      bubbles: true,
      composed: true,
      detail: "any value",
      cancelable: true,
    },
  },
};
// listener
nodeComponent.addEventListener("change", handler);

Where:

• event.type: String - optional, name of the event to be emitted when the prop is changed

• event.bubbles: Boolean - optional, indicates that the event can be listened to by containers.

• event.detail: Any - optional, allows to attach a custom detail for the event

• event.cancelable: Boolean - optional, indicates that the event can be canceled by any listener

• event.composed: Boolean - optional, allows the event to exceed the shadow-root limit

The special properties of the event are the well-known Event Init, you can know more details in the attached documentation.

Prop.value

Atomico allows the definition of default values of the props.

WebComponents.props = {
  valueNormal: {
    type: Number,
    value: 100,
  },
  valueObject: {
    type: Object,
    value: () => ({}),
  },
};

The association of callback as value allows generating unique values for each instance of the webcomponent, this is useful with the Object and Array types since it eliminates the references between instances.

Reactivity in the scope of the webcomponent

Atomico removes the use of "this" given its functional approach, but adds the hook [useProp] (hooks / useprop.md) which allows to reference a prop for use with a functional syntax, eg:

function component() {
  const [message, setMessage] = useProp("message");
  return (
    <host>
      Hello, {message}
      <input oninput={({ target }) => setMessage(target.value)} />
    </host>
  );
}

component.props = { message: String };

Recommended articles

First let's say that Atomico is light since it has a size close to 3kB vs React + ReactDOM that have a size close to 60kB, now if your project is already written in React I can integrate Atomico progressively since a component created can be instantiated as a component for React thanks to @atomico/react, example:

import { Button } from "@formas/button/react";

function App(){
   return <>
      <h1>React App!</h1>
      <Button onClick={()=>console.log("Click!")}>
         Submit
      </Button>
   </>
}

Magical , isn't it?... well now let's speed up your Atomico learning path:

How to declare a component?

Atomico, like React, allows a declaration of components using only functions, example:

import { useState } from "react";
import ReactDOM from 'react-dom'

function Counter({initialCount}) {
  const [count, setCount] = useState(initialCount);
  return (
    <>
      Count: {count}
      <button onClick={() => setCount(initialCount)}>Reset</button>
      <button onClick={() => setCount(prevCount => prevCount - 1)}>-</button>
      <button onClick={() => setCount(prevCount => prevCount + 1)}>+</button>
    </>
  );
}


render(
  <Counter initialCount={1}/>, 
  document.querySelector("#counter")
);

import { c, useProp } from "atomico";

function counter() {
  const [count, setCount] = useProp("count");
  return (
    <host>
      Count: {count}
      <button onClick={() => setCount(prevCount => prevCount - 1)}>-</button>
      <button onClick={() => setCount(prevCount => prevCount + 1)}>+</button>
    </host>
  );
}

counter.props = { count: { type: Number, value: 0 } }

const Counter = c(counter);

customElements.define(
  "my-counter",
  Counter  
);

From the example we will highlight the following differences:

1. In Atomico you only use one import.

2. useProp is like useState, but with the difference that useProp references the state from the webcomponent property defined in counter.props.

3. counter.props allows us to create the properties of our webcomponent, these are like React's propTypes, but with a big difference they are associated with the instance and can be read and modified by referencing the node, example document.querySelector("my-counter").count = 10;

4. ReactDom.render needs a reference to mount the component, in Atomico you only need to create the my-counter tag to create a new instance of the component.

5. The <host/> tag is similar to <> </> for React, but <host/> represents the webcomponent instance and every component created with Atomico must return the host tag

6. This is only readability, but in Atomico by convention we do not use capital letters when naming our component, these are only used when creating the customElement as in line 16, since Counter is instantiable.

Now I want to invite you to learn how to declare a style using Atomico.

How do you declare styles using Atomico?

It is common to see the use of libraries such as Emotion or styled-components to encapsulate styles in React, but these add an additional cost, be it for performance or bundle, in Atomico there is no such cost.

const Button = styled.a`
  /* This renders the buttons above... Edit me! */
  display: inline-block;
  border-radius: 3px;
  padding: 0.5rem 0;
  margin: 0.5rem 1rem;
  width: 11rem;
  background: transparent;
  color: white;
  border: 2px solid white;

  /* The GitHub button is a primary button
   * edit this to target it specifically! */
  ${props => props.primary && css`
    background: white;
    color: black;
  `}
`

render(
  <div>
    <Button
      href="https://github.com/styled-components/styled-components"
      target="_blank"
      rel="noopener"
      primary
    >
      GitHub
    </Button>

    <Button as={Link} href="/docs">
      Documentation
    </Button>
  </div>
)

import { c, css } from "atomico";

function button() {
  return <host shadowDom><slot/></host>;
}

button.props = { primary: { type: Boolean, relfect: true } };

button.styles = css`
  :host {
    display: inline-block;
    border-radius: 3px;
    padding: 0.5rem 0;
    margin: 0.5rem 1rem;
    width: 11rem;
    background: transparent;
    color: white;
    border: 2px solid white;
  }

  :host([primary]) {
    background: white;
    color: black;
  }
`;

export const Button = c(button);

Instances, children and slots

It is normal for React to create components that you then instantiate within other components, for example:

function Child({children}){
    return <span>children</span>
}

function Main(){
    return <>
        <Child>text 1...</Child>
        <Child>text 2...</Child>
    </>
}

with Atomico there are certain differences:

1. With Atomico you can instantiate CustomElements using its constructor

The constructor in Atomic is the product of the c function and is the one you will use to register your webcomponent, example:

import { c } from "atomico";

function myComponent(){
    return <host>
        ...
    </host>
}

export const MyComponent = c(myComponent); // Constructor

customElements.define("my-component", MyComponent);

According to the previous example, you can instantiate MyComponent as a JSX Component, example:

import { c } from "atomico";
import { MyComponent } from "./my-component";

function myApp(){
    return <host>
        <MyComponent/>
    </host>;
}

export const MyApp = c(myApp);

customElements.define("my-app", MyApp);

This instance type allows autocompletion at the JSX level and type validation at the Typescript level.

2. With Atomico you can instantiate components as functions as long as these are only stateless functions

function MyStatelessTemplateBlock(){

}

function MyComponent(){
    return <host>
        <MyStatelessTemplateBlock/>
    </host>
}

This will be useful for reusing templates, but always remember stateless.

Cycle as attribute:

the given value is transformed to the corresponding type, be it String, Number, Boolean, Array or Object, once transformed it is sent to the cycle as property.

Cycle as property:

evaluates if the value is of the declared type:

• If it corresponds to the type:

  1. It is saved in props.

  2. An event is emitted (if this has been configured in the prop).

  3. It is reflected as an attribute (if this has been configured in the prop).

  4. It is sent to the update queue and subsequent rendering.

• It does not correspond to the type: an error is created by console with the following data:

  • target: Instance of the webcomponent.

  • value: Input value.

  • type: expected type.

Special properties

render

By default, the render is configured to be used within the webcomponent by reading the return of the function, but it can be used outside of Atomico, example:

import { h, render } from "atomico";


render(
    h("host",{ style: {background:"red"} }
        h("h1",null,"Text content...")
    ),
    document.querySelector("#app")
);

import { h, render } from "atomico";


render(
    <host style={{background:"red"}}>
        <h1>Text content...</h1>
    </host>,
    document.querySelector("#app")
);

import { html, render } from "atomico";


render(
    html`<host style=${background:"red"}>
        <h1>Text content...</h1>
    </host>`,
    document.querySelector("#app")
);

Constructor with custom element

This technique allows you to use any registered custom element without the need to know its tag-name for its use, example:

function component(){
    return <host/>
}
// 1️⃣ We create the custom element
const Component = c(component);

// 2️⃣ We register the custom element
customElements.define("my-component", Component);

function App(){
    return <host>
        <Component/>
    </host>
}

Advantage :

1. Remove leverage from tag-name

2. Infer the types of the props and autocomplete only if you use JSX and Atomico.

Constructor with DOM

Atomico allows the use of the DOM, for this it establishes its created or recovered node as a constructor, example:

function component(){

    const Div = useMemo(()=>document.createElement("div"));
    
    return <host>
        <Div style="color: black">content...</Div>
    </host>
}

Dynamic constructor

Atomico associates the variable associated with the instance as a constructor, example:

function component({ subComponent }){
    const TagName = `my-${subComponent}`;
    
    return <host>
        <TagName/>
    </host>
}

staticNode

allows to declare a node within the scope of the function as static, this will optimize the diff process between render, achieving better performance in cases of high stress of the UI, example:

function component() {
  return (
    <host>
      <h1 staticNode onclick={console.log}>
        i am static node!
      </h1>
    </host>
  );
}

the biggest advantage of this is that the node accesses the scope of the webcomponent

cloneNode

Allows to clone a node from the virtualDOM, example:

const Div = document.createElement("div");

Div.innerHTML = `<h1>Div!</h1>`;

function component() {
  return (
    <host>
      <Div cloneNode onclick={console.log} />
      <Div cloneNode onclick={console.log} />
      <Div cloneNode onclick={console.log} />
      <Div cloneNode onclick={console.log} />
      <Div cloneNode onclick={console.log} />
    </host>
  );
}

The objective of this feature is to retrieve slot and use it as a template from the webcomponent.

SSR hydration

Atomico allows reusing existing DOM in the document. This is done during the webcomponent instatiation, by setting a special property in the tag to mark it for hydration.

<my-webcomponent data-hydrate>
    <h1>I will be the title of the component</h1>
</my-webcomponent>

This can be done for shadowDom too:

<my-webcomponent data-hydrate>
    <template shadowroot="open">
        <h2>Shadow Content</h2>
        <slot></slot>
        <style>shadow styles</style>
    </template>
    <h2>Light content</h2>
</my-webcomponent>

Class name inheritance

Atomic creates a customElement from a function, Atomico will take the name of the function and associate it as the name of the CustomElement in CamelCase format, example:

function button(){
    return <host/>
}

const Button = c(button);

This results in the class name being equal to Button. This feature is useful for tools like Storybook, when serializing the JSX.

Hooks only for webcomponents

Hooks homogolates of React

@atomico/hooks

Atomico today offers more Hooks external to the core, we invite you to visit @atomico/hooks with more than 50 hooks to enhance the use of webcomponents 😎

Syntax

Example

Observation

The reference object is useful for referencing nodes between customHooks.

useProp allows you to work with a prop(property) of the webcomponent in a similar way to useState.

Syntax

Where :

• value: Current value of the prop.

• setValue: Callback to update the value of the prop.

• myProp: string, defines the name of the prop to be used by the hook.

Example

Where:

1. useCounter is a customHook and that it can work with any property of the webcomponent of type Number.

2. useCounter returns 2 methods increment and decrement that modify the value of the prop.

3. useCounter can be instantiated multiple times for different properties.

Syntax

Returns the instance of the webcomponent in reference format, this reference allows to extend behaviors when creating customHooks.

Example

From the example we can highlight that useListener is a customHook that allows listening to an event from the webcomponent without the need to link said event to the VirtualDOM.

Syntax

Where :

1. effectCallback : Function that is executed one or more times according to optionalArgumentList,effectCallback can return a function that will be executed only if effectCallback is executed again or the webcomponent is unmounted.

2. optionalArgumentList: Array of arguments that controls the execution of effectCallback, if an argument ofoptionalArgumentList changes it will trigger that effectCallback is executed again without first cleaning the effects subscribed by the previous execution.

Example

useLayoutEffect

useLayoutEffect replicates the logic of useEffect but with synchronous execution after rendering.

useInsertionEffect

useLayoutEffect replicates the logic of useEffect but with synchronous execution before rendering.

Syntax

Where:

• dispatchEvent: callback, dispatches the event from the webcomponent and allows defining the detail by receiving a first parameter

• myEvent: string, name of the event to dispatch.

• eventInit: optional object, event configuration.

Examples

Event customization

The second parameter of useEvent allows customizing the behavior of the even:

Recommended articles

Syntax

Where:

1. const [state,setState] : Return of useState, the arguments allow reading and updating of the state associated with the hook instance.

   • state : Current state.

   • setState: Current status updater.

2. useState( optionalInitialState ): Function that associates the state to the webcomponent:

   • optionalInitialState: Optional parameter that defines the initial state associated to the hook instance, If optionalInitialState is a function it will be executed in order to obtain the initial state only at the moment of the hook instance for the first time.

Example

With the new contexts API you will be able to easily communicate components without the need to handle events, by default the communication is top down, but through it you can share anything as long as it is defined as an object.

Atomico's api is similar to React's Context api, let's explore the behavior of Atomico's context api:

createContext

create a custom Element as a context, this will serve to synchronize all the components nested within it, you must always remember to declare the tagname of this customElement, example

import { createContext } from "atomico";

export const Theme = createContext({
    color: "white",
    background: "black"
});

customElements.define( "my-theme", Theme  );

useContext

It allows to consume the return of createContext, let's go back to the previous example and suppose that we want to consume the customElement Theme created by createContext, the code for this would be the following:

import { useContext } from "atomico";
import { Theme } from "./my-theme";

function card(){
    const {color, background} = useContext(Theme);
    return <host>
        color: { color }
        background: { background }
    </host>
}

In this way useContext captures the value of the parent component or reuses the value given by default to createContext.

Custom context values

By setting the value prop on the context, you can pass custom values down the sub-tree:

function child() {
    const {color, background} = useContext(Theme);
    return <host>{color === "red" && background === "blue"}</host>
}


export const MyChild = c(child);
customElements.define("my-child", MyChild);

function parent() {
    return (
        <host>
            <Theme value={{ color: "red", background: "blue" }}>
                <my-child></my-child>
            </Theme>
        </host>
    )
}

When to use the Context API?

It is ideal to always prioritize a conversation between parent and child through events or props api, but sometimes the depth of the DOM makes this process difficult, for this the context api has been introduced. To remove DOM depth limitations and ensure synchronization based on a unique identifier, some ideal cases to solve with the context api are:

1. Synchronize states or private methods between components.

2. Share a value or states inherited from the parent regardless of DOM depth.

Syntax

const memoValue = useMemo(callback, optionalArgumentList);

Where :

1. memoValue : Return memorized by useMemo.

2. callback: Function that is executed one or more times according to optionalArgumentList.

3. optionalArgumentList: Array of arguments that controls the execution of callback, if an argument of optionalArgumentList changes it will trigger that callback is executed again.

useCallback

Hook that allows you to memorize a callback so that it keeps its scope

const memoCallback = useCallack(callback, optionalArgumentList);

Where:

1. memoCallback : Return memorized by useCallback.

It is normal that the state of your component depends on the references of a slot, this hook facilitates the process of observing these references without the need to associate the changes to a state.

Syntax

const update = useUpdate();

Where:

1. update: Callback, force component update.

The purpose of this hook is to facilitate the consumption of promises.

Syntax

import { usePromise } from "atomico";

const callback = (id: number) => Promise.resolve(id);
const args: Parameters<typeof callback> = [1];
const autorun = true;

const promise = usePromise( callback, args, autorun );

where:

• callback : asynchronous function.

• args: arguments that callback requires.

• autorun: by default true, it automatically executes the promise, if it is false the execution of the promise is suspended.

• promise : return object, at the type level it defines the following properties:

  • pending: boolean, defines if the promise is executed but pending resolution.

  • fulfilled: boolean, defines if the promise has been fulfilled

  • result: result of the promise.

  • rejected: boolean, defines if the promise has been rejected.

Example

import { usePromise } from "atomico";

const getUsers = (id: number) => Promise.resolve({ id, name: "Atomico" });

function component() {
  const promise = usePromise(getUsers, [1]);

  return (
    <host>
      {promise.fulfilled ? (
        <h1>Done {promise.result.name}!</h1>
      ) : promise.pending ? (
        <h1>Loading...</h1>
      ) : (
        <h1>Error!</h1>
      )}
    </host>
  );
}

This hook enables you to take control of the context from the component that instantiates useProvider, thus avoiding the need to instantiate the context node in the DOM.

Example of the useProvider hook:

import { createContext, useProvider, c } from "atomico";

export const Theme = createContext({
    color: "white",
    background: "black"
});

export const App = c(()=>{
    useProvider(Theme,{
        color: "red",
        background: "yellow"
    });
    
    return <host shadowDom><slot/></host>
});

Objective

Avoid creating an instantiable context node in the DOM.

useId is a Atomico Hook for generating unique IDs that can be passed to accessibility attributes.

Syntax

import { useId } from "atomico";

const stringId = useId();

Example

Use ID generate a unique ID for each component, this id can be useful for referencing CSS selectors or creating names for inputs that only the component knows about.

function component() {
  const id = useId();
  return <host id={id}>
    <style>{`#${id}{ display: block; color: white; }`}</style>
    <h1>useId</h1>
  </host>;
}

fixture

function that allows to keep the render on a single node for each execution of it, the container will be unmounted at the end of each execution of it.

import { html } from "atomico";
import { expect } from "@esm-bundle/chai";
import { fixture } from "atomico/test-dom";
import { Component } from "./component.js";

describe("my test", () => {
  it("my-component", async () => {
    const component = fixture(html`<${Component}>
        <span>content...</span>
    </${Component}>`);

    await component.updated;

    /** Test logic */
  });
});

This allows each fixture execution inside it to be related to the container used for the test, allowing you to fily test external DOM changes, example:

import { html } from "atomico";
import { expect } from "@esm-bundle/chai";
import { fixture } from "atomico/test-dom";
import { Component } from "./component.js";


describe("my test", () => {
  it("my-component", async () => {
    // first instance of the render, it will return the component
    const component = fixture(html`<${Component}>
        <span>content...</span>
    </${Component}>`);

    await component.updated;
    
    // updates the content of the span tag of the first instance of the render
    fixture(html`<${Component}>
        <span>new content...</span>
    </${Component}>`);
    
    await component.updated;

    expect(
          component.querySelector("span").textContent
    ).to.equal("new content...");
  });
});

Atomico's render cycle works like this:

First, when the component is instantiated, 3 promises will be created pending resolution:

1. componentInstance.mounted: resolved once the connectedCallback has been executed by the customElement.

2. componentInstance.updated: the render cycle for first mount or update is encapsulated in componentInstance.updated.

3. componentInstance.unmounted: resolved once the disconnectedCallback has been executed by the customElement.

Render or rerender cases are:

1. First render.

2. Updating a property or attribute.

3. Update dispatched by a hook

Remember all updates are stacked into a single big loop of componentInstance.updated.

This improves the testing experience since to observe the changes you only have to wait for the resolution of componentInstance.updated , example:

Webcomponent as function

The first rendering as the update of a prop will call to execute again the function that defines our component, Atomico internally stores the references to support the Hooks api and will render the virtualDOM returned by said function, this is encapsulated within componentInstance.updated

SSR

Atomico allows modifying its life cycle in cases of SSR, improving the rendering of the CSS in case of SSR and avoiding the effects of useEffect and useLayoutEffect

Hydration

Technique to reuse the DOM generated by the SSR, Atomico only in the first render of the component that declares date-hydrate will retrieve the existing DOM in the DOM not created by Atomico to relate it to the virtualDOM, avoiding creating the node again.

Optimization

Atomico by default has a good performance, but it can be further optimized if certain techniques are applied.

Render optimization with static nodes

A static node is equivalent to using node.cloneNode(true)

render optimization with renderOnce

The renderOnce property renders the node only once, one of the advantages of this technique is that the virtualDOM can access the scope of the function.

The "atomico/test-hooks" submodule is a direct part of Atomico's core and will allow you to run the customHook in a controlled way without the need for webcomponents.

createHooks

function that creates an isolated context that is shared globally with Atomico hooks when executing the load method

Instance

Where:

• optionalRender: Callback that allows restarting the hook's life cycle, this callback will be executed every time a hook like or requests the scope update, Atomico uses it to render the webcomponent again.

• opcionalHost: allows to share an object for the hook , Atomico uses it to share the instance of the webcomponent.

Return of the instance

Where:

• load: Function that allows to load the hooks to the temporary global context of Atomico.

• clearEffect: Function that activates the collector of useLayoutEffect, when executing clear Effect a callback will be returned that allows ending the collector for useEffect, closing the cycle of secondary effects.

  If clear Effect receives true as parameter, it communicates the unmounted.

Example:

./use-counter.js: customHook to test.

We recommend the tool, if your project was created with the command npm init @atomico the test environment will be preconfigured, you can see this pre-configuration at .

Advanced (Documentation in progress)

To scale the test environment you can complement with tools such as:

1. : allows you to automate interactions and evaluate interactions of your interface.

2. : Allows you to evaluate the appearance changes of your component or application between versions.

useAsync

with a similar approach to React's use hook, but with scope approach.

scope approach? yes, this hook seeks to resolve a promise from a callback return, this allows you to regenerate the promise according to the scope, example:

where:

• getUser: async callback.

• [ userId ]: arguments that if changed regenerate the promise.

• user : promise return

Like useEffect, the promise will be executed every time the arguments to the second parameter of useAsync change.

useSuspense

allows to listen to all useAsync executions nested in the component, example:

When to use the shadow Dom?

By creating a UI solution that coexists in the web ecosystem such as HTML, libraries and frameworks, since the shadowDOM allows you to:

1. Protect your UI from libraries like React, Vue and others

2. Associate styles natively, efficiently and safely

3. Reference lightDOM content in the shadowDOM

Webcomponents with Shadow DOM are ideal for creating cross UI solutions as they coexist without conflict with the entire web ecosystem.

Why use shadowDOM?

To protect our component at the DOM manipulation level and take advantage of some of the benefits of the shadowDOM such as:

1. Slot management

2. CSS appearance of web component.

3. The shadowDOM is ideal for creating components that interact with libraries like React, Vue or others. The ShadowDOM protects the DOM it contains from manipulations generated by other libraries.

Slot management

Slots allow us to reflect existing nodes in the lightDOM into the shadowDOM, example:

This is really useful, since we can group slots according to their name in a specific place of the webcomponent.

We invite you to learn more about slots through the following guide:

CSS appearance of web component.

The shadowDOM allows you to do something fantastic, protect your CSS from global styles, this has 2 great advantages:

1. The appearance of our component will not be affected by global CSS declarations.

2. Customization protected by CSS custom Properties

We invite you to learn more about handling styles in atomic through the following guide:

The idea is to create an instance of AbortController every time the hook's parameters change. Each parameter change will abort the previously generated controller, thus cancelling any subscribed promises.

Example

The significant advantage of using useAbortController is the automatic cancellation of asynchronous processes that depend on it when modifying the arguments provided to useAbortController (similar to useEffect).

Atomico makes it easy to declare events at the type level using the Host type.

Example

In the previous code, we have declared the onMyCustomEvent event at the type level. According to the template logic, this event will be dispatched every time the button is clicked, and the detail attached to this event will be of type CustomDetail.

1. Its name cannot have the on prefix since, if it does, Atomico will recognize it as a property expecting to listen to the event.

2. It can only have one listener, limiting others from observing the event.

We recommend:

1. Using the hook to dispatch component-level events or any custom hook.

2. Using the API to dispatch events when the observed prop changes.

Always prefer the two previously mentioned methods, as they allow you to:

1. Define if the event bubbles.

2. Define if the event is cancelable.

3. Define if the bubbling event can penetrate the shadow DOM.

4. Define a custom constructor for the event.

5. Having multiple listeners for the event