@fieldia/calendar 0.0.0-stage → 0.23.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fieldia-dev
+
+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

@@ -1,3 +1,126 @@
-# Temporary Holding Version
+# @fieldia/calendar
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[Fieldia](https://fieldia.dev)'s calendar: a **list's records on a calendar**,
+by day, week or month, or as an agenda, with a column for each person or room.
+People drag a record to move it, drag its end to stretch it, press an empty
+slot to make one, and move one from the keyboard with **Move to…**. A move is
+written through the data source's `save`, with **Undo**. It shares the list's
+search, filters and favourites, reads right to left, speaks English, Arabic,
+French and German, and its code loads only when a calendar is first shown.
+
+```sh
+npm install @fieldia/calendar
+```
+
+```ts
+import { mountViewer } from '@fieldia/viewer';
+import { calendarListViews } from '@fieldia/calendar';
+
+mountViewer(host, {
+  page,
+  dataSource,
+  listViews: calendarListViews(),
+  // A slot pressed: the app opens a new record with its start and end filled in.
+  onNewRecord: (values) => openNewAppointment(values),
+});
+```
+
+With a map as well, register both: `listViews: { ...mapListViews({ provider }), ...calendarListViews() }`.
+
+## The page
+
+A list page with `calendar` offers **Calendar** beside its table:
+
+```json
+"layout": {
+  "type": "list", "id": "appointments", "columns": ["patient", "start", "doctor"],
+  "calendar": {
+    "start": "start", "end": "stop", "title": "patient",
+    "colour": "service", "resource": "doctor",
+    "views": ["day", "week", "month", "agenda"], "view": "day", "opens": "calendar",
+    "firstDay": 6, "hours": { "start": 8, "end": 20 }, "slot": 15
+  }
+}
+```
+
+| Option | What it does |
+|---|---|
+| `start` | When each record starts: a `date` (it takes the whole day) or a `datetime`. Required. |
+| `end` | When it ends, a field of the same kind. Without it a record lasts an hour (a day, for a date) and cannot be stretched. |
+| `title` | The words on each record. Required. |
+| `colour` | A field whose value colours each record: the same value, the same colour. A value that is a colour itself (`#0f766e`) is used as it is. |
+| `resource` | Who or what each record is with, a link, a choice, text or a whole number: the day view has a column for each, and a record dragged to another column changes it. |
+| `views` | The views offered, in order: `day`, `week`, `month`, `agenda`. All four unless said. |
+| `view` | The view it shows first: the first of `views` unless said. On a phone it opens on the agenda. |
+| `opens` | `calendar` opens the list on its calendar; `list` (unless said) on its table. |
+| `firstDay` | The week's first day, `0` Sunday to `6` Saturday: Saturday in Arabic, Monday in English, French and German unless said. |
+| `hours` | The hours the day and week show, `0` to `24`: 8 to 20 unless said. A record outside them stretches them. |
+| `slot` | The minutes a drag moves by and a slot holds: `15`, `30` (unless said) or `60`. |
+
+The page check refuses a field the page lacks or one of the wrong kind, an end
+of another kind than its start, a `view` that is not among `views`, and hours
+that end before they start.
+
+## What a person can do
+
+- **See** the week (days across, the hours down), the day (a column for each
+  person or room when the page names a `resource`, and one for records with
+  no one), the month in whole weeks (with "+2 more" where a day is crowded)
+  and the agenda (each day that has something, in order). Records that meet
+  sit side by side, as many as the column's width can show the start of a
+  name for; past that, "+N more" opens a list of them all. A whole day's
+  records sit in the row over the hours. A red line marks now.
+- **Move** a record by dragging it to another time, day or person, and
+  **stretch** it by dragging its lower edge. Escape while dragging or
+  stretching puts it back, and Escape while dragging across empty slots makes
+  nothing. The move is saved at once; **Undo** puts it back.
+- **Make** a record by pressing an empty slot, or dragging down across the
+  slots it should take, or with **New**. The app's `onNewRecord` gets the
+  values (start, end, person). Without it, the viewer opens the record's page
+  from `pages` in a dialog; with neither, nothing offers to make one.
+- **Open** a record by pressing it, or Enter: the app's `onOpenRecord`, as a
+  row of the table opens it.
+- **Keys**: the arrow keys move between days and slots (flipped right to
+  left), Page Up and Page Down change the week; Enter on an empty slot makes a
+  record there; on a record, Enter opens it and M (or Shift+F10) opens
+  **Move to…**, a small form for its day, its time and its person. It refuses
+  a day more than ten years from the record's own (a year typed as 26 or
+  2062), and the words after a move name the year when it changes. When the
+  record leaves the days shown, the keys stand on the step toward its day.
+  Each slot and each record says what it is to a screen reader.
+
+What cannot be done is hidden, never greyed: with no `save` on the data source,
+or a page whose start, end or person field is `readonly`, nothing moves; a
+record whose list row says `can: { edit: false }`, or puts its start, end or
+person in `can.readonlyFields` or `can.hiddenFields`, stays where it is and
+says why (`can.reason`).
+
+## The data source
+
+The calendar asks `list` for the records of the span it shows, with the list's
+own search:
+
+```ts
+filter: [...search, { field: 'start', op: '<', value: spanEnd }, { any: [{ field: 'stop', op: '>', value: spanStart }, { field: 'start', op: '>=', value: spanStart }] }]
+```
+
+A `date` is compared as `"2026-10-14"`, a `datetime` as an ISO instant
+(`toISOString()`), as the date widgets write them. Times are the reader's own;
+time zones of their own come later. A move calls `save` with the changed
+fields alone, in `changes.values` and in `values`, `fields` naming those alone
+and `partial: true` (and the row's `version`, when the list gave one), so a
+source that saves whole records keeps every other field; Undo saves what those
+fields held before, the same way. A refused save puts the record
+back and says why. In the day view, the columns of a link are the related
+records `search` finds (up to 40), with any the records hold besides.
+
+## Settings
+
+`calendarListViews({ labels, now, limit })`:
+
+- `labels`: words over the calendar's own, by language (`CalendarLabels` names them all).
+- `now`: the moment it is now, for a demo or a test pinned to a day.
+- `limit`: how many records a span asks for at most, 500 unless said. Past
+  it, the calendar says how many it leaves out.
+
+MIT licensed.

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@fieldia/calendar",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.23.0",
+  "description": "Fieldia's calendar: a list's records by day, week, month or as an agenda, a column for each person or room, moved by dragging or from the keyboard. Loaded only where a calendar is shown.",
+  "license": "MIT",
+  "homepage": "https://fieldia.dev",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "module": "./src/index.mjs",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./src/index.d.mts",
+        "require": "./src/index.d.ts"
+      },
+      "import": "./src/index.mjs",
+      "require": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@fieldia/core": "0.23.0",
+    "@fieldia/viewer": "0.23.0",
+    "@fieldia/widgets": "0.23.0",
+    "tslib": "^2.8.1"
+  },
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fieldia-dev/fieldia",
+    "directory": "libs/calendar"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ]
 }

