@design.estate/dees-catalog 12.3.0 → 12.5.0

package/ts_web/elements/00group-input/dees-input-reference/dees-input-reference.ts

@@ -0,0 +1,221 @@
+import { DeesElement, customElement, property, state, html, css, cssManager } from '@design.estate/dees-element';
+import type { Editor } from '@tiptap/core';
+import { DeesServiceLibLoader } from '../../../services/DeesServiceLibLoader.js';
+import { themeDefaultStyles } from '../../00theme.js';
+import { DeesInputDropdownPopup } from '../dees-input-dropdown/dees-input-dropdown-popup.js';
+import type { IInputReference, TReferenceContent, TReferenceSearch } from './interfaces.js';
+import { referenceContent, referenceDocument } from './document.js';
+import { demoFunc } from './dees-input-reference.demo.js';
+
+declare global { interface HTMLElementTagNameMap { 'dees-input-reference': DeesInputReference; } }
+
+@customElement('dees-input-reference')
+export class DeesInputReference extends DeesElement {
+  public static demo = demoFunc;
+  public static demoGroups = ['Input', 'Kanban'];
+  @property({ attribute: false }) accessor value: TReferenceContent = [];
+  @property({ attribute: false }) accessor searchReferences: TReferenceSearch | undefined;
+  @property({ type: String }) accessor trigger = '#_';
+  @property({ type: String }) accessor label = 'Message';
+  @property({ type: String }) accessor placeholder = 'Write a comment…';
+  @property({ type: String }) accessor searchLabel = 'Search tickets';
+  /** Changing documents resets editor history, so undo cannot cross conversation boundaries. */
+  @property({ type: String }) accessor documentKey = '';
+  @property({ type: Boolean }) accessor disabled = false;
+  @state() private accessor loadError = '';
+  private editor?: Editor;
+  private initializing?: Promise<void>;
+  private connection = 0;
+  private popup?: DeesInputDropdownPopup;
+  private popupOpening?: Promise<void>;
+  private referenceRange?: { from: number; to: number };
+  private serializedValue = '';
+
+  public static styles = [themeDefaultStyles, cssManager.defaultStyles, css`
+    :host { display: block; min-width: 0; color: var(--dees-color-text-primary); font-family: var(--dees-font-family); }
+    .editor { border: 1px solid var(--dees-color-border-default); border-radius: var(--dees-radius-lg); background: var(--dees-color-bg-primary); }
+    .editor:focus-within { outline: 2px solid var(--dees-color-focus-ring); outline-offset: 1px; }
+    .ProseMirror { padding: 12px; min-height: 84px; max-height: 260px; overflow: auto; outline: none; white-space: pre-wrap; overflow-wrap: anywhere; font-size: var(--dees-font-body-size); line-height: 1.6; }
+    .ProseMirror p { margin: 0; }
+    .ProseMirror p + p { margin-top: 0; }
+    .ProseMirror:has(> p:only-child > br:only-child)::before { content: attr(data-placeholder); float: left; color: var(--dees-color-text-muted); pointer-events: none; height: 0; }
+    .ProseMirror [data-reference-id] { display: inline; padding: 1px 5px; border-radius: var(--dees-radius-sm); color: var(--dees-color-link); background: var(--dees-color-badge-default-bg); cursor: pointer; font-weight: 500; }
+    .ProseMirror [data-reference-id]:focus-visible, .ProseMirror .ProseMirror-selectednode { outline: 2px solid var(--dees-color-focus-ring); }
+    .ProseMirror[contenteditable=false] { opacity: .65; }
+    .error { color: var(--dees-color-text-error); font-size: var(--dees-font-footnote-size); }
+  `];
+
+  public render() {
+    return html`<div class="editor"></div>${this.loadError ? html`<p class="error" role="alert">${this.loadError}</p>` : ''}`;
+  }
+
+  public async connectedCallback(): Promise<void> {
+    const connection = super.connectedCallback();
+    this.connection++;
+    void this.initialize();
+    await connection;
+  }
+
+  /** Resolves after the lazy editor is mounted; also useful when focusing after opening a modal. */
+  public async ready(): Promise<void> {
+    await this.initialize();
+    if (!this.editor) throw new Error(this.loadError || 'Connect the reference editor before calling ready().');
+  }
+
+  private initialize(): Promise<void> {
+    if (this.editor) return Promise.resolve();
+    if (this.initializing) return this.initializing;
+    const connection = this.connection;
+    const operation = (async () => {
+      await this.updateComplete;
+      const { Editor, Node, StarterKit } = await DeesServiceLibLoader.getInstance().loadTiptap();
+      if (!this.isConnected || connection !== this.connection) return;
+      const referenceNode = Node.create({
+        name: 'catalogReference', group: 'inline', inline: true, atom: true, selectable: true,
+        addAttributes: () => ({
+          id: { default: '', parseHTML: element => element.getAttribute('data-reference-id') },
+          label: { default: '', parseHTML: element => element.textContent },
+        }),
+        parseHTML: () => [{ tag: 'span[data-reference-id]' }],
+        renderHTML: ({ node }) => ['span', { 'data-reference-id': String(node.attrs.id), contenteditable: 'false', role: 'link', tabindex: '0' }, String(node.attrs.label)],
+        renderText: ({ node }) => String(node.attrs.label),
+      });
+      this.editor = new Editor({
+        element: this.shadowRoot!.querySelector<HTMLElement>('.editor')!,
+        injectCSS: false,
+        editable: !this.disabled,
+        extensions: [StarterKit.configure({ blockquote: false, bold: false, bulletList: false, code: false, codeBlock: false, heading: false, horizontalRule: false, italic: false, listItem: false, orderedList: false, strike: false }), referenceNode],
+        content: referenceDocument(this.value),
+        editorProps: {
+          attributes: { role: 'textbox', 'aria-multiline': 'true', 'aria-label': this.label, 'data-placeholder': this.placeholder },
+          handleClickOn: (_view, _position, node, _nodePosition, event, direct) => {
+            if (!direct || node.type.name !== 'catalogReference') return false;
+            event.preventDefault(); this.openReference({ id: String(node.attrs.id), label: String(node.attrs.label) }); return true;
+          },
+          handleDOMEvents: {
+            keydown: (_view, event) => {
+              const target = event.target as HTMLElement;
+              if (event.key === 'Enter' && target.dataset.referenceId) {
+                event.preventDefault(); this.openReference({ id: target.dataset.referenceId, label: target.textContent ?? '' }); return true;
+              }
+              if ((event.ctrlKey || event.metaKey) && event.key === 'Enter' && !event.isComposing && !this.disabled) {
+                event.preventDefault(); this.dispatchEvent(new CustomEvent('reference-submit', { bubbles: true, composed: true })); return true;
+              }
+              return false;
+            },
+            compositionend: () => { queueMicrotask(() => this.detectTrigger()); return false; },
+          },
+        },
+        onUpdate: ({ editor, transaction }) => {
+          this.value = referenceContent(editor.getJSON());
+          this.serializedValue = JSON.stringify(this.value);
+          this.dispatchEvent(new CustomEvent('reference-input', { detail: { value: this.value }, bubbles: true, composed: true }));
+          if (!transaction.getMeta('preventReferenceTrigger')) this.detectTrigger();
+        },
+      });
+      this.serializedValue = JSON.stringify(this.value);
+      this.loadError = '';
+    })().catch(error => { this.loadError = error instanceof Error ? error.message : 'Could not load the editor.'; })
+      .finally(() => { if (this.initializing === operation) this.initializing = undefined; });
+    this.initializing = operation;
+    return operation;
+  }
+
+  public updated(changed: Map<string, unknown>): void {
+    if (changed.has('documentKey') && changed.get('documentKey') !== undefined && this.editor) {
+      this.connection++;
+      void this.closePicker(false);
+      this.editor.destroy(); this.editor = undefined; this.initializing = undefined;
+      void this.initialize();
+    }
+    if (changed.has('disabled')) {
+      this.editor?.setEditable(!this.disabled, false);
+      if (this.disabled) void this.closePicker(false);
+    }
+    if (changed.has('value') && this.editor && JSON.stringify(this.value) !== this.serializedValue) {
+      void this.closePicker(false);
+      this.editor.commands.setContent(referenceDocument(this.value), false);
+      this.serializedValue = JSON.stringify(this.value);
+    }
+    if (changed.has('label') || changed.has('placeholder')) this.editor?.setOptions({ editorProps: {
+      ...this.editor.options.editorProps,
+      attributes: { role: 'textbox', 'aria-multiline': 'true', 'aria-label': this.label, 'data-placeholder': this.placeholder },
+    } });
+  }
+
+  public focus(options?: FocusOptions): void { this.editor?.view.dom.focus(options); }
+
+  private detectTrigger(): void {
+    const editor = this.editor;
+    if (!editor || this.disabled || this.popup || !this.searchReferences || !this.trigger || editor.view.composing || !editor.isFocused) return;
+    const { from, to, $from } = editor.state.selection;
+    if (from !== to || $from.parentOffset < this.trigger.length) return;
+    if ($from.parent.textBetween($from.parentOffset - this.trigger.length, $from.parentOffset, '', '\ufffc') !== this.trigger) return;
+    this.referenceRange = { from: from - this.trigger.length, to };
+    void this.openPicker();
+  }
+
+  private positionPicker(): void {
+    if (!this.editor || !this.popup || !this.referenceRange) return;
+    const coords = this.editor.view.coordsAtPos(this.referenceRange.to);
+    this.popup.triggerRect = new DOMRect(coords.left, coords.top, 340, coords.bottom - coords.top);
+    this.popup.opensToTop = window.innerHeight - coords.bottom < 300 && coords.top > window.innerHeight - coords.bottom;
+  }
+
+  private async openPicker(): Promise<void> {
+    const popup = this.popup = new DeesInputDropdownPopup();
+    popup.ownerComponent = this;
+    popup.searchLabel = this.searchLabel;
+    popup.searchOptions = async (query, signal) => (await this.searchReferences!(query, signal))
+      .map(reference => ({ key: reference.id, option: reference.label, payload: reference }));
+    this.positionPicker();
+    popup.addEventListener('reposition-request', () => this.positionPicker());
+    popup.addEventListener('close-request', () => { void this.closePicker(true); });
+    popup.addEventListener('keydown', (event: KeyboardEvent) => {
+      if (event.key === 'Tab') { event.preventDefault(); void this.closePicker(true); }
+    });
+    popup.addEventListener('option-selected', (event: Event) => {
+      const reference = (event as CustomEvent<{ payload: IInputReference }>).detail.payload;
+      const range = this.referenceRange;
+      if (range && this.editor && !this.disabled) {
+        this.editor.chain().setMeta('preventReferenceTrigger', true).insertContentAt(range, [
+          { type: 'catalogReference', attrs: reference }, { type: 'text', text: ' ' },
+        ]).run();
+      }
+      void this.closePicker(true);
+    });
+    this.popupOpening = popup.show();
+    try {
+      await this.popupOpening;
+      if (this.popup === popup && this.isConnected && !this.disabled) await popup.focusSearchInput();
+    } catch (error) {
+      this.loadError = error instanceof Error ? error.message : 'Could not open search.';
+      void this.closePicker(false);
+    }
+  }
+
+  private async closePicker(restoreFocus: boolean): Promise<void> {
+    const popup = this.popup;
+    const editor = this.editor;
+    const opening = this.popupOpening;
+    this.popup = undefined;
+    this.referenceRange = undefined;
+    if (!popup) return;
+    await opening?.catch(() => undefined);
+    await popup.hide();
+    if (restoreFocus && this.isConnected && !this.disabled && this.editor === editor) editor?.commands.focus();
+  }
+
+  private openReference(reference: IInputReference): void {
+    this.dispatchEvent(new CustomEvent('reference-open', { detail: reference, bubbles: true, composed: true }));
+  }
+
+  public async disconnectedCallback(): Promise<void> {
+    this.connection++;
+    void this.closePicker(false);
+    this.editor?.destroy();
+    this.editor = undefined;
+    this.initializing = undefined;
+    await super.disconnectedCallback();
+  }
+}

package/ts_web/elements/00group-input/dees-input-reference/document.ts

@@ -0,0 +1,38 @@
+import type { JSONContent } from '@tiptap/core';
+import type { TReferenceContent } from './interfaces.js';
+
+/** The public value is editor-independent JSON: plain text (including newlines) and references. */
+export const referenceDocument = (value: TReferenceContent): JSONContent => {
+  const paragraphs: JSONContent[] = [{ type: 'paragraph', content: [] }];
+  for (const part of value) {
+    if (part.type === 'reference') {
+      paragraphs.at(-1)!.content!.push({ type: 'catalogReference', attrs: { id: part.id, label: part.label } });
+    } else {
+      const lines = part.text.split('\n');
+      lines.forEach((text, index) => {
+        if (index) paragraphs.push({ type: 'paragraph', content: [] });
+        if (text) paragraphs.at(-1)!.content!.push({ type: 'text', text });
+      });
+    }
+  }
+  return { type: 'doc', content: paragraphs };
+};
+
+export const referenceContent = (document: JSONContent): TReferenceContent => {
+  const parts: TReferenceContent = [];
+  const appendText = (text: string) => {
+    if (!text) return;
+    const last = parts.at(-1);
+    if (last?.type === 'text') last.text += text;
+    else parts.push({ type: 'text', text });
+  };
+  for (const [index, paragraph] of (document.content ?? []).entries()) {
+    if (index) appendText('\n');
+    for (const node of paragraph.content ?? []) {
+      if (node.type === 'catalogReference') parts.push({ type: 'reference', id: String(node.attrs!.id), label: String(node.attrs!.label) });
+      else if (node.type === 'hardBreak') appendText('\n');
+      else appendText(node.text ?? '');
+    }
+  }
+  return parts;
+};

package/ts_web/elements/00group-input/dees-input-reference/index.ts

@@ -0,0 +1,2 @@
+export * from './interfaces.js';
+export * from './dees-input-reference.js';

package/ts_web/elements/00group-input/dees-input-reference/interfaces.ts

@@ -0,0 +1,8 @@
+/** Stable reference identity; label is a human-readable snapshot, never the lookup key. */
+export interface IInputReference { id: string; label: string; }
+export type TReferencePart = { type: 'text'; text: string } | { type: 'reference'; id: string; label: string };
+export type TReferenceContent = TReferencePart[];
+export type TReferenceSearch = (query: string, signal: AbortSignal) => Promise<IInputReference[]>;
+
+export const referenceText = (content: TReferenceContent): string =>
+  content.map(part => part.type === 'text' ? part.text : part.label).join('');

package/ts_web/elements/00group-input/dees-input-wysiwyg/dees-input-wysiwyg.ts

@@ -85,7 +85,17 @@ export class DeesInputWysiwyg extends DeesInputBase<string> {
   public blockOperations: WysiwygBlockOperations;
   private inputHandler: WysiwygInputHandler;
   private keyboardHandler: WysiwygKeyboardHandler;
-  private dragDropHandler: WysiwygDragDropHandler;
+  /**
+   * Block drag and drop, public alongside `blockOperations` because the drag *interaction* has
+   * no other seam: `dragState`, the drop indicator and the global drag-over listener all live in
+   * this handler, and a native HTML5 drag sequence cannot be synthesised from script, so a host
+   * or a test that exercises dragging has to drive `handleDragStart` / `handleDragEnd` itself.
+   * Reordering a block programmatically needs none of that: `blockOperations.moveBlock(blockId,
+   * targetIndex)` is the public path for that, on the public `blocks` accessor. The remaining
+   * handlers stay private because everything they own is reachable through ordinary input and
+   * keyboard events.
+   */
+  public dragDropHandler: WysiwygDragDropHandler;
   private history: WysiwygHistory;
 
   public static styles = [

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

@@ -19,3 +19,4 @@ export * from './dees-input-toggle/index.js';
 export * from './dees-input-typelist/index.js';
 export * from './dees-input-wysiwyg.js';
 export * from './profilepicture/dees-input-profilepicture.js';
+export * from './dees-input-reference/index.js';

package/ts_web/elements/00group-kanban/dees-kanban/dees-kanban.demo.ts

@@ -0,0 +1,9 @@
+import { html } from '@design.estate/dees-element';
+import { demoApp } from '../../../demos/templates.js';
+import { createKanbanDemo, kanbanDemoColumns, kanbanDemoPeople } from '../kanban.demodata.js';
+
+export const demoFunc = () => {
+  const demo = createKanbanDemo();
+  return demoApp(html`<dees-kanban heading="Product workspace" .tickets=${demo.tickets} .columns=${kanbanDemoColumns}
+    .people=${kanbanDemoPeople} .provider=${demo.provider}></dees-kanban>`);
+};

package/ts_web/elements/00group-kanban/dees-kanban/dees-kanban.ts

@@ -0,0 +1,315 @@
+import { DeesElement, customElement, property, state, html, css } from '@design.estate/dees-element';
+import type { IKanbanColumn, IKanbanComment, IKanbanCreate, IKanbanMove, IKanbanPerson, IKanbanProvider, IKanbanTicket, IKanbanTicketDraft } from '../interfaces.js';
+import type { TReferenceContent, TReferenceSearch } from '../../00group-input/dees-input-reference/interfaces.js';
+import type { DeesInputText } from '../../00group-input/dees-input-text/dees-input-text.js';
+import { DeesModal } from '../../00group-overlay/dees-modal/dees-modal.js';
+import { DeesContextmenu } from '../../00group-overlay/dees-contextmenu/dees-contextmenu.js';
+import { DeesKanbanTicketDetail } from '../dees-kanban-ticket-detail/dees-kanban-ticket-detail.js';
+import { kanbanStyles } from '../kanban.styles.js';
+import { kanbanError, kanbanEvent, sortKanbanTickets, ticketLabel } from '../kanban.helpers.js';
+import { demoFunc } from './dees-kanban.demo.js';
+import '../dees-kanban-column/dees-kanban-column.js';
+
+declare global { interface HTMLElementTagNameMap { 'dees-kanban': DeesKanban; } }
+
+const interactionEvents = ['kanban-ticket-open', 'kanban-ticket-move', 'kanban-ticket-create', 'kanban-move-menu',
+  'kanban-ticket-save', 'kanban-ticket-draft', 'kanban-comment-draft', 'kanban-comment-added', 'kanban-comments-refresh',
+  'kanban-detail-back', 'kanban-drag-start', 'kanban-drag-end'] as const;
+
+interface IKanbanInteractionMap {
+  'kanban-ticket-open': { ticketId: string };
+  'kanban-ticket-move': IKanbanMove;
+  'kanban-ticket-create': Omit<IKanbanCreate, 'title'>;
+  'kanban-move-menu': { ticketId: string; anchor: HTMLElement };
+  'kanban-ticket-save': { ticketId: string; draft: IKanbanTicketDraft };
+  'kanban-ticket-draft': { ticketId: string; draft?: IKanbanTicketDraft };
+  'kanban-comment-draft': { ticketId: string; body: TReferenceContent };
+  'kanban-comment-added': { comment: IKanbanComment; submittedBody: TReferenceContent };
+  'kanban-comments-refresh': { ticketId: string };
+  'kanban-detail-back': Record<string, never>;
+  'kanban-drag-start': { ticketId: string };
+  'kanban-drag-end': Record<string, never>;
+}
+type TKanbanInteraction = { [K in keyof IKanbanInteractionMap]: { type: K; detail: IKanbanInteractionMap[K] } }[keyof IKanbanInteractionMap];
+
+@customElement('dees-kanban')
+export class DeesKanban extends DeesElement {
+  public static demo = demoFunc;
+  public static demoGroups = ['Kanban'];
+  @property({ type: String }) accessor heading = 'Board';
+  @property({ attribute: false }) accessor tickets: IKanbanTicket[] = [];
+  @property({ attribute: false }) accessor columns: IKanbanColumn[] = [];
+  @property({ attribute: false }) accessor people: IKanbanPerson[] = [];
+  @property({ attribute: false }) accessor provider: IKanbanProvider = {};
+  @property({ type: Boolean }) accessor loading = false;
+  @property({ type: String }) accessor error = '';
+  @state() private accessor query = '';
+  @state() private accessor epicId = '';
+  @state() private accessor operationError = '';
+  @state() private accessor pendingTicketId = '';
+  @state() private accessor draggingTicketId = '';
+  @state() private accessor openingTicket = false;
+  private modal?: DeesModal;
+  private modalOpening?: Promise<DeesModal>;
+  private detail?: DeesKanbanTicketDetail;
+  private selectedId = '';
+  private history: string[] = [];
+  private openAbort?: AbortController;
+  private commentsAbort?: AbortController;
+  private commentCache = new Map<string, IKanbanComment[]>();
+  private commentRevisions = new Map<string, number>();
+  private commentDrafts = new Map<string, TReferenceContent>();
+  private ticketDrafts = new Map<string, IKanbanTicketDraft>();
+  private resolvedTickets = new Map<string, IKanbanTicket>();
+
+  public static styles = [...kanbanStyles, css`
+    :host { padding: 24px; background: var(--dees-color-bg-canvas); min-height: 100%; }
+    .heading { display: flex; gap: 12px; align-items: center; flex-wrap: wrap; margin-bottom: 20px; }
+    h2 { font-size: var(--dees-font-title1-size); font-weight: 650; letter-spacing: -.02em; }
+    .filters { display: flex; align-items: end; gap: 16px; flex-wrap: wrap; margin-bottom: 24px; }
+    .filters dees-input-text { flex: 1; min-width: 200px; max-width: 360px; }
+    .filters dees-input-dropdown { min-width: 200px; max-width: 320px; flex: 1; }
+    .columns { display: flex; gap: 16px; overflow-x: auto; padding: 3px 3px 16px; align-items: stretch; }
+    @media (max-width: 600px) { :host { padding: 16px; } .filters { gap: 10px; } .columns { scroll-snap-type: x proximity; } dees-kanban-column { scroll-snap-align: start; flex-basis: 85vw; } }
+  `];
+
+  public async connectedCallback(): Promise<void> {
+    const connection = super.connectedCallback();
+    for (const name of interactionEvents) this.addEventListener(name, this.handleInteraction);
+    await connection;
+  }
+  public updated(): void { this.syncDetail(); }
+  public render() {
+    const epics = sortKanbanTickets(this.tickets.filter(ticket => ticket.kind === 'epic'));
+    const query = this.query.trim().toLocaleLowerCase();
+    const tasks = this.tickets.filter(ticket => ticket.kind === 'task' && (!this.epicId || ticket.parentId === this.epicId) &&
+      (!query || [ticket.key, ticket.title, ticket.assignee?.name, ...ticket.labels ?? [],
+        ...this.tickets.filter(child => child.parentId === ticket.id).map(child => `${child.key} ${child.title}`)].join(' ').toLocaleLowerCase().includes(query)));
+    const epic = epics.find(ticket => ticket.id === this.epicId);
+    return html`<header class="heading"><h2>${this.heading}</h2><span class="caption">${tasks.length} tasks · ${epics.length} epics</span><span class="spacer"></span>
+      ${this.provider.createTicket ? html`<dees-button type="ghost" size="sm" text="New epic" .disabled=${!this.columns.length}
+        @clicked=${() => { void this.createTicket({ kind: 'epic', columnId: this.columns[0].id }); }}></dees-button>
+        <dees-button type="accent" size="sm" icon="lucide:Plus" text="New task" .disabled=${!this.columns.length}
+          @clicked=${() => { void this.createTicket({ kind: 'task', columnId: this.columns[0].id, parentId: this.epicId || undefined }); }}></dees-button>` : ''}</header>
+      <div class="filters"><dees-input-text label="Search tickets" placeholder="Title, ticket number, assignee…" .value=${this.query}
+        @input=${(event: Event) => { this.query = String((event.currentTarget as DeesInputText).value ?? ''); }}></dees-input-text>
+        <dees-input-dropdown label="Epic" .value=${{ key: this.epicId, option: epic?.title ?? 'All epics' }}
+          .options=${[{ key: '', option: 'All epics' }, ...epics.map(ticket => ({ key: ticket.id, option: ticket.title }))]}
+          @selectedOption=${(event: CustomEvent<{ key: string }>) => { this.epicId = event.detail.key; }}></dees-input-dropdown>
+        ${epic ? html`<dees-button type="ghost" size="sm" text="Open epic" @clicked=${() => { void this.openTicket(epic.id); }}></dees-button>` : ''}
+      </div>
+      ${this.loading || this.openingTicket ? html`<p class="caption" role="status">${this.loading ? 'Loading board…' : 'Opening ticket…'}</p>` : ''}
+      ${this.error || this.operationError ? html`<p class="error" role="alert">${this.error || this.operationError}</p>` : ''}
+      ${!this.columns.length ? html`<p class="empty">No columns configured.</p>` : html`<div class="columns" aria-label=${this.heading}>
+        ${this.columns.map(column => html`<dees-kanban-column .column=${column} .columns=${this.columns}
+          .tickets=${tasks.filter(ticket => ticket.columnId === column.id)} .allTickets=${this.tickets}
+          .movable=${Boolean(this.provider.moveTicket) && !this.pendingTicketId} .canCreate=${Boolean(this.provider.createTicket)}
+          .pendingTicketId=${this.pendingTicketId} .draggingTicketId=${this.draggingTicketId}></dees-kanban-column>`)}</div>`}`;
+  }
+
+  private findTicket(id: string): IKanbanTicket | undefined { return this.tickets.find(ticket => ticket.id === id) ?? this.resolvedTickets.get(id); }
+  private searchTickets: TReferenceSearch = async (query, signal) => {
+    const tickets = this.provider.searchTickets ? await this.provider.searchTickets(query, signal) :
+      this.tickets.filter(ticket => ticketLabel(ticket).toLocaleLowerCase().includes(query.toLocaleLowerCase()));
+    if (!signal.aborted) for (const ticket of tickets) this.resolvedTickets.set(ticket.id, ticket);
+    return tickets.map(ticket => ({ id: ticket.id, label: ticketLabel(ticket) }));
+  };
+
+  /** Open a task, epic, subtask or remotely resolved linked ticket in the board's detail modal. */
+  public async openTicket(id: string, addHistory = true): Promise<void> {
+    this.openAbort?.abort();
+    const controller = this.openAbort = new AbortController();
+    this.openingTicket = true;
+    this.operationError = '';
+    try {
+      const ticket = this.provider.getTicket ? await this.provider.getTicket(id, controller.signal) : this.findTicket(id);
+      if (controller.signal.aborted || !this.isConnected) return;
+      if (!ticket || ticket.id !== id) throw new Error('This ticket is unavailable or you do not have access.');
+      this.resolvedTickets.set(ticket.id, ticket);
+      this.tickets = this.tickets.map(item => item.id === ticket.id ? ticket : item);
+      if (addHistory && this.selectedId && this.selectedId !== id && this.modal) this.history.push(this.selectedId);
+      this.selectedId = id;
+      if (!this.detail) {
+        this.detail = new DeesKanbanTicketDetail();
+        for (const name of interactionEvents) this.detail.addEventListener(name, this.handleInteraction);
+      }
+      this.detail.ticket = ticket;
+      this.detail.error = '';
+      this.syncDetail();
+      if (!this.modal && !this.modalOpening) {
+        this.modalOpening = DeesModal.createAndShow({ heading: ticket.key, width: 1000, maxWidth: 1040,
+          mobileFullscreen: true, content: html`${this.detail}`, menuOptions: [] });
+        const modal = await this.modalOpening;
+        this.modalOpening = undefined;
+        if (!this.isConnected) { await modal.destroy(); return; }
+        this.modal = modal;
+        modal.addEventListener('modal-close', () => {
+          if (this.modal !== modal) return;
+          this.modal = undefined; this.selectedId = ''; this.history = [];
+          this.commentsAbort?.abort(); this.openAbort?.abort();
+        }, { once: true });
+      } else if (this.modalOpening) await this.modalOpening;
+      this.syncDetail();
+      if (controller.signal.aborted) return;
+      kanbanEvent(this, 'kanban-ticket-opened', { ticketId: id });
+      await this.refreshComments(id);
+    } catch (error) {
+      if (!controller.signal.aborted) this.reportError(error);
+    } finally { if (this.openAbort === controller) this.openingTicket = false; }
+  }
+
+  private syncDetail(): void {
+    if (!this.detail || !this.selectedId) return;
+    const ticket = this.resolvedTickets.get(this.selectedId) ?? this.findTicket(this.selectedId);
+    if (!ticket) return;
+    // Host-fed updates take precedence for records on this board.
+    this.detail.ticket = this.tickets.find(item => item.id === this.selectedId) ?? ticket;
+    this.detail.tickets = [...this.tickets, ...[...this.resolvedTickets.values()].filter(item => !this.tickets.some(known => known.id === item.id))];
+    this.detail.columns = this.columns; this.detail.people = this.people;
+    this.detail.provider = this.provider; this.detail.searchTickets = this.searchTickets;
+    this.detail.comments = this.commentCache.get(this.selectedId) ?? [];
+    this.detail.commentDraft = this.commentDrafts.get(this.selectedId) ?? [];
+    this.detail.draft = this.ticketDrafts.get(this.selectedId);
+    this.detail.canGoBack = this.history.length > 0;
+    this.detail.saving = this.pendingTicketId === this.selectedId;
+    if (this.modal) this.modal.heading = this.detail.ticket.key;
+  }
+
+  /** Replace a ticket's discussion with an authoritative snapshot (for realtime updates). */
+  public setComments(ticketId: string, comments: IKanbanComment[]): void {
+    if (comments.some(comment => comment.ticketId !== ticketId)) throw new Error('Comment ticket IDs must match.');
+    this.commentCache.set(ticketId, [...comments]);
+    this.commentRevisions.set(ticketId, (this.commentRevisions.get(ticketId) ?? 0) + 1);
+    this.syncDetail();
+  }
+
+  public async refreshComments(ticketId = this.selectedId): Promise<void> {
+    this.commentsAbort?.abort();
+    const controller = this.commentsAbort = new AbortController();
+    if (!ticketId || !this.provider.loadComments) { if (this.detail) { this.detail.loadingComments = false; this.detail.commentsError = ''; } return; }
+    const revision = this.commentRevisions.get(ticketId) ?? 0;
+    const existingIds = new Set((this.commentCache.get(ticketId) ?? []).map(comment => comment.id));
+    if (this.detail && ticketId === this.selectedId) { this.detail.loadingComments = true; this.detail.commentsError = ''; }
+    try {
+      const comments = await this.provider.loadComments(ticketId, controller.signal);
+      if (!controller.signal.aborted && (this.commentRevisions.get(ticketId) ?? 0) === revision) {
+        const postedWhileLoading = (this.commentCache.get(ticketId) ?? []).filter(comment => !existingIds.has(comment.id) && !comments.some(item => item.id === comment.id));
+        this.setComments(ticketId, [...comments, ...postedWhileLoading]);
+      }
+    } catch (error) {
+      if (!controller.signal.aborted && this.detail && ticketId === this.selectedId) this.detail.commentsError = kanbanError(error);
+    } finally {
+      if (!controller.signal.aborted && this.detail && ticketId === this.selectedId) this.detail.loadingComments = false;
+    }
+  }
+
+  private mergeTickets(tickets: IKanbanTicket[], addToBoard = false): void {
+    for (const ticket of tickets) this.resolvedTickets.set(ticket.id, ticket);
+    this.tickets = this.tickets.map(ticket => tickets.find(item => item.id === ticket.id) ?? ticket);
+    if (addToBoard) this.tickets = [...this.tickets, ...tickets.filter(ticket => !this.tickets.some(item => item.id === ticket.id))];
+    this.syncDetail();
+    kanbanEvent(this, 'kanban-change', { tickets });
+  }
+
+  /** Provider commits the move and supplies the new ordering. Hierarchy is never part of a move request. */
+  public async moveTicket(input: IKanbanMove): Promise<void> {
+    const ticket = this.findTicket(input.ticketId);
+    if (!ticket || !this.provider.moveTicket || ticket.permissions?.move === false || this.pendingTicketId || input.beforeTicketId === ticket.id) return;
+    if (!this.columns.some(column => column.id === input.columnId)) { this.reportError(new Error('Unknown destination column.')); return; }
+    const before = input.beforeTicketId ? this.findTicket(input.beforeTicketId) : undefined;
+    if (input.beforeTicketId && (!before || before.columnId !== input.columnId || before.kind !== ticket.kind)) { this.reportError(new Error('Invalid insertion target.')); return; }
+    this.pendingTicketId = ticket.id; this.operationError = ''; this.draggingTicketId = '';
+    try {
+      const changed = await this.provider.moveTicket(input);
+      if (!changed.some(item => item.id === ticket.id)) throw new Error('The move provider did not return the moved ticket.');
+      this.mergeTickets(changed);
+    } catch (error) { this.reportError(error); }
+    finally { this.pendingTicketId = ''; this.syncDetail(); }
+  }
+
+  private async saveTicket(ticketId: string, draft: IKanbanTicketDraft): Promise<void> {
+    const ticket = this.findTicket(ticketId);
+    if (!ticket || !this.provider.updateTicket || ticket.permissions?.edit === false || this.pendingTicketId || !draft.title.trim()) return;
+    const parent = draft.parentId ? this.findTicket(draft.parentId) : undefined;
+    if ((ticket.kind === 'subtask' && parent?.kind !== 'task') || (ticket.kind === 'task' && draft.parentId && parent?.kind !== 'epic')) {
+      this.reportError(new Error('Choose a valid parent ticket.')); return;
+    }
+    const assignee = this.people.find(person => person.id === draft.assigneeId) ?? (ticket.assignee?.id === draft.assigneeId ? ticket.assignee : undefined);
+    if (draft.assigneeId && !assignee) { this.reportError(new Error('Choose an available assignee.')); return; }
+    this.pendingTicketId = ticketId; this.operationError = ''; if (this.detail) this.detail.error = '';
+    try {
+      const saved = await this.provider.updateTicket({ ticketId, changes: { title: draft.title.trim(), description: draft.description,
+        priority: draft.priority, assignee: assignee ?? null, parentId: ticket.kind === 'epic' ? null : draft.parentId || null } });
+      if (saved.id !== ticketId) throw new Error('The update provider returned a different ticket.');
+      this.ticketDrafts.delete(ticketId);
+      this.mergeTickets([saved]);
+      if (this.selectedId === ticketId) this.detail?.finishEditing();
+    } catch (error) { this.reportError(error); }
+    finally { this.pendingTicketId = ''; this.syncDetail(); }
+  }
+
+  private async createTicket(input: Omit<IKanbanCreate, 'title'>): Promise<void> {
+    if (!this.provider.createTicket || !this.columns.some(column => column.id === input.columnId)) return;
+    const parent = input.parentId ? this.findTicket(input.parentId) : undefined;
+    if (parent?.permissions?.createChild === false) return;
+    if ((input.kind === 'subtask' && parent?.kind !== 'task') || (input.kind === 'task' && parent && parent.kind !== 'epic')) return;
+    const parentId = input.parentId ?? (input.kind === 'task' ? this.epicId || undefined : undefined);
+    await DeesModal.prompt({ heading: `New ${input.kind}`, label: 'Title', confirmLabel: 'Create', onConfirm: async title => {
+      const ticket = await this.provider.createTicket!({ ...input, parentId, title });
+      this.mergeTickets([ticket], true);
+    } });
+  }
+
+  private async openMoveMenu(ticketId: string, anchor: HTMLElement): Promise<void> {
+    const ticket = this.findTicket(ticketId);
+    if (!ticket || !this.provider.moveTicket || ticket.permissions?.move === false || this.pendingTicketId) return;
+    const siblings = sortKanbanTickets(this.tickets.filter(item => item.columnId === ticket.columnId && item.kind === ticket.kind));
+    const index = siblings.findIndex(item => item.id === ticket.id);
+    const rect = anchor.getBoundingClientRect();
+    await DeesContextmenu.openContextMenuWithOptions(new MouseEvent('click', { clientX: rect.right, clientY: rect.bottom }), [
+      { name: 'Move up', disabled: index <= 0, action: async () => { if (index > 0) await this.moveTicket({ ticketId, columnId: ticket.columnId, beforeTicketId: siblings[index - 1].id }); } },
+      { name: 'Move down', disabled: index < 0 || index >= siblings.length - 1, action: async () => { if (index >= 0 && index < siblings.length - 1) await this.moveTicket({ ticketId, columnId: ticket.columnId, beforeTicketId: siblings[index + 2]?.id }); } },
+      { divider: true }, ...this.columns.filter(column => column.id !== ticket.columnId).map(column => ({ name: `Move to ${column.title}`, action: async () => { await this.moveTicket({ ticketId, columnId: column.id }); } })),
+    ], { ownerElement: anchor });
+  }
+
+  private reportError(error: unknown): void {
+    this.operationError = kanbanError(error);
+    if (this.detail && this.modal) this.detail.error = this.operationError;
+    kanbanEvent(this, 'kanban-error', { error, message: this.operationError });
+  }
+
+  private handleInteraction = (event: Event): void => {
+    event.stopPropagation();
+    const { type, detail } = event as unknown as TKanbanInteraction;
+    switch (type) {
+      case 'kanban-ticket-open': void this.openTicket(detail.ticketId); break;
+      case 'kanban-ticket-move': void this.moveTicket(detail); break;
+      case 'kanban-ticket-create': void this.createTicket(detail).catch(error => this.reportError(error)); break;
+      case 'kanban-move-menu': void this.openMoveMenu(detail.ticketId, detail.anchor).catch(error => this.reportError(error)); break;
+      case 'kanban-ticket-save': void this.saveTicket(detail.ticketId, detail.draft); break;
+      case 'kanban-ticket-draft':
+        if (detail.draft) this.ticketDrafts.set(detail.ticketId, detail.draft); else this.ticketDrafts.delete(detail.ticketId);
+        this.syncDetail(); break;
+      case 'kanban-comment-draft': this.commentDrafts.set(detail.ticketId, detail.body); break;
+      case 'kanban-comment-added': {
+        const { comment, submittedBody } = detail;
+        const comments = this.commentCache.get(comment.ticketId) ?? [];
+        this.commentCache.set(comment.ticketId, [...comments.filter(item => item.id !== comment.id), comment]);
+        if (JSON.stringify(this.commentDrafts.get(comment.ticketId) ?? []) === JSON.stringify(submittedBody)) this.commentDrafts.delete(comment.ticketId);
+        this.syncDetail(); kanbanEvent(this, 'kanban-comment-saved', { comment }); break;
+      }
+      case 'kanban-comments-refresh': void this.refreshComments(detail.ticketId); break;
+      case 'kanban-detail-back': { const previous = this.history.pop(); if (previous) void this.openTicket(previous, false); break; }
+      case 'kanban-drag-start': this.draggingTicketId = detail.ticketId; break;
+      case 'kanban-drag-end': this.draggingTicketId = ''; break;
+    }
+  };
+
+  public async disconnectedCallback(): Promise<void> {
+    for (const name of interactionEvents) this.removeEventListener(name, this.handleInteraction);
+    this.openAbort?.abort(); this.commentsAbort?.abort();
+    void this.modal?.destroy();
+    await super.disconnectedCallback();
+  }
+}