@api-client/ui 0.5.58 → 0.6.0

package/src/modeling/internals/ApiModelingAccessScreen.ts

@@ -0,0 +1,279 @@
+import { html, type TemplateResult, nothing } from 'lit'
+import { DomainEntity, SemanticType, type ApiModel, type DomainProperty } from '@api-client/core/browser.js'
+import { live } from 'lit/directives/live.js'
+import { state } from 'lit/decorators.js'
+import { ApiModelingScreen } from './ApiModelingScreen.js'
+import { renderHelp } from '../../help/render.js'
+import type { UiSelectElement } from '../../md/select/ui-select.js'
+import type {
+  AuthenticationConfiguration,
+  AuthorizationConfiguration,
+  RolesBasedAccessControl,
+  UsernamePasswordConfiguration,
+} from '@api-client/core/modeling/types.js'
+
+/**
+ * A screen for editing API access information.
+ * Used in API modeling.
+ *
+ * Note that unlike configuration components, screens alter the model directly
+ * and notify changes as needed (on the model).
+ */
+export default class ApiModelingAccessScreen extends ApiModelingScreen {
+  /**
+   * A computed property from the data domain model that has the password semantic tag.
+   */
+  @state() protected accessor passwordProperty: DomainProperty | null = null
+  /**
+   * A computed property from the data domain model that has the user role semantic tag.
+   *
+   * TODO:
+   * - We should scan the entire data domain for UserRole semantic as likely there might be more than one.
+   *   We should recommend the one on the `User` entity if multiple found.
+   */
+  @state() protected accessor roleProperty: DomainProperty | null = null
+
+  protected handleModelChange(model: ApiModel | undefined): void {
+    this.passwordProperty = null
+    this.roleProperty = null
+    if (!model) {
+      return
+    }
+    const domain = model.domain
+    if (!domain) {
+      return
+    }
+    // check local entities
+    for (const entity of domain.listEntities()) {
+      if (entity.hasSemantic(SemanticType.User)) {
+        this.analyzeUserEntity(entity)
+        return
+      }
+    }
+    // check foreign entities
+    for (const entity of domain.listAllForeignEntities()) {
+      if (entity.hasSemantic(SemanticType.User)) {
+        this.analyzeUserEntity(entity)
+        return
+      }
+    }
+  }
+
+  protected analyzeUserEntity(entity: DomainEntity): void {
+    let passwordProp: DomainProperty | null = null
+    let roleProp: DomainProperty | null = null
+    for (const property of entity.listProperties()) {
+      if (property.hasSemantic(SemanticType.Password)) {
+        passwordProp = property
+      }
+      if (property.hasSemantic(SemanticType.UserRole)) {
+        roleProp = property
+      }
+      if (passwordProp && roleProp) {
+        break
+      }
+    }
+    this.passwordProperty = passwordProp
+    this.roleProperty = roleProp
+  }
+
+  protected handleAuthStrategyChange(e: CustomEvent): void {
+    const model = this.model
+    if (!model) {
+      return
+    }
+    const select = e.target as UiSelectElement
+    const { value } = select
+
+    if (model.authentication?.strategy === value) {
+      // Ignore resetting the same value.
+      return
+    }
+
+    if (value === 'UsernamePassword') {
+      if (!model.authentication || model.authentication.strategy !== 'UsernamePassword') {
+        model.authentication = {
+          strategy: 'UsernamePassword',
+        } as UsernamePasswordConfiguration
+      }
+    } else {
+      // For now, only UsernamePassword is a valid, non-disabled option.
+      // If other options are added, this logic will need to be expanded.
+      if (!model.authentication) {
+        model.authentication = { strategy: value } as AuthenticationConfiguration
+      } else {
+        model.authentication.strategy = value as string
+      }
+    }
+    this.model?.notifyChange()
+    this.requestUpdate()
+  }
+
+  protected handleAuthzStrategyChange(e: CustomEvent): void {
+    const model = this.model
+    if (!model) {
+      return
+    }
+    const select = e.target as UiSelectElement
+    const { value } = select
+
+    if (model.authorization?.strategy === value) {
+      // Ignore resetting the same value.
+      return
+    }
+
+    if (value === 'RBAC') {
+      if (!model.authorization || model.authorization.strategy !== 'RBAC') {
+        model.authorization = {
+          strategy: 'RBAC',
+          roleKey: this.roleProperty?.key || '', // default value
+        } as RolesBasedAccessControl
+      }
+    } else {
+      // For now, only RBAC is a valid, non-disabled option.
+      if (!model.authorization) {
+        model.authorization = { strategy: value } as AuthorizationConfiguration
+      } else {
+        model.authorization.strategy = value as string
+      }
+    }
+    this.model?.notifyChange()
+    this.requestUpdate()
+  }
+
+  protected handleAccessConfigChange(): void {
+    this.model?.notifyChange()
+  }
+
+  override render(): TemplateResult | typeof nothing {
+    const model = this.model
+    if (!model) {
+      return nothing
+    }
+    return html`
+      <div class="screen-container">
+        <div class="screen-header">
+          <h2 class="headline-medium">API Access</h2>
+          <span class="body-medium description">
+            API access allows you to control how your API customers access the API. Here, you can configure the
+            authentication strategy and global access rules. You can update these settings for each behaviors
+            separately.
+          </span>
+        </div>
+        ${this.renderAuthentication(model)} ${this.renderAuthorization(model)} ${this.renderApiAccessConfiguration()}
+      </div>
+    `
+  }
+
+  protected renderAuthentication(model: ApiModel): TemplateResult {
+    const authStrategy = model.authentication?.strategy
+    return html`
+      <div class="config-section authentication">
+        <div class="section-header">
+          <h3 class="title-large">Authentication strategy</h3>
+          <span class="body-small description">
+            Choose how your API will verify the identity of its users. You can change these settings until you first
+            deploy your API. After that the change won't be possible.
+          </span>
+        </div>
+        <div class="row">
+          <ui-select
+            label="Strategy"
+            name="authenticationStrategy"
+            .value="${live(authStrategy)}"
+            @change="${this.handleAuthStrategyChange}"
+          >
+            <ui-option value="UsernamePassword">
+              <div>Username and Password</div>
+              <div slot="supporting-text">Authenticate with a username and password.</div>
+            </ui-option>
+            <ui-option value="SSO" disabled>
+              <div>Single Sign-On</div>
+              <div slot="supporting-text">Coming soon</div>
+            </ui-option>
+          </ui-select>
+          ${renderHelp('api', 'auth-strategy-select')}
+        </div>
+
+        ${this.renderPasswordConfirmation(model)}
+      </div>
+    `
+  }
+
+  protected renderPasswordConfirmation(model: ApiModel): TemplateResult | typeof nothing {
+    const strategy = model.authentication?.strategy
+    if (strategy !== 'UsernamePassword') {
+      return nothing
+    }
+    const prop = this.passwordProperty
+    if (!prop) {
+      return html`<span class="body-small no-property-warning">
+        <ui-icon>warning_amber</ui-icon>
+        No password property found on the user entity. Please define one on the data domain's User entity to ensure
+        secure authentication.
+      </span>`
+    }
+    return html`<span class="body-small property-info"
+      >Password property: <strong>${prop.info.getLabel()}</strong></span
+    >`
+  }
+
+  protected renderAuthorization(model: ApiModel): TemplateResult {
+    const authzStrategy = model.authorization?.strategy || ''
+    return html`
+      <div class="config-section authorization">
+        <div class="section-header">
+          <h2 class="title-large">Authorization strategy</h2>
+          <span class="body-medium description">
+            It allows you to configure how users access data in your API. After the authorization strategy is set it
+            cannot be changed.
+          </span>
+        </div>
+        <div class="row">
+          <ui-select
+            label="Strategy"
+            name="authorizationStrategy"
+            .value="${live(authzStrategy)}"
+            @change="${this.handleAuthzStrategyChange}"
+          >
+            <ui-option value="RBAC">
+              <div>Role-based authentication</div>
+              <div slot="supporting-text">Access is granted based on user roles.</div>
+            </ui-option>
+            <ui-option value="PBAC" disabled>
+              <div>Permission-based authentication</div>
+              <div slot="supporting-text">Coming soon</div>
+            </ui-option>
+          </ui-select>
+          ${renderHelp('api', 'authz-strategy-select')}
+        </div>
+        ${this.renderRoleConfirmation(model)}
+      </div>
+    `
+  }
+
+  protected renderRoleConfirmation(model: ApiModel): TemplateResult | typeof nothing {
+    const strategy = model.authorization?.strategy || ''
+    if (strategy !== 'RBAC') {
+      return nothing
+    }
+    const prop = this.roleProperty
+    if (!prop) {
+      return html`<span class="body-small no-property-warning">
+        <ui-icon>warning_amber</ui-icon>
+        No role property found on the user entity. Please define one on the data domain's User entity to ensure proper
+        authorization.
+      </span>`
+    }
+    return html`<span class="body-small property-info">Role property: <strong>${prop.info.getLabel()}</strong></span>`
+  }
+
+  protected renderApiAccessConfiguration(): TemplateResult {
+    return html`<api-modeling-access-configuration
+      .model=${this.model}
+      target="api"
+      @change=${this.handleAccessConfigChange}
+      class="api-access-configuration"
+    ></api-modeling-access-configuration>`
+  }
+}

