# Components

These web components are custom elements (DOM elements) that serve as building blocks to make web software.

## Requirements

- Components should never rely on instances of other components, except if they live in the 'orchestrator' category or if the instance is a child of itself. Orchestrator components can refer to other components using a DOM selector, this can be provided via an attribute ending with `-selector` as its name. These orchestrators are responsible for bringing components together and making prebuilt setups.
- Components rely on signals exposed via the `common/signal.js` module. Only signal getters are exposed, never the entire signal object.
- A base class should be built that all components build on. This should be made available via `common/element.js`.
- Components should be broadcastable, meaning that various instances of that component should be able to communicate with each other. This will be used to replicate state and call methods. Broadcasting should have two modes: 'replicate' and 'leaderOnly'. The former is executed on all instances, while the latter is only executed on the leader. Another base class should be provided for broadcastable components. A `group` attribute will be used to choose the group in which we'll broadcast, so can we can form groups of instances that communicate.
- Components live in the `components` directory.
- Another special category of components is 'configurator', those components take DOM children of the same category. For example, A configurator must have at least the same properties as the component provided via the DOM, but may have more.
- If heavy computation work or other work which could block the main thread is needed, the element should be accompanied by a web worker.
- A tunnel should be able to be formed between workers using message ports, passing the message port along using `postMessage`.
- Communication between different threads/workers should be performant.
- Register the custom element as soon as possible. Ideally using the `defineElement` helper to prevent double registration.
- When any namespace is needed, prefer to prefix with `diffuse/`
- When code is shared between files from a specific component, components in a specific category, or components across different categories; put it in a `common.js` file (or `common` directory with multiple js files if it gets too big) on the appropriate level.
- Tag naming convention: all lowercase, starts with letter `d`, then the first letter of each sub category, a dash, and finally the name of the element in kebab case. Collisions may occur with the prefix, in that case, change the element name.
- All elements should have a `static NAME` property with the directory path in src prefixed with `diffuse/`.

## Other categories

### Artwork

Various ways to fetch artwork for tracks. Must adhere to types defined in `artwork/types.d.ts`


### Engine

All kinds of core behaviour.


### Input

Input components generate tracks and resolve track URIs into audio. They must adhere to types defined in `input/types.d.ts`


### Metadata

Various ways to fetch metadata for tracks. Must adhere to types defined in `metadata/types.d.ts`


### Upload

Upload components handle uploading audio files to cloud storage (e.g. Dropbox) and deleting them again. They are paired with input components by scheme: an upload component's `SCHEME` matches the input component that can resolve the URIs it produces. `upload()` returns a URI carrying that scheme, which is stored on a track; the matching input component can then resolve it, and `delete()` the file remotely. Must adhere to types defined in `upload/types.d.ts`


### Output

Output components hold all the user data: facets, playlist items, settings and tracks. They all have the same surface API. Data is exposed via a signal getter called `collection`, one for each kind of data. These components are also responsible loading and saving that data. The data may be encoded, each component decides for its own what the type of the data is. The subcategory states what that type is and this is reflected in the directory structure these components live in:

- `polymorphic`: The data can be of multiple types.
- `raw`: The data is not encoded at all, it is of the same type stated in the definitions (lexicons).
- `bytes`: Encoded as `Uint8Array`.

Must adhere to types defined in `output/types.d.ts`


### Supplement

All kinds of additional components, not really required to make a working audio player application. Scrobbling for example.


### Transformer

Transformers are also intermediate components like configurators, with the same API requirements. They don't take DOM elements as children however, instead they serve to be used as a chain. Output transformers have a `output-selector` which chains the transformer to another component. These output transformers also have the same subcategories and directory structure as the output category.