asciidoctor-diagram-layout 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 259d60e19f11c5464595f92d72139d65650d5c9323a1be52604e576ebc07fa00
-  data.tar.gz: 3943431e97a920a3793802bd2749d74912f96eb6d9c8292e99d708345599ece5
+  metadata.gz: c49ff65f5b48299da96077abff591082253d7d235f7d04c376563722b6ef3fdd
+  data.tar.gz: 120ad77f8019c03234c9c58e7dfc10fbd6332baebb81f2ba58a83268f3a34d21
 SHA512:
-  metadata.gz: 8f02690b155ef916aab876e901ea19f3d3a987531057c28f45a8a448caa350e10420ce390a1374daf45d390edb52af3443f814469eabc219a446b51f9276d1b0
-  data.tar.gz: b9df257e16623a6107627bc55b7a4f086f276582f6abb3acecfdea0708fc581010423a3448bcdc3861abe89c03bdabe7b27be65b607bf4dab4afaddabcfd92de
+  metadata.gz: 643df3c7a743cd9f67b7c067c9e19cb251de1e4b2bc3cbdf6457985f7ced4aab41612214d084b050218562b016ffd425346b5e1c705f575cc65233962ac20847
+  data.tar.gz: 874427307fe73724a2d47b0f2010280585f10c209348366ffce5d95c5809441f0e195808c7c6a967ff8e2d519e97a0b6bd20ddffc4961a629efec9b2e16df971

data/README.md

@@ -1,7 +1,27 @@
 # asciidoctor-diagram-layout
 
-An Asciidoctor extension that adds a `[layout-rowcol]` block for
-rendering flex-based layout diagrams as HTML or SVG.
+An Asciidoctor extension for documenting UI layouts as diagrams,
+intended for describing the structure of composite views (pages, screens,
+etc.).
+
+## The problem
+
+When writing software requirements or design documents, you often need
+to describe the layout of a screen or a page: which areas exist, how
+they are positioned relative to each other, and what proportion of
+space each one occupies.
+
+The usual alternatives are screenshots, wireframe tools, or hand-drawn
+sketches - none of which live well next to the text, can be diffed in
+version control, or stay in sync as the design evolves.
+
+This extension lets you describe a layout directly in AsciiDoc source
+using a simple line-oriented DSL.
+The same source serves as both a human-readable description of the
+structure and a machine-rendered visual diagram - there is no separate
+"source" and "picture" to keep in sync.
+The diagram is rendered as HTML (for web output) or SVG (for PDF and
+other backends) without any external tools.
 
 ## Installation
 
@@ -19,71 +39,229 @@ gem install asciidoctor-diagram-layout
 
 ## Usage
 
-Register the extension and use the `[layout-rowcol]` block in your
-AsciiDoc documents:
+Pass `-r asciidoctor-diagram-layout` to the Asciidoctor CLI:
 
-```ruby
-require "asciidoctor"
-require "asciidoctor-diagram-layout"
+```
+asciidoctor -r asciidoctor-diagram-layout doc.adoc
+```
+
+### Running from source
+
+```
+bundle exec asciidoctor -r asciidoctor-diagram-layout doc.adoc
+```
+
+## Development
+
+Install dependencies:
+
+```
+bundle install
+```
+
+Run tests:
+
+```
+bundle exec rake spec
+```
+
+Build the gem:
+
+```
+bundle exec rake build
+```
+
+### Releasing a new version
+
+1. Update the version in `lib/asciidoctor_diagram_layout/version.rb`
+2. Update `CHANGELOG.md`
+3. Commit: `git commit -m "Release x.y.z"`
+4. Tag: `git tag vx.y.z`
+5. Push: `git push origin vx.y.z`
+
+Requires `RUBYGEMS_API_KEY` secret configured in the repository settings.
+
+**Locally** - build, tag, and publish in one command:
+
+```
+bundle exec rake release
+```
+
+Requires rubygems.org credentials (`gem signin`).
+
+## Examples
+
+
+### Single column layout
+
+The simplest case: a vertical stack of areas.
+Top-level cells without an explicit container are stacked
+vertically by default.
+
+```asciidoc
+[layout-rowcol, width="400px", height="200px"]
+----
+cell: Header
+cell: Content
+cell: Footer
+----
+```
+
+![](examples/single-column.svg)
+
+### Fixed-size header and footer
+
+A number in parentheses sets the size as a percentage of the
+parent.
+The remaining space is distributed equally among auto-sized
+cells.
+
+```asciidoc
+[layout-rowcol, width="400px", height="200px"]
+----
+cell(20): Header
+cell: Content
+cell(20): Footer
+----
+```
+
+![](examples/fixed-size.svg)
+
+### Two-column layout with a sidebar
 
-Asciidoctor::Extensions.register do
-  block AsciidoctorDiagramLayout::Asciidoc::LayoutBlockProcessor
-end
+```asciidoc
+[layout-rowcol, width="400px", height="200px"]
+----
+cols:
+  cell(25): Sidebar
+  cell: Content
+----
+```
+
+![](examples/sidebar.svg)
+
+### Classic page layout
+
+A header and footer at fixed height, with a sidebar and main
+content area in between.
+
+```asciidoc
+[layout-rowcol, width="400px", height="250px"]
+----
+cell(20): Header
+cols:
+  cell(25): Sidebar
+  cell: Content
+cell(20): Footer
+----
 ```
 
-### Basic example
+![](examples/classic-page.svg)
+
+### Dashboard with nested sections
+
+Nesting `rows:` and `cols:` containers produces complex grids.
+
+```asciidoc
+[layout-rowcol, width="600px", height="350px"]
+----
+cell(10): Toolbar
+cols:
+  cell(20): Navigation
+  rows:
+    cell(30): Hero
+    cols:
+      cell: Features
+      cell: Pricing
+      cell: Testimonials
+    cell: Call to Action
+cell(8): Footer
+----
+```
+
+![](examples/dashboard.svg)
+
+### Referencing document sections
+
+Cell names support AsciiDoc `xref:` macros.
+The cross-reference is preserved in HTML output and stripped to the
+display label in SVG output.
 
 ```asciidoc
 [layout-rowcol]
 ----
