@anyblades/blades 0.28.0-alpha.4 → 0.28.0-alpha.6

package/assets/blades.theme.css

@@ -1,4 +1,6 @@
-/* <!--section:code-->
+/*
+<!--section:docs-->
+<details>How it works:
 ```css */
 label:has(input:not([type="checkbox"], [type="radio"], [type="range"]), textarea, select),
 .has-float-label {
@@ -31,17 +33,40 @@ label:has(input:not([type="checkbox"], [type="radio"], [type="range"]), textarea
     }
   }
 }
+html {
+  /* Prevent horizontal overflow and scrolling, modern way. */
+  overflow-x: clip;
+
+  /* Enable font smoothing */
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
 body {
+  /* Ensure `body` takes at least the full height of the viewport (using dynamic viewport height for better mobile support). */
+  min-height: 100dvh;
+
   /* Make the `body` a flex container with column layout, and `main` to automatically fill available space. This is useful for creating sticky footers and full-height layouts. */
   display: flex;
   flex-direction: column;
   > main {
     flex-grow: 1;
   }
+
+  /* Evaluates the last ~4 lines of text blocks to prevent a single word from sitting on the final line. */
+  text-wrap: pretty;
+
+  /* Enable global hyphenation */
+  hyphens: auto;
+  /* ... except for links and tables which are better (safer) without hyphenation */
+  a,
+  table {
+    hyphens: none;
+  }
 }
 a {
   &:not([href^="#"]) {
     text-decoration-thickness: 1px;
+
     &:hover {
       text-decoration-thickness: 2px;
     }
@@ -51,22 +76,6 @@ h1 {
   font-size: 2.5em; /* for pico.css & tw-typography */
   margin-bottom: 1rem; /* for tw-typography */
 }
-/* Potential fix https://github.com/picocss/pico/blob/main/css/pico.css for the very first headings
-:where(article, address, blockquote, dl, figure, form, ol, p, pre, table, ul) ~ :is(h1, h2, h3, h4, h5, h6) {
-  margin-top: var(--pico-typography-spacing-top);
-}
-h1,
-h2,
-h3,
-h4,
-h5,
-h6 {
-  & ~ & {
-    margin-bottom: 2rem;
-  }
-}
-NOTE: be careful with wrapped headings, i.e. inside nav: https://blades.ninja/build-awesome-11ty/#usage
-*/
 hr {
   margin-block: 2em; /* for pico.css & tw-typography */
 }
@@ -94,6 +103,11 @@ table {
   }
 }
 [data-jump-to="top"] {
+  opacity: 25%;
+  &:hover {
+    opacity: 75%;
+  }
+
   > i {
     display: inline-block;
     padding: 0.25rem 0.375rem;
@@ -103,16 +117,6 @@ table {
     border-color: black;
   }
 }
-[data-is-toc] {
-  font-size: 87.5%;
-
-  a {
-    text-decoration: none;
-  }
-  > ul > * > a {
-    font-weight: 500;
-  }
-}
 .breakout,
 .breakout-all {
   > img,
@@ -126,4 +130,5 @@ table {
   }
 }
 /*```
+</details>
 <!--section--> */

package/assets/breakout.css

@@ -1,4 +1,7 @@
-/* <!--section:code-->```css */
+/*
+<!--section:how-->
+<details>How it works:
+```css */
 .breakout,
 .breakout-all {
   /* Prepare the container for breakout elements */
@@ -79,20 +82,49 @@
   }
 }
 /*```
-<!--section:docs,summary-->
+</details>
 
-Framework-agnostic utilities for breaking out images and figures beyond their container width.
+<!--section:summary-->
 
-Use the `.breakout` class to allow elements to extend beyond their parent container.
+The `.breakout` layout allows images, tables, and other figures to automatically extend or bleed beyond their parent container’s width.
 
 <!--section:docs-->
 
+### Demo <!-- inside parent .breakout -->
+
+Break out a wide image from the text flow:
+
+<div><!-- Dummy div to avoid p tag in Markdown --></div><img
+  src="data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='3000' height='300'><rect width='100%' height='100%' fill='gray'/></svg>">
+
+Or table:
+
+| Imagine<hr> | a<hr> | really<hr> | wide<hr> | table<hr> | here<hr> |
+| ----------- | ----- | ---------- | -------- | --------- | -------- |
+| ...         |
+
+Or code block:
+
 ```html
-<div class="breakout">
-  <img src="image.jpg" alt="Description" />
-</div>
+<p>
+  Lorem ipsum dolor sit amet consectetur adipisicing elit. Quisquam, quod. Lorem ipsum dolor sit amet consectetur
+  adipisicing elit. Quisquam, quod.
+</p>
 ```
 
-The breakout container has `10%` inline padding and a max-width of `calc(10% + 65ch + 10%)`. The breakout utilities support images, pictures, figures, canvas, audio, video, tables, pre, iframe, and other media elements. Tables inside `.breakout` are specifically enhanced for horizontal scrolling and full-bleed mobile display. This is automatically included when you import the stylesheet.
+Or anything else:
+
+<article class="breakout-item-max" data-theme="dark">
+
+Using `.breakout-item` and `.breakout-item-max` helpers {style=margin:0}
+
+</article>
+
+<div><hr></div>
+
+`.breakout-all` also visually breaks out headings and horizontal rules:
+
+<h2>Heading 2</h2><h3>Heading 3</h3><h4>Heading 4</h4><h5>Heading 5</h5><h6>Heading 6</h6>
+<hr>
 
 <!--section--> */

package/assets/link-icon.css

@@ -1,5 +1,6 @@
 /* Extends https://github.com/picocss/pico/blob/main/scss/content/_link.scss
-<!--section:code-->
+<!--section:how-->
+<details>How it works:
 ```css */
 a {
   /* Use inline flex only if link contains an icon */
@@ -33,24 +34,31 @@ a {
   }
 }
 /*```
-> **PRO-TIP** for 11ty: https://blades.ninja/build-awesome-11ty/processors/#auto-link-favicons
+</details>
 
-<!--section:docs,summary-->
+How we made it: https://codepen.io/editor/anydigital/pen/019d2b94-5616-75dc-a23e-e111869d5237
 
-Use Blades' `<i>`-helper to wrap emojis, favicons, or simply drop Font Awesome icons inside links. It automatically handles sizing and alignment while preventing underline on icons.
+**PRO** example of automatic favicons for `11ty`: https://blades.ninja/build-awesome-11ty/processors/#auto-link-favicons
+
+<!--section:summary-->
+
+Use *Bl*ades `<i>`-helper to wrap emojis, favicons, or simply drop Font Awesome icons inside links. It automatically handles sizing and alignment while preventing underline on icons.
 
 <!--section:docs-->
 
-Compare:
+<article class="breakout-item">
 
-| Without Blades <hr class="lg">                                                                          | With Blades' `<i>`-helper <hr class="lg">                                                                      | Clean HTML without `<span>ning` <hr class="x2"> |
-| ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
-| [🥷 Link with emoji](#)                                                                                 | [<i>🥷</i> Link with emoji](#)                                                                                 | `<a><i>🥷</i> Text</a>`                         |
-| [![](https://www.google.com/s2/favicons?domain=any.digital&sz=64) Multi-line link <br> with favicon](#) | [<i>![](https://www.google.com/s2/favicons?domain=any.digital&sz=64)</i> Multi-line link <br> with favicon](#) | `<a><i><img src="..."></i> Text</a>`            |
-| [<b class="fa-brands fa-github fa-lg"></b> Link with Font Awesome icon](#)                              | [<i class="fa-brands fa-github fa-lg"></i> Link with Font Awesome icon](#)                                     | `<a><i class="fa-..."></i> Text</a>`            |
+| Use `<i>`-helper with                                                                 | Clean HTML without `<span>ning`      |
+| ------------------------------------------------------------------------------------- | ------------------------------------ |
+| [<i>🥷</i> Emojis](#)                                                                 | `<a><i>🥷</i> Text</a>`              |
+| [<i>![](https://www.google.com/s2/favicons?domain=any.digital&sz=64)</i> Favicons](#) | `<a><i><img src="..."></i> Text</a>` |
+| [<i class="fa-brands fa-github fa-lg"></i> Font Awesome icons](#)                     | `<a><i class="fa-..."></i> Text</a>` |
+</article>
 
----
+Or even:
 
-[How we made it ↗ &nbsp;<small>(on Codepen)</small>](https://codepen.io/editor/anydigital/pen/019d2b94-5616-75dc-a23e-e111869d5237){role=button .outline}
+<article>
+  <a href="#" style="margin: 0 0 0 1rem"><i>🥷</i> very-very-very-very-very-<br>long-multiline-links</a>
+</article>
 
 <!--section--> */

package/assets/responsive-table.css

@@ -1,4 +1,6 @@
-/* <!--section:code-->
+/*
+<!--section:how-->
+<details>How it works:
 ```css */
 table.responsive,
 .breakout > table:not(.does-not-exist),
@@ -24,17 +26,20 @@ table.responsive,
   }
 }
 /*```
-<!--#TODO:css-blade-->
-Soft-increase selector specificity trick:
+</details>
 
-`table:not(.does-not-exist)` (inspired by postcss) is used here to increase specificity against selectors like `&:is(table, .table)`
+`table:not(.does-not-exist)` trick (inspired by postcss) is used here to increase specificity against selectors like `&:is(table, .table)`
 
-<!--section:docs,summary-->
+<!--section:summary-->
 
-`<table class="responsive">` allows a table to full-bleed and scroll on mobile.
+`.responsive` makes a table full-bleed and scroll on mobile, without a need for a redundant wrapper (finally).
+
+Tables inside https://blades.ninja/css/breakout/ are responsive by default.
 
 <!--section:docs-->
 
+### Demo table
+
 | Term              | Description <hr class="x2">                                                                                                                                                                  | Link                                                |
 | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
 | Responsive design | Approach to web design that aims to make web pages render well on a variety of devices and window or screen sizes from minimum to maximum display size to ensure usability and satisfaction. | https://en.wikipedia.org/wiki/Responsive_web_design |
@@ -43,13 +48,11 @@ Soft-increase selector specificity trick:
 
 ---
 
-Tables inside https://blades.ninja/css/breakout/ are responsive by default.
-
-Living examples:
+Living examples: <!--A-Z-->
 
-- https://any.digital/insights/ai-ide/
-- https://any.digital/insights/css-frameworks/
-- https://any.digital/insights/ssg/
-- https://blades.ninja/build-awesome-11ty/#min-starters
+- https://blades.ninja/ai/ide/
+- https://blades.ninja/build-awesome-11ty/starters/
+- https://blades.ninja/css/frameworks/
+- https://blades.ninja/ssg/
 
 <!--section--> */

package/blades.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name          = "blades"
-  spec.version       = "0.28.0-alpha.4"
+  spec.version       = "0.28.0-alpha.6"
   spec.authors       = ["Anton Staroverov"]
 
   spec.summary       = "Framework-agnostic CSS utilities and single-file Liquid 'blades' for modern web development."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anyblades/blades",
-  "version": "0.28.0-alpha.4",
+  "version": "0.28.0-alpha.6",
   "description": "Framework-agnostic CSS utilities and single-file Liquid 'blades' for modern web development.",
   "style": "./assets/blades.css",
   "exports": {

package/src/_layout.css

@@ -1,24 +1,25 @@
 /* Extends https://github.com/picocss/pico/blob/main/scss/layout/
-<!--section:docs-intro-->
-
-Global styles:
-```css */
-html {
-  /* Prevent horizontal overflow and scrolling, modern way. */
-  overflow-x: clip;
-}
-body {
-  /* Ensure `body` takes at least the full height of the viewport (using dynamic viewport height for better mobile support). */
-  min-height: 100dvh;
-}
-/*```
 <!--section:docs-->
 
 ### Auto-columns
+
+`.columns` automatically creates columns with at least 30 characters each:
+
+<article class="columns">
+  <p>1</p><p>2</p><p>3</p><p>4</p><p>5</p><p>6</p>
+</article>
+
+The smaller the font size, the more columns will be created:
+
+<article class="columns" style="font-size: 65%">
+  <p>1</p><p>2</p><p>3</p><p>4</p><p>5</p><p>6</p><p>7</p><p>8</p><p>9</p>
+</article>
+
+Useful for tables of contents and long lists.
+
+<details>How it works:
 ```css */
-.columns,
-[data-is-toc] > ul,
-[data-is-toc] > ol {
+.columns {
   columns: 30ch auto; /* 2 cols max for 65ch container */
 
   /* Avoid breaking inside elements, such as nested lists */
@@ -27,21 +28,17 @@ body {
   }
 }
 /*```
-
-Table of contents (`[data-is-toc]`) has auto-columns by default.
+</details>
 
 ### Jump to top
+
+`data-jump-to="top"` fixes element to the corner and adds extra top padding to make it easy to click:
 ```css */
 [data-jump-to="top"] {
   position: fixed;
   bottom: 0;
   right: 0;
   padding-top: 50vh;
-  opacity: 25%;
-
-  &:hover {
-    opacity: 75%;
-  }
 }
 /*```
 <!--section--> */

package/src/_utilities.css

@@ -1,34 +1,58 @@
-/*
+/* Extends https://github.com/picocss/pico/tree/main/scss/utilities
 <!--section:docs-->
 
 ### Auto-dark
+
+`.dark-auto` automatically creates a simple dark version of any element:
+
+<article data-theme="dark">
+  <p>Look how cool <big class="dark-auto">🔥🕷️🐦‍⬛🐄🦓</big> can look in the dark!</p>
+</article>
+
+<details>How it works:
 ```css */
-@media (prefers-color-scheme: dark) {
-  :root:not([data-theme="light"]) {
-    .dark-auto {
-      filter: invert(100%) hue-rotate(180deg);
-    }
+/* Per https://picocss.com/docs/css-variables#css-variables-for-color-schemes */
+:root {
+  --blades-dark-filter: invert(100%) hue-rotate(180deg);
+}
+.dark-auto {
+  /* Dark color scheme (Auto) */
+  @media (prefers-color-scheme: dark) {
+    filter: var(--blades-dark-filter);
+  }
+  /* Dark color scheme (Forced) */
+  &[data-theme="dark"],
+  &:where([data-theme="dark"] *) {
+    filter: var(--blades-dark-filter);
   }
 }
 /*```
+</details>
 
 ### Faded
+
+`.faded` reduces the opacity of an element:
+
+<article class="faded">
+  Hover to unfade me!
+</article>
+
+<details>How it works:
 ```css */
 .faded {
   opacity: 50%;
+
   &:hover {
     opacity: 87.5%;
   }
 }
 /*```
+</details>
+<!--section--> */
 
-### Invert
-```css */
-/* Extends https://tailwindcss.com/docs/filter-invert */
+/* Fix the scrollbar color when inverted by https://tailwindcss.com/docs/filter-invert */
 .invert {
-  /* Fix the scrollbar color when inverted */
   ::-webkit-scrollbar {
     filter: invert(1) !important;
   }
 }
-/*``` <!--section--> */

package/src/blades.core.css

@@ -1,15 +1,15 @@
-/*** Follows https://github.com/picocss/pico/blob/main/scss/_index.scss ***/
+/* Follows https://github.com/picocss/pico/blob/main/scss/_index.scss */
 
 /* Layout */
 @import "./_layout";
 @import "./breakout";
 
 /* Content */
-@import "./_typography";
+@import "./content/_typography";
 @import "./link-icon";
-@import "./_table";
+@import "./content/_table";
 @import "./responsive-table";
-@import "./_code";
+@import "./content/_code";
 
 /* Forms */
 @import "./float-label.core";

package/src/blades.theme.css

@@ -1,19 +1,45 @@
-/* <!--section:code-->
+/*
+<!--section:docs-->
+<details>How it works:
 ```css */
 @import "./float-label.theme";
 
+html {
+  /* Prevent horizontal overflow and scrolling, modern way. */
+  overflow-x: clip;
+
+  /* Enable font smoothing */
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
 body {
+  /* Ensure `body` takes at least the full height of the viewport (using dynamic viewport height for better mobile support). */
+  min-height: 100dvh;
+
   /* Make the `body` a flex container with column layout, and `main` to automatically fill available space. This is useful for creating sticky footers and full-height layouts. */
   display: flex;
   flex-direction: column;
   > main {
     flex-grow: 1;
   }
+
+  /* Evaluates the last ~4 lines of text blocks to prevent a single word from sitting on the final line. */
+  text-wrap: pretty;
+
+  /* Enable global hyphenation */
+  hyphens: auto;
+  /* ... except for links and tables which are better (safer) without hyphenation */
+  a,
+  table {
+    hyphens: none;
+  }
 }
 
 a {
   &:not([href^="#"]) {
     text-decoration-thickness: 1px;
+
     &:hover {
       text-decoration-thickness: 2px;
     }
@@ -25,23 +51,6 @@ h1 {
   margin-bottom: 1rem; /* for tw-typography */
 }
 
-/* Potential fix https://github.com/picocss/pico/blob/main/css/pico.css for the very first headings
-:where(article, address, blockquote, dl, figure, form, ol, p, pre, table, ul) ~ :is(h1, h2, h3, h4, h5, h6) {
-  margin-top: var(--pico-typography-spacing-top);
-}
-h1,
-h2,
-h3,
-h4,
-h5,
-h6 {
-  & ~ & {
-    margin-bottom: 2rem;
-  }
-}
-NOTE: be careful with wrapped headings, i.e. inside nav: https://blades.ninja/build-awesome-11ty/#usage
-*/
-
 hr {
   margin-block: 2em; /* for pico.css & tw-typography */
 }
@@ -73,6 +82,11 @@ table {
 }
 
 [data-jump-to="top"] {
+  opacity: 25%;
+  &:hover {
+    opacity: 75%;
+  }
+
   > i {
     display: inline-block;
     padding: 0.25rem 0.375rem;
@@ -83,17 +97,6 @@ table {
   }
 }
 
-[data-is-toc] {
-  font-size: 87.5%;
-
-  a {
-    text-decoration: none;
-  }
-  > ul > * > a {
-    font-weight: 500;
-  }
-}
-
 .breakout,
 .breakout-all {
   > img,
@@ -108,4 +111,5 @@ table {
   }
 }
 /*```
+</details>
 <!--section--> */

package/src/breakout.css

@@ -1,4 +1,7 @@
-/* <!--section:code-->```css */
+/*
+<!--section:how-->
+<details>How it works:
+```css */
 .breakout,
 .breakout-all {
   /* Prepare the container for breakout elements */
@@ -80,20 +83,49 @@
   }
 }
 /*```
-<!--section:docs,summary-->
+</details>
 
-Framework-agnostic utilities for breaking out images and figures beyond their container width.
+<!--section:summary-->
 
-Use the `.breakout` class to allow elements to extend beyond their parent container.
+The `.breakout` layout allows images, tables, and other figures to automatically extend or bleed beyond their parent container’s width.
 
 <!--section:docs-->
 
+### Demo <!-- inside parent .breakout -->
+
+Break out a wide image from the text flow:
+
+<div><!-- Dummy div to avoid p tag in Markdown --></div><img
+  src="data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='3000' height='300'><rect width='100%' height='100%' fill='gray'/></svg>">
+
+Or table:
+
+| Imagine<hr> | a<hr> | really<hr> | wide<hr> | table<hr> | here<hr> |
+| ----------- | ----- | ---------- | -------- | --------- | -------- |
+| ...         |
+
+Or code block:
+
 ```html
-<div class="breakout">
-  <img src="image.jpg" alt="Description" />
-</div>
+<p>
+  Lorem ipsum dolor sit amet consectetur adipisicing elit. Quisquam, quod. Lorem ipsum dolor sit amet consectetur
+  adipisicing elit. Quisquam, quod.
+</p>
 ```
 
-The breakout container has `10%` inline padding and a max-width of `calc(10% + 65ch + 10%)`. The breakout utilities support images, pictures, figures, canvas, audio, video, tables, pre, iframe, and other media elements. Tables inside `.breakout` are specifically enhanced for horizontal scrolling and full-bleed mobile display. This is automatically included when you import the stylesheet.
+Or anything else:
+
+<article class="breakout-item-max" data-theme="dark">
+
+Using `.breakout-item` and `.breakout-item-max` helpers {style=margin:0}
+
+</article>
+
+<div><hr></div>
+
+`.breakout-all` also visually breaks out headings and horizontal rules:
+
+<h2>Heading 2</h2><h3>Heading 3</h3><h4>Heading 4</h4><h5>Heading 5</h5><h6>Heading 6</h6>
+<hr>
 
 <!--section--> */

package/src/{_code.css → content/_code.css}

@@ -1,6 +1,17 @@
-/* <!--section:docs-->
+/* Extends https://github.com/picocss/pico/blob/main/scss/content/_code.scss
+<!--section:docs-->
+
 ### Code
-Extends https://github.com/picocss/pico/blob/main/scss/content/_code.scss
+
+The `<pre><code>` blocks are Prism-compatible and support captions via `data-caption="..."` attribute:
+
+```treeview {data-caption="Key Blades CSS files:"}
+├── blades.core.css     # reusable class-light utilities, unthemed
+├── blades.theme.css    # minimal opinionated theme
+└── blades.css          # above two together
+```
+
+<details>How it works:
 ```css */
 pre {
   padding: 1rem 1.5rem;
@@ -28,7 +39,7 @@ code {
   }
 }
 
-/*** Extends https://github.com/PrismJS/prism/blob/master/plugins/treeview/prism-treeview.css ***/
+/* Extends https://github.com/PrismJS/prism/blob/master/plugins/treeview/prism-treeview.css */
 .token.treeview-part {
   .entry-line {
     width: 2.5em !important;
@@ -42,4 +53,6 @@ code {
     }
   }
 }
-/*``` <!--section--> */
+/*```
+</details>
+<!--section--> */