@anydigital/blades 0.27.0-alpha.15 → 0.27.0-beta

package/assets/blades.css

@@ -1,59 +1,39 @@
-/**
- * Follows the structure of https://github.com/picocss/pico/blob/main/scss/_index.scss
- */
+/*** Follows https://github.com/picocss/pico/blob/main/scss/_index.scss ***/
+
+/* Layout */
+
+/* <!--section:docs-->
+Extends https://github.com/picocss/pico/blob/main/scss/layout/_document.scss
+
+Prevent horizontal overflow and scrolling, modern way:
+```css */
 
 html {
-  /* Prevent horizontal overflow and scrolling, modern way */
   overflow-x: clip;
-
-  /* Font smoothing */
-  -webkit-font-smoothing: antialiased;
-  -moz-osx-font-smoothing: grayscale;
 }
 
+/*```
+
+## Landmarks
+Extends https://github.com/picocss/pico/blob/main/scss/layout/_landmarks.scss
+
+1. Ensure `body` takes at least the full height of the viewport (using dynamic viewport height for better mobile support).
+2. 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.
+```css */
+
 body {
-  /* Ensures 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; main fills space */
   display: flex;
   flex-direction: column;
   > main {
     flex-grow: 1;
   }
-
-  /* Hyphenation */
-  hyphens: auto;
-  /* Links and tables are better (safer) without hyphenation */
-  a,
-  table {
-    hyphens: none;
-  }
 }
 
