@gntik-ai/templates 0.0.0-stage → 0.6.0

package/src/getting-started/data.ts

@@ -0,0 +1,67 @@
+import { BookOpen, Code2, LifeBuoy, PlayCircle, type LucideIcon } from '@gntik-ai/icons';
+import type { BreadcrumbItem } from '@gntik-ai/ui';
+
+export interface SetupTask {
+  id: string;
+  title: string;
+  description: string;
+}
+
+export interface DocLink {
+  id: string;
+  title: string;
+  description: string;
+  href: string;
+  icon: LucideIcon;
+}
+
+export const startBreadcrumbs: BreadcrumbItem[] = [{ label: 'Overview', href: '/overview' }, { label: 'Get started' }];
+
+export const setupTasks: SetupTask[] = [
+  {
+    id: 'workspace',
+    title: 'Create your workspace',
+    description: 'Name it and pick the region where your data lives.',
+  },
+  { id: 'project', title: 'Create a project', description: 'Import a repository or start from a template.' },
+  {
+    id: 'deploy',
+    title: 'Ship your first deployment',
+    description: 'Push to the main branch or deploy from the console.',
+  },
+  { id: 'invite', title: 'Invite your team', description: 'Add teammates and choose what each of them can do.' },
+  { id: 'billing', title: 'Add a payment method', description: 'Needed before you go over the free plan limits.' },
+];
+
+export const setupInitialDone: string[] = ['workspace', 'project'];
+
+export const docLinks: DocLink[] = [
+  {
+    id: 'quickstart',
+    title: 'Quickstart',
+    description: 'Deploy a sample service in five minutes.',
+    href: '#quickstart',
+    icon: PlayCircle,
+  },
+  {
+    id: 'concepts',
+    title: 'Core concepts',
+    description: 'Workspaces, projects, environments and deployments.',
+    href: '#concepts',
+    icon: BookOpen,
+  },
+  {
+    id: 'api',
+    title: 'API reference',
+    description: 'Automate everything you can do in the console.',
+    href: '#api',
+    icon: Code2,
+  },
+  {
+    id: 'support',
+    title: 'Get help',
+    description: 'Guides, community forum and support.',
+    href: '#support',
+    icon: LifeBuoy,
+  },
+];

package/src/getting-started/template.meta.ts

@@ -0,0 +1,12 @@
+import type { TemplateMeta } from '../meta';
+
+export const meta: TemplateMeta = {
+  name: 'Getting started',
+  family: 'Onboarding',
+  priority: 'P2',
+  status: 'beta',
+  description:
+    'Onboarding checklist in the console shell: setup progress, checkable steps with a completion message, and cards linking to the docs.',
+  layout: 'SidebarLayout + Page',
+  blocks: ['app-sidebar', 'app-topbar', 'page-header'],
+};

package/src/help-home/Page.test.tsx

@@ -0,0 +1,33 @@
+import { render, screen, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expectNoAxeViolations } from '../test/a11y';
+import HelpHomePage from './Page';
+import { helpCategories } from './data';
+
+describe('HelpHomePage', () => {
+  it('renders search, categories and popular articles', { timeout: 15000 }, async () => {
+    render(<HelpHomePage />);
+    expect(screen.getByRole('main')).toBeInTheDocument();
+    expect(screen.getByRole('heading', { level: 1, name: 'How can we help?' })).toBeInTheDocument();
+    expect(screen.getByRole('search', { name: 'Help articles' })).toBeInTheDocument();
+    expect(screen.getByRole('navigation', { name: 'Help center' })).toBeInTheDocument();
+    expect(screen.getAllByRole('heading', { level: 3 })).toHaveLength(helpCategories.length);
+    expect(within(screen.getByRole('main')).getByRole('link', { name: 'Deployments' })).toHaveAttribute(
+      'href',
+      '/help/deployments',
+    );
+    expect(screen.getByRole('heading', { level: 2, name: 'Popular articles' })).toBeInTheDocument();
+    await expectNoAxeViolations();
+  });
+
+  it('filters articles and submits the query', { timeout: 15000 }, async () => {
+    const onSearch = vi.fn();
+    render(<HelpHomePage onSearch={onSearch} />);
+    await userEvent.type(screen.getByRole('searchbox', { name: 'Search help articles' }), 'webhook{Enter}');
+    expect(onSearch).toHaveBeenCalledWith('webhook');
+    const results = screen.getByRole('region', { name: 'Search results' });
+    expect(within(results).getAllByRole('listitem')).toHaveLength(1);
+    expect(screen.getByText('1 article')).toBeInTheDocument();
+    expect(screen.queryByRole('heading', { name: 'Browse by topic' })).not.toBeInTheDocument();
+  });
+});

package/src/help-home/Page.tsx

@@ -0,0 +1,159 @@
+import { Clock, Search } from '@gntik-ai/icons';
+import {
+  Badge,
+  ClickableCard,
+  DocsLayout,
+  EmptyState,
+  Grid,
+  Heading,
+  Input,
+  Link,
+  Logo,
+  NavList,
+  Stack,
+  Text,
+  ThemeSwitcher,
+  type NavGroup,
+} from '@gntik-ai/ui';
+import { useId, useState, type FormEvent, type ReactNode } from 'react';
+import { helpArticles, helpCategories, helpNav, searchArticles, type HelpArticle, type HelpCategory } from './data';
+
+export interface HelpHomeProps {
+  /** Logo or product name in the top bar. */
+  brand: ReactNode;
+  title: string;
+  description: string;
+  nav: NavGroup[];
+  currentHref: string;
+  categories: HelpCategory[];
+  /** Popular articles; the search filters them client-side unless `onSearch` handles it. */
+  articles: HelpArticle[];
+  /** Enter in the search field (server-side search). */
+  onSearch: (query: string) => void;
+  /** Text under the popular articles (contact support…). */
+  footer: ReactNode;
+}
+
+/** Help center home on DocsLayout: search, category cards and popular articles. */
+export default function HelpHomePage(props: Partial<HelpHomeProps>) {
+  const {
+    brand = <Logo size={22} wordmark />,
+    title = 'How can we help?',
+    description = 'Guides, answers and troubleshooting for your workspace.',
+    nav = helpNav,
+    currentHref = '/help',
+    categories = helpCategories,
+    articles = helpArticles,
+    onSearch,
+    footer = (
+      <Text variant="supporting" tone="muted">
+        Can’t find what you need? <Link href="/help/support">Contact support</Link>.
+      </Text>
+    ),
+  } = props;
+  const [query, setQuery] = useState('');
+  const ids = useId();
+  const results = searchArticles(articles, query);
+  const searching = query.trim() !== '';
+  const categoryTitle = (id: string) => categories.find((c) => c.id === id)?.title ?? id;
+
+  const submit = (e: FormEvent) => {
+    e.preventDefault();
+    onSearch?.(query.trim());
+  };
+
+  return (
+    <DocsLayout
+      fullScreen
+      header={
+        <>
+          {brand}
+          <Badge tone="neutral" size="sm">
+            Help
+          </Badge>
+          <ThemeSwitcher size="sm" className="ms-auto" />
+        </>
+      }
+      nav={<NavList label="Help center" groups={nav} currentHref={currentHref} />}
+      footer={footer}
+    >
+      <Stack gap={10}>
+        <Stack gap={4}>
+          <Heading level={1} size="xl">
+            {title}
+          </Heading>
+          <Text tone="muted">{description}</Text>
+          <form role="search" aria-label="Help articles" onSubmit={submit} className="max-w-xl">
+            <Input
+              type="search"
+              aria-label="Search help articles"
+              aria-describedby={`${ids}-count`}
+              placeholder="Search articles…"
+              leadingIcon={Search}
+              value={query}
+              onValueChange={setQuery}
+            />
+          </form>
+        </Stack>
+
+        {!searching && (
+          <section aria-labelledby={`${ids}-categories`}>
+            <Heading id={`${ids}-categories`} level={2} size="sm" className="mb-4">
+              Browse by topic
+            </Heading>
+            <Grid cols={{ base: 1, md: 2 }} gap={3}>
+              {categories.map((c) => {
+                const Icon = c.icon;
+                return (
+                  <ClickableCard
+                    key={c.id}
+                    href={c.href}
+                    titleAs="h3"
+                    icon={<Icon aria-hidden />}
+                    title={c.title}
+                    description={c.description}
+                    meta={<span>{c.articleCount} articles</span>}
+                  />
+                );
+              })}
+            </Grid>
+          </section>
+        )}
+
+        <section aria-labelledby={`${ids}-articles`}>
+          <Heading id={`${ids}-articles`} level={2} size="sm" className="mb-1">
+            {searching ? 'Search results' : 'Popular articles'}
+          </Heading>
+          <Text id={`${ids}-count`} variant="caption" tone="muted" aria-live="polite" className="mb-3 block">
+            {searching ? (results.length === 1 ? '1 article' : `${results.length} articles`) : ''}
+          </Text>
+          {results.length === 0 ? (
+            <EmptyState
+              icon={Search}
+              size="sm"
+              titleAs="h3"
+              title="No articles match"
+              description="Try fewer words, or contact support."
+            />
+          ) : (
+            <ul className="divide-y divide-border rounded-xl border border-border">
+              {results.map((a) => (
+                <li key={a.id} className="flex flex-col gap-1 px-4 py-3.5">
+                  <Link href={a.href} className="self-start text-[14px] font-medium">
+                    {a.title}
+                  </Link>
+                  <Text variant="supporting" tone="muted">
+                    {a.excerpt}
+                  </Text>
+                  <Text as="span" variant="caption" tone="muted" className="inline-flex items-center gap-1.5">
+                    {categoryTitle(a.category)} · <Clock size={12} aria-hidden /> {a.minutes} min read
+                  </Text>
+                </li>
+              ))}
+            </ul>
+          )}
+        </section>
+      </Stack>
+    </DocsLayout>
+  );
+}

