gdk-toogle 0.9.3 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b41975a3c2a35c12eecaad91aa7bfd949d68d0132576d1f68ecca48987abf641
-  data.tar.gz: ad9ede84ae8f37f9286699d33163f360a04854a00abb3fbfb4ec6b07e3ec386f
+  metadata.gz: 5b7fb4c9b37ce9f5712cc5635ff39bea2b3745179ea554dbe4b941f2a9472cab
+  data.tar.gz: 57a6c432b93d5dc0e88c52f46c653ca26338638f99f866c57e56dc5540a21692
 SHA512:
-  metadata.gz: 20a49dff67060c27ab608f9851570494726856f34e0deb11ad3c60266b72a3af13260384c63ddf3afe3284449e9984e03f3fd345a9302c6e132760a515c124eb
-  data.tar.gz: 1d372ec1b321404ad287154a027aef0a1732116ffedd449602bcd57f57e4d4d77b0a0e5ea11f2e5ed5e7c5caf3901ae99569485f3db8c0e50c7bc5f581ba5957
+  metadata.gz: da4f86f837651e78dc12c7c61e2563cb8e099ff5a6a454e00226728906427243649190743cc36b46bcac34967551542afe8da58f5f5a35e5c6fd834412d434e4
+  data.tar.gz: 807b565d41e6f131a0811fb7e4d980f1c5a0a5ad5a61c892e81f3c9e6d4c2c614fe269bfadf8087465467deca63d3297080366ad1827b4abd302a09c5fb30e21

data/README.md

@@ -4,30 +4,93 @@ A Rails engine web-UI to quickly toggle feature flags in GDK.
 
 ## Usage
 
-This gem was written specifically for the GitLab codebase. It won't work in any other Rails app.
+This gem was written specifically for the GitLab codebase. It relies on
+GitLab's `Feature` classes, so mounting it in any other Rails app won't work
+(for developing Toogle itself there is a standalone dummy app, see below).
 
 ### Usage within the GitLab Development Kit
 
-This gem is still an experiment and not yet part of our `Gemfile`. So for now, to try out this gem, take the following steps:
+The UI is available at http://gdk.test:3000/rails/features.
 
-- `git clone` this repository to your machine.
-- Add `gem 'toogle', path: 'local_toogle_path_here'` to the Gemfile and `bundle`.
-- Add `mount Toogle::Engine, at: '/rails/toogle'` to `config/routes/development.rb`.
-- Restart the rails server to pick up the new route: `gdk restart rails-web`
+## Contributing
 
-The UI is now availabe at http://gdk.test:3000/rails/toogle.
+Everyone can contribute. Open issues and merge requests at
+https://gitlab.com/thutterer/toogle. Please make sure `rake` (specs and
+linter) passes before submitting.
 
-## Contributing
+There is an `AGENTS.md` with the conventions and architecture notes that
+keep this codebase simple — worth a read, and keep it accurate when you
+change things.
+
+### How to run it standalone
+
+The dummy app used for testing includes fake in-memory versions of GitLab's
+`Feature` and Flipper classes (see `spec/dummy/app/models/`), so you can
+develop the engine without a GDK:
+
+```sh
+cd spec/dummy
+bin/rails server
+```
+
+Then open http://localhost:3000/toogle. Toggled state lives in memory and
+resets on restart.
+
+To test your changes inside a real GDK, point GitLab's `Gemfile` at your
+local checkout:
+
+```ruby
+gem 'gdk-toogle', path: '~/Code/toogle', require: 'toogle'
+```
+
+### How to run tests and linting
+
+Run `rake` to run both the specs and the [standard](https://github.com/standardrb/standard)
+linter. They are also available separately as `rake spec` and `rake standard`
+(use `rake standard:fix` to autoformat).
+
+To lint automatically before each commit, enable the bundled git hook once:
+
+```sh
+git config core.hooksPath .githooks
+```
+
+The system specs in `spec/system` use headless Firefox by default. Set
+`CAPYBARA_DRIVER` to any registered Capybara driver to switch, e.g. if you
+don't have Firefox or only a Snap-installed one (incompatible with
+geckodriver):
+
+```sh
+CAPYBARA_DRIVER=selenium_chrome_headless bundle exec rspec
+```
+
+### How to cut a release
+
+1. Bump `Toogle::VERSION` in `lib/toogle/version.rb`.
+2. Add an entry to `CHANGELOG.md`.
+3. Commit, then tag: `git tag vX.Y.Z && git push --tags`.
+4. Build and push the gem: `rake build` then `gem push pkg/gdk-toogle-X.Y.Z.gem`.
+5. Bump the version constraint in GitLab's `Gemfile` to pick it up.
+
+Keep Ruby and gem versions at or below what GitLab itself runs (see
+`AGENTS.md`).
+
+## Tech stack
+
+One design goal of this little Rails engine was to keep it free of any dependencies, that GitLab uses today.
+Because, tomorrow we might decide to ditch one or the other tech we use today, and Toogle shouldn't break just because GitLab removes `sassc`, as an example (that actually happened during development).
+
+That's why Toogle only depends on the bare basics: `rails`, `sprockets` and `haml`.
 
