easy-cloudscape-table

A React table component library built on AWS Cloudscape Design System, providing ready-to-use table components with advanced features like filtering, pagination, and collection preferences.

Features

✅ Built on AWS Cloudscape: Leverages the robust Cloudscape Design System
✅ TypeScript Support: Full type safety and IntelliSense support
✅ Row Actions: Support for clickable row actions in table columns
✅ Internationalization: Built-in Italian and English language support
✅ Collection Preferences: User customizable table preferences
✅ Local Storage: Persistent user preferences and table state
✅ Filter Utilities: Advanced filtering and search capabilities
✅ Empty States: Beautiful empty and no-match state components
✅ Responsive Design: Mobile-friendly and responsive by default

Installation

npm install easy-cloudscape-table

Peer Dependencies

Make sure you have the required peer dependencies installed:

npm install react react-dom @cloudscape-design/components @cloudscape-design/collection-hooks

Quick Start

import React from "react";
import { TableElement } from "easy-cloudscape-table";

function MyTable() {
  return (
    <div>
      <TableElement.FullPageHeader
        title="My Table"
        description="A simple table example"
      />

      <TableElement.TableEmptyState resourceName="items" />

      <TableElement.CustomCollectionPreferences
        title="Preferences"
        confirmLabel="Apply"
        cancelLabel="Cancel"
        preferences={preferences}
        onConfirm={handlePreferencesChange}
        t={(key) => key} // Simple translation function
      />
    </div>
  );
}

Components

Core Components

TableElement.FullPageHeader

A full-page header component for tables with title, description, and action support.

<TableElement.FullPageHeader
  title="Users Table"
  description="Manage your users"
  actions={<Button>Add User</Button>}
/>

TableElement.TableHeader

A simple table header component.

<TableElement.TableHeader
  title="Table Title"
  counter="(25)"
  description="Table description"
  actions={<Button>Action</Button>}
/>

TableElement.CustomCollectionPreferences

Customizable collection preferences for tables.

<TableElement.CustomCollectionPreferences
  title="Table Preferences"
  confirmLabel="Apply"
  cancelLabel="Cancel"
  preferences={preferences}
  onConfirm={handlePreferencesChange}
  t={translationFunction}
/>

Empty State Components

TableElement.TableEmptyState

Shows when the table has no data.

<TableElement.TableEmptyState resourceName="users" />

TableElement.TableNoMatchState

Shows when filters return no results.

<TableElement.TableNoMatchState onClearFilter={clearFilters} />

Utility Components

TableElement.ArrayDisplayCell

Displays arrays in table cells with proper formatting.

<TableElement.ArrayDisplayCell
  array={["item1", "item2", "item3"]}
  maxItems={2}
/>

Hooks and Utilities

Local Storage Hook

const [value, setValue] = TableElement.useLocalStorage("myKey", defaultValue);

Storage Functions

// Save data
TableElement.save("key", data);

// Load data
const data = TableElement.load("key");

Row Action Utilities

// Handle row actions in your table implementation
const handleRowAction = (action: string, item: any) => {
  switch (action) {
    case 'view':
      // Handle view action
      break;
    case 'edit':
      // Handle edit action
      break;
    case 'delete':
      // Handle delete action
      break;
  }
};

// Use helper functions for row actions
const { handleRowAction as handleAction, createActionCell } = TableElement;

// Example column definition with action
const columns = [
  {
    id: "name",
    header: "Name",
    cell: (item) => item.name,
    action: "view", // This column will trigger 'view' action when clicked
    sortingField: "name",
    minWidth: 150
  }
];

// In your table component
<Table
  columnDefinitions={columns}
  items={items}
  onRowClick={(item) => handleAction(columnDef, item.detail, handleRowAction)}
/>

Filter Utilities

// Create default filter
const filter = TableElement.createTableDefaultFilter();

// Set table filter
TableElement.setTableFilter(filter, "columnId", "value");

// Parse search parameters
const params = TableElement.parseSearchParams(searchString);

Text Filter Functions

// Get filter counter text
const text = TableElement.getFilterCounterText(5); // "5 trovati"

// Get text filter counter
const text = TableElement.getTextFilterCounterText(3); // "3 matches"

