velvetkit 0.1.0.beta

data/registry/app/javascript/controllers/ui/tabs_controller.ts

@@ -0,0 +1,74 @@
+import { Controller } from '@hotwired/stimulus';
+
+export default class extends Controller<HTMLElement> {
+  static targets = ['trigger', 'panel'];
+  static values = { active: String };
+
+  declare readonly triggerTargets: HTMLButtonElement[];
+  declare readonly panelTargets: HTMLElement[];
+  declare activeValue: string;
+
+  connect() {
+    // If no active value is set, activate the first non-disabled trigger
+    const value = this.activeValue || this.firstEnabledTriggerValue();
+    this.sync(value);
+  }
+
+  private firstEnabledTriggerValue(): string {
+    const enabled = this.triggerTargets.filter((t) => !t.disabled);
+    return enabled[0]?.dataset.value || '';
+  }
+
+  activate(event: Event) {
+    const btn = event.currentTarget as HTMLButtonElement;
+    if (btn.disabled) return;
+    const value = btn.dataset.value!;
+    this.activeValue = value;
+    this.sync(value);
+    btn.focus();
+  }
+
+  keydown(event: KeyboardEvent) {
+    const enabled = this.triggerTargets.filter((t) => !t.disabled);
+    if (enabled.length === 0) return;
+    const currentIndex = enabled.indexOf(event.currentTarget as HTMLButtonElement);
+    let next = -1;
+    switch (event.key) {
+      case 'ArrowRight':
+        next = (currentIndex + 1) % enabled.length;
+        break;
+      case 'ArrowLeft':
+        next = (currentIndex - 1 + enabled.length) % enabled.length;
+        break;
+      case 'Home':
+        next = 0;
+        break;
+      case 'End':
+        next = enabled.length - 1;
+        break;
+      default:
+        return;
+    }
+    event.preventDefault();
+    const target = enabled[next];
+    if (!target) return;
+    this.activeValue = target.dataset.value!;
+    this.sync(this.activeValue);
+    target.focus();
+  }
+
+  private sync(value: string) {
+    this.triggerTargets.forEach((t) => {
+      const active = t.dataset.value === value;
+      t.dataset.state = active ? 'active' : 'inactive';
+      t.setAttribute('aria-selected', active ? 'true' : 'false');
+      t.tabIndex = active ? 0 : -1;
+    });
+    this.panelTargets.forEach((p) => {
+      const active = p.dataset.value === value;
+      p.dataset.state = active ? 'active' : 'inactive';
+      if (active) p.removeAttribute('hidden');
+      else p.setAttribute('hidden', '');
+    });
+  }
+}

data/registry/app/javascript/controllers/ui/theme_controller.ts

@@ -0,0 +1,101 @@
+import { Controller } from '@hotwired/stimulus';
+
+// Connects to data-controller="ui--theme"
+//
+// Applies the `.dark` class to <html>, which is what `@custom-variant dark`
+// in application.css keys off. The stored preference is one of three values;
+// 'system' defers to the OS and keeps following it while selected. With
+// nothing stored, the page is light.
+//
+// The same resolution logic runs in an inline <head> script (see
+// layouts/_theme_script.html.erb) so the class is set before first paint. This
+// controller only handles changes made after load.
+type ThemePreference = 'system' | 'light' | 'dark';
+
+const STORAGE_KEY = 'ui-theme';
+
+export default class extends Controller<HTMLElement> {
+  static targets = ['option'];
+
+  declare readonly hasOptionTarget: boolean;
+  declare readonly optionTargets: HTMLElement[];
+
+  private media?: MediaQueryList;
+  private onSystemChange?: () => void;
+
+  connect() {
+    this.media = window.matchMedia('(prefers-color-scheme: dark)');
+    // An OS-level switch should move the page live, but only while the user
+    // has not pinned an explicit preference.
+    this.onSystemChange = () => {
+      if (this.preference() === 'system') this.apply();
+    };
+    this.media.addEventListener('change', this.onSystemChange);
+    this.apply();
+  }
+
+  disconnect() {
+    if (this.media && this.onSystemChange) {
+      this.media.removeEventListener('change', this.onSystemChange);
+    }
+  }
+
+  // data-action="ui--theme#select" data-theme="dark"
+  select(event: Event) {
+    const chosen = (event.currentTarget as HTMLElement)?.dataset.theme as
+      | ThemePreference
+      | undefined;
+    if (!chosen) return;
+
+    localStorage.setItem(STORAGE_KEY, chosen);
+    this.apply();
+  }
+
+  // Cycles light -> dark -> system, for a single-button toggle.
+  cycle() {
+    const order: ThemePreference[] = ['light', 'dark', 'system'];
+    const next = order[(order.indexOf(this.preference()) + 1) % order.length];
+    localStorage.setItem(STORAGE_KEY, next);
+    this.apply();
+  }
+
+  private preference(): ThemePreference {
+    const stored = this.readStored();
+    return stored === 'light' || stored === 'dark' || stored === 'system'
+      ? stored
+      : 'light';
+  }
+
+  // Private windows and blocked site data make localStorage throw on access,
+  // so every read is guarded; the page still renders in the light theme.
+  private readStored(): string | null {
+    try {
+      return localStorage.getItem(STORAGE_KEY);
+    } catch {
+      return null;
+    }
+  }
+
+  private resolved(): 'light' | 'dark' {
+    const preference = this.preference();
+    if (preference !== 'system') return preference;
+    return this.media?.matches ? 'dark' : 'light';
+  }
+
+  private apply() {
+    const dark = this.resolved() === 'dark';
+    document.documentElement.classList.toggle('dark', dark);
+    document.documentElement.dataset.theme = this.preference();
+    this.syncOptions();
+  }
+
+  private syncOptions() {
+    if (!this.hasOptionTarget) return;
+
+    const preference = this.preference();
+    this.optionTargets.forEach((option) => {
+      const selected = option.dataset.theme === preference;
+      option.setAttribute('aria-checked', selected ? 'true' : 'false');
+    });
+  }
+}

data/registry/app/javascript/controllers/ui/tooltip_controller.ts

@@ -0,0 +1,102 @@
+import { Controller } from '@hotwired/stimulus';
+import { useFloating, type Placement } from './_internal/use_floating.js';
+
+export default class extends Controller<HTMLElement> {
+  static targets = ['trigger', 'content', 'arrow'];
+
+  declare readonly triggerTarget: HTMLElement;
+  declare readonly contentTarget: HTMLElement;
+  declare readonly arrowTarget: HTMLElement;
+
+  private floatingCleanup: (() => void) | null = null;
+  private showTimeout: number | null = null;
+  private hideTimeout: number | null = null;
+  private isVisible = false;
+
+  // Configuration
+  private readonly openDelay = 150;
+  private readonly closeDelay = 100;
+
+  connect() {
+    // Initialize with content hidden
+    this.hideContent();
+  }
+
+  disconnect() {
+    this.clearTimeouts();
+    this.cleanupFloating();
+  }
+
+  show() {
+    this.clearTimeouts();
+    this.showTimeout = window.setTimeout(() => {
+      this.showContent();
+    }, this.openDelay);
+  }
+
+  hide() {
+    this.clearTimeouts();
+    this.hideTimeout = window.setTimeout(() => {
+      this.hideContent();
+    }, this.closeDelay);
+  }
+
+  private showContent() {
+    if (this.isVisible) return;
+
+    const placement = this.getPlacement();
+    // Offset = visible gap (8) + arrow protrusion (~6: 4px staticSide + ~2px
+    // diamond corner from rotate-45). Without this margin the arrow tip hugs
+    // the trigger edge and reads as "overlapped".
+    const floating = useFloating(this.triggerTarget, this.contentTarget, {
+      placement,
+      offset: 14,
+      flip: true,
+      shift: true,
+      arrow: this.arrowTarget,
+    });
+
+    this.floatingCleanup = floating.destroy;
+    this.contentTarget.removeAttribute('hidden');
+    this.contentTarget.dataset.state = 'open';
+    this.isVisible = true;
+  }
+
+  private hideContent() {
+    if (!this.isVisible) return;
+
+    this.cleanupFloating();
+    this.contentTarget.setAttribute('hidden', '');
+    this.contentTarget.dataset.state = 'closed';
+    this.isVisible = false;
+  }
+
+  private cleanupFloating() {
+    if (this.floatingCleanup) {
+      this.floatingCleanup();
+      this.floatingCleanup = null;
+    }
+  }
+
+  private clearTimeouts() {
+    if (this.showTimeout) {
+      clearTimeout(this.showTimeout);
+      this.showTimeout = null;
+    }
+    if (this.hideTimeout) {
+      clearTimeout(this.hideTimeout);
+      this.hideTimeout = null;
+    }
+  }
+
+  private getPlacement(): Placement {
+    const side = this.contentTarget.dataset.side || 'top';
+    const align = this.contentTarget.dataset.align || 'center';
+
+    if (align === 'center') {
+      return side as Placement;
+    }
+
+    return `${side}-${align}` as Placement;
+  }
+}

