senren-ui 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 789980b8355793bdfee36c7d930fe41a2c3ed379bb3a38b6960485c62acc9c69
+  data.tar.gz: d54ebbc90d3ae06c0ea76a3cb5c6d331afb1598eec69c372358399eb6cd1b5f7
+SHA512:
+  metadata.gz: f863e1bb2132548ee87c6eae7b113f3b0fad9ef2b6d388e4c9cf688852a14c43812c95dc75fdc08c2123dfb0de7541a5cf4c47b595e47c9eb23220a4f7cace6f
+  data.tar.gz: '039c3f45102ebef05ef9dcd4cf2c8f64c7bdc8faa710baeffbe4f87ed061afc547f9390b2a2a8fea708e773d17bac07e47e06c05a2115c66217100a1f0632445'

data/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to `senren-ui` are recorded here.
+
+This project follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+v0.x is a pre-stable line: minor bumps may break things; patch bumps are
+bug fixes only.
+
+## [Unreleased]
+
+### Added
+
+- Initial gem skeleton, engine, and version constant.
+- Component registry (`registry/components.yml`, `groups.yml`,
+  `recipes.yml`) covering all Phase 1–6 components from the master plan.
+- Library classes: `Registry`, `HostPaths`, `ComponentCopier`,
+  `SkillWriter`, `LlmsWriter`, `Installer`, `Doctor`.
+- Generators: `senren:install`, `senren:component` (with `--client`).
+- Rake tasks: `senren:add`, `senren:skill:sync`, `senren:llms:generate`,
+  `senren:doctor`.
+- Phase 1–3 components fully implemented as ViewComponents.
+- Phase 4–6 components scaffolded as registered stubs.
+- Stimulus controllers for all interactive Phase 3 components.
+- Tailwind design-token stylesheet (`senren.css`) with light/dark.
+- Centralized `.senren/skill.md` system with preserved user-region.
+- `public/llms.txt` and `public/llms-full.txt` generation.
+- `apps/todolist` Rails app dogfooding the gem via local path.
+
+## [0.1.0] — TBD
+
+First tagged release once the Unreleased entries are validated end-to-end
+in `apps/todolist` per `plans/011_release_checklist.md`.

