UI/UX Consistency Guidelines

This document provides comprehensive guidelines for maintaining UI/UX consistency across Waldur HomePort. Following these patterns ensures a predictable, accessible, and professional user experience.

Table of Contents

1. Empty States
2. Button Visibility (Hide vs Disable)
3. Loading States
4. Tables and Filters
5. Dialogs and Confirmations
6. Notifications
7. Status Indicators
8. Tooltips
9. Typography and Content
10. Accessibility
11. Responsive Behavior
12. Anti-Patterns
13. Report Filters
14. Chart Composition
15. Report Page Layout
16. Prices and Computed Totals

---

1. Empty States

Empty states are critical touchpoints that can either frustrate users or guide them toward productive actions. Never leave users at dead ends.

1.1 Empty State Types

Type	Purpose	Example
First-use	Onboarding opportunity	"No projects yet. Create your first project to get started."
No search results	Help refine search	"Your search 'xyz' did not match any resources."
Filtered empty	Suggest filter modification	"No resources matching current filters"
User-cleared	Task completion	"All tasks completed!"
Error state	Recovery with retry	"Unable to load data." + Reload button

1.2 Table Empty States

Use the NoResult component for all table empty states:

import { NoResult } from '@/navigation/header/search/NoResult';

// Basic usage - let NoResult provide defaults
<NoResult />

// With custom title and message
<NoResult
  title={translate('No projects found')}
  message={translate('Create a project to start using resources.')}
/>

// With search context and clear action
<NoResult
  title={getNoResultTitle({ verboseName: 'projects', hasFilter: true })}
  message={getNoResultMessage({ query, verboseName: 'projects' })}
  callback={clearFilters}
  buttonTitle={translate('Clear filters')}
/>

// With custom action button
<NoResult
  title={translate('No resources yet')}
  message={translate('Deploy your first resource to get started.')}
  actions={
    <SubmitButton
      label={translate('Deploy resource')}
      onClick={handleDeploy}
    />
  }
/>

Message hierarchy: Title → Explanation → CTA (call-to-action)

Utility functions (from src/table/utils.tsx):

import { getNoResultTitle, getNoResultMessage } from '@/table/utils';

// For filtered tables
getNoResultTitle({ verboseName: 'users', hasFilter: true });
// → "No users found matching current filters"

// For search queries
getNoResultMessage({ query: 'john', verboseName: 'users' });
// → "Your search "john" did not match any users."

// For empty tables without filters
getNoResultMessage({ verboseName: 'projects', customEmpty: translate('Start by creating a project.') });

1.3 Inline Empty Values

Standard: Use DASH_ESCAPE_CODE (—) for null/undefined values in displays:

import { DASH_ESCAPE_CODE } from '@/table/constants';
import { renderFieldOrDash } from '@/table/utils';

// In table columns
{
  title: translate('Description'),
  render: ({ row }) => renderFieldOrDash(row.description),
}

// In detail views
<Field label={translate('End date')} value={renderFieldOrDash(project.end_date)} />

// Direct usage
{user.phone || DASH_ESCAPE_CODE}

For arrays:

// Empty array - use descriptive message
{items.length > 0 ? items.map(renderItem) : translate('None')}

// Or use dash for consistency
{items.length > 0 ? items.join(', ') : DASH_ESCAPE_CODE}

What the column holds decides it, not how empty the cell looks.

An empty cell is rarely a null: a count is 0, a price is 0.0000000, a relation is []. Deciding per cell is how one table ends up saying nothing three different ways, so decide by type:

The column holds	Empty renders as	Example
money — a price, a cost, a total	the figure, always: defaultCurrency(...)	€0.00 for a plan whose components are all priced at 0
a count	the number, or the column's own word for zero	Not used for the resources on a plan
an optional list or relation, where empty is the ordinary state	—	a plan's organization groups: none assigned means no restriction
a genuinely absent field (null/undefined)	— via renderFieldOrDash	a description nobody wrote

A price, a count or a total is never dashed: 0 is a fact somebody's configuration produced and usually one they must act on, while — reads as "does not apply". Money columns print defaultCurrency(...) unconditionally for the same reason, and PlanComponentsTable spells it out where a plan's zero prices are listed.

Where the two conventions collide — the app-wide idiom for an unconfigured value is muted text (FieldRow, WaldurResourcesList), while a neighbouring column in the same table states its zero at full weight — match the table. Cells read against the ones beside them before they read against the app.

1.4 Empty State Message Templates

// Default (no context)
translate('No {verboseName} found', { verboseName })

// With search query
translate('Your search "{query}" did not match any {verboseName}.', { query, verboseName })

// With active filters
translate('No {verboseName} found matching current filters', { verboseName })

// First use (encouraging)
translate('No {verboseName} yet. Create your first {singular} to get started.', { verboseName, singular })

// After action completion
translate('All {verboseName} have been processed.')

---

2. Button Visibility (Hide vs Disable)

The decision to hide vs disable a button significantly impacts user experience. Use this decision matrix consistently.

2.1 Decision Matrix

Scenario	Action	Rationale
User lacks permission (role-based)	HIDE	User will never be authorized in current context
Resource in wrong state	DISABLE + tooltip	Temporary; user can fix by changing state
Action in progress	DISABLE + spinner	Will become available when complete
Feature not applicable	HIDE	Doesn't apply to this resource type
Validation incomplete	DISABLE + tooltip	User can complete requirements
Quota exceeded	DISABLE + tooltip	User can request more quota

2.2 Disabled Button Requirements

ALWAYS provide a tooltip explaining WHY the button is disabled.

import { useValidators } from '@/resource/actions/useValidators';
import { ActionItem } from '@/resource/actions/ActionItem';

// Using useValidators hook for state-based validation
const validators = [
  ({ resource }) => {
    if (resource.state !== 'OK') {
      return translate('Resource must be in OK state');
    }
  },
  ({ resource }) => {
    if (resource.runtime_state !== 'ACTIVE') {
      return translate('Instance must be running');
    }
  },
];

const MyAction = ({ resource }) => {
  const { tooltip, disabled } = useValidators(validators, resource);

  return (
    <ActionItem
      title={translate('Restart')}
      action={handleRestart}
      disabled={disabled}
      tooltip={tooltip}  // Always provide tooltip when disabled
      iconNode={<ArrowClockwiseIcon weight="bold" />}
    />
  );
};

Visual requirements:

• Disabled buttons use design token colors (e.g., text-muted, btn-disabled) - NOT opacity
• Opacity is reserved for overlays only; components use solid colors for predictability, accessibility, and theming
• Keep the same width to prevent layout shift
• Use aria-disabled for accessibility

2.3 Permission Patterns

Use hasPermission() utility consistently:

import { hasPermission } from '@/permissions/hasPermission';
import { useUser } from '@/workspace/hooks';

const MyComponent = ({ project }) => {
  const user = useUser();

  // HIDE if user lacks permission (they can never do this)
  if (!hasPermission(user, {
    permission: 'resource.create',
    projectId: project.uuid
  })) {
    return null;  // Early return - hide entire component
  }

  return <CreateResourceButton />;
};

Staff-only actions:

import { StaffOnlyIndicator } from '@/customer/details/StaffOnlyIndicator';

// For staff-only actions that should still be visible
<ActionItem
  title={translate('Admin action')}
  action={handleAction}
  staff  // Shows StaffOnlyIndicator badge
/>

// Check staff status
const user = useUser();
if (!user?.is_staff) {
  return null;  // Hide from non-staff
}

---

3. Loading States

Consistent loading feedback prevents user confusion and maintains perceived performance.

3.1 Table Loading

// Table handles this automatically via the loading prop
// Spinner shown when: loading === true && rows.length === 0

// For manual control in custom components:
import { LoadingSpinner } from '@/core/LoadingSpinner';

{loading && !data.length ? (
  <LoadingSpinner />
) : (
  <DataContent data={data} />
)}

// With existing data - show subtle indicator, don't replace content
{loading && data.length > 0 && (
  <div className="text-center py-2">
    <LoadingSpinnerIcon className="text-muted" />
  </div>
)}

3.2 Button Loading

Use the pending prop on buttons:

import { SubmitButton } from '@/form';
import { BaseButton } from '@/core/buttons/BaseButton';

// Form submit button
<SubmitButton
  label={translate('Save')}
  submitting={isSubmitting}  // Shows spinner, disables button
/>

// Action button
<BaseButton
  label={translate('Process')}
  onClick={handleProcess}
  pending={isProcessing}  // Shows spinner, disables button
  size="sm"
/>

Key behaviors:

• Button shows spinner and becomes disabled
• Button width stays stable (no layout shift)
• Label remains visible next to spinner

3.3 Error States

Use LoadingErred component for recoverable errors:

import { LoadingErred } from '@/core/LoadingErred';

// In data-fetching components
if (error) {
  return (
    <LoadingErred
      loadData={refetch}
      message={translate('Unable to load projects.')}
    />
  );
}

// Custom error message
<LoadingErred
  loadData={retry}
  message={translate('Connection failed. Please check your network.')}
/>

Always provide a retry action - never leave users stuck.

---

4. Tables and Filters

4.1 Filter Visibility Rules

Filter Position	When Visible	On Empty Table
header	Always	Always visible
menu	Toggle button click	Show toggle button
sidebar	When filters active OR toggled	Show toggle button (allow discovery)

Important: Never completely hide filters on empty tables. Users need to discover that filters exist and may be causing the empty state.

