the notebook: a table of cell forms

[tonyfast]

this pull request introduces a new notebook template that is can be navigated with a screen reader. when designing this template:

• patterns were constrained to WAI patterns
• screen reader browse mode navigation is considered
• notebooks are presented as structured data in tables containing complex forms.
• static notebook cell inputs are considered interactive because of their natural copy/paste affordances

addressing issues

• the structure proposed here includes skip links and a place to assist users as requested in Notebook Tutorial Link #22
• the metadata for the document can be captured in the table.cells > caption. this is linked to assistive tech and a good place to present more metadata Move Metadata to the top #21 .
• closes Share Cell Content with screenreaders #20, each cell/row is labelled as markdown or code.
• closes Navigate to cells using keyboard commands #19 , now screen reader users can use table navigation to move through the rows of their table.
• closes Code cells cut off content at high zoom in rendered notebook #15 our overflow issues are displaced to the new format
• Explore ARIA options in rendered notebook #14 defines a bunch of aria one we have chosen patterns, when we choose patterns, we know the aria to apply.
• addresses Review/explore keyboard shortcuts in rendered notebooks #13: the patterns chosen here allow us to define keyboard usage and notes to the user.
• addresses Explore options for minimizing content on left side of rendered notebook #12 scroll, navigation, and zoom should be tested in the new format.
• closes "Top of Page" link in template footer bug #11 with a Scroll to Top button
• addresses Explore landmark options in rendered notebook #5 by adding header, footer, and main landmark conventions
• includes Add a table of contents to rendered notebooks #9 by including a table of contents in the footer within a disclosure pattern. the table of contents is expanded on a skip link,

[smythp]

Wow, this looks like a big one, major issue referencing here. Excited to take a look.

[tonyfast]

now this template supports native dark/light mode settings.

there is a place holder for accessibility settings that we can add to later. what accessibility settings should we provide?

• dark/light theme picker
• pygments theme picker
• font size
• line/letter spacing
• toggle metadata buttons

readability defines css variables as features for changing the presentation.

[tonyfast]

this template is designed for non-visual features, but the lack of aestethics hinder how people will receive the concept. in this extended version, we are prototyping using bootstrap. this approach should not be framework specific when all is said and done. the bootstrap version does make the sighted experience more pleasing.

currently missing:
mathjax, accessible pygments, jupyter widgets

[tonyfast]

the table had role="treegrid" but this sacrifices reading mode. we switched to a standard table because it reads and navigates better.

[tonyfast]

below are three versions of this template on stsci notebooks:

• https://iota-school.github.io/notebooks-for-all/branch/table-form/exports/html/Imaging_Sky_Background_Estimation-table-default.html
• https://iota-school.github.io/notebooks-for-all/branch/table-form/exports/html/lorenz-executed-table-default.html
• https://iota-school.github.io/notebooks-for-all/branch/table-form/exports/html/stsci_example_notebook-table-default.html#citations

[tonyfast]

when the table of contents drawer closes we lose focus. we'll fix that by focusing the window.location.hash when the drawer closes

[tonyfast]

bootstrap doesn't have the concept of drawer, like material design does. the offcanvas element is not a drawer and focus is problem until bootstrap 5

[tonyfast]

so i just dropped all the javascript. i need to trim some css.

currently the focus on the table of contents needs work.

[tonyfast]

i think we may have been misleading ourselves by designing "static notebooks". it turns out that the "static" or html rendering of a notebook can be intensely interactive. we consider that user experience below.

interactivity

there are two naive interactions we can lean on for a rendered notebook:

• interaction arrives through interactive html widgets that can be tabbed.
• code input areas to be navigable, copy-paste element.

navigation

readers may need quicker navigation capabilities to parts of the document; these needs are more critical for long notebooks. when the notebook is rendered we can identify parts both:

1. nominal: there is a special cell name that is an anchor to a specific cell (todo)
2. ordinal: we can reference specific cells numbers

this pull request structures the main are of html with the specific identifiers. since one of our test notebooks is really long (>80 cells) we can test better navigation tactics.

table of contents

a natural first widget to implement was the table of contents. this feature was a recurring need from #9. this pull request implements a table of contents that starts to consider how the document should be navigation. heading and cell navigation is implemented.

the table of contents is turning into its own widget to navigation code, narrative, and cells. managing focus will be a very important ux consideration. the navigation system became a natural extension of a semantically meaningful rendered version of the notebook.

there are specific patterns that should be upheld for the hybrid code, narrative, and cells.

[tonyfast]

scrolling is another natural interactive affordance when working in zoom mode.

[tonyfast]

chartability heuristics are for accessible data visualizations, systems, and interfaces. when these heuristics apply, we can use extended POUR principles that include CAF - Compromising, Assistive, Flexible. the CAF principles extend the accessibility design space to consider interactions with data.

the first Compromising heuristic states:

A table must be provided that contains a human-readable version of the data the chart is based on. This may be excluded if the chart title, summary, context, or annotations are sufficient at conveying all relevant information contained in the chart.

i think it is safe to say that we are in chartability's domain by representing notebook documents as a <table> . the semantic table representation we have chosen in this pull request could meet all of the Compromising principles. for example, the links/cells/table of contents widgets abide "Location and history is clear". the <table> feature extends the perceived interaction affordances to arrow navigation defined by WAI Patterns and sorting and filtering defined by the Compromising principles.

the Assistive heuristics will need some further development. they can be handle with different css states. in the past, style conventions were developed to convey state. now, however, the semantic description of the notebook interface provides canonical selectors to the interface based html and aria standards. the new representation should allow design teams to optimize the experience based on standards, with less conventions.

this work introduces a nascent degree of Flexibility. the flexible settings should be in the <footer> of the <body>. we can have flexible features for text like readability mode or dark/light mode.

we've started accruing idioms:

• notebooks are naturally interactive documents
• notebook cells are complex forms
• large notebooks should be navigable

i think with this work we are adding

• notebooks are data visualizations bound to POUR-CAF principles

adding this idiom naturally expands the expected interactivity of the notebook document. we gain expectations for our <table> structure and seed a substrate to build other accessible visualizations from. that said, POUR-CAF notebook principles provide a powerful container for further POUR-CAF visualizations in the outputs. accessibility all the way down.

one feature we'll need to consider is performance. i don't know what guidelines these fall under. we should be lazy and async loading media like images and iframes.

cc: @frankelavsky

[tonyfast]

it looks like role="document" might be something worth investigating https://www.digitala11y.com/document-role/

[smythp]

A little hard to tell what the implementations will look like, but it seems to fit the semantics of the situation. Hadn't run into it before.

[tonyfast]

still need to add cell numbers to markdown links.

the notebooks are being testing in axe, webaim, equal access, and with the orca screen reader at 400% zoom.

[tonyfast]

this last pass reintroduces the nbconvert conventions and flags to feel more familiar to nbconvert users although it is not reusuable like one might expect because the semantics are different.

[tonyfast]

some notebooks on dark theme look really bad. we are restricting our opinions to light mode notebook, but we know how to super a preferred dark mode. since we don;t have to manage themes we are adding the github light color blind theme. to go further down the accessible path we've included atkinson hyperlegible font for dyslexic readers.

[tonyfast]

i added a readme section to the template that is duplicated in the docs now.

[tonyfast]

to finish

• [ x] add to docs
• add tests

[tonyfast]

gonna merge this before i do damage