package/src/modeling/internals/ApiModelingActionsScreen.ts

@@ -0,0 +1,333 @@
+import { html, type TemplateResult, nothing } from 'lit'
+import { ExposedEntity, type ApiModel } from '@api-client/core/browser.js'
+import type { ApiAction } from '@api-client/core/modeling/types.js'
+import { state } from 'lit/decorators.js'
+import { ApiModelingScreen } from './ApiModelingScreen.js'
+import type ApiModelingEntityCardElement from './ApiModelingEntityCard.js'
+
+export interface EditActionEventDetail {
+  /**
+   * The id of the exposed entity.
+   */
+  exposedId: string
+  /**
+   * The kind of operation to edit (list, read, delete, etc)
+   */
+  kind: string
+}
+
+export interface EditExposedEntityEventDetail {
+  /**
+   * The id of the exposed entity.
+   */
+  exposedId: string
+}
+
+/**
+ * A screen that allows the user to expose data entities as a root level actions
+ * and configure their properties:
+ * - Collection actions (create, list, search)
+ * - Resource actions (read, update, delete)
+ *
+ * @fires exposed-new - When the user wants to expose an entity.
+ * @fires action-edit - When the user wants to edit an action.
+ * @fires exposed-edit - When the user wants to edit an exposed entity.
+ * @fires exposed-remove - When the user wants to remove an exposed entity.
+ */
+export default class ApiModelingActionsScreen extends ApiModelingScreen {
+  /**
+   * A flag that determines whether the API has added a data domain.
+   */
+  @state() accessor hasDomain = false
+
+  /**
+   * The list of exposed entities **on the root level**.
+   */
+  @state() accessor exposed: ExposedEntity[] = []
+
+  protected handleModelChange(model: ApiModel | undefined): void {
+    this.hasDomain = false
+    this.exposed = []
+    if (!model) {
+      return
+    }
+
+    if (!model.domain) {
+      return
+    }
+    this.hasDomain = true
+    this.exposed = model.exposes.filter((expose) => expose.isRoot)
+  }
+
+  protected override handleDomainChange(): void {
+    // TODO: this is too much for a model change, but temporary we will re-render the screen on any model change
+    // until we figure out how to expose a new entity to the API and capture only that change.
+    this.handleModelChange(this.model)
+    this.requestUpdate()
+  }
+
+  /**
+   * A handler for the "Add data" button click.
+   * It dispatches the `exposeentity` event to notify the parent component that the user wants to expose an entity.
+   */
+  protected handleAddDataClick(): void {
+    this.dispatchEvent(
+      new Event('exposed-new', {
+        bubbles: true,
+        cancelable: true,
+        composed: true,
+      })
+    )
+  }
+
+  /**
+   * A handler for the "Remove action" button click.
+   * It removes the action from the model and updates the exposed list.
+   * @param event The event object.
+   */
+  protected handleRemoveAction(e: Event): void {
+    const card = e.currentTarget as ApiModelingEntityCardElement
+    const id = card.domainKey
+    if (!id) {
+      return
+    }
+    this.dispatchEvent(
+      new CustomEvent<EditExposedEntityEventDetail>('exposed-remove', {
+        bubbles: true,
+        cancelable: true,
+        composed: true,
+        detail: {
+          exposedId: id,
+        },
+      })
+    )
+  }
+
+  /**
+   * Handles the action selection event.
+   * It dispatches the `editaction` event to notify the parent component that the user wants to edit an action.
+   * @param e The event object.
+   */
+  protected handleActionSelect(e: CustomEvent<{ kind: string }>): void {
+    const card = e.currentTarget as ApiModelingEntityCardElement
+    const id = card.domainKey
+    if (!id) {
+      return
+    }
+    this.dispatchEvent(
+      new CustomEvent<EditActionEventDetail>('action-edit', {
+        bubbles: true,
+        cancelable: true,
+        composed: true,
+        detail: {
+          exposedId: id,
+          kind: e.detail.kind,
+        },
+      })
+    )
+  }
+
+  protected handleEditAction(e: Event): void {
+    const card = e.currentTarget as ApiModelingEntityCardElement
+    const id = card.domainKey
+    if (!id) {
+      return
+    }
+    this.dispatchEvent(
+      new CustomEvent<EditExposedEntityEventDetail>('exposed-edit', {
+        bubbles: true,
+        cancelable: true,
+        composed: true,
+        detail: {
+          exposedId: id,
+        },
+      })
+    )
+  }
+
+  override render(): TemplateResult | typeof nothing {
+    const model = this.model
+    if (!model) {
+      return nothing
+    }
+    return html`
+      <div class="config-section horizontal center">
+        <div class="section-header">
+          <h2 class="headline-medium">API Actions</h2>
+          <p class="body-medium">
+            You define your API logic by selecting data objects you want to use in your API and adding predefined
+            actions to these data.
+          </p>
+        </div>
+        <ui-button @click="${this.handleAddDataClick}">Add data</ui-button>
+      </div>
+      ${this.hasDomain ? this.renderContent(model) : html`<p>No data domain selected.</p>`}
+    `
+  }
+
+  private renderContent(model: ApiModel): TemplateResult | typeof nothing {
+    if (!this.exposed.length) {
+      return this.renderEmptyView()
+    }
+    return html`<div class="exposed-canvas">
+      ${this.exposed.map((expose) => this.renderExposedPath(model, expose))}
+    </div>`
+  }
+
+  private renderEmptyView(): TemplateResult | typeof nothing {
+    return html`
+      <section class="empty-screen">
+        <div class="icon-wrapper">
+          <ui-icon class="icon" icon="api"></ui-icon>
+        </div>
+        <p class="empty-message body-large">Find your API logic here</p>
+        <p class="empty-message body-medium">Add a data entity to define your API behavior.</p>
+      </section>
+    `
+  }
+
+  private renderExposedPath(model: ApiModel, rootExpose: ExposedEntity): TemplateResult | typeof nothing {
+    // Render the root expose and all its nested children (by parent key) in a single row.
+    // Use the model.exposes list as the source of truth for child relationships.
+    const allExposes = model.exposes ?? []
+    const row = this.renderExposeTree(model, rootExpose, allExposes)
+    return html`<div class="exposure-row">${row}</div>`
+  }
+
+  /**
+   * Recursively render an expose and its children. Shows entity name only.
+   * The model guarantees no infinite cycles, so the UI does not need to track visited nodes.
+   */
+  private renderExposeTree(
+    model: ApiModel,
+    rootExpose: ExposedEntity,
+    allExposes: ExposedEntity[]
+  ): TemplateResult | typeof nothing {
+    if (!rootExpose || !rootExpose.key) {
+      return nothing
+    }
+
+    // Render current entity
+    const current = this.renderEntity(model, rootExpose)
+
+    // Find children that reference this expose as parent.
+    const children = allExposes.filter((e) => e.parent?.key === rootExpose.key)
+
+    // If no children, render just the entity
+    if (!children.length) {
+      return html`<div class="expose-node inline">${current}</div>`
+    }
+
+    // Render current entity and stack children vertically. Each child row shows
+    // the child and its inline descendants (classic tree view).
+    return html`${current}
+      <div class="children-list">
+        ${children.map(
+          (child) => html`
+            <div class="child-row">
+              <span class="expose-sep">→</span>
+              ${this.renderExposeTree(model, child, allExposes)}
+            </div>
+          `
+        )}
+      </div>`
+    // <!-- ${this.renderExposeInline(model, child, allExposes)} -->
+  }
+
+  /**
+   * Render a node and all its descendants inline (used for child rows).
+   */
+  private renderExposeInline(
+    model: ApiModel,
+    expose: ExposedEntity,
+    allExposes: ExposedEntity[]
+  ): TemplateResult | typeof nothing {
+    if (!expose || !expose.key) {
+      return nothing
+    }
+    const current = this.renderEntity(model, expose)
+
+    const children = allExposes.filter((e) => {
+      const parentRef = (e as unknown as { parent?: { key?: string } }).parent
+      const parentKey = parentRef?.key
+      return parentKey === expose.key
+    })
+
+    if (!children.length) {
+      return html`${current}`
+    }
+
+    return html`${current}${children.map(
+      (child) => html`
+        <span class="expose-sep">→</span>
+        ${this.renderExposeInline(model, child, allExposes)}
+      `
+    )}`
+  }
+
+  private renderEntity(model: ApiModel, expose: ExposedEntity): TemplateResult {
+    const entity = model.domain?.findEntity(expose.entity.key, expose.entity.domain)
+    if (!entity) {
+      return this.renderMissingEntity(expose)
+    }
+    return html`<api-modeling-entity-card
+      .model=${model}
+      .domainKey=${expose.key}
+      ?showCollectionActions="${expose.hasCollection}"
+      @select="${this.handleActionSelect}"
+      @edit="${this.handleEditAction}"
+      @remove="${this.handleRemoveAction}"
+    ></api-modeling-entity-card>`
+  }
+
+  private renderMissingEntity(expose: ExposedEntity): TemplateResult {
+    return html`<div class="entity missing-entity">
+      <span class="entity-missing-label">Missing entity:</span>
+      <span class="api-action-entity">${expose.key}</span>
+    </div>`
+  }
+
+  private renderEntityActions(expose: ExposedEntity): TemplateResult {
+    const hasActions = !!expose.actions.length
+    if (!hasActions) {
+      return html`<div class="no-actions">
+        <p class="body-medium">No API actions are defined for this object.</p>
+      </div>`
+    }
+    return html`${this.renderCollectionActions(expose)}${this.renderResourceActions(expose)}`
+  }
+
+  private renderCollectionActions(expose: ExposedEntity): TemplateResult {
+    const actions = expose.actions.filter((action) => ['create', 'list', 'search'].includes(action.kind))
+    const hasActions = !!actions.length
+    const templates: TemplateResult[] = []
+    if (!hasActions) {
+      templates.push(html`<p class="body-medium">No API actions are defined for this collection.</p>`)
+    } else {
+      templates.push(...actions.map((action) => this.renderEntityAction(action)))
+    }
+    return html`<div class="actions-group">
+      <div class="label-small">Collection</div>
+      ${templates}
+    </div>`
+  }
+
+  private renderResourceActions(expose: ExposedEntity): TemplateResult {
+    const actions = expose.actions.filter((action) => ['read', 'update', 'delete'].includes(action.kind))
+    const hasActions = !!actions.length
+    const templates: TemplateResult[] = []
+    if (!hasActions) {
+      templates.push(html`<p class="body-medium">No API actions are defined for this resource.</p>`)
+    } else {
+      templates.push(...actions.map((action) => this.renderEntityAction(action)))
+    }
+    return html`<div class="actions-group">
+      <div class="label-small">Resource</div>
+      ${templates}
+    </div>`
+  }
+
+  private renderEntityAction(action: ApiAction): TemplateResult {
+    return html`<ui-chip type="assist">${action.kind}</ui-chip>`
+  }
+}