New Case Study:See how Anthropic automated 95% of dependency reviews with Socket.Learn More
Socket
Sign inDemoInstall
Socket

@operato/data-grist

Package Overview
Dependencies
Maintainers
6
Versions
685
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@operato/data-grist

User interface for grid (desktop) and list (mobile)

9.0.0-beta.56
latest
Source
npm
Version published
Weekly downloads
968
-37.02%
Maintainers
6
Weekly downloads
 
Created
Source

Data-Grist

Data-Grist is a powerful web component for displaying and manipulating data. It can present data in Grid, List, or Card formats and provides various features such as data sorting, filtering, editing, and more.

Key Features

  • Multiple Display Modes: Flexibly display the same data in grid, list, or card formats
  • Data Manipulation: Add, modify, and delete records
  • Sorting and Filtering: Single/multi-column sorting, various filtering options
  • Editing Capabilities: Inline cell editing, validation
  • Pagination: Standard paging and infinite scroll support
  • Selection: Single/multiple record selection
  • State Tracking: Track changed (dirty) records
  • Customization: Support for various renderers, editors, and event handlers
  • Mobile Responsive: Responsive design support

Installation

npm install @operato/data-grist

Basic Usage

<script type="module">
  import '@operato/data-grist/ox-grist.js'
</script>

<ox-grist
  .mode=${'GRID'}
  .config=${gridConfig}
  .fetchHandler=${fetchDataFunction}
></ox-grist>

Modes

Data-Grist supports three display modes:

  • GRID: Tabular data display (default)
  • LIST: Mobile-friendly list format display
  • CARD: Card format display
// Set mode
gristElement.mode = 'GRID' // or 'LIST', 'CARD'

Configuration (Config)

Data-Grist provides various configuration options.

const config = {
  columns: [
    {
      type: 'string',
      name: 'name',
      header: 'Name',
      record: {
        editable: true
      },
      sortable: true,
      width: 150
    }
    // More columns...
  ],
  rows: {
    appendable: true, // Allow adding new records
    editable: true, // Allow editing records
    selectable: {
      // Record selection settings
      multiple: true // Allow multiple selections
    }
  },
  pagination: {
    infinite: false, // Use paging instead of infinite scroll
    page: 1, // Starting page
    limit: 20 // Records per page
  }
  // Additional settings...
}

Column Types

// String column
{
  type: 'string',
  name: 'firstName',
  header: 'First Name'
}

// Number column
{
  type: 'number',
  name: 'age',
  header: 'Age',
  record: {
    align: 'right'
  }
}

// Boolean column
{
  type: 'boolean',
  name: 'isActive',
  header: 'Active'
}

// Link column
{
  type: 'link',
  name: 'website',
  header: 'Website',
  record: {
    options: {
      href: (column, record) => record.url,
      target: '_blank'
    }
  }
}

// Gutter column (row number, checkbox, button, etc.)
{
  type: 'gutter',
  gutterName: 'sequence' // 'row-selector', 'button', 'dirty', etc.
}

Fetching Data

Data can be retrieved through the fetchHandler function.

const fetchHandler = async params => {
  const { page, limit, sorters, filters } = params

  // Fetch data from server
  const response = await fetch(`/api/data?page=${page}&limit=${limit}`)
  const data = await response.json()

  return {
    total: data.total,
    records: data.items
  }
}

// Configure the grist
gristElement.fetchHandler = fetchHandler

Record Manipulation API

Adding Records

// Add record at the end (default)
gristElement.addRecord({
  name: 'John Doe',
  age: 30
})

// Add record at the top
gristElement.addRecordToTop({
  name: 'Jane Smith',
  age: 25
})

Record Selection

// Get all selected records
const selectedRecords = gristElement.selected

// Set selection
gristElement.selected = [record1, record2]

// Select records using a selector function
gristElement.select(record => record.age > 30)

Tracking Changed Records

