Back-Kit Events

Events are data structures sent into a communication channel to enable event-driven component behavior. They extend an any object and they come as

type Event<P, M> = {
  label: string
  payload: P
  meta?: M
}

where label is a unique string identifying the event such as "create-data" or "delete-file", payload contains transactional data and meta other data with extra information like what action triggered this event, a transaction ID if there's any and so on.

To create a new event within src/events there's a factory method which is a generic function that takes the P and M types with the label

export function factory<P extends Payload = Payload, M extends Meta = Meta> (
  label: string, options: FactoryOptions = {}
): Factory<P, M> {
  ...
}

This function generates a function with hybrid prototype that contains:

an event generator
a predicate .is( to check whether an event was made with the current generator
a label which returns the generator and its spawned events label

for instance

const addNew = factory<Record<string, never>>('add-new')

const addNewEvent = addNew({})

expect(addNew.is(addNewEvent)).toBeTruthy()
expect(addNew.label).toStrictlyEqual('add-new')

There's also the concept of a register which automatically adds event is on factory call the constant

const REGISTERED = true

is provided. In that case, src/events/eventRegister.ts exports an eventBuilderRegister map that contains only registered event generators. It has an .add( method which is idempotent on a factory with the same label already contained in the register.

An eventBus conforming event is an object like

{
  label: string,
  payload: object,
  meta: object,
}

label is a unique event identifier. Standard Back-kit events are always kebab-case idiomatic strings,
payload is an object, possibly empty,
meta helps to keep track of transaction states or enhance event scoping. Meta is not required and its value might be an empty object.

For instance an upload-file event looks like:

{
  label: "upload-file",
  payload: {
    file: {
      lastModified: 1627457290180,
      lastModifiedDate: "Wed Jul 28 2021 09:28:10 GMT+0200 (Central European Summer Time)",
      name: "file.pdf",
      size: "9090",
      type: "application/json",
      uid: "rc-upload-1630930409639-3"
    }
  },
  meta: {
    transactionId: "97de9662-70aa-48a0-bdee-25113fc66c8f"
  }
}

A

Add Filter

delivers data to add a new filter

Label: add-filter
Payload:

{
  operator:
    | "equal"
    | "exists"
    | "notEqual"
    | "greater"
    | "greaterEqual"
    | "less"
    | "lessEqual"
    | "regex"
    | "includeSome"
    | "includeAll"
    | "includeExactly"
    | "notIncludeAny"
    | "between"
    | "notBetween"
    | "hasLengthEqual"
    | "hasLengthGreaterEqual"
    | "hasLengthLessEqual"
  property: string
  value: string | number | boolean | any[]
  applied?: boolean
  name: string
}

Meta:

{
  hash: string
}

Add New

notifies adding a new item

Label: add-new
Payload:

{
  [key: string]: any
}

Add New External

notifies adding a new item on an external collection

Label: add-new-external
Payload:

{
  [key: string]: any
}

B

Bulk update - Boolean and Enums

allows to modify enums or boolean values from an array of items

Label: bulk-update
Payload:

{
  data: {
    [key: string]: any
  }[]
  changes: {
    [key: string]: string | boolean
  }[]
}

C

Cancel

notifies operation abort via a given transactionId

Label: event-bus-cancel
Payload:

{}

Meta:

{
  transactionId: string
}

Change Filter

delivers data on an edited filter

Label: change-filter
Payload:

{
  operator:
    | "equal"
    | "notEqual"
    | "greater"
    | "greaterEqual"
    | "less"
    | "lessEqual"
    | "regex"
    | "includeSome"
    | "includeAll"
    | "includeExactly"
    | "notIncludeAny"
    | "between"
    | "hasLengthEqual"
    | "hasLengthGreaterEqual"
    | "hasLengthLessEqual"
  property: string
  value: string | number | boolean | any[]
  applied?: boolean
  name: string
}

Change Query

requires a modification of the currently viewed dataset (filtering, sorting, paging)

Label: change-query
Payload:

{
  characteristic?: string
  pageNumber?: number
  pageSize?: number
  search?: string
  sortDirection?: SortDirection
  sortProperty?: string
  filters?: {
    operator:
      | "equal"
      | "notEqual"
      | "greater"
      | "greaterEqual"
      | "less"
      | "lessEqual"
      | "regex"
      | "includeSome"
      | "includeAll"
      | "includeExactly"
      | "notIncludeAny"
      | "between"
      | "hasLengthEqual"
      | "hasLengthGreaterEqual"
      | "hasLengthLessEqual"
    property: string
    value: string | number | boolean | any[]
    applied?: boolean
    name: string
  }[]
}

Close Modal

closes a modal

Label: close-modal
Payload:

{
  modalId: string
}

Meta:

{
  sessionId?: string
}

Count Data

sends count and pagination of current dataset

Label: count-data
Payload:

{
  total: number
  pageSize: number
  pageNumber: number
}

Create Data

notifies the request for creation of a new item and carries its value

Label: create-data
Payload:

{
  [key: string]: any
}

Create Data With File

create data that have one or more files within their properties, the current file property is set into meta

Label: create-data-with-file
Payload:

{
  data: {
    [key: string]: any
  }
}

Meta:

{
  property: string
}

D

Delete Data

notifies the request for deletion of an item

Label: delete-data
Payload:

{
  [key: string]: any
}
| {
  [key: string]: any
}[]

Delete File

notifies that a given file, identified by its unique id, must be deleted

Label: delete-file
Payload:

{
  file: string
}

Meta:

{
  transactionId: string
}

Deleted File

notifies that a given file was deleted, carries a transaction ID to rollback

Label: deleted-file
Payload:

{
  [key: string]: any
}

Meta:

{
  transactionId: string
}

Display Data

carries a dataset

Label: display-data
Payload:

{
  data: any
}

Download File

notifies that a given file must be downloaded. Payload could be either the file identifier or a structure that contains it. In the latter case, the object property to find the file must be set into the meta. It carries transaction ID to rollback. Allows to request in-browser view of the file.

Label: download-file
Payload:

{
  file?: string
  [key: string]: any
}

Meta:

{
  transactionId?: string
  property?: string
  showInViewer?: boolean | "skip-checks"
}

Downloaded File

notifies that a given file was downloaded, carries a transaction ID to rollback

Label: downloaded-file
Payload:

{
  file: string
}

Meta:

{
  transactionId: string
}

Duplicate Data

notifies the request for duplication of an item and carries its value

Label: duplicate-data
Payload:

{
  [key: string]: any
}

E

Error

notifies a generic error event

Label: error
Payload:

{
  error: any
}

Meta:

{
  triggeredBy: string
  transactionId: string
}

Export Data

raised when the export button is clicked

Label: export-data
Payload:

{}

Export Data - Request Config

prompts for export configuration payload

Label: awaiting-for-export-configuration
Payload:

{
  total?: number
  selected?: number
  columns: {
    label: string
    value: T
  }[]
}

Meta:

{
  transactionId?: string
}

Export Data - User Config

sends user configuration payload to perform export

Label: export-user-config
Payload:

{
  exportType: "json" | "csv" | "html" | "xlsx"
  csvSeparator?: "COMMA" | "SEMICOLON"
  filters: "all" | "filtered" | "selected"
  columns: string[]
  columnName: "id" | "label"
  dateFormat?: string
  timezone?: string
}

Meta:

{
  transactionId?: string
}

F

Fetch Files

notifies to requests to fetch files

Label: fetch-files
Payload:

{
  limit?: string | number
  page?: string | number
  dateFrom?: string
}

Meta:

{
  transactionId?: string
}

Fetched Files

carries result of files fetching operation

Label: fetched-files
Payload:

{
  files: {
    [key: string]: unknown
  }[]
}

Meta:

{
  transactionId?: string
}

Filter

notifies opening of UI component that handles form creation

Label: filter
Payload:

{}

H

Http Delete

notifies the request for permanent deletion of an item

Label: http-delete
Payload:

{
  [key: string]: any
}
| {
  [key: string]: any
}[]

I

Import Data

raised when the import button is clicked

Label: import-data
Payload:

{}

Import Data - User Config

sends user configuration payload to perform import

Label: import-user-config
Payload:

{
  file: File
  encoding?: "utf8" | "ucs2" | "utf16le" | "latin1" | "ascii" | "base64" | "hex"
  delimiter?: string
  escape?: string
}

L

Layout Change

requires a layout change from bk-layout-container

Label: layout-change
Payload:

{
  layout: string
}

Link File To Record

sends file upload data

Label: link-file-to-record
Payload:

{
  data: {
    [key: string]: any
  }
}

Meta:

{
  property: string
}

Loading Data

notifies whether dataset is loading or not. It also advices that a dataset may be inbound

Label: loading-data
Payload:

{
  loading: boolean
}

Lookup Data

carries lookup data information and dataset

Label: lookup-data
Payload:

{
  [key: string]: any[]
}

Meta:

{
  dataOrigin?: string
}

Lookup Live Found

fired when options for a Select form input are found

Label: lookup-live-found
Payload:

{
  [key: string]: any[]
}

Lookup Live Searching

fired upon searching on a Select form input

Label: lookup-live-searching
Payload:

{
  property: string
  input: string
}

Meta:

{
  limit: number
  input: {
    [key: string]: any[]
  }
  currentValues?: any[]
  keys?: string[]
}

N

Nested Navigation State - Display

displays data or a slice of data

Label: display-state
Payload:

Array<{
  data: Record<string, any>[]
  from?: number
  to?: number
  sort?: number[]
}>

Meta:

{
  keys?: string[]
}

Nested Navigation State - Go Back

goes back an arbitrary number of levels of nesting

Label: back-state
Payload:

{
  steps?: number
}

Nested Navigation State - Push

adds a new level of nesting

Label: push-state
Payload:

{
  data: Record<string, any>[]
  origin: Record<string, any>
  selectedKey?: string
}

O

Open Modal

opens a modal

Label: open-modal
Payload:

{
  modalId: string
}

Meta:

{
  sessionId?: string
}

R

Require Confirm

Signals that a certain action requires confirmation to be performed

Label: require-confirm
Payload:

{
  cancelText?: LocalizedText
  content?: LocalizedText
  okText?: LocalizedText
  onCancel?: () => {}
  onOk?: () => {}
  title?: LocalizedText
  configOk?: {
    tag: string
    properties?: Record<string, any>
    children?: string | ReactNode
  }
  configCancel?: {
    tag: string
    properties?: Record<string, any>
    children?: string | ReactNode
  }
}

S

Search Lookups

notifies that all lookups having excludeFromSearch set to false should be searched against a value

Label: search-lookups
Payload:

{
  input: string
}

Meta:

{
  limit: number
}

Search Lookups Found

fired when values from a text search for lookups are found

Label: search-lookups-found
Payload:

{
  [key: string]: any[]
}

Meta:

{
  input: string
}

Selected Data

notifies that a single datum has been selected from a dataset

Label: selected-data
Payload:

{
  data: {
    [key: string]: any
  }
}

Selected Data Bulk

notifies data selection in a dataset

Label: selected-data-bulk
Payload:

{
  data: Array<{
    [key: string]: any
  }>
}

Show In Viewer

notifies the request for starting/updating the visualization of a PDF file

Label: show-in-viewer
Payload:

{
  show: boolean
  url: string
}

Submit Form - Request

requests submission of form

Label: submit-form-request
Payload:

{}

Meta:

{
  openingEvent: string
  formId: string
}

Submit Form - Success

notifies correct submission of form

Label: submit-form-success
Payload:

{}

Meta:

{
  transactionId?: string
}

Success

notifies a successful action

Label: success
Payload:

{}

Meta:

{
  triggeredBy: string
  transactionId: string
}

U

Update Data