asciidoctor-tabs 1.0.0.alpha.1 → 1.0.0.alpha.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 370d0b3ca4f09c79c9e427316a4caaebea3f00d1759767967d0ef97a9195748d
-  data.tar.gz: 6e6da5d865f2c664aad52cd5ae7806623fc125f73139bd774c2594fa5cee171c
+  metadata.gz: a6224fd054576b98130cb17fff445018029d8c3271cc4747ff00c112e513bb42
+  data.tar.gz: 1f1f618257e63009b54fc7d3fd11fd41bc490fc96c089fae0de75f6b74bb4239
 SHA512:
-  metadata.gz: 79f7f471c4ca7a4c240b8015fc4a160d802d73e898af80529cf5da51e9e5fbbb02e029d2786007bdd39aac2f10f686de6fd8fdec683dbea552bd9811f89505ba
-  data.tar.gz: b954ee1788718b5b63b4536555c7d5b51260108946d34200cc84a53cee2b64304a7d266effba6d0eaf485c862c820e26259fd005f3c018749c613994e46701ca
+  metadata.gz: 96ac2018cfaa5c8d0ee23c87c306cc64d0f67b76100d623816166ea1a09f9a9c1939503111717616dc2f062efe3d13bffe3469d88570011de18ff9a9c7ea6b82
+  data.tar.gz: 97b9ab0a22a0ffa2eadec746d963c91b5a9c60d274bb088e82ef3224f55116ec5353706601765c1d858c45a364b2e8d5ff3a9d61a51e8034d9b78a80f64b4cb8

data/CHANGELOG.adoc

@@ -4,6 +4,52 @@
 This document provides a curated view of the changes to Asciidoctor Tabs per release.
 For a detailed view of what has changed, refer to the {url-repo}/commits/main[commit history] on GitHub.
 