data/registry/app/javascript/velvetkit_icons.ts

@@ -0,0 +1,58 @@
+// Lucide icons for VelvetKit components.
+//
+// The Icon component renders `<i data-lucide="name">`; createIcons swaps each
+// one for its SVG. Only the icons listed here are bundled, so an icon your
+// own views use has to be added in BOTH places below — one only in the import
+// list renders as an empty element with a console warning and no error.
+import {
+  createIcons,
+  Calendar,
+  Check,
+  ChevronDown,
+  ChevronLeft,
+  ChevronRight,
+  ChevronsUpDown,
+  CircleAlert,
+  Ellipsis,
+  Eye,
+  EyeOff,
+  Info,
+  Loader,
+  Mail,
+  Monitor,
+  Moon,
+  PanelLeft,
+  Sun,
+  X,
+} from 'lucide';
+
+const icons = {
+  Calendar,
+  Check,
+  ChevronDown,
+  ChevronLeft,
+  ChevronRight,
+  ChevronsUpDown,
+  CircleAlert,
+  Ellipsis,
+  Eye,
+  EyeOff,
+  Info,
+  Loader,
+  Mail,
+  Monitor,
+  Moon,
+  PanelLeft,
+  Sun,
+  X,
+};
+
+// Turbo replaces markup without a full page load, so icons are drawn again
+// after every kind of render, not just the first.
+[
+  'turbo:load',
+  'turbo:frame-load',
+  'turbo:render',
+  'turbo:submit-end',
+  'turbo:render-stream',
+].forEach((event) => document.addEventListener(event, () => createIcons({ icons })));

data/registry/app/views/layouts/_theme_script.html.erb

@@ -0,0 +1,19 @@
+<%# Resolves the stored theme and sets `.dark` on <html> BEFORE first paint.
+    The JS bundle is loaded as a deferred module, so it runs after paint —
+    without this blocking script every page flashes light before going dark.
+    Mirrors the resolution logic in controllers/ui/theme_controller.ts.
+    Render it inside <head> with render "layouts/theme_script". %>
+<%= javascript_tag nonce: true do %>
+  (function () {
+    try {
+      var stored = null;
+      try { stored = localStorage.getItem('ui-theme'); } catch (e) {}
+      var pref = stored === 'dark' || stored === 'system' ? stored : 'light';
+      var dark = pref === 'dark' ||
+        (pref === 'system' &&
+         window.matchMedia('(prefers-color-scheme: dark)').matches);
+      document.documentElement.classList.toggle('dark', dark);
+      document.documentElement.dataset.theme = pref;
+    } catch (e) {}
+  })();
+<% end %>

data/registry/components.yml

