# stillExplore

A modern, configurable application showcase tool built with GTK4 and libadwaita. Originally designed to showcase stillOS features and applications, but fully customizable for any use case through JSON configuration.

## Overview

stillExplore provides a clean, native interface for showcasing applications, tools, and resources through a customizable sidebar navigation system. While it ships with stillOS branding and content, **the entire interface can be completely rebranded and reconfigured** by simply providing your own configuration file.

## Features

- **Modern libadwaita Interface**: Native GTK4/libadwaita design that follows GNOME HIG
- **Sidebar Navigation**: Clean navigation split view with page switching
- **Fully Configurable**: Every aspect controllable through JSON configuration
- **Action Support**: Launch applications, open URLs, or run commands
- **Preference Groups**: Organized content using libadwaita PreferencesGroup
- **Custom Branding**: Override app title, page names, descriptions, and icons
- **Responsive Design**: Adapts to different window sizes
- **Proper Installation**: Full FHS-compliant installation with desktop integration

## Installation

### Dependencies

- GTK4
- libadwaita-1 
- json-glib-1.0
- libgee-0.8
- Vala compiler
- Meson build system (>= 0.59.0)

### Quick Install

For testing and development:

```bash
./install.sh
```

This will install to `/usr` if run as root, or `~/.local` if run as a regular user.

### Building from Source

```bash
meson setup builddir --prefix=/usr
ninja -C builddir
sudo ninja -C builddir install
```

### Testing Without Installing

To quickly build and test without installing:

```bash
./test.sh
```

### Uninstalling

```bash
./uninstall.sh
```

## Configuration

The application is entirely driven by a JSON configuration file. After installation, the configuration is located at:
- System: `/usr/share/stillexplore/config.json`
- User: `~/.local/share/stillexplore/config.json`

### Configuration Schema

The configuration follows this structure:

#### Root Object

```json
{
  "app": { ... },
  "pages": [ ... ]
}
```

#### App Configuration

```json
{
  "app": {
    "app_title": "Your Application Name"
  }
}
```

- `app_title` (string, required): The main application title displayed in headers

#### Pages Array

```json
{
  "pages": [
    {
      "id": "unique-page-id",
      "title": "Page Title",
      "titlebar": "Optional Titlebar Text", 
      "icon": "icon-name",
      "groups": [ ... ]
    }
  ]
}
```

- `id` (string, required): Unique identifier for the page
- `title` (string, required): Page title shown in navigation sidebar
- `titlebar` (string, optional): Custom title for the page header (defaults to `title`)
- `icon` (string, optional): Icon name for the page
- `groups` (array, required): Array of preference groups

#### Groups Array

```json
{
  "groups": [
    {
      "title": "Group Title",
      "description": "Optional group description",
      "actions": [ ... ]
    }
  ]
}
```

- `title` (string, required): Group title displayed as header
- `description` (string, optional): Description text shown below title
- `actions` (array, required): Array of action items

#### Actions Array

```json
{
  "actions": [
    {
      "title": "Action Title",
      "description": "Action description",
      "icon": "icon-name",
      "svg": "custom-icon.svg",
      "action": {
        "type": "application|url|command",
        "target": "application-id|url|command",
        "button_name": "Custom Button Text",
        "button_style_class": "suggested|destructive|flat"
      }
    }
  ]
}
```

- `title` (string, required): Action title displayed prominently
- `description` (string, optional): Subtitle/description text
- `icon` (string, optional): Icon name from icon theme
- `svg` (string, optional): Custom SVG file from data/icons/ directory (takes priority over `icon`)
- `action` (object, required): Action configuration

#### Action Object

- `type` (string, required): One of:
  - `"application"`: Launch an application
  - `"url"`: Open a URL in default browser
  - `"command"`: Execute a shell command
- `target` (string, required): The application ID, URL, or command to execute
- `button_name` (string, optional): Custom text for the action button (default: "Open")
- `button_style_class` (string, optional): CSS class for button styling

### Example Configuration

```json
{
  "app": {
    "app_title": "My Custom Showcase"
  },
  "pages": [
    {
      "id": "applications",
      "title": "Applications",
      "titlebar": "Featured Applications",
      "groups": [
        {
          "title": "Development Tools",
          "description": "Essential tools for developers",
          "actions": [
            {
              "title": "VS Code",
              "description": "Modern code editor with extensive plugin support",
              "icon": "com.visualstudio.code",
              "action": {
                "type": "application",
                "target": "code",
                "button_name": "Launch",
                "button_style_class": "suggested"
              }
            },
            {
              "title": "GitHub",
              "description": "Version control and collaboration platform",
              "icon": "web-browser",
              "action": {
                "type": "url", 
                "target": "https://github.com"
              }
            }
          ]
        }
      ]
    }
  ]
}
```

## Building RPM Packages

A spec file is provided for building RPM packages:

```bash
# From a source tarball
rpmbuild -tb stillexplore-1.0.tar.gz

# Or using the spec file directly
rpmbuild -ba stillexplore.spec
```

## Customization

To completely rebrand the application:

1. Fork/clone the repository
2. Edit `data/config.json` with your own content
3. Replace icons in `data/icons/` with your own
4. Replace `src/data/io.stillhq.explore.svg` with your application icon
5. Optionally edit `src/data/io.stillhq.explore.desktop` to customize the desktop entry
6. Build and install

The application will completely transform to match your configuration - no stillOS branding will remain except in the desktop file name (which can be changed by modifying `meson.build`).

## Use Cases

- **Distribution Welcome Screens**: Welcome new users to your Linux distribution
- **Project Showcases**: Highlight your applications and tools
- **System Utilities**: Create a launcher for administrative tools
- **Resource Centers**: Organize documentation, websites, and applications
- **Kiosk Interfaces**: Provide controlled access to specific applications
- **Demo Environments**: Showcase software collections

## Development

### Project Structure

```
├── src/
│   ├── main.vala          # Application entry point
│   ├── window.vala        # Main window and UI logic
│   ├── config.vala        # Configuration loading and data structures
│   ├── utils.vala         # Utility functions
│   ├── paths.vala.in      # Path configuration template
│   └── data/
│       ├── io.stillhq.explore.desktop  # Desktop entry
│       └── io.stillhq.explore.svg      # Application icon
├── data/
│   ├── config.json        # Default configuration
│   └── icons/             # Custom SVG icons
├── meson.build            # Build configuration
├── stillexplore.spec      # RPM spec file
├── install.sh             # Installation script
├── uninstall.sh           # Uninstallation script
└── test.sh                # Quick test script
```

### Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with different configurations
5. Submit a pull request

### Adding Features

When extending the application:
- Update the config data structures in `src/config.vala`
- Add handling in `src/window.vala`
- Update this README with new configuration options
- Consider updating `data/config-schema.json` if it exists

## License

This project is licensed under the GPL-3.0-or-later License. See the LICENSE file for details.

## Credits

Built with:
- [GTK4](https://gtk.org/) - The widget toolkit
- [libadwaita](https://gnome.pages.gitlab.gnome.org/libadwaita/) - GNOME's application development library
- [Vala](https://vala.dev/) - Programming language
- [Meson](https://mesonbuild.com/) - Build system

Originally created for stillOS by stillHQ.