+== 1.0.0-alpha.3 (2022-10-05) - @mojavelinux
+
+=== Added
+
+* Provide fallback behavior for non-HTML backends (filetype is not html) (#4)
+* Support multiple tab labels (terms) for the same content (description) (#8)
+* Allow alternate stylesheet for tabs to be specified using `tabs-stylesheet` attribute (#6)
+
+=== Changed
+
+* Assign ID directly to tab (list item) node (instead of using inline anchor) if backend supports it (#11)
+
+=== Fixed
+
+* Create empty pane instead of crashing if dlist item has term only / no description
+
+=== Details
+
+{url-repo}/releases/tag/v1.0.0-alpha.3[git tag] | {url-repo}/compare/v1.0.0-alpha.2\...v1.0.0-alpha.3[full diff]
+
+== 1.0.0-alpha.2 (2022-10-03) - @mojavelinux
+
+=== Added
+
+* Transpile `Asciidoctor::Tabs::Extensions` class for npm package
+
+=== Changed
+
+* Rename `idx-tabset` counter to `tabset-number` to be consistent with built-in counter names
+* Don't register docinfo extensions if converter is producing embedded output
+* Update `register` and `unregister` on `Asciidoctor::Tabs::Extensions` to accept a registry argument
+* Delegate registration of extension in npm package to `Asciidoctor::Tabs::Extensions.register` method
+* Allow `Extensions` class to be required from `@asciidoctor/tabs/extensions` in Node.js; attach `Block` and `Docinfo` classes
+
+=== Fixed
+
+* Preserve text of dlist item for tab if item has both text and blocks (#13)
+* Honor explicit ID on tabs block and use it as ID prefix for tabs
+* Register reference for tabset in document catalog
+* Autogenerate IDs for tabsets and tabs in a manner consistent with section ID generation (#2)
+* Fix context value on pass blocks created by extension
+
+=== Details
+
+{url-repo}/releases/tag/v1.0.0-alpha.2[git tag] | {url-repo}/compare/v1.0.0-alpha.1\...v1.0.0-alpha.2[full diff]
+
 == 1.0.0-alpha.1 (2022-10-01) - @mojavelinux
 
 _Initial release._

data/README.adoc

@@ -1,12 +1,18 @@
 = Asciidoctor Tabs
 Dan Allen <https://github.com/mojavelinux[@mojavelinux]>
-v1.0.0-alpha.1, 2022-10-01
+v1.0.0-alpha.3, 2022-10-05
 :idprefix:
 :idseparator: -
+ifndef::env-github[:icons: font]
+ifdef::env-github[]
+:note-caption: :paperclip:
+endif::[]
 
-An Asciidoctor extension that adds tabs to the AsciiDoc syntax.
-The tabset is constructed from a dlist enclosed in an example block marked with the tabs style.
-This extension is only designed to be used with the `html` backend.
+An Asciidoctor extension that adds a tabs block to the AsciiDoc syntax.
+Each set of tabs (a "tabset") is constructed from a dlist enclosed in an example block marked with the tabs style.
+
+NOTE: This extension is intended to be used with HTML backends (e.g., `html`).
+For other backends (i.e., filetype is not html), the example block enclosure will be taken away and the dlist will be converted normally.
 
 == Install
 
@@ -41,7 +47,7 @@ Then use Bundler to install the gem:
 
 A tabset is defined using a dlist enclosed in an example block marked with the tabs style.
 Each item in the dlist becomes a separate tab.
-The term in the dlist item is used for the title of the tab.
+The term in the dlist item is used as the tab's label.
 The description in the dlist item is used for the contents of the tab.
 The contents can be defined as primary text, attached blocks, or blocks enclosed in an attached open block.
 If the blocks are enclosed in an attached open block, the open block enclosure itself will be discarded.
@@ -69,8 +75,51 @@ Contains more than one block.
 
 == Usage
 
+=== CLI
+
  $ asciidoctor -r asciidoctor-tabs document-with-tabs.adoc
 
+You can specify an alternate stylesheet for tabs using the `tabs-stylesheet` document attribute.
+The value of this attribute is handled in the same way as the built-in `stylesheet` document attribute.
+A relative path is resolved starting from the value of the `stylesdir` document attribute, which defaults to the directory of the document.
+
+ $ asciidoctor -r asciidoctor-tabs -a tabs-stylesheet=my-tabs.css document-with-tabs.adoc
+
+=== API
+
+There are two ways to use the extension with the Asciidoctor API.
+In either case, you must require the Asciidoctor gem (`asciidoctor`) before requiring this one.
+
+You can require `asciidoctor/tabs` to register the extension as a global extension, just like with the CLI.
+
+[,js]
+----
+require 'asciidoctor'
+require 'asciidoctor/tabs'
+
+Asciidoctor.convert_file 'document-with-tabs.adoc', safe: :safe
+----
+
+Or you can pass a registry instance to the `Extensions.register` method to register the extension with a scoped registry.
+
+[,js]
+----
+require 'asciidoctor'
+require 'asciidoctor/tabs/extensions'
+
+registry = Asciidoctor::Extensions.create
+Asciidoctor::Tabs::Extensions.register registry
+
+Asciidoctor.convert_file 'document-with-tabs.adoc', extension_registry: registry, safe: :safe
+----
+
+If you're not using other scoped extensions, you can pass in the extensions group without creating a registry instance:
+
+[,js]
+----
+Asciidoctor.convert_file 'document-with-tabs.adoc', extensions: Asciidoctor::Tabs::Extensions.group, safe: :safe
+----
+
 == Authors
 
 Asciidoctor Tabs was written by Dan Allen of OpenDevise Inc. and contributed to the Asciidoctor project.

data/data/css/tabs.css

@@ -1,5 +1,5 @@
 /*! Asciidoctor Tabs stylesheet | Copyright (c) 2018-present Dan Allen | MIT License */
-.tabs ul {
+.tabs > ul {
   display: flex;
   flex-wrap: wrap;
   list-style: none;
@@ -7,7 +7,7 @@
   padding: 0;
 }
 
-.tabs li {
+.tabs > ul li {
   align-items: center;
   border: 1px solid black;
   border-bottom: 0;
@@ -21,11 +21,11 @@
   position: relative;
 }
 
-.tabs.ulist li, .tabs.ulist p {
+.tabs > ul li, .tabs > ul p {
   margin-bottom: 0;
 }
 
-.tabs li + li {
+.tabs > ul li + li {
   margin-top: 0;
 }
 

data/data/js/tabs.js

@@ -11,7 +11,8 @@
       find('li', tabs).forEach(function (tab, idx) {
         var id = (tab.querySelector('a[id]') || tab).id
         if (!id) return
-        var pane = getPane(id, tabset)
+        var pane = tabset.querySelector('.tab-pane[aria-labelledby~="' + id + '"]')
+        if (!pane) return
         if (!idx) first = { tab: tab, pane: pane }
         if (!active && hash === '#' + id && (active = true)) {
           tab.classList.add('is-active')
@@ -42,10 +43,4 @@
   function find (selector, from) {
     return Array.prototype.slice.call((from || document).querySelectorAll(selector))
   }
-
-  function getPane (id, tabset) {
-    return find('.tab-pane', tabset).find(function (it) {
-      return it.getAttribute('aria-labelledby') === id
-    })
-  }
 })()

data/lib/asciidoctor/tabs/block.rb

@@ -6,58 +6,73 @@ module Asciidoctor
       use_dsl
       on_context :example
 
-      ID_SEPARATOR_CHAR = '-'
-      INVALID_ID_CHARS_RX = /[^a-zA-Z0-9_]/
-
       def process parent, reader, attrs
-        block = create_block parent, :example, nil, attrs, content_model: :compound
+        block = create_block parent, attrs['cloaked-context'], nil, attrs, content_model: :compound
         children = (parse_content block, reader).blocks
         return block unless children.size == 1 && (source_tabs = children[0]).context == :dlist && source_tabs.items?
-        nodes = []
-        tabset_idx = parent.document.counter 'idx-tabset'
-        id = block.id || %(tabset#{tabset_idx})
-        nodes << (create_html_fragment parent, %(<div id="#{id}" class="tabset is-loading">))
-        tabs = create_list parent, :ulist
-        tabs.add_role 'tabs'
+        unless (doc = parent.document).attr? 'filetype', 'html'
+          source_tabs.id ||= attrs['id']
+          (reftext = attrs['reftext']) && (source_tabs.set_attr 'reftext', reftext) unless source_tabs.attr? 'reftext'
+          return source_tabs
+        end
+        tabset_number = doc.counter 'tabset-number'
+        id = attrs['id'] || %(#{doc.attributes['idprefix'] || '_'}tabset#{tabset_number})
+        parent << (create_html_fragment parent, %(<div id="#{id}" class="tabset is-loading">))
+        (tabs = create_list parent, :ulist).add_role 'tabs'
         panes = {}
-        source_tabs.items.each do |(title), details|
-          tab = create_list_item tabs
-          tabs << tab
-          tab_id = generate_id title.text, id
-          tab.text = %([[#{tab_id}]]#{title.instance_variable_get :@text})
-          if details.blocks?
-            blocks = details.blocks
-          elsif details.text?
-            blocks = [(create_paragraph parent, (details.instance_variable_get :@text), {})]
-          else
-            next
+        set_id_on_tab = (doc.backend == 'html5') || (list_item_supports_id? doc)
+        source_tabs.items.each do |labels, content|
+          tab_ids = labels.map do |tab|
+            tabs << tab
+            tab_id = generate_id tab.text, id, doc
+            set_id_on_tab ? (tab.id = tab_id) : (tab.text = %([[#{tab_id}]]#{tab.instance_variable_get :@text}))
+            tab_id
           end
-          if (block0 = blocks[0]).context == :open && blocks.size == 1 && block0.blocks?
-            blocks = block0.blocks
+          if content
+            text = create_paragraph parent, (content.instance_variable_get :@text), nil if content.text?
+            if content.blocks?
+              if (block0 = (blocks = content.blocks)[0]).context == :open && blocks.size == 1 && block0.blocks?
+                blocks = block0.blocks
+              end
+              blocks.unshift text if text
+            elsif text
+              blocks = [text]
+            end
           end
-          (panes[tab_id] = blocks).each {|it| it.parent = parent }
+          panes[tab_ids] = blocks || []
         end
-        nodes << tabs
-        nodes << (create_html_fragment parent, '<div class="content">')
-        panes.each do |tab_id, blocks|
-          nodes << (create_html_fragment parent, %(<div class="tab-pane" aria-labelledby="#{tab_id}">))
-          nodes.push(*blocks)
-          nodes << (create_html_fragment parent, '</div>')
+        parent << tabs
+        parent << (create_html_fragment parent, '<div class="content">')
+        panes.each do |tab_ids, blocks|
+          parent << (create_html_fragment parent, %(<div class="tab-pane" aria-labelledby="#{tab_ids.join ' '}">))
+          blocks.each {|it| parent << it }
+          parent << (create_html_fragment parent, '</div>')
         end
-        nodes << (create_html_fragment parent, '</div>')
-        nodes << (create_html_fragment parent, '</div>')
-        nodes.each {|it| parent.blocks << it }
-        nil
+        parent << (create_html_fragment parent, '</div>')
+        create_html_fragment parent, '</div>', 'id' => id
       end
 
       private
 
-      def create_html_fragment parent, html
-        create_block parent, 'pass', html, nil
+      def create_html_fragment parent, html, attributes = nil
+        create_block parent, :pass, html, attributes
       end
 
-      def generate_id str, base_id
-        %(#{base_id}_#{str.downcase.gsub INVALID_ID_CHARS_RX, ID_SEPARATOR_CHAR})
+      def generate_id str, base_id, doc
+        restore_idprefix = (attrs = doc.attributes)['idprefix']
+        attrs['idprefix'] = %(#{base_id}#{attrs['idseparator'] || '_'})
+        ::Asciidoctor::Section.generate_id str, doc
+      ensure
+        restore_idprefix ? (attrs['idprefix'] = restore_idprefix) : (attrs.delete 'idprefix')
+      end
+
+      def list_item_supports_id? doc
+        if (converter = doc.converter).instance_variable_defined? :@list_item_supports_id
+          converter.instance_variable_get :@list_item_supports_id
+        else
+          output = (create_list doc, :ulist).tap {|ul| ul << (create_list_item ul).tap {|li| li.id = 'name' } }.convert
+          converter.instance_variable_set :@list_item_supports_id, (output.include? ' id="name"')
+        end
       end
     end
   end

data/lib/asciidoctor/tabs/docinfo.rb

@@ -15,10 +15,15 @@ module Asciidoctor
         use_dsl
         at_location :head
 
-        STYLESHEET_FILE = ::File.join DATA_DIR, 'css/tabs.css'
+        DEFAULT_STYLESHEET_FILE = ::File.join DATA_DIR, 'css/tabs.css'
 
-        def process _doc
-          %(<style>\n#{(::File.read STYLESHEET_FILE, mode: FILE_READ_MODE).chomp}\n</style>)
+        def process doc
+          return unless (path = doc.attr 'tabs-stylesheet')
+          styles = path.empty? ?
+            (::File.read DEFAULT_STYLESHEET_FILE, mode: FILE_READ_MODE) :
+            (doc.read_contents path, start: (doc.attr 'stylesdir'), warn_on_failure: true, label: 'tabs stylesheet')
+          return unless styles
+          %(<style>\n#{styles.chomp}\n</style>)
         end
       end
 

data/lib/asciidoctor/tabs/extensions.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
-require_relative 'block'
-require_relative 'docinfo'
+unless RUBY_ENGINE == 'opal'
+  require_relative 'block'
+  require_relative 'docinfo'
+end
 
 module Asciidoctor
   module Tabs
@@ -11,8 +13,14 @@ module Asciidoctor
       def group
         proc do
           block Block, :tabs
+          next if (doc = @document).embedded? || !(doc.attr? 'filetype', 'html')
+          unless (doc.attribute_locked? 'tabs-stylesheet') ||
+              ((doc.options[:attributes] || {}).transform_keys {|it| it.delete '@!' }.key? 'tabs-stylesheet')
+            doc.set_attr 'tabs-stylesheet'
+          end
           docinfo_processor Docinfo::Styles
           docinfo_processor Docinfo::Behavior
+          nil
         end
       end
 
@@ -20,12 +28,13 @@ module Asciidoctor
         :tabs
       end
 
-      def register
-        ::Asciidoctor::Extensions.register key, &group
+      def register registry = nil
+        (registry || ::Asciidoctor::Extensions).groups[key] ||= group
       end
 
-      def unregister
-        ::Asciidoctor::Extensions.groups.delete key
+      def unregister registry = nil
+        (registry || ::Asciidoctor::Extensions).groups.delete key
+        nil
       end
     end
   end

data/lib/asciidoctor/tabs/version.rb

@@ -2,6 +2,6 @@
 
 module Asciidoctor
   module Tabs
-    VERSION = '1.0.0.alpha.1'
+    VERSION = '1.0.0.alpha.3'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: asciidoctor-tabs
 version: !ruby/object:Gem::Version
-  version: 1.0.0.alpha.1
+  version: 1.0.0.alpha.3
 platform: ruby
 authors:
 - Dan Allen
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-10-01 00:00:00.000000000 Z
+date: 2022-10-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asciidoctor