@@ -0,0 +1,102 @@
+# The VelvetKit catalog.
+#
+# Only what the source files cannot say lives here. Which files make up a
+# component, which other components it renders, and which Stimulus controllers
+# and npm packages it needs are all read from the files themselves by
+# Velvetkit::Registry, so they cannot drift out of date.
+
+# Versions of the npm packages the components import.
+packages:
+  "@floating-ui/dom": "^1.7.4"
+  "@hotwired/stimulus": "^3.2.2"
+  ag-grid-community: "^36.1.0"
+  cally: "^0.9.2"
+  lucide: "^0.545.0"
+  tw-animate-css: "^1.4.0"
+
+# Versions of the gems a component needs beyond view_component and tailwind_merge.
+gems:
+  pagy: "~> 43.0"
+
+components:
+  accordion:
+    description: Sections that expand and collapse, one at a time or several.
+  alert:
+    description: A highlighted message, optionally dismissible.
+  avatar:
+    description: A person's picture, with initials when there is none.
+  avatar_group:
+    description: Overlapping avatars with a "+N" count for the rest.
+  badge:
+    description: A small status label.
+  banner:
+    description: A dismissible strip across the top of a page.
+  base:
+    description: The base class every component inherits — variants and class merging.
+  breadcrumb:
+    description: The path to the current page, collapsing long trails.
+  button:
+    description: Buttons in every variant and size, with icons and a loading state.
+  button_to:
+    description: A button that submits a one-off form, like Rails' button_to.
+  card:
+    description: A bordered container with header, content and footer.
+  checkbox:
+    description: A checkbox with label, standalone or bound to a form builder.
+  data_grid:
+    description: A sortable, filterable, server-paged table on AG Grid.
+  date_picker:
+    description: A typed date field with a calendar, on Cally.
+  dialog:
+    description: A modal dialog on the native <dialog> element.
+  divider:
+    description: A horizontal or vertical rule, optionally labelled.
+  icon:
+    description: A Lucide icon.
+  image:
+    description: An image with consistent sizing and corner radius.
+  input:
+    description: A text field with label, hint and error, standalone or with a form builder.
+  input_group:
+    description: A text field with addons before or after it.
+  label:
+    description: A form label with a required marker.
+  link:
+    description: A link styled as text or as a button.
+  menu:
+    description: A dropdown menu with keyboard navigation.
+  pagination:
+    description: Page links for a long list, from a Pagy object.
+    gems: [pagy]
+  password_input:
+    description: A password field with a show/hide toggle.
+  popover:
+    description: Floating content anchored to a trigger.
+  radio_group:
+    description: A set of radio buttons.
+  native_select:
+    description: The browser's own select, styled closed; best for phones' system pickers.
+  select:
+    description: A styled dropdown with keyboard navigation and type-ahead, posting like a native select.
+  sheet:
+    description: A panel that slides in from an edge of the screen.
+  sidebar:
+    description: A collapsible application sidebar with groups and menus.
+  spinner:
+    description: A loading indicator.
+  switch:
+    description: An on/off toggle.
+  table:
+    description: A styled table with header, rows and caption.
+  tabs:
+    description: Tabbed panels with keyboard navigation.
+  text:
+    description: Body text in set sizes, weights and tones.
+  theme_toggle:
+    description: A light/dark/system theme switcher.
+    files:
+      - app/views/layouts/_theme_script.html.erb
+  tooltip:
+    description: A hint shown on hover and focus.
+  typography:
+    description: Headings, lead, muted, code and blockquote text styles.

data/registry/config/locales/velvetkit.en.yml

@@ -0,0 +1,56 @@
+# Strings rendered by VelvetKit components. Translate by copying this file
+# to velvetkit.<locale>.yml and changing the values, never the keys.
+en:
+  date:
+    formats:
+      # How DatePicker writes and reads a date: its placeholder, parse order
+      # and separator all come from this one string. Change it per locale.
+      typed: "%d/%m/%Y"
+  ui:
+    date_picker:
+      open: 'Open the calendar'
+      # `format` is a reserved I18n interpolation key, hence `pattern`.
+      hint: 'Type the date as %{pattern}, or use the calendar'
+      previous: 'Previous month'
+      next: 'Next month'
+    data_grid:
+      empty: 'Nothing to show'
+    breadcrumb:
+      label: 'Breadcrumb'
+      ellipsis_label: 'More breadcrumb pages'
+      collapsed_pages_label: 'Collapsed breadcrumb pages'
+    alert:
+      close_label: 'Close alert'
+    button:
+      loading: 'Loading, please wait'
+    spinner:
+      label: 'Loading'
+    dialog:
+      close_label: 'Close'
+    password_input:
+      show: 'Show password'
+      hide: 'Hide password'
+    sidebar:
+      toggle: 'Toggle sidebar'
+    pagination:
+      label: 'Pages'
+      summary: 'Showing %{from}–%{to} of %{count}'
+      previous: 'Go to previous page'
+      previous_label: 'Previous'
+      next: 'Go to next page'
+      next_label: 'Next'
+      more: 'More pages'
+    select:
+      placeholder: 'Choose…'
+      search: 'Search'
+      search_label: 'Search the options'
+      no_matches: 'No matches'
+      # Shown on a multiple select once more than two options are ticked.
+      selected: '%{count} selected'
+    theme_toggle:
+      label: 'Change theme'
+      heading: 'Theme'
+      options:
+        light: 'Light'
+        dark: 'Dark'
+        system: 'System'

