// View // ---- import type { Bindings } from '@mnjs/utils'; import { MarionetteError, getValue, uniqueId } from '@mnjs/utils'; import extend from '../utils/extend.ts'; import monitorViewEvents from './common/monitor-view-events.ts'; import buildRegion from './common/build-region.ts'; import ViewMixin, { ViewOptions } from '../mixins/view.ts'; import Region from './region.ts'; import { setEventDelegator } from '../runtime/event-delegator.ts'; import { setRenderer } from '../runtime/renderer.ts'; import { setDomApi } from '../runtime/dom-api.ts'; import { setDataApi } from '../runtime/data-api.ts'; import { setStateApi } from '../runtime/state-api.ts'; import { runtimeId } from '../runtime-id.ts'; import type { ViewMixinHost } from '../mixins/view.ts'; import type { DOMEvents, DOMTriggers } from '../mixins/view-events.ts'; import type { UISelectors, UIBindings } from '../mixins/ui.ts'; import type { BehaviorDefinitions, BehaviorInstance } from '../mixins/behaviors.ts'; import type { EventCallback } from '@mnjs/utils'; import type CommonMixin from '../mixins/common.ts'; import type { DomApi } from '../runtime/dom-api.ts'; import type { DataApi } from '../runtime/data-api.ts'; import type { StateApi } from '../runtime/state-api.ts'; import type { EventDelegator } from '../runtime/event-delegator.ts'; import type { Renderer } from '../runtime/renderer.ts'; import type { SupportedView } from './common/view.ts'; import type { RegionInstance, RegionInternals, ShowOptions } from './region.ts'; import type { RegionDefinition, RegionClass } from './common/build-region.ts'; import type { Constructed, Merge, ArgumentsFor, DefaultOptions, OptionsFor, StateFor, SuppliedState } from './object.ts'; /** * Configure a component with data-first templates and managed child Regions. * @example * // This example uses the optional @mnjs/html adapter for text interpolation. * import { View } from 'marionette'; * import HtmlDomApi from '@mnjs/html/marionette'; * import { html } from '@mnjs/html'; * const Ready = View.extend({ template: () => html`Ready` }).setDomApi(HtmlDomApi); * const Screen = View.extend({ * template: ({ title }) => html`

${title}

