asciidoctor-carousels 0.1.0.alpha.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f6624de15321b8a6228b276a27716201e2226260dd73d326bf80e0394be80a76
+  data.tar.gz: 9f4958a66c8cc54a9f80406e1c51f2c59a4ec4a665992f28e8f46c934a0cc191
+SHA512:
+  metadata.gz: 9d5b695dab6c1c90c21cfa43c54b6cda60a6164cb47d66d4eb1c00849d9168a9279fe4262ce91dd22fae8cbcf135f58cea7bd14bbae671f444019fdc78f925ce
+  data.tar.gz: 52fc451ad1803c4987a5ac126f463c9696425bdf5a373d9a5c687cb8594035919d4a791288ec79596e9d4be07295dbd47192dfc368cee074278be97c08979795

data/CHANGELOG.adoc

@@ -0,0 +1,10 @@
+= Changelog
+
+This document provides a summary of notable changes to the Asciidoctor Carousels project by release.
+
+== 0.1.0.alpha.1 (unreleased)
+
+* Initial implementation of the `carousel` block extension.
+* Add support for image blocks, inline image paragraphs, and Asciidoctor Diagram blocks, block macros, and inline macros.
+* Add responsive stylesheet and dependency-free script with autoplay, loop, controls, indicators, keyboard, touch, and fade support.
+* Add Ruby gem packaging and RSpec test suite.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present Asciidoctor Carousels contributors
+
+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.

data/README.adoc

