WiseMapping Frontend Rules

1. Copyright Header (MANDATORY)

ALL

.ts

.tsx

.js

.jsx

files MUST start with this header BEFORE any imports:

/*
 *    Copyright [2007-2025] [wisemapping]
 *
 *   Licensed under WiseMapping Public License, Version 1.0 (the "License").
 *   It is basically the Apache License, Version 2.0 (the "License") plus the
 *   "powered by wisemapping" text requirement on every single page;
 *   you may not use this file except in compliance with the License.
 *   You may obtain a copy of the license at
 *
 *       https://github.com/wisemapping/wisemapping-open-source/blob/main/LICENSE.md
 *
 *   Unless required by applicable law or agreed to in writing, software
 *   distributed under the License is distributed on an "AS IS" BASIS,
 *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *   See the License for the specific language governing permissions and
 *   limitations under the License.
 */

Exceptions:

package.json

tsconfig.json

.md

.txt

, test data files, assets

2. Material UI Imports (CRITICAL - 500KB+ Bundle Impact)

⚠️ Pre-push hook will REJECT incorrect imports

✅ CORRECT (Tree-shakeable):

// Components - one per line
import Button from '@mui/material/Button';
import Box from '@mui/material/Box';

// Icons - one per line
import SearchIcon from '@mui/icons-material/Search';
import EditIcon from '@mui/icons-material/Edit';

// Hooks from /styles
import { useTheme, styled } from '@mui/material/styles';

// Types use 'import type'
import type { PaletteMode } from '@mui/material';
import type { SvgIconProps } from '@mui/material/SvgIcon';

❌ WRONG (Bloats bundle):

import { Button, Box } from '@mui/material';           // NO!
import { Search, Edit } from '@mui/icons-material';    // NO!
import { PaletteMode } from '@mui/material';           // NO! Use 'import type'

Common Components Quick Reference:

// Layout: Box, Container, Grid, Stack
// Inputs: Button, TextField, Select, MenuItem, Checkbox, Switch
// Feedback: Alert, Dialog, Snackbar, CircularProgress
// Data: Table, TableBody, TableCell, TableHead, TableRow, Chip, Tooltip
// Navigation: Tabs, Tab, Drawer
// Utils: IconButton, Divider, Paper, Typography

Validation: Run

./scripts/check-mui-imports.sh

yarn build:analyze

3. Component File Organization (MANDATORY)

Every component MUST follow the

index.tsx

pattern:

ComponentName/
├── index.tsx              # Main component (REQUIRED)
├── SubComponent.tsx       # Sub-components in same dir
├── helpers.ts             # Component-specific utilities
├── types.ts               # Component-specific types
└── styles.css             # Component-specific styles

Rules:

✅ Every component dir has
```
index.tsx
```
(main entry point)
✅ Sub-components stay in parent directory, named
```
PascalCase.tsx
```
✅ Helper files:
```
helpers.ts
```
,
```
types.ts
```
,
```
constants.ts
```
,
```
utils.ts
```
✅ Shared/reusable →
```
shared/
```
or
```
common/
```
directory
❌ NO components at root level without directory

❌ NO redundant naming:

MyComponent/MyComponent.tsx

→ use

MyComponent/index.tsx

Examples:

theme-toggle/
└── index.tsx

admin-console/
├── index.tsx
├── layout/index.tsx
├── maps-page/index.tsx
└── accounts-page/index.tsx

action-widget/pane/
├── topic-style-editor/
│   ├── index.tsx
│   ├── IconCollection.tsx
│   └── ColorPicker.tsx
└── shared/
    ├── StyledTabs.tsx
    └── StyledEditorContainer.tsx

Clean Imports Result:

import ThemeToggle from '../common/theme-toggle';        // ✅ Clean
import MapsPage from '../admin-console/maps-page';       // ✅ Clean
// vs
import ThemeToggle from '../common/theme-toggle/ThemeToggle'; // ❌ Redundant

4. Code Standards

Language: TypeScript preferred over JavaScript
React: Functional components + hooks (no class components)

Naming:

Components:
```
PascalCase
```
(
```
MyComponent.tsx
```
)
Utilities:
```
camelCase
```
(
```
myUtility.ts
```
)
Constants:
```
UPPER_SNAKE_CASE
```
(
```
MAX_VALUE
```
)

Git:
- Clear commit messages
- No force push to
```
main
```
- Branch names:
```
feature/name
```
  ,
```
fix/name
```

5. Performance

Check for duplicate dependencies before adding packages
Use dynamic imports for code splitting when appropriate
Run
```
yarn build:analyze
```
to verify bundle sizes

6. Testing

Unit tests:
```
*.test.ts
```
or
```
*.test.tsx
```
Integration tests: Cypress
Aim for good coverage on critical paths

7. TypeScript Type Safety (CRITICAL)

MANDATORY: All TypeScript code must be properly typed. NO exceptions.

Prohibited:

❌ NEVER use
any
type - Always use specific types
❌ NEVER use
@ts-ignore
or
@ts-expect-error
without discussion
❌ NEVER leave implicit
any
from function parameters or variables

Required Practices:

1. Import Proper Types:

// ✅ CORRECT - Import types from mindplot
import { Topic, Designer } from '@wisemapping/mindplot';

// ❌ WRONG - Using 'any'
const topic: any = ...;

2. Handle Nullable Types Correctly:

// ✅ CORRECT - Properly handle Topic | null
const getTopicDepth = (topic: Topic): number => {
  let current: Topic | null = topic;
  while (current && current.getParent() !== null) {
    current = current.getParent();  // Returns Topic | null
  }
};

// ❌ WRONG - Type mismatch
const getTopicDepth = (topic: Topic): number => {
  let current = topic;  // TypeScript infers Topic
  current = current.getParent();  // ERROR: Topic | null not assignable to Topic
};

3. Use Unknown for Truly Unknown Types:

// ✅ If you truly don't know the type
const data: unknown = JSON.parse(str);
if (typeof data === 'object' && data !== null) {
  // Type guard before use
}

// ❌ WRONG
const data: any = JSON.parse(str);

8. Linting and Code Quality (CRITICAL)

MANDATORY: AI MUST check linter errors after EVERY file creation or modification.

When to Run Linter (REQUIRED):

✅ IMMEDIATELY after creating a new file
✅ IMMEDIATELY after modifying an existing file
✅ Before declaring a task complete
✅ After any code generation or refactoring

Linting Workflow (ENFORCED):

For EACH file created/modified:
1. Write/modify the code
2. IMMEDIATELY run read_lints([specific_file_path])
3. Fix ALL errors found
4. Re-run read_lints to verify
5. Only then move to next file

At task completion:
1. Run read_lints on ALL modified files together
2. Fix any remaining issues
3. Final verification
4. Task complete

How to Check Lints:

// ✅ CORRECT - Check specific files you modified
read_lints([
  "packages/editor/src/components/new-component/index.tsx",
  "packages/editor/src/components/new-component/styled.ts"
])

// ❌ WRONG - Checking entire codebase (too noisy)
read_lints()  // or read_lints([])

Common ESLint Rules to Follow:

```
@typescript-eslint/no-explicit-any
```
- NO
```
any
```
types
```
@typescript-eslint/no-unused-vars
```
- Remove unused imports/variables

@typescript-eslint/explicit-function-return-type

- Type function returns when needed

