charness 0.0.0-stage → 3.0.0

package/dist/utils/reminderScheduleText.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @description THE localized rendering of a reminder's schedule — the one text
+ * every reminder surface shows: the list row BUTTONS, the card, the created-screen,
+ * and the fire announcement `scheduler/delivery.ts` posts into the topic.
+ *
+ * It exists because `describeSchedule` (`scheduler/recurrence.ts`) cannot serve
+ * these screens: that one is English-ONLY by design (it is interpolated into i18n
+ * templates as a value), while the reminder UI exists in 12 locales. Rendering
+ * the list in the operator's language and the announcement of the SAME reminder
+ * in English would be two descriptions of one thing, so both go through here.
+ *
+ * The split of labour: `getReminderScheduleDescriptor` (pure, no i18n) decomposes
+ * the spec; this module is the ONLY place that turns a descriptor into words. It
+ * may import `t` because i18n has no env dependency — unlike `bot.ts`, whose
+ * module-scope `parseEnv()` exits the process, so it can be unit-tested directly.
+ */
+import type { ScheduleSpec } from '../scheduler/types';
+import { type ReminderScheduleDescriptor } from './reminderWizard';
+/**
+ * i18n keys the descriptor → words mapping resolves, one per descriptor kind.
+ * Collected so the set of strings the translation scope owes has a single list.
+ */
+export declare const reminderScheduleTextKeys: Readonly<Record<ReminderScheduleDescriptor['kind'], string>>;
+/**
+ * @description Render an already-decomposed descriptor as localized words. The
+ * `weekly` case reuses the weekday BUTTON label (`Sun`) rather than a second set
+ * of full weekday names: the operator picked the reminder on that button, so a
+ * different wording here would read as a different day.
+ *
+ * `raw` renders the bare cron expression verbatim — it is the honest fallback for
+ * a shape the wizard cannot create (an agent-made job, an N-times budget), and
+ * dressing it up as a plain recurring reminder would hide what it really is.
+ */
+export declare function getReminderScheduleDescriptorText(descriptor: ReminderScheduleDescriptor): string;
+/** Render a persisted spec as localized words (descriptor + {@link getReminderScheduleDescriptorText}). */
+export declare function getReminderScheduleText(spec: ScheduleSpec): string;
+/**
+ * Longest list-row BUTTON caption. This is a READABILITY bound, not an API one: the
+ * Bot API documents no maximum for a button label (the 64-BYTE cap is on
+ * `callback_data`, not on the text), while the caption must still read as one line
+ * on a phone — and the reminder NAME it carries is operator-controlled free text.
+ */
+export declare const reminderRowLabelMaxLength = 64;
+/**
+ * @description One list-row button caption: the reminder's name plus the SAME
+ * localized schedule wording its card shows, so a row and a card can never describe
+ * one reminder differently.
+ *
+ * Past the cap the NAME gives way, never the schedule: the schedule is what the row
+ * exists to communicate, whereas the name is already an excerpt of the reminder
+ * text. The overhead is measured against the ACTIVE locale (composing with an empty
+ * name) instead of assumed from the en template, so a longer translated row shrinks
+ * the name rather than blowing the budget.
+ */
+export declare function getReminderRowLabel(name: string, descriptor: ReminderScheduleDescriptor): string;
+/**
+ * @name ReminderNextRunDescriptor
+ * @description The next fire instant, decomposed for localized rendering.
+ * `today` / `tomorrow` are separate kinds rather than a formatted date because
+ * "today at 21:00" is what the operator can act on — a bare date makes them work
+ * out which day it is.
+ */
+export type ReminderNextRunDescriptor = {
+    kind: 'today';
+    time: string;
+} | {
+    kind: 'tomorrow';
+    time: string;
+} | {
+    kind: 'date';
+    dateIso: string;
+    time: string;
+};
+/**
+ * @description Decompose the next fire instant against the caller's clock. The
+ * comparison is on the local CALENDAR DATE (not an hours-apart delta), so an
+ * instant 20 hours away is "tomorrow" when it falls on the next day and "today"
+ * when it does not — which is how the operator reads it.
+ */
+export declare function getReminderNextRunDescriptor(nextRunAtMs: number, nowMs: number): ReminderNextRunDescriptor;
+/**
+ * @description Localized "Next: …" value. `null` (an exhausted / unarmed job) is
+ * rendered as the explicit none-marker rather than an empty string, so the row
+ * never looks like a failed substitution.
+ */
+export declare function getReminderNextRunText(nextRunAtMs: number | null, nowMs: number): string;
+//# sourceMappingURL=reminderScheduleText.d.ts.map

