kiso 0.4.1.pre → 0.4.2.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2746806e86680de2110a413ce1e6f29b0cc31a080bd1a41de7b5ac07902833cd
-  data.tar.gz: e4bd2a60cf877c765c15b57de4d2743ca4de925a65bd7646ef7783b39d32fbb9
+  metadata.gz: 4e7e4247e68272499ab572c3aa2ed94ad54860cf075f0b4e3240a1b11fd909d6
+  data.tar.gz: 87e9710cb6428055adad01d89a4357e735ac5c8b326c547b01d696d208501cf8
 SHA512:
-  metadata.gz: 28c754958c46ffee194a411b0fe995c99fb8e9fe7bce78a30113063311d690d591f4ac6d2ef3855384fbc71e46562477de4981173eb938cc5318c5339c72253e
-  data.tar.gz: fab0ce827f49744c698ff9522aa68dcca1d64c73ae1ba9a453297d2fbb3ca5f65fa9d06a15830cc6e5f4c1e1b301b8ecdb0aead95ed368423f7f728aa3058cf2
+  metadata.gz: 9f0842c23bdf92f06c826614ac8eb81d427eb136ea5fa2d6f735886387790cccda7943d450e8e771a7405cb9d6017eb2c1a5b00386b499b2c079ff933b520ec2
+  data.tar.gz: 1322bed3abb54da45bb4163e7fa5ca5919efbb6af07f505606dc17e65ac100f5fbc6d438e336347bdb44a09f70a2a7f3c413df876ace869adcd2b7a758ee725a

data/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.2.pre] - 2026-03-08
+
+### Added
+
+- `scope:` prop for sharing domain locals from parent components to sub-parts — `appui(:room_card, scope: { room: room })` makes `room:` available to all sub-parts automatically without repeating it on every call. Explicit kwargs on sub-part calls override scope values. One level deep only (parent to its own sub-parts).
+
 ## [0.4.1.pre] - 2026-03-08
 
 ### Added
