@backmatter/studio 0.0.8 → 0.0.10

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

@@ -0,0 +1,160 @@
+// packages/studio/src/pages/ui-kit/devbar.tsx
+// Specimens of the host bar. This file stays free of StyleX so the markup
+// test can render it under bun, which does not compile StyleX.
+import { useState, type CSSProperties } from "react";
+import type { DevbarActivity } from "../../devbar-state";
+import { SiteBar } from "../../site-bar";
+
+const noop = () => {};
+
+const stageStyle: CSSProperties = {
+  position: "relative",
+  height: 96,
+  overflow: "hidden",
+  transform: "translateZ(0)",
+  ["--bm-devbar-right" as string]: "auto",
+  ["--bm-devbar-left" as string]: "12px",
+};
+
+const sampleDoc = {
+  locale: "en",
+  type: "page",
+  slug: "home",
+  workspaceId: "ws_sample",
+};
+
+export function DevBarTopic() {
+  const [play, setPlay] = useState(0);
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: 40 }}>
+      <style>{`
+        .ui-kit-devbar-label {
+          margin: 0 0 8px;
+          font-size: 14px;
+          font-weight: 600;
+          letter-spacing: -0.01em;
+          line-height: 1.3;
+        }
+        .ui-kit-devbar-stage {
+          width: 100%;
+        }
+        .ui-kit-devbar-reset {
+          align-self: flex-start;
+          height: 28px;
+          padding: 0 10px;
+          border: 1px solid currentColor;
+          border-radius: 8px;
+          background: transparent;
+          color: inherit;
+          font: 500 13px/1 ui-sans-serif, system-ui, sans-serif;
+          cursor: pointer;
+        }
+        .ui-kit-devbar-reset:focus-visible {
+          outline: 2px solid currentColor;
+          outline-offset: 2px;
+        }
+      `}</style>
+      <button
+        type="button"
+        className="ui-kit-devbar-reset"
+        onClick={() => setPlay((next) => next + 1)}
+      >
+        Reset
+      </button>
+      <Bar play={play} heading="Preview" siteMode="preview" />
+      <Bar play={play} heading="Live" siteMode="live" />
+      <Bar play={play} heading="Branch" siteMode="preview" branch="feat/sale" doc />
+      <Bar play={play} heading="Exiting" siteMode="preview" exiting />
+      <Bar play={play} heading="Agent" siteMode="preview" doc chatOpen />
+      <Bar play={play} heading="Publish" siteMode="live" doc changeCount={3} />
+      <Bar
+        play={play}
+        heading="Changes"
+        siteMode="preview"
+        doc
+        changeCount={3}
+        lineDiff={{ added: 14, removed: 2 }}
+      />
+      <Bar
+        play={play}
+        heading="Editing"
+        siteMode="preview"
+        doc
+        activity={{ type: "editing", field: "hero.title" }}
+      />
+      <Bar
+        play={play}
+        heading="Publishing"
+        siteMode="preview"
+        doc
+        activity={{
+          type: "publishing",
+          progress: 0.45,
+          steps: [
+            { label: "Commit", state: "done" },
+            { label: "PR #42", state: "done" },
+            { label: "Deploying 0:14", state: "active" },
+          ],
+        }}
+      />
+      <Bar
+        play={play}
+        heading="Published"
+        siteMode="live"
+        doc
+        activity={{ type: "published", sha: "3a9f21", when: "just now" }}
+      />
+    </div>
+  );
+}
+
+function Bar({
+  play,
+  heading,
+  siteMode,
+  branch,
+  exiting = false,
+  doc = false,
+  chatOpen = false,
+  changeCount = 0,
+  lineDiff,
+  activity = null,
+}: {
+  play: number;
+  heading: string;
+  siteMode: "preview" | "live";
+  branch?: string;
+  exiting?: boolean;
+  doc?: boolean;
+  chatOpen?: boolean;
+  changeCount?: number;
+  lineDiff?: { added: number; removed: number };
+  activity?: DevbarActivity | null;
+}) {
+  return (
+    <section style={{ display: "flex", flexDirection: "column" }}>
+      <h2 className="ui-kit-devbar-label">{heading}</h2>
+      <div className="ui-kit-devbar-stage" style={stageStyle}>
+        <SiteBar
+          key={play}
+          label="page/home"
+          branch={branch}
+          doc={doc ? sampleDoc : null}
+          siteMode={siteMode}
+          exiting={exiting}
+          chatOpen={chatOpen}
+          publishOpen={false}
+          changeCount={changeCount}
+          lineDiff={lineDiff}
+          activity={activity}
+          entrance="play"
+          onExit={noop}
+          onEnterPreview={noop}
+          onToggleChat={noop}
+          onTogglePublish={noop}
+        />
+      </div>
+    </section>
+  );
+}

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

@@ -0,0 +1,39 @@
+// packages/studio/src/pages/ui-kit/feedback.tsx
+import { StatusBar, StatusItem } from "../../chrome/StatusBar";
+import { Text } from "../../ui/Text";
+import { Columns, Specimen, Topic } from "./topic";
+import { UI_KIT_TOPICS } from "./topics";
+
+const topic = UI_KIT_TOPICS.find((item) => item.slug === "feedback")!;
+
+export function FeedbackTopic() {
+  return (
+    <Topic title={topic.title} lede={topic.lede}>
+      <Columns>
+      <Specimen label="StatusBar" block>
+        <StatusBar>
+          <StatusItem>main</StatusItem>
+          <StatusItem>2 uncommitted</StatusItem>
+        </StatusBar>
+      </Specimen>
+      <Specimen label="StatusBar" block>
+        <StatusBar>
+          <StatusItem>feat/sale</StatusItem>
+          <StatusItem>Unsaved</StatusItem>
+        </StatusBar>
+      </Specimen>
+      <Specimen label="danger" block>
+        <StatusBar>
+          <StatusItem tone="danger">Save failed</StatusItem>
+        </StatusBar>
+      </Specimen>
+      <Specimen label="success">
+        <Text tone="success">Success</Text>
+      </Specimen>
+      <Specimen label="danger">
+        <Text tone="danger">Danger</Text>
+      </Specimen>
+      </Columns>
+    </Topic>
+  );
+}

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

