From a8696e088efedf310929bc4e01eded36d41414b1 Mon Sep 17 00:00:00 2001 From: Asko Nõmm Date: Wed, 11 Feb 2026 16:48:43 +0200 Subject: Update docs --- API.md | 58 +++++++++++++++++++++++++++++++++++++--------------- README.md | 31 +++++++++++++++++++++++++--- bb.edn | 3 ++- src/dompa/nodes.cljc | 21 ++++++++++++++----- 4 files changed, 88 insertions(+), 25 deletions(-) diff --git a/API.md b/API.md index 3786b9b..625a7a5 100644 --- a/API.md +++ b/API.md @@ -7,10 +7,11 @@ - [`->coordinates`](#dompa.html/->coordinates) - Transform a html string into a vector of coordinates indicating where an HTML node ends and begins. - [`->nodes`](#dompa.html/->nodes) - Transform a html string into a tree of nodes, each representing one HTML node and its children. - [`dompa.nodes`](#dompa.nodes) - - [`$`](#dompa.nodes/$) - Creates a new node Usage: clojure ($ :div ($ "hello world" )) . + - [`$`](#dompa.nodes/$) - Creates a new node. - [`->html`](#dompa.nodes/->html) - Transform a vector of nodes into an HTML string. - [`defhtml`](#dompa.nodes/defhtml) - Creates a new function with name that outputs HTML. - [`traverse`](#dompa.nodes/traverse) - Recursively traverses given tree of nodes with a traverser-fn that gets a single node passed to it and returns a new updated tree. + - [`zip`](#dompa.nodes/zip) - Creates a zipper for given a given node. ----- # dompa.coordinates @@ -39,7 +40,7 @@ Transform given `html` according to given `coordinates` into coordinates/unify coordinates/->nodes) ``` -

Source

+

Source

## `compose` ``` clojure @@ -59,7 +60,7 @@ Composes a given `html` string into a vector of coordinates. will return 3 coordinates (div, text, div) instead of 2 (div, text). To unify the coordinates in a context-aware way, you pass the result of this function to the [`unify`](#dompa.coordinates/unify) function. -

Source

+

Source

## `unify` ``` clojure @@ -71,7 +72,7 @@ Function. Joins together given `coordinates` that represent one HTML node in `html`, using a stack-based approach to correctly handle nested and void tags. -

Source

+

Source

----- # dompa.html @@ -90,7 +91,7 @@ Function. Transform a `html` string into a vector of coordinates indicating where an HTML node ends and begins. -

Source

+

Source

## `->nodes` ``` clojure @@ -101,7 +102,7 @@ Function. Transform a `html` string into a tree of nodes, each representing one HTML node and its children. -

Source

+

Source

----- # dompa.nodes @@ -114,19 +115,23 @@ Transform a `html` string into a tree of nodes, ## `$` ``` clojure -($ name & opts) +($ & opts) ``` Function. -Creates a new node +Creates a new node. + Children can be passed directly - strings, numbers, and other values + are automatically converted to text nodes. Nil values are filtered out. + Usage: ```clojure - ($ :div - ($ "hello world" )) + ($ :div "hello world") + ($ :div {:class "container"} "Hello, " name "!") + ($ :<> "one" "two" "three") ``` -

Source

+

Source

## `->html` ``` clojure @@ -155,7 +160,7 @@ Transform a vector of `nodes` into an HTML string. - `:track` - `:wbr` -

Source

+

Source

## `defhtml` ``` clojure @@ -166,17 +171,28 @@ Macro. Creates a new function with `name` that outputs HTML. + Optionally accepts a docstring between the name and the argument vector. + + Functions created with [`defhtml`](#dompa.nodes/defhtml) can be nested and composed with each other. + Example usage: ```clojure - (defhtml about-page [who] + (defhtml greeting [who] + ($ :span who)) + + (defhtml about-page + "Renders the about page." + [who] ($ :div - ($ "hello " who))) + "Hello, " + (greeting who))) (about-page "world") + ;;=> "
Hello, world
" ``` -

Source

+

Source

## `traverse` ``` clojure @@ -190,4 +206,14 @@ Recursively traverses given tree of `nodes` with a `traverser-fn` If the traverses function returns `nil`, the node will be removed. In any other case the node will be replaced. If you wish to keep a node unchanged, just return it as-is. -

Source

+

Source

+ +## `zip` +``` clojure + +(zip node) +``` +Function. + +Creates a zipper for given a given `node`. +

Source

diff --git a/README.md b/README.md index 9548d42..20e8360 100644 --- a/README.md +++ b/README.md @@ -144,9 +144,7 @@ You can also use fragment nodes, which are nodes with a name of `:<>` and whose (:require [dompa.nodes :refer [$ ->html]])) (->html [($ :button - ($ :<> - ($ "hello ") - ($ "world")))]) + ($ :<> "hello " "world"))]) ;;=>
hello world
``` @@ -185,6 +183,33 @@ It works seamlessly with standard Clojure functions like `map`: ;;=> "" ``` +#### Docstrings + +`defhtml` supports optional docstrings, just like `defn`: + +```clojure +(defhtml about-page + "Renders the about page for a person." + [who] + ($ :div "Hello, " who "!")) +``` + +#### Composition + +Functions created with `defhtml` can be nested and composed with each other: + +```clojure +(defhtml greeting [who] + ($ :span who)) + +(defhtml page [who] + ($ :div + (greeting who))) + +(page "world") +;;=> "
world
" +``` + **Note for ClojureScript:** Remember to use `:refer-macros` instead of `:refer` when requiring `defhtml`. ----- diff --git a/bb.edn b/bb.edn index dd486e0..13d7fa6 100644 --- a/bb.edn +++ b/bb.edn @@ -13,5 +13,6 @@ :extra-deps {io.github.borkdude/quickdoc {:git/tag "v0.2.5", :git/sha "25784ca"}} :task (exec 'quickdoc.api/quickdoc) :exec-args {:git/branch "main" - :github/repo "https://github.com/askonomm/dompa" + :github/repo "https://git.nmm.ee/asko/dompa" + :source-uri "{repo}/src/branch/{branch}/{filename}#L{row}-L{end-row}" :source-paths ["src/dompa"]}}}} diff --git a/src/dompa/nodes.cljc b/src/dompa/nodes.cljc index 7e8f769..73bc11f 100644 --- a/src/dompa/nodes.cljc +++ b/src/dompa/nodes.cljc @@ -96,17 +96,24 @@ "Creates a new function with `name` that outputs HTML. Optionally accepts a docstring between the name and the argument vector. + + Functions created with `defhtml` can be nested and composed with each other. Example usage: ```clojure + (defhtml greeting [who] + ($ :span who)) + (defhtml about-page - \"Renders the about page for the given person.\" + \"Renders the about page.\" [who] ($ :div - ($ \"hello \" who))) + \"Hello, \" + (greeting who))) (about-page \"world\") + ;;=> \"
Hello, world
\" ``` " [name & args-and-elements] @@ -182,13 +189,17 @@ (first nodes)))) (defn $ - "Creates a new node + "Creates a new node. + Children can be passed directly - strings, numbers, and other values + are automatically converted to text nodes. Nil values are filtered out. + Usage: ```clojure - ($ :div - ($ \"hello world\" )) + ($ :div \"hello world\") + ($ :div {:class \"container\"} \"Hello, \" name \"!\") + ($ :<> \"one\" \"two\" \"three\") ```" [& opts] (if (keyword? (first opts)) -- cgit v1.2.3