unmagic-components 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73a26932047bf5f5019925414115576c98d199f51e434ebae9e614423ba67022
-  data.tar.gz: 93be93b5f8b3c9c42c8224a0ec229635a270a89f5319477e0b99970cb4ab4e8c
+  metadata.gz: c204e77700223b87a5c4a2d019bb285de3dd24f9a9c1530aa54dd4b798f171a7
+  data.tar.gz: 91b9db1448f9a74a259a565e7d8ac0d4db6cb75927f3680a0914517666134011
 SHA512:
-  metadata.gz: 1269dce8cd8dac1c5d3d8e9f0ac2437bf4b2bd25e2511d5dc8aee4010157dfb9156be984fc2976029995dc704d3bb4ac8b880ea2683f51571f9bc88edf3cac8d
-  data.tar.gz: 4a6e77ce020686fecbbe0c09247ab61769128b263ff47cea7df9549b3b360670e068400743bfae9a69d467250479f0768e57d57581d651927c686800ccefd868
+  metadata.gz: af2099fb9686c1b87742f79a07ee892a7dc3b8c984f93b684eb3a51355c82b793369230857ff9f8e5eff2ee24e7fda85d482f215126eb6ba7df59a3c62cd7aa9
+  data.tar.gz: a975d65b9b5575e6cbb2768dd22232f8c20291eecfcb7984fc075b6d6c2acefd1e56f558d3ca96a92329ae24588cc35042d780ecd1a2558d2fc7abe8e3aa3323

data/CHANGELOG.md

@@ -7,6 +7,47 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-09-16
+
+### Added
+
+- Styled form controls:
+  - `FormBuilder`'s text-like fields (`text_field`, `email_field`,
+    `password_field`, `date_field`, `text_area` and the rest) wear
+    `UnmagicInput`.
+  - Its selects wear `UnmagicSelect`.
+  - `check_box_field` and `check_box_collection` wear `UnmagicCheck`.
+  - The classes come from the new `config.control_class` seam, called with
+    `(view, kind)`.
+- `control_classes(kind, size:)` gives a control outside the builder the same
+  classes, for a `select_tag` or a hand-written radio. It takes `:small` and
+  `:large` sizes that match `button_classes`.
+- The preview app (`bin/dev`) is rebuilt as component docs: a sidebar, an
+  overview of every component with a live thumbnail, and a page per component
+  whose examples each show their source beside the rendered result.
+
+### Changed
+
+- **Breaking: the styles are Tailwind CSS v4, and your app needs Tailwind v4.**
+  - The gem's styles are now a Tailwind source file,
+    `app/assets/tailwind/unmagic_components/engine.css`, compiled by your app's
+    own Tailwind build.
+  - It uses Tailwind's palette with `dark:` variants, so dark mode follows your
+    app's `dark` variant.
+  - The rules sit in `@layer components`, so utilities passed as `class:`
+    override them.
+  - `unmagic/components.css` and every `--unmagic-*` theming variable are
+    removed.
+  - To migrate: drop `stylesheet_link_tag "unmagic/components"`, and add
+    `@import "../builds/tailwind/unmagic_components";` after
+    `@import "tailwindcss";` in `app/assets/tailwind/application.css`. Then move
+    any `--unmagic-*` overrides into your `@theme` colours or your `dark`
+    variant.
+- **Form controls now carry a class, and the gem's CSS styles them.** An app
+  that styles its inputs itself keeps its own look with
+  `config.control_class = ->(_view, _kind) { nil }`, or points the seam at its
+  own classes.
+
 ## [0.2.0] - 2026-09-16
 
 ### Added
@@ -120,6 +161,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Configurable empty-state, pagination and Pagy seams so the gem depends on neither
   Pagy nor any host helper.
 
-[Unreleased]: https://github.com/unreasonable-magic/unmagic-components/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/unreasonable-magic/unmagic-components/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/unreasonable-magic/unmagic-components/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/unreasonable-magic/unmagic-components/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/unreasonable-magic/unmagic-components/releases/tag/v0.1.0

data/README.md

