493cefaa6e
* web: clear "blanked" placeholder when present (#15) - Renames "SearchSelect.ts" to "ak-search-select.ts", the better to reflect that it is a web component. - Moves it into an independent folder named "SearchSelect" so that all existing folders that use it don't need any renaming or manipulation. - Refactors SearchSelect.ts in the following ways: - Re-arranges the properties declaration so the seven properties actually used by callers are at the top; comments and documents every property. - Separates out the `renderItem` and `renderEmptyItem` HTML blocks into their own templates. - Separates `renderItem` further into `renderItemWithDescription` and `RenderItemWithoutDescription`; prior to this, there were multiple conditionals handling the description issue - Separates `renderItems` into `renderItemsAsGroups` and `renderItems`; this documents what each function does and removes multiple conditionals - Isolates the `groupedItems()` logic into a single method, moving the *how* away from the *what*. - Replaces the manual styling of `renderMenu()` into a lit-element `styleMap()`. This makes the actual render a lot more readable! - Refactors the `value` logic into its own method, as a _getter_. - Refactors the ad-hoc handlers for `focus`, `input`, and `blur` into functions on the `render()` method itself. - Alternatively, I could have put the handlers as methods on the ak-search-select Node itself; Lit would automatically bind `this` correctly if referenced through the `@event` syntax. Moving them *out* of the `render()` method would require significantly more testing, however, as that would change the code flow enough it might have risked the original behavior. By leaving them in the `render()` scope, this guarantees their original behavior -- whether that behavior is correct or not. - FIXES #15 - Having isolated as much functionality as was possible, it was easy to change the `onFocus()` event so that when the user focuses on the `<input>` object, if it's currently populated with the empty option and the user specified `isBlankable`, clear it. - **Notice**: This creates a new, possibly undesirable behavior; since it's not possible to know *why* the input object is currently empty, in the event that it is currently empty as a result of this clearing there is no way to know when the "empty option" marker needs to be put back. This is an incredibly complex bit of code, the sort that really shouldn't be written by application teams. The behavior is undefined in a number of cases, and although none of those cases are fatal, some of them are quite annoying. I recommend that we seriously consider adopting a third-party solution. Selects (and DataLists) are notoriously difficult to get right on the desktop; they are almost impossible to get right on mobile. Every responsible implementation of Selects has a "default-to-native" experience on mobile because, for the most part, the mobile native experience is excellent -- delta wanting two-line `<option>` blocks and `<optiongroup>`s, both of which we do want. This component implements: - Rendering the `<input>` element and handling its behavior - Rendering the `<select>` element and handling its behavior - Mediating between these two components - Fetching the data for the `<select>` component from the back-end - Filtering the data via a partial-match search through the `<input>` element - Distinguishing between hard-affirm and soft-affirm "No choice" options - Dispatching the `<select>` element via a portal, the better to control rendering. That's a *lot* of responsibilities! And it makes Storybooking this component non-viable. I recommend breaking this up further, but I've already spent a lot of time just doing the refactoring and getting the new behavior as right as possible, so for now I'm just going to submit the clean-up and come back to this later. * web: refactor search-select and fix placeholder * web: refactor search-select and fix placeholder; fix misleading comment * backport changes Signed-off-by: Jens Langhammer <jens@goauthentik.io> * Fix display issue when using "grouped" select lists --------- Signed-off-by: Jens Langhammer <jens@goauthentik.io> Co-authored-by: Jens Langhammer <jens@goauthentik.io>
authentik WebUI
This is the default UI for the authentik server. The documentation is going to be a little sparse for awhile, but at least let's get started.
The Theory of the authentik UI
In Peter Naur's 1985 essay Programming as Theory Building, programming is described as creating a mental model of how a program should run, then writing the code to test if the program can run that way.
The mental model for the authentik UI is straightforward. There are five "applications" within the UI, each with its own base URL, router, and responsibilities, and each application needs as many as three contexts in which to run.
The three contexts corresponds to objects in the API's model section, so let's use those names.
- The root
Config. The root configuration object of the server, containing mostly caching and error reporting information. This is misleading, however; theConfigobject contains some user information, specifically a list of permissions the current user (or "no user") has. - The root
CurrentTenant. This describes theBrandinformation UIs should use, such as themes, logos, favicon, and specific default flows for logging in, logging out, and recovering a user password. - The current
SessionUser, the person logged in: username, display name, and various states. (Note: the authentik server permits administrators to "impersonate" any other user in order to debug their authentikation experience. If impersonation is active, theuserfield reflects that user, but it also includes a field,original, with the administrator's information.)
(There is a fourth context object, Version, but its use is limited to displaying version information and checking for upgrades. Just be aware that you will see it, but you will probably never interact with it.)
There are five applications. Two (loading and api-browser) are trivial applications whose
insides are provided by third-party libraries (Patternfly and Rapidoc, respectively). The other
three are actual applications. The descriptions below are wholly from the view of the user's
experience:
Flow: From a given URL, displays a form that requests information from the user to accomplish a task. Some tasks require the user to be logged in, but many (such as logging in itself!) obviously do not.User: Provides the user with access to the applications they can access, plus a few user settings.Admin: Provides someone with super-user permissions access to the administrative functions of the authentik server.
Mental Model
- Upon initialization, every authentik UI application fetches
ConfigandCurrentTenant.UserandAdminwill also attempt to load theSessionUser; if there is none, the user is kicked out to theFlowfor logging into authentik itself. Config,CurrentTenant, andSessionUser, are provided by the@goauthentik/apiapplication, not by the codebase under./web. (Where you are now).Flow,User, andAdminare all calledInterfacesand are found in./web/src/flow/FlowInterface,./web/src/user/UserInterface,./web/src/admin/AdminInterface, respectively.
Inside each of these you will find, in a hierarchal order:
- The context layer described above
- A theme managing layer
- The orchestration layer:
- web socket handler for server-generated events
- The router
- Individual routes for each vertical slice and its relationship to other objects:
Each slice corresponds to an object table on the server, and each slice usually consists of the following:
- A paginated collection display, usually using the
Tablefoundation (found in./web/src/elements/Table) - The ability to view an individual object from the collection, which you may be able to:
- Edit
- Delete
- A form for creating a new object
- Tabs showing that object's relationship to other objects
- Interactive elements for changing or deleting those relationships, or creating new ones.
- The ability to create new objects with which to have that relationship, if they're not part of the core objects (such as User->MFA authenticator apps, since the latter is not a "core" object and has no tab of its own).
We are still a bit "all over the place" with respect to sub-units and common units; there are
folders common, elements, and components, and ideally they would be:
common: non-UI related libraries all of our applications needelements: UI elements shared among multiple applications that do not need contextcomponents: UI elements shared among multiple that use one or more context
... but at the moment there are some context-sensitive elements, and some UI-related stuff in
common.
Comments
NOTE: The comments in this section are for specific changes to this repository that cannot be reliably documented any other way. For the most part, they contain comments related to custom settings in JSON files, which do not support comments.
tsconfig.json:compilerOptions.useDefineForClassFields: falseis required to make TSC use the "classic" form of field definition when compiling class definitions. Storybook does not handle the ESNext proposed definition mechanism (yet).compilerOptions.plugins.ts-lit-plugin.rules.no-unknown-tag-name: "off": required to support rapidoc, which exports its tag late.compilerOptions.plugins.ts-lit-plugin.rules.no-missing-import: "off": lit-analyzer currently does not support path aliases very well, and cannot find the definition files associated with imports using them.compilerOptions.plugins.ts-lit-plugin.rules.no-incompatible-type-binding: "warn": lit-analyzer does not support generics well when parsing a subtype ofHTMLElement. As a result, this threw too many errors to be supportable.