@api-client/ui 0.5.57 → 0.6.0

package/src/data/UsersModel.ts

@@ -0,0 +1,325 @@
+import { type IUser } from '@api-client/core/models/store/User.js'
+import type { InvitationSchema } from '@api-client/core/models/store/Invitation.js'
+import type { ContextListOptions, ContextListResult } from '@api-client/core/events/BaseEvents.js'
+import { Model } from '../core/Model.js'
+import { exponentialBackoffDelay, type RetryOptions, shouldRetryApiError, retry } from './retry_logic.js'
+import { fromError } from '../exceptions/builder.js'
+import type SdkService from '../services/SdkService.js'
+import { LiveData } from '../reactive/LiveData.js'
+
+enum ModelState {
+  /**
+   * Not doing anything.
+   */
+  idle,
+  /**
+   * Currently querying for file data.
+   */
+  reading,
+}
+
+export type OrgUser = InvitationSchema | IUser
+
+interface PageInfo {
+  cursor?: string
+  ended: boolean
+}
+
+export default class UsersModel extends Model<LiveData<OrgUser[]>> {
+  /**
+   * The current state of the model.
+   */
+  state: ModelState = ModelState.idle
+  /**
+   * The organization ID this model is associated with.
+   */
+  oid: string
+  /**
+   * A reference to the SDK service used to perform API calls.
+   */
+  sdk: SdkService
+
+  /**
+   * Pagination information for invitations.
+   */
+  invitationsInfo: PageInfo
+
+  /**
+   * Pagination information for users.
+   */
+  usersInfo: PageInfo
+
+  get loading(): boolean {
+    return this.state === ModelState.reading
+  }
+
+  override get value(): LiveData<OrgUser[]> {
+    return this.raw as LiveData<OrgUser[]>
+  }
+
+  constructor(oid: string, sdk: SdkService) {
+    super()
+    this.oid = oid
+    this.sdk = sdk
+    this.invitationsInfo = { ended: false }
+    this.usersInfo = { ended: false }
+    this.raw = new LiveData<OrgUser[]>([])
+  }
+
+  /**
+   * Lists users in the organization.
+   * It performs a paginated query to the API.
+   * Call this method again to fetch the next page of results.
+   */
+  async list(): Promise<void> {
+    if (this.state === ModelState.idle) {
+      this.debounce(() => this.#fetchPage())
+    }
+    await this.taskComplete
+  }
+
+  /**
+   * Checks if the model has any users.
+   * @returns True if there are users, false otherwise.
+   */
+  hasUsers(): boolean {
+    return this.value.value.length > 0
+  }
+
+  /**
+   * Finds a user by their key.
+   */
+  find(key: string): OrgUser | undefined {
+    return this.value.value.find((user) => user.key === key)
+  }
+
+  /**
+   * Adds a user to the model.
+   * @param user The user to add to the model.
+   */
+  add(user: OrgUser): void {
+    if (this.find(user.key)) {
+      throw new Error(`User with key ${user.key} already exists.`)
+    }
+    this.value.value.push(user)
+  }
+
+  /**
+   * Replaces an existing user in the model.
+   * If the user does not exist, it will be added.
+   * @param key The key of the user to remove.
+   */
+  replace(user: OrgUser): void {
+    const index = this.value.value.findIndex((u) => u.key === user.key)
+    if (index === -1) {
+      return this.add(user)
+    }
+    this.value.value[index] = user
+  }
+
+  /**
+   * Removes a user from the model.
+   * @param key The key of the user to remove.
+   */
+  remove(key: string): void {
+    const index = this.value.value.findIndex((user) => user.key === key)
+    if (index === -1) {
+      return
+    }
+    this.value.value.splice(index, 1)
+  }
+
+  async #fetchPage(): Promise<void> {
+    if (this.invitationsInfo.ended && this.usersInfo.ended) {
+      return
+    }
+    this.state = ModelState.reading
+    try {
+      await this.#fetchUsers()
+      await this.#fetchInvitations()
+    } catch (e) {
+      const err = fromError(e as Error)
+      this.notifyError(err)
+      throw err
+    } finally {
+      this.state = ModelState.idle
+    }
+  }
+
+  async #fetchUsers(): Promise<void> {
+    const operation = async (): Promise<ContextListResult<IUser>> => {
+      const options: ContextListOptions = {
+        limit: this.limit,
+        sort: 'name',
+      }
+      if (this.usersInfo.cursor) {
+        options.cursor = this.usersInfo.cursor
+      }
+      return this.sdk.organizations.users.list(this.oid, options)
+    }
+    const retryOptions: RetryOptions = {
+      retries: this.retryCount,
+      delayMs: exponentialBackoffDelay,
+      shouldRetry: shouldRetryApiError as (error: Error) => boolean,
+    }
+    const users = await retry(operation, retryOptions)
+    this.value.set(this.value.value.concat(users.items))
+    this.usersInfo.cursor = users.cursor
+    if (users.items.length < this.limit) {
+      this.usersInfo.ended = true
+    }
+  }
+
+  async #fetchInvitations(): Promise<void> {
+    const operation = async (): Promise<ContextListResult<InvitationSchema>> => {
+      const options: ContextListOptions = {
+        limit: this.limit,
+      }
+      if (this.usersInfo.cursor) {
+        options.cursor = this.usersInfo.cursor
+      }
+      return this.sdk.organizations.invitations.list(this.oid)
+    }
+    const retryOptions: RetryOptions = {
+      retries: this.retryCount,
+      delayMs: exponentialBackoffDelay,
+      shouldRetry: shouldRetryApiError as (error: Error) => boolean,
+    }
+    const invitations = await retry(operation, retryOptions)
+    this.value.set(this.value.value.concat(invitations.items))
+    this.usersInfo.cursor = invitations.cursor
+    if (invitations.items.length < this.limit) {
+      this.usersInfo.ended = true
+    }
+  }
+
+  async deactivate(uid: string): Promise<void> {
+    const { oid } = this
+    if (!uid) {
+      throw new Error('User ID (uid) is not set. Cannot deactivate user.')
+    }
+    this.state = ModelState.reading
+    const operation = async (): Promise<IUser> => {
+      return this.sdk.organizations.users.deactivate(oid, uid)
+    }
+    const retryOptions: RetryOptions = {
+      retries: this.retryCount,
+      delayMs: exponentialBackoffDelay,
+      shouldRetry: shouldRetryApiError as (error: Error) => boolean,
+    }
+    try {
+      const updated = await retry(operation, retryOptions)
+      this.replace(updated)
+    } catch (e) {
+      const err = fromError(e as Error)
+      this.notifyError(err)
+      throw err
+    } finally {
+      this.state = ModelState.idle
+    }
+  }
+
+  async activate(uid: string): Promise<void> {
+    const { oid } = this
+    if (!uid) {
+      throw new Error('User ID (uid) is not set. Cannot activate user.')
+    }
+    this.state = ModelState.reading
+    const operation = async (): Promise<IUser> => {
+      return this.sdk.organizations.users.activate(oid, uid)
+    }
+    const retryOptions: RetryOptions = {
+      retries: this.retryCount,
+      delayMs: exponentialBackoffDelay,
+      shouldRetry: shouldRetryApiError as (error: Error) => boolean,
+    }
+    try {
+      const updated = await retry(operation, retryOptions)
+      this.replace(updated)
+    } catch (e) {
+      const err = fromError(e as Error)
+      this.notifyError(err)
+      throw err
+    } finally {
+      this.state = ModelState.idle
+    }
+  }
+
+  async deleteUser(uid: string): Promise<void> {
+    const { oid } = this
+    if (!uid) {
+      throw new Error('User ID (uid) is not set. Cannot delete user.')
+    }
+    this.state = ModelState.reading
+    const operation = async (): Promise<void> => {
+      return this.sdk.organizations.users.delete(oid, uid)
+    }
+    const retryOptions: RetryOptions = {
+      retries: this.retryCount,
+      delayMs: exponentialBackoffDelay,
+      shouldRetry: shouldRetryApiError as (error: Error) => boolean,
+    }
+    try {
+      await retry(operation, retryOptions)
+      this.remove(uid)
+    } catch (e) {
+      const err = fromError(e as Error)
+      this.notifyError(err)
+      throw err
+    } finally {
+      this.state = ModelState.idle
+    }
+  }
+
+  async deleteInvitation(key: string): Promise<void> {
+    const { oid } = this
+    if (!key) {
+      throw new Error('Invitation key is not set. Cannot delete invitation.')
+    }
+    this.state = ModelState.reading
+    const operation = async (): Promise<void> => {
+      await this.sdk.organizations.invitations.delete(oid, key)
+    }
+    const retryOptions: RetryOptions = {
+      retries: this.retryCount,
+      delayMs: exponentialBackoffDelay,
+      shouldRetry: shouldRetryApiError as (error: Error) => boolean,
+    }
+    try {
+      await retry(operation, retryOptions)
+      this.remove(key)
+    } catch (e) {
+      const err = fromError(e as Error)
+      this.notifyError(err)
+      throw err
+    } finally {
+      this.state = ModelState.idle
+    }
+  }
+
+  async resendInvitation(key: string): Promise<void> {
+    const { oid } = this
+    if (!key) {
+      throw new Error('Invitation key is not set. Cannot resend invitation.')
+    }
+    this.state = ModelState.reading
+    const operation = async (): Promise<InvitationSchema> => {
+      return this.sdk.organizations.invitations.resend(oid, key)
+    }
+    const retryOptions: RetryOptions = {
+      retries: this.retryCount,
+      delayMs: exponentialBackoffDelay,
+      shouldRetry: shouldRetryApiError as (error: Error) => boolean,
+    }
+    try {
+      const updated = await retry(operation, retryOptions)
+      this.replace(updated)
+    } catch (e) {
+      const err = fromError(e as Error)
+      this.notifyError(err)
+      throw err
+    } finally {
+      this.state = ModelState.idle
+    }
+  }
+}

