phlex_kit 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c45b2de6be65de34864a76e477a59011047aedbcd60622748301fba338ab61bf
-  data.tar.gz: 91d2611e8b3d7aaecaae5a123065efaac66e53ae67a8c60d8b4264bba8cbb34c
+  metadata.gz: dabd58e18372455c16ef319dc2f6270469ea2bbacfa42f2418f1e82f127d57cb
+  data.tar.gz: 04b6f68484015c542bfb65d24322c9342ec029d4d3d322f80dca0f571bbdcba0
 SHA512:
-  metadata.gz: 2528e616b1d5d55ee66f8089cb016207e505601e2be03cca6e9f706f4c68c29622414e9fcd96717354222e142c570806dc85290842eff2570e3d2120f7cc97ce
-  data.tar.gz: 9c218687c79045dc1cf070b40b37f4706fb023c878a142a86c5c2f05cd88f99516a81f00d5cb382d97aae2c9b48dc8c7e0a680f4b43a09146a5a8bcddde3668f
+  metadata.gz: d7ffa228298fa3583da83586982aa28404e1c87979b5c839123c6f493da0e6ce8502b9df6a40b58ba73cd11276a06c3e2c96a081bd82057b903dfd5f9d4dddab
+  data.tar.gz: fee2a8edf8f4ad0da4ab8ee42da82316ee0a6674f689f9f1c6025b7efd097c4a557e788dbe725683c5ecdbe49635735cab086a798c39d104550bc17dbb017b70

data/README.md

