Summon v0.7.0 - Advanced Web & Desktop Prep

Focus: Multi-window capabilities, desktop-specific features, and advanced styling. Goal: Enable complex desktop-class applications, advanced web workflows, and eliminate raw CSS/HTML workarounds.

---

12. HTML DSL (Semantic HTML Components)

Requirement: Provide kotlinx.html-like syntax for web developers who prefer working directly with HTML elements.

Motivation: Web developers familiar with HTML find the Compose-like DSL (Row, Column, Box) abstract. An HTML DSL provides familiar semantic elements (Nav, Article, Section, H1, P, Ul, Li) while maintaining full integration with Summon's reactivity and Modifier system.

Technical Specs

Approach: Create @Composable wrapper functions for HTML5 elements that delegate to PlatformRenderer.renderHtmlTag().

Target Syntax:

@Composable
fun MyPage() {
  Nav(modifier = Modifier().className("navbar")) {
    A(href = "/home") { Text("Home") }
    A(href = "/about") { Text("About") }
  }
  Main {
    Article {
      H1 { Text("Welcome") }
      P { Text("Content here") }
      Ul {
        Li { Text("Item 1") }
        Li { Text("Item 2") }
      }
    }
  }
}

Implementation Plan

New Package: codes.yousef.summon.components.html/

File	Elements
HtmlElements.kt	Header, Nav, Main, Footer, Section, Article, Aside
TextElements.kt	H1-H6, P, Blockquote, Pre, Code, Strong, Em, Small, Mark
ListElements.kt	Ul, Ol, Li, Dl, Dt, Dd
TableElements.kt	Table, Thead, Tbody, Tfoot, Tr, Th, Td, Caption
InlineElements.kt	A, Strong, Em, Code, Time, Abbr, Cite, Q, Kbd
MediaElements.kt	Figure, Figcaption, Picture, Audio, Video

Files to Modify:

1. JvmPlatformRenderer.kt - Expand renderHtmlTag switch to handle all HTML5 tags via kotlinx.html
2. seo/routes/SemanticHTML.kt - Deprecate in favor of new package

Component API Pattern

Standard Element:

@Composable
fun Nav(
  modifier: Modifier = Modifier(),
  content: @Composable FlowContent.() -> Unit
) {
  LocalPlatformRenderer.current.renderHtmlTag("nav", modifier, content)
}

Element with Convenience Parameters:

@Composable
fun A(
  href: String,
  target: String? = null,
  modifier: Modifier = Modifier(),
  content: @Composable FlowContent.() -> Unit
) {
  val finalModifier = modifier
    .attribute("href", href)
    .let { if (target != null) it.attribute("target", target) else it }
  LocalPlatformRenderer.current.renderHtmlTag("a", finalModifier, content)
}

Priority Order

1. Tier 1 - Structural: Header, Nav, Main, Footer, Section, Article, Aside
2. Tier 2 - Text: H1-H6, P, Blockquote, Pre, Code, Strong, Em
3. Tier 3 - Lists: Ul, Ol, Li
4. Tier 4 - Tables: Table, Thead, Tbody, Tr, Th, Td
5. Tier 5 - Inline: A (with href), Time, Abbr, etc.

Platform Support

• JVM: Rendered via kotlinx.html (requires expanding when statement)
• JS: Uses createElement(tagName) directly (already works)
• WASM: Uses kotlinx-browser DOM APIs (already works)

Estimated Effort: 2-3 days

---

13. Window Management API

Requirement: Control application windows programmatically. Technical Specs:

• Open Window: Launch a new window with specified content, size, and position.
• Window State: Query and modify state (Minimized, Maximized, Fullscreen).
• Screen Info: Access information about available displays (resolution, DPI).
• Web Implementation: Uses window.open() and PWA display modes.
• Desktop Implementation: Maps to native window creation (NSWindow, HWND).

14. Pseudo-Class Modifiers

Requirement: Style elements based on interaction state without raw CSS. Technical Specs:

• Hover: Modifier.hover { ... } applies styles on mouse hover.
• Focus: Modifier.focus { ... } applies styles when element is focused.
• Active: Modifier.active { ... } applies styles during click/press.
• Visited: Modifier.visited { ... } for link visited state.
• Implementation: Generates unique class names with corresponding CSS pseudo-selectors.
• Example:

  Modifier()
      .backgroundColor(Colors.SURFACE)
      .hover { backgroundColor(Colors.SURFACE_HOVER) }
      .focus { borderColor(Colors.ACCENT) }
  

15. Responsive Breakpoint Modifiers

Requirement: Apply styles conditionally based on viewport size without GlobalStyle. Technical Specs:

• Breakpoint API: Modifier.media(minWidth = 768.px) { ... } for responsive styles.
• Predefined Breakpoints: Modifier.sm { }, .md { }, .lg { }, .xl { } shortcuts.
• Mobile-First: Base styles apply to all, breakpoint styles override at larger sizes.
• Implementation: Generates @media queries with scoped class selectors.
• Example:

  Modifier()
      .flexDirection(FlexDirection.Column)
      .md { flexDirection(FlexDirection.Row) }
      .padding(16.px)
      .lg { padding(32.px) }
  

16. Scoped Style Blocks

Requirement: Apply CSS rules to descendants without global pollution. Technical Specs:

• Scoped Selector: Modifier.descendant("a") { color(Colors.LINK) } targets child elements.
• Direct Child: Modifier.child("img") { maxWidth(100.percent) } targets immediate children.
• Class Selector: Modifier.className("prose").descendant("code") { ... } for specific contexts.
• Implementation: Generates scoped CSS with parent class + descendant selector.
• Example:

  Column(
      modifier = Modifier()
          .className("prose")
          .descendant("a") { 
              color(Colors.LINK)
              textDecoration(TextDecoration.Underline)
          }
          .descendant("a").hover { color(Colors.LINK_HOVER) }
  )
  

17. Details & Summary Components

Requirement: Native collapsible disclosure widget without RawHtml. Technical Specs:

• Details: Container component that can be expanded/collapsed.
• Summary: The visible header that toggles the Details open state.
• Controlled State: Optional open parameter for programmatic control.
• Events: onToggle callback when state changes.
• Styling: Full Modifier support for both Details and Summary.
• Example:

  Details(
      open = isExpanded,
      onToggle = { isExpanded = it },
      modifier = Modifier().marginBottom(12.px)
  ) {
      Summary(modifier = Modifier().fontWeight(FontWeight.SemiBold)) {
          Text("Navigation")
      }
      // Collapsible content
      Column {
          NavLink("Home", "/")
          NavLink("About", "/about")
      }
  }
  

18. Nav Component

Status: Consolidated into #12 HTML DSL above.

The Nav component is now part of the comprehensive HTML DSL feature, which includes Nav, Header, Footer, Article, Section, and all other semantic HTML5 elements.

19. Native Menu Bar

Requirement: Application-level menu bar (File, Edit, View). Technical Specs:

• Structure: Hierarchical menu definition (Menu -> Item/Submenu/Separator).
• Shortcuts: Display keyboard shortcuts next to items.
• Platform Mapping:
  • Web: Rendered as a top navigation bar or hamburger menu.
  • macOS: Global system menu bar.
  • Windows/Linux: Window-attached menu bar.

20. Native File Dialogs

Requirement: System-native dialogs for opening and saving files. Technical Specs:

• Pick File: Open dialog to select one or multiple files.
• Pick Directory: Open dialog to select a folder.
• Save File: Save dialog to choose a destination filename.
• Filters: Filter visible files by extension or MIME type.
• Web Implementation: Uses File System Access API where available, falls back to <input type="file">.

21. System Tray

Requirement: Persistent icon in the OS system tray / status area. Technical Specs:

• Icon: Set and update the tray icon.
• Menu: Context menu shown on tray icon click/right-click.
• Tooltip: Hover text for the icon.
• Web Implementation: No-op (not supported in browsers).

22. Multi-Window Communication (BroadcastChannel)

Requirement: Message passing between different windows/tabs of the same application. Technical Specs:

• Channel: Named channels for pub/sub messaging.
• Message Types: Support for serializable data payloads.
• Scope: Same-origin restriction.
• Web Implementation: Wraps the BroadcastChannel API.

23. Cross-Window Drag and Drop

Requirement: Drag items from one app window and drop them into another. Technical Specs:

• Coordination: Use BroadcastChannel or shared storage to coordinate drag state between windows if the platform treats them as separate processes (like browser tabs).
• Data: Ensure drag data is accessible across window boundaries.

24. Shared/Synced Storage

Requirement: State persistence that automatically syncs across open windows/tabs. Technical Specs:

• Storage Hook: A reactive primitive (like remember) that reads/writes to persistent storage.
• Synchronization: Updates in one window must trigger recomposition in others listening to the same key.
• Web Implementation: localStorage + storage event listener.

20. Document Picture-in-Picture

Requirement: Support for "Always on Top" mini-windows for arbitrary content. Technical Specs:

• PiP Mode: API to move a component into a floating PiP window.
• Content: Support for interactive content (buttons, controls), not just video.
• Web Implementation: Wraps the Document Picture-in-Picture API.