diff options
| author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-09-03 07:47:33 +0000 |
|---|---|---|
| committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-09-03 07:47:33 +0000 |
| commit | 39bf3544d4064a528a85c21a9069a9cae364a6c1 (patch) | |
| tree | aa318bfe1e7816ba9492aff0cdd2454d278f5836 | |
| parent | Adding upstream version 0.45+dfsg. (diff) | |
| download | jinjax-39bf3544d4064a528a85c21a9069a9cae364a6c1.tar.xz jinjax-39bf3544d4064a528a85c21a9069a9cae364a6c1.zip | |
Adding upstream version 0.46.upstream/0.46
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
125 files changed, 8421 insertions, 71 deletions
diff --git a/benchmark/benchmark.py b/benchmark/benchmark.py index 09a7447..b939952 100644 --- a/benchmark/benchmark.py +++ b/benchmark/benchmark.py @@ -3,6 +3,7 @@ from pathlib import Path from fastapi.templating import Jinja2Templates from jinja2 import Environment, FileSystemLoader + from jinjax import Catalog @@ -72,7 +73,7 @@ def print_separator(): if __name__ == "__main__": - print(f"Benchmarking...\n") + print("Benchmarking...\n") time_jinja = timeit.timeit(render_jinja, number=number) time_fastapi = timeit.timeit(render_fastapi, number=number) diff --git a/docs/components/Copyright.jinja b/docs/components/Copyright.jinja new file mode 100644 index 0000000..473b66b --- /dev/null +++ b/docs/components/Copyright.jinja @@ -0,0 +1,4 @@ +<div {{ attrs.render(class="copy") }}> + <p>Website © <a href="https://jpscaletti.com">Juan-Pablo Scaletti</a>.</p> + <p>JinjaX and the documentation text licensed under the MIT license.</p> +</div>
\ No newline at end of file diff --git a/docs/components/Home.jinja b/docs/components/Home.jinja new file mode 100644 index 0000000..045150b --- /dev/null +++ b/docs/components/Home.jinja @@ -0,0 +1,154 @@ +<div class="homepage"> + <section class="hero"> + <h1>JinjaX</h1> + <h2> + Super + <span class="g1">components powers</span> + for your + <span class="g2">Jinja templates</span> + </h2> + </section> + + <section class="code"> + <div class="stack"> + <div class="panel"> + <h2>Before: chaos!</h2> +{% filter markdown %}{% raw %} +```html+jinja +{% extends "layout.html" %} +{% block title %}My title{% endblock %} + +{% from "bunch_of_macros.html" + import card_macro, another_macro %} + +{% block content -%} + <div> + <h2>Hello {{ mistery or "World?" }}</h2> + <div> + {% call card_macro(div="So verbose") %} + {% for product in products %} + {{ another_macro(product) }} + {% endfor %} + {% endcall %} + </div> + </div> + {% with items=products %} + {% include "snippets/pagination.html" %} + {% endwith %} +{%- endblock %} +``` +{% endraw %}{% endfilter %} + </div> + + <div class="panel"> + <h2>After: ✨ clarity ✨</h2> +{% filter markdown %}{% raw %} +```html+jinja +{#def products, msg="World!" #} + +<Layout title="My title"> + <div> + <h2>Hello, {{ msg }}</h2> + <div> + <Card div="So clean"> + {% for product in products %} + <Product product={{ product }} /> + {% endfor %} + </Card> + </div> + </div> + <Paginator items={{ products }} /> +</Layout> +``` +{% endraw %}{% endfilter %} + </div> + </div> + </section> + + <section class="features"> + <h2> + Better than <code>include</code> and <code>macros</code> + </h2> + <div class="cd-cards"> + <article class="card"> + <div class="header"> + <h3>Encapsulated</h3> + <img src="/static/img/encapsulated.svg" width="32" height="32"> + </div> + <div class="body prose prose-zinc"> + <div> + Link to their own <code>css</code> and/or <code>js</code> files + and can be copy/pasted to other projects without modifications. + </div> + </div> + </article> + + <article class="card"> + <div class="header"> + <h3>Simple</h3> + <img src="/static/img/simple.svg" width="32" height="32"> + </div> + <div class="body prose prose-zinc"> + <div> + Just regular Jinja files and no need to import them. + Easier to use and easier to read. + </div> + </div> + </article> + + <article class="card"> + <div class="header"> + <h3>Modern</h3> + <img src="/static/img/modern.svg" width="32" height="32"> + </div> + <div class="body prose prose-zinc"> + <div> + Components works great with + <a href="https://htmx.org/" target="_blank">htmx</a>, + <a href="https://tailwindcss.com/" target="_blank">TailwindCSS</a>, + or <a href="https://hotwired.dev/" target="_blank">Hotwire</a> + </div> + </div> + </article> + + <article class="card"> + <div class="header"> + <h3>Composable</h3> + <img src="/static/img/composable.svg" width="32" height="32"> + </div> + <div class="body prose prose-zinc"> + <div> + Can wrap content (HTML, other components, etc.) in a natural way. + </div> + </div> + </article> + </div> + </section> + + <section class="spaghetti"> + <div class="wrapper"> + <h2> + Say goodbye to spaghetti templates + </h2> + + <div class="text"> + <img src="/static/img/spaghetti_code.png" alt="Spaguetti code"> + + <p>Your Python code should be easy to understand and test.</p> + <p><b>Template code, however, often fails even basic code standards</b>: long methods, deep conditional nesting,and mystery variables everywhere. + </p> + <p><b>But when it's built with components, you see</b> where everything is, understand what are the possible statesof every piece of UI, and know exactly what data need to have. + </p> + <p>You can replace <b>all</b> your templates with components, or start with one section.</p> + </div> + </div> + </section> + + <section class="engage" data-md-skip> + <div class="wrapper"> + <h3>Ready to get going? Engage!</h3> + <a href="./guide/">Get started <i>→</i></a> + <div class="hint">Millions of people clicked a button in the last week alone!</div> + </div> + </section> +</div>
\ No newline at end of file diff --git a/docs/components/Logo.jinja b/docs/components/Logo.jinja new file mode 100644 index 0000000..3dd9ecd --- /dev/null +++ b/docs/components/Logo.jinja @@ -0,0 +1,7 @@ +{#def base_url="/" #} + +<a + {{ attrs.render(class="Logo", href=base_url, title="Back home") }}> + <img class="light" src="/static/img/jinjax-logo.svg" width="140" aria-hidden> + <img class="dark" src="/static/img/jinjax-logo-w.svg" width="140" aria-hidden> +</a> diff --git a/docs/components/NavExtra.jinja b/docs/components/NavExtra.jinja new file mode 100644 index 0000000..e6bb984 --- /dev/null +++ b/docs/components/NavExtra.jinja @@ -0,0 +1 @@ +<Source title="Go to repo" url="https://github.com/jpsca/jinjax" />
\ No newline at end of file diff --git a/docs/components/NavLinks.jinja b/docs/components/NavLinks.jinja new file mode 100644 index 0000000..fd2e693 --- /dev/null +++ b/docs/components/NavLinks.jinja @@ -0,0 +1,2 @@ +<a href="/guide/">Documentation</a> +<a href="/ui/">UI components</a> diff --git a/docs/components/SocialCardIndex.jinja b/docs/components/SocialCardIndex.jinja new file mode 100644 index 0000000..54da150 --- /dev/null +++ b/docs/components/SocialCardIndex.jinja @@ -0,0 +1,66 @@ +{#def page #} +<Layout + title={{ page.title }} + description={{ page.description }} +> + <style> + body { + background-color: black; + } + .sc1 { + width: 1200px; + height: 630px; + margin: 0; + font-family: SF Pro Display, system-ui, sans-serif; + color: black; + background-color: white + } + .sc1 > * { + position: absolute; + left: 100px; + width: 900px; + text-align: center; + overflow: hidden; + } + .sc1__logo { + top: 100px; + } + .sc1__logo img { + display: inline-block; + height: 200px; + width: auto; + margin: 0 auto; + } + .sc1__description { + top: 350px; + font-weight: bold; + font-size: 60px; + line-height: 1.2; + letter-spacing: -0.05em; + text-align: center; + } + .sc1__description .g1 { + background-image: linear-gradient(to bottom right, #fbbf24, #fb923c); + background-clip: text; + color: transparent; + } + + .sc1__description .g2 { + background-image: linear-gradient(to bottom right, #34d399, #3b82f6); + background-clip: text; + color: transparent; + } + </style> + + <article class="sc1"> + <div class="sc1__logo"> + <img src="/static/img/jinjax-logo.png" /> + </div> + <div class="sc1__description"> + Super + <span class="g1">components powers</span> + for your + <span class="g2">Jinja templates</span> + </div> + </article> +</Layout> diff --git a/docs/components/guide/slots/CompArchive.jinja b/docs/components/guide/slots/CompArchive.jinja new file mode 100644 index 0000000..dc242fe --- /dev/null +++ b/docs/components/guide/slots/CompArchive.jinja @@ -0,0 +1,10 @@ +{% filter markdown %}{% raw %} +```html+jinja +{#def posts #} +<Layout title="Archive"> + {% for post in posts %} + <Post post={post} /> + {% endfor %} +</Layout> +``` +{% endraw %}{% endfilter %}
\ No newline at end of file diff --git a/docs/components/guide/slots/CompLayout.jinja b/docs/components/guide/slots/CompLayout.jinja new file mode 100644 index 0000000..86c482e --- /dev/null +++ b/docs/components/guide/slots/CompLayout.jinja @@ -0,0 +1,14 @@ +{% filter markdown %}{% raw %} +```html+jinja +{#def title #} +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="utf-8"> + <title>{{ title }}</title> +</head> +<body> + {{ content }} +</body> +``` +{% endraw %}{% endfilter %}
\ No newline at end of file diff --git a/docs/components/guide/slots/Modal.jinja b/docs/components/guide/slots/Modal.jinja new file mode 100644 index 0000000..c2a9f66 --- /dev/null +++ b/docs/components/guide/slots/Modal.jinja @@ -0,0 +1,7 @@ +{% filter markdown %}{% raw %} +```html+jinja +<dialog class="modal"> + {{ content }} +</dialog> +``` +{% endraw %}{% endfilter %}
\ No newline at end of file diff --git a/docs/components/guide/slots/ModalBody.jinja b/docs/components/guide/slots/ModalBody.jinja new file mode 100644 index 0000000..66794ce --- /dev/null +++ b/docs/components/guide/slots/ModalBody.jinja @@ -0,0 +1,7 @@ +{% filter markdown %}{% raw %} +```html+jinja +<div class="modal-body"> + {{ content }} +</div> +``` +{% endraw %}{% endfilter %}
\ No newline at end of file diff --git a/docs/components/guide/slots/ModalFooter.jinja b/docs/components/guide/slots/ModalFooter.jinja new file mode 100644 index 0000000..e4eac26 --- /dev/null +++ b/docs/components/guide/slots/ModalFooter.jinja @@ -0,0 +1,7 @@ +{% filter markdown %}{% raw %} +```html+jinja +<footer class="modal-footer"> + {{ content }} +</footer> +``` +{% endraw %}{% endfilter %}
\ No newline at end of file diff --git a/docs/components/guide/slots/ModalHeader.jinja b/docs/components/guide/slots/ModalHeader.jinja new file mode 100644 index 0000000..6f5bc52 --- /dev/null +++ b/docs/components/guide/slots/ModalHeader.jinja @@ -0,0 +1,10 @@ +{% filter markdown %}{% raw %} +```html+jinja +<header class="modal-header> + <h2 class="modal-title"> + {{ content }} + </h2> + <CloseButton /> +</header> +``` +{% endraw %}{% endfilter %}
\ No newline at end of file diff --git a/docs/components/ui/Accordion/Accordion.css b/docs/components/ui/Accordion/Accordion.css new file mode 100644 index 0000000..e39911b --- /dev/null +++ b/docs/components/ui/Accordion/Accordion.css @@ -0,0 +1,67 @@ +@scope (#accordion-demo) { + :scope { + position: relative; + display: block; + flex-direction: column; + align-items: center; + justify-content: center; + padding: 4rem 0.5rem 0; + height: 360px; + margin: 0 auto; + } + @media (min-width: 38rem) { + :scope { + width: 36rem; + } + } + + details { + margin: 0; + border-width: 1px; + border-color: rgb(212 212 212); + background-color: rgb(245 245 245); + padding: 0; + overflow: hidden; + height: 3.5rem; + transition: all 0.15s ease-in-out; + } + details[open] { + height: 10rem; + } + details:focus-within { + box-shadow: 0 1px 2px 0 #2563eb; + } + details:first-of-type { + margin-top: 0px; + border-top-left-radius: 0.375rem; + border-top-right-radius: 0.375rem; + } + details:last-of-type { + margin-bottom: 0px; + border-bottom-left-radius: 0.375rem; + border-bottom-right-radius: 0.375rem; + } + + summary { + position: relative; + height: 3.5rem; + border-bottom-width: 1px; + border-color: transparent; + background-color: rgb(255, 255, 255); + padding: 1rem 1.25rem; + color: rgb(0, 0, 0); + cursor: default; + } + details[open] > summary { + border-color: rgb(229 229 229); + } + + .panel { + color: rgb(82 82 82); + padding: 0 1.25rem; + padding: 0.75rem 1.25rem; + } + .panel code { + font-weight: bold; + } +}
\ No newline at end of file diff --git a/docs/components/ui/Accordion/DemoCSS.jinja b/docs/components/ui/Accordion/DemoCSS.jinja new file mode 100644 index 0000000..d256041 --- /dev/null +++ b/docs/components/ui/Accordion/DemoCSS.jinja @@ -0,0 +1,51 @@ +{% filter markdown %}{% raw %} +```css +@scope (#accordion-demo) { + details { + margin: 0; + border-width: 1px; + border-color: rgb(212 212 212); + background-color: rgb(245 245 245); + padding: 0; + overflow: hidden; + height: 3.5rem; + width: 36rem; + transition: all 0.15s ease-in-out; + } + details[open] { + height: 10rem; + } + details:focus-within { + box-shadow: 0 1px 2px 0 #2563eb; + } + details:first-of-type { + margin-top: 0px; + border-top-left-radius: 0.375rem; + border-top-right-radius: 0.375rem; + } + details:last-of-type { + margin-bottom: 0px; + border-bottom-left-radius: 0.375rem; + border-bottom-right-radius: 0.375rem; + } + summary { + position: relative; + height: 3.5rem; + border-bottom-width: 1px; + border-color: transparent; + background-color: rgb(255, 255, 255); + padding: 1rem 1.25rem; + color: rgb(0, 0, 0); + cursor: default; + } + details[open] > summary { + border-color: rgb(229 229 229); + } + .panel { + color: rgb(82 82 82); + padding: 0 1.25rem; + padding: 0.75rem 1.25rem; + } +} +``` +{% endraw %}{% endfilter %}
\ No newline at end of file diff --git a/docs/components/ui/Accordion/DemoHTML.jinja b/docs/components/ui/Accordion/DemoHTML.jinja new file mode 100644 index 0000000..1e28d29 --- /dev/null +++ b/docs/components/ui/Accordion/DemoHTML.jinja @@ -0,0 +1,29 @@ +{% filter markdown %}{% raw %} +```html+jinja +<Accordion> + <details> + <summary>Is it accessible?</summary> + <div class="panel"> + Yes, more than any custom accordion you'll find on the web, because it's made + with native elements. + </div> + </details> + + <details> + <summary>Is it unstyled?</summary> + <div class="panel"> + Yes. The Accordion doesn't need any styles, you are free to style your + <code><details></code> elements however you need. + </div> + </details> + + <details> + <summary>Can it be animated?</summary> + <div class="panel"> + The <code><details></code> elements can be animated (with some restrictions) + using CSS animations, or with JS. + </div> + </details> +</Accordion> +``` +{% endraw %}{% endfilter %} diff --git a/docs/components/ui/Accordion/DemoResult.jinja b/docs/components/ui/Accordion/DemoResult.jinja new file mode 100644 index 0000000..8666e2d --- /dev/null +++ b/docs/components/ui/Accordion/DemoResult.jinja @@ -0,0 +1,32 @@ +{#css ui/Accordion/Accordion.css #} + +<div class="bg-cover" + style="background-image:linear-gradient(to right, rgba(252,211,77, 0.9), rgba(251,146,60, 0.9))" + data-md-skip +></div> + +<Accordion id="accordion-demo" data-md-skip> + <details> + <summary>Is it accessible?</summary> + <div class="panel"> + Yes, more than any custom accordion you'll find on the web, because it's made + with native elements. + </div> + </details> + + <details> + <summary>Is it unstyled?</summary> + <div class="panel"> + Yes. The Accordion doesn't need any styles, you are free to style your + <code><details></code> elements however you need. + </div> + </details> + + <details> + <summary>Can it be animated?</summary> + <div class="panel"> + The <code><details></code> elements can be animated (with some restrictions) + using CSS animations, or with JS. + </div> + </details> +</Accordion>
\ No newline at end of file diff --git a/docs/components/ui/Dialog/DemoCode.jinja b/docs/components/ui/Dialog/DemoCode.jinja new file mode 100644 index 0000000..36ecb76 --- /dev/null +++ b/docs/components/ui/Dialog/DemoCode.jinja @@ -0,0 +1,6 @@ +{% filter markdown %}{% raw %} +```html+jinja +{# Style classes and some content removed for clarity #} + +``` +{% endraw %}{% endfilter %} diff --git a/docs/components/ui/Dialog/DemoPreview.jinja b/docs/components/ui/Dialog/DemoPreview.jinja new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/docs/components/ui/Dialog/DemoPreview.jinja diff --git a/docs/components/ui/LinkedList/DemoCSS.jinja b/docs/components/ui/LinkedList/DemoCSS.jinja new file mode 100644 index 0000000..0927d4e --- /dev/null +++ b/docs/components/ui/LinkedList/DemoCSS.jinja @@ -0,0 +1,83 @@ +{% filter markdown %}{% raw %} +```css +.ui-linkedlist { + padding: 0px; + background-color: rgb(255 255 255); + overscroll-behavior: contain; + overflow-y: scroll; + list-style-type: none; + height: 16rem; + margin: 0px; + border: 1px solid rgb(128 128 128); + border-radius: 0.25rem; + font-size: 0.85rem; +} +.ui-linkedlist li { + cursor: pointer; + display: flex; + padding: 0.25rem 1rem; + align-items: center; +} +.ui-linkedlist li[disabled] { + color: rgb(156 156 156); + cursor: default; +} +.ui-linkedlist li:hover { + background-color: rgb(243 244 246); +} +.ui-linkedlist input[type="checkbox"] { + margin-right: 0.5rem; +} +label { + display: inline-block; + font-weight: bold; + background-color: white; + padding: 0.25rem 2rem; + border: 1px solid rgb(128 128 128); + border-radius: 0.25rem 0.25rem 0 0; + font-size: 0.7rem; + margin-bottom: -1px; +} + +button { + margin-top: 0.5rem; + display: inline-flex; + cursor: pointer; + -webkit-appearance: none; + -moz-appearance: none; + appearance: none; + align-items: center; + justify-content: center; +} +button > :not([hidden]) ~ :not([hidden]) { + margin-left: 0.25rem; +} +button { + white-space: nowrap; + border-radius: 0.25rem; + border: 1px solid transparent; + background-color: rgb(229 231 235); + padding: 0.5rem 0.75rem; + text-align: center; + font-size: 0.75rem; + line-height: 1rem; +} +button:hover { + border-color: rgb(219 234 254); + background-color: rgb(243 244 246); +} +button:focus { + background-color: rgb(229 231 235); + outline-offset: 1px; + outline-color: #3b82f6; +} +@media (min-width: 640px) { + button { + padding: 0.25rem 0.5rem; + } +} +button.select-all { + float: right; +} +``` +{% endraw %}{% endfilter %}
\ No newline at end of file diff --git a/docs/components/ui/LinkedList/DemoHTML.jinja b/docs/components/ui/LinkedList/DemoHTML.jinja new file mode 100644 index 0000000..375ddd7 --- /dev/null +++ b/docs/components/ui/LinkedList/DemoHTML.jinja @@ -0,0 +1,35 @@ +{% filter markdown %}{% raw %} +```html+jinja +<div> + <label>Known Mutants</label> + <LinkedList id="linkedlist-demo-list1" linked_to="linkedlist-demo-list2"> + <li><input type="checkbox" name="users" value="1" /> + Alexander Summers</li> + <!-- ... etc ... --> + <li><input type="checkbox" name="users" value="27" /> + Warren Worthington III</li> + </LinkedList> + + <button + type="button" + class="select-all" + onclick="document.getElementById('linkedlist-demo-list1').dispatchEvent(new CustomEvent('jxui:linked:sendall'));" + > + Select all » + </button> +</div> +<div> + <label>X-Men</label> + <LinkedList id="linkedlist-demo-list2" linked_to="linkedlist-demo-list1" active> + </LinkedList> + + <button + type="button" + class="remove-all" + onclick="document.getElementById('linkedlist-demo-list2').dispatchEvent(new CustomEvent('jxui:linked:sendall'));" + > + « Remove all + </button> +</div> +``` +{% endraw %}{% endfilter %}
\ No newline at end of file diff --git a/docs/components/ui/LinkedList/DemoResult.jinja b/docs/components/ui/LinkedList/DemoResult.jinja new file mode 100644 index 0000000..e3d9631 --- /dev/null +++ b/docs/components/ui/LinkedList/DemoResult.jinja @@ -0,0 +1,89 @@ +{#css ui/LinkedList/LinkedList.css #} + +<div class="bg-cover" + style="background-image:linear-gradient(to right, rgba(132,204,22,0.7), rgba(22,163,74,0.7))" + data-md-skip +></div> + +<div id="linkedlist-demo" data-md-skip> + <div> + <label>Known Mutants</label> + <LinkedList id="linkedlist-demo-list1" linked_to="linkedlist-demo-list2"> + <li><input type="checkbox" name="users" value="1" /> + Alexander Summers</li> + <li><input type="checkbox" name="users" value="2" /> + Alison Blaire</li> + <li><input type="checkbox" name="users" value="3" /> + Anna Marie LeBeau</li> + <li><input type="checkbox" name="users" value="4" /> + Charles Francis Xavier</li> + <li><input type="checkbox" name="users" value="5" /> + Elizabeth Braddock</li> + <li><input type="checkbox" name="users" value="6" /> + Emma Grace Frost</li> + <li disabled><input type="checkbox" name="users" value="7" disabled /> + Erik Magnus Lehnsherr</li> + <li><input type="checkbox" name="users" value="8" /> + Henry Philip McCoy</li> + <li><input type="checkbox" name="users" value="9" /> + James Howlett</li> + <li><input type="checkbox" name="users" value="10" /> + Jean Elaine Grey</li> + <li><input type="checkbox" name="users" value="11" /> + John Proudstar</li> + <li><input type="checkbox" name="users" value="12" /> + Jubilation Lee</li> + <li><input type="checkbox" name="users" value="13" /> + Katherine Anne Pryde</li> + <li><input type="checkbox" name="users" value="14" /> + Kurt Wagner</li> + <li><input type="checkbox" name="users" value="15" /> + Lucas Bishop</li> + <li><input type="checkbox" name="users" value="16" /> + Nathan Summers</li> + <li><input type="checkbox" name="users" value="17" /> + Ororo Munroe</li> + <li><input type="checkbox" name="users" value="18" /> + Piotr Nikolaievitch Rasputin</li> + <li><input type="checkbox" name="users" value="19 + Rachel Anne Summers</li> + <li><input type="checkbox" name="users" value="20" /> + Raven Darkhölme</li> + <li><input type="checkbox" name="users" value="21" /> + Remy Etienne LeBeau</li> + <li><input type="checkbox" name="users" value="22" /> + Robert Louis Drake</li> + <li><input type="checkbox" name="users" value="23" /> + Roberto da Costa</li> + <li><input type="checkbox" name="users" value="24" /> + Scott Summers</li> + <li><input type="checkbox" name="users" value="25" /> + Sean Cassidy</li> + <li><input type="checkbox" name="users" value="26" /> + Shiro Yoshida</li> + <li><input type="checkbox" name="users" value="27" /> + Warren Worthington III</li> + </LinkedList> + + <button + type="button" + class="select-all" + onclick="document.getElementById('linkedlist-demo-list1').dispatchEvent(new CustomEvent('jxui:linked:sendall'));" + > + Select all » + </button> + </div> + <div> + <label>X-Men</label> + <LinkedList id="linkedlist-demo-list2" linked_to="linkedlist-demo-list1" active> + </LinkedList> + + <button + type="button" + class="remove-all" + onclick="document.getElementById('linkedlist-demo-list2').dispatchEvent(new CustomEvent('jxui:linked:sendall'));" + > + « Remove all + </button> + </div> +</div>
\ No newline at end of file diff --git a/docs/components/ui/LinkedList/LinkedList.css b/docs/components/ui/LinkedList/LinkedList.css new file mode 100644 index 0000000..fd69adc --- /dev/null +++ b/docs/components/ui/LinkedList/LinkedList.css @@ -0,0 +1,96 @@ +@scope (#linkedlist-demo) { + :scope { + position: relative; + display: block; + display: flex; + align-items: center; + justify-content: center; + padding: 0.5rem; + height: 360px; + margin: 0 auto; + } + :scope > div { + width: 100%; + margin: 0 1rem; + } + + .ui-linkedlist { + padding: 0px; + background-color: rgb(255 255 255); + overscroll-behavior: contain; + overflow-y: scroll; + list-style-type: none; + height: 16rem; + margin: 0px; + border: 1px solid rgb(128 128 128); + border-radius: 0.25rem; + font-size: 0.85rem; + } + .ui-linkedlist li { + cursor: pointer; + display: flex; + padding: 0.25rem 1rem; + align-items: center; + } + .ui-linkedlist li[disabled] { + color: rgb(156 156 156); + cursor: default; + } + .ui-linkedlist li:hover { + background-color: rgb(243 244 246); + } + .ui-linkedlist input[type="checkbox"] { + margin-right: 0.5rem; + } + label { + display: inline-block; + font-weight: bold; + background-color: white; + padding: 0.25rem 2rem; + border: 1px solid rgb(128 128 128); + border-radius: 0.25rem 0.25rem 0 0; + font-size: 0.7rem; + margin-bottom: -1px; + } + + button { + margin-top: 0.5rem; + display: inline-flex; + cursor: pointer; + -webkit-appearance: none; + -moz-appearance: none; + appearance: none; + align-items: center; + justify-content: center; + } + button > :not([hidden]) ~ :not([hidden]) { + margin-left: 0.25rem; + } + button { + white-space: nowrap; + border-radius: 0.25rem; + border: 1px solid transparent; + background-color: rgb(229 231 235); + padding: 0.5rem 0.75rem; + text-align: center; + font-size: 0.75rem; + line-height: 1rem; + } + button:hover { + border-color: rgb(219 234 254); + background-color: rgb(243 244 246); + } + button:focus { + background-color: rgb(229 231 235); + outline-offset: 1px; + outline-color: #3b82f6; + } + @media (min-width: 640px) { + button { + padding: 0.25rem 0.5rem; + } + } + button.select-all { + float: right; + } +}
\ No newline at end of file diff --git a/docs/components/ui/Menu/DemoCSS.jinja b/docs/components/ui/Menu/DemoCSS.jinja new file mode 100644 index 0000000..d726800 --- /dev/null +++ b/docs/components/ui/Menu/DemoCSS.jinja @@ -0,0 +1,131 @@ +{% filter markdown %}{% raw %} +```css +@scope (#menu-demo) { + :scope { + position: relative; + display: block; + padding: 2rem 0.5rem 0; + height: 300px; + margin: 0 auto; + } + + .ui-menubutton { + border-radius: 0.25rem; + border-width: 1px; + background-color: rgb(0 0 0 / 0.1); + padding-top: 0.25rem; + padding-bottom: 0.25rem; + padding-left: 1rem; + padding-right: 1rem; + font-weight: 600; + color: white; + display: flex; + align-items: center; + justify-content: center; + box-shadow: 0 10px 15px -3px rgb(0 0 0 / 0.1), + 0 4px 6px -4px rgb(0 0 0 / 0.1); + width: fit-content; + margin: 0 auto; + } + .ui-menubutton:hover { + background-color: rgb(0 0 0 / 0.2); + } + .ui-menubutton .icon { + margin-left: 0.25rem; + } + + .group:not([hidden]) ~ .group:not([hidden]) { + border-top: 1px solid #d1d5db; + } + .ui-menu { + margin-top: 4px; + padding: 8px 0; + border-radius: 8px; + width: 400px; + background-color: #ffffff; + box-shadow: 0 1px 3px 4px rgba(0, 0, 0, 0.2); + overflow: visible; + font-size: 0.9rem; + font-weight: 400; + transition: all 0.2s allow-discrete; + /* Final state of the exit animation */ + opacity: 0; + transform: translateY(-1rem); + } + .ui-menu:popover-open { + opacity: 1; + transform: translateY(0); + } + /* Needs to be after the previous .ui-menu:popover-open rule + to take effect, as the specificity is the same */ + @starting-style { + .ui-menu:popover-open { + opacity: 0; + transform: translateY(-1rem); + } + } + .ui-menu:focus { + outline: none; + } + .ui-menu .ui-menu { + position: absolute; + margin: 0 0 0 -4px; + width: 300px; + z-index: 1; + transition: opacity 0.2s allow-discrete; + } + .ui-menu * { + user-select: none; + } + + .ui-menuitem { + display: flex; + height: 40px; + padding-left: 24px; + padding-right: 24px; + align-items: center; + justify-items: flex-start; + line-height: 40px; + color: #000000; + background-color: #ffffff; + cursor: default; + user-select: none; + position: relative; + text-align: left; + } + .ui-menuitem.ui-selected { + background-color: #f2e7e4; + } + .ui-menuitem.ui-disabled { + color: #5f6368; + } + .ui-menuitem > .icon { + font-size: 1rem; + width: 24px; + text-align: left; + } + .ui-menuitem.ui-disabled > .icon { + color: #aca6a7; + } + .ui-menuitem > a { + flex-grow: 1; + } + .ui-menuitem > kbd { + visibility: hidden; + margin-left: auto; + font-size: 0.9rem; + font-family: inherit; + text-align: right; + color: #524f50; + } + .ui-menuitem:not(.ui-disabled):hover > kbd { + visibility: visible; + } + .ui-menuitem > .arrow { + margin-left: auto; + font-size: 0.7rem; + text-align: right; + } +} +``` +{% endraw %}{% endfilter %} diff --git a/docs/components/ui/Menu/DemoHTML.jinja b/docs/components/ui/Menu/DemoHTML.jinja new file mode 100644 index 0000000..60c126a --- /dev/null +++ b/docs/components/ui/Menu/DemoHTML.jinja @@ -0,0 +1,89 @@ +{% filter markdown %}{% raw %} +```html+jinja +<MenuButton id="menu-demo-btn" target="menu-demo-menu"> + Menu <i class="icon">keyboard_arrow_down</i> +</MenuButton> + +<Menu id="menu-demo-menu" anchor="menu-demo-btn" anchor-to="bottom end"> + <div class="group"> + <MenuItem> + <i class="icon">tab</i> + <a>New tab</a> + <kbd>Ctrl+T</kbd> + </MenuItem> + <MenuItem> + <i class="icon">new_window</i> + <a>New window</a> + <kbd>Ctrl+N</kbd> + </MenuItem> + <MenuItem disabled> + <i class="icon">fingerprint_off</i> + <a>Disabled item</a> + <kbd>Ctrl+Shift+N</kbd> + </MenuItem> + </div> + <div class="group"> + <MenuItem> + <i class="icon">download</i> + <a>Downloads</a> + <kbd>Ctrl+J</kbd> + </MenuItem> + <MenuItemSub id="bookmarks-item"> + <i class="icon">bookmarks</i> + <a>Bookmarks and lists</a> + <span class="icon arrow">keyboard_arrow_right</span> + + <Menu anchor="bookmarks-item" anchor_to="right start"> + <div class="group"> + <MenuItem> + <i class="icon">bookmark_add</i> + <a>Bookmark this tab...</a> + <kbd>Ctrl+D</kbd> + </MenuItem> + <MenuItem> + <i class="icon">bookmarks</i> + <a>Bookmark all tabs...</a> + <kbd>Ctrl+Shift+D</kbd> + </MenuItem> + </div> + <div class="group"> + <MenuItem> + <i class="icon">toolbar</i> + <a>Hide bookmarks bar</a> + <kbd>Ctrl+Shift+B</kbd> + </MenuItem> + <MenuItem> + <i class="icon">bookmarks</i> + <a>Show all bookmarks</a> + </MenuItem> + <MenuItem> + <i class="icon">bookmark_manager</i> + <a>Bookmark manager</a> + <kbd>Ctrl+Shift+O</kbd> + </MenuItem> + </div> + </Menu> + </MenuItemSub> + </div> + <div class="group"> + <MenuItem> + <i class="icon">print</i> + <a>Print...</a> + <kbd>Ctrl+P</kbd> + </MenuItem> + <MenuItem> + <i class="icon">help</i> + <a>Help</a> + </MenuItem> + <MenuItem> + <i class="icon">settings</i> + <a>Settings</a> + </MenuItem> + <MenuItem> + <i class="icon">exit_to_app</i> + <a>Exit</a> + </MenuItem> + </div> +</Menu> +``` +{% endraw %}{% endfilter %} diff --git a/docs/components/ui/Menu/DemoResult.jinja b/docs/components/ui/Menu/DemoResult.jinja new file mode 100644 index 0000000..b62226c --- /dev/null +++ b/docs/components/ui/Menu/DemoResult.jinja @@ -0,0 +1,94 @@ +{#css ui/Menu/Menu.css #} + +<div class="bg-cover" + style="background-image:linear-gradient(to right, rgba(244,114,182, 0.9), rgba(219,39,119, 0.9))" + data-md-skip +></div> + +<div id="menu-demo" data-md-skip> + <MenuButton id="menu-demo-btn" target="menu-demo-menu"> + Menu <i class="icon">keyboard_arrow_down</i> + </MenuButton> + + <Menu id="menu-demo-menu" anchor="menu-demo-btn" anchor-to="bottom end"> + <div class="group"> + <MenuItem> + <i class="icon">tab</i> + <a>New tab</a> + <kbd>Ctrl+T</kbd> + </MenuItem> + <MenuItem> + <i class="icon">new_window</i> + <a>New window</a> + <kbd>Ctrl+N</kbd> + </MenuItem> + <MenuItem disabled> + <i class="icon">fingerprint_off</i> + <a>Disabled item</a> + <kbd>Ctrl+Shift+N</kbd> + </MenuItem> + </div> + <div class="group"> + <MenuItem> + <i class="icon">download</i> + <a>Downloads</a> + <kbd>Ctrl+J</kbd> + </MenuItem> + <MenuItemSub id="bookmarks-item"> + <i class="icon">bookmarks</i> + <a>Bookmarks and lists</a> + <span class="icon arrow">keyboard_arrow_right</span> + + <Menu anchor="bookmarks-item" anchor_to="right start"> + <div class="group"> + <MenuItem> + <i class="icon">bookmark_add</i> + <a>Bookmark this tab...</a> + <kbd>Ctrl+D</kbd> + </MenuItem> + <MenuItem> + <i class="icon">bookmarks</i> + <a>Bookmark all tabs...</a> + <kbd>Ctrl+Shift+D</kbd> + </MenuItem> + </div> + <div class="group"> + <MenuItem> + <i class="icon">toolbar</i> + <a>Hide bookmarks bar</a> + <kbd>Ctrl+Shift+B</kbd> + </MenuItem> + <MenuItem> + <i class="icon">bookmarks</i> + <a>Show all bookmarks</a> + </MenuItem> + <MenuItem> + <i class="icon">bookmark_manager</i> + <a>Bookmark manager</a> + <kbd>Ctrl+Shift+O</kbd> + </MenuItem> + </div> + </Menu> + </MenuItemSub> + </div> + <div class="group"> + <MenuItem> + <i class="icon">print</i> + <a>Print...</a> + <kbd>Ctrl+P</kbd> + </MenuItem> + <MenuItem> + <i class="icon">help</i> + <a>Help</a> + </MenuItem> + <MenuItem> + <i class="icon">settings</i> + <a>Settings</a> + </MenuItem> + <MenuItem> + <i class="icon">exit_to_app</i> + <a>Exit</a> + </MenuItem> + </div> + </Menu> +</div> diff --git a/docs/components/ui/Menu/Menu.css b/docs/components/ui/Menu/Menu.css new file mode 100644 index 0000000..a93313d --- /dev/null +++ b/docs/components/ui/Menu/Menu.css @@ -0,0 +1,127 @@ +@scope (#menu-demo) { + :scope { + position: relative; + display: block; + padding: 2rem 0.5rem 0; + height: 200px; + margin: 0 auto; + } + + .ui-menubutton { + border-radius: 0.25rem; + border-width: 1px; + background-color: rgb(0 0 0 / 0.1); + padding-top: 0.25rem; + padding-bottom: 0.25rem; + padding-left: 1rem; + padding-right: 1rem; + font-weight: 600; + color: white; + display: flex; + align-items: center; + justify-content: center; + box-shadow: 0 10px 15px -3px rgb(0 0 0 / 0.1), + 0 4px 6px -4px rgb(0 0 0 / 0.1); + width: fit-content; + margin: 0 auto; + } + .ui-menubutton:hover { + background-color: rgb(0 0 0 / 0.2); + } + .ui-menubutton .icon { + margin-left: 0.25rem; + } + + .group:not([hidden]) ~ .group:not([hidden]) { + border-top: 1px solid #d1d5db; + } + .ui-menu { + margin-top: 4px; + padding: 8px 0; + border-radius: 8px; + width: 400px; + background-color: #ffffff; + box-shadow: 0 1px 3px 4px rgba(0, 0, 0, 0.2); + overflow: visible; + font-size: 0.9rem; + font-weight: 400; + transition: all 0.2s allow-discrete; + /* Final state of the exit animation */ + opacity: 0; + transform: translateY(-1rem); + } + .ui-menu:popover-open { + opacity: 1; + transform: translateY(0); + } + /* Needs to be after the previous .ui-menu:popover-open rule + to take effect, as the specificity is the same */ + @starting-style { + .ui-menu:popover-open { + opacity: 0; + transform: translateY(-1rem); + } + } + .ui-menu:focus { + outline: none; + } + .ui-menu .ui-menu { + position: absolute; + margin: 0 0 0 -4px; + width: 300px; + z-index: 1; + transition: opacity 0.2s allow-discrete; + } + .ui-menu * { + user-select: none; + } + + .ui-menuitem { + display: flex; + height: 40px; + padding-left: 24px; + padding-right: 24px; + align-items: center; + justify-items: flex-start; + line-height: 40px; + color: #000000; + background-color: #ffffff; + cursor: default; + user-select: none; + position: relative; + text-align: left; + } + .ui-menuitem.ui-selected { + background-color: #f2e7e4; + } + .ui-menuitem.ui-disabled { + color: #5f6368; + } + .ui-menuitem > .icon { + font-size: 1rem; + width: 24px; + text-align: left; + } + .ui-menuitem.ui-disabled > .icon { + color: #aca6a7; + } + .ui-menuitem > a { + flex-grow: 1; + } + .ui-menuitem > kbd { + visibility: hidden; + margin-left: auto; + font-size: 0.9rem; + font-family: inherit; + text-align: right; + color: #524f50; + } + .ui-menuitem:not(.ui-disabled):hover > kbd { + visibility: visible; + } + .ui-menuitem > .arrow { + margin-left: auto; + font-size: 0.7rem; + text-align: right; + } +}
\ No newline at end of file diff --git a/docs/components/ui/Popover/DemoCSS.jinja b/docs/components/ui/Popover/DemoCSS.jinja new file mode 100644 index 0000000..83418c9 --- /dev/null +++ b/docs/components/ui/Popover/DemoCSS.jinja @@ -0,0 +1,96 @@ +{% filter markdown %}{% raw %} +```css +.ui-popbutton { + border-radius: 0.25rem; + border-width: 1px; + background-color: rgb(0 0 0 / 0.1); + padding-top: 0.25rem; + padding-bottom: 0.25rem; + padding-left: 1rem; + padding-right: 1rem; + font-weight: 600; + color: white; + box-shadow: 0 10px 15px -3px rgb(0 0 0 / 0.1), + 0 4px 6px -4px rgb(0 0 0 / 0.1); +} +.ui-popbutton:hover { + background-color: rgb(0 0 0 / 0.2); +} + +[popover] { + background-color: Canvas; + border-radius: 0.25rem; + border: 1px solid #666; + color: CanvasText; + height: fit-content; + margin: 0.75rem auto 0; + padding: 1rem; + width: 15rem; + overflow: visible; + transition: all 0.2s allow-discrete; + /* Final state of the exit animation */ + opacity: 0; + transform: translateY(-3rem); +} +[popover]:popover-open { + opacity: 1; + transform: translateY(0); +} +/* Needs to be after the previous [popover]:popover-open rule +to take effect, as the specificity is the same */ +@starting-style { + [popover]:popover-open { + opacity: 0; + transform: translateY(-3rem); + } +} + +/* Transition for the popover's backdrop */ +[popover]::backdrop { + transition: all 0.2s allow-discrete; + /* Final state of the exit animation */ + background-color: rgb(0 0 0 / 0%); +} +[popover]:popover-open::backdrop { + background-color: rgb(0 0 0 / 15%); +} +/* The nesting selector (&) cannot represent pseudo-elements +so this starting-style rule cannot be nested */ +@starting-style { + [popover]:popover-open::backdrop { + background-color: rgb(0 0 0 / 0%); + } +} + +[popover] h1 { + font-weight: bold; + margin-bottom: 0.75rem; +} +[popover] label { + display: flex; + align-items: center; + justify-content: space-between; + font-size: 0.75rem; + line-height: 1rem; +} +[popover] input { + margin-left: auto; + width: 66.666667%; + border-radius: 0.25rem; + border-width: 1px; + padding: 0.25rem; + font-size: 0.75rem; + line-height: 1rem; +} +[popover] svg.arrow { + position: absolute; + top: -4px; + left: 50%; + z-index: 10; + display: block; + transform: rotate(180deg); + border-color: rgb(255 255 255); + fill: white; +} +``` +{% endraw %}{% endfilter %} diff --git a/docs/components/ui/Popover/DemoHTML.jinja b/docs/components/ui/Popover/DemoHTML.jinja new file mode 100644 index 0000000..b40ddfb --- /dev/null +++ b/docs/components/ui/Popover/DemoHTML.jinja @@ -0,0 +1,23 @@ +{% filter markdown %}{% raw %} +```html+jinja +<PopButton id="pop-demo-btn" target="pop-demo-pop">Open popover</PopButton> + +<Popover id="pop-demo-pop" anchor="pop-demo-btn" anchor-to="bottom"> + <h1>Edit Dimensions</h1> + <fieldset class="space-y-2"> + <label> + <span>Width</span> + <input type="text" name="width" value="340px"> + </label> + <label> + <span>Height</span> + <input type="text" name="height" value="25px"> + </label> + </fieldset> + + <svg class="arrow" width="10" height="5" viewBox="0 0 30 10" aria-hidden="true"> + <polygon points="0,0 30,0 15,10"></polygon> + </svg> +</Popover> +``` +{% endraw %}{% endfilter %} diff --git a/docs/components/ui/Popover/DemoResult.jinja b/docs/components/ui/Popover/DemoResult.jinja new file mode 100644 index 0000000..a0b73e8 --- /dev/null +++ b/docs/components/ui/Popover/DemoResult.jinja @@ -0,0 +1,27 @@ +{#css ui/Popover/Popover.css #} + +<div class="bg-cover" + style="background-image:linear-gradient(to right, rgba(217,70,239, 0.9), rgba(147,51,234, 0.9))" + data-md-skip +></div> + +<div id="pop-demo" data-md-skip> + <PopButton id="pop-demo-btn" target="pop-demo-pop">Open popover</PopButton> + + <Popover id="pop-demo-pop" anchor="pop-demo-btn" anchor-to="bottom"> + <h1 data-outline-skip=>Edit Dimensions</h1> + <fieldset class="space-y-2"> + <label> + <span>Width</span> + <input type="text" name="width" value="340px"> + </label> + <label> + <span>Height</span> + <input type="text" name="height" value="25px"> + </label> + </fieldset> + <svg class="arrow" width="10" height="5" viewBox="0 0 30 10" aria-hidden="true"> + <polygon points="0,0 30,0 15,10"></polygon> + </svg> + </Popover> +</div> diff --git a/docs/components/ui/Popover/Popover.css b/docs/components/ui/Popover/Popover.css new file mode 100644 index 0000000..724547f --- /dev/null +++ b/docs/components/ui/Popover/Popover.css @@ -0,0 +1,101 @@ +@scope (#pop-demo) { + :scope { + position: relative; + display: block; + padding: 2rem 0.5rem 0; + height: 300px; + margin: 0 auto; + text-align: center; + } + + .ui-popbutton { + border-radius: 0.25rem; + border-width: 1px; + background-color: rgb(0 0 0 / 0.1); + padding-top: 0.25rem; + padding-bottom: 0.25rem; + padding-left: 1rem; + padding-right: 1rem; + font-weight: 600; + color: white; + box-shadow: 0 10px 15px -3px rgb(0 0 0 / 0.1), + 0 4px 6px -4px rgb(0 0 0 / 0.1); + } + .ui-popbutton:hover { + background-color: rgb(0 0 0 / 0.2); + } + + [popover] { + background-color: Canvas; + border-radius: 0.25rem; + border: 1px solid #666; + color: CanvasText; + height: fit-content; + margin: 0.75rem auto 0; + padding: 1rem; + width: 15rem; + overflow: visible; + transition: all 0.2s allow-discrete; + /* Final state of the exit animation */ + opacity: 0; + transform: translateY(-3rem); + } + [popover]:popover-open { + opacity: 1; + transform: translateY(0); + } + /* Needs to be after the previous [popover]:popover-open rule + to take effect, as the specificity is the same */ + @starting-style { + [popover]:popover-open { + opacity: 0; + transform: translateY(-3rem); + } + } + + /* Transition for the popover's backdrop */ + [popover]::backdrop { + /* Final state of the exit animation */ + background-color: rgb(0 0 0 / 0%); + transition: all 0.2s allow-discrete; + } + [popover]:popover-open::backdrop { + background-color: rgb(0 0 0 / 15%); + } + @starting-style { + [popover]:popover-open::backdrop { + background-color: rgb(0 0 0 / 0%); + } + } + + [popover] h1 { + font-weight: bold; + margin-bottom: 0.75rem; + } + [popover] label { + display: flex; + align-items: center; + justify-content: space-between; + font-size: 0.75rem; + line-height: 1rem; + } + [popover] input { + margin-left: auto; + width: 66.666667%; + border-radius: 0.25rem; + border-width: 1px; + padding: 0.25rem; + font-size: 0.75rem; + line-height: 1rem; + } + [popover] svg.arrow { + position: absolute; + top: -4px; + left: 50%; + z-index: 10; + display: block; + transform: rotate(180deg); + border-color: rgb(255 255 255); + fill: white; + } +}
\ No newline at end of file diff --git a/docs/components/ui/Tabs/DemoCSS.jinja b/docs/components/ui/Tabs/DemoCSS.jinja new file mode 100644 index 0000000..07db8f0 --- /dev/null +++ b/docs/components/ui/Tabs/DemoCSS.jinja @@ -0,0 +1,59 @@ +{% filter markdown %}{% raw %} +```css +.ui-tablist { + display: flex; +} +.ui-tablist > :not([hidden]) ~ :not([hidden]) { + margin-left: 0.25rem ; +} +.ui-tablist { + border-radius: 1rem; + background-color: rgb(30 58 138 / 0.6); + padding: 0.5rem; + color: #111; +} +.ui-tablist > .ui-tab:not([hidden]) ~ .ui-tab:not([hidden]) { + margin-left: 0.5rem; +} +.ui-tab { + width: 100%; + border-radius: 0.5rem; + color: #222; + background-color: rgb(255 255 255 / 0.7); + padding: 0.75rem 0.25rem; + font-size: 0.875rem; + font-weight: 500; + line-height: 1.25rem; +} +.ui-tab:focus { + outline: 2px solid rgb(59 130 246 / 0.8); + outline-offset: 2px; +} +.ui-tab.ui-selected { + background-color: white; + color: black; +} +.ui-tab:hover:not(.ui-selected, .ui-disabled), +.ui-tab:focus:not(.ui-selected, .ui-disabled) { + background-color: rgb(255 255 255 / 0.8); +} +.ui-tabpanel { + margin-top: 0.5rem; + border-radius: 0.75rem; + background-color: rgb(254 254 254); + border: 2px solid rgb(59 130 246 / 0.8); + padding: 0.1rem; + min-height: 8rem; + display: flex; + align-items: center; + justify-content: center; +} +.ui-tabpanel:focus { + outline: 2px solid transparent; + outline-offset: 2px; +} +.ui-tabpanel.ui-hidden { + display: none; +} +``` +{% endraw %}{% endfilter %}
\ No newline at end of file diff --git a/docs/components/ui/Tabs/DemoHTML.jinja b/docs/components/ui/Tabs/DemoHTML.jinja new file mode 100644 index 0000000..e267335 --- /dev/null +++ b/docs/components/ui/Tabs/DemoHTML.jinja @@ -0,0 +1,23 @@ +{% filter markdown %}{% raw %} +```html+jinja +<TabGroup> + <TabList> + <Tab target="demo-recent" selected>Recent</Tab> + <Tab target="demo-popular">Popular</Tab> + <Tab target="demo-trending">Trending</Tab> + </TabList> + + <TabPanel id> + <p>This is the tab panel for <b>"Recent"</b>.</p> + </TabPanel> + + <TabPanel id="demo-popular" hidden> + <p>This is the tab panel for <b>"Popular"</b>.</p> + </TabPanel> + + <TabPanel id="demo-trending" hidden> + <p>This is the tab panel for <b>"Trending"</b>.</p> + </TabPanel> +</TabGroup> +``` +{% endraw %}{% endfilter %} diff --git a/docs/components/ui/Tabs/DemoResult.jinja b/docs/components/ui/Tabs/DemoResult.jinja new file mode 100644 index 0000000..3306eac --- /dev/null +++ b/docs/components/ui/Tabs/DemoResult.jinja @@ -0,0 +1,28 @@ +{#css ui/Tabs/Tabs.css #} + +<div class="bg-cover" + style="background-image:linear-gradient(to right, rgba(56,189,248, 0.9), rgba(37,99,235, 0.9))" + data-md-skip +></div> + +<div class="horizontal-tabs" data-md-skip> + <TabGroup> + <TabList> + <Tab target="demo-recent" selected>Recent</Tab> + <Tab target="demo-popular">Popular</Tab> + <Tab target="demo-trending">Trending</Tab> + </TabList> + + <TabPanel id="demo-recent"> + <p>This is the tab panel for <b>"Recent"</b>.</p> + </TabPanel> + + <TabPanel id="demo-popular" hidden> + <p>This is the tab panel for <b>"Popular"</b>.</p> + </TabPanel> + + <TabPanel id="demo-trending" hidden> + <p>This is the tab panel for <b>"Trending"</b>.</p> + </TabPanel> + </TabGroup> +</div> diff --git a/docs/components/ui/Tabs/ManualHTML.jinja b/docs/components/ui/Tabs/ManualHTML.jinja new file mode 100644 index 0000000..1a39f35 --- /dev/null +++ b/docs/components/ui/Tabs/ManualHTML.jinja @@ -0,0 +1,28 @@ +{% filter markdown %}{% raw %} +```html+jinja +<TabGroup> + <TabList manual> + <Tab target="manual-recent" selected>Recent</Tab> + <Tab target="manual-popular">Popular</Tab> + <Tab target="manual-disabled" disabled>Disabled</Tab> + <Tab target="manual-trending">Trending</Tab> + </TabList> + + <TabPanel id="manual-recent"> + <p>This is the tab panel for <b>"Recent"</b>.</p> + </TabPanel> + + <TabPanel id="manual-popular" hidden> + <p>This is the tab panel for <b>"Popular"</b>.</p> + </TabPanel> + + <TabPanel id="manual-disabled" hidden> + <p>This is the tab panel for "Disabled".</p> + </TabPanel> + + <TabPanel id="manual-trending" hidden> + <p>This is the tab panel for <b>"Trending"</b>.</p> + </TabPanel> +</TabGroup> +``` +{% endraw %}{% endfilter %} diff --git a/docs/components/ui/Tabs/ManualResult.jinja b/docs/components/ui/Tabs/ManualResult.jinja new file mode 100644 index 0000000..2a067bd --- /dev/null +++ b/docs/components/ui/Tabs/ManualResult.jinja @@ -0,0 +1,33 @@ +{#css ui/Tabs/Tabs.css #} + +<div class="bg-cover" + style="background-image:linear-gradient(to right, rgba(56,189,248, 0.3), rgba(37,99,235, 0.3))" + data-md-skip +></div> + +<div class="horizontal-tabs" data-md-skip> + <TabGroup> + <TabList manual> + <Tab target="manual-recent" selected>Recent</Tab> + <Tab target="manual-popular">Popular</Tab> + <Tab target="manual-disabled" disabled>Disabled</Tab> + <Tab target="manual-trending">Trending</Tab> + </TabList> + + <TabPanel id="manual-recent"> + <p>This is the tab panel for <b>"Recent"</b>.</p> + </TabPanel> + + <TabPanel id="manual-popular" hidden> + <p>This is the tab panel for <b>"Popular"</b>.</p> + </TabPanel> + + <TabPanel id="manual-disabled" hidden> + <p>This is the tab panel for "Disabled".</p> + </TabPanel> + + <TabPanel id="manual-trending" hidden> + <p>This is the tab panel for <b>"Trending"</b>.</p> + </TabPanel> + </TabGroup> +</div> diff --git a/docs/components/ui/Tabs/SelectHTML.jinja b/docs/components/ui/Tabs/SelectHTML.jinja new file mode 100644 index 0000000..7651bb8 --- /dev/null +++ b/docs/components/ui/Tabs/SelectHTML.jinja @@ -0,0 +1,35 @@ +{% filter markdown %}{% raw %} +```html+jinja +<TabGroup> + <TabSelect> + <TabOption target="select-recent">Recent</TabOption> + <TabOption target="select-popular">Popular</TabOption> + <TabOption target="select-disabled" disabled>Disabled</TabOption> + <TabOption target="select-trending">Trending</TabOption> + </TabSelect> + + <TabList> + <Tab target="select-recent">Recent</Tab> + <Tab target="select-popular" selected>Popular</Tab> + <Tab target="select-disabled" disabled>Disabled</Tab> + <Tab target="select-trending">Trending</Tab> + </TabList> + + <TabPanel id="select-recent"> + <p>This is the tab panel for <b>"Recent"</b>.</p> + </TabPanel> + + <TabPanel id="select-popular" hidden> + <p>This is the tab panel for <b>"Popular"</b>.</p> + </TabPanel> + + <TabPanel id="select-disabled" hidden> + <p>This is the tab panel for "Disabled".</p> + </TabPanel> + + <TabPanel id="select-trending" hidden> + <p>This is the tab panel for <b>"Trending"</b>.</p> + </TabPanel> +</TabGroup> +``` +{% endraw %}{% endfilter %} diff --git a/docs/components/ui/Tabs/SelectResult.jinja b/docs/components/ui/Tabs/SelectResult.jinja new file mode 100644 index 0000000..ffdf0ea --- /dev/null +++ b/docs/components/ui/Tabs/SelectResult.jinja @@ -0,0 +1,40 @@ +{#css ui/Tabs/Tabs.css #} + +<div class="bg-cover" + style="background-image:linear-gradient(to right, rgba(56,189,248, 0.3), rgba(37,99,235, 0.3))" + data-md-skip +></div> + +<div class="horizontal-tabs" data-md-skip> + <TabGroup> + <TabSelect> + <TabOption target="select-recent">Recent</TabOption> + <TabOption target="select-popular">Popular</TabOption> + <TabOption target="select-disabled" disabled>Disabled</TabOption> + <TabOption target="select-trending">Trending</TabOption> + </TabSelect> + + <TabList> + <Tab target="select-recent">Recent</Tab> + <Tab target="select-popular" selected>Popular</Tab> + <Tab target="select-disabled" disabled>Disabled</Tab> + <Tab target="select-trending">Trending</Tab> + </TabList> + + <TabPanel id="select-recent"> + <p>This is the tab panel for <b>"Recent"</b>.</p> + </TabPanel> + + <TabPanel id="select-popular" hidden> + <p>This is the tab panel for <b>"Popular"</b>.</p> + </TabPanel> + + <TabPanel id="select-disabled" hidden> + <p>This is the tab panel for "Disabled".</p> + </TabPanel> + + <TabPanel id="select-trending" hidden> + <p>This is the tab panel for <b>"Trending"</b>.</p> + </TabPanel> + </TabGroup> +</div> diff --git a/docs/components/ui/Tabs/Tabs.css b/docs/components/ui/Tabs/Tabs.css new file mode 100644 index 0000000..ddbef0e --- /dev/null +++ b/docs/components/ui/Tabs/Tabs.css @@ -0,0 +1,126 @@ +@scope(.horizontal-tabs,.vertical-tabs) { + :scope { + width: 100%; + max-width: 36rem; + margin: 10% auto; + padding: 0.5rem; + } + + .ui-tablist { + display: flex; + border-radius: 1rem; + background-color: #6383dd; + padding: 0.5rem; + color: #111; + } + .ui-tablist > .ui-tab:not([hidden]) ~ .ui-tab:not([hidden]) { + margin-left: 0.5rem; + } + .ui-tab { + width: 100%; + border-radius: 0.5rem; + color: #222; + background-color: rgb(255 255 255 / 0.7); + padding: 0.75rem 0.25rem; + font-size: 0.875rem; + font-weight: 500; + line-height: 1.25rem; + } + .ui-tab:focus { + outline: 2px solid rgb(255 255 255 / 0.8); + outline-offset: 2px; + } + .ui-tab.ui-selected { + background-color: white; + color: black; + } + .ui-tab.ui-disabled { + background-color: rgb(255 255 255 / 0.5); + color: #666; + cursor: default; + } + .ui-tab:hover:not(.ui-selected, .ui-disabled), + .ui-tab:focus:not(.ui-selected, .ui-disabled) { + background-color: rgb(255 255 255 / 0.8); + } + .ui-tabpanel { + margin-top: 0.5rem; + border-radius: 1rem; + background-color: rgb(254 254 254); + border: 2px solid rgb(59 130 246 / 0.8); + padding: 0.1rem; + min-height: 8rem; + display: flex; + align-items: center; + justify-content: center; + } + .ui-tabpanel:focus { + outline: 2px solid transparent; + outline-offset: 2px; + } + .ui-tabpanel.ui-hidden { + display: none; + } + .ui-tabpanel b { + font-weight: bold; + } + + .ui-tabselect { + display: block; + width: 100%; + border-radius: 0.5rem; + border-width: 1px; + border-color: rgb(209 213 219); + background-color: rgb(249 250 251); + padding: 0.5rem; + font-size: 1rem; + line-height: 1.25rem; + color: rgb(17 24 39); + margin-bottom: 0.5rem; + } + .ui-tabselect:focus { + border-color: rgb(59 130 246); + } + .ui-tabselect:is(.dark *) { + border-color: rgb(75 85 99); + background-color: rgb(55 65 81); + color: rgb(255 255 255); + } + .ui-tabselect:is(.dark *)::-moz-placeholder { + color: rgb(156 163 175); + } + .ui-tabselect:is(.dark *):-ms-input-placeholder { + color: rgb(156 163 175); + } + .ui-tabselect:is(.dark *)::placeholder { + color: rgb(156 163 175); + } + .ui-tabselect:is(.dark *):focus { + border-color: rgb(59 130 246); + } +} + +@scope(.vertical-tabs) { + .ui-tabgroup { + display: flex; + } + .ui-tablist { + flex-direction: column; + width: 10rem; + border-radius: 1rem 0 0 1rem; + padding-right: 0; + } + .ui-tablist > .ui-tab:not([hidden]) ~ .ui-tab:not([hidden]) { + margin: 0.5rem 0 0 0; + } + .ui-tab { + border-radius: 0.5rem 0 0 0.5rem; + padding: 1rem; + } + .ui-tabpanel { + margin: 0; + border-radius: 0 1rem 1rem 0; + padding: 2rem; + min-width: 24rem; + } +}
\ No newline at end of file diff --git a/docs/components/ui/Tabs/VerticalHTML.jinja b/docs/components/ui/Tabs/VerticalHTML.jinja new file mode 100644 index 0000000..1dd7123 --- /dev/null +++ b/docs/components/ui/Tabs/VerticalHTML.jinja @@ -0,0 +1,28 @@ +{% filter markdown %}{% raw %} +```html+jinja +<TabGroup> + <TabList vertical> + <Tab target="vertical-recent" selected>Recent</Tab> + <Tab target="vertical-popular">Popular</Tab> + <Tab target="vertical-disabled" disabled>Disabled</Tab> + <Tab target="vertical-trending">Trending</Tab> + </TabList> + + <TabPanel id="vertical-recent"> + <p>This is the tab panel for <b>"Recent"</b>.</p> + </TabPanel> + + <TabPanel id="vertical-popular" hidden> + <p>This is the tab panel for <b>"Popular"</b>.</p> + </TabPanel> + + <TabPanel id="vertical-disabled" hidden> + <p>This is the tab panel for "Disabled".</p> + </TabPanel> + + <TabPanel id="vertical-trending" hidden> + <p>This is the tab panel for <b>"Trending"</b>.</p> + </TabPanel> +</TabGroup> +``` +{% endraw %}{% endfilter %} diff --git a/docs/components/ui/Tabs/VerticalResult.jinja b/docs/components/ui/Tabs/VerticalResult.jinja new file mode 100644 index 0000000..b83204a --- /dev/null +++ b/docs/components/ui/Tabs/VerticalResult.jinja @@ -0,0 +1,33 @@ +{#css ui/Tabs/Tabs.css #} + +<div class="bg-cover" + style="background-image:linear-gradient(to right, rgba(56,189,248, 0.3), rgba(37,99,235, 0.3))" + data-md-skip +></div> + +<div class="vertical-tabs" data-md-skip> + <TabGroup> + <TabList vertical> + <Tab target="vertical-recent" selected>Recent</Tab> + <Tab target="vertical-popular">Popular</Tab> + <Tab target="vertical-disabled" disabled>Disabled</Tab> + <Tab target="vertical-trending">Trending</Tab> + </TabList> + + <TabPanel id="vertical-recent"> + <p>This is the tab panel for <b>"Recent"</b>.</p> + </TabPanel> + + <TabPanel id="vertical-popular" hidden> + <p>This is the tab panel for <b>"Popular"</b>.</p> + </TabPanel> + + <TabPanel id="vertical-disabled" hidden> + <p>This is the tab panel for "Disabled".</p> + </TabPanel> + + <TabPanel id="vertical-trending" hidden> + <p>This is the tab panel for <b>"Trending"</b>.</p> + </TabPanel> + </TabGroup> +</div> diff --git a/docs/content/api.md b/docs/content/api.md new file mode 100644 index 0000000..b2eaf50 --- /dev/null +++ b/docs/content/api.md @@ -0,0 +1,27 @@ +--- +title: "API reference" +--- + +<Header title="API reference" section={{ None }}> +</Header> + +<Autodoc name="jinjax.Catalog" /> + +---- + +<Autodoc name="jinjax.LazyString" members={{ False }} /> + +<Autodoc name="jinjax.HTMLAttrs" /> + +---- + +## Exceptions + +<Autodoc name="jinjax.ComponentNotFound" level={{ 3 }} members={{ False }} /> + +<Autodoc name="jinjax.MissingRequiredArgument" level={{ 3 }} members={{ False }} /> + +<Autodoc name="jinjax.DuplicateDefDeclaration" level={{ 3 }} members={{ False }} /> + +<Autodoc name="jinjax.InvalidArgument" level={{ 3 }} members={{ False }} /> + diff --git a/docs/content/guide/components.md b/docs/content/guide/components.md new file mode 100644 index 0000000..ac8a77f --- /dev/null +++ b/docs/content/guide/components.md @@ -0,0 +1,348 @@ +--- +title: Components +description: Declaring and using components. +--- + +<Header title="Components"> +</Header> + +## Declaring and Using Components + +The components are simple text files that look like regular Jinja templates, with three requirements: + +**First**, components must be placed inside a folder registered in the catalog or a subfolder of it. + +```python +catalog.add_folder("myapp/components") +``` + +You can call that folder whatever you want, not just "components". You can also add more than one folder: + +```python +catalog.add_folder("myapp/layouts") +catalog.add_folder("myapp/components") +``` + +If you end up having more than one component with the same name, the one in the first folder will take priority. + +**Second**, they must have a ".jinja" extension. This also helps code editors automatically select the correct language syntax to highlight. However, you can configure it in the catalog. + +**Third**, the component name must start with an uppercase letter. Why? This is how JinjaX differentiates a component from a regular HTML tag when using it. I recommend using PascalCase names, like Python classes. + +The name of the file (minus the extension) is also how you call the component. For example, if the file is "components/PersonForm.jinja": + +``` +└ myapp/ + ├── app.py + ├── components/ + └─ PersonForm.jinja +``` + +The name of the component is "PersonForm" and can be called like this: + +From Python code or a non-component template: + +- `catalog.render("PersonForm")` + +From another component: + +- `<PersonForm> some content </PersonForm>`, or +- `<PersonForm />` + +If the component is in a subfolder, the name of that folder becomes part of its name too: + +``` +└ myapp/ + ├── app.py + ├── components/ + └─ person + └─ PersonForm.jinja +``` + +A "components/person/PersonForm.jinja" component is named "person.PersonForm", meaning the name of the subfolder and the name of the file separated by a dot. This is the full name you use to call it: + +From Python code or a non-component template: + +- `catalog.render("person.PersonForm")` + +From another component: + +- `<person.PersonForm> some content </person.PersonForm>`, or +- `<person.PersonForm />` + +Notice how the folder name doesn't need to start with an uppercase if you don't want it to. + +<a href="/static/img/anatomy-en.png" target="_blank"> + <img src="/static/img/anatomy-en.png" style="margin:0 auto;width:90%;max-width:35rem;"> +</a> + +## Taking Arguments + +More often than not, a component takes one or more arguments to render. Every argument must be declared at the beginning of the component with `{#def arg1, arg2, ... #}`. + +```html+jinja +{#def action, method="post", multipart=False #} + +<form method="{{ method }}" action="{{ action }}" + {%- if multipart %} enctype="multipart/form-data"{% endif %} +> + {{ content }} +</form> +``` + +In this example, the component takes three arguments: "action", "method", and "multipart". The last two have default values, so they are optional, but the first one doesn't. That means it must be passed a value when rendering the component. + +The syntax is exactly like how you declare the arguments of a Python function (in fact, it's parsed by the same code), so it can even include type comments, although they are not used by JinjaX (yet!). + +```python +{#def + data: dict[str, str], + method: str = "post", + multipart: bool = False +#} +... +``` + +## Passing Arguments + +There are two types of arguments: strings and expressions. + +### String + +Strings are passed like regular HTML attributes: + +```html+jinja +<Form action="/new" method="PATCH"> ... </Form> + +<Alert message="Profile updated" /> + +<Card title="Hello world" type="big"> ... </Card> +``` + +### Expressions + +There are two different but equivalent ways to pass non-string arguments: + +"Jinja-like", where you use double curly braces instead of quotes: + +```html+jinja title="Jinja-like" +<Example + columns={{ 2 }} + tabbed={{ False }} + panels={{ {'one': 'lorem', 'two': 'ipsum'} }} + class={{ 'bg-' + color }} +/> +``` + +... and "Vue-like", where you keep using quotes, but prefix the name of the attribute with a colon: + +```html+jinja title="Vue-like" +<Example + :columns="2" + :tabbed="False" + :panels="{'one': 'lorem', 'two': 'ipsum'}" + :class="'bg-' + color" +/> +``` + +<Callout type="note"> + For `True` values, you can just use the name, like in HTML: + <br> + ```html+jinja + <Example class="green" hidden /> + ``` +</Callout> + +<Callout type="note"> + You can also use dashes when passing an argument, but they will be translated to underscores: + <br> + ```html+jinja + <Example aria-label="Hi" /> + ``` + <br> + ```html+jinja title="Example.jinja" + {#def aria_label = "" #} + ... + ``` +</Callout> + +## With Content + +There is always an extra implicit argument: **the content** inside the component. Read more about it in the [next](/guide/slots) section. + +## Extra Arguments + +If you pass arguments not declared in a component, those are not discarded but rather collected in an `attrs` object. + +You then call `attrs.render()` to render the received arguments as HTML attributes. + +For example, this component: + +```html+jinja title="Card.jinja" +{#def title #} +<div {{ attrs.render() }}> + <h1>{{ title }}</h1> + {{ content }} +</div> +``` + +Called as: + +```html +<Card title="Products" class="mb-10" open>bla</Card> +``` + +Will be rendered as: + +```html +<div class="mb-10" open> + <h1>Products</h1> + bla +</div> +``` + +You can add or remove arguments before rendering them using the other methods of the `attrs` object. For example: + +```html+jinja +{#def title #} +{% do attrs.set(id="mycard") -%} + +<div {{ attrs.render() }}> + <h1>{{ title }}</h1> + {{ content }} +</div> +``` + +Or directly in the `attrs.render()` call: + +```html+jinja +{#def title #} + +<div {{ attrs.render(id="mycard") }}> + <h1>{{ title }}</h1> + {{ content }} +</div> +``` + +<Callout type="info"> +The string values passed into components as attrs are not cast to `str` until the string representation is **actually** needed, for example when `attrs.render()` is invoked. +</Callout> + +### `attrs` Methods + +#### `.render(name=value, ...)` + +Renders the attributes and properties as a string. + +Any arguments you use with this function are merged with the existing +attibutes/properties by the same rules as the `HTMLAttrs.set()` function: + +- Pass a name and a value to set an attribute (e.g. `type="text"`) +- Use `True` as a value to set a property (e.g. `disabled`) +- Use `False` to remove an attribute or property +- The existing attribute/property is overwritten **except** if it is `class`. + The new classes are appended to the old ones instead of replacing them. +- The underscores in the names will be translated automatically to dashes, + so `aria_selected` becomes the attribute `aria-selected`. + +To provide consistent output, the attributes and properties +are sorted by name and rendered like this: +`<sorted attributes> + <sorted properties>`. + +```html+jinja +<Example class="ipsum" width="42" data-good /> +``` +```html+jinja +<div {{ attrs.render() }}> +<!-- <div class="ipsum" width="42" data-good> --> + +<div {{ attrs.render(class="abc", data_good=False, tabindex=0) }}> +<!-- <div class="abc ipsum" width="42" tabindex="0"> --> +``` + +<Callout type="warning"> +Using `<Component {{ attrs.render() }}>` to pass the extra arguments to other components **WILL NOT WORK**. That is because the components are translated to macros before the page render. + +You must pass them as the special argument `_attrs`. + +```html+jinja +{#--- WRONG 😵 ---#} +<MyButton {{ attrs.render() }} /> + +{#--- GOOD 👍 ---#} +<MyButton _attrs={{ attrs }} /> +<MyButton :_attrs="attrs" /> +``` +</Callout> + +#### `.set(name=value, ...)` + +Sets an attribute or property + +- Pass a name and a value to set an attribute (e.g. `type="text"`) +- Use `True` as a value to set a property (e.g. `disabled`) +- Use `False` to remove an attribute or property +- If the attribute is "class", the new classes are appended to + the old ones (if not repeated) instead of replacing them. +- The underscores in the names will be translated automatically to dashes, + so `aria_selected` becomes the attribute `aria-selected`. + +```html+jinja title="Adding attributes/properties" +{% do attrs.set( + id="loremipsum", + disabled=True, + data_test="foobar", + class="m-2 p-4", +) %} +``` + +```html+jinja title="Removing attributes/properties" +{% do attrs.set( + title=False, + disabled=False, + data_test=False, + class=False, +) %} +``` + +#### `.setdefault(name=value, ...)` + +Adds an attribute, but only if it's not already present. + +The underscores in the names will be translated automatically to dashes, so `aria_selected` +becomes the attribute `aria-selected`. + +```html+jinja +{% do attrs.setdefault( + aria_label="Products" +) %} +``` + +#### `.add_class(name1, name2, ...)` + +Adds one or more classes to the list of classes, if not already present. + +```html+jinja +{% do attrs.add_class("hidden") %} +{% do attrs.add_class("active", "animated") %} +``` + +#### `.remove_class(name1, name2, ...)` + +Removes one or more classes from the list of classes. + +```html+jinja +{% do attrs.remove_class("hidden") %} +{% do attrs.remove_class("active", "animated") %} +``` + +#### `.get(name, default=None)` + +Returns the value of the attribute or property, +or the default value if it doesn't exist. + +```html+jinja +{%- set role = attrs.get("role", "tab") %} +``` + +...
\ No newline at end of file diff --git a/docs/content/guide/css_and_js.md b/docs/content/guide/css_and_js.md new file mode 100644 index 0000000..8e296e2 --- /dev/null +++ b/docs/content/guide/css_and_js.md @@ -0,0 +1,230 @@ +--- +title: Adding CSS and JS +description: Your components might need custom styles or custom JavaScript for many reasons. +--- + +<Header title="Adding CSS and JS"> +Your components might need custom styles or custom JavaScript for many reasons. +</Header> +Instead of using global stylesheet or script files, writing assets for each individual component has several advantages: + +- **Portability**: You can copy a component from one project to another, knowing it will keep working as expected. +- **Performance**: Only load the CSS and JS that you need on each page. Additionally, the browser will have already cached the assets of the components for other pages that use them. +- **Simple testing**: You can test the JS of a component independently from others. + +## Auto-loading assets + +JinjaX searches for `.css` and `.js` files with the same name as your component in the same folder and automatically adds them to the list of assets included on the page. For example, if your component is `components/common/Form.jinja`, both `components/common/Form.css` and `components/common/Form.js` will be added to the list, but only if those files exist. + +## Manually declaring assets + +In addition to auto-loading assets, the CSS and/or JS of a component can be declared in the metadata header with `{#css ... #}` and `{#js ... #}`. + +```html +{#css lorem.css, ipsum.css #} +{#js foo.js, bar.js #} +``` + +- The file paths must be relative to the root of your components catalog (e.g., `components/form.js`) or absolute (e.g., `http://example.com/styles.css`). +- Multiple assets must be separated by commas. +- Only **one** `{#css ... #}` and **one** `{#js ... #}` tag is allowed per component at most, but both are optional. + +### Global assets + +The best practice is to store both CSS and JS files of the component within the same folder. Doing this has several advantages, including easier component reuse in other projects, improved code readability, and simplified debugging. + +However, there are instances when you may need to rely on global CSS or JS files, such as third-party libraries. In such cases, you can specify these dependencies in the component's metadata using URLs that start with either "/", "http://," or "https://." + +When you do this, JinjaX will render them as is, instead of prepending them with the component's prefix like it normally does. + +For example, this code: + +```html+jinja +{#css foo.css, bar.css, /static/bootstrap.min.css #} +{#js http://example.com/cdn/moment.js, bar.js #} + +{{ catalog.render_assets() }} +``` + +will be rendered as this HTML output: + +```html +<link rel="stylesheet" href="/static/components/foo.css"> +<link rel="stylesheet" href="/static/components/bar.css"> +<link rel="stylesheet" href="/static/bootstrap.min.css"> +<script type="module" src="http://example.com/cdn/moment.js"></script> +<script type="module" src="/static/components/bar.js"></script> +``` + +## Including assets in your pages + +The catalog will collect all CSS and JS file paths from the components used on a "page" render on the `catalog.collected_css` and `catalog.collected_js` lists. + +For example, after rendering this component: + +```html+jinja title="components/MyPage.jinja" +{#css mypage.css #} +{#js mypage.js #} + +<Layout title="My page"> + <Card> + <CardBody> + <h1>Lizard</h1> + <p>The Iguana is a type of lizard</p> + </CardBody> + <CardActions> + <Button size="small">Share</Button> + </CardActions> + </Card> +</Layout> +``` + +Assuming the `Card` and `Button` components declare CSS assets, this will be the state of the `collected_css` list: + +```py +catalog.collected_css +['mypage.css', 'card.css', 'button.css'] +``` + +You can add the `<link>` and `<script>` tags to your page automatically by calling `catalog.render_assets()` like this: + +```html+jinja title="components/Layout.jinja" hl_lines="8" +{#def title #} + +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="utf-8"> + <title>{{ title }}</title> + {{ catalog.render_assets() }} +</head> +<body> + {{ content }} +</body> +</html> +``` + +The variable will be rendered as: + +```html +<link rel="stylesheet" href="/static/components/mypage.css"> +<link rel="stylesheet" href="/static/components/card.css"> +<link rel="stylesheet" href="/static/components/button.css"> +<script type="module" src="/static/components/mypage.js"></script> +<script type="module" src="/static/components/card.js"></script> +<script type="module" src="/static/components/button.js"></script> +``` + +## Middleware + +The tags above will not work if your application can't return the content of those files. Currently, it can't. + +For that reason, JinjaX includes WSGI middleware that will process those URLs if you add it to your application. + +```py +from flask import Flask +from jinjax import Catalog + +app = Flask(__name__) + +# Here we add the Flask Jinja globals, filters, etc., like `url_for()` +catalog = jinjax.Catalog(jinja_env=app.jinja_env) + +catalog.add_folder("myapp/components") + +app.wsgi_app = catalog.get_middleware( + app.wsgi_app, + autorefresh=app.debug, +) +``` + +The middleware uses the battle-tested [Whitenoise library](http://whitenoise.evans.io/) and will only respond to the *.css* and *.js* files inside the component(s) folder(s). You can configure it to also return files with other extensions. For example: + +```python +catalog.get_middleware(app, allowed_ext=[".css", .js", .svg", ".png"]) +``` + +Be aware that if you use this option, `get_middleware()` must be called **after** all folders are added. + +## Good practices + +### CSS Scoping + +The styles of your components will not be auto-scoped. This means the styles of a component can affect other components and likewise, it will be affected by global styles or the styles of other components. + +To protect yourself against that, *always* add a custom class to the root element(s) of your component and use it to scope the rest of the component styles. + +You can even use this syntax now supported by [all modern web browsers](https://caniuse.com/css-nesting): + +```sass +.Parent { + .foo { ... } + .bar { ... } +} +``` + +The code above will be interpreted as + +```css +.Parent .foo { ... } +.Parent .bar { ... } +``` + +Example: + +```html+jinja title="components/Card.jinja" +{#css card.css #} + +<div {{ attrs.render(class="Card") }}> + <h1>My Card</h1> + ... +</div> +``` + +```sass title="components/card.css" +/* 🚫 DO NOT do this */ +h1 { font-size: 2em; } +h2 { font-size: 1.5em; } +a { color: blue; } + +/* 👍 DO THIS instead */ +.Card { + & h1 { font-size: 2em; } + & h2 { font-size: 1.5em; } + & a { color: blue; } +} + +/* 👍 Or this */ +.Card h1 { font-size: 2em; } +.Card h2 { font-size: 1.5em; } +.Card a { color: blue; } +``` + +<Callout type="warning"> +Always use a class **instead of** an `id`, or the component will not be usable more than once per page. +</Callout> + +### JS events + +Your components might be inserted in the page on-the-fly, after the JavaScript files have been loaded and executed. So, attaching events to the elements on the page on load will not be enough: + +```js title="components/card.js" +// This will fail for any Card component inserted after page load +document.querySelectorAll('.Card button.share') + .forEach((node) => { + node.addEventListener("click", handleClick) + }) + +/* ... etc ... */ +``` + +A solution can be using event delegation: + +```js title="components/card.js" +// This will work for any Card component inserted after page load +document.addEventListener("click", (event) => { + if (event.target.matches(".Card button.share")) { + handleClick(event) + } +}) +``` diff --git a/docs/content/guide/index.md b/docs/content/guide/index.md new file mode 100644 index 0000000..0c092ea --- /dev/null +++ b/docs/content/guide/index.md @@ -0,0 +1,196 @@ +--- +title: Introduction +--- + +<Header title="Introduction"> +JinjaX is a Python library for creating reusable "components": encapsulated template snippets that can take arguments and render to HTML. They are similar to React or Vue components, but they render on the server side, not in the browser. +</Header> + +Unlike Jinja's `{% include "..." %}` or macros, JinjaX components integrate naturally with the rest of your template code. + +```html+jinja +<div> + <Card class="bg-gray"> + <h1>Products</h1> + {% for product in products %} + <Product product={{ product }} /> + {% endfor %} + </Card> +</div> +``` + +## Features + +### Simple + +JinjaX components are simple Jinja templates. You use them as if they were HTML tags without having to import them: easy to use and easy to read. + +### Encapsulated + +They are independent of each other and can link to their own CSS and JS, so you can freely copy and paste components between applications. + +### Testable + +All components can be unit tested independently of the pages where they are used. + +### Composable + +A JinjaX component can wrap HTML code or other components with a natural syntax, as if they were another tag. + +### Modern + +They are a great complement to technologies like [TailwindCSS](https://tailwindcss.com/), [htmx](https://htmx.org/), or [Hotwire](https://hotwired.dev/). + +## Usage + +#### Install + +Install the library using `pip`. + +```bash +pip install jinjax +``` + +#### Components folder + +Then, create a folder that will contain your components, for example: + +``` +└ myapp/ + ├── app.py + ├── components/ 🆕 + │ └── Card.jinja 🆕 + ├── static/ + ├── templates/ + └── views/ +└─ requirements.txt +``` + +#### Catalog + +Finally, you must create a "catalog" of components in your app. This is the object that manages the components and their global settings. You then add the path of the folder with your components to the catalog: + +```python +from jinjax import Catalog + +catalog = Catalog() +catalog.add_folder("myapp/components") +``` + +#### Render + +You will use the catalog to render components from your views. + +```python +def myview(): + ... + return catalog.render( + "Page", + title="Lorem ipsum", + message="Hello", + ) +``` + +In this example, it is a component for the whole page, but you can also render smaller components, even from inside a regular Jinja template if you add the catalog as a global: + +```python +app.jinja_env.globals["catalog"] = catalog +``` + +```html+jinja +{% block content %} +<div> + {{ catalog.irender("LikeButton", title="Like and subscribe!", post=post) }} +</div> +<p>Lorem ipsum</p> +{{ catalog.irender("CommentForm", post=post) }} +{% endblock %} +``` + +## How It Works + +JinjaX uses Jinja to render the component templates. In fact, it currently works as a pre-processor, replacing all: + +```html +<Component attr="value">content</Component> +``` + +with function calls like: + +```html+jinja +{% call catalog.irender("Component", attr="value") %}content{% endcall %} +``` + +These calls are evaluated at render time. Each call loads the source of the component file, parses it to extract the names of CSS/JS files, required and/or optional attributes, pre-processes the template (replacing components with function calls, as before), and finally renders the new template. + +### Reusing Jinja's Globals, Filters, and Tests + +You can add your own global variables and functions, filters, tests, and Jinja extensions when creating the catalog: + +```python +from jinjax import Catalog + +catalog = Catalog( + globals={ ... }, + filters={ ... }, + tests={ ... }, + extensions=[ ... ], +) +``` + +or afterward. + +```python +catalog.jinja_env.globals.update({ ... }) +catalog.jinja_env.filters.update({ ... }) +catalog.jinja_env.tests.update({ ... }) +catalog.jinja_env.extensions.extend([ ... ]) +``` + +The ["do" extension](https://jinja.palletsprojects.com/en/3.0.x/extensions/#expression-statement) is enabled by default, so you can write things like: + +```html+jinja +{% do attrs.set(class="btn", disabled=True) %} +``` + +### Reusing an Existing Jinja Environment + +You can also reuse an existing Jinja Environment, for example: + +#### Flask: + +```python +app = Flask(__name__) + +# Here we add the Flask Jinja globals, filters, etc., like `url_for()` +catalog = jinjax.Catalog(jinja_env=app.jinja_env) +``` + +#### Django: + +First, configure Jinja in `settings.py` and [jinja_env.py](https://docs.djangoproject.com/en/5.0/topics/templates/#django.template.backends.jinja2.Jinja2). + +To have a separate "components" folder for shared components and also have "components" subfolders at each Django app level: + +```python +import jinjax +from jinja2.loaders import FileSystemLoader + +def environment(loader: FileSystemLoader, **options): + env = Environment(loader=loader, **options) + + ... + + env.add_extension(jinjax.JinjaX) + catalog = jinjax.Catalog(jinja_env=env) + + catalog.add_folder("components") + for dir in loader.searchpath: + catalog.add_folder(os.path.join(dir, "components")) + + return env +``` + +#### FastAPI: + +TBD
\ No newline at end of file diff --git a/docs/content/guide/integrations.md b/docs/content/guide/integrations.md new file mode 100644 index 0000000..0884d22 --- /dev/null +++ b/docs/content/guide/integrations.md @@ -0,0 +1,3 @@ +--- +title: Integrations +---
\ No newline at end of file diff --git a/docs/content/guide/motivation.md b/docs/content/guide/motivation.md new file mode 100644 index 0000000..90602b5 --- /dev/null +++ b/docs/content/guide/motivation.md @@ -0,0 +1,115 @@ +--- +title: Motivation +--- +<Header title="Motivation"> +An overview of what Jinja is about, and a glimpse into my disjointed decision-making process that got me here. +</Header> + +## Components are cool + +Despite the complexity of a single-page application, some programmers claim React or Vue offer a better development experience than traditional server-side rendered templates. I believe this is mostly because of the greatest improvement React introduced to web development: components. + +<small> +Components, *as a way to organize template code*. Reactivity is cool too, but unrelated to the main issue. +</small> + +When writing Python, we aim for the code to be easy to understand and test. However, we often forget all of that when writing templates that don't even meet basic standards: long methods, deep conditional nesting, and mysterious variables everywhere. + +Components are way cooler than the HTML soup tag of server-side rendered templates. They make it very clear what arguments they take and how they can render. More than anything, components are modular: markup, logic, and relevant styles all in one package. You can copy and paste them between projects, and you can share them with other people. + +This means a community has formed around sharing these components. Now you can easily find hundreds of ready-to-use components—some of them very polished—for every common UI widget, even the "complex" ones, like color-pickers. The big problem is that you can only use them with React (and Vue components with Vue, etc.) and in a single-page application. + +Jinja is about bringing that innovation back to server-side-rendered applications. + +## Not quite there: Jinja macros + +An underestimated feature of Jinja is *macros*. Jinja [macros](https://jinja.palletsprojects.com/en/3.0.x/templates/#macros) are template snippets that work like functions: They can have positional or keyword arguments, and when called return the rendered text inside. + +```html+jinja +{% macro input(name, value="", type="text", size=20) -%} + <input type="{{ type }}" name="{{ name }}" + value="{{ value|e }}" size="{{ size }}"> +{%- endmacro %} + +{% macro button(type="button") -%} + <button type="{{ type }}" class="btn-blue"> + {{ caller() }} + </button> +{%- endmacro %} +``` + +You can then import the macro to your template to use it: + +```html+jinja +{% from 'forms.html' import input, button %} + +<p>{{ input("username") }}</p> +<p>{{ input("password", type="password") }}</p> +{% call button("submit") %}Submit{% endcall %} +``` +You must use the `{% call x %}` to pass the child content to the macro—by using the weird incantation `{{ caller() }}`—otherwise you can just call it like it were a function. + +So, can we use macros as components and call it a day? Well... no. This looks terrible: + +```html+jinja +{% call Card(label="Hello") %} + {% call MyButton(color="blue", shadowSize=2) %} + {{ Icon(name="ok") }} Click Me + {% endcall %} +{% endcall %} +``` + +compared to how you would write it with JSX: + +```html +<Card label="Hello"> + <MyButton color="blue" shadowSize={2}> + <Icon name="ok" /> Click Me + </MyButton> +</Card> +``` + +But macros are *almost* there. They would be a great foundation if we could adjust the syntax just a little. + +## Strong alternative: Mako + +At some point, I considered dropping this idea and switching to [Mako](https://www.makotemplates.org/), a template library by Michael Bayer (of SQLAlchemy fame). + +It's a hidden gem that doesn't get much attention because of network effects. See how close you can get with it: + +```html+mako +<%def name="layout()"> # <--- A "macro" + <div class="mainlayout"> + <div class="header"> + ${caller.header()} + </div> + + <div class="sidebar"> + ${caller.sidebar()} + </div> + + <div class="content"> + ${caller.body()} + </div> + </div> +</%def> + +## calls the layout def <--- Look! Python-style comments + +<%self:layout> + <%def name="header()"> # <--- This is like a "slot"! + I am the header + </%def> + <%def name="sidebar()"> + <ul> + <li>sidebar 1</li> + <li>sidebar 2</li> + </ul> + </%def> + this is the body +</%self:layout> +``` + +Mako also has `<% include %>`s with arguments, which is another way of doing components if you don't need to pass content. + +However, in the end, the network effects, my familiarity with Jinja, and a little of not-invented-here syndrome tipped the scales to write a Jinja extension. diff --git a/docs/content/guide/performance.md b/docs/content/guide/performance.md new file mode 100644 index 0000000..609b952 --- /dev/null +++ b/docs/content/guide/performance.md @@ -0,0 +1,3 @@ +--- +title: Performance +--- diff --git a/docs/content/guide/slots.md b/docs/content/guide/slots.md new file mode 100644 index 0000000..991f327 --- /dev/null +++ b/docs/content/guide/slots.md @@ -0,0 +1,175 @@ +--- +title: Slots / Content +description: Working with content in components. +--- + +<Header title="Slots / Content"> +Besides attributes, components can also accept content to render inside them. +</Header> + +Everything between the open and close tags of the components will be rendered and passed to the component as an implicit `content` variable + +This is a very common pattern, and it is called a **_slot_**. A slot is a placeholder for content that can be provided by the user of the component. For example, we may have a `<FancyButton>` component that supports usage like this: + +```html+jinja +<FancyButton> + <i class="icon></i> Click me! +</FancyButton> +``` + +The template of `<FancyButton>` looks like this: + +```html+jinja +<button class="fancy-btn"> + {{ content }} +</button> +``` + + + +The `<FancyButton>` is responsible for rendering the outer `<button>` (and its fancy styling), while the inner content is provided by the parent component. + +A great use case of the `content` is to make layout components: + +<ExampleTabs + prefix="slots-layouts" + panels={{ { + "ArchivePage.jinja": "guide.slots.CompArchive", + "Layout.jinja": "guide.slots.CompLayout", + } }} +/> + + +## Fallback Content + +There are cases when it's useful to specify fallback (i.e. default) content for a slot, to be rendered only when no content is provided. For example, in a `<SubmitButton>` component: + +```html+jinja +<button type="submit"> + {{ content }} +</button> +``` + +We might want the text "Submit" to be rendered inside the `<button>` if the parent didn't provide any slot content. The special "content" variable is just a string like any other, so we can test if it's empty to make "Submit" the fallback content: + +```html+jinja +<button type="submit"> + {% if content %} + {{ content }} + {% else %} + Submit <!-- fallback content --> + {% endif %} +</button> +``` + +Now when we use `<SubmitButton>` in a parent component, providing no content for the slot: + +```html+jinja +<SubmitButton /> +``` + +<Callout type="info"> +The `content` of a self-closing component is an empty string. +</Callout> + +This will render the fallback content, "Submit": + +```html +<button type="submit">Submit</button> +``` + +But if we provide content: + +```html+jinja +<SubmitButton>Save</SubmitButton> +``` + +Then the provided content will be rendered instead: + +```html +<button type="submit">Save</button> +``` + + +## Multiple content slots (a.k.a. "named slots") + +There are cases when a component is complex enough to need multiple content slots. For example, a `<Modal>` component might need a `header`, a `body`, and a `footer` content. + +One way to implement it is using multiple content slots. To do so, instead of rendering `content` as a string, you can also _call_ it with name. Then, the parent component can provide a content _for_ that name. + + + +Note the `_slot` special variable. This is automatically available in the content in the parent component and contains the named the component has used to call request its content. + +The `_slot` variable is scoped to the content of that component, so it's not available outside of it: + +```html+jinja hl_lines="2 7 11" +<FancyButton> + {% if _slot == "hi" %} {# <--- _slot #} + Hello{% endif %} +</FancyButton> + +<FancyButton2> + {% if _slot == "hi" %} {# <--- This _slot is a different one #} + Sup?{% endif %} +</FancyButton2> + +{{ _slot }} {# <--- Undefined variable #} +``` + + +## Composability: better than named slots + +Named slots are a quick way to have multiple content slots, but are a bit messy beyond some simple cases. + +Composability offers a more flexible and idiomatic approach when multiple content slots are needed. The idea is to have separated components for each content slot, and then compose them together. Let's explore this concept using the same example as above. + +Consider a `Modal` component that requires three distinct sections: a header, a body, and a footer. Instead of using named slots, we can create separate components for each section and composing them within a `Modal` component wrapper. + +```html+jinja +<Modal> + + <ModalHeader> + <i class="icon-rocket"></i> + Hello World! + </ModalHeader> + + <ModalBody> + <p>The modal body.</p> + </ModalBody> + + <ModalFooter> + <button>Cancel</button> + <button>Save</button> + </ModalFooter> + +</Modal> +``` + +Now, the `Modal` component is responsible for rendering the outer `<dialog>` and its styling, while the inner content is provided by the child components. + +<ExampleTabs + prefix="slots-modal" + panels={{ { + "Modal.jinja": "guide.slots.Modal", + "ModalHeader.jinja": "guide.slots.ModalHeader", + "ModalBody.jinja": "guide.slots.ModalBody", + "ModalFooter.jinja": "guide.slots.ModalFooter", + } }} +/> + +### Advantages of Composability + +- **Flexibility**: You can easily rearrange, omit, or add new sections without modifying the core `Modal` component. +- **Reusability**: Each section (`ModalHeader`, `ModalBody`, `ModalFooter`) can be used independently or within other components. +- **Maintainability**: It's easier to update or style individual sections without affecting the others. + + +## Testing components with content + +To test a component in isolation, you can manually send a content argument using the special `_content` argument: + +```python +catalog.render("PageLayout", title="Hello world", _content="TEST") +``` + diff --git a/docs/content/index.md b/docs/content/index.md new file mode 100644 index 0000000..69796da --- /dev/null +++ b/docs/content/index.md @@ -0,0 +1,8 @@ +--- +title: Welcome +component: PageSingle +description: Super components powers for your Jinja templates +social_card: SocialCardIndex +--- + +<Home /> diff --git a/docs/content/ui/accordion.md b/docs/content/ui/accordion.md new file mode 100644 index 0000000..8676fd5 --- /dev/null +++ b/docs/content/ui/accordion.md @@ -0,0 +1,43 @@ +--- +title: Accordion +description: Component for grouping <details> HTML elements where only one of them can be open at the same time. +--- + +<Header title="Accordion" section="UI components"> + Component for grouping <code>details</code> HTML elements where only one of them can be open at the same time. +</Header> + +An accordion is a vertically stacked group of collapsible sections. HTML has already a native element for this, the `<details>` element, but it doesn't support the "only one open at a time" behavior, so we need to add some JS to make it work, and that's what this component does. + +If you don't need to ensure only one section is open at a time, you don't need this component at all, just use the `<details>` element directly. + +<ExampleTabs + prefix="demo" + :panels="{ + 'Result': 'ui.Accordion.DemoResult', + 'HTML': 'ui.Accordion.DemoHTML', + 'CSS': 'ui.Accordion.DemoCSS', + }" +/> + + +The `Accordion` is a simple wrapper plus some JS logic, so it doesn't uses any arguments and it's as accesible as the `details` element you put inside. + + +## Events + +The `Accordion` doesn't emit or listen to any events, but the `<details>` elements inside do. + +In addition to the usual events supported by HTML elements, the `<details>` element supports the `toggle` event, which is dispatched to the `<details>` element whenever its state changes between open and closed. The `Accordion` component listen to it to be able to close the other `<details>` elements when one is opened. + +The `toggle` event is sent *after* the state is changed, although if the state changes multiple times before the browser can dispatch the event, the events are coalesced so that only one is sent. + +```js +details.addEventListener("toggle", (event) => { + if (details.open) { + /* the element was toggled open */ + } else { + /* the element was toggled closed */ + } +}); +``` diff --git a/docs/content/ui/index.md b/docs/content/ui/index.md new file mode 100644 index 0000000..0a406a4 --- /dev/null +++ b/docs/content/ui/index.md @@ -0,0 +1,58 @@ +--- +title: UI components +description: Unstyled, fully accessible UI components, to integrate with your projects. +--- + +<Header title="UI components" :section="false"> + Unstyled, fully accessible UI components, to integrate with your projects. +</Header> + +<div class="cd-cards not-prose"> + <a class="card" href="/ui/tabs"> + <h2>Tabs</h2> + <img src="/static/img/ui-tabs.png" /> + </a> + <a class="card" href="/ui/popover"> + <h2>Popover</h2> + <img src="/static/img/ui-popover.png" /> + </a> + <a class="card" href="/ui/menu"> + <h2>Menu</h2> + <img src="/static/img/ui-menu.png" /> + </a> + <a class="card" href="/ui/accordion"> + <h2>Accordion</h2> + <img src="/static/img/ui-accordion.png" /> + </a> + <a class="card" href="/ui/linkedlist"> + <h2>LinkedList</h2> + <img src="/static/img/ui-linkedlist.png" /> + </a> + <a class="card" href="/ui/reldate"> + <h2>RelDate</h2> + <img src="/static/img/ui-reldate.png" /> + </a> +</div> + + +## How to use + +1. Install the `jinjax-ui` python library doing + + ```bash + pip install jinjax-ui + ``` + +2. Add it to your *JinjaX* catalog: + + ```python + import jinjax_ui + + catalog.add_folder(jinjax_ui.components_path, prefix="") + ``` + +3. Use the UI components in your components/templates: + + ```html+jinja + <Popover> ... </Popover> + ```
\ No newline at end of file diff --git a/docs/content/ui/linkedlist.md b/docs/content/ui/linkedlist.md new file mode 100644 index 0000000..ac3fce2 --- /dev/null +++ b/docs/content/ui/linkedlist.md @@ -0,0 +1,19 @@ +--- +title: Linked Lists +description: A component to select multiple items from a long list, while keeping them sorted. +--- + +<Header title="Linked Lists" section="UI components"> + A component to select multiple items from a long list, while keeping them sorted. +</Header> + +<ExampleTabs + prefix="demo" + :panels="{ + 'Result': 'ui.LinkedList.DemoResult', + 'HTML': 'ui.LinkedList.DemoHTML', + 'CSS': 'ui.LinkedList.DemoCSS', + }" +/> + +<Callout>The checkboxes above are displayed so you can see how they get checked/unchecked. If you might want to hide them with CSS, the component will keep working as usual, but they must be present.</Callout> diff --git a/docs/content/ui/menu.md b/docs/content/ui/menu.md new file mode 100644 index 0000000..12539d5 --- /dev/null +++ b/docs/content/ui/menu.md @@ -0,0 +1,112 @@ +--- +title: Menu (Dropdown) +description: Displays a list of options that a user can choose with robust support for keyboard navigation. Built using the Popover API. +--- + +<Header title="Menu" section="UI components"> + Displays a list of options that a user can choose with robust support for + keyboard navigation. Built using the Popover API. +</Header> + +<ExampleTabs + prefix="menu-demo" + :panels="{ + 'Result': 'ui.Menu.DemoResult', + 'HTML': 'ui.Menu.DemoHTML', + 'CSS': 'ui.Menu.DemoCSS', + }" +/> + +**Note:** This component does not handle keyboard shortcuts, here are shown only as an example. + +Menus are built using the `Menu`, `MenuButton`, `MenuItem`, and `MenuItemSub` components. Clicking on menu button or activating it with the keyboard will show the corresponding menu. + +```html+jinja +<MenuButton>Open menu</<MenuButton> +<Menu> + <MenuItem> item1 </MenuItem> 〈-- Regular item + <MenuItem> item2 </MenuItem> + <MenuItem> item3 </MenuItem> + <MenuItemSub> item4 〈----------- An item with a submenu + <Menu> ... </Menu>〈----------- Submenu + </MenuItemSub> +</Menu> +``` + +A `Menu` starts hidden on page load by having `display:none` set on it (the Popover API does it automatically). To show/hide the menu, you need to add a `MenuButton`. + +When a `Menu` is shown, it has `display:none` removed from it and it is put into the top layer so, unlike just using `position: absolute`, it's guaranteed that it will sit on top of all other page content. + + +## Anchor positioning + +By default, the menu appears centered in the layout view, but this component allows you to position it relative to an specific element in the page, using the `anchor` and `anchor-to` attributes. + +`anchor` is the ID of the element used as a reference, and `anchor-to` which side of the anchor to use: "top", "bottom", "right", or "left"; with an optional postfix of "start" or "end" ("center" is the default). + +<p> + <img src="/static/img/anchors.png" alt="Anchor positioning" + width="595" height="324" style="display:block;margin:60px auto;" /> +</p> + +The positioning is done every time the menu opens, but you can trigger the re-position, for example, on windows resizing, by calling the `jxui-popover/setPosition(menu)` function. + + +## Styling states + +| CSS selector | Description +| ----------------------- | -------------- +| `.ui-menu` | Every menu has this class +| `.ui-menu:popover-open` | This pseudo-class matches only menus that are currently being shown +| `::backdrop` | This pseudo-element is a full-screen element placed directly behind showing menu elements in the top layer, allowing effects to be added to the page content behind the menu(s) if desired. You might for example want to blur out the content behind the menu to help focus the user's attention on it + +To animate a menu, follow the [Animating popovers section](/headless/popover#animating-popovers) in the Popover page. + + +## Component arguments + +### MenuButton + +| Argument | Type | Default | Description +| --------------- | --------- | ---------- | -------------- +| `target` | `str` | | Required. The ID of the linked `Popover` component. +| `action` | `str` | `"toggle"` | `"open"`, `"close"`, or `"toggle"`. +| `tag` | `str` | `"button"` | HTML tag of the component. + +### Menu + +| Argument | Type | Default | Description +| ------------ | ----- | -------- | -------------- +| `mode` | `str` | `"auto"` | `"auto"` or `"manual"`. +| `anchor` | `str` | | ID of the element used as an anchor +| `anchor-to` | `str` | | Which side/position of the anchor to use: "**top**", "**bottom**", "**right**", or "**left**"; with an optional postfix of "**start**", "**end**", "**center**". +| `tag` | `str` | `"div"` | HTML tag of the component. + +### MenuItem + +| Argument | Type | Default | Description +| ------------ | ----- | -------- | -------------- +| `mode` | `str` | `"auto"` | `"auto"` or `"manual"`. + +### MenuSubItem + +| Argument | Type | Default | Description +| ------------ | ----- | -------- | -------------- +| `mode` | `str` | `"auto"` | `"auto"` or `"manual"`. + + +## Accessibility notes + +### Mouse interaction + +- Clicking a `PopButton` will trigger the button action (open, close, or toggle state). + +- Clicking outside of a `Popover` will close *all* the `Popover` with `mode="auto"`. + + +### Keyboard interaction + +- Pressing the <kbd>Enter</kbd> or <kbd>Space</kbd> keys on a `PopButton` will trigger +the button action (open, close, or toggle state), and close *all* the `Popover` with `mode="auto"`. + +- Pressing the <kbd>Escape</kbd> key will close *all* the `Popover` with `mode="auto"`. diff --git a/docs/content/ui/popover.md b/docs/content/ui/popover.md new file mode 100644 index 0000000..673f96d --- /dev/null +++ b/docs/content/ui/popover.md @@ -0,0 +1,204 @@ +--- +title: Pop-over +description: A wrapper over the Popover API with anchor positioning. +--- + +<Header title="Pop-over" section="UI components"> + A wrapper over the Popover API with anchor positioning. +</Header> + +Pop-overs are powerful components with many use cases like edit menus, +custom notifications, content pickers, or help dialogs. + +They can also be used for big hideable sidebars, like a shopping cart or action panels. +Pop-overs are **always non-modal**. If you want to create a modal popoverover, a `Dialog` +component is the way to go instead. + +<ExampleTabs + prefix="demo" + :panels="{ + 'Result': 'ui.Popover.DemoResult', + 'HTML': 'ui.Popover.DemoHTML', + 'CSS': 'ui.Popover.DemoCSS', + }" +/> + +A `Popover` starts hidden on page load by having `display:none` set on it (the Popover API does it automatically). To show/hide the popover, you need to add some control `PopButton`s. + +When a popover is shown, it has `display:none` removed from it and it is put into the top layer so, unlike just using `position: absolute`, it's guaranteed that it will sit on top of all other page content. + + +## Anchor positioning + +By default, a popover appears centered in the layout view, but this component allows you to position it relative to an specific element in the page, using the `anchor` and `anchor-to` attributes. + +`anchor` is the ID of the element used as a reference, and `anchor-to` which side of the anchor to use: "top", "bottom", "right", or "left"; with an optional postfix of "start" or "end" ("center" is the default). + +<p> + <img src="/static//img/anchors.png" alt="Anchor positioning" + width="595" height="324" style="display:block;margin:60px auto;" /> +</p> + +The positioning is done every time the popover opens, but you can trigger the re-position, for example, on windows resizing, by calling the `jxui-popover/setPosition(popover)` function. + + +## Styling states + +| CSS selector | Description +| ------------------- | -------------- +| `[popover]` | Every popover has this attribute +| `:popover-open` | This pseudo-class matches only popovers that are currently being shown +| `::backdrop` | This pseudo-element is a full-screen element placed directly behind showing popover elements in the top layer, allowing effects to be added to the page content behind the popover(s) if desired. You might for example want to blur out the content behind the popover to help focus the user's attention on it + + +## Closing modes + +A `Popover` can be of two types: "auto" or "manual". This is controlled by the `mode` argument. + +| Argument | Description +| ------------------ | -------------- +| `mode="auto"` | The `Popover` will close automatically when the user clicks outside of it, or when presses the Escape key. +| `mode="manual"` | The `Popover` will not close automatically. It will only close when the user clicks on a linked `PopButton` with `action="close"` or `action="toggle"`. + +If the `mode` argument is not set, it defaults to "auto". + + +## `PopButton` actions + +A `PopButton` can have an `action` argument, which can be set to one of three values: "open", "close", or "toggle". This argument determines what happens to the target `Popover` when the button is clicked. + +| Argument | Description +| ----------------- | -------------- +| `action="open"` | Opens the target `Popover`. If the `Popover` is already open, it has no effect. +| `action="close"` | Closes the target `Popover`. If the `Popover` is already closed, it has no effect. +| `action="toggle"` | This is the default action. It toggles the target `Pop – opening it if it's closed and closing it if it's open. + + +## Animating popovers + +Popovers are set to `display:none;` when hidden and `display:block;` when shown, as well as being removed from / added to the [top layer](https://developer.mozilla.org/en-US/docs/Glossary/Top_layer). Therefore, for popovers to be animated, the `display` property [needs to be animatable]. + +[Supporting browsers](https://developer.mozilla.org/en-US/docs/Web/CSS/display#browser_compatibility) animate `display` flipping between `none` and another value of `display` so that the animated content is shown for the entire animation duration. So, for example: + +- When animating `display` from `none` to `block` (or another visible `display` value), the value will flip to `block` at `0%` of the animation duration so it is visible throughout. +- When animating `display` from `block` (or another visible `display` value) to `none`, the value will flip to `none` at `100%` of the animation duration so it is visible throughout. + +<Callout> +When animating using CSS transitions, `transition-behavior:allow-discrete` needs to be set to enable the above behavior. When animating with CSS animations, the above behavior is available by default; an equivalent step is not required. +</Callout> + + +### Transitioning a popover + +When animating popovers with CSS transitions, the following features are required: + +- `@starting-style` at-rule + + Provides a set of starting values for properties set on the popover that you want to transition from when it is first shown. This is needed to avoid unexpected behavior. By default, CSS transitions only occur when a property changes from one value to another on a visible element; they are not triggered on an element's first style update, or when the `display` type changes from `none` to another type. + +- `display` property + + Add `display` to the transitions list so that the popover will remain as `display:block` (or another visible `display` value) for the duration of the transition, ensuring the other transitions are visible. + +- `overlay` property + + Include `overlay` in the transitions list to ensure the removal of the popover from the top layer is deferred until the transition completes, again ensuring the transition is visible. + +- `transition-behavior` property + + Set `transition-behavior:allow-discrete` on the `display` and `overlay` transitions (or on the `transition` shorthand) to enable discrete transitions on these two properties that are not by default animatable. + +For example, let's say the styles we want to transition are `opacity` and `transform`: we want the popover to fade in or out while moving down or up. + +To achieve this, we set a starting state for these properties on the hidden state of the popover element (selected with the `[popover]` attribute selector) and an end state for the shown state of the popover (selected via the `:popover-open` pseudo-class). We also use the `transition` property to define the properties to animate and the animation's duration as the popover gets shown or hidden: + +```css +/*** Transition for the popover itself ***/ +[popover]:popover-open { + opacity: 1; + transform: scaleX(1); +} +[popover] { + transition: all 0.2s allow-discrete; + /* Final state of the exit animation */ + opacity: 0; + transform: translateY(-3rem); +} +[popover]:popover-open { + opacity: 1; + transform: translateY(0); +} +/* Needs to be after the previous [popover]:popover-open rule +to take effect, as the specificity is the same */ +@starting-style { + [popover]:popover-open { + opacity: 0; + transform: translateY(-3rem); + } +} + +/*** Transition for the popover's backdrop ***/ +[popover]::backdrop { + /* Final state of the exit animation */ + background-color: rgb(0 0 0 / 0%); + transition: all 0.2s allow-discrete; +} +[popover]:popover-open::backdrop { + background-color: rgb(0 0 0 / 15%); +} +@starting-style { + [popover]:popover-open::backdrop { + background-color: rgb(0 0 0 / 0%); + } +} +``` + +You can see a working example of this in the demo [at the beginning of the page](#startpage). + +<Callout> +Because popovers change from <code>display:none</code> to <code>display:block</code> each time they are shown, the popover transitions from its <code>@starting-style</code> styles to its <code>[popover]:popover-open</code> styles every time the entry transition occurs. When the popover closes, it transitions from its <code>[popover]:popover-open</code> state to the default <code>[popover]</code> state. + +<b>So it is possible for the style transition on entry and exit to be different.</b> +</Callout> + +<Callout type="note"> +This section was adapted from [Animating popovers](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API/Using#animating_popovers) +by [Mozilla Contributors](https://developer.mozilla.org/en-US/docs/MDN/Community/Roles_teams#contributor), licensed under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/). +</Callout> + + +## Component arguments + +### PopButton + +| Argument | Type | Default | Description +| --------------- | --------- | ---------- | -------------- +| `target` | `str` | | Required. The ID of the linked `Popover` component. +| `action` | `str` | `"toggle"` | `"open"`, `"close"`, or `"toggle"`. +| `tag` | `str` | `"button"` | HTML tag of the component. + +### Pop + +| Argument | Type | Default | Description +| ------------ | ----- | -------- | -------------- +| `mode` | `str` | `"auto"` | `"auto"` or `"manual"`. +| `anchor` | `str` | | ID of the element used as an anchor +| `anchor-to` | `str` | | Which side/position of the anchor to use: "**top**", "**bottom**", "**right**", or "**left**"; with an optional postfix of "**start**", "**end**", "**center**". +| `tag` | `str` | `"div"` | HTML tag of the component. + + +## Accessibility notes + +### Mouse interaction + +- Clicking a `PopButton` will trigger the button action (open, close, or toggle state). + +- Clicking outside of a `Popover` will close *all* the `Popover` with `mode="auto"`. + + +### Keyboard interaction + +- Pressing the <kbd>Enter</kbd> or <kbd>Space</kbd> keys on a `PopButton` will trigger +the button action (open, close, or toggle state), and close *all* the `Popover` with `mode="auto"`. + +- Pressing the <kbd>Escape</kbd> key will close *all* the `Popover` with `mode="auto"`. diff --git a/docs/content/ui/reldate.md b/docs/content/ui/reldate.md new file mode 100644 index 0000000..e3624c8 --- /dev/null +++ b/docs/content/ui/reldate.md @@ -0,0 +1,58 @@ +--- +title: Relative date +description: A component to convert datetimes to relative dates strings, such as "a minute ago", "in 2 hours", "yesterday", "3 months ago", etc. using JavaScript's Intl.RelativeTimeFormat API. +--- + +<Header title="Relative date" section="UI components"> +A component to convert datetimes to relative dates strings, +such as "a minute ago", "in 2 hours", "yesterday", "3 months ago", +etc. using JavaScript's <a class="link" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat" target="_blank">Intl.RelativeTimeFormat API</a>. +</Header> + +*Some examples (as if the datetime was `June 20th, 2024 6:30pm`)*: + +| Source | Relative date +| -----------------------------------------| -------------- +| `<RelDate datetime="2024-01-01"/>` | 6 months ago +| `<RelDate datetime="2024-06-19T18:30"/>` | yesterday +| `<RelDate datetime="2024-06-20T14:00"/>` | 5 hours ago +| `<RelDate datetime="2024-06-21T14:00"/>` | in 19 hours +| `<RelDate datetime="2024-06-30T10:00"/>` | next week +| `<RelDate datetime="1992-10-01"/>` | 32 years ago + + +## How it works + +The `RelDate` component is rendered as an empty `<time datetme="..." data-relative>` tag and, when the page load, the datetime is rendered by JavaScript. + +There is also a `MutationObserver` in place to render the datetime on any `<time datetme="..." data-relative>` inserted later to the page by JavaScript. + + +## Localization + +The locale used for the localization of the dates is, in order of priority: + +1. The optional `lang` attribute of the component; or +2. The `lang` attribute of the `<body>` tag + +Both can be a comma-separated lists of locales (e.g.: `"en-US,en-UK,en`). If none of these attributes exists, or if the locales are not supported by the browser, it fallsback to the default browser language. + +*Some examples (as if the datetime was `June 20th, 2024 6:30pm`)*: + +| Source | Relative date +| ---------------------------------------------------------------| -------------- +| `<RelDate datetime="2024-01-01" lang="it"/> ` | 6 mesi fa +| `<RelDate datetime="2024-06-19T18:30" lang="fr"/>` | hier +| `<RelDate datetime="2024-06-21T14:00" lang="es"/>` | dentro de 19 horas +| `<RelDate datetime="2024-06-21T14:00" lang="es-PE,es-ES,es"/>` | dentro de 19 horas + + +## Component arguments + +## RelDate + +| Argument | Type | Description +| -----------| ----- | -------------- +| `datetime` | `str` | Required. +| `lang` | `str` | Optional comma-separated list of locales to use for formatting. If not defined, the attribute `lang` of the `<body>` tag will be used. If that is also not defined, or none of the locales are supported by the browser, the default browser language is used +| `now` | `str` | Optional ISO-formatted date to use as the "present time". Useful for testing. diff --git a/docs/content/ui/tabs.md b/docs/content/ui/tabs.md new file mode 100644 index 0000000..094e271 --- /dev/null +++ b/docs/content/ui/tabs.md @@ -0,0 +1,162 @@ +--- +title: Tabs +description: Easily create accessible, fully customizable tab interfaces, with robust focus management and keyboard navigation support. +--- + +<Header title="Tabs" section="UI components"> + Easily create accessible, fully customizable tab interfaces, with robust focus management and keyboard navigation support. +</Header> + +<ExampleTabs + prefix="demo" + panels={{ { + 'Result': 'ui.Tabs.DemoResult', + 'HTML': 'ui.Tabs.DemoHTML', + 'CSS': 'ui.Tabs.DemoCSS', + } }} +/> + +Tabs are built using the `TabGroup`, `TabList`, `Tab`, and `TabPanel` components. Clicking on any tab or selecting it with the keyboard will activate the corresponding panel. + + +## Styling states + +| CSS selector | Description +| --------------- | -------------- +| `.ui-hidden` | Added to all `TabPanel` except the one that is active. +| `.ui-selected` | Added to the selected `Tab`. +| `.ui-disabled` | Added to disabled `Tab`s. + + +## Disabling a tab + +To disable a tab, use the disabled attribute on the `Tab` component. Disabled tabs cannot be selected with the mouse, and are also skipped when navigating the tab list using the keyboard. + +<Callout type="warning"> +Disabling tabs might be confusing for users. Instead, I reccomend you either remove it or explain why there is no content for that tab when is selected. +</Callout> + + +## Manually activating tabs + +By default, tabs are automatically selected as the user navigates through them using the arrow kbds. + +If you'd rather not change the current tab until the user presses <kbd>Enter</kbd> or <kbd>Space</kbd>, use the `manual` attribute on the `TabGroup` component. + +Remember to add styles to the `:focus` state of the tab so is clear to the user that the tab is focused. + +<ExampleTabs + prefix="manual" + panels={{{ + 'HTML': 'ui.Tabs.ManualHTML', + 'Result': 'ui.Tabs.ManualResult', + } }} +/> + +The manual prop has no impact on mouse interactions — tabs will still be selected as soon as they are clicked. + + +## Vertical tabs + +If you've styled your `TabList` to appear vertically, use the `vertical` attribute to enable navigating with the <kbd title="arrow up">↑</kbd> and <kbd title="arrow down">↓</kbd> arrow kbds instead of <kbd title="arrow left">←</kbd> and <kbd title="arrow right">→</kbd>, and to update the `aria-orientation` attribute for assistive technologies. + +<ExampleTabs + prefix="vertical" + panels={{ { + 'HTML': 'ui.Tabs.VerticalHTML', + 'Result': 'ui.Tabs.VerticalResult', + } }} +/> + + +## Controlling the tabs with a `<select>` + +Sometimes, you want to display a `<select>` element in addition to tabs. To do so, use the `TabSelect` and `TabOption` components. +A `TabSelect` component is a wrapper for a `<select>` element, and it accepts `TabOption` components as children. + +Note that a `TabSelect` **is not a replacement for a `TabList`**. For accessibility the `TabList` must be remain in your code, even if it's visually hidden. + +<ExampleTabs + prefix="select" + :panels="{ + 'HTML': 'ui.Tabs.SelectHTML', + 'Result': 'ui.Tabs.SelectResult', + }" +/> + + +## Component arguments + +### TabGroup + +| Argument | Type | Default | Description +| ----------- | -------- | ---------- | -------------- +| tag | `str` | `"div"` | HTML tag used for rendering the wrapper. + +### TabList + +| Argument | Type | Default | Description +| ----------- | -------- | ---------- | -------------- +| vertical | `bool` | `false` | Use the <kbd title="arrow up">↑</kbd> and <kbd title="arrow down">↓</kbd> arrow kbds to move between tabs instead of the defaults <kbd title="arrow left">←</kbd> and <kbd title="arrow right">→</kbd> arrow kbds. +| manual | `bool` | `false` | If `true`, selecting a tab with the keyboard won't activate it, you must press <kbd>Enter</kbd> os <kbd>Space</kbd> kbds to do it. +| tag | `str` | `"nav"` | HTML tag used for rendering the wrapper. + + +### Tab + +| Argument | Type | Default | Description +| ----------- | -------- | ---------- | -------------- +| target | `str` | | Required. HTML id of the panel associated with this tab. +| selected | `bool` | `false` | Initially selected tab. Only one tab in the `TabList` can be selected at the time. +| disabled | `bool` | `false` | If the tab can be selected. +| tag | `str` | `"button"` | HTML tag used for rendering the tab. + +### TabPanel + +| Argument | Type | Default | Description +| ----------- | -------- | ---------- | -------------- +| hidden | `bool` | `false` | Initially hidden panel. +| tag | `bool` | `"div"` | HTML tag used for rendering the panel. + + +### TabSelect + +No arguments. + + +### TabOption + +| Argument | Type | Default | Description +| ----------- | -------- | ---------- | -------------- +| target | `str` | | Required. HTML id of the panel associated with this tab. +| disabled | `bool` | `false` | Display the option but not allow to select it. + + +## Events + +A tab emits a `jxui:tab:selected` event every time is selected. The event contains the `target` property with the tag node. + +```js +document.addEventListener("jxui:tab:selected", (event) => { + console.log(`'${event.target.textContent}' tab selected`); +}); +``` + + +## Accessibility notes + +### Mouse interaction + +Clicking a `Tab` will select that tab and display the corresponding `TabPanel`. + +### Keyboard interaction + +All interactions apply when a `Tab` component is focused. + +| Command | Description +| ------------------------------------------------------------------------------------- | ----------- +| <kbd title="arrow left">←</kbd> / <kbd title="arrow right">→</kbd> arrow kbds | Selects the previous/next non-disabled tab, cycling from last to first and vice versa. +| <kbd title="arrow up">↑</kbd> / <kbd title="arrow down">↓</kbd> arrow kbds when `vertical` is set | Selects the previous/next non-disabled tab, cycling from last to first and vice versa. +| <kbd>Enter</kbd> or <kbd>Space</kbd> when `manual` is set | Activates the selected tab +| <kbd>Home</kbd> or <kbd>PageUp</kbd> | Activates the **first** tab +| <kbd>End</kbd> or <kbd>PageDown</kbd> | Activates the **last** tab diff --git a/docs/deploy.sh b/docs/deploy.sh new file mode 100755 index 0000000..9fe8897 --- /dev/null +++ b/docs/deploy.sh @@ -0,0 +1,4 @@ +#!/bin/bash +python docs.py build +ssh code 'rm -rf /var/www/jinjax/build' +rsync --recursive --delete --progress build code:/var/www/jinjax/ diff --git a/docs/docs.py b/docs/docs.py new file mode 100755 index 0000000..d49699f --- /dev/null +++ b/docs/docs.py @@ -0,0 +1,72 @@ +#!/usr/bin/env python +import logging +from pathlib import Path + +import jinjax_ui +from claydocs import Docs + + +logging.getLogger("jinjax").setLevel(logging.INFO) +logging.getLogger("jinjax").addHandler(logging.StreamHandler()) + +here = Path(__file__).parent + +pages = [ + "index.md", + [ + "Guide", + [ + "guide/index.md", + "guide/components.md", + "guide/slots.md", + "guide/css_and_js.md", + # "guide/integrations.md", + # "guide/performance.md", + "guide/motivation.md", + ], + ], + [ + "API", + [ + "api.md", + ], + ], + [ + "UI components", [ + "ui/index.md", + "ui/tabs.md", + "ui/popover.md", + "ui/menu.md", + "ui/accordion.md", + "ui/linkedlist.md", + "ui/reldate.md", + ], + ], +] + +def get_docs() -> Docs: + root_path = here / "content" + docs = Docs( + pages, + content_folder=root_path, + add_ons=[jinjax_ui], + search=False, + cache=False, + domain="https://jinjax.scaletti.dev", + default_component="Page", + default_social="SocialCard", + metadata={ + "name": "JinjaX", + "language": "en", + "license": "MIT", + "version": "0.43", + "web": "https://jinjax.scaletti.dev", + } + ) + docs.add_folder(here / "components") + docs.add_folder(here / "theme") + return docs + + +if __name__ == "__main__": + get_docs().run() diff --git a/docs/indexer.js b/docs/indexer.js new file mode 100644 index 0000000..637645b --- /dev/null +++ b/docs/indexer.js @@ -0,0 +1,27 @@ +var lunr = require("lunr"); +require("lunr-languages/lunr.stemmer.support")(lunr); +const fs = require("node:fs"); + +function build_index([lang, outpath]) { + lang = lang || "en" + outpath = outpath || "." + + if (lang !== "en") { + const lunr_lang = require(`lunr-languages/lunr.${lang}`)(lunr); + this.use(lunr_lang); + } + + const idx = lunr(function() { + this.ref("id"); + this.field("title", { boost: 10 }); + this.field("body"); + const docs = JSON.parse(fs.readFileSync(`${outpath}/docs-${lang}.json`)); + + for (let doc in docs) { + this.add(doc) + } + }) + fs.writeFileSync(`${outpath}/search-${lang}.json`, JSON.stringify(idx)); +} + +build_index(process.argv.slice(2)); diff --git a/docs/static/docs.css b/docs/static/docs.css new file mode 100644 index 0000000..30c9898 --- /dev/null +++ b/docs/static/docs.css @@ -0,0 +1,413 @@ +.bg-cover { + position: absolute; + z-index: -1; + inset: 0; +} + +.Logo { + display: flex; + height: 2.5rem; + align-items: center; + color: rgb(24 24 27); + opacity: 0.9; + + &:hover { + opacity: 1; + } + & img.light { + display: block; + } + & img.dark { + display: none; + } + &:is(.dark *) img.light { + display: none; + } + &:is(.dark *) img.dark { + display: block; + } +} + +.NavLinks { + & a { + padding: 0.25rem; + font-size: 0.875rem; + line-height: 1.25rem; + color: rgb(82 82 91); + } + & a:hover { + color: rgb(24 24 27); + } + + & a:is(.dark *) { + color: rgb(212 212 216); + } + & a:is(.dark *):hover { + color: rgb(255 255 255); + } +} + +.homepage { + padding-top: 0; + padding-bottom: 0; + padding-left: var(--cd-padding-left); + padding-right: var(--cd-padding-right); +} +.homepage section.hero { + margin-left: auto; + margin-right: auto; + display: flex; + max-width: 56rem; + flex-direction: column; + padding-top: 2.25rem; + padding-bottom: 2.25rem; + color: rgb(23 23 23); + + &:is(.dark *) { + color: rgb(245 245 245); + } + + & h1 { + margin: 0 auto; + width: 300px; + height: 140px; + background-image: url("/static/img/jinjax-logo.svg"); + background-position: center center; + background-repeat: no-repeat; + background-size: contain; + text-indent: -999px; + display: none; + } + + & h2 { + font-size: 2.2rem; + font-weight: 600; + line-height: 1.2; + letter-spacing: -0.05em; + } + & h2 .g1 { + background-image: linear-gradient(to bottom right, #fbbf24, #fb923c); + background-clip: text; + color: transparent; + } + + & h2 .g2 { + background-image: linear-gradient(to bottom right, #34d399, #3b82f6); + background-clip: text; + color: transparent; + } + + @media (min-width: 768px) { + & { + padding-top: 2.5rem; + padding-bottom: 3rem; + } + & h1 { + display: block; + width: 300px; + height: 100px; + } + & h2 { + font-size: 2.4rem; + text-align: center; + } + & h2 .g2 { + white-space: nowrap; + } + } + + @media (min-width: 1024px) { + & h1 { + width: 400px; + height: 140px; + } + & h2 { + font-size: 3rem; + } + } +} + +.homepage section.code { + margin-left: -1rem; + margin-right: -1rem; + max-width: 72rem; + border-width: 1px; + border-color: rgb(212 212 212); + background-color: rgb(231 229 228); + padding: 1.5rem 0; + + &:is(.dark *) { + border-color: rgb(82 82 82); + background-color: rgb(41 37 36); + } + + & .panel { + display: flex; + flex-direction: column; + } + & .panel ~ .panel { + margin-top: 1.5rem; + } + & h2 { + margin-bottom: 0.5rem; + text-align: center; + font-size: 1.5rem; + line-height: 1.1; + font-weight: 700; + } + & .highlight { + flex-grow: 1; + } + & pre { + height: 100%; + } + + @media (min-width: 1024px) { + & { + border-radius: 1rem; + padding: 1.5rem; + margin-bottom: 2.5rem; + margin-left: auto; + margin-right: auto; + } + & .stack { + display: flex; + align-items: stretch; + } + & .panel { + width: 50%; + } + & .panel ~ .panel { + margin-top: 0; + margin-left: 0.5rem; + } + } +} + +.homepage section.features { + margin-left: auto; + margin-right: auto; + max-width: 56rem; + padding-top: 2rem; + padding-bottom: 2rem; + + & h2 { + margin-bottom: 2rem; + text-align: center; + font-size: 2.2rem; + line-height: 1.2; + font-weight: 800; + } + & h2 code { + font-size: 0.9em; + } + & .cards { + margin-top: 2.5rem; + display: grid; + grid-template-columns: repeat(1, minmax(0, 1fr)); + column-gap: 1rem; + row-gap: 1.5rem; + font-size: 1rem; + line-height: 1.4rem; + } + & .card { + margin-left: auto; + margin-right: auto; + display: flex; + flex-direction: column; + height: 9rem; + max-width: 28rem; + border-radius: 1rem; + border-width: 2px; + border-color: rgb(245 245 244); + background-color: rgb(250 250 249); + padding-top: 1rem; + padding-bottom: 1rem; + padding-left: 1.5rem; + padding-right: 1.5rem; + box-shadow: 0 1px 2px 0 rgb(0 0 0 / 0.05); + } + & .card:is(.dark *) { + border-color: rgb(41 37 36); + background-color: rgb(41 37 36); + } + & .card > .header { + margin-bottom: 0.5rem; + display: flex; + align-items: center; + flex-direction: row-reverse; + } + & .card > .header img { + float: left; + max-height: 32px; + width: 2.5rem; + padding-right: 0.75rem; + } + & .card > .header img:is(.dark *) { + filter: invert(100%) + } + & .card > .header h3 { + font-size: 1.4rem; + font-weight: 600; + color: rgb(24 24 27); + } + & .card > .header h3:is(.dark *) { + color: rgb(228 228 231); + } + & .card > .body { + flex-grow: 1; + margin-top: 0.5rem; + font-size: 1rem; + line-height: 1.4; + color: rgb(82 82 91); + } + & .card a { + font-weight: 600; + } + + @media (min-width: 768px) { + & .cards { + grid-template-columns: repeat(2, minmax(0, 1fr)); + } + & .card { + height: 10rem; + } + } + + @media (min-width: 1280px) { + & { + max-width: 1280px; + } + & .cards { + grid-template-columns: repeat(4, minmax(0, 1fr)); + } + & .card { + height: 13rem; + align-items: flex-start; + padding-top: 1.5rem; + padding-bottom: 1.5rem; + } + } +} + +.homepage section.spaghetti { + margin-bottom: 1.25rem; + padding-left: var(--cd-padding-left); + padding-right: var(--cd-padding-right); + + & .wrapper { + margin-left: auto; + margin-right: auto; + max-width: 64rem; + padding-left: 0.75rem; + padding-right: 0.75rem; + padding-top: 2rem; + padding-bottom: 2rem; + } + + & h2 { + margin-bottom: 2rem; + text-align: center; + font-size: 2.2rem; + line-height: 1.2; + font-weight: 800; + } + + & .text { + position: relative; + font-size: 1.4rem; + line-height: 1.4; + } + & .text img { + position: absolute; + left: 0; + top: 0; + display: none; + height: 100%; + max-height: 24rem; + } + & .text p { + margin-bottom:1.5rem; + } + + @media (min-width: 640px) { + & .wrapper { + padding-top: 3rem; + padding-bottom: 3rem; + } + } + + @media (min-width: 1024px) { + & .wrapper { + max-width: 72rem; + } + & .text { + padding-left: 440px; + } + & .text img { + display: block; + } + } +} + +.homepage section.engage { + background-image: linear-gradient(to bottom, #d6d3d1, #e7e5e4, #a8a29e); + margin-left: -1rem; + margin-right: -1rem; + + &:is(.dark *) { + background-image: linear-gradient(to bottom, #000, #1c1917); + } + + & .wrapper { + padding-top: 3rem; + padding-bottom: 3rem; + text-align: center; + } + + & h3 { + margin-bottom: 2rem; + text-align: center; + font-size: 1.875rem; + line-height: 1.4; + font-weight: 800; + } + + & a { + display: flex-inline; + align-items: center; + justify-content: center; + margin-left: auto; + margin-right: auto; + margin-bottom: 1.25rem; + display: inline-block; + -webkit-appearance: none; + -moz-appearance: none; + appearance: none; + border-radius: 1rem; + background-image: linear-gradient(to top right, #a3e635, #65a30d); + padding: 1rem 2rem; + text-align: center; + font-family: var(--cd-font-sans); + font-size: 1.25rem; + line-height: 1.75rem; + font-weight: 700; + color: rgb(39 39 42); + text-decoration-line: none; + box-shadow: 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1); + transition: all 0.4s cubic-bezier(0.4, 0, 0.2, 1); + } + & a:hover { + background-image: linear-gradient(to top right, #a3e635, #a3e635); + color: rgb(0 0 0); + } + & a i { + font-style: normal; + font-size: 1.2rem; + } + + & .hint { + font-size: 0.75rem; + line-height: 1rem; + } +}
\ No newline at end of file diff --git a/docs/static/favicon.ico b/docs/static/favicon.ico Binary files differnew file mode 100644 index 0000000..3615f29 --- /dev/null +++ b/docs/static/favicon.ico diff --git a/docs/static/fonts/karla-bold-ext.woff2 b/docs/static/fonts/karla-bold-ext.woff2 Binary files differnew file mode 100644 index 0000000..88c185a --- /dev/null +++ b/docs/static/fonts/karla-bold-ext.woff2 diff --git a/docs/static/fonts/karla-bold.woff2 b/docs/static/fonts/karla-bold.woff2 Binary files differnew file mode 100644 index 0000000..244e69d --- /dev/null +++ b/docs/static/fonts/karla-bold.woff2 diff --git a/docs/static/fonts/karla-regular-.woff2 b/docs/static/fonts/karla-regular-.woff2 Binary files differnew file mode 100644 index 0000000..244e69d --- /dev/null +++ b/docs/static/fonts/karla-regular-.woff2 diff --git a/docs/static/fonts/karla-regular-ext.woff2 b/docs/static/fonts/karla-regular-ext.woff2 Binary files differnew file mode 100644 index 0000000..88c185a --- /dev/null +++ b/docs/static/fonts/karla-regular-ext.woff2 diff --git a/docs/static/fonts/material-symbols-rounded.woff2 b/docs/static/fonts/material-symbols-rounded.woff2 Binary files differnew file mode 100644 index 0000000..0200f5e --- /dev/null +++ b/docs/static/fonts/material-symbols-rounded.woff2 diff --git a/docs/static/img/anatomy-en.png b/docs/static/img/anatomy-en.png Binary files differnew file mode 100644 index 0000000..d880437 --- /dev/null +++ b/docs/static/img/anatomy-en.png diff --git a/docs/static/img/anatomy-en.svg b/docs/static/img/anatomy-en.svg new file mode 100644 index 0000000..bacfb60 --- /dev/null +++ b/docs/static/img/anatomy-en.svg @@ -0,0 +1,347 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<svg + width="420" + height="440" + version="1.1" + viewBox="0 0 420 440" + id="svg151" + sodipodi:docname="anatomy-en.svg" + inkscape:export-filename="/media/data/anatomy-en.png" + inkscape:export-xdpi="223.41818" + inkscape:export-ydpi="223.41818" + inkscape:version="1.1.2 (0a00cf5339, 2022-02-04)" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns="http://www.w3.org/2000/svg" + xmlns:svg="http://www.w3.org/2000/svg"> + <sodipodi:namedview + id="namedview153" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageshadow="2" + inkscape:pageopacity="0.0" + inkscape:pagecheckerboard="0" + showgrid="false" + inkscape:zoom="2.3136364" + inkscape:cx="172.45579" + inkscape:cy="357.66208" + inkscape:window-width="1280" + inkscape:window-height="740" + inkscape:window-x="0" + inkscape:window-y="0" + inkscape:window-maximized="1" + inkscape:current-layer="svg151" /> + <defs + id="defs5"> + <marker + id="TriangleStart" + overflow="visible" + markerHeight="2.6867051" + markerWidth="2.3239999" + orient="auto-start-reverse" + preserveAspectRatio="xMidYMid" + viewBox="0 0 5.3244081 6.1553851"> + <path + transform="scale(.6)" + d="m5.8 0-8.6 5v-10z" + fill="context-stroke" + fill-rule="evenodd" + stroke="context-stroke" + stroke-width="1pt" + id="path2" /> + </marker> + </defs> + <rect + width="420" + height="440" + fill="#ffffff" + fill-opacity="0.85" + stroke="#dddddd" + id="rect7" + x="0.40752804" + y="1.6170791" + inkscape:export-filename="/home/jpsca/Code/jinjax/docs/static/img/anatomy-en.png" + inkscape:export-xdpi="223.418" + inkscape:export-ydpi="223.418" /> + <path + d="m17 98h320" + stroke="#555" + stroke-width="1px" + id="path9" + inkscape:export-filename="/home/jpsca/Code/jinjax/docs/static/img/anatomy-en.png" + inkscape:export-xdpi="223.418" + inkscape:export-ydpi="223.418" /> + <text + id="code" + fill="#444444" + font-family="'SF Mono', Monaco, monospace" + font-size="11px" + font-weight="bold" + stroke-width="1.4" + style="line-height:1.25;font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal" + inkscape:export-filename="/home/jpsca/Code/jinjax/docs/static/img/anatomy-en.png" + inkscape:export-xdpi="223.418" + inkscape:export-ydpi="223.418"><tspan + sodipodi:role="line" + id="tspan83456" + x="17" + y="90"><tspan + x="17" + y="90" + font-style="italic" + font-weight="600" + id="tspan8">components/Form.jinja</tspan><tspan + x="17" + y="131" + id="tspan10">{#def action, label, method="post" #}</tspan><tspan + x="17" + y="145" + id="tspan12" /></tspan><tspan + sodipodi:role="line" + id="tspan83458" + x="17" + y="103.75"><tspan + x="17" + y="145" + id="tspan83460" /></tspan><tspan + sodipodi:role="line" + x="17" + y="145" + id="tspan83494"><tspan + x="17" + y="145" + id="tspan83496">{#css form.css, /static/theme.css #}</tspan><tspan + x="17" + y="160" + id="tspan14">{#js form.js #}</tspan><tspan + x="17" + y="187" + fill="#555555" + id="tspan16">{% set method = method.lower() %}</tspan><tspan + x="17" + y="215" + fill="#3771c8" + id="tspan22"><tspan + id="tspan18"><</tspan><tspan + id="tspan20">form</tspan></tspan><tspan + x="24" + y="229" + id="tspan32"><tspan + fill="#5f8dd3" + id="tspan24">method=</tspan><tspan + fill="#008800" + id="tspan26">"</tspan><tspan + fill="#ff7f2a" + id="tspan28">{{ method }}</tspan><tspan + fill="#008800" + id="tspan30">"</tspan></tspan><tspan + x="24" + y="244" + id="tspan42"><tspan + fill="#5f8dd3" + id="tspan34">action=</tspan><tspan + fill="#008800" + id="tspan36">"</tspan><tspan + fill="#ff7f2a" + id="tspan38">{{ action }}</tspan><tspan + fill="#008800" + id="tspan40">"</tspan></tspan><tspan + x="24" + y="257" + fill="#ff7f2a" + id="tspan46">{{ attrs.render(<tspan + id="tspan44">class="form"</tspan>) }}</tspan><tspan + x="17" + y="272" + fill="#3771c8" + id="tspan48">></tspan><tspan + x="24" + y="286" + fill="#555555" + id="tspan50">{% if method == "post" -%}</tspan><tspan + x="24" + y="299" + fill="#3771c8" + id="tspan60"><input <tspan + fill="#5f8dd3" + id="tspan58">type=<tspan + fill="#008800" + id="tspan52">"hidden"</tspan> name=<tspan + fill="#008800" + id="tspan54">"csrf"</tspan> value="<tspan + fill="#ff7f2a" + id="tspan56">{{token}}</tspan>" /></tspan></tspan><tspan + x="24" + y="314" + fill="#555555" + id="tspan62">{% endif -%}</tspan><tspan + x="24" + y="341" + id="tspan66"><tspan + fill="#ff7f2a" + id="tspan64">{{ content }}</tspan></tspan><tspan + x="24" + y="370" + fill="#214478" + id="tspan72"><Button :label=<tspan + fill="#008800" + id="tspan53">"label"</tspan> /></tspan><tspan + x="17" + y="386" + fill="#3771c8" + id="tspan76"></<tspan + fill="#3771c8" + font-weight="bold" + id="tspan74">form</tspan>></tspan></tspan></text> + <g + id="arrows" + transform="translate(0.44852325)" + inkscape:export-filename="/home/jpsca/Code/jinjax/docs/static/img/anatomy-en.png" + inkscape:export-xdpi="223.418" + inkscape:export-ydpi="223.418"> + <path + d="m 96,49 c 13,28 24,0.84 25,24" + fill="none" + marker-end="url(#TriangleStart)" + stroke="#000000" + stroke-width="1.7" + id="path94" /> + <path + d="m 263.05173,66.190373 c 3.21374,29.013609 -66.83732,10.210641 -66.83732,43.210637" + fill="none" + marker-end="url(#TriangleStart)" + stroke="#000000" + stroke-width="1.7" + id="path96" + sodipodi:nodetypes="cc" /> + <path + d="m 299.74715,171.9951 c -24.29574,-13.93589 13.75099,-34.69573 -30.19646,-30.86252" + fill="none" + marker-end="url(#TriangleStart)" + stroke="#000000" + stroke-width="1.7" + id="path98" + sodipodi:nodetypes="cc" /> + <path + d="M 299.74715,171.9951 C 282.96418,161.72557 170.13518,157.37012 132.6202,158.53979" + fill="none" + marker-end="url(#TriangleStart)" + stroke="#000000" + stroke-width="1.7" + id="path100" + sodipodi:nodetypes="cc" /> + <path + d="m 169,404 c -11,-17 -39.53849,-5.19589 -47.53849,-23.49589" + fill="none" + marker-end="url(#TriangleStart)" + stroke="#000000" + stroke-width="1.7" + id="path102" + sodipodi:nodetypes="cc" /> + </g> + <text + style="font-size:12px;font-family:'Comic Neue'" + transform="matrix(0.99580394,0,0,0.99717236,22.306709,8.8220192)" + id="text111" + inkscape:export-filename="/home/jpsca/Code/jinjax/docs/static/img/anatomy-en.png" + inkscape:export-xdpi="223.418" + inkscape:export-ydpi="223.418"><tspan + x="0" + y="11" + id="tspan105">Everything before the </tspan><tspan + x="0" + y="30" + id="tspan107">first dot is the component </tspan><tspan + x="0" + y="48" + id="tspan109">name</tspan></text> + <text + style="font-size:12px;font-family:'Comic Neue'" + transform="matrix(0.99585975,0,0,0.94509234,216.62806,15.846205)" + id="text115" + inkscape:export-filename="/home/jpsca/Code/jinjax/docs/static/img/anatomy-en.png" + inkscape:export-xdpi="223.418" + inkscape:export-ydpi="223.418"><tspan + x="0" + y="6" + id="tspan113">Arguments definition</tspan></text> + <text + style="font-size:12px;font-family:'Comic Neue'" + transform="matrix(0.99962611,0,0,0.98554306,218.63043,28.835757)" + id="text121" + inkscape:export-filename="/home/jpsca/Code/jinjax/docs/static/img/anatomy-en.png" + inkscape:export-xdpi="223.418" + inkscape:export-ydpi="223.418"><tspan + x="0" + y="11" + id="tspan117">Arguments without a </tspan><tspan + x="0" + y="30" + id="tspan119">default value are required</tspan></text> + <text + style="font-size:12px;font-family:'Comic Neue';white-space:pre;inline-size:102.594" + transform="matrix(1.0036128,0,0,0.99557292,305.3546,154.45222)" + id="text127" + inkscape:export-filename="/home/jpsca/Code/jinjax/docs/static/img/anatomy-en.png" + inkscape:export-xdpi="223.418" + inkscape:export-ydpi="223.418" + xml:space="preserve"><tspan + x="0" + y="11" + id="tspan1018">Optional lists of </tspan><tspan + x="0" + y="26" + id="tspan1020">CSS and JS files</tspan></text> + <text + style="font-size:12px;font-family:'Comic Neue';white-space:pre;inline-size:138.046" + transform="translate(277.91845,188.39939)" + id="text135" + inkscape:export-filename="/home/jpsca/Code/jinjax/docs/static/img/anatomy-en.png" + inkscape:export-xdpi="223.418" + inkscape:export-ydpi="223.418" + xml:space="preserve"><tspan + x="0" + y="11" + id="tspan1022">Paths are absolute or </tspan><tspan + x="0" + y="26" + id="tspan1024">relative to the root of +</tspan><tspan + x="0" + y="41" + id="tspan1026">the components folder</tspan></text> + <text + style="font-size:12px;font-family:'Comic Neue'" + transform="matrix(0.99764329,0,0,0.98692271,247.4097,314.31427)" + id="text143" + inkscape:export-filename="/home/jpsca/Code/jinjax/docs/static/img/anatomy-en.png" + inkscape:export-xdpi="223.418" + inkscape:export-ydpi="223.418"><tspan + x="0" + y="11" + id="tspan137">You can have more </tspan><tspan + x="0" + y="30" + id="tspan139">than one parent </tspan><tspan + x="0" + y="48" + id="tspan141">element, unlike React</tspan></text> + <text + style="font-size:12px;font-family:'Comic Neue';white-space:pre;inline-size:165.6" + transform="matrix(0.9980174,0,0,0.98858774,171.78044,387.36773)" + id="text149" + inkscape:export-filename="/home/jpsca/Code/jinjax/docs/static/img/anatomy-en.png" + inkscape:export-xdpi="223.418" + inkscape:export-ydpi="223.418" + xml:space="preserve"><tspan + x="0" + y="11" + id="tspan1028">You can call any other </tspan><tspan + x="0" + y="26" + id="tspan1030">component and pass attributes </tspan><tspan + x="0" + y="41" + id="tspan1032">to them</tspan></text> +</svg> diff --git a/docs/static/img/anatomy-es.svg b/docs/static/img/anatomy-es.svg new file mode 100644 index 0000000..a3b3952 --- /dev/null +++ b/docs/static/img/anatomy-es.svg @@ -0,0 +1,288 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<svg + width="420" + height="440" + version="1.1" + viewBox="0 0 420 440" + id="svg151" + sodipodi:docname="anatomy-es.svg" + inkscape:export-filename="/media/data/Code/jinjax-docs/static/img/anatomy-es.png" + inkscape:export-xdpi="223.41818" + inkscape:export-ydpi="223.41818" + inkscape:version="1.1.2 (0a00cf5339, 2022-02-04)" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns="http://www.w3.org/2000/svg" + xmlns:svg="http://www.w3.org/2000/svg"> + <sodipodi:namedview + id="namedview153" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageshadow="2" + inkscape:pageopacity="0.0" + inkscape:pagecheckerboard="0" + showgrid="false" + inkscape:zoom="1.1568182" + inkscape:cx="14.695481" + inkscape:cy="220.86444" + inkscape:window-width="2560" + inkscape:window-height="1357" + inkscape:window-x="0" + inkscape:window-y="0" + inkscape:window-maximized="1" + inkscape:current-layer="svg151" /> + <defs + id="defs5"> + <marker + id="TriangleStart" + overflow="visible" + markerHeight="2.6867051" + markerWidth="2.3239999" + orient="auto-start-reverse" + preserveAspectRatio="xMidYMid" + viewBox="0 0 5.3244081 6.1553851"> + <path + transform="scale(.6)" + d="m5.8 0-8.6 5v-10z" + fill="context-stroke" + fill-rule="evenodd" + stroke="context-stroke" + stroke-width="1pt" + id="path2" /> + </marker> + </defs> + <rect + width="420" + height="440" + fill="#fff" + fill-opacity=".85" + stroke="#ddd" + id="rect7" /> + <path + d="m17 98h320" + stroke="#555" + stroke-width="1px" + id="path9" /> + <text + id="code" + fill="#444" + font-family="'SF Mono', Monaco, monospace" + font-size="11px" + font-weight="bold" + stroke-width="1.4" + style="font-variant-caps:normal;font-variant-east-asian:normal;font-variant-ligatures:normal;font-variant-numeric:normal;line-height:1.25"><tspan + x="17" + y="90" + font-style="italic" + font-weight="600" + id="tspan1151">components/Form.jinja</tspan><tspan + x="17" + y="131" + id="tspan1153">{#def action, label, method="post" #}</tspan><tspan + x="17" + y="145" + id="tspan1155">{#css form.css %}</tspan><tspan + x="17" + y="160" + id="tspan1157">{#js form.js %}</tspan><tspan + x="17" + y="187" + fill="#555" + id="tspan1159">{% set method = method.lower() %}</tspan><tspan + x="17" + y="215" + fill="#3771c8" + id="tspan1165"><tspan + id="tspan1161"><</tspan><tspan + id="tspan1163">form</tspan></tspan><tspan + x="24" + y="229" + id="tspan1175"><tspan + fill="#5f8dd3" + id="tspan1167">method=</tspan><tspan + fill="#080" + id="tspan1169">"</tspan><tspan + fill="#ff7f2a" + id="tspan1171">{{ method }}</tspan><tspan + fill="#080" + id="tspan1173">"</tspan></tspan><tspan + x="24" + y="244" + id="tspan1185"><tspan + fill="#5f8dd3" + id="tspan1177">action=</tspan><tspan + fill="#080" + id="tspan1179">"</tspan><tspan + fill="#ff7f2a" + id="tspan1181">{{ action }}</tspan><tspan + fill="#080" + id="tspan1183">"</tspan></tspan><tspan + x="24" + y="257" + fill="#ff7f2a" + id="tspan1189">{{ attrs.render(<tspan + id="tspan1187">class="form"</tspan>) }} + </tspan><tspan + x="17" + y="272" + fill="#3771c8" + id="tspan1191">></tspan><tspan + x="24" + y="286" + fill="#555" + id="tspan1193">{% if method == "post" -%}</tspan><tspan + x="24" + y="299" + fill="#3771c8" + id="tspan1203"> + <input <tspan + fill="#5f8dd3" + id="tspan1201">type=<tspan + fill="#080" + id="tspan1195">"hidden"</tspan> name=<tspan + fill="#080" + id="tspan1197">"csrf"</tspan> value="<tspan + fill="#ff7f2a" + id="tspan1199">{{token}}</tspan>" /></tspan></tspan><tspan + x="24" + y="314" + fill="#555" + id="tspan1205">{% endif -%}</tspan><tspan + x="24" + y="341" + id="tspan1209"><tspan + fill="#ff7f2a" + id="tspan1207">{{ content }}</tspan></tspan><tspan + x="24" + y="370" + fill="#214478" + id="tspan1215"> + <Button <tspan + fill="#5f8dd3" + id="tspan1211">label=</tspan><tspan + fill="#ff7f2a" + id="tspan1213">{label}</tspan>> + </tspan><tspan + x="17" + y="386" + fill="#3771c8" + id="tspan1219"></<tspan + fill="#3771c8" + font-weight="bold" + id="tspan1217">form</tspan>></tspan></text> + <g + id="arrows"> + <path + d="m96 49c13 28 24 .84 25 24" + fill="none" + marker-end="url(#TriangleStart)" + stroke="#000" + stroke-width="1.7" + id="path94" /> + <path + d="m255 65c13 28-60 16-60 49" + fill="none" + marker-end="url(#TriangleStart)" + stroke="#000" + stroke-width="1.7" + id="path96" /> + <path + d="m260 151c-26 6.7-74-7.6-108-9.2" + fill="none" + marker-end="url(#TriangleStart)" + stroke="#000" + stroke-width="1.7" + id="path98" /> + <path + d="m262 158c-26 5.2-91-.74-124-2" + fill="none" + marker-end="url(#TriangleStart)" + stroke="#000" + stroke-width="1.7" + id="path100" /> + <path + d="m169 404c-11-17-56-3.7-64-22" + fill="none" + marker-end="url(#TriangleStart)" + stroke="#000" + stroke-width="1.7" + id="path102" /> + </g> + <text + style="font-size:12px;font-family:'Comic Neue'" + transform="matrix(0.99580394,0,0,0.99717236,22.306709,8.8220192)" + id="text111"><tspan + x="0" + y="11" + id="tspan105">Todo antes del primer </tspan><tspan + x="0" + y="30" + id="tspan107">punto es el nombre del </tspan><tspan + x="0" + y="48" + id="tspan109">componente</tspan></text> + <text + style="font-size:12px;font-family:'Comic Neue'" + transform="matrix(0.99585975,0,0,0.94509234,216.62806,15.846205)" + id="text115"><tspan + x="0" + y="6" + id="tspan113">Definición de argumentos</tspan></text> + <text + style="font-size:12px;font-family:'Comic Neue'" + transform="matrix(0.99962611,0,0,0.98554306,218.63043,28.835757)" + id="text121"><tspan + x="0" + y="11" + id="tspan117">Los argumentos sin valores </tspan><tspan + x="0" + y="30" + id="tspan119">predefinidos son obligatorios</tspan></text> + <text + style="font-size:12px;font-family:'Comic Neue'" + transform="matrix(1.0036128,0,0,0.99557292,276.36705,142.82391)" + id="text127"><tspan + x="0" + y="11" + id="tspan123">Listas opcionales de </tspan><tspan + x="0" + y="30" + id="tspan125">archivos CSS y JS</tspan></text> + <text + style="font-size:12px;font-family:'Comic Neue'" + transform="translate(275.93954,180.65106)" + id="text135"><tspan + x="0" + y="11" + id="tspan129">Las rutas son </tspan><tspan + x="0" + y="30" + id="tspan131">relativas al folder </tspan><tspan + x="0" + y="48" + id="tspan133">de componentes</tspan></text> + <text + style="font-size:12px;font-family:'Comic Neue'" + transform="matrix(0.99764329,0,0,0.98692271,247.4097,314.31427)" + id="text143"><tspan + x="0" + y="11" + id="tspan137">Puedes tener mas de </tspan><tspan + x="0" + y="30" + id="tspan139">un elemento padre, a </tspan><tspan + x="0" + y="48" + id="tspan141">diferencia de React</tspan></text> + <text + style="font-size:12px;font-family:'Comic Neue'" + transform="matrix(0.9980174,0,0,0.98858774,171.78044,387.36773)" + id="text149"><tspan + x="0" + y="11" + id="tspan145">Puedes llamar a cualquier </tspan><tspan + x="0" + y="30" + id="tspan147">otro componente</tspan></text> +</svg> diff --git a/docs/static/img/anchors.png b/docs/static/img/anchors.png Binary files differnew file mode 100644 index 0000000..ba74fe5 --- /dev/null +++ b/docs/static/img/anchors.png diff --git a/docs/static/img/apple-touch-icon.png b/docs/static/img/apple-touch-icon.png Binary files differnew file mode 100644 index 0000000..aa04ca4 --- /dev/null +++ b/docs/static/img/apple-touch-icon.png diff --git a/docs/static/img/composable.svg b/docs/static/img/composable.svg new file mode 100644 index 0000000..c54628c --- /dev/null +++ b/docs/static/img/composable.svg @@ -0,0 +1,3 @@ +<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" class="w-6 h-6"> + <path stroke-linecap="round" stroke-linejoin="round" d="M14.25 6.087c0-.355.186-.676.401-.959.221-.29.349-.634.349-1.003 0-1.036-1.007-1.875-2.25-1.875s-2.25.84-2.25 1.875c0 .369.128.713.349 1.003.215.283.401.604.401.959v0a.64.64 0 01-.657.643 48.39 48.39 0 01-4.163-.3c.186 1.613.293 3.25.315 4.907a.656.656 0 01-.658.663v0c-.355 0-.676-.186-.959-.401a1.647 1.647 0 00-1.003-.349c-1.036 0-1.875 1.007-1.875 2.25s.84 2.25 1.875 2.25c.369 0 .713-.128 1.003-.349.283-.215.604-.401.959-.401v0c.31 0 .555.26.532.57a48.039 48.039 0 01-.642 5.056c1.518.19 3.058.309 4.616.354a.64.64 0 00.657-.643v0c0-.355-.186-.676-.401-.959a1.647 1.647 0 01-.349-1.003c0-1.035 1.008-1.875 2.25-1.875 1.243 0 2.25.84 2.25 1.875 0 .369-.128.713-.349 1.003-.215.283-.4.604-.4.959v0c0 .333.277.599.61.58a48.1 48.1 0 005.427-.63 48.05 48.05 0 00.582-4.717.532.532 0 00-.533-.57v0c-.355 0-.676.186-.959.401-.29.221-.634.349-1.003.349-1.035 0-1.875-1.007-1.875-2.25s.84-2.25 1.875-2.25c.37 0 .713.128 1.003.349.283.215.604.401.96.401v0a.656.656 0 00.658-.663 48.422 48.422 0 00-.37-5.36c-1.886.342-3.81.574-5.766.689a.578.578 0 01-.61-.58v0z" /> +</svg> diff --git a/docs/static/img/encapsulated.svg b/docs/static/img/encapsulated.svg new file mode 100644 index 0000000..afb9119 --- /dev/null +++ b/docs/static/img/encapsulated.svg @@ -0,0 +1,3 @@ +<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" class="w-6 h-6"> + <path stroke-linecap="round" stroke-linejoin="round" d="M21 11.25v8.25a1.5 1.5 0 01-1.5 1.5H5.25a1.5 1.5 0 01-1.5-1.5v-8.25M12 4.875A2.625 2.625 0 109.375 7.5H12m0-2.625V7.5m0-2.625A2.625 2.625 0 1114.625 7.5H12m0 0V21m-8.625-9.75h18c.621 0 1.125-.504 1.125-1.125v-1.5c0-.621-.504-1.125-1.125-1.125h-18c-.621 0-1.125.504-1.125 1.125v1.5c0 .621.504 1.125 1.125 1.125z" /> +</svg> diff --git a/docs/static/img/favicon.png b/docs/static/img/favicon.png Binary files differnew file mode 100644 index 0000000..9b6ccd2 --- /dev/null +++ b/docs/static/img/favicon.png diff --git a/docs/static/img/favicon.svg b/docs/static/img/favicon.svg new file mode 100644 index 0000000..d243cf2 --- /dev/null +++ b/docs/static/img/favicon.svg @@ -0,0 +1,7 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<svg width="512" height="512" viewBox="0 0 135 135" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:svg="http://www.w3.org/2000/svg"> + <rect style="fill:#ffffff" width="128.0000" height="112.0000" x="4.0000" y="12.0000" /> + <rect style="fill:#55b2ff" width="128.0000" height="16.0000" x="4.0000" y="12.0000" /> + <path style="fill:#000000" d="m 1.6901338,127.07004 v 3e-5 C 1.3828219,126.9448 0.8768176,126.51851 0.56568825,126.12275 L -6.9341144e-6,125.40319 V 67.874657 C -6.9341144e-6,23.83623 0.07409113,10.183354 0.31607229,9.6520087 1.0219463,8.1019542 -3.7115247,8.2034435 67.877153,8.2034435 h 65.786837 l 0.90134,0.9018238 0.90133,0.9018247 c 0,0 -0.0453,38.573404 -0.0679,57.860106 -0.0226,19.286701 -0.0679,57.860102 -0.0679,57.860102 l -0.7336,0.73399 -0.73359,0.73399 m -3.69215,-5.16205 V 33.351884 H 5.291517 V 122.03323 M 130.17158,13.497852 H 5.291517 V 28.057476 H 130.17158 Z" /> + <rect style="fill:#d0ec7e;stroke:#000000;stroke-width:4.81818;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none" width="58.46307" height="58.463062" x="55.0000" y="50.0000" /> +</svg> diff --git a/docs/static/img/jinjax-logo-w.png b/docs/static/img/jinjax-logo-w.png Binary files differnew file mode 100644 index 0000000..74f52c3 --- /dev/null +++ b/docs/static/img/jinjax-logo-w.png diff --git a/docs/static/img/jinjax-logo-w.svg b/docs/static/img/jinjax-logo-w.svg new file mode 100644 index 0000000..0b8c9bf --- /dev/null +++ b/docs/static/img/jinjax-logo-w.svg @@ -0,0 +1 @@ +<svg xmlns="http://www.w3.org/2000/svg" width="87mm" height="24mm" viewBox="0 0 87 24"><g style="fill:#f0f0f0;fill-opacity:1"><g style="font-size:40px;line-height:1.25;white-space:pre;shape-inside:url(#d);fill:#f0f0f0;fill-opacity:1;stroke:none;stroke-width:1.44682;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" transform="matrix(.46943 0 0 .47617 -461.947 -45.454)"><path d="M1054.78 135.02c6.991 0 10.976-3.75 10.976-10.273v-18.691h-8.281v18.632c0 2.227-.957 3.399-2.813 3.399-1.836 0-3.027-1.27-3.027-3.496v-.04h-7.93v.06c0 6.523 4.316 10.41 11.074 10.41zm18.964-25.273c2.246 0 4.082-1.758 4.082-3.984 0-2.247-1.836-4.004-4.082-4.004-2.226 0-4.082 1.757-4.082 4.004 0 2.226 1.856 3.984 4.082 3.984zm-4.004 24.492h8.008v-21.953h-8.008zm11.29.001h8.007v-12.403c0-2.13 1.074-3.653 2.988-3.653 2.032 0 2.95 1.368 2.95 3.653v12.402h8.007v-14.18c0-5.273-2.5-8.32-7.343-8.32-3.047 0-5.313 1.602-6.211 4.024h-.39v-3.477h-8.009zm29.042-24.493c2.246 0 4.082-1.758 4.082-3.984 0-2.247-1.836-4.004-4.082-4.004-2.226 0-4.082 1.757-4.082 4.004 0 2.226 1.856 3.984 4.082 3.984zm-4.804 31.914c5.566 0 8.808-2.598 8.808-7.05v-22.325h-8.008v21.973c0 1.23-.703 1.757-2.324 1.757-.332 0-.683-.019-.918-.058v5.586c.469.058 1.64.117 2.442.117zm18.027-7.109c2.773 0 5.117-1.153 5.957-2.891h.39v2.578h7.852v-14.941c0-4.805-3.574-7.559-9.844-7.559-6.308 0-10.234 2.754-10.566 6.992l-.02.254h7.148l.04-.097c.37-.918 1.328-1.426 2.91-1.426 1.543 0 2.48.703 2.48 1.836v1.62l-4.336.255c-5.82.351-9.004 2.695-9.004 6.68v.038c0 4.004 2.793 6.66 6.992 6.66zm.645-7.266v-.04c0-1.054.976-1.757 2.656-1.874l3.047-.195v1.27c0 1.523-1.426 2.714-3.223 2.714-1.523 0-2.48-.742-2.48-1.875zm15.468 6.954h8.75l4.824-8.497h.157l4.863 8.496h9.219l-8.692-14.082v-.156l8.73-13.945h-9.179l-4.453 8.984h-.156l-4.434-8.984h-9.648l8.32 13.906v.156z" aria-label="JinjaX" style="font-weight:900;font-family:"SF Pro Text";-inkscape-font-specification:"SF Pro Text Heavy";fill:#f0f0f0;fill-opacity:1;stroke:none;stroke-width:1.44682;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"/></g></g><g style="fill:#90d73b;stroke:#4d4d4d;stroke-width:4"><path fill="#fff" stroke="none" d="M1.74 1.616h23.704v20.906H1.741Z"/><path fill="#e6e6e6" stroke="none" d="M1.74 1.616h23.704v2.986H1.741Z"/><path fill="#4d4d4d" stroke="none" d="M1 23c.003-7.61 0-15.455 0-22h25v22m-.894-.846V5.601H1.98v16.553m23.126-18.9V1.897H1.98v2.718h23.126z"/><path d="M92.311 45.905h26.316v26.316H92.311Z" transform="matrix(.18519 0 0 .18666 1 -.624)"/><path fill="#fff" d="M17.147 45.887h64.319v64.319H17.147Z" transform="matrix(.18519 0 0 .18666 1 -.624)"/><path fill="#55b2ff" d="M25.854 53.803h35.304v35.304H25.854Z" transform="matrix(.18519 0 0 .18666 1 -.624)"/><path fill="#e6e6e6" d="M92.311 83.873h26.316v26.316H92.311Z" transform="matrix(.18519 0 0 .18666 1 -.624)"/></g></svg>
\ No newline at end of file diff --git a/docs/static/img/jinjax-logo.png b/docs/static/img/jinjax-logo.png Binary files differnew file mode 100644 index 0000000..941df9f --- /dev/null +++ b/docs/static/img/jinjax-logo.png diff --git a/docs/static/img/jinjax-logo.svg b/docs/static/img/jinjax-logo.svg new file mode 100644 index 0000000..4870abb --- /dev/null +++ b/docs/static/img/jinjax-logo.svg @@ -0,0 +1 @@ +<svg xmlns="http://www.w3.org/2000/svg" width="87mm" height="24mm" viewBox="0 0 87 24"><g style="fill:#000;fill-opacity:1"><g style="font-size:40px;line-height:1.25;white-space:pre;shape-inside:url(#d);fill:#000;fill-opacity:1;stroke:none;stroke-width:1.44682;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" transform="matrix(.46943 0 0 .47617 -461.947 -45.454)"><path d="M1054.78 135.02c6.991 0 10.976-3.75 10.976-10.273v-18.691h-8.281v18.632c0 2.227-.957 3.399-2.813 3.399-1.836 0-3.027-1.27-3.027-3.496v-.04h-7.93v.06c0 6.523 4.316 10.41 11.074 10.41zm18.964-25.273c2.246 0 4.082-1.758 4.082-3.984 0-2.247-1.836-4.004-4.082-4.004-2.226 0-4.082 1.757-4.082 4.004 0 2.226 1.856 3.984 4.082 3.984zm-4.004 24.492h8.008v-21.953h-8.008zm11.29.001h8.007v-12.403c0-2.13 1.074-3.653 2.988-3.653 2.032 0 2.95 1.368 2.95 3.653v12.402h8.007v-14.18c0-5.273-2.5-8.32-7.343-8.32-3.047 0-5.313 1.602-6.211 4.024h-.39v-3.477h-8.009zm29.042-24.493c2.246 0 4.082-1.758 4.082-3.984 0-2.247-1.836-4.004-4.082-4.004-2.226 0-4.082 1.757-4.082 4.004 0 2.226 1.856 3.984 4.082 3.984zm-4.804 31.914c5.566 0 8.808-2.598 8.808-7.05v-22.325h-8.008v21.973c0 1.23-.703 1.757-2.324 1.757-.332 0-.683-.019-.918-.058v5.586c.469.058 1.64.117 2.442.117zm18.027-7.109c2.773 0 5.117-1.153 5.957-2.891h.39v2.578h7.852v-14.941c0-4.805-3.574-7.559-9.844-7.559-6.308 0-10.234 2.754-10.566 6.992l-.02.254h7.148l.04-.097c.37-.918 1.328-1.426 2.91-1.426 1.543 0 2.48.703 2.48 1.836v1.62l-4.336.255c-5.82.351-9.004 2.695-9.004 6.68v.038c0 4.004 2.793 6.66 6.992 6.66zm.645-7.266v-.04c0-1.054.976-1.757 2.656-1.874l3.047-.195v1.27c0 1.523-1.426 2.714-3.223 2.714-1.523 0-2.48-.742-2.48-1.875zm15.468 6.954h8.75l4.824-8.497h.157l4.863 8.496h9.219l-8.692-14.082v-.156l8.73-13.945h-9.179l-4.453 8.984h-.156l-4.434-8.984h-9.648l8.32 13.906v.156z" aria-label="JinjaX" style="font-weight:900;font-family:"SF Pro Text";-inkscape-font-specification:"SF Pro Text Heavy";fill:#000;fill-opacity:1;stroke:none;stroke-width:1.44682;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"/></g></g><g style="fill:#90d73b;stroke:#4d4d4d;stroke-width:4"><path fill="#fff" stroke="none" d="M1.74 1.616h23.704v20.906H1.741Z"/><path fill="#e6e6e6" stroke="none" d="M1.74 1.616h23.704v2.986H1.741Z"/><path fill="#4d4d4d" stroke="none" d="M1 23c.003-7.61 0-15.455 0-22h25v22m-.894-.846V5.601H1.98v16.553m23.126-18.9V1.897H1.98v2.718h23.126z"/><path d="M92.311 45.905h26.316v26.316H92.311Z" transform="matrix(.18519 0 0 .18666 1 -.624)"/><path fill="#fff" d="M17.147 45.887h64.319v64.319H17.147Z" transform="matrix(.18519 0 0 .18666 1 -.624)"/><path fill="#55b2ff" d="M25.854 53.803h35.304v35.304H25.854Z" transform="matrix(.18519 0 0 .18666 1 -.624)"/><path fill="#e6e6e6" d="M92.311 83.873h26.316v26.316H92.311Z" transform="matrix(.18519 0 0 .18666 1 -.624)"/></g></svg>
\ No newline at end of file diff --git a/docs/static/img/logo.png b/docs/static/img/logo.png Binary files differnew file mode 100644 index 0000000..4b12c00 --- /dev/null +++ b/docs/static/img/logo.png diff --git a/docs/static/img/logo.svg b/docs/static/img/logo.svg new file mode 100644 index 0000000..ed5ce3f --- /dev/null +++ b/docs/static/img/logo.svg @@ -0,0 +1,9 @@ +<svg width="512" height="512" viewBox="0 0 135 135" fill="#90d73b" stroke-width="4" stroke="#4d4d4d" xmlns="http://www.w3.org/2000/svg"> +<path d="M4 12h128v112H4z" fill="#fff" stroke-width="0"/> +<path d="M4 12h128v16H4z" fill="#e6e6e6" stroke-width="0"/> +<path d="M0 126.563C.014 85.794 0 43.763 0 8.7h135v117.862m-4.828-4.53V33.35H5.292v88.681M130.17 20.78V13.5H5.29v14.56h124.88z" fill="#4d4d4d" stroke-width="0"/> +<path d="M92.311 45.905h26.316v26.316H92.311z"/> +<path d="M17.147 45.887h64.319v64.319H17.147z" fill="#fff"/> +<path d="M25.854 53.803h35.304v35.304H25.854z" fill="#55b2ff"/> +<path d="M92.311 83.873h26.316v26.316H92.311z" fill="#e6e6e6"/> +</svg>
\ No newline at end of file diff --git a/docs/static/img/modern.svg b/docs/static/img/modern.svg new file mode 100644 index 0000000..e986962 --- /dev/null +++ b/docs/static/img/modern.svg @@ -0,0 +1,8 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> +<svg width="32mm" height="20mm" version="1.1" viewBox="0 0 32 20" xmlns="http://www.w3.org/2000/svg"> + <text transform="matrix(.38398 0 0 .3722 -42.207 -42.291)" fill="#000000" font-family="sans-serif" font-size="40px" style="line-height:1.25;shape-inside:url(#rect2079);white-space:pre" xml:space="preserve"/> + <path d="m21.48 2.5704e-6h-3.3855l-7.4789 20h3.3986z" fill="#3465a4" stroke-width=".7728"/> + <path d="m32 8.6678-10.497-3.7261v2.6314l7.9024 2.5711-7.9024 2.5812v2.5711l10.497-3.7261z" fill="#333" stroke-width=".44679"/> + <path d="m1.3575e-7 8.6678 10.497-3.7261v2.6314l-7.9024 2.5711 7.9024 2.5812v2.5711l-10.497-3.7261z" fill="#333" stroke-width=".44679"/> +</svg> diff --git a/docs/static/img/practical.svg b/docs/static/img/practical.svg new file mode 100644 index 0000000..702446c --- /dev/null +++ b/docs/static/img/practical.svg @@ -0,0 +1,3 @@ +<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" class="w-6 h-6"> + <path stroke-linecap="round" stroke-linejoin="round" d="M18.375 12.739l-7.693 7.693a4.5 4.5 0 01-6.364-6.364l10.94-10.94A3 3 0 1119.5 7.372L8.552 18.32m.009-.01l-.01.01m5.699-9.941l-7.81 7.81a1.5 1.5 0 002.112 2.13" /> +</svg> diff --git a/docs/static/img/simple.svg b/docs/static/img/simple.svg new file mode 100644 index 0000000..b69150b --- /dev/null +++ b/docs/static/img/simple.svg @@ -0,0 +1,3 @@ +<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" class="w-6 h-6"> + <path stroke-linecap="round" stroke-linejoin="round" d="M9 12.75L11.25 15 15 9.75M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /> +</svg> diff --git a/docs/static/img/slots-_slot.png b/docs/static/img/slots-_slot.png Binary files differnew file mode 100644 index 0000000..93cbab3 --- /dev/null +++ b/docs/static/img/slots-_slot.png diff --git a/docs/static/img/slots-diagram.png b/docs/static/img/slots-diagram.png Binary files differnew file mode 100644 index 0000000..c085250 --- /dev/null +++ b/docs/static/img/slots-diagram.png diff --git a/docs/static/img/spaghetti_code.png b/docs/static/img/spaghetti_code.png Binary files differnew file mode 100644 index 0000000..df44455 --- /dev/null +++ b/docs/static/img/spaghetti_code.png diff --git a/docs/static/img/ui-accordion.png b/docs/static/img/ui-accordion.png Binary files differnew file mode 100644 index 0000000..adddd7b --- /dev/null +++ b/docs/static/img/ui-accordion.png diff --git a/docs/static/img/ui-linkedlist.png b/docs/static/img/ui-linkedlist.png Binary files differnew file mode 100644 index 0000000..87667ba --- /dev/null +++ b/docs/static/img/ui-linkedlist.png diff --git a/docs/static/img/ui-menu.png b/docs/static/img/ui-menu.png Binary files differnew file mode 100644 index 0000000..ee82e03 --- /dev/null +++ b/docs/static/img/ui-menu.png diff --git a/docs/static/img/ui-popover.png b/docs/static/img/ui-popover.png Binary files differnew file mode 100644 index 0000000..22507f5 --- /dev/null +++ b/docs/static/img/ui-popover.png diff --git a/docs/static/img/ui-reldate.png b/docs/static/img/ui-reldate.png Binary files differnew file mode 100644 index 0000000..e2258c5 --- /dev/null +++ b/docs/static/img/ui-reldate.png diff --git a/docs/static/img/ui-tabs.png b/docs/static/img/ui-tabs.png Binary files differnew file mode 100644 index 0000000..7b3bccd --- /dev/null +++ b/docs/static/img/ui-tabs.png diff --git a/docs/static/prose.css b/docs/static/prose.css new file mode 100644 index 0000000..9a6531d --- /dev/null +++ b/docs/static/prose.css @@ -0,0 +1,637 @@ +.prose { + --cd-prose-body: #3f3f46; + --cd-prose-headings: #18181b; + --cd-prose-lead: #52525b; + --cd-prose-links: #18181b; + --cd-prose-bold: #18181b; + --cd-prose-counters: #71717a; + --cd-prose-bullets: #d4d4d8; + --cd-prose-hr: #e4e4e7; + --cd-prose-quotes: #18181b; + --cd-prose-quote-borders: #e4e4e7; + --cd-prose-captions: #71717a; + --cd-prose-code: #18181b; + --cd-prose-pre-code: rgb(238 238 238); + --cd-prose-pre-border: rgb(51, 51, 51); + --cd-prose-pre-bg: rgb(24 24 24); + --cd-prose-th-borders: #ddd; + --cd-prose-td-borders: #eee; + --cd-prose-bg-hover: rgba(0,0,0,0.035); + + --cd-prose-invert-body: #d4d4d8; + --cd-prose-invert-headings: #fff; + --cd-prose-invert-lead: #a1a1aa; + --cd-prose-invert-links: #fff; + --cd-prose-invert-bold: #fff; + --cd-prose-invert-counters: #a1a1aa; + --cd-prose-invert-bullets: #52525b; + --cd-prose-invert-hr: #3f3f46; + --cd-prose-invert-quotes: #f4f4f5; + --cd-prose-invert-quote-borders: #3f3f46; + --cd-prose-invert-captions: #a1a1aa; + --cd-prose-invert-code: #fff; + --cd-prose-invert-pre-code: rgb(238 238 238); + --cd-prose-invert-pre-border: rgb(51, 51, 51); + --cd-prose-invert-pre-bg: rgb(24 24 24); + --cd-prose-invert-th-borders: #52525b; + --cd-prose-invert-td-borders: #3f3f46; + --cd-prose-invert-bg-hover: rgba(0,0,0,0.035); +} + +.dark .prose { + --cd-prose-body: var(--cd-prose-invert-body); + --cd-prose-headings: var(--cd-prose-invert-headings); + --cd-prose-lead: var(--cd-prose-invert-lead); + --cd-prose-links: var(--cd-prose-invert-links); + --cd-prose-bold: var(--cd-prose-invert-bold); + --cd-prose-counters: var(--cd-prose-invert-counters); + --cd-prose-bullets: var(--cd-prose-invert-bullets); + --cd-prose-hr: var(--cd-prose-invert-hr); + --cd-prose-quotes: var(--cd-prose-invert-quotes); + --cd-prose-quote-borders: var(--cd-prose-invert-quote-borders); + --cd-prose-captions: var(--cd-prose-invert-captions); + --cd-prose-code: var(--cd-prose-invert-code); + --cd-prose-pre-code: var(--cd-prose-invert-pre-code); + --cd-prose-pre-border: var(--cd-prose-invert-pre-border); + --cd-prose-pre-bg: var(--cd-prose-invert-pre-bg); + --cd-prose-th-borders: var(--cd-prose-invert-th-borders); + --cd-prose-td-borders: var(--cd-prose-invert-td-borders); + --cd-prose-bg-hover: var(--cd-prose-invert-bg-hover); +} + +.prose { + font-size: 1em; + line-height: 1.75; + color: var(--cd-prose-body); +} + +.prose h1:not(:where([class~="not-prose"] *)) , +.prose h2:not(:where([class~="not-prose"] *)) , +.prose h3:not(:where([class~="not-prose"] *)) , +.prose h4:not(:where([class~="not-prose"] *)) , +.prose h5:not(:where([class~="not-prose"] *)) , +.prose h6:not(:where([class~="not-prose"] *)) { + font-family: var(--cd-font-serif); +} + +.prose :where(p):not(:where([class~="not-prose"] *)) { + margin-top: 1.25em; + margin-bottom: 1.25em; +} + +.prose :where([class~="lead"]):not(:where([class~="not-prose"] *)) { + color: var(--cd-prose-lead); + font-size: 1.25em; + line-height: 1.6; + margin-top: 1.2em; + margin-bottom: 1.2em; +} + +.prose :where(a):not(:where([class~="not-prose"] *)) { + color: var(--cd-prose-links); + text-decoration: underline; + font-weight: 500; +} + +.prose :where(strong):not(:where([class~="not-prose"] *)) { + color: var(--cd-prose-bold); + font-weight: 600; +} + +.prose :where(a strong):not(:where([class~="not-prose"] *)) { + color: inherit; +} + +.prose :where(blockquote strong):not(:where([class~="not-prose"] *)) { + color: inherit; +} + +.prose :where(thead th strong):not(:where([class~="not-prose"] *)) { + color: inherit; +} + +.prose :where(ol):not(:where([class~="not-prose"] *)) { + list-style-type: decimal; + margin-top: 1.25em; + margin-bottom: 1.25em; + padding-left: 1.625em; +} + +.prose :where(ol[type="A"]):not(:where([class~="not-prose"] *)) { + list-style-type: upper-alpha; +} + +.prose :where(ol[type="a"]):not(:where([class~="not-prose"] *)) { + list-style-type: lower-alpha; +} + +.prose :where(ol[type="A" s]):not(:where([class~="not-prose"] *)) { + list-style-type: upper-alpha; +} + +.prose :where(ol[type="a" s]):not(:where([class~="not-prose"] *)) { + list-style-type: lower-alpha; +} + +.prose :where(ol[type="I"]):not(:where([class~="not-prose"] *)) { + list-style-type: upper-roman; +} + +.prose :where(ol[type="i"]):not(:where([class~="not-prose"] *)) { + list-style-type: lower-roman; +} + +.prose :where(ol[type="I" s]):not(:where([class~="not-prose"] *)) { + list-style-type: upper-roman; +} + +.prose :where(ol[type="i" s]):not(:where([class~="not-prose"] *)) { + list-style-type: lower-roman; +} + +.prose :where(ol[type="1"]):not(:where([class~="not-prose"] *)) { + list-style-type: decimal; +} + +.prose :where(ul):not(:where([class~="not-prose"] *)) { + list-style-type: disc; + margin-top: 1.25em; + margin-bottom: 1.25em; + padding-left: 1.625em; +} + +.prose :where(ol > li):not(:where([class~="not-prose"] *))::marker { + font-weight: 400; + color: var(--cd-prose-counters); +} + +.prose :where(ul > li):not(:where([class~="not-prose"] *))::marker { + color: var(--cd-prose-bullets); +} + +.prose :where(hr):not(:where([class~="not-prose"] *)) { + border-color: var(--cd-prose-hr); + border-top-width: 1px; + margin-top: 3em; + margin-bottom: 3em; +} + +.prose :where(blockquote):not(:where([class~="not-prose"] *)) { + font-weight: 500; + font-style: italic; + color: var(--cd-prose-quotes); + border-left-width: 0.25em; + border-left-color: var(--cd-prose-quote-borders); + quotes: "\201C""\201D""\2018""\2019"; + margin-top: 1.6em; + margin-bottom: 1.6em; + padding-left: 1em; +} + +.prose :where(blockquote p:first-of-type):not(:where([class~="not-prose"] *))::before { + content: open-quote; +} + +.prose :where(blockquote p:last-of-type):not(:where([class~="not-prose"] *))::after { + content: close-quote; +} + +.prose :where(h1):not(:where([class~="not-prose"] *)) { + color: var(--cd-prose-headings); + font-weight: 800; + font-size: 2.2rem; + margin-top: 0; + margin-bottom: 0.8888889em; + line-height: 1.1111111; +} + +.prose :where(h1 strong):not(:where([class~="not-prose"] *)) { + font-weight: 900; + color: inherit; +} + +.prose :where(h2):not(:where([class~="not-prose"] *)) { + color: var(--cd-prose-headings); + font-weight: 700; + font-size: 1.8em; + margin-top: 1.2em; + margin-bottom: 0.5em; + line-height: 1.3333333; +} + +.prose :where(h2 strong):not(:where([class~="not-prose"] *)) { + font-weight: 800; + color: inherit; +} + +.prose :where(h3):not(:where([class~="not-prose"] *)) { + color: var(--cd-prose-headings); + font-weight: 600; + font-size: 1.4em; + margin-top: 1.6em; + margin-bottom: 0.4em; + line-height: 1.6; +} + +.prose :where(h3 strong):not(:where([class~="not-prose"] *)) { + font-weight: 700; + color: inherit; +} + +.prose :where(h4):not(:where([class~="not-prose"] *)) { + color: var(--cd-prose-headings); + font-weight: 600; + font-size: 1.2em; + margin-top: 1.5em; + margin-bottom: 0.5em; + line-height: 1.5; +} + +.prose :where(h4 strong):not(:where([class~="not-prose"] *)) { + font-weight: 700; + color: inherit; +} + +.prose :where(h5):not(:where([class~="not-prose"] *)) { + color: var(--cd-prose-headings); + font-weight: 600; + font-size: 1em; + margin-top: 1em; + margin-bottom: 0.5em; + line-height: 1.5; +} + + +.prose :where(h6):not(:where([class~="not-prose"] *)) { + color: var(--cd-prose-headings); + font-weight: 600; + font-size: 1em; + margin-top: 1em; + margin-bottom: 0.5em; + line-height: 1.4; +} + + +.prose :where(img):not(:where([class~="not-prose"] *)) { + margin-top: 2em; + margin-bottom: 2em; +} + +.prose :where(figure > *):not(:where([class~="not-prose"] *)) { + margin-top: 0; + margin-bottom: 0; +} + +.prose :where(figcaption):not(:where([class~="not-prose"] *)) { + color: var(--cd-prose-captions); + font-size: 0.875em; + line-height: 1.4285714; + margin-top: 0.8571429em; +} + +.prose :where(code):not(:where([class~="not-prose"] *)) { + color: var(--cd-prose-code); + font-size: 0.98em; + letter-spacing: -0.02em; +} +.prose :where(code):not(:where(pre code)):not(:where([class~="not-prose"] *)) { + padding: 0.1em; + background: var(--cd-bg-color-hover); +} + +.prose :where(a code):not(:where([class~="not-prose"] *)) { + color: inherit; +} + +.prose :where(h1 code):not(:where([class~="not-prose"] *)) { + color: inherit; +} + +.prose :where(h2 code):not(:where([class~="not-prose"] *)) { + color: inherit; + font-size: 0.875em; +} + +.prose :where(h3 code):not(:where([class~="not-prose"] *)) { + color: inherit; + font-size: 0.9em; +} + +.prose :where(h4 code):not(:where([class~="not-prose"] *)) { + color: inherit; +} + +.prose :where(blockquote code):not(:where([class~="not-prose"] *)) { + color: inherit; +} + +.prose :where(thead th code):not(:where([class~="not-prose"] *)) { + color: inherit; +} + +.prose :where(table):not(:where([class~="not-prose"] *)) { + width: 100%; + table-layout: auto; + text-align: left; + margin-top: 2em; + margin-bottom: 2em; + font-size: 0.875em; + line-height: 1.7142857; + border-width: 1px; + border-color: var(--cd-prose-td-borders); +} + +.prose :where(thead):not(:where([class~="not-prose"] *)) { + border-bottom-width: 1px; + border-bottom-color: var(--cd-prose-th-borders); +} + +.prose :where(thead th):not(:where([class~="not-prose"] *)) { + color: var(--cd-prose-headings); + font-weight: 600; + vertical-align: bottom; + border-left-width: 1px; + border-left-color: var(--cd-prose-th-borders); + /* text-transform: uppercase; */ +} +.prose :where(thead th:first-child):not(:where([class~="not-prose"] *)) { + border-left-width: 0; +} + +.prose :where(tbody tr):not(:where([class~="not-prose"] *)) { + border-bottom-width: 1px; + border-bottom-color: var(--cd-prose-td-borders); + transition: background-color 125ms; +} +.prose :where(tbody tr:hover):not(:where([class~="not-prose"] *)) { + background-color: var(--cd-prose-bg-hover); +} + +.prose :where(tbody tr:last-child):not(:where([class~="not-prose"] *)) { + border-bottom-width: 0; +} + +.prose :where(tbody td):not(:where([class~="not-prose"] *)) { + vertical-align: baseline; + border-left-width: 1px; + border-left-color: var(--cd-prose-th-borders); +} +.prose :where(tbody td:first-child):not(:where([class~="not-prose"] *)) { + border-left-width: 0; +} +.prose :where(tbody td p:first-child):not(:where([class~="not-prose"] *)) { + margin-top: 0; +} + +.prose :where(tfoot):not(:where([class~="not-prose"] *)) { + border-top-width: 1px; + border-top-color: var(--cd-prose-th-borders); +} + +.prose :where(tfoot td):not(:where([class~="not-prose"] *)) { + vertical-align: top; +} + +.prose :where(th, td):not(:where([class~="not-prose"] *)) { + padding: 0.5rem 1rem; +} + +.prose :where(video):not(:where([class~="not-prose"] *)) { + margin-top: 2em; + margin-bottom: 2em; +} + +.prose :where(figure):not(:where([class~="not-prose"] *)) { + margin-top: 2em; + margin-bottom: 2em; +} + +.prose :where(li):not(:where([class~="not-prose"] *)) { + margin-top: 0.5em; + margin-bottom: 0.5em; +} + +.prose :where(ol > li):not(:where([class~="not-prose"] *)) { + padding-left: 0.375em; +} + +.prose :where(ul > li):not(:where([class~="not-prose"] *)) { + padding-left: 0.375em; +} + +.prose :where(.prose > ul > li p):not(:where([class~="not-prose"] *)) { + margin-top: 0.75em; + margin-bottom: 0.75em; +} + +.prose :where(.prose > ul > li > *:first-child):not(:where([class~="not-prose"] *)) { + margin-top: 1.25em; +} + +.prose :where(.prose > ul > li > *:last-child):not(:where([class~="not-prose"] *)) { + margin-bottom: 1.25em; +} + +.prose :where(.prose > ol > li > *:first-child):not(:where([class~="not-prose"] *)) { + margin-top: 1.25em; +} + +.prose :where(.prose > ol > li > *:last-child):not(:where([class~="not-prose"] *)) { + margin-bottom: 1.25em; +} + +.prose :where(ul ul, ul ol, ol ul, ol ol):not(:where([class~="not-prose"] *)) { + margin-top: 0.75em; + margin-bottom: 0.75em; +} + +.prose :where(hr + *):not(:where([class~="not-prose"] *)) { + margin-top: 0; +} + +.prose :where(h2 + *):not(:where([class~="not-prose"] *)) { + margin-top: 0; +} + +.prose :where(h3 + *):not(:where([class~="not-prose"] *)) { + margin-top: 0; +} + +.prose :where(h4 + *):not(:where([class~="not-prose"] *)) { + margin-top: 0; +} + +.prose :where(.prose > :first-child):not(:where([class~="not-prose"] *)) { + margin-top: 0; +} + +.prose :where(.prose > :last-child):not(:where([class~="not-prose"] *)) { + margin-bottom: 0; +} + +.prose :where(.task-list .task-list):not(:where([class~="not-prose"] *)) { + padding-left: 1em; +} + +.prose :where(dl):not(:where([class~="not-prose"] *)) { + margin-top: 1.25em; + margin-bottom: 1.25em; +} + +.prose :where(dt):not(:where([class~="not-prose"] *)) { + font-weight: bold; +} + +.prose :where(dd):not(:where([class~="not-prose"] *)) { + padding-left: 1em; +} + +pre { + border: 1px solid rgb(var(--cd-prose-pre-border)); + overflow-x: auto; + font-weight: 400; + font-feature-settings: "kern"; + white-space: pre; + scrollbar-width: thin; + padding: 1.25rem 1.5rem; +} +pre::-webkit-scrollbar { + width: 2px; + background-color: ButtonFace; +} +pre:has([data-linenos]) { + padding-left: 0; +} +pre code { + background-color: transparent; + border-width: 0; + border-radius: 0; + padding: 0; + font-weight: inherit; + color: inherit; + font-size: inherit; + font-family: inherit; + line-height: inherit; + +} +pre a { + text-decoration: none; +} + +.highlight { + margin-top: 0.5rem; + margin-bottom: 1rem; + border-radius: 6px; +} +.highlight:has(> .filename) { + background-color: rgb(249 250 251); + border: 1px solid rgb(153, 153, 153); +} +.highlight:is(.dark *):has(> .filename) { + background-color: rgb(55 65 81); + border-color: rgb(75 85 99); +} +.highlight > .filename { + border-radius: 6px 0 0 0; + display: inline-block; + border-right: 1px solid rgb(153, 153, 153); + background-color: #e7e9ed; + padding: 0.5rem; + color: #333; + font-weight: 500; + font-size: 0.9em; +} +.highlight:is(.dark *) > .filename { + border-color: rgb(75 85 99); + background-color: #111; + color: rgb(255 255 255); +} +.highlight pre { + background-color: rgba(0, 0, 0, 0.9); + border-radius: 6px; + font-size: 0.98rem; + line-height: 1.4; +} +.highlight .filename + pre { + border-radius: 0 0 6px 6px; +} +.highlight pre code { color: white; } + +.highlight pre code [data-linenos]:before { + content: attr(data-linenos); + display: inline-block; + width: 3rem; + text-align: right; + padding-right: 1rem; + white-space: nowrap; + color: rgb(82 82 91); + font-size: 0.75rem; +} +.highlight .hll { + background-color: #333; + display: block; +} + +.highlight .c { color: hsl(31, 76%, 64%) } /* Comment */ +.highlight .err { color: #960050; background-color: #1e0010 } /* Error */ +.highlight .k { color: #66d9ef } /* Keyword */ +.highlight .l { color: #ae81ff } /* Literal */ +.highlight .n { color: #f8f8f2 } /* Name */ +.highlight .o { color: #f92672 } /* Operator */ +.highlight .p { color: #f8f8f2 } /* Punctuation */ +.highlight .cm { color: hsl(30, 20%, 50%) } /* Comment.Multiline */ +.highlight .cp { color: hsl(30, 20%, 50%) } /* Comment.Preproc */ +.highlight .c1 { color: hsl(30, 20%, 50%) } /* Comment.Single */ +.highlight .cs { color: hsl(30, 20%, 50%) } /* Comment.Special */ +.highlight .ge { font-style: italic } /* Generic.Emph */ +.highlight .gs { font-weight: bold } /* Generic.Strong */ +.highlight .kc { color: #66d9ef } /* Keyword.Constant */ +.highlight .kd { color: #66d9ef } /* Keyword.Declaration */ +.highlight .kn { color: #f92672 } /* Keyword.Namespace */ +.highlight .kp { color: #66d9ef } /* Keyword.Pseudo */ +.highlight .kr { color: #66d9ef } /* Keyword.Reserved */ +.highlight .kt { color: #66d9ef } /* Keyword.Type */ +.highlight .ld { color: #e6db74 } /* Literal.Date */ +.highlight .m { color: #ae81ff } /* Literal.Number */ +.highlight .s { color: #e6db74 } /* Literal.String */ +.highlight .na { color: #a6e22e } /* Name.Attribute */ +.highlight .nb { color: #f8f8f2 } /* Name.Builtin */ +.highlight .nc { color: #a6e22e } /* Name.Class */ +.highlight .no { color: #66d9ef } /* Name.Constant */ +.highlight .nd { color: #a6e22e } /* Name.Decorator */ +.highlight .ni { color: #f8f8f2 } /* Name.Entity */ +.highlight .ne { color: #a6e22e } /* Name.Exception */ +.highlight .nf { color: #a6e22e } /* Name.Function */ +.highlight .nl { color: #f8f8f2 } /* Name.Label */ +.highlight .nn { color: #f8f8f2 } /* Name.Namespace */ +.highlight .nx { color: #a6e22e } /* Name.Other */ +.highlight .py { color: #f8f8f2 } /* Name.Property */ +.highlight .nt { color: #f92672 } /* Name.Tag */ +.highlight .nv { color: #f8f8f2 } /* Name.Variable */ +.highlight .ow { color: #f92672 } /* Operator.Word */ +.highlight .w { color: #f8f8f2 } /* Text.Whitespace */ +.highlight .mf { color: #ae81ff } /* Literal.Number.Float */ +.highlight .mh { color: #ae81ff } /* Literal.Number.Hex */ +.highlight .mi { color: #ae81ff } /* Literal.Number.Integer */ +.highlight .mo { color: #ae81ff } /* Literal.Number.Oct */ +.highlight .sb { color: #e6db74 } /* Literal.String.Backtick */ +.highlight .sc { color: #e6db74 } /* Literal.String.Char */ +.highlight .sd { color: #e6db74 } /* Literal.String.Doc */ +.highlight .s2 { color: #e6db74 } /* Literal.String.Double */ +.highlight .se { color: #ae81ff } /* Literal.String.Escape */ +.highlight .sh { color: #e6db74 } /* Literal.String.Heredoc */ +.highlight .si { color: #e6db74 } /* Literal.String.Interpol */ +.highlight .sx { color: #e6db74 } /* Literal.String.Other */ +.highlight .sr { color: #e6db74 } /* Literal.String.Regex */ +.highlight .s1 { color: #e6db74 } /* Literal.String.Single */ +.highlight .ss { color: #e6db74 } /* Literal.String.Symbol */ +.highlight .bp { color: #f8f8f2 } /* Name.Builtin.Pseudo */ +.highlight .vc { color: #f8f8f2 } /* Name.Variable.Class */ +.highlight .vg { color: #f8f8f2 } /* Name.Variable.Global */ +.highlight .vi { color: #f8f8f2 } /* Name.Variable.Instance */ +.highlight .il { color: #ae81ff } /* Literal.Number.Integer.Long */ + +.highlight .gh { } /* Generic Heading & Diff Header */ +.highlight .gu { color: hsl(30, 20%, 50%); } /* Generic.Subheading & Diff Unified/Comment? */ +.highlight .gd { color: #f92672; } /* Generic.Deleted & Diff Deleted */ +.highlight .gi { color: #a6e22e; } /* Generic.Inserted & Diff Inserted */ diff --git a/docs/static/theme.css b/docs/static/theme.css new file mode 100644 index 0000000..8dad4aa --- /dev/null +++ b/docs/static/theme.css @@ -0,0 +1,1808 @@ +/* latin */ +@font-face { + font-family: "Karla"; + font-style: normal; + font-weight: 400; + src: url("./fonts/karla-regular-.woff2") format("woff2"); + unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD; +} +/* latin-ext */ +@font-face { + font-family: "Karla"; + font-style: normal; + font-weight: 400; + src: url("./fonts/karla-regular-ext.woff2") format("woff2"); + unicode-range: U+0100-02AF, U+0304, U+0308, U+0329, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF; +} +/* latin */ +@font-face { + font-family: "Karla"; + font-style: normal; + font-weight: 700; + src: url("./fonts/karla-bold.woff2") format("woff2"); + unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD; +} +/* latin-ext */ +@font-face { + font-family: "Karla"; + font-style: normal; + font-weight: 700; + src: url("./fonts/karla-bold-ext.woff2") format("woff2"); + unicode-range: U+0100-02AF, U+0304, U+0308, U+0329, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF; +} +@font-face { + font-family: "Material Symbols Rounded"; + font-style: normal; + font-weight: 100 700; + font-display: block; + src: url("./fonts/material-symbols-rounded.woff2") format("woff2"); +} + +/* ---------------------------------------------------------------------- */ + +html { + --cd-font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace; + --cd-font-sans: Karla, sans-serif; + --cd-font-icons: "Material Symbols Rounded"; + + --cd-padding-left: max(1rem, env(safe-area-inset-right)); + --cd-padding-right: max(1rem, env(safe-area-inset-left)); + + --cd-brand-color: #fbbf24; + --cd-bg-color-light: rgb(255 255 255); + --cd-bg-color-dark: rgb(23 23 23); + + --cd-bg-color: var(--cd-bg-color-light); + --cd-bg-color-hover: rgb(240, 240, 240); + --cd-text-color: rgb(23 23 23); + --cd-text-color-mild: rgb(63 63 70); + --cd-border-color: #e3e3e4; + + --cd-nav-bg-color: rgba(255, 255, 255, 0.8); + --cd-nav-bg-color-hover: rgb(244, 244, 244); + + --doc-symbol-parameter-fg-color: #df50af; + --doc-symbol-attribute-fg-color: #953800; + --doc-symbol-function-fg-color: #8250df; + --doc-symbol-method-fg-color: #8250df; + --doc-symbol-class-fg-color: #0550ae; + --doc-symbol-module-fg-color: #5cad0f; + + --doc-symbol-parameter-bg-color: #df50af1a; + --doc-symbol-attribute-bg-color: #9538001a; + --doc-symbol-function-bg-color: #8250df1a; + --doc-symbol-method-bg-color: #8250df1a; + --doc-symbol-class-bg-color: #0550ae1a; + --doc-symbol-module-bg-color: #5cad0f1a; +} + +html.dark { + --cd-brand-color: #3451b2; + + --cd-bg-color: var(--cd-bg-color-dark); + --cd-bg-color-hover: rgb(40 40 40); + --cd-text-color: rgb(250 250 250); + --cd-text-color-mild: rgb(161 161 170); + --cd-border-color: rgb(60 60 60); + + --cd-nav-bg-color: rgba(60, 60, 60, 0.8); + --cd-nav-bg-color-hover: rgb(70, 70, 70); + + --doc-symbol-parameter-fg-color: #ffa8cc; + --doc-symbol-attribute-fg-color: #ffa657; + --doc-symbol-function-fg-color: #d2a8ff; + --doc-symbol-method-fg-color: #d2a8ff; + --doc-symbol-class-fg-color: #79c0ff; + --doc-symbol-module-fg-color: #baff79; + + --doc-symbol-parameter-bg-color: #ffa8cc1a; + --doc-symbol-attribute-bg-color: #ffa6571a; + --doc-symbol-function-bg-color: #d2a8ff1a; + --doc-symbol-method-bg-color: #d2a8ff1a; + --doc-symbol-class-bg-color: #79c0ff1a; + --doc-symbol-module-bg-color: #baff791a; +} + +/* ---------------------------------------------------------------------- */ + +/* +1. Prevent padding and border from affecting element width. (https://github.com/mozdevs/cssremedy/issues/4) +2. Allow adding a border to an element by just adding a border-width. (https://github.com/tailwindcss/tailwindcss/pull/116) +*/ +*, +::before, +::after { + /* 1 */ + box-sizing: border-box; + /* 2 */ + border-width: 0; + /* 2 */ + border-style: solid; + /* 2 */ + border-color: #e5e7eb; +} +::before, +::after { + --cd-content: ""; +} + +/* +1. Use a consistent sensible line-height in all browsers. +2. Prevent adjustments of font size after orientation changes in iOS. +3. Use a more readable tab size. +4. Set default font sans +4. Disable tap highlights on iOS +*/ +html, +:host { + /* 1 */ + line-height: 1.5; + /* 2 */ + tab-size: 4; + /* 3 */ + -webkit-text-size-adjust: 100%; + /* 4 */ + font-family: var(--cd-font-sans); + font-feature-settings: normal; + font-variation-settings: normal; + /* 5 */ + -webkit-tap-highlight-color: transparent; +} + +/* +1. Remove the margin in all browsers. +2. Inherit line-height from `html` so users can set them as a class + directly on the `html` element. +*/ +body { + /* 1 */ + margin: 0; + /* 2 */ + line-height: inherit; +} + +/* +1. Add the correct height in Firefox. +2. Correct the inheritance of border color in Firefox. (https://bugzilla.mozilla.org/show_bug.cgi?id=190655) +3. Ensure horizontal rules are visible by default. +*/ +hr { + /* 1 */ + height: 0; + /* 2 */ + color: inherit; + /* 3 */ + border-top-width: 1px; +} + +/* +Add the correct text decoration in Chrome, Edge, and Safari. +*/ +abbr:where([title]) { + -webkit-text-decoration: underline dotted; + text-decoration: underline dotted; +} + +/* Remove the default font size and weight for headings. */ +h1, h2, h3, h4, h5, h6 { + font-size: inherit; + font-weight: inherit; +} + +/* Reset links to optimize for opt-in styling instead of opt-out. */ +a { + color: inherit; + text-decoration: inherit; +} + +/* Add the correct font weight in Edge and Safari. */ +b, strong { + font-weight: bolder; +} + +/* +1. Use the user"s configured `mono` font-family by default. +2. Correct the odd `em` font sizing in all browsers. +*/ +code, kbd, samp, pre { + /* 1 */ + font-family: var(--cd-font-mono); + font-feature-settings: normal; + font-variation-settings: normal; + /* 2 */ + font-size: 1em; +} + +/* Add the correct font size in all browsers. */ +small { + font-size: 80%; +} + +/* +Prevent `sub` and `sup` elements from affecting the line height in +all browsers. +*/ +sub, sup { + font-size: 75%; + line-height: 0; + position: relative; + vertical-align: baseline; +} +sub { + bottom: -0.25em; +} +sup { + top: -0.5em; +} + +/* +1. Remove text indentation from table contents in Chrome and Safari. (https://bugs.chromium.org/p/chromium/issues/detail?id=999088, https://bugs.webkit.org/show_bug.cgi?id=201297) +2. Correct table border color inheritance in all Chrome and Safari. (https://bugs.chromium.org/p/chromium/issues/detail?id=935729, https://bugs.webkit.org/show_bug.cgi?id=195016) +3. Remove gaps between table borders by default. +*/ +table { + /* 1 */ + text-indent: 0; + /* 2 */ + border-color: inherit; + /* 3 */ + border-collapse: collapse; +} + +/* +1. Change the font styles in all browsers. +2. Remove the margin in Firefox and Safari. +3. Remove default padding in all browsers. +*/ +button, input, optgroup, select, textarea { + /* 1 */ + font-family: inherit; + font-feature-settings: inherit; + font-variation-settings: inherit; + font-size: 100%; + font-weight: inherit; + line-height: inherit; + letter-spacing: inherit; + color: inherit; + /* 2 */ + margin: 0; + /* 3 */ + padding: 0; +} + +/* Remove the inheritance of text transform in Edge and Firefox. */ +button, select { + text-transform: none; +} + +/* +1. Correct the inability to style clickable types in iOS and Safari. +2. Remove default button styles. +*/ +button, +input:where([type="button"]), +input:where([type="reset"]), +input:where([type="submit"]) { + /* 1 */ + -webkit-appearance: button; + /* 2 */ + background-color: transparent; + background-image: none; +} + +/* Use the modern Firefox focus style for all focusable elements. */ +:-moz-focusring { + outline: auto; +} + +/* Remove the additional `:invalid` styles in Firefox. (https://github.com/mozilla/gecko-dev/blob/2f9eacd9d3d995c937b4251a5557d95d494c9be1/layout/style/res/forms.css#L728-L737) */ +:-moz-ui-invalid { + box-shadow: none; +} + +/* Add the correct vertical alignment in Chrome and Firefox. */ +progress { + vertical-align: baseline; +} + +/* Correct the cursor style of increment and decrement buttons in Safari. */ +::-webkit-inner-spin-button, +::-webkit-outer-spin-button { + height: auto; +} + +/* +1. Correct the odd appearance in Chrome and Safari. +2. Correct the outline style in Safari. +*/ +[type="search"] { + /* 1 */ + -webkit-appearance: textfield; + /* 2 */ + outline-offset: -2px; +} + +/* Remove the inner padding in Chrome and Safari on macOS. */ +::-webkit-search-decoration { + -webkit-appearance: none; +} + +/* +1. Correct the inability to style clickable types in iOS and Safari. +2. Change font properties to `inherit` in Safari. +*/ +::-webkit-file-upload-button { + /* 1 */ + -webkit-appearance: button; + /* 2 */ + font: inherit; +} + +/* Add the correct display in Chrome and Safari. */ +summary { + display: list-item; +} + +/* Removes the default spacing and border for appropriate elements. */ +blockquote, dl, dd, h1, h2, h3, h4, h5, h6, hr, figure, p, pre { + margin: 0; +} +fieldset { + margin: 0; + padding: 0; +} +legend { + padding: 0; +} +ol, ul, menu { + list-style: none; + margin: 0; + padding: 0; +} + +/* Reset default styling for dialogs. */ +dialog { + padding: 0; +} + +/* Prevent resizing textareas horizontally by default. */ +textarea { + resize: vertical; +} + +/* +1. Reset the default placeholder opacity in Firefox. (https://github.com/tailwindlabs/tailwindcss/issues/3300) +2. Set the default placeholder color to the user"s configured gray 400 color. +*/ +input::-moz-placeholder, +textarea::-moz-placeholder { + /* 1 */ + opacity: 1; + /* 2 */ + color: #9ca3af; +} +input::placeholder, +textarea::placeholder { + /* 1 */ + opacity: 1; + /* 2 */ + color: #9ca3af; +} + +/* Set the default cursor for buttons. */ +button, +[role="button"] { + cursor: pointer; +} + +/* Make sure disabled buttons don"t get the pointer cursor. */ +:disabled { + cursor: default; +} + +/* +1. Make replaced elements `display: block` by default. (https://github.com/mozdevs/cssremedy/issues/14) +2. Add `vertical-align: middle` to align replaced elements more sensibly by default. (https://github.com/jensimmons/cssremedy/issues/14#issuecomment-634934210) + This can trigger a poorly considered lint error in some tools but is included by design. +*/ +img, svg, video, canvas, audio, iframe, embed, object { + /* 1 */ + display: block; + /* 2 */ + vertical-align: middle; +} + +/* +Constrain images and videos to the parent width and preserve their +intrinsic aspect ratio. (https://github.com/mozdevs/cssremedy/issues/14) +*/ +img, video { + max-width: 100%; + height: auto; +} + +/* Make elements with the HTML hidden attribute stay hidden by default */ +[hidden] { + display: none; +} + +/* ---------------------------------------------------------------------- */ + +html:has(.cd-nav-mobile:popover-open) { + overflow: hidden !important; + overflow-x: hidden !important; + overflow-y: hidden !important; +} +body { + position: relative; + min-height: 100vh; + color: var(--cd-text-color); + -webkit-font-smoothing: antialiased; + -moz-osx-font-smoothing: grayscale; + background-color: var(--cd-bg-color-light); + transition: background 100ms linear; +} +html.dark body { + background-color: var(--cd-bg-color-dark); +} + +.keys, +kbd:not(.keys > kbd) { + font-family: var(--cd-font-mono); + display: inline-block; + padding: 0.2rem 0.25rem; + margin-left: 0.1rem; + margin-right: 0.1rem; + font-size: 0.875rem; + line-height: 1; + font-weight: 500; + letter-spacing: -0.025em; + line-height: 1; + border-radius: 0.25rem; + border-width: 1px; + border-color: #ffffff; + box-shadow: 0 0 2px 0 #000; + + &:is(.dark *) { + border-color: rgb(0 0 0); + background-color: rgb(24 24 27); + } +} + +.scrollbar-thin { + scrollbar-width: thin; /* Firefox */ +} +.scrollbar-thin::-webkit-scrollbar { + /* Safari and Chrome */ + width: 2px; + background-color: ButtonFace; +} +.scrollbar-default { + -ms-overflow-style: auto; /* IE and Edge */ + scrollbar-width: auto; /* Firefox */ +} +.scrollbar-default::-webkit-scrollbar { + /* Safari and Chrome */ + width: auto; +} + +a.headerlink { + margin-left: .25rem; + display: inline-block; + text-decoration-line: none; + opacity: 0; + transition-property: opacity; + transition-timing-function: cubic-bezier(.4,0,.2,1); + transition-duration: .15s; +} +h2:hover a.headerlink, +h3:hover a.headerlink, +h4:hover a.headerlink, +h5:hover a.headerlink, +h6:hover a.headerlink { + opacity: 0.5; +} + +/* ---------------------------------------------------------------------- */ + +.doc-symbol { + border-radius: 0.1rem; + padding: 0 0.3em; + font-weight: bold; +} +.doc-symbol-attr { + color: var(--doc-symbol-attribute-fg-color) !important; + background-color: var(--doc-symbol-attribute-bg-color) !important; +} +.doc-symbol-function { + color: var(--doc-symbol-function-fg-color) !important; + background-color: var(--doc-symbol-function-bg-color) !important; +} +.doc-symbol-method { + color: var(--doc-symbol-method-fg-color) !important; + background-color: var(--doc-symbol-method-bg-color) !important; +} +.doc-symbol-class { + color: var(--doc-symbol-class-fg-color) !important; + background-color: var(--doc-symbol-class-bg-color) !important; +} +.doc-symbol-module { + color: var(--doc-symbol-module-fg-color) !important; + background-color: var(--doc-symbol-module-bg-color) !important; +} + +.doc-oname { + font-weight: normal; +} +.doc-olabel { + font-size: 0.6em !important; + color: #36464e !important; + font-weight: 400; + padding: 0.1rem 0.4rem !important; +} + +.doc-attrs ~ .doc-methods, +.doc-properties ~ .doc-methods { + margin-top; 1rem; +} + +/* ---------------------------------------------------------------------- */ + +.icon { + font-family: var(--cd-font-icons); + font-weight: normal; + font-style: normal; + letter-spacing: normal; + text-transform: none; + display: inline-block; + white-space: nowrap; + word-wrap: normal; + direction: ltr; + -webkit-font-smoothing: antialiased; + -moz-osx-font-smoothing: grayscale; + text-rendering: optimizeLegibility; + font-feature-settings: "liga"; + cursor: default; + pointer-events: none; +} + +/* ---------------------------------------------------------------------- */ + +.cd-source { + display: flex; + align-items: center; + font-size: 0.85rem; + line-height: 1.2; + white-space: nowrap; + cursor: pointer; + text-decoration: none; + padding: 0.5rem 0.75rem; + min-width: 150px; + backdrop-filter: blur(4px); + background-color: var(--cd-nav-bg-color); + border-radius: 1rem; + transition: background 300ms ease-in-out; + + &:hover { + background-color: var(--cd-nav-bg-color-hover); + } + & > div { + opacity: 0.8; + transition: opacity 300ms ease-in-out; + } + &:hover > div { + opacity: 1; + } + & .cd-source__icon { + padding-right: 0.5rem; + } + & .cd-source__icon svg { + height: 1.5rem; + width: 1.5rem; + fill: currentcolor; + display: block; + } + & .cd-source__label { + font-size: 0.9rem; + font-weight: bold; + } + & .cd-source__repo { + display: inline-block; + max-width: calc(100% - 1.2rem); + overflow: hidden; + text-overflow: ellipsis; + vertical-align: middle; + } + @media (max-width: 480px) { + & { + min-width: 0; + } + & .cd-source__icon { + padding-right: 0; + } + & .cd-source__repo { + display: none; + } + } + & .cd-source__facts { + display: hidden; + gap: 0.4rem; + list-style-type: none; + margin: 0.1rem 0 0; + overflow: hidden; + padding: 0; + width: 100%; + opacity: 0; + transform: translateY(100%); + transition: all 0.5s ease-out; + } + & .cd-source__facts.cd-source__facts--visible { + display: flex; + opacity: 1; + transform: translateY(0); + } + & .cd-source__facts [data-fact] { + overflow: hidden; + text-overflow: ellipsis; + display: flex; + align-items: center; + line-height: 1; + } + & .cd-source__facts [data-fact]:nth-child(1n+2) { + flex-shrink: 0; + } + & .cd-source__facts [data-fact]:not([hidden]):before { + width: 0.6rem; + padding-right: 0.8rem; + font-family: var(--cd-font-icons); + font-weight: normal; + font-style: normal; + letter-spacing: normal; + text-transform: none; + display: inline-block; + white-space: nowrap; + word-wrap: normal; + direction: ltr; + -webkit-font-smoothing: antialiased; + -moz-osx-font-smoothing: grayscale; + text-rendering: optimizeLegibility; + font-feature-settings: "liga"; + cursor: default; + pointer-events: none; + } + & .cd-source__facts [data-fact="version"]:not([hidden]):before { + content: "tag"; + } + & .cd-source__facts [data-fact="stars"]:not([hidden]):before { + content: "star"; + } + & .cd-source__facts [data-fact="forks"]:not([hidden]):before { + content: "fork_right"; + } + & .cd-source__facts [data-fact="numrepos"]:not([hidden]):before { + content: "numbers"; + } +} + +/* ---------------------------------------------------------------------- */ + +.cd-cards { + & { + display: grid; + grid-gap: 1rem; + } + @media (min-width: 480px) { + & { grid-template-columns: repeat(2, 1fr); } + } + @media (min-width: 900px) { + & { grid-template-columns: repeat(4, 1fr); } + } + & a.card { + display: block; + border: 1px solid var(--cd-border-color); + padding: 1rem; + border-radius: 6px; + background-color: var(--cd-bg-color); + transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1); + } + & a.card:hover { + display: block; + background-color: var(--cd-bg-color-hover); + } + & a.card h2 { + text-decoration: none; + font-family: var(--cd-font-sans); + font-weight: bold; + } +} + +/* ---------------------------------------------------------------------- */ + +.cd-text-button { + display: inline-flex; + cursor: pointer; + touch-action: manipulation; + -webkit-appearance: none; + -moz-appearance: none; + appearance: none; + align-items: center; + justify-content: center; + white-space: nowrap; + border-radius: 0.25rem; + border-width: 1px; + border-color: rgb(228 228 231); + background-color: rgb(250 250 250); + padding: 0.25rem 0.5rem; + font-size: 0.875rem; + line-height: 1.25rem; + font-weight: 600; + color: rgb(39 39 42); + + &:hover { + border-color: rgb(212 212 216); + background-color: rgb(244 244 245); + color: rgb(24 24 27); + box-shadow: 0 1px 2px 0 rgb(0 0 0 / 0.05);; + } + &:focus { + outline-style: solid; + outline-offset: 1px; + outline-color: rgb(82 82 91 / 0.5); + } + &:active { + border-color: rgb(161 161 170); + } + &:disabled { + cursor: default; + outline: 2px solid transparent; + outline-offset: 2px; + } + &:is(.dark *) { + border-color: rgb(82 82 91); + background-color: rgb(82 82 91 / 0.1); + color: rgb(228 228 231); + } + &:is(.dark *):hover { + border-color: rgb(113 113 122); + background-color: rgb(24 24 27); + color: rgb(244 244 245); + } + &:is(.dark *):active { + border-color: var(--cd-bg-color); + } +} + +/* ---------------------------------------------------------------------- */ + +.cd-callout { + --bg-color: rgb(244 244 245); + --border-color: rgb(212 212 216); + --text-color: rgb(39 39 42); + + &.type-note, + &.type-info, + &.type-todo { + --bg-color: rgb(244 244 245); + --border-color: rgb(212 212 216); + --text-color: rgb(39 39 42); + } + &.type-tip { + --bg-color: rgb(254 249 195); + --border-color: rgb(254 240 138); + --text-color: rgb(133 77 14); + } + &.type-alert { + --bg-color: rgb(255 237 213); + --border-color: rgb(254 215 170); + --text-color: rgb(154 52 18); + } + &.type-warning { + --bg-color: rgb(255 237 213); + --border-color: rgb(254 215 170); + --text-color: rgb(154 52 18); + } + &.type-danger { + --bg-color: rgb(255 228 230); + --border-color: rgb(254 205 211); + --text-color: rgb(136 19 55); + } + &.type-error { + --bg-color: rgb(255 228 230); + --border-color: rgb(254 205 211); + --text-color: rgb(136 19 55); + } + &.type-internal { + --bg-color: rgb(231 229 228); + --border-color: rgb(214 211 209); + --text-color: rgb(28 25 23); + } + & { + position: relative; + border-top-width: 1px; + border-bottom-width: 1px; + overflow: hidden; + margin-left: -1rem; + margin-right: -1rem; + background-color: var(--bg-color); + border-color: var(--border-color); + color: var(--text-color); + } + @media (min-width: 640px) { + & { + border-left-width: 1px; + border-right-width: 1px; + border-radius: 0.25rem; + margin-left: 0; + margin-right: 0; + } + } + &:is(.dark *) { + background-color: oklch(from var(--bg-color) calc(l * 2) calc(c * 3) h / 0.8); + border-color: oklch(from var(--border-color) calc(l * 1.5) c h); + color: oklch(from var(--text-color) calc(l * 0.5) c h); + } + &:is(.dark *) ::selection { + background-color: oklch(from var(--bg-color) calc(l * 1.2) calc(c * 4) h) + } + &:is(aside) { + display: flex; + align-items: flex-start; + padding: 1.25rem 1rem 1rem; + } + @media (min-width: 640px) { + &:is(aside) { + padding-left: 1.25rem; + padding-right: 1.25rem; + } + } + & summary { + display: flex; + align-items: center; + font-weight: 700; + height: 3rem; + padding-left: 1.25rem; + padding-right: 1.25rem; + cursor: pointer; + } + & .icon { + margin: -0.1rem 1rem 0 -0.25rem; + opacity: 0.9; + font-size: 1.2rem; + line-height: 1.4; + } + @media (max-width: 639px) { + & .icon { + display: none; + } + } + & .icon.arrow { + margin-left: auto; + transition-property: transform; + transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1); + transition-duration: 150ms; + } + & details&[open] .icon.arrow { + transform: rotate(180deg); + } + & .content { + line-height: 1.4; + } + & details& .content { + padding: 0 1rem 1rem; + } + @media (min-width: 640px) { + & details& .content { + padding: 0 1.25rem 1rem; + } + } +} +/* Cannot be nested */ +.cd-callout::selection { + background-color: oklch(from var(--bg-color) calc(l * 0.9) calc(c * 3) h); +} + +/* ---------------------------------------------------------------------- */ + +.cd-example-tabs { + position: relative; + margin-top: 2rem; + margin-bottom: 3rem; + display: flex; + flex-direction: column; + align-items: center; + justify-content: center; + width: 100%; + + & .example-tabgroup { + width: 100%; + overflow: hidden; + position: relative; + border: 1px solid #999; + border-radius: 0.4rem; + } + + & .example-tablist { + z-index: 0; + display: flex; + border-bottom: 1px solid #999; + background-color: rgb(249 250 251); + overflow-x: auto; + overflow-y: hidden; + -ms-scroll-chaining: none; + overscroll-behavior: contain; + width: 100%; + text-align: center; + font-size: 0.875rem; + line-height: 1.25rem; + font-weight: 500; + color: rgb(107 114 128); + } + & .example-tablist:is(.dark *) { + border-color: rgb(75 85 99); + background-color: rgb(55 65 81); + color: rgb(156 173 175); + } + + & .example-tab { + user-select: none; + border-right-width: 1px; + border-color: #999; + background-color: rgb(255 255 255); + padding: 0.5rem 1.6rem; + color: #333; + } + & .example-tab:is(.dark *) { + border-color: rgb(75 85 99); + background-color: rgb(31 41 55); + color: rgb(255 255 255); + } + & .example-tab:not(.ui-disabled):not(.ui-selected):hover { + background-color: rgb(249 250 251); + color: rgb(55 65 81); + } + & .example-tab:not(.ui-disabled):not(.ui-selected):hover:is(.dark *) { + background-color: rgb(55 65 81); + color: rgb(255 255 255); + } + & .example-tab.ui-disabled { + color: rgb(193 204 220); + } + & .example-tab.ui-selected { + color: black; + background-color: #e7e9ed; + } + & .example-tab.ui-selected:is(.dark *) { + color: white; + background-color: #111; + } + + & .example-tabpanel { + width: 100%; + flex-grow: 0;` + z-index: 10; + overflow: auto; + position: relative; + max-height: 400px; + } + & .example-tabpanel.ui-hidden { + display: none; + } + & .example-tabpanel div.highlight { + margin: 0; + padding: 0; + border-radius: 0; + font-size: 0.9rem; + } + & .example-tabpanel div.highlight pre { + border-radius: 0; + } +} + +/* ---------------------------------------------------------------------- */ + +.cd-footer { + padding-top: 1.25rem; + padding-bottom: 1.25rem; + padding-left: var(--cd-padding-left); + padding-right: var(--cd-padding-right); + font-size: 0.875rem; + line-height: 1.25rem; + text-align: center; + border-top: 1px solid rgb(228 228 231); + + &:is(.dark *){ + border-color: rgb(82 82 91); + } + & .wrapper { + display: flex; + align-items: center; + } + & .copy { + margin-right: auto; + text-align: left; + padding: 0 16px; + } + & .built-with { + height: 100%; + color: rgb(113 113 122); + } + & .built-with:is(.dark *) { + color: inherit; + } + & .built-with a { + text-decoration: underline; + cursor: pointer; + } + & .themeswitch { + margin-left: 1.5rem; + margin-right: 0; + opacity: 0.8; + border-radius: 1rem; + background-color: var(--cd-nav-bg-color); + transition: opacity 300ms ease-in-out, background 300ms ease-in-out; + padding-left: 0.5rem; + padding-right: 0.5rem; + } + & .themeswitch:hover { + opacity: 1; + background-color: var(--cd-nav-bg-color-hover); + } + @media (max-width: 640px) { + & .built-with, + & .themeswitch { + display: none; + } + } +} + +/* ---------------------------------------------------------------------- */ + +.cd-header { + margin-bottom: 2rem; + + & div p { + margin-bottom: 0.5rem; + font-size: 0.875rem; + line-height: 1; + font-weight: 600; + } + & h1 { + display: inline-block; + font-size: 1.9rem; + line-height: 1.25rem; + color: rgb(24 24 27); + font-weight: 800; + margin: 0; + } + & h1:is(.dark *) { + color: rgb(228 228 231); + } + @media (min-width: 640px) { + & h1 { + font-size: 2.2rem; + } + } + & p.description { + margin-top: 0.25rem; + font-size: 1.125rem; + line-height: 1.75rem; + color: var(--cd-text-color-mild); + } +} + +/* ---------------------------------------------------------------------- */ + +.cd-navbar { + display: flex; + align-items: center; + border-radius: 1rem; + padding: 0 0.75rem; + font-size: 0.875rem; + font-weight: bold; + backdrop-filter: blur(4px); + background-color: var(--cd-nav-bg-color); + box-shadow: rgb(15, 15, 15) 0px 0px 0px 0px inset, + rgba(163, 163, 170, 0.3) 0px 0px 0px 1px inset, + rgba(255, 255, 255, 0.2) 0px 20px 25px -5px, + rgba(255, 255, 255, 0.2) 0px 8px 10px -6px; + + &:is(.dark *) { + box-shadow: rgb(255, 255, 255) 0px 0px 0px 0px inset, + rgba(63, 63, 70, 0.3) 0px 0px 0px 1px inset, + rgba(0, 0, 0, 0.2) 0px 20px 25px -5px, + rgba(0, 0, 0, 0.2) 0px 8px 10px -6px; + } + + & a { + white-space: nowrap; + padding: 0.75rem; + } + & a, + & button { + opacity: 0.8; + transition: opacity 300ms ease-in-out, background 300ms ease-in-out; + border-radius: 4px; + } + & a:hover, + & button:hover { + opacity: 1; + background-color: var(--cd-nav-bg-color-hover); + } + & a svg { + height: 20px; + } +} + +/* ---------------------------------------------------------------------- */ + +.cd-nav-top { + z-index: 1000; + width: 100%; + margin-top: 1rem; + + /* @media ((min-width: 1024px) and (min-height: 640px)) { + & { + position: sticky; + top: 1rem; + } + } */ + & .wrapper { + margin-left: auto; + margin-right: auto; + display: flex; + max-width: 100rem; + align-items: center; + padding-left: var(--cd-padding-left); + padding-right: var(--cd-padding-right); + } + + & .logo { + padding: 0.75rem; + margin-left: -0.75rem; + margin-right: auto; + background-color: transparent; + transition: background 300ms ease-in-out; + } + @media (min-width: 640px) { + & .logo { + border-radius: 4px; + backdrop-filter: blur(4px); + background-color: var(--cd-nav-bg-color); + } + } + + & .nav-links { + display: none; + } + @media (min-width: 768px) { + & .nav-links { + display: inline-flex; + } + } + & .nav-extra { + margin-left: 0.75rem; + } + & .nav-links > .themeswitch { + border: none; + outline: none; + margin-left: 0.25rem; + } + & .cd-toggle-sidebar { + font-size: 1rem; + margin-left: 0.75rem; + width: 4.5rem; + line-height: 1; + padding: 0.75rem 0.5rem; + } +} + +/* ---------------------------------------------------------------------- */ + +.cd-nav-global { + /* position: sticky; */ + /* top: 0; */ + z-index: 0; + width: 12rem; + border-right-width: 1px; + border-color: rgb(228 228 231); + padding-right: 1rem; + padding-bottom: 2rem; + font-size: 0.875rem; + line-height: 1.2; + flex-shrink: 0; + /* + @media (min-height: 640px) { + & { + overflow-y: auto; + height: 100vh; + top: 3rem; + min-height: calc(100vh - 3rem); + } + } */ + + @media (min-width: 1536px) { + & { + font-size: 1rem; + line-height: 1.5rem; + width: 18rem; + } + } + &:is(.dark *) { + border-color: rgb(82 82 91); + } + + & nav { + display: flex; + width: 100%; + flex-direction: column; + padding-bottom: 3.5rem; + } +} + +/* ---------------------------------------------------------------------- */ + +.cd-nav-local { + position: sticky; + top: 5rem; + z-index: 0; + width: 25rem; + height: calc(100vh - 6.5rem); + margin-right: -1rem; + overflow: hidden; + border-left-width: 1px; + border-color: rgb(228 228 231); + + &:is(.dark *) { + border-color: rgb(82 82 91); + } + & .wrapper { + position: absolute; + inset: 0; + overflow-y: auto; + overflow-x: hidden; + -ms-scroll-chaining: none; + overscroll-behavior: contain; + scroll-behavior: smooth; + padding: 1.5rem 0.25rem; + font-size: 0.9rem; + line-height: 1.2; + } +} + +/* ---------------------------------------------------------------------- */ + +.cd-nav-mobile { + position: fixed; + left: 0; + top: 0; + height: 100vh; + width: 100%; + min-width: 360px; + max-width: 640px; + -ms-scroll-chaining: none; + overscroll-behavior: contain; + margin: 0; + padding: 0 0 4rem 0; + background-color: var(--cd-bg-color-hover); + color: var(--cd-text-color); + + transition: all 0.2s allow-discrete; + /* Final state of the exit animation */ + opacity: 0; + transform: translateX(-100%); + + &:popover-open { + opacity: 1; + transform: translateX(0); + } + /* Needs to be after the previous &:popover-open rule + to take effect, as the specificity is the same */ + @starting-style { + &:popover-open { + opacity: 0; + transform: translateX(-100%); + } + } + + @media (min-width: 640px) { + & { + border-right: 1px solid var(--cd-border-color); + } + } + & header { + margin: 1rem 0; + display: flex; + align-items: center; + padding-left: var(--cd-padding-left); + padding-right: var(--cd-padding-right); + } + & .logo { + margin-right: auto; + } + & .themeswitch { + border: none; + background: none; + outline: none; + } + & .cd-toggle-sidebar { + font-size: 1rem; + margin-left: 0.75rem; + width: 4.5rem; + line-height: 1; + padding: 0.75rem 0.5rem; + } + + & .toc { + margin-bottom: 1.25rem; + display: flex; + flex-direction: column; + -ms-scroll-chaining: none; + overscroll-behavior: contain; + padding-left: var(--cd-padding-left); + padding-right: var(--cd-padding-right); + font-size: 1rem; + line-height: 1.5rem; + } +} +/* Transition for the popover's backdrop. + ::backdrop cannot be nested */ +.cd-nav-mobile::backdrop { + transition: all 0.5s allow-discrete; + /* Final state of the exit animation */ + backdrop-filter: blur(0); + background-color: rgb(0 0 0 / 0%); +} +.cd-nav-mobile:popover-open::backdrop { + backdrop-filter: blur(2px); + background-color: rgb(0 0 0 / 15%); +} +@starting-style { + .cd-nav-mobile:popover-open::backdrop { + backdrop-filter: blur(0); + background-color: rgb(0 0 0 / 0%); + } +} + +/* ---------------------------------------------------------------------- */ + +.cd-page-single > main { + margin: 0; + max-width: 100%; + padding: 0; +} + +.cd-page { + & .page-wrapper { + z-index: 10; + margin-left: auto; + margin-right: auto; + display: flex; + max-width: 100rem; + padding-top: 1rem; + padding-left: var(--cd-padding-left); + padding-right: var(--cd-padding-right); + padding-bottom: 1.5rem; + min-width: 360px; + } + & .page-wrapper > main { + width: 100%; + padding-top: 1rem; + } + @media (min-width: 640px) { + & { + padding-bottom: 1rem; + } + } +} + +/* ---------------------------------------------------------------------- */ + +.cd-prevnext { + display: flex; + align-items: stretch; + width: 100%; + margin-top: 2rem; + padding-top: 2rem; + padding-bottom: 2rem; + padding-left: var(--cd-padding-left); + padding-right: var(--cd-padding-right); + border-top: 1px solid var(--cd-border-color); + font-family: var(--cd-font-sans); + + & a.prev, + & a.next { + display: flex; + align-items: center; + padding: 0.75rem 0.25rem; + text-decoration: none; + width: 50%; + border: 1px solid var(--cd-border-color); + color: var(--cd-text-color); + border-radius: 10px; + transition: all 0.2s ease-in; + } + & a.prev { + margin-right: 1.25rem; + justify-content: flex-start; + text-align: left; + } + & a.next { + margin-left: auto; + justify-content: flex-end; + text-align: right; + } + & a.prev:hover, + & a.next:hover { + border-color: rgb(113, 113, 122); + } + &:is(.dark *) a.prev:hover, + &:is(.dark *) a.next:hover { + border-color: rgb(150, 150, 150); + } + & .section { + font-size: 0.875rem; + line-height: 1; + color: rgb(113, 113, 122); + margin-bottom: 0.1rem; + } + &:is(.dark *) .section { + color: rgb(150, 150, 150); + } + & .title { + font-size: 1rem; + line-height: 1.1; + } + & i { + opacity: 0.8; + font-style: normal; + font-size: 1.4rem; + padding: 0 0.5rem; + } +} + +/* ---------------------------------------------------------------------- */ + +.cd-theme-switch { + display: flex; + align-items: center; + justify-content: center; + -webkit-tap-highlight-color: transparent; + + & { + font-weight: 400; + height: 2.5rem; + width: 2.5rem; + flex-grow: 0; + padding: 0.2rem; + } + @media (min-width: 1024px) { + & { + width: auto; + } + } + & svg { + padding: 0.3rem; + margin: 0; + } + &:is(.dark *) svg { + padding: 0.1rem; + } + & .sun-and-moon { + pointer-events: none; + display: block; + height: 100%; + width: 100%; + } + & .sun { + transform-origin: center; + transform: scale(1, 1); + transform: translate3d(0, 0, 0); + fill: #3f3f46; + stroke: transparent; + } + &:hover .sun { + fill: #27272a; + } + &:focus-visible .sun { + fill: #27272a; + } + @media (prefers-reduced-motion: no-preference) { + & .sun { + transition-property: transform; + transition-timing-function: cubic-bezier(0.5, 1.25, 0.75, 1.25); + transition-duration: 0.5s; + } + } + & .sun:is(.dark *) { + transform: scale(1.75, 1).75; + fill: #e4e4e7; + } + &:hover .sun:is(.dark *) { + fill: #f4f4f5; + } + &:focus-visible .sun:is(.dark *) { + fill: #f4f4f5; + } + @media (prefers-reduced-motion: no-preference) { + & .sun:is(.dark *) { + transition-timing-function: cubic-bezier(0.25, 0, 0.3, 1); + transition-duration: 250ms; + } + } + & .sun-beams { + transform-origin: center; + stroke: #3f3f46; + stroke-width: 2; + } + &:hover .sun-beams { + stroke: #27272a; + } + &:focus-visible .sun-beams { + stroke: #27272a; + } + @media (prefers-reduced-motion: no-preference) { + & .sun-beams { + transition-property: transform, opacity; + transition-timing-function: cubic-bezier(0.5, 1.5, 0.75, 1.25); + transition-duration: 400ms; + } + } + & .sun-beams:is(.dark *) { + transform: translate3d(0, 0, 0); + transform: rotate(-25deg); + stroke: #e4e4e7; + opacity: 0; + } + &:hover .sun-beams:is(.dark *) { + stroke: #f4f4f5; + } + &:focus-visible .sun-beams:is(.dark *) { + stroke: #f4f4f5; + } + @media (prefers-reduced-motion: no-preference) { + & .sun-beams:is(.dark *) { + transition-duration: 150ms; + } + } + & .moon { + transform-origin: center; + fill: #52525b; + } + &:hover .moon { + fill: #71717a; + } + & .moon circle { + transform: translate3d(0, 0, 0); + } + @media (prefers-reduced-motion: no-preference) { + & .moon circle { + transition-property: transform; + transition-timing-function: cubic-bezier(0, 0, 0, 1); + transition-duration: 0.3s; + } + } + & .moon circle:is(.dark *) { + transform: translateX(-7px); + } + @media (prefers-reduced-motion: no-preference) { + & .moon circle:is(.dark *) { + transition-delay: 0.3s; + } + } + & .light-text, + & .dark-text { + padding: 0.5rem; + padding-left: 0; + display: none; + white-space: nowrap; + font-weight: bold; + text-align: left; + } + @media (min-width: 1024px) { + & .light-text { + display: block; + } + & .light-text:is(.dark *) { + display: none; + } + & .dark-text:is(.dark *) { + display: block; + } + } +} + +/* ---------------------------------------------------------------------- */ + +.cd-toc { + & details, + & section { + margin-top: 1.5rem; + } + + & summary { + margin-bottom: 0.5rem; + font-weight: 600; + color: rgb(39 39 42); + } + & summary:is(.dark *) { + color: rgb(244 244 245); + } + + & h2 { + margin-bottom: 0.5rem; + font-weight: 600; + color: rgb(39 39 42); + } + & h2:is(.dark *) { + color: rgb(244 244 245); + } + + & .page { + border-left-width: 2px; + border-color: rgb(244 244 245); + padding-left: 0.5rem; + } + & .page:hover { + border-color: rgb(212 212 216); + } + + & .page:is(.dark *) { + border-color: rgb(63 63 70 / 0.5); + } + & .page:is(.dark *):hover { + border-color: rgb(161 161 170); + } + + & a { + position: relative; + display: flex; + align-items: center; + border-radius: 0.25rem; + border-width: 1px; + border-color: transparent; + line-height: 1.2; + margin: 0; + padding-top: 0.25rem; + padding-bottom: 0.25rem; + padding-left: 0.5rem; + padding-right: 0.5rem; + color: rgb(63 63 70); + } + & a:hover { + color: rgb(0 0 0); + } + & a:is(.dark *) { + color: rgb(161 161 170); + } + & a:is(.dark *):hover { + color: rgb(244 244 245); + } + & .active a { + border-color: rgb(228 228 231); + background-color: rgb(244 244 245); + font-weight: bold; + color: rgb(39 39 42); + } + & .active:is(.dark *) a { + color: black; + } +} + +/* ---------------------------------------------------------------------- */ + +.cd-toc-page { + margin-top: -0.25rem; + + & li { + position: relative; + display: flex; + align-items: center; + } + + & li::after { + content: ""; + display: block; + position: absolute; + inset: 0; + background-color: var(--cd-brand-color); + border-radius: 0.25rem; + opacity: 0; + transition: opacity 0.2s ease-in-out; + z-index: -1; + } + + & li:has(a.active)::after { + opacity: 0.15; + } + + & a { + display: flex; + align-items: center; + color: rgb(82 82 91); + padding: 0.3rem 0 0.3rem 0.5rem; + } + & a:is(.dark *) { + color: rgb(161 161 170); + } + & a:hover:not(.active) { + & span { + text-decoration: underline; + } + } + + & li.indent-0 a { + padding-left: 0rem; + font-size: smaller; + text-transform: uppercase; + font-weight: bold; + border-bottom-width: 1px; + } + & li.indent-1 a { + padding-left: 0rem; + font-weight: bold; + } + & li.indent-2 a { padding-left: 1rem; } + & li.indent-3 a { padding-left: 1.5rem; } + & li.indent-4 a { padding-left: 2rem; } + & li.indent-5 a { padding-left: 2.5rem; } + & li.indent-6 a { padding-left: 3rem; } + + & li a::before { + content: ""; + display: inline-flex; + align-items: center; + justify-content: right; + line-height: 1; + height: 8px; + width: 8px; + margin: 0 0.5rem 0 0.5rem; + flex-grow: 0; + flex-shrink: 0; + } + li.indent-2 a::before { content: "○" } + li.indent-3 a::before { content: "•" } + li.indent-4 a::before { content: "·" } + li.indent-5 a::before { content: "⁃" } + li.indent-6 a::before { content: "·" } + + & li a.active::before { + content: ""; + border-radius: 3px; + background-color: var(--cd-brand-color); + } +} + +/* ---------------------------------------------------------------------- */ + +.cd-nav-global, +.cd-nav-local, +.cd-nav-mobile { + display: none; +} +.cd-nav-mobile:popover-open, +.cd-nav-top .cd-toggle-sidebar { + display: block; +} + +@media (min-width: 924px) { + .cd-nav-mobile, + .cd-nav-top .cd-toggle-sidebar { + display: none; + } +} + +@media (min-width: 924px) { + .cd-nav-global { + display: block; + } +} + +@media (min-width: 1024px) { + .cd-page .page-wrapper > main { + margin-left: 2.5rem; + margin-right: 2.5rem; + } + .cd-nav-local { + display: block; + } +} diff --git a/docs/theme/Autodoc.jinja b/docs/theme/Autodoc.jinja new file mode 100644 index 0000000..e1a967c --- /dev/null +++ b/docs/theme/Autodoc.jinja @@ -0,0 +1,127 @@ +{#def + obj: dict | None = None, + name: str = "", + level: int = 2, + members: bool = True, +#} + +{% set obj = obj or autodoc(name) %} + +<h{{ level }}> + <code class="doc-symbol doc-symbol-{{ obj.symbol }}">{{ obj.symbol }}</code> + <span class="doc-oname doc-oname-{{ obj.symbol }}">{{ name or obj.name }}</span> + {% if obj.label -%} + <small class="doc-olabel doc-olabel-{{ obj.label }}"> + <code>{{ obj.label }}</code> + </small> + {%- endif %} +</h{{ level }}> + +{%- if obj.short_description -%} +<div class="doc-short-description"> + {{ obj.short_description | markdown | utils.widont }} +</div> +{% endif -%} + +{%- if obj.signature -%} +<div class="doc-signature"> +{% filter markdown -%} +```python +{{ obj.signature }} +``` +{%- endfilter %} +</div> +{%- endif %} + +{% if obj.bases -%} +<div class="doc-bases"> + <p>Bases: + {%- for base in obj.bases %} <code>{{ base }}</code>{% if not loop.last %}, {% endif %} + {%- endfor %} + </p> +</div> +{%- endif %} + +{% if obj.params -%} +<table class="doc-arguments"> + <thead><tr><th>Argument</th><th>Description</th></tr> + </thead> + <tbody> +{%- for param in obj.params %} + <tr> + <td><code>{{ param.name }}</code></td> + <td>{{ param.description | markdown | utils.widont }}</td> + </tr> +{%- endfor %} + </tbody> +</table> +{%- endif %} + +{%- if obj.description -%} +<div class="doc-long-description"> + {{ obj.description | markdown | utils.widont }} +</div> +{% endif -%} + +{% if obj.examples -%} +<div class="doc-examples"> +<p><strong>Example:</strong></p> + +{% for ex in obj.examples -%} +<div> +{% if ex.description %}{{ ex.description | markdown | utils.widont }}{% endif %} +{% if ex.snippet %}{{ ex.snippet }}{% endif %} +<div> +{% endfor -%} +</div> +{%- endif %} + +{% if obj.returns -%} +<li class="doc-returns"> + <p><strong>Returns:</strong></p> + + {% if ex.returns -%} + <p>{{ obj.returns }}</p> + {%- endif %} + {% if ex.many_returns -%} + <ul> + {% for return in ex.many_returns %} + <li>{{ return }}</li> + {%- endfor %} + </ul> + {%- endif %} +</div> +{%- endif %} + +{% if obj.raises -%} + <div class="doc-raises"></div> + <p><strong>Raises:</strong></p> + + <ul> + {% for raises in obj.raises -%} + <li>{{ raises.description | markdown | utils.widont }}<ul> + {% endfor -%} + </ul> + </li> +{%- endif %} + +{% if members -%} + {% if obj.attrs or obj.properties-%} + <div class="doc-attrs"> + {% for attr in obj.attrs -%} + <Autodoc obj={{ attr }} level={{ level + 1 }} /> + {% endfor %} + {% for attr in obj.properties %} + <Autodoc obj={{ attr }} level={{ level + 1 }} /> + {%- endfor %} + </div> + {%- endif %} + + {% if obj.methods -%} + <div class="doc-methods"> + {% for method in obj.methods %} + <Autodoc obj={{ method }} level={{ level + 1 }} /> + {%- endfor %} + </div> + {%- endif %} +{%- endif %}
\ No newline at end of file diff --git a/docs/theme/Callout.jinja b/docs/theme/Callout.jinja new file mode 100644 index 0000000..4279b3a --- /dev/null +++ b/docs/theme/Callout.jinja @@ -0,0 +1,45 @@ +{#def title="", type="info", icon="", open=True #} + +{% set icons = { + "note": "sticky_note", + "info": "info", + "tip": "check_circle", + "alert": "release_alert", + "warning": "warning", + "danger": "release_alert", + "error": "release_alert", + "internal": "rocket_launch", + "todo": "checklist", +} %} + +{% if icon != False %} + {% set icon = icon or icons.get(type) %} +{% endif %} + +{% do attrs.set(class="type-" + type or "none") %} + +{% if title -%} + +<details {{ attrs.render(open=open, class="cd-callout", data_component="Callout") }}> + <summary> + {% if icon -%} + <i class="icon">{{ icon }}</i> + {% endif -%} + {{ title }} + <icon class="icon arrow">keyboard_arrow_down</icon> + </summary> + <div class="content">{{content}}</div> +</details> + +{%- else -%} + +<aside {{ attrs.render(class="cd-callout", data_component="Callout") }}> + {% if icon -%} + <div class="icon-wrapper"> + <i class="icon">{{ icon }}</i> + </div> + {%- endif %} + <div class="content">{{content}}</div> +</aside> + +{%- endif %} diff --git a/docs/theme/ExampleTabs.jinja b/docs/theme/ExampleTabs.jinja new file mode 100644 index 0000000..0853ec5 --- /dev/null +++ b/docs/theme/ExampleTabs.jinja @@ -0,0 +1,27 @@ +{#def prefix, panels={} #} + +<div {{ attrs.render( + class="cd-example-tabs not-prose", + data_component="ExampleTabs", +) }}> + <TabGroup class="example-tabgroup"> + <TabList class="example-tablist" data-md-skip> + {%- for text in panels.keys() %} + <Tab + class="example-tab" + target={{ "ex-%s-%s" % (prefix, loop.index) }} + selected={{ loop.index == 1 }} + >{{ text }}</Tab> + {%- endfor %} + </TabList> + {%- for name in panels.values() %} + <TabPanel + class="example-tabpanel" + id={{ "ex-%s-%s" % (prefix, loop.index) }} + hidden={{ loop.index != 1 }} + > + {{ catalog.irender(name) }} + </TabPanel> + {%- endfor %} + </TabGroup> +</div> diff --git a/docs/theme/Footer.jinja b/docs/theme/Footer.jinja new file mode 100644 index 0000000..a9e9c5a --- /dev/null +++ b/docs/theme/Footer.jinja @@ -0,0 +1,10 @@ +<footer {{ attrs.render(class="cd-footer", data_component="Footer") }}> + <div class="wrapper"> + <Copyright /> + <div class="built-with"> + This site was + <a title="Coming soon!">built using Claydocs</a> + </div> + <ThemeSwitch class="themeswitch" /> + </div> +</footer> diff --git a/docs/theme/Header.jinja b/docs/theme/Header.jinja new file mode 100644 index 0000000..1b719cf --- /dev/null +++ b/docs/theme/Header.jinja @@ -0,0 +1,17 @@ +{#def title="", section="" #} + +{% set section = section or page.section if section != false else None %} +{% set title = title or page.title %} + +<header {{ attrs.render( + class="cd-header", + data_component="Header", +) }}> + <div> + {% if section -%} + <div>{{ section }}</div> + {%- endif %} + <h1>{{ title | utils.widont }}</h1> + </div> + <p class="description">{{ content | utils.widont }}</p> +</header> diff --git a/docs/theme/Layout.jinja b/docs/theme/Layout.jinja new file mode 100644 index 0000000..e76046f --- /dev/null +++ b/docs/theme/Layout.jinja @@ -0,0 +1,25 @@ +{#def title="", description="" #} + +<!DOCTYPE html> +<html lang="{{ page.lang }}" class="light"> +<head> +<meta charset="utf-8"> +<MetaTags page={{ page }} /> +<link rel="icon" type="image/x-icon" href="/static/favicon.ico"> +<link rel="apple-touch-icon" sizes="120x120" href="/static/img/apple-touch-icon.png"> +<link rel="stylesheet" href="/static/theme.css?v={{ utils.timestamp }}"> +<link rel="stylesheet" href="/static/prose.css?v={{ utils.timestamp }}"> +<link rel="stylesheet" href="/static/docs.css?v={{ utils.timestamp }}"> +{{ catalog.render_assets() }} +{% if page.prev_page and page.prev_page.url -%} + <link href="{{ page.prev_page.url }}" rel="prev"> +{% endif -%} +{% if page.next_page and page.next_page.url -%} + <link href="{{ page.next_page.url }}" rel="next"> +{% endif -%} +<meta property="generator" content="claydocs" /> +</head> +<body {{ attrs.render() }}> +{{ content }} +</body> +</html> diff --git a/docs/theme/MetaTags.jinja b/docs/theme/MetaTags.jinja new file mode 100644 index 0000000..2639afb --- /dev/null +++ b/docs/theme/MetaTags.jinja @@ -0,0 +1,22 @@ +{#def page #} + +{% set DEFAULT_TITLE = "JinjaX Documentation" %} +{% set title = (page.title + " | " + DEFAULT_TITLE) if page.title else DEFAULT_TITLE %} +{% set description = page.description %} + +<title>{{ title }}</title> +<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover"> +<meta property="og:type" content="website"> +<meta property="og:url" content="{{ nav.domain }}{{ page.url }}"> +<meta property="og:title" content="{{ title }}"> +<meta property="twitter:title" content="{{ title }}"> +{% if description -%} +<meta property="og:description" content="{{ description }}"> +<meta property="twitter:description" content="{{ description }}"> +{%- endif %} +<meta property="og:image" content="{{ nav.domain }}{{ page.url }}/og-card.png"> +<meta property="og:image:type" content="image/png"> +<meta property="og:image:width" content="1200"> +<meta property="og:image:height" content="630"> +<meta property="twitter:card" content="summary_large_image"> +<meta property="twitter:image" content="{{ nav.domain }}{{ page.url }}/og-card.png"> diff --git a/docs/theme/NavBar.jinja b/docs/theme/NavBar.jinja new file mode 100644 index 0000000..50f8ca2 --- /dev/null +++ b/docs/theme/NavBar.jinja @@ -0,0 +1,3 @@ +<nav {{ attrs.render(class="cd-navbar", data_component="NavBar") }}> +{{ content }} +</nav>
\ No newline at end of file diff --git a/docs/theme/NavGlobal.jinja b/docs/theme/NavGlobal.jinja new file mode 100644 index 0000000..1171db0 --- /dev/null +++ b/docs/theme/NavGlobal.jinja @@ -0,0 +1,3 @@ +<div {{ attrs.render(class="cd-nav-global scrollbar-thin", data_component="NavGlobal") }}> + <Toc toc={{ nav.toc }} page={{ page}} /> +</div> diff --git a/docs/theme/NavLocal.jinja b/docs/theme/NavLocal.jinja new file mode 100644 index 0000000..2af7606 --- /dev/null +++ b/docs/theme/NavLocal.jinja @@ -0,0 +1,5 @@ +<div {{ attrs.render(class="cd-nav-local", data_component="NavLocal") }}> + <div class="wrapper scrollbar-thin"> + <TocPage :page_toc="page.toc" /> + </div> +</div> diff --git a/docs/theme/NavMobile.jinja b/docs/theme/NavMobile.jinja new file mode 100644 index 0000000..4126fb0 --- /dev/null +++ b/docs/theme/NavMobile.jinja @@ -0,0 +1,18 @@ +{% do attrs.set(id="navMobile", class="cd-nav-mobile", data_component="NavMobile") %} + +<Popover _attrs={{ attrs }}> + <header> + <Logo base_url={{ page.base_url }} class="logo" /> + <nav class="cd-navbar nav-links"> + <ThemeSwitch class="themeswitch" text={{ false }} /> + </nav> + <PopButton + target="navMobile" + action="close" + title="Close menu" + class="cd-toggle-sidebar cd-text-button" + >Close</PopButton> + </header> + + <Toc class="toc" toc={{ nav.toc }} page={{ page }} /> +</Popover> diff --git a/docs/theme/NavTop.jinja b/docs/theme/NavTop.jinja new file mode 100644 index 0000000..8518391 --- /dev/null +++ b/docs/theme/NavTop.jinja @@ -0,0 +1,17 @@ +<section class="cd-nav-top", data_component="NavTop"> + <div class="wrapper"> + <Logo class="logo" base_url={{ page.base_url }} /> + <nav class="cd-navbar nav-links"> + <NavLinks /> + <ThemeSwitch class="themeswitch" text={{ false }} /> + </nav> + <nav class="nav-extra"> + <NavExtra /> + </nav> + <PopButton + target="navMobile" + title="Show menu" + class="cd-toggle-sidebar cd-text-button" + >Menu</PopButton> + </div> +</section> diff --git a/docs/theme/Page.jinja b/docs/theme/Page.jinja new file mode 100644 index 0000000..8fec014 --- /dev/null +++ b/docs/theme/Page.jinja @@ -0,0 +1,19 @@ +<Layout + title={{ page.title }} + description={{ page.description }} + class={{ meta.get('class', 'cd-page') }} +> + <NavTop></NavTop> + <div class="page-wrapper"> + <NavGlobal></NavGlobal> + <main id="main" class="page prose">{{ content }}</main> + <NavLocal></NavLocal> + </div> + <PrevNext + curr={{ page }} + prev={{ page.prev_page }} + next={{ page.next_page }} + /> + <NavMobile></NavMobile> + <Footer></Footer> +</Layout> diff --git a/docs/theme/PageSingle.jinja b/docs/theme/PageSingle.jinja new file mode 100644 index 0000000..d89fd49 --- /dev/null +++ b/docs/theme/PageSingle.jinja @@ -0,0 +1,10 @@ +<Layout + title={{ page.title }} + description={{ page.description }} + class={{ meta.get('class', 'cd-page-single') }} +> + <NavTop /> + <main>{{ content }}</main> + <NavMobile /> + <Footer /> +</Layout> diff --git a/docs/theme/PrevNext.jinja b/docs/theme/PrevNext.jinja new file mode 100644 index 0000000..9c6a572 --- /dev/null +++ b/docs/theme/PrevNext.jinja @@ -0,0 +1,26 @@ +{#def curr, prev, next #} + +<nav {{ attrs.render(class="cd-prevnext", data_component="PrevNext") }}> + {% if prev.url -%} + <a href="{{ prev.url }}" class="prev"> + <i>←</i> + <div> + <div class="section"> + {{ prev.section or "Previous" if prev.section != curr.section else "Previous" }} + </div> + <div class="title">{{ prev.title }}</div> + </div> + </a> + {%- endif %} + {% if next.url -%} + <a href="{{ next.url }}" class="next"> + <div> + <div class="section"> + {{ next.section or "Next" if next.section != curr.section else "Next" }} + </div> + <div class="title">{{ next.title }}</div> + </div> + <i>→</i> + </a> + {%- endif %} +</nav> diff --git a/docs/theme/SocialCard.jinja b/docs/theme/SocialCard.jinja new file mode 100644 index 0000000..2fe00be --- /dev/null +++ b/docs/theme/SocialCard.jinja @@ -0,0 +1,61 @@ +{#def page #} +<Layout + title={{ page.title }} + description={{page.description }} +> + <style> + body { + background-color: black; + } + .sc1 { + width: 1200px; + height: 630px; + margin: 0; + font-family: SF Pro Display, system-ui, sans-serif; + color: white; + background-image: linear-gradient(to bottom, #404faa, #0068b2); + } + .sc1__wrapper { + position: absolute; + inset: 60px 90px 90px 60px; + } + .sc1__wrapper > * { + position: absolute; + left: 0; + max-width: 1060px; + } + .sc1__logo { + top: 0; + height: 50px; + } + .sc1__section { + top: 150px; + line-height: 1; + font-weight: bold; + text-transform: uppercase; + font-size: 22px; + width: 600px; + } + .sc1__title { + top: 180px; + line-height: 1; + font-weight: bold; + font-size: 68px; + } + .sc1__description { + bottom: 0; + line-height: 1.4; + font-weight: normal; + font-size: 22px; + } + </style> + + <article class="sc1"> + <div class="sc1__wrapper"> + <img class="sc1__logo" src="/static/img/jinjax-logo-w.png" /> + <h2 class="sc1__section">{{ page.section }}</h2> + <h1 class="sc1__title">{{ page.title | utils.widont }}</h1> + <div class="sc1__description">{{ page.description | utils.widont }}</div> + </div> + </article> +</Layout> diff --git a/docs/theme/Source.jinja b/docs/theme/Source.jinja new file mode 100644 index 0000000..c742f56 --- /dev/null +++ b/docs/theme/Source.jinja @@ -0,0 +1,24 @@ +{# def url: str, label: str = "" #} +{% do attrs.set(href=url, target="_blank") %} +{% set icon = url.replace("http://", "").replace("https://", "").split(".")[0] %} + +<a {{ attrs.render(class="cd-source", data_component="Source") }}> + <div class="cd-source__icon"> + {% if icon == "github" -%} + <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 496 512"><!--! Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc. --><path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"/></svg> + {% elif icon == "gitlab" -%} + <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc. --><path d="M503.5 204.6L502.8 202.8L433.1 21.02C431.7 17.45 429.2 14.43 425.9 12.38C423.5 10.83 420.8 9.865 417.9 9.57C415 9.275 412.2 9.653 409.5 10.68C406.8 11.7 404.4 13.34 402.4 15.46C400.5 17.58 399.1 20.13 398.3 22.9L351.3 166.9H160.8L113.7 22.9C112.9 20.13 111.5 17.59 109.6 15.47C107.6 13.35 105.2 11.72 102.5 10.7C99.86 9.675 96.98 9.295 94.12 9.587C91.26 9.878 88.51 10.83 86.08 12.38C82.84 14.43 80.33 17.45 78.92 21.02L9.267 202.8L8.543 204.6C-1.484 230.8-2.72 259.6 5.023 286.6C12.77 313.5 29.07 337.3 51.47 354.2L51.74 354.4L52.33 354.8L158.3 434.3L210.9 474L242.9 498.2C246.6 500.1 251.2 502.5 255.9 502.5C260.6 502.5 265.2 500.1 268.9 498.2L300.9 474L353.5 434.3L460.2 354.4L460.5 354.1C482.9 337.2 499.2 313.5 506.1 286.6C514.7 259.6 513.5 230.8 503.5 204.6z"/></svg> + {%- else -%} + <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc. --><path d="M439.55 236.05L244 40.45a28.87 28.87 0 0 0-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 0 1-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 0 0 0 40.81l195.61 195.6a28.86 28.86 0 0 0 40.8 0l194.69-194.69a28.86 28.86 0 0 0 0-40.81z"/></svg> + {%- endif %} + </div> + <div class="cd-source__repo"> + <span class="cd-source__label">{{ label or url.split("/", 3)[-1] }}</span> + <ul class="cd-source__facts"> + <li data-fact="version" hidden></li> + <li data-fact="stars" hidden></li> + <li data-fact="forks" hidden></li> + <li data-fact="numrepos" hidden></li> + </ul> + </div> +</a>
\ No newline at end of file diff --git a/docs/theme/Source.js b/docs/theme/Source.js new file mode 100644 index 0000000..e627460 --- /dev/null +++ b/docs/theme/Source.js @@ -0,0 +1,123 @@ +const ATTR_FACT = "data-fact"; +const CLASS_FACTS = "cd-source__facts"; +const CLASS_FACTS_VISIBLE = `${CLASS_FACTS}--visible`; + +document.addEventListener("DOMContentLoaded", function () { + document.querySelectorAll('[data-component="Source"]').forEach(showFacts); +}); + +function showFacts(node) { + function renderFacts(facts) { + Array.from(node.querySelectorAll(`[${ATTR_FACT}]`)) + .forEach(function(node) { + const name = node.getAttribute(ATTR_FACT); + if (facts[name]) { + node.removeAttribute("hidden"); + node.innerText = facts[name]; + } + }); + + node.querySelector(`.${CLASS_FACTS}`).classList.add(CLASS_FACTS_VISIBLE); + } + + getSourceFacts(node.href, renderFacts); +} + +function getSourceFacts(url, callback) { + const key = `Source:${url}`; + let facts = sessionStorage.getItem(key); + if (facts) { + callback(JSON.parse(facts)); + return; + } + + fetchSourceFacts(url) + .then((facts) => { + if (facts && Object.keys(facts).length) { + sessionStorage.setItem(key, JSON.stringify(facts)); + callback(facts); + } + }); +} + +function fetchJSON(url) { + return fetch(url) + .then(response => response.json()) + .catch((error) => { + console.log(error); + }); +} + +function fetchSourceFacts(url) { + /* Try to match GitHub repository */ + let match = url.match(/^.+github\.com\/([^/]+)\/?([^/]+)?/i); + if (match) { + const [, user, repo] = match; + return fetchSourceFactsFromGitHub(user, repo); + } + + /* Try to match GitLab repository */ + match = url.match(/^.+?([^/]*gitlab[^/]+)\/(.+?)\/?$/i); + if (match) { + const [, base, slug] = match; + return fetchSourceFactsFromGitLab(base, slug); + } + + /* Fallback */ + return null; +} + +function fetchSourceFactsFromGitLab(base, project) { + const url = `https://${base}/api/v4/projects/${encodeURIComponent(project)}` + + fetchJSON(url) + .then(function({ star_count, forks_count }) { + return { + stars: star_count, + forks: forks_count, + }; + }); +} + +function fetchSourceFactsFromGitHub (user, repo) { + if (typeof repo === "undefined") { + return fetchSourceFactsFromGitHubOrg(user); + } else { + return fetchSourceFactsFromGitHubRepo(user, repo); + } +} + +function fetchSourceFactsFromGitHubOrg(user) { + const url = `https://api.github.com/users/${user}` + + fetchJSON(url) + .then(function(data) { + return { + numrepos: data.public_repos, + }; + }); +} + +function fetchSourceFactsFromGitHubRepo(user, repo) { + const url = `https://api.github.com/repos/${user}/${repo}` + + const release = fetchJSON(`${url}/releases/latest`) + .then((data) => { + return { + version: data.tag_name, + }; + }); + + const info = fetchJSON(url) + .then((data) => { + return { + stars: data.stargazers_count, + forks: data.forks_count, + }; + }); + + return Promise.all([release, info]) + .then(([release, info]) => { + return { ...release, ...info }; + }); +} diff --git a/docs/theme/Test.jinja b/docs/theme/Test.jinja new file mode 100644 index 0000000..00176ce --- /dev/null +++ b/docs/theme/Test.jinja @@ -0,0 +1,6 @@ +<!DOCTYPE html><html> +<head><MetaTags page={{ page }} /></head><body class="prose"> + +{{ content }} + +</body></html>
\ No newline at end of file diff --git a/docs/theme/ThemeSwitch.jinja b/docs/theme/ThemeSwitch.jinja new file mode 100644 index 0000000..3543b73 --- /dev/null +++ b/docs/theme/ThemeSwitch.jinja @@ -0,0 +1,36 @@ +{#def text=true #} + +<button {{ attrs.render( + class="cd-theme-switch", + data_component="ThemeSwitch", + title="Toggle light & dark mode", + aria_label="auto", + aria_live="polite", +) }}> + <svg + class="sun-and-moon" + aria-hidden="true" + stroke-linecap="round" + viewBox="0 0 24 24" + > + <circle class="sun" cx="12" cy="12" r="6" mask="url(#moon-mask)"></circle> + <g class="sun-beams"> + <line x1="12" y1="1" x2="12" y2="3" /> + <line x1="12" y1="21" x2="12" y2="23" /> + <line x1="4.22" y1="4.22" x2="5.64" y2="5.64" /> + <line x1="18.36" y1="18.36" x2="19.78" y2="19.78" /> + <line x1="1" y1="12" x2="3" y2="12" /> + <line x1="21" y1="12" x2="23" y2="12" /> + <line x1="4.22" y1="19.78" x2="5.64" y2="18.36" /> + <line x1="18.36" y1="5.64" x2="19.78" y2="4.22" /> + </g> + <mask class="moon" id="moon-mask"> + <rect x="0" y="0" width="100%" height="100%" fill="white" /> + <circle cx="24" cy="10" r="6"></circle> + </mask> + </svg> + {% if text -%} + <span class="light-text">Light</span> + <span class="dark-text">Dark</span> + {%- endif %} +</button> diff --git a/docs/theme/ThemeSwitch.js b/docs/theme/ThemeSwitch.js new file mode 100644 index 0000000..c8b2847 --- /dev/null +++ b/docs/theme/ThemeSwitch.js @@ -0,0 +1,41 @@ +import { on } from "./jxui.js"; + +const SEL_TARGET = ".cd-theme-switch"; +const STORAGE_KEY = "theme"; + +const DARK = "dark"; +const LIGHT = "light"; +const theme = {value: getColorPreference()}; + +reflectPreference(); +on("click", SEL_TARGET, onClick); +// sync with system changes +window + .matchMedia("(prefers-color-scheme: dark)") + .addEventListener("change", ({matches:isDark}) => { + theme.value = isDark ? DARK : LIGHT + setPreference() + }); + +function onClick (event, target) { + if (target.matches("[disabled]")) return; + theme.value = theme.value === LIGHT ? DARK : LIGHT; + setPreference(); +} +function setPreference () { + localStorage.setItem(STORAGE_KEY, theme.value); + reflectPreference(); +} +function reflectPreference () { + const value = getColorPreference (); + if (value === DARK) { + document.documentElement.classList.add(DARK); + document.documentElement.classList.remove(LIGHT); + } else { + document.documentElement.classList.add(LIGHT); + document.documentElement.classList.remove(DARK); + } +} +function getColorPreference () { + return localStorage.getItem(STORAGE_KEY); +}
\ No newline at end of file diff --git a/docs/theme/Toc.jinja b/docs/theme/Toc.jinja new file mode 100644 index 0000000..2670b62 --- /dev/null +++ b/docs/theme/Toc.jinja @@ -0,0 +1,45 @@ +{# def toc, page #} + +{% macro render_page(url, title) %} +{% if url != "/" -%} +<div class="page {{ 'active' if page.url == url else '' }}"> + <a href="{{ url }}#">{{ title }}</a> +</div> +{%- endif %} +{% endmacro %} + + +{% macro render_collapsable(title, children) %} +<details open> + {% if title %}<summary>{{ title }}</summary>{% endif %} + {{ render_children(children) }} +</details> +{% endmacro %} + + +{% macro render_section(title, children) %} +<section open> + {% if title %}<h2>{{ title }}</h2>{% endif %} + {{ render_children(children) }} +</section> +{% endmacro %} + + +{% macro render_children(children, collapsable=True) %} + {%- for url, title, sub_children in children %} + {% if sub_children -%} + {% if collapsable -%} + {{ render_collapsable(title, sub_children) }} + {%- else -%} + {{ render_section(title, sub_children) }} + {%- endif %} + {%- else -%} + {{ render_page(url, title) }} + {%- endif %} + {%- endfor %} +{% endmacro %} + + +<div {{ attrs.render(class="cd-toc", data_component="Toc") }}> + {{ render_children(toc, collapsable=False) }} +</div>
\ No newline at end of file diff --git a/docs/theme/TocPage.jinja b/docs/theme/TocPage.jinja new file mode 100644 index 0000000..754b624 --- /dev/null +++ b/docs/theme/TocPage.jinja @@ -0,0 +1,21 @@ +{#def page_toc, max_depth=3 #} + +{% macro render_sub_items(pages) %} +{%- for section in pages %} + <li class="indent-{{ section.level }}"> + <a href="#{{ section.id }}"><span>{{ section.name }}</span></a> + </li> + {% if section.level <= max_depth -%} + {{ render_sub_items(section.children) }} + {%- endif %} +{%- endfor %} +{% endmacro %} + +<ul {{ attrs.render(class="cd-toc-page", data_component="TocPage") }}> +{%- for section in page_toc %} + <li class="indent-{{ section.level }}"> + <a href="#{{ section.id }}"><span>{{ section.name }}</span></a> + </li> + {{ render_sub_items(section.children) }} +{%- endfor %} +</ul> diff --git a/docs/theme/TocPage.js b/docs/theme/TocPage.js new file mode 100644 index 0000000..77bad1e --- /dev/null +++ b/docs/theme/TocPage.js @@ -0,0 +1,97 @@ +import { on } from "./jxui.js"; + +const ACTIVE = "active"; +const SEL_BACKTOTOP = ".cd-back-to-top" +const SEL_PAGETOC = ".cd-toc-page" +const SEL_TARGET = `${SEL_PAGETOC} a`; +const SEL_ACTIVE = `${SEL_TARGET}.${ACTIVE}`; +const SEL_PAGE = "#main.page"; +const SEL_SECTIONS = `${SEL_PAGE} section[id]`; +const DESKTOP_THRESHOLD = 1024; + +on("click", SEL_TARGET, handleClick); +on("click", SEL_BACKTOTOP, backToTop); + +function handleClick(event, target) { + removeHighlight(); + setTimeout(function () { updateHighlight(target) }, 10); +} + +function updateHighlight (elem) { + if (window.innerWidth > DESKTOP_THRESHOLD && !elem?.classList.contains(ACTIVE)) { + removeHighlight(); + if (!elem) return; + elem.classList.add(ACTIVE); + } +} + +function removeHighlight () { + document.querySelectorAll(SEL_ACTIVE).forEach(function (node) { + node.classList.remove(ACTIVE); + }); +} + +function resetNavPosition () { + var pagetoc = document.querySelector(SEL_TOC); + pagetoc?.scroll({ top: 0 }); +} + +export function backToTop () { + window.scrollTo({ top: 0, behavior: "smooth" }); + resetNavPosition(); +} + +export function scrollSpy() { + const sections = Array.from(document.querySelectorAll(SEL_SECTIONS)); + + function matchingNavLink(elem) { + if (!elem) return; + var index = sections.indexOf(elem); + + var match; + while (index >= 0 && !match) { + var sectionId = sections[index].getAttribute("id"); + if (sectionId) { + match = document.querySelector(`${SEL_PAGETOC} [href="#${sectionId}"]`); + } + index--; + } + return match; + } + + function belowBottomHalf(i) { + return i.boundingClientRect.bottom > (i.rootBounds.bottom + i.rootBounds.top) / 2; + } + + function prevElem(elem) { + var index = sections.indexOf(elem); + if (index <= 0) { + return null; + } + return sections[index - 1]; + } + + const PAGE_LOAD_BUFFER = 1000; + + function navHighlight(entries) { + entries.forEach(function (entry) { + if (entry.isIntersecting) { + updateHighlight(matchingNavLink(entry.target)); + } else if (entry.time >= PAGE_LOAD_BUFFER && belowBottomHalf(entry)) { + updateHighlight(matchingNavLink(prevElem(entry.target))); + } + }); + } + + const observer = new IntersectionObserver(navHighlight, { + threshold: 0, + rootMargin: "0% 0px -95% 0px" + }); + + sections.forEach(function (elem) { + observer.observe(elem); + }) + observer.observe(document.querySelector(SEL_PAGE)); +} + +document.addEventListener("DOMContentLoaded", scrollSpy); diff --git a/jinjax-logo.png b/jinjax-logo.png Binary files differnew file mode 100644 index 0000000..941df9f --- /dev/null +++ b/jinjax-logo.png diff --git a/poetry.lock b/poetry.lock index 6bd91d8..5bcb8e2 100644 --- a/poetry.lock +++ b/poetry.lock @@ -1,4 +1,4 @@ -# This file is automatically @generated by Poetry 1.7.1 and should not be changed by hand. +# This file is automatically @generated by Poetry 1.8.3 and should not be changed by hand. [[package]] name = "cachetools" @@ -355,13 +355,13 @@ testing = ["covdefaults (>=2.3)", "pytest (>=8.2.2)", "pytest-cov (>=5)", "pytes [[package]] name = "pyright" -version = "1.1.369" +version = "1.1.377" description = "Command line wrapper for pyright" optional = false python-versions = ">=3.7" files = [ - {file = "pyright-1.1.369-py3-none-any.whl", hash = "sha256:06d5167a8d7be62523ced0265c5d2f1e022e110caf57a25d92f50fb2d07bcda0"}, - {file = "pyright-1.1.369.tar.gz", hash = "sha256:ad290710072d021e213b98cc7a2f90ae3a48609ef5b978f749346d1a47eb9af8"}, + {file = "pyright-1.1.377-py3-none-any.whl", hash = "sha256:af0dd2b6b636c383a6569a083f8c5a8748ae4dcde5df7914b3f3f267e14dd162"}, + {file = "pyright-1.1.377.tar.gz", hash = "sha256:aabc30fedce0ded34baa0c49b24f10e68f4bfc8f68ae7f3d175c4b0f256b4fcf"}, ] [package.dependencies] diff --git a/pyproject.toml b/pyproject.toml index 693d296..e5836e6 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,7 @@ build-backend = "poetry.core.masonry.api" [tool.poetry] name = "jinjax" -version = "0.45" +version = "0.46" description = "Replace your HTML templates with Python server-Side components" authors = ["Juan-Pablo Scaletti <juanpablo@jpscaletti.com>"] license = "MIT" diff --git a/src/jinjax/catalog.py b/src/jinjax/catalog.py index c70f81d..d0d0635 100644 --- a/src/jinjax/catalog.py +++ b/src/jinjax/catalog.py @@ -1,6 +1,7 @@ import os import typing as t from collections import UserString +from contextvars import ContextVar from hashlib import sha256 from pathlib import Path @@ -22,6 +23,10 @@ DEFAULT_EXTENSION = ".jinja" ARGS_ATTRS = "attrs" ARGS_CONTENT = "content" +# Create ContextVars containers at module level +collected_css: dict[int, ContextVar[list[str]]] = {} +collected_js: dict[int, ContextVar[list[str]]] = {} + class CallerWrapper(UserString): def __init__(self, caller: t.Callable | None, content: str = "") -> None: @@ -42,7 +47,6 @@ class CallerWrapper(UserString): return self() - class Catalog: """ The object that manages the components and their global settings. @@ -50,12 +54,12 @@ class Catalog: Arguments: globals: - Dictionary of Jinja globals to add to the Catalog's Jinja environment - (or the one passed in `jinja_env`). + Dictionary of Jinja globals to add to the Catalog's Jinja + environment (or the one passed in `jinja_env`). filters: - Dictionary of Jinja filters to add to the Catalog's Jinja environment - (or the one passed in `jinja_env`). + Dictionary of Jinja filters to add to the Catalog's Jinja + environment (or the one passed in `jinja_env`). tests: Dictionary of Jinja tests to add to the Catalog's Jinja environment @@ -63,34 +67,36 @@ class Catalog: extensions: List of Jinja extensions to add to the Catalog's Jinja environment - (or the one passed in `jinja_env`). The `jinja2.ext.do` extension is - always added at the end of these. + (or the one passed in `jinja_env`). The `jinja2.ext.do` extension + is always added at the end of these. jinja_env: - Custom Jinja environment to use. This argument is useful to reuse an - existing Jinja Environment from your web framework. + Custom Jinja environment to use. This argument is useful to reuse + an existing Jinja Environment from your web framework. root_url: - Add this prefix to every asset URL of the static middleware. By default, - it is `/static/components/`, so, for example, the URL of the CSS file of - a `Card` component is `/static/components/Card.css`. + Add this prefix to every asset URL of the static middleware. + By default, it is `/static/components/`, so, for example, + the URL of the CSS file of a `Card` component is + `/static/components/Card.css`. - You can also change this argument so the assets are requested from a - Content Delivery Network (CDN) in production, for example, + You can also change this argument so the assets are requested from + a Content Delivery Network (CDN) in production, for example, `root_url="https://example.my-cdn.com/"`. file_ext: The extensions the components files have. By default, ".jinja". - This argument can also be a list to allow more than one type of file to - be a component. + This argument can also be a list to allow more than one type of + file to be a component. use_cache: Cache the metadata of the component in memory. auto_reload: - Used with `use_cache`. If `True`, the last-modified date of the component - file is checked every time to see if the cache is up-to-date. + Used with `use_cache`. If `True`, the last-modified date of the + component file is checked every time to see if the cache + is up-to-date. Set to `False` in production. @@ -98,12 +104,12 @@ class Catalog: If `True`, inserts a hash of the updated time into the URL of the asset files (after the name but before the extension). - This strategy encourages long-term caching while ensuring that new copies - are only requested when the content changes, as any modification alters the - fingerprint and thus the filename. + This strategy encourages long-term caching while ensuring that + new copies are only requested when the content changes, as any + modification alters the fingerprint and thus the filename. - **WARNING**: Only works if the server knows how to filter the fingerprint - to get the real name of the file. + **WARNING**: Only works if the server knows how to filter the + fingerprint to get the real name of the file. Attributes: @@ -124,12 +130,11 @@ class Catalog: "file_ext", "jinja_env", "fingerprint", - "collected_css", - "collected_js", "auto_reload", "use_cache", "_tmpl_globals", "_cache", + "_key", ) def __init__( @@ -141,14 +146,14 @@ class Catalog: extensions: "list | None" = None, jinja_env: "jinja2.Environment | None" = None, root_url: str = DEFAULT_URL_ROOT, - file_ext: "str | tuple[str, ...]" = DEFAULT_EXTENSION, + file_ext: "str | list[str] | tuple[str, ...]" = DEFAULT_EXTENSION, use_cache: bool = True, auto_reload: bool = True, fingerprint: bool = False, ) -> None: self.prefixes: dict[str, jinja2.FileSystemLoader] = {} - self.collected_css: list[str] = [] - self.collected_js: list[str] = [] + if isinstance(file_ext, list): + file_ext = tuple(file_ext) self.file_ext = file_ext self.use_cache = use_cache self.auto_reload = auto_reload @@ -186,11 +191,49 @@ class Catalog: self._tmpl_globals: "t.MutableMapping[str, t.Any] | None" = None self._cache: dict[str, dict] = {} + self._key = id(self) + + def __del__(self) -> None: + name = f"collected_css_{self._key}" + if name in collected_css: + del collected_css[name] + name = f"collected_js_{self._key}" + if name in collected_js: + del collected_js[name] + + @property + def collected_css(self) -> list[str]: + if self._key not in collected_css: + name = f"collected_css_{self._key}" + collected_css[self._key] = ContextVar(name, default=[]) + return collected_css[self._key].get() + + @collected_css.setter + def collected_css(self, value: list[str]) -> None: + if self._key not in collected_css: + name = f"collected_css_{self._key}" + collected_css[self._key] = ContextVar(name, default=[]) + collected_css[self._key].set(list(value)) + + @property + def collected_js(self) -> list[str]: + if self._key not in collected_js: + name = f"collected_js_{self._key}" + collected_js[self._key] = ContextVar(name, default=[]) + return collected_js[self._key].get() + + @collected_js.setter + def collected_js(self, value: list[str]) -> None: + if self._key not in collected_js: + name = f"collected_js_{self._key}" + collected_js[self._key] = ContextVar(name, default=[]) + collected_js[self._key].set(list(value)) @property def paths(self) -> list[Path]: """ - A helper property that returns a list of all the components folder paths. + A helper property that returns a list of all the components + folder paths. """ _paths = [] for loader in self.prefixes.values(): @@ -204,15 +247,17 @@ class Catalog: prefix: str = DEFAULT_PREFIX, ) -> None: """ - Add a folder path from where to search for components, optionally under a prefix. + Add a folder path from where to search for components, optionally + under a prefix. The prefix acts like a namespace. For example, the name of a `components/Card.jinja` component is, by default, "Card", but under the prefix "common", it becomes "common.Card". - The rule for subfolders remains the same: a `components/wrappers/Card.jinja` - name is, by default, "wrappers.Card", but under the prefix "common", - it becomes "common.wrappers.Card". + The rule for subfolders remains the same: a + `components/wrappers/Card.jinja` name is, by default, + "wrappers.Card", but under the prefix "common", it + becomes "common.wrappers.Card". If there is more than one component with the same name in multiple added folders under the same prefix, the one in the folder added @@ -228,26 +273,35 @@ class Catalog: have. The default is empty. """ - prefix = prefix.strip().strip(f"{DELIMITER}{SLASH}").replace(SLASH, DELIMITER) + prefix = ( + prefix.strip() + .strip(f"{DELIMITER}{SLASH}") + .replace(SLASH, DELIMITER) + ) root_path = str(root_path) if prefix in self.prefixes: loader = self.prefixes[prefix] if root_path in loader.searchpath: return - logger.debug(f"Adding folder `{root_path}` with the prefix `{prefix}`") + logger.debug( + f"Adding folder `{root_path}` with the prefix `{prefix}`" + ) loader.searchpath.append(root_path) else: - logger.debug(f"Adding folder `{root_path}` with the prefix `{prefix}`") + logger.debug( + f"Adding folder `{root_path}` with the prefix `{prefix}`" + ) self.prefixes[prefix] = jinja2.FileSystemLoader(root_path) def add_module(self, module: t.Any, *, prefix: str | None = None) -> None: """ - Reads an absolute path from `module.components_path` and an optional prefix - from `module.prefix`, then calls `Catalog.add_folder(path, prefix)`. + Reads an absolute path from `module.components_path` and an optional + prefix from `module.prefix`, then calls + `Catalog.add_folder(path, prefix)`. - The prefix can also be passed as an argument instead of being read from - the module. + The prefix can also be passed as an argument instead of being read + from the module. This method exists to make it easy and consistent to have components installable as Python libraries. @@ -263,7 +317,9 @@ class Catalog: """ mprefix = ( - prefix if prefix is not None else getattr(module, "prefix", DEFAULT_PREFIX) + prefix + if prefix is not None + else getattr(module, "prefix", DEFAULT_PREFIX) ) self.add_folder(module.components_path, prefix=mprefix) @@ -314,16 +370,25 @@ class Catalog: if source: logger.debug("Rendering from source %s", __name) - component = self._get_from_source(name=name, prefix=prefix, source=source) + component = self._get_from_source( + name=name, prefix=prefix, source=source + ) elif self.use_cache: logger.debug("Rendering from cache or file %s", __name) - component = self._get_from_cache(prefix=prefix, name=name, file_ext=file_ext) + component = self._get_from_cache( + prefix=prefix, name=name, file_ext=file_ext + ) else: logger.debug("Rendering from file %s", __name) - component = self._get_from_file(prefix=prefix, name=name, file_ext=file_ext) + component = self._get_from_file( + prefix=prefix, name=name, file_ext=file_ext + ) root_path = component.path.parent if component.path else None + css = self.collected_css + js = self.collected_js + for url in component.css: if ( root_path @@ -332,8 +397,8 @@ class Catalog: ): url = self._fingerprint(root_path, url) - if url not in self.collected_css: - self.collected_css.append(url) + if url not in css: + css.append(url) for url in component.js: if ( @@ -343,8 +408,8 @@ class Catalog: ): url = self._fingerprint(root_path, url) - if url not in self.collected_js: - self.collected_js.append(url) + if url not in js: + js.append(url) attrs = attrs.as_dict if isinstance(attrs, HTMLAttrs) else attrs attrs.update(kw) @@ -368,7 +433,8 @@ class Catalog: **kwargs, ) -> ComponentsMiddleware: """ - Wraps you application with [Withenoise](https://whitenoise.readthedocs.io/), + Wraps you application with + [Withenoise](https://whitenoise.readthedocs.io/), a static file serving middleware. Tecnically not neccesary if your components doesn't use static assets @@ -380,13 +446,15 @@ class Catalog: A WSGI application allowed_ext: - A list of file extensions the static middleware is allowed to read - and return. By default, is just ".css", ".js", and ".mjs". + A list of file extensions the static middleware is allowed to + read and return. By default, is just ".css", ".js", and ".mjs". """ logger.debug("Creating middleware") middleware = ComponentsMiddleware( - application=application, allowed_ext=tuple(allowed_ext or []), **kwargs + application=application, + allowed_ext=tuple(allowed_ext or []), + **kwargs, ) for prefix, loader in self.prefixes.items(): url_prefix = get_url_prefix(prefix) @@ -396,7 +464,11 @@ class Catalog: return middleware - def get_source(self, cname: str, file_ext: "tuple[str, ...] | str" = "") -> str: + def get_source( + self, + cname: str, + file_ext: "tuple[str, ...] | str" = "", + ) -> str: """ A helper method that returns the source file of a component. """ @@ -445,12 +517,26 @@ class Catalog: return f"{parent}{stem}-{fingerprint}{ext}" - def _get_from_source(self, *, name: str, prefix: str, source: str) -> Component: + def _get_from_source( + self, + *, + name: str, + prefix: str, + source: str, + ) -> Component: tmpl = self.jinja_env.from_string(source, globals=self._tmpl_globals) - component = Component(name=name, prefix=prefix, source=source, tmpl=tmpl) + component = Component( + name=name, prefix=prefix, source=source, tmpl=tmpl + ) return component - def _get_from_cache(self, *, prefix: str, name: str, file_ext: str) -> Component: + def _get_from_cache( + self, + *, + prefix: str, + name: str, + file_ext: str, + ) -> Component: key = f"{prefix}.{name}.{file_ext}" cache = self._from_cache(key) if cache: @@ -461,7 +547,9 @@ class Catalog: return component logger.debug("Loading %s", key) - component = self._get_from_file(prefix=prefix, name=name, file_ext=file_ext) + component = self._get_from_file( + prefix=prefix, name=name, file_ext=file_ext + ) self._to_cache(key, component) return component @@ -475,10 +563,16 @@ class Catalog: def _to_cache(self, key: str, component: Component) -> None: self._cache[key] = component.serialize() - def _get_from_file(self, *, prefix: str, name: str, file_ext: str) -> Component: - path, tmpl_name = self._get_component_path(prefix, name, file_ext=file_ext) + def _get_from_file( + self, *, prefix: str, name: str, file_ext: str + ) -> Component: + path, tmpl_name = self._get_component_path( + prefix, name, file_ext=file_ext + ) component = Component(name=name, prefix=prefix, path=path) - component.tmpl = self.jinja_env.get_template(tmpl_name, globals=self._tmpl_globals) + component.tmpl = self.jinja_env.get_template( + tmpl_name, globals=self._tmpl_globals + ) return component def _split_name(self, cname: str) -> tuple[str, str]: @@ -492,7 +586,10 @@ class Catalog: return DEFAULT_PREFIX, cname def _get_component_path( - self, prefix: str, name: str, file_ext: "tuple[str, ...] | str" = "" + self, + prefix: str, + name: str, + file_ext: "tuple[str, ...] | str" = "", ) -> tuple[Path, str]: name = name.replace(DELIMITER, SLASH) root_paths = self.prefixes[prefix].searchpath @@ -512,7 +609,10 @@ class Catalog: filepath = f"{relfolder}/{filename}" else: filepath = filename - if filepath.startswith(name_dot) and filepath.endswith(file_ext): + if ( + filepath.startswith(name_dot) and + filepath.endswith(file_ext) + ): return Path(curr_folder) / filename, filepath raise ComponentNotFound( diff --git a/tests/test_render.py b/tests/test_render.py index 1e52cda..0f37ea7 100644 --- a/tests/test_render.py +++ b/tests/test_render.py @@ -1,6 +1,7 @@ import time from pathlib import Path from textwrap import dedent +from threading import Thread import jinja2 import pytest @@ -923,7 +924,7 @@ def test_vue_like_syntax(catalog, folder): ) html = catalog.render("Caller") print(html) - expected = """4 2+2 {'lorem': 'ipsum'} False""".strip() + expected = """4 2+2 {'lorem': 'ipsum'} False""".strip() assert html == Markup(expected) @@ -937,7 +938,7 @@ def test_jinja_like_syntax(catalog, folder): ) html = catalog.render("Caller") print(html) - expected = """4 2+2 {'lorem': 'ipsum'} False""".strip() + expected = """4 2+2 {'lorem': 'ipsum'} False""".strip() assert html == Markup(expected) @@ -951,7 +952,7 @@ def test_mixed_syntax(catalog, folder): ) html = catalog.render("Caller") print(html) - expected = """4 {{2+2}} {'lorem': 'ipsum'} False""".strip() + expected = """4 {{2+2}} {'lorem': 'ipsum'} False""".strip() assert html == Markup(expected) @@ -990,3 +991,130 @@ def test_slots(catalog, folder, autoescape): <p>Default</p> """.strip() assert html == Markup(expected) + + +class ThreadWithReturnValue(Thread): + def __init__(self, group=None, target=None, name=None, args=None, kwargs=None): + args = args or () + kwargs = kwargs or {} + Thread.__init__( + self, + group=group, + target=target, + name=name, + args=args, + kwargs=kwargs, + ) + self._target = target + self._args = args + self._kwargs = kwargs + self._return = None + + def run(self): + if self._target is not None: + self._return = self._target(*self._args, **self._kwargs) + + def join(self, *args): + Thread.join(self, *args) + return self._return + + +def test_thread_safety_of_render_assets(catalog, folder): + NUM_THREADS = 5 + + child_tmpl = """ +{#css "c{i}.css" #} +{#js "c{i}.js" #} +<p>Child {i}</p>""".strip() + + parent_tmpl = """ +{{ catalog.render_assets() }} +{{ content }}""".strip() + + comp_tmpl = """ +{#css "a{i}.css", "b{i}.css" #} +{#js "a{i}.js", "b{i}.js" #} +<Parent{i}><Child{i} /></Parent{i}>""".strip() + + expected_tmpl = """ +<link rel="stylesheet" href="/static/components/a{i}.css"> +<link rel="stylesheet" href="/static/components/b{i}.css"> +<link rel="stylesheet" href="/static/components/c{i}.css"> +<script type="module" src="/static/components/a{i}.js"></script> +<script type="module" src="/static/components/b{i}.js"></script> +<script type="module" src="/static/components/c{i}.js"></script> +<p>Child {i}</p>""".strip() + + def render(i): + return catalog.render(f"Page{i}") + + + for i in range(NUM_THREADS): + si = str(i) + child_name = f"Child{i}.jinja" + child_src = child_tmpl.replace("{i}", si) + + parent_name = f"Parent{i}.jinja" + parent_src = parent_tmpl.replace("{i}", si) + + comp_name = f"Page{i}.jinja" + comp_src = comp_tmpl.replace("{i}", si) + + (folder / child_name).write_text(child_src) + (folder / comp_name).write_text(comp_src) + (folder / parent_name).write_text(parent_src) + + threads = [] + + for i in range(NUM_THREADS): + thread = ThreadWithReturnValue(target=render, args=(i,)) + threads.append(thread) + thread.start() + + results = [thread.join() for thread in threads] + + for i, result in enumerate(results): + expected = expected_tmpl.replace("{i}", str(i)) + print(f"---- EXPECTED {i}----") + print(expected) + print(f"---- RESULT {i}----") + print(result) + assert result == Markup(expected) + + +def test_same_thread_assets_independence(catalog, folder): + catalog2 = jinjax.Catalog() + catalog2.add_folder(folder) + + print(catalog._key) + print(catalog2._key) + + (folder / "Parent.jinja").write_text(""" +{{ catalog.render_assets() }} +{{ content }}""".strip()) + + (folder / "Comp1.jinja").write_text(""" +{#css "a.css" #} +{#js "a.js" #} +<Parent />""".strip()) + + (folder / "Comp2.jinja").write_text(""" +{#css "b.css" #} +{#js "b.js" #} +<Parent />""".strip()) + + expected_1 = """ +<link rel="stylesheet" href="/static/components/a.css"> +<script type="module" src="/static/components/a.js"></script>""".strip() + + expected_2 = """ +<link rel="stylesheet" href="/static/components/b.css"> +<script type="module" src="/static/components/b.js"></script>""".strip() + + html1 = catalog.render("Comp1") + # `irender` instead of `render` so the assets are not cleared + html2 = catalog2.irender("Comp2") + print(html1) + print(html2) + assert html1 == Markup(expected_1) + assert html2 == Markup(expected_2) |
