@cratis/showrunner.usher.react 0.0.0-bootstrap.0

package/Labels/UsherLabels.ts

@@ -0,0 +1,365 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Every text the Usher components show or announce. Placeholders in braces, such as `{time}`, are filled in by the
+ * components.
+ */
+export interface UsherLabels {
+    /** Texts shared by several components. */
+    common: {
+        /** The cancel button. */
+        cancel: string;
+        /** The accessible name of a dialog's close button. */
+        close: string;
+        /** Introduces what is sent with a report. */
+        sentWithYourReport: string;
+        /** How many recent requests are sent with a report. `{count}` is the number. */
+        recentRequests: string;
+        /** Shown for one recent request sent with a report. */
+        oneRecentRequest: string;
+        /** Shown when nothing is known about where the user is. */
+        unknownLocation: string;
+        /** Separates the module, feature and slice of a location. */
+        locationSeparator: string;
+    };
+
+    /** The report button. */
+    reportButton: {
+        /** The text, tooltip and accessible name of the button that reports a problem. */
+        reportProblem: string;
+        /** The text, tooltip and accessible name of the button that reports an error. */
+        reportError: string;
+    };
+
+    /** The my issues button. */
+    myIssuesButton: {
+        /** The text, tooltip and accessible name of the button. */
+        label: string;
+        /** Added to the accessible name when support waits for the user. `{count}` is the number of issues. */
+        waiting: string;
+    };
+
+    /** The identity and access choices of the report dialogs and the grant access dialog. */
+    access: {
+        /** The checkbox that shares who the reporter is. */
+        shareIdentity: string;
+        /** Explains what sharing who the reporter is means. */
+        shareIdentityDescription: string;
+        /** The switch that lets support sign in as the reporter. */
+        grantAccess: string;
+        /** Explains what letting support sign in means. */
+        grantAccessDescription: string;
+        /** The duration dropdown. */
+        duration: string;
+        /** One hour of access. */
+        oneHour: string;
+        /** One day of access. */
+        oneDay: string;
+        /** Seven days of access. */
+        sevenDays: string;
+        /** States what granting access means. `{time}` is when it ends. */
+        notice: string;
+    };
+
+    /** The report a problem dialog. */
+    reportIssue: {
+        /** The title. */
+        title: string;
+        /** The button that sends the report. */
+        send: string;
+        /** The summary field. */
+        summary: string;
+        /** The description field. */
+        description: string;
+    };
+
+    /** The report this error dialog. */
+    reportError: {
+        /** The title. */
+        title: string;
+        /** The button that sends the report. */
+        send: string;
+        /** The collapsed section with the technical details. */
+        technicalDetails: string;
+        /** The type of the error. */
+        errorType: string;
+        /** The correlation id of the error. */
+        correlationId: string;
+        /** The stack frames of the error. */
+        stackFrames: string;
+        /** One stack frame. `{method}`, `{file}` and `{line}` are the frame's parts. */
+        stackFrame: string;
+        /** The details field. */
+        details: string;
+        /** The placeholder of the details field. */
+        detailsPlaceholder: string;
+    };
+
+    /** The notification shown when a report is sent. */
+    reportSent: {
+        /** The title. */
+        title: string;
+        /** The action that opens the issue. */
+        view: string;
+    };
+
+    /** The my issues side sheet. */
+    myIssues: {
+        /** The title. */
+        title: string;
+        /** The subtitle. */
+        description: string;
+        /** The button that reports a problem. */
+        reportProblem: string;
+        /** The switch that shows closed issues. */
+        showClosed: string;
+        /** The issue column. */
+        issueColumn: string;
+        /** The state column. */
+        stateColumn: string;
+        /** The last activity column. */
+        lastActivityColumn: string;
+        /** Marks an issue support waits for the user on. */
+        waitingForYou: string;
+        /** Marks an issue a release fixed. `{version}` is the version. */
+        fixedIn: string;
+        /** Shown when the user has reported nothing. */
+        empty: string;
+        /** Shown when only closed issues exist and they are hidden. */
+        noOpenIssues: string;
+        /** Shown while the issues load. */
+        loading: string;
+        /** Shown when the issues could not load. */
+        failed: string;
+        /** Shown when the user may not see issues. */
+        unauthorized: string;
+        /** An issue reported from an error. */
+        errorKind: string;
+        /** An issue described by hand. */
+        manualKind: string;
+    };
+
+    /** The states of an issue. */
+    states: {
+        /** Reported. */
+        reported: string;
+        /** Triaged. */
+        triaged: string;
+        /** Accepted. */
+        accepted: string;
+        /** In progress. */
+        inProgress: string;
+        /** Resolved. */
+        resolved: string;
+        /** Won't fix. */
+        wontFix: string;
+        /** Withdrawn. */
+        withdrawn: string;
+    };
+
+    /** The issue view. */
+    issue: {
+        /** The back button. */
+        back: string;
+        /** When the issue was reported. `{date}` is the date. */
+        reported: string;
+        /** Introduces the known issue. */
+        knownIssue: string;
+        /** Introduces the work item. */
+        trackedIn: string;
+        /** Shown while no release has the fix. */
+        notReleased: string;
+        /** Shown once a release has the fix. `{version}` is the version. */
+        fixedIn: string;
+        /** Quotes the question support waits for an answer to. `{question}` is the question. */
+        questionBanner: string;
+        /** Marks the question support waits for an answer to. */
+        waitingForAnswer: string;
+        /** Marks an answered question. */
+        answered: string;
+        /** The placeholder of the composer. */
+        composerPlaceholder: string;
+        /** The placeholder of the composer once the issue is withdrawn. */
+        withdrawnPlaceholder: string;
+        /** Shown when a message is sent on a withdrawn issue. */
+        withdrawnNotice: string;
+        /** Shown when the issue cannot be found. */
+        notFound: string;
+        /** Shown while the issue loads. */
+        loading: string;
+    };
+
+    /** The identity panel of the issue view. */
+    identity: {
+        /** The heading. */
+        heading: string;
+        /** Shown when support does not know who the reporter is. */
+        unknown: string;
+        /** Shown when support knows who the reporter is. */
+        known: string;
+        /** The button that shares who the reporter is. */
+        share: string;
+        /** The title of the share dialog. */
+        shareTitle: string;
+        /** Explains what is shared. */
+        shareDescription: string;
+        /** The confirm button of the share dialog. */
+        shareConfirm: string;
+    };
+
+    /** The access panel of the issue view. */
+    accessPanel: {
+        /** The heading while support may sign in. */
+        grantedHeading: string;
+        /** The heading while support may not sign in. */
+        notGrantedHeading: string;
+        /** The heading while support asks to sign in. */
+        requestedHeading: string;
+        /** Until when support may sign in. `{time}` is when it ends. */
+        grantedUntil: string;
+        /** Shown when support may not sign in. */
+        notGranted: string;
+        /** Quotes support's reason for asking. `{reason}` is the reason. */
+        requestReason: string;
+        /** The button that grants access. */
+        grant: string;
+        /** The button that dismisses support's request for now. */
+        notNow: string;
+        /** The button that revokes access. */
+        revoke: string;
+        /** The title of the revoke confirmation. */
+        revokeTitle: string;
+        /** The message of the revoke confirmation. */
+        revokeMessage: string;
+        /** The title of the grant dialog. */
+        grantTitle: string;
+        /** The confirm button of the grant dialog. */
+        grantConfirm: string;
+        /** Shown when support has not signed in. */
+        noSessions: string;
+        /** One session. `{name}`, `{start}` and `{end}` are filled in. */
+        session: string;
+        /** The end of a session still running. */
+        sessionRunning: string;
+        /** The heading of the sessions list. */
+        sessionsHeading: string;
+        /** Shown under a session in which support did nothing as the reporter. */
+        sessionDidNothing: string;
+        /** What support did as the reporter in a session, by entry kind. `{text}` is the entry's text. */
+        sessionActions: SessionActionLabels;
+    };
+
+    /** The actions of the issue view. */
+    actions: {
+        /** The button that reopens a resolved issue. */
+        reopen: string;
+        /** The title of the reopen dialog. */
+        reopenTitle: string;
+        /** The reason field of the reopen dialog. */
+        reopenReason: string;
+        /** The button that withdraws the issue. */
+        withdraw: string;
+        /** The title of the withdraw confirmation. */
+        withdrawTitle: string;
+        /** The message of the withdraw confirmation. */
+        withdrawMessage: string;
+    };
+
+    /** The conversation of the issue view. */
+    conversation: {
+        /** The reporter. */
+        you: string;
+        /** Support, when the desk hides the name. */
+        support: string;
+        /** The author of state changes. */
+        update: string;
+        /** Shown when there is nothing in the conversation. */
+        empty: string;
+        /** The accessible name of the send button. */
+        send: string;
+        /** Under a minute ago. */
+        justNow: string;
+        /** Minutes ago. `{minutes}` is the number. */
+        minutesAgo: string;
+        /** Hours ago. `{hours}` is the number. */
+        hoursAgo: string;
+        /** What a state change shows, by entry kind. `{text}` is the entry's text. */
+        events: ConversationEventLabels;
+    };
+}
+
+/**
+ * What support did while signed in as the reporter, as the sessions list shows it. `{text}` is the text of the entry.
+ */
+export interface SessionActionLabels {
+    /** Support added details. */
+    detailsAdded: string;
+    /** Support answered a question. */
+    questionAnswered: string;
+    /** Support shared who the reporter is. */
+    identityShared: string;
+    /** Support reopened the issue. */
+    reopened: string;
+    /** Support withdrew the issue. */
+    withdrawn: string;
+    /** Support revoked its own access. */
+    accessRevoked: string;
+}
+
+/**
+ * What the state changes in a conversation show. `{text}` is the text of the entry, such as a reason or a version.
+ */
+export interface ConversationEventLabels {
+    /** The reporter shared who they are. */
+    identityShared: string;
+    /** The reporter let support sign in. */
+    accessGranted: string;
+    /** The reporter revoked access. */
+    accessRevoked: string;
+    /** Access ended. */
+    accessLapsed: string;
+    /** Support asked to sign in. */
+    accessRequested: string;
+    /** Support signed in. */
+    supportSignedIn: string;
+    /** A support session ended. */
+    supportSessionEnded: string;
+    /** Support triaged the issue. */
+    triaged: string;
+    /** Support accepted the issue. */
+    accepted: string;
+    /** Support declined to fix the issue. */
+    declinedToFix: string;
+    /** Support started work. */
+    workStarted: string;
+    /** Support resolved the issue. */
+    resolved: string;
+    /** The reporter reopened the issue. */
+    reopened: string;
+    /** The reporter withdrew the issue. */
+    withdrawn: string;
+    /** The issue was linked to a known issue. */
+    linkedToKnownIssue: string;
+    /** The issue was unlinked from its known issue. */
+    unlinkedFromKnownIssue: string;
+    /** The issue was linked to a work item. */
+    linkedToWorkItem: string;
+    /** The issue was unlinked from its work item. */
+    unlinkedFromWorkItem: string;
+    /** A release with the fix shipped. */
+    fixReleased: string;
+}
+
+/**
+ * Makes every property of a type optional, all the way down.
+ */
+export type DeepPartial<T> = {
+    [TKey in keyof T]?: T[TKey] extends object ? DeepPartial<T[TKey]> : T[TKey];
+};
+
+/**
+ * The labels of the Usher components that a solution replaces, for instance to localize them. Labels left out keep
+ * their English defaults.
+ */
+export type UsherLabelOverrides = DeepPartial<UsherLabels>;

