@pulsar-edit/types 1.128.1

package/src/theme-manager.d.ts

@@ -0,0 +1,29 @@
+import { Disposable, Package } from "../index";
+
+/** Handles loading and activating available themes. */
+export interface ThemeManager {
+  // Event Subscription
+  /**
+   *  Invoke callback when style sheet changes associated with updating the
+   *  list of active themes have completed.
+   */
+  onDidChangeActiveThemes(callback: () => void): Disposable;
+
+  // Accessing Loaded Themes
+  /** Returns an Array of strings of all the loaded theme names. */
+  getLoadedThemeNames(): string[] | undefined;
+
+  /** Returns an Array of all the loaded themes. */
+  getLoadedThemes(): Package[] | undefined;
+
+  // Managing Enabled Themes
+  /** Returns an Array of strings all the active theme names. */
+  getActiveThemeNames(): string[] | undefined;
+
+  /** Returns an Array of all the active themes. */
+  getActiveThemes(): Package[] | undefined;
+
+  // Managing Enabled Themes
+  /** Get the enabled theme names from the config. */
+  getEnabledThemeNames(): string[];
+}

package/src/tooltip-manager.d.ts

@@ -0,0 +1,42 @@
+import { Disposable, Tooltip } from "../index";
+
+export type TooltipPlacement =
+  | "top"
+  | "bottom"
+  | "left"
+  | "right"
+  | "auto"
+  | "auto top"
+  | "auto bottom"
+  | "auto left"
+  | "auto right";
+
+/** Associates tooltips with HTML elements or selectors. */
+export interface TooltipManager {
+  /** Add a tooltip to the given element. */
+  add(
+    target: HTMLElement | JQueryCompatible,
+    options:
+      | {
+        item?: object | undefined;
+      }
+      | ({
+        title?: string | (() => string) | undefined;
+        html?: boolean | undefined;
+        keyBindingCommand?: string | undefined;
+        keyBindingTarget?: HTMLElement | undefined;
+      } & {
+        class?: string | undefined;
+        placement?: TooltipPlacement | (() => TooltipPlacement) | undefined;
+        trigger?: "click" | "hover" | "focus" | "manual" | undefined;
+        delay?: { show: number; hide: number } | undefined;
+      }),
+  ): Disposable;
+
+  /** Find the tooltips that have been applied to the given element. */
+  findTooltips(target: HTMLElement): Tooltip[];
+}
+
+export interface JQueryCompatible<Element extends Node = HTMLElement> extends Iterable<Element> {
+  jquery: string;
+}

package/src/tooltip.d.ts

@@ -0,0 +1,63 @@
+/**
+ *  This tooltip class is derived from Bootstrap 3, but modified to not require
+ *  jQuery, which is an expensive dependency we want to eliminate.
+ */
+export interface Tooltip {
+  readonly options: TooltipOptions;
+  readonly enabled: boolean;
+  readonly timeout: number;
+  readonly hoverState: "in" | "out" | null;
+  readonly element: HTMLElement;
+
+  getTitle(): string;
+  getTooltipElement(): HTMLElement;
+  getArrowElement(): HTMLElement;
+  enable(): void;
+  disable(): void;
+  toggleEnabled(): void;
+  toggle(): void;
+  recalculatePosition(): void;
+}
+
+/** The options for a Bootstrap 3 Tooltip class, which Atom uses a variant of. */
+export interface TooltipOptions {
+  /** Apply a CSS fade transition to the tooltip. */
+  animation?: boolean | undefined;
+
+  /** Appends the tooltip to a specific element. */
+  container?: string | HTMLElement | false | undefined;
+
+  /**
+   *  Delay showing and hiding the tooltip (ms) - does not apply to manual
+   *  trigger type.
+   */
+  delay?: number | { show: number; hide: number } | undefined;
+
+  /** Allow HTML in the tooltip. */
+  html?: boolean | undefined;
+
+  /** How to position the tooltip. */
+  placement?: "top" | "bottom" | "left" | "right" | "auto" | undefined;
+
+  /**
+   *  If a selector is provided, tooltip objects will be delegated to the
+   *  specified targets.
+   */
+  selector?: string | undefined;
+
+  /** Base HTML to use when creating the tooltip. */
+  template?: string | undefined;
+
+  /**
+   *  Default title value if title attribute isn't present.
+   *  If a function is given, it will be called with its this reference set to
+   *  the element that the tooltip is attached to.
+   */
+  title?: string | HTMLElement | (() => string) | undefined;
+
+  /**
+   *  How tooltip is triggered - click | hover | focus | manual.
+   *  You may pass multiple triggers; separate them with a space.
+   */
+  trigger?: string | undefined;
+}

