@mushi-mushi/core 1.28.0 → 1.30.0

package/dist/reporter-ui.d.cts

@@ -0,0 +1,131 @@
+/**
+ * FILE: reporter-ui.ts
+ * PURPOSE: The one reporter-facing vocabulary shared by every SDK widget
+ *          (web, React Native, Capacitor): report categories, the end-user
+ *          status table, the timeline kinds and their copy in en/ja/es/th.
+ *
+ * OVERVIEW:
+ * - `reporterStatus(report, locale)` maps all 14 internal `reports.status`
+ *   values (plus the `awaiting_reporter` and duplicate-group overlays and the
+ *   feature-request variants) onto eight end-user states. There is no branch
+ *   that echoes the raw status: an unknown value reads as "Received".
+ * - `reporterTimelineText(kind, params, locale)` renders pipeline events from
+ *   a fixed template per kind. Stored notification payload text is never
+ *   shown, so internal category / severity can not leak to a reporter.
+ *
+ * USAGE:
+ * - `import { reporterStatus } from '@mushi-mushi/core/reporter-ui'`
+ * - Shipped as a subpath so the main `@mushi-mushi/core` entry stays within
+ *   its size budget; nothing here is re-exported from `index.ts`.
+ *
+ * Plan 018 (docs/execplans/reporter-loop-v2.md) §2.1 and §2.3.
+ */
+/** Every value `reports_status_check` allows. Pinned to the server list by a test. */
+declare const REPORTER_CANONICAL_STATUSES: readonly ["new", "pending", "submitted", "queued", "classified", "grouped", "fixing", "fixed", "dismissed", "triaged", "in_progress", "resolved", "verified", "reopened"];
+type ReporterCanonicalStatus = (typeof REPORTER_CANONICAL_STATUSES)[number];
+declare const REPORTER_LOCALES: readonly ["en", "ja", "es", "th"];
+type ReporterLocale = (typeof REPORTER_LOCALES)[number];
+/** Optional type chips on the one-screen report form, in display order. */
+declare const REPORTER_CATEGORIES: readonly ["bug", "slow", "visual", "confusing", "idea"];
+type ReporterCategory = (typeof REPORTER_CATEGORIES)[number];
+/** `closed_reason` values the `reports_closed_reason_check` constraint allows. */
+declare const REPORTER_CLOSED_REASONS: readonly ["duplicate", "not_reproducible", "wont_fix", "working_as_intended", "spam"];
+type ReporterClosedReason = (typeof REPORTER_CLOSED_REASONS)[number];
+type ReporterTone = 'neutral' | 'info' | 'attention' | 'progress' | 'success' | 'success-muted' | 'muted';
+/** The end-user state a report is shown in. */
+type ReporterStatusKey = 'received' | 'reviewing' | 'reviewing_again' | 'fixing' | 'verified' | 'fixed_next' | 'fixed_version' | 'fixed' | 'closed' | 'waiting';
+/** Timeline entry kinds the reporter detail view renders (§2.3). */
+declare const REPORTER_TIMELINE_KINDS: readonly ["received", "reviewing", "duplicate_linked", "info_requested", "comment", "reporter_comment", "fix_started", "fixed", "released", "verified", "reopened", "closed"];
+type ReporterTimelineKind = (typeof REPORTER_TIMELINE_KINDS)[number];
+interface ReporterCopy {
+    status: Record<ReporterStatusKey, string>;
+    detail: Record<ReporterStatusKey, string>;
+    idea: {
+        received: string;
+        reviewing: string;
+        fixing: string;
+        shipped: string;
+        shippedVersion: string;
+    };
+    closedReason: Record<Exclude<ReporterClosedReason, 'spam'>, string> & {
+        none: string;
+    };
+    others: {
+        few: string;
+        many: string;
+    };
+    timeline: Record<Exclude<ReporterTimelineKind, 'comment' | 'closed'>, string>;
+    categories: Record<ReporterCategory, string>;
+    ui: {
+        yes: string;
+        notYet: string;
+        empty: string;
+        loadError: string;
+        retry: string;
+        sending: string;
+        sent: string;
+        sendFailed: string;
+        noReplies: string;
+        you: string;
+        developer: string;
+        addWords: string;
+        developerReplied: string;
+        updates: string;
+    };
+}
+/** Resolve a BCP-47 tag (`ja-JP`, `es-419`) to a supported locale; English otherwise. */
+declare function resolveReporterLocale(tag: string | null | undefined): ReporterLocale;
+/** The full copy table for a locale (unknown tags fall back to English). */
+declare function reporterCopy(locale?: string): ReporterCopy;
+/** Replace `{name}` placeholders; a missing value leaves an empty string. */
+declare function fillReporterTemplate(template: string, params?: Record<string, string | number | null | undefined>): string;
+/** Fields of a reporter-list row `reporterStatus` reads. All but `status` are optional. */
+interface ReporterStatusInput {
+    status: string;
+    /** True (or a timestamp) while the developer waits for the reporter. */
+    awaiting_reporter?: boolean | null;
+    awaiting_reporter_at?: string | null;
+    fixed_in_version?: string | null;
+    closed_reason?: string | null;
+    /** Bucketed duplicate count; never a raw number. */
+    group_bucket?: 'none' | 'few' | 'many' | null;
+    /** `user_category`; "Feature request" / "idea" selects the idea labels. */
+    user_category?: string | null;
+}
+interface ReporterStatusView {
+    key: ReporterStatusKey;
+    label: string;
+    tone: ReporterTone;
+    detail: string;
+    /** Show the Yes / Not yet verification buttons. */
+    canVerify: boolean;
+    /** "You and a few others reported this", or null. */
+    othersNote: string | null;
+    /** `closed_reason = 'spam'`: hide the report from the reporter entirely. */
+    hidden: boolean;
+}
+/** True when the row is a feature request rather than a bug. */
+declare function isReporterIdea(input: Pick<ReporterStatusInput, 'user_category'>): boolean;
+/**
+ * The end-user view of a report. Overlays are checked before the base
+ * status: "Waiting on you" wins for any open report, and the duplicate-group
+ * note is added on top of whatever the base state is.
+ */
+declare function reporterStatus(input: ReporterStatusInput, locale?: string): ReporterStatusView;
+/** Parameters a timeline template may interpolate. */
+interface ReporterTimelineParams {
+    /** Verbatim developer text for `comment` and `info_requested`; the reporter's own for `reporter_comment`. */
+    text?: string | null;
+    version?: string | null;
+    closed_reason?: string | null;
+}
+/**
+ * Render one timeline entry. Pipeline kinds always come from the template for
+ * their kind; only the developer's own words (`comment`, `info_requested`) are
+ * passed through, verbatim.
+ */
+declare function reporterTimelineText(kind: ReporterTimelineKind, params?: ReporterTimelineParams, locale?: string): string;
+/** Reporter-facing label for a category chip. */
+declare function reporterCategoryLabel(category: ReporterCategory, locale?: string): string;
+
+export { REPORTER_CANONICAL_STATUSES, REPORTER_CATEGORIES, REPORTER_CLOSED_REASONS, REPORTER_LOCALES, REPORTER_TIMELINE_KINDS, type ReporterCanonicalStatus, type ReporterCategory, type ReporterClosedReason, type ReporterCopy, type ReporterLocale, type ReporterStatusInput, type ReporterStatusKey, type ReporterStatusView, type ReporterTimelineKind, type ReporterTimelineParams, type ReporterTone, fillReporterTemplate, isReporterIdea, reporterCategoryLabel, reporterCopy, reporterStatus, reporterTimelineText, resolveReporterLocale };

