stream_weaver 0.3.0

data/lib/stream_weaver/components/keyboard_shortcuts.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module StreamWeaver
+  module Components
+    # Centralized keyboard shortcut registry.
+    # Non-visual component -- emits a <script> block that registers keyboard handlers
+    # with context awareness (suppress in text inputs, textareas, code editors).
+    #
+    # "mod" maps to Meta (Cmd) on Mac, Control elsewhere -- handled in JS.
+    #
+    # sw- CSS classes: none (non-visual)
+    #
+    # @example Basic usage
+    #   keyboard_shortcuts do |kb|
+    #     kb.on "mod+s", context: :global do |state|
+    #       # save action
+    #     end
+    #     kb.on "ArrowRight", context: :navigation do |state|
+    #       # next slide
+    #     end
+    #   end
+    class KeyboardShortcuts < Base
+      attr_reader :bindings
+
+      # Suppression selectors -- keyboard shortcuts are ignored when
+      # the active element matches any of these.
+      SUPPRESSION_SELECTORS = %w[
+        input[type=text]
+        input[type=search]
+        input[type=email]
+        input[type=url]
+        input[type=number]
+        input:not([type])
+        textarea
+        [contenteditable=true]
+        .sw-mermaid--zoom
+        .sw-code-scroll
+      ].freeze
+
+      # @param options [Hash] Additional options
+      def initialize(**options)
+        @bindings = []
+        super(**options)
+      end
+
+      # Register a keyboard shortcut binding.
+      #
+      # @param key_combo [String] Key combination (e.g. "mod+s", "ArrowRight", "1..9")
+      # @param context [Symbol] Context for suppression (:global, :navigation, :selection)
+      # @param js_action [String, nil] JavaScript code to execute (alternative to block)
+      # @param block [Proc, nil] Server-side callback (stored but not executed client-side)
+      def on(key_combo, context: :global, js_action: nil, &block)
+        @bindings << {
+          key: key_combo,
+          context: context,
+          js_action: js_action,
+          callback: block
+        }
+      end
+
+      def render(view, state)
+        view.adapter.render_keyboard_shortcuts(view, self, state)
+      end
+
+      # Generate the JS registration calls for all bindings.
+      # Each binding becomes a call to swKeyboard.register(...)
+      #
+      # @return [String] JavaScript code
+      def to_js
+        lines = @bindings.map do |binding|
+          key = binding[:key]
+          context = binding[:context]
+          action = binding[:js_action] || "console.log('shortcut: #{key}')"
+
+          if key.include?("..")
+            # Range shortcut (e.g. "1..9")
+            range_start, range_end = key.split("..").map(&:to_i)
+            (range_start..range_end).map do |n|
+              "swKeyboard.register('#{n}', '#{context}', function(e) { #{action.gsub('KEY', n.to_s)} });"
+            end.join("\n")
+          else
+            "swKeyboard.register('#{key}', '#{context}', function(e) { #{action} });"
+          end
+        end
+        lines.join("\n")
+      end
+
+      # CSS class list (empty -- non-visual component)
+      def css_classes
+        ""
+      end
+    end
+  end
+end