package/dist/utils/reminderScheduleText.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reminderScheduleText.d.ts","sourceRoot":"","sources":["../../src/utils/reminderScheduleText.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAOL,KAAK,0BAA0B,EAChC,MAAM,kBAAkB,CAAC;AAE1B;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,QAAQ,CAAC,MAAM,CAAC,0BAA0B,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAOjG,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,iCAAiC,CAAC,UAAU,EAAE,0BAA0B,GAAG,MAAM,CAkBhG;AAED,2GAA2G;AAC3G,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAElE;AAKD;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,0BAA0B,GAAG,MAAM,CAOhG;AAED;;;;;;GAMG;AACH,MAAM,MAAM,yBAAyB,GACjC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpD;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,yBAAyB,CAO1G;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAWxF"}

package/dist/utils/reminderScheduleText.js

@@ -0,0 +1,135 @@
+"use strict";
+/**
+ * @description THE localized rendering of a reminder's schedule — the one text
+ * every reminder surface shows: the list row BUTTONS, the card, the created-screen,
+ * and the fire announcement `scheduler/delivery.ts` posts into the topic.
+ *
+ * It exists because `describeSchedule` (`scheduler/recurrence.ts`) cannot serve
+ * these screens: that one is English-ONLY by design (it is interpolated into i18n
+ * templates as a value), while the reminder UI exists in 12 locales. Rendering
+ * the list in the operator's language and the announcement of the SAME reminder
+ * in English would be two descriptions of one thing, so both go through here.
+ *
+ * The split of labour: `getReminderScheduleDescriptor` (pure, no i18n) decomposes
+ * the spec; this module is the ONLY place that turns a descriptor into words. It
+ * may import `t` because i18n has no env dependency — unlike `bot.ts`, whose
+ * module-scope `parseEnv()` exits the process, so it can be unit-tested directly.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reminderRowLabelMaxLength = exports.reminderScheduleTextKeys = void 0;
+exports.getReminderScheduleDescriptorText = getReminderScheduleDescriptorText;
+exports.getReminderScheduleText = getReminderScheduleText;
+exports.getReminderRowLabel = getReminderRowLabel;
+exports.getReminderNextRunDescriptor = getReminderNextRunDescriptor;
+exports.getReminderNextRunText = getReminderNextRunText;
+const i18n_1 = require("../i18n");
+const reminderWizard_1 = require("./reminderWizard");
+/**
+ * i18n keys the descriptor → words mapping resolves, one per descriptor kind.
+ * Collected so the set of strings the translation scope owes has a single list.
+ */
+exports.reminderScheduleTextKeys = {
+    daily: 'reminders.scheduleDaily',
+    weekdays: 'reminders.scheduleWeekdays',
+    weekly: 'reminders.scheduleWeekly',
+    monthly: 'reminders.scheduleMonthly',
+    once: 'reminders.scheduleOnce',
+    raw: 'reminders.scheduleRaw',
+};
+/**
+ * @description Render an already-decomposed descriptor as localized words. The
+ * `weekly` case reuses the weekday BUTTON label (`Sun`) rather than a second set
+ * of full weekday names: the operator picked the reminder on that button, so a
+ * different wording here would read as a different day.
+ *
+ * `raw` renders the bare cron expression verbatim — it is the honest fallback for
+ * a shape the wizard cannot create (an agent-made job, an N-times budget), and
+ * dressing it up as a plain recurring reminder would hide what it really is.
+ */
+function getReminderScheduleDescriptorText(descriptor) {
+    const key = exports.reminderScheduleTextKeys[descriptor.kind];
+    switch (descriptor.kind) {
+        case 'daily':
+        case 'weekdays':
+            return (0, i18n_1.t)(key, { time: descriptor.time });
+        case 'weekly':
+            return (0, i18n_1.t)(key, {
+                weekday: (0, i18n_1.t)(reminderWizard_1.reminderWeekdayLabelKeys[descriptor.weekday]),
+                time: descriptor.time,
+            });
+        case 'monthly':
+            return (0, i18n_1.t)(key, { dayOfMonth: descriptor.dayOfMonth, time: descriptor.time });
+        case 'once':
+            return (0, i18n_1.t)(key, { date: descriptor.dateIso, time: descriptor.time });
+        case 'raw':
+            return (0, i18n_1.t)(key, { text: descriptor.text });
+    }
+}
+/** Render a persisted spec as localized words (descriptor + {@link getReminderScheduleDescriptorText}). */
+function getReminderScheduleText(spec) {
+    return getReminderScheduleDescriptorText((0, reminderWizard_1.getReminderScheduleDescriptor)(spec));
+}
+/** The template a list row is composed from: `🔔 {name} · {schedule}`. */
+const reminderRowLabelKey = 'reminders.listRow';
+/**
+ * Longest list-row BUTTON caption. This is a READABILITY bound, not an API one: the
+ * Bot API documents no maximum for a button label (the 64-BYTE cap is on
+ * `callback_data`, not on the text), while the caption must still read as one line
+ * on a phone — and the reminder NAME it carries is operator-controlled free text.
+ */
+exports.reminderRowLabelMaxLength = 64;
+/**
+ * @description One list-row button caption: the reminder's name plus the SAME
+ * localized schedule wording its card shows, so a row and a card can never describe
+ * one reminder differently.
+ *
+ * Past the cap the NAME gives way, never the schedule: the schedule is what the row
+ * exists to communicate, whereas the name is already an excerpt of the reminder
+ * text. The overhead is measured against the ACTIVE locale (composing with an empty
+ * name) instead of assumed from the en template, so a longer translated row shrinks
+ * the name rather than blowing the budget.
+ */
+function getReminderRowLabel(name, descriptor) {
+    const schedule = getReminderScheduleDescriptorText(descriptor);
+    const label = (0, i18n_1.t)(reminderRowLabelKey, { name, schedule });
+    if (label.length <= exports.reminderRowLabelMaxLength)
+        return label;
+    const overheadLength = (0, i18n_1.t)(reminderRowLabelKey, { name: '', schedule }).length;
+    const nameBudget = Math.max(0, exports.reminderRowLabelMaxLength - overheadLength);
+    return (0, i18n_1.t)(reminderRowLabelKey, { name: (0, reminderWizard_1.getShortenedText)(name, nameBudget), schedule });
+}
+/**
+ * @description Decompose the next fire instant against the caller's clock. The
+ * comparison is on the local CALENDAR DATE (not an hours-apart delta), so an
+ * instant 20 hours away is "tomorrow" when it falls on the next day and "today"
+ * when it does not — which is how the operator reads it.
+ */
+function getReminderNextRunDescriptor(nextRunAtMs, nowMs) {
+    const at = new Date(nextRunAtMs);
+    const time = (0, reminderWizard_1.formatReminderTime)({ hour: at.getHours(), minute: at.getMinutes() });
+    const dateIso = (0, reminderWizard_1.formatReminderDateIso)(at);
+    if (dateIso === (0, reminderWizard_1.formatReminderDateIso)((0, reminderWizard_1.getLocalDateAtDayOffset)(nowMs, 0)))
+        return { kind: 'today', time };
+    if (dateIso === (0, reminderWizard_1.formatReminderDateIso)((0, reminderWizard_1.getLocalDateAtDayOffset)(nowMs, 1)))
+        return { kind: 'tomorrow', time };
+    return { kind: 'date', dateIso, time };
+}
+/**
+ * @description Localized "Next: …" value. `null` (an exhausted / unarmed job) is
+ * rendered as the explicit none-marker rather than an empty string, so the row
+ * never looks like a failed substitution.
+ */
+function getReminderNextRunText(nextRunAtMs, nowMs) {
+    if (nextRunAtMs === null)
+        return (0, i18n_1.t)('reminders.nextRunNone');
+    const descriptor = getReminderNextRunDescriptor(nextRunAtMs, nowMs);
+    switch (descriptor.kind) {
+        case 'today':
+            return (0, i18n_1.t)('reminders.nextRunToday', { time: descriptor.time });
+        case 'tomorrow':
+            return (0, i18n_1.t)('reminders.nextRunTomorrow', { time: descriptor.time });
+        case 'date':
+            return (0, i18n_1.t)('reminders.nextRunOnDate', { date: descriptor.dateIso, time: descriptor.time });
+    }
+}
+//# sourceMappingURL=reminderScheduleText.js.map

