@pstdio/ui 0.0.1

package/.storybook/main.ts

@@ -0,0 +1,28 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { StorybookConfig } from "@storybook/react-vite";
+import { mergeConfig } from "vite";
+
+/**
+ * This function is used to resolve the absolute path of a package.
+ * It is needed in projects that use Yarn PnP or are set up within a monorepo.
+ */
+function getAbsolutePath(value: string) {
+  return dirname(fileURLToPath(import.meta.resolve(`${value}/package.json`)));
+}
+const rootDir = dirname(fileURLToPath(import.meta.url));
+const config: StorybookConfig = {
+  stories: ["../src/**/*.stories.@(js|jsx|mjs|ts|tsx)"],
+  addons: ["@storybook/addon-themes", getAbsolutePath("@storybook/addon-vitest")],
+  framework: getAbsolutePath("@storybook/react-vite"),
+  viteFinal: async (config) =>
+    mergeConfig(config, {
+      resolve: {
+        alias: {
+          "@": resolve(rootDir, "../src"),
+          $fonts: resolve(rootDir, "../public/font"),
+        },
+      },
+    }),
+};
+export default config;

package/.storybook/preview.tsx

@@ -0,0 +1,28 @@
+import { ChakraProvider } from "@chakra-ui/react";
+import { withThemeByClassName } from "@storybook/addon-themes";
+import type { Preview } from "@storybook/react-vite";
+import { psTheme } from "../src/theme";
+
+const preview: Preview = {
+  parameters: {
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+  },
+  decorators: [
+    (Story) => (
+      <ChakraProvider value={psTheme}>
+        <Story />
+      </ChakraProvider>
+    ),
+    withThemeByClassName({
+      defaultTheme: "light",
+      themes: { light: "light", dark: "dark" },
+    }),
+  ],
+};
+
+export default preview;

package/.storybook/vitest.setup.ts

@@ -0,0 +1,6 @@
+import { setProjectAnnotations } from "@storybook/react-vite";
+import * as projectAnnotations from "./preview";
+
+// This is an important step to apply the right configuration when testing your stories.
+// More info at: https://storybook.js.org/docs/api/portable-stories/portable-stories-vitest#setprojectannotations
+setProjectAnnotations([projectAnnotations]);

package/README.md

