@api-client/ui 0.5.58 → 0.6.0

package/src/modeling/types.ts

@@ -0,0 +1,279 @@
+import { type DataDomain, DomainEntityKind, DomainModelKind, DomainNamespaceKind } from '@api-client/core/browser.js'
+import type { SupportedInputTypes } from '../types/input.js'
+
+/**
+ * Names of the operations supported in the API modeling.
+ */
+export type ApiModelOperationName = 'list' | 'read' | 'create' | 'update' | 'delete' | 'search'
+/**
+ * The target of the access configuration.
+ */
+export type ApiModelAccessTarget = 'api' | 'action' | 'endpoint'
+
+export interface DomainPropertyInputConfig {
+  /**
+   * The input's type
+   */
+  type: SupportedInputTypes
+  /**
+   * The `pattern` to set on the input.
+   */
+  pattern?: string
+  /**
+   * The `min` to set on the input.
+   */
+  min?: number
+  /**
+   * The `max` to set on the input.
+   */
+  max?: number
+  /**
+   * The `step` to set on the input.
+   */
+  step?: number
+  /**
+   * The `supportingText` to set on the Material Text Field.
+   */
+  help?: string
+}
+
+/**
+ * Information about the selected item in the domain/schema editor.
+ */
+export interface DomainSelectionInfo {
+  /**
+   * The key of the selected item
+   */
+  key: string
+  /**
+   * THe kind of the selected item
+   */
+  kind: string
+  /**
+   * Optionally, the parent odf the selected item, if any.
+   */
+  parent?: string
+  /**
+   * The domain of the selected item
+   */
+  domain: string
+}
+
+/**
+ * In the schema editor, information about the current selection
+ * and field selection.
+ */
+export interface SchemaSelectionInfo {
+  /**
+   * The selection to apply to the current domain.
+   */
+  selection?: DomainSelectionInfo
+  /**
+   * The field selection to apply to the current domain.
+   */
+  field?: DomainSelectionInfo
+}
+
+/**
+ * Items allowed to pick in the Domain Browser.
+ *
+ * - `entity` - allows to pick an entity from the local domain or external one
+ *              when configured by the `withExternal` property.
+ * - `data-model` - allows to pick a data model from the local domain or external one
+ *                  when configured by the `withExternal` property.
+ * - `data-namespace` - Only valid when `withExternal` is set.
+ */
+export type DomainBrowserPickItem = typeof DomainEntityKind | typeof DomainModelKind | typeof DomainNamespaceKind
+
+/**
+ * The reason to browse the domain:
+ * - `pick` - to select a domain element specified in the `allowed` property.
+ *
+ * More options may be introduced in the future, like 'move' or 'link'.
+ */
+export type DomainBrowserPickReason = 'pick'
+
+/**
+ * The configuration to initialize the Domain Browser element.
+ */
+export interface DomainBrowseInit {
+  /**
+   * The reason to browse the domain.
+   */
+  reason: DomainBrowserPickReason
+  /**
+   * The data domain to browse.
+   */
+  domain: DataDomain
+  /**
+   * Specifies which items are allowed to select in the UI to return the result
+   * back to the application. By default all data domain items are allowed.
+   */
+  allowed?: DomainBrowserPickItem[]
+  /**
+   * When set, it presents the user with the list of recently picked
+   * values. This improves the user experience when the pick action
+   * happens multiple times in a workflow.
+   *
+   * Note, when `withExternal` is not set then it will filter out recent items
+   * belonging to other namespace.
+   */
+  withRecent?: boolean
+}
+
+export type DomainBrowseResult =
+  | {
+      /**
+       * The user has picked the value.
+       */
+      result: 'ok'
+      /**
+       * The key of the selected item.
+       */
+      selected: string
+      /**
+       * The kind of the selected item.
+       */
+      kind: string
+      /**
+       * The key of the parent data domain.
+       */
+      domain: string
+    }
+  | {
+      /**
+       * The user has canceled the dialog.
+       */
+      result: 'canceled'
+    }
+
+export interface DomainBrowseRecentItem {
+  /**
+   * The key of the item.
+   */
+  key: string
+  /**
+   * The kind of the item.
+   */
+  kind: string
+  /**
+   * The label of the item.
+   */
+  label: string
+  /**
+   * The domain key of the item.
+   */
+  domain: string
+  /**
+   * The last time the item was picked represented as a timestamp.
+   * This is used to sort the items in the list.
+   * The most recent item is always at the top of the list.
+   */
+  used: number
+}
+
+export interface DomainBrowseRecentItems {
+  /**
+   * The list of recent items.
+   */
+  items: DomainBrowseRecentItem[]
+  /**
+   * The last time the list was updated.
+   * It is the timestamp of the last time the list was saved to the local storage.
+   */
+  updated: number
+}
+
+export interface DomainRenameEventDetail {
+  /**
+   * The key of the domain element that was renamed.
+   */
+  key: string
+  /**
+   * The new label of the domain element.
+   */
+  label: string
+  /**
+   * The namespace of the domain element.
+   */
+  namespace: string
+  /**
+   * The kind of the domain element.
+   */
+  kind: string
+}
+
+export interface DomainBrowseEventDetail extends DomainBrowseInit {
+  /**
+   * The promise set by the event listener to return the domain browse result.
+   * If undefined after the event is dispatched, it means the event was not handled.
+   */
+  result?: Promise<DomainBrowseResult | undefined>
+}
+
+/**
+ * The detail of the custom event dispatched to request the domain recent items.
+ */
+export interface DomainRecentEventDetail {
+  /**
+   * The key of the data domain to load recent items for.
+   */
+  domain: string
+  /**
+   * The allowed items to pick, if any.
+   */
+  allowed?: DomainBrowserPickItem[]
+  /**
+   * The promise set by the event listener to return the recent items.
+   * If undefined after the event is dispatched, it means the event was not handled.
+   */
+  result?: Promise<DomainBrowseRecentItem[] | undefined>
+}
+
+/**
+ * Event detail for the auto fields selection result
+ */
+export interface AutoFieldsSelectionResult {
+  selectedFields: string[]
+}
+
+/**
+ * Auto field definition
+ */
+export interface AutoFieldDefinition {
+  id: string
+  name: string
+  description: string
+}
+
+/**
+ * Auto field category definition
+ */
+export interface AutoFieldCategory {
+  name: string
+  fields: AutoFieldDefinition[]
+}
+
+/**
+ * Information about the selected item in the Domain Browser.
+ * Used with the `select` custom event as the detail.
+ */
+export interface DomainBrowseSelectedItem {
+  /**
+   * The key of the selected item.
+   */
+  key: string
+  /**
+   * The kind of the selected item.
+   */
+  kind: string
+  /**
+   * The namespace key of the selected item.
+   */
+  namespace: string
+  /**
+   * Whether the selected item is a parent item.
+   * This is set to true for `DomainModel` and `DomainNamespace` kinds.
+   */
+  isParent?: boolean
+}

package/src/providers/organization.ts

@@ -0,0 +1,7 @@
+import { createContext } from '@lit/context'
+import type { IOrganization } from '@api-client/core/models/store/Organization.js'
+export type { IOrganization } from '@api-client/core/models/store/Organization.js'
+/**
+ * A context that provides the currently selected organization.
+ */
+export const organizationContext = createContext<IOrganization | undefined>('current-organization')

package/src/providers/organizations.ts

@@ -0,0 +1,7 @@
+import { createContext } from '@lit/context'
+import type { IOrganization } from '@api-client/core/models/store/Organization.js'
+export type { IOrganization } from '@api-client/core/models/store/Organization.js'
+/**
+ * A context that provides the list of available organizations.
+ */
+export const organizationsContext = createContext<IOrganization[] | undefined>('current-organizations')

package/src/providers/user.ts

@@ -0,0 +1,7 @@
+import { createContext } from '@lit/context'
+import type { IUser } from '@api-client/core/models/store/User.js'
+export type { IUser } from '@api-client/core/models/store/User.js'
+/**
+ * A context that provides the current user.
+ */
+export const userContext = createContext<IUser | undefined>('current-user')

package/src/services/CacheService.ts

@@ -0,0 +1,56 @@
+import { Cache, TTL } from '../cache/Cache.js'
+import { Service } from '../core/Service.js'
+
+export default class CacheService extends Service {
+  static override key = 'api-service/cache'
+
+  private cache: Cache
+
+  get TTL(): typeof TTL {
+    return TTL
+  }
+
+  constructor() {
+    super()
+    this.cache = new Cache()
+  }
+
+  getCache(): Cache {
+    return this.cache
+  }
+
+  /**
+   * Store data in the cache with optional TTL
+   *
+   * @param key - The key to store the data under
+   * @param data - The data to store
+   * @param ttl - Time to live in milliseconds
+   * @returns A promise that resolves to true if the data was stored successfully, false otherwise
+   */
+  async set<T>(key: string, data: T, ttl?: number): Promise<boolean> {
+    return this.cache.set(key, data, ttl)
+  }
+
+  /**
+   * Retrieve data from the cache with type safety
+   */
+  async get<T = unknown>(key: string): Promise<T | null> {
+    return this.cache.get(key)
+  }
+
+  /**
+   * Delete a specific cache item
+   */
+  async delete(key: string): Promise<boolean> {
+    return this.cache.delete(key)
+  }
+
+  async clear(): Promise<void> {
+    await this.cache.clear()
+  }
+
+  override async destroy(): Promise<void> {
+    await this.cache.close()
+    await super.destroy()
+  }
+}

package/src/services/ConfigurationService.ts

@@ -0,0 +1,28 @@
+import { Service } from '../core/Service.js'
+import { WebConfigurationBindings } from '../bindings/web/WebConfigurationBindings.js'
+
+export default class ConfigurationService extends Service {
+  static override key = 'api-service/config'
+  config!: WebConfigurationBindings
+
+  override async onCreate(): Promise<void> {
+    this.config = new WebConfigurationBindings()
+    return Promise.resolve()
+  }
+
+  override async onStart(): Promise<void> {
+    await this.config.initialize()
+  }
+
+  get local(): WebConfigurationBindings['local'] {
+    return this.config.local
+  }
+
+  get session(): WebConfigurationBindings['session'] {
+    return this.config.session
+  }
+
+  get telemetry(): WebConfigurationBindings['telemetry'] {
+    return this.config.telemetry
+  }
+}

package/src/services/LoggingService.ts

@@ -0,0 +1,60 @@
+import { Logger, ILogObj } from 'tslog'
+import { Service } from '../core/Service.js'
+
+export enum LogLevel {
+  Silly = 0,
+  Trace = 1,
+  Debug = 2,
+  Info = 3,
+  Warn = 4,
+  Error = 5,
+  Fatal = 6,
+}
+
+export default class LoggingService extends Service {
+  static override key = 'api-service/logger'
+
+  logger!: Logger<ILogObj>
+
+  /**
+   * 0: silly, 1: trace, 2: debug, 3: info, 4: warn, 5: error, 6: fatal
+   */
+  level = LogLevel.Error
+
+  constructor(env = 'production') {
+    super()
+    this.level = env === 'production' ? LogLevel.Trace : LogLevel.Error
+  }
+
+  protected override async onCreate(): Promise<void> {
+    this.logger = new Logger({ name: 'quick-api', type: 'pretty', minLevel: this.level })
+  }
+
+  silly(...args: unknown[]): void {
+    this.logger.silly(...args)
+  }
+
+  debug(...args: unknown[]): void {
+    this.logger.debug(...args)
+  }
+
+  info(...args: unknown[]): void {
+    this.logger.info(...args)
+  }
+
+  warn(...args: unknown[]): void {
+    this.logger.warn(...args)
+  }
+
+  error(...args: unknown[]): void {
+    this.logger.error(...args)
+  }
+
+  fatal(...args: unknown[]): void {
+    this.logger.fatal(...args)
+  }
+
+  trace(...args: unknown[]): void {
+    this.logger.trace(...args)
+  }
+}

