Troubleshooting
Relevant source files
The following files were used as context for generating this wiki page:
This guide provides technical details for identifying and resolving issues within the @pcstyle/ui library. It focuses on theme synchronization, build-time configurations, and runtime component errors. The library utilizes a React-based provider system to manage state and visual effects across two primary modes: cyber and minimal.
Sources: package.json:2-4, src/provider/index.tsx:18-21
Context and Provider Issues
The most common runtime error occurs when components are used outside the UIProvider hierarchy. This is enforced by the useUI custom hook, which validates the presence of the UIContext.
Missing Provider Error
Components such as Button, Input, and Card rely on the useUI hook to determine their visual style. If the context is undefined, the library throws a specific error.
The diagram shows the logic flow for theme access within library components.
Sources: src/provider/index.tsx:43-49
Form and Input Validation
The Input component provides a visual feedback mechanism for displaying error states. When an error string is passed to the component, it renders a specialized error message with a unique prefix.
| Field | Type | Description | Cyber Style | Minimal Style |
|---|---|---|---|---|
label | string | Optional field label | Neon Pink (#ff00ff/60) | Zinc 500 |
error | string | Error message text | Neon Red (#ff0000) | Red 500 |
ERROR_CODE | string | Prefix for error display | Uppercase, Font-Black | Uppercase, Font-Black |
Sources: src/components/forms/Input.tsx:10-39
Theme Synchronization Failures
The UIProvider synchronizes the selected theme with the document root through CSS variables and data attributes. If themes are not applying correctly to non-component elements, verify the document.documentElement attributes.
Synchronization Logic
The provider executes an effect whenever the theme changes, performing the following actions:
- Iterates through the
colors[theme]object. - Sets CSS variables using the
--pc-{key}naming convention. - Updates the
data-pc-themeattribute on the root element.
The sequence shows how state changes propagate to the DOM for global styling.
Sources: src/provider/index.tsx:28-38
Effect and Overlay Troubleshooting
Visual effects like the NeuralCursor and CRTOverlay are conditional and performance-sensitive.
Effect Visibility Matrix
If an effect is not appearing, check the current theme and device type:
| Effect | Condition | Target Element | Visibility |
|---|---|---|---|
NeuralCursor | theme === "cyber" | lg:block (Desktop) | Hidden on mobile |
CRTOverlay | theme === "cyber" | fixed inset-0 | Hidden in minimal theme |
Sources: src/effects/neural-cursor.tsx:28-30, src/effects/crt-overlay.tsx:10-12
Neural Cursor Lag
The NeuralCursor uses a delayed mouse position logic. If the secondary "glow" dot is not following correctly, ensure the mousemove event listener is active on the window object.
Sources: src/effects/neural-cursor.tsx:8-16, src/effects/neural-cursor.tsx:23-26
Build and Type Safety Constraints
The project enforces strict standards via tsconfig.json and cubic.yaml to prevent runtime failures.
Common Build Issues
- Type Safety: The project prohibits
anytypes and non-null assertions. - Module Resolution: Uses
ESNextmodules withbundlerresolution. - Target: Targets
ES2020.
{
"compilerOptions": {
"target": "ES2020",
"module": "ESNext",
"strict": true,
"jsx": "react-jsx"
}
}
Sources: tsconfig.json:3-14, cubic.yaml:23-26
Summary
Troubleshooting the @pcstyle/ui library primarily involves ensuring the UIProvider is correctly wrapped around the application and verifying that the cyber theme requirements are met for advanced visual effects. Developers should monitor the data-pc-theme attribute for synchronization issues and adhere to the strict TypeScript configuration to ensure build stability.