@cratis/showrunner.boxoffice.react 0.0.0-stage → 1.9.0

package/Banners/NoLicense.tsx

@@ -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 { Message } from '@cratis/components/Display';
+import { PortalIntent } from '@cratis/showrunner.boxoffice';
+import { useEntitlementsContext } from '../Entitlements/EntitlementsContext.js';
+import { PortalButton } from '../Portal/PortalButton.js';
+import { useBoxOfficeContext } from '../Provider/BoxOfficeContext.js';
+import { noLicenseModel } from './bannerModels.js';
+
+/**
+ * Tells a user who cannot use the product why, and what to do about it: the tenant is suspended, its trial ended, the
+ * user has no seat, or the tenant has more people with seats than it has bought. Nothing is shown to a user with a
+ * license. Render it where the application's content would be, or above it.
+ */
+export const NoLicense = () => {
+    const entitlements = useEntitlementsContext();
+    const { labels, seat } = useBoxOfficeContext();
+    const model = noLicenseModel(entitlements, seat, labels);
+
+    if (!model) {
+        return null;
+    }
+
+    return (
+        <div className='boxoffice-no-license' data-reason={model.reason}>
+            <Message severity={model.reason === 'noSeat' || model.reason === 'overCapacity' ? 'warn' : 'error'}>
+                <div className='boxoffice-banner__text'>
+                    <strong>{model.title}</strong>
+                    <span>{model.text}</span>
+                </div>
+            </Message>
+            {model.reason !== 'noSeat' && <PortalButton intent={PortalIntent.buy} label={labels.noLicense.openPortal} variant='outline' />}
+        </div>
+    );
+};

package/Banners/SuspensionBanner.tsx

@@ -0,0 +1,54 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Message } from '@cratis/components/Display';
+import { CurrentStanding, PortalIntent, ReadOnlyReason, SuspensionCause } from '@cratis/showrunner.boxoffice';
+import { useEntitlementsContext } from '../Entitlements/EntitlementsContext.js';
+import { PortalButton } from '../Portal/PortalButton.js';
+import { useBoxOfficeLabels } from '../Provider/BoxOfficeContext.js';
+import { suspensionReason } from './bannerModels.js';
+
+/**
+ * Props for {@link SuspensionBannerView}.
+ */
+export interface SuspensionBannerViewProps {
+    /** The cause the operator gave; the reason is left out when not known. */
+    cause?: SuspensionCause;
+}
+
+/**
+ * What the suspension banner shows, for the cause it is given.
+ */
+export const SuspensionBannerView = ({ cause }: SuspensionBannerViewProps) => {
+    const labels = useBoxOfficeLabels();
+    const reason = suspensionReason(cause, labels);
+
+    return (
+        <div className='boxoffice-banner'>
+            <Message severity='error'>
+                <div className='boxoffice-banner__text'>
+                    <strong>{labels.suspension.title}</strong>
+                    {reason && <span>{reason}</span>}
+                    <span>{labels.suspension.resolve}</span>
+                </div>
+            </Message>
+            <PortalButton intent={PortalIntent.buy} label={labels.suspension.openPortal} size='small' variant='outline' />
+        </div>
+    );
+};
+
+/**
+ * Tells the user that the operator suspended the tenant and why, and that everything is read-only until it is lifted.
+ * Nothing is shown when the tenant is not suspended. Render it once, above the application's pages.
+ */
+export const SuspensionBanner = () => {
+    const entitlements = useEntitlementsContext();
+    const isSuspended = entitlements.readOnlyReason === ReadOnlyReason.tenantSuspended;
+    const [standing] = CurrentStanding.when(isSuspended).use();
+
+    if (!isSuspended) {
+        return null;
+    }
+
+    return <SuspensionBannerView cause={standing.isSuccess ? standing.data?.cause : undefined} />;
+};

package/Banners/TrialBanner.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 { Message } from '@cratis/components/Display';
+import { PortalIntent } from '@cratis/showrunner.boxoffice';
+import { useEntitlementsContext } from '../Entitlements/EntitlementsContext.js';
+import { PortalButton } from '../Portal/PortalButton.js';
+import { useBoxOfficeLabels } from '../Provider/BoxOfficeContext.js';
+import { trialBannerModel } from './bannerModels.js';
+
+/**
+ * Tells the user how long the tenant's trial runs, or that it has closed, with a button to buy. Nothing is shown when
+ * the tenant is not on a trial. Render it once, above the application's pages.
+ */
+export const TrialBanner = () => {
+    const entitlements = useEntitlementsContext();
+    const labels = useBoxOfficeLabels();
+    const model = trialBannerModel(entitlements, labels);
+
+    if (!model) {
+        return null;
+    }
+
+    return (
+        <div className='boxoffice-banner'>
+            <Message severity={model.severity}>{model.text}</Message>
+            <PortalButton intent={PortalIntent.buy} label={labels.trialBanner.buy} size='small' />
+        </div>
+    );
+};

package/Banners/bannerModels.ts

@@ -0,0 +1,117 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ReadOnlyReason, SeatStanding, SeatStatus, SuspensionCause } from '@cratis/showrunner.boxoffice';
+import { Entitlements } from '../Entitlements/entitlementModel.js';
+import { BoxOfficeLabels, format } from '../Labels/index.js';
+
+/** How loud a banner is. */
+export type BannerSeverity = 'info' | 'warn' | 'error';
+
+/**
+ * What the trial banner says.
+ */
+export interface TrialBannerModel {
+    /** How loud the banner is. */
+    readonly severity: BannerSeverity;
+
+    /** What it says. */
+    readonly text: string;
+}
+
+/** How many days before a trial ends the banner turns into a warning. */
+export const trialWarningDays = 7;
+
+/**
+ * Works out what the trial banner says.
+ * @param entitlements What the tenant may do.
+ * @param labels The labels to show.
+ * @returns What to say; undefined when the tenant is not on a trial, or the trial is not what makes it read-only.
+ */
+export function trialBannerModel(entitlements: Entitlements, labels: BoxOfficeLabels): TrialBannerModel | undefined {
+    if (entitlements.state === 'trialClosed') {
+        return { severity: 'error', text: labels.trialBanner.closed };
+    }
+
+    if (entitlements.state !== 'trial' || !entitlements.trial) {
+        return undefined;
+    }
+
+    const { daysLeft } = entitlements.trial;
+    if (daysLeft <= 0) {
+        return { severity: 'warn', text: labels.trialBanner.lastDay };
+    }
+
+    return {
+        severity: daysLeft <= trialWarningDays ? 'warn' : 'info',
+        text: format(labels.trialBanner.running, { days: daysLeft })
+    };
+}
+
+/**
+ * Says why the operator suspended a tenant.
+ * @param cause The cause the operator gave.
+ * @param labels The labels to show.
+ * @returns The reason, in words.
+ */
+export function suspensionReason(cause: SuspensionCause | undefined, labels: BoxOfficeLabels): string {
+    switch (cause) {
+        case SuspensionCause.trialEndedWithoutSeats:
+            return labels.suspension.trialEndedWithoutSeats;
+        case SuspensionCause.paymentOverdue:
+            return labels.suspension.paymentOverdue;
+        case SuspensionCause.administratorDecision:
+            return labels.suspension.administratorDecision;
+        default:
+            return '';
+    }
+}
+
+/** Why a user is told they have no license. */
+export type NoLicenseReason = 'suspended' | 'trialClosed' | 'noSeat' | 'overCapacity';
+
+/**
+ * What a user without a license is told.
+ */
+export interface NoLicenseModel {
+    /** Why the user has no license. */
+    readonly reason: NoLicenseReason;
+
+    /** The title. */
+    readonly title: string;
+
+    /** What to do about it. */
+    readonly text: string;
+}
+
+/**
+ * Works out whether the user has a license, and what to tell them if not. The tenant being read-only comes first,
+ * because it holds for everyone in it.
+ * @param entitlements What the tenant may do.
+ * @param seat Where the user stands with the tenant's seats; nothing while it loads.
+ * @param labels The labels to show.
+ * @returns What to tell the user; undefined when they have a license, or it is not known yet.
+ */
+export function noLicenseModel(entitlements: Entitlements, seat: SeatStanding | undefined, labels: BoxOfficeLabels): NoLicenseModel | undefined {
+    if (entitlements.isLoading) {
+        return undefined;
+    }
+
+    if (entitlements.readOnlyReason === ReadOnlyReason.tenantSuspended) {
+        return { reason: 'suspended', title: labels.noLicense.suspendedTitle, text: labels.noLicense.suspended };
+    }
+
+    if (entitlements.readOnlyReason === ReadOnlyReason.trialClosed) {
+        return { reason: 'trialClosed', title: labels.noLicense.trialClosedTitle, text: labels.noLicense.trialClosed };
+    }
+
+    if (seat?.status === SeatStatus.noSeat) {
+        return { reason: 'noSeat', title: labels.noLicense.noSeatTitle, text: labels.noLicense.noSeat };
+    }
+
+    if (seat?.status === SeatStatus.overCapacity) {
+        return { reason: 'overCapacity', title: labels.noLicense.overCapacityTitle, text: labels.noLicense.overCapacity };
+    }
+
+    return undefined;
+}

package/Banners/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 './bannerModels.js';
+export * from './NoLicense.js';
+export * from './SuspensionBanner.js';
+export * from './TrialBanner.js';

package/Entitlements/EntitlementsContext.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { createContext, useContext } from 'react';
+import { Entitlements, entitlementsOf } from './entitlementModel.js';
+
+/**
+ * The React context {@link BoxOfficeProvider} provides the entitlements through. Without a provider nothing is
+ * known, so nothing that belongs to a module is shown.
+ */
+export const EntitlementsContext = createContext<Entitlements>(entitlementsOf(undefined));
+
+/**
+ * Gets what the tenant may do.
+ * @returns The {@link Entitlements}.
+ */
+export const useEntitlementsContext = (): Entitlements => useContext(EntitlementsContext);

package/Entitlements/RequiresModule.tsx

@@ -0,0 +1,68 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Message } from '@cratis/components/Display';
+import { PortalIntent } from '@cratis/showrunner.boxoffice';
+import { ReactNode } from 'react';
+import { PortalButton } from '../Portal/PortalButton.js';
+import { useBoxOfficeLabels } from '../Provider/BoxOfficeContext.js';
+import { useEntitlementsContext } from './EntitlementsContext.js';
+import { requiresModuleModel } from './requiresModuleModel.js';
+
+/**
+ * Props for {@link RequiresModule}.
+ */
+export interface RequiresModuleProps {
+    /** The module whose content this is. */
+    module: string;
+
+    /**
+     * What to do when the tenant does not have the module: `hide` shows the fallback, which is nothing unless given;
+     * `explain` says why it is not there, and offers to try or buy it. Defaults to `hide`.
+     */
+    mode?: 'hide' | 'explain';
+
+    /** What to show instead of the content in `hide` mode. Nothing when not given. */
+    fallback?: ReactNode;
+
+    /** The content of the module. */
+    children?: ReactNode;
+}
+
+/**
+ * Shows its content only when the tenant has the module, in full or on trial. Nothing is shown while the entitlements
+ * load, so the content never flashes up and is taken away. The backend refuses the module's commands and queries on its
+ * own; this is what keeps the user from meeting the refusal.
+ */
+export const RequiresModule = ({ module, mode = 'hide', fallback, children }: RequiresModuleProps) => {
+    const entitlements = useEntitlementsContext();
+    const labels = useBoxOfficeLabels();
+
+    if (entitlements.isLoading) {
+        return null;
+    }
+
+    const model = requiresModuleModel(entitlements, module, labels);
+    if (model.hasModule) {
+        return <>{children}</>;
+    }
+
+    if (mode === 'hide') {
+        return <>{fallback}</>;
+    }
+
+    return (
+        <div className='boxoffice-requires-module'>
+            <Message severity='info'>
+                <div className='boxoffice-requires-module__text'>
+                    <strong>{model.title}</strong>
+                    <span>{model.text}</span>
+                </div>
+            </Message>
+            <div className='boxoffice-requires-module__actions'>
+                {model.canTry && <PortalButton intent={PortalIntent.try} label={labels.requiresModule.try} variant='outline' />}
+                <PortalButton intent={PortalIntent.buy} label={labels.requiresModule.buy} />
+            </div>
+        </div>
+    );
+};

package/Entitlements/entitlementModel.ts

