maquina-components 0.5.1 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9159362a034d89b9abf1b6a5a636851942f69c32491eea74c438c9d8dc678b57
-  data.tar.gz: 9ab23823a833fdfb8d02727fea268539ea0dd26d974b3212aedf90c87d2c5963
+  metadata.gz: 0a445c4fe008c07069fd7d0e9fd4249c9a169410e9a53fa6cdaa6c2455351b92
+  data.tar.gz: c0964a27ecfdbd92797ee8c03a24d7c9e6db2b5e41147d2d81bf18ff2e38540d
 SHA512:
-  metadata.gz: 2b7d4230c490e4a98db049a2a527300b060873b6befb6925c2825455923e2179f353ffadbca0f90ebda98779ef711083b819c60a13763a5d982be3d22b73ab4e
-  data.tar.gz: c0671e469d43f1fbc265638755f453365748f2cf3d39e435ffa5218d81f9453a55f87cd1babe8acdfb2ccfdfb21a4e2415366a82388ddabb74f9a127a3bdc821
+  metadata.gz: 7c59d1819376a7242cbac12758ceffdb6e221184a29150b6f70364b275545f84d8da7c3235a5d9bdc3a1044e08622dba5b379615e2bc7053e8647506f83b6b7c
+  data.tar.gz: 340d7fcd15e476d17e2244cb7e7b29563b27e7fff360c09f9427d2ccc0491379b4dc5c412e4b8be9447159bbb75fd9d47bade573fbfb9497284d3d9ada629931

data/README.md

@@ -2,6 +2,19 @@
 
 UI components for Ruby on Rails, built with ERB, TailwindCSS 4.0, and Stimulus.
 
+> [!IMPORTANT]
+> **0.6.0 has breaking changes.** Engine CSS moved into `@layer components`,
+> which changes what wins in your app. Most notably, the `* { border-color }`
+> shim in the `theme.css` you already installed must be wrapped in
+> `@layer base` — unlayered, it now outranks every engine rule and flattens
+> the tinted alert, toast and badge borders. That one affects every existing
+> app and fails silently.
+>
+> Before upgrading, read [docs/upgrading.md](docs/upgrading.md). After
+> upgrading, run `bin/rails maquina:doctor` — it prints file:line for every
+> pattern the release changes and never edits anything. An appendix in the
+> upgrading guide restores the 0.5.1 look with one token block.
+
 ---
 
 ## Why This Exists
@@ -43,6 +56,7 @@ If you're open to trying maquina_components and providing feedback, you're welco
 - **Stimulus controllers** only used where interactivity is needed
 - **Dark mode** support via CSS variables
 - **shadcn/ui theming** convention (works with their color system)
+- **Design tokens** for shape, focus rings, elevation and weight — [theming guide](docs/theming.md)
 - **Composable** — small partials you can combine freely
 
 ![Test dummy app with light mode](/imgs/light.png)
@@ -136,6 +150,28 @@ generates views built with maquina_components. Customize the templates as needed
 
 ---
 
+## Upgrading
+
+**0.5.1 → 0.6.0 is a breaking upgrade** — see the note at the top of this
+README and [docs/upgrading.md](docs/upgrading.md) for the seven changes, each
+with measurements, plus an appendix that reverts every visual change with one
+token block.
+
+Re-running the install generator is safe — it is idempotent and never rewrites
+your palette. After upgrading, run the doctor:
+
+```bash
+bin/rails maquina:doctor
+```
+
+It scans your CSS, views and JavaScript and prints file:line for every pattern
+the new release changes, grouped `BREAKING` / `REVIEW` / `CLEANUP`. It is
+advisory: it never edits anything and never fails a build. See
+[docs/upgrading.md](docs/upgrading.md) for what changed and how to keep the
+previous look.
+
+---
+
 ## Available Components
 
 ### Layout Components
@@ -381,6 +417,22 @@ flash[:success] = "Changes saved successfully!"
 
 Components use CSS variables following the [shadcn/ui theming convention](https://ui.shadcn.com/docs/theming).
 
+Colors are not the only variables: shape, focus rings, elevation and weight are
+design tokens too, so reshaping the whole library is a short list of
+declarations rather than override CSS fighting the cascade.
+
+```css
+:root {
+  --control-radius: 0;   /* buttons, inputs, badges, menu items */
+  --surface-radius: 0;   /* cards, popovers, toasts, alerts */
+  --elevation-raised: none;
+}
+```
+
+**[Theming guide](docs/theming.md)** — the full token list, flat and brutalist
+themes in a dozen lines each, recoloring the control marks, dark mode, and how
+to pin a single component without redefining a role.
+
 The install generator adds default theme variables. Customize them in `app/assets/tailwind/application.css`:
 
 ```css
@@ -469,12 +521,54 @@ cd test/dummy
 bin/rails server
 ```
 
-Run tests:
+Run tests (build the dummy app's CSS first — the stylesheet guards assert on the
+compiled output):
+
+```bash
+cd test/dummy && bin/rails tailwindcss:build && cd -
+bin/test
+```
+
+### Running against the published branch
+
+Both commands above run against the source tree. To exercise the gem the way a
+consuming app resolves it — from GitHub rather than from `lib/` and `app/` —
+use `Gemfile.branch`:
 
 ```bash
-bin/rails test
+BUNDLE_GEMFILE=Gemfile.branch bundle install
+BUNDLE_GEMFILE=Gemfile.branch bin/test
+
+# or drive the app by hand
+cd test/dummy
+BUNDLE_GEMFILE=../../Gemfile.branch bin/rails tailwindcss:build
+BUNDLE_GEMFILE=../../Gemfile.branch bin/rails server
 ```
 
+It defaults to the current release branch; override with `MAQUINA_BRANCH`.
+
+`test/dummy/config/boot.rb` skips its `$LOAD_PATH` unshift under
+`Gemfile.branch`, so the source tree cannot shadow the resolved gem — without
+that the check would pass no matter what was on the branch. `Gemfile.common`
+holds the app gems both Gemfiles share, so the two cannot drift.
+
+Two limits worth knowing. It resolves the **pushed** commit, so local work you
+have not pushed is not what you are testing — `bundle list | grep maquina`
+prints the SHA. And Bundler resolves a git source from a checkout, so every
+file is present whether or not `spec.files` lists it: this catches a bad
+dependency or a broken require path, but a file missing from the packaged gem
+stays invisible. For that, build the gem and install what comes out:
+
+```bash
+gem build maquina-components.gemspec
+gem contents --show-install-dir maquina-components   # after installing it
+```
+
+Worth confirming either way: `bin/rails -T | grep maquina` (the rake task
+ships), `bin/rails generate --help` (the generators are found), and that the
+previews render — those exercise `lib/tasks`, `lib/generators/**/templates` and
+`app/**`, which are the parts a packaging mistake tends to drop.
+
 ---
 
 ## Claude Code Skill

data/app/assets/stylesheets/alert.css

@@ -3,141 +3,175 @@
  * Alert component for displaying callouts, messages, and notifications.
  * Uses data attributes for styling to maintain consistency with other components.
  * Fully compatible with dark mode via CSS variables.
+ *
+ * Cascade order in this file (full contract documented in form.css):
+ *   1. base      [data-component="alert"], [data-alert-part="…"]
+ *   2. sizes     — none
+ *   3. variants  [data-component="alert"]:where([data-variant="…"], [data-has-icon])
+ *   4. states    — none
+ *   5. dark      — none; dark-mode differences are tokens (see tokens.css)
+ * Every rule is flattened to 0,1,0 with :where() and lives in
+ * @layer components, so a caller's utility class wins and source order is
+ * the only tie-breaker. (Rules whose target is a bare element read 0,1,1 — an
+ * element selector cannot be zeroed away.)
  */
 
-/* ===== Base Alert Styles ===== */
-[data-component="alert"] {
-  position: relative;
-  display: grid;
-  grid-template-columns: 1fr;
-  @apply w-full rounded-lg border p-4 text-sm;
-  
-  /* Default colors */
-  background-color: var(--background);
-  color: var(--foreground);
-  border-color: var(--border);
+@layer components {
+  /* ===== Base Alert Styles ===== */
+  [data-component="alert"] {
+    position: relative;
+    display: grid;
+    grid-template-columns: 1fr;
+    @apply w-full border p-4 text-sm;
+    border-radius: var(--alert-radius, var(--surface-radius, 0.5rem));
+
+    /* Default colors — an alert sits *on* a surface, so it paints --card, not
+       the page background (painting --background measures ΔL 0.00 inside a card) */
+    background-color: var(--card, var(--background));
+    color: var(--foreground);
+    border-color: var(--border);
+  }
+
+  /* Alert with icon - add left padding for icon space */
+  [data-component="alert"]:where([data-has-icon="true"]) {
+    grid-template-columns: auto 1fr;
+    @apply gap-3;
+  }
+
+  /* ===== Icon Support ===== */
+  [data-component="alert"] > svg:where(:first-child),
+  :where([data-component="alert"]) [data-alert-part="icon"] {
+    @apply size-4 shrink-0;
+    color: var(--foreground);
+    /* Align with first line of text */
+    margin-top: 0.125rem;
+  }
+
+  /* ===== Alert Title ===== */
+  :where([data-component="alert"]) [data-alert-part="title"] {
+    @apply leading-none tracking-tight;
+    font-weight: var(--label-weight, 500);
+    color: var(--foreground);
+  }
+
+  /* Title followed by description needs margin */
+  :where([data-component="alert"]) [data-alert-part="title"]:where(:has(+ [data-alert-part="description"])) {
+    @apply mb-1;
+  }
+
+  /* ===== Alert Description ===== */
+  :where([data-component="alert"]) [data-alert-part="description"] {
+    @apply text-sm;
+    color: var(--muted-foreground);
+  }
+
+  /* Nested paragraphs */
+  :where([data-component="alert"]) [data-alert-part="description"] p {
+    @apply leading-relaxed;
+  }
+
+  /* Lists inside description */
+  :where([data-component="alert"]) [data-alert-part="description"] ul {
+    @apply mt-2 list-inside list-disc;
+  }
+
+  /* ===== Variant: Default ===== */
+  [data-component="alert"]:where([data-variant="default"]) {
+    background-color: var(--card, var(--background));
+    color: var(--foreground);
+    border-color: var(--border);
+  }
+
+  [data-component="alert"]:where([data-variant="default"]) > svg:where(:first-child),
+  :where([data-component="alert"][data-variant="default"]) [data-alert-part="icon"] {
+    color: var(--foreground);
+  }
+
+  /* ===== Variant: Destructive ===== */
+  [data-component="alert"]:where([data-variant="destructive"]) {
+    background-color: var(--destructive);
+    color: var(--destructive-foreground);
+    border-color: var(--destructive);
+  }
+
+  :where([data-component="alert"][data-variant="destructive"]) [data-alert-part="title"] {
+    color: var(--destructive-foreground);
+  }
+
+  :where([data-component="alert"][data-variant="destructive"]) [data-alert-part="description"] {
+    color: var(--destructive-foreground);
+    opacity: 0.9;
+  }
+
+  [data-component="alert"]:where([data-variant="destructive"]) > svg:where(:first-child),
+  :where([data-component="alert"][data-variant="destructive"]) [data-alert-part="icon"] {
+    color: var(--destructive-foreground);
+  }
+
+  /* ===== Variant: Success ===== */
+  [data-component="alert"]:where([data-variant="success"]) {
+    background-color: var(--success, oklch(0.627 0.194 149.214));
+    color: var(--success-foreground, oklch(0.985 0 0));
+    border-color: var(--success, oklch(0.627 0.194 149.214));
+  }
+
+  :where([data-component="alert"][data-variant="success"]) [data-alert-part="title"] {
+    color: var(--success-foreground, oklch(0.985 0 0));
+  }
+
+  :where([data-component="alert"][data-variant="success"]) [data-alert-part="description"] {
+    color: var(--success-foreground, oklch(0.985 0 0));
+    opacity: 0.9;
+  }
+
+  [data-component="alert"]:where([data-variant="success"]) > svg:where(:first-child),
+  :where([data-component="alert"][data-variant="success"]) [data-alert-part="icon"] {
+    color: var(--success-foreground, oklch(0.985 0 0));
+  }
+
+  /* ===== Variant: Warning ===== */
+  [data-component="alert"]:where([data-variant="warning"]) {
+    background-color: var(--warning, oklch(0.769 0.188 70.08));
+    color: var(--warning-foreground, oklch(0.216 0.006 56.043));
+    border-color: var(--warning, oklch(0.769 0.188 70.08));
+  }
+
+  :where([data-component="alert"][data-variant="warning"]) [data-alert-part="title"] {
+    color: var(--warning-foreground, oklch(0.216 0.006 56.043));
+  }
+
+  :where([data-component="alert"][data-variant="warning"]) [data-alert-part="description"] {
+    color: var(--warning-foreground, oklch(0.216 0.006 56.043));
+    opacity: 0.9;
+  }
+
+  [data-component="alert"]:where([data-variant="warning"]) > svg:where(:first-child),
+  :where([data-component="alert"][data-variant="warning"]) [data-alert-part="icon"] {
+    color: var(--warning-foreground, oklch(0.216 0.006 56.043));
+  }
+
+  /* ===== Variant: Info ===== */
+  /*
+   * --info has no engine default on purpose: an undefined --info must fall back
+   * to the neutral default treatment, never to --primary (that renders an
+   * informational alert in the brand accent, so it reads as a call to action).
+   */
+  [data-component="alert"]:where([data-variant="info"]) {
+    background-color: var(--info, var(--card, var(--background)));
+    color: var(--info-foreground, var(--foreground));
+    border-color: var(--info, var(--border));
+  }
+
+  :where([data-component="alert"][data-variant="info"]) [data-alert-part="title"] {
+    color: var(--info-foreground, var(--foreground));
+  }
+
+  :where([data-component="alert"][data-variant="info"]) [data-alert-part="description"] {
+    color: var(--info-foreground, var(--muted-foreground));
+  }
+
+  [data-component="alert"]:where([data-variant="info"]) > svg:where(:first-child),
+  :where([data-component="alert"][data-variant="info"]) [data-alert-part="icon"] {
+    color: var(--info-foreground, var(--foreground));
+  }
 }
-
-/* Alert with icon - add left padding for icon space */
-[data-component="alert"][data-has-icon="true"] {
-  grid-template-columns: auto 1fr;
-  @apply gap-3;
-}
-
-/* ===== Icon Support ===== */
-[data-component="alert"] > svg:first-child,
-[data-component="alert"] [data-alert-part="icon"] {
-  @apply size-4 shrink-0;
-  color: var(--foreground);
-  /* Align with first line of text */
-  margin-top: 0.125rem;
-}
-
-/* ===== Alert Title ===== */
-[data-component="alert"] [data-alert-part="title"] {
-  @apply font-medium leading-none tracking-tight;
-  color: var(--foreground);
-}
-
-/* Title followed by description needs margin */
-[data-component="alert"] [data-alert-part="title"]:has(+ [data-alert-part="description"]) {
-  @apply mb-1;
-}
-
-/* ===== Alert Description ===== */
-[data-component="alert"] [data-alert-part="description"] {
-  @apply text-sm;
-  color: var(--muted-foreground);
-}
-
-/* Nested paragraphs */
-[data-component="alert"] [data-alert-part="description"] p {
-  @apply leading-relaxed;
-}
-
-/* Lists inside description */
-[data-component="alert"] [data-alert-part="description"] ul {
-  @apply mt-2 list-inside list-disc;
-}
-
-/* ===== Variant: Default ===== */
-[data-component="alert"][data-variant="default"] {
-  background-color: var(--background);
-  color: var(--foreground);
-  border-color: var(--border);
-}
-
-[data-component="alert"][data-variant="default"] > svg:first-child,
-[data-component="alert"][data-variant="default"] [data-alert-part="icon"] {
-  color: var(--foreground);
-}
-
-/* ===== Variant: Destructive ===== */
-[data-component="alert"][data-variant="destructive"] {
-  background-color: var(--destructive);
-  color: var(--destructive-foreground);
-  border-color: var(--destructive);
-}
-
-[data-component="alert"][data-variant="destructive"] [data-alert-part="title"] {
-  color: var(--destructive-foreground);
-}
-
-[data-component="alert"][data-variant="destructive"] [data-alert-part="description"] {
-  color: var(--destructive-foreground);
-  opacity: 0.9;
-}
-
-[data-component="alert"][data-variant="destructive"] > svg:first-child,
-[data-component="alert"][data-variant="destructive"] [data-alert-part="icon"] {
-  color: var(--destructive-foreground);
-}
-
-/* ===== Variant: Success ===== */
-[data-component="alert"][data-variant="success"] {
-  background-color: var(--success);
-  color: var(--success-foreground);
-  border-color: var(--success);
-}
-
-[data-component="alert"][data-variant="success"] [data-alert-part="title"] {
-  color: var(--success-foreground);
-}
-
-[data-component="alert"][data-variant="success"] [data-alert-part="description"] {
-  color: var(--success-foreground);
-  opacity: 0.9;
-}
-
-[data-component="alert"][data-variant="success"] > svg:first-child,
-[data-component="alert"][data-variant="success"] [data-alert-part="icon"] {
-  color: var(--success-foreground);
-}
-
-/* ===== Variant: Warning ===== */
-[data-component="alert"][data-variant="warning"] {
-  background-color: var(--warning);
-  color: var(--warning-foreground);
-  border-color: var(--warning);
-}
-
-[data-component="alert"][data-variant="warning"] [data-alert-part="title"] {
-  color: var(--warning-foreground);
-}
-
-[data-component="alert"][data-variant="warning"] [data-alert-part="description"] {
-  color: var(--warning-foreground);
-  opacity: 0.9;
-}
-
-[data-component="alert"][data-variant="warning"] > svg:first-child,
-[data-component="alert"][data-variant="warning"] [data-alert-part="icon"] {
-  color: var(--warning-foreground);
-}
-
-/* ===== Dark Mode ===== */
-/*
- * Dark mode is handled automatically through CSS variables.
- * The theme variables change based on the .dark class on html/body.
- * No additional dark mode styles needed here.
- */