Cataclysm

Typesafe CSS in Scala

Cataclysm provides a typesafe representation of CSS, including properties, selectors, rules and stylesheets.

Features

• typesafe DSL for CSS
• model stylesheets in Scala
• use typed expressions for CSS attribute values
• integration with Honeycomb and Scintillate
• write CSS selectors as Scala expressions

Availability

Getting Started

Cataclysm provides several types for modeling CSS.

Selectors

CSS selectors are currently unparsed, and represented by the Selector type, which is just a wrapper for a String. The easiest way to construct a new Selector is with the sel interpolator, for example:

val selector: Selector = sel".form input[type=radio]"

In a later version, these will be parsed at compiletime to check they are well-formed.

CSS selectors are implemented using a DSL that allows values, representing CSS classes, identifiers HTML elements and pseudo-classes, to be combined with a variety of combinators, much as they are in a CSS stylesheet.

The syntax is similar to CSS, but must nevertheless be valid Scala. While this compromises familiarity with CSS syntax, there are many advantages too: the code is parsed and typechecked, so many errors can be detected earlier. And every value is an expression, which facilitates code reuse. And since selectors are algebraic expressions, with parentheses available, they can express some selectors more concisely than is possible in CSS.

The syntax mirrors CSS as much as possible, with a couple of differences. A | is used in place of CSS's ,, and the use of juxtaposition in CSS, with or without a space, is made explicit with the operators >> and & respectively. In a general context, these operators should be intuitive.

Elements are represented by Tag types from Honeycomb, and CSS classes may be specified using an interpolated string with the cls prefix, e.g. cls"hidden". Likewise DOM IDs are interpolated strings with the id prefix.

Pseudo-classes are available inside the cataclysm.pseudo package, and have the same name as their CSS equivalents, though dashed syntax is translated to camelcase. For example, first-child becomes firstChild.

CSS | Cataclysm ----------------------+--------- .myClass | cls"myClass" #domId | id"domId" table | Table (honeycomb.Table) table tr | Table >> Tr tr>td | Tr > Td td, th | Td | Th td.hide | Td&cls"hide" td+th | Td + Th td~th | Td ~ Th tr td, tr th | Tr >> (Td | Th) tr td.hide | Tr >> Td&cls"hide" tr:first-child | Tr&firstChild tr.head:first-child | Tr&cls"head"&firstChild

Note in particular that Tr >> (Td | Th) gets rewritten to the equivalent of Tr >> Td | Tr >> Th, as parentheses are not available in CSS.

