@logilab/cwelements/README.md

Library of reusable React components for building web application with cubicweb

# cwelements

CWElements is a library of reusable React components for building web application with CubciWeb.
It relies on [@logilab/cwclientlibjs](https://www.npmjs.com/package/@logilab/cwclientlibjs) to query a CubicWeb instance.

To know what's in CWElements, read [Description of the main components](#description-of-the-main-components).

To use a component with `monaco-editor`, which is needed for the syntaxic colouring, read [Using monaco-editor-based components](#using-monaco-editor-based-components).

For details about the components architecture, read [Library architecture](#library-architecture).

## Description of the main components

### Entity Form

The [EntityForm](src/EntityForm.tsx) displays a detailed description of a CubicWeb instance entity, entity type, relation or attribute referenced by an EID.
For the concerned EID, a list of its attributes is displayed using [EntityAttribute](src/EntityAttribute.tsx) (and its subclasses: FloatEntityAttribute, IntegerEntityAttribute, _etc._); followed by a list of its relations grouped by relation name ([MergedEntityRelationsGroup](src/MergedEntityRelationsGroup)).

### Entity Browser

The [EntityBrowser](src/EntityBrowser.tsx) allows browsing a CubicWeb schema with an EID search bar.
An EntityForm of the entity, entity type, relation or attribute designated by the EID is displayed.
The entities, entity types, relations or attributes in an EntityBrowser can also be browsed by clicking on the links displayed in an EntityForm.

![entity browser screenshot](docs/EntityBrowser.png 'Entity Browser using an Entity Form')

### Schema Navigator

The [SchemaNavigator](src/schema-navigator/SchemaNavigator.tsx) loads and displays a CubicWeb schema.
When instanciating a SchemaNavigator, you can decide to show or hide the CubicWeb Metamodel entities.
It is composed of three columns: the first displays the schema's CWETypes, the second one the CWRelations and CWAttributes
and the third one CWETypes based on the selected CWRelation.
The user can filter the column lists based on the items' name with a search bar.
The user can click on the items to select them and filter the other columns based on the constraints between them. For example, if a user selects
"Comment" in the first column, the second column is updated to show only the relations and attributes which apply to "Comment" and
the third column only shows the entity types which can be linked to "Comment".

![schema navigator screenshot](docs/SchemaNavigator.png 'Schema Navigator with a User selecting *Comment*')

### RQL Querier

The RQL Querier is a component to query a CubicWeb instance. A standalone version is available ([StandaloneRqlQuerier](src/StandaloneRqlQuerier.tsx)).
The basic components of a RQL Querier are a query input field, an execute button and a query results element.
Different versions of these components are available: QueryInputText and QueryMonacoEditorTextInput (in [QueryInput](src/QueryInput.tsx)) for the query input field, JSONQueryResults, TableQueryResults and TabbedQueryResults (in [QueryResults](src/QueryResults.tsx)).

![rql querier screenshot](docs/RqlQuerier.png 'RqlQuerier with QueryMonacoEditorTextInput and TabbedQueryResults')

### RQL Browser

The [RqlBrowser](src/RqlBrowser.tsx) is a tool to help write RQL queries. It instanciates a Schema Navigator and a RqlQuerier.

A _Show Metamodel_ option can show CubicWeb metamodel entities and relations in the Schema Navigator.

A _Auto-help_ option can change filter the Schema Navigator columns based on the cursor position in the QueryEditor.

A _Clear selection_ button can reset the Schema Navigator state (clear search bars and selection).

![rql browser screenshot](docs/RqlBrowser.png 'RQL Browser')

## Using monaco-editor-based components

The QueryMonacoEditorTextInput, included in RqlBrowser and RqlBrowserQuerier is based on [monaco-editor](https://www.npmjs.com/package/monaco-editor) for syntaxic colouring, cursor tracking, etc.

To make it work, you need to install `monaco-editor` in your own project:

```bash
npm install monaco-editor
```

## Library architecture

### Historic global component architecture

For now, most components follow an architecture in which an interface or a class(_e.g._, [EntityBrowser](src/EntityBrowser.tsx)) is defined using its own props and state interfaces (_e.g._, EntityBrowserProps and EntityBrowserState).

Then a component (_e.g._, [DefaultEntityBrowser](src/EntityBrowser.tsx#L143)) implements this interface using default props defined in a constant (_e.g._, [ENTITY_BROWSER_DEFAULT_PROPS](src/EntityBrowser.tsx#L92)).

The props include rendering functions and the Default components the inherent logic and state update.

A rendering function defined in the props is likely to call another rendering function of the props. The `render` function of [ENTITY_BROWSER_DEFAULT_PROPS](src/EntityBrowser.tsx#L92) calls `renderInput`, `renderViewWaiting` and `renderViewData` from the [DefaultEntityBrowser](src/EntityBrowser.tsx#L143). So if you override many functions check that they have the expected behaviour.

The components which follow this logic are:

-   [DefaultEntityBrowser](src/EntityBrowser.tsx#L143) implements [EntityBrowser](src/EntityBrowser.tsx)
-   [DefaultEntityForm](src/DefaultEntityForm.tsx) extends [EntityForm](src/EntityForm.tsx)
-   [DefaultEntityRelation](src/DefaultEntityRelation.tsx) extends [EntityRelation](src/EntityRelation.tsx)
-   [EntityRelationsGroup](src/EntityRelationsGroup.tsx) is extended by [DefaultEntityRelationsGroup](src/DefaultEntityRelationsGroup.tsx) and [MergedEntityRelationsGroup](src/MergedEntityRelationsGroup)
-   [EntityRelationsEditor](src/EntityRelationsEditor.tsx) is implemented by [DefaultEntityRelationsEditor](src/EntityRelationsEditorDefault.tsx) and [SingleEntityRelationsEditor](src/EntityRelationsEditorSingle.tsx)
-   [EntityAttribute](src/EntityAttribute.tsx) is extended by [DefaultEntityAttribute](src/DefaultEntityAttribute.tsx), [BooleanEntityAttribute](src/BooleanEntityAttribute.tsx), [EnumEntityAttribute](src/EnumEntityAttribute.tsx), [FloatEntityAttribute](src/FloatEntityAttribute.tsx), [FloatEntityAttributeWithStaticUnit](src/FloatEntityAttributeWithStaticUnit.tsx) and [IntegerEntityAttribute](src/IntegerEntityAttribute.tsx)

### Hooks as a replacement

In earlier versions of this library, the RqlQuerier (a component to edit, execute and view the results of an RQL query) worked as explained above: rendering functions were defined as constant default props, and the logic behind the component (executing the query, etc.) was implemented in the DefaultRqlQuerier component.
To make this component more flexible, its state and logic (_e.g._, query execution) have been gathered in a functional state [useQuery](src/useQuery.tsx) which can be reused in any component dealing with their own rendering.
The functional components [StandaloneRqlQuerier](src/StandaloneRqlQuerier.tsx) and [RqlBrowser](src/RqlBrowser.tsx) both uses the functional state [useQuery](src/useQuery.tsx) with their own rendering.
This logic was also applied to the SchemaNavigator.