// Package timefmt provides tools for building and converting time format strings
// with human-readable descriptions.
//
// It offers a fluent builder API for constructing time formats and can convert
// between Go's reference time format, LDML (Unicode Locale Data Markup Language)
// tokens, and plain English descriptions.
//
// # Basic Usage
//
// Build a time format using the fluent builder:
//
//	format := timefmt.NewBuilder().
//	    Year4().Dash().
//	    MonthNumeric2().Dash().
//	    DayNumeric2().
//	    Build()
//
//	fmt.Println(format.GoFormat())      // "2006-01-02"
//	fmt.Println(format.LDML())          // "yyyy-MM-dd"
//	fmt.Println(format.Description())   // "Year (4-digit), dash, ..."
//
// # Pre-built Formats
//
// Common formats are available as package-level constants:
//
//	now := time.Now()
//	fmt.Println(timefmt.ISO8601.Format(now))
//	fmt.Println(timefmt.DateTime.Format(now))
//	fmt.Println(timefmt.DateUS.Format(now))
//
// # Parsing Existing Formats
//
// Parse an existing Go time format string to get human-readable descriptions:
//
//	format, err := timefmt.ParseGoFormat("02/01/2006 15:04:05")
//	if err != nil {
//	    log.Fatal(err)
//	}
//
//	fmt.Println(format.LDML())         // "dd/MM/yyyy HH:mm:ss"
//	fmt.Println(format.Description())  // Full English description
//
// # Multiple Output Formats
//
// Every Format provides three representations:
//
//   - GoFormat(): Go's reference time format (e.g., "2006-01-02")
//   - LDML(): Unicode LDML tokens (e.g., "yyyy-MM-dd")
//   - Description(): Plain English description
//
// This makes it easy to document time formats for both developers and end users.
//
// # Use Cases
//
// Display format information to users:
//
//	format := timefmt.DateOnly
//	fmt.Printf("Expected format: %s\n", format.Description())
//	fmt.Printf("Example: %s\n", format.Example())
//
// Validate user input with helpful error messages:
//
//	if _, err := format.Parse(userInput); err != nil {
//	    return fmt.Errorf("invalid date. Expected: %s (example: %s)",
//	        format.Description(), format.Example())
//	}
//
// Generate documentation for configuration:
//
//	for name, fmt := range configFormats {
//	    fmt.Printf("%s: %s (LDML: %s)\n",
//	        name, fmt.Description(), fmt.LDML())
//	}
//
// # LDML Compatibility
//
// The LDML output follows the Unicode LDML standard, making it compatible with:
//
//   - ICU (International Components for Unicode)
//   - Java (SimpleDateFormat, DateTimeFormatter)
//   - Swift (DateFormatter)
//   - JavaScript (Moment.js, Day.js, date-fns)
//   - Most modern date/time libraries
//
// This allows seamless integration with systems that use LDML for time formatting.
package timefmt