Add docs site

Author: stevegeek

lib/tasks/website.rake

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+namespace :website do
+  WEBSITE_DIR = File.expand_path("../../website", __dir__)
+
+  desc "Render demo components and write HTML/source fragments into the docs site"
+  task :demos do
+    require File.expand_path("../../test/dummy/config/environment", __dir__)
+    require "fileutils"
+
+    out = File.join(WEBSITE_DIR, "_includes", "demos")
+    FileUtils.mkdir_p(out)
+
+    demos = [
+      {
+        slug: "release_card",
+        title: "Deploy dashboard release card",
+        component: Dashboard::ReleaseCardComponent,
+        args: {release_id: 1, name: "API Gateway", version: "2.4.1", environment: :production, status: :deployed},
+        # The release card emits a sibling card and a third "pending" card so
+        # the demo shows the dynamic `status:` class colours side by side.
+        siblings: [
+          {release_id: 2, name: "Auth Service", version: "1.9.0", environment: :staging, status: :pending},
+          {release_id: 3, name: "Web Frontend", version: "3.0.0-rc1", environment: :preview, status: :failed}
+        ],
+        source_path: "test/dummy/app/components/dashboard/release_card_component.rb"
+      }
+    ]
+
+    demos.each do |demo|
+      html = Vident::StableId.with_sequence_generator(seed: "vident-docs-#{demo[:slug]}") do
+        rendered = demo[:component].new(**demo[:args]).call
+        Array(demo[:siblings]).each do |sibling_args|
+          rendered += demo[:component].new(**sibling_args).call
+        end
+        rendered
+      end
+      # Strip the development-only "Before ..." HTML comment that the dummy
+      # ApplicationComponent injects so the embedded fragment stays clean.
+      html = html.gsub(/<!--\s*Before [^>]*?-->/, "").strip
+
+      source = File.read(File.expand_path("../../#{demo[:source_path]}", __dir__))
+
+      File.write(File.join(out, "#{demo[:slug]}_rendered.html"), html + "\n")
+      File.write(File.join(out, "#{demo[:slug]}_source.rb"), source)
+      File.write(File.join(out, "#{demo[:slug]}_html.html"), pretty_html(html))
+      puts "  rendered #{demo[:slug]} → #{html.bytesize} bytes"
+    end
+
+    puts "Wrote demos to #{out}"
+  end
+
+  desc "Build the documentation website"
+  task build: :demos do
+    Dir.chdir(WEBSITE_DIR) do
+      sh "bundle install"
+      sh "bundle exec jekyll build"
+    end
+  end
+
+  desc "Serve the documentation website locally with live reload"
+  task serve: :demos do
+    Dir.chdir(WEBSITE_DIR) do
+      sh "bundle install"
+      sh "bundle exec jekyll serve --livereload"
+    end
+  end
+
+  desc "Clean the documentation website build"
+  task :clean do
+    Dir.chdir(WEBSITE_DIR) do
+      sh "bundle exec jekyll clean"
+    end
+  end
+
+  # Pretty-prints the rendered fragment for the "Raw HTML" tab. Nokogiri
+  # escapes `>` inside attribute values to `&gt;` (correct HTML5, but ugly to
+  # read), so we unescape that back — the result is still valid HTML and
+  # matches what a developer would expect to see in their source.
+  def pretty_html(html)
+    require "nokogiri"
+    Nokogiri::HTML5.fragment(html).to_xhtml(indent: 2).gsub("&gt;", ">")
+  end
+end

test/dummy/app/components/dashboard/release_card_component.rb

@@ -2,37 +2,18 @@
 
 module Dashboard
   class ReleaseCardComponent < ApplicationComponent
-    # Lock the stimulus identifier to match the V1 component's, so the
-    # existing `app_components/dashboard/release_card_component_controller.js`
-    # still resolves against this V2 component without duplication.
-    # Emitted `data-controller="dashboard--release-card-component"`.
-    class << self
-      def stimulus_identifier_path = "dashboard/release_card_component"
-    end
-
     prop :release_id, Integer
     prop :name, String
     prop :version, String
     prop :environment, _Union(:production, :staging, :preview), default: :staging
     prop :status, _Union(:pending, :deployed, :failed), default: :pending
 
-    # `stimulus_outlet_host:` is inherited from Vident::Component. Passing
-    # the parent page at render time causes this card to call
-    # `host.add_stimulus_outlets(self)` in after_initialize, which wires a
-    # `data-dashboard--page-component-dashboard--release-card-component-outlet`
-    # attribute onto the host's root element.
-
     stimulus do
-      # Mirrors the :release_id / :name / :status props straight through as
-      # Stimulus values. No second declaration needed — the Resolver reads
-      # the `@ivar` current value at render time.
       values_from_props :release_id, :name, :status
 
