Settings & Configuration UI
Relevant source files
The following files were used as context for generating this wiki page:
The Settings & Configuration UI provides a structured framework for building application preference pages. It consists of a multi-level navigation system, categorized sections, and standardized form fields designed to maintain visual consistency across complex configuration interfaces. The system utilizes a "card-per-section" layout where individual settings are organized into rows within distinct modules.
This module is categorized under "Layout Components" (版式件) within the HX-UI library. It defines the high-level appearance of configuration pages, including sidebar navigation, section headers, and data entry rows.
Sources: src/index.ts:7-12, src/layout/SettingChrome.tsx:1-5
Core Layout Components
The system relies on three primary components to build the settings interface: SettingSection, SettingRow, and SettingHeading. These components enforce a consistent hierarchy and spacing.
SettingSection and SettingRow
SettingSection acts as a container that groups related settings into a card-like interface with a rounded border. Inside these sections, SettingRow provides a flexbox-based layout that aligns labels and descriptions on the left with interactive controls on the right.
The diagram shows the hierarchical relationship between sections and individual rows within the configuration UI.
Sources: src/layout/SettingChrome.tsx:14-87
Component Specifications
| Component | Purpose | Key Properties |
|---|---|---|
SettingSection | Groups related settings into a card. | section (Meta), title, description, children |
SettingRow | Displays a single setting item. | title, description, border (boolean), children |
SettingHeading | Provides a standalone section title. | section (Meta), title, className |
Sources: src/layout/SettingChrome.tsx:14-106
Navigation and Sidebar Structure
The SettingsSidebarView manages the secondary navigation tier for configuration pages. It supports a hierarchical structure consisting of tabs and optional child items.
Navigation Logic
The sidebar handles two primary states: standard width (200px) and narrow (14 pixels). It supports "Deep Linking" where selecting a child item automatically expands and highlights the parent tab.
The flow shows how the sidebar dynamically expands parent categories based on the active tab or active child key.
Sources: src/layout/SettingsSidebarView.tsx:39-118
Sidebar Data Structures
The sidebar is driven by the SettingsSidebarTabItem interface:
key: Unique identifier for the tab.label: Display text.icon: Icon class name.children: Optional array ofSettingsSidebarChildItemfor nested navigation.
Sources: src/layout/SettingsSidebarView.tsx:4-21
Form Fields and Controls
Configuration inputs are standardized through the SettingsFormFields.tsx and specialized layout controls like SegmentedControl.
Standardized Inputs
The UI provides specialized field wrappers for common inputs to ensure they fit the SettingRow layout constraints:
SelectField: Standard dropdown selection.InputField: Text and numeric input.TextareaField: Multi-line text input.
Sources: src/index.ts:51-54, src/layout/SettingsFormFields.tsx
SegmentedControl
Used for switching between mutually exclusive views or small sets of options. It features a Framer Motion-powered layout animation for the selection indicator.
This diagram illustrates the reactive update and animation flow when a user interacts with a segmented control.
Sources: src/layout/SegmentedControl.tsx:38-100
Page Headers
The PageHeader component provides the top-level identity for configuration pages. It enforces a strict layout where the title and right-side actions (such as "Save" or "Reset" buttons) remain vertically baseline-aligned to prevent layout shifts.
- Truncation: Titles use the
truncateclass to prevent long text from pushing action buttons out of the viewport. - Compact Mode: Supports a smaller font size (
--fs-lgvs--fs-2xl) for use inside cards or drawers.
Sources: src/layout/PageHeader.tsx:1-55
Summary
The Settings & Configuration UI in HX-UI provides a robust framework for complex application settings. By utilizing standardized SettingSection and SettingRow components alongside a dynamic SettingsSidebarView, it ensures that even pages with numerous configuration options remain legible and consistent. The system is strictly governed by design tokens, ensuring that layout metrics like the 24rem maximum control width are maintained across all configuration fields.
Sources: src/layout/SettingChrome.tsx:31, src/layout/PageHeader.tsx:18-20