@api-client/ui 0.5.34 → 0.5.35

package/build/src/core/Fragment.d.ts

@@ -5,6 +5,7 @@ import type { Application, UpdateRequest } from './Application.js';
 import { FragmentRenderer } from './renderer/FragmentRenderer.js';
 import { Intent, IntentResult } from './ActivityManager.js';
 import type { ActivityDetail, ActivityWithResultDetail } from '../events/IntentEvents.js';
+import { type RefOrCallback } from 'lit/directives/ref.js';
 export interface PendingActivityResult {
     onResult(result: IntentResult, intent: Intent): void;
 }
@@ -124,6 +125,19 @@ export declare class Fragment extends EventTarget {
      * @param key The name of the fragment to remove.
      */
     removeChild(key: string): Promise<void>;
+    /**
+     * Creates a RefCallback that can be used with lit's `ref()` directive
+     * to automatically show/hide a child fragment when its container element
+     * is added or removed from the DOM.
+     *
+     * @param key The key of the child fragment to manage.
+     * @returns A RefCallback to be used with the `ref()` directive.
+     *
+     * @example
+     * // In your parent fragment's render method:
+     * html`<div ${ref(this.createFragmentRef('my-child-fragment'))}></div>`
+     */
+    createFragmentRef(key: string): RefOrCallback<Element>;
     /**
      * A helper to request an update.
      * Application or parent Fragment will handle rendering.

package/build/src/core/Fragment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Fragment.d.ts","sourceRoot":"","sources":["../../../src/core/Fragment.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Fragment.d.ts","sourceRoot":"","sources":["../../../src/core/Fragment.ts"],"names":[],"mappings":"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"}

package/build/src/core/Fragment.js

@@ -187,6 +187,31 @@ let Fragment = (() => {
                 this.children.delete(key);
             }
         }
+        /**
+         * Creates a RefCallback that can be used with lit's `ref()` directive
+         * to automatically show/hide a child fragment when its container element
+         * is added or removed from the DOM.
+         *
+         * @param key The key of the child fragment to manage.
+         * @returns A RefCallback to be used with the `ref()` directive.
+         *
+         * @example
+         * // In your parent fragment's render method:
+         * html`<div ${ref(this.createFragmentRef('my-child-fragment'))}></div>`
+         */
+        createFragmentRef(key) {
+            return (element) => {
+                if (element) {
+                    this.fragmentManager.showFragment(key, element);
+                }
+                else {
+                    const fragment = this.fragmentManager.findFragment(key);
+                    if (fragment) {
+                        this.fragmentManager.hideFragment(fragment);
+                    }
+                }
+            };
+        }
         /**
          * A helper to request an update.
          * Application or parent Fragment will handle rendering.

package/build/src/core/Fragment.js.map

@@ -1 +1 @@
-{"version":3,"file":"Fragment.js","sourceRoot":"","sources":["../../../src/core/Fragment.ts"],"names":[],"mappings":"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","sourcesContent":["import { nothing, TemplateResult } from 'lit'\nimport { Activity } from './Activity.js'\nimport { FragmentState, type FragmentOptions, FragmentManager } from './FragmentManager.js'\nimport type { Application, UpdateRequest } from './Application.js'\nimport { FragmentRenderer } from './renderer/FragmentRenderer.js'\nimport { Intent, IntentResult } from './ActivityManager.js'\nimport { bound } from '../decorators/bound.js'\nimport type { ActivityDetail, ActivityWithResultDetail } from '../events/IntentEvents.js'\nimport { EventTypes } from '../events/EventTypes.js'\n\nexport interface PendingActivityResult {\n  onResult(result: IntentResult, intent: Intent): void\n}\n\n/**\n * Similar to Activity, with lifecycle methods (onCreate, onAttach, onDetach, etc.).\n * The crucial difference is that a Fragment is always hosted by an `Activity` or\n * another `Fragment`.\n *\n * A `Fragment` represents a reusable portion of the app's UI.\n * A fragment defines and manages its own layout, has its own lifecycle,\n * and can handle its own input events.\n * Fragments can't live on their own. They must be hosted by an activity or another\n * fragment. The fragment’s view hierarchy becomes part of, or attaches to,\n * the host’s view hierarchy.\n */\nexport class Fragment extends EventTarget {\n  public state: FragmentState = FragmentState.Initialized\n  public parent?: Activity | Fragment\n  protected children = new Map<string, Fragment>()\n  protected fragmentManager: FragmentManager\n\n  /**\n   * The request code used to start an activity for a result.\n   */\n  requestCode = -1\n\n  /**\n   * A list of pending activity results that were requested by the components\n   * hosted in this fragment.\n   * The key is the request code and the value contains the callback\n   * that will be called when the activity result is received.\n   * The callback is called with the result code and the resulting intent.\n   */\n  pendingActivityResult: Map<number, PendingActivityResult> = new Map<number, PendingActivityResult>()\n\n  #renderer: FragmentRenderer\n\n  get renderer(): FragmentRenderer {\n    return this.#renderer\n  }\n\n  constructor(options?: FragmentOptions) {\n    super()\n    this.parent = options?.parent\n    this.fragmentManager = new FragmentManager(this)\n    this.#renderer = new FragmentRenderer(this)\n  }\n\n  /**\n   * When implemented, this method returns the class name to be used as a root class for the fragment.\n   * This class name can be used to apply styles or identify the fragment in the DOM.\n   * @returns The class name to be used as a root class for the fragment.\n   */\n  public rootClass(): string | undefined {\n    return undefined\n  }\n\n  /**\n   * @see {@link ./Renderer.js}\n   */\n  public setRenderRoot(renderRoot: HTMLElement | string): void {\n    this.#renderer.setRenderRoot(renderRoot)\n  }\n\n  onData(data: unknown): void | Promise<void> {\n    this.dispatchEvent(new CustomEvent('fragment:data', { detail: data }))\n  }\n\n  /**\n   * Called once when the fragment is created.\n   *\n   * In the `onCreate()` method, perform basic fragment startup logic that happens only once\n   * for the entire life of the fragment.\n   * @param data Optional init data.\n   */\n  onCreate(data?: unknown): void | Promise<void> {\n    this.dispatchEvent(new CustomEvent('fragment:create', { detail: data }))\n  }\n\n  /**\n   * Called when the fragment is attached to a parent\n   */\n  onAttach(data?: unknown): void | Promise<void> {\n    this.dispatchEvent(new CustomEvent('fragment:attach', { detail: data }))\n  }\n\n  /**\n   * Called when the fragment becomes visible.\n   */\n  onStart(): void | Promise<void> {\n    this.dispatchEvent(new CustomEvent('fragment:start', { detail: null }))\n  }\n\n  /**\n   * Called when the fragment gains focus.\n   */\n  onResume(): void | Promise<void> {\n    this.dispatchEvent(new CustomEvent('fragment:resume', { detail: null }))\n  }\n\n  /**\n   * Called when the fragment loses focus.\n   */\n  onPause(): void | Promise<void> {\n    this.dispatchEvent(new CustomEvent('fragment:pause', { detail: null }))\n  }\n\n  /**\n   * Called when the fragment is no longer visible.\n   */\n  onStop(): void | Promise<void> {\n    this.dispatchEvent(new CustomEvent('fragment:stop', { detail: null }))\n  }\n\n  /**\n   * Called when the fragment is detached from a parent\n   */\n  onDetach(): void | Promise<void> {\n    this.dispatchEvent(new CustomEvent('fragment:detach', { detail: null }))\n  }\n\n  /**\n   * Called before the fragment is destroyed.\n   */\n  onDestroy(): void | Promise<void> {\n    this.dispatchEvent(new CustomEvent('fragment:destroy', { detail: null }))\n    this.fragmentManager.onDestroy()\n  }\n\n  /**\n   * Called by the renderer when the fragment is rendered for the first time.\n   */\n  onFirstRender(): void {\n    //\n  }\n\n  /**\n   * A function called when it should render the view.\n   * By default it renders a fragment view if the fragment hosts other fragments and only one is visible.\n   */\n  render(): TemplateResult | typeof nothing {\n    const fragment = this.getSingleVisibleFragment()\n    if (fragment) {\n      // we can manage the default rendering.\n      // we make an assumption that by default only one fragment is rendered,\n      // otherwise the parent activity or fragment would have to setup render roots.\n      return fragment.render()\n    }\n    return nothing\n  }\n\n  /**\n   * Checks whether there's only one `Fragment` that is in the `Resumed` state\n   * and returns it. It returns `null` if there is no `Fragment`s or more than a single\n   * visible `Fragment`.\n   * @returns A Fragment that is the only fragment that should be visible.\n   */\n  getSingleVisibleFragment(): Fragment | null {\n    const fragments = this.getVisibleFragments()\n    return fragments.length === 1 ? fragments[0] : null\n  }\n\n  /**\n   * Checks whether this fragment is a host for other fragments.\n   * @returns `true` when this fragment hosts other fragments.\n   */\n  isRenderingFragments(): boolean {\n    return this.children.size > 0\n  }\n\n  /**\n   * @returns The list of all fragments that are in the Resumed state.\n   */\n  getVisibleFragments(): Fragment[] {\n    return this.fragmentManager.getVisible()\n  }\n\n  /**\n   * Adds a child fragment to this fragment.\n   * The FragmentManager will handle lifecycle.\n   * @param key The name of the fragment.\n   * @param fragment The fragment to add.\n   */\n  async addChild(key: string, fragment: Fragment, data?: unknown): Promise<void> {\n    this.children.set(key, fragment)\n    await this.fragmentManager.attachFragment(key, fragment, this, data)\n  }\n\n  /**\n   * Removes a fragment from this fragment.\n   * @param key The name of the fragment to remove.\n   */\n  async removeChild(key: string): Promise<void> {\n    const child = this.children.get(key)\n    if (child) {\n      await this.fragmentManager.detachFragment(key)\n      this.children.delete(key)\n    }\n  }\n\n  /**\n   * A helper to request an update.\n   * Application or parent Fragment will handle rendering.\n   */\n  requestUpdate(opts: UpdateRequest = {}): void {\n    const { fragment = true } = opts\n    if (fragment) {\n      this.#renderer.requestUpdate()\n    }\n    this.parent?.requestUpdate(opts)\n    // If no parent, do nothing (or maybe throw an error?)\n  }\n\n  getApplication(): Application | undefined {\n    return this.parent?.getApplication()\n  }\n\n  getActivity(): Activity | undefined {\n    return this.parent?.getActivity()\n  }\n\n  /**\n   * Starts an activity for result.\n   * @param intent The intent to start.\n   */\n  async startActivityForResult(intent: Intent): Promise<void> {\n    const activity = this.getActivity()\n    if (!activity) {\n      throw new Error(`The fragment has no activity. Unable to start an intent.`)\n    }\n    this.requestCode = await activity.startActivityForResult(intent)\n  }\n\n  /**\n   * Starts another activity.\n   * @param intent The intent to start.\n   */\n  async startActivity(intent: Intent): Promise<void> {\n    const activity = this.getActivity()\n    if (!activity) {\n      throw new Error(`The fragment has no activity. Unable to start an intent.`)\n    }\n    await activity.startActivity(intent)\n  }\n\n  /**\n   * The callback method that is triggered when another activity that was\n   * started for result finishes.\n   *\n   * @param requestCode The request code that was used to start the activity.\n   * @param data The data that was passed back.\n   * @param intent The intent that was used to start the activity.\n   */\n  async onActivityResult(requestCode: number, resultCode: IntentResult, intent: Intent): Promise<void> {\n    const { pendingActivityResult, children } = this\n    if (pendingActivityResult.has(requestCode)) {\n      const { onResult } = pendingActivityResult.get(requestCode) as PendingActivityResult\n      pendingActivityResult.delete(requestCode)\n      onResult(resultCode, intent)\n      return\n    }\n    for (const fragment of children.values()) {\n      if (fragment.hasRequestCode(requestCode)) {\n        fragment.onActivityResult(requestCode, resultCode, intent)\n        return\n      }\n    }\n    this.requestCode = -1\n    if (this.constructor === Fragment) {\n      // eslint-disable-next-line no-console\n      console.info('Fragment#onActivityResult() not implemented', requestCode, resultCode, intent)\n    }\n  }\n\n  hasRequestCode(requestCode: number): boolean {\n    for (const fragment of this.children.values()) {\n      if (fragment.hasRequestCode(requestCode)) {\n        return true\n      }\n    }\n    return this.requestCode === requestCode\n  }\n\n  /**\n   * A handler for the intent event dispatched by web components hosted by this fragment.\n   *\n   * **Usage example:**\n   *\n   * ```ts\n   * <custom-element @startactivity=\"${this.handleIntentEvent}\"></custom-element>\n   * <custom-element @startactivityforresult=\"${this.handleIntentEvent}\"></custom-element>\n   * ```\n   *\n   * @param event The event that was dispatched.\n   * @returns A promise that resolves when the intent is handled.\n   * @throws An error if the fragment has no activity.\n   * @throws An error if the event type is not recognized.\n   */\n  @bound\n  async handleIntentEvent(event: CustomEvent<ActivityDetail | ActivityWithResultDetail>): Promise<void> {\n    const activity = this.getActivity()\n    if (!activity) {\n      throw new Error(`The fragment has no activity. Unable to start an intent.`)\n    }\n    if (event.type === EventTypes.Intent.startActivityForResult) {\n      const info = event.detail as ActivityWithResultDetail\n      const code = await activity.startActivityForResult(info.intent)\n      this.requestCode = code\n      this.pendingActivityResult.set(code, {\n        onResult: info.onResult,\n      })\n    } else if (event.type === EventTypes.Intent.startActivity) {\n      await activity.startActivity(event.detail.intent)\n    } else {\n      throw new Error(`Unrecognized intent event: ${event.type}`)\n    }\n  }\n}\n"]}
+{"version":3,"file":"Fragment.js","sourceRoot":"","sources":["../../../src/core/Fragment.ts"],"names":[],"mappings":";AAAA,OAAO,EAAE,OAAO,EAAkB,MAAM,KAAK,CAAA;AAE7C,OAAO,EAAE,aAAa,EAAwB,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAE3F,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAA;AAEjE,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAA;AAE9C,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AAOpD;;;;;;;;;;;GAWG;IACU,QAAQ;sBAAS,WAAW;;;iBAA5B,QAAS,SAAQ,WAAW;;;6CAoTtC,KAAK;YACN,sMAAM,iBAAiB,6DAiBtB;;;QArUM,KAAK,IADD,mDAAQ,EACW,aAAa,CAAC,WAAW,EAAA;QAChD,MAAM,CAAsB;QACzB,QAAQ,GAAG,IAAI,GAAG,EAAoB,CAAA;QACtC,eAAe,CAAiB;QAE1C;;WAEG;QACH,WAAW,GAAG,CAAC,CAAC,CAAA;QAEhB;;;;;;WAMG;QACH,qBAAqB,GAAuC,IAAI,GAAG,EAAiC,CAAA;QAEpG,SAAS,CAAkB;QAE3B,IAAI,QAAQ;YACV,OAAO,IAAI,CAAC,SAAS,CAAA;QACvB,CAAC;QAED,YAAY,OAAyB;YACnC,KAAK,EAAE,CAAA;YACP,IAAI,CAAC,MAAM,GAAG,OAAO,EAAE,MAAM,CAAA;YAC7B,IAAI,CAAC,eAAe,GAAG,IAAI,eAAe,CAAC,IAAI,CAAC,CAAA;YAChD,IAAI,CAAC,SAAS,GAAG,IAAI,gBAAgB,CAAC,IAAI,CAAC,CAAA;QAC7C,CAAC;QAED;;;;WAIG;QACI,SAAS;YACd,OAAO,SAAS,CAAA;QAClB,CAAC;QAED;;WAEG;QACI,aAAa,CAAC,UAAgC;YACnD,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,UAAU,CAAC,CAAA;QAC1C,CAAC;QAED,MAAM,CAAC,IAAa;YAClB,IAAI,CAAC,aAAa,CAAC,IAAI,WAAW,CAAC,eAAe,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;QACxE,CAAC;QAED;;;;;;WAMG;QACH,QAAQ,CAAC,IAAc;YACrB,IAAI,CAAC,aAAa,CAAC,IAAI,WAAW,CAAC,iBAAiB,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;QAC1E,CAAC;QAED;;WAEG;QACH,QAAQ,CAAC,IAAc;YACrB,IAAI,CAAC,aAAa,CAAC,IAAI,WAAW,CAAC,iBAAiB,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;QAC1E,CAAC;QAED;;WAEG;QACH,OAAO;YACL,IAAI,CAAC,aAAa,CAAC,IAAI,WAAW,CAAC,gBAAgB,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;QACzE,CAAC;QAED;;WAEG;QACH,QAAQ;YACN,IAAI,CAAC,aAAa,CAAC,IAAI,WAAW,CAAC,iBAAiB,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;QAC1E,CAAC;QAED;;WAEG;QACH,OAAO;YACL,IAAI,CAAC,aAAa,CAAC,IAAI,WAAW,CAAC,gBAAgB,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;QACzE,CAAC;QAED;;WAEG;QACH,MAAM;YACJ,IAAI,CAAC,aAAa,CAAC,IAAI,WAAW,CAAC,eAAe,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;QACxE,CAAC;QAED;;WAEG;QACH,QAAQ;YACN,IAAI,CAAC,aAAa,CAAC,IAAI,WAAW,CAAC,iBAAiB,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;QAC1E,CAAC;QAED;;WAEG;QACH,SAAS;YACP,IAAI,CAAC,aAAa,CAAC,IAAI,WAAW,CAAC,kBAAkB,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;YACzE,IAAI,CAAC,eAAe,CAAC,SAAS,EAAE,CAAA;QAClC,CAAC;QAED;;WAEG;QACH,aAAa;YACX,EAAE;QACJ,CAAC;QAED;;;WAGG;QACH,MAAM;YACJ,MAAM,QAAQ,GAAG,IAAI,CAAC,wBAAwB,EAAE,CAAA;YAChD,IAAI,QAAQ,EAAE,CAAC;gBACb,uCAAuC;gBACvC,uEAAuE;gBACvE,8EAA8E;gBAC9E,OAAO,QAAQ,CAAC,MAAM,EAAE,CAAA;YAC1B,CAAC;YACD,OAAO,OAAO,CAAA;QAChB,CAAC;QAED;;;;;WAKG;QACH,wBAAwB;YACtB,MAAM,SAAS,GAAG,IAAI,CAAC,mBAAmB,EAAE,CAAA;YAC5C,OAAO,SAAS,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;QACrD,CAAC;QAED;;;WAGG;QACH,oBAAoB;YAClB,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC,CAAA;QAC/B,CAAC;QAED;;WAEG;QACH,mBAAmB;YACjB,OAAO,IAAI,CAAC,eAAe,CAAC,UAAU,EAAE,CAAA;QAC1C,CAAC;QAED;;;;;WAKG;QACH,KAAK,CAAC,QAAQ,CAAC,GAAW,EAAE,QAAkB,EAAE,IAAc;YAC5D,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAA;YAChC,MAAM,IAAI,CAAC,eAAe,CAAC,cAAc,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,CAAA;QACtE,CAAC;QAED;;;WAGG;QACH,KAAK,CAAC,WAAW,CAAC,GAAW;YAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;YACpC,IAAI,KAAK,EAAE,CAAC;gBACV,MAAM,IAAI,CAAC,eAAe,CAAC,cAAc,CAAC,GAAG,CAAC,CAAA;gBAC9C,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YAC3B,CAAC;QACH,CAAC;QAED;;;;;;;;;;;WAWG;QACH,iBAAiB,CAAC,GAAW;YAC3B,OAAO,CAAC,OAAiB,EAAE,EAAE;gBAC3B,IAAI,OAAO,EAAE,CAAC;oBACZ,IAAI,CAAC,eAAe,CAAC,YAAY,CAAC,GAAG,EAAE,OAAsB,CAAC,CAAA;gBAChE,CAAC;qBAAM,CAAC;oBACN,MAAM,QAAQ,GAAG,IAAI,CAAC,eAAe,CAAC,YAAY,CAAC,GAAG,CAAC,CAAA;oBACvD,IAAI,QAAQ,EAAE,CAAC;wBACb,IAAI,CAAC,eAAe,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAA;oBAC7C,CAAC;gBACH,CAAC;YACH,CAAC,CAAA;QACH,CAAC;QAED;;;WAGG;QACH,aAAa,CAAC,OAAsB,EAAE;YACpC,MAAM,EAAE,QAAQ,GAAG,IAAI,EAAE,GAAG,IAAI,CAAA;YAChC,IAAI,QAAQ,EAAE,CAAC;gBACb,IAAI,CAAC,SAAS,CAAC,aAAa,EAAE,CAAA;YAChC,CAAC;YACD,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,IAAI,CAAC,CAAA;YAChC,sDAAsD;QACxD,CAAC;QAED,cAAc;YACZ,OAAO,IAAI,CAAC,MAAM,EAAE,cAAc,EAAE,CAAA;QACtC,CAAC;QAED,WAAW;YACT,OAAO,IAAI,CAAC,MAAM,EAAE,WAAW,EAAE,CAAA;QACnC,CAAC;QAED;;;WAGG;QACH,KAAK,CAAC,sBAAsB,CAAC,MAAc;YACzC,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,EAAE,CAAA;YACnC,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAA;YAC7E,CAAC;YACD,IAAI,CAAC,WAAW,GAAG,MAAM,QAAQ,CAAC,sBAAsB,CAAC,MAAM,CAAC,CAAA;QAClE,CAAC;QAED;;;WAGG;QACH,KAAK,CAAC,aAAa,CAAC,MAAc;YAChC,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,EAAE,CAAA;YACnC,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAA;YAC7E,CAAC;YACD,MAAM,QAAQ,CAAC,aAAa,CAAC,MAAM,CAAC,CAAA;QACtC,CAAC;QAED;;;;;;;WAOG;QACH,KAAK,CAAC,gBAAgB,CAAC,WAAmB,EAAE,UAAwB,EAAE,MAAc;YAClF,MAAM,EAAE,qBAAqB,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAA;YAChD,IAAI,qBAAqB,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC;gBAC3C,MAAM,EAAE,QAAQ,EAAE,GAAG,qBAAqB,CAAC,GAAG,CAAC,WAAW,CAA0B,CAAA;gBACpF,qBAAqB,CAAC,MAAM,CAAC,WAAW,CAAC,CAAA;gBACzC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,CAAA;gBAC5B,OAAM;YACR,CAAC;YACD,KAAK,MAAM,QAAQ,IAAI,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;gBACzC,IAAI,QAAQ,CAAC,cAAc,CAAC,WAAW,CAAC,EAAE,CAAC;oBACzC,QAAQ,CAAC,gBAAgB,CAAC,WAAW,EAAE,UAAU,EAAE,MAAM,CAAC,CAAA;oBAC1D,OAAM;gBACR,CAAC;YACH,CAAC;YACD,IAAI,CAAC,WAAW,GAAG,CAAC,CAAC,CAAA;YACrB,IAAI,IAAI,CAAC,WAAW,KAAK,QAAQ,EAAE,CAAC;gBAClC,sCAAsC;gBACtC,OAAO,CAAC,IAAI,CAAC,6CAA6C,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,CAAC,CAAA;YAC9F,CAAC;QACH,CAAC;QAED,cAAc,CAAC,WAAmB;YAChC,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;gBAC9C,IAAI,QAAQ,CAAC,cAAc,CAAC,WAAW,CAAC,EAAE,CAAC;oBACzC,OAAO,IAAI,CAAA;gBACb,CAAC;YACH,CAAC;YACD,OAAO,IAAI,CAAC,WAAW,KAAK,WAAW,CAAA;QACzC,CAAC;QAED;;;;;;;;;;;;;;WAcG;QAEH,KAAK,CAAC,iBAAiB,CAAC,KAA6D;YACnF,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,EAAE,CAAA;YACnC,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAA;YAC7E,CAAC;YACD,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU,CAAC,MAAM,CAAC,sBAAsB,EAAE,CAAC;gBAC5D,MAAM,IAAI,GAAG,KAAK,CAAC,MAAkC,CAAA;gBACrD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,sBAAsB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;gBAC/D,IAAI,CAAC,WAAW,GAAG,IAAI,CAAA;gBACvB,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,IAAI,EAAE;oBACnC,QAAQ,EAAE,IAAI,CAAC,QAAQ;iBACxB,CAAC,CAAA;YACJ,CAAC;iBAAM,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC;gBAC1D,MAAM,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;YACnD,CAAC;iBAAM,CAAC;gBACN,MAAM,IAAI,KAAK,CAAC,8BAA8B,KAAK,CAAC,IAAI,EAAE,CAAC,CAAA;YAC7D,CAAC;QACH,CAAC;;;SAtUU,QAAQ","sourcesContent":["import { nothing, TemplateResult } from 'lit'\nimport { Activity } from './Activity.js'\nimport { FragmentState, type FragmentOptions, FragmentManager } from './FragmentManager.js'\nimport type { Application, UpdateRequest } from './Application.js'\nimport { FragmentRenderer } from './renderer/FragmentRenderer.js'\nimport { Intent, IntentResult } from './ActivityManager.js'\nimport { bound } from '../decorators/bound.js'\nimport type { ActivityDetail, ActivityWithResultDetail } from '../events/IntentEvents.js'\nimport { EventTypes } from '../events/EventTypes.js'\nimport { type RefOrCallback } from 'lit/directives/ref.js'\n\nexport interface PendingActivityResult {\n  onResult(result: IntentResult, intent: Intent): void\n}\n\n/**\n * Similar to Activity, with lifecycle methods (onCreate, onAttach, onDetach, etc.).\n * The crucial difference is that a Fragment is always hosted by an `Activity` or\n * another `Fragment`.\n *\n * A `Fragment` represents a reusable portion of the app's UI.\n * A fragment defines and manages its own layout, has its own lifecycle,\n * and can handle its own input events.\n * Fragments can't live on their own. They must be hosted by an activity or another\n * fragment. The fragment’s view hierarchy becomes part of, or attaches to,\n * the host’s view hierarchy.\n */\nexport class Fragment extends EventTarget {\n  public state: FragmentState = FragmentState.Initialized\n  public parent?: Activity | Fragment\n  protected children = new Map<string, Fragment>()\n  protected fragmentManager: FragmentManager\n\n  /**\n   * The request code used to start an activity for a result.\n   */\n  requestCode = -1\n\n  /**\n   * A list of pending activity results that were requested by the components\n   * hosted in this fragment.\n   * The key is the request code and the value contains the callback\n   * that will be called when the activity result is received.\n   * The callback is called with the result code and the resulting intent.\n   */\n  pendingActivityResult: Map<number, PendingActivityResult> = new Map<number, PendingActivityResult>()\n\n  #renderer: FragmentRenderer\n\n  get renderer(): FragmentRenderer {\n    return this.#renderer\n  }\n\n  constructor(options?: FragmentOptions) {\n    super()\n    this.parent = options?.parent\n    this.fragmentManager = new FragmentManager(this)\n    this.#renderer = new FragmentRenderer(this)\n  }\n\n  /**\n   * When implemented, this method returns the class name to be used as a root class for the fragment.\n   * This class name can be used to apply styles or identify the fragment in the DOM.\n   * @returns The class name to be used as a root class for the fragment.\n   */\n  public rootClass(): string | undefined {\n    return undefined\n  }\n\n  /**\n   * @see {@link ./Renderer.js}\n   */\n  public setRenderRoot(renderRoot: HTMLElement | string): void {\n    this.#renderer.setRenderRoot(renderRoot)\n  }\n\n  onData(data: unknown): void | Promise<void> {\n    this.dispatchEvent(new CustomEvent('fragment:data', { detail: data }))\n  }\n\n  /**\n   * Called once when the fragment is created.\n   *\n   * In the `onCreate()` method, perform basic fragment startup logic that happens only once\n   * for the entire life of the fragment.\n   * @param data Optional init data.\n   */\n  onCreate(data?: unknown): void | Promise<void> {\n    this.dispatchEvent(new CustomEvent('fragment:create', { detail: data }))\n  }\n\n  /**\n   * Called when the fragment is attached to a parent\n   */\n  onAttach(data?: unknown): void | Promise<void> {\n    this.dispatchEvent(new CustomEvent('fragment:attach', { detail: data }))\n  }\n\n  /**\n   * Called when the fragment becomes visible.\n   */\n  onStart(): void | Promise<void> {\n    this.dispatchEvent(new CustomEvent('fragment:start', { detail: null }))\n  }\n\n  /**\n   * Called when the fragment gains focus.\n   */\n  onResume(): void | Promise<void> {\n    this.dispatchEvent(new CustomEvent('fragment:resume', { detail: null }))\n  }\n\n  /**\n   * Called when the fragment loses focus.\n   */\n  onPause(): void | Promise<void> {\n    this.dispatchEvent(new CustomEvent('fragment:pause', { detail: null }))\n  }\n\n  /**\n   * Called when the fragment is no longer visible.\n   */\n  onStop(): void | Promise<void> {\n    this.dispatchEvent(new CustomEvent('fragment:stop', { detail: null }))\n  }\n\n  /**\n   * Called when the fragment is detached from a parent\n   */\n  onDetach(): void | Promise<void> {\n    this.dispatchEvent(new CustomEvent('fragment:detach', { detail: null }))\n  }\n\n  /**\n   * Called before the fragment is destroyed.\n   */\n  onDestroy(): void | Promise<void> {\n    this.dispatchEvent(new CustomEvent('fragment:destroy', { detail: null }))\n    this.fragmentManager.onDestroy()\n  }\n\n  /**\n   * Called by the renderer when the fragment is rendered for the first time.\n   */\n  onFirstRender(): void {\n    //\n  }\n\n  /**\n   * A function called when it should render the view.\n   * By default it renders a fragment view if the fragment hosts other fragments and only one is visible.\n   */\n  render(): TemplateResult | typeof nothing {\n    const fragment = this.getSingleVisibleFragment()\n    if (fragment) {\n      // we can manage the default rendering.\n      // we make an assumption that by default only one fragment is rendered,\n      // otherwise the parent activity or fragment would have to setup render roots.\n      return fragment.render()\n    }\n    return nothing\n  }\n\n  /**\n   * Checks whether there's only one `Fragment` that is in the `Resumed` state\n   * and returns it. It returns `null` if there is no `Fragment`s or more than a single\n   * visible `Fragment`.\n   * @returns A Fragment that is the only fragment that should be visible.\n   */\n  getSingleVisibleFragment(): Fragment | null {\n    const fragments = this.getVisibleFragments()\n    return fragments.length === 1 ? fragments[0] : null\n  }\n\n  /**\n   * Checks whether this fragment is a host for other fragments.\n   * @returns `true` when this fragment hosts other fragments.\n   */\n  isRenderingFragments(): boolean {\n    return this.children.size > 0\n  }\n\n  /**\n   * @returns The list of all fragments that are in the Resumed state.\n   */\n  getVisibleFragments(): Fragment[] {\n    return this.fragmentManager.getVisible()\n  }\n\n  /**\n   * Adds a child fragment to this fragment.\n   * The FragmentManager will handle lifecycle.\n   * @param key The name of the fragment.\n   * @param fragment The fragment to add.\n   */\n  async addChild(key: string, fragment: Fragment, data?: unknown): Promise<void> {\n    this.children.set(key, fragment)\n    await this.fragmentManager.attachFragment(key, fragment, this, data)\n  }\n\n  /**\n   * Removes a fragment from this fragment.\n   * @param key The name of the fragment to remove.\n   */\n  async removeChild(key: string): Promise<void> {\n    const child = this.children.get(key)\n    if (child) {\n      await this.fragmentManager.detachFragment(key)\n      this.children.delete(key)\n    }\n  }\n\n  /**\n   * Creates a RefCallback that can be used with lit's `ref()` directive\n   * to automatically show/hide a child fragment when its container element\n   * is added or removed from the DOM.\n   *\n   * @param key The key of the child fragment to manage.\n   * @returns A RefCallback to be used with the `ref()` directive.\n   *\n   * @example\n   * // In your parent fragment's render method:\n   * html`<div ${ref(this.createFragmentRef('my-child-fragment'))}></div>`\n   */\n  createFragmentRef(key: string): RefOrCallback<Element> {\n    return (element?: Element) => {\n      if (element) {\n        this.fragmentManager.showFragment(key, element as HTMLElement)\n      } else {\n        const fragment = this.fragmentManager.findFragment(key)\n        if (fragment) {\n          this.fragmentManager.hideFragment(fragment)\n        }\n      }\n    }\n  }\n\n  /**\n   * A helper to request an update.\n   * Application or parent Fragment will handle rendering.\n   */\n  requestUpdate(opts: UpdateRequest = {}): void {\n    const { fragment = true } = opts\n    if (fragment) {\n      this.#renderer.requestUpdate()\n    }\n    this.parent?.requestUpdate(opts)\n    // If no parent, do nothing (or maybe throw an error?)\n  }\n\n  getApplication(): Application | undefined {\n    return this.parent?.getApplication()\n  }\n\n  getActivity(): Activity | undefined {\n    return this.parent?.getActivity()\n  }\n\n  /**\n   * Starts an activity for result.\n   * @param intent The intent to start.\n   */\n  async startActivityForResult(intent: Intent): Promise<void> {\n    const activity = this.getActivity()\n    if (!activity) {\n      throw new Error(`The fragment has no activity. Unable to start an intent.`)\n    }\n    this.requestCode = await activity.startActivityForResult(intent)\n  }\n\n  /**\n   * Starts another activity.\n   * @param intent The intent to start.\n   */\n  async startActivity(intent: Intent): Promise<void> {\n    const activity = this.getActivity()\n    if (!activity) {\n      throw new Error(`The fragment has no activity. Unable to start an intent.`)\n    }\n    await activity.startActivity(intent)\n  }\n\n  /**\n   * The callback method that is triggered when another activity that was\n   * started for result finishes.\n   *\n   * @param requestCode The request code that was used to start the activity.\n   * @param data The data that was passed back.\n   * @param intent The intent that was used to start the activity.\n   */\n  async onActivityResult(requestCode: number, resultCode: IntentResult, intent: Intent): Promise<void> {\n    const { pendingActivityResult, children } = this\n    if (pendingActivityResult.has(requestCode)) {\n      const { onResult } = pendingActivityResult.get(requestCode) as PendingActivityResult\n      pendingActivityResult.delete(requestCode)\n      onResult(resultCode, intent)\n      return\n    }\n    for (const fragment of children.values()) {\n      if (fragment.hasRequestCode(requestCode)) {\n        fragment.onActivityResult(requestCode, resultCode, intent)\n        return\n      }\n    }\n    this.requestCode = -1\n    if (this.constructor === Fragment) {\n      // eslint-disable-next-line no-console\n      console.info('Fragment#onActivityResult() not implemented', requestCode, resultCode, intent)\n    }\n  }\n\n  hasRequestCode(requestCode: number): boolean {\n    for (const fragment of this.children.values()) {\n      if (fragment.hasRequestCode(requestCode)) {\n        return true\n      }\n    }\n    return this.requestCode === requestCode\n  }\n\n  /**\n   * A handler for the intent event dispatched by web components hosted by this fragment.\n   *\n   * **Usage example:**\n   *\n   * ```ts\n   * <custom-element @startactivity=\"${this.handleIntentEvent}\"></custom-element>\n   * <custom-element @startactivityforresult=\"${this.handleIntentEvent}\"></custom-element>\n   * ```\n   *\n   * @param event The event that was dispatched.\n   * @returns A promise that resolves when the intent is handled.\n   * @throws An error if the fragment has no activity.\n   * @throws An error if the event type is not recognized.\n   */\n  @bound\n  async handleIntentEvent(event: CustomEvent<ActivityDetail | ActivityWithResultDetail>): Promise<void> {\n    const activity = this.getActivity()\n    if (!activity) {\n      throw new Error(`The fragment has no activity. Unable to start an intent.`)\n    }\n    if (event.type === EventTypes.Intent.startActivityForResult) {\n      const info = event.detail as ActivityWithResultDetail\n      const code = await activity.startActivityForResult(info.intent)\n      this.requestCode = code\n      this.pendingActivityResult.set(code, {\n        onResult: info.onResult,\n      })\n    } else if (event.type === EventTypes.Intent.startActivity) {\n      await activity.startActivity(event.detail.intent)\n    } else {\n      throw new Error(`Unrecognized intent event: ${event.type}`)\n    }\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@api-client/ui",
-  "version": "0.5.34",
+  "version": "0.5.35",
   "description": "Internal UI component library for the API Client ecosystem.",
   "license": "UNLICENSED",
   "main": "build/src/index.js",

package/src/core/Fragment.ts

@@ -7,6 +7,7 @@ import { Intent, IntentResult } from './ActivityManager.js'
 import { bound } from '../decorators/bound.js'
 import type { ActivityDetail, ActivityWithResultDetail } from '../events/IntentEvents.js'
 import { EventTypes } from '../events/EventTypes.js'
+import { type RefOrCallback } from 'lit/directives/ref.js'
 
 export interface PendingActivityResult {
   onResult(result: IntentResult, intent: Intent): void
@@ -209,6 +210,31 @@ export class Fragment extends EventTarget {
     }
   }
 
+  /**
+   * Creates a RefCallback that can be used with lit's `ref()` directive
+   * to automatically show/hide a child fragment when its container element
+   * is added or removed from the DOM.
+   *
+   * @param key The key of the child fragment to manage.
+   * @returns A RefCallback to be used with the `ref()` directive.
+   *
+   * @example
+   * // In your parent fragment's render method:
+   * html`<div ${ref(this.createFragmentRef('my-child-fragment'))}></div>`
+   */
+  createFragmentRef(key: string): RefOrCallback<Element> {
+    return (element?: Element) => {
+      if (element) {
+        this.fragmentManager.showFragment(key, element as HTMLElement)
+      } else {
+        const fragment = this.fragmentManager.findFragment(key)
+        if (fragment) {
+          this.fragmentManager.hideFragment(fragment)
+        }
+      }
+    }
+  }
+
   /**
    * A helper to request an update.
    * Application or parent Fragment will handle rendering.

package/test/core/fragment.spec.ts

@@ -1,6 +1,6 @@
 import { assert } from '@esm-bundle/chai'
 import sinon from 'sinon'
-import { fixture, html } from '@open-wc/testing'
+import { fixture, html, nextFrame } from '@open-wc/testing'
 import { Fragment } from '../../src/core/Fragment.js'
 import { Activity } from '../../src/core/Activity.js'
 import { Application } from '../../src/core/Application.js'
@@ -8,8 +8,9 @@ import { FragmentState, FragmentManager } from '../../src/core/FragmentManager.j
 import { IntentResult, type Intent, ActivityLifecycle } from '../../src/core/ActivityManager.js'
 import { FragmentRenderer } from '../../src/core/renderer/FragmentRenderer.js'
 import { EventTypes } from '../../src/events/EventTypes.js'
-import { nothing } from 'lit'
+import { nothing, render } from 'lit'
 import type { ActivityDetail } from '../../src/events/IntentEvents.js'
+import { ref } from 'lit/directives/ref.js'
 
 class TestActivity extends Activity {
   static override action = 'test-activity'
@@ -273,6 +274,35 @@ describe('Fragment', () => {
     })
   })
 
+  describe('createFragmentRef()', () => {
+    it('shows and hides a fragment via lit ref directive', async () => {
+      const childFragment = new TestFragment()
+      await fragment.addChild('childKey', childFragment)
+
+      const showSpy = sinon.spy(fragment['fragmentManager'], 'showFragment')
+      const hideSpy = sinon.spy(fragment['fragmentManager'], 'hideFragment')
+      // When the element is removed, the ref callback is called with `undefined`.
+      // The implementation then calls `findFragment` to get the fragment instance.
+      sinon.stub(fragment['fragmentManager'], 'findFragment').withArgs('childKey').returns(childFragment)
+      const root = document.createElement('div')
+      document.body.appendChild(root)
+      const tpl1 = html`<div class="target" ${ref(fragment.createFragmentRef('childKey'))}></div>`
+      render(tpl1, root)
+
+      const childDiv = root.querySelector<HTMLElement>('div')!
+
+      assert.isTrue(showSpy.calledOnce, 'showFragment should be called on render')
+      assert.isTrue(showSpy.calledWith('childKey', childDiv), 'showFragment called with correct arguments')
+
+      // Re-render without the ref to trigger disconnection
+      render(html`<span></span>`, root)
+      await nextFrame()
+      assert.isTrue(hideSpy.calledOnce, 'hideFragment should be called on removal')
+      assert.isTrue(hideSpy.calledWith(childFragment), 'hideFragment called with correct fragment instance')
+      assert.isNull(root.querySelector('div'), 'Target div should be removed from DOM')
+    })
+  })
+
   describe('requestUpdate()', () => {
     it('calls renderer.requestUpdate by default', () => {
       const rendererSpy = sinon.spy(fragment.renderer, 'requestUpdate')