feat(ui): add formatRelative() for human-readable timestamps

[galligan]

Formats dates as relative time strings ("just now", "5 minutes ago",
"2 days ago"). Handles both past and future dates with appropriate
phrasing. Covers edge cases documented in SPEC.

Closes #48

Co-Authored-By: Claude Opus 4.5 noreply@anthropic.com

[galligan]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• chore(outfitter): sync templates on pack #108
• chore(changesets): ignore app package #107
• fix(errors): avoid TaggedError extends warnings #106
• chore(release): align package versions to 0.1.0 #105
• docs: add README and CHANGELOG for testing, kit, outfitter #95
• feat(templates): add daemon project template #94
• feat(templates): add MCP server project template #93
• feat(templates): add CLI project template #92
• fix(cli): implement confirmDestructive prompts #104
• fix(cli): implement createCLI and command builder #103
• feat(kit): add @outfitter/kit meta-package #91
• docs(daemon): add README and CHANGELOG #90
• fix(daemon): fix locking module bugs (GREEN phase) #89
• test(daemon): add locking module tests (RED phase) #88
• feat(daemon): add errors, platform, and locking module stubs #87
• feat(outfitter): add doctor command for environment validation #86
• feat(outfitter): add init command with project scaffolding #85
• feat(daemon): add IPC communication and health checks #84
• feat(daemon): add types and lifecycle management #83
• feat(index): add FTS5 full-text search implementation #82
• feat(index): add types for FTS5 full-text search #81
• feat(testing): add MCP and CLI test harnesses #80
• feat(testing): add test fixture utilities #79
• feat(mcp): add MCP server implementation with typed handlers #78
• feat(mcp): add types and interfaces for MCP server #77
• feat(ui): add Shape discriminated union and render() #76
• feat(ui): add createTokens semantic color layer #75
• feat(state): add pagination helpers #74
• feat(logging): add DEFAULT_PATTERNS for common secret redaction #73
• feat(ui): add formatRelative() for human-readable timestamps #72 👈 (View in Graphite)
• feat(state): add encodeCursor/decodeCursor for pagination #71
• feat(types): add hashId() for deterministic short identifiers #70
• feat(contracts): add Logger.child() and fix AssertionError category #69
• feat(config): centralize environment variable access with Zod validation #42
• fix(logging): enable redaction by default when global rules exist #41
• docs(ui): add README, CHANGELOG, and TSDoc comments #39
• docs(state): add README, CHANGELOG, and TSDoc comments #38
• docs(file-ops): add README, CHANGELOG, and TSDoc comments #37
• docs(logging): add README, CHANGELOG, and TSDoc comments #36
• docs(config): add README, CHANGELOG, and TSDoc comments #35
• fix(cli): enforce cursor TTL #114
• fix(tests): remove placeholder tests #113
• chore(gitattributes): prefer ours for bun lockfiles #115
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: cc258f2c24

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[greptile-apps]

Greptile Summary

• Adds formatRelative() function to packages/ui/src/index.ts for human-readable timestamp formatting ("just now", "5 minutes ago", "tomorrow")
• Introduces comprehensive test suite in packages/ui/src/__tests__/format-relative.test.ts covering multiple input types, edge cases, and future/past date handling

Important Files Changed

Filename	Overview
packages/ui/src/index.ts	New formatRelative() function implementation with robust input handling and cascading time unit logic
packages/ui/src/tests/format-relative.test.ts	New comprehensive test suite covering all time ranges, input types, and edge cases for the formatRelative function

Confidence score: 5/5

• This PR is safe to merge with minimal risk as it adds a self-contained utility function with comprehensive test coverage
• Score reflects the thorough implementation following TDD principles, robust error handling, and well-structured test cases
• No files require special attention as the code is well-tested and follows established patterns

Sequence Diagram

sequenceDiagram
    participant User
    participant formatRelative
    participant Date
    participant Math
    
    User->>formatRelative: "Call with date input (Date|number|string)"
    formatRelative->>formatRelative: "Convert input to timestamp"
    alt "Input is Date object"
        formatRelative->>Date: "getTime()"
        Date-->>formatRelative: "timestamp"
    else "Input is number"
        formatRelative->>formatRelative: "Use as timestamp"
    else "Input is string"
        formatRelative->>Date: "parse(string)"
        Date-->>formatRelative: "parsed timestamp"
    end
    
    formatRelative->>Date: "now()"
    Date-->>formatRelative: "current timestamp"
    
    formatRelative->>Math: "abs(now - timestamp)"
    Math-->>formatRelative: "absolute difference"
    
    formatRelative->>formatRelative: "Determine time unit and format"
    alt "< 10 seconds"
        formatRelative-->>User: "'just now'"
    else "< 1 minute"
        formatRelative-->>User: "'X seconds ago/in X seconds'"
    else "< 1 hour"
        formatRelative-->>User: "'X minutes ago/in X minutes'"
    else "< 1 day"
        formatRelative-->>User: "'X hours ago/in X hours'"
    else "< 2 days"
        formatRelative-->>User: "'yesterday/tomorrow'"
    else "< 1 month"
        formatRelative-->>User: "'X days ago/in X days'"
    else "< 1 year"
        formatRelative-->>User: "'X months ago/in X months'"
    else "> 1 year"
        formatRelative-->>User: "'X years ago/in X years'"
    end

Loading

[galligan]

Added explicit tests for invalid Date and non-finite timestamp inputs in formatRelative().

[galligan]

Fixed flakiness in formatRelative tests by freezing Date.now per test (avoids sub-millisecond drift in future-hour assertions).

[galligan]

Resubmitted after restack; formatRelative already guards invalid Date/number inputs with Number.isFinite, so no additional changes needed here.

[galligan]

Resubmitted after downstack updates; no new feedback beyond already-resolved formatRelative guard/test tweaks.