instructure-ui

What's New in 6.5.0?

New InstUI Starter App Generator

We were inspired by the simplicity of spinning up projects using create React app, and wanted to provide that same convenience to build apps with Instructure UI. As of the latest release, you can now use instui-cli to generate react apps configured with Instructure UI's presets out of the box. This includes settings for webpack, babel, eslint, and postcss. The canvas theme is also already imported for you and ui-themeable is preinstalled with a simple themeable component example. All you have to do is start developing.

$ npx @instructure/instui-cli create app --name MyInstuiApp
$ cd MyInstuiApp
$ yarn && yarn start

For more detailed usage and documentation, hit up the Quick Start guide on the instructure.design homepage.

Integration with Codesandbox

Codesandbox makes it easy to share and edit code directly in the browser. All starter apps ship with an open:sandbox command which allows you to open your project in codesandbox if it is stored in a public GitHub repository. Fill in the repository field in your package.json, push your latest changes, and then do

$ yarn open:sandbox

Prototyping with Instructure UI

Our starter app and Codesandbox integration emerged from discussions about how we develop
prototypes that can be shared between developers and designers. We needed a system that would
allow us to easily:

• Create prototypes using an Instructure UI development environment
• Share and collaborate on prototypes with developers and designers
• Get a higher fidelity representation of the UX than is possible with static prototyping
• Share the actual interface code demonstrating what Instructure UI components should be used

Codesandbox gave us most of this out of the box. In fact, we initially considered using
it for our entire prototyping workflow. However, as our prototypes became larger Codesandbox
was less performant in the browser. We also found that we preferred to work in our standard
IDEs locally with our typical development configurations. Additionally, we were uncomfortable
placing all the source in Codesandbox. It seemed too far removed from the rest of Instructure
code currently living on GitHub, and we wanted to make sure we still had versioning.

Speaking of GitHub, we discovered that GitHub Codesandbox integrations could offer compelling
solutions to the issues above. With a little scripting we were able to come up with a workflow
that would combine the best of both worlds. Here are some of the key ideas:

• Prototypes with Instructure UI presets can easily be generated using the instui create app command
• Prototypes can be edited and run locally in the developer's preferred IDE using their typical tools
• Prototypes are committed to a single GitHub repository
• When we want to share a prototype, we can simply open the GitHub source in Codesandbox (using the open:sandbox command mentioned above)
• We can share the Codesandbox link with developers and designers
• Any changes made in Codesandbox during the collaborative stages can be committed back to GitHub using Codesandbox

Even though this workflow is WIP, we're excited about the possibilities. We hope you'll find some of
this useful or at least mildly interesting. Also, if you have ideas or improvements reach out!
We believe that better prototypes will mean better collaboration between engineering and product
design, and ultimately better interfaces for our users.

AppNav

Many Instructure products appear inside the Canvas chrome — a fancy way of saying that they appear to be part of Canvas to the user. AppNav provides a main navigation for these apps that works visually next to Canvas' global navigation. (Having said that, AppNav also works fine as a standalone nav outside of Canvas.)

AppNav's navigation items can render as either links or buttons, and feature a renderAfter prop you can use to easily align an element such as a badge with the item's text. AppNav also provides a renderAfterItems prop that, you guessed it, renders content after the navigation items (a separate set of action buttons, for example).

AppNav is currently an experimental component because it is not responsive yet. Once we make the layout responsive, the experimental flag will be removed.

Select/Selectable/Options

Keeping with our direction of moving to controlled-only components, Select has been rebuilt from the ground up as a 100% controlled component. Combobox components like Select are used for a myriad of different use cases, and it's very difficult to prescribe functionality that fits every single one. To combat this recurring issue, we thought it best to make only the safest assumptions under the hood of Select and leave the specifics to the consumer.

Select is composed using a number of our other components — most notably Selectable and Options. Selectable facilitates the creation of combobox widgets, providing the attributes needed to associate an input with a list of selectable options navigable by mouse, keyboard, and screen reader. Selectable was previously released as an experimental component, but is now fully implemented in both DateInput and Select and ready for action.

Options is a component that provides views for a list of interactive list items. We realized this kind of view-only component could help consolidate styles in our existing components, like Select or Menu — and facilitate the creation of new ones as well. Previously, if Select didn't quite fit your use case, you'd probably need to build something completely from scratch. Now, pairing Options and Selectable can provide a great starting point for a custom combobox.

TL;DR: InstUI 6. New CLI tool makes upgrading easy. Codemods are even better. Goodbye React 0.14. Shake your trees and use named imports.

InstUI 6 is here, and it has a few fun surprises.

InstUI 6 should be the easiest upgrade in the history of InstUI. We documented all of the breaking changes in components that would occur; most changes are simply the removal of deprecated code. If you’ve fixed all of your console warnings, upgrading to InstUI 6 should be smooth sailing.

💲 instui-cli