@@ -0,0 +1,304 @@
+= Asciidoctor Carousels
+
+An Asciidoctor extension that adds a carousel block to the AsciiDoc syntax.
+It turns a sequence of images into a responsive, accessible image carousel (or slideshow).
+
+NOTE: This extension is intended for HTML backends (e.g., `html5`).
+For all other backends, the custom block enclosure is discarded and its visual content is converted normally.
+
+== Overview
+
+Each carousel is constructed from visual blocks enclosed in an example block annotated with the `carousel` style.
+Every child block that resolves to a single image becomes one slide.
+The following child blocks are supported:
+
+* block image macro (`image::`)
+* Asciidoctor Diagram block (e.g., `[plantuml]`)
+* Asciidoctor Diagram block macro (e.g., `plantuml::file.puml[]`)
+* Asciidoctor Diagram inline macro on its own paragraph (e.g., `plantuml:file.puml[]`)
+* any other paragraph that contains a single inline image (e.g., `+image:logo.svg[]+`)
+
+The extension does not redefine image or diagram processing.
+It delegates each slide to the normal AsciiDoc converters, so existing image and diagram attributes continue to work.
+
+== Install
+
+=== Using gem command
+
+ $ gem install asciidoctor-carousels
+
+=== Using Bundler
+
+Create a [.path]_Gemfile_ in your project:
+
+.Gemfile
+[,ruby]
+----
+source 'https://rubygems.org'
+
+gem 'asciidoctor-carousels'
+----
+
+Then install the dependencies:
+
+ $ bundle
+
+== Syntax
+
+The simplest carousel contains two or more block image macros.
+
+.basic.adoc
+[,asciidoc]
+----
+[carousel]
+====
+.Sunset over the bay
+image::images/sunset.jpg[Sunset,800,600]
+
+.Beach at noon
+image::images/beach.jpg[Beach,800,600]
+
+.City at dusk
+image::images/city.jpg[City,800,600]
+====
+----
+
+The optional block title above each image becomes that slide's caption.
+Within a carousel, those titles are not numbered as figures.
+
+=== Images included from external files
+
+You can use an include directive to load a sequence of slides.
+
+.carousel-with-include.adoc
+[,asciidoc]
+----
+[carousel]
+====
+\include::gallery/slides.adoc[]
+====
+----
+
+The included file contains the image macros:
+
+.gallery/slides.adoc
+[,asciidoc]
+----
+.Sunset over the bay
+image::sunset.jpg[Sunset,800,600]
+
+.Beach at noon
+image::beach.jpg[Beach,800,600]
+----
+
+=== Using Asciidoctor Diagram
+
+Load Asciidoctor Diagram alongside this extension and use any of its block forms as a slide.
+
+.diagrams.adoc
+[,asciidoc]
+----
+[carousel]
+====
+.Flow diagram
+[plantuml,target=flow,format=svg]
+....
+@startuml
+Alice -> Bob: hello
+@enduml
+....
+
+.Sequence diagram
+plantuml::diagrams/sequence.puml[format=svg]
+
+.Overview diagram
+plantuml:diagrams/overview.puml[format=svg]
+====
+----
+
+Diagram attributes such as `target`, `format`, `server-url`, and `svg-type` are passed through to Asciidoctor Diagram unchanged.
+If a diagram outputs a text format (e.g., `txt`), the carousel falls back to a normal example block.
+
+== Options
+
+Options and named attributes are assigned on the carousel block using standard AsciiDoc block attribute syntax.
+
+.carousel-options.adoc
+[,asciidoc]
+----
+[carousel#tour.hero%autoplay%loop,interval=3000,active-slide=2,height=400px]
+====
+image::images/a.jpg[First]
+image::images/b.jpg[Second]
+image::images/c.jpg[Third]
+====
+----
+
+=== Named attributes
+
+[cols="1,3"]
+|===
+|Attribute |Description
+
+|`interval`
+|Autoplay interval in milliseconds. Defaults to `5000`.
+
+|`active-slide`
+|Initial slide number, starting at `1`. Defaults to `1`.
+
+|`height`
+|Optional stage height as a CSS length (e.g., `400px` or `24rem`).
+
+|`width`
+|Optional stage width as a CSS length.
+
+|`aspect-ratio`
+|Optional stage aspect-ratio hint (e.g., `16/9`).
+|===
+
+=== Behavior options
+
+[cols="1,3"]
+|===
+|Option |Description
+
+|`autoplay`
+|Advance slides automatically using `interval`.
+
+|`loop`
+|Wrap from the last slide to the first. Enabled by default.
+
+|`noloop`
+|Disable looping.
+
+|`fade`
+|Use a crossfade transition instead of a horizontal slide transition.
+
+|`pause-on-hover`
+|Pause autoplay while the pointer is over the carousel.
+
+|`keyboard`
+|Enable left and right arrow keys. Enabled by default.
+
+|`nokeyboard`
+|Disable keyboard navigation.
+
+|`touch`
+|Enable swipe navigation on touch devices. Enabled by default.
+
+|`notouch`
+|Disable touch navigation.
+
+|`controls`
+|Show previous and next controls. Enabled by default.
+
+|`nocontrols`
+|Hide the previous and next controls.
+
+|`indicators`
+|Show slide indicators. Enabled by default.
+
+|`noindicators`
+|Hide the slide indicators.
+|===
+
+== Usage
+
+=== CLI
+
+ $ asciidoctor -r asciidoctor-carousels basic.adoc
+
+To use diagrams in a carousel, load Asciidoctor Diagram as well:
+
+ $ asciidoctor -r asciidoctor-carousels -r asciidoctor-diagram diagrams.adoc
+
+You can specify an alternate stylesheet using the `carousel-stylesheet` document attribute.
+
+ $ asciidoctor -r asciidoctor-carousels -a carousel-stylesheet=my-carousel.css basic.adoc
+
+The value of `carousel-stylesheet` is handled in the same way as the built-in `stylesheet` document attribute.
+
+=== API
+
+Require the extension with either of these two forms:
+
+[,ruby]
+----
+require 'asciidoctor'
+require 'asciidoctor-carousels'
+----
+
+[,ruby]
+----
+require 'asciidoctor'
+require 'asciidoctor/carousels'
+----
+
+You can also register the extension with a scoped registry:
+
+[,ruby]
+----
+require 'asciidoctor'
+require 'asciidoctor/carousels/extensions'
+
+registry = Asciidoctor::Extensions.create
+Asciidoctor::Carousels::Extensions.register registry
+
+Asciidoctor.convert_file 'basic.adoc', extension_registry: registry, safe: :safe
+----
+
+== How it Works
+
+The extension transforms the visual blocks inside the example block into a single carousel block that is a specialization of an open block.
+The example block enclosure is discarded.
+
+The carousel interface consists of:
+
+* a stage element that clips the visible slide,
+* a track element that contains the slides,
+* one slide element per visual block,
+* optional previous and next controls,
+* optional slide indicators.
+
+The supporting stylesheet and script are added only when producing a standalone HTML document.
+The stylesheet is added to the end of the `<head>` element and the script is added to the end of the `<body>` element.
+By default, both assets are embedded into the HTML.
+If the `linkcss` attribute is set, the HTML links to these assets instead.
+*In that case, copy the assets from the [.path]_data_ folder of the gem to the linked location.*
+
+The first slide is selected by default, or the slide specified by `active-slide`.
+
+== Managing Assets
+
+The carousel is activated at runtime by a stylesheet and a script.
+Both assets are embedded by default, so there is normally nothing else to do.
+
+If `linkcss` is set, the linked assets must be copied to the expected location.
+The files are [.path]_data/css/carousels.css_ and [.path]_data/js/carousels.js_ in the gem or project repository.
+Copy them as [.path]_asciidoctor-carousels.css_ and [.path]_asciidoctor-carousels.js_ in the directory of the HTML document, or adjust `stylesdir` and `scriptsdir` accordingly.
+
+== Development
+
+=== Run the tests
+
+The test suite is located in the [.path]_spec_ directory and uses RSpec.
+
+ $ bundle exec rspec
+
+=== Lint the code
+
+ $ bundle exec rake lint
+
+=== Build the gem
+
+ $ bundle exec rake build
+
+== Copyright and License
+
+Copyright (C) 2026-present Asciidoctor Carousels contributors.
+Use of this software is granted under the terms of the MIT License.
+See the link:LICENSE[LICENSE] file for the full license text.
+
+== Trademarks
+
+AsciiDoc(R) is a trademark of the Eclipse Foundation, Inc.

data/asciidoctor-carousels.gemspec

@@ -0,0 +1,38 @@
+begin
+  require_relative 'lib/asciidoctor/carousels/version'
+rescue LoadError
+  require 'asciidoctor/carousels/version'
+end
+
+Gem::Specification.new do |s|
+  s.name = 'asciidoctor-carousels'
+  s.version = Asciidoctor::Carousels::VERSION
+  s.summary = 'An Asciidoctor extension that adds a carousel block to the AsciiDoc syntax.'
+  s.description = 'An Asciidoctor extension that adds a carousel block to the AsciiDoc syntax. The carousel is constructed from visual blocks, such as image macros and Asciidoctor Diagram blocks, enclosed in an example block marked with the carousel style.'
+  s.authors = ['Asciidoctor Carousels contributors']
+  s.email = 'noreply@asciidoctor.org'
+  s.homepage = 'https://asciidoctor.org'
+  s.license = 'MIT'
+  # NOTE required ruby version is informational only; it's not enforced since it can't be overridden and can cause builds to break
+  #s.required_ruby_version = '>= 2.3.0'
+  s.metadata = {
+    'bug_tracker_uri' => 'https://github.com/asciidoctor/asciidoctor-carousels/issues',
+    'changelog_uri' => 'https://github.com/asciidoctor/asciidoctor-carousels/blob/main/CHANGELOG.adoc',
+    'mailing_list_uri' => 'https://chat.asciidoctor.org',
+    'source_code_uri' => 'https://github.com/asciidoctor/asciidoctor-carousels'
+  }
+
+  # NOTE the logic to build the list of files is designed to produce a usable package even when the git command is not available.
+  # The directory listing is merged in so the gem can also be built from an uncommitted working tree.
+  begin
+    files = `git ls-files -z`.split ?\0
+    files = files.empty? ? Dir['**/*'] : (files + Dir['**/*']).uniq
+  rescue
+    files = Dir['**/*']
+  end
+  s.files = files.grep %r/^(?:(?:data|lib)\/.+|LICENSE|(?:CHANGELOG|README|design)\.adoc|#{s.name}\.gemspec)$/
+  s.executables = (files.grep %r/^bin\//).map {|f| File.basename f }
+  s.require_paths = ['lib']
+
+  s.add_runtime_dependency 'asciidoctor', ['>= 2.0.0', '< 3.0.0']
+end

data/data/css/carousels.css

@@ -0,0 +1,162 @@
+/*! Asciidoctor Carousels | Copyright (c) 2026-present Asciidoctor Carousels contributors | MIT License */
+.carousel {
+  margin-bottom: 1.25em;
+}
+
+.carousel-stage {
+  position: relative;
+  overflow: hidden;
+  background-color: #fff;
+  border: 1px solid #dcdcdc;
+}
+
+.carousel-track {
+  display: flex;
+  align-items: stretch;
+  transition: transform 300ms ease-in-out;
+  will-change: transform;
+}
+
+.carousel-slide {
+  flex: 0 0 100%;
+  min-width: 100%;
+  position: relative;
+}
+
+.carousel-slide.is-hidden {
+  display: none;
+}
+
+.carousel-slide .imageblock,
+.carousel-slide .paragraph {
+  margin: 0;
+}
+
+.carousel-slide .imageblock .content,
+.carousel-slide .paragraph p {
+  margin: 0;
+}
+
+.carousel-slide img {
+  display: block;
+  width: 100%;
+  max-width: 100%;
+  height: auto;
+  margin: 0 auto;
+}
+
+.carousel-slide-caption {
+  position: absolute;
+  top: 0;
+  left: 0;
+  z-index: 1;
+  max-width: calc(100% - 2rem);
+  padding: 0.4rem 0.75rem;
+  background-color: rgba(0, 0, 0, 0.55);
+  color: #fff;
+  font-size: 0.875em;
+  line-height: 1.4;
+  pointer-events: none;
+}
+
+.carousel-control {
+  position: absolute;
+  top: 50%;
+  z-index: 2;
+  width: 2.5em;
+  height: 2.5em;
+  padding: 0;
+  border: 1px solid #dcdcdc;
+  border-radius: 50%;
+  background-color: rgba(255, 255, 255, 0.9);
+  color: rgba(0, 0, 0, 0.7);
+  cursor: pointer;
+  transform: translateY(-50%);
+}
+
+.carousel-control:hover,
+.carousel-control:focus-visible {
+  background-color: #fff;
+  color: #2156a5;
+}
+
+.carousel-control-prev {
+  left: 0.5rem;
+}
+
+.carousel-control-next {
+  right: 0.5rem;
+}
+
+.carousel-indicators {
+  position: absolute;
+  right: 0;
+  bottom: 0;
+  left: 0;
+  z-index: 2;
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: center;
+  gap: 0.25rem;
+  padding: 0.5rem;
+}
+
+.carousel-indicator {
+  width: 0.75rem;
+  height: 0.75rem;
+  padding: 0;
+  border: 1px solid #dcdcdc;
+  border-radius: 50%;
+  background-color: rgba(255, 255, 255, 0.7);
+  cursor: pointer;
+}
+
+.carousel-indicator:hover,
+.carousel-indicator:focus-visible,
+.carousel-indicator.is-active {
+  background-color: #2156a5;
+}
+
+.carousel-indicator span {
+  display: block;
+  font-size: 0;
+}
+
+.carousel.is-fade .carousel-track {
+  display: block;
+  transition: none;
+}
+
+.carousel.is-fade .carousel-slide {
+  position: absolute;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  left: 0;
+  display: block;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 300ms ease-in-out;
+}
+
+.carousel.is-fade .carousel-slide.is-active {
+  position: relative;
+  opacity: 1;
+  pointer-events: auto;
+}
+
+.carousel.is-fade .carousel-stage {
+  height: var(--carousel-height, auto);
+}
+
+.carousel-stage[style*='--carousel-height'] .carousel-slide img {
+  height: var(--carousel-height, auto);
+  object-fit: contain;
+}
+
+@media (max-width: 767px) {
+  .carousel-control {
+    width: 2.25em;
+    height: 2.25em;
+  }
+}

data/data/js/carousels.js

@@ -0,0 +1,124 @@
+;(function () { /*! Asciidoctor Carousels | Copyright (c) 2026-present Asciidoctor Carousels contributors | MIT License */
+  'use strict'
+
+  var forEach = Array.prototype.forEach
+  var slice = Array.prototype.slice
+
+  init(document.querySelectorAll('.carousel'))
+
+  function init (carousels) {
+    forEach.call(carousels, function (carousel) {
+      var stage = carousel.querySelector('.carousel-stage')
+      var track = carousel.querySelector('.carousel-track')
+      var slides = slice.call(carousel.querySelectorAll('.carousel-slide'))
+      if (!stage || !track || !slides.length) return
+
+      var config = stage.dataset || {}
+      var activeIndex = clamp(parseInt(config.activeSlide || '1', 10) - 1, 0, slides.length - 1)
+      var interval = parsePositiveInt(config.interval || '5000', 5000)
+      var autoplay = config.autoplay === 'true'
+      var loop = config.loop !== 'false'
+      var keyboard = config.keyboard !== 'false'
+      var touch = config.touch !== 'false'
+      var pauseOnHover = config.pauseOnHover === 'true'
+      var isFade = carousel.classList.contains('is-fade')
+      var timer
+
+      slides.forEach(function (slide) { slide.classList.remove('is-hidden') })
+      if (keyboard) stage.setAttribute('tabindex', '0')
+
+      function setActive (index, skipFocus) {
+        activeIndex = clamp(index, 0, slides.length - 1)
+        slides.forEach(function (slide, idx) {
+          var active = idx === activeIndex
+          slide.classList[active ? 'add' : 'remove']('is-active')
+          slide.setAttribute('aria-hidden', active ? 'false' : 'true')
+        })
+        if (!isFade) track.style.transform = 'translateX(-' + activeIndex * 100 + '%)'
+        forEach.call(carousel.querySelectorAll('.carousel-indicator'), function (indicator, idx) {
+          indicator.classList[idx === activeIndex ? 'add' : 'remove']('is-active')
+        })
+        if (!skipFocus && keyboard) stage.focus()
+      }
+
+      function next () {
+        var target = activeIndex + 1
+        if (target >= slides.length) target = loop ? 0 : slides.length - 1
+        setActive(target)
+        if (!loop && target === slides.length - 1 && timer) stop()
+      }
+
+      function prev () {
+        var target = activeIndex - 1
+        if (target < 0) target = loop ? slides.length - 1 : 0
+        setActive(target)
+      }
+
+      function go (index) {
+        setActive(index)
+        stop()
+        if (autoplay) start()
+      }
+
+      function start () {
+        if (timer) stop()
+        timer = window.setInterval(next, interval)
+      }
+
+      function stop () {
+        if (!timer) return
+        window.clearInterval(timer)
+        timer = undefined
+      }
+
+      forEach.call(carousel.querySelectorAll('.carousel-control'), function (control) {
+        control.addEventListener('click', function () {
+          control.dataset.carouselAction === 'prev' ? prev() : next()
+        })
+      })
+
+      forEach.call(carousel.querySelectorAll('.carousel-indicator'), function (indicator) {
+        indicator.addEventListener('click', function () {
+          go(parseInt(indicator.dataset.carouselIndex, 10))
+        })
+      })
+
+      if (keyboard) {
+        stage.addEventListener('keydown', function (e) {
+          if (e.key === 'ArrowLeft') prev()
+          else if (e.key === 'ArrowRight') next()
+        })
+      }
+
+      if (touch) {
+        var startX
+        stage.addEventListener('pointerdown', function (e) { startX = e.clientX })
+        stage.addEventListener('pointerup', function (e) {
+          if (startX === undefined) return
+          var delta = e.clientX - startX
+          if (Math.abs(delta) > 30) delta < 0 ? next() : prev()
+          startX = undefined
+        })
+      }
+
+      if (autoplay) start()
+      if (pauseOnHover) {
+        carousel.addEventListener('mouseenter', stop)
+        carousel.addEventListener('mouseleave', function () { if (autoplay) start() })
+      }
+
+      setActive(activeIndex, true)
+      carousel.classList.remove('is-loading')
+      carousel.classList.add('is-loaded')
+    })
+  }
+
+  function clamp (value, min, max) {
+    return Math.min(max, Math.max(min, value))
+  }
+
+  function parsePositiveInt (value, fallback) {
+    var parsed = parseInt(value, 10)
+    return parsed > 0 ? parsed : fallback
+  }
+})()