lesli_date 1.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98f6a82caee6c75ab6e3c9734827c809e3d1aa0240e914075915783498a5c390
-  data.tar.gz: eb622a5530482c55ca05a6202783632450b2af3025264a1bd72b998cc6f8c389
+  metadata.gz: d64dec0455da16b095e0cb4b67fccb28fb2a3010f97dedcd97e0ac8178e272ca
+  data.tar.gz: 1452d2bf0482a4604b26b03341312e3ebab51fdedba716807fd38457cb11162d
 SHA512:
-  metadata.gz: 6ac72c1eea1075046b372676f9de4b2c0fb8ebdc3ff9bc228ac557c295f0a87743d155092a08171c6bb9e4293983e8771ae20ee3a1c82ce7f9aa1142062e3db0
-  data.tar.gz: 1a3707b14b70c9924b8ee9ee5145d0bad7a611cc21d23bd8c406c8e99204a9a1281e4df9420a579d5823459bea85b3d4985a2a9492580aad92d3d22525b88b9e
+  metadata.gz: bfc90a78e1b1cb23175cf9d3283720048ca882d7268528422ff20b169f67ba78ffe29a26599028cd6c5d0f1d5b3e60ccd84673425c7338a7f29f89feefeb568f
+  data.tar.gz: 03e1aa63070d95b58b153413ce7c17d3d0052829f3be572d6d141863ca53d0533f370b441e6c8f6ec6bf2a028d6d46660446ac5c4809fcbed5a767a9838a3a33

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## 1.1.0 (unreleased)
+
+### Requirements
+
+- Ruby 3.3 or later; ActiveSupport and ActiveRecord 8.0.x or 8.1.x.
+- Explicit runtime dependencies on ActiveSupport, ActiveRecord and I18n.
+- Database drivers remain dependencies of the host application.
+
+### Parsing and presentation
+
+- Preserve temporal instants and native precision; retain calendar dates as `Date`.
+- Use native Ruby parsing and Rails time-zone conversion. UTC is the default
+  input zone; external local times can specify `input_zone:`.
+- Apply all configured output formats, with defaults for omitted values.
+- Use existing Rails translations with optional per-formatter `locale:`.
+- Expose parsing and configuration errors through `ArgumentError` subclasses.
+- Keep the fluent selectors, positional signatures, `.get` and Date2 inheritance.
+
+### SQL and verification
+
+- Quote SQL identifiers and literals with ActiveRecord, without modifying inputs.
+- Return both timestamp columns with shared `*_string` aliases on SQLite and PostgreSQL.
+- Generate expressions without executing validation queries; `as: false` omits an alias.
+- Preserve fractional fixed offsets in SQLite; use per-row IANA conversion in PostgreSQL.
+- Keep native SQLite `NULL` results for unsupported formatting directives.
+- Run standalone LesliTesting suites with real SQLite and PostgreSQL queries.
+- Use the LesliActions gem workflow and test the supported Rails lines in CI.
+
+See [application examples](docs/api/examples.md) for forms, APIs, imports and SQL.

data/Rakefile

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require "minitest/test_task"
 
-RSpec::Core::RakeTask.new(:spec)
+Minitest::TestTask.create
 
-task default: :spec
+task default: :test

data/docs/about/configuration.md