package/src/data/retry_logic.ts

@@ -0,0 +1,111 @@
+import type { Exception } from '@api-client/core/exceptions/exception.js'
+
+/**
+ * Defines the options for the retry mechanism.
+ */
+export interface RetryOptions {
+  /**
+   * The maximum number of retry attempts.
+   * Defaults to 3.
+   */
+  retries?: number
+  /**
+   * The delay in milliseconds before the next retry.
+   * Can be a fixed number or a function that returns a number (e.g., for exponential backoff).
+   * Defaults to 1000ms.
+   */
+  delayMs?: number | ((attempt: number) => number)
+  /**
+   * An optional function that determines if a retry should be attempted based on the error.
+   * If not provided, all errors will trigger a retry up to the maximum number of retries.
+   * @param error The error that occurred.
+   * @returns True if a retry should be attempted, false otherwise.
+   */
+  shouldRetry?: (error: Error) => boolean
+}
+
+/**
+ * Calculates an exponential backoff delay for retry attempts.
+ * The delay doubles with each attempt.
+ *
+ * @param attempt The current retry attempt number (should be 1-indexed).
+ * @param initialDelay The initial delay in milliseconds. Defaults to 1000ms.
+ * @returns The calculated delay in milliseconds.
+ */
+export function exponentialBackoffDelay(attempt: number, initialDelay = 1000): number {
+  if (attempt <= 0) return initialDelay
+  // For attempt 1, delay is initialDelay * 2^0 = initialDelay
+  return initialDelay * Math.pow(2, attempt - 1)
+}
+/**
+ * Checks if the API error should be retried based on its status code.
+ * If the status code is 404, it returns false (do not retry).
+ * For other status codes, it returns true (retry).
+ * @param error The error to check.
+ */
+export function shouldRetryApiError(error: Error): boolean {
+  const { status } = error as Exception
+  if (typeof status === 'number' && status >= 400 && status < 500) {
+    // Do not retry on 4xx errors (client errors)
+    return false
+  }
+  return true
+}
+
+/**
+ * Executes an asynchronous operation with a retry mechanism.
+ *
+ * @param operation A function that returns a Promise to be executed.
+ * @param options Optional retry configurations.
+ * @returns A Promise that resolves with the result of the operation or rejects if all retries fail.
+ * @example
+ * ```typescript
+ * import { shouldRetryApiError, exponentialBackoffDelay, retry } from '../data/retry_logic.js'
+ *
+ * override async create(data: Partial<IUser>): Promise<IUser> {
+ *   const operation = async (): Promise<UserData> => {
+ *     // ... perform API call or other async operation
+ *   }
+ *   const retryOptions: RetryOptions = {
+ *     retries: 5,
+ *     delayMs: exponentialBackoffDelay,
+ *     shouldRetry: shouldRetryApiError,
+ *   }
+ *   const data = await retry(operation, retryOptions)
+ *   this.dispatchEvent(new CustomEvent('data-changed', { detail: data }))
+ *   return data
+ * }
+ * ```
+ */
+export async function retry<R>(operation: () => Promise<R>, options: RetryOptions = {}): Promise<R> {
+  const { retries = 3, delayMs = 1000, shouldRetry = () => true } = options
+
+  let lastError: Error | undefined
+
+  for (let attempt = 0; attempt < retries; attempt++) {
+    try {
+      return await operation()
+    } catch (e) {
+      lastError = e as Error
+      if (!shouldRetry(lastError) || attempt === retries - 1) {
+        // Do not retry if shouldRetry returns false or if it's the last attempt
+        throw lastError
+      }
+
+      const delay = typeof delayMs === 'function' ? delayMs(attempt + 1) : delayMs
+      if (delay > 0) {
+        await new Promise((resolve) => setTimeout(resolve, delay))
+      }
+    }
+  }
+  // This part should ideally not be reached if retries > 0,
+  // as the loop would throw on the last attempt.
+  // However, to satisfy TypeScript and guard against retries = 0:
+  if (lastError) {
+    throw lastError
+  }
+  // Should not happen if operation is called at least once.
+  // Adding a generic error for completeness.
+  const err = new Error('Retry operation failed without a specific error.')
+  throw err
+}

