jb-grid 0.4.1 → 0.5.0

package/README.md

@@ -40,9 +40,26 @@ For the standalone pagination API and CSS variables, see [jb-pagination README](
 
 ### jb-pagination CSS variables
 
-| CSS variable name | description |
-| --- | --- |
-| --jb-pagination-index-width | Width of each page index button. |
+| CSS variable name | description |
+| --- | --- |
+| --jb-pagination-arrow-button-fill-color | Fill color of pagination arrow buttons. |
+| --jb-pagination-arrow-button-fill-color-disabled | Fill color of disabled pagination arrow buttons. |
+| --jb-pagination-index-width | Width of each page index button. |
+| --jb-pagination-page-index-color | Color of page index buttons. |
+| --jb-pagination-page-index-color-current | Color of the current page index button. |
+
+### jb-row CSS variables
+
+| CSS variable name | description |
+| --- | --- |
+| --jb-row-bg-color | Row background color. |
+| --jb-row-bg-color-even | Even row background color. |
+| --jb-row-bg-color-even-tablet | Even row background color in tablet layout. |
+| --jb-row-border-radius | Row border radius in tablet layout. |
+| --jb-row-expand-border-color | Expand panel bottom border color. |
+| --jb-row-expand-padding-block | Expand panel block padding. |
+| --jb-row-expand-padding-inline | Expand panel inline padding. |
+| --jb-row-shadow-color | Row shadow color in tablet layout. |
 
 ## Row & Cells
 `jb-row` is a row web-component that imply a grid template based on given config to below cells. it also accept expand row that you can open and close it.
@@ -64,7 +81,7 @@ to set column size of the row you can pass a config that tell each column size.
 ```js
 document.querySelector(""jb-row).rowTemplate = [
   {name:"id",size:"1fr"},
-  {name:"name",size:"400px"},
+  {name:"name",size:"25rem"},
   {name:"age",size:200},
   {name:"operation",size:20%},
 ]
@@ -91,11 +108,121 @@ document.querySelector(`jb-row`).isOpen = true;
 document.querySelector(`jb-row`).isOpen = false;
 ```
 
-### Ellipses Cell
-
-if your cell content is a long text need to get ellipses on overflow add `ellipsis` attribute to the `jb-cell` and `ellipsis="max line"` for multiline
+### Ellipses Cell
+
+Cells clip horizontal overflow to stay inside their grid column. If long text should show an ellipsis, add the `ellipsis` attribute to `jb-cell`; use `ellipsis="max line"` for multiline truncation.
 ```html
-<jb-cell ellipsis>Put Long Text Here</jb-cell>
-<!-- Limited Browser Support for Multiline -->
-<jb-cell ellipsis="3">Put Long Text Here</jb-cell>
-```
+<jb-cell ellipsis>Put Long Text Here</jb-cell>
+<!-- Limited Browser Support for Multiline -->
+<jb-cell ellipsis="3">Put Long Text Here</jb-cell>
+```
+
+## Table Header
+
+`jb-table-header` is a grid header wrapper for `jb-col-header` cells. Set `headerTemplate` to the same column template shape used by `jb-row`.
+
+```html
+<jb-table-header>
+  <jb-col-header name="id">
+    <span slot="title">ID</span>
+  </jb-col-header>
+  <jb-col-header name="name" sortable>
+    <span slot="title">Name</span>
+  </jb-col-header>
+</jb-table-header>
+```
+
+```js
+import 'jb-grid';
+
+document.querySelector('jb-table-header').headerTemplate = [
+  { name: 'id', size: '5rem' },
+  { name: 'name', size: '1fr' },
+];
+```
+
+### jb-table-header API
+
+| name | type | description |
+| --- | --- | --- |
+| `headerTemplate` | property | Column template config for the header grid. |
+
+### jb-col-header API
+
+| name | type | description |
+| --- | --- | --- |
+| `name` | attribute/property | Column name. It is used as the grid-area name. |
+| `sortable` | attribute/property | Enables click sorting for this column. |
+| `sort` | attribute/property | Current sort direction. Accepts `asc`, `desc`, or no value. |
+| `sort` | event | Fired when a sortable header is clicked. Event detail is `{ name, sort }`. |
+| `title` | slot | Header caption content. |
+
+```js
+document.querySelector('jb-col-header').addEventListener('sort', (event) => {
+  console.log(event.detail.name, event.detail.sort);
+});
+```
+
+## Pagination Info
+
+`jb-pagination-info` shows page-size selection and the current item range.
+
+```html
+<jb-pagination-info></jb-pagination-info>
+```
+
+```js
+const paginationInfo = document.querySelector('jb-pagination-info');
+
+paginationInfo.pageSize = 20;
+paginationInfo.pageSizes = [10, 20, 50, 100];
+paginationInfo.startItemIndex = 1;
+paginationInfo.endItemIndex = 20;
+paginationInfo.totalItemsCount = 124;
+paginationInfo.pageItemCountTitle = 'Items per page';
+paginationInfo.fromLabel = 'of';
+paginationInfo.currentAvailableItemTitle = 'Available items';
+paginationInfo.showPersianNumber = false;
+
+paginationInfo.addEventListener('page-size-change', (event) => {
+  console.log(event.detail.pageSize);
+});
+```
+
+### jb-pagination-info API
+
+| name | type | description |
+| --- | --- | --- |
+| `pageSize` | property | Current selected page size. |
+| `pageSizes` | property | Available page-size options. Default is `[20, 30, 50, 100]`. |
+| `startItemIndex` | property | First visible item index. |
+| `endItemIndex` | property | Last visible item index. |
+| `totalItemsCount` | property | Total item count. |
+| `pageItemCountTitle` | property | Tooltip text for the page-size section. |
+| `fromLabel` | property | Label rendered before the total count. |
+| `currentAvailableItemTitle` | property | Tooltip text for the total count. |
+| `showPersianNumber` | property | Converts displayed numbers to Persian digits when `true`. |
+| `page-size-change` | event | Fired when the selected page size changes. Event detail is `{ pageSize }`. |
+
+## Utility Icons
+
+`jb-refresh-icon` and `jb-fullscreen-icon` are standalone icons used by the grid controls.
+
+```html
+<jb-refresh-icon></jb-refresh-icon>
+<jb-fullscreen-icon state="enter"></jb-fullscreen-icon>
+```
+
+### jb-refresh-icon API
+
+| name | type | description |
+| --- | --- | --- |
+| `play()` | method | Starts the refresh rotation animation. |
+| `pause()` | method | Pauses the refresh rotation animation. |
+| `stop()` | method | Stops the animation after the current rotation finishes. |
+
+### jb-fullscreen-icon API
+
+| name | type | description |
+| --- | --- | --- |
+| `state` | attribute/property | Icon state. Accepts `enter` or `exit`. |

package/package.json

@@ -14,17 +14,15 @@
     "web component",
     "react component"
   ],
-  "version": "0.4.1",
+  "version": "0.5.0",
   "bugs": "https://github.com/javadbat/jb-grid/issues",
   "license": "MIT",
   "files": [
     "LICENSE",
     "README.md",
-    "lib/",
-    "dist/",
     "react/",
-    "web-component/",
-    "web-component/dist",
+    "web-component/lib/",
+    "web-component/dist/",
     "react/dist/"
   ],
   "main": "index.js",
@@ -34,9 +32,8 @@
 		"url": "git@github.com:javadbat/jb-grid.git"
   },
   "dependencies": {
-    "jb-core":">=0.27.2",
-    "mobx":">=6.0.0",
-    "mobx-react":">=7.0.0",
+    "jb-button":">=3.10.0",
+    "jb-core":">=0.30.0",
     "jb-searchbar":">=3.0.2"
   }
 }

package/react/README.md

@@ -1,206 +1,211 @@
-# jb-grid React component
-
-[![Published on webcomponents.org](https://img.shields.io/badge/webcomponents.org-published-blue.svg)](https://www.webcomponents.org/element/jb-grid)
-[![GitHub license](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://raw.githubusercontent.com/javadbat/jb-grid/main/LICENSE)
-[![NPM Version](https://img.shields.io/npm/v/jb-grid-react)](https://www.npmjs.com/package/jb-grid-react)
-![GitHub Created At](https://img.shields.io/github/created-at/javadbat/jb-grid)
-
-react mobx table grid with pagination, filtering and sorting functionality.
-
-- responsive
-- mobx ready
-- easy filter implementation (customizable)
-- customizable column templates
-- flexible column size
-- support for server side data fetching
-
-## instructions
-
-### install the package
-
-```sh
-npm i jb-grid
-```
-
-### import and use in your component
-```JSX
-import {Cell, Row, JBGrid} from 'jb-grid/react';
-//this file is a class that implement `JBGridBridgeClassInterface` interface to translate your server data to jb-grid data interface see Bridge section for more detail
-import {JBGridBridge} from './my-bridge';
-// grid config that impl JBGridConfig type see config section for more detail
-import {yourConfig} from './your-grid-config-file';
-//jb-search-bar config so you can filter your data
-import {filterConfig} from './my-filter-config';
-
-<JBGrid config={yourConfig} bridge={JBGridBridge} title="user list" searchbarConfig={vm.filterConfig}></JBGrid>
-```
-
-### config
-
-config is unique for each data table you want to show and contains information about columns,filters,sort,initData,...    
-you can create your own config from scratch using Mobx class Stores that implements `JBGridConfigInterface` or just create instance of `JBGridData` and start to config it's fields based on your need.
-
-```js
-import { JBGridData } from "jb-grid/react";
-
-const yourConfig = new JBGridData();
-```
-or in typescript: (in javascript you don't need to implements from `JBGridConfigInterface` but you have to check every detail manually to avoid errors)
-```ts
-import {JBGridConfigInterface}  from "jb-grid/types"
-
-class yourConfigClass implements JBGridConfigInterface{
-    //put your config here. for sample code see /lib/JBGridData in package files
-}
-export const yourConfig = new yourConfigClass();
-```
-you can config columns of table like this:    
-
-```js
-yourConfig.table.columns = [
-            {
-                //uniq identifier of column
-                id: 1,
-                //will be used as a key in sort  object when sorting by column
-                name: 'name',
-                //showed in column header
-                title: 'نام',
-                //let us sort column default is false
-                sortable: true,
-            },
-            {
-                id: 2,                
-                name: 'age',
-                title: 'سن',
-                sortable: false,
-                //if you don't set width , it will be '1fr' mean it get 1 share of width from free space
-                width: '1fr'
-            },
-            {
-                id: 3,
-                name: 'expand',
-                title: 'باز کردن',
-                sortable: false,
-                //you can set px,em, auto, fr , % , ... in here 
-                width: '200px'
-            }
-        ];
-
-```
-to config backend service call config you can set `` like this:
-```js
-        // your api endpoint
-        yourConfig.data.requestParams.url = "http://localhost:3000/grid/user-list",
-        //endpoint http method
-        yourConfig.data.requestParams.method = "POST";
-        // you can set any custom parameter your backend needs here. for example if you using grpc or graphql you can set any config they need
-        yourConfig.data.requestParams.custom1 = {aa:""};
-        yourConfig.data.requestParams.foo = "x";
-```
-### i18n
-you can pass a i18n config to set a text, number display and other localization config to jb-grid
-```tsx
-const i18nMessages:JBGridI18nMessage = {
-  EnterPageNumberMessage:"شماره صفحه ای که میخواهید وارد آن شوید را وارد کنید",
-  serverErrorText:"متاسفانه در هنگام بارگذاری اطلاعات خطایی رخ داده است",
-  serverErrorTitle:"すみません",
-  serverErrorRefreshButtonTitle:"تلاش مجدد",
-  currentAvailableItem:"تعداد کل ایتم های موجود",
-  pageItemCount:"تعداد آیتم در هر صفحه",
-  from:"از"
-};
-export const i18n:JBGridI18nConfig = {
-  messages: i18nMessages,
-  showPersianNumber:false
-};
-<JBGrid i18n={i18n}></JBGrid>
-
-```
-### actions
-
-there is some actions you may want to call inside a grid for example you need to refresh data by code after some entity insert/update or fullscreen grid by code. for doing so you just have to call `actionDispatchers` methods in your grid config after initialization process (after render of jb-grid finish grid will automatically extend your config and add this methods).
-```typescript
-//action dispatcher type in typescript:
-type ActionDispatchers = Readonly<{
-    refreshData: () => Promise<void>,
-    fullScreenGrid: () => void,
-    exitFullScreenGrid: () => void
-}>
-// the call function:
-    yourConfig.actionDispatchers.refreshData();
-// 
-```
-
-### bridge
-
-bridge is a js/ts class, responsible for converting jb-grid standard data to your back-end standard data and reverse.
-jb-grid doesn't send request by it self, instead it ask bridge to send request & and receive data. so you have freedom to use whatever standard and technology you may see fit.
-the reason that we separate config & bridge is most of the time all tables of your project use  same request and response data structure so you don't need to repeat yourself. you code 1 bridge for all of project and config each list for endpoints url ,...
-
-### filter
-
-### show list
-
-### custom error page
-
-if you want to show customized error page instead of default one use `contentError` prop
-```jsx
-<JBGrid contentError={<CustomErrorComponent />}></JBGrid>
-```
-
-### full-screen grid
-
-jb-grid has a fullscreenable feature and you can activate that by set `isFullscreen={value:bool}` for example
-
-```jsx
-    const [isFullscreen,setIsFullscreen] = useState(false);
-    <JBGrid isFullscreen={isFullscreen} onFullscreenChange={(newValue)=>setIsFullscreen(newValue)}></JBGrid>
-
-```
-### expandable row
-you can add expandable row so user can expand row to see more info about a row in detail
-
-```jsx
-<JBGrid config={jbGridConfig} bridge={JBGridBridge} title="general list" searchbarConfig={filterConfig}>
-    {
-        jbGridConfig.data.data.map(
-            (item) => {
-                return (
-                    <React.Fragment key={item.id}>
-                        <Row>
-                            <Cell>{item.name}</Cell>
-                            <Cell>{item.age}</Cell>
-                            <Cell><button onClick={()=>{item.jbGridDetail.isExpanded = !item.jbGridDetail.isExpanded;}}>detail</button></Cell>
-                        </Row>
-                        <ExpandRow show={item.jbGridDetail.isExpanded}>
-                            <YourExpandedData></YourExpandedData>
-                        </ExpandRow>
-                    </React.Fragment>
-
-                );
-            }
-        )
-    }
-</JBGrid>
-
-```
-
-## make it mobile friendly
-
-jb-grid by default is mobile friendly but when it turns to mobile view it show row as cards. this cards show the table fields in themselves but without any label. to show label of columns beside the cell in mobile just add `label` property to each cell like this:
-```jsx
-            <Row>
-                <Cell label="name:">{item.name}</Cell>
-                <Cell label="age:">{item.age}</Cell>
-                <Cell label="operations:"><button onClick={()=>{item.jbGridDetail.isExpanded = !item.jbGridDetail.isExpanded;}}>detail</button></Cell>
-            </Row>
-```
-
+# jb-grid React component
+
+[![Published on webcomponents.org](https://img.shields.io/badge/webcomponents.org-published-blue.svg)](https://www.webcomponents.org/element/jb-grid)
+[![GitHub license](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://raw.githubusercontent.com/javadbat/jb-grid/main/LICENSE)
+[![NPM Version](https://img.shields.io/npm/v/jb-grid-react)](https://www.npmjs.com/package/jb-grid-react)
+![GitHub Created At](https://img.shields.io/github/created-at/javadbat/jb-grid)
+
+react table grid with pagination, filtering and sorting functionality.
+
+- responsive
+- React state ready
+- easy filter implementation (customizable)
+- customizable column templates
+- flexible column size
+- stateless data, pagination, loading, and error handling
+
+## instructions
+
+### install the package
+
+```sh
+npm i jb-grid
+```
+
+### import and use in your component
+```JSX
+import {JBCell, JBRow, JBGrid} from 'jb-grid/react';
+import {Searchbar} from './Searchbar';
+
+<JBGrid
+  data={data}
+  pageIndex={pageIndex}
+  pageSize={pageSize}
+  totalItemsCount={totalItemsCount}
+  title="user list"
+  searchbarComponent={<Searchbar />}
+  onPageIndexChange={setPageIndex}
+  onPageSizeChange={setPageSize}
+  onRefresh={refreshData}
+></JBGrid>
+```
+
+### state
+
+`JBGrid` is stateless. Keep data, pagination, loading, error, filtering, sorting, columns, and row expansion in your own component/store and pass the current values to the grid.
+
+```tsx
+<JBGrid
+  data={data}
+  pageIndex={pageIndex}
+  pageSize={pageSize}
+  totalItemsCount={totalItemsCount}
+  totalPages={totalPages}
+  isLoading={isLoading}
+  isErrorOccurred={isErrorOccurred}
+  onPageIndexChange={(newPageIndex) => setPageIndex(newPageIndex)}
+  onPageSizeChange={(newPageSize) => setPageSize(newPageSize)}
+  onRefresh={() => loadData()}
+  title="user list"
+/>
+```
+
+### table header and rows
+
+The grid does not own column definitions. If you need a table header, render it yourself with `tableHeader`. Pass row layout directly to `JBRow`.
+
+```ts
+const rowTemplate = [
+  { name: "name", size: "1fr" },
+  { name: "age", size: "6.25rem" },
+  { name: "operation", size: "10rem" }
+];
+```
+```tsx
+  <JBTableHeader headerTemplate={rowTemplate}>
+    <JBColumnHeader name="id">ID</JBColumnHeader>
+    <JBColumnHeader name="name" sortable>Name</JBColumnHeader>
+    <JBColumnHeader name="family" sortable>Family</JBColumnHeader>
+    <JBColumnHeader name="age">Age</JBColumnHeader>
+  </JBTableHeader>
+```
+```tsx
+<JBGrid
+  tableHeader={<YourTableHeader />}
+  data={data}
+  pageIndex={pageIndex}
+  pageSize={pageSize}
+  totalItemsCount={totalItemsCount}
+  title="user list"
+>
+  {(data) => data.map((item) => (
+    <JBRow key={item.id} rowTemplate={rowTemplate}>
+      <JBCell name="name" label="name:">{item.name}</JBCell>
+      <JBCell name="age" label="age:">{item.age}</JBCell>
+      <JBCell name="operation" label="operations:"><button>detail</button></JBCell>
+    </JBRow>
+  ))}
+</JBGrid>
+```
+
+### i18n
+you can pass a i18n config to set a text, number display and other localization config to jb-grid
+```tsx
+const i18nMessages:JBGridI18nMessage = {
+  EnterPageNumberMessage:"شماره صفحه ای که میخواهید وارد آن شوید را وارد کنید",
+  serverErrorText:"متاسفانه در هنگام بارگذاری اطلاعات خطایی رخ داده است",
+  serverErrorTitle:"すみません",
+  serverErrorRefreshButtonTitle:"تلاش مجدد",
+  currentAvailableItem:"تعداد کل ایتم های موجود",
+  pageItemCount:"تعداد آیتم در هر صفحه",
+  from:"از"
+};
+export const i18n:JBGridI18nConfig = {
+  messages: i18nMessages,
+  showPersianNumber:false
+};
+<JBGrid i18n={i18n} data={data} pageIndex={pageIndex} pageSize={pageSize} totalItemsCount={totalItemsCount}></JBGrid>
+
+```
+
+### filter
+
+### show list
+
+### custom error page
+
+if you want to show customized error page instead of default one use `contentError` prop
+```jsx
+<JBGrid {...gridProps} contentError={<CustomErrorComponent />} isErrorOccurred={isErrorOccurred}></JBGrid>
+```
+
+### full-screen grid
+
+jb-grid has a fullscreenable feature and you can activate that by set `isFullscreen={value:bool}` for example
+
+```jsx
+    const [isFullscreen,setIsFullscreen] = useState(false);
+    <JBGrid {...gridProps} isFullscreen={isFullscreen} onFullscreen={()=>setIsFullscreen(true)} onExitFullscreen={()=>setIsFullscreen(false)}></JBGrid>
+
+```
+### expandable row
+you can add expandable row so user can expand row to see more info about a row in detail
+
+```jsx
+<JBGrid data={data} pageIndex={pageIndex} pageSize={pageSize} totalItemsCount={totalItemsCount} title="general list" searchbarComponent={<Searchbar />}>
+    {
+        (data) => data.map(
+            (item) => {
+                return (
+                    <React.Fragment key={item.id}>
+                        <JBRow isOpen={expandedRowIds.has(item.id)}>
+                            <JBCell name="name">{item.name}</JBCell>
+                            <JBCell name="age">{item.age}</JBCell>
+                            <JBCell name="operation"><button onClick={()=>toggleRowExpanded(item.id)}>detail</button></JBCell>
+                            <div slot="expand">
+                            <YourExpandedData></YourExpandedData>
+                            </div>
+                        </JBRow>
+                    </React.Fragment>
+
+                );
+            }
+        )
+    }
+</JBGrid>
+
+```
+
+## make it mobile friendly
+
+jb-grid by default is mobile friendly but when it turns to mobile view it show row as cards. this cards show the table fields in themselves but without any label. to show label of columns beside the cell in mobile just add `label` property to each cell like this:
+```jsx
+            <JBRow>
+                <JBCell name="name" label="name:">{item.name}</JBCell>
+                <JBCell name="age" label="age:">{item.age}</JBCell>
+                <JBCell name="operation" label="operations:"><button onClick={()=>toggleRowExpanded(item.id)}>detail</button></JBCell>
+            </JBRow>
+```
+
+## Pagination
+
+The full React grid shows pagination from `pageIndex`, `pageSize`, `totalItemsCount`, and `totalPages`, and reports changes with `onPageIndexChange` and `onPageSizeChange`. If you need the standalone web-component pagination primitive, import and use `jb-pagination` from the web-component package directly.
+
+```jsx
+import 'jb-grid/web-component/lib/pagination';
+```
+
+See the web-component README for the standalone `pageIndex`, `min`, and `max` API.
+
+## Row & Cells
+
+The React package exports `Row`, `Cell`, and `ExpandRow` wrappers for the underlying row/cell primitives.
+
+```jsx
+<Row>
+  <Cell label="Name">Sara</Cell>
+  <Cell label="Age">32</Cell>
+</Row>
+```
+
+Use `Cell` for normal content, `ExpandRow` for expandable detail panels, and `label` on cells for the mobile card view.
+
 ## Styling
-| CSS variable name                          | description                                                            |
-| -------------                              | -------------                                                          |
-| --jb-grid-loading-color                    | list loading color                                                     |
-| --jb-grid-page-active-color                | color of active page                                                   |
+| CSS variable name                          | description                                                            |
+| -------------                              | -------------                                                          |
+| --jb-grid-footer-icon-fill-color-hover     | footer icon hover fill color                                           |
+| --jb-grid-loading-color                    | list loading color                                                     |
+| --jb-grid-page-color-active                | color of active page                                                   |
 
 ## Shared Documentation
 

package/react/dist/Content.d.ts

@@ -12,5 +12,4 @@ export type ContentProps = {
     errorComponent?: ReactNode;
 };
 declare function Content(props: ContentProps): React.JSX.Element;
-declare const _default: typeof Content;
-export default _default;
+export default Content;

package/react/dist/Footer.d.ts

@@ -5,5 +5,4 @@ type FooterProps = {
     isFullscreen: boolean;
 };
 declare function Footer(props: FooterProps): React.JSX.Element;
-declare const _default: typeof Footer;
-export default _default;
+export default Footer;