Skip to content

initial stage for copilot development planning and specification #1269

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
aswad32 wants to merge 1 commit into from
Closed

initial stage for copilot development planning and specification #1269

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
127 changes: 127 additions & 0 deletions .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,127 @@
# Copilot Instructions — Adminer UI Modernization

## Project Goal

This project is a fork of Adminer. The goal is to modernize the user interface while preserving Adminer's existing behavior, database support, portability, and lightweight nature.

The main objective is **UI modernization only**, not a full rewrite.

Modernization should improve:

- Visual design
- Layout clarity
- Spacing and typography
- Tables
- Forms
- Buttons
- Navigation
- Login screen
- Responsive behavior
- Optional dark mode support

The project must continue to behave like Adminer.

---

## Important Context

Adminer is a legacy-style PHP application where PHP logic and HTML output are often mixed together.

Because of this, UI changes must be made carefully. Some HTML elements are directly connected to form submission, routing, query parameters, session handling, database actions, and SQL execution.

Do not assume markup is purely visual.

---

## Absolute Rules

Copilot must follow these rules strictly:

1. Do not rewrite the application architecture.
2. Do not convert the project to React, Vue, Angular, Svelte, or any frontend SPA framework.
3. Do not change database logic.
4. Do not change SQL execution behavior.
5. Do not change authentication, session, or permission logic.
6. Do not rename existing form fields.
7. Do not remove hidden inputs.
8. Do not change form `method` or `action` attributes unless explicitly requested.
9. Do not change existing query parameters or URL behavior.
10. Do not change driver-specific database behavior.
11. Do not remove accessibility-related attributes.
12. Do not introduce large JavaScript dependencies.
13. Do not make broad changes across many screens in one step.
14. Do not optimize or refactor backend logic unless explicitly requested.
15. Do not change behavior while modernizing UI.

When uncertain, preserve the existing code behavior.

---

## Preferred Approach

Use a safe, incremental approach.

Priority order:

1. CSS-first modernization
2. Add wrapper classes around existing markup
3. Improve spacing, typography, buttons, forms, and tables
4. Refactor repeated UI output into small PHP helper functions only when safe
5. Improve one screen at a time
6. Avoid large-scale structural changes

Prefer small, reviewable pull requests.

---

## UI Modernization Strategy

Start by improving global UI styles before changing deep PHP logic.

Recommended first areas:

1. Login page
2. Main layout shell
3. Sidebar / navigation
4. Header / top actions
5. Table browsing screen
6. Forms for insert/edit/update
7. SQL command screen
8. Export/import screens
9. Messages, warnings, and error states
10. Responsive layout improvements

Each UI change should preserve existing behavior.

---

## Styling Guidelines

Prefer modern plain CSS unless otherwise instructed.

Use:

- CSS variables
- Consistent spacing scale
- Consistent border radius
- Modern typography
- Clear focus states
- Accessible color contrast
- Responsive layout
- Minimal JavaScript

Example CSS direction:

```css
:root {
--color-bg: #f8fafc;
--color-surface: #ffffff;
--color-text: #0f172a;
--color-muted: #64748b;
--color-border: #e2e8f0;
--color-primary: #2563eb;
--radius-sm: 6px;
--radius-md: 10px;
--radius-lg: 14px;
--shadow-sm: 0 1px 2px rgba(15, 23, 42, 0.08);
}
140 changes: 140 additions & 0 deletions specs/00-architecture-overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,140 @@
# Adminer UI Architecture Overview

## Purpose

This document maps the files and functions responsible for generating HTML output in Adminer. It is the reference for all UI modernization work. **Do not change behavior — only change appearance.**

---

## Request Routing

All requests enter through `adminer/index.php`, which dispatches to a specific `*.inc.php` page based on `$_GET` parameters.

| `$_GET` key | File loaded | Screen |
|---|---|---|
| _(none)_ | `db.inc.php` | Database / table list |
| `select` | `select.inc.php` | Browse table rows |
| `edit` | `edit.inc.php` | Insert / edit row |
| `table` | `table.inc.php` | Table structure |
| `create` | `create.inc.php` | Alter/create table |
| `indexes` | `indexes.inc.php` | Index management |
| `sql` | `sql.inc.php` | SQL command |
| `dump` | `dump.inc.php` | Export |
| `privileges` | `privileges.inc.php` | User privileges |
| `schema` | `schema.inc.php` | ER diagram |
| `database` | `database.inc.php` | Alter database |
| `call` / `callf` | `call.inc.php` | Stored procedure call |
| `foreign` | `foreign.inc.php` | Foreign key editor |
| `view` | `view.inc.php` | View editor |
| `procedure` / `function` | `procedure.inc.php` | Routine editor |
| `trigger` | `trigger.inc.php` | Trigger editor |
| `event` | `event.inc.php` | Event editor |
| `type` | `type.inc.php` | User-defined type editor |
| `user` | `user.inc.php` | User management |
| `processlist` | `processlist.inc.php` | Process list |
| `variables` | `variables.inc.php` | Server variables |
| `sequence` | `sequence.inc.php` | Sequence editor |
| `check` | `check.inc.php` | Check constraint editor |

Every page file calls `page_header()` at the top and relies on `page_footer()` being called at the bottom of `index.php`.

---

## HTML Shell — The Two Functions That Wrap Every Screen

### `page_header()` — `adminer/include/design.inc.php`

Outputs:
- Full `<!DOCTYPE html>` preamble, `<head>`, CSS links, JS links
- `<body>` opening with classes (`ltr`, `nojs`, `adminer`, etc.)
- `<div id="content">` wrapper
- `#menuopen` hamburger button (mobile only)
- `<p id="breadcrumb">` navigation trail
- `<h2>` page title
- Flash / error message divs (`.message`, `.error`)