data/CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing to Senren UI
+
+Thanks for your interest. Senren is small and opinionated; please read
+this file before opening a PR.
+
+## Two non-negotiable rules
+
+1. **Plans before code.** Architectural changes start with a new or
+   updated file in `plans/` describing Purpose, Scope, Decisions, Files
+   to create, Files to modify, Expected behavior, Test strategy, and
+   Acceptance criteria.
+2. **History after work.** Every meaningful implementation session ends
+   with a new file in `history/YYYY-MM-DD-HHMM-<title>.md` recording
+   goal, changes, commands run, results, decisions, and next steps.
+
+## Local setup
+
+```bash
+git clone <repo>
+cd senren-rails
+bundle install
+bundle exec rake test
+```
+
+To exercise the gem against a real Rails app, use the bundled workspace:
+
+```bash
+cd ../apps/todolist
+bundle install
+bin/rails db:setup
+bin/rails generate senren:install
+bin/rails senren:add button card badge alert
+bin/rails server
+```
+
+## What to forbid in PRs
+
+- React, Vue, Alpine, lit, or any other JS framework dependency.
+- Network calls from Stimulus controllers (Turbo handles server state).
+- Hard-coded color utilities (`gray-*`, `slate-*`, etc.) in component
+  templates — use semantic tokens (`bg-background`, `text-foreground`).
+- New per-component markdown files for AI agents — Senren uses one
+  centralized `.senren/skill.md`.
+
+## Component checklist (Definition of Done)
+
+- ViewComponent Ruby class under `Senren::` namespace.
+- ERB template with `data-senren-component="<name>"` on root.
+- Tailwind classes use semantic tokens only.
+- Variants/sizes declared as class-level constants.
+- Stimulus controller iff client behavior is needed
+  (`app/javascript/controllers/senren/<name>_controller.js`).
+- Component test in `test/components/`.
+- System test in `test/system/` if interactive.
+- Registry entry in `registry/components.yml` (full schema).
+- Skill block produced by `SkillWriter`.
+- Demo usage in `apps/todolist` if relevant to the Todo UI.
+
+## Commit hygiene
+
+- One logical change per commit.
+- Mention the affected plan and history files in the commit body.
+- Run `bundle exec rake test` before pushing.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Senren UI Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,135 @@
+# Senren UI (`senren-ui`)
+
+> 洗練 — refined, polished, sophisticated.
+
+A Rails-native UI component library built on **ViewComponent**, **Hotwire
+(Turbo + Stimulus)**, and **TailwindCSS**, with a centralized AI-agent
+skill system and a source-copy install model inspired by shadcn/ui.
+
+## What Senren is
+
+- A Rails engine + generators that ship UI components into your host app.
+- A registry of well-tested ViewComponents and Stimulus controllers.
+- A centralized `.senren/skill.md` file so AI coding agents understand
+  every installed component, its dependencies, and its anti-patterns.
+- An `llms.txt` / `llms-full.txt` generator so AI agents can discover
+  Senren without scraping your codebase.
+
+## What Senren is not
+
+- Not React, Vue, Alpine, or any external state framework.
+- Not a CSS-only kit — components ship Ruby + ERB + (optional) Stimulus.
+- Not an opaque dependency — installed components live in your app
+  under `app/components/senren/` and you own them.
+
+## Installation
+
+Add to your Rails app's `Gemfile`:
+
+```ruby
+gem "senren-ui", path: "../../senren-rails", require: "senren/rails"   # local path during dev
+# or once published:
+# gem "senren-ui", require: "senren/rails"
+```
+
+Then:
+
+```bash
+bundle install
+bin/rails generate senren:install
+bin/rails senren:add button card badge alert form input \
+  textarea native_select table dropdown_menu dialog alert_dialog
+```
+
+## Daily commands
+
+```bash
+bin/rails generate senren:install           # one-time setup
+bin/rails generate senren:component picker --client  # custom component with Stimulus
+bin/rails generate senren:component picker --no-client  # without Stimulus
+bin/rails senren:add dialog --client        # install interactive official component
+bin/rails senren:add button                 # install static official component
+bin/rails senren:skill:sync                 # rebuild .senren/skill.md
+bin/rails senren:llms:generate              # rebuild public/llms*.txt
+bin/rails senren:doctor                     # check installation health
+```
+
+## Using a component
+
+```erb
+<%= render Senren::ButtonComponent.new(variant: :primary) do %>
+  Save changes
+<% end %>
+
+<%= render Senren::CardComponent.new do |card| %>
+  <% card.with_header { "Account settings" } %>
+  <% card.with_body   { "Manage your account details." } %>
+  <% card.with_footer do %>
+    <%= render(Senren::ButtonComponent.new(variant: :primary)) { "Save" } %>
+  <% end %>
+<% end %>
+```
+
+## Workspace layout
+
+This repository ships as a workspace with a real Rails dogfooding app:
+
+```text
+senren-workspace/
+  senren-rails/        # the local gem source directory
+  apps/
+    todolist/          # real Rails app that uses senren-ui via local path
+```
+
+`apps/todolist` is the production-like acceptance test for Senren — a
+small SaaS-style Todo manager built entirely from Senren components.
+
+## AI Agent skill system
+
+After install, your app contains:
+
+- `.senren/skill.md` — centralized component guide for AI agents,
+  grouped by Actions / Forms / Overlays / Navigation / Layout /
+  Data Display / SaaS Blocks / Rich Content.
+- `.senren/registry.yml` — mirror of the gem-side registry.
+- `.senren/installed_components.yml` — ledger of installed components.
+- `.senren/conventions.md` — Senren conventions for humans and agents.
+- `public/llms.txt`, `public/llms-full.txt` — discoverable AI summary.
+
+The skill file uses `<!-- senren:skill:start -->` / `:end` markers; only
+the region between them is rewritten by the generator, so any notes you
+add outside the markers are preserved.
+
+## Component list
+
+See `registry/components.yml` for the canonical list. v0.1 ships:
+
+- **Phase 1 — Foundation** (full): Button, Link, Badge, Typography,
+  Separator, Skeleton, Avatar, Alert, Card, AspectRatio.
+- **Phase 2 — Forms** (full): Form, Input, Textarea, Checkbox,
+  CheckboxGroup, RadioButton, NativeSelect, Select, Switch, MaskedInput.
+- **Phase 3 — Overlays** (full): Dialog, AlertDialog, DropdownMenu,
+  Popover, Tooltip, HoverCard, Sheet, ContextMenu.
+- **Phases 4–6** (scaffolded stubs): Navigation/Layout, Data/Advanced,
+  SaaS Blocks. Each is registered, has a class, and renders a clearly
+  marked placeholder until promoted to full implementation.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test            # gem tests
+bundle exec rake test:system     # Stimulus/system tests
+```
+
+## Contributing
+
+See `CONTRIBUTING.md`. Two rules to know up front:
+
+1. Every meaningful change creates or updates a file in `history/`.
+2. Architectural decisions are captured in `plans/` before code is
+   written.
+
+## License
+
+MIT — see `LICENSE`.

data/Rakefile

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb'].exclude('test/system/**/*_test.rb')
+  t.warning = false
+end
+
+namespace :test do
+  Rake::TestTask.new(:system) do |t|
+    t.libs << 'test'
+    t.libs << 'lib'
+    t.test_files = FileList['test/system/**/*_test.rb']
+    t.warning = false
+  end
+end
+
+task default: :test

data/docs/visual_style.md

@@ -0,0 +1,51 @@
+# Senren Visual Style
+
+Senren's default visual direction is **Spring Garden SaaS**: modern Rails UI
+components with the color warmth of Japanese garden illustration, the tactile
+quality of risograph print, and the restraint needed for real product screens.
+
+## Vocabulary
+
+- **Spring**: fresh, bright, optimistic color without candy-like saturation.
+- **Japanese garden**: pond blue, sakura pink, young leaf green, iris violet,
+  warm paper, and deep pine ink.
+- **Risograph-adjacent**: flat color fields, gentle grain when used in
+  marketing surfaces, and clear shape boundaries.
+- **SaaS-practical**: readable tables, forms, dialogs, and dashboards. Color
+  supports hierarchy; it does not replace hierarchy.
+- **Elegant**: small radius, calm borders, controlled shadows, generous but
+  not decorative spacing.
+
+## Core Palette
+
+Use the semantic `--senren-*` tokens in component templates. The named palette
+tokens are available for documentation, examples, and branded surfaces.
+
+| Token | Role |
+| --- | --- |
+| `--senren-background` | warm paper app background |
+| `--senren-foreground` | deep pine ink text |
+| `--senren-primary` | main action green |
+| `--senren-secondary` | sakura surface |
+| `--senren-accent` | pond blue hover and highlight |
+| `--senren-muted` | soft young leaf surface |
+| `--senren-border` | pale waterline borders |
+| `--senren-palette-sky` | illustration and brand accent |
+| `--senren-palette-sakura` | illustration and secondary surfaces |
+| `--senren-palette-pond` | panels, previews, and selected surfaces |
+| `--senren-palette-leaf` | success and growth accents |
+| `--senren-palette-iris` | secondary visual accent |
+| `--senren-palette-paper` | warm neutral surface |
+
+## Component Rules
+
+- Prefer semantic tokens over raw color utilities.
+- Keep primitives quiet: buttons, inputs, cards, tables, menus, and dialogs
+  must stay usable in dense SaaS screens.
+- Use colorful surfaces mostly for state, focus, hover, badges, empty states,
+  callouts, and documentation previews.
+- Avoid black-and-white defaults unless contrast requires it.
+- Avoid one-hue themes; every screen should have a warm neutral, green, blue,
+  and one soft floral accent available.
+- Do not use noisy grain inside core form controls, tables, or menus. Grain is
+  for marketing areas, illustrations, and preview frames only.

data/lib/generators/senren/component/component_generator.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'rails/generators/named_base'
+require 'senren/rails'
+
+module Senren
+  module Generators
+    # Low-level generator for creating a custom component in the host app.
+    #
+    #   bin/rails generate senren:component picker
+    #   bin/rails generate senren:component picker --no-client
+    class ComponentGenerator < ::Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      class_option :client, type: :boolean, default: true,
+                            desc: 'Generate a Stimulus controller alongside the component.'
+
+      def create_component_class
+        template 'component.rb.tt',
+                 "app/components/senren/#{file_name}_component.rb"
+      end
+
+      def create_component_template
+        template 'component.html.erb.tt',
+                 "app/components/senren/#{file_name}_component.html.erb"
+      end
+
+      def create_component_test
+        template 'component_test.rb.tt',
+                 "test/components/senren/#{file_name}_component_test.rb"
+      end
+
+      def create_stimulus_controller
+        return unless options[:client]
+
+        template 'controller.js.tt',
+                 "app/javascript/controllers/senren/#{file_name}_controller.js"
+      end
+
+      def create_system_test
+        return unless options[:client]
+
+        template 'system_test.rb.tt',
+                 "test/system/senren/#{file_name}_test.rb"
+      end
+
+      private
+
+      def file_name
+        super.underscore
+      end
+
+      def class_name
+        file_name.camelize
+      end
+
+      def stimulus_identifier
+        "senren--#{file_name.dasherize}"
+      end
+    end
+  end
+end

data/lib/generators/senren/component/templates/component.html.erb.tt

@@ -0,0 +1,3 @@
+<div <%%= tag.attributes(**root_attrs("rounded-md border border-border bg-background p-4 text-foreground"<% if options[:client] %>, data: { controller: "<%= stimulus_identifier %>" }<% end %>)) %>>
+  <%%= content %>
+</div>

data/lib/generators/senren/component/templates/component.rb.tt

@@ -0,0 +1,13 @@
+module Senren
+  class <%= class_name %>Component < BaseComponent
+    VARIANTS = {
+      default: ""
+    }.freeze
+
+    SIZES = {
+      sm: "",
+      md: "",
+      lg: ""
+    }.freeze
+  end
+end

data/lib/generators/senren/component/templates/component_test.rb.tt

@@ -0,0 +1,16 @@
+require "test_helper"
+
+class Senren::<%= class_name %>ComponentTest < ViewComponent::TestCase
+  test "renders with default variant" do
+    render_inline(Senren::<%= class_name %>Component.new) { "hello" }
+
+    assert_selector "[data-senren-component='<%= file_name %>']"
+    assert_text "hello"
+  end
+
+  test "rejects unknown variant" do
+    assert_raises(ArgumentError) do
+      Senren::<%= class_name %>Component.new(variant: :nope)
+    end
+  end
+end

data/lib/generators/senren/component/templates/controller.js.tt

@@ -0,0 +1,23 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Stimulus controller for Senren <%= class_name %>.
+// Identifier: <%= stimulus_identifier %>
+//
+// Responsibilities (local UI only):
+// - Manage open/close, focus, or keyboard behavior for this component.
+// Forbidden:
+// - fetch / XHR (Turbo handles server state)
+// - importing React, Vue, Alpine, lit, or any other framework
+export default class extends Controller {
+  static targets = []
+  static values  = {}
+  static classes = []
+
+  connect() {
+    // initialization
+  }
+
+  disconnect() {
+    // cleanup
+  }
+}

data/lib/generators/senren/component/templates/system_test.rb.tt

@@ -0,0 +1,7 @@
+require "application_system_test_case"
+
+class Senren::<%= class_name %>Test < ApplicationSystemTestCase
+  test "<%= file_name %> connects its Stimulus controller" do
+    skip "Add a demo route or fixture page that renders Senren::<%= class_name %>Component, then assert behavior here."
+  end
+end

data/lib/generators/senren/install/install_generator.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'rails/generators/base'
+require 'senren/rails'
+
+module Senren
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      class_option :force, type: :boolean, default: false,
+                           desc: 'Overwrite existing Senren-managed files.'
+
+      def create_senren_dir
+        empty_directory '.senren'
+      end
+
+      def create_components_dir
+        empty_directory 'app/components/senren'
+      end
+
+      def create_stimulus_dir
+        empty_directory 'app/javascript/controllers/senren'
+      end
+
+      def create_assets_dir
+        empty_directory 'app/assets/stylesheets'
+      end
+
+      def create_public_dir
+        empty_directory 'public'
+      end
+
+      def copy_base_files
+        template 'base_component.rb.tt', 'app/components/senren/base_component.rb'
+        template 'senren.css.tt',                'app/assets/stylesheets/senren.css'
+        template 'conventions.md.tt',            '.senren/conventions.md'
+        template 'installed_components.yml.tt',  '.senren/installed_components.yml'
+      end
+
+      def mirror_registry
+        copy_file Senren::Rails.registry_path, '.senren/registry.yml'
+      end
+
+      def write_skill_file
+        say_status :senren, 'writing .senren/skill.md'
+        Senren::Rails::SkillWriter.new(paths: host_paths).sync!
+      end
+
+      def write_llms_files
+        say_status :senren, 'writing public/llms.txt and public/llms-full.txt'
+        Senren::Rails::LlmsWriter.new(paths: host_paths).generate!
+      end
+
+      def print_next_steps
+        say "\nSenren installed."
+        say 'Next: bin/rails senren:add button card badge alert dialog'
+      end
+
+      private
+
+      def host_paths
+        @host_paths ||= Senren::Rails::HostPaths.new(destination_root)
+      end
+    end
+  end
+end

data/lib/generators/senren/install/templates/base_component.rb.tt

@@ -0,0 +1,45 @@
+module Senren
+  # Base class for every Senren ViewComponent.
+  #
+  # Provides:
+  # - keyword-only constructor with `class_name:` (renamed from `class:`)
+  # - variant and size resolution against class-level constants
+  # - small class merger (no external `tailwind_merge` dependency in v0.1)
+  # - a default root-attribute helper that emits `data-senren-component="<name>"`
+  class BaseComponent < ViewComponent::Base
+    VARIANTS = { default: "" }.freeze
+    SIZES    = { md: "" }.freeze
+
+    attr_reader :class_name, :variant, :size, :html_attrs
+
+    def initialize(variant: :default, size: :md, class_name: nil, **html_attrs)
+      @variant = resolve!(variant, self.class::VARIANTS, :variant)
+      @size    = resolve!(size,    self.class::SIZES,    :size)
+      @class_name = class_name
+      @html_attrs = html_attrs
+    end
+
+    # Compose final root attributes; subclasses pass their base classes.
+    def root_attrs(*classes, **extra)
+      data = (extra.delete(:data) || {}).merge(senren_component: senren_component_name)
+      tag_class = merge_classes(classes, self.class::VARIANTS[@variant], self.class::SIZES[@size], @class_name, extra.delete(:class))
+      { class: tag_class, data: data, **html_attrs, **extra }
+    end
+
+    def senren_component_name
+      self.class.name.to_s.sub(/^Senren::/, "").sub(/Component$/, "").gsub(/([a-z])([A-Z])/, '\1_\2').downcase
+    end
+
+    private
+
+    def resolve!(value, table, label)
+      key = value.to_sym
+      return key if table.key?(key)
+      raise ArgumentError, "Unknown #{label}: #{value.inspect}. Allowed: #{table.keys.join(', ')}"
+    end
+
+    def merge_classes(*sources)
+      sources.flatten.map { |s| s.to_s.strip }.reject(&:empty?).join(" ")
+    end
+  end
+end

data/lib/generators/senren/install/templates/conventions.md.tt

@@ -0,0 +1,66 @@
+# Senren Conventions
+
+This file is for both human contributors and AI coding agents. Keep it short
+and obey it strictly.
+
+## Hard rules
+
+1. Use Senren components before writing custom HTML for the same purpose.
+2. Server-render via ViewComponent. Stimulus only for **local** behavior.
+3. Turbo handles server state. Controllers do not fetch/XHR from JS.
+4. No React, Vue, Alpine, lit, or external state framework. Ever.
+5. Tailwind classes must use **semantic tokens** (`bg-background`,
+   `text-foreground`, `bg-primary`, `text-muted-foreground`,
+   `border-border`, `bg-destructive`). Do not hard-code `gray-*`,
+   `slate-*`, `zinc-*`, etc. in component templates.
+6. Every component root carries `data-senren-component="<name>"` so DOM
+   inspection and tests can locate it.
+7. **Render with parens when passing inline content blocks**. Ruby block
+   precedence makes `render Senren::Foo.new(args) { "bar" }` attach the
+   block to `.new`, **not** to `render`, producing an empty component.
+   Use either of these forms instead:
+   ```erb
+   <%= render(Senren::ButtonComponent.new(variant: :primary)) { "Save" } %>
+
+   <%= render Senren::ButtonComponent.new(variant: :primary) do %>
+     Save
+   <% end %>
+   ```
+
+## File ownership
+
+| Path                                | Owned by         |
+| ----------------------------------- | ---------------- |
+| `app/components/senren/**`          | This app         |
+| `app/javascript/controllers/senren/**` | This app      |
+| `app/assets/stylesheets/senren.css` | This app         |
+| `.senren/skill.md`                  | Generated region only (between markers) |
+| `.senren/registry.yml`              | Generator (mirror of gem registry) |
+| `.senren/installed_components.yml`  | Generator (ledger)  |
+| `.senren/conventions.md`            | This file - safe to edit |
+| `public/llms.txt`                   | Generator (do not edit) |
+| `public/llms-full.txt`              | Generator (do not edit) |
+
+## Adding a component
+
+```bash
+bin/rails senren:add <name> [<name>...]
+bin/rails senren:add dialog --no-client     # override registry default
+bin/rails senren:add button --client        # override registry default
+```
+
+After install you can edit any file under `app/components/senren/` directly.
+Senren never overwrites those files unless you pass `--force`.
+
+## Skill file maintenance
+
+`.senren/skill.md` has a generated region delimited by:
+
+```
+<!-- senren:skill:start -->
+...generated...
+<!-- senren:skill:end -->
+```
+
+You can write app-specific notes outside those markers. They are preserved
+across `bin/rails senren:skill:sync`.

data/lib/generators/senren/install/templates/installed_components.yml.tt

@@ -0,0 +1,4 @@
+# This file is the ledger of Senren components installed in this app.
+# It is updated by `bin/rails senren:add` and `bin/rails senren:install`.
+# Do not edit by hand unless you know what you are doing.
+installed: []