stream_weaver 0.3.0

data/examples/timer_showcase.rb

@@ -0,0 +1,131 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Dev Machine Monitor
+# Live system metrics from YOUR machine — CPU, Memory, Disk — updated every few seconds.
+# Run with: bundle exec ruby examples/timer_showcase.rb
+
+require_relative "../lib/stream_weaver"
+require "etc"
+
+THRESHOLD = {
+  cpu:    { green: 2.0, yellow: 4.0 },
+  memory: { green: 70.0, yellow: 85.0 },
+  disk:   { green: 80.0, yellow: 90.0 }
+}.freeze
+
+LABEL = { cpu: "CPU LOAD (1m avg)", memory: "MEMORY %", disk: "DISK %" }.freeze
+UNIT  = { cpu: "", memory: "%", disk: "%" }.freeze
+METRIC_KEYS = %i[cpu memory disk].freeze
+MAX_ALERTS  = 50
+
+SPOTLIGHT_CSS = "<style>.sw-spotlight{box-shadow:0 0 0 3px var(--sw-color-primary,#c2410c)," \
+                "0 0 12px rgba(194,65,12,0.3) !important;transition:box-shadow 0.3s ease}</style>"
+
+CPU_PERCENT_PER_UNIT = (100.0 / Etc.nprocessors).freeze
+EMOJI = { red: "\u{1F534}", yellow: "\u{1F7E1}", green: "\u{1F7E2}" }.freeze
+
+def color_for(key, value)
+  t = THRESHOLD[key]
+  if value > t[:yellow] then :red
+  elsif value > t[:green] then :yellow
+  else :green
+  end
+end
+
+def read_cpu    = `sysctl -n vm.loadavg`.scan(/[\d.]+/)[0].to_f
+def read_memory = `ps -A -o %mem`.lines.drop(1).map(&:to_f).sum.round(1)
+def read_disk   = `df -h /`.lines.last.split[4].to_i
+
+def read_all_metrics
+  { cpu: read_cpu, memory: read_memory, disk: read_disk }
+end
+
+def cpu_as_percent(load_avg)
+  (load_avg * CPU_PERCENT_PER_UNIT).clamp(0, 100)
+end
+
+App = app "Dev Machine Monitor", theme: :dark, layout: :wide do
+  app_header "Dev Machine Monitor", variant: :primary do
+    pulse_indicator color: :green, label: "Live"
+  end
+
+  grid columns: 3, gap: :lg do
+    METRIC_KEYS.each do |key|
+      expandable_card key: key, title: key.to_s.capitalize, status: :green, initially_expanded: true do
+        div id: "metric-#{key}" do
+          stat_display value: "\u2014", label: LABEL[key], color: :blue
+        end
+      end
+    end
+  end
+
+  div id: "spotlight-css", style: "display:none"
+
+  header2 "Alerts"
+  div id: "alert-feed" do
+    text "Watching for threshold crossings..."
+  end
+
+  latest      = { cpu: 0.0, memory: 0.0, disk: 0.0 }
+  prev_status = { cpu: :green, memory: :green, disk: :green }
+  spotlight   = nil
+  alert_count = 0
+
+  every(3) do |streamer|
+    latest.merge!(read_all_metrics)
+
+    METRIC_KEYS.each do |key|
+      value   = latest[key]
+      color   = color_for(key, value)
+      display = "#{value}#{UNIT[key]}"
+
+      streamer.replace("#metric-#{key}") do
+        div id: "metric-#{key}" do
+          stat_display value: display, label: LABEL[key], color: color
+          status_dot status: color, pulse: color != :green
+        end
+      end
+    end
+  end
+
+  every(5) do |streamer|
+    streamer.replace("#spotlight-css", SPOTLIGHT_CSS)
+
+    scores  = { cpu: cpu_as_percent(latest[:cpu]), memory: latest[:memory], disk: latest[:disk] }
+    hottest = scores.max_by { |_, v| v }.first
+
+    if hottest != spotlight
+      streamer.remove_class("#card-#{spotlight}", "sw-spotlight") if spotlight
+      spotlight = hottest
+    end
+    streamer.add_class("#card-#{hottest}", "sw-spotlight")
+  end
+
+  every(10) do |streamer|
+    now = Time.now.strftime("%H:%M:%S")
+
+    METRIC_KEYS.each do |key|
+      value = latest[key]
+      color = color_for(key, value)
+      prev  = prev_status[key]
+
+      next if color == prev
+      next if alert_count >= MAX_ALERTS
+
+      direction = %i[yellow red].include?(color) ? "exceeded" : "dropped below"
+      threshold = color == :green ? THRESHOLD[key][:green] : THRESHOLD[key][:yellow]
+
+      streamer.prepend("#alert-feed") do
+        div style: "padding:4px 8px;border-bottom:1px solid rgba(255,255,255,0.1)" do
+          text "#{EMOJI[color]} #{key.to_s.capitalize} #{direction} #{threshold}#{UNIT[key]} (now #{value}#{UNIT[key]}) at #{now}"
+        end
+      end
+
+      alert_count += 1
+      prev_status[key] = color
+    end
+  end
+end
+
+App.run! if __FILE__ == $0

data/examples/tutorials/render_markdown.rb

