terrier-engine 4.0.21 → 4.1.0

package/parts/content-part.ts

@@ -0,0 +1,188 @@
+import Theme, {Action, ThemeType} from "../theme"
+import {TerrierApp} from "../app"
+import {PartParent, PartTag} from "tuff-core/parts"
+import {Dropdown} from "../dropdowns"
+import TerrierPart from "./terrier-part"
+
+export type PanelActions<TT extends ThemeType> = {
+    primary: Array<Action<TT>>
+    secondary: Array<Action<TT>>
+    tertiary: Array<Action<TT>>
+}
+export type ActionLevel = keyof PanelActions<any>
+
+/**
+ * Base class for all Parts that render some main content, like pages, panels, and modals.
+ */
+export default abstract class ContentPart<
+    TState,
+    TThemeType extends ThemeType,
+    TApp extends TerrierApp<TThemeType, TApp, TTheme>,
+    TTheme extends Theme<TThemeType>
+> extends TerrierPart<TState, TThemeType, TApp, TTheme> {
+
+    /**
+     * All ContentParts must implement this to render their actual content.
+     * @param parent
+     */
+    abstract renderContent(parent: PartTag): void
+
+
+    protected _title = ''
+
+    /**
+     * Sets the page, panel, or modal title.
+     * @param title
+     */
+    setTitle(title: string) {
+        this._title = title
+    }
+
+    protected _icon: TThemeType['icons'] | null = null
+
+    setIcon(icon: TThemeType['icons']) {
+        this._icon = icon
+    }
+
+    protected _titleClasses: string[] = []
+
+    addTitleClass(c: string) {
+        this._titleClasses.push(c)
+    }
+
+
+    /// Actions
+
+    // stored actions can be either an action object or a reference to a named action
+    private _actions = {
+        primary: Array<Action<TThemeType> | string>(),
+        secondary: Array<Action<TThemeType> | string>(),
+        tertiary: Array<Action<TThemeType> | string>()
+    }
+
+    private _namedActions: Record<string, { action: Action<TThemeType>, level: ActionLevel }> = {}
+
+    /**
+     * Add an action to the part, or replace a named action if it already exists.
+     * @param action the action to add
+     * @param level whether it's a primary, secondary, or tertiary action
+     * @param name a name to be given to this action, so it can be accessed later
+     */
+    addAction(action: Action<TThemeType>, level: ActionLevel = 'primary', name?: string) {
+        if (name?.length) {
+            if (name in this._namedActions) {
+                const currentLevel = this._namedActions[name].level
+                if (level != currentLevel) {
+                    const index = this._actions[currentLevel].indexOf(name)
+                    this._actions[currentLevel].splice(index, 1)
+                    this._actions[level].push(name)
+                }
+                this._namedActions[name].action = action
+            } else {
+                this._namedActions[name] = {action, level}
+                this._actions[level].push(name)
+            }
+        } else {
+            this._actions[level].push(action)
+        }
+    }
+
+    /**
+     * Returns the action definition for the action with the given name, or undefined if there is no action with that name
+     * @param name
+     */
+    getNamedAction(name: string): Action<TThemeType> | undefined {
+        return this._namedActions[name].action
+    }
+
+    /**
+     * Removes the action with the given name
+     * @param name
+     */
+    removeNamedAction(name: string) {
+        if (!(name in this._namedActions)) return
+        const level = this._actions[this._namedActions[name].level]
+        delete this._namedActions[name]
+        const actionIndex = level.indexOf(name)
+        if (actionIndex >= 0) {
+            level.splice(actionIndex, 1)
+        }
+    }
+
+    /**
+     * Clears the actions for this part
+     * @param level whether to clear the primary, secondary, or both sets of actions
+     */
+    clearActions(level: ActionLevel) {
+        for (const action of this._actions[level]) {
+            if (typeof action === 'string') {
+                delete this._namedActions[action]
+            }
+        }
+        this._actions[level] = []
+    }
+
+    getAllActions(): PanelActions<TThemeType> {
+        return {
+            primary: this.getActions('primary'),
+            secondary: this.getActions('secondary'),
+            tertiary: this.getActions('tertiary'),
+        }
+    }
+
+    getActions(level: ActionLevel): Action<TThemeType>[] {
+        return this._actions[level].map(action => {
+            return (typeof action === 'string') ? this._namedActions[action].action : action
+        })
+    }
+
+    hasActions(level: ActionLevel): boolean {
+        return this._actions[level].length > 0
+    }
+
+
+    /// Dropdowns
+
+    /**
+     * Shows the given dropdown part on the page.
+     * It's generally better to call `toggleDropdown` instead so that the dropdown will be
+     * hidden upon a subsequent click on the target.
+     * @param constructor a constructor for a dropdown part
+     * @param state the dropdown's state
+     * @param target the target element around which to show the dropdown
+     */
+    makeDropdown<DropdownType extends Dropdown<DropdownStateType, TThemeType, TApp, TTheme>, DropdownStateType extends {}>(
+        constructor: { new(p: PartParent, id: string, state: DropdownStateType): DropdownType; },
+        state: DropdownStateType,
+        target: EventTarget | null) {
+        if (!(target && target instanceof HTMLElement)) {
+            throw "Trying to show a dropdown without an element target!"
+        }
+        const dropdown = this.app.addOverlay(constructor, state, 'dropdown')
+        dropdown.parentPart = this
+        dropdown.anchor(target)
+        this.app.lastDropdownTarget = target
+    }
+
+    clearDropdowns() {
+        this.app.clearDropdowns()
+    }
+
+    /**
+     * Calls `makeDropdown` only if there's not a dropdown currently originating from the target.
+     * @param constructor a constructor for a dropdown part
+     * @param state the dropdown's state
+     * @param target the target element around which to show the dropdown
+     */
+    toggleDropdown<DropdownType extends Dropdown<DropdownStateType, TThemeType, TApp, TTheme>, DropdownStateType extends {}>(
+        constructor: { new(p: PartParent, id: string, state: DropdownStateType): DropdownType; },
+        state: DropdownStateType,
+        target: EventTarget | null) {
+        if (target && target instanceof HTMLElement && target == this.app.lastDropdownTarget) {
+            this.clearDropdowns()
+        } else {
+            this.makeDropdown(constructor, state, target)
+        }
+    }
+
+}