package/src/help-home/data.ts

@@ -0,0 +1,151 @@
+import { BookOpen, CreditCard, LifeBuoy, Plug, Rocket, Shield, type LucideIcon } from '@gntik-ai/icons';
+import type { NavGroup } from '@gntik-ai/ui';
+
+export interface HelpCategory {
+  id: string;
+  title: string;
+  description: string;
+  icon: LucideIcon;
+  href: string;
+  /** Number of articles in the category. */
+  articleCount: number;
+}
+
+export interface HelpArticle {
+  id: string;
+  title: string;
+  excerpt: string;
+  /** Category id. */
+  category: string;
+  href: string;
+  /** Reading time in minutes. */
+  minutes: number;
+}
+
+export const helpNav: NavGroup[] = [
+  {
+    label: 'Help center',
+    items: [
+      { label: 'Home', href: '/help', icon: LifeBuoy },
+      { label: 'Get started', href: '/help/get-started', icon: Rocket },
+      { label: 'Deployments', href: '/help/deployments', icon: BookOpen },
+    ],
+  },
+  {
+    label: 'Account',
+    items: [
+      { label: 'Billing', href: '/help/billing', icon: CreditCard },
+      { label: 'Security', href: '/help/security', icon: Shield },
+      { label: 'Integrations', href: '/help/integrations', icon: Plug },
+    ],
+  },
+];
+
+export const helpCategories: HelpCategory[] = [
+  {
+    id: 'get-started',
+    title: 'Get started',
+    description: 'Create a workspace, invite your team and ship a first project.',
+    icon: Rocket,
+    href: '/help/get-started',
+    articleCount: 12,
+  },
+  {
+    id: 'deployments',
+    title: 'Deployments',
+    description: 'Environments, previews, rollbacks and deploy gates.',
+    icon: BookOpen,
+    href: '/help/deployments',
+    articleCount: 24,
+  },
+  {
+    id: 'billing',
+    title: 'Billing',
+    description: 'Plans, invoices, usage limits and payment methods.',
+    icon: CreditCard,
+    href: '/help/billing',
+    articleCount: 9,
+  },
+  {
+    id: 'security',
+    title: 'Security',
+    description: 'Single sign-on, two-factor, roles and audit logs.',
+    icon: Shield,
+    href: '/help/security',
+    articleCount: 15,
+  },
+  {
+    id: 'integrations',
+    title: 'Integrations',
+    description: 'Webhooks, API keys and connected services.',
+    icon: Plug,
+    href: '/help/integrations',
+    articleCount: 18,
+  },
+  {
+    id: 'support',
+    title: 'Contact support',
+    description: 'Open a ticket or check the status page.',
+    icon: LifeBuoy,
+    href: '/help/support',
+    articleCount: 4,
+  },
+];
+
+export const helpArticles: HelpArticle[] = [
+  {
+    id: 'a1',
+    title: 'Deploy your first project',
+    excerpt: 'From a repository to a running deployment in five minutes.',
+    category: 'get-started',
+    href: '/help/deploy-first-project',
+    minutes: 5,
+  },
+  {
+    id: 'a2',
+    title: 'Roll back a deployment',
+    excerpt: 'Promote an earlier deployment or schedule a rollback.',
+    category: 'deployments',
+    href: '/help/roll-back',
+    minutes: 3,
+  },
+  {
+    id: 'a3',
+    title: 'Set up single sign-on',
+    excerpt: 'Connect your identity provider with SAML or OIDC.',
+    category: 'security',
+    href: '/help/sso',
+    minutes: 8,
+  },
+  {
+    id: 'a4',
+    title: 'Understand your invoice',
+    excerpt: 'Seats, usage and credits, line by line.',
+    category: 'billing',
+    href: '/help/invoice',
+    minutes: 4,
+  },
+  {
+    id: 'a5',
+    title: 'Verify webhook signatures',
+    excerpt: 'Check the HMAC header before trusting a payload.',
+    category: 'integrations',
+    href: '/help/webhook-signatures',
+    minutes: 6,
+  },
+  {
+    id: 'a6',
+    title: 'Invite members and assign roles',
+    excerpt: 'Owners, admins, members and viewers explained.',
+    category: 'get-started',
+    href: '/help/roles',
+    minutes: 4,
+  },
+];
+
+/** Articles whose title or excerpt contains the query. */
+export function searchArticles(articles: readonly HelpArticle[], query: string): HelpArticle[] {
+  const q = query.trim().toLowerCase();
+  if (!q) return [...articles];
+  return articles.filter((a) => a.title.toLowerCase().includes(q) || a.excerpt.toLowerCase().includes(q));
+}

package/src/help-home/template.meta.ts

@@ -0,0 +1,12 @@
+import type { TemplateMeta } from '../meta';
+
+export const meta: TemplateMeta = {
+  name: 'Help home',
+  family: 'Help',
+  priority: 'P3',
+  status: 'experimental',
+  description:
+    'Help center home on DocsLayout: search with a live result count, category ClickableCards with article counts, popular articles with reading time, and a contact-support footer.',
+  layout: 'DocsLayout',
+  blocks: [],
+};

package/src/home-dashboard/Page.test.tsx

@@ -0,0 +1,57 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expectNoAxeViolations } from '../test/a11y';
+import HomeDashboardPage from './Page';
+import { meta } from './template.meta';
+
+describe('HomeDashboardPage', () => {
+  it('renders the shell, heading, KPIs, charts and activity', { timeout: 15000 }, async () => {
+    const { container } = render(<HomeDashboardPage />);
+    expect(screen.getByRole('main')).toBeInTheDocument();
+    expect(screen.getByRole('heading', { level: 1, name: 'Overview' })).toBeInTheDocument();
+    expect(screen.getByText('Active projects')).toBeInTheDocument();
+    expect(screen.getByRole('heading', { name: 'Infrastructure cost' })).toBeInTheDocument();
+    expect(screen.getByRole('heading', { name: 'Requests' })).toBeInTheDocument();
+    expect(screen.getByRole('region', { name: 'Recent activity' })).toBeInTheDocument();
+    await expectNoAxeViolations(container);
+  });
+
+  it('reports quick actions by id', { timeout: 15000 }, async () => {
+    const onQuickAction = vi.fn();
+    render(<HomeDashboardPage onQuickAction={onQuickAction} />);
+    await userEvent.click(screen.getByRole('button', { name: 'Invite members', description: /teammates/ }));
+    expect(onQuickAction).toHaveBeenCalledWith('invite');
+  });
+
+  it('renders product charts from props', { timeout: 15000 }, () => {
+    const signups = {
+      '7d': [
+        { week: 'W1', Signups: 10, Trials: 4 },
+        { week: 'W2', Signups: 14, Trials: 6 },
+      ],
+    };
+    render(
+      <HomeDashboardPage
+        primaryChart={{
+          title: 'Signups',
+          description: 'New accounts',
+          ranges: [{ value: '7d', label: '7d' }],
+          dataByRange: signups,
+          index: 'week',
+          categories: ['Signups', 'Trials'],
+        }}
+        secondaryChart={{ title: 'Agent runs', categories: ['Requests'] }}
+      />,
+    );
+    expect(screen.getByRole('heading', { name: 'Signups' })).toBeInTheDocument();
+    expect(screen.queryByRole('heading', { name: 'Infrastructure cost' })).toBeNull();
+    expect(screen.getByRole('button', { name: 'Trials' })).toBeInTheDocument();
+    expect(screen.getByRole('heading', { name: 'Agent runs' })).toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: 'Errors' })).toBeNull();
+  });
+
+  it('declares its meta', () => {
+    expect(meta.priority).toBe('P1');
+    expect(meta.blocks).toContain('kpi-row');
+  });
+});

