stream_weaver 0.3.0

data/lib/stream_weaver/component_assets.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'set'
+
+module StreamWeaver
+  # Registry for files served via the /sw-asset/ route.
+  # Maps a short SHA key → absolute path so only pre-registered files are served.
+  module ComponentAssets
+    @file_registry = {}
+
+    class << self
+      # Register a file and return its URL key.
+      def register_file(abs_path)
+        key = Digest::SHA256.hexdigest(abs_path)[0, 16]
+        @file_registry[key] = abs_path
+        key
+      end
+
+      # Resolve a key back to an absolute path, or nil if unknown.
+      def resolve_file(key)
+        @file_registry[key]
+      end
+
+      # Return the key for an already-registered path (registers if new).
+      def file_key(abs_path)
+        key = Digest::SHA256.hexdigest(abs_path)[0, 16]
+        @file_registry[key] ||= abs_path
+        key
+      end
+
+      # Walk a component tree and collect unique CSS/JS declarations.
+      # Returns [css_strings, css_paths, js_paths] — all deduped by component class.
+      def collect(components, seen_classes = Set.new)
+        css_strings = []
+        css_paths   = []
+        js_paths    = []
+
+        components.each do |c|
+          klass = c.class
+          unless seen_classes.include?(klass)
+            seen_classes << klass
+            if klass.respond_to?(:component_css_strings)
+              css_strings.concat(klass.component_css_strings)
+            end
+            if klass.respond_to?(:component_css_path) && klass.component_css_path
+              css_paths << klass.component_css_path
+            end
+            if klass.respond_to?(:component_js_path) && klass.component_js_path
+              js_paths << klass.component_js_path
+            end
+          end
+
+          if c.respond_to?(:children) && !c.children.empty?
+            child_css_s, child_css_p, child_js_p = collect(c.children, seen_classes)
+            css_strings.concat(child_css_s)
+            css_paths.concat(child_css_p)
+            js_paths.concat(child_js_p)
+          end
+        end
+
+        [css_strings, css_paths, js_paths]
+      end
+
+      def reset!
+        @file_registry.clear
+      end
+    end
+  end
+end

data/lib/stream_weaver/component_registry.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module StreamWeaver
+  # Registry for third-party component classes.
+  #
+  # Allows downstream gems to contribute DSL methods without monkey-patching App or DisplayDSL.
+  # Registered components are available globally on every app instance via DisplayDSL.
+  #
+  # @example
+  #   StreamWeaver.register_component(MyGem::Banner, dsl: :banner)
+  #
+  # Then in any app block:
+  #   banner(text: "Hello") { ... }
+  module ComponentRegistry
+    @registry = {}
+
+    class << self
+      def register(klass, dsl:, adapter: :alpinejs)
+        dsl_name = dsl.to_sym
+        @registry[dsl_name] = { class: klass, adapter: adapter }
+
+        # Install the DSL method on DisplayDSL so every App picks it up immediately.
+        # with_container handles both leaf (no block) and container (block) usage.
+        DisplayDSL.module_eval do
+          define_method(dsl_name) do |*args, **kwargs, &block|
+            with_container(klass.new(*args, **kwargs), &block)
+          end
+        end
+      end
+
+      def [](dsl_name)
+        @registry[dsl_name.to_sym]
+      end
+
+      def registered?(dsl_name)
+        @registry.key?(dsl_name.to_sym)
+      end
+
+      def each(&block)
+        @registry.each(&block)
+      end
+
+      def all
+        @registry.dup
+      end
+
+      # Remove all registrations (intended for test isolation only).
+      def reset!
+        @registry.each_key do |dsl_name|
+          DisplayDSL.undef_method(dsl_name) if DisplayDSL.method_defined?(dsl_name)
+        end
+        @registry.clear
+      end
+    end
+  end
+
+  class << self
+    # Register a component class with a DSL method name.
+    #
+    # @param klass [Class] A class that inherits from Components::Base
+    # @param dsl [Symbol, String] The DSL method name to define on App/DisplayDSL
+    # @param adapter [Symbol] Adapter hint (:alpinejs, :opal) — informational for now
+    def register_component(klass, dsl:, adapter: :alpinejs)
+      ComponentRegistry.register(klass, dsl: dsl, adapter: adapter)
+    end
+  end
+end

