its-showtime 0.1.1

data/lib/showtime/charts.rb

@@ -0,0 +1,229 @@
+require "active_support"
+
+module Showtime
+  module Charts
+    SUPPORTED_TYPES = %w[line bar column area pie scatter].freeze
+
+    class ValidationError < StandardError; end
+
+    def self.figure(chart_type:, data:, encoding:, colorway: nil, layout: {}, config: {})
+      Validator.validate_chart_type!(chart_type)
+      normalized_encoding = Validator.normalize_encoding(encoding, chart_type)
+      normalized_data = DataNormalizer.normalize(data, normalized_encoding, chart_type: chart_type)
+      Validator.validate_data!(chart_type, normalized_data, normalized_encoding)
+
+      {
+        chart_type: chart_type.to_s,
+        data: normalized_data,
+        encoding: normalized_encoding,
+        colorway: colorway,
+        layout: layout,
+        config: config,
+      }.compact
+    end
+
+    module Validator
+      module_function
+
+      def validate_chart_type!(chart_type)
+        return if SUPPORTED_TYPES.include?(chart_type.to_s)
+
+        raise ValidationError, "Unsupported chart_type #{chart_type}"
+      end
+
+      def normalize_encoding(encoding, chart_type)
+        if chart_type.to_s == "pie"
+          base = (encoding || {}).transform_keys(&:to_sym)
+          label_key = base[:label] || "label"
+          value_key = base[:value] || "value"
+
+          return {
+            label: label_key.to_s,
+            value: value_key.to_s
+          }
+        end
+
+        raise ValidationError, "encoding is required" if encoding.nil?
+
+        enc = encoding.transform_keys(&:to_sym)
+        raise ValidationError, "encoding.x is required" unless enc[:x]
+        raise ValidationError, "encoding.y is required" unless enc[:y]
+
+        {
+          x: enc[:x].to_s,
+          y: enc[:y].to_s,
+          series: enc[:series]&.to_s,
+          color: enc[:color]&.to_s,
+          stack: enc.key?(:stack) ? !!enc[:stack] : nil
+        }.compact
+      end
+
+      def validate_data!(chart_type, data, encoding)
+        if chart_type.to_s == "pie"
+          unless data.is_a?(Array) && data.all? { |slice| slice.key?("label") && slice.key?("value") }
+            raise ValidationError, "pie data requires label and value keys"
+          end
+          return
+        end
+
+        named_series = data.is_a?(Array) && data.first.is_a?(Hash) && data.first.key?(:name)
+        if named_series && encoding[:series].nil?
+          raise ValidationError, "encoding.series is required when data contains named series"
+        end
+      end
+    end
+
+    module DataNormalizer
+      module_function
+
+      def normalize(data, encoding, chart_type:)
+        return normalize_pie(data, encoding) if chart_type.to_s == "pie"
+
+        case data
+        when Hash
+          if data.values.all? { |v| v.is_a?(Array) }
+            normalize_hash_of_arrays(data, encoding)
+          else
+            normalize_grouped_hash(data, encoding)
+          end
+        when Array
+          return [] if data.empty?
+          if data.first.is_a?(Array)
+            normalize_array_of_arrays(data, encoding)
+          elsif data.first.is_a?(Hash)
+            normalize_array_of_hashes(data, encoding)
+          else
+            raise ValidationError, "Unsupported array contents #{data.first.class}"
+          end
+        when ->(d) { polars_dataframe?(d) }
+          normalize_polars_dataframe(data, encoding)
+        else
+          raise ValidationError, "Unsupported data type #{data.class}"
+        end
+      end
+
+      def polars_dataframe?(data)
+        data.respond_to?(:columns) && (data.respond_to?(:rows) || data.respond_to?(:to_a))
+      end
+
+      def normalize_grouped_hash(data, encoding)
+        data.sort_by { |k, _| k.to_s }.map do |key, value|
+          { "x" => key.is_a?(String) ? key : key.to_s, "y" => value }
+        end
+      end
+
+      def normalize_array_of_arrays(data, encoding)
+        data.sort_by { |row| row[0] }.map do |row|
+          { "x" => row[0], "y" => row[1] }
+        end
+      end
+
+      def normalize_hash_of_arrays(data, encoding)
+        raise ValidationError, "encoding.series is required for multi-series data" if encoding[:series].nil?
+
+        x_key = encoding.fetch(:x).to_s
+        y_key = encoding.fetch(:y).to_s
+
+        data.sort_by { |series_name, _| series_name.to_s }.map do |series_name, rows|
+          sorted_rows = rows.sort_by { |row| row[0] }
+          {
+            name: series_name.to_s,
+            data: sorted_rows.map { |row| { "x" => row[0], "y" => row[1] } },
+          }
+        end
+      end
+
+      def normalize_array_of_hashes(data, encoding)
+        x_key = encoding.fetch(:x).to_s
+        y_key = encoding.fetch(:y).to_s
+        series_key = encoding[:series]&.to_s
+
+        if series_key
+          grouped = data.group_by { |row| row[series_key] || row[series_key.to_sym] }
+          grouped.keys.sort_by(&:to_s).map do |series_name|
+            points = grouped[series_name].sort_by { |row| row[x_key] || row[x_key.to_sym] }
+            {
+              name: series_name.to_s,
+              data: points.map do |row|
+                {
+                  "x" => coerce_value(row[x_key] || row[x_key.to_sym]),
+                  "y" => coerce_value(row[y_key] || row[y_key.to_sym])
+                }
+              end,
+            }
+          end
+        else
+          data.sort_by { |row| row[x_key] || row[x_key.to_sym] }.map do |row|
+            {
+              "x" => coerce_value(row[x_key] || row[x_key.to_sym]),
+              "y" => coerce_value(row[y_key] || row[y_key.to_sym])
+            }
+          end
+        end
+      end
+
+      def coerce_value(value)
+        return value if value.is_a?(String) || value.is_a?(Numeric)
+        return value.to_f if value.respond_to?(:to_f)
+        value
+      end
+
+      def normalize_polars_dataframe(df, encoding)
+        rows =
+          if df.respond_to?(:rows)
+            df.rows(named: true)
+          else
+            # Fall back to to_a; if it returns arrays, zip with columns
+            raw = df.to_a
+            if raw.first.is_a?(Hash)
+              raw
+            else
+              cols = df.columns.map(&:to_s)
+              raw.map { |row| cols.zip(row).to_h }
+            end
+          end
+
+        normalize_array_of_hashes(rows, encoding)
+      end
+
+      def normalize_pie(data, encoding)
+        label_key = encoding.fetch(:label).to_s
+        value_key = encoding.fetch(:value).to_s
+
+        case data
+        when Hash
+          data.sort_by { |k, _| k.to_s }.map { |k, v| { "label" => k.to_s, "value" => v } }
+        when Array
+          return [] if data.empty?
+          if data.first.is_a?(Hash)
+            data.sort_by { |row| row[label_key] || row[label_key.to_sym] }.map do |row|
+              { "label" => row[label_key] || row[label_key.to_sym], "value" => row[value_key] || row[value_key.to_sym] }
+            end
+          elsif data.first.is_a?(Array)
+            data.sort_by { |row| row[0].to_s }.map { |row| { "label" => row[0].to_s, "value" => row[1] } }
+          else
+            raise ValidationError, "Unsupported array contents #{data.first.class}"
+          end
+        when ->(d) { polars_dataframe?(d) }
+          rows =
+            if data.respond_to?(:rows)
+              data.rows(named: true)
+            else
+              raw = data.to_a
+              if raw.first.is_a?(Hash)
+                raw
+              else
+                cols = data.columns.map(&:to_s)
+                raw.map { |row| cols.zip(row).to_h }
+              end
+            end
+          rows.sort_by { |row| row[label_key] || row[label_key.to_sym] }.map do |row|
+            { "label" => row[label_key] || row[label_key.to_sym], "value" => row[value_key] || row[value_key.to_sym] }
+          end
+        else
+          raise ValidationError, "Unsupported data type #{data.class}"
+        end
+      end
+    end
+  end
+end

