things-api 0.6.0 → 0.8.0

package/dist/cli/commands/reads.d.ts

@@ -4,23 +4,61 @@
  */
 import type { Command } from "commander";
 import { type ThingsClient } from "../../client.ts";
-import { type ListItem } from "../../read/views.ts";
+import { type ListItem, type SidebarSection } from "../../read/views.ts";
 interface GlobalReadOpts {
     json?: boolean;
     db?: string;
 }
 export declare function withClient(opts: GlobalReadOpts, kind: string, fn: (client: ThingsClient) => unknown, render: (data: never) => string[]): void;
+export interface FormatOpts {
+    /**
+     * Render a grouped project TITLE row: bold+underlined title (the GUI's
+     * project-header look) — the circle glyph and count chip still apply.
+     */
+    projectTitle?: boolean;
+    /** Container uuids already implied by surrounding output — their context suffix is dropped. */
+    suppressProject?: string | null;
+    suppressArea?: string | null;
+    /** Reference instant for date-relative tokens (tests pin this; defaults to now). */
+    now?: Date;
+    /** Pre-styled Today/Evening mark (★/⏾), rendered right after the box — GUI position. */
+    mark?: string | null;
+    /** Dim status word after the box (the GUI's waiting/paused/ended chips on repeating templates). */
+    statusWord?: string;
+    /** Suppress the ‹date› chip (rows under a day header already carry the date). */
+    hideDateChip?: boolean;
+}
+/**
+ * One item line:
+ * `<uuid-prefix>  <box> [★|⏾] [logged-date] [‹chip›] <title> [‹n›] [⍾] [≡] [≔] (container) #tags [⚑ deadline]`.
+ * Repeating templates seat ↻ INSIDE the box (`[↻]`/`(↻)`) rather than as a
+ * separate mark; open project rows render their circle and title blue.
+ * The box is the glyph-language state carrier (../glyphs.ts): `[ ]`-family
+ * for to-dos, `( )`-family for projects — state survives with color
+ * stripped. Completed titles dim; canceled titles dim+strike (the `[×]`
+ * mark keeps the state when strike/ANSI is unavailable). Human output shows
+ * a SHORTENED uuid prefix (every command accepts unique prefixes >= 6
+ * chars); `uuidWidth` is the display length from uuidDisplayWidth — never
+ * below 8 so a copied prefix stays unique across the whole database, not
+ * just the rendered list. Tags follow the title (`#`-prefixed, green — GUI
+ * color), after the count chip (projects), notes marker, and container.
+ * Heading-nested to-dos label their parent PROJECT (via headingProject),
+ * never the heading — GUI behavior. Colors engage on a TTY only
+ * (../style.ts); `--json` always carries full uuids.
+ */
+export declare function formatItem(item: ListItem, uuidWidth?: number, opts?: FormatOpts): string;
+/**
+ * Row prefix in today-aware views: yellow ★ for Today members, cyan ⏾ for
+ * effective This-Evening members (raw evening assignment counts only while
+ * startDate is exactly today — the UI's daily expiry), null otherwise.
+ */
+export declare function todayMark(item: ListItem, now?: Date): string | null;
 /**
- * One item line: `<uuid-prefix>  <marker> [meta …] <title> (container)`.
- * Human output shows a SHORTENED uuid prefix (every command accepts unique
- * prefixes >= 6 chars); `uuidWidth` is the display length from
- * uuidDisplayWidth — never below 8 so a copied prefix stays unique across
- * the whole database, not just the rendered list. Exactly one space
- * separates every following token; meta tokens colorize on a TTY only
- * (../style.ts) — piped output stays plain. `--json` always carries full
- * uuids.
+ * Foreground the Things app on a resource via its share URI. A GUI action
+ * on this Mac — NOT headless; the shared implementation behind every
+ * `open` command. Returns the URI it launched.
  */
-export declare function formatItem(item: ListItem, uuidWidth?: number): string;
+export declare function openInThings(uuid: string): string;
 /**
  * Display width for a list's uuid column: the shortest prefix that is
  * unique WITHIN the list, floored at UUID_DISPLAY_MIN (list-local
@@ -29,5 +67,68 @@ export declare function formatItem(item: ListItem, uuidWidth?: number): string;
 export declare function uuidDisplayWidth(items: Array<{
     uuid: string;
 }>): number;
+/** Hidden-later counts per sidebar group (null area = the loose block). */
+export interface LaterHints {
+    /** Sidebar-ordered, INCLUDING groups whose every project is later. */
+    groups: Array<{
+        area: {
+            uuid: string;
+            title: string;
+        } | null;
+        hidden: number;
+    }>;
+}
+/**
+ * The sidebar mirror for `things projects`: loose projects first (the GUI
+ * lists them above the areas), then a `── ⬡ Area ──` header per area with
+ * its projects beneath (the redundant `(Area)` suffix suppressed). Items
+ * arrive from projectsView already in sidebar order — this only inserts the
+ * headers. Denser than renderSections on purpose: no title styling and no
+ * blank line per project (every row here IS a project). With `hints`,
+ * default-hidden later projects are never silent: each group trails a muted
+ * `…n later projects` count (a later-only area still gets its header), and
+ * the output ends with the flag that reveals them.
+ */
+export declare function renderProjectsSidebar(items: ListItem[], hints?: LaterHints): string[];
+/**
+ * `--until` accepting whole periods: `2024` means through Dec 31 2024,
+ * `2024-03` through Mar 31, `2024-03-05` through end of that day; relative
+ * periods (`2w`, `1m`, `1y`) count FORWARD from now through the end of the
+ * landing day; anything else parses as an instant.
+ */
+export declare function parsePeriodEnd(s: string, now?: Date): Date;
+/**
+ * `--since` accepting the same vocabulary at the period's START: `2024` =
+ * Jan 1 2024 00:00, `2024-03` = Mar 1, `2024-03-05` = that midnight;
+ * relative periods (`2w`, `1m`) count BACKWARD from now to the landing
+ * day's midnight; anything else parses as an instant.
+ */
+export declare function parsePeriodStart(s: string, now?: Date): Date;
+/**
+ * Upcoming rows under GUI-style date headers (empty periods are simply
+ * absent), with the trailing Repeating To-Dos section: templates with no
+ * set next occurrence, carrying their waiting/paused/ended status word and
+ * the bare ⚑ when the rule will assign a deadline per occurrence.
+ */
+export declare function renderUpcoming(items: ListItem[], now?: Date): string[];
+/**
+ * Logbook rows under GUI-style date headings, month granularity throughout
+ * — `── July ──` within the current year, `── March 2025 ──` beyond (finer
+ * than the GUI's bare per-year buckets, deliberately). When the row count
+ * hits the limit, a trailing note says the range is NOT exhaustive.
+ */
+export declare function renderLogbook(items: ListItem[], limit: number, now?: Date): string[];
+/**
+ * Sidebar-grouped views (anytime/someday), rendered the way the GUI reads:
+ * the area-less block headerless first, then one `── <area> ──` header per
+ * area; inside a section, loose to-dos first, then each project GROUP — a
+ * blank line, the project's bold+underlined title row, then its members.
+ * Container names implied by the grouping are not repeated on member rows
+ * (an area header covers its rows; a project title row covers the to-dos
+ * beneath it — a clustered child whose project row is absent, e.g. under a
+ * tag filter, keeps its `(project)` suffix). `star` prefixes each item line
+ * with the Today-membership mark (★, or ⏾ for This-Evening members).
+ */
+export declare function renderSections(sections: SidebarSection[], star?: boolean): string[];
 export declare function registerReadCommands(program: Command): void;
 export {};