@digithings-ai/ui 0.0.0-stage → 0.1.0

package/src/components/chat/skins/webpage-assistant/config-provider.tsx

@@ -0,0 +1,132 @@
+"use client";
+
+import { docsAssistantConfig } from "./assistant-config";
+import { defaultBrandTheme, defaultDocsHostUi } from "./host-ui";
+import type { BrandTheme, DocsAssistantConfig, DocsHostUiSpec } from "./types";
+import { useSkinChrome } from "../../stock";
+import {
+  createContext,
+  useContext,
+  useMemo,
+  type CSSProperties,
+  type ReactNode,
+} from "react";
+
+const defaultDocsConfig: {
+  hostUi: DocsHostUiSpec;
+  assistant: DocsAssistantConfig;
+  brandTheme: BrandTheme;
+} = {
+  hostUi: defaultDocsHostUi,
+  assistant: docsAssistantConfig,
+  brandTheme: defaultBrandTheme,
+};
+
+const DocsConfigContext = createContext(defaultDocsConfig);
+
+export function DocsConfigProvider({ children }: { children: ReactNode }) {
+  const chrome = useSkinChrome();
+  const config = useMemo(() => {
+    const title = chrome.title?.trim();
+    const welcome = chrome.welcome?.trim();
+    const placeholder = chrome.placeholder?.trim();
+    const hostUi = title
+      ? {
+          ...defaultDocsHostUi,
+          root: {
+            ...defaultDocsHostUi.root,
+            props: {
+              ...defaultDocsHostUi.root.props,
+              productName: title,
+            },
+          },
+        }
+      : defaultDocsHostUi;
+    const brandTheme = chrome.accent
+      ? { ...defaultBrandTheme, accent: chrome.accent.color }
+      : defaultBrandTheme;
+    const assistant = {
+      ...docsAssistantConfig,
+      ...(title ? { productName: title, assistantName: title } : {}),
+      welcome: {
+        ...docsAssistantConfig.welcome,
+        ...(welcome ? { headline: welcome } : {}),
+      },
+      labels: {
+        ...docsAssistantConfig.labels,
+        ...(placeholder
+          ? { composerPlaceholder: placeholder }
+          : {}),
+      },
+    };
+    return { hostUi, assistant, brandTheme };
+  }, [chrome]);
+
+  const theme = config.brandTheme;
+  const accentForeground = bestContrast(theme.accent);
+  const style = {
+    "--docs-accent": theme.accent,
+    "--docs-accent-foreground": accentForeground,
+    "--docs-accent-soft": colorMix(theme.accent, theme.surface, 0.12),
+    "--docs-accent-softer": colorMix(theme.accent, theme.surface, 0.06),
+    "--docs-surface": theme.surface,
+    "--docs-border": theme.border,
+    "--docs-muted": theme.mutedText,
+    "--docs-ring": theme.focusRing,
+    "--primary": theme.accent,
+    "--primary-foreground": accentForeground,
+    "--ring": theme.focusRing,
+    "--accent": colorMix(theme.accent, theme.surface, 0.12),
+    "--accent-foreground": accentForeground,
+    "--border": theme.border,
+    "--muted-foreground": theme.mutedText,
+    "--sidebar-primary": theme.accent,
+    "--sidebar-primary-foreground": accentForeground,
+    "--sidebar-accent": colorMix(theme.accent, theme.surface, 0.12),
+    "--sidebar-accent-foreground": accentForeground,
+    "--sidebar-border": theme.border,
+    "--sidebar-ring": theme.focusRing,
+  } as CSSProperties;
+
+  return (
+    <DocsConfigContext.Provider value={config}>
+      <div className="h-full" style={style}>
+        {children}
+      </div>
+    </DocsConfigContext.Provider>
+  );
+}
+
+export function useDocsConfig() {
+  return useContext(DocsConfigContext);
+}
+
+function colorMix(first: string, second: string, firstWeight: number) {
+  const a = parseHex(first);
+  const b = parseHex(second);
+  if (!a || !b) return first;
+
+  const mix = a.map((value, index) =>
+    Math.round(value * firstWeight + b[index] * (1 - firstWeight)),
+  );
+  return `#${mix.map((value) => value.toString(16).padStart(2, "0")).join("")}`;
+}
+
+function bestContrast(hex: string) {
+  const rgb = parseHex(hex);
+  if (!rgb) return "#ffffff";
+  const luminance =
+    (0.2126 * rgb[0] + 0.7152 * rgb[1] + 0.0722 * rgb[2]) / 255;
+  return luminance > 0.6 ? "#0f172a" : "#ffffff";
+}
+
+function parseHex(hex: string) {
+  const match = /^#([0-9a-f]{6})$/i.exec(hex);
+  if (!match) return null;
+  const value = match[1];
+  return [
+    Number.parseInt(value.slice(0, 2), 16),
+    Number.parseInt(value.slice(2, 4), 16),
+    Number.parseInt(value.slice(4, 6), 16),
+  ];
+}