data/lib/stream_weaver/component_renderer.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module StreamWeaver
+  # Renders StreamWeaver components to HTML strings via Phlex.
+  # Used by Feed and Streamer to turn component DSL blocks into HTML
+  # that can be pushed via SSE or POST /stream/push.
+  #
+  # @example
+  #   components = [Components::StatDisplay.new(value: 42, label: "RPS", color: :blue)]
+  #   html = ComponentRenderer.render_html(adapter, components)
+  class ComponentRenderer < Phlex::HTML
+    attr_reader :adapter
+
+    def initialize(adapter, components, state = {})
+      @adapter = adapter
+      @components = Array(components)
+      @state = state
+    end
+
+    def view_template
+      @components.each { |c| c.render(self, @state) }
+    end
+
+    # Fragment scope tracking, matching Views::AppContentView. Components::Fragment
+    # asks every view it renders into for this, so a renderer without it raises
+    # NoMethodError on any app that uses `fragment`.
+    attr_reader :current_fragment_id
+
+    def with_fragment(id)
+      previous = @current_fragment_id
+      @current_fragment_id = id
+      yield
+    ensure
+      @current_fragment_id = previous
+    end
+
+    # Render components to an HTML string
+    #
+    # @param adapter [StreamWeaver::Adapter::Base] The adapter (default: AlpineJS)
+    # @param components [Array<Components::Base>] Components to render
+    # @param state [Hash] State hash (default: empty)
+    # @return [String] Rendered HTML
+    def self.render_html(adapter = nil, components = [], state = {})
+      adapter ||= Adapter::AlpineJS.new
+      new(adapter, components, state).call
+    end
+  end
+end

data/lib/stream_weaver/components/annotated_code.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module StreamWeaver
+  module Components
+    # Code block with line-number-pinned annotation bubbles in a side panel.
+    # Uses Prism.js for syntax highlighting. Note: highlighting is applied per line,
+    # so multi-line constructs (heredocs, block comments) may highlight each line
+    # independently — this component optimises for annotation alignment, not perfect highlighting.
+    # Renders a side-by-side layout: code pane left, annotation panel right.
+    # Each annotation is aligned to its target line; annotated lines get a subtle highlight.
+    # Annotations are positioned by line number (1-based, in-range). Out-of-range lines
+    # produce dangling bubbles with no highlighted counterpart — that is visible authoring feedback.
+    class AnnotatedCode < Base
+      Annotation = Struct.new(:line, :note, keyword_init: true)
+
+      attr_reader :language, :annotations
+
+      def initialize(language: nil, annotations: [], **options)
+        @language = language
+        @annotations = annotations.map { |a| Annotation.new(line: a[:line], note: a[:note]) }
+        @options = options
+      end
+
+      def code=(value)
+        @code = value.to_s
+      end
+
+      def code
+        @code || ""
+      end
+
+      def lines
+        code.lines
+      end
+
+      def line_count
+        lines.length
+      end
+
+      def language_class
+        language ? "language-#{language}" : "language-none"
+      end
+
+      def annotated_lines
+        @annotated_lines ||= Set.new(annotations.map(&:line))
+      end
+
+      def render(view, state)
+        view.adapter.render_annotated_code(view, self, state)
+      end
+    end
+  end
+end

data/lib/stream_weaver/components/api_endpoint.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module StreamWeaver
+  module Components
+    # Single API endpoint spec card: method badge, path, description, params table, response schema.
+    # DSL: api_endpoint(method: "POST", path: "/users", description: "Create user",
+    #                   params: [{name: "email", type: "string", required: true}],
+    #                   response: {id: "integer", email: "string"})
+    class ApiEndpoint < Base
+      DEFAULT_BADGE_COLOR = "#6b7280"
+      BADGE_COLORS = {
+        "GET"     => "#2563eb",
+        "POST"    => "#16a34a",
+        "PUT"     => "#d97706",
+        "PATCH"   => "#d97706",
+        "DELETE"  => "#dc2626",
+        "HEAD"    => DEFAULT_BADGE_COLOR,
+        "OPTIONS" => DEFAULT_BADGE_COLOR
+      }.freeze
+
+      attr_reader :http_method, :path, :description, :params, :response
+
+      def initialize(method:, path:, description: nil, params: [], response: {}, **options)
+        @http_method = method.to_s.upcase
+        @path        = path.to_s
+        @description = description
+        @params      = Array(params)
+        @response    = response.is_a?(Hash) ? response : {}
+        @options     = options
+      end
+
+      def badge_color = BADGE_COLORS.fetch(@http_method, DEFAULT_BADGE_COLOR)
+      def description? = @description && !@description.empty?
+      def params?      = @params.any?
+      def response?    = !@response.empty?
+
+      def render(view, state)
+        view.adapter.render_api_endpoint(view, self, state)
+      end
+    end
+  end
+end

