tgwidget 0.1.0 → 0.1.2

package/README.md

@@ -38,13 +38,19 @@ When a user completes the widget, the result comes back via deep link `t.me/your
 ```typescript
 import { parseDate, parseColor, parseSchedule } from "tgwidget";
 
-// Date result
+// Date result — includes native Date object
 const result = parseDate("2025-03-15", { mode: "date" });
-// { date: '2025-03-15' }
+// result.date === '2025-03-15'
+// result.dateObj === Date(2025, 2, 15)
+
+// Datetime — native Date with time set
+const result = parseDate("2025-03-15_14-30", { mode: "datetime" });
+// result.dateObj — Date object with date and time
 
 // Unix timestamp
 const result = parseDate("1710460800_1718236800", { mode: "date-range", format: "unix-s" });
-// { timestamp: 1710460800, timestampEnd: 1718236800, date: '2025-03-15', ... }
+// result.dateObj, result.dateEndObj — native Date objects
+// result.timestamp === 1710460800
 
 // Color
 const result = parseColor("FF6600", { format: "hex" });
@@ -55,21 +61,84 @@ const result = parseSchedule("09001800090018000000000009001800090018000000000000
 // [{ enabled: true, start: '09:00', end: '18:00' }, ...]
 ```
 
+All parsers automatically handle Telegram bot command prefixes — you can pass raw `/start payload` strings directly:
+
+```typescript
+const result = parseDate("/start 2025-03-15", { mode: "date" });
+// result.dateObj — Date(2025, 2, 15)
+
+const result = parseColor("/start FF6600", { format: "hex" });
+// result.hex === '#FF6600'
+```
+
+### Pattern (informational format string)
+
+Each widget exposes a `.pattern` property — a human-readable format hint you can show to users:
+
+```typescript
+const widget = tgwidget("your_bot").date({ mode: "datetime" });
+widget.pattern; // "YYYY-MM-DD HH:MM"
+
+const widget2 = tgwidget("your_bot").date({ mode: "date", order: "dmy" });
+widget2.pattern; // "DD-MM-YYYY"
+
+const widget3 = tgwidget("your_bot").color({ format: "hex" });
+widget3.pattern; // "#RRGGBB"
+
+// Use in bot messages:
+await ctx.reply(`Введите дату в формате ${widget.pattern}`);
+```
+
+You can also use the standalone `getPattern(widget, payload)` function directly.
+
+### Widget-level parsing with `parse()`
+
+If you keep a reference to the widget builder, you can call `.parse()` directly — it automatically uses the configured widget type and options. The return type is inferred from the widget type:
+
+```typescript
+const widget = tgwidget("your_bot").date({ mode: "datetime" });
+const url = widget.url();
+
+// Later, when the user completes the widget:
+const result = widget.parse("/start 2025-03-15_14-30");
+// result is DateResult (type-safe!)
+// result.dateObj — native Date object
+```
+
 ## API
 
 ### `tgwidget(botUsername)`
 
 Create a widget builder. Returns a chainable `TgWidget` instance.
 
-- `.date({ mode?, format?, order? })` — Date/time picker
-- `.color({ format? })` — Color picker
-- `.schedule()` — Weekly schedule
+- `.date({ mode?, format?, order? })` — Date/time picker → `TgWidget<"date">`
+- `.color({ format? })` — Color picker → `TgWidget<"color">`
+- `.schedule()` — Weekly schedule → `TgWidget<"schedule">`
 - `.style({ colorScheme?, accent?, tint?, liquidGlass?, adaptTgTheme?, adoptTgPalette? })` — Styling
 - `.url(baseUrl?)` — Generate the final URL
 - `.payload()` — Get the raw payload object
+- `.pattern` — Human-readable format string (e.g. `"YYYY-MM-DD HH:MM"`)
+- `.parse(value)` — Parse a widget result string (return type matches widget type)
 
 ### Parsers
 
 - `parseDate(value, { mode?, format?, order? })` → `DateResult`
 - `parseColor(value, { format? })` → `ColorResult`
 - `parseSchedule(value)` → `ScheduleDay[]`
+
+### Result types
+
+#### `DateResult`
+- `date`, `time`, `dateEnd`, `timeEnd` — string representations
+- `timestamp`, `timestampEnd` — raw integer timestamps (unix modes)
+- `dateObj`, `dateEndObj` — native `Date` objects
+
+#### `ColorResult`
+- `raw` — original value string
+- `hex` — e.g. `'#FF6600'`
+- `rgb` — e.g. `[255, 102, 0]`
+- `hsl` — e.g. `[24, 100, 50]`
+
+#### `ScheduleDay`
+- `enabled` — whether the day is active
+- `start`, `end` — time strings e.g. `'09:00'`

package/dist/builder.d.ts

@@ -1,5 +1,5 @@
-import type { DateMode, DateFormat, DateOrder, ColorFormat, ColorScheme } from "./types";
-export declare class TgWidget {
+import type { DateMode, DateFormat, DateOrder, ColorFormat, ColorScheme, WidgetType, ParseResult } from "./types";
+export declare class TgWidget<T extends WidgetType | null = null> {
     private _botUsername;
     private _widget;
     private _payload;
@@ -9,11 +9,11 @@ export declare class TgWidget {
         mode?: DateMode;
         format?: DateFormat;
         order?: DateOrder;
-    }): this;
+    }): TgWidget<"date">;
     color(opts?: {
         format?: ColorFormat;
-    }): this;
-    schedule(): this;
+    }): TgWidget<"color">;
+    schedule(): TgWidget<"schedule">;
     style(opts?: {
         colorScheme?: ColorScheme;
         accent?: string;
@@ -25,5 +25,7 @@ export declare class TgWidget {
     private _buildPayload;
     url(baseUrl?: string): string;
     payload(): Record<string, unknown>;
+    get pattern(): string;
+    parse(value: string): ParseResult<T>;
 }
 export declare function tgwidget(botUsername: string): TgWidget;

package/dist/builder.js

@@ -1,3 +1,5 @@
+import { parseDate, parseColor, parseSchedule } from "./parser";
+import { getPattern } from "./pattern";
 const BASE_URL = "https://tgwidget.github.io/";
 const HEX_RE = /^#?[0-9A-Fa-f]{6}$/;
 const VALID_DATE_MODES = new Set(["date", "time", "datetime", "date-range", "time-range"]);
@@ -83,6 +85,23 @@ export class TgWidget {
     payload() {
         return this._buildPayload();
     }
+    get pattern() {
+        if (!this._widget)
+            throw new Error("No widget type set. Call .date(), .color(), or .schedule() first.");
+        return getPattern(this._widget, this._payload);
+    }
+    parse(value) {
+        if (this._widget === "date") {
+            return parseDate(value, this._payload);
+        }
+        if (this._widget === "color") {
+            return parseColor(value, this._payload);
+        }
+        if (this._widget === "schedule") {
+            return parseSchedule(value);
+        }
+        throw new Error("No widget type set. Call .date(), .color(), or .schedule() first.");
+    }
 }
 export function tgwidget(botUsername) {
     return new TgWidget(botUsername);

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export { tgwidget, TgWidget } from "./builder";
 export { parseDate, parseColor, parseSchedule } from "./parser";
-export type { DateMode, DateFormat, DateOrder, ColorFormat, ColorScheme, WidgetStyle, DateResult, ColorResult, ScheduleDay, } from "./types";
+export { getPattern } from "./pattern";
+export type { DateMode, DateFormat, DateOrder, ColorFormat, ColorScheme, WidgetType, WidgetStyle, DateResult, ColorResult, ScheduleDay, ParseResult, } from "./types";

package/dist/index.js

@@ -1,2 +1,3 @@
 export { tgwidget, TgWidget } from "./builder";
 export { parseDate, parseColor, parseSchedule } from "./parser";
+export { getPattern } from "./pattern";

package/dist/parser.js

@@ -1,3 +1,11 @@
+function stripCommand(value) {
+    if (value.startsWith("/")) {
+        const idx = value.indexOf(" ");
+        if (idx !== -1)
+            return value.slice(idx + 1);
+    }
+    return value;
+}
 function parseDateStr(value, order) {
     const parts = value.split("-");
     if (order === "ymd")
@@ -6,7 +14,12 @@ function parseDateStr(value, order) {
         return `${parts[2]}-${parts[1]}-${parts[0]}`;
     return `${parts[2]}-${parts[0]}-${parts[1]}`; // mdy
 }
+function dateFromYmd(ymdStr) {
+    const [y, m, d] = ymdStr.split("-").map(Number);
+    return new Date(y, m - 1, d);
+}
 export function parseDate(value, opts = {}) {
+    value = stripCommand(value);
     const { mode = "date", format = "default", order = "ymd" } = opts;
     const result = {};
     if (format === "unix-s" || format === "unix-ms") {
@@ -15,21 +28,26 @@ export function parseDate(value, opts = {}) {
         const ts = parseInt(parts[0], 10);
         result.timestamp = ts;
         const dt = new Date(ts * mul);
+        result.dateObj = dt;
         result.date = dt.toISOString().slice(0, 10);
         result.time = dt.toISOString().slice(11, 16);
         if (parts.length > 1) {
             const tsEnd = parseInt(parts[1], 10);
             result.timestampEnd = tsEnd;
             const dtEnd = new Date(tsEnd * mul);
+            result.dateEndObj = dtEnd;
             result.dateEnd = dtEnd.toISOString().slice(0, 10);
             result.timeEnd = dtEnd.toISOString().slice(11, 16);
         }
         return result;
     }
     switch (mode) {
-        case "date":
-            result.date = parseDateStr(value, order);
+        case "date": {
+            const dateStr = parseDateStr(value, order);
+            result.date = dateStr;
+            result.dateObj = dateFromYmd(dateStr);
             break;
+        }
         case "time": {
             const [h, m] = value.split("-");
             result.time = `${h}:${m}`;
@@ -37,15 +55,23 @@ export function parseDate(value, opts = {}) {
         }
         case "datetime": {
             const [datePart, timePart] = value.split("_");
-            result.date = parseDateStr(datePart, order);
+            const dateStr = parseDateStr(datePart, order);
             const [h, m] = timePart.split("-");
+            result.date = dateStr;
             result.time = `${h}:${m}`;
+            const d = dateFromYmd(dateStr);
+            d.setHours(parseInt(h, 10), parseInt(m, 10), 0, 0);
+            result.dateObj = d;
             break;
         }
         case "date-range": {
             const parts = value.split("_");
-            result.date = parseDateStr(parts[0], order);
-            result.dateEnd = parseDateStr(parts[1], order);
+            const dateStr = parseDateStr(parts[0], order);
+            const dateEndStr = parseDateStr(parts[1], order);
+            result.date = dateStr;
+            result.dateEnd = dateEndStr;
+            result.dateObj = dateFromYmd(dateStr);
+            result.dateEndObj = dateFromYmd(dateEndStr);
             break;
         }
         case "time-range": {
@@ -60,6 +86,7 @@ export function parseDate(value, opts = {}) {
     return result;
 }
 export function parseColor(value, opts = {}) {
+    value = stripCommand(value);
     const { format = "hex" } = opts;
     const result = { raw: value };
     if (format === "hex") {
@@ -76,6 +103,7 @@ export function parseColor(value, opts = {}) {
     return result;
 }
 export function parseSchedule(value) {
+    value = stripCommand(value);
     if (value.length !== 56) {
         throw new Error(`Schedule bunch format must be 56 chars, got ${value.length}`);
     }

package/dist/pattern.d.ts

@@ -0,0 +1,2 @@
+import type { WidgetType } from "./types";
+export declare function getPattern(widget: WidgetType, payload: Record<string, unknown>): string;

package/dist/pattern.js

@@ -0,0 +1,40 @@
+const DATE_PATTERNS = {
+    ymd: "YYYY-MM-DD",
+    dmy: "DD-MM-YYYY",
+    mdy: "MM-DD-YYYY",
+};
+const TIME_PATTERN = "HH-MM";
+export function getPattern(widget, payload) {
+    if (widget === "date") {
+        const mode = payload.mode ?? "date";
+        const order = payload.order ?? "ymd";
+        const datePat = DATE_PATTERNS[order];
+        switch (mode) {
+            case "date":
+                return datePat;
+            case "time":
+                return TIME_PATTERN;
+            case "datetime":
+                return `${datePat}_${TIME_PATTERN}`;
+            case "date-range":
+                return `${datePat}_${datePat}`;
+            case "time-range":
+                return `${TIME_PATTERN}_${TIME_PATTERN}`;
+        }
+    }
+    if (widget === "color") {
+        const format = payload.format ?? "hex";
+        switch (format) {
+            case "hex":
+                return "#RRGGBB";
+            case "rgb":
+                return "R, G, B";
+            case "hsl":
+                return "H, S, L";
+        }
+    }
+    if (widget === "schedule") {
+        return "HH:MM—HH:MM × 7 days";
+    }
+    return "";
+}

package/dist/types.d.ts

@@ -3,6 +3,7 @@ export type DateFormat = "default" | "unix-s" | "unix-ms";
 export type DateOrder = "ymd" | "dmy" | "mdy";
 export type ColorFormat = "hex" | "rgb" | "hsl";
 export type ColorScheme = "light" | "dark" | "auto";
+export type WidgetType = "date" | "color" | "schedule";
 export interface WidgetStyle {
     colorScheme?: ColorScheme;
     accent?: string;
@@ -18,6 +19,8 @@ export interface DateResult {
     timeEnd?: string;
     timestamp?: number;
     timestampEnd?: number;
+    dateObj?: Date;
+    dateEndObj?: Date;
 }
 export interface ColorResult {
     raw: string;
@@ -30,3 +33,4 @@ export interface ScheduleDay {
     start?: string;
     end?: string;
 }
+export type ParseResult<T extends WidgetType | null> = T extends "date" ? DateResult : T extends "color" ? ColorResult : T extends "schedule" ? ScheduleDay[] : DateResult | ColorResult | ScheduleDay[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tgwidget",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Node.js SDK for TeleWidget — Telegram Mini App widgets",
   "type": "module",
   "main": "./dist/index.js",