@tzslot/angular 0.1.0-beta.0 → 1.0.0

package/README.md

@@ -19,8 +19,8 @@ what the clock faces suggest.
 |---|---|
 | `@tzslot/core` | The arithmetic. No DOM, no framework — usable on a server too. |
 | `@tzslot/dom` | Every widget, in plain DOM. Works in any framework, or none. |
-| `@tzslot/angular` | Angular components over `@tzslot/dom`: signals, forms, zoneless or not. Angular 18 to 21. |
-| `@tzslot/theme` | Optional. CSS (or Sass) setting the widgets' colours; light, dark, high contrast, a Tailwind v4 bridge. |
+| `@tzslot/angular` | Angular components over `@tzslot/dom`: signals, forms, zoneless or not. Angular 18 to 22. |
+| `@tzslot/theme` | Optional. CSS (or Sass) setting the widgets' colours; light, dark, high contrast, a bridge for Tailwind v4 and one for v3. |
 
 The widgets live in `@tzslot/dom`; a framework package only translates its own
 idioms into calls on them. A behaviour fixed there is fixed everywhere.
@@ -32,12 +32,54 @@ idioms into calls on them. A behaviour fixed there is fixed everywhere.
 | `<tz-calendar>` | `createCalendar` | a day — month and year views, keyboard, Today / Clear |
 | `<tz-multi-date>` | `createMultiDate` | several days, not necessarily adjacent |
 | `<tz-date-field>` | `createDateField` | a day, from a field that opens a panel, anchored or centred |
+| `<tz-datetime-field>` | `createDateTimeField` | a moment: the same panel with a time under the calendar — flatpickr's `enableTime`, except that it says when the time cannot happen and offers both readings when it happens twice |
+| — | `createTimeInput` | an hour and a minute on their own: arrows, wheel, up/down keys, 12- or 24-hour |
 | `<tz-date-range>` | `createDateRange` | two days, refusing a range across a closed one |
+| `<tz-range-field>` | `createRangeField` | a period in one field: named ranges, months side by side, whole days or moments |
 | `<tz-time-slots>` | `createTimeSlots` | a moment on one day: the skipped hour struck through, the repeated one offered twice |
-| `<tz-datetime-range>` | `createDateTimeRange` | an interval with a time at both ends, and the hour it hides |
+| `<tz-datetime-range>` | `createDateTimeRange` | an interval: two date-and-time fields, and the hour it hides |
 | `<tz-daily-range>` | `createDailyRange` | a range of days with the same hours on each, overnight allowed |
 
-`renderCell` puts a price, places left or your own class on any day.
+`renderCell` puts a price, places left or your own class on any day, and
+`weekNumbers` adds a column of ISO week numbers down the left.
+`timeLayout` chooses how a time is asked for: `'input'` for the compact field
+with arrows, `'select'` for two menus (`minuteStep`, every minute by default),
+`'list'` for the times on offer that day. The menus show the chosen day as the
+zone really has it: the hour the clocks skip is not offered, and the hour they
+repeat appears twice, in the words everyone uses — "02 — summer" and
+"02 — winter", "02 — été" and "02 — hiver" — so there is nothing left to ask
+afterwards. The zone's official name for each is on the tooltip. The compact field does ask, with the same names, and the
+text itself says which of the two it holds — `25/10/2026 02:30 (winter)` —
+because 02:30 looks identical either way. Typed back in, that name is read
+too, so the text always means exactly one moment.
+
+## The text in a field
+
+A field can be typed into as well as chosen from, and what it writes is what
+it reads back:
+
+```html
+<!-- the locale's own numeric form: 20/09/2026 09:15 in French -->
+<tz-datetime-field [(value)]="at" timeZone="Europe/Paris" />
+
+<!-- a pattern, when the shape matters more than the reader -->
+<tz-datetime-field format="yyyy-MM-dd HH:mm" />
+
+<!-- read-only, and then free to be written any way at all -->
+<tz-datetime-field [editable]="false" dateStyle="long" timeStyle="short" />
+<tz-datetime-field [editable]="false" [displayWith]="mine" />
+```
+
+Tokens: `yyyy yy MMMM MMM MM M dd d EEEE EEE HH H hh h mm a`, anything else
+kept as written, `'quoted'` to keep letters. Typing gets the separators as the
+figures arrive, the way a card number gets its spaces — `2009` becomes
+`20/09/` — for patterns that leave no doubt about where each part ends; pass
+`[mask]="false"` to turn that off. The pattern is never used as the
+placeholder. Text that cannot be read is
+refused rather than guessed at, and the field goes back to the last moment it
+held when you leave it. A pattern that names its month is for display only:
+"sept.", "Sept" and "septembre" are one month in three spellings, and picking
+between them is how a field stores the wrong date quietly.
 
 ## Angular
 
@@ -118,7 +160,8 @@ Nine palette colours, each `light-dark(light, dark)`. `data-theme="dark"` on
 any element themes everything inside it; `--tz-accent` on any element
 recolours the selection, the range tint and the focus ring beneath it.
 `@tzslot/theme/contrast.css` follows `prefers-contrast: more`, and
-`@tzslot/theme/tailwind.css` maps the palette to a Tailwind v4 theme. From
+`@tzslot/theme/tailwind.css` maps the palette to a Tailwind v4 theme and
+`tailwind3.css` to a v3 one. From
 Sass, `@use '@tzslot/theme/tzslot' with ($accent: …)`. All of it in
 `docs/customising.md`.