package/dist/utils/reminderScheduleText.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reminderScheduleText.js","sourceRoot":"","sources":["../../src/utils/reminderScheduleText.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;;AAqCH,8EAkBC;AAGD,0DAEC;AAwBD,kDAOC;AAoBD,oEAOC;AAOD,wDAWC;AAtID,kCAA4B;AAE5B,qDAQ0B;AAE1B;;;GAGG;AACU,QAAA,wBAAwB,GAAiE;IACpG,KAAK,EAAE,yBAAyB;IAChC,QAAQ,EAAE,4BAA4B;IACtC,MAAM,EAAE,0BAA0B;IAClC,OAAO,EAAE,2BAA2B;IACpC,IAAI,EAAE,wBAAwB;IAC9B,GAAG,EAAE,uBAAuB;CAC7B,CAAC;AAEF;;;;;;;;;GASG;AACH,SAAgB,iCAAiC,CAAC,UAAsC;IACtF,MAAM,GAAG,GAAG,gCAAwB,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IACtD,QAAQ,UAAU,CAAC,IAAI,EAAE,CAAC;QACxB,KAAK,OAAO,CAAC;QACb,KAAK,UAAU;YACb,OAAO,IAAA,QAAC,EAAC,GAAG,EAAE,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;QAC3C,KAAK,QAAQ;YACX,OAAO,IAAA,QAAC,EAAC,GAAG,EAAE;gBACZ,OAAO,EAAE,IAAA,QAAC,EAAC,yCAAwB,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;gBACxD,IAAI,EAAE,UAAU,CAAC,IAAI;aACtB,CAAC,CAAC;QACL,KAAK,SAAS;YACZ,OAAO,IAAA,QAAC,EAAC,GAAG,EAAE,EAAE,UAAU,EAAE,UAAU,CAAC,UAAU,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;QAC9E,KAAK,MAAM;YACT,OAAO,IAAA,QAAC,EAAC,GAAG,EAAE,EAAE,IAAI,EAAE,UAAU,CAAC,OAAO,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;QACrE,KAAK,KAAK;YACR,OAAO,IAAA,QAAC,EAAC,GAAG,EAAE,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;IAC7C,CAAC;AACH,CAAC;AAED,2GAA2G;AAC3G,SAAgB,uBAAuB,CAAC,IAAkB;IACxD,OAAO,iCAAiC,CAAC,IAAA,8CAA6B,EAAC,IAAI,CAAC,CAAC,CAAC;AAChF,CAAC;AAED,0EAA0E;AAC1E,MAAM,mBAAmB,GAAG,mBAAmB,CAAC;AAEhD;;;;;GAKG;AACU,QAAA,yBAAyB,GAAG,EAAE,CAAC;AAE5C;;;;;;;;;;GAUG;AACH,SAAgB,mBAAmB,CAAC,IAAY,EAAE,UAAsC;IACtF,MAAM,QAAQ,GAAG,iCAAiC,CAAC,UAAU,CAAC,CAAC;IAC/D,MAAM,KAAK,GAAG,IAAA,QAAC,EAAC,mBAAmB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;IACzD,IAAI,KAAK,CAAC,MAAM,IAAI,iCAAyB;QAAE,OAAO,KAAK,CAAC;IAC5D,MAAM,cAAc,GAAG,IAAA,QAAC,EAAC,mBAAmB,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC;IAC7E,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,iCAAyB,GAAG,cAAc,CAAC,CAAC;IAC3E,OAAO,IAAA,QAAC,EAAC,mBAAmB,EAAE,EAAE,IAAI,EAAE,IAAA,iCAAgB,EAAC,IAAI,EAAE,UAAU,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;AACxF,CAAC;AAcD;;;;;GAKG;AACH,SAAgB,4BAA4B,CAAC,WAAmB,EAAE,KAAa;IAC7E,MAAM,EAAE,GAAG,IAAI,IAAI,CAAC,WAAW,CAAC,CAAC;IACjC,MAAM,IAAI,GAAG,IAAA,mCAAkB,EAAC,EAAE,IAAI,EAAE,EAAE,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAClF,MAAM,OAAO,GAAG,IAAA,sCAAqB,EAAC,EAAE,CAAC,CAAC;IAC1C,IAAI,OAAO,KAAK,IAAA,sCAAqB,EAAC,IAAA,wCAAuB,EAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACzG,IAAI,OAAO,KAAK,IAAA,sCAAqB,EAAC,IAAA,wCAAuB,EAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IAC5G,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AACzC,CAAC;AAED;;;;GAIG;AACH,SAAgB,sBAAsB,CAAC,WAA0B,EAAE,KAAa;IAC9E,IAAI,WAAW,KAAK,IAAI;QAAE,OAAO,IAAA,QAAC,EAAC,uBAAuB,CAAC,CAAC;IAC5D,MAAM,UAAU,GAAG,4BAA4B,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;IACpE,QAAQ,UAAU,CAAC,IAAI,EAAE,CAAC;QACxB,KAAK,OAAO;YACV,OAAO,IAAA,QAAC,EAAC,wBAAwB,EAAE,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;QAChE,KAAK,UAAU;YACb,OAAO,IAAA,QAAC,EAAC,2BAA2B,EAAE,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;QACnE,KAAK,MAAM;YACT,OAAO,IAAA,QAAC,EAAC,yBAAyB,EAAE,EAAE,IAAI,EAAE,UAAU,CAAC,OAAO,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;IAC7F,CAAC;AACH,CAAC"}