Month: March 2018

Home / Month: March 2018

An OSD700 Contribution Update Part 1

In this day and age, you live in one of two camps, you either love or hate autocomplete. Autocomplete (which differs from autocorrect due to contextual opposites of operation) is the answer to the mundane long dropdown lists, providing a means to both filter and evaluate a value without scrolling through the entire component (and then some!). For my second foray into Angular Material, I decided I wanted to go further with the documentation while also browsing for enhancements or usability fixes. This led me to the an issue request for documentation explaining how to incorporate option groups, which revolves around a far more complex observable pattern and design pattern (yay!), I’m guessing.

Humphrey mentioned while presenting previous documentation work that these forms of contributions also fall under my intended focus on accessibility, which I’m glad he said because it resolves my concern I had with accessibility not being related to usability. I agreed wholeheartedly. My goal since getting into programming was always to make technology as accessible and usable to the largest populous as possible, and I’m proud that I’ve been creating a path which does exactly that in small ripple-like motions. I believe that, if the technology is inaccessible to developers who devote 90% of their day to such, then how can we possible push forward without tricks which will bite us tomorrow?

I digress. Back to the task at hand.

Getting Started

Compared to the stepper component from my previous work, this autocomplete was a whole new component and workflow that I had to learn. I first started with the provided StackBlitz example from the issue itself, just to understand the underlying semantic patterns and components which make up the overall functionality. Link for those following along here.

In the StackBlitz example, we see the following hierarchy of components below. I’ve include in my explanation of each component some literal HTML code examples taken straight from material.angular.io, my argument being that they’d help to understand the semantic levels of each component and how one acts as an container to the other.

Components

Material Input

Documentation
The mat-input is a custom directive which allows for standard html input and textarea elements to work with the material form field container. The easiest way to think of this directive is to describe it as a upgrade to the original input element. Let’s go from 1.0, to 2.0 which includes form validation, error message styling, and responsive modern design. This is the component that we’d input our text into (duh), and also manipulate the autocomplete / filter.

Material Autocomplete

Documentation
Extending the material input even further, the autocomplete component provides a list component which can be filtered. This component acts as the container and main driving functionality when extended with coupling mat-option components for each list item.

Material Option Group

Documentation
Older
This component acts as a container for an array of mat-option components, allowing one to group multiple under a single heading / text.

Material Option & Material Select

Documentation
The list component used by mat-autocomplete, these act as the list item 2.0 of the HTML semantic world. Used in both the mat-autocomplete and mat-select components as display items, the material option is a very powerful component.

Updating the StackBlitz Example

When I first discovered the bug and the corresponding StackBlitz example, I thought that the component itself was broken and that I had a lot more work than what the issue had described. I was relieved while looking into the code (for the above analysis) to see this code snippet which implied that completion would show true progress and remaining work.

I corrected the issue using common sense with option groups, meaning my logic (which is below and in the link) focuses on filtering the option groups themselves, instead of the individual options (following what the issuer’s logic described). I love functional programming, and even small traces such as these makes me so happy to come up with since I think they are where many languages are heading; utilizing powerful paradigms sans the verbose 100+ lines of code to achieve such.

Thoughts on the Current Documentation and Next Steps

In a word, complete. Realistically, the work that’s required of me is minimal, simply expanding the code snippet to a full blown example which is tangible to others. After confirming that the logic is all there, and the autocomplete works as expected, this is another case of directing the readers and users towards a proper implementation so that they can push it further in their own code. Compared to the stepper, this component’s API and documented attributes is very thorough and explained using multiple examples. Working with such makes it even easier since I have a good foundation to base my work off of.

Next steps is putting the work into a pull request, verifying the expected behavior of the component. Stay tuned for a follow up coming soon!

An OSD Contribution Update – Part 1

Tutorial Header

Getting Onboard

