@anydigital/bricks 0.24.2 → 0.26.0-alpha

package/README.md

@@ -1,30 +1,36 @@
-# *Any*bricks
+# `bricks[.css]` <sup><sub>by *Any*digital</sub></sup>
 
-Framework-agnostic CSS utilities and single-file Liquid 'bricks' for modern web development.
+Framework-agnostic, Tailwind-compatible CSS utilities and single-file `bricks` for modern web development.
 
-## Installation
+<!--section:css-h2-->
 
-### Via CDN
+## CSS 'Bricks' <br><sub>from https://github.com/anydigital/bricks</sub> <a id="bricks"></a>
+
+### Install CSS
+
+Via CDN:
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@anydigital/bricks@1/dist/bricks.css" />
+<link href="https://cdn.jsdelivr.net/npm/@anydigital/bricks@0/dist/bricks.min.css" rel="stylesheet" />
 ```
 
-### Via npm
+Or import source styles via npm:
 
 ```sh
 npm install @anydigital/bricks
 ```
 
-Then import in your CSS:
-
-```css
+```css {data-caption=.css}
 @import "@anydigital/bricks";
 ```
 
-## Features
+<details><summary>
+
+### `_base.css` styles
+
+</summary>
 
-### Overflow Control
+#### Overflow Control
 
 Prevents horizontal overflow and scrolling on the entire page:
 
