@alaarab/ogrid-core 1.0.0

package/README.md

@@ -0,0 +1,37 @@
+# @alaarab/ogrid-core
+
+Framework-agnostic types, hooks, and utilities for [OGrid](https://github.com/alaarab/ogrid) data tables.
+
+This package is the shared foundation used by `@alaarab/ogrid-fluent` and `@alaarab/ogrid-material`. You typically don't need to install it directly -- both framework packages re-export everything from core.
+
+## Install
+
+```bash
+npm install @alaarab/ogrid-core
+```
+
+## What's Included
+
+### Types
+
+- `IColumnDef<T>` -- Column definition with sorting, filtering, and rendering
+- `IDataSource<T>` -- Server-side data source interface
+- `IFetchParams` -- Parameters for `fetchPage()`
+- `IFilters` -- Unified filter values (text, multi-select, people)
+- `UserLike` -- Minimal user shape for people picker
+- `IColumnFilterDef`, `IColumnMeta`, `IPageResult`, `ColumnFilterType`
+
+### Hooks
+
+- `useFilterOptions(dataSource, fields)` -- Loads filter options for multi-select columns
+
+### Utilities
+
+- `toDataGridFilterProps(filters)` -- Splits `IFilters` into `multiSelectFilters`, `textFilters`, `peopleFilters`
+- `toUserLike(user)` -- Converts a user-like object to `UserLike`
+- `exportToCsv(items, columns, getValue, filename)` -- Full CSV export
+- `buildCsvHeader`, `buildCsvRows`, `triggerCsvDownload`, `escapeCsvValue` -- Low-level CSV helpers
+
+## License
+
+MIT

package/dist/esm/hooks/index.js

@@ -0,0 +1 @@
+export { useFilterOptions } from './useFilterOptions';

package/dist/esm/hooks/useFilterOptions.js

@@ -0,0 +1,40 @@
+import { useState, useEffect, useCallback } from 'react';
+/**
+ * Load filter options for the given fields from a data source.
+ *
+ * Accepts `IDataSource<T>` or a plain `{ fetchFilterOptions }` object.
+ */
+export function useFilterOptions(dataSource, fields) {
+    const [filterOptions, setFilterOptions] = useState({});
+    const [loadingOptions, setLoadingOptions] = useState({});
+    const load = useCallback(async () => {
+        const fetcher = 'fetchFilterOptions' in dataSource && typeof dataSource.fetchFilterOptions === 'function'
+            ? dataSource.fetchFilterOptions.bind(dataSource)
+            : undefined;
+        if (!fetcher) {
+            setFilterOptions({});
+            setLoadingOptions({});
+            return;
+        }
+        const loading = {};
+        fields.forEach((f) => { loading[f] = true; });
+        setLoadingOptions(loading);
+        const results = {};
+        await Promise.all(fields.map(async (field) => {
+            try {
+                results[field] = await fetcher(field);
+            }
+            catch (e) {
+                console.error(`Error loading filter options for ${field}:`, e);
+                results[field] = [];
+            }
+        }));
+        setFilterOptions(results);
+        setLoadingOptions({});
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [dataSource, fields.slice().sort().join(',')]);
+    useEffect(() => {
+        load().catch(console.error);
+    }, [load]);
+    return { filterOptions, loadingOptions };
+}

package/dist/esm/index.js

@@ -0,0 +1,5 @@
+export { toUserLike, toDataGridFilterProps } from './types';
+// Hooks
+export { useFilterOptions } from './hooks';
+// Utilities
+export { escapeCsvValue, buildCsvHeader, buildCsvRows, exportToCsv, triggerCsvDownload, } from './utils';

package/dist/esm/types/columnTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/types/dataGridTypes.js

@@ -0,0 +1,27 @@
+export function toUserLike(u) {
+    if (!u)
+        return undefined;
+    return {
+        id: u.id,
+        displayName: u.displayName,
+        email: 'email' in u && u.email ? u.email : (u.mail || u.userPrincipalName || ''),
+        photo: u.photo
+    };
+}
+/** Split IFilters into DataGridTable's multiSelect, text, and people props. */
+export function toDataGridFilterProps(filters) {
+    const multiSelectFilters = {};
+    const textFilters = {};
+    const peopleFilters = {};
+    for (const [key, value] of Object.entries(filters)) {
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value))
+            multiSelectFilters[key] = value;
+        else if (typeof value === 'string')
+            textFilters[key] = value;
+        else if (typeof value === 'object' && value !== null && 'email' in value)
+            peopleFilters[key] = value;
+    }
+    return { multiSelectFilters, textFilters, peopleFilters };
+}