Documentation is a topic that often splits developers into two or more camps, those who write and those who don’t; an irony since both camps rely heavily on documentation with external libraries to utilize and understand it’s respective API. So, when is documentation considered ‘good’? When does the documentation fulfill the needs of the developers, and convey the key functionality without proposing self discovery of unknown APIs? This is what I wanted to explore while contributing to Angular Material (https://material.angular.io/), https://github.com/angular/material2. I found a great issue which was requesting for more documentation for their material stepper, https://github.com/angular/material2/issues/10381 and I thought it would be a great introduction to their community while providing a changeset which benefits more than just developers or current users of Material. Updating documentation helps everyone, and in a few examples from my task I’ll explain my thoughts on why I think so.

Current State of Stepper Documentation

As the issue suggested, the documented examples for the stepper component was lacklustre… sparse even. The API was listed in beautiful English, but no interactive examples were present which displayed the various states, attributes and data-flow which the component offered. The recommendation by mmalerba was to provide better examples between various state flags, icon matching, and expansion of the original example.

Current State of Stepper Example

One item that I had noticed was the button to ‘toggle linear’ mode for the stepper never actually toggled the state, but instead set the state to true (meaning linear is enabled) and nothing else. No toggling (enabling / disabling of linear state), just moving to a single state. This was the first item I wanted to address since as a user, I’d want 1) visual feedback and 2) the option to toggle and switch between states in the example. All the foundation was already there for such an update, and it became my first commit into what would be the Angular Material project.

Creating Examples for Edit and Optional Steps

For the documentation, I saw that there were no tangible examples of the edit and optional attribute Inputs of the Material Stepper, a need which needed to be met. This is where my Pull Request started, with implied intent that I’d add more if mmalerba or I found more appropriate examples which could be utilized for the stepper component to display even deeper functionality.

I can say that reading the documentation gave me a thorough understanding of the components API, and that creating the examples which will be used to explain said API was also a easy task, but that is because I’ve worked with Angular and UI Frameworks such as Material for almost a year now non-stop. To the beginner, to the one who’s experimenting with Angular Material for the first time, this documentation and API is daunting. Despite the well written content, proper examples help to truly establish a thorough understanding of the framework in my opinion.

For either example, the process was the exact same. Copy the foundation (Stepper Overview Example), and modify the attributes, title, and toggle logic to accommodate the specific example itself on one of the steps. This way, the examples mirror each other instead of presenting the reader with different context every time. The changes are borderline single line changes, but abstracted away to their own components for clarity:

Meeting Contribution Guidelines’ Compliance

This is the first project I have worked on Open Source wise which has a predefined commit message structure (which I totally love!) to make the development process both more uniform and accessible to those doing the review. It took a few commits to truly embed into my habits the proper structure, which looks like this (taken straight from CONTRIBUTING.md):

The documentation did not provide any Pull Request related specifications, so I did my norm and hoped for the best -making it clear that it’s possible I overlooked, disregarded, or even added too much to a specific area. Really, I gave them the putty and asked for hands to show me how to mold it to their liking.

Mold it they did, leaving comments on the code review which suggested a better practice, more uniform styling or removal of unnecessary code blocks. More on that can be found here. All of the first round of code review were stylistic changes, which I was happy to fix since it also showed a gap in my understanding of their accepted coding guidelines.

Thoughts so Far

Spinning wheel of Light

This is the first contribution I’ve worked on which primarily dwelled on documentation, my niche being more of that relating to accessibility or editor features. I like to think this is equally, if not even more, monumental because it makes the code base itself and the components which are offered to developers more accessible; enabling their work with far less friction so they can further push the technologies farther. Mmalerba has been incredibly helpful so far, and also very accommodative to a new contributor who does not know his way around the code base or expectations when testing and documenting their changes.

Furthermore, it’s awesome to pick up a technology that I feel proficient with for a change, instead of having to learn (which is great, don’t get me wrong) a new one including all the bells, whistles, errors, and painful realizations that you should have started weeks before. I’m confident that I still have hundreds if not thousands of hours to learn on Angular alone, but I also see it as a tool which I can already start giving back to in any way possible.


This is a follow up to my previous post, describing some examples and public issues which touch upon heading semantics and color contrast.

Four Individuals infront of Glacier

Headings

Admitting to Your Mistakes

South Wind Motel

As you would have guessed, even I found the issues discussed above in past work from two websites which I used to claim where the best I was capable of at that time. Even more so, now that I know of these issues (which I discovered while looking for examples), the urge to fix and improve upon is there. In the South Wind Motel Website, I improperly used a H1 for the hero component, which would be fine had I made that hero display ‘Accommodations’ instead of a tagline. This is how the page reads to screen interpreters right now (without worrying in this example of divisional area tag sementatics):

