@khorsheed/dsh-reader 0.2.0

package/lib/types/client/quote.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Ref-block formatting and the draft merge the conversation write needs.
+ *
+ * Both are pure and both are copies-with-intent from `@khorsheed/dsh-quote`:
+ * this plugin must NOT depend on quote (a composition may omit it), and the
+ * conversation input's `setDraft` REPLACES the whole draft, so every writer in
+ * this ecosystem has to read-merge-write. Keeping the two functions here means
+ * a change in quote cannot change this plugin's output, at the cost of a
+ * deliberate, documented duplication.
+ *
+ * @module @khorsheed/dsh-reader/client/quote
+ */
+import type { ReaderSourceSummary } from '../types.ts';
+import type { ReaderEntry } from './parse-rss.ts';
+/** The provenance line every reader ref carries. */
+export interface ReaderRefProvenance {
+    readonly title: string;
+    readonly source: string;
+    /** Publication time, when the entry declares one. */
+    readonly publishedAt?: string;
+    readonly author?: string;
+    readonly link?: string;
+}
+/**
+ * Build the provenance block for one entry.
+ *
+ * @param entry - the entry being quoted.
+ * @param source - its source, for the label.
+ * @returns the provenance.
+ */
+export declare function provenanceOf(entry: Pick<ReaderEntry, 'title' | 'author' | 'publishedAt' | 'link'>, source: Pick<ReaderSourceSummary, 'label'>): ReaderRefProvenance;
+/**
+ * Format a quote block: the quoted text, then an attribution line naming the
+ * article, its source and its link.
+ *
+ * A blockquote rather than a bare paste because the reader is a citation tool:
+ * what comes out of it has to stay traceable to the article it came from, even
+ * after the conversation has moved on.
+ *
+ * @param text - the passage (or the whole entry's summary) being quoted.
+ * @param provenance - where it came from.
+ * @returns the markdown block to insert.
+ */
+export declare function formatReaderRef(text: string, provenance: ReaderRefProvenance): string;
+/**
+ * Merge a block into the existing draft. The input's `setDraft` replaces the
+ * whole value, so an appending writer has to do the read-merge itself; a
+ * non-empty draft gets a blank line between the two.
+ *
+ * @param draft - the draft as it stands.
+ * @param block - the block to append.
+ * @returns the draft to write back.
+ */
+export declare function mergedDraft(draft: string, block: string): string;
+/**
+ * A relative "when" for a card, from a timestamp and a reference instant. The
+ * reference is a parameter so the formatting is testable without a clock.
+ *
+ * @param iso - the entry's publication timestamp.
+ * @param now - the reference instant.
+ * @returns a key plus its parameters, for the caller to translate.
+ */
+export type RelativeWhenKey = 'when.justNow' | 'when.minutes' | 'when.hours' | 'when.yesterday' | 'when.days';
+/**
+ * A relative "when" for a card, from a timestamp and a reference instant. The
+ * reference is a parameter so the formatting is testable without a clock.
+ *
+ * @param iso - the entry's publication timestamp.
+ * @param now - the reference instant.
+ * @returns a dictionary key plus its parameters, for the caller to translate.
+ */
+/**
+ * The wall-clock time of an ISO-8601 instant, in the reader's own zone.
+ *
+ * The footer states when the next scheduled refresh is due as a time of day
+ * ("每日 10:00"), because that is how the schedule itself is configured — a
+ * relative "in 14 h" would be a different number every time you look at it.
+ *
+ * @param iso - the instant.
+ * @returns `HH:MM`, or an empty string when the value is unusable.
+ */
+export declare function clockOf(iso: string | undefined): string;
+export declare function relativeWhen(iso: string | undefined, now: Date): {
+    key: RelativeWhenKey;
+    count?: number;
+};
+/** Format an ISO timestamp as a stable absolute date (detail header, title attrs). */
+export declare function absoluteDate(iso: string | undefined): string | undefined;
+//# sourceMappingURL=quote.d.ts.map

package/lib/types/client/quote.js