@@ -0,0 +1,72 @@
+# @pstdio/ui
+
+Shared React UI package for Prompt Studio apps. This package owns:
+
+- reusable components
+- design tokens and Chakra theme configuration
+- Storybook stories used as UI test cases
+
+## Run Locally
+
+From repo root:
+
+```bash
+bun run storybook:ui
+```
+
+From `packages/ui`:
+
+```bash
+bun run storybook
+```
+
+Build distributable package:
+
+```bash
+bun run --cwd packages/ui build
+```
+
+Run Storybook tests:
+
+```bash
+bun run --cwd packages/ui test-storybook
+```
+
+## Package Layout
+
+- `src/components/*`: components and colocated stories (`*.stories.tsx`)
+- `src/theme/*`: theme, recipes, tokens, and theme helpers
+- `src/index.ts`: public exports for `@pstdio/ui`
+- `.storybook/*`: Storybook configuration and Vitest setup
+
+## Contributor Workflow
+
+1. Implement or update the component in `src/components`.
+2. Add or update stories next to the component to cover important user-visible states.
+3. If the component is public, export it from `src/index.ts`.
+4. If you add a new package entrypoint, update `package.json#exports`.
+5. Run validations before opening a PR.
+
+## Validation Checklist
+
+From repo root:
+
+```bash
+bun run format
+bun run lint
+bun run build
+bun run test
+```
+
+UI-specific check:
+
+```bash
+bun run --cwd packages/ui test-storybook
+```
+
+## Story Guidelines
+
+- Treat each story as a reproducible test case for a real UI state.
+- Include states like default, loading, empty, error, long content, and disabled where relevant.
+- For non-visual behavior, add `play` interactions and assertions in the story.
+- Keep stories deterministic: avoid real network calls.

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@pstdio/ui",
+  "version": "0.0.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    },
+    "./rich-text": {
+      "import": "./src/components/rich-text/index.ts",
+      "types": "./src/components/rich-text/index.ts"
+    },
+    "./theme": {
+      "import": "./src/theme/index.ts",
+      "types": "./src/theme/index.ts"
+    }
+  },
+  "scripts": {
+    "build": "vite build",
+    "visualize-bundle": "bunx vite-bundle-visualizer",
+    "lint": "bunx biome check .",
+    "typegen:tokens": "chakra typegen ./src/theme/theme.ts",
+    "test": "echo 'no tests — use storybook for UI'",
+    "test-storybook": "vitest --project=storybook",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build"
+  },
+  "peerDependencies": {
+    "@chakra-ui/react": "^3.0.0",
+    "@emotion/react": "^11.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "dependencies": {
+    "@chakra-ui/react": "3.32.0",
+    "@emotion/react": "11.14.0",
+    "@fontsource/inter": "^5.2.8",
+    "@fontsource/onest": "^5.2.11",
+    "@fontsource/playfair-display": "^5.2.8",
+    "@lexical/code": "^0.40.0",
+    "@lexical/link": "^0.40.0",
+    "@lexical/list": "^0.40.0",
+    "@lexical/mark": "^0.40.0",
+    "@lexical/markdown": "^0.40.0",
+    "@lexical/react": "^0.40.0",
+    "@lexical/rich-text": "^0.40.0",
+    "@lexical/selection": "^0.40.0",
+    "@lexical/table": "^0.40.0",
+    "@lexical/utils": "^0.40.0",
+    "@lexical/yjs": "^0.40.0",
+    "@monaco-editor/react": "^4.7.0",
+    "@tanstack/react-query": "^5.90.21",
+    "@tanstack/react-router": "^1.163.2",
+    "@tanstack/react-table": "^8.21.3",
+    "@tanstack/react-virtual": "^3.13.19",
+    "date-fns": "^2.30.0",
+    "katex": "^0.16.33",
+    "lexical": "^0.40.0",
+    "lucide-react": "^0.556.0",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "use-stick-to-bottom": "^1.1.3",
+    "y-protocols": "^1.0.7",
+    "y-websocket": "^3.0.0",
+    "yjs": "^13.6.29"
+  },
+  "devDependencies": {
+    "@storybook/addon-themes": "^10.1.10",
+    "@storybook/addon-vitest": "^10.2.12",
+    "@storybook/react": "^10.1.9",
+    "@storybook/react-vite": "^10.1.9",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@vitejs/plugin-react": "^5.1.1",
+    "babel-plugin-react-compiler": "^1.0.0",
+    "storybook": "^10.1.9",
+    "typescript": "~5.9.3",
+    "vite": "^7.2.4",
+    "vite-plugin-dts": "^4.5.4",
+    "vite-plugin-externalize-deps": "^0.8.0",
+    "vite-plugin-svgr": "^4.3.0",
+    "vitest": "^4.0.18",
+    "playwright": "^1.58.2",
+    "@vitest/browser-playwright": "^4.0.18",
+    "@vitest/coverage-v8": "^4.0.18"
+  }
+}

package/src/components/alert.tsx

@@ -0,0 +1,27 @@
+import { Alert as ChakraAlert } from "@chakra-ui/react";
+import * as React from "react";
+
+export interface AlertProps extends Omit<ChakraAlert.RootProps, "title"> {
+  startElement?: React.ReactNode;
+  endElement?: React.ReactNode;
+  title?: React.ReactNode;
+  icon?: React.ReactElement;
+}
+
+export const AlertMessage = React.forwardRef<HTMLDivElement, AlertProps>(function Alert(props, ref) {
+  const { title, children, icon, startElement, endElement, ...rest } = props;
+  return (
+    <ChakraAlert.Root ref={ref} {...rest}>
+      {startElement || <ChakraAlert.Indicator>{icon}</ChakraAlert.Indicator>}
+      {children ? (
+        <ChakraAlert.Content>
+          <ChakraAlert.Title>{title}</ChakraAlert.Title>
+          <ChakraAlert.Description>{children}</ChakraAlert.Description>
+        </ChakraAlert.Content>
+      ) : (
+        <ChakraAlert.Title flex="1">{title}</ChakraAlert.Title>
+      )}
+      {endElement}
+    </ChakraAlert.Root>
+  );
+});

package/src/components/breadcrumb.stories.tsx