South Wind Motel Heading Fail
South Wind Motel Heading Mistake

This may look like a minor issue, but the pattern repeats on each page with different taglines, some often not granting proper title-like context such as Property or Trail, which become increasingly more vague. Still, you have to start somewhere I suppose.

Silver Maple Motel

A website done a year after South Wind’s was finished (which was a weekend project during Christmas break in my defence), Silver Maple corrected many of the layout and ‘aesthetic’ issues I had with South Wind’s. In doing so, I created a different pattern of heading misuse. Here are the obvious ones that a simple inspect element unveils:

  • I used H1s due to their styling and size as icons. Meaning every standard icon on the page is a H1, without text or proper hierarchy in the slightest.
  • The proper titles use H5, unsure why I went so low down the spectrum, but we jump from an icon of H1 to H5 titles
  • The parallax images and their respective titles are H3s, which really should be H1s since they define the separation of page contents and topics. Likewise there is inconsistent blurring in attempt to mitigate contrast issues which I’ll discuss in a later article.

Two Examples of Similar Common Mistakes in the Wild

AndroidPolice

I love this website, it has been my goto source of news for all things Android since 2011, and I have to this day always held high regard for the content and it’s writers who publish there. While inspecting the site, I only saw one major offence (in my opinion, I could be forgetting a rule since there are so many) when it came to header use. The navigation bar uses a H1 for the AndroidPolice logo, and the article titles start at H2. This means that ever page is interpreted this way:

Android Police Headings Mistake
Android Police Headings Mistake

This may be a very minor issue, perhaps not an issue at all (depending on the ruleset, I am in no mood to read through the documentation this year just to confirm the smallest, most minute of a detail with a overall non-offending site), but I found it interested in how headings were used to imply hierarchy directly from the site’s title.

PC World

Simply put from a quick inspection of an article (I imagine said patterns are throughout, since all CMS use templates to remove the grunt work): H1 for title (great!), H3 for subtitle / annotation…. not so great. Realistically, the guidelines do not imply a need for subtitles to have a heading, and I imagine this was used to leverage the H3s styling. Kudos for following expected heading semantics otherwise, every other title falls under the H2 use, making the page be interpreted in the following way:

PC World Headings Mistake
PC World Headings Mistake

Color Contrast

I decided to take a stroll through Modern Flat Web designs, and see if I could find any practice which was an instant red flag. I’m using https://speckyboy.com/flat-web-design/ which currates 50 ‘Perfect’ examples of modern web design, a perfect list to try and pick a few apart. Will I succeed? Read on!

Design Interactions without Code

Website Interactions Without Code Color Contrast Mistake
Website Interactions Without Code Color Contrast Mistake

Damn that’s a bright hero component, it’s eye catching and yet blinding at the same time. The hero’s text is very readable, until you notice the cursive text which I almost missed the first time glancing through. It’s the same #FFFFFF as the bigger text, so how did I glance it over so quickly? How did it not catch my gaze? Well because the contrast ratio of that specific background color (#3EC7C2) and the text (#FFFFFF 29px font size) is 2.07:1, which fails both WCAG AA, and WCAG AAA demands. For large text, the ratio must be 3:1 or greater, which this one still does not comply with. Not off to a great start from the first page alone, and the contrast compliance didn’t improve throughout the page either for most of the colorful elements. Sad, and we just began.

CraftsmanAvenue

Funnily enough, the design and overall approach here is much more subtle and well established. I decided to test the mission statement found at the top, which has a text color of #887771 and a background page color of #FAF7F6, together they form a contrast ratio of 4.00:1, so close. Many of the elements are basic hues off from WCAG AA Color Contrast compliance, so I moved on, feeling hopeful.

Stash Flat Icons

Blinding Image
….

Presenting, modern aesthetic. Colors so close together in the spectrum that you don’t need to test using a color ratio tool to identify compliance. I can barely read the list items, I dare you to without squinting. It was at this point that I decided we had a good assortment of color related examples which all could learn from.

Learning from These Items

