@wssto2/vue-core 0.1.0 → 0.3.0

package/dist/access/catalogue.d.ts

@@ -0,0 +1,64 @@
+import type { AccessQualifier } from "../platform";
+/**
+ * What go-core's catalogue says about one permission: the shape of `authzts`'s `PermissionMeta`, so the
+ * `permissions` object its generator writes (`frontend/generated/permissions.ts`) is the catalogue as it is.
+ */
+export interface PermissionMeta {
+    readonly module: string;
+    /** Empty for a permission of the module itself. */
+    readonly resource: string;
+    readonly verb: string;
+    /** i18n keys; the texts live in the application. */
+    readonly labelKey: string;
+    readonly descriptionKey: string;
+    readonly sensitive: boolean;
+    readonly system: boolean;
+    readonly organizationOnly: boolean;
+    /** The record type the "whose" qualifiers refer to; null when the permission has no owner. */
+    readonly ownable: string | null;
+    readonly unownedIsOwn: boolean;
+    readonly feature: string | null;
+    readonly attributes: readonly string[];
+    readonly requires: readonly string[];
+}
+/** Every permission of the application by identifier (`module.resource:verb`). */
+export type PermissionCatalogue = Readonly<Record<string, PermissionMeta>>;
+/** A permission with its identifier. */
+export interface PermissionEntry extends PermissionMeta {
+    readonly id: string;
+}
+/** The permissions of one screen (a resource of a module). */
+export interface PermissionScreen {
+    /** `module` or `module_resource` (dots turned into underscores): the i18n key of its heading, under `access.resources`. */
+    readonly key: string;
+    readonly permissions: readonly PermissionEntry[];
+}
+/** One tab of the editor: a module's screens. Permissions that run the system are together in the group `system`. */
+export interface PermissionGroup {
+    readonly key: string;
+    readonly screens: readonly PermissionScreen[];
+}
+export declare const SYSTEM_GROUP = "system";
+export declare const groupOf: (meta: Pick<PermissionMeta, "module" | "system">) => string;
+export declare const screenKeyOf: (meta: Pick<PermissionMeta, "module" | "resource">) => string;
+/** The catalogue as the editor shows it: module, then screen, then action (view, create, update, manage, delete, the rest by name). */
+export declare function permissionTree(catalogue: PermissionCatalogue): readonly PermissionGroup[];
+/** Everything `id` needs, transitively (not `id` itself). */
+export declare function requiredClosure(catalogue: PermissionCatalogue, id: string): string[];
+/** Everything that needs `id`, transitively (not `id` itself). */
+export declare function dependantsClosure(catalogue: PermissionCatalogue, id: string): string[];
+/** What a role holds: each permission with whose records it reaches (`all` for a permission that has no owner). */
+export type Grants = Record<string, AccessQualifier>;
+/** The whose the role holds of a record type: its view permission's, else any granted one's; null when it holds none. */
+export declare function ownableQualifier(catalogue: PermissionCatalogue, grants: Grants, ownable: string): AccessQualifier | null;
+/** Grants `id` and what it needs; the whose of an ownable one is what the role already holds of its record type, else `own`. */
+export declare function grant(catalogue: PermissionCatalogue, grants: Grants, id: string): void;
+/** Takes `id` away, and what needs it. */
+export declare function revoke(catalogue: PermissionCatalogue, grants: Grants, id: string): void;
+/** Applies one whose to every granted permission of the record type. */
+export declare function setOwnableQualifier(catalogue: PermissionCatalogue, grants: Grants, ownable: string, qualifier: AccessQualifier): void;
+/**
+ * Grants what the granted permissions need but the role lacks (a role saved before a permission gained a
+ * requirement, which the server would refuse as it is). Returns what was added.
+ */
+export declare function completeRequired(catalogue: PermissionCatalogue, grants: Grants): string[];

package/dist/access/context.d.ts

@@ -0,0 +1,20 @@
+import type { RouteLocationRaw } from "vue-router";
+import type { ScopeOptions, SubjectRef } from "../modules/access/entities";
+import type { PermissionCatalogue } from "./catalogue";
+/** What the access screens need from the feature that installed them. */
+export interface AccessContext {
+    readonly catalogue: PermissionCatalogue;
+    /** Where a holder's name leads (their record), or null for a name that is not a link. */
+    readonly subjectRoute: (subject: SubjectRef) => RouteLocationRaw | null;
+    /** The places `subject` may be given roles at; by default what the server says (`GET /v1/iam/users/:id/scopes`). */
+    readonly scopes: ((subject: SubjectRef, signal: AbortSignal) => Promise<ScopeOptions>) | null;
+}
+export declare const accessContextKey: import("vue").InjectionKey<AccessContext>, useAccessContext: () => AccessContext;
+/** The permissions go-core's access module guards its routes with: fixed, so a screen can name them. */
+export declare const accessPermissions: {
+    readonly viewRoles: "iam.role:view";
+    readonly manageRoles: "iam.role:manage";
+    readonly deleteRoles: "iam.role:delete";
+    readonly viewAccess: "iam.user:view";
+    readonly manageBindings: "iam.user:manage";
+};

package/dist/access/effective.d.ts

@@ -0,0 +1,42 @@
+import type { AccessQualifier } from "../platform";
+import type { EffectiveGrant, EffectivePermission, Scope } from "../modules/access/entities";
+import { type PermissionCatalogue } from "./catalogue";
+/** A role that gives a screen's permissions, with the widest whose it gives them at. */
+export interface EffectiveSource {
+    readonly roleKey: string;
+    readonly roleName: string;
+    readonly qualifier: AccessQualifier;
+    readonly scope: Scope;
+}
+/** One permission the person holds, with every grant behind it. */
+export interface EffectiveAction {
+    readonly permission: string;
+    readonly verb: string;
+    /** Granted by a role but switched off for this tenant. */
+    readonly unavailable: boolean;
+    readonly grants: readonly EffectiveGrant[];
+}
+/** One screen: what is held of it, which roles give it, and how wide. */
+export interface EffectiveScreen {
+    readonly key: string;
+    readonly actions: readonly EffectiveAction[];
+    readonly sources: readonly EffectiveSource[];
+    /** The widest whose over the screen's ownable actions; null when none of them is ownable. */
+    readonly qualifier: AccessQualifier | null;
+    /** Where the screen's permissions apply, each place once, the root first. */
+    readonly scopes: readonly Scope[];
+    readonly ownable: boolean;
+    /** Every action here is switched off for the tenant. */
+    readonly allUnavailable: boolean;
+}
+export interface EffectiveGroup {
+    readonly key: string;
+    readonly screens: readonly EffectiveScreen[];
+}
+/**
+ * *What a person can do*: the effective permissions by module and screen, worked out from the roles. The server sends one entry per
+ * permission with every grant behind it (`EffectivePermission.grants`); this turns them into the rows the panel shows: a screen with the
+ * actions held, the roles that give them, and how wide (whose records, which places). A permission the catalogue does not know (a role
+ * saved before it was removed) is grouped by its module and shown by its identifier.
+ */
+export declare function groupEffective(catalogue: PermissionCatalogue, effective: readonly EffectivePermission[]): readonly EffectiveGroup[];

package/dist/access/feature.d.ts