Of course, identifiers like cls"hide" and id"banner"` are just values like any other, so it would be typical to first define, for example,

val hide = cls"hide"
val banner = id"banner"

and then refer to hide and banner directly in the selector. These same identifiers can be used as values for Honeycomb element attributes, for example,

Div(id = banner)(contents*)

or,

Tr(hclass = hide)(Th(heading))

Specifying attributes

CSS attributes may be added to a Selector to create a Rule by binding the selector to a Style value (typically created with the Css constructor) using the := operator. For example,

val rule: Rule = Tr >> Th := Css(margin = (1.px, 2.px, 1.px), cursor = Cursor.Pointer)

This rule would serialize to the CSS,

tr th { margin: 1px 2px 1px; cursor: pointer; }

Each named parameter takes its name from the CSS attribute, where CSS's dashed naming style (for example, animation-fill-mode) should be translated into camelcase (for example, animationFillMode).

Every CSS attribute may be transformed in this way, without exception. Only valid CSS attributes (after transformation) may be used as named parameters, and any attempt to use a nonexistent CSS attribute will produce a compile error.

For example,

val rule: Rule = sel".form input[type=radio]"(fontWeight = 600, textAlign = TextAlign.Center)

Stylesheets

A number of Rules may be combined into a single Stylesheet. The Stylesheet constructor can take repeated Rule arguments, for example:

val styles = Stylesheet(
  Form := Css(backgroundColor = colors.White),
  Form&mainForm >> Input := Css(display = Display.InlineBlock),
  rule3
)

Other directives

In addition to Rules, a Stylesheet may contain a number of other directives, such as imports and media queries.

These include:

• Keyframes
• Import

Support for others, in particular media queries, will be added in due course.

Attribute values

As much as possible, attribute values are strongly typed, which means arbitrary Scala expressions may be used for attribute values, provided they conform to a suitable type.

The process of finding the most suitable types for each attribute is an ongoing process, and different CSS attributes are gradually being migrated from using Strings to more precise types.

Additionally, arithmetic expressions involving dimensional values will use CSS's calc function where necessary, while any Scala expression is valid for an attribute value, as long as it returns a value of a suitable type.

Dimensional values

Lengths and other values use instances of the Length enumeration. This provides representations of all CSS unit types (px, pt, in, pc, cm, mm, em, ex, ch, rem, vw, vh, vmin and vmax). These are made available as extension methods on Double values.

Colors

Colours are provided by Iridescence which can represent colors in a variety of different models. Colors defined using color models which are natively supported by CSS will be embedded using that same model, while other colors will be converted automatically to SRGB.

Enumerated values

Many CSS attributes take one of a selection of enumerated possibilities. These are generally represented by an enum whose name is taken from the capitalized, camelcase name of that attribute, and whose members' names are similarly transformed.

For example, the CSS value, color-dodge for the attribute, mix-blend-mode is called, MixBlendMode.ColorDodge.

Multi-part values

Some CSS attributes, such as border, can accept multiple arguments. While these would be separated by spaces in CSS, they should be embedded in a tuple using Cataclysm. For example,

Css(margin = (1.px, 3.em))

Status

Cataclysm is classified as fledgling. For reference, Soundness projects are categorized into one of the following five stability levels:

• embryonic: for experimental or demonstrative purposes only, without any guarantees of longevity
• fledgling: of proven utility, seeking contributions, but liable to significant redesigns
• maturescent: major design decisions broady settled, seeking probatory adoption and refinement
• dependable: production-ready, subject to controlled ongoing maintenance and enhancement; tagged as version 1.0.0 or later
• adamantine: proven, reliable and production-ready, with no further breaking changes ever anticipated

Projects at any stability level, even embryonic projects, can still be used, as long as caution is taken to avoid a mismatch between the project's stability level and the required stability and maintainability of your own project.

Cataclysm is designed to be small. Its entire source code currently consists of 705 lines of code.

Building

Cataclysm will ultimately be built by Fury, when it is published. In the meantime, two possibilities are offered, however they are acknowledged to be fragile, inadequately tested, and unsuitable for anything more than experimentation. They are provided only for the necessity of providing some answer to the question, "how can I try Cataclysm?".

1. Copy the sources into your own project

   Read the fury file in the repository root to understand Cataclysm's build structure, dependencies and source location; the file format should be short and quite intuitive. Copy the sources into a source directory in your own project, then repeat (recursively) for each of the dependencies.

   The sources are compiled against the latest nightly release of Scala 3. There should be no problem to compile the project together with all of its dependencies in a single compilation.

2. Build with Wrath

   Wrath is a bootstrapping script for building Cataclysm and other projects in the absence of a fully-featured build tool. It is designed to read the fury file in the project directory, and produce a collection of JAR files which can be added to a classpath, by compiling the project and all of its dependencies, including the Scala compiler itself.

   Download the latest version of wrath, make it executable, and add it to your path, for example by copying it to /usr/local/bin/.

   Clone this repository inside an empty directory, so that the build can safely make clones of repositories it depends on as peers of cataclysm. Run wrath -F in the repository root. This will download and compile the latest version of Scala, as well as all of Cataclysm's dependencies.

   If the build was successful, the compiled JAR files can be found in the .wrath/dist directory.

Contributing

Contributors to Cataclysm are welcome and encouraged. New contributors may like to look for issues marked beginner.

We suggest that all contributors read the Contributing Guide to make the process of contributing to Cataclysm easier.

Please do not contact project maintainers privately with questions unless there is a good reason to keep them private. While it can be tempting to repsond to such questions, private answers cannot be shared with a wider audience, and it can result in duplication of effort.

Author

Cataclysm was designed and developed by Jon Pretty, and commercial support and training on all aspects of Scala 3 is available from Propensive OÜ.

Name

Cataclysm takes its name from the sweeping inundation (typical of a waterfall, or cascade) since it represents Cascading Style Sheets.

In general, Soundness project names are always chosen with some rationale, however it is usually frivolous. Each name is chosen for more for its uniqueness and intrigue than its concision or catchiness, and there is no bias towards names with positive or "nice" meanings—since many of the libraries perform some quite unpleasant tasks.

Names should be English words, though many are obscure or archaic, and it should be noted how willingly English adopts foreign words. Names are generally of Greek or Latin origin, and have often arrived in English via a romance language.

Logo

The logo shows a cresting wave, cataclysmic in nature.

License

Cataclysm is copyright © 2024 Jon Pretty & Propensive OÜ, and is made available under the Apache 2.0 License.