@@ -0,0 +1,119 @@
+/**
+ * Build the provenance block for one entry.
+ *
+ * @param entry - the entry being quoted.
+ * @param source - its source, for the label.
+ * @returns the provenance.
+ */
+export function provenanceOf(entry, source) {
+    return {
+        title: entry.title,
+        source: source.label,
+        ...(entry.publishedAt !== undefined ? { publishedAt: entry.publishedAt } : {}),
+        ...(entry.author !== undefined ? { author: entry.author } : {}),
+        ...(entry.link !== undefined ? { link: entry.link } : {}),
+    };
+}
+/**
+ * Format a quote block: the quoted text, then an attribution line naming the
+ * article, its source and its link.
+ *
+ * A blockquote rather than a bare paste because the reader is a citation tool:
+ * what comes out of it has to stay traceable to the article it came from, even
+ * after the conversation has moved on.
+ *
+ * @param text - the passage (or the whole entry's summary) being quoted.
+ * @param provenance - where it came from.
+ * @returns the markdown block to insert.
+ */
+export function formatReaderRef(text, provenance) {
+    const trimmed = text.trim();
+    const quoted = trimmed.length > 0 ? trimmed : provenance.title;
+    const quotedLines = quoted
+        .split('\n')
+        .map(line => (line.length > 0 ? `> ${line}` : '>'))
+        .join('\n');
+    const attribution = [
+        `— 《${provenance.title}》`,
+        provenance.source,
+        provenance.author,
+        provenance.publishedAt === undefined ? undefined : formatDate(provenance.publishedAt),
+    ].filter((part) => part !== undefined && part.length > 0).join(' · ');
+    const link = provenance.link === undefined ? '' : `\n${provenance.link}`;
+    return `${quotedLines}\n\n${attribution}${link}`;
+}
+/**
+ * Merge a block into the existing draft. The input's `setDraft` replaces the
+ * whole value, so an appending writer has to do the read-merge itself; a
+ * non-empty draft gets a blank line between the two.
+ *
+ * @param draft - the draft as it stands.
+ * @param block - the block to append.
+ * @returns the draft to write back.
+ */
+export function mergedDraft(draft, block) {
+    const trimmedDraft = draft.replace(/\s+$/, '');
+    return trimmedDraft.length === 0 ? block : `${trimmedDraft}\n\n${block}`;
+}
+/** A short absolute date for the attribution line. */
+function formatDate(iso) {
+    const parsed = new Date(iso);
+    if (Number.isNaN(parsed.getTime()))
+        return iso;
+    const year = parsed.getFullYear();
+    const month = `${parsed.getMonth() + 1}`.padStart(2, '0');
+    const day = `${parsed.getDate()}`.padStart(2, '0');
+    return `${year}-${month}-${day}`;
+}
+/**
+ * A relative "when" for a card, from a timestamp and a reference instant. The
+ * reference is a parameter so the formatting is testable without a clock.
+ *
+ * @param iso - the entry's publication timestamp.
+ * @param now - the reference instant.
+ * @returns a dictionary key plus its parameters, for the caller to translate.
+ */
+/**
+ * The wall-clock time of an ISO-8601 instant, in the reader's own zone.
+ *
+ * The footer states when the next scheduled refresh is due as a time of day
+ * ("每日 10:00"), because that is how the schedule itself is configured — a
+ * relative "in 14 h" would be a different number every time you look at it.
+ *
+ * @param iso - the instant.
+ * @returns `HH:MM`, or an empty string when the value is unusable.
+ */
+export function clockOf(iso) {
+    if (iso === undefined)
+        return '';
+    const at = new Date(iso);
+    if (Number.isNaN(at.getTime()))
+        return '';
+    return `${String(at.getHours()).padStart(2, '0')}:${String(at.getMinutes()).padStart(2, '0')}`;
+}
+export function relativeWhen(iso, now) {
+    if (iso === undefined)
+        return { key: 'when.justNow' };
+    const then = new Date(iso);
+    if (Number.isNaN(then.getTime()))
+        return { key: 'when.justNow' };
+    const minutes = Math.floor((now.getTime() - then.getTime()) / 60_000);
+    if (minutes < 1)
+        return { key: 'when.justNow' };
+    if (minutes < 60)
+        return { key: 'when.minutes', count: minutes };
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return { key: 'when.hours', count: hours };
+    const days = Math.floor(hours / 24);
+    if (days === 1)
+        return { key: 'when.yesterday' };
+    return { key: 'when.days', count: days };
+}
+/** Format an ISO timestamp as a stable absolute date (detail header, title attrs). */
+export function absoluteDate(iso) {
+    if (iso === undefined)
+        return undefined;
+    const parsed = new Date(iso);
+    return Number.isNaN(parsed.getTime()) ? undefined : formatDate(iso);
+}

