diff --git a/.gitignore b/.gitignore index 31e006e..1daec2e 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,4 @@ dist/ -docs/generated/ test/ node_modules/ *.d.ts diff --git a/docs/dialogs.md b/docs/dialogs.md deleted file mode 100644 index 3c2d451..0000000 --- a/docs/dialogs.md +++ /dev/null @@ -1,120 +0,0 @@ -# Dialogs - -Menu dialogs refer to any amount of text on a menu. -Some dialogs are static, and just used to display text Things on top of a menu. -Others are dynamic and can advance through formatted lines of interactive text. - -## `addMenuDialog` - -Adds dialog-style text to a menu. -If the text would overflow the menu's size, excess horizontal lines are delayed. -The user can advance through the menu with "A" button presses. - -Parameters: - -* `menuName`: Name of the menu. -* `dialog`: Raw dialog to add to the menu, as strings, arrays of strings, or complex placement commands. -* `onCompletion`: Optional callback for when the text is done. - -### Dialogs - -The actual type for menu dialogs is weirdly flexible: - -```typescript -type IMenuDialogRaw = string | (string | string[] | (string | string[])[] | IMenuWordCommandBase)[]; -``` - -#### String Dialogs - -The simplest dialogs will typically just contain strings: -When provided as a raw string, the dialog is split across whitespace to generate words. -This forces the dialog to not wrap words across lines. - -```typescript -// Creates a new GeneralText menu, deleting any existing one -menuGrapher.createMenu("GeneralText"); - -// Adds the dialog to GeneralText -menuGrapher.addMenuDialog("GeneralText", "Hello world!"); - -// Sets GeneralText as the active, input-receiving menu -menuGrapher.setActiveMenu("GeneralText"); -``` - -#### Array Dialogs - -Dialogs will show as many consecutive lines on "A" press as possible by default. -You can force a "break" in the sections by providing an array of dialog strings. -The dialog will clear any lines on the screen when moving across a break. - -```typescript -menuGrapher.addMenuDialog("GeneralText", ["Hello world!", "Me again!"]); -``` - -### Advanced Commands - -It's allowed to provide advanced "commands" to dialogs along with words in the dialogs. -These commands can insert "floating" text or change position offsets or alignments of the dialog text. - -Alas, these command types aren't well fleshed out in `IMenuGraphr.ts` and not recommended until documentation is solidified. -See [#52](https://github.com/FullScreenShenanigans/MenuGraphr/issues/52). - -## `IMenuSchema` - -These options are available on `IMenuSchema` generally, but only useful once the menu is given a dialog. - -### `deleteOnFinish` - -Whether the menu should be deleted when its dialog finishes. - -```typescript -{ - deleteOnFinish: true, -} -``` - -### `finishAutomatically` - -Whether the dialog should finish when the last word is displayed, -instead of waiting for user input. - -```typescript -{ - finishAutomatically: true, -}, -``` - -### `finishAutomaticSpeed` - -How many game ticks to delay completion by when `finishAutomatically` is true. -Defaults to `0`. - -```typescript -{ - finishAutomaticSpeed: 100, -} -``` - -### `finishLinesAutomatically` - -Whether individual lines of dialog should finish when the last word is displayed, -instead of waiting for user input. - -```typescript -{ - finishLinesAutomatically: true, -}, -``` - -### `finishLinesAutomaticSpeed` - -How many game ticks to delay completion by when `finishLinesAutomatically` is true. -Defaults to `0`. - -```typescript -{ - finishLinesAutomaticSpeed: 100, -} -``` - -See [`lists.md`](./lists.md) for examples of lists intermixed with dialogs. diff --git a/docs/lists.md b/docs/lists.md deleted file mode 100644 index 1e67cc9..0000000 --- a/docs/lists.md +++ /dev/null @@ -1,214 +0,0 @@ -# Lists - -Menus can have scrollable lists of selectable text options in them. -Users can use direction inputs to scroll through the items. - -Lists can be one-dimensional or two-dimensional. -This is determined by the computed height of list options within the menu's height. -If enough options are added to a list to pass the bottom, unless the menu specifies `singleColumnList`, they will overflow to a column to the right. - -## `IListMenuSchema` - -When creating or declaring schemas for list menus, there are some additional properties you can apply to them. -These are all optional. - -### `saveIndex` - -Whether the last selected index should be saved. -When `true`, the parent EightBittr's ItemsHoldr will save the selected index of the menu under the menu's name. -Recreating the menu will read from that stored index if available. - -```typescript -{ - saveIndex: true, -}, -``` - -### `clearedIndicesOnDeletion` - -Names of menus whose whose selected indices that should be cleared when this menu is deleted. -Use this when there are multiple related list menus open at once, and finishing one clears another. - -```typescript -{ - clearedIndicesOnDeletion: [ - "KeyboardKeys", - "NameCollection", - ], -}, -``` - -### `scrollingItems` - -How many scrolling items should be visible within the menu vertically. -List menus will by default show all the items at once, which is bad if there are many options and not enough menu height to display them all. -Specify a `scrollingItems` number to hardcode a maximum to display at once. - -If the user shifts their selected index to below the lowest displayed item or above the highest displayed item, -the menu will "scroll" items vertically. -It does this by shifting their Things vertically and setting `hidden` on items not allowed to be seen. - -```typescript -{ - scrollingItems: 10, -}, -``` - -> There is no equivalent for horizontal items. - -### `scrollingItemsComputed` - -As an alternative to `scrollingItems`, you can have the maximum displayed number of items computed as a function of menu height and expected height per list option. -This will set the `scrollingItems` member of the menu on list creation. - -```typescript -{ - scrollingItemsComputed: true, -}, -``` - -### `singleColumnList` - -Whether the list should always be a single column, rather than auto-flow. - -```typescript -{ - singleColumnList: true, -}, -``` - -## `addMenuList` - -Adds a list of text options to a menu. - -Parameters: - -* `menuName`: Name of the menu. -* `settings`: Settings for the list, particularly its options. - -### `IListMenuOption` - -Individual option within a list. -Only `text` is required. - -#### `callback` - -Callback for when the option is triggered. -Receives just the menu name. - -```typescript -{ - options: [ - { - callback: () => console.log("First!"), - text: "First", - }, - ], -}, -``` - -#### `position` - -Position offsets to shift the option by, allowing top, right, bottom, left. - -```typescript -{ - options: [ - { - position: { - top: 30, - right: -20, - }, - text: "First", - }, - ], -}, -``` - -#### `text` - -Text displayed as the option. -This text will be rendered all in one row, similar to dialogs. - - -### `IListMenuOptions` - -Settings to create a new list menu. -Only - -#### `bottom` - -A bottom option to display underneath displayed options. -If the list is two-dimensional, this will span across all rows. - -```typescript -{ - bottom: { - callback: () => console.log("Cancelled."), - text: "Cancel", - }, -}, -``` - -#### `options` - -Options within the menu, or a function to generate them. -This is a flat list of options regarldess of whether the menu is one- or two-dimensional. - -```typescript -{ - options: [ - { - callback: () => console.log("First!"), - text: "First", - }, - ], -}, -``` - -See `IListMenuOption` above. - -#### `selectedIndex` - -Each list contains a `selectedIndex: [number, number]` of the position of the currently selected index. -This option overrides the starting selected index. -It defaults to `[0, 0]`. - -## Examples - -Showing a simple "Yes/No" menu after a general text dialog that stays alive: - -```typescript -const finalize = (choice) => { - console.log("Choice:", choice); - menuGrapher.deleteMenu("Yes/No"); -}; - -const createOptions = () => { - menuGrapher.createMenu("Yes/No", { - killOnB: ["GeneralText"], - }); - - menuGrapher.addMenuList("Yes/No", { - options: [ - { - text: "YES", - callback: () => finalize(true), - }, - { - text: "NO", - callback: () => finalize(false), - } - ], - }); - - menuGrapher.setActiveMenu("Yes/No"); -}; - -menuGrapher.createMenu("GeneralText", { - finishAutomatically: true, - keepOnBack: true, -}); -menuGrapher.addMenuDialog("GeneralText", "Are you sure?", createOptions); -menuGrapher.setActiveMenu("GeneralText"); -``` diff --git a/docs/schemas.md b/docs/schemas.md deleted file mode 100644 index 764e173..0000000 --- a/docs/schemas.md +++ /dev/null @@ -1,337 +0,0 @@ -# Menu Schemas - -## `IMenuSchema` - -Attributes describing menu appearance and behavior. -These may be specified in the default schemas on a MenuGraphr instance or overriden with `createMenu`. - -All properties are optional. - -> See [`dialogs.md`](./dialogs.md) for properties specific to menu dialogs. - -> See [`lists.md`](./lists.md) for properties specific to menu lists. - -> See [`text.md`](./text.md) for properties around displaying text in dialog and list menus. - -### `backMenu` - -Name of a menu to set as active when this one is deleted. - -```typescript -{ - backMenu: "GeneralText", -}, -``` - -### `callback` - -Callback for when this menu is set as active. -Called with the menu name. - -```typescript -{ - callback: (menuName) => { - console.log("Set", menuName, "as active."); - }, -}, -``` - -### `childrenSchemas` - -Schemas of children to add on creation. -These will be directly passed to `createMenuChild`, which will call `createMenu`, `createMenuWord`, or `createMenuThing` as per the child type. -As with regular menu schemas, these allow all properties as overrides. - -```typescript -{ - childrenSchemas: [ - { - type: "text", - words: ["Hello", "world!"], - }, - { - type: "thing", - thing: "PlayerPortrait", - position: { - horizontal: "right", - }, - }, - { - type: "menu", - name: "PlayerStats", - }, - ], -}, -``` - -> See `IMenuChildSchema`. - -### `container` - -Name of a containing menu to position within. -If not provided, this defaults to the entire game canvas. - -```typescript -{ - container: "GeneralText", -}, -``` - -### `height` - -How tall the menu should be, as Thing height. -This will also set the general Thing height of the menu. - -```typescript -{ - height: 80, -}, -``` - -### `ignoreA` - -Whether user selection events should be ignored. -These "A" events normally advance menu dialogs forward or trigger selected items in lists. - -```typescript -{ - ignoreA: true, -}, -``` - -### `ignoreB` - -Whether user deselection events should be ignored. -These "B" events normally exit out of menus. - -```typescript -{ - ignoreB: true, -}, -``` - -### `ignoreProgressB` - -Whether deselection events should count as selection during dialogs. -Menus with "progress" are in the middle of dialog or list creation. -Pressing B during progress would normally advance the menu forward. - -```typescript -{ - ignoreProgressB: true, -}, -``` - -### `keepOnBack` - -Whether this should be kept alive when deselected. -Useful for switching active state between multiple menus on B. - -```typescript -{ - keepOnBack: true, -}, -``` - -### `killOnB` - -Other menus to kill when this is deselected. -Commonly used with "Yes/No"-style dialogs that appear along with text descriptions in other menus. - -```typescript -{ - killOnB: ["GeneralText", "OtherDecorations"], -}, -``` - -### `onActive` - -Callback for when the menu becomes active. -Receives just the menu name. - -```typescript -{ - onActive: (menuName) => { - console.log("Menu", menuName, "is now active."); - }, -}, -``` - -### `onBPress` - -Callback for when the "B" button is pressed while the menu is active. -Receives just the menu name. - -Does not fire if `ignoreB` is true. -Also does not fire if the menu is mid-progress and `ignoreProgressB` is not true, as that simulates an "A" press. - -```typescript -{ - onBPress: (menuName) => { - console.log("Menu", menuName, "received a B press."); - }, -}, -``` - -### `onDown` - -Callback for when the "down" button is pressed. -Receives just the menu name. - -```typescript -{ - onDown: (menuName) => { - console.log("Menu", menuName, "received a down event."); - }, -}, -``` - -### `onInactive` - -Callback for when the menu becomes inactive. -Receives just the menu name. - -```typescript -{ - onActive: (menuName) => { - console.log("Menu", menuName, "is now active."); - }, -}, -``` - -### `onLeft` - -Callback for when the "left" button is pressed. -Receives just the menu name. - -```typescript -{ - onLeft: (menuName) => { - console.log("Menu", menuName, "received a left event."); - }, -}, -``` - -### `onMenuDelete` - -Callback for when the menu is deleted. -Receives just the menu name. - -This is called _after_ the menu is deleted, but _before_ menu children are deleted. - -```typescript -{ - onMenuDelete: (menuName) => { - console.log("Menu", menuName, "was deleted."); - }, -}, -``` - -### `onRight` - -Callback for when the "right" button is pressed. -Receives just the menu name. - -```typescript -{ - onRight: (menuName) => { - console.log("Menu", menuName, "received a right event."); - }, -}, -``` - -### `onUp` - -Callback for when the "up" button is pressed. -Receives just the menu name. - -```typescript -{ - onUp: (menuName) => { - console.log("Menu", menuName, "received an up event."); - }, -}, -``` - -### `size` - -Sizing description, including `height` and `width`. -This will override the native Thing `height` and `width` on the Menu. - -```typescript -{ - size: { - height: 80, - width: 40, - }, -}, -``` - -```typescript -{ - -}, -``` - -> This allows menus to act as containers at a different size from their visual Things. - -### `width` - -How wide the menu should be, as Thing width. -This will also set the general Thing width of the menu. - -```typescript -{ - width: 40, -}, -``` - -### `position` - -How the menu should be positioned within its container. -Defaults to the menu aligning itself to the top-left corner of its container and no width or height. - -#### `horizontal` - -Modifies how the schema lays itself out horizontally. - -* If `"center"`, aligns to the horizontal midpoint of its container. -* If `"right"`, its right aligns with its container's right. -* If `"stretch"`, stretches to fit its container horizontally. - -```typescript -position: { - horizontal: "right", -}, -``` - -#### `offset` - -Horizontal and vertical offsets to shift the menu by. -These are allowed to be negative numbers, are calculated relative to the menu's container, and each reduce the menu's size horizontally or vertically. - -```typescript -position: { - offset: { - top: -1, - right: 2, - bottom: 3, - left: -4, - }, -}, -``` - -#### `vertical` - -Modifies how the schema lays itself out vertically. - -* If `"center"`, aligns to the vertical midpoint of its container. -* If `"bottom"`, its bottom aligns with its container's bottom. -* If `"stretch"`, stretches to fit its container vertically. - -```typescript -position: { - vertical: "bottom", -}, -``` - diff --git a/docs/text.md b/docs/text.md deleted file mode 100644 index a17ab7b..0000000 --- a/docs/text.md +++ /dev/null @@ -1,74 +0,0 @@ -# Text - -Text within menu dialogs and lists can be displayed with granular controls over paddings and spacing. - -## `IMenuSchema` - -These options will be used when the menu has a dialog or list added. - -### `textPaddingRight` - -How much padding there is between the right of the text and the right side of the box. -Text in dialogs will return to the next line instead of crossing the menu's `right` minus `textPaddingRight`. -Defaults to `0` (none) if not provided. -Allowed to be negative. - -```typescript -{ - textPaddingRight: 8, -}, -``` - -### `textPaddingX` - -How much horizontal padding should be between characters. -Defaults to the `"Text"` Thing prototype's `paddingX` if it exists, or `0` otherwise. -Characters placed next to each other in dialogs and lists will be placed this number of game pixels to the right each subsequent character. - -```typescript -{ - textPaddingX: 4, -}, -``` - -### `textPaddingY` - -How much vertical padding should be between lines of text. -Defaults to the `"Text"` Thing prototype's `paddingY` if it exists, or `0` otherwise. -Lines of text in dialogs and lists will start this number of game pixels lower each line. - -```typescript -{ - textPaddingY: 12, -}, -``` - -### `textSpeed` - -How long to delay between placing characters and words. -If `0` or not provided, characters and words will be placed immediately. - -Otherwise, each character will wait a `textSpeed` delay before displaying. -Words will wait a `textSpeed` delay before appearing after each other as well, which gives the illusion of spaces between words also adhering to the delay. - -### `textXOffset` - -Horizontal offset for the text placement area. -All text will be offset horizontally by this amount. - -```typescript -{ - textXOffset: 2, -}, -``` - -### `textYOffset` - -Vertical offset for the text placement area. -All text will be offset vertically by this amount. - -```typescript -{ - textYOffset: -2, -}, -``` diff --git a/package-lock.json b/package-lock.json index 46acf5b..cf242a2 100644 --- a/package-lock.json +++ b/package-lock.json @@ -5491,9 +5491,9 @@ } }, "shenanigans-manager": { - "version": "0.2.39", - "resolved": "https://registry.npmjs.org/shenanigans-manager/-/shenanigans-manager-0.2.39.tgz", - "integrity": "sha512-Lr/JMUWQF35tkLryRhIcxGg05meh7wdX9bipqfd7YfxRw0t02dEG4sohViX15NhZd58rTKzUGSdiL7CrAXMIwA==", + "version": "0.2.40", + "resolved": "https://registry.npmjs.org/shenanigans-manager/-/shenanigans-manager-0.2.40.tgz", + "integrity": "sha512-sVP3iUrhE2/ro3KD+/MtvEyEcUmL6kfMFB6Exr9Ks4GyLV3sSKO7PEEMuO9zwZa3UQnNwOOrZtYi8G820wD8qw==", "dev": true, "requires": { "chalk": "^2.4.2", diff --git a/package.json b/package.json index 19b3e1d..5f2ddd7 100644 --- a/package.json +++ b/package.json @@ -30,7 +30,7 @@ "npm-check-updates": "^3.1.7", "requirejs": "^2.3.6", "run-for-every-file": "^1.1.0", - "shenanigans-manager": "^0.2.39", + "shenanigans-manager": "^0.2.36", "sinon": "^7.3.1", "sinon-chai": "^3.3.0", "tslint": "5.15.0", @@ -77,8 +77,8 @@ "test:setup:dir": "mkdirp test", "test:setup:html": "shenanigans-manager generate-test-html", "test:setup:tsc": "tsc -p test", - "verify": "npm run src && npm run test && npm run dist && npm run docs", - "verify:coverage": "npm run src && npm run test:setup && npm run test:coverage && npm run dist && npm run docs", + "verify": "npm run src && npm run test && npm run dist", + "verify:coverage": "npm run src && npm run test:setup && npm run test:coverage && npm run dist", "watch": "concurrently \"tsc -p . -w\" --raw \"chokidar src/**/*.test.t* --command \"\"npm run test:setup:html\"\" --silent\" --raw" }, "shenanigans": { @@ -86,4 +86,4 @@ }, "types": "./src/index.d.ts", "version": "0.7.11" -} +} \ No newline at end of file diff --git a/settings.json b/settings.json new file mode 100644 index 0000000..5f1a263 --- /dev/null +++ b/settings.json @@ -0,0 +1,13 @@ +{ + "editor.tabSize": 4, + "editor.trimAutoWhitespace": true, + "files.exclude": { + "**/*.d.ts": true, + "**/*.js.map": true, + "**/*.js": { "when": "$(basename).ts" }, + "**/*?.js": { "when": "$(basename).tsx" } + }, + "tslint.alwaysShowRuleFailuresAsWarnings": true, + "tslint.autoFixOnSave": true, + "typescript.tsdk": "node_modules/typescript/lib" +}