Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Heydon/bruck
A prototyping system built with web components and the Houdini Paint API
https://github.com/Heydon/bruck
Last synced: 11 days ago
JSON representation
A prototyping system built with web components and the Houdini Paint API
- Host: GitHub
- URL: https://github.com/Heydon/bruck
- Owner: Heydon
- Created: 2018-09-05T13:34:06.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2023-08-25T11:38:13.000Z (about 1 year ago)
- Last Synced: 2024-07-31T07:18:18.124Z (3 months ago)
- Language: JavaScript
- Size: 579 KB
- Stars: 511
- Watchers: 24
- Forks: 13
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome - bruck - A prototyping system built with web components and the Houdini Paint API (JavaScript)
- my-awesome-list - bruck
- awesome-web-components - bruck - Prototyping system built with web components and the Houdini Paint API. (Miscellaneous / Custom State Pseudo Class)
README
# 
**Bruck** is a lo-fi prototyping system made with web components. Quickly create and comment on interface layouts. The output is screen reader accessible, and responsive without you having to author breakpoints.
[**Try out the demo**](https://heydon.github.io/bruck/)
**Warning: Bruck is experimental, and in its very early stages of development.**
You can mock up real or dummy content with a set of primitive layout components
## Get started
1. Clone this repository.
2. (No `npm install` because there's no dependencies, unless you want to contribute — then you may need the **Jest** stuff)
3. Write HTML with the help of the components (below) in the `index.html` and split-screen `editor.html` files. Check out a demo in `demo.html`.
4. Serve by using something like [http-server](https://www.npmjs.com/package/http-server) at the root
5. That's pretty much it. Requests and contribution offers welcome.
## Documentation
(Used in conjunction with the [utility classes](#utility-classes).)
* [Components](#components)
* [``](#t-ext)
* [``](#w-ords)
* [``](#i-mage)
* [``](#c-enter)
* [``](#b-ox)
* [``](#s-tack)
* [``](#g-rid)
* [``](#c-luster)
* [``](#s-pread)
* [``](#s-idebar)
* [``](#l-ine)
* [``](#i-con)
* [``](#p-rogress)
* [``](#d-rawer)
* [``](#s-creen)
* [``](#g-o)
* [``](#f-low)
* [``](#c-omment)
* [``](#c-lone)
* [``](#i-nput)
* [``](#t-extarea)
* [``](#s-elect)
* [``](#c-heckbox)
* [``](#r-adios)
* `` ([see **Working with data**](#working-with-data))
* `` ([see **Working with data**](#working-with-data))
* [Utility classes](#utility-classes)
* [Working with data](#working-with-data)
* [Actions](#actions)
## Components
### ``
The `` component lets you generate a paragraph of dummy text. Each word is represented as a line. 'Words' wrap like any other text content.
#### Props
words
A comma separated range e.g. words="30,60"
Default: 15,20
#### Example
```html
```
#### Accessibility information
Just the lorem ipsum text underlying the emblematic line-words.
### ``
The `` component lets you generate sets of words, picked at random from lorem ipsum. It is an inline element, so can be used to generate text inside a `
` or `
` etc.
#### Props
count
The number of words. Can be a set integer e.g. count="5" or a random integer picked from a supplied range e.g. count="5,10".
Default: 2,3
capitalize
Capitalizes the first letter of each word (Boolean)
sentence
Capitalizes the first letter of the first word, and appends a period followed by a space (Boolean)
repeat
How many times to repeat the pattern (i.e. how many sentences to produce). Can be a set integer e.g. count="5" or a random integer picked from a supplied range e.g. count="5,10".
#### Example
The following will produce a paragraph or 3-4 sentences.
```html
```
#### Accessibility information
Just the lorem ipsum text verbatim.
### ``
The `` element creates an accessible dummy/placeholder image (with a X-through style generated via Houdini's Paint API). The available horizontal space is filled unless `minWidth` and `maxWidth` props are supplied.
#### Props
ratio
The expression of an aspect ratio e.g. ratio="3:4".
Default: 1:1
caption
The text for a caption, which is placed in a <figcaption> element after the image itself e.g. caption="A giant crab monster".
Default: nothing (<figcaption> omitted)
minWidth
Any CSS min-width value e.g. minWidth="5rem".
Default: 0
maxWidth
Any CSS max-width value e.g. maxWidth="5rem".
Default: none
#### Example
```html
```
#### Accessibility information
_"Image with [ratio] aspect ratio"_.
### ``
The simplest of components: just wraps some content with some padding, and a border if you want it.
#### Props
pad
Padding for all sides. A point on the modular scale (-5 to 10, or none) e.g. pad="2".
Default: 1
border
Whether to apply a border (Boolean)
Default: false (attribute omitted)
#### Example
```html
My box
```
#### Accessibility information
_"['Bordered'?] box containing [# of child elements] elements"_
### ``
The `` component lets you inject whitespace between flow elements. Wrap it around a set of elements and separate them visually. Critically, it accepts a `repeat` prop that lets you multiply its contents a set number of times.
#### Props
gap
A point on the modular scale (-5 to 10, or none) e.g. gap="2".
Default: 1
repeat
The number of times the content (light DOM children) will be repeated. Can be an integer e.g. repeat="5" or a range e.g. repeat="5,10" (a random integer within the range is picked).
Default: 0 (no repetition)
lines
Boolean: Whether or not to divide items with horizontal lines/borders
Default: omitted (no lines)
#### Example
```html
```
#### Accessibility information
_"Column of [# of child elements] elements"_
### ``
The `` element let's you easily compose a responsive grid using CSS's Grid algorithm. Like `` it lets you repeat the contents/children you supply. Useful for quickly mocking up a set of card components or similar.
#### Props
gap
A point on the modular scale (-5 to 10, or none) e.g. gap="2".
Default: 1
repeat
The number of times the content (light DOM children) will be repeated. Can be an integer e.g. repeat="5" or a range e.g. repeat="5,10" (a random integer within the range is picked).
Default: 0 (no repetition)
itemWidth
The 'ideal' width of the grid item as a CSS length value e.g. itemWidth="10ch". CSS Grid's auto-fit and minmax features ensure the layout is responsive.
Default: 15rem
#### Example
```html
Card title
```
#### Accessibility information
_"Grid of [# of child elements] elements, each [itemWidth] wide"_
### ``
The `` component uses Flexbox to let you cluster items around the horizontal center of their context. Items wrap where there is no room for them all on one line, maintaining responsiveness.
#### Props
gap
The gap between clustered items. A point on the modular scale (-5 to 10, or none) e.g. gap="2".
Default: 1
align
Maps to the Flexbox align-items property. Choice of center (default), top (flex-start), or bottom (flex-end).
Default: center
#### Example
```html
Will Something on the left
Something in the center
something on the right
```
#### Accessibility information
_"Set of [# of child elements] centrally grouped elements"_
### ``
The `` component uses Flexbox to let you separate items horizontally. Items wrap where there is no room for them all on one line, maintaining responsiveness.
#### Props
gap
The minimum gap between spread-out items. A point on the modular scale (-5 to 10, or none) e.g. gap="2".
Default: 1
spaces
Where the spaces occur. One of between (maps to justify-content: space-between) or around (maps to justify-content: space-around).
Default: between
align
Maps to the Flexbox align-items property. Choice of center (default), top (flex-start), or bottom (flex-end).
Default: center
#### Example
```html
Will be pushed to the left
Will appear in the center
Will be pushed to the right
```
### ``
The `` component wraps two child elements, with one as the designated 'sidebar' and the other taking up the remaining space. If more than two child elements are supplied, construction ceases and an error is returned.
The designated sidebar only _appears_ as a sidebar where it is narrower than its sibling. Otherwise, Flexbox reorganizes the two elements into a single column (uses the `flex-grow: 999` hack).
#### Props
gap
The gap between the sidebar and adjacent element. A point on the modular scale (-5 to 10, or none) e.g. gap="2".
Default: none
width
The width of the sidebar in contexts wide enough that it can be a sidebar. Any CSS length, e.g. width="25rem".
Default: 20rem
to
Which child element (left or right) to be the sidebar. Values can only be 'left' or 'right'; If anything different is supplied, 'left' is used by default.
Default: left (omit the attribute)
#### Example
Creates a sidebar of the second element (introduced with the `
` heading). The gap between the sidebar and the adjacent content matches the second point on the modular scale (one point higher than the default).
```html
The main content
The sidebar content
```
#### Accessibility information
_"Content with a [left || right] sidebar"_
### ``
The `` component configures child elements inline, with the option to add a separator. The separator can be any character or HTML.
#### Props
between
Some HTML to separate each item e.g. sep="·" or sep="|" (inline SVG can be used too!)
gap
A point on the modular scale (-5 to 10, or none) e.g. gap="2".
Default: 1
justify
Maps to the Flexbox justify-content property. One of left (flex-start), center (default), or right (flex-end).
Default: center
#### Example
```html
```
#### Accessibility information
_"Line of [# of child elements] elements"_
### ``
The `` component inserts an inline SVG icon, by name, from the **icons** folder (using fetch). The size of the icon is determined by its parent's `font-size`, or you can use the `u-h1` — `u-h6` utility classes on the `` itself.
#### Props
name (required)
The name of the icon, matching the filename (without extension) from the icons folder.
label
A string to describe the SVG as an image. Not necessary if the icon has accompanying, descriptive text (for example, alongside a <button>'s text content).
Default: omitted (no label or image role)
#### Example
```html
```
#### Accessibility information
None by default (it is assumed the icon will be accompanied by text). Or you can supply a label via the `label` prop. This will also include the `img` ARIA role.
### ``
The `` component displays a series of steps in a continuum to indicate how far along the user is in a process.
#### Props
steps (required)
A comma-separated set of labels for he consecutive steps, e.g. `steps="one,two,three"`.
current
The label of the current step, which takes aria-current="step" and a visual style to differentiate it from the other steps, e.g. current="two"
Default: the first step (whatever it is named)
#### Example
```html
```
#### Accessibility information
_"Progress indicator of [# of steps] steps"_ (in addition to list semantics and `aria-current`).
### ``
The `` component simply creates a centralized column (with horizontal margins set to `auto`). The `max-width` is set to the `--measure` custom property value (under **css/lib/variables.css**) by default.
#### Props
maxWidth
A CSS max-width value e.g. 30ch.
Default: the root --measure value
#### Example
```html
A centrally aligned document section
```
#### Accessibility information
NA
### ``
A basic collapsible section, as you might find in an accordion. The first child (light DOM) element is use to form a button. This is wrapped in a heading, for which the level can be adjusted using the `level` prop.
#### Props
level
An integer between 1 <h1> and 6 <h6> e.g. level="3".
Default: 2
open
An integer between 1 <h1> and 6 <h6> e.g. level="3".
#### Example
```html
Collapsible section title
This content appears when the handle is clicked...
...and so does this content.
```
#### Accessibility information
_"Collapsible section"_
### ``
The `` element lets you define whole screens (like those defined within a routed Single Page Application). You can link between screens using either the `` call-to-action component, or regular links pointing to hash fragments that match the screens' `id`s.
The `` with the `index` `id` is displayed on page load.
#### Props
id (required)
A valid id attribute value e.g. id="about".
label
A string describing the screen (think <title>) e.g. label="My App: Home page".
Default: the screen's id value
#### Example
```html
The default screen
About
The about screen
Home
```
#### Accessibility information
The value of the label prop (or the id value as a fallback).
### ``
A call-to-action type component, specifically for linking between `` elements.
#### Props
to (required)
A valid id attribute value for a <s-creen> component e.g. to="index".
#### Example
```html
Home
```
#### Accessibility information
The text content of the link.
### ``
The `` component lets you group elements as a navigable sequence of steps, such as sections in a form. On hover and focus, previous and next buttons are exposed to change steps.
#### Props
hideControls
Boolean. Whether to show the previous and next buttons.
Default: false (attribute omitted)
#### Methods
prev()
Show the previous element
next()
Show the next element
goTo(index)
Show the element with the supplied index
#### Example
```html
Step 1
Step 2
Step 3
```
#### Accessibility information
_"Sequence of [# of child elements] steps"_
### ``
Allows you to write a comment for any part of the interface, simply by wrapping it and supplying text for the `wording` prop. The comment is revealed by pressing a '?' button that is revealed on both hover and focus.
#### Props
wording
A basic string e.g. wording="The main page content".
Default: 'TBD'
#### Example
```html
Card title
```
#### Accessibility information
The comment wrapper is identified as a region. The buttons to open and close the comment are suitably labeled.
### ``
The `` lets you instantiate content from a named ``. It's the easiest way to reuse compound components.
#### Props
of (required)
The id of a <template> element e.g. of="header".
#### Example
```html
```
#### Accessibility information
NA (whatever the cloned elements provide)
### ``
The `` component is an abstraction of a basic `type="text"` input/label, with accessible labeling built in.
#### Props
label
A string for the `` element e.g. label="Your favorite animal"
Default: 'Text'
name (required)
A valid name value (mapping to the standard name attribute), e.g. name="favoriteAnimal"
value
Optionally prepopulate a value, e.g. value="aardvark"
#### Example
```html
```
#### Accessibility information
Standard `` and `` elements are used (and associated with one another) and convey the standard/expected semantics to assistive technologies.
### ``
The `` component is an abstraction of a basic `` with accessible labeling built in.
#### Props
label
A string for the `` element e.g. label="Tell us about your favorite animal"
Default: 'Text box'
name (required)
A valid name value (mapping to the standard name attribute), e.g. name="favoriteAnimal"
value
Optionally prepopulate the <textarea>, e.g. value="The aardvark is my favorite because it is telepathic"
#### Example
```html
```
#### Accessibility information
Standard `` and `` elements are used (and associated with one another) and convey the standard/expected semantics to assistive technologies.
### ``
The `` component is an abstraction of a basic ``/``s pattern, with accessible labeling built in.
#### Props
label
A string for the `` element e.g. label="Your favorite animal"
Default: 'Select'
name (required)
A valid name value (mapping to the standard name attribute), e.g. name="favoriteAnimal"
options (required)
A comma-separated list of available options, e.g. options="dog, cat, fish, aardvark"
Note: Both "dog,cat,fish,aardvark" and "dog, cat, fish, aardvark" are acceptable (the spaces are removed)
selected
The string that represents the selected option (if any), e.g. selected="aardvark"
Default: No item is selected
#### Example
```html
```
#### Accessibility information
Standard `` and `` elements are used (and associated with one another) and convey the standard/expected semantics to assistive technologies.
### ``
The `` component is an abstraction of a basic `type="checkbox"` input/label, with accessible labeling built in.
#### Props
label
A string for the `` element, e.g. label="Do you like animals?"
Default: 'Check'
name (required)
A valid name value (mapping to the standard name attribute), e.g. name="likesAnimals"
checked
Boolean: whether the checkbox is checked by default
#### Example
```html
```
#### Accessibility information
Standard `` and `` elements are used (and associated with one another) and convey the standard/expected semantics to assistive technologies.
### ``
The `` component is an abstraction of a basic radio group pattern (using `` and `` for the group labeling).
#### Props
legend
A string for the `` element e.g. legend="Your favorite animal"
Default: 'Choose'
name (required)
A valid name value (mapping to the standard name attribute), e.g. name="favoriteAnimal"
options (required)
A comma-separated list of available options, e.g. options="dog, cat, fish, aardvark"
Note: Both "dog,cat,fish,aardvark" and "dog, cat, fish, aardvark" are acceptable (the spaces are removed)
checked
The string that represents the checked option (if any), e.g. checked="aardvark"
Default: No item is checked
#### Example
```html
```
#### Accessibility information
Standard ``, ``, ``, `` and `` elements are used (and associated with one another) and convey the standard/expected semantics to assistive technologies.
## Utility classes
A set of utility classes for global styling. Each is prefixed with `u-`.
### `u-invert`
With `class="u-invert"` a CSS filter inverts the colors of the element in hand.
### `u-text-center`, `u-text-left`, `u-text-right`
For realigning text.
### `u-h1`, `u-h2`, `u-h3`, `u-h4`, `u-h5`, `u-h6`
For emulating the font sizes of semantic headings without introducing heading elements (mapped to h1—h6 sizes).
### `u-rounded`
Rounds the edges of an element with a `50%` border radius (making square elements circles).
## Working with data
Sometimes you'll want to work with dummy text (like `` and ``). Other times, you'll want to add real content using basic elements like `
` and `
`. But you can also work with data.
### The `data.js` file
This file defines a global data object and is found in the root of the **/js** folder. You can add properties to the data object as you wish. For example, I might add a `people` property defining an array of usernames:
```js
// in js/data.js
export default {
people: [
{
firstName: 'Lara',
lastName: 'Hogan'
},
{
firstName: 'Hulk',
lastName: 'Hogan'
},
{
firstName: 'Paul',
lastName: 'Hogan'
},
{
firstName: 'Heydon',
lastName: 'Pickering'
}
]
}
```
Using the `` component, you can template the data. Note that `this` refers to the property identified using the mandatory `property` attribute (`property="people"` here).
```html
{{% for (let name in this) { %}}
{{% this[name].lastName %}}, {{% this[name].firstName %}}
{{% this[name].firstName === 'Heydon' ? '(me!)' : '' %}}
{{% } %}}
```
There you have it: a set of user 'cards' laid out in a ``.
### The `` component
The `` component wraps a form and lets you change or add data to the global data object. It too takes a `property` attribute (i.e. it can only affect one property at a time, and only works to one level of depth).
```html
Submit
```
When the submit button is pressed, a `FormData` object of values is created based on the form fields' `name` attributes. In this case, the object would be:
```js
{
firstName: /* value from `name="firstName"` */,
lastName: /* value from `name="lastName"` */
}
```
If the `window.data.people` property's value is an object, it will be overridden with the new data. If it is an _array_, the data will be pushed as a new item (as in the `people` example). If the `` contains just one field, the `FormData` object will be flattened into a simple string of that single value. That is:
```js
// This would be avoided...
people: [
{
person: 'Heydon Pickering'
}
]
// ...in preference of this:
people: [
'Heydon Pickering'
]
```
(**Note:** In this scenario, the field's `name` attribute would actually be immaterial because the first and only property of the `FormData` object is taken, whatever it is called.)
Whenever a `` changes the data, a `'stored'` event is fired, alerting any `` elements of the new data so they can rerender accordingly. This event also fires on page load, rendering out the original data.
### Security
Be careful not to allow the use of `` or the creation of `` on domains that expose personal/sensitive data. You may invite XSS.
## Actions
A set of global functions to be used with inline handlers (`onClick` etc). It is recommended these are used primarily on `` elements, since they are accessible. Each action is prefixed with the `actions` namespace, like `onClick="actions.nameOfAction(arg1, arg2)"`.
### `show(id)`
Shows an element by its `id` (removes the `hidden` property).
#### Example
Shows the element with the `id` 'myElem':
```html
SHow the element
```
### `hide(id)`
Hides an element by its `id` (adds the `hidden` property).
#### Example
Hides the element with the `id` 'myElem':
```html
SHow the element
```
### `showHide(id)`
Toggles the visibility of an element by its `id` (toggles the `hidden` property).
#### Example
Toggles the visibility of the element with the `id` 'myElem':
```html
SHow the element
```
### `flowPrev(this)`
Shows the previous element/slide/step within a `` component. **Must be called from inside the `` component, with `this` as the only argument**.
#### Example
```html
Previous
```
### `flowNext(this)`
Shows the next element/slide/step within a `` component. **Must be called from inside the `` component, with `this` as the only argument**.
#### Example
```html
Previous
```
### `flowGoTo(this, index)`
Shows the next element/slide/step within a `` component. **Must be called from inside the `` component, with `this` as the first argument**. The second argument is the index of the element/slide/step (not zero-based; the first item is `1`).
#### Example
Shows the third element/slide/step within the ``.
```html
Previous
```