@tzslot/angular 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Plinthworks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,152 @@
+# tzslot
+
+Date and time pickers that know what daylight saving does.
+
+Most pickers — flatpickr, Air Datepicker, nearly every Angular wrapper — are
+built on `Date`, which has no notion of an IANA time zone. They will let
+someone book 02:30 on a morning when 02:30 does not happen, or on one when it
+happens twice, and store whichever reading the browser guessed. They call a
+night shift from 23:00 to 05:00 six hours on the night it lasts seven.
+
+tzslot is built on [Temporal](https://tc39.es/proposal-temporal/docs/). It
+shows the hour that does not exist, offers both readings of the one that
+happens twice, and says in words when an interval lasts something other than
+what the clock faces suggest.
+
+## Packages
+
+| | |
+|---|---|
+| `@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. |
+
+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.
+
+## The widgets
+
+| Angular | Plain DOM | What it chooses |
+|---|---|---|
+| `<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-date-range>` | `createDateRange` | two days, refusing a range across a closed one |
+| `<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-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.
+
+## Angular
+
+```bash
+npm install @tzslot/angular @tzslot/theme
+```
+
+```jsonc
+// angular.json → build.options
+"styles": ["@tzslot/theme/tzslot.css", "src/styles.css"]
+```
+
+```ts
+import { Component, signal } from '@angular/core';
+import { Calendar, TimeSlotPicker, provideTzslotMessages, FR } from '@tzslot/angular';
+import type { Instant, PlainDate } from '@tzslot/core';
+
+@Component({
+  imports: [Calendar, TimeSlotPicker],
+  template: `
+    <tz-calendar [(value)]="day" [buttons]="['today', 'clear']" />
+    @if (day(); as d) {
+      <tz-time-slots [date]="d" timeZone="Europe/Paris" [(value)]="moment" />
+    }
+  `,
+})
+export class Booking {
+  readonly day = signal<PlainDate | null>(null);
+  readonly moment = signal<Instant | null>(null);
+}
+
+// French everywhere: bootstrapApplication(App, { providers: [provideTzslotMessages(FR)] })
+```
+
+Every component is a `ControlValueAccessor` — `formControlName`, `ngModel` and
+`[(value)]` all work — and takes `valueAs="date"` to keep an existing
+`FormControl<Date>` untouched. See `docs/migrating-from-flatpickr.md`.
+
+## Without a framework
+
+```bash
+npm install @tzslot/dom @tzslot/theme
+```
+
+```js
+import { createCalendar } from '@tzslot/dom';
+import { Temporal } from '@tzslot/core';
+import '@tzslot/theme';
+
+const calendar = createCalendar(document.querySelector('#day'), {
+  onChange: (day) => console.log(day?.toString()),
+});
+calendar.update({ min: Temporal.Now.plainDateISO() });
+```
+
+Each `create…` returns an instance with `update`, `clear` and `destroy`.
+Layout CSS is injected once; pass `injectStyles: false` under a strict
+Content-Security-Policy and include the exported `*_CSS` strings yourself.
+
+## The arithmetic
+
+```ts
+import { getDaySlots, getDailyWindows } from '@tzslot/core';
+
+getDaySlots('2026-10-25', 'Europe/Paris').filter((s) => s.time.hour === 2);
+// 02:00 is ambiguous: offsets ['+02:00', '+01:00'], two instants an hour apart
+
+getDailyWindows('2026-10-23', '2026-10-26', '22:00', '06:00', 'Europe/Paris').minutes / 60;
+// 33 — four night shifts, one of them nine hours long
+```
+
+Store an instant, never a wall time: it is unambiguous everywhere and
+survives a change of zone, of the rules, and being read back next year.
+
+## Theming
+
+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
+Sass, `@use '@tzslot/theme/tzslot' with ($accent: …)`. All of it in
+`docs/customising.md`.
+
+## Browsers
+
+Temporal is used natively where it exists and polyfilled where it does not.
+The polyfill is a static import, so a bundle carries it for every visitor —
+about 19 kB gzipped. There is deliberately no fallback to `Date`: it would
+bring back the exact bug this library exists to fix.
+
+The theme uses `light-dark()` and `color-mix()`: Chrome 123, Safari 17.5,
+Firefox 120 and later.
+
+## Development
+
+```bash
+npm install
+npm start            # playground: http://localhost:4500/playground/index.html
+npm test             # 263 tests, against real time zone rules
+npm run typecheck
+npm run build        # every package into its own dist/, ready to publish
+```
+
+The playground has a page per way of using it: Angular, Tailwind, and plain
+DOM.
+
+## Licence
+
+[MIT](LICENSE). Free to use, in personal and commercial projects alike, free
+to copy, modify and redistribute; keep the copyright notice. It comes with no
+warranty.