kiso 0.3.0.pre → 0.4.1.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17ae0456b44e65c4a1f0c0fc7a0fb854daca4af8bf933d13d0fa2a3e78dc0b5d
-  data.tar.gz: 5dad006edca36a6d23822274557de73667eb8bd8aa69aa575037859ed1983742
+  metadata.gz: 2746806e86680de2110a413ce1e6f29b0cc31a080bd1a41de7b5ac07902833cd
+  data.tar.gz: e4bd2a60cf877c765c15b57de4d2743ca4de925a65bd7646ef7783b39d32fbb9
 SHA512:
-  metadata.gz: 490e5777fbc1fd030736c6c7866b3e39855699d7f71be28af41c9fc6bb2cbd7fd6b793d9d302e35886908ce663ddcc98e171ffd1c3419eebf8c6577073276c12
-  data.tar.gz: caa47f1734d26450d7163108cefa70438d75e8ef1201ffc1b4123eb4e5bb5e22aa5f7b545fddad657235d79d18e62aacb05818b6f0aa87922baa20c2d3d66bbb
+  metadata.gz: 28c754958c46ffee194a411b0fe995c99fb8e9fe7bce78a30113063311d690d591f4ac6d2ef3855384fbc71e46562477de4981173eb938cc5318c5339c72253e
+  data.tar.gz: fab0ce827f49744c698ff9522aa68dcca1d64c73ae1ba9a453297d2fbb3ca5f65fa9d06a15830cc6e5f4c1e1b301b8ecdb0aead95ed368423f7f728aa3058cf2

data/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.1.pre] - 2026-03-08
+
+### Added
+
+- `center:` variant on App layout component — `kui(:app, center: true)` applies full-viewport centering for login pages and similar single-focus layouts
+- `kui_tag` / `appui_tag` helpers — collapse the common `content_tag` + `kiso_prepare_options` + theme rendering boilerplate into a single call; component generator templates now use `appui_tag` by default
+- Shade scale auto-wiring — host apps defining `--color-primary-50` through `--color-primary-950` in their Tailwind `@theme` block now automatically feed into Kiso's semantic color tokens (shade 500 for light mode, 400 for dark mode, matching Nuxt UI conventions)
+
+### Fixed
+
+- Palette CSS files are now importable in host apps — a `kiso:palettes` rake task generates CSS stubs so `@import "../builds/tailwind/kiso/palettes/blue.css"` resolves correctly
+
+## [0.4.0.pre] - 2026-03-08
+
+### Added
+
+- Layout component family: App, Container (4 size variants), Header, Footer, Main
+- Page component family: Page (grid with sidebars), PageHeader, PageBody, PageSection, PageGrid, PageCard (4 variants)
+- `appui()` helper for host app components with `app/themes/` and `app/views/components/`
+- `kiso:framework_component` generator for scaffolding engine components
+- `kiso:component` generator for scaffolding host app components
+- Theme presets: `apply_preset(:rounded)` and `apply_preset(:sharp)`
+- 5 OKLCH color palettes (zinc, blue, green, orange, violet)
+- i18n support: all component strings use `t()` with `config/locales/en.yml`
+- [Building Your Own Components](/guide/building-components) guide — how to wrap Kiso components with domain logic and build standalone components with `appui()`, themes, and sub-parts
+- [Detailed release notes](/releases/batch-merge) with upgrade guide and examples for all new features
+
 ## [0.3.0.pre] - 2026-03-03
 
 ### Added
@@ -85,7 +112,9 @@ 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.3.0.pre...HEAD
+[Unreleased]: https://github.com/steveclarke/kiso/compare/v0.4.1.pre...HEAD
+[0.4.1.pre]: https://github.com/steveclarke/kiso/releases/tag/v0.4.1.pre
+[0.4.0.pre]: https://github.com/steveclarke/kiso/releases/tag/v0.4.0.pre
 [0.3.0.pre]: https://github.com/steveclarke/kiso/releases/tag/v0.3.0.pre
 [0.2.2.pre]: https://github.com/steveclarke/kiso/releases/tag/v0.2.2.pre
 [0.2.1.pre]: https://github.com/steveclarke/kiso/releases/tag/v0.2.1.pre

data/README.md

