@itrocks/list 0.0.20 → 0.0.22

package/README.md

@@ -7,3 +7,121 @@
 # list
 
 Generic action-based object list navigation in HTML and JSON.
+
+*This documentation was written by an artificial intelligence and may contain errors or approximations.
+It has not yet been fully reviewed by a human. If anything seems unclear or incomplete,
+please feel free to contact the author of this package.*
+
+## Installation
+
+```bash
+npm i @itrocks/list
+```
+
+## Usage
+
+`@itrocks/list` exposes a single `List` action that you can plug into your
+existing [@itrocks/action](https://github.com/itrocks-ts/action) workflow.
+
+The `List` action is meant to be attached to a domain class (for example an
+`User` entity) and is responsible for rendering either an HTML list page or a
+JSON payload depending on the requested format.
+
+```ts
+import { List } from '@itrocks/list'
+import { Request } from '@itrocks/action-request'
+
+// The domain object you want to list
+class User {
+	/* ... */
+}
+
+// Create an action instance for this domain
+const listUsers = new List<User>()
+
+// In your controller / route handler
+async function usersHtml (request: Request<User>) {
+	return listUsers.html(request)
+}
+
+async function usersJson (request: Request<User>) {
+	return listUsers.json(request)
+}
+```
+
+The request object is typically created by
+[@itrocks/action-request](https://github.com/itrocks-ts/action-request) from
+an incoming HTTP request.
+
+## API
+
+### `class List<T extends object = object> extends Action<T>`
+
+Main entry point of the module. It extends
+[@itrocks/action](https://github.com/itrocks-ts/action)'s `Action` class and
+adds list‑oriented behaviors.
+
+#### Type parameter
+
+- `T` – The domain object type you want to list (for example `User`).
+
+#### Properties
+
+- `lineHeight: number` – Estimated height of a row in pixels. This is mainly
+  used by the front‑end to compute scrollable area and virtualisation.
+
+#### Methods
+
+##### `html(request: Request<T>): Promise<HtmlResponse>`
+
+Builds an HTML response for the list view.
+
+The returned
+[`HtmlResponse`](https://github.com/itrocks-ts/core-responses#htmlresponse)
+contains the rendered table along with paging, filters and actions configured
+through your `Action` stack.
+
+Typical usage is to call this method from a route that should return HTML:
+
+```ts
+fastify.get('/users', async (req, reply) => {
+	const request = toActionRequest<User>(req) // project helper
+	const response = await listUsers.html(request)
+	reply
+		.status(response.status)
+		.headers(response.headers)
+		.type('text/html')
+		.send(response.body)
+})
+```
+
+##### `json(request: Request<T>): Promise<JsonResponse>`
+
+Builds a JSON representation of the same list data.
+
+The returned
+[`JsonResponse`](https://github.com/itrocks-ts/core-responses#jsonresponse)
+typically contains the current page of results, meta‑data (page, page size,
+total count) and any additional information configured via your
+`Action`/`List` setup.
+
+This is useful for API‑only endpoints, asynchronous front‑end components or
+infinite‑scroll lists.
+
+```ts
+fastify.get('/api/users', async (req, reply) => {
+	const request = toActionRequest<User>(req)
+	const response = await listUsers.json(request)
+	reply
+		.status(response.status)
+		.headers(response.headers)
+		.send(response.body)
+})
+```
+
+## Typical use cases
+
+- Back‑office list screens for any business entity (users, products, orders…).
+- Filterable / searchable tables built on top of
+  [@itrocks/table](https://github.com/itrocks-ts/table).
+- JSON list endpoints consumed by SPA or mobile applications.

package/build.js

@@ -1,10 +1,10 @@
 import { build } from '../build/build.js';
-import { xTargetCall } from '../xtarget/xtarget.js';
 import { TableFeed } from '../table/feed.js';
 import { TableFreeze } from '../table/freeze.js';
 import { TableFreezeInheritBackground } from '../table/freeze/inherit-background.js';
 import { TableFreezeInheritBorder } from '../table/freeze/inherit-border.js';
 import { tableByElement } from '../table/table.js';
+import { xTargetCall } from '../xtarget/xtarget.js';
 build('article[data-action="list"] > form > table.objects', element => {
     tableByElement(element, {
         plugins: [TableFeed, TableFreeze, TableFreezeInheritBackground, TableFreezeInheritBorder]

package/package.json

@@ -12,9 +12,9 @@
 	"description": "Generic action-based object list navigation in HTML and JSON",
 	"devDependencies": {
 		"@itrocks/prepare-module": "latest",
-		"@types/node": "^22.9",
-		"sass": "^1.83",
-		"typescript": "~5.8"
+		"@types/node": "^24.10",
+		"sass": "^1.95",
+		"typescript": "~5.9"
 	},
 	"engines": {
 		"node": ">=18"
@@ -32,12 +32,14 @@
 		"!*.map"
 	],
 	"keywords": [
+		"action",
 		"API",
 		"backend",
 		"browse",
 		"component",
 		"display",
 		"filter",
+		"html",
 		"interactive",
 		"json",
 		"list",
@@ -47,6 +49,8 @@
 		"search",
 		"select",
 		"selection",
+		"standard",
+		"view",
 		"UI",
 		"UX"
 	],
@@ -63,5 +67,5 @@
 		"build:front": "tsc -p esm/tsconfig.json && ../prepare-module/prepare-module.js esm"
 	},
 	"types": "./cjs/list.d.ts",
-	"version": "0.0.20"
+	"version": "0.0.22"
 }