data/registry/docs/agents.md

@@ -0,0 +1,62 @@
+# VelvetKit components in this app
+
+This app builds its UI from VelvetKit components: ViewComponents styled with
+Tailwind CSS 4 and wired up with Stimulus. They were copied into the app by
+the `velvetkit` gem and are now the app's own code, under `UI::`.
+
+Use them for every new screen. Reach for raw HTML and Tailwind only when no
+component fits, and never build a second version of a component that exists.
+
+## Where things are
+
+- Components: `app/components/ui/` (`UI::Button` is `app/components/ui/button.rb`)
+- Their Stimulus controllers: `app/javascript/controllers/ui/`, registered as `ui--<name>`
+- Tests: `test/components/ui/` (Minitest, `render_inline`)
+- Lookbook previews: `test/components/previews/ui/`
+- Design tokens: `app/assets/tailwind/velvetkit.css`
+- Strings: `config/locales/velvetkit.en.yml`, under `ui.`
+- Icons: `app/javascript/velvetkit_icons.ts`
+
+## Rules
+
+1. **Render, with slots.** Components take keyword arguments and fill their
+   parts through `with_*` slots in a block:
+
+   ```erb
+   <%= render(UI::Card.new) do |card| %>
+     <% card.with_header do |header| %>
+       <% header.with_title { "Billing" } %>
+     <% end %>
+     <% card.with_content { "…" } %>
+   <% end %>
+   ```
+
+2. **Pass `class:` to adjust, not to restyle.** Your classes are merged with
+   the component's by tailwind_merge, and yours win on conflict. For a
+   different look, use a `variant:` or `size:` the component already has.
+
+3. **Never hardcode colours.** Use the tokens: `bg-primary`,
+   `text-muted-foreground`, `border-input`, `bg-card`, `text-destructive`.
+   They switch with dark mode. Hex values and `blue-600` don't.
+
+4. **Need a component the app doesn't have yet?** Add it from the kit rather
+   than writing one: `bin/rails generate velvetkit:add <name>`. It copies the
+   component with everything it depends on, and refreshes this file.
+   Available: {{available}}.
+
+5. **Icons are Lucide names** (`UI::Icon.new(name: "calendar")`). An icon the
+   app hasn't used before must be added to `app/javascript/velvetkit_icons.ts`,
+   in both the import list and the `icons` object, or it renders empty.
+
+6. **User-facing text goes through I18n**, as the components' own strings do.
+
+7. **Changing a component is fine**, it's app code. Keep its test passing, and
+   update its Lookbook preview so the change can be seen.
+
+8. **Links that look like buttons** use `UI::Link.new(href:, variant:, button_variant: true)`.
+   Without `button_variant: true` a link is styled as text.
+
+## Components installed here
+
+Each section below lists a component's arguments, slots and working
+examples. The examples are the same templates its Lookbook previews render.

data/registry/test/components/previews/ui/accordion_preview/faq_style.html.erb

@@ -0,0 +1,20 @@
+<div class="max-w-lg">
+  <h2 class="text-xl font-semibold mb-4">Frequently Asked Questions</h2>
+  <%= render(UI::Accordion.new(type: :single)) do |accordion| %>
+    <% faqs = [
+      { q: "How do I reset my password?", a: "Go to Settings &gt; Security and click 'Change Password'. You'll need to enter your current password and your new password." },
+      { q: "Can I import data from another system?", a: "Yes, we import CSV and JSON files. Go to Admin &gt; Data Import and follow the wizard to map your fields." },
+      { q: "What integrations are available?", a: "Most tools connect through our API and webhooks, and the integrations page lists ready-made ones." },
+      { q: "Is there a mobile app?", a: "Yes, for iOS and Android. Search for it in your phone's app store." },
+      { q: "How do I contact support?", a: 'Email us at support@example.com or use the live chat widget in the bottom-right corner of your dashboard.' }
+    ] %>
+    <% faqs.each_with_index do |faq, i| %>
+      <% accordion.with_item(value: "faq-#{i}") do |item| %>
+        <% item.with_trigger { faq[:q] } %>
+        <% item.with_content do %>
+          <p class="text-muted-foreground"><%= faq[:a].html_safe %></p>
+        <% end %>
+      <% end %>
+    <% end %>
+  <% end %>
+</div>