+cell(10): xref:header[Header]
 cols:
-    cell(30): Sidebar
-    rows:
-        cell: Header
-        cell: Content
+  cell(25): xref:sidebar[Sidebar]
+  cell: xref:content[Content]
+cell(10): xref:footer[Footer]
 ----
 ```
 
-### DSL syntax
+### Color palettes
 
-Each line declares one node. Indentation (4 spaces or one tab) defines
-nesting.
+The `palette` attribute controls the color scheme.
+Available values: `rainbow` (default), `warm`, `cool`, `mono`, `pastel`.
 
-* `cols:` - container that arranges children horizontally
-* `rows:` - container that arranges children vertically
-* `cell: Name` - leaf cell with a visible label
-* `cell(30): Name` - leaf cell with a fixed size of 30% of its parent
-* Containers without an explicit size take equal shares of the remaining
-  space
-* Lines starting with `#` are comments
+`warm`:
 
-### Block attributes
+![](examples/palette-warm.svg)
 
-* `direction` - implicit direction for top-level cells when no container
-  is declared: `rows` (default) or `cols`
-* `renderer` - force output format: `html` or `svg`; defaults to `html`
-  for HTML backends and `svg` for all others including PDF
-* `palette` - color scheme: `rainbow` (default), `pastel`, `warm`,
-  `cool`, `mono`
-* `width` - diagram width, e.g. `100%` (default) or `800px`
-* `height` - diagram height, e.g. `400px`; not set by default
-* `target` - SVG file name (without extension) when rendering to PDF
+`cool`:
+
+![](examples/palette-cool.svg)
+
+`mono`:
+
+![](examples/palette-mono.svg)
+
+`pastel`:
+
+![](examples/palette-pastel.svg)
 
 ### PDF output
 
-When converting to PDF, the extension writes the diagram as an SVG file
-and embeds it as an image block.
-Use the `target` attribute to control the output file name:
+When converting to PDF the diagram is written as an SVG file and
+embedded as an image.
+Use the `target` attribute to set the output file name:
 
 ```asciidoc
-[layout-rowcol, target="my-diagram"]
+[layout-rowcol, target="page-layout"]
 ----
-cols:
-    cell: Left
-    cell: Right
+cell(10): Header
+cell: Content
+cell(10): Footer
 ----
 ```
 
+## DSL syntax
+
+Each line declares one node.
+Indentation (4 spaces or one tab) defines nesting.
+
+* `rows:` - container that arranges children vertically
+* `cols:` - container that arranges children horizontally
+* `cell: Name` - leaf cell with a visible label
+* `cell(N): Name` - leaf cell with a fixed size of N% of its parent
+* Containers and cells without an explicit size share the remaining
+  space equally
+* Top-level nodes without an explicit container are wrapped in a
+  vertical (`rows`) container by default
+* Lines starting with `#` are comments
+
+## Block attributes
+
+* `direction` - implicit direction when no top-level container is
+  declared: `rows` (default) or `cols`
+* `renderer` - force output format: `html` or `svg`; defaults to
+  `html` for HTML backends and `svg` for all others including PDF
+* `palette` - color scheme: `rainbow` (default), `pastel`, `warm`,
+  `cool`, `mono`
+* `width` - diagram width, e.g. `100%` (default) or `800px`
+* `height` - diagram height, e.g. `400px`; not set by default
+* `target` - SVG file name without extension, used when rendering
+  to PDF
+
 ## License
 
 Apache License 2.0.

data/lib/asciidoctor_diagram_layout/asciidoc/layout_block_processor.rb

@@ -7,26 +7,28 @@ module AsciidoctorDiagramLayout
       use_dsl
       named :"layout-rowcol"
       on_contexts :listing, :literal
+      name_positional_attributes "target"
 
       def process(parent, reader, attrs)
