752735d480
* web: much better focus discipline Fix the way focus is handled in SearchSelect so that the drop-down isn't grabbing the focus away from the Input when the user wants to type in their selection. Because it was broken otherwise! There's still a bug where it's possible to type in a complete value *Label*, then leave the component's focus (input and menu) completely, in which case the Label remains, looking innocent and correct, but it is *not* reflective of the value as understood by the SearchSelect API controller. Gonna try to fix that next. But I'm saving this as a useful checkpoint. * . * root: insert daphne app in correct order Signed-off-by: Jens Langhammer <jens@goauthentik.io> * web: implement ak-list-select Creates a new element, ak-list-select, which is a scrollable list that reports when an element is clicked or selected by the keyboard. I was hideously over-engineering ak-search-select-menu, and I decided to try something simpler. This is that something. The events we care about are just "change" and "lost focus", and both of those can be attached by the parent regardless of portaling. * web: ak-list-select is complete An extraction of the "menu" and "list" features from SearchSelect and DualSelect, this is a very simplified version of a visible list that emulates the Radio/Select behavior (i.e only one from the collection may be "valued" at the time). It has no visible indicators of selection (aside from some highlighting), as it's meant to be used to present the list rather than be indicative of any state of the list. I was seriously over-engineering the menu. It turns out, it's just not that difficult after all. The only things we care about, really, are "did the user change the selection," "did the user click out of the list," and "did the user press the escape key." Those are pre-existing events (click w/value, blur, and keydown w/keycode, respectively), so there was no need for me to introduce new custom events to handler them. * web: downgrade sonarjs again, because dependabot Dammit, really need to tell that machine to leave our versions alone. * web: search select After a lot of testing and experimenting, it's finally starting to look stable. What a pain in the neck this has all been. * web: hold * web: search select with focus and progressive search - New component: ak-list-select, which allows you to select from a list of elements, with keyboard control. - New component: ak-portal, which manages elements by moving "slotted" content into a distant component, usually one attached to the body, and positions it relative to an existing element. - ak-search-select-view has been revamped to handle focus, change, input, and blur using the browser native event handlers, rather than inventing my own. - ak-search-select has been turned into a simple driver that manages the view. - ak-search-select has a new declarative syntax for the most common use case. I seriously over-engineered this thing, leaning too heavily on outdated knowledge or assumptions about how the browser works. The native event handlers attached at the component's borders works more than fine, and by attaching the event handlers to the portaled component before sending it off to the slots, the correct handlers get the message. This revision leverages the browser a *lot* more, and gets much more effective interaction with much less code. `<ak-list-select>` is a new component that replaces the ad-hoc menu object of the old SearchSelect. It is a standalone component that just shows a list, allows someone to navigate that list with the keyboard or the mouse. By default, it is limited to half the height of the viewport. The list does not have an indicator of "selected" at this time. That's just a side effect of it being developed as an adjunct to search-select. Its design does not preclude extension. It has a *lot* of CSS components that can be customized. The properties and events are documented, but there is only one event: `change`. Consistent with HTML, the value is not sent with the `change` event; clients are expected to extract it with `change:event.target.value`. Like all HTML components, it is completely stringly defined; the value is either a string or undefined. `<ak-portal>` is a somewhat specialized "portal" component that places an `ak-list-select` in an object on top of the existing DOM content. It can generalized to do this with any component, though, and can be extended. It has no events or CSS, since it's "just" managing the portaling relationship. `<ak-search-select-view>` is the heart of the system. It takes a collection options and behaves like an autocomplete component for them. The only unique event it sends out is `change`, and like `ak-list-select`, it expects the client to retrieve the value. Like all HTML components, it is completely stringly defined; the value is either a string or undefined. This is the SearchSelect component we've all known to come and love, but with a better pop-up and cleaner keyboard interaction. It emits only one event, `ak-change`, which *does* carry the value with it. The Storybooks have been updated to show the current version of Search Select, with a (simulated) API layer as well as more blunt stringly-typed tests for the View layer. A handful of tests have been provided to cover a number of edge cases that I discovered during testing. These run fine with the `npx` command, and I would love to see them integrated into CI/CD. The search select fields `renderElement`, `renderDescription`, and `value` properties of `ak-search-select` have been modified to take a string. For example, the search for the list of user looks like this: ``` <ak-search-select .fetchObjects=${async (query?: string): Promise<User[]> => { const args: CoreUsersListRequest = { ordering: "username" }; if (query !== undefined) { args.search = query; } const users = await new CoreApi(DEFAULT_CONFIG).coreUsersList(args); return users.results; }} .renderElement=${(user: User): string => { return user.username; }} .renderDescription=${(user: User): TemplateResult => { return html`${user.name}`; }} .value=${(user: User | undefined): string | undefined => { return user?.username; }} ></ak-search-select> ``` The most common syntax for the these three fields is "just return the string contents of a field by name," in the case of the description wrapped in a TemplateResult with no DOM components. By automating that initialization in the `connectedCallback` of the `ak-search-select` component, this object would look like: <ak-search-select .fetchObjects=${async (query?: string): Promise<User[]> => { const args: CoreUsersListRequest = { ordering: "username" }; if (query !== undefined) { args.search = query; } const users = await new CoreApi(DEFAULT_CONFIG).coreUsersList(args); return users.results; }} .renderElement=${"username"} .renderDescription=${"name"} .value=${"username"} ></ak-search-select> ``` Due to a limitation in the way properties (such as functions) are interpreted, the syntax `renderElement="username"` is invalid; it has to be a property expression. Sorry; best I could do. The old syntax works just fine. This is a "detect and extend at runtime" enhancement. * Added comments to the Component Driver Harness. * Added more safety and comments. * web: remove string-based access to API; replace with a consolidated "adapter" layer. Clean out the string-based API layer in SearchSelect. Break SearchSelect into a "Base" that does all the work, and then wrap it in two different front-ends: one that conforms to the old WCAPI, and one with a slightly new WCAPI: ``` <ak-search-select-ez .config=${{ fetchObjects: async (query?: string): Promise<Group[]> => { const args: CoreGroupsListRequest = { ordering: "name", includeUsers: false, }; if (query !== undefined) { args.search = query; } const groups = await new CoreApi(DEFAULT_CONFIG).coreGroupsList( args, ); return groups.results; }, renderElement: (group: Group): string => group.name, value: (group: Group | undefined): string | undefined => group?.pk, selected: (group: Group): boolean => group.pk === this.instance?.group }} blankable > </ak-search-select-ez> ``` * Prettier had opinions. In one case, an important opinion. * Rename test and fix lint error. * fix lint Signed-off-by: Jens Langhammer <jens@goauthentik.io> --------- 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.
License
This code is licensed under the MIT License. A copy of the license is included with this package.