Skip to content
This repository has been archived by the owner on Feb 27, 2024. It is now read-only.

Latest commit

 

History

History
188 lines (139 loc) · 5.95 KB

OVERVIEW.md

File metadata and controls

188 lines (139 loc) · 5.95 KB
Raw

Overview

The purpose of this document is to give an overview of the Dialtone Combinator project and help provide context for any contributors wanting to work on the project.

If you are looking for documentation to implement Dialtone Combinator in an external project please see USAGE.

Documentation

Organizational

Documentation for maintaining the project.

README
CONTRIBUTING
RELEASING
COMMIT_CONVENTION
FUTURE_ADDITIONS
KNOWN_ISSUES \

Internal

Documentation that describes the system architecture in-depth.

SYSTEM
RENDERER
OPTION_BAR
CODE_PANEL CONTROLS

External

Documentation instructing how to implement into external projects.

USAGE

Terminology

  Root: The root level component in 'combinator.vue'
  Preview: The preview app in 'app.vue'
  Member: An identifiable element of a component (Prop, attribute, slot, event)
  Binding: A member that is bound to the component with `v-bind` (Prop, attribute)
  Attribute: An HTML attribute
  Documentation: The raw data generated by docgen
  Information / Info: The central data object containing extended documentation data after parsing and processing
  Options: The central data object containing key-value pairs for members and their values
  Control: A control used for manipulating a value, usually a member value
  Target Component: The component the combinator is using

Folder Structure

  / Root project folder, primarily containing configuration files 

  /.github The folder containing documentation and special GitHub files

  /dist The local folder that contains the library and preview build output

  /public The folder containing publicly accessible files for the preview app

  /src The folder containing all internal project files

  ⎣__/assets The folder containing general assets and styling for vue

  ⎣__/components The root component folder that contains the root component ('Combinator.vue')
  ⎣____/code_editor The folder containing components for the code editor
  ⎣____/code_panel The folder containing components for the code panel
  ⎣____/controls The folder containing individual control components
  ⎣____/event_console The folder containing components for the event console
  ⎣____/option_bar The folder containing components for the code editor
  ⎣____/renderer The folder containing components for the renderer

  ⎣__/lib The main library folder for files containing utility functions in plain js

  ⎣__/variants The folder containing variants for specific components for the 'variantBank' export

Root System

The Dialtone Combinator consists of three main components:

  • Renderer
  • Option bar
  • Code panel

The Dialtone Combinator uses two main data objects:

  • Info
  • Options

Data central to the system is stored in the root component and is communicated between child components. The system is designed with reactivity and extensibility in mind.

The settings data object is also used to dictate global settings for the combinator.

See SYSTEM

Supported Components

Currently, not all Dialtone Vue components are working with the Combinator.

A supported component is a component that is intended to be working with full functionality in the Combinator.

Supported components are listed in supported_components.json. These components are used by various tests to ensure they are working and future updates do not break them.

When adding a new component to this list make sure it is working with all tests afterwards.

Docgen

Documentation generated from the dialtone-vue project is used to obtain extended information about the target components. This documentation is currently generated by the vue-docgen-api which creates data based on code comments with the format indicated in the 'Vue Styleguidist' Documenting components section.

Usage

Essential generated data that is used by the Combinator:

  • Code comments and tags
    • Props
    • Slots
    • Emits
  • Default values
  • Valid values
  • Valid types
  • ...

Custom Tags

Custom tags are required by the combinator to generate some additional documentation for the components.

Attribute

Used to indicate custom members that should be generated for HTML attributes.

Format:

@property {TYPE} NAME attribute

Example:

/**
 * Base Vue component for Dialtone Buttons.
 * @displayName DtButton
 * @property {Boolean} disabled attribute
 * @property {String} width attribute
 */
export default {
  name: 'DtButton',
  ...
}

Tags for disabled and width attributes on button component

Attributes should only ever be of type 'Boolean' or 'String' based on the Mozilla reference.

Model

Used to indicate the member is used in v-model, the reason is twofold:

  • Apply a custom badge to the member in the option bar
  • Docgen implicitly changes the name of the member if it is a prop to 'v-model'

Format:

@model PROP

Example:

/**
 * The value of the input
 * @model value
 */
value: {
  type: [String, Number, Boolean, Object],
  default: null,
},

The name of the prop is indicated in the model tag, so it can be changed back to its original name. This was being implemented at one point, however the pull request went stale and has closed.