@@ -0,0 +1,27 @@
+import type { RouteLocationRaw } from "vue-router";
+import { type Feature } from "../app";
+import type { ScopeOptions, SubjectRef } from "../modules/access/entities";
+import type { Destination } from "../router";
+import type { PermissionCatalogue } from "./catalogue";
+export interface AccessFeatureOptions {
+    /**
+     * The application's permissions: the `permissions` object go-core's `authzts` writes (`frontend/generated/permissions.ts`).
+     * The role editor's tree is this catalogue; the texts are the application's (`labelKey`, `access.modules.<module>`, ...).
+     */
+    catalogue: PermissionCatalogue;
+    /** Where a holder's name leads (their record). Default: nowhere, the name is not a link. */
+    subjectRoute?: (subject: SubjectRef) => RouteLocationRaw | null;
+    /** The places a person may be given roles at. Default: what the server says (`GET /v1/iam/users/:id/scopes`). */
+    scopes?: (subject: SubjectRef, signal: AbortSignal) => Promise<ScopeOptions>;
+    /** The backend's navigation destination that opens the roles list. Without it the application links to `accessPages.roles` itself. */
+    destination?: Destination;
+}
+/**
+ * The screens of go-core's access module, one feature to install: the roles list (`/iam/roles`), a role's page and the editor of
+ * a new role (`/iam/roles/new`, `?copy=` to start from another role), compare and replace, with every action behind the module's
+ * own permissions (`iam.role:view`, `manage`, `delete`). Pair it with `identityFeature()`; the module's routes must be mounted
+ * on the server (`access.Install`).
+ *
+ *   createApplication({ platform, shell: backofficeShell(), features: [identityFeature(), accessFeature({ catalogue: permissions })] })
+ */
+export declare function accessFeature(options: AccessFeatureOptions): Feature;

package/dist/access/index.d.ts

@@ -0,0 +1,13 @@
+export type * from "../modules/access/entities";
+export type * as Inputs from "../modules/access/schemas";
+export { accessRoutes } from "../modules/access/routes";
+export { accessFeature } from "./feature";
+export type { AccessFeatureOptions } from "./feature";
+export { accessPages, personRolesSection } from "./routes";
+export { accessPermissions } from "./context";
+export { dependantsClosure, permissionTree, requiredClosure } from "./catalogue";
+export type { Grants, PermissionCatalogue, PermissionEntry, PermissionGroup, PermissionMeta, PermissionScreen } from "./catalogue";
+export { useAccessLabels } from "./labels";
+export { useRefusalMessage } from "./refusals";
+export { default as PersonAccess } from "./PersonAccess.vue";
+export { default as BindingRow } from "./BindingRow.vue";

package/dist/access/index.js

@@ -0,0 +1,15 @@
+import { _ as a, i as c, j as o, c as r, b as n, k as i, l as u, p as l, m as p, n as t, u as d, f as m } from "../index-B2dbYZR9.js";
+export {
+  a as BindingRow,
+  c as PersonAccess,
+  o as accessFeature,
+  r as accessPages,
+  n as accessPermissions,
+  i as accessRoutes,
+  u as dependantsClosure,
+  l as permissionTree,
+  p as personRolesSection,
+  t as requiredClosure,
+  d as useAccessLabels,
+  m as useRefusalMessage
+};

package/dist/access/labels.d.ts

@@ -0,0 +1,35 @@
+/** A role as the screens name it: predefined roles by their key, custom ones by the name they were saved with. */
+export interface RoleName {
+    readonly key?: string | null;
+    readonly name: string;
+}
+/** A place as the server names it. */
+export interface ScopeName {
+    readonly level: string;
+    readonly name?: string | null;
+}
+/**
+ * The words of access. The library's own texts are `core.access.*`; the application's catalogue
+ * brings its own: a permission's label and description by the keys the catalogue holds, modules under
+ * `access.modules.<module>`, screens under `access.resources.<module_resource>`, record types under
+ * `access.ownable.<type>`, predefined roles under `access.roles.<key>`, hierarchy levels under
+ * `access.levels.<level>`. A name nobody wrote a text for is shown as it is.
+ */
+export declare function useAccessLabels(): {
+    roleName: (role: RoleName) => string;
+    permissionLabel: (id: string) => string;
+    permissionDescription: (id: string) => string;
+    groupLabel: (group: string) => string;
+    screenLabel: (key: string) => string;
+    ownableLabel: (ownable: string) => string;
+    qualifierLabel: (qualifier: string) => string;
+    qualifierHint: (qualifier: string) => string;
+    qualifierNoun: (qualifier: string) => string;
+    levelLabel: (level: string) => string;
+    /** A place: the level and its name (`Dealer · Auto Zagreb`); the root, which has no name, by its level. */
+    scopeLabel: (scope: ScopeName) => string;
+    roleKind: (role: {
+        predefined: boolean;
+        computed: boolean;
+    }) => string;
+};

