m9sh 0.2.1 → 0.2.2

data/app/views/docs/components/toaster.html.erb

@@ -0,0 +1,227 @@
+<%= render Docs::ComponentPageComponent.new(title: "Toaster - m9sh Components") do |page| %>
+  <% page.with_header(
+    name: "Toaster",
+    description: "A container component that manages and displays toast notifications dynamically."
+  ) %>
+
+  <% page.with_installation(component_name: "toaster") %>
+
+  <% page.with_usage do %>
+    <p class="text-sm text-muted-foreground">
+      Add the Toaster component to your application layout (typically in <code class="text-xs bg-muted px-1 py-0.5 rounded">app/views/layouts/application.html.erb</code>):
+    </p>
+
+    <%= render Docs::CodeBlockComponent.new(
+      code: toaster_usage_code,
+      language: "erb"
+    ) %>
+
+    <p class="text-sm text-muted-foreground mt-4">
+      Then trigger toasts from anywhere in your JavaScript code using custom events:
+    </p>
+
+    <%= render Docs::CodeBlockComponent.new(
+      code: toaster_javascript_code,
+      language: "javascript"
+    ) %>
+  <% end %>
+
+  <% page.with_examples do %>
+    <!-- Default Setup Example -->
+    <% default_setup_html = capture do %>
+      <div class="space-y-4">
+        <p class="text-sm text-muted-foreground">
+          Add the Toaster component to your layout file:
+        </p>
+        <%= render Docs::CodeBlockComponent.new(
+          code: toaster_usage_code,
+          language: "erb"
+        ) %>
+      </div>
+    <% end %>
+
+    <%= render Docs::ComponentPreviewComponent.new(
+      title: "Default Setup",
+      preview_content: default_setup_html,
+      code: nil,
+      ai_command: nil
+    ) %>
+
+    <!-- Triggering Toasts Example -->
+    <% trigger_toasts_html = capture do %>
+      <div class="space-y-4">
+        <%= render M9sh::ButtonComponent.new(
+          onclick: "window.dispatchEvent(new CustomEvent('hotcdn:toast', { detail: { title: 'Success', description: 'Operation completed successfully.', variant: 'success' } }))"
+        ) do %>
+          Show Success Toast
+        <% end %>
+
+        <%= render M9sh::ButtonComponent.new(
+          variant: :destructive,
+          onclick: "window.dispatchEvent(new CustomEvent('hotcdn:toast', { detail: { title: 'Error', description: 'Something went wrong.', variant: 'error' } }))"
+        ) do %>
+          Show Error Toast
+        <% end %>
+
+        <%= render M9sh::ButtonComponent.new(
+          variant: :outline,
+          onclick: "window.dispatchEvent(new CustomEvent('hotcdn:toast', { detail: { title: 'Warning', description: 'Please review your changes.', variant: 'warning' } }))"
+        ) do %>
+          Show Warning Toast
+        <% end %>
+
+        <%= render M9sh::ButtonComponent.new(
+          variant: :secondary,
+          onclick: "window.dispatchEvent(new CustomEvent('hotcdn:toast', { detail: { title: 'Information', description: 'Here is some useful information.', variant: 'info' } }))"
+        ) do %>
+          Show Info Toast
+        <% end %>
+      </div>
+    <% end %>
+
+    <%= render Docs::ComponentPreviewComponent.new(
+      title: "Triggering Toasts",
+      preview_content: trigger_toasts_html,
+      code: toaster_example_code,
+      ai_command: toaster_example_code
+    ) %>
+
+    <!-- JavaScript Integration Example -->
+    <% js_integration_html = capture do %>
+      <div class="space-y-4">
+        <h4 class="text-sm font-semibold">From Stimulus Controllers</h4>
+        <%= render Docs::CodeBlockComponent.new(
+          code: <<~JAVASCRIPT,
+            // In your Stimulus controller
+            export default class extends Controller {
+              showToast() {
+                window.dispatchEvent(new CustomEvent('hotcdn:toast', {
+                  detail: {
+                    title: 'Success',
+                    description: 'Your changes have been saved.',
+                    variant: 'success',
+                    duration: 5000
+                  }
+                }));
+              }
+            }
+          JAVASCRIPT
+          language: "javascript"
+        ) %>
+
+        <h4 class="text-sm font-semibold mt-4">From Server Responses (Turbo Streams)</h4>
+        <%= render Docs::CodeBlockComponent.new(
+          code: toaster_turbo_stream_code,
+          language: "erb"
+        ) %>
+      </div>
+    <% end %>
+
+    <%= render Docs::ComponentPreviewComponent.new(
+      title: "JavaScript Integration",
+      preview_content: js_integration_html,
+      code: nil,
+      ai_command: nil
+    ) %>
+
+    <!-- Configuration Options Example -->
+    <% config_options_html = capture do %>
+      <div class="space-y-4">
+        <p class="text-sm text-muted-foreground">
+          The toaster listens for the <code class="text-xs bg-muted px-1 py-0.5 rounded">hotcdn:toast</code> custom event with the following options:
+        </p>
+
+        <%= render Docs::PropTableComponent.new(
+          props: [
+            {
+              name: "title",
+              type: "String",
+              default: nil,
+              description: "The title of the toast (required)"
+            },
+            {
+              name: "description",
+              type: "String",
+              default: "null",
+              description: "Optional description text"
+            },
+            {
+              name: "variant",
+              type: "String",
+              default: "'default'",
+              description: "Visual variant: 'default', 'success', 'error', 'warning', 'info'"
+            },
+            {
+              name: "duration",
+              type: "Number",
+              default: "5000",
+              description: "Duration in milliseconds before auto-dismiss"
+            }
+          ]
+        ) %>
+      </div>
+    <% end %>
+
+    <%= render Docs::ComponentPreviewComponent.new(
+      title: "Configuration Options",
+      preview_content: config_options_html,
+      code: nil,
+      ai_command: nil
+    ) %>
+  <% end %>
+
+  <% page.with_api do %>
+    <h3 class="text-lg font-semibold">Toaster Component</h3>
+    <p class="text-sm text-muted-foreground">
+      The Toaster component is a container that manages toast notifications. It doesn't accept any props and should be added once to your layout.
+    </p>
+
+    <div class="mt-6 space-y-2">
+      <h3 class="text-lg font-semibold">Event API</h3>
+      <p class="text-sm text-muted-foreground mb-4">
+        Toasts are triggered by dispatching a custom event on the window object:
+      </p>
+
+      <%= render Docs::CodeBlockComponent.new(
+        code: <<~JAVASCRIPT,
+          window.dispatchEvent(new CustomEvent('hotcdn:toast', {
+            detail: {
+              title: 'Title',           // Required: The toast title
+              description: 'Message',   // Optional: The toast description
+              variant: 'success',       // Optional: Visual variant (default, success, error, warning, info)
+              duration: 5000           // Optional: Auto-dismiss duration in ms (default: 5000)
+            }
+          }));
+        JAVASCRIPT
+        language: "javascript"
+      ) %>
+    </div>
+
+    <div class="mt-6 space-y-2">
+      <h3 class="text-lg font-semibold">Notes</h3>
+      <ul class="list-disc list-inside text-sm text-muted-foreground space-y-1">
+        <li>The Toaster should be added to your application layout once, typically near the end of the body tag</li>
+        <li>Multiple toasts can be displayed simultaneously and are stacked vertically</li>
+        <li>Toasts are positioned at the bottom-right on mobile and can be configured via CSS classes</li>
+        <li>Each toast automatically dismisses after its duration expires (default 5 seconds)</li>
+        <li>Users can manually dismiss toasts by clicking the close button</li>
+        <li>The component uses Stimulus controllers to manage toast creation and removal</li>
+        <li>Toasts include smooth slide-in and slide-out animations</li>
+        <li>The container is accessible with proper ARIA live regions for screen readers</li>
+      </ul>
+    </div>
+
+    <div class="mt-6 space-y-2">
+      <h3 class="text-lg font-semibold">Best Practices</h3>
+      <ul class="list-disc list-inside text-sm text-muted-foreground space-y-1">
+        <li>Use success toasts for confirmations of user actions</li>
+        <li>Use error toasts for operations that failed and need user attention</li>
+        <li>Use warning toasts for important information that doesn't block the user</li>
+        <li>Use info toasts for general informational messages</li>
+        <li>Keep toast messages concise - ideally under two lines</li>
+        <li>Avoid showing too many toasts at once to prevent overwhelming the user</li>
+        <li>For critical errors that require action, consider using a modal or alert dialog instead</li>
+      </ul>
+    </div>
+  <% end %>
+<% end %>