@@ -1,6 +1,19 @@
-# Kiso 基礎
-
-UI components for Rails. Built on ERB, Tailwind CSS, and Hotwire.
+<p align="center">
+  <a href="https://kisoui.com">
+    <img src="brand/svg/logo-horizontal-color.svg" width="280" alt="Kiso">
+  </a>
+</p>
+
+<p align="center">
+  UI components for Rails. Built on ERB, Tailwind CSS, and Hotwire.
+</p>
+
+<p align="center">
+  <a href="https://kisoui.com">Docs</a> ·
+  <a href="https://lookbook.kisoui.com">Lookbook</a> ·
+  <a href="https://github.com/steveclarke/kiso/discussions">Discussions</a> ·
+  <a href="https://discord.gg/aMshcWAW">Discord</a>
+</p>
 
 Add one gem and get badges, buttons, cards, alerts, and more. They all work with screen readers and dark mode.
 

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

@@ -16,7 +16,8 @@
    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        */
+@source "../../../../lib/kiso/themes";  /* → lib/kiso/themes        */
+@source "../../../../lib/kiso/presets"; /* → lib/kiso/presets       */
 
 /* === Geist Font (by Vercel) ===
    Self-hosted variable fonts — no CDN dependency.
@@ -50,29 +51,40 @@
    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); }
+   Two ways to customize brand colors:
+
+   1. Define a shade scale (Tailwind-native):
+        @theme {
+          --color-primary-50:  oklch(...);
+          --color-primary-500: oklch(...);
+          --color-primary-950: oklch(...);
+        }
+      Kiso auto-wires: shade 500 for light mode, shade 400 for dark mode,
+      shade 50 for foreground (light), shade 950 for foreground (dark).
+
+   2. Override the semantic token directly:
+        @theme { --color-primary: oklch(0.55 0.10 237); }
 */
 
 @theme {
-  /* Brand / action colors */
-  --color-primary: var(--color-sky-600);
-  --color-primary-foreground: white;
+  /* Brand / action colors — auto-wire from shade scale, fall back to defaults */
+  --color-primary: var(--color-primary-500, var(--color-rose-500));
+  --color-primary-foreground: var(--color-primary-50, white);
 
-  --color-secondary: var(--color-teal-600);
-  --color-secondary-foreground: white;
+  --color-secondary: var(--color-secondary-500, var(--color-teal-600));
+  --color-secondary-foreground: var(--color-secondary-50, white);
 
-  --color-success: var(--color-green-600);
-  --color-success-foreground: white;
+  --color-success: var(--color-success-500, var(--color-green-600));
+  --color-success-foreground: var(--color-success-50, white);
 
-  --color-info: var(--color-sky-600);
-  --color-info-foreground: white;
+  --color-info: var(--color-info-500, var(--color-sky-600));
+  --color-info-foreground: var(--color-info-50, white);
 
-  --color-warning: var(--color-amber-500);
-  --color-warning-foreground: var(--color-amber-950);
+  --color-warning: var(--color-warning-500, var(--color-amber-500));
+  --color-warning-foreground: var(--color-warning-950, var(--color-amber-950));
 
-  --color-error: var(--color-red-600);
-  --color-error-foreground: white;
+  --color-error: var(--color-error-500, var(--color-red-600));
+  --color-error-foreground: var(--color-error-50, white);
 
   /* Surface tokens */
   --color-background: white;
@@ -99,23 +111,23 @@
    Redefine tokens under .dark — components never use dark: prefixes. */
 
 .dark {
-  --color-primary: var(--color-blue-400);
-  --color-primary-foreground: var(--color-zinc-950);
+  --color-primary: var(--color-primary-400, var(--color-rose-400));
+  --color-primary-foreground: var(--color-primary-950, var(--color-zinc-950));
 
-  --color-secondary: var(--color-teal-400);
-  --color-secondary-foreground: var(--color-zinc-950);
+  --color-secondary: var(--color-secondary-400, var(--color-teal-400));
+  --color-secondary-foreground: var(--color-secondary-950, var(--color-zinc-950));
 
-  --color-success: var(--color-green-400);
-  --color-success-foreground: var(--color-zinc-950);
+  --color-success: var(--color-success-400, var(--color-green-400));
+  --color-success-foreground: var(--color-success-950, var(--color-zinc-950));
 
-  --color-info: var(--color-sky-400);
-  --color-info-foreground: var(--color-zinc-950);
+  --color-info: var(--color-info-400, var(--color-sky-400));
+  --color-info-foreground: var(--color-info-950, var(--color-zinc-950));
 
-  --color-warning: var(--color-amber-400);
-  --color-warning-foreground: var(--color-zinc-950);
+  --color-warning: var(--color-warning-400, var(--color-amber-400));
+  --color-warning-foreground: var(--color-warning-950, var(--color-zinc-950));
 
-  --color-error: var(--color-red-400);
-  --color-error-foreground: var(--color-zinc-950);
+  --color-error: var(--color-error-400, var(--color-red-400));
+  --color-error-foreground: var(--color-error-950, var(--color-zinc-950));
 
   --color-background: var(--color-zinc-950);
   --color-foreground: var(--color-zinc-50);

data/app/assets/tailwind/kiso/palettes/blue.css

@@ -0,0 +1,65 @@
+/* Kiso Color Palette: Blue
+   A professional blue palette — classic SaaS/enterprise feel.
+   Based on shadcn/ui's Blue theme with OKLCH color values.
+
+   Usage:
+     1. Import in your CSS: @import "../builds/tailwind/kiso/palettes/blue.css";
+     2. Add to your HTML: <html data-palette="blue"> or <body data-palette="blue">
+*/
+
+[data-palette="blue"] {
+  /* Brand / action colors — vibrant blue */
+  --color-primary: oklch(0.488 0.243 264.376);
+  --color-primary-foreground: oklch(0.97 0.014 254.604);
+
+  --color-secondary: oklch(0.967 0.001 286.375);
+  --color-secondary-foreground: oklch(0.21 0.006 285.885);
+
+  /* Surface tokens — slate-tinted neutrals */
+  --color-background: oklch(1 0 0);
+  --color-foreground: oklch(0.13 0.028 261.692);
+
+  --color-muted: oklch(0.967 0.003 264.542);
+  --color-muted-foreground: oklch(0.551 0.027 264.364);
+
+  --color-accent: oklch(0.967 0.003 264.542);
+  --color-accent-foreground: oklch(0.21 0.034 264.665);
+
+  --color-inverted: oklch(0.21 0.034 264.665);
+  --color-inverted-foreground: oklch(0.985 0.002 247.839);
+  --color-elevated: oklch(0.967 0.003 264.542);
+  --color-accented: oklch(0.707 0.022 261.325);
+
+  --color-border: oklch(0.928 0.006 264.531);
+  --color-border-accented: oklch(0.707 0.022 261.325);
+
+  --color-ring: oklch(0.488 0.243 264.376);
+}
+
+.dark [data-palette="blue"],
+[data-palette="blue"].dark {
+  --color-primary: oklch(0.42 0.18 266);
+  --color-primary-foreground: oklch(0.97 0.014 254.604);
+
+  --color-secondary: oklch(0.274 0.006 286.033);
+  --color-secondary-foreground: oklch(0.985 0 0);
+
+  --color-background: oklch(0.13 0.028 261.692);
+  --color-foreground: oklch(0.985 0.002 247.839);
+
+  --color-muted: oklch(0.278 0.033 256.848);
+  --color-muted-foreground: oklch(0.707 0.022 261.325);
+
+  --color-accent: oklch(0.278 0.033 256.848);
+  --color-accent-foreground: oklch(0.985 0.002 247.839);
+
+  --color-inverted: oklch(0.985 0.002 247.839);
+  --color-inverted-foreground: oklch(0.21 0.034 264.665);
+  --color-elevated: oklch(0.278 0.033 256.848);
+  --color-accented: oklch(0.551 0.027 264.364);
+
+  --color-border: oklch(0.278 0.033 256.848);
+  --color-border-accented: oklch(0.551 0.027 264.364);
+
+  --color-ring: oklch(0.488 0.243 264.376);
+}

data/app/assets/tailwind/kiso/palettes/green.css

@@ -0,0 +1,65 @@
+/* Kiso Color Palette: Green
+   A fresh, natural green palette — great for eco, health, or finance apps.
+   Based on shadcn/ui's Green theme with OKLCH color values.
+
+   Usage:
+     1. Import in your CSS: @import "../builds/tailwind/kiso/palettes/green.css";
+     2. Add to your HTML: <html data-palette="green"> or <body data-palette="green">
+*/
+
+[data-palette="green"] {
+  /* Brand / action colors — vivid green */
+  --color-primary: oklch(0.648 0.2 131.684);
+  --color-primary-foreground: oklch(0.986 0.031 120.757);
+
+  --color-secondary: oklch(0.967 0.001 286.375);
+  --color-secondary-foreground: oklch(0.21 0.006 285.885);
+
+  /* Surface tokens — zinc neutrals */
+  --color-background: oklch(1 0 0);
+  --color-foreground: oklch(0.141 0.005 285.823);
+
+  --color-muted: oklch(0.967 0.001 286.375);
+  --color-muted-foreground: oklch(0.552 0.016 285.938);
+
+  --color-accent: oklch(0.967 0.001 286.375);
+  --color-accent-foreground: oklch(0.21 0.006 285.885);
+
+  --color-inverted: oklch(0.21 0.006 285.885);
+  --color-inverted-foreground: oklch(0.985 0 0);
+  --color-elevated: oklch(0.967 0.001 286.375);
+  --color-accented: oklch(0.705 0.015 286.067);
+
+  --color-border: oklch(0.92 0.004 286.32);
+  --color-border-accented: oklch(0.705 0.015 286.067);
+
+  --color-ring: oklch(0.648 0.2 131.684);
+}
+
+.dark [data-palette="green"],
+[data-palette="green"].dark {
+  --color-primary: oklch(0.648 0.2 131.684);
+  --color-primary-foreground: oklch(0.986 0.031 120.757);
+
+  --color-secondary: oklch(0.274 0.006 286.033);
+  --color-secondary-foreground: oklch(0.985 0 0);
+
+  --color-background: oklch(0.141 0.005 285.823);
+  --color-foreground: oklch(0.985 0 0);
+
+  --color-muted: oklch(0.274 0.006 286.033);
+  --color-muted-foreground: oklch(0.705 0.015 286.067);
+
+  --color-accent: oklch(0.274 0.006 286.033);
+  --color-accent-foreground: oklch(0.985 0 0);
+
+  --color-inverted: oklch(0.985 0 0);
+  --color-inverted-foreground: oklch(0.21 0.006 285.885);
+  --color-elevated: oklch(0.274 0.006 286.033);
+  --color-accented: oklch(0.552 0.016 285.938);
+
+  --color-border: oklch(0.274 0.006 286.033);
+  --color-border-accented: oklch(0.552 0.016 285.938);
+
+  --color-ring: oklch(0.648 0.2 131.684);
+}

data/app/assets/tailwind/kiso/palettes/orange.css

@@ -0,0 +1,65 @@
+/* Kiso Color Palette: Orange
+   A warm, energetic palette — great for creative, food, or community apps.
+   Based on shadcn/ui's Orange theme with OKLCH color values.
+
+   Usage:
+     1. Import in your CSS: @import "../builds/tailwind/kiso/palettes/orange.css";
+     2. Add to your HTML: <html data-palette="orange"> or <body data-palette="orange">
+*/
+
+[data-palette="orange"] {
+  /* Brand / action colors — warm orange */
+  --color-primary: oklch(0.646 0.222 41.116);
+  --color-primary-foreground: oklch(0.98 0.016 73.684);
+
+  --color-secondary: oklch(0.97 0.001 106.424);
+  --color-secondary-foreground: oklch(0.216 0.006 56.043);
+
+  /* Surface tokens — warm stone neutrals */
+  --color-background: oklch(1 0 0);
+  --color-foreground: oklch(0.147 0.004 49.25);
+
+  --color-muted: oklch(0.97 0.001 106.424);
+  --color-muted-foreground: oklch(0.553 0.013 58.071);
+
+  --color-accent: oklch(0.97 0.001 106.424);
+  --color-accent-foreground: oklch(0.216 0.006 56.043);
+
+  --color-inverted: oklch(0.216 0.006 56.043);
+  --color-inverted-foreground: oklch(0.985 0.001 106.423);
+  --color-elevated: oklch(0.97 0.001 106.424);
+  --color-accented: oklch(0.709 0.01 56.259);
+
+  --color-border: oklch(0.923 0.003 48.717);
+  --color-border-accented: oklch(0.709 0.01 56.259);
+
+  --color-ring: oklch(0.646 0.222 41.116);
+}
+
+.dark [data-palette="orange"],
+[data-palette="orange"].dark {
+  --color-primary: oklch(0.705 0.213 47.604);
+  --color-primary-foreground: oklch(0.98 0.016 73.684);
+
+  --color-secondary: oklch(0.268 0.007 34.298);
+  --color-secondary-foreground: oklch(0.985 0.001 106.423);
+
+  --color-background: oklch(0.147 0.004 49.25);
+  --color-foreground: oklch(0.985 0.001 106.423);
+
+  --color-muted: oklch(0.268 0.007 34.298);
+  --color-muted-foreground: oklch(0.709 0.01 56.259);
+
+  --color-accent: oklch(0.268 0.007 34.298);
+  --color-accent-foreground: oklch(0.985 0.001 106.423);
+
+  --color-inverted: oklch(0.985 0.001 106.423);
+  --color-inverted-foreground: oklch(0.216 0.006 56.043);
+  --color-elevated: oklch(0.268 0.007 34.298);
+  --color-accented: oklch(0.553 0.013 58.071);
+
+  --color-border: oklch(0.268 0.007 34.298);
+  --color-border-accented: oklch(0.553 0.013 58.071);
+
+  --color-ring: oklch(0.705 0.213 47.604);
+}

data/app/assets/tailwind/kiso/palettes/violet.css

@@ -0,0 +1,65 @@
+/* Kiso Color Palette: Violet
+   A rich, creative purple palette — great for design tools or premium brands.
+   Based on shadcn/ui's Violet theme with OKLCH color values.
+
+   Usage:
+     1. Import in your CSS: @import "../builds/tailwind/kiso/palettes/violet.css";
+     2. Add to your HTML: <html data-palette="violet"> or <body data-palette="violet">
+*/
+
+[data-palette="violet"] {
+  /* Brand / action colors — vivid violet */
+  --color-primary: oklch(0.541 0.281 293.009);
+  --color-primary-foreground: oklch(0.969 0.016 293.756);
+
+  --color-secondary: oklch(0.967 0.001 286.375);
+  --color-secondary-foreground: oklch(0.21 0.006 285.885);
+
+  /* Surface tokens — gray neutrals */
+  --color-background: oklch(1 0 0);
+  --color-foreground: oklch(0.13 0.028 261.692);
+
+  --color-muted: oklch(0.967 0.003 264.542);
+  --color-muted-foreground: oklch(0.551 0.027 264.364);
+
+  --color-accent: oklch(0.967 0.003 264.542);
+  --color-accent-foreground: oklch(0.21 0.034 264.665);
+
+  --color-inverted: oklch(0.21 0.034 264.665);
+  --color-inverted-foreground: oklch(0.985 0.002 247.839);
+  --color-elevated: oklch(0.967 0.003 264.542);
+  --color-accented: oklch(0.707 0.022 261.325);
+
+  --color-border: oklch(0.928 0.006 264.531);
+  --color-border-accented: oklch(0.707 0.022 261.325);
+
+  --color-ring: oklch(0.541 0.281 293.009);
+}
+
+.dark [data-palette="violet"],
+[data-palette="violet"].dark {
+  --color-primary: oklch(0.606 0.25 292.717);
+  --color-primary-foreground: oklch(0.969 0.016 293.756);
+
+  --color-secondary: oklch(0.274 0.006 286.033);
+  --color-secondary-foreground: oklch(0.985 0 0);
+
+  --color-background: oklch(0.13 0.028 261.692);
+  --color-foreground: oklch(0.985 0.002 247.839);
+
+  --color-muted: oklch(0.278 0.033 256.848);
+  --color-muted-foreground: oklch(0.707 0.022 261.325);
+
+  --color-accent: oklch(0.278 0.033 256.848);
+  --color-accent-foreground: oklch(0.985 0.002 247.839);
+
+  --color-inverted: oklch(0.985 0.002 247.839);
+  --color-inverted-foreground: oklch(0.21 0.034 264.665);
+  --color-elevated: oklch(0.278 0.033 256.848);
+  --color-accented: oklch(0.551 0.027 264.364);
+
+  --color-border: oklch(0.278 0.033 256.848);
+  --color-border-accented: oklch(0.551 0.027 264.364);
+
+  --color-ring: oklch(0.606 0.25 292.717);
+}

data/app/assets/tailwind/kiso/palettes/zinc.css

@@ -0,0 +1,65 @@
+/* Kiso Color Palette: Zinc
+   A neutral, cool-toned palette using the Zinc scale.
+   Based on shadcn/ui's Zinc theme with OKLCH color values.
+
+   Usage:
+     1. Import in your CSS: @import "../builds/tailwind/kiso/palettes/zinc.css";
+     2. Add to your HTML: <html data-palette="zinc"> or <body data-palette="zinc">
+*/
+
+[data-palette="zinc"] {
+  /* Brand / action colors — zinc primary (near-black in light, near-white in dark) */
+  --color-primary: oklch(0.21 0.006 285.885);
+  --color-primary-foreground: oklch(0.985 0 0);
+
+  --color-secondary: oklch(0.967 0.001 286.375);
+  --color-secondary-foreground: oklch(0.21 0.006 285.885);
+
+  /* Surface tokens */
+  --color-background: oklch(1 0 0);
+  --color-foreground: oklch(0.141 0.005 285.823);
+
+  --color-muted: oklch(0.967 0.001 286.375);
+  --color-muted-foreground: oklch(0.552 0.016 285.938);
+
+  --color-accent: oklch(0.967 0.001 286.375);
+  --color-accent-foreground: oklch(0.21 0.006 285.885);
+
+  --color-inverted: oklch(0.21 0.006 285.885);
+  --color-inverted-foreground: oklch(0.985 0 0);
+  --color-elevated: oklch(0.967 0.001 286.375);
+  --color-accented: oklch(0.705 0.015 286.067);
+
+  --color-border: oklch(0.92 0.004 286.32);
+  --color-border-accented: oklch(0.705 0.015 286.067);
+
+  --color-ring: oklch(0.705 0.015 286.067);
+}
+
+.dark [data-palette="zinc"],
+[data-palette="zinc"].dark {
+  --color-primary: oklch(0.92 0.004 286.32);
+  --color-primary-foreground: oklch(0.21 0.006 285.885);
+
+  --color-secondary: oklch(0.274 0.006 286.033);
+  --color-secondary-foreground: oklch(0.985 0 0);
+
+  --color-background: oklch(0.141 0.005 285.823);
+  --color-foreground: oklch(0.985 0 0);
+
+  --color-muted: oklch(0.274 0.006 286.033);
+  --color-muted-foreground: oklch(0.705 0.015 286.067);
+
+  --color-accent: oklch(0.274 0.006 286.033);
+  --color-accent-foreground: oklch(0.985 0 0);
+
+  --color-inverted: oklch(0.985 0 0);
+  --color-inverted-foreground: oklch(0.21 0.006 285.885);
+  --color-elevated: oklch(0.274 0.006 286.033);
+  --color-accented: oklch(0.552 0.016 285.938);
+
+  --color-border: oklch(0.274 0.006 286.033);
+  --color-border-accented: oklch(0.552 0.016 285.938);
+
+  --color-ring: oklch(0.552 0.016 285.938);
+}

data/app/helpers/kiso/app_component_helper.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Kiso
+  # View helpers for rendering host app components.
+  #
+  # Mirrors {ComponentHelper#kui} but resolves partials from
+  # +app/views/components/+ and themes from +AppThemes::+.
+  # No global config layer — host apps own the source directly.
+  #
+  # Included in all views automatically by {Engine}.
+  module AppComponentHelper
+    # Renders a host app component partial.
+    #
+    # Components live in +app/views/components/+. Sub-parts are nested
+    # in a directory matching the parent component name.
+    #
+    # @param component [Symbol] the component name (e.g. +:pricing_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 ui [Hash{Symbol => String}, nil] per-slot class overrides keyed by sub-part name.
+    #   For parent components, the hash is pushed onto a context stack so sub-parts
+    #   inherit overrides automatically. For self-rendering components, the hash is
+    #   also passed as a local so the partial can apply overrides to internally
+    #   rendered elements.
+    # @param kwargs [Hash] locals passed to the partial (e.g. +css_classes:+)
+    # @yield optional block for component content
+    # @return [ActiveSupport::SafeBuffer] rendered HTML
+    #
+    # @example Render a pricing card
+    #   appui(:pricing_card) { "Content" }
+    #
+    # @example Render a pricing card with sub-parts
+    #   appui(:pricing_card) do
+    #     appui(:pricing_card, :header) { "Header" }
+    #   end
+    #
+    # @example Render with per-slot overrides
+    #   appui(:pricing_card, ui: { header: "p-8" }) do
+    #     appui(:pricing_card, :header) { "Header" }
+    #   end
+    #
+    # @example Render a collection
+    #   appui(:pricing_card, collection: @plans)
+    def appui(component, part = nil, collection: nil, ui: nil, **kwargs, &block)
+      kiso_render_component(
+        component, part,
+        path_prefix: "components",
+        collection: collection, ui: ui, merge_global_ui: false,
+        **kwargs, &block
+      )
+    end
+
+    # Renders a themed HTML element for host app components.
+    #
+    # Identical to {ComponentHelper#kui_tag} — provided as a naming
+    # convenience so host app partials use +appui_tag+ alongside +appui()+.
+    #
+    # @see ComponentHelper#kui_tag
+    def appui_tag(...)
+      kui_tag(...)
+    end
+  end
+end