@atcute/bluesky-richtext-builder 1.0.0

package/LICENSE

@@ -0,0 +1,17 @@
+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

@@ -0,0 +1,19 @@
+# @atcute/bluesky-richtext-builder
+
+builder pattern for Bluesky's rich text format
+
+```ts
+import RichtextBuilder from '@atcute/bluesky-richtext-builder';
+
+const { text, facets } = new RichtextBuilder()
+	.addText(`hello, `)
+	.addMention(`@user`, 'did:plc:ia76kvnndjutgedggx2ibrem')
+	.addText(`! please visit my`)
+	.addLink(`website`, 'https://example.com');
+
+text;
+// ^? `hello, @user! please visit my website`
+
+facets;
+// ^? [{ index: { byteStart: 7, byteEnd: 12 }, ... }, { index: { byteStart: 30, byteEnd: 37 }, ... }];
+```

package/dist/index.d.ts

@@ -0,0 +1,58 @@
+import '@atcute/bluesky/lexicons';
+import type { AppBskyRichtextFacet, At } from '@atcute/client/lexicons';
+type UnwrapArray<T> = T extends (infer V)[] ? V : never;
+/** Facet interface, `app.bsky.richtext.facet#main` from the lexicon */
+export type Facet = AppBskyRichtextFacet.Main;
+/** Feature union type from Facet['features'] */
+export type FacetFeature = UnwrapArray<Facet['features']>;
+/** Resulting rich text */
+export interface BakedRichtext {
+    text: string;
+    facets: Facet[];
+}
+/** Builder for constructing Bluesky rich texts */
+declare class RichtextBuilder {
+    #private;
+    /** Resulting composed text */
+    get text(): string;
+    /** Resulting composed facets */
+    get facets(): Facet[];
+    /** Retrieve the composed rich text */
+    build(): BakedRichtext;
+    /** Clone rich text builder instance */
+    clone(): RichtextBuilder;
+    /**
+     * Add plain text to the rich text
+     * @param substr The plain text
+     * @returns The builder instance, for chaining
+     */
+    addText(substr: string): this;
+    /**
+     * Add decorated text to the rich text
+     * @param substr The text itself
+     * @param feature Feature to imbue on the text
+     * @returns The builder instance, for chaining
+     */
+    addDecoratedText(substr: string, feature: FacetFeature): this;
+    /**
+     * Add link to the rich text
+     * @param substr Text of the link
+     * @param uri Valid URL, for example: https://example.com
+     * @returns The builder instance, for chaining
+     */
+    addLink(substr: string, uri: string): this;
+    /**
+     * Mentions a user in rich text
+     * @param substr Text of the mention, this is usually in the form of `@handle`
+     * @param did Valid DID, for example: did:plc:ia76kvnndjutgedggx2ibrem
+     * @returns The builder instance, for chaining
+     */
+    addMention(substr: string, did: At.DID): this;
+    /**
+     * Add inline hashtag to the rich text
+     * @param tag The tag, without the pound prefix
+     * @returns THe builder instance, for chaining
+     */
+    addTag(tag: string): this;
+}
+export default RichtextBuilder;

package/dist/index.js

@@ -0,0 +1,104 @@
+import '@atcute/bluesky/lexicons';
+const encoder = new TextEncoder();
+/** Builder for constructing Bluesky rich texts */
+class RichtextBuilder {
+    // Even-numbered are substrings, odd-numbered are facets
+    // This way we'll avoid taking the hit on calculating UTF-8 indices up until
+    // a facet is actually being inserted.
+    #segments = [''];
+    /** Resulting composed text */
+    get text() {
+        const segments = this.#segments;
+        let str = '';
+        for (let idx = 0, len = segments.length; idx < len; idx += 2) {
+            str += segments[idx];
+        }
+        return str;
+    }
+    /** Resulting composed facets */
+    get facets() {
+        const segments = this.#segments;
+        const facets = [];
+        for (let idx = 1, len = segments.length; idx < len; idx += 2) {
+            facets.push(segments[idx]);
+        }
+        return facets;
+    }
+    /** Retrieve the composed rich text */
+    build() {
+        return {
+            text: this.text,
+            facets: this.facets,
+        };
+    }
+    /** Clone rich text builder instance */
+    clone() {
+        const instance = new RichtextBuilder();
+        instance.#segments = this.#segments.slice(0);
+        return instance;
+    }
+    /**
+     * Add plain text to the rich text
+     * @param substr The plain text
+     * @returns The builder instance, for chaining
+     */
+    addText(substr) {
+        const segments = this.#segments;
+        segments[segments.length - 1] += substr;
+        return this;
+    }
+    /**
+     * Add decorated text to the rich text
+     * @param substr The text itself
+     * @param feature Feature to imbue on the text
+     * @returns The builder instance, for chaining
+     */
+    addDecoratedText(substr, feature) {
+        const segments = this.#segments;
+        const last = segments.length - 1;
+        // Calculate the starting index
+        let start = 0;
+        start += encoder.encode(segments[last]).byteLength;
+        if (last !== 0) {
+            start += segments[last - 1].index.byteEnd;
+        }
+        const facet = {
+            index: {
+                byteStart: start,
+                byteEnd: start + encoder.encode(substr).byteLength,
+            },
+            features: [feature],
+        };
+        segments[last] += substr;
+        segments.push(facet, '');
+        return this;
+    }
+    /**
+     * Add link to the rich text
+     * @param substr Text of the link
+     * @param uri Valid URL, for example: https://example.com
+     * @returns The builder instance, for chaining
+     */
+    addLink(substr, uri) {
+        return this.addDecoratedText(substr, { $type: 'app.bsky.richtext.facet#link', uri: uri });
+    }
+    /**
+     * Mentions a user in rich text
+     * @param substr Text of the mention, this is usually in the form of `@handle`
+     * @param did Valid DID, for example: did:plc:ia76kvnndjutgedggx2ibrem
+     * @returns The builder instance, for chaining
+     */
+    addMention(substr, did) {
+        return this.addDecoratedText(substr, { $type: 'app.bsky.richtext.facet#mention', did: did });
+    }
+    /**
+     * Add inline hashtag to the rich text
+     * @param tag The tag, without the pound prefix
+     * @returns THe builder instance, for chaining
+     */
+    addTag(tag) {
+        return this.addDecoratedText('#' + tag, { $type: 'app.bsky.richtext.facet#tag', tag: tag });
+    }
+}
+export default RichtextBuilder;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "type": "module",
+  "name": "@atcute/bluesky-richtext-builder",
+  "version": "1.0.0",
+  "description": "builder pattern for Bluesky's rich text format",
+  "license": "MIT",
+  "repository": {
+    "url": "https://codeberg.org/mary-ext/atcute"
+  },
+  "files": [
+    "dist/"
+  ],
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "@atcute/bluesky": "^1.0.0",
+    "@atcute/client": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.1.6",
+    "@atcute/bluesky": "^1.0.0",
+    "@atcute/client": "^1.0.0"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "test": "bun test --coverage",
+    "prepublish": "rm -rf dist; pnpm run build"
+  }
+}