Release/2.1.0 (#10)

* chore: Update member ordering rules and PHPStan level.

* refactor: Standardize PHPDoc wording for predicate and conversion methods.

* test: Rewrite existing test suite to full BDD Given/When/Then format.

* feat: Add Precision enum and sub-second output to Instant.toIso8601.

* feat: Add LocalDate value object.

* docs: Document LocalDate and sub-second Instant precision in README.

Author: gustavofreze

.claude/rules/php-library-code-style.md

@@ -44,27 +44,45 @@ Verify every item before producing any PHP code. If any item fails, revise befor
 5. Classes follow the rules in "Inheritance and constructors". `final readonly` is the default,
    with documented exceptions for extension points and for parents that are not `readonly`.
 6. Members are ordered constants first, then constructor, then static methods, then instance
-   methods. Within each group, order by body size ascending (number of lines between `{` and `}`).
-   Constants and enum cases, which have no body, are ordered by name length ascending. This
-   ordering may be overridden only when the alternative carries explicit documentation value:
-   grouping by domain class with section markers (HTTP status codes by 1xx/2xx/3xx/etc),
-   mirroring the order of an implemented interface, or similar evident structure. The override
-   must be obvious at first reading.
+   methods. Within each group, order by **member name length ascending** (count the name only,
+   without parentheses, arguments, or return type). Constants, enum cases, and methods share
+   the same name-length-ascending rule, applied within their respective groups. This mirrors
+   the rule that governs constructor parameters and named arguments (rule 7). When two names
+   have equal length, order them alphabetically. This ordering may be overridden only when the
+   alternative carries explicit documentation value: grouping by domain class with section
+   markers (HTTP status codes by 1xx/2xx/3xx/etc), mirroring the order of an implemented
+   interface, or similar evident structure. The override must be obvious at first reading.
 
    **At call sites** (chained method calls in production code, tests, or documentation
-   examples), consecutive method invocations on the same receiver are ordered by the **visible
-   width** of each call expression ascending. The body is not visible at the call site, so the
-   visible width is the practical proxy for body size. Boolean toggles such as `->secure()` and
-   `->httpOnly()` come before parameterized `with*` builders for the same reason. When two
-   calls have equal width, order them alphabetically by method name.
+   examples), consecutive method invocations on the same receiver are ordered by **method name
+   length ascending**, the same rule that governs member declarations. Boolean toggles such as
+   `->secure()` and `->httpOnly()` come before parameterized `with*` builders because their
+   names are shorter, not because the expression is narrower. When two method names have equal
+   length, order them alphabetically.
 
    **Terminal methods that change the receiver type** stay at the end of the chain regardless
-   of width. A `build()` that returns the built value, a `commit()` that finalizes a unit of
-   work, a `send()` that flushes a request, are terminal: the chain ends with them. The
+   of name length. A `build()` that returns the built value, a `commit()` that finalizes a unit
+   of work, a `send()` that flushes a request, are terminal: the chain ends with them. The
    ordering rule applies only to consecutive calls on the same receiver type; calls that
    transition to a different type are not reorderable. The same applies in reverse to the
    factory or accessor that starts the chain (`Cookie::create(...)`, `$repository`) — it stays
    at its position.
+
+   **PHPUnit test classes** follow a dedicated sub-grouping inside the instance-methods group
+   that overrides the name-length-ascending rule:
+
+    1. **Lifecycle hooks** first, in PHPUnit execution order:
+       `setUpBeforeClass` → `setUp` → `tearDown` → `tearDownAfterClass`. Only those actually
+       defined appear; never introduce an empty hook to satisfy the rule.
+    2. **Test methods** (prefix `test`) next, ordered by name length ascending (alphabetical
+       tiebreak).
+    3. **Data providers** last, ordered by name length ascending (alphabetical tiebreak).
+
+   A method is a data provider if and only if its name appears as the string argument of a
+   `#[DataProvider('<name>')]` attribute or a `@dataProvider <name>` docblock annotation on a
+   test method in the same class. The naming convention (`*DataProvider`) is informational
+   only; the reference is the authoritative signal. A method named `*DataProvider` that no
+   test references is dead code under rule 17, not a data provider.
 7. Constructor parameters are ordered by parameter name length ascending (count the name only,
    without `$` or type), except when parameters have an implicit semantic order (for example,
    `$start/$end`, `$from/$to`, `$startAt/$endAt`), which takes precedence. Parameters with default
