zotero-kb/docs/superpowers/specs/2026-04-16-project-items-and-inline-card-detail-design.md

2026-04-16 Project Items And Inline Card Detail Design

Goal

Fix three related UI/data issues:

• collection 列表里未选中项文字太浅，保证未选中时也清晰可读
• 文献导入项目后，项目主区要立刻显示这些条目，而不是等生成卡片后才出现
• 卡片/条目详情改成在当前条目下方展开，不再集中显示在固定详情区域

Approved Direction

Use a single project-scoped item list as the main source of truth in the center panel.

Each project item carries a card_status:

• pending: 已导入项目，但还没生成卡片
• done: 已生成卡片

The center panel renders all project items, not only completed cards.

Data Model

Backend project view

ProjectService.get_project_view() should return:

• project_id
• selected_items
• items
• collections

Each items[] element should contain:

• item_key
• title
• creators
• year
• item_type
• card_status
• card fields when available:
  • summary
  • claims
  • quotable_spans

This makes imported-but-not-generated items visible immediately after import.

Status semantics

• imported via imports/item-keys and not yet generated => pending
• present in cards.json => done

UI Behavior

Collection tree readability

Unselected collection cards keep the current light theme, but their text contrast must be increased:

• title remains readable on light background
• meta line remains readable without relying on hover or selection state

Center panel item list

Replace the current “only cards” rendering with a project item list:

• pending items render as project entries with a clear “未生成卡片” state
• done items render as completed card entries
• remove the assumption that invisible means “not imported”

Inline detail expansion

Clicking “查看详情” or the item itself expands detail directly below that same entry.

Rules:

• only one item detail is expanded at a time
• clicking the same item again collapses it
• clicking another item moves the expanded detail to that item

Expanded detail content

For pending:

• title
• item key / year / type
• a short message that the item is already in the project but card generation has not happened yet

For done:

• existing summary
• claims
• quotable spans

Frontend Structure

State

Add a current expanded item key in the page script, e.g.:

• expandedProjectItemKey

Rendering

Replace the current renderCards() + fixed showCardDetail() pattern with:

• a renderer for all project items
• inline expansion markup inserted under the active item

The fixed side detail area can be removed or converted into a passive empty state, because detail no longer lives there.

Testing

Add or update tests to cover:

• project view includes imported pending items
• index template still contains the main page and valid inline script
• center panel contract no longer depends on a fixed detail-only area for current item detail
• inline project item detail hooks exist in the template script

Risks

Risk: center panel mixes two incompatible data shapes

Mitigation:

• make backend project view emit a single normalized items list

Risk: pending items have no detail data

Mitigation:

• pending inline detail shows metadata plus explicit status messaging, not empty summary sections

Risk: old fixed detail panel becomes misleading

Mitigation:

• remove dependence on it from the item interaction flow