discord.builders

repository·master·Indexed 42 days ago

https://github.com/startitbot/discord.builders

A monorepo featuring a public website and a source-available components-sdk. The components-sdk is a React-based library for creating Discord-style UI/UX components, acting as a lightweight WYSIWYG editor for visual emulation of Discord messages and elements. It includes a Capsule component for previews, a StateManager for state handling, and a set of component interfaces and mock factories via default_settings.

Tokens
11.8K
Snippets
44
Records
52
Agent score
54%

What's inside discord.builders

  1. Overview of components-sdk

    master

    The components-sdk library provides a React-based interface for creating Discord-style components. It acts as a lightweight WYSIWYG editor, offering a close visual approximation of how Discord messages and UI elements will appear.

    Key characteristics:

    • Minimalist: Designed with as few dependencies as possible.
    • Visual Approximation: Focuses on visual emulation rather than exact replication.
    • Abstraction-ready: Elements not directly related to Discord should be abstracted through interfaces and implemented separately in your application.
  2. Commercial use restrictions for components-sdk

    master

    The components-sdk is licensed under the PolyForm Noncommercial License 1.0.0.

    • Permitted Use: Free for personal, educational, and other noncommercial purposes.
    • Prohibited Use: Commercial use is strictly prohibited without a separate commercial license. This includes integration into proprietary bots, dashboards, or any other revenue-generating products.

    If you intend to use this library for a commercial product, you must obtain a separate commercial license.

  3. How to use provided interfaces in components-sdk

    master

    To keep the components-sdk lightweight, components that are not specific to Discord are not provided as full implementations. Instead, they are provided as interfaces.

    As a developer, you are expected to implement these interfaces within your own application (e.g., in a website directory). This allows you to tailor the UX and implementation to your specific project needs while ensuring compatibility with the SDK's expected patterns. Implementing these yourself also allows your specific implementation to be under your own license (e.g., MIT).

  4. Understand the licensing and commercial use restrictions

    master

    The monorepo contains two packages with different licenses:

    • website: Licensed under the MIT License.
    • components-sdk: Licensed under the PolyForm Noncommercial License 1.0.0.

    CRITICAL: Because the website package depends on components-sdk, any deployment or distribution of the website is subject to the PolyForm Noncommercial License 1.0.0. You cannot use, deploy, or distribute the website for commercial purposes unless you either remove the dependency on components-sdk or obtain a separate commercial license.

  5. Install and run the discord.builders monorepo

    master

    To set up the development environment for the monorepo, you must install the root dependencies, build the components-sdk package, and then start the website development server.

    1. Install monorepo dependencies: yarn install
    2. Build the components library: cd components-sdk && yarn build
    3. Start the website dev server: cd website && yarn dev

    Once running, the website is available at http://localhost:3000.

    yarn install
    cd components-sdk && yarn build
    cd website && yarn dev
  6. Reference of provided component interfaces

    master

    The following interfaces are provided by components-sdk to guide the implementation of common UI and logic patterns. You must implement the logic for these yourself based on these definitions:

    • BetterInput.ts: A customizable input component (e.g., a resizable text area or advanced input).
    • EmojiPicker.ts: An interface for an emoji picker component; you define the UX.
    • EmojiShow.ts: An interface for rendering emoji images based on an Emoji object.
    • StateManager.ts: A lightweight reducer-style state manager for handling state changes within components.
    • files.ts: Functions for managing uploaded files storage.
  7. Reference component and action icons

    master

    The components-sdk package uses a set of custom-made icons for various UI components and actions. When building or designing with these components, refer to the following mappings for visual consistency:

    Component Type Icons

    • Button Link: ButtonLink.svg
    • Container: Container.svg
    • Button: Button.svg
    • MediaGallery: MediaGallery.svg
    • Select: Select.svg
    • Separator: Separator.svg
    • File: Upload.svg
    • TextDisplay: TextDisplay.svg

    Button Color Variants

    Buttons support the following color themes:

    • Blue: ColorBlue.svg
    • Green: ColorGreen.svg
    • Grey: ColorGrey.svg
    • Red: ColorRed.svg

    Action Icons and States

    Many actions include an 'Active' state (e.g., ColorActive.svg) to represent a toggled or selected status.

    ActionIconUndo IconUsage
    DeleteTrash.svgN/AColor picker: Close; All "delete" actions
    ColorColor.svgColorActive.svgContainer: Add color
    SpoilerSpoiler.svgSpoilerActive.svgContainer: Spoiler
    EmojiEmoji.svgEmojiActive.svgButton/Select: Set Emoji
    DisabledLock.svgLockActive.svgButton/Select: Set Disabled
    DefaultDefault.svgDefaultActive.svgSelect: Set as default
    DescriptionDescriptionText.svgDescriptionTextActive.svgSelect: Change description/placeholder
    Label ChangeDescriptionPen.svgN/AButton/Select: Change label
    Global SettingsEdit.svgN/ASelect: Global settings
    Min OptionsMinimum.svgN/ASelect: Minimum options
    Max OptionsMaximum.svgN/ASelect: Maximum options
    File IconFileIcon.svgN/AFile component: Set/change file icon
    Add ComponentIcons.svgN/AAdd component
    Add DescriptionAddDescription.svgAddDescriptionActive.svgThumbnail: Add description
    Upload ImageUploadImage.svgN/AThumbnail: Upload image
    URLUrl.svgN/AThumbnail: Set image URL; Button: Set URL
  8. Use default_settings for generating mock components

    master

    The default_settings object provides factory functions to quickly generate valid mock component structures for testing or previewing. These functions return ActionRowComponent or specific component types with randomized or placeholder data (like random animal names or sentences).

    Available factories:

    • Button(): Returns an ActionRowComponent containing a standard button.
    • LinkButton(): Returns an ActionRowComponent containing a button with ButtonStyle.URL.
    • StringSelect(): Returns an ActionRowComponent containing a StringSelectComponent.
    • TextDisplay(): Returns a TextDisplayComponent with random text.
    • Thumbnail: A static object for a thumbnail component.
    • MediaGallery: A static object for a media gallery.
    • File: A static object for a file component.
    • Separator: A static object for a separator.
    • Container: A static object for a container.

    Example of generating a mock button row:

    const mockButtonRow = default_settings.Button();
    export const default_settings = {
        Button: () => ({
            type: 1,
            components: [{
                ..._Button,
                custom_id: uuidv4(),
                label: generateRandomAnimal()
            }]
        }),
        // ... other factories
    } as {
        Button: () => ActionRowComponent<ButtonComponent>,
        // ...
    }
  9. Extract error messages excluding component-level errors with flattenErrorsWithoutComponents

    master

    Use flattenErrorsWithoutComponents to get a list of unique error messages from an object while ignoring any errors nested under the components key. This is useful when you want to display top-level or global errors without cluttering the UI with specific component validation messages.

    import { flattenErrorsWithoutComponents } from '@startitbot/components-sdk';
    
    const errorObj = {
      components: {
        input: { _errors: [{ message: 'Component error' }] }
      },
      global: { _errors: [{ message: 'Global error' }] }
    };
    
    const messages = flattenErrorsWithoutComponents(errorObj);
    // Result: ['Global error']
  10. Guess a component type from a raw object

    master

    If you have a raw object and need to determine its Discord component type, use guessComponentType. It uses structural typing to identify the component.

    Heuristics used:

    • If it has a numeric type property present in ComponentType, it returns that type.
    • If it has label (string) and value (string), it is identified as ComponentTypeUnofficial.STRING_SELECT_OPTION.
    • If it has a media object with a url (string), it is identified as ComponentTypeUnofficial.MEDIA_GALLERY_ITEM.
    • Otherwise, returns null.
    export function guessComponentType(arg: object): ComponentType | ComponentTypeUnofficial | null
  11. Transform a component for a specific drop target with `getValidObj`

    master

    The getValidObj function is used to wrap or restructure a component so it is valid for the target DroppableID. This is useful when a component needs to be nested (e.g., wrapping a button in an ACTION_ROW or a select option in a STRING_SELECT).

    Parameters:

    • comp: The raw component object.
    • droppableId: The target DroppableID.
    • randomizeId: If true, calls randomizeIds to generate new custom_id and value fields using uuidv4().

    Returns:

    • A valid, structured component object, or null if the component is invalid for that location.
    export function getValidObj(comp: object, droppableId: DroppableID, randomizeId: boolean)