baldur 0.2.5 → 0.3.0

data/docs/forms.md

@@ -0,0 +1,267 @@
+# Forms
+
+## Text Field Basics
+
+Use `ui_text_field_tag` for Baldur-styled single-line inputs and textareas.
+
+```erb
+<%= ui_text_field_tag(
+  :company_name,
+  "Acme",
+  label: "Company name",
+  supporting_text: "Shown in billing and exports."
+) %>
+```
+
+Use Baldur-owned named parameters for common concerns:
+
+- `label:`
+- `supporting_text:`
+- `type:`
+- `required:`
+- `disabled:`
+- `wrapper_class:`
+- `input_class:`
+- `multiline:`
+- `prefix:`
+- `suffix:`
+
+## HTML5 Input Attributes via `input_options`
+
+For raw HTML input attributes, pass them through `input_options:`.
+
+This is the recommended way to set HTML5 attributes such as:
+
+- `step`
+- `min`
+- `max`
+- `inputmode`
+- `autocomplete`
+- `pattern`
+- `maxlength`
+- `readonly`
+- `data`
+- `aria`
+- custom `id`
+
+Example:
+
+```erb
+<%= ui_text_field_tag(
+  :price,
+  12.5,
+  label: "Price",
+  type: :number,
+  input_options: {
+    step: :any,
+    min: 0,
+    inputmode: "decimal",
+    autocomplete: "off"
+  }
+) %>
+```
+
+Another example with pattern and max length:
+
+```erb
+<%= ui_text_field_tag(
+  :sku,
+  nil,
+  label: "SKU",
+  input_options: {
+    pattern: "[A-Z0-9-]+",
+    maxlength: 32,
+    autocomplete: "off"
+  }
+) %>
+```
+
+`ui_text_field_tag` forwards `input_options` directly to the underlying `<input>` or `<textarea>` after Baldur applies its own base classes, generated `id`, and accessibility wiring.
+
+## Hidden State Fields
+
+Use hidden fields to preserve UI state that should survive submits, validation rerenders, or Turbo refreshes.
+
+Common examples:
+
+- active tab
+- selected filter
+- stepped form state
+- selected panel
+
+For Baldur-flavored app code, prefer `ui_hidden_field_tag`:
+
+```erb
+<%= ui_hidden_field_tag :planner_tab, "targets" %>
+```
+
+It is a thin wrapper around Rails `hidden_field_tag`, so both are valid.
+
+### When to Use `ui_hidden_field_tag`
+
+Prefer `ui_hidden_field_tag` when:
+
+- hidden state is part of a documented Baldur interaction pattern
+- you want host app helper usage to stay consistently `ui_*`
+- the hidden field sits beside other Baldur controls such as segmented buttons, menu selects, or submit flows
+
+### When Plain `hidden_field_tag` Is Acceptable
+
+Plain Rails `hidden_field_tag` is still acceptable when:
+
+- the field is simple Rails glue and Baldur adds no extra meaning
+- you are already inside host-specific form builder or low-level Rails form code
+- the hidden field is not part of a reusable Baldur interaction pattern
+
+Rule of thumb: if the hidden field is helping a Baldur control preserve UI state, reach for `ui_hidden_field_tag`. If it is generic Rails plumbing, plain `hidden_field_tag` is fine.
+
+### URL Params vs Hidden State
+
+Prefer URL params for state that should be shareable, bookmarkable, or navigable:
+
+- GET-driven tabs
+- filters in index screens
+- state that should survive refresh and copy-pasted URLs
+
+Prefer hidden fields for state that primarily belongs to an in-form workflow:
+
+- current step in a stepped form
+- active tab inside a POST form
+- selected panel within a multi-surface editor
+
+Avoid storing the same state in both params and hidden inputs unless the flow truly needs both.
+
+## Hidden State Cookbook
+
+### Active Tab
+
+Inside a form, store the selected tab so rerenders return the user to the same panel:
+
+```erb
+<% current_tab = params[:planner_tab].presence || "global" %>
+
+<%= form_with url: planner_path, method: :post do %>
+  <%= ui_hidden_field_tag :planner_tab,
+                          current_tab,
+                          data: { planner_tabs_target: "hiddenInput" } %>
+
+  <%= ui_segmented_buttons(
+    aria_label: "Planner tabs",
+    items: [
+      {
+        label: "Global",
+        value: "global",
+        selected: current_tab == "global",
+        data: {
+          action: "click->planner-tabs#switch",
+          planner_tabs_target: "tab",
+          planner_tab_value: "global"
+        }
+      },
+      {
+        label: "Targets",
+        value: "targets",
+        selected: current_tab == "targets",
+        data: {
+          action: "click->planner-tabs#switch",
+          planner_tabs_target: "tab",
+          planner_tab_value: "targets"
+        }
+      }
+    ]
+  ) %>
+<% end %>
+```
+
+See `docs/tabs-and-segmented-controls.md` for the full tabs cookbook.
+
+### Filters
+
+For POST-backed filter forms or mixed interactive controls, hidden state can hold the selected filter key:
+
+```erb
+<%= form_with url: reports_path, method: :post do %>
+  <%= ui_hidden_field_tag :status_filter,
+                          params[:status_filter].presence || "active",
+                          data: { report_filters_target: "hiddenInput" } %>
+
+  <%= ui_segmented_buttons(
+    aria_label: "Status filters",
+    items: [
+      {
+        label: "Active",
+        value: "active",
+        selected: params[:status_filter] != "archived",
+        data: {
+          action: "click->report-filters#select",
+          report_filter_value: "active"
+        }
+      },
+      {
+        label: "Archived",
+        value: "archived",
+        selected: params[:status_filter] == "archived",
+        data: {
+          action: "click->report-filters#select",
+          report_filter_value: "archived"
+        }
+      }
+    ]
+  ) %>
+<% end %>
+```
+
+If the filter should be shareable in the URL, prefer GET params instead of hidden POST state.
+
+### Stepped Form State
+
+For multi-step forms, hidden state can track current step across validation failures and submit cycles:
+
+```erb
+<% current_step = params[:step].presence || "details" %>
+
+<%= form_with url: onboarding_path, method: :post do %>
+  <%= ui_hidden_field_tag :step,
+                          current_step,
+                          data: { onboarding_target: "currentStep" } %>
+
+  <% if current_step == "details" %>
+    ...details fields...
+    <%= ui_button(label: "Continue", type: :submit, data: { action: "click->onboarding#setStep", onboarding_step_value: "billing" }) %>
+  <% elsif current_step == "billing" %>
+    ...billing fields...
+    <%= ui_button(label: "Review", type: :submit, data: { action: "click->onboarding#setStep", onboarding_step_value: "review" }) %>
+  <% end %>
+<% end %>
+```
+
+Server rerender should read `params[:step]` and send the same value back so the correct step remains visible.
+
+### Selected Panel
+
+When a page has multiple host-owned panels, hidden state can preserve which panel was open when the form submitted:
+
+```erb
+<%= form_with url: workspace_path, method: :post do %>
+  <%= ui_hidden_field_tag :selected_panel,
+                          params[:selected_panel].presence || "summary",
+                          data: { workspace_panels_target: "hiddenInput" } %>
+
+  <%= ui_button(label: "Show Details", type: :button, data: { action: "click->workspace-panels#select", workspace_panel_value: "details" }) %>
+  <%= ui_button(label: "Show Summary", type: :button, data: { action: "click->workspace-panels#select", workspace_panel_value: "summary" }) %>
+<% end %>
+```
+
+This is useful when visibility is host-owned but the selected panel should survive submit-driven rerenders.
+
+## When to Use Raw Rails Helpers
+
+Prefer raw Rails helpers when Baldur is not adding meaningful value to the field shape.
+
+Good examples:
+
+- simple hidden fields with no Baldur interaction coupling
+- low-level form builder integrations
+- one-off HTML attributes that already fit naturally inside `input_options:`
+
+Prefer Baldur helpers when you want shared label, support text, styling, component structure, or a documented interaction pattern.

