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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6224fd054576b98130cb17fff445018029d8c3271cc4747ff00c112e513bb42
-  data.tar.gz: 1f1f618257e63009b54fc7d3fd11fd41bc490fc96c089fae0de75f6b74bb4239
+  metadata.gz: 9a220a5fcabda931f52d5ca7d6fbf4b3c459eb258c6694288cd147b5db58f68b
+  data.tar.gz: 20b389528d89b8e450e06dedfc0e9dc4944c9672854a12469b4e15189dfd8868
 SHA512:
-  metadata.gz: 96ac2018cfaa5c8d0ee23c87c306cc64d0f67b76100d623816166ea1a09f9a9c1939503111717616dc2f062efe3d13bffe3469d88570011de18ff9a9c7ea6b82
-  data.tar.gz: 97b9ab0a22a0ffa2eadec746d963c91b5a9c60d274bb088e82ef3224f55116ec5353706601765c1d858c45a364b2e8d5ff3a9d61a51e8034d9b78a80f64b4cb8
+  metadata.gz: 641e2de8bba5626ba461fca9b5b212769bf4175724d02f6fc56d2f891395dffdd9072aa65224530fc0ec26e84d35ff21026097aa0f57a37d7e81a957dbf14c6d
+  data.tar.gz: 5d723e02e0b9a4255715ee4daae0502900a1598e804dbf08801dd9e7acc91a78e2c3b9451a95a4b1d1d6a1060e41ef2c91d6527c3b3e278940f8b27045f41d0a

data/CHANGELOG.adoc

@@ -4,6 +4,48 @@
 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.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
+
+* Define exports for behavior (tabs.js) and style (tabs.css) in npm package
+
+=== Changed
+
+* Use value of `idseparator` attribute in front of tabset number in auto-generated ID (#16)
+* Add aliases for `Block` and `Docinfo` classes to `Extensions` class; remove workaround in js module
+* Move `margin-bottom` style to tabset element
+* Move behavior (tabs.js) and style (tabs.css) to dist folder in npm package
+
+=== Fixed
+
+* Increase specificity of sibling selector for tab to work with Antora default UI
+
+=== Details
+
+{url-repo}/releases/tag/v1.0.0-alpha.4[git tag] | {url-repo}/compare/v1.0.0-alpha.3\...v1.0.0-alpha.4[full diff]
+
 == 1.0.0-alpha.3 (2022-10-05) - @mojavelinux
 
 === Added
@@ -18,6 +60,7 @@ For a detailed view of what has changed, refer to the {url-repo}/commits/main[co
 
 === Fixed
 
+* Preserve text of dlist item for tab if item has both text and blocks (#13)
 * Create empty pane instead of crashing if dlist item has term only / no description
 
 === Details
@@ -40,7 +83,6 @@ For a detailed view of what has changed, refer to the {url-repo}/commits/main[co
 
 === 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)

data/README.adoc

@@ -1,18 +1,28 @@
 = Asciidoctor Tabs
 Dan Allen <https://github.com/mojavelinux[@mojavelinux]>
-v1.0.0-alpha.3, 2022-10-05
+v1.0.0-alpha.5, 2022-10-23
 :idprefix:
 :idseparator: -
 ifndef::env-github[:icons: font]
 ifdef::env-github[]
 :note-caption: :paperclip:
+:tip-caption: :bulb:
 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
 
@@ -32,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
 
@@ -45,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]
@@ -73,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
@@ -80,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.
@@ -113,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/css/tabs.css

@@ -1,4 +1,4 @@
-/*! Asciidoctor Tabs stylesheet | Copyright (c) 2018-present Dan Allen | MIT License */
+/*! Asciidoctor Tabs | Copyright (c) 2018-present Dan Allen | MIT License */
 .tabs > ul {
   display: flex;
   flex-wrap: wrap;
@@ -25,10 +25,14 @@
   margin-bottom: 0;
 }
 
-.tabs > ul li + li {
+.tabs > ul li + li[id] {
   margin-top: 0;
 }
 
+.tabset {
+  margin-bottom: 1.25em;
+}
+
 .tabset.is-loading .tabs li:not(:first-child),
 .tabset:not(.is-loading) .tabs li:not(.is-active) {
   background-color: black;
@@ -50,7 +54,6 @@
 .tabset > .content {
   border: 1px solid gray;
   padding: 1.25em;
-  margin-bottom: 1.25em;
 }
 
 .tabset.is-loading .tab-pane:not(:first-child),

data/data/js/tabs.js

@@ -1,4 +1,4 @@
-/*! Asciidoctor Tabs behavior | Copyright (c) 2018-present Dan Allen | MIT License */
+/*! Asciidoctor Tabs | Copyright (c) 2018-present Dan Allen | MIT License */
 ;(function () {
   'use strict'
 

data/lib/asciidoctor/tabs/block.rb

@@ -11,35 +11,34 @@ 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#{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">))
         (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
+            tab_id = generate_id tab.text, doc, tabs_id
             set_id_on_tab ? (tab.id = tab_id) : (tab.text = %([[#{tab_id}]]#{tab.instance_variable_get :@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">')
@@ -49,7 +48,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
@@ -58,12 +57,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,14 +4,12 @@ module Asciidoctor
   module Tabs
     module Docinfo
       if RUBY_ENGINE == 'opal'
-        DATA_DIR = ::File.absolute_path '../data', %x(__dirname)
-        FILE_READ_MODE = 'r'
+        DATA_DIR = ::File.absolute_path '../dist', %x(__dirname)
       else
         DATA_DIR = ::File.join (::File.absolute_path '../../..', __dir__), 'data'
-        FILE_READ_MODE = 'rb:utf-8:utf-8'
       end
 
-      class Styles < ::Asciidoctor::Extensions::DocinfoProcessor
+      class Style < ::Asciidoctor::Extensions::DocinfoProcessor
         use_dsl
         at_location :head
 
@@ -19,11 +17,14 @@ module Asciidoctor
 
         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>)
+          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
 
@@ -33,8 +34,13 @@ module Asciidoctor
 
         JAVASCRIPT_FILE = ::File.join DATA_DIR, 'js/tabs.js'
 
-        def process _doc
-          %(<script>\n#{(::File.read JAVASCRIPT_FILE, mode: FILE_READ_MODE).chomp}\n</script>)
+        def process doc
+          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

@@ -8,6 +8,9 @@ end
 module Asciidoctor
   module Tabs
     module Extensions
+      const_set :Block, Block
+      const_set :Docinfo, Docinfo
+
       module_function
 
       def group
@@ -18,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.3'
+    VERSION = '1.0.0.alpha.5'
   end
 end

metadata

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