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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e968b72b74144aad60adceb6290712b43017a61b74cc80c73793f474473e59c3
-  data.tar.gz: c7a33865929a61775548be25bda28627c6d9687e68e5d498134d3d87a4eef82b
+  metadata.gz: fd23b52dcb671b18e2fc149ff7c4c0f131acc7b36c5a83df0003c22cc341d8cd
+  data.tar.gz: 502e57c0df6a007731a21dce2f382f54ea3e940c6548e914e91aab25d233a995
 SHA512:
-  metadata.gz: afdc6a70cec6b9a9519a9f8d72a29e234099ab3b58ed0cceabdcfff3a14574ad905214af88b6c32ffa527994607d30d3ed66403c22f4c60442cd318fd2f9dc7c
-  data.tar.gz: d09843fadb14ddee7d2fa5baf42e0125faeebe6342f7428175100ad7d0401cb6d8693045d51dfe53225e637849cefd15085ca7c7d52ec94f847d3949fc31e2a4
+  metadata.gz: 41ddf35603690caa50d3685eb398ebbfd65ecc13630827731ec11493667a2bcd4db8616e530ae11cb8f05fa450d258b9e734ad4ee10fbe1bcaaf1c256ee681e7
+  data.tar.gz: ac3f2b5a3d44a8209436955dd5ebb74eff9e2bfbc0f107e572488859de78cb133817db3c5362c09198aee71b9381dfa56646e036ebd885b5cf05231b23231a7b

data/CHANGELOG.adoc

@@ -4,6 +4,44 @@
 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.6 (2022-11-16) - @mojavelinux
