nitro_kit 2.0.0.alpha.2 → 2.0.0.alpha.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2cfb9e904d8890216a6c778b5dd10655e22f77fa7508fd4d9eb9521453b61cd8
-  data.tar.gz: 3c9564fa27b68e1a10c1febe8b7104416251a5203b1bd25aa89b1617cab1e116
+  metadata.gz: ac13933782cc8434035e1b9e27f836b19dfe96a0f98124b91f2a4d62a4222d7e
+  data.tar.gz: 3ac6f8709fba0d6b5bffdac9eca6f21db615408303284afbc7ef7dbb7809d8d4
 SHA512:
-  metadata.gz: de02c676e41ea2cb0d674de967efa9c73aa8d6f65195af0bfae0ce35e305dc9fb5e53979659e5feed738cf0fdc4e968902931be726a5d1bd67f22a400ce3c0b2
-  data.tar.gz: 2ffdd83fe0f4005c5146a3d9e4fa13e7ce8a6b6d84d0a7e881aace598a6ff938836b20c15f29bde5f9d72e9bed8ef2e4a6b8a083add6986a0acdacb653221a4e
+  metadata.gz: 3e7e6d588753fada85d9435dade70583da5322dab94a09a97c125f8847fcef74c99d8ed8654230d839babfb230cc589c73e8de8b60671665f90229a958b1705e
+  data.tar.gz: c13cc9b6315a6e5e17a34b1bcb9a7d1d8f624abbb3ffc53940a8c3f743c774efb6988dd8cddc36b45224afd44b41d0ccdbb57a0e5eacca07c4731b52cc21fa81

data/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## Unreleased
+
+## 2.0.0.alpha.3
+
+### Added
+
+- Add a dated browser verification matrix with full Chrome coverage, focused
+  Firefox and macOS Safari lanes, and explicit Android, iOS, and near-floor
+  release checks.
+- Add `--nk-button-radius` so applications can preserve a button-specific shape without changing inputs and surfaces.
+- Add structured JSON output to `nitro_kit:doctor` for migration automation.
+
+### Changed
+
+- Accept Rails-style nested and conditional class values through `desperately_need_a_class:`, normalizing retained external-integration hooks without manual string formatting, while directing migrations to review every use and aim for zero.
+- Make migration diagnostics surface usages of application-owned button treatments and provable 2.0 Table/Button runtime contract errors, and require semantic theme translation plus wide and narrow browser comparison.
+- Recognize explicit Stimulus controller registration used by JavaScript bundlers.
+- Explain the purpose and limits of generated host-integration smoke tests in each generated file.
+
+### Documentation
+
+- Define the rolling evergreen browser-support policy, with Mobile Safari as a
+  first-class target and standards-first, feature-detected fallbacks for core
+  behavior.
+- Classify every interactive component's no-JavaScript baseline as full,
+  reduced, or unavailable.
+- Document native month and week inputs as progressive enhancement, including
+  server-side ISO validation and bounded Select guidance.
+- Document Accordion's reduced single-group behavior where named details are
+  unavailable instead of adding a compatibility controller.
+
+### Fixed
+
+- Keep Dialog, Sheet, and CommandPalette controls working when Invoker Commands
+  are unavailable while preserving the native declarative path and consistent
+  focus restoration in Safari.
+- Stack AppShell toolbar actions below the title on narrow screens instead of
+  clipping child-route titles when a Back affordance and several actions share
+  the header.
+- Restore Dropdown outside-tap dismissal on affected Mobile Safari Popover
+  implementations and keep its reduced placement inside the viewport.
+- Provide readable Typeset styling in Firefox versions without CSS `@scope`.
+- Keep settled progressive images visible when Turbo restores a cached page.
+- Keep arbitrary multi-element Button content aligned inside the label slot.
+- Keep the command palette at a stable height while filtering destinations.
+- Use a neutral elevated surface instead of the primary accent for tooltips.
+- Resolve implicit FormBuilder labels only when rendered, so custom field blocks work under strict i18n.
+- Allow generated upgrade smoke tests to coexist with host catch-all routes while still rejecting exact route collisions.
+
 ## 2.0.0.alpha.2
 
 This alpha keeps the 2.0 API experimental while incorporating the first full
@@ -73,7 +122,7 @@ Nitro Kit 2.0 alpha is a ground-up, intentionally incompatible rebuild around ge
 - Static zero-specificity CSS, light and dark theme tokens with a no-JavaScript system fallback, and a separate Tailwind CSS v4 adapter.
 - Responsive Flex and Grid layouts with fixed mobile-first breakpoints, closed values, classless data contracts, and no Tailwind runtime; plus the constrained-width Container.
 - Sortable `Table` headers with caller-owned URLs, native `aria-sort`, and an optional Ransack gallery recipe.
