maquina-components 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5288e1d8b1501f99a2b94c8d296e4babbe5e1d9d42f41d6f969dc1742e78c48
-  data.tar.gz: f4b31f8e38c025b05fc9a12a8c16d13b1fc62cfee10ce4596711a935203c39c4
+  metadata.gz: a849035735227db855acba5bb371ba284e6b1e8887b10c7072e1bcf007601944
+  data.tar.gz: 00a1f783571ac6ad7dffdc722256eb8a6c42831dd1a716786af3639775fef05a
 SHA512:
-  metadata.gz: 0c9977c27048fb814c4158033afa8bcfd538a257531d94cfe07a9f35dc623dda73503d430fea93947f026caf55ab9b8237423a010af0677f2d637b3abebd6138
-  data.tar.gz: 51c6744241d753e6b022c481fead7ad3b47725ac52cddf43a655f78a94c066f69b412a6f4f347a93c8e6935221ba743a6807035ebd86c1ffdd036605a6c30b80
+  metadata.gz: d9e8e0d25d4d228d673ece1ab3c215f51c6ec8b05125b27952951922ce2ea4acbb3b399cb54efdbcaad90b6ab6357c58c24bb3330e47804ff647a8f8fa347961
+  data.tar.gz: b57bb6e7179f1c97a0c4a25f84e22fc9defa09c0f73b97b150df29f733c9fb56ddc5e3a950da816c92d661bdfa6ffd62b676240c4a83f70feafa7ffe554a595c

data/README.md

@@ -43,6 +43,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)
@@ -134,6 +135,21 @@ generates views built with maquina_components. Customize the templates as needed
 
 **Prerequisite:** [tailwindcss-rails](https://github.com/rails/tailwindcss-rails) must be installed first.
 
+### Upgrading
+
+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
@@ -152,8 +168,10 @@ generates views built with maquina_components. Customize the templates as needed
 | **Card** | Content container with header, content, footer | [Card](https://maquina.app/documentation/components/card/) |
 | **Alert** | Callout messages (info, warning, error) | [Alert](https://maquina.app/documentation/components/alert/) |
 | **Badge** | Status indicators and labels | [Badge](https://maquina.app/documentation/components/badge/) |
-| **Table** | Data tables with sorting support | [Table](https://maquina.app/documentation/components/table/) |
+| **Table** | Data tables with striped and bordered variants | [Table](https://maquina.app/documentation/components/table/) |
+| **Separator** | Horizontal or vertical divider | [Separator](https://maquina.app/documentation/components/separator/) |
 | **Empty State** | Placeholder for empty lists | [Empty State](https://maquina.app/documentation/components/empty/) |
+| **Stats** | Metric cards in a responsive grid | [Stats](https://maquina.app/documentation/components/stats/) |
 
 ### Navigation Components
 
@@ -379,6 +397,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
@@ -467,12 +501,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
-bin/rails test
+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
+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.
- */