// Server-side text counter
const text = TableElement.getTextFilterCounterServerSideText(items, 2, 10);

Header Counter Functions

// Get header counter text
const text = TableElement.getHeaderCounterText(allItems, selectedItems);

// Server-side header counter
const text = TableElement.getHeaderCounterServerSideText(100, 5);

Configuration

Language Support

The library supports Italian and English out of the box. You can customize the language by providing translation functions:

const translations = {
  "admin.preferences.title": "Table Preferences",
  "admin.preferences.confirmLabel": "Apply",
  "admin.preferences.cancelLabel": "Cancel",
  // ... other translations
};

const t = (key: string) => translations[key] || key;

<TableElement.CustomCollectionPreferences t={t} />;

Constants

The library provides several useful constants:

// Default table configuration
const defaultTable = TableElement.DEFAULT_TABLE;

// Page size options
const pageSizeOptions = TableElement.PAGE_SIZE_OPTIONS;

// Property filtering constants
const filteringConstants = TableElement.propertyFilterI18nStrings;

Types

The library exports all necessary TypeScript types:

import {
  TableProps,
  ColumnDefinition,
  TableEmptyStateProps,
  TableNoMatchStateProps,
  DefaultAdminTableType,
  // ... other types
} from "easy-cloudscape-table";

Examples

Basic Table with Preferences

import React, { useState } from "react";
import { TableElement } from "easy-cloudscape-table";

function BasicTable() {
  const [preferences, setPreferences] = useState({
    pageSize: 10,
    visibleContent: ["name", "email"],
    wrapLines: false,
    stripedRows: false,
    contentDensity: "comfortable",
  });

  return (
    <div>
      <TableElement.FullPageHeader
        title="Users"
        description="Manage system users"
      />

      <TableElement.CustomCollectionPreferences
        title="Table Preferences"
        confirmLabel="Apply"
        cancelLabel="Cancel"
        preferences={preferences}
        onConfirm={setPreferences}
        t={(key) => key}
      />
    </div>
  );
}

Table with Local Storage

function PersistentTable() {
  const [tableData, setTableData] = TableElement.useLocalStorage(
    "tableData",
    []
  );
  const [filters, setFilters] = TableElement.useLocalStorage(
    "tableFilters",
    {}
  );

  // Your table logic here

  return <div>{/* Your table components */}</div>;
}

Complete Table Example with Row Actions

import React, { useState } from "react";
import { Table } from "@cloudscape-design/components";
import { TableElement } from "easy-cloudscape-table";

function CompleteTableExample() {
  const [items] = useState([
    { id: 1, name: "John Doe", email: "[email protected]" },
    { id: 2, name: "Jane Smith", email: "[email protected]" },
  ]);

  const handleRowAction = (action: string, item: any) => {
    switch (action) {
      case 'viewDetails':
        console.log('Viewing details for:', item);
        // Navigate to details page or open modal
        break;
      case 'editUser':
        console.log('Editing user:', item);
        // Open edit form
        break;
      default:
        console.log('Unknown action:', action);
    }
  };

  const columns = [
    {
      id: "name",
      header: "Name",
      cell: (item) => item.name,
      action: "viewDetails", // Clicking name will trigger viewDetails action
      sortingField: "name",
      minWidth: 150
    },
    {
      id: "email",
      header: "Email",
      cell: (item) => item.email,
      action: "editUser", // Clicking email will trigger editUser action
      sortingField: "email",
      minWidth: 200
    }
  ];

  return (
    <div>
      <TableElement.FullPageHeader
        title="Users"
        description="Manage system users"
      />
      
      <Table
        columnDefinitions={columns}
        items={items}
        onRowClick={(detail) => {
          const columnDef = columns.find(col => col.action);
          if (columnDef) {
            TableElement.handleRowAction(columnDef, detail.item, handleRowAction);
          }
        }}
        empty={<TableElement.TableEmptyState resourceName="users" />}
        filter={<TableElement.TableNoMatchState onClearFilter={() => {}} />}
      />
    </div>
  );
}

Development

Building the Library

npm run build

Development Mode

npm run dev

Linting

npm run lint

Testing

npm run test

Storybook

npm run storybook

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Run linting and tests
6. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions, please open an issue on the GitHub repository.