@vvedantb/ui 0.12.1 → 0.13.0

package/src/artifacts/artifact-versions-menu.tsx

@@ -0,0 +1,103 @@
+import { IconCheck, IconChevronDown, IconHistory, IconRestore } from "@tabler/icons-react";
+import { toast } from "sonner";
+import { formatCompactRelativeTime } from "../../app/src/time/compactRelativeTime";
+import { Button } from "../ui/button";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "../ui/dropdown-menu";
+import type { ArtifactVersionSummary } from "./types";
+
+export type ArtifactVersionsMenuProps = {
+  versions: readonly ArtifactVersionSummary[];
+  currentVersion: number;
+  /** The version on screen. Default `currentVersion`. */
+  viewingVersion?: number;
+  /** Show a version. Without it, picking an older version restores it. */
+  onViewVersion?: (version: number) => void;
+  /** Make a version current. With `onViewVersion`, offered as "Restore vN" while an older version is on screen. */
+  onRestoreVersion?: (version: number) => void | Promise<void>;
+  className?: string;
+};
+
+/** "vN" menu listing the kept versions, newest first, to view or restore one. */
+export function ArtifactVersionsMenu({
+  versions,
+  currentVersion,
+  viewingVersion = currentVersion,
+  onViewVersion,
+  onRestoreVersion,
+  className,
+}: ArtifactVersionsMenuProps) {
+  const sorted = [...versions].sort((a, b) => b.version - a.version);
+
+  const restore = async (version: number) => {
+    try {
+      await onRestoreVersion?.(version);
+    } catch {
+      toast.error("Couldn't restore version");
+    }
+  };
+
+  const pick = (version: number) => {
+    if (onViewVersion) onViewVersion(version);
+    else if (version !== currentVersion) void restore(version);
+  };
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <Button
+          variant="ghost"
+          size="sm"
+          aria-label="Versions"
+          className={className}
+          startContent={<IconHistory size={16} />}
+          endContent={<IconChevronDown size={14} />}
+        >
+          v{viewingVersion}
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent fitViewport suppressAltKey restoreScrollLockOnClose align="end" className="min-w-52">
+        <DropdownMenuLabel>Versions</DropdownMenuLabel>
+        {sorted.map((entry) => {
+          const current = entry.version === currentVersion;
+          const time = formatCompactRelativeTime(entry.createdAt);
+          return (
+            <DropdownMenuItem
+              key={entry.version}
+              data-version={entry.version}
+              disabled={!onViewVersion && (current || !onRestoreVersion)}
+              startContent={
+                entry.version === viewingVersion ? <IconCheck size={16} /> : <span aria-hidden className="size-4" />
+              }
+              description={entry.title ? `${time} · ${entry.title}` : time}
+              endContent={
+                current ? (
+                  <span className="text-xs text-muted-foreground">Current</span>
+                ) : !onViewVersion && onRestoreVersion ? (
+                  <span className="text-xs text-muted-foreground">Restore</span>
+                ) : undefined
+              }
+              onClick={() => pick(entry.version)}
+            >
+              v{entry.version}
+            </DropdownMenuItem>
+          );
+        })}
+        {onViewVersion && onRestoreVersion && viewingVersion !== currentVersion ? (
+          <>
+            <DropdownMenuSeparator />
+            <DropdownMenuItem startContent={<IconRestore size={16} />} onClick={() => void restore(viewingVersion)}>
+              Restore v{viewingVersion}
+            </DropdownMenuItem>
+          </>
+        ) : null}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}

package/src/artifacts/artifact-viewer.tsx

