Merge pull request #30 from Roll20/csc-alice

CSC: Update component pages

config/production/hugo.toml

@@ -1,2 +1,2 @@
 # Overrides for production environment
-baseurl = "https://roll20.github.io/beacon-docs/"
+baseURL  = "https://roll20.github.io/beacon-docs/"

content/docs/components/InitRelay.md

@@ -50,12 +50,8 @@ These components are crucial for handling actions, computations, macros, and rol
   href="/docs/components/handlers/"
   target="_blank"
 >}}
-
 {{< /card-grid >}}
 
-
-
-
 {{< card-grid >}}
 {{< link-card
   title="Computed"
@@ -69,21 +65,20 @@ These components are crucial for handling actions, computations, macros, and rol
   href="/docs/components/handling-legacy-macro-attributes/"
   target="_blank"
 >}}
-
 {{< /card-grid >}}
 
-
+{{< card-grid >}}
 {{< link-card
   title="Rolls"
   description="The Rolls component allows for advanced dice-rolling mechanics within the Roll20 Tabletop. It supports both simple and complex rolls, providing flexibility in how roll results are displayed and computed."
   href="/docs/components/rolls/"
   target="_blank"
 >}}
 
-
 {{< link-card
   title="Dispatch"
   description="The dispatch object provides methods for sending commands from the character sheet back to the host. Except when specified every method returns a promise."
   href="/docs/components/dispatch/"
   target="_blank"
->}}
+>}}
+{{< /card-grid >}}

content/docs/components/actions.md

@@ -16,28 +16,35 @@ seo:
   noindex: false # false (default) or true
 ---
 
-Actions are a collection of methods that can be executed from the Roll20 Tabletop. These actions are used for any rolls that may need to be triggered outside of the sheet itself, such as from a macro or a chat button. Generally, most or all of a sheet’s rolls should be defined as actions.
+```typescript
+initRelay({
+  //...other methods
+    actions: {},
+}): Promise<Dispatch>
+```
+
+Actions are a collection of methods that can be executed from the Roll20 Tabletop or Roll20 Characters. These actions are used for any rolls that may need to be triggered outside of the sheet itself, such as from a macro or a chat button. Generally, most or all of a sheet’s rolls should be defined as actions.
 
-```javascript
+```typescript
 actions: {
- [name: string]: {
+  [name: string]: {
     method: (props: {
- dispatch: Dispatch,
- character: Character,
- messageId?: string,
- rolls?: RollResults 
- }, ...args: string[]): void | Promise<void>
- }
+      dispatch: Dispatch,
+      character: Character,
+      messageId?: string,
+      rolls?: RollResults 
+    }, ...args: string[]): void | Promise<void>
+  }
 }
 ```
 
 Actions are passed into the  `initRelay` function in an object, where the keys are the unique names of the actions, and the values are objects containing a `method` property (additional metadata fields may be added to this object in the future).
 
-The `method` receives a `props` object containing the following properties:
+The action's `method` receives a `props` object from the host containing the following properties:
 
 - `dispatch`: A `Dispatch` object.
 - `character`: The data of the character performing the action. Currently, the action will not receive the character’s bio or GM notes, regardless of whether the player has access to those fields.
 - `messageId` (optional): A unique ID for an existing chat message. It's included in actions triggered from chat buttons to provide context for the original roll.
 - `rolls` (optional): Included when action is triggered from a chat button. Contains the roll results of the original roll.
 
-> These functions can also receive an unlimited number of additional arguments. This is because these actions can be triggered by plain text via a macro. However, all additional arguments must be strings. Additionally, these functions can be synchronous or asynchronous and do not return a value.
+These methods can also receive an unlimited number of additional arguments. This is because these actions can be triggered by plain text via a macro. However, all additional arguments must be strings. Additionally, these methods can be synchronous or asynchronous and do not return a value.

content/docs/components/computed.md

@@ -16,28 +16,31 @@ seo:
   noindex: false # false (default) or true
 ---
 
-Sheet authors define computed properties that are accessed by the host. These computed properties can be used as attributes in macros and are available to assign as values to token bars - if the `tokenBarValue` property is set to true.
-
-```javascript
-computed: {
- [name: string]: {
- tokenBarValue?: boolean,
- description?: string,
-    get: (
-      props: {
- character: Character
- },
-      ...args: string[]
- ) => ComputedResult,
- set?: (
-      props: {
- character: Character,
- dispatch: Dispatch
- },
-      ...args: string[]
- ) => void | Promise<void>
- }
-}
+Sheet authors define computed properties that are accessed by the Roll20 Tabletop or Roll20 Characters. These computed properties can be used as attributes in macros and are available to assign as values to token bars - if the `tokenBarValue` property is set to true.
+
+```typescript
+initRelay({
+  //...other methods
+  computed: {
+    [name: string]: {
+      tokenBarValue?: boolean
+      description?: string
+      get: (
+        props: {
+          character: Character
+        },
+        ...args: string[]
+      ) => string | number | JSONValue
+      set?: (
+        props: {
+          character: Character
+          dispatch: Dispatch
+        },
+        ...args: string[]
+      ) => void | Promise<void>
+    }
+  },
+}): Promise<Dispatch>
 ```
 
 Computed properties are passed into the `initRelay` function in an object where the keys are the names of the properties, and the value should be an object containing the following:

content/docs/components/handlers.md

@@ -15,118 +15,126 @@ seo:
   canonical: "" # custom canonical URL (optional)
   noindex: false # false (default) or true
 ---
+Handler methods allow the sheet to respond to data passed from the Roll20 Tabletop or Roll20 Characters (both refered to as host throughout this page) to the sheet. It is the main agrument that must be passed into `initRelay` or the sheet will never fully load.
+
+```typescript
+initRelay({
+    handlers: {
+        onInit,
+        onChange,
+        onSettingsChange,
+        onSharedSettingsChange,
+        onTranslationsRequest,
+        onDragOver, // optional
+        onDropOver, // optional
+    }
+    //...other methods
+}): Promise<Dispatch>
+```
 
-
-Handler functions allow the sheet to respond to messages from the host. The `handlers` argument requires the following methods:
-
-## `onInit`
-
-The `onInit` function provides the initial set of data to the sheet.
-
-```javascript
-onInit(e: {
- character: Character,
- settings: {
- colorTheme: string,
- language: string,
- gm: boolean,
- owned: boolean,
- settingsSheet: boolean,
- headless: boolean,
- sandbox: boolean,
- campaignId: number,
- environment: string,
- currentUserId: string,
- singleSheet: boolean
- },
- sharedSettings: {},
- compendiumDropData: {
- pageName: string,
- categoryName: string,
- expansion: number
- }
+## onInit
+
+The `onInit` method receives the initial data from the host. 
+
+This will be the first time we have access to character data, sheet settings, as well as compendium data if this character is made as a result of a compendium drag and drop on the host.
+
+```typescript
+onInit(event: {
+  character: Character, // Initial Data of the primary character for this sheet.
+  settings: { // Campaign and character specific settings
+    colorTheme: string, // 'dark' or 'light'
+    language: string, // two-letter language code, i.e. 'en'
+    gm: boolean, // whether or not the current player has gm permissions
+    owned: boolean, // whether or not the current player controls the primary character
+    settingsSheet: boolean, // whether or not this sheet is the settings sheet
+    headless: boolean, // whether or not it should be displayed, set by the host
+    sandbox: boolean,
+    campaignId: number, // The id of the current campaign
+    environment: string, // VTT, CHARACTERS, DISCORD
+    currentUserId: string, // user id of user opening the sheet
+    singleSheet: boolean
+  },
+  sharedSettings: {}, // Data shared between all characters in this campaign
+  compendiumDropData: { //  Populated when the character sheet is created from a compendium entry such as a creature or NPC.
+    pageName: string,
+    categoryName: string,
+    expansion: number,
+  },
 }, dispatch: Dispatch): void;
 ```
 
-The event object contains the following:
-
-- `character`: The primary character for this sheet.
-- `settings`: Campaign and character-specific settings.
-- `sharedSettings`: Data shared between all characters in this campaign.
-- `compendiumDropData`: Populated when the character sheet is created from a compendium entry such as a creature or NPC.
-
 {{< callout context="note" >}}
  This function may be called multiple times during development in the sheet sandbox as part of hot reloads.
 {{< /callout >}}
 
 
-## `onChange`
+## onChange
 
 `onChange` is called whenever a character’s data is changed on the host’s end. The event object contains a partial character with only the character’s ID and the changed data. This could be the character’s bio, GM notes, or attributes (only the changed attributes).
 
-```javascript
+```typescript
 onChange(e: {
- character: Partial<Character>
+  character: Partial<Character>
 }, dispatch: Dispatch): void;
 ```
 
