stimeo-ui 0.1.0.pre.alpha.1

data/dist/positioning/index.js

@@ -0,0 +1,145 @@
+import { computePosition, autoUpdate, offset, flip, shift } from '@floating-ui/dom';
+import { Controller } from '@hotwired/stimulus';
+
+// src/positioning/index.ts
+var AnchoredController = class extends Controller {
+  static targets = ["anchor", "floating"];
+  static values = {
+    placement: { type: String, default: "bottom" },
+    offset: { type: Number, default: 0 },
+    flip: { type: Boolean, default: true },
+    shift: { type: Boolean, default: true },
+    padding: { type: Number, default: 0 },
+    strategy: { type: String, default: "absolute" },
+    active: { type: Boolean, default: true }
+  };
+  static events = ["position"];
+  /** `autoUpdate` cleanup while tracking; `null` when detached. */
+  #stop = null;
+  /** True between connect and disconnect (Stimulus may fire value callbacks before connect). */
+  #connected = false;
+  /** Serialized options of the live observer, or `null` when detached — see {@link #sync}. */
+  #appliedKey = null;
+  connect() {
+    this.#connected = true;
+    this.#sync();
+  }
+  disconnect() {
+    this.#connected = false;
+    this.#sync();
+  }
+  // Every value change (active or an option) re-syncs. `#sync` is idempotent and
+  // order-independent, so no Value has to be declared in a particular position.
+  activeValueChanged() {
+    this.#sync();
+  }
+  placementValueChanged() {
+    this.#sync();
+  }
+  offsetValueChanged() {
+    this.#sync();
+  }
+  flipValueChanged() {
+    this.#sync();
+  }
+  shiftValueChanged() {
+    this.#sync();
+  }
+  paddingValueChanged() {
+    this.#sync();
+  }
+  strategyValueChanged() {
+    this.#sync();
+  }
+  /** Current Values mapped to the positioning engine's options. */
+  get #options() {
+    return {
+      placement: this.placementValue,
+      offset: this.offsetValue,
+      flip: this.flipValue,
+      shift: this.shiftValue,
+      padding: this.paddingValue,
+      // Narrow the free-form Value to the engine's union; anything but "fixed"
+      // falls back to the default "absolute".
+      strategy: this.strategyValue === "fixed" ? "fixed" : "absolute"
+    };
+  }
+  /**
+   * Reconciles the live observer with the desired state — track iff connected,
+   * `active`, and both targets exist — re-attaching only when that state or the
+   * options actually changed. Stimulus fires the value-changed callbacks on
+   * connect in declaration order and may run them before or after `connect()`;
+   * keying on the applied options collapses that whole burst (in any order) to a
+   * single attach, while an option change at runtime re-attaches exactly once. So
+   * correctness never depends on `active` being declared last.
+   */
+  #sync() {
+    const shouldTrack = this.#connected && this.activeValue && this.hasAnchorTarget && this.hasFloatingTarget;
+    const key = shouldTrack ? JSON.stringify(this.#options) : null;
+    if (key === this.#appliedKey) return;
+    this.#detach();
+    this.#appliedKey = key;
+    if (shouldTrack) this.#attach();
+  }
+  #attach() {
+    this.#stop = attachPositioning(
+      this.anchorTarget,
+      this.floatingTarget,
+      this.#options,
+      (result) => this.#onComputed(result)
+    );
+  }
+  #detach() {
+    this.#stop?.();
+    this.#stop = null;
+  }
+  /** Reflects the resolved side onto the CSS hook and announces the placement. */
+  #onComputed(result) {
+    this.floatingTarget.setAttribute("data-anchored-placement", result.placement);
+    this.dispatch("position", {
+      detail: { placement: result.placement, x: result.x, y: result.y }
+    });
+  }
+};
+
+// src/positioning/index.ts
+function buildMiddleware(options) {
+  const padding = options.padding ?? 0;
+  const middleware = [];
+  if (options.offset) middleware.push(offset(options.offset));
+  if (options.flip !== false) middleware.push(flip({ padding }));
+  if (options.shift !== false) middleware.push(shift({ padding }));
+  return middleware;
+}
+async function position(anchor, floating, options = {}) {
+  const strategy = options.strategy ?? "absolute";
+  const config = {
+    placement: options.placement ?? "bottom",
+    middleware: buildMiddleware(options),
+    strategy
+  };
+  const { x, y, placement } = await computePosition(anchor, floating, config);
+  Object.assign(floating.style, {
+    position: strategy,
+    left: `${x}px`,
+    top: `${y}px`
+  });
+  return { x, y, placement };
+}
+function attachPositioning(anchor, floating, options = {}, onComputed) {
+  return autoUpdate(anchor, floating, () => {
+    void position(anchor, floating, options).then((result) => onComputed?.(result));
+  });
+}
+var positioningControllers = {
+  "stimeo--anchored": AnchoredController
+};
+function registerPositioning(application) {
+  for (const [identifier, controller] of Object.entries(positioningControllers)) {
+    application.register(identifier, controller);
+  }
+}
+
+export { AnchoredController, attachPositioning, position, positioningControllers, registerPositioning };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