@@ -112,7 +118,8 @@ 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.4.1.pre...HEAD
+[Unreleased]: https://github.com/steveclarke/kiso/compare/v0.4.2.pre...HEAD
+[0.4.2.pre]: https://github.com/steveclarke/kiso/releases/tag/v0.4.2.pre
 [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

data/app/helpers/kiso/app_component_helper.rb

@@ -22,6 +22,9 @@ module Kiso
     #   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 scope [Hash, nil] domain locals shared from parent to sub-parts via context stack.
+    #   Sub-parts receive scope values as kwargs automatically. Explicit kwargs on sub-part
+    #   calls override scope values. One level deep only — no ancestor resolution.
     # @param kwargs [Hash] locals passed to the partial (e.g. +css_classes:+)
     # @yield optional block for component content
     # @return [ActiveSupport::SafeBuffer] rendered HTML
@@ -39,13 +42,19 @@ module Kiso
     #     appui(:pricing_card, :header) { "Header" }
     #   end
     #
+    # @example Share domain locals with sub-parts
+    #   appui(:room_card, scope: { room: room }) do
+    #     appui(:room_card, :status)
+    #     appui(:room_card, :meta)
+    #   end
+    #
     # @example Render a collection
     #   appui(:pricing_card, collection: @plans)
-    def appui(component, part = nil, collection: nil, ui: nil, **kwargs, &block)
+    def appui(component, part = nil, collection: nil, ui: nil, scope: nil, **kwargs, &block)
       kiso_render_component(
         component, part,
         path_prefix: "components",
-        collection: collection, ui: ui, merge_global_ui: false,
+        collection: collection, ui: ui, scope: scope, merge_global_ui: false,
         **kwargs, &block
       )
     end

data/app/helpers/kiso/component_helper.rb

@@ -16,6 +16,9 @@ module Kiso
     #   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 scope [Hash, nil] domain locals shared from parent to sub-parts via context stack.
+    #   Sub-parts receive scope values as kwargs automatically. Explicit kwargs on sub-part
+    #   calls override scope values. One level deep only — no ancestor resolution.
     # @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
@@ -33,13 +36,18 @@ module Kiso
     # @example Render an alert with inner element overrides
     #   kui(:alert, icon: "info", ui: { close: "opacity-50" })
     #
+    # @example Share domain locals with sub-parts
+    #   kui(:card, scope: { project: @project }) do
+    #     kui(:card, :header) # sub-part receives project: automatically
+    #   end
+    #
     # @example Render a collection
     #   kui(:badge, collection: @tags)
-    def kui(component, part = nil, collection: nil, ui: nil, **kwargs, &block)
+    def kui(component, part = nil, collection: nil, ui: nil, scope: nil, **kwargs, &block)
       kiso_render_component(
         component, part,
         path_prefix: "kiso/components",
-        collection: collection, ui: ui, merge_global_ui: true,
+        collection: collection, ui: ui, scope: scope, merge_global_ui: true,
         **kwargs, &block
       )
     end
@@ -109,11 +117,12 @@ module Kiso
     # @param path_prefix [String] partial path prefix (e.g. "kiso/components" or "components")
     # @param collection [Array, nil] renders the partial once per item when present
     # @param ui [Hash, nil] per-slot class overrides
+    # @param scope [Hash, nil] domain locals shared from parent to sub-parts
     # @param merge_global_ui [Boolean] whether to merge global config ui layer
     # @param kwargs [Hash] locals passed to the partial
     # @param block [Proc] optional block for component content
     # @return [ActiveSupport::SafeBuffer] rendered HTML
-    def kiso_render_component(component, part, path_prefix:, collection:, ui:, merge_global_ui: true, **kwargs, &block)
+    def kiso_render_component(component, part, path_prefix:, collection:, ui:, scope:, merge_global_ui: true, **kwargs, &block)
       path = if part
         "#{path_prefix}/#{component}/#{part}"
       else
@@ -131,6 +140,10 @@ module Kiso
       block ||= proc {}
 
       if part
+        # Sub-part: merge scope from parent context (scope values first, explicit kwargs win)
+        parent_scope = kiso_current_scope(component)
+        kwargs = parent_scope.merge(kwargs) if parent_scope.present?
+
         # Sub-part: merge slot override from parent's ui context
         parent_ui = kiso_current_ui(component)
         if (slot_classes = parent_ui[part].presence)
@@ -154,9 +167,11 @@ module Kiso
           ui || {}
         end
         has_ui = merged_ui.present?
+        has_scope = scope.present?
 
         # Push context for composed sub-parts to read (skip when empty)
         kiso_push_ui_context(component, merged_ui) if has_ui
+        kiso_push_scope(component, scope) if has_scope
         begin
           locals = has_ui ? kwargs.merge(ui: merged_ui) : kwargs
 
@@ -167,6 +182,7 @@ module Kiso
           end
         ensure
           kiso_pop_ui_context(component) if has_ui
+          kiso_pop_scope(component) if has_scope
         end
       end
     end

data/app/helpers/kiso/ui_context_helper.rb

@@ -1,17 +1,22 @@
 # frozen_string_literal: true
 
 module Kiso
-  # Manages a request-scoped context stack for per-slot +ui:+ overrides.
+  # Manages request-scoped context stacks for component communication.
   #
-  # This is ERB's equivalent of Vue's provide/inject pattern. When a parent
-  # component is rendered with +ui:+, the hash is pushed onto a stack.
-  # Sub-parts rendered inside the parent's block read their slot override
-  # from the stack automatically.
+  # This is ERB's equivalent of Vue's provide/inject pattern. Two stacks:
+  #
+  # - **ui:** — per-slot CSS class overrides. When a parent component is
+  #   rendered with +ui:+, the hash is pushed onto a stack. Sub-parts read
+  #   their slot override automatically.
+  # - **scope:** — domain locals shared from parent to sub-parts. When a
+  #   parent is rendered with +scope:+, the hash is pushed onto a stack.
+  #   Sub-parts receive scope values as kwargs, with explicit kwargs
+  #   taking priority. One level deep only — no ancestor resolution.
   #
   # Thread-safe because Rails creates a fresh view context (and therefore
   # fresh instance variables) per request.
   #
-  # @example How the stack flows
+  # @example ui: stack flow
   #   # Parent pushes:
   #   kiso_push_ui_context(:card, { header: "p-8", title: "text-xl" })
   #
@@ -21,6 +26,16 @@ module Kiso
   #   # After parent renders:
   #   kiso_pop_ui_context(:card)
   #
+  # @example scope: stack flow
+  #   # Parent pushes:
+  #   kiso_push_scope(:room_card, { room: room })
+  #
+  #   # Sub-part reads (merged into kwargs before render):
+  #   kiso_current_scope(:room_card)  #=> { room: room }
+  #
+  #   # After parent renders:
+  #   kiso_pop_scope(:room_card)
+  #
   # @see ComponentHelper#kui
   module UiContextHelper
     # Push a ui hash onto the context stack for a component.
@@ -49,11 +64,45 @@ module Kiso
       kiso_ui_stack.dig(component, -1) || {}
     end
 
+    # Push a scope hash onto the context stack for a component.
+    #
+    # Scope shares domain locals from a parent component with its sub-parts
+    # so callers don't have to repeat the same locals on every sub-part call.
+    #
+    # @param component [Symbol] the component name (e.g. +:room_card+)
+    # @param scope [Hash] domain locals to share with sub-parts
+    # @return [void]
+    def kiso_push_scope(component, scope)
+      kiso_scope_stack[component] ||= []
+      kiso_scope_stack[component].push(scope || {})
+    end
+
+    # Pop the most recent scope hash for a component.
+    #
+    # @param component [Symbol] the component name
+    # @return [Hash, nil] the popped scope hash
+    def kiso_pop_scope(component)
+      kiso_scope_stack[component]&.pop
+    end
+
+    # Read the current scope hash for a component (top of stack).
+    #
+    # @param component [Symbol] the component name
+    # @return [Hash] the current scope, or empty hash
+    def kiso_current_scope(component)
+      kiso_scope_stack.dig(component, -1) || {}
+    end
+
     private
 
-    # @return [Hash{Symbol => Array<Hash>}] per-component stacks
+    # @return [Hash{Symbol => Array<Hash>}] per-component ui stacks
     def kiso_ui_stack
       @kiso_ui_stack ||= {}
     end
+
+    # @return [Hash{Symbol => Array<Hash>}] per-component scope stacks
+    def kiso_scope_stack
+      @kiso_scope_stack ||= {}
+    end
   end
 end

data/lib/kiso/version.rb

@@ -2,5 +2,5 @@
 
 module Kiso
   # @return [String] the current gem version
-  VERSION = "0.4.1.pre"
+  VERSION = "0.4.2.pre"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kiso
 version: !ruby/object:Gem::Version
-  version: 0.4.1.pre
+  version: 0.4.2.pre
 platform: ruby
 authors:
 - Steve Clarke