storeui

package
v0.12.11 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 3, 2026 License: AGPL-3.0 Imports: 13 Imported by: 0

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

View Source
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.

View Source
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

func GetFieldValue(v any, path string) (any, error)

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

func SetFieldValue(v any, path string, val string) error

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

func ShortenHome(p string) string

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

func ApplyOverrides(fields []Field, overrides []Override) []Field

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

func WalkFields(v any) []Field

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

type FieldKind = storage.FieldKind

FieldKind is an alias for storage.FieldKind. Consumers should use the storage constants (KindText, KindBool, etc.) directly.

const KindTriState FieldKind = KindBool

KindTriState is deprecated. Use KindBool instead. Retained for backward compatibility — maps to the same underlying type as KindBool.

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

func BuildLayerTargets[T storage.Schema](store *storage.Store[T]) ([]LayerTarget, error)

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

func WithOnlyPaths(paths ...string) Option

WithOnlyPaths restricts the editor to show only the given dotted paths. All other fields are excluded. When set, WithSkipPaths is ignored.

func WithOverrides

func WithOverrides(overrides []Override) Option

WithOverrides provides domain-specific field overrides.

func WithSkipPaths

func WithSkipPaths(paths ...string) Option

WithSkipPaths hides the given dotted paths from the editor.

func WithTitle

func WithTitle(title string) Option

WithTitle sets the editor title displayed at the top.

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:

  1. store.Read() → snapshot
  2. WalkFields(snapshot) → fields
  3. Filter skip paths, ApplyOverrides
  4. Map storeui.Field → tui.BrowserField, run tui.FieldBrowserModel
  5. OnFieldSaved callback: store.Set + store.WriteTo(target) per field
  6. Return Result

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL