@surrealdb/ui 1.2.16 → 1.2.17

package/doc/code-style.md

@@ -1,264 +0,0 @@
-# Code Style
-
-This document describes how code is written in the SurrealDB UI Kit. It is
-derived from analysing the existing source under `src/`, which is the
-**leading** authority: when in doubt, match the surrounding code. The goal is
-that anyone can write new code indistinguishable from what is already there.
-
-Formatting (tabs, 100-column width, one-attribute-per-line JSX, import ordering)
-is enforced by oxfmt. This document covers the conventions the formatter and
-linter do **not** enforce: structure, naming, comments, and idiom.
-
-## Files and extensions
-
-- **`.tsx` everywhere in `/src`** — including files
-  that contain no JSX (for example `api/helpers.tsx`, `api/keys.tsx`,
-  `api/publisher.tsx`). The framework packages use `.tsx` as the default source
-  extension.
-- **Component folders** are `PascalCase` and contain an `index.tsx` plus, when
-  needed, a `style.module.scss`. Sub-parts of a component live beside it as
-  lowercase files (e.g. `section.tsx`, `view.tsx`, `list.tsx`) or in nested
-  `PascalCase` folders.
-- **Hook and utility files** are `kebab-case`: `use-stable.tsx`,
-  `use-registry.tsx`, `make-panel-type.tsx`, `clone.ts`.
-- **SCSS modules** are always named `style.module.scss` and imported as
-  `import classes from "./style.module.scss"`.
-
-## Components
-
-**Always define components as typed `const` arrow functions, never as `function`
-declarations.** This is the dominant convention across `core`.
-
-```tsx
-export interface EntryButtonProps
-  extends ButtonProps, ElementProps<"button">, RefAttributes<HTMLButtonElement> {}
-
-export const EntryButton: FC<...> = ({ children, className, ...other }) => {
-  return (
-    <Button
-      {...other}
-      className={clsx(classes.root, className)}
-    >
-      {children}
-    </Button>
-  );
-};
-```
-
-Conventions:
-
-- Type the component with `FC` (or `FC<Props>`) imported from `react`, and
-  destructure props in the parameter list.
-- Name the props interface `<Component>Props`. Extend Mantine prop types
-  (`ButtonProps`, `BoxProps`, `ElementProps<"...">`), `PropsWithChildren`, and
-  `RefAttributes<...>` where relevant, rather than re-declaring common props.
-- **Named exports** are the norm; avoid default exports.
-- When a component needs an inner implementation (for example to sit behind a
-  `<Suspense>` or memo boundary), the exported component is a thin wrapper and the
-  implementation is a private `const XxxInner: FC<...>` in the same file:
-
-```tsx
-export const WorkspaceMixin: FC<WorkspaceMixinProps> = memo((props) => (
-	<Suspense>
-		<WorkspaceMixinInner {...props} />
-	</Suspense>
-));
-
-const WorkspaceMixinInner: FC<WorkspaceMixinProps> = ({ depotKey, name, weight }) => {
-	// ...
-};
-```
-
-- Boolean props read as flags: `with*` (`withBackground`, `withDebug`), `is*`
-  (`isActive`, `isFocused`), or `show*` (`showResults`, `showSidebar`).
-- JSX attributes are placed one-per-line (oxfmt `singleAttributePerLine: true`);
-  do not fight the formatter by collapsing them.
-
-## Event handlers
-
-Interactive handlers are named `handle<Event>` and wrapped in `useStable` so they
-keep a stable identity across renders:
-
-```tsx
-const handleSidebarToggle = useStable(() => {
-	setShowSidebar(!showSidebar);
-});
-```
-
-`useStable` (from `src/hooks`) is preferred over `useCallback` for
-callbacks whose dependencies would otherwise churn; it is registered with Biome
-as a stable-result hook, so it does not need a dependency array.
-
-## Hooks
-
-- Custom hooks are `use<Thing>` and live in `src/hooks/` (core-wide) or beside the
-  feature they serve.
-- **Context hooks** read a context with `use(SomeContext)` and throw a typed
-  error when used outside their provider, rather than returning `null`:
-
-```tsx
-export function useTabs(): TabsContext {
-	const ctx = use(TabsContext);
-
-	if (!ctx) {
-		throw new SurrealistError("Component must be wrapped in a <Workspace> component");
-	}
-
-	return ctx;
-}
-```
-
-- A context, its `use*` accessor, and its `Provider` component typically share a
-  file. The context value interface and the context object often share the same
-  name (`interface TabsContext` and `const TabsContext = createContext(...)`).
-- Utility hooks are exceptions to the arrow-component rule and are written as
-  `export function` (e.g. `useStable`, `useRegistry`, `useTabs`). Components use
-  `const` + `FC`; standalone functions and hooks use `function`.
-
-## Functions and utilities
-
-- Standalone, non-component functions use `export function foo(...)` with explicit
-  return types where they are part of a public surface.
-- Pure helpers live in utility modules and are small and
-  single-purpose (`generateId`, `delegate`, `dedent`, `extractError`, `bail`,
-  `sanitizeId`).
-- Prefer early returns and guard clauses over deep nesting.
-
-## Types and interfaces
-
-- Use `interface` for object shapes, component props, and context values; use
-  `type` for unions, aliases, mapped/conditional types, and function-type
-  aliases.
-- Union-of-literals is the norm for enumerations
-  (`type Platform = "darwin" | "windows" | "linux"`,
-  `type UpdateType = "metadata" | "state"`).
-- Discriminated unions use a `kind` field, with `is*` type guards:
-
-```ts
-export type ProviderEntry = FolderEntry | ModelEntry;
-
-export const isFolder = (item: ProviderEntry): item is FolderEntry => item.kind === "folder";
-export const isModel = (item: ProviderEntry): item is ModelEntry => item.kind === "model";
-```
-
-- Generic type parameters are single uppercase letters (`T`, `K`, `A`, `S`, `U`),
-  matching the panel/registry/depot generics.
-- Deliberate exceptions to a lint rule use an inline
-  `// oxlint-disable-next-line <rule>: <reason>` comment, always with a trailing
-  reason. The Biome-owned `useExhaustiveDependencies` rule is the exception — it
-  still reads `// biome-ignore lint/correctness/useExhaustiveDependencies` comments.
-
-## Naming
-
-- **Variables, functions, props, methods:** `camelCase`.
-- **Components, classes, interfaces, types:** `PascalCase`.
-- **Module-level constants:** `SCREAMING_SNAKE_CASE` — e.g. `LOG_TAG`,
-  `CONFIG_CACHE`, `DEFAULT_PANELS`, `WORKSPACE_PROVIDER`, `THEME_DATA_RETRIEVAL`,
-  `OPACITY_STRONG`, `ENTITY_TYPES`, `FullSync`. (A small number of local
-  singletons like `FullSync` use `PascalCase`; module-wide exported constants use
-  `SCREAMING_SNAKE_CASE`.)
-- **Refs:** suffix with `Ref` (`onChangeInner`, `modelEntryCacheRef`,
-  `collectRef`).
-- **Design tokens:** colours are `THEME_*` (`THEME_DATA_RETRIEVAL`,
-  `THEME_SCHEMA`, `THEME_ADMIN`, ...); opacities are `OPACITY_*`
-  (`OPACITY_SUBTLE`, `OPACITY_MEDIUM`, `OPACITY_STRONG`).
-- **Icons and pictos:** `icon<Name>` (`iconQuery`, `iconCog`, `iconNamespace`)
-  and `picto<Name>` (`pictoSurrealist`), imported from the core UI layer.
-- **Event names** use a namespaced, double-colon convention on the IPC/electron
-  boundary (`window::maximize`, `window::toggle-fullscreen`).
-- **SCSS class names** are `kebab-case` in the stylesheet and accessed as
-  `camelCase` via the `classes` object (`.save-box` → `classes.saveBox`).
-
-## Comments
-
-Two distinct comment styles are used, and both matter:
-
-1. **Multi-line JSDoc block comments (`/** ... */`)** document exported functions, classes,
-   interfaces, class members, and interface members. They describe intent, and
-   use `@param`/`@returns`/`@example` where helpful. Nearly every public method
-   on `Depot`, `Panel`, `ModelProvider`, and the hooks carries one:
-
-```ts
-/**
- * Get a value from the storage backend.
- *
- * @param key - The key of the value to get.
- * @returns A promise that resolves with the value.
- */
-async get<K extends keyof T>(key: K): Promise<T[K] | null> { ... }
-```
-
-2. **Short single-line comments (`// ...`)** explain _why_ a block of logic exists
-   or mark the steps of a longer procedure. They sit directly above the code they
-   describe and read as terse imperative phrases:
-
-```ts
-// Focus or replace the model if it is already open
-for (const key of currentKeys) {
-  // Focus the existing model
-  if (models.includes(uriString)) { ... }
-
-  // Replace an existing model
-  if (replaceUriString && models.includes(replaceUriString)) { ... }
-}
-
-// Create a new region
-const newKey = generateId();
-```
-
-**Do not** restate the code; explain the reason behind logic or explain the use case to a public facing audience.
-Longer procedural functions (like tab open/close logic) are essentially outlined by these step-comments.
-
-**Do not** make any references to the planning phases or phrase comments from a first person perspective.
-
-## Whitespace and vertical rhythm
-
-Blank lines are used deliberately to separate **logical units**, not
-arbitrarily. The consistent pattern is:
-
-- One blank line between the imports block and the first declaration.
-- One blank line separating each logical step inside a function — typically a
-  step introduced by a `// ...` comment is preceded by a blank line:
-
-```ts
-const newSchema = { ...schema };
-
-// Synchronize root schema
-if (options.root) {
-  ...
-}
-
-// Synchronize namespace schema
-if (surreal.namespace && options.namespace) {
-  ...
-}
-```
-
-- One blank line between members of a class/interface, and between grouped
-  declarations.
-- Related declarations are grouped together with no blank lines between them,
-  then separated from the next group by a single blank line. For example, a block
-  of `useLocalDepotState` calls is grouped, then a blank line precedes the refs:
-
-```tsx
-const [regionKeys, setRegionKeys] = useLocalDepotState(depot, "regionKeys", [], true);
-const [regionModels, setRegionModels] = useLocalDepotState(depot, "regionModels", {}, true);
-const [regionActives, setRegionActives] = useLocalDepotState(depot, "regionActives", {});
-
-const modelEntryCacheRef = useRef(new Map<string, ModelEntry>());
-const providers = modelProviders.mapping();
-```
-
-Never use more than one consecutive blank line.
-
-## Imports and exports
-
-- oxfmt organises imports automatically (`sortImports`); do not hand-sort them.
-  Imports are grouped — external packages, then internal, then local/relative —
-  with a blank line between groups, and sorted within each group.
-- Use **named exports**. Barrel `index.tsx` files re-export a package's public
-  surface with `export *` and named re-exports, grouped by area with a short
-  comment header per group (see `core/src/index.tsx`, whose sections are labelled
-  `// API exports`, `// Foundation exports`, `// Hooks exports`, etc.).
-- Import type-only symbols with `import type { ... }` (`verbatimModuleSyntax` is
-  on, so this is required for types).

