Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .changeset/tidy-examples-preview.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
"@tailor-platform/app-shell": patch
---

Replace static documentation snippets with runnable, self-contained examples for components and hooks, including forms, data tables, and AI chat.
Improve the documentation browser with grouped sidebar navigation, a global header, and a neutral preview background.
3 changes: 2 additions & 1 deletion docs-browser/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,8 @@
"scripts": {
"dev": "vite",
"build": "vite build",
"type-check": "tsc --noEmit"
"type-check": "tsc --noEmit",
"test": "node --test tests/*.test.mjs"
},
"dependencies": {
"@tailor-platform/app-shell": "workspace:*",
Expand Down
127 changes: 115 additions & 12 deletions docs-browser/src/App.tsx
Original file line number Diff line number Diff line change
@@ -1,14 +1,33 @@
import { Fragment, type ReactNode, useState } from "react";
import {
BookOpenIcon,
CodeXmlIcon,
ComponentIcon,
LayersIcon,
LightbulbIcon,
PanelsTopLeftIcon,
} from "lucide-react";

import {
AppearanceSwitcher,
AppShell,
DefaultSidebar,
defineModule,
defineResource,
SidebarLayout,
GlobalHeaderLayout,
Link,
Select,
SidebarItem,
SidebarSection,
SidebarSeparator,
Text,
useAppShell,
useLocation,
} from "@tailor-platform/app-shell";

import { DocPage } from "./_lib/DocPage";
import { type DocUnit, units } from "./docs";
import HomePage from "./pages/page";
import { sectionForPath, sections } from "./sections";

// Declarative routing: the module/resource tree is derived from the same
// manifest the renderer already consumes (see docs.tsx). This dogfoods the
Expand All @@ -17,13 +36,13 @@ import HomePage from "./pages/page";

type Res = ReturnType<typeof defineResource>;

const CATEGORY_LABEL: Record<string, string> = {
guides: "Guides",
concepts: "Concepts",
components: "Components",
patterns: "Patterns",
pages: "Pages",
api: "API",
const CATEGORY_META: Record<string, { title: string; icon: ReactNode }> = {
guides: { title: "Guides", icon: <BookOpenIcon /> },
concepts: { title: "Concepts", icon: <LightbulbIcon /> },
components: { title: "Components", icon: <ComponentIcon /> },
patterns: { title: "Patterns", icon: <LayersIcon /> },
pages: { title: "Pages", icon: <PanelsTopLeftIcon /> },
api: { title: "API", icon: <CodeXmlIcon /> },
};
// Sidebar order; any category not listed falls to the end alphabetically.
const CATEGORY_ORDER = ["guides", "concepts", "components", "patterns", "pages", "api"];
Expand Down Expand Up @@ -81,16 +100,100 @@ function buildModules(): ReturnType<typeof defineModule>[] {
.map((category) =>
defineModule({
path: category,
meta: { title: CATEGORY_LABEL[category] ?? category },
meta: CATEGORY_META[category] ?? { title: category },
resources: buildResources(byCategory.get(category) ?? []),
}),
);
}

const modules = buildModules();

function ResourceItems({ resources, basePath }: { resources: Res[]; basePath: string }) {
return resources.map((resource, index) => {
const path = `${basePath}/${resource.path}`;
return resource.subResources?.length ? (
<Fragment key={path}>
{index > 0 && <SidebarSeparator />}
<SidebarSection title={resource.meta.title}>
<ResourceItems resources={resource.subResources} basePath={path} />
</SidebarSection>
</Fragment>
) : (
<SidebarItem key={path} to={path} />
);
});
}

function DocsLayout() {
const { title } = useAppShell();
const { pathname } = useLocation();
const [selection, setSelection] = useState(() => ({
pathname,
section: sectionForPath(pathname),
}));

// Follow document navigation without remounting the layout and resetting the sidebar.
if (selection.pathname !== pathname) {
setSelection({ pathname, section: sectionForPath(pathname) });
}

return (
<GlobalHeaderLayout
header={
<header className="flex h-14 shrink-0 items-center gap-2 border-b border-border px-3 sm:gap-3 sm:px-4">
<Link
to="/"
className="shrink-0 rounded-sm focus-visible:outline-2 focus-visible:outline-ring"
>
<Text.span variant="heading-sm">{title}</Text.span>
</Link>
<div className="min-w-0 flex-1 sm:w-56 sm:flex-none">
<Select.Parts.Root
value={selection.section}
itemToStringLabel={(section) => section.label}
onValueChange={(section) => {
if (section) setSelection({ pathname, section });
}}
>
<Select.Parts.Trigger aria-label="Documentation section" className="min-w-0">
<Select.Parts.Value className="truncate" />
</Select.Parts.Trigger>
<Select.Parts.Content className="min-w-56">
{sections.map((section) => (
<Select.Parts.Item key={section.label} value={section}>
{section.label}
</Select.Parts.Item>
))}
</Select.Parts.Content>
</Select.Parts.Root>
</div>
<div className="ml-auto shrink-0">
<AppearanceSwitcher />
</div>
</header>
}
sidebar={
<GlobalHeaderLayout.DefaultSidebar>
{modules
.filter((module) => selection.section.categories.includes(module.path))
.map((module, index) => (
<Fragment key={module.path}>
{index > 0 && <SidebarSeparator />}
<SidebarSection title={module.meta.title}>
<ResourceItems resources={module.resources} basePath={`/${module.path}`} />
</SidebarSection>
</Fragment>
))}
</GlobalHeaderLayout.DefaultSidebar>
}
/>
);
}

const App = () => {
return (
<AppShell title="app-shell docs" modules={buildModules()} rootComponent={HomePage}>
<SidebarLayout sidebar={<DefaultSidebar />} />
<AppShell title="AppShell Docs" modules={modules} rootComponent={HomePage}>
<DocsLayout />
</AppShell>
);
};
Expand Down
2 changes: 1 addition & 1 deletion docs-browser/src/index.css
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
@import "tailwindcss";
@import "@tailor-platform/app-shell/styles";
@import "@tailor-platform/app-shell/themes/bloom";
@import "./theme.css";

/* The live examples live at the repo root (docs-src/), outside this app's own tree,
so Tailwind won't discover their utility classes by default. Point it at them
Expand Down
10 changes: 10 additions & 0 deletions docs-browser/src/sections.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
export const sections = [
{ label: "Guide and Concepts", categories: ["guides", "concepts"] },
{ label: "Components and APIs", categories: ["components", "api"] },
{ label: "Patterns and Pages", categories: ["patterns", "pages"] },
];

export function sectionForPath(pathname: string) {
const category = pathname.split("/")[1];
return sections.find((section) => section.categories.includes(category)) ?? sections[0];
}
8 changes: 8 additions & 0 deletions docs-browser/src/theme.css
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
/* Keep the preview canvas neutral; inherit all other tokens from the default palette. */
:root {
--background: #fff;
}

:root.dark {
--background: #0a0a0a;
}
35 changes: 35 additions & 0 deletions docs-browser/tests/sections.test.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
import assert from "node:assert/strict";
import { test } from "node:test";

import { sectionForPath, sections } from "../src/sections.ts";

test("the three sections partition all six documentation categories", () => {
assert.deepEqual(
sections.map((section) => section.categories),
[
["guides", "concepts"],
["components", "api"],
["patterns", "pages"],
],
);
});

test("document paths select their section, including nested API pages", () => {
for (const [pathname, expected] of [
["/guides/introduction", sections[0]],
["/concepts/styling-theming", sections[0]],
["/components/button", sections[1]],
["/api/guards/hidden", sections[1]],
["/api/router/use-location", sections[1]],
["/patterns/form-composer", sections[2]],
["/pages/standard-page", sections[2]],
]) {
assert.equal(sectionForPath(pathname), expected, pathname);
}
});

test("home and unknown categories default to guides without partial-prefix matches", () => {
for (const pathname of ["/", "/unknown/page", "/components-extra/button", "/apiary/page"]) {
assert.equal(sectionForPath(pathname), sections[0], pathname);
}
});
Loading
Loading