====== Evergreen Angular Development Best Practices ======

Work in progress.
Loose collection of practices to review with developers so we can agree on UI developer guidelines.

==== Code quality ====

  * Run %%'ng build --prod'%% before committing.
    * This ensures the templates also compile successfully.
  * Run 'ng lint' before committing.
    * This does more than check style, it also warns when an import pulls in too much code, among other things.
  * Make sure that 'ng extract-i18n' runs before committing (some i18n syntax errors are not caught by ng build)
  * use camelCase variables when possible for consistency.  (Note fields on IDL objects don't apply).
  * Use 2-space indentation in HTML files
  * Use 4-space indentation in Typescript and CSS files.
  * Avoid column widths in code that extend well beyond 80-100 characters
  * Avoid subscribing to Observables within other subscriptions (nested subscriptions).  Instead, you should should use pipeable rxjs operators like switchMap, mergeMap, filter, map, and tap. [[https://github.com/cartant/rxjs-tslint-rules|Some of these tslint rules]] can be helpful for catching nested subscriptions and other RxJS issues.

==== UI ====

  * Design for screen width of 1350 pixels.
    * This is somewhat arbitrary, but seems to cover most laptops and smaller (non-mobile) screens without being too limiting.
    * Browser dev tools can show the width of the current browser window.
  * Use Bootstrap utility classes when possible instead of writing custom CSS.
    * https://getbootstrap.com/docs/4.2/utilities/
    * These are especially useful for margins and padding.
  * Use console.debug() for debugging.  Use console.log() sparingly.  Excessive logging can impact UI speed.
  * Make resources deep-linkable where possible (/eg2/path/to/thing/id)
  * Give form inputs ID values with linked i18n labels
    * <label for="patron-name" i18n>Name</label><input id="patron-name" .../>
    * Beware repeatable components have unique form input IDs (extend id with incrementor, random(), etc.)
  * Give buttons meaningful title or aria-label attributes
  * Give images meaningful alt attributes (alt="" is okay for decorative or redundant images; see the [[https://www.w3.org/WAI/tutorials/images/decision-tree/|W3C decision tree for alt text]])
  * Test keyboard navigation with tab, shift+tab, arrow keys, and other keys as appropriate. Make sure that all buttons, links, and other interactive elements are focusable.
    * The [[https://www.w3.org/TR/wai-aria-practices-1.1/|WAI-Aria Authoring Practices]] may help you determine the appropriate keyboard interactions for more complex widgets
    * Don't add Bootstrap's "btn" class to unfocusable elements, like <span>s, <label>s, or <a>s that don't also have a "href" attribute.  Use a tag that is already focusable instead, like <button> or <a> with a "href" attribute.
  * Make sure that your screens have an <eg-staff-banner> at the top to let users know where they are.


==== Unit Tests ====

  * Files named *.spec.ts are automatically treated as unit test files.
  * Unit test files should live in the same directory as the code they are testing.  
    * e.g. idl.service.ts and idl.spec.ts are in the same directory.
  * See Open-ILS/src/eg2/src/app/core/*.spec.ts files unit test examples of core services.
  * The highest priority for unit test implementation are shared *.service.ts files, followed by shared components, since changes to these files have the broadest impact.