-- Eleven blocks and shells: AuthShell, AppShell, SettingsLayout, Toolbar, PaginationBar, PageHeader, StatGrid, DataSection, FormSection, DangerZone, and EmptyState.
+- Eleven blocks and shells: AuthShell, AppShell, SettingsLayout, Toolbar, PaginationBar, PageHeader, StatGrid, DataSection, SettingsSection, DangerZone, and EmptyState.
 - AppNavigation, AppearancePicker, DetailsTable, Dropzone, and ProgressiveImage components, plus the non-visual AppearanceBootstrap runtime.
 - Typed Choice values and direct-Phlex Rails FormBuilder integration with Active Model errors, native and direct uploads, and Turbo Frame/Stream examples.
 - Direct optional Pagy integration through `Pagination(pagy:)`, with an explicit URL callable for caller-owned destinations.

data/README.md

@@ -6,16 +6,16 @@
 
 **Rails front-end for the agent era.**
 
-Nitro Kit is a gem-owned, agent-native UI system for Ruby on Rails. The `2.0.0.alpha.2` prerelease is a ground-up rebuild under active testing and must not be treated as stable. New documentation and the Nitro Kit Pro alpha catalog are coming next.
+Nitro Kit is a gem-owned, agent-native UI system for Ruby on Rails. The `2.0.0.alpha.3` prerelease is a ground-up rebuild under active testing and must not be treated as stable. New documentation and the Nitro Kit Pro alpha catalog are coming next.
 
 [![RubyGems](https://img.shields.io/gem/v/nitro_kit.svg)](https://rubygems.org/gems/nitro_kit)
 
 ## Installation
 
-Install the alpha explicitly and keep it pinned while evaluating it.
+Install the prerelease explicitly and keep it pinned while evaluating it.
 
 ```ruby
-gem "nitro_kit", "2.0.0.alpha.2"
+gem "nitro_kit", "2.0.0.alpha.3"
 ```
 
 Use the released gem and commit `Gemfile` with `Gemfile.lock`. Before upgrading, review the changelog, run `bundle update nitro_kit`, rerun the installer, and test the application.
@@ -26,7 +26,26 @@ bin/rails generate nitro_kit:install
 bin/rails nitro_kit:doctor
 ```
 
-The [agent guide](docs/agent_guide.md), [Rails integration guide](docs/rails_integration.md), and [component contracts](docs/component_contracts.md) are included with the gem.
+Example migration prompt:
+
+> Upgrade this Rails app to Nitro Kit `2.0.0.alpha.3`. Run the installer, follow its diagnostics, preserve existing behavior and styling, and use Nitro Kit MCP patterns where helpful. Run tests and summarize changes or unresolved issues.
+
+Example new application prompt:
+
+> Build this Rails app with Nitro Kit `2.0.0.alpha.3`. Run the installer, follow the included agent guide, compose gem-owned components, and use Nitro Kit MCP patterns where helpful. Add tests and summarize the result.
+
+The [agent guide](docs/agent_guide.md), [Rails integration guide](docs/rails_integration.md), [component contracts](docs/component_contracts.md), and [browser support policy](docs/browser_support.md) are included with the gem.
+
+## Browser support
+
+Nitro Kit uses modern web standards while keeping core content and actions
+usable for the overwhelming majority of people on maintained browsers. The
+practical target is current stable and popular evergreen releases from roughly
+the previous two years, with Mobile Safari as a first-class target. Small,
+feature-detected fallbacks preserve essential behavior without holding
+components to the oldest browser's feature set; visual polish may degrade. See
+the [browser support policy](docs/browser_support.md) for the dated browser
+matrix and canonical full/reduced/unavailable no-JavaScript classifications.
 
 Maintaining Nitro Kit 1? Its frozen documentation remains at [v1.nitrokit.dev](https://v1.nitrokit.dev).
 

data/STYLE_GUIDE.md

@@ -32,6 +32,35 @@ render immediately and only work from a Phlex context; they do not work in ERB.
 - Let applications customize themes and compose product-specific UI without editing Nitro internals.
 - Keep behavior minimal, progressive, and Turbo-safe.
 
+## Browser compatibility
+
+The public compatibility contract lives in
+[`docs/browser_support.md`](docs/browser_support.md). Use modern standards while
+keeping essential behavior usable for the overwhelming majority of people on
+maintained browsers. The practical target is current stable and popular
+evergreen Chrome, Edge, Firefox, macOS Safari, and iOS Safari releases from
+roughly the previous two years. Treat Mobile Safari as a primary browser. The
+dated release matrix sets the actual floor by release date and usage, not equal
+major-version counts.
+
+Prefer approved native standards even when their support is newer than the
+window, but do not confuse standards adoption with baseline availability.
+Feature-detect the preferred path and add the smallest Nitro-owned fallback
+when its absence breaks core content, navigation, submission, disclosure, or
+overlay operation. A simpler layout, placement, wrapping, or animation is an
+acceptable fallback. Copying controllers into applications, requiring every
+consumer to choose a polyfill, or silently leaving a control inert is not.
+
+Record no-JavaScript behavior per interactive component. Test the native and
+fallback paths, Turbo cache and reconnect lifecycles, keyboard behavior, and a
+representative browser near the support-window floor. Chromium emulation alone
+does not establish Safari or iOS compatibility.
+
+Place a broadly supported CSS declaration before a newer visual enhancement,
+or use a feature query when unsupported syntax would invalidate layout, color,
+contrast, focus visibility, or interaction. Unsupported polish may disappear;
+readability and operability may not.
+
 ## File layout
 
 ```text
@@ -206,7 +235,7 @@ component translates each string the controller needs and emits it through the
 Stimulus values API:
 
 ```html
-<div data-nk--dropzone-queued-value="Queued">
+<div data-nk--dropzone-queued-value="Queued"></div>
 ```
 
 The controller reads the value and keeps the shipped English literal only as an
@@ -219,10 +248,13 @@ a translator sees one grammar in both languages.
 Nitro components never emit or depend on classes. The only exception is:
 
 ```ruby
-desperately_need_a_class: "external-widget-hook"
+desperately_need_a_class: [
+  "external-widget-hook",
+  { "is-active": active? }
+]
 ```
 
-It must produce both the class and `data-nk-escape="class"`. Blank or non-string values raise. Implement this once in the base component.
+It accepts Rails `class_names` values—strings, symbols, nested arrays, and conditional hashes—and normalizes them into a deduplicated string. It must contain at least one class and produce both the class and `data-nk-escape="class"`. Implement this once in the base component. Tailwind applications may run a Tailwind-aware merger before passing classes when conflicting utilities need resolution; Nitro does not require one.
 
 ## CSS architecture
 
@@ -275,7 +307,7 @@ Never target an unqualified `[data-slot]`. Never use `transition: all`.
 
 Public `--nk-*` variables cover themeable decisions: semantic colors, paired foregrounds, typography, spacing, radii, control dimensions, shadows, borders, motion, and content widths.
 
-Buttons and data-entry controls share control heights, radii, border geometry, focus treatment, and disabled treatment, but they do not share one surface role. Inputs, selects, textareas, and unchecked controls use the general surface tokens. The raised default Button uses the public `--nk-button-default-background`, `--nk-button-default-hover-background`, `--nk-button-default-foreground`, and `--nk-button-default-border` tokens. Button-like controls such as the native file selector may consume the same treatment; do not make ordinary data-entry surfaces depend on it.
+Buttons and data-entry controls share control heights, the default radius scale, border geometry, focus treatment, and disabled treatment, but they do not share one surface role. `--nk-button-radius` may override only Button shape when an application deliberately distinguishes buttons from inputs and surfaces. Inputs, selects, textareas, and unchecked controls use the general surface tokens. The raised default Button uses the public `--nk-button-default-background`, `--nk-button-default-hover-background`, `--nk-button-default-foreground`, and `--nk-button-default-border` tokens. Button-like controls such as the native file selector may consume the same treatment; do not make ordinary data-entry surfaces depend on it.
 
 Private `--_nk-*` variables coordinate component mechanics and are not a theme API.
 
@@ -370,7 +402,7 @@ Do not add mandatory Dropzone.js, Ransack, or image-processing dependencies to N
 
 Native HTML and CSS own behavior when they already provide the required semantics. Stimulus adds the smallest missing enhancement.
 
-- Use `details`/`summary` for disclosure, declarative `command`/`commandfor` for dialogs, native Popover for dropdown visibility, and CSS hover/focus for tooltips.
+- Prefer `details`/`summary` for disclosure, declarative `command`/`commandfor` for dialogs, native Popover for dropdown visibility, and CSS hover/focus for tooltips. Before making one authoritative, verify that it covers `docs/browser_support.md` or pair it with the smallest capability-detected fallback.
 - Do not mirror browser-owned open state into `data-state`, `aria-expanded`, or hidden attributes. Use targets and values only for state Nitro genuinely owns.
 - The exception is state HTML cannot express as an attribute at all. A checkbox's `indeterminate` is a DOM property with no markup form, so `Checkbox` mounts `nk--checkable` only when `indeterminate: true`, and that controller's whole scope is applying the property and owning the matching `data-state="indeterminate"`. Ordinary checked state stays native, with no controller and no mirrored `data-state`. Do not widen a controller past the one state the browser cannot express.
 - Keep native state selectors such as `[open]` and `:popover-open` authoritative in CSS.