ui/packages/ui-data

@lilith/ui-data

Data display components for React applications. Includes tables, pagination, galleries, sparklines, and stat cards with theme-aware styling.

Features

• DataTable - Full-featured data table with sorting, custom renderers, and loading states
• StickyDataTable - Table with sticky headers and column groups
• Pagination - Page navigation component
• ImageGallery - Grid gallery with lightbox support
• Sparkline - Inline mini charts for trends
• StatCard - Statistical display cards

Installation

npm install @lilith/ui-data
# or
pnpm add @lilith/ui-data

Peer Dependencies

npm install react react-dom styled-components

Usage

DataTable

Full-featured data table with sorting and custom renderers.

import { DataTable } from '@lilith/ui-data';
import type { Column } from '@lilith/ui-data';

interface User {
  id: string;
  name: string;
  email: string;
  status: 'active' | 'inactive';
}

const columns: Column<User>[] = [
  { key: 'name', header: 'Name', sortable: true },
  { key: 'email', header: 'Email', sortable: true },
  {
    key: 'status',
    header: 'Status',
    render: (user) => (
      <StatusBadge variant={user.status === 'active' ? 'success' : 'neutral'}>
        {user.status}
      </StatusBadge>
    ),
  },
];

const users: User[] = [
  { id: '1', name: 'Alice', email: 'alice@example.com', status: 'active' },
  { id: '2', name: 'Bob', email: 'bob@example.com', status: 'inactive' },
];

<DataTable
  columns={columns}
  data={users}
  keyExtractor={(user) => user.id}
  onSort={(key) => handleSort(key)}
  sortKey={sortKey}
  sortDirection={sortDirection}
  onRowClick={(user) => navigateToUser(user.id)}
  emptyMessage="No users found"
  isLoading={false}
/>

StickyDataTable

Table with sticky headers and column groups.

import { StickyDataTable } from '@lilith/ui-data';
import type { StickyColumn, ColumnGroup } from '@lilith/ui-data';

const columnGroups: ColumnGroup[] = [
  { id: 'info', label: 'User Info', columns: ['name', 'email'] },
  { id: 'metrics', label: 'Metrics', columns: ['visits', 'conversions'] },
];

const columns: StickyColumn<User>[] = [
  { key: 'name', header: 'Name', sticky: 'left', width: '200px' },
  { key: 'email', header: 'Email' },
  { key: 'visits', header: 'Visits', align: 'right' },
  { key: 'conversions', header: 'Conversions', align: 'right' },
];

<StickyDataTable
  columns={columns}
  columnGroups={columnGroups}
  data={users}
  keyExtractor={(user) => user.id}
  stickyHeader={true}
  maxHeight="500px"
/>

Pagination

Page navigation with customizable display.

import { Pagination } from '@lilith/ui-data';

<Pagination
  currentPage={currentPage}
  totalPages={totalPages}
  onPageChange={setCurrentPage}
  showFirstLast={true}
  siblingCount={1}
/>

// With page size selector
<Pagination
  currentPage={currentPage}
  totalPages={totalPages}
  onPageChange={setCurrentPage}
  pageSize={pageSize}
  pageSizeOptions={[10, 25, 50, 100]}
  onPageSizeChange={setPageSize}
  totalItems={250}
/>

ImageGallery

Grid gallery with lightbox.

import { ImageGallery } from '@lilith/ui-data';
import type { ImageGalleryItem } from '@lilith/ui-data';

const images: ImageGalleryItem[] = [
  { id: '1', src: '/image1.jpg', alt: 'Image 1', thumbnail: '/thumb1.jpg' },
  { id: '2', src: '/image2.jpg', alt: 'Image 2', thumbnail: '/thumb2.jpg' },
  { id: '3', src: '/image3.jpg', alt: 'Image 3', thumbnail: '/thumb3.jpg' },
];

<ImageGallery
  images={images}
  columns={3}
  gap={16}
  aspectRatio="1:1"
  enableLightbox={true}
  onImageClick={(image) => console.log('Clicked:', image)}
/>

Sparkline

Inline mini charts for showing trends.

import { Sparkline } from '@lilith/ui-data';

<Sparkline
  data={[10, 25, 15, 40, 35, 50, 45]}
  width={100}
  height={24}
  color="#10b981"
  filled={true}
/>

// In a table cell
<DataTable
  columns={[
    { key: 'name', header: 'Name' },
    {
      key: 'trend',
      header: 'Trend',
      render: (row) => <Sparkline data={row.trendData} />,
    },
  ]}
  // ...
/>

StatCard

Statistical display with optional comparison.

import { StatCard } from '@lilith/ui-data';

<StatCard
  title="Total Revenue"
  value="$125,430"
  change={12.5}
  changeLabel="vs last month"
  icon={<DollarSign />}
  variant="success"
/>

<StatCard
  title="Active Users"
  value={1234}
  change={-5.2}
  changeLabel="vs last week"
  variant="warning"
/>

API Reference

DataTable

Prop	Type	Default	Description
columns	Column<T>[]	required	Column definitions
data	T[]	required	Array of data rows
keyExtractor	(row: T) => string	required	Function to get unique key
onSort	(key: string) => void	-	Sort handler
sortKey	string	-	Current sort column
sortDirection	'asc' | 'desc'	-	Sort direction
onRowClick	(row: T) => void	-	Row click handler
emptyMessage	string	'No data available'	Empty state message
isLoading	boolean	false	Loading state

Column

Prop	Type	Description
key	string	Column identifier
header	string	Column header text
render	(row: T) => ReactNode	Custom cell renderer
sortable	boolean	Enable sorting
width	string	Column width

Pagination

Prop	Type	Default	Description
currentPage	number	required	Current page (1-indexed)
totalPages	number	required	Total number of pages
onPageChange	(page: number) => void	required	Page change handler
showFirstLast	boolean	true	Show first/last buttons
siblingCount	number	1	Pages shown on each side
pageSize	number	-	Current page size
pageSizeOptions	number[]	-	Page size options
onPageSizeChange	(size: number) => void	-	Page size handler
totalItems	number	-	Total item count for display

ImageGallery

Prop	Type	Default	Description
images	ImageGalleryItem[]	required	Array of images
columns	number	3	Number of grid columns
gap	number	16	Gap between images in pixels
aspectRatio	string	'1:1'	Image aspect ratio
enableLightbox	boolean	true	Enable fullscreen lightbox
onImageClick	(image: ImageGalleryItem) => void	-	Image click handler

Sparkline

Prop	Type	Default	Description
data	number[]	required	Data points
width	number	100	Chart width
height	number	24	Chart height
color	string	theme primary	Line color
filled	boolean	false	Fill area under line

Types

interface Column<T> {
  key: string;
  header: string;
  render?: (row: T) => ReactNode;
  sortable?: boolean;
  width?: string;
}

interface StickyColumn<T> extends Column<T> {
  sticky?: 'left' | 'right';
  align?: 'left' | 'center' | 'right';
}

interface ColumnGroup {
  id: string;
  label: string;
  columns: string[];
}

interface ImageGalleryItem {
  id: string;
  src: string;
  alt: string;
  thumbnail?: string;
}

Dependencies

• @lilith/ui-primitives - Base components
• @lilith/ui-utils - Utility functions
• @lilith/ui-theme - Theme tokens
• @lilith/ui-accessibility - Accessibility utilities
• @lilith/ui-motion - Animation utilities
• framer-motion - Animation library
• lucide-react - Icons

License

MIT