data/lib/stream_weaver/components/callout.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module StreamWeaver
+  module Components
+    # Non-dismissible callout box with colored left border and icon area.
+    #
+    # Unlike Alert (which is dismissible), Callout is a static content box
+    # used for tips, warnings, notes, etc. in explainer documents.
+    #
+    # Variants: :info (blue), :warning (amber), :success (green),
+    #           :error (red), :tip (purple)
+    #
+    # @example
+    #   callout(variant: :warning, title: "Caution") do
+    #     text "Be careful with this API."
+    #   end
+    class Callout < Base
+      VARIANTS = %i[info warning success error tip decision risk].freeze
+
+      attr_reader :variant, :title
+      attr_accessor :children
+
+      # @param variant [Symbol] Callout type (:info, :warning, :success, :error, :tip)
+      # @param title [String, nil] Optional callout title
+      # @param options [Hash] Additional options
+      def initialize(variant: :info, title: nil, **options)
+        @variant = VARIANTS.include?(variant) ? variant : :info
+        @title = title
+        @options = options
+        @children = []
+      end
+
+      # Icon character for each variant
+      # @return [String] Unicode icon
+      def icon
+        case @variant
+        when :info     then "\u2139\uFE0F"  # info
+        when :warning  then "\u26A0\uFE0F"  # warning
+        when :success  then "\u2705"         # check
+        when :error    then "\u274C"         # cross
+        when :tip      then "\u{1F4A1}"      # lightbulb
+        when :decision then "\u2696\uFE0F"  # scales (decision)
+        when :risk     then "\u{1F53A}"  # red triangle up (risk)
+        else "\u2139\uFE0F"
+        end
+      end
+
+      # CSS modifier class for the variant
+      # @return [String]
+      def variant_class
+        "sw-callout--#{@variant}"
+      end
+
+      def render(view, state)
+        view.adapter.render_callout(view, self, state)
+      end
+    end
+  end
+end

data/lib/stream_weaver/components/chart.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "json"
+
+module StreamWeaver
+  module Components
+    # Chart.js wrapper component.
+    # Renders a Chart.js chart (bar, line, pie, doughnut, radar).
+    # CDN loads lazily -- Chart.js 4 is only loaded when this component is used.
+    # Dark mode aware: reads --sw-text and --sw-border for grid/text colors.
+    #
+    # sw- CSS classes:
+    #   sw-chart              - outer container
+    #   sw-chart__canvas      - the canvas element
+    #
+    # @example Bar chart
+    #   chart type: :bar, data: {
+    #     labels: ["A", "B", "C"],
+    #     datasets: [{ label: "Values", data: [1, 2, 3] }]
+    #   }
+    #
+    # @example Line chart with custom height
+    #   chart type: :line, data: { labels: [...], datasets: [...] }, height: 400
+    #
+    # @example Pie chart
+    #   chart type: :pie, data: { labels: ["X", "Y"], datasets: [{ data: [60, 40] }] }
+    class Chart < Base
+      VALID_TYPES = %i[bar line pie doughnut radar].freeze
+      CHART_JS_CDN = "https://cdn.jsdelivr.net/npm/chart.js@4/dist/chart.umd.min.js"
+
+      attr_reader :chart_type, :data, :chart_options, :height
+
+      # @param type [Symbol] Chart type (:bar, :line, :pie, :doughnut, :radar)
+      # @param data [Hash] Chart.js data config (labels, datasets)
+      # @param options [Hash] Chart.js options config
+      # @param height [Integer] Canvas height in pixels (default: 300)
+      def initialize(type:, data:, options: {}, height: 300, **extra)
+        @chart_type = type.to_sym
+        unless VALID_TYPES.include?(@chart_type)
+          raise ArgumentError, "Invalid chart type: #{@chart_type}. Must be one of: #{VALID_TYPES.join(', ')}"
+        end
+        @data = data
+        @chart_options = options
+        @height = height
+        super(**extra)
+      end
+
+      def render(view, state)
+        view.adapter.render_chartjs(view, self, state)
+      end
+
+      # Generate a unique canvas ID for this chart instance
+      def canvas_id
+        @canvas_id ||= "sw-chart-#{object_id}"
+      end
+
+      # Serialize data to JSON for the JS initializer
+      def data_json
+        JSON.generate(deep_stringify(@data))
+      end
+
+      # Serialize options to JSON for the JS initializer
+      def options_json
+        JSON.generate(deep_stringify(@chart_options))
+      end
+
+      private
+
+      # Deep-convert symbol keys to strings for JSON compatibility
+      def deep_stringify(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) do |(k, v), h|
+            h[k.to_s] = deep_stringify(v)
+          end
+        when Array
+          obj.map { |v| deep_stringify(v) }
+        else
+          obj
+        end
+      end
+    end
+  end
+end