-## `onSettingsChange`
+## onSettingsChange
 
-`onSettingsChange` is called when either the Roll20 Tabletop's color theme is changed, or when the current player’s ownership of the primary character changes.
+`onSettingsChange` is called when either the host’s color theme is changed, or when the current player’s ownership of the primary character changes.
 
-```javascript
+```typescript
 onSettingsChange(e: {
  colorTheme: string,
  owned: boolean
 }, dispatch: Dispatch): void;
 ```
 
-## `onSharedSettingsChange`
+## onSharedSettingsChange
 
-`onSharedSettingsChange` is called when someone changes a shared setting in the Roll20 Tabletop.
+`onSharedSettingsChange` is called when someone changes a shared setting in the host.
 
-```javascript
+```typescript
 onSharedSettingsChange({ settings: { [key: string]: any } }): void;
 ```
 
-## `onTranslationsRequest`
+## onTranslationsRequest
 
 `onTranslationsRequest` is called before the relay is fully initialized and returns the translation JSON data corresponding to the two-letter language argument.
 
-```javascript
+```typescript
 onTranslationsRequest(language: string): { [key: string]: string };
 ```
 
-## `onDragOver` (optional)
+## onDragOver (optional)
 
 `onDragOver` is called when a compendium item from the compendium tab is dragged over the iframe window containing the character sheet.
 
 Coordinates of the drag are provided via top and left values, and basic compendium data is passed so that a subsequent compendium request can be made via the provided dispatch. If the item is moved outside of the iframe, `dragData` and `coordinates` are null.
 
-```javascript
+```typescript
 onDragOver(e: {
- coordinates: { top: number, left: number },
- dragData: { 
- pageName: string,
- categoryName: string,
- expansionId: number
- } | null
-}, dispatch: Dispatch): void
+  coordinates: { top: number, left: number },
+  dragData: { 
+    pageName: string
+    categoryName: string
+    expansionId: number
+  } | null,
+}, dispatch: Dispatch) => void
 ```
 
-## `onDropOver` (optional)
+## onDropOver (optional)
 
 `onDropOver` is called when a compendium item from the compendium tab is dropped over the iframe window containing the character sheet.
 
 Coordinates of the drop are provided via top and left values, and basic compendium data is passed so that a subsequent compendium request can be made via the provided dispatch.
 
-```javascript
+```typescript
 onDropOver(e: {
- coordinates: { top: number, left: number },
- dropData: { 
- pageName: string,
- categoryName: string,
- expansionId: number
- }
-}, dispatch: Dispatch): void
+  coordinates: { top: number, left: number },
+  dropData: { 
+    pageName: string
+    categoryName: string
+    expansionId: number
+  }
+}, dispatch: Dispatch) => void
 ```