package/Labels/defaultUsherLabels.ts

@@ -0,0 +1,178 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { UsherLabels } from './UsherLabels.js';
+
+/**
+ * The English labels of the Usher components.
+ */
+export const defaultUsherLabels: UsherLabels = {
+    common: {
+        cancel: 'Cancel',
+        close: 'Close',
+        sentWithYourReport: 'Sent with your report',
+        recentRequests: '{count} recent requests',
+        oneRecentRequest: '1 recent request',
+        unknownLocation: 'Unknown location',
+        locationSeparator: ' › '
+    },
+    reportButton: {
+        reportProblem: 'Report a bug',
+        reportError: 'Report this error'
+    },
+    myIssuesButton: {
+        label: 'My issues',
+        waiting: '{count} waiting for you'
+    },
+    access: {
+        shareIdentity: 'Let support know who I am',
+        shareIdentityDescription: 'Support sees your name and email. Without this, they only see where the report came from.',
+        grantAccess: 'Let support sign in as me to look into this',
+        grantAccessDescription: 'Only for this report, and only for the time you choose.',
+        duration: 'For how long',
+        oneHour: '1 hour',
+        oneDay: '1 day',
+        sevenDays: '7 days',
+        notice: 'Support will see who you are and can act as you until {time}. You can revoke this at any time.'
+    },
+    reportIssue: {
+        title: 'Report a problem',
+        send: 'Send report',
+        summary: 'Summary',
+        description: 'What happened?'
+    },
+    reportError: {
+        title: 'Report this error',
+        send: 'Send report',
+        technicalDetails: 'Technical details',
+        errorType: 'Error type',
+        correlationId: 'Correlation id',
+        stackFrames: 'Stack frames',
+        stackFrame: '{method} line {line}',
+        details: 'What were you doing? (optional)',
+        detailsPlaceholder: 'For example: I selected three invoices and pressed Pay selected.'
+    },
+    reportSent: {
+        title: 'Report sent',
+        view: 'View'
+    },
+    myIssues: {
+        title: 'My issues',
+        description: 'What you have reported. Updates appear here as support works on them.',
+        reportProblem: 'Report a problem',
+        showClosed: 'Show closed',
+        issueColumn: 'Issue',
+        stateColumn: 'State',
+        lastActivityColumn: 'Last activity',
+        waitingForYou: 'Waiting for you',
+        fixedIn: 'Fixed in {version}',
+        empty: 'You haven\'t reported anything yet.',
+        noOpenIssues: 'You have no open issues.',
+        loading: 'Loading your issues…',
+        failed: 'Your issues could not be loaded.',
+        unauthorized: 'You are not allowed to see issues.',
+        errorKind: 'Error',
+        manualKind: 'Problem'
+    },
+    states: {
+        reported: 'Reported',
+        triaged: 'Triaged',
+        accepted: 'Accepted',
+        inProgress: 'In progress',
+        resolved: 'Resolved',
+        wontFix: 'Won\'t fix',
+        withdrawn: 'Withdrawn'
+    },
+    issue: {
+        back: 'Back to my issues',
+        reported: 'Reported {date}',
+        knownIssue: 'Known issue:',
+        trackedIn: 'Tracked in',
+        notReleased: 'Not released yet',
+        fixedIn: 'Fixed in {version}',
+        questionBanner: 'Your reply answers support\'s question: “{question}”',
+        waitingForAnswer: 'Waiting for your answer',
+        answered: 'Answered',
+        composerPlaceholder: 'Write to support',
+        withdrawnPlaceholder: 'You withdrew this issue',
+        withdrawnNotice: 'You withdrew this issue, so nothing more can be added to it.',
+        notFound: 'This issue could not be found.',
+        loading: 'Loading the issue…'
+    },
+    identity: {
+        heading: 'Who you are',
+        unknown: 'Support doesn\'t know who you are. They only see where the report came from.',
+        known: 'Support knows who you are.',
+        share: 'Share who I am',
+        shareTitle: 'Share who you are',
+        shareDescription: 'Support will see your name and email on this issue. This cannot be undone.',
+        shareConfirm: 'Share'
+    },
+    accessPanel: {
+        grantedHeading: 'Support can sign in as you',
+        notGrantedHeading: 'Support access',
+        requestedHeading: 'Support asks to sign in as you',
+        grantedUntil: 'Until {time}.',
+        notGranted: 'Support cannot sign in as you.',
+        requestReason: '“{reason}” Granting also shares who you are.',
+        grant: 'Grant access',
+        notNow: 'Not now',
+        revoke: 'Revoke access',
+        revokeTitle: 'Revoke access?',
+        revokeMessage: 'Support will no longer be able to sign in as you on this issue.',
+        grantTitle: 'Let support sign in as you',
+        grantConfirm: 'Grant access',
+        noSessions: 'No support sessions yet.',
+        session: '{name} signed in as you · {start}–{end}',
+        sessionRunning: 'now',
+        sessionsHeading: 'Support sessions',
+        sessionDidNothing: 'Did nothing as you.',
+        sessionActions: {
+            detailsAdded: 'Added details: {text}',
+            questionAnswered: 'Answered a question: {text}',
+            identityShared: 'Shared who you are',
+            reopened: 'Reopened the issue: {text}',
+            withdrawn: 'Withdrew the issue',
+            accessRevoked: 'Revoked its access'
+        }
+    },
+    actions: {
+        reopen: 'Reopen issue',
+        reopenTitle: 'Reopen issue',
+        reopenReason: 'Why is it not fixed?',
+        withdraw: 'Withdraw issue',
+        withdrawTitle: 'Withdraw this issue?',
+        withdrawMessage: 'Support stops working on it, and you cannot add to it afterwards.'
+    },
+    conversation: {
+        you: 'You',
+        support: 'Support',
+        update: 'Update',
+        empty: 'Nothing has happened on this issue yet.',
+        send: 'Send',
+        justNow: 'just now',
+        minutesAgo: '{minutes} min ago',
+        hoursAgo: '{hours} h ago',
+        events: {
+            identityShared: 'You shared who you are',
+            accessGranted: 'You let support sign in as you',
+            accessRevoked: 'You revoked support access',
+            accessLapsed: 'Support access ended',
+            accessRequested: 'Support asked to sign in as you: {text}',
+            supportSignedIn: 'Support signed in as you',
+            supportSessionEnded: 'Support signed out',
+            triaged: 'Triaged by support',
+            accepted: 'Accepted',
+            declinedToFix: 'Won\'t fix: {text}',
+            workStarted: 'Work started',
+            resolved: 'Resolved: {text}',
+            reopened: 'You reopened the issue: {text}',
+            withdrawn: 'You withdrew the issue',
+            linkedToKnownIssue: 'Linked to known issue “{text}”',
+            unlinkedFromKnownIssue: 'No longer linked to a known issue',
+            linkedToWorkItem: 'Tracked as “{text}”',
+            unlinkedFromWorkItem: 'No longer tracked',
+            fixReleased: 'Fixed in {text}'
+        }
+    }
+};

