Pattern Props and Slots
When defining the mutable properties of a pattern, it’s important to strive for a single source of definition. This way, if those properties grow or change, we can be sure they’re up to date wherever they’re referenced (in docs, in the Schema Editor, etc).
In Knapsack, properties (or "props") are used to pass data into a pattern to create a specific presentation or implementation. Slots are props specifically used to pass other objects (e.g. a component) into the pattern; for example, inserting a button into a card component.
Users can define props and slots for a pattern in multiple ways:
Defining via the Pattern Settings UI
Using the Knapsack UI to define the Props and Slots for a pattern ensures they’ll be readable everywhere they’re referenced in the documentation site.
When viewing a Template Tab on a Pattern Page, click the three dots ("Edit Pattern API") at the top right of the schema form.
The Pattern Settings will appear in a modal where you can define the Props and Slots for the selected Pattern Template.
Expand any Prop or Slot definition to see extra settings associated with it.
Note: Slots can be used to pass patterns into other patterns. Knapsack actually allows you to pass Pattern Examples into other Pattern Examples via the slots portion of the Schema Editor.
When you click the "Save Changes" button, the Schema Editor, along with the Props and Slots definition tables below the Schema Editor, will automatically update. If you happen to be using the Pattern Variations Block somewhere to document something like size variations, that documentation will also be automatically updated.
If you happen to be using Typescript, Knapsack also auto generates type definitions from the Props and Slots you’ve defined in the UI. You can import them from the /dist/react.d.ts file (you may need to restart your dev environment to see these files generated initially).
NOTE: Support for Arrays is currently in alpha, and is limited to an Array of Strings. Expanded support for the JSON Schema Spec is planned for 2022.
Defining Custom Properties
If you need to define properties in a way not supported by the Pattern API Editor, or you prefer to edit the JSON directly, you can do so within the Prop Spec section of the Editor. This area supports live editing, allowing you to expand or override the default options provided in the UI.
Looking for Objects as Props?
Looking for Components as Props?
Defining by Inference
Support for spec inference is currently limited to React with Typescript and Vue.
You may have already defined properties for your component in code and don’t want to use the Knapsack UI to define them. In this case, for certain templating languages, Knapsack can infer the spec from your code.
How to enable "Infer Spec"
To enable Infer Spec, simply connect your source template, navigate to the the Pattern API Editor, and enable the Enable infer spec toggle, then click Save Changes.
When you refresh your browser, Knapsack will have generated the Schema Editor form and the Prop/Slot definitions. If you update the spec in your coded file, it will reflect in Knapsack after a browser refresh.
Note for React: In order to have children read as a Slot by Knapsack, add a comment to your props definition (this is required, because otherwise children would be assumed by all components):
type Props = {
title?: string;
children?: React.ReactNode;
};