Add custom theme support for styles

Author: akclace

docs/content/docs/App/Styling.md

@@ -42,7 +42,7 @@ To use TailwindCSS, in app settings, add
 
 Tailwind CSS works by scanning the HTML files for class names, generating the corresponding styles and then writing them to a static CSS file. A watcher process is started when an app using Tailwind is loaded in dev mode. The output of the watcher is written to `static/gen/css/style.css` file. This file is automatically included as part of the `openrun_gen_import` template.
 
-To ensure that the tailwind watcher is started, the tailwind CLI needs to be installed manually. With the default Tailwind 4/daisyUI 5 config, install the Tailwind CLI and daisyUI npm packages, for example `npm install -D tailwindcss @tailwindcss/cli daisyui`. The [standalone CLI](https://tailwindcss.com/blog/standalone-cli) can also be used when it includes the required plugins.
+To ensure that the tailwind watcher is started, the tailwind CLI needs to be installed manually. The [standalone CLI](https://tailwindcss.com/blog/standalone-cli) is the easiest option: no npm or node_modules setup is required. The npm packages (`npm install -D tailwindcss @tailwindcss/cli daisyui`, with `npx tailwindcss` as the command) also work.
 
 The OpenRun server config file has the following entries:
 
@@ -72,6 +72,40 @@ To use [DaisyUI](https://daisyui.com/), in app settings, add
     style=ace.style("daisyui", themes=["dark"])
 ```
 
-Change to the preferred [theme](https://daisyui.com/docs/themes/). DaisyUI is a good option to use to get great default styling for components, with the full flexibility of Tailwind. OpenRun takes care of creating the config files. With `tailwind_version = 4`, OpenRun writes the daisyUI plugin and theme list into `style/input.css` using the daisyUI 5 `@plugin "daisyui"` syntax. Using the CDN version of DaisyUI or Tailwind is not recommended since that will cause the style files to be large.
+Change to the preferred [theme](https://daisyui.com/docs/themes/). DaisyUI is a good option to use to get great default styling for components, with the full flexibility of Tailwind. OpenRun takes care of creating the config files. With `tailwind_version = 4`, OpenRun writes the daisyUI plugin and theme list into `style/input.css` using the daisyUI 5 `@plugin` syntax. Using the CDN version of DaisyUI or Tailwind is not recommended since that will cause the style files to be large.
+
+The standalone tailwind CLI does not bundle daisyUI. Since a `tailwindcss_command` is configured, OpenRun automatically downloads the prebundled daisyUI plugin (a single `daisyui.js` file, no node_modules required) into the app's work directory and references it from the generated `style/input.css`. The download happens once and is cached across server restarts. The download location can be overridden (for example to an internal mirror) with:
+
+```toml {filename="openrun.toml"}
+[system]
+daisyui_url = "https://internal.example.com/daisyui.js"
+```
+
+If the download fails (for example, no network access), OpenRun falls back to the `@plugin "daisyui"` node_modules based reference, which requires `npm install daisyui` such that daisyui is resolvable from the app work directory.
 
 If using [Actions]({{< ref "/docs/actions/" >}}), DaisyUI styles are automatically included. The themes can be customized using the `light` and `dark` property.
+
+### Custom Themes
+
+With `tailwind_version = 4`, fully custom [daisyUI themes](https://daisyui.com/docs/themes/#how-to-add-a-new-custom-theme) can be defined with the `custom_themes` property: a dict of theme name to the theme's CSS properties. Setting `light`/`dark` to a custom theme name makes it the default for that color scheme:
+
+```python {filename="app.star"}
+    style=ace.style("daisyui",
+                    light="mybrand-light",
+                    dark="mybrand-dark",
+                    custom_themes={
+                        "mybrand-light": {
+                            "color-scheme": "light",
+                            "--color-base-100": "#ffffff",
+                            "--color-primary": "#007700",
+                            # ... other daisyUI theme variables
+                        },
+                        "mybrand-dark": {
+                            "color-scheme": "dark",
+                            "--color-base-100": "#17221a",
+                            "--color-primary": "#00c200",
+                        },
+                    })
+```
+
+OpenRun generates a daisyUI theme plugin block per custom theme in `style/input.css` (using the prebundled daisyUI theme plugin, downloaded automatically like the main plugin; `daisyui_theme_url` overrides the download location). Custom themes can be mixed with the bundled theme names in `themes`. When only custom themes are used, the bundled themes are disabled, keeping the generated CSS small.

internal/app/apptype/builtins.go

@@ -183,18 +183,24 @@ func createFragmentBuiltin(_ *starlark.Thread, _ *starlark.Builtin, args starlar
 func createStyleBuiltin(_ *starlark.Thread, _ *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
 	var library, light, dark starlark.String
 	var themes *starlark.List
+	var customThemes *starlark.Dict
 	var disableWatcher starlark.Bool
-	if err := starlark.UnpackArgs(FRAGMENT, args, kwargs, "library", &library, "themes?", &themes, "disable_watcher?", &disableWatcher, "light?", &light, "dark?", &dark); err != nil {
+	if err := starlark.UnpackArgs(FRAGMENT, args, kwargs, "library", &library, "themes?", &themes, "disable_watcher?", &disableWatcher,
+		"light?", &light, "dark?", &dark, "custom_themes?", &customThemes); err != nil {
 		return nil, fmt.Errorf("error unpacking style args: %w", err)
 	}
 
 	if themes == nil {
 		themes = starlark.NewList([]starlark.Value{})
 	}
+	if customThemes == nil {
+		customThemes = starlark.NewDict(0)
+	}
 
 	fields := starlark.StringDict{
 		"library":         library,
 		"themes":          themes,
+		"custom_themes":   customThemes,
 		"disable_watcher": disableWatcher,
 		"light":           cmp.Or(light, DEFAULT_DAISYUI_LIGHT_THEME),
 		"dark":            cmp.Or(dark, DEFAULT_DAISYUI_DARK_THEME),

internal/app/dev/appdev.go

@@ -7,6 +7,7 @@ import (
 	"bytes"
 	"embed"
 	"encoding/json"
+	"fmt"
 	"io"
 	"net/http"
 	"slices"
@@ -97,6 +98,36 @@ func (a *AppDev) downloadFile(url string, appFS *appfs.WritableSourceFs, path st
 	return nil
 }
 
+// downloadWorkFile downloads the url into the app work directory, unless it was
+// already downloaded for this app in the current server session.
+func (a *AppDev) downloadWorkFile(url string, path string) error {
+	if alreadyDone, ok := a.filesDownloaded[url]; ok && slices.Contains(alreadyDone, path) {
+		a.Trace().Msgf("File %s:%s already downloaded", url, path)
+		return nil
+	}
+
+	a.Info().Msgf("Downloading %s into %s", url, path)
+
+	resp, err := http.Get(url)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close() //nolint:errcheck
+	if resp.StatusCode != http.StatusOK {
+		return fmt.Errorf("error downloading %s : status %d", url, resp.StatusCode)
+	}
+
+	var buf bytes.Buffer
+	if _, err = io.Copy(&buf, resp.Body); err != nil {
+		return err
+	}
+	if err = a.workFS.Write(path, buf.Bytes()); err != nil {
+		return err
+	}
+	a.filesDownloaded[url] = append(a.filesDownloaded[url], path)
+	return nil
+}
+
 // SetupJsLibs sets up the js libraries for the app.
 func (a *AppDev) SetupJsLibs() error {
 	hasHtmx := false

internal/app/dev/styling.go

@@ -4,6 +4,8 @@
 package dev
 
 import (
+	"cmp"
+	"crypto/sha256"
 	"fmt"
 	"os"
 	"os/exec"
@@ -22,8 +24,35 @@ import (
 
 const (
 	STYLE_FILE_PATH = "static/gen/css/style.css"
+
+	// The standalone tailwindcss v4 CLI does not bundle daisyui; @plugin "daisyui"
+	// is resolved through node_modules, walking up from the input.css directory.
+	// To avoid requiring any node_modules setup, the prebundled daisyui plugin is
+	// downloaded next to the generated input.css and referenced by relative path.
+	// The download urls are configured with daisyui_url and daisyui_theme_url in
+	// the [system] server config.
+	DAISYUI_MODULE_REF       = "daisyui"       // node_modules based plugin reference
+	DAISYUI_THEME_MODULE_REF = "daisyui/theme" // node_modules based theme plugin reference
 )
 
+// DaisyUIPluginFile is the work dir file name for the prebundled daisyui
+// plugin downloaded from url. The name includes a hash of the url so that a
+// url (version) change triggers a fresh download.
+func DaisyUIPluginFile(url string) string {
+	return pluginFileName("daisyui", url)
+}
+
+// DaisyUIThemePluginFile is the work dir file name for the prebundled daisyui
+// theme plugin (used for custom themes) downloaded from url.
+func DaisyUIThemePluginFile(url string) string {
+	return pluginFileName("daisyui-theme", url)
+}
+
+func pluginFileName(prefix, url string) string {
+	hash := sha256.Sum256([]byte(url))
+	return fmt.Sprintf("%s-%x.js", prefix, hash[:4])
+}
+
 const (
 	TailwindCSS types.StyleType = "tailwindcss"
 	DaisyUI     types.StyleType = "daisyui"
@@ -35,17 +64,27 @@ const (
 // when the App is loaded. It keeps track of the watcher process required to rebuild the
 // CSS file when the tailwind/daisy config changes. The reload mutex lock in App is used to
 // ensure only one call to the watcher is done at a time, no locking is implemented in AppStyle
+// CustomTheme is a daisyui custom theme: the theme name and its CSS
+// properties (color-scheme, --color-* etc), in declaration order
+type CustomTheme struct {
+	Name  string
+	Props [][2]string
+}
+
 type AppStyle struct {
-	appId          types.AppId
-	library        types.StyleType
-	themes         []string
-	libraryUrl     string
-	DisableWatcher bool
-	watcher        *exec.Cmd
-	watcherState   *WatcherState
-	watcherStdout  *os.File
-	Light          string
-	Dark           string
+	appId                 types.AppId
+	library               types.StyleType
+	themes                []string
+	customThemes          []CustomTheme
+	libraryUrl            string
+	DisableWatcher        bool
+	watcher               *exec.Cmd
+	watcherState          *WatcherState
+	watcherStdout         *os.File
+	Light                 string
+	Dark                  string
+	daisyUIPluginRef      string // plugin reference to use in the generated input.css
+	daisyUIThemePluginRef string // theme plugin reference for custom themes
 }
 
 // WatcherState is the state of the watcher process as of when it was last started.
@@ -93,6 +132,9 @@ func (s *AppStyle) Init(appId types.AppId, appDef *starlarkstruct.Struct) error
 	if disableWatcher, err = apptype.GetBoolAttr(styleDef, "disable_watcher"); err != nil {
 		return err
 	}
+	if s.customThemes, err = getCustomThemes(styleDef); err != nil {
+		return err
+	}
 	themes = append(themes, s.Light, s.Dark)
 	slices.Sort(themes)
 	themes = slices.Compact(themes)
@@ -122,6 +164,50 @@ func (s *AppStyle) Init(appId types.AppId, appDef *starlarkstruct.Struct) error
 	return nil
 }
 
+// getCustomThemes reads the custom_themes style attribute: a dict of theme
+// name to a dict of CSS properties. Declaration order is preserved so the
+// generated input.css is stable across reloads.
+func getCustomThemes(styleDef *starlarkstruct.Struct) ([]CustomTheme, error) {
+	customAttr, err := styleDef.Attr("custom_themes")
+	if err != nil || customAttr == nil {
+		return nil, nil // custom_themes not defined
+	}
+
+	customDict, ok := customAttr.(*starlark.Dict)
+	if !ok {
+		return nil, fmt.Errorf("custom_themes must be a dict of theme name to theme properties")
+	}
+
+	customThemes := make([]CustomTheme, 0, customDict.Len())
+	for _, item := range customDict.Items() {
+		name, ok := item[0].(starlark.String)
+		if !ok || name.GoString() == "" {
+			return nil, fmt.Errorf("custom_themes keys must be non-empty theme name strings")
+		}
+
+		propsDict, ok := item[1].(*starlark.Dict)
+		if !ok {
+			return nil, fmt.Errorf("custom theme %s must be a dict of CSS properties", name.GoString())
+		}
+
+		theme := CustomTheme{Name: name.GoString(), Props: make([][2]string, 0, propsDict.Len())}
+		for _, prop := range propsDict.Items() {
+			propName, ok := prop[0].(starlark.String)
+			if !ok || propName.GoString() == "" {
+				return nil, fmt.Errorf("custom theme %s property names must be non-empty strings", theme.Name)
+			}
+			propValue, ok := prop[1].(starlark.String)
+			if !ok {
+				return nil, fmt.Errorf("custom theme %s property %s value must be a string", theme.Name, propName.GoString())
+			}
+			theme.Props = append(theme.Props, [2]string{propName.GoString(), propValue.GoString()})
+		}
+		customThemes = append(customThemes, theme)
+	}
+
+	return customThemes, nil
+}
+
 // Setup sets up the style library for the app. This is called when the app is reloaded.
 func (s *AppStyle) Setup(dev *AppDev) error {
 	switch s.library {
@@ -131,6 +217,20 @@ func (s *AppStyle) Setup(dev *AppDev) error {
 	case TailwindCSS:
 		fallthrough
 	case DaisyUI:
+		if s.library == DaisyUI {
+			if tailwindVersion(dev.systemConfig) == types.TailwindVersionLegacy {
+				if len(s.customThemes) > 0 {
+					return fmt.Errorf("custom_themes require tailwind_version %d", types.TailwindVersionCurrent)
+				}
+			} else {
+				url := dev.systemConfig.DaisyUIURL
+				s.daisyUIPluginRef = s.resolvePluginFile(dev, DaisyUIPluginFile(url), url, DAISYUI_MODULE_REF)
+				if len(s.customThemes) > 0 {
+					themeUrl := dev.systemConfig.DaisyUIThemeURL
+					s.daisyUIThemePluginRef = s.resolvePluginFile(dev, DaisyUIThemePluginFile(themeUrl), themeUrl, DAISYUI_THEME_MODULE_REF)
+				}
+			}
+		}
 		// Generate the tailwind/daisyui config files
 		return s.setupTailwindConfig(dev.Config.Routing.TemplateLocations, dev.sourceFS, dev.workFS, tailwindVersion(dev.systemConfig))
 	case Other:
@@ -251,17 +351,49 @@ func (s *AppStyle) legacyDaisyThemes() string {
 	return fmt.Sprintf("  daisyui: { themes: [%s], },", quotedThemes.String())
 }
 
+// resolvePluginFile returns the plugin reference to use in the generated
+// input.css. When a tailwind CLI is configured, the prebundled plugin file is
+// downloaded into the app work dir, next to input.css (cached across
+// restarts), so that the standalone tailwindcss CLI works without requiring
+// node_modules. Falls back to the node_modules based reference if the
+// download fails.
+func (s *AppStyle) resolvePluginFile(dev *AppDev, fileName, url, moduleRef string) string {
+	if strings.TrimSpace(dev.systemConfig.TailwindCSSCommand) == "" || url == "" {
+		// No watcher will run (or no download url is configured); keep the
+		// node_modules based reference for externally run tailwind builds
+		return moduleRef
+	}
+
+	localRef := "./" + fileName
+	filePath := path.Join("style", fileName)
+	if fi, err := dev.workFS.Stat(filePath); err == nil && fi.Size() > 0 {
+		return localRef
+	}
+
+	if err := dev.downloadWorkFile(url, filePath); err != nil {
+		dev.Warn().Err(err).Msgf("Error downloading daisyui plugin from %s, falling back to node_modules resolution", url)
+		return moduleRef
+	}
+	return localRef
+}
+
 func (s *AppStyle) daisyUIPlugin() string {
 	if s.library != DaisyUI {
 		return ""
 	}
 
-	if len(s.themes) == 0 {
-		return `@plugin "daisyui";`
+	customNames := map[string]bool{}
+	for _, theme := range s.customThemes {
+		customNames[theme.Name] = true
 	}
 
+	// Custom themes are excluded from the bundled themes list, they are
+	// defined through the theme plugin instead
 	themes := make([]string, 0, len(s.themes))
 	for _, theme := range s.themes {
+		if customNames[theme] {
+			continue
+		}
 		themeConfig := theme
 		if theme == s.Light {
 			themeConfig += " --default"
@@ -272,9 +404,34 @@ func (s *AppStyle) daisyUIPlugin() string {
 		themes = append(themes, themeConfig)
 	}
 
-	return fmt.Sprintf(`@plugin "daisyui" {
+	pluginRef := cmp.Or(s.daisyUIPluginRef, DAISYUI_MODULE_REF)
+	var buf strings.Builder
+	if len(themes) > 0 {
+		fmt.Fprintf(&buf, `@plugin "%s" {
 	  themes: %s;
-	}`, strings.Join(themes, ", "))
+	}`, pluginRef, strings.Join(themes, ", "))
+	} else if len(s.customThemes) > 0 {
+		// Only custom themes are used, disable the bundled themes
+		fmt.Fprintf(&buf, `@plugin "%s" {
+	  themes: false;
+	}`, pluginRef)
+	} else {
+		fmt.Fprintf(&buf, `@plugin "%s";`, pluginRef)
+	}
+
+	themePluginRef := cmp.Or(s.daisyUIThemePluginRef, DAISYUI_THEME_MODULE_REF)
+	for _, theme := range s.customThemes {
+		fmt.Fprintf(&buf, "\n\t@plugin \"%s\" {\n", themePluginRef)
+		fmt.Fprintf(&buf, "\t  name: \"%s\";\n", theme.Name)
+		fmt.Fprintf(&buf, "\t  default: %t;\n", theme.Name == s.Light)
+		fmt.Fprintf(&buf, "\t  prefersdark: %t;\n", theme.Name == s.Dark)
+		for _, prop := range theme.Props {
+			fmt.Fprintf(&buf, "\t  %s: %s;\n", prop[0], prop[1])
+		}
+		buf.WriteString("\t}")
+	}
+
+	return buf.String()
 }
 
 func sourceDirectives(contentList string) string {

internal/app/tests/app_test_helper.go

@@ -32,6 +32,10 @@ func CreateDevModeTestAppTailwindVersion(logger *types.Logger, fileData map[stri
 	return CreateTestAppIntSystemConfig(logger, "/test", "", fileData, true, nil, nil, nil, "app_dev_testapp", types.AppSettings{}, nil, nil, nil, systemConfig)
 }
 
+func CreateDevModeTestAppSystemConfig(logger *types.Logger, fileData map[string]string, systemConfig types.SystemConfig) (*app.App, *appfs.WorkFs, error) {
+	return CreateTestAppIntSystemConfig(logger, "/test", "", fileData, true, nil, nil, nil, "app_dev_testapp", types.AppSettings{}, nil, nil, nil, systemConfig)
+}
+
 func CreateTestApp(logger *types.Logger, fileData map[string]string) (*app.App, *appfs.WorkFs, error) {
 	return CreateTestAppInt(logger, "/test", "", fileData, false, nil, nil, nil, "app_prd_testapp", types.AppSettings{}, nil, nil, nil)
 }