@raystack/chronicle 0.5.4 → 0.6.0

package/src/types/config.ts

@@ -1,3 +1,4 @@
+import uniqBy from 'lodash/uniqBy.js'
 import { z } from 'zod'
 
 const logoSchema = z.object({
@@ -45,19 +46,11 @@ const apiSchema = z.object({
   name: z.string(),
   spec: z.string(),
   basePath: z.string(),
+  icon: z.string().optional(),
   server: apiServerSchema,
   auth: apiAuthSchema.optional(),
 })
 
-const footerSchema = z.object({
-  copyright: z.string().optional(),
-  links: z.array(navLinkSchema).optional(),
-})
-
-const llmsSchema = z.object({
-  enabled: z.boolean().optional(),
-})
-
 const googleAnalyticsSchema = z.object({
   measurementId: z.string(),
 })
@@ -73,24 +66,155 @@ const telemetrySchema = z.object({
   port: z.number().int().min(1).max(65535).default(9090),
 })
 
-export const chronicleConfigSchema = z.object({
+const siteSchema = z.object({
   title: z.string(),
   description: z.string().optional(),
-  url: z.string().optional(),
-  content: z.string().optional(),
-  preset: z.string().optional(),
-  logo: logoSchema.optional(),
-  theme: themeSchema.optional(),
-  navigation: navigationSchema.optional(),
-  search: searchSchema.optional(),
-  footer: footerSchema.optional(),
+})
+
+const DIR_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/
+
+const dirNameSchema = z
+  .string()
+  .min(1)
+  .refine((s) => DIR_NAME_PATTERN.test(s) && s !== '.' && s !== '..', {
+    message:
+      'dir must start with a letter or digit and contain only letters, digits, ".", "_", or "-"',
+  })
+
+const contentEntrySchema = z.object({
+  dir: dirNameSchema,
+  label: z.string().min(1),
+  icon: z.string().optional(),
+})
+
+// Variants map to Apsara Badge color prop.
+// https://apsara.raystack.org/docs/components/badge
+const badgeVariantSchema = z.enum([
+  'accent',
+  'warning',
+  'danger',
+  'success',
+  'neutral',
+  'gradient',
+])
+
+const badgeSchema = z.object({
+  label: z.string().min(1),
+  variant: badgeVariantSchema.default('accent'),
+})
+
+const latestSchema = z.object({
+  label: z.string().min(1),
+  landing: z.boolean().optional(),
+})
+
+const versionSchema = z.object({
+  dir: dirNameSchema,
+  label: z.string().min(1),
+  badge: badgeSchema.optional(),
+  landing: z.boolean().optional(),
+  content: z.array(contentEntrySchema).min(1),
   api: z.array(apiSchema).optional(),
-  llms: llmsSchema.optional(),
-  analytics: analyticsSchema.optional(),
-  telemetry: telemetrySchema.optional(),
 })
 
+const allUnique = <T>(items: T[], key: (item: T) => string): boolean =>
+  uniqBy(items, key).length === items.length
+
+const RESERVED_ROUTE_SEGMENTS = [
+  'api',
+  'apis',
+  'og',
+  'llms.txt',
+  'robots.txt',
+  'sitemap.xml',
+] as const
+
+export const chronicleConfigSchema = z
+  .object({
+    site: siteSchema,
+    url: z.string().optional(),
+    content: z.array(contentEntrySchema).min(1),
+    latest: latestSchema.optional(),
+    versions: z.array(versionSchema).optional(),
+    preset: z.string().optional(),
+    logo: logoSchema.optional(),
+    theme: themeSchema.optional(),
+    navigation: navigationSchema.optional(),
+    search: searchSchema.optional(),
+    api: z.array(apiSchema).optional(),
+    analytics: analyticsSchema.optional(),
+    telemetry: telemetrySchema.optional(),
+  })
+  .strict()
+  .refine((cfg) => allUnique(cfg.content, (c) => c.dir), {
+    message: 'content[].dir must be unique',
+    path: ['content'],
+  })
+  .refine((cfg) => !cfg.versions || allUnique(cfg.versions, (v) => v.dir), {
+    message: 'versions[].dir must be unique',
+    path: ['versions'],
+  })
+  .refine(
+    (cfg) =>
+      !cfg.versions ||
+      cfg.versions.every((v) => allUnique(v.content, (c) => c.dir)),
+    {
+      message: 'versions[].content[].dir must be unique within each version',
+      path: ['versions'],
+    },
+  )
+  .refine((cfg) => !cfg.versions || cfg.versions.length === 0 || !!cfg.latest, {
+    message: 'latest is required when versions are declared',
+    path: ['latest'],
+  })
+  .refine(
+    (cfg) => {
+      if (!cfg.versions) return true
+      const contentDirs = new Set(cfg.content.map((c) => c.dir))
+      return !cfg.versions.some((v) => contentDirs.has(v.dir))
+    },
+    {
+      message:
+        'versions[].dir must not overlap with content[].dir — the URL segment would be shadowed',
+      path: ['versions'],
+    },
+  )
+  .superRefine((cfg, ctx) => {
+    const reserved = new Set<string>(RESERVED_ROUTE_SEGMENTS)
+    const message = `dir must not be a reserved route segment: ${RESERVED_ROUTE_SEGMENTS.join(', ')}`
+
+    cfg.content.forEach((c, i) => {
+      if (reserved.has(c.dir)) {
+        ctx.addIssue({ code: 'custom', message, path: ['content', i, 'dir'] })
+      }
+    })
+    cfg.versions?.forEach((v, vi) => {
+      if (reserved.has(v.dir)) {
+        ctx.addIssue({
+          code: 'custom',
+          message,
+          path: ['versions', vi, 'dir'],
+        })
+      }
+      v.content.forEach((c, ci) => {
+        if (reserved.has(c.dir)) {
+          ctx.addIssue({
+            code: 'custom',
+            message,
+            path: ['versions', vi, 'content', ci, 'dir'],
+          })
+        }
+      })
+    })
+  })
+
 export type ChronicleConfig = z.infer<typeof chronicleConfigSchema>
+export type SiteConfig = z.infer<typeof siteSchema>
+export type ContentEntry = z.infer<typeof contentEntrySchema>
+export type BadgeConfig = z.infer<typeof badgeSchema>
+export type BadgeVariant = z.infer<typeof badgeVariantSchema>
+export type LatestConfig = z.infer<typeof latestSchema>
+export type VersionConfig = z.infer<typeof versionSchema>
 export type LogoConfig = z.infer<typeof logoSchema>
 export type ThemeConfig = z.infer<typeof themeSchema>
 export type NavigationConfig = z.infer<typeof navigationSchema>
@@ -100,8 +224,6 @@ export type SearchConfig = z.infer<typeof searchSchema>
 export type ApiConfig = z.infer<typeof apiSchema>
 export type ApiServerConfig = z.infer<typeof apiServerSchema>
 export type ApiAuthConfig = z.infer<typeof apiAuthSchema>
-export type FooterConfig = z.infer<typeof footerSchema>
-export type LlmsConfig = z.infer<typeof llmsSchema>
 export type AnalyticsConfig = z.infer<typeof analyticsSchema>
 export type GoogleAnalyticsConfig = z.infer<typeof googleAnalyticsSchema>
 export type TelemetryConfig = z.infer<typeof telemetrySchema>

package/src/types/content.ts

@@ -12,7 +12,17 @@ export interface Frontmatter {
   lastModified?: string
 }
 
-export interface Page {
+export interface PageNavLink {
+  url: string
+  title: string
+}
+
+export interface PageNav {
+  prev: PageNavLink | null
+  next: PageNavLink | null
+}
+
+export interface Page extends PageNav {
   slug: string[]
   frontmatter: Frontmatter
   content: ReactNode

package/src/types/theme.ts

@@ -7,6 +7,7 @@ export interface ThemeLayoutProps {
   children: ReactNode
   config: ChronicleConfig
   tree: Root
+  hideSidebar?: boolean
   classNames?: { layout?: string; body?: string; sidebar?: string; content?: string }
 }
 

package/src/components/ui/footer.module.css

@@ -1,27 +0,0 @@
-.footer {
-  border-top: 1px solid var(--rs-color-border-base-primary);
-  padding: var(--rs-space-5) var(--rs-space-7);
-}
-
-.container {
-  max-width: 1200px;
-  margin: 0 auto;
-  width: 100%;
-}
-
-.copyright {
-  color: var(--rs-color-foreground-base-secondary);
-}
-
-.links {
-  flex-wrap: wrap;
-}
-
-.link {
-  color: var(--rs-color-foreground-base-secondary);
-  font-size: 14px;
-}
-
-.link:hover {
-  color: var(--rs-color-foreground-base-primary);
-}

package/src/components/ui/footer.tsx

@@ -1,30 +0,0 @@
-import { Flex, Link, Text } from "@raystack/apsara";
-import type { FooterConfig } from "@/types";
-import styles from "./footer.module.css";
-
-interface FooterProps {
-  config?: FooterConfig;
-}
-
-export function Footer({ config }: FooterProps) {
-  return (
-    <footer className={styles.footer}>
-      <Flex align="center" justify="between" className={styles.container}>
-        {config?.copyright && (
-          <Text size={2} className={styles.copyright}>
-            {config.copyright}
-          </Text>
-        )}
-        {config?.links && config.links.length > 0 && (
-          <Flex gap="medium" className={styles.links}>
-            {config.links.map((link) => (
-              <Link key={link.href} href={link.href} className={styles.link}>
-                {link.label}
-              </Link>
-            ))}
-          </Flex>
-        )}
-      </Flex>
-    </footer>
-  );
-}