`, * regions: { body: '.body' }, * onRender() { this.showChildView('body', new Ready()); } * }).setDomApi(HtmlDomApi); * const screen = new Screen({ model: { title: 'Posts' } }); * // Show through a Region; destroy that Region at teardown. */ export interface ViewConfiguration { el?: Element | (() => Element); tagName?: string | (() => string); id?: string | null | (() => string | null | undefined); className?: string | null | (() => string | null | undefined); attributes?: Record | (() => Record); model?: unknown; collection?: unknown; events?: DOMEvents | (() => DOMEvents); triggers?: DOMTriggers | (() => DOMTriggers); ui?: UIBindings; behaviors?: BehaviorDefinitions | (() => BehaviorDefinitions); regions?: Record | (() => Record); regionClass?: RegionClass; childViewEvents?: Record | (() => Record); childViewTriggers?: Record | (() => Record); childViewEventPrefix?: string | false | (() => string | false); modelEvents?: Bindings | (() => Bindings); collectionEvents?: Bindings | (() => Bindings); stateEvents?: Bindings | (() => Bindings); state?: unknown; template?: unknown; templateContext?: object | (() => object); } type Common = typeof CommonMixin; import type { ViewFluent } from './common/chainable-methods.ts'; export interface ViewInstance = ArrayLike> extends Common, ViewFluent<{}> { cid: string; cidPrefix: string; options: Options; readonly el: Element; tagName: string | (() => string); id?: ViewConfiguration['id']; className?: ViewConfiguration['className']; attributes?: ViewConfiguration['attributes']; model?: unknown; collection?: unknown; events?: ViewConfiguration['events']; triggers?: ViewConfiguration['triggers']; ui?: UIBindings | Record; behaviors?: ViewConfiguration['behaviors']; regions: Record | (() => Record); regionClass: RegionClass; childViewEvents?: ViewConfiguration['childViewEvents']; childViewTriggers?: ViewConfiguration['childViewTriggers']; childViewEventPrefix?: ViewConfiguration['childViewEventPrefix']; modelEvents?: Bindings | (() => Bindings); collectionEvents?: Bindings | (() => Bindings); stateEvents?: Bindings | (() => Bindings); state?: unknown; template?: unknown; templateContext?: ViewConfiguration['templateContext']; Dom: Partial>; Data: Partial; State: Partial>; EventDelegator: EventDelegator; _renderHtml?: Renderer; monitorViewEvents?: boolean; preinitialize(options?: Options): void; initialize(options?: Options): void; createState(options?: Options): unknown; getState(): State; $(selector: string): Query; isDestroyed(): boolean; isRendered(): boolean; isAttached(): boolean; _removeBehavior(behavior: BehaviorInstance): void; _getImmediateChildren(): SupportedView[]; getUI(name: string): Query | undefined; normalizeUIString(value: string, bindings?: UISelectors): string; normalizeUIKeys(hash: Record | null | undefined, bindings?: UISelectors): Record; normalizeUIValues(hash: Hash, property?: string, bindings?: UISelectors): Hash; getTemplate(): unknown; serializeData(): unknown; serializeModel(): unknown; serializeCollection(): unknown[]; mixinTemplateContext(data: unknown): unknown; attachElContent(html: unknown): void; addRegion(name: string, definition: RegionDefinition): RegionInstance; addRegions(regions?: Record | null): Record | undefined; removeRegion(name: string): RegionInstance; removeRegions(): Record; emptyRegions(): Record; hasRegion(name: string): boolean; getRegion(name: string): RegionInstance | undefined; getRegions(): Record; showChildView(name: string, view: Child, options?: ShowOptions): Child; detachChildView(name: string): SupportedView | undefined; getChildView(name: string): SupportedView | undefined; } type ViewResult> = Extract extends never ? ViewInstance, OptionsFor>, State, Query> & Props : Merge, OptionsFor>, State, Query>, keyof ViewFluent<{}>>, Extract<'options' | 'el', keyof Props> extends never ? Props : Omit> & ViewFluent; export type ViewConstructor = ArrayLike> = { new (...args: Provided): Constructed, Query>>; (this: object, ...args: Args): void; } & Merge<{ prototype: ViewResult; call(receiver: object, ...args: Args): void; apply(receiver: object, args: Args | IArguments): void; setRenderer: typeof setRenderer; setDomApi: typeof setDomApi; setEventDelegator: typeof setEventDelegator; setDataApi: typeof setDataApi; setStateApi: typeof setStateApi; extend( this: Added extends { constructor: (...args: never[]) => unknown } ? object : (this: object, ...args: never[]) => unknown, prototypeProperties?: Added & ThisType, ArgumentsFor, Args>, StateFor>, Query>>, staticProperties?: AddedStatics & ThisType, ArgumentsFor, Args>, StateFor>, Merge, Query>> ): ViewConstructor, ArgumentsFor, Args>, StateFor>, Merge, Query>; }, Statics>; type RegionMap = Record; type RegionDefinitions = Record; type ViewInternals = ViewInstance & ViewMixinHost & { [runtimeId]?: object; regions: RegionDefinitions; _regions: RegionMap; _initRegions(): void; _reInitRegions(): void; _addRegions(regions: RegionDefinitions): RegionMap; _addRegion(region: RegionInternals, name: string): void; _removeReferences(name: string): void; _getRegions(): RegionMap; _isElAttached(): boolean; _getEl(): Element; }; const classErrorName = 'RegionError'; function assertRegionName(name: string) { if (name.length > 0) { return; } throw new MarionetteError({ code: 'MN0032', name: classErrorName, message: 'A Region name must be a non-empty string.' }); } function setRegion(regions: Record, definition: Value, name: string) { assertRegionName(name); Object.defineProperty(regions, name, { configurable: true, enumerable: true, value: definition, writable: true }); return regions; } function getOwnRegion(regions: RegionMap, name: string): RegionInternals | undefined { assertRegionName(name); return regions[name]; } function getRequiredRegion(region: RegionInstance | undefined, name: string) { if (region) { return region; } throw new MarionetteError({ code: 'MN0020', name: classErrorName, message: `Region "${name}" does not exist.` }); } function getRegionForChild(view: ViewInternals, name: string) { assertRegionName(name); if (!view._isRendered) { view.render(); } return getRequiredRegion(view.getRegion(name), name); } function throwRegionRegistrationConflict(message: string) { throw new MarionetteError({ code: 'MN0030', name: classErrorName, message }); } function isSameRegionRegistration(view: ViewInternals, region: RegionInternals, name: string) { return region._parentView === view && region._name === name && getOwnRegion(view._regions, name) === region; } function assertRegionCanRegister(view: ViewInternals, region: RegionInternals, name: string) { if (isSameRegionRegistration(view, region, name)) { return; } if (region._parentView !== undefined) { throwRegionRegistrationConflict('A Region instance cannot be registered with more than one owner or name.'); } if (region._isDestroying || region._isDestroyed) { throwRegionRegistrationConflict('A destroying or destroyed Region cannot be registered.'); } if (getOwnRegion(view._regions, name)) { throwRegionRegistrationConflict(`Region name "${name}" is already registered.`); } } function assertRegionDefinitionsCanRegister(view: ViewInternals, definitions: RegionDefinitions) { const seenRegions = new Set(); for (const name of Object.keys(definitions)) { const definition = definitions[name]; if (!(definition instanceof Region)) { if (getOwnRegion(view._regions, name)) { throwRegionRegistrationConflict(`Region name "${name}" is already registered.`); } continue; } if (seenRegions.has(definition)) { throwRegionRegistrationConflict('A Region instance cannot be registered under more than one name.'); } seenRegions.add(definition); assertRegionCanRegister(view, definition as RegionInternals, name); } } // MixinOptions // - regions // - regionClass const RegionsMixin = { regionClass: Region, // Internal method to initialize the regions that have been defined in a // `regions` attribute on this View. _initRegions(this: ViewInternals) { // init regions hash this.regions = this.regions || {}; this._regions = Object.create(null); this.addRegions(getValue(this, 'regions') as RegionDefinitions | undefined); }, // Empty each Region and restore its initial element reference. Selector-based // Regions resolve against the new template when their next operation needs it. _reInitRegions(this: ViewInternals) { for (const name of Object.keys(this._regions)) { this._regions[name].reset(); } }, // Add a single region, by name, to the View addRegion(this: ViewInternals, name: string, definition: RegionDefinition) { const regions = setRegion({}, definition, name); return this.addRegions(regions)![name]; }, // Add multiple regions as a {name: definition, name2: def2} object literal addRegions(this: ViewInternals, regions?: RegionDefinitions | null) { // If there's nothing to add, stop here. if (regions == null || Object.keys(regions).length === 0) { return; } for (const name of Object.keys(regions)) { assertRegionName(name); } // Normalize private copies so shared declarations retain their @ui selectors. const definitions: RegionDefinitions = {}; for (const name of Object.keys(regions)) { const definition = regions[name]; setRegion(definitions, typeof definition === 'object' && !(definition instanceof Region) ? { ...definition } : definition, name); } regions = this.normalizeUIValues(definitions, 'el'); assertRegionDefinitionsCanRegister(this, regions); // Add the regions definitions to the regions property const allRegions = {}; for (const name of Object.keys(this.regions)) { setRegion(allRegions, this.regions[name], name); } for (const name of Object.keys(regions)) { setRegion(allRegions, regions[name], name); } this.regions = allRegions; return this._addRegions(regions); }, // internal method to build and add regions _addRegions(this: ViewInternals, regionDefinitions: RegionDefinitions) { const defaults = { [runtimeId]: this[runtimeId], regionClass: this.regionClass, parentEl: () => getValue(this, 'el') as Element }; const regions: RegionMap = {}; for (const name of Object.keys(regionDefinitions)) { const region = buildRegion(regionDefinitions[name], defaults); this._addRegion(region, name); setRegion(regions, region, name); } return regions; }, _addRegion(this: ViewInternals, region: RegionInternals, name: string) { // Repeating the completed identity is safe even during teardown: this path does not mutate. if (isSameRegionRegistration(this, region, name)) { return; } assertRegionCanRegister(this, region, name); region._parentView = this; region._name = name; this._regions[name] = region; }, // Remove a single region from the View, by name removeRegion(this: ViewInternals, name: string) { const region = getRequiredRegion(getOwnRegion(this._regions, name), name); region.destroy(); return region; }, // Remove all regions from the View removeRegions(this: ViewInternals) { const regions = this._getRegions(); for (const name of Object.keys(regions)) { regions[name].destroy(); } return regions; }, // Called in a region's destroy _removeReferences(this: ViewInternals, name: string) { delete this.regions[name]; delete this._regions[name]; }, // Render the parent if needed, then empty each Region while keeping its registration. emptyRegions(this: ViewInternals) { if (!this._isRendered) { this.render(); } const regions = this.getRegions(); for (const name of Object.keys(regions)) { regions[name].empty(); } return regions; }, // Checks to see if view contains region // Accepts the region name // hasRegion('main') hasRegion(this: ViewInternals, name: string) { return !!getOwnRegion(this._regions, name); }, // Provides access to regions // Accepts the region name // getRegion('main') getRegion(this: ViewInternals, name: string) { return getOwnRegion(this._regions, name); }, _getRegions(this: ViewInternals) { const regions: RegionMap = {}; for (const name of Object.keys(this._regions)) { setRegion(regions, this._regions[name], name); } return regions; }, // Get all regions getRegions(this: ViewInternals) { return this._getRegions(); }, showChildView(this: ViewInternals, name: string, view: SupportedView, options?: ShowOptions) { const region = getRegionForChild(this, name); region.show(view, options); return view; }, detachChildView(this: ViewInternals, name: string) { return getRegionForChild(this, name).detachView(); }, getChildView(this: ViewInternals, name: string) { return getRegionForChild(this, name).currentView; } }; // View // --------- const ViewClassOptions = [ 'attributes', 'behaviors', 'childViewEventPrefix', 'childViewEvents', 'childViewTriggers', 'className', 'collection', 'collectionEvents', 'el', 'events', 'id', 'model', 'modelEvents', 'regionClass', 'regions', 'stateEvents', 'tagName', 'template', 'templateContext', 'triggers', 'ui' ]; // Used by _getImmediateChildren function childReducer(children: SupportedView[], region: RegionInternals) { if (region.currentView) { children.push(region.currentView); } return children; } // Initialize a View's element, events, State, Behaviors, and named Regions. // Construction does not evaluate its template; render() or an owning Region does. const View = function(this: ViewInternals, options?: ViewConfiguration) { this.cid = uniqueId(this.cidPrefix); this._setOptions(options, ViewClassOptions); (this.preinitialize as Function).apply(this, arguments); this.mergeOptions(options, ViewOptions); this._initViewEvents(); this.el = this._getEl(); this._isRendered = this.Dom.hasContents!(this.el); this._isAttached = this._isElAttached(); if (this._isRendered) { this.bindUIElements(); } this.delegateEvents(); if (this._isAttached && this.monitorViewEvents !== false) { this.Dom.notifyAttach?.(this.el); } monitorViewEvents(this); this._initState(options); this._initBehaviors(); this._initRegions(); this._buildEventProxies(); (this.initialize as Function).apply(this, arguments); if (this._isDestroyed || this._isDestroying) { return; } this._initStateEvents(); this.delegateEntityEvents(); this._triggerEventOnBehaviors('initialize', this, options); }; Object.assign(View, { extend, setRenderer, setDomApi, setEventDelegator, setDataApi, setStateApi }); Object.assign(View.prototype, ViewMixin, RegionsMixin, { cidPrefix: 'mnv', // If a template is available, renders it into the view's `el` // Re-inits regions and binds UI. render(this: ViewInternals) { if (this._isDestroyed) { return this; } const template = this.getTemplate(); if (template === false) { return this; } this.triggerMethod('before:render', this); // Existing rendered content (including prerendered DOM) requires Region reset // before replacing the template; this destroys any current child Views. if (this._isRendered) { this._reInitRegions(); } this._renderTemplate(template); this.bindUIElements(); this._isRendered = true; this.triggerMethod('render', this); return this; }, // called by ViewMixin destroy _removeChildren(this: ViewInternals) { this.removeRegions(); }, _getImmediateChildren(this: ViewInternals) { const children: SupportedView[] = []; for (const name of Object.keys(this._regions)) { childReducer(children, this._regions[name]); } return children; } }); export default View as unknown as ViewConstructor;