stream_weaver 0.3.0

data/examples/components/table_demo.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+# Demo of the Table component with all features
+# Run: ruby examples/components/table_demo.rb
+# Open: http://localhost:4567
+
+require_relative '../../lib/stream_weaver'
+
+# Sample data for demos
+USERS = [
+  { name: "Alice Johnson", email: "alice@example.com", balance: 1234.56, joined: Date.new(2024, 3, 15), active: true },
+  { name: "Bob Smith", email: "bob@example.com", balance: 567.89, joined: Date.new(2024, 6, 22), active: true },
+  { name: "Carol Davis", email: "carol@example.com", balance: 89012.34, joined: Date.new(2023, 11, 1), active: false },
+  { name: "Dan Wilson", email: "dan@example.com", balance: 234.00, joined: Date.new(2025, 1, 5), active: true }
+].freeze
+
+METRICS = {
+  month: %w[Jan Feb Mar Apr May Jun],
+  revenue: [45000, 52000, 48000, 61000, 55000, 67000],
+  users: [120, 145, 132, 178, 165, 203]
+}.freeze
+
+app "Table Component Demo", layout: :wide do
+  header "Table Component - All Features"
+  text "Demonstrating the enhanced table component with smart data inference, formatters, and interactive features."
+
+  tabs :demo_tabs do
+    # Tab 1: Basic Usage
+    tab "Basic" do
+      vstack spacing: :lg do
+        card do
+          header3 "Original API"
+          text "The original headers/rows API still works:"
+
+          table headers: ["Name", "Role", "Status"],
+                rows: [
+                  ["Alice", "Engineer", "Active"],
+                  ["Bob", "Designer", "Active"],
+                  ["Carol", "Manager", "On Leave"]
+                ],
+                striped: true
+        end
+
+        card do
+          header3 "Array of Hashes (Auto-Infer Headers)"
+          text "Pass an array of hashes - headers are inferred from keys:"
+
+          table [
+            { name: "Alice", role: "Engineer", department: "Platform" },
+            { name: "Bob", role: "Designer", department: "Product" },
+            { name: "Carol", role: "Manager", department: "Engineering" }
+          ], striped: true
+        end
+
+        card do
+          header3 "Hash of Arrays"
+          text "Pass a hash where keys are columns and values are arrays:"
+
+          table METRICS, striped: true, compact: true
+        end
+      end
+    end
+
+    # Tab 2: Column DSL with Formatters
+    tab "Formatters" do
+      vstack spacing: :lg do
+        card do
+          header3 "Column DSL with Built-in Formatters"
+          text "Define columns with formatting and alignment:"
+
+          table USERS do
+            column :name
+            column :email, header: "E-mail"
+            column :balance, format: :currency, align: :right
+            column :joined, header: "Join Date", format: :date
+            column(:active) { |u| u[:active] ? "Yes" : "No" }
+          end
+        end
+
+        card do
+          header3 "Available Formatters"
+          table headers: ["Formatter", "Input", "Output"],
+                rows: [
+                  [":date", "Date.today", Date.today.strftime("%b %d, %Y")],
+                  [":datetime", "Time.now", Time.now.strftime("%b %d, %Y %l:%M %p")],
+                  [":currency", "1234.56", "$1,234.56"],
+                  [":number", "1234567", "1,234,567"],
+                  [":percent", "0.42", "42%"]
+                ],
+                bordered: true, compact: true
+        end
+
+        card do
+          header3 "Custom Formatter (Proc)"
+          text "Use a Proc for custom formatting logic:"
+
+          table USERS do
+            column :name
+            column :balance, format: ->(v) { v > 1000 ? "#{(v/1000.0).round(1)}k" : v.to_s }, align: :right
+            column(:status) { |u| u[:active] ? "Active" : "Inactive" }
+          end
+        end
+      end
+    end
+
+    # Tab 3: Interactive Features
+    tab "Interactive" do
+      vstack spacing: :lg do
+        card do
+          header3 "Sortable Table"
+          text "Click column headers to sort. Handles both text and numeric sorting:"
+
+          table [
+            { product: "Widget A", price: 29.99, quantity: 150, revenue: 4498.50 },
+            { product: "Widget B", price: 49.99, quantity: 75, revenue: 3749.25 },
+            { product: "Widget C", price: 19.99, quantity: 300, revenue: 5997.00 },
+            { product: "Widget D", price: 99.99, quantity: 25, revenue: 2499.75 }
+          ], sortable: true, striped: true
+        end
+
+        card do
+          header3 "Sticky Header (Scroll to See)"
+          text "Header stays visible when scrolling long tables:"
+
+          # Generate more rows for scrolling demo
+          many_rows = (1..20).map do |i|
+            { id: i, name: "Item #{i}", category: %w[A B C].sample, value: rand(100..999) }
+          end
+
+          table many_rows, sticky_header: true, striped: true, compact: true
+        end
+
+        card do
+          header3 "Combined: Sortable + Sticky"
+
+          table USERS + USERS + USERS do
+            column :name
+            column :balance, format: :currency, align: :right
+            column :joined, format: :date
+          end
+        end
+      end
+    end
+
+    # Tab 4: Data Sources
+    tab "Data Sources" do
+      vstack spacing: :lg do
+        card do
+          header3 "State Binding"
+          text "Table reads from state - updates when state changes:"
+
+          state[:dynamic_items] ||= [
+            { item: "Apple", count: 5 },
+            { item: "Banana", count: 3 },
+            { item: "Cherry", count: 8 }
+          ]
+
+          table data: :dynamic_items, striped: true
+
+          hstack spacing: :sm do
+            button "Add Random Item" do |s|
+              fruits = %w[Mango Orange Grape Kiwi Peach]
+              s[:dynamic_items] << { item: fruits.sample, count: rand(1..10) }
+            end
+
+            button "Clear", style: :secondary do |s|
+              s[:dynamic_items] = []
+            end
+          end
+        end
+
+        card do
+          header3 "File Loading"
+          text "Load data from YAML or JSON files (like charts):"
+          md "`table file: \"data/users.yaml\", path: \"users\"`"
+          text "The file: and path: options work exactly like charts."
+        end
+
+        card do
+          header3 "Transform Block"
+          text "Process file data before display:"
+          md <<~MD
+            ```ruby
+            table file: "raw_data.yaml" do |data|
+              data.map { |r| { name: r[:n], value: r[:v] } }
+            end
+            ```
+          MD
+        end
+
+        card do
+          header3 "Markdown Links"
+          text "Enable clickable links in cells with markdown: true:"
+
+          table [
+            { issue: "[PROJ-101](https://example.com/issues/101)", title: "Fix login bug", status: "Open" },
+            { issue: "[PROJ-102](https://example.com/issues/102)", title: "Add dark mode", status: "In Progress" },
+            { issue: "[PROJ-103](https://example.com/issues/103)", title: "Update docs", status: "Closed" }
+          ], markdown: true, striped: true
+
+          text "Without markdown: true, links show as literal text."
+        end
+      end
+    end
+
+    # Tab 5: Styling
+    tab "Styling" do
+      columns do
+        column do
+          card do
+            header4 "Default"
+            table [{ a: 1, b: 2 }, { a: 3, b: 4 }]
+          end
+
+          card do
+            header4 "Striped"
+            table [{ a: 1, b: 2 }, { a: 3, b: 4 }, { a: 5, b: 6 }], striped: true
+          end
+
+          card do
+            header4 "Bordered"
+            table [{ a: 1, b: 2 }, { a: 3, b: 4 }], bordered: true
+          end
+        end
+
+        column do
+          card do
+            header4 "Compact"
+            table [{ a: 1, b: 2 }, { a: 3, b: 4 }], compact: true
+          end
+
+          card do
+            header4 "With Caption"
+            table [{ a: 1, b: 2 }, { a: 3, b: 4 }], caption: "Sample Data"
+          end
+
+          card do
+            header4 "All Options"
+            table [{ a: 1, b: 2 }, { a: 3, b: 4 }, { a: 5, b: 6 }],
+                  striped: true, bordered: true, compact: true,
+                  caption: "Full Style Demo"
+          end
+        end
+      end
+    end
+  end
+end.run!

