@linxin666/dsh-client-ui-task-board 0.4.4 → 0.4.5

package/src/client/board/overlay.tsx

@@ -0,0 +1,189 @@
+/**
+ * Shared behavior of the board's transient surfaces (the task detail overlay
+ * and every modal that opens above it).
+ *
+ * Two concerns live here because they are one contract:
+ *
+ * - `usePresence` keeps a surface mounted through its exit leg. The board's
+ *   overlays are mounted by a boolean at the call site; the moment that
+ *   boolean flips the node would vanish, so the enter animation had no
+ *   reverse. Presence turns the boolean into `open` -> `closing` -> gone and
+ *   paints the phase on the surface, which is what the CSS transition pair
+ *   reads. Dimensions never change across the pair, so nothing around the
+ *   overlay reflows.
+ * - `useDialog` owns the keyboard and focus contract of a modal surface:
+ *   focus moves into the dialog when it opens and returns to the control that
+ *   opened it when it closes, Tab cycles inside it, and Escape asks the owner
+ *   to close.
+ *
+ * @module @linxin666/dsh-client-ui-task-board/client/board/overlay
+ */
+import { useCallback, useEffect, useRef, useState, type MouseEvent } from 'react'
+
+/**
+ * Exit duration in milliseconds. It matches `--dsh-tb-motion-close` in
+ * `board.module.css`; under `prefers-reduced-motion` the stylesheet keeps the
+ * same duration and drops only the spatial travel, so the unmount delay stays
+ * valid for both motion settings.
+ */
+export const OVERLAY_EXIT_MS = 140
+
+/** Lifecycle phase of one transient surface. */
+export type OverlayPhase = 'open' | 'closing'
+
+/** Presence of one transient surface. */
+export interface OverlayPresence {
+  /** Whether the surface should render at all (true through the exit leg). */
+  mounted: boolean
+  /** Which leg of the motion pair the surface is on. */
+  phase: OverlayPhase
+}
+
+/**
+ * Keep a surface mounted until its exit transition has run.
+ *
+ * `open=false` starts the exit leg immediately (the surface paints
+ * `data-state="closing"`) and unmounts it one exit duration later. Re-opening
+ * during the exit leg cancels the unmount, so a fast toggle never leaves a
+ * half-faded surface behind.
+ * @param open - the owner's mount request.
+ * @param exitMs - exit duration; defaults to {@link OVERLAY_EXIT_MS}.
+ * @returns the mount decision and the phase to paint.
+ */
+export function usePresence(open: boolean, exitMs: number = OVERLAY_EXIT_MS): OverlayPresence {
+  const [presence, setPresence] = useState<OverlayPresence>(
+    () => ({ mounted: open, phase: open ? 'open' : 'closing' }),
+  )
+  useEffect(() => {
+    if (open) {
+      setPresence(current => (current.mounted && current.phase === 'open' ? current : { mounted: true, phase: 'open' }))
+      return
+    }
+    setPresence(current => (current.mounted ? { mounted: true, phase: 'closing' } : current))
+    const timer = setTimeout(() => { setPresence({ mounted: false, phase: 'closing' }) }, exitMs)
+    return () => { clearTimeout(timer) }
+  }, [open, exitMs])
+  return presence
+}
+
+/** Tab-order selector of the elements a modal surface hands focus to. */
+const FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]), textarea:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])'
+
+/**
+ * Open modal surfaces in mount order. Keyboard handling belongs to the last
+ * entry only: the board nests modals (a confirm or an edit form above the task
+ * detail), and without the stack one Escape press would close both layers.
+ */
+const MODAL_STACK: symbol[] = []
+
+/** The surface that currently owns the keyboard, if any. */
+function topMostDialog(): symbol | undefined {
+  return MODAL_STACK[MODAL_STACK.length - 1]
+}
+
+/** The dialog's keyboard/focus handle. */
+export interface DialogHandle<T extends HTMLElement> {
+  /** Callback ref for the dialog element itself (it must accept focus). */
+  attach: (node: T | null) => void
+  /** Backdrop press handler: closes only on a press of the backdrop itself. */
+  onMouseDown: (event: MouseEvent<HTMLElement>) => void
+}
+
+/**
+ * Bind a modal surface's keyboard and focus contract.
+ *
+ * Focus enters the dialog on mount (its first focusable control, or the dialog
+ * itself) and returns to the control that opened it on unmount. Tab wraps
+ * inside the dialog, and Escape asks the owner to close — but only while the
+ * surface is on its enter leg, so a repeat press during the exit cannot queue
+ * a second close.
+ * @param onClose - the owner's close request.
+ * @param phase - the surface's current motion phase.
+ * @returns the ref to attach and the backdrop press handler.
+ */
+export function useDialog<T extends HTMLElement>(onClose: () => void, phase: OverlayPhase): DialogHandle<T> {
+  const nodeRef = useRef<T | null>(null)
+  const openerRef = useRef<HTMLElement | null>(null)
+  const [attached, setAttached] = useState(false)
+  const closeRef = useRef(onClose)
+  closeRef.current = onClose
+  // Identity in the document-wide stack of open surfaces (see MODAL_STACK).
+  const [token] = useState(() => Symbol('board-dialog'))
+
+  /** Callback ref: records the node and triggers the initial focus pass. */
+  const attach = useCallback((node: T | null): void => {
+    nodeRef.current = node
+    setAttached(node !== null)
+  }, [])
+
+  // Focus enters the surface on its first attach; the element that opened it
+  // is remembered and gets focus back when the surface unmounts, so a keyboard
+  // user returns to the control they came from instead of to the document.
+  //
+  // A surface that already landed focus inside itself keeps it: React's own
+  // `autoFocus` (the create form's title field) commits before this pass and
+  // names the field the user actually starts on. Otherwise focus goes to the
+  // surface itself, which announces the dialog and its accessible name; the
+  // first Tab then reaches its first control.
+  useEffect(() => {
+    if (!attached) return
+    const opener = document.activeElement
+    openerRef.current = opener instanceof HTMLElement ? opener : null
+    const node = nodeRef.current
+    if (node === null) return
+    if (opener instanceof HTMLElement && node.contains(opener)) return
+    const target = node.querySelector<HTMLElement>('[data-dsh-autofocus]')
+    ;(target ?? node).focus()
+  }, [attached])
+
+  useEffect(() => {
+    MODAL_STACK.push(token)
+    return () => {
+      const index = MODAL_STACK.indexOf(token)
+      if (index >= 0) MODAL_STACK.splice(index, 1)
+      const restore = openerRef.current
+      if (restore !== null && restore.isConnected) restore.focus()
+    }
+  }, [token])
+
+  useEffect(() => {
+    const onKeyDown = (event: KeyboardEvent): void => {
+      // Only the topmost surface answers: a modal opened from the detail view
+      // must swallow Escape and Tab itself instead of closing both layers.
+      if (topMostDialog() !== token) return
+      if (event.key === 'Escape') {
+        if (phase === 'closing') return
+        event.stopPropagation()
+        closeRef.current()
+        return
+      }
+      if (event.key !== 'Tab') return
+      const node = nodeRef.current
+      if (node === null) return
+      const focusable = Array.from(node.querySelectorAll<HTMLElement>(FOCUSABLE))
+      if (focusable.length === 0) return
+      const first = focusable[0]
+      const last = focusable[focusable.length - 1]
+      const active = document.activeElement
+      if (event.shiftKey) {
+        if (active === first || active === node) {
+          event.preventDefault()
+          last.focus()
+        }
+        return
+      }
+      if (active === last) {
+        event.preventDefault()
+        first.focus()
+      }
+    }
+    document.addEventListener('keydown', onKeyDown, true)
+    return () => { document.removeEventListener('keydown', onKeyDown, true) }
+  }, [phase, token])
+
+  const onMouseDown = useCallback((event: MouseEvent<HTMLElement>): void => {
+    if (event.target === event.currentTarget) closeRef.current()
+  }, [])
+
+  return { attach, onMouseDown }
+}