package/src/services/OrganizationService.ts

@@ -0,0 +1,238 @@
+import { Service } from '../core/Service.js'
+import type { IOrganization, UserOrganizationGrantType } from '@api-client/core/models/store/Organization.js'
+import { CurrentOrganizationKey } from '../lib/StoreKeys.js'
+import services from './api_service.js'
+
+enum State {
+  NotChecked,
+  Checking,
+  Checked,
+}
+
+export enum CompletionState {
+  /**
+   * The user has at least one organization and the current organization is selected.
+   */
+  OK,
+  /**
+   * The user has at leas two organizations and no valid selection.
+   */
+  NotSelected,
+  /**
+   * The user have no organizations. Setup is needed.
+   */
+  NoOrganizations,
+  /**
+   * Unable to determine the state due to an error.
+   */
+  Error,
+}
+
+const OrgsCacheKey = 'user_organizations'
+
+export default class OrganizationService extends Service {
+  static override key = 'api-service/organization'
+
+  state: State = State.NotChecked
+  organizations: IOrganization[] = []
+  organizationId: string | undefined
+  /**
+   * A pending organization ID that was set via the URL query parameter `oid`.
+   * When it is set, it preselects the organization when loading list of organizations.
+   * This will override the `organizationId` set in the local storage.
+   */
+  pendingOid: string | undefined | null
+
+  /**
+   * A hidden value for the `updateComplete` getter.
+   */
+  #updateComplete?: Promise<CompletionState>
+
+  /**
+   * The resolver to call when the update completes.
+   */
+  #updateResolver?: (state: CompletionState) => void
+
+  protected override async onCreate(): Promise<void> {
+    const url = new URL(window.location.href)
+    this.pendingOid = url.searchParams.get('oid')
+  }
+
+  async getUserOrganization(id: string): Promise<IOrganization> {
+    await this.#updateComplete
+    const org = this.organizations.find((i) => i.key === id)
+    if (!org) {
+      throw new Error(`Organization with id ${id} not found`)
+    }
+    return org
+  }
+
+  async currentOrganization(): Promise<IOrganization | undefined> {
+    if (this.state === State.Checking) {
+      await this.#updateComplete
+    }
+    if (!this.organizationId) {
+      return undefined
+    }
+    // TODO: we will store the orgs list in the local/session store
+    // so we won't be pinging server with every page reload.
+    return this.organizations.find((i) => i.key === this.organizationId)
+  }
+
+  protected async hasGrantType(grantType: UserOrganizationGrantType): Promise<boolean> {
+    const org = await this.currentOrganization()
+    if (!org) {
+      return false
+    }
+    return org.grantType === grantType
+  }
+
+  async hasRoles(types: UserOrganizationGrantType[]): Promise<boolean> {
+    const org = await this.currentOrganization()
+    if (!org) {
+      return false
+    }
+    return types.includes(org.grantType)
+  }
+
+  /**
+   * Checks if the user is the owner of the current organization.
+   * @returns `true` if the user is the owner of the current organization, `false` otherwise.
+   */
+  async isOwner(): Promise<boolean> {
+    return this.hasGrantType('owner')
+  }
+
+  /**
+   * Checks if the user is a manager of the current organization.
+   * @returns `true` if the user is a manager of the current organization, `false` otherwise.
+   */
+  async isManager(): Promise<boolean> {
+    return this.hasGrantType('manager')
+  }
+
+  /**
+   * Checks if the user is an editor of the current organization.
+   * @returns `true` if the user is a editor of the current organization, `false` otherwise.
+   */
+  async isEditor(): Promise<boolean> {
+    return this.hasGrantType('editor')
+  }
+
+  /**
+   * Forces to get the list of organizations from the server.
+   *
+   * Returns one of the following states:
+   *
+   * - `CompletionState.OK` - The user has at least one organization and the current organization is selected.
+   * - `CompletionState.NotSelected` - The user has at leas two organizations and no valid selection.
+   * - `CompletionState.NoOrganizations` - The user have no organizations. Setup is needed.
+   * - `CompletionState.Error` - Unable to determine the state due to an error.
+   *
+   * @returns The state of the organization creation.
+   */
+  revalidate(): Promise<CompletionState> {
+    if (this.state === State.Checking) {
+      return this.#updateComplete as Promise<CompletionState>
+    }
+    if (this.organizationId) {
+      return Promise.resolve(CompletionState.OK)
+    }
+    this.state = State.Checking
+    this.#updateComplete = new Promise<CompletionState>((resolver) => {
+      this.#updateResolver = resolver
+    })
+    this.#getState()
+    return this.#updateComplete
+  }
+
+  /**
+   * Reads the list of organizations either from the cache or from the server.
+   */
+  async #getState(): Promise<void> {
+    const loaded = await this.#loadCache()
+    if (!loaded) {
+      try {
+        await this.#callOrganizations()
+      } catch {
+        this.#resolve(CompletionState.Error)
+        this.state = State.Checked
+        return
+      }
+    }
+    const result = await this.#readState()
+    this.state = State.Checked
+    this.#resolve(result)
+  }
+
+  async #loadCache(): Promise<boolean> {
+    const cache = await services.get('cache')
+    const orgs = await cache.get<IOrganization[]>(OrgsCacheKey)
+    if (orgs) {
+      this.organizations = orgs
+      return true
+    }
+    return false
+  }
+
+  async #saveCache(orgs: IOrganization[]): Promise<void> {
+    const cache = await services.get('cache')
+    if (orgs.length === 0) {
+      await cache.delete(OrgsCacheKey)
+    } else {
+      await cache.set<IOrganization[]>(OrgsCacheKey, orgs, cache.TTL.OneHour)
+    }
+  }
+
+  async #callOrganizations(): Promise<void> {
+    const sdk = await services.get('sdk')
+    const orgs = await sdk.organizations.list()
+    this.organizations = orgs.items || []
+    await this.#saveCache(orgs.items)
+  }
+
+  #resolve(state: CompletionState): void {
+    if (this.#updateResolver) {
+      this.#updateResolver(state)
+      this.#updateResolver = undefined
+    }
+  }
+
+  async #readState(): Promise<CompletionState> {
+    const config = await services.get('config')
+    const selected = this.pendingOid ?? ((await config.local.get(CurrentOrganizationKey)) as string | undefined)
+    this.pendingOid = undefined // Clear the pending OID after reading it
+    const hasSelected = this.organizations.some((i) => i.key === selected)
+    let result: CompletionState
+    if (selected && hasSelected) {
+      this.organizationId = selected
+      result = CompletionState.OK
+      await config.local.set(CurrentOrganizationKey, selected)
+    } else if (this.organizations.length === 1) {
+      const key = this.organizations[0].key
+      await config.local.set(CurrentOrganizationKey, key)
+      this.organizationId = key
+      result = CompletionState.OK
+    } else if (this.organizations.length) {
+      result = CompletionState.NotSelected
+    } else {
+      result = CompletionState.NoOrganizations
+    }
+    return result
+  }
+
+  /**
+   * When the user has no organizations, it set the organization as the only one
+   * and persists the organization id as the selected organization.
+   * @param org The organization to add.
+   */
+  async setupUserOrganization(org: IOrganization): Promise<void> {
+    const hasOrg = this.organizations.some((i) => i.key === org.key)
+    if (!hasOrg) {
+      this.organizations.push(org)
+    }
+    const config = await services.get('config')
+    await config.local.set(CurrentOrganizationKey, org.key)
+    this.organizationId = org.key
+  }
+}