feat(ui): the Pins screen, Exclude only

UI-SPEC §4 specifies it in one sentence — "Pin list with reason field" — so the
shape comes from what a pin has to answer six months later: which package, why,
and how to stop. There is no `PdPins*` in §6's inventory, so it is built from the
primitives, and the 🔒 chip is `PdPinChip` shared with the table rather than
re-derived.

**No Hold control.** The screen renders a `Hold` pin faithfully if one exists,
but does not offer to create one: `pins::hold_requirements` is dead code in the
core and `engine::plan_requirements` restates every package at its *installed*
version, so a hold at any other version is a promise nothing keeps. The CLI
cannot create one either, so both heads agree rather than one of them lying.

The reason commits on blur — a `pin_add` upsert per commit, and one round trip
per character is a lot of SQLite for a text field — and commits `null`, never
`''`: `reason` is optional and `exactOptionalPropertyTypes` is on, so an empty
string would round-trip as a reason that exists and says nothing. `updatePin`
carries the existing mode through, because changing what a pin *is* must not be a
side effect of typing in its reason box. Both writes go through one `writePin`,
so which environment, the re-read, the selection prune and where the error lands
are decided once.

With no environment selected it says so rather than "no pins": pins are keyed by
`envHash`, so that is not an empty list, it is no list.

`useEnvPackages` extracts the mount effect `PdPackages` and `PdSearch` had each
written. It loads **both** halves, always — `loadedFor` is one flag covering two
calls, so a screen that fetched only `pkg_list` would set it and leave every row
`unknown` for that environment permanently.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5 committed 2026-08-09 21:46:25 +07:00
1 parent ef5b489861
commit 980bd5d750
8 files changed
+238 -36

No files matched your search

