@tzslot/theme 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`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tzslot/theme",
-  "version": "0.1.0-beta.0",
+  "version": "1.0.0",
   "description": "An optional stylesheet for the tzslot components. Plain CSS, no framework.",
   "license": "MIT",
   "main": "./tzslot.css",
@@ -13,7 +13,8 @@
       "sass": "./tzslot.scss",
       "default": "./tzslot.css"
     },
-    "./tailwind.css": "./tailwind.css"
+    "./tailwind.css": "./tailwind.css",
+    "./tailwind3.css": "./tailwind3.css"
   },
   "sideEffects": [
     "*.css"
@@ -24,7 +25,7 @@
     "url": "git+https://github.com/plinthworks/tzslot.git",
     "directory": "packages/theme"
   },
-  "homepage": "https://github.com/plinthworks/tzslot#readme",
+  "homepage": "https://plinthworks.github.io/tzslot/",
   "bugs": {
     "url": "https://github.com/plinthworks/tzslot/issues"
   },

package/tailwind.css

@@ -28,9 +28,16 @@
  * nothing to do. With the class strategy (a .dark class toggled by your
  * app), the .dark rule below reaches them; add
  *
- *   :root { --tz-color-scheme: light; }
+ *   :root:not(.dark) { --tz-color-scheme: light; }
  *
  * so that no .dark means light even when the system is dark.
+ *
+ * The :not() is not decoration. `:root` and `.dark` weigh the same (0,1,0),
+ * so between two rules of equal weight the later one in the stylesheet wins —
+ * and yours is imported after this file. Written `:root`, it beats `.dark`
+ * every time and the widgets stay light inside a dark page: readable text on
+ * a light surface that is no longer there. `:root:not(.dark)` weighs (0,2,0)
+ * and says what it means whatever the order.
  */
 
 :root {

package/tailwind3.css

@@ -0,0 +1,81 @@
+/**
+ * @tzslot/theme/tailwind3.css — the widgets in your Tailwind v3 theme.
+ *
+ * In the CSS file that imports Tailwind, after it:
+ *
+ *   @import "tailwindcss/base";
+ *   @import "tailwindcss/components";
+ *   @import "tailwindcss/utilities";
+ *   @import "@tzslot/theme";
+ *   @import "@tzslot/theme/tailwind3.css";
+ *
+ * The @import form of the three Tailwind directives, not @tailwind: CSS
+ * requires @import to come first and be consecutive, and postcss-import
+ * enforces it — an @import written after an @tailwind line is refused with
+ * "@import statements must precede all other statements", and the bridge
+ * never arrives.
+ *
+ * ── Why a second file ───────────────────────────────────────────────────────
+ *
+ * v4 publishes its theme as CSS variables, so tailwind.css reads them with
+ * var(). v3 keeps its theme in JavaScript and exposes it through theme(),
+ * which is resolved at build time — the two cannot share a file.
+ *
+ * This one therefore has to go *through* Tailwind: it is PostCSS that turns
+ * theme(colors.zinc.900) into #18181b. Linked from your HTML, or imported by
+ * a bundler that does not run Tailwind's plugin over it, it reaches the
+ * browser as written and every colour is dropped. v3 says nothing when this
+ * happens — the page simply comes out unstyled.
+ *
+ * Two conditions, both silent when unmet:
+ *   1. this file is part of the stylesheet Tailwind compiles;
+ *   2. your build inlines @import (postcss-import — Vite, Next and the
+ *      Angular builder do; the tailwindcss CLI on its own does not).
+ *
+ * Neither holds? Paste the block below straight into your own CSS. It is the
+ * whole bridge; there is nothing else in this file.
+ *
+ * ── What it maps ────────────────────────────────────────────────────────────
+ *
+ *   surfaces and text  → the zinc scale
+ *   accent             → colors.primary.600 / .400 when your config has them,
+ *                        blue otherwise
+ *   danger / warning   → red / amber
+ *   font, radius       → fontFamily.sans, borderRadius.md
+ *
+ * Another grey (slate, neutral, stone…) is a matter of changing zinc below.
+ *
+ * ── Dark mode ───────────────────────────────────────────────────────────────
+ *
+ * With darkMode: 'media' (v3's default) the widgets follow the system and
+ * there is nothing to do. With darkMode: 'class' the .dark rule below reaches
+ * them, and you add
+ *
+ *   :root:not(.dark) { --tz-color-scheme: light; }
+ *
+ * so that no .dark means light even when the system is dark. The :not() is
+ * not decoration: `:root` and `.dark` weigh the same (0,1,0), so a bare
+ * `:root` written after this file wins on source order and pins the widgets
+ * to light inside a dark page.
+ */
+
+:root {
+  --tz-bg: light-dark(theme(colors.white), theme(colors.zinc.900));
+  --tz-bg-raised: light-dark(theme(colors.zinc.100), theme(colors.zinc.800));
+  --tz-fg: light-dark(theme(colors.zinc.900), theme(colors.zinc.100));
+  --tz-fg-muted: light-dark(theme(colors.zinc.600), theme(colors.zinc.400));
+  --tz-border: light-dark(theme(colors.zinc.300), theme(colors.zinc.700));
+  --tz-accent: light-dark(
+    theme(colors.primary.600, theme(colors.blue.600)),
+    theme(colors.primary.400, theme(colors.blue.400))
+  );
+  --tz-accent-fg: light-dark(theme(colors.white), theme(colors.zinc.950));
+  --tz-danger: light-dark(theme(colors.red.700), theme(colors.red.400));
+  --tz-warning: light-dark(theme(colors.amber.700), theme(colors.amber.400));
+  --tz-font: theme(fontFamily.sans);
+  --tz-radius: theme(borderRadius.md);
+}
+
+.dark {
+  --tz-color-scheme: dark;
+}