kiso 0.5.2.pre → 0.6.0.pre

data/lib/kiso/engine.rb

@@ -1,11 +1,17 @@
+# frozen_string_literal: true
+
 module Kiso
   # Rails engine that integrates Kiso into host applications.
   #
   # Registers initializers for:
+  # - i18n locale loading
   # - ClassVariants merger (TailwindMerge for class deduplication)
   # - Global theme overrides ({ThemeOverrides})
-  # - View helpers ({ComponentHelper}, {IconHelper})
+  # - View helpers (+kui()+, +appui()+, +kiso_icon()+, +kiso_theme_script()+)
   # - Importmap and asset pipeline paths
+  # - Propshaft tailwind stub filtering
+  # - Theme hot-reloading in development
+  # - App theme loading from +app/themes/+
   # - Lookbook preview path registration
   class Engine < ::Rails::Engine
     isolate_namespace Kiso
@@ -36,7 +42,8 @@ module Kiso
       Kiso::ThemeOverrides.apply!
     end
 
-    # Makes {ComponentHelper}, {AppComponentHelper}, and {IconHelper} available in all views.
+    # Makes all Kiso view helpers available: {UiContextHelper}, {ComponentHelper},
+    # {AppComponentHelper}, {IconHelper}, and {ThemeHelper}.
     initializer "kiso.helpers" do
       ActiveSupport.on_load(:action_view) do
         include Kiso::UiContextHelper

data/lib/kiso/propshaft_tailwind_stub_filter.rb

@@ -1,11 +1,18 @@
+# frozen_string_literal: true
+
 module Kiso
   # Filters tailwindcss-rails engine CSS stubs from Propshaft's :app stylesheet
-  # resolution. Prepended onto Propshaft::Helper by the engine initializer.
+  # resolution. Prepended onto +Propshaft::Helper+ by the engine initializer.
   #
-  # Engine stubs have logical paths like "tailwind/kiso.css" — always under the
+  # Engine stubs have logical paths like "tailwind/kiso.css" -- always under the
   # "tailwind/" prefix. The compiled output is "tailwind.css" (no slash) and
   # passes through unaffected.
+  #
+  # @see Engine the initializer that prepends this module
   module PropshaftTailwindStubFilter
+    # Filters out Tailwind engine stubs from the list of app stylesheet paths.
+    #
+    # @return [Array<String>] stylesheet logical paths with engine stubs removed
     def app_stylesheets_paths
       super.reject { |path| path.start_with?("tailwind/") }
     end

data/lib/kiso/themes/avatar.rb

@@ -1,5 +1,19 @@
 module Kiso
   module Themes
+    # User avatar with image, fallback initials, optional status badge,
+    # and group layout.
+    #
+    # Supports automatic contrast text color for initials via
+    # {ColorUtils.contrast_text_color} in the partial.
+    #
+    # @example
+    #   Avatar.render(size: :md)
+    #
+    # Variants:
+    # - +size+ -- :xs, :sm, :md (default), :lg, :xl, :2xl
+    #
+    # Sub-parts: {AvatarImage}, {AvatarFallback}, {AvatarBadge},
+    # {AvatarGroup}, {AvatarGroupCount}
     Avatar = ClassVariants.build(
       base: "group/avatar relative flex shrink-0 rounded-full select-none items-center justify-center bg-muted",
       variants: {
@@ -7,16 +21,23 @@ module Kiso
           xs: "size-5",
           sm: "size-6",
           md: "size-8",
-          lg: "size-10"
+          lg: "size-10",
+          xl: "size-16",
+          "2xl": "size-20"
         }
       },
       defaults: {size: :md}
     )
 
+    # The +<img>+ element, absolutely positioned to fill the avatar circle.
     AvatarImage = ClassVariants.build(
       base: "absolute inset-0 aspect-square size-full rounded-full object-cover"
     )
 
+    # Initials or icon shown when no image is provided.
+    #
+    # Variants:
+    # - +size+ -- :xs, :sm, :md (default), :lg, :xl, :2xl (controls font size)
     AvatarFallback = ClassVariants.build(
       base: "flex size-full items-center justify-center rounded-full bg-muted text-muted-foreground font-medium",
       variants: {
@@ -24,35 +45,48 @@ module Kiso
           xs: "text-[10px]",
           sm: "text-xs",
           md: "text-sm",
-          lg: "text-base"
+          lg: "text-base",
+          xl: "text-2xl",
+          "2xl": "text-3xl"
         }
       },
       defaults: {size: :md}
     )
 