package/dist/esm/types/index.js

@@ -0,0 +1 @@
+export { toUserLike, toDataGridFilterProps } from './dataGridTypes';

package/dist/esm/utils/exportToCsv.js

@@ -0,0 +1,34 @@
+export function escapeCsvValue(value) {
+    if (value === null || value === undefined) {
+        return '';
+    }
+    const s = String(value);
+    if (s.includes(',') || s.includes('"') || s.includes('\n')) {
+        return `"${s.replace(/"/g, '""')}"`;
+    }
+    return s;
+}
+export function buildCsvHeader(columns) {
+    return columns.map((c) => escapeCsvValue(c.name)).join(',');
+}
+export function buildCsvRows(items, columns, getValue) {
+    return items.map((item) => columns.map((c) => escapeCsvValue(getValue(item, c.columnId))).join(','));
+}
+export function exportToCsv(items, columns, getValue, filename) {
+    const header = buildCsvHeader(columns);
+    const rows = buildCsvRows(items, columns, getValue);
+    const csv = [header, ...rows].join('\n');
+    triggerCsvDownload(csv, filename ?? `export_${new Date().toISOString().slice(0, 10)}.csv`);
+}
+export function triggerCsvDownload(csvContent, filename) {
+    const blob = new Blob([csvContent], { type: 'text/csv;charset=utf-8;' });
+    const link = document.createElement('a');
+    const url = URL.createObjectURL(blob);
+    link.setAttribute('href', url);
+    link.setAttribute('download', filename);
+    link.style.visibility = 'hidden';
+    document.body.appendChild(link);
+    link.click();
+    document.body.removeChild(link);
+    URL.revokeObjectURL(url);
+}

package/dist/esm/utils/index.js

@@ -0,0 +1 @@
+export { escapeCsvValue, buildCsvHeader, buildCsvRows, exportToCsv, triggerCsvDownload, } from './exportToCsv';

package/dist/types/hooks/index.d.ts

@@ -0,0 +1,2 @@
+export { useFilterOptions } from './useFilterOptions';
+export type { UseFilterOptionsResult } from './useFilterOptions';

package/dist/types/hooks/useFilterOptions.d.ts

@@ -0,0 +1,16 @@
+import type { IDataSource } from '../types/dataGridTypes';
+export interface UseFilterOptionsResult {
+    filterOptions: Record<string, string[]>;
+    loadingOptions: Record<string, boolean>;
+}
+/** Accepted data source shapes for useFilterOptions. */
+type FilterOptionsSource = IDataSource<unknown> | {
+    fetchFilterOptions?: (field: string) => Promise<string[]>;
+};
+/**
+ * Load filter options for the given fields from a data source.
+ *
+ * Accepts `IDataSource<T>` or a plain `{ fetchFilterOptions }` object.
+ */
+export declare function useFilterOptions(dataSource: FilterOptionsSource, fields: string[]): UseFilterOptionsResult;
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,6 @@
+export type { ColumnFilterType, IColumnFilterDef, IColumnMeta, IColumnDef, IColumnDefinition, UserLike, IFilters, IFetchParams, IPageResult, IDataSource, } from './types';
+export { toUserLike, toDataGridFilterProps } from './types';
+export { useFilterOptions } from './hooks';
+export type { UseFilterOptionsResult } from './hooks';
+export { escapeCsvValue, buildCsvHeader, buildCsvRows, exportToCsv, triggerCsvDownload, } from './utils';
+export type { CsvColumn } from './utils';

package/dist/types/types/columnTypes.d.ts