While doing writing this follow-up, I found two really helpful links for headings and HTML semantics which I’ve posted below. I think that if every front-end developer went through and truly understood, it wouldn’t take long at all to reprogram our already-logic-driven minds to the true semantic structuring of headings. I cannot say how we can improve these types of color contrast issues, aside from being mindful and questioning if aesthetic such as flat demands such low contrast elements beside one another. Even in enterprise, it’s not unheard of for design to be beautiful, but inaccessible to many.

H1: Headings Are Important

Common Heading Mistakes

Part 1

Caterpillar on Human Wrist

Introduction & Screen Readers

Accessibility is one topic which not many take into account when designing and developing an application, website, or printed media even. The concept of visual and interactive accessibility relates to any medium which the user uses to discover and consume content from, and how different impairments hinder the common forms and designs useless and nonconsumable. Easiest way to explain that last statement is this example: Imagine being unable to read the standard news headline found on newsprint or websites, but still wanting to know what the world around you is doing. How might one approach this if they don’t wish to listen to a TV or Radio? How might one discover headlines around a certain topic that the locals gloss over? Screen Readers and accessible websites. This video can explain the concept and need far better than I ever could, and hopefully also provides a foundation which segues into the important attributes which screen readers utilize in more detail.

Element Hierarchy

Resource
Many developers disassociate the levels and semantics of element hierarchy when designing and developing, opting for H2’s because H1 is too big for example in article titles. Often, I’ve seen cases where the H2s were used for titles, and H4s used for subtitles. Though the overall aesthetic may look better for your needs, this does not comply with the established semantics which screen readers / interceptors read to the end user, furthermore it also messes with Search Engine bots looking for content on your website.

If it’s a more unified overall font sizing you’re looking for, use a normalizer stylesheet such as NormalizeCSS or a css framework such as Bulma.IO which dictates all text the be the same normalized size among supported browsers (implying that you will edit / extend for custom font sizing).

‘Fake’ Elements

Resource
When is a button not a button? Well, aside from the philosophical test which also has us questioning what truly is, and what isn’t, we can discuss again how different element tags provide unique attributes which are useful to screen readers and screen interpreters. Likewise, as the blog explains, these attributes are critical to proper understanding of a screen and the contents on the page. Using fake a tags styled to look like buttons, or divs with backgrounds meant to impersonate an image make interpretation of the page borderline difficult.

Contrast and Colors

Resource
It’s a good thing that most developers admit that they should never design, because in truth it’s not a skill many have in their genes. I suppose the opposite can be said for designers attempting to program, but I digress. Perhaps a different day’s story. When it comes to design, there is a ratio which many choose to ignore because modern aesthetic demands it, contrast ratio.

WCAG Level AA sets the golden standard for how the contrast ratio is defined, that is the difference between two colors (commonly background and foreground) such as text and parent element or borders and container backgrounds. AA compliance is a ratio of 4.5:1, which demotes many of the grey on gray choices of modern design. This is important because too little of a ratio makes text unreadable, and too high of the ratio is semi-literally blinding to even the common user.

Part One Conclusion & Examples

I hope to update this article later in the week with real-world examples and explanations of these details more, along with following up with the next segment which would include aria tags! If you made it this far, thank you for reading and I hope you enjoyed!

An OSD Contribution Update – Part 2

Getting up to Speed in the Late Hours

In my previous post, I went through a retelling of anguish, environmental issues and dead ends while trying to evaluate how a bug such as this was possible. Throughout the process, I kept asking myself and even the other developers, what is the scope? Where could this bug be created? The overall scope of QuickOpenController.ts is massive, since it acts as the User Interface between many mediums which all have their own set of requirements, validation rules, and user input rules to be enforced. The scope was never defined in the time that I had to work and understand the bug, so I began an old method which had proven to display results. I console.log’d, and alerted till I was blue in the face. Well, almost blue. I was a mix of 4AM hues: despair, desperation, frustration, and sleep deprivation by the time ‘results’ started to show themselves.

A couple of notes before I go on:

  • I owe a working with Git Bisect article, since this one still does not detail the process or my thoughts on said process. To remedy, I think I’m going to rename the article series from ‘Working with Git Bisect and Visual Studio Code’ to ‘The Trials of The Promise-Centric Input, a Visual Studio Code Story’.
  • The ending of this article has a rainbow, one which looks like a faded, easy to miss image which compares to tie dye shirts after they start to lose their luminance. It’s a happy, ‘look what I did hackers!’ kind of rainbow, but one that is also easily dismayed by a lack of confidence in the final fix.
  • My god have I learned how easily one can glance over the information they are looking for, unknowingly skipping the one line which has the answers to their questions. Thanks David again for finding the extension host argument for Code’s CLI.