@@ -225,10 +243,7 @@ are `canceled` (not `cancelled`), `organization` (not `organisation`), `initiali
 
 ### When required
 
-- Every method of an interface, **including interfaces declared inside `src/Internal/`**.
-  Interfaces define contracts. The contract is documentation by definition, regardless of
-  namespace. The `Internal/` boundary applies to implementations, not to the contracts that
-  internal collaborators expose to each other.
+- Every method of an interface.
 - Every public method of a concrete class outside `src/Internal/`. Public classes are at the
   public API boundary by definition. Consumers call every public method directly, and the
   PHPDoc is the contract for each call. Trivial getters and `with*` methods are not exempt.
@@ -244,10 +259,7 @@ are `canceled` (not `cancelled`), `organization` (not `organisation`), `initiali
   interface. The interface carries the docblock.
 - Anything inside `src/Internal/`. Internal types are implementation detail and must not carry
   PHPDoc. The namespace itself is the boundary. See `php-library-architecture.md` for the
-  architectural meaning of `Internal/`. **Exception**: interfaces and their methods. An
-  interface declared inside `src/Internal/` still defines a contract, and the contract is
-  documented per `### When required` regardless of namespace. The prohibition covers concrete
-  classes, traits, enums, and anonymous classes inside `Internal/`, never interfaces.
+  architectural meaning of `Internal/`.
 - Anywhere inside `tests/`. Test methods name the scenario via the `testXxxWhenYyyGivenThenZzz`
   naming convention, and the `@Given`/`@When`/`@Then`/`@And` annotation blocks defined in
   `php-library-testing.md` describe the steps. PHPDoc documentation (summary plus
@@ -270,10 +282,7 @@ The PHPDoc prohibitions above take priority over the typed-array case. When PHPS
 
 - On a **constructor parameter** → suppress via `ignoreErrors` in `phpstan.neon.dist`. Do not
   add PHPDoc.
-- On anything inside **`src/Internal/`** (concrete classes, traits, enums) → suppress via
-  `ignoreErrors`. Do not add PHPDoc. Interfaces inside `src/Internal/` are the exception:
-  they carry PHPDoc per `### When required`, and the PHPStan errors they raise are resolved
-  through the PHPDoc, never through `ignoreErrors`.
+- On anything inside **`src/Internal/`** → suppress via `ignoreErrors`. Do not add PHPDoc.
 - On anything inside **`tests/`** → suppress via `ignoreErrors`. Do not add PHPDoc.
 - On a **public method of a public (non-Internal) class** → add full PHPDoc with summary,
   `@param` descriptions, and the typed-array information. The bare-tag form remains
@@ -338,8 +347,7 @@ public function __construct(public array $entries)
 }
 ```
 
-**Prohibited.** PHPDoc on a **concrete class** inside `src/Internal/` (the prohibition does
-not extend to interfaces; see "Correct" below for an Internal/ interface):
+**Prohibited.** PHPDoc on anything inside `src/Internal/`:
 
 ```php
 namespace TinyBlocks\Http\Internal\Client;
@@ -353,26 +361,6 @@ final readonly class Url
 }
 ```
 
-**Correct.** Interface declared **inside `src/Internal/`** still carries PHPDoc on every
-method. The Internal/ prohibition covers concrete classes; interfaces are exempt because they
-are the contract:
-
-```php
-namespace TinyBlocks\Http\Internal\Client;
-
-interface RequestResolver
-{
-    /**
-     * Resolves the given URL against the configured base URL.
-     *
-     * @param string $url The path or absolute URL to resolve.
-     * @return string The absolute URL to dispatch.
-     * @throws MalformedPath If the URL violates RFC 3986.
-     */
-    public function resolve(string $url): string;
-}
-```
-
 **Correct.** Generic array type with summary and `@param` description:
 
 ```php

.claude/rules/php-library-testing.md

