Project: Keycloak (Provisioning / Security & Compliance)
File: CODING_GUIDELINES.md

The default package manager is PNPM, we recommend enabling for the best compatibility, which will automatically ensure the correct version of PNPM is used: ```sh corepack enable ``` There are several reasons why PNPM is used over other package managers (such as NPM and Yarn): The reasons mentioned in , mostly it avoids . Unlike it preserves the `node_modules` directory between installs, allowing for faster install times (especially in Maven builds). Unlike NPM it does not require workspace dependencies to be , simplifying release versioning. If you submit a pull request that changes the dependencies, make sure that you also update the `pnpm-lock.yaml` as well. Since this project relies greatly on it is recommended you familiarize yourself with features such as . To ensure code-style is consistent between various contributions is used to enforce a common set of guidelines. The of ESLint are used as a foundation. For TypeScript code-style the recommendations of are adhered to as much as possible, specifically the and configurations. Deviations from, or additions to these rules should be documented by comments in the . The (`!`) is sometimes used to tell the TypeScript compiler that it is guaranteed that a value is not `null` or `undefined`. Because this might possibly introduce errors at run-time it should be used sparingly. The only place where it is valid to use the non-null assertion operator is on the types that are provided by the . The reason for this is that the types are generated from Java code, which does not explicitly provide information about the nullability of fields (more on that ). We have made a conscious decision to stay away from state management technologies such as Redux. These overarching state management schemes tend to be overly complex and encourage dumping everything into the global state. Instead, we are following a simple philosophy that state should remain close to where it is used and moved to a wider scope only as truly needed. This encourages encapsulation and makes management of the state much simpler. The way this plays out in our application is that we first prefer state to remain in the scope of the component that uses it. If the state is required by more than one component, we move to a more complex strategy for management of that state. In other words, in order of preference, state should be managed by: Storing in the component that uses it. If #1 is not sufficient, . If #2 is not sufficient, try . If #3, is not sufficient, use a . A good tutorial on this approach is found in . When using hooks with Typescript there are few recommendations that we follow below. Additional recommendations besides the ones mentioned in this document can be found . Currently we recommend using inference for the primitive types booleans, numbers, and strings when using useState. Anything other then these 3 types should use a declarative syntax to specify what is expected. For example the following is an example of how to use inference: ```javascript const [isEnabled, setIsEnabled] = useState(false); ``` Here is an example how to use a declarative syntax. When using a declarative syntax, if the value can be null, that will also need to be specified: ```javascript const [user, setUser] = useState<IUser | null>(null); ... setUser(newUser); ``` When using reducers make sure you specify the . For useEffect only . We use custom CSS in rare cases where PatternFly styling does not meet our design

If styling needs to be added, we should first check that the PatternFly component is being properly built and whether a variant is already provided to meet the use case. Next, PatternFly layouts should be used for most positioning of components. For one-off tweaks (e.g. spacing an icon slightly away from the text next to it), a PatternFly utility class should be used. In all cases, PatternFly variables should be used for colors, spacing, etc. rather than hard coding color or pixel values. We will use one global CSS file to surface customization variables. Styles particular to a component should be located in a .CSS file within the components folder. A modified BEM naming convention should be used as detailed below. Global styling should be located? ./public/index.css. The CSS relating to a single component should be located in a file within each components folder. PatternFly reference https://pf4.patternfly.org/guidelines#variables For the Admin UI, we modify the PatternFly convention to namespace the classes and variables to the Keycloak packages. Class name ```css .keycloak-admin--block[--pseudo-element] ``` Examples of custom CSS classes ```css // Modification to all data tables throughout Keycloak admin .keycloak-admin--data-table { ... } // Data tables throughout keycloak that are marked as compact .keycloak-admin--data-table--compact { ... } // Child elements of a compact data-table // Dont increase specificity with a selector like this: // .keycloak-admin--data-table--compact .data-table-item // Instead, follow the pattern for a single class on the child .keycloak-admin--data-tabledata-table-item--compact { ... } // Compact data table just in the management UI at the lg or higher breakpoint .keycloak-admin--data-table--compact--lg { ... } ``` Usually, PatternFly components will properly style components. Sometimes problems with the spacing or other styling indicate that a wrapper component is missing or that components havent been put together quite as intended. Often there is a variant of the component available that will accomplish the design. However, there are other times when modifications must be made to the styling provided by PatternFly, or when styling a custom component. In these cases, PatternFly custom properties (CSS variables) should be used as attribute values. PatternFly defines custom properties for colors, spacing, border width, box shadow, and more. Besides a full color palette, colors are defined specifically for borders, statuses (success, warning, danger, info), backgrounds, etc. These values can be seen in the and a can be found in the documentation section. For the Admin UI, we modify the PatternFly convention to namespace the classes and variables to the Keycloak packages. Custom property ```css --keycloak-admin--block[--pseudo-element]--PropertyCamelCase ``` Example of a CSS custom property ```css // Modify the height of the brand image --keycloak-admin--brand--Height: var(--pf-v5-global--spacer--xl); ``` Example ```css // Dont increase specificity // Dont use pixel values .keycloak-admin--manage-columnsmodal .pf-v5-c-dropdown { margin-bottom: 24px; } // Do use a new class // Do use a PatternFly global spacer variable .keycloak-admin--manage-columnsdropdown { margin-bottom: var(--pf-v5-global--spacer--xl); } ``` Utility classes can be used to add specific styling to a component, such as margin-bottom or padding. However, their use should be limited to one-off styling needs. For example, instead of using the utility class for margin-right multiple times, we should define a new Admin UI class that adds this margin-right: var(--pf-v5-global--spacer--sm); and in this example, the new class can set the color appropriately as well. Using a utility class ```js switch (titleStatus) { case "success": return ( <> <InfoCircleIcon className="pf-v5-u-mr-sm" // utility class color="var(--pf-v5-global--info-color--100)" />{" "} {titleText} </> ); case "failure": return ( <> <InfoCircleIcon className="pf-v5-u-mr-sm" color="var(--pf-v5-global--danger-color--100)" />{" "} {titleText} </> ); } ``` Better way with a custom class ```js switch (titleStatus) { case "success": return ( <> <InfoCircleIcon className="keycloak-admin--icon--info" // use a new keycloak class />{" "} {titleText}{" "} </>