RubyGems - kiso - Versions diffs - 0.5.3.pre → 0.6.0.pre - Mend

kiso 0.5.3.pre → 0.6.0.pre

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (121) hide show

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e2ae8ad60d92d8f26f348cfcf1dc7e244ab9d43d8650c70bb55563a569ebd92
-  data.tar.gz: 75bcf4fd1147c79754256ab6c3cccd994a1b5a7ace087fd52529e716d7521422
+  metadata.gz: 71bd073faf4eaf81467972ad2e834769956d808d79790d0de417697766823fcf
+  data.tar.gz: c31b53740f75c262b588d7b56416ed91a58496e6aad704286662c4575af81dff
 SHA512:
-  metadata.gz: 80ddd9d1a892eec79083c535516369d0278c3680ee75fd9e7cbffb406a8684d705805104ee12dd2e8d5a920baa15aa1a445d31c637d0ec8a8a675b05889f96e6
-  data.tar.gz: '06824eba6296399c458259426d806da86901040d0922c696efc1f066e0c1feed2c8f405fb09edc5344e54995ef51a932e313291ee77846605315d3e8c433f1ca'
+  metadata.gz: fd986968f5371f77ac6ab53852d6a9227fdb645734fd1c8fa51e0c6737b1074bb6d1839a6779bd3f2ed4e30c69f126a504ad5330b607ba68e4deadd9a735b125
+  data.tar.gz: c1834a11353dd43503b96317612cdbf76287c614845e264b53efb23182cdfc472f92dacd81d673cd7d2834abd278e0af96c22d63e1d894951459776975a15080

data/app/assets/tailwind/kiso/button.css CHANGED Viewed

