From db380666dbac10143eef726f1648544a367dba80 Mon Sep 17 00:00:00 2001 From: Thomas Hintz Date: Tue, 20 Jan 2026 06:56:33 -0800 Subject: [PATCH] Updating readme --- README.org | 38 +++++++++++++++++++++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/README.org b/README.org index 67a8d8e..107ce4b 100644 --- a/README.org +++ b/README.org @@ -227,7 +227,43 @@ These will need to be installed via the ~chicken-install~ command. This is a CHICKEN Scheme library that also needs to be installed but it is not available via the ~chicken-install~ repository as I wrote it for this project and I have not published it externally yet. You can -get the project here: [[https://code.thintz.com/tjhintz/html-widgets][https://code.thintz.com/tjhintz/html-widgets]] +get the project here: [[https://code.thintz.com/tjhintz/html-widgets][code.thintz.com/tjhintz/html-widgets]] After downloading the project, you can install it by ~cd~ to the directory it is in and then running ~chicken-install~. + +** Architecture + +The webapp was designed to be very simple. Pages and handlers are +based on the [[https://schematra.com/][Schematra]] CHICKEN Scheme library (Chiccup is NOT +used). Currently, there are no external dependencies other than +docker, which is used to run postgres in development as well as +generate ssh keys for users in production. There is no JavaScript or +styling libraries. The webapp is built as HTML pages with forms. + +The entry point for the webapp is ~src/nassella.scm~. + +*** HTML Widgets + +The core of page markup is created with the html-widgets library which +provides the ~define-widget~ function. This would be similar to a +"component" in something like React. It allows defining properties of +a widget (component) as well as a name and default values. It also +handles style transforms, detailed in the next section. + +*** Styling + +All styling is done via ~style~ attributes on HTML elements. This is +handled internally by the html-widgets library. The html-widgets +library will extract all of the styles into a CSS stylesheet and +replace the ~style~ attributes with a corresponding, auto-generated, +CSS class name attribute. Nothing is needed to define or manage styles +other than to set them directly via an HTML ~style~ attribute. + +Shared styling values, like colors, are defined in the *style-tokens* +global variable. It is a tree of style tokens (similar to +[[https://css-tricks.com/what-are-design-tokens/][Design Tokens]]). ~nassella.scm~ also includes some functions to make it +easy for widgets to fetch style values. The most common being ~$~ +which allows getting a style token value based on a dotted symbol or a +symbol list ~($ 'color.primary.contrast)~ or ~($ '(color primary +contrast)~