data/lib/showtime/component_registry.rb

@@ -0,0 +1,38 @@
+module Showtime
+  # Component registry for tracking dependencies and updates
+  class ComponentRegistry
+    def initialize
+      @dependencies = {} # key -> Set of dependent component keys
+      @dirty_components = Set.new
+    end
+
+    # Register a component's dependencies
+    def register_dependencies(key, dependencies)
+      dependencies.each do |dep|
+        @dependencies[dep] ||= Set.new
+        @dependencies[dep].add(key)
+      end
+    end
+    
+    # Find all components that depend on a key
+    def find_dependents(key)
+      @dependencies[key] || Set.new
+    end
+
+    # Mark a component and its dependents as needing update
+    def mark_dirty(key)
+      @dirty_components.add(key)
+      find_dependents(key).each { |dep_key| mark_dirty(dep_key) }
+    end
+
+    # Get list of components that need updates
+    def dirty_components
+      @dirty_components.dup
+    end
+
+    # Clear the dirty components list
+    def clear_dirty
+      @dirty_components.clear
+    end
+  end
+end

data/lib/showtime/components/Components.md

@@ -0,0 +1,309 @@
+# Creating a New Showtime Component
+
+This guide walks through all the steps needed to create a new component in Showtime and make it available in the frontend.
+
+## Overview
+
+Showtime components consist of two main parts:
+1. A Ruby component class in the backend
+2. A React component in the frontend
+
+## Metric Component (quick use)
+
+Render a KPI-style number with an optional delta indicator:
+
+```ruby
+St.metric("Revenue", value: 12_000, delta: "+5%", prefix: "$", suffix: "/wk", help: "vs last week")
+```
+
+## Backend Implementation
+
+### 1. Choose the Appropriate File
+
+First, determine which Ruby file should contain your component based on its type:
+
+- `alerts.rb`: Alert/notification components
+- `charts.rb`: Data visualization components
+- `data.rb`: Data display components
+- `inputs.rb`: User input components
+- `layout.rb`: Layout/structure components
+- `media.rb`: Media (images, video) components
+- `text.rb`: Text display components
+
+### 2. Create the Component Class
+
+Create a new class that inherits from `BaseComponent`. Example:
+
+```ruby
+module Showtime
+  module Components
+    class MyComponent < BaseComponent
+      attr_reader :label, :value
+      
+      def initialize(label, value: nil, key: nil, help: nil)
+        super(key: key, help: help)
+        @label = label
+        @value = value
+      end
+      
+      def to_h
+        super.merge({
+          label: @label,
+          value: @value
+        })
+      end
+    end
+  end
+end
+```
+
+Key points:
+- Inherit from `BaseComponent`
+- Define attributes using `attr_reader`
+- Initialize with necessary parameters
+- Implement `to_h` method to serialize component data
+
+#### Optional Parameters
+
+- **key**: A unique identifier for the component. It's used for:
+  - State management: Tracking component values across sessions
+  - WebSocket communication: Identifying which component triggered a change
+  - Component updates: Ensuring the correct component gets updated
+  - If not provided, some components like buttons will auto-generate a unique key
+  - Example format: `button_counter`, `data_table_1`, `color_picker_theme`
+
+- **help**: A help text that appears below the component to provide additional information
+
+### 3. Add Method to St Module
+
+Add a method to expose your component through the `St` module:
+
+```ruby
+module St
+  def self.my_component(label, value: nil, key: nil, help: nil)
+    Showtime::session.add_element(
+      Showtime::Components::MyComponent.new(
+        label, 
+        value: value, 
+        key: key, 
+        help: help
+      )
+    )
+  end
+end
+```
+
+## Frontend Implementation
+
+### 1. Create the React Component
+
+Create a new component file in `frontend/src/components/ui/` in the appropriate subdirectory:
+
+```typescript
+// frontend/src/components/ui/my-component/MyComponent.tsx
+import React from 'react';
+
+interface MyComponentProps {
+  label: string;
+  value?: any;
+  help?: string;
+  onChange?: (value: any) => void;
+}
+
+export function MyComponent({ 
+  label, 
+  value, 
+  help, 
+  onChange 
+}: MyComponentProps) {
+  return (
+    <div className="mb-4">
+      <label className="block text-sm font-medium text-gray-700 dark:text-gray-300">
+        {label}
+      </label>
+      {/* Your component UI here */}
+    </div>
+  );
+}
+```
+
+### 2. Export the Component
+
+Add your component to `frontend/src/components/ui/index.ts`:
+
+```typescript
+export { MyComponent } from './my-component/MyComponent';
+```
+
+### 3. Add to ComponentRenderer
+
+Update `frontend/src/components/ComponentRenderer.tsx`:
+
+1. Import your component:
+```typescript
+import { MyComponent } from './ui';
+```
+
+2. Add a case in the switch statement:
+```typescript
+case 'my_component':
+  return (
+    <MyComponent
+      label={component.label || ''}
+      value={component.value}
+      onChange={handleChange}
+      help={component.help}
+    />
+  );
+```
+
+## Example: Creating a Color Picker Component
+
+Here's a complete example of creating a color picker component:
+
+### Backend (lib/showtime/components/inputs.rb)
+
+```ruby
+module Showtime
+  module Components
+    class ColorPicker < BaseComponent
+      attr_reader :label, :value
+      
+      def initialize(label, value: "#000000", key: nil, help: nil)
+        super(key: key, help: help)
+        @label = label
+        @value = value
+      end
+      
+      def to_h
+        super.merge({
+          label: @label,
+          value: @value
+        })
+      end
+    end
+  end
+
+  module St
+    def self.color_picker(label, value: "#000000", key: nil, help: nil)
+      Showtime::session.add_element(
+        Showtime::Components::ColorPicker.new(
+          label, 
+          value: value, 
+          key: key, 
+          help: help
+        )
+      )
+    end
+  end
+end
+```
+
+### Frontend
+
+1. Create the component (frontend/src/components/ui/input/ColorPicker.tsx):
+
+```typescript
+import React from 'react';
+
+interface ColorPickerProps {
+  label: string;
+  value: string;
+  help?: string;
+  onChange?: (value: string) => void;
+}
+
+export function ColorPicker({ 
+  label, 
+  value = "#000000", 
+  help, 
+  onChange 
+}: ColorPickerProps) {
+  return (
+    <div className="mb-4">
+      <label className="block text-sm font-medium text-gray-700 dark:text-gray-300">
+        {label}
+      </label>
+      <input
+        type="color"
+        value={value}
+        onChange={(e) => onChange?.(e.target.value)}
+        className="mt-1 block w-full"
+      />
+      {help && (
+        <p className="mt-1 text-sm text-gray-500 dark:text-gray-400">
+          {help}
+        </p>
+      )}
+    </div>
+  );
+}
+```
+
+2. Export the component in frontend/src/components/ui/index.ts:
+
+```typescript
+export { ColorPicker } from './input/ColorPicker';
+```
+
+3. Add to ComponentRenderer.tsx:
+
+```typescript
+// In the imports section:
+import {
+  Alert,
+  Button,
+  ColorPicker, // Add this line
+  DateInput,
+  // ... other imports
+} from './ui';
+
+// In the switch statement:
+case 'color_picker':
+  return (
+    <ColorPicker
+      label={component.label || ''}
+      value={component.value}
+      onChange={handleChange}
+      help={component.help}
+    />
+  );
+```
+
+### Usage Example
+
+With everything set up, the component can be used in your Showtime applications:
+
+```ruby
+St.color_picker("Choose a color", value: "#ff0000", help: "Select your favorite color")
+```
+
+## Best Practices
+
+1. **Component Naming**
+   - Use CamelCase for component class names
+   - Use snake_case for component types and method names
+
+2. **State Management**
+   - Use session state for persistent values
+   - Handle state updates through the WebSocket connection
+
+3. **Type Safety**
+   - Define clear interfaces in TypeScript
+   - Validate input parameters in Ruby
+
+4. **Styling**
+   - Use Tailwind CSS classes for styling
+   - Support both light and dark themes
+   - Follow existing component patterns
+
+5. **Error Handling**
+   - Provide meaningful error messages
+   - Handle edge cases gracefully
+
+6. **Documentation**
+   - Document all parameters
+   - Include usage examples
+   - Explain any special behaviors
+
+Following this guide will ensure your new component integrates seamlessly with the Showtime framework and provides a consistent experience for users.