@@ -37,7 +43,7 @@ body {
 
 This is automatically applied when you include the stylesheet.
 
-### Full Viewport Height
+#### Full Viewport Height
 
 Ensures the body element takes at least the full height of the viewport using dynamic viewport height for better mobile support:
 
@@ -49,7 +55,26 @@ body {
 
 This is automatically applied when you include the stylesheet.
 
-### Typography Enhancements
+#### Flexbox Layout
+
+Sets up a flexible column layout structure:
+
+```css
+body {
+  display: flex;
+  flex-direction: column;
+}
+
+body > main {
+  flex-grow: 1;
+}
+```
+
+The body becomes a flex container with column direction, and `main` elements automatically grow to fill available space. This is useful for creating sticky footers and full-height layouts.
+
+This is automatically applied when you include the stylesheet.
+
+#### Typography Enhancements
 
 Improves text rendering and readability:
 
@@ -67,7 +92,13 @@ body {
 
 This is automatically applied when you include the stylesheet.
 
-### Prose Styling
+</details>
+
+<details><summary>
+
+### `_prose.css` Tailwind Typography enhancements
+
+</summary>
 
 The `.prose` class provides enhanced typography for article content and long-form text with container-like behavior:
 
@@ -110,7 +141,9 @@ The `.prose` class provides enhanced typography for article content and long-for
 
 - Code blocks with `data-caption` attribute display the caption above the code block (styled with 50% opacity, italic, and `1.5em` bottom margin)
 
-### Code Highlighting
+</details>
+
+### `_prism.css` enhancements
 
 Includes specialized styling for Prism.js, specifically focusing on treeview components:
 
@@ -120,7 +153,11 @@ Includes specialized styling for Prism.js, specifically focusing on treeview com
 - Last-child entry names have no `::before` pseudo-element
 - Supports complex file tree visualizations out of the box
 
-### Utilities
+<details><summary>
+
+### `_util.css` helpers
+
+</summary>
 
 #### Scrollbar Inversion
 
@@ -157,26 +194,9 @@ This ensures the icon and the text stay together on the same line. If you need n
 
 This is automatically included when you import the stylesheet.
 
-### Flexbox Layout
-
-Sets up a flexible column layout structure:
-
-```css
-body {
-  display: flex;
-  flex-direction: column;
-}
-
-body > main {
-  flex-grow: 1;
-}
-```
-
-The body becomes a flex container with column direction, and `main` elements automatically grow to fill available space. This is useful for creating sticky footers and full-height layouts.
-
-This is automatically applied when you include the stylesheet.
+</details>
 
-### Breakout CSS
+### `breakout-css` included
 
 Includes [breakout-css](https://github.com/anydigital/breakout-css) utilities for breaking out images and figures beyond their container width. Use the `.breakout` class to allow elements to extend beyond their parent container:
 
@@ -188,13 +208,45 @@ Includes [breakout-css](https://github.com/anydigital/breakout-css) utilities fo
 
 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.
 
-## Bricks (Template Components)
+<!--section:njk-liquid-h2-->
+
+## Universal Template 'Bricks' <small>(`.njk` & `.liquid`)</small> <br><sub>from https://github.com/anydigital/bricks</sub>
+
+The package includes reusable templates in the `./src/bricks/` directory. These are useful for common web development patterns.
+
+### Install Templates
+
+```sh
+npm install @anydigital/bricks
+cd ./src/_includes
+ln -s ../../node_modules/@anydigital/bricks/src/bricks
+```
+
+### Base HTML Template <small>(`__html.*`)</small>
+
+A unified base HTML template `bricks/__html.{njk|liquid}` that provides the essential document structure with built-in support for modern web best practices.
+
+**Usage:**
 
-The package includes reusable Liquid templates in the `bricks/` directory. These are useful for common web development patterns.
+```jinja2 {data-caption="in .njk layout:"}
+{% extends 'bricks/__html.njk' %}
 
-### Base HTML Template (`__html.liquid`)
+{% block body %}
+  <!-- YOUR page content -->
+{% endblock %}
+```
 
-A unified base HTML template that provides the essential document structure with built-in support for modern web best practices.
+Example: https://github.com/anydigital/sveleven/blob/main/src/_theme/__layout.njk
+
+```liquid {data-caption="in .liquid layout:"}
+{% capture body %}
+  <!-- YOUR page content -->
+{% endcapture %}
+
+{% include 'bricks/__html' %}
+```
+
+Example: https://github.com/anydigital/sveleven/blob/main/src/_theme/__layout.liquid
 
 **Features:**
 
@@ -207,19 +259,7 @@ A unified base HTML template that provides the essential document structure with
 - Automatic script loading from `site.scripts` array (with `defer` attribute)
 - Inline module scripts from `site.inline_scripts` array (joined with newlines in a `<script type="module">` tag)
 - Custom header content via `content_for_header`
-- Google Tag Manager integration (automatically rendered via `_gtm.liquid` template for both `<head>` and `<body>`)
-
-**Usage:**
-
-```liquid
-{% capture page_content %}
-  <!-- Your page content -->
-{% endcapture %}
-
-{% render 'bricks/__html', site: site, title: title, content_for_header: content_for_header, body: page_content %}
-```
-
-Note: Google Tag Manager is automatically included in both `<head>` and `<body>` (via the `_gtm.liquid` template) when `site.prod` and `site.gtm_id` are set.
+- Google Tag Manager integration (automatically rendered via `_gtm.{njk|liquid}` template for both `<head>` and `<body>` when `site.prod` and `site.gtm_id` are set)
 
 **Variables:**
 
@@ -235,26 +275,20 @@ Note: Google Tag Manager is automatically included in both `<head>` and `<body>`
 - `site.gtm_id` - Google Tag Manager ID (optional)
 - `site.prod` - Boolean flag for production environment (optional)
 
-### Navigation (`_nav.liquid`)
+### Navigation <small>(`_nav.*`)</small>
 
-A navigation template that renders a list of navigation links with proper accessibility attributes.
+A navigation template `bricks/_nav.{njk|liquid}` that renders a list of navigation links with proper accessibility attributes.
 
 **Parameters:**
 
 - `nav_pages` - Array of navigation page objects with `url` and `title` properties
 - `current_url` - The URL of the current page (used to set `aria-current="page"`)
 
-**Usage:**
+**Usage example with [Eleventy Navigation plugin](https://www.11ty.dev/docs/plugins/navigation/#bring-your-own-html-render-the-menu-items-manually):**
 
-```liquid
-{% render 'bricks/_nav', nav_pages: navPages, current_url: page.url %}
-```
-
-**Example:**
-
-```liquid
-{% assign navPages = site.pages | where: "nav", true %}
-{% render 'bricks/_nav', nav_pages: navPages, current_url: page.url %}
+```liquid {data-caption="in .liquid:"}
+{% assign nav_pages = collections.all | eleventyNavigation %}
+{% render 'bricks/_nav', nav_pages: nav_pages, current_url: page.url %}
 ```
 
 **Output:**
@@ -267,11 +301,13 @@ A navigation template that renders a list of navigation links with proper access
 </nav>
 ```
 
-**Compatibility:** Compatible with [Eleventy Navigation plugin](https://www.11ty.dev/docs/plugins/navigation/#bring-your-own-html-render-the-menu-items-manually).
+<details><summary>
+
+### Google Tag Manager <small>(`_gtm.*`)</small>
 
-### Google Tag Manager (`_gtm.liquid`)
+</summary>
 
-A template for embedding Google Tag Manager scripts in your pages.
+A template `bricks/_gtm.{njk|liquid}` for embedding Google Tag Manager scripts in your pages.
 
 **Parameters:**
 
@@ -279,39 +315,9 @@ A template for embedding Google Tag Manager scripts in your pages.
 - `site.prod` - Boolean flag to enable GTM only in production
 - `for_body` - Boolean flag (default: `false`). When `false`, renders the script tag for the `<head>`. When `true`, renders the noscript fallback for the `<body>`.
 
-**Note:** This template is automatically included when using `__html.liquid`. You only need to manually render it if you're not using that base template.
-
-**Manual Usage:**
-
-In your base template's `<head>`:
-
-```liquid
-{% render 'bricks/_gtm', site: site %}
-```
-
-In your base template's `<body>` (right after the opening tag):
-
-```liquid
-{% render 'bricks/_gtm', site: site, for_body: true %}
-```
-
-**Example (Manual Integration):**
-
-```liquid
-<!DOCTYPE html>
-<html>
-<head>
-  {% render 'bricks/_gtm', site: site %}
-</head>
-<body>
-  {% render 'bricks/_gtm', site: site, for_body: true %}
-  <!-- Your content -->
-</body>
-</html>
-```
-
-**Rendering Logic:** The GTM script is only rendered when both `site.prod` is `true` and `site.gtm_id` is set. The template uses a capture block to strip whitespace from the output.
+**Note:** This template is automatically included when using `__html.liquid`. You only need to manually render it if you're not using that base template, see examples:
 
-## License
+- https://github.com/anydigital/bricks/blob/main/bricks/__html.njk
+- https://github.com/anydigital/bricks/blob/main/bricks/__html.liquid
 
-MIT
+</details>

package/_config.yml

@@ -0,0 +1,4 @@
+exclude:
+  - "**/*"
+include:
+  - "*.md"

package/{bricks/__html.liquid → _includes/bricks/html.liquid}

@@ -4,7 +4,7 @@
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no, viewport-fit=cover">
     <title>
-      {{- title | strip_html | append: ' | ' | if: title -}}
+      {%- if title %}{{ title | strip_html | append: ' | ' }}{% endif -%}
       {{- site.title -}}
     </title>
     <link rel="icon" href="/favicon.ico">
@@ -12,24 +12,24 @@
     {%- for href in site.styles %}
       <link rel="stylesheet" href="{{ href }}">
     {%- endfor %}
-    {% # prettier-ignore %}
-    <style>{{ site.inline_styles | join: '\n' }}</style>
-    {% # %}
+    <style>
+      {{ site.inline_styles | join: '\n' }}
+    </style>
 
     {%- for src in site.scripts %}
       <script src="{{ src }}" defer></script>
     {%- endfor %}
-    {% # prettier-ignore %}
-    <script type="module">{{ site.inline_scripts | join: '\n' }}</script>
-    {% # %}
+    <script type="module">
+      {{ site.inline_scripts | join: '\n' }}
+    </script>
 
     {{ content_for_header }}
-    {% render './_gtm', site: site %}
+    {% include bricks/gtm.liquid %}
   </head>
 
   <body>
-    {% render './_gtm', site: site, for_body: true %}
+    {% include bricks/gtm.liquid for_body=true %}
+
     {{ body }}
-    {% # %}
   </body>
 </html>

package/{bricks/__html.njk → _includes/bricks/html.njk}

@@ -12,23 +12,23 @@
     {%- for href in site.styles %}
       <link rel="stylesheet" href="{{ href }}" />
     {%- endfor %}
-    {# prettier-ignore-start #}
-    <style>{{ site.inline_styles | d([]) | join('\n') }}</style>
-    {# prettier-ignore-end #}
+    {# prettier-ignore-start #}<style>
+      {{ site.inline_styles | d([]) | join('\n') }}
+    </style>{# prettier-ignore-end #}
 
     {%- for src in site.scripts %}
       <script src="{{ src }}" defer></script>
     {%- endfor %}
-    {# prettier-ignore-start #}
-    <script type="module">{{ site.inline_scripts | d([]) | join('\n') }}</script>
-    {# prettier-ignore-end #}
+    {# prettier-ignore-start #}<script type="module">
+      {{ site.inline_scripts | d([]) | join('\n') }}
+    </script>{# prettier-ignore-end #}
 
     {{ content_for_header }}
-    {% include 'bricks/_gtm.njk' %}
+    {% include 'bricks/gtm.njk' %}
   </head>
 
   <body>
-    {% set for_body = true %}{% include 'bricks/_gtm.njk' %}
+    {% set for_body = true %}{% include 'bricks/gtm.njk' %}
     {% block body %}
     {% endblock %}
   </body>

package/bricks.gemspec

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+Gem::Specification.new do |spec|
+  spec.name          = "bricks"
+  spec.version       = "0.25.0"
+  spec.authors       = ["Anton Staroverov"]
+
+  spec.summary       = "Framework-agnostic CSS utilities and single-file Liquid 'bricks' for modern web development."
+  spec.homepage      = "https://github.com/anydigital/bricks"
+  spec.license       = "MIT"
+
+  spec.files = Dir.glob("{_includes}/**/*")
+  # puts "spec.files: #{spec.files.inspect}"
+
+  spec.add_runtime_dependency "jekyll", ">= 3.5", "< 5.0"
+end

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@anydigital/bricks",
-  "version": "0.24.2",
+  "version": "0.26.0-alpha",
   "description": "Framework-agnostic CSS utilities and single-file Liquid 'bricks' for modern web development.",
-  "style": "./bricks/bricks.css",
+  "style": "./src/bricks.css",
   "exports": {
-    ".": "./bricks/bricks.css",
+    ".": "./src/bricks.css",
     "./dist": "./dist/bricks.css"
   },
   "scripts": {
-    "postcss": "postcss bricks/bricks.css -o dist/bricks.css",
+    "postcss": "postcss src/bricks.css -o dist/bricks.css",
     "build": "npm run postcss -- --no-map",
     "start": "npm run postcss -- --watch",
     "prepublishOnly": "npm run build"

package/{bricks → src}/bricks.css

@@ -3,7 +3,7 @@
  * Framework-agnostic CSS utility helpers
  */
 
-@import "./__html";
+@import "./_base";
 @import "./_prose";
 @import "@anydigital/breakout-css"; /* after prose to override it */
 @import "./_prism";