@coveo/atomic

Atomic

A web-component library for building modern UIs interfacing with the Coveo platform. Atomic web-components are built with Stencil. They are self-encapsulated, composable, and light-weight.

Getting Started

Once you have cloned the repo, follow the instructions in the top-level README.md to install dependencies and link packages.

To start the project in development mode, run:

npm start

To build the library for production, run:

npm run build

To run the unit tests for the components, run:

npm test

Using the components

Script tag

• Put a script tag similar to this <script src='https://unpkg.com/my-component@0.0.1/dist/mycomponent.js'></script> in the head of your index.html
• Then you can use the element anywhere in your template, JSX, html etc

Initialization

• To initialize the atomic-search-interface component, you have to add a script tag calling initialize(...) on it once the custom element is defined:

<script>
  (async () => {
    await customElements.whenDefined('atomic-search-interface');
    document.querySelector('atomic-search-interface').initialize({
      accessToken: 'my_token',
      organizationId: 'my_org',
    });
  })();
</script>

• All other components have to be the child of an initialized atomic-search-interface to work properly.
• For testing or demo purposes, adding the sample attribute on the atomic-search-interface element is sufficient and will bypass initialization.

Node Modules

• Run npm install @coveo/atomic --save
• Put a script tag similar to this <script src='node_modules/@coveo/atomic/dist/mycomponent.js'></script> in the head of your index.html
• Then you can use the element anywhere in your template, JSX, html etc

In your app

• Run npm install @coveo/atomic --save
• Add an import to the npm packages import '@coveo/atomic';
• Then you can use the element anywhere in your template, JSX, html etc

Run Cypress for Atomic components

Ref: https://docs.cypress.io/

• All the tests will need to be under folder cypress\integration

Open

To open cypress, run:

npm run cypress:open

To run all the test, run:

npm run cypress:test

Utilities

The InitializeBindings, BindStateToController & BindStateToI18n decorators

The InitializeBindings is an utility that automatically fetches the bindings from the parent atomic-search-interface component. This decorator should be applied to the bindings property directly.

Important In order for a component using this decorator to render properly, it should have an internal state bound to one of the property from bindings. This is possible by using either the BindStateToController or the BindStateToI18n decorator.

Here is a complete example using all these decorators:

@Component({
  tag: 'atomic-component',
  shadow: true,
})
export class AtomicComponent {
  @InitializeBindings() public bindings!: Bindings;
  private controller!: Controller;

  // Will automatically subscribe the `controllerState` to state of the `controller`
  @BindStateToController('controller')
  @State()
  private controllerState!: ControllerState;

  // Will automically update the strings on initialization and when the locale changes
  @BindStateToI18n()
  @State()
  private strings = {
    value: () =>
      this.bindings.i18n.t('value', {
        /* options */
      }),
  };

  // Method called after bindings are defined, where controllers should be initialized
  public initialize() {
    this.controller = buildController(this.bindings.engine);
  }

  render() {
    return [this.strings.value(), this.controllerState.value];
  }
}