Skip to content

Commit 87ef6a1

Browse files
jn138jn138
committed
qwik release version 0.0.5
1 parent 5e8f45f commit 87ef6a1

File tree

5 files changed

+108
-43
lines changed

5 files changed

+108
-43
lines changed

‎README.md‎

Lines changed: 103 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -15,17 +15,16 @@ import { mocked } from "~/__mocked__/data"
1515

1616
export default component$(() => {
1717
const tData = useResource$(async () => {
18-
const { Head, Body } = await tableLoader({
18+
const { THead, TBody } = await tableLoader({
1919
tData: mocked,
2020
})
21-
return { Head, Body }
21+
return { THead, TBody }
2222
})
2323

2424
return (
2525
<Resource
2626
value={tData}
27-
onPending={() => <></>}
28-
onResolved={({ Head, Body }) => (
27+
onResolved={({ THead, TBody }) => (
2928
<table>
3029
<thead>
3130
<Head />
@@ -40,13 +39,22 @@ export default component$(() => {
4039
})
4140
```
4241

42+
## Docs
43+
44+
- [Features](#features)
45+
- [Usage](#usage)
46+
- [API](#api)
47+
- [Tips](#tips)
48+
- [Read More](#read-more)
49+
4350
## Features
4451

45-
### v.0.0.3
52+
### v.0.0.5 (first s-table version)
4653

47-
- Use `tableLoader` to generate table JSX elements such as: _&lt;Head /&gt;, &lt;Body /&gt;, &lt;THead /&gt; and &lt;TBody /&gt;_.
48-
- Customize table elements by parsing properties to `tableLoader`.
49-
- **TypeScript** and **TailwindCSS** friendly (I think).
54+
- Use `tableLoader` to generate table JSX elements: _&lt;THead /&gt; and &lt;TBody /&gt;_.
55+
- Customize table elements by parsing properties into `tableLoader`.
56+
- Built-in methods for sophisticated table functionalities.
57+
- **TypeScript** and **TailwindCSS** friendly.
5058

5159
## Usage
5260

@@ -77,25 +85,41 @@ pnpm install -D qwik-table-loader
7785
Import the library
7886

7987
```typescript
80-
import { component$, useResource$, Resource } from "@builder.io/qwik"
81-
import { tableLoader } from "qwik-table-loader"
88+
import {
89+
component$,
90+
useSignal,
91+
useResource$,
92+
Resource,
93+
$,
94+
} from "@builder.io/qwik"
95+
import { tableLoader, sortTable } from "qwik-table-loader"
96+
import type { TableRecord } from "qwik-table-loader"
97+
import LoadingSpinner from "~/components/loading-spinner"
98+
import { mocked } from "~/__mocked__/data"
8299
```
83100

84101
You must wrap the table data inside `useResource$`, and the return element inside `Resource`. To put it in other frameworks' language: **The data must be memoized**.
85102

86103
```typescript
87104
export default component$(() => {
88-
const tData = useResource$(async () => {
105+
const data = useSignal<TableRecord[]>(mocked)
106+
107+
const tData = useResource$(async ({ track }) => {
108+
track(() => data)
89109
const { THead, TBody } = await tableLoader({
90-
tData: mocked,
110+
tData: data,
91111
transformHeads: true,
92112
tailwindClasses: true,
93113
tHeadings: {
94114
props: {
95115
class: "bg-rose-500 text-white"
96116
onClick$: $(() => onClickFunc())
97117
}
98-
accessor: $((heading) => <><Icon />{heading}</>),
118+
element$: $((heading) => (
119+
<div onClick$={$(() => sortTable(data, heading, true))}>
120+
{heading}
121+
</div>
122+
)),
99123
},
100124
})
101125
return { THead, TBody }
@@ -104,10 +128,15 @@ export default component$(() => {
104128
return (
105129
<Resource
106130
value={tData}
131+
onPending={() => <LoadingSpinner />}
107132
onResolved={({ THead, TBody }) => (
108133
<table>
109-
<THead />
110-
<TBody />
134+
<thead>
135+
<Head />
136+
</thead>
137+
<tbody>
138+
<Body />
139+
</tbody>
111140
</table>
112141
)}
113142
/>
@@ -117,38 +146,72 @@ export default component$(() => {
117146

118147
### 3. Customize loader's properties
119148

120-
In order to customize the table, simply provide your desired properties to the `tableLoader`. See the section below for more.
149+
In order to customize the table, simply provide your desired properties to the `tableLoader` (see [API](#api) for more details).
150+
151+
### 4. Add table functions
152+
153+
Such methods including _search_, _filter_ or _sort_ can be found the library as well for your convenience (see [API](#api) for more details).
121154

122155
## API
123156

124157
### 1. `tableLoader`
125158

126159
These properties can be set in `tableLoader` during memoization.
127160

128-
| Property | Type | Description | Required |
129-
| --------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
130-
| tData | Record[] | Table data _(must be memoized)_. | ✅ |
131-
| transformHeads | boolean | Checkbox if you want to transform your data params to headings (ie. turn "date_received" to "Date Received"). Support both `snakeCaseParams` and `camel_case_params`. | ❌ (default = `true`) |
132-
| tailwindClasses | boolean | Checkbox if you want to include the library's default Tailwind classes to the return components. You can always customize the classes using `accessor` (see below). | ❌ (default = `true`) |
133-
| tHeadings | Object | Customize table headings here! | ❌ |
134-
| tHeadings.props | { [key: string]: JSXChildren } | Add props to all &lt;th&gt; tags. | ❌ |
135-
| tHeadings.props.class | string | Add class list to all &lt;th&gt; tags. For `TailwindCSS` users, you can add your classes here. | ❌ |
136-
| tHeadings.accessor | QRL<(heading: string) => JSX.Element> | Render custom JSX elements inside all &lt;th&gt; tags. | ❌ |
137-
| tRows | Object | Customize table rows here! | ❌ |
138-
| tRows.props | { [key: string]: JSXChildren } | Add props to all &lt;tr&gt; tags. | ❌ |
139-
| tRows.props.class | string | Add class list to all &lt;tr&gt; tags. For `TailwindCSS` users, you can add your classes here. | ❌ |
140-
| tCells | Object | Customize table cells here! | ❌ |
141-
| tCells.props | { [key: string]: JSXChildren } | Add props to all &lt;td&gt; tags. | ❌ |
142-
| tCells.props.class | string | Add class list to all &lt;td&gt; tags. For `TailwindCSS` users, you can add your classes here. | ❌ |
143-
| tCells.accessor | QRL<(record: TableRecord, param: string) => JSX.Element> | Render custom JSX elements inside all &lt;td&gt; tags. | ❌ |
144-
145-
### 2. Return Components
161+
| Property | Type | Description | Required |
162+
| --------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
163+
| tData | Record[] | Table data _(must be memoized)_. | ✅ |
164+
| transformHeads | boolean | Checkbox if you want to transform your data params to headings (ie. turn "date_received" to "Date Received"). Support both `snakeCaseParams` and `camel_case_params`. | ❌ (default = `true`) |
165+
| tHeadings | Object | Customize table headings here! | ❌ |
166+
| tHeadings.props | { [key: string]: JSXChildren } | Add props to all &lt;th&gt; tags. | ❌ |
167+
| tHeadings.props.class | string | Add class list to all &lt;th&gt; tags. For `TailwindCSS` users, you can change your classes here. | ❌ (default = `"table-heading"`) |
168+
| tHeadings.accessor | QRL<(heading: string) => JSX.Element> | Render custom JSX elements inside all &lt;th&gt; tags. | ❌ |
169+
| tRows | Object | Customize table rows here! | ❌ |
170+
| tRows.props | { [key: string]: JSXChildren } | Add props to all &lt;tr&gt; tags. | ❌ |
171+
| tRows.props.class | string | Add class list to all &lt;tr&gt; tags. For `TailwindCSS` users, you can change your classes here. | ❌ (default = `"table-row"`) |
172+
| tCells | Object | Customize table cells here! | ❌ |
173+
| tCells.props | { [key: string]: JSXChildren } | Add props to all &lt;td&gt; tags. | ❌ |
174+
| tCells.props.class | string | Add class list to all &lt;td&gt; tags. For `TailwindCSS` users, you can change your classes here. | ❌ (default = `"table-cell"`) |
175+
| tCells.accessor | QRL<(record: TableRecord, param: string) => JSX.Element> | Render custom JSX elements inside all &lt;td&gt; tags. | ❌ |
176+
177+
### 2. `tableLoader` Return Components
146178

147179
These are the components returned by `tableLoader`.
148180

149-
| Component | Description |
150-
| ----------- | ------------------------------------------------------------ |
151-
| `<Head />` | List of table headers. Must be wrapped in &lt;thead&gt; tag. |
152-
| `<THead />` | List of table headers wrapped in &lt;thead&gt; tag. |
153-
| `<Body />` | Table body. Must be wrapped in &lt;tbody&gt; tag. |
154-
| `<TBody />` | Table body wrapped in &lt;tbody&gt; tag. |
181+
| Component | Type | Description |
182+
| ----------- | ------------ | ------------------------------------------------------------ |
183+
| `<THead />` | `component$` | List of table headers. Must be wrapped in &lt;thead&gt; tag. |
184+
| `<TBody />` | `component$` | Table body. Must be wrapped in &lt;tbody&gt; tag. |
185+
186+
### 3. Methods
187+
188+
These methods support sophisticated table functions apart from generating table data. They can be imported directly from the library, same as `tableLoader`.
189+
190+
| Method | Parameters | Description |
191+
| ----------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
192+
| `param2string()` | str: `string` | Convert `snake_case_param` or `camelCaseParam` to string. Used in table headings. |
193+
| `string2param()` | str: `string`, method: `"snake" or "camel"` | Convert string to `snake_case` or `camelCase`, opposed to `param2string()` method. |
194+
| `sortTable()` | data: `Record[]`, param: `string`, isAcending: `boolean` | Sort table data with given heading (`param`) in ascending order (isAcending=`true`) or descending (isAcending=`false`). |
195+
| `searchTable()` | data: `Record[]`, params: `string[]`, keyword: `string` | Search table data base with given headings (`params`) and keyword (`keyword`). Can be used in search or filter inputs. |
196+
| `getTotalPages()` | total_record: `number`, record_per_page: `number` | Calculate total pages. Can be used in paginating table records. |
197+
198+
## Tips
199+
200+
- Make sure to name your param in your data in either `snake_case` or `camelCase` for `transformHeads` feature to work properly...
201+
202+
```typescript
203+
const data = {
204+
name: "Jon Doe", // OK
205+
date_of_birth: "1990/01/01", // OK
206+
timeZone: "UTC+08:00", // OK
207+
// ...
208+
}
209+
```
210+
211+
- The table `props` property has type `[key: string]: JSXChildren` in which `JSXChildren` does NOT include `QRL`. Therefore, you should only add basic `props` such as ID or class; for event handlers like `onClick$` or `onFocus$` for example, try to add those in a separate element in the `element$` property instead.
212+
213+
- Check out some examples located in the folder `/example` in the library.
214+
215+
## Read More
216+
217+
- [Qwik Documentation](https://qwik.builder.io/docs/)

src/example/BasicTable.tsx renamed to example/BasicTable.tsx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { component$, useResource$, Resource, $ } from "@builder.io/qwik"
2-
import { tableLoader } from "../loaders/tableLoader"
2+
import { tableLoader } from "../src/loaders/tableLoader" // change this to "qwik-table-loader"
33

44
export default component$(() => {
55
const tData = useResource$(async () => {

‎example/index.tsx‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
import BasicTable from "./BasicTable"
2+
3+
export { BasicTable }

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "qwik-table-loader",
3-
"version": "0.0.4",
3+
"version": "0.0.5",
44
"description": "A table library for Qwik",
55
"main": "src/index.ts",
66
"engines": {

‎src/example/index.tsx‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

0 commit comments

Comments
 (0)