Design Document - Jaspr Standard Component Library

This document outlines the design principles for the components contained in the standard component library that is part of the core jaspr package.

The goal of this document is to give a clear set of rules and guiding principles around the design of components in the standard library. It should be taken into account when creating a new component, modifying an existing one or reviewing changes regarding any of the components.

The standard component library should contain a set of components that can be used by any developer either for building an application or as the basis for further component packages.

The library should contain components in the following categories:

• Layout: Components helping with laying out other components.
• Text: Components displaying text.
• Forms & Input: Components for (form) input and other interactions.
• ... (TODO)

The library is not meant to be exhaustive in any of these categories, as it will be implemented and extended over time.

Where possible, it should be oriented at the standard Flutter widgets for familiarity, but should not recreate every widget be default. Rather, it should be decided on a case-by-case basis whether a given widget should be recreated and added to the library, based on the component design requirements defined further down in this document.

A component inside the library should have the following qualities:

Each component in the library should be well documented directly in the code using documentation comments.

Ideally the function and behavior of a component should be immediately clear to the developer who is using it. Besides documentation, the main factor of this is the name and properties of a component.

When a component is named equal or similar to a Flutter widget, it should also behave similar and have similar properties, otherwise the developer will be confused.

One of the biggest challenges for jaspr is the gap between best practices both in Flutter and on the native web. Our primary goal is to make a framework that is appealing to Flutter devs while also adhering to modern web standards. When designing components inspired from Flutter widgets, we must be careful to not use bad practices regarding web development.

One key aspect of this is to use semantically correct HTML tags for components. While its possible to use e.g. divs everywhere (mostly), we should try and use the semantically meaningful tags, like ul, p, section, etc.

This is also important for accessibility and SEO to some extent.

Related to this, it is probably a good idea to add some sort of CSS reset functionality when building a theming system.

Components should be unopinionated in styling and be greatly customizable and flexible. One way to achieve this is to keep the option to use custom CSS classes, styles and attributes on a component.

Currently, we have a BaseComponent class that most library components extend. The base component renders a single dom component based on the provided properties, and has overridable methods like getStyles().

I have a couple of points that bother me with this.

• The extra class has very little value. It would be just as much code, if not less when the components directly render a dom component in their build method, instead of extending this class.
• Components that implement the base component are not easily inspectable. When a developer looks inside a component to understand its implementation, he cannot see a build method but instead has to understand the inheritance system.
• The inheritance structure goes against the core Flutter (and Jaspr) design principle, which is composability. A custom component should be built by composing other components in the build method, not by inheriting other components.

Therefore, I plan to remove this BaseComponent class.

The following section contains specifications and discussions around single components.

A few discussion points:

• Everything can have multiple children and can be made scrollable on the web, so we should be clear on the purpose of a ListView component.
• I'm strongly for using the correct ul / ol tag with li items for this, based on 3.
• By default, on the web, lists have some type of marker: bullets for ul and numbers for ol. In Flutter lists have no marker. Based on 2 I would suggest defaulting to ul with the marker type set to none, and then have an additional property to specify a different marker type (which includes numbered for ol).
• ...