senren-ui 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d99681351df1dad873d945bf82b3070b3f8393c9d14b3ca65917262e6258ef6c
-  data.tar.gz: b487d9ac589b1d9ba2c304a5f53e4d93064b321d76e97a43ccfa1b9909a44b58
+  metadata.gz: 99b7430e710e44023cbc886c862b4d237d06bb489a4a00f5e30685b59768f6dc
+  data.tar.gz: 6ead04eac8e4e518cbf7129c65dfb63ad683db3dfb44b13a794366eee8be37dd
 SHA512:
-  metadata.gz: f383e88dea3c90da1f1f93831bdf26c4bc5e00e1c63ffeb8ae53031d7c7e38c8afbaa30c445839cdbf8ad346acf247dcd04ae597c01b23704837daeb4eb4c2bf
-  data.tar.gz: 54e1f4ad10351c05906cdf1f864160cd3a0555e1698c0fa4944a728752cd97560300a9bae40a337a214a39d19eae87a3620fd4690e412d689b9430d022df0662
+  metadata.gz: 7cf42a8f5992b7de9bc4135c7d6bea7c44987ca3844de06b575876957877efd773711cdfcb9cd54d2ddc1ca878f38842d4df082b0fb7451b5b63613c9bb5f056
+  data.tar.gz: e3c329bc7eb8ef0c7b90af18971c92f24dfdea4822e17a9e43faff3b1e94a6815ed4b6c18cff30a2e65932cd8bf96d88b2e64153671d72e2a52c8ffe2d759c76

data/CHANGELOG.md

@@ -7,6 +7,244 @@ 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.
 