package/dist/reporter-ui.d.ts

@@ -0,0 +1,131 @@
+/**
+ * FILE: reporter-ui.ts
+ * PURPOSE: The one reporter-facing vocabulary shared by every SDK widget
+ *          (web, React Native, Capacitor): report categories, the end-user
+ *          status table, the timeline kinds and their copy in en/ja/es/th.
+ *
+ * OVERVIEW:
+ * - `reporterStatus(report, locale)` maps all 14 internal `reports.status`
+ *   values (plus the `awaiting_reporter` and duplicate-group overlays and the
+ *   feature-request variants) onto eight end-user states. There is no branch
+ *   that echoes the raw status: an unknown value reads as "Received".
+ * - `reporterTimelineText(kind, params, locale)` renders pipeline events from
+ *   a fixed template per kind. Stored notification payload text is never
+ *   shown, so internal category / severity can not leak to a reporter.
+ *
+ * USAGE:
+ * - `import { reporterStatus } from '@mushi-mushi/core/reporter-ui'`
+ * - Shipped as a subpath so the main `@mushi-mushi/core` entry stays within
+ *   its size budget; nothing here is re-exported from `index.ts`.
+ *
+ * Plan 018 (docs/execplans/reporter-loop-v2.md) §2.1 and §2.3.
+ */
+/** Every value `reports_status_check` allows. Pinned to the server list by a test. */
+declare const REPORTER_CANONICAL_STATUSES: readonly ["new", "pending", "submitted", "queued", "classified", "grouped", "fixing", "fixed", "dismissed", "triaged", "in_progress", "resolved", "verified", "reopened"];
+type ReporterCanonicalStatus = (typeof REPORTER_CANONICAL_STATUSES)[number];
+declare const REPORTER_LOCALES: readonly ["en", "ja", "es", "th"];
+type ReporterLocale = (typeof REPORTER_LOCALES)[number];
+/** Optional type chips on the one-screen report form, in display order. */
+declare const REPORTER_CATEGORIES: readonly ["bug", "slow", "visual", "confusing", "idea"];
+type ReporterCategory = (typeof REPORTER_CATEGORIES)[number];
+/** `closed_reason` values the `reports_closed_reason_check` constraint allows. */
+declare const REPORTER_CLOSED_REASONS: readonly ["duplicate", "not_reproducible", "wont_fix", "working_as_intended", "spam"];
+type ReporterClosedReason = (typeof REPORTER_CLOSED_REASONS)[number];
+type ReporterTone = 'neutral' | 'info' | 'attention' | 'progress' | 'success' | 'success-muted' | 'muted';
+/** The end-user state a report is shown in. */
+type ReporterStatusKey = 'received' | 'reviewing' | 'reviewing_again' | 'fixing' | 'verified' | 'fixed_next' | 'fixed_version' | 'fixed' | 'closed' | 'waiting';
+/** Timeline entry kinds the reporter detail view renders (§2.3). */
+declare const REPORTER_TIMELINE_KINDS: readonly ["received", "reviewing", "duplicate_linked", "info_requested", "comment", "reporter_comment", "fix_started", "fixed", "released", "verified", "reopened", "closed"];
+type ReporterTimelineKind = (typeof REPORTER_TIMELINE_KINDS)[number];
+interface ReporterCopy {
+    status: Record<ReporterStatusKey, string>;
+    detail: Record<ReporterStatusKey, string>;
+    idea: {
+        received: string;
+        reviewing: string;
+        fixing: string;
+        shipped: string;
+        shippedVersion: string;
+    };
+    closedReason: Record<Exclude<ReporterClosedReason, 'spam'>, string> & {
+        none: string;
+    };
+    others: {
+        few: string;
+        many: string;
+    };
+    timeline: Record<Exclude<ReporterTimelineKind, 'comment' | 'closed'>, string>;
+    categories: Record<ReporterCategory, string>;
+    ui: {
+        yes: string;
+        notYet: string;
+        empty: string;
+        loadError: string;
+        retry: string;
+        sending: string;
+        sent: string;
+        sendFailed: string;
+        noReplies: string;
+        you: string;
+        developer: string;
+        addWords: string;
+        developerReplied: string;
+        updates: string;
+    };
+}
+/** Resolve a BCP-47 tag (`ja-JP`, `es-419`) to a supported locale; English otherwise. */
+declare function resolveReporterLocale(tag: string | null | undefined): ReporterLocale;
+/** The full copy table for a locale (unknown tags fall back to English). */
+declare function reporterCopy(locale?: string): ReporterCopy;
+/** Replace `{name}` placeholders; a missing value leaves an empty string. */
+declare function fillReporterTemplate(template: string, params?: Record<string, string | number | null | undefined>): string;
+/** Fields of a reporter-list row `reporterStatus` reads. All but `status` are optional. */
+interface ReporterStatusInput {
+    status: string;
+    /** True (or a timestamp) while the developer waits for the reporter. */
+    awaiting_reporter?: boolean | null;
+    awaiting_reporter_at?: string | null;
+    fixed_in_version?: string | null;
+    closed_reason?: string | null;
+    /** Bucketed duplicate count; never a raw number. */
+    group_bucket?: 'none' | 'few' | 'many' | null;
+    /** `user_category`; "Feature request" / "idea" selects the idea labels. */
+    user_category?: string | null;
+}
+interface ReporterStatusView {
+    key: ReporterStatusKey;
+    label: string;
+    tone: ReporterTone;
+    detail: string;
+    /** Show the Yes / Not yet verification buttons. */
+    canVerify: boolean;
+    /** "You and a few others reported this", or null. */
+    othersNote: string | null;
+    /** `closed_reason = 'spam'`: hide the report from the reporter entirely. */
+    hidden: boolean;
+}
+/** True when the row is a feature request rather than a bug. */
+declare function isReporterIdea(input: Pick<ReporterStatusInput, 'user_category'>): boolean;
+/**
+ * The end-user view of a report. Overlays are checked before the base
+ * status: "Waiting on you" wins for any open report, and the duplicate-group
+ * note is added on top of whatever the base state is.
+ */
+declare function reporterStatus(input: ReporterStatusInput, locale?: string): ReporterStatusView;
+/** Parameters a timeline template may interpolate. */
+interface ReporterTimelineParams {
+    /** Verbatim developer text for `comment` and `info_requested`; the reporter's own for `reporter_comment`. */
+    text?: string | null;
+    version?: string | null;
+    closed_reason?: string | null;
+}
+/**
+ * Render one timeline entry. Pipeline kinds always come from the template for
+ * their kind; only the developer's own words (`comment`, `info_requested`) are
+ * passed through, verbatim.
+ */
+declare function reporterTimelineText(kind: ReporterTimelineKind, params?: ReporterTimelineParams, locale?: string): string;
+/** Reporter-facing label for a category chip. */
+declare function reporterCategoryLabel(category: ReporterCategory, locale?: string): string;
+
+export { REPORTER_CANONICAL_STATUSES, REPORTER_CATEGORIES, REPORTER_CLOSED_REASONS, REPORTER_LOCALES, REPORTER_TIMELINE_KINDS, type ReporterCanonicalStatus, type ReporterCategory, type ReporterClosedReason, type ReporterCopy, type ReporterLocale, type ReporterStatusInput, type ReporterStatusKey, type ReporterStatusView, type ReporterTimelineKind, type ReporterTimelineParams, type ReporterTone, fillReporterTemplate, isReporterIdea, reporterCategoryLabel, reporterCopy, reporterStatus, reporterTimelineText, resolveReporterLocale };