inquirex-ui 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b9f77805162e181fd5c4401a8f4d49842b12dddb2983f0a9d7776ca41f278c3b
+  data.tar.gz: aa6be396e7fb41a435c1d83d1c11222a8b0d8eab520498ce5f4df5e05a012c73
+SHA512:
+  metadata.gz: 83867ad8179b78032bd8b2b69d5ee803ede04ec5d6aa6ad465ec38956a64531c2d3d0fbe38b2784e1765899fa477503bad29b0f7ea5201f0fd78957762643dd5
+  data.tar.gz: 9c9992150abd220d2af4cb8c7fc07b19ac2e152d87c12d31172d17f02adbc4acb0b24d953aa49cf83743e78243dc2ac819bee1e6cddc41434f8f93477d41872d

data/.relaxed_rubocop.yml

@@ -0,0 +1,153 @@
+# Relaxed.Ruby.Style
+## Version 2.5
+
+Style/Alias:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylealias
+
+Style/AsciiComments:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styleasciicomments
+
+Style/BeginBlock:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylebeginblock
+
+Style/BlockDelimiters:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styleblockdelimiters
+
+Style/CommentAnnotation:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylecommentannotation
+
+Style/Documentation:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styledocumentation
+
+Layout/DotPosition:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#layoutdotposition
+
+Style/DoubleNegation:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styledoublenegation
+
+Style/EndBlock:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styleendblock
+
+Style/FormatString:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styleformatstring
+
+Style/IfUnlessModifier:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styleifunlessmodifier
+
+Style/Lambda:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylelambda
+
+Style/ModuleFunction:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylemodulefunction
+
+Style/MultilineBlockChain:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylemultilineblockchain
+
+Style/NegatedIf:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylenegatedif
+
+Style/NegatedWhile:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylenegatedwhile
+
+Style/NumericPredicate:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylenumericpredicate
+
+Style/ParallelAssignment:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styleparallelassignment
+
+Style/PercentLiteralDelimiters:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylepercentliteraldelimiters
+
+Style/PerlBackrefs:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styleperlbackrefs
+
+Style/Semicolon:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylesemicolon
+
+Style/SignalException:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylesignalexception
+
+Style/SingleLineBlockParams:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylesinglelineblockparams
+
+Style/SingleLineMethods:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylesinglelinemethods
+
+Layout/SpaceBeforeBlockBraces:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#layoutspacebeforeblockbraces
+
+Layout/SpaceInsideParens:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#layoutspaceinsideparens
+
+Style/SpecialGlobalVars:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylespecialglobalvars
+
+Style/StringLiterals:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylestringliterals
+
+Style/TrailingCommaInArguments:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styletrailingcommainarguments
+
+Style/TrailingCommaInArrayLiteral:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styletrailingcommainarrayliteral
+
+Style/TrailingCommaInHashLiteral:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styletrailingcommainhashliteral
+
+Style/SymbolArray:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#stylesymbolarray
+
+Style/WhileUntilModifier:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylewhileuntilmodifier
+
+Style/WordArray:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylewordarray
+
+Lint/AmbiguousRegexpLiteral:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#lintambiguousregexpliteral
+
+Lint/AssignmentInCondition:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#lintassignmentincondition
+
+Layout/LineLength:
+  Enabled: false
+
+Metrics:
+  Enabled: false
+

data/.ruby-version

@@ -0,0 +1 @@
+4.0.2

data/.secrets.baseline