@@ -0,0 +1,133 @@
+import type { ReactNode } from "react";
+import { IconCopy, IconDownload, IconExternalLink, IconPencil, IconTrash } from "@tabler/icons-react";
+import { ARTIFACT_FORMAT_FILES } from "@vvedantb/server";
+import { skipConfirmTitle } from "../../app/src/confirm/ConfirmSkipHint";
+import { Artifact, ArtifactAction, ArtifactActions, ArtifactHeader, ArtifactTitle } from "../ai-elements/artifact";
+import { TooltipProvider } from "../ui/tooltip";
+import { cn } from "../utils/cn";
+import { useArtifactEditDialogs, type ArtifactEditCallbacks } from "./artifact-dialogs";
+import { copyArtifactBody, downloadArtifactBody, openArtifactInNewTab } from "./artifact-file";
+import { ArtifactRender, type ArtifactRenderProps } from "./artifact-render";
+import { ArtifactTypeIcon } from "./artifact-type-icon";
+import { ArtifactVersionsMenu, type ArtifactVersionsMenuProps } from "./artifact-versions-menu";
+import type { ArtifactDocument, ArtifactVersionSummary } from "./types";
+
+export type ArtifactViewerProps = ArtifactEditCallbacks &
+  Pick<ArtifactRenderProps, "store" | "stateGlobalAliases"> &
+  Pick<ArtifactVersionsMenuProps, "viewingVersion" | "onViewVersion" | "onRestoreVersion"> & {
+    /** The artifact, with the body of the version on screen. */
+    artifact: ArtifactDocument;
+    /** Kept versions for the versions menu. Omit to hide the menu. */
+    versions?: readonly ArtifactVersionSummary[];
+    /** The artifact's own page, for "Open in new tab". Omit to hide the button. */
+    href?: string;
+    /** Before the title, e.g. a back link from the app's router. */
+    headerStart?: ReactNode;
+    /** Extra header actions, before Delete. */
+    actions?: ReactNode;
+    className?: string;
+  };
+
+/**
+ * One artifact: a header with the title and its actions (versions, rename,
+ * copy, download as the format's file, open in new tab, delete) above the
+ * rendered body. Rename and delete go through confirm dialogs; Alt-click on
+ * Delete skips the dialog.
+ */
+export function ArtifactViewer({
+  artifact,
+  store,
+  stateGlobalAliases,
+  versions,
+  viewingVersion,
+  onViewVersion,
+  onRestoreVersion,
+  href,
+  onRename,
+  onDelete,
+  headerStart,
+  actions,
+  className,
+}: ArtifactViewerProps) {
+  const edit = useArtifactEditDialogs({ title: artifact.title, onRename, onDelete });
+  const extension = ARTIFACT_FORMAT_FILES[artifact.format].extension;
+  const actionClass = "h-8 min-w-8";
+
+  return (
+    <TooltipProvider>
+      <Artifact className={cn("flex min-h-0 flex-1 flex-col overflow-hidden", className)}>
+        <ArtifactHeader className="items-center">
+          <div className="flex min-w-0 items-center gap-2">
+            {headerStart}
+            <ArtifactTypeIcon type={artifact.type} />
+            <ArtifactTitle className="truncate">{artifact.title}</ArtifactTitle>
+          </div>
+          <ArtifactActions className="shrink-0">
+            {versions ? (
+              <ArtifactVersionsMenu
+                versions={versions}
+                currentVersion={artifact.currentVersion}
+                viewingVersion={viewingVersion}
+                onViewVersion={onViewVersion}
+                onRestoreVersion={onRestoreVersion}
+              />
+            ) : null}
+            {onRename ? (
+              <ArtifactAction
+                tooltip="Rename"
+                size="icon-sm"
+                className={actionClass}
+                icon={<IconPencil size={16} />}
+                onClick={edit.startRename}
+              />
+            ) : null}
+            <ArtifactAction
+              tooltip="Copy"
+              size="icon-sm"
+              className={actionClass}
+              icon={<IconCopy size={16} />}
+              onClick={() => void copyArtifactBody(artifact.body)}
+            />
+            <ArtifactAction
+              tooltip={`Download .${extension}`}
+              label="Download"
+              size="icon-sm"
+              className={actionClass}
+              icon={<IconDownload size={16} />}
+              onClick={() => downloadArtifactBody(artifact.title, artifact.format, artifact.body)}
+            />
+            {href !== undefined ? (
+              <ArtifactAction
+                tooltip="Open in new tab"
+                size="icon-sm"
+                className={actionClass}
+                icon={<IconExternalLink size={16} />}
+                onClick={() => openArtifactInNewTab(href)}
+              />
+            ) : null}
+            {actions}
+            {onDelete ? (
+              <ArtifactAction
+                tooltip={skipConfirmTitle("Delete")}
+                label="Delete"
+                size="icon-sm"
+                className={cn(actionClass, "text-danger hover:text-danger")}
+                icon={<IconTrash size={16} />}
+                onClick={(event) => edit.requestDelete(event)}
+              />
+            ) : null}
+          </ArtifactActions>
+        </ArtifactHeader>
+        <div className="min-h-0 flex-1 overflow-hidden bg-surface-secondary">
+          <ArtifactRender
+            artifact={artifact}
+            store={store}
+            stateGlobalAliases={stateGlobalAliases}
+            className="h-full min-h-64"
+          />
+        </div>
+      </Artifact>
+      {edit.dialogs}
+    </TooltipProvider>
+  );
+}

package/src/artifacts/index.ts

@@ -0,0 +1,11 @@
+export * from "./types";
+export * from "./artifact-type-icon";
+export * from "./artifact-file";
+export * from "./artifact-frame";
+export * from "./artifact-render";
+export * from "./artifact-dialogs";
+export * from "./artifact-card";
+export * from "./artifact-list";
+export * from "./artifact-list-toolbar";
+export * from "./artifact-versions-menu";
+export * from "./artifact-viewer";

package/src/artifacts/types.ts

@@ -0,0 +1,18 @@
+import type { ArtifactDetailRow, ArtifactListRow } from "@vvedantb/server";
+
+/** What a card or list row shows. Any `ArtifactListRow` fits; the body is never needed. */
+export type ArtifactSummary = Pick<ArtifactListRow, "id" | "title" | "description" | "type" | "format" | "updatedAt">;
+
+/** What the viewer renders: the summary fields it shows plus the body of the version on screen. */
+export type ArtifactDocument = Pick<
+  ArtifactDetailRow,
+  "id" | "title" | "type" | "format" | "language" | "stateSpec" | "currentVersion" | "body"
+>;
+
+/** One entry in the versions menu. */
+export type ArtifactVersionSummary = {
+  version: number;
+  createdAt: number;
+  /** The title the artifact had at this version, when it differs. */
+  title?: string;
+};

package/src/index.ts

@@ -106,6 +106,10 @@ export * from "./ai-elements/sources";
 export * from "./ai-elements/speech-input";
 export * from "./ai-elements/suggestion";
 
+// Artifact viewers: frame with the state bridge, card, list, toolbar, viewer.
+// The core (schemas, state ops, document wrapper) comes from `@vvedantb/server`.
+export * from "./artifacts";
+
 export * from "./audio";
 
 export * from "./composer";

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, the radius utilities `rounded-surface` (`clamp(0.75rem, var(--radius), 1rem)`), `rounded-menu-item` (`min(var(--radius), 0.5rem)`) and `rounded-control` (`min(var(--radius), 0.625rem)`) (0.7.1; `rounded-surface` was in `utilities.css` before), `*` border and `body` defaults. 0.7.2 adds `--sidebar-accent` / `sidebar-accent` (sidebar nav row fill: light `var(--surface-tertiary)`, dark `oklch(22.64% 0 0)`). 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` and `@utility reveal-on-hover`. `rounded-surface` moved to `tokens.css` in 0.7.1. |
+| `@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`, the same three radius utilities as `tokens.css` 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.