dash_kit 2.0.0

data/lib/dash_kit/reference/guide.md

@@ -0,0 +1,289 @@
+## DashKit
+
+DashKit is a Rails engine gem for composable, configurable dashboards. It is a
+presentation and interaction layer: you register widgets, persist per-owner
+configuration (visibility, order, filters), and render dashboards without
+coupling the UI to any specific data backend.
+
+### What DashKit is
+
+- A Rails engine (`DashKit::Engine`) with an isolated namespace, mounted in the
+  host app.
+- A widget registry: dashboard types map to the widgets available on them.
+- A persistence layer for user preferences (which widgets show, in what order,
+  with which filters) via an ActiveRecord `Dashboard` model.
+- A rendering layer that lazy-loads each widget through a Turbo Frame and
+  refreshes on configuration change.
+
+A dashboard renders two kinds of widget side by side:
+
+- **Registered widgets** — declared up front in `DashKit.configure`. The
+  developer fixes the set of widgets a dashboard type can show.
+- **Widget definitions (built widgets)** — created at runtime by a host-app
+  *user* through the settings modal and persisted as records. The host opens a
+  small builder UI (a `source` and a `visualization`) and DashKit renders each
+  built widget through a host-registered renderer partial.
+
+### What DashKit is not
+
+- It does **not** define metrics or their meaning.
+- It does **not** query databases or fetch data. Widgets declare what they need
+  through a partial; the host app supplies the data.
+- It does **not** validate filter meaning or enforce business rules.
+- It assumes no specific backend or analytics engine.
+
+DashKit treats datasets as opaque structures it can render consistently, so a
+host can replace or evolve its backend without rewriting dashboards.
+
+### Architecture
+
+The layers, all under the `DashKit` namespace:
+
+- **WidgetRegistry** (`lib/dash_kit/widget_registry.rb`) — a global registry
+  mapping a dashboard type to its available widgets. `DashKit.registry` returns
+  the singleton; `DashKit.configure { |r| ... }` yields it. Each
+  `register(:type)` block uses a `DashboardBuilder` whose `widget(key, label:,
+  partial:, **options)` declares one widget and assigns it a position by
+  declaration order.
+- **Dashboard** (`app/models/dash_kit/dashboard.rb`) — the ActiveRecord model
+  (table `dash_kit_dashboards`) persisting per-owner configuration:
+  `widget_order`, `hidden_widgets`, `widget_settings`, and `filter_state`, plus
+  `name`, `dashboard_type`, `visibility` (`private` or `account`),
+  `role_default_for`, and `active`. It `belongs_to :owner, polymorphic: true`
+  and optionally an `account`. Owners may have many named dashboards;
+  `for_owner(owner)` and `for_account(account)` scope them, and `activate!` /
+  `duplicate!` manage the active one.
+- **WidgetManagement** (`app/models/concerns/dash_kit/widget_management.rb`) — a
+  concern mixed into `Dashboard` providing `ordered_visible_widgets`,
+  `available_widgets`, `widget_visible?`, `toggle_widget`, `move_widget_up`,
+  `move_widget_down`, and `update_filter`.
+- **WidgetDefinition** (`app/models/dash_kit/widget_definition.rb`) — the
+  ActiveRecord model (table `dash_kit_widget_definitions`) for a widget a user
+  built at runtime. It `belongs_to :dashboard` and carries `source` (string),
+  `visualization` (string), and `options` (jsonb, default `{}`). `Dashboard
+  has_many :widget_definitions, -> { order(:id) }, dependent: :destroy`.
+- **RendererRegistry** (`lib/dash_kit/renderer_registry.rb`) — a global registry
+  mapping a visualization name to the host partial that draws it.
+  `DashKit.register_renderer(:visualization_name, partial: "path/to/partial")`
+  registers one; `DashKit.renderer_for(visualization)` looks it up;
+  `DashKit.visualizations` lists the registered names; `DashKit.reset_renderers!`
+  clears them. A built widget whose visualization has no registered renderer
+  falls back to the `dash_kit/widget_definitions/missing_renderer` partial.
+- **Sources** — the host declares what a viewer may build from with
+  `DashKit.available_sources_for = ->(viewer) { [...] }`, a lambda returning the
+  list of sources offered in the builder. `DashKit.available_sources(viewer)`
+  calls it. It defaults to `NO_SOURCES` (`->(_viewer) { [] }`), so the builder UI
+  stays hidden until the host sets it.
+- **DashboardHelper** (`app/helpers/dash_kit/dashboard_helper.rb`) — view
+  helpers: `dash_kit_render_widgets(config:)`, `dash_kit_widget_frame`,
+  `dash_kit_settings_modal(config:)`, `dash_kit_settings_button_attributes`,
+  `dash_kit_loading_skeleton`, and, for built widgets,
+  `dash_kit_available_sources`, `dash_kit_visualizations`, and
+  `dash_kit_widget_definition_frame(definition)`. `dash_kit_render_widgets`
+  renders the registered widgets in order, then appends one lazy Turbo Frame per
+  `widget_definition`.
+
+### Data flow
+
+UI events -> dashboard update -> Turbo refresh -> widgets re-render via
+lazy-loaded Turbo Frames. A widget is never rendered inline; it loads through a
+`<turbo-frame loading="lazy">` pointing at the widget's own route. The frame
+carries its dashboard's id, so the widget partial is handed the dashboard's
+`filter_state` to render against (DashKit passes the blob; the host interprets
+it).
+
+Built widgets follow the same flow. Each `widget_definition` lazy-loads through
+its own `<turbo-frame>` at `/widget_definitions/:id`;
+`WidgetDefinitionsController#show` finds the definition scoped to the current
+owner's dashboards, looks up `renderer_for(definition.visualization)`, and
+renders that host partial with `source:` (the definition's source), `options:`
+(its options hash), and `filter_state: definition.dashboard.filter_state`. So
+**both** registered widgets and built widgets receive the dashboard's
+`filter_state` as a local — DashKit passes the opaque blob and the host partial
+reads it to shape its own data or stats request.
+
+### Routes (mounted at `/dash_kit`)
+
+The engine routes live in `config/routes.rb`:
+
+- `GET  /widgets/:id` — render an individual registered widget
+- `GET  /widget_definitions/:id` — render an individual built widget
+- `resources :dashboards` (`index`, `new`, `create`, `edit`, `update`,
+  `destroy`) plus member `select`, `duplicate`, `toggle_widget`, `move_widget`,
+  `reorder`, and `save_filters` — the dashboard CRUD plus the widget
+  visibility/order/filter actions.
+- Dashboard member `create_definition`, `update_definition`, and
+  `destroy_definition` — create, update, and delete a built widget. They accept
+  `widget_definition[source, visualization, options]` (strong params
+  `permit(:source, :visualization, options: {})`) and are guarded by
+  `require_editable!`.
+
+### JavaScript
+
+Stimulus controllers ship via importmap (no Node.js build step). The
+`SortableListController` handles client-side widget toggles and drag reordering,
+batching saves when the settings modal closes. It depends on `sortablejs`.
+
+### Widget builder (built widgets)
+
+Beyond the registered widgets a developer declares, DashKit lets a host-app
+*user* build their own widgets at runtime and persist them as
+`WidgetDefinition` records. Two host-supplied pieces turn the builder on:
+
+- **Sources** — set `DashKit.available_sources_for = ->(viewer) { [...] }` to
+  return the list of sources a viewer may build from. Until the host sets this
+  it defaults to `NO_SOURCES` and the builder UI stays hidden. The settings
+  modal only renders the "Build a widget" form when
+  `dash_kit_available_sources.any?`.
+- **Renderers** — call `DashKit.register_renderer(:visualization, partial:
+  "path/to/partial")` for each visualization the builder offers, and write each
+  renderer partial. A built widget whose visualization has no registered
+  renderer falls back to `dash_kit/widget_definitions/missing_renderer`.
+
+In the UI, the settings modal's "Build a widget" form is a `source` select
+(from `available_sources`) and a `visualization` select (from `visualizations`);
+it POSTs to `create_definition`. Once saved, `dash_kit_render_widgets` appends a
+lazy Turbo Frame for the new definition, which loads `/widget_definitions/:id`
+and renders the matching renderer partial with `source`, `options`, and
+`filter_state` — the same `filter_state` contract registered widgets get. A
+renderer partial reads `filter_state` to shape its own data request; DashKit
+passes the opaque blob and never interprets it.
+
+### Installation in a host app
+
+Add the gem to the host's `Gemfile` (until it is on RubyGems, use a git source):
+
+```ruby
+gem "dash_kit", github: "DYB-Development/dash_kit"
+```
+
+Then run the install generator and migrate:
+
+```bash
+bundle install
+rails generate dash_kit:install
+rails db:migrate
+```
+
+The generator creates the migrations for `dash_kit_dashboards` and
+`dash_kit_widget_definitions`, the `config/initializers/dash_kit.rb`
+initializer, and mounts the engine with `mount DashKit::Engine => "/dash_kit"`.
+The following manual steps remain:
+
+1. **Add the association to the owner model** (the model that owns dashboards,
+   e.g. `Account`):
+
+   ```ruby
+   has_many :dash_kit_dashboards, class_name: "DashKit::Dashboard",
+            as: :owner, dependent: :destroy
+   ```
+
+2. **Pin sortablejs** in `config/importmap.rb`:
+
+   ```ruby
+   pin "sortablejs"
+   ```
+
+3. **Register the Stimulus controllers** in
+   `app/javascript/controllers/index.js`:
+
+   ```js
+   import { registerControllers as registerDashKitControllers } from "dash_kit/index"
+   registerDashKitControllers(application)
+   ```
+
+4. **Configure the initializer** `config/initializers/dash_kit.rb`:
+
+   ```ruby
+   DashKit.parent_controller = "ApplicationController"
+   DashKit.current_owner_method = :current_account
+
+   DashKit.configure do |config|
+     config.register(:home) do |d|
+       d.widget :on_deck, label: "On Deck", partial: "widgets/home/on_deck"
+       d.widget :tasks,   label: "Tasks",   partial: "widgets/home/tasks"
+     end
+   end
+   ```
+
+   - `parent_controller` is the controller DashKit's controllers inherit from,
+     giving them the host's authentication and helpers. It defaults to
+     `DashKit::ApplicationController`.
+   - `current_owner_method` is the method DashKit calls to scope dashboards
+     to the current owner (e.g. `:current_account`). It defaults to `nil` and
+     must be set.
+
+5. **Create a dashboard controller and view** that look up the dashboard and
+   render the widgets:
+
+   ```ruby
+   class DashboardController < ApplicationController
+     def show
+       @dashboard = DashKit::Dashboard.for_owner(current_account)
+         .find_or_create_by!(dashboard_type: "home", name: "Home") do |dashboard|
+           dashboard.widget_order = DashKit.registry.default_widget_order(:home)
+         end
+     end
+   end
+   ```
+
+   ```erb
+   <%= dash_kit_settings_button_attributes %>
+   <%= dash_kit_settings_modal(config: @dashboard) %>
+   <%= dash_kit_render_widgets(config: @dashboard) %>
+   ```
+
+6. **(Optional) Enable the widget builder.** To let users build their own
+   widgets, set the sources lambda and register a renderer per visualization in
+   the initializer, then write each renderer partial:
+
+   ```ruby
+   DashKit.available_sources_for = ->(viewer) { viewer.account.reports }
+   DashKit.register_renderer(:bar_chart, partial: "widgets/renderers/bar_chart")
+   DashKit.register_renderer(:stat,      partial: "widgets/renderers/stat")
+   ```
+
+   Each renderer partial receives `source`, `options`, and `filter_state` as
+   locals. Until `available_sources_for` returns a non-empty list the builder UI
+   stays hidden.
+
+### Conventions a consuming app must follow
+
+- **Register every dashboard type and its widgets** in
+  `DashKit.configure`; a widget that is not registered will not render. Each
+  `widget` needs a `label` and a `partial`. Declaration order is the default
+  display order.
+- **Supply the data yourself.** A widget's partial is responsible for fetching
+  and rendering its own data; DashKit only renders the partial inside a lazy
+  Turbo Frame. Keep partials self-contained around the owner DashKit scopes to.
+  This holds for registered widgets and for built-widget renderer partials
+  alike — both receive `filter_state` and read it to shape their own request.
+- **Register a renderer for every visualization the builder offers.** A built
+  widget renders through the partial registered with
+  `DashKit.register_renderer`; one with no registered renderer falls back to the
+  `missing_renderer` partial. Set `DashKit.available_sources_for` to expose the
+  builder UI in the first place.
+- **Persist built widgets through the engine routes**
+  (`create_definition` / `update_definition` / `destroy_definition`), not by
+  writing `WidgetDefinition` rows by hand.
+- **Scope to the current owner.** Always look up dashboards through
+  `DashKit::Dashboard.for_owner(owner)` and set `current_owner_method` so
+  DashKit never leaks one owner's dashboard to another. `Dashboard` is
+  polymorphic on `owner`.
+- **Persist preferences through the model, not by hand.** Use the
+  `WidgetManagement` methods (`toggle_widget`, `move_widget_up`,
+  `move_widget_down`, `update_filter`) or the engine routes; do not write
+  `widget_order` / `hidden_widgets` / `filter_state` directly.
+- **Let widgets lazy-load.** Render through `dash_kit_render_widgets` /
+  `dash_kit_widget_frame` so each widget loads in its own Turbo Frame; do not
+  inline widget bodies.
+- **Mobile-first, Tailwind, dark mode.** The shipped UI is styled with Tailwind
+  and supports dark mode; host styling should match. The primary surface is
+  often a native webview.
+
+### Requirements
+
+- Ruby >= 3.2, Rails >= 7.1.
+- `turbo-rails` for Turbo Frames and Stream refreshes.
+- `keystone_ui` (a ViewComponent-based UI gem) for shared UI components.
+- `sortablejs`, pinned via importmap, for drag reordering.

data/lib/dash_kit/reference.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module DashKit
+  module Reference
+    GUIDE_PATH = File.expand_path("reference/guide.md", __dir__)
+
+    def self.content
+      File.read(GUIDE_PATH)
+    end
+  end
+end

data/lib/dash_kit/renderer_registry.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module DashKit
+  class RendererRegistry
+    def initialize
+      @renderers = {}
+    end
+
+    def register(visualization, partial:)
+      @renderers[visualization.to_sym] = partial
+    end
+
+    def renderer_for(visualization)
+      @renderers[visualization.to_sym]
+    end
+
+    def visualizations
+      @renderers.keys
+    end
+  end
+end

data/lib/dash_kit/the_local/agents/dash_kit-develop.md

@@ -0,0 +1,298 @@
+---
+name: dash_kit-develop
+description: Use to build dashboards and widgets with DashKit in a host app: register widget types, write widget partials, render and lazy-load them, and persist per-owner visibility, order, and filters correctly.
+tools: Read, Edit, Write, Bash
+---
+
+You build dashboards and widgets with DashKit, following the reference's conventions. You register dashboard types and widgets in DashKit.configure, write self-contained widget partials that fetch their own data, render through dash_kit_render_widgets so widgets lazy-load in Turbo Frames, and always scope dashboards to the current owner via Dashboard.for_owner. You enable the runtime widget builder by setting DashKit.available_sources_for and registering a renderer per visualization with DashKit.register_renderer, writing renderer partials that read filter_state just like registered widgets, and persisting built widgets through the create_definition/update_definition/destroy_definition routes rather than writing WidgetDefinition rows by hand. You persist preferences through the WidgetManagement methods and engine routes rather than writing JSON columns by hand. You never make DashKit query data or enforce metric semantics — those belong to the host.
+
+## DashKit
+
+DashKit is a Rails engine gem for composable, configurable dashboards. It is a
+presentation and interaction layer: you register widgets, persist per-owner
+configuration (visibility, order, filters), and render dashboards without
+coupling the UI to any specific data backend.
+
+### What DashKit is
+
+- A Rails engine (`DashKit::Engine`) with an isolated namespace, mounted in the
+  host app.
+- A widget registry: dashboard types map to the widgets available on them.
+- A persistence layer for user preferences (which widgets show, in what order,
+  with which filters) via an ActiveRecord `Dashboard` model.
+- A rendering layer that lazy-loads each widget through a Turbo Frame and
+  refreshes on configuration change.
+
+A dashboard renders two kinds of widget side by side:
+
+- **Registered widgets** — declared up front in `DashKit.configure`. The
+  developer fixes the set of widgets a dashboard type can show.
+- **Widget definitions (built widgets)** — created at runtime by a host-app
+  *user* through the settings modal and persisted as records. The host opens a
+  small builder UI (a `source` and a `visualization`) and DashKit renders each
+  built widget through a host-registered renderer partial.
+
+### What DashKit is not
+
+- It does **not** define metrics or their meaning.
+- It does **not** query databases or fetch data. Widgets declare what they need
+  through a partial; the host app supplies the data.
+- It does **not** validate filter meaning or enforce business rules.
+- It assumes no specific backend or analytics engine.
+
+DashKit treats datasets as opaque structures it can render consistently, so a
+host can replace or evolve its backend without rewriting dashboards.
+
+### Architecture
+
+The layers, all under the `DashKit` namespace:
+
+- **WidgetRegistry** (`lib/dash_kit/widget_registry.rb`) — a global registry
+  mapping a dashboard type to its available widgets. `DashKit.registry` returns
+  the singleton; `DashKit.configure { |r| ... }` yields it. Each
+  `register(:type)` block uses a `DashboardBuilder` whose `widget(key, label:,
+  partial:, **options)` declares one widget and assigns it a position by
+  declaration order.
+- **Dashboard** (`app/models/dash_kit/dashboard.rb`) — the ActiveRecord model
+  (table `dash_kit_dashboards`) persisting per-owner configuration:
+  `widget_order`, `hidden_widgets`, `widget_settings`, and `filter_state`, plus
+  `name`, `dashboard_type`, `visibility` (`private` or `account`),
+  `role_default_for`, and `active`. It `belongs_to :owner, polymorphic: true`
+  and optionally an `account`. Owners may have many named dashboards;
+  `for_owner(owner)` and `for_account(account)` scope them, and `activate!` /
+  `duplicate!` manage the active one.
+- **WidgetManagement** (`app/models/concerns/dash_kit/widget_management.rb`) — a
+  concern mixed into `Dashboard` providing `ordered_visible_widgets`,
+  `available_widgets`, `widget_visible?`, `toggle_widget`, `move_widget_up`,
+  `move_widget_down`, and `update_filter`.
+- **WidgetDefinition** (`app/models/dash_kit/widget_definition.rb`) — the
+  ActiveRecord model (table `dash_kit_widget_definitions`) for a widget a user
+  built at runtime. It `belongs_to :dashboard` and carries `source` (string),
+  `visualization` (string), and `options` (jsonb, default `{}`). `Dashboard
+  has_many :widget_definitions, -> { order(:id) }, dependent: :destroy`.
+- **RendererRegistry** (`lib/dash_kit/renderer_registry.rb`) — a global registry
+  mapping a visualization name to the host partial that draws it.
+  `DashKit.register_renderer(:visualization_name, partial: "path/to/partial")`
+  registers one; `DashKit.renderer_for(visualization)` looks it up;
+  `DashKit.visualizations` lists the registered names; `DashKit.reset_renderers!`
+  clears them. A built widget whose visualization has no registered renderer
+  falls back to the `dash_kit/widget_definitions/missing_renderer` partial.
+- **Sources** — the host declares what a viewer may build from with
+  `DashKit.available_sources_for = ->(viewer) { [...] }`, a lambda returning the
+  list of sources offered in the builder. `DashKit.available_sources(viewer)`
+  calls it. It defaults to `NO_SOURCES` (`->(_viewer) { [] }`), so the builder UI
+  stays hidden until the host sets it.
+- **DashboardHelper** (`app/helpers/dash_kit/dashboard_helper.rb`) — view
+  helpers: `dash_kit_render_widgets(config:)`, `dash_kit_widget_frame`,
+  `dash_kit_settings_modal(config:)`, `dash_kit_settings_button_attributes`,
+  `dash_kit_loading_skeleton`, and, for built widgets,
+  `dash_kit_available_sources`, `dash_kit_visualizations`, and
+  `dash_kit_widget_definition_frame(definition)`. `dash_kit_render_widgets`
+  renders the registered widgets in order, then appends one lazy Turbo Frame per
+  `widget_definition`.
+
+### Data flow
+
+UI events -> dashboard update -> Turbo refresh -> widgets re-render via
+lazy-loaded Turbo Frames. A widget is never rendered inline; it loads through a
+`<turbo-frame loading="lazy">` pointing at the widget's own route. The frame
+carries its dashboard's id, so the widget partial is handed the dashboard's
+`filter_state` to render against (DashKit passes the blob; the host interprets
+it).
+
+Built widgets follow the same flow. Each `widget_definition` lazy-loads through
+its own `<turbo-frame>` at `/widget_definitions/:id`;
+`WidgetDefinitionsController#show` finds the definition scoped to the current
+owner's dashboards, looks up `renderer_for(definition.visualization)`, and
+renders that host partial with `source:` (the definition's source), `options:`
+(its options hash), and `filter_state: definition.dashboard.filter_state`. So
+**both** registered widgets and built widgets receive the dashboard's
+`filter_state` as a local — DashKit passes the opaque blob and the host partial
+reads it to shape its own data or stats request.
+
+### Routes (mounted at `/dash_kit`)
+
+The engine routes live in `config/routes.rb`:
+
+- `GET  /widgets/:id` — render an individual registered widget
+- `GET  /widget_definitions/:id` — render an individual built widget
+- `resources :dashboards` (`index`, `new`, `create`, `edit`, `update`,
+  `destroy`) plus member `select`, `duplicate`, `toggle_widget`, `move_widget`,
+  `reorder`, and `save_filters` — the dashboard CRUD plus the widget
+  visibility/order/filter actions.
+- Dashboard member `create_definition`, `update_definition`, and
+  `destroy_definition` — create, update, and delete a built widget. They accept
+  `widget_definition[source, visualization, options]` (strong params
+  `permit(:source, :visualization, options: {})`) and are guarded by
+  `require_editable!`.
+
+### JavaScript
+
+Stimulus controllers ship via importmap (no Node.js build step). The
+`SortableListController` handles client-side widget toggles and drag reordering,
+batching saves when the settings modal closes. It depends on `sortablejs`.
+
+### Widget builder (built widgets)
+
+Beyond the registered widgets a developer declares, DashKit lets a host-app
+*user* build their own widgets at runtime and persist them as
+`WidgetDefinition` records. Two host-supplied pieces turn the builder on:
+
+- **Sources** — set `DashKit.available_sources_for = ->(viewer) { [...] }` to
+  return the list of sources a viewer may build from. Until the host sets this
+  it defaults to `NO_SOURCES` and the builder UI stays hidden. The settings
+  modal only renders the "Build a widget" form when
+  `dash_kit_available_sources.any?`.
+- **Renderers** — call `DashKit.register_renderer(:visualization, partial:
+  "path/to/partial")` for each visualization the builder offers, and write each
+  renderer partial. A built widget whose visualization has no registered
+  renderer falls back to `dash_kit/widget_definitions/missing_renderer`.
+
+In the UI, the settings modal's "Build a widget" form is a `source` select
+(from `available_sources`) and a `visualization` select (from `visualizations`);
+it POSTs to `create_definition`. Once saved, `dash_kit_render_widgets` appends a
+lazy Turbo Frame for the new definition, which loads `/widget_definitions/:id`
+and renders the matching renderer partial with `source`, `options`, and
+`filter_state` — the same `filter_state` contract registered widgets get. A
+renderer partial reads `filter_state` to shape its own data request; DashKit
+passes the opaque blob and never interprets it.
+
+### Installation in a host app
+
+Add the gem to the host's `Gemfile` (until it is on RubyGems, use a git source):
+
+```ruby
+gem "dash_kit", github: "DYB-Development/dash_kit"
+```
+
+Then run the install generator and migrate:
+
+```bash
+bundle install
+rails generate dash_kit:install
+rails db:migrate
+```
+
+The generator creates the migrations for `dash_kit_dashboards` and
+`dash_kit_widget_definitions`, the `config/initializers/dash_kit.rb`
+initializer, and mounts the engine with `mount DashKit::Engine => "/dash_kit"`.
+The following manual steps remain:
+
+1. **Add the association to the owner model** (the model that owns dashboards,
+   e.g. `Account`):
+
+   ```ruby
+   has_many :dash_kit_dashboards, class_name: "DashKit::Dashboard",
+            as: :owner, dependent: :destroy
+   ```
+
+2. **Pin sortablejs** in `config/importmap.rb`:
+
+   ```ruby
+   pin "sortablejs"
+   ```
+
+3. **Register the Stimulus controllers** in
+   `app/javascript/controllers/index.js`:
+
+   ```js
+   import { registerControllers as registerDashKitControllers } from "dash_kit/index"
+   registerDashKitControllers(application)
+   ```
+
+4. **Configure the initializer** `config/initializers/dash_kit.rb`:
+
+   ```ruby
+   DashKit.parent_controller = "ApplicationController"
+   DashKit.current_owner_method = :current_account
+
+   DashKit.configure do |config|
+     config.register(:home) do |d|
+       d.widget :on_deck, label: "On Deck", partial: "widgets/home/on_deck"
+       d.widget :tasks,   label: "Tasks",   partial: "widgets/home/tasks"
+     end
+   end
+   ```
+
+   - `parent_controller` is the controller DashKit's controllers inherit from,
+     giving them the host's authentication and helpers. It defaults to
+     `DashKit::ApplicationController`.
+   - `current_owner_method` is the method DashKit calls to scope dashboards
+     to the current owner (e.g. `:current_account`). It defaults to `nil` and
+     must be set.
+
+5. **Create a dashboard controller and view** that look up the dashboard and
+   render the widgets:
+
+   ```ruby
+   class DashboardController < ApplicationController
+     def show
+       @dashboard = DashKit::Dashboard.for_owner(current_account)
+         .find_or_create_by!(dashboard_type: "home", name: "Home") do |dashboard|
+           dashboard.widget_order = DashKit.registry.default_widget_order(:home)
+         end
+     end
+   end
+   ```
+
+   ```erb
+   <%= dash_kit_settings_button_attributes %>
+   <%= dash_kit_settings_modal(config: @dashboard) %>
+   <%= dash_kit_render_widgets(config: @dashboard) %>
+   ```
+
+6. **(Optional) Enable the widget builder.** To let users build their own
+   widgets, set the sources lambda and register a renderer per visualization in
+   the initializer, then write each renderer partial:
+
+   ```ruby
+   DashKit.available_sources_for = ->(viewer) { viewer.account.reports }
+   DashKit.register_renderer(:bar_chart, partial: "widgets/renderers/bar_chart")
+   DashKit.register_renderer(:stat,      partial: "widgets/renderers/stat")
+   ```
+
+   Each renderer partial receives `source`, `options`, and `filter_state` as
+   locals. Until `available_sources_for` returns a non-empty list the builder UI
+   stays hidden.
+
+### Conventions a consuming app must follow
+
+- **Register every dashboard type and its widgets** in
+  `DashKit.configure`; a widget that is not registered will not render. Each
+  `widget` needs a `label` and a `partial`. Declaration order is the default
+  display order.
+- **Supply the data yourself.** A widget's partial is responsible for fetching
+  and rendering its own data; DashKit only renders the partial inside a lazy
+  Turbo Frame. Keep partials self-contained around the owner DashKit scopes to.
+  This holds for registered widgets and for built-widget renderer partials
+  alike — both receive `filter_state` and read it to shape their own request.
+- **Register a renderer for every visualization the builder offers.** A built
+  widget renders through the partial registered with
+  `DashKit.register_renderer`; one with no registered renderer falls back to the
+  `missing_renderer` partial. Set `DashKit.available_sources_for` to expose the
+  builder UI in the first place.
+- **Persist built widgets through the engine routes**
+  (`create_definition` / `update_definition` / `destroy_definition`), not by
+  writing `WidgetDefinition` rows by hand.
+- **Scope to the current owner.** Always look up dashboards through
+  `DashKit::Dashboard.for_owner(owner)` and set `current_owner_method` so
+  DashKit never leaks one owner's dashboard to another. `Dashboard` is
+  polymorphic on `owner`.
+- **Persist preferences through the model, not by hand.** Use the
+  `WidgetManagement` methods (`toggle_widget`, `move_widget_up`,
+  `move_widget_down`, `update_filter`) or the engine routes; do not write
+  `widget_order` / `hidden_widgets` / `filter_state` directly.
+- **Let widgets lazy-load.** Render through `dash_kit_render_widgets` /
+  `dash_kit_widget_frame` so each widget loads in its own Turbo Frame; do not
+  inline widget bodies.
+- **Mobile-first, Tailwind, dark mode.** The shipped UI is styled with Tailwind
+  and supports dark mode; host styling should match. The primary surface is
+  often a native webview.
+
+### Requirements
+
+- Ruby >= 3.2, Rails >= 7.1.
+- `turbo-rails` for Turbo Frames and Stream refreshes.
+- `keystone_ui` (a ViewComponent-based UI gem) for shared UI components.
+- `sortablejs`, pinned via importmap, for drag reordering.
+