@@ -0,0 +1,175 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { DateOnly } from '@cratis/fundamentals';
+import { EntitlementSummary, ModuleAccess, ModuleStanding, ReadOnlyReason } from '@cratis/showrunner.boxoffice';
+
+/**
+ * Where a tenant stands with its license, as one word.
+ *
+ * - `loading`: nothing is known yet.
+ * - `suspended`: the operator suspended the tenant; it is read-only.
+ * - `trialClosed`: the trial ended without seats being bought; the tenant is read-only.
+ * - `trial`: the tenant is on a trial that runs.
+ * - `licensed`: the tenant has bought seats.
+ * - `unlicensed`: the tenant has no seats and is not on a trial.
+ */
+export type LicenseState = 'loading' | 'suspended' | 'trialClosed' | 'trial' | 'licensed' | 'unlicensed';
+
+/**
+ * A trial that is running or has closed.
+ */
+export interface TrialStanding {
+    /** The last day of the trial. */
+    readonly ends: Date;
+
+    /** How many days are left; zero on the last day, and less than zero after it. */
+    readonly daysLeft: number;
+
+    /** Whether the trial has closed. */
+    readonly isClosed: boolean;
+}
+
+/**
+ * What a tenant may do, for a component to decide what to show.
+ */
+export interface Entitlements {
+    /** Whether nothing is known about the tenant yet. */
+    readonly isLoading: boolean;
+
+    /** Where the tenant stands with its license. */
+    readonly state: LicenseState;
+
+    /** Whether the tenant can read but not change anything. */
+    readonly isReadOnly: boolean;
+
+    /** Why the tenant is read-only; none when it is not. */
+    readonly readOnlyReason: ReadOnlyReason;
+
+    /** How many seats the tenant has today. */
+    readonly seats: number;
+
+    /** The trial, when the tenant is on one or was. */
+    readonly trial?: TrialStanding;
+
+    /** Whether the product has a customer portal to buy, try and change plan in. */
+    readonly canOpenPortal: boolean;
+
+    /** Every module the product declares, and what the tenant may do with it. */
+    readonly modules: readonly ModuleStanding[];
+
+    /**
+     * Gets whether the tenant has a module: in full or on trial. A preview does not count.
+     * @param module The module.
+     * @returns True when the tenant has the module.
+     */
+    has(module: string): boolean;
+
+    /**
+     * Gets the access the tenant has to a module.
+     * @param module The module.
+     * @returns The access; none for a module the product does not declare.
+     */
+    accessTo(module: string): ModuleAccess;
+
+    /**
+     * Gets what the tenant may do with a module.
+     * @param module The module.
+     * @returns The standing, or undefined for a module the product does not declare.
+     */
+    standingOf(module: string): ModuleStanding | undefined;
+}
+
+const millisecondsInADay = 24 * 60 * 60 * 1000;
+
+/**
+ * Turns a day from a proxy into a date.
+ * @param day The day: a `DateOnly`, a `yyyy-mm-dd` text, or a date.
+ * @returns The date at midnight local time; undefined when there is no day.
+ */
+export function toDate(day: DateOnly | Date | string | undefined): Date | undefined {
+    if (day === undefined || day === null) {
+        return undefined;
+    }
+
+    if (day instanceof Date) {
+        return new Date(day.getFullYear(), day.getMonth(), day.getDate());
+    }
+
+    const dateOnly = typeof day === 'string' ? DateOnly.parse(day.substring(0, 10)) : day;
+    return dateOnly.toDate();
+}
+
+/**
+ * Counts the days from one day to another, ignoring the time of day.
+ * @param from The day to count from.
+ * @param to The day to count to.
+ * @returns How many days `to` is after `from`; less than zero when it is before.
+ */
+export function daysBetween(from: Date, to: Date): number {
+    const start = Date.UTC(from.getFullYear(), from.getMonth(), from.getDate());
+    const end = Date.UTC(to.getFullYear(), to.getMonth(), to.getDate());
+    return Math.round((end - start) / millisecondsInADay);
+}
+
+function stateOf(summary: EntitlementSummary, trial: TrialStanding | undefined): LicenseState {
+    if (summary.readOnlyReason === ReadOnlyReason.tenantSuspended) {
+        return 'suspended';
+    }
+
+    if (summary.readOnlyReason === ReadOnlyReason.trialClosed) {
+        return 'trialClosed';
+    }
+
+    if (summary.isTrial && trial && !trial.isClosed) {
+        return 'trial';
+    }
+
+    return summary.seats > 0 ? 'licensed' : 'unlicensed';
+}
+
+/**
+ * Works out what a tenant may do from what the backend says.
+ * @param summary The entitlement summary; nothing while it loads.
+ * @param today The day it is. Defaults to today.
+ * @returns The {@link Entitlements}.
+ */
+export function entitlementsOf(summary: EntitlementSummary | undefined, today: Date = new Date()): Entitlements {
+    if (!summary) {
+        return {
+            isLoading: true,
+            state: 'loading',
+            isReadOnly: false,
+            readOnlyReason: ReadOnlyReason.none,
+            seats: 0,
+            canOpenPortal: false,
+            modules: [],
+            has: () => false,
+            accessTo: () => ModuleAccess.none,
+            standingOf: () => undefined
+        };
+    }
+
+    const modules = summary.modules ?? [];
+    const ends = summary.isTrial ? toDate(summary.trialEnds) : undefined;
+    const daysLeft = ends ? daysBetween(today, ends) : 0;
+    const trial = ends
+        ? { ends, daysLeft, isClosed: daysLeft < 0 || summary.readOnlyReason === ReadOnlyReason.trialClosed }
+        : undefined;
+    const standingOf = (module: string) => modules.find(_ => _.module === module);
+    const accessTo = (module: string) => standingOf(module)?.access ?? ModuleAccess.none;
+
+    return {
+        isLoading: false,
+        state: stateOf(summary, trial),
+        isReadOnly: summary.readOnlyReason !== ReadOnlyReason.none,
+        readOnlyReason: summary.readOnlyReason,
+        seats: summary.seats,
+        trial,
+        canOpenPortal: summary.canOpenPortal,
+        modules,
+        has: module => accessTo(module) === ModuleAccess.trial || accessTo(module) === ModuleAccess.full,
+        accessTo,
+        standingOf
+    };
+}

