Package org.apache.juneau.console

Class Theme.Builder

java.lang.Object
org.apache.juneau.console.Theme.Builder
Enclosing class:
Theme
public static final class Theme.Builder extends Object
Builder for Theme.

  • Method Details

    • token

      public Theme.Builder token(String name, String value)
      Adds (or overrides) a single CSS custom-property token.

      The value may be either a literal or a var(--jc-name) reference to another known token:

      • A literal is validated eagerly here by CssValueGrammar's accept-known-safe allowlist grammar after normalization (trim → reject C0/C1/DEL → strip comments → reject url( in any spelling → grammar).
      • A value that, after that same normalization belt, matches var(--jc-name) is recognized as a reference and stored unresolved — it is resolved to a concrete literal at build() time (its target may not be defined yet, e.g. a forward reference). var() is never a CssValueGrammar value shape; it is Theme-layer syntax recognized one layer above the grammar.
      Escaping happens later, at emission time, via CssValueEscaper (see ConsoleChromeMixin).

      A declared name in the reserved --jc-chrome-* namespace that Theme.OPEN does not already declare is rejected.

      Parameters:
      name - The token name. Must not be null and must match ^--jc-[a-z0-9-]+$.
      value - The CSS value — a literal, or a var(--jc-name) reference.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If the name is not in the legal shape (full-string String.matches(...), not find(...) — "--jc-foo;--bar" must REJECT even though "--jc-foo" matches as a leading substring), if the value contains a control character or a url( production, or if the value is neither a var(--jc-name) reference nor one of the allowlisted CSS value shapes. A reference whose target is unknown, cyclic, or too deeply chained is instead reported at build() time.

    • dark

      public Theme.Builder dark(String name, String value)
      Adds (or overrides) a dark accent token: a literal applied on top of the shared dark neutral layer when the page is in the dark scheme.

      The name and value go through the same guards as token(String, String), with one difference: the value must be a literal. A var() reference is rejected, because the only thing it could resolve against is the light palette, which would bake the wrong value into the dark scheme.

      Parameters:
      name - The token name. Must match ^--jc-[a-z0-9-]+$.
      value - The CSS literal.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If the name is malformed or in the reserved --jc-chrome-* namespace without being a Theme.OPEN token, or if the value is a var() reference or is not one of the allowlisted CSS value shapes.

    • alias

      public Theme.Builder alias(String name, String target)
      Declares an alias token: a name whose value is a live reference to another --jc-* token.

      The target must be exactly one var(--jc-name) reference, with no fallback, no surrounding value and no second reference. It is stored after the shared normalization belt (trim and comment strip, with control characters rejected on the raw value) and emitted verbatim. Nothing dangerous is representable in that shape, so an alias needs no escaper. A literal belongs in token(String, String). A var() given to token() is resolved to its literal at build time; one given here is not.

      A name may be declared by only one channel: build() rejects a name given to both token() and alias(), in either order.

      Example:

      // Follows --jc-card-bg live, including any later override of it. builder.alias("--jc-tab-bar-bg", "var(--jc-card-bg)"); // Rejected: a literal belongs in token(), not alias(). builder.alias("--jc-tab-bar-bg", "#fff");

      A declared name in the reserved --jc-chrome-* namespace that Theme.OPEN does not already declare is rejected.

      Parameters:
      name - The alias name. Must match ^--jc-[a-z0-9-]+$.
      target - The reference. Must be a single var(--jc-name).
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If the name or the target is malformed.

    • build

      public Theme build()
      Builds the immutable Theme, resolving every var(--jc-name) reference to a concrete literal.

      Resolution scope is this builder's own tokens, shadowing Theme.OPEN's tokens (exact shadowing: a name defined on this builder wins outright, even if resolving that entry then fails — there is no silent fall-through to Theme.OPEN's value for a shadowed name). Resolution runs on a copy of the token map, so a failed build() leaves this builder unchanged and retryable.

      Rejects a name declared by both token(String, String) and alias(String, String).

      Returns:
      A new Theme whose every token value is a resolved six-shape literal (the substring var( appears in none of them).
      Throws:
      IllegalArgumentException - If a reference names an unknown token, forms a cycle (the message carries the cycle path), or exceeds the resolution depth cap.