package/src/components/chat/skins/webpage-assistant/docs-app.tsx

@@ -0,0 +1,106 @@
+"use client";
+
+import { DocsArticle } from "./docs-article";
+import { DocsAssistant } from "./docs-assistant";
+import { DocsNav } from "./docs-nav";
+import { useIsMobile } from "./use-mobile";
+import { useDocsConfig } from "./config-provider";
+import { getPageById } from "./pages";
+import { BookOpenIcon, SearchIcon } from "lucide-react";
+import { useEffect, useRef, useState } from "react";
+
+export function DocsApp({ previewWarning }: { previewWarning?: string }) {
+  const { assistant, hostUi } = useDocsConfig();
+  const shell = hostUi.root.props;
+  const pages = shell.pages;
+  const isMobile = useIsMobile();
+  const desktopAssistantPlacement = shell.assistantPlacement ?? "sidebar";
+  const showAssistantAsModal = isMobile || desktopAssistantPlacement === "modal";
+  const showAssistantSidebar = !showAssistantAsModal;
+  const contentRef = useRef<HTMLElement>(null);
+  const defaultPageId = shell.defaultPageId;
+  const [selectedPageId, setSelectedPageId] = useState(defaultPageId);
+  const currentPage = getPageById(selectedPageId, pages, defaultPageId);
+  useEffect(() => {
+    const readPageFromUrl = () => {
+      const pageId = new URLSearchParams(window.location.search).get("page");
+      if (pageId && pages.some((page) => page.id === pageId)) {
+        setSelectedPageId(pageId);
+      }
+    };
+
+    readPageFromUrl();
+    window.addEventListener("popstate", readPageFromUrl);
+    return () => window.removeEventListener("popstate", readPageFromUrl);
+  }, [pages]);
+
+  const handleSelectPage = (pageId: string) => {
+    if (!pages.some((page) => page.id === pageId)) return;
+    setSelectedPageId(pageId);
+    const nextUrl = new URL(window.location.href);
+    nextUrl.searchParams.set("page", pageId);
+    window.history.replaceState(null, "", nextUrl);
+    requestAnimationFrame(() => {
+      contentRef.current?.scrollTo({ top: 0, behavior: "smooth" });
+    });
+  };
+
+  return (
+    <div className="h-full overflow-hidden bg-[color-mix(in_oklab,var(--docs-accent)_4%,#f7f8fb)] text-foreground">
+      {previewWarning ? (
+        <div className="border-b border-amber-200 bg-amber-50 px-4 py-2 text-sm text-amber-900">
+          {previewWarning}
+        </div>
+      ) : null}
+      <header className="sticky top-0 z-30 border-b bg-white/95 backdrop-blur">
+        <div className="flex h-14 items-center justify-between gap-4 px-4 lg:px-6">
+          <div className="flex min-w-0 items-center gap-3">
+            <div className="flex size-8 shrink-0 items-center justify-center rounded-md bg-[var(--docs-accent)] text-[var(--docs-accent-foreground)]">
+              <BookOpenIcon className="size-4" />
+            </div>
+            <div className="min-w-0">
+              <div className="truncate text-sm font-semibold">{shell.productName}</div>
+              <div className="truncate text-xs text-muted-foreground">{shell.docsName}</div>
+            </div>
+          </div>
+          <div className="hidden min-w-48 items-center gap-2 rounded-md border border-[var(--docs-border)] bg-[var(--docs-accent-softer)] px-3 py-1.5 text-sm text-[var(--docs-muted)] md:flex">
+            <SearchIcon className="size-4 text-[var(--docs-accent)]" />
+            {assistant.labels.headerSearch}
+          </div>
+        </div>
+      </header>
+
+      <main
+        className={`grid h-[calc(100%-3.5rem)] grid-cols-1 overflow-hidden ${
+          showAssistantSidebar
+            ? "md:grid-cols-[minmax(0,1fr)_410px] xl:grid-cols-[240px_minmax(0,1fr)_410px]"
+            : "xl:grid-cols-[240px_minmax(0,1fr)]"
+        }`}
+      >
+        <aside className="hidden h-full overflow-hidden border-r bg-white xl:block">
+          <DocsNav currentPageId={currentPage.id} onSelectPage={handleSelectPage} />
+        </aside>
+        <section ref={contentRef} className="min-w-0 overflow-y-auto">
+          <div className="border-b bg-white px-4 py-3 xl:hidden">
+            <DocsNav currentPageId={currentPage.id} onSelectPage={handleSelectPage} compact />
+          </div>
+          <DocsArticle key={currentPage.id} page={currentPage} onSelectPage={handleSelectPage} />
+        </section>
+        <aside
+          className={`${showAssistantSidebar ? "hidden md:block" : "hidden"} h-full min-h-0 overflow-hidden border-l bg-white`}
+        >
+          <DocsAssistant currentPage={currentPage} onSelectPage={handleSelectPage} mode="sidebar" />
+        </aside>
+      </main>
+
+      {showAssistantAsModal ? (
+        <DocsAssistant
+          currentPage={currentPage}
+          defaultOpen={!isMobile && desktopAssistantPlacement === "modal"}
+          onSelectPage={handleSelectPage}
+          mode="modal"
+        />
+      ) : null}
+    </div>
+  );
+}

