Rossini Postgrest UI

This repository contains react components to display and edit tables using postgrest.

ake a look at the docs to see components exported by rossini-postgrest.

React components usage

DBTable

The main component is DBTable, which can be used by passing postgrestURL and editable props:

<DBTable
    postgrestURL='http://localhost:8000/api/db'
    dbTable='table_name'
    editable
/>

Props

• postgrestURL (string): base url where postgrest endpoints are reachable
• dbTable (string): name of the table
• params { [key: string]: string }: any additional query params to be passed to postgrest
• editable boolean: will allow editing the table
• singleSelectColumns {[key: string]: string[]}: a map where the keys are table columns and the values are a list of selectable options
• newRowTemplate: an object containing the default values for a new row

Any additional prop will be passed to the underlying DataGrid.

TableFilters

Provides filters for the given columns of a table. The callback onChange will receive an object that can be used as query params for postgrest

<TableFilters
  columns={[
    {
      name: 'foo',
      label: 'Foo',
      type: 'date'
    },
    {
      name: 'bar',
      label: 'Bar',
      type: 'string',
      valueOptions: [{value: 'a', label: 'A'}, {value: 'b', label: 'B'}]
    }
  ]}
  onChange={(filters) => {...}}
/>

Structured Data Forms

The library provides a set of components to create and manage forms based on structured data schemas. These components support both flat table structures and dynamic JSONB columns.

BaseStructuredDataForm

Low-level component that renders a form based on a StructuredTableModel. Use this when you already have a table model and initial values.

<BaseStructuredDataForm
  tableModel={myTableModel}
  initialValues={data}
  editing={true}
  onSubmit={(data) => console.log(data)}
/>

Props

• tableModel (StructuredTableModel): defines the form structure
• initialValues (object): initial form data
• editing (boolean): enable/disable edit mode
• onSubmit (function): callback when form is submitted
• onChange (function): callback on every field change
• showSaveButton (boolean): show/hide save button (defaults to editing value)
• fieldSize (GridBaseProps['size']): grid columns per field (1-12 or responsive object)
• customConfirmLabel (StringTranslation): custom label for save button
• deletable (boolean): show delete button
• onDelete (function): callback when delete is confirmed
• optionalNodes (ReactNode[]): additional nodes to render alongside form actions
• warnings (function): function to display warnings for specific fields
• showPreview (boolean): preview mode, see Preview mode

StructuredDataForm

Wrapper around BaseStructuredDataForm that loads data from a PostgreSQL table via PostgREST. Use this for tables with flat column structure (each field is a column).

<StructuredDataForm
  postgrestUrl='http://localhost:3000'
  tableModel={myTableModel}
  rowId={123}
  editing={true}
  onSave={() => console.log('saved')}
/>

Props

• postgrestUrl (string): PostgREST API base URL (not needed with showPreview)
• tableModel (StructuredTableModel): defines the form structure
• rowId (string | number): ID of the row to edit (not needed with showPreview)
• rowIdColumn (string): name of the ID column (default: 'id')
• editing (boolean): enable/disable edit mode
• onSave (function): callback after successful save
• onClose (function): callback when form is closed
• showPreview (boolean): preview mode, no row is fetched (see Preview mode)
• All props from BaseStructuredDataForm are also supported

StructuredDataFormFromUrl

Like StructuredDataForm but loads the table model from a JSON URL instead of passing it as a prop.

<StructuredDataFormFromUrl
  postgrestUrl='http://localhost:3000'
  tableModelJsonUrl='https://example.com/model.json'
  rowId={123}
  editing={true}
/>

DynamicStructuredDataForm

NEW: Advanced component for dynamic schemas stored in JSONB columns. Fetches the schema from field_definitions table and manages data in a JSONB column (e.g., extracted_data).

<DynamicStructuredDataForm
  postgrestUrl='http://localhost:3000'
  dataTableName='egon_reports'
  dataColumn='extracted_data'
  rowId={123}
  schemaId='egon_report'
  inputSourceFilter='user_input'
  editing={true}
  onSave={() => console.log('saved')}
/>

Props

• postgrestUrl (string): PostgREST API base URL (always required, the schema is fetched from it)
• dataTableName (string): name of the table containing the data (e.g., 'egon_reports'; not needed with showPreview)
• dataColumn (string): name of the JSONB column containing structured data (e.g., 'extracted_data'; not needed with showPreview)
• rowId (string | number): ID of the row to edit (not needed with showPreview)
• rowIdColumn (string): name of the ID column (default: 'id')
• schemaId (string): schema identifier in schema_versions table (default: 'egon_report')
• inputSourceFilter ('user_input' | 'llm'): filter fields by input source
• editing (boolean): enable/disable edit mode
• showPreview (boolean): preview mode, only the schema is fetched (see Preview mode)
• All props from BaseStructuredDataForm are also supported