-      # Proc evaluated in the component instance, so it sees @status. The DSL
-      # emits a `data-<controller>-status-class="..."` attribute on the root
-      # which Stimulus exposes as `this.statusClasses` in the JS controller.
-      # `class_list_for_stimulus_classes(:status)` below inlines the same
-      # resolved value into the `class=` attribute for the first render.
+      # Procs run in the component instance at render time, so they see
+      # `@status`. `class_list_for_stimulus_classes(:status)` inlines the
+      # same value into `class=` for the first paint.
       classes status: -> {
         case @status
         when :deployed then "border-green-500 bg-green-50"
@@ -41,9 +22,6 @@ def stimulus_identifier_path = "dashboard/release_card_component"
         end
       }
 
-      # Fluent builder: reads left-to-right as "the `select` method fires
-      # on the `click` event". Emits `click->implied#select`. Equivalent
-      # V1-style shorthand `actions [:click, :select]` still works.
       action(:select).on(:click)
     end
 
@@ -64,12 +42,9 @@ def view_template
         p(class: "mt-3 text-xs uppercase tracking-wide text-gray-500") { @status.to_s }
 
         div(class: "mt-3 flex gap-2") do
-          # Demo of Stimulus params: one `apply` handler for both buttons, with
-          # `stimulus_params: { kind: ... }` on the element so the handler reads
-          # `event.params.kind` to tell which button fired. In a real app you'd
-          # probably just keep separate `promote` / `cancel` handlers — this
-          # intentional "one dispatch switch" shape is a bit RPC-ish and is
-          # here to show what the params feature looks like.
+          # Both buttons share an `apply` handler; the controller reads
+          # `event.params.kind` to tell them apart, matching each button's
+          # `stimulus_params:` declaration.
           card.child_element(
             :button,
             stimulus_action: [:click, :apply],

website/.gitignore

@@ -0,0 +1,6 @@
+_site/
+.jekyll-cache/
+.jekyll-metadata
+.sass-cache/
+Gemfile.lock
+vendor/

website/Gemfile

@@ -0,0 +1,19 @@
+source "https://rubygems.org"
+
+# Jekyll site generator. The vitepress theme requires Jekyll 4.3+ and Ruby 3.1+.
+gem "jekyll", "~> 4.4"
+gem "jekyll-vitepress-theme"
+
+group :jekyll_plugins do
+  gem "jekyll-feed", "~> 0.17"
+  gem "jekyll-sitemap", "~> 1.4"
+end
+
+# Windows / JRuby zoneinfo support — kept for parity with the encoded_id site.
+platforms :mingw, :x64_mingw, :mswin, :jruby do
+  gem "tzinfo", ">= 1", "< 3"
+  gem "tzinfo-data"
+end
+
+gem "wdm", "~> 0.1", platforms: [:mingw, :x64_mingw, :mswin]
+gem "http_parser.rb", "~> 0.6.0", platforms: [:jruby]

website/README.md

@@ -0,0 +1,45 @@
+# Vident Documentation Website
+
+Static documentation site built with Jekyll and the
+[jekyll-vitepress-theme](https://github.com/crmne/jekyll-vitepress-theme).
+The site deploys to Cloudflare Pages from `main` (see
+`.github/workflows/website.yml`).
+
+## Local development
+
+From the repository root:
+
+```bash
+# Build the site (also re-renders the live demo HTML / sources)
+bundle exec rake website:demos website:build
+
+# Serve with live reload at http://localhost:4000
+bundle exec rake website:serve
+
+# Clean generated output
+bundle exec rake website:clean
+```
+
+Or, manually inside `website/`:
+
+```bash
+cd website
+bundle install
+bundle exec jekyll serve
+```
+
+## How the live demo on the landing page works
+
+The landing page leads with a working component (`PhlexGreeters::GreeterVidentComponent`
+from the dummy app). Because Cloudflare Pages serves static HTML only, we
+pre-render the example at build time:
+
+- `rake website:demos` renders the Phlex component to HTML and writes the
+  fragment, the Vident source, and a pretty-printed copy of the rendered
+  HTML into `website/_includes/demos/`.
+- `website/assets/js/demo.js` ships a tiny Stimulus bundle (loaded from a CDN)
+  that registers the controllers under the same identifiers the rendered
+  components use, so the demo is interactive in the browser without a server.
+
+If you change the demo component, re-run `rake website:demos` to refresh the
+embedded fragments.

website/_config.yml

@@ -0,0 +1,75 @@
+title: Vident
+tagline: Type-safe Rails components with first-class Stimulus
+description: >-
+  Vident builds typed, Stimulus-wired components for Rails on top of Phlex
+  or ViewComponent. A single declarative DSL replaces the data-attribute
+  boilerplate, with intelligent Tailwind class merging and component caching.
+url: "https://vident.dev"
+baseurl: ""
+github_username: stevegeek
+github_repo: vident
+
+theme: jekyll-vitepress-theme
+plugins:
+  - jekyll-vitepress-theme
+  - jekyll-feed
+  - jekyll-sitemap
+
+markdown: kramdown
+kramdown:
+  input: GFM
+  syntax_highlighter: rouge
+permalink: pretty
+
+# Collections power the sidebar groups. Each `_<name>/` folder becomes a group;
+# pages are ordered by `nav_order` frontmatter inside each group.
+collections:
+  introduction:
+    output: true
+    permalink: /introduction/:path/
+  guides:
+    output: true
+    permalink: /guides/:path/
+  reference:
+    output: true
+    permalink: /reference/:path/
+
+defaults:
+  - scope: { path: "", type: "introduction" }
+    values: { layout: "default" }
+  - scope: { path: "", type: "guides" }
+    values: { layout: "default" }
+  - scope: { path: "", type: "reference" }
+    values: { layout: "default" }
+
+jekyll_vitepress:
+  branding:
+    site_title: Vident
+    logo: /assets/img/vident-logo.svg
+  syntax:
+    light_theme: github
+    dark_theme: github.dark
+  edit_link:
+    pattern: "https://github.com/stevegeek/vident/edit/main/website/:path"
+    text: Edit this page on GitHub
+  footer:
+    message: Released under the MIT License.
+    copyright: "Copyright © 2023–{{ 'now' | date: '%Y' }} Stephen Ierodiaconou"
+  # Light mode leads with the logo's red; dark mode swaps to its yellow so
+  # links/CTAs stay legible on a dark background.
+  tokens:
+    light:
+      "--vp-c-brand-1": "#cf3a13"
+      "--vp-c-brand-2": "#b13110"
+      "--vp-c-brand-3": "#92290d"
+    dark:
+      "--vp-c-brand-1": "#fbbf24"
+      "--vp-c-brand-2": "#f59e0b"
+      "--vp-c-brand-3": "#d97706"
+
+exclude:
+  - Gemfile
+  - Gemfile.lock
+  - vendor/
+  - node_modules/
+  - README.md

website/_data/navigation.yml

@@ -0,0 +1,11 @@
+- title: Introduction
+  url: /introduction/getting-started/
+  collections: [introduction]
+- title: Guides
+  url: /guides/components/
+  collections: [guides]
+- title: Reference
+  url: /reference/stimulus-dsl/
+  collections: [reference]
+- title: Changelog
+  url: https://github.com/stevegeek/vident/blob/main/CHANGELOG.md

website/_data/sidebar.yml

@@ -0,0 +1,6 @@
+- title: Introduction
+  collection: introduction
+- title: Guides
+  collection: guides
+- title: Reference
+  collection: reference

website/_data/social_links.yml

@@ -0,0 +1,6 @@
+- icon: github
+  link: https://github.com/stevegeek/vident
+  label: Vident on GitHub
+- icon: rubygems
+  link: https://rubygems.org/gems/vident
+  label: Vident on RubyGems

website/_guides/caching.md

@@ -0,0 +1,46 @@
+---
+title: Component caching
+nav_order: 5
+---
+
+# Component caching
+
+Vident exposes a `cache_component` helper on both the Phlex and
+ViewComponent adapters. It's a thin wrapper around Rails' fragment
+caching that scopes the cache key to the component, so expensive renders
+become a single cache lookup once warmed.
+
+```ruby
+class ProductCardComponent < Vident::ViewComponent::Base
+  prop :product, Product
+
+  def call
+    cache_component(@product) do
+      root_element do |card|
+        # …expensive markup…
+      end
+    end
+  end
+end
+```
+
+The cache key is composed from the component class, its props (or an
+explicit dependency you pass in), and the request-scoped ID seed, so:
+
+- Two requests rendering the same component with the same props share a
+  cache entry.
+- Within a single request, repeated renders of a cached fragment keep
+  consistent element IDs (the seed makes them deterministic), so
+  Stimulus controllers wire up correctly to the rehydrated HTML.
+
+### Tips
+
+- Pass an explicit cache dependency (`cache_component([@product, @user])`)
+  when the component reads things outside its props.
+- Stimulus values that read from procs evaluate **before** the cache lookup,
+  so they're stable across cache hits.
+- For per-user output that should not be cached together, include the user
+  (or their role) in the cache key.
+
+For the broader cache key story and the seeding rationale, see
+[Element IDs and seeding](/reference/element-ids/).