@spaced-out/ui-design-system 0.3.38 → 0.3.39-beta.0

package/.cspell/custom-words.txt

@@ -46,14 +46,17 @@ flowtype
 fontawesome
 framename
 Gaurav
+gulpfile
 Heatmaps
 highcharts
 Hovd
 innerref
 interdimensional
 Jangid
+jscodeshift
 Kamchatskiy
 Kemshetty
+khanacademy
 Kiritimati
 Kosrae
 Kuala
@@ -100,6 +103,7 @@ senseai
 sharad
 Stapleton
 storysource
+subproject
 superrover
 Swatantramishra
 Syowa

package/.github/workflows/publish_to_npm.yml

@@ -37,16 +37,44 @@ jobs:
           token: ${{ secrets.NPM_PUBLISH_USER_ACCESS_TOKEN }}
           fetch-depth: '0'
 
-      # Setup Node.js environment
-      - name: Setup Node.js
+      # Note(Nishant): Possible cleanup required Setup Node 18 for the base npm package
+      - name: Setup Node.js @18
         uses: actions/setup-node@v4
         with:
           registry-url: https://registry.npmjs.org/
           node-version: '18.20.5'
 
-      # Install dependencies (required by Run tests step)
+      # Note(Nishant): Possible cleanup required Setup Node 20 for the dts-generator
+      # We already pin the node versions with volta so this should be fine(but not ideal)
+      - name: Setup Node.js @20
+        uses: actions/setup-node@v4
+        with:
+          registry-url: https://registry.npmjs.org/
+          node-version: '20.9.0'
+
+      # -------------------------------------------------------------------------------------
+      # Note(Nishant): Install isolated dependencies for app and the DTS generator tool
+      # -------------------------------------------------------------------------------------
+      # Our project uses `flow-to-ts` to convert `.js.flow` files into `.d.ts` files.
+      # This is handled in a dedicated subproject located at `dts-generator/`,
+      # which contains its own `package.json` with pinned versions of `flow-to-ts`,
+      # `jscodeshift`, and `glob`.
+      #
+      # We keep it isolated to:
+      #   - Avoid dependency conflicts with the main project (e.g. Babel, Yarn PnP)
+      #   - Maintain cleaner separation of concerns (build vs type generation)
+      #   - Simplify upgrades or testing for Flow → TS conversions
+      #
+      # The `yarn --cwd` command ensures that only the dependencies inside
+      # `dts-generator` are installed, and is necessary before invoking
+      # `yarn build`, as our `gulpfile.js` calls this tool via `spawnSync`.
+      #
+      # DO NOT remove this step — skipping it will break `.d.ts` generation in CI.
+      # -------------------------------------------------------------------------------------
       - name: Install dependencies