data/lib/stream_weaver/components/kpi_dashboard.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module StreamWeaver
+  module Components
+    # KPI Dashboard component.
+    # Renders an auto-fit grid of metric cards, each showing a large value,
+    # label, optional trend arrow, and optional color accent.
+    # Entry animation via CSS fadeIn.
+    #
+    # sw- CSS classes:
+    #   sw-kpi-dashboard         - outer grid container (auto-fit)
+    #   sw-kpi-card              - individual metric card
+    #   sw-kpi-card--{color}     - color accent variant
+    #   sw-kpi-card__value       - large value display
+    #   sw-kpi-card__label       - label below value
+    #   sw-kpi-card__trend       - trend arrow indicator
+    #   sw-kpi-card__trend--up   - green up arrow
+    #   sw-kpi-card__trend--down - red down arrow
+    #   sw-kpi-card__trend--flat - gray flat arrow
+    #
+    # @example
+    #   kpi_dashboard metrics: [
+    #     { value: "99.9%", label: "Uptime", color: :green, trend: :up },
+    #     { value: "42ms",  label: "Latency", trend: :down },
+    #     { value: "1.2M",  label: "Requests", trend: :flat }
+    #   ]
+    class KpiDashboard < Base
+      attr_reader :metrics
+
+      # @param metrics [Array<Hash>] Array of metric hashes with :value, :label, :color (optional), :trend (optional)
+      #   trend values: :up, :down, :flat, nil
+      #   color values: :green, :blue, :red, :orange, :purple, nil
+      # @param options [Hash] Additional options
+      def initialize(metrics:, **options)
+        @metrics = metrics.map { |m| normalize_metric(m) }
+        super(**options)
+      end
+
+      def render(view, state)
+        view.adapter.render_kpi_dashboard(view, self, state)
+      end
+
+      # Trend arrow character for a metric
+      def trend_arrow(metric)
+        case metric[:trend]
+        when :up   then "\u2191" # up arrow
+        when :down then "\u2193" # down arrow
+        when :flat then "\u2192" # right arrow
+        end
+      end
+
+      # CSS class for trend indicator
+      def trend_css_class(metric)
+        base = "sw-kpi-card__trend"
+        return base unless metric[:trend]
+        "#{base} sw-kpi-card__trend--#{metric[:trend]}"
+      end
+
+      # CSS class for the card (with optional color)
+      def card_css_class(metric)
+        classes = ["sw-kpi-card"]
+        classes << "sw-kpi-card--#{metric[:color]}" if metric[:color]
+        classes.join(" ")
+      end
+
+      private
+
+      def normalize_metric(m)
+        {
+          value: m[:value].to_s,
+          label: m[:label] || "",
+          color: m[:color] ? m[:color].to_sym : nil,
+          trend: m[:trend] ? m[:trend].to_sym : nil
+        }
+      end
+    end
+  end
+end

data/lib/stream_weaver/components/mermaid.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module StreamWeaver
+  module Components
+    # Mermaid diagram component.
+    # Renders Mermaid.js diagrams with optional zoom/pan support,
+    # compact mode for card embedding, and theme-aware styling.
+    #
+    # CDN loading is lazy: Mermaid.js 11 (ESM) is only loaded when
+    # this component is present on the page.
+    #
+    # sw- CSS classes:
+    #   sw-mermaid              - outer container
+    #   sw-mermaid--compact     - compact mode for card embedding
+    #   sw-mermaid--zoom        - zoom/pan enabled
+    #   sw-mermaid__diagram     - the diagram rendering area
+    #   sw-mermaid__controls    - zoom control buttons
+    #   sw-mermaid__btn         - individual zoom button
+    #
+    # @example Basic usage
+    #   mermaid("graph LR; A-->B")
+    #
+    # @example With zoom
+    #   mermaid("graph TD; A-->B-->C", zoom: true)
+    #
+    # @example Compact for cards
+    #   mermaid("graph LR; A-->B", compact: true)
+    #
+    # @example ELK layout
+    #   mermaid("graph TD; A-->B", layout: :elk)
+    class Mermaid < Base
+      attr_reader :code, :zoom, :compact, :layout, :theme_vars
+
+      # @param code [String] Mermaid diagram definition
+      # @param zoom [Boolean] Enable zoom/pan controls (default: false)
+      # @param compact [Boolean] Compact mode for card embedding (default: false)
+      # @param layout [Symbol] Layout engine (:default or :elk)
+      # @param theme_vars [Hash, nil] Per-block Mermaid themeVariables overrides
+      # @param options [Hash] Additional HTML options
+      def initialize(code, zoom: false, compact: false, layout: :default, theme_vars: nil, **options)
+        @code = code
+        @zoom = zoom
+        @compact = compact
+        @layout = layout.to_sym
+        @theme_vars = theme_vars
+        super(**options)
+      end
+
+      def render(view, state)
+        view.adapter.render_mermaid(view, self, state)
+      end
+
+      # Whether ELK layout engine is requested
+      def elk?
+        @layout == :elk
+      end
+
+      # Generate a unique ID for this diagram instance
+      def diagram_id
+        @diagram_id ||= "sw-mermaid-#{object_id}"
+      end
+
+      # Serialize theme_vars to JSON for the JS initializer
+      def theme_vars_json
+        return "null" unless @theme_vars
+        require "json"
+        JSON.generate(@theme_vars)
+      end
+
+      # CSS class list for the outer container
+      def css_classes
+        classes = ["sw-mermaid"]
+        classes << "sw-mermaid--compact" if @compact
+        classes << "sw-mermaid--zoom" if @zoom
+        classes.join(" ")
+      end
+    end
+  end
+end

