@design.estate/dees-catalog 11.2.2 → 12.1.0

package/ts_web/elements/00group-harness/dees-terminal-view/dees-terminal-view.ts

@@ -93,6 +93,11 @@ export class DeesTerminalView extends DeesElement {
   private pendingWriteBytes = 0;
   private pendingWritesDropped = false;
   private setupPromise: Promise<void> | undefined;
+  /**
+   * Set only by an explicit `focus()` that arrived before the terminal existed. Nothing else sets
+   * it, so a re-render, a write, or a resize can never move the caret into this element.
+   */
+  private focusWhenReady = false;
   private readyPending = true;
   private readyResolve: () => void = () => undefined;
   private readyReject: (reasonArg: unknown) => void = () => undefined;
@@ -302,8 +307,35 @@ export class DeesTerminalView extends DeesElement {
     this.pendingWritesDropped = false;
   }
 
-  public focus(): void {
-    this.terminal?.focus();
+  /**
+   * Moves the caret into the terminal's input surface, so the next keystroke goes to the pty
+   * rather than to whatever the page focused last. This is the call a host makes when the user
+   * selects a terminal in a list.
+   *
+   * The terminal is created asynchronously — the xterm modules are loaded on first connection —
+   * so a call that arrives before it exists is remembered and applied once it is ready, exactly
+   * once. The same applies to an element that is focused while detached and then reattached: the
+   * pending request is dropped on disconnect, because by then the user's intent has expired, and
+   * a fresh `focus()` after the move is what a host should issue.
+   *
+   * Only this method arms that behaviour; re-renders, buffered output and background updates
+   * never steal focus.
+   */
+  public focus(optionsArg?: FocusOptions): void {
+    const terminal = this.terminal;
+    if (terminal && this.isConnected) {
+      this.focusWhenReady = false;
+      terminal.focus();
+      return;
+    }
+    // Preventing scroll is a hint for the eventual focus, not a reason to skip it.
+    void optionsArg;
+    this.focusWhenReady = true;
+  }
+
+  /** True while an explicit `focus()` is waiting for the terminal to come up. */
+  public get focusPending(): boolean {
+    return this.focusWhenReady;
   }
 
   /** Current grid size, or undefined while no terminal is live. */
@@ -444,6 +476,11 @@ export class DeesTerminalView extends DeesElement {
     this.refit();
     this.resizeObserver = new ResizeObserver(() => this.refit());
     this.resizeObserver.observe(host);
+    // An explicit focus() that arrived before the terminal existed is honoured now, once.
+    if (this.focusWhenReady) {
+      this.focusWhenReady = false;
+      terminal.focus();
+    }
     this.readyResolve();
   }
 
@@ -478,6 +515,9 @@ export class DeesTerminalView extends DeesElement {
     // re-announce its grid and may retry a load that failed.
     this.lastReportedSize = '';
     this.setupPromise = undefined;
+    // A focus request belongs to the connection it was made in; a reattached element must not
+    // grab the caret from wherever the user moved it meanwhile.
+    this.focusWhenReady = false;
     // Buffered output deliberately survives, so a replay that arrived while the
     // element was detached still reaches the next connection.
     if (this.readyPending) {

package/ts_web/elements/00group-harness/index.ts

@@ -12,6 +12,7 @@ export * from './dees-harness-overflow-text.js';
 export * from './dees-harness-chat/index.js';
 export * from './dees-harness-composer/index.js';
 export * from './dees-harness-content-blocks/index.js';
+export * from './dees-harness-conversation-picker/index.js';
 export * from './dees-harness-message/index.js';
 export * from './dees-harness-permission-card/index.js';
 export * from './dees-harness-question-card/index.js';

package/ts_web/elements/00group-harness/interfaces.ts

@@ -401,49 +401,66 @@ export interface IHarnessResourceMeta<TState extends string = string> {
 }
 
 /**
- * A controlled zero-or-one association for one resource. The target is any
- * other list item — a session or another resource such as a terminal.
+ * The controlled set of associations for one resource. A resource can be attached to several
+ * items at once, and a target is any other list item — a session or another resource such as a
+ * terminal. An empty array is an unattached resource.
  */
 export interface IHarnessResourceAssociation {
   resourceId: string;
-  target: IHarnessSessionListItemRef;
+  targets: IHarnessSessionListItemRef[];
 }
 
 export interface IHarnessResourceEventDetail<TState extends string = string> {
   resource: IHarnessResourceMeta<TState>;
-  /** The controlled association target, or null when the resource is unattached. */
-  target: IHarnessSessionListItemRef | null;
+  /** The controlled association targets; empty when the resource is unattached. */
+  targets: IHarnessSessionListItemRef[];
 }
 
 /**
- * Association is an explicit host action, never a drop: dragging a resource
- * only moves it inside the ordered list.
+ * Attaching is an explicit choice, never an accident of reordering: a drag only attaches when it
+ * is released on the centre of a row, and the edges of that same row stay positional. Keyboard
+ * moves are always positional; keyboard attaching goes through the host's menu.
  */
-export type THarnessResourceAssociationInteractionSource = 'action' | 'keyboard';
+export type THarnessResourceAssociationInteractionSource = 'action' | 'keyboard' | 'pointer';
 
-export type THarnessResourceAssociationRequestDetail<TState extends string = string> =
+/**
+ * A validated association request. `attach` adds the first target, `attach-additional` adds
+ * another one beside existing targets, `move` replaces one specific target, and `detach` removes
+ * one. `fromTarget` always names the attachment being replaced or removed, never the whole set.
+ */
+export type THarnessResourceAssociateDetail<TState extends string = string> =
   | {
-      intent: 'attach';
+      mode: 'attach';
       resource: IHarnessResourceMeta<TState>;
       fromTarget: null;
       toTarget: IHarnessSessionListItemRef;
       source: THarnessResourceAssociationInteractionSource;
     }
   | {
-      intent: 'detach';
+      mode: 'attach-additional';
       resource: IHarnessResourceMeta<TState>;
-      fromTarget: IHarnessSessionListItemRef;
-      toTarget: null;
+      fromTarget: null;
+      toTarget: IHarnessSessionListItemRef;
       source: THarnessResourceAssociationInteractionSource;
     }
   | {
-      intent: 'reassign';
+      mode: 'move';
       resource: IHarnessResourceMeta<TState>;
       fromTarget: IHarnessSessionListItemRef;
       toTarget: IHarnessSessionListItemRef;
       source: THarnessResourceAssociationInteractionSource;
+    }
+  | {
+      mode: 'detach';
+      resource: IHarnessResourceMeta<TState>;
+      fromTarget: IHarnessSessionListItemRef;
+      toTarget: null;
+      source: THarnessResourceAssociationInteractionSource;
     };
 
+/** Explicit mode for `requestAssociation`; omitted lets the list infer it from the current set. */
+export type THarnessResourceAssociateMode = THarnessResourceAssociateDetail['mode'];
+
 export type THarnessResourceContextSource = 'pointer' | 'action' | 'keyboard';
 
 /** Detail of `harness-resource-context`; the host owns the actual menu. */
@@ -453,8 +470,16 @@ export interface IHarnessResourceContextDetail<TState extends string = string>
   clientY: number;
   source: THarnessResourceContextSource;
   originalEvent: MouseEvent | KeyboardEvent;
-  /** Routes a host menu choice through the component's validated controlled request event. */
-  requestAssociation: (toTarget: IHarnessSessionListItemRef | null) => boolean;
+  /**
+   * Routes a host menu choice through the component's validated controlled request event. With no
+   * mode, an unattached resource attaches and a singly attached one moves; a resource with several
+   * attachments is refused, because only the host knows which attachment was meant.
+   */
+  requestAssociation: (
+    toTarget: IHarnessSessionListItemRef | null,
+    mode?: THarnessResourceAssociateMode,
+    fromTarget?: IHarnessSessionListItemRef | null,
+  ) => boolean;
   /** Closes the external-menu disclosure state and restores focus to its invoking control. */
   close: () => void;
 }