@vvedantb/ui 0.4.4 → 0.5.1

package/src/index.ts

@@ -120,6 +120,40 @@ export type {
   SessionsHoverCardSurface,
 } from "../shell/src/SessionsHoverCard";
 
+// App shell: sidebar and main page layout. Widths come from the
+// `--app-shell-*` CSS variables that `AppShell` sets.
+export { AppShell } from "../shell/src/AppShell";
+export type { AppShellProps } from "../shell/src/AppShell";
+export { AppSidebar } from "../shell/src/AppSidebar";
+export type { AppSidebarProps } from "../shell/src/AppSidebar";
+export { SidebarRail, RailTile, RailDivider } from "../shell/src/SidebarRail";
+export type { SidebarRailProps, RailTileProps, RailDividerProps } from "../shell/src/SidebarRail";
+export { SidebarResizeHandle, useAppShellResize } from "../shell/src/SidebarResize";
+export type {
+  AppShellResize,
+  SidebarResizeHandleProps,
+  SidebarResizeOptions,
+} from "../shell/src/SidebarResize";
+export { SidebarIconTooltip } from "../shell/src/SidebarIconTooltip";
+export type { SidebarIconTooltipProps } from "../shell/src/SidebarIconTooltip";
+export { SidebarPanel } from "../shell/src/SidebarPanel";
+export type { SidebarPanelProps } from "../shell/src/SidebarPanel";
+export { SidebarAccountMenu, SidebarAccountMenuPlaceholder } from "../shell/src/SidebarAccountMenu";
+export type {
+  SidebarAccountMenuProps,
+  SidebarAccountMenuPlaceholderProps,
+} from "../shell/src/SidebarAccountMenu";
+export { SignOutDialog } from "../shell/src/SignOutDialog";
+export type { SignOutDialogProps } from "../shell/src/SignOutDialog";
+export {
+  railBadgeClass,
+  railTileClass,
+  railTileStateClass,
+  sidebarNavLinkTextClass,
+  sidebarNavRowClass,
+  sidebarSectionLabelClass,
+} from "../shell/src/app-shell-classes";
+
 // App helpers: confirm skip, update watcher, settings chrome, stable auth.
 export * from "../app/src/index";
 

package/src/motion/panel-transition.tsx

@@ -1,4 +1,15 @@
-import { ViewTransition, type ReactNode } from "react";
+import * as React from "react";
+import type { ComponentType, ReactNode } from "react";
+
+/** The `ViewTransition` props used here. Typed locally so consumers on `@types/react` without `ViewTransition` still typecheck. */
+type ViewTransitionLikeProps = {
+  children?: ReactNode;
+  default?: string;
+  enter?: string;
+  exit?: string;
+};
+
+const ViewTransition: ComponentType<ViewTransitionLikeProps> = Reflect.get(React, "ViewTransition");
 
 export interface PanelTransitionProps {
   children?: ReactNode;

package/tokens/README.md

@@ -0,0 +1,98 @@
+# `@vvedantb/ui/tokens`
+
+Design tokens and shared Tailwind v4 CSS for the vvedantb web apps. The CSS and Tailwind preset are subpaths of `@vvedantb/ui`; the native JS tokens are named exports of the root (`tokens`, `Tokens`). Source-exported: no build step. Paths in the `File` column are relative to `packages/ui/tokens/`.
+
+## Exports
+
+| Export | File | What it is |
+| --- | --- | --- |
+| `@vvedantb/ui/tokens`, `@vvedantb/ui/tokens/tokens.css` | `src/tokens.css` | Colour, radius, shadow, ease and font tokens (`@theme`), light/dark variables, `dark` variant, `*` border and `body` defaults. In 0.2.1 it also defines shadcn-style aliases (`primary`, `muted-foreground`, `secondary`, `destructive`, `card`, `popover`, `input`, `ring`) that point at the same tokens. |
+| `tokens` and `Tokens` from `@vvedantb/ui` | `src/native.ts` | JS colours, radii and spacing for React Native. `@vvedantb/native-ui` keeps its own copy in `src/tokens.ts`; a test keeps the two equal. |
+| `@vvedantb/ui/tokens/css/base.css` | `src/css/base.css` | `html` touch/accent, `::selection`, control transitions, pointer cursor, range accent (`@layer base`). |
+| `@vvedantb/ui/tokens/css/dialog.css` | `src/css/dialog.css` | Unlayered `max-width: none` for `@vvedantb/ui` compact (bottom-sheet) dialogs. |
+| `@vvedantb/ui/tokens/css/modal.css` | `src/css/modal.css` | `.t-modal`, `.is-open`, `.is-closing` and `t-modal-presence-wait` (`@layer components`). |
+| `@vvedantb/ui/tokens/css/tabs.css` | `src/css/tabs.css` | `.t-tab`, active colour, `.t-tabs-pill`, small-screen `.t-tabs` scrolling. |
+| `@vvedantb/ui/tokens/css/tabs-pills.css` | `src/css/tabs-pills.css` | `--tabs-*` colour variables, `.t-tabs--segmented`, `.t-tabs--pills` and pill hover / active fills. |
+| `@vvedantb/ui/tokens/css/utilities.css` | `src/css/utilities.css` | `@utility hit-target`, `@utility reveal-on-hover` and `@utility rounded-surface` (`clamp(0.75rem, var(--radius), 1rem)`). |
+| `@vvedantb/ui/tokens/css/scrollbar-thin.css` | `src/css/scrollbar-thin.css` | `.scrollbar-thin` (`@layer utilities`, always emitted). |
+| `@vvedantb/ui/tokens/css/animations.css` | `src/css/animations.css` | `animate-aurora`, `animate-fade-in-up`, `animate-indeterminate` as `@theme` (CSS-first apps). |
+| `@vvedantb/ui/tokens/css/compat-shadcn-rgb.css`, `@vvedantb/ui/tokens/compat/shadcn-rgb.css` | `src/css/compat-shadcn-rgb.css` | Replaces `tokens.css` for apps with shadcn-style `R G B` channel variables. Defines only the UI-only `--color-*` names as `rgb(var(--x) / alpha)` references, `--radius-field`, `--scrollbar`, `--field-radius` and a `glass-panel-strong` fallback. Import it **or** `tokens.css`, never both. |
+| `@vvedantb/ui/tokens/css/index.css` | `src/css/index.css` | base + dialog + utilities + scrollbar-thin + animations, for new CSS-first apps. |
+| `@vvedantb/ui/tokens/tailwind-preset` | `src/tailwind-preset.mjs` (+ `.d.mts`) | Tailwind preset for apps that load a JS config with `@config`. |
+
+Every file was extracted because the same rule (same at-rule context, selector and body) sits in 3 or more of the five apps. The measured duplication is in `verify/ANALYSIS.md`, and the proof that each app compiles to the same CSS after migrating is in `verify/RESULTS.md`. Blocks that only 2 apps share, or that drift in a way that would change an app's CSS, stay in the apps; `verify/ANALYSIS.md` lists them.
+
+## Use
+
+CSS-first app (no `tailwind.config`):
+
+```css
+@import "tailwindcss";
+@import "@vvedantb/ui/tokens";
+@import "@vvedantb/ui/tokens/css/animations.css";
+@import "@vvedantb/ui/tokens/css/base.css";
+/* ...app @layer base rules... */
+@import "@vvedantb/ui/tokens/css/modal.css";
+@import "@vvedantb/ui/tokens/css/tabs.css";
+/* ...app @layer components rules... */
+```
+
+App with a JS config (`@config "../tailwind.config.ts"`):
+
+```ts
+import { tokensPreset } from "@vvedantb/ui/tokens/tailwind-preset";
+
+export default {
+  presets: [tokensPreset()],
+  // or tokensPreset({ color: (name) => `color-mix(in oklch, var(--${name}) calc(<alpha-value> * 100%), transparent)` })
+  content: ["./src/**/*.{ts,tsx}"],
+  theme: { extend: { /* app-only colours, fonts, animations */ } },
+  plugins: [tailwindcssAnimate],
+};
+```
+
+The preset holds `darkMode: "class"`, the shared colour map (`border`, `surface.*`, `danger.*`, `field.*`, shadcn aliases `primary`/`secondary`/`destructive`/`card`/`popover`/`input` ...), `borderRadius` lg/md/sm/field, `boxShadow` soft/panel/insetSoft, `ease-smooth`, `screens` xs to 2xl in px, and the aurora / fade-in-up / indeterminate / accordion keyframes. It does not hold plugins, `content`, fonts, `accent`/`muted`/`ring`/`sidebar` (they differ per app) or accordion timings.
+
+Do not import `css/animations.css` in an app that uses the preset: the preset already defines the same keyframes and animations.
+
+### Where to put the imports
+
+Tailwind inlines an `@import` where it sits, even in the middle of a file (it must be at top level, not inside an `@layer` block). Put each import where the app's own copy of the rules was. Within one layer, later rules win at equal specificity, so moving shared rules above or below app rules can flip the result for elements matched by both. `examples/migration.md` gives the exact position for each app, and `pnpm --filter @vvedantb/ui verify` checks it.
+
+### Variables each file needs
+
+| File | Needs | Provided by |
+| --- | --- | --- |
+| `base.css` | `--accent`, `--foreground` | tokens.css or the app theme |
+| `dialog.css` | none | |
+| `modal.css` | `--modal-open-dur`, `--modal-close-dur`, `--modal-scale`, `--modal-scale-close`, `--modal-ease` | app `:root` |
+| `tabs.css` | `--tabs-dur`, `--tabs-ease` (app `:root`); `--tabs-text-muted`, `--tabs-text-active`, `--tabs-pill-bg` | colours: tabs-pills.css or the app theme |
+| `tabs-pills.css` | `--muted`, `--segment`, `--segment-foreground`, `--default` | tokens.css or the app theme |
+| `utilities.css` | `--breakpoint-sm` (Tailwind default or app theme) | Tailwind |
+| `scrollbar-thin.css` | `--scrollbar` | tokens.css or the app theme |
+| `animations.css` | none | |
+| `tailwind-preset` | the CSS variables named in its colour map, `--radius`, `--field-radius` | tokens.css or the app theme |
+
+### Using an existing shadcn RGB theme
+
+See the package `README.md`. With the compat file, `base.css`, `scrollbar-thin.css`, `utilities.css`, `dialog.css`, `modal.css` and `tabs.css` need no `tokens.css`. `base.css` reads `--accent` and `--foreground` and `tabs-pills.css` reads `--muted`, `--segment` and `--default`. Those are not channel-compatible, so skip `tabs-pills.css` and `index.css` (which includes `base.css`) unless the app defines those variables as full colours.
+
+### Parameters
+
+Where apps share a rule but drifted in one value, the value is a custom property whose fallback is the most common value. Set it on `:root` to keep a different value.
+
+| File | Property | Default | Set by |
+| --- | --- | --- | --- |
+| `base.css` | `--tokens-control-transition-property` | `background-color, border-color, color, box-shadow, transform, opacity` | app-c: `background-color, color, transform, opacity` |
+| `base.css` | `--tokens-control-transition-duration` | `240ms` | app-c: `100ms` |
+
+## Develop
+
+```sh
+pnpm --filter @vvedantb/ui build     # export targets exist + tsc (primitives, shell, app)
+pnpm --filter @vvedantb/ui test      # vitest (app helpers) + offline node --test: exports, CSS structure, Tailwind compile, preset
+pnpm --filter @vvedantb/ui analyze   # rule-level duplication across the app clones -> verify/ANALYSIS.tables.md
+pnpm --filter @vvedantb/ui verify    # before/after compile of every app -> verify/RESULTS.md, examples/migration.md
+```
+
+`analyze` and `verify` need the app clones (`APPS_DIR`, default `/workspace/cvx`; name or symlink the clones `app-a` to `app-e` inside it) and network access the first time: they install Tailwind 4.3.3, the plugins, postcss and jiti into a scratch directory (`VERIFY_DIR`, default `/workspace/pk-tokens-verify`, outside the repo). The migration for each app is data in `verify/migrations/<app>.json`. Each removed block must equal the shared file's block with the same context and selector, or the run fails.

package/shell/src/SessionsHoverCard.test.tsx

@@ -1,256 +0,0 @@
-// @vitest-environment happy-dom
-import { act, createRef } from "react";
-import { createRoot, type Root } from "react-dom/client";
-import { afterEach, describe, expect, it, vi } from "vitest";
-import { SessionsHoverCard } from "./SessionsHoverCard";
-
-(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
-
-let root: Root | null = null;
-let host: HTMLElement | null = null;
-
-async function mount(node: React.ReactNode) {
-  host = document.createElement("div");
-  document.body.appendChild(host);
-  root = createRoot(host);
-  await act(async () => {
-    root!.render(node);
-  });
-}
-
-afterEach(async () => {
-  await act(async () => root?.unmount());
-  host?.remove();
-  document.body.innerHTML = "";
-  root = null;
-  host = null;
-});
-
-describe("SessionsHoverCard", () => {
-  it("renders header, body and footer slots when open", async () => {
-    await mount(
-      <SessionsHoverCard open header="Head" body="Body text" footer="Foot">
-        <button type="button">Row</button>
-      </SessionsHoverCard>,
-    );
-    const text = document.body.textContent ?? "";
-    expect(text).toContain("Row");
-    expect(text).toContain("Head");
-    expect(text).toContain("Body text");
-    expect(text).toContain("Foot");
-    expect(document.body.innerHTML).toContain("w-64");
-  });
-
-  it("does not call the body render prop or loadContent while closed", async () => {
-    const body = vi.fn(() => "x");
-    const loadContent = vi.fn(() => "y");
-    await mount(
-      <>
-        <SessionsHoverCard open={false} body={body}>
-          <button type="button">A</button>
-        </SessionsHoverCard>
-        <SessionsHoverCard open={false} loadContent={loadContent}>
-          <button type="button">B</button>
-        </SessionsHoverCard>
-      </>,
-    );
-    expect(body).not.toHaveBeenCalled();
-    expect(loadContent).not.toHaveBeenCalled();
-  });
-
-  it("calls the render prop with open true and loads content once when open", async () => {
-    const body = vi.fn((ctx: { open: boolean }) => `open=${ctx.open}`);
-    const loadContent = vi.fn(async () => "Loaded preview");
-    await mount(
-      <>
-        <SessionsHoverCard open body={body}>
-          <button type="button">A</button>
-        </SessionsHoverCard>
-        <SessionsHoverCard open loadContent={loadContent} loadingFallback="Loading">
-          <button type="button">B</button>
-        </SessionsHoverCard>
-      </>,
-    );
-    expect(body).toHaveBeenCalledWith({ open: true });
-    expect(document.body.textContent).toContain("open=true");
-    expect(loadContent).toHaveBeenCalledTimes(1);
-    expect(document.body.textContent).toContain("Loaded preview");
-  });
-
-  it("portals the content to document.body by default", async () => {
-    await mount(
-      <div id="clip" style={{ overflow: "hidden" }}>
-        <SessionsHoverCard open body="Body text">
-          <button type="button">Row</button>
-        </SessionsHoverCard>
-      </div>,
-    );
-    const content = document.querySelector("[data-radix-popper-content-wrapper]");
-    expect(content).not.toBeNull();
-    expect(document.getElementById("clip")!.contains(content)).toBe(false);
-    expect(document.body.textContent).toContain("Body text");
-  });
-
-  it("keeps the content in place with portal={false}", async () => {
-    await mount(
-      <div id="clip" style={{ overflow: "hidden" }}>
-        <SessionsHoverCard open portal={false} body="Body text">
-          <button type="button">Row</button>
-        </SessionsHoverCard>
-      </div>,
-    );
-    const content = document.querySelector("[data-radix-popper-content-wrapper]");
-    expect(document.getElementById("clip")!.contains(content)).toBe(true);
-  });
-
-  it("swaps the surface without keeping the default one", async () => {
-    await mount(
-      <>
-        <SessionsHoverCard open surface="glass" body="G" className="p-5">
-          <button type="button">A</button>
-        </SessionsHoverCard>
-      </>,
-    );
-    const card = document.querySelector("[data-state=open][data-side]") as HTMLElement;
-    expect(card.className).toContain("glass-panel-strong");
-    expect(card.className).toContain("rounded-surface");
-    expect(card.className).not.toContain("bg-overlay");
-    expect(card.className).not.toContain("rounded-lg");
-    expect(card.className).toContain("p-5");
-    expect(card.className).not.toContain("p-3");
-  });
-
-  it("uses the floating overlay surface by default", async () => {
-    await mount(
-      <SessionsHoverCard open body="B">
-        <button type="button">A</button>
-      </SessionsHoverCard>,
-    );
-    const card = document.querySelector("[data-state=open][data-side]") as HTMLElement;
-    expect(card.className).toContain("bg-overlay");
-    expect(card.className).toContain("rounded-lg");
-  });
-
-  it("forwards the ref and props to the child trigger and keeps its handlers", async () => {
-    const ref = createRef<HTMLButtonElement>();
-    const onClick = vi.fn();
-    await mount(
-      <SessionsHoverCard ref={ref as never} data-testid="row" body="B">
-        <button type="button" onClick={onClick}>
-          Row
-        </button>
-      </SessionsHoverCard>,
-    );
-    const button = document.querySelector("button") as HTMLButtonElement;
-    expect(ref.current).toBe(button);
-    expect(button.getAttribute("data-testid")).toBe("row");
-    await act(async () => button.click());
-    expect(onClick).toHaveBeenCalledTimes(1);
-  });
-
-  it("renders its own trigger element with asChild={false}", async () => {
-    await mount(
-      <SessionsHoverCard asChild={false} body="B">
-        <span>Row</span>
-      </SessionsHoverCard>,
-    );
-    const trigger = document.querySelector("[data-state]") as HTMLElement;
-    expect(trigger.tagName).toBe("A");
-    expect(trigger.textContent).toBe("Row");
-  });
-
-  describe("focus and pointer", () => {
-    function setFocusVisible(el: HTMLElement, value: boolean) {
-      const orig = el.matches.bind(el);
-      el.matches = (sel: string) => (sel === ":focus-visible" ? value : orig(sel));
-    }
-
-    it("does not open on pointer-driven focus after a context menu", async () => {
-      const onOpenChange = vi.fn();
-      await mount(
-        <SessionsHoverCard openDelay={0} header="Head" onOpenChange={onOpenChange}>
-          <button type="button">Row</button>
-        </SessionsHoverCard>,
-      );
-      const row = document.querySelector("button")!;
-      setFocusVisible(row, false);
-      await act(async () => {
-        row.dispatchEvent(new MouseEvent("contextmenu", { bubbles: true }));
-        row.dispatchEvent(new FocusEvent("focus", { bubbles: false }));
-        row.dispatchEvent(new FocusEvent("focusin", { bubbles: true }));
-      });
-      await act(async () => new Promise((r) => setTimeout(r, 20)));
-      expect(onOpenChange).not.toHaveBeenCalledWith(true);
-      expect(document.body.textContent).not.toContain("Head");
-    });
-
-    it("opens on keyboard focus-visible", async () => {
-      const onOpenChange = vi.fn();
-      await mount(
-        <SessionsHoverCard openDelay={0} header="Head" onOpenChange={onOpenChange}>
-          <button type="button">Row</button>
-        </SessionsHoverCard>,
-      );
-      const row = document.querySelector("button")!;
-      setFocusVisible(row, true);
-      await act(async () => {
-        row.dispatchEvent(new FocusEvent("focusin", { bubbles: true }));
-      });
-      await act(async () => new Promise((r) => setTimeout(r, 20)));
-      expect(onOpenChange).toHaveBeenCalledWith(true);
-    });
-
-    // React derives onPointerLeave from native pointerout (with a null or outside
-    // relatedTarget). A native pointerleave event does not reach the handler.
-    function leave(el: HTMLElement) {
-      return act(async () => {
-        el.dispatchEvent(new PointerEvent("pointerout", { pointerType: "mouse", bubbles: true, relatedTarget: null }));
-      });
-    }
-
-    it("closes on pointer leave when stuck open by non-focus-visible focus", async () => {
-      const onOpenChange = vi.fn();
-      await mount(
-        <SessionsHoverCard defaultOpen header="Head" onOpenChange={onOpenChange}>
-          <button type="button">Row</button>
-        </SessionsHoverCard>,
-      );
-      const row = document.querySelector("button")!;
-      setFocusVisible(row, false);
-      row.focus();
-      await leave(row);
-      expect(onOpenChange).toHaveBeenCalledWith(false);
-      await act(async () => new Promise((r) => setTimeout(r, 20)));
-      expect(document.body.textContent).not.toContain("Head");
-    });
-
-    it("stays open on pointer leave with keyboard focus-visible", async () => {
-      const onOpenChange = vi.fn();
-      await mount(
-        <SessionsHoverCard defaultOpen header="Head" onOpenChange={onOpenChange}>
-          <button type="button">Row</button>
-        </SessionsHoverCard>,
-      );
-      const row = document.querySelector("button")!;
-      setFocusVisible(row, true);
-      row.focus();
-      await leave(row);
-      await act(async () => new Promise((r) => setTimeout(r, 20)));
-      expect(onOpenChange).not.toHaveBeenCalledWith(false);
-      expect(document.body.textContent).toContain("Head");
-    });
-
-    it("does not force-close on pointer leave without focus (Radix owns hover close)", async () => {
-      const onOpenChange = vi.fn();
-      await mount(
-        <SessionsHoverCard defaultOpen closeDelay={1000} header="Head" onOpenChange={onOpenChange}>
-          <button type="button">Row</button>
-        </SessionsHoverCard>,
-      );
-      const row = document.querySelector("button")!;
-      await leave(row);
-      expect(onOpenChange).not.toHaveBeenCalledWith(false);
-      expect(document.body.textContent).toContain("Head");
-    });
-  });
-});