@qoretechnologies/reqraft 0.10.64 → 0.10.65-pr.148.gc6381e4

package/src/components/supportTicket/WorkspaceAccessStatus.stories.tsx

@@ -0,0 +1,105 @@
+import { StoryObj } from '@storybook/react-vite';
+import { expect, fn, userEvent, waitFor, within } from 'storybook/test';
+import { StoryMeta } from '../../types';
+import { TicketHeader } from './TicketHeader';
+import { IWorkspaceAccessStatusProps, WorkspaceAccessStatus } from './WorkspaceAccessStatus';
+
+/** The frozen clock every relative time here is spoken against. */
+const NOW = Date.parse('2026-10-19T12:00:00Z');
+const at = (minutes: number) => new Date(NOW + minutes * 60_000).toISOString();
+
+const ACTIVE = { state: 'active', created_by_type: 'customer', issued_at: at(-180), expires_at: at(2 * 24 * 60), until_resolved: false };
+
+/*
+ * One read-only value with many states: the review grid is one story, every state a
+ * labelled rail row, staff beside customer — one capture to look at, and a wrong word
+ * in any row still fails the play by name. The clicking case and the phone case are
+ * their own stories.
+ */
+const STATES: { label: string; props: Omit<IWorkspaceAccessStatusProps, 'now'> }[] = [
+  { label: 'Active · staff', props: { viewerRole: 'staff', grant: ACTIVE } },
+  { label: 'Active · customer', props: { viewerRole: 'customer', grant: ACTIVE } },
+  { label: 'Expiring soon', props: { viewerRole: 'staff', grant: { ...ACTIVE, expires_at: at(40) } } },
+  { label: 'Ended on the clock', props: { viewerRole: 'staff', grant: { ...ACTIVE, expires_at: at(-5) } } },
+  // six days, not seven: at seven the clock says "next week", which reads worse
+  { label: 'Automatic, until resolved', props: { viewerRole: 'staff', grant: { ...ACTIVE, created_by_type: 'system', until_resolved: true, expires_at: at(6 * 24 * 60) } } },
+  { label: 'Revoked', props: { viewerRole: 'staff', grant: { state: 'revoked', created_by_type: 'customer', issued_at: at(-3 * 24 * 60), expires_at: at(-24 * 60), ended_at: at(-26 * 60), end_cause: 'staff_revoked' } } },
+  { label: 'Pending · staff', props: { viewerRole: 'staff', request: { requested_at: at(-45), suggested_duration: '72h' } } },
+  { label: 'Pending · customer', props: { viewerRole: 'customer', request: { requested_at: at(-45), suggested_duration: '24h' } } },
+  { label: 'Setting is never', props: { viewerRole: 'staff', policy: 'never' } },
+  // the row label must not repeat the value's own word, or the play finds two
+  { label: 'Nothing yet', props: { viewerRole: 'staff' } },
+];
+
+const meta = {
+  component: WorkspaceAccessStatus,
+  title: 'Components/WorkspaceAccessStatus',
+  args: { viewerRole: 'staff', now: NOW, grant: ACTIVE },
+  // the value sits in the ticket rail, so each story renders it in one
+  render: (args) => <TicketHeader padding={14} properties={[{ label: 'Workspace access', value: <WorkspaceAccessStatus {...args} /> }]} />,
+} as StoryMeta<typeof WorkspaceAccessStatus>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const States: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders every state of the value as a labelled rail row against one frozen clock: an active grant from the staff and the customer side, one expiring within the hour (amber), one whose expiry passed (muted), an automatic grant until the ticket is resolved, a revoked one, an open request from both sides, a setting of "never", and none.',
+      },
+    },
+  },
+  render: () => (
+    <TicketHeader
+      padding={14}
+      properties={STATES.map(({ label, props }) => ({ label, value: <WorkspaceAccessStatus {...props} now={NOW} /> }))}
+    />
+  ),
+  async play({ canvasElement }) {
+    const canvas = within(canvasElement);
+    for (const text of [
+      'Granted by the customer · ends in 2 days',
+      'Granted by you · ends in 2 days',
+      'Granted by the customer · ends in 40 minutes',
+      'Access ended 5 minutes ago',
+      'Granted automatically · ends in 6 days',
+      'Access revoked: ended by support · yesterday',
+      'Requested for 3 days · awaiting the customer · 45 minutes ago',
+      'Qorus Support asks for access for 24 hours · 45 minutes ago',
+      "Not allowed: the account's setting is never",
+      'None',
+    ]) {
+      await expect(canvas.getByText(text)).toBeInTheDocument();
+    }
+  },
+};
+
+export const Active: Story = {
+  args: { action: { label: 'End access', icon: 'ShieldCrossLine', intent: 'danger', onClick: fn() } },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Renders the staff value of an active grant with "End access" beside it — the one state that carries an action. Clicking the action calls it.',
+      },
+    },
+  },
+  async play({ canvasElement, args }) {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByText('Granted by the customer · ends in 2 days')).toBeInTheDocument();
+    await userEvent.click(canvas.getByText('End access'));
+    await waitFor(() => expect(args.action?.onClick).toHaveBeenCalledTimes(1));
+  },
+};
+
+export const Mobile: Story = {
+  args: Active.args,
+  parameters: {
+    qlip: { viewport: { width: 390, height: 844 } },
+    docs: { description: { story: 'Renders the active value with its action at 390px: the sentence truncates with an ellipsis before the action does, and the action keeps its label.' } },
+  },
+  async play({ canvasElement }) {
+    await expect(within(canvasElement).getByText('End access')).toBeInTheDocument();
+  },
+};

