cotomy 1.0.4 → 2.0.0

package/README.md

@@ -69,7 +69,7 @@ The View layer provides thin wrappers around DOM elements and window events.
   - `enabled: boolean` (get/set) — Toggles `disabled` attribute
   - `setFocus(): void`
 - Tree traversal & manipulation
-  - `parent: CotomyElement`
+  - `parent: CotomyElement` — Returns `CotomyElement.empty()` when no parent element exists (mainly edge cases such as `html` or detached elements)
   - `parents: CotomyElement[]`
   - `children(selector = "*", type?): T[]` (direct children only)
   - `firstChild(selector = "*", type?)`
@@ -83,6 +83,8 @@ The View layer provides thin wrappers around DOM elements and window events.
   - `clone(type?): CotomyElement` - Returns a deep-cloned element, optionally typed, and reassigns a new `data-cotomy-instance` while preserving the `data-cotomy-scopeid` for scoped CSS sharing (strips `data-cotomy-moving`). Cloning an invalidated element (`data-cotomy-invalidated`) throws.
   - `clear(): this` — Removes all descendants and text
   - `remove(): void` — Explicitly non-chainable after removal
+
+> Design note: `parent` intentionally returns `CotomyElement` (non-null) for chaining and simpler usage. In typical page structures, missing parent elements are rare (mainly `html` or detached elements), and those cases are represented by `CotomyElement.empty()`.
 - Geometry & visibility
   - `visible: boolean`
   - `width: number` (get/set px)
@@ -255,8 +257,15 @@ The Form layer builds on `CotomyElement` for common form flows.
 - `mail`, `tel`, `url` — Wrap the value in a corresponding anchor tag.
 - `number` — Uses `Intl.NumberFormat` with `data-cotomy-locale`/`data-cotomy-currency` inheritance.
   - `data-cotomy-fraction-digits="2"` — Forces fixed fraction digits (sets both `minimumFractionDigits` and `maximumFractionDigits`). Works with or without `data-cotomy-currency` (e.g. `0` → `0.00`).
-- `utc` — Treats the value as UTC (or appends `Z` when missing) and formats with `data-cotomy-format` (default `YYYY/MM/DD HH:mm`).
-- `date` — Renders local dates with `data-cotomy-format` (default `YYYY/MM/DD`) when the input is a valid `Date` value.
+- `utc` — Treats the value as UTC (or appends `Z` when missing) and formats with `data-cotomy-format` (default `YYYY/MM/DD HH:mm`). By default it renders in local time; set `data-cotomy-timezone` (element or ancestor) to render in a specific IANA timezone.
+- `date` — Renders local dates with `data-cotomy-format` (default `YYYY/MM/DD`) when the input is a valid `Date` value. By default it renders in local time; set `data-cotomy-timezone` (element or ancestor) to render in a specific IANA timezone.
+
+### UTC Renderer
+
+- Supports ISO 8601 offsets (`+09:00`, `-05:00`)
+- Explicitly supports `Z` (UTC indicator)
+- Offset-less timestamps are treated as UTC (internally appends "Z" before parsing)
+- `data-cotomy-timezone` is optional. When omitted, output stays local; when set, output is converted to the specified IANA timezone (supports ancestor inheritance).
 
 Example: