@batono/ui 0.0.3 → 0.0.4

package/README.md

@@ -1,6 +1,6 @@
 # @batono/ui
 
-> SHORT_DESCRIPTION.
+> UI primitives for the Batono server-driven interaction protocol.
 
 [![npm version](https://badge.fury.io/js/%40batono%2Fui.svg)](https://www.npmjs.com/package/@batono/ui)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
@@ -8,54 +8,280 @@
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
 [![codecov](https://codecov.io/gh/batono/ui/branch/main/graph/badge.svg)](https://codecov.io/gh/batono/ui)
 
-This package
+`@batono/ui` provides the UI building blocks for the Batono protocol — layout containers, content definitions, and
+action primitives. It builds on top of `@batono/core` and is designed to be used together with it.
 
 ---
 
 ## Features
 
-- ✅ No dependencies
+- ✅ Peer dependency on `@batono/core` only
+- ✅ Fully composable layout system (`rows`, `row`, `inline`)
+- ✅ Rich content definitions (`header`, `section`, `field`, `meta`, `note`, `stat`)
+- ✅ Fluent builder API with method chaining
+- ✅ Typed result interfaces for frontend renderers
+- ✅ String shorthand for field values — auto-wrapped in `Text`
 
 ---
 
 ## Installation
 
 ```bash
-npm install @batono/ui
-````
+npm install @batono/ui @batono/core
+```
 
 ---
 
 ## Basic Usage
 
+```ts
+import {bt as btCore} from '@batono/core'
+import {bt} from '@batono/ui'
+
+const openProfile = btCore.defineAction(
+  bt.request('GET', '/customers/42')
+)
+
+const graph = btCore.graph(
+  bt.rows(
+    bt.row(
+      bt.header('Batman Forever', {
+        avatar: 'BF',
+        subtitle: bt.inline(
+          bt.link('Bruno Labbadia', openProfile),
+          bt.text(' · '),
+          bt.text('K2602206207')
+        )
+      })
+    ),
+    bt.row(
+      bt.section('Personal Data', bt.rows(
+        bt.row(
+          bt.field('First Name', 'Batman'),
+          bt.field('Last Name', 'Forever')
+        ),
+        bt.row(
+          bt.field('Email', null),
+          bt.field('Phone', null)
+        )
+      ))
+    )
+  )
+)
+
+res.json(graph)
+```
+
+---
+
+## Layout
+
+### `rows` / `row`
+
+The primary layout system. `rows` is a vertical stack of `row` containers. Each `row` distributes its children
+horizontally with equal width.
 
 ```ts
-import {x} from '@batono/ui'
+bt.rows(
+  bt.row(bt.field('First Name', 'Batman'), bt.field('Last Name', 'Forever')),
+  bt.row(bt.field('Email', null))
+)
+```
+
+### `inline`
 
-const t =....
+A horizontal container without grid spacing — for composing inline content like subtitles.
 
+```ts
+bt.inline(
+  bt.link('Parent', openParent),
+  bt.text(' · '),
+  bt.text('K2602206207')
+)
 ```
 
 ---
 
-### Example2
+## Definitions
+
+### `header`
+
+Page-level header with avatar, subtitle and actions.
 
 ```ts
-import {x} from '@batono/ui'
+bt.header('Batman Forever', {
+  avatar: 'BF',
+  subtitle: bt.inline(bt.text('Student')),
+  actions: bt.actionButtons(
+    bt.action('+ Book Unit', bookUnit, {variant: 'primary'})
+  )
+})
+```
+
+### `section`
 
-const t =....
+A card container with a title, optional icon, actions and a rows layout.
 
+```ts
+bt.section('Personal Data', bt.rows(
+  bt.row(bt.field('First Name', 'Batman'))
+))
+  .withIcon('🧑')
+  .withVariant('accent')
+  .withActions(bt.actionButtons(
+    bt.action('Edit', editAction)
+  ))
 ```
 
+### `field`
+
+A labeled value. Accepts a string shorthand — automatically wrapped in `Text`.
+
+```ts
+bt.field('First Name', 'Batman')
+bt.field('Newsletter', 'Yes', 'bool-true')
+bt.field('Email', null)  // renders as empty
+bt.field('ID', bt.inline(bt.text('NJkR7'), bt.text(' (obfuscated)')))
+```
+
+### `meta`
+
+A compact chip or badge for metadata display.
+
+```ts
+bt.meta('89544').withLabel('ID').withIcon('🆔')
+bt.meta('New Customer').withVariant('badge-green')
+bt.meta('Student').withVariant('badge-accent')
+```
+
+### `stat`
+
+A large metric display for key numbers.
+
+```ts
+bt.stat('Available Units', '99.0')
+bt.stat('Available (HH:mm)', '74:15')
+```
+
+### `note`
+
+A timestamped note with author and optional actions.
+
+```ts
+bt.note(
+  'Student mentioned difficulties in analysis.',
+  'Maria K.',
+  '2026-02-12T11:15:00',
+  bt.actionButtons(
+    bt.action('✕', deleteNote, {variant: 'ghost'})
+  )
+)
+```
+
+### `text` / `link`
+
+Inline content primitives.
+
+```ts
+bt.text('Some text')
+bt.link('Open Profile', openProfileAction)
+```
+
+---
+
+## Actions
+
+### `request`
+
+An HTTP action definition.
+
+```ts
+bt.request('POST', '/bookings')
+bt.request('DELETE', '/users/42').withPayload({id: 42})
+```
+
+### `modal`
+
+A modal dialog action.
+
+```ts
+bt.modal('Are you sure?')
+```
+
+### `actionButtons`
+
+A container for `action` buttons, used in `header` and `section`.
+
+```ts
+bt.actionButtons(
+  bt.action('+ Book Unit', bookUnit, {variant: 'primary'}),
+  bt.action('+ Note', addNote, {variant: 'secondary'})
+)
+```
+
+---
+
+## Variants
+
+`RenderVariant` is used on `field`, `meta`, `section` and `action` to signal visual intent to the renderer.
+
+| Variant        | Usage                       |
+|----------------|-----------------------------|
+| `primary`      | Primary action button       |
+| `secondary`    | Secondary action button     |
+| `ghost`        | Subtle/destructive action   |
+| `mono`         | Monospace text (IDs, codes) |
+| `bool-true`    | Positive boolean value      |
+| `bool-false`   | Negative boolean value      |
+| `badge-green`  | Success/positive badge      |
+| `badge-accent` | Highlighted badge           |
+| `accent`       | Highlighted section         |
+
+---
+
+## Frontend Types
+
+`@batono/ui` exports typed result interfaces for frontend renderers — no dependency on build-time classes needed.
+
+```ts
+import type {
+  HeaderResult,
+  SectionResult,
+  FieldResult,
+  RowsResult,
+  Defined
+} from '@batono/ui'
+```
+
+All result types extend `Defined` from `@batono/core`:
+
+```ts
+interface Defined {
+  $schema: string
+  $graph: string
+  type: string
+}
+```
+
+---
+
+## Utilities
+
 ```ts
+import {NBSP} from '@batono/ui'
 
+bt.text(`${NBSP}·${NBSP}`) // non-breaking space separator
 ```
 
 ---
 
 ## Design Goals
 
-* Predictable behavior
+- **Semantic over generic** — `header`, `section`, `field` express intent, not just structure
+- **Fluent API** — method chaining for optional properties keeps constructors clean
+- **Frontend-agnostic** — result interfaces work with any renderer (Vue, React, vanilla)
+- **Composable** — every definition is an `IBuildable`, freely nestable
+- **Renderer-friendly** — `type` discriminator on every node enables exhaustive switch rendering
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@batono/ui",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "",
   "license": "MIT",
   "author": "Pascal Pfeifer <pascal@pfeifer.zone>",
@@ -38,16 +38,16 @@
     "prepublishOnly": "npm test",
     "build": "npm run clean && tsc",
     "clean": "rm -rf dist",
-    "test": "npm run build && node --test 'test/'",
-    "test:coverage": "npm run build && node --test 'test/' --experimental-test-coverage --test-coverage-exclude='test/**'",
-    "test:coverage:c8": "npm run build && npx c8 node --test 'test/'",
-    "test:coverage:lcov": "npm run build && node --enable-source-maps --test 'test/' --experimental-test-coverage --test-coverage-exclude='test/**' --test-reporter=lcov --test-reporter-destination=lcov.info"
+    "test": "npm run build && node --test",
+    "test:coverage": "npm run build && node --test --experimental-test-coverage --test-coverage-exclude='test/**'",
+    "test:coverage:c8": "npm run build && npx c8 node --test",
+    "test:coverage:lcov": "npm run build && node --enable-source-maps --test --experimental-test-coverage --test-coverage-exclude='test/**' --test-reporter=lcov --test-reporter-destination=lcov.info"
   },
   "devDependencies": {
     "@types/node": "^20.17.9",
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@batono/core": "^0.0.3"
+    "@batono/core": "^0.0.4"
   }
 }