Skip to content

Latest commit

 

History

History
475 lines (382 loc) · 11.7 KB

API.md

File metadata and controls

475 lines (382 loc) · 11.7 KB
Raw

Aura Theme

Aura API

createPort

Used to create a port file in disk from a given template file path.

Definition:

interface PortCompiler {
  template: string
  replacements: Record<string, unknown>
  outputFileName?: string
  outputDist?: string
  showDebugLogs?: boolean
}

createPort(props: PortCompiler): Promise<void> {}

  • template:
    The path of the file to apply the replacements.

  • replacements:
    An object to be used for the template engine to replace values based on the name of the keys.

  • outputFileName?:
    The name to be used as output (just the name without the file extension)

  • outputDist?:
    A path to override the default <root>/packages to compile the file.

  • showDebugLogs?:
    Self-descriptive, default is true.

Example:

await createPort({
  template: resolve(templateFolder, `aura-theme.js`),
  replacements: colorSchemes.dark,
})

createInMemoryPort

Used to create a port in memory.

This is useful, for example, when you need to convert one port to another before creating it in disk.

Definition:

interface PortInMemoryCompiler {
  template: string
  replacements: Record<string, unknown>
}

createInMemoryPort(props: PortInMemoryCompiler): Promise<string> {}

  • template:
    The path of the file to apply the replacements.

  • replacements:
    An object to be used for the template engine to replace values based on the name of the keys.

Example:

await createInMemoryPort({
  template: resolve(templateFolder, `aura-theme.js`),
  replacements: {
    portName: 'Aura Theme',
  },
})

createFromInMemoryPort

Used to create a port file in disk from an in memory one.

Definition:

interface PortFromInMemoryCompiler {
  template: string
  output: string
}

createFromInMemoryPort(props: PortFromInMemoryCompiler): Promise<void> {}

  • template:
    The in memory port to be created in disk.

  • output:
    The path where the port will be created.

Example:

await createFromInMemoryPort({
  template: templateInMemory,
  output: resolve(
    constants.folders.distFolder,
    'aura-port',
    'aura-theme.json'
  ),
})

createReadme

Used to create a README.md in disk from a given template file path.

The values at "theme" property in the root "package.json" file will be injected by default to also fill the template.

Definition:

interface DocumentCompiler {
  template: string
  replacements: Record<string, unknown>
  outputFileName?: string
  outputDist?: string
  showDebugLogs?: boolean
}

createReadme(props: DocumentCompiler): Promise<void> {}

  • template:
    the path of the file to apply the replacements.

  • replacements:
    an object to be used for the template engine to replace values based on the name of the keys.

  • outputFileName?:
    The name to be used as output (just the name without the file extension)

  • outputDist?:
    A path to override the default <root>/packages to compile the file.

  • showDebugLogs?:
    self-descriptive, default is true.

Example:

await createReadme({
  template: resolve('path', 'to', 'README.md'),
  replacements: {
    portName: 'Visual Studio Code',
  },
})

copyExtraFiles

Used to copy all files and folders inside a folder named as "extra" inside your port folder, keeping their structure.

This is useful to add files in the dist version that you don't need to change their content dynamically at the build process.

Definition:

copyExtraFiles(portRootFolder: string, outputFolder: string = ''): Promise<void> {}

  • portRootFolder:
    The root folder where the "extra" folder lives.

  • outputFolder:
    The output folder where the files will be copied to, if not provided, the default port folder dist will be used: <root>/packages.

Example:

await copyExtraFiles(__dirname)

colorHandlers

  • tokenize


    Used to convert hex colors in a given string to Aura accent tokens.

    This is useful to convert the ports you are creating by hard coding the hex colors for testing to the tokenized port template version.

    Definition:

    tokenize(content: string): string {}
    • content:
      A string containing hex colors to be replaced to their respective Aura accent tokens.

    Example:

    tokenize(`"activityBar.activeBorder": "#a277ff",`)
// "activityBar.activeBorder": "{{ accent1 }}",

  • desaturate


    Decreases the intensity of a color. Its range is between 0 to 1. The first argument of the desaturate function is the amount by how much the color intensity should be decreased.

    Definition:

    desaturate(amount: string | number): (color: string) => string

    • amount:
      The value to be decreased.

    • color:
      The color to apply the desaturation.

    Example:

    const applyDesaturation = desaturate(0.2)

applyDesaturation('#CCCD64') // #b8b979

  • shade


    Shades a color by mixing it with black. shade can produce hue shifts, where as darken manipulates the luminance channel and therefore doesn't produce hue shifts.

    Definition:

    shade(percentage: string | number): (color: string) => string

    • percentage:
      The shade percentage

    • color:
      The color to apply the shade

    Example:

    const applyShade = shade(0.25)

applyShade('#00f') // #00003f

  • hexToRgb


    Used to convert a Hex value to RGB.

    Definition:

    hexToRgb(color: string): number[] {}
    • colors:
      The Hex value to be converted.

    Example:

    hexToRgb('#a277ff') // [162, 119, 255]

  • rgbToHex


    Used to convert a RGB value to Hex.

    Definition:

    rgbToHex(color: [number, number, number]): string {}
    • colors:
      The RGB array to be converted.

    Example:

    rgbToHex([162, 119, 255]) // #a277ff

  • schemeToRgb


    Used to convert the values of a hex color scheme to RGB.

    Definition:

    schemeToRgb(colors: Record<string, unknown>): Record<string, unknown> {}
    • colors:
      A hex color scheme object

    Example:

    schemeToRgb(colorSchemes.dark) // { accent1: [162, 119, 255], accent2: [97, 255, 202], ... }

  • schemeToTerminalRgb


    Used to convert the values of a hex color scheme to RGB scheme compatible with iTerm.

    Definition:

    schemeToTerminalRgb(colors: Record<string, unknown>): Record<string, unknown> {}
    • colors:
      A hex color scheme object

    Example:

    schemeToTerminalRgb(colorSchemes.dark)
/*{
  accent1_red: 0.6352941176470588,
  accent1_green: 0.4666666666666667,
  accent1_blue: 1,
  accent2_red: 0.3803921568627451,
  accent2_green: 1,
  accent2_blue: 0.792156862745098,
}*/

  • terminalConvertion

colorSchemes

getAllFiles

Used get all files from a root folder recursively.

Definition:

 getAllFiles(directory: string, files: string[] = []): Promise<string[]> {}

  • directory:
    The root directory to get all file paths.

  • files:
    Used to store the paths recursively, you don't need to pass it manually.

Example:

await getAllFiles('/path/to/folder')
// ['path/to/file1.ext', 'path/folder/to/file2.ext']

unlink

Used to remove files and folders recursively.

Definition:

 unlink(path: string): Promise<void> {}
  • path:
    A file or folder path to be removed.

Example:

await unlink('/path/to/file/or/folder')

getPathByPlatformInDev

Used to get a path in the provided object for the current platform in development.

If the platform doesn't exist in the provided object, an empty string will be returned.

Definition:

getPathByPlatformInDev(pathsPerPlatform: Record<string, string>): string {}
  • pathsPerPlatform:
    An object with paths per platform id and their values.

Example:

getPathByPlatformInDev({ darwin: '/some/path', linux: '/other/path' }) // '/some/path'

zip

  • addFile(path: string): void
  • writeZip(path: string): void
  • zipFolder(targetFolder: string, outputPath: string): Promise<void | Error>

toCamelCase

Used to transform a string to camel-case.

Definition:

toCamelCase(str: string, separator: string): string

  • str:
    A string to be converted to camel-case.

  • separator:
    The separator to be used to split the string and apply the camel-case transformation.

Example:

toCamelCase('aura-theme', '-') // 'auraTheme'

toPortName

Used to convert a string to a valid port name (PascalCase).

Definition:

toPortName(name: string): string {}
  • name:
    The name of the port separated by hiphens.

Example:

toPortName('aura-theme') // 'AuraTheme'

capitalizeFirstLetter

Used to capitalize only the first letter in a given text.

Definition:

capitalizeFirstLetter(rawText: string): string {}
  • rawText:
    A string to capitalize the first letter.

Example:

capitalizeFirstLetter('aura theme') // 'Aura theme'

constants

License

MIT © Dalton Menezes