+## [0.4.0] — 2026-10-08
+
+### Added
+
+- **Every word a component shows or announces can be translated from the host
+  app, without editing a component.** Visible text, `aria-label` and `sr-only`
+  text, the defaults of `label:`, `placeholder:` and `empty_text:`, the
+  calendar's month and weekday names, and the sentences a Stimulus controller
+  says after load now go through one helper, `senren_t`, with the English as its
+  default: `senren_t('pagination.next', default: 'Next')` is
+  `I18n.t("senren.pagination.next", default: "Next")`. 111 keys across 27
+  components, named `senren.<component>.<key>`, with `senren.shared.*` for the
+  two words that are the same word in several components.
+
+  An app with no locale file renders exactly what it did before, and a missing
+  translation never raises, including under
+  `config.i18n.raise_on_missing_translations`. Text you pass in yourself is used
+  as given and never looked up; `label: nil` still means "none", and leaving the
+  argument out is what gets the translated default.
+
+  The gem ships `senren.en.yml` and `senren.vi.yml`, and copies either only
+  when asked for: `bin/rails generate senren:install --locales vi`, or later
+  `bin/rails senren:locales vi`. Not even English is copied by default: a copied
+  `senren.en.yml` loads after the app's `en.yml`, overriding any `senren.*` key
+  set there, and pins today's wording against later releases. An existing file
+  is never overwritten unless that is asked for by name
+  (`senren:locales vi --force`, or `senren:install --force-locales`); the
+  `--force` that refreshes Senren's own files leaves translations alone. To add
+  another language, `bin/rails senren:locales en`, copy the file, change `en:`,
+  and translate the values. A translation with a misspelt `%{variable}` falls
+  back to the English instead of raising. See [docs/i18n.md](docs/i18n.md).
+
+  `bin/i18n-sync` regenerates `templates/locales/senren.en.yml` from the code,
+  and a test fails if it, `senren.vi.yml`, and the components disagree, or if a
+  template shows a word that did not go through `senren_t`.
+
+### Changed
+
+- **Five Stimulus controllers no longer carry an English sentence.** `clipboard`
+  ("Copied", "Copied to clipboard"), `api_key_field` ("Copy complete"),
+  `carousel` ("Slide 2 of 3"), `theme_toggle` ("Light theme", "Dark theme") and
+  `rich_text_editor_lite` (the link prompt) read the sentence from a Stimulus
+  value the component renders, so they speak the host's language. The markup
+  gains six `data-senren--<controller>-…-value` attributes and is otherwise
+  byte-for-byte what it was.
+
+  **Migrate:** none for an unmodified install. The controller and its component
+  go together: if you copied a component and edited its controller, or the other
+  way round, copy both again (`bin/rails senren:add <name> --force`) so the value
+  the controller reads is the one the component writes.
+- `bin/rails senren:add` appends `senren_t` to an existing
+  `app/components/senren/base_component.rb` that lacks it, so a component added
+  after upgrading the gem does not raise `NoMethodError`. Components you copied
+  earlier keep the English written into them until you copy them again.
+- The performance budgets for component source (140000 -> 150000 bytes) and for
+  the Stimulus payload (56000 -> 56500) are raised, with the reasons recorded in
+  `config/performance_budgets.yml`. The per-file caps and the gzip total are
+  unchanged.
+- **`NativeSelectComponent` defaults to its own chevron instead of the browser's
+  arrow** (`native_arrow: false`). A select was the one control in the library
+  with no visible state: the OS arrow cannot be styled or animated, so nothing
+  distinguished an open select from a closed one. The custom chevron already
+  existed, rotated on focus, and had to be asked for by name — which meant
+  nobody got it. Pass `native_arrow: true` to opt back in; worth doing on
+  mobile, where the OS renders its own picker anyway.
+
+  The component marker moves with it. In custom-arrow mode
+  `data-senren-component="native_select"` sits on the wrapper that positions the
+  chevron, and the `<select>` underneath still carries the name, the controller
+  and the selection. Anything selecting on `select[data-senren-component]` needs
+  updating.
+- `InviteMemberDialogComponent` renders its role field through
+  `NativeSelectComponent` rather than a hand-written `<select>` whose styling
+  had been copied out of it — which is why it silently missed everything that
+  component gained afterwards, the chevron included.
+
+### Fixed
+
+- `FormComponent` yields the Rails form builder, as `docs/components.md` always
+  said it did. The block received the component instead, and because a
+  component is an `ActionView::Base` the documented `f.text_field :title,
+  class: "x"` did not raise: it reached the template-level helper and rendered
+  `name="title[{class: "x"}]"`, so the field posted under a name no controller
+  reads. Blocks that never touch `f`, and `with_content`, render as before.
+
+  Code that treated `|f|` as the component breaks: `f.tag`, `f.link_to`,
+  `f.render`, `f.model` and `f.url` now raise `NoMethodError` on the builder.
+  Call those on the view instead. A `FormComponent` rendered with neither a
+  block nor content now renders an empty `<form>` rather than raising.
+- `TopNavComponent`'s default variant had no background. Its class,
+  `bg-[hsl(var(--senren-background))/0.88]`, put the alpha outside `hsl()`,
+  inside the brackets, so Tailwind emitted `hsl(...)/0.88` verbatim and the
+  browser dropped it as an invalid colour: the sticky header was transparent
+  over scrolled content. It is now `bg-[hsl(var(--senren-background)/0.88)]`,
+  the form every other translucent class in the library uses, and a test bans
+  the broken shape across `templates/` and `lib/`.
+- `TableComponent` and `DataTableComponent` are now `relative`, so their
+  `sr-only` caption is positioned inside the component. `sr-only` is
+  `position: absolute`, and with nothing positioned the caption escaped the
+  components' own overflow clipping and was placed against the page. In a
+  fixed-height shell whose `<main>` scrolls, a captioned table below the fold
+  made the document taller, and the window scrolled into blank space under a
+  shell that should never scroll.
+- `DataTableComponent` no longer breaks a `<td>` whose cell holds markup. The
+  cell value was written straight into `data-sort-value="..."`, and a badge,
+  link or anything else built with `tag` or `render` is a SafeBuffer, which ERB
+  does not escape: the markup's first `"` closed the attribute, the rest became
+  junk attributes, and every row sorted on the same `<span class=` fragment.
+  The sort value is now the cell's decoded text, escaped once, so a cell
+  showing `R&D` sorts as `R&D`. Plain-string and numeric cells are unchanged.
+- `ThemeToggleComponent` rendered the letters `O`, `D` and `L` where an icon
+  belongs. It now ships sun and moon SVGs and swaps which is hidden, so the
+  correct icon is in the HTML the server sends rather than written in by
+  JavaScript after first paint. The icon names the theme the click switches to,
+  matching the label.
+- `AccordionComponent` showed a static `+` and snapped open. It now has a
+  chevron that turns over, driven by `aria-expanded` so the icon cannot drift
+  out of step with the state assistive technology is told, and the panel
+  animates via `grid-template-rows: 0fr → 1fr` — which reaches the content's own
+  height without measuring it in JavaScript.
+
+  The `hidden` attribute is kept through the animation. Content that is visually
+  collapsed but present is still focusable and still read aloud, so the
+  controller drops `hidden` before opening and restores it once the closing
+  transition ends, with a timer for the cases where `transitionend` never
+  arrives: reduced motion, an off-screen element, an already-collapsed panel.
+
+## [0.3.0] — 2026-09-01
+
+### Breaking
+
+- **`ButtonComponent` no longer emits `type="button"` by default.** The
+  attribute is omitted, so a button inside a form submits it, which is what
+  plain HTML does and what everyone expects. The old default silently swallowed
+  submits: a form's own submit button did nothing, with no error anywhere to
+  explain it. The new default fails the other way, and loudly — a trigger that
+  should not submit now has to say so.
+
+  **Migrate:** pass `type: :button` to any button that must not submit — overlay
+  triggers, menu triggers, a dialog's Cancel. Everything inside a form that is
+  meant to submit needs no change and starts working. Buttons outside a form
+  are unaffected either way.
+
+  ```erb
+  <%= render(Senren::ButtonComponent.new(type: :button)) { "Open dialog" } %>
+  ```
+
+### Fixed
+
+- Every component now merges a caller's `class:` and `data:` instead of
+  dropping them. Splatting `**html_attrs` after the computed values replaced
+  them outright, so `class:` erased the component's own variant and size
+  styling and `data:` erased its `data-senren-component` marker.
+- For the eight wrapper components — dialog, alert dialog, sheet, popover,
+  dropdown menu, context menu, hover card, tooltip — a caller's class now lands
+  on the panel, which is the element they style, not on the empty root, where it
+  sat in the DOM doing nothing.
+
+  This makes the extension point reachable; it does not make it resolve
+  conflicts. `class_name: "max-w-sm"` on a dialog emits
+  `class="max-w-lg max-w-sm"` and both declarations stay live, so which one
+  applies is decided by the order Tailwind emits them, not by the order of the
+  attribute. Measured against a real build: `max-w-sm` wins (narrowing works),
+  `max-w-2xl` loses (widening is a silent no-op). Use Tailwind's important
+  modifier — `class_name: "max-w-2xl!"` — for an override that does not depend
+  on emit order.
+- `data-controller` and `data-action` are appended rather than substituted, so
+  attaching your own Stimulus controller to a Senren component no longer unbinds
+  the component's own.
+- A caller's `data-controller` or `data-action` that repeated one of the
+  component's own tokens was appended rather than deduplicated:
+  `data: { controller: "a senren--popover" }` produced
+  `"a senren--popover senren--popover"`. Stimulus reads that list literally, so
+  the controller connected twice and every action fired twice — a toggle opened
+  and immediately closed. Tokens are deduplicated individually now.
+- `data:` written with String keys (`data: { "action" => ... }`) is merged the
+  same as Symbol keys. The Symbol-only read meant a dropdown item passing a
+  String key lost close-on-click and arrow-key handling.
+- A dropdown item's `class:` is merged rather than substituted. Losing the hover
+  style was cosmetic; losing `focus:bg-` removed the only indication a keyboard
+  user has of where they are in the menu.
+- Sheet's scrolling body no longer clips focus rings.
+- Dialog, sheet, and the invite-member dialog close on an overlay click.
+- `method:` on a dropdown item reaches Turbo. It was passed to `link_to` as a
+  rails-ujs option, which Rails 7 dropped, so it had rendered an inert `method`
+  attribute since the library began targeting Rails 7.1.
+- Card footer spacing, and pagination now wraps.
+- `CartComponent` accepted `remove_url:` per item, normalised it, and wrote it
+  nowhere. Removal is client-side and dispatches `senren--cart:removed` for the
+  application to act on, so the URL was the one thing the listener needed and
+  the only thing it could not get. It is emitted as `data-remove-url` on the
+  line and carried in the event detail, omitted entirely when not supplied, and
+  passed through `safe_url` like every other URL the library renders.
+- `senren_themes.css` shipped with its ERB examples unrendered, so the header
+  comment showed `<%%=` where it means `<%=`. The assertion guarding against that
+  named a single file, so the property held exactly where someone had thought to
+  look; it now runs over everything the generator writes.
+
+### Documentation
+
+- The palette presets shipped in 0.2.0 with no mention in the README, the docs,
+  or the generated conventions file. All three now cover them, including the
+  load-order constraint: `senren_themes.css` must be linked after `senren.css`
+  or the theme silently does nothing.
+
+### Internal
+
+- ERB linting names every linter it runs. Thirteen were running against nine
+  named in the config; eight formatting linters had been on by default and
+  unrecorded. A test now fails if an upgrade adds a fourteenth.
+- `bin/ci` and the GitHub workflow call `erb_lint` rather than the deprecated
+  `erblint` shim.
+- json bumped to 2.21.2 for CVE-2026-71847.
+- Herb now lints the markup, and the 32 offenses it found in shipped templates
+  are fixed. It was adopted after a developer reported warnings in their editor
+  that none of this project's gates produced — RuboCop covered the Ruby, Biome
+  the Stimulus controllers, erb_lint the ERB structure, and the HTML itself had
+  no linter at all. Pinned to 0.10.3 in `.herb.yml`, and wired into `bin/ci`,
+  `bin/lint-fix` and the GitHub workflow.
+
+  Most of what it found is invisible in the rendered page but visible in the
+  editor of anyone who installs these components, since `senren:add` copies them
+  into their repository. Fifteen component roots moved from
+  `<div <%= tag.attributes(**root_attrs(...)) %>>` to `tag.div(...) do`, which
+  is what the overlays already used; seven conditional boolean attributes moved
+  from `<%= "hidden" unless expanded %>` to `<% unless expanded %>hidden<% end %>`;
+  three raw `<img>` tags became `image_tag`; breadcrumb stopped writing its whole
+  `<nav>` once per branch; and an empty `aria-activedescendant` is gone.
+
+  Nothing changes visually, but the markup string is not identical: rendering
+  all 64 components before and after produces 35 differing lines — 26 of them
+  whitespace and indentation, 6 the attribute order and self-closing slash that
+  `image_tag` emits, 2 the `href` moving to the front of an `<a>`, and 1 the
+  removed empty attribute. If you assert on exact markup anywhere, those
+  snapshots need regenerating. If you have already installed these components,
+  nothing in your application changes at all — the new markup arrives only if
+  you re-run `senren:add --force`.
+
 ## [0.2.0] — 2026-08-02
 
 A hardening release. Most of it came out of an adversarial review of the whole

