inquirex-ui 0.2.0

data/Rakefile

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "timeout"
+require "yard"
+
+def shell(*args)
+  puts "running: #{args.join(" ")}"
+  system(args.join(" "))
+end
+
+task :clean do
+  shell("rm -rf pkg/ tmp/ coverage/ doc/ ")
+end
+
+task gem: [:build] do
+  shell("gem install pkg/*")
+end
+
+task permissions: [:clean] do
+  shell("chmod -v o+r,g+r * */* */*/* */*/*/* */*/*/*/* */*/*/*/*/*")
+  shell("find . -type d -exec chmod o+x,g+x {} \\;")
+end
+
+task build: :permissions
+
+YARD::Rake::YardocTask.new(:doc) do |t|
+  t.files = %w[lib/**/*.rb exe/*.rb - README.md LICENSE.txt CHANGELOG.md]
+  t.options.unshift("--title", '"FlowEngine — DSL + AST for buildiong complex flows in Ruby."')
+  t.after = -> { exec("open doc/index.html") } if RUBY_PLATFORM =~ /darwin/
+end
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/exe/inquirex-ui

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+
+require "inquirex/ui"

data/justfile

@@ -0,0 +1,38 @@
+set shell := ["bash", "-lc"]
+
+rbenv := 'eval "$(rbenv init -)"'
+
+[no-exit-message]
+recipes:
+    @just --choose
+
+# Sync all dependencies
+install:
+    {{rbenv}} && bin/setup
+
+# Lint and reformat files
+lint-fix *args:
+    {{rbenv}} && bundle exec rubocop -a
+
+alias format := lint-fix
+
+# Lint and reformat files
+lint:
+    {{rbenv}} && bundle exec rubocop
+
+# Run all the tests
+test *args: 
+    {{rbenv}} &&  ENVIRONMENT=test bundle exec rspec {{args}}
+
+# Run tests with coverage
+test-coverage *args:
+    ENVIRONMENT=test COVERAGE=true bundle exec rspec
+
+clean:
+    #!/usr/bin/env bash
+    find . -name .DS_Store -delete -print || true
+    rm -rf tmp/*
+
+# Run all lefthook pre-commit hooks
+ci:
+    {{rbenv}} && lefthook run pre-commit --all-files

data/lefthook.yml

@@ -0,0 +1,35 @@
+output:
+  - summary
+  - failure
+
+pre-commit:
+  parallel: true
+  jobs:
+    - name: lint
+      run: bundle exec rubocop -c .rubocop.yml {staged_files}
+      glob: "*.{rb,Gemfile}"
+      stage_fixed: true
+
+    - name: check for conflict markers and whitespace issues
+      run: git --no-pager diff --check
+
+    # If tests take >1 second, move this (or just the long-running tests) to pre-push.
+    - name: run tests
+      run: just test
+
+    - name: fix rubocop formatting issues
+      run: bundle exec rubocop -a {staged_files}
+      glob: "*.{rb,Gemfile,gemspec}"
+      stage_fixed: true
+
+    - name: spell check
+      run: codespell {staged_files}
+      glob: "*.{rb,md,gemspec}"
+
+    - name: format markdown
+      run: mdformat {staged_files}
+      glob: "*.md"
+      stage_fixed: true
+
+    - name: scan for secrets
+      run: detect-secrets-hook --baseline .secrets.baseline

data/lib/inquirex/ui/dsl/flow_builder.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module UI
+    module DSL
+      # Extends Inquirex::DSL::FlowBuilder to use UI::DSL::StepBuilder for all steps,
+      # ensuring every node produced by Inquirex::UI.define carries widget hints.
+      class FlowBuilder < Inquirex::DSL::FlowBuilder
+        private
+
+        # Overrides the parent's add_step to instantiate UI::DSL::StepBuilder
+        # instead of the base StepBuilder, so widget hints are available in blocks.
+        def add_step(id, verb, &block)
+          builder = UI::DSL::StepBuilder.new(verb)
+          builder.instance_eval(&block) if block
+          @nodes[id.to_sym] = builder.build(id)
+        end
+      end
+    end
+  end
+end

data/lib/inquirex/ui/dsl/step_builder.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module UI
+    module DSL
+      # Extends Inquirex::DSL::StepBuilder with widget rendering hint methods.
+      # Used by FlowBuilder whenever a step block is evaluated inside Inquirex::UI.define.
+      #
+      # Additional DSL methods:
+      #   widget :radio_group, columns: 2     # desktop/default hint
+      #   widget_mobile :dropdown             # mobile-specific hint
+      class StepBuilder < Inquirex::DSL::StepBuilder
+        def initialize(verb)
+          super
+          @widget_hints = {}
+        end
+
+        # Sets a rendering hint for the given target context.
+        # Call once per target. Recognized targets: :desktop, :mobile (and any
+        # future targets adapters may define).
+        #
+        # @param target [Symbol] rendering context (default: :desktop)
+        # @param type [Symbol] widget type (see WidgetRegistry::WIDGET_TYPES)
+        # @param opts [Hash] widget-specific options (e.g. columns: 2)
+        #
+        # @example
+        #   widget target: :desktop, type: :radio_group, columns: 2
+        #   widget target: :mobile,  type: :dropdown
+        def widget(type:, target: :desktop, **opts)
+          @widget_hints[target.to_sym] = WidgetHint.new(type:, options: opts)
+        end
+
+        # Builds a UI::Node with widget hints (explicit or registry defaults).
+        #
+        # @param id [Symbol]
+        # @return [UI::Node]
+        def build(id)
+          effective_type = resolve_type
+          hints = @widget_hints.dup
+
+          # Fill in registry defaults for any targets not explicitly set.
+          %i[desktop mobile].each do |target|
+            hints[target] ||= WidgetRegistry.default_hint_for(effective_type, context: target)
+          end
+          hints.compact!
+
+          UI::Node.new(
+            id:,
+            verb:         @verb,
+            type:         effective_type,
+            question:     @question,
+            text:         @text,
+            options:      @options,
+            transitions:  @transitions,
+            skip_if:      @skip_if,
+            default:      @default,
+            widget_hints: hints.empty? ? nil : hints
+          )
+        end
+      end
+    end
+  end
+end

data/lib/inquirex/ui/node.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module UI
+    # Enriched node that extends Inquirex::Node with widget rendering hints.
+    # Hints are stored as a Hash keyed by target context (e.g. :desktop, :mobile).
+    # Additional targets can be introduced by adapters without changing this class.
+    #
+    # The hints are included in JSON serialization and consumed by frontend adapters
+    # (JS widget, TTY renderer, etc.). This class does NOT render anything itself.
+    #
+    # @attr_reader widget_hints [Hash{Symbol => WidgetHint}, nil]
+    #   Map of target → hint. nil for display nodes (say/header/btw/warning).
+    class Node < Inquirex::Node
+      attr_reader :widget_hints
+
+      # @param widget_hints [Hash{Symbol => WidgetHint}, nil]
+      # @param kwargs [Hash] all other params forwarded to Inquirex::Node
+      def initialize(widget_hints: nil, **)
+        # Set widget attr BEFORE calling super — super calls freeze.
+        @widget_hints = widget_hints&.freeze
+        super(**)
+      end
+
+      # Returns the explicit hint for the given target, or nil when not set.
+      #
+      # @param target [Symbol] e.g. :desktop, :mobile
+      # @return [WidgetHint, nil]
+      def widget_hint_for(target: :desktop)
+        widget_hints&.fetch(target.to_sym, nil)
+      end
+
+      # Returns the explicit hint for the given target, falling back to the
+      # registry default for this node's type when no explicit hint is set.
+      #
+      # @param target [Symbol] e.g. :desktop, :mobile
+      # @return [WidgetHint, nil]
+      def effective_widget_hint_for(target: :desktop)
+        widget_hint_for(target:) || WidgetRegistry.default_hint_for(type, context: target)
+      end
+
+      # Serializes to a plain Hash. When widget_hints are present, they are nested
+      # under the "widget" key as { "desktop" => {...}, "mobile" => {...} }.
+      #
+      # @return [Hash]
+      def to_h
+        hash = super
+        if widget_hints && !widget_hints.empty?
+          hash["widget"] = widget_hints.transform_keys(&:to_s)
+                                       .transform_values(&:to_h)
+        end
+        hash
+      end
+
+      # Deserializes from a plain Hash (string or symbol keys).
+      # Parses the nested "widget" target map in addition to all base Node fields.
+      #
+      # @param id [Symbol, String]
+      # @param hash [Hash]
+      # @return [UI::Node]
+      def self.from_h(id, hash)
+        widget_data = hash["widget"] || hash[:widget]
+
+        widget_hints =
+          if widget_data.is_a?(Hash) && widget_data.any? { |_, v| v.is_a?(Hash) }
+            # New format: { "desktop" => { "type" => "...", ... }, ... }
+            widget_data.each_with_object({}) do |(target, hint_hash), acc|
+              acc[target.to_sym] = WidgetHint.from_h(hint_hash)
+            end
+          end
+
+        verb             = hash["verb"]        || hash[:verb]
+        type             = hash["type"]        || hash[:type]
+        question         = hash["question"]    || hash[:question]
+        text             = hash["text"]        || hash[:text]
+        raw_options      = hash["options"]     || hash[:options]
+        transitions_data = hash["transitions"] || hash[:transitions] || []
+        skip_if_data     = hash["skip_if"]     || hash[:skip_if]
+        default          = hash["default"]     || hash[:default]
+
+        transitions = transitions_data.map { |t| Inquirex::Transition.from_h(t) }
+        skip_if     = skip_if_data ? Inquirex::Rules::Base.from_h(skip_if_data) : nil
+        options     = deserialize_options(raw_options)
+
+        new(
+          id:,
+          verb:,
+          type:,
+          question:,
+          text:,
+          options:,
+          transitions:,
+          skip_if:,
+          default:,
+          widget_hints:
+        )
+      end
+
+      private_class_method def self.deserialize_options(raw)
+        return nil if raw.nil?
+        return raw unless raw.is_a?(Array)
+        return raw if raw.empty?
+
+        raw.to_h { |o| [(o["value"] || o[:value]).to_s, (o["label"] || o[:label]).to_s] }
+      end
+    end
+  end
+end

data/lib/inquirex/ui/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module UI
+    VERSION = "0.2.0"
+  end
+end

data/lib/inquirex/ui/widget_hint.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module UI
+    # Immutable rendering hint attached to a step node.
+    # Carries a widget type (e.g. :radio_group) and an optional options hash
+    # (e.g. { columns: 2 }). Framework-agnostic — consumed by the JS widget,
+    # TTY adapter, or any other frontend renderer.
+    #
+    # @example
+    #   hint = WidgetHint.new(type: :radio_group, options: { columns: 2 })
+    #   hint.to_h  # => { "type" => "radio_group", "columns" => 2 }
+    WidgetHint = Data.define(:type, :options) do
+      def initialize(type:, options: {})
+        super(type: type.to_sym, options: options.transform_keys(&:to_sym).freeze)
+      end
+
+      # Serializes to a flat hash: type key + option keys merged in.
+      #
+      # @return [Hash<String, Object>]
+      def to_h
+        { "type" => type.to_s }.merge(options.transform_keys(&:to_s))
+      end
+
+      # Deserializes from a plain hash (string or symbol keys).
+      #
+      # @param hash [Hash]
+      # @return [WidgetHint]
+      def self.from_h(hash)
+        type = hash["type"] || hash[:type]
+        options = hash.reject { |k, _| k.to_s == "type" }
+                      .transform_keys(&:to_sym)
+        new(type:, options:)
+      end
+    end
+  end
+end

data/lib/inquirex/ui/widget_registry.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module UI
+    # Canonical mapping from Inquirex data types to default widget types per rendering context.
+    #
+    # Desktop defaults lean toward richer controls (radio groups, checkbox groups).
+    # Mobile defaults lean toward compact controls (dropdowns, toggles).
+    #
+    # Adapters (TTY, JS, Rails) use this to pick an appropriate renderer when
+    # the DSL author has not specified an explicit `widget` hint.
+    module WidgetRegistry
+      # All recognized widget type symbols. Adapters may not support every widget;
+      # they should fall back gracefully to a simpler one.
+      WIDGET_TYPES = %i[
+        text_input
+        textarea
+        number_input
+        currency_input
+        toggle
+        yes_no_buttons
+        yes_no
+        radio_group
+        dropdown
+        checkbox_group
+        multi_select_dropdown
+        select
+        multi_select
+        enum_select
+        multiline
+        mask
+        slider
+        date_picker
+        email_input
+        phone_input
+      ].freeze
+
+      # Default widget per data type and rendering context.
+      # Each context key (:desktop, :mobile, :tty, …) maps to a widget type symbol.
+      # Adapters consult this table when no explicit `widget` hint was given.
+      #
+      # TTY defaults align with tty-prompt methods:
+      #   text_input   → prompt.ask
+      #   multiline    → prompt.multiline
+      #   number_input → prompt.ask (with numeric conversion)
+      #   yes_no       → prompt.yes?
+      #   select       → prompt.select
+      #   multi_select → prompt.multi_select
+      DEFAULTS = {
+        string:     { desktop: :text_input, mobile: :text_input, tty: :text_input },
+        text:       { desktop: :textarea,        mobile: :textarea,       tty: :multiline },
+        integer:    { desktop: :number_input,    mobile: :number_input,   tty: :number_input },
+        decimal:    { desktop: :number_input,    mobile: :number_input,   tty: :number_input },
+        currency:   { desktop: :currency_input,  mobile: :currency_input, tty: :number_input },
+        boolean:    { desktop: :toggle,          mobile: :yes_no_buttons, tty: :yes_no },
+        enum:       { desktop: :radio_group,     mobile: :dropdown,       tty: :select },
+        multi_enum: { desktop: :checkbox_group,  mobile: :checkbox_group, tty: :multi_select },
+        date:       { desktop: :date_picker,     mobile: :date_picker,    tty: :text_input },
+        email:      { desktop: :email_input,     mobile: :email_input,    tty: :text_input },
+        phone:      { desktop: :phone_input,     mobile: :phone_input,    tty: :text_input }
+      }.freeze
+
+      # Returns the default widget type for a given data type and context.
+      #
+      # @param type [Symbol, String, nil] Inquirex data type (e.g. :enum, :integer)
+      # @param context [Symbol] :desktop or :mobile (default: :desktop)
+      # @return [Symbol, nil] widget type symbol, or nil if type is unknown
+      def self.default_for(type, context: :desktop)
+        DEFAULTS.dig(type&.to_sym, context)
+      end
+
+      # Returns a WidgetHint with the default widget for the given type + context,
+      # or nil when no default exists (e.g. for display verbs with no type).
+      #
+      # @param type [Symbol, String, nil]
+      # @param context [Symbol]
+      # @return [WidgetHint, nil]
+      def self.default_hint_for(type, context: :desktop)
+        widget_type = default_for(type, context:)
+        widget_type ? WidgetHint.new(type: widget_type) : nil
+      end
+    end
+  end
+end

data/lib/inquirex/ui.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "inquirex"
+require_relative "ui/version"
+require_relative "ui/widget_hint"
+require_relative "ui/widget_registry"
+require_relative "ui/node"
+require_relative "ui/dsl/step_builder"
+require_relative "ui/dsl/flow_builder"
+
+module Inquirex
+  # UI enrichment layer for Inquirex flows.
+  #
+  # Extends the core DSL with `widget` and `widget_mobile` rendering hints.
+  # Every node built via Inquirex::UI.define carries a WidgetHint describing
+  # the preferred UI control for that step's data type.
+  #
+  # Widget hints are:
+  #   - Framework-agnostic (no HTML/JS generated here)
+  #   - Included in JSON serialization
+  #   - Consumed by adapters: inquirex-tty, inquirex-js, inquirex-rails
+  #
+  # When no explicit hint is provided, WidgetRegistry supplies a sensible default
+  # for each data type × rendering context (desktop / mobile).
+  #
+  # @example
+  #   definition = Inquirex::UI.define id: "tax-2025" do
+  #     start :filing_status
+  #
+  #     ask :filing_status do
+  #       type :enum
+  #       question "What is your filing status?"
+  #       options single: "Single", married_jointly: "Married Filing Jointly"
+  #       widget target: :desktop, type: :radio_group, columns: 2
+  #       widget target: :mobile,  type: :dropdown
+  #       transition to: :next_step
+  #     end
+  #
+  #     ask :income do
+  #       type :currency
+  #       question "Estimated annual income?"
+  #       # No widget call — WidgetRegistry provides :currency_input by default
+  #       transition to: :done
+  #     end
+  #
+  #     say :done do
+  #       text "All done."
+  #     end
+  #   end
+  #
+  #   definition.step(:filing_status).widget_hint_for(target: :desktop)
+  #   # => #<data Inquirex::UI::WidgetHint type=:radio_group, options={columns: 2}>
+  #
+  #   definition.step(:income).effective_widget_hint_for(target: :desktop)
+  #   # => #<data Inquirex::UI::WidgetHint type=:currency_input, options={}>
+  #
+  #   definition.to_json
+  #   # => '{"start":"filing_status","steps":{"filing_status":{...,"widget":{"type":"radio_group","columns":2},...}}}'
+  #
+  module UI
+    # Builds an immutable Definition where every node is a UI::Node with widget hints.
+    # Accepts the same arguments as Inquirex.define.
+    #
+    # @param id [String, nil] optional flow identifier
+    # @param version [String] semver (default: "1.0.0")
+    # @yield context of UI::DSL::FlowBuilder
+    # @return [Inquirex::Definition]
+    def self.define(id: nil, version: "1.0.0", &)
+      builder = UI::DSL::FlowBuilder.new(id:, version:)
+      builder.instance_eval(&)
+      builder.build
+    end
+  end
+end

data/sig/inquirex/ui.rbs

@@ -0,0 +1,6 @@
+module Inquirex
+  module Ui
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,165 @@
+--- !ruby/object:Gem::Specification
+name: inquirex-ui
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Konstantin Gredeskoul
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: inquirex
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-its
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: Enriches Inquirex flow definitions with framework-agnostic widget rendering
+  metadata. Adds `widget` and `widget_mobile` DSL verbs that attach WidgetHint objects
+  to nodes. Consumed by inquirex-tty, inquirex-js, and inquirex-rails adapters. Produces
+  enriched JSON — no HTML or JavaScript generated.
+email:
+- kigster@gmail.com
+executables:
+- inquirex-ui
+extensions: []
+extra_rdoc_files: []
+files:
+- ".relaxed_rubocop.yml"
+- ".ruby-version"
+- ".secrets.baseline"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/inquirex-ui
+- justfile
+- lefthook.yml
+- lib/inquirex/ui.rb
+- lib/inquirex/ui/dsl/flow_builder.rb
+- lib/inquirex/ui/dsl/step_builder.rb
+- lib/inquirex/ui/node.rb
+- lib/inquirex/ui/version.rb
+- lib/inquirex/ui/widget_hint.rb
+- lib/inquirex/ui/widget_registry.rb
+- sig/inquirex/ui.rbs
+homepage: https://github.com/inquirex/inquirex-ui
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/inquirex/inquirex-ui
+  source_code_uri: https://github.com/inquirex/inquirex-ui
+  changelog_uri: https://github.com/inquirex/inquirex-ui/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Widget rendering hints for Inquirex flow definitions
+test_files: []