asciidoctor-tabs 1.0.0.beta.4 → 1.0.0.beta.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e73997158c47ea046d9c2016a25cac989e0f0e12e013bdc17f0c3cde8128e55f
-  data.tar.gz: 2dd6e9907c7c2498c1ff2226f25d00d654b872644063b02230882a2090f35e45
+  metadata.gz: d453d4bfdf6f6b92e7a098908890fb85643aaee9d4fde38bd94aeae1f9576139
+  data.tar.gz: 7a6d50452588a2785e201fd76aa7cd6b61294f507456ad10aeb2fab76e97b1fc
 SHA512:
-  metadata.gz: d530e0bb402fd7aa9346c5dc747efe5224436ef8d2e1fd4139a64fb84ed3f3c044069ba0fb807f12ecfe78104d6665395d979aeb1aac77465cef6bb831b1e0ad
-  data.tar.gz: c1c756f94280e8d70394c13abdfeb541f226b5eb39cfe86b514211781e5ab80bf1208e7faad6162db45571b26801ada288ae656143d074a7184ba40674afac32
+  metadata.gz: 4697b8dd5e29a82a88d2102cc9d983568416c8a4d14dbb54469e4f343fd1d0311c0d77e65ee4cecb2cd5446a4bb4431b6831b9a36d35927f1391e5125ac6b7da
+  data.tar.gz: 7ee4072275cf65f19d34715714e51e52d767830a278dd133b6eb9663a9c81c3f89f3eb9acbc4177562f65c6c6c3e5170547ba51f1991ff218d03b8e4226e0ec9

data/CHANGELOG.adoc

@@ -4,6 +4,34 @@
 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-beta.6 (2023-08-01) - @mojavelinux
