Utility Functions

Relevant source files

The following files were used as context for generating this wiki page:

• src/lib/utils.ts
• src/lib/exportUtils.ts
• src/hooks/useTheme.ts
• src/lib/themes.ts
• src/store/useSheetStore.ts
• src/components/layout/TopBar.tsx

The Character Sheet Maker project relies on a set of utility functions, custom hooks, and configuration files to provide shared, reusable logic across the application. These utilities handle concerns such as dynamic styling, state management actions, sheet exporting, and theme management. They are crucial for maintaining a clean and modular codebase by separating these cross-cutting concerns from the UI components.

This document outlines the key utility modules, their purpose, and how they are used within the application.

Styling Utilities

cn - Dynamic ClassName Merging

The primary styling utility is the cn function, which provides a convenient way to conditionally apply and merge Tailwind CSS classes. It is a wrapper around the clsx and tailwind-merge libraries.

• clsx: Allows for defining class names using strings, objects, or arrays, making it easy to apply classes conditionally.
• tailwind-merge: Intelligently merges Tailwind CSS classes, resolving conflicts (e.g., merging p-2 and p-4 into just p-4) without manual intervention.

This function is imported and used extensively throughout the component files to manage dynamic styles based on component state or props.

Sources: src/lib/utils.ts:1-7

The following diagram illustrates the flow of the cn function.

Export Utilities

The application provides functionality to export the character sheet canvas as a PNG image or a PDF document. These features are handled by utility functions in src/lib/exportUtils.ts, which leverage the html-to-image and jspdf libraries.

Sources: src/lib/exportUtils.ts, package.json:13,14

Functions

Function	Description	Dependencies
downloadAsImage	Finds the canvas element by its ID (rpg-sheet-canvas), converts it to a PNG data URL using toPng, and triggers a browser download.	html-to-image
downloadAsPDF	First converts the canvas to a PNG data URL, then creates a new A4-sized jsPDF document, calculates the proportional image dimensions to fit the page width, adds the image, and saves the PDF.	html-to-image, jspdf

Sources: src/lib/exportUtils.ts:4-19, src/lib/exportUtils.ts:21-40

PDF Export Flow

The process for exporting a PDF involves first generating an image and then embedding it into a PDF document.

Theme Management

Theme management is split into two main parts: a configuration file defining the available themes and a custom hook to manage the application's current theme (light/dark mode and sheet styles).

Theme Configuration

The THEMES constant, defined in src/lib/themes.ts, is an object that holds the styling configurations for different character sheet aesthetics. Each theme specifies fonts, colors, and block-specific CSS classes.

The structure is defined by the ThemeConfig interface.

Key	Type	Description
name	string	The display name of the theme.
fonts	{ heading: string, body: string }	Font-family strings for headers and body text.
colors	{ text: string, ... }	Tailwind CSS class strings for various colors.
blocks	{ header: object, ... }	Tailwind CSS classes for specific block types.

Sources: src/lib/themes.ts:4-29

Currently, the following themes are defined:

• simple: "Modern Clean"
• medieval: "Ancient Scroll"
• cyberpunk: "Neon Future"

Sources: src/lib/themes.ts:31-112

useTheme Hook

The useTheme custom hook manages the application's light and dark mode. It is a self-contained unit that handles state, side effects, and interaction with localStorage.

Its core responsibilities are:

1. Initialization: On first load, it reads the theme from localStorage or falls back to the user's system preference (prefers-color-scheme).
2. State Management: Uses a useState hook to hold the current theme ("light" or "dark").
3. Side Effects: A useEffect hook runs whenever the theme changes. It updates the class on the root <html> element and persists the new theme value to localStorage.
4. Toggler Function: Exposes a toggleTheme function to switch between light and dark modes.

Sources: src/hooks/useTheme.ts:3-28

The following sequence diagram shows how the useTheme hook and a component interact.

State Management Actions

While the entire state is managed by Zustand in useSheetStore, the actions exported from the store can be considered utility functions for manipulating the application's state from components. These actions abstract the logic of updating the immutable state tree.

Key actions include:

• addBlock: Adds a new block of a specified type to the canvas.
• removeBlock: Removes a block by its ID.
• updateBlockData: Updates the data property of a specific block.
• updateLayout: Syncs the layout changes from react-grid-layout back to the store.
• setTheme: Updates the globalStyle.theme property in the state.

Sources: src/store/useSheetStore.ts:41-47

This diagram shows how a component (e.g., ToolsSidebar) uses an action from the store to update the application state.

Conclusion

The utility functions, hooks, and configurations are fundamental to the Character Sheet Maker's architecture. They promote a separation of concerns, enhance code reusability, and simplify component logic. By centralizing functionality like styling, exporting, and state manipulation, the application becomes more maintainable and easier to extend.