data/lib/stream_weaver/components/pipeline.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module StreamWeaver
+  module Components
+    # Pipeline step flow visualization.
+    # Renders a horizontal sequence of steps with arrow connectors,
+    # color-coded by status: complete (green), active (blue), pending (gray).
+    # Responsive: collapses to vertical layout on narrow screens.
+    #
+    # sw- CSS classes:
+    #   sw-pipeline              - outer flexbox container
+    #   sw-pipeline__step        - individual step box
+    #   sw-pipeline__step--complete  - green (done)
+    #   sw-pipeline__step--active    - blue (in progress)
+    #   sw-pipeline__step--pending   - gray (not started)
+    #   sw-pipeline__label       - step label text
+    #   sw-pipeline__desc        - step description text
+    #   sw-pipeline__arrow       - CSS triangle arrow connector
+    #
+    # @example Basic
+    #   pipeline steps: [
+    #     { label: "Build", status: :complete },
+    #     { label: "Test",  status: :active },
+    #     { label: "Deploy", status: :pending }
+    #   ]
+    class Pipeline < Base
+      attr_reader :steps
+
+      # @param steps [Array<Hash>] Array of step hashes with :label, :description (optional), :status
+      #   status values: :complete, :active, :pending
+      # @param options [Hash] Additional options
+      def initialize(steps:, **options)
+        @steps = steps.map { |s| normalize_step(s) }
+        super(**options)
+      end
+
+      def render(view, state)
+        view.adapter.render_pipeline(view, self, state)
+      end
+
+      # CSS class for a step based on its status
+      def step_css_class(step)
+        base = "sw-pipeline__step"
+        modifier = case step[:status]
+                   when :complete then "sw-pipeline__step--complete"
+                   when :active   then "sw-pipeline__step--active"
+                   else                "sw-pipeline__step--pending"
+                   end
+        "#{base} #{modifier}"
+      end
+
+      private
+
+      def normalize_step(step)
+        {
+          label: step[:label] || "Step",
+          description: step[:description],
+          status: (step[:status] || :pending).to_sym
+        }
+      end
+    end
+  end
+end

data/lib/stream_weaver/components/sidebar_toc.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module StreamWeaver
+  module Components
+    # Sticky sidebar table-of-contents with IntersectionObserver scroll spy.
+    #
+    # Desktop (>=1000px): sticky 170px sidebar with active-section highlighting.
+    # Mobile (<1000px): horizontal scrollable sticky bar at the top.
+    #
+    # Sections are an array of hashes, each with :id and :label keys.
+    # The :id corresponds to the DOM id of the target section element.
+    #
+    # @example
+    #   sidebar_toc sections: [
+    #     { id: "summary", label: "Executive Summary" },
+    #     { id: "architecture", label: "Architecture" },
+    #     { id: "risks", label: "Risks" }
+    #   ]
+    class SidebarToc < Base
+      attr_reader :sections
+
+      # @param sections [Array<Hash>] Array of { id:, label: } hashes
+      # @param options [Hash] Additional options
+      def initialize(sections:, **options)
+        @sections = normalize_sections(sections)
+        @options = options
+      end
+
+      def render(view, state)
+        view.adapter.render_sidebar_toc(view, self, state)
+      end
+
+      private
+
+      # Normalize sections to ensure string keys become symbols
+      def normalize_sections(sections)
+        sections.map do |s|
+          {
+            id: (s[:id] || s["id"]).to_s,
+            label: (s[:label] || s["label"]).to_s
+          }
+        end
+      end
+    end
+  end
+end

