nitro_kit 0.9.0 → 2.0.0.alpha.2

data/app/javascript/controllers/nk/tabs_controller.js

@@ -2,45 +2,157 @@ import { Controller } from "@hotwired/stimulus";
 
 export default class extends Controller {
   static targets = ["tab", "panel"];
-  static values = { active: String };
+  static values = {
+    active: String,
+    activation: { type: String, default: "automatic" },
+    orientation: { type: String, default: "horizontal" },
+  };
 
-  setActiveTab(event) {
-    this.activeValue = event.params.key;
+  connect() {
+    this.enhanced = true;
+    this.element.dataset.enhanced = "true";
+    this.synchronize();
   }
 
-  prevTab(event) {
-    const prevTab = event.target.previousElementSibling;
-    if (prevTab) {
-      prevTab.click();
-      prevTab.focus();
+  disconnect() {
+    this.enhanced = false;
+    this.reconcileScheduled = false;
+    delete this.element.dataset.enhanced;
+
+    this.element
+      .querySelectorAll(':scope > [data-slot="tabs-panel"]')
+      .forEach((panel) => {
+        panel.hidden = false;
+        panel.removeAttribute("aria-hidden");
+        panel.removeAttribute("tabindex");
+      });
+
+    this.element
+      .querySelectorAll(
+        ':scope > [data-slot="tabs-list"] > [data-slot="tabs-tab"]',
+      )
+      .forEach((tab) => {
+        tab.tabIndex = tab.disabled ? -1 : 0;
+      });
+  }
+
+  select(event) {
+    if (!event.currentTarget.disabled) {
+      this.activeValue = event.currentTarget.dataset.key;
     }
   }
 
-  nextTab(event) {
-    const nextTab = event.target.nextElementSibling;
-    if (nextTab) {
-      nextTab.click();
-      nextTab.focus();
+  navigate(event) {
+    const directionKeys =
+      this.orientationValue === "vertical"
+        ? ["ArrowUp", "ArrowDown"]
+        : ["ArrowLeft", "ArrowRight"];
+
+    if (![...directionKeys, "Home", "End"].includes(event.key)) return;
+
+    event.preventDefault();
+
+    const enabledTabs = this.tabTargets.filter((tab) => !tab.disabled);
+    const currentIndex = enabledTabs.indexOf(event.currentTarget);
+
+    if (currentIndex === -1) return;
+
+    let nextIndex;
+
+    if (event.key === "Home") {
+      nextIndex = 0;
+    } else if (event.key === "End") {
+      nextIndex = enabledTabs.length - 1;
+    } else {
+      const offset = event.key === directionKeys[0] ? -1 : 1;
+      nextIndex =
+        (currentIndex + offset + enabledTabs.length) % enabledTabs.length;
     }
+
+    const nextTab = enabledTabs[nextIndex];
+
+    if (this.activationValue === "automatic") {
+      this.activeValue = nextTab.dataset.key;
+    } else {
+      this.tabTargets.forEach((tab) => {
+        tab.tabIndex = -1;
+      });
+      nextTab.tabIndex = 0;
+    }
+
+    nextTab.focus();
   }
 
   activeValueChanged() {
+    if (!this.enhanced) return;
+
+    this.synchronize();
+  }
+
+  panelTargetConnected() {
+    if (this.enhanced) this.synchronize();
+  }
+
+  panelTargetDisconnected() {
+    this.scheduleReconciliation();
+  }
+
+  tabTargetConnected() {
+    if (this.enhanced) this.synchronize();
+  }
+
+  tabTargetDisconnected() {
+    this.scheduleReconciliation();
+  }
+
+  scheduleReconciliation() {
+    if (!this.enhanced || this.reconcileScheduled) return;
+
+    this.reconcileScheduled = true;
+    queueMicrotask(() => {
+      this.reconcileScheduled = false;
+      if (this.enhanced) this.reconcileTargets();
+    });
+  }
+
+  reconcileTargets() {
+    const active = this.activeValue;
+    const hasActivePair =
+      this.tabTargets.some((tab) => tab.dataset.key === active) &&
+      this.panelTargets.some((panel) => panel.dataset.key === active);
+
+    if (!hasActivePair) {
+      const fallback = this.tabTargets.find(
+        (tab) =>
+          !tab.disabled &&
+          this.panelTargets.some(
+            (panel) => panel.dataset.key === tab.dataset.key,
+          ),
+      );
+      if (fallback) this.activeValue = fallback.dataset.key;
+    }
+
+    this.synchronize();
+  }
+
+  synchronize() {
     const value = this.activeValue;
 
     this.panelTargets.forEach((panel) => {
-      if (panel.dataset.key === value) {
-        panel.ariaHidden = false;
-      } else {
-        panel.ariaHidden = true;
-      }
+      const active = panel.dataset.key === value;
+
+      panel.hidden = !active;
+      panel.setAttribute("aria-hidden", String(!active));
+      panel.dataset.state = active ? "active" : "inactive";
+      panel.tabIndex = active ? 0 : -1;
     });
 
     this.tabTargets.forEach((tab) => {
-      if (tab.dataset.key === value) {
-        tab.ariaSelected = true;
-      } else {
-        tab.ariaSelected = false;
-      }
+      const active = tab.dataset.key === value;
+
+      tab.setAttribute("aria-selected", String(active));
+      tab.dataset.state = active ? "active" : "inactive";
+      tab.tabIndex = active && !tab.disabled ? 0 : -1;
     });
   }
 }

data/app/javascript/controllers/nk/toast_controller.js

@@ -1,70 +1,137 @@
 import { Controller } from "@hotwired/stimulus";
 
 export default class extends Controller {
-  static targets = ["list", "template", "sink"];
-  static values = {
-    duration: { type: Number, default: 5000 },
-  };
-
-  connect() {
-    if (this.hasSinkTarget) {
-      this.mutationObserver = new MutationObserver(([event]) => {
-        if (event.addedNodes.length === 0) return;
-        this.#flushSink();
-      });
-      this.mutationObserver.observe(this.sinkTarget, { childList: true });
-    }
-
-    this.#flushSink();
-  }
+  static targets = ["item"];
+  static values = { duration: Number };
 
   disconnect() {
-    if (this.mutationObserver) this.mutationObserver.disconnect();
+    this.teardown();
+  }
+
+  teardown() {
+    this.timers?.forEach((timers) => {
+      window.clearTimeout(timers.dismiss);
+      window.clearTimeout(timers.remove);
+    });
+    this.timers?.clear();
+
+    this.itemTargets
+      .filter((item) => item.dataset.state === "closed")
+      .forEach((item) => item.remove());
   }
 
-  toast({ params }) {
-    const { title, description } = params;
-    const item = this.templateTarget.content.cloneNode(true);
+  itemTargetConnected(item) {
+    this.schedule(item);
+  }
+
+  itemTargetDisconnected(item) {
+    this.clear(item);
+  }
+
+  dismiss(event) {
+    const item = event.currentTarget.closest('[data-nk="toast-item"]');
+    if (item) this.close(item);
+  }
 
-    item.querySelector("[data-slot=title]").textContent = title;
-    item.querySelector("[data-slot=description]").textContent = description;
+  pause(event) {
+    const item = event.currentTarget;
+    const timers = this.timerMap.get(item);
+    if (!timers?.dismiss) return;
 
-    this.show(item);
+    window.clearTimeout(timers.dismiss);
+    timers.dismiss = null;
+    timers.remaining = Math.max(0, timers.deadline - Date.now());
   }
 
-  show(item) {
-    this.clear();
-    this.listTarget.appendChild(item);
+  resume(event) {
+    const item = event.currentTarget;
+    if (item.contains(event.relatedTarget)) return;
+    if (item.matches(":hover, :focus-within")) return;
+    if (item.dataset.state !== "open") return;
 
-    requestAnimationFrame(() => {
-      this.listTarget.children[0].dataset.state = "open";
+    const remaining = this.timerMap.get(item)?.remaining ?? this.durationValue;
+    this.schedule(item, remaining);
+  }
+
+  remove(event) {
+    if (event.target !== event.currentTarget) return;
+    if (event.currentTarget.dataset.state !== "closed") return;
+
+    this.removeItem(event.currentTarget);
+  }
+
+  schedule(item, delay = this.durationValue) {
+    this.clear(item);
+    if (item.dataset.state !== "open") return;
+    if (item.hasAttribute("data-nk--toast-permanent")) return;
+
+    const dismiss = window.setTimeout(() => this.close(item), delay);
+    this.timerMap.set(item, {
+      dismiss,
+      remove: null,
+      deadline: Date.now() + delay,
+      remaining: delay,
     });
+  }
 
-    if (this.timer) clearTimeout(this.timer);
+  close(item) {
+    if (!item.isConnected || item.dataset.state === "closed") return;
+
+    this.clear(item);
+    item.dataset.state = "closed";
+
+    const remove = window.setTimeout(
+      () => this.removeItem(item),
+      this.removalDelay(item),
+    );
+    this.timerMap.set(item, {
+      dismiss: null,
+      remove,
+      deadline: null,
+      remaining: null,
+    });
+  }
 
-    this.timer = setTimeout(() => {
-      this.hide();
-    }, this.durationValue);
+  removeItem(item) {
+    this.clear(item);
+    item.remove();
   }
 
-  hide() {
-    this.listTarget.children[0].dataset.state = "closed";
+  clear(item) {
+    const timers = this.timerMap.get(item);
+    if (!timers) return;
 
-    setTimeout(() => {
-      this.clear();
-    }, 250);
+    window.clearTimeout(timers.dismiss);
+    window.clearTimeout(timers.remove);
+    this.timerMap.delete(item);
   }
 
-  clear() {
-    this.listTarget.innerHTML = "";
+  removalDelay(item) {
+    const style = getComputedStyle(item);
+    const durations = style.transitionDuration
+      .split(",")
+      .map((value) => this.timeInMilliseconds(value));
+    const delays = style.transitionDelay
+      .split(",")
+      .map((value) => this.timeInMilliseconds(value));
+
+    return (
+      Math.max(
+        ...durations.map(
+          (duration, index) => duration + delays[index % delays.length],
+        ),
+        0,
+      ) + 50
+    );
   }
 
-  #flushSink() {
-    if (!this.hasSinkTarget) return;
+  timeInMilliseconds(value) {
+    const time = Number.parseFloat(value) || 0;
+    return value.trim().endsWith("ms") ? time : time * 1000;
+  }
 
-    for (const li of this.sinkTarget.children) {
-      this.show(li.cloneNode(true));
-      li.remove();
-    }
+  get timerMap() {
+    this.timers ||= new Map();
+    return this.timers;
   }
 }

data/app/javascript/controllers/nk/tooltip_controller.js

@@ -1,59 +1,24 @@
 import { Controller } from "@hotwired/stimulus";
-import {
-  computePosition,
-  offset,
-  flip,
-  shift,
-  autoUpdate,
-} from "@floating-ui/dom";
 
 export default class extends Controller {
-  static targets = ["content"];
-  static values = {
-    open: { type: Boolean, default: false },
-    // Options for floating-ui
-    placement: { type: String, default: "top" },
-  };
-
-  connect() {
-    this.updatePosition();
-  }
-
   disconnect() {
-    this.close();
+    this.reset();
   }
 
-  open() {
-    this.openValue = true;
+  dismiss(event) {
+    event.preventDefault();
+    this.element.dataset.dismissed = "";
   }
 
-  close() {
-    this.openValue = false;
-  }
-
-  openValueChanged(state, _previous) {
-    this.contentTarget.dataset.state = state ? "open" : "closed";
+  resetIfUninterested(event) {
+    if (event.relatedTarget && this.element.contains(event.relatedTarget))
+      return;
+    if (this.element.matches(":hover, :focus-within")) return;
 
-    if (state) {
-      this.clearAutoUpdate = autoUpdate(
-        this.element,
-        this.contentTarget,
-        this.updatePosition,
-      );
-    } else {
-      if (this.clearAutoUpdate) {
-        this.clearAutoUpdate();
-      }
-    }
+    this.reset();
   }
 
-  updatePosition = () => {
-    computePosition(this.element, this.contentTarget, {
-      placement: this.placementValue,
-      middleware: [offset(5), flip(), shift({ padding: 5 })],
-    }).then(({ x, y }) => {
-      this.contentTarget.style.left = `${x}px`;
-      this.contentTarget.style.top = `${y}px`;
-    });
-  };
+  reset() {
+    delete this.element.dataset.dismissed;
+  }
 }

data/config/importmap.rb

@@ -0,0 +1,2 @@
+pin "@rails/activestorage", to: "activestorage.esm.js"
+pin_all_from File.expand_path("../app/javascript/controllers", __dir__), under: "controllers"

data/config/locales/en.yml

@@ -0,0 +1,98 @@
+en:
+  nitro_kit:
+    app_shell:
+      skip_link: "Skip to content"
+      open_navigation: "Open navigation"
+      close_navigation: "Close navigation"
+      navigation_dialog: "Application navigation"
+    appearance_picker:
+      label: "Appearance"
+      preferences:
+        light: "Light"
+        dark: "Dark"
+        system: "System"
+    avatar_stack:
+      overflow: "%{count} more avatars"
+    combobox:
+      invalid_selection: "Choose an option."
+      no_results: "No options found."
+      results:
+        one: "%{count} option available."
+        other: "%{count} options available."
+    command_palette:
+      label: "Search"
+      placeholder: "Search destinations…"
+      empty: "No destinations found."
+      close: "Close search"
+      shortcut: "⌘K"
+      results:
+        one: "%{count} destination available."
+        other: "%{count} destinations available."
+    details_table:
+      empty: "Not provided"
+      boolean_true: "Yes"
+      boolean_false: "No"
+    dialog:
+      close: "Close dialog"
+    dropzone:
+      label: "Upload files"
+      prompt: "Drop files here or choose them from your device."
+      preview_list: "Selected files"
+      progress: "Upload progress"
+      progress_for: "Upload progress for %{name}"
+      remove: "Remove"
+      remove_file: "Remove %{name}"
+      queued: "Queued"
+      uploading: "Uploading"
+      uploading_percent: "Uploading %{percent}%"
+      uploaded: "Uploaded"
+      upload_failed: "Upload failed"
+      ready: "Ready to submit"
+      status:
+        disabled: "File upload is disabled."
+        empty: "No files selected."
+        selected:
+          one: "%{count} file selected."
+          other: "%{count} files selected."
+        uploading:
+          one: "Uploading %{count} file."
+          other: "Uploading %{count} files."
+        attention:
+          one: "%{count} file needs attention."
+          other: "%{count} files need attention."
+        uploaded:
+          one: "%{count} file uploaded."
+          other: "%{count} files uploaded."
+        ready:
+          one: "%{count} file ready to submit."
+          other: "%{count} files ready to submit."
+      errors:
+        upload_failed: "%{name} could not be uploaded."
+        upload_failed_detail: "%{name} could not be uploaded: %{error}"
+        uploads_in_progress: "Wait for uploads to finish before submitting the form."
+        failed_files: "Remove failed files or choose them again before submitting the form."
+        too_large: "%{name} is larger than %{size}."
+        not_accepted: "%{name} is not an accepted file type."
+        max_files:
+          one: "Choose no more than %{count} file."
+          other: "Choose no more than %{count} files."
+    field:
+      options_legend: "Options"
+    form:
+      submit: "Save changes"
+    pagination:
+      label: "Pagination"
+      previous: "Previous"
+      next: "Next"
+      previous_page: "Previous page"
+      next_page: "Next page"
+      ellipsis: "More pages"
+    progressive_image:
+      unavailable: "Image unavailable"
+    sheet:
+      close: "Close panel"
+    tabs:
+      label: "Tabs"
+    toast:
+      label: "Notifications"
+      dismiss: "Dismiss notification"

data/docs/agent_guide.md

@@ -0,0 +1,139 @@
+# Building applications with Nitro Kit
+
+This is the routing guide for coding agents working in a Rails application that uses Nitro Kit. It describes how to find the installed contract, select components, and apply the same Rails and Hotwire conventions across features.
+
+## Start from the installed version
+
+From the application root, run:
+
+```sh
+bundle show nitro_kit
+```
+
+Read this guide from that directory, then consult only the reference needed for the task:
+
+| Task                                        | Read next                                 |
+| ------------------------------------------- | ----------------------------------------- |
+| Rails models, routes, CRUD, and tests       | `docs/rails_conventions.md`               |
+| Authentication, teams, shell, and settings  | `docs/patterns/application_foundation.md` |
+| Build a complete product resource           | `docs/patterns/crud_resource.md`          |
+| Choose or compose UI                        | `docs/component_contracts.md`             |
+| Rails assets, forms, and application shells | `docs/rails_integration.md`               |
+| Turbo, Frames, Streams, morphs, or Stimulus | `docs/hotwire.md`                         |
+| Theme tokens and application composition    | `docs/customization.md`                   |
+| Upgrade an existing Nitro Kit 1.x app        | `docs/migration_1_to_2.md`                |
+| Query, sort, filter, or paginate            | `docs/patterns/queryable_collection.md`   |
+| Create, update, and show validation         | `docs/patterns/resource_form.md`          |
+| Delete, revoke, archive, or confirm         | `docs/patterns/destructive_action.md`     |
+| Flash messages and notifications            | `docs/patterns/flash_and_toast.md`        |
+| Edit and cancel inside a page               | `docs/patterns/inline_edit.md`            |
+
+The installed component source is the final authority for constructor and compound-method details. This guide describes Nitro Kit 2.x. Do not use an API remembered from Nitro Kit 1.x or another installed version.
+
+## Select the highest-level matching component
+
+Prefer the component that owns the whole region, then compose smaller components inside it.
+
+| Product need                     | Begin with                                                |
+| -------------------------------- | --------------------------------------------------------- |
+| Application chrome               | `AppShell`, `AppNavigation`, `CommandPalette`             |
+| Authentication page              | `AuthShell`                                               |
+| Settings navigation              | `SettingsLayout`                                          |
+| Team or account administration   | `AppShell`, `Toolbar`, `Table`, `FormSection`             |
+| App page title and basic actions | `AppShell`, then `Toolbar`                                |
+| Content-led page introduction    | `PageHeader`                                              |
+| Data region                      | `DataSection`, then `Table` or `EmptyState`               |
+| Queryable tabular data           | `Table`, `Toolbar`, `PaginationBar`                       |
+| Model-backed form                | `FormSection`, Rails `form_with`, `NitroKit::FormBuilder` |
+| Destructive settings             | `DangerZone`, optionally `Dialog`                         |
+| Transient server feedback        | `Toast::FlashMessages`                                    |
+| Rendered Markdown or rich text   | `Container`, then `Typeset`                               |
+| General grouping                 | `Card`, `Flex`, `Grid`, `Container`                       |
+
+Application-specific product UI belongs under the application's namespace and composes Nitro components. Nitro owns component markup, styles, accessibility structure, and narrowly scoped progressive behavior. The application owns product policy, records, routes, authorization, queries, DOM IDs, and server responses.
+
+For admin CRUD, treat the starter and entitled flows as complete compositions:
+use toolbar Back links on child routes, keep deletion on edit, keep status in
+the details flow, implement full invitation and membership management, and use
+native links for settings destinations. Do not stop after rendering a screen
+that only looks structurally similar.
+
+## Preserve controls during migration
+
+Before changing a 1.x application, read `docs/migration_1_to_2.md`. Inventory
+user-facing flows and behavior before mapping helpers. When the Nitro Kit MCP
+catalog is available, search by product workflow rather than old component
+name, then prefer the highest-level matching composition before replacing
+atoms.
+
+After establishing that inventory, generate the host integration smoke tests
+from the currently bundled gem with `bin/rails generate
+nitro_kit:upgrade_smoke_tests`. The generator preserves existing files and
+skips missing Rails Minitest or system-test infrastructure with setup guidance.
+Run supported generated tests before and after the application conversion,
+while retaining application-specific acceptance coverage for every inventoried
+flow. Customize each generated `prepare_nitro_kit_upgrade_smoke_test` method
+with host sign-in and account-selection helpers when `ApplicationController`
+requires them; do not disable the host callbacks.
+
+In an existing application, replace a form control only when the installed
+Nitro Kit catalog provides a genuine semantic and behavioral equivalent.
+Preserve its parameter name, IDs, values, errors, accessibility, uploads, and
+browser behavior. If no equivalent exists, keep or re-express the control as
+application-owned Rails and semantic HTML, optionally inside a custom
+`form.field` composition. Never downgrade an editor, autocomplete, date range,
+upload, or other specialized input to the nearest generic Nitro control merely
+for visual consistency.
+
+Do not retain copied Nitro Kit 1.x source as the fallback. Remove the legacy
+component and preserve the unsupported behavior in clearly application-owned
+code. Report the missing equivalent as a Nitro Kit coverage gap.
+
+## Use one interaction grammar
+
+Choose the smallest primitive that completes the interaction:
+
+1. Ordinary Rails links and forms under Turbo Drive.
+2. A Turbo Frame for one independently navigable or replaceable region.
+3. A request-scoped Turbo Stream response when one action changes multiple regions.
+4. A broadcast only when other sessions must receive the change.
+5. Application Stimulus only for browser-only behavior the preceding layers cannot express.
+
+Successful non-GET HTML submissions redirect with `303 See Other`. Invalid form submissions render the same invalid model with `422 Unprocessable Entity`. GET parameters remain the source of truth for queryable collections. Frame identifiers come from `dom_id` or one named constant shared by rendering, responses, and tests.
+
+## Stay inside the public boundary
+
+- Include `NitroKit` once in the application's base Phlex component and use
+  capitalized Kit methods such as `Button(...)` and `Card(...)`.
+- Use the scoped `NitroKit::Button(...)` form when inclusion is not appropriate.
+- Use an explicit constructor such as `Button.new(...)` only when another API
+  needs a component object; Kit methods render immediately.
+- Select `NitroKit::FormBuilder` explicitly from Rails `form_with`.
+- Put a standalone form's visible fields, submit control, and related links
+  inside `form.group`; hidden fields may remain before the group.
+- Parents own rhythm. Wrap stacked fields in `FieldGroup` — as
+  `render NitroKit::FieldGroup.new { ... }`, or `form.group` inside a
+  `form_with` block. Two Fields, or a Field and its submit Button, rendered as
+  bare siblings of a `form` or a plain `div` have no gap between them at all.
+  Use `Flex` or `Grid` instead only when the arrangement is deliberately
+  inline or multi-column.
+- Use component options, compound declarations, layouts, and documented `--nk-*` theme properties.
+- Keep an HTML fallback for every Turbo form flow.
+- Test semantic output and stable owned attributes.
+
+Do not copy component source, add `nk_*` helpers, invent a general ERB bridge, mutate Nitro-owned Stimulus controllers, or pass `class:` and `style:`. The intentionally loud `desperately_need_a_class:` escape exists only for external integrations that require a class hook.
+
+## Application `AGENTS.md`
+
+Install the durable project instruction and local skills from the consuming
+application root:
+
+```sh
+bin/rails generate nitro_kit:install
+```
+
+The installer preserves application-owned content around a bounded Nitro Kit 2
+block in `AGENTS.md` and adds project-local Rails, Hotwire, and UI skills for
+supported agents. The skills deliberately resolve the installed gem first, so
+upgrading the gem upgrades the instructions they use. Re-run the generator
+after an upgrade; it never copies component or controller source.