package/src/components/supportTicket/WorkspaceAccessStatus.tsx

@@ -0,0 +1,176 @@
+import { ReqoreButton, ReqoreIcon, ReqoreSpan } from '@qoretechnologies/reqore';
+import { TSizes } from '@qoretechnologies/reqore/dist/constants/sizes';
+import { TReqoreIntent } from '@qoretechnologies/reqore/dist/constants/theme';
+import { IReqoreIconName } from '@qoretechnologies/reqore/dist/types/icons';
+import {
+  formatInstant,
+  formatRelativeTime,
+  grantTimeIntent,
+  millisUntil,
+  supportAccessDurationLabel,
+  supportGrantEndCauseLabel,
+  supportGrantStateMeta,
+  TSupportAccessPolicy,
+  TSupportGrantState,
+} from './accessMeta';
+import { TTicketViewerRole } from './meta';
+import { TicketPersonValue } from './TicketHeader';
+
+/*
+ * Where a ticket's workspace access stands, as one rail value: granted and for how
+ * long, requested and waiting, refused by the setting, or none — with the one thing
+ * the viewer may do about it beside it (the customer's Revoke, support's End access).
+ * The customer's IDE and the staff portal show the same grant from opposite sides,
+ * so the sentence is built here once and `viewerRole` picks the pronoun.
+ *
+ * The clock is the caller's (`now`): the component never reads the wall clock, so a
+ * story freezes it and every surface on a page agrees on "ends in 2 days".
+ */
+
+/** What the value needs of a grant: the plane's `SupportAccessGrant`, a subset. */
+export interface IWorkspaceAccessGrantSummary {
+  state: TSupportGrantState | string;
+  issued_at?: string;
+  expires_at?: string;
+  until_resolved?: boolean;
+  created_by_type?: 'customer' | 'staff' | 'system' | string;
+  ended_at?: string;
+  end_cause?: string;
+}
+
+/** What the value needs of an open staff request. */
+export interface IWorkspaceAccessRequestSummary {
+  requested_at: string;
+  suggested_duration?: string;
+}
+
+export interface IWorkspaceAccessStatusAction {
+  label: string;
+  icon?: IReqoreIconName;
+  intent?: TReqoreIntent;
+  onClick: () => void;
+  loading?: boolean;
+  tooltip?: string;
+}
+
+export interface IWorkspaceAccessStatusProps {
+  /** the ticket's active grant, or the last one when none is active */
+  grant?: IWorkspaceAccessGrantSummary;
+  /** the open staff request, when there is one and no active grant */
+  request?: IWorkspaceAccessRequestSummary;
+  /** the account's setting; `never` is said when nothing else is there to say */
+  policy?: TSupportAccessPolicy | string;
+  /** who is reading: decides "by you" against "by the customer" */
+  viewerRole: TTicketViewerRole;
+  /** the clock, in ms; a story passes a fixed one */
+  now: number;
+  /** the one thing the viewer may do right now, rendered beside the sentence */
+  action?: IWorkspaceAccessStatusAction;
+  /** the rail's size by default */
+  size?: TSizes;
+  className?: string;
+}
+
+const grantedBy = (grant: IWorkspaceAccessGrantSummary, viewerRole: TTicketViewerRole): string => {
+  if (grant.created_by_type === 'system') return 'automatically';
+  if (grant.created_by_type === 'customer' || !grant.created_by_type) {
+    return viewerRole === 'customer' ? 'by you' : 'by the customer';
+  }
+  return 'by support';
+};
+
+/** The sentence, its mark and its colour for the state the props describe. */
+export const describeWorkspaceAccess = (
+  { grant, request, policy, viewerRole, now }: Pick<IWorkspaceAccessStatusProps, 'grant' | 'request' | 'policy' | 'viewerRole' | 'now'>
+): { text: string; tooltip?: string; intent: TReqoreIntent; icon: IReqoreIconName; muted?: boolean } => {
+  if (grant && grant.state === 'active') {
+    const left = millisUntil(grant.expires_at, now);
+    if (!Number.isNaN(left) && left <= 0) {
+      return {
+        text: `Access ended ${formatRelativeTime(grant.expires_at, now)}`,
+        tooltip: formatInstant(grant.expires_at),
+        intent: 'muted',
+        icon: 'HourglassLine',
+      };
+    }
+    const ends = grant.expires_at ? ` · ends ${formatRelativeTime(grant.expires_at, now)}` : '';
+    return {
+      text: `Granted ${grantedBy(grant, viewerRole)}${ends}`,
+      tooltip: grant.expires_at
+        ? `Until ${formatInstant(grant.expires_at)}${grant.until_resolved ? ', or when the ticket is resolved' : ''}`
+        : undefined,
+      intent: grantTimeIntent(grant.expires_at, now),
+      icon: 'ShieldCheckLine',
+    };
+  }
+  if (grant) {
+    const meta = supportGrantStateMeta(grant.state);
+    const cause = supportGrantEndCauseLabel(grant.end_cause);
+    const when = formatRelativeTime(grant.ended_at ?? grant.expires_at, now);
+    return {
+      text: `Access ${meta.label.toLowerCase()}${cause && cause !== meta.label.toLowerCase() ? `: ${cause}` : ''}${when ? ` · ${when}` : ''}`,
+      tooltip: formatInstant(grant.ended_at ?? grant.expires_at) || undefined,
+      intent: meta.intent,
+      icon: meta.icon,
+    };
+  }
+  if (request) {
+    const since = formatRelativeTime(request.requested_at, now);
+    const duration = request.suggested_duration ? ` for ${supportAccessDurationLabel(request.suggested_duration)}` : '';
+    return {
+      text:
+        viewerRole === 'customer'
+          ? `Qorus Support asks for access${duration} · ${since}`
+          : `Requested${duration} · awaiting the customer · ${since}`,
+      tooltip: formatInstant(request.requested_at),
+      intent: 'pending',
+      icon: 'TimeLine',
+    };
+  }
+  if (policy === 'never') {
+    return {
+      text: viewerRole === 'customer' ? 'Off: your setting is never' : "Not allowed: the account's setting is never",
+      intent: 'danger',
+      icon: 'ShieldCrossLine',
+    };
+  }
+  return { text: 'None', intent: 'muted', icon: 'ShieldLine', muted: true };
+};
+
+export const WorkspaceAccessStatus = ({
+  grant,
+  request,
+  policy,
+  viewerRole,
+  now,
+  action,
+  size = 'small',
+  className,
+}: IWorkspaceAccessStatusProps) => {
+  const { text, tooltip, intent, icon, muted } = describeWorkspaceAccess({ grant, request, policy, viewerRole, now });
+  return (
+    <TicketPersonValue className={`reqore-workspace-access-status${className ? ` ${className}` : ''}`}>
+      {/* intent as a dot, the way the rail's other state values read: the colour
+          carries the state without a saturated chip in a row of reference material */}
+      <ReqoreIcon icon={icon} size='tiny' color={intent as never} />
+      <ReqoreSpan size={size} tooltip={tooltip} effect={muted ? { opacity: 0.5 } : undefined}>
+        {text}
+      </ReqoreSpan>
+      {action ? (
+        <ReqoreButton
+          size={size}
+          minimal
+          flat
+          icon={action.icon}
+          intent={action.intent}
+          loading={action.loading}
+          tooltip={action.tooltip}
+          onClick={action.onClick}
+          className='reqore-workspace-access-status-action'
+        >
+          {action.label}
+        </ReqoreButton>
+      ) : null}
+    </TicketPersonValue>
+  );
+};

package/src/components/supportTicket/accessMeta.ts

@@ -0,0 +1,210 @@
+import { TReqoreIntent } from '@qoretechnologies/reqore/dist/constants/theme';
+import { IReqoreIconName } from '@qoretechnologies/reqore/dist/types/icons';
+import { ITicketEnumMeta, humaniseWireValue } from './meta';
+
+/*
+ * The delegated-support-access vocabulary (qorus#692): how the account's access
+ * setting, a grant's state, the reasons a grant ended, the duration presets and the
+ * grant's own audit trail read on every surface that shows them — the customer's IDE
+ * (the sign-up step, the account tab, the ticket drawer) and the staff portal (the
+ * workspace tab, the tenant card). The wire values are the SaaS plane's
+ * (`QorusSaasSupportAccessStore`, `QorusSupportSessionStore`); the words are shared so
+ * the two sides describe one grant the same way. The customer-facing LEGAL wording of
+ * the setting is not here: the plane versions and serves it with the choice.
+ */
+
+/** The account's support access setting, least to most restrictive. */
+export type TSupportAccessPolicy = 'auto' | 'ask' | 'never';
+
+/** Where the governing setting came from. `default` when the customer never chose;
+ *  `owner` when the workspace's billing owner's stricter setting governs the ticket. */
+export type TSupportAccessPolicySource = 'default' | 'signup' | 'prompt' | 'settings' | 'admin' | 'owner';
+
+export type TSupportGrantState = 'active' | 'revoked' | 'expired';
+
+export type TSupportGrantEndCause =
+  | 'customer_revoked'
+  | 'staff_revoked'
+  | 'superseded'
+  | 'ticket_resolved'
+  | 'ticket_closed'
+  | 'policy_changed'
+  | 'account_erased'
+  | 'workspace_deleted'
+  | 'expired';
+
+/** A duration a staff request suggests; the customer's Grant answers exactly it. */
+export type TSupportAccessDuration = '24h' | '72h' | '7d' | 'until_resolved';
+
+/** The grant's own audit trail (`…/access` `audit`, the account's access log). */
+export type TSupportAccessAuditAction =
+  | 'policy_set'
+  | 'access_requested'
+  | 'granted'
+  | 'extended'
+  | 'revoked'
+  | 'expired'
+  | 'used'
+  | 'use_refused'
+  | 'session_started'
+  | 'session_ended';
+
+/** A mark with a sentence: the setting's meaning is what a customer decides on. */
+export interface ISupportAccessMeta extends ITicketEnumMeta {
+  description?: string;
+}
+
+/** `idle_paused` → "Idle paused": a wire value as words. */
+
+const UNKNOWN: ISupportAccessMeta = { label: 'Unknown', intent: 'muted', icon: 'QuestionLine' };
+
+const lookup =
+  <K extends string>(table: Record<K, ISupportAccessMeta>) =>
+  (value: string | undefined): ISupportAccessMeta =>
+    value === undefined
+      ? UNKNOWN
+      : ((table as Record<string, ISupportAccessMeta>)[value] ?? { ...UNKNOWN, label: humaniseWireValue(value) });
+
+export const SUPPORT_ACCESS_POLICY_META: Record<TSupportAccessPolicy, ISupportAccessMeta> = {
+  auto: {
+    label: 'Granted automatically',
+    intent: 'success',
+    icon: 'ShieldCheckLine',
+    description: 'Read-only access for Qorus Support is granted automatically on every ticket filed.',
+  },
+  ask: {
+    label: 'Ask the customer',
+    intent: 'info',
+    icon: 'QuestionAnswerLine',
+    description: 'Support asks on each ticket; the customer decides whether to grant access.',
+  },
+  never: {
+    label: 'Never',
+    intent: 'danger',
+    icon: 'ShieldCrossLine',
+    description: 'No workspace access for Qorus Support. Support asks for information in the thread instead.',
+  },
+};
+/** The setting's mark; an unknown value still reads as words. */
+export const supportAccessPolicyMeta = lookup(SUPPORT_ACCESS_POLICY_META);
+
+export const SUPPORT_ACCESS_POLICY_SOURCE_LABEL: Record<TSupportAccessPolicySource, string> = {
+  default: 'the default, never chosen',
+  signup: 'chosen at sign-up',
+  prompt: 'chosen when first asked',
+  settings: 'chosen in the account settings',
+  admin: 'set by Qorus staff',
+  owner: "the workspace owner's stricter setting",
+};
+export const supportAccessPolicySourceLabel = (source: string | undefined): string =>
+  (source && (SUPPORT_ACCESS_POLICY_SOURCE_LABEL as Record<string, string>)[source]) ||
+  humaniseWireValue(source ?? '');
+
+export const SUPPORT_GRANT_STATE_META: Record<TSupportGrantState, ISupportAccessMeta> = {
+  active: { label: 'Active', intent: 'success', icon: 'ShieldCheckLine' },
+  revoked: { label: 'Revoked', intent: 'danger', icon: 'ShieldCrossLine' },
+  expired: { label: 'Expired', intent: 'muted', icon: 'HourglassLine' },
+};
+export const supportGrantStateMeta = lookup(SUPPORT_GRANT_STATE_META);
+
+export const SUPPORT_GRANT_END_CAUSE_LABEL: Record<TSupportGrantEndCause, string> = {
+  customer_revoked: 'ended by the customer',
+  staff_revoked: 'ended by support',
+  superseded: 'extended into a new grant',
+  ticket_resolved: 'the ticket was resolved',
+  ticket_closed: 'the ticket was closed',
+  policy_changed: "the account's setting changed",
+  account_erased: 'the account was erased',
+  workspace_deleted: 'the workspace was deleted',
+  expired: 'expired',
+};
+export const supportGrantEndCauseLabel = (cause: string | undefined): string | undefined =>
+  cause ? ((SUPPORT_GRANT_END_CAUSE_LABEL as Record<string, string>)[cause] ?? humaniseWireValue(cause)) : undefined;
+
+export const SUPPORT_ACCESS_DURATION_LABEL: Record<TSupportAccessDuration, string> = {
+  '24h': '24 hours',
+  '72h': '3 days',
+  '7d': '7 days',
+  until_resolved: 'until the ticket is resolved',
+};
+export const supportAccessDurationLabel = (duration: string | undefined): string =>
+  (duration && (SUPPORT_ACCESS_DURATION_LABEL as Record<string, string>)[duration]) ||
+  humaniseWireValue(duration ?? '');
+
+/** The grant's own trail, as a customer's access log or a staff access view lists it. */
+export const SUPPORT_ACCESS_AUDIT_ACTION_META: Record<TSupportAccessAuditAction, ISupportAccessMeta> = {
+  policy_set: { label: 'Setting changed', intent: 'info', icon: 'Settings3Line' },
+  access_requested: { label: 'Access requested', intent: 'pending', icon: 'ShieldUserLine' },
+  granted: { label: 'Access granted', intent: 'success', icon: 'ShieldCheckLine' },
+  extended: { label: 'Access extended', intent: 'info', icon: 'TimerLine' },
+  revoked: { label: 'Access revoked', intent: 'danger', icon: 'ShieldCrossLine' },
+  expired: { label: 'Access expired', intent: 'muted', icon: 'HourglassLine' },
+  used: { label: 'Workspace read', intent: 'info', icon: 'EyeLine' },
+  use_refused: { label: 'Read refused', intent: 'warning', icon: 'ForbidLine' },
+  session_started: { label: 'IDE session started', intent: 'info', icon: 'ExternalLinkLine' },
+  session_ended: { label: 'IDE session ended', intent: 'muted', icon: 'LogoutBoxLine' },
+};
+/** An action the plane writes that this vocabulary has not caught up with still renders. */
+export const supportAccessAuditActionMeta = (action: string): ISupportAccessMeta =>
+  (SUPPORT_ACCESS_AUDIT_ACTION_META as Record<string, ISupportAccessMeta>)[action] ?? {
+    ...UNKNOWN,
+    icon: 'HistoryLine' as IReqoreIconName,
+    label: humaniseWireValue(action),
+  };
+
+/* ── time, against a clock the caller owns ───────────────────────────────────── */
+
+const RELATIVE_UNITS: [Intl.RelativeTimeFormatUnit, number][] = [
+  ['year', 60 * 60 * 24 * 365],
+  ['month', 60 * 60 * 24 * 30],
+  ['week', 60 * 60 * 24 * 7],
+  ['day', 60 * 60 * 24],
+  ['hour', 60 * 60],
+  ['minute', 60],
+  ['second', 1],
+];
+
+/**
+ * "in 3 hours" / "2 days ago" against a clock the caller passes, so a story freezes it
+ * and two surfaces reading the same grant agree. An unparsable instant is an empty
+ * string, never "NaN years ago".
+ *
+ * Not `epoch-timeago` (what `ReqoreTimeAgo` and `TicketReferences` use): it speaks only
+ * of the past and reads the real clock, so it can neither say "in 3 hours" for a grant
+ * that is still running nor hold still in a story.
+ */
+export const formatRelativeTime = (iso: string | undefined, now: number, locale = 'en'): string => {
+  if (!iso) return '';
+  const then = new Date(iso).getTime();
+  if (Number.isNaN(then)) return '';
+  const seconds = Math.round((then - now) / 1000);
+  const rtf = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' });
+  for (const [unit, secondsInUnit] of RELATIVE_UNITS) {
+    if (Math.abs(seconds) >= secondsInUnit || unit === 'second') {
+      return rtf.format(Math.round(seconds / secondsInUnit), unit);
+    }
+  }
+  return '';
+};
+
+/** The absolute instant, for a tooltip beside a relative one. */
+export const formatInstant = (iso: string | undefined, locale = 'en-GB'): string => {
+  if (!iso) return '';
+  const date = new Date(iso);
+  return Number.isNaN(date.getTime())
+    ? iso
+    : date.toLocaleString(locale, { dateStyle: 'medium', timeStyle: 'short' });
+};
+
+/** Milliseconds until an instant; negative once it passed; NaN for nothing. */
+export const millisUntil = (iso: string | undefined, now: number): number =>
+  iso ? new Date(iso).getTime() - now : Number.NaN;
+
+/** The intent a grant's remaining time reads as: the state's, amber under an hour, muted once passed. */
+export const EXPIRING_SOON_MS = 60 * 60 * 1000;
+export const grantTimeIntent = (expiresAt: string | undefined, now: number): TReqoreIntent => {
+  const left = millisUntil(expiresAt, now);
+  if (Number.isNaN(left)) return 'success';
+  if (left <= 0) return 'muted';
+  return left < EXPIRING_SOON_MS ? 'warning' : 'success';
+};

package/src/components/supportTicket/index.ts

@@ -1,4 +1,5 @@
 export * from './meta';
+export * from './accessMeta';
 export * from './ticketModel';
 export * from './attachmentAccess';
 export * from './AttachmentChips';
@@ -8,3 +9,4 @@ export * from './InterfaceReferenceTags';
 export * from './ReferencePicker';
 export * from './fileToAttachment';
 export * from './TicketReplyBox';
+export * from './WorkspaceAccessStatus';