@backmatter/studio 0.0.7 → 0.0.9

package/src/pages/ui-kit/surfaces.tsx

@@ -0,0 +1,121 @@
+// packages/studio/src/pages/ui-kit/surfaces.tsx
+import * as stylex from "@stylexjs/stylex";
+import { colors, radius, space } from "../../styles/tokens.stylex";
+import { Text } from "../../ui/Text";
+import { Specimen, Topic } from "./topic";
+import { UI_KIT_TOPICS } from "./topics";
+
+const topic = UI_KIT_TOPICS.find((item) => item.slug === "surfaces")!;
+
+export function SurfacesTopic() {
+  return (
+    <Topic title={topic.title} lede={topic.lede}>
+      <Specimen label="Space">
+        <div {...stylex.props(styles.scale)}>
+          <Scale label="xs" bar={styles.xs} />
+          <Scale label="sm" bar={styles.sm} />
+          <Scale label="md" bar={styles.md} />
+          <Scale label="lg" bar={styles.lg} />
+          <Scale label="xl" bar={styles.xl} />
+          <Scale label="xxl" bar={styles.xxl} />
+        </div>
+      </Specimen>
+      <Specimen label="Radius">
+        <div {...stylex.props(styles.scale)}>
+          <Scale label="sm" box={styles.radiusSm} />
+          <Scale label="md" box={styles.radiusMd} />
+        </div>
+      </Specimen>
+      <Specimen label="Backgrounds">
+        <div {...stylex.props(styles.role, styles.app)}>
+          <Text size="xs" tone="muted" mono>
+            bgApp
+          </Text>
+          <div {...stylex.props(styles.role, styles.sidebar)}>
+            <Text size="xs" tone="muted" mono>
+              bgSidebar
+            </Text>
+            <div {...stylex.props(styles.role, styles.panel)}>
+              <Text size="xs" tone="muted" mono>
+                bgPanel
+              </Text>
+              <div {...stylex.props(styles.role, styles.surface)}>
+                <Text size="xs" mono>
+                  bgSurface
+                </Text>
+              </div>
+            </div>
+          </div>
+        </div>
+      </Specimen>
+    </Topic>
+  );
+}
+
+function Scale({
+  label,
+  bar,
+  box,
+}: {
+  label: string;
+  bar?: stylex.StyleXStyles;
+  box?: stylex.StyleXStyles;
+}) {
+  return (
+    <div {...stylex.props(styles.tick)}>
+      <div {...stylex.props(bar ? styles.bar : styles.radiusBox, bar, box)} />
+      <Text size="xs" tone="muted" mono>
+        {label}
+      </Text>
+    </div>
+  );
+}
+
+const styles = stylex.create({
+  bar: {
+    height: "16px",
+    backgroundColor: colors.accent,
+    borderRadius: radius.sm,
+  },
+  scale: {
+    display: "flex",
+    flexWrap: "wrap",
+    alignItems: "flex-end",
+    gap: space.xl,
+  },
+  tick: {
+    display: "flex",
+    flexDirection: "column",
+    alignItems: "flex-start",
+    gap: space.sm,
+  },
+  xs: { width: space.xs },
+  sm: { width: space.sm },
+  md: { width: space.md },
+  lg: { width: space.lg },
+  xl: { width: space.xl },
+  xxl: { width: space.xxl },
+  radiusBox: {
+    width: "64px",
+    height: "40px",
+    backgroundColor: colors.bgSurface,
+    borderWidth: 1,
+    borderStyle: "solid",
+    borderColor: colors.border,
+  },
+  radiusSm: { borderRadius: radius.sm },
+  radiusMd: { borderRadius: radius.md },
+  role: {
+    padding: space.lg,
+    borderRadius: radius.md,
+  },
+  app: { backgroundColor: colors.bgApp },
+  sidebar: { backgroundColor: colors.bgSidebar },
+  panel: { backgroundColor: colors.bgPanel },
+  surface: {
+    backgroundColor: colors.bgSurface,
+    borderWidth: 1,
+    borderStyle: "solid",
+    borderColor: colors.border,
+  },
+});

package/src/pages/ui-kit/topic.tsx

@@ -0,0 +1,112 @@
+// packages/studio/src/pages/ui-kit/topic.tsx
+import * as stylex from "@stylexjs/stylex";
+import { colors, space, type } from "../../styles/tokens.stylex";
+import { Text } from "../../ui/Text";
+
+export function Topic({
+  title,
+  lede,
+  children,
+}: {
+  title: string;
+  lede: string;
+  children: React.ReactNode;
+}) {
+  return (
+    <div {...stylex.props(styles.topic)}>
+      <header {...stylex.props(styles.intro)}>
+        <Text as="h1" size="display" weight="semibold">
+          {title}
+        </Text>
+        <Text tone="muted" size="sm">
+          {lede}
+        </Text>
+      </header>
+      <div {...stylex.props(styles.body)}>{children}</div>
+    </div>
+  );
+}
+
+/** Two aligned columns. Sections share a top edge across the row. */
+export function Columns({ children }: { children: React.ReactNode }) {
+  return <div {...stylex.props(styles.columns)}>{children}</div>;
+}
+
+export function Row({ children }: { children: React.ReactNode }) {
+  return <div {...stylex.props(styles.row)}>{children}</div>;
+}
+
+export function Specimen({
+  label,
+  children,
+}: {
+  label: string;
+  children: React.ReactNode;
+  /** Kept so older call sites still compile. Sections always stack. */
+  block?: boolean;
+}) {
+  return (
+    <section {...stylex.props(styles.specimen)}>
+      <h2 {...stylex.props(styles.heading)}>{label}</h2>
+      <div {...stylex.props(styles.example)}>{children}</div>
+    </section>
+  );
+}
+
+const styles = stylex.create({
+  topic: {
+    display: "flex",
+    flexDirection: "column",
+    gap: "40px",
+    maxWidth: "920px",
+  },
+  intro: {
+    display: "flex",
+    flexDirection: "column",
+    gap: space.md,
+    maxWidth: "62ch",
+  },
+  body: {
+    display: "flex",
+    flexDirection: "column",
+    gap: "40px",
+  },
+  columns: {
+    display: "grid",
+    gridTemplateColumns: "repeat(2, minmax(0, 1fr))",
+    columnGap: "48px",
+    rowGap: "40px",
+    alignItems: "start",
+    "@media (max-width: 800px)": {
+      gridTemplateColumns: "1fr",
+    },
+  },
+  specimen: {
+    display: "flex",
+    flexDirection: "column",
+    gap: space.md,
+    minWidth: 0,
+  },
+  heading: {
+    margin: 0,
+    fontSize: type.lg,
+    fontWeight: 600,
+    letterSpacing: "-0.01em",
+    lineHeight: 1.3,
+    color: colors.text,
+  },
+  example: {
+    display: "flex",
+    flexDirection: "column",
+    alignItems: "stretch",
+    gap: space.sm,
+    width: "100%",
+    minWidth: 0,
+  },
+  row: {
+    display: "flex",
+    flexWrap: "wrap",
+    alignItems: "center",
+    gap: space.sm,
+  },
+});

package/src/pages/ui-kit/topics.ts

@@ -0,0 +1,71 @@
+// packages/studio/src/pages/ui-kit/topics.ts
+
+export const UI_KIT_TOPICS = [
+  {
+    slug: "colors",
+    title: "Colors",
+    group: "Foundations",
+    lede: "Color tokens paint surfaces, text, and status, and follow the active theme.",
+  },
+  {
+    slug: "type",
+    title: "Type",
+    group: "Foundations",
+    lede: "Text sizes and tones for titles, body copy, and metadata.",
+  },
+  {
+    slug: "surfaces",
+    title: "Surfaces",
+    group: "Foundations",
+    lede: "Spacing, radii, and the background roles stacked the way a page stacks them.",
+  },
+  {
+    slug: "sections",
+    title: "Sections",
+    group: "Foundations",
+    lede: "Page header, panel, and stack are how a settings page is built.",
+  },
+  {
+    slug: "buttons",
+    title: "Buttons",
+    group: "Components",
+    lede: "Variants for a primary action, a secondary action, a quiet action, and danger.",
+  },
+  {
+    slug: "fields",
+    title: "Fields",
+    group: "Components",
+    lede: "Text, select, and multiline fields, including a hint and a disabled control.",
+  },
+  {
+    slug: "lists",
+    title: "Lists",
+    group: "Components",
+    lede: "A list of rows that link to a document.",
+  },
+  {
+    slug: "overlays",
+    title: "Overlays",
+    group: "Components",
+    lede: "A confirm dialog and a tooltip.",
+  },
+  {
+    slug: "feedback",
+    title: "Feedback",
+    group: "Components",
+    lede: "Status bars, and the success and danger text tones.",
+  },
+  {
+    slug: "devbar",
+    title: "DevBar",
+    group: "Host",
+    lede: "The host bar a site mounts. These specimens do not call the preview API.",
+  },
+] as const;
+
+export type UiKitTopicSlug = (typeof UI_KIT_TOPICS)[number]["slug"];
+
+export function resolveUiKitTopic(slug: string | undefined): UiKitTopicSlug {
+  const match = UI_KIT_TOPICS.find((topic) => topic.slug === slug);
+  return match ? match.slug : "colors";
+}