package/src/index.d.mts

@@ -0,0 +1,3 @@
+export { calendarListViews } from './lib/list-view.mjs';
+export type { CalendarSettings } from './lib/settings.mjs';
+export type { CalendarLabels } from './lib/labels.mjs';

package/src/index.d.ts

@@ -0,0 +1,3 @@
+export { calendarListViews } from './lib/list-view';
+export type { CalendarSettings } from './lib/settings';
+export type { CalendarLabels } from './lib/labels';

package/src/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calendarListViews = void 0;
+var list_view_1 = require("./lib/list-view");
+Object.defineProperty(exports, "calendarListViews", { enumerable: true, get: function () { return list_view_1.calendarListViews; } });
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../libs/calendar/src/index.ts"],"names":[],"mappings":";;;AAAA,6CAAoD;AAA3C,8GAAA,iBAAiB,OAAA"}

package/src/index.mjs

@@ -0,0 +1,2 @@
+export { calendarListViews } from './lib/list-view.mjs';
+//# sourceMappingURL=index.mjs.map

package/src/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../../../../libs/calendar/src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC"}

package/src/lib/calendar-core.d.mts

@@ -0,0 +1,83 @@
+import type { CalendarView, ListCalendar, Locale, Page, RecordId, Values } from '@fieldia/core';
+import type { CalendarEvent, Resource } from './events.mjs';
+import type { CalendarLabels } from './labels.mjs';
+/** A column of the day or the week: a day, and a person or room when the day shows one each. */
+export interface Column {
+    day: Date;
+    resource: (Resource & {
+        label: string;
+    }) | null;
+}
+/** Where the slots' and the days' one stop is: a day, a time, a column. */
+export interface Cursor {
+    day: Date;
+    minutes: number;
+    column: number;
+}
+/** What a calendar shows now, which its drawing, its gestures, its keys and Move to… all read and set. */
+export interface CalendarState {
+    view: CalendarView;
+    /** A day in the span shown. */
+    anchor: Date;
+    cursor: Cursor;
+    /** The day's or the week's columns, as last drawn. */
+    columns: Column[];
+    /** The hours shown: the page's, stretched to the records outside them. */
+    shownHours: {
+        start: number;
+        end: number;
+    };
+    /** The people or rooms the day shows a column for; null alone when it shows none. */
+    resources: Column['resource'][];
+}
+/** How many whole lines of words a record's block of this height shows under its 2 pixels of padding: one at least. */
+export declare const linesIn: (height: number) => number;
+/** An element with its attributes (those undefined left off) and its children. */
+export type Make = <K extends keyof HTMLElementTagNameMap>(tag: K, attrs?: Record<string, string | undefined>, ...children: (Node | string)[]) => HTMLElementTagNameMap[K];
+export declare const maker: (doc: Document) => Make;
+/**
+ * One calendar as its parts in other files reach it (gestures.ts, keys.ts,
+ * move-to.ts): what it was made with, what it shows now, and what it does —
+ * draw, ask again, open, make, write a move.
+ */
+export interface CalendarCore {
+    /** Its own prefix for ids: "fd-cal-1". */
+    readonly id: string;
+    readonly doc: Document;
+    readonly element: HTMLElement;
+    /** Where the day, the week, the month or the agenda is drawn. */
+    readonly body: HTMLElement;
+    readonly page: Page;
+    readonly spec: ListCalendar;
+    readonly locale: Locale;
+    readonly labels: CalendarLabels;
+    /** The minutes a slot holds, and a drag moves by. */
+    readonly slot: number;
+    /** The pixels an hour takes in the day and the week. */
+    readonly hour: number;
+    /** The week's first day, 0 Sunday to 6 Saturday. */
+    readonly firstDay: number;
+    readonly canOpen: boolean;
+    readonly state: CalendarState;
+    readonly make: Make;
+    /** Whether the page reads right to left. */
+    rtl(): boolean;
+    /** A moment's time, as the calendar writes one: "14:30". */
+    time(d: Date): string;
+    /** The part of an event on one day; null when it has none there. */
+    segment(event: CalendarEvent, day: Date): {
+        start: Date;
+        end: Date;
+    } | null;
+    /** Minutes kept to a slot's start inside the hours shown. */
+    clampMinutes(minutes: number): number;
+    draw(): void;
+    reload(): Promise<void>;
+    open(event: CalendarEvent): void;
+    createAt(start: Date, end: Date | null, column: Column | null, wholeDay?: boolean): Promise<void>;
+    /** Write a move through the data source's save, with Undo, and say so in these words: whether it was saved. */
+    commit(event: CalendarEvent, values: Values, words: string): Promise<boolean>;
+    /** Where a record is now, for the keys to stand on: its block on that day, any of its blocks, the "+N more" that holds it, or the bar's step toward that day. */
+    place(id: RecordId, day: Date): HTMLElement;
+    openMove(event: CalendarEvent, target: HTMLElement): void;
+}

