Documentation
¶
Overview ¶
Package storeui provides a generic TUI for browsing and editing storage.Store[T] instances.
It bridges the gap between typed stores (internal/storage) and terminal presentation (internal/tui), enabling interactive field browsing, editing, and layer-targeted saving for any store instance.
Index ¶
- Constants
- func BuildBrowser[T storage.Schema](store *storage.Store[T], opts ...Option) (*tui.FieldBrowserModel, error)
- func GetFieldValue(v any, path string) (any, error)
- func Ptr[T any](v T) *T
- func SetFieldValue(v any, path string, val string) error
- func ShortenHome(p string) string
- type Field
- type FieldKind
- type LayerTarget
- type Option
- type Override
- type Result
Constants ¶
const ( LabelProject = "Project" // walk-up target (in-play file or CWD candidate) LabelUser = "User" // configured directory candidate (config dir etc.) LabelLocal = "Local" // domain-applied: discovered local override file )
Save-destination label vocabulary. BuildLayerTargets applies the placement labels (Project, User); LabelLocal is exported for domain adapters that relabel targets whose Filename they recognize as a local override — which filename that is being domain knowledge storeui does not hold.
const ( KindText = storage.KindText KindBool = storage.KindBool KindSelect = storage.KindSelect KindInt = storage.KindInt KindStringSlice = storage.KindStringSlice KindDuration = storage.KindDuration KindTime = storage.KindTime KindMap = storage.KindMap KindStructSlice = storage.KindStructSlice )
Re-export storage.FieldKind constants for backward compatibility.
Variables ¶
This section is empty.
Functions ¶
func BuildBrowser ¶
func BuildBrowser[T storage.Schema](store *storage.Store[T], opts ...Option) (*tui.FieldBrowserModel, error)
BuildBrowser creates a FieldBrowserModel for a storage.Store[T] without running it. The returned model can be wrapped as a WizardPage via tui.NewBrowserPage or run standalone via tui.RunProgram. All save/delete callbacks are wired.
func GetFieldValue ¶ added in v0.12.11
GetFieldValue reads a field on a struct pointer by its dotted YAML path and returns its typed value, dereferencing pointers (a nil pointer yields nil). It is the read counterpart of SetFieldValue: coerce a string into a fresh T with SetFieldValue, then read the typed value back out for storage.Store.Set.
v must be a non-nil pointer to a struct, else an error is returned.
func Ptr ¶
func Ptr[T any](v T) *T
Ptr returns a pointer to a copy of the given value. Useful for constructing Override fields.
func SetFieldValue ¶
SetFieldValue sets a field on a struct pointer by its dotted YAML path. It walks the struct via yaml tags, allocates nil pointer-to-struct parents, and performs type-aware conversion at the leaf.
v must be a non-nil pointer to a struct. Panics otherwise.
func ShortenHome ¶
ShortenHome replaces $HOME prefix with ~ for display.
Types ¶
type Field ¶
type Field struct {
Path string // Dotted YAML path (e.g. "build.image")
Label string // Human-readable label
Description string // Help text
Kind FieldKind // Widget type
Value string // Formatted current value (compact summary for browse display)
EditValue string // Full value for editor pre-population (YAML for Map/StructSlice kinds)
Default string // Effective default shown when Value is "<unset>" or empty
Options []string // For Select fields
Validator func(string) error // Optional input validation
Required bool // Whether the field must have a value
ReadOnly bool // Whether the field is not editable
Order int // Sort order (lower = first)
// Editor is a custom editor factory provided by domain adapters.
// When non-nil, the field browser uses it instead of the default kind-based
// editor dispatch. The returned value must satisfy [tui.FieldEditor].
// Using any preserves the storeui → tui import boundary.
Editor func(label, value string) any
}
Field represents a single editable configuration field discovered via reflection.
func ApplyOverrides ¶
ApplyOverrides merges overrides into a copy of fields, returning the result sorted by Order. Fields matched by a Hidden override are removed. Nil override pointer fields do not clobber existing values. Overrides with no matching field path are silently ignored.
func WalkFields ¶
WalkFields uses reflection to discover editable fields from a struct value. It maps Go types to FieldKind: string→Text, bool→Bool, *bool→Bool, int/int64→Int, []string→StringSlice, time.Duration→Duration, time.Time→Time, map[string]string→Map, []struct→StructSlice, nested struct→recurse, nil *struct→recurse zero value. Unrecognized types fall back to KindStructSlice (enrichWithSchema overwrites the kind from schema metadata afterward).
Accepts both value and pointer types. Uses yaml struct tags for path building.
type FieldKind ¶
FieldKind is an alias for storage.FieldKind. Consumers should use the storage constants (KindText, KindBool, etc.) directly.
type LayerTarget ¶
type LayerTarget struct {
Label string // Display label (e.g. "Project", "User", "Local")
Description string // Shortened path for display
Path string // Full absolute filesystem path
Filename string // Store-configured filename this target serves (for domain relabeling)
}
LayerTarget represents a save destination for a single field. Domain adapters build these from config accessors.
func BuildLayerTargets ¶
BuildLayerTargets builds save destinations from the store's own write targets (storage.Store.WriteTargets), so the editor only ever offers locations the store can rediscover on reload — a store without walk-up gets no "Project" target. The walk-up target is labeled "Project", directory candidates "User", and discovered layer files show their shortened path; each target carries the store-reported Filename so a domain adapter can relabel filenames it recognizes (e.g. a local override file). Virtual layers (defaults) are never offered.
type Option ¶
type Option func(*editOptions)
Option configures the Edit function.
func WithLayerTargets ¶
func WithLayerTargets(targets []LayerTarget) Option
WithLayerTargets provides the per-field save destinations. Domain adapters build these using config path accessors.
func WithOnlyPaths ¶
WithOnlyPaths restricts the editor to show only the given dotted paths. All other fields are excluded. When set, WithSkipPaths is ignored.
func WithOverrides ¶
WithOverrides provides domain-specific field overrides.
func WithSkipPaths ¶
WithSkipPaths hides the given dotted paths from the editor.
type Override ¶
type Override struct {
Path string
Label *string
Description *string
Default *string // Effective default shown when value is "<unset>"
Kind *FieldKind
Options []string // Replaces options when non-nil
Validator func(string) error // Replaces validator when non-nil
Required *bool
ReadOnly *bool
Order *int
Hidden bool // When true, removes the field from the list entirely
// Editor is a custom editor factory for this field.
// When non-nil, the field browser uses it instead of the default kind-based
// editor dispatch. The returned value must satisfy [tui.FieldEditor].
Editor func(label, value string) any
}
Override allows domain adapters to customize reflected fields by path. Pointer fields use nil to mean "don't override" — only non-nil values replace the original.
type Result ¶
type Result struct {
Saved bool // True if any field was persisted
Cancelled bool // True if the user cancelled
SavedCount int // Number of fields successfully saved
}
Result holds the outcome of an interactive edit session.
func Edit ¶
func Edit[T storage.Schema](ios *iostreams.IOStreams, store *storage.Store[T], opts ...Option) (Result, error)
Edit runs an interactive field editor for a storage.Store[T].
Each field edit is saved immediately to a user-chosen layer target. The orchestration flow:
- store.Read() → snapshot
- WalkFields(snapshot) → fields
- Filter skip paths, ApplyOverrides
- Map storeui.Field → tui.BrowserField, run tui.FieldBrowserModel
- OnFieldSaved callback: store.Set + store.WriteTo(target) per field
- Return Result