@@ -36,7 +36,8 @@ Verify every item before producing any test code. If any item fails, revise befo
 4. No intermediate variables used only once. Chain method calls when the intermediate state is
    not referenced elsewhere (e.g., `Money::of(...)->add(...)` instead of
    `$money = Money::of(...)` followed by `$money->add(...)`).
-5. No private or helper methods in test classes. The only non-test methods allowed are data
+5. No private or helper methods in test classes. The only non-test methods allowed are PHPUnit
+   lifecycle hooks (`setUp`, `setUpBeforeClass`, `tearDown`, `tearDownAfterClass`) and data
    providers. Setup logic complex enough to extract belongs in a dedicated fixture class.
 6. Test only the public API. Never assert on private state or `Internal/` classes directly.
 7. Test the behavior that **raises** an exception, never the exception itself. Exception classes
@@ -69,6 +70,8 @@ Verify every item before producing any test code. If any item fails, revise befo
 15. Never use `@codeCoverageIgnore`, attributes, or configuration that exclude code from
     coverage. Never suppress mutants via `infection.json.dist` or any other mechanism. See
     "Coverage and mutation discipline".
+16. Member ordering in test classes follows `php-library-code-style.md` rule 6 (PHPUnit
+    test-class sub-grouping).
 
 ## Structure: Given/When/Then (BDD)
 

README.md

@@ -1,6 +1,6 @@
 # Time
 
