RFR: 8253117: Replace HTML tables in javadoc summaries with CSS grid elements

[Hannes Wallnöfer]

On Fri, 25 Sep 2020 17:39:20 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> This changes the output of the `html.markup.Table` class to plain `div` elements, using CSS Grid Layout to display them
>> in a tabular format.
>> I decided against renaming the Table class and related identifiers even though it does no longer emit an HTML <table>
>> element. I admit this results in a somewhat odd mismatch in a few places, but on the other hand the generated HTML
>> still represents tabular data. Also, the changes are much easier to understand and review this way. I'm open to
>> renaming things if we can find a better terminology.  I simplified the existing code in quite a few places:
>>  - Removed the setters for table tab ids and the browser tab script. The ids are now derived from the main table id which
>>    makes them unique even with multiple tables per page (provided the tables have different ids), and the browser script
>>    will always work for the used ids.
>>  
>>  - Removed the complex tab selection scheme based on bitwise operations and replaced it with one CSS class per tab. The
>>    elements making up a table row will have a CSS class for each tab they belong to. The CSS class names are derived from
>>    the table id as well.
>> 
>>  - Reduced per usage style classes for summary tables, thereby simplifying the style sheet. Instead of having a CSS class
>>    for each useage of a table (e.g. `member-summary`, `type-summary` etc) there is only one common CSS class for summary
>>    tables as well as one specifying the number of columns to use, e.g. `two-column-summary`, `three-column-summary` etc.
>> 
>> The rendering and spacing of the tables should be the same as previously. There are a few exceptions:
>> 
>>  - The style sheet has additional media queries to switch the layout of tables when the width of the browser window
>>    becomes very narrow. This happens at different thresholds for tables with two, three, or four columns. Note that these
>>    theresholds are based on heuristics, it is what I have found to work well under most circumstances.
>> 
>>  - The new grid never grow larger than the width available in the browser. When a table cell becomes too narrow to contain
>>    its content, the cell becomes scrollable. This happens very rarely and is not too disturbing IMO.
>> 
>>  - Spacing of columns is usually a bit different than previously. Grids offers very complex layout options, and the
>>    setting I came to use partitions space depending on the width of cell contents.
>> 
>> Here are the API docs for java.base rendered with these changes:
>> http://cr.openjdk.java.net/~hannesw/8253117/api.00/
>> 
>> Here are the API docs with these changes and additionally the patch for JDK-8248566 (mobile browser optimizations)
>> applied: http://cr.openjdk.java.net/~hannesw/8253117/api.00.mobile/
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/script.js line 60:
> 
>> 58:             var isEvenRow = index % (columns * 2) < columns;
>> 59:             elem.classList.remove(isEvenRow ? rowColor : altColor);
>> 60:             elem.classList.add(isEvenRow ? altColor : rowColor);
> 
> I assume that `elem.classList` is a set, not a list.  If it was previously an odd/even row and is still the same, we
> don't want to add an extra duplicate entry to the list.
> In the DOM spec here
> https://dom.spec.whatwg.org/#dom-element-classlist
> I could only find non-normative narrative description that it is a set.

Yes, Element.classList.add(...) has Set-semantics, it will not add the class again if it is already contained.

https://www.w3schools.com/jsref/prop_element_classlist.asp

> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css line 416:
> 
>> 414:     display: grid;
>> 415:     grid-template-columns: minmax(10%, max-content) minmax(10%, max-content) minmax(10%, max-content) minmax(10%,
>> auto); 416: }
> 
> I like the minmax values and mostly like the effect on the generated docs ... although it is still slightly weird (to
> me) that the column widths can change when switching tabs in the same table.

I agree. I did try to make column width more uniform, but it is nearly impossible to do that while fitting all possible
use cases. Content lengths vary very much even within the same type of summary table.

-------------

PR: https://git.openjdk.java.net/jdk/pull/253