package/doc/release.md

@@ -1,102 +0,0 @@
-# Release process
-
-This document describes how to cut a release of `@surrealdb/ui`.
-
-## 1. Determine the version bump
-
-Releases follow [semantic versioning](https://semver.org/) (`x.y.z`).
-
-- **Patch** (`x.y.Z`) — the default. Unless the release is explicitly stated
-  to be a minor or major, always assume it is a patch.
-- **Minor** (`x.Y.0`) — only when explicitly stated (new backwards-compatible
-  features).
-- **Major** (`X.0.0`) — only when explicitly stated (breaking changes).
-
-## 2. Determine the next version
-
-Read the current version from `package.json` (the `version` field) and apply
-the bump from step 1.
-
-For example, if the current version is `1.2.12`:
-
-| Bump  | Next version |
-| ----- | ------------ |
-| patch | `1.2.13`     |
-| minor | `1.3.0`      |
-| major | `2.0.0`      |
-
-The resulting `x.y.z` is used for the branch name, the `package.json` version,
-and the pull request title below.
-
-## 3. Create the release branch
-
-Branch off the latest `main`:
-
-```sh
-git checkout main
-git pull
-git checkout -b release/x.y.z
-```
-
-## 4. Bump the `package.json` version
-
-Set the `version` field in `package.json` to the new `x.y.z`.
-
-## 5. Format, test, and fix
-
-1. Run the formatter and apply any fixes:
-
-    ```sh
-    bun run qa
-    ```
-
-    If this produces changes (formatting that was previously missing), commit
-    them.
-
-2. Run the test suite:
-
-    ```sh
-    bun run test
-    ```
-
-3. Iteratively fix any broken tests, re-running the suite until it passes.
-   Commit the fixes.
-
-## 6. Commit and push
-
-Commit the version bump (and any formatting/test fixes) and push the branch:
-
-```sh
-git push -u origin release/x.y.z
-```
-
-## 7. Open the pull request
-
-Open a pull request from `release/x.y.z` into `main`.
-
-- **Title:** `Release x.y.z`
-- **Description:** a bullet-point list of the PRs included in this release,
-  each linking to its PR. Format each entry as:
-
-    ```md
-    - Did something (#100)
-    ```
-
-    where `#100` links to the corresponding pull request. Compile the list from
-    the PRs merged into `main` since the previous release.
-
-> **The PR description becomes the release notes**, so make sure it is
-> complete and well-formed before merging.
-
-## 8. Merge the pull request
-
-Merging the `release/x.y.z` branch into `main` is all that's required — the
-[Publish workflow](../.github/workflows/publish.yml) takes over automatically:
-
-1. It infers the tag `vx.y.z` from the branch name and asserts it matches the
-   `package.json` version.
-2. It creates the GitHub release, using the PR description as the release notes.
-3. It builds, packs, and publishes the package to npm.
-
-No manual GitHub release or tag is needed. (Publishing a GitHub release by hand
-still works as a fallback — it triggers the same build-and-publish steps.)

package/doc/stacker-plan.md

@@ -1,219 +0,0 @@
-# Stacker v2 — Responsive modal/drawer overlay manager
-
-## Context
-
-Rewrite `src/lib/stacker` **from scratch** (replacing the previous attempt entirely). Stacker becomes a single imperative API for spawning overlays that render as **modals on desktop and drawers on mobile**, chosen automatically per stack, exposed as `<StackerProvider>` + `useStacker()` (Mantine modals-manager style). It must be built on Mantine's lower-level compound primitives (`Modal.Root`/`Drawer.Root`/`ModalBase*`) rather than the opinionated `<Modal>`/`<Drawer>`.
-
-Key behaviors (authoritative requirements):
-
-- **Single `open()`** receives one content + chrome props; kind chosen live from the viewport (mobile → drawer), forceable via optional `variant` on the **first** stack item. Later items' `variant` hints are ignored for rendering. Resizing remounts the matching host immediately.
-- **Nested stack** like Mantine Modal Manager: closing the top reveals the previous.
-- **Modals**: only ever ONE modal rendered; pushes/pops animate a content swap (scale/fade). ONE scrim (`<Overlay>`) that darkens/fades only — never scales the page.
-- **Drawers**: lower drawers stay mounted & peek out behind the top one (shadcn nested look), their **content faded to opacity 0** (sheet surface stays visible). ONE scrim + the page content scales down slightly (fixed amount, no per-depth compounding).
-- `title` + `subtitle` (under title); close button pinned top-right even when title/subtitle wrap.
-- `side` hint (drawer-only, **default "right"** per user), `draggable` hint (drawer-only, vaul-style velocity drag-to-dismiss).
-- Mobile breakpoint: **`sm` = 48em/768px** (per user), overridable via provider `mobileQuery` prop.
-- Storybook stories + unit + e2e tests.
-
-## Verified Mantine 9.2.2 facts that drive the design
-
-1. `Transition` never animates on initial mount (`useDidUpdate`) → every Root mounts `opened=false` and flips true in a mount effect (two-phase mount).
-2. In the `entered` state, Transition keeps its `in` styles **inline on `Modal.Content`/`Drawer.Content` permanently** → our depth/drag/swap transforms must live on inner elements we own, never on Mantine's Content.
-3. Every mounted `ModalBase` registers its own window-capture Escape listener gated only by its own `closeOnEscape` → with N drawer roots mounted, set `closeOnEscape` **only on the top** root.
-4. Theme `defaultProps` do NOT reach compound roots (keys are `ModalRoot`/`DrawerRoot`) → replicate house defaults explicitly (modal: `size "lg"`, `radius "sm"`, `centered`, `padding "xl"`). Theme `Overlay` (opacity .25, blur 4) and `CloseButton` (surreal, custom icon) defaults DO apply — free consistency.
-5. `ModalBase*` parts (`ModalBaseTitle/Body/...`) are exported from `@mantine/core` root and share one context with both Modal and Drawer → one shared header/body chrome component works in both paths with correct `aria-labelledby`/`aria-describedby`.
-6. `onExitTransitionEnd`/`onEnterTransitionEnd` are first-class Root props → use for REMOVE dispatch.
-7. `Drawer.Content` has `overflow-y: auto` and `data-hidden` means `opacity: 0 !important` on the whole content → neutralize Content (transparent, `overflow: visible`), never use `__hidden`; scrolling moves into our `.body`.
-8. `RemoveScroll` is refcounted → per-root `lockScroll` default is safe with N mounted roots.
-9. Drawer `position` auto-picks slide transition (top→slide-down, bottom→slide-up, left→slide-right, right→slide-left); positioning is CSS-vars, not data attributes.
-10. `useDrag` (@mantine/hooks) provides movement/velocity/direction with document-level listeners → synthetic PointerEvents work for e2e drag tests.
-11. `useMediaQuery(query, initial, { getInitialValueInEffect: false })` reads matchMedia synchronously.
-12. Repo: `isolatedDeclarations` (annotate all exports), SCSS modules `dashesOnly`, `clsx` from `@src/helpers/clsx`, `generateRandomId` from `@src/helpers/id`, `useStable` from `src/hooks/use-stable.tsx`, `src/index.ts` already re-exports `./lib/stacker`.
-
-## File layout — `src/lib/stacker/` (delete all 11 existing files)
-
-| File                  | Responsibility                                                                                                                                                                                                                                                  |
-| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `index.ts`            | Public re-exports (components, hook, types, `stackerReducer`, pure helpers for tests)                                                                                                                                                                           |
-| `types.ts`            | `StackerKind`, `StackerSide`, `StackerSettings`, `StackerItem`, `StackerContextValue`                                                                                                                                                                           |
-| `config.ts`           | Constants: `STACKER_MOBILE_QUERY = "(max-width: 48em)"`, z base 200, durations (root 200ms, swap 220ms, drawer 300ms, page 400ms), easing `cubic-bezier(0.32, 0.72, 0, 1)`, `DRAWER_PEEK_PX 12`, `DRAWER_DEPTH_SCALE 0.04`, `PAGE_SCALE 0.98`, `PAGE_RADIUS 12` |
-| `helpers.ts`          | Pure: `resolveKind(variant, isMobile)`, `resolveLiveKind(items, isMobile)`, `drawerDepthStyle(side, depth)`, `topOpened(items)`                                                                                                                                 |
-| `reducer.ts`          | `stackerReducer` — OPEN/CLOSE/CLOSE_ALL/REMOVE/UPDATE (items only; no stored kind)                                                                                                                                                                              |
-| `context.ts`          | `StackerContext`, `useStacker()` (throws outside provider)                                                                                                                                                                                                      |
-| `provider.tsx`        | `StackerProvider`: reducer, `useMediaQuery`, stable callbacks, page-scale shell, mounts one host by kind                                                                                                                                                        |
-| `modal-host.tsx`      | The single `Modal.Root` tree; REMOVE on root exit                                                                                                                                                                                                               |
-| `modal-swap.tsx`      | Content cross-swap state machine (current/leaving panes, push/pop direction, cleanup, reduced motion)                                                                                                                                                           |
-| `drawer-host.tsx`     | Shared scrim (Portal + Transition + `<Overlay fixed>`) + one `Drawer.Root` per item                                                                                                                                                                             |
-| `drawer-sheet.tsx`    | Per-item inner sheet: depth transform, content fade, drag wiring, handle                                                                                                                                                                                        |
-| `chrome.tsx`          | `StackerHeader` (title/subtitle/close, `live` vs inert mode) + `StackerBody`                                                                                                                                                                                    |
-| `use-drag-dismiss.ts` | Port of existing hook nearly as-is (`position`→`side`); pure `shouldDismiss` kept                                                                                                                                                                               |
-| `style.module.scss`   | Page shell, sheet, content fade, handle, header, swap panes/keyframes, reduced-motion                                                                                                                                                                           |
-| `AGENTS.md`           | Rewritten module doc                                                                                                                                                                                                                                            |
-
-### Public API
-
-```ts
-type StackerKind = "modal" | "drawer";
-type StackerSide = "left" | "right" | "top" | "bottom";
-
-interface StackerSettings {
-  id?: string;                       // default generateRandomId()
-  title?: ReactNode;
-  subtitle?: ReactNode;              // under title
-  children?: ReactNode;              // THE one content
-  variant?: StackerKind;             // first-overlay hint only
-  side?: StackerSide;                // drawer-only, DEFAULT "right"
-  draggable?: boolean;               // drawer-only, default false
-  size?: MantineSize | (string & {}) | number;  // modal default "lg", drawer "md"
-  padding?: MantineSpacing;          // default "xl"
-  withCloseButton?: boolean;         // default true
-  closeOnEscape?: boolean;           // default true
-  closeOnClickOutside?: boolean;     // default true
-  onClose?: () => void;
-}
-
-useStacker(): { open(settings?): string; close(id?): void; closeAll(): void;
-                update(id, patch): void; stack: StackerItem[]; kind: StackerKind | null }
-
-<StackerProvider mobileQuery?: string /* default "(max-width: 48em)" */ zIndex?: number>
-```
-
-## State & reducer
-
-`{ items: StackerItem[] /* bottom→top; opened=false = playing exit */ }`
-
-- **OPEN** `{item}`: existing id → no-op if open, **revive** (flip opened, merge settings) if closing; else append.
-- **CLOSE**: flip `opened=false` (idempotent, same-ref no-op).
-- **CLOSE_ALL**: flip all.
-- **REMOVE**: filter id.
-- **UPDATE**: shallow-merge patch.
-
-Provider `open()` (stable via `useStable`, state via ref): dispatches `{ item }` only. Live kind is `resolveLiveKind(items, isMobile)` = first item's `variant` ?? viewport.
-Provider `close(id?)`: target = id or top opened item; skip if already closing (onClose fires once); fire `onClose`; **non-top modal → immediate REMOVE** (it isn't rendered, no animation); else CLOSE.
-
-Edge cases: double-close = no-op; reopen mid-exit = revive (Transition reverses); viewport change mid-stack remounts the matching host with the same items.
-
-## Modal path — ONE `Modal.Root` for the whole stack
-
-```
-<Modal.Root opened={entered && anyOpen} onClose={() => close()}
-    closeOnEscape={top.closeOnEscape} closeOnClickOutside={top.closeOnClickOutside}
-    trapFocus returnFocus lockScroll centered radius="sm"
-    padding={top.padding ?? "xl"} size={top.size ?? "lg"}
-    transitionProps={{ transition: "pop", duration: 200, timingFunction: EASING }}
-    onExitTransitionEnd={removeAllClosedItems} zIndex={zIndex}>
-  <Modal.Overlay data-stacker-scrim />          ← THE single scrim (darken/fade only)
-  <Modal.Content data-stacker="modal">
-    <ModalSwap top={lastItemRegardlessOfOpened} onLeaveEnd={removeIfStillClosed}>
-      pane: <StackerHeader live /> + <StackerBody />
-    </ModalSwap>
-  </Modal.Content>
-</Modal.Root>
-```
-
-- Escape + overlay click funnel through `onClose` → pops top. Native Mantine focus trap/scroll lock/portal.
-- When the LAST item pops, content persists (swap keyed on last item, not last _open_) while the Root plays exit; `onExitTransitionEnd` REMOVEs → kind reset.
-
-### Swap mechanism (`modal-swap.tsx`)
-
-- Derived-state-in-render: when top id ≠ current id, `setLeaving({item: current, direction})`, `setCurrent(top)` during render (no flash frame). Direction: old current still in items → "push", else "pop".
-- Layout: `.swap { display:grid }`, `.pane { grid-area: 1/1; min-width: 0 }` (panes overlap; no height animation in v1).
-- CSS keyframes 220ms, fill-mode both, direction-aware deck: push = old scales back to 0.94 + fades, new enters from 1.06; pop = reversed.
-- Leaving pane is `inert aria-hidden` with `live={false}` chrome (plain markup — avoids duplicate `ModalBaseTitle` aria ids).
-- Cleanup: `onAnimationEnd` → `onLeaveEnd(id)` → provider REMOVEs only if item still present with `opened === false`; `setTimeout(duration+100)` fallback. Reduced motion (`useReducedMotion`): skip leaving pane entirely, instant swap.
-- Focus: entering pane `tabIndex={-1}`, focused (preventScroll) when `document.activeElement` collapsed to body.
-
-## Drawer path — one `Drawer.Root` per item + standalone scrim
-
-```
-<Portal>
-  <Transition mounted={anyOpen} transition="fade" duration={200}>
-    {(styles) => <Overlay fixed data-stacker-scrim style={styles} zIndex={zIndex}
-                   onClick={() => topAllowsClickOutside && close()} />}
-  </Transition>
-</Portal>
-{items.map((item, index) =>
-  <Drawer.Root opened={entered && item.opened} onClose={() => close(item.id)}
-      position={side /* default "right" */} size={size ?? "md"} padding={padding ?? "xl"}
-      closeOnEscape={isTop && closeOnEscape}     ← CRITICAL (fact 3)
-      closeOnClickOutside={false}                 ← scrim owns click-outside
-      trapFocus={isTop} returnFocus lockScroll
-      transitionProps={{ duration: 300, timingFunction: EASING }}  ← slide-* auto per position
-      onExitTransitionEnd={() => remove(item.id)} zIndex={zIndex + 1 + index}>
-    <Drawer.Content className={contentReset} data-stacker="drawer" data-covered={depth > 0}>
-      <div className={sheet} data-side data-covered style={depthOrDragTransform}>
-        {draggable && <div className={grip} ref={isTop ? dragRef : undefined}
-                        style={{ touchAction: isTop ? "none" : undefined }}><div className={handle}/></div>}
-        <StackerHeader live className={fadeItem} />
-        <StackerBody className={fadeItem} />
-      </div>
-    </Drawer.Content>
-  </Drawer.Root>)}
-```
-
-- **Standalone scrim** (not `Drawer.Overlay` in root[0]) because a mid-stack/bottom REMOVE must not tear down the scrim. z: scrim at base, roots at base+1+index.
-- **Depth visuals** (`drawerDepthStyle(side, depth)`, depth = count of opened items above): transform-origin at the **free edge**, translate away from anchor + scale, net peek = depth × 12px:
-    - right: `translateX(-12px·depth) scale(1 − 0.04·depth)`, origin `0% 50%`
-    - left: `translateX(+…)`, origin `100% 50%`; bottom: `translateY(-…)`, origin `50% 0%`; top: `translateY(+…)`, origin `50% 100%`
-- Mantine's slide transform lives on Content (outer), ours on `.sheet` (inner) — they compose, never conflict (fact 2). `.sheet { transition: transform .3s EASING }`.
-- **Content fade**: `.sheet[data-covered] :is(.header, .body) { opacity: 0 }` — surface + handle stay visible. Covered content gets `pointer-events: none` so clicks on peeking sheets fall through to the scrim.
-- **Content neutralization**: `.contentReset { background: transparent; box-shadow: none; overflow: visible }`; scrolling in `.body { flex:1; min-height:0; overflow-y:auto }`; per-side radius on `.sheet` (round free corners only).
-- **Drag**: reuse ported `use-drag-dismiss` (flick ≥ 0.5 px/ms toward edge OR past 50% of extent → dismiss); enabled only for top sheet with `draggable`; `transition: none` while dragging; spring-back via sheet transition. Drag and depth transforms never coexist (only depth-0 drags).
-
-## Page scale (drawers only)
-
-Provider wraps children: `<Box className={page} data-pushed={kind === "drawer" && anyOpen}>`. `.page[data-pushed] { transform: scale(0.98); border-radius: 12px; overflow: hidden }`, 0.4s EASING, `transform-origin: top center`, no transform when idle (keeps `position: fixed` descendants working), fixed amount regardless of depth, reduced-motion disables it. Never applied for modals.
-
-## Header (`chrome.tsx`)
-
-Flex row `align-items: flex-start`: left column `.titles { flex:1; min-width:0 }` with `ModalBaseTitle` (live) or plain div (inert) + subtitle `<Text c="dimmed" size="sm">`; right `CloseButton` `.close { flex-shrink:0; margin-inline-start:auto }` → pinned top-right regardless of wrapping. Padding via `--mb-padding`. NOT using `ModalBaseHeader` (sticky/min-height/opaque bg don't fit sheets). Body = `ModalBaseBody` (live) for `aria-describedby`.
-
-## Stories (`src/stories/primitives/Stacker.stories.tsx`, CSF3, NO play functions)
-
-1. `Default` — auto kind, nested push buttons, title/subtitle demo
-2. `MobileEmulated` — `mobileQuery="(min-width: 0px)"` + explanatory banner
-3. `ForcedModal` / `ForcedDrawer`
-4. `ModalDeck` — recursive push/pop (+ `update` title button)
-5. `StackedDrawers` — nested right drawers, peek + content fade
-6. `DrawerSides` — 4 side buttons
-7. `DraggableDrawer` — `draggable`, `size "60vh"`
-8. `CoercedStack` — drawer first, then `variant:"modal"` push renders as drawer
-9. `DismissControl` — closeOnEscape/closeOnClickOutside/withCloseButton false combos
-10. `LongHeader` — wrapping title+subtitle fixture
-11. `Lifecycle` — visible onClose counters + closeAll
-
-## Tests
-
-**Unit** (`tests/unit/Stacker/`): `reducer.test.ts` (open order/kind lock incl. all-closing stack/revive/idempotent close/remove resets kind/close-all/update), `helpers.test.ts` (`resolveKind` matrix; `drawerDepthStyle` 4 sides × depths), `drag.test.ts` (keep existing 4 `shouldDismiss` cases).
-
-**E2E** (`tests/e2e/Stacker/stacker.test.tsx`, composeStories + mountStory, selectors via `data-stacker*`):
-
-- E1 nothing mounts on render; E2 desktop auto → modal, page scale 1; E3 `MobileEmulated` → drawer + page scale < 0.99; E4 forced drawer on desktop; E5 kind coercion (2 sheets, 0 modals); E6 modal push keeps exactly ONE dialog + ONE scrim, old pane leaves DOM; E7 pop reveals previous, scrim stays mounted; E8 drawer peek geometry (lower sheet offset ≈ 12px) + lower body computed opacity 0; E9 page scale not compounding + returns to 1 after closeAll; E10 escape/scrim-click pop only top + respect opt-outs + focus returns into revealed drawer; E11 close button pinned with wrapping header; E12 drag-dismiss via synthetic PointerEvents (past 50% closes; 30px springs back); E13 onClose fires once, closeAll empties, kind resets after stack empties.
-- Delete stale `tests/e2e/Stacker/__screenshots__/`.
-
-## Implementation sequence
-
-1. `types/config/helpers/reducer` → unit tests green
-2. `context` + `provider` (callbacks, kind decision, page shell)
-3. Drawer path (`drawer-host`, `drawer-sheet`, `chrome`, SCSS, `use-drag-dismiss` port)
-4. Modal path (`modal-host`, `modal-swap`, keyframes)
-5. Stories rewrite; manual Storybook pass
-6. E2E rewrite; delete stale screenshots
-7. `AGENTS.md`; verify `src/index.ts` re-export
-
-## Verification
-
-- `npx tsc --noEmit` clean (mind `isolatedDeclarations`)
-- `npm run qc` (oxlint + biome exhaustive-deps + oxfmt) clean
-- `npx vitest run --project=unit tests/unit/Stacker --project=e2e tests/e2e/Stacker --project=storybook src/stories/primitives/Stacker.stories.tsx` all green
-- Live check in Storybook via preview server (spawn on a free port; user's own runs on 6006): no auto-open on load; modal path (single dialog, swap animation, scrim persists, page never scales); drawer path (right default, peek + content fade, page scales once, drag-dismiss); `npm run build` rolls up types
-
-## Key risks (mitigations built into design)
-
-- Transition inline styles on Content → transforms only on inner elements (2)
-- No initial-mount animation → two-phase mount everywhere (1)
-- Escape multi-close across drawer roots → closeOnEscape top-only (3)
-- `data-hidden`/`__hidden` hides sheet surface → never used; fade header/body instead (7)
-- Duplicate ARIA ids in swap → inert `live={false}` leaving pane
-- Focus tug-of-war on drawer pop → e2e asserts; fallback = delay trapFocus flip one frame or manual focus restore
-- Page transform breaks fixed descendants while drawers open → inherent vaul trade-off, no transform when idle, documented

package/release-notes.md

@@ -1,39 +0,0 @@
-Fenced code blocks tagged `tsx` or `jsx` rendered as plain, unhighlighted text in both the markdown viewer and the editor, and TypeScript blocks were silently parsed as plain JavaScript.
-
-## Cause
-
-`src/syntax/language.ts` mapped both `javascript` and `typescript` to the bare `@lezer/javascript` parser. That grammar exposes `dialects: {jsx, ts}`, but Lezer dialects are opt-in and nothing configured them.
-
-Two consequences:
-
-- `tsx` and `jsx` were not registered as languages or aliases. `findLanguageDefinition` returned `null`, so `MarkdownCodeLines` fell back to rendering each line as a bare fragment, `createMarkdownLanguage` skipped embedded highlighting in the editor, and neither appeared in the fence language picker.
-- `ts` resolved, but to a JavaScript grammar. Type annotations and `interface` declarations parsed as errors.
-
-Measured against the installed parser:
-
-```
-### ts (interface + annotations)
-   bare parser (before)   error nodes: 2
-   dialect: ts            error nodes: 0
-### tsx (JSX element)
-   bare parser (before)   error nodes: 4
-   dialect: ts            error nodes: 2
-   dialect: jsx ts        error nodes: 0
-```
-
-## Change
-
-- `javascript` now uses `dialect: "jsx"` and gains the `jsx` alias.
-- `typescript` now uses `dialect: "jsx ts"` and gains the `tsx` alias.
-
-Registering them as aliases rather than separate entries keeps the exported `Language` union and the fence language picker unchanged.
-
-Enabling `jsx` on plain JavaScript is safe. The grammar only treats `<` as a tag start where an expression may begin, so comparisons, generic calls, and shift operators parse with zero errors before and after.
-
-## Tests
-
-Adds `tests/unit/Syntax/language.test.ts` covering registration, alias resolution, JSX and TypeScript parsing, and a regression guard that plain JavaScript comparison and shift operators are not read as JSX. Four of the five fail without the fix. Full unit suite passes at 274 tests, and the library builds.
-
-## Impact
-
-Consumers get highlighting for `tsx` and `jsx` blocks, and correct highlighting for the `ts` blocks they already have. On docs.surrealdb.com that is 23 `tsx` and 2 `jsx` blocks currently unhighlighted, plus roughly 1,150 `ts` blocks that were being parsed as JavaScript.