From 2a598acf4601ba7c1d7c90d134d57df28f451e90 Mon Sep 17 00:00:00 2001 From: annieversary Date: Sat, 9 Jul 2022 21:22:08 +0100 Subject: [PATCH] readme --- README.org | 120 ++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 91 insertions(+), 29 deletions(-) diff --git a/README.org b/README.org index 83e8812..edec6be 100644 --- a/README.org +++ b/README.org @@ -1,51 +1,113 @@ * zephyr -zephyr is a [[https://tailwindcss.com/][tailwind]]-esque css generator library - -zephyr is not a framework, it will not give you the tools to make good UI - -zephyr is a replacement for inline styles, with the added ability of pseudo-elements, pseudo-classes, and more - -zephyr is kinda somewhat a dsl for css +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 ** how to define classes -*** name and value -in the most simple case, classes have a name and a value: =name[value]=. zephyr will take this and generate the following css: +*** 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 - -note that classes without values are currently unsupported, but a high priority on the roadmap +*** non-value classes +some non-value classes are supported [[#declarations][read more here]]. +for example, =flex=, which will generate =.flex { display: flex; }= *** pseudo-classes -to use pseudo-classes such as =focus=, =hover=, and others, you provide a name, value, and the pseudo-class: =name[value]pseudo=. multiple pseudo-classes can be concatenated with commas: =m[1rem]focus,hover,odd= +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 =$=: =content['*']hover$after= will result in: +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 - -which will display an asterisk after the element, but only while hovered *** replacements -zephyr performs replacements for some common names and pseudo-classes +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)= -im not gonna list them all here, cause they're probably gonna change often - -these allow you to write =bgc[red]odd= instead of =background-color[red]nth-child(odd)= - -there's currently no way to customize the replacements, but it is planned in the future +you can customize the replacements by accessing the hashmaps in =Zephyr= and inserting/removing what you see fit *** media queries -media queries are unsupported so far, but are also on the roadmap -** faq -*** should i use this? -probably no? especially now that it's in such an early phase, but even when i "finish" implementing the base set of features, zephyr will be a very niche tool highly tailored to my needs +media queries are unsupported so far, but are on the roadmap +** 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"), +("justify-center", "justify-content:center"), +#+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"), +("bg", "background"), +("bgc", "background-color"), +#+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 +** how to use +to generate the css out of the list of classes, call =generate_classes= -you are welcome to give it a go, but unless you want to use it in exactly the same way i want to, you'll probably not have much luck -*** why did you make this? -i want the convenience of tailwind's utility classes without having to touch the hellscape that is npm +#+begin_src rust +let classes = [ + "mt[10rem]", + "color[#e20f00]", + "color[green]hover", + "content[attr(after)]$after", + "content['*']$before", + "color[red]$after", +]; -i also thought this might be a fun little project to work on, and so far it has been ! +let z = zephyr::Zephyr::new(); +let css = z.generate_classes(classes); +#+end_src + +see [[examples/html.rs][examples/html.rs]] for more information +** 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 =generate_from_inventory=. this is done by using the [[https://docs.rs/inventory/][inventory]] crate + +see [[examples/inventory.rs][examples/inventory.rs]] for more information