data/examples/components/timer_with_state_demo.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# Demonstrates: accessing `state` inside streamer.replace blocks
+#
+# KEY PATTERN: Pass `state: state` to streamer.replace/append/prepend whenever
+# the block (or a helper it calls) needs to read session state.
+#
+# Without `state: state`, the replace block runs in FeedBuilder context where
+# `state` is not defined — you'll see:
+#   [StreamWeaver] Timer error: NameError: undefined local variable or method `state'
+#
+# Run with: ruby examples/components/timer_with_state_demo.rb
+
+require_relative "../../lib/stream_weaver"
+
+# Top-level helper — works inside replace blocks (global methods are accessible).
+# Receives state as an argument (not via DSL) since the helper is display-only.
+def render_status_panel(label:, count:, state:)
+  card do
+    hstack justify: :between do
+      text label
+      badge state[:filter] || "all", variant: :info
+    end
+    stat_display value: count, label: "items", color: :blue
+    text "Last refresh: #{Time.now.strftime('%H:%M:%S')}"
+  end
+end
+
+app "Timer + State Demo" do
+  header1 "Timer + State Demo"
+  md "Change the filter, then watch the panel refresh every 3 seconds. " \
+     "The filter value persists across timer refreshes."
+
+  state[:filter] ||= "all"
+
+  select :filter, %w[all active paused archived], submit: true
+
+  md "---"
+
+  div id: "status-panel" do
+    render_status_panel(
+      label:  "Showing: #{state[:filter]}",
+      count:  rand(10..99),
+      state:  state
+    )
+  end
+
+  # CORRECT: pass `state: state` so FeedBuilder exposes it inside the block
+  every(3) do |streamer|
+    streamer.replace("#status-panel", state: state) do
+      render_status_panel(
+        label:  "Showing: #{state[:filter]}",
+        count:  rand(10..99),
+        state:  state
+      )
+    end
+  end
+end.run!

