@api-client/ui 0.5.57 → 0.6.0

package/src/modeling/internals/ApiModelingDescriptionScreen.ts

@@ -0,0 +1,342 @@
+import { html, type TemplateResult, nothing } from 'lit'
+import { ApiModelingScreen } from './ApiModelingScreen.js'
+import { state } from 'lit/decorators.js'
+import { live } from 'lit/directives/live.js'
+import { renderHelp } from '../../help/render.js'
+import type { ApiModel } from '@api-client/core/browser.js'
+import type { UiSelectElement } from '../../md/select/ui-select.js'
+import type { UiSwitchElement } from '../../md/switch/ui-switch.js'
+
+/**
+ * A screen for editing API description information.
+ * Used in API modeling.
+ */
+export default class ApiModelingDescriptionScreen extends ApiModelingScreen {
+  /**
+   * Whether a custom license name is being used.
+   */
+  @state() protected accessor isCustomLicense = false
+
+  /**
+   * Whether contact information is enabled.
+   */
+  @state() protected accessor isContactEnabled = false
+
+  protected handleModelChange(model: ApiModel | undefined): void {
+    this.checkCustomLicense(model)
+    this.checkContactEnabled(model)
+  }
+
+  /**
+   * Checks if the current license is a custom one and updates the state.
+   * @param model The current API model.
+   */
+  checkCustomLicense(model: ApiModel | undefined = this.model): void {
+    if (!model?.license?.name) {
+      this.isCustomLicense = false
+      return
+    }
+    const commonLicenses = ['MIT', 'Apache-2.0', 'GPL-3.0']
+    this.isCustomLicense = !commonLicenses.includes(model.license.name)
+  }
+
+  /**
+   * Checks if contact information is available and updates the state.
+   * @param model The current API model.
+   */
+  checkContactEnabled(model?: ApiModel): void {
+    const currentModel = model || this.model
+    this.isContactEnabled = !!currentModel?.contact
+  }
+
+  protected handleMetaChange(e: Event): void {
+    const model = this.model
+    if (!model) {
+      return
+    }
+    const node = e.target as HTMLInputElement
+    if (node.value && !node.reportValidity()) {
+      return
+    }
+    const { name, value } = node
+
+    switch (name) {
+      case 'name':
+      case 'version':
+      case 'description':
+        if (name === 'name' && !value) {
+          return
+        }
+        model.info[name as 'name' | 'description' | 'version'] = value
+        break
+      case 'termsOfService':
+        model.termsOfService = value || undefined
+        break
+      case 'licenseUrl':
+        if (!model.license) {
+          model.license = { name: '' }
+        }
+        model.license.url = value || undefined
+        break
+      case 'customLicenseName':
+        if (!model.license) {
+          model.license = { name: '' }
+        }
+        model.license.name = value
+        break
+      case 'contactName':
+        if (!model.contact) model.contact = {}
+        model.contact.name = value || undefined
+        break
+      case 'contactEmail':
+        if (!model.contact) model.contact = {}
+        model.contact.email = value || undefined
+        break
+      case 'contactUrl':
+        if (!model.contact) model.contact = {}
+        model.contact.url = value || undefined
+        break
+      default:
+        return
+    }
+    this.model?.notifyChange()
+    this.requestUpdate()
+  }
+
+  protected handleLicenseSelect(e: CustomEvent): void {
+    const model = this.model
+    if (!model) {
+      return
+    }
+    const select = e.target as UiSelectElement
+    const { value } = select
+
+    if (value === 'custom') {
+      this.isCustomLicense = true
+      const isStandard = model.license && ['MIT', 'Apache-2.0', 'GPL-3.0'].includes(model.license.name)
+      if (!model.license || isStandard) {
+        model.license = { name: '' }
+      }
+    } else if (value) {
+      this.isCustomLicense = false
+      model.license = {
+        name: value,
+        url: this.getLicenseUrl(value),
+      }
+    } else {
+      this.isCustomLicense = false
+      model.license = undefined
+    }
+    this.model?.notifyChange()
+    this.requestUpdate()
+  }
+
+  protected handleContactToggle(e: Event): void {
+    const model = this.model
+    if (!model) {
+      return
+    }
+    const toggle = e.target as UiSwitchElement
+    this.isContactEnabled = !!toggle.checked
+    if (this.isContactEnabled) {
+      if (!model.contact) {
+        model.contact = {}
+      }
+    } else {
+      model.contact = undefined
+    }
+    this.model?.notifyChange()
+    this.requestUpdate()
+  }
+
+  getLicenseUrl(name: string): string | undefined {
+    switch (name) {
+      case 'MIT':
+        return 'https://opensource.org/licenses/MIT'
+      case 'Apache-2.0':
+        return 'https://opensource.org/licenses/Apache-2.0'
+      case 'GPL-3.0':
+        return 'https://www.gnu.org/licenses/gpl-3.0'
+      default:
+        return undefined
+    }
+  }
+
+  override render(): TemplateResult | typeof nothing {
+    const model = this.model
+    if (!model) {
+      return nothing
+    }
+    return html`${this.renderMetaFields(model)}<ui-divider type="full"></ui-divider>${this.renderLegalFields(
+        model
+      )}<ui-divider type="full"></ui-divider>${this.renderContactSection(model)}`
+  }
+
+  protected renderMetaFields(model: ApiModel): TemplateResult {
+    return html`
+      <div class="form-section meta-section">
+        <div class="row">
+          <ui-outlined-text-field
+            class="input"
+            name="name"
+            .value="${live(model.info.name || '')}"
+            label="Name"
+            required
+            minLength="2"
+            @change="${this.handleMetaChange}"
+          ></ui-outlined-text-field>
+          ${renderHelp('api', 'description:name-input')}
+        </div>
+        <div class="row">
+          <ui-outlined-text-field
+            class="input"
+            name="description"
+            .value="${live(model.info.description || '')}"
+            label="Description"
+            @change="${this.handleMetaChange}"
+          ></ui-outlined-text-field>
+          ${renderHelp('api', 'description:description-input')}
+        </div>
+        <div class="row">
+          <ui-outlined-text-field
+            class="input"
+            name="version"
+            .value="${live(model.info.version || 'v1')}"
+            label="Version"
+            required
+            @change="${this.handleMetaChange}"
+          ></ui-outlined-text-field>
+          ${renderHelp('api', 'description:version-input')}
+        </div>
+      </div>
+    `
+  }
+
+  protected renderLegalFields(model: ApiModel): TemplateResult {
+    const licenseName = model.license?.name || ''
+    const licenseValue = this.isCustomLicense ? 'custom' : licenseName
+
+    return html`
+      <div class="form-section legal-section">
+        <div class="row">
+          <ui-outlined-text-field
+            class="input"
+            name="termsOfService"
+            .value="${live(model.termsOfService || '')}"
+            label="Terms of Service (URL)"
+            @change="${this.handleMetaChange}"
+            type="url"
+          ></ui-outlined-text-field>
+          ${renderHelp('api', 'description:terms-of-service-input')}
+        </div>
+        <div class="row">
+          <ui-select
+            class="input"
+            label="License"
+            name="license"
+            .value="${licenseValue}"
+            @change="${this.handleLicenseSelect}"
+          >
+            <ui-option value=""><div>None</div></ui-option>
+            <ui-option value="MIT"><div>MIT</div></ui-option>
+            <ui-option value="Apache-2.0"><div>Apache 2.0</div></ui-option>
+            <ui-option value="GPL-3.0"><div>GNU GPLv3</div></ui-option>
+            <ui-option value="custom"><div>Custom</div></ui-option>
+          </ui-select>
+          ${renderHelp('api', 'description:license-input')}
+        </div>
+        ${this.isCustomLicense ? this.renderCustomLicenseName(model) : nothing}
+        ${model.license ? this.renderLicenseUrl(model) : nothing}
+      </div>
+    `
+  }
+
+  protected renderCustomLicenseName(model: ApiModel): TemplateResult {
+    return html`
+      <div class="row">
+        <ui-outlined-text-field
+          class="input"
+          name="customLicenseName"
+          .value="${live(model.license?.name || '')}"
+          label="Custom License Name"
+          @change="${this.handleMetaChange}"
+          required
+        ></ui-outlined-text-field>
+        ${renderHelp('api', 'description:custom-license-name-input')}
+      </div>
+    `
+  }
+
+  protected renderLicenseUrl(model: ApiModel): TemplateResult {
+    return html`
+      <div class="row">
+        <ui-outlined-text-field
+          class="input"
+          name="licenseUrl"
+          .value="${live(model.license?.url || '')}"
+          label="License URL"
+          @change="${this.handleMetaChange}"
+          type="url"
+        ></ui-outlined-text-field>
+        ${renderHelp('api', 'description:license-url-input')}
+      </div>
+    `
+  }
+
+  protected renderContactSection(model: ApiModel): TemplateResult {
+    return html`
+      <div class="form-section contact-section">
+        <div class="row">
+          <div class="input enum">
+            <ui-switch
+              .checked="${this.isContactEnabled}"
+              id="contactEnabled"
+              @change="${this.handleContactToggle}"
+            ></ui-switch>
+            <label for="contactEnabled" class="body-medium">Contact Information</label>
+          </div>
+          ${renderHelp('api', 'description:contact-info-toggle')}
+        </div>
+        ${this.isContactEnabled ? this.renderContactFields(model) : nothing}
+      </div>
+    `
+  }
+
+  protected renderContactFields(model: ApiModel): TemplateResult {
+    const contact = model.contact || {}
+    return html`
+      <div class="row">
+        <ui-outlined-text-field
+          class="input"
+          name="contactName"
+          .value="${live(contact.name || '')}"
+          label="Contact Name"
+          @change="${this.handleMetaChange}"
+        ></ui-outlined-text-field>
+        ${renderHelp('api', 'description:contact-name-input')}
+      </div>
+      <div class="row">
+        <ui-outlined-text-field
+          class="input"
+          name="contactEmail"
+          .value="${live(contact.email || '')}"
+          label="Contact Email"
+          type="email"
+          @change="${this.handleMetaChange}"
+        ></ui-outlined-text-field>
+        ${renderHelp('api', 'description:contact-email-input')}
+      </div>
+      <div class="row">
+        <ui-outlined-text-field
+          class="input"
+          name="contactUrl"
+          .value="${live(contact.url || '')}"
+          label="Contact URL"
+          type="url"
+          @change="${this.handleMetaChange}"
+        ></ui-outlined-text-field>
+        ${renderHelp('api', 'description:contact-url-input')}
+      </div>
+    `
+  }
+}

