chore: added editor specs

2026-04-05 09:22:42 +02:00
parent 041eeb3a4f
commit 579f1cd068
4 changed files with 495 additions and 32 deletions
--- a/specs/editors.allium
+++ b/specs/editors.allium
@@ -0,0 +1,415 @@
+-- allium: 1
+-- bDS Editor Views
+-- Scope: UI content area (all waves + extensions)
+-- Distilled from: PostEditor.tsx, MediaEditor.tsx, Editor.tsx (Dashboard),
+--   SettingsView.tsx, StyleView.tsx, ChatPanel.tsx, TagsView
+
+-- Describes the layout and behaviour of each editor view rendered in
+-- the main content area when a tab is active (or dashboard when no tab).
+-- Tab routing is in tabs.allium. Sidebar navigation is in sidebar_views.allium.
+
+use "./tabs.allium" as tabs
+use "./post.allium" as post
+use "./media.allium" as media
+use "./i18n.allium" as i18n
+
+-- ─── Dashboard (no tab active) ───────────────────────────────
+
+-- Shown as default/welcome view when no entity tab is active.
+-- Single centered column.
+
+value Dashboard {
+    title: String
+    subtitle: String
+    stats: DashboardStats
+    timeline: DashboardTimeline
+    tag_cloud: DashboardTagCloud
+    category_cloud: DashboardCategoryCloud
+    recent_posts: List<DashboardRecentPost>
+}
+
+value DashboardStats {
+    -- Three stat cards side by side:
+    total_posts: Integer
+    published_count: Integer
+    draft_count: Integer
+    archived_count: Integer             -- shown only if > 0
+    media_count: Integer
+    image_count: Integer
+    total_media_size: String            -- formatted B/KB/MB/GB
+    tag_count: Integer
+    category_count: Integer
+}
+
+value DashboardTimeline {
+    -- Bar chart of posts over time
+    -- Last 12 months that have data
+    -- Each bar: count label on top, month abbreviation + year below
+    -- Bar height proportional to max count
+    months: List<DashboardTimelineMonth>
+}
+
+value DashboardTimelineMonth {
+    label: String                       -- month abbreviation
+    year: Integer
+    count: Integer
+}
+
+value DashboardTagCloud {
+    -- Up to 40 tags, sorted alphabetically
+    -- Font size scaled 11px-22px based on post count
+    -- Tags with colours get coloured background with contrast text
+    -- Hover title shows post count
+    -- "and N more" text if > 40 tags
+    tags: List<DashboardTag>
+    overflow_count: Integer?
+}
+
+value DashboardTag {
+    name: String
+    count: Integer
+    color: String?
+}
+
+value DashboardCategoryCloud {
+    -- All categories as badge-like tags
+    -- Each shows category name + count
+    categories: List<DashboardCategory>
+}
+
+value DashboardCategory {
+    name: String
+    count: Integer
+}
+
+value DashboardRecentPost {
+    -- Last 5 posts by updatedAt descending
+    -- Each row: title (or "Untitled"), status badge (draft/published), date
+    -- Single-click: preview tab, double-click: pin tab
+    post_id: String
+    title: String
+    status: String
+    date: String
+}
+
+config {
+    dashboard_max_tags: Integer = 40
+    dashboard_tag_min_font: Integer = 11
+    dashboard_tag_max_font: Integer = 22
+    dashboard_recent_count: Integer = 5
+    dashboard_timeline_months: Integer = 12
+}
+
+-- ─── Post editor ──────────────────────────────────────────────
+
+-- Single vertical column. Three regions: header, body, footer.
+
+-- Header bar:
+--   Left: post title (or "Untitled") with dirty indicator dot
+--   Right: status badge, auto-save indicator, Quick Actions dropdown, Publish/Delete buttons
+-- Quick Actions:
+--   AI Analysis (suggests title, excerpt, slug)
+--   Translate Post (opens translation modal)
+
+-- Collapsible Metadata section (starts expanded when title is empty):
+--   Two-column layout. Left column: metadata fields. Right column: linked media panel.
+--   Left column fields:
+--     Title (text input), Tags (autocomplete chip input), Author (text input),
+--     Language (select + AI detect button), Do Not Translate (checkbox),
+--     Slug (read-only), Categories (chip input), Template (select, if templates exist),
+--     PostLinks (backlinks and outlinks)
+--   Right column:
+--     LinkedMediaPanel (media items linked to this post)
+
+-- Language flags bar (inline with metadata toggle):
+--   Row of flag emoji buttons for canonical language + each translation
+--   Styles: status class (draft/published), active indicator
+--   Clicking switches editor content to that language's draft
+
+-- Collapsible Excerpt section:
+--   Excerpt textarea (4 rows)
+
+-- Editor Body:
+--   Toolbar: "Content" label | mode toggle (Visual/Markdown/Preview) | action buttons
+--   Action buttons (markdown mode only): Gallery, Insert Post Link, Insert Media
+--   Visual mode: rich-text WYSIWYG editor
+--   Markdown mode: code editor with markdown-with-macros language
+--     Highlights [[macro ...]] double-bracket syntax
+--     Word wrap on, minimap off, 14px font
+--   Preview mode: iframe showing rendered preview
+--   Supports drag-and-drop of images (imports media, inserts markdown)
+
+-- Footer:
+--   Three date stamps: Created, Updated, Published (published only if publishedAt exists)
+--   Locale-formatted dates
+
+-- Modals:
+--   InsertModal for link search (Ctrl+K) and media search
+--   AISuggestionsModal for AI-generated title/excerpt/slug
+--   Translation modal: select target language, shows existing status
+--   Lightbox for content images
+
+value PostEditorView {
+    post_id: String
+    header: PostEditorHeader
+    metadata_expanded: Boolean
+    excerpt_expanded: Boolean
+    editor_mode: String                 -- visual | markdown | preview
+}
+
+value PostEditorHeader {
+    title: String                       -- post title or "Untitled"
+    is_dirty: Boolean
+    status: String                      -- draft | published | archived
+    is_auto_saving: Boolean
+}
+
+config {
+    post_auto_save_delay: Integer = 3000
+    -- milliseconds of idle before auto-save triggers
+}
+
+invariant PostAutoSave {
+    -- Auto-saves after 3 seconds of idle in the editor
+    -- Also auto-saves on unmount/tab switch
+    -- Ctrl/Cmd+S triggers immediate save
+}
+
+invariant PostDirtyTracking {
+    -- Compares canonical draft + translation drafts against saved state
+    -- Dirty indicator shown in header and tab bar
+}
+
+-- ─── Media editor ─────────────────────────────────────────────
+
+-- Single column: preview area on top, metadata form below.
+
+-- Header bar:
+--   Media display name
+--   Actions: Quick Actions dropdown, Replace File, Save, Delete
+-- Quick Actions:
+--   AI Image Analysis (image/* types only) - suggests title, alt, caption
+--   Detect Language (from metadata text)
+--   Translate Metadata (opens translation target modal)
+
+-- Preview area:
+--   Images: rendered via bds-media:// protocol with cache-busting timestamp
+--   Non-images: SVG file icon placeholder + original filename text
+
+-- Metadata form fields:
+--   File Name (read-only), MIME Type (read-only),
+--   Size (formatted as KB) + Dimensions (W x H, only if width/height exist),
+--   Title (editable), Alt Text (editable), Caption (textarea 3 rows),
+--   Tags (comma-separated text input), Author, Language (select)
+
+-- Translations section (shown only when language is set):
+--   List of existing translations: flag + language name + title
+--   Per-translation: click to edit, refresh button, delete button
+--   "No translations" message when empty
+
+-- Linked Posts section:
+--   "Link to Post" button opens post picker overlay
+--   Post picker: search input, up to 10 unlinked posts, "and N more" if >10
+--   List of currently linked posts (clickable -> navigates), unlink button
+--   "Not linked to any posts" when empty
+
+value MediaEditorView {
+    media_id: String
+    is_image: Boolean
+    file_name: String                   -- originalName, read-only
+    mime_type: String
+    file_size: String                   -- formatted
+    dimensions: String?                 -- "W x H" if available
+    title: String?
+    alt_text: String?
+    caption: String?
+    tags: String?                       -- comma-separated
+    author: String?
+    language: String?
+    translations: List<MediaTranslationItem>
+    linked_posts: List<LinkedPostItem>
+}
+
+value MediaTranslationItem {
+    language: String
+    title: String?
+}
+
+value LinkedPostItem {
+    post_id: String
+    title: String
+}
+
+-- No auto-save; explicit Save button required.
+-- Replace File opens a native file dialog.
+-- Delete shows confirmation with references (linked posts).
+
+-- ─── Settings view ────────────────────────────────────────────
+
+-- VS Code-style settings page with header + search bar + scrollable sections.
+-- Search filters sections by keyword match. "No results" with clear button.
+
+-- 8 sections (style is a separate tab, not a settings section):
+
+-- 1. Project Settings:
+--   Project Name (text), Project Description (textarea 3 rows),
+--   Data Path (text + Browse + Reset), Public URL (url),
+--   Main Language (select), Blog Languages (checkboxes, main disabled),
+--   Default Author (text), Max Posts Per Page (number 1-500 default 50),
+--   Blogmark Category (select), Blogmark Bookmarklet (copy button), Save
+
+-- 2. Editor Settings:
+--   Default Editor Mode (select: WYSIWYG/Markdown/Preview),
+--   Diff View Style (select: Inline/Side-by-side),
+--   Wrap Long Lines (checkbox), Hide Unchanged Regions (checkbox)
+
+-- 3. Content Settings (Categories):
+--   Table: Category | Title | Render in Lists | Show Titles | Post Template | List Template | Remove
+--   Protected categories: article, aside, page, picture (cannot be deleted)
+--   Add Category: text input + Add button. Reset to Defaults button
+
+-- 4. AI Assistant Settings:
+--   API keys: OpenCode, Mistral (masked display + Change, or password input + Save)
+--   Local providers: Ollama enable checkbox + capabilities table,
+--     LM Studio enable checkbox + capabilities table
+--   Offline mode: enable checkbox (disabled if no local providers),
+--     selectors for chat/title/image models (local only)
+--   Default Model (select with optgroup by provider + refresh),
+--     shows: max output tokens, context window, pricing
+--   Title Model (select), Image Analysis Model (vision-capable only)
+--   System Prompt (textarea 12 rows + Save + Reset to Default)
+
+-- 5. Technology Settings:
+--   Python Runtime Mode (select: Web Worker/Main Thread)
+--   Semantic Similarity (checkbox)
+
+-- 6. Publishing Settings (SSH):
+--   Info: SSH key auth only
+--   SSH Mode (select: scp/rsync), SSH Host, SSH Username, SSH Remote Path
+--   Save + Clear buttons
+
+-- 7. Data Maintenance:
+--   Rebuild buttons (6): Posts from Files, Media from Files, Scripts from Files,
+--     Templates from Files, Links, Regenerate Missing Thumbnails
+--   Open Data Folder button
+
+-- 8. MCP Server Settings:
+--   Status badge (port or "Not running")
+--   Per-agent rows: Claude Code, Claude Desktop, GitHub Copilot, Gemini CLI,
+--     OpenCode, Mistral Vibe, OpenAI Codex — each with Add/Remove toggle
+
+-- ─── Style view ───────────────────────────────────────────────
+
+-- Simple vertical layout: header, theme picker, controls row, preview.
+
+-- Theme Picker: grid of theme buttons (one per Pico CSS theme).
+--   Each button: swatch with 3 colour tones (accent, light bg, dark bg), theme name.
+--   Selected theme: highlighted with aria-pressed.
+
+-- Controls row: Preview Mode dropdown (Auto/Light/Dark), Apply Theme button.
+
+-- Preview: iframe of style preview page at 127.0.0.1:4123/__style-preview
+--   with theme and mode query params. Updates live on selection change.
+
+-- Apply Theme persists to project metadata.
+
+-- ─── Tags view ────────────────────────────────────────────────
+
+-- Three sections controlled by sidebar TagsNav:
+
+-- 1. Cloud: tag cloud visualization. Tags sized by post count,
+--    coloured by tag colour. Clickable to select for editing.
+
+-- 2. Manage (Create/Edit): tag name input, colour picker, template select.
+--    Edit existing tag or create new. Delete button with confirmation.
+
+-- 3. Merge: source tag select, target tag select, Merge button.
+--    Merges all posts from source tag into target, removes source.
+
+-- ─── Chat panel ───────────────────────────────────────────────
+
+-- Three-region vertical layout: header, message area, input area.
+
+-- API Key Required screen (shown when no API key):
+--   Key icon, title, description, "Open Settings" button
+
+-- Header:
+--   Left: conversation title (or "New Chat"), CSS ellipsis on overflow
+--   Right: model selector button + dropdown. Groups models by provider.
+
+-- Message area:
+--   Welcome screen (no messages, not streaming): robot icon, tips
+--   Message list: each has avatar (user=person, assistant=robot), role label, text
+--     User messages: plain text
+--     Assistant messages: rendered as GFM Markdown
+--       External images blocked (CSP), shown as links
+--     Tool markers: checkmark/dot, tool name, truncated args (30 char strings)
+--     Streaming: accumulating markdown + tool markers, thinking dots animation
+--   Auto-scrolls to bottom on new messages
+
+-- Input area:
+--   Abort/Stop button (only during streaming, square stop icon)
+--   Auto-growing textarea (max 200px). Enter sends, Shift+Enter newline
+--   Send button (up-arrow icon), disabled when empty or streaming
+
+-- Token usage tracked per conversation (displayed in status bar, not chat panel).
+-- Per-conversation model override via header selector.
+
+config {
+    chat_tool_args_max_length: Integer = 30
+    chat_input_max_height: Integer = 200
+}
+
+-- ─── Git diff view ────────────────────────────────────────────
+
+-- Renders diff for a file (working tree vs HEAD) or a commit.
+-- File diff: id = "git-diff:{filePath}"
+-- Commit diff: id = "git-diff:commit:{commitHash}"
+-- Supports inline and side-by-side diff display modes (from editor settings).
+
+-- ─── Menu editor view ────────────────────────────────────────
+
+-- Visual editor for the OPML navigation menu (meta/menu.opml).
+-- Drag-and-drop reordering of menu items.
+-- Item types: page, submenu, category_archive, home.
+-- Add/remove items, edit labels and targets.
+-- See menu.allium for data model.
+
+-- ─── Metadata diff view ──────────────────────────────────────
+
+-- Shows DB vs filesystem differences for all entity types.
+-- Each diff entry: entity type, field name, DB value, file value.
+-- Actions: apply file value to DB, or apply DB value to file.
+-- See metadata_diff.allium for diff field definitions.
+
+-- ─── Documentation views ─────────────────────────────────────
+
+-- documentation:     renders DOCUMENTATION.md as styled HTML
+-- api_documentation: renders API.md as styled HTML
+
+-- ─── Validation views ────────────────────────────────────────
+
+-- site_validation:         checks generated site for broken links, missing assets
+-- translation_validation:  checks translation completeness across languages
+
+-- ─── Find duplicates view ────────────────────────────────────
+
+-- Uses embedding vectors to find semantically similar posts.
+-- Shows candidate pairs with similarity score.
+-- See embedding.allium for vector details.
+
+-- ─── Script editor view ──────────────────────────────────────
+
+-- Code editor for Lua scripts (macros, utilities, transforms).
+-- Header: script title, kind badge, enabled toggle.
+-- Editor: code editor with Lua syntax highlighting.
+-- Toolbar: Run button, entrypoint selector.
+-- See script.allium for entity model.
+
+-- ─── Template editor view ─────────────────────────────────────
+
+-- Code editor for Liquid templates (post, list, not_found, partial).
+-- Header: template title, kind badge, enabled toggle, version.
+-- Editor: code editor with Liquid syntax highlighting.
+-- Preview: rendered template output in iframe.
+-- See template.allium for entity model and Liquid subset.