@@ -0,0 +1,112 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# "Build My Todos: the StreamWeaver Way" -- the markdown rendering.
+#
+# TWIN NOTICE: this file renders content it does not own. The words live in
+# examples/tutorials/tutorial_content.rb and are rendered twice -- here into
+# docs/tutorials/the-streamweaver-way.md, and by
+# examples/tutorials/streamweaver_way_tutorial.rb as a :doc-theme StreamWeaver
+# app. Edit the outline, never a twin.
+#
+# Regenerate the checked-in markdown:
+#
+#   ruby examples/tutorials/render_markdown.rb
+#
+# spec/tutorial_twins_spec.rb fails if the checked-in file differs from a fresh
+# render, so the twins cannot drift apart silently.
+
+require_relative 'tutorial_content'
+
+module TutorialMarkdown
+  OUTPUT_PATH = File.expand_path('../../docs/tutorials/the-streamweaver-way.md', __dir__)
+
+  # The doc-app's callout variants map onto GitHub's alert syntax, which renders
+  # as a coloured admonition there and degrades to a plain blockquote anywhere
+  # else -- so the teaching weight of a `:error` gotcha survives both.
+  VARIANT_ALERTS = {
+    info: 'NOTE',
+    tip: 'TIP',
+    warning: 'WARNING',
+    error: 'CAUTION',
+    decision: 'IMPORTANT',
+    success: 'NOTE',
+    risk: 'CAUTION'
+  }.freeze
+
+  BANNER = <<~MD
+    <!-- GENERATED FILE -- do not edit directly. -->
+    <!-- Source outline: examples/tutorials/tutorial_content.rb -->
+    <!-- Regenerate:     ruby examples/tutorials/render_markdown.rb -->
+  MD
+
+  class << self
+    def render
+      parts = [BANNER.strip, "# #{TutorialContent::TITLE}", pill_line,
+               TutorialContent::LEAD.strip, contents]
+      TutorialContent::SECTIONS.each { |section| parts << section(section) }
+      "#{parts.join("\n\n")}\n"
+    end
+
+    def write!(path = OUTPUT_PATH)
+      require 'fileutils'
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, render)
+      path
+    end
+
+    private
+
+    def pill_line
+      pills = TutorialContent::PILLS.map { |p| p.is_a?(Hash) ? p[:text] : p }
+      "*#{TutorialContent::EYEBROW}* · #{pills.join(' · ')}"
+    end
+
+    def contents
+      lines = TutorialContent::SECTIONS.map do |s|
+        "- [#{s[:number]}. #{s[:title]}](##{s[:id]})"
+      end
+      ['## Contents', '', *lines].join("\n")
+    end
+
+    def section(section)
+      # An explicit anchor keeps the markdown's section ids identical to the
+      # doc-app's `doc_section_header id:` values, rather than depending on how
+      # a given renderer slugifies heading text.
+      head = %(<a id="#{section[:id]}"></a>\n\n## #{section[:number]}. #{section[:title]})
+      [head, *section[:blocks].map { |block| self.block(*block) }].join("\n\n")
+    end
+
+    def block(kind, *rest)
+      case kind
+      when :md      then rest[0].strip
+      when :code    then "```#{rest[0]}\n#{rest[1].strip}\n```"
+      when :table   then table(rest[0], rest[1])
+      when :callout then callout(*rest)
+      else raise ArgumentError, "unknown tutorial block: #{kind.inspect}"
+      end
+    end
+
+    def callout(variant, title, body)
+      quoted = body.strip.split("\n").map { |line| line.empty? ? '>' : "> #{line}" }
+      ["> [!#{VARIANT_ALERTS.fetch(variant)}]", "> **#{title}**", '>', *quoted].join("\n")
+    end
+
+    # Separator cells are exactly three ASCII hyphens: some renderers turn
+    # longer runs into em-dashes.
+    def table(headers, rows)
+      lines = [row(headers), "|#{(['---'] * headers.length).join('|')}|"]
+      rows.each { |r| lines << row(r) }
+      lines.join("\n")
+    end
+
+    def row(cells)
+      "| #{cells.map { |c| c.to_s.gsub('|', '\\|') }.join(' | ')} |"
+    end
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  path = TutorialMarkdown.write!
+  puts "wrote #{path} (#{File.size(path)} bytes, #{File.readlines(path).length} lines)"
+end

data/examples/tutorials/streamweaver_way_tutorial.rb

@@ -0,0 +1,44 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# "Build My Todos: the StreamWeaver Way" -- the :doc-theme rendering.
+#
+# TWIN NOTICE: this file renders content it does not own. The words live in
+# examples/tutorials/tutorial_content.rb and are rendered twice -- here as a
+# StreamWeaver doc-app, and by examples/tutorials/render_markdown.rb into
+# docs/tutorials/the-streamweaver-way.md. Edit the outline, never a twin.
+#
+#   SW_NO_OPEN=1 ruby examples/tutorials/streamweaver_way_tutorial.rb
+
+require_relative '../../lib/stream_weaver'
+require_relative 'tutorial_content'
+
+TutorialApp = app TutorialContent::TITLE, theme: :doc do
+  sidebar_toc sections: TutorialContent.toc
+
+  doc_header(
+    eyebrow: TutorialContent::EYEBROW,
+    title: TutorialContent::TITLE,
+    pills: TutorialContent::PILLS
+  )
+
+  md TutorialContent::LEAD
+
+  TutorialContent::SECTIONS.each do |section|
+    doc_section_header section[:number], section[:title], id: section[:id]
+
+    section[:blocks].each do |kind, *rest|
+      case kind
+      when :md      then md rest[0]
+      when :code    then code_block(rest[1], lang: rest[0])
+      when :table   then table(headers: rest[0], rows: rest[1])
+      when :callout
+        variant, title, body = rest
+        callout(variant: variant, title: title) { md body }
+      else raise ArgumentError, "unknown tutorial block: #{kind.inspect}"
+      end
+    end
+  end
+end
+
+TutorialApp.run! if __FILE__ == $PROGRAM_NAME