ba-js-common-header 0.0.27 → 0.0.28

package/README.md

@@ -1,6 +1,6 @@
-# Bookassist Shared Header
+# Bookassist Common Header
 
-A React-based common Bookassist header component
+A React-based shared header component
 
 ## Installation
 
@@ -44,173 +44,220 @@ function App(props) {
 </script>
 ```
 
-## Redux State
+## Header Props
+
+| Prop                   | Type  | Description                        | Required |
+| :--------------------- | :---- | :--------------------------------- | :------- |
+| `config`               | `url` | header configuration feed endpoint | Yes      |
+| `userInfo`             | `obj` | userInfo object                    | Yes      |
+| `userLanguage`         | `str` | default user language              | No       |
+| `handleLanguageChange` | `fn`  | language selector callback         | No       |
+| `handleHotelChange`    | `fn`  | hotel selector callback            | No       |
+| `i18nFeed`             | `url` | Jed i18n endpoint                  | No       |
+
+#### config (required)
+
+The header configuration feed endpoint. See below for structure
+
+#### userInfo (required)
 
-The header uses redux to manage shared application state. The redux state shape is as follows:
+The user state
 
 ```javascript
 {
-    hotelInfo: {
-        name: '',
-        hotelId: 0,
-        guideId: 0,
-        hotelGroupId: 0,
-    },
-    userInfo: {
-        username: '',
-        userid: 0,
-        hotelId: 0,
-        guideId: 0,
-        hotelGroupId: 0,
-    },
-    userLanguage: 'en',
-    menuItems: [
-      {
-        id: 1453141030,
-        label: 'Hotel Info',
-        path: '/hotel_admin/hotelinfo.jsp',
-      },
-      {
-        id: 555613737,
-        parentId: 1453141030,
-        label: 'Create Vouchers',
-        path: '/hotel_admin/new_voucher_package.jsp',
-      },
-    ],
-    selectedMenuItem: 555613737,
-    notifications,
+    username, // string (required)
+    hotelId, // integer (optional)
+    guideId, // integer (optional)
 }
 ```
 
-## Header Props
+The username is used by the header for display purposes. The hotel and guide ids are to provide for an initially selected hotel
 
-| Prop                   | Type     | Description                                                      |
-| :--------------------- | :------- | :--------------------------------------------------------------- |
-| `fetchUserInfo`        | `obj/fn` | userInfo object (or function that resolves to same)              |
-| `fetchHotelInfo`       | `obj/fn` | hotelInfo object (or function that resolves to same)             |
-| `fetchHotels`          | `arr/fn` | array of hotels for selector (or function that resolves to same) |
-| `handleHotelChange`    | `fn`     | hotel selector callback                                          |
-| `languages`            | `arr`    | array of language codes                                          |
-| `handleLanguageChange` | `fn`     | language selector callback                                       |
-| `brand`                | `str`    | brand name                                                       |
-| `product`              | `str`    | product name                                                     |
-| `logout`               | `str/fn` | href or logout function                                          |
-| `handleLogout`         | `fn`     | logout callback                                                  |
-| `fetchMenu`            | `obj/fn` | menu configuration object (or function that resolves to same)    |
+#### userLanguage (optional)
 
-#### fetchUserInfo
+The initially selected language, provided as an ISO language code (defaults to 'en')
 
-This provides the initial userInfo state to the header. It can be one of three things:
+#### handleLanguageChange (optional)
 
-1. a userInfo object
-2. a promise resolving to a userInfo object
-3. a function returning a promise that resolves to a userInfo object
+Callback fired on selection of a language. The callback is passed the new language code
 
 ```javascript
-// userInfo
-{
-    userId: 0,
-    username: '',
-    hotelId: 0,
-    guideId: 0,
-    hotelGroupId: 0,
+const cb = code => {
+    console.log(`The new language code is ${code}`)
 }
 ```
 
-#### fetchHotelInfo
+#### handleHotelChange (optional)
 
-This provides the initial hotelInfo state to the header. It can be one of three things:
+Callback fired on selection of a hotel. The callback is passed an object containing name, hotel id and guide id
 
-1. a hotelInfo object
-2. a promise resolving to a hotelInfo object
-3. a function returning a promise that resolves to a hotelInfo object
+```javascript
+const cb = ({ name, hotelId, guideId }) => {
+    console.log({ name, hotelId, guideId })
+}
+```
+
+#### i18nFeed (optional)
+
+Endpoint for Jed-based i18n feed. The url may contain a '{0}' placeholder for the current language code
+
+```javascript
+const i18nFeed =
+    'https://www.bookassist.com/rest/api/v1/i18n/jed/bookassist.i18n.HotelAdminRB/{0}'
+```
+
+## Feed Structures
+
+### Config Feed (required)
+
+The config feed is an object with 2 required properties:
+
+```javascript
+const config = {
+    titleBar, // required object
+    menuBar, // required array
+}
+```
+
+#### titleBar (required)
+
+The `titleBar` property provides configuration details for the 6 available widgets in the upper half of the header (a given widget will be rendered if configuration for it exists). The property value is an object with 6 possible properties:
 
 ```javascript
-// hotelInfo
 {
-    hotelId: 0,
-    guideId: 0,
-    name: '',
-    hotelGroupId: 0,
+    help, // optional object
+    languageSelector, // optional object
+    notifications, // optional object
+    product, // required object
+    propertySelector, // optional object
+    user, // required object
 }
 ```
 
-#### handleHotelChange
+##### help (optional)
 
-This is a callback that fires when the hotelInfo state changes. The callback is passed the new hotelInfo state
+The `help` property provides link information for the help widget. The property value is an object with 2 required properties:
 
-#### fetchHotels
+```javascript
+{
+  label: 'Help Center', // required string
+  href: 'https://go.bookassist.org/en/knowledge/booking-engine', // required string
+}
+```
 
-This is an array of hotels for the hotel selector combo box (format TBD). It can be one of three things:
+##### languageSelector (optional)
 
-1. an array of hotel objects
-2. a promise resolving to an array of hotel objects
-3. a function returning a promise that resolves to an array of hotel objects
+The `languageSelector` property provides a language widget label and an array of available languages. The property value is an object with 2 required properties:
 
 ```javascript
-// current Hotel Admin format
-hotels = [
-    ['ADLER HOTEL', '3724_802'],
-    ['Adria Hotel Prague', '1465_802'],
-    ['Agroturismo Can Toni Xumeu', '3033_102'],
+
+{
+  label: 'Language', // required string
+  children: [ // required array
+    {
+      code: 'en', // required string
+    },
+    {
+      code: 'es', // required string
+      label: 'Español', // optional string
+    },
+    {
+      code: 'fr', // required string
+    },
     // ...
-]
+  ],
+}
 ```
 
-Selecting a hotel updates the hotelInfo state
-
-#### languages
+The `children` array is a list of `language` objects. A `language` object consists of a required language code property and an optional label property that can be used to override the name provided by [Intl.DisplayNames](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DisplayNames)
 
-This is an array of ISO language codes. The header handles language naming needs using the [Intl.DisplayNames](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DisplayNames) object.
+##### notifications (optional)
 
-#### handleLanguageChange
+```javascript
+{
+}
+```
 
-This is a callback that fires when the user selects a language. The callback is passed the new language code
+##### product (required)
 
-#### brand
+The `product` property denotes the current product. The property value is an object with 2 required properties:
 
-This is the product brand
+```javascript
+{
+  name: 'Booking Engine', // required string
+  href: '/hotel_admin/spl.jsp', // required string
+}
+```
 
-#### product
+##### propertySelector (optional)
 
-This is the product
+The `propertySelector` property is used to provide the list of selectable hotels. The property value is an object with 2 required properties:
 
-#### logout
+```javascript
+{
+    type, // required string (one of 'data' or 'fetch')
+    items, // required array of hotels or endpoint providing said array
+}
+```
 
-This is a string (logout link) or function that logs a user out
+The `items` property value is an array of hotels or an endpoint returning such an array. Individual hotels are specified as 2-item arrays containing the hotel name and a string consisting of the hotel and guide ids separated by an underscore.
 
-#### handleLogout
+```javascript
+const hotels = [
+    ['ADLER HOTEL', '3724_802'],
+    ['Adria Hotel Prague', '1465_802'],
+    ['Agroturismo Can Toni Xumeu', '3033_102'],
+    // ...
+]
+```
 
-When `logout` is a function this is a callback that fires after successful logout. It is passed the return value of the `logout` call
+##### user (required)
 
-#### fetchMenu
+The `user` property denotes a set of user-related links. The property value is an object with 2 required properties:
 
-TBD
+```javascript
+{
+  label: 'Profile', // required string
+  children: [ // required array
+    {
+      label: 'Maintain Users', // required string
+      href: '/hotel_admin/maintain_users.jsp', // required string
+    },
+    {
+      label: 'Change Password', // required string
+      href: '/hotel_admin/login.jsp?resetpass', // required string
+    },
+    {
+      label: 'Log Out', // required string
+      href: '/hotel_admin/logout.jsp', // required string
+    },
+  ],
+}
+```
 
-## Data Structures
+The `children` property is a list of link objects, each with 2 required properties (`label` and `href`)
 
-#### Menu
+#### menuBar (requred)
 
-The menu items are modelled as a flat array of objects.
+The `menuBar` property provides configuration details for the lower half of the header. The property value is a flat array of menu item objects:
 
 ```javascript
-var menuItems = [
+const menuBar = [
     {
-        id, // required
+        id, // required string
         parentId, // required for nested menu items
-        label, // required
-        host, // origin for external links
-        path, // link path
+        label, // required string
+        href, // optional link (string)
+        group, // optional header for menu item grouping (string)
+        premium: { // optional object outlining premium status
+            value: true, // required boolean
+            locked: true, // required boolean
+        },
     },
     // ...
 ]
 ```
 
-#### TODO
+## i18n
 
--   feed structure
--   how breadcrumb works
--   notifications
--   icons
--   bootstrap dependencies
--   i18n
+i18n can be optionally provided via the `i18nFeed` prop.  The header uses [Jed](https://github.com/messageformat/Jed). If an i18n feed is specified all header labels will be treated as i18n keys and run through Jed for translation.