@@ -44,10 +44,29 @@ the spirit of `form_for`: describe the columns, get the chrome.
 gem "unmagic-components"
 ```
 
-Add the stylesheet to your layout:
+The components are styled with **Tailwind CSS v4, which your app needs**. The
+gem's styles are a Tailwind source file,
+`app/assets/tailwind/unmagic_components/engine.css`, that your own Tailwind
+build compiles. Markup inside an installed gem is never scanned, so the gem
+hands Tailwind its CSS instead of relying on scanning.
 
-```erb
-<%= stylesheet_link_tag "unmagic/components" %>
+With tailwindcss-rails, import the engine's entry file after Tailwind itself in
+`app/assets/tailwind/application.css`:
+
+```css
+@import "tailwindcss";
+@import "../builds/tailwind/unmagic_components";
+```
+
+tailwindcss-rails generates that entry file on every build and watch, or on
+demand with `bin/rails tailwindcss:engines`.
+
+With the Tailwind CLI or an npm build, import the gem's file by path. `bundle
+show unmagic-components` prints where the gem is installed:
+
+```css
+@import "tailwindcss";
+@import "/path/to/unmagic-components/app/assets/tailwind/unmagic_components/engine.css";
 ```
 
 The engine mixes the helpers into ActionView automatically — no initializer
@@ -57,65 +76,38 @@ to your application.js (see [Dialogs](#dialogs)).
 
 ## Theming
 
-The stylesheet is plain CSS driven by custom properties, and every value falls
-back to a Tailwind palette default, so the components look right unconfigured.
-To match your own design, set the `--unmagic-*` knobs wherever your theme lives:
+The components use Tailwind's own palette (neutral for surfaces, borders and
+text, and red, green and amber for tones), with a `dark:` variant for every
+colour. They look right with Tailwind's defaults and follow your theme from
+there.
+
+**Dark mode** follows your app's `dark` variant. Tailwind's default is the
+visitor's system setting. To switch on a class or an attribute instead, redefine
+the variant in your Tailwind input file and the components switch with it:
 
 ```css
-:root {
-  --unmagic-surface:       var(--surface);
-  --unmagic-surface-2:     var(--surface-2);
-  --unmagic-surface-3:     var(--surface-3);    /* neutral badges, tab tracks */
-  --unmagic-raised:        var(--surface);      /* the selected tab */
-  --unmagic-hover:         var(--hover);
-  --unmagic-border:        var(--border);
-  --unmagic-border-strong: var(--border-strong);
-  --unmagic-text:          var(--text);
-  --unmagic-text-2:        var(--text-2);
-  --unmagic-text-3:        var(--text-3);
-  --unmagic-skeleton:      var(--surface-3);
-  --unmagic-accent:        var(--primary);      /* primary buttons */
-  --unmagic-on-accent:     var(--on-primary);
-  --unmagic-bad:           var(--danger);       /* errors, danger buttons */
-  --unmagic-bad-surface:   var(--danger-surface);
-  --unmagic-bad-border:    var(--danger-border);
-  --unmagic-good:          var(--success);      /* good toasts */
-  --unmagic-good-surface:  var(--success-surface);
-  --unmagic-good-border:   var(--success-border);
-  --unmagic-warn:          var(--warning);      /* warn toasts */
-  --unmagic-warn-surface:  var(--warning-surface);
-  --unmagic-warn-border:   var(--warning-border);
-  --unmagic-tooltip:       var(--inverse);      /* tooltips */
-  --unmagic-on-tooltip:    var(--on-inverse);
-  --unmagic-focus:         var(--focus-ring);
-  --unmagic-backdrop:      rgb(0 0 0 / 0.5);    /* behind dialogs */
-}
+@custom-variant dark (&:where(.dark, .dark *));
 ```
 
-In a dark theme, set `--unmagic-accent` too. Its fallback is near-black, which
-disappears against a dark dialog.
-
-Dark mode needs nothing extra. If your own tokens already flip, these flip with
-them — the gem ships no dark variant and makes no assumption about how you
-select a theme.
-
-The CSS is deliberately **not** part of any Tailwind build. Tailwind only
-generates classes it can see and it does not scan installed gems, so a component
-library that emitted utilities from Ruby would render unstyled in your app
-unless you pointed `@source` at the gem's install path.
-
-If you do want Tailwind utilities from these tokens, map them with `@theme
-inline` — not plain `@theme`. A non-inline theme variable makes the utility emit
-`var(--color-unmagic-surface)`, which resolves *where that variable is defined*,
-so an override scoped to a subtree (a themed preview pane, a `.dark` region)
-would be invisible to it:
+**Colours, radii and fonts** come from your theme, so change them there and the
+components follow:
 
 ```css
