baldur 0.1.6 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e620053e45888da66925e20f8143ce9d5dcc70eaccec2b536414fe433e346e92
-  data.tar.gz: 1ec87cf893794467a791cad74f09fad3be0a2750d7962b7d08b07b021aa2518e
+  metadata.gz: 633d727781f1701dcac870818b72d1c8df5ea9392cee702502ce5bd45aa1ef8a
+  data.tar.gz: aa155789ea73b321dff4cb7d795e5291c7613cbcff8b24142558c8b9cd0e3700
 SHA512:
-  metadata.gz: 0e54b8327f9ce5842ab63ca60aaf81c1f14217a70beabf30f372454d75614bf711d25a1b985156eb6bd3573c5c18b565002b8792217b79c57bf9ac93a2272bff
-  data.tar.gz: 20e13f55afd2a2f20b2c2116986dd023d6ac9d592008549321acb77e0b87b72091ee901f722bf6a43091da0a34f1949dc3e1b7d1f42162e91535bf97ea59adc0
+  metadata.gz: 00f499098c0a6cd6bd35aa0819e9978e63648f23d3c7e1b1e57f90c3b6775338beb54fbf956e3e1185666b89362e523e39fadb9403c7722b1d97c4353530a568
+  data.tar.gz: e45efa594d08c3271fa53a2b56319d92e97e270c2610595c5ff01ce16b9a8d3e7a6b4ece4da564d82ccb8b5e42f80c0160611dc2ae92a51c7e855be9c94a4113

data/README.md

@@ -1,24 +1,29 @@
 # Baldur
 