data/lib/showtime/components/alerts.rb

@@ -0,0 +1,83 @@
+require_relative 'base'
+
+module Showtime
+  module Components
+    class Info < BaseComponent
+      attr_reader :text
+      
+      def initialize(text)
+        super()
+        @text = text
+      end
+      
+      def to_h
+        super.merge({
+          text: @text
+        })
+      end
+    end
+    
+    class Success < BaseComponent
+      attr_reader :text
+      
+      def initialize(text)
+        super()
+        @text = text
+      end
+      
+      def to_h
+        super.merge({
+          text: @text
+        })
+      end
+    end
+    
+    class Warning < BaseComponent
+      attr_reader :text
+      
+      def initialize(text)
+        super()
+        @text = text
+      end
+      
+      def to_h
+        super.merge({
+          text: @text
+        })
+      end
+    end
+    
+    class Error < BaseComponent
+      attr_reader :text
+      
+      def initialize(text)
+        super()
+        @text = text
+      end
+      
+      def to_h
+        super.merge({
+          text: @text
+        })
+      end
+    end
+  end
+
+  module St
+    def self.info(text)
+      Showtime::session.add_element(Showtime::Components::Info.new(text))
+    end
+    
+    def self.success(text)
+      Showtime::session.add_element(Showtime::Components::Success.new(text))
+    end
+    
+    def self.warning(text)
+      Showtime::session.add_element(Showtime::Components::Warning.new(text))
+    end
+    
+    def self.error(text)
+      Showtime::session.add_element(Showtime::Components::Error.new(text))
+    end
+  end
+end 