data/examples/components/todo_due_dates.rb

@@ -0,0 +1,63 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Todo list with due dates -- exercises date_field inside a `form` block
+# (stream_weaver-nvu): title + due date submit together as one payload, and
+# the due date correctly lands in state[:new_task][:due_on] rather than
+# leaking into a flat top-level key.
+# Run: ruby examples/components/todo_due_dates.rb
+
+require_relative '../../lib/stream_weaver'
+require 'securerandom'
+
+App = app "Todo List with Due Dates" do
+  header1 "📝 Todo List"
+  md "`date_field` inside a `form` block: title + due date submit together."
+
+  state[:tasks] ||= []
+
+  header2 "Add a task"
+  form :new_task do
+    text_field :title, placeholder: "What needs doing?"
+    date_field :due_on, label: "Due date", min: Date.today.iso8601
+
+    submit "Add Task" do |form_values|
+      title = form_values[:title].to_s.strip
+      next if title.empty?
+
+      state[:tasks] << { id: SecureRandom.uuid, title: title, due_on: form_values[:due_on] }
+      state[:new_task] = { title: "", due_on: "" }
+    end
+  end
+
+  header2 "Tasks (#{state[:tasks].length})"
+
+  if state[:tasks].empty?
+    text "No tasks yet -- add one above.", tone: :muted
+  else
+    sorted_tasks = state[:tasks].sort_by do |task|
+      due = StreamWeaver::Components::DateField.to_date(task[:due_on])
+      [due ? 0 : 1, due || Date.new(9999, 12, 31)]
+    end
+
+    sorted_tasks.each do |task|
+      due = StreamWeaver::Components::DateField.to_date(task[:due_on])
+      overdue = due && due < Date.today
+
+      div class: "todo-item" do
+        text task[:title]
+        if due
+          text "Due #{due.iso8601}#{overdue ? ' (overdue)' : ''}", tone: overdue ? :error : :muted
+        else
+          text "No due date", tone: :muted
+        end
+        # key: a stable per-task id, so reordering by due date can't misroute the click
+        button "✓", key: task[:id], style: :secondary do |s|
+          s[:tasks].reject! { |t| t[:id] == task[:id] }
+        end
+      end
+    end
+  end
+end
+
+App.run! if __FILE__ == $0

