supercharts-bullet_train 0.1.14 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e5ec9ffd3a3ecf773b6793ae88d0c14693e87df5715182dc91512eb01a8baf4
-  data.tar.gz: 2a7114b0474c1419eada79c1d07a1e6c1fea4d76e1db36a4bd5c53c05244927e
+  metadata.gz: a2f0bde3d3e9cf606feab507df6d18cf5796d366e20fd4c2c326bff9baa9f7ea
+  data.tar.gz: ef0c87fdd8b008ef513515085f804a77b5304148f142339f1369ad038a78ab8b
 SHA512:
-  metadata.gz: 7e429f870a0f055aa05ea9279eca6d58eaea52b278cf611aec4ee809947316246b98dd782f887ce53ce21373a3dcfebe77260b74a29b7f70cfdb9d9c218ae71b
-  data.tar.gz: 8e086d10be125ada08f5609e56af8552ebf264d0cd8f09553eb4e1d56f0c4365e9979c802030c2f4686fc91717bebb76492b98115e3c6adaad406a45496b5c8b
+  metadata.gz: c8e6dc53dbf3bb5ee9c927e87f11c05d53725e970da5129d8334924cec2a25c162f4ab914f7b425287be6aa797ed56ab41a11576d0cbd6ad18be3c1e5ce45fb1
+  data.tar.gz: 90122ff8e4e5672f9c16a5d0779fbf887082353d8a9ebb9e52f18a3080f37bb80aee6d50ada5e14b38fd530fd5842a00610919157003af8e4729fa8cc13fc8dd

data/README.md

@@ -78,17 +78,19 @@ You're all set.
 
 ## Usage
 
-Let's you already have a ClickThrough model, storing click-throughs from campaigns. For now we'll just say it click_throughs have a `team_id` (in Bullet Train apps, your account is associated with a team).
+Let's say you already have a ClickThrough model, storing click-throughs from campaigns. For now we'll just say it click_throughs have a `team_id` (in Bullet Train apps, your account is associated with a team).
 
-You'd like a chart to appear in your Dashboard, showing how many click-throughs per day (so we'll group by), associated with your Team.
+You'd like a chart to appear in your Dashboard, showing how many click-throughs per day (so we'll group by day), associated with your Team.
 
 ```bash
 bin/super-scaffold supercharts:chart ClickThrough Team
 ```
 
+This will generated some new files and modify some files like inserting a `turbo_frame` in your `team#show` file, modifying your `roles.yml` file, etc. Look over the changes and commit when satisfied.
+
 ### Generate some test data
 