When filters return no results, show a specific empty state:

• Message: "No results match your filters"
• Actions: "Clear filters" / "View filters"

<NoResult
  title={translate('No results match your filters')}
  message={translate('Try adjusting your filters or clear them to see all items.')}
  actions={
    <>
      <Button variant="tertiary" onClick={clearFilters}>
        {translate('Clear filters')}
      </Button>
      <Button variant="outline" onClick={openFilters}>
        {translate('View filters')}
      </Button>
    </>
  }
/>

// Table configuration
<Table
  filters={<MyFilters />}
  filterPosition="menu"  // 'header' | 'menu' | 'sidebar'
  // ...
/>

4.2 Filter Behavior Checklist

• Clear visual indication when filters are active (badge count)
• Prominent "Clear all" functionality
• Reset to page 1 when filters change
• Persist filter state across navigation (when appropriate)
• Show "No results matching filters" message (not generic empty)

4.3 Pagination Rules

import { PAGE_SIZE_COMPACT, PAGE_SIZE_FULL } from '@/table/constants';

// PAGE_SIZE_COMPACT = 5 (for embedded/secondary tables)
// PAGE_SIZE_FULL = 10 (for primary tables)

// Hide pagination when items ≤ PAGE_SIZE_COMPACT
{pagination.resultCount > PAGE_SIZE_COMPACT && (
  <TablePagination {...pagination} />
)}

// Show item count
// Format: "Showing 1-10 of 100"

---

5. Dialogs and Confirmations

5.1 Confirmation and Mutation Pattern

The preferred way to handle mutations that require user confirmation is the useManagedMutation hook. It centralizes confirmation logic, loading states, and notifications.

import { useManagedMutation } from '@/modal/useManagedMutation';
import { translate } from '@/i18n';

export const DeleteProjectButton = ({ project, refetch }) => {
  const { mutate, isPending } = useManagedMutation<any, any, void>({
    mutationFn: () => deleteProject(project.uuid),
    successMessage: translate('Project has been deleted.'),
    errorMessage: translate('Could not delete project.'),
    refetch,
    confirmation: {
      title: translate('Delete project {name}?', { name: project.name }),
      body: translate('This action cannot be undone.'),
      options: {
        forDeletion: true,
        positiveButton: translate('Delete'),
      },
    },
  });

  return (
    <Button
      variant="danger"
      onClick={() => mutate()}
      disabled={isPending}
    >
      {translate('Delete')}
    </Button>
  );
};

5.2 Batch Mutation Pattern

For operations involving multiple items (bulk actions), use the useBatchMutation hook. It handles partial successes gracefully and standardizes bulk confirmation dialogs.

import { useBatchMutation } from '@/modal/useBatchMutation';
import { translate } from '@/i18n';

export const BulkDeleteProjectsButton = ({ projects, refetch }) => {
  const { mutate, isPending } = useBatchMutation<any, any, void>({
    rows: projects,
    mutationFn: (project) => deleteProject(project.uuid),
    successMessage: translate('Selected projects have been deleted.'),
    errorMessage: translate('Some projects could not be deleted.'),
    renderPartialSuccessMessage: (n) =>
      translate('{n} projects have been deleted.', { n }),
    refetch,
    confirmation: {
      title: translate('Delete selected projects'),
      body: (
        <div>
          <p>{translate('You are about to delete these projects:')}</p>
          <ul>
            {projects.map((p) => (
              <li key={p.uuid}>{p.name}</li>
            ))}
          </ul>
        </div>
      ),
      options: { forDeletion: true },
    },
  });

  return (
    <Button
      variant="danger"
      onClick={() => mutate()}
      disabled={isPending}
    >
      {translate('Delete selected')}
    </Button>
  );
};

5.2 Form Dialog Pattern

Use the useModal hook to manage dialog state:

import { useModal } from '@/modal/actions';

export const MyDialog: FC = () => {
  const { closeDialog } = useModal();

  return (
    <ModalDialog
      title={translate('Title')}
      footer={
        <div className="d-flex gap-2 justify-content-end">
          <Button variant="tertiary" onClick={closeDialog}>
            {translate('Cancel')}
          </Button>
          <SubmitButton
            label={translate('Save changes')}
            submitting={isSubmitting}
            disabled={!isValid}
          />
        </div>
      }
    >
      {/* Form content */}
    </ModalDialog>
  );
};

---

6. Notifications

6.1 Standard Mutation Pattern

For most API actions, use useManagedMutation even if no confirmation is required. This ensures consistent loading state and notification handling.

import { useManagedMutation } from '@/modal/useManagedMutation';

export const ApproveButton = ({ resource }) => {
  const { mutate, isPending } = useManagedMutation<any, any, void>({
    mutationFn: () => approveResource(resource.uuid),
    successMessage: translate('Resource approved'),
    errorMessage: translate('Could not approve resource'),
  });

  return (
    <Button onClick={() => mutate()} disabled={isPending}>
      {translate('Approve')}
    </Button>
  );
};