-Everyone can contribute.
+### Javascript
 
-### How to run tests
+Toogle uses [Alpine.js](https://alpinejs.dev/) from a `<script>` tag so it does not use or depend on our Vue.js usage or any bundler. Alpine is very similar to Vue, so it's really easy to pick up. Give it a try!
 
-This is the default rake task. Just run `rake` with no arguments.
+### CSS
 
-The system specs in `spec/system` are configured to use Firefox as headless browser.
+Toogle uses native unprocessed CSS to not depend on any specific preprocessor. Modern CSS is awesome, and all modern browsers support things like nested selectors today.
 
-**Tip:** If you don't have Firefox installed on your machine, or if you are on Ubuntu and have Firefox installed only via Snap, you can switch to Chrome by changing the `driven_by` to `:selenium_chrome_headless` in `spec/rails_helper.rb`.
+For theming and dark mode, it uses CSS variables and HSL colors, which makes it super easy to switch from light to dark by just changing the variable that makes up the _Lightness_. Check it out!
 
 ## License
 

data/Rakefile

@@ -13,4 +13,7 @@ require "rspec/core/rake_task"
 desc "Run all specs in spec directory"
 RSpec::Core::RakeTask.new(:spec)
 
-task default: :spec
+# Provides rake tasks `standard` and `standard:fix`
+require "standard/rake"
+
+task default: %i[spec standard]

data/app/assets/javascript/toogle/application.js

@@ -1,10 +1,41 @@
 document.addEventListener("alpine:init", () => {
-  Alpine.data("features", (indexUrl) => ({
+  Alpine.store("flash", {
+    message: "",
+
+    show(message) {
+      this.message = message;
+    },
+  });
+
+  const showFetchError = (error) => {
+    console.error("Error fetching data:", error);
+    Alpine.store("flash").show(
+      "Could not reach the server. Is your GDK running?"
+    );
+  };
+
+  const csrfToken = () =>
+    document.head.querySelector("meta[name=csrf-token]")?.content;
+
+  // Cap how many Defaults render at once. This is a search tool — the wanted
+  // flag is reachable by typing — so we never build the full ~700+ row DOM.
+  const MAX_DEFAULTS_SHOWN = 50;
+
+  Alpine.data("flags", (featuresUrl, definitionsUrl, shareName = "") => ({
     features: [],
-    indexUrl,
+    definitions: [],
+    query: "",
+    lastMoved: "",
+    moving: "",
+    selectedName: "",
+    max: MAX_DEFAULTS_SHOWN,
+    featuresUrl: featuresUrl.replace(/\/$/, ""),
+    definitionsUrl,
 
     init() {
-      fetch(this.indexUrl, {
+      const featuresLoaded = this.fetchFeatures();
+
+      const definitionsLoaded = fetch(this.definitionsUrl, {
         method: "GET",
         headers: {
           Accept: "application/json",
@@ -12,70 +43,174 @@ document.addEventListener("alpine:init", () => {
       })
         .then((response) => response.json())
         .then((data) => {
-          this.features = data;
+          this.definitions = data;
         })
-        .catch((error) => console.error("Error fetching data:", error));
+        .catch(showFetchError);
+
+      if (shareName) {
+        Promise.all([featuresLoaded, definitionsLoaded]).then(() =>
+          this.openDetails(shareName)
+        );
+      }
     },
 
-    toggleFeature(feature) {
-      const newState = feature.state === "enabled" ? "disabled" : "enabled";
-      fetch(`${this.indexUrl}/${feature.name}`, {
-        method: "PUT",
+    openDetails(name) {
+      this.selectedName = name;
+      history.replaceState({}, "", `${this.featuresUrl}/${name}`);
+      this.$refs.dialog.showModal();
+    },
+
+    closeDetails() {
+      this.selectedName = "";
+      history.replaceState({}, "", `${this.featuresUrl}/`);
+    },
+
+    // The dialog's subject, looked up live so it stays in sync after toggles.
+    selected() {
+      const feature = this.features.find((f) => f.name === this.selectedName);
+      if (feature) {
+        return {
+          state: feature.state,
+          definition: feature.definition,
+        };
+      }
+
+      const definition = this.definitions.find(
+        (d) => d.name === this.selectedName
+      );
+      if (definition) {
+        return {
+          state: definition.default_enabled ? "enabled" : "disabled",
+          definition,
+        };
+      }
+
+      return null;
+    },
+
+    toggleSelected() {
+      const feature = this.features.find((f) => f.name === this.selectedName);
+
+      if (feature) {
+        this.toggleFeature(feature);
+      } else {
+        this.toggleDefault(this.selected().definition);
+      }
+    },
+
+    fetchFeatures(movedName = "") {
+      return fetch(this.featuresUrl, {
+        method: "GET",
         headers: {
           Accept: "application/json",
-          "Content-Type": "application/json",
         },
-        body: JSON.stringify({
-          state: newState,
-        }),
-      }).then(() => {
+      })
+        .then((response) => response.json())
+        .then((data) => {
+          if (movedName) {
+            this.animated(() => {
+              this.features = data;
+            }, movedName);
+          } else {
+            // Not animated: the initial load should not "fly in" rows.
+            this.features = data;
+          }
+        })
+        .catch(showFetchError);
+    },
+
+    // Animates the layout change, e.g. a row moving between the sections.
+    // Only the moving row gets a view-transition-name (see the view), so the
+    // browser snapshots one row, not all ~700 — keeping toggles fast no
+    // matter how many flags exist. The moved row then gets a short "shine".
+    async animated(applyChange, movedName = "") {
+      if (!document.startViewTransition || !movedName) return applyChange();
+
+      // Name the moving row before the browser snapshots the old state.
+      this.moving = movedName;
+      await this.$nextTick();
+
+      const transition = document.startViewTransition(() => {
+        applyChange();
+        return this.$nextTick();
+      });
+
+      await transition.finished.catch(() => {});
+      this.moving = "";
+      this.lastMoved = movedName;
+      setTimeout(() => {
+        if (this.lastMoved === movedName) this.lastMoved = "";
+      }, 1200);
+    },
+
+    filteredFeatures() {
+      return this.features.filter((f) => f.name.includes(this.query.trim()));
+    },
+
+    // All definitions matching the query, minus those already customized.
+    matchingDefinitions() {
+      const customized = this.features.map((f) => f.name);
+      return this.definitions.filter(
+        (d) =>
+          d.name.includes(this.query.trim()) && !customized.includes(d.name)
+      );
+    },
+
+    // Only the rows we actually render (capped); see MAX_DEFAULTS_SHOWN.
+    filteredDefinitions() {
+      return this.matchingDefinitions().slice(0, this.max);
+    },
+
+    defaultsCapped() {
+      return this.matchingDefinitions().length > this.max;
+    },
+
+    toggleFeature(feature) {
+      const newState = feature.state === "enabled" ? "disabled" : "enabled";
+
+      this.putState(feature.name, newState).then(() => {
         this.features = this.features.map((f) => {
           return f === feature ? { ...f, state: newState } : f;
         });
       });
     },
 
-    deleteFeature(featureName) {
-      const csrfToken = document.head.querySelector(
-        "meta[name=csrf-token]"
-      )?.content;
+    toggleDefault(definition) {
+      const newState = definition.default_enabled ? "disabled" : "enabled";
 
-      fetch(`${this.indexUrl}/${featureName}`, {
-        method: "DELETE",
+      this.putState(definition.name, newState).then(() =>
+        this.fetchFeatures(definition.name)
+      );
+    },
+
+    putState(featureName, state) {
+      return fetch(`${this.featuresUrl}/${featureName}`, {
+        method: "PUT",
         headers: {
           Accept: "application/json",
-          "X-CSRF-Token": csrfToken,
+          "Content-Type": "application/json",
+          "X-CSRF-Token": csrfToken(),
         },
-      }).then(() => {
-        this.features = this.features.filter((f) => f.name !== featureName);
-      });
+        body: JSON.stringify({ state }),
+      }).catch(showFetchError);
     },
-  }));
 
-  Alpine.data("toggle", (featureName, isChecked, indexUrl) => ({
-    name: featureName,
-    checked: isChecked,
-    indexUrl,
-
-    input: {
-      ["@change"]() {
-        const csrfToken = document.head.querySelector(
-          "meta[name=csrf-token]"
-        )?.content;
-
-        fetch(`${this.indexUrl}/${this.name}`, {
-          method: "PUT",
-          headers: {
-            "Content-Type": "application/json",
-            "X-CSRF-Token": csrfToken,
-          },
-          body: JSON.stringify({
-            state: this.checked ? "disabled" : "enabled",
-          }),
-        }).then(() => {
-          window.location = this.indexUrl;
-        });
-      },
+    deleteFeature(featureName) {
+      fetch(`${this.featuresUrl}/${featureName}`, {
+        method: "DELETE",
+        headers: {
+          Accept: "application/json",
+          "X-CSRF-Token": csrfToken(),
+        },
+      })
+        .then(() => {
+          this.animated(() => {
+            this.features = this.features.filter(
+              (f) => f.name !== featureName
+            );
+          }, featureName);
+        })
+        .catch(showFetchError);
     },
   }));
 

data/app/assets/stylesheets/toogle/application.css

@@ -4,15 +4,13 @@
 @import "layout";
 @import "utilities";
 
-@import "components/card";
-@import "components/scrollbox";
 @import "components/toggle";
 
 [x-cloak] {
   display: none !important;
 }
 
-#notice {
+.notice {
   background-color: #fc6d26;
   color: white;
   padding: 0.5rem;

data/app/assets/stylesheets/toogle/components/toggle.css

@@ -4,6 +4,7 @@
   width: 60px;
   height: 34px;
   margin: 4px;
+  flex-shrink: 0;
 
   input {
     opacity: 0;
@@ -14,11 +15,9 @@
   .handle {
     position: absolute;
     cursor: pointer;
-    top: 0;
-    left: 0;
-    right: 0;
-    bottom: 0;
-    background-color: #ccc;
+    inset: 0;
+    background-color: var(--color-track);
+    box-shadow: inset 0 1px 3px var(--color-shadow);
     transition: 0.2s;
 
     &:before {
@@ -28,10 +27,19 @@
       width: 26px;
       left: 4px;
       bottom: 4px;
-      background-color: white;
+      background-color: var(--color-thumb);
+      box-shadow: 0 1px 2px var(--color-shadow);
       transition: 0.2s;
     }
 
+    &:hover:before {
+      filter: brightness(1.1);
+    }
+
+    &:active:before {
+      transform: scale(0.92);
+    }
+
     &.round {
       border-radius: 34px;
     }
@@ -41,30 +49,37 @@
     }
   }
 
-  input:checked + .handle {
+  input:checked + .handle:before {
     background-color: var(--color-primary);
+    transform: translateX(26px);
   }
 
-  input:focus + .handle {
-    outline: 4px solid var(--color-primary);
-  }
-
-  input:checked + .handle:before {
-    -webkit-transform: translateX(26px);
-    -ms-transform: translateX(26px);
-    transform: translateX(26px);
+  input:checked + .handle:active:before {
+    transform: translateX(26px) scale(0.92);
   }
 
-  input:disabled + .handle:before {
-    background-color: #ddd;
-    content: "N/A";
-    text-align: center;
-    color: white;
-    font-size: x-small;
-    line-height: 26px;
+  input:focus-visible + .handle {
+    outline: 2px solid var(--color-primary);
+    outline-offset: 2px;
   }
 
+  /* Truly disabled (e.g. flag unknown on this branch): flat and washed out
+     into the page, nothing raised or sunken that could look clickable. */
   input:disabled + .handle {
     cursor: not-allowed;
+    background-color: var(--color-disabled);
+    box-shadow: none;
+
+    &:before,
+    &:hover:before {
+      content: "N/A";
+      text-align: center;
+      color: var(--color-text-muted);
+      font-size: x-small;
+      line-height: 26px;
+      background-color: transparent;
+      box-shadow: none;
+      filter: none;
+    }
   }
 }

data/app/assets/stylesheets/toogle/elements.css

@@ -1,11 +1,11 @@
+* {
+  box-sizing: border-box;
+}
+
 html {
   color: var(--color-text);
   transition: 0.2s;
-  background-image: radial-gradient(
-    circle at 10vh 10vw,
-    hsl(var(--hue-primary), var(--saturation-bg), var(--lightness-bg1)),
-    hsl(var(--hue-primary), var(--saturation-bg), var(--lightness-bg0))
-  );
+  background-color: var(--color-page-bg);
 }
 
 body {
@@ -44,11 +44,6 @@ footer a {
   color: var(--color-text);
 }
 
-input[type="submit"]:not(.small) {
-  font-size: large;
-  padding: 0.25rem;
-}
-
 input[type="search"],
 input[type="text"] {
   margin: 0.25rem 0;
@@ -71,18 +66,26 @@ input[type="text"] {
 
 input[type="search"],
 input[type="text"] {
-  color: hsl(var(--hue-primary), var(--saturation-bg), var(--lightness-fg));
-  background-color: hsl(
-    var(--hue-primary),
-    var(--saturation-bg),
-    var(--lightness-bg2)
-  );
+  color: var(--color-text);
+  background-color: var(--color-surface);
   border: none;
-  box-shadow: inset 1px 1px 2px var(--color-shadow);
+  box-shadow: inset 0 1px 3px var(--color-shadow);
+  transition: filter 0.15s;
+
+  &:not(:read-only):hover {
+    filter: brightness(1.05);
+  }
 }
 
 hr {
+  width: 100%;
   margin: 1.5rem 0;
+  border: none;
+  border-top: 1px solid var(--color-track);
+}
+
+::selection {
+  background-color: hsl(var(--hue-primary), 90%, 50%, 0.3);
 }
 
 code {
@@ -94,7 +97,7 @@ button {
   cursor: pointer;
   background-color: transparent;
   border: none;
-  border-radius: 0.125rem;
+  border-radius: 0.5rem;
   padding: 0.5rem;
   min-width: 1rem;
 
@@ -103,19 +106,36 @@ button {
   justify-content: center;
 
   font-size: large;
+  transition: 0.15s;
 
-  &:hover,
-  &:focus {
+  &:hover {
     background-color: var(--color-primary);
     color: white;
   }
 
-  &:focus {
+  /* Keyboard focus only: an offset ring, no fill, so a focused button and
+     a hovered neighbor stay clearly two separate things. */
+  &:focus-visible {
     outline: 2px solid var(--color-primary);
+    outline-offset: 2px;
     opacity: 1 !important;
   }
 }
 
+.badge {
+  font-size: 0.75rem;
+  font-weight: bold;
+  padding: 0.125rem 0.5rem;
+  border-radius: 1rem;
+  background-color: var(--color-surface);
+  box-shadow: 0 1px 2px var(--color-shadow);
+
+  &.type {
+    background-color: var(--color-primary);
+    color: white;
+  }
+}
+
 ul {
   margin: 0;
   padding: 0;
@@ -135,11 +155,60 @@ dialog {
   border: none;
   outline: none;
 
+  /* Zoom/fade the dialog in and out. Browsers without @starting-style or
+     allow-discrete simply show and hide it instantly. */
+  opacity: 0;
+  transform: scale(0.95);
+  transition: opacity 0.2s ease-out, transform 0.2s ease-out,
+    display 0.2s allow-discrete, overlay 0.2s allow-discrete;
+
+  &[open] {
+    opacity: 1;
+    transform: scale(1);
+
+    @starting-style {
+      opacity: 0;
+      transform: scale(0.95);
+    }
+  }
+
   &::backdrop {
+    background-color: rgba(0, 0, 0, 0);
+    transition: background-color 0.2s ease-out,
+      display 0.2s allow-discrete, overlay 0.2s allow-discrete;
+  }
+
+  &[open]::backdrop {
     background-color: rgba(0, 0, 0, 0.5);
+
+    @starting-style {
+      background-color: rgba(0, 0, 0, 0);
+    }
   }
 
-  > .card {
-    margin: 0;
+  > .details {
+    background-color: var(--color-page-bg);
+    border-radius: 0.75rem;
+    padding: 1.5rem;
+    max-width: 100%;
+
+    header {
+      margin-bottom: 1rem;
+
+      h2 {
+        display: flex;
+        align-items: center;
+        gap: 0.5rem;
+      }
+
+      .badges {
+        margin-top: 0.5rem;
+        gap: 0.5rem;
+      }
+    }
+
+    main {
+      gap: 0.5rem;
+    }
   }
 }