package/src/home-dashboard/Page.tsx

@@ -0,0 +1,152 @@
+import {
+  ActivityFeed,
+  ChartCard,
+  KpiRow,
+  PageHeader,
+  type ActivityItem,
+  type ChartCardProps,
+  type ChartCardRange,
+  type CostPoint,
+  type KpiItem,
+  type PageChromeAction,
+} from '@gntik-ai/blocks';
+import { chartFmt } from '@gntik-ai/charts';
+import { Plus, UserPlus } from '@gntik-ai/icons';
+import { Button, ClickableCard, Grid, GridItem, Page, Section, Stack, type BreadcrumbItem } from '@gntik-ai/ui';
+import { ConsoleShell, type ConsoleShellProps } from '../shared/ConsoleShell';
+import {
+  homeActivity,
+  homeBreadcrumbs,
+  homeKpis,
+  homeQuickActions,
+  homeRequestRanges,
+  homeRequestsByRange,
+  type QuickAction,
+  type RequestPoint,
+} from './data';
+
+/** Second-chart settings (everything but its data and ranges, which have their own props). */
+export type HomeSecondaryChart<S extends object> = Omit<ChartCardProps<S>, 'dataByRange' | 'ranges'>;
+
+/**
+ * `P` is the row type of the first chart (default: the infrastructure-cost fixture), `S` the row
+ * type of the second one (default: requests and errors per day).
+ */
+export interface HomeDashboardProps<P extends object = CostPoint, S extends object = RequestPoint> {
+  title: string;
+  description: string;
+  breadcrumbs: BreadcrumbItem[];
+  /** Header actions (the last one is the primary). */
+  actions: PageChromeAction[];
+  kpis: readonly KpiItem[];
+  /**
+   * First chart: any ChartCard props (title, description, ranges, dataByRange, index, categories,
+   * colors, kind, valueFormatter…). Unset fields keep the infrastructure-cost fixture.
+   */
+  primaryChart: ChartCardProps<P>;
+  /** Data of the second chart, per range key. */
+  requestsByRange: Readonly<Record<string, readonly S[]>>;
+  requestRanges: readonly ChartCardRange[];
+  /** Second chart: title, description, index, categories, colors, kind… (merged over the requests defaults). */
+  secondaryChart: HomeSecondaryChart<S>;
+  activity: readonly ActivityItem[];
+  quickActions: readonly QuickAction[];
+  /** Called with the id of a quick action card (cards with `href` also navigate). */
+  onQuickAction: (id: string) => void;
+  onViewAllActivity: () => void;
+  /** Console frame overrides (nav, user, workspaces, topbar). */
+  shell: Omit<ConsoleShellProps, 'children'>;
+}
+
+const REQUESTS_CHART: HomeSecondaryChart<RequestPoint> = {
+  title: 'Requests',
+  description: 'Requests and errors per day',
+  index: 'day',
+  categories: ['Requests', 'Errors'],
+  colors: ['primary', 'rose'],
+  kind: 'line',
+  stacked: false,
+  valueFormatter: chartFmt.num,
+};
+
+/** Home dashboard: header, KPI row, two charts, recent activity and quick actions in the console shell. */
+export default function HomeDashboardPage<P extends object = CostPoint, S extends object = RequestPoint>({
+  title = 'Overview',
+  description = 'How your workspace is doing across projects, traffic and spend.',
+  breadcrumbs = homeBreadcrumbs,
+  actions = [
+    { label: 'Invite members', icon: UserPlus, variant: 'secondary' },
+    { label: 'New project', icon: Plus, variant: 'primary' },
+  ],
+  kpis = homeKpis,
+  primaryChart,
+  requestsByRange = homeRequestsByRange as unknown as Readonly<Record<string, readonly S[]>>,
+  requestRanges = homeRequestRanges,
+  secondaryChart,
+  activity = homeActivity,
+  quickActions = homeQuickActions,
+  onQuickAction,
+  onViewAllActivity,
+  shell,
+}: Partial<HomeDashboardProps<P, S>>) {
+  const secondary = { ...(REQUESTS_CHART as unknown as HomeSecondaryChart<S>), ...secondaryChart };
+  return (
+    <ConsoleShell currentHref="/overview" breadcrumbs={breadcrumbs} {...shell}>
+      <Page
+        width="wide"
+        header={
+          <PageHeader
+            breadcrumbs={null}
+            title={title}
+            description={description}
+            status=""
+            meta={[]}
+            tabs={null}
+            actions={actions}
+          />
+        }
+      >
+        <Stack gap={6}>
+          <KpiRow items={kpis} />
+          <Grid cols={{ base: 1, lg: 2 }} gap={6}>
+            <ChartCard<P> titleAs="h2" {...primaryChart} />
+            <ChartCard<S> titleAs="h2" {...secondary} ranges={requestRanges} dataByRange={requestsByRange} />
+          </Grid>
+          <Grid cols={{ base: 1, lg: 3 }} gap={6} align="start">
+            <GridItem span={{ base: 1, lg: 2 }}>
+              <Section
+                variant="card"
+                padding="md"
+                title="Recent activity"
+                actions={
+                  <Button variant="ghost" size="sm" onClick={onViewAllActivity}>
+                    View all
+                  </Button>
+                }
+              >
+                <ActivityFeed items={activity} label="Activity, newest first" />
+              </Section>
+            </GridItem>
+            <Section title="Quick actions" description="Common next steps.">
+              <Stack gap={3}>
+                {quickActions.map((qa) => {
+                  const Icon = qa.icon;
+                  return (
+                    <ClickableCard
+                      key={qa.id}
+                      title={qa.title}
+                      description={qa.description}
+                      icon={<Icon aria-hidden />}
+                      href={qa.href}
+                      onClick={() => onQuickAction?.(qa.id)}
+                    />
+                  );
+                })}
+              </Stack>
+            </Section>
+          </Grid>
+        </Stack>
+      </Page>
+    </ConsoleShell>
+  );
+}