UserWrappr
Creates configurable HTML displays over flexible-sized contents.
UserWrappr adds two features for wrapping HTML contents:
- Sizing of the content area within the available window space
- Delayed creation of content menus from readable schemas
Usage
const userWrapper = new UserWrappr({
createContents: (size: AbsoluteSizeSchema) => {
return YourContentCreationLogic(size).canvas;
},
});
userWrapper.createDisplay(document.querySelector("#YourElementContainer"));
Details
UserWrappr prioritizes creating the contents as soon as possible.
When you call createDisplay
, the following happen in order:
- View libraries (i.e. Preact) start to load.
- A visual approximation of your menus is placed at the bottom of the area.
- Contents are created in the remaining usable area.
- Once view libraries are loaded, real menus created using them to replace the fake menus.
Menus
It's assumed that your menus will exist below your content. Clicking a menu title with a mouse will open the menu the content.
Each menu's schema must contain a title: string
and options: OptionSchema[]
.
Options will be created in top-to-bottom order within their parent menu.
The allowed option types, as indicated by the type
member of the option schemas, are:
-
"action"
: Simple triggerable action with anaction: () => void
callback. -
"boolean"
: Stores an on/off value. -
"multi-select"
: Stores multiple options within preset values. Needs:-
options: string[]
: Given preset values. -
selections: number
: How many of the preset options must be chosen at once.
-
-
"number"
: Stores a numeric value. May specifymax
and/ormin
values. -
"select"
: Stores one of some presetoptions: string[]
. -
"string"
: Stores a string value.
All schema types except "action"
store their TValue
type and must also provide:
-
getInitialValue(): TValue
: returns an initial state for the value. -
saveValue(newValue: TValue, oldValue: TValue): void
: saves a new state for the value.
See OptionSchemas.ts
for the full definitions.
Styles
UserWrappr will provide some default styles to its elements to position them.
You can override them by passing in a styles
object keying preset identifiers to their CSS styles.
Although they're not used internally, you can also customize which class names are added to elements by passing a classNames
object mapping preset identifiers to their class names.
Both styles
and classNames
will only override with provided values.
See ClassNames.ts
for default class names and Styles.ts
for preset identifiers and their default values.
API
Optional Parameters
-
classNames: ClassNames
: Class names to use for display elements. -
createElement: (tagName: string, properties: ElementProperties)
: Creates a new HTML element. -
defaultSize: RelativeSizeSchema
: initial size to create contents at (by default, 100% x 100%). -
getAvailableContainerHeight
: Gets how much height is available to hold contents (by default,window.innerHeight
). -
menuInitializer: string
: RequireJS path to the menu initialization script. -
menus: MenuSchema[]
: Menus to create inside the menus area. -
styles: Styles
: Styles to use for display elements. -
requirejs
: RequireJS (AMD) API to load scripts.
See IUserWrappr.ts
for specifications on the parameters.
Examples
Giving each menu title a .my-menu-title
class and color: red
CSS style:
const userWrapper = new UserWrappr({
classNames: {
menuTitle: "my-menu-title",
},
createContents: () => {
/* ... */
},
styles: {
menuTitle: {
color: "red",
},
},
});
Creating a menu with mute and volume inputs for a EightBittr's AudioPlayr:
const game = new EightBittr(/* ... */);
const userWrapper = new UserWrappr({
createContents: (size: AbsoluteSizeSchema) => {
game.reset(size);
return game.canvas;
},
menus: [
{
options: [
{
getInitialValue: (): boolean => game.audioPlayer.getMuted(),
saveValue: (value: boolean): void => {
game.audioPlayer.setMuted(value);
},
title: "Mute",
type: OptionType.Boolean,
},
{
getInitialValue: () = > Math.round(game.audioPlayer.getVolume() * 100),
maximum: 100,
minimum: 0,
saveValue: (value: number): void => {
game.audioPlayer.setVolume(value / 100);
},
title: "Volume",
type: OptionType.Number,
},
],
title: "Sound",
},
],
});
Development
This repository is a portion of the EightBittr monorepo.
See its docs/Development.md for details on how to get started.
Running Tests
yarn run test
Tests are written in Mocha and Chai.
Their files are written using alongside source files under src/
and named *.test.ts?
.
Whenever you add, remove, or rename a *.test.t*
file under src/
, watch
will re-run yarn run test:setup
to regenerate the list of static test files in test/index.html
.
You can open that file in a browser to debug through the tests, or run yarn test:run
to run them in headless Chrome.