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:
1 parent
ef5b489861
commit
980bd5d750
8 files changed
+238
-36
No files matched your search
@@ -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 />,
|
||||
}
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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"
|
||||
/>
|
||||
)
|
||||
}
|
||||
@@ -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
@@ -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
|
||||
|
||||
Reference in new issue
Block a user