+    # Status indicator dot positioned at the bottom-right corner.
+    # Size adapts to the parent avatar via +group-data-[size=*]+ selectors.
     AvatarBadge = ClassVariants.build(
       base: "bg-primary text-primary-foreground ring-background absolute right-0 bottom-0 z-10 " \
             "inline-flex items-center justify-center rounded-full ring-2 select-none " \
             "group-data-[size=xs]/avatar:size-1.5 group-data-[size=xs]/avatar:[&>svg]:hidden " \
             "group-data-[size=sm]/avatar:size-2 group-data-[size=sm]/avatar:[&>svg]:hidden " \
             "group-data-[size=md]/avatar:size-2.5 group-data-[size=md]/avatar:[&>svg]:size-2 " \
-            "group-data-[size=lg]/avatar:size-3 group-data-[size=lg]/avatar:[&>svg]:size-2"
+            "group-data-[size=lg]/avatar:size-3 group-data-[size=lg]/avatar:[&>svg]:size-2 " \
+            "group-data-[size=xl]/avatar:size-4 group-data-[size=xl]/avatar:[&>svg]:size-3 " \
+            "group-data-[size=2xl]/avatar:size-5 group-data-[size=2xl]/avatar:[&>svg]:size-3.5"
     )
 
+    # Overlapping row of avatars with negative spacing.
     AvatarGroup = ClassVariants.build(
       base: "*:data-[slot=avatar]:ring-background group/avatar-group flex -space-x-2 " \
             "*:data-[slot=avatar]:ring-2"
     )
 
+    # "+N" overflow indicator at the end of an {AvatarGroup}.
     AvatarGroupCount = ClassVariants.build(
       base: "bg-muted text-muted-foreground ring-background relative flex size-8 shrink-0 " \
             "items-center justify-center rounded-full text-sm ring-2 " \
             "group-has-data-[size=xs]/avatar-group:size-5 " \
-            "group-has-data-[size=lg]/avatar-group:size-10 " \
             "group-has-data-[size=sm]/avatar-group:size-6 " \
-            "[&>svg]:size-4 group-has-data-[size=lg]/avatar-group:[&>svg]:size-5 " \
+            "group-has-data-[size=lg]/avatar-group:size-10 " \
+            "group-has-data-[size=xl]/avatar-group:size-16 " \
+            "group-has-data-[size=2xl]/avatar-group:size-20 " \
+            "[&>svg]:size-4 " \
             "group-has-data-[size=xs]/avatar-group:[&>svg]:size-2.5 " \
-            "group-has-data-[size=sm]/avatar-group:[&>svg]:size-3"
+            "group-has-data-[size=sm]/avatar-group:[&>svg]:size-3 " \
+            "group-has-data-[size=lg]/avatar-group:[&>svg]:size-5 " \
+            "group-has-data-[size=xl]/avatar-group:[&>svg]:size-6 " \
+            "group-has-data-[size=2xl]/avatar-group:[&>svg]:size-7"
     )
   end
 end

data/lib/kiso/themes/badge.rb

@@ -1,6 +1,10 @@
 module Kiso
   module Themes
-    # @return [Array<Symbol>] the seven semantic colors available to all colored components
+    # The seven semantic colors shared by all colored components.
+    # Used by compound variant definitions in Badge, Alert, Button, Checkbox,
+    # RadioGroup, Switch, and others.
+    #
+    # @return [Array<Symbol>]
     COLORS = %i[primary secondary success info warning error neutral].freeze
 
     # Inline badge for status labels, counts, and tags.

data/lib/kiso/themes/color_mode_button.rb

@@ -1,5 +1,16 @@
 module Kiso
   module Themes