+
+=== Changed
+
+* Repurpose example block as open block if filetype is not html
+
+=== Fixed
+
+* Preserve attribute entries above tabs block (#64)
+
+=== Details
+
+{url-repo}/releases/tag/v1.0.0-beta.6[git tag] | {url-repo}/compare/v1.0.0-beta.5\...v1.0.0-beta.6[full diff]
+
+== 1.0.0-beta.5 (2023-05-28) - @mojavelinux
+
+=== Changed
+
+* Ensure tab number sequence follows document order when tabs blocks are nested (#61)
+
+=== Fixed
+
+* Only remove open block enclosure around tab content if it is anonymous; preserve nested tabs block (#59)
+
+=== Details
+
+{url-repo}/releases/tag/v1.0.0-beta.5[git tag] | {url-repo}/compare/v1.0.0-beta.4\...v1.0.0-beta.5[full diff]
+
 == 1.0.0-beta.4 (2023-05-22) - @mojavelinux
 
 === Changed

data/README.adoc

@@ -1,6 +1,6 @@
 = Asciidoctor Tabs
 Dan Allen <https://github.com/mojavelinux[@mojavelinux]>
-v1.0.0-beta.4, 2023-05-22
+v1.0.0-beta.6, 2023-08-01
 :idprefix:
 :idseparator: -
 ifndef::env-github[:icons: font]
@@ -12,14 +12,14 @@ endif::[]
 An Asciidoctor extension that adds a tabs block to the AsciiDoc syntax.
 
 NOTE: This extension is intended to be used with HTML backends (e.g., `html5`).
-For all other backends (i.e., the filetype is not html), the custom block enclosure is taken away and its contents (a dlist) is converted normally.
+For all other backends (i.e., the filetype is not html), the custom block enclosure is discarded and its contents (a dlist) is converted normally.
 
 TIP: This extension is also published as an npm package named `@asciidoctor/tabs` for use with Asciidoctor.js.
 See the xref:js/README.adoc[README in the js folder] for details.
 
 == Overview
 
-Each set of tabs (aka a "`tabset`" or tabs block) is constructed from a description list (dlist) enclosed in an example block marked with the tabs style (i.e., `[tab]`).
+Each set of tabs (i.e., a "`tabset`" or tabs block) is constructed from a description list (dlist) enclosed in an example block annotated with the tabs style (i.e., `[tab]`).
 That nested combination of blocks gets translated by this extension into a single tabs block that is a specialization of an open block.
 
 The tabbed interface produced from this block can help organize information by code language, operating system, or product variant.
@@ -57,37 +57,38 @@ Then use Bundler to install the gem:
 
 == Syntax
 
-A tabset is defined using a description list (dlist) enclosed in an example block marked with the tabs style.
+A tabset is defined using a description list (dlist) enclosed in an example block annotated with the tabs style.
 
-.document-with-tabs.adoc
+.tabs.adoc
 [,asciidoc]
 ----
 [tabs]
 ====
-Tab A:: Contents of tab A.
+Tab A:: Contents of Tab A.
 
 Tab B::
 +
-Contents of tab B.
+Contents of Tab B.
 
 Tab C::
 +
 --
-Contents of tab C.
+Contents of Tab C.
 
 Contains more than one block.
 --
 ====
 ----
 
-The tabbed content is modeled as a dlist.
+The tabs themselves are modeled as a dlist.
 Each item in the dlist becomes a separate tab.
 The term is used as the tab's label and the description is used as the tab's contents.
 The contents can be defined as primary text, attached blocks, or both.
-If the attached blocks are themselves enclosed in a single open block, the open block enclosure itself is discarded upon conversion.
+If the tab has a single attached block, and that block is an open block with no attributes, the open block enclosure itself is discarded upon conversion.
 
 You may choose to extend the block delimiter length from the typical 4 characters to 6 in order to avoid conflicts with any example blocks inside the tabs block (or just as a matter of style).
 
+.tab-with-example-block.adoc
 [,asciidoc]
 ----
 [tabs]
@@ -102,52 +103,172 @@ Tab B:: Just text.
 ======
 ----
 
+Using this technique, you can also create nested tabsets.
+
+.tab-with-nested-tabs.adoc
+[,asciidoc]
+----
+[tabs]
+======
+Tab A::
++
+Selecting Tab A reveals a tabset with Tab Y and Tab Z.
++
+[tabs]
+====
+Tab Y:: Contents of Tab Y, nested inside Tab A.
+Tab Z:: Contents of Tab Z, nested inside Tab A.
+====
+
+Tab B:: Just text.
+======
+----
+
 == Tabs Sync
 
-If you want to synchronize the tab selection across tabsets, set the `tabs-sync-option` on the document.
+If you want to synchronize (i.e., sync) the tab selection across tabsets, set the `tabs-sync-option` on the document.
 
-.document-with-tabs-sync.adoc
+.tabs-sync.adoc
 [,asciidoc]
 ----
 :tabs-sync-option:
 
 [tabs]
 ====
-Tab A:: Contents of tab A in first tabset.
-Tab B:: Contents of tab B in first tabset.
+Tab A:: Triggers selection of Tab A in other congruent tabsets.
+Tab B:: Triggers selection of Tab B in other congruent tabsets.
 ====
 
 ...
 
 [tabs]
 ====
-Tab A:: Contents of tab A in second tabset.
-Tab B:: Contents of tab B in second tabset.
+Tab A:: Triggers selection of Tab A in other congruent tabsets.
+Tab B:: Triggers selection of Tab B in other congruent tabsets.
+====
+----
+
+Only tabsets that have the same sync group ID are synchronized.
+By default, the sync group ID is computed by taking the text of each tab, sorting that list, and joining it on `|` (e.g., `A|B`).
+Each unique combination of tabs--or congruent tablist--implicitly creates a new sync group.
+
+You can override the sync group ID of a tabset using the `sync-group-id` attribute on the block.
+This allows you to control the scope of the sync or to force a tabset to participate in a sync group even if its not congruent.
+
+.tabs-with-custom-sync-groups.adoc
+[,asciidoc]
+----
+:tabs-sync-option:
+
+[tabs,sync-group-id=group-1]
+====
+Tab A:: Triggers selection of Tab A in second tabset.
+Tab B:: Triggers selection of Tab B in second tabset.
+====
+
+[tabs,sync-group-id=group-1]
+====
+Tab A:: Triggers selection of Tab A in first tabset.
+Tab B:: Triggers selection of Tab B in first tabset.
+====
+
+[tabs,sync-group-id=group-2]
+====
+Tab A:: Triggers selection of Tab A in fourth tabset.
+Tab B:: Triggers selection of Tab B in fourth tabset.
+====
+
+[tabs,sync-group-id=group-2]
+====
+Tab A:: Triggers selection of Tab A in third tabset.
+Tab B:: Triggers selection of Tab B in third tabset.
 ====
 ----
 
-Only tabs blocks with congruent tablists are synchronized by default.
-Each unique combination of tabs implicitly creates a new sync group.
-You can override the sync group ID using the `sync-group-id` attribute on a tabs block to force it to participate in a sync group.
-By default, the sync group ID is derived from the text of each tab, sorted, then joined on `|` (e.g., `A|B`).
+Instead of enabling tabs sync globally, you can set the `sync` option on individual tabs blocks.
 
-Alternately, you can set the `sync` option on each tabs block.
-If you want to delist a tabs block from sync, set the `nosync` option on that block.
+.tabs-with-sync-option.adoc
+[,asciidoc]
+----
+[tabs%sync]
+====
+Tab A:: Triggers selection of Tab A in third tabset.
+Tab B:: Triggers selection of Tab B in third tabset.
+====
+
+[tabs]
+====
+Tab A:: Does not trigger selection of Tab A in other tabsets.
+Tab B:: Does not trigger selection of Tab B in other tabsets.
+====
+
+[tabs%sync]
+====
+Tab A:: Triggers selection of Tab A in first tabset.
+Tab B:: Triggers selection of Tab B in first tabset.
+====
+----
+
+Conversely, if you want to delist a tabs block from the global sync, set the `nosync` option on that block.
+
+.tabs-with-nosync-option.adoc
+[,asciidoc]
+----
+:tabs-sync-option:
+
+[tabs]
+====
+Tab A:: Triggers selection of Tab A in third tabset.
+Tab B:: Triggers selection of Tab B in third tabset.
+====
+
+[tabs%nosync]
+====
+Tab A:: Does not trigger selection of Tab A in other tabsets.
+Tab B:: Does not trigger selection of Tab B in other tabsets.
+====
+
+[tabs]
+====
+Tab A:: Triggers selection of Tab A in first tabset.
+Tab B:: Triggers selection of Tab B in first tabset.
+====
+----
 
 If you want to persist the sync selection, assign a value to the `data-sync-storage-key` attribute on the `<script>` tag.
-By default, the sync selection will be assigned to the specified key in local storage.
-You can set the `data-sync-storage-scope` attribute on the `<script>` tag to `session` to use session storage instead.
-When using the extension on a standalone document, you can configure these options using the `tabs-sync-storage-key` and `tabs-sync-storage-scope` document attributes, respectively.
+
+[,js]
+----
+<script data-sync-storage-key="preferred-tab">
+----
+
+By default, the sync selection (per group) will be persisted to local storage (i.e., `data-sync-storage-scope="local"`) using the specified key.
+You can set the `data-sync-storage-scope` attribute on the `<script>` tag to `session` to use session storage instead of local storage.
+
+[,js]
+----
+<script data-sync-storage-key="preferred-tab" data-sync-storage-scope="session">
+----
+
+When using the extension on a standalone document (which will automatically embed the supporting script), you can configure these options using the `tabs-sync-storage-key` and `tabs-sync-storage-scope` document attributes, respectively.
+
+[,asciidoc]
+----
+:tabs-sync-storage-key: tabs
+:tabs-sync-storage-scope: session
+----
+
+In this case, the converter will set the corresponding attributes on the `<script>` tag automatically.
 
 == Usage
 
 === CLI
 
- $ asciidoctor -r asciidoctor-tabs document-with-tabs.adoc
+ $ asciidoctor -r asciidoctor-tabs tabs.adoc
 
 You can specify an alternate stylesheet for tabs using the `tabs-stylesheet` document attribute.
 
- $ asciidoctor -r asciidoctor-tabs -a tabs-stylesheet=my-tabs.css document-with-tabs.adoc
+ $ asciidoctor -r asciidoctor-tabs -a tabs-stylesheet=my-tabs.css tabs.adoc
 
 The value of the `tabs-stylesheet` 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.
@@ -164,7 +285,7 @@ You can require `asciidoctor/tabs` to register the extension as a global extensi
 require 'asciidoctor'
 require 'asciidoctor/tabs'
 
-Asciidoctor.convert_file 'document-with-tabs.adoc', safe: :safe
+Asciidoctor.convert_file 'tabs.adoc', safe: :safe
 ----
 
 Or you can pass a registry instance to the `Extensions.register` method to register the extension with a scoped registry.
@@ -177,14 +298,14 @@ 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
+Asciidoctor.convert_file 'tabs.adoc', extension_registry: registry, safe: :safe
 ----
 
 If you're not using other scoped extensions, you can pass in the extensions group without first creating a registry instance:
 
 [,js]
 ----
-Asciidoctor.convert_file 'document-with-tabs.adoc', extensions: Asciidoctor::Tabs::Extensions.group, safe: :safe
+Asciidoctor.convert_file 'tabs.adoc', extensions: Asciidoctor::Tabs::Extensions.group, safe: :safe
 ----
 
 == How it Works

data/lib/asciidoctor/tabs/block.rb

@@ -7,21 +7,20 @@ module Asciidoctor
       on_context :example
 
       def process parent, reader, attrs
+        doc = parent.document
+        return create_open_block parent, nil, attrs unless doc.attr? 'filetype', 'html'
+        tabs_number = doc.counter 'tabs-number'
         block = create_block parent, attrs['cloaked-context'], nil, attrs, content_model: :compound
         children = (parse_content block, reader).blocks
-        return block unless children.size == 1 && (seed_tabs = children[0]).context == :dlist && seed_tabs.items?
-        unless (doc = parent.document).attr? 'filetype', 'html'
-          (id = attrs['id']) && (doc.register :refs, [(seed_tabs.id = id), seed_tabs]) unless seed_tabs.id
-          (reftext = attrs['reftext']) && (seed_tabs.set_attr 'reftext', reftext) unless seed_tabs.reftext?
-          parent << seed_tabs
-          return
-        end
-        tabs_number = doc.counter 'tabs-number'
+        return (reset_counter doc, 'tabs-number', (tabs_number - 1)) || block unless children.size == 1 &&
+          (seed_tabs = children[0]).context == :dlist && seed_tabs.items?
         tabs_id = attrs['id'] || (generate_id %(tabs #{tabs_number}), doc)
         tabs_role = 'tabs' + (!(block.option? 'nosync') && ((block.option? 'sync') || (doc.option? 'tabs-sync')) ?
           ((gid = attrs['sync-group-id']) ? %( is-sync data-sync-group-id=#{gid.gsub ' ', ?\u00a0}) : ' is-sync') : '')
         tabs_role += (tabs_user_role = attrs['role']) ? %( #{tabs_user_role} is-loading) : ' is-loading'
-        (tabs = create_open_block parent, nil, { 'id' => tabs_id, 'role' => tabs_role }).title = attrs['title']
+        tabs_attrs = { 'id' => tabs_id, 'role' => tabs_role }
+        tabs_attrs[:attribute_entries] = attrs[:attribute_entries] if attrs.key? :attribute_entries
+        (tabs = create_open_block parent, nil, tabs_attrs).title = attrs['title']
         tablist = create_list parent, :ulist, { 'role' => 'tablist' }
         panes = {}
         set_id_on_tab = (doc.backend == 'html5') || (list_item_supports_id? doc)
@@ -39,7 +38,8 @@ module Asciidoctor
             tab_blocks = content.text? ?
               [(create_paragraph parent, (content.instance_variable_get :@text), nil, subs: :normal)] : []
             if content.blocks?
-              if (block0 = (blocks = content.blocks)[0]).context == :open && blocks.size == 1 && block0.blocks?
+              if (block0 = (blocks = content.blocks)[0]).context == :open && block0.style == 'open' &&
+                  blocks.size == 1 && !(block0.id || block0.title? || block0.attributes.keys.any? {|k| k != 'style' })
                 blocks = block0.blocks
               end
               tab_blocks.push(*blocks)
@@ -81,6 +81,12 @@ module Asciidoctor
           converter.instance_variable_set :@list_item_supports_id, (output.include? ' id="name"')
         end
       end
+
+      def reset_counter doc, name, val
+        doc.counters[name] = val
+        doc.set_attr name, val unless doc.attribute_locked? name
+        nil
+      end
     end
   end
 end

data/lib/asciidoctor/tabs/version.rb

@@ -2,6 +2,6 @@
 
 module Asciidoctor
   module Tabs
-    VERSION = '1.0.0.beta.4'
+    VERSION = '1.0.0.beta.6'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: asciidoctor-tabs
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta.4
+  version: 1.0.0.beta.6
 platform: ruby
 authors:
 - Dan Allen
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-05-22 00:00:00.000000000 Z
+date: 2023-08-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asciidoctor