-[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/tiny-blocks/time/blob/main/LICENSE)
 
 * [Overview](#overview)
 * [Installation](#installation)
@@ -13,6 +13,7 @@
         - [Adding and subtracting time](#adding-and-subtracting-time)
         - [Measuring distance between instants](#measuring-distance-between-instants)
         - [Comparing instants](#comparing-instants)
+        - [Emitting with sub-second precision](#emitting-with-sub-second-precision)
     + [Duration](#duration)
         - [Creating durations](#creating-durations)
         - [Arithmetic](#arithmetic)
@@ -37,6 +38,13 @@
         - [Comparing times](#comparing-times)
         - [Measuring distance between times](#measuring-distance-between-times)
         - [Converting to other representations](#converting-to-other-representations)
+    + [LocalDate](#localdate)
+        - [Creating from components](#creating-from-components-1)
+        - [Creating from a string](#creating-from-a-string-2)
+        - [Today in a timezone](#today-in-a-timezone)
+        - [Projecting an Instant](#projecting-an-instant)
+        - [Comparing dates](#comparing-dates)
+        - [Day arithmetic](#day-arithmetic)
     + [Timezone](#timezone)
         - [Creating from an identifier](#creating-from-an-identifier)
         - [Creating a UTC timezone](#creating-a-utc-timezone)
@@ -54,8 +62,8 @@
 
 ## Overview
 
-Models time as immutable value objects for PHP, including instants, durations, periods, timezones, time-of-day, and
-day-of-week. All instants are normalized to UTC with microsecond precision, with strict parsing, formatting, and
+Models time as immutable value objects for PHP, including instants, durations, periods, timezones, time-of-day,
+local dates, and day-of-week. All instants are normalized to UTC with microsecond precision, with strict parsing, formatting, and
 arithmetic operations. Declared as `final readonly class` for language-level immutability, with structural equality
 provided by the tiny-blocks value-object contract.
 
@@ -226,6 +234,27 @@ $later->isAfter(other: $earlier);          # true
 $later->isAfterOrEqual(other: $earlier);   # true
 ```
 
+#### Emitting with sub-second precision
+
+By default `toIso8601()` emits seconds only. Pass a `Precision` value to include fractional
+seconds in the output. Existing callers that omit the argument are unaffected.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use TinyBlocks\Time\Instant;
+use TinyBlocks\Time\Precision;
+
+$instant = Instant::fromString(value: '2026-05-23T12:55:10.272097+00:00');
+
+$instant->toIso8601();                               # 2026-05-23T12:55:10+00:00
+$instant->toIso8601(precision: Precision::Seconds);  # 2026-05-23T12:55:10+00:00
+$instant->toIso8601(precision: Precision::Microseconds); # 2026-05-23T12:55:10.272097+00:00
+$instant->toIso8601(precision: Precision::Milliseconds); # 2026-05-23T12:55:10.272+00:00
+```
+
 ### Duration
 
 A `Duration` represents an immutable, unsigned quantity of time measured in seconds. It has no reference point on the
@@ -648,6 +677,108 @@ $time->toDuration()->toSeconds(); # 30600
 $time->toString();                # 08:30
 ```
 
+### LocalDate
+
+A `LocalDate` is a value object representing a calendar date (year, month, day) without time and without timezone.
+Dates are always in the proleptic Gregorian calendar and restricted to the range `0001–9999`.
+
+#### Creating from components
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use TinyBlocks\Time\LocalDate;
+
+$date = LocalDate::of(year: 2026, month: 5, day: 23);
+
+$date->year();        # 2026
+$date->month();       # 5
+$date->dayOfMonth();  # 23
+$date->toIso8601();   # 2026-05-23
+```
+
+#### Creating from a string
+
+Accepts only the canonical ISO 8601 date format `YYYY-MM-DD`. Any other format raises `InvalidLocalDate`.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use TinyBlocks\Time\LocalDate;
+
+$date = LocalDate::fromString(value: '2026-05-23');
+
+$date->toIso8601(); # 2026-05-23
+```
+
+#### Today in a timezone
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use TinyBlocks\Time\LocalDate;
+use TinyBlocks\Time\Timezone;
+
+$today = LocalDate::today(zone: Timezone::from(identifier: 'America/Sao_Paulo'));
+
+$today->toIso8601(); # 2026-05-23
+```
+
+#### Projecting an Instant
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use TinyBlocks\Time\Instant;
+use TinyBlocks\Time\Timezone;
+
+$instant = Instant::fromString(value: '2026-05-23T12:00:00+00:00');
+$date = $instant->toLocalDate(zone: Timezone::utc());
+
+$date->toIso8601(); # 2026-05-23
+```
+
+#### Comparing dates
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use TinyBlocks\Time\LocalDate;
+
+$earlier = LocalDate::of(year: 2026, month: 1, day: 1);
+$later = LocalDate::of(year: 2026, month: 12, day: 31);
+
+$earlier->isBefore(other: $later);        # true
+$earlier->isBeforeOrEqual(other: $later); # true
+$later->isAfter(other: $earlier);         # true
+$later->isAfterOrEqual(other: $earlier);  # true
+```
+
+#### Day arithmetic
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use TinyBlocks\Time\LocalDate;
+
+$date = LocalDate::of(year: 2026, month: 5, day: 23);
+
+$date->plusDays(days: 10)->toIso8601();  # 2026-06-02
+$date->minusDays(days: 30)->toIso8601(); # 2026-04-23
+```
+
 ### Timezone
 
 A `Timezone` is a value object representing a single valid [IANA timezone](https://www.iana.org) identifier.

phpstan.neon.dist

@@ -4,6 +4,10 @@ parameters:
         - src
         - tests
     ignoreErrors:
+        # DateTimeImmutable::createFromFormat returns DateTimeImmutable|false; the UNIX format 'U' always succeeds for a valid integer, so the false branch is unreachable.
+        - identifier: method.nonObject
+          path: src/Instant.php
+
         # Property and constructor parameter are intentionally untyped; PHPDoc on constructors is prohibited per code-style rule. Suppress missing iterable value-type plus cascading return.type and argument.type errors that propagate from the untyped property.
         - identifier: missingType.iterableValue
           path: src/Timezones.php

src/Exceptions/InvalidLocalDate.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TinyBlocks\Time\Exceptions;
+
+use InvalidArgumentException;
+
+final class InvalidLocalDate extends InvalidArgumentException
+{
+    public static function becauseValueIsInvalid(string $value): InvalidLocalDate
+    {
+        $template = 'The value <%s> is not a valid local date.';
+
+        return new InvalidLocalDate(message: sprintf($template, $value));
+    }
+
+    public static function becauseComponentsAreInvalid(int $year, int $month, int $day): InvalidLocalDate
+    {
+        $template = 'Year <%d>, month <%d>, and day <%d> do not form a valid calendar date.';
+
+        return new InvalidLocalDate(message: sprintf($template, $year, $month, $day));
+    }
+}