@anydigital/breakout-css 0.11.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Anton Staroverov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+# breakout-css
+
+Modern CSS utilities to easily break-out / hang / pop-out / bleed images, tables, iframes, and other figures from their parent container.
+
+## Installation
+
+### From CDN
+
+```html
+<link
+  rel="stylesheet"
+  href="https://cdn.jsdelivr.net/npm/@anydigital/breakout-css@1/dist/breakout.css"
+/>
+```
+
+### From Source
+
+```css
+@import "@anydigital/breakout-css";
+```
+
+^ This is supported by Tailwind v4!
+
+## Usage
+
+### Basic Usage
+
+```html
+<div class="breakout">
+  <h1>Article Title</h1>
+  <p>Lorem ipsum dolor sit amet...</p>
+
+  <!-- This image will automatically break out -->
+  <img src="hero.jpg" alt="Hero image" />
+
+  <p>More content here...</p>
+</div>
+```
+
+### Supported Elements
+
+The breakout effect automatically applies to direct children or elements wrapped in `<p>` tags:
+
+**Inline blocks:**
+
+- `img`, `picture`, `figure`, `canvas`, `audio`
+
+**Larger blocks:**
+
+- `table` (responsive with horizontal scroll support), `pre`
+- `iframe`, `object`, `embed`, `video`
+
+**Custom utility classes:**
+
+- Elements with `.breakout-item` or `.breakout-item-max` class
+
+### Headings & Dividers
+
+For decorative headings and full-width dividers, use the `.breakout-headings` class. This adds a subtle accent line to the left of headings and makes horizontal rules span the full viewport width:
+
+```html
+<div class="breakout-headings">
+  <h2>Section Title</h2>
+  <p>Some content...</p>
+
+  <hr />
+
+  <h3>Subheading</h3>
+  <p>More content...</p>
+</div>
+```
+
+The extension applies to the following elements (when they don't have other classes):
+
+- `h2`, `h3`, `h4` (adds decorative accent line)
+- `hr` (breaks out to full viewport width)
+
+_Note: The decorative accent on headings is automatically hidden if the heading immediately follows an `<hr>` to avoid visual overlap._
+
+### Manual Breakout
+
+For elements that don't automatically break out, use the `.breakout-item` class:
+
+```html
+<div class="breakout">
+  <p>Regular content...</p>
+
+  <div class="breakout-item">
+    <iframe src="https://example.com/embed"></iframe>
+  </div>
+
+  <p>More content...</p>
+</div>
+```
+
+### Force Maximum Width
+
+By default, breakout elements use `width: fit-content` with `max-width: 125%`, allowing them to size between 100% and 125% width based on their content. To force an element to always use the full 125% breakout width, use `.breakout-item-max`:
+
+```html
+<div class="breakout">
+  <p>Regular content...</p>
+
+  <!-- This will always be 125% width, never smaller -->
+  <img src="wide-image.jpg" class="breakout-item-max" alt="Wide image" />
+
+  <p>More content...</p>
+</div>
+```
+
+Note: `.breakout-item-max` uses `width: 125% !important` to override default sizing.
+
+## How It Works
+
+The `.breakout` container acts as a content wrapper that:
+
+1. Sets a smart `max-width: calc(10% + 65ch + 10%)` to ensure an optimal reading line length (approx. 65 characters).
+2. Applies `padding-inline: 10%` to create the necessary gutter space for breakout elements to extend into.
+
+The breakout effect on elements is achieved by:
+
+1. Setting `width: fit-content` with `min-width: 100%` and `max-width: 125%` (inline blocks like `img`, `picture`, `figure`, `canvas`, and `audio` use `min-width: auto` instead). Tables are handled specially to be full-bleed (`max-width: 100vw`) with internal horizontal padding (`7.5%`) and horizontal scroll support.
+2. Using `margin-left: 50%` to position from the center of the container
+3. Using `transform: translateX(-50%)` to shift it left by half its width
+
+This combination allows elements to extend beyond their parent container (up to 125% width) while remaining visually centered.
+
+The `.breakout-headings` utility works by:
+
+1. Adding a `::before` pseudo-element to headings (`h2-h4`) positioned to the left.
+2. Using a `100vw` width and negative translation on `hr::before` to create a full-width divider.
+
+### Markdown Support
+
+The breakout effect works on direct children of `.breakout`, or elements wrapped in `<p>` tags (for Markdown compatibility where images are often wrapped in paragraphs).
+
+## License
+
+MIT

package/dist/breakout.css

@@ -0,0 +1,150 @@
+/* Breakout CSS - Framework-agnostic utilities for breaking out images and figures */
+
+.breakout {
+  /* Prepare the container for breakout elements */
+  padding-inline: 10%;
+  max-width: calc(10% + 65ch + 10%);
+
+  /* Direct children, or wrapped in <p> for Markdown support */
+}
+
+.breakout > img:not(does-not-exist):not(.does-not-exist),.breakout > picture:not(does-not-exist):not(.does-not-exist),.breakout > figure:not(does-not-exist):not(.does-not-exist),.breakout > canvas:not(does-not-exist):not(.does-not-exist),.breakout > audio:not(does-not-exist):not(.does-not-exist),.breakout > table:not(does-not-exist):not(.does-not-exist),.breakout > pre:not(does-not-exist):not(.does-not-exist),.breakout > iframe:not(does-not-exist):not(.does-not-exist),.breakout > object:not(does-not-exist):not(.does-not-exist),.breakout > embed:not(does-not-exist):not(.does-not-exist),.breakout > video:not(does-not-exist):not(.does-not-exist),.breakout > .breakout-item:not(does-not-exist),.breakout > .breakout-item-max:not(does-not-exist),.breakout > p > img:not(.does-not-exist),.breakout > p > picture:not(.does-not-exist),.breakout > p > figure:not(.does-not-exist),.breakout > p > canvas:not(.does-not-exist),.breakout > p > audio:not(.does-not-exist),.breakout > p > table:not(.does-not-exist),.breakout > p > pre:not(.does-not-exist),.breakout > p > iframe:not(.does-not-exist),.breakout > p > object:not(.does-not-exist),.breakout > p > embed:not(.does-not-exist),.breakout > p > video:not(.does-not-exist),.breakout > p > .breakout-item,.breakout > p > .breakout-item-max {
+      width: -moz-fit-content;
+      width: fit-content;
+      min-width: 100%;
+      max-width: 125%;
+      margin-left: 50%;
+      transform: translateX(-50%);
+    }
+
+/* Respect inline blocks' min-width */
+
+.breakout > img:not(does-not-exist),.breakout > picture:not(does-not-exist),.breakout > figure:not(does-not-exist),.breakout > canvas:not(does-not-exist),.breakout > audio:not(does-not-exist),.breakout > p > img,.breakout > p > picture,.breakout > p > figure,.breakout > p > canvas,.breakout > p > audio {
+      min-width: auto;
+    }
+
+/* Tables are so special :( */
+
+.breakout > table:not(does-not-exist):not(.does-not-exist),.breakout > p > table:not(.does-not-exist) {
+      /* .does-not-exist is here to avoid !important below @TODO */
+
+      /* Let them full-bleed */
+      width: -moz-max-content;
+      width: max-content;
+      min-width: auto;
+      max-width: 100vw;
+      padding-inline: 7.5%;
+
+      /* Let them scroll */
+      display: block;
+      overflow-x: auto;
+      -webkit-overflow-scrolling: touch; /* Smooth scroll for iOS */
+    }
+
+/* Max out the width of the element */
+
+.breakout > .breakout-item-max:not(does-not-exist),.breakout > p > .breakout-item-max {
+      width: 125% !important; /* !important is for cases like figure.breakout-item-max @TODO */
+    }
+
+.breakout-headings h2:not([class]),.breakout-headings h3:not([class]),.breakout-headings h4:not([class]),.breakout-headings hr {
+    position: relative;
+  }
+
+.breakout-headings h2:not([class])::before {
+      content: "";
+      display: block;
+      position: absolute;
+      background-color: rgba(0, 0, 0, 5%);
+    }
+
+.breakout-headings h3:not([class])::before {
+      content: "";
+      display: block;
+      position: absolute;
+      background-color: rgba(0, 0, 0, 5%);
+    }
+
+.breakout-headings h4:not([class])::before {
+      content: "";
+      display: block;
+      position: absolute;
+      background-color: rgba(0, 0, 0, 5%);
+    }
+
+.breakout-headings hr:not(.does-not-exist)::before {
+      content: "";
+      display: block;
+      position: absolute;
+      background-color: rgba(0, 0, 0, 5%);
+    }
+
+.breakout-headings h2:not([class])::before {
+      width: 10em;
+      right: 100%;
+      margin-right: 1rem;
+      height: 0.3em;
+      top: 50%;
+      transform: translateY(-50%);
+      background: linear-gradient(
+        to left,
+        rgba(0, 0, 0, 10%),
+        rgba(0, 0, 0, 5%) 10%,
+        transparent
+      );
+    }
+
+.breakout-headings h3:not([class])::before {
+      width: 10em;
+      right: 100%;
+      margin-right: 1rem;
+      height: 0.3em;
+      top: 50%;
+      transform: translateY(-50%);
+      background: linear-gradient(
+        to left,
+        rgba(0, 0, 0, 10%),
+        rgba(0, 0, 0, 5%) 10%,
+        transparent
+      );
+    }
+
+.breakout-headings h4:not([class])::before {
+      width: 10em;
+      right: 100%;
+      margin-right: 1rem;
+      height: 0.3em;
+      top: 50%;
+      transform: translateY(-50%);
+      background: linear-gradient(
+        to left,
+        rgba(0, 0, 0, 10%),
+        rgba(0, 0, 0, 5%) 10%,
+        transparent
+      );
+    }
+
+.breakout-headings hr {
+    height: 0.75rem;
+    border: none;
+    overflow: visible;
+  }
+
+.breakout-headings hr::before {
+      width: 100vw;
+      left: 50%;
+      height: 100%;
+      transform: translateX(-50%);
+    }
+
+.breakout-headings hr + h2::before {
+      display: none !important;
+    }
+
+.breakout-headings hr + h3::before {
+      display: none !important;
+    }
+
+.breakout-headings hr + h4::before {
+      display: none !important;
+    }

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@anydigital/breakout-css",
+  "version": "0.11.0",
+  "description": "Modern CSS utilities to easily break-out / hang / pop-out / bleed images, tables, iframes, and other figures from their parent container",
+  "keywords": [
+    "css",
+    "breakout",
+    "bleed",
+    "images",
+    "tables",
+    "figures",
+    "responsive",
+    "tailwind",
+    "utilities"
+  ],
+  "files": [
+    "dist",
+    "src",
+    "postcss.config.js"
+  ],
+  "style": "./src/breakout.css",
+  "exports": {
+    ".": "./src/breakout.css",
+    "./dist": "./dist/breakout.css"
+  },
+  "scripts": {
+    "build": "postcss src/breakout.css --no-map -o dist/breakout.css",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anydigital/breakout-css.git"
+  },
+  "author": "Anton Staroverov",
+  "license": "MIT",
+  "devDependencies": {
+    "postcss": "^8.4.0",
+    "postcss-cli": "^11.0.0",
+    "postcss-preset-env": "^10.6.0"
+  }
+}