+
+=== Added
+
+* Honor title on tabs block; apply normal subs to it (#26)
+* Clear location hash (URL fragment) when a tab is clicked (#24)
+* Register ref for each tab so its ID can be used as target of xref (#24)
+* Activate tab when selected from an internal xref (#24)
+
+=== Fixed
+
+* Decode fragment from URL so it can be matched against tab ID (#27)
+
+=== Details
+
+{url-repo}/releases/tag/v1.0.0-alpha.6[git tag] | {url-repo}/compare/v1.0.0-alpha.5\...v1.0.0-alpha.6[full diff]
+
+== 1.0.0-alpha.5 (2022-10-23) - @mojavelinux
+
+=== Added
+
+* Link to stylesheet (style) and script (behavior) if `linkcss` attribute is set on document (#7)
+* Honor safe mode settings (don't read files if safe mode is secure) (#7)
+
+=== Changed
+
+* Rename Docinfo::Styles class to Docinfo::Style (#22)
+* Add smoke test for npm package (#19)
+
+=== Fixed
+
+* Prevent dlist ref from being registered again to avoid warning when filetype is not html (#21)
+* Restore missing default style and behavior in JavaScript version by mapping data dir to dist folder in npm package (#18)
+
+=== Details
+
+{url-repo}/releases/tag/v1.0.0-alpha.5[git tag] | {url-repo}/compare/v1.0.0-alpha.4\...v1.0.0-alpha.5[full diff]
+
 == 1.0.0-alpha.4 (2022-10-08) - @mojavelinux
 
 === Added

data/README.adoc

@@ -1,6 +1,6 @@
 = Asciidoctor Tabs
 Dan Allen <https://github.com/mojavelinux[@mojavelinux]>
-v1.0.0-alpha.4, 2022-10-08
+v1.0.0-alpha.6, 2022-11-16
 :idprefix:
 :idseparator: -
 ifndef::env-github[:icons: font]
@@ -10,13 +10,20 @@ ifdef::env-github[]
 endif::[]
 
 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.
+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.
 
 TIP: This extension is also published as an npm package named `@asciidoctor/tabs` for use with Asciidoctor.js (and thus Antora).
 
+== Overview
+
+Each set of tabs (a "`tabset`") is constructed from a description list (dlist) enclosed in an example block marked with the tabs style (i.e., `[tab]`).
+The tabbed interface that this block produces can help to organize information by code language, operating system, or product variant.
+
+The benefit of organizing information in this way is that it condenses the use of vertical space by only showing what's relevant to the reader (and thus hiding information that's irrelevant or redundant).
+The result is that readers enjoy a better user experience when reading your documentation.
+
 == Install
 
 === Using gem command
@@ -35,10 +42,10 @@ source 'https://rubygems.org'
 gem 'asciidoctor-tabs'
 
 # or use the code directlly from GitHub
-# gem 'asciidoctor-tabs', github: 'asciidoctor/asciidoctor-pdf'
+# gem 'asciidoctor-tabs', github: 'asciidoctor/asciidoctor-tabs'
 ----
 
-Then configure Bundler to install gems locally (optional):
+Then optionally configure Bundler to install gems locally:
 
  $ bundle config --local path .bundle/gems
 
@@ -48,12 +55,7 @@ Then use Bundler to install the gem:
 
 == Syntax
 
-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 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.
+A tabset is defined using a description list (dlist) enclosed in an example block marked with the tabs style.
 
 .document-with-tabs.adoc
 [,asciidoc]
@@ -76,6 +78,28 @@ Contains more than one block.
 ====
 ----
 
+The tabbed content is 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.
+
+You may decide to extend the block delimiter length instead of using the typical 4 characters to avoid conflicts with any example blocks inside the tab block (or just as a manner of style).
+
+[,asciidoc]
+----
+[tabs]
+======
+Tab A::
++
+====
+Example block in Tab A.
+====
+
+Tab B:: Just text.
+======
+----
+
 == Usage
 
 === CLI
@@ -83,11 +107,12 @@ Contains more than one block.
  $ 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
 
+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.
+
 === API
 
 There are two ways to use the extension with the Asciidoctor API.
@@ -116,13 +141,35 @@ 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:
+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
 ----
 
+== How it Works
+
+This extension works by transforming the dlist inside the example block into a tabbed interface.
+The example block enclosure is discarded.
+The tabbed interface is supported by a stylesheet (style) and script (behavior) that are added to the HTML document by this extension.
+(These assets can be found in the [.path]_data_ folder of the gem).
+
+NOTE: The stylesheet and script are only added when producing a standalone document.
+The stylesheet is added to the end of the `<head>` tag and the script added to the end of the `<body>` tag.
+If the `linkcss` attribute is set by the API, the CLI, the document, or the safe mode, the HTML links to these assets.
+Otherwise, the contents of these assets are embedded into the HTML.
+
+The tabbed interface consists of two output elements.
+The first element contains an unordered list of all the tab labels in document order.
+The second element contains all the tab panes.
+The labels and panes are correlated through the use of a unique ID.
+Each tab is assigned an `id` attribute and each pane is assigned an `aria-labelledby` attribute that references the corresponding ID.
+The added stylesheet sets up the appearance of the tabbed interface and the added script supports the interaction (i.e., tab selection).
+
+A tab can be selected when the page loads using a URL fragment (e.g., `#id-of-tab-here`).
+Otherwise, the first tab is selected when the page loads.
+
 == Authors
 
 Asciidoctor Tabs was written by Dan Allen of OpenDevise Inc. and contributed to the Asciidoctor project.

data/data/js/tabs.js

@@ -2,8 +2,11 @@
 ;(function () {
   'use strict'
 
-  var hash = window.location.hash
-  find('.tabset').forEach(function (tabset) {
+  var tabsets = find('.tabset')
+  if (!tabsets.length) return
+  var fragment = decodeFragment(window.location.hash)
+
+  tabsets.forEach(function (tabset) {
     var active
     var tabs = tabset.querySelector('.tabs')
     if (tabs) {
@@ -14,7 +17,7 @@
         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)) {
+        if (!active && fragment === id && (active = true)) {
           tab.classList.add('is-active')
           if (pane) pane.classList.add('is-active')
         } else if (!idx) {
@@ -31,15 +34,36 @@
     tabset.classList.remove('is-loading')
   })
 
+  tabsets = undefined
+  window.addEventListener('hashchange', onHashChange)
+
   function activateTab (e) {
     var tab = this.tab
     var pane = this.pane
     find('.tabs li, .tab-pane', this.tabset).forEach(function (it) {
       it === tab || it === pane ? it.classList.add('is-active') : it.classList.remove('is-active')
     })
+    if (!e) return
+    var hashIdx = window.location.hash ? window.location.href.indexOf('#') : -1
+    if (~hashIdx) window.history.replaceState(null, '', window.location.href.slice(0, hashIdx))
     e.preventDefault()
   }
 
+  function decodeFragment (hash) {
+    return hash && (~hash.indexOf('%') ? decodeURIComponent(hash.slice(1)) : hash.slice(1))
+  }
+
+  function onHashChange () {
+    var id = decodeFragment(window.location.hash)
+    if (!id) return
+    var tab = document.getElementById(id)
+    if (!(tab && document.querySelector('.tabset .tabs [id="' + id + '"]'))) return
+    if (tab.tagName === 'A') tab = tab.parentNode
+    var tabset = tab.closest('.tabset')
+    var pane = tabset.querySelector('.tab-pane[aria-labelledby~="' + id + '"]')
+    activateTab.call({ tabset: tabset, tab: tab, pane: pane })
+  }
+
   function find (selector, from) {
     return Array.prototype.slice.call((from || document).querySelectorAll(selector))
   }

data/lib/asciidoctor/tabs/block.rb

@@ -11,36 +11,39 @@ module Asciidoctor
         children = (parse_content block, reader).blocks
         return block unless children.size == 1 && (source_tabs = children[0]).context == :dlist && source_tabs.items?
         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
+          (id = attrs['id']) && (doc.register :refs, [(source_tabs.id = id), source_tabs]) unless source_tabs.id
+          (reftext = attrs['reftext']) && (source_tabs.set_attr 'reftext', reftext) unless source_tabs.reftext?
+          parent << source_tabs
+          return
         end
         tabset_number = doc.counter 'tabset-number'
-        id = attrs['id'] ||
-          %(#{doc.attributes['idprefix'] || '_'}tabset#{doc.attributes['idseparator'] || '_'}#{tabset_number})
-        parent << (create_html_fragment parent, %(<div id="#{id}" class="tabset is-loading">))
+        tabs_id = attrs['id'] || (generate_id %(tabset #{tabset_number}), doc)
+        parent << (create_html_fragment parent, %(<div id="#{tabs_id}" class="tabset is-loading">))
+        if (title = attrs['title'])
+          parent << (create_html_fragment parent, %(<div class="title">#{parent.apply_subs title}</div>))
+        end
         (tabs = create_list parent, :ulist).add_role 'tabs'
         panes = {}
         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 = generate_id tab.text, doc, tabs_id
+            tab_source_text = tab.instance_variable_get :@text
+            set_id_on_tab ? (tab.id = tab_id) : (tab.text = %([[#{tab_id}]]#{tab_source_text}))
+            (doc.register :refs, [tab_id, tab]).set_attr 'reftext', tab_source_text
             tab_id
           end
           if content
-            text = create_paragraph parent, (content.instance_variable_get :@text), nil if content.text?
+            tab_blocks = content.text? ? [(create_paragraph parent, (content.instance_variable_get :@text), nil)] : []
             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]
+              tab_blocks.push(*blocks)
             end
           end
-          panes[tab_ids] = blocks || []
+          panes[tab_ids] = tab_blocks || []
         end
         parent << tabs
         parent << (create_html_fragment parent, '<div class="content">')
@@ -50,7 +53,7 @@ module Asciidoctor
           parent << (create_html_fragment parent, '</div>')
         end
         parent << (create_html_fragment parent, '</div>')
-        create_html_fragment parent, '</div>', 'id' => id
+        create_html_fragment parent, '</div>', 'id' => tabs_id
       end
 
       private
@@ -59,12 +62,14 @@ module Asciidoctor
         create_block parent, :pass, html, attributes
       end
 
-      def generate_id str, base_id, doc
-        restore_idprefix = (attrs = doc.attributes)['idprefix']
-        attrs['idprefix'] = %(#{base_id}#{attrs['idseparator'] || '_'})
+      def generate_id str, doc, base_id = nil
+        if base_id
+          restore_idprefix = (attrs = doc.attributes)['idprefix']
+          attrs['idprefix'] = %(#{base_id}#{attrs['idseparator'] || '_'})
+        end
         ::Asciidoctor::Section.generate_id str, doc
       ensure
-        restore_idprefix ? (attrs['idprefix'] = restore_idprefix) : (attrs.delete 'idprefix')
+        restore_idprefix ? (attrs['idprefix'] = restore_idprefix) : (attrs.delete 'idprefix') if base_id
       end
 
       def list_item_supports_id? doc

data/lib/asciidoctor/tabs/docinfo.rb

@@ -4,12 +4,12 @@ module Asciidoctor
   module Tabs
     module Docinfo
       if RUBY_ENGINE == 'opal'
-        DATA_DIR = ::File.absolute_path '../data', %x(__dirname)
+        DATA_DIR = ::File.absolute_path '../dist', %x(__dirname)
       else
         DATA_DIR = ::File.join (::File.absolute_path '../../..', __dir__), 'data'
       end
 
-      class Styles < ::Asciidoctor::Extensions::DocinfoProcessor
+      class Style < ::Asciidoctor::Extensions::DocinfoProcessor
         use_dsl
         at_location :head
 
@@ -17,10 +17,14 @@ module Asciidoctor
 
         def process doc
           return unless (path = doc.attr 'tabs-stylesheet')
-          return unless (styles = path.empty? ?
-            (doc.read_asset DEFAULT_STYLESHEET_FILE) :
-            (doc.read_contents path, start: (doc.attr 'stylesdir'), warn_on_failure: true, label: 'tabs stylesheet'))
-          %(<style>\n#{styles.chomp}\n</style>)
+          if doc.attr? 'linkcss'
+            href = doc.normalize_web_path (path.empty? ? 'asciidoctor-tabs.css' : path), (doc.attr 'stylesdir')
+            %(<link rel="stylesheet" href="#{href}"#{(doc.attr? 'htmlsyntax', 'xml') ? '/' : ''}>) # rubocop:disable Style/TernaryParentheses
+          elsif (styles = path.empty? ?
+              (doc.read_asset DEFAULT_STYLESHEET_FILE) :
+              (doc.read_contents path, start: (doc.attr 'stylesdir'), warn_on_failure: true, label: 'tabs stylesheet'))
+            %(<style>\n#{styles.chomp}\n</style>)
+          end
         end
       end
 
@@ -31,8 +35,12 @@ module Asciidoctor
         JAVASCRIPT_FILE = ::File.join DATA_DIR, 'js/tabs.js'
 
         def process doc
-          return unless (script = doc.read_asset JAVASCRIPT_FILE)
-          %(<script>\n#{script.chomp}\n</script>)
+          if doc.attr? 'linkcss'
+            src = doc.normalize_web_path 'asciidoctor-tabs.js', (doc.attr 'scriptsdir')
+            %(<script src="#{src}"></script>)
+          elsif (script = doc.read_asset JAVASCRIPT_FILE)
+            %(<script>\n#{script.chomp}\n</script>)
+          end
         end
       end
     end

data/lib/asciidoctor/tabs/extensions.rb

@@ -21,7 +21,7 @@ module Asciidoctor
               ((doc.options[:attributes] || {}).transform_keys {|it| it.delete '@!' }.key? 'tabs-stylesheet')
             doc.set_attr 'tabs-stylesheet'
           end
-          docinfo_processor Docinfo::Styles
+          docinfo_processor Docinfo::Style
           docinfo_processor Docinfo::Behavior
           nil
         end

data/lib/asciidoctor/tabs/version.rb

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

metadata

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