Display Settings Widget

Relevant source files

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

• src/components/widget/DisplaySettings.svelte
• src/utils/setting-utils.ts
• src/config.ts
• src/types/config.ts
• src/components/LightDarkSwitch.svelte
• src/constants/constants.ts

The Display Settings widget is a Svelte component that provides users with real-time customization of the website's visual appearance. It allows for adjusting the primary theme color (hue) and the background color style of card elements. All settings are persisted in the browser's localStorage to maintain user preferences across sessions.

This widget is part of a broader settings system that also includes light/dark mode switching, managed through a centralized utility module. The configuration for default values is sourced from the main site configuration file.

Sources: src/components/widget/DisplaySettings.svelte, src/utils/setting-utils.ts, src/config.ts

Architecture and Data Flow

The system's architecture separates the UI component (DisplaySettings.svelte) from the business logic (setting-utils.ts). The component handles user interaction and state management, while the utility module manages the persistence of settings to localStorage and applies the changes to the DOM by manipulating CSS custom properties.

The following diagram illustrates the overall data flow when a user changes a setting.

This diagram shows the sequence of events from user interaction to the final application of styles on the page.

Sources: src/components/widget/DisplaySettings.svelte:19-25, src/utils/setting-utils.ts:19-27, 80-92

Features

The widget offers two primary customization features.

Theme Color (Hue) Control

Users can adjust the site's primary color hue using a range slider.

• UI Element: An <input type="range"> slider allows selecting a hue value from 0 to 360 in steps of 5.
• State Management: The component's hue variable is initialized by calling getHue() from setting-utils.ts. Any change to the slider updates this variable.
• Persistence: A Svelte reactive statement ($:) detects changes to the hue variable and calls setHue(hue) to persist the value to localStorage and update the --hue CSS custom property on the :root element.
• Reset Functionality: A "Reset" button restores the hue to its default value, which is retrieved via getDefaultHue(). The default is configured in src/config.ts.

Sources: src/components/widget/DisplaySettings.svelte:11, 15, 19-21, 38-40, src/utils/setting-utils.ts:8-27, src/config.ts:11

The flow for updating the theme hue is as follows:

This diagram shows how a user's action on the slider triggers a series of function calls that persist the setting and update the live styles.

Sources: src/components/widget/DisplaySettings.svelte:19-21, src/utils/setting-utils.ts:19-27

Card Background Color Control

This feature allows users to choose between two styles for card backgrounds.

• UI Element: A set of radio buttons provides two options: "White" and "Themed".
• State Management: The cardBgType variable holds the current selection. It is initialized using getCardBgType().
• Persistence: When a user selects an option, the on:change event triggers switchCardBgType(), which updates the component's state. A reactive statement then calls setCardBgType() to save the choice in localStorage and update the --card-bg CSS custom property.
  • CARD_BG_TYPE.WHITE (value 0): Sets --card-bg to var(--card-bg-original).
  • CARD_BG_TYPE.THEMED (value 1): Sets --card-bg to var(--card-bg-themed).

Sources: src/components/widget/DisplaySettings.svelte:14, 17, 23-28, 50-57, src/utils/setting-utils.ts:71-92

The flow for updating the card background is as follows:

This diagram outlines the process from selecting a radio button to the application of the corresponding card background style.

Sources: src/components/widget/DisplaySettings.svelte:23-28, src/utils/setting-utils.ts:80-92

Key Utility Functions

The core logic for managing settings is centralized in src/utils/setting-utils.ts.

Function	Description	Source File
getDefaultHue()	Retrieves the default hue from a #config-carrier DOM element's data-hue attribute.	src/utils/setting-utils.ts:8-12
getHue()	Gets the current hue from localStorage, falling back to getDefaultHue().	src/utils/setting-utils.ts:14-17
setHue(hue)	Persists the hue to localStorage and applies it to the --hue CSS variable on the :root element.	src/utils/setting-utils.ts:19-27
getCardBgType()	Gets the card background type from localStorage, falling back to the default (CARD_BG_TYPE.WHITE).	src/utils/setting-utils.ts:75-78
setCardBgType(type)	Persists the card background type to localStorage and updates the --card-bg CSS variable accordingly.	src/utils/setting-utils.ts:80-92

This module also handles light/dark/auto theme switching, demonstrating a consistent pattern for managing user-facing display options.

Sources: src/utils/setting-utils.ts, src/components/LightDarkSwitch.svelte:15-17

Configuration

Default values and behavior are controlled by the main site configuration.

Property	Description	Default Value	Source File
siteConfig.themeColor.hue	The default hue value for the theme.	65	src/config.ts:11
siteConfig.themeColor.fixed	If true, the theme color selector is hidden from the user.	false	src/config.ts:12
CARD_BG_TYPE.WHITE	Constant representing the white card background option.	0	src/utils/setting-utils.ts:72
CARD_BG_TYPE.THEMED	Constant representing the themed card background option.	1	src/utils/setting-utils.ts:73

The type definitions for these configurations are specified in src/types/config.ts.

Sources: src/config.ts:10-13, src/types/config.ts:11-14, src/utils/setting-utils.ts:71-74