data/docs/installation.md

@@ -0,0 +1,63 @@
+# Installation
+
+## Add the Gem
+
+Add to the host `Gemfile`:
+
+```ruby
+gem "baldur", ">= 0.1.3"
+```
+
+Baldur declares `tailwindcss-rails >= 4.3.0` as a dependency, so hosts do not need to add it separately unless they want to enforce their own minimum version.
+
+## Install and Generate
+
+```sh
+bundle install
+bundle exec rails tailwindcss:engines
+bundle exec rails generate baldur:install
+```
+
+`tailwindcss:engines` creates `app/assets/builds/tailwind/baldur.css` from the engine-owned Tailwind entrypoint.
+
+`baldur:install` imports that generated build into the host Tailwind entrypoint.
+
+If the host already runs `tailwindcss:build` or `tailwindcss:watch`, those commands will also create the engine build once the entrypoint exists.
+
+## Rebuild Tailwind
+
+```sh
+bundle exec rails tailwindcss:build
+```
+
+## Optional Surfaces
+
+Install only what you need:
+
+```sh
+bundle exec rails generate baldur:install_panel_secondary
+bundle exec rails generate baldur:install_google_auth
+```
+
+`baldur:install` already includes `Baldur::Optional::AuthPageHelper` in the generated `UiHelper`, so `ui_auth_page` is available by default after base install. The generators above are only required when using those specific surfaces.
+
+## Installer Assumptions
+
+- 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`
+
+Default install behavior keeps Geist loaded through the host `fonts.css` scaffold. If the host wants a different stack, update `fonts.css` and then map the loaded families in `theme.css`.
+
+## Smoke Check
+
+After installation, run from the host app root:
+
+```sh
+bundle exec rails tailwindcss:build
+bundle exec ruby "$(bundle show baldur)/script/verify_host_install"
+```
+
+That verifies the host can render core helpers, confirms the Tailwind entrypoint contains the required Baldur imports, and checks that Baldur template utility classes (e.g. `px-6`, `py-4`, `uppercase`, `tracking-wide`) are present in the compiled CSS. If utility classes are missing, the engine `@source` paths in `engine.css` may be misconfigured — ensure they resolve correctly from `app/assets/tailwind/baldur/` to `app/helpers` and `app/views`.

data/docs/marketing.md

@@ -0,0 +1,77 @@
+# Marketing
+
+## When to Use
+
+Use marketing helpers for landing pages, pricing, and feature surfaces. Keep marketing-page templates separate from app UI primitives. Low-level atoms live under `ui_*`, while full-page marketing surfaces use dedicated `ui_marketing_*` helpers.
+
+## 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`
+
+Use the existing landing and pricing templates as canonical v1 variants. Future hero or testimonial layouts should be added as new variants, not folded into the existing default markup.
+
+## Branding
+
+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 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.
+
+`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.
+
+## Controllers
+
+Interactive marketing templates ship with Baldur-owned Stimulus controllers. `baldur:install` 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.
+
+## Examples
+
+Hero:
+
+```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" }
+) %>
+```
+
+Features:
+
+```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 }
+) %>
+```

data/docs/modals-and-panels.md

@@ -0,0 +1,55 @@
+# Modals and Panels
+
+## Modals
+
+Prefer `ui_modal` directly:
+
+```erb
+<%= ui_modal(id: "confirm-delete", title: "Delete item") do %>
+  <p>This action cannot be undone.</p>
+<% 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.
+
+## Panels
+
+`ui_panel_secondary` is part of the optional panel surface. Install it if needed:
+
+```sh
+bundle exec rails generate baldur:install_panel_secondary
+```
+
+Example usage:
+
+```erb
+<%= 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`.
+
+## Action Rows
+
+For horizontal primary/secondary CTA groups, prefer `ui_action_row`:
+
+```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.

data/docs/security.md

@@ -0,0 +1,11 @@
+# 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.
+
+## Verify a Release Artifact
+
+```sh
+sha512sum -c baldur-0.1.3.gem.sha512
+```

data/docs/sidebar.md

@@ -0,0 +1,105 @@
+# Sidebar
+
+## When to Use
+
+Use `ui_sidebar` for authenticated application shells. It is part of the base install and includes:
+
+- desktop and mobile sidebar shell markup
+- `sidebar` and `mobile-sidebar` controller wiring
+- default brand rendering from `config.marketing_brand`
+- default nav rendering for primary and secondary links
+
+Host apps provide the route arrays, active-state logic, and any optional slot content.
+
+## Quick Example
+
+```erb
+<%= 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 %>
+```
+
+## Link Options
+
+Each link accepts:
+
+- `name` required label text
+- `path` required destination
+- `icon` optional Lucide icon name, defaults to `circle`
+- `active` optional boolean for `aria-current="page"`
+- `title` optional hover title
+- `method` optional Rails link method
+- `data` optional data attributes hash
+- `html_options` optional extra HTML attributes hash
+
+## Brand Behavior
+
+- `brand_name`, `brand_wordmark`, and `brand_logo` are optional
+- when omitted, Baldur resolves them from `config.marketing_brand`
+- `brand_path` defaults to `#` if the host app does not provide one
+
+## Mobile Behavior
+
+- mobile nav mirrors desktop primary and secondary links automatically
+- the install generator ships both `sidebar_controller.js` and `mobile_sidebar_controller.js`
+
+## Slots vs Params
+
+You can adopt `ui_sidebar` with no slots. The block content becomes the main app surface beside the sidebar:
+
+```erb
+<%= ui_sidebar(
+      brand_path: root_path,
+      primary_links: sidebar_primary_links,
+      secondary_links: sidebar_secondary_links,
+      secondary_label: "Admin"
+    ) do |_sidebar| %>
+  <main id="main-content" class="flex-1 p-6">
+    <%= yield %>
+  </main>
+<% end %>
+```
+
+For host-specific sidebar surfaces, prefer slots. `*_content` params are also supported for incremental adoption.
+
+```erb
+<%= ui_sidebar(
+      brand_path: root_path,
+      primary_links: sidebar_primary_links,
+      secondary_links: sidebar_secondary_links,
+      secondary_label: "Admin"
+    ) do |sidebar| %>
+  <% sidebar.with_header do %>
+    <%= render "layouts/tenant_switcher" %>
+  <% end %>
+
+  <% sidebar.with_footer do %>
+    <div class="space-y-2">
+      <p class="text-sm text-muted"><%= current_user.email %></p>
+      <%= ui_button(label: "Sign out", href: logout_path, method: :delete, variant: :text, size: :sm, icon: "log-out") %>
+    </div>
+  <% end %>
+<% end %>
+```
+
+## Ownership
+
+Host apps own:
+
+- route definitions
+- active-state logic
+- app-specific header/footer content
+
+Baldur owns:
+
+- desktop and mobile sidebar shell markup
+- toggle behavior wiring
+- default brand rendering
+- default nav rendering

