[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6HY72HWPASX9F55JM3KKVM4":3,"skill-same:01M6HY72HWPASX9F55JM3KKVM4":70},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":37,"linkOnly":38,"markdownContent":39,"markdownBody":40,"frontMatter":41,"refName":42,"commitSha":43,"skillDirectory":44,"forksCount":45,"repositoryHtmlUrl":46,"repositoryHomepageUrl":6,"ownerHtmlUrl":47,"ownerBlogUrl":48,"ownerDescription":6,"updatedAt":49,"install":50,"resources":63},"01M6HY72HWPASX9F55JM3KKVM4","panel-component-colocated-helpers",null,"Enhanced dashboard panel component with robust error handling, retry logic, localStorage persistence, and co-located inline helper functions (e.g. timeAgo, statusIcon) for self-contained, import-light panel implementations.","HKUDS\u002FAgentPilot","HKUDS","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F118165258?v=4","01M6HW8VRNZP64G0P4MVJW2KKQ","✨Data Intelligence Lab@HKU✨","01M6HW8VWZVHBRHYH3T330PFWV",8029,"MIT","https:\u002F\u002Fgithub.com\u002FHKUDS\u002FAgentPilot\u002Fblob\u002Fmain\u002Fopenspace\u002Flegacy\u002Fv1\u002Fshowcase\u002Fskills\u002Fpanel-component-colocated-helpers\u002FSKILL.md",[],[19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36],"component","panel component","panel component colocated helpers","panel","functions","self","logic","import","persistence","error","helper","co","with","retry","for","inline","error handling","dashboard","2026-11-10 10:12:30",false,"---\nname: panel-component-colocated-helpers\ndescription: Enhanced dashboard panel component with robust error handling, retry logic, localStorage persistence, and co-located inline helper functions (e.g. timeAgo, statusIcon) for self-contained, import-light panel implementations.\n---\n\n# Panel Component Pattern\n\nCreate dashboard panel components using **vanilla TypeScript** (no framework, no JSX). Each panel is a class extending a `Panel` base class.\n\n## Architecture Overview\n\n### Enhanced Features\n- **Retry Logic**: Automatically retries failed data fetches with exponential backoff.\n- **State Persistence**: Saves panel state (expanded\u002Fcollapsed, size) to localStorage.\n- **Detailed Error Handling**: Provides more granular error messages and recovery options.\n- **Co-located Helpers**: Panel-specific pure utility functions live in the same file as the panel class, keeping implementations self-contained.\n\n```\nPanel (base class)\n├── element: HTMLElement (outer container, .panel)\n│   ├── header: HTMLElement (.panel-header)\n│   │   ├── headerLeft (.panel-header-left)\n│   │   │   ├── title (.panel-title)\n│   │   │   └── newBadge (.panel-new-badge) [optional]\n│   │   ├── statusBadge (.panel-data-badge) [optional]\n│   │   └── countEl (.panel-count) [optional]\n│   ├── content: HTMLElement (.panel-content)\n│   └── resizeHandle (.panel-resize-handle)\n```\n\n## Base Panel Class (Simplified for this project)\n\n```typescript\nexport class Panel {\n  \u002F\u002F ... existing code ...\n\n  private retryAttempts = 0;\n  private maxRetries = 3;\n  private retryDelay = 1000; \u002F\u002F starts at 1s, doubles each retry\n\n  protected async fetchWithRetry(url: string): Promise\u003Cany> {\n    while (this.retryAttempts \u003C this.maxRetries) {\n      try {\n        const response = await fetch(url);\n        if (!response.ok) throw new Error(`HTTP ${response.status}`);\n        return await response.json();\n      } catch (error) {\n        this.retryAttempts++;\n        if (this.retryAttempts >= this.maxRetries) {\n          throw new Error(`Failed after ${this.maxRetries} attempts: ${error.message}`);\n        }\n        await new Promise(resolve => setTimeout(resolve, this.retryDelay));\n        this.retryDelay *= 2;\n      }\n    }\n  }\n\n  public saveState(): void {\n    localStorage.setItem(`panelState_${this.panelId}`, JSON.stringify({\n      isExpanded: !this.element.classList.contains('collapsed'),\n      width: this.element.style.width,\n      height: this.element.style.height\n    }));\n  }\n\n  public loadState(): void {\n    const savedState = localStorage.getItem(`panelState_${this.panelId}`);\n    if (savedState) {\n      const { isExpanded, width, height } = JSON.parse(savedState);\n      if (!isExpanded) this.element.classList.add('collapsed');\n      if (width) this.element.style.width = width;\n      if (height) this.element.style.height = height;\n    }\n  }\n}\n```\n\nCreate `src\u002Fcomponents\u002FPanel.ts`:\n\n```typescript\nexport interface PanelOptions {\n  id: string;\n  title: string;\n  showCount?: boolean;\n  className?: string;\n}\n\nexport class Panel {\n  protected element: HTMLElement;\n  protected content: HTMLElement;\n  protected header: HTMLElement;\n  protected countEl: HTMLElement | null = null;\n  protected panelId: string;\n  private _fetching = false;\n\n  constructor(options: PanelOptions) {\n    this.panelId = options.id;\n    this.element = document.createElement('div');\n    this.element.className = `panel ${options.className || ''}`;\n    this.element.dataset.panel = options.id;\n\n    \u002F\u002F Header\n    this.header = document.createElement('div');\n    this.header.className = 'panel-header';\n\n    const headerLeft = document.createElement('div');\n    headerLeft.className = 'panel-header-left';\n\n    const title = document.createElement('span');\n    title.className = 'panel-title';\n    title.textContent = options.title;\n    headerLeft.appendChild(title);\n    this.header.appendChild(headerLeft);\n\n    \u002F\u002F Count badge (optional)\n    if (options.showCount) {\n      this.countEl = document.createElement('span');\n      this.countEl.className = 'panel-count';\n      this.countEl.textContent = '0';\n      this.header.appendChild(this.countEl);\n    }\n\n    \u002F\u002F Content area\n    this.content = document.createElement('div');\n    this.content.className = 'panel-content';\n    this.content.id = `${options.id}Content`;\n\n    this.element.appendChild(this.header);\n    this.element.appendChild(this.content);\n    this.showLoading();\n  }\n\n  public getElement(): HTMLElement { return this.element; }\n\n  public showLoading(message = 'Loading...'): void {\n    this.content.innerHTML = `\n      \u003Cdiv class=\"panel-loading\">\n        \u003Cdiv class=\"panel-loading-spinner\">\u003C\u002Fdiv>\n        \u003Cdiv class=\"panel-loading-text\">${message}\u003C\u002Fdiv>\n      \u003C\u002Fdiv>`;\n  }\n\n  public showError(message = 'Failed to load', onRetry?: () => void): void {\n    this.content.innerHTML = `\n      \u003Cdiv class=\"panel-error-state\">\n        \u003Cdiv class=\"panel-error-msg\">${message}\u003C\u002Fdiv>\n        ${onRetry ? '\u003Cbutton class=\"panel-retry-btn\" data-panel-retry>Retry\u003C\u002Fbutton>' : ''}\n      \u003C\u002Fdiv>`;\n    if (onRetry) {\n      this.content.querySelector('[data-panel-retry]')?.addEventListener('click', onRetry);\n    }\n  }\n\n  public setContent(html: string): void {\n    this.content.innerHTML = html;\n  }\n\n  public setCount(count: number): void {\n    if (this.countEl) this.countEl.textContent = count.toString();\n  }\n\n  public show(): void { this.element.classList.remove('hidden'); }\n  public hide(): void { this.element.classList.add('hidden'); }\n\n  protected setFetching(v: boolean): void { this._fetching = v; }\n  protected get isFetching(): boolean { return this._fetching; }\n\n  public destroy(): void {\n    this.element.remove();\n  }\n}\n```\n\n## Creating a Concrete Panel (Example: StockPanel)\n\n```typescript\nexport class StockPanel extends Panel {\n  \u002F\u002F ... existing code ...\n\n  private async fetchData(): Promise\u003Cvoid> {\n    if (this.isFetching) return;\n    this.setFetching(true);\n    try {\n      const quotes = await this.fetchWithRetry('\u002Fapi\u002Fstocks');\n      this.render(quotes);\n      this.setCount(quotes.length);\n      this.saveState();\n    } catch (err) {\n      this.showError(`Failed to load stock data: ${err.message}`, () => {\n        this.retryAttempts = 0;\n        this.retryDelay = 1000;\n        this.fetchData();\n      });\n    } finally {\n      this.setFetching(false);\n    }\n  }\n}\n```\n\nEach panel extends `Panel` and manages its own data fetching + rendering:\n\n```typescript\nimport { Panel } from '.\u002FPanel';\n\ninterface StockQuote {\n  symbol: string;\n  name: string;\n  price: number | null;\n  change: number | null;\n  sparkline?: number[];\n}\n\nexport class StockPanel extends Panel {\n  private refreshTimer: ReturnType\u003Ctypeof setInterval> | null = null;\n\n  constructor() {\n    super({ id: 'stocks', title: 'Stock Market', showCount: true });\n    this.fetchData();\n    this.refreshTimer = setInterval(() => this.fetchData(), 60_000);\n  }\n\n  private async fetchData(): Promise\u003Cvoid> {\n    if (this.isFetching) return;\n    this.setFetching(true);\n    try {\n      const quotes = await fetchStockQuotes(); \u002F\u002F from data-service\n      this.render(quotes);\n      this.setCount(quotes.length);\n    } catch (err) {\n      this.showError('Failed to load stock data', () => this.fetchData());\n    } finally {\n      this.setFetching(false);\n    }\n  }\n\n  private render(quotes: StockQuote[]): void {\n    const rows = quotes.map(q => `\n      \u003Cdiv class=\"stock-row\">\n        \u003Cspan class=\"stock-symbol\">${q.symbol}\u003C\u002Fspan>\n        \u003Cspan class=\"stock-name\">${q.name}\u003C\u002Fspan>\n        \u003Cspan class=\"stock-price\">${q.price != null ? '$' + q.price.toFixed(2) : '—'}\u003C\u002Fspan>\n        \u003Cspan class=\"stock-change ${(q.change ?? 0) >= 0 ? 'positive' : 'negative'}\">\n          ${q.change != null ? (q.change >= 0 ? '+' : '') + q.change.toFixed(2) + '%' : '—'}\n        \u003C\u002Fspan>\n      \u003C\u002Fdiv>\n    `).join('');\n\n    this.setContent(`\u003Cdiv class=\"stock-list\">${rows}\u003C\u002Fdiv>`);\n  }\n\n  public override destroy(): void {\n    if (this.refreshTimer) clearInterval(this.refreshTimer);\n    super.destroy();\n  }\n}\n```\n\n## Key Patterns\n\n1. **Constructor** calls `super()` with panel config, then triggers initial data fetch\n2. **fetchData()** is async, uses `isFetching` guard, shows error on failure with retry\n3. **render()** builds HTML strings and calls `this.setContent(html)`\n4. **destroy()** cleans up timers and event listeners\n5. Use `showLoading()` during initial load (auto-called in constructor)\n6. Use `showError(msg, retryFn)` on failure\n7. Sparkline SVGs use inline `\u003Csvg>` with `\u003Cpolyline>` — see sparkline utility\n8. **Co-located helpers**: Define panel-specific pure utility functions (e.g. `timeAgo`, `statusIcon`) as module-level functions in the same `.ts` file as the panel class. Do **not** place them in `src\u002Futils` unless they are reused by three or more panels.\n\n## Co-located Helper Pattern\n\nPanel-specific formatting and mapping utilities live directly above the class\ndefinition in the same file. This keeps the panel self-contained, avoids\npolluting `src\u002Futils`, and makes the file easier to read and test in isolation.\n\n### When to co-locate\n\n| Situation | Decision |\n|-----------|----------|\n| Helper used only in this panel | ✅ Co-locate in panel file |\n| Helper used in 2 panels | ✅ Co-locate in the more \"owning\" panel; import from there |\n| Helper used in 3+ panels | ❌ Move to `src\u002Futils\u002F\u003Chelper>.ts` |\n| Helper depends on DOM or Panel API | ✅ Always co-locate (private method or module function) |\n\n### timeAgo — relative timestamp helper\n\n```typescript\n\u002F\u002F co-located at the top of, e.g., src\u002Fcomponents\u002FCodeStatusPanel.ts\n\n\u002F** Returns a human-readable relative time string, e.g. \"3 minutes ago\". *\u002F\nfunction timeAgo(dateStr: string): string {\n  const diff = Date.now() - new Date(dateStr).getTime();\n  const minutes = Math.floor(diff \u002F 60_000);\n  if (minutes \u003C 1)  return 'just now';\n  if (minutes \u003C 60) return `${minutes} minute${minutes === 1 ? '' : 's'} ago`;\n  const hours = Math.floor(minutes \u002F 60);\n  if (hours \u003C 24)   return `${hours} hour${hours === 1 ? '' : 's'} ago`;\n  const days = Math.floor(hours \u002F 24);\n  return `${days} day${days === 1 ? '' : 's'} ago`;\n}\n```\n\nUsage inside `render()`:\n\n```typescript\nprivate render(runs: WorkflowRun[]): void {\n  const rows = runs.map(r => `\n    \u003Cdiv class=\"run-row\">\n      \u003Cspan class=\"run-name\">${r.name}\u003C\u002Fspan>\n      \u003Cspan class=\"run-time\">${timeAgo(r.updatedAt)}\u003C\u002Fspan>\n    \u003C\u002Fdiv>\n  `).join('');\n  this.setContent(`\u003Cdiv class=\"run-list\">${rows}\u003C\u002Fdiv>`);\n}\n```\n\n### statusIcon — enum-to-icon mapping helper\n\nMaps a string enum (e.g. CI status) to an icon character or emoji. Define\nthe map as a `const` outside the function so it is allocated once.\n\n```typescript\n\u002F\u002F co-located at the top of, e.g., src\u002Fcomponents\u002FCodeStatusPanel.ts\n\nconst STATUS_ICON: Record\u003Cstring, string> = {\n  success:     '✅',\n  failure:     '❌',\n  cancelled:   '⛔',\n  skipped:     '⏭️',\n  in_progress: '?',\n  queued:      '⏳',\n};\n\n\u002F** Returns an icon string for a workflow run conclusion\u002Fstatus value. *\u002F\nfunction statusIcon(status: string | null): string {\n  if (!status) return '❓';\n  return STATUS_ICON[status] ?? '❓';\n}\n```\n\nUsage inside `render()`:\n\n```typescript\nconst rows = runs.map(r => `\n  \u003Cdiv class=\"run-row ${r.conclusion ?? r.status}\">\n    \u003Cspan class=\"run-status\">${statusIcon(r.conclusion ?? r.status)}\u003C\u002Fspan>\n    \u003Cspan class=\"run-name\">${r.name}\u003C\u002Fspan>\n    \u003Cspan class=\"run-time\">${timeAgo(r.updatedAt)}\u003C\u002Fspan>\n  \u003C\u002Fdiv>\n`).join('');\n```\n\n### Full example: CodeStatusPanel with co-located helpers\n\n```typescript\nimport { Panel } from '.\u002FPanel';\nimport { fetchWorkflowRuns, WorkflowRun } from '..\u002Fservices\u002Fcode-status';\n\n\u002F\u002F ── Co-located helpers ────────────────────────────────────────────────────────\n\nconst STATUS_ICON: Record\u003Cstring, string> = {\n  success:     '✅',\n  failure:     '❌',\n  cancelled:   '⛔',\n  skipped:     '⏭️',\n  in_progress: '?',\n  queued:      '⏳',\n};\n\nfunction statusIcon(status: string | null): string {\n  if (!status) return '❓';\n  return STATUS_ICON[status] ?? '❓';\n}\n\nfunction timeAgo(dateStr: string): string {\n  const diff = Date.now() - new Date(dateStr).getTime();\n  const minutes = Math.floor(diff \u002F 60_000);\n  if (minutes \u003C 1)  return 'just now';\n  if (minutes \u003C 60) return `${minutes} minute${minutes === 1 ? '' : 's'} ago`;\n  const hours = Math.floor(minutes \u002F 60);\n  if (hours \u003C 24)   return `${hours} hour${hours === 1 ? '' : 's'} ago`;\n  const days = Math.floor(hours \u002F 24);\n  return `${days} day${days === 1 ? '' : 's'} ago`;\n}\n\n\u002F\u002F ── Panel class ───────────────────────────────────────────────────────────────\n\nexport class CodeStatusPanel extends Panel {\n  private refreshTimer: ReturnType\u003Ctypeof setInterval> | null = null;\n\n  constructor() {\n    super({ id: 'codeStatus', title: 'CI \u002F CD Status', showCount: true });\n    this.fetchData();\n    this.refreshTimer = setInterval(() => this.fetchData(), 60_000);\n  }\n\n  private async fetchData(): Promise\u003Cvoid> {\n    if (this.isFetching) return;\n    this.setFetching(true);\n    try {\n      const runs = await fetchWorkflowRuns();\n      this.render(runs);\n      this.setCount(runs.length);\n      this.saveState();\n    } catch (err) {\n      this.showError(`Failed to load CI status: ${(err as Error).message}`, () => this.fetchData());\n    } finally {\n      this.setFetching(false);\n    }\n  }\n\n  private render(runs: WorkflowRun[]): void {\n    if (!runs.length) {\n      this.setContent('\u003Cp class=\"panel-empty\">No recent runs.\u003C\u002Fp>');\n      return;\n    }\n    const rows = runs.map(r => `\n      \u003Cdiv class=\"run-row ${r.conclusion ?? r.status}\">\n        \u003Cspan class=\"run-icon\">${statusIcon(r.conclusion ?? r.status)}\u003C\u002Fspan>\n        \u003Cspan class=\"run-name\">${r.name}\u003C\u002Fspan>\n        \u003Cspan class=\"run-branch\">${r.headBranch}\u003C\u002Fspan>\n        \u003Cspan class=\"run-time\">${timeAgo(r.updatedAt)}\u003C\u002Fspan>\n      \u003C\u002Fdiv>\n    `).join('');\n    this.setContent(`\u003Cdiv class=\"run-list\">${rows}\u003C\u002Fdiv>`);\n  }\n\n  public override destroy(): void {\n    if (this.refreshTimer) clearInterval(this.refreshTimer);\n    super.destroy();\n  }\n}\n```\n\n### Naming conventions for co-located helpers\n\n- Use **camelCase** function names (`timeAgo`, `statusIcon`, `formatBytes`).\n- Keep them **pure** (no side effects, no DOM access) so they are trivially unit-testable.\n- Place them **above** the class definition, below imports.\n- Prefix module-level constants that back a helper with the helper name in SCREAMING_SNAKE (`STATUS_ICON` for `statusIcon`).\n- Do **not** export them unless another file already needs them — keep the API surface minimal.\n\n## Sparkline Utility\n\n```typescript\nexport function miniSparkline(data: number[] | undefined, change: number | null, w = 50, h = 16): string {\n  if (!data || data.length \u003C 2) return '';\n  const min = Math.min(...data);\n  const max = Math.max(...data);\n  const range = max - min || 1;\n  const color = change != null && change >= 0 ? 'var(--green)' : 'var(--red)';\n  const points = data.map((v, i) => {\n    const x = (i \u002F (data.length - 1)) * w;\n    const y = h - ((v - min) \u002F range) * (h - 2) - 1;\n    return `${x.toFixed(1)},${y.toFixed(1)}`;\n  }).join(' ');\n  return `\u003Csvg width=\"${w}\" height=\"${h}\" viewBox=\"0 0 ${w} ${h}\">\u003Cpolyline points=\"${points}\" fill=\"none\" stroke=\"${color}\" stroke-width=\"1.2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"\u002F>\u003C\u002Fsvg>`;\n}\n```\n","# Panel Component Pattern\n\nCreate dashboard panel components using **vanilla TypeScript** (no framework, no JSX). Each panel is a class extending a `Panel` base class.\n\n## Architecture Overview\n\n### Enhanced Features\n- **Retry Logic**: Automatically retries failed data fetches with exponential backoff.\n- **State Persistence**: Saves panel state (expanded\u002Fcollapsed, size) to localStorage.\n- **Detailed Error Handling**: Provides more granular error messages and recovery options.\n- **Co-located Helpers**: Panel-specific pure utility functions live in the same file as the panel class, keeping implementations self-contained.\n\n```\nPanel (base class)\n├── element: HTMLElement (outer container, .panel)\n│   ├── header: HTMLElement (.panel-header)\n│   │   ├── headerLeft (.panel-header-left)\n│   │   │   ├── title (.panel-title)\n│   │   │   └── newBadge (.panel-new-badge) [optional]\n│   │   ├── statusBadge (.panel-data-badge) [optional]\n│   │   └── countEl (.panel-count) [optional]\n│   ├── content: HTMLElement (.panel-content)\n│   └── resizeHandle (.panel-resize-handle)\n```\n\n## Base Panel Class (Simplified for this project)\n\n```typescript\nexport class Panel {\n  \u002F\u002F ... existing code ...\n\n  private retryAttempts = 0;\n  private maxRetries = 3;\n  private retryDelay = 1000; \u002F\u002F starts at 1s, doubles each retry\n\n  protected async fetchWithRetry(url: string): Promise\u003Cany> {\n    while (this.retryAttempts \u003C this.maxRetries) {\n      try {\n        const response = await fetch(url);\n        if (!response.ok) throw new Error(`HTTP ${response.status}`);\n        return await response.json();\n      } catch (error) {\n        this.retryAttempts++;\n        if (this.retryAttempts >= this.maxRetries) {\n          throw new Error(`Failed after ${this.maxRetries} attempts: ${error.message}`);\n        }\n        await new Promise(resolve => setTimeout(resolve, this.retryDelay));\n        this.retryDelay *= 2;\n      }\n    }\n  }\n\n  public saveState(): void {\n    localStorage.setItem(`panelState_${this.panelId}`, JSON.stringify({\n      isExpanded: !this.element.classList.contains('collapsed'),\n      width: this.element.style.width,\n      height: this.element.style.height\n    }));\n  }\n\n  public loadState(): void {\n    const savedState = localStorage.getItem(`panelState_${this.panelId}`);\n    if (savedState) {\n      const { isExpanded, width, height } = JSON.parse(savedState);\n      if (!isExpanded) this.element.classList.add('collapsed');\n      if (width) this.element.style.width = width;\n      if (height) this.element.style.height = height;\n    }\n  }\n}\n```\n\nCreate `src\u002Fcomponents\u002FPanel.ts`:\n\n```typescript\nexport interface PanelOptions {\n  id: string;\n  title: string;\n  showCount?: boolean;\n  className?: string;\n}\n\nexport class Panel {\n  protected element: HTMLElement;\n  protected content: HTMLElement;\n  protected header: HTMLElement;\n  protected countEl: HTMLElement | null = null;\n  protected panelId: string;\n  private _fetching = false;\n\n  constructor(options: PanelOptions) {\n    this.panelId = options.id;\n    this.element = document.createElement('div');\n    this.element.className = `panel ${options.className || ''}`;\n    this.element.dataset.panel = options.id;\n\n    \u002F\u002F Header\n    this.header = document.createElement('div');\n    this.header.className = 'panel-header';\n\n    const headerLeft = document.createElement('div');\n    headerLeft.className = 'panel-header-left';\n\n    const title = document.createElement('span');\n    title.className = 'panel-title';\n    title.textContent = options.title;\n    headerLeft.appendChild(title);\n    this.header.appendChild(headerLeft);\n\n    \u002F\u002F Count badge (optional)\n    if (options.showCount) {\n      this.countEl = document.createElement('span');\n      this.countEl.className = 'panel-count';\n      this.countEl.textContent = '0';\n      this.header.appendChild(this.countEl);\n    }\n\n    \u002F\u002F Content area\n    this.content = document.createElement('div');\n    this.content.className = 'panel-content';\n    this.content.id = `${options.id}Content`;\n\n    this.element.appendChild(this.header);\n    this.element.appendChild(this.content);\n    this.showLoading();\n  }\n\n  public getElement(): HTMLElement { return this.element; }\n\n  public showLoading(message = 'Loading...'): void {\n    this.content.innerHTML = `\n      \u003Cdiv class=\"panel-loading\">\n        \u003Cdiv class=\"panel-loading-spinner\">\u003C\u002Fdiv>\n        \u003Cdiv class=\"panel-loading-text\">${message}\u003C\u002Fdiv>\n      \u003C\u002Fdiv>`;\n  }\n\n  public showError(message = 'Failed to load', onRetry?: () => void): void {\n    this.content.innerHTML = `\n      \u003Cdiv class=\"panel-error-state\">\n        \u003Cdiv class=\"panel-error-msg\">${message}\u003C\u002Fdiv>\n        ${onRetry ? '\u003Cbutton class=\"panel-retry-btn\" data-panel-retry>Retry\u003C\u002Fbutton>' : ''}\n      \u003C\u002Fdiv>`;\n    if (onRetry) {\n      this.content.querySelector('[data-panel-retry]')?.addEventListener('click', onRetry);\n    }\n  }\n\n  public setContent(html: string): void {\n    this.content.innerHTML = html;\n  }\n\n  public setCount(count: number): void {\n    if (this.countEl) this.countEl.textContent = count.toString();\n  }\n\n  public show(): void { this.element.classList.remove('hidden'); }\n  public hide(): void { this.element.classList.add('hidden'); }\n\n  protected setFetching(v: boolean): void { this._fetching = v; }\n  protected get isFetching(): boolean { return this._fetching; }\n\n  public destroy(): void {\n    this.element.remove();\n  }\n}\n```\n\n## Creating a Concrete Panel (Example: StockPanel)\n\n```typescript\nexport class StockPanel extends Panel {\n  \u002F\u002F ... existing code ...\n\n  private async fetchData(): Promise\u003Cvoid> {\n    if (this.isFetching) return;\n    this.setFetching(true);\n    try {\n      const quotes = await this.fetchWithRetry('\u002Fapi\u002Fstocks');\n      this.render(quotes);\n      this.setCount(quotes.length);\n      this.saveState();\n    } catch (err) {\n      this.showError(`Failed to load stock data: ${err.message}`, () => {\n        this.retryAttempts = 0;\n        this.retryDelay = 1000;\n        this.fetchData();\n      });\n    } finally {\n      this.setFetching(false);\n    }\n  }\n}\n```\n\nEach panel extends `Panel` and manages its own data fetching + rendering:\n\n```typescript\nimport { Panel } from '.\u002FPanel';\n\ninterface StockQuote {\n  symbol: string;\n  name: string;\n  price: number | null;\n  change: number | null;\n  sparkline?: number[];\n}\n\nexport class StockPanel extends Panel {\n  private refreshTimer: ReturnType\u003Ctypeof setInterval> | null = null;\n\n  constructor() {\n    super({ id: 'stocks', title: 'Stock Market', showCount: true });\n    this.fetchData();\n    this.refreshTimer = setInterval(() => this.fetchData(), 60_000);\n  }\n\n  private async fetchData(): Promise\u003Cvoid> {\n    if (this.isFetching) return;\n    this.setFetching(true);\n    try {\n      const quotes = await fetchStockQuotes(); \u002F\u002F from data-service\n      this.render(quotes);\n      this.setCount(quotes.length);\n    } catch (err) {\n      this.showError('Failed to load stock data', () => this.fetchData());\n    } finally {\n      this.setFetching(false);\n    }\n  }\n\n  private render(quotes: StockQuote[]): void {\n    const rows = quotes.map(q => `\n      \u003Cdiv class=\"stock-row\">\n        \u003Cspan class=\"stock-symbol\">${q.symbol}\u003C\u002Fspan>\n        \u003Cspan class=\"stock-name\">${q.name}\u003C\u002Fspan>\n        \u003Cspan class=\"stock-price\">${q.price != null ? '$' + q.price.toFixed(2) : '—'}\u003C\u002Fspan>\n        \u003Cspan class=\"stock-change ${(q.change ?? 0) >= 0 ? 'positive' : 'negative'}\">\n          ${q.change != null ? (q.change >= 0 ? '+' : '') + q.change.toFixed(2) + '%' : '—'}\n        \u003C\u002Fspan>\n      \u003C\u002Fdiv>\n    `).join('');\n\n    this.setContent(`\u003Cdiv class=\"stock-list\">${rows}\u003C\u002Fdiv>`);\n  }\n\n  public override destroy(): void {\n    if (this.refreshTimer) clearInterval(this.refreshTimer);\n    super.destroy();\n  }\n}\n```\n\n## Key Patterns\n\n1. **Constructor** calls `super()` with panel config, then triggers initial data fetch\n2. **fetchData()** is async, uses `isFetching` guard, shows error on failure with retry\n3. **render()** builds HTML strings and calls `this.setContent(html)`\n4. **destroy()** cleans up timers and event listeners\n5. Use `showLoading()` during initial load (auto-called in constructor)\n6. Use `showError(msg, retryFn)` on failure\n7. Sparkline SVGs use inline `\u003Csvg>` with `\u003Cpolyline>` — see sparkline utility\n8. **Co-located helpers**: Define panel-specific pure utility functions (e.g. `timeAgo`, `statusIcon`) as module-level functions in the same `.ts` file as the panel class. Do **not** place them in `src\u002Futils` unless they are reused by three or more panels.\n\n## Co-located Helper Pattern\n\nPanel-specific formatting and mapping utilities live directly above the class\ndefinition in the same file. This keeps the panel self-contained, avoids\npolluting `src\u002Futils`, and makes the file easier to read and test in isolation.\n\n### When to co-locate\n\n| Situation | Decision |\n|-----------|----------|\n| Helper used only in this panel | ✅ Co-locate in panel file |\n| Helper used in 2 panels | ✅ Co-locate in the more \"owning\" panel; import from there |\n| Helper used in 3+ panels | ❌ Move to `src\u002Futils\u002F\u003Chelper>.ts` |\n| Helper depends on DOM or Panel API | ✅ Always co-locate (private method or module function) |\n\n### timeAgo — relative timestamp helper\n\n```typescript\n\u002F\u002F co-located at the top of, e.g., src\u002Fcomponents\u002FCodeStatusPanel.ts\n\n\u002F** Returns a human-readable relative time string, e.g. \"3 minutes ago\". *\u002F\nfunction timeAgo(dateStr: string): string {\n  const diff = Date.now() - new Date(dateStr).getTime();\n  const minutes = Math.floor(diff \u002F 60_000);\n  if (minutes \u003C 1)  return 'just now';\n  if (minutes \u003C 60) return `${minutes} minute${minutes === 1 ? '' : 's'} ago`;\n  const hours = Math.floor(minutes \u002F 60);\n  if (hours \u003C 24)   return `${hours} hour${hours === 1 ? '' : 's'} ago`;\n  const days = Math.floor(hours \u002F 24);\n  return `${days} day${days === 1 ? '' : 's'} ago`;\n}\n```\n\nUsage inside `render()`:\n\n```typescript\nprivate render(runs: WorkflowRun[]): void {\n  const rows = runs.map(r => `\n    \u003Cdiv class=\"run-row\">\n      \u003Cspan class=\"run-name\">${r.name}\u003C\u002Fspan>\n      \u003Cspan class=\"run-time\">${timeAgo(r.updatedAt)}\u003C\u002Fspan>\n    \u003C\u002Fdiv>\n  `).join('');\n  this.setContent(`\u003Cdiv class=\"run-list\">${rows}\u003C\u002Fdiv>`);\n}\n```\n\n### statusIcon — enum-to-icon mapping helper\n\nMaps a string enum (e.g. CI status) to an icon character or emoji. Define\nthe map as a `const` outside the function so it is allocated once.\n\n```typescript\n\u002F\u002F co-located at the top of, e.g., src\u002Fcomponents\u002FCodeStatusPanel.ts\n\nconst STATUS_ICON: Record\u003Cstring, string> = {\n  success:     '✅',\n  failure:     '❌',\n  cancelled:   '⛔',\n  skipped:     '⏭️',\n  in_progress: '?',\n  queued:      '⏳',\n};\n\n\u002F** Returns an icon string for a workflow run conclusion\u002Fstatus value. *\u002F\nfunction statusIcon(status: string | null): string {\n  if (!status) return '❓';\n  return STATUS_ICON[status] ?? '❓';\n}\n```\n\nUsage inside `render()`:\n\n```typescript\nconst rows = runs.map(r => `\n  \u003Cdiv class=\"run-row ${r.conclusion ?? r.status}\">\n    \u003Cspan class=\"run-status\">${statusIcon(r.conclusion ?? r.status)}\u003C\u002Fspan>\n    \u003Cspan class=\"run-name\">${r.name}\u003C\u002Fspan>\n    \u003Cspan class=\"run-time\">${timeAgo(r.updatedAt)}\u003C\u002Fspan>\n  \u003C\u002Fdiv>\n`).join('');\n```\n\n### Full example: CodeStatusPanel with co-located helpers\n\n```typescript\nimport { Panel } from '.\u002FPanel';\nimport { fetchWorkflowRuns, WorkflowRun } from '..\u002Fservices\u002Fcode-status';\n\n\u002F\u002F ── Co-located helpers ────────────────────────────────────────────────────────\n\nconst STATUS_ICON: Record\u003Cstring, string> = {\n  success:     '✅',\n  failure:     '❌',\n  cancelled:   '⛔',\n  skipped:     '⏭️',\n  in_progress: '?',\n  queued:      '⏳',\n};\n\nfunction statusIcon(status: string | null): string {\n  if (!status) return '❓';\n  return STATUS_ICON[status] ?? '❓';\n}\n\nfunction timeAgo(dateStr: string): string {\n  const diff = Date.now() - new Date(dateStr).getTime();\n  const minutes = Math.floor(diff \u002F 60_000);\n  if (minutes \u003C 1)  return 'just now';\n  if (minutes \u003C 60) return `${minutes} minute${minutes === 1 ? '' : 's'} ago`;\n  const hours = Math.floor(minutes \u002F 60);\n  if (hours \u003C 24)   return `${hours} hour${hours === 1 ? '' : 's'} ago`;\n  const days = Math.floor(hours \u002F 24);\n  return `${days} day${days === 1 ? '' : 's'} ago`;\n}\n\n\u002F\u002F ── Panel class ───────────────────────────────────────────────────────────────\n\nexport class CodeStatusPanel extends Panel {\n  private refreshTimer: ReturnType\u003Ctypeof setInterval> | null = null;\n\n  constructor() {\n    super({ id: 'codeStatus', title: 'CI \u002F CD Status', showCount: true });\n    this.fetchData();\n    this.refreshTimer = setInterval(() => this.fetchData(), 60_000);\n  }\n\n  private async fetchData(): Promise\u003Cvoid> {\n    if (this.isFetching) return;\n    this.setFetching(true);\n    try {\n      const runs = await fetchWorkflowRuns();\n      this.render(runs);\n      this.setCount(runs.length);\n      this.saveState();\n    } catch (err) {\n      this.showError(`Failed to load CI status: ${(err as Error).message}`, () => this.fetchData());\n    } finally {\n      this.setFetching(false);\n    }\n  }\n\n  private render(runs: WorkflowRun[]): void {\n    if (!runs.length) {\n      this.setContent('\u003Cp class=\"panel-empty\">No recent runs.\u003C\u002Fp>');\n      return;\n    }\n    const rows = runs.map(r => `\n      \u003Cdiv class=\"run-row ${r.conclusion ?? r.status}\">\n        \u003Cspan class=\"run-icon\">${statusIcon(r.conclusion ?? r.status)}\u003C\u002Fspan>\n        \u003Cspan class=\"run-name\">${r.name}\u003C\u002Fspan>\n        \u003Cspan class=\"run-branch\">${r.headBranch}\u003C\u002Fspan>\n        \u003Cspan class=\"run-time\">${timeAgo(r.updatedAt)}\u003C\u002Fspan>\n      \u003C\u002Fdiv>\n    `).join('');\n    this.setContent(`\u003Cdiv class=\"run-list\">${rows}\u003C\u002Fdiv>`);\n  }\n\n  public override destroy(): void {\n    if (this.refreshTimer) clearInterval(this.refreshTimer);\n    super.destroy();\n  }\n}\n```\n\n### Naming conventions for co-located helpers\n\n- Use **camelCase** function names (`timeAgo`, `statusIcon`, `formatBytes`).\n- Keep them **pure** (no side effects, no DOM access) so they are trivially unit-testable.\n- Place them **above** the class definition, below imports.\n- Prefix module-level constants that back a helper with the helper name in SCREAMING_SNAKE (`STATUS_ICON` for `statusIcon`).\n- Do **not** export them unless another file already needs them — keep the API surface minimal.\n\n## Sparkline Utility\n\n```typescript\nexport function miniSparkline(data: number[] | undefined, change: number | null, w = 50, h = 16): string {\n  if (!data || data.length \u003C 2) return '';\n  const min = Math.min(...data);\n  const max = Math.max(...data);\n  const range = max - min || 1;\n  const color = change != null && change >= 0 ? 'var(--green)' : 'var(--red)';\n  const points = data.map((v, i) => {\n    const x = (i \u002F (data.length - 1)) * w;\n    const y = h - ((v - min) \u002F range) * (h - 2) - 1;\n    return `${x.toFixed(1)},${y.toFixed(1)}`;\n  }).join(' ');\n  return `\u003Csvg width=\"${w}\" height=\"${h}\" viewBox=\"0 0 ${w} ${h}\">\u003Cpolyline points=\"${points}\" fill=\"none\" stroke=\"${color}\" stroke-width=\"1.2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"\u002F>\u003C\u002Fsvg>`;\n}\n```\n",{"name":5,"description":7},"main","6b84b0689ca0d9e7b1e4061188ff6b60758e0f8a","openspace\u002Flegacy\u002Fv1\u002Fshowcase\u002Fskills\u002Fpanel-component-colocated-helpers",944,"https:\u002F\u002Fgithub.com\u002FHKUDS\u002FAgentPilot","https:\u002F\u002Fgithub.com\u002FHKUDS","https:\u002F\u002Fsites.google.com\u002Fview\u002Fchaoh","2026-11-12 22:26:39",{"source":8,"skillName":5,"commands":51,"prompt":61,"zipAvailable":62},[52,55,58],{"tool":53,"command":54},"npx","npx skills add HKUDS\u002FAgentPilot --skill panel-component-colocated-helpers",{"tool":56,"command":57},"bunx","bunx skills add HKUDS\u002FAgentPilot --skill panel-component-colocated-helpers",{"tool":59,"command":60},"pnpm","pnpm dlx skills add HKUDS\u002FAgentPilot --skill panel-component-colocated-helpers","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FHKUDS\u002FAgentPilot\u002Fblob\u002Fmain\u002Fopenspace\u002Flegacy\u002Fv1\u002Fshowcase\u002Fskills\u002Fpanel-component-colocated-helpers\u002FSKILL.md",true,[64],{"path":65,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":68,"sourceHtmlUrl":69},".skill_id","OTHER","其他",47,"https:\u002F\u002Fgithub.com\u002FHKUDS\u002FAgentPilot\u002Fblob\u002Fmain\u002Fopenspace\u002Flegacy\u002Fv1\u002Fshowcase\u002Fskills\u002Fpanel-component-colocated-helpers\u002F.skill_id",[71,90,109,134,157,180],{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":37},"01M6HYB297NDABRERJRVG0K8R0","agentpilot","Set up AgentPilot and use its single entry to prepare missing inputs and run configured RSI experiments. Use when the user requests AgentPilot installation or work with AgentPilot.","https:\u002F\u002Fgithub.com\u002FHKUDS\u002FAgentPilot\u002Fblob\u002Fmain\u002Fplugins\u002Fagentpilot\u002Fskills\u002Fagentpilot\u002FSKILL.md",[],[73,78,79,31,80,81,82,83,84,85,86,87,88,89],"prepare","requests","missing","installation","rsi","up","use","user","work","SET","run","experiments",{"skillNo":91,"name":92,"nameZh":6,"description":93,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":94,"categories":95,"keywords":96,"publishedAt":37},"01M6HYAYWXTTE1J7DJM0MFNQ4H","remember","Review auto-memory entries and propose promotions to OPENSPACE.md, OPENSPACE.local.md, or retained auto-memory topics; detect duplicates, stale facts, conflicts, and ambiguous entries before making changes.","https:\u002F\u002Fgithub.com\u002FHKUDS\u002FAgentPilot\u002Fblob\u002Fmain\u002Fopenspace\u002Fopenspace\u002Fskills\u002Fremember\u002FSKILL.md",[],[92,97,98,99,100,101,102,103,104,105,106,107,108],"memory","review","auto","openspace","changes","facts","detect","entries","local","conflicts","stale","duplicates",{"skillNo":110,"name":111,"nameZh":6,"description":112,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":113,"categories":114,"keywords":120,"publishedAt":37},"01M6HYAVMPM4SBDV60R2B5HPV8","skill-discovery","Search reusable OpenSpace skills locally, and browse cloud packages step by step when a cloud skill may help. Reusing proven skills saves tokens, improves reliability, and extends your capabilities beyond built-in tools.","https:\u002F\u002Fgithub.com\u002FHKUDS\u002FAgentPilot\u002Fblob\u002Fmain\u002Fopenspace\u002Fopenspace\u002Fhost_skills\u002Fskill-discovery\u002FSKILL.md",[115],{"categoryNo":116,"categoryName":117,"taxonomyType":118,"taxonomyTypeDesc":119},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[121,122,123,100,124,125,126,127,128,129,130,131,132,133],"skill discovery","discovery","reusable","step by step","tokens","packages","help","cloud","reliability","capabilities","browse","search","Tools",{"skillNo":135,"name":136,"nameZh":6,"description":137,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":138,"categories":139,"keywords":141,"publishedAt":37},"01M6HYAR811B3RB0M50RBEDGN6","delegate-task","Delegate tasks to OpenSpace — a full-stack autonomous worker for coding, DevOps, web research, and desktop automation, backed by an extensive MCP tool and skill library. Skills auto-improve through use, reducing token consumption over time. A cloud community lets agents share and collectively evolve reusable skills.","https:\u002F\u002Fgithub.com\u002FHKUDS\u002FAgentPilot\u002Fblob\u002Fmain\u002Fopenspace\u002Fopenspace\u002Fhost_skills\u002Fdelegate-task\u002FSKILL.md",[140],{"categoryNo":116,"categoryName":117,"taxonomyType":118,"taxonomyTypeDesc":119},[142,143,144,100,145,146,147,148,149,123,99,84,150,151,152,33,153,154,155,156],"delegate","task","delegate task","time","improve","desktop automation","worker","community","autonomous","tool","stack","share","tasks","automation","MCP",{"skillNo":158,"name":159,"nameZh":6,"description":160,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":161,"categories":162,"keywords":163,"publishedAt":37},"01M6HYAM9FSGV6E52AYENDQXYH","write-special-chars-ts-check","Workaround for write_file failures caused by special characters (apostrophes, backticks, template literals) using a Python heredoc script, plus a reliable TypeScript type-checking step that filters output to only the newly-written files to avoid being misled by pre-existing errors.","https:\u002F\u002Fgithub.com\u002FHKUDS\u002FAgentPilot\u002Fblob\u002Fmain\u002Fopenspace\u002Flegacy\u002Fv1\u002Fshowcase\u002Fskills\u002Fwrite-special-chars-ts-check\u002FSKILL.md",[],[164,165,166,167,168,169,170,171,172,173,174,175,176,177,33,178,179],"write special chars ts check","write","check","type","files","filters","only","template","file","python","typescript","output","Existing","type-checking","errors","script",{"skillNo":181,"name":182,"nameZh":6,"description":183,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":184,"categories":185,"keywords":186,"publishedAt":37},"01M6HYAH05HGV7SVWSVR8PJRQD","write-special-chars-readback","Workaround for write_file failures caused by special characters (apostrophes, backticks, template literals) using a Python heredoc script, with mandatory post-write verification via read_file and cleanup of \u002Ftmp helper scripts.","https:\u002F\u002Fgithub.com\u002FHKUDS\u002FAgentPilot\u002Fblob\u002Fmain\u002Fopenspace\u002Flegacy\u002Fv1\u002Fshowcase\u002Fskills\u002Fwrite-special-chars-readback\u002FSKILL.md",[],[187,188,165,31,33,179,29,189,190,191,192,171,172,193,194,173],"write special chars readback","readback","post","via","scripts","read","verification","cleanup"]