package/src/pages/ui-kit/type.tsx

@@ -0,0 +1,55 @@
+// packages/studio/src/pages/ui-kit/type.tsx
+import { Text } from "../../ui/Text";
+import { Specimen, Topic } from "./topic";
+import { UI_KIT_TOPICS } from "./topics";
+
+const topic = UI_KIT_TOPICS.find((item) => item.slug === "type")!;
+
+export function TypeTopic() {
+  return (
+    <Topic title={topic.title} lede={topic.lede}>
+      <Specimen label="display">
+        <Text size="display" weight="semibold">
+          Display
+        </Text>
+      </Specimen>
+      <Specimen label="xl">
+        <Text size="xl" weight="semibold">
+          Title
+        </Text>
+      </Specimen>
+      <Specimen label="lg">
+        <Text size="lg" weight="medium">
+          Heading
+        </Text>
+      </Specimen>
+      <Specimen label="md">
+        <Text>Body</Text>
+      </Specimen>
+      <Specimen label="sm">
+        <Text size="sm">Small</Text>
+      </Specimen>
+      <Specimen label="xs">
+        <Text size="xs" weight="semibold">
+          Overline
+        </Text>
+      </Specimen>
+      <Specimen label="muted">
+        <Text tone="muted" size="sm">
+          Muted
+        </Text>
+      </Specimen>
+      <Specimen label="danger">
+        <Text tone="danger">Danger</Text>
+      </Specimen>
+      <Specimen label="success">
+        <Text tone="success">Success</Text>
+      </Specimen>
+      <Specimen label="mono">
+        <Text mono size="sm">
+          content/blog/hello.mdx
+        </Text>
+      </Specimen>
+    </Topic>
+  );
+}

package/src/preview-frame-radius.ts