Proper null/undefined handling
Material UI imports must follow tree-shakeable pattern (see rule #2)

AI Assistant Workflow (MANDATORY):

1. Create/modify TypeScript file
2. Add proper type imports (Topic, Designer, etc.)
3. Use correct types for all variables and parameters
4. Handle nullable types with | null or | undefined
5. RUN read_lints([file_path]) - DO NOT SKIP THIS
6. Fix all errors found
7. Verify with read_lints again
8. Move to next file/task

Priority:

ZERO tolerance for linting errors in completed tasks
Fix ALL errors before declaring task complete
If a linting rule seems incorrect, discuss with user before bypassing
Never commit code with linting errors

WiseMapping Frontend Rules

1. Copyright Header (MANDATORY)

ALL

.ts

.tsx

.js

.jsx

files MUST start with this header BEFORE any imports:

/*
 *    Copyright [2007-2025] [wisemapping]
 *
 *   Licensed under WiseMapping Public License, Version 1.0 (the "License").
 *   It is basically the Apache License, Version 2.0 (the "License") plus the
 *   "powered by wisemapping" text requirement on every single page;
 *   you may not use this file except in compliance with the License.
 *   You may obtain a copy of the license at
 *
 *       https://github.com/wisemapping/wisemapping-open-source/blob/main/LICENSE.md
 *
 *   Unless required by applicable law or agreed to in writing, software
 *   distributed under the License is distributed on an "AS IS" BASIS,
 *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *   See the License for the specific language governing permissions and
 *   limitations under the License.
 */

Exceptions:

package.json

tsconfig.json

.md

.txt

, test data files, assets

2. Material UI Imports (CRITICAL - 500KB+ Bundle Impact)

⚠️ Pre-push hook will REJECT incorrect imports

✅ CORRECT (Tree-shakeable):

// Components - one per line
import Button from '@mui/material/Button';
import Box from '@mui/material/Box';

// Icons - one per line
import SearchIcon from '@mui/icons-material/Search';
import EditIcon from '@mui/icons-material/Edit';

// Hooks from /styles
import { useTheme, styled } from '@mui/material/styles';

// Types use 'import type'
import type { PaletteMode } from '@mui/material';
import type { SvgIconProps } from '@mui/material/SvgIcon';

❌ WRONG (Bloats bundle):

import { Button, Box } from '@mui/material';           // NO!
import { Search, Edit } from '@mui/icons-material';    // NO!
import { PaletteMode } from '@mui/material';           // NO! Use 'import type'

Common Components Quick Reference:

// Layout: Box, Container, Grid, Stack
// Inputs: Button, TextField, Select, MenuItem, Checkbox, Switch
// Feedback: Alert, Dialog, Snackbar, CircularProgress
// Data: Table, TableBody, TableCell, TableHead, TableRow, Chip, Tooltip
// Navigation: Tabs, Tab, Drawer
// Utils: IconButton, Divider, Paper, Typography

Validation: Run

./scripts/check-mui-imports.sh

yarn build:analyze

3. Component File Organization (MANDATORY)

Every component MUST follow the

index.tsx

pattern:

ComponentName/
├── index.tsx              # Main component (REQUIRED)
├── SubComponent.tsx       # Sub-components in same dir
├── helpers.ts             # Component-specific utilities
├── types.ts               # Component-specific types
└── styles.css             # Component-specific styles

Rules:

✅ Every component dir has
```
index.tsx
```
(main entry point)
✅ Sub-components stay in parent directory, named
```
PascalCase.tsx
```
✅ Helper files:
```
helpers.ts
```
,
```
types.ts
```
,
```
constants.ts
```
,
```
utils.ts
```
✅ Shared/reusable →
```
shared/
```
or
```
common/
```
directory
❌ NO components at root level without directory

❌ NO redundant naming:

MyComponent/MyComponent.tsx

→ use

MyComponent/index.tsx

Examples:

theme-toggle/
└── index.tsx

admin-console/
├── index.tsx
├── layout/index.tsx
├── maps-page/index.tsx
└── accounts-page/index.tsx

action-widget/pane/
├── topic-style-editor/
│   ├── index.tsx
│   ├── IconCollection.tsx
│   └── ColorPicker.tsx
└── shared/
    ├── StyledTabs.tsx
    └── StyledEditorContainer.tsx

Clean Imports Result:

import ThemeToggle from '../common/theme-toggle';        // ✅ Clean
import MapsPage from '../admin-console/maps-page';       // ✅ Clean
// vs
import ThemeToggle from '../common/theme-toggle/ThemeToggle'; // ❌ Redundant

4. Code Standards

Language: TypeScript preferred over JavaScript
React: Functional components + hooks (no class components)

Naming:

Components:
```
PascalCase
```
(
```
MyComponent.tsx
```
)
Utilities:
```
camelCase
```
(
```
myUtility.ts
```
)
Constants:
```
UPPER_SNAKE_CASE
```
(
```
MAX_VALUE
```
)

Git:
- Clear commit messages
- No force push to
```
main
```
- Branch names:
```
feature/name
```
  ,
```
fix/name
```

5. Performance

Check for duplicate dependencies before adding packages
Use dynamic imports for code splitting when appropriate
Run
```
yarn build:analyze
```
to verify bundle sizes

6. Testing

Unit tests:
```
*.test.ts
```
or
```
*.test.tsx
```
Integration tests: Cypress
Aim for good coverage on critical paths

7. TypeScript Type Safety (CRITICAL)

MANDATORY: All TypeScript code must be properly typed. NO exceptions.

Prohibited:

❌ NEVER use
any
type - Always use specific types
❌ NEVER use
@ts-ignore
or
@ts-expect-error
without discussion
❌ NEVER leave implicit
any
from function parameters or variables

Required Practices:

1. Import Proper Types:

// ✅ CORRECT - Import types from mindplot
import { Topic, Designer } from '@wisemapping/mindplot';

// ❌ WRONG - Using 'any'
const topic: any = ...;

2. Handle Nullable Types Correctly:

// ✅ CORRECT - Properly handle Topic | null
const getTopicDepth = (topic: Topic): number => {
  let current: Topic | null = topic;
  while (current && current.getParent() !== null) {
    current = current.getParent();  // Returns Topic | null
  }
};

// ❌ WRONG - Type mismatch
const getTopicDepth = (topic: Topic): number => {
  let current = topic;  // TypeScript infers Topic
  current = current.getParent();  // ERROR: Topic | null not assignable to Topic
};

3. Use Unknown for Truly Unknown Types:

// ✅ If you truly don't know the type
const data: unknown = JSON.parse(str);
if (typeof data === 'object' && data !== null) {
  // Type guard before use
}

// ❌ WRONG
const data: any = JSON.parse(str);

8. Linting and Code Quality (CRITICAL)

MANDATORY: AI MUST check linter errors after EVERY file creation or modification.

When to Run Linter (REQUIRED):

✅ IMMEDIATELY after creating a new file
✅ IMMEDIATELY after modifying an existing file
✅ Before declaring a task complete
✅ After any code generation or refactoring

Linting Workflow (ENFORCED):

For EACH file created/modified:
1. Write/modify the code
2. IMMEDIATELY run read_lints([specific_file_path])
3. Fix ALL errors found
4. Re-run read_lints to verify
5. Only then move to next file

At task completion:
1. Run read_lints on ALL modified files together
2. Fix any remaining issues
3. Final verification
4. Task complete

How to Check Lints:

// ✅ CORRECT - Check specific files you modified
read_lints([
  "packages/editor/src/components/new-component/index.tsx",
  "packages/editor/src/components/new-component/styled.ts"
])

// ❌ WRONG - Checking entire codebase (too noisy)
read_lints()  // or read_lints([])

Common ESLint Rules to Follow:

```
@typescript-eslint/no-explicit-any
```
- NO
```
any
```
types
```
@typescript-eslint/no-unused-vars
```
- Remove unused imports/variables

@typescript-eslint/explicit-function-return-type

- Type function returns when needed

Proper null/undefined handling
Material UI imports must follow tree-shakeable pattern (see rule #2)

AI Assistant Workflow (MANDATORY):

1. Create/modify TypeScript file
2. Add proper type imports (Topic, Designer, etc.)
3. Use correct types for all variables and parameters
4. Handle nullable types with | null or | undefined
5. RUN read_lints([file_path]) - DO NOT SKIP THIS
6. Fix all errors found
7. Verify with read_lints again
8. Move to next file/task

Priority:

ZERO tolerance for linting errors in completed tasks
Fix ALL errors before declaring task complete
If a linting rule seems incorrect, discuss with user before bypassing
Never commit code with linting errors

WiseMapping Frontend Rules

Related Skills

Markdown Converter

Nano Banana Pro

1password