# Droost UI Kit

> Build Manage Display from Single Directory Components on UI Patterns 2, through droost's site-building tools.

**Build Manage Display from Single Directory Components, through
[Droost](https://droost.org/docs/module.md)'s site-building tools.**

Drupal Canvas builds freeform pages from Single Directory Components (SDCs).
Droost UI Kit does the same for **Manage Display**: an entity's fields are
bound to a component's props and slots, deterministically, with
[UI Patterns 2](https://www.drupal.org/project/ui_patterns) as the storage
underneath.

```
entity fields → source mapping → SDC props and slots → render
```

## The tools

| Tool | Kind | What it answers |
|---|---|---|
| `droost_sdc_components` (droost_build) | read | What components exist? What props, slots and schemas does one have? |
| `droost_display_get` (droost_build) | read | What does a display look like now, as a field-to-component mapping? |
| `droost_display_check` (droost_build) | read | Does every binding a stored display names (component, source, context) exist? |
| `droost_display_sources` | read | What can feed a prop or slot, including a field's own properties and formatters? |
| `droost_display_compose` | write (gated) | Bind fields to components; validate everything; save. |

An agent picks a component, picks its sources, composes with
`dry_run: true`, then composes for real and views the entity:

```bash
drush droost:tool droost_display_sources '{"prop_type":"slot","bundle":"event","field":"body"}'
drush droost:tool droost_display_compose help
```

## Validation and write access

- `droost_display_compose` runs from the command line and checks the
  `allow_config_write` gate. CLI writes are enabled by default unless the
  site disables them; changing an explicit gate setting is an operator action.
  See [Write gates](https://droost.org/docs/module-gates.md).
- Validation is all or nothing: one error anywhere and nothing is written.
- A binding written any other way, through `droost_config_set`, is held to
  the same rule.
- The configuration it writes passes Drupal's strict schema check.
- Composing twice gives the same result, so verify with
  `droost_display_get` instead of retrying.

## Install

For development sites: like droost's build tools, this module belongs in
`require-dev`.

```bash
composer require --dev 'drupal/tool:^1.0@beta' 'drupal/droost:^2.0' \
  'drupal/droost_build:^2.0' 'drupal/droost_ui_kit:^2.0'
drush en droost_ui_kit
```

Tool API is still in beta, so the site requires it at that stability.
drupal.org resolves this module's dependency on `droost_build` as the
package `drupal/droost_build`, so require it at droost's version.

## Canvas and UI Patterns, together

Canvas and UI Patterns both take over Drupal's SDC plugin manager
([#3561618](https://www.drupal.org/project/canvas/issues/3561618)). From UI
Patterns 2.0.22, which this module requires, the two coexist with no patch
and no bridge module (measured on Canvas 1.12.0).

## Formerly Droost UI Patterns

This module began as a droost submodule (`droost_display`, then
`droost_ui_patterns`) and became its own project as
[Droost UI Patterns](https://www.drupal.org/project/droost_ui_patterns). It
was renamed Droost UI Kit because the old name never reached
packages.drupal.org. Droost UI Patterns is retired. The tool ids,
configuration and gate are unchanged.

## Requirements

- Drupal 11.3 or later, PHP 8.3 or later.
- [Droost](https://droost.org/docs/module.md) 2.0.0 or later, with its
  `droost_build` submodule (enabled with this module).
- [UI Patterns](https://www.drupal.org/project/ui_patterns) 2.0.22 or later,
  with `ui_patterns_field_formatters`.

The project: [Droost UI Kit on drupal.org](https://www.drupal.org/project/droost_ui_kit).