Tangram code standards

Tangram code standards ensure that components are optimised for performance, accessibility and ease of use.

Performance

Tangram components are designed with page performance in mind

• Minimise DOM nodes
  • Use ng-containers instead of divs to separate content
• Run code outside of the Angular exclusion zone to minimise interference with Angular change events
• Keep bundle sizes low by reducing dependencies between components
  • Consider the dependency tree and minimise import order from widely used components
  • Consider dependency projection vs. dependency injection, and module imports and exports

Accessibility

Tangram components provide the foundation for teams to create accessible web experiences.

• Apply a consistent focus state on interactive elements
• Make use of semantic native HTML elements
• Use ARIA attributes sparingly, and only when a good level of accessibility cannot be achieved with native HTML elements

Teams are responsible for composing and configuring components in their specific contexts in an accessible way.

See the Tangram best practice guide for accessibility

API design

The Tangram API is designed to be consistent and easy to follow.

• Any interactive component supports standard HTML states, such as active, hover, and focus
• API options with the same function are named consistently across components

Common API options across Tangram components are:

• Compact (boolean)

  Defines a component state that is smaller, or takes up less room. This is not tied to mobile views or breakpoints

• Disabled (boolean)

  The state of an interactive component that is disabled

• Size (enum)

  Defines the space a component takes up on the page. Tangram components are device agnostic, and use viewport width to define size

Tangram versioning

Tangram is a shared code library, with components in use across multiple projects. Any changes to the API must be carefully considered.

We use Semver to communicate with teams about our API changes. Chat to the Tangram team before making any Tangram Web UI code changes.

Using @Input.transform (a replacement for @trademe/ensure)

To do runtime validation on inputs to an Angular component, you can use Angular's built in Input transform functionality, combined with our custom transform functions. For example, the following can be used to guarantee that the input will be a number, throwing an exception otherwise: @Input({transform: (value: any) => ensureNumber('exampleProperty', v) public exampleProperty: number

Previously this functionality was provided by @trademe/ensure, however this no longer works from Angular 16, so we have moved to using the Angular API instead.