@@ -0,0 +1,100 @@
+# Configuration and presentation
+
+LesliDate reads `Lesli.config.datetime` from the Lesli initializer. Database
+timestamps are interpreted as UTC; `time_zone` controls presentation. The fluent
+API stays the same:
+
+```ruby
+LesliDate::Formatter.new(value).date.to_s
+LesliDate::Formatter.new(value).time.to_s
+LesliDate::Formatter.new(value).date_time.to_s
+LesliDate::Formatter.new(value).date_words.to_s
+```
+
+## Initializer formats
+
+Each selector reads the same-named symbol key from `datetime[:formats]`. These
+are the patterns supplied by the Lesli initializer:
+
+```ruby
+config.datetime = {
+  time_zone: "America/Guatemala",
+  start_week_on: "monday",
+  formats: {
+    date: "%d/%m/%Y",
+    time: "%H:%M",
+    date_time: "%d/%m/%Y %H:%M",
+    date_words: "%A, %B %d, %Y",
+    date_time_words: "%A, %B %d, %Y, %H:%M",
+    date_time_words_pm: "%A, %B %d, %Y, %I:%M %p",
+    date_time_words_day: "%A, %B %d, %Y, %H:%M"
+  }
+}
+```
+
+`date_words_day` is also configurable. When omitted, it uses its fallback.
+`start_week_on` remains part of Lesli's configuration and does not change how
+this formatter parses or presents a value.
+
+## Missing settings and validation
+
+The entire `formats` hash is optional: absent, `nil`, or empty hashes use the
+fallback patterns listed in the [Formatter API](/gems/date/api/formatter).
+Partial hashes override only the supplied keys, and individual `nil` values
+also use the fallback. Defaults are merged without modifying the initializer.
+Existing formatters retain their patterns if configuration changes later.
+
+Output patterns must be nonempty strings. Empty or whitespace-only strings,
+invalid text encoding, and other value types raise `LesliDate::InvalidFormat`
+when constructing the formatter. A non-hash `formats` value also raises this
+error. Every configured pattern is checked, even if its selector is not used.
+
+Syntax checks delegate to Ruby's `strftime`; there is no directive allowlist or
+custom pattern compiler. Directives that Ruby preserves as literal text retain
+that behavior. Native formatting exceptions are exposed as `InvalidFormat`.
+
+A valid output zone is required in the initializer unless supplied through
+`zone:`. `input_zone:` defaults to UTC and can be used for external local-time
+sources. Both zone names are validated during construction. Missing or unknown
+zones raise `LesliDate::InvalidTimeZone` rather than using the process timezone.
+
+## Native Rails translations
+
+`to_s` calls `I18n.localize` with the configured pattern. It uses the backend,
+locale data, fallbacks and customizations already configured by the Rails
+application. LesliDate does not register locales, ship translations, change the
+backend or alter `I18n.locale`.
+
+By default, each call to `to_s` uses the current `I18n.locale`. Set `locale:` to
+choose a language for one formatter:
+
+```ruby
+I18n.with_locale(:es) do
+  LesliDate::Formatter.new("2026-10-22").date_words.to_s
+  # => "jueves, octubre 22, 2026", with the initializer above
+end
+
+LesliDate::Formatter.new("2026-10-22", locale: :en).date_words.to_s
+# => "Thursday, October 22, 2026"
+```
+
+The pattern controls order and punctuation; I18n supplies words for directives
+such as `%A`, `%a`, `%B`, `%b`, `%p` and `%P`. Ruby/Rails also determine casing,
+so `%p` uses uppercase AM/PM text. The input parser is unchanged and does not
+use this output locale to interpret strings.
+
+Use the translations Rails already loads, including the application's existing
+Rails locale-data dependencies. Only add keys in Lesli or the host application's
+locale files when customization is desired. For example, an optional override
+file can contain just:
+
+```yaml
+es:
+  time:
+    am: "a. m."
+    pm: "p. m."
+```
+
+All other translations remain with the existing I18n backend. Missing locales
+or translations follow Rails/I18n's configured behavior; LesliDate does not add
+a separate fallback language or translation-loading mechanism.

data/docs/about/development.md