package/lib/types/client/selectors.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Pure view selectors: the filter, the search and the sort the list applies to
+ * the parsed entries.
+ *
+ * All three are LOCAL by design (design decision D14). Entries are parsed in
+ * this process, so searching and re-sorting never costs a host round trip — and
+ * keeping them as pure functions is what makes them testable without a DOM.
+ *
+ * @module @khorsheed/dsh-reader/client/selectors
+ */
+import type { ReaderEntry } from './parse-rss.ts';
+import type { ReaderFilter, ReaderSort } from './store.ts';
+import { type ReaderEntryFetchState, type ReaderSourceKind } from '../types.ts';
+/** How many entries the pane will show before it stops rendering cards. */
+export declare const LIST_RENDER_LIMIT = 300;
+/** One entry plus the source it came from, which is what a card needs. */
+export interface ReaderRow {
+    readonly entry: ReaderEntry;
+    readonly sourceId: string;
+    readonly sourceLabel: string;
+    readonly sourceTile: string;
+    readonly sourceHue: string;
+    /** When the source was added — the time key for an entry that has no date. */
+    readonly sourceAddedAt: string;
+    /** The source kind, so a card knows whether "link only" can apply to it. */
+    readonly sourceKind: ReaderSourceKind;
+    /** True for an entry this session has not opened yet. */
+    readonly unread: boolean;
+}
+/** The per-source metadata a row needs (kept structural so the selector is pure). */
+export interface SourcePresentation {
+    readonly id: string;
+    readonly label: string;
+    readonly tile: string;
+    readonly hue: string;
+    /** The kind, so a kind query can narrow the wall without a second lookup. */
+    readonly kind: ReaderSourceKind;
+    /**
+     * When the reader added this source.
+     *
+     * A saved link has no publication date, so this is the only date it has —
+     * and the wall's time sort falls back to it. Without the fallback a
+     * freshly added link sorts as the oldest card on the wall, which is exactly
+     * where the reader who just added it does not look.
+     */
+    readonly addedAt: string;
+}
+/** Every parsed entry, flattened in source order. */
+export declare function flattenEntries(parsed: Readonly<Record<string, {
+    entries: readonly ReaderEntry[];
+}>>): ReaderEntry[];
+/**
+ * What the plugin holds for one entry, as every surface reads it.
+ *
+ * The host's annotation is the only authority (a cached body, an in-flight or
+ * stored-raw fetch, a classified failure with its reason); the pane mirrors it
+ * per entry, and this is the ONE read path into that mirror — including the
+ * default, so no surface spells "no record" as anything other than `none`.
+ *
+ * @param states - the pane's mirror of the host's fetch states.
+ * @param entryId - the entry being shown.
+ * @returns the entry's fetch state.
+ */
+export declare function fetchStateOf(states: Readonly<Record<string, ReaderEntryFetchState>>, entryId: string): ReaderEntryFetchState;
+/**
+ * Apply the filter, the query and the sort.
+ *
+ * @param entries - the parsed entries.
+ * @param sources - presentation metadata per source id.
+ * @param options - the current filter/query/sort plus the session's read cursor.
+ * @returns the rows to render, newest-first unless the sort says otherwise.
+ */
+export declare function selectRows(entries: readonly ReaderEntry[], sources: ReadonlyMap<string, SourcePresentation>, options: {
+    readonly filter: ReaderFilter;
+    readonly query: string;
+    readonly unreadOnly: boolean;
+    readonly sort: ReaderSort;
+    readonly read: Readonly<Record<string, true>>;
+    /** The reader's own tag ids per entry — the third filter dimension. */
+    readonly tags?: Readonly<Record<string, readonly string[]>>;
+    readonly now: Date;
+}): ReaderRow[];
+/**
+ * The row for one entry, when its source is still known.
+ *
+ * `selectRows` builds rows for the LIST; the detail view needs the same row for
+ * one entry it was told to reopen (a restored reading position), and rebuilding
+ * the row by hand there would be a second, drifting copy of this mapping.
+ *
+ * @param entry - the entry to present.
+ * @param sources - presentation metadata per source id.
+ * @param read - the session's read cursor.
+ * @returns the row, or `undefined` when the entry's source is gone.
+ */
+export declare function rowFor(entry: ReaderEntry, sources: ReadonlyMap<string, SourcePresentation>, read: Readonly<Record<string, true>>): ReaderRow | undefined;
+/**
+ * Whether an entry belongs in the "today" view.
+ *
+ * An entry with NO usable date is kept, not dropped. The default filter is
+ * `today`, and a saved article link carries no `publishedAt` at all — dropping
+ * undated entries would make the primary add-a-link flow produce a link the
+ * reader can never see. A date the reader cannot compare is likewise not
+ * evidence that the entry is old.
+ *
+ * @param iso - the feed-declared timestamp, when there is one.
+ * @param now - the reference day.
+ * @returns true when the entry is on that day, or carries no comparable date.
+ */
+export declare function isToday(iso: string | undefined, now: Date): boolean;
+/**
+ * The query that selects exactly one source's entries.
+ *
+ * The search box and the source strip are the same mechanism — one local
+ * predicate (D14) — so a source filter is a query the reader can also see and
+ * edit. The two-character prefix keeps it out of the way of real search terms:
+ * no title search will accidentally match it, and the id is stable across
+ * renames.
+ *
+ * @param sourceId - the source to select.
+ * @returns the query string.
+ */
+export declare function sourceQuery(sourceId: string): string;
+/**
+ * The query that selects everything carrying one tag.
+ *
+ * @param tagId - the tag to select.
+ * @returns the query string.
+ */
+export declare function tagQuery(tagId: string): string;
+/** How many of these rows are still unread. */
+export declare function countUnread(rows: readonly ReaderRow[]): number;
+/** The result of hiding duplicates behind their survivors. */
+export interface DedupedRows {
+    /** The rows to render: one per group, in the input's order. */
+    readonly rows: ReaderRow[];
+    /** Survivor entry id → the rows it hides (input order). */
+    readonly dupesBy: ReadonlyMap<string, readonly ReaderRow[]>;
+    readonly hiddenCount: number;
+}
+/**
+ * Fold duplicate rows into their survivors.
+ *
+ * Survivor choice, in order: a member whose body the host already holds
+ * (a `ready` fetch state — the fetched copy opens instantly) beats a NEWER
+ * member, and a tie keeps the input order. Same-id copies share the id-keyed
+ * fetch-state record, so between them the choice is always the input order —
+ * they share every annotation anyway. The survivor sits at its own position in
+ * the row order. Read state merges across the group: the card reads as read
+ * when ANY copy was read (free via the shared id for same-id copies). Hidden
+ * rows are reported, never deleted — the card badges them.
+ *
+ * All bookkeeping is POSITIONAL (row indexes), never id-keyed for the fold
+ * itself: two copies of one article can share ONE entry id by design, and
+ * id-keyed folding keeps both — the survivor's id is the hidden copy's id.
+ * Only the badge lookup (`dupesBy`) is id-keyed, which is safe: the surviving
+ * card is the only rendered row carrying that id.
+ *
+ * @param rows - the wall's rows (selectRows' output: filtered and sorted).
+ * @param fetchStates - the pane's fetch-state mirror, for the ready signal.
+ * @returns the rows to render, and where the hidden ones went.
+ */
+export declare function dedupeRows(rows: readonly ReaderRow[], fetchStates?: Readonly<Record<string, ReaderEntryFetchState>>): DedupedRows;
+/** A short, stable, source-derived monogram tile (design decision D11). */
+export declare function tileForSource(label: string): string;
+/** A stable hue derived from the source label, so a source keeps its colour. */
+export declare function hueForSource(label: string): string;
+//# sourceMappingURL=selectors.d.ts.map