Smoother sailing than ever, in fact, thanks to the new INSTUI CLI TOOL:


With npx

$ cd your-repository

$ npx @instructure/instui-cli upgrade --version 6


Globally installing with yarn or npm

$ npm install -g @instructure/instui-cli

  # or
  yarn global add @instructure/instui-cli

$ cd your-repository

$ instui upgrade --version 6

Every InstUI package in your repository is updated to 6.0, and all of the codemods necessary to remove deprecated props and packages are run effortlessly.

With future releases, you can use instui upgrade for all of your InstUI upgrading needs, even for minor and patch versions. If you’re in a hurry and want to skip running codemods, instui upgrade-packages is also available, but we encourage you to just use instui upgrade every time to help you catch deprecations earlier.

The instui CLI is going to continue to grow and improve. We’d love to hear your ideas for what we can do with it.

🔀 Codemods are Cooler

Speaking of codemods, we’ve made a number of improvements to how they work.

• The patterns that codemods use are now stored in a separate package — instui-config — improving versioning and testing the changes we’re making to your code.

• Deprecations now reference the version at which we’re going to remove the deprecated code. That way, if you see a deprecation, you know how long you can still rely on that feature.

• Our Babel transpile will now output full paths to cross-package imports for CommonJS output and named (member) exports/imports for ES module output. See “Transforming Imports with ui-babel-preset” below to learn more about this change.


🛠 The Stuff We Know You’ll Have to Fix

Try as we might, there are a few places the codemods just won’t fix. If you aren’t seeing deprecation warnings about these in the console before the upgrade, you’re all set. If you upgrade without fixing these, you’ll get warnings and who knows what else might happen.

• Icons using the deprecated width and height props are going to break if you don’t switch to the size prop. We can’t change that one because the width/height props accepted magic numbers like 10px, but size only accepts named sizes like large.

• Alert and Img have props that changed in both name and type. If you’ve used a literal value for those props, our updated codemods will catch them. However, if you’ve used a variable or an invoked function, you’ll have to fix it yourself. For example, the codemod will change <Img cover={true} /> to <Img constrain="cover" />, but <Img cover={variable} /> would result in <Img constrain={variable} />. In the latter case only the prop name would be updated, not the variable value. The tables below outline the 6.0 equivalents for deprecated props if they need to be updated manually.


<Alert/>

<Img/>

Also, as we announced back in January, the variants of a Tooltip have changed. Though you won’t see any errors, there may be aesthetic contrast issues to resolve.

👋 So Long, React 0.14

InstUI 6 drops support for React 0.14. No one at Instructure is using it, so it was a safe choice. (InstUI 7 will drop support for React 15, but that’s another blog post.)

🌳 Tree Shaking and Webpack 4

All instructure-ui modules now provide a named export, and cross-package dependencies no longer reference the full /lib path. This means if you are using Webpack 4, you can convert default imports to named member imports and leverage tree shaking for smaller bundle sizes.

The default exports still exist for each component; however, we will likely remove the default exports in a future release to encourage usage of named member imports. With named member imports everyone gets the benefits of tree shaking as well as better IDE code refactoring and IntelliSense functionality.

🧙‍♂️ Transforming Imports with ui-babel-preset

If you are using @instructure/ui-babel-preset, it will now transform import paths by default, and you will need to opt-out of the transform. **⚠️ We do not recommend opting out unless you can be sure that all of your instructure-ui imports are consistent across your codebase—otherwise you will risk pulling in duplicates of instructure-ui modules.
**

// babel.config.js
module.exports = {
  presets: [[
    require(‘@instructure/ui-babel-preset’),
    {
      transformImports: true
      // ...
    }
  ]]
}

This will convert any non-default imports that are referencing the package only to reference the full path to the module instead. For example:

// a named member import:

import { Text } from '@instructure/ui-elements'

would be converted to

// a named import using the full module path:

import { Text } from '@instructure/ui-elements/lib/Text'

Note that any default imports you are currently using will not be transformed:


Import Text from '@instructure/ui-elements/lib/Text'

Why is this useful?


For Webpack 4 users

While you were previously able to use both import styles, mixing them in a single application can cause duplication of imported modules along with other potentially erroneous results. A single import style should be used. The babel transform standardizes import paths to ensure consistency and smaller bundle sizes.

For Webpack 3 users

The transform will save you some keystrokes by allowing you to do a named member import from the instructure-ui packages without having to specify the full module path, and you can start getting set up to do tree shaking when you are able to upgrade webpack, without increasing your JS bundle size. For example, you can do:

// a named member import:

import { Avatar } from '@instructure/ui-elements'

instead of:

// a named import with the full module path:

import { Avatar } from '@instructure/ui-elements/lib/Avatar'

or:

// a default import with the full module path:

import Avatar from '@instructure/ui-elements/lib/Avatar'

…and babel will make all of the paths consistent when your bundle is generated.