lua: expose quarto.brand; add has_mode() function

news/changelog-1.7.md

@@ -66,7 +66,7 @@ All changes included in 1.7:
 ## `html`
 
 - ([#1325](https://github.com/quarto-dev/quarto-cli/issues/1325)): Dark Mode pages should not flash light on reload. (Nor should Light Mode pages flash dark.)
-- ([#1470](https://github.com/quarto-dev/quarto-cli/issues/1470)): `respect-user-color-scheme` enables checking the media query `prefers-color-scheme` for user dark mode preference. This is only on page load, not dynamic. Author preference still influences stylesheet order and NoJS experience. Defaults to `false`, leaving to author preference.
+- ([#1470](https://github.com/quarto-dev/quarto-cli/issues/1470)): `respect-user-color-scheme` enables checking the media query `prefers-color-scheme` for user dark mode preference. Author preference still influences stylesheet order and NoJS experience. Defaults to `false`, leaving to author preference.
 - ([#10780])(https://github.com/quarto-dev/quarto-cli/issues/10780)): improve `link-external-filter` documentation.
 - ([#11860](https://github.com/quarto-dev/quarto-cli/issues/11860)): ES6 modules that import other local JS modules in documents with `embed-resources: true` are now correctly embedded.
 - ([#12277](https://github.com/quarto-dev/quarto-cli/pull/12277)): Provide light and dark plot and table renderings with `renderings: [light,dark]`
@@ -143,6 +143,7 @@ All changes included in 1.7:
 - ([#11896](https://github.com/quarto-dev/quarto-cli/pull/11896)): fix `\f` (`{{< pagebreak >}}`) form feed character not valid in PowerPoint (`pptx`).
 - ([#12326](https://github.com/quarto-dev/quarto-cli/issues/12326)): Add `quarto.shortcode.*` API entry points for shortcode developers.
 - ([#12365](https://github.com/quarto-dev/quarto-cli/pull/12365)): `brand color` shortcode takes an optional `brandMode` second parameter, default `light`.
+- ([#12453](https://github.com/quarto-dev/quarto-cli/issues/12453)): Expose `_quarto.modules.brand` as `quarto.brand` and add `has_mode()` function.
 
 ## Lua API
 

src/resources/filters/modules/brand/brand.lua

@@ -1,6 +1,12 @@
 -- brand.lua
 -- Copyright (C) 2020-2024 Posit Software, PBC
 
+local function has_mode(brandMode)
+  assert(brandMode == 'light' or brandMode == 'dark')
+  local brand = param("brand")
+  return (brand and brand[brandMode]) ~= nil
+end
+
 local function get_color_css(brandMode, name)
   assert(brandMode == 'light' or brandMode == 'dark')
   local brand = param("brand")
@@ -57,6 +63,7 @@ local function get_logo(brandMode, name)
 end
 
 return {
+  has_mode = has_mode,
   get_color_css = get_color_css,
   get_color = get_color,
   get_typography = get_typography,

src/resources/filters/modules/import_all.lua

@@ -22,3 +22,5 @@ _quarto.modules = {
   tablecolwidths = require("modules/tablecolwidths"),
   typst = require("modules/typst")
 }
+
+quarto.brand = _quarto.modules.brand

src/resources/lua-types/quarto/brand.lua

@@ -0,0 +1,50 @@
+---@meta
+
+quarto.brand = {}
+
+--[[
+Determine whether the current document has a brand of the specified `mode`.
+]]
+---@param mode string Mode string, `light` or `dark`
+---@return boolean
+function quarto.brand.has_mode(mode) end
+
+--[[
+Get a brand color in CSS format, for the brand of the specified `mode`.
+]]
+---@param mode string Mode string, `light` or `dark`
+---@param name string Brand color name
+---@return string
+function quarto.brand.get_color_css(mode, name) end
+
+--[[
+Get a brand color in the output format, for the brand of the specified `mode`.
+]]
+---@param mode string Mode string, `light` or `dark`
+---@param name string Brand color name
+---@return string
+function quarto.brand.get_color(mode, name) end
+
+--[[
+Get typography brand options, for the brand of the specified `mode` and element `name`.
+
+The options table may have `family`, `size`, `weight`, `style`, `line-height`, `color`, 
+`background-color`, `decoration` entries, depending on the element.
+]]
+---@param mode string Mode string, `light` or `dark`
+---@param name string Typography element name
+---@return table
+function quarto.brand.get_typography(mode, name) end
+
+--[[
+Get a logo resource, for the brand of the specified `mode` and element `name`.
+
+Currently the resulting table contains `light` and/or `dark` entries,
+each a table with `path` and `alt`.
+
+In the future, we could resolve fully based on `mode`.
+]]
+---@param mode string Mode string, `light` or `dark`
+---@param name string String to be converted
+---@return table
+function quarto.brand.get_logo(mode, name) end

tests/docs/smoke-all/dark-mode/lua-brand/both-brand.qmd

@@ -0,0 +1,16 @@
+---
+format: html
+brand:
+  light: united-brand.yml
+  dark: slate-brand.yml
+filters:
+  - print-available-brands.lua
+_quarto:
+  tests:
+    html:
+      ensureFileRegexMatches:
+        -
+          - this document has a light brand
+          - this document has a dark brand
+        - []
+---

tests/docs/smoke-all/dark-mode/lua-brand/dark-brand.qmd

@@ -0,0 +1,15 @@
+---
+format: html
+brand:
+  dark: slate-brand.yml
+filters:
+  - print-available-brands.lua
+_quarto:
+  tests:
+    html:
+      ensureFileRegexMatches:
+        -
+          - this document has a dark brand
+        -
+          - this document has a light brand
+---

tests/docs/smoke-all/dark-mode/lua-brand/light-brand.qmd

@@ -0,0 +1,15 @@
+---
+format: html
+brand:
+  light: united-brand.yml
+filters:
+  - print-available-brands.lua
+_quarto:
+  tests:
+    html:
+      ensureFileRegexMatches:
+        -
+          - this document has a light brand
+        -
+          - this document has a dark brand
+---

tests/docs/smoke-all/dark-mode/lua-brand/no-brand.qmd

@@ -0,0 +1,13 @@
+---
+format: html
+filters:
+  - print-available-brands.lua
+_quarto:
+  tests:
+    html:
+      ensureFileRegexMatches:
+        - []
+        -
+          - this document has a light brand
+          - this document has a dark brand
+---

tests/docs/smoke-all/dark-mode/lua-brand/print-available-brands.lua

@@ -0,0 +1,11 @@
+function Pandoc(doc)
+  if not quarto.brand then return nil end
+  if quarto.brand.has_mode('light') then
+    doc.blocks:insert(1, pandoc.Div(quarto.utils.as_blocks("this document has a light brand")))
+  end
+  if quarto.brand.has_mode('dark') then
+    quarto.log.output('has dark')
+    doc.blocks:insert(1, pandoc.Div(quarto.utils.as_blocks("this document has a dark brand")))
+  end
+  return doc
+end

tests/docs/smoke-all/dark-mode/lua-brand/slate-brand.yml

@@ -0,0 +1,12 @@
+color:
+  background: "#282B30"
+  foreground: "#aaaaaa"
+  primary: white
+typography:
+  fonts:
+    - family: "Montserrat"
+      source: google
+  base:
+    family: "Montserrat"
+  monospace-block:
+    background-color: "#435"

tests/docs/smoke-all/dark-mode/lua-brand/united-brand.yml

@@ -0,0 +1,10 @@
+color:
+  background: "#ffffff"
+  foreground: "#333333"
+  primary: red
+typography:
+  fonts:
+    - family: "Montserrat"
+      source: google
+  base:
+    family: "Montserrat"