Features

• Automatically fetches schema from field_definitions table via v_active_schema_fields view
• Loads KB (knowledge base) values from kb_value_sets and kb_value_items
• Supports field filtering by input_source (show only user input or LLM fields)
• Handles CRUD operations on JSONB columns
• Schema updates are automatically reflected in the form

Database requirements The following tables/views must exist in your PostgreSQL database:

• v_active_schema_fields: view exposing active schema fields
• kb_value_sets: table containing KB value set definitions
• kb_value_items: table containing KB items for each value set

Preview mode

All structured form components accept a showPreview prop that renders only the structure of the form (groups, fields, labels and layout), with no data and no interaction. Useful to show what a form/schema looks like, e.g. in a schema editor or a template picker.

When showPreview is true:

• fields are rendered disabled and empty (initialValues are ignored)
• no row is fetched or saved: rowId, rowIdColumn, dataTableName and dataColumn are not needed
• editing, validation rules, warnings, onChange and onSubmit are ignored
• save/delete buttons and optionalNodes are hidden

// Static table model: no PostgREST connection needed
<BaseStructuredDataForm tableModel={myTableModel} showPreview />
<StructuredDataForm tableModel={myTableModel} showPreview />

// Dynamic schema: postgrestUrl and schemaId/schemaVersionId are still needed to fetch the schema
<DynamicStructuredDataForm
  postgrestUrl='http://localhost:3000'
  schemaId='egon_report'
  showPreview
/>

Outside preview mode the data source props (postgrestUrl/rowId for StructuredDataForm, dataTableName/dataColumn/rowId for DynamicStructuredDataForm) are still mandatory: if they are missing, the form shows an error and logs it to the console.

Form Field Types

Supported field types in StructuredTableModel:

• string: text input
• int / float: number input
• bool: checkbox
• literal: select dropdown with predefined options
• string_array: array of text inputs
• date: date picker
• datetime: date and time picker
• object: nested group of fields (can contain any of the above types)
• multilingual: NEW - multilingual text fields (stored as JSONB Record<string, string>)
• object_array: NEW - arrays of complex objects with arbitrary schema

Example: Complete Table Model

const tableModel: StructuredTableModel = {
  dbTableName: 'my_table',
  modelLabel: { en: 'My Form', it: 'Il mio modulo' },
  fieldsDirection: 'column',
  fields: [
    {
      type: 'string',
      name: 'title',
      label: { en: 'Title', it: 'Titolo' },
      dbColumn: 'title',
      optional: false
    },
    {
      type: 'literal',
      name: 'status',
      label: { en: 'Status', it: 'Stato' },
      dbColumn: 'status',
      literalValues: [
        { value: 'draft', label: { en: 'Draft', it: 'Bozza' } },
        { value: 'published', label: { en: 'Published', it: 'Pubblicato' } }
      ]
    },
    {
      type: 'object',
      name: 'metadata',
      label: { en: 'Metadata', it: 'Metadati' },
      fieldsDirection: 'row',
      fields: [
        {
          type: 'date',
          name: 'created_at',
          label: { en: 'Created', it: 'Creato' },
          dbColumn: 'created_at'
        },
        {
          type: 'int',
          name: 'views',
          label: { en: 'Views', it: 'Visualizzazioni' },
          dbColumn: 'views'
        }
      ]
    }
  ]
};

New Features: Multilingual and Object Array Fields

Multilingual Fields

Store translations in JSONB columns (Record<string, string>):

{
  type: 'multilingual',
  name: 'title',
  label: { en: 'Title', it: 'Titolo' },
  dbColumn: 'title',
  languages: [
    { id: 'it', label: { en: 'Italian', it: 'Italiano' } },
    { id: 'en', label: { en: 'English', it: 'Inglese' } }
  ]
}

Object Array Fields

Manage arrays of complex objects:

{
  type: 'object_array',
  name: 'literal_values',
  label: { en: 'Values' },
  dbColumn: 'literal_values',
  fields: [
    { type: 'string', name: 'value', label: { en: 'Value' } },
    { type: 'multilingual', name: 'label', label: { en: 'Label' }, languages: [...] }
  ]
}

📖 Full documentation: docs/NEW_COMPONENTS.md

Usage as a docker image

docker run -d \
    -e POSTGREST_URL=http://localhost:8000/ \
    -e ENABLE_EDITING=true \
    -p 3000:3000 \
    quay.io/deix/rossini-postgrest