@@ -1,6 +1,15 @@
-/* Default display for buttons — lives in @layer components so utility classes
-   (including `hidden`) override via the higher-priority utilities layer. When
-   a utility like `hidden` is removed via JS, this rule restores inline-flex.
+/* ── Button ──────────────────────────────────────────────────────────────────
+   Default display value for the Button component.
+   Why CSS instead of a Tailwind class?
+   The theme module applies `inline-flex` via Tailwind, but Tailwind utilities
+   live in @layer utilities — the highest-priority layer. That means when JS
+   removes a `hidden` class, the button's `inline-flex` (also in utilities)
+   has no cascade advantage to restore visibility. Placing the default display
+   in @layer components (lower priority) lets utility classes like `hidden`
+   override it naturally, while still restoring inline-flex when `hidden` is
+   removed.
    Fixes: https://github.com/steveclarke/kiso/issues/200 */
 @layer components {

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

@@ -1,5 +1,16 @@
-/* Checkbox indicator — CSS ::after for the checkmark since native <input>
-   can't contain child elements. Uses mask-image with the Lucide Check icon. */
+/* ── Checkbox ────────────────────────────────────────────────────────────────
+   Checkmark indicator via CSS ::after pseudo-element.
+   Why CSS instead of ERB?
+   Native <input type="checkbox"> cannot contain child elements, so the
+   checkmark must be rendered as a pseudo-element. The indicator uses
+   mask-image with an inline SVG (Lucide Check icon) and currentColor for
+   the fill, which inherits the text color set by compound variants — this
+   keeps the checkmark color in sync with the checkbox's checked state
+   styling (e.g., text-primary-foreground on a bg-primary background).
+   The grid + place-content: center pattern ensures the ::after checkmark
+   is perfectly centered within the checkbox regardless of its size. */
 [data-component="checkbox"] {
   display: grid;

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

@@ -1,6 +1,18 @@
-/* ── 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. */
+/* ── Color Mode Button ────────────────────────────────────────────────────────
+   Icon visibility toggling for the light/dark mode button (kui(:color_mode_button)).
+   Why CSS instead of ERB?
+   The icon swap must respond to the .dark class on <html>, which is set by a
+   blocking script before first paint. Using CSS ensures the correct icon
+   (sun or moon) is visible immediately — no Stimulus controller or JS needed
+   for the initial render. The kiso--theme controller handles toggling after
+   that.
+   Uses @layer components so utility classes on the icon elements can override
+   if needed.
+   Light mode: sun icon visible, moon icon hidden.
+   Dark mode:  moon icon visible, sun icon hidden. */
 @layer components {
   [data-slot="color-mode-icon-dark"] { display: none; }

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

@@ -1,37 +1,51 @@
 /* ── 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.
+   CSS grid mechanics, tokens, and state-driven rules for the full-screen
+   sidebar + topbar dashboard shell (kui(:dashboard_group) and friends).
-   Host apps can override any token in their own @theme block:
-     @theme { --sidebar-width: 18rem; }
- */
+   Why CSS instead of ERB?
+   The dashboard layout uses CSS Grid with animated column widths, fixed
+   positioning for mobile overlays, pseudo-state-driven visibility, and
+   custom Tailwind variants — none of which can be expressed as Tailwind
+   utility classes in ERB templates. The sidebar open/close animation,
+   grid template transitions, mobile overlay transform, and scrim backdrop
+   all require real CSS rules.
-/* ── Tokens ──────────────────────────────────────────────────────────────── */
+   Host apps can override any @theme token in their own @theme block:
+     @theme { --sidebar-width: 18rem; --topbar-height: 4rem; }
+   All selectors target [data-slot="..."] attributes (shadcn v4 convention)
+   rather than class names, making them resilient to theme customization.
+   ──────────────────────────────────────────────────────────────────────────── */
+/* ── Design Tokens ───────────────────────────────────────────────────────── */
 @theme {
-  /* Sidebar geometry */
+  /* Sidebar geometry — fixed width when open (collapses to 0 when closed) */
   --sidebar-width:             16rem;
-  /* Layout heights */
+  /* Topbar row height — sidebar header matches this to align horizontally */
   --topbar-height:             3.5rem;
-  /* Sidebar surface tokens (light mode defaults) */
+  /* Sidebar surface tokens (light mode defaults).
+     These are separate from the main semantic tokens because the sidebar
+     can have its own distinct color scheme (e.g., a dark sidebar in an
+     otherwise light app). */
   --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 */
+  /* Animation timing for sidebar open/close transitions */
   --sidebar-duration:          220ms;
   --ease-out-expo:             cubic-bezier(0.16, 1, 0.3, 1);
-  /* Z-index stack */
+  /* Z-index stack — sidebar above topbar for mobile overlay */
   --z-topbar:  30;
   --z-sidebar: 40;
 }
-/* Dark mode sidebar token overrides */
+/* Dark mode overrides for sidebar-specific surface tokens */
 .dark {
   --sidebar-background:        var(--color-zinc-950);
   --sidebar-foreground:        var(--color-zinc-100);
@@ -40,11 +54,13 @@
   --sidebar-accent-foreground: var(--color-zinc-300);
 }
-/* ── Sidebar state variants ──────────────────────────────────────────────────
-   Custom Tailwind variants for showing/hiding content based on sidebar state.
-   Works on any descendant of dashboard_group. Compose with breakpoints:
-     kui-sidebar-open:lg:hidden    — hide on desktop when sidebar expanded
-     kui-sidebar-closed:lg:hidden  — hide on desktop when sidebar collapsed  */
+/* ── Sidebar State Variants (Tailwind v4 @custom-variant) ────────────────────
+   Register custom Tailwind variants that activate based on sidebar open/close
+   state. These let ERB templates use conditional classes without JS:
+     kui-sidebar-open:lg:hidden    — hide on desktop when sidebar is expanded
+     kui-sidebar-closed:lg:hidden  — hide on desktop when sidebar is collapsed
+   The variant matches any descendant of an element with the data-sidebar-open
+   attribute (set by the kiso--sidebar Stimulus controller on dashboard_group). */
 @custom-variant kui-sidebar-open {
   [data-sidebar-open="true"] & {
@@ -58,53 +74,71 @@
   }
 }
-/* ── Layout mechanics ─────────────────────────────────────────────────────── */
+/* ── Layout Mechanics ─────────────────────────────────────────────────────────
+   All layout rules live in @layer components so Tailwind utility classes
+   (in the higher-priority @layer utilities) can override them when needed.
+   Grid structure (default "sidebar" layout):
+   ┌─────────────┬──────────────────────────┐
+   │  sidebar     │  topbar (navbar)         │  row 1: --topbar-height
+   │  (full       ├──────────────────────────┤
+   │   height)    │  panel (main content)    │  row 2: 1fr
+   └─────────────┴──────────────────────────┘
+   col 1: sidebar   col 2: 1fr
+   ──────────────────────────────────────────────────────────────────────────── */
 @layer components {
-  /* Drive --sidebar-current-width from the data attribute set by sidebar controller */
+  /* ── Sidebar width state ─────────────────────────────────────────────────
+     The kiso--sidebar Stimulus controller sets data-sidebar-open on the
+     dashboard_group element. These rules translate that attribute into a
+     CSS variable that drives the grid column width. */
   [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 */
+  /* Prevent a 1px ghost border when sidebar is fully collapsed */
   [data-sidebar-open="false"] [data-slot="dashboard-sidebar"] {
     border-right-width: 0;
   }
-  /* Flat 2×2 grid: topbar row + sidebar/panel row */
+  /* ── Grid container ──────────────────────────────────────────────────── */
+  /* 2-row, 2-column grid with animated sidebar column */
   [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) */
+  /* Topbar occupies column 2 only (sidebar spans both rows in column 1) */
   [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.
-  */
+  /* Sidebar spans full height (row 1 through last row).
+     background-color and border-right-color reference sidebar-specific CSS
+     variables and are set here rather than via Tailwind arbitrary classes
+     because bg-(--css-var) classes in @theme are tree-shaken if not
+     referenced elsewhere. */
   [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 */
+  /* Sidebar header aligns with the topbar height */
   [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 */
+  /* Inner nav container: fixed at --sidebar-width so content doesn't reflow
+     during the grid column animation (the outer column shrinks, clipping
+     the overflow from this fixed-width inner element). */
   [data-slot="dashboard-sidebar-inner"] {
     width: var(--sidebar-width);
     height: 100%;
@@ -114,13 +148,16 @@
     color: var(--sidebar-foreground);
   }
-  /* Panel: row 2, col 2 */
+  /* Main content panel: row 2, column 2 */
   [data-slot="dashboard-panel"] {
     grid-column: 2;
     grid-row: 2;
   }
-  /* ── Navbar layout variant: navbar spans full width, sidebar below ────── */
+  /* ── "Navbar" layout variant ─────────────────────────────────────────────
+     Alternative layout where the navbar spans the full width (both columns)
+     and the sidebar sits below it instead of spanning full height. Activated
+     by data-layout="navbar" on the dashboard_group element. */
   [data-layout="navbar"] [data-slot="dashboard-navbar"] {
     grid-column: 1 / -1;
   }
@@ -128,16 +165,20 @@
     grid-row: auto;
   }
-  /* Scrim: hidden on desktop */
+  /* Scrim overlay: hidden on desktop, shown on mobile when sidebar is open */
   [data-slot="dashboard-scrim"] { display: none; }
-  /* ── Collapse button icon switching ────────────────────────────────────── */
+  /* ── Collapse button icon switching ──────────────────────────────────────
+     The sidebar collapse button shows different icons depending on whether
+     the sidebar is open or closed (e.g., chevron-left vs chevron-right). */
   [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) ───────────────────────────────────── */
+  /* ── Nav section accordion (native <details>/<summary>) ─────────────────
+     Chevron rotates 180deg when the section is expanded. Uses CSS transition
+     rather than JS for smooth animation. */
   [data-slot="nav-section-chevron"] {
     transition: transform 200ms ease;
   }
@@ -145,7 +186,9 @@
     transform: rotate(180deg);
   }
-  /* ── Nav item sidebar context ────────────────────────────────────────── */
+  /* ── Nav item hover/active states inside sidebar ────────────────────────
+     Nav items use the sidebar's own accent tokens (not the global accent
+     tokens) so the sidebar can have an independent color scheme. */
   [data-slot="dashboard-sidebar-inner"] [data-slot="nav-item"]:hover {
     background-color: var(--sidebar-accent);
     color: var(--sidebar-accent-foreground);
@@ -155,34 +198,44 @@
     color: var(--sidebar-accent-foreground);
   }
-  /* ── Mobile: sidebar becomes a fixed full-width overlay ───────────────── */
+  /* ── Mobile (< md breakpoint): sidebar becomes a full-width overlay ────
+     On small screens, the sidebar column collapses to 0 in the grid and the
+     sidebar element switches to a fixed-position overlay that slides in from
+     the left. A semi-transparent scrim appears behind it. */
   @media (max-width: 767px) {
-    /* Collapse sidebar column to 0 on mobile */
+    /* Remove the sidebar column from the grid on mobile.
+       --sidebar-mobile-width caps the sidebar so the scrim remains
+       visible and tappable for dismiss (#208). */
     [data-slot="dashboard-group"] {
+      --sidebar-mobile-width: min(var(--sidebar-width), 85dvw);
       grid-template-columns: 0 1fr;
     }
-    /* Sidebar switches from grid column to fixed overlay */
+    /* Sidebar becomes a fixed overlay that slides in from the left */
     [data-slot="dashboard-sidebar"] {
       position: fixed;
       inset-block: 0;
       inset-inline-start: 0;
       z-index: var(--z-sidebar);
-      width: 100dvw;
-      transform: translateX(-100dvw);
+      width: var(--sidebar-mobile-width);
+      transform: translateX(-100%);
       transition: transform var(--sidebar-duration) var(--ease-out-expo);
     }
+    /* Slide sidebar into view when open */
     [data-sidebar-open="true"] [data-slot="dashboard-sidebar"] {
       transform: translateX(0);
     }
-    /* Inner nav fills the full-width sidebar on mobile */
+    /* Inner nav matches mobile sidebar width */
     [data-slot="dashboard-sidebar-inner"] {
-      width: 100dvw;
+      width: var(--sidebar-mobile-width);
     }
-    /* Scrim: appears behind the sidebar overlay on mobile */
+    /* Semi-transparent scrim behind the open sidebar overlay.
+       z-index is one below the sidebar so it sits behind the sidebar
+       but above the main content. Clicking the scrim closes the sidebar
+       (handled by the kiso--sidebar Stimulus controller). */
     [data-sidebar-open="true"] [data-slot="dashboard-scrim"] {
       display: block;
       position: fixed;

data/app/assets/tailwind/kiso/dialog.css CHANGED Viewed

@@ -1,6 +1,26 @@
-/* Dialog and Alert Dialog entry/exit animations and scroll lock. */
+/* ── Dialog & Alert Dialog ────────────────────────────────────────────────────
+   Entry/exit animations, scroll lock, and reduced-motion support for both
+   Dialog and Alert Dialog components.
-/* Entry */
+   Why CSS instead of ERB?
+   Both components use the native <dialog> element with showModal(). Animations
+   on open/close, the ::backdrop fade, and scroll locking on the <html> element
+   require CSS — they cannot be expressed as Tailwind utility classes.
+   Animation lifecycle (managed by the kiso--dialog Stimulus controller):
+   1. Open:  controller calls dialog.showModal() → browser sets [open] →
+             CSS triggers fade-in + scale-up on both backdrop and content.
+   2. Close: controller sets data-state="closing" → CSS triggers fade-out +
+             scale-down with `forwards` fill → animationend fires → controller
+             calls dialog.close() and removes data-state.
+   Selectors use :is() to target both dialog and alert-dialog with shared
+   rules, avoiding duplication.
+   ──────────────────────────────────────────────────────────────────────────── */
+/* ── Entry animations ──────────────────────────────────────────────────────
+   Triggered by the native [open] attribute when showModal() is called.
+   Backdrop fades in; content fades in and scales up from 95%. */
 :is(dialog[data-slot="dialog"], dialog[data-slot="alert-dialog"])[open] {
   animation: kiso-dialog-backdrop-in 200ms ease-out;
 }
@@ -8,7 +28,10 @@
   animation: kiso-dialog-content-in 200ms ease-out;
 }
-/* Exit — data-state="closing" set by Stimulus before calling .close() */
+/* ── Exit animations ──────────────────────────────────────────────────────
+   Triggered by data-state="closing" which the Stimulus controller sets
+   before calling .close(). Uses `forwards` fill mode to hold the final
+   frame (opacity: 0) until the controller removes the dialog from view. */
 :is(dialog[data-slot="dialog"], dialog[data-slot="alert-dialog"])[data-state="closing"] {
   animation: kiso-dialog-backdrop-out 200ms ease-in forwards;
 }
@@ -16,12 +39,18 @@
   animation: kiso-dialog-content-out 200ms ease-in forwards;
 }
+/* ── Keyframes ─────────────────────────────────────────────────────────── */
+/* Backdrop: simple opacity fade */
 @keyframes kiso-dialog-backdrop-in {
   from { opacity: 0; }
 }
 @keyframes kiso-dialog-backdrop-out {
   to { opacity: 0; }
 }
+/* Content: opacity fade combined with a subtle scale transform (95% → 100%
+   on entry, 100% → 95% on exit) for a "zoom in" feel. */
 @keyframes kiso-dialog-content-in {
   from { opacity: 0; transform: scale(0.95); }
 }
@@ -29,13 +58,18 @@
   to { opacity: 0; transform: scale(0.95); }
 }
-/* Scroll lock — prevent body scroll when modal dialog is open */
+/* ── Scroll lock ──────────────────────────────────────────────────────────
+   Prevent background scrolling when a modal dialog is open. The :modal
+   pseudo-class ensures this only applies to dialogs opened with showModal()
+   (not dialog.show()). scrollbar-gutter: stable prevents layout shift when
+   the scrollbar disappears. */
 html:has(:is(dialog[data-slot="dialog"], dialog[data-slot="alert-dialog"])[open]:modal) {
   overflow: hidden;
   scrollbar-gutter: stable;
 }
-/* Respect reduced motion */
+/* ── Reduced motion ───────────────────────────────────────────────────────
+   Disable all dialog animations for users who prefer reduced motion. */
 @media (prefers-reduced-motion: reduce) {
   :is(dialog[data-slot="dialog"], dialog[data-slot="alert-dialog"])[open],
   :is(dialog[data-slot="dialog"], dialog[data-slot="alert-dialog"])[open] > :is([data-slot="dialog-content"], [data-slot="alert-dialog-content"]),