data/lib/stream_weaver/components/slide_container.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module StreamWeaver
+  module Components
+    # Slide within a SlideContainer.
+    # Contains child components rendered as slide content.
+    #
+    # sw- CSS classes:
+    #   sw-slide                - individual slide wrapper
+    #   sw-slide--active        - currently visible slide (swap mode)
+    #   sw-slide--title         - title slide type
+    #   sw-slide--content       - content slide type
+    #
+    # @example
+    #   slide "intro", "Introduction" do
+    #     text "Welcome to the presentation"
+    #   end
+    class Slide < Base
+      attr_reader :id, :title, :type
+      attr_accessor :children
+
+      # @param id [String] Unique identifier for this slide
+      # @param title [String, nil] Optional slide title
+      # @param type [Symbol] Slide type (:content, :title)
+      # @param options [Hash] Additional HTML options
+      def initialize(id, title = nil, type: :content, **options)
+        @id = id.to_s
+        @title = title
+        @type = type.to_sym
+        @children = []
+        super(**options)
+      end
+
+      def render(view, state)
+        view.adapter.render_slide(view, self, state)
+      end
+
+      # CSS class list
+      def css_classes
+        classes = ["sw-slide"]
+        classes << "sw-slide--#{@type}"
+        classes.join(" ")
+      end
+    end
+
+    # Container for navigable slides.
+    # Supports two modes:
+    #   :swap        -- one slide visible at a time, Back/Next buttons, fade transition (deck)
+    #   :scroll_snap -- all slides rendered, CSS scroll-snap-type: y mandatory (explainer)
+    #
+    # Both modes share: keyboard navigation, progress tracking, Alpine.js x-data for current index.
+    #
+    # sw- CSS classes:
+    #   sw-slide-container              - outer container
+    #   sw-slide-container--swap        - swap mode
+    #   sw-slide-container--scroll-snap - scroll-snap mode
+    #   sw-slide-nav                    - navigation buttons wrapper
+    #   sw-slide-nav__btn               - Back/Next buttons
+    #   sw-slide-nav__btn--prev         - Back button modifier
+    #   sw-slide-nav__btn--next         - Next button modifier
+    #   sw-slide-progress               - progress bar
+    #   sw-slide-progress--fixed        - fixed at top of viewport
+    #   sw-slide-progress__bar          - progress bar fill
+    #   sw-slide-dots                   - navigation dots container
+    #   sw-slide-dots__dot              - individual dot
+    #   sw-slide-dots__dot--active      - active dot
+    #   sw-slide-counter                - slide counter text (e.g. "2 / 5")
+    #
+    # @example Swap mode (deck)
+    #   slide_container mode: :swap, progress_bar: true do
+    #     slide "intro", "Introduction" do
+    #       text "Welcome"
+    #     end
+    #     slide "arch", "Architecture" do
+    #       text "System design"
+    #     end
+    #   end
+    #
+    # @example Scroll-snap mode (explainer)
+    #   slide_container mode: :scroll_snap, nav_dots: true, counter: true do
+    #     slide "title", type: :title do
+    #       header1 "Title"
+    #     end
+    #     slide "content1" do
+    #       text "Content..."
+    #     end
+    #   end
+    class SlideContainer < Base
+      attr_reader :mode, :progress_bar, :nav_dots, :counter, :keyboard_nav
+      attr_accessor :children
+
+      # @param mode [Symbol] Display mode (:swap or :scroll_snap)
+      # @param progress_bar [Boolean] Show progress bar (default: true)
+      # @param keyboard_nav [Boolean] Enable arrow key navigation (default: true)
+      # @param nav_dots [Boolean] Show navigation dots (default: false)
+      # @param counter [Boolean] Show slide counter (default: false)
+      # @param options [Hash] Additional options
+      def initialize(mode: :swap, progress_bar: true, keyboard_nav: true,
+                     nav_dots: false, counter: false, **options)
+        @mode = mode.to_sym
+        @progress_bar = progress_bar
+        @keyboard_nav = keyboard_nav
+        @nav_dots = nav_dots
+        @counter = counter
+        @children = []
+        super(**options)
+      end
+
+      def render(view, state)
+        view.adapter.render_slide_container(view, self, state)
+      end
+
+      # Number of slides
+      def slide_count
+        @children.length
+      end
+
+      # Whether swap mode
+      def swap?
+        @mode == :swap
+      end
+
+      # Whether scroll-snap mode
+      def scroll_snap?
+        @mode == :scroll_snap
+      end
+
+      # Generate a unique container ID
+      def container_id
+        @container_id ||= "sw-slides-#{object_id}"
+      end
+
+      # CSS class list
+      def css_classes
+        classes = ["sw-slide-container"]
+        classes << "sw-slide-container--#{@mode.to_s.tr('_', '-')}"
+        classes.join(" ")
+      end
+    end
+  end
+end

