# Note

For the main Describo project visit: https://www.npmjs.com/package/@describo/crate-builder-component

This is a fork of the Crate Builder Component for use in the [ARP project](https://researchdata.hu/en). Contains additions and modifications necessary for the ARP project that are not present/required/supported by the original component. We, however, try to keep compatibilioty with the original project as much as possible and update to its new version. 

The package version matches the latest version  of the original Crate Builder project (eg. 0.80.0) and an additional `-arp.X` marks the patch version for ARP. For example, `0.80.0-arp.12` is based on the `0.80.0` version of the Crate Builder Component and is the `12th` patched version of it for use in ARP.

# Crate Builder Component

-   [Crate Builder Component](#crate-builder-component)
-   [Documentation](#documentation)
-   [API Documentation](#api-documentation)
-   [ARP feature notes](#arp-feature-notes)
    -   [AI metadata review](#ai-metadata-review)
    -   [Quick filter/settings header](#quick-filtersettings-header)
    -   [Profile action management](#profile-action-management)
-   [Developing the plugin](#developing-the-plugin)
    -   [Storybook](#storybook)
    -   [Development application](#development-application)
-   [Building and publishing a release](#building-and-publishing-a-release)
-   [Building and publishing API docs - has to be separate stage](#building-and-publishing-api-docs---has-to-be-separate-stage)
-   [Repository structure](#repository-structure)

This is the core UI component for assembling an RO-Crate inside Describo. It is a self contained
React component that can be used inside your app. If you use this component, your app is responsible
for loading the crate file from the storage layer (or minting a new one if none exists) and saving
the updated crate back. Your app can also provide a profile to the component and a class to handle
template lookups.

# Documentation

Comprehensive documentation is available @
[https://describo.github.io/docs/component/introduction.html](https://describo.github.io/docs/component/introduction.html)

# API Documentation

-   [CrateManager](https://describo.github.io/crate-builder-component/CrateManager.html)
-   [ProfileManager](https://describo.github.io/crate-builder-component/ProfileManager.html)
-   [EditorState](https://describo.github.io/crate-builder-component/EditorState.html)

# ARP feature notes

The ARP fork adds several host-integrated workflows on top of the upstream crate builder. Their
public integration points are documented in the generated `DescriboCrateBuilderProps` API docs.

## AI metadata review

Pass `roCrateApproval` to display AI-generated metadata changes that still need review. The approval
payload is usually loaded from `ro-crate-approval.json` and can be an array of entity approval
objects, an object with an `items` array, or a single entity approval object with an `approval`
array.

Each approval record should include:

```json
{
  "propertyName": "title",
  "previousValue": "Original title",
  "operation": "update",
  "approved": false,
  "timestamp": "2026-05-12T08:15:00.000Z"
}
```

When pending records exist for the current entity, the editor shows the AI review banner, field-level
diffs, edited-field badges, and next/previous review controls. Accepting a field marks its records as
approved. Rejecting a field or making a manual edit removes the pending records from the approval
state. Persist approval state changes with `onSaveRoCrateApproval`.

```tsx
<DescriboCrateBuilder
  crate={crate}
  profile={profile}
  roCrateApproval={roCrateApproval}
  onSaveCrate={({ crate }) => saveCrate(crate)}
  onSaveRoCrateApproval={({ roCrateApproval }) => saveApproval(roCrateApproval)}
/>
```

## Quick filter/settings header

The control-bar settings button opens a quick settings header above the entity fields. It lets users
toggle field help, filter visible fields by label or value, hide empty fields, and, when approved AI
records exist, show only AI-edited fields.

Host applications can control the panel state with `quickSettingsVisible` and
`onQuickSettingsVisibleChange`.

```tsx
<DescriboCrateBuilder
  crate={crate}
  profile={profile}
  quickSettingsVisible={quickSettingsVisible}
  onQuickSettingsVisibleChange={setQuickSettingsVisible}
/>
```

## Profile action management

Set `enableProfileActions` or provide profile action callbacks to show add/remove profile controls in
the profile tab rail. `onAddNewProfileRequest` tells the host that the user wants to add a profile to
the current entity. `onRemoveProfile` gives the host the entity id and selected profile tab metadata,
including whether the tab has data or missing required fields.

```tsx
<DescriboCrateBuilder
  crate={crate}
  profile={profile}
  enableProfileActions
  onAddNewProfileRequest={() => openProfilePicker()}
  onRemoveProfile={({ entityId, tab }) => removeProfileFromEntity(entityId, tab)}
/>
```

# Developing the plugin

## Storybook

[Storybook](https://storybook.js.org/) is used in this application. When you are just developing the
components, storybook is what you want as you can focus just on the component in isolation. To start
it run:

```
npm run storybook
```

## Development application

When you want to see the component in action as a whole, there is a small React app in this
codebase. To start up the dev environment:

```
> npm install
> npm run start

--> browse to localhost:9000
```

# Building and publishing a release

-   `npm run build`: This builds the plugin and styles that the react component uses
-   `npm version {minor|patch}`
-   `git push origin master --tags`
-   Go to the repo and create a release from the tag, documenting what is in it.
-   Publish to npm: `npm publish`
-   Create an issue in the
    [React component issue tracker](https://github.com/describo/crate-builder-component-react/issues)
    to inform that a new release of that component needs to be built and published to npm.

# Building and publishing API docs - has to be separate stage

-   `npm run docs`: Update the jsdoc documentation
-   `git add . && git commit -a`
-   `git push origin master --tags`

# Repository structure

-   The development app is at `./src/app`. In there you will find the file index.tsx where we import
    the plugin and wire it into React as well as an App.tsx file where we load the component.
-   The component is at `./src/crate-builder`.
