This hook has a behavior similar to useEffect but focused on resolving the consumption of one or more references.

The useClickPress hook will allow you to execute a callback with acceleration according to the click time, for example in the input type number we have 2 buttons by default, an up arrow and a down arrow, these allow us to modify the input value, either:

1. Increase the value before a click in a unit.

2. Increase the value by more than one unit according to the click pressure time.

Example

import { useClickPress } from "@atomico/hooks/use-click-press";

function counter() {
  const refButton = useRef();

  const [value, setValue] = useProp("value");

  const increment = () => setValue((value) => value + 1);

  useClickPress(refButton, increment);

  return (
    <host>
      <h1>value: {value}</h1>
      <button ref={refButton}>Increment</button>
    </host>
  );
}

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

Live example

where:

1. ref, the reference to associate the event keydown and keyup.

2. keysCode: key combination to capture

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 ...

What have we imported?

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

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

Our function receives all the props (Properties and Attributes) declared in 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".

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.

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.

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.

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.

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

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.

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.

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.

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:

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.

Simple statements allow setting just type validations.

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.

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:

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

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

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

Atomico allows the definition of default values of the props.

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.

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:

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.

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 "

import { c, useProp } 

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. const props

Now I want to invite you to learn how to declare a style 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.

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

with Atomico there are certain differences:

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

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

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

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

Syntax

JSX

import { c } from "atomico";

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

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

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";

Return rule

import { c } from "atomico";

const MyComponent = c(() => {
  // The webcomponent should always return the host tag
  return (
    <host shadowDom>
      <slot></slot>
    </host>
  );
});

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

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.

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:

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

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:

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

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

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

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:

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

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. 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. makes it easy for you to maintain a token system efficiently and sustainably

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.

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.

The reference object is useful for referencing nodes between customHooks.

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.

Where:

1. update: Callback, force component update.

Where:

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

   • state

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

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.

Avoid creating an instantiable context node in the DOM.

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:

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

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:

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

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

import { useAsync, useAbortController } from 'atomico';

async function getUser(id: number, signal: AbortSignal) {
  return fetch(`/id/${id}`, { signal });
}

function myComponent({ userId }: Props<typeof myComponent>) {
  const { signal } = useAbortController([userId]);

  const user = useAsync(getUser, [userId, signal]);

  return <host>{user.name}</host>;
}

myComponent.props = { userId: { type: Number, value: 0 } };

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).

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.

import { createHooks } from "atomico/test-hooks";

createHooks

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

Instance

const hooks = createHooks(opcionalRender, opcionalHost);

Where:

• optionalRender: Callback that allows restarting the hook's life cycle, this callback will be executed every time a hook like useState or useReducer 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.

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.

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

./use-counter.test.js: The example is based on the test environment from .

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:

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:

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

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

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.

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

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

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.

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.

Cuando se busca comunicar parametros o leer el retorno de este, ejemplo:

We recommend the @web/test-runner 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 https://github.com/atomicojs/base/tree/2-started.

Advanced (Documentation in progress)

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

1. Cypress: 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.

If you are a React user, it is common for you to make component declarations like these:

export function MyComponent(){
    return <>My component in react</>
}

Thanks to the previous code in React we can:

1. Instantiate your component through its function, example <MyComponent>

2. Friendly export component as module

In Atomico there are some small differences

Export the return of the c function, since it is instantiable at the JSX level or when using the new operator, example:

Gracias a lo anterior podemos:

1. Instantiate your component with TS-level type validation either by using JSX or the new operator with, but remember that to get this type of instances you must first have registered your customElement in the same file or another.

2. Export the useful component to instantiate.

With Atomico and Typescript you will be able to:

Meta-types allow you to define properties not covered by Atomico's Automatic support, such as:

1. Type declaration

2. Event declaration

React and webcomponents

React has begun to support the use of webcomponents in an experimental way, this will allow to use custom tag with association of events and more, example:

import React from "react";
import "@formilk/components";

export default function App() {
  return (
    <fm-button>Click!<fm-button>
  );
}

