@octans/ui 1.6.2 → 1.7.0

package/dist/utils/date.d.ts

@@ -2,14 +2,35 @@ import { default as dayjs } from 'dayjs';
 declare function setLocale(locale: string): void;
 declare function setTimezone(timezone?: string | null): void;
 declare function getTimezone(): string | undefined;
+declare function setInputTimezone(timezone?: string | null): void;
+declare function getInputTimezone(): string | undefined;
+/**
+ * True for a value that names a DAY rather than a moment.
+ *
+ * These are deliberately left floating: no input zone applied, no display zone
+ * applied. A birthday or a MySQL `DATE` column has no time and no zone, so
+ * pinning it to one and rendering it in another moves it — `'2024-03-15'` read
+ * as UTC and shown in Los Angeles is the 14th, which is how a date of birth
+ * ends up off by a day.
+ */
+declare function isFloatingDate(value?: dayjs.ConfigType): boolean;
+/**
+ * Turns a value into an instant, using `zone` for strings that do not say.
+ *
+ * Anything that is already an instant is left alone: a `Date`, an epoch
+ * number, another dayjs object, or a string ending in `Z` or an offset. Only
+ * the naive strings are ambiguous, and only they are pinned.
+ */
+declare function parseInTimezone(value?: dayjs.ConfigType, zone?: string): dayjs.Dayjs;
 /**
  * Reads a value in the display time zone, or the viewer's clock when there
- * isn't one. `timezone` overrides the global for this one call.
+ * isn't one. `timezone` overrides the global for this one call, as does
+ * `inputTimezone` for the zone a naive string is read in.
  *
  * A zone the runtime rejects falls back rather than throwing: a date that
  * renders in the wrong zone is a bug, and a component that throws while
  * rendering is an outage.
  */
-declare function inTimezone(value?: dayjs.ConfigType, timezone?: string): dayjs.Dayjs;
+declare function inTimezone(value?: dayjs.ConfigType, timezone?: string, input?: string): dayjs.Dayjs;
 declare const mysqlFormat = "YYYY-MM-DD HH:mm:ss";
-export { dayjs, setLocale, setTimezone, getTimezone, inTimezone, mysqlFormat };
+export { dayjs, setLocale, setTimezone, getTimezone, setInputTimezone, getInputTimezone, isFloatingDate, parseInTimezone, inTimezone, mysqlFormat };

package/dist/utils/format.d.ts

@@ -9,6 +9,17 @@ export interface FormatContextInterface {
      * to be, unconditionally.
      */
     timezone?: string;
+    /**
+     * IANA time zone a date string with no zone of its own is READ in.
+     *
+     * `timezone` picks the clock a date is shown on; this picks the clock it was
+     * written on. `'2024-03-15 02:00:00'` out of a MySQL `DATETIME` names no
+     * instant by itself, so without this it is read as the viewer's local time
+     * and one stored row becomes a different moment for every reader.
+     *
+     * Defaults to the library-wide input zone set with `setInputTimezone`.
+     */
+    inputTimezone?: string;
 }
 export declare const emptyValuePlaceholder = "\u2014";
 export declare const formatters: Record<string, any>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@octans/ui",
-  "version": "1.6.2",
-  "description": "A Vue 3 component library \u2014 accessible, themeable UI primitives and application shell components.",
+  "version": "1.7.0",
+  "description": "A Vue 3 component library — accessible, themeable UI primitives and application shell components.",
   "keywords": [
     "vue",
     "vue3",

package/skills/octans-ui/SKILL.md

@@ -242,20 +242,37 @@ later:
 import { addTranslations, setTranslationLocale } from '@octans/ui'
 ```
 
-Dates have two knobs, both set once at start-up and both global:
+Dates have three knobs, all global, all settable at install
+(`app.use(UI, { locale, timezone, inputTimezone })`) or later:
 
 ```ts
-import { setLocale, setTimezone } from '@octans/ui'
+import { setLocale, setTimezone, setInputTimezone } from '@octans/ui'
 
 setLocale('fr') // formats, month names, and the day the week starts on
+setInputTimezone('UTC') // what a string with NO zone of its own means
 setTimezone('America/Los_Angeles') // what "now" is, and what zone dates render in
 ```
 
-`setTimezone` is for an app that must show ONE zone to everybody — an
-operations console pinned to head-office time — rather than each viewer's own
-clock, which is the default. It affects display only; it never reinterprets a
-stored value. `Formatter`, `Calendar` and `DatePicker` each take a `timezone`
-prop to override it for one instance.
+The two zones answer different questions and are easy to confuse:
+
+- **`setTimezone`** — the clock a date is SHOWN on. For an app that must show
+  one zone to everybody, an operations console pinned to head-office time,
+  rather than each viewer's own clock, which is the default.
+- **`setInputTimezone`** — the clock a date was WRITTEN on. A MySQL `DATETIME`
+  arrives as `2024-03-15 02:00:00`, a wall clock naming no moment, so without
+  this it is read as the reader's own local time and the same stored row means
+  a different instant in every country. Setting `setTimezone` alone does NOT
+  fix that: it converts an instant that was already wrong. Set both, or
+  neither.
+
+Neither is reactive — they are read during render, so set them before mounting
+or remount the subtree. Two things are deliberately never reinterpreted: a
+value that already names an instant (a `Z` or offset suffix, a `Date`, an epoch
+number), and a bare `2024-03-15`, which is a day rather than a moment and would
+otherwise render as the 14th west of the display zone.
+
+`Formatter` takes `timezone` and `input-timezone` props to override either for
+one instance; `Calendar` and `DatePicker` take `timezone`.
 
 ## Components