data/lib/stream_weaver/components/code_block.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module StreamWeaver
+  module Components
+    # Syntax-highlighted code block component using Prism.js CDN.
+    #
+    # Renders code with optional language-based syntax highlighting,
+    # file path header, line truncation for thumbnails, and scrollable container.
+    #
+    # Uses Prism.js with autoloader plugin for lazy per-language loading.
+    # CDN scripts are only included when this component is used.
+    #
+    # @example Basic usage
+    #   code_block("puts 'hello'", lang: "ruby")
+    #
+    # @example With file header
+    #   code_block(code, file: "src/app.rb", lang: "ruby")
+    #
+    # @example Truncated for thumbnail
+    #   code_block(code, truncate: 10, lang: "ruby")
+    class CodeBlock < Base
+      attr_reader :code, :lang, :file, :truncate, :scroll, :copy
+
+      # @param code [String] The source code to display
+      # @param lang [String, nil] Language for syntax highlighting (e.g. "ruby", "javascript")
+      # @param file [String, nil] File path to show in header bar
+      # @param truncate [Integer, nil] Maximum number of lines to show (nil = show all)
+      # @param scroll [Boolean] Whether to enable scrolling for long code (default: true)
+      # @param copy [Boolean] Show a copy-to-clipboard affordance in the header (default: false)
+      # @param options [Hash] Additional options
+      def initialize(code, lang: nil, file: nil, truncate: nil, scroll: true, copy: false, **options)
+        @code = code.to_s
+        @lang = lang
+        @file = file
+        @truncate = truncate
+        @scroll = scroll
+        @copy = copy
+        @options = options
+      end
+
+      # Return the display code, truncated if needed
+      # @return [String] The code to render
+      def display_code
+        return @code unless @truncate
+
+        lines = @code.lines
+        return @code if lines.length <= @truncate
+
+        lines.first(@truncate).join
+      end
+
+      # Whether the code was truncated
+      # @return [Boolean]
+      def truncated?
+        return false unless @truncate
+
+        @code.lines.length > @truncate
+      end
+
+      # Total line count of original code
+      # @return [Integer]
+      def total_lines
+        @code.lines.length
+      end
+
+      # Prism.js language class (e.g. "language-ruby")
+      # @return [String]
+      def language_class
+        @lang ? "language-#{@lang}" : "language-none"
+      end
+
+      def render(view, state)
+        view.adapter.render_code_block(view, self, state)
+      end
+    end
+  end
+end

data/lib/stream_weaver/components/comparison.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module StreamWeaver
+  module Components
+    # Side-by-side comparison panels with "before" and "after" named regions.
+    #
+    # Each panel renders its children independently. On narrow viewports
+    # (<768px), panels stack vertically.
+    #
+    # Uses named block DSL: `before { ... }` and `after { ... }` inside
+    # the comparison block populate the two panels.
+    #
+    # @example
+    #   comparison(before_label: "Old", after_label: "New") do
+    #     before { text "Version 1" }
+    #     after { text "Version 2" }
+    #   end
+    class Comparison < Base
+      attr_reader :before_label, :after_label
+      attr_accessor :children, :before_children, :after_children
+
+      # @param before_label [String] Label for the "before" panel
+      # @param after_label [String] Label for the "after" panel
+      # @param options [Hash] Additional options
+      def initialize(before_label: "Before", after_label: "After", **options)
+        @before_label = before_label
+        @after_label = after_label
+        @options = options
+        @children = []
+        @before_children = []
+        @after_children = []
+      end
+
+      def render(view, state)
+        view.adapter.render_comparison(view, self, state)
+      end
+    end
+  end
+end