package/src/ui.d.ts

@@ -0,0 +1,101 @@
+import { Grammar } from '../index';
+
+type MarkdownRenderOptions = {
+  renderMode?: 'full' | 'fragment',
+  html?: boolean,
+  sanitize?: boolean,
+  sanitizeAllowUnknownProtocols?: boolean,
+  sanitizeAllowSelfClose?: boolean,
+  breaks?: boolean,
+  handleFrontMatter?: boolean,
+  useDefaultEmoji?: boolean,
+  useGitHubHeadings?: boolean,
+  useTaskCheckbox?: boolean,
+  taskCheckboxDisabled?: boolean,
+  taskCheckboxDivWrap?: boolean,
+  transformImageLinks?: boolean,
+  transformAtomLinks?: boolean,
+  transformNonFqdnLinks?: boolean,
+  rootDomain?: string,
+  filePath?: string,
+  disableMode?: 'none' | 'strict'
+}
+
+type ApplySyntaxHighlightingOptions = {
+  syntaxScopeNameFunc?: (id: string) => string,
+  renderMode?: 'full'| 'fragment',
+  grammar?: Grammar
+};
+
+type MatcherOptions = {
+  numThreads?: number
+  algorithm?: 'fuzzaldrin' | 'command-t'
+  maxResults?: number
+  recordMatchIndexes?: boolean
+  maxGap: number
+}
+
+type MatchResult = {
+  id: number
+  value: string
+  score: number
+  matchIndexes?: number[]
+}
+
+interface Matcher {
+  numCpus: number;
+  match(query: string, options: MatcherOptions): MatchResult;
+  setCandidates(candidates: string[]): void;
+}
+
+interface Markdown {
+  /**
+   * Render a Markdown document as HTML.
+   */
+  render(content: string, options?: MarkdownRenderOptions): string;
+
+  /**
+   * Apply Pulsar's built-in syntax highlighting system to code blocks within
+   * Markdown. Modifies the given `DocumentFragment`.
+   */
+  applySyntaxHighlighting(
+    content: DocumentFragment,
+    options?: ApplySyntaxHighlightingOptions
+  ): Promise<HTMLElement>;
+
+  /**
+   * Convert a string of HTML into a `DocumentFragment`.
+   */
+  convertToDOM(content: string): DocumentFragment;
+}
+
+interface FuzzyMatcher {
+  setCandidates(candidates: string[]): Matcher;
+  setCandidates(matcher: Matcher, candidates: string[]): Matcher;
+
+  score(candidate: string, query: string, options?: MatcherOptions): number;
+  match(candidate: string, query: string, options?: MatcherOptions): MatchResult;
+}
+
+export interface UI {
+  /**
+   * Utility methods for converting Markdown to HTML.
+   */
+  markdown: Markdown,
+
+  /**
+   * The fuzzy-matcher API – just like the one used in `autocomplete-plus`,
+   * the command palette, etc.
+   *
+   * This API filters and scores a list of candidates based on what the user
+   * has typed. Scoring is done by the particular algorithm of the configured
+   * fuzzy-matching library. Filtering is done by returning a new
+   * {@link Matcher} using {@link Matcher#setCandidates}, then calling
+   * {@link Matcher#match}.
+   *
+   * You may also use {@link UI.fuzzyMatcher}’s `match` method to match a
+   * single candidate; it uses the same API and options as
+   * {@link Matcher#match}.
+   */
+  fuzzyMatcher: FuzzyMatcher
+}