data/examples/components/uat_gaps_demo.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+# UAT demo for three framework gaps closed in one session (2026-08-06):
+#   1. Table cell style escape hatches (col.style, id_style:, id_column:)
+#   2. collapsible subtitle:/badge_text:/badge_variant: parity with expandable_card
+#   3. copy_button primitive + code_block copy: affordance
+#
+# Run: SW_NO_OPEN=1 ruby examples/components/uat_gaps_demo.rb
+# Open: http://localhost:4567 (or whatever port the banner prints)
+
+require_relative '../../lib/stream_weaver'
+
+TEAM = [
+  { assignee: "Priya Patel", tier: "P1", open_issues: 4 },
+  { assignee: "Sam Okafor",  tier: "P2", open_issues: 1 },
+  { assignee: "Jin Watanabe", tier: "P0", open_issues: 7 }
+].freeze
+
+app "UAT: Table / Collapsible / Copy gaps", layout: :wide do
+  header "Three Gaps, One Session"
+  text "Each card below is a UAT checkpoint for one specific fix. See docs/ideas/2026-08-06-table-collapsible-clipboard-gaps.md."
+
+  vstack spacing: :lg do
+    # ---------------------------------------------------------------
+    card do
+      header3 "1a. Table: legacy default UNCHANGED (regression guard)"
+      text "Raw headers:/rows: table, no options. First column (Key) should still render accent-blue monospace, like every table before this session."
+      table headers: ["Key", "Title", "Status"],
+            rows: [
+              ["PROJ-101", "Fix login bug", "Open"],
+              ["PROJ-102", "Add dark mode", "In Progress"]
+            ]
+    end
+
+    card do
+      header3 "1b. Table: id_column escape hatch for raw tables"
+      text "Same shape as Sprint Focus's Team table -- first column is an Assignee name, not an id. id_column: false turns OFF the accent-mono treatment table-wide."
+      table headers: ["Assignee", "Tier", "Open Issues"],
+            rows: TEAM.map { |r| [r[:assignee], r[:tier], r[:open_issues]] },
+            id_column: false
+    end
+
+    card do
+      header3 "1c. Table: id_column pointed at a different column"
+      text "id_column: 1 -- only the Tier column (index 1) gets the identifier treatment."
+      table headers: ["Assignee", "Tier", "Open Issues"],
+            rows: TEAM.map { |r| [r[:assignee], r[:tier], r[:open_issues]] },
+            id_column: 1
+    end
+
+    card do
+      header3 "1d. Table: column DSL with style: Proc (per-row) + id_style: false"
+      text "Open Issues column gets a Proc style (red when > 3); Assignee opts out of accent via id_style: false even though it's column 0."
+      table TEAM do
+        column :assignee, id_style: false
+        column :tier
+        column :open_issues, header: "Open Issues",
+               style: ->(item) { item[:open_issues] > 3 ? "color: #c0392b; font-weight: 700;" : nil }
+      end
+    end
+
+    # ---------------------------------------------------------------
+    card do
+      header3 "2a. Collapsible: plain (legacy look, unchanged)"
+      collapsible "Show details" do
+        text "No subtitle, no badge -- must look exactly like it did before this session."
+      end
+    end
+
+    card do
+      header3 "2b. Collapsible: subtitle + badge (the actual gap)"
+      collapsible "Priority Alignment: cultiv-dashboard", subtitle: "12 issues, 83% aligned", badge_text: "P1", badge_variant: :danger do
+        text "This is the pattern that used to force a switch to expandable_card just for a badge."
+      end
+    end
+
+    card do
+      header3 "2c. Collapsible: class:/style: forwarding (previously silently dropped)"
+      collapsible "Custom-styled section", subtitle: "class:/style: now apply", badge_text: "NEW", badge_variant: :success,
+                  class: "uat-custom-collapsible", style: "border-color: #2563eb;" do
+        text "Inspect the outer div -- it should carry class=\"collapsible sw-collapsible uat-custom-collapsible\" and the inline border-color."
+      end
+    end
+
+    # ---------------------------------------------------------------
+    card do
+      header3 "3a. copy_button: plain text"
+      copy_button "Copy summary", text: "Sprint Focus: 3 gaps closed, 2613 tests green."
+    end
+
+    card do
+      header3 "3b. copy_button: hostile payload (quotes, newline, backslash, <script>)"
+      text "Click Copy, then paste somewhere to confirm the exact payload round-trips -- this is the safety-critical case."
+      copy_button "Copy hostile text", text: "Line one \"quoted\"\nLine two with a backslash \\ and <script>alert(1)</script>"
+    end
+
+    card do
+      header3 "3c. code_block: copy: true (opt-in, default off elsewhere)"
+      code_block <<~RUBY, lang: "ruby", copy: true
+        def hello(name)
+          puts "Hello, \#{name}!"
+        end
+      RUBY
+      text "Below: same code_block with copy: omitted -- must show NO copy affordance (regression guard)."
+      code_block <<~RUBY, lang: "ruby"
+        def goodbye(name)
+          puts "Goodbye, \#{name}!"
+        end
+      RUBY
+    end
+  end
+end.run!

