kiso 0.1.0.pre → 0.1.1.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4cd911512ec3d322db2ec1fd6ff2a24660fbc28e654424e710007e77a2e1317b
-  data.tar.gz: 8506e424c434844d10dd1dd7899ace376a65119b22e4602ea1ded3280ea85e86
+  metadata.gz: bda2256a79d7581462417a394433826ba6289cdab8f7f6bc04fbc451ee929478
+  data.tar.gz: a444b9108f532af991b690f8620faa3019639b533d9fd6ccda9f1aabca3b4540
 SHA512:
-  metadata.gz: ffa23334590c70c3576bba3f3cbab806d4965d1c673e12652f1c976f3a213d02a88fa568a2773d62a484eae7af9a4a62b018c3eed8fd04ecb383f7e122274b0f
-  data.tar.gz: 371226d21fc79972ff6b7fc222f59b7fa81a5a3fc660cc6f73bb2bfc5986a22ba3200d05a360551c249583b33930f0370e899bb6af3bd8497335da4d80eddd39
+  metadata.gz: 1cc8613ffb244b57a7499bcb4b4f7e4c3ec2c3c9feb8b8e6235cb55c9288cf0ea40261598424e33c221055577a0d8eeb9ec229aa18e9e0fcb20796551d5985c7
+  data.tar.gz: 93f2dee31a6a6526b7d6548b394a37eaa6ccca2bed6fa47b331664bfcb9a233bb466e41f9b5d4d1cdb8a029dcf85a46ddfb9286cb304165dc3420e7bcabd5ac3

data/CHANGELOG.md

@@ -7,11 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.1.pre] - 2026-03-03
+
+### Added
+
+- Dashboard layout system — sidebar, navbar, panel, toolbar, and nav components with cookie-persisted sidebar state
+- Avatar component with image, fallback, badge, and group support
+- Form components — Field, Label, Input, Textarea, InputGroup, Checkbox, RadioGroup, Switch, Select, Combobox
+- Overlay components — Popover, DropdownMenu, Command palette
+- Navigation components — Breadcrumb, Pagination
+- Element components — Kbd, Toggle, ToggleGroup
+- Dark mode system — `kiso_theme_script` helper, ColorModeButton, ColorModeSelect
+- Floating UI positioning for popovers and dropdowns
+- Global theme overrides via `Kiso.configure`
+- Configurable default icons via `kiso_component_icon`
+- Getting Started guide
+
+### Changed
+
+- Renamed `kiso()` helper to `kui()` to avoid Rails route proxy collision
+- Renamed `empty_state` to `empty` to match shadcn naming
+- Adopted `data-slot` convention from shadcn v4
+
 ## [0.1.0.pre] - 2026-02-25
 
 ### Added
 
-- Core engine with `kiso()` component helper and `component_tag` builder
+- Core engine with `kui()` component helper and `kiso_prepare_options` builder
 - `class_variants` + `tailwind_merge` integration for variant definitions
 - Theme CSS with 7 palettes, surface tokens, and dark mode
 - Badge component (color × variant × size, pill shape, SVG handling)
@@ -23,5 +45,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Lookbook component previews
 - Bridgetown documentation site
 
-[Unreleased]: https://github.com/steveclarke/kiso/compare/v0.1.0.pre...HEAD
+[Unreleased]: https://github.com/steveclarke/kiso/compare/v0.1.1.pre...HEAD
+[0.1.1.pre]: https://github.com/steveclarke/kiso/releases/tag/v0.1.1.pre
 [0.1.0.pre]: https://github.com/steveclarke/kiso/releases/tag/v0.1.0.pre

data/README.md

@@ -2,13 +2,16 @@
 
 UI components for Rails. Built on ERB, Tailwind CSS, and Hotwire.
 
