Skip to content

Commit

Permalink
docs: improve documentations in prep for v5
Browse files Browse the repository at this point in the history
  • Loading branch information
@ghiscoding-SE
ghiscoding-SE committed May 9, 2024
1 parent 62aa625 commit 2bcce65
Showing 1 changed file with 15 additions and 15 deletions.
30 changes: 15 additions & 15 deletions docs/migrations/migration-to-5.x.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,30 +6,30 @@ Another noticeable UI change is the migration from [Flatpickr](https://flatpickr
##### Flatpickr cons:
- barely supported (lots of opened PR but nothing merged for the past 2 years)
- not fully ESM ready (it's only partially ESM, for example it is detected as CJS in Angular-Slickgrid and requires an exception in `allowedCommonJsDependencies`)
- styling could be a bit more modern (the use of native select/input to change year/month/time is a bit outdated and rudimentary)
- styling could be a bit more modern (the use of native select/input to change year/month/time is a bit outdated and basic)
- date range selection is not very user friendly (UX)

##### Vanilla-Calendar (VC)
- pros:
- ESM ready
- modern styling and also includes Dark Mode theme
- date range becomes a lot more easy by displaying a picker with 2 months
- date range selection is a lot easier by displaying 2 months at a time in the picker
- cons:
- build size is slightly larger but its UI/UX is awesome (especially when chaning month/year)
- build size is slightly larger but its UI/UX is awesome (especially when changing month/year)
- settings are named differently and are not using flat config (complex object settings) and requires code change
- for example Flatpickr `minDate: 'today'` is instead `range: { min: 'today' }` in VC
- some settings were missing, like the `'today'` shortcut which is why I forked the VC project
- I did open a few PRs on the main project, so the hope is to drop the fork in the future while being a totally transparent change to you when it happens.

With this release, and after 7 years of development as a 1 man show (myself @ghiscoding), I believe that I have achieved all goals and even more than I originally planned to accomplish and with that being said, I am not foreseeing any new major releases on the short term. As a recap, I think that the biggest challenge was the removal of jQuery/jQueryUI and transition to native code, that took 2-3 years to accomplish, and I am of course very proud to have achieved. All dependencies are now also all ESM and the project is CSP compliant.
To summarize, the goal of this new release was mainly to improve UI/UX (mostly for Dark Mode) and also to make it fully ESM ready. Also noteworthy, the project is smaller in size (~100Kb smaller) compared to what it was in v2.x (that was when the user had to install jQuery/jQueryUI separately). So, considering that we're no longer requiring the install of jQuery/jQueryUI, and also considering that these 2 dependencies had a total of well over 200kb. We can safely assume that our project build size is in fact a lot smaller than it was 2 years ago, that is really nice to know considering that we kept adding features (like Dark Mode and other features) while still decreasing its size over the years :)

To summarize, the goal of this new release was mainly to improve UI/UX (mostly for Dark Mode) and also to make it fully ESM ready. Also noteworthy, the project is smaller in size (~100Kb smaller) compared to what it was in v2.x (that was when the user had to install jQuery/jQueryUI separately). So, considering that we're no longer requiring the install of jQuery/jQueryUI, and also considering that these 2 dependencies had a total of well over 200kb. We can safely assume that our project build size is in fact a lot smaller than it was just 2 years ago, that is really nice to know considering that we kept adding features (like Dark Mode and other features) while still decreasing its size over the years :)
With this release, and after 7 years of development as a 1 man show (myself @ghiscoding), I believe that I have achieved all goals and even more than I originally planned to accomplish. So with that being said, I am not foreseeing any new major releases for a while. As a recap, I think that the biggest challenge was the removal of jQuery/jQueryUI and transitioning to native code, that took 2-3 years to accomplish, and I am of course very proud to have achieved. All dependencies are now also all ESM and the project is now CSP compliant as well.

#### Major Changes - Quick Summary
- minimum requirements bump
- Node >=v18.x
- Bootstrap >=v5.x (or any other UI framework)
- SASS >=v1.35 (`dart-sass`)
- Node v18.0+
- Bootstrap v5.0+ (or any other UI framework)
- SASS v1.35+ (`dart-sass`)
- migrated from Flatpickr to Vanilla-Calendar (visit [Vanilla-Calendar-Pro](https://vanilla-calendar.pro/) for demos and docs)
- migrated from MomentJS to [Tempo](https://tempo.formkit.com/) (by the FormKit
team)
Expand Down Expand Up @@ -68,7 +68,7 @@ or move the class to the parent container and have both the icon & the text `inh
#### SASS variables
A lot of SASS variables were changed, we recommend that you take a look at the [_variables.scss](https://github.com/ghiscoding/slickgrid-universal/blob/master/packages/common/src/styles/_variables.scss) file to compare them with your SASS overrides and fix any SASS build issues. For example a lot of the ms-select variables and all Flatpickr related variables were deleted (note that Vanilla-Calendar doesn't actually have any variables). Also a lot of the icon related variables were renamed and updated (icons now all have the suffix `-icon-svg-path` for the SVG vector path, you can easily change them with SASS).

> **Note** if you want create your own SVGs icons in pure CSS, you could use the `generateSvgStyle()` SASS function from Slickgrid-Universal [`svg-utilities.scss`](https://github.com/ghiscoding/slickgrid-universal/blob/master/packages/common/src/styles/svg-utilities.scss) (take a look at the [`slickgrid-icons.scss`](https://github.com/ghiscoding/slickgrid-universal/blob/master/packages/common/src/styles/slickgrid-icons.scss) for some usage)
> **Note** if you want to create your own SVGs icons in pure CSS, you could use the `generateSvgStyle()` SASS function from Slickgrid-Universal [`svg-utilities.scss`](https://github.com/ghiscoding/slickgrid-universal/blob/master/packages/common/src/styles/svg-utilities.scss) (take a look at the [`slickgrid-icons.scss`](https://github.com/ghiscoding/slickgrid-universal/blob/master/packages/common/src/styles/slickgrid-icons.scss) for some usage)
#### SASS (dart-sass) `math` polyfills are removed
When SASS (dart-sass) released their version 1.33 (~3 years ago), it caused a ton of console warnings (and a lot of unhappy users) in projects that were using `/` in their SASS files (for math division) instead of their new `math.div()` function. To avoid seeing all these warnings, I added a temporary polyfill at the time (that piece of code was actually copied from the Bootstrap project). That polyfill patch was put in place about 3 years ago, so I'm assuming that most users have already upgraded their SASS version and already fixed all of these warnings... So, I think it's now safe to remove this polyfill, because like I said earlier, it was really meant to be a temp patch. If you see any warnings coming back, then a suggestion would be to use the SASS CLI `--quiet-upstream` option.
Expand Down Expand Up @@ -138,7 +138,7 @@ There were a few remaining traces of jQueryUI CSS classes like `.ui-state-defaul
}
```

#### Formatters Cleanup & Removals
### Formatters Cleanup & Removals

Since we now use SVGs everywhere and we got rid of any Font usage (no more Font-Awesome code anywhere), the `checkmark` Formatter no longer has any reason to exist and was removed. If you were using it and still plan to use Font-Awesome in your project, then you'll have to either recreate the Formatter yourself or use alternatives. You could use the `Formatters.icon` or `Formatters.iconBoolean` which require the CSS classes to be provided via `params`. Or as a last alternative, and if you are importing the optional SVG icons `.mdi` subset, then we recommend you simply switch to the `checkmarkMaterial` Formatter.

Expand Down Expand Up @@ -229,14 +229,14 @@ complexityEditor.collection.push({ value: 9, label: 'Hard' });
complexityEditor.collection.push({ value: 9, label: 'Hard' });
```

if you want to read the Editor class (e.g. `Editors.longText`), you can now reference it via `column.editor.model` or via `column.editorClass`
if you want to reference the Editor class (e.g. `Editors.longText`), you can now get it from either `column.editor.model` or `column.editorClass`

## Grid Functionalities

### Sanitizer (DOMPurify)
`DOMPurify` is now completely optional via the `sanitizer` grid option and you must now provide it yourself. The main reason to make it optional is because even though most users would prefer to use `dompurify`, some might prefer to use `isomorphic-dompurify` for SSR support. Consider that it is now optional, you could also technically speaking skip the `sanitizer` configuration completely, but that is not at all recommended.

> **Note** even if the `sanitizer` is now optional, we **strongly suggest** that you configure it as a global grid option to avoid possible XSS attacks from your data and also to remain CSP compliant. Note that for Salesforce users, you do not have to configure it since Salesforce already use DOMPurify internally.
> **⚠ Note** even if the `sanitizer` is now optional, we **strongly suggest** that you configure it as a global grid option to avoid any XSS attacks from your data and also to remain CSP compliant. Also note that for Salesforce users, you do not have to configure it since Salesforce already use DOMPurify internally.
```diff
// prefer the global grid options if possible
Expand All @@ -248,10 +248,10 @@ this.gridOptions = {
> **Note** If you're wondering about the `ADD_ATTR: ['level']`, the "level" is a custom attribute used by SlickGrid Grouping/Draggable Grouping to track the grouping level depth and it must be kept for the group indentation to work properly.
### From MomentJS to [Tempo](https://tempo.formkit.com/)
I wanted to replace MomentJS for a long time now (it's been deprecated for years and is CJS only), but it was really hard to find a good replacement (I tried DayJS, Luxon, date-fns and they all had problems)... and here comes [Tempo](https://tempo.formkit.com/)! With Tempo, I was finally able to migrate by taking advantage of their `parse()` and `format()` functions, which are the most important for our datagrid use case. The library also has plenty of extra optional functions as well, like `addDay()`, `diffDays()`, ... Another great thing about Tempo is that they use the same format [tokens](https://tempo.formkit.com/#format-tokens) as MomentJS, so the conversion on that side was super easy.
I really wanted to replace MomentJS for a long timeeee... (it's been deprecated for years and is CJS only), but it was really hard to find a good replacement (I tried many alternatives like `DayJS`, `Luxon`, `date-fns` and they all had problems at least for a datagrid use case where parsing & formatting is important)... and here comes [Tempo](https://tempo.formkit.com/)! With Tempo, I was finally able to migrate by taking advantage of their `parse()` and `format()` functions, which are the most important in a datagrid usage. The library also has plenty of extra, and optional, functions as well, for example `addDay()`, `diffDays()`, ... Another great thing about Tempo is that they use the same format/parse [tokens](https://tempo.formkit.com/#format-tokens) as MomentJS, so the conversion on that side was super easy.

This migration should be transparent to most users like you. **However** if you are currently using MomentJS in your project, then I would suggest you to consider trying [Tempo](https://tempo.formkit.com/) in order to modernize your project and also lower your dependencies count. The other great advantage of Tempo is that it's ESM and that helps a lot in decreasing our build size footprint because ESM also means that it is Tree Shakable (only import and build what you use).
The migration to Tempo should be transparent to most users like you. **However** if you are currently using MomentJS in your project, then I would suggest you to consider trying [Tempo](https://tempo.formkit.com/) in order to modernize your project and also lower your dependencies count. The other great advantage of Tempo is that it's ESM and it helped a lot in decreasing our build size footprint because ESM also means that it is Tree Shakable (only import and build what you use). By using Bundlephobia and comparing [@slickgrid-universal@4.7.0](https://bundlephobia.com/package/@slickgrid-universal/[email protected]) we can see that `moment-mini` is taking 41.5Kb, while Tempo takes only 16.6Kb in [@slickgrid-universal@5.0.0](https://bundlephobia.com/package/@slickgrid-universal/[email protected]), that is a decrease of almost 25Kb (ESM makes a huge difference).

### Smaller Size - Full ESM

To compare size, you can take a look at BundlePhobia for previous [v1.4.0](https://bundlephobia.com/package/@slickgrid-universal/[email protected]) and [v5.0.0](https://bundlephobia.com/package/@slickgrid-universal/[email protected]) and you'll see that the gzip version went down by 17Kb (or 8.9%) and that's just for 1 dependency of the Slickgrid-Universal (there's a few more installed behind the scene). From that website you can also see that removing MomentJS & Flatpickr had a large impact.
To compare size, you can take a look at BundlePhobia for the older [v1.4.0](https://bundlephobia.com/package/@slickgrid-universal/[email protected]) (when we required jQuery/jQueryUI) and [v5.0.0](https://bundlephobia.com/package/@slickgrid-universal/[email protected]) and you'll see that the gzip version went down by 17Kb (or 8.9%) and that's just for 1 dependency of the Slickgrid-Universal workspace (there's a few more installed behind the scene, like the footer component, binding, utils, ...). From that website you can also see that removing MomentJS & Flatpickr had a significant impact especially since the replacements are ESM and tree shakable.

0 comments on commit 2bcce65

Please sign in to comment.