feat(ui): the Installed and Updates screens

One screen with two modes: UI-SPEC §4 defines Updates as "the same table filtered to
outdated" and DATA-FLOW §4 has outdated rows "mirrored into the Updates tab". Both read the
same joined array, so a package cannot be outdated in one tab and not the other, and one
scan feeds both.

`useEnvStore` grows the package slice rather than gaining a sibling store, per ARCHITECTURE
§9 and the slice plan. Four things in it are load-bearing:

- **`packages` is state, not a derived selector.** Zustand v5 sits on `useSyncExternalStore`,
  so a selector returning a freshly built array hands React a new reference every call and
  either warns about `getSnapshot` caching or re-renders forever. The actions recompute it
  through the pure `joinRows`.
- **`select()` and `scan()` clear the slice.** Without it, switching environments shows the
  previous one's packages under the new one's name — cheap to get wrong, and invisible to
  any test that only ever loads one environment.
- **Two error slots.** `pkg_outdated` hits PyPI and will fail offline; one shared `error`
  would blank the installed table over a network failure that only costs badges. This is
  the whole reason the two are separate commands.
- **Per-field selectors only.** Destructuring the store re-renders a 200-row virtualized
  table on every `scan-progress` tick.

Loading is automatic on environment selection, because UI-SPEC §5's budget already spends
that click ("app auto-scans on env open"), and guarded on `loadedFor` so switching tabs
does not refetch.

*Select all* excludes pinned rows and says how many — presentation only, and commented as
such: DATA-FLOW §9.5 is enforced by `pins::filter_upgrades` when a plan is built, and S3's
preview must report the flow's `excluded_pins()` rather than this number. *Update selected*
ships disabled with a title saying why, so the 4-click budget is honest about where that
click will land once S3 exists.

The Installed screen also reports outdated packages it has no row for. The two sources can
genuinely disagree — the probe runs isolated and hides user-site packages, `pip list
--outdated` does not (SP-6) — and saying so beats a sidebar count promising rows the table
cannot show.

`App.tsx`'s ternary chain becomes a lookup. Its last branch was a hand-maintained negation
of every key above it, so adding a screen meant editing two places and forgetting the
second rendered both at once.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5 committed 2026-08-04 16:26:51 +07:00
1 parent c4974cb426
commit 96ed0bb9f4
4 files changed
+391 -18

No files matched your search