package/dist/access/refusals.d.ts

@@ -0,0 +1,6 @@
+/**
+ * For a form's `failureMessage`: a refusal of go-core's delegation rules (`authz.escalation`, `self_assignment`, `last_admin`,
+ * `role_in_use`, ...) says which rule it was, in the app's language (`core.errors.authz.*`, overridable with `errors.authz.*`);
+ * any other failure keeps the form's own sentence for its kind. Call it in `setup`.
+ */
+export declare function useRefusalMessage(): (kind: unknown, error: unknown) => string | undefined;

package/dist/access/routes.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The pages of the access feature as typed targets (`accessPages.role({ ref })`), for a link from the application's own
+ * pages. `/iam/roles/new` is declared before `/iam/roles/:ref`, so "new" is never read as a role's ref.
+ */
+export declare const accessPages: import("../router").DefinedRoutes<{
+    readonly roles: {
+        readonly name: "access.roles";
+        readonly path: "/iam/roles";
+        readonly component: () => Promise<typeof import("./RolesPage.vue")>;
+        readonly meta: {
+            readonly access: "iam.role:view";
+            readonly titleKey: "core.access.title";
+        };
+    };
+    readonly newRole: {
+        readonly name: "access.roles.new";
+        readonly path: "/iam/roles/new";
+        readonly component: () => Promise<typeof import("./NewRolePage.vue")>;
+        readonly meta: {
+            readonly access: "iam.role:manage";
+            readonly titleKey: "core.access.new_title";
+        };
+    };
+    readonly role: {
+        readonly name: "access.role";
+        readonly path: "/iam/roles/:ref";
+        readonly component: () => Promise<typeof import("./RolePage.vue")>;
+        readonly meta: {
+            readonly access: "iam.role:view";
+            readonly titleKey: "core.access.title";
+            readonly remountOnParam: "ref";
+        };
+    };
+}>;
+/**
+ * What a person's record needs to list *Roles* among its sections (`meta` of a child route whose component shows `PersonAccess`): the
+ * label, the icon and the permission go-core guards the person's access with. Spread it into the route's `meta`.
+ */
+export declare const personRolesSection: {
+    readonly access: "iam.user:view";
+    readonly section: {
+        readonly labelKey: "core.access.person_roles";
+        readonly icon: "shieldStarFill";
+    };
+};

package/dist/access/scopes.d.ts

@@ -0,0 +1,20 @@
+import type { ScopeOption, ScopeOptions } from "../modules/access/entities";
+/** A way to say where a role applies: a level of the hierarchy, and the chain of places down to it (a dealer, then its location). */
+export interface ScopeLevel {
+    readonly level: string;
+    /** The levels from just below the root down to this one; empty for the root itself. */
+    readonly chain: readonly string[];
+}
+/**
+ * The levels a person may be given roles at, from what the server says (`GET /v1/iam/users/:id/scopes`): each level that has places,
+ * narrowest first, then the root when roles may be given there. The hierarchy is read off the places (each says its parent level), so
+ * the library knows no level names.
+ */
+export declare function scopeLevels(options: ScopeOptions): readonly ScopeLevel[];
+/** Where to start: the broadest level below the root (the usual choice), else the root. */
+export declare const defaultLevel: (levels: readonly ScopeLevel[]) => ScopeLevel | null;
+/**
+ * The places to choose from at step `index` of `level`'s chain, given what was chosen above (`chosen[i]` is the id at `chain[i]`). A place
+ * that has nothing below it in the chain is left out when the level is deeper: it could not complete a choice.
+ */
+export declare function placesAt(options: ScopeOptions, level: ScopeLevel, index: number, chosen: readonly (number | null)[]): readonly ScopeOption[];

package/dist/app/application.d.ts

@@ -59,6 +59,11 @@ export interface ApplicationLocaleOptions {
     fallback?: string;
     /** The locales the application offers. Default: the library's (`en`, `hr`, `bs`, `sl`). */
     supported?: readonly string[];
+    /**
+     * The flag shown beside each locale's name in the language menu, as an ISO 3166-1 country code: `{ en: "GB", sl: "SI" }`.
+     * A flag stands for a language here, so the app chooses (English is not one country). No entry: the name alone.
+     */
+    flags?: Readonly<Record<string, string>>;
     /**
      * Called after a switch to another locale committed (not for the start locale, a switch to the locale already active, or a
      * switch a later one superseded), so the application can save the choice on the user. Not awaited: the page has already

package/dist/app/contributions.d.ts

@@ -1,5 +1,5 @@
 import { type PropType } from "vue";
-import type { Session } from "../platform/session";
+import { type Session } from "../platform/session";
 import type { ShellContribution, ShellSlot } from "./feature";
 /** A contribution with the feature that declared it, for error messages. */
 export interface OwnedContribution {

package/dist/app/environment.d.ts

@@ -22,6 +22,8 @@ export interface ApplicationEnvironment {
     /** The active locale. */
     readonly locale: Readonly<Ref<string>>;
     readonly locales: readonly string[];
+    /** The flag country of each locale that has one (`{ en: "GB" }`); a locale without one shows no flag. */
+    readonly localeFlags: Readonly<Record<string, string>>;
     /** Switches the locale once the texts in use exist in it; see `MessageRuntime.setLocale`. */
     setLocale(locale: string): Promise<boolean>;
     /** Tries the start again after a failed one. */

package/dist/app/feature.d.ts

@@ -20,6 +20,7 @@ export declare function provideContext<T>(key: InjectionKey<T>, value: T): Conte
  *
  * - `headerActions`: the actions of the top bar (a notification bell, a search button)
  * - `accountMenu`: entries of the signed-in user's menu
+ * - `banner`: a strip across the top of the whole shell, above everything (a notice that must stay in view: signed in as somebody else)
  * - `host`: components with no place of their own that must be mounted once (a command palette, a dialog host)
  */
 export interface ShellSlots {
@@ -27,6 +28,7 @@ export interface ShellSlots {
 interface DocumentedShellSlots {
     headerActions: true;
     accountMenu: true;
+    banner: true;
     host: true;
 }
 export type ShellSlot = keyof DocumentedShellSlots | keyof ShellSlots;
@@ -93,6 +95,11 @@ export interface FeatureDefinition {
     effects?: readonly FeatureEffect[];
     /** Capabilities the backend must report (`platform.config.capabilities`); startup fails naming this feature when one is missing. */
     backend?: readonly string[];
+    /**
+     * The feature shows its own prompt when a session expires in the middle of work (a sheet to sign in again), so the
+     * router keeps the person on their page instead of sending them to the login page.
+     */
+    holdsExpiredSession?: boolean;
     /** Features that must be installed too (for a shared integration); checked, never installed for you. */
     requires?: readonly FeatureReference[];
 }
@@ -106,6 +113,7 @@ export interface Feature {
     readonly contributions: readonly ShellContribution[];
     readonly effects: readonly FeatureEffect[];
     readonly backend: readonly string[];
+    readonly holdsExpiredSession: boolean;
     readonly requires: readonly string[];
 }
 /** Whether `value` came from `defineFeature`. */