@@ -0,0 +1,51 @@
+// packages/studio/src/preview-frame-radius.ts
+// Heuristic bottom corner radius for the on-site preview ring (no web API for real window shape).
+
+/** Chromium on macOS 26+ (Tahoe) — see chromium/brave window corner updates. */
+export const PREVIEW_FRAME_RADIUS_MAC_CHROMIUM_TAHOE = 20;
+/** Chromium on macOS with rounded desktop windows (approx. Sequoia era). */
+export const PREVIEW_FRAME_RADIUS_MAC_CHROMIUM = 16;
+/** Safari / Firefox on macOS. */
+export const PREVIEW_FRAME_RADIUS_MAC = 12;
+export const PREVIEW_FRAME_RADIUS_WINDOWS = 8;
+export const PREVIEW_FRAME_RADIUS_DEFAULT = 12;
+
+/** Pull macOS major from Chromium `platformVersion` (e.g. "26.1.0" → 26). */
+export function macPlatformMajor(platformVersion?: string): number | null {
+  if (!platformVersion) return null;
+  const major = Number.parseInt(platformVersion.split(".")[0] ?? "", 10);
+  return Number.isFinite(major) ? major : null;
+}
+
+export function isMacUserAgent(userAgent: string): boolean {
+  return /Macintosh|Mac OS X/.test(userAgent);
+}
+
+/** Chromium desktop builds on macOS (Chrome, Brave, Edge, Opera). */
+export function isMacChromiumUserAgent(userAgent: string): boolean {
+  if (!isMacUserAgent(userAgent)) return false;
+  if (/Firefox\//.test(userAgent)) return false;
+  return /Chrome\/|Chromium\/|Edg\/|OPR\/|Brave\//.test(userAgent);
+}
+
+/**
+ * Guess preview ring bottom radius (px). `platformVersion` comes from
+ * `navigator.userAgentData.getHighEntropyValues(['platformVersion'])` when available.
+ */
+export function previewFrameRadiusFromUserAgent(
+  userAgent: string,
+  platformVersion?: string,
+): number {
+  if (/Windows/.test(userAgent)) return PREVIEW_FRAME_RADIUS_WINDOWS;
+  if (!isMacUserAgent(userAgent)) return PREVIEW_FRAME_RADIUS_DEFAULT;
+
+  const macMajor = macPlatformMajor(platformVersion);
+  if (isMacChromiumUserAgent(userAgent)) {
+    if (macMajor !== null && macMajor >= 26) return PREVIEW_FRAME_RADIUS_MAC_CHROMIUM_TAHOE;
+    if (macMajor !== null && macMajor >= 15) return PREVIEW_FRAME_RADIUS_MAC_CHROMIUM;
+    // UA-only: still assume modern Chromium on Mac (Brave/Chrome rarely expose OS in UA).
+    return PREVIEW_FRAME_RADIUS_MAC_CHROMIUM;
+  }
+
+  return PREVIEW_FRAME_RADIUS_MAC;
+}

package/src/preview-frame.tsx

@@ -1,38 +1,92 @@
 // packages/studio/src/preview-frame.tsx
-// Full-viewport ring and a top-right preview label while the site session is active.
+// Full-viewport violet frame while preview is on. No corner label.
+import { useLayoutEffect, useRef, useState, type CSSProperties } from "react";
+import {
+  DEVBAR_EASE_IN,
+  DEVBAR_EASE_OUT,
+  DEVBAR_FRAME_ENTER_MS,
+  DEVBAR_FRAME_EXIT_MS,
+  prefersReducedMotion,
+} from "./devbar-state";
+import { PREVIEW_FRAME_RADIUS_DEFAULT, previewFrameRadiusFromUserAgent } from "./preview-frame-radius";
+
 export const PREVIEW_FRAME_CLASS = "backmatter-preview-frame";
 
-/** Shared with the on-site dev bar while preview is active. */
-export const PREVIEW_CHROME_BORDER = "#d97706";
+/** Bottom window corner radius when the host does not set `devBar.previewFrameRadius`. */
+export function guessPreviewFrameRadius(): number {
+  if (typeof navigator === "undefined") return PREVIEW_FRAME_RADIUS_DEFAULT;
+  return previewFrameRadiusFromUserAgent(navigator.userAgent);
+}
 
-function EyeIcon() {
-  return (
-    <svg width="14" height="14" viewBox="0 0 16 16" fill="none" aria-hidden>
-      <path
-        d="M1.5 8s2.5-4.5 6.5-4.5S14.5 8 14.5 8s-2.5 4.5-6.5 4.5S1.5 8 1.5 8Z"
-        stroke="currentColor"
-        strokeWidth="1.25"
-        strokeLinejoin="round"
-      />
-      <circle cx="8" cy="8" r="1.75" stroke="currentColor" strokeWidth="1.25" />
-    </svg>
-  );
+/** Host config, then `--bm-preview-frame-radius` on `<html>`, then platform guess. */
+export function resolvePreviewFrameRadius(override?: number): number {
+  if (override !== undefined && Number.isFinite(override) && override >= 0) return override;
+  if (typeof document !== "undefined") {
+    const raw = getComputedStyle(document.documentElement).getPropertyValue("--bm-preview-frame-radius").trim();
+    if (raw) {
+      const parsed = Number.parseFloat(raw);
+      if (Number.isFinite(parsed) && parsed >= 0) return parsed;
+    }
+  }
+  return guessPreviewFrameRadius();
 }
 
-export function PreviewFrame() {
+/** Violet used by the frame and the preview toolbar. */
+export const PREVIEW_CHROME_BORDER = "oklch(0.56 0.21 295)";
+
+export function PreviewFrame({
+  active,
+  radius,
+}: {
+  active: boolean;
+  /** Bottom window corner radius (px). Top stays square under the browser chrome. */
+  radius?: number;
+}) {
+  const ref = useRef<HTMLDivElement>(null);
+  const was = useRef<boolean | null>(null);
+  const [corner, setCorner] = useState(() => resolvePreviewFrameRadius(radius));
+
+  useLayoutEffect(() => {
+    if (radius !== undefined) {
+      setCorner(resolvePreviewFrameRadius(radius));
+      return;
+    }
+    const ua = navigator.userAgent;
+    setCorner(previewFrameRadiusFromUserAgent(ua));
+
+    const uad = navigator.userAgentData;
+    if (!uad?.getHighEntropyValues) return;
+    void uad.getHighEntropyValues(["platformVersion"]).then((hints) => {
+      setCorner(previewFrameRadiusFromUserAgent(ua, hints.platformVersion));
+    });
+  }, [radius]);
+
+  useLayoutEffect(() => {
+    const frame = ref.current;
+    const previous = was.current;
+    was.current = active;
+    if (!frame || previous === null || previous || !active || prefersReducedMotion()) return;
+    frame.animate(
+      [
+        { borderWidth: "3px" },
+        { borderWidth: "7px", offset: 0.5 },
+        { borderWidth: "3px" },
+      ],
+      { duration: 700, delay: 180, easing: DEVBAR_EASE_OUT },
+    );
+  }, [active]);
+
   return (
     <>
       <style>{FRAME_CSS}</style>
       <div
+        ref={ref}
         className={PREVIEW_FRAME_CLASS}
         data-backmatter-preview-frame=""
+        data-active={active ? "true" : "false"}
+        style={{ "--bm-preview-frame-radius": `${corner}px` } as CSSProperties}
         aria-hidden
-      >
-        <div className={`${PREVIEW_FRAME_CLASS}-badge`}>
-          <EyeIcon />
-          <span>Preview</span>
-        </div>
-      </div>
+      />
     </>
   );
 }
@@ -42,37 +96,27 @@ const FRAME_CSS = `
   position: fixed;
   inset: 0;
   z-index: 2147482999;
+  box-sizing: border-box;
   pointer-events: none;
-  box-shadow: inset 0 0 0 2px ${PREVIEW_CHROME_BORDER};
-  overflow: visible;
-}
-.${PREVIEW_FRAME_CLASS}-badge {
-  position: absolute;
-  top: env(safe-area-inset-top, 0px);
-  right: env(safe-area-inset-right, 0px);
-  display: inline-flex;
-  align-items: center;
-  gap: 6px;
-  padding: 6px 12px;
-  border: 2px solid ${PREVIEW_CHROME_BORDER};
-  border-top: 0;
-  border-radius: 0 0 14px 14px;
-  background: #fff7ed;
-  color: #9a3412;
-  font: 500 12px/1 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
-  white-space: nowrap;
-  -webkit-font-smoothing: antialiased;
+  border: 3px solid ${PREVIEW_CHROME_BORDER};
+  border-radius: 0 0 var(--bm-preview-frame-radius, 12px) var(--bm-preview-frame-radius, 12px);
+  background: transparent;
+  clip-path: circle(0% at 100% 100%);
+  transition: clip-path ${DEVBAR_FRAME_EXIT_MS}ms ${DEVBAR_EASE_IN};
 }
-@keyframes backmatter-preview-frame-in {
-  from { opacity: 0; }
-  to { opacity: 1; }
+.${PREVIEW_FRAME_CLASS}[data-active="true"] {
+  /* 150% is shorter than the viewport diagonal — the ring never reached the top. */
+  clip-path: circle(150vmax at 100% 100%);
+  transition: clip-path ${DEVBAR_FRAME_ENTER_MS}ms ${DEVBAR_EASE_OUT} 80ms;
 }
-@media (prefers-reduced-motion: no-preference) {
+@media (prefers-reduced-motion: reduce) {
   .${PREVIEW_FRAME_CLASS} {
-    animation: backmatter-preview-frame-in 240ms cubic-bezier(0.23, 1, 0.32, 1) both;
+    transition: none;
+    clip-path: none;
+    opacity: 0;
+  }
+  .${PREVIEW_FRAME_CLASS}[data-active="true"] {
+    opacity: 1;
   }
-}
-@media (prefers-reduced-motion: reduce) {
-  .${PREVIEW_FRAME_CLASS} { animation: none; }
 }
 `;