data/app/views/docs/components/toggle.html.erb

@@ -0,0 +1,154 @@
+<%= render Docs::ComponentPageComponent.new(title: "Toggle") do |page| %>
+  <% page.with_header(
+    name: "Toggle",
+    description: "A two-state button that can be either on or off."
+  ) %>
+
+  <% page.with_installation(component_name: "toggle") %>
+
+  <% page.with_usage do %>
+    <%= render Docs::CodeBlockComponent.new(
+      code: toggle_usage_code,
+      language: "erb"
+    ) %>
+  <% end %>
+
+  <% page.with_examples do %>
+    <!-- Default Example -->
+    <% toggle = M9sh::ToggleComponent.new %>
+    <% toggle_html = capture do %>
+      <%= render toggle do %>
+        Toggle
+      <% end %>
+    <% end %>
+
+    <%= render Docs::ComponentPreviewComponent.new(
+      title: "Default",
+      preview_content: toggle_html,
+      code: toggle_default_code,
+      ai_command: toggle_default_code
+    ) %>
+
+    <!-- With Text Example -->
+    <% with_text_html = capture do %>
+      <%= render M9sh::ToggleComponent.new do %>
+        Toggle with text
+      <% end %>
+    <% end %>
+
+    <%= render Docs::ComponentPreviewComponent.new(
+      title: "With Text",
+      preview_content: with_text_html,
+      code: toggle_with_text_code,
+      ai_command: toggle_with_text_code
+    ) %>
+
+    <!-- With Icon Example -->
+    <% with_icon_html = capture do %>
+      <%= render M9sh::ToggleComponent.new do %>
+        <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+          <path d="M17 3a2.85 2.83 0 1 1 4 4L7.5 20.5 2 22l1.5-5.5Z"/>
+          <path d="m15 5 4 4"/>
+        </svg>
+      <% end %>
+    <% end %>
+
+    <%= render Docs::ComponentPreviewComponent.new(
+      title: "With Icon",
+      preview_content: with_icon_html,
+      code: toggle_with_icon_code,
+      ai_command: toggle_with_icon_code
+    ) %>
+
+    <!-- Disabled Example -->
+    <% disabled_html = capture do %>
+      <div class="flex gap-2">
+        <%= render M9sh::ToggleComponent.new(disabled: true) do %>
+          Disabled
+        <% end %>
+        <%= render M9sh::ToggleComponent.new(pressed: true, disabled: true) do %>
+          Disabled Pressed
+        <% end %>
+      </div>
+    <% end %>
+
+    <%= render Docs::ComponentPreviewComponent.new(
+      title: "Disabled",
+      preview_content: disabled_html,
+      code: toggle_disabled_code,
+      ai_command: toggle_disabled_code
+    ) %>
+
+    <!-- Variants Example -->
+    <% variants_html = capture do %>
+      <div class="flex gap-2">
+        <%= render M9sh::ToggleComponent.new(variant: :default) do %>
+          Default
+        <% end %>
+        <%= render M9sh::ToggleComponent.new(variant: :outline) do %>
+          Outline
+        <% end %>
+      </div>
+    <% end %>
+
+    <%= render Docs::ComponentPreviewComponent.new(
+      title: "Variants",
+      preview_content: variants_html,
+      code: toggle_variants_code,
+      ai_command: toggle_variants_code
+    ) %>
+
+    <!-- Sizes Example -->
+    <% sizes_html = capture do %>
+      <div class="flex items-center gap-2">
+        <%= render M9sh::ToggleComponent.new(size: :sm) do %>
+          Small
+        <% end %>
+        <%= render M9sh::ToggleComponent.new(size: :default) do %>
+          Default
+        <% end %>
+        <%= render M9sh::ToggleComponent.new(size: :lg) do %>
+          Large
+        <% end %>
+      </div>
+    <% end %>
+
+    <%= render Docs::ComponentPreviewComponent.new(
+      title: "Sizes",
+      preview_content: sizes_html,
+      code: toggle_sizes_code,
+      ai_command: toggle_sizes_code
+    ) %>
+  <% end %>
+
+  <% page.with_api do %>
+    <%= render Docs::PropTableComponent.new(
+      props: [
+        {
+          name: "variant",
+          type: "Symbol",
+          default: ":default",
+          description: "The visual style variant. Options: :default, :outline"
+        },
+        {
+          name: "size",
+          type: "Symbol",
+          default: ":default",
+          description: "The size of the toggle. Options: :sm, :default, :lg"
+        },
+        {
+          name: "pressed",
+          type: "Boolean",
+          default: "false",
+          description: "Whether the toggle is in the pressed (on) state"
+        },
+        {
+          name: "disabled",
+          type: "Boolean",
+          default: "false",
+          description: "Whether the toggle is disabled"
+        }
+      ]
+    ) %>
+  <% end %>
+<% end %>