@@ -0,0 +1,30 @@
+import * as React from 'react';
+export type ColumnFilterType = 'none' | 'text' | 'multiSelect' | 'people';
+export interface IColumnFilterDef {
+    type: Exclude<ColumnFilterType, 'none'>;
+    filterField?: string;
+    optionsSource?: 'api' | 'static' | 'years';
+    options?: string[];
+    yearsCount?: number;
+}
+export interface IColumnMeta {
+    columnId: string;
+    name: string;
+    sortable?: boolean;
+    filterable?: false | IColumnFilterDef;
+    defaultVisible?: boolean;
+    required?: boolean;
+    minWidth?: number;
+    defaultWidth?: number;
+    idealWidth?: number;
+}
+export interface IColumnDef<T = unknown> extends IColumnMeta {
+    renderCell?: (item: T) => React.ReactNode;
+    compare?: (a: T, b: T) => number;
+}
+/** Minimal column info for the ColumnChooser (framework-agnostic). */
+export interface IColumnDefinition {
+    columnId: string;
+    name: string;
+    required?: boolean;
+}

package/dist/types/types/dataGridTypes.d.ts

@@ -0,0 +1,44 @@
+export interface UserLike {
+    id?: string;
+    displayName: string;
+    email: string;
+    photo?: string;
+}
+export declare function toUserLike(u: {
+    displayName: string;
+    mail?: string;
+    userPrincipalName?: string;
+    email?: string;
+    id?: string;
+    photo?: string;
+} | undefined): UserLike | undefined;
+/** Unified filter values: text (string), multi-select (string[]), or people (UserLike). */
+export interface IFilters {
+    [field: string]: string | string[] | UserLike | undefined;
+}
+/** Split IFilters into DataGridTable's multiSelect, text, and people props. */
+export declare function toDataGridFilterProps(filters: IFilters): {
+    multiSelectFilters: Record<string, string[]>;
+    textFilters: Record<string, string>;
+    peopleFilters: Record<string, UserLike | undefined>;
+};
+export interface IFetchParams {
+    page: number;
+    pageSize: number;
+    sort?: {
+        field: string;
+        direction: 'asc' | 'desc';
+    };
+    filters: IFilters;
+}
+export interface IPageResult<T> {
+    items: T[];
+    totalCount: number;
+}
+/** Data source API: fetch a page and optionally filter options / people. */
+export interface IDataSource<T> {
+    fetchPage(params: IFetchParams): Promise<IPageResult<T>>;
+    fetchFilterOptions?(field: string): Promise<string[]>;
+    searchPeople?(query: string): Promise<UserLike[]>;
+    getUserByEmail?(email: string): Promise<UserLike | undefined>;
+}

package/dist/types/types/index.d.ts

@@ -0,0 +1,3 @@
+export type { ColumnFilterType, IColumnFilterDef, IColumnMeta, IColumnDef, IColumnDefinition, } from './columnTypes';
+export type { UserLike, IFilters, IFetchParams, IPageResult, IDataSource, } from './dataGridTypes';
+export { toUserLike, toDataGridFilterProps } from './dataGridTypes';

package/dist/types/utils/exportToCsv.d.ts

@@ -0,0 +1,9 @@
+export interface CsvColumn {
+    columnId: string;
+    name: string;
+}
+export declare function escapeCsvValue(value: unknown): string;
+export declare function buildCsvHeader(columns: CsvColumn[]): string;
+export declare function buildCsvRows<T>(items: T[], columns: CsvColumn[], getValue: (item: T, columnId: string) => string): string[];
+export declare function exportToCsv<T>(items: T[], columns: CsvColumn[], getValue: (item: T, columnId: string) => string, filename?: string): void;
+export declare function triggerCsvDownload(csvContent: string, filename: string): void;

package/dist/types/utils/index.d.ts

@@ -0,0 +1,2 @@
+export { escapeCsvValue, buildCsvHeader, buildCsvRows, exportToCsv, triggerCsvDownload, } from './exportToCsv';
+export type { CsvColumn } from './exportToCsv';

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@alaarab/ogrid-core",
+  "version": "1.0.0",
+  "description": "OGrid core – framework-agnostic types, hooks, and utilities for OGrid data tables.",
+  "main": "dist/esm/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/esm/index.js"
+    }
+  },
+  "scripts": {
+    "build": "rimraf dist && tsc -p tsconfig.build.json",
+    "test": "jest"
+  },
+  "keywords": ["ogrid", "datatable", "react", "typescript", "grid", "core"],
+  "author": "Ala Arab",
+  "license": "MIT",
+  "files": ["dist", "README.md", "LICENSE"],
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "react": "^17.0.0 || ^18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}