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 #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 #21 .
• closes #20, each cell/row is labelled as markdown or code.
• closes #19 , now screen reader users can use table navigation to move through the rows of their table.
• closes #15 our overflow issues are displaced to the new format

• 14 defines a bunch of aria one we have chosen patterns, when we choose patterns, we know the aria to apply.

• addresses #13: the patterns chosen here allow us to define keyboard usage and notes to the user.
• addresses #12 scroll, navigation, and zoom should be tested in the new format.
• closes #11 with a Scroll to Top button
• addresses #5 by adding header, footer, and main landmark conventions
• includes #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]

i've stripped away most personal opinions to the bare form of an accessible notebook webpage. from an accessible starting point we are more likely to design accessible interactive experiences and documentation. retrofitting accessibility is expensive.

[tonyfast]

aria is a code smell is an important document in this work. it allowed us to start asking what are naturally interactive widgets in the notebook parlance. through this we could rediscover the interactive form nature of a cell, consider links to be interactive which is why we added links to headings, and, further at extreme zoom, we find overflowing elements become interactive. these documents really aren't static.

[tonyfast]

currently, headings in markdown or code outputs link directly to the heading id and cannot reference their parent. the headings should have an pilcrow link to the cell. this is true in the contents and navigation.

[smythp]

• Visual focus is very browswer, OS, reader specific, I wouldn't worry too much about it. (Very common using NVDA, etc. for the visual focus to get completely out of sync, they don't seem to regard it as a major issue, possibly because they tend to be more focused on eyes-free usage.)
• Really enjoying the big visual focus when you tab through, that's really nice, I can actually tell what's selected. (!)
• Currently not getting audio feedback when tabbing with Orca. (Just tried it out briefly while you were talking, haven't gone deep into it or tried NVDA, JAWS, etc.)
• Really like the no div approach. Div is where HTML semantics goes to die.

Thanks, great demo, Tony. P)

[tonyfast]

@smythp

Currently not getting audio feedback when tabbing with Orca. (Just tried it out briefly while you were talking, haven't gone deep into it or tried NVDA, JAWS, etc.)

i was developing on orca in chrome. i have to Tab to elements then start reading mode Super + ;

[smythp]

Hi Tony, that does work (i.e., can read forward from the tabbed code and hear the code, and that part works well). Guess I find tabbing and not hearing something to be a little disturbing, like something is muted. On the other hand, I don't know what you'd label those tab indexes ("code cell?" number of lines?) Again, probably in somewhat uncharted territory here.

Thanks, really enjoyed the demo, think this is a major step forward / consolidation of the prior work.

[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