-@theme inline {
-  --color-unmagic-surface: var(--unmagic-surface);
+@theme {
+  --color-neutral-900: oklch(0.21 0.03 265);
+  --radius-md: 0.25rem;
 }
 ```
 
+**One component** takes utilities through `class:`, like any other option.
+The gem's rules sit in `@layer components`, which Tailwind orders before
+`@layer utilities`, so your utilities win:
+
+```erb
+<%= card title: "Members", class: "rounded-none shadow-none" do %>…<% end %>
+<%= form.field :email, "Email", class: "font-mono" %>
+```
+
 ## Configuration
 
 Three seams, each with a working default. Point them at your own versions if you
@@ -269,19 +261,45 @@ Set it as the default with `config.action_view.default_form_builder`, or pass
   Outside a form builder, use `uuid_input_tag`. Needs
   `import "unmagic/components/uuid_input"`.
 
-**What the control looks like is not decided here.** Apps style inputs in
-incompatible ways — a class on every input, or a bare-element rule — and a
-component library that picked one would be wrong in the other. So the builder emits
-structure and the gem's CSS styles only the label, hint and error. Point your own
-input rules at `.UnmagicField` to give its controls your look:
+**The controls are styled too.** Each control the builder makes wears a class for
+its kind, and the gem's CSS styles those classes, never bare elements, so an input
+the gem didn't render keeps whatever your app gives it:
 
-```css
-.field,
-.UnmagicField {
-  /* your existing input rules */
-}
+| Builder methods | Kind | Class |
+|---|---|---|
+| `text_field`, `email_field`, `number_field`, `url_field`, `search_field`, `telephone_field` | `:input` | `UnmagicInput` |
+| `password_field` | `:password` | `UnmagicInput` |
+| `text_area`, `autogrow_text_area` | `:text_area` | `UnmagicInput` |
+| `date_field`, `time_field`, `datetime_field`, `month_field`, `week_field` | `:date` | `UnmagicInput` |
+| `select`, `collection_select`, `grouped_collection_select`, `time_zone_select` | `:select` | `UnmagicSelect` |
+| `check_box_field`, `check_box_collection` | `:check` | `UnmagicCheck` |
+
+A class you pass (`class: "font-mono"`) is added after the gem's. Rails' own
+`check_box` and `radio_button` are left alone, as are the `*_tag` helpers. Give
+one of those the same look with `control_classes`:
+
+```erb
+<%= select_tag "status", options_for_select(%w[Open Closed]), class: control_classes(:select) %>
+<%= search_field_tag "q", params[:q], class: control_classes(:input, size: :small) %>
+<%= radio_button_tag "notify", "daily", class: control_classes(:radio) %>
 ```
 
+`control_classes(kind, size:)` takes the kinds above plus `:radio`. `size:
+:small` or `:large` sits a box level with a `button_classes` button of the same
+size.
+
+The classes come from a seam. If your app already styles its inputs, point it at
+your own classes, or return `nil` to leave the controls unstyled:
+
+```ruby
+config.control_class = ->(_view, kind) { kind == :select ? "form-select" : "form-input" }
+config.control_class = ->(_view, _kind) { nil }
+```
+
+The controls use the same palette as the rest of the gem. A checked box or radio
+is neutral-900 (neutral-100 in dark mode), and an invalid control has a red
+border.
+
 The submit button's classes come from a seam, so it wears your own button:
 
 ```ruby