package/src/lib/calendar-core.d.ts

@@ -0,0 +1,83 @@
+import type { CalendarView, ListCalendar, Locale, Page, RecordId, Values } from '@fieldia/core';
+import type { CalendarEvent, Resource } from './events';
+import type { CalendarLabels } from './labels';
+/** A column of the day or the week: a day, and a person or room when the day shows one each. */
+export interface Column {
+    day: Date;
+    resource: (Resource & {
+        label: string;
+    }) | null;
+}
+/** Where the slots' and the days' one stop is: a day, a time, a column. */
+export interface Cursor {
+    day: Date;
+    minutes: number;
+    column: number;
+}
+/** What a calendar shows now, which its drawing, its gestures, its keys and Move to… all read and set. */
+export interface CalendarState {
+    view: CalendarView;
+    /** A day in the span shown. */
+    anchor: Date;
+    cursor: Cursor;
+    /** The day's or the week's columns, as last drawn. */
+    columns: Column[];
+    /** The hours shown: the page's, stretched to the records outside them. */
+    shownHours: {
+        start: number;
+        end: number;
+    };
+    /** The people or rooms the day shows a column for; null alone when it shows none. */
+    resources: Column['resource'][];
+}
+/** How many whole lines of words a record's block of this height shows under its 2 pixels of padding: one at least. */
+export declare const linesIn: (height: number) => number;
+/** An element with its attributes (those undefined left off) and its children. */
+export type Make = <K extends keyof HTMLElementTagNameMap>(tag: K, attrs?: Record<string, string | undefined>, ...children: (Node | string)[]) => HTMLElementTagNameMap[K];
+export declare const maker: (doc: Document) => Make;
+/**
+ * One calendar as its parts in other files reach it (gestures.ts, keys.ts,
+ * move-to.ts): what it was made with, what it shows now, and what it does —
+ * draw, ask again, open, make, write a move.
+ */
+export interface CalendarCore {
+    /** Its own prefix for ids: "fd-cal-1". */
+    readonly id: string;
+    readonly doc: Document;
+    readonly element: HTMLElement;
+    /** Where the day, the week, the month or the agenda is drawn. */
+    readonly body: HTMLElement;
+    readonly page: Page;
+    readonly spec: ListCalendar;
+    readonly locale: Locale;
+    readonly labels: CalendarLabels;
+    /** The minutes a slot holds, and a drag moves by. */
+    readonly slot: number;
+    /** The pixels an hour takes in the day and the week. */
+    readonly hour: number;
+    /** The week's first day, 0 Sunday to 6 Saturday. */
+    readonly firstDay: number;
+    readonly canOpen: boolean;
+    readonly state: CalendarState;
+    readonly make: Make;
+    /** Whether the page reads right to left. */
+    rtl(): boolean;
+    /** A moment's time, as the calendar writes one: "14:30". */
+    time(d: Date): string;
+    /** The part of an event on one day; null when it has none there. */
+    segment(event: CalendarEvent, day: Date): {
+        start: Date;
+        end: Date;
+    } | null;
+    /** Minutes kept to a slot's start inside the hours shown. */
+    clampMinutes(minutes: number): number;
+    draw(): void;
+    reload(): Promise<void>;
+    open(event: CalendarEvent): void;
+    createAt(start: Date, end: Date | null, column: Column | null, wholeDay?: boolean): Promise<void>;
+    /** Write a move through the data source's save, with Undo, and say so in these words: whether it was saved. */
+    commit(event: CalendarEvent, values: Values, words: string): Promise<boolean>;
+    /** Where a record is now, for the keys to stand on: its block on that day, any of its blocks, the "+N more" that holds it, or the bar's step toward that day. */
+    place(id: RecordId, day: Date): HTMLElement;
+    openMove(event: CalendarEvent, target: HTMLElement): void;
+}

package/src/lib/calendar-core.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.maker = exports.linesIn = void 0;
+/** A line of a record's words in the hours, in pixels: the stylesheet's line-height there (styles.ts). */
+const LINE = 16;
+/** How many whole lines of words a record's block of this height shows under its 2 pixels of padding: one at least. */
+const linesIn = (height) => Math.max(1, Math.floor((height - 2) / LINE));
+exports.linesIn = linesIn;
+const maker = (doc) => (tag, attrs = {}, ...children) => {
+    const node = doc.createElement(tag);
+    for (const [key, value] of Object.entries(attrs))
+        if (value !== undefined)
+            node.setAttribute(key, value);
+    node.append(...children);
+    return node;
+};
+exports.maker = maker;
+//# sourceMappingURL=calendar-core.js.map

package/src/lib/calendar-core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"calendar-core.js","sourceRoot":"","sources":["../../../../../libs/calendar/src/lib/calendar-core.ts"],"names":[],"mappings":";;;AA+BA,0GAA0G;AAC1G,MAAM,IAAI,GAAG,EAAE,CAAC;AAChB,uHAAuH;AAChH,MAAM,OAAO,GAAG,CAAC,MAAc,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;AAA3E,QAAA,OAAO,WAAoE;AAKjF,MAAM,KAAK,GAChB,CAAC,GAAa,EAAQ,EAAE,CACxB,CAAC,GAAG,EAAE,KAAK,GAAG,EAAE,EAAE,GAAG,QAAQ,EAAE,EAAE;IAC/B,MAAM,IAAI,GAAG,GAAG,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;IACpC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,YAAY,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACzG,IAAI,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC;IACzB,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AAPS,QAAA,KAAK,SAOd"}