+2
View File
@@ -10,6 +10,7 @@ import { PdUninstallDialog } from '@/components/PdUninstallDialog'
import type { NavKey } from '@/components/nav'
import { PdEnvironments } from '@/screens/PdEnvironments'
import { PdPackages } from '@/screens/PdPackages'
import { PdPins } from '@/screens/PdPins'
import { PdPlanPanel } from '@/screens/PdPlanPanel'
import { PdSearch } from '@/screens/PdSearch'
import { PdSettings } from '@/screens/PdSettings'
@@ -26,6 +27,7 @@ const SCREENS: Partial<Record<NavKey, React.ReactNode>> = {
installed: <PdPackages mode="installed" />,
updates: <PdPackages mode="updates" />,
search: <PdSearch />,
pins: <PdPins />,
settings: <PdSettings />,
}
+1 -1
View File
@@ -4,7 +4,7 @@ import { NAV_KEYS, type NavKey } from '@/components/nav'
import { useEnvStore, useUiStore } from '@/stores'
/** Tabs whose screens land in a later milestone. Kept in place, not hidden. */
const NOT_YET: readonly NavKey[] = ['pins', 'health', 'security']
const NOT_YET: readonly NavKey[] = ['health', 'security']
/**
* The sidebar — UI-SPEC §3 and §8.
+6
View File
@@ -155,6 +155,12 @@
"checkFinding": "{{pkg}} requires {{requirement}}",
"done": "Back to packages"
},
"pins": {
"empty": "no pins in this environment",
"emptyHint": "Pin a package from the Installed table to keep bulk updates away from it.",
"reasonPlaceholder": "Why is this pinned?",
"reasonFor": "Reason for pinning {{pkg}}"
},
"uninstall": {
"title": "Remove packages",
"titleBreaks": "This removal breaks other packages",
+6
View File
@@ -148,6 +148,12 @@
"checkFinding": "{{pkg}} yêu cầu {{requirement}}",
"done": "Quay lại danh sách gói"
},
"pins": {
"empty": "môi trường này chưa có gói nào được ghim",
"emptyHint": "Ghim một gói từ bảng Đã cài để các lần cập nhật hàng loạt bỏ qua nó.",
"reasonPlaceholder": "Vì sao ghim gói này?",
"reasonFor": "Lý do ghim {{pkg}}"
},
"uninstall": {
"title": "Gỡ gói",
"titleBreaks": "Thao tác gỡ này làm hỏng gói khác",
+3 -12
View File
@@ -10,13 +10,14 @@
* spends that click already ("app auto-scans on env open").
*/
import { useCallback, useEffect } from 'react'
import { useCallback } 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 { useEnvPackages } from '@/screens/useEnvPackages'
import { useEnvStore, usePlanStore } from '@/stores'
interface PdPackagesProps {
@@ -37,9 +38,6 @@ export function PdPackages({ mode }: PdPackagesProps) {
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)
@@ -73,14 +71,7 @@ export function PdPackages({ mode }: PdPackagesProps) {
[env, startUninstall],
)
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])
useEnvPackages()
const visible = mode === 'updates' ? outdatedOnly(packages) : packages
const { selectable, pinnedExcluded } = selectableForUpdate(visible)
+132
View File
@@ -0,0 +1,132 @@
/**
* Pins — UI-SPEC §4: "Pin list with reason field".
*
* The whole specification is that sentence, so the shape comes from what a pin has to answer six
* months later: *which* package, *why*, and how to stop. There is no `PdPins*` in §6's component
* inventory, so it is built from the primitives; the 🔒 chip is `PdPinChip`, shared with the table
* rather than re-derived, or the two would eventually disagree about which mode is which.
*
* **Exclude only.** The screen shows a `Hold` pin faithfully if one exists — the CLI could write
* one in principle — but does not offer to create one, because `pins::hold_requirements` is dead
* code in the core and `engine::plan_requirements` restates each package at its *installed*
* version. A hold at any other version is a promise nothing keeps, and offering it here would be
* the interface lying about what the engine does. §4's auto-suggest section is P1 and absent.
*
* The reason commits on blur rather than on every keystroke: it is a `pin_add` upsert per commit,
* and one round trip per character typed is a lot of SQLite for a text field.
*/
import { useState } from 'react'
import { useTranslation } from 'react-i18next'
import { PdEmptyState } from '@/components/PdEmptyState'
import { PdErrorRow } from '@/components/PdErrorRow'
import { PdPinChip } from '@/components/PdPinChip'
import { useEnvPackages } from '@/screens/useEnvPackages'
import { useEnvStore } from '@/stores'
export function PdPins() {
const { t } = useTranslation()
const selected = useEnvStore((s) => s.selected)
const pins = useEnvStore((s) => s.pins)
const listError = useEnvStore((s) => s.listError)
const togglePin = useEnvStore((s) => s.togglePin)
const updatePin = useEnvStore((s) => s.updatePin)
useEnvPackages()
return (
<section aria-labelledby="pins-title" className="h-full overflow-auto p-6">
<h1 id="pins-title" className="text-accent">
{t('nav.pins')}
</h1>
{listError !== null ? (
<div className="mt-4">
<PdErrorRow error={listError} />
</div>
) : null}
{selected === null ? (
// Pins are stored per `envHash`, so with no environment there is not an empty list — there
// is no list. Saying "no pins" here would read as "this environment has none".
<PdEmptyState
message={t('packages.noEnvironment')}
hint={t('packages.noEnvironmentHint')}
/>
) : pins.length === 0 ? (
<PdEmptyState message={t('pins.empty')} hint={t('pins.emptyHint')} />
) : (
<ul className="mt-4 space-y-2">
{pins.map((pin) => (
<li
key={pin.pkg}
data-pin={pin.pkg}
className="flex items-center gap-3 rounded-pd border border-border bg-surface px-3 py-2"
>
<code className="w-56 shrink-0 truncate font-mono text-data">{pin.pkg}</code>
<PdPinChip mode={pin.mode} />
<ReasonField
// Keyed on the committed reason, which is React's own way to reset state when a
// prop changes: a write elsewhere — unpinning another row re-reads the whole
// list — must not strand this box showing what it held before. The key is stable
// while typing, because typing only moves local draft state.
key={`${pin.pkg}:${pin.reason ?? ''}`}
pkg={pin.pkg}
reason={pin.reason ?? ''}
onCommit={(next) => {
void updatePin(pin.pkg, next)
}}
/>
<button
type="button"
onClick={() => {
void togglePin(pin.pkg)
}}
data-action="unpin"
className="shrink-0 rounded-pd border border-border px-2 py-0.5 text-data text-text-dim"
>
{t('packages.actions.unpin')}
</button>
</li>
))}
</ul>
)}
</section>
)
}
/** The reason box for one pin: local while typing, committed on blur. */
function ReasonField({
pkg,
reason,
onCommit,
}: {
pkg: string
reason: string
onCommit: (reason: string | null) => void
}) {
const { t } = useTranslation()
const [draft, setDraft] = useState(reason)
return (
<input
type="text"
value={draft}
aria-label={t('pins.reasonFor', { pkg })}
placeholder={t('pins.reasonPlaceholder')}
onChange={(e) => {
setDraft(e.target.value)
}}
onBlur={() => {
const next = draft.trim()
if (next === reason) return
// `null`, never `''`: `exactOptionalPropertyTypes` is on and `reason` is an optional
// field, so an empty string would round-trip through SQLite as a reason that is there and
// says nothing.
onCommit(next === '' ? null : next)
}}
className="min-w-0 flex-1 rounded-pd border border-border bg-bg px-2 py-0.5 text-data"
/>
)
}
+33
View File
@@ -0,0 +1,33 @@
/**
* Load the selected environment's packages on mount, once per environment.
*
* Three screens need the installed set for different reasons — Installed and Updates render it,
* Search needs it for DATA-FLOW §4's `INSTALLED`/`UPDATE` chips, and Pins joins pins against it —
* and each of them can be the first screen a user opens. The effect was written twice already and
* a third copy is how they start disagreeing.
*
* **Both fetches, always.** `loadedFor` is one flag covering two calls, so a screen that loads only
* `pkg_list` sets it and the outdated fetch never happens for that environment: every row would
* stay `unknown`, permanently. That is the whole reason this is one hook rather than a convention.
*
* The `loadedFor` guard is also what stops React's double-invoked development effects fetching
* twice, and what makes switching between Installed and Updates free.
*/
import { useEffect } from 'react'
import { useEnvStore } from '@/stores'
export function useEnvPackages(): void {
const selected = useEnvStore((s) => s.selected)
const loadedFor = useEnvStore((s) => s.loadedFor)
const loadPackages = useEnvStore((s) => s.loadPackages)
const loadOutdated = useEnvStore((s) => s.loadOutdated)
useEffect(() => {
if (selected !== null && loadedFor !== selected) {
void loadPackages()
void loadOutdated()
}
}, [selected, loadedFor, loadPackages, loadOutdated])
}
+55 -23
View File
@@ -167,6 +167,8 @@ interface EnvState {
selectAll: (names: readonly string[]) => void
clearSelection: () => void
togglePin: (name: string) => Promise<void>
/** Set or clear a pin's reason, leaving its mode alone. `null` clears it. */
updatePin: (name: string, reason: string | null) => Promise<void>
}
/** Everything the package slice resets to. Named so a future field cannot be forgotten. */
@@ -291,33 +293,63 @@ export const useEnvStore = create<EnvState>((set, get) => ({
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 { pins } = get()
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) })
}
await writePin(set, get, (envHash) =>
existing === undefined
? // From a row, a pin is always `Exclude` — "do not sweep this up". Holding at a version
// is not offered anywhere: `pins::hold_requirements` is dead code in the core and
// `plan_requirements` restates the *installed* version, so a hold at another version
// is a promise nothing keeps. The CLI cannot create one either, so both heads agree.
pinAdd(envHash, { pkg: name, mode: 'exclude' })
: pinRemove(envHash, name).then(() => undefined),
)
},
updatePin: async (name, reason) => {
const { pins } = get()
const existing = pins.find((p) => p.pkg === name)
if (existing === undefined) return
// `pin_add` is documented "add or replace", so an edit is a write of the whole pin — with the
// mode carried over untouched. Changing what a pin *is* must never be a side effect of typing
// in its reason box.
await writePin(set, get, (envHash) =>
pinAdd(envHash, { pkg: name, mode: existing.mode, ...(reason === null ? {} : { reason }) }),
)
},
}))
/**
* Apply one pin write and re-read the list.
*
* Shared so that "which environment", "re-read afterwards", "prune the selection" and "where the
* error goes" are decided once. Re-reading rather than patching in place: `pin_add` is an upsert
* and the store is not the authority on what came back out of SQLite.
*/
async function writePin(
set: (partial: Partial<EnvState> | ((s: EnvState) => Partial<EnvState>)) => void,
get: () => EnvState,
write: (envHash: string) => Promise<void>,
): Promise<void> {
const { selected, rows, dists, outdated } = get()
const row = rows.find((r) => r.interpreter === selected)
if (row === undefined) return
try {
await write(row.envHash)
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 {
/** Null until checked; false means the gate must be shown. */
accepted: boolean | null