Progress looks like a Pillow full of Sweet Nothings

Back on track, where a 4AM ‘all or nothing’ type of hacking session produced some of the most unexplainable, and yet tangible concept of how the code worked. Through the console logs and alerts, I learned how the doPick function worked against the user’s input lazily, validating only as conditions were changed instead of every keystroke being entered. It was there that I also managed to catch the scope where the cursor is moved to the back, progress! Now I could remove all breakpoints (saving me what would add up minutes of step throughs) and add them into this scope alone. Alas we are moving at lightspeed now R2.

Momento: Issue Found (Code)
A rare moment of light, where the comments reveal my inner thoughts as this little experiment produced golden results.

Following the same path of console logs and the infamous alerts, I managed to emulate a very basic A/B test where a console.log('PRE:', this) would occur prior to the cursor change, and the second console.log('POST:', this) occurring just after. I had cornered the function itself in between two statements which allowed me to check for state changes, while also establishing the direct line which changed it. I’m pleased to admit that it was from my first article’s speculation, I was very close to the money when I guessed that the value being set each time caused the cursor to move to the (default) end of line.

Break All the Things

Imagine yourself ambushing a single function, knowing that when it’s called you’re watching it’s every move, it’s every operation. What do you do to confirm that the function does indeed know where the rainbow’s located? Well, I decided to break it. Moreso, I decided that my first step (as one may do when asserting dominance), was to make it disappear.

Making it disappear broadcasted an overall UI change which was hard to miss, and also a removal of the bug itself. Still, I couldn’t just leave it commented out and helpless. I removed the comment-line restraints from the conditions found here, and left this.pickOpenWidget.setValue(...) commented out. Now, we were fishing to see which logical block led to the amazing wonders which is well-deserved sleep. It became clear after my next round of reproducing the error that the function itself being called causes the cursor jump, and from my opinion, did not need to be called in every single case.

The logic fix that I opted for which did cover the two edge cases described was to check if the validation process had started, meaning when options.valueOptions existed then the user had already begun to input into the component, and we shouldn’t be redrawing the input with the previous state -autofocusing in the process. After this corrected the initial issue, I went about testing other command palette functions to ensure that I had not tampered with other bits of functionality. When all was good, I slept.

The Rainbow at the end! Photo by Sam Kulesh

3 Hours Later: Conclusions

The final resolution that I came up with can be found here, which contains a pull request being reviewing and evaluated for the validity of the fix -a case I knew would occur since this fix affects almost all non-editor related user input such as the command palette, file opening, symbol finder, etc. Even as I’m writing this, I’m not confident that the fix itself is the most correct of all possible ones, since the scope and affected functionality rings through many other edge cases. Imagine changing how a paragraph tag works on your average website; that big of a change.

Custom Function Reproducing the Error... Fixed!
Custom Function Reproducing the Error… Fixed!
Azure Functions Error Replicated... Fixed!
Azure Functions Error Replicated… Fixed!

An OSD Contribution Update – Part 1

Header Image

While working towards implementing a fix for this bug, it was made clear to me that the bug was a regression, and not evident two months or so ago. This led David to directing me towards his (awesome btw) tutorial on how git bisect works, and how developers use it to determine where in the version history the bug was introduced. I’m glad that this concept existed, for even at work a few colleges and I attempted to replicate the similar behavior by hand, unaware that such tools already existed and was widely available.

Some background details that I had collected prior to me starting the bisect process:

  • I knew that the current master branch contained the issue. According to the comment thread, this issue had arrived around a month or two ago.
  • The Azure Functions validation logic is intact and functioning as expected, so the bug itself derives from refocusing the input after rerendering post-validation, a lifecycle which shouldn’t occur to begin with.
  • A custom extension could be created (and was provided in the bug description) which replicated the error.

First Steps – Identifying a Working ‘Good’ Commit!