package/Labels/format.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Fills the placeholders of a label, such as `{count}`, with values. A placeholder without a value is left as it is.
+ * @param template The label.
+ * @param values The values by placeholder name.
+ * @returns The label with its placeholders filled in.
+ */
+export function format(template: string, values: Record<string, string | number>): string {
+    return template.replace(/\{(\w+)\}/g, (placeholder, name: string) =>
+        Object.hasOwn(values, name) ? String(values[name]) : placeholder);
+}

package/Labels/index.ts

@@ -0,0 +1,7 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './UsherLabels.js';
+export * from './defaultUsherLabels.js';
+export * from './resolveLabels.js';
+export * from './format.js';

package/Labels/resolveLabels.ts

@@ -0,0 +1,36 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { defaultUsherLabels } from './defaultUsherLabels.js';
+import { UsherLabelOverrides, UsherLabels } from './UsherLabels.js';
+
+/**
+ * Resolves the labels to show: the overrides given, and the English default for every label left out.
+ * @param overrides The labels a solution replaces.
+ * @returns The {@link UsherLabels}.
+ */
+export function resolveLabels(overrides?: UsherLabelOverrides): UsherLabels {
+    return merge(defaultUsherLabels, overrides) as UsherLabels;
+}
+
+function merge(defaults: object, overrides?: object): object {
+    if (!overrides) {
+        return defaults;
+    }
+
+    const merged: Record<string, unknown> = { ...defaults };
+    for (const [key, value] of Object.entries(overrides)) {
+        if (value === undefined) {
+            continue;
+        }
+
+        const defaultValue = (defaults as Record<string, unknown>)[key];
+        merged[key] = isObject(defaultValue) && isObject(value) ? merge(defaultValue, value) : value;
+    }
+
+    return merged;
+}
+
+function isObject(value: unknown): value is object {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/Provider/UsherBoundary.tsx

@@ -0,0 +1,30 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ArcContext } from '@cratis/arc.react';
+import { Slice } from '@cratis/arc.react/slices';
+import { ReactNode, useContext } from 'react';
+import { UsherContext } from './UsherContext.js';
+
+/**
+ * Props for {@link UsherBoundary}.
+ */
+export interface UsherBoundaryProps {
+    /** What Usher renders. */
+    children?: ReactNode;
+}
+
+/**
+ * Keeps Usher's own commands and queries out of what a report carries: they run without correlation tracking, and
+ * do not change the slice location of the solution's components around them.
+ */
+export const UsherBoundary = ({ children }: UsherBoundaryProps) => {
+    const usher = useContext(UsherContext);
+    const arc = useContext(ArcContext);
+
+    return (
+        <ArcContext.Provider value={usher.untrackedArc ?? arc}>
+            <Slice>{children}</Slice>
+        </ArcContext.Provider>
+    );
+};