roamjs-components 0.85.1 → 1.0.0-beta.1

package/.eslintrc.json

@@ -0,0 +1,19 @@
+{
+  "root": true,
+  "parser": "@typescript-eslint/parser",
+  "plugins": ["@typescript-eslint"],
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/eslint-recommended",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "ignorePatterns": "**/dist/*",
+  "rules": {
+    "@typescript-eslint/no-unused-vars": [
+      "error",
+      { "argsIgnorePattern": "_+" }
+    ],
+    "@typescript-eslint/no-empty-function": 0,
+    "no-control-regex": 0
+  }
+}

package/.github/workflows/main.yaml

@@ -0,0 +1,34 @@
+name: Publish package
+on:
+  workflow_dispatch:
+  push:
+    branches: main
+    paths:
+      - "package.json"
+      - ".github/workflows/main.yaml"
+
+env:
+  ROAMJS_DEVELOPER_TOKEN: ${{ secrets.ROAMJS_DEVELOPER_TOKEN }}
+  ROAMJS_TEST_DEVELOPER_TOKEN: ${{ secrets.ROAMJS_TEST_DEVELOPER_TOKEN }}
+  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+jobs:
+  deploy:
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v3
+      - name: install
+        run: npm install
+      - name: authenticate
+        run: echo '//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}' > ~/.npmrc
+      - name: lint
+        run: npm run lint
+      - name: build
+        run: npx tsc
+      # - name: test
+      #   run: npm t
+      - name: prepare
+        run: cp LICENSE README.md package.json dist
+      - name: publish
+        run: npm publish --access public
+        working-directory: dist

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2021 David Vargas
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2021 David Vargas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,29 +1,29 @@
-# roamjs-components
-
-This is a collection of common UI components used by RoamJS extensions made available to make development easier for other Roam developers.
-
-The `roamjs-components` repository provides a robust set of tools and components for building extensions and integrations for the Roam Research note-taking application. Engineers can use this repo to streamline the development of Roam extensions by leveraging pre-built React components, utility functions, and custom hooks that interact with the Roam Research API. This repo addresses the real-world problem of efficiently creating and managing Roam Research extensions, enabling developers to focus on building unique features rather than handling boilerplate code.
-
-The most important parts of the repo include the Components, utility functions, and database query functions. These components are organized into several directories, each serving a specific purpose:
-
-[Components](https://github.com/RoamJS/roamjs-components/blob/main/docs/components.md): Found in the `…/components` directory, these components handle tasks such as configuration management, external authentication, and data visualization. Key components include configuration panels like `BlockPanel`, `BlocksPanel`, and `OauthPanel`, which are detailed in the Configuration Panels section. These components use React hooks and context to manage state and interactions within the Roam Research application.
-
-[Date and Time Utilities](https://github.com/RoamJS/roamjs-components/blob/main/docs/date.md): Located in `…/date`, this directory provides functions for parsing and manipulating dates, crucial for working with Roam's daily notes. The `parseNlpDate` function uses the `chrono-node` library to parse natural language dates, while `parseRoamDateUid` converts Roam date UIDs into JavaScript Date objects. More details can be found in the Date and Time Utilities section.
-
-[DOM Manipulation](https://github.com/RoamJS/roamjs-components/blob/main/docs/dom.md): The `…/dom` directory contains functions for interacting with the Document Object Model (DOM) within Roam Research. Functions like `addBlockCommand` and `createBlockObserver` are essential for adding new commands and observing changes in the DOM. These utilities are explained in the DOM Manipulation section.
-
-[Event Handling](https://github.com/RoamJS/roamjs-components/blob/main/docs/events.md): The `…/events` directory includes the `watchOnce` function, which sets up one-time event listeners in Roam Research. This function is useful for performing actions when specific changes occur in the Roam environment, as detailed in the Event Handling section.
-
-[Custom React Hooks](https://github.com/RoamJS/roamjs-components/blob/main/docs/hooks.md): Found in `…/hooks`, these hooks provide reusable functionality for managing user interactions and data structures. The `useArrowKeyDown` hook handles keyboard navigation within lists, while `useSubTree` manages sub-tree data structures. More information is available in the Custom React Hooks section.
-
-[Markdown Parsing and Rendering](https://github.com/RoamJS/roamjs-components/blob/main/docs/marked.md): The `…/marked` directory customizes the `marked` library to parse and render Markdown content within Roam Research. This includes handling Roam-specific elements like block references and tags. The Markdown Parsing and Rendering section provides further details.
-
-[Database Queries](https://github.com/RoamJS/roamjs-components/blob/main/docs/queries.md): The `…/queries` directory offers utility functions for interacting with the Roam Research database. Functions like `getAllBlockUids`, `getPageTitleByBlockUid`, and `getCurrentUser` retrieve various types of data from the database. These functions are crucial for building data-driven features and are discussed in the Database Queries section.
-
-[Script Management](https://github.com/RoamJS/roamjs-components/blob/main/docs/scripts.md): The `…/scripts` directory includes functions for managing scripts in Roam Research. This includes functions for creating and managing script commands, as well as functions for executing scripts.
-
-[Type Definitions](https://github.com/RoamJS/roamjs-components/blob/main/docs/types.md): The `…/types` directory contains TypeScript type definitions for various Roam Research components.
-
-[Utility Functions](https://github.com/RoamJS/roamjs-components/blob/main/docs/util.md): The `…/util` directory includes utility functions for working with the Roam Research API. These functions are designed to simplify the process of interacting with the API.
-
-[Write Operations](https://github.com/RoamJS/roamjs-components/blob/main/docs/writes.md): The `…/writes` directory includes functions for performing write operations in Roam, such as `createBlock`, `deleteBlock`, and `updateActiveBlock`. These functions handle the submission of actions to the Roam API, as detailed in the Write Operations section.
+# roamjs-components
+
+This is a collection of common UI components used by RoamJS extensions made available to make development easier for other Roam developers.
+
+The `roamjs-components` repository provides a robust set of tools and components for building extensions and integrations for the Roam Research note-taking application. Engineers can use this repo to streamline the development of Roam extensions by leveraging pre-built React components, utility functions, and custom hooks that interact with the Roam Research API. This repo addresses the real-world problem of efficiently creating and managing Roam Research extensions, enabling developers to focus on building unique features rather than handling boilerplate code.
+
+The most important parts of the repo include the Components, utility functions, and database query functions. These components are organized into several directories, each serving a specific purpose:
+
+[Components](https://github.com/RoamJS/roamjs-components/blob/main/docs/components.md): Found in the `…/components` directory, these components handle tasks such as configuration management, external authentication, and data visualization. Key components include configuration panels like `BlockPanel`, `BlocksPanel`, and `OauthPanel`, which are detailed in the Configuration Panels section. These components use React hooks and context to manage state and interactions within the Roam Research application.
+
+[Date and Time Utilities](https://github.com/RoamJS/roamjs-components/blob/main/docs/date.md): Located in `…/date`, this directory provides functions for parsing and manipulating dates, crucial for working with Roam's daily notes. The `parseNlpDate` function uses the `chrono-node` library to parse natural language dates, while `parseRoamDateUid` converts Roam date UIDs into JavaScript Date objects. More details can be found in the Date and Time Utilities section.
+
+[DOM Manipulation](https://github.com/RoamJS/roamjs-components/blob/main/docs/dom.md): The `…/dom` directory contains functions for interacting with the Document Object Model (DOM) within Roam Research. Functions like `addBlockCommand` and `createBlockObserver` are essential for adding new commands and observing changes in the DOM. These utilities are explained in the DOM Manipulation section.
+
+[Event Handling](https://github.com/RoamJS/roamjs-components/blob/main/docs/events.md): The `…/events` directory includes the `watchOnce` function, which sets up one-time event listeners in Roam Research. This function is useful for performing actions when specific changes occur in the Roam environment, as detailed in the Event Handling section.
+
+[Custom React Hooks](https://github.com/RoamJS/roamjs-components/blob/main/docs/hooks.md): Found in `…/hooks`, these hooks provide reusable functionality for managing user interactions and data structures. The `useArrowKeyDown` hook handles keyboard navigation within lists, while `useSubTree` manages sub-tree data structures. More information is available in the Custom React Hooks section.
+
+[Markdown Parsing and Rendering](https://github.com/RoamJS/roamjs-components/blob/main/docs/marked.md): The `…/marked` directory customizes the `marked` library to parse and render Markdown content within Roam Research. This includes handling Roam-specific elements like block references and tags. The Markdown Parsing and Rendering section provides further details.
+
+[Database Queries](https://github.com/RoamJS/roamjs-components/blob/main/docs/queries.md): The `…/queries` directory offers utility functions for interacting with the Roam Research database. Functions like `getAllBlockUids`, `getPageTitleByBlockUid`, and `getCurrentUser` retrieve various types of data from the database. These functions are crucial for building data-driven features and are discussed in the Database Queries section.
+
+[Script Management](https://github.com/RoamJS/roamjs-components/blob/main/docs/scripts.md): The `…/scripts` directory includes functions for managing scripts in Roam Research. This includes functions for creating and managing script commands, as well as functions for executing scripts.
+
+[Type Definitions](https://github.com/RoamJS/roamjs-components/blob/main/docs/types.md): The `…/types` directory contains TypeScript type definitions for various Roam Research components.
+
+[Utility Functions](https://github.com/RoamJS/roamjs-components/blob/main/docs/util.md): The `…/util` directory includes utility functions for working with the Roam Research API. These functions are designed to simplify the process of interacting with the API.
+
+[Write Operations](https://github.com/RoamJS/roamjs-components/blob/main/docs/writes.md): The `…/writes` directory includes functions for performing write operations in Roam, such as `createBlock`, `deleteBlock`, and `updateActiveBlock`. These functions handle the submission of actions to the Roam API, as detailed in the Write Operations section.

package/docs/components.md

@@ -0,0 +1,32 @@
+# Components
+
+https://github.com/RoamJS/roamjs-components/tree/main/src/components
+
+React components in this codebase provide various functionalities for the Roam Research application, focusing on configuration management, external authentication, user interface elements, and data visualization.
+
+## Configuration Panels
+
+Configuration panels are managed by components located in `https://github.com/RoamJS/roamjs-components/blob/main/src/components/ConfigPanels`. These components handle various input types such as text, number, time, and selection fields, as well as external authentication. The panels are designed to be modular and reusable, allowing for easy integration and customization within the Roam Research application.
+
+[See More](https://wiki.mutable.ai/RoamJS/roamjs-components#configuration-panels)
+
+## Extension API Context
+
+The [`ExtensionApiContext`](https://github.com/RoamJS/roamjs-components/blob/main/src/components/ExtensionApiContext.tsx#L5) component, found in `https://github.com/RoamJS/roamjs-components/blob/main/src/components/ExtensionApiContext.tsx`, provides a React context for managing the extension API and version information. It exports two custom hooks, [`useExtensionAPI()`](https://github.com/RoamJS/roamjs-components/blob/main/src/components/ExtensionApiContext.tsx#L9) and [`useVersion()`](https://github.com/RoamJS/roamjs-components/blob/main/src/components/ExtensionApiContext.tsx#L11), which allow components to access the extension API and version information, respectively. The [`ExtensionApiContextProvider`](https://github.com/RoamJS/roamjs-components/blob/main/src/util/renderWithUnmount.ts#L3) component wraps the application to provide the necessary context.
+
+[See More](https://wiki.mutable.ai/RoamJS/roamjs-components#extension-api-context)
+
+## Additional Components
+
+- **AutocompleteInput**: Provides an autocomplete input field with fuzzy string matching and customizable options.
+- **BlockErrorBoundary**: A React error boundary that handles errors within a specific block of content.
+- **Loading**: Renders a small loading spinner component and a function to display it in a specific location on the page.
+- **PageLink**: Renders a link to a Roam Research page, handling various user interactions such as opening the page in the sidebar.
+- **MenuItemSelect**: Provides a dropdown menu with selectable items, supporting filtering and custom rendering of menu items.
+- **ExternalLogin**: Handles the authentication flow for various external services and integrates the authentication data into a Roam Research note.
+- **FormDialog**: Provides a reusable dialog box with various input fields for collecting user data.
+- **ProgressDialog**: Displays a progress dialog showing the progress of writing actions to Roam and providing an estimated time for completion.
+- **SimpleAlert**: Renders a customizable alert dialog with options for confirmation, cancellation, and a "Don't show again" checkbox.
+- **Description**: Displays a tooltip with a description text when the user hovers over an information icon.
+
+[See More](https://wiki.mutable.ai/RoamJS/roamjs-components#utility-components)

package/docs/date.md

@@ -0,0 +1,13 @@
+# Date and Time Utilities
+
+https://github.com/RoamJS/roamjs-components/blob/main/src/date
+
+Utilities for parsing and manipulating dates and times within the Roam Research application are provided in the `https://github.com/RoamJS/roamjs-components/blob/main/src/date` directory. Key functionalities include:
+
+- **Natural Language Date Parsing**: The [`parseNlpDate`](https://github.com/RoamJS/roamjs-components/blob/main/src/date/parseNlpDate.ts#L250) function leverages the [`chrono-node`](/roamjs-components/package.json#L32) library to interpret natural language dates (e.g., "yesterday", "next Monday"). Custom parsing and refinement logic enhance its robustness. The [`startOfWeek`](https://github.com/RoamJS/roamjs-components/blob/main/src/date/parseNlpDate.ts#L13), [`endOfWeek`](https://github.com/RoamJS/roamjs-components/blob/main/src/date/parseNlpDate.ts#L21), [`startOfMonth`](https://github.com/RoamJS/roamjs-components/blob/main/src/date/parseNlpDate.ts#L211), [`endOfMonth`](/roamjs-components/tests/date.test.ts#L14), [`startOfYear`](https://github.com/RoamJS/roamjs-components/blob/main/src/date/parseNlpDate.ts#L224), and [`endOfYear`](https://github.com/RoamJS/roamjs-components/blob/main/src/date/parseNlpDate.ts#L8) functions from [`date-fns`](https://github.com/RoamJS/roamjs-components/blob/main/src/date/parseNlpDate.ts#L1) determine the start and end of various periods. The [`ORDINAL_WORD_DICTIONARY`](https://github.com/RoamJS/roamjs-components/blob/main/src/date/parseNlpDate.ts#L29) and [`ORDINAL_REGEX`](https://github.com/RoamJS/roamjs-components/blob/main/src/date/parseNlpDate.ts#L73) assist in parsing ordinal words and numbers. The [`assignDay`](https://github.com/RoamJS/roamjs-components/blob/main/src/date/parseNlpDate.ts#L159) function assigns year, month, and day components to a [`ParsingComponents`](https://github.com/RoamJS/roamjs-components/blob/main/src/date/parseNlpDate.ts#L10) object.
+
+- **Roam Date UID Parsing**: The [`parseRoamDateUid`](https://github.com/RoamJS/roamjs-components/blob/main/src/date/parseRoamDateUid.ts#L1) function converts Roam Research date UIDs (formatted as "month-date-year") into JavaScript [`Date`](https://github.com/RoamJS/roamjs-components/blob/main/src/types/index.ts#L98) objects. It splits the input string, converts the components to numbers, and constructs a [`Date`](https://github.com/RoamJS/roamjs-components/blob/main/src/types/index.ts#L98) object, adjusting the month value to match JavaScript's zero-indexed months.
+
+- **Constants**: The [`constants.ts`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/constants.ts#L0) file provides constants like [`MONTHS`](https://github.com/RoamJS/roamjs-components/blob/main/src/date/constants.ts#L1), an array of month names, and regular expressions ([`DAILY_NOTE_PAGE_REGEX`](https://github.com/RoamJS/roamjs-components/blob/main/src/date/constants.ts#L15) and [`DAILY_NOTE_PAGE_TITLE_REGEX`](https://github.com/RoamJS/roamjs-components/blob/main/src/date/constants.ts#L17)) for matching and validating daily note page titles in Roam Research.
+
+For detailed discussions on constants and parsing functions, refer to the subsections [Constants](https://wiki.mutable.ai/RoamJS/roamjs-components#constants) and [Date Parsing](https://wiki.mutable.ai/RoamJS/roamjs-components#date-parsing).

package/docs/dom.md

@@ -0,0 +1,58 @@
+# DOM Manipulation
+
+https://github.com/RoamJS/roamjs-components/blob/main/src/dom
+
+The `https://github.com/RoamJS/roamjs-components/blob/main/src/dom` directory contains utility functions and constants for interacting with the Document Object Model (DOM) in the context of Roam Research. These utilities facilitate various operations, including adding commands, observing DOM changes, retrieving data, generating URLs, and parsing block content.
+
+## Adding Block Commands and Script Dependencies
+
+Functions like [`addBlockCommand`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/addBlockCommand.ts#L11) allow developers to add new block commands to the Roam Research UI. Script dependencies can be managed using [`addOldRoamJSDependency`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/addOldRoamJSDependency.ts#L3) and [`addRoamJSDependency`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/addRoamJSDependency.ts#L3). These functions ensure that necessary scripts are loaded into the application.
+
+[See More](https://wiki.mutable.ai/RoamJS/roamjs-components#adding-block-commands-and-script-dependencies)
+
+## DOM Observation and Manipulation
+
+Utilities such as [`createBlockObserver`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/createBlockObserver.ts#L3) and [`createHTMLObserver`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/createHTMLObserver.ts#L4) enable observing changes in the DOM. These functions use [`MutationObserver`](https://github.com/RoamJS/roamjs-components/blob/main/src/types/index.ts#L25) to monitor specific elements and execute callbacks when changes occur. For example, [`createBlockObserver`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/createBlockObserver.ts#L3) observes changes to Roam blocks, while [`createHTMLObserver`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/createHTMLObserver.ts#L4) can be configured to watch for any HTML element with a specific tag and class.
+
+[See More](https://wiki.mutable.ai/RoamJS/roamjs-components#dom-observation-and-manipulation)
+
+## Retrieving and Manipulating Roam-Specific Data
+
+Functions like [`getCurrentPageUid`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/getCurrentPageUid.ts#L1), [`getBlockUidFromTarget`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/getBlockUidFromTarget.ts#L5), and [`getUids`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/getUids.ts#L3) are used to retrieve unique identifiers (UIDs) for pages and blocks within Roam Research. These UIDs are essential for various operations, such as linking to specific blocks or pages.
+
+[See More](https://wiki.mutable.ai/RoamJS/roamjs-components#retrieving-and-manipulating-roamspecific-data)
+
+## URL Generation and Reference Resolution
+
+The [`getRoamUrl`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/getRoamUrl.ts#L1) and [`getRoamUrlByPage`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/getRoamUrlByPage.ts#L4) functions generate URLs for Roam Research pages and blocks. The [`resolveRefs`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/resolveRefs.ts#L16) function processes text strings to resolve references, such as alias tags and block references, into their corresponding URLs or text content.
+
+[See More](https://wiki.mutable.ai/RoamJS/roamjs-components#url-generation-and-reference-resolution)
+
+## Parsing Roam Block Content
+
+The [`parseRoamBlocksToHtml`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/parseRoamBlocksToHtml.ts#L111) function converts Roam block content into HTML. This is useful for rendering Roam content in different contexts, such as exporting notes or displaying them in custom views.
+
+[See More](https://wiki.mutable.ai/RoamJS/roamjs-components#parsing-roam-block-content)
+
+## Constants
+
+The [`BLOCK_REF_REGEX`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L42) constant, defined in `https://github.com/RoamJS/roamjs-components/blob/main/src/dom/constants.ts`, is a regular expression used to match block references in Roam Research. This regex is critical for identifying and manipulating block references within the application.
+
+## Utility Functions
+
+- **[`getUidsFromId`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/getUidsFromId.ts#L1)**: Extracts [`blockUid`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/getUidsFromId.ts#L3) and [`windowId`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/getUidsFromId.ts#L5) from an [`id`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L454) string.
+- **[`getPageTitleValueByHtmlElement`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/getPageTitleValueByHtmlElement.ts#L4)**: Retrieves the page title value associated with an HTML element.
+- **[`getReferenceBlockUid`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/getReferenceBlockUid.ts#L5)**: Retrieves the UID of a reference block based on an HTML element.
+- **[`addScriptAsDependency`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/addScriptAsDependency.ts#L1)**: Adds a script tag to the document's head, ensuring it is only added once.
+- **[`createIconButton`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/createIconButton.ts#L1)**: Creates an HTML [`<span>`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L28) element representing an icon button.
+- **[`addStyle`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/addStyle.ts#L1)**: Adds a new style element to the document.
+- **[`createDivObserver`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/createDivObserver.ts#L3)**: Sets up a [`MutationObserver`](https://github.com/RoamJS/roamjs-components/blob/main/src/types/index.ts#L25) to monitor changes to a specific DOM element.
+- **[`createOverlayObserver`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/createOverlayObserver.ts#L3)**: Creates a [`MutationObserver`](https://github.com/RoamJS/roamjs-components/blob/main/src/types/index.ts#L25) that observes changes to the [`document.body`](https://github.com/RoamJS/roamjs-components/blob/main/src/util/runExtension.ts#L51) element.
+- **[`createButtonObserver`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/createButtonObserver.ts#L3)**: Monitors the DOM for changes to HTML [`<span>`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L28) elements with a specific class.
+- **[`createPageTitleObserver`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/createPageTitleObserver.ts#L4)**: Observes changes to the title of a specific Roam Research page.
+- **[`getMutatedNodes`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/getMutatedNodes.ts#L3)**: Finds nodes in a list of mutation records that match specified criteria.
+- **[`getActiveUids`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/getActiveUids.ts#L3)**: Retrieves the UIDs of the currently active HTML element on the page.
+- **[`elToTitle`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/elToTitle.ts#L1)**: Converts a DOM [`Node`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/createHTMLObserver.ts#L17) to a string representing its title or text content.
+- **[`getDropUidOffset`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/getDropUidOffset.ts#L5)**: Determines the parent UID and offset of a given HTML [`div`](https://github.com/RoamJS/roamjs-components/blob/main/src/components/Filter.tsx#L81) element within its parent container.
+
+These utilities streamline interactions with the DOM, making it easier to build and manage extensions and integrations for Roam Research.

package/docs/events.md

@@ -0,0 +1,16 @@
+# Event Handling
+
+https://github.com/RoamJS/roamjs-components/blob/main/src/events
+
+Utilities for setting up and managing event listeners in the Roam Research application are centralized in `https://github.com/RoamJS/roamjs-components/blob/main/src/events`. The primary function provided is [`watchOnce`](https://github.com/RoamJS/roamjs-components/blob/main/src/events/watchOnce.ts#L3), which allows for one-time event listening.
+
+- [`watchOnce`](https://github.com/RoamJS/roamjs-components/blob/main/src/events/watchOnce.ts#L3) is designed to monitor changes in a specific Roam Research block and execute a callback function when a change is detected.
+- It takes three parameters: [`pullPattern`](https://github.com/RoamJS/roamjs-components/blob/main/src/events/watchOnce.ts#L4) (the pattern to watch for), [`entityId`](https://github.com/RoamJS/roamjs-components/blob/main/src/events/watchOnce.ts#L5) (the block ID to watch), and [`callback`](https://github.com/RoamJS/roamjs-components/blob/main/src/types/index.ts#L128) (the function to execute upon detection).
+
+The function operates as follows:
+
+- Sets up a watcher using [`window.roamAlphaAPI.data.addPullWatch()`](https://github.com/RoamJS/roamjs-components/blob/main/src/events/watchOnce.ts#L14), passing the [`pullPattern`](https://github.com/RoamJS/roamjs-components/blob/main/src/events/watchOnce.ts#L4), [`entityId`](https://github.com/RoamJS/roamjs-components/blob/main/src/events/watchOnce.ts#L5), and a custom watcher function.
+- The custom watcher function invokes the [`callback`](https://github.com/RoamJS/roamjs-components/blob/main/src/types/index.ts#L128) with [`before`](https://github.com/RoamJS/roamjs-components/blob/main/src/util/renderOverlay.ts#L34) and [`after`](https://github.com/RoamJS/roamjs-components/blob/main/src/events/watchOnce.ts#L6) [`PullBlock`](https://github.com/RoamJS/roamjs-components/blob/main/src/types/native.ts#L171) objects.
+- If the [`callback`](https://github.com/RoamJS/roamjs-components/blob/main/src/types/index.ts#L128) returns [`true`](/roamjs-components/tsconfig.json#L9), the watcher is removed using [`window.roamAlphaAPI.data.removePullWatch()`](https://github.com/RoamJS/roamjs-components/blob/main/src/events/watchOnce.ts#L10).
+
+This utility is useful for scenarios where an action needs to be performed once upon a block's update, such as updating a visualization or triggering a notification.

package/docs/hooks.md

@@ -0,0 +1,15 @@
+# Hooks
+
+https://github.com/RoamJS/roamjs-components/blob/main/src/hooks
+
+Custom React hooks in this codebase manage user interactions and data structures.
+
+[`useArrowKeyDown`](https://github.com/RoamJS/roamjs-components/blob/main/src/hooks/useArrowKeyDown.ts#L13) handles keyboard navigation within a list of results. It takes three parameters: [`results`](https://github.com/RoamJS/roamjs-components/blob/main/src/testing/mockRoamEnvironment.ts#L1147), [`onEnter`](https://github.com/RoamJS/roamjs-components/blob/main/src/hooks/useArrowKeyDown.ts#L15), and [`menuRef`](https://github.com/RoamJS/roamjs-components/blob/main/src/components/CursorMenu.tsx#L115). The hook maintains the [`activeIndex`](https://github.com/RoamJS/roamjs-components/blob/main/src/hooks/useArrowKeyDown.ts#L22) state to track the selected item in the list. The [`onKeyDown`](https://github.com/RoamJS/roamjs-components/blob/main/src/hooks/useArrowKeyDown.ts#L23) function processes key presses:
+
+- **ArrowDown**: Increments [`activeIndex`](https://github.com/RoamJS/roamjs-components/blob/main/src/hooks/useArrowKeyDown.ts#L22), wrapping to 0 if the end of the list is reached, and ensures the selected element is in view.
+- **ArrowUp**: Decrements [`activeIndex`](https://github.com/RoamJS/roamjs-components/blob/main/src/hooks/useArrowKeyDown.ts#L22), wrapping to the last index if the beginning is reached, and ensures the selected element is in view.
+- **Enter**: Calls [`onEnter`](https://github.com/RoamJS/roamjs-components/blob/main/src/hooks/useArrowKeyDown.ts#L15) with the selected item and resets [`activeIndex`](https://github.com/RoamJS/roamjs-components/blob/main/src/hooks/useArrowKeyDown.ts#L22).
+
+[`useSubTree`](https://github.com/RoamJS/roamjs-components/blob/main/src/hooks/useSubTree.ts#L4) manages a sub-tree data structure. It takes [`props`](https://github.com/RoamJS/roamjs-components/blob/main/src/types/native.ts#L187) and uses [`useMemo`](https://github.com/RoamJS/roamjs-components/blob/main/src/components.tsx#L2) to memoize the result of [`getSubTree(props)`](https://github.com/RoamJS/roamjs-components/blob/main/src/hooks/useSubTree.ts#L8), based on the [`parentUid`](https://github.com/RoamJS/roamjs-components/blob/main/src/components/FormDialog.tsx#L97) property. This hook returns the current sub-tree object and a function to update it.
+
+Both hooks are exported from `https://github.com/RoamJS/roamjs-components/blob/main/src/hooks/index.ts`.

package/docs/marked.md

@@ -0,0 +1,56 @@
+# Markdown Parsing and Rendering
+
+https://github.com/RoamJS/roamjs-components/blob/main/src/marked
+
+Markdown content is parsed and rendered using a custom implementation of the [`marked`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L14) library, tailored for Roam Research. The main entry point for this functionality is in `https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts`.
+
+- **Language Syntax Highlighting**: Various language syntax highlighters from the [`refractor`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L2) library are registered, including Markdown, YAML, CSS, Bash, Java, Rust, Python, C#, Clojure, and HCL.
+
+- **Regular Expressions**: Several regular expressions are defined to match different types of Markdown elements:
+
+  - [`URL_REGEX`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L32): Matches URLs
+  - [`TODO_REGEX`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L34): Matches TODO items
+  - [`DONE_REGEX`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L35): Matches DONE items
+  - [`IFRAME_REGEX`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L36): Matches iframes
+  - [`BUTTON_REGEX`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L39): Matches buttons
+  - [`TAG_REGEX`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L41): Matches tags
+  - [`BLOCK_REF_REGEX`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L42): Matches block references
+  - [`ALIAS_REGEX`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L45): Matches aliases
+  - [`ALIAS_REF_REGEX`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L46): Matches alias references
+  - [`HASHTAG_REGEX`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L47): Matches hashtags
+  - [`ATTRIBUTE_REGEX`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L48): Matches attributes
+  - [`BOLD_REGEX`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L49): Matches bold text
+  - [`ITALICS_REGEX`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L50): Matches italicized text
+  - [`HIGHLIGHT_REGEX`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L51): Matches highlighted text
+  - [`INLINE_STOP_REGEX`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L52): Matches various inline elements that should stop the parsing of inline text
+  - [`HR_REGEX`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L54): Matches horizontal rules
+  - [`BQ_REGEX`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L55): Matches blockquotes
+  - [`TWEET_STATUS_REGEX`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L56): Matches Twitter status URLs
+
+- **Custom Options ([`opts`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L121))**: Extends the default [`marked`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L14) options to handle:
+
+  - HTML tags
+  - Strikethrough text
+  - Bold and italicized text
+  - Code blocks
+  - Inline text
+  - Code spans
+
+- **Custom Renderer ([`renderer`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L426))**: Extends the default [`marked`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L14) renderer to handle:
+
+  - Different types of links
+  - Code spans with syntax highlighting
+  - Various HTML elements
+
+- **Exported Functions**: Several functions wrap the [`marked`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L14) library's functionality, allowing for contextual parsing of Markdown text based on a provided [`RoamContext`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L563) object:
+  - [`getInlineLexer`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L602)
+  - [`getLexer`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L603)
+  - [`getParseInline`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L604)
+  - [`getParse`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L605)
+  - [`inlineLexer`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L615)
+  - [`lexer`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L616)
+  - [`parseInline`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L617)
+  - [`parse`](https://github.com/RoamJS/roamjs-components/blob/main/src/date/parseNlpDate.ts#L253)
+  - [`default`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/index.ts#L2) (exports the [`parse`](https://github.com/RoamJS/roamjs-components/blob/main/src/date/parseNlpDate.ts#L253) function)
+
+These customizations ensure that Roam-specific elements and formatting are correctly handled within the Markdown content.

package/docs/queries.md

@@ -0,0 +1,24 @@
+# Queries
+
+https://github.com/RoamJS/roamjs-components/blob/main/src/queries
+
+Utility functions for interacting with the Roam Research database are provided in the `https://github.com/RoamJS/roamjs-components/blob/main/src/queries` directory. These functions facilitate various operations, including retrieving and manipulating data.
+
+- **Datalog Compilation**: The [`compileDatalog`](https://github.com/RoamJS/roamjs-components/blob/main/src/queries/compileDatalog.ts#L5) function in `https://github.com/RoamJS/roamjs-components/blob/main/src/queries/compileDatalog.ts` compiles Datalog-related constructs into string representations. This includes data patterns, source variables, constants, variables, function expressions, predicate expressions, rule expressions, and different types of clauses (not, or, and, not-join, or-join).
+
+- **Attribute Retrieval**: The [`getAttributeValueByBlockAndName`](https://github.com/RoamJS/roamjs-components/blob/main/src/queries/getAttributeValueByBlockAndName.ts#L4) function in `https://github.com/RoamJS/roamjs-components/blob/main/src/queries/getAttributeValueByBlockAndName.ts` retrieves the value of an attribute associated with a specific block. It uses a Datalog query to find the block with the given attribute name and parent UID, then extracts and returns the attribute value.
+
+- **Utility Functions**:
+  - [`isTagOnPage`](https://github.com/RoamJS/roamjs-components/blob/main/src/queries/isTagOnPage.ts#L3) in `https://github.com/RoamJS/roamjs-components/blob/main/src/queries/isTagOnPage.ts` checks if a given tag is present on a specific page. It normalizes the tag and title, then uses a Datalog query to determine if the tag exists on the page.
+  - [`normalizePageTitle`](https://github.com/RoamJS/roamjs-components/blob/main/src/queries/normalizePageTitle.ts#L1) in `https://github.com/RoamJS/roamjs-components/blob/main/src/queries/normalizePageTitle.ts` normalizes a page title by replacing backslashes and double quotes with their escaped counterparts.
+
+These utility functions are essential for efficiently interacting with the Roam Research database, enabling complex queries and data manipulations. For more detailed information on specific operations, refer to the respective sections on
+
+- [Block Retrieval](https://wiki.mutable.ai/RoamJS/roamjs-components#block-retrieval)
+- [Page Retrieval](https://wiki.mutable.ai/RoamJS/roamjs-components#page-retrieval)
+- [User Information](https://wiki.mutable.ai/RoamJS/roamjs-components#user-information)
+- [Block Hierarchy](https://wiki.mutable.ai/RoamJS/roamjs-components#block-hierarchy)
+- [Block Metadata](https://wiki.mutable.ai/RoamJS/roamjs-components#block-metadata)
+- [Attribute Retrieval](https://wiki.mutable.ai/RoamJS/roamjs-components#attribute-retrieval)
+- [Datalog Compilation](https://wiki.mutable.ai/RoamJS/roamjs-components#datalog-compilation)
+- [Utility Functions](https://wiki.mutable.ai/RoamJS/roamjs-components#utility-functions)

package/docs/scripts.md

@@ -0,0 +1,20 @@
+# Script Management
+
+https://github.com/RoamJS/roamjs-components/blob/main/src/scripts
+
+The `https://github.com/RoamJS/roamjs-components/blob/main/src/scripts` directory contains two main files: [`index.ts`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/index.ts#L0) and [`publishToRoamDepot.ts`](https://github.com/RoamJS/roamjs-components/blob/main/src/scripts/publishToRoamDepot.ts#L0).
+
+- The [`index.ts`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/index.ts#L0) file serves as an entry point for the `@samepage/scripts/cli` module. This module provides command-line interface (CLI) functionality for the project.
+
+- The [`publishToRoamDepot.ts`](https://github.com/RoamJS/roamjs-components/blob/main/src/scripts/publishToRoamDepot.ts#L0) file contains the [`publishToRoamDepot`](https://github.com/RoamJS/roamjs-components/blob/main/src/scripts/publishToRoamDepot.ts#L15) function, which is responsible for publishing a Roam extension to the Roam Depot. The function performs several key tasks:
+  - Checks for existing pull requests for the current branch in the Roam Depot repository using the GitHub API.
+  - Clones the Roam Depot repository using [`execSync()`](https://github.com/RoamJS/roamjs-components/blob/main/src/scripts/publishToRoamDepot.ts#L5).
+  - Determines the path to the extension manifest file based on provided [`proxy`](https://github.com/RoamJS/roamjs-components/blob/main/src/scripts/publishToRoamDepot.ts#L19) and [`repo`](https://github.com/RoamJS/roamjs-components/blob/main/src/scripts/publishToRoamDepot.ts#L17) parameters.
+  - Retrieves the author's name and email from the GitHub API or falls back to [`package.json`](/roamjs-components/package.json#L109) if the API call fails.
+  - Configures Git user information using [`execSync()`](https://github.com/RoamJS/roamjs-components/blob/main/src/scripts/publishToRoamDepot.ts#L5).
+  - Adds the Roam Depot repository as a remote and pulls the latest changes from the [`main`](/roamjs-components/package.json#L5) branch.
+  - If an existing pull request is found, it checks out the branch, rebases it against [`main`](/roamjs-components/package.json#L5), updates the [`source_commit`](https://github.com/RoamJS/roamjs-components/blob/main/src/scripts/publishToRoamDepot.ts#L70) field in the manifest file, commits the changes, and pushes the updated branch.
+  - If no existing pull request is found, it creates a new branch, creates the extension manifest file if it doesn't exist, populates it with necessary information, commits the changes, and pushes the new branch.
+  - Creates a new pull request in the Roam Depot repository using the GitHub API and logs the URL of the created or updated pull request.
+
+The [`publishToRoamDepot`](https://github.com/RoamJS/roamjs-components/blob/main/src/scripts/publishToRoamDepot.ts#L15) function uses several utility functions and libraries, such as the GitHub API and [`execSync()`](https://github.com/RoamJS/roamjs-components/blob/main/src/scripts/publishToRoamDepot.ts#L5) from the [`child_process`](https://github.com/RoamJS/roamjs-components/blob/main/src/scripts/publishToRoamDepot.ts#L5) module, to perform its tasks. It handles both the creation of new pull requests and the update of existing ones, making it a versatile tool for publishing Roam extensions.

package/docs/types.md

@@ -0,0 +1,32 @@
+## Type Definitions
+
+https://github.com/RoamJS/roamjs-components/blob/main/src/types
+
+The `https://github.com/RoamJS/roamjs-components/blob/main/src/types` directory defines the core types and interfaces used throughout the Roam Research extension ecosystem. These types cover a wide range of functionalities, from data structures and queries to user interface components and SmartBlocks.
+
+The [`index.ts`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/index.ts#L0) file serves as the entry point, importing and re-exporting types from other modules such as [`native`](https://github.com/RoamJS/roamjs-components/blob/main/src/types/native.ts#L0), [`query-builder`](https://github.com/RoamJS/roamjs-components/blob/main/src/types/query-builder.ts#L0), and [`smartblocks`](https://github.com/RoamJS/roamjs-components/blob/main/src/types/index.ts#L15). It also defines the [`Registry`](https://github.com/RoamJS/roamjs-components/blob/main/src/types/index.ts#L22) type, which centralizes the storage of various elements, event listeners, and other state used by the extension. Additionally, it extends the global [`Window`](https://github.com/RoamJS/roamjs-components/blob/main/src/types/index.ts#L57) object with Roam Research-specific APIs and utilities, including the [`roamAlphaAPI`](https://github.com/RoamJS/roamjs-components/blob/main/src/types/index.ts#L83) and [`roamjs`](https://github.com/RoamJS/roamjs-components/blob/main/src/types/index.ts#L234) namespaces.
+
+The [`native.ts`](https://github.com/RoamJS/roamjs-components/blob/main/src/types/native.ts#L0) file provides a comprehensive set of types for working with the Roam Research application. Key types include:
+
+- **Datalog Types**: These types, such as [`DatalogSrcVar`](https://github.com/RoamJS/roamjs-components/blob/main/src/types/native.ts#L6) and [`DatalogVariable`](https://github.com/RoamJS/roamjs-components/blob/main/src/types/native.ts#L11), model the structure of Datalog queries, which are integral to the Roam Research data model.
+- **Roam Research Data Structures**: Types like [`RoamBasicBlock`](https://github.com/RoamJS/roamjs-components/blob/main/src/types/native.ts#L139), [`RoamBasicPage`](https://github.com/RoamJS/roamjs-components/blob/main/src/types/native.ts#L144), and [`RoamBasicNode`](https://github.com/RoamJS/roamjs-components/blob/main/src/types/native.ts#L146) represent the various elements of Roam Research, such as blocks, pages, and nodes.
+- **User Interface Components**: Types such as [`Action`](https://github.com/RoamJS/roamjs-components/blob/main/src/types/native.ts#L447), [`ButtonAction`](https://github.com/RoamJS/roamjs-components/blob/main/src/types/native.ts#L419), and [`SwitchAction`](https://github.com/RoamJS/roamjs-components/blob/main/src/types/native.ts#L425) model the user interface components that can be added to the Roam Research application.
+- **Client-Side Actions**: Types like [`ClientParams`](https://github.com/RoamJS/roamjs-components/blob/main/src/types/native.ts#L324) and [`ActionParams`](https://github.com/RoamJS/roamjs-components/blob/main/src/types/native.ts#L341) represent the parameters for various client-side actions, such as creating or updating blocks and pages.
+- **User Settings**: The [`UserSettings`](https://github.com/RoamJS/roamjs-components/blob/main/src/types/native.ts#L363) type represents the user settings for the Roam Research application.
+- **Sidebar Functionality**: Types like [`SidebarWindowInput`](https://github.com/RoamJS/roamjs-components/blob/main/src/types/native.ts#L376) and [`SidebarBlockWindow`](https://github.com/RoamJS/roamjs-components/blob/main/src/types/native.ts#L381) model the sidebar functionality of the Roam Research application.
+
+The [`query-builder.ts`](https://github.com/RoamJS/roamjs-components/blob/main/src/types/query-builder.ts#L0) file defines types related to querying and working with data in [Query Builder](https://github.com/RoamJS/query-builder). Key types include:
+
+- **Result**: Represents the result of a query, containing fields like [`text`](https://github.com/RoamJS/roamjs-components/blob/main/src/marked/index.ts#L211) and [`uid`](https://github.com/RoamJS/roamjs-components/blob/main/src/util/getOauth.ts#L45).
+- **RunQuery** and **RunQuerySync**: Function types that execute a query and return the results.
+- **ListActiveQueries**: A function type that returns active queries.
+- **IsDiscourseNode**: A function type that determines if a node is a discourse node.
+
+The [`smartblocks.ts`](https://github.com/RoamJS/roamjs-components/blob/main/src/types/smartblocks.ts#L0) file defines types and interfaces used in the [SmartBlocks](https://github.com/RoamJS/smartblocks) extension. Key types include:
+
+- **CommandOutput**: Represents the output of a command handler.
+- **CommandHandler**: A function type that handles commands.
+- **SmartBlocksContext**: Represents the context in which a SmartBlock is executed.
+- **RegisterCommand** and **UnregisterCommand**: Function types for registering and unregistering commands.
+
+These types are essential for building robust and extensible Roam Research applications and integrations. For more detailed information on specific types, refer to the subsections on [Index Types](https://wiki.mutable.ai/RoamJS/roamjs-components#index-types), [Native Types](https://wiki.mutable.ai/RoamJS/roamjs-components#native-types), [Query Builder Types](https://wiki.mutable.ai/RoamJS/roamjs-components#query-builder-types), and [SmartBlocks Types](https://wiki.mutable.ai/RoamJS/roamjs-components#smartblocks-types).

package/docs/util.md

@@ -0,0 +1,38 @@
+## Utility Functions
+
+https://github.com/RoamJS/roamjs-components/blob/main/src/util
+
+Utility functions in the RoamJS ecosystem provide essential support for various operations, including API interactions, DOM manipulation, data extraction, settings management, extension management, and miscellaneous tasks.
+
+## API Interaction Utilities
+
+Functions like [`apiDelete()`](https://github.com/RoamJS/roamjs-components/blob/main/src/util/apiDelete.ts#L3), [`apiGet()`](https://github.com/RoamJS/roamjs-components/blob/main/src/util/apiGet.ts#L3), [`apiPost()`](https://github.com/RoamJS/roamjs-components/blob/main/src/util/apiPost.ts#L3), and [`apiPut()`](https://github.com/RoamJS/roamjs-components/blob/main/src/util/apiPut.ts#L3) standardize HTTP requests, while [`getOauth()`](https://github.com/RoamJS/roamjs-components/blob/main/src/util/getOauth.ts#L8) and [`getOauthAccounts()`](https://github.com/RoamJS/roamjs-components/blob/main/src/util/getOauthAccounts.ts#L7) manage OAuth authentication. For more details, see [API Interaction Utilities](https://wiki.mutable.ai/RoamJS/roamjs-components#api-interaction-utilities).
+
+## DOM and Rendering Utilities
+
+Utilities such as [`createOverlayRender()`](https://github.com/RoamJS/roamjs-components/blob/main/src/util/createOverlayRender.ts#L4), [`getRenderRoot()`](https://github.com/RoamJS/roamjs-components/blob/main/src/util/getRenderRoot.ts#L3), and [`renderOverlay()`](https://github.com/RoamJS/roamjs-components/blob/main/src/util/renderOverlay.ts#L16) facilitate DOM manipulation and component rendering within the Roam application. For more details, see [DOM and Rendering Utilities](https://wiki.mutable.ai/RoamJS/roamjs-components#dom-and-rendering-utilities).
+
+## Data Extraction and Transformation Utilities
+
+Functions like [`extractRef()`](https://github.com/RoamJS/roamjs-components/blob/main/src/util/extractRef.ts#L3), [`extractTag()`](https://github.com/RoamJS/roamjs-components/blob/main/src/util/extractTag.ts#L1), and [`createTagRegex()`](https://github.com/RoamJS/roamjs-components/blob/main/src/util/createTagRegex.ts#L1) handle the extraction and transformation of data from Roam page content. For more details, see [Data Extraction and Transformation Utilities](https://wiki.mutable.ai/RoamJS/roamjs-components#setting-and-configuration-utilities).
+
+## Setting and Configuration Utilities
+
+Utilities such as [`addInputSetting()`](https://github.com/RoamJS/roamjs-components/blob/main/src/util/addInputSetting.ts#L5), [`setInputSetting()`](https://github.com/RoamJS/roamjs-components/blob/main/src/util/setInputSetting.ts#L6), and [`getSettingValueFromTree()`](https://github.com/RoamJS/roamjs-components/blob/main/src/util/getSettingValueFromTree.ts#L5) manage settings and configurations within Roam extensions. For more details, see [Setting and Configuration Utilities](https://wiki.mutable.ai/RoamJS/roamjs-components#extension-management-utilities).
+
+## Extension Management Utilities
+
+Functions like [`extensionDeprecatedWarning()`](https://github.com/RoamJS/roamjs-components/blob/main/src/util/extensionDeprecatedWarning.ts#L11) and [`runExtension()`](https://github.com/RoamJS/roamjs-components/blob/main/src/util/runExtension.ts#L22) manage and run Roam extensions. For more details, see [Extension Management Utilities](https://wiki.mutable.ai/RoamJS/roamjs-components#extension-management-utilities).
+
+## Miscellaneous Utilities
+
+Various other utilities include [`isControl()`](https://github.com/RoamJS/roamjs-components/blob/main/src/util/isControl.ts#L1), [`toFlexRegex()`](https://github.com/RoamJS/roamjs-components/blob/main/src/util/toFlexRegex.ts#L1), and [`getWorkerClient()`](https://github.com/RoamJS/roamjs-components/blob/main/src/util/getWorkerClient.ts#L1), which handle tasks like checking DOM elements and interacting with web workers.
+
+## Key Design Choices and Important Implementations
+
+- **OAuth Management**: [`getOauth()`](https://github.com/RoamJS/roamjs-components/blob/main/src/util/getOauth.ts#L8) retrieves OAuth information from local storage or the Roam Research database, ensuring efficient access to authentication data.
+- **Overlay Rendering**: [`createOverlayRender()`](https://github.com/RoamJS/roamjs-components/blob/main/src/util/createOverlayRender.ts#L4) and [`renderOverlay()`](https://github.com/RoamJS/roamjs-components/blob/main/src/util/renderOverlay.ts#L16) manage the rendering of React components as overlays, providing a flexible way to display modal content.
+- **Extension Lifecycle Management**: [`runExtension()`](https://github.com/RoamJS/roamjs-components/blob/main/src/util/runExtension.ts#L22) handles the setup and cleanup of Roam extensions, including event listeners and registry management.
+- **Settings Management**: [`setInputSetting()`](https://github.com/RoamJS/roamjs-components/blob/main/src/util/setInputSetting.ts#L6) and [`getSettingValueFromTree()`](https://github.com/RoamJS/roamjs-components/blob/main/src/util/getSettingValueFromTree.ts#L5) streamline the process of managing input settings within Roam blocks, ensuring consistent configuration handling.
+
+These utilities are designed to be reusable and modular, promoting code organization and maintainability across the RoamJS ecosystem.

package/docs/writes.md

@@ -0,0 +1,23 @@
+# Write Operations
+
+https://github.com/RoamJS/roamjs-components/blob/main/src/writes
+
+`https://github.com/RoamJS/roamjs-components/blob/main/src/writes` contains functions that handle various write operations in a Roam. These functions include clearing, creating, updating, and deleting blocks, as well as creating pages and managing sidebar operations.
+
+- [`clearBlockById`](https://github.com/RoamJS/roamjs-components/blob/main/src/writes/clearBlockById.ts#L4): Clears the content of a block by its ID. It uses [`getUidsFromId`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/getUidsFromId.ts#L1) to extract the block UID and then calls [`submitActions`](https://github.com/RoamJS/roamjs-components/blob/main/src/writes/submitActions.ts#L19) to update the block content to an empty string.
+- [`clearBlockByUid`](https://github.com/RoamJS/roamjs-components/blob/main/src/writes/clearBlockByUid.ts#L3): Clears the content of a block by its UID. It directly calls [`submitActions`](https://github.com/RoamJS/roamjs-components/blob/main/src/writes/submitActions.ts#L19) with an update action to set the block content to an empty string.
+- [`createBlock`](https://github.com/RoamJS/roamjs-components/blob/main/src/writes/createBlock.ts#L41): Creates a new block with the provided content and options. It gathers the necessary actions using [`gatherActions`](https://github.com/RoamJS/roamjs-components/blob/main/src/writes/createBlock.ts#L4) and submits them using [`submitActions`](https://github.com/RoamJS/roamjs-components/blob/main/src/writes/submitActions.ts#L19).
+- [`createPage`](https://github.com/RoamJS/roamjs-components/blob/main/src/writes/createPage.ts#L6): Creates a new page with the provided title. It checks if the title matches a daily note pattern and generates a UID if necessary. It then submits actions to create the page and any child blocks using [`submitActions`](https://github.com/RoamJS/roamjs-components/blob/main/src/writes/submitActions.ts#L19).
+- [`deleteBlock`](https://github.com/RoamJS/roamjs-components/blob/main/src/writes/deleteBlock.ts#L3): Deletes a block by its UID. It submits a delete action using [`submitActions`](https://github.com/RoamJS/roamjs-components/blob/main/src/writes/submitActions.ts#L19).
+- [`openBlockInSidebar`](https://github.com/RoamJS/roamjs-components/blob/main/src/writes/openBlockInSidebar.ts#L1): Opens a block in the sidebar. It checks if the block is already open in the sidebar and either opens the sidebar or adds a new window with the block UID.
+- [`updateActiveBlock`](https://github.com/RoamJS/roamjs-components/blob/main/src/writes/updateActiveBlock.ts#L4): Updates the content of the currently active block. It retrieves the active block UID using [`getActiveUids`](https://github.com/RoamJS/roamjs-components/blob/main/src/dom/getActiveUids.ts#L3) and submits an update action using [`submitActions`](https://github.com/RoamJS/roamjs-components/blob/main/src/writes/submitActions.ts#L19).
+- [`updateBlock`](https://github.com/RoamJS/roamjs-components/blob/main/src/writes/updateBlock.ts#L4): Updates the properties of a block, including text, heading, text alignment, view type, and open state. It submits these updates using [`submitActions`](https://github.com/RoamJS/roamjs-components/blob/main/src/writes/submitActions.ts#L19).
+
+The [`submitActions`](https://github.com/RoamJS/roamjs-components/blob/main/src/writes/submitActions.ts#L19) function is central to these operations, handling the submission of various actions to the Roam Research API. It manages an action queue and retries actions in case of API errors.
+
+For more details on see
+
+- [Block Operations](https://wiki.mutable.ai/RoamJS/roamjs-components#block-operations)
+- [Page Operations](https://wiki.mutable.ai/RoamJS/roamjs-components#page-operations)
+- [Sidebar Operations](https://wiki.mutable.ai/RoamJS/roamjs-components#sidebar-operations)
+- [Action Submission](https://wiki.mutable.ai/RoamJS/roamjs-components#action-submission)