skzephyr/README.org

* zephyr
zephyr is a [[https://tailwindcss.com/][tailwind]]-inspired css generator dsl. it acts as a replacement for inline styles, with the added ability of pseudo-elements, pseudo-classes, and more

[[https://versary.town/zephyr/][playground]]

** how to use
*** as a library
to generate the css out of the list of classes, call =Zephyr::generate_classes=

#+begin_src rust
let classes = [
    "mt[10rem]",
    "color[#e20f00]",
    "color[green]hover",
    "content[attr(after)]$after",
    "content['*']$before",
    "color[red]$after",
];

let z = zephyr::Zephyr::new();
let css = z.generate_classes(classes);
#+end_src

see [[examples/html.rs][examples/html.rs]] for a more detailed usage example
*** as a cli program
first go into =zephyr-cli= and run =cargo install --path .=. =zephry-cli= will now be available. you can use it like so: =zephyr-cli . -wr -o my.css=
** how to define classes
*** property and value
in the most simple case, classes have a property and a value: =name[value]=. zephyr will take this and generate the following css:

#+begin_src css
.name\[value\] {
    name: value;
}
#+end_src
*** non-value classes
some non-value classes are supported [[#declarations][read more here]].
for example, =flex=, which will generate =.flex { display: flex; }=
*** pseudo-classes
zephyr supports pseudo-classes:
**** with values
when using pseudo-classes with values, simply write the pseudo-class you want after the closing square bracket, like so: =name[value]pseudo=.
multiple pseudo-classes can be concatenated with commas: =m[1rem]focus,hover,odd=
**** without values
for non-value classes, the format used is =name|pseudo=.
multiple pseudo-classes can be concatenated with commas: =flex-row|focus,hover,odd=
*** pseudo-elements
pseudo-elements like =::before= or =::after= are also supported. they are delimited by =$=.
for example, =content['*']hover$after= will result in:

#+begin_src css
.content\[\'\*\'\]hover\$after:hover::after {
    content: '*';
}
#+end_src
*** replacements
zephyr performs replacements for some common properties, values, pseudo-classes, and pseudo-elements. they are listed under [[#defaults][defaults]]. these allow you to write =bgc[red]odd= instead of =background-color[red]nth-child(odd)=

you can customize the replacements by accessing the hashmaps in =Zephyr= and inserting/removing what you see fit
*** spaces
any underscores will be replaced by spaces (eg: =border[1px_solid_black] -> border: 1px solid black=). this is because you can't have spaces in a class name, and underscores are not common in css values (as far as i'm aware)

if you would like to use underscores in a value, please use [[#literals][literals]]
*** literals
if you want no replacements to be applied, use curly brackets instead of square brackets

=border{1px_solid_black} -> border: 1px_solid_black=
*** variables
there's a shorthand syntax for referring to css variables, by using parenthesis instead of square brackets

=bg(my-bg-color) -> background: var(--my-bg-color)=
*** responsive modifiers
responsive modifiers are written the same way pseudo-classes are. options are =sm=, =md=, =lg=, =xl=, =xxl=

#+caption:  sizes
|-----+-------------------|
| sm  | min-width: 640px  |
| md  | min-width: 768px  |
| lg  | min-width: 1024px |
| xl  | min-width: 1280px |
| xxl | min-width: 1536px |

classes with a responsive modifier apply on that size and up. you can use =<lg= to apply on all sizes strictly smaller than =lg=, or =@xl= to apply exactly on =xl=
** defaults
these are the current default values, lifted straight from the code.
you are free to add more by accessing the hashmaps in =Zephyr=
*** declarations
these are the non-value classes:
#+begin_src rust
("flex", "display:flex"),
("flex-row", "display:flex;flex-direction:row"),
("flex-col", "display:flex;flex-direction:column"),
("items-center", "align-items:center"),
("items-start", "align-items:flex-start"),
("items-end", "align-items:flex-end"),
("justify-center", "justify-content:center"),
("justify-between", "justify-content:space-between"),
("justify-evenly", "justify-content:space-evenly"),
("text-left", "text-align:left"),
("text-right", "text-align:right"),
#+end_src
*** properties
#+begin_src rust
("w", "width"),
("h", "height"),
("m", "margin"),
("mt", "margin-top"),
("mb", "margin-bottom"),
("ml", "margin-left"),
("mr", "margin-right"),
("p", "padding"),
("pt", "padding-top"),
("pb", "padding-bottom"),
("pl", "padding-left"),
("pr", "padding-right"),
("c", "color"),
("bg", "background"),
("bgc", "background-color"),
("tt", "text-transform"),
("td", "text-decoration"),
("fw", "font-weight"),
("ff", "font-family"),
("fs", "font-size"),
#+end_src
*** values
#+begin_src rust
("full", "100%"),
#+end_src
*** pseudo-classes
#+begin_src rust
("odd", "nth-child(odd)"),
("even", "nth-child(even)"),
("first", "first-child"),
("last", "last-child"),
("only", "only-child"),
#+end_src
*** pseudo-elements
#+begin_src rust
("ph", "placeholder"),
#+end_src
*** specials
these are for property-value classes which need to output multiple declarations or need to do some processing to the value
#+begin_src rust
special!("mx", val, "margin-left:{val};margin-right:{val};"),
special!("my", val, "margin-top:{val};margin-bottom:{val};"),
special!("px", val, "padding-left:{val};padding-right:{val};"),
special!("py", val, "padding-top:{val};padding-bottom:{val};"),
#+end_src
** inventory
by activating the =inventory= feature, you can register classes from different parts of your application, and then generate them all with a single call to =Zephyr::generate_from_inventory=. this is done by using the [[https://docs.rs/inventory/][inventory]] crate

you can register the classes you use with =register_class!("mt[10rem]");=

see [[examples/inventory.rs][examples/inventory.rs]] for more information