mirror of
https://github.com/Ku6epXBOCTuK/easy-png-tools.git
synced 2026-09-17 15:06:36 +00:00
docs: update plan for field audit
This commit is contained in:
@@ -0,0 +1,388 @@
|
||||
# План: исправления по аудиту UX/UI
|
||||
|
||||
> Статус: **draft** — на ревью.
|
||||
>
|
||||
> Источник: `docs/tools-audit.md`. Этот документ разбивает аудит на конкретные
|
||||
> шаги, группирует по типу работы и фиксирует решения.
|
||||
|
||||
## 0. Ключевое решение: select → buttons
|
||||
|
||||
Существующий `Segmented.svelte` — компонент с группированными кнопками (общая
|
||||
рамка, разделители между сегментами). Для параметров инструментов он не
|
||||
подходит: при 3+ опциях сегменты сжимаются, текст не читается.
|
||||
|
||||
**Решение:** новый компонент `ButtonsControl` — раздельные outline-кнопки с
|
||||
отступами. Каждая опция — отдельная `<button>` со своей рамкой, активная
|
||||
подсвечивается заливкой (`--color-main`). Не зависит от `Segmented`.
|
||||
|
||||
### Компонент `ButtonsControl`
|
||||
|
||||
```svelte
|
||||
<!-- web/src/lib/components/fields/schema/ButtonsControl.svelte -->
|
||||
<div class="buttons" role="group">
|
||||
{#each options as opt}
|
||||
<button
|
||||
class="btn"
|
||||
class:selected={value === opt.value}
|
||||
aria-pressed={value === opt.value}
|
||||
onclick={() => select(opt.value)}
|
||||
>{opt.label}</button>
|
||||
{/each}
|
||||
</div>
|
||||
```
|
||||
|
||||
```css
|
||||
.buttons {
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
gap: var(--space-m);
|
||||
}
|
||||
.btn {
|
||||
padding: var(--space-m) var(--space-l);
|
||||
border: var(--size-border) solid var(--color-border);
|
||||
border-radius: var(--radius-s);
|
||||
font: var(--font-size-s) var(--font-mono);
|
||||
color: var(--color-text-muted);
|
||||
background: transparent;
|
||||
cursor: pointer;
|
||||
}
|
||||
.btn.selected {
|
||||
background: var(--color-main);
|
||||
color: var(--color-background);
|
||||
border-color: var(--color-main);
|
||||
}
|
||||
```
|
||||
|
||||
### Схема: `field.buttons()`
|
||||
|
||||
Новый тип в `registry-schema.ts`:
|
||||
|
||||
```ts
|
||||
export interface ButtonsSpec<V extends string = string> extends FieldSpecBase {
|
||||
kind: "buttons";
|
||||
default: V;
|
||||
options: { value: V; label: string }[];
|
||||
}
|
||||
```
|
||||
|
||||
Фабрика:
|
||||
|
||||
```ts
|
||||
buttons: <V extends string>(s: Omit<ButtonsSpec<V>, "kind">): Field<V> => ({
|
||||
spec: { kind: "buttons", ...s },
|
||||
}),
|
||||
```
|
||||
|
||||
Регистрация: добавить `"buttons": {} as ButtonsSpec` в `fieldSpecs`, добавить
|
||||
`ButtonsControl` в `FIELDS` в `SchemaFields.svelte`, добавить дефолт/санитайз в
|
||||
`sanitizeSchemaParams` и `defaultSchemaParams`.
|
||||
|
||||
---
|
||||
|
||||
## 1. Волна A — инфраструктура (1 коммит)
|
||||
|
||||
### Шаг A1. Новый тип `buttons` в схеме
|
||||
|
||||
Файлы:
|
||||
|
||||
- `web/src/lib/registry-schema.ts` — `ButtonsSpec`, фабрика `field.buttons()`,
|
||||
кейс в `sanitizeSchemaParams`, кейс в `defaultSchemaParams`
|
||||
- `web/src/lib/components/fields/schema/ButtonsControl.svelte` — новый компонент
|
||||
- `web/src/lib/components/SchemaFields.svelte` — импорт + запись в `FIELDS`
|
||||
|
||||
### Шаг A2. Seed → input + randomize
|
||||
|
||||
Для `field.number()` с `kind: "seed"` (или новый подтип `field.seed()`) —
|
||||
рендерить поле ввода + кнопку «Random» вместо range slider.
|
||||
|
||||
Решение: новый вид `field.seed()` (наследует от number, но рендерится иначе).
|
||||
Или проще: опциональное поле `variant?: "seed"` в `NumberSpec` — тогда
|
||||
`RangeControl` покажет input + кнопку.
|
||||
|
||||
Решение: **`variant: "seed"` в `NumberSpec`** — меньше новых типов.
|
||||
|
||||
Файлы:
|
||||
|
||||
- `web/src/lib/registry-schema.ts` — `NumberSpec.variant?: "seed"`
|
||||
- `web/src/lib/components/fields/schema/RangeControl.svelte` — условный рендер
|
||||
- `web/src/lib/registry/filters.ts` — `randomizePixels`, `addNoise`: поле seed →
|
||||
`{ ...field.number(...), spec: { ...spec, variant: "seed" } }` (или
|
||||
пересоздать через `field.seed()`)
|
||||
|
||||
---
|
||||
|
||||
## 2. Волна B — select → buttons (по файлам)
|
||||
|
||||
Каждый шаг — один коммит, < 500 строк. Меняем `field.select()` →
|
||||
`field.buttons()` в перечисленных ниже схемах.
|
||||
|
||||
### B1. geometry.ts (8 инструментов)
|
||||
|
||||
| Инструмент | Поле | Опции |
|
||||
| ----------------------- | -------- | ----------------------------------------- |
|
||||
| rotate-png | angle | 90° / 180° / 270° |
|
||||
| flip-png | axis | horizontal / vertical |
|
||||
| swap-orientation-png | target | portrait / landscape |
|
||||
| symmetric-copy-png | axis | vertical / horizontal |
|
||||
| symmetric-copy-png | keepSide | left / right / top / bottom |
|
||||
| change-aspect-ratio-png | ratio | 1:1 / 4:3 / 3:4 / 3:2 / 2:3 / 16:9 / 9:16 |
|
||||
| change-aspect-ratio-png | mode | crop / pad |
|
||||
|
||||
**Исключение:** `change-canvas-size-png` (anchor, 9 опций) — оставить
|
||||
`field.select()`, т.к. 9 кнопок в ряд не поместятся. Аналогично `position9` (уже
|
||||
отдельный компонент `PositionControl`).
|
||||
|
||||
### B2. color.ts (4 инструмента)
|
||||
|
||||
| Инструмент | Поле | Опции |
|
||||
| ------------------------ | --------- | ------------------------------------ |
|
||||
| dithering-png | pattern | floyd-steinberg / bayer |
|
||||
| extract-channel-png | channel | red / green / blue |
|
||||
| swap-channels-png | pair | r-g / r-b / g-b |
|
||||
| decrease-color-count-png | maxColors | 2 / 4 / 8 / 16 / 32 / 64 / 128 / 256 |
|
||||
|
||||
**Исключение:** channel spaces (hsl/hsv/... component) — 3-6 опций, но это
|
||||
динамические инструменты, оставить `select`.
|
||||
|
||||
### B3. analyze.ts (5 инструментов)
|
||||
|
||||
| Инструмент | Поле | Опции |
|
||||
| ------------------------- | ---- | ------------------ |
|
||||
| show-transparent-png | mode | binary / highlight |
|
||||
| show-grayscale-pixels-png | mode | (тот же) |
|
||||
| show-color-pixels-png | mode | (тот же) |
|
||||
| light-pixel-mask-png | mode | (тот же) |
|
||||
| dark-pixel-mask-png | mode | (тот же) |
|
||||
|
||||
Все используют общий `maskBaseFields` — правка в одном месте.
|
||||
|
||||
### B4. filters.ts (1 инструмент)
|
||||
|
||||
| Инструмент | Поле | Опции |
|
||||
| ------------- | ---- | ------------ |
|
||||
| add-noise-png | mode | mono / color |
|
||||
|
||||
### B5. generate.ts (12 инструментов)
|
||||
|
||||
| Инструмент | Поле | Опции |
|
||||
| ------------------ | ------------ | --------------------- |
|
||||
| color-spectrum-png | direction | horizontal / vertical |
|
||||
| step-colors-png | layout | grid / strip |
|
||||
| complementary-png | layout | grid / strip |
|
||||
| triadic-png | layout | grid / strip |
|
||||
| tetradic-png | layout | grid / strip |
|
||||
| analogous-png | layout | grid / strip |
|
||||
| monochromatic-png | layout | grid / strip |
|
||||
| shades-png | layout | grid / strip |
|
||||
| sort-colors-png | layout | grid / strip |
|
||||
| mix-colors-png | (нет select) | — |
|
||||
|
||||
---
|
||||
|
||||
## 3. Волна C — обязательные фиксы (баги + дефолты)
|
||||
|
||||
### C1. resize-png: дефолт 0×0 → осмысленный
|
||||
|
||||
`geometry.ts`: `width: 0, height: 0` → `width: 512, height: 512` (или
|
||||
`width: imgWidth, height: imgHeight` — но дефолт в схеме не может знать размер
|
||||
изображения). **Решение:** дефолт `512×512`.
|
||||
|
||||
### C2. symmetric-copy-png: "keep side" не работает
|
||||
|
||||
Баг в `run()`: `keepSide` не учитывает `axis`. При `axis: "vertical"` (удвоение
|
||||
ширины) работают только `left`/`right`, `top`/`bottom` не имеют смысла. Нужно:
|
||||
либо фильтровать опции `keepSide` в зависимости от `axis` (reactive schema),
|
||||
либо нормализовать в `run()`.
|
||||
|
||||
**Решение:** reactive — при смене `axis` сбрасывать `keepSide` на допустимое
|
||||
значение. Пока достаточно в `run()`: если `axis === "vertical"` и `keepSide` ∈
|
||||
{top, bottom} → заменить на `left`.
|
||||
|
||||
### C3. Механизм проброса размеров картинки в схему
|
||||
|
||||
**Проблема.** Поля, значения которых зависят от размеров исходника (crop x/y,
|
||||
resize, offsets), объявлены в статической схеме (`-100000…100000`), а реальная
|
||||
картинка обычно 800–4000px. Диапазон надо считать от фактического размера
|
||||
изображения, а не от потолков.
|
||||
|
||||
**Что нужно спроектировать и завести:**
|
||||
|
||||
1. **Где берём размер.** `SchemaToolView` уже знает размер после `decodeFile()`
|
||||
→ `PixelImage` (width/height). Сейчас он никуда не пробрасывается — надо
|
||||
прокинуть в `SchemaFields` и дальше в контролы, например через context или
|
||||
проп `sourceSize`.
|
||||
|
||||
2. **Как схеме описать зависимость.** В спеках добавить ссылку на размер
|
||||
источника вместо жёстких чисел. Кандидат:
|
||||
|
||||
```ts
|
||||
x: field.slider({
|
||||
label: "fields.x",
|
||||
bound: "sourceWidth", // min/max = ±sourceWidth
|
||||
default: 0,
|
||||
}),
|
||||
```
|
||||
|
||||
`BoundSpec = "sourceWidth" | "sourceHeight" | "minSide" | "maxSide"`,
|
||||
применимо к `NumberSpec`, `SliderSpec`, `OffsetSpec`, `DimensionSpec`.
|
||||
|
||||
3. **Что делает RangeControl.** При `bound` вычисляет min/max из текущего
|
||||
размера источника; при смене картинки диапазон пересчитывается, текущее
|
||||
значение пере-клампится. Дефолт и `sanitize` остаются на статической основе
|
||||
(или тоже учат bound) — решить при проектировании.
|
||||
|
||||
4. **Первые потребители:** crop (x/y → ±sourceWidth/sourceHeight), shift
|
||||
(offsetX/offsetY), resize (max → maxSide).
|
||||
|
||||
Это отдельный шаг плана: **завести механизм**, спроектировать на ревью интерфейс
|
||||
спека (`bound` vs `range: (size) => [min, max]`), затем применить к crop и
|
||||
остальным полям размерности. Пока механизма нет — поля crop остаются как есть.
|
||||
|
||||
### C4. verify-is-png: неверное название
|
||||
|
||||
Проверяет текст, не PNG-файл. Переименовать:
|
||||
|
||||
- `id` → `verify-is-png-data` (или оставить для обратной совместимости)
|
||||
- `title` → "Verify PNG data"
|
||||
- `description` → уточнить
|
||||
|
||||
**Решение:** поменять title и description, id не трогать (url-dependent).
|
||||
|
||||
---
|
||||
|
||||
## 4. Волна D — обязательные фиксы (новые параметры)
|
||||
|
||||
### D1. remove-alpha-channel-png: выбор цвета фона
|
||||
|
||||
Сейчас захардкожен `#ffffff`. Добавить `field.color({ default: "#ffffff" })`.
|
||||
|
||||
Файл: `alpha.ts`, схема `removeAlphaChannelSchema`.
|
||||
|
||||
### D2. extract-alpha-mask-png: галочка «инвертировать»
|
||||
|
||||
Добавить `field.checkbox({ label: "fields.invertMask", default: false })`. В
|
||||
`run()`: если `invert`, вызвать `invertAlpha()` после `extractAlphaMask()`.
|
||||
|
||||
Файл: `alpha.ts`.
|
||||
|
||||
### D3. change-canvas-size-png: position9 вместо select
|
||||
|
||||
`anchor` сейчас `field.select()` с 9 опциями → `field.position9()`.
|
||||
|
||||
Файл: `geometry.ts`. Уже есть `PositionControl`.
|
||||
|
||||
### D4. Generators: добавить height
|
||||
|
||||
Инструменты без `size`/`height`:
|
||||
|
||||
- blend-two-png — добавить
|
||||
`height: field.slider({ min: 1, max: 1024, default: 512 })`
|
||||
- step-colors-png — аналогично
|
||||
- complementary, triadic, tetradic, analogous, monochromatic, shades,
|
||||
sort-colors — все используют `paletteBaseSchema` (общий объект), добавить
|
||||
`height` туда
|
||||
- mix-colors-png — добавить height
|
||||
|
||||
Файл: `generate.ts`.
|
||||
|
||||
### D5. add-border-png: прозрачность цвета
|
||||
|
||||
Текущий `field.color()` не поддерживает alpha. Пока что: оставить как есть
|
||||
(прозрачность не поддерживается нативным color picker). Отметить в аудите как
|
||||
blocked.
|
||||
|
||||
---
|
||||
|
||||
## 5. Волна E — полировка (некритично)
|
||||
|
||||
### E1. Плейсхолдер "нет параметров"
|
||||
|
||||
Инструменты с пустой схемой (`EmptyParams`) выглядят странно. Добавить
|
||||
`EmptyState` или подсказку "No parameters — click Run".
|
||||
|
||||
Файл: `SchemaToolView.svelte` — показать подсказку если `schema.fields` пуст.
|
||||
|
||||
### E2. quantize-png: пресеты
|
||||
|
||||
`field.slider` с max 64 → добавить пресеты (8, 16, 32, 64) как кнопки под
|
||||
слайдером. Либо `field.buttons()` с 4 опциями вместо слайдера.
|
||||
|
||||
### E3. trim-empty-space-png: 0-254 → проценты
|
||||
|
||||
Текущий `min: 0, max: 254` — нестандартно. Добавить переключатель px/% (аналог
|
||||
шага A1 — `variant: "alpha-threshold"` в NumberSpec).
|
||||
|
||||
### E4. add-text-png: plate offset
|
||||
|
||||
Plate снизу имеет большой отступ — добавить галочку "compact plate" или
|
||||
уменьшить дефолтный padding.
|
||||
|
||||
### E5. emoji-to-png: выбор эмодзи
|
||||
|
||||
Поле `text` → добавить группу часто используемых эмодзи как кнопки- пресеты над
|
||||
полем ввода.
|
||||
|
||||
---
|
||||
|
||||
## 6. Верификация
|
||||
|
||||
После каждой волны:
|
||||
|
||||
1. `pnpm --dir web build` — без ошибок
|
||||
2. `pnpm --dir web exec svelte-check --tsconfig ./tsconfig.json` — без ошибок
|
||||
3. `pnpm --dir web lint` — без ошибок (кроме ожидаемых долгов)
|
||||
4. Ручная проверка в браузере: параметры рендерятся, инструменты работают
|
||||
|
||||
---
|
||||
|
||||
## 7. Не покрыто / требует решения
|
||||
|
||||
Эти пункты из аудита не попали в волны A–E. Требуют либо дополнительного
|
||||
исследования, либо нормативного решения, либо отложены.
|
||||
|
||||
### 7.1 Требуют normative решения
|
||||
|
||||
- **Pixel ↔ Percent** (circle-mask, square-mask, star-mask, wavy-mask — %→px,
|
||||
round-corners — px→%): нужен компонент переключателя единиц в слайдере.
|
||||
Отложен до волны E, т.к. требует правки `RangeControl` + всех схем.
|
||||
- **Smoothing checkbox** для масок (circle, square, star, wavy, round-corners,
|
||||
invert-alpha): нужен `field.checkbox("smoothing")` + правка core (shapes.ts,
|
||||
alpha). Отложен — требует визуального тестирования.
|
||||
- **Vignette**: выбор центра + цвет + feather — 3 новых параметра. Требует
|
||||
normative решения по UI.
|
||||
- **Remove-background**: выбор точки удаления — либо параметр, либо отдельный
|
||||
инструмент.
|
||||
- **Precision/quality**: select в resize (bilinear/bicubic/nearest) — нужен ли
|
||||
выбор алгоритма?
|
||||
- **Placeholders**: "нет параметров" — какой текст/компонент показывать.
|
||||
|
||||
### 7.2 Операционные (тест-кейсы, описания)
|
||||
|
||||
- find-contour-png: расширять на толщину линии (требует правки core)
|
||||
- make-thicker-png: расширять картинку на толщину линии
|
||||
- make-thinner-png: уменьшать от краев, fix выступа
|
||||
- feather-edges-png: расширять картинку на толщину линии
|
||||
- clean-edges-png: найти тест-кейс, возможно увеличить максимум
|
||||
- despeckle-alpha-png: найти более заметный тест-кейс
|
||||
- close-holes-png: проверить поведение на больших полупрозрачных областях
|
||||
- auto-contrast-png: найти тестовый кейс
|
||||
- sharpen-png: добавить тест-кейс
|
||||
- center-by-alpha-png: найти тест-кейс
|
||||
- png-is-grayscale: улучшить видимость результата
|
||||
|
||||
### 7.3 Дизайн-вопросы
|
||||
|
||||
- add-padding-png vs add-border-png: разница неочевидна, нужен review
|
||||
- change-aspect-ratio-png: не видно что меняется — рамка результата
|
||||
- watermark-tile-png: заполняет не полностью
|
||||
- sepia-png: нужна ли настройка силы эффекта?
|
||||
- posterize-png: настройка для каждого канала отдельно?
|
||||
- pixelate-png: разные алгоритмы?
|
||||
- swap-channels-png: обдумать flow через более простые инструменты
|
||||
|
||||
### 7.4 Аудит полей (компоненты)
|
||||
|
||||
- Range slider: поле ввода + кнопки +/- + кнопка сброса
|
||||
- Color picker: пипетка с картинки, прозрачность
|
||||
- Width/height с keep-aspect-ratio: единый компонент
|
||||
- Position offset: отдельные слайдеры x/y (уже сделано в `OffsetControl`)
|
||||
Reference in New Issue
Block a user