### `page_footer()` — `adminer/include/design.inc.php`

Outputs:
- Closing `</div>` for `#content`
- `<div id="foot">` containing:
- `<div id="menu">` — sidebar navigation (rendered by `navigation()`)
- Logout `<form>` with username display and `<input type="submit" name="logout">`

---

## CSS Files

| File | Role |
|---|---|
| `adminer/static/default.css` | Main stylesheet (light mode + layout) |
| `adminer/static/dark.css` | Dark mode overrides |
| `externals/jush/jush.css` | Syntax highlight (light) |
| `externals/jush/jush-dark.css` | Syntax highlight (dark) |
| `adminer.css` / `adminer-dark.css` | Optional per-deployment custom CSS (loaded via `Adminer::css()`) |

CSS is loaded from `Adminer::head()` and `page_header()`. The active color scheme is determined by `adminer()->css()` and whether `prefers-color-scheme: dark` is referenced in the custom CSS.

---

## JavaScript Files

| File | Role |
|---|---|
| `adminer/static/functions.js` | Core utilities: DOM helpers (`qs`, `qsl`, `qsa`), `mixin`, `toggle`, `cookie`, AJAX helpers |
| `adminer/static/editing.js` | Form behavior: file uploads, field change handlers, select-table click, inline edit |

No large JS framework is used. All interactivity is hand-rolled vanilla JS.

---

## CSS Variable System (current)

The existing stylesheet uses four CSS variables defined on `html {}`:

```css
--bg /* page background */
--fg /* foreground text */
--dim /* dimmed surface (header, table headers, hover) */
--lit /* highlighted surface (breadcrumb, thead, focus target) */
```

These are minimal and must be kept. Modernization should expand this system with new variables without removing these four.

---

## Key HTML IDs and Classes (do not rename)

These IDs and classes are referenced by PHP logic, existing JavaScript, or designs:

| Selector | Used by |
|---|---|
| `#content` | Layout: main area offset from sidebar |
| `#foot` | Layout: sidebar + footer container |
| `#menu` | Navigation sidebar |
| `#menuopen` | Mobile hamburger toggle |
| `#breadcrumb` | Navigation breadcrumb |
| `#logins` | Login session list in sidebar |
| `#tables` | Table list in sidebar |
| `#dbs` | Database list in sidebar |
| `#help` | Inline SQL help popup |
| `#ajaxstatus` | AJAX loading indicator |
| `#logout` | Logout submit button |
| `.message` | Success flash messages |
| `.error` | Error messages |
| `.hidden` | JS show/hide toggle |
| `.jsonly` | Shown only when JS is active |
| `.nojs` | Shown only without JS |
| `.active` | Active nav item (bold) |
| `.links` | Action link bar under headings |
| `.nowrap` | Table with no-wrap cells |
| `.checkable` | Selectable table rows |
| `.checked` | Selected row highlight |
| `.odds` | Alternating row colors |
| `.scrollable` | Horizontally scrollable table wrapper |
| `.footer` | Sticky bottom action bar in select |
| `.icon` | Icon buttons (background-image based) |
| `.function` | Right-aligned function select cell in edit form |
| `.sqlarea` | Full-width SQL textarea |
| `.layout` | Login form table |
| `form#form` | Main select/search form |
Loading
Loading