package/src/components/chat/skins/webpage-assistant/docs-article.tsx

@@ -0,0 +1,109 @@
+"use client";
+
+import { MarkdownPage } from "./markdown-page";
+import { Button } from "../../stock/ui/button";
+import { useDocsConfig } from "./config-provider";
+import { getPageById } from "./pages";
+import type { DocsPage } from "./types";
+import { ArrowRightIcon, FileTextIcon } from "lucide-react";
+
+export function DocsArticle({
+  page,
+  onSelectPage,
+}: {
+  page: DocsPage;
+  onSelectPage: (pageId: string) => void;
+}) {
+  const { hostUi } = useDocsConfig();
+  const related = page.relatedPageIds.map((pageId) =>
+    getPageById(pageId, hostUi.root.props.pages, hostUi.root.props.defaultPageId),
+  );
+
+  return (
+    <article className="mx-auto max-w-4xl px-4 py-8 lg:px-10">
+      <PageHeader page={page} />
+      <MarkdownPage markdown={page.markdown} />
+      <RelatedPages related={related} onSelectPage={onSelectPage} />
+      <ArticleCta />
+    </article>
+  );
+}
+
+function PageHeader({ page }: { page: DocsPage }) {
+  const { assistant } = useDocsConfig();
+
+  return (
+    <>
+      <div className="mb-6 flex flex-wrap items-center gap-2 text-xs text-muted-foreground">
+        <span className="rounded-full border bg-white px-2.5 py-1">{page.section}</span>
+        <span className="rounded-full bg-[var(--docs-accent-soft)] px-2.5 py-1 text-[var(--docs-accent)]">
+          {assistant.labels.currentPage}: {page.title}
+        </span>
+      </div>
+      <h1 className="text-3xl font-semibold tracking-normal text-slate-950 md:text-4xl">
+        {page.title}
+      </h1>
+      <p className="mt-3 max-w-2xl text-base leading-7 text-muted-foreground">{page.description}</p>
+    </>
+  );
+}
+
+function RelatedPages({
+  related,
+  onSelectPage,
+}: {
+  related: DocsPage[];
+  onSelectPage: (pageId: string) => void;
+}) {
+  const { assistant } = useDocsConfig();
+  const uniqueRelated = related.filter(
+    (page, index, pages) => pages.findIndex((item) => item.id === page.id) === index,
+  );
+
+  if (uniqueRelated.length === 0) return null;
+
+  return (
+    <div className="mt-10 border-t pt-6">
+      <h2 className="mb-3 text-sm font-semibold text-slate-900">{assistant.labels.relatedPages}</h2>
+      <div className="grid gap-3">
+        {uniqueRelated.map((relatedPage) => (
+          <button
+            key={relatedPage.id}
+            type="button"
+            onClick={() => onSelectPage(relatedPage.id)}
+            className="rounded-lg border bg-white p-4 text-left transition-colors hover:border-[var(--docs-accent)] hover:bg-[var(--docs-accent-softer)]"
+          >
+            <div className="flex items-start gap-3">
+              <FileTextIcon className="mt-0.5 size-4 shrink-0 text-[var(--docs-accent)]" />
+              <div className="min-w-0">
+                <div className="font-medium">{relatedPage.title}</div>
+                <p className="mt-1 line-clamp-2 text-sm text-muted-foreground">
+                  {relatedPage.description}
+                </p>
+              </div>
+            </div>
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+function ArticleCta() {
+  const { assistant } = useDocsConfig();
+
+  return (
+    <div className="mt-10 rounded-lg border bg-white p-4">
+      <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+        <div>
+          <div className="font-medium">{assistant.labels.articleCtaTitle}</div>
+          <p className="text-sm text-muted-foreground">{assistant.labels.articleCtaBody}</p>
+        </div>
+        <Button variant="outline" className="w-full gap-1.5 sm:w-auto">
+          {assistant.labels.articleCtaAction}
+          <ArrowRightIcon className="size-4" />
+        </Button>
+      </div>
+    </div>
+  );
+}

package/src/components/chat/skins/webpage-assistant/docs-assistant.tsx

@@ -0,0 +1,73 @@
+"use client";
+
+import { Thread } from "../../stock/thread.aui";
+import { BotIcon } from "lucide-react";
+import { AssistantModal } from "./assistant-modal";
+import { useDocsConfig } from "./config-provider";
+import type { DocsPage } from "./types";
+
+export function DocsAssistant({
+  currentPage,
+  mode,
+  defaultOpen = false,
+}: {
+  currentPage: DocsPage;
+  onSelectPage: (pageId: string) => void;
+  mode: "sidebar" | "modal";
+  defaultOpen?: boolean;
+}) {
+  const { assistant } = useDocsConfig();
+  const thread = (
+    <Thread
+      components={{
+        Welcome: () => (
+          <div className="mb-4 px-4 text-center">
+            <h2 className="text-lg font-medium">{assistant.welcome.headline}</h2>
+            {assistant.welcome.body ? (
+              <p className="mt-1 text-sm text-muted-foreground">{assistant.welcome.body}</p>
+            ) : null}
+          </div>
+        ),
+      }}
+    />
+  );
+
+  if (mode === "sidebar") {
+    return (
+      <div className="flex h-full flex-col">
+        <div className="border-b px-4 py-3">
+          <div className="flex items-center gap-2">
+            <div className="flex size-8 items-center justify-center rounded-md bg-[var(--docs-accent-soft)] text-[var(--docs-accent)]">
+              <BotIcon className="size-4" />
+            </div>
+            <div className="min-w-0">
+              <div className="truncate text-sm font-semibold">{assistant.assistantName}</div>
+              <div className="truncate text-xs text-muted-foreground">
+                {assistant.labels.currentPage}: {currentPage.title}
+              </div>
+            </div>
+          </div>
+        </div>
+        <div className="min-h-0 flex-1">{thread}</div>
+      </div>
+    );
+  }
+
+  return (
+    <AssistantModal
+      defaultOpen={defaultOpen}
+      tooltipClosed={assistant.assistantName}
+      tooltipOpen="Close assistant"
+    >
+      <div className="flex h-full flex-col">
+        <div className="border-b px-4 py-3">
+          <div className="text-sm font-semibold">{assistant.assistantName}</div>
+          <div className="truncate text-xs text-muted-foreground">
+            {assistant.labels.currentPage}: {currentPage.title}
+          </div>
+        </div>
+        <div className="min-h-0 flex-1">{thread}</div>
+      </div>
+    </AssistantModal>
+  );
+}

package/src/components/chat/skins/webpage-assistant/docs-nav.tsx

@@ -0,0 +1,81 @@
+"use client";
+
+import { useDocsConfig } from "./config-provider";
+import { cn } from "../../../../lib/utils";
+
+export function DocsNav({
+  currentPageId,
+  onSelectPage,
+  compact = false,
+}: {
+  currentPageId: string;
+  onSelectPage: (pageId: string) => void;
+  compact?: boolean;
+}) {
+  const { hostUi } = useDocsConfig();
+  const pages = hostUi.root.props.pages;
+  const selectPage = (pageId: string) => {
+    onSelectPage(pageId);
+  };
+  const navGroups =
+    hostUi.root.props.navGroups ??
+    Array.from(new Set(pages.map((page) => page.section))).map((section) => ({
+      label: section,
+      pageIds: pages.filter((page) => page.section === section).map((page) => page.id),
+    }));
+
+  if (compact) {
+    return (
+      <select
+        className="w-full rounded-md border bg-white px-3 py-2 text-sm"
+        value={currentPageId}
+        onChange={(event) => selectPage(event.currentTarget.value)}
+        onInput={(event) => selectPage(event.currentTarget.value)}
+        aria-label="Select docs page"
+      >
+        {pages.map((page) => (
+          <option key={page.id} value={page.id}>
+            {page.section}: {page.title}
+          </option>
+        ))}
+      </select>
+    );
+  }
+
+  return (
+    <nav className="h-full overflow-y-auto px-4 py-5">
+      {navGroups.map((group) => {
+        const groupPages = group.pageIds
+          .map((pageId) => pages.find((page) => page.id === pageId))
+          .filter((page) => page !== undefined);
+
+        if (groupPages.length === 0) return null;
+
+        return (
+          <div key={group.label} className="mb-6">
+            <div className="mb-2 px-2 text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+              {group.label}
+            </div>
+            <div className="space-y-1">
+              {groupPages.map((page) => (
+                <button
+                  key={page.id}
+                  type="button"
+                  onClick={() => selectPage(page.id)}
+                  className={cn(
+                    "block w-full rounded-md px-2 py-1.5 text-left text-sm transition-colors",
+                    currentPageId === page.id
+                      ? "bg-[var(--docs-accent-soft)] font-medium text-[var(--docs-accent)]"
+                      : "text-[var(--docs-muted)] hover:bg-[var(--docs-accent-softer)] hover:text-foreground",
+                  )}
+                >
+                  {page.title}
+                </button>
+              ))}
+            </div>
+          </div>
+        );
+      })}
+    </nav>
+  );
+}

package/src/components/chat/skins/webpage-assistant/host-ui.ts

@@ -0,0 +1,79 @@
+import type { BrandTheme, DocsHostUiSpec } from "./types";
+
+export const defaultBrandTheme = {
+  "accent": "#0369a1",
+  "surface": "#ffffff",
+  "border": "#dbe3ea",
+  "mutedText": "#64748b",
+  "focusRing": "#38bdf8"
+} satisfies BrandTheme;
+
+export const defaultDocsHostUi: DocsHostUiSpec = {
+  "version": 1,
+  "root": {
+    "type": "ContentShell",
+    "props": {
+      "productName": "Northstar Docs",
+      "docsName": "Product Guides",
+      "defaultPageId": "guided-onboarding",
+      "pages": [
+        {
+          "id": "guided-onboarding",
+          "title": "Guided Onboarding",
+          "section": "Product guides",
+          "description": "Set up a workspace, invite teammates, and publish your first customer guide.",
+          "url": "/docs/guided-onboarding",
+          "markdown": "## Create a workspace\n\nNorthstar workspaces keep product guides, owners, and release notes organized by team.\n\n## Invite teammates\n\nInvite teammates as editors when they need to update docs, or viewers when they only need review access.\n\n## Publish the guide\n\nPublish your first guide after assigning an owner, choosing a collection, and checking the preview.",
+          "keywords": [
+            "onboarding",
+            "workspace",
+            "guide",
+            "publish",
+            "setup"
+          ],
+          "relatedPageIds": [
+            "roles-and-permissions",
+            "release-notes"
+          ]
+        },
+        {
+          "id": "roles-and-permissions",
+          "title": "Roles and Permissions",
+          "section": "Product guides",
+          "description": "Choose editor, reviewer, and viewer roles for a documentation workspace.",
+          "url": "/docs/roles-and-permissions",
+          "markdown": "## Editors\n\nEditors can update guides, manage screenshots, and publish approved changes.\n\n## Reviewers\n\nReviewers can leave comments and request changes before a guide is released.\n\n## Viewers\n\nViewers can read internal guides without changing the source content.",
+          "keywords": [
+            "roles",
+            "permissions",
+            "teammates",
+            "workspace"
+          ],
+          "relatedPageIds": [
+            "guided-onboarding",
+            "release-notes"
+          ]
+        },
+        {
+          "id": "release-notes",
+          "title": "Release Notes",
+          "section": "Product guides",
+          "description": "Prepare product updates and attach related docs before publishing.",
+          "url": "/docs/release-notes",
+          "markdown": "## Draft notes\n\nRelease notes summarize product changes and link readers to the guides they should read next.\n\n## Attach docs\n\nAttach related docs so support and customer success teams can answer follow-up questions quickly.\n\n## Publish updates\n\nSchedule release notes when launch timing matters across regions.",
+          "keywords": [
+            "release",
+            "notes",
+            "updates",
+            "launch"
+          ],
+          "relatedPageIds": [
+            "guided-onboarding",
+            "roles-and-permissions"
+          ]
+        }
+      ],
+      "assistantPlacement": "sidebar"
+    }
+  }
+} satisfies DocsHostUiSpec;

package/src/components/chat/skins/webpage-assistant/index.tsx

@@ -0,0 +1,12 @@
+"use client";
+
+import { DocsApp } from "./docs-app";
+import { DocsConfigProvider } from "./config-provider";
+
+export function WebpageAssistant() {
+  return (
+    <DocsConfigProvider>
+      <DocsApp />
+    </DocsConfigProvider>
+  );
+}

package/src/components/chat/skins/webpage-assistant/markdown-page.tsx

@@ -0,0 +1,11 @@
+"use client";
+
+import ReactMarkdown from "react-markdown";
+
+export function MarkdownPage({ markdown }: { markdown: string }) {
+  return (
+    <div className="mt-8 text-slate-800 [&_a]:text-[var(--docs-accent)] [&_a]:underline [&_blockquote]:border-l-4 [&_blockquote]:border-[var(--docs-accent-soft)] [&_blockquote]:pl-4 [&_blockquote]:text-slate-600 [&_code]:rounded [&_code]:bg-slate-100 [&_code]:px-1.5 [&_code]:py-0.5 [&_code]:font-mono [&_h2]:mt-8 [&_h2]:mb-3 [&_h2]:text-xl [&_h2]:font-semibold [&_h2]:text-slate-900 [&_h3]:mt-6 [&_h3]:mb-2 [&_h3]:text-lg [&_h3]:font-semibold [&_li]:my-1 [&_ol]:my-4 [&_ol]:list-decimal [&_ol]:pl-6 [&_p]:my-4 [&_p]:leading-7 [&_pre]:my-5 [&_pre]:overflow-x-auto [&_pre]:rounded-lg [&_pre]:bg-slate-950 [&_pre]:p-4 [&_pre_code]:bg-transparent [&_pre_code]:p-0 [&_pre_code]:text-slate-50 [&_strong]:font-semibold [&_ul]:my-4 [&_ul]:list-disc [&_ul]:pl-6">
+      <ReactMarkdown>{markdown}</ReactMarkdown>
+    </div>
+  );
+}

package/src/components/chat/skins/webpage-assistant/pages.ts

@@ -0,0 +1,9 @@
+import type { DocsPage } from "./types";
+
+export function getPageById(pageId: string | undefined, pages: DocsPage[], defaultPageId?: string) {
+  return (
+    pages.find((page) => page.id === pageId) ??
+    pages.find((page) => page.id === defaultPageId) ??
+    pages[0]
+  );
+}