@@ -0,0 +1,127 @@
+{
+  "version": "1.5.0",
+  "plugins_used": [
+    {
+      "name": "ArtifactoryDetector"
+    },
+    {
+      "name": "AWSKeyDetector"
+    },
+    {
+      "name": "AzureStorageKeyDetector"
+    },
+    {
+      "name": "Base64HighEntropyString",
+      "limit": 4.5
+    },
+    {
+      "name": "BasicAuthDetector"
+    },
+    {
+      "name": "CloudantDetector"
+    },
+    {
+      "name": "DiscordBotTokenDetector"
+    },
+    {
+      "name": "GitHubTokenDetector"
+    },
+    {
+      "name": "GitLabTokenDetector"
+    },
+    {
+      "name": "HexHighEntropyString",
+      "limit": 3.0
+    },
+    {
+      "name": "IbmCloudIamDetector"
+    },
+    {
+      "name": "IbmCosHmacDetector"
+    },
+    {
+      "name": "IPPublicDetector"
+    },
+    {
+      "name": "JwtTokenDetector"
+    },
+    {
+      "name": "KeywordDetector",
+      "keyword_exclude": ""
+    },
+    {
+      "name": "MailchimpDetector"
+    },
+    {
+      "name": "NpmDetector"
+    },
+    {
+      "name": "OpenAIDetector"
+    },
+    {
+      "name": "PrivateKeyDetector"
+    },
+    {
+      "name": "PypiTokenDetector"
+    },
+    {
+      "name": "SendGridDetector"
+    },
+    {
+      "name": "SlackDetector"
+    },
+    {
+      "name": "SoftlayerDetector"
+    },
+    {
+      "name": "SquareOAuthDetector"
+    },
+    {
+      "name": "StripeDetector"
+    },
+    {
+      "name": "TelegramBotTokenDetector"
+    },
+    {
+      "name": "TwilioKeyDetector"
+    }
+  ],
+  "filters_used": [
+    {
+      "path": "detect_secrets.filters.allowlist.is_line_allowlisted"
+    },
+    {
+      "path": "detect_secrets.filters.common.is_ignored_due_to_verification_policies",
+      "min_level": 2
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_indirect_reference"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_likely_id_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_lock_file"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_not_alphanumeric_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_potential_uuid"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_prefixed_with_dollar_sign"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_sequential_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_swagger_file"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_templated_secret"
+    }
+  ],
+  "results": {},
+  "generated_at": "2026-04-13T21:29:03Z"
+}

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-04-13
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Konstantin Gredeskoul
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,360 @@
+# inquirex-ui
+
+Widget rendering hints for [Inquirex](https://github.com/flowengine-rb/inquirex) flow
+definitions.
+
+`inquirex-ui` enriches an Inquirex `Definition` with **framework-agnostic rendering
+metadata** — the `widget` DSL verb attaches a `WidgetHint` to each step node for each
+rendering target (`:desktop`, `:mobile`, `:tty`, …), describing the preferred UI control.
+Frontend adapters
+(`inquirex-tty`, `inquirex-js`, `inquirex-rails`) consume these hints to pick the right
+renderer. This gem produces enriched JSON — **no HTML or JavaScript is generated here**.
+
+## Installation
+
+```ruby
+gem "inquirex-ui"
+```
+
+`inquirex-ui` depends only on `inquirex` (the core gem). Both have zero required
+runtime dependencies beyond Ruby itself.
+
+## `Inquirex.define` vs `Inquirex::UI.define`
+
+The two entry points share the same DSL — the only difference is whether nodes carry
+widget hints:
+
+| | Entry point | Node class | `widget` verb |
+|---|---|---|---|
+| **`inquirex`** | `Inquirex.define` | `Inquirex::Node` | not available |
+| **`inquirex-ui`** | `Inquirex::UI.define` | `Inquirex::UI::Node` | available |
+
+Both return an `Inquirex::Definition` that works identically with `Inquirex::Engine`,
+`to_json`/`from_json`, `MermaidExporter`, etc. `inquirex-ui` is a strict superset —
+everything you can write in `Inquirex.define` works unchanged inside
+`Inquirex::UI.define`.
+
+**Use `Inquirex.define`** when you only need the flow logic: server-side processing,
+pure Ruby scripts, tests that don't care about rendering.
+
+**Use `Inquirex::UI.define`** when the definition will be consumed by a frontend adapter
+(`inquirex-tty`, `inquirex-js`, Rails views) that needs to know *how* to render each
+question.
+
+## Quick Start
+
+```ruby
+require "inquirex/ui"
+
+definition = Inquirex::UI.define id: "tax-intake", version: "1.0.0" do
+  meta title: "Tax Preparation Intake"
+
+  start :filing_status
+
+  ask :filing_status do
+    type :enum
+    question "What is your filing status?"
+    options single:             "Single",
+            married_jointly:    "Married Filing Jointly",
+            married_separately: "Married Filing Separately",
+            head_of_household:  "Head of Household"
+    widget target: :desktop, type: :radio_group, columns: 2
+    widget target: :mobile,  type: :dropdown
+    widget target: :tty,     type: :select
+    transition to: :income
+  end
+
+  ask :income do
+    type :currency
+    question "Estimated annual income?"
+    # No widget call — WidgetRegistry provides :currency_input by default
+    transition to: :has_deductions
+  end
+
+  confirm :has_deductions do
+    question "Any deductions to claim?"
+    # WidgetRegistry default: :toggle (desktop) / :yes_no_buttons (mobile)
+    transition to: :deductions, if_rule: equals(:has_deductions, true)
+    transition to: :done
+  end
+
+  ask :deductions do
+    type :multi_enum
+    question "Select applicable deductions."
+    options %w[Mortgage Charitable Medical]
+    widget target: :desktop, type: :checkbox_group, layout: :vertical
+    widget target: :tty,     type: :multi_select
+    transition to: :done
+  end
+
+  say :done do
+    text "Thank you for completing the intake."
+  end
+end
+```
+
+The definition object is a standard `Inquirex::Definition` — fully compatible with
+`Inquirex::Engine`, `to_json`/`from_json`, and `Inquirex::Graph::MermaidExporter`.
+Every step is an `Inquirex::UI::Node` (a subclass of `Inquirex::Node`) with widget hints
+attached.
+
+______________________________________________________________________
+
+## The `widget` DSL Verb
+
+`widget` is available inside any step block when using `Inquirex::UI.define`. Call it
+once per target context. The `target:` keyword defaults to `:desktop`, and the design
+is open-ended — any adapter may introduce its own targets (`:watch`, `:tv`, `:embed`, …).
+
+```ruby
+ask :priority do
+  type :enum
+  question "How urgent is this?"
+  options low: "Low", medium: "Medium", high: "High"
+
+  widget target: :desktop, type: :radio_group, columns: 3
+  widget target: :mobile,  type: :dropdown
+  widget target: :tty,     type: :select
+
+  transition to: :next_step
+end
+```
+
+`type:` names the widget. All remaining keyword arguments become the hint's `options`
+hash and are passed through to the adapter unchanged.
+
+`target:` can be any symbol. The three built-in targets are `:desktop`, `:mobile`, and
+`:tty`. Additional targets (`:watch`, `:embed`, …) are valid — adapters can define their
+own without any changes to this gem.
+
+### Widget DSL Method
+
+| Signature | Purpose |
+|-----------|---------|
+| `widget(target: :desktop, type:, **opts)` | Set rendering hint for the given target |
+
+`target:` defaults to `:desktop` — you can omit it when only a single hint is needed:
+
+```ruby
+widget type: :text_input, placeholder: "e.g. Alice"
+```
+
+When no `widget` call is made for a target, `WidgetRegistry` fills in the default for
+that data type. Adapters may also call `#effective_widget_hint_for(target:)` on any node
+to get the explicit hint or the registry fallback in one call.
+
+______________________________________________________________________
+
+## Widget Registry (Auto-Defaults)
+
+When no explicit `widget` call is made, `WidgetRegistry` provides a sensible default per
+data type and rendering context:
+
+| Data Type | `:desktop` default | `:mobile` default | `:tty` default |
+|-----------|-------------------|------------------|----------------|
+| `:string` | `text_input` | `text_input` | `text_input` |
+| `:text` | `textarea` | `textarea` | `multiline` |
+| `:integer` | `number_input` | `number_input` | `number_input` |
+| `:decimal` | `number_input` | `number_input` | `number_input` |
+| `:currency` | `currency_input` | `currency_input` | `number_input` |
+| `:boolean` | `toggle` | `yes_no_buttons` | `yes_no` |
+| `:enum` | `radio_group` | `dropdown` | `select` |
+| `:multi_enum` | `checkbox_group` | `checkbox_group` | `multi_select` |
+| `:date` | `date_picker` | `date_picker` | `text_input` |
+| `:email` | `email_input` | `email_input` | `text_input` |
+| `:phone` | `phone_input` | `phone_input` | `text_input` |
+
+Display steps (`say`, `header`, `btw`, `warning`) have no type, so they return `nil`
+widget hints by default.
+
+### All Recognized Widget Types
+
+**Web / graphical (desktop + mobile):**
+
+```
+text_input         textarea            number_input
+currency_input     toggle              yes_no_buttons
+radio_group        dropdown            checkbox_group
+multi_select_dropdown  date_picker     email_input
+phone_input
+```
+
+**TTY — maps to [tty-prompt](https://github.com/piotrmurach/tty-prompt) methods:**
+
+| Widget type | tty-prompt method | Notes |
+|-------------|-------------------|-------|
+| `text_input` | `prompt.ask` | Single-line text |
+| `multiline` | `prompt.multiline` | Multi-line text (`:text` type) |
+| `number_input` | `prompt.ask` | With numeric conversion |
+| `yes_no` | `prompt.yes?` | Boolean gate |
+| `select` | `prompt.select` | Single choice from list |
+| `multi_select` | `prompt.multi_select` | Multiple choices from list |
+| `enum_select` | `prompt.enum_select` | Numbered menu |
+| `mask` | `prompt.mask` | Hidden/password input |
+| `slider` | `prompt.slider` | Numeric range slider |
+
+Adapters are not required to support every widget type and should fall back gracefully
+(e.g. `radio_group` → `dropdown` in a TTY context).
+
+______________________________________________________________________
+
+## `WidgetHint`
+
+`WidgetHint` is an immutable `Data` class (`Data.define`) that pairs a widget type with
+an options hash:
+
+```ruby
+hint = Inquirex::UI::WidgetHint.new(type: :radio_group, options: { columns: 2 })
+
+hint.type     # => :radio_group
+hint.options  # => { columns: 2 }
+hint.to_h     # => { "type" => "radio_group", "columns" => 2 }
+
+Inquirex::UI::WidgetHint.from_h({ "type" => "radio_group", "columns" => 2 })
+# => #<data Inquirex::UI::WidgetHint type=:radio_group, options={columns: 2}>
+```
+
+The options hash is merged inline with `"type"` in the serialized form — no extra nesting.
+
+______________________________________________________________________
+
+## `UI::Node`
+
+`Inquirex::UI::Node` extends `Inquirex::Node` with a `widget_hints` hash and two
+accessor methods:
+
+| Attribute / Method | Returns | Description |
+|--------------------|---------|-------------|
+| `widget_hints` | `Hash{Symbol => WidgetHint}?` | All explicit hints keyed by target, or `nil` for display nodes |
+| `widget_hint_for(target:)` | `WidgetHint?` | Explicit hint for the given target, or `nil` |
+| `effective_widget_hint_for(target:)` | `WidgetHint?` | Explicit hint or registry default for the given target |
+
+```ruby
+step = definition.step(:filing_status)
+
+step.widget_hints
+# => { desktop: #<WidgetHint type=:radio_group, options={columns: 2}>,
+#      mobile:  #<WidgetHint type=:dropdown, options={}> }
+
+step.widget_hint_for(target: :desktop)
+# => #<data WidgetHint type=:radio_group, options={columns: 2}>
+
+step.effective_widget_hint_for(target: :mobile)
+# => #<data WidgetHint type=:dropdown, options={}>
+```
+
+Collecting steps produced by `Inquirex::UI.define` always return a non-nil value from
+`effective_widget_hint_for` (registry fills in the gap). Display steps (`say`, `header`,
+`btw`, `warning`) return `nil`.
+
+______________________________________________________________________
+
+## JSON Serialization
+
+Widget hints round-trip through JSON:
+
+```ruby
+definition.to_json
+# => '{"id":"tax-intake","start":"filing_status","steps":{"filing_status":{"verb":"ask",
+#      "type":"enum","question":"What is your filing status?","options":[...],"transitions":[...],
+#      "widget":{"desktop":{"type":"radio_group","columns":2},"mobile":{"type":"dropdown"},
+#               "tty":{"type":"select"}}},...}}'
+```
+
+### Wire Format for a Step with Hints
+
+```json
+{
+  "verb": "ask",
+  "type": "enum",
+  "question": "What is your filing status?",
+  "options": [
+    { "value": "single", "label": "Single" },
+    { "value": "married_jointly", "label": "Married Filing Jointly" }
+  ],
+  "transitions": [{ "to": "income" }],
+  "widget": {
+    "desktop": { "type": "radio_group", "columns": 2 },
+    "mobile":  { "type": "dropdown" },
+    "tty":     { "type": "select" }
+  }
+}
+```
+
+There is a single `"widget"` key whose value is an object keyed by target name. New
+targets can be added without changing the schema. Display steps (`say`, `header`, `btw`,
+`warning`) carry no `"widget"` key at all.
+
+### Deserializing UI Nodes
+
+`Inquirex::Definition.from_json` restores the base `Inquirex::Node` class by default
+(the core gem has no knowledge of `inquirex-ui`). To restore `UI::Node` instances:
+
+```ruby
+json = definition.to_json
+step_hash = JSON.parse(json)["steps"]["filing_status"]
+
+restored = Inquirex::UI::Node.from_h(:filing_status, step_hash)
+restored.widget_hints.type  # => :radio_group
+```
+
+______________________________________________________________________
+
+## Engine Compatibility
+
+`Inquirex::UI.define` returns a standard `Inquirex::Definition`. It works unchanged with
+`Inquirex::Engine`:
+
+```ruby
+engine = Inquirex::Engine.new(definition)
+engine.answer("single")        # :filing_status → :income
+engine.answer(75_000.00)       # :income → :has_deductions
+engine.answer(true)            # :has_deductions → :deductions
+engine.answer(%w[Mortgage])    # :deductions → :done
+engine.advance                 # past :done
+engine.finished?               # => true
+engine.answers
+# => { filing_status: "single", income: 75000.0, has_deductions: true, deductions: ["Mortgage"] }
+```
+
+______________________________________________________________________
+
+## For Adapter Authors
+
+If you are building an adapter (TTY terminal, JS widget, Rails views):
+
+1. Parse the flow JSON to get step definitions.
+1. For each collecting step, read `step["widget"]` — it is an object keyed by target name.
+1. Look up your target (e.g. `step["widget"]["tty"]`). The `"type"` key names the widget; additional keys are options.
+1. If `"widget"` is absent, call `WidgetRegistry.default_hint_for(type)` (Ruby) or
+   implement the same lookup table in your target language.
+1. Fall back gracefully — not every adapter supports every widget type.
+
+```ruby
+# Example adapter lookup
+def widget_for(step_hash, target: :desktop)
+  widget_map = step_hash["widget"]
+  raw = widget_map&.fetch(target.to_s, nil) || widget_map&.fetch("desktop", nil)
+  return Inquirex::UI::WidgetRegistry.default_hint_for(step_hash["type"], context: target) unless raw
+
+  Inquirex::UI::WidgetHint.from_h(raw)
+end
+```
+
+______________________________________________________________________
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec                       # run specs (90 examples)
+bundle exec rspec --format documentation
+bundle exec rubocop                     # lint
+```
+
+The core `inquirex` gem is loaded from a relative path (`../inquirex`) in development.
+See `Gemfile` for details.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).