// Get modified records
const dirtyRecords = gristElement.dirtyRecords

// Check for changes
gristElement.checkDirties()

// Export changes as patches
const patches = gristElement.exportPatchList()

Events

Data-Grist triggers various events.

// Record selection change event
gristElement.addEventListener('select-record-change', e => {
  const { records, added, removed } = e.detail
  console.log('Selected records:', records)
})

// Field change event
gristElement.addEventListener('field-change', e => {
  const { after, before, column, record, row } = e.detail
  console.log('Changed field:', column.name, 'from', before, 'to', after)
})

// Record change event
gristElement.addEventListener('record-change', e => {
  const { before, after, column, row } = e.detail
  console.log('Record changed:', row)
})

Advanced Features

Column Accumulation Feature (Accumulator)

{
  type: 'number',
  name: 'amount',
  header: 'Amount',
  accumulator: 'sum' // 'avg', 'count', 'min', 'max' or custom function
}

Tree Structure Data

const config = {
  // ...
  tree: {
    childrenProperty: 'children', // Property name where child nodes are stored
    expanded: true // Initial tree expansion state
  }
}

Grouped Headers

const config = {
  columns: [
    // ...
    {
      type: 'string',
      name: 'firstName',
      header: 'First Name',
      group: 'personalInfo'
    },
    {
      type: 'string',
      name: 'lastName',
      header: 'Last Name',
      group: 'personalInfo'
    }
  ],
  // ...
  rows: {
    // ...
    groups: [
      {
        name: 'personalInfo',
        title: 'Personal Information'
      }
    ]
  }
}

User Settings Storage

// Configure user settings provider
gristElement.personalConfigProvider = {
  async load() {
    // Load saved settings
    return JSON.parse(localStorage.getItem('userGristConfig'))
  },
  async save(preference) {
    // Save user settings
    localStorage.setItem('userGristConfig', JSON.stringify(preference))
  }
}

Styling

Data-Grist can be styled through CSS variables.

ox-grist {
  --grid-header-background-color: #f5f5f5;
  --grid-record-background-color: white;
  --grid-record-odd-background-color: #f9f9f9;
  --grid-header-color: #333;
  --grid-record-hover-background-color: #e9e9e9;
}

API Reference

Properties

PropertyTypeDescription
modestringDisplay mode ('GRID', 'LIST', 'CARD')
configobjectGrist configuration object
dataobjectData to display
selectedRecordsarrayArray of selected records
explicitFetchbooleanEnable explicit data fetching
fetchHandlerfunctionData fetching function
fetchOptionsobjectData fetching options
filtersarrayArray of filters
sortersarrayArray of sorters
paginationobjectPagination settings

Methods

MethodDescription
fetch(reset)Fetch data
addRecord(record)Add a record
addRecordToTop(record)Add a record at the top
deleteSelectedRecords(dirty)Delete selected records
cloneSelectedRecords()Clone selected records
checkDirties()Check for modified records
undo()Undo last action
redo()Redo undone action
reset()Reset data
commit()Commit changes
select(selector, reset)Select records using a function
exportPatchList(options)Export list of change patches
exportRecords(options)Export record data

Examples

Basic Grid

<ox-grist
  .mode=${'GRID'}
  .config=${gridConfig}
  .fetchHandler=${fetchData}
  @record-change=${handleRecordChange}
></ox-grist>

Editable Grid

<ox-grist
  .mode=${'GRID'}
  .config=${{
    columns: [/* column definitions */],
    rows: {
      appendable: true,
      editable: true,
      selectable: { multiple: true }
    }
  }}
  .data=${{ records: initialData }}
></ox-grist>

Add Row to Top Button

<button @click="${() => gristRef.addRecordToTop()}">Add Row to Top</button>
<ox-grist id="my-grist"></ox-grist>

<script>
  const gristRef = document.getElementById('my-grist')
</script>

License

MIT

FAQs

Package last updated on 30 Mar 2025

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts