feat(ui): format phone numbers for display (#873)

## Summary

- Add `FormatPhoneNumber` in `internal/locale/phone.go` using
`nyaruka/phonenumbers` for international phone formatting (NATIONAL for
same-region, INTERNATIONAL for foreign numbers)
- Add `Locale` field to `Vendor` model (ISO 3166-1 alpha-2, empty =
system default via `DetectCountry()`)
- Add `cellTelephoneNumber` kind with explicit exhaustive switch cases
- Format phones in the TUI vendor table, CLI `show vendors` text output,
and extraction preview
- Preserve `Locale` through form round-trips; leave `FindOrCreateVendor`
untouched
- JSON `show vendors` output keeps raw phone values for machine
consumption
- Handle shared calling codes (+1 US/CA) by checking `+` prefix presence
for fictional numbers

closes #860

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: cpcloud

cmd/micasa/show.go

@@ -12,7 +12,9 @@ import (
 	"text/tabwriter"
 	"time"
 
+	"github.com/micasa-dev/micasa/internal/config"
 	"github.com/micasa-dev/micasa/internal/data"
+	"github.com/micasa-dev/micasa/internal/locale"
 	"github.com/spf13/cobra"
 	"gorm.io/gorm"
 )
@@ -447,7 +449,13 @@ var vendorCols = []showCol[data.Vendor]{
 	{"NAME", func(v data.Vendor) string { return fmtStr(v.Name) }},
 	{"CONTACT", func(v data.Vendor) string { return fmtStr(v.ContactName) }},
 	{"EMAIL", func(v data.Vendor) string { return fmtStr(v.Email) }},
-	{"PHONE", func(v data.Vendor) string { return fmtStr(v.Phone) }},
+	{"PHONE", func(v data.Vendor) string {
+		region := strings.ToUpper(config.DetectCountry())
+		if v.Locale != "" {
+			region = strings.ToUpper(v.Locale)
+		}
+		return fmtStr(locale.FormatPhoneNumber(v.Phone, region))
+	}},
 	{"WEBSITE", func(v data.Vendor) string { return fmtStr(v.Website) }},
 }
 

cmd/micasa/show_test.go

@@ -169,14 +169,16 @@ func TestShowProjectsJSON(t *testing.T) {
 }
 
 func TestShowVendorsText(t *testing.T) {
-	t.Parallel()
+	// Not parallel: t.Setenv modifies process-global state.
+	// LC_ALL has highest precedence in DetectCountry().
+	t.Setenv("LC_ALL", "en_US.UTF-8")
 	store := newTestStoreWithMigration(t)
 
 	require.NoError(t, store.CreateVendor(&data.Vendor{
 		Name:        "Acme Plumbing",
 		ContactName: "John Doe",
 		Email:       "john@acme.com",
-		Phone:       "555-1234",
+		Phone:       "5551234567",
 	}))
 
 	var buf bytes.Buffer
@@ -187,7 +189,7 @@ func TestShowVendorsText(t *testing.T) {
 	assert.Contains(t, out, "Acme Plumbing")
 	assert.Contains(t, out, "John Doe")
 	assert.Contains(t, out, "john@acme.com")
-	assert.Contains(t, out, "555-1234")
+	assert.Contains(t, out, "(555) 123-4567")
 }
 
 func TestShowVendorsJSON(t *testing.T) {
@@ -210,6 +212,25 @@ func TestShowVendorsJSON(t *testing.T) {
 	assert.NotEmpty(t, result[0]["id"])
 }
 
+func TestShowVendorsJSONPhoneRaw(t *testing.T) {
+	t.Parallel()
+	store := newTestStoreWithMigration(t)
+
+	require.NoError(t, store.CreateVendor(&data.Vendor{
+		Name:  "Raw Phone Co",
+		Phone: "5551234567",
+	}))
+
+	var buf bytes.Buffer
+	require.NoError(t, runShow(&buf, store, "vendors", true, false))
+
+	var result []map[string]any
+	require.NoError(t, json.Unmarshal(buf.Bytes(), &result))
+	require.Len(t, result, 1)
+	assert.Equal(t, "5551234567", result[0]["phone"],
+		"JSON output must carry raw phone, not formatted")
+}
+
 func TestShowAppliancesText(t *testing.T) {
 	t.Parallel()
 	store := newTestStoreWithMigration(t)

go.mod

@@ -17,6 +17,7 @@ require (
 	github.com/itchyny/gojq v0.12.18
 	github.com/mark3labs/mcp-go v0.46.0
 	github.com/mozilla-ai/any-llm-go v0.9.0
+	github.com/nyaruka/phonenumbers v1.6.12
 	github.com/oklog/ulid/v2 v2.1.1
 	github.com/spf13/cobra v1.10.2
 	github.com/stretchr/testify v1.11.1

go.sum

@@ -193,6 +193,8 @@ github.com/muesli/roff v0.1.0 h1:YD0lalCotmYuF5HhZliKWlIx7IEhiXeSfq7hNjFqGF8=
 github.com/muesli/roff v0.1.0/go.mod h1:pjAHQM9hdUUwm/krAfrLGgJkXJ+YuhtsfZ42kieB2Ig=
 github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOFAw7w=
 github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
+github.com/nyaruka/phonenumbers v1.6.12 h1:aeGHjGQnfLhdN5/mZPevhoYMs13FWcQ0Vus0YQHh1Ec=
+github.com/nyaruka/phonenumbers v1.6.12/go.mod h1:IUu45lj2bSeYXQuxDyyuzOrdV10tyRa1YSsfH8EKN5c=
 github.com/oklog/ulid/v2 v2.1.1 h1:suPZ4ARWLOJLegGFiZZ1dFAkqzhMjL3J1TzI+5wHz8s=
 github.com/oklog/ulid/v2 v2.1.1/go.mod h1:rcEKHmBBKfef9DhnvX7y1HZBYxjXb0cP5ExxNsTT1QQ=
 github.com/ollama/ollama v0.18.3 h1:sOJhncLeA+ZlwLLjEksY393wojeYE52E1CF4E0ZgFN4=

internal/app/coldefs.go

@@ -218,7 +218,7 @@ var vendorColumnDefs = []columnDef{
 	{"Name", columnSpec{Title: "Name", Min: 14, Max: 24, Flex: true}},
 	{"Contact", columnSpec{Title: "Contact", Min: 10, Max: 20, Flex: true}},
 	{"Email", columnSpec{Title: "Email", Min: 12, Max: 24, Flex: true}},
-	{"Phone", columnSpec{Title: "Phone", Min: 12, Max: 16}},
+	{"Phone", columnSpec{Title: "Phone", Min: 12, Max: 20, Kind: cellTelephoneNumber}},
 	{"Website", columnSpec{Title: "Website", Min: 12, Max: 28, Flex: true}},
 	{
 		"Quotes",

internal/app/extraction_render.go

@@ -12,6 +12,7 @@ import (
 	"time"
 
 	"charm.land/lipgloss/v2"
+	"github.com/micasa-dev/micasa/internal/config"
 	"github.com/micasa-dev/micasa/internal/data"
 	"github.com/micasa-dev/micasa/internal/extract"
 	"github.com/micasa-dev/micasa/internal/locale"
@@ -707,7 +708,7 @@ func previewColumns(tableName string, cur locale.Currency) []previewColDef {
 			{data.ColName, s[1], fmtAnyText},
 			{data.ColContactName, s[2], fmtAnyText},
 			{data.ColEmail, s[3], fmtAnyText},
-			{data.ColPhone, s[4], fmtAnyText},
+			{data.ColPhone, s[4], fmtPhone},
 			{data.ColWebsite, s[5], fmtAnyText},
 		}
 	case tableDocuments:
@@ -873,6 +874,17 @@ func fmtAnyText(v any) string {
 	}
 }
 
+func fmtPhone(v any) string {
+	if v == nil {
+		return ""
+	}
+	s, ok := v.(string)
+	if !ok {
+		return fmtAnyText(v)
+	}
+	return locale.FormatPhoneNumber(s, strings.ToUpper(config.DetectCountry()))
+}
+
 func fmtAnyFK(v any) string {
 	s := fmtAnyText(v)
 	if s != "" && s != "0" {

internal/app/extraction_render_test.go

@@ -0,0 +1,36 @@
+// Copyright 2026 Phillip Cloud
+// Licensed under the Apache License, Version 2.0
+
+package app
+
+import (
+	"testing"
+
+	"github.com/micasa-dev/micasa/internal/data"
+	"github.com/micasa-dev/micasa/internal/locale"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestPreviewColumnsVendorFormatsPhone(t *testing.T) {
+	// Not parallel: t.Setenv modifies process-global state.
+	// LC_ALL has highest precedence in DetectCountry().
+	t.Setenv("LC_ALL", "en_US.UTF-8")
+	cur, err := locale.ResolveDefault("")
+	require.NoError(t, err)
+	cols := previewColumns(data.TableVendors, cur)
+
+	// Find the phone column by key.
+	var phoneFmt func(any) string
+	for _, c := range cols {
+		if c.dataKey == data.ColPhone {
+			phoneFmt = c.format
+			break
+		}
+	}
+	require.NotNil(t, phoneFmt, "phone column not found in vendor preview")
+
+	// Should format parseable numbers, passthrough garbage.
+	assert.Equal(t, "(555) 123-4567", phoneFmt("5551234567"))
+	assert.Equal(t, "not a phone", phoneFmt("not a phone"))
+}

internal/app/forms.go

@@ -126,6 +126,7 @@ type vendorFormData struct {
 	Phone       string
 	Website     string
 	Notes       string
+	Locale      string
 }
 
 // entityRef identifies a polymorphic document parent (kind + ID).
@@ -1102,6 +1103,7 @@ func (m *Model) parseVendorFormData() (data.Vendor, error) {
 		Phone:       strings.TrimSpace(values.Phone),
 		Website:     strings.TrimSpace(values.Website),
 		Notes:       strings.TrimSpace(values.Notes),
+		Locale:      strings.TrimSpace(values.Locale),
 	}, nil
 }
 
@@ -1153,6 +1155,7 @@ func vendorFormValues(vendor data.Vendor) *vendorFormData {
 		Phone:       vendor.Phone,
 		Website:     vendor.Website,
 		Notes:       vendor.Notes,
+		Locale:      vendor.Locale,
 	}
 }
 

internal/app/handlers.go

@@ -5,9 +5,11 @@ package app
 
 import (
 	"fmt"
+	"strings"
 	"time"
 
 	"charm.land/bubbles/v2/table"
+	"github.com/micasa-dev/micasa/internal/config"
 	"github.com/micasa-dev/micasa/internal/data"
 )
 
@@ -494,7 +496,8 @@ func (vendorHandler) Load(
 	quoteCounts := fetchCounts(store.CountQuotesByVendor, ids)
 	jobCounts := fetchCounts(store.CountServiceLogsByVendor, ids)
 	docCounts := fetchDocCounts(store, data.DocumentEntityVendor, ids)
-	rows, meta, cellRows := vendorRows(vendors, quoteCounts, jobCounts, docCounts)
+	defaultRegion := strings.ToUpper(config.DetectCountry())
+	rows, meta, cellRows := vendorRows(vendors, quoteCounts, jobCounts, docCounts, defaultRegion)
 	return rows, meta, cellRows, nil
 }
 

internal/app/mag.go

@@ -26,13 +26,13 @@ func magFormat(c cell, includeUnit bool, currencySymbol string) string {
 	}
 
 	// Only transform kinds that carry meaningful numeric data.
-	// cellText is excluded because it covers phone numbers, serial numbers,
+	// cellText is excluded because it covers serial numbers,
 	// model numbers, and other identifiers that happen to look numeric.
 	switch c.Kind {
 	case cellMoney, cellDrilldown, cellOps:
 		// Definitely numeric; continue to parsing below.
 	case cellText, cellReadonly, cellDate, cellStatus, cellWarranty,
-		cellUrgency, cellNotes, cellEntity:
+		cellUrgency, cellNotes, cellEntity, cellTelephoneNumber:
 		return value
 	default:
 		panic(fmt.Sprintf("unhandled cellKind: %d", c.Kind))