ba-js-common-header 0.0.1

package/README.md

@@ -0,0 +1,216 @@
+# Bookassist Shared Header
+
+A React-based common Bookassist header component
+
+## Installation
+
+```javascript
+yarn add ba-js-common-header
+```
+
+## Usage
+
+```javascript
+// React
+
+import { Header } from 'ba-js-common-header'
+
+function App(props) {
+    return <Header {...props} />
+}
+```
+
+```javascript
+// website
+
+<div id="header"></div>
+
+// es5
+<script src="https://unpkg.com/ba-js-common-header/dist/ba-js-common-header.umd.js"></script>
+// baJsHeader global now available
+<script>
+  const { renderHeader } = baJsHeader
+  renderHeader(document.querySelector('#header'), {
+    // props
+  })
+</script>
+
+// ES Modules
+<script type="module">
+  import { renderHeader } from 'https://unpkg.com/ba-js-common-header/dist/ba-js-common-header.es.js'
+  renderHeader(document.querySelector('#header'), {
+    // props
+  })
+</script>
+```
+
+## Redux State
+
+The header uses redux to manage shared application state. The redux state shape is as follows:
+
+```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,
+}
+```
+
+## Header Props
+
+| 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)    |
+
+#### fetchUserInfo
+
+This provides the initial userInfo state to the header. It can be one of three things:
+
+1. a userInfo object
+2. a promise resolving to a userInfo object
+3. a function returning a promise that resolves to a userInfo object
+
+```javascript
+// userInfo
+{
+    userId: 0,
+    username: '',
+    hotelId: 0,
+    guideId: 0,
+    hotelGroupId: 0,
+}
+```
+
+#### fetchHotelInfo
+
+This provides the initial hotelInfo state to the header. It can be one of three things:
+
+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
+// hotelInfo
+{
+    hotelId: 0,
+    guideId: 0,
+    name: '',
+    hotelGroupId: 0,
+}
+```
+
+#### handleHotelChange
+
+This is a callback that fires when the hotelInfo state changes. The callback is passed the new hotelInfo state
+
+#### fetchHotels
+
+This is an array of hotels for the hotel selector combo box (format TBD). It can be one of three things:
+
+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
+
+```javascript
+// current Hotel Admin format
+hotels = [
+    ['ADLER HOTEL', '3724_802'],
+    ['Adria Hotel Prague', '1465_802'],
+    ['Agroturismo Can Toni Xumeu', '3033_102'],
+    // ...
+]
+```
+
+Selecting a hotel updates the hotelInfo state
+
+#### languages
+
+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.
+
+#### handleLanguageChange
+
+This is a callback that fires when the user selects a language. The callback is passed the new language code
+
+#### brand
+
+This is the product brand
+
+#### product
+
+This is the product
+
+#### logout
+
+This is a string (logout link) or function that logs a user out
+
+#### handleLogout
+
+When `logout` is a function this is a callback that fires after successful logout. It is passed the return value of the `logout` call
+
+#### fetchMenu
+
+TBD
+
+## Data Structures
+
+#### Menu
+
+The menu items are modelled as a flat array of objects.
+
+```javascript
+var menuItems = [
+    {
+        id, // required
+        parentId, // required for nested menu items
+        label, // required
+        host, // origin for external links
+        path, // link path
+    },
+    // ...
+]
+```
+
+#### TODO
+
+-   feed structure
+-   how breadcrumb works
+-   notifications
+-   icons
+-   bootstrap dependencies
+-   i18n