data/CONTRIBUTING.md

@@ -35,6 +35,8 @@ bin/matrix                            # unit tests on every supported Rails
 bundle exec rubocop
 bundle exec bundle-audit check --update
 bun run controllers:check
+bin/lint-fix                          # auto-fix RuboCop, ERB lint, controller JS
+bin/i18n-sync --check                 # templates/locales/senren.en.yml matches the components
 ```
 
 `bin/system` needs no setup: it uses a system Chrome and
@@ -86,6 +88,13 @@ real documentation/reference app is maintained separately in
 - ViewComponent Ruby class under `Senren::` namespace.
 - ERB template with `data-senren-component="<name>"` on root.
 - Tailwind classes use semantic tokens only.
+- Every word the component shows or announces (visible text, `aria-label`,
+  `sr-only`, a default `label:` or `placeholder:`, a sentence a controller will
+  say) goes through `senren_t('<component>.<key>', default: 'English')` with a
+  literal key and a literal default, and a controller receives it as a Stimulus
+  value, never as text in JavaScript. Run `bin/i18n-sync` to regenerate
+  `templates/locales/senren.en.yml` and add the same key to `senren.vi.yml`.
+  See `docs/i18n.md`.
 - Variants/sizes declared as class-level constants.
 - Stimulus controller iff client behavior is needed
   (`app/javascript/controllers/senren/<name>_controller.js`).
@@ -114,6 +123,8 @@ real documentation/reference app is maintained separately in
   templates, Stimulus controllers, or Importmap loading guidance.
 - Run `bun run controllers:check` before pushing if you touched
   `templates/controllers/*.js`.
+- Run `bin/i18n-sync --check` before pushing if you touched text in a
+  component; `bin/i18n-sync` fixes what it reports.
 
 ## Pull request workflow
 

data/README.md

@@ -53,6 +53,67 @@ bin/rails senren:add button card badge alert form input \
 bracketed Rake task form, `bin/rails 'senren:add[button,card]'`, remains
 supported for backward compatibility.
 
+## Palettes
+
+The install writes two stylesheets. `senren.css` is the token set every
+component renders against; `senren_themes.css` is optional and adds five
+alternate palettes.
+
+```erb
+<%= stylesheet_link_tag "senren" %>
+<%= stylesheet_link_tag "senren_themes" %>   <%# after senren.css %>
+```
+
+```erb
+<html data-senren-theme="rose">
+```
+
+`rose`, `slate`, `indigo`, `emerald`, `amber` — or omit the attribute for the
+default, Spring Garden. Order matters: `:root` and `[data-senren-theme="rose"]`
+have equal specificity, so the file that loads last wins. Reversed, nothing
+errors and the page quietly renders in the default palette.
+
+A theme is a re-declaration of the same tokens and nothing else. No component
+reads the attribute, so a sixth palette is a copied CSS block — no component
+change, no build step, no configuration. Switch at runtime with
+`document.documentElement.dataset.senrenTheme = "slate"`.
+
+Details and the token table: [docs/visual_style.md](docs/visual_style.md).
+
+## Translating components
+
+Every word a component shows or announces (labels, `aria-label` and
+screen-reader text, default placeholders, the calendar's month and weekday names,
+and what a Stimulus controller says after load) goes through one helper with its
+English as the default:
+
+```ruby
+senren_t('pagination.next', default: 'Next')   # I18n.t("senren.pagination.next", default: "Next")
+```
+
+An app with no locale file renders exactly the English it always did, and the
+installer copies none unless asked. To change a word, set its `senren.*` key in
+your own locale file. To add a language, copy a shipped file and translate it:
+
+```bash
+bin/rails generate senren:install --locales vi   # writes config/locales/senren.vi.yml
+bin/rails senren:locales en                      # every key and its English, to translate from
+```
+
+```yaml
+# config/locales/senren.fr.yml - copy senren.en.yml, change `en:` to `fr:`, translate the values
+fr:
+  senren:
+    pagination:
+      previous: "Précédent"
+      next: "Suivant"
+```
+
+The gem ships `en` and `vi`. A key you leave out stays English, and a missing
+key never raises. [docs/i18n.md](docs/i18n.md) has the key naming, the values a
+controller reads, what is not translated, and how to move components you copied
+before this existed.
+
 ## Daily commands
 
 ```bash
@@ -61,6 +122,7 @@ bin/rails generate senren:component picker --client  # custom component with Sti
 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:locales vi                 # copy a shipped translation to config/locales
 bundle exec rails senren:add form input     # equivalent alternate entry point
 bin/rails senren:skill:sync                 # rebuild .senren/skill.md
 bin/rails senren:agents:sync                # rebuild .senren/agent-rules + adapters
@@ -235,6 +297,8 @@ bin/performance                  # local payload/performance budgets
 bun run controllers:check        # lint + syntax check for templates/controllers/*.js
 bun run controllers:lint:fix     # auto-fix lint issues for controllers
 bundle exec rake test:system     # Stimulus/system tests
+bin/lint-fix                     # auto-fix RuboCop, ERB lint, and controller JS
+bin/i18n-sync                    # rewrite templates/locales/senren.en.yml from the senren_t calls
 ```
 
 ## Contributing

data/docs/i18n.md

@@ -0,0 +1,194 @@
+# Translating Senren components
+
+Every word a component shows or announces can be translated from your app's
+locale files, without editing a component. That covers the visible labels
+("Previous", "Next", "Close", "Today"), the `aria-label` and screen-reader text
+("Toggle sidebar", "Go to slide 2"), the defaults for arguments such as
+`label:` and `placeholder:`, the calendar's month and weekday names, and the
+sentences a Stimulus controller writes into the page after it loads ("Copied",
+"Slide 2 of 3").
+
+## How it works
+
+Each string goes through one helper, `senren_t`, with its English as the
+default:
+
+```ruby
+senren_t('pagination.next', default: 'Next')
+```
+
+That is `I18n.t("senren.pagination.next", default: "Next")`. If your app defines
+`senren.pagination.next` for the current locale it wins; if not, the English in
+the component is used. Two things follow:
+
+- **Nothing is required for English.** Install Senren, render a component, and it
+  says what it always said. There is no locale file to forget.
+- **A missing translation never raises**, not even with
+  `config.i18n.raise_on_missing_translations = true`, because I18n only reports
+  a key that has no default.
+
+Keys are `senren.<component>.<key>`. `senren.shared.*` holds the few words that
+are the same word in more than one component (`open`, `close`).
+
+## Install the locale files
+
+`senren:install` copies no locale file: English needs none. Every file is
+copied only when you ask for it by name:
+
+```bash
+bin/rails generate senren:install --locales vi   # at install time
+bin/rails senren:locales vi                      # any time later
+bin/rails senren:locales en                      # every key and its English, to translate from
+bin/rails senren:locales vi --force              # replace your copy with the shipped one
+```
+
+Today the gem ships `en` and `vi`. The files are yours once they are copied:
+the installer never overwrites one that exists unless you ask for that file to
+be replaced (`senren:locales <name> --force`, or `--force-locales` on
+`senren:install`). The `--force` that refreshes Senren's own files leaves them
+alone, so a re-run after a gem upgrade does not undo your wording.
+
+A copied `senren.en.yml` has two side effects, which is why it is not copied by
+default. Rails loads `config/locales` in name order, so it loads after your
+`en.yml` and overrides any `senren.*` key you set there. And it pins today's
+English: when a later Senren release improves a default, an app holding the copy
+keeps the old wording. Copy it to translate from, and delete it once your own
+language file exists.
+
+A translation is only loaded when its file is in `config/locales`, and a locale
+becomes known to I18n when a file for it is loaded. If your app builds a
+language switcher from `I18n.available_locales`, copying `senren.vi.yml` is what
+makes Vietnamese appear in it, which is why it is opt-in.
+
+## Change one word
+
+Define just that key in any locale file you already have. You do not need to
+copy the whole file:
+
+```yaml
+# config/locales/en.yml
+en:
+  senren:
+    pagination:
+      next: "Newer"
+      previous: "Older"
+```
+
+Everything you do not mention keeps its English. If you copied
+`config/locales/senren.en.yml`, edit the value there instead: that file loads
+after `en.yml` and wins.
+
+## Add a language
+
+1. Run `bin/rails senren:locales en`, then copy `config/locales/senren.en.yml` to
+   `config/locales/senren.fr.yml`.
+2. Change the top-level key from `en:` to `fr:`.
+3. Translate the values.
+
+```yaml
+fr:
+  senren:
+    pagination:
+      label: "Pagination"
+      previous: "Précédent"
+      next: "Suivant"
+    cart:
+      remove_item: "Retirer %{name}"
+```
+
+Keep every `%{name}` spelled exactly as it is. They are filled in when the
+component renders. A translation that names a variable the component does not
+pass (a typo such as `%{nmae}`) cannot be filled in, so that string falls back to
+its English rather than raising. You can
+move a variable anywhere in the sentence, and leave one out if the sentence does
+not need it. A key you delete falls back to English, so a partial translation is
+a working translation.
+
+Then select the locale the way your app already does, for example
+`I18n.locale = :fr` in an `around_action`. A word you did not translate shows in
+English, because the English is the default.
+
+If you would like the language included in the gem, send the file in a pull
+request: `templates/locales/senren.<locale>.yml`, with the same keys as
+`senren.en.yml`. `test/i18n_catalog_test.rb` checks that the keys and the
+`%{}` variables match.
+
+## Text you pass in yourself
+
+An argument you pass is used exactly as given and is never looked up:
+
+```erb
+<%= render Senren::PaginationComponent.new(label: "Pages", current_page: 2, total_pages: 5) %>
+```
+
+Only the argument you leave out gets the translated default. Two details:
+
+- `label: nil` still means "no label". For an attribute such as `aria-label` that
+  omits it, as it always has. Pass `""` for an empty string and leave the
+  argument out for the default.
+- Words that arrive as *data* are yours to supply: a column header built from the
+  key `:created_at` ("Created at"), the items of a menu, the text in a slot. Give
+  `TableComponent` and `DataTableComponent` a `label:` per column to control it.
+
+Values you interpolate into a translation are text. A name containing `<b>`
+shows as the characters `<b>`, not as an element.
+
+## What a controller says
+
+Five controllers write a sentence into the page after it loads. They no longer
+carry the English in JavaScript: the component renders each one into a Stimulus
+value, and the controller reads it.
+
+| Controller | Value | Key |
+| --- | --- | --- |
+| `clipboard` | `copied-status` | `senren.clipboard.copied_status` |
+| `api_key_field` | `copied-status` | `senren.api_key_field.copied_status` |
+| `carousel` | `status-template` | `senren.carousel.status` |
+| `theme_toggle` | `light-label`, `dark-label` | `senren.theme_toggle.light`, `.dark` |
+| `rich_text_editor_lite` | `link-prompt` | `senren.rich_text_editor_lite.link_prompt` |
+
+The carousel's value is a template. Its `%{current}` and `%{total}` are left in
+for the controller to fill in on every slide change, so a translation has to keep
+them.
+
+## Components you copied before this existed
+
+`bin/rails senren:add <anything>` adds the `senren_t` helper to your
+`app/components/senren/base_component.rb` if it is missing, so components you add
+from now on work.
+
+Components you copied earlier still have their English written into them. To
+translate one, copy it again with `bin/rails senren:add pagination --force`
+(which replaces any edits you made to that component), or change its strings by
+hand. It is one call per string: swap `"Next"` for
+`senren_t('pagination.next', default: 'Next')`. `senren.en.yml` lists the key for
+every string.
+
+## Writing a component or an edit that has text
+
+Anything a person reads or a screen reader announces goes through `senren_t`
+with a literal key and a literal English default:
+
+```ruby
+def initialize(label: senren_t('tabs.label', default: 'Tabs'), **html)
+```
+
+```erb
+<button><%= senren_t('date_picker.today', default: 'Today') %></button>
+<button aria-label="<%= senren_t('cart.remove_item', default: 'Remove %{name}', name: item[:name]) %>">
+```
+
+- Use the component's own namespace. Use `shared` only for a word that more than
+  one component says.
+- Put the English where the call is. Do not write it in a locale file first.
+- Give an argument its default in the signature, as above. Ruby evaluates it
+  when the component is built, in the locale that is current then.
+- A string a controller needs goes to it as a Stimulus value, never as text in the
+  JavaScript.
+- Symbols that are not words (`×`, `+`, `*`) stay as they are.
+
+If you are working on the gem itself, `bin/i18n-sync` regenerates
+`templates/locales/senren.en.yml` from the calls, and `bin/i18n-sync --check`
+reports whether it is current. `senren.vi.yml` is written by hand. The tests fail
+if the two files disagree with the code or with each other, if a call is not
+literal, and if a template shows a word that did not go through `senren_t`.

data/docs/visual_style.md

@@ -37,6 +37,86 @@ tokens are available for documentation, examples, and branded surfaces.
 | `--senren-palette-iris` | secondary visual accent |
 | `--senren-palette-paper` | warm neutral surface |
 
+## Palette Presets
+
+`senren.css` declares Spring Garden in `:root`. That is the default and needs no
+attribute. `senren_themes.css` adds five alternates, each one a re-declaration
+of the same token table:
+
+| `data-senren-theme` | Reads as |
+| --- | --- |
+| *(omitted)* | Spring Garden — warm paper, pine ink, garden green |
+| `rose` | warm pink, low contrast |
+| `slate` | neutral grey, high contrast |
+| `indigo` | cool blue-violet |
+| `emerald` | cool green |
+| `amber` | warm gold |
+
+```erb
+<%= stylesheet_link_tag "senren" %>
+<%= stylesheet_link_tag "senren_themes" %>
+```
+
+```erb
+<html data-senren-theme="rose">
+```
+
+**Load `senren_themes.css` after `senren.css`.** `:root` and
+`[data-senren-theme="rose"]` are equal specificity, so the later rule wins and
+source order is the whole mechanism. Reversed, both files load, the attribute is
+on `<html>`, nothing errors, and the page renders in the default palette — the
+one failure mode of this feature, and it looks like the theme file was never
+installed.
+
+The attribute goes on `<html>`, not on `<body>` or a wrapper, so it composes
+with the existing `.dark` class instead of replacing it. Light/dark stays
+orthogonal to palette: each preset ships both blocks.
+
+No component knows themes exist. They read `hsl(var(--senren-*))` and inherit
+whatever is in scope, which is why a sixth palette is a copied CSS block and
+nothing else — no component to touch, no build step, no configuration.
+
+Switching at runtime is one attribute write:
+
+```js
+document.documentElement.dataset.senrenTheme = "slate"
+```
+
+## Overriding a Component's Classes
+
+`class_name:` and `class:` are both merged into the element the component
+styles. Merged, not resolved — the component's own class stays in the list:
+
+```erb
+<%= render Senren::DialogComponent.new(class_name: "max-w-sm") %>
+<!-- panel renders class="… max-w-lg max-w-sm …" -->
+```
+
+Two `max-w-*` declarations with identical specificity, so the winner is whichever
+Tailwind emits later in the stylesheet. The order of the HTML attribute is not an
+input to that. Tailwind emits the named scale alphabetically, which measured
+against a real build means:
+
+| You pass | Against dialog's `max-w-lg` | Result |
+| --- | --- | --- |
+| `max-w-sm` | `sm` emitted after `lg` | applies |
+| `max-w-2xl` | `2xl` emitted before `lg` | **silently ignored** |
+
+Nothing about either class tells you which you are getting. For an override that
+does not depend on emit order, use Tailwind's important modifier:
+
+```erb
+<%= render Senren::DialogComponent.new(class_name: "max-w-2xl!") %>
+```
+
+This applies to any pair from one utility family — `w-`, `h-`, `p-`, `z-`,
+`text-`, `bg-`. It is not specific to widths. Senren does not ship a
+class-conflict resolver; adding one means a `tailwind_merge` dependency, which
+the library has so far chosen not to take.
+
+Classes from families the component does not use need no modifier — there is
+nothing to conflict with.
+
 ## Component Rules
 
 - Prefer semantic tokens over raw color utilities.