@johnhenry/temporals-viaframe 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +48 -2
- package/package.json +40 -4
- package/temporals-viaframe.viaframe-pkg.json +1393 -0
package/README.md
CHANGED
|
@@ -1,3 +1,49 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @johnhenry/temporals-viaframe
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Calendar and duration panes for [viaframe](https://viaframe.johnhenry.me), the spatial JavaScript notebook, made from [`@johnhenry/temporals`](https://github.com/johnhenry/temporals). It is a viaframe **pane package**: data, not code that runs on viaframe's page. Each pane is a function canvas that runs in viaframe's sandbox like any other pane, and nothing is fetched or sent: every pane computes its answer offline.
|
|
4
|
+
|
|
5
|
+
| Pane | What it gives |
|
|
6
|
+
| --- | --- |
|
|
7
|
+
| **Working hours** (`working-hours`) | Is a schedule open at a moment? `open`, `closesAt` while open, `nextOpen` while closed, the `wait` in milliseconds and in words (`waitWords`), and a `summary` ("closed; opens Fri 2026-11-27 09:00 (in 23 hours)"). |
|
|
8
|
+
| **Business time between** (`business-time`) | The working time between two moments: `ms`, `hours`, `words`, and how many working days the stretch touches (`businessDays`). |
|
|
9
|
+
| **Add business days** (`add-business-days`) | A date moved by a number of working days (negative goes back), its `weekday`, and the days off it skipped (`daysOff`). |
|
|
10
|
+
| **Duration in words** (`duration-words`) | Milliseconds, an ISO 8601 duration (`PT1H30M`, `P2W3D`) or shorthand (`1h 30m`) as words ("1 day, 2 hours, 3 minutes, 4 seconds", or "1d 2h 3m 4s" with `short`), with its ISO form and milliseconds. |
|
|
11
|
+
| **Relative time** (`relative-time`) | One time said relative to another ("in 2 days", "tomorrow", "1 day ago") in a locale, counting calendar days in a zone, and the time between in words. |
|
|
12
|
+
| **Next occurrences (RRULE)** (`recurrence`) | The times of an RFC 5545 rule from a start time in a zone, keeping the wall clock across daylight saving changes, with zone and in UTC. |
|
|
13
|
+
|
|
14
|
+
A schedule is a time zone (`zone`), working windows (`[["09:00", "17:00"]]`; a window that ends before it starts crosses midnight), a `weekend` (`["SA", "SU"]`, or ISO numbers 1-7) and `holidays`: `us-federal` (the 11 US federal holidays, weekend-observed), `easter`, `good-friday`, `easter-monday`, a date (`2026-12-24`, that day only), a month and day every year (`12-25`), or an object (`{ "month": 11, "weekday": "TH", "nth": 4 }`, `{ "month": 7, "day": 4, "observed": true }`, `{ "easter": -2 }`). Times are ISO times with an offset or `Z`, with a `[zone]`, or wall-clock times read in `zone`; `at`, `from` and `to` also take `now`.
|
|
15
|
+
|
|
16
|
+
Every pane returns plain data (strings, numbers, booleans, lists), so its outputs wire into any other pane, and each output is a port of its own.
|
|
17
|
+
|
|
18
|
+
## Install it in viaframe
|
|
19
|
+
|
|
20
|
+
"Pane packages…" → **Install a pane package from npm or a URL…**, and type `@johnhenry/temporals-viaframe`. viaframe asks before it reaches the CDN (jsDelivr) and shows the review: each pane's signature, code and tests ("run its tests" runs them in a sandbox of their own, with no network). After you install it, its panes are at the end of "+ add".
|
|
21
|
+
|
|
22
|
+
## How the panes carry the library
|
|
23
|
+
|
|
24
|
+
A pane package can't import a module, and its panes can't share code. Each pane's code is its own short logic, followed by one function, `temporalsLibrary()`, that holds the part of `@johnhenry/temporals` the panes use (`src/lib.ts`: working hours, business calendars and holidays, `humanizeDuration`, `formatRelative`, `parseDuration`, `recurFromString`, and an adapter that reads a pane's parameters), bundled and minified with [`temporal-polyfill`](https://github.com/fullcalendar/temporal-polyfill). The polyfill is used only where the runtime has no `Temporal` of its own. So each of the six panes carries about 85 kB of library, and the package file is about 550 kB.
|
|
25
|
+
|
|
26
|
+
## Developing
|
|
27
|
+
|
|
28
|
+
Everything is built from `src/panes.mjs` (each pane's inputs, code and tests) and `src/lib.ts`, with `viaframe-package.yaml` for the titles, descriptions and icons. The viaframe command line isn't on npm yet: set `VIAFRAME` to `bin/viaframe.mjs` in a checkout of viaframe (or put `viaframe` on the PATH). From this folder, after `npm ci` at the repository root:
|
|
29
|
+
|
|
30
|
+
```sh
|
|
31
|
+
export VIAFRAME=~/src/viaframe/bin/viaframe.mjs
|
|
32
|
+
npm run build # bundle the library, write panes/ (ignored by git), viaframe pkg pack
|
|
33
|
+
npm run check # the package file is up to date, and viaframe pkg check --strict
|
|
34
|
+
npm test # viaframe pkg test: every pane's tests in the review's sandbox
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
The repository's own `npm test` also runs every pane's tests and the adapter's (`test/viaframe-panes.test.ts`), without viaframe.
|
|
38
|
+
|
|
39
|
+
To publish: bump `version` here, `npm run build`, sign it if you have a key (`node scripts/viaframe.mjs pkg sign . --key <key file>`, then publish the key's fingerprint here), `npm run check && npm test`, then `npm publish` from this folder. Keep pane ids and input names stable across versions: canvases find a pane by package name and id, and wires by input name.
|
|
40
|
+
|
|
41
|
+
## Limitations
|
|
42
|
+
|
|
43
|
+
- English words by default. `locale` on Duration in words is used only where the runtime has `Intl.DurationFormat`; Relative time uses `Intl.RelativeTimeFormat`, which every current runtime has.
|
|
44
|
+
- Durations with years, months or weeks have no fixed length: Duration in words gives them `ms: null`, and Working hours and Business time count in hours and days only.
|
|
45
|
+
- Working hours looks for the next opening within a year (`nextOpen: null` past that). Holidays close the whole day; a half day is a window, not a holiday.
|
|
46
|
+
- Relative time says less than a day in hours ("in 3 hours"), even across midnight, as `formatRelative` does.
|
|
47
|
+
- The library's own limits apply (its README, "Scope & limitations"): proleptic Gregorian dates, ISO-calendar weeks, no leap seconds.
|
|
48
|
+
|
|
49
|
+
MIT. The bundled `temporal-polyfill` is MIT too.
|
package/package.json
CHANGED
|
@@ -1,6 +1,42 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@johnhenry/temporals-viaframe",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Calendar and duration panes for viaframe, from @johnhenry/temporals: working hours (open now? next opening), business time between two moments, adding business days over holidays, durations in words, relative time and RRULE occurrences. Offline: no network, no server.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"author": "John Henry <john@iamjohnhenry.com>",
|
|
8
|
+
"keywords": [
|
|
9
|
+
"viaframe-package",
|
|
10
|
+
"viaframe",
|
|
11
|
+
"temporal",
|
|
12
|
+
"calendar",
|
|
13
|
+
"business-hours",
|
|
14
|
+
"working-hours",
|
|
15
|
+
"holidays",
|
|
16
|
+
"duration",
|
|
17
|
+
"humanize",
|
|
18
|
+
"rrule"
|
|
19
|
+
],
|
|
20
|
+
"repository": {
|
|
21
|
+
"type": "git",
|
|
22
|
+
"url": "git+https://github.com/johnhenry/temporals.git",
|
|
23
|
+
"directory": "viaframe"
|
|
24
|
+
},
|
|
25
|
+
"homepage": "https://github.com/johnhenry/temporals/tree/main/viaframe#readme",
|
|
26
|
+
"bugs": {
|
|
27
|
+
"url": "https://github.com/johnhenry/temporals/issues"
|
|
28
|
+
},
|
|
29
|
+
"viaframe": "temporals-viaframe.viaframe-pkg.json",
|
|
30
|
+
"files": [
|
|
31
|
+
"temporals-viaframe.viaframe-pkg.json",
|
|
32
|
+
"README.md"
|
|
33
|
+
],
|
|
34
|
+
"publishConfig": {
|
|
35
|
+
"access": "public"
|
|
36
|
+
},
|
|
37
|
+
"scripts": {
|
|
38
|
+
"build": "node scripts/build.mjs",
|
|
39
|
+
"check": "node scripts/build.mjs --check && node scripts/viaframe.mjs pkg check . --strict",
|
|
40
|
+
"test": "node scripts/viaframe.mjs pkg test ."
|
|
41
|
+
}
|
|
42
|
+
}
|