package/src/client/board/status-key.ts

@@ -1,4 +1,5 @@
 import type { TaskStatus } from '../../core/tasks.ts'
+import { verificationPhase, type ExecutionVerification, type VerificationPhase } from '../../core/verification.ts'
 import type { TaskBoardKey } from '../locales.ts'
 
 /** Task status → locale key (board column titles and the detail badge). */
@@ -9,3 +10,29 @@ export const STATUS_KEY: Record<TaskStatus, TaskBoardKey> = {
   done: 'board.status.done',
   failed: 'board.status.failed',
 }
+
+/**
+ * Acceptance phase to the label the running column shows: executing,
+ * verifying, or fixing a failed acceptance. The card keeps one running label;
+ * this decides which one.
+ */
+export const VERIFICATION_PHASE_KEY: Record<VerificationPhase, TaskBoardKey> = {
+  off: 'running.executing',
+  executing: 'running.executing',
+  verifying: 'running.verifying',
+  repairing: 'running.repairing',
+  passed: 'running.verificationPassed',
+  failed: 'running.verificationFailed',
+}
+
+/**
+ * The acceptance label for one open execution, or undefined when acceptance
+ * does not govern it (the switch was off at start, the run never became a goal
+ * run, or a teammate is covered by its Lead).
+ * @param verification - the execution's acceptance state.
+ * @returns the locale key to render, or undefined for the historical label.
+ */
+export function verificationRunningKey(verification: ExecutionVerification | undefined): TaskBoardKey | undefined {
+  if (verification === undefined || verification.applicability !== 'enforced') return undefined
+  return VERIFICATION_PHASE_KEY[verificationPhase(verification)]
+}