6.2 Benefits of Managed Mutations

• Declarative Logic: Focus on the action and messages rather than managing try/catch blocks and loading states manually.
• UX Consistency: Standardizes how confirmations look and how success/error notifications are displayed.
• Robustness: useBatchMutation handles partial failures (using Promise.allSettled) ensuring the user knows exactly what succeeded and what failed.
• Automatic Sync: Integrated support for refetch and query invalidation ensures the UI stays up to date after the mutation.
• Type Safety: Fully typed hooks reduce runtime errors when passing variables or handling results.

For non-component usage (utility functions, services), use NotifyService:

import { NotifyService } from '@/store/notify';

export const standaloneHelper = async (error) => {
  NotifyService.errorResponse(error, translate('Background task failed'));
};

Configuration:

• Duration: 7000ms (7 seconds)
• Position: top-right
• Dismissible: Yes (show dismiss button)

---

7. Status Indicators

7.1 StateIndicator Component

import { StateIndicator } from '@/core/StateIndicator';

// Basic usage
<StateIndicator
  label={resource.state}
  variant="success"
/>

// With spinner for active/in-progress states
<StateIndicator
  label={translate('Creating')}
  variant="primary"
  active  // Shows spinner
/>

// Common variant options
<StateIndicator label="Active" variant="success" />
<StateIndicator label="Pending" variant="warning" />
<StateIndicator label="Error" variant="danger" />
<StateIndicator label="Inactive" variant="default" />

// Styling options
<StateIndicator
  label="OK"
  variant="success"
  outline  // Outlined style
  pill     // Rounded pill shape
  hasBullet  // Shows bullet indicator
  size="sm"  // 'sm' | 'lg'
/>

7.2 Variant Mapping Guidelines

State Category	Variant	Examples
Success/Active	success	Active, Running, Completed, Approved
Warning/Pending	warning	Pending, Processing, Updating
Error/Failed	danger	Error, Failed, Rejected, Unavailable
Neutral/Default	default	Draft, Archived, Paused, Unknown
Info	info	New, In Review

Custom variants (for differentiation within same category): pink, blue, teal, indigo, purple, rose, orange, moss

---

8. Tooltips

8.1 Usage Guidelines

Use tooltips for:

• Disabled buttons: Explain why disabled (required)
• Icon-only buttons: Always provide tooltip describing the action (required)
• Truncated text: Show full text
• Icons without labels: Describe the element's purpose
• Complex terms: Provide definitions

import { Tip } from '@/core/Tooltip';

// Basic tooltip
<Tip label={translate('Copy to clipboard')} id="copy-btn">
  <CopyIcon />
</Tip>

// Tooltip with body (title + description)
<Tip
  label={translate('Resource limits')}
  body={translate('Maximum amount of resources that can be allocated.')}
  id="limits-info"
>
  <InfoIcon />
</Tip>

// Light theme tooltip
<Tip label={fullText} id="text-tooltip" theme="light">
  <span className="ellipsis">{truncatedText}</span>
</Tip>

8.2 Disabled Element Tooltip Pattern

From ActionItem - use question icon for disabled action explanation:

import { QuestionIcon } from '@phosphor-icons/react';

// When action is disabled, show question icon with tooltip
{props.disabled && props.tooltip && (
  <Tip label={props.tooltip} id={`disabled-reason-${id}`}>
    <QuestionIcon
      size={20}
      weight="bold"
      className="text-muted ms-1"
    />
  </Tip>
)}

---

9. Typography and Content

9.1 Text Truncation

import { formatLongText } from '@/table/utils';

// For text > 100 characters - shows tooltip with full text
{formatLongText(description)}

// CSS truncation class
<span className="ellipsis">{text}</span>

// With custom width
<span className="ellipsis d-inline-block" style={{ maxWidth: 200 }}>
  {text}
</span>

9.2 Internationalization

All user-facing text must use translate():

import { translate } from '@/i18n';

// Simple string
translate('Save changes')

// With placeholders
translate('Hello, {name}!', { name: user.name })

// Plural forms
translate('{count} item', '{count} items', { count })

// Never hard-code strings
// ❌ <Button>Submit</Button>
// ✅ <Button>{translate('Submit')}</Button>

---

10. Accessibility

10.1 Disabled State Accessibility

// Use aria-disabled for screen reader support
<button
  aria-disabled={isDisabled}
  onClick={!isDisabled ? handleClick : undefined}
  className={isDisabled ? 'text-muted' : ''}
>
  {label}
</button>

// Tooltips on disabled buttons should be accessible
// The Tip component handles this automatically

10.2 Keyboard Navigation