package/postcss.config.js

@@ -0,0 +1,12 @@
+module.exports = {
+  plugins: {
+    'postcss-preset-env': {
+      stage: 3,
+      features: {
+        'nesting-rules': true,
+        'is-pseudo-class': true,
+      },
+      preserve: false,
+    }
+  }
+}

package/src/breakout.css

@@ -0,0 +1,108 @@
+/* Breakout CSS - Framework-agnostic utilities for breaking out images and figures */
+
+.breakout {
+  /* Prepare the container for breakout elements */
+  padding-inline: 10%;
+  max-width: calc(10% + 65ch + 10%);
+
+  /* Direct children, or wrapped in <p> for Markdown support */
+  & > *,
+  & > p > * {
+    &:is(
+      /* Inline blocks */
+      img, picture, figure, canvas, audio,
+      /* Larger blocks */
+      table,
+      pre,
+      iframe, object, embed, video,
+      /* Custom utility classes for other tags that need to be broken out */
+      .breakout-item,
+      .breakout-item-max
+    ) {
+      width: fit-content;
+      min-width: 100%;
+      max-width: 125%;
+      margin-left: 50%;
+      transform: translateX(-50%);
+    }
+
+    /* Respect inline blocks' min-width */
+    &:is(img, picture, figure, canvas, audio) {
+      min-width: auto;
+    }
+
+    /* Tables are so special :( */
+    &:is(table):not(.does-not-exist) {
+      /* .does-not-exist is here to avoid !important below @TODO */
+
+      /* Let them full-bleed */
+      width: max-content;
+      min-width: auto;
+      max-width: 100vw;
+      padding-inline: 7.5%;
+
+      /* Let them scroll */
+      display: block;
+      overflow-x: auto;
+      -webkit-overflow-scrolling: touch; /* Smooth scroll for iOS */
+    }
+
+    /* Max out the width of the element */
+    &.breakout-item-max {
+      width: 125% !important; /* !important is for cases like figure.breakout-item-max @TODO */
+    }
+  }
+}
+
+.breakout-headings {
+  h2:not([class]),
+  h3:not([class]),
+  h4:not([class]),
+  hr {
+    position: relative;
+
+    &::before {
+      content: "";
+      display: block;
+      position: absolute;
+      background-color: rgba(0, 0, 0, 5%);
+    }
+  }
+  h2:not([class]),
+  h3:not([class]),
+  h4:not([class]) {
+    &::before {
+      width: 10em;
+      right: 100%;
+      margin-right: 1rem;
+      height: 0.3em;
+      top: 50%;
+      transform: translateY(-50%);
+      background: linear-gradient(
+        to left,
+        rgba(0, 0, 0, 10%),
+        rgba(0, 0, 0, 5%) 10%,
+        transparent
+      );
+    }
+  }
+  hr {
+    height: 0.75rem;
+    border: none;
+    overflow: visible;
+
+    &::before {
+      width: 100vw;
+      left: 50%;
+      height: 100%;
+      transform: translateX(-50%);
+    }
+  }
+  hr + h2,
+  hr + h3,
+  hr + h4 {
+    &::before {
+      display: none !important;
+    }
+  }
+}