Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(richtext): bootstrap @astryxdesign/richtext package (canary-only) (#4281)

Cindy Zhang0db5dfda5c9a
diff --git a/packages/richtext/CHANGELOG.md b/packages/richtext/CHANGELOG.md
new file mode 100644
index 0000000000..eb0b60b6d4
--- /dev/null
+++ b/packages/richtext/CHANGELOG.md
@@ -0,0 +1 @@
+# @astryxdesign/richtext
diff --git a/packages/richtext/README.md b/packages/richtext/README.md
new file mode 100644
index 0000000000..6cbf2c952f
--- /dev/null
+++ b/packages/richtext/README.md
@@ -0,0 +1,64 @@
+# @astryxdesign/richtext
+
+Astryx rich text — a Lexical-based rich text editor and viewer.
+
+> **Status: empty scaffold.** This package is bootstrapped but does not export
+> anything yet. It will house the rich text editor and viewer that currently
+> live in `@astryxdesign/lab`; that code will move here without a fresh package
+> rollout.
+
+It will ship to npm **only under the `@canary` dist-tag** — there is never a
+stable (`latest`) release yet.
+
+## Trying richtext in your own project (canary)
+
+Once components land, `@astryxdesign/richtext` will be published **only** under
+the `@canary` dist-tag, so you must request that tag explicitly. There is no
+`latest` version to install.
+
+```bash
+npm install @astryxdesign/richtext@canary @astryxdesign/core@canary
+```
+
+> Canary builds track the latest commit on `main` (`0.x.y-canary.<sha>`). They
+> can break between any two versions — pin an exact version if you need
+> stability.
+
+## Why no stable release?
+
+`package.json` keeps `"private": true` plus an `"astryx": { "canaryOnly": true }`
+marker. The release workflow's stable (`latest`) job skips both private and
+`canaryOnly` packages, while the canary job strips `private` in its ephemeral CI
+checkout only (never in git) to publish the `@canary` tag. The committed
+`private: true` is npm's hard guarantee that no stable publish can ever happen —
+**do not remove it.**
+
+## Publishing publicly (when the editor/view are ready)
+
+When maintainers are ready to promote richtext to a stable public release:
+
+1. Move the editor/view source from `@astryxdesign/lab` into `src/` and export
+ it from `src/index.ts`. Add the StyleX CSS build wiring (see below).
+2. Remove `"private": true` **and** the `"astryx": { "canaryOnly": true }`
+ marker from `package.json`.
+3. Add a changeset (`pnpm changeset`) selecting `@astryxdesign/richtext` so the
+ release workflow versions and publishes it to the `latest` dist-tag.
+4. The stable (`latest`) release job (`.github/workflows/release.yml`) will then
+ include richtext on the next release.
+
+### Adding the StyleX CSS build (deferred until the first component)
+
+This scaffold intentionally omits the `build:css` step. `build-css.mjs` exits
+with an error ("No StyleX rules found") when a package has zero StyleX
+components, which would break CI for an empty package. When the first StyleX
+component lands:
+
+1. Register a `richtext` target in `scripts/build-css.mjs` (mirror the `lab` /
+ `charts` entries — same core token alias).
+2. Add `"build:css": "node ../../scripts/build-css.mjs --package richtext"` to
+ the `scripts` block and append `&& pnpm build:css` to the `build` script
+ (before `check-no-dev-jsx`).
+3. Add a `"./richtext.css"` entry to `exports` and add `richtext.css` under
+ `files` if needed.
+
+The babel config is already StyleX-ready, so this is a small, mechanical add.
diff --git a/packages/richtext/babel-plugin-add-extensions.cjs b/packages/richtext/babel-plugin-add-extensions.cjs
new file mode 100644
index 0000000000..3c6f15956a
--- /dev/null
+++ b/packages/richtext/babel-plugin-add-extensions.cjs
@@ -0,0 +1,61 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/* eslint-disable @typescript-eslint/no-require-imports, no-undef */
+
+/**
+ * Babel plugin that appends .js to relative import/export paths.
+ *
+ * TypeScript source uses extensionless imports (e.g. './XDSButton').
+ * Node.js ESM requires explicit extensions for "type": "module" packages.
+ * This plugin rewrites them during compilation so no postbuild step is needed.
+ *
+ * Handles both file imports ('./XDSButton' → './XDSButton.js') and
+ * directory imports ('./domainTokens' → './domainTokens/index.js').
+ */
+const fs = require('node:fs');
+const nodePath = require('node:path');
+
+module.exports = function addExtensions() {
+ const SKIP = /\.(?:js|mjs|cjs|json|css)$/;
+
+ return {
+ visitor: {
+ 'ImportDeclaration|ExportNamedDeclaration|ExportAllDeclaration'(
+ path,
+ state,
+ ) {
+ const source = path.node.source;
+ if (!source) return;
+ const value = source.value;
+
+ // Compat alias barrels self-re-export from `'.'` in source. Node ESM
+ // does not support directory imports in built output, so make the self
+ // reference explicit (`./index.js`) during compilation.
+ if (value === '.') {
+ source.value = './index.js';
+ return;
+ }
+ if (value === '..') {
+ source.value = '../index.js';
+ return;
+ }
+
+ if (!value.startsWith('./') && !value.startsWith('../')) return;
+ if (SKIP.test(value)) return;
+
+ const dir = nodePath.dirname(state.filename);
+ const asFile = nodePath.join(dir, value + '.ts');
+ const asTsx = nodePath.join(dir, value + '.tsx');
+ const asIndex = nodePath.join(dir, value, 'index.ts');
+ const asIndexTsx = nodePath.join(dir, value, 'index.tsx');
+
+ if (fs.existsSync(asFile) || fs.existsSync(asTsx)) {
+ source.value = value + '.js';
+ } else if (fs.existsSync(asIndex) || fs.existsSync(asIndexTsx)) {
+ source.value = value + '/index.js';
+ } else {
+ source.value = value + '.js';
+ }
+ },
+ },
+ };
+};
diff --git a/packages/richtext/babel.config.js b/packages/richtext/babel.config.js
new file mode 100644
index 0000000000..8fa6b58127
--- /dev/null
+++ b/packages/richtext/babel.config.js
@@ -0,0 +1,46 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file babel.config.js
+ * @input Uses @babel/preset-react, @babel/preset-typescript, the local
+ * add-extensions plugin, and @stylexjs/babel-plugin
+ * @output Babel config for compiling richtext src -> dist (ESM .js with StyleX)
+ * @position Build config for @astryxdesign/richtext
+ *
+ * Mirrors packages/lab/babel.config.js: richtext consumes core's StyleX theme
+ * tokens (@astryxdesign/core/theme/tokens.stylex), a cross-package reference
+ * core never makes. The StyleX resolver therefore needs an alias to core's
+ * source and a monorepo-root rootDir.
+ *
+ * SYNC: When modified, update this header and /packages/richtext/README.md
+ */
+
+/* global module, require, __dirname */
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const path = require('node:path');
+
+const rootDir = path.resolve(__dirname, '../..');
+
+module.exports = {
+ presets: [
+ ['@babel/preset-react', {runtime: 'automatic', development: false}],
+ ['@babel/preset-typescript', {isTSX: true, allExtensions: true}],
+ ],
+ plugins: [
+ './babel-plugin-add-extensions.cjs',
+ [
+ '@stylexjs/babel-plugin',
+ {
+ dev: false,
+ runtimeInjection: false,
+ genConditionalClasses: true,
+ treeshakeCompensation: true,
+ aliases: {
+ '@astryxdesign/core/*': [path.join(rootDir, 'packages/core/src/*')],
+ '@astryxdesign/core': [path.join(rootDir, 'packages/core/src')],
+ },
+ unstable_moduleResolution: {type: 'commonJS', rootDir},
+ },
+ ],
+ ],
+};
diff --git a/packages/richtext/package.json b/packages/richtext/package.json
new file mode 100644
index 0000000000..65cbc8e137
--- /dev/null
+++ b/packages/richtext/package.json
@@ -0,0 +1,62 @@
+{
+ "name": "@astryxdesign/richtext",
+ "version": "0.1.8",
+ "private": true,
+ "description": "Astryx rich text — a Lexical-based rich text editor and viewer. Published to npm only under the @canary dist-tag for early testing; never released as a stable (latest) version.",
+ "author": "Meta Open Source",
+ "license": "MIT",
+ "homepage": "https://github.com/facebook/astryx#readme",
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/facebook/astryx.git",
+ "directory": "packages/richtext"
+ },
+ "bugs": {
+ "url": "https://github.com/facebook/astryx/issues"
+ },
+ "keywords": [
+ "astryx",
+ "richtext",
+ "rich-text",
+ "editor",
+ "lexical",
+ "design-system"
+ ],
+ "astryx": {
+ "canaryOnly": true,
+ "_comment": "Published ONLY to the @canary dist-tag (see .github/workflows/release.yml). Never released as a stable `latest` release. `private: true` is intentional and must stay — it is npm's hard guarantee against an accidental stable publish."
+ },
+ "main": "./dist/index.js",
+ "module": "./dist/index.js",
+ "types": "./dist/index.d.ts",
+ "sideEffects": false,
+ "files": [
+ "dist",
+ "src",
+ "README.md",
+ "CHANGELOG.md"
+ ],
+ "exports": {
+ ".": {
+ "source": "./src/index.ts",
+ "types": "./dist/index.d.ts",
+ "default": "./dist/index.js"
+ }
+ },
+ "scripts": {
+ "prepack": "pnpm build",
+ "build": "rm -rf dist && pnpm build:esm && tsc --project tsconfig.build.json && node ../../scripts/check-no-dev-jsx.mjs",
+ "build:esm": "babel src --out-dir dist --extensions '.ts,.tsx' --out-file-extension '.js' --ignore '**/*.test.ts,**/*.test.tsx,**/__tests__/**,**/*.perf.test.*,**/*.doc.mjs,**/*.d.ts,**/*.css,**/*.css.d.ts' --config-file ./babel.config.js",
+ "dev": "babel src --watch --out-dir dist --extensions '.ts,.tsx' --out-file-extension '.js' --ignore '**/*.test.*,**/*.doc.mjs,**/*.d.ts,**/*.css*' --config-file ./babel.config.js",
+ "test": "vitest run --root ../..",
+ "test:watch": "vitest --root ../..",
+ "lint": "eslint src",
+ "typecheck": "tsc --project tsconfig.json --noEmit"
+ },
+ "peerDependencies": {
+ "@stylexjs/stylex": ">=0.10.0",
+ "@astryxdesign/core": "0.1.8",
+ "react": ">=19.0.0",
+ "react-dom": ">=19.0.0"
+ }
+}
diff --git a/packages/richtext/src/index.ts b/packages/richtext/src/index.ts
new file mode 100644
index 0000000000..62980ea342
--- /dev/null
+++ b/packages/richtext/src/index.ts
@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file index.ts
+ * @input (none yet — empty package)
+ * @output Public API surface for @astryxdesign/richtext
+ * @position Barrel export; entry point for consumers of @astryxdesign/richtext
+ *
+ * SYNC: When modified, update /packages/richtext/README.md
+ */
+
+/**
+ * @astryxdesign/richtext will house the Lexical-based rich text editor and
+ * viewer currently in @astryxdesign/lab. It is intentionally empty for now —
+ * this bootstrap only establishes the package, its build wiring, and its npm
+ * canary-only publishing setup so the editor/view can move here later without
+ * a fresh package rollout.
+ *
+ * The `export {}` keeps this a valid ES module with no exports until the first
+ * component lands.
+ */
+export {};
diff --git a/packages/richtext/tsconfig.build.json b/packages/richtext/tsconfig.build.json
new file mode 100644
index 0000000000..5966f8174f
--- /dev/null
+++ b/packages/richtext/tsconfig.build.json
@@ -0,0 +1,21 @@
+{
+ "extends": "../../tsconfig.json",
+ "compilerOptions": {
+ "outDir": "./dist",
+ "rootDir": "./src",
+ "noEmit": false,
+ "declaration": true,
+ "declarationMap": true,
+ "emitDeclarationOnly": true,
+ "sourceMap": false
+ },
+ "include": ["src"],
+ "exclude": [
+ "src/**/*.test.ts",
+ "src/**/*.test.tsx",
+ "src/**/*.doc.mjs",
+ "src/**/__tests__/**",
+ "src/**/*.perf.test.ts",
+ "src/**/*.perf.test.tsx"
+ ]
+}
diff --git a/packages/richtext/tsconfig.json b/packages/richtext/tsconfig.json
new file mode 100644
index 0000000000..49e05cea1e
--- /dev/null
+++ b/packages/richtext/tsconfig.json
@@ -0,0 +1,8 @@
+{
+ "extends": "../../tsconfig.json",
+ "compilerOptions": {
+ "outDir": "./dist",
+ "rootDir": "./src"
+ },
+ "include": ["src"]
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 344cedb689..4ee67a815b 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -665,6 +665,21 @@ importers:
specifier: ^0.46.0
version: 0.46.0([email protected])
+ packages/richtext:
+ dependencies:
+ '@astryxdesign/core':
+ specifier: 0.1.8
+ version: link:../core
+ '@stylexjs/stylex':
+ specifier: ^0.19.0
+ version: 0.19.0
+ react:
+ specifier: '>=19.0.0'
+ version: 19.2.7
+ react-dom:
+ specifier: '>=19.0.0'
+ version: 19.2.7([email protected])
+
packages/themes/butter:
dependencies:
'@astryxdesign/core':