package/src/client/board/task-markdown.module.css

@@ -0,0 +1,137 @@
+/**
+ * Styles for task detail safe Markdown rendering.
+ * Respects dsh --dsw-* theme tokens.
+ */
+
+.markdownRoot {
+  font-size: 13px;
+  line-height: 1.55;
+  color: var(--dsw-alias-label-primary);
+  overflow-wrap: anywhere;
+}
+
+.markdownRoot > :first-child {
+  margin-top: 0;
+}
+
+.markdownRoot > :last-child {
+  margin-bottom: 0;
+}
+
+.paragraph {
+  margin: 0 0 8px;
+  line-height: 1.55;
+}
+
+.heading1,
+.heading2,
+.heading3,
+.heading4,
+.heading5,
+.heading6 {
+  margin: 12px 0 6px;
+  font-weight: 600;
+  color: var(--dsw-alias-label-primary);
+  line-height: 1.35;
+}
+
+.heading1 { font-size: 16px; }
+.heading2 { font-size: 15px; }
+.heading3 { font-size: 14px; }
+.heading4 { font-size: 13px; }
+.heading5 { font-size: 12.5px; }
+.heading6 { font-size: 12px; }
+
+.list {
+  margin: 0 0 8px;
+  padding-left: 20px;
+}
+
+.listItem {
+  margin: 2px 0;
+}
+
+.taskItem {
+  list-style-type: none;
+  margin-left: -18px;
+  display: flex;
+  align-items: baseline;
+  gap: 6px;
+}
+
+.taskCheckbox {
+  margin: 0;
+  cursor: default;
+  vertical-align: middle;
+}
+
+.codeBlock {
+  margin: 8px 0;
+  padding: 8px 10px;
+  font-size: 12px;
+  line-height: 1.45;
+  font-family: var(--dsw-font-markdown-code-block-small, monospace);
+  color: var(--dsw-alias-label-primary);
+  background: var(--dsw-alias-markdown-code-block, rgba(0, 0, 0, 0.05));
+  border: 1px solid var(--dsw-alias-border-l1, rgba(0, 0, 0, 0.1));
+  border-radius: 6px;
+  overflow-x: auto;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+
+.inlineCode {
+  padding: 1px 4px;
+  font-size: 12px;
+  font-family: var(--dsw-font-markdown-code-block-small, monospace);
+  color: var(--dsw-alias-label-primary);
+  background: var(--dsw-alias-markdown-code-block, rgba(0, 0, 0, 0.05));
+  border: 1px solid var(--dsw-alias-border-l1, rgba(0, 0, 0, 0.1));
+  border-radius: 4px;
+}
+
+.link {
+  color: var(--dsw-alias-brand-primary, #3b82f6);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.link:hover {
+  opacity: 0.85;
+}
+
+.imagePlaceholder {
+  display: inline-block;
+  padding: 2px 6px;
+  font-size: 11px;
+  color: var(--dsw-alias-label-secondary, #666);
+  background: var(--dsw-alias-bg-subtle, rgba(0, 0, 0, 0.04));
+  border: 1px dashed var(--dsw-alias-border-l1, rgba(0, 0, 0, 0.15));
+  border-radius: 4px;
+}
+
+.blockquote {
+  margin: 8px 0;
+  padding-left: 10px;
+  border-left: 3px solid var(--dsw-alias-border-l1, #ccc);
+  color: var(--dsw-alias-label-secondary, #666);
+}
+
+.table {
+  border-collapse: collapse;
+  width: 100%;
+  margin: 8px 0;
+  font-size: 12.5px;
+}
+
+.table th,
+.table td {
+  border: 1px solid var(--dsw-alias-border-l1, rgba(0, 0, 0, 0.1));
+  padding: 6px 8px;
+  text-align: left;
+}
+
+.table th {
+  background: var(--dsw-alias-bg-subtle, rgba(0, 0, 0, 0.03));
+  font-weight: 600;
+}

package/src/client/board/task-markdown.tsx

@@ -0,0 +1,106 @@
+import { Fragment, createElement, useMemo, type ReactNode } from 'react'
+import { Lexer, type Token, type Tokens } from 'marked'
+import { EMPTY_FIELD, HEADING_COLON, SUMMARY_HEADING } from '../../core/issue-form.ts'
+import css from './task-markdown.module.css'
+
+function safeHref(value: string): string | undefined {
+  try {
+    const url = new URL(value)
+    return ['http:', 'https:', 'mailto:'].includes(url.protocol) ? url.href : undefined
+  } catch { return undefined }
+}
+
+function plain(tokens: Token[], separator = ''): string {
+  return tokens.map(token => {
+    if (token.type === 'html' || token.type === 'def' || token.type === 'hr') return ''
+    if (token.type === 'list') return (token as Tokens.List).items.map(item => plain(item.tokens)).join(' ')
+    if (token.type === 'table') {
+      const table = token as Tokens.Table
+      return [table.header, ...table.rows].map(row => row.map(cell => plain(cell.tokens)).join(' ')).join(' ')
+    }
+    if ('tokens' in token && Array.isArray(token.tokens)) return plain(token.tokens)
+    return 'text' in token ? String(token.text) : ' '
+  }).join(separator)
+}
+
+/** Readable summary without changing the task source or creating DOM HTML. */
+export function markdownToPlainText(source: string): string {
+  return plain(Lexer.lex(source, { gfm: true }), ' ').replace(/\s+/g, ' ').trim()
+}
+
+
+/**
+ * Card excerpt: the plain text a reader can tell cards apart by.
+ *
+ * Issue-form bodies open with identical boilerplate (a duplicate-search
+ * checkbox, a plugin field, an issue-type field), so the plain-text prefix of
+ * every synced card read the same. The excerpt drops section headings, lists
+ * made only of checkboxes, raw HTML, rules and empty-field placeholders; when a
+ * summary-like section exists its body wins. A description that loses
+ * everything to those rules falls back to its full plain text, so no card goes
+ * blank. The stored description is never changed.
+ * @param source - the task description (Markdown).
+ */
+export function markdownExcerpt(source: string): string {
+  const blocks: string[] = []
+  const summary: string[] = []
+  let inSummary = false
+  for (const token of Lexer.lex(source, { gfm: true })) {
+    if (token.type === 'heading') {
+      inSummary = SUMMARY_HEADING.test(plain([token]).replace(HEADING_COLON, '').trim())
+      continue
+    }
+    if (token.type === 'space' || token.type === 'html' || token.type === 'hr' || token.type === 'def') continue
+    if (token.type === 'list' && (token as Tokens.List).items.every(item => item.task)) continue
+    const text = plain([token], ' ').replace(/\s+/g, ' ').trim()
+    if (text === '' || EMPTY_FIELD.test(text)) continue
+    ;(inSummary ? summary : blocks).push(text)
+  }
+  const picked = (summary.length > 0 ? summary : blocks).join(' ').trim()
+  return picked === '' ? markdownToPlainText(source) : picked
+}
+
+function renderTokens(tokens: Token[]): ReactNode {
+  return tokens.map((token, index) => {
+    const children = 'tokens' in token && Array.isArray(token.tokens) ? renderTokens(token.tokens) : 'text' in token ? String(token.text) : null
+    let node: ReactNode
+    switch (token.type) {
+      case 'space': case 'def': case 'html': node = null; break
+      case 'heading': node = createElement(`h${(token as Tokens.Heading).depth}`, { className: css[`heading${(token as Tokens.Heading).depth}`] }, children); break
+      case 'paragraph': node = <p className={css.paragraph}>{children}</p>; break
+      case 'strong': node = <strong>{children}</strong>; break
+      case 'em': node = <em>{children}</em>; break
+      case 'del': node = <del>{children}</del>; break
+      case 'codespan': node = <code className={css.inlineCode}>{token.text}</code>; break
+      case 'code': node = <pre className={css.codeBlock}><code>{token.text}</code></pre>; break
+      case 'br': node = <br />; break
+      case 'hr': node = <hr />; break
+      case 'blockquote': node = <blockquote className={css.blockquote}>{children}</blockquote>; break
+      case 'link': {
+        const href = safeHref((token as Tokens.Link).href)
+        node = href ? <a className={css.link} href={href} target="_blank" rel="noopener noreferrer">{children}</a> : children
+        break
+      }
+      case 'image': node = <span>{token.text}</span>; break
+      case 'list': {
+        const list = token as Tokens.List
+        const items = list.items.map((item, i) => <li key={i} className={css.listItem}>{item.task && <input type="checkbox" checked={item.checked === true} disabled readOnly />} {renderTokens(item.tokens)}</li>)
+        node = list.ordered ? <ol className={css.list} start={list.start || 1}>{items}</ol> : <ul className={css.list}>{items}</ul>
+        break
+      }
+      case 'table': {
+        const table = token as Tokens.Table
+        node = <div style={{ overflowX: 'auto' }}><table className={css.table}><thead><tr>{table.header.map((cell, i) => <th key={i}>{renderTokens(cell.tokens)}</th>)}</tr></thead><tbody>{table.rows.map((row, i) => <tr key={i}>{row.map((cell, j) => <td key={j}>{renderTokens(cell.tokens)}</td>)}</tr>)}</tbody></table></div>
+        break
+      }
+      default: node = children
+    }
+    return <Fragment key={index}>{node}</Fragment>
+  })
+}
+
+/** Markdown rendered as React nodes: raw HTML and automatic image loads are disabled. */
+export function TaskMarkdown({ source }: { source: string }) {
+  const content = useMemo(() => renderTokens(Lexer.lex(source, { gfm: true })), [source])
+  return <div className={css.markdownRoot}>{content}</div>
+}

package/src/client/board-card-seat.ts

@@ -0,0 +1,102 @@
+/**
+ * Board-owned variant of the family plugin-card seat that can declare child
+ * slots on the registration.
+ *
+ * The shared `installPluginCard` helper owns seat selection but cannot forward
+ * a `children` declaration, and the task board's settings card declares the
+ * `task-board.settings.section` seat a provider renders into. This wrapper
+ * reuses the shared seat decision (`familyGroupLoaded` and the two seat keys)
+ * and adds the declaration; it should collapse back into the shared helper once
+ * that helper accepts children.
+ *
+ * @module dsh-task-board/client/board-card-seat
+ */
+import {
+  FAMILY_PLUGIN_CARD_SEAT,
+  OFFICIAL_PLUGIN_CARD_SEAT,
+  familyGroupLoaded,
+  type PluginCardContext,
+} from './plugin-card-seat.ts'
+
+/** One board card contribution, with the child seats it declares. */
+export interface BoardCardSeat {
+  bundle: string
+  id: string
+  order?: number
+  label?: () => string
+  locale: string
+  /** Child slots this entry declares and renders. */
+  children: Record<string, unknown>
+  inject?: () => object
+  component: unknown
+}
+
+function warnRefusedSeat(seat: string, error: unknown): void {
+  try {
+    console.warn(`[dsh-web] plugin card registration into "${seat}" was refused; the card will not render`, error)
+  } catch {
+    // Best-effort console write; a failed warning must not break the plugin.
+  }
+}
+
+/**
+ * Contribute the board's settings card to the seat this host renders, declaring
+ * the child slots it owns. Mirrors the shared helper's reconcile discipline: the
+ * entry moves when the family group appears, and is never in two seats at once.
+ * @param ctx - client context (its slot registry decides the seat).
+ * @param seat - the card contribution and its children declaration.
+ */
+export function installBoardCard(ctx: PluginCardContext, seat: BoardCardSeat): void {
+  const slots = ctx.slots
+  const component = seat.component as never
+  const inject = seat.inject as never
+
+  let dispose: (() => void) | undefined
+  let current: string | undefined
+  let reconciling = false
+
+  const reconcile = (): void => {
+    if (reconciling) return
+    const target = familyGroupLoaded(ctx) ? FAMILY_PLUGIN_CARD_SEAT : OFFICIAL_PLUGIN_CARD_SEAT
+    if (current === target) return
+    reconciling = true
+    const previous = dispose
+    dispose = undefined
+    current = undefined
+    previous?.()
+    try {
+      dispose = slots.register((target === FAMILY_PLUGIN_CARD_SEAT
+        ? {
+          name: FAMILY_PLUGIN_CARD_SEAT,
+          id: seat.id,
+          ...(seat.order === undefined ? {} : { order: seat.order }),
+          ...(seat.label === undefined ? {} : { label: seat.label }),
+          locale: seat.locale,
+          children: seat.children,
+          ...(seat.inject === undefined ? {} : { inject }),
+        }
+        : {
+          name: OFFICIAL_PLUGIN_CARD_SEAT,
+          key: seat.bundle,
+          locale: seat.locale,
+          children: seat.children,
+          ...(seat.inject === undefined ? {} : { inject }),
+        }) as never, component) as () => void
+      current = target
+    } catch (error) {
+      warnRefusedSeat(target, error)
+    } finally {
+      reconciling = false
+    }
+  }
+
+  if (typeof ctx.on === 'function') {
+    try {
+      ctx.on('slots/changed', () => { reconcile() })
+    } catch {
+      // An event seat that refuses the subscription leaves the initial
+      // decision in place; the card still renders in the seat chosen below.
+    }
+  }
+  reconcile()
+}

package/src/client/board-settings.module.css

@@ -0,0 +1,66 @@
+/**
+ * Local styles of the task-board settings card.
+ *
+ * The card's chrome belongs to the shared family slice
+ * (`settings-card.module.css`, generated); this file owns only the nested
+ * disclosure list and the acceptance block's quiet notes, on theme tokens
+ * instead of inline literals.
+ */
+
+.note {
+  margin: 4px 0;
+  font-size: 12px;
+  color: var(--dsw-alias-label-secondary);
+}
+
+.error {
+  margin: 4px 0;
+  font-size: 12px;
+  color: var(--dsw-alias-state-error-primary);
+}
+
+.resolvedList {
+  margin: 4px 0 8px;
+  padding-left: 16px;
+  font-size: 12px;
+  color: var(--dsw-alias-label-secondary);
+}
+
+/* Live power facts plus the battery caveat, below the topic cards: quiet
+   small print that follows the disclosures instead of competing with them.
+   No rule of its own — the last topic card already closes with its border. */
+.power {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  margin-top: 14px;
+}
+
+/* Both the live power line and the battery caveat: secondary ink at the small
+   size the 12-13px roles use, so neither competes with the topic cards. */
+.powerLine {
+  margin: 0;
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--dsw-alias-label-secondary);
+}
+
+.powerError {
+  margin: 0;
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--dsw-alias-state-error-primary);
+}
+
+/* The nested disclosure cards of this card: the board and its runtime
+   behavior, goal acceptance, and the sections a provider extension
+   contributes. The gap keeps the stacked card
+   borders apart; an empty list draws nothing. */
+.nestedCards {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}