Notes Component

Introduction

The Notes Component is a rich-text editor built on TipTap that enables users to create, edit, and manage threaded notes for any entity in CargoXplorer TMS. It provides a powerful documentation and collaboration system with support for mentions, tags, rich formatting, and full-text search across logistics workflows.

Key Concepts:

• Notes are automatically organized into implicit threads identified by organizationId + threadName
• Each notes component instance displays and manages notes from a single thread
• Threads are auto-created when first accessed - no pre-configuration required
• Rich-text editing with TipTap provides professional document authoring capabilities
• Full-text search, tagging, and mention system enable efficient information retrieval

YAML Structure

component: notes
props:
  threadName: "ParcelShipment/10001/Internal"
  title:
    en-US: "Parcel Shipment Notes"
  height: 400
  placeholder: "Add your notes here..."
  readonly: false
  options:
    allowAttachments: true
    allowReplies: true
    sortOrder: "desc"
    showTimestamps: true
    showAuthor: true
    autoRefresh: false
    refreshInterval: 30
  pagination:
    pageSize: 20
    orderBy: "createdAt"
  permissions:
    create: "Notes/Create"
    view: "Notes/View"
    edit: "Notes/Edit"
    delete: "Notes/Delete"
  events:
    onNoteCreated:
      - notification:
          message: "Note added successfully"
    onNoteUpdated:
      - setVariables:
          lastUpdated: "{{ event.note.updatedAt }}"
    onNoteDeleted:
      - notification:
          message: "Note deleted"

Attribute Description

Core Attributes

• component: (string) Required - Must be set to "notes" to use this component type.
• props: (object) Required - Contains the configuration properties for the notes component.

Props Attributes

Required Properties

• threadName: (string) Required - Thread identifier for grouping related notes. Threads are automatically created when first accessed. Use the entity type and id to create a unique thread name. For example, "ParcelShipment/123456/Internal".

Optional Properties

• title: (object) - Localized title for the notes section.

  • Supports multiple languages (e.g., en-US, es-ES, fr-FR)
  • Default: "Notes" in the user's language

• height: (number) - Height of the component in pixels.

  • Default: 400
  • Minimum: 200

• placeholder: (string) - Placeholder text displayed in empty editor.

  • Default: "Add your notes here..."

• readonly: (boolean) - Enable read-only mode to prevent editing.

  • Default: false
  • When true, disables all editing, creation, and deletion

• options: (object) - Configuration options for component behavior and display.

  • allowAttachments: (boolean) - Enable attaching files to notes
    • Default: true
  • allowReplies: (boolean) - Enable threaded replies under notes
    • Default: true
  • sortOrder: (string) - Sort order for notes
    • Options: "asc", "desc"
    • Default: "desc"
  • showTimestamps: (boolean) - Display created/updated timestamps
    • Default: true
  • showAuthor: (boolean) - Display author/user on each note
    • Default: true
  • autoRefresh: (boolean) - Auto-refresh the notes list
    • Default: false
  • refreshInterval: (number) - Auto-refresh interval in seconds (used when autoRefresh is true)
    • Default: 30

• editor: (object) - TipTap editor configuration and extensions.

  • extensions: (array) - Enabled editor extensions
    • Available: bold, italic, underline, strikethrough, bulletList, orderedList, link, mention, table, image, code, codeBlock, highlight, taskList
  • mentions: (object) - Mention functionality settings
    • enabled: (boolean) - Enable @mentions feature
  • tags: (object) - Tag configuration
    • suggestions: (array) - Pre-defined tag suggestions for quick selection

• pagination: (object) - Pagination settings for note listing.

  • pageSize: (number) - Number of notes to display per page
    • Default: 20
    • Range: 5-100
  • orderBy: (string) - Sort field
    • Options: "createdAt", "updatedAt"
    • Default: "createdAt"
  • orderDirection: (string) - Sort direction
    • Options: "ASC" (oldest first), "DESC" (newest first)
    • Default: "DESC"

• permissions: (object) - Permission control for note operations.

  • create: (string) - Permission required to create notes
  • view: (string) - Permission required to view notes
  • edit: (string) - Permission required to edit notes
  • delete: (string) - Permission required to delete notes

Note: props.readonly: true disables create/edit/delete actions even if permissions are granted.

Events Attributes

• events: (object) - Event handlers for notes interactions using
  • onNoteCreated: (array) - Actions executed when a note is created
  • onNoteUpdated: (array) - Actions executed when a note is updated
  • onNoteDeleted: (array) - Actions executed when a note is deleted
  • onMentionClick: (array) - Actions executed when a mention is clicked
  • onTagClick: (array) - Actions executed when a tag is clicked

Examples

Basic Notes Component

component: notes
props:
  threadName: "Order/{{ orderId }}/Internal"

This creates a basic notes component with default settings for order-related customer communication.

Customer Support Notes with Tags and Mentions

component: notes
props:
  threadName: "Support Case/{{ ticketNumber }}/Internal"
  title:
    en-US: "Support Case Documentation"
  editor:
    extensions:
      - bold
      - italic
      - bulletList
      - orderedList
      - link
      - mention
    mentions:
      enabled: true
    tags:
      suggestions:
        - "urgent"
        - "waiting-customer"
        - "escalated"
        - "resolved"
  events:
    onNoteCreated:
      - notification:
          message: "Support note added"

This component provides rich text editing with mentions for support staff and predefined tags for case categorization.

Shipment Operations Log

component: notes
props:
  threadName: "Shipment/{{ shipmentId }}/OperationsLog"
  title:
    en-US: "Operations Log"
  editor:
    extensions:
      - bold
      - italic
      - bulletList
      - orderedList
      - table
      - image
    tags:
      suggestions:
        - "pickup"
        - "delivery"
        - "customs"
        - "delay"
        - "inspection"
  pagination:
    pageSize: 30
    orderBy: "createdAt"
    orderDirection: "ASC" # Chronological order for logs
  events:
    onNoteCreated:
      - mutation:
          command: "mutation LogShipmentActivity($shipmentId: ID!, $activity: String!) { logShipmentActivity(shipmentId: $shipmentId, activity: $activity) }"
          variables:
            shipmentId: "{{ shipmentId }}"
            activity: "Documentation updated"

This configuration provides structured logging with tables and images, using chronological ordering appropriate for operational logs.

Read-Only Documentation

component: notes
props:
  threadName: "SystemAudit/{{ auditId }}/Internal"
  title:
    en-US: "System Audit Log"
  readonly: true
  options:
    allowAttachments: false
    allowReplies: false
    sortOrder: "desc"
    showTimestamps: true
    showAuthor: true
    autoRefresh: false
  permissions:
    view: "Audit/View"
    # No create, edit, or delete permissions - read only

This creates a read-only notes display for system-generated audit documentation.

Role-Based Access Control

component: notes
props:
  threadName: "QC Report/{{ inspectionId }}/Internal"
  title:
    en-US: "Quality Control Report"
  readonly: "{{ eval user.role !== 'quality_inspector' }}"
  options:
    allowAttachments: "{{ eval user.role === 'quality_inspector' }}"
    allowReplies: "{{ eval user.role === 'quality_inspector' }}"
  editor:
    tags:
      suggestions:
        - "passed"
        - "failed"
        - "retest-required"
  permissions:
    create: "QC/Reports/Create"
    view: "QC/Reports/View"
    edit: "QC/Reports/Edit"

This component adapts its interface based on user roles, providing full editing for quality inspectors and read-only access for others.