data/lib/stream_weaver/components/timeline_event.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module StreamWeaver
+  module Components
+    # Timeline event row with colored type badge and expandable detail fields.
+    # Designed to replicate the DTO Run Viewer event log style:
+    # compact row with index, type badge, timestamp, label — click to expand key-value details.
+    #
+    # Event types map to distinct colors:
+    #   phase        → cyan (#00bcd4)
+    #   snapshot     → yellow (#ffc107)
+    #   intervention → purple (#ce93d8)
+    #   timeout      → red (#ef5350)
+    #   guard        → red (#ef5350)
+    #   final        → green (#66bb6a)
+    #
+    # sw- CSS classes:
+    #   sw-timeline-event                    - outer row container
+    #   sw-timeline-event--{type}            - type-specific border + badge colors
+    #   sw-timeline-event__idx               - index number (right-aligned)
+    #   sw-timeline-event__badge             - type badge pill
+    #   sw-timeline-event__ts                - timestamp
+    #   sw-timeline-event__label             - summary label
+    #   sw-timeline-event__detail            - expandable detail section
+    #   sw-timeline-event__field             - single key-value pair
+    #   sw-timeline-event__field-key         - field label (bold)
+    #   sw-timeline-event__field-value       - field value (may contain pre block)
+    #
+    # @example
+    #   timeline_event index: 0, event_type: :phase, timestamp: "10:00:00",
+    #                  label: "launch", fields: { run_id: "abc-123", phase: "launch" }
+    class TimelineEvent < Base
+      attr_reader :index, :event_type, :timestamp, :label, :fields, :expanded
+
+      TYPES = %i[phase snapshot intervention timeout guard final].freeze
+
+      # @param index [Integer] Event sequence number
+      # @param event_type [Symbol] One of :phase, :snapshot, :intervention, :timeout, :guard, :final
+      # @param timestamp [String] Time display (e.g., "10:00:00")
+      # @param label [String] Summary label for the event row
+      # @param fields [Hash] Key-value pairs shown in the expanded detail section
+      # @param expanded [Boolean] Whether to start expanded (default: false)
+      def initialize(index:, event_type:, timestamp:, label:, fields: {}, expanded: false, **options)
+        @index = index
+        @event_type = TYPES.include?(event_type.to_sym) ? event_type.to_sym : :phase
+        @timestamp = timestamp
+        @label = label
+        @fields = fields
+        @expanded = expanded
+        super(**options)
+      end
+
+      def render(view, state)
+        view.adapter.render_timeline_event(view, self, state)
+      end
+    end
+  end
+end

data/lib/stream_weaver/components/wireframe.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module StreamWeaver
+  module Components
+    # HTML mockup wrapped in device chrome matching the surface type.
+    # Renders the author's HTML fragment inside a visual device frame —
+    # browser window, phone bezel, desktop window, or compact floating frame.
+    #
+    # @example
+    #   wireframe(surface: :browser) do
+    #     "<h1>Login</h1><button class=\"primary\">Sign in</button>"
+    #   end
+    class Wireframe < Base
+      SURFACES = %w[browser desktop mobile phone tablet popover card widget panel].freeze
+
+      attr_reader :html, :surface
+
+      def initialize(html: "", surface: :browser, **options)
+        @html    = html
+        @surface = SURFACES.include?(surface.to_s) ? surface.to_s : "browser"
+        @options = options
+      end
+
+      def render(view, state)
+        view.adapter.render_wireframe(view, self, state)
+      end
+    end
+  end
+end

data/lib/stream_weaver/components/wireframe_block.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module StreamWeaver
+  module Components
+    # A wireframe surface block that renders raw HTML as a hand-drawn mockup.
+    # Provides scoped --wf-* CSS tokens and helper classes within .sw-wireframe-surface.
+    #
+    # All styling is intentionally scoped to .sw-wireframe-surface so wireframe
+    # aesthetics cannot leak into the surrounding app UI.
+    #
+    # CSS tokens and helper classes are injected inline by the adapter (same pattern
+    # as other canvas components). See AlpineJS#wireframe_css for the full token set.
+    #
+    # @example
+    #   wireframe_block(html: "<h1>Login</h1><button class=\"primary\">Sign in</button>")
+    class WireframeBlock < Base
+      SURFACES = %w[browser desktop mobile popover panel].freeze
+
+      attr_reader :html, :surface
+
+      # @param html [String] Raw HTML fragment to display inside the wireframe surface
+      # @param surface [String] Surface type: browser, desktop, mobile, popover, panel
+      def initialize(html: "", surface: "browser", **options)
+        @html    = html
+        @surface = SURFACES.include?(surface) ? surface : "browser"
+        @options = options
+      end
+
+      def render(view, state)
+        view.adapter.render_wireframe_block(view, self, state)
+      end
+    end
+  end
+end