Class ThemeSheetPalette

java.lang.Object
com.iizix.prop.ThemeSheetPalette
public final class ThemeSheetPalette extends Object
The platform base palette read from the shipped theme sheet, iz/css/iiziThemes.css: the last step of every color resolution chain (ColorResolver.setBasePalette(PropCnr)), a container of PaletteColors named by role (ColorRoles) with a light value from the sheet's plain :root block, the default family's light member, and a dark value from its prefers-color-scheme: dark block, the same family's dark member (THEME-DESIGN.md section 4.5).

The sheet is the source of truth for the shipped themes; nothing here holds a value of its own. The reader is a literal one of the sheet's own shape - one level of at-rule, no nesting, no strings holding braces - and takes only the properties that are color roles, so the shape, type and motion tokens beside them are left alone. A role the sheet does not define for a scheme is left without that scheme's value and reported; ThemeSheetTest keeps the sheet complete before that can happen.

The whole members are read too (readSheet(String)): every declaration of every family block, the shape, type and motion tokens of ThemeTokens included, as the text the sheet holds. That is the base a custom theme (AppTheme) is composed on: the generator of the app block writes a theme's rule from its base family's member, and a theme's contrast is checked against it. The server installs it with the palette (installFromWebRoot(String)); the Designer sets its own (setSheet(Sheet)).

Author:
Christopher Mindus

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final record 
    ThemeSheetPalette.Sheet
    The family members of the sheet: for every block :root[data-iz-scheme="<family>"][data-iz-mode="<mode>"], its declarations as the sheet writes them, custom property (or color-scheme) to value text, in sheet order.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Atom
    ATOM
    The name of the base palette container: $roles.

  • Method Summary

    Modifier and Type
    Method
    Description
    static ThemeSheetPalette.Sheet
    getSheet()
    Gets the family members of the installed sheet: the base a custom theme is composed on.
    static boolean
    installFromWebRoot(String webRoot)
    Installs the platform base palette from the sheet under a web root, once per process: a later call with the same or another root does nothing.
    static List<String>
    missing(PropCnr palette)
    Gets the roles a palette leaves without a light or a dark value.
    static PropCnr
    parse(String css)
    Builds the base palette from the text of the sheet.
    static PropCnr
    parse(String css, String family)
    Builds the base palette of a family from the text of the sheet: the light and dark values of the family's explicit blocks, :root[data-iz-scheme="<family>"][data-iz-mode="light"] and the same with dark (THEME-DESIGN section 4.6), which every shipped family carries; the Designer's previews read them.
    static PropCnr
    readFamily(File file, String family)
    Reads the base palette of a family from the sheet file, for the Designer's previews.
    static ThemeSheetPalette.Sheet
    readSheet(String css)
    Reads the family members of a sheet: every top-level rule whose selector, or one of whose comma-separated selectors, is :root[data-iz-scheme="<family>"][data-iz-mode="<mode>"], with all its declarations.
    static void
    setSheet(ThemeSheetPalette.Sheet members)
    Sets the family members the custom themes are composed on: the Designer's, read under its own client root, or a test's.
    static Map<String,String>
    tokens(Map<String,String> member)
    Gets the shape, type and motion tokens of a member.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • ATOM

      public static final Atom ATOM
      The name of the base palette container: $roles.

  • Method Details

    • installFromWebRoot

      public static boolean installFromWebRoot(String webRoot)
      Installs the platform base palette from the sheet under a web root, once per process: a later call with the same or another root does nothing. A missing sheet is a warning and leaves the resolver without a base palette, so that every role reference is sent as magenta with a warning - visible, never silent.
      Parameters:
      webRoot - The web server root directory, or null when the web server is not started.
      Returns:
      true when a base palette is installed, by this call or an earlier one, false when the sheet could not be read.

    • missing

      public static List<String> missing(PropCnr palette)
      Gets the roles a palette leaves without a light or a dark value.
      Parameters:
      palette - The palette, as parse(String) builds it.
      Returns:
      The role names, as NormalText/dark, empty when every role has both.

    • readFamily

      public static PropCnr readFamily(File file, String family)
      Reads the base palette of a family from the sheet file, for the Designer's previews.
      Parameters:
      file - The sheet file.
      family - The family name, or null for the default family.
      Returns:
      The palette, or null when the sheet cannot be read, which is logged.

    • getSheet

      public static ThemeSheetPalette.Sheet getSheet()
      Gets the family members of the installed sheet: the base a custom theme is composed on.
      Returns:
      The members, or null when no sheet is installed or set.

    • setSheet

      public static void setSheet(ThemeSheetPalette.Sheet members)
      Sets the family members the custom themes are composed on: the Designer's, read under its own client root, or a test's.
      Parameters:
      members - The members, or null for none.

    • tokens

      public static Map<String,String> tokens(Map<String,String> member)
      Gets the shape, type and motion tokens of a member.
      Parameters:
      member - The declarations of a member, as ThemeSheetPalette.Sheet.member(String,String) returns them.
      Returns:
      The tokens the member defines, slug to value text, in the order of ThemeTokens.TOKENS; a token the member lacks is absent.

    • readSheet

      public static ThemeSheetPalette.Sheet readSheet(String css) throws ParseException
      Reads the family members of a sheet: every top-level rule whose selector, or one of whose comma-separated selectors, is :root[data-iz-scheme="<family>"][data-iz-mode="<mode>"], with all its declarations. The same reader serves the generated app block, whose theme rules have that form.
      Parameters:
      css - The sheet.
      Returns:
      The members, never null; a member two rules declare holds the declarations of both, the later winning, as the cascade has it.
      Throws:
      ParseException - If the sheet is not of the shape this reader knows.

    • parse

      public static PropCnr parse(String css) throws ParseException, PropException
      Builds the base palette from the text of the sheet.
      Parameters:
      css - The sheet.
      Returns:
      The palette: a PaletteColor per role the sheet defines, with the light value from the plain :root block and the dark value from the prefers-color-scheme: dark block, each present when the block defines the role's property as a color.
      Throws:
      ParseException - If the sheet is not of the shape this reader knows, or a role's value is not a color.
      PropException - If the palette cannot be built.

    • parse

      public static PropCnr parse(String css, String family) throws ParseException, PropException
      Builds the base palette of a family from the text of the sheet: the light and dark values of the family's explicit blocks, :root[data-iz-scheme="<family>"][data-iz-mode="light"] and the same with dark (THEME-DESIGN section 4.6), which every shipped family carries; the Designer's previews read them.
      Parameters:
      css - The sheet.
      family - The family name, or null for the default family's plain :root block and its prefers-color-scheme: dark fallback, as parse(String).
      Returns:
      The palette, as for parse(String).
      Throws:
      ParseException - If the sheet is not of the shape this reader knows, or a role's value is not a color.
      PropException - If the palette cannot be built.