@@ -0,0 +1,131 @@
+# Development and tests
+
+Run commands from the LesliDate gem directory. The suite uses LesliTesting 1.4.2,
+Minitest 6, ActiveRecord/ActiveSupport 8.0.x or 8.1.x, SQLite and PostgreSQL.
+It runs without a Rails or Lesli application. Ruby 3.3 or later is required;
+CI uses 3.3.5. The lockfile includes macOS Intel and Linux x86_64.
+
+```shell
+bundle install
+bundle exec rake
+COVERAGE=true bundle exec rake test
+```
+
+## LesliTesting integration
+
+`test/test_helper.rb` requires LesliTesting and configures
+`LesliTesting.gem("LesliDate", coverage_min_coverage: 90)` before loading the gem.
+This activates the shared Minitest reporter and, when `COVERAGE=true`, SimpleCov
+with console and Cobertura output at `coverage/coverage.xml`.
+
+`Rakefile` exposes the standard Minitest `test` task as its default. The GitHub
+Actions workflow delegates to
+`LesliTech/LesliActions/.github/workflows/lesli-ci-gem.yaml@master`, which runs
+coverage tests, verifies the XML report, builds the gem, and uploads artifacts.
+Providing `CODECOV_TOKEN` also enables its optional Codecov upload. The reusable
+LesliActions gem job remains the SQLite coverage and packaging job. An adapter
+matrix starts PostgreSQL 17 and runs the same LesliTesting suite in SQLite and
+PostgreSQL for each supported Rails line:
+
+| CI lane | Ruby | Rails components | Database |
+| --- | --- | --- | --- |
+| LesliActions gem workflow | 3.3.5 | Locked 8.0.x baseline | SQLite |
+| Adapter matrix | 3.3.5 | 8.0.x / 8.1.x | SQLite and PostgreSQL 17 |
+
+`RAILS_VERSION` selects matching ActiveRecord and ActiveSupport requirements in
+the development Gemfile. The checked-in lockfile keeps the baseline; the matrix
+allows Bundler to resolve the selected line and uses separate caches. To test a
+different line locally, update the development bundle explicitly:
+
+```shell
+RAILS_VERSION='~> 8.1.0' bundle install
+RAILS_VERSION='~> 8.1.0' bundle exec rake test
+```
+
+This changes the local lockfile. Run `bundle install` without `RAILS_VERSION`
+to return to the default 8.0.x development requirement before committing.
+
+## Controlled test environment
+
+Each test receives a fresh `Lesli.config.datetime` with the
+`America/Guatemala` display zone, a Monday week start, `%d.%m.%Y` date format,
+and `%d.%m.%Y %H:%M` date-time format. The helper supplies only the minimal
+Lesli configuration interface; it does not load the framework.
+
+The Ruby clock is fixed at `2026-10-22 14:30:45 UTC`, `Time.zone` is UTC, and
+the locale is English. Configuration, clock, zone, and locale are restored after
+each test. Spanish translation fixtures support localization tests without
+booting a Rails application. These fixtures are test data only; LesliDate
+registers no translations at runtime.
+
+SQLite uses a dedicated `:memory:` database. The `events` table is reset before
+every test with these UTC timestamps:
+
+| Column | Value |
+| --- | --- |
+| `occurred_at` | `2026-10-22 14:30:45` |
+| `created_at` | `2026-10-22 14:30:45` |
+| `updated_at` | `2026-10-23 15:40:50` |
+
+The database's own clock is independent of Ruby's frozen clock. The `db_now` test
+checks the expression and result shape without asserting a wall-clock value.
+
+## Test groups
+
+| File | Coverage |
+| --- | --- |
+| `test/lesli_date_test.rb` | Version and build metadata |
+| `test/formatter_test.rb` | Constructor calls, supported inputs, explicit output, chaining, `.get`, configuration, and the Date2 subclass pattern |
+| `test/parser_test.rb` | Calendar dates, native Ruby formats and exceptions, fractions, offsets, zone conversion, and standalone loading |
+| `test/presentation_test.rb` | All initializer formats, defaults, construction-time validation, Rails locales and host translation overrides |
+| `test/database_test.rb` | Real SQL execution, aliases, NULL values, ActiveRecord selects and grouped counts on either adapter |
+| `test/database_regression_test.rb` | Quoting, immutable arguments, fractional offsets, native format limitations and PostgreSQL daylight saving/session independence |
+
+## Running PostgreSQL tests
+
+SQLite is the default and requires no server. To run the same suite against
+PostgreSQL, supply a test database URL:
+
+```shell
+LESLI_DATE_DATABASE_URL=postgresql://localhost/lesli_date_test bundle exec rake test
+```
+
+The helper creates an isolated `lesli_date_test_<pid>` schema, sets the
+connection's search path to it, and drops that schema after the run. The test
+user needs permission to create schemas. Each test resets the same controlled
+fixture data as SQLite. A failed connection fails the suite; PostgreSQL tests
+are never replaced with SQL-generation stubs or silently skipped.
+
+Date2 remains a minimal subclass defined in the test file, independent of the
+application's source tree. The SQL regressions are ordinary passing tests;
+there is no pending-defect wrapper. Tests cover each adapter's formatting
+behavior, including SQLite's native `NULL` for unsupported directives.
+See [Database expressions](../api/database.md) for each
+adapter's formats, zone limitations, and the shared `*_string` aliases.
+
+## Reproduce ordering
+
+Minitest randomizes test order and prints the seed. Reuse it with the standard
+Minitest task's `A` argument:
+
+```shell
+bundle exec rake test A="--seed 1729"
+```
+
+## Preparing a release
+
+1. Choose the release version in `lib/lesli_date/version.rb`, move the
+   `Unreleased` changelog entries to that version, and refresh `Gemfile.lock`.
+2. Run the CI matrix and review the changelog.
+3. Build and inspect the package, which includes the public documentation,
+   changelog, runtime source and license:
+
+```shell
+COVERAGE=true bundle exec rake test
+bundle exec rake build
+```
+
+The artifact is `pkg/lesli_date-<version>.gem`. Verify its specification with
+`gem specification pkg/lesli_date-<version>.gem` and publish the selected package
+with `gem push pkg/lesli_date-<version>.gem` after the release version and notes
+are finalized. Building the package does not publish it or create a Git tag.

