@cardstack/boxel-cli 0.13.0-unstable.4 → 0.13.0-unstable.5

package/bundled-types/choreo/choreo.gts

@@ -1402,11 +1402,23 @@ export class Choreo extends Component<Signature> implements ChoreoHost {
    * participant standing in the same layout box it compiled in (a REFLOW
    * always replays — it is what a Move is FOR). Anything else takes the
    * full pipeline.
+   *
+   * A run that is nothing but ambient loops counts as in flight after its
+   * clock ends, for as long as the loops go round. A loop lends its run no
+   * length, so a loop-only run ends as soon as it starts, and without this
+   * every later app render would replace the run, cancelling each loop's
+   * animation for a new one. The layout check still applies to such a run.
+   * A loop on a layout property (width, height) changes the boxes
+   * `layoutOf` reads on every frame, so no pass matches the layout the run
+   * compiled in, and each one replaces the run, as it does a Move that
+   * animates size. A score with anything besides loops in it has a
+   * timeline to re-fire (§3.1), so once it ends, a pass takes the full
+   * pipeline.
    */
   private fastKeep(root: HTMLElement): boolean {
     if (
       !this.run ||
-      this.run.isDone() ||
+      (this.run.isDone() && !this.run.isLooping()) ||
       this.claimed.size ||
       this.arrived.size
     ) {

package/bundled-types/choreo/run.ts

@@ -99,6 +99,12 @@ export interface Run {
   finished: Promise<void>;
   /** nothing left to play: the run completed or was cancelled */
   isDone(): boolean;
+  /**
+   * The run completed and every cue it has is an ambient loop, still going
+   * round. Such a run is done but not over: its loops play on until a pass
+   * replaces it.
+   */
+  isLooping(): boolean;
   /**
    * Where each of this run's ambient loops is in its cycle. A replacement
    * run starts the same loop on the same sprite from there, so an edited
@@ -772,6 +778,19 @@ export class ChoreoRun implements Run {
   isDone(): boolean {
     return this.ended || this.cancelled;
   }
+  isLooping(): boolean {
+    return (
+      this.ended &&
+      !this.cancelled &&
+      this.tracks.length > 0 &&
+      this.tracks.every(
+        (t) =>
+          t.cue.loop &&
+          t.loopAnimation !== undefined &&
+          t.loopAnimation.playState !== 'idle',
+      )
+    );
+  }
   /**
    * A text delivery is still standing in for its sprite's text. The clock
    * can end first: a delivery lands on its own platform animations, and the

package/bundled-types/host-app/components/operator-mode/dashboard/get-started.gts

@@ -1,3 +1,4 @@
+import { fn } from '@ember/helper';
 import { on } from '@ember/modifier';
 import { action } from '@ember/object';
 import { guidFor } from '@ember/object/internals';
@@ -11,18 +12,21 @@ import ChevronDown from '@cardstack/boxel-icons/chevron-down';
 import ChevronUp from '@cardstack/boxel-icons/chevron-up';
 import { Button } from '@cardstack/pretui/components/button';
 import { IconButton } from '@cardstack/pretui/components/icon-button';
+import { Menu } from '@cardstack/pretui/components/menu';
 import { ProgressBar } from '@cardstack/pretui/components/progress-bar';
 import { VisuallyHidden } from '@cardstack/pretui/components/visually-hidden';
 import { didCancel, dropTask, task, timeout } from 'ember-concurrency';
 import { modifier } from 'ember-modifier';
 
-import { cn, eq } from '@cardstack/boxel-ui/helpers';
+import { cn, eq, not } from '@cardstack/boxel-ui/helpers';
 
-import { logger } from '@cardstack/runtime-common';
+import { logger, type RealmIdentifier } from '@cardstack/runtime-common';
 
+import { realmIdentifierSegments } from '@cardstack/host/lib/realm-utils';
 import { isHostedRealm } from '@cardstack/host/lib/workspace-list';
 import { NEW_SESSION_NAME } from '@cardstack/host/services/ai-assistant-panel-service';
 import type AiAssistantPanelService from '@cardstack/host/services/ai-assistant-panel-service';
+import type HostModeService from '@cardstack/host/services/host-mode-service';
 import type MatrixService from '@cardstack/host/services/matrix-service';
 import type OperatorModeStateService from '@cardstack/host/services/operator-mode-state-service';
 import type RealmService from '@cardstack/host/services/realm';
@@ -30,6 +34,9 @@ import type RealmServerService from '@cardstack/host/services/realm-server';
 import type RecentCardsService from '@cardstack/host/services/recent-cards-service';
 
 import { AGENT_KINDS, usesCodingAgent } from './agent-kinds';
+import { sortByUpdatedAtDesc } from './workspace-layout';
+
+import type { MenuEntry } from '@cardstack/pretui/internal/menu';
 
 const log = logger('component:dashboard/get-started');
 
@@ -83,6 +90,10 @@ interface Signature {
   };
 }
 
+function countOf<T>(values: T[], value: T) {
+  return values.filter((other) => other === value).length;
+}
+
 // The dashboard's onboarding checklist. Every tick comes from something the
 // user has actually done, read from state the host already keeps, so the list
 // can't drift from what happened. A button in the page's header opens and
@@ -93,6 +104,7 @@ export default class GetStarted extends Component<Signature> {
   @service declare private operatorModeStateService: OperatorModeStateService;
   @service declare private realm: RealmService;
   @service declare private realmServer: RealmServerService;
+  @service declare private hostModeService: HostModeService;
   @service declare private recentCardsService: RecentCardsService;
 
   // The open list and the dismissed note each hold only for the dismissal
@@ -331,6 +343,73 @@ export default class GetStarted extends Component<Signature> {
     }
   }
 
+  // The workspaces the user can publish, most recently updated first.
+  // Read several times a render.
+  @cached
+  private get workspacesToPublish() {
+    return sortByUpdatedAtDesc(
+      this.realmServer.userRealmIdentifiers.filter((url) =>
+        this.realm.canPublish(url),
+      ),
+      this.realm.info,
+    );
+  }
+
+  // Why there's nothing to publish. A workspace made before workspaces were
+  // marked publishable isn't, so owning one isn't enough.
+  private get publishUnavailableNote() {
+    return this.realmServer.userRealmIdentifiers.some((url) =>
+      this.realm.isRealmOwner(url),
+    )
+      ? 'None of your workspaces can be published. Create a new one to publish it.'
+      : 'Publishing needs a workspace you own. Create one to publish it.';
+  }
+
+  // The note waits for the info of every workspace the user owns: until a
+  // workspace's info loads, it may yet turn out publishable.
+  private get showsPublishUnavailableNote() {
+    return (
+      this.workspacesToPublish.length === 0 &&
+      this.realmServer.userRealmIdentifiers
+        .filter((url) => this.realm.isRealmOwner(url))
+        .every((url) => this.realm.isInfoLoaded(url))
+    );
+  }
+
+  // With one workspace to publish the button opens it in host mode to
+  // publish; with more, a menu asks which.
+  private get onlyWorkspaceToPublish() {
+    let [only, ...rest] = this.workspacesToPublish;
+    return rest.length === 0 ? only : undefined;
+  }
+
+  // Workspaces that share a name are told apart by the last segment of
+  // their address, or by the whole address when that segment is shared too.
+  private get publishMenuItems(): MenuEntry[] {
+    let workspaces = this.workspacesToPublish;
+    let names = workspaces.map((url) => this.realm.info(url).name);
+    let withSegment = workspaces.map((url, index) => {
+      let segment = realmIdentifierSegments(url).at(-1);
+      return segment ? `${names[index]} (${segment})` : undefined;
+    });
+    return workspaces.map((url, index) => {
+      let label = names[index];
+      if (countOf(names, label) > 1) {
+        let short = withSegment[index];
+        label =
+          short && countOf(withSegment, short) === 1
+            ? short
+            : `${label} (${this.realm.realmURLTextOf(url) ?? url})`;
+      }
+      return { label, onSelect: () => this.openToPublish(url) };
+    });
+  }
+
+  // Publishing happens in host mode, which shows the site it publishes.
+  @action private openToPublish(workspace: RealmIdentifier) {
+    this.hostModeService.openToPublishTask.perform(workspace);
+  }
+
   @action private async askBoxelAi() {
     await this.aiAssistantPanelService.openNewSession();
   }
@@ -420,8 +499,66 @@ export default class GetStarted extends Component<Signature> {
                       {{/if}}
                     </span>
                     <span class='step-hint'>{{step.hint}}</span>
+                    {{#if (eq step.id 'publish')}}
+                      {{#unless step.done}}
+                        {{#if this.showsPublishUnavailableNote}}
+                          <span
+                            class='step-note'
+                            data-test-get-started-publish-unavailable
+                          >{{this.publishUnavailableNote}}</span>
+                        {{/if}}
+                      {{/unless}}
+                    {{/if}}
                   </span>
-                  {{#unless step.done}}
+                  {{! Publishing again stays a step away once one workspace
+                      is on the web. }}
+                  {{#if (eq step.id 'publish')}}
+                    {{#if this.onlyWorkspaceToPublish}}
+                      <Button
+                        class='step-action'
+                        @appearance='outlined'
+                        @size='s'
+                        {{on
+                          'click'
+                          (fn this.openToPublish this.onlyWorkspaceToPublish)
+                        }}
+                        data-test-get-started-action={{step.id}}
+                      >Publish a workspace</Button>
+                    {{else if this.workspacesToPublish.length}}
+                      <Menu
+                        class='step-action'
+                        @items={{this.publishMenuItems}}
+                        @label='Workspaces to publish'
+                        @align='end'
+                      >
+                        <:trigger as |isMenuOpen toggle|>
+                          <Button
+                            @appearance='outlined'
+                            @size='s'
+                            {{on 'click' toggle}}
+                            data-test-get-started-action={{step.id}}
+                          >Publish a workspace
+                            {{#if isMenuOpen}}
+                              <ChevronUp
+                                width='14'
+                                height='14'
+                                class='publish-chevron'
+                                aria-hidden='true'
+                                data-test-get-started-publish-chevron='up'
+                              />
+                            {{else}}
+                              <ChevronDown
+                                width='14'
+                                height='14'
+                                class='publish-chevron'
+                                aria-hidden='true'
+                                data-test-get-started-publish-chevron='down'
+                              />
+                            {{/if}}</Button>
+                        </:trigger>
+                      </Menu>
+                    {{/if}}
+                  {{else if (not step.done)}}
                     {{#if (eq step.id 'open-card')}}
                       {{#if this.realmServer.userRealmIdentifiers.length}}
                         <Button
@@ -449,7 +586,7 @@ export default class GetStarted extends Component<Signature> {
                         data-test-get-started-action={{step.id}}
                       >Set up an agent</Button>
                     {{/if}}
-                  {{/unless}}
+                  {{/if}}
                 </li>
               {{/each}}
             </ol>
@@ -560,10 +697,15 @@ export default class GetStarted extends Component<Signature> {
         color: var(--muted-foreground);
         font-weight: 500;
       }
-      .step-hint {
+      .step-hint,
+      .step-note {
         font-size: var(--boxel-font-size-xs);
         color: var(--muted-foreground);
       }
+      /* Keeps its size when the label runs short of room. */
+      .publish-chevron {
+        flex: none;
+      }
       .get-started-dismissed {
         display: flex;
         flex-wrap: wrap;
@@ -617,9 +759,12 @@ export default class GetStarted extends Component<Signature> {
         .get-started-step {
           grid-template-columns: var(--_get-started-tick-size) minmax(0, 1fr);
         }
+        /* The action takes the whole row, tick column included: the text
+           column alone is narrower than a labeled button. It stays at the
+           row's end, as in the wide layout. */
         .step-action {
-          grid-column: 2;
-          justify-self: start;
+          grid-column: 1 / -1;
+          justify-self: end;
         }
       }
     </style>

package/bundled-types/host-app/components/operator-mode/dashboard/index.gts

@@ -576,10 +576,12 @@ export default class Dashboard extends Component<Signature> {
             <:head as |getStarted|>
               <header class='page-head'>
                 <div class='greeting-line'>
+                  {{! Percy hides the greeting: it changes with the hour. }}
                   <h1
                     class='greeting'
                     {{this.trackHour}}
                     data-test-dashboard-greeting
+                    data-test-percy-hide
                   >{{this.greeting}}</h1>
                   {{#if getStarted.isReady}}
                     {{! Light mode on the dark dashboard, so the neutral open state

package/bundled-types/host-app/components/operator-mode/dashboard/workspace.gts

@@ -335,8 +335,10 @@ export default class Workspace extends Component<Signature> {
         >
           {{! The star's fill already shows the state, so it takes no
               pressed tint, which would show as a gray square on the chip.
-              Its tip opens to the right, into the tile: centered above the
-              corner, it would run past the tile into a narrow gutter. }}
+              Its tip opens into the workspace, away from the edge the star
+              sits on: right from a tile's top-left corner, left from a row's
+              right end. Centered, or opened the other way, it would run
+              past the workspace. }}
           <IconButton
             @label='Favorite'
             @appearance='plain'
@@ -347,7 +349,7 @@ export default class Workspace extends Component<Signature> {
               'Remove from Favorites'
               'Add to Favorites'
             }}
-            @tooltipSide='right'
+            @tooltipSide={{if (eq @variant 'row') 'left' 'right'}}
             {{on 'click' this.workspace.toggleFavorite}}
             data-test-workspace-favorite-btn={{@realmIdentifier}}
           >

package/bundled-types/host-app/components/operator-mode/dashboard-modals/workspace-modals.gts

@@ -14,33 +14,16 @@ import { Warning as WarningIcon } from '@cardstack/boxel-ui/icons';
 import type { RealmIdentifier } from '@cardstack/runtime-common';
 
 import ModalContainer from '@cardstack/host/components/modal-container';
+import { modalFocusTrapOptions } from '@cardstack/host/lib/modal-focus-trap';
 import type { EnhancedRealmInfo } from '@cardstack/host/services/realm';
 
 // The tile's Delete, Archive and Duplicate modals. The tile sends them to the
 // operator-mode modal outlet, so they render outside the dashboard's size
 // container, which would otherwise trap their fixed positioning.
-
-interface ModalFocusArgs {
-  onClose: () => void;
-  returnFocusTarget: () => HTMLElement | undefined;
-}
-
-// Focus opens on Cancel, stays in the modal, and goes back to the tile on
-// close. Escape closes the modal. The confirm button turns busy
-// rather than being replaced while its task runs, so it keeps focus.
-function modalFocusTrapOptions(dialogId: string, args: ModalFocusArgs) {
-  return {
-    initialFocus: `#${dialogId} [data-modal-initial-focus]`,
-    fallbackFocus: `#${dialogId}`,
-    allowOutsideClick: true,
-    escapeDeactivates: () => {
-      args.onClose();
-      return false;
-    },
-    setReturnFocus: (previous: HTMLElement | SVGElement) =>
-      args.returnFocusTarget() ?? previous,
-  };
-}
+//
+// Each opens with focus on Cancel and hands it back to the tile on close.
+// The confirm button turns busy rather than being replaced while its task
+// runs, so it keeps focus.
 
 interface DeleteWorkspaceModalSignature {
   Args: {

package/bundled-types/host-app/components/operator-mode/host-submode/publishing-realm-popover.gts

@@ -32,7 +32,7 @@ export default class PublishingRealmPopover extends Component<PublishingRealmArg
 
   <template>
     {{#if @isOpen}}
-      <div class='publishing-realm-popover'>
+      <div class='publishing-realm-popover' data-test-publishing-realm-popover>
         <div class='publishing-realm-header'>
           Publishing to:
         </div>

package/bundled-types/host-app/components/operator-mode/host-submode.gts

@@ -1,6 +1,7 @@
 import { fn } from '@ember/helper';
 import { on } from '@ember/modifier';
 import { action } from '@ember/object';
+import { guidFor } from '@ember/object/internals';
 import { service } from '@ember/service';
 import Component from '@glimmer/component';
 import { tracked } from '@glimmer/tracking';
@@ -11,13 +12,21 @@ import onClickOutside from 'ember-click-outside/modifiers/on-click-outside';
 
 import { restartableTask } from 'ember-concurrency';
 import perform from 'ember-concurrency/helpers/perform';
+import focusTrap from 'ember-focus-trap/modifiers/focus-trap';
+import { modifier } from 'ember-modifier';
 
 import { BoxelButton, Tooltip } from '@cardstack/boxel-ui/components';
 import { PublishSiteIcon } from '@cardstack/boxel-ui/icons';
 
+import { ensureTrailingSlash } from '@cardstack/runtime-common';
+
 import OpenSitePopover from '@cardstack/host/components/operator-mode/host-submode/open-site-popover';
 import PublishingRealmPopover from '@cardstack/host/components/operator-mode/host-submode/publishing-realm-popover';
 import PublishRealmModal from '@cardstack/host/components/operator-mode/publish-realm-modal';
+import {
+  ifConnected,
+  modalFocusTrapOptions,
+} from '@cardstack/host/lib/modal-focus-trap';
 
 import type HostModeService from '@cardstack/host/services/host-mode-service';
 import type OperatorModeStateService from '@cardstack/host/services/operator-mode-state-service';
@@ -48,18 +57,60 @@ export default class HostSubmode extends Component<HostSubmodeSignature> {
   @service declare private hostModeService: HostModeService;
   @service declare private toolService: ToolService;
 
-  @tracked isPublishRealmModalOpen = false;
   @tracked isPublishingRealmPopoverOpen = false;
   @tracked isOpenSitePopoverOpen = false;
 
   @action
   openPublishRealmModal() {
-    this.isPublishRealmModalOpen = true;
+    // A popover left open during a publish started elsewhere doesn't come
+    // back with this one.
+    this.isPublishingRealmPopoverOpen = false;
+    this.hostModeService.publishDialogRealm = ensureTrailingSlash(
+      this.realmURL,
+    );
   }
 
   @action
   closePublishRealmModal() {
-    this.isPublishRealmModalOpen = false;
+    this.hostModeService.publishDialogRealm = undefined;
+  }
+
+  get isPublishRealmModalOpen() {
+    return (
+      this.hostModeService.publishDialogRealm ===
+      ensureTrailingSlash(this.realmURL)
+    );
+  }
+
+  // Leaving host mode closes the dialog, so it doesn't come back open later.
+  willDestroy() {
+    super.willDestroy();
+    this.hostModeService.publishDialogRealm = undefined;
+  }
+
+  private publishDialogId = guidFor(this);
+
+  private get publishDialogRealms() {
+    return [this.realmURL];
+  }
+
+  // The visible title asks "Where to?"; the name says what is published.
+  private get publishDialogLabel() {
+    return `Publish ${this.realm.info(this.realmURL).name}`;
+  }
+
+  // The publish button, which becomes a "Publishing…" button while a publish
+  // runs, so focus goes back to whichever is on screen when the dialog closes.
+  private publishButton: HTMLElement | undefined;
+  private capturePublishButton = modifier((element: HTMLElement) => {
+    this.publishButton = element;
+  });
+
+  private get publishFocusTrapOptions() {
+    return modalFocusTrapOptions(this.publishDialogId, {
+      onClose: this.closePublishRealmModal,
+      returnFocusTarget: () => ifConnected(this.publishButton),
+    });
   }
 
   @action
@@ -80,6 +131,12 @@ export default class HostSubmode extends Component<HostSubmodeSignature> {
     return this.realm.isPublishing(this.realmURL);
   }
 
+  // Shown on request while a publish runs, and gone with the publish,
+  // whether it succeeds or fails.
+  get showsPublishingRealmPopover() {
+    return this.isPublishingRealmPopoverOpen && this.isPublishing;
+  }
+
   get hasPublishedSites() {
     return this.hostModeService.publishedRealmURLs.length > 0;
   }
@@ -97,35 +154,42 @@ export default class HostSubmode extends Component<HostSubmodeSignature> {
   }
 
   handlePublishTask = restartableTask(async (publishedRealmURLs: string[]) => {
-    // Publish through the same command exposed to boxel-cli so the UI and
-    // headless callers share one path. The modal already enforces the
-    // publishability gate, so force past the command's redundant re-check.
-    let command = new PublishRealmTool(this.toolService.toolContext);
-    let result = await command.execute({
-      realmURL: this.realmURL,
-      publishedRealmURLs,
-      force: true,
-    });
-
-    const errors = new Map<string, string>();
-    for (let target of result.results) {
-      if (target.status === 'error' || target.status === 'published-pending') {
-        errors.set(
-          target.publishedRealmURL,
-          target.error || 'Failed to publish to this domain',
-        );
+    try {
+      // Publish through the same command exposed to boxel-cli so the UI and
+      // headless callers share one path. The modal already enforces the
+      // publishability gate, so force past the command's redundant re-check.
+      let command = new PublishRealmTool(this.toolService.toolContext);
+      let result = await command.execute({
+        realmURL: this.realmURL,
+        publishedRealmURLs,
+        force: true,
+      });
+
+      const errors = new Map<string, string>();
+      for (let target of result.results) {
+        if (
+          target.status === 'error' ||
+          target.status === 'published-pending'
+        ) {
+          errors.set(
+            target.publishedRealmURL,
+            target.error || 'Failed to publish to this domain',
+          );
+        }
       }
-    }
 
-    if (errors.size > 0) {
-      const error = new Error(
-        'Failed to publish to some domains',
-      ) as PublishError;
-      error.urlErrors = errors;
-      throw error;
+      if (errors.size > 0) {
+        const error = new Error(
+          'Failed to publish to some domains',
+        ) as PublishError;
+        error.urlErrors = errors;
+        throw error;
+      }
+    } finally {
+      // The popover goes with the publish it was opened for, whether it
+      // succeeds or fails.
+      this.isPublishingRealmPopoverOpen = false;
     }
-
-    this.isPublishingRealmPopoverOpen = false;
   });
 
   @action
@@ -200,6 +264,7 @@ export default class HostSubmode extends Component<HostSubmodeSignature> {
               @size='tall'
               class='publish-realm-button publishing'
               {{on 'click' this.togglePublishingRealmPopover}}
+              {{this.capturePublishButton}}
               data-test-publish-realm-button
             >
               <Refresh width='22' height='22' class='publish-icon' />
@@ -211,6 +276,7 @@ export default class HostSubmode extends Component<HostSubmodeSignature> {
               @size='tall'
               class='publish-realm-button'
               {{on 'click' this.openPublishRealmModal}}
+              {{this.capturePublishButton}}
               data-test-publish-realm-button
             >
               <PublishSiteIcon width='22' height='22' class='publish-icon' />
@@ -220,7 +286,7 @@ export default class HostSubmode extends Component<HostSubmodeSignature> {
             </BoxelButton>
           {{/if}}
           <PublishingRealmPopover
-            @isOpen={{this.isPublishingRealmPopoverOpen}}
+            @isOpen={{this.showsPublishingRealmPopover}}
           />
         </div>
         {{#if this.hasPublishedSites}}
@@ -270,13 +336,21 @@ export default class HostSubmode extends Component<HostSubmodeSignature> {
       </:default>
     </SubmodeLayout>
 
-    <PublishRealmModal
-      @isOpen={{this.isPublishRealmModalOpen}}
-      @onClose={{this.closePublishRealmModal}}
-      @handlePublish={{this.handlePublish}}
-      @publishError={{this.handlePublishError}}
-      @handleUnpublish={{perform this.handleUnpublish}}
-    />
+    {{! Keyed by the realm, so another workspace gets a new dialog: it loads
+        a workspace's unlisted link and domains when it's made. }}
+    {{#each this.publishDialogRealms key='@identity' as |_realmURL|}}
+      <PublishRealmModal
+        @isOpen={{this.isPublishRealmModalOpen}}
+        @onClose={{this.closePublishRealmModal}}
+        @handlePublish={{this.handlePublish}}
+        @publishError={{this.handlePublishError}}
+        @handleUnpublish={{perform this.handleUnpublish}}
+        aria-label={{this.publishDialogLabel}}
+        id={{this.publishDialogId}}
+        tabindex='-1'
+        {{focusTrap focusTrapOptions=this.publishFocusTrapOptions}}
+      />
+    {{/each}}
 
     <style scoped>
       .host-submode-layout {

package/bundled-types/host-app/components/operator-mode/publish-realm-modal.gts

@@ -1031,6 +1031,7 @@ export default class PublishRealmModal extends Component<Signature> {
       @isOpen={{@isOpen}}
       @onClose={{this.handleCancel}}
       data-test-publish-realm-modal
+      ...attributes
     >
       <:header>
         <div class='modal-subtitle'>

package/bundled-types/host-app/lib/modal-focus-trap.ts

@@ -0,0 +1,33 @@
+interface ModalFocusArgs {
+  onClose: () => void;
+  returnFocusTarget?: () => HTMLElement | undefined;
+}
+
+// Options for the `focusTrap` modifier on a modal whose element has the id
+// `dialogId`. Focus opens on the element marked `data-modal-initial-focus`,
+// or on the modal itself when none is, stays in the modal, and on close goes
+// to `returnFocusTarget` or back to where it was. Escape closes the modal.
+export function modalFocusTrapOptions(dialogId: string, args: ModalFocusArgs) {
+  return {
+    initialFocus: () =>
+      document.querySelector<HTMLElement>(
+        `#${dialogId} [data-modal-initial-focus]`,
+      ) ?? `#${dialogId}`,
+    fallbackFocus: `#${dialogId}`,
+    allowOutsideClick: true,
+    escapeDeactivates: () => {
+      args.onClose();
+      return false;
+    },
+    setReturnFocus: (previous: HTMLElement | SVGElement) =>
+      args.returnFocusTarget?.() ?? previous,
+  };
+}
+
+// The element when it's still on the page, for a `returnFocusTarget` whose
+// opener may have been replaced or removed while the modal was open.
+export function ifConnected(
+  element: HTMLElement | undefined,
+): HTMLElement | undefined {
+  return element?.isConnected ? element : undefined;
+}