@onivoro/server-html 24.30.12 → 24.30.13

package/README.md

@@ -1,12 +1,6 @@
 # @onivoro/server-html
 
-A TypeScript library for server-side HTML generation with a functional approach. Philosophically similar to JSX except there's no compilation.
-
-## Features
-
-- **Functional HTML Generation**: Create HTML elements using functional composition
-- **Type-Safe**: Full TypeScript support with proper type definitions
-- **Server-Side Focused**: Optimized for server-side rendering scenarios
+A TypeScript library for server-side HTML generation with a functional approach. Provides a simple, type-safe way to generate HTML strings on the server without any compilation or JSX.
 
 ## Installation
 
@@ -14,27 +8,173 @@ A TypeScript library for server-side HTML generation with a functional approach.
 npm install @onivoro/server-html
 ```
 
-## Quick Start
+## Overview
+
+This library provides functional HTML element creators that generate HTML strings. Each element is a function that takes content and optional attributes.
+
+## Core API
 
-Use the $-prefixed element factories from @vanilla-mint/dom server-side:
+### Element Functions
+
+The library exports element functions for common HTML tags:
 
 ```typescript
-import { $div, $h1, $p } from '@onivoro/server-html';
+import { div, h1, p, button, anchor } from '@onivoro/server-html';
+
+// Basic usage
+const html = div(['Hello World']);
+// Output: <div>Hello World</div>
 
-const html = $div({
-  className: 'container',
-  style: { display: 'flex', flexDirection: 'column' },
-  children: [
-    $h1({ textContent: 'Server-Side Rendering', style: { fontWeight: 700 }}),
-    $p({ textContent: 'This markup was generated on the server.' })
-  ]
+// With attributes
+const heading = h1(['Welcome'], { 
+  id: 'main-title',
+  style: { 'font-size': '2rem', color: 'blue' }
 });
+// Output: <h1 id="main-title" style="font-size: 2rem; color: blue;">Welcome</h1>
+
+// Nested elements
+const card = div([
+  h2(['Card Title']),
+  p(['This is the card content']),
+  button(['Click me'], { onclick: 'handleClick()' })
+]);
+```
+
+### Available Elements
+
+Regular elements:
+- `anchor`, `body`, `button`, `div`
+- `h1`, `h2`, `h3`, `h4`, `h5`, `h6`
+- `head`, `header`, `htm` (html), `main`
+- `p`, `pre`, `style`
+- `tab` (table), `tbody`, `td`, `th`, `thead`, `tr`
+
+Self-closing elements:
+- `img`
+
+### Special Styling
+
+The `anchor` and `button` elements come with default button styles that can be overridden:
+
+```typescript
+const styledButton = button(['Submit'], {
+  style: { 
+    // Default button styles are applied automatically
+    // You can override them here
+    'background-color': 'green'
+  }
+});
+```
+
+## Utility Functions
+
+### Table Generator
+
+Create HTML tables easily:
+
+```typescript
+import { table } from '@onivoro/server-html';
+
+const columns = ['Name', 'Age', 'City'];
+const rows = [
+  ['John', '30', 'New York'],
+  ['Jane', '25', 'London'],
+  ['Bob', '35', 'Paris']
+];
+
+const htmlTable = table(columns, rows);
+// Generates a complete table with alternating row colors
+```
+
+### Email Body Generator
+
+Create formatted email bodies with consistent styling:
+
+```typescript
+import { emailBody } from '@onivoro/server-html';
+
+const html = emailBody(
+  'Welcome!',                    // title
+  'Thanks for signing up',       // subtitle
+  [                             // content
+    p(['Your account is ready']),
+    button(['Get Started'], { href: 'https://example.com' })
+  ],
+  'https://example.com/logo.png', // optional logo URL
+  { 'font-family': 'Arial' }      // optional extra styles
+);
+```
+
+## Low-Level Functions
+
+For more control, use the low-level element creation functions:
+
+```typescript
+import { element, selfClosingElement } from '@onivoro/server-html';
+
+// Create custom elements
+const section = element('section', ['Content'], { class: 'my-section' });
+const br = selfClosingElement('br', {});
 ```
 
-## Contributing
+## Deprecated API
+
+The library includes deprecated functions prefixed with underscore (`_div`, `_h1`, etc.) that use the older `tag` and `selfClosingTag` functions. These are maintained for backward compatibility but should not be used in new code.
+
+## Type Safety
+
+All functions are fully typed with TypeScript:
+
+```typescript
+import { TAttributes, TElementRenderer } from '@onivoro/server-html';
 
-This package is part of the Onivoro monorepo. Please refer to the main repository for contribution guidelines.
+// Attributes type for element properties
+const attrs: TAttributes = {
+  id: 'my-id',
+  className: 'my-class',
+  style: {
+    display: 'flex',
+    'align-items': 'center'
+  }
+};
+
+// Element renderers return strings
+const myDiv: string = div(['Content'], attrs);
+```
+
+## Examples
+
+### Complete HTML Document
+
+```typescript
+import { htm, head, body, h1, div, p } from '@onivoro/server-html';
+
+const document = htm([
+  head([
+    '<meta charset="UTF-8">',
+    '<title>My Page</title>'
+  ]),
+  body([
+    h1(['Welcome to My Site']),
+    div([
+      p(['This is a paragraph']),
+      p(['Another paragraph'])
+    ], { class: 'content' })
+  ])
+]);
+```
+
+### Dynamic Content
+
+```typescript
+const items = ['Apple', 'Banana', 'Orange'];
+
+const list = div([
+  h2(['Fruits']),
+  ...items.map(item => div([item], { class: 'list-item' }))
+]);
+```
 
 ## License
 
-This library is licensed under the MIT License. See the LICENSE file in this package for details.
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onivoro/server-html",
-  "version": "24.30.12",
+  "version": "24.30.13",
   "license": "MIT",
   "type": "commonjs",
   "main": "./src/index.js",