data/docs/about/installation.md

@@ -0,0 +1,48 @@
+# Installation
+
+LesliDate provides time-zone-aware display formatting and database date expressions for Lesli Rails applications.
+
+Add the gem to the application:
+
+```shell
+bundle add lesli_date
+```
+
+## Requirements
+
+| Requirement | Supported versions / setup |
+| --- | --- |
+| Ruby | 3.3 or later |
+| ActiveSupport and ActiveRecord | 8.0.x or 8.1.x; Rails keeps their versions aligned |
+| I18n | `>= 1.6`, `< 2`; use the locale data already loaded by Rails |
+| Host configuration | `Lesli.config.datetime`, including a valid output `time_zone` |
+| SQL helpers | An established ActiveRecord connection; SQLite or PostgreSQL |
+
+The gem declares ActiveSupport, ActiveRecord and I18n as runtime dependencies.
+The application supplies its database driver (`sqlite3` or `pg`). LesliTesting,
+Rake and test database drivers are development dependencies, not requirements
+installed by this gem. CI tests Ruby 3.3.5, both supported Rails lines,
+SQLite, and PostgreSQL 17. See [Development](/gems/date/about/development).
+
+## Configuration
+
+LesliDate reads `Lesli.config.datetime`, so load and configure Lesli before constructing a formatter. A standard Lesli application already provides this configuration.
+
+All display formats come from `datetime[:formats]`, with defaults for missing
+values. Presentation uses the translations already loaded by Rails/I18n; no
+LesliDate locale files are required. See [Configuration](/gems/date/about/configuration)
+for output patterns and optional customization in Lesli.
+
+Verify the installation in a Rails console:
+
+```ruby
+LesliDate::Formatter.new(Time.current).date_time.to_s
+```
+
+The formatter accepts `Date`, `DateTime`, `Time`, `TimeWithZone`, supported
+ISO-style strings, and strings accompanied by an explicit input format. It
+returns itself from its format selectors. `get` returns a `Date` for calendar
+inputs and a `TimeWithZone` for instants. See [Parsing rules](/gems/date/api/parsing)
+for input and presentation zones, supported syntax, and validation errors.
+
+LesliDate currently generates adapter-specific database expressions for SQLite and PostgreSQL. See [Database expressions](/gems/date/api/database) before using those helpers with another adapter.