package/src/view-registry.d.ts

@@ -0,0 +1,34 @@
+import { Disposable, TextEditor, TextEditorElement } from "../index";
+
+/**
+ * Handles the association between model and view types in Atom. We call this
+ * association a _view provider_.
+ *
+ * In other words: for a given model, this class can provide a view via
+ * {@link getView}, as long as the model/view association was registered via
+ * {@link addViewProvider}.
+ */
+export interface ViewRegistry {
+  /**
+   * Add a provider that will be used to construct views in the workspace's
+   * view layer based on model objects in its model layer.
+   */
+  addViewProvider(createView: (model: object) => HTMLElement | undefined): Disposable;
+  /**
+   * Add a provider that will be used to construct views in the workspace's
+   * view layer based on model objects in its model layer.
+   */
+  // tslint:disable-next-line:no-any
+  addViewProvider<T>(
+    modelConstructor: { new(...args: any[]): T }, // tslint:disable-line no-any
+    createView: (instance: T) => HTMLElement | undefined,
+  ): Disposable;
+
+  /** Get the view associated with an object in the workspace. */
+  getView(obj: TextEditor): TextEditorElement;
+  getView(obj: object): HTMLElement;
+}
+
+export interface ViewModel {
+  getTitle: () => string;
+}

package/src/wasm-tree-sitter-grammar.d.ts