data/examples/dashboard/feed_simulator.rb

@@ -0,0 +1,60 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# External Feed Simulator - pushes targeted updates to a running StreamWeaver app.
+#
+# Demonstrates the Feed DSL: connect by app name (via portfile) and push
+# updates using the same component DSL as the app itself. Zero raw HTML.
+#
+# Usage:
+#   1. Start the dashboard: bundle exec ruby examples/dashboard/live_dashboard.rb
+#   2. In another terminal:  bundle exec ruby examples/dashboard/feed_simulator.rb
+
+require_relative '../../lib/stream_weaver'
+
+feed = StreamWeaver.connect("Live Monitor")
+
+ACTIVITIES = [
+  ["Deploy v2.14.3 completed",        "Zero-downtime rolling deploy to production"],
+  ["Anomaly detected in API gateway",  "Latency spike on /api/v2/users (p99 > 200ms)"],
+  ["Auto-scaler triggered",           "Added 2 instances to web-pool (CPU > 75%)"],
+  ["SSL certificate renewed",         "Wildcard cert renewed for 90 days"],
+  ["Database failover test passed",    "RDS Multi-AZ failover completed in 28s"],
+  ["Rate limiter adjusted",           "API rate limit increased to 1000 req/min"],
+  ["Cache hit ratio improved",        "Redis cache hit ratio now at 94.2%"],
+  ["Backup verification passed",      "Nightly snapshot restored and validated"],
+].freeze
+
+ALERTS = [
+  [:critical, "High error rate on API",        "Error rate exceeded 5% threshold for 3 minutes"],
+  [:urgent,   "Memory pressure detected",      "Worker nodes approaching OOM limits"],
+  [:high,     "Slow query detected",           "Query on orders table taking >5s"],
+  [:normal,   "Log volume increasing",         "Log ingestion rate up 40% this week"],
+  [:critical, "Disk usage critical",           "Production DB volume at 94% capacity"],
+  [:urgent,   "SSL cert expiring soon",        "Certificate expires in 7 days"],
+].freeze
+
+puts "Feed simulator started - connected to #{feed.url}"
+puts "Press Ctrl+C to stop\n\n"
+
+loop do
+  # Push a new activity event (prepend to feed)
+  act = ACTIVITIES.sample
+  time_str = Time.now.strftime("%H:%M:%S")
+
+  feed.prepend("#activity-feed") do
+    activity_item time: time_str, title: act[0], summary: act[1], type: :task
+  end
+  puts "  [activity] #{time_str} #{act[0]}"
+  sleep rand(3.0..6.0)
+
+  # Occasionally push an alert update
+  if rand < 0.4
+    alert = ALERTS.sample
+    feed.prepend("#alerts-panel") do
+      priority_item priority: alert[0], title: alert[1], description: alert[2]
+    end
+    puts "  [alert]    #{alert[0].upcase}: #{alert[1]}"
+  end
+  sleep rand(2.0..5.0)
+end