-Add one gem and get badges, buttons, cards, alerts, and more. They all work with screen readers and dark mode. The look follows [shadcn/ui](https://ui.shadcn.com).
+Add one gem and get badges, buttons, cards, alerts, and more. They all work with screen readers and dark mode.
 
 No React. No extra build step. Just ERB with [class_variants](https://github.com/avo-hq/class_variants) for styling.
 
-Icons come from the [kiso-icons](https://github.com/steveclarke/kiso-icons) gem, which is bundled in.
+> [!WARNING]
+> Kiso is in early development and **not ready for production use**. The gem is published to reserve the name on RubyGems. APIs, component names, and theme tokens will change without notice. Watch the repo or check back in a few weeks.
 
-## Installation
+## Getting started
+
+Add the gem to your Gemfile and bundle:
 
 ```ruby
 # Gemfile
@@ -17,36 +20,70 @@ gem "kiso"
 
 ```bash
 bundle install
-bin/rails generate kiso:install
 ```
 
+Then add one import to your Tailwind CSS entrypoint:
+
+```css
+/* app/assets/tailwind/application.css */
+@import "../builds/tailwind/kiso.css";
+```
+
+And add the dark mode helper to your layout's `<head>`:
+
+```erb
+<head>
+  <%= kiso_theme_script %>
+  <%= stylesheet_link_tag "tailwind" %>
+  <%= javascript_importmap_tags %>
+</head>
+
+<body class="bg-background text-foreground antialiased">
+```
+
+That's it. Helpers, importmap pins, asset paths, and dark mode tokens are all
+wired up automatically by the engine. See the
+[Getting Started guide](https://kisoui.com/getting-started) for the full
+walkthrough.
+
+### Bundler apps (esbuild, Vite, Bun)
+
+If your app uses a JS bundler instead of importmaps, also install the npm
+package for Stimulus controllers:
+
+```bash
+npm install kiso-ui
+```
+
+```js
+// app/javascript/controllers/index.js
+import KisoUi from "kiso-ui"
+KisoUi.start(application)
+```
+
+Importmap apps get Stimulus controllers automatically — no npm install needed.
+
 ## Usage
 
-Use the `kiso()` helper to render components:
+Use the `kui()` helper to render components:
 
 ```erb
-<%= kiso(:badge, variant: :primary) { "Active" } %>
+<%= kui(:badge, color: :primary) { "Active" } %>
 ```
 
 Components are made of small parts. A card has a header, title, content, and footer:
 
 ```erb
-<%= kiso(:card) do %>
-  <%= kiso(:card, :header) do %>
-    <%= kiso(:card, :title, text: "Members") %>
+<%= kui(:card) do %>
+  <%= kui(:card, :header) do %>
+    <%= kui(:card, :title, text: "Members") %>
   <% end %>
-  <%= kiso(:card, :content) do %>
+  <%= kui(:card, :content) do %>
     ...
   <% end %>
 <% end %>
 ```
 
-Data attributes work on any HTML element too:
-
-```erb
-<%= f.submit "Save", data: { component: "button", variant: "primary" } %>
-```
-
 ## How it works
 
 Each component has two parts:
@@ -56,6 +93,10 @@ Each component has two parts:
 
 Colors use tokens like `bg-primary` and `text-muted`. They switch on their own in dark mode. No `dark:` classes needed.
 
+## Design system
+
+Kiso follows a strict spatial system — consistent heights, padding, gaps, typography, border radius, and icon sizing across every component. See the [Design System](https://kisoui.com/design-system) page for the visual reference.
+
 ## Design principles
 
 1. **Native HTML first.** Use `<dialog>`, `[popover]`, `<details>` before adding JavaScript.
@@ -79,11 +120,14 @@ This starts [Lookbook](https://lookbook.build) on port 4001 with a Tailwind watc
 
 Cloned without `--recurse-submodules`? Run `bin/vendor init` to fetch the vendor repos.
 
-Run tests:
+Run tests and lint:
 
 ```bash
-bundle exec rake test             # all tests
-bundle exec standardrb            # lint
+bundle exec rake test             # Ruby tests
+npm run test:unit                 # JS unit tests (Vitest)
+npm run test:e2e                  # E2E tests (Playwright, needs bin/dev)
+bundle exec standardrb            # Ruby lint
+npm run lint && npm run fmt:check # JS lint + format check
 ```
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) to help out.
@@ -93,12 +137,10 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) to help out.
 ```
 app/views/kiso/components/   ERB partials
 lib/kiso/themes/             Theme files (class_variants)
-app/helpers/kiso/            component_tag, kiso() helpers
-app/assets/stylesheets/kiso/ CSS (only transitions and pseudo-states)
-test/components/previews/    Lookbook previews
-test/dummy/                  Dev Rails app
-vendor/shadcn-ui/            Layout reference (git submodule)
-vendor/nuxt-ui/              Theme reference (git submodule)
+app/javascript/controllers/  Stimulus controllers (also shipped via npm as kiso-ui)
+app/helpers/kiso/            kui(), kiso_prepare_options() helpers
+app/assets/tailwind/kiso/   CSS (only transitions and pseudo-states)
+lookbook/                    Lookbook dev app (previews on port 4001)
 docs/                        Docs site (Bridgetown)
 ```
 
@@ -106,11 +148,11 @@ docs/                        Docs site (Bridgetown)
 
 - Ruby >= 3.3
 - Rails >= 8.0
-- [tailwindcss-rails](https://github.com/rails/tailwindcss-rails)
+- A Tailwind CSS build pipeline ([tailwindcss-rails](https://github.com/rails/tailwindcss-rails) or [cssbundling-rails](https://github.com/rails/cssbundling-rails))
 
 ## Status
 
-Early development. See [VISION.md](VISION.md) for the roadmap and full component list.
+Early development. APIs, component names, and theme tokens may change.
 
 ## License
 

data/Rakefile

@@ -1,5 +1,13 @@
 require "bundler/setup"
 require "bundler/gem_tasks"
+require "rake/testtask"
 
 APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
 load "rails/tasks/engine.rake"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+end
+
+task default: :test

data/app/assets/tailwind/kiso/checkbox.css

@@ -0,0 +1,18 @@
+/* Checkbox indicator — CSS ::after for the checkmark since native <input>
+   can't contain child elements. Uses mask-image with the Lucide Check icon. */
+
+[data-component="checkbox"] {
+  display: grid;
+  place-content: center;
+}
+
+[data-component="checkbox"]:checked::after {
+  content: '';
+  width: 0.875em;
+  height: 0.875em;
+  background-color: currentColor;
+  mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='white' stroke-width='3' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M20 6 9 17l-5-5'/%3E%3C/svg%3E");
+  mask-size: contain;
+  mask-repeat: no-repeat;
+  mask-position: center;
+}

data/app/assets/tailwind/kiso/color-mode.css

@@ -0,0 +1,9 @@
+/* ── Color Mode Components ────────────────────────────────────────────────────
+   Icon visibility for the color mode button. The .dark class on <html> drives
+   which icon is shown — sun in light mode, moon in dark mode. */
+
+@layer components {
+  [data-slot="color-mode-icon-dark"] { display: none; }
+  .dark [data-slot="color-mode-icon-light"] { display: none; }
+  .dark [data-slot="color-mode-icon-dark"] { display: inline-block; }
+}

data/app/assets/tailwind/kiso/dashboard.css

@@ -0,0 +1,176 @@
+/* ── Kiso Dashboard Layout ────────────────────────────────────────────────────
+   Tokens and mechanics for the full-screen sidebar + topbar dashboard shell.
+   Bundled with the engine — all apps get these tokens and layout rules.
+
+   Host apps can override any token in their own @theme block:
+     @theme { --sidebar-width: 18rem; }
+ */
+
+/* ── Tokens ──────────────────────────────────────────────────────────────── */
+
+@theme {
+  /* Sidebar geometry */
+  --sidebar-width:             16rem;
+
+  /* Layout heights */
+  --topbar-height:             3.5rem;
+
+  /* Sidebar surface tokens (light mode defaults) */
+  --sidebar-background:        var(--color-white);
+  --sidebar-foreground:        var(--color-zinc-900);
+  --sidebar-border:            var(--color-zinc-200);
+  --sidebar-accent:            var(--color-zinc-100);
+  --sidebar-accent-foreground: var(--color-zinc-700);
+
+  /* Animation */
+  --sidebar-duration:          220ms;
+  --ease-out-expo:             cubic-bezier(0.16, 1, 0.3, 1);
+
+  /* Z-index stack */
+  --z-topbar:  30;
+  --z-sidebar: 40;
+}
+
+/* Dark mode sidebar token overrides */
+.dark {
+  --sidebar-background:        var(--color-zinc-950);
+  --sidebar-foreground:        var(--color-zinc-100);
+  --sidebar-border:            var(--color-zinc-800);
+  --sidebar-accent:            var(--color-zinc-800);
+  --sidebar-accent-foreground: var(--color-zinc-300);
+}
+
+/* ── Layout mechanics ─────────────────────────────────────────────────────── */
+
+@layer components {
+  /* Drive --sidebar-current-width from the data attribute set by sidebar controller */
+  [data-sidebar-open="true"]  { --sidebar-current-width: var(--sidebar-width); }
+  [data-sidebar-open="false"] { --sidebar-current-width: 0rem; }
+
+  /* Hide sidebar border when collapsed to prevent ghost border at 0 width */
+  [data-sidebar-open="false"] [data-slot="dashboard-sidebar"] {
+    border-right-width: 0;
+  }
+
+  /* Flat 2×2 grid: topbar row + sidebar/panel row */
+  [data-slot="dashboard-group"] {
+    grid-template-rows: var(--topbar-height) 1fr;
+    grid-template-columns: var(--sidebar-current-width) 1fr;
+    transition: grid-template-columns var(--sidebar-duration) var(--ease-out-expo);
+  }
+
+  /* Topbar spans panel column only (sidebar owns full height) */
+  [data-slot="dashboard-navbar"] {
+    grid-column: 2;
+  }
+
+  /*
+    Sidebar: spans full height (both grid rows). background-color and
+    border-right-color are set here (not via Tailwind arbitrary classes)
+    because bg-[--css-var] classes don't generate reliably.
+  */
+  [data-slot="dashboard-sidebar"] {
+    grid-row: 1 / -1;
+    background-color: var(--sidebar-background);
+    border-right: 1px solid var(--sidebar-border);
+  }
+
+  /* Sidebar header: matches topbar height, bottom border */
+  [data-slot="dashboard-sidebar-header"] {
+    height: var(--topbar-height);
+    border-bottom: 1px solid var(--sidebar-border);
+  }
+
+  /* Sidebar footer: top border */
+  [data-slot="dashboard-sidebar-footer"] {
+    border-top: 1px solid var(--sidebar-border);
+  }
+
+  /* Inner nav: always sidebar-width, flex column for header/nav/footer layout */
+  [data-slot="dashboard-sidebar-inner"] {
+    width: var(--sidebar-width);
+    height: 100%;
+    overflow: hidden;
+    display: flex;
+    flex-direction: column;
+    color: var(--sidebar-foreground);
+  }
+
+  /* Panel: row 2, col 2 */
+  [data-slot="dashboard-panel"] {
+    grid-column: 2;
+    grid-row: 2;
+  }
+
+  /* ── Navbar layout variant: navbar spans full width, sidebar below ────── */
+  [data-layout="navbar"] [data-slot="dashboard-navbar"] {
+    grid-column: 1 / -1;
+  }
+  [data-layout="navbar"] [data-slot="dashboard-sidebar"] {
+    grid-row: auto;
+  }
+
+  /* Scrim: hidden on desktop */
+  [data-slot="dashboard-scrim"] { display: none; }
+
+  /* ── Collapse button icon switching ────────────────────────────────────── */
+  [data-sidebar-open="true"] [data-slot="collapse-icon-open"]   { display: inline; }
+  [data-sidebar-open="true"] [data-slot="collapse-icon-closed"]  { display: none; }
+  [data-sidebar-open="false"] [data-slot="collapse-icon-open"]  { display: none; }
+  [data-sidebar-open="false"] [data-slot="collapse-icon-closed"] { display: inline; }
+
+  /* ── Nav section (details/summary) ───────────────────────────────────── */
+  [data-slot="nav-section-chevron"] {
+    transition: transform 200ms ease;
+  }
+  [data-slot="nav-section"][open] [data-slot="nav-section-chevron"] {
+    transform: rotate(180deg);
+  }
+
+  /* ── Nav item sidebar context ────────────────────────────────────────── */
+  [data-slot="dashboard-sidebar-inner"] [data-slot="nav-item"]:hover {
+    background-color: var(--sidebar-accent);
+    color: var(--sidebar-accent-foreground);
+  }
+  [data-slot="dashboard-sidebar-inner"] [data-slot="nav-item"][data-active="true"] {
+    background-color: var(--sidebar-accent);
+    color: var(--sidebar-accent-foreground);
+  }
+
+  /* ── Mobile: sidebar becomes a fixed full-width overlay ───────────────── */
+  @media (max-width: 767px) {
+    /* Collapse sidebar column to 0 on mobile */
+    [data-slot="dashboard-group"] {
+      grid-template-columns: 0 1fr;
+    }
+
+    /* Sidebar switches from grid column to fixed overlay */
+    [data-slot="dashboard-sidebar"] {
+      position: fixed;
+      inset-block: 0;
+      inset-inline-start: 0;
+      z-index: var(--z-sidebar);
+      width: 100dvw;
+      transform: translateX(-100dvw);
+      transition: transform var(--sidebar-duration) var(--ease-out-expo);
+    }
+
+    [data-sidebar-open="true"] [data-slot="dashboard-sidebar"] {
+      transform: translateX(0);
+    }
+
+    /* Inner nav fills the full-width sidebar on mobile */
+    [data-slot="dashboard-sidebar-inner"] {
+      width: 100dvw;
+    }
+
+    /* Scrim: appears behind the sidebar overlay on mobile */
+    [data-sidebar-open="true"] [data-slot="dashboard-scrim"] {
+      display: block;
+      position: fixed;
+      inset: 0;
+      z-index: calc(var(--z-sidebar) - 1);
+      background: oklch(0% 0 0 / 40%);
+    }
+  }
+}

data/app/assets/tailwind/kiso/engine.css

@@ -3,6 +3,18 @@
    that are awkward to express in ERB. Most styling lives in Ruby theme modules
    (lib/kiso/themes/) as computed Tailwind classes. */
 
+@import "./checkbox.css";
+@import "./radio-group.css";
+@import "./color-mode.css";
+@import "./dashboard.css";
+
+/* Scan Kiso's own files so host apps don't need to know the gem's internals.
+   Paths are relative to THIS file (app/assets/tailwind/kiso/engine.css).
+   Count carefully — wrong paths fail SILENTLY (classes just won't generate). */
+@source "../../../views";              /* → app/views              */
+@source "../../../helpers";            /* → app/helpers            */
+@source "../../../../lib/kiso/themes"; /* → lib/kiso/themes        */
+
 /* === Geist Font (by Vercel) ===
    Self-hosted variable fonts — no CDN dependency.
    Licensed under the SIL Open Font License (see OFL.txt).
@@ -30,3 +42,94 @@
   --font-sans: "Geist", ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
   --font-mono: "Geist Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
 }
+
+/* === Semantic Color Tokens ===
+   Purpose-named tokens that flip in dark mode. Components use bg-primary,
+   text-foreground, etc. — never raw palette shades or dark: prefixes.
+
+   Override any token in your app's CSS to retheme:
+     @theme { --color-primary: var(--color-violet-600); }
+*/
+
+@theme {
+  /* Brand / action colors */
+  --color-primary: var(--color-sky-600);
+  --color-primary-foreground: white;
+
+  --color-secondary: var(--color-teal-600);
+  --color-secondary-foreground: white;
+
+  --color-success: var(--color-green-600);
+  --color-success-foreground: white;
+
+  --color-info: var(--color-sky-600);
+  --color-info-foreground: white;
+
+  --color-warning: var(--color-amber-500);
+  --color-warning-foreground: var(--color-amber-950);
+
+  --color-error: var(--color-red-600);
+  --color-error-foreground: white;
+
+  /* Surface tokens */
+  --color-background: white;
+  --color-foreground: var(--color-zinc-950);
+
+  --color-muted: var(--color-zinc-100);
+  --color-muted-foreground: var(--color-zinc-500);
+
+  --color-accent: var(--color-zinc-100);
+  --color-accent-foreground: var(--color-zinc-900);
+
+  --color-inverted: var(--color-zinc-900);
+  --color-inverted-foreground: white;
+  --color-elevated: var(--color-zinc-100);
+  --color-accented: var(--color-zinc-300);
+
+  --color-border: var(--color-zinc-200);
+  --color-border-accented: var(--color-zinc-300);
+
+  --color-ring: var(--color-zinc-400);
+}
+
+/* === Dark Mode ===
+   Redefine tokens under .dark — components never use dark: prefixes. */
+
+.dark {
+  --color-primary: var(--color-blue-400);
+  --color-primary-foreground: var(--color-zinc-950);
+
+  --color-secondary: var(--color-teal-400);
+  --color-secondary-foreground: var(--color-zinc-950);
+
+  --color-success: var(--color-green-400);
+  --color-success-foreground: var(--color-zinc-950);
+
+  --color-info: var(--color-sky-400);
+  --color-info-foreground: var(--color-zinc-950);
+
+  --color-warning: var(--color-amber-400);
+  --color-warning-foreground: var(--color-zinc-950);
+
+  --color-error: var(--color-red-400);
+  --color-error-foreground: var(--color-zinc-950);
+
+  --color-background: var(--color-zinc-950);
+  --color-foreground: var(--color-zinc-50);
+
+  --color-muted: var(--color-zinc-800);
+  --color-muted-foreground: var(--color-zinc-400);
+
+  --color-accent: var(--color-zinc-800);
+  --color-accent-foreground: var(--color-zinc-50);
+
+  --color-inverted: white;
+  --color-inverted-foreground: var(--color-zinc-950);
+  --color-elevated: var(--color-zinc-800);
+  --color-accented: var(--color-zinc-700);
+
+  --color-border: var(--color-zinc-800);
+  --color-border-accented: var(--color-zinc-700);
+
+  --color-ring: var(--color-zinc-600);
+}

data/app/assets/tailwind/kiso/radio-group.css

@@ -0,0 +1,17 @@
+/* RadioGroupItem indicator — CSS ::after for the filled circle dot since
+   native <input type="radio"> can't contain child elements. Uses currentColor
+   which inherits from checked:text-{color}-foreground set by compound variants.
+   Follows the same pattern as Checkbox (mask-image with currentColor). */
+
+[data-radio-group-part="item"] {
+  display: grid;
+  place-content: center;
+}
+
+[data-radio-group-part="item"]:checked::after {
+  content: '';
+  width: 0.5em;
+  height: 0.5em;
+  border-radius: 9999px;
+  background-color: currentColor;
+}

data/app/helpers/kiso/component_helper.rb

@@ -1,36 +1,29 @@
 module Kiso
+  # View helpers for rendering Kiso components.
+  #
+  # Included in all views automatically by {Engine}.
   module ComponentHelper
-    # Renders a component element with data-attribute API.
+    # Renders a Kiso component partial.
     #
-    #   component_tag(:span, :badge, variant: :primary, size: :md) { "Active" }
-    #   # => <span data-component="badge" data-variant="primary" data-size="md">Active</span>
+    # Components live in +app/views/kiso/components/+. Sub-parts are nested
+    # in a directory matching the parent component name.
     #
-    #   component_tag(:div, :card, part: :header) { ... }
-    #   # => <div data-card-part="header">...</div>
+    # @param component [Symbol] the component name (e.g. +:badge+, +:card+)
+    # @param part [Symbol, nil] optional sub-part name (e.g. +:header+, +:footer+)
+    # @param collection [Array, nil] renders the partial once per item when present
+    # @param kwargs [Hash] locals passed to the partial (e.g. +color:+, +variant:+, +css_classes:+)
+    # @yield optional block for component content
+    # @return [ActiveSupport::SafeBuffer] rendered HTML
     #
-    def component_tag(element, component, variant: nil, size: nil, part: nil, **options, &block)
-      data = options.delete(:data) || {}
-
-      if part
-        data[:"#{component}-part"] = part
-      else
-        data[:component] = component
-        data[:variant] = variant if variant
-        data[:size] = size if size
-      end
-
-      options[:data] = data
-
-      content_tag(element, **options, &block)
-    end
-
-    # Renders a Kiso component partial.
+    # @example Render a badge
+    #   kui(:badge, color: :success, variant: :soft) { "Active" }
     #
-    #   kiso(:badge, variant: :success) { "Active" }
-    #   kiso(:card, :header) { ... }
-    #   kiso(:badge, collection: @statuses)
+    # @example Render a card sub-part
+    #   kui(:card, :header) { "Title" }
     #
-    def kiso(component, part = nil, collection: nil, **kwargs, &block)
+    # @example Render a collection
+    #   kui(:badge, collection: @tags)
+    def kui(component, part = nil, collection: nil, **kwargs, &block)
       path = if part
         "kiso/components/#{component}/#{part}"
       else
@@ -38,10 +31,36 @@ module Kiso
       end
 
       if collection
-        render partial: path, collection: collection, **kwargs, &block
+        render partial: path, collection: collection, locals: kwargs, &block
       else
         render path, **kwargs, &block
       end
     end
+
+    # Prepares +component_options+ for use with +content_tag+.
+    #
+    # Sets +data-slot+ for component identity (shadcn v4 convention) and
+    # merges any additional data attributes. Raises if +class:+ is passed
+    # (use +css_classes:+ instead).
+    #
+    # @param component_options [Hash] the +**component_options+ splat from the partial.
+    #   Any +data:+ key is extracted and merged with +slot+ and +data_attrs+.
+    # @param slot [String] the +data-slot+ value (kebab-case, e.g. +"card-header"+)
+    # @param data_attrs [Hash] additional data attributes (e.g. +controller: "kiso--toggle"+)
+    # @return [Hash] merged data attributes hash for +content_tag+
+    # @raise [ArgumentError] if +component_options+ contains a +class:+ key
+    #
+    # @example In a component partial
+    #   data: kiso_prepare_options(component_options, slot: "badge")
+    #
+    # @example With a Stimulus controller
+    #   data: kiso_prepare_options(component_options, slot: "toggle", controller: "kiso--toggle")
+    def kiso_prepare_options(component_options, slot:, **data_attrs)
+      if component_options.key?(:class)
+        raise ArgumentError, "Use css_classes: instead of class: for Kiso components"
+      end
+
+      (component_options.delete(:data) || {}).merge(slot: slot, **data_attrs)
+    end
   end
 end