-pre {
-  padding: 1rem 1.5rem;
-  padding-inline-end: 2rem;
+/*``` <!--section--> */
 
-  code {
-    padding: 0;
-  }
-
-  @media screen and (max-width: 767px) {
-    border-radius: 0;
-  }
-}
-
-small {
-  [role="button"] {
-    padding: 0.75em 1em;
-    font-size: inherit;
-  }
-}
-
-/* Layout */
-
-/* Breakout CSS - Framework-agnostic utilities for breaking out images and figures */
+/* <!--section:code-->```css */
 
 .breakout,
 .breakout-all {
@@ -84,11 +64,6 @@ small {
       min-width: auto;
     }
 
-    /* #TODO: add <!--section:tricks-->
-    #### Soft-increase selector specificity
-    `&:is(table):not(.does-not-exist)` trick (inspired by postcss) was used here to increase specificity to (0,1,1) against (0,1,0) of selectors like `&:is(table, .table)`
-    <!--section--> */
-
     /* Max out the width of the element */
     &.breakout-item-max {
       width: 125% !important; /* !important is for cases like figure.breakout-item-max @TODO */
@@ -141,9 +116,118 @@ small {
   }
 }
 
+/*```<!--section:docs-->
+Framework-agnostic utilities for breaking out images and figures beyond their container width.
+
+Use the `.breakout` class to allow elements to extend beyond their parent container:
+
+```html
+<div class="breakout">
+  <img src="image.jpg" alt="Description" />
+</div>
+```
+
+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.
+<!--section--> */
+
 /* Content */
 
+/*** Extends https://github.com/picocss/pico/blob/main/scss/content/_typography.scss ***/
+
+html {
+  /* Enable font smoothing */
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+body {
+  /* Enable global hyphenation */
+  hyphens: auto;
+  /* ... except for links and tables which are better (safer) without hyphenation */
+  a,
+  table {
+    hyphens: none;
+  }
+}
+
+/*
+<!--section:docs-->
+## Heading anchors
+```css */
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  position: relative;
+
+  [data-is-anchor] {
+    visibility: hidden;
+    position: absolute;
+    top: 0;
+    right: 100%;
+    padding-right: 0.2ch;
+    color: silver;
+    text-decoration: none;
+  }
+  &:hover {
+    [data-is-anchor] {
+      visibility: visible;
+    }
+  }
+}
+
+/*```
+
+## List markers
+```css */
+
+ul,
+ol {
+  li[data-marker]::marker {
+    content: attr(data-marker) " ";
+  }
+}
+
+/*``` <!--section--> */
+
+/* <!--section:code-->```css */
+
+a {
+  /* Helper to handle icons in links */
+  > i {
+    display: inline-block;
+    font-style: normal;
+  }
+
+  /* Helper for favicons in links */
+  &[data-has-favicon] {
+    display: inline-block;
+
+    > img {
+      max-height: 1.25em;
+      margin-top: calc(-0.25em / 2);
+      margin-inline-end: 0.375ch; /* =3/8 */
+
+      /* for tw-typography (.prose) */
+      display: inline-block;
+      margin-bottom: 0;
+    }
+  }
+}
+
+/*```
+<!--section:docs-->
+Extends https://github.com/picocss/pico/blob/main/scss/content/_link.scss
+
+## Link [fav]icons
+<!--section--> */
+
 /* <!--section:docs-->
+Extends https://github.com/picocss/pico/blob/main/scss/content/_table.scss
+
 ### Horizontal expanders
 
 Simply insert `<hr>` inside `<th>` to forcibly widen too narrow columns (especially useful in markdown):
@@ -182,17 +266,13 @@ table {
 ---
 ### Borderless table
 
-`.borderless` removes all default borders:
-| Less |            | Borders |
-| ---- | ---------- | ------- |
-|      | ↖ ↗<br>↙ ↘ |         |
-| More |            | Fun     |
+`<table class="borderless">` removes all default borders:
+| Less |     | Borders |
+| ---- | --- | ------- |
+| More |     | Fun     |
 
 {.borderless}
 
-```html
-<table class="borderless">...</table>
-```
 Living example: https://bladeswitch.com/#minimal-dependencies table
 <!--section--> */
 
@@ -207,8 +287,8 @@ table.borderless {
 ```css */
 
 table.responsive,
-.breakout > table,
-.breakout-all > table {
+.breakout > table:not(.does-not-exist),
+.breakout-all > table:not(.does-not-exist) {
   /* Center horizontally */
   margin-left: 50%;
   transform: translateX(-50%);
@@ -231,9 +311,13 @@ table.responsive,
 }
 
 /*```
+<!--#TODO:css-blade-->
+Soft-increase selector specificity trick:
+
+`table:not(.does-not-exist)` (inspired by postcss) is used here to increase specificity against selectors like `&:is(table, .table)`
 <!--section:docs-->
 ### Responsive table without wrapper
-`.responsive` allows a table to full-bleed and scroll on mobile:
+`<table class="responsive">` allows a table to full-bleed and scroll on mobile:
 <div>
 
 | Term | Description <hr class="x2"> | Link |
@@ -246,78 +330,60 @@ table.responsive,
 Tables inside `.breakout[-all]` are responsive by default.
 <!--section--> */
 
-/* Utilities */
-
-/* Header anchors @TODO: add to tricks-wiki */
+/* <!--section:docs-->
+Extends https://github.com/picocss/pico/blob/main/scss/content/_code.scss
+```css */
 
-h1,
-h2,
-h3,
-h4,
-h5,
-h6 {
-  position: relative;
+pre {
+  padding: 1rem 1.5rem;
+  padding-inline-end: 2rem;
 
-  [data-is-anchor] {
-    visibility: hidden;
-    position: absolute;
-    top: 0;
-    right: 100%;
-    padding-right: 0.2ch;
-    color: silver;
-    text-decoration: none;
-  }
-  &:hover {
-    [data-is-anchor] {
-      visibility: visible;
-    }
+  @media screen and (max-width: 767px) {
+    border-radius: 0;
   }
 }
 
-/* Helper to handle icons in links */
+code {
+  /* Code block caption via data-attr (to display filename, etc.) */
+  &[data-caption] {
+    &::before {
+      content: attr(data-caption);
+      display: block;
+      margin-bottom: 1rem;
+      opacity: 50%;
+      font-style: italic;
+    }
+  }
 
-a > i {
-  display: inline-block;
-  /* margin-inline-end: 0.375ch; safer to use &nbsp;? */ /* =3/8 */
-  font-style: normal;
+  &:where(pre > *) {
+    padding: 0;
+  }
 }
 
-/* Favicons in links @TODO: add to tricks-wiki */
-
-a[data-has-favicon] {
-  display: inline-block;
+/*** Extends https://github.com/PrismJS/prism/blob/master/plugins/treeview/prism-treeview.css ***/
 
-  > img {
-    max-height: 1.25em;
-    margin-top: calc(-0.25em / 2);
-    margin-inline-end: 0.375ch; /* =3/8 */
-
-    /* for tw-typography (.prose) */
-    display: inline-block;
-    margin-bottom: 0;
+.token.treeview-part {
+  .entry-line {
+    width: 2.5em !important;
+    opacity: 25%;
   }
-}
-
-code[data-caption] {
-  &::before {
-    content: attr(data-caption);
-    display: block;
-    margin-bottom: 1rem;
+  .entry-name:last-child {
     opacity: 50%;
-    font-style: italic;
+
+    &::before {
+      display: none !important;
+    }
   }
 }
 
-/* Tailwind tricks */
+/*``` <!--section--> */
 
-.invert {
-  /* Fix the scrollbar color when inverted */
-  ::-webkit-scrollbar {
-    filter: invert(1) !important;
-  }
-}
+/* Utilities */
 
-/* Jump to top trick */
+/* <!--section:docs-->
+
+## Jump to top
+```css */
 
 [data-jump-to="top"] {
   position: fixed;
@@ -331,7 +397,10 @@ code[data-caption] {
   }
 }
 
-/* Table of contents */
+/*```
+
+## Table of contents
+```css */
 
 [data-is-toc] {
   font-size: 87.5%;
@@ -344,27 +413,24 @@ code[data-caption] {
   }
 }
 
-/* @TODO: to TRICKS */
+/*```
+
+## Auto-columns
+```css */
 
 .columns {
   columns: 20ch auto; /* 3 cols max for 65ch container */
-}
-
-/* @TODO: to TRICKS */
 
-ul,
-ol {
-  li[data-marker]::marker {
-    content: attr(data-marker) " ";
+  /* Avoid breaking inside elements, such as nested lists */
+  > * {
+    break-inside: avoid;
   }
 }
 
-.faded {
-  opacity: 50%;
-  &:hover {
-    opacity: 87.5%;
-  }
-}
+/*```
+
+## Auto-dark
+```css */
 
 @media (prefers-color-scheme: dark) {
   :root:not([data-theme="light"]) {
@@ -374,20 +440,25 @@ ol {
   }
 }
 
-/* 3rd-party */
+/*```
 
-/* Prism.js */
+## Other
+```css */
 
-.token.treeview-part {
-  .entry-line {
-    width: 2.5em !important;
-    opacity: 25%;
+.faded {
+  opacity: 50%;
+  &:hover {
+    opacity: 87.5%;
   }
-  .entry-name:last-child {
-    opacity: 50%;
+}
 
-    &::before {
-      display: none !important;
-    }
+/* Extends https://tailwindcss.com/docs/filter-invert */
+
+.invert {
+  /* Fix the scrollbar color when inverted */
+  ::-webkit-scrollbar {
+    filter: invert(1) !important;
   }
 }
+
+/*``` <!--section--> */

package/assets/breakout.css

@@ -1,5 +1,4 @@
-/* Breakout CSS - Framework-agnostic utilities for breaking out images and figures */
-
+/* <!--section:code-->```css */
 .breakout,
 .breakout-all {
   /* Prepare the container for breakout elements */
@@ -29,18 +28,12 @@
       min-width: auto;
     }
 
-    /* #TODO: add <!--section:tricks-->
-    #### Soft-increase selector specificity
-    `&:is(table):not(.does-not-exist)` trick (inspired by postcss) was used here to increase specificity to (0,1,1) against (0,1,0) of selectors like `&:is(table, .table)`
-    <!--section--> */
-
     /* Max out the width of the element */
     &.breakout-item-max {
       width: 125% !important; /* !important is for cases like figure.breakout-item-max @TODO */
     }
   }
 }
-
 .breakout-all > * {
   &:is(h2, h3, h4, h5, h6, hr):not([class]) {
     position: relative;
@@ -85,3 +78,16 @@
     }
   }
 }
+/*```<!--section:docs-->
+Framework-agnostic utilities for breaking out images and figures beyond their container width.
+
+Use the `.breakout` class to allow elements to extend beyond their parent container:
+
+```html
+<div class="breakout">
+  <img src="image.jpg" alt="Description" />
+</div>
+```
+
+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.
+<!--section--> */

package/assets/responsive-table.css

@@ -1,8 +1,8 @@
 /* <!--section:code-->
 ```css */
 table.responsive,
-.breakout > table,
-.breakout-all > table {
+.breakout > table:not(.does-not-exist),
+.breakout-all > table:not(.does-not-exist) {
   /* Center horizontally */
   margin-left: 50%;
   transform: translateX(-50%);
@@ -24,9 +24,13 @@ table.responsive,
   }
 }
 /*```
+<!--#TODO:css-blade-->
+Soft-increase selector specificity trick:
+
+`table:not(.does-not-exist)` (inspired by postcss) is used here to increase specificity against selectors like `&:is(table, .table)`
 <!--section:docs-->
 ### Responsive table without wrapper
-`.responsive` allows a table to full-bleed and scroll on mobile:
+`<table class="responsive">` allows a table to full-bleed and scroll on mobile:
 <div>
 
 | Term | Description <hr class="x2"> | Link |

package/blades.gemspec

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

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "@anydigital/blades",
-  "version": "0.27.0-alpha.15",
+  "version": "0.27.0-beta",
   "description": "Framework-agnostic CSS utilities and single-file Liquid 'blades' for modern web development.",
-  "style": "./src/blades.css",
+  "style": "./assets/blades.css",
   "exports": {
     ".": "./src/blades.css",
     "./theme": "./src/blades.theme.css",
-    "./unreduce-motion": "./src/_unreduce-motion.css",
-    "./dist": "./dist/blades.css"
+    "./unreduce-motion": "./src/_unreduce-motion.css"
   },
   "scripts": {
     "postcss": "postcss './src/!(_)*.css' --dir ./assets",

package/src/_code.css

@@ -0,0 +1,44 @@
+/* <!--section:docs-->
+Extends https://github.com/picocss/pico/blob/main/scss/content/_code.scss
+```css */
+pre {
+  padding: 1rem 1.5rem;
+  padding-inline-end: 2rem;
+
+  @media screen and (max-width: 767px) {
+    border-radius: 0;
+  }
+}
+
+code {
+  /* Code block caption via data-attr (to display filename, etc.) */
+  &[data-caption] {
+    &::before {
+      content: attr(data-caption);
+      display: block;
+      margin-bottom: 1rem;
+      opacity: 50%;
+      font-style: italic;
+    }
+  }
+
+  &:where(pre > *) {
+    padding: 0;
+  }
+}
+
+/*** Extends https://github.com/PrismJS/prism/blob/master/plugins/treeview/prism-treeview.css ***/
+.token.treeview-part {
+  .entry-line {
+    width: 2.5em !important;
+    opacity: 25%;
+  }
+  .entry-name:last-child {
+    opacity: 50%;
+
+    &::before {
+      display: none !important;
+    }
+  }
+}
+/*``` <!--section--> */

package/src/_layout.css

@@ -0,0 +1,26 @@
+/* <!--section:docs-->
+Extends https://github.com/picocss/pico/blob/main/scss/layout/_document.scss
+
+Prevent horizontal overflow and scrolling, modern way:
+```css */
+html {
+  overflow-x: clip;
+}
+/*```
+
+## Landmarks
+Extends https://github.com/picocss/pico/blob/main/scss/layout/_landmarks.scss
+
+1. Ensure `body` takes at least the full height of the viewport (using dynamic viewport height for better mobile support).
+2. 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.
+```css */
+body {
+  min-height: 100dvh;
+
+  display: flex;
+  flex-direction: column;
+  > main {
+    flex-grow: 1;
+  }
+}
+/*``` <!--section--> */

package/src/_link.css

@@ -0,0 +1,29 @@
+/* <!--section:code-->```css */
+a {
+  /* Helper to handle icons in links */
+  > i {
+    display: inline-block;
+    font-style: normal;
+  }
+
+  /* Helper for favicons in links */
+  &[data-has-favicon] {
+    display: inline-block;
+
+    > img {
+      max-height: 1.25em;
+      margin-top: calc(-0.25em / 2);
+      margin-inline-end: 0.375ch; /* =3/8 */
+
+      /* for tw-typography (.prose) */
+      display: inline-block;
+      margin-bottom: 0;
+    }
+  }
+}
+/*```
+<!--section:docs-->
+Extends https://github.com/picocss/pico/blob/main/scss/content/_link.scss
+
+## Link [fav]icons
+<!--section--> */

package/src/_table.css

@@ -1,4 +1,6 @@
 /* <!--section:docs-->
+Extends https://github.com/picocss/pico/blob/main/scss/content/_table.scss
+
 ### Horizontal expanders
 
 Simply insert `<hr>` inside `<th>` to forcibly widen too narrow columns (especially useful in markdown):
@@ -35,17 +37,13 @@ table {
 ---
 ### Borderless table
 
-`.borderless` removes all default borders:
-| Less |            | Borders |
-| ---- | ---------- | ------- |
-|      | ↖ ↗<br>↙ ↘ |         |
-| More |            | Fun     |
+`<table class="borderless">` removes all default borders:
+| Less |     | Borders |
+| ---- | --- | ------- |
+| More |     | Fun     |
 
 {.borderless}
 
-```html
-<table class="borderless">...</table>
-```
 Living example: https://bladeswitch.com/#minimal-dependencies table
 <!--section--> */
 table.borderless {