Advantages: The react team will take care of the coverage of this characteristic.

Disadvantages: (Optional) The maintainer of the component must declare the types of the custom tag.

Although the use of the custom tag is a way of instantiating the component, many times it does not define the import path at the time of its use, complicating the resolution of the component's origin, to avoid this we recommend the use of the Atomico wrapper for React.

Atomico wrapper for React

Atomico the package @atomic/react allows:

1. Create a Wrapper component for the custom Element

2. Avoid react conflicts with webcomponents, such as association of events, attributes, properties and children.

3. Reflect the types declared in Atomic to React, valid for JSX or TSX

Coverage is automatic if you decide to share your package using under the following

All webcomponents work in Next if it escapes from SSR

Remember if you use the auto module, it should always be imported first than the customElement to use, otherwise auto will generate an id as a custom tag to instantiate the component within react

Atomico allows the definition of methods from the host tag, this in order to share the scope with the methods (Functions) of the component, but this escapes the definition of types, to patch this we must use the Host type, this will allow us to validate the method from the JSX, TSX and the component instance.

Host to method declaration

import {Host} from "atomico";

type MyMethod = (value: number)=>void;

function component():Host<{myMethod: MyMethod }>{
    const myMethod: MyMethod = ()=>{}
    return <host myMethod={myMethod }/>
}

Atomico integrates very easily into React, either using @atomico/exports or @atomico/react.

@atomico/exports

CLI that decorates the package.json according to the code to be exported in order to share your code optimally. By using the --wrappers flag the CLI will detect the export of webcomponents and automatically create a wrapper for React, Preact and Vue.

You can learn more about @atomico/exports in the following guide:

@atomico/react

With this package you will be able to create wrappers for your Webcomponents in React, even managing to make SSR of your webcomponents in environments like Next.js with these wrappers.

You can learn more about @atomico/react in the following guide:

1. Atomico will not limit your React learning curve, what you learned in Atomico is applicable in React, for example hooks and virtualDOM.

2. Atomico is 3kB in size which is 7% of React + React-dom.

Atomico has 3 great hooks to solve asynchronous tasks:

1. : Processes asynchronous tasks and shows the status and resolution of these

2. : Allows you to pause rendering until a promise is resolved

The use of slots improves the composition allowing to reflect the content exposed in the lightDOM of the component in the shadowDOM of this, example:

::slotted(<selector>)

The slotted selector allows the manipulation of the content exposed as a lightDOM slot from the shadowDOM, example:

Auto slot

With Atomico you can define a default slot for your components, this is useful if you want to maintain some compositional consistency without the need to declare the use of slot, example:

To define a default slot, you only have to declare slot in the props, example:

Consider this practical only if the composition is leveraged to the container, this does not prevent you from modifying the slot property from the component instance.

Atomico has the hook that appends the slotchange event to a reference, this will allow you to hide slots if they do not declare content, example:

Normally we create webcomponents that only work with lightDOM or shadowDOM, example:

function componentWithLightDom() {
  return (
    <host>
      <h1>I am in the lightDOM</h1>
    </host>
  );
}

function componentWithShadowDom() {
  return (
    <host shadowDom>
      <h1>I am inside the shadowDOM</h1>
    </host>
  );
}

With atomico you can go further thanks to the hook @atomico/hooks/use-render which allows you to execute renders independent of the main one, example:

import { useRender } from "@atomico/hooks/use-render";

function componentWithLightDomAndShadowDom() {
  useRender(() => <h1>I am in the lightDOM</h1>);
  return (
    <host shadowDom>
      <h1>I am inside the shadowDOM</h1>
    </host>
  );
}

What are the benefits of using useRender?

1. Encapsulate DOM fragments within custom Hooks and then render to any webcomponent.

2. patch the limitations of webcomponents that use shadowDOM, to improve communication with forms.

With the useRender(...) fragment we are managing to render an input in the lightDOM, thanks to this we will be able to control said input from inside the webcomponent.

Thanks to useRender you will be able to work together with LightDOM and shadowDOM from the scope of the webcomponent created with Atomico.