-        dsl               = reader.read
-        implicit_dir      = attrs["direction"] == "cols" ? :cols : :rows
-        root              = Parser.new.parse(dsl, implicit_dir)
-        backend           = parent.document.attr("backend").to_s
-        renderer_attr     = attrs["renderer"]
-        strategy          = resolve_strategy(renderer_attr, backend)
-        palette           = attrs.fetch("palette", "rainbow")
-        pdf               = backend == "pdf"
-        options           = Renderer::RenderOptions.new(
+        dsl           = reader.read
+        implicit_dir  = attrs["direction"] == "cols" ? :cols : :rows
+        root          = Parser.new.parse(dsl, implicit_dir)
+        backend       = parent.document.attr("backend").to_s
+        strategy      = resolve_strategy(attrs["renderer"], backend)
+        palette       = attrs.fetch("palette", "rainbow")
+        pdf           = backend == "pdf"
+        title         = attrs["title"]
+        options       = Renderer::RenderOptions.new(
           width:          attrs.fetch("width", "100%"),
           height:         attrs["height"],
+          title:          title,
           palette:        palette,
           pdf:            pdf,
-          name_converter: method(:identity)
+          name_converter: ->(name) { convert_inline(parent, name) }
         )
         case strategy
         when :html then render_html(parent, root, options)
-        when :svg  then render_svg(parent, root, backend, options, attrs)
+        when :svg  then render_svg(parent, root, backend, options, attrs, title)
         end
       end
 
@@ -49,16 +51,17 @@ module AsciidoctorDiagramLayout
         create_pass_block(parent, html, {}, subs: nil)
       end
 
-      def render_svg(parent, root, backend, options, attrs)
-        svg = Renderer::SvgRenderer.new.render(root, options)
-        if backend == "pdf"
-          target = attrs["target"]
-          outdir = parent.document.attr("outdir").to_s
-          path   = write_svg(svg, target, outdir)
-          create_image_block(parent, { "target" => path, "format" => "svg" })
-        else
-          create_pass_block(parent, svg, {}, subs: nil)
-        end
+      def render_svg(parent, root, backend, options, attrs, title)
+        svg    = Renderer::SvgRenderer.new.render(root, options)
+        target = attrs["target"]
+        outdir = parent.document.attr("outdir").to_s
+        path   = write_svg(svg, target, outdir)
+        filename = File.basename(path)
+        parent.document.register(:images, filename)
+        img_target = backend == "pdf" ? File.expand_path(path) : filename
+        block = create_image_block(parent, { "target" => img_target, "format" => "svg" })
+        block.title = title if title && !title.empty?
+        block
       end
 
       def write_svg(svg, name, outdir)
@@ -75,8 +78,9 @@ module AsciidoctorDiagramLayout
         path
       end
 
-      def identity(text)
-        text
+      def convert_inline(node, text)
+        escaped  = node.sub_specialchars(text)
+        node.sub_macros(escaped)
       end
     end
   end

data/lib/asciidoctor_diagram_layout/renderer/html_renderer.rb

@@ -13,7 +13,12 @@ module AsciidoctorDiagramLayout
         sb << "<div style=\"#{wrapper_style}\">\n"
         render_node(root, sb, 1, options)
         sb << "</div>\n"
-        sb
+        if options.title && !options.title.empty?
+          "<div class=\"imageblock\">\n<div class=\"content\">\n#{sb}</div>\n" \
+          "<div class=\"title\">#{options.title}</div>\n</div>"
+        else
+          sb
+        end
       end
 
       private

data/lib/asciidoctor_diagram_layout/renderer/render_options.rb

@@ -1,12 +1,13 @@
 module AsciidoctorDiagramLayout
   module Renderer
     class RenderOptions
-      attr_reader :width, :height, :color_scheme, :name_converter
+      attr_reader :width, :height, :title, :color_scheme, :name_converter
 
-      def initialize(width: "100%", height: nil, palette: "rainbow", pdf: false,
+      def initialize(width: "100%", height: nil, title: nil, palette: "rainbow", pdf: false,
                      color_scheme: nil, name_converter: nil)
         @width          = width
         @height         = height
+        @title          = title
         @color_scheme   = color_scheme || Scheme::CellColorSchemeFactory.resolve(palette, pdf: pdf)
         @name_converter = name_converter || method(:escape)
       end

data/lib/asciidoctor_diagram_layout/renderer/svg_renderer.rb

@@ -17,6 +17,9 @@ module AsciidoctorDiagramLayout
         sb << " height=\"#{h}\""
         sb << " style=\"font-family:sans-serif;\""
         sb << ">\n"
+        if options.title && !options.title.empty?
+          sb << "  <title>#{escape_xml(options.title)}</title>\n"
+        end
         if defs.length > 0
           sb << "  <defs>\n" << defs << "  </defs>\n"
         end

data/lib/asciidoctor_diagram_layout/version.rb

@@ -1,3 +1,3 @@
 module AsciidoctorDiagramLayout
-  VERSION = "1.0.1"
+  VERSION = "1.1.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asciidoctor-diagram-layout
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Anton Pechinsky
@@ -13,14 +13,14 @@ dependencies:
   name: asciidoctor
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
 - !ruby/object:Gem::Dependency
@@ -37,6 +37,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: erb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Provides a [layout] block for Asciidoctor that renders layout diagrams
   as HTML or SVG.
 email: anton@pechinsky.com
@@ -69,7 +97,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="