• All interactive elements must be keyboard accessible
• Use proper focus management in modals
• Maintain logical tab order

10.3 Screen Reader Support

// Loading states should be announced
<LoadingSpinnerIcon
  role="status"
  aria-label={translate('Loading...')}
/>

// Provide text alternatives for icons
<button aria-label={translate('Delete item')}>
  <TrashIcon />
</button>

---

11. Responsive Behavior

11.1 Breakpoints

import { GRID_BREAKPOINTS } from '@/core/constants';

// GRID_BREAKPOINTS = { xs: 0, sm: 576, md: 768, lg: 992, xl: 1200, xxl: 1400 }

import { useMediaQuery } from 'react-responsive';

const isSm = useMediaQuery({ maxWidth: GRID_BREAKPOINTS.sm });
const isMd = useMediaQuery({ maxWidth: GRID_BREAKPOINTS.md });

11.2 Filter Position Adaptation

// Automatically converts 'menu' to 'sidebar' on small screens
const filterPosition = isSm && originalPosition === 'menu'
  ? 'sidebar'
  : originalPosition;

11.3 Interactive Element Sizing

Form controls (inputs, selects, textareas):

• Minimum height: 40px for adequate touch/click area

Buttons:

• Three standard sizes: 44px (large), 36px (default), 28px (small)
• All sizes are acceptable for desktop interfaces
• Use size appropriate to context and hierarchy

Icon-only buttons:

• Should maintain adequate click area even with small icons
• Consider padding to reach at least 28px hit area

// Button sizes
<Button size="lg">Large (44px)</Button>
<Button>Default (36px)</Button>
<Button size="sm">Small (28px)</Button>

Note: The 44px minimum touch target (WCAG) is primarily for mobile/touch interfaces. Desktop applications can use smaller interactive elements.

---

12. Anti-Patterns

12.1 Anonymous User Actions

When an action requires authentication (e.g., deploying a resource, ordering a service), show a confirmation dialog explaining that login is required, rather than silently redirecting or doing nothing.

import { useModal } from '@/modal/actions';

const { confirm } = useModal();

const handleClick = async () => {
  if (!user) {
    try {
      await confirm(
        translate('Authentication required'),
        translate(
          'Please log in to order a resource. You will be redirected to the login page.',
        ),
        { positiveButton: translate('Log in') },
      );
      router.stateService.go('login');
    } catch {
      // User cancelled
    }
    return;
  }
  // Proceed with authenticated action
};

Key rules:

• Never silently redirect anonymous users — always explain what's happening
• Use confirm from useModal() hook with a clear title and descriptive body
• Label the positive button with the action ("Log in"), not generic "OK"
• If the element is normally a <Link>, render a <button> for anonymous users to prevent navigation before the dialog

12.2 Equal Card Heights in Flex Containers

When cards are displayed in a row (carousel, grid), ensure they all have equal height regardless of content differences (description length, tags, badges).

// Carousel/flex container item wrapper
.offering-carousel-item {
  display: flex; // Makes child card stretch to full height
}

// Card wrapper class needs height: 100%
.offering-card-list {
  height: 100%;
}

// Card itself needs h-100
<Card className="card-bordered h-100">
  <Card.Body className="d-flex flex-column">
    {/* Use flex-grow-1 on variable-height content */}
    <p className="flex-grow-1">{description}</p>
    {/* Fixed footer stays at bottom */}
  </Card.Body>
</Card>

Checklist:

• Flex container parent: default align-items: stretch (don't override)
• Item wrapper: display: flex to propagate stretch
• Card link/wrapper: height: 100%
• Card element: h-100 class
• Variable content area: flex-grow-1 to fill remaining space

What NOT to Do

Anti-Pattern	Problem	Correct Approach
Redundant length === 0 checks	Table already handles empty	Trust the Table component
Mixed null display (—, "N/A", "", "None")	Inconsistent	Always use DASH_ESCAPE_CODE or renderFieldOrDash
Hide + Disable for same scenario	Confusing	Follow decision matrix consistently
Disabled button without tooltip	User doesn't know why	Always provide tooltip
Hard-coded strings	Not translatable	Always use translate()
Hidden filters on empty tables	Can't discover filters	Show filter toggle
Empty state without CTA	Dead end	Always provide next action
user.is_staff checks everywhere	Inconsistent	Use hasPermission() utility
Silent redirect for anonymous users	Confusing, "magical"	Show confirmation dialog before redirect
Cards without h-100 in flex rows	Uneven card heights	Use display: flex on wrapper + h-100 on card

Code Examples - Bad vs Good

// ❌ BAD: Inconsistent empty display
{user.email || 'N/A'}
{user.phone || ''}
{user.name || '—'}

// ✅ GOOD: Consistent
{renderFieldOrDash(user.email)}
{renderFieldOrDash(user.phone)}
{renderFieldOrDash(user.name)}

// ❌ BAD: Disabled without explanation
<Button disabled={!canEdit}>Edit</Button>

// ✅ GOOD: Disabled with tooltip
<Tip label={canEdit ? null : translate('You need edit permission')}>
  <Button disabled={!canEdit}>Edit</Button>
</Tip>

// ❌ BAD: Inconsistent staff checks
if (user.is_staff) { ... }
if (hasPermission(user, { permission: 'admin.view' })) { ... }
if (user?.is_staff || user?.is_support) { ... }

// ✅ GOOD: Consistent permission checking
if (hasPermission(user, { permission: 'resource.admin', projectId })) { ... }

// ❌ BAD: Empty state dead end
{items.length === 0 && <p>No items</p>}

// ✅ GOOD: Actionable empty state
{items.length === 0 && (
  <NoResult
    title={translate('No items yet')}
    message={translate('Create your first item to get started.')}
    actions={<CreateButton />}
  />
)}

---

Quick Reference

Key Imports

// Empty states
import { NoResult } from '@/navigation/header/search/NoResult';
import { DASH_ESCAPE_CODE } from '@/table/constants';
import { renderFieldOrDash, getNoResultTitle, getNoResultMessage } from '@/table/utils';

// Buttons & Actions
import { BaseButton } from '@/core/buttons/BaseButton';
import { ActionItem } from '@/resource/actions/ActionItem';
import { useValidators } from '@/resource/actions/useValidators';

// Loading & Errors
import { LoadingSpinner, LoadingSpinnerIcon } from '@/core/LoadingSpinner';
import { LoadingErred } from '@/core/LoadingErred';

// Indicators
import { StateIndicator } from '@/core/StateIndicator';
import { Badge } from '@/core/Badge';

// Tooltips
import { Tip } from '@/core/Tooltip';

// Permissions
import { hasPermission } from '@/permissions/hasPermission';
import { StaffOnlyIndicator } from '@/customer/details/StaffOnlyIndicator';

// Notifications
import { useNotify } from '@/store/notify';

// Modals
import { useModal } from '@/modal/actions';

// i18n
import { translate } from '@/i18n';

// Constants
import { GRID_BREAKPOINTS } from '@/core/constants';
import { PAGE_SIZE_COMPACT, PAGE_SIZE_FULL } from '@/table/constants';

Decision Trees

Should I hide or disable this button?

Is the user PERMANENTLY unable to perform this action in current context?
├─ YES → HIDE the button
│   Examples: lacks role, feature not applicable, wrong resource type
│
└─ NO (temporary or user-fixable) → DISABLE with tooltip
    Examples: wrong state, validation incomplete, quota exceeded, action in progress

What empty state should I show?

Is there an active search/filter?
├─ YES (search) → "Your search '{query}' did not match any {items}"
├─ YES (filter) → "No {items} found matching current filters" + Clear button
│
└─ NO → Is this first-time use?
    ├─ YES → Encouraging message + Create CTA
    └─ NO → "No {items} found" + relevant action

---

Top 10 Inconsistencies to Fix

Based on a codebase analysis, these are prioritized inconsistencies that should be addressed:

1. Mixed Null/Empty Display Values

Files affected: src/vmware/PortsList.tsx, src/project/manage/ProjectGeneral.tsx, src/user/hooks/HooksList.tsx, and others

Problem: Using || 'N/A' instead of renderFieldOrDash()

// Current (inconsistent)
row.network_name || 'N/A'
project.name || 'N/A'
row.destination_url || row.email || 'N/A'

// Should be
renderFieldOrDash(row.network_name)
renderFieldOrDash(project.name)

2. Scattered Staff Permission Checks

Files affected: Multiple files with direct user.is_staff checks

Problem: Permission checks done inconsistently across components

// Current (scattered)
if (user.is_staff) { ... }

// Should use centralized utility
if (hasPermission(user, { permission: 'staff.action', ... })) { ... }

3. Sidebar Filters Hidden on Empty Tables

Files affected: src/table/Table.tsx:301-323

Problem: Sidebar filters only show when filtersStorage.length > 0, preventing filter discovery

// Current behavior
{props.filterPosition === 'sidebar' && props.filtersStorage.length > 0 && ...}

// Should show toggle button even when no filters active

4. Disabled Buttons Without Tooltips

Various components have disabled buttons that don't explain why they're disabled.

Fix: Audit all disabled props and ensure accompanying tooltip prop

5. Empty Copy Field Values

Files affected: src/proposals/manage/CallProposalsList.tsx, src/openstack/openstack-tenant/TenantPortsList.tsx

Problem: Using || '' for copy fields can result in copying empty string

// Current
copyField: (row) => row.mac_address || ''

// Should provide fallback or hide copy when empty
copyField: (row) => row.mac_address || undefined

6. Inconsistent Empty State Messages

Various list components show plain text instead of using the NoResult component.

Fix: All list empty states should use NoResult with appropriate messaging

7. Mixed Boolean Permission Returns

Files affected: src/permissions/hasPermission.ts

Problem: Function returns true or undefined instead of true or false

// Current
if (...) return true;
// Falls through to undefined

// Should be explicit
return false;

8. Invitation Display Inconsistencies

Files affected: src/invitations/join-organization/submission.tsx

Problem: Using || 'N/A' in user-facing messages

// Current
organization: groupInvitation.scope_name || 'N/A'

// Should handle missing data more gracefully

9. Form Field Empty Fallbacks

Files affected: Various form components using || ''

Problem: Inconsistent handling of empty form values

10. Missing Error State Handling

Various data-fetching components don't show LoadingErred on fetch failure.

Fix: Audit all data-fetching components for proper error state handling

---

13. Report Filters

When to use which filter pattern

Pattern	Use
Page-level filters (top of page)	Used on report pages
Header global filters	Used as system-wide filters affecting multiple pages
Table dropdown filters	Used for table column filtering

Standard filter component composition

There is no fixed standard set — filters vary per report depending on the dataset.

Filters used in reports:

• Organization
• Project
• Date range (start–end)

Optional shortcut selectors that populate the date range:

• 7 days
• 30 days
• 1 year

Other filters depend on the report dataset.

Filter visibility rules

Filters are visible at the top of the page. Even when result data is empty, filters remain visible so the user can adjust them to change the dataset.

Fix: Always render filter components unconditionally — never gate them on data state or loading.

// ❌ BAD
{data.length > 0 && <ReportFilters />}
{!loading && <FilterBar />}

// ✅ GOOD
<ReportFilters />
<FilterBar />

module.exports = {
  create(context) {
    return {
      JSXExpressionContainer(node) {
        const expr = node.expression;
        if (expr.type === 'LogicalExpression' && expr.operator === '&&') {
          const left = context.getSourceCode().getText(expr.left);
          if (left.includes('.length') || left.includes('loading') || left.includes('isEmpty')) {
            context.report({
              node,
              message: 'Filters must not be conditionally hidden based on data or loading state. Always render filters.',
            });
          }
        }
      },
    };
  },
};

Mobile behavior

Report filters remain at the top of the page. On smaller screens filters may wrap to multiple rows, and remain visible above charts and tables. Filters must stay accessible without opening a separate panel.

Default filter states per report type

Default state	Meaning
No filters applied	Report loads full dataset
Pre-filled date range	Report loads recent data (e.g. last 30 days)
Required filters empty	User must select filters before results appear

---

14. Chart Composition

When to use each chart type

Chart	Use
Donut / Pie	Showing how something breaks down as a share of the whole
Bar	Comparing values across categories
Line	Showing how something changes over time
Stacked bar	Comparing totals AND showing what's inside each total

• Use line when continuity matters — when the shape of the trend is the point.
• Use stacked bar only when both the total and the breakdown are meaningful. Keep it to 4–5 segments max, otherwise it gets hard to read.
• Avoid donut/pie when you have more than 5 segments or when users need to compare values precisely — a bar chart does that job better.

Chart-to-filter binding

Charts must reflect the same filtered dataset as the report. Filters affect charts and tables simultaneously. There is no separate filter state for charts.

Fix: Charts must receive already-filtered data from the parent report, not manage filters themselves.

// ❌ BAD
const MyChart = () => {
  const [filters, setFilters] = useState({});
  const [dateRange, setDateRange] = useState(null);
}

// ✅ GOOD
const MyChart = ({ data }) => {
  // receives already-filtered data from parent report
}

module.exports = {
  create(context) {
    return {
      CallExpression(node) {
        const isUseState =
          node.callee.name === 'useState' ||
          (node.callee.property && node.callee.property.name === 'useState');
        if (!isUseState) return;

        const varName = node.parent?.id?.elements?.[0]?.name || '';
        const filterKeywords = ['filter', 'Filter', 'dateRange', 'DateRange', 'period', 'Period'];
        const componentName = context.getScope().block?.id?.name || '';

        if (
          componentName.toLowerCase().includes('chart') &&
          filterKeywords.some((k) => varName.includes(k))
        ) {
          context.report({
            node,
            message: 'Chart components must not manage their own filter state. Receive filtered data from the parent report instead.',
          });
        }
      },
    };
  },
};

Data provenance display

Charts should include:

• Title describing the metric
• Totals or summary values
• Legend

Tooltips show the specific value and aggregation context (e.g. Sum of invoices in March — $12,400).

Chart empty and loading states

State	UI
Loading	Chart skeleton
Empty	"No data for selected filters. Try adjusting your filters."
Error	Inline message or alert

Keep the chart container at its normal height even when empty. Never return null from a chart component.

Fix: Always render the chart container. Show an empty state when there is no data.

// ❌ BAD
if (!data.length) return null;

// ✅ GOOD
{data.length === 0
  ? <NoResult title={translate('No data for selected filters. Try adjusting your filters.')} />
  : <Chart data={data} />
}

module.exports = {
  create(context) {
    return {
      ReturnStatement(node) {
        const src = context.getSourceCode().getText(node);
        const componentName = context.getScope().block?.id?.name || '';
        if (componentName.toLowerCase().includes('chart') && src.includes('return null')) {
          context.report({
            node,
            message: 'Chart components must not return null on empty data. Keep the container and show an empty state instead.',
          });
        }
      },
    };
  },
};

Responsive chart behavior

Charts should resize to container width and remain readable without horizontal scroll.

---

15. Report Page Layout

Standard page structure

Page title → Report filters → Charts → Data table.

Fix: Always follow this order — never render a chart or table before filters.

// ❌ BAD
const ReportPage = () => (
  <>
    <DataTable />
    <ReportFilters />
  </>
);

// ✅ GOOD
const ReportPage = () => (
  <>
    <PageTitle />
    <ReportFilters />
    <Charts />
    <DataTable />
  </>
);

module.exports = {
  create(context) {
    return {
      JSXElement(node) {
        const children = node.children.filter((c) => c.type === 'JSXElement');
        const names = children.map((c) => c.openingElement?.name?.name || '');

        const filterIdx = names.findIndex((n) => n.includes('Filter'));
        const tableIdx = names.findIndex((n) => n.includes('Table') || n.includes('DataTable'));
        const chartIdx = names.findIndex((n) => n.includes('Chart'));

        if (filterIdx !== -1 && tableIdx !== -1 && tableIdx < filterIdx) {
          context.report({
            node,
            message: 'DataTable must come after ReportFilters in report page layout.',
          });
        }
        if (filterIdx !== -1 && chartIdx !== -1 && chartIdx < filterIdx) {
          context.report({
            node,
            message: 'Chart must come after ReportFilters in report page layout.',
          });
        }
      },
    };
  },
};

Spacing

16px between blocks.

State label placement

Use existing label hierarchy from current mocks. Mocks must follow the same placement used in existing pages. Do not introduce new state layouts.

---

16. Prices and Computed Totals

Never make the reader do the arithmetic

If a screen shows charges that add up to something the user cares about, show the sum. A list of line items with no total is an unfinished screen.

Where the total goes, relative to its line items

The job the number does decides the placement:

• The total drives a choice — a catalogue price, a plan comparison, anything the user reads in order to pick. The total leads: it is the first thing in its column or block, and the line items below explain how it was reached.
• The total confirms a calculation — an order summary, an invoice, a cart. The total follows: the user has already read the line items and the sum closes them out.

Either way the total and its line items are on the same screen. A total behind a tab, an accordion or a dialog is a total the decision was made without.

// ❌ BAD — line items only; the reader sums four rows to learn the price
<FormTable>
  <ComponentRow component={managementFee} />
  <ComponentRow component={cpu} />
</FormTable>

// ✅ GOOD — deciding: the total leads its line items
<Table
  {...tableProps}
  columns={[componentColumn, ...planColumns]}
  // rows = [ totalRow, ...componentRows ]
/>

// ✅ GOOD — verifying: the total closes the line items
<FormTable>
  <ComponentRow component={cpu} />
  <ComponentRowTotal amount={total} period="monthly" />
</FormTable>

A floor must be labelled as a floor

When the figure is only what the user pays before sizing anything, or before metered usage, say so in the label — Starting price, From €20.00 — not in a footnote below the fold. Price: €20.00 next to components charged per unit is a wrong number, not a rounded one.

Comparable options go side by side

Plans, tiers and any other set of alternatives the user is choosing between are laid out in parallel columns, never in tabs. Two options that are never on screen together cannot be compared. Reference: src/marketplace/offerings/details/PlanComparison.tsx.

Price belongs next to the primary action

A page whose primary call to action is a purchase or a request shows the entry price adjacent to that button, with a link into the full breakdown. Reference: src/marketplace/offerings/details/OfferingPriceSummary.tsx.

Labels must not undercut what is on screen

Do not name an action in a way that implies the visible content is partial — Download full price list next to a price list tells the reader that the list they are looking at is not the full one. Name the format or the destination instead: Export price list.

---

Implementation Checklist

When fixing these inconsistencies:

• Run yarn lint:check after changes
• Verify no TypeScript errors with yarn build
• Test empty states manually
• Verify disabled button tooltips appear
• Check responsive behavior on mobile
• Run relevant unit tests