data/examples/dashboard/live_dashboard.rb

@@ -0,0 +1,80 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Live Dashboard with Server-Push via StreamWeaver Streams
+#
+# This dashboard sets up a shell with stable DOM target IDs.
+# It receives real-time updates via SSE from:
+#   - An internal stream thread (built-in data source, using component DSL)
+#   - External scripts via POST /stream/push (pluggable data sources)
+#
+# Run with: bundle exec ruby examples/dashboard/live_dashboard.rb
+#
+# To push updates externally:
+#   bundle exec ruby examples/dashboard/feed_simulator.rb
+# Or manually:
+#   curl -X POST localhost:4567/stream/push \
+#     -d 'target=#metric-rps&html=<div>MANUAL</div>'
+
+require_relative '../../lib/stream_weaver'
+
+App = app "Live Monitor", theme: :dark, layout: :fluid do
+  app_shell sidebar_width: "360px" do
+    main do
+      app_header "System Monitor", variant: :primary do
+        pulse_indicator color: :green, label: "Live"
+      end
+
+      header2 "KEY METRICS"
+      grid cols: 3, gap: :md do
+        div(id: "metric-rps") do
+          card { stat_display value: "---", label: "REQ/SEC", color: :blue, size: :lg }
+        end
+        div(id: "metric-latency") do
+          card { stat_display value: "---", label: "LATENCY", color: :purple, size: :lg }
+        end
+        div(id: "metric-errors") do
+          card { stat_display value: "---", label: "ERROR RATE", color: :green, size: :lg }
+        end
+      end
+
+      header2 "ACTIVITY"
+      div(id: "activity-feed") do
+        text "Waiting for events..."
+      end
+    end
+
+    sidebar header: "Alerts" do
+      div(id: "alerts-panel") do
+        text "Monitoring..."
+      end
+    end
+  end
+
+  # Internal stream thread - pushes simulated metrics using component DSL.
+  # No raw HTML needed - same components as the app definition.
+  stream do |streamer|
+    loop do
+      rps = rand(1200..3500)
+      streamer.replace("#metric-rps") do
+        card { stat_display value: rps, label: "REQ/SEC", color: :blue, size: :lg }
+      end
+      sleep rand(1.5..3.0)
+
+      latency = rand(12..85)
+      streamer.replace("#metric-latency") do
+        card { stat_display value: "#{latency}ms", label: "LATENCY", color: :purple, size: :lg }
+      end
+      sleep rand(1.5..3.0)
+
+      err = (rand * 2.5).round(2)
+      color = err > 1.5 ? :red : :green
+      streamer.replace("#metric-errors") do
+        card { stat_display value: "#{err}%", label: "ERROR RATE", color: color, size: :lg }
+      end
+      sleep rand(2.0..4.0)
+    end
+  end
+end
+
+App.run! if __FILE__ == $0