data/lib/generators/stimeo/install/install_generator.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+require "rails/generators/base"
+require "stimeo/ui"
+
+module Stimeo
+  module Generators
+    # `bin/rails generate stimeo:install`
+    #
+    # Sets up an importmap-rails app to use Stimeo UI without npm:
+    #   1. vendors the gem's prebuilt JS into vendor/javascript/stimeo/
+    #   2. pins "stimeo-ui" in config/importmap.rb
+    #   3. registers every stimeo--* controller with the app's Stimulus
+    #      application (app/javascript/controllers/stimeo.js)
+    #
+    # Re-running is safe: the vendor copy is refreshed in place, while pins
+    # and imports are only appended when missing — so after a gem update you
+    # just run the generator again to pick up the new JS.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      VENDOR_DIR = "vendor/javascript/stimeo"
+
+      def copy_dist
+        source = Pathname.new(Stimeo::UI.dist_dir)
+        vendor = destination_pathname.join(VENDOR_DIR)
+        # Refresh: wipe the vendored copy first so files removed/renamed in a
+        # newer gem release don't linger here after re-running the generator.
+        FileUtils.rm_rf(vendor)
+        Dir[source.join("**/*.js").to_s].each do |file|
+          relative = Pathname.new(file).relative_path_from(source)
+          # The inspector CLI is a Node tool, not browser code — keep it out
+          # of the asset path (use the npm package for `stimeo check`).
+          next if relative.to_s.start_with?("inspector/")
+
+          target = vendor.join(relative)
+          FileUtils.mkdir_p(target.dirname)
+          FileUtils.cp(file, target)
+        end
+        say_status :vendor, "#{VENDOR_DIR} (prebuilt JS from the stimeo-ui gem)"
+      end
+
+      def pin_importmap
+        importmap = destination_pathname.join("config/importmap.rb")
+        unless importmap.exist?
+          say_status :skip, "config/importmap.rb not found — this generator targets " \
+                            "importmap-rails; with a JS bundler use `npm install stimeo-ui` " \
+                            "instead (see the README)", :yellow
+          return
+        end
+
+        if importmap.read.include?('pin "stimeo-ui"')
+          say_status :identical, "config/importmap.rb (stimeo-ui already pinned)", :blue
+        else
+          append_to_file "config/importmap.rb", <<~RUBY
+
+            # Stimeo UI (vendored by `rails g stimeo:install`)
+            pin "stimeo-ui", to: "stimeo/index.js"
+            # Opt-in positioning module — also pin @floating-ui/dom if you enable it:
+            # pin "stimeo-ui/positioning", to: "stimeo/positioning/index.js"
+          RUBY
+        end
+      end
+
+      def register_controllers
+        # Only create it the first time. The file is "safe to edit"; re-running
+        # the generator must not clobber a user's customised registration.
+        registration = destination_pathname.join("app/javascript/controllers/stimeo.js")
+        if registration.exist?
+          say_status :identical, "app/javascript/controllers/stimeo.js (kept your edits)", :blue
+        else
+          copy_file "stimeo.js", "app/javascript/controllers/stimeo.js"
+        end
+
+        index = destination_pathname.join("app/javascript/controllers/index.js")
+        if !index.exist?
+          say_status :action_required, 'add `import "controllers/stimeo"` wherever your ' \
+                                       "Stimulus application boots", :yellow
+        elsif index.read.include?("controllers/stimeo")
+          say_status :identical, "controllers/index.js (already imports controllers/stimeo)", :blue
+        else
+          append_to_file "app/javascript/controllers/index.js", <<~JS
+            import "controllers/stimeo"
+          JS
+        end
+      end
+
+      def show_next_steps
+        say <<~MSG
+
+          Stimeo UI is installed. Drive components from HTML alone, e.g.:
+
+            <div data-controller="stimeo--dropdown">
+              <button data-stimeo--dropdown-target="trigger"
+                      data-action="click->stimeo--dropdown#toggle">Menu</button>
+              <div data-stimeo--dropdown-target="menu" hidden>...</div>
+            </div>
+
+          Docs: https://github.com/taiyaky/stimeo-ui
+        MSG
+      end
+
+      private
+
+      # Generator actions (copy_file/append_to_file) already resolve against
+      # destination_root; this helper is for the direct file checks above.
+      def destination_pathname
+        Pathname.new(destination_root)
+      end
+    end
+  end
+end