package/src/elements/autocomplete/internals/autocomplete.ts

@@ -398,9 +398,12 @@ export default class Autocomplete extends LitElement {
     // We use the manual popover mode, so we need to close suggestions
     // when the input loses focus, but only the current active element is not part of the suggestions.
     requestAnimationFrame(() => {
+      // Get the root of the current context (ShadowRoot or Document)
+      const root = this.getRootNode() as Document | ShadowRoot
+      const activeElement = root.activeElement
       if (
-        !this.inputRef?.contains(document.activeElement) &&
-        (!this.suggestionsRef || !this.suggestionsRef.contains(document.activeElement))
+        !this.inputRef?.contains(activeElement) &&
+        (!this.suggestionsRef || !this.suggestionsRef.contains(activeElement))
       ) {
         this.closeSuggestions()
       }

package/src/elements/data-table/DataTable.styles.ts

@@ -30,8 +30,8 @@ export default css`
     text-align: left;
   }
 
-  th:has(md-focus-ring),
-  td:has(md-focus-ring) {
+  th:has(ui-focus-ring),
+  td:has(ui-focus-ring) {
     position: relative;
     outline: none;
   }
@@ -44,6 +44,11 @@ export default css`
     border-bottom: 1px solid var(--md-sys-color-outline-variant);
   }
 
+  td,
+  th {
+    user-select: none;
+  }
+
   td:not(.no-padding):not(:first-child):not(:last-child),
   th:not(.no-padding):not(:first-child):not(:last-child) {
     padding: 12px;

package/src/elements/data-table/DataTable.ts

@@ -38,6 +38,10 @@ export interface CellRenderOptions {
    * the name for the row, like, a person name or a file name.
    */
   isPrimary?: boolean
+  /**
+   * The part name to use for the cell.
+   */
+  part?: string
 }
 
 /**
@@ -82,6 +86,20 @@ export interface EventCellInfo {
   row: number
 }
 
+/**
+ * Details for the `sort` event dispatched by the DataTable component.
+ */
+export interface DataTableSortEventDetail {
+  /**
+   * The name of the column being sorted.
+   */
+  column: string
+  /**
+   * The sort direction, either "asc" (ascending) or "desc" (descending).
+   */
+  direction: 'asc' | 'desc'
+}
+
 /**
  * A versatile and accessible data table web component.
  *
@@ -405,7 +423,7 @@ export abstract class DataTable<T extends object> extends LitElement {
    */
   protected notifySort(column: string, direction: 'asc' | 'desc'): void {
     this.dispatchEvent(
-      new CustomEvent('sort', {
+      new CustomEvent<DataTableSortEventDetail>('sort', {
         detail: {
           column,
           direction,
@@ -450,6 +468,7 @@ export abstract class DataTable<T extends object> extends LitElement {
         continue
       }
       const isTarget = ['TD', 'TH'].includes(element.nodeName)
+      // @TODO: This creates a focus trap and should be investigated.
       if (!isTarget && element.hasAttribute('tabindex')) {
         // It means that the user focusing on an interactive element
         // within a cell and we should abandon whatever we do right now.
@@ -695,7 +714,7 @@ export abstract class DataTable<T extends object> extends LitElement {
       this.lastSelectedIndex = index
     }
     // This won't cause the focus ring to be rendered because the cell
-    // won't hey the `tabindex=0`, which is OK with pointer device navigation,
+    // won't have the `tabindex=0`, which is OK with pointer device navigation,
     // but it will keep track of the last cell in case the keyboard navigation starts.
     this.position = { row, col }
   }
@@ -944,7 +963,7 @@ export abstract class DataTable<T extends object> extends LitElement {
           data-row="${row}"
           data-col="${col}"
           scope="row"
-          part="cell"
+          part="${opts.part ?? 'cell'}"
         >
           ${ring}
           <div class="cell-content">${content}</div>
@@ -961,7 +980,7 @@ export abstract class DataTable<T extends object> extends LitElement {
         data-delegate="${ifDefined(delegateFocus ? true : undefined)}"
         data-row="${row}"
         data-col="${col}"
-        part="cell"
+        part="${opts.part ?? 'cell'}"
       >
         ${ring}
         <div class="cell-content">${content}</div>
@@ -1018,7 +1037,7 @@ export abstract class DataTable<T extends object> extends LitElement {
       tabindex="${ifDefined(index)}"
       data-delegate="${ifDefined(delegateFocus ? true : undefined)}"
       aria-label="${ifDefined(ariaLabel)}"
-      part="header-cell"
+      part="${opts.part ?? 'header-cell'}"
     >
       <ui-focus-ring .inward="${this.overflow ? true : false}"></ui-focus-ring>
       <div class="cell-content">

package/src/elements/data-table/data-catalog-table.ts

@@ -0,0 +1,22 @@
+import type { CSSResultOrNative } from 'lit'
+import { customElement } from 'lit/decorators.js'
+import Element from './internals/DataCatalogTable.js'
+import tableStyles from './DataTable.styles.js'
+import styles from './internals/DataCatalog.styles.js'
+
+import '../../md/date/ui-date-time.js'
+import '../../md/button/ui-button.js'
+import '../../md/icons/ui-icon.js'
+import '../../md/listbox/ui-listbox.js'
+import '../../md/list/ui-list-item.js'
+
+@customElement('data-catalog-table')
+export class DataCatalogTableElement extends Element {
+  static override styles: CSSResultOrNative[] = [tableStyles, styles]
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'data-catalog-table': DataCatalogTableElement
+  }
+}

package/src/elements/data-table/filesystem-table.ts

@@ -0,0 +1,24 @@
+import type { CSSResultOrNative } from 'lit'
+import { customElement } from 'lit/decorators.js'
+import Element from './internals/FilesystemDataTable.js'
+import tableStyles from './DataTable.styles.js'
+import fsStyles from './internals/Filesystem.styles.js'
+import typography from '../../styles/m3/typography.module.js'
+
+import '../user/ui-user-avatar.js'
+import '../../md/icon-button/ui-icon-button.js'
+import '../../md/icons/ui-icon.js'
+import '../../md/divider/ui-divider.js'
+import '../../md/menu/ui-menu.js'
+import '../../md/menu/ui-menu-item.js'
+
+@customElement('filesystem-table')
+export class FilesystemDataElement extends Element {
+  static override styles: CSSResultOrNative[] = [tableStyles, fsStyles, typography]
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'filesystem-table': FilesystemDataElement
+  }
+}

package/src/elements/data-table/internals/DataCatalog.styles.ts

@@ -0,0 +1,29 @@
+import { css } from 'lit'
+
+export default css`
+  .version-listbox {
+    margin: 0;
+    position-area: bottom;
+    justify-self: anchor-center;
+    transform: scaleY(0);
+    transform-origin: top center;
+    transition: transform 250ms cubic-bezier(0.2, 0, 0, 1) 0s;
+    box-shadow: var(--md-sys-elevation-1);
+    border-radius: var(--md-sys-shape-corner-medium);
+    border: none;
+    /* background-color: var(--md-sys-color-surface-container-high); */
+
+    &:not(:popover-open) {
+      display: none;
+    }
+
+    &:popover-open {
+      display: block;
+      transform: scaleY(1);
+
+      @starting-style {
+        transform: scaleY(0);
+      }
+    }
+  }
+`