@operato/shell 2.0.0-alpha.0 → 2.0.0-alpha.102

package/src/actions/route.ts

@@ -4,12 +4,17 @@ import { HOMEPAGE, UPDATE_PAGE } from '../actions/const'
 import { store } from '../store'
 
 /**
+ * Navigate to a page using one of two methods:
+ * 1. Using a page link: <a href='page'>goto page</a> (equivalent to route(page))
+ * 2. Using the navigate('page') function.
+ *
  * 페이지를 이동하는 방법으로는 다음 두가지가 있다.
  * 1. page link를 사용하는 방법 <a href='page'>goto page</a>
  *    이 방법은 route(page)와 동일하다.
  * 2. navigate('page')를 사용하는 방법
  *
- * @param string page
+ * @param location - The path of the page to navigate to.
+ * @param replace - Optional. If true, replaces the current page in the browser's history.
  */
 export const navigate = (location: string, replace?: boolean) => {
   if (replace) history.replaceState(history.state, '', location)
@@ -18,6 +23,12 @@ export const navigate = (location: string, replace?: boolean) => {
   window.dispatchEvent(new Event('popstate'))
 }
 
+/**
+ * Navigate to a page with optional query parameters, and dispatch a Redux action to load the page.
+ *
+ * @param pathInfo - Object containing pathname, search, and optional params.
+ * @param dispatch - Redux dispatch function.
+ */
 export const navigateWithSilence =
   ({ pathname: path, search, params }: { pathname: string; search?: string; params?: { [key: string]: any } }) =>
   (dispatch: any) => {
@@ -42,7 +53,13 @@ export const navigateWithSilence =
     dispatch(loadPage(page, id, params))
   }
 
-const _preLoadPage = (page: any) => {
+/**
+ * Preload a page by performing any necessary preprocessing before loading.
+ *
+ * @param page - The page to preload.
+ * @returns - The new page path or routing result after preprocessing.
+ */
+const _preLoadPage = async (page: any) => {
   /*
    * _preLoadPage 에서는 page를 load하기 전처리를 수행한다.
    * 예를 들면, page dynamic import 또는 page re-routing
@@ -53,8 +70,8 @@ const _preLoadPage = (page: any) => {
   var modules = state.app.modules
   if (modules) {
     for (let i = modules.length - 1; i >= 0; i--) {
-      let factoryModule = modules[i]
-      let _page = factoryModule.route && factoryModule.route(page)
+      let module = modules[i]
+      let _page = module.route && (await module.route(page, module))
       if (_page) {
         return _page
       }
@@ -62,8 +79,15 @@ const _preLoadPage = (page: any) => {
   }
 }
 
-export const loadPage = (page: string, id: string, params: { [key: string]: any }) => (dispatch: any) => {
-  var newPage = _preLoadPage(page)
+/**
+ * Load a page by dispatching a Redux action, and handle page navigation if necessary.
+ *
+ * @param page - The page to load.
+ * @param id - The associated resource ID.
+ * @param params - Additional parameters to pass to the page.
+ */
+export const loadPage = (page: string, id: string, params: { [key: string]: any }) => async (dispatch: any) => {
+  var newPage = await _preLoadPage(page)
 
   if (page !== newPage && newPage.indexOf('/') == 0) {
     dispatch(
@@ -83,6 +107,11 @@ export const loadPage = (page: string, id: string, params: { [key: string]: any
   })
 }
 
+/**
+ * Route to a given URL by creating a link element and triggering a click event.
+ *
+ * @param url - The URL to route to.
+ */
 export const route = (url: string) => {
   const link = document.createElement('a')
 

package/src/app/app-style.ts

@@ -63,16 +63,24 @@ export const AppStyle = css`
     z-index: 1000;
   }
 
-  /* Wide layout */
-  @media (min-width: 460px) {
-  }
-
   @media print {
     :host {
       width: 100%;
       height: 100%;
       min-height: 100vh;
       min-height: 100dvh;
+
+      max-width: unset;
+      width: unset;
+      height: unset;
+      height: unset;
+    }
+
+    main {
+      /* important for printing!!! */
+      display: block;
+      flex: unset;
+      overflow: visible;
     }
 
     ox-page-header-bar {

package/src/app/app.ts

@@ -23,7 +23,21 @@ export class ThingsApp extends connect(store)(LitElement) {
 
   static moduleInitialized: MODULES_STATE = MODULES_STATE.NOT_INITIALIZED
   static modules: Array<any> = []
-  static pages: { [path: string]: string } = {}
+
+  /* 
+    모든 모듈의 routes 리스트가 수집될 때까지, routeToPage(..) 를 hold 시키기 위해서 ThingsApp.pages를 Promise로 정의한다. 
+  */
+  static pagesResolver: (
+    value:
+      | {
+          [path: string]: string
+        }
+      | PromiseLike<{
+          [path: string]: string
+        }>
+  ) => void
+  static pages: Promise<{ [path: string]: string }>
+
   static callbacks: Array<any> = []
   static contextPath?: string
 
@@ -86,13 +100,13 @@ export class ThingsApp extends connect(store)(LitElement) {
     ).then(module => {
       var modules: {
         name: string
-        bootstrap: any
+        bootstrap: (m?: any /* self */) => void
       }[] = module.modules
 
       /* lifecycle - bootstrapping */
       modules.forEach(async (m, idx) => {
         try {
-          m.bootstrap && (await m.bootstrap())
+          m.bootstrap && (await m.bootstrap(m))
         } catch (e) {
           console.error(`[${idx} BOOTSTRAP ERROR -${m.name}]`, e)
         }
@@ -114,7 +128,13 @@ export class ThingsApp extends connect(store)(LitElement) {
         var { contextPath } = getPathInfo(pathname)
 
         /* 페이지를 나가기 전에 옮기지 않도록 개입할 기회를 준다 */
-        if (lastPathName && lastPathName != pathname && this.activePage && !(await this.activePage.canDeactivate())) {
+        if (
+          lastPathName &&
+          lastPathName != pathname &&
+          this.activePage &&
+          this.activePage.canDeactivate &&
+          !(await this.activePage.canDeactivate())
+        ) {
           history.back()
           return
         }
@@ -146,7 +166,7 @@ export class ThingsApp extends connect(store)(LitElement) {
     super.disconnectedCallback()
   }
 
-  routeToPage() {
+  async routeToPage() {
     const activePages = this.renderRoot.querySelectorAll('main > .page[active]')
     activePages.forEach(page => {
       page.removeAttribute('active')
@@ -156,7 +176,7 @@ export class ThingsApp extends connect(store)(LitElement) {
 
     if (!this.activePage) {
       /* 해당 route에 연결된 page가 없는 경우에 main 섹션에 해당 element를 추가해준다. */
-      const tagname = ThingsApp.pages[this.page!]
+      const tagname = (await ThingsApp.pages)[this.page!]
       if (tagname) {
         const el = document.createElement(tagname) as PageView
         el.setAttribute('class', 'page')
@@ -219,19 +239,32 @@ export class ThingsApp extends connect(store)(LitElement) {
     ThingsApp.callbacks = state.route.callbacks
   }
 
-  static registerPages() {
+  static async registerPages() {
+    ThingsApp.pages = new Promise<{ [path: string]: string }>(resolve => (ThingsApp.pagesResolver = resolve))
+
     var reversedModules = [...ThingsApp.modules].reverse()
-    ThingsApp.pages = {}
+    const pages: { [path: string]: string } = {}
 
     /* 모듈 참조 순서 역순으로 page를 추가한다. (for overidable) */
-    reversedModules.forEach(m => {
-      m.routes &&
-        m.routes.forEach((route: any) => {
-          if (!ThingsApp.pages[route.page]) {
-            ThingsApp.pages[route.page] = route.tagname
-          }
-        })
-    })
+    for (const m of reversedModules) {
+      if (!m.routes) {
+        continue
+      }
+
+      /* 
+        각 모듈의 routes가 모두 완성될 때까지 ThingsApp.pages 구성을 지연한다.
+        각 모듈의 routes를 동적으로도 구성할 수 있도록 하기 위해서이다.
+      */
+      const routes = await m.routes
+
+      routes.forEach((route: any) => {
+        if (!pages[route.page]) {
+          pages[route.page] = route.tagname
+        }
+      })
+    }
+
+    ThingsApp.pagesResolver(pages)
   }
 
   setBase() {

package/src/app/pages/page-404.ts

@@ -17,8 +17,8 @@ export class Page404 extends PageView {
       text-align: center;
       color: var(--secondary-color);
     }
-    mwc-icon {
-      --mdc-icon-size: 120px;
+    md-icon {
+      --md-icon-size: 120px;
       color: var(--status-danger-color);
       text-shadow: 2px 2px 2px rgba(0, 0, 0, 0.1);
     }
@@ -28,9 +28,9 @@ export class Page404 extends PageView {
       text-transform: capitalize;
     }
     @media only screen and (max-width: 460px) {
-      mwc-icon {
+      md-icon {
         padding-top: 25%;
-        --mdc-icon-size: 90px;
+        --md-icon-size: 90px;
       }
       h2 {
         font-size: 2em;
@@ -47,7 +47,7 @@ export class Page404 extends PageView {
   render() {
     return html`
       <section>
-        <mwc-icon>error_outline</mwc-icon>
+        <md-icon>error_outline</md-icon>
         <h2>page not found!</h2>
         The page you requested cannot be found.
       </section>

package/src/app/pages/page-view.ts

@@ -22,12 +22,26 @@ function diff(after: any, before: any): any {
   return changed && changes
 }
 
+/**
+ * PageView is a base class for creating page elements with lifecycle management.
+ * Subclasses can extend PageView to define custom behavior and handle page lifecycle events.
+ */
 export class PageView extends LitElement {
+  /**
+   * Determines whether the page can be deactivated. Subclasses can override this method
+   * to implement custom deactivation logic.
+   * @returns A Promise that resolves to true if the page can be deactivated, or false otherwise.
+   */
   async canDeactivate(): Promise<boolean> {
     return Promise.resolve(true)
   }
 
-  // Only render this page if it's actually visible.
+  /**
+   * Determines whether the page should update. This method is called whenever there are
+   * changes to the page's properties.
+   * @param changes - A map of changed property values.
+   * @returns True if the page should update, or false otherwise.
+   */
   shouldUpdate(changes: PropertyValues<this>) {
     var active = String(this.active) == 'true'
     var { active: oldActive = false } = this._oldLifecycleInfo$ || {}
@@ -50,13 +64,31 @@ export class PageView extends LitElement {
     return active
   }
 
+  /**
+   * Indicates whether the page is currently active.
+   */
   @property({ type: Boolean }) active: boolean = false
+
+  /**
+   * Stores information about the page's lifecycle.
+   */
   @property({ type: Object }) lifecycle: any
+
+  /**
+   * The context path for the page.
+   */
   @property({ type: String, attribute: 'context-path' }) contextPath?: string
 
   _oldLifecycleInfo$: any
 
   /* lifecycle */
+
+  /**
+   * Handles page updates and lifecycle events. Subclasses can override this method
+   * to implement custom logic for initializing, updating, and disposing of the page.
+   * @param changes - A map of changed properties.
+   * @param force - If true, forces an update of the page.
+   */
   async pageUpdate(changes: any = {}, force: boolean = false) {
     var before = this._oldLifecycleInfo$ || {}
 
@@ -113,6 +145,9 @@ export class PageView extends LitElement {
     }
   }
 
+  /**
+   * Resets the page. Subclasses can override this method to perform custom reset logic.
+   */
   async pageReset() {
     var { initialized } = this._oldLifecycleInfo$ || {}
 
@@ -122,14 +157,35 @@ export class PageView extends LitElement {
     }
   }
 
+  /**
+   * Disposes of the page. Subclasses can override this method to perform custom disposal logic.
+   */
   async pageDispose() {
     await this.pageUpdate({
       initialized: false
     })
   }
 
+  /**
+   * Initializes the page. Subclasses can override this method to perform custom initialization logic.
+   * @param pageInfo - Information about the page's state.
+   */
   pageInitialized(pageInfo: any) {}
+
+  /**
+   * Handles page updates and changes in properties.
+   * Subclasses can override this method to implement custom update logic.
+   * @param changes - A map of changed properties.
+   * @param after - The current state of the page.
+   * @param before - The previous state of the page.
+   */
   pageUpdated(changes: any, after: any, before: any) {}
+
+  /**
+   * Handles the disposal of the page. Subclasses can override this method
+   * to implement custom disposal logic.
+   * @param pageInfo - Information about the page's state.
+   */
   pageDisposed(pageInfo: any) {}
 
   /* context */
@@ -140,6 +196,12 @@ export class PageView extends LitElement {
     })
   }
 
+  /**
+   * Updates the context of the page. Subclasses can override the `context` getter
+   * to provide specific context information for the page. The context will be updated
+   * using the `updateContext` method inherited from PageView.
+   * @param override - An optional object with context properties to override.
+   */
   get context() {
     return {}
   }

package/src/custom-alert.ts

@@ -0,0 +1,43 @@
+import { OxPrompt } from '@operato/popup'
+
+const TYPES_ICON: { [type: string]: string } = {
+  success: 'verified',
+  error: 'error',
+  warning: 'warning',
+  info: 'info',
+  question: 'question_mark'
+}
+
+export async function CustomAlert({
+  type,
+  icon,
+  title,
+  text,
+  confirmButton,
+  cancelButton,
+  callback
+}: {
+  type?: 'info' | 'success' | 'error' | 'warning' | 'question'
+  icon?: string
+  title?: string
+  text?: string
+  confirmButton?: { color?: string; text: string }
+  cancelButton?: { color?: string; text: string }
+  callback?: (val: { isConfirmed: boolean; isDismissed: boolean; value: boolean }) => any
+}) {
+  const result = await OxPrompt.open({
+    type: type || 'info',
+    icon: (icon && TYPES_ICON[icon]) || icon,
+    title,
+    text,
+    confirmButton,
+    cancelButton
+  })
+
+  const val = { isConfirmed: result, isDismissed: !result, value: result }
+  if (callback && typeof callback === 'function') {
+    callback(val)
+  } else {
+    return val
+  }
+}

package/src/entries/public/home.ts

@@ -1,5 +1,4 @@
-import '@material/mwc-icon-button'
-import '@material/mwc-button'
+import '@material/web/icon/icon.js'
 
 import { css, html, LitElement } from 'lit'
 import { customElement } from 'lit/decorators.js'
@@ -13,7 +12,7 @@ export class HomePage extends LitElement {
       display: block;
       position: relative;
 
-      --mdc-theme-primary: white;
+      --md-theme-primary: white;
     }
 
     [home] {
@@ -30,17 +29,19 @@ export class HomePage extends LitElement {
       color: #fff;
       text-align: center;
       font-size: 20px;
-    }
-    [message] strong {
-      display: block;
-      font-size: 2.5rem;
-    }
-    [message] img {
-      width: 450px;
-      max-width: 90%;
-      display: block;
-      margin: auto;
-      margin-top: 20px;
+
+      strong {
+        display: block;
+        font-size: 2.5rem;
+      }
+
+      img {
+        width: 450px;
+        max-width: 90%;
+        display: block;
+        margin: auto;
+        margin-top: 20px;
+      }
     }
 
     @media screen and (max-width: 460px) {
@@ -64,10 +65,10 @@ export class HomePage extends LitElement {
   }
 
   render() {
-    var { icon, title, description } = this.applicationMeta
+    var { title, description } = this.applicationMeta
 
     return html`
-      <mwc-icon-button home icon="home" @click=${() => (window.location.href = '/')}></mwc-icon-button>
+      <md-icon home @click=${() => (window.location.href = '/')}>home</md-icon>
 
       <div message>
         <strong>${title}</strong>

package/src/index.ts

@@ -3,3 +3,4 @@ export * from './store'
 export * from './actions'
 export * from './app/pages/page-view'
 export * from './object-store'
+export * from './custom-alert'

package/src/store.ts

@@ -14,6 +14,15 @@ declare global {
 // See https://github.com/zalmoxisus/redux-devtools-extension for more information.
 const devCompose = window.__REDUX_DEVTOOLS_EXTENSION_COMPOSE__ || compose
 
+// Only for providing test environment - combineReducers 에서 process.env.NODE_ENV를 접근하기 때문에.
+if (typeof window.process == 'undefined') {
+  window.process = {
+    env: {
+      NODE_ENV: JSON.stringify('development')
+    }
+  } as any
+}
+
 export const store: Store<unknown, Action<any>> & LazyStore = createStore(
   state => state,
   devCompose(lazyReducerEnhancer(combineReducers), applyMiddleware(thunk))

package/stories/app.stories.ts

@@ -0,0 +1,51 @@
+import '@material/web/icon/icon.js'
+
+import { css, html, render, TemplateResult } from 'lit'
+import '../src/app/app.js'
+
+export default {
+  title: 'things-app',
+  component: 'things-app',
+  argTypes: {
+    label: { control: 'string' }
+  }
+}
+
+interface Story<T> {
+  (args: T): TemplateResult
+  args?: Partial<T>
+  argTypes?: Record<string, unknown>
+}
+
+interface ArgTypes {
+  label?: string
+}
+
+const Template: Story<ArgTypes> = ({ label = '' }: ArgTypes) => html`
+  <link href="/themes/app-theme.css" rel="stylesheet" />
+  <link
+    href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL@20..48,100..700,0..1"
+    rel="stylesheet"
+  />
+  <link
+    href="https://fonts.googleapis.com/css2?family=Material+Symbols+Rounded:opsz,wght,FILL@20..48,100..700,0..1"
+    rel="stylesheet"
+  />
+  <link
+    href="https://fonts.googleapis.com/css2?family=Material+Symbols+Sharp:opsz,wght,FILL@20..48,100..700,0..1"
+    rel="stylesheet"
+  />
+
+  <style>
+    body {
+      background-color: white;
+    }
+  </style>
+
+  <things-app></things-app>
+`
+
+export const Regular = Template.bind({})
+Regular.args = {
+  label: 'common header styles'
+}