@@ -0,0 +1,40 @@
+import { Box, Icon } from "@chakra-ui/react";
+import { ChevronRight } from "lucide-react";
+import type { ReactNode } from "react";
+
+import { Breadcrumb } from "./breadcrumb";
+
+type StoryFn = () => ReactNode;
+
+const items = [
+  { title: "Dashboard", url: "/" },
+  { title: "Invoices", url: "/invoices" },
+  { title: "Northwind Traders Q4 2024" },
+];
+
+const meta = {
+  title: "Components/Breadcrumb",
+  component: Breadcrumb,
+  decorators: [
+    (Story: StoryFn) => (
+      <Box padding="sm" background="bg">
+        <Story />
+      </Box>
+    ),
+  ],
+  args: {
+    items,
+    separator: "/",
+    separatorGap: "xs",
+  },
+};
+
+export default meta;
+
+export const Default = {};
+
+export const IconSeparator = {
+  args: {
+    separator: <Icon as={ChevronRight} boxSize="12px" color="fg.muted" />,
+  },
+};

package/src/components/breadcrumb.tsx

@@ -0,0 +1,67 @@
+import { Breadcrumb as ChakraBreadcrumb, type SystemStyleObject } from "@chakra-ui/react";
+import * as React from "react";
+
+export interface BreadcrumbItem {
+  title: React.ReactNode;
+  url?: string;
+  onClick?: () => void;
+}
+
+export interface BreadcrumbLinkProps {
+  to: string;
+  children: React.ReactNode;
+}
+
+export interface BreadcrumbProps extends ChakraBreadcrumb.RootProps {
+  separator?: React.ReactNode;
+  separatorGap?: SystemStyleObject["gap"];
+  items: BreadcrumbItem[];
+  linkComponent?: React.ComponentType<BreadcrumbLinkProps>;
+}
+
+export const Breadcrumb = React.forwardRef<HTMLDivElement, BreadcrumbProps>(function BreadcrumbRoot(props, ref) {
+  const { separator, separatorGap, items, linkComponent: LinkComponent, ...rest } = props;
+
+  return (
+    <ChakraBreadcrumb.Root ref={ref} {...rest}>
+      <ChakraBreadcrumb.List gap={separatorGap}>
+        {items.map((item, index) => {
+          const last = index === items.length - 1;
+          const isInteractive = Boolean(item.url || item.onClick);
+          let itemContent: React.ReactNode;
+
+          if (last && !isInteractive) {
+            itemContent = <ChakraBreadcrumb.CurrentLink>{item.title}</ChakraBreadcrumb.CurrentLink>;
+          } else if (item.url) {
+            itemContent = LinkComponent ? (
+              <ChakraBreadcrumb.Link asChild>
+                <LinkComponent to={item.url}>{item.title}</LinkComponent>
+              </ChakraBreadcrumb.Link>
+            ) : (
+              <ChakraBreadcrumb.Link href={item.url}>{item.title}</ChakraBreadcrumb.Link>
+            );
+          } else if (item.onClick) {
+            itemContent = (
+              <ChakraBreadcrumb.Link as="button" type="button" onClick={item.onClick}>
+                {item.title}
+              </ChakraBreadcrumb.Link>
+            );
+          } else {
+            itemContent = <ChakraBreadcrumb.Link>{item.title}</ChakraBreadcrumb.Link>;
+          }
+
+          return (
+            <ChakraBreadcrumb.Item key={index}>
+              {itemContent}
+              {last ? null : (
+                <ChakraBreadcrumb.Separator as="span" aria-hidden ml="xs">
+                  {separator}
+                </ChakraBreadcrumb.Separator>
+              )}
+            </ChakraBreadcrumb.Item>
+          );
+        })}
+      </ChakraBreadcrumb.List>
+    </ChakraBreadcrumb.Root>
+  );
+});

package/src/components/button.stories.tsx

