@surrealdb/ui 1.0.86 → 1.0.88

package/CLAUDE.md

@@ -0,0 +1,92 @@
+# CLAUDE.md
+
+This is `@surrealdb/ui` — the SurrealDB design system and UI component library, published to npm as a reusable package for all SurrealDB frontend projects.
+
+## Tooling
+
+- **Runtime & package manager:** Bun (do NOT use npm, yarn, or pnpm)
+- **Build:** Vite 7 in library mode, targeting ES2022 with source maps
+- **Language:** TypeScript with `isolatedDeclarations` enabled — all exported types must be explicitly annotated
+- **UI framework:** React 19 with JSX transform (`react-jsx`)
+- **Component library:** Mantine v8 (peer dependency)
+- **Linter/formatter:** Biome 2.x — 4-space indentation, 100-character line width
+- **Storybook:** Storybook 10 with `@storybook/react-vite`
+- **Testing:** Vitest with Playwright browser provider for Storybook integration tests
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `bun install` | Install dependencies |
+| `bun run build` | Production build (outputs to `dist/`) |
+| `bun run storybook:dev` | Start Storybook dev server on port 6006 |
+| `bun run storybook:build` | Build static Storybook site |
+| `bun qc` | Run Biome lint/format check |
+| `bun qa` | Auto-fix Biome lint/format issues |
+| `bun qau` | Auto-fix including unsafe fixes |
+| `bun qts` | TypeScript type check (`tsc --noEmit`) |
+| `bun test` | Run all tests |
+| `bun run icons` | Regenerate icon constants from `icons.zip` (requires `picosvg`) |
+
+## Path Aliases
+
+`@src/*` maps to `./src/*` (configured in `tsconfig.json` and resolved by `vite-tsconfig-paths`).
+
+## Styling
+
+- SCSS modules (`.module.scss`) with `dashesOnly` locals convention — access classes as `styles.myClass`, not `styles["my-class"]`
+- All `.scss` files auto-import `@surrealdb/ui/mixins` via Vite's `additionalData`, providing global access to theme-aware mixins:
+  - `@include light { ... }` / `@include dark { ... }` — color scheme scoping
+  - `@include sm-and-up { ... }`, `@include md-and-down { ... }`, etc. — responsive breakpoints
+  - `@include background-blur { ... }` — backdrop blur with fallback
+- Global CSS variables are defined in `src/assets/styles/global.scss` (prefixed `--surreal-*`)
+- Mantine design tokens available as `--mantine-color-*` CSS variables
+- Build output CSS is automatically wrapped in `@layer surreal` by a custom Vite plugin
+
+## Exports
+
+The package exposes three entry points:
+- `@surrealdb/ui` — all components, hooks, helpers, and constants (from `src/index.ts`)
+- `@surrealdb/ui/styles.css` — compiled CSS (wrapped in `@layer surreal`)
+- `@surrealdb/ui/mixins` — raw SCSS mixins (from `res/_mixins.scss`)
+
+## Source Structure
+
+```
+src/
+├── assets/          # Static assets: brand SVGs, picto WebPs, global SCSS styles
+├── constants/       # Generated/static constants (icons.ts, brands.ts, pictos.ts)
+├── editor/          # CodeMirror editor setup: extensions, keybinds, commands, theme
+├── helpers/         # Utility functions (clsx, brandsafe URL helper, ID generator)
+├── hooks/           # React hooks (useEditor, useStable, useLater, useSort, useSwitch)
+├── lib/
+│   ├── markdown/    # Custom stack-based markdown parser and React renderer
+│   └── yoopta/      # Yoopta block editor plugins (Mantine-styled)
+├── primitives/      # React UI components (Icon, CodeBlock, Spinner, VideoPlayer, etc.)
+├── stories/         # Storybook stories organized by category
+├── syntax/          # Syntax highlighting: language definitions, highlighter, theme
+├── theme/           # Mantine theme override (mantine.ts)
+└── types/           # TypeScript module augmentations for Mantine (colors, variants, spacing)
+```
+
+Other top-level directories:
+- `res/` — SCSS mixins exported as `@surrealdb/ui/mixins`
+- `tools/` — Icon parser script (`icon-parser.ts`)
+- `.storybook/` — Storybook configuration (main, preview, vitest setup)
+- `.github/workflows/` — CI (`check.yml`) and publish (`publish.yml`) workflows
+- `dist/` — Build output (gitignored)
+
+## Peer Dependencies
+
+Consumers must provide: React 19, Mantine 8, CodeMirror 6 suite, Yoopta 6, and Slate. These are externalized during build.
+
+## CI/CD
+
+- **check.yml** — Runs on push/PR to `main`: Biome lint, TypeScript check, build, and tests (Bun 1.2.23)
+- **publish.yml** — Triggered by GitHub release: asserts `package.json` version matches git tag, builds, packs, and publishes to npm
+
+## Conventions
+
+- `useStable` hook is configured as returning a stable reference in Biome's `useExhaustiveDependencies` rule — do not list its return value in dependency arrays
+- The `src/constants/icons.ts` file is auto-generated — do not edit it manually
+- Biome excludes: `.vscode/`, `.github/`, `.storybook/`, `src/constants/icons.ts`, `dist/`, and `*.js` files