data/lib/showtime/components/base.rb

@@ -0,0 +1,63 @@
+require 'json'
+require 'base64'
+require 'securerandom'
+require 'active_support/all'
+
+module Showtime
+  module Components
+    class BaseComponent
+      attr_reader :key, :help, :errors
+
+      def initialize(key: nil, help: nil)
+        @key = key || generate_unique_id
+        @help = help
+        @errors = []
+      end
+
+      def generate_unique_id
+        # Generate a stable key if none provided
+        if @key.nil?
+          # Add counter to ensure uniqueness
+          counter = Showtime::Helpers.update_component_counter(component_type)
+          @key = "#{component_type}_#{counter}"
+        elsif !@key.to_s.start_with?("#{component_type}_")
+          @key = "#{component_type}_#{@key}"
+        end
+      end
+
+      def validate
+        # Placeholder for validation logic
+        # For example, check if the component has a valid key
+        # if @key.nil? || @key.empty?
+        #  @errors << "Key cannot be nil or empty"
+        # end
+        # returns errors if any
+        @errors
+      end
+      
+      def to_h
+        {
+          type: component_type,
+          key: @key,
+          help: @help,
+          errors: validate,
+        }
+      end
+
+      def value
+        # Retrieve value from session if key is provided
+        @key ? St.get(@key) : @value
+      end
+
+      def component_type
+        self.class.name.demodulize.underscore
+      end
+      
+      private
+
+      def self.component_type
+        name.demodulize.underscore
+      end
+    end
+  end
+end