@@ -0,0 +1,151 @@
+import type { ButtonProps } from "@chakra-ui/react";
+import { Box, Button, HStack, Icon, IconButton, SimpleGrid, Stack, Text } from "@chakra-ui/react";
+import { Download, Plus, Settings, Trash2 } from "lucide-react";
+import type { ReactNode } from "react";
+
+type StoryFn = () => ReactNode;
+
+interface ButtonVariantOption {
+  label: string;
+  description: string;
+  variant: ButtonProps["variant"] | "primary";
+}
+
+interface ButtonSizeOption {
+  label: string;
+  helper: string;
+  size: ButtonProps["size"];
+}
+
+const buttonVariants: ButtonVariantOption[] = [
+  { label: "Primary", description: "Brand action style using accent tokens.", variant: "primary" },
+  { label: "Solid", description: "Primary calls to action.", variant: "solid" },
+  { label: "Surface", description: "Secondary surfaces with borders.", variant: "surface" },
+  { label: "Outline", description: "Neutral outlines for quiet actions.", variant: "outline" },
+  { label: "Ghost", description: "Low emphasis actions in dense UI.", variant: "ghost" },
+  { label: "Subtle", description: "Low-contrast background actions.", variant: "subtle" },
+  { label: "Plain", description: "Inline link-style actions.", variant: "plain" },
+];
+
+const buttonSizes: ButtonSizeOption[] = [
+  { label: "Small", helper: "Dense toolbars and tables.", size: "sm" },
+  { label: "Medium", helper: "Default buttons across the app.", size: "md" },
+  { label: "Large", helper: "Primary CTAs in dialogs.", size: "lg" },
+  { label: "2XL", helper: "Hero CTAs on landing surfaces.", size: "2xl" },
+];
+
+const meta = {
+  title: "Components/Button",
+  component: Button,
+  decorators: [
+    (Story: StoryFn) => (
+      <Box padding="sm" background="bg">
+        <Story />
+      </Box>
+    ),
+  ],
+};
+
+export default meta;
+
+export const Variants = {
+  render: () => (
+    <SimpleGrid columns={{ base: 1, lg: 2 }} gap="md">
+      {buttonVariants.map((variant) => (
+        <Box
+          key={variant.label}
+          borderWidth="1px"
+          borderColor="border.muted"
+          borderRadius="md"
+          background="bg"
+          padding="md"
+        >
+          <Stack gap="sm">
+            <Stack gap="xs">
+              <Text textStyle="label/L/medium">{variant.label}</Text>
+              <Text textStyle="label/XS" color="fg.muted">
+                {variant.description}
+              </Text>
+            </Stack>
+
+            <HStack gap="sm" flexWrap="wrap">
+              <Button variant={variant.variant as ButtonProps["variant"]}>Run action</Button>
+              <Button variant={variant.variant as ButtonProps["variant"]} loading>
+                Loading
+              </Button>
+              <Button variant={variant.variant as ButtonProps["variant"]} disabled>
+                Disabled
+              </Button>
+            </HStack>
+          </Stack>
+        </Box>
+      ))}
+    </SimpleGrid>
+  ),
+};
+
+export const Sizes = {
+  render: () => (
+    <Stack gap="lg">
+      {buttonSizes.map((size) => (
+        <HStack
+          key={size.label}
+          alignItems="center"
+          justifyContent="space-between"
+          flexWrap="wrap"
+          gap="md"
+          padding="md"
+          borderWidth="1px"
+          borderColor="border.muted"
+          borderRadius="md"
+          background="bg"
+        >
+          <Stack gap="xs" minWidth="12rem">
+            <Text textStyle="label/L/medium">{size.label}</Text>
+            <Text textStyle="label/XS" color="fg.muted">
+              {size.helper}
+            </Text>
+          </Stack>
+
+          <HStack gap="sm" flexWrap="wrap">
+            <Button size={size.size} variant="solid">
+              Create new
+            </Button>
+            <Button size={size.size} variant="outline">
+              Secondary
+            </Button>
+            <Button size={size.size} variant="ghost">
+              <Icon as={Download} boxSize="16px" />
+              Export
+            </Button>
+            <IconButton size={size.size} variant="ghost" aria-label="Settings">
+              <Icon as={Settings} boxSize="16px" />
+            </IconButton>
+            <IconButton size={size.size} variant="outline" aria-label="Delete">
+              <Icon as={Trash2} boxSize="16px" />
+            </IconButton>
+          </HStack>
+        </HStack>
+      ))}
+    </Stack>
+  ),
+};
+
+export const IconOnly = {
+  render: () => (
+    <HStack gap="sm" flexWrap="wrap" padding="md" borderWidth="1px" borderColor="border.muted" borderRadius="md">
+      <IconButton variant="solid" aria-label="Add">
+        <Icon as={Plus} boxSize="icon-sm" />
+      </IconButton>
+      <IconButton variant="surface" aria-label="Settings">
+        <Icon as={Settings} boxSize="16px" />
+      </IconButton>
+      <IconButton variant="outline" aria-label="Download">
+        <Icon as={Download} boxSize="16px" />
+      </IconButton>
+      <IconButton variant="ghost" aria-label="Delete">
+        <Icon as={Trash2} boxSize="16px" />
+      </IconButton>
+    </HStack>
+  ),
+};