data/lib/generators/stimeo/install/templates/stimeo.js

@@ -0,0 +1,12 @@
+// Registers every stimeo--* controller with the app's Stimulus application.
+// Generated by `rails g stimeo:install`. Safe to edit.
+//
+// To cherry-pick instead of registering all controllers, import them
+// individually from "stimeo-ui/controllers/<name>" and register under your own
+// identifiers. Note: with a JS bundler this works as-is; with importmap-rails
+// each "stimeo-ui/controllers/<name>" needs its own pin (this generator only
+// pins the "stimeo-ui" entrypoint), so add those pins to config/importmap.rb.
+import { application } from "controllers/application";
+import { registerStimeo } from "stimeo-ui";
+
+registerStimeo(application);

data/lib/stimeo/ui/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Stimeo
+  module UI
+    # Kept in lockstep with package.json: npm `0.1.0-alpha.1` ⇔ gem
+    # `0.1.0.pre.alpha.1` (RubyGems forbids dashes). Bump both together —
+    # see RELEASING.md for the synchronized release procedure.
+    VERSION = "0.1.0.pre.alpha.1"
+  end
+end

data/lib/stimeo/ui.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "ui/version"
+
+module Stimeo
+  # The stimeo-ui gem is distribution only: it bundles the prebuilt JS
+  # (dist/, identical to the npm package) and the `stimeo:install`
+  # generator that vendors it into a Rails app. All behavior lives in
+  # the JS; there is no Ruby runtime component.
+  module UI
+    # Gem root — inside the packaged gem, dist/ sits alongside lib/.
+    ROOT = File.expand_path("../..", __dir__)
+
+    # The prebuilt JS payload shipped inside the gem.
+    def self.dist_dir
+      File.join(ROOT, "dist")
+    end
+  end
+end

data/lib/stimeo-ui.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Entry point matching the gem name (`require "stimeo-ui"`).
+require_relative "stimeo/ui"

metadata

