@datavysta/vysta-react v1.0.47

@datavysta/vysta-react

React components for Vysta - a backend as a service platform.

Installation

npm install @datavysta/vysta-react @datavysta/vysta-client ag-grid-community ag-grid-react

Basic Usage

First, import the styles:

import '@datavysta/vysta-react/style.css';

Then use the components in your app:

import { DataGrid } from '@datavysta/vysta-react';
import { VystaClient, VystaService } from '@datavysta/vysta-client';
import { useMemo } from 'react';

// Define your entity type
interface Product {
  productId: number;
  productName: string;
  unitPrice: number;
}

// Create your service
class ProductService extends VystaService<Product> {
  constructor(client: VystaClient) {
    super(client, 'Northwinds', 'Products', {
      primaryKey: 'productId'
    });
  }
}

// In your React component
function ProductList() {
  const products = useMemo(() => {
    const client = new VystaClient({ baseUrl: 'http://localhost:8080' });
    return new ProductService(client);
  }, []);

  const columnDefs = [
    { field: 'productId', headerName: 'ID' },
    { field: 'productName', headerName: 'Name' },
    { field: 'unitPrice', headerName: 'Price' }
  ];

  return (
    <DataGrid<Product>
      title="Products"
      noun="Product"
      repository={products}
      columnDefs={columnDefs}
      getRowId={(product) => product.productId.toString()}
    />
  );
}

## VystaServiceProvider (Core Service Context)

`VystaServiceProvider` is a core feature that provides the VystaClient instance and core Vysta services (roles, permissions, user profile, and authentication) to your app via React context.

**Usage Example:**