@@ -9,7 +9,11 @@ instead of Tailwind**. The full [ruby_ui](https://ruby-ui.com) catalog plus
 shadcn's own additions — 70 component families, 38 Stimulus controllers —
 with the default theme lifted verbatim from shadcn/ui's current token system.
 
-![The docs site's /create page — shadcn/ui's theme-builder demo rebuilt entirely from PhlexKit components](docs/images/create-page.png)
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/create-page-dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="docs/images/create-page-light.png">
+  <img alt="The docs site's /create page — shadcn/ui's theme-builder demo rebuilt entirely from PhlexKit components" src="docs/images/create-page-light.png">
+</picture>
 
 *Every pixel above is PhlexKit: [shadcn's /create demo](https://ui.shadcn.com/create)
 rebuilt in the dummy app from kit components — cards, charts, sliders,
@@ -147,7 +151,11 @@ stylesheet_link_tag "phlex_kit/themes/neutral"
 
 The three knobs from ui.shadcn.com/create map directly: **Radius** →
 `--pk-radius`; **Icon Library** → `PhlexKit.config.icon_library` (see Icons
-below); **Menu** → `PhlexKit::Sidebar.new(menu: :default | :solid)`.
+below); **Menu** → `PhlexKit::Sidebar.new(menu: :default | :solid)`. For an
+off-canvas sidebar, `PhlexKit::SidebarWrapper.new(collapsible: :offcanvas)` +
+a `PhlexKit::SidebarTrigger` anywhere inside it: desktop slides the rail out
+of the layout, below 768px it overlays as a drawer behind a scrim (Escape /
+scrim-click closes; state is DOM-only so Turbo caches restore closed).
 
 ## Icons
 
@@ -195,6 +203,11 @@ render PhlexKit::Chart.new(options: {
 No `window.Chart`? The controller dispatches `phlex-kit--chart:connect` with
 `{ canvas, options }` so you can drive any other library.
 
+For the full walkthrough — pinning Chart.js through **importmap** (and the
+gotcha that makes the obvious `bin/importmap pin chart.js` fail), the UMD
+alternative, and end-to-end verification — see
+[docs/06-CHARTS.md](docs/06-CHARTS.md).
+
 ## phlex-reactive (optional)
 
 For components that own server-state behavior, add phlex-reactive and include

data/app/components/phlex_kit/sidebar/sidebar.css

@@ -158,3 +158,60 @@
 .pk-input.pk-sidebar-input { height: 2rem; width: 100%; background: var(--pk-bg); box-shadow: none; }
 
 .pk-sidebar-inset { flex: 1; min-width: 0; }
+
+/* --- Offcanvas mode (SidebarWrapper collapsible: :offcanvas) ---------------
+   Desktop: the rail slides out of the layout (data-collapsed on the wrapper).
+   Mobile (<768px): the rail is a fixed overlay drawer behind a scrim
+   (data-open). The trigger only shows inside an offcanvas wrapper. The 767px
+   cutoff matches sidebar_controller.js. */
+.pk-sidebar-wrapper.collapsible-offcanvas .pk-sidebar {
+  transition: margin-left .2s ease, transform .2s ease;
+}
+.pk-sidebar-wrapper.collapsible-offcanvas[data-collapsed] .pk-sidebar { margin-left: -16rem; }
+
+.pk-sidebar-trigger {
+  display: none;
+  align-items: center;
+  justify-content: center;
+  width: 2rem;
+  height: 2rem;
+  border: 0;
+  border-radius: calc(var(--pk-radius) - 2px);
+  background: transparent;
+  color: inherit;
+  padding: 0;
+  cursor: pointer;
+}
+.pk-sidebar-trigger:hover { background: var(--pk-accent); }
+.pk-sidebar-trigger svg { width: 1rem; height: 1rem; }
+.collapsible-offcanvas .pk-sidebar-trigger { display: inline-flex; }
+
+.pk-sidebar-scrim { display: none; }
+
+@media (max-width: 767px) {
+  .pk-sidebar-wrapper.collapsible-offcanvas .pk-sidebar {
+    position: fixed;
+    inset-block: 0;
+    left: 0;
+    z-index: 50;
+    height: 100dvh;
+    margin-left: 0;
+    transform: translateX(-100%);
+    box-shadow: 0 8px 30px rgb(0 0 0 / .35);
+  }
+  .pk-sidebar-wrapper.collapsible-offcanvas[data-open] .pk-sidebar { transform: none; }
+  .pk-sidebar-wrapper.collapsible-offcanvas[data-open] .pk-sidebar-scrim {
+    display: block;
+    position: fixed;
+    inset: 0;
+    z-index: 49;
+    background: rgb(0 0 0 / .5);
+    border: 0;
+    padding: 0;
+    cursor: default;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .pk-sidebar-wrapper.collapsible-offcanvas .pk-sidebar { transition: none; }
+}

data/app/components/phlex_kit/sidebar/sidebar.rb

@@ -1,9 +1,9 @@
 module PhlexKit
-  # Sidebar shell, ported from ruby_ui's RubyUI::Sidebar at `collapsible: :none`
-  # (the NonCollapsibleSidebar path): a static flex-column rail. Deliberately
-  # WITHOUT ruby_ui's collapsible/offcanvas Stimulus controller + cookie state +
-  # mobile Sheet (the admin sidebar is static) — those can be added later if a
-  # collapsible chrome is wanted. The static part set matches shadcn/ui's Sidebar:
+  # Sidebar shell, ported from ruby_ui's RubyUI::Sidebar: a flex-column rail.
+  # Static by default; SidebarWrapper(collapsible: :offcanvas) + SidebarTrigger
+  # give it shadcn's offcanvas behavior (desktop slide-away, mobile overlay
+  # drawer with scrim — see sidebar_wrapper.rb / sidebar_controller.js).
+  # The part set matches shadcn/ui's Sidebar:
   # compose with SidebarWrapper (the page root) + SidebarHeader / SidebarContent /
   # SidebarGroup (+ Label / Content / Action) / SidebarMenu (+ Item / Button /
   # Action / Badge / Skeleton / Sub / SubItem / SubButton) / SidebarSeparator /

data/app/components/phlex_kit/sidebar/sidebar_controller.js

@@ -0,0 +1,24 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Connects to data-controller="phlex-kit--sidebar" — set by SidebarWrapper when
+// collapsible: :offcanvas. One attribute per surface, both DOM-only so Turbo's
+// page cache never restores an open drawer (the wrapper also closes on
+// turbo:before-cache): `data-open` shows the mobile overlay drawer,
+// `data-collapsed` slides the desktop rail out of the layout. The 767px cutoff
+// matches sidebar.css's offcanvas media query.
+export default class extends Controller {
+  static MOBILE = "(max-width: 767px)"
+
+  toggle() {
+    if (this.mobile) this.element.toggleAttribute("data-open")
+    else this.element.toggleAttribute("data-collapsed")
+  }
+
+  closeMobile() {
+    this.element.removeAttribute("data-open")
+  }
+
+  get mobile() {
+    return window.matchMedia(this.constructor.MOBILE).matches
+  }
+}

data/app/components/phlex_kit/sidebar/sidebar_trigger.rb

@@ -0,0 +1,23 @@
+module PhlexKit
+  # The hamburger that toggles an offcanvas sidebar, ported from shadcn/ui's
+  # SidebarTrigger. Place it anywhere inside a
+  # SidebarWrapper(collapsible: :offcanvas) — typically at the top of the
+  # SidebarInset. Renders the :menu icon unless a block supplies its own
+  # content. Hidden by CSS unless the wrapper is offcanvas. See sidebar.rb.
+  class SidebarTrigger < BaseComponent
+    def initialize(**attrs)
+      @attrs = attrs
+    end
+
+    def view_template(&block)
+      button(**mix({
+        type: :button,
+        class: "pk-sidebar-trigger",
+        aria_label: "Toggle sidebar",
+        data: { action: "click->phlex-kit--sidebar#toggle" }
+      }, @attrs)) do
+        block ? yield : render(Icon.new(:menu, size: nil))
+      end
+    end
+  end
+end

data/app/components/phlex_kit/sidebar/sidebar_wrapper.rb

@@ -1,13 +1,48 @@
 module PhlexKit
   # The page-level flex row that holds a PhlexKit::Sidebar + a PhlexKit::SidebarInset.
+  #
+  # `collapsible:` (shadcn/ui's Sidebar `collapsible` prop, held here because the
+  # wrapper is the Stimulus scope shared by rail, trigger and scrim):
+  #   :none      — static rail (default).
+  #   :offcanvas — the rail hides/reveals via a PhlexKit::SidebarTrigger. On
+  #                desktop it slides out of the layout; below 768px it overlays
+  #                as a fixed drawer behind a click-to-close scrim, closed by
+  #                Escape and before Turbo caches the page. State is DOM-only:
+  #                `data-collapsed` (desktop) / `data-open` (mobile drawer).
   # See sidebar.rb.
   class SidebarWrapper < BaseComponent
-    def initialize(**attrs)
+    COLLAPSIBLE = { none: nil, offcanvas: "collapsible-offcanvas" }.freeze
+
+    def initialize(collapsible: :none, **attrs)
+      @collapsible = collapsible.to_sym
       @attrs = attrs
     end
 
     def view_template(&block)
-      div(**mix({ class: "pk-sidebar-wrapper" }, @attrs), &block)
+      unless offcanvas?
+        return div(**mix({ class: classes }, @attrs), &block)
+      end
+
+      div(**mix({
+        class: classes,
+        data: {
+          controller: "phlex-kit--sidebar",
+          action: "keydown.esc@window->phlex-kit--sidebar#closeMobile " \
+                  "turbo:before-cache@window->phlex-kit--sidebar#closeMobile"
+        }
+      }, @attrs)) do
+        yield if block
+        button(type: :button, class: "pk-sidebar-scrim", aria_label: "Close sidebar",
+               tabindex: "-1", data: { action: "click->phlex-kit--sidebar#closeMobile" })
+      end
+    end
+
+    private
+
+    def offcanvas? = @collapsible == :offcanvas
+
+    def classes
+      [ "pk-sidebar-wrapper", COLLAPSIBLE.fetch(@collapsible) ].compact.join(" ")
     end
   end
 end

data/app/javascript/phlex_kit/controllers/index.js

@@ -39,6 +39,7 @@ import SelectController from "phlex_kit/controllers/select_controller"
 import SelectItemController from "phlex_kit/controllers/select_item_controller"
 import SheetController from "phlex_kit/controllers/sheet_controller"
 import SheetContentController from "phlex_kit/controllers/sheet_content_controller"
+import SidebarController from "phlex_kit/controllers/sidebar_controller"
 import SliderController from "phlex_kit/controllers/slider_controller"
 import TabsController from "phlex_kit/controllers/tabs_controller"
 import ThemeToggleController from "phlex_kit/controllers/theme_toggle_controller"
@@ -79,6 +80,7 @@ export function registerPhlexKitControllers(application) {
   application.register("phlex-kit--select-item", SelectItemController)
   application.register("phlex-kit--sheet", SheetController)
   application.register("phlex-kit--sheet-content", SheetContentController)
+  application.register("phlex-kit--sidebar", SidebarController)
   application.register("phlex-kit--slider", SliderController)
   application.register("phlex-kit--tabs", TabsController)
   application.register("phlex-kit--theme-toggle", ThemeToggleController)

data/lib/phlex_kit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PhlexKit
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phlex_kit
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Matt Kennedy
@@ -462,6 +462,7 @@ files:
 - app/components/phlex_kit/sidebar/sidebar.css
 - app/components/phlex_kit/sidebar/sidebar.rb
 - app/components/phlex_kit/sidebar/sidebar_content.rb
+- app/components/phlex_kit/sidebar/sidebar_controller.js
 - app/components/phlex_kit/sidebar/sidebar_footer.rb
 - app/components/phlex_kit/sidebar/sidebar_group.rb
 - app/components/phlex_kit/sidebar/sidebar_group_action.rb
@@ -480,6 +481,7 @@ files:
 - app/components/phlex_kit/sidebar/sidebar_menu_sub_button.rb
 - app/components/phlex_kit/sidebar/sidebar_menu_sub_item.rb
 - app/components/phlex_kit/sidebar/sidebar_separator.rb
+- app/components/phlex_kit/sidebar/sidebar_trigger.rb
 - app/components/phlex_kit/sidebar/sidebar_wrapper.rb
 - app/components/phlex_kit/skeleton/skeleton.css
 - app/components/phlex_kit/skeleton/skeleton.rb