@api-client/ui 0.5.58 → 0.6.1

package/src/events/DomainEvents.ts

@@ -0,0 +1,80 @@
+import { EventTypes } from './EventTypes.js'
+import type {
+  DomainBrowseEventDetail,
+  DomainBrowseInit,
+  DomainBrowseRecentItem,
+  DomainBrowseResult,
+  DomainBrowserPickItem,
+  DomainRecentEventDetail,
+  DomainRenameEventDetail,
+} from '../modeling/types.js'
+
+export default {
+  /**
+   * Dispatches a domain rename event. Called when a domain element is renamed.
+   *
+   * @param key The key of the domain element that was renamed.
+   * @param namespace The domain namespace key.
+   * @param kind The domain element kind.
+   * @param name The new name.
+   * @param target Event dispatch target.
+   */
+  rename: (key: string, namespace: string, kind: string, name: string, target = document.body): void => {
+    const detail: DomainRenameEventDetail = {
+      key,
+      label: name,
+      namespace,
+      kind,
+    }
+    const e = new CustomEvent<DomainRenameEventDetail>(EventTypes.Domain.rename, {
+      bubbles: true,
+      composed: true,
+      cancelable: true,
+      detail,
+    })
+    target.dispatchEvent(e)
+  },
+
+  Browse: {
+    /**
+     * Dispatches an event to request recent items from the data domain.
+     * @param domain The key of the data domain to request items for.
+     * @param allowed Optional list of allowed items to filter the results for.
+     * @param target The event target.
+     */
+    recent: async (
+      domain: string,
+      allowed: DomainBrowserPickItem[] | undefined,
+      target = document.body
+    ): Promise<DomainBrowseRecentItem[] | undefined> => {
+      const e = new CustomEvent<DomainRecentEventDetail>(EventTypes.Domain.Browse.recent, {
+        bubbles: true,
+        composed: true,
+        detail: {
+          domain,
+          allowed,
+        },
+      })
+      target.dispatchEvent(e)
+      const result = await e.detail.result
+      return result
+    },
+
+    /**
+     * Dispatches an event to open the domain browser.
+     * @param init The domain browse initialization data.
+     * @param target The event target.
+     * @returns The domain browse result, or undefined if the event was not handled.
+     */
+    browse: async (init: DomainBrowseInit, target = document.body): Promise<DomainBrowseResult | undefined> => {
+      const e = new CustomEvent<DomainBrowseEventDetail>(EventTypes.Domain.Browse.browse, {
+        bubbles: true,
+        composed: true,
+        detail: init,
+      })
+      target.dispatchEvent(e)
+      const result = await e.detail.result
+      return result
+    },
+  },
+}

package/src/events/EventTypes.ts

@@ -172,4 +172,12 @@ export const EventTypes = Object.freeze({
     startActivity: 'startactivity',
     startActivityForResult: 'startactivityforresult',
   }),
+  // Data domain related events.
+  Domain: Object.freeze({
+    rename: 'domainrename',
+    Browse: Object.freeze({
+      recent: 'domainbrowserrecent',
+      browse: 'domainbrowserbrowse',
+    }),
+  }),
 })

package/src/events/Events.ts

@@ -6,6 +6,7 @@ import SchemaDesignEvents from './SchemaDesignEvents.js'
 import HttpClientEvents from './HttpClientEvents.js'
 import HttpEvents from './HttpEvents.js'
 import IntentEvents from './IntentEvents.js'
