gdk-toogle 0.9.5 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 126d3207f78acad2e5a2af3959117efd93a9a6b210187afafb4b4b69e1db33b9
-  data.tar.gz: 26b6411779359a408db3f218e3e9d71d5f33538277c9cf276183c8756c63ede8
+  metadata.gz: cacce942effef205bff4a9e31cd15889c6e3faba254dd3efee2e238519940147
+  data.tar.gz: f1e506fe72c8dbe264382fa96544a66e232ea0b40fb0bfb4fb14772b3a0e9702
 SHA512:
-  metadata.gz: 19cd5ab3ca2ecf53b0f4712ada95810c468a37e963d70cf726081dacf6797ce2cf63d9cc193c79d924a658e7d5effcb4042f1e5cc0f0210a11b4cc077a45b04a
-  data.tar.gz: 9f88ab74e9ed65a6ccdc031378d59b3310b52f2cdd0a8703d58f837cf7c357f9f2679b754fb525c99c1e7d934e81ef10e1c775f627ecad8c13da108b6aece209
+  metadata.gz: aac129e17fb36ea58e72b2bd12dbf9d90b52d8055ab787146fc3fccaf0eec5cd178d6f1cf21672e0de6fd48aa9ab9ea15fa5a7d328e522ff430286ecf0c49d16
+  data.tar.gz: 83a9942634aab84f4058e743f900f538c5e5bc69c74f8c678c8738b544c96d377ef091cc96302164e33f03bc611db886cd90b10581b47b75a3b5e070ff32173f

data/README.md

@@ -4,23 +4,77 @@ 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
 
-The UI is availabe at http://gdk.test:3000/rails/features.
+The UI is available at http://gdk.test:4000/rails/features.
 
 ## Contributing
 
-Everyone can contribute.
+Everyone can contribute. Open issues and merge requests at
+https://gitlab.com/thutterer/toogle. Please make sure `rake` (specs and
+linter) passes before submitting.
 
-### How to run tests
+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.
 
-This is the default rake task. Just run `rake` with no arguments.
+### How to run it standalone
 
-The system specs in `spec/system` are configured to use Firefox as headless browser.
+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:
 
-**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`.
+```sh
+bundle install
+cd spec/dummy
+bin/rails server
+```
+
+Then open http://localhost:4000/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
 

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);
     },
   }));
 
@@ -103,11 +238,8 @@ document.addEventListener("alpine:init", () => {
       ["@click"]() {
         this.isDark = !this.isDark;
         document.cookie = `toogle-dark=${this.isDark}; SameSite=Strict`;
-        if (this.isDark) {
-          document.documentElement.classList.remove("light-mode");
-        } else {
-          document.documentElement.classList.add("light-mode");
-        }
+        document.documentElement.classList.toggle("dark-mode", this.isDark);
+        document.documentElement.classList.toggle("light-mode", !this.isDark);
       },
       ["x-bind:title"]() {
         return `Switch to ${this.isDark ? "Light Mode" : "Dark Mode"}`;

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

@@ -15,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 {
@@ -29,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;
     }
@@ -43,29 +50,39 @@
   }
 
   input:checked + .handle {
-    background-color: var(--color-primary);
-  }
-
-  input:focus + .handle {
-    outline: 4px solid var(--color-primary);
+    background-color: var(--color-on);
   }
 
   input:checked + .handle:before {
-    -webkit-transform: translateX(26px);
-    -ms-transform: translateX(26px);
     transform: translateX(26px);
   }
 
-  input:disabled + .handle:before {
-    background-color: #ddd;
-    content: "N/A";
-    text-align: center;
-    color: white;
-    font-size: x-small;
-    line-height: 26px;
+  input:checked + .handle:active:before {
+    transform: translateX(26px) scale(0.92);
+  }
+
+  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

@@ -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;
+    }
   }
 }