@@ -0,0 +1,305 @@
+import {
+  Disposable,
+  Grammar,
+  GrammarRegistry,
+  GrammarToken,
+  Range,
+  TextBuffer,
+  TokenizeLineResult
+} from '../index';
+import type { Language, Node, Query } from 'web-tree-sitter';
+
+/**
+ * An object with properties that describe the comment delimiters of a given
+ * language.
+ */
+export type CommentDelimiterSpec = {
+  /**
+   * If present, a delimiter to be used for line comments. (If missing, the
+   * language does not support line comments.)
+   */
+  line?: string,
+  /**
+   * If present, a two-item tuple representing the starting and ending
+   * delimiters of block comments. (If missing, the language does not support
+   * block comments.)
+   */
+  block?: [string, string]
+}
+
+/** A "standard" type of query used by Pulsar. */
+type StandardQueryType =
+  | 'highlightsQuery'
+  | 'foldsQuery'
+  | 'tagsQuery'
+  | 'indentsQuery'
+
+/**
+ * An arbitrary query name that can be used by a community package.
+ */
+type CustomQueryType = string;
+
+type DidChangeQueryPayload = {
+  filePath: string,
+  queryType: StandardQueryType | CustomQueryType
+}
+
+type LanguageScopeFunction = (
+  grammar: WASMTreeSitterGrammar,
+  buffer: TextBuffer,
+  range: Range
+) => string | null
+
+export type InjectionPoint = {
+  /** The name of the syntax node that may embed other languages. */
+  type: string,
+  /**
+   * A function that is called with syntax nodes of the specified type. Can
+   * return a string that will be tested against grammars' `injectionRegex`
+   * properties in order to match this injection point to a given language.
+   *
+   * If this callback returns `undefined` or `null`, the injection will fail.
+   */
+  language(node: Node): string | undefined,
+  /**
+   * A function that is called with syntax nodes of the specified type. Should
+   * return a {@link Node} (or an array of {@link Node}s) to identify the exact
+   * range or ranges that should be highlighted.
+   *
+   * Depending on other settings, the ranges described by the return value may
+   * be modified further. When the injected language parses this file, only
+   * the content within these buffer ranges will be "visible" to the parser.
+   *
+   * If this callback returns `undefined` or `null`, the injection will fail.
+   */
+  content(node: Node): Node | Node[] | undefined,
+
+  /**
+   * Whether the children of nodes returned by `content` should be included
+   * in the injection range. Defaults to `false`, meaning that for every node
+   * returned by the `content` function, the ranges of all that node's children
+   * will be "subtracted" from the injection range.
+   *
+   * When `true`, the full content ranges of all nodes returned from the
+   * `content` callback will be part of the injection content range.
+   */
+  includeChildren?: boolean,
+
+  /**
+  * Whether the injection ranges should include any newline characters that
+  * may exist in between injection ranges. Defaults to `false`.
+  *
+  * Grammars like ERB and EJS need this so that they do not interpret two
+  * different embedded code sections on different lines as occurring on the
+  * same line.
+   */
+  newlinesBetween?: boolean,
+
+  /**
+   * A string or function that returns the desired root scope name to apply to
+   * each of the injection's buffer ranges. Defaults to the injected grammar's
+   * own root language scope — e.g., `source.js` for the JavaScript grammar.
+   *
+   * Set to `null` if the language scope should be omitted.
+   *
+   * If a function, will be called with the {@link WASMTreeSitterGrammar}
+   * instance, the {@link TextBuffer}, and the given buffer {@link Range}, and
+   * should return either a string or `null`.
+   */
+  languageScope?: string | null | LanguageScopeFunction,
+
+  /**
+   * Whether this injection should prevent shallower layers (including the
+   * layer that created this injection) from adding scopes within any of this
+   * injection's buffer ranges. Useful for injecting languages into themselves
+   * — for instance, injecting Rust into Rust macro definitions. Defaults to
+   * `false`.
+   */
+  coverShallowerScopes?: boolean,
+
+  /**
+   * Whether the injection's buffer ranges should include whitespace that
+   * occurs between two ranges that are separated only by whitespace. Defaults
+   * to `false`. If `true`, such ranges will be consolidated into a single
+   * range along with the whitespace that separates them.
+   */
+  includeAdjacentWhitespace?: boolean
+}
+
+type TreeSitterParams = {
+  grammar: string
+  highlightsQuery?: string
+  foldsQuery?: string
+  tagsQuery?: string
+  indentsQuery?: string
+  languageSegment?: string
+}
+
+type WASMTreeSitterGrammarParams = {
+  name: string;
+  scopeName: string;
+  contentRegex?: string | string[]
+  firstLineRegex?: string | string[]
+  treeSitter: TreeSitterParams,
+  comments?: {
+    start?: string,
+    end?: string
+  }
+}
+
+/**
+ *  A grammar responsible for language-specific features like syntax
+ *  highlighting, indentation, and code folding. Uses Tree-sitter as its parsing
+ *  system.
+ */
+export interface WASMTreeSitterGrammar extends Grammar {
+  /** The name of the grammar. */
+  readonly name: string;
+
+  /** Undocumented: Root scope name of the grammar. */
+  readonly scopeName: string;
+
+  constructor(
+    registry: GrammarRegistry,
+    grammarPath: string,
+    params: WASMTreeSitterGrammarParams
+  );
+
+  // Callbacks
+  onDidUpdate(callback: () => void): Disposable;
+
+  /**
+   * Calls `callback` when any of this grammar’s queries change.
+   *
+   * A grammar’s queries typically will not change after initial load. When
+   * they do, it may mean:
+   *
+   * - The user is editing query files in dev mode; Pulsar will automatically
+   *   reload queries in dev mode after changes.
+   * - A community packge is altering a query file via an API like
+   *   {@link setQueryForTest}.
+   */
+  onDidChangeQuery(callback: (payload: DidChangeQueryPayload) => void): Disposable;
+  onDidChangeQueryFile(callback: (payload: DidChangeQueryPayload) => void): Disposable;
+
+  /**
+   * Calls `callback` when this grammar first loads its query files.
+   */
+  onDidLoadQueryFiles(callback: () => void): Disposable;
+
+  /**
+   * Undocumented: Adds an injection point by which this language can inject
+   * another language during parsing.
+   *
+   * Do not call this directly; prefer {@link GrammarRegistry#addInjectionPoint}.
+   */
+  addInjectionPoint(injectionPoint: InjectionPoint): void;
+
+  /**
+   * Undocumented: Removes an injection point that was previously added.
+   *
+   * Do not call this directly; instead, use
+   * {@link GrammarRegistry#addInjectionPoint} to add the injection point, then
+   * retain the returned {@link Disposable} so you can use it to remove the
+   * injection point you added.
+   */
+  removeInjectionPoint(injectionPoint: InjectionPoint): void;
+
+
+  /**
+   * Retrieve all known comment delimiters for this grammar.
+   *
+   * Some grammars may have different delimiters for different parts of a file
+   * (for example, JSX within JavaScript). In these cases, you might instead
+   * want to call {@link TextEditor#getCommentDelimitersForBufferPosition}
+   * with a {@link Point} that represents a buffer position.
+   */
+  getCommentDelimiters(): CommentDelimiterSpec;
+
+  /**
+   * Retrieves the Tree-sitter `Language` instance associated with this
+   * grammar.
+   */
+  getLanguage(): Promise<Language>
+
+  /**
+   * Synchronously retrieves the Tree-sitter `Language` instance associated
+   * with this grammar, or `null` if the `Language` has not yet been loaded.
+   */
+  getLanguageSync(): Language | null
+
+  /**
+   * Retrieve a `Query` instance by name. Asynchronous.
+   */
+  getQuery(queryType: StandardQueryType | CustomQueryType): Promise<Query>
+
+  /**
+   * Retrieve a `Query` instance by name.
+   *
+   * Synchronous. Returns `null` if the language itself has not yet loaded.
+   */
+  getQuerySync(queryType: StandardQueryType | CustomQueryType): Query | null
+
+  /**
+   * Creates an arbitrary Tree-sitter `Query` instance from this grammar’s
+   * `Language`.
+   *
+   * Package authors and end users can use queries for whatever purpose they
+   * like.
+   */
+  createQuery(queryContents: string): Promise<Query>
+
+  /**
+   * Creates an arbitrary Tree-sitter `Query` instance from this grammar’s
+   * `Language`.
+   *
+   * Package authors and end users can use queries for whatever purpose they
+   * like.
+   *
+   * Synchronous; throws an error if the grammar’s `Language` is not yet
+   * loaded.
+   */
+  createQuerySync(queryContents: string): Query
+
+  /**
+   * Sets the contents of standard or custom query type.
+   *
+   * Used by the specs to override a particular query for testing purposes.
+   */
+  setQueryForTest(
+    queryType: StandardQueryType | CustomQueryType,
+    contents: string
+  ): Promise<Query>;
+
+  /**
+   * Tokenize all lines in the given text.
+   *
+   * @param text A string containing one or more lines.
+   * @return An array of token arrays for each line tokenized.
+   */
+  tokenizeLines(text: string): GrammarToken[][];
+
+  /**
+   * Tokenize the line of text.
+   *
+   * @param line A string of text to tokenize.
+   * @param ruleStack An optional array of rules previously returned from this
+   *   method. This should be null when tokenizing the first line in the file.
+   * @param firstLine A optional boolean denoting whether this is the first
+   *   line in the file which defaults to `false`.
+   * @return An object representing the result of the tokenize.
+   */
+  tokenizeLine(line: string, ruleStack?: null, firstLine?: boolean): TokenizeLineResult;
+
+  /**
+   * Tokenize the line of text.
+   *
+   * @param line A string of text to tokenize.
+   * @param ruleStack An optional array of rules previously returned from this
+   *   method. This should be null when tokenizing the first line in the file.
+   * @param firstLine A optional boolean denoting whether this is the first
+   *   line in the file which defaults to `false`.
+   * @return An object representing the result of the tokenize.
+   */
+  tokenizeLine(line: string, ruleStack: any[], firstLine?: false): TokenizeLineResult;
+}