+import DomainEvents from './DomainEvents.js'
 
 export const Events = Object.freeze({
   Config: ConfigEvents,
@@ -16,4 +17,5 @@ export const Events = Object.freeze({
   SchemaDesign: SchemaDesignEvents,
   Http: HttpEvents,
   Intent: IntentEvents,
+  Domain: DomainEvents,
 })

package/src/exceptions/builder.ts

@@ -0,0 +1,28 @@
+import { Exception } from '@api-client/core/exceptions/exception.js'
+/**
+ * Converts a standard Error object into an Exception instance.
+ * This function extracts relevant properties from the Error object
+ * and sets them on the Exception instance, allowing for a more
+ * consistent error handling experience across the application.
+ * @param error The Error object to convert.
+ * @returns An Exception instance with properties set from the Error object.
+ */
+export function fromError(error: Error): Exception {
+  // The SDK error most likely is an instance of an Exception, so we can process it as one.
+  // If not (some other error), we create a new Exception instance.
+  const e = new Exception(error.message || 'An error occurred')
+  const typed = error as unknown as Record<string, string | number>
+  if (typed.code) {
+    e.code = typed.code as string
+  }
+  if (typed.status) {
+    e.status = Number(typed.status)
+  }
+  if (typed.help) {
+    e.setHelp(typed.help as string)
+  }
+  if (typed.name) {
+    e.name = typed.name as string
+  }
+  return e
+}

package/src/help/README.md

@@ -0,0 +1,99 @@
+# Help System
+
+This directory contains the help system implementation for the Quick API application.
+
+## Overview
+
+The help system provides contextual assistance to users through a panel-based interface. It supports:
+
+- **Categories**: Help topics are organized into categories (general, taxonomy, entity, model, namespace, property, association, function)
+- **Search**: Full-text search across titles, body content, and examples
+- **Examples**: Flexible examples format supporting both legacy string format and new array format with optional titles
+- **Links**: Related links to external resources
+
+## Help Topic Structure
+
+Each help topic follows this structure:
+
+```typescript
+interface HelpTopic {
+  id: string                    // Unique identifier within the category
+  category: string              // Topic category
+  title: string                 // Display title
+  body: string                  // Main content (Markdown format)
+  examples?: string | HelpExample[]  // Optional examples (see below)
+  links?: HelpLink[]            // Optional related links
+}
+```
+
+## Examples Format
+
+The `examples` field supports two formats for backward compatibility and enhanced functionality:
+
+### Legacy String Format (Backward Compatible)
+
+```yaml
+examples: |
+  ```
+  // Simple example in code block
+  const example = "This is a string example"
+  ```
+```
+
+### New Array Format (Enhanced)
+
+```yaml
+examples:
+  - title: "Basic Example"
+    value: |
+      ```
+      // Example with title
+      const basic = "Basic usage"
+      ```
+  - title: "Advanced Example"
+    value: |
+      ```
+      // More complex example
+      const advanced = {
+        feature: "Advanced usage",
+        complexity: "High"
+      }
+      ```
+  - value: |
+      ```
+      // Example without title
+      const simple = "No title needed"
+      ```
+```
+
+### HelpExample Interface
+
+```typescript
+interface HelpExample {
+  title?: string    // Optional title for the example
+  value: string     // The example content (Markdown format)
+}
+```
+
+## Benefits of the New Format
+
+1. **Better Organization**: Examples can be grouped with descriptive titles
+2. **Improved Readability**: Multiple examples can be clearly separated
+3. **Backward Compatibility**: Existing help topics continue to work
+4. **Enhanced Search**: Search functionality works with both example titles and content
+5. **Flexible**: Examples can have titles or not, depending on needs
+
+## Implementation Details
+
+- **Help Panel**: Renders both formats correctly with proper titles
+- **Search Service**: Searches both example titles and content
+- **Type Safety**: Full TypeScript support for both formats
+- **Testing**: Comprehensive tests for both formats
+
+## Best Practices
+
+- Use descriptive titles for examples when they add value
+- Keep examples concise but meaningful
+- Use code blocks for code examples
+- Include practical, real-world examples
+- Consider the user's skill level when writing examples

package/src/help/help_coordinator.ts

@@ -0,0 +1,168 @@
+import { LitElement, html, type TemplateResult } from 'lit'
+import { customElement, property, state } from 'lit/decorators.js'
+import { bound } from '../decorators/bound.js'
+import type { HelpServiceController } from './help_service_controller.js'
+import type { HelpTopic } from './help_topic.js'
+import './help_panel.js'
+
+export interface HelpRequestDetail {
+  /**
+   * The category of the help request, which determines where to look for help content.
+   */
+  category: string
+  /**
+   * The ID of the help request, which identifies the specific help topic.
+   */
+  id: string
+  /**
+   * The target element that triggered the help request.
+   * This can be used to position the help panel relative to the element.
+   */
+  target: HTMLElement
+}
+
+/**
+ * The main coordinator for the help system.
+ * This element should be placed once in your application root and will:
+ * - Listen for help requests from anywhere in the DOM
+ * - Show/hide the help panel
+ * - Coordinate between the help service and UI components
+ *
+ * It relies on the `HelpServiceController` to fetch and manage help topics.
+ * Make sure to configure the `helpService` property with an instance of `HelpServiceController`.
+ *
+ * Usage:
+ * ```ts
+ * const helpServiceInstance = new HelpServiceController({
+ *   categories: {
+ *     property: '/help/property.yaml',
+ *     entity: '/help/entity.yaml',
+ *   },
+ *   version: '1.0.0',
+ * })
+ * ```
+ * ```html
+ * <help-coordinator .helpService="${helpServiceInstance}"></help-coordinator>
+ * ```
+ */
+@customElement('help-coordinator')
+export class HelpCoordinator extends LitElement {
+  /**
+   * The help category of the current help request.
+   * @attribute
+   */
+  @property({ type: String }) accessor category: string | undefined
+  /**
+   * The help ID of the current help request.
+   * @attribute
+   */
+  @property({ type: String }) accessor helpId: string | undefined
+
+  @property({ type: Object }) accessor topic: HelpTopic | undefined
+
+  @state() private accessor opened = false
+  /**
+   * The element that triggered the help request.
+   * This is used to position the help panel relative to the triggering element.
+   * Might not always be set, depending on how the help request is triggered.
+   */
+  @state() private accessor trigger: HTMLElement | undefined
+
+  /**
+   * The help service controller instance.
+   * This should be configured with the appropriate categories and version.
+   */
+  @property({ type: Object }) accessor helpService: HelpServiceController | undefined
+
+  override connectedCallback(): void {
+    super.connectedCallback()
+    // Listen for help requests from anywhere in the application
+    document.addEventListener('request-help', this.handleHelpRequest)
+    // Note: Escape key handling is now automatic with popover API
+  }
+
+  override disconnectedCallback(): void {
+    super.disconnectedCallback()
+    document.removeEventListener('request-help', this.handleHelpRequest)
+  }
+
+  @bound
+  private async handleHelpRequest(event: Event): Promise<void> {
+    if (event.defaultPrevented) {
+      return
+    }
+    const service = this.helpService
+    if (!service) {
+      // eslint-disable-next-line no-console
+      console.warn('Help service not configured')
+      return
+    }
+    const customEvent = event as CustomEvent<HelpRequestDetail>
+    const { category, id, target } = customEvent.detail
+    this.requestTopic(category, id, target)
+    // Prevent further propagation to avoid multiple handlers
+    event.stopPropagation()
+  }
+
+  async requestTopic(category: string, id: string, trigger: HTMLElement): Promise<void> {
+    const service = this.helpService
+    if (!service) {
+      // eslint-disable-next-line no-console
+      console.warn('Help service not configured')
+      return
+    }
+    if (!service.initialized) {
+      await service.untilReady
+    }
+    const topic = await service.getTopic(category, id)
+    if (topic) {
+      this.topic = topic
+      this.opened = true
+      this.trigger = trigger
+    } else {
+      this.showHelpNotAvailable(category, id)
+    }
+    this.trackHelpUsage(category, id)
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  private trackHelpUsage(category: string, id: string): void {
+    // TODO: Implement analytics tracking here
+  }
+
+  private showHelpNotAvailable(category: string, id: string): void {
+    this.topic = {
+      id: 'not-found',
+      category: 'general',
+      title: 'Help Not Available',
+      body: `Sorry, help content for **${category}::${id}** is not available yet.
+
+Please check back later or contact support if you need assistance with this feature.`,
+      links: [
+        { text: 'Contact Support', url: '/support' },
+        { text: 'Documentation', url: '/docs' },
+      ],
+    }
+    this.opened = true
+  }
+
+  protected handleClose(): void {
+    this.opened = false
+  }
+
+  override render(): TemplateResult {
+    return html`<help-panel
+      class="panel"
+      .opened="${this.opened}"
+      .topic="${this.topic}"
+      .trigger="${this.trigger}"
+      @close="${this.handleClose}"
+    ></help-panel>`
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'help-coordinator': HelpCoordinator
+  }
+}

package/src/help/help_panel.styles.ts

@@ -0,0 +1,196 @@
+import { css } from 'lit'
+
+export default css`
+  :host {
+    display: flex;
+    flex-direction: column;
+    width: 380px;
+    max-width: calc(100vw - 40px);
+    max-height: calc(100vh - 40px);
+    background-color: var(--md-sys-color-surface-container-high);
+    color: var(--md-sys-color-on-surface);
+    border-radius: var(--md-sys-shape-corner-extra-large);
+    box-shadow: var(--md-sys-elevation-0);
+    overflow: hidden;
+    border: none;
+    margin: 0;
+    padding: 0;
+
+    position: fixed;
+    top: 20px;
+    right: 20px;
+    left: auto;
+    bottom: auto;
+
+    /* Animation for popover opening/closing */
+    transform: scaleY(0) translateY(-8px);
+    transform-origin: top;
+    opacity: 0;
+    transition:
+      transform 200ms cubic-bezier(0.4, 0, 0.2, 1),
+      box-shadow 200ms cubic-bezier(0.4, 0, 0.2, 1),
+      opacity 200ms cubic-bezier(0.4, 0, 0.2, 1),
+      overlay 200ms allow-discrete,
+      display 200ms allow-discrete;
+
+    font-family: var(--md-sys-typescale-body-medium-font);
+    font-weight: var(--md-sys-typescale-body-medium-weight);
+    font-size: var(--md-sys-typescale-body-medium-size);
+    letter-spacing: var(--md-sys-typescale-body-medium-tracking);
+    line-height: var(--md-sys-typescale-body-medium-height);
+
+    --code-background-color: var(--md-sys-color-surface-container-low);
+    --code-color: var(--md-sys-color-on-surface);
+    --api-font-code-family: 'Roboto Mono, Consolas, Menlo, monospace';
+  }
+
+  /* Popover open state */
+  :host(:popover-open) {
+    display: flex;
+    box-shadow: var(--md-sys-elevation-3);
+    transform: scaleY(1) translateY(0);
+    opacity: 1;
+  }
+
+  .header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    padding: 16px 12px 16px 24px;
+    border-bottom: 1px solid var(--md-sys-color-outline-variant, #cac4d0);
+    flex-shrink: 0;
+    cursor: grab;
+    user-select: none;
+    transition:
+      border-bottom-color 200ms cubic-bezier(0.4, 0, 0.2, 1),
+      box-shadow 200ms cubic-bezier(0.4, 0, 0.2, 1);
+    box-shadow: 0 0 0 0 transparent;
+  }
+
+  /* Add subtle shadow when content is scrolled */
+  :host([data-scrolled]) .header {
+    border-bottom-color: var(--md-sys-color-outline, rgba(0, 0, 0, 0.3));
+    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
+  }
+
+  .header:active {
+    cursor: grabbing;
+  }
+
+  .header:hover {
+    background-color: var(--md-sys-color-surface-container-highest, rgba(0, 0, 0, 0.05));
+  }
+
+  .title {
+    font-family: var(--md-sys-typescale-title-medium-font);
+    font-weight: var(--md-sys-typescale-title-medium-weight);
+    font-size: var(--md-sys-typescale-title-medium-size);
+    letter-spacing: var(--md-sys-typescale-title-medium-tracking);
+    line-height: var(--md-sys-typescale-title-medium-height);
+  }
+
+  .content-wrapper {
+    overflow-y: auto;
+    flex-grow: 1;
+    position: relative;
+    cursor: grab;
+    /* CSS custom properties for scroll state */
+    --scroll-top: 0;
+    --scroll-bottom: 0;
+  }
+
+  /* Scroll shadows - show when content is scrolled */
+  .content-wrapper::before,
+  .content-wrapper::after {
+    content: '';
+    position: sticky;
+    left: 0;
+    right: 0;
+    height: 12px;
+    display: block;
+    pointer-events: none;
+    z-index: 1;
+    transition: opacity 200ms cubic-bezier(0.4, 0, 0.2, 1);
+  }
+
+  /* Top scroll shadow */
+  .content-wrapper::before {
+    top: 0;
+    background: linear-gradient(to bottom, var(--md-sys-color-surface-container-highest) 0%, transparent 100%);
+    opacity: var(--scroll-top, 0);
+  }
+
+  /* Bottom scroll shadow */
+  .content-wrapper::after {
+    bottom: 0;
+    background: linear-gradient(to top, var(--md-sys-color-surface-container-highest) 0%, transparent 100%);
+    opacity: var(--scroll-bottom, 0);
+    margin-top: -12px; /* Overlap with content */
+  }
+
+  .content {
+    padding: 20px;
+    cursor: default;
+    user-select: text;
+  }
+
+  /* Only style our custom section headers (not markdown content) */
+  .content > h3:not([slot='markdown-html'] *) {
+    font-family: var(--md-sys-typescale-headline-small-font);
+    font-weight: var(--md-sys-typescale-headline-small-weight);
+    font-size: var(--md-sys-typescale-headline-small-size);
+    letter-spacing: var(--md-sys-typescale-headline-small-tracking);
+    line-height: var(--md-sys-typescale-headline-small-height);
+    margin-top: 20px;
+    margin-bottom: 8px;
+    color: var(--md-sys-color-on-surface);
+  }
+
+  /* Style the Links section specifically */
+  .links {
+    margin-top: 20px;
+  }
+
+  .links ul {
+    list-style: none;
+    padding: 0;
+    margin: 8px 0 0 0;
+  }
+
+  .links li {
+    margin-bottom: 4px;
+  }
+
+  .links li a {
+    color: var(--md-sys-color-primary);
+    text-decoration: none;
+    display: inline-flex;
+    align-items: center;
+    gap: 4px;
+  }
+
+  .links li a:hover {
+    text-decoration: underline;
+  }
+
+  /* Smooth content animation */
+  .header,
+  .content-wrapper {
+    transition: opacity 100ms cubic-bezier(0.4, 0, 0.2, 1) 50ms;
+  }
+
+  :host(:not([opened])) .header,
+  :host(:not([opened])) .content-wrapper {
+    opacity: 0;
+    transition: opacity 100ms cubic-bezier(0.4, 0, 0.2, 1);
+  }
+
+  [slot='markdown-html'] pre {
+    border-radius: var(--md-sys-shape-corner-medium);
+  }
+
+  .content [slot='markdown-html'] code,
+  .content [slot='markdown-html'] pre {
+    word-break: break-word;
+  }
+`