data/lib/stream_weaver/components/decision.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module StreamWeaver
+  module Components
+    # Architecture decision block with labeled options and a recommended flag.
+    # Renders a question heading with option cards; recommended option gets a badge,
+    # non-recommended options are visually de-emphasized.
+    #
+    # @example
+    #   decision(question: "Which database should we use?") do
+    #     option(id: :pg, label: "PostgreSQL", detail: "Full ACID, rich extensions", recommended: true)
+    #     option(id: :sqlite, label: "SQLite", detail: "Zero-dependency, great for dev")
+    #   end
+    class Decision < Base
+      Option = Struct.new(:id, :label, :detail, :recommended, keyword_init: true)
+
+      attr_reader :question
+
+      def initialize(question:, **options)
+        @question = question
+        @options = options
+        @decision_options = []
+      end
+
+      def options
+        @decision_options
+      end
+
+      def add_option(id:, label:, detail:, recommended: false)
+        @decision_options << Option.new(id: id, label: label, detail: detail, recommended: recommended)
+      end
+
+      def render(view, state)
+        view.adapter.render_decision(view, self, state)
+      end
+    end
+  end
+end

data/lib/stream_weaver/components/deck/close_overlay.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module StreamWeaver
+  module Components
+    module Deck
+      # Full-screen overlay shown after deck submit or cancel.
+      # Displays a status message with blur backdrop and optional auto-close tab.
+      #
+      # sw- CSS classes:
+      #   sw-close-overlay                  - full-screen overlay wrapper
+      #   sw-close-overlay--submitted       - green status (submitted)
+      #   sw-close-overlay--cancelled       - amber status (cancelled)
+      #   sw-close-overlay__backdrop        - blur backdrop layer
+      #   sw-close-overlay__content         - centered content box
+      #   sw-close-overlay__icon            - status icon (checkmark or X)
+      #   sw-close-overlay__message         - status message text
+      #   sw-close-overlay__countdown       - auto-close countdown display
+      #   sw-close-overlay__close-btn       - manual close button
+      #
+      # @example
+      #   close_overlay(status: :submitted, message: "Deck submitted successfully!")
+      #   close_overlay(status: :cancelled, message: "Deck cancelled.")
+      class CloseOverlay < Base
+        attr_reader :status, :message, :auto_close_delay
+
+        VALID_STATUSES = [:submitted, :cancelled].freeze
+
+        # @param status [Symbol] Status type (:submitted or :cancelled)
+        # @param message [String] Status message to display
+        # @param auto_close_delay [Integer] Delay before auto-closing tab in ms (default: 800)
+        # @param options [Hash] Additional options
+        def initialize(status:, message:, auto_close_delay: 800, **options)
+          @status = validate_status(status)
+          @message = message
+          @auto_close_delay = auto_close_delay
+          super(**options)
+        end
+
+        def render(view, state)
+          view.adapter.render_close_overlay(view, self, state)
+        end
+
+        # Whether this is a submitted status.
+        # @return [Boolean]
+        def submitted?
+          @status == :submitted
+        end
+
+        # Whether this is a cancelled status.
+        # @return [Boolean]
+        def cancelled?
+          @status == :cancelled
+        end
+
+        # Status-specific CSS modifier class.
+        # @return [String]
+        def status_modifier
+          "sw-close-overlay--#{@status}"
+        end
+
+        # CSS class list
+        def css_classes
+          "sw-close-overlay #{status_modifier}"
+        end
+
+        # Status icon character.
+        # @return [String]
+        def icon
+          submitted? ? "✓" : "✕"
+        end
+
+        private
+
+        def validate_status(status)
+          status = status.to_sym
+          unless VALID_STATUSES.include?(status)
+            raise ArgumentError, "Invalid status '#{status}'. Must be one of: #{VALID_STATUSES.join(', ')}"
+          end
+          status
+        end
+      end
+    end
+  end
+end