@@ -0,0 +1,47 @@
+// packages/studio/src/pages/ui-kit/fields.tsx
+import { useState } from "react";
+import { Field } from "../../ui/Field";
+import { Input, Select, Textarea } from "../../ui/Input";
+import { Columns, Specimen, Topic } from "./topic";
+import { UI_KIT_TOPICS } from "./topics";
+
+const topic = UI_KIT_TOPICS.find((item) => item.slug === "fields")!;
+
+export function FieldsTopic() {
+  const [locale, setLocale] = useState("en");
+
+  return (
+    <Topic title={topic.title} lede={topic.lede}>
+      <Columns>
+      <Specimen label="Input" block>
+        <Field label="Text" hint="Shown under the field.">
+          <Input defaultValue="Ada Lovelace" autoComplete="off" spellCheck={false} />
+        </Field>
+      </Specimen>
+      <Specimen label="disabled" block>
+        <Field label="Disabled">
+          <Input defaultValue="Locked" disabled />
+        </Field>
+      </Specimen>
+      <Specimen label="Select" block>
+        <Field label="Select">
+          <Select
+            aria-label="Locale"
+            value={locale}
+            onValueChange={(next) => setLocale(next ?? "en")}
+            options={[
+              { value: "en", label: "English (en)" },
+              { value: "da", label: "Dansk (da)" },
+            ]}
+          />
+        </Field>
+      </Specimen>
+      <Specimen label="Textarea" block>
+        <Field label="Body">
+          <Textarea mono rows={4} defaultValue={"---\ntitle: Hello\n---\n\nParagraph."} />
+        </Field>
+      </Specimen>
+      </Columns>
+    </Topic>
+  );
+}

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

@@ -0,0 +1,19 @@
+// packages/studio/src/pages/ui-kit/lists.tsx
+import { List, ListRow } from "../../ui/ListRow";
+import { Specimen, Topic } from "./topic";
+import { UI_KIT_TOPICS } from "./topics";
+
+const topic = UI_KIT_TOPICS.find((item) => item.slug === "lists")!;
+
+export function ListsTopic() {
+  return (
+    <Topic title={topic.title} lede={topic.lede}>
+      <Specimen label="List" block>
+        <List>
+          <ListRow to="/__ui/lists" title="hello" meta="en" />
+          <ListRow to="/__ui/lists" title="about" meta="da" />
+        </List>
+      </Specimen>
+    </Topic>
+  );
+}

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

@@ -0,0 +1,39 @@
+// packages/studio/src/pages/ui-kit/overlays.tsx
+import { useState } from "react";
+import { Button } from "../../ui/Button";
+import { ConfirmDialog } from "../../ui/ConfirmDialog";
+import { Tooltip, TooltipProvider } from "../../ui/Tooltip";
+import { Columns, Specimen, Topic } from "./topic";
+import { UI_KIT_TOPICS } from "./topics";
+
+const topic = UI_KIT_TOPICS.find((item) => item.slug === "overlays")!;
+
+export function OverlaysTopic() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <TooltipProvider>
+      <Topic title={topic.title} lede={topic.lede}>
+        <Columns>
+        <Specimen label="ConfirmDialog">
+          <Button onClick={() => setOpen(true)}>Open dialog</Button>
+          <ConfirmDialog
+            open={open}
+            onOpenChange={setOpen}
+            title="Delete this sample?"
+            confirmLabel="Delete"
+            cancelLabel="Cancel"
+            destructive
+            onConfirm={() => setOpen(false)}
+          />
+        </Specimen>
+        <Specimen label="Tooltip">
+          <Tooltip label="Sample tooltip">
+            <Button variant="secondary">Hover</Button>
+          </Tooltip>
+        </Specimen>
+        </Columns>
+      </Topic>
+    </TooltipProvider>
+  );
+}

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

@@ -0,0 +1,9 @@
+// packages/studio/src/pages/ui-kit/path.ts
+import { isStudioDev } from "../../studio-config";
+
+/** Dev-only catalog: `/__ui` or `/__ui/` plus one segment. */
+export function isUiKitPath(pathname: string) {
+  if (!isStudioDev()) return false;
+  const path = pathname.replace(/\/$/, "") || "/";
+  return path === "/__ui" || /^\/__ui\/[^/]+$/.test(path);
+}

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

@@ -0,0 +1,32 @@
+// packages/studio/src/pages/ui-kit/sections.tsx
+import { BackLink } from "../../ui/BackLink";
+import { Button } from "../../ui/Button";
+import { PageHeader, Panel, Stack } from "../../ui/Page";
+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 === "sections")!;
+
+export function SectionsTopic() {
+  return (
+    <Topic title={topic.title} lede={topic.lede}>
+      <Specimen label="PageHeader" block>
+        <PageHeader
+          kicker={<BackLink to="/__ui/sections">Sections</BackLink>}
+          title="Documents"
+          description="Sample page header with action."
+          action={<Button>New</Button>}
+        />
+      </Specimen>
+      <Specimen label="Panel" block>
+        <Panel>
+          <Stack>
+            <Text>First line</Text>
+            <Text>Second line</Text>
+          </Stack>
+        </Panel>
+      </Specimen>
+    </Topic>
+  );
+}

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";
+}