data/app/views/docs/components/tooltip.html.erb

@@ -0,0 +1,216 @@
+<%= render Docs::ComponentPageComponent.new(title: "Tooltip") do |page| %>
+  <% page.with_header(
+    name: "Tooltip",
+    description: "A popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it."
+  ) %>
+
+  <% page.with_installation(component_name: "tooltip") %>
+
+  <% page.with_usage do %>
+    <%= render Docs::CodeBlockComponent.new(
+      code: tooltip_usage_code,
+      language: "erb"
+    ) %>
+  <% end %>
+
+  <% page.with_examples do %>
+    <!-- Default Example -->
+    <% default_html = capture do %>
+      <div class="flex justify-center items-center p-8">
+        <%= render M9sh::TooltipComponent.new do |tooltip| %>
+          <% tooltip.with_trigger do %>
+            <button class="px-4 py-2 rounded-md border bg-background hover:bg-muted transition-colors">
+              Hover me
+            </button>
+          <% end %>
+          <% tooltip.with_tooltip_content do %>
+            This is a tooltip
+          <% end %>
+        <% end %>
+      </div>
+    <% end %>
+
+    <%= render Docs::ComponentPreviewComponent.new(
+      title: "Default",
+      preview_content: default_html,
+      code: tooltip_default_code,
+      ai_command: tooltip_default_code
+    ) %>
+
+    <!-- Different Positions Example -->
+    <% positions_html = capture do %>
+      <div class="flex justify-center items-center gap-8 p-16">
+        <%= render M9sh::TooltipComponent.new(side: "top") do |tooltip| %>
+          <% tooltip.with_trigger do %>
+            <button class="px-4 py-2 rounded-md border bg-background hover:bg-muted transition-colors">
+              Top
+            </button>
+          <% end %>
+          <% tooltip.with_tooltip_content do %>
+            Tooltip on top
+          <% end %>
+        <% end %>
+
+        <%= render M9sh::TooltipComponent.new(side: "right") do |tooltip| %>
+          <% tooltip.with_trigger do %>
+            <button class="px-4 py-2 rounded-md border bg-background hover:bg-muted transition-colors">
+              Right
+            </button>
+          <% end %>
+          <% tooltip.with_tooltip_content do %>
+            Tooltip on right
+          <% end %>
+        <% end %>
+
+        <%= render M9sh::TooltipComponent.new(side: "bottom") do |tooltip| %>
+          <% tooltip.with_trigger do %>
+            <button class="px-4 py-2 rounded-md border bg-background hover:bg-muted transition-colors">
+              Bottom
+            </button>
+          <% end %>
+          <% tooltip.with_tooltip_content do %>
+            Tooltip on bottom
+          <% end %>
+        <% end %>
+
+        <%= render M9sh::TooltipComponent.new(side: "left") do |tooltip| %>
+          <% tooltip.with_trigger do %>
+            <button class="px-4 py-2 rounded-md border bg-background hover:bg-muted transition-colors">
+              Left
+            </button>
+          <% end %>
+          <% tooltip.with_tooltip_content do %>
+            Tooltip on left
+          <% end %>
+        <% end %>
+      </div>
+    <% end %>
+
+    <%= render Docs::ComponentPreviewComponent.new(
+      title: "Different Positions",
+      preview_content: positions_html,
+      code: tooltip_positions_code,
+      ai_command: tooltip_positions_code
+    ) %>
+
+    <!-- Rich Content Example -->
+    <% rich_content_html = capture do %>
+      <div class="flex justify-center items-center p-8">
+        <%= render M9sh::TooltipComponent.new do |tooltip| %>
+          <% tooltip.with_trigger do %>
+            <button class="px-4 py-2 rounded-md border bg-background hover:bg-muted transition-colors">
+              Hover for info
+            </button>
+          <% end %>
+          <% tooltip.with_tooltip_content do %>
+            <div class="space-y-1">
+              <p class="font-semibold">Pro Tip</p>
+              <p class="text-xs">You can use rich content in tooltips</p>
+            </div>
+          <% end %>
+        <% end %>
+      </div>
+    <% end %>
+
+    <%= render Docs::ComponentPreviewComponent.new(
+      title: "With Rich Content",
+      preview_content: rich_content_html,
+      code: tooltip_rich_content_code,
+      ai_command: tooltip_rich_content_code
+    ) %>
+  <% end %>
+
+  <% page.with_api do %>
+    <h3 class="text-lg font-semibold">TooltipComponent</h3>
+
+    <%= render Docs::PropTableComponent.new(
+      props: [
+        {
+          name: "side",
+          type: "String",
+          default: '"top"',
+          description: "The preferred side of the trigger to render against when open. Options: 'top', 'right', 'bottom', 'left'"
+        },
+        {
+          name: "delay",
+          type: "Number",
+          default: "200",
+          description: "The duration in milliseconds before the tooltip appears"
+        }
+      ]
+    ) %>
+
+    <h3 class="text-lg font-semibold mt-6">Slots</h3>
+
+    <%= render Docs::PropTableComponent.new(
+      props: [
+        {
+          name: "trigger",
+          type: "Slot",
+          default: "-",
+          description: "The element that triggers the tooltip on hover. This should be a focusable element."
+        },
+        {
+          name: "tooltip_content",
+          type: "Slot",
+          default: "-",
+          description: "The content to display in the tooltip"
+        }
+      ]
+    ) %>
+  <% end %>
+<% end %>
+
+<!-- Accessibility -->
+<div class="space-y-4">
+  <h2 class="text-2xl font-semibold border-b pb-2">Accessibility</h2>
+
+  <div class="space-y-3 text-sm">
+    <p>
+      The Tooltip component uses Stimulus to manage visibility and positioning:
+    </p>
+
+    <ul class="list-disc list-inside space-y-2 text-muted-foreground">
+      <li>
+        The tooltip appears after a configurable delay when hovering over the trigger element
+      </li>
+      <li>
+        The tooltip uses the <code class="text-xs bg-muted px-1 py-0.5 rounded">role="tooltip"</code> attribute for proper screen reader support
+      </li>
+      <li>
+        Tooltips should provide supplementary information, not critical content that can't be accessed otherwise
+      </li>
+      <li>
+        The tooltip is positioned dynamically based on the <code class="text-xs bg-muted px-1 py-0.5 rounded">side</code> parameter
+      </li>
+      <li>
+        Smooth animations provide visual feedback when showing and hiding
+      </li>
+    </ul>
+  </div>
+</div>
+
+<!-- Notes -->
+<div class="space-y-4">
+  <h2 class="text-2xl font-semibold border-b pb-2">Notes</h2>
+
+  <div class="space-y-3 text-sm">
+    <ul class="list-disc list-inside space-y-2 text-muted-foreground">
+      <li>
+        Tooltips are triggered on <code class="text-xs bg-muted px-1 py-0.5 rounded">mouseenter</code> and hidden on <code class="text-xs bg-muted px-1 py-0.5 rounded">mouseleave</code>
+      </li>
+      <li>
+        Use the <code class="text-xs bg-muted px-1 py-0.5 rounded">delay</code> parameter to control how quickly the tooltip appears
+      </li>
+      <li>
+        Tooltips are best used for short, informative text. For longer content, consider using a HoverCard or Popover instead
+      </li>
+      <li>
+        The tooltip content is styled with a dark background and light text by default
+      </li>
+      <li>
+        Multiple tooltips can exist on the same page independently
+      </li>
+    </ul>
+  </div>
+</div>