-Baldur is a reusable Rails UI engine for apps using the same frontend stack as this repository:
+[![Gem Version](https://badge.fury.io/rb/baldur.svg)](https://badge.fury.io/rb/baldur) [![CI](https://github.com/varunmurkar/baldur/actions/workflows/ci.yml/badge.svg)](https://github.com/varunmurkar/baldur/actions)
 
-- Rails 8
+Batteries-included opinionated Rails UI engine for the importmap, Stimulus, Tailwind stack. Baldur helps Rails teams ship polished UI faster with install generators, reusable ui_* helpers, Tailwind components, and Stimulus wiring for apps using Propshaft, importmap-rails, stimulus-rails, and tailwindcss-rails.
+
+## Supported Stack
+
+- **Ruby** `>= 3.3`
+- **Rails** `>= 7.0`
 - Propshaft
 - `importmap-rails`
 - `stimulus-rails`
-- `tailwindcss-rails`
+- `tailwindcss-rails` `>= 4.3.0`
 
-## Install Into Another App
+It ships install generators, ready `ui_*` helpers, Tailwind components, and Stimulus controllers so host teams can skip rebuilding common UI primitives per app.
 
-1. Add Baldur to the target app `Gemfile`:
+## Install
 
-Baldur now declares `tailwindcss-rails >= 4.4.0` as a gem dependency, so hosts do not need to add that gem separately unless they want to enforce their own minimum version.
+Add to your `Gemfile`:
 
 ```ruby
 gem "baldur", ">= 0.1.3"
 ```
 
-2. Run:
+Run:
 
 ```sh
 bundle install
@@ -26,327 +31,117 @@ bundle exec rails tailwindcss:engines
 bundle exec rails generate baldur:install
 ```
 
-3. Rebuild Tailwind:
+Rebuild Tailwind:
 
 ```sh
 bundle exec rails tailwindcss:build
 ```
 
-`tailwindcss:engines` creates `app/assets/builds/tailwind/baldur.css` from the engine-owned Tailwind entrypoint. `baldur:install` then imports that generated build into the host Tailwind entrypoint.
-
-If the host app already runs `tailwindcss:build` or `tailwindcss:watch`, those commands will also create the engine build automatically once the engine entrypoint exists.
-
-4. Install optional surfaces as needed:
+Optional surfaces:
 
 ```sh
 bundle exec rails generate baldur:install_panel_secondary
 bundle exec rails generate baldur:install_google_auth
 ```
 
-`baldur:install` now includes `Baldur::Optional::AuthPageHelper` in generated `UiHelper`, so `ui_auth_page` is available by default after base install.
-
-The generators above are still optional and only required when using those specific surfaces.
-
-Default install behavior keeps Geist loaded through the host `fonts.css` scaffold. If a host app wants a different stack, it should update `fonts.css` and then map the loaded families in `theme.css`.
-
-## Security
-
-- New Baldur releases require MFA for RubyGems owners via gem metadata starting with `0.1.2`.
-- Release artifacts should be installed from RubyGems or GitHub releases and can be verified with the published `.sha512` checksum file.
-- Report vulnerabilities privately through GitHub Security Advisories.
-
-To verify a release artifact manually:
-
-```sh
-sha512sum -c baldur-0.1.3.gem.sha512
-```
-
-## Styling Ownership
-
-Tailwind provides the utility/base layer. Baldur is the source of truth for shared design-system primitives.
-
-- Import host `fonts.css` before Tailwind so the host controls what font families get loaded.
-- Import the generated Baldur Tailwind engine build into the host Tailwind entrypoint.
-- Import host `theme.css` after the Baldur build to override only the base palette inputs and font-token mapping.
-- Treat host `fonts.css` as the project-specific font loading layer.
-- Treat host `theme.css` as the project-specific override layer for palette, font-token mapping, and other brand inputs, not as a place to fork Baldur-owned primitive styles.
-- Add host-app styles only for app-specific surfaces after Baldur.
-- Do not re-import or override host-local copies of Baldur-owned primitives such as buttons, forms, snackbars, or tables.
-- Keep shared elevation semantics in Baldur-owned `--elev-*` tokens. If a host app needs softer or stronger shared shadows, change the Baldur token source instead of swapping raw Tailwind shadow utilities into Baldur-owned primitives.
-- Do not keep duplicate copies of Baldur-owned primitives under `app/assets/stylesheets/application/`; leave only app-specific files there.
-- Do not keep host copies of Baldur semantic theme files such as `theme/light.css` or `theme/dark.css`.
-
-## What The Installer Assumes
-
-- Tailwind entrypoint exists at `app/assets/tailwind/application.css`
-- Host app gets `tailwindcss-rails` through Baldur or its own Gemfile and uses engine builds
-- Host app uses importmap Stimulus boot with `app/javascript/controllers`
-- Host app gets `app/assets/stylesheets/fonts.css` for font loading and `app/assets/stylesheets/theme.css` for brand and font-token overrides
-- Host app can import `app/assets/builds/tailwind/baldur.css` from `app/assets/tailwind/application.css`
-
-## Building UI
-
-Canonical Ruby internals live under `Baldur::*`, but the default DX is `ui_*` helpers through the generated `UiHelper` include.
-
-Not every `ui_*` helper is part of the base install. Some helpers belong to optional surfaces and require the matching generator. `ui_auth_page` is part of the default install; `ui_panel_secondary` and google-auth helpers are optional.
-
-Examples:
-
-```erb
-<%= ui_button(label: "Save", href: "#") %>
-
-<%= ui_card(title: "Revenue") do %>
-  <p>Content</p>
-<% end %>
-
-<%= ui_panel_secondary(id: "assistant", title: "Assistant", trigger_label: "Open") do %>
-  <p>Panel content</p>
-<% end %>
-```
-
-External triggers can open a Baldur panel declaratively:
-
-```erb
-<button
-  type="button"
-  data-open-panel="#assistant"
-  data-panel-payload="<%= json_escape({ source: "dashboard" }.to_json) %>">
-  Open assistant
-</button>
-```
-
-`panel-secondary` emits `baldur:panel:opened` and `baldur:panel:closed` on the panel shell and `window`. The event detail includes `id`, `selector`, `trigger`, and parsed `payload`.
-
-For modals, prefer `ui_modal` directly:
-
-```erb
-<%= ui_modal(id: "confirm-delete", title: "Delete item") do %>
-  <p>This action cannot be undone.</p>
-<% end %>
-```
-
-For auth layouts, use `ui_auth_page` (available after `baldur:install`):
-
-```erb
-<%= ui_auth_page(title: "Sign in", description: nil, brand_path: root_path) do %>
-  <%= yield %>
-<% end %>
-```
-
-Auth flash messaging can be rendered inside the card by passing `notice:` / `alert:`:
+## Example
 
-```erb
-<%= ui_auth_page(title: "Sign in", description: nil, brand_path: root_path, notice: notice, alert: alert) do %>
-  <%= yield %>
-<% end %>
-```
-
-If a host app keeps a shared wrapper partial around `ui_modal`, treat `modal_body:` as the wrapper-local input and let the wrapper pass that content into `ui_modal`. Avoid calling a wrapper with `body:` through `render`, since `body` collides with Rails render options.
-
-For horizontal primary/secondary CTA groups, prefer `ui_action_row`:
+Render a sidebar with navigation and a main content area:
 
 ```erb
-<%= ui_action_row(
-  secondary_button: { label: "Back", variant: :outline, href: settings_path },
-  primary_button: { label: "Save", variant: :primary, type: :submit }
-) %>
-```
-
-The action row owns the responsive layout and keeps the primary CTA last on the right.
-
-Use `ui_alert` for inline status surfaces. Alerts support optional inline actions and opt-in collapsed state:
-
-```erb
-<%= ui_alert(
-  variant: :warning,
-  title: "Data freshness warning",
-  actions: ui_button(label: "Upload Latest Data", href: new_ecommerce_import_path, variant: :primary, size: :sm),
-  collapsible: true,
-  collapse_key: "tenant-#{current_tenant.id}-executive-pulse-stale-data"
-) do %>
-  <p>Latest available data is 10 days old.</p>
-<% end %>
-```
-
-Collapsed alerts stay inline and can be re-expanded with the built-in `More` summary action.
-
-## Tables
-
-Use the table helpers as a small composition system:
-
-- `ui_table` is the table atom.
-- `ui_table_card` is the card shell for title, controls, table body, and footer.
-- `ui_table_footer` owns the `Show [x] items per page` control and the `Showing x-y of z` status line.
-- `ui_pagination` is the page-navigation atom and is usually composed through `ui_table_footer`.
-
-If a table has title, controls, rows, and pagination, render them inside the same `ui_table_card`.
-
-Use `ui_table` directly for embedded or simple tables:
-
-```erb
-<%= ui_table(
-  columns: [
-    { label: "SKU", key: :sku },
-    { label: "Status", key: :status },
-    { label: "Revenue", key: :revenue, header_class: "text-right", cell_class: "text-right" }
-  ],
-  rows: [
-    { sku: "SKU-001", status: "Active", revenue: number_to_currency(12_500) },
-    { sku: "SKU-002", status: "Draft", revenue: number_to_currency(3_800) }
-  ],
-  empty_state: "No SKUs found"
-) %>
-```
-
-Use `ui_table_card` when the table is a standalone surface:
-
-```erb
-<% table_controls = capture do %>
-  <div class="flex items-end gap-3">
-    <%= ui_menu_select_tag :status,
-          options: [
-            { label: "All", value: "all" },
-            { label: "Active", value: "active" },
-            { label: "Draft", value: "draft" }
-          ],
-          selected: params[:status].presence || "all",
-          label: "Status" %>
-  </div>
-<% end %>
-
-<%= ui_table_card(
-  title: "Products",
-  description: "Track inventory and performance in one place.",
-  controls: table_controls,
-  controls_position: :header,
-  footer: ui_table_footer(
-    current_page: @pagination[:current_page],
-    total_pages: @pagination[:total_pages],
-    total_count: @pagination[:total_count],
-    per_page: @pagination[:per_page],
-    path_builder: ->(page) { products_path(request.query_parameters.merge(page: page, per_page: @pagination[:per_page])) },
-    rows_per_page_param: "per_page",
-    rows_per_page_options: [10, 20, 50],
-    rows_per_page_selected: @pagination[:per_page]
-  )
-) do %>
-  <%= ui_table(
-    sort: { key: params[:sort], direction: params[:direction] },
-    sort_path_builder: ->(sort_key, direction) { products_path(request.query_parameters.merge(sort: sort_key, direction: direction, page: 1)) },
-    columns: [
-      { label: "SKU", key: :sku, sortable: true, sort_key: "sku" },
-      { label: "Status", key: :status },
-      {
-        label: "Revenue",
-        key: :revenue,
-        sortable: true,
-        sort_key: "revenue",
-        header_class: "text-right",
-        cell_class: "text-right",
-        header_tooltip: "Total revenue attributed to the current filter window."
-      }
-    ],
-    rows: @rows,
-    empty_state: "No products found"
-  ) %>
+<%= ui_sidebar(
+      brand_path: root_path,
+      primary_links: [
+        { name: "Dashboard", path: root_path, icon: "layout-dashboard", active: current_page?(root_path) }
+      ]
+    ) do |_sidebar| %>
+  <main class="flex-1 p-6">
+    <h1>Dashboard</h1>
+  </main>
 <% end %>
 ```
 
-Use `controls_position: :header` for compact data-view controls that belong in the top-right header zone. Keep the default `:row` placement for wider filter bars. You can also pass `title_meta:` to render subdued inline metadata beside the title, for example `title_meta: "24 rows"`.
+## Getting Started
 
-Sorting is opt-in: header sort controls render only when a column is marked `sortable: true` and the table receives `sort:` plus `sort_path_builder:`.
+- See [docs/installation.md](docs/installation.md) for install steps.
+- See [docs/sidebar.md](docs/sidebar.md) and [docs/auth.md](docs/auth.md) for common usage patterns.
 
-Use `ui_pagination` directly only when you need bare page navigation without the table-footer composition.
+## Documentation
 
-## Marketing Templates
+- [Installation](docs/installation.md)
+- [Styling](docs/styling.md)
+- [Sidebar](docs/sidebar.md)
+- [Auth](docs/auth.md)
+- [Modals and Panels](docs/modals-and-panels.md)
+- [Alerts and Snackbars](docs/alerts-and-snackbars.md)
+- [Tables](docs/tables.md)
+- [Marketing](docs/marketing.md)
+- [Security](docs/security.md)
 
-Keep marketing-page templates separate from app UI primitives. Baldur’s low-level atoms still live under the shared `ui_*` component layer, while full-page marketing surfaces use dedicated `ui_marketing_*` helpers.
-
-Current canonical marketing helpers:
-
-- `ui_marketing_top_nav`
-- `ui_marketing_hero_section(variant: :solar_system, ...)`
-- `ui_marketing_features_section`
-- `ui_marketing_testimonials_section(variant: :bento, ...)`
-- `ui_marketing_faq_section`
-- `ui_marketing_cta_banner`
-- `ui_marketing_pricing_tables`
-- `ui_marketing_footer`
+## Security
 
-Use the existing landing and pricing templates as the canonical v1 variants. Future hero or testimonial layouts should be added as new variants, not folded into the existing default markup.
+See [docs/security.md](docs/security.md) for artifact verification, MFA requirements, and vulnerability reporting.
 
-Marketing nav/footer branding comes from `config.marketing_brand` in the Baldur initializer. Hosts can override that deployment-level default per render by passing `brand:` into `ui_marketing_top_nav` or `ui_marketing_footer`. If a future host needs tenant-specific or whitelabel branding, resolve/cache that in the app and pass the resolved values through `brand:` rather than teaching Baldur about tenant lookup.
+## Available Now
 
-Interactive marketing templates ship with Baldur-owned Stimulus controllers. `baldur:install` now generates `marketing_tabs_controller.js` and `marketing_pricing_controller.js` shims so features tabs and pricing billing toggles do not depend on host-specific controller names.
+- [x] Host app brand theming via `theme.css` and `config.marketing_brand`
+- [x] Reusable auth page shell for sign-in, sign-up, and password reset
+- [x] Core UI helpers, Tailwind components, and Stimulus wiring
 
-`config.marketing_brand` supports `name`, `wordmark`, `logo_src`, `logo_alt`, and optional `href`. Hosts should treat that config as the canonical branding contract instead of relying on helper-method coupling.
+## Roadmap
 
-Example hero usage:
+### Installing
+- Harden `baldur:install` so host assumptions are reduced
+- Expand `script/verify_host_install` coverage
+- Add end-to-end install verification in dummy app
 
-```erb
-<%= ui_marketing_hero_section(
-  variant: :solar_system,
-  headline: "Turn Every Data Point Into ROI",
-  body: "Connect fragmented data into one decision engine.",
-  primary_action: { label: "Book a Demo", variant: :primary, href: dashboard_path },
-  secondary_action: { label: "See Use Cases", variant: :outline, href: "#use-cases" },
-  supporting_action: { href: "#", label: "Watch walkthrough", data: { open_modal: "#walkthrough-modal" } },
-  callouts: [
-    { label: "Unified decision context" },
-    { label: "Prioritized recommendations" },
-    { label: "Impact-aware next actions" }
-  ],
-  orbit_sources: [
-    { name: "Shopify", asset_path: "/landing/source-logos/shopify.svg" },
-    { name: "HubSpot", asset_path: "/landing/source-logos/hubspot.svg" }
-  ],
-  centerpiece_image: { src: "/branding/logo.png", alt: "Acme logo" }
-) %>
-```
+### Showcase
+- Add a dedicated dummy app for visual smoke checks
+- Add component inventory/showcase page in dummy app
+- Add interaction showcase pages for modal, sidebar, menu select, snackbar, and panel_secondary
+- Add copy-paste examples for core surfaces from the showcase app back into docs
 
-Example features section usage:
+### Starter Templates
+- Add dedicated password reset templates
+- Add magic link templates
+- Add error/system pages
+- Add starter settings page layout
+- Add starter CRUD index/show/form templates
+- Add starter dashboard shell/page templates
 
-```erb
-<%= ui_marketing_features_section(
-  title: "What Mimir unlocks for your teams",
-  description: "Tailored to your business model and decision priorities.",
-  tabs: [
-    {
-      value: "ecommerce",
-      label: "E-commerce",
-      selected: true,
-      panel_title: "E-commerce",
-      panel_body: "Priority ROI plays for commerce teams.",
-      cards: [
-        { title: "Which products should I run campaigns for?", body: "Rank SKUs by incremental margin potential." }
-      ]
-    }
-  ],
-  cta: { label: "Get a demo tailored for you", variant: :primary, href: dashboard_path }
-) %>
-```
+### Forms
+- Add Rails form-builder integration for Baldur fields
+- Bind labels, hints, errors, and invalid states automatically
+- Document model-bound form usage
 
-## Snackbars
+### Tables and Resource Screens
+- Add a higher-level resource index pattern on top of existing table primitives
+- Support search, filters, row actions, bulk select, and empty states
+- Document recommended resource index composition
 
-Use semantic snackbar tones:
+### Theming
+- Add a small set of starter theme presets
+- Improve dark-mode/theme controller documentation
+- Document brand-token customization more clearly
 
-- `:success` for green success states
-- `:notice` for blue notice/info states
-- `:warning` for amber warning states
-- `:error` for red error states
+### Accessibility
+- Audit keyboard and focus behavior across interactive components
+- Add accessibility-focused tests for core surfaces
+- Document a11y guarantees and known gaps
 
-Host apps should map `flash[:notice]` to `:notice` and `flash[:alert]` to `:error` unless they have a stronger semantic signal available.
+### Internationalization
+- Add I18n-friendly labels/messages for reusable helpers
+- Remove hard-coded helper copy where practical
+- Document translation override points
 
-## Smoke Check
+## Contributing
 
-Run this from the host app root after installation:
+Open an issue or PR. Before you start, read [CONTRIBUTING.md](CONTRIBUTING.md) and [docs/security.md](docs/security.md).
 
-```sh
-bundle exec ruby "$(bundle show baldur)/script/verify_host_install"
-```
+## Changelog
 
-That verifies the host can render core helpers and confirms the Tailwind entrypoint contains the required Baldur imports.
+See [CHANGELOG.md](CHANGELOG.md).
 
-## Deferred Work
+## License
 
-See `TODO.md` for work intentionally deferred until the dedicated gem repo exists.
+MIT. See [LICENSE](LICENSE).

data/TODO.md

@@ -1,7 +1,50 @@
 # Baldur TODO
 
-- Improve RubyGems page description for DX
+## Install and Verification
+- [ ] Harden `baldur:install` so host assumptions are reduced
+- [ ] Audit generated controller shims against all shipped components
+- [ ] Expand `script/verify_host_install` coverage
+- [ ] Add end-to-end install verification in dummy app
 
-- Add a dedicated dummy app in the extracted gem repo for visual smoke checks.
-- Add a component inventory/showcase page in that dummy app.
-- Add a few interaction-specific showcase pages for modal, sidebar, menu select, snackbar, and `panel_secondary`.
+## Showcase App and Docs
+- [ ] Add a dedicated dummy app in the extracted gem repo for visual smoke checks
+- [ ] Add a component inventory/showcase page in that dummy app
+- [ ] Add interaction showcase pages for modal, sidebar, menu select, snackbar, and `panel_secondary`
+- [ ] Add copy-paste examples for core surfaces from the showcase app back into docs
+
+## Starter Templates
+- [ ] Add dedicated password reset templates
+- [ ] Add magic link templates
+- [ ] Add error/system pages
+- [ ] Add starter settings page layout
+- [ ] Add starter CRUD index/show/form templates
+- [ ] Add starter dashboard shell/page templates
+
+## Forms
+- [ ] Add Rails form-builder integration for Baldur fields
+- [ ] Bind labels, hints, errors, and invalid states automatically
+- [ ] Document model-bound form usage
+
+## Tables and Resource Screens
+- [ ] Add a higher-level resource index pattern on top of existing table primitives
+- [ ] Support search, filters, row actions, bulk select, and empty states
+- [ ] Document recommended resource index composition
+
+## Theming
+- [ ] Add a small set of starter theme presets
+- [ ] Improve dark-mode/theme controller documentation
+- [ ] Document brand-token customization more clearly
+
+## Accessibility
+- [ ] Audit keyboard and focus behavior across interactive components
+- [ ] Add accessibility-focused tests for core surfaces
+- [ ] Document a11y guarantees and known gaps
+
+## Internationalization
+- [ ] Add I18n-friendly labels/messages for reusable helpers
+- [ ] Remove hard-coded helper copy where practical
+- [ ] Document translation override points
+
+## Contributor and Agent Guidance
+- [ ] Add `.agents/AGENTS.md` with project conventions and reference files for LLM agents
+- [ ] Keep `.agents/AGENTS.md` in sync with actual project conventions

data/app/assets/javascripts/baldur/controllers/confirmation_controller.js

@@ -0,0 +1,23 @@
+import { Controller } from "@hotwired/stimulus";
+
+export default class ConfirmationController extends Controller {
+  static targets = ["input", "submit", "expectedText"];
+  static values = { caseSensitive: { type: Boolean, default: true } };
+
+  connect() {
+    this.validate();
+  }
+
+  validate() {
+    if (!this.hasSubmitTarget || !this.hasInputTarget) return;
+
+    const input = this.inputTarget.value.trim();
+    const expected = this.hasExpectedTextTarget ? this.expectedTextTarget.textContent.trim() : "";
+
+    const matches = this.caseSensitiveValue
+      ? input === expected
+      : input.toLowerCase() === expected.toLowerCase();
+
+    this.submitTarget.disabled = !matches;
+  }
+}

data/app/assets/stylesheets/baldur/application/components/auth-page.css

@@ -0,0 +1,22 @@
+@layer components {
+  .auth-page {
+    display: flex;
+    min-height: 100vh;
+    align-items: center;
+    justify-content: center;
+    padding: var(--space-6);
+    background: var(--color-surface-low);
+  }
+
+  .auth-page__container {
+    width: 32rem;
+    max-width: 100%;
+    margin-inline: auto;
+  }
+
+  .auth-page__brand {
+    display: flex;
+    justify-content: center;
+    margin-bottom: var(--space-6);
+  }
+}

data/app/assets/stylesheets/baldur/application/components/confirmation.css

@@ -0,0 +1,11 @@
+@layer components {
+  .confirmation-modal__input-wrapper {
+    margin-top: var(--space-4);
+  }
+
+  [data-confirmation] .text-field__control:focus {
+    border-color: var(--color-primary);
+    outline: none;
+    box-shadow: 0 0 0 2px color-mix(in srgb, var(--color-primary) 24%, transparent);
+  }
+}