```tsx
import { VystaServiceProvider, useVystaServices } from '@datavysta/vysta-react';
import { VystaConfig } from '@datavysta/vysta-client';

const config: VystaConfig = {
  baseUrl: '/api',
  debug: true,
};

function App() {
  return (
    <VystaServiceProvider config={config} apps={["Northwinds"]}>
      <YourApp />
    </VystaServiceProvider>
  );
}

// In any child component:
function MyComponent() {
  const {
    roleService,
    permissionService,
    profile,
    permissions,
    canSelectConnection,
    isAuthenticated,
    profileLoading,
    profileError,
    loginLoading,
    loginError,
    auth,
  } = useVystaServices();

  // Example: login
  const handleLogin = async () => {
    await auth.login('user@example.com', 'password');
  };

  // Example: logout
  const handleLogout = async () => {
    await auth.logout();
  };

  // Example: get sign-in methods
  const signInMethods = await auth.getSignInMethods();

  // ...use any of the above context values as needed
}

Note: VystaServiceProvider provides the following via context (using useVystaServices):

• roleService: VystaRoleService instance
• permissionService: VystaPermissionService instance
• profile: The user's profile object (or null if not loaded)
• permissions: A record mapping app/connection names to their permissions (or null if not loaded or not requested)
• canSelectConnection: Helper to check if the user has SELECT permission for a given app
• isAuthenticated: Boolean, true if a user profile is loaded
• profileLoading: Boolean, true while profile/permissions are loading
• profileError: Any error encountered during profile/permissions loading
• loginLoading: Boolean, true while a login/logout is in progress
• loginError: Any error encountered during login/logout
• auth: An object with authentication methods:
  • login(username, password)
  • logout()
  • getSignInMethods()
  • getAuthorizeUrl(providerId)
  • exchangeToken(token)

Always use the context-based approach for authentication, user, and permissions state. Direct use of internal hooks is not supported in the public API.

Authentication and User Profile (Context-based Access)

Authentication, user profile, and permissions are now accessed exclusively via the VystaServiceProvider and the useVystaServices context hook. This ensures a single source of truth for authentication and user state throughout your app.

• profile: The user's profile object (or null if not loaded).
• permissions: A record mapping app/connection names to their permissions (or null if not loaded or not requested).
• canSelectConnection: Helper to check if the user has SELECT permission for a given app.
• profileLoading: Boolean, true while profile/permissions are loading.
• profileError: Any error encountered during profile/permissions loading.
• loginLoading: Boolean, true while a login/logout is in progress.
• loginError: Any error encountered during login/logout.
• isAuthenticated: Boolean, true if a user profile is loaded.
• auth: An object with authentication methods:
  • login(username, password)
  • logout()
  • getSignInMethods()
  • getAuthorizeUrl(providerId)
  • exchangeToken(token)
• roleService: VystaRoleService instance for role management.
• permissionService: VystaPermissionService instance for permission management.

Note: Direct use of internal hooks is not supported in the public API. Always use the context-based approach for authentication and user state.

FilterPanel Component

The FilterPanel component provides a powerful and flexible filtering interface for your data.

Basic Usage

import { FilterPanel } from '@datavysta/vysta-react';
import DataType from '@datavysta/vysta-react/components/Models/DataType';
import { FilterDefinitionsByField } from '@datavysta/vysta-react/components/Filter/FilterDefinitionsByField';

const filterDefinitions: FilterDefinitionsByField = [
    {
        targetFieldName: "productName",
        label: "Product Name",
        dataType: DataType.String
    },
    {
        targetFieldName: "unitPrice",
        label: "Unit Price",
        dataType: DataType.Numeric
    },
    {
        targetFieldName: "unitsInStock",
        label: "Units In Stock",
        dataType: DataType.Numeric
    },
    {
        targetFieldName: "discontinued",
        label: "Discontinued",
        dataType: DataType.Boolean
    }
];

function App() {
    const [conditions, setConditions] = useState<Condition[]>([]);

    return (
        <FilterPanel 
            conditions={conditions}
            onApply={setConditions}
            filterDefinitions={filterDefinitions}
        />
    );
}

FilterPanel Props

Filter Types

The FilterPanel supports these data types from DataType:

• String: Text fields with operations like contains, equals, starts with
• Numeric: Numeric fields with operations like equals, greater than, less than
• Boolean: True/false fields
• Date: Date fields with operations like equals, before, after

Filter Definition Format

Each filter definition should include:

• targetFieldName: The field name to filter on
• label: Display label for the field
• dataType: One of the DataType enum values

Vysta Mantine Integration

Vysta components can optionally use Mantine UI for enhanced styling and interactions. To use Vysta's Mantine integration:

1. Install Mantine dependencies:

npm install @mantine/core @mantine/hooks

2. Import Mantine styles:

import '@mantine/core/styles.css';

3. Wrap your Vysta components with both providers:

import { MantineProvider } from '@mantine/core';
import { VystaMantineComponentProvider } from '@datavysta/vysta-react/mantine';

function App() {
  return (
    <MantineProvider>
      <VystaMantineComponentProvider>
        {/* Your Vysta components here */}
      </VystaMantineComponentProvider>
    </MantineProvider>
  );
}

This will enable Mantine-styled versions of Vysta components while maintaining all their core functionality.

Props Documentation

Required Props

Optional Props

Styling

You can customize the appearance of individual grid elements using the styles prop:

<DataGrid<Product>
  // ... other props ...
  styles={{
    container: { backgroundColor: '#f5f5f5' },
    title: { color: 'blue', fontSize: '1.2rem' },
    badge: { backgroundColor: 'red', color: 'white' },
    createButton: { backgroundColor: 'green' },
    // ... other style overrides
  }}
/>

Available style targets:

• container: The main grid container
• toolbar: The top toolbar section
• titleSection: The title and badge container
• title: The grid title text
• badge: The count badge
• actions: The actions container (buttons)
• createButton: The "New" button
• downloadButton: The download button
• deleteButton: The delete button in rows
• grid: The AG Grid container

Features

• 🔄 Infinite scrolling with server-side operations
• 📊 Sorting and filtering
• ✨ Customizable columns
• 🎨 Modern UI with great UX
• 💪 Fully typed with TypeScript

Grid Customization

The grid uses AG Grid Community Edition under the hood. You can customize the grid behavior using the gridOptions prop:

<DataGrid<Product>
  // ... required props ...
  gridOptions={{
    rowHeight: 48,
    headerHeight: 40,
    rowSelection: 'multiple',
    // ... any other AG Grid options
  }}
/>

Filtering Example

// Example with memoized filters to prevent unnecessary reloads
function ProductList() {
  const [useFilter, setUseFilter] = useState(false);
  
  const filters = useMemo(
    () => useFilter ? { unitPrice: { gt: 20 } } : undefined,
    [useFilter]
  );

  return (
    <DataGrid<Product>
      // ... other props ...
      filters={filters}
    />
  );
}

Input Properties Example

// Example with memoized input properties
function ProductList() {
  const [useInputProps, setUseInputProps] = useState(false);
  
  const inputProperties = useMemo(
    () => useInputProps ? { customParam: 'value' } : undefined,
    [useInputProps]
  );

  return (
    <DataGrid<Product>
      // ... other props ...
      inputProperties={inputProperties}
    />
  );
}

Aggregate Summary Row (Footer)

DataGrid supports showing a summary/footer row with aggregate values (SUM, AVG, etc) using the Vysta aggregate query API. This is useful for totals, averages, and other summary statistics.

Usage Example

import { DataGrid } from '@datavysta/vysta-react';
import { Aggregate, SelectColumn } from '@datavysta/vysta-client';

const aggregateSelect: SelectColumn<Product>[] = [
  { name: 'unitPrice', aggregate: Aggregate.AVG, alias: 'avgUnitPrice' },
  { name: 'unitsInStock', aggregate: Aggregate.SUM, alias: 'totalUnitsInStock' },
];

<DataGrid<Product>
  title="Products"
  noun="Product"
  repository={productService}
  columnDefs={columnDefs}
  getRowId={(product) => product.productId.toString()}
  aggregateSelect={aggregateSelect}
/>

• The summary row appears below the grid and updates with filters, search, etc.
• By default, the row matches columns by field name or alias. You can customize rendering with the renderAggregateFooter prop.
• The summary row is not part of the grid (not a pinned row), so it is always visible below the grid.

Details & Customization

• Column value formatting: The footer automatically applies the column's valueFormatter (if provided in your columnDefs). This lets you format numbers, currency, dates, etc., exactly the same way as in the grid cells.
• Alias required: Every SelectColumn in aggregateSelect must have an alias. The alias is used to look up the aggregate value in the server response.
• Column matching: The footer places the aggregate under the column whose field equals the name in the SelectColumn. The alias can be anything you like.
• Fully custom footer: Provide a renderAggregateFooter prop to supply your own React node. You receive the raw summary object (keyed by alias) and can render any layout, charts, or styled components you need.

Props

See the @datavysta/vysta-client docs for more on Aggregate and SelectColumn.

LazyLoadList Component

The LazyLoadList component provides a searchable, lazy-loading dropdown list that efficiently loads data from a Vysta service.

Basic Usage

import { LazyLoadList } from '@datavysta/vysta-react';

function ProductSelector() {
    const [selectedId, setSelectedId] = useState<string | null>(null);
    const productService = useMemo(() => new ProductService(client), [client]);

    return (
        <LazyLoadList<Product>
            repository={productService}
            value={selectedId}
            onChange={setSelectedId}
            label="Select Product"
            displayColumn="productName"
            clearable
        />
    );
}

LazyLoadList Props

Features

• 🔄 Lazy loading with infinite scroll
• 🔍 Built-in search functionality
• 📑 Optional grouping of items
• 🎯 Efficient loading of selected values
• 🎨 Customizable styles
• 💪 Full TypeScript support

Example with Filtering

function OrderSelector() {
    const [selectedOrderId, setSelectedOrderId] = useState<string | null>(null);
    const [customerId, setCustomerId] = useState<string | null>(null);
    
    return (
        <LazyLoadList<Order>
            repository={orderService}
            value={selectedOrderId}
            onChange={setSelectedOrderId}
            label="Select Order"
            displayColumn="orderId"
            clearable={true}
            filters={customerId ? { customerId: { eq: customerId } } : undefined}
        />
    );
}

FileUpload Component

A file upload component that integrates with Vysta's file service and uses Uppy for the upload interface.

import { FileUpload } from '@datavysta/vysta-react';

function MyComponent() {
    return (
        <FileUpload
            fileService={fileService}
            allowedFileTypes={['.jpg', '.png', 'image/*']}
            filename="custom-name.jpg"
            autoProceed={true}
            onUploadSuccess={(fileId, fileName) => {
                console.log(`File uploaded: ${fileName} with ID: ${fileId}`);
            }}
        />
    );
}

Props

The component provides:

• Drag and drop interface
• File type restrictions
• Upload progress bar
• Automatic or manual upload triggering
• Integration with Vysta's file service

License

MIT