@@ -0,0 +1,152 @@
+--- !ruby/object:Gem::Specification
+name: stimeo-ui
+version: !ruby/object:Gem::Version
+  version: 0.1.0.pre.alpha.1
+platform: ruby
+authors:
+- Stimeo Labs
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-06-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+description: 'Behavior-only, accessible UI primitives for Rails: WAI-ARIA state, keyboard
+  interaction, focus management and Turbo resilience as data-attribute-driven Stimulus
+  controllers, with no CSS. Ships the prebuilt stimeo-ui JS and a `stimeo:install`
+  generator that vendors it into an importmap-rails app.'
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- dist/controllers/accordion_controller.js
+- dist/controllers/announcer_controller.js
+- dist/controllers/aspect_ratio_controller.js
+- dist/controllers/auto_submit_controller.js
+- dist/controllers/avatar_controller.js
+- dist/controllers/breadcrumb_controller.js
+- dist/controllers/bulk_select_controller.js
+- dist/controllers/calendar_controller.js
+- dist/controllers/character_counter_controller.js
+- dist/controllers/checkbox_controller.js
+- dist/controllers/combobox_controller.js
+- dist/controllers/command_palette_controller.js
+- dist/controllers/conditional_fields_controller.js
+- dist/controllers/confirm_controller.js
+- dist/controllers/context_menu_controller.js
+- dist/controllers/countdown_controller.js
+- dist/controllers/dialog_controller.js
+- dist/controllers/direct_upload_controller.js
+- dist/controllers/dirty_form_controller.js
+- dist/controllers/dropdown_controller.js
+- dist/controllers/empty_state_controller.js
+- dist/controllers/flash_controller.js
+- dist/controllers/focus_controller.js
+- dist/controllers/form_field_controller.js
+- dist/controllers/form_validation_controller.js
+- dist/controllers/frame_loading_controller.js
+- dist/controllers/highlight_controller.js
+- dist/controllers/hover_card_controller.js
+- dist/controllers/idle_controller.js
+- dist/controllers/input_mask_controller.js
+- dist/controllers/lazy_frame_controller.js
+- dist/controllers/listbox_controller.js
+- dist/controllers/local_time_controller.js
+- dist/controllers/menu_controller.js
+- dist/controllers/meter_controller.js
+- dist/controllers/nested_form_controller.js
+- dist/controllers/network_status_controller.js
+- dist/controllers/number_input_controller.js
+- dist/controllers/otp_controller.js
+- dist/controllers/overflow_indicator_controller.js
+- dist/controllers/overflow_menu_controller.js
+- dist/controllers/pagination_controller.js
+- dist/controllers/password_strength_controller.js
+- dist/controllers/persist_controller.js
+- dist/controllers/popover_controller.js
+- dist/controllers/portal_controller.js
+- dist/controllers/preview_guard_controller.js
+- dist/controllers/progress_controller.js
+- dist/controllers/radio_group_controller.js
+- dist/controllers/rating_controller.js
+- dist/controllers/relative_time_controller.js
+- dist/controllers/reset_before_cache_controller.js
+- dist/controllers/resizable_controller.js
+- dist/controllers/roving_controller.js
+- dist/controllers/scroll_area_controller.js
+- dist/controllers/scroll_visibility_controller.js
+- dist/controllers/scrollspy_controller.js
+- dist/controllers/skeleton_controller.js
+- dist/controllers/slider_controller.js
+- dist/controllers/spinner_controller.js
+- dist/controllers/step_indicator_controller.js
+- dist/controllers/stepper_controller.js
+- dist/controllers/stick_to_bottom_controller.js
+- dist/controllers/sticky_observer_controller.js
+- dist/controllers/submit_once_controller.js
+- dist/controllers/switch_controller.js
+- dist/controllers/tabs_controller.js
+- dist/controllers/textarea_autosize_controller.js
+- dist/controllers/theme_controller.js
+- dist/controllers/toast_controller.js
+- dist/controllers/toggle_group_controller.js
+- dist/controllers/toolbar_controller.js
+- dist/controllers/tooltip_controller.js
+- dist/controllers/transition_controller.js
+- dist/index.js
+- dist/positioning/index.js
+- lib/generators/stimeo/install/install_generator.rb
+- lib/generators/stimeo/install/templates/stimeo.js
+- lib/stimeo-ui.rb
+- lib/stimeo/ui.rb
+- lib/stimeo/ui/version.rb
+homepage: https://github.com/taiyaky/stimeo-ui
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/taiyaky/stimeo-ui
+  bug_tracker_uri: https://github.com/taiyaky/stimeo-ui/issues
+  changelog_uri: https://github.com/taiyaky/stimeo-ui/releases
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Headless Stimulus UI framework for Ruby on Rails.
+test_files: []