Generating a Kit

Creating a new kit requires multiple files in multiple locations in the repo so to make the process easier, Playbook provides a Kit Generator that creates the base files that can be build upon. Servers do not need to be running to run the kit generator, but if they are, be sure to stop and restart the servers after running the generator to allow everything to update properly.

Usage

You must be inside playbook/playbook to run this command:

bin/rails generate kit "Button"

By default the above command will generate a kit for each type (rails, react, and swift). You can use flags to limit kit creation to just one or two languages, and any combination is accepted.

# Generate a kit in one version only
bin/rails g kit button --rails

bin/rails g kit button --react

bin/rails g kit button --swift

# Generate a kit in two versions
bin/rails g kit button --rails --react

bin/rails g kit button --react --swift

bin/rails g kit button --swift --rails

Options

Adding Props via the command line is an optional feature. As of June 2024, Props are working for React kits only. Rails props must be manually added right now. This issue is on our backlog to resolve.

# Defining props
bin/rails generate kit "Button" --props text variant disabled

When passing the props option through the generator, the Kit Class is generated will all props ready to use in Rails HTML Partial.

Defining props with type

# Defining props with type
bin/rails generate kit "Button" --props text:string variant:enum disabled:boolean other:object

When props with type is passed through the generator, it will kickstart your Kit Class in my_kit.rb for Rails and my_kit.tsx for React by providing base validation.

# Example boolean prop type
def disabled
  true_value(configured_active, "true value", "false value")
end

# Example string prop type
def text
  default_value(configured_title, "default value")
end

# Example enum prop type
def variant
  variant_options = %w(option1 option2)
  one_of_value(configured_variant, variant_options, "default value")
end

Category Prop and Sorting the Kit

Category Prop

If a user knows exactly which category (that is, one of the 16 Submenu options under Components on the Playbook Website) they would like the newly generated kit to fall under, use the --category prop.

bin/rails generate kit large_button --category buttons

The category must match one of the existing categories (as making a new category is an infrequent occurrence and should be done manually with care). Use underscores to represent spaces ("Data Visualization" is data_visualization). If the category given has a typo or does not exist yet, an error message will appear and the kit will not be created. It can be used alone or in conjunction with one or multiple kit type or the props flag.

bin/rails generate kit large_button --react --rails --category buttons

bin/rails generate kit large_button --react --props text:string disabled:boolean --category buttons

The category prop is optional. If a user forgets to include it, or prefers to have the information appended to the bottom of menu.yml and manually sort it as was the previous protocol (see next paragraph), a user may do so

Sorting the Kit

When adding to the menu.yml file (without using the category prop) the generator does not reorder the list to place the new kit in alphabetical order but simply places it at the bottom of the list. Placing the new kit in the correct place alphabetically can be done manually. After moving your kit, ensure that menu.yml ends with a blank line so that the next time the kit generator is run, its contents appear on a new line.

Beta Prop and Kit Status

Beta Prop

When generating a new kit, users have the option to declare the status of the kit via the --beta prop.

bin/rails generate kit large_button --beta false

By default, all kits generated will be in beta, so this prop is only needed when you want to override the status.

Kit Status

If a kit is in beta, it will not be visible in the sidebar nor will it be discoverable in the search field. You will only be able to access the kit via direct link and the kit page will have a "beta" disclaimer appear at the top. In order to update the status of a kit, find the kit in the menu.yml file and change the status from "beta" to "stable" or vice versa.

Files Generated

The kit generator creates all the files and imports a base kit needs.

React and Rails Kits

Generated by running all kit versions (no flags appended) or with one of the following combinations:

--rails

--react

--rails --react

• Added to the main menu in config/data/menu.yml
• Kit SCSS Stylesheet created at app/pb_kits/playbook/pb_my_kit/_my_kit.scss
• Imported into the main kit stylesheet at app/pb_kits/playbook/site_styles/kit_style_index.scss
• Kit Example YML at app/pb_kits/playbook/pb_my_kit/docs/example.yml

Rails Kits

• Kit Class created at app/pb_kits/playbook/pb_my_kit/my_kit.rb
• Kit Rails Partial created at app/pb_kits/playbook/pb_my_kit/_my_kit.html.erb
• Kit Rails Example Usage at app/pb_kits/playbook/pb_my_kit/docs/_my_kit_default.html.erb

React Kits

• Kit React Component created at app/pb_kits/playbook/pb_my_kit/_my_kit.tsx
• Kit React Example Usage at app/pb_kits/playbook/pb_my_kit/docs/_my_kit_default.jsx
• Kit React Examples index at app/pb_kits/playbook/pb_my_kit/docs/index.js
• Kit React Pack file at app/pb_kits/playbook/packs/pb_my_kit.js
• Kit added to Index for React Files at app/pb_kits/playbook/index.js
• Imported into main kit js at app/pb_kits/playbook/packs/kits.js
• Imported examples into examples js at app/pb_kits/playbook/packs/examples.js

Swift Kits

If a kit is generated for swift only with --swift, only the following files are updated and created. No other imports or additions are set.

• Added to the main menu in config/data/menu.yml
• Kit Example YML at app/pb_kits/playbook/pb_my_kit/docs/example.yml
• Kit Swift Example Usage at app/pb_kits/playbook/pb_testtwentyseven/docs/_my_kit_default_swift.md