data/registry/test/components/previews/ui/accordion_preview/multiple.html.erb

@@ -0,0 +1,27 @@
+<div class="max-w-md">
+  <%= render(UI::Accordion.new(type: :multiple, default_value: ["item-1", "item-3"])) do |accordion| %>
+    <% accordion.with_item(value: "item-1") do |item| %>
+      <% item.with_trigger { "Features" } %>
+      <% item.with_content do %>
+        <ul class="list-disc list-inside text-sm text-muted-foreground space-y-1">
+          <li>Projects and tasks</li>
+          <li>Time tracking</li>
+          <li>Grade reporting</li>
+          <li>Client portal</li>
+        </ul>
+      <% end %>
+    <% end %>
+    <% accordion.with_item(value: "item-2") do |item| %>
+      <% item.with_trigger { "Pricing" } %>
+      <% item.with_content do %>
+        <p class="text-sm text-muted-foreground">We offer flexible pricing plans for teams of all sizes. Contact our sales team for a custom quote.</p>
+      <% end %>
+    <% end %>
+    <% accordion.with_item(value: "item-3") do |item| %>
+      <% item.with_trigger { "Support" } %>
+      <% item.with_content do %>
+        <p class="text-sm text-muted-foreground">24/7 support via email and chat. Premium plans include dedicated account managers and phone support.</p>
+      <% end %>
+    <% end %>
+  <% end %>
+</div>

data/registry/test/components/previews/ui/accordion_preview/single.html.erb

@@ -0,0 +1,22 @@
+<div class="max-w-md">
+  <%= render(UI::Accordion.new(type: :single, default_value: "item-1")) do |accordion| %>
+    <% accordion.with_item(value: "item-1") do |item| %>
+      <% item.with_trigger { "What is a workspace?" } %>
+      <% item.with_content do %>
+        <p class="text-muted-foreground">A workspace holds your team, projects and billing in one place. Everyone you invite sees the same projects.</p>
+      <% end %>
+    <% end %>
+    <% accordion.with_item(value: "item-2") do |item| %>
+      <% item.with_trigger { "How do I get started?" } %>
+      <% item.with_content do %>
+        <p class="text-muted-foreground">Create an account, name your workspace and invite your team. A short setup guide walks you through each step.</p>
+      <% end %>
+    <% end %>
+    <% accordion.with_item(value: "item-3") do |item| %>
+      <% item.with_trigger { "Is my data secure?" } %>
+      <% item.with_content do %>
+        <p class="text-muted-foreground">Yes. We use industry-standard encryption and follow GDPR to ensure your data is protected.</p>
+      <% end %>
+    <% end %>
+  <% end %>
+</div>

data/registry/test/components/previews/ui/accordion_preview.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+class UI::AccordionPreview < ViewComponent::Preview
+  # @label Playground
+  # @param type select { choices: [single, multiple] }
+  def playground(type: :single)
+    render(UI::Accordion.new(type: type.to_sym, default_value: "item-1")) do |accordion|
+      accordion.with_item(value: "item-1") do |item|
+        item.with_trigger { "Is it accessible?" }
+        item.with_content do
+          tag.p(class: "text-muted-foreground") { "Yes. It adheres to the WAI-ARIA design pattern." }
+        end
+      end
+      accordion.with_item(value: "item-2") do |item|
+        item.with_trigger { "Is it styled?" }
+        item.with_content do
+          tag.p(class: "text-muted-foreground") { "Yes. It comes with default styles that match the other components' aesthetic." }
+        end
+      end
+    end
+  end
+
+  # @label Single (one open at a time)
+  def single; render_with_template; end
+
+  # @label Multiple (independent items)
+  def multiple; render_with_template; end
+
+  # @label FAQ Style
+  def faq_style; render_with_template; end
+end