package/REVIEW.md

@@ -0,0 +1,81 @@
+# Code Review Guidelines
+
+Before marking any task as done, verify every applicable section below.
+
+## Code Quality
+
+- **Biome**: run `bun qc` and confirm zero errors. Do not suppress or ignore lint rules without justification.
+- **TypeScript**: run `bun qts` and confirm zero type errors. All exported functions and types must have explicit type annotations (`isolatedDeclarations` is enabled).
+- **Formatting**: 4-space indentation, 100-character line width, multiline JSX attributes. Run `bun qa` to auto-fix if needed.
+- **Unused imports**: Biome warns on unused imports — remove them before committing.
+- **Unused code**: do not leave behind dead code, commented-out blocks, or `console.log` statements.
+
+## Components
+
+- **Mantine first**: use Mantine components (`Box`, `Text`, `Group`, `Stack`, etc.) over raw HTML elements. Use `<Box>` instead of `<div>`.
+- **Props interface**: extend `BoxProps` or the appropriate Mantine component props type. Export the props interface alongside the component.
+- **Prop spreading**: spread remaining props (`...rest`) onto the root element so consumers can pass through Mantine attributes.
+- **clsx**: use `clsx` from `@src/helpers/clsx` (the project's own implementation), not the npm `clsx` package.
+- **Return type**: use `ReactNode` for function declarations or `FC<Props>` for arrow functions — match the convention of surrounding code.
+
+## Styling
+
+- **SCSS modules**: styles go in `style.module.scss` next to the component. Import as `import classes from "./style.module.scss"`.
+- **dashesOnly**: access class names as `classes.myClass`, never `classes["my-class"]`.
+- **Dynamic values**: use Mantine's `__vars` prop to pass CSS custom properties for dynamic size/color — not inline styles.
+- **Design tokens**: reference Mantine tokens (`--mantine-color-*`) and SurrealDB tokens (`--surreal-*`). Do not hardcode color hex values in SCSS unless defining a new token.
+- **Light/dark theme**: any color that differs between themes must use `@include light { ... }` and `@include dark { ... }` mixins. Verify the component looks correct in both color schemes.
+- **Responsive**: use the breakpoint mixins (`@include sm-and-up`, `@include md-and-down`, etc.) instead of raw `@media` queries.
+- **No global styles**: do not add styles to `global.scss` or `variants.scss` unless defining a new design token. Component styles belong in SCSS modules.
+
+## Exports
+
+- **Re-export from index**: new components, hooks, helpers, or types must be re-exported from `src/index.ts`. Missing re-exports break the public API.
+- **Explicit type exports**: use `export type` for type-only exports (required by `isolatedDeclarations` and `verbatimModuleSyntax`).
+
+## Storybook
+
+- **Story exists**: every primitive component must have a corresponding story in `src/stories/primitives/`. Mantine-themed component demos go in `src/stories/mantine/`.
+- **CSF3 format**: stories must use Component Story Format 3 with a typed `meta` default export and `StoryObj` named exports.
+- **Title convention**: use the correct prefix (`Primitives/`, `Mantine/`, `Catalog/`, or `Playground/`) in the story `title`.
+- **No providers in stories**: do not wrap stories in `MantineProvider` — this is handled globally by `.storybook/preview.tsx`.
+- **Shared arg types**: reuse `size` and `icon` from `src/stories/arg-types/` instead of redefining them.
+
+## Testing
+
+- **Tests pass**: run `bun test` and confirm all tests pass. Do not skip or disable tests without justification.
+- **Markdown parser**: changes to `src/lib/markdown/` must include tests. Run `bun test src/lib/markdown/__tests__` to verify. Update snapshots only when the change is intentional.
+- **Snapshot review**: if snapshots are updated, verify the diff reflects the intended change — not unrelated side effects.
+
+## Dependencies
+
+- **Justify new packages**: new external dependencies require justification. Prefer small helper functions over adding utility packages.
+- **Peer vs direct**: UI framework dependencies (React, Mantine, CodeMirror, Yoopta, Slate) are peer dependencies — never add them to `dependencies`.
+- **Package manager**: use `bun` exclusively. Do not use npm, yarn, or pnpm commands. Do not commit `package-lock.json`, `yarn.lock`, or `pnpm-lock.yaml`.
+
+## Generated Files
+
+- **Do not edit**: `src/constants/icons.ts` is auto-generated by `bun run icons`. Never edit it manually.
+- **Do not edit**: `bun.lock` is managed by Bun. Do not manually modify it.
+- **Do not commit**: `dist/`, `node_modules/`, `storybook-static/`, and `.tgz` files are gitignored.
+
+## Security
+
+- **No secrets**: credentials, tokens, and API keys must not appear in source code, console logs, or error messages.
+- **No `.env` files**: do not commit `.env` or any environment variable files.
+
+## Build Compatibility
+
+- **ES2022 target**: do not use syntax or APIs that require a target newer than ES2022.
+- **Tree-shaking**: the package is marked `"sideEffects": false`. Ensure new modules do not introduce top-level side effects outside of style imports.
+- **CSS layer**: all component CSS is wrapped in `@layer surreal` at build time. Do not add `@layer` directives in SCSS modules — the Vite plugin handles this.
+
+## Hooks
+
+- **useStable**: the return value of `useStable` is a stable reference — do not include it in React dependency arrays. Biome enforces this automatically.
+- **useExhaustiveDependencies**: Biome enforces exhaustive deps at error level. Do not suppress this rule; fix the dependency array instead.
+
+## Skip
+
+- Formatting and linting auto-fixes (enforced by `bun qa` / `bun qau`).
+- Biome-excluded files: `.vscode/`, `.github/`, `.storybook/`, `src/constants/icons.ts`, `dist/`, `*.js`.

package/dist/ui.d.ts

@@ -8,6 +8,7 @@ import { ButtonProps } from '@mantine/core';
 import { CalloutElementMap } from '@yoopta/callout/dist/types';
 import { CodeProps } from '@mantine/core';
 import { Command } from '@codemirror/view';
+import { default as default_2 } from 'github-slugger';
 import { DividerElementMap } from '@yoopta/divider/dist/types';
 import { EditorSelection } from '@codemirror/state';
 import { EditorView } from '@codemirror/view';
@@ -396,7 +397,7 @@ export declare interface CommonAttrs {
 export declare const commonExtensions: () => Extension;
 
 /**
- * Create a style highlighter for the given color scheme and syntax theme
+ * Get a cached style highlighter for the given color scheme
  */
 export declare function createHighlighter(colorScheme: MantineColorScheme): Highlighter;
 
@@ -565,6 +566,8 @@ export declare const iconAccountPlus: string;
 
 export declare const iconAccountSecure: string;
 
+export declare const iconAlert: string;
+
 export declare const iconAPI: string;
 
 export declare const iconArrowDownFat: string;
@@ -879,6 +882,8 @@ export declare const iconTextBoxPlus: string;
 
 export declare const iconTransfer: string;
 
+export declare const iconTrash: string;
+
 export declare const iconTune: string;
 
 export declare const iconUniversity: string;
@@ -1197,6 +1202,7 @@ export declare interface ParserState {
     stack: string[];
     root: BlockNode[];
     currentContainer: BlockNode[];
+    slugger: default_2;
 }
 
 export declare const picto2106: string;