package/parts/not-found-page.ts

@@ -0,0 +1,26 @@
+import {Logger} from "tuff-core/logging"
+import Theme, {ThemeType} from "../theme"
+import {TerrierApp} from "../app"
+import PagePart from "./page-part"
+import {NoState, PartTag} from "tuff-core/parts"
+
+const log = new Logger('NotFoundRoute')
+
+/**
+ * Default page part if the router can't find the path.
+ */
+export default class NotFoundRoute<
+    TT extends ThemeType,
+    TApp extends TerrierApp<TT, TApp, TTheme>,
+    TTheme extends Theme<TT>
+> extends PagePart<NoState, TT, TApp, TTheme> {
+    async init() {
+        this.setTitle("Page Not Found")
+    }
+
+    renderContent(parent: PartTag) {
+        log.warn(`Not found: ${this.context.href}`)
+        parent.h1({text: "Not Found"})
+    }
+
+}

package/parts/page-part.ts

@@ -0,0 +1,196 @@
+import Theme, {Action, RenderActionOptions, ThemeType} from "../theme"
+import {TerrierApp} from "../app"
+import ContentPart, {ActionLevel} from "./content-part"
+import {PartTag} from "tuff-core/parts"
+import {optionsForSelect, SelectOptions} from "tuff-core/forms"
+import {UntypedKey} from "tuff-core/messages"
+import {Logger} from "tuff-core/logging"
+import {HtmlParentTag} from "tuff-core/html"
+
+const log = new Logger("Terrier PagePart")
+
+/**
+ * Whether some content should be constrained to a reasonable width or span the entire screen.
+ */
+export type ContentWidth = "normal" | "wide"
+
+/// Top row fields
+
+type BaseFieldDef = { name: string } & ToprowFieldDefOptions
+
+type ToprowFieldDefOptions = {
+    onChangeKey?: UntypedKey,
+    onInputKey?: UntypedKey,
+    defaultValue?: string,
+    tooltip?: string
+}
+
+type ToprowSelectDef = { type: 'select', options: SelectOptions } & BaseFieldDef
+
+type ValuedInputType = 'text' | 'color' | 'date' | 'datetime-local' | 'email' | 'hidden' | 'month' | 'number' | 'password' | 'search' | 'tel' | 'time' | 'url' | 'week'
+type ToprowValuedInputDef = { type: ValuedInputType } & BaseFieldDef
+
+/**
+ * Defines a field to be rendered in the page's top row
+ */
+type ToprowFieldDef = ToprowSelectDef | ToprowValuedInputDef
+
+/**
+ * A part that renders content to a full page.
+ */
+export default abstract class PagePart<
+    TState,
+    TThemeType extends ThemeType,
+    TApp extends TerrierApp<TThemeType, TApp, TTheme>,
+    TTheme extends Theme<TThemeType>
+> extends ContentPart<TState, TThemeType, TApp, TTheme> {
+
+    /// Content Width
+
+    /**
+     * Whether the main content should be constrained to a reasonable width (default) or span the entire screen.
+     */
+    protected mainContentWidth: ContentWidth = "normal"
+
+    /// Breadcrumbs
+
+    private _breadcrumbs = Array<Action<TThemeType>>()
+
+    addBreadcrumb(crumb: Action<TThemeType>) {
+        this._breadcrumbs.push(crumb)
+    }
+
+    private _titleHref?: string
+
+    /**
+     * Adds an href to the title (last) breadcrumb.
+     * @param href
+     */
+    setTitleHref(href: string) {
+        this._titleHref = href
+    }
+
+    /// Top Bar Fields
+
+    private _toprowFieldsOrder: string[] = []
+    private _toprowFields: Record<string, ToprowFieldDef> = {}
+
+    protected get hasToprowFields() {
+        return this._toprowFieldsOrder.length > 0
+    }
+
+    /**
+     * Adds a select to the toolbar with the given options.
+     * @param name the name of the select
+     * @param selectOptions an array of select options
+     * @param opts
+     */
+    addToprowSelect(name: string, selectOptions: SelectOptions, opts?: ToprowFieldDefOptions) {
+        this.addToprowFieldDef({ type: 'select', name, options: selectOptions, ...opts })
+    }
+
+    /**
+     * Adds a select to the toolbar with the given options.
+     * @param name the name of the select
+     * @param type the type attribute of the input field
+     * @param opts
+     */
+    addToprowInput(name: string, type: ValuedInputType, opts?: ToprowFieldDefOptions) {
+        this.addToprowFieldDef({ type, name, ...opts })
+    }
+
+    private addToprowFieldDef(def: ToprowFieldDef) {
+        this._toprowFieldsOrder.push(def.name)
+        this._toprowFields[def.name] = def
+    }
+
+    /// Rendering
+
+    protected get topRowClasses() : string[] {
+        return []
+    }
+
+    render(parent: PartTag) {
+        parent.div(`.tt-page-part.content-width-${this.mainContentWidth}`, page => {
+            page.div('.tt-flex.top-row', topRow => {
+                topRow.class(...this.topRowClasses)
+                topRow.div('.page-title', col => this.renderBreadcrumbs(col));
+                topRow.div('.page-top-actions', col => {
+                    this.renderCustomToprow(col)
+                    if (this.hasToprowFields) this.renderToprowFields(col);
+                    if (this.hasActions('tertiary')) this.renderActions(col, 'tertiary');
+                });
+
+            })
+
+            page.div('.lighting')
+            page.div('.full-width-page', conatiner => {
+                conatiner.div('.page-content', main => {
+                    this.renderContent(main)
+                    main.div('.page-actions', actions => {
+                        this.renderActions(actions, 'secondary', {iconColor: null, defaultClass: 'secondary'})
+                        this.renderActions(actions, 'primary', {iconColor: null, defaultClass: 'primary'})
+                    })
+                })
+            })
+        })
+    }
+
+    protected renderActions(parent: PartTag, level: ActionLevel, options?: RenderActionOptions<TThemeType>) {
+        parent.div(`.${level}-actions`, actions => {
+            this.app.theme.renderActions(actions, this.getActions(level), options)
+        })
+    }
+
+    protected renderBreadcrumbs(parent: PartTag) {
+        if (!this._breadcrumbs.length && !this._title?.length) return
+
+        parent.h1('.breadcrumbs', h1 => {
+            const crumbs = Array.from(this._breadcrumbs)
+
+            // add a breadcrumb for the page title
+            const titleCrumb: Action<TThemeType> = {
+                title: this._title,
+                icon: this._icon || undefined,
+            }
+            if (this._titleHref) {
+                titleCrumb.href = this._titleHref
+            }
+            if (this._titleClasses?.length) {
+                titleCrumb.classes = this._titleClasses
+            }
+            crumbs.push(titleCrumb)
+
+            this.app.theme.renderActions(h1, crumbs)
+        })
+    }
+
+    protected renderCustomToprow(_parent: PartTag): void {
+
+    }
+
+    protected renderToprowFields(parent: PartTag) {
+        parent.div('.fields.tt-flex.align-center.small-gap', fields => {
+            for (const name of this._toprowFieldsOrder) {
+                const def = this._toprowFields[name]
+                if (!def) {
+                    log.warn(`No select def with name ${name} could be found!`)
+                    continue;
+                }
+
+                let field!: HtmlParentTag
+                if (def.type === 'select') {
+                    field = fields.select({name: def.name}, select => {
+                        optionsForSelect(select, def.options, def.defaultValue)
+                    })
+                } else {
+                    field = fields.input({name: def.name, type: def.type})
+                }
+
+                if (def.onChangeKey) field.emitChange(def.onChangeKey)
+                if (def.onInputKey) field.emitInput(def.onInputKey)
+                if (def.tooltip?.length) field.dataAttr('tooltip', def.tooltip)
+            }
+        })
+    }
+}

package/parts/panel-part.ts

@@ -0,0 +1,47 @@
+import Theme, {ThemeType} from "../theme"
+import {TerrierApp} from "../app"
+import ContentPart from "./content-part"
+import {PartTag} from "tuff-core/parts"
+import Fragments from "../fragments"
+
+/**
+ * A part that renders content inside a panel.
+ */
+export default abstract class PanelPart<
+    TState,
+    TThemeType extends ThemeType,
+    TApp extends TerrierApp<TThemeType, TApp, TTheme>,
+    TTheme extends Theme<TThemeType>
+> extends ContentPart<TState, TThemeType, TApp, TTheme> {
+
+    getLoadingContainer() {
+        return this.element?.getElementsByClassName('tt-panel')[0]
+    }
+
+    protected get panelClasses(): string[] {
+        return []
+    }
+
+    render(parent: PartTag) {
+        parent.div('.tt-panel', panel => {
+            panel.class(...this.panelClasses)
+            if (this._title?.length || this.hasActions('tertiary')) {
+                panel.div('.panel-header', header => {
+                    header.h2(h2 => {
+                        if (this._icon) {
+                            this.app.theme.renderIcon(h2, this._icon, 'link')
+                        }
+                        h2.div('.title', {text: this._title || 'Call setTitle()'})
+                    })
+                    header.div('.tertiary-actions', actions => {
+                        this.theme.renderActions(actions, this.getActions('tertiary'))
+                    })
+                })
+            }
+            panel.div('.panel-content', content => {
+                this.renderContent(content)
+            })
+            Fragments.panelActions(panel, this.getAllActions(), this.theme)
+        })
+    }
+}

package/parts/terrier-part.ts

@@ -0,0 +1,94 @@
+import {Part} from "tuff-core/parts"
+import {TerrierApp} from "../app"
+import Loading from "../loading"
+import Theme, {ThemeType} from "../theme"
+import Toasts, {ToastOptions} from "../toasts"
+
+/**
+ * Base class for ALL parts in a Terrier application.
+ */
+export default abstract class TerrierPart<
+    TState,
+    TThemeType extends ThemeType,
+    TApp extends TerrierApp<TThemeType, TApp, TTheme>,
+    TTheme extends Theme<TThemeType>
+> extends Part<TState> {
+
+    get app(): TApp {
+        return this.root as TApp // this should always be true
+    }
+
+    get theme(): TTheme {
+        return this.app.theme
+    }
+
+    /// Loading
+
+    /**
+     * This can be overloaded if the loading overlay should go
+     * somewhere other than the part's root element.
+     */
+    getLoadingContainer(): Element | null | undefined {
+        return this.element
+    }
+
+
+    /**
+     * Shows the loading animation on top of the part.
+     */
+    startLoading() {
+        const elem = this.getLoadingContainer()
+        if (!elem) {
+            return
+        }
+        Loading.showOverlay(elem, this.theme)
+    }
+
+    /**
+     * Removes the loading animation from the part.
+     */
+    stopLoading() {
+        const elem = this.getLoadingContainer()
+        if (!elem) {
+            return
+        }
+        Loading.removeOverlay(elem)
+    }
+
+    /**
+     * Shows the loading overlay until the given function completes (either returns successfully or throws an exception)
+     * @param func
+     */
+    showLoading(func: () => void): void
+    showLoading(func: () => Promise<void>): Promise<void>
+    showLoading(func: () => void | Promise<void>): void | Promise<void>  {
+        this.startLoading()
+        let stopImmediately = true
+        try {
+            const res = func()
+            if (res) {
+                stopImmediately = false
+                return res.finally(() => {
+                    this.stopLoading()
+                })
+            }
+        } finally {
+            if (stopImmediately) {
+                this.stopLoading()
+            }
+        }
+    }
+
+
+    /// Toasts
+
+    /**
+     * Shows a toast message in a bubble in the upper right corner.
+     * @param message the message text
+     * @param options
+     */
+    showToast(message: string, options: ToastOptions<TThemeType>) {
+        Toasts.show(message, options, this.theme)
+    }
+
+}

package/parts/themed-form-part.ts

@@ -0,0 +1,25 @@
+import {FormPart, FormPartData} from "tuff-core/forms"
+import Theme, {ThemeType} from "../theme"
+import {TerrierApp} from "../app"
+
+export default abstract class ThemedFormPart<
+    TState extends FormPartData,
+    TThemeType extends ThemeType,
+    TApp extends TerrierApp<TThemeType, TApp, TTheme>,
+    TTheme extends Theme<TThemeType>
+> extends FormPart<TState> {
+
+
+    get app(): TApp {
+        return this.root as TApp // this should always be true
+    }
+
+    get theme(): TTheme {
+        return this.app.theme
+    }
+
+
+    get parentClasses(): Array<string> {
+        return ['tt-form']
+    }
+}

package/schema.ts

@@ -1,4 +1,5 @@
 import Api from "./api"
+import inflection from "inflection";
 
 ////////////////////////////////////////////////////////////////////////////////
 // Schema Definitions
@@ -60,8 +61,34 @@ async function get(): Promise<SchemaDef> {
     return res.schema
 }
 
+
+////////////////////////////////////////////////////////////////////////////////
+// Utilities
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Generated a string used to display a `BelongsToDef` to the user.
+ * If the name differs from the model, the name will be included in parentheses.
+ * @param belongsTo
+ */
+function belongsToDisplay(belongsTo: BelongsToDef): string {
+    if (belongsTo.name != inflection.singularize(inflection.tableize(belongsTo.model))) {
+        // the model is different than the name of the association
+        return `${belongsTo.model} (${belongsTo.name})`
+    }
+    else {
+        return belongsTo.model
+    }
+}
+
+
+////////////////////////////////////////////////////////////////////////////////
+// Export
+////////////////////////////////////////////////////////////////////////////////
+
 const Schema = {
-    get
+    get,
+    belongsToDisplay
 }
 
 export default Schema

package/toasts.ts

@@ -23,7 +23,7 @@ function show<TT extends ThemeType>(message: string, options: ToastOptions<TT>,
     if (!container) {
         log.debug(`Creating toasts container`)
         container = createElement('div', (div) => {
-            div.sel('#tt-toasts.flex.column.padded')
+            div.sel('#tt-toasts.tt-flex.column.padded')
         })
         document.body.appendChild(container)
     }