# @ticatec/uniface-pro-components

[![NPM Version](https://img.shields.io/npm/v/@ticatec/uniface-pro-components.svg)](https://www.npmjs.com/package/@ticatec/uniface-pro-components)
[![License](https://img.shields.io/npm/l/@ticatec/uniface-pro-components.svg)](LICENSE)

**[🇨🇳 中文文档](./README-CN.md)** | **[📖 Documentation](./docs/en/)**

A focused Svelte component library providing essential data display components for building data-driven web applications. Built on top of Svelte 5 and the Ticatec Uniface ecosystem, it offers specialized components for card-based and table-based data presentations.

This library is the perfect tool for building:
- Data-intensive admin panels
- Complex data grids and lists
- Card-based data views
- Paginated data displays

## ✨ Key Features

- **📊 Specialized Data Views**: Professional components for displaying data, including `DataTable` and `CardList`, with comprehensive support for:
    - Pagination (client-side and server-side)
    - "Managed" mode with automatic data fetching and state management
    - Dynamic filtering and searching
- **🔧 Two Component Modes**: Both "managed" (automatic data handling) and "unmanaged" (manual control) versions available
- **🌐 Internationalization (i18n)**: Core components come with built-in support for multiple languages
- **🎨 Ticatec Ecosystem**: Seamlessly integrates with `@ticatec/uniface-element` and other Ticatec data management libraries

## 🧭 Available Components

Every component below is importable via a dedicated subpath (see the `exports` field in [`package.json`](./package.json) for the authoritative list).

| Subpath | Component | Description |
| --- | --- | --- |
| `data-table/DataTableBoard` | `DataTableBoard` | Low-level, non-paginated data table board (wraps `@ticatec/uniface-element/DataTable`). |
| `data-table/SimpleDataTableBoard` | `SimpleDataTableBoard` | Minimal table board without filtering/action-bar chrome. |
| `data-table/PagingDataTableBoard` | `PagingDataTableBoard` | Low-level paginated table board. |
| `data-table/ManagedSimpleDataTableBoard` | `ManagedSimpleDataTableBoard` | Managed full-dataset table board without the `CommonPage` shell — embeddable in any layout. |
| `data-table/ManagedPagingDataTableBoard` | `ManagedPagingDataTableBoard` | Managed paging table board without the `CommonPage` shell — embeddable in any layout. |
| `data-table/TablePage` | `TablePage` | Unmanaged full-page table: title/filter bar + table, you own the array. |
| `data-table/PagingTablePage` | `PagingTablePage` | Unmanaged full-page paginated table: you own a `PagedDataManager` and pass its state as props. |
| `data-table/managed/TablePage` | `TablePage` (managed) | Fetches a full dataset via a `FullListDataManager` and manages loading/error state automatically. |
| `data-table/managed/PagingTablePage` | `PagingTablePage` (managed) | Fetches paginated data via a `PagedDataManager`, fully automated. |
| `card/CardListBoard` | `CardListBoard` | Low-level card renderer driven by a `render` config object. |
| `card/CardPage` | `CardPage` | Unmanaged full-page card list, client-side array + optional filter function. |
| `card/PagingCardPage` | `PagingCardPage` | Unmanaged full-page paginated card list, you own a `PagedDataManager`. |
| `card/managed/CardPage` | `CardPage` (managed) | Fetches a full dataset and renders it as cards, automatically managed. |
| `card/managed/PagingCardPage` | `PagingCardPage` (managed) | Fetches paginated data and renders it as cards, fully automated. |
| `common` | `unifaceProCtx` / `ListDataManager` | Application context helper and the `ListDataManager` interface used by managed components. |

Each "unmanaged" component only accepts raw data/props and callbacks; each "managed" component instead accepts a data manager instance (`FullListDataManager` / `PagedDataManager` from `@ticatec/app-data-manager`) and handles fetching, loading state, and pagination internally.

## 📦 Installation

Install the package and its peer dependencies using your favorite package manager:

```bash
npm install @ticatec/uniface-pro-components @ticatec/uniface-element @ticatec/uniface-micro-frame svelte
```

> 0.5.0 requires `@ticatec/uniface-element >= 5.1.0`, `@ticatec/uniface-micro-frame >= 5.1.0` and `@ticatec/uniface-filter-panel >= 0.3.0` (the 5.1 API names: `emptyText`, `rowCountText`, `actions`, `beforeClose`, …); it does not work with 5.0.x.

You also need to include the component's stylesheet in your main application file.

```ts
// src/main.ts
import "@ticatec/uniface-pro-components/uniface-pro-components.css";
```

## 🌐 I18N Resources

The components rely on the following i18n resource keys; add translations as needed:

```json
{
  "uniface": {
    "app": {
      "btnAddNew": "New",
      "btnRefresh": "Refresh",
      "emptyFiltered": "There is no data that meets the filter criteria. Please set the filter criteria again.",
      "emptyDataSet": "There is no data that meets the search criteria. Please set the search criteria again.",
      "busyIndicator": "Loading...",
      "moduleError": "Can't load the module.",
      "paginationInfo": "<span>Total: <b>{{total}}</b> record(s).</span>",
      "rowCountLabel": "records per page",
      "datasetSummaryInfo": "<span>{{eligible}} / {{total}} record(s).</span>"
    }
  }
}
```

If a key is missing from the loaded resources, the component falls back to these English defaults, so you only need to ship the keys you want to override.

## 🚀 Quick Start

Here's how to create a managed, paginated data table that fetches data from a remote API using DataManager.

1.  **Define your data service, manager and columns:**

    ```ts
    // src/routes/demo/paged-table/TenantService.ts
    import { PagingDataService } from '@ticatec/app-data-service';

    export default class TenantService extends PagingDataService {
        constructor() {
            super('/api/tenants');
        }
    }

    export const service = new TenantService();
    ```

    ```ts
    // src/routes/demo/paged-table/TenantManager.ts
    import { PagedDataManager } from "@ticatec/app-data-manager";
    import { service } from "./TenantService";

    export default class TenantManager extends PagedDataManager {
        constructor() {
            super(service, 'id'); // Use 'id' as the unique identifier field
        }
    }
    ```

    ```ts
    // src/routes/demo/paged-table/TenantColumns.ts
    import type { DataColumn } from "@ticatec/uniface-element";

    const columns: Array<DataColumn> = [
        {
            title: 'Tenant Name',
            field: 'name',
            width: 200,
            resizable: true
        },
        {
            title: 'Contact Email',
            field: 'email',
            width: 250,
            resizable: true
        },
        {
            title: 'Status',
            field: 'status',
            width: 120,
            align: 'center'
        }
    ];

    export default columns;
    ```

2.  **Configure the global REST service (in your app setup):**

    ```ts
    // src/app.ts or src/main.ts
    import { BaseDataService } from '@ticatec/app-data-service';
    import RestService from '@ticatec/axios-restful-service';

    // Configure global REST service
    BaseDataService.setProxy(new RestService('https://api.example.com'));
    ```

3.  **Use the `PagingTablePage` component in your Svelte page:**

    ```svelte
    <!-- src/routes/demo/paged-table/+page.svelte -->
    <script lang="ts">
        import PagingTablePage from '@ticatec/uniface-pro-components/data-table/managed/PagingTablePage';
        import TenantManager from './TenantManager';
        import columns from './TenantColumns';

        const dataManager = new TenantManager();

        let page$attrs = {
            title: "Managed Tenants"
        };

        const indicatorColumn = { width: 50, selectable: true };
        const actions = [];
    </script>

    <PagingTablePage
        {dataManager}
        {columns}
        {indicatorColumn}
        {page$attrs}
        {actions}
        rowHeight={48}
    />
    ```

This example creates a fully functional data table using @ticatec/uniface-element/DataTable with pagination, data fetching, loading indicators, and error handling—all managed automatically by the PagedDataManager.

## 🛠️ Development

This is a SvelteKit library project. To start developing, clone the repository and run the following commands:

```bash
# Install dependencies
npm install

# Start the development server with live-reloading
npm run dev

# Build the library for publishing
npm run build

# Run type checking
npm run check
```

## 📚 Documentation

### 🌐 Language Options
- **[📖 English Documentation](./docs/en/)** - Complete English documentation
- **[🇨🇳 中文文档](./docs/cn/)** - 完整中文文档

### 🧩 Core Components

**Common Utilities**
- **[unifaceProCtx](./src/lib/common/unifaceProCtx.ts)** - Application context management
- **[ListDataManager](./src/lib/common/ListDataManager.ts)** - Data management utilities

### 📊 Data Display Components

#### 📊 Data Table
- **[TablePage](./docs/en/data-table-TablePage.md)** - Basic data table page
- **[PagingTablePage](./docs/en/data-table-PagingTablePage.md)** - Paginated data table page
- **[Managed TablePage](./docs/en/data-table-managed-TablePage.md)** - Managed data table page (auto data fetch)
- **[Managed PagingTablePage](./docs/en/data-table-managed-PagingTablePage.md)** - Managed paginated data table page

#### 🃏 Card List
- **[CardPage](./docs/en/card-CardPage.md)** - Basic card list page
- **[PagingCardPage](./docs/en/card-PagingCardPage.md)** - Paginated card list page
- **[Managed CardPage](./docs/en/card-managed-CardPage.md)** - Managed card list page
- **[Managed PagingCardPage](./docs/en/card-managed-PagingCardPage.md)** - Managed paginated card list page


## 📄 License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.