-        run: yarn install
+        run: |
+          yarn install
+          yarn --cwd dts-generator install
 
       # ToDo(Nishant): Activate this once we have chromatic tests ready.
       #- name: Run tests

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [0.3.39-beta.0](https://github.com/spaced-out/ui-design-system/compare/v0.3.38...v0.3.39-beta.0) (2025-05-13)
+
+
+### Features
+
+* 🌈 add dts-generator tooling to support .d.ts generation from .js.flow files ([#334](https://github.com/spaced-out/ui-design-system/issues/334)) ([4580f22](https://github.com/spaced-out/ui-design-system/commit/4580f228a69b094d46078170138f621408393a03))
+* react 19 upgrade ([#340](https://github.com/spaced-out/ui-design-system/issues/340)) ([e90f3a4](https://github.com/spaced-out/ui-design-system/commit/e90f3a4b417cf37c531f912f309fa4e989160ba7))
+
+
+### Bug Fixes
+
+* multiple node versions ([#343](https://github.com/spaced-out/ui-design-system/issues/343)) ([f8f08e4](https://github.com/spaced-out/ui-design-system/commit/f8f08e46acadb5d892bd032250c0a58518d495a2))
+* yarn pack manager version ([#342](https://github.com/spaced-out/ui-design-system/issues/342)) ([64021f0](https://github.com/spaced-out/ui-design-system/commit/64021f044c678581bc5ad872a1f7593b966a811a))
+
 ### [0.3.38](https://github.com/spaced-out/ui-design-system/compare/v0.3.38-beta.0...v0.3.38) (2025-05-09)
 
 ### [0.3.38-beta.0](https://github.com/spaced-out/ui-design-system/compare/v0.3.37...v0.3.38-beta.0) (2025-05-09)

package/dts-generator/.editorconfig

@@ -0,0 +1,10 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+
+[*.{js,json,yml}]
+charset = utf-8
+indent_style = space
+indent_size = 2

package/dts-generator/.gitattributes

@@ -0,0 +1,4 @@
+/.yarn/**            linguist-vendored
+/.yarn/releases/*    binary
+/.yarn/plugins/**/*  binary
+/.pnp.*              binary linguist-generated

package/dts-generator/README.md

@@ -0,0 +1,63 @@
+# DTS Generator
+
+This folder contains a standalone utility to generate TypeScript declaration (`.d.ts`) files from existing `.js.flow` files using [`flow-to-ts`](https://github.com/MarcoPolo/flowToTs). These typings are essential for supporting downstream TypeScript consumers of the Genesis component library.
+
+---
+
+## Why this exists
+
+Although Genesis is written in Flow, the JavaScript ecosystem (including editors like VSCode, tsserver, and downstream NPM consumers) expects `.d.ts` files for rich type support. This tool bridges that gap by converting `.js.flow` files into `.d.ts` files that TypeScript understands — without requiring a full migration to TypeScript.
+
+This is **not a Flow-to-TypeScript migration**. It's a compatibility layer that allows us to continue using Flow internally while supporting TS externally.
+
+---
+
+## What it does
+
+- Scans `lib/` for `.js.flow` files
+- Uses `flow-to-ts` to convert each file into a `.d.ts` equivalent
+- Writes the `.d.ts` files alongside the original files
+- Formats the output with Prettier
+
+This process runs automatically as part of the `yarn build` step (via Gulp), ensuring typings are up-to-date with every release.
+
+---
+
+## Usage
+
+Install dependencies:
+
+```bash
+yarn --cwd dts-generator install
+```
+
+Run the generator:
+
+```bash
+yarn --cwd dts-generator generate
+```
+
+This will generate and format all `.d.ts` files for the project based on the current contents of `lib/`.
+
+---
+
+## Included in Release
+
+The `.d.ts` files generated here are published as part of our NPM release and are used by any project consuming Genesis with TypeScript.
+
+---
+
+## Tech Stack
+
+- [`flow-to-ts`](https://github.com/khan/flow-to-ts)
+- [`jscodeshift`](https://github.com/facebook/jscodeshift)
+- [`glob`](https://www.npmjs.com/package/glob)
+- [`prettier`](https://prettier.io)
+
+---
+
+## Related Context
+
+This setup is a foundational step toward the long-term vision of migrating all frontend codebases (`ui_server`, `ui_design_system`, `ui_chatbot`) to TypeScript at Sense.
+
+---

package/dts-generator/convert.js

@@ -0,0 +1,101 @@
+/**
+ * Note(Nishant): This script is part of our long-term migration and type safety strategy.
+ *
+ * Context:
+ * Our codebase has historically used Flow for type checking. Flow offers strong static typing,
+ * but has limited ecosystem support compared to TypeScript. Since the TypeScript ecosystem
+ * (including editors like VSCode, IDE integrations, and npm consumers) natively expects `.d.ts`
+ * files for type definitions, we need to bridge that gap.
+ *
+ * Purpose of this script:
+ * 1. It converts `.js.flow` files (Flow declaration files) in our `lib/` directory to
+ *    corresponding `.d.ts` files using `flow-to-ts`.
+ * 2. The output `.d.ts` files provide equivalent type declarations in TypeScript syntax.
+ * 3. We format these generated files using `prettier` to ensure consistent and readable output.
+ *
+ * Why `.d.ts` files matter:
+ * - TypeScript consumers of our NPM package (like internal projects or external partners)
+ *   rely on `.d.ts` files to get autocompletion, compile-time checking, and rich IDE support.
+ * - They serve as the public API contract of our component library.
+ * - Without `.d.ts` files, consumers would have to fall back to `any` or custom typings,
+ *   defeating the purpose of having a typed library.
+ *
+ * Why not just migrate to TS directly?
+ * - A full migration to TS is non-trivial and requires coordination across all teams.
+ * - In the interim, this approach gives us compatibility with the TypeScript ecosystem
+ *   without dropping Flow support.
+ *
+ * How it works:
+ * - We locate all `.js.flow` files under `lib/`
+ * - Each file is passed through `flow-to-ts` with `-o d.ts` to get a `.d.ts` representation.
+ * - We write the output next to the original file.
+ * - The result is then formatted using Prettier.
+ *
+ * This script is invoked as part of the build pipeline, and must run **after** the Gulp build step.
+ * Do not remove or bypass this logic — breaking `.d.ts` generation will break downstream consumers.
+ *
+ * Future:
+ * - Once we fully migrate to TypeScript, this step can be replaced by native `.d.ts` generation
+ *   via `tsc` or Babel.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const glob = require('glob');
+const {spawnSync} = require('child_process');
+
+
+const files = glob.sync(path.resolve(__dirname, '../lib/**/*.js.flow'));
+
+files.forEach((file) => {
+  const outPath = file.replace(/\.js\.flow$/, '.d.ts');
+  const flowToTs = path.resolve(__dirname, './node_modules/.bin/flow-to-ts');
+  // Note(Nishant) For some reason if i try to install prettier locally it fails for few components. Not
+  // spending too much time on it because the idea here is to move to ts eventually
+  const prettier = path.resolve(__dirname, '../node_modules/.bin/prettier');
+
+  const result = spawnSync(flowToTs, ['-o', 'd.ts', file], {
+    encoding: 'utf-8',
+    // Note(Nishant): Tells Node.js to run the command inside a shell, like bash or sh.
+    // essential for calling binaries via relative paths (e.g., from node_modules/.bin/)
+    shell: true,
+  });
+
+  const stdout = result.stdout?.trim();
+  const stderr = result.stderr?.trim();
+
+  if (result.error) {
+    console.error(`Spawn error converting ${file}:`, result.error.message);
+    return;
+  }
+
+  if (stderr) {
+    console.error(`stderr converting ${file}:\n${stderr}`);
+    return;
+  }
+
+  if (result.status !== 0) {
+    console.error(`Non-zero exit code for ${file}`);
+    return;
+  }
+
+  if (stdout && !stdout.includes('Processing') && !stdout.includes('Results')) {
+    fs.writeFileSync(outPath, stdout);
+    // eslint-disable-next-line no-console
+    console.log(`✅ Converted: ${file} → ${outPath}`);
+
+    // Format with Prettier
+    const fmt = spawnSync(prettier, ['--write', outPath], {
+      encoding: 'utf-8',
+      shell: true,
+    });
+
+    if (fmt.status !== 0) {
+      console.error(`Prettier formatting failed for ${outPath}`);
+    }
+  } else {
+    console.warn(
+      `No meaningful output for ${file}. It may be empty or skipped.`,
+    );
+  }
+});

package/dts-generator/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "dts-generator",
+  "private": true,
+  "scripts": {
+    "generate": "node convert.js"
+  },
+  "dependencies": {
+    "@khanacademy/flow-to-ts": "^0.5.2",
+    "glob": "^11.0.1",
+    "jscodeshift": "^17.3.0"
+  },
+  "volta": {
+    "node": "20.9.0",
+    "yarn": "1.22.19"
+  }
+}

package/gulpfile.js

@@ -2,6 +2,8 @@ const gulp = require('gulp');
 const babel = require('gulp-babel');
 const rename = require('gulp-rename');
 const replace = require('gulp-replace');
+const {spawnSync} = require('child_process');
+const path = require('path');
 
 const babelRc = require('./babel.config');
 
@@ -46,4 +48,21 @@ function copyOther() {
     .pipe(gulp.dest('lib'));
 }
 
-module.exports.build = gulp.parallel(buildCjs, copyFlow, copyOther);
+function generateDts(done) {
+  const result = spawnSync('yarn', ['generate'], {
+    stdio: 'inherit',
+    cwd: path.resolve(__dirname, 'dts-generator'),
+    shell: true,
+  });
+
+  if (result.status !== 0) {
+    return done(new Error('Failed to generate .d.ts files'));
+  }
+
+  done();
+}
+
+const coreBuild = gulp.parallel(buildCjs, copyFlow, copyOther);
+const fullBuild = gulp.series(coreBuild, generateDts);
+
+module.exports.build = fullBuild;

package/lib/components/Avatar/Avatar.d.ts

@@ -0,0 +1,264 @@
+import {$ReadOnly, $Values, $Keys} from 'utility-types';
+import * as React from 'react';
+import {
+  JumboSmall,
+  SubTitleLarge,
+  SubTitleMedium,
+  SubTitleSmall,
+} from '../../components/Text';
+import * as COLORS from '../../styles/variables/_color';
+import {
+  colorDangerLightest,
+  colorGrayLightest,
+  colorInformationLightest,
+  colorNeutralLightest,
+  colorSuccessLightest,
+  colorWarningLightest,
+} from '../../styles/variables/_color';
+import classify from '../../utils/classify';
+import type {IconType} from '../Icon';
+import {Icon} from '../Icon';
+import type {StatusSemanticType} from '../StatusIndicator';
+import {StatusIndicator} from '../StatusIndicator';
+import css from './Avatar.module.css';
+type ClassNames = $ReadOnly<{
+  wrapper?: string;
+  ring?: string;
+  content?: string;
+  image?: string;
+  icon?: string;
+  text?: string;
+}>;
+export const AVATAR_SIZE = Object.freeze({
+  small: 'small',
+  medium: 'medium',
+  large: 'large',
+  extraLarge: 'extraLarge',
+});
+export const avatarSizeOptions: Array<unknown> = [...Object.keys(AVATAR_SIZE)];
+export type AvatarSize = $Values<typeof AVATAR_SIZE>;
+export const AVATAR_COLOR = Object.freeze({
+  red: colorDangerLightest,
+  orange: colorWarningLightest,
+  green: colorSuccessLightest,
+  blue: colorInformationLightest,
+  gray: colorGrayLightest,
+  indigo: colorNeutralLightest,
+});
+export type AvatarColorType = $Keys<typeof AVATAR_COLOR>;
+export type AvatarProps = {
+  classNames?: ClassNames;
+  size?: AvatarSize;
+  imageSrc?: string;
+  ring?: boolean;
+  icon?: boolean;
+  text?: string;
+  color?: AvatarColorType;
+  style?: unknown;
+  iconName?: string;
+  iconType?: IconType;
+  ring?: boolean;
+  status?: StatusSemanticType;
+  statusBorderColorToken?: $Keys<typeof COLORS>;
+};
+
+const getAvatarText = (text = '') => {
+  const [firstWord, secondWord] = text.split(' ');
+  const firstChar = firstWord ? firstWord[0].toUpperCase() : '';
+  const secondChar = secondWord ? secondWord[0].toUpperCase() : '';
+  return firstChar + secondChar;
+};
+
+const AvatarTextDecorator = ({
+  avatarText,
+  size,
+  className,
+}: {
+  avatarText: string;
+  size: AvatarSize;
+  className?: string;
+}) => {
+  switch (size) {
+    case 'small':
+      return <SubTitleSmall className={className}>{avatarText}</SubTitleSmall>;
+
+    case 'medium':
+      return (
+        <SubTitleMedium className={className}>{avatarText}</SubTitleMedium>
+      );
+
+    case 'large':
+      return <SubTitleLarge className={className}>{avatarText}</SubTitleLarge>;
+
+    case 'extraLarge':
+      return <JumboSmall className={className}>{avatarText}</JumboSmall>;
+  }
+};
+
+// mapping of iconSize for each avatar size;
+const iconSize = Object.freeze({
+  small: 'small',
+  medium: 'medium',
+  large: 'medium',
+  extraLarge: 'large',
+});
+export type AvatarContentProps = {
+  imageSrc?: string;
+  text?: string;
+  iconName?: string;
+  iconType?: IconType;
+  size: AvatarSize;
+  color?: AvatarColorType;
+  ring?: boolean;
+  status?: StatusSemanticType;
+  statusBorderColorToken?: $Keys<typeof COLORS>;
+  classNames?: ClassNames;
+};
+
+const AvatarConditionalContent = ({
+  imageSrc,
+  text,
+  iconName,
+  size,
+  iconType,
+  color = 'blue',
+  status,
+  statusBorderColorToken,
+  classNames,
+}: AvatarContentProps) => (
+  <div
+    className={classify(
+      css.innerContainer,
+      {
+        [css.alignCenter]: !imageSrc,
+      },
+      classNames?.content,
+    )}
+    style={{
+      '--background-color': AVATAR_COLOR[color],
+    }}
+  >
+    {!!status && (
+      <div className={classify(css.statusIndicatorWrapper, css[size])}>
+        <StatusIndicator
+          status={status}
+          withBorder
+          borderColorToken={statusBorderColorToken}
+        />
+      </div>
+    )}
+
+    {imageSrc ? (
+      <img
+        src={imageSrc}
+        alt="Avatar"
+        className={classify(css.avatar, classNames?.image)}
+      ></img>
+    ) : iconName ? (
+      <Icon
+        name={iconName}
+        type={iconType}
+        size={iconSize[size]}
+        className={classNames?.icon}
+      />
+    ) : text ? (
+      <AvatarTextDecorator
+        avatarText={getAvatarText(text)}
+        size={size}
+        className={classNames?.text}
+      />
+    ) : null}
+  </div>
+);
+
+export const Avatar: React$AbstractComponent<AvatarProps, HTMLDivElement> =
+  React.forwardRef<AvatarProps, HTMLDivElement>(
+    (
+      {
+        classNames,
+        size = AVATAR_SIZE.medium,
+        imageSrc,
+        text,
+        style,
+        iconName,
+        iconType,
+        color,
+        ring = false,
+        status,
+        statusBorderColorToken,
+      }: AvatarProps,
+      ref,
+    ) => (
+      <div
+        className={classify(
+          css.container,
+          {
+            [css.extraLargeSize]: size === 'extraLarge',
+            [css.largeSize]: size === 'large',
+            [css.mediumSize]: size === 'medium',
+            [css.smallSize]: size === 'small',
+          },
+          classNames?.wrapper,
+        )}
+        style={style}
+        ref={ref}
+      >
+        {ring ? (
+          <div className={classify(css.ring, classNames?.ring)}>
+            <div className={css.whiteCircle}>
+              <AvatarConditionalContent
+                imageSrc={imageSrc}
+                text={text}
+                iconName={iconName}
+                iconType={iconType}
+                color={color}
+                size={size}
+                status={status}
+                statusBorderColorToken={statusBorderColorToken}
+                classNames={classNames}
+              />
+            </div>
+          </div>
+        ) : (
+          <AvatarConditionalContent
+            imageSrc={imageSrc}
+            text={text}
+            iconName={iconName}
+            iconType={iconType}
+            color={color}
+            size={size}
+            status={status}
+            statusBorderColorToken={statusBorderColorToken}
+            classNames={classNames}
+          />
+        )}
+      </div>
+    ),
+  );
+export const BaseAvatar = ({
+  classNames,
+  size = AVATAR_SIZE.medium,
+  text = '',
+  style,
+  color = 'blue',
+}: AvatarProps): React.ReactNode => (
+  <div
+    className={classify(
+      css.container,
+      {
+        [css.baseExtraLargeSize]: size === 'extraLarge',
+        [css.baseLargeSize]: size === 'large',
+        [css.baseMediumSize]: size === 'medium',
+        [css.baseSmallSize]: size === 'small',
+      },
+      classNames?.wrapper,
+    )}
+    style={{...style, background: AVATAR_COLOR[color]}}
+  >
+    <AvatarTextDecorator
+      avatarText={text}
+      size={size}
+      className={classNames?.text}
+    />
+  </div>
+);

package/lib/components/Avatar/index.d.ts

@@ -0,0 +1 @@
+export * from './Avatar';