package/src/lib/calendar-core.mjs

@@ -0,0 +1,13 @@
+/** A line of a record's words in the hours, in pixels: the stylesheet's line-height there (styles.ts). */
+const LINE = 16;
+/** How many whole lines of words a record's block of this height shows under its 2 pixels of padding: one at least. */
+export const linesIn = (height) => Math.max(1, Math.floor((height - 2) / LINE));
+export const maker = (doc) => (tag, attrs = {}, ...children) => {
+    const node = doc.createElement(tag);
+    for (const [key, value] of Object.entries(attrs))
+        if (value !== undefined)
+            node.setAttribute(key, value);
+    node.append(...children);
+    return node;
+};
+//# sourceMappingURL=calendar-core.mjs.map

package/src/lib/calendar-core.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"calendar-core.mjs","sourceRoot":"","sources":["../../../../../libs/calendar/src/lib/calendar-core.ts"],"names":[],"mappings":"AA+BA,0GAA0G;AAC1G,MAAM,IAAI,GAAG,EAAE,CAAC;AAChB,uHAAuH;AACvH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,MAAc,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;AAKxF,MAAM,CAAC,MAAM,KAAK,GAChB,CAAC,GAAa,EAAQ,EAAE,CACxB,CAAC,GAAG,EAAE,KAAK,GAAG,EAAE,EAAE,GAAG,QAAQ,EAAE,EAAE;IAC/B,MAAM,IAAI,GAAG,GAAG,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;IACpC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,YAAY,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACzG,IAAI,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC;IACzB,OAAO,IAAI,CAAC;AACd,CAAC,CAAC"}

package/src/lib/calendar-view.d.mts

@@ -0,0 +1,11 @@
+import type { ListViewContext, ListViewPart } from '@fieldia/viewer';
+import type { CalendarSettings } from './settings.mjs';
+/**
+ * A list's records on a calendar, for the list's switcher: the list's own
+ * search, its records by day, week or month, or as an agenda; a column for
+ * each person or room in the day view; dragged to move and stretched by
+ * their end (gestures.ts), or moved from the keyboard (keys.ts) with "Move
+ * to…" (move-to.ts), written through the data source's save with Undo; an
+ * empty slot pressed for a new record.
+ */
+export declare function calendarPart(context: ListViewContext, settings?: CalendarSettings): ListViewPart;

package/src/lib/calendar-view.d.ts

@@ -0,0 +1,11 @@
+import type { ListViewContext, ListViewPart } from '@fieldia/viewer';
+import type { CalendarSettings } from './settings';
+/**
+ * A list's records on a calendar, for the list's switcher: the list's own
+ * search, its records by day, week or month, or as an agenda; a column for
+ * each person or room in the day view; dragged to move and stretched by
+ * their end (gestures.ts), or moved from the keyboard (keys.ts) with "Move
+ * to…" (move-to.ts), written through the data source's save with Undo; an
+ * empty slot pressed for a new record.
+ */
+export declare function calendarPart(context: ListViewContext, settings?: CalendarSettings): ListViewPart;