+16 -4
View File
@@ -5,10 +5,24 @@ import { NAV_KEYS } from '@/components/nav'
import { PdLegalGate } from '@/components/PdLegalGate'
import { PdSidebar } from '@/components/PdSidebar'
import { PdStatusLine } from '@/components/PdStatusLine'
import type { NavKey } from '@/components/nav'
import { PdEnvironments } from '@/screens/PdEnvironments'
import { PdPackages } from '@/screens/PdPackages'
import { PdSettings } from '@/screens/PdSettings'
import { useEnvStore, useLegalStore, useUiStore } from '@/stores'
/**
* Which screen each tab shows. A lookup rather than a ternary chain: the chain's last branch was a
* hand-maintained negation of every key above it, so adding a screen meant editing two places and
* forgetting the second showed both at once. Tabs with no entry fall through to the placeholder.
*/
const SCREENS: Partial<Record<NavKey, React.ReactNode>> = {
environments: <PdEnvironments />,
installed: <PdPackages mode="installed" />,
updates: <PdPackages mode="updates" />,
settings: <PdSettings />,
}
/**
* The app shell — UI-SPEC §3.
*
@@ -66,13 +80,11 @@ export function App() {
can observe, and nesting one inside an already-scrolling <main> gives two scrollbars
and an outer one whose content is already the virtualizer's full height. */}
<main className="flex min-w-0 flex-1 flex-col overflow-hidden">
{nav === 'environments' ? <PdEnvironments /> : null}
{nav === 'settings' ? <PdSettings /> : null}
{nav !== 'environments' && nav !== 'settings' ? (
{SCREENS[nav] ?? (
<p className="h-full overflow-auto p-6 font-mono text-text-dim">
{`▸ ${t(`nav.${nav}`)}`}
</p>
) : null}
)}
</main>
</div>
+12 -3
View File
@@ -1,10 +1,10 @@
import { useTranslation } from 'react-i18next'
import { NAV_KEYS, type NavKey } from '@/components/nav'
import { useUiStore } from '@/stores'
import { useEnvStore, useUiStore } from '@/stores'
/** Tabs whose screens land in a later milestone. Kept in place, not hidden. */
const NOT_YET: readonly NavKey[] = ['installed', 'updates', 'search', 'pins', 'health', 'security']
const NOT_YET: readonly NavKey[] = ['search', 'pins', 'health', 'security']
/**
* The sidebar — UI-SPEC §3 and §8.
@@ -17,6 +17,8 @@ export function PdSidebar() {
const { t } = useTranslation()
const nav = useUiStore((s) => s.nav)
const setNav = useUiStore((s) => s.setNav)
// UI-SPEC §3's layout sketch shows `Updates (7)`. A primitive, so this selector is stable.
const updatesCount = useEnvStore((s) => s.updatesCount)
return (
<nav aria-label={t('app.name')} className="w-48 shrink-0 border-r border-border p-2">
@@ -35,7 +37,14 @@ export function PdSidebar() {
active ? 'bg-surface-2 text-accent' : 'text-text-dim hover:bg-surface-2'
} ${NOT_YET.includes(key) ? 'opacity-60' : ''}`}
>
<span>{t(`nav.${key}`)}</span>
<span>
{t(`nav.${key}`)}
{key === 'updates' && updatesCount > 0 ? (
<span className="ml-1 font-mono text-data text-warn">
{`(${String(updatesCount)})`}
</span>
) : null}
</span>
<span aria-hidden="true" className="font-mono text-data opacity-50">
{`^${index + 1}`}
</span>
+195
View File
@@ -0,0 +1,195 @@
/**
* Installed and Updates — UI-SPEC §4.
*
* One screen with two modes, because §4 defines Updates as "the same table filtered to outdated"
* and DATA-FLOW §4 has outdated rows "mirrored into the Updates tab". Both read the same joined
* array from the store, so a package cannot be outdated in one tab and not the other, and there is
* one scan feeding both.
*
* Loading is automatic on environment selection, not behind a button: UI-SPEC §5's click budget
* spends that click already ("app auto-scans on env open").
*/
import { useCallback, useEffect } from 'react'
import { useTranslation } from 'react-i18next'
import { PdEmptyState } from '@/components/PdEmptyState'
import { PdErrorRow } from '@/components/PdErrorRow'
import { PdPackageTable } from '@/components/PdPackageTable'
import { outdatedOnly, selectableForUpdate } from '@/screens/rows'
import { useEnvStore } from '@/stores'
interface PdPackagesProps {
mode: 'installed' | 'updates'
}
export function PdPackages({ mode }: PdPackagesProps) {
const { t } = useTranslation()
// Per-field selectors throughout. Destructuring the whole store re-renders a 200-row
// virtualized table on every unrelated field change, including each `scan-progress` tick.
const selected = useEnvStore((s) => s.selected)
const rows = useEnvStore((s) => s.rows)
const packages = useEnvStore((s) => s.packages)
const orphanOutdated = useEnvStore((s) => s.orphanOutdated)
const listing = useEnvStore((s) => s.listing)
const listError = useEnvStore((s) => s.listError)
const outdatedStatus = useEnvStore((s) => s.outdatedStatus)
const outdatedError = useEnvStore((s) => s.outdatedError)
const selection = useEnvStore((s) => s.selection)
const loadedFor = useEnvStore((s) => s.loadedFor)
const loadPackages = useEnvStore((s) => s.loadPackages)
const loadOutdated = useEnvStore((s) => s.loadOutdated)
const toggle = useEnvStore((s) => s.toggle)
const selectAll = useEnvStore((s) => s.selectAll)
const clearSelection = useEnvStore((s) => s.clearSelection)
const togglePin = useEnvStore((s) => s.togglePin)
// The row's handler must return void. Wrapped here rather than in the store so `togglePin` stays
// awaitable for the tests, and stable across renders so the memoized rows are not defeated.
const pinToggle = useCallback(
(name: string) => {
void togglePin(name)
},
[togglePin],
)
useEffect(() => {
// Guarded on `loadedFor` so switching between Installed and Updates does not refetch, and so
// the two screens mounting in turn do not both start a scan.
if (selected !== null && loadedFor !== selected) {
void loadPackages()
void loadOutdated()
}
}, [selected, loadedFor, loadPackages, loadOutdated])
const row = rows.find((r) => r.interpreter === selected)
const visible = mode === 'updates' ? outdatedOnly(packages) : packages
const { selectable, pinnedExcluded } = selectableForUpdate(visible)
const title = mode === 'updates' ? t('packages.updatesTitle') : t('packages.installedTitle')
if (selected === null) {
return (
<section aria-labelledby="pkg-title" className="h-full overflow-auto p-6">
<h1 id="pkg-title" className="text-accent">
{title}
</h1>
<PdEmptyState
message={t('packages.noEnvironment')}
hint={t('packages.noEnvironmentHint')}
/>
</section>
)
}
return (
<section aria-labelledby="pkg-title" className="flex h-full min-h-0 flex-col p-6">
<div className="flex shrink-0 items-center justify-between gap-3">
<h1 id="pkg-title" className="text-accent">
{title}
</h1>
<div className="flex items-center gap-2 text-data text-text-dim">
{outdatedStatus === 'loading' ? <span>{t('packages.checkingUpdates')}</span> : null}
{selection.size > 0 ? (
<>
<span>{t('packages.selected', { count: selection.size })}</span>
<button
type="button"
onClick={clearSelection}
className="rounded-pd border border-border px-2 py-0.5"
>
{t('packages.actions.clearSelection')}
</button>
</>
) : null}
<button
type="button"
onClick={() => {
selectAll(selectable)
}}
disabled={selectable.length === 0}
className="rounded-pd border border-border px-3 py-1 disabled:opacity-40"
>
{t('actions.selectAll')}
</button>
{/* S3's entry point. Rendered disabled rather than omitted, so the 4-click budget in
UI-SPEC §5 is honest about where the click will be when the preview lands. */}
<button
type="button"
disabled
title={t('packages.updateSelectedSoon')}
className="rounded-pd border border-border px-3 py-1 disabled:opacity-40"
>
{t('packages.actions.updateSelected')}
</button>
</div>
</div>
{/* UI-SPEC §4: pinned rows are excluded from Select all, and it says so. Presentation only —
DATA-FLOW §9.5 is enforced by `pins::filter_upgrades` when a plan is built (S3). */}
{pinnedExcluded > 0 ? (
<p className="mt-1 shrink-0 text-data text-info">
{t('packages.pinnedExcluded', { count: pinnedExcluded })}
</p>
) : null}
{/* SECURITY §2 and SP-6: only when the probe really hid something, and it names the path. */}
{row?.env?.hiddenUserSite != null ? (
<p className="mt-2 shrink-0 rounded-pd border-l-2 border-info pl-2 text-data text-text-dim">
{t('env.partialListing')} {t('env.partialListingDetail', { path: row.env.hiddenUserSite })}
</p>
) : null}
{/* The two sources can disagree about what is installed — the probe runs isolated and hides
user-site packages, `pip list --outdated` does not. Saying so beats a badge count that
promises rows the table cannot show. */}
{orphanOutdated.length > 0 ? (
<p className="mt-2 shrink-0 text-data text-text-dim">
{t('packages.orphanOutdated', { count: orphanOutdated.length })}
</p>
) : null}
{listError !== null ? (
<div className="mt-4 shrink-0">
<PdErrorRow error={listError} />
</div>
) : null}
{/* Scoped to the outdated fetch: the table below stays. */}
{outdatedError !== null ? (
<div className="mt-4 shrink-0">
<p className="mb-1 text-data text-text-dim">{t('packages.outdatedFailed')}</p>
<PdErrorRow error={outdatedError} />
</div>
) : null}
{listing === 'loading' ? (
<p aria-live="polite" className="mt-4 shrink-0 text-text-dim">
{t('packages.loading')}
</p>
) : null}
{listing === 'ready' && visible.length === 0 ? (
<PdEmptyState
message={mode === 'updates' ? t('packages.updatesEmpty') : t('packages.empty')}
{...(mode === 'updates' ? {} : { hint: t('packages.emptyHint') })}
/>
) : null}
{visible.length > 0 ? (
<div className="mt-4 flex min-h-0 flex-1 flex-col">
<PdPackageTable
rows={visible}
outdatedStatus={outdatedStatus}
selection={selection}
onToggle={toggle}
onPinToggle={pinToggle}
onSelectAll={() => {
selectAll(selectable)
}}
/>
</div>
) : null}
</section>
)
}
+168 -11
View File
@@ -21,13 +21,22 @@ import {
isPdError,
legalConsentGet,
legalConsentSet,
pinAdd,
pinList,
pinRemove,
pkgList,
pkgOutdated,
settingsGet,
settingsSet,
type Dist,
type EnvRow,
type OutdatedDist,
type PdError,
type Pin,
type ScanProgress,
type Settings,
} from '@/ipc'
import { joinRows, type LoadState, type PackageRow } from '@/screens/rows'
/** Which resolver is active; shown in the status line (UI-SPEC §3). */
export type EngineId = 'pip' | 'uv'
@@ -116,37 +125,185 @@ interface EnvState {
scan: () => Promise<void>
setProgress: (progress: ScanProgress) => void
select: (interpreter: string) => void
// -- the package slice, for Installed and Updates ------------------------------------------
/** Raw responses, one field per command, kept so any one can be refreshed on its own. */
dists: Dist[]
outdated: OutdatedDist[]
pins: Pin[]
/**
* The joined rows, held as **state rather than derived in a selector**.
*
* Zustand v5 sits on `useSyncExternalStore`, so a selector returning a freshly built array
* hands React a new reference every call and either warns about `getSnapshot` caching or
* re-renders forever. Recomputed by the actions below via the pure `joinRows`.
*/
packages: PackageRow[]
/** Outdated names with no installed row — see `joinRows`. */
orphanOutdated: string[]
/** Count for the sidebar badge. A primitive, so reading it needs no memo. */
updatesCount: number
/** Which interpreter `packages` describes, so switching tabs does not refetch. */
loadedFor: string | null
listing: LoadState
listError: PdError | null
/**
* Tracked separately from `listing` because `pkg_outdated` is the networked half. A PyPI
* failure must cost badges, not the table.
*/
outdatedStatus: LoadState
outdatedError: PdError | null
selection: Set<string>
/** `pkg_list` + `pin_list` for the selected environment. */
loadPackages: () => Promise<void>
/** `pkg_outdated`, retryable on its own without re-reading the environment. */
loadOutdated: () => Promise<void>
toggle: (name: string) => void
selectAll: (names: readonly string[]) => void
clearSelection: () => void
togglePin: (name: string) => Promise<void>
}
export const useEnvStore = create<EnvState>((set) => ({
/** Everything the package slice resets to. Named so a future field cannot be forgotten. */
const NO_PACKAGES = {
dists: [] as Dist[],
outdated: [] as OutdatedDist[],
pins: [] as Pin[],
packages: [] as PackageRow[],
orphanOutdated: [] as string[],
updatesCount: 0,
loadedFor: null,
listing: 'idle' as LoadState,
listError: null,
outdatedStatus: 'idle' as LoadState,
outdatedError: null,
selection: new Set<string>(),
}
/** Recompute the joined view from the three raw responses. */
function joined(dists: Dist[], outdated: OutdatedDist[], pins: Pin[]) {
const { rows, orphanOutdated } = joinRows(dists, outdated, pins)
return {
packages: rows,
orphanOutdated,
updatesCount: rows.filter((r) => r.latest !== undefined).length,
}
}
export const useEnvStore = create<EnvState>((set, get) => ({
rows: [],
selected: null,
scanning: false,
progress: null,
error: null,
...NO_PACKAGES,
scan: async () => {
set({ scanning: true, error: null })
try {
const rows = await envScan()
set((state) => ({
rows,
scanning: false,
progress: null,
// Keep the current selection if it survived the rescan; otherwise fall back to the first
// usable row, so the status line is never empty while something is available.
selected:
set((state) => {
const selected =
// Keep the current selection if it survived the rescan; otherwise fall back to the first
// usable row, so the status line is never empty while something is available.
state.selected !== null && rows.some((r) => r.interpreter === state.selected)
? state.selected
: (rows.find((r) => r.env !== undefined)?.interpreter ?? null),
}))
: (rows.find((r) => r.env !== undefined)?.interpreter ?? null)
return {
rows,
scanning: false,
progress: null,
selected,
// A rescan can move the selection, and the package slice belongs to whichever
// environment was selected when it was read.
...(selected === state.loadedFor ? {} : NO_PACKAGES),
}
})
} catch (e) {
set({ scanning: false, progress: null, error: asPdError(e) })
}
},
setProgress: (progress) => set({ progress }),
select: (interpreter) => set({ selected: interpreter }),
// Clearing the package slice here is load-bearing: without it, switching environments shows the
// previous one's packages under the new one's name. Invisible to any test that loads one env.
select: (interpreter) =>
set((state) =>
state.selected === interpreter ? {} : { selected: interpreter, ...NO_PACKAGES },
),
loadPackages: async () => {
const { selected, rows } = get()
const row = rows.find((r) => r.interpreter === selected)
if (selected === null || row?.env === undefined) return
set({ listing: 'loading', listError: null })
try {
const [dists, pins] = await Promise.all([pkgList(row.env), pinList(row.envHash)])
set({ dists, pins, ...joined(dists, get().outdated, pins), listing: 'ready', loadedFor: selected })
} catch (e) {
set({ listing: 'error', listError: asPdError(e) })
}
},
loadOutdated: async () => {
const { selected, rows } = get()
const row = rows.find((r) => r.interpreter === selected)
if (selected === null || row?.env === undefined) return
set({ outdatedStatus: 'loading', outdatedError: null })
try {
const outdated = await pkgOutdated(row.env)
set({ outdated, ...joined(get().dists, outdated, get().pins), outdatedStatus: 'ready' })
} catch (e) {
// The installed table stays; only the badges are missing. This is the whole reason
// `pkg_list` and `pkg_outdated` are two commands.
set({ outdatedStatus: 'error', outdatedError: asPdError(e) })
}
},
toggle: (name) =>
set((state) => {
const next = new Set(state.selection)
if (!next.delete(name)) next.add(name)
return { selection: next }
}),
selectAll: (names) => set({ selection: new Set(names) }),
clearSelection: () => set({ selection: new Set<string>() }),
togglePin: async (name) => {
const { selected, rows, pins, dists, outdated } = get()
const row = rows.find((r) => r.interpreter === selected)
if (row === undefined) return
const existing = pins.find((p) => p.pkg === name)
try {
if (existing === undefined) {
// From a row, a pin is always `Exclude` — "do not sweep this up". Holding at a version
// needs a reason field, which UI-SPEC §4 puts on the Pins screen (S5).
await pinAdd(row.envHash, { pkg: name, mode: 'exclude' })
} else {
await pinRemove(row.envHash, name)
}
const fresh = await pinList(row.envHash)
set((state) => ({
pins: fresh,
...joined(dists, outdated, fresh),
// A newly pinned package must leave the selection, or Select all's count and what is
// actually ticked disagree.
selection: new Set([...state.selection].filter((n) => !fresh.some((p) => p.pkg === n))),
}))
} catch (e) {
set({ listError: asPdError(e) })
}
},
}))
interface LegalState {