data/docs/api/database.md

@@ -0,0 +1,89 @@
+# Database expressions
+
+LesliDate generates SQL for UTC timestamps stored by Rails: ISO date-time text
+in SQLite and `timestamp without time zone` columns in PostgreSQL. These helpers
+format instants, not calendar-only `date` columns or PostgreSQL `timestamptz`.
+Use `.to_s` for calendar dates and localized presentation.
+
+## One column
+
+```ruby
+formatter = LesliDate::Formatter.new.date_time
+sql = formatter.db_column("published_at", "articles", as: "published_at_display")
+Article.select("articles.*", sql)
+```
+
+`db_column(column, table = "", as: nil)` keeps the positional column and table
+arguments. Strings and symbols are accepted. The default alias is
+`<column>_string`; `as:` customizes it. Arguments are never modified, including
+frozen strings. ActiveRecord quotes identifiers and SQL literals. Column and
+alias arguments are identifiers, not expressions; table names follow the
+adapter's native naming conventions, including PostgreSQL `schema.table`.
+Generating these SQL fragments does not execute database queries.
+
+For grouping, omit the alias explicitly instead of editing the SQL string:
+
+```ruby
+group = LesliDate::Formatter.new.date.db_column(:created_at, as: false)
+Article.group(Arel.sql(group)).order(Arel.sql("MIN(created_at) ASC")).count
+```
+
+`as: false` is the only additional option. Existing calls keep their aliases.
+
+## Timestamp columns and aliases
+
+```ruby
+sql = LesliDate::Formatter.new.date_time.db_timestamps("articles")
+Article.select("articles.*", sql)
+```
+
+Both adapters return `created_at_string` and `updated_at_string`, matching the
+aliases used by Lesli consumers. SQLite now includes `updated_at` as well.
+The previous PostgreSQL aliases `created_at_date` and `updated_at_date` are
+replaced directly; no legacy mode is retained. Consumers needing another name
+can use `db_column(:created_at, as: "created_at_date")` explicitly. SQL `NULL`
+values remain `nil`.
+
+## Supported formats
+
+The selected pattern comes from `Lesli.config.datetime[:formats]`, just as it
+does for `.to_s`, but SQL uses each database's formatting capabilities:
+
+| Adapter | Supported patterns |
+| --- | --- |
+| SQLite | Native `strftime` patterns supported by the connected SQLite version. Unsupported directives return SQL `NULL` (`nil`) when the query executes, following SQLite's native behavior. `%Y`, `%m`, `%d`, `%H`, `%M`, `%S`, and `%%` cover the common numeric formats. Month/day names such as `%B` and `%A` are unavailable. |
+| PostgreSQL | `%Y`, `%y`, `%m`, `%d`, `%B`, `%b`, `%A`, `%a`, `%j`, `%F`, `%H`, `%I`, `%p`, `%P`, `%M`, `%S`, `%R`, `%T`, and `%%`. Other directives, flags, and widths raise `InvalidFormat`. Literal text is preserved. |
+
+PostgreSQL names and AM/PM indicators use native English formatting, without
+padding month/day names. SQL does not use Rails translations or `locale:`.
+For translated words, format the value in Ruby with `.to_s`, which continues to
+use the host's existing I18n translations. SQLite-specific directives can differ
+from Ruby; use the common numeric directives when matching Ruby output matters.
+
+See the native [SQLite strftime documentation](https://www.sqlite.org/lang_datefunc.html)
+and [PostgreSQL formatting documentation](https://www.postgresql.org/docs/current/functions-formatting.html).
+
+## Supported output zones
+
+| Adapter | Zone behavior |
+| --- | --- |
+| PostgreSQL | Converts each stored UTC timestamp with the configured IANA zone, including historical offsets and daylight saving. Rails names such as `Eastern Time (US & Canada)` are converted to their IANA identifiers. The session time zone does not change the result. |
+| SQLite | Uses the configured zone's current permanent offset, including fractional hours, as a fixed offset for every row. UTC, present-day Guatemala, Kolkata and Kathmandu are examples. A zone whose current TZInfo period has an upcoming transition raises `InvalidTimeZone`; New York is an example. |
+
+SQLite cannot apply historical IANA rules. Its fixed-offset mode is intended for
+records within the zone's current permanent-offset period. Earlier records,
+such as Guatemala during its former daylight-saving years, require Ruby
+presentation or PostgreSQL. A named zone accepted today could be rejected after
+a tzdata update introduces a future transition. Prefer UTC for unrestricted
+historical SQLite data. The formatter's input value does not select an offset
+for individual database rows.
+
+## Current database time
+
+```ruby
+LesliDate::Compatibility.db_now
+```
+
+Returns `CURRENT_TIMESTAMP` for SQLite and `NOW()` otherwise, preserving the
+original two-line helper. Both are executed by the database and do not depend
+on Ruby's clock. Column formatting supports only SQLite and PostgreSQL.

data/docs/api/examples.md

@@ -0,0 +1,113 @@
+# Application examples
+
+These examples assume a Lesli application with this presentation configuration:
+
+```ruby
+config.datetime = {
+  time_zone: "America/Guatemala",
+  formats: { date: "%d/%m/%Y", date_time: "%d/%m/%Y %H:%M" }
+}
+```
+
+`Date2` can replace `LesliDate::Formatter` in applications that provide the usual
+`class Date2 < LesliDate::Formatter` subclass.
+
+## Date fields in forms
+
+An HTML date field submits `YYYY-MM-DD`. Keep the resulting calendar date when
+assigning a Rails `date` attribute:
+
+```ruby
+# params[:birthday] == "2026-10-22"
+person.birthday = LesliDate::Formatter.new(params[:birthday], "%Y-%m-%d").get
+# => Date.new(2026, 10, 22)
+```
+
+Use ISO output for the HTML field and the configured format for display:
+
+```ruby
+LesliDate::Formatter.new(person.birthday).get.iso8601 # => "2026-10-22"
+LesliDate::Formatter.new(person.birthday).date.to_s   # => "22/10/2026"
+```
+
+A `datetime-local` field has no offset. Specify its input zone when it represents
+local time, then persist the instant in UTC:
+
+```ruby
+# params[:starts_at] == "2026-10-22T08:30"
+event.starts_at = LesliDate::Formatter.new(
+  params[:starts_at], "%Y-%m-%dT%H:%M", input_zone: "America/Guatemala"
+).get.utc
+# => 2026-10-22 14:30:00 UTC
+```
+
+Handle `LesliDate::ParseError` in the application's validation flow. Native Ruby
+parsing determines accepted input; an explicit format does not add strict
+whole-string validation. See [Parsing rules](/gems/date/api/parsing).
+
+## API timestamps
+
+For an API timestamp with an explicit offset, retain the instant. Use ISO 8601
+for the machine value and the configured presentation format for display:
+
+```ruby
+formatter = LesliDate::Formatter.new("2026-10-22T14:30:45.123Z")
+
+render json: {
+  started_at: formatter.get.utc.iso8601(3),
+  started_at_display: formatter.date_time.to_s
+}
+# { "started_at": "2026-10-22T14:30:45.123Z",
+#   "started_at_display": "22/10/2026 08:30" }
+```
+
+For a calendar-date API field, use `.get.iso8601` to emit `YYYY-MM-DD`.
+`locale:` controls display words only; it does not change input parsing or ISO
+serialization. Missing or invalid inputs raise `ParseError`; the API controller
+chooses the response status and error representation.
+
+## Importing local timestamps
+
+For a CSV that supplies local Guatemala times in `DD/MM/YYYY HH:MM`, declare
+both the input pattern and its zone:
+
+```ruby
+require "csv"
+
+CSV.foreach("events.csv", headers: true) do |row|
+  timestamp = LesliDate::Formatter.new(
+    row.fetch("occurred_at"), "%d/%m/%Y %H:%M", input_zone: "America/Guatemala"
+  ).get
+
+  Event.create!(occurred_at: timestamp.utc)
+end
+```
+
+If the source already supplies UTC times, omit `input_zone:`. Explicit offsets
+in the data take precedence over that option. Rescue `ParseError` per row if the
+import should collect failures and continue; no fallback pattern is tried.
+
+## Database presentation
+
+Select display strings alongside the original UTC timestamps:
+
+```ruby
+formatter = LesliDate::Formatter.new.date_time
+events = Event.select("events.*", formatter.db_timestamps("events"))
+
+events.first.created_at_string # => "22/10/2026 08:30", for 14:30 UTC
+events.first.updated_at_string
+```
+
+Select one column with an explicit alias:
+
+```ruby
+Event.select(:id, formatter.db_column(:occurred_at, "events", as: "occurred_at_display"))
+```
+
+The helpers generate SQL without executing a query or modifying their arguments.
+Both adapters use `*_string` aliases. SQL output does not use Rails translations;
+use `.to_s` for localized words. SQLite supports fixed offsets and its native
+`strftime` directives; unsupported directives return `NULL`. PostgreSQL handles
+IANA zones per row. See [Database expressions](/gems/date/api/database) for the
+supported column types, directives and zone limits.

data/docs/api/formatter.md

@@ -0,0 +1,104 @@
+# Formatter
+
+`LesliDate::Formatter` interprets calendar dates and instants and exposes a set of display formats. Calendar dates retain their day; instants are converted to the presentation time zone.
+
+## Create a formatter
+
+```ruby
+formatter = LesliDate::Formatter.new(Time.current)
+```
+
+The constructor accepts a value, an optional positional input format, zone options, and an optional output locale:
+
+```ruby
+LesliDate::Formatter.new("2026/10/05 14:30", "%Y/%m/%d %H:%M")
+```
+
+| Argument | Default | Purpose |
+| --- | --- | --- |
+| `datetime` | `Time.current` | Date or instant to interpret; explicit `nil` is invalid |
+| `format` | `nil` | Native Ruby `strptime` pattern; otherwise use `DateTime.parse` |
+| `input_zone:` | `"UTC"` | Interpret date-time strings that have no offset |
+| `zone:` | `nil` | Presentation zone; `nil` reads `Lesli.config.datetime[:time_zone]` |
+| `locale:` | `nil` | Output language; `nil` uses `I18n.locale` when rendering |
+
+Lesli's database timestamps are UTC. The configured zone controls output;
+normal Lesli calls need no zone keywords. `input_zone:` is available for
+external sources that provide local times instead of UTC.
+
+Accepted objects are `Date`, `DateTime`, `Time`, and `ActiveSupport::TimeWithZone`.
+Strings are interpreted with Ruby's `DateTime.parse` or, when a pattern is
+provided, `DateTime.strptime`. Accepted syntax and directives follow Ruby rather
+than a separate LesliDate format language. See [Parsing rules](/gems/date/api/parsing)
+for timezone behavior and errors.
+
+```ruby
+LesliDate::Formatter.new(
+  "2026-10-22 14:30",
+  input_zone: "America/Guatemala",
+  zone: "UTC"
+).date_time.to_s
+# => "22.10.2026 20:30", with output format %d.%m.%Y %H:%M
+
+LesliDate::Formatter.new("2026-10-22").get
+# => Date.new(2026, 10, 22)
+```
+
+## Select an output format
+
+Every selector uses its matching key in `Lesli.config.datetime[:formats]`.
+Missing or `nil` values use these fallback patterns:
+
+| Method | Fallback pattern |
+| --- | --- |
+| `date` | `%d.%m.%Y` |
+| `time` | `%H:%M` |
+| `date_time` | `%d.%m.%Y %H:%M` |
+| `date_words` | `%B %d, %Y` |
+| `date_words_day` | `%A, %B %d, %Y` |
+| `date_time_words` | `%B %d, %Y, %H:%M` |
+| `date_time_words_pm` | `%B %d, %Y, %I:%M %p` |
+| `date_time_words_day` | `%A, %B %d, %Y, %H:%M` |
+
+Each selector returns the formatter:
+
+```ruby
+formatter.date_time_words.to_s
+```
+
+Selectors change the output format of the same instance. They do not parse the
+input again or replace `.get`. Input strings, temporal values and the host's
+configuration are not modified. Patterns are copied at construction, so later
+configuration edits do not change an existing formatter. `.get` exposes the
+underlying parsed value without cloning it. Use a separate formatter for
+independent selector state.
+
+`to_s` uses `I18n.localize` with the selected pattern. Days, months and AM/PM use
+the translations already loaded by Rails. LesliDate does not install or replace
+translation data. The initializer determines the pattern and the current Rails
+locale determines its translated words:
+
+```ruby
+I18n.with_locale(:es) do
+  LesliDate::Formatter.new("2026-10-22").date_words.to_s
+end
+
+LesliDate::Formatter.new("2026-10-22", locale: :es).date_words.to_s
+```
+
+`get` returns a `Date` for calendar inputs
+and an `ActiveSupport::TimeWithZone` for instants. Selecting `.date` on an instant
+does not discard its underlying time or fractional seconds.
+
+Calendar dates support `date`, `date_words`, and `date_words_day`. Selecting
+`time` or any `date_time*` format raises `LesliDate::InvalidFormat` without
+changing the previous output format.
+
+Invalid values and native parsing failures raise `LesliDate::ParseError`;
+invalid zone options raise `LesliDate::InvalidTimeZone`. `InvalidFormat` is used
+for invalid output configuration and time selectors applied to calendar dates. All inherit from
+`LesliDate::Error < ArgumentError`.
+
+See [Configuration](/gems/date/about/configuration) for defaults, validation,
+locales and optional translation overrides in Lesli.
+See [Application examples](/gems/date/api/examples) for forms, APIs and imports.

data/docs/api/index

@@ -0,0 +1,6 @@
+---
+title: API
+---
+
+<!-- This section landing page introduces the supported formatter and database compatibility APIs. -->
+<%= partial("overview") %>

data/docs/api/overview.md

@@ -0,0 +1,26 @@
+# API overview
+
+LesliDate has two public entry points:
+
+| API | Purpose |
+| --- | --- |
+| `LesliDate::Formatter` | Parse a date or time, apply the configured time zone, format it for display, or generate a formatted SQL selection |
+| `LesliDate::Compatibility.db_now` | Return the current-timestamp SQL expression for the active database adapter |
+
+A formatter is mutable: calling `date`, `time`, or another format selector changes the output format and returns the same formatter instance.
+
+```ruby
+formatter = LesliDate::Formatter.new(Time.current)
+
+formatter.date.to_s
+formatter.date_time_words.to_s
+formatter.get
+```
+
+`get` returns a `Date` for calendar inputs and an `ActiveSupport::TimeWithZone`
+for instants. Calendar dates support only date selectors; time selectors raise
+`LesliDate::InvalidFormat`.
+
+Use [Parsing rules](/gems/date/api/parsing) for accepted inputs, zones and errors,
+[Formatter](/gems/date/api/formatter) for display values, and
+[Database expressions](/gems/date/api/database) for SQL selection helpers.