data/docs/styling.md

@@ -0,0 +1,34 @@
+# Styling
+
+## Ownership
+
+Tailwind provides the utility/base layer. Baldur is the source of truth for shared design-system primitives.
+
+Host app responsibilities:
+
+- Load `fonts.css` before Tailwind to control font families.
+- Import the generated Baldur Tailwind engine build into the host Tailwind entrypoint.
+- Override only base palette inputs and font-token mapping in `theme.css` after the Baldur build.
+- Add host-app styles only for app-specific surfaces after Baldur.
+
+Host app restrictions:
+
+- Do not re-import or override host-local copies of Baldur-owned primitives such as buttons, forms, snackbars, or tables.
+- 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`.
+- Keep shared elevation semantics in Baldur-owned `--elev-*` tokens. If a host needs softer or stronger shared shadows, change the Baldur token source instead of swapping raw Tailwind shadow utilities into Baldur-owned primitives.
+
+## Brand tokens
+
+Baldur derives all semantic colors from four brand input tokens. Override only these in your host `theme.css` — see `docs/theme.md` for the full token reference and customization guide.
+
+In short:
+
+| Token | Purpose |
+|-------|---------|
+| `--_primary-base` | Primary actions, CTA |
+| `--_secondary-base` | Sidebar, nav, subdued |
+| `--_accent-base` | Highlights, badges |
+| `--_neutral-base` | Surfaces, text, borders |
+
+Do not override semantic `--color-*` tokens (e.g. `--color-primary`, `--color-surface`). Baldur maps brand inputs to semantic outputs automatically for both light and dark modes.