+    # Light/dark mode toggle button with sun and moon icons.
+    #
+    # Uses the +kiso--theme+ Stimulus controller to cycle between
+    # light and dark modes. Icon visibility is controlled via CSS
+    # (see +color-mode-button.css+).
+    #
+    # @example
+    #   ColorModeButton.render(size: :md)
+    #
+    # Variants:
+    # - +size+ -- :sm, :md (default), :lg
     ColorModeButton = ClassVariants.build(
       base: "inline-flex items-center justify-center rounded-md text-foreground/50 hover:text-foreground hover:bg-accent transition-colors duration-150 shrink-0 cursor-pointer",
       variants: {

data/lib/kiso/themes/color_mode_select.rb

@@ -1,5 +1,12 @@
 module Kiso
   module Themes
+    # Dropdown select for choosing between Light, Dark, and System color modes.
+    #
+    # Wraps a {SelectNative} element with the +kiso--theme+ Stimulus controller.
+    # No variants -- styling is handled by the inner select component.
+    #
+    # @example
+    #   ColorModeSelect.render
     ColorModeSelect = ClassVariants.build(
       base: ""
     )

data/lib/kiso/themes/dashboard.rb

@@ -1,49 +1,77 @@
 module Kiso
   module Themes
+    # Dashboard layout system -- composable components for admin/app shells.
+    #
+    # The dashboard uses CSS Grid for layout with a sidebar, navbar, and
+    # main content panel. CSS mechanics (grid tracks, sidebar animation,
+    # mobile overlay) live in +dashboard.css+ using +[data-slot]+ selectors.
+    # Sidebar state is persisted via cookies.
+    #
+    # @example
+    #   DashboardGroup.render
+    #
+    # Sub-parts: {DashboardNavbar}, {DashboardNavbarToggle}, {DashboardSidebar},
+    # {DashboardPanel}, {DashboardSidebarHeader}, {DashboardSidebarFooter},
+    # {DashboardSidebarToggle}, {DashboardSidebarCollapse}, {DashboardToolbar},
+    # {DashboardToolbarLeft}, {DashboardToolbarRight}
+
+    # Root grid container spanning the full viewport height.
     DashboardGroup = ClassVariants.build(
       base: "grid h-dvh overflow-hidden bg-background text-foreground antialiased"
     )
 
+    # Top navigation bar with border-bottom separator.
     DashboardNavbar = ClassVariants.build(
       base: "flex items-center gap-3 px-4 border-b border-border bg-background shrink-0 z-(--z-topbar)"
     )
 
+    # Icon button inside the navbar (e.g., sidebar toggle, color mode).
     DashboardNavbarToggle = ClassVariants.build(
       base: "flex items-center justify-center w-8 h-8 rounded-md text-foreground/50 hover:text-foreground hover:bg-accent transition-colors duration-150 shrink-0 [&>svg]:size-4"
     )
 
+    # Collapsible side panel for navigation. Width and animation
+    # controlled by CSS custom properties in +dashboard.css+.
     DashboardSidebar = ClassVariants.build(
       base: "overflow-hidden"
     )
 
+    # Scrollable main content area beside the sidebar.
     DashboardPanel = ClassVariants.build(
       base: "min-w-0 overflow-y-auto bg-background"
     )
 
+    # Top section of the sidebar (e.g., logo, search).
     DashboardSidebarHeader = ClassVariants.build(
       base: "shrink-0 flex flex-col gap-2 p-2"
     )
 
+    # Bottom section of the sidebar (e.g., user menu).
     DashboardSidebarFooter = ClassVariants.build(
       base: "shrink-0 flex flex-col gap-2 p-2"
     )
 
+    # Mobile-only button to open/close the sidebar overlay.
     DashboardSidebarToggle = ClassVariants.build(
       base: "lg:hidden flex items-center justify-center w-8 h-8 rounded-md text-foreground/50 hover:text-foreground hover:bg-accent transition-colors duration-150 shrink-0 cursor-pointer [&>svg]:size-4"
     )
 
+    # Desktop-only button to collapse the sidebar to icon-only width.
     DashboardSidebarCollapse = ClassVariants.build(
       base: "hidden lg:flex items-center justify-center w-8 h-8 rounded-md text-foreground/50 hover:text-foreground hover:bg-accent transition-colors duration-150 shrink-0 cursor-pointer [&>svg]:size-4"
     )
 
+    # Secondary toolbar below the navbar with left/right content slots.
     DashboardToolbar = ClassVariants.build(
       base: "shrink-0 flex items-center justify-between border-b border-border px-4 sm:px-6 gap-1.5 overflow-x-auto h-(--topbar-height)"
     )
 
+    # Left-aligned content area within {DashboardToolbar}.
     DashboardToolbarLeft = ClassVariants.build(
       base: "flex items-center gap-1.5"
     )
 
+    # Right-aligned content area within {DashboardToolbar}.
     DashboardToolbarRight = ClassVariants.build(
       base: "flex items-center gap-1.5"
     )

data/lib/kiso/themes/dropdown_menu.rb

@@ -21,7 +21,7 @@ module Kiso
 
     # The dropdown panel containing menu items.
     DropdownMenuContent = ClassVariants.build(
-      base: "bg-background text-foreground z-50 min-w-32 " \
+      base: "bg-background text-foreground z-50 min-w-32 whitespace-nowrap " \
             "overflow-x-hidden overflow-y-auto rounded-md ring ring-inset ring-border p-1 shadow-md"
     )
 
@@ -101,7 +101,7 @@ module Kiso
 
     # Panel for nested sub-menu items (same as {DropdownMenuContent} but +shadow-lg+).
     DropdownMenuSubContent = ClassVariants.build(
-      base: "bg-background text-foreground z-50 min-w-32 " \
+      base: "bg-background text-foreground z-50 min-w-32 whitespace-nowrap " \
             "overflow-hidden rounded-md ring ring-inset ring-border p-1 shadow-lg"
     )
   end

data/lib/kiso/themes/input_otp.rb

@@ -9,16 +9,19 @@ module Kiso
       base: "relative text-foreground flex items-center gap-2 has-disabled:opacity-50"
     )
 
-    # Groups adjacent slots visually (e.g., first 3 digits, last 3 digits).
+    # Groups adjacent {InputOtpSlot} elements visually (e.g., first 3 digits, last 3 digits).
     InputOtpGroup = ClassVariants.build(
       base: "flex items-center"
     )
 
     # Individual character display slot with connected borders.
-    # Content and active state managed by +kiso--input-otp+ controller.
+    # Content and active state managed by the +kiso--input-otp+ Stimulus controller.
     #
     # @example
     #   InputOtpSlot.render(size: :md)
+    #
+    # Variants:
+    # - +size+ -- :sm, :md (default), :lg
     InputOtpSlot = ClassVariants.build(
       base: "border-border relative flex items-center justify-center " \
             "border -ml-px shadow-xs transition-all outline-none " \
@@ -38,7 +41,7 @@ module Kiso
       defaults: {size: :md}
     )
 
-    # Separator between groups (renders a minus icon by default).
+    # Visual separator between {InputOtpGroup} elements (renders a minus icon by default).
     InputOtpSeparator = ClassVariants.build(
       base: "flex items-center text-muted-foreground [&>svg]:size-4"
     )

data/lib/kiso/themes/nav.rb

@@ -1,25 +1,42 @@
 module Kiso
   module Themes
+    # Sidebar navigation menu with collapsible sections.
+    #
+    # Designed for use inside {DashboardSidebar}. Sections use native
+    # +<details>+ elements for expand/collapse without JavaScript.
+    #
+    # @example
+    #   Nav.render
+    #
+    # Sub-parts: {NavSection}, {NavSectionTitle}, {NavSectionContent},
+    # {NavItem}, {NavItemBadge}
+
+    # Root navigation container.
     Nav = ClassVariants.build(
       base: "flex flex-col gap-2"
     )
 
+    # Collapsible group of related navigation items.
     NavSection = ClassVariants.build(
       base: "relative flex w-full min-w-0 flex-col gap-1 p-2"
     )
 
+    # Section heading that acts as the +<summary>+ toggle for a +<details>+ element.
     NavSectionTitle = ClassVariants.build(
       base: "flex h-8 shrink-0 items-center rounded-md px-2 text-xs font-medium text-muted-foreground cursor-pointer select-none list-none [&::-webkit-details-marker]:hidden"
     )
 
+    # Container for the list of {NavItem} elements inside a section.
     NavSectionContent = ClassVariants.build(
       base: "flex w-full min-w-0 flex-col gap-1 text-sm"
     )
 
+    # Individual navigation link. Highlights via +data-[active=true]+.
     NavItem = ClassVariants.build(
       base: "group relative w-full flex items-center gap-2 rounded-md px-2 py-1.5 text-left text-sm outline-hidden transition-colors hover:bg-accent hover:text-accent-foreground focus-visible:ring-2 focus-visible:ring-ring data-[active=true]:bg-accent data-[active=true]:font-medium data-[active=true]:text-accent-foreground [&>svg]:size-4 [&>svg]:shrink-0"
     )
 
+    # Counter or status badge aligned to the right side of a {NavItem}.
     NavItemBadge = ClassVariants.build(
       base: "ms-auto pointer-events-none flex h-5 min-w-5 items-center justify-center rounded-md px-1 text-xs font-medium tabular-nums select-none"
     )

data/lib/kiso/themes/pagination.rb

@@ -1,7 +1,9 @@
 module Kiso
   module Themes
-    # @return [String] shared base classes for all pagination link-type elements.
-    #   Matches shadcn's buttonVariants base (ghost/outline neutral).
+    # Shared base classes for all pagination link-type elements.
+    # Matches shadcn's buttonVariants base (ghost/outline neutral).
+    #
+    # @return [String]
     PAGINATION_LINK_BASE = "inline-flex items-center justify-center whitespace-nowrap rounded-md " \
                            "text-sm font-medium transition-all " \
                            "focus-visible:outline-2 focus-visible:outline-offset-2 " \
@@ -9,8 +11,11 @@ module Kiso
                            "aria-disabled:cursor-not-allowed aria-disabled:opacity-50 " \
                            "#{Shared::SVG_BASE}"
 
-    # @return [Hash] shared active/inactive variants for pagination links.
-    #   +active: true+ renders outline neutral style, +active: false+ renders ghost.
+    # Shared active/inactive variants for pagination links.
+    # +active: true+ renders outline neutral style (current page),
+    # +active: false+ renders ghost style (other pages).
+    #
+    # @return [Hash{Symbol => Hash}]
     PAGINATION_ACTIVE_VARIANTS = {
       active: {
         true => "ring ring-inset text-foreground bg-background ring-accented " \

data/lib/kiso/themes/shared.rb

@@ -1,5 +1,5 @@
 module Kiso
-  # Theme definitions for all Kiso components.
+  # Namespace for all Kiso component theme definitions.
   #
   # Each constant is a +ClassVariants+ instance that maps variant options
   # to Tailwind CSS class strings. Call +.render+ with variant options to
@@ -22,25 +22,45 @@ module Kiso
     # SelectSeparator with +pointer-events-none+) should remain inline to
     # preserve shadcn fidelity.
     module Shared
+      # SVG child element base classes: disables pointer events, prevents shrinking,
+      # and sets default icon size when not explicitly sized.
+      #
       # Used by: Button, Toggle, ToggleGroupItem, SelectTrigger, SelectItem,
       # ComboboxItem, CommandItem, DropdownMenuItem, DropdownMenuSubTrigger,
       # DropdownMenuCheckboxItem, DropdownMenuRadioItem (via CHECKABLE_ITEM),
       # PaginationLink/Previous/Next (via PAGINATION_LINK_BASE)
+      #
+      # @return [String]
       SVG_BASE = "[&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4"
 
-      # Used by: ComboboxSeparator, DropdownMenuSeparator
-      # (CommandSeparator omits my-1, SelectSeparator adds pointer-events-none — both per shadcn)
+      # Horizontal separator line for items in dropdown-style menus.
+      #
+      # Used by: ComboboxSeparator, DropdownMenuSeparator.
+      # CommandSeparator omits +my-1+, SelectSeparator adds +pointer-events-none+ --
+      # both per shadcn, so they remain inline.
+      #
+      # @return [String]
       ITEM_SEPARATOR = "bg-border -mx-1 my-1 h-px"
 
-      # Used by: ComboboxLabel, SelectLabel
-      # (CommandGroupHeading adds font-medium — per shadcn)
+      # Non-interactive group heading in dropdown-style menus.
+      #
+      # Used by: ComboboxLabel, SelectLabel.
+      # CommandGroupHeading adds +font-medium+ per shadcn, so it remains inline.
+      #
+      # @return [String]
       MENU_LABEL = "text-muted-foreground px-2 py-1.5 text-xs"
 
-      # Used by: CommandShortcut, DropdownMenuShortcut
+      # Keyboard shortcut hint aligned to the right of a menu item.
+      #
+      # Used by: CommandShortcut, DropdownMenuShortcut.
+      #
+      # @return [String]
       MENU_SHORTCUT = "text-muted-foreground ml-auto text-xs tracking-widest"
 
       # Shared base for checkbox and radio items in DropdownMenu.
-      # These are structurally identical — same layout, same interactive states.
+      # These are structurally identical -- same layout, same interactive states.
+      #
+      # @return [String]
       CHECKABLE_ITEM = "relative flex cursor-default items-center gap-2 rounded-sm " \
                        "py-1.5 pr-2 pl-8 text-sm outline-none select-none " \
                        "data-[highlighted]:bg-elevated data-[highlighted]:text-foreground " \

data/lib/kiso/version.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 module Kiso
-  # @return [String] the current gem version
-  VERSION = "0.5.2.pre"
+  # Current version of the Kiso gem, following semantic versioning.
+  # Updated by +bin/release+.
+  #
+  # @return [String]
+  VERSION = "0.6.0.pre"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kiso
 version: !ruby/object:Gem::Version
-  version: 0.5.2.pre
+  version: 0.6.0.pre
 platform: ruby
 authors:
 - Steve Clarke
@@ -337,6 +337,10 @@ files:
 - lib/generators/kiso/component/templates/sub_part_partial.html.erb.tt
 - lib/generators/kiso/component/templates/sub_part_theme.rb.tt
 - lib/generators/kiso/component/templates/theme.rb.tt
+- lib/generators/kiso/install/USAGE
+- lib/generators/kiso/install/install_generator.rb
+- lib/generators/kiso/install/templates/design_system.md.tt
+- lib/generators/kiso/install/templates/initializer.rb.tt
 - lib/kiso.rb
 - lib/kiso/cli.rb
 - lib/kiso/cli/base.rb