Migrate sorting settings to GSettings enums

[andrepg]

Description

The current sorting configuration relies on string-based GSettings keys combined with JavaScript constants. While functional, this approach allows invalid values, requires defensive string comparisons, and makes UI bindings more verbose.

This enhancement proposes migrating sorting-related settings to GSettings enums, improving type safety, schema validation, UI integration, and long-term maintainability.

[!info]
The change will be introduced in a future version to avoid breaking existing user configurations.

---

Motivation / Benefits

• Prevent invalid sorting values at the schema level
• Reduce reliance on string comparisons in JS code
• Improve integration with GNOME UI widgets
• Make sorting logic more declarative and scalable
• Align the codebase with GNOME / GJS best practices

---

Scope

This enhancement covers:

• Sorting mode (e.g. by date, by status, by title)
• Sorting strategy (e.g. ascending / descending), if applicable

---

Proposed Plan of Action

1. Update GSettings schema

• Define enum types for sorting-related keys in the .gschema.xml
• Replace string-based keys with enum-based keys
• Preserve existing default values

Example:

<enum id="org.example.SortingMode">
  <value nick="by-date" value="0"/>
  <value nick="by-status" value="1"/>
  <value nick="by-title" value="2"/>
</enum>

<key name="sorting-mode" enum="org.example.SortingMode">
  <default>'by-date'</default>
</key>

---

2. Update JavaScript constants

Ensure JS constants match the numeric enum values defined in the schema:

export const SortingModes = {
  BY_DATE: 0,
  BY_STATUS: 1,
  BY_TITLE: 2
}

---

3. Migrate settings access in code

• Replace get_string() / custom helpers with get_enum()
• Remove string comparisons where possible
• Keep public function interfaces unchanged when feasible

Example:

const current_sort_mode = this._settings.get_enum('sorting-mode')

---

4. Update sorting helper logic

• Continue using declarative mappings (e.g. label_by_mode)
• Use enum values as object keys
• Keep all translations (_()) unchanged

---

5. Handle migration of existing user settings

To preserve backward compatibility:

• Detect legacy string-based settings on startup
• Map legacy values to enum values
• Persist the enum value
• Deprecate (but do not immediately remove) legacy keys

Suggested approach:

1. Read old string key if present
2. Convert to enum value
3. Write enum-based key
4. Ignore legacy key afterward

---

6. Update documentation and comments

• Document enum usage in code
• Update developer documentation if needed

---

Checklist

• Add enum definitions to GSettings schema
• Compile and validate updated schema
• Update JS constants to numeric enums
• Replace string-based settings access with get_enum()
• Ensure translations (_()) remain unchanged
• Implement migration logic for existing users
• Test upgrade from previous version
• Test clean install
• Update developer documentation

---

Backward Compatibility Notes

• Existing user configurations must not break
• Migration logic is required for at least one release cycle
• Legacy keys should be deprecated gradually

---

References / Documentation

• GSettings API - https://developer.gnome.org/gio/stable/GSettings.html
• GSettings schema files and enums - https://developer.gnome.org/gio/stable/gsettings-schema-file.html
• GJS GSettings guide - https://gjs.guide/guides/gsettings.html

---

Optional Enhancements / Follow-ups

UI Integration with AdwComboRow

Once enums are in place, sorting mode selection can be simplified using AdwComboRow:

• Direct binding to enum-based GSettings keys
• No manual string ↔ value conversion
• Cleaner, more idiomatic GNOME UI code

Benefits:

• Reduced boilerplate
• Automatic synchronization between UI and settings
• Improved accessibility and consistency

---

Notes

This enhancement aligns the project with GNOME platform conventions and reduces long-term maintenance cost.
It should be implemented in a versioned release with clear upgrade testing.

This issue was created with help of ChatGPT and should be reviewed before going into backlog.