package/Entitlements/index.ts

@@ -0,0 +1,9 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './entitlementModel.js';
+export * from './EntitlementsContext.js';
+export * from './moduleFilter.js';
+export * from './requiresModuleModel.js';
+export * from './RequiresModule.js';
+export * from './useEntitlements.js';

package/Entitlements/moduleFilter.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Entitlements } from './entitlementModel.js';
+
+/**
+ * Something that belongs to a module: a navigation entry, a page, a menu item or a route.
+ */
+export interface ModuleOwned {
+    /** The module that owns it; leave it out for what belongs to the product itself and is always shown. */
+    module?: string;
+}
+
+/**
+ * Leaves out what belongs to a module the tenant does not have, so navigation and pages disappear without it. While
+ * the entitlements load, what belongs to a module is left out too, rather than shown and taken away.
+ * @param items The items, such as the entries of a sidebar.
+ * @param entitlements What the tenant may do.
+ * @returns The items the tenant may see.
+ */
+export function filterByModule<TItem extends ModuleOwned>(items: readonly TItem[], entitlements: Entitlements): TItem[] {
+    return items.filter(item => item.module === undefined || entitlements.has(item.module));
+}

package/Entitlements/requiresModuleModel.ts

@@ -0,0 +1,44 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ModuleAccess, ModuleStanding } from '@cratis/showrunner.boxoffice';
+import { BoxOfficeLabels, format } from '../Labels/index.js';
+import { Entitlements } from './entitlementModel.js';
+
+/**
+ * What to tell the user about a module they do not have.
+ */
+export interface RequiresModuleModel {
+    /** Whether the tenant has the module, so the content shows. */
+    readonly hasModule: boolean;
+
+    /** The title of the explanation. */
+    readonly title: string;
+
+    /** The explanation. */
+    readonly text: string;
+
+    /** Whether to offer to try the module. */
+    readonly canTry: boolean;
+}
+
+/**
+ * Works out what to show where a module's content would be.
+ * @param entitlements What the tenant may do.
+ * @param module The module.
+ * @param labels The labels to show.
+ * @returns The {@link RequiresModuleModel}.
+ */
+export function requiresModuleModel(entitlements: Entitlements, module: string, labels: BoxOfficeLabels): RequiresModuleModel {
+    const standing: ModuleStanding | undefined = entitlements.standingOf(module);
+    const name = standing?.name ?? module;
+    const access = standing?.access ?? ModuleAccess.none;
+    const text = access === ModuleAccess.preview ? labels.requiresModule.preview : labels.requiresModule.none;
+
+    return {
+        hasModule: entitlements.has(module),
+        title: format(labels.requiresModule.title, { module: name }),
+        text: format(text, { module: name }),
+        canTry: access === ModuleAccess.none || access === ModuleAccess.preview
+    };
+}

package/Entitlements/useEntitlements.ts

@@ -0,0 +1,25 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Entitlements } from './entitlementModel.js';
+import { useEntitlementsContext } from './EntitlementsContext.js';
+import { filterByModule, ModuleOwned } from './moduleFilter.js';
+
+/**
+ * Gets what the signed-in user's tenant may do: whether it is on a trial, read-only or suspended, and which modules it
+ * has. Use it inside a {@link BoxOfficeProvider}.
+ * @returns The {@link Entitlements}.
+ */
+export function useEntitlements(): Entitlements {
+    return useEntitlementsContext();
+}
+
+/**
+ * Leaves out what belongs to a module the tenant does not have, for the entries of a shell's navigation. Use it
+ * inside a {@link BoxOfficeProvider}.
+ * @param items The items, each optionally owned by a module.
+ * @returns The items the tenant may see.
+ */
+export function useModuleFilter<TItem extends ModuleOwned>(items: readonly TItem[]): TItem[] {
+    return filterByModule(items, useEntitlementsContext());
+}