Skip to main content

API surface

Introduction​

Given the nature of the frontend development, there are some details of the implementation, or its outcome, that are exposed to consumers. However, not all of them are part of the API surface.

This document enumerates and describes the JDP parts that compose the contract between JDP and its consumers. These parts are subject to the non-breaking changes policies, ensuring that minor releases do not introduce non-backwards compatible changes to them.

The rare exception to this rule is necessary security fixes, or bug fixes.

Warning: Relying on any non-API element might cause issues for applications maintenance and upgrade.

Breaking changes (non-backwards compatible changes) to aspects that are not APIs can occur in minor releases without any mention in the release notes.

We strongly recommend that you do not rely on these aspects in any production code.

Jutro Design System and UI Libraries API​

The following aspects are considered Jutro Design System and UI Libraries contract:

Package names and package and module public structures or signatures​

JDP package names and their public exports are part of the contract, as well as the different functions' signatures and types.

Warning: Only the direct exports from the listed entry points are considered part of the contract. For more information, see the Packages overview.

Example: this would not be a direct export from a defined entry point (@jutro/components), so it is not part of the JDP libraries contract:

import { intlMessageShape } from '@jutro/components/types/types';

In this case, a valid import from that entry point would be:

import { Button } from '@jutro/components';

Examples:

  • The package name, the MicroFrontend component name, its import path and its properties are part of the contract.
import { MicroFrontend } from '@jutro/micro-frontends'

<MicroFrontend
    src='claimMicroFrontend@http://localhost:3001'
    jutro = {
        mode: 'isolated'
        router: {
            basename: '/welcome',
        }
    ...
    }
>

The jutro property could add new properties or extend their accepted values, but always maintaining the support for the existing ones.

  • The useAuth hook from @jutro/auth package returns the below attributes and they will not be modified (they could be extended):
{
  isAuthenticated: boolean;
  isPending: boolean;
  userInfo: OidcUserInfo | null;
  error?: Error;
  login: AuthLogin;
  logout: AuthLogout;
  accessToken: string | null;
  idToken: string | null;
}

React component props: their names, types and default values​

Component names and the set of accepted properties are part of the contract. Review the components documentation and the escape hatches for more details and customization options.

Example: Making an optional property required would be considered a breaking change. However, making a required property optional could occur in a minor release as it would not have an impact on existing customers.

React components visual aspects and behavior​

Components behavior and visual representation are part of the contract and must remain stable.

Example of behaviors:

  • When should a Tooltip be closed by default
  • The default status (expanded / collapsed) of AccordionCard elements
  • Events triggered on user interaction: when the onChange event is triggered while the user is interacting with an input element

The way the component (and each of its variants) is displayed by default will remain stable and any modification will be backwards compatible. However, components also provide customization options that allow consumers to override these default values (for example, design tokens).

The available customization options available are part of the contract, while the values applied depend on the consumer. See the Theming: Design tokens section below for more details. The Escape hatches page also describes other customization alternatives.

React components' accessibility tree​

Accessibility is one of the key aspects of the Jutro Design System, and the accessibility tree of each component is part of the contract.

Warning: Components accessibility requirements are under continuous review. The lack of compliance in this area is considered a bug and its resolution might imply modifications in the accessibility tree, for example. adding, removing or modifying an element aria role.

Theming: Design tokens​

Design tokens define the different customization options available and how they are applied to the different components. While the design token values can evolve, there are 2 parts that will remain stable and backwards compatible in the React components library:

  1. Design token names
  2. How the design tokens are applied to every component
Note: Component level tokens represent the way that design tokens are applied to the components. They define the customization options that each component supports. It is possible to introduce new customization options but existing ones must remain available.

See the Design Tokens documentation for further details

Translation keys​

JDP libraries, including the Jutro Design System components, provide default messages, for example. the message to be displayed when there is no option available in a Combobox. These are defined to allow their internationalization and provide some default values.

 noResults: {
        id: 'jutro-components.fields.Combobox.noResults',
        defaultMessage: 'No results.',
    },

The message keys (id) are part of the contract.

Support for major third-party dependencies​

Support for Node.js, React, or Webpack versions would be maintained, but support for new versions might be added.

Note: Vendors defined EoL or EoS must be considered, especially from security perspective.

Additionally, new JDP features might require customers to upgrade to newer dependencies versions to work.

Configuration: files, variable names, default values and types​

The existing configuration variables, accepted values, and their default values must remain available and unmodified. It is possible to extend the options available or to introduce new alternatives.

Example: JUTRO_AUTH_USE_NATIVE_OKTA_CLIENT is provided, and it accepts true / false, false being the default value.

Micro frontends nesting compatibility​

The MicroFrontend component and the Microfrontend SDK define a clear API and contain a wrapping layer that facilitates the embedding of micro frontends independent of the minor version of the JDP libraries that the shell and the micro frontend apps use.

See the Micro frontends documentation, including the API reference for further details.

CLI commands: availability, signature, and purpose​

The list of available commands in the provided CLIs are part of the contract, as well as their different configuration options.

Warning: CLI commands execution results might be modified to adapt them to the latest versions, practices and feature needs.

Configuration of the provided developer tooling​

Scripts used for building the application, linting options, and other related functionalities will remain backwards compatible.

Warning: While the scripts and configurations will remain available, we might need to change or adapt them based on evolving product and customer needs, which might result in different output of these scripts.

Aspects that are not part of the API​

The following is a list of aspects that are not part of the JDP contract, even when they are exposed and available:

  • Any exports from under internal path or any entry point not listed in the Packages overview section.
  • Component HTML Markup
  • CSS class names
  • CSS variables
  • CSS mixins
  • Design patterns and examples, which are typically written in the documentation
  • Developer and build tooling messaging, such as error text and warnings
  • Runtime errors: error throwing and associated error codes (specific messages and additional properties are not part of the API)
  • Templates

Digital SDK​

See the Digital SDK API contract documentation.

Digital SDK in Jutro​

When generating the Digital SDK using the Jutro Platform CLI, the same contracts as defined in Digital SDK documentation applies.

However, there is some Jutro specific functionality available for the initialization and configuration that is also part of the JDP contract.

Digital SDK UI extensions​

The Digital SDK UI extensions are a set of generated abstractions that expand the Digital SDK to work more effectively in React-based applications. These extensions have their own contracts defined in the Digital SDK UI Extensions API contract.

Jutro Digital Platform infrastructure​

Jutro Digital Platform infrastructure is provided as a service. However, with the goal of reducing disruptions for customers, the following aspects have been considered part of its contract:

Auto-generated deployment URL format​

The auto-generated deployment URLs format used when deployments are created without using custom domains.