In git bisect, you identify a good and bad commit range, which is used to isolate and pinpoint where the commit occurred which causes the bug. I wanted to identify a good commit prior to entering the process where the bug was not present so that the process would go along smoother. I started as early as git commit 834ba9b, and moved my way down the following commits to identify a ‘good’ commit:

  • 249a796 – November 20, 2017 – Still broken!
  • 83d8cbe – October 2, 2017 – Still broken!
  • 08d8f0f – September 25, 2017 – Still broken!
  • a87dd9c – August 21, 2017 – Still broken!

My Brain After This
Broken Down Bus

It was here that I decided there were two choices, continue going down this rabbit hole with the next commit jump being all the way to January 2017, or I admit that perhaps this edge case always existed and in consequence, needs to be addressed with the latest code base. I’ve decided that I want to go down the rabbit hole all the way to January 2016 if it produces a different edge case at least. That will be the introduction to part two, which I hope to publish in close succession to this first post.

Below are some of the issues which I encountered while working out this bug, and what caused what felt like work-week-long delays in between progress.

How far back I can go!

Trials, Errors, Showstoppers along the Way

Before I even started with the bisecting process, I knew that I had to attempt to replicate the bug in the development version of Visual Studio Code. Two hours later, here is what I learned:

  1. The Extension Gallery and it’s respective API do not exist as a part of the developer / open source Visual Studio Code. They exist similar to a feature toggle, which Microsoft activates in the production version, this being due to some licensing concepts and beliefs which is explained in much better detail here.
  2. You cannot sideload an extension easily without the Gallery API, which led me and hundreds of others who created, browsed, or cried for answers relating to this issue to a stackoverflow answer like no other. The code needed to be added to product.json:
  3. Extensions hook into a proxy-esque API (depending on their required context), meaning this process of using git bisect is entirely based on faith that the extensions themselves are not the issue. If they produce the error, your scope broadened 10x.
  4. Because all things must have versions and updates, it’s entirely possible while going forward / backward to encounter where version mismatches causes the extension or host editor to not be compatible.
    Version Mismatch with Azure Functions
  5. It is entirely possible because of the number 4, you will have to create your own extension. This is a battle of itself which I will describe below more.

Custom Extensions To Replicate Broken Edge Case

In the original bug, the reporter provided example code which when run, replicated the issue itself without an official extension. The tradeoff? Well you have to create a local temporary extension that Code will compile and attempt to integrate into its infrastructure. Issue? Well similar to the Extension Gallery being not included with the development version of visual studio code, neither is the node debugger and or compiler. These are extensions which are included by default with Microsoft’s release version. In attempt to mitigate before I get very hacky, I side-loaded the extensions gallery in the same way described above, and then installed node debug and node exec. The first allowed for successful execution of the environment (more on that), and the later is incase I could find a way to bleed / inject my custom function into the live environment.

I was able to follow the Microsoft documentation for creating and launching an extension with my standard version of Code, but that doesn’t help unless I’m debugging against the latest release (1.21.1). A few Github threads specify fixes for this issue so that you can bootstrap the production-built debug instance through your developer instance, but so far results have been less than stellar on MacOS and Linux. My worst case scenario that I think I will try if no further progress is made with the previous approach is to debug the latest (again), but this time focus on the validation handler, referencing commits which change its surrounding scope for example.

Important Update:
Thanks to David, whose eyes and searching skills proved themselves far better than mine, I was able to sideload the custom extension consisting of the following code into the development version of Code with this command: --extensionDevelopmentPath=\....

The extension which replicates the bug itself is:

Dependency Issues with Linux (Fedora 27) While Rolling Back

I encountered many dependency and build process issues on my Fedora 27 box while moving between commits, often cleaning /tmp directory to see if the issue was related to version mismatch. Later after some Googling I found that some of the issues related to NPM’s handling of file systems and permission, which was equally terrifying as I began to experiment while looking for a fix. Who wouldn’t be terrified after this lovely fiasco After about an hour or more of attempts, I moved to MacOS to see if that process would be smoother. If so, I can admit that my linux workstation probably needs a clean-up / reinstall, having served me and thousands of packages / files well for over two years without major issues. After I moved to MacOS on High Sierra 10.13.3, the issue relating to the different build systems was not apparent.