package/src/modeling/internals/ApiModelingEntityCard.ts

@@ -0,0 +1,210 @@
+import { html, type TemplateResult, nothing } from 'lit'
+import { property, state } from 'lit/decorators.js'
+import { repeat } from 'lit/directives/repeat.js'
+import { ApiEditor } from './ApiEditor.js'
+import type { ApiAction, ApiModel, DomainEntity, ExposedEntity } from '@api-client/core/browser.js'
+import { apiActionKindToIcon, apiActionKindToLabel } from '../lib/ui_mapping.js'
+
+import '../../md/icons/ui-icon.js'
+import '../../md/chip/ui-chip.js'
+import '../../md/divider/ui-divider.js'
+import '../../md/button/ui-button.js'
+import '../../md/icon-button/ui-icon-button.js'
+import '../../md/dropdown-list/ui-dropdown-list.js'
+import '../../md/list/ui-list.js'
+import '../../md/list/ui-list-item.js'
+
+/**
+ * An entity card displaying information about an exposed entity
+ * in the API model, including its domain entity and configured actions.
+ *
+ * @fires remove - Fired when the user requests to remove the exposed entity.
+ * @fires select - Fired when the user clicks on an action chip. The event detail contains the action kind.
+ * @fires edit - Fired when the user clicks the Edit button.
+ */
+export default class ApiModelingEntityCard extends ApiEditor {
+  /**
+   * Computed exposed entity being edited.
+   */
+  @state() accessor exposed: ExposedEntity | undefined
+  /**
+   * Computed domain entity that corresponds to the exposed entity being edited.
+   */
+  @state() accessor entity: DomainEntity | undefined
+
+  /**
+   * Some exposed entities (specifically downstream associated entities) may not have collection actions
+   * (when the association is one-to-one and are not linked).
+   * When this flag is true, the collection actions section is shown.
+   * @attribute
+   */
+  @property({ type: Boolean }) accessor showCollectionActions = false
+
+  protected override setupModel(model?: ApiModel, domainKey?: string): void | Promise<void> {
+    this.exposed = undefined
+    this.entity = undefined
+    if (!model || !domainKey) {
+      return
+    }
+    const exposed = model.exposes.find((exposed) => exposed.key === domainKey)
+    this.exposed = exposed
+    if (!exposed) {
+      return
+    }
+    const domain = model.domain
+    if (!domain) {
+      return
+    }
+    const entity = domain.findEntity(exposed.entity.key, exposed.entity.domain)
+    if (!entity) {
+      return
+    }
+    this.entity = entity
+  }
+
+  protected handleMenuSelect(e: CustomEvent): void {
+    const item = e.detail.item as HTMLElement | undefined
+    if (!item) {
+      return
+    }
+    switch (item.dataset.item) {
+      case 'remove':
+        this.dispatchEvent(new Event('remove'))
+        break
+    }
+  }
+
+  protected handleActionChipClick(e: Event): void {
+    const chip = e.currentTarget as HTMLElement
+    const { kind } = chip.dataset
+    if (!kind) {
+      return
+    }
+    this.dispatchEvent(
+      new CustomEvent('select', {
+        detail: { kind },
+        bubbles: true,
+        composed: true,
+      })
+    )
+  }
+
+  protected handleEditButtonClick(): void {
+    this.dispatchEvent(new Event('edit'))
+  }
+
+  protected override render(): TemplateResult | typeof nothing {
+    const { exposed, entity } = this
+    if (!exposed || !entity) {
+      return nothing
+    }
+    return html`<div class="entity-card">
+      <div class="entity">${this.renderHeader(exposed, entity)} ${this.renderActions(exposed)}</div>
+      <ui-divider type="middle"></ui-divider>
+      <div class="footer">
+        <div class="action-buttons">
+          <ui-button color="text" @click="${this.handleEditButtonClick}">Edit</ui-button>
+        </div>
+        <ui-dropdown-list @select="${this.handleMenuSelect}" closeOnOutsideClick>
+          <ui-icon-button aria-label="More options"><ui-icon icon="moreVert"></ui-icon></ui-icon-button>
+          <ui-list slot="dropdown" role="menu">
+            <ui-list-item role="menuitem" data-item="remove">Remove</ui-list-item>
+          </ui-list>
+        </ui-dropdown-list>
+      </div>
+    </div>`
+  }
+
+  /**
+   * Renders the header section of the entity card.
+   * @param exposed The exposed entity
+   * @param entity The domain entity
+   * @returns The template for the header section
+   */
+  protected renderHeader(exposed: ExposedEntity, entity: DomainEntity): TemplateResult {
+    const path = exposed.hasCollection ? exposed.collectionPath || exposed.resourcePath : exposed.resourcePath
+    return html`
+      <div class="header">
+        <ui-icon class="icon" icon="schemaEntity"></ui-icon>
+        <div class="headline">
+          <div class="title title-medium">${entity.info.getLabel()}</div>
+          <div class="path body-small">${path}</div>
+        </div>
+      </div>
+    `
+  }
+
+  /**
+   * Renders the actions section.
+   * @param exposed The exposed entity
+   * @returns The template for the actions section
+   */
+  protected renderActions(exposed: ExposedEntity): TemplateResult {
+    const content: TemplateResult[] = []
+    if (this.showCollectionActions) {
+      content.push(this.renderCollectionActions(exposed))
+    }
+    content.push(this.renderResourceActions(exposed))
+    return html`<div class="actions-section">
+      <div class="actions-headline title-small">Actions</div>
+      ${content}
+    </div>`
+  }
+
+  /**
+   * Renders the collection actions section.
+   * @param exposed The exposed entity
+   * @returns The template for the collection actions section
+   */
+  protected renderCollectionActions(exposed: ExposedEntity): TemplateResult {
+    const actions = exposed.actions.filter((a) => a.kind === 'list' || a.kind === 'create' || a.kind === 'search')
+    return html`<div class="collection actions">
+      <div class="actions-title label-small">Collection</div>
+      ${this.renderActionsList(actions, 'collection')}
+    </div>`
+  }
+
+  /**
+   * Renders the resource actions section.
+   * @param exposed The exposed entity
+   * @returns The template for the resource actions section
+   */
+  protected renderResourceActions(exposed: ExposedEntity): TemplateResult {
+    const actions = exposed.actions.filter((a) => a.kind === 'read' || a.kind === 'update' || a.kind === 'delete')
+    return html`<div class="resource actions">
+      <div class="actions-title label-small">Resource</div>
+      ${this.renderActionsList(actions, 'resource')}
+    </div>`
+  }
+
+  /**
+   * Renders a list of API actions.
+   * @param actions The list of API actions to render.
+   * @param type The type of actions ('collection' or 'resource').
+   * @returns A TemplateResult containing the rendered actions list.
+   */
+  protected renderActionsList(actions: ApiAction[], type: 'collection' | 'resource'): TemplateResult {
+    let content: TemplateResult
+    if (actions.length === 0) {
+      content = html`<div class="no-actions body-small">This entity has no ${type} actions.</div>`
+    } else {
+      content = html`<div class="chip-list">
+        ${repeat(
+          actions,
+          (action) => action.kind,
+          (action) =>
+            html`<ui-chip
+              class="action-chip"
+              type="assist"
+              data-kind="${action.kind}"
+              @click="${this.handleActionChipClick}"
+            >
+              <ui-icon class="chip-icon" slot="icon">${apiActionKindToIcon(action.kind)}</ui-icon>
+              ${apiActionKindToLabel(action.kind)}
+            </ui-chip>`
+        )}
+      </div>`
+    }
+    return content
+  }
+}