-We'll use a FactoryBot `trait` to randomize the `created_at` property for the test data we'll create.
+We'll use a FactoryBot `trait` to randomize the `created_at` property for the test data we'll create. This is the change I suggest you make to your `factories/click_throughs.rb` file:
 
 ```ruby
 # test/factories/click_throughs.rb
@@ -111,16 +113,126 @@ FactoryBot.create_list(:click_through, 450, :created_last_2_months, team_id: 1)
 
 Visit your app in `localhost:3000` and you should see your new chart.
 
-![Example chart inside a Bullet Train app showing Click Throughs in the last 30 days](https://user-images.githubusercontent.com/104179/194341008-c8b9f232-4117-4c8a-b93f-e95cf1d5159f.gif)
+![Example chart inside a Bullet Train app showing Click Throughs in the last 30 days](https://user-images.githubusercontent.com/104179/198366639-cd73eba5-eeb7-4654-bb35-8b0415b964c8.gif)
 
 ## Modifying the chart
 
-Coming soon...
+### The smallest change: switching to a bar chart
+
+Changing to a bar chart is super easy: just change the following line in your `show.html.erb`
+
+From:
+
+```html
+data-superchart-type-value="line"
+```
+
+To:
+
+```html
+data-superchart-type-value="bar"
+```
+
+### Other chart types: new Stimulus controller
+
+Under the hood, the default Superchart is built using a chart.js instance wrapped inside a Stimulus controller.
+
+For the following types of changes, you'll need to create your own Stimulus controller, duplicating the main `superchart_controller.js` found in this repo.
+
+* Changing to a multi-line, stacked area or stacked bar chart
+* Changing to a radial chart, a scattered plot, a box plot or any other chart
+
+### Any other change: it depends
+
+If you just want to make aesthetic changes, you can change the following css variables found at the top of your scaffolded `show.html.erb`. In this case, these are all TailwindCSS classes that set the appropriate custom CSS properties scoped to just that chart.
+
+```html
+[--axis-color:theme('colors.gray.300')] dark:[--axis-color:theme('colors.darkPrimary.500')]
+[--grid-color:theme('colors.gray.100')] dark:[--grid-color:theme('colors.darkPrimary.800')]
+[--line-color:#a86fe7]
+[--point-color:theme('colors.gray.800')] dark:[--point-color:theme('colors.white')]
+[--point-stroke-color:theme('colors.white')] dark:[--point-stroke-color:theme('colors.darkPrimary.700')]
+[--point-stroke-color-hover:theme('colors.gray.100')] dark:[--point-stroke-color-hover:theme('colors.darkPrimary.800')]
+[--bar-fill-color:var(--line-color)]
+[--bar-hover-fill-color:var(--point-color)]
+[--point-radius:4] md:[--point-radius:6]
+[--point-hover-radius:6] md:[--point-hover-radius:10]
+[--point-border-width:3] md:[--point-border-width:4]
+[--point-hover-border-width:2] md:[--point-hover-border-width:3]
+``` 
+
+If you'd like to override some chart.js options, you can do so in the `chartjsOptions` element:
+
+```html
+<!-- This can only include valid JSON, but no functions. This is not code that will be evaluated -->
+<template data-superchart-target="chartjsOptions">
+  {
+    "borderColor": "#000"
+  }
+</template>
+```
+
+Note that to make this work with both light and dark mode, you might as well use a custom CSS property, which Supercharts lets you do (but chart.js does not support by default):
+
+```html
+<!-- cssVar is a special sub-property which Supercharts will properly interpret as the value of the custom CSS property you set it to -->
+<template data-superchart-target="chartjsOptions">
+  {
+    "borderColor": {
+      "cssVar": "--my-custom-accent-color"
+    }
+  }
+</template>
+```
+
+But if the changes you'd like to make is in the list below, you'll need to make your own custom Stimulus controller:
+
+* The chart.js options you'd like to override includes JavaScript code (e.g. callback functions on properties)
+* Including more than one series (multi-line chart, etc)
+* Including annotations
+* Including a custom hover overlay
+* You need to change a chart.js option that's deeply nested (e.g. `scales.x.grid: false`) because it'll override all options in the top option
 
 ## Contributing
-Contribution directions go here.
+
+### Local development
+
+* Create a Bullet Train app
+* Use the instructions above to include the required gems and the npm package
+* Create a `local/` directory into which you'll clone a copy of this repo:
+
+```bash
+mkdir local
+cd local/
+git clone <this REPO URL>
+```
+
+* In your Gemfile, change the gem to use the local path:
+
+```ruby
+gem "supercharts-bullet_train", path: "local/supercharts-bullet_train"
+```
+
+Then do
+
+```bash
+bundle install
+```
+
+* For modifying the JavaScript, Stimulus Controllers, you'll need to install `yalc` and use it to point to your local copy of the npm package:
+
+```bash
+yarn global add yalc
+cd local/supercharts-bullet_train
+yarn build # build the local changes
+yalc push # publish the npm package locally on your own computer
+cd ../../ # go back to the bullet-train project
+yalc link @supercharts/supercharts-bullet-train
+cd local/supercharts-bullet_train
+yarn watch # continually watch for JavaScript changes, re-build the npm package and push to the Bullet Train app
+```
 
 ## License
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem and npm package are available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
 [bullet-train]: https://bullettrain.co

data/app/views/account/scaffolding/completely_concrete/tangible_things/tangible_things_chart/show.html.erb

@@ -20,7 +20,7 @@
     data-supercharts--describable-hide-contextual-description-class="hidden"
   >
     <%= turbo_frame_tag :charts_tangible_things_filters do %>
-      <div class="flex justify-start">
+      <div class="sm:flex justify-start">
         <div class="relative">
           <div data-supercharts--describable-target="overallDescription">
             <h2 class="text-xs uppercase dark:text-white/50">
@@ -50,7 +50,7 @@
             </p>
           </template>
         </div>
-        <div class="ml-auto">
+        <div class="mt-4 sm:mt-0 ml-auto">
           <div
             data-controller="supercharts--filters" data-supercharts--filters-event-name="superchart:update-chart"
           >

data/lib/bullet_train/supercharts/version.rb

@@ -1,5 +1,5 @@
 module BulletTrain
   module Supercharts
-    VERSION = "0.1.14"
+    VERSION = "1.0.0"
   end
 end

data/lib/scaffolding/supercharts_chart_transformer.rb

@@ -22,7 +22,7 @@ class Scaffolding::SuperchartsChartTransformer < Scaffolding::SuperchartsTransfo
     # add children to the show page of their parent.
     unless cli_options["skip-parent"] || parent == "None"
       lines_to_add = <<~RUBY
-        <div class="mt-4 [--chart-height:250px] md:[--chart-height:200px]">
+        <div class="mt-4 [--chart-height:150px] md:[--chart-height:200px]">
           <%= turbo_frame_tag :charts_tangible_things, src: polymorphic_path([:account, @creative_concept, :tangible_things, :chart], timespan: "1m") do %>
             <%= render "shared/supercharts/chart_skeleton" do %>
               Tangible Things&hellip;

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: supercharts-bullet_train
 version: !ruby/object:Gem::Version
-  version: 0.1.14
+  version: 1.0.0
 platform: ruby
 authors:
 - Pascal Laliberté
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-10-18 00:00:00.000000000 Z
+date: 2022-10-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails