mainmind Docs

Pages with the page kit

Draw a report, plan or comparison as a page with the Mainmind page kit. Copy this starter, then replace the sample data.

Write the page

Save pages/<name>.md: frontmatter, a sentence or two for search, then one fenced jsx block. Push it like any other page. Keep write-class as shown, or the push is refused. More on the file: A visual page.

---
type: Page
title: "Alder & Ash sales"
keeper: reports
write-class: ledger
---

# Alder & Ash sales

Sample sales for Monday and Tuesday, drawn with the page kit.

Then the jsx block, in the same file:

import React from 'react';
import { Page, Header, Grid, Kpi, Card, Line, format } from '@mainmind/kit';

const data = {
  days: [{ label: 'Mon', value: 42000 }, { label: 'Tue', value: 51000 }],
};

export default function SalesPage() {
  return (
    <Page id="sales-page">
      <Header id="heading" title="Alder & Ash sales"
        subtitle="Sample data · Tuesday sales rose from Monday." />
      <Grid id="summary">
        <Kpi id="total" label="Two-day sales" value={data.days.reduce((sum, day) => sum + day.value, 0)}
          valueFormat={format.inr} span={12} />
        <Card id="trend-card" title="Daily sales" span={12}>
          <Line id="trend" label="Sales in rupees" data={data.days} valueFormat={format.inr} />
        </Card>
      </Grid>
    </Page>
  );
}
  • Use only static imports from react and @mainmind/kit. No dynamic import() or import.meta.
  • Use export default for the page component.
  • Keep the JSX source within 120,000 bytes.
  • Do not use require, module or exports as names. Names starting with __mainmind_ are reserved too.
  • No fetch or other network calls. Keep the data in the page.
  • No outside URLs, custom fonts or hex colours. Use the kit and its tokens.
  • Hooks through React.useState or named imports from react are fine.

A page that does not compile is refused at save with its line number. A pushed page that does not compile shows an error card and tells its keeper. A page that compiles but fails while drawing shows the error card only; read the error it names, fix the page and push again.

The page runs in an isolated frame with sandbox="allow-scripts" and no network access. Mainmind sets light or dark mode; let the kit follow it. Links go through the host's Open this link? dialog. To link to another page, use <a id="plan-link" data-page="pages/plan.md">Read the plan</a>.

Eight design rules

  1. Lead with the answer. Use a Header whose subtitle says what changed in one sentence, then 3 or 4 Kpi cards.
  2. Use Grid. Put the main chart in a Card with span={8} and a supporting card with span={4} beside it.
  3. Use kit components and tokens only. No hex colours, custom fonts or outside URLs. Use flavours for series: sky, mint, grape, tangerine, sunny.
  4. Give the page at most one main action. Use few, warm words.
  5. Give every component a stable id. Keep ids when editing.
  6. Put the data in one const data = {...} at the top. Edits should change numbers, not layout.
  7. Check at 390px wide. Nothing should be wider than the screen. Tables should scroll inside their card.
  8. Label sample or estimated numbers as such. For example, put “Sample data” in the subtitle.

Components

Every component accepts id. Give each one a unique, stable value. span is a number from 1 to 12 within a Grid. It defaults to 12 on Card and Stack, and 4 on Kpi. The kit stacks these on small screens.

Layout

ComponentProps besides idUse
Pagechildren, classNameWrap the whole page.
Headertitle, subtitle, actions, childrenState the answer; put a control in actions.
Sectiontitle, childrenGroup related content under a heading.
GridchildrenArrange content in 12 columns.
Stackchildren, spanPut parts in a vertical group.
ClusterchildrenPut small parts together in a wrapping row.
Cardtitle, span, childrenFrame a chart or supporting detail.

Numbers

ComponentProps besides idUse
Kpilabel, value, delta, data, valueFormat, spanShow a key number, a short change note and an optional sparkline.
Progresslabel, value (default 0), max (default 100)Show progress as a share of a target.
Badgechildren, toneMark a status; tone is neutral or a flavour.
Callouttitle, childrenState a finding, next step or risk.

Kpi.value can be a number or display text. valueFormat formats numbers and defaults to format.number. Its data uses the single-value chart shape below. delta is display text, such as “Up 12% from last week”.

Choices

ComponentProps besides idUse
Tabslabel, items, value, defaultValue, onChangeSwitch between panels supplied as item content.
Segmentedlabel, items, value, defaultValue, onChangeChoose a value, such as a chart's date range.

Items have {value, label, content?, disabled?}. Tabs displays content; Segmented only chooses a value. Control either with value and onChange(value), or let it keep its own choice with defaultValue. Both support arrow keys, Home and End.

Lists

ComponentProps besides idUse
Tablecaption, columns, rows, rowKey (default 'id')Show exact values and optional bars, with scrolling inside the table.
TimelineitemsShow dated steps with descriptions and statuses.
Checklistitems, onChangeTrack tasks with checkboxes.
LegenditemsExplain series colours.
  • Table columns: {key, label, number?, bar?, format?, max?}. Rows are plain objects with those keys. number aligns values; bar adds a bar. format(value) supplies display text. A positive max sets the bar scale; otherwise the largest absolute value in that column sets it, with a minimum of 1.
  • Timeline items: {id, title, date?, description?, status?}. Dates use format.date; status is text shown in a badge.
  • Checklist items: {id, label, checked?, disabled?}. Its callback is onChange(id, checked). Update your state there. Without it, boxes are disabled.
  • Legend items: {key?, label, color?}. Use a flavour for color.

Charts

ComponentProps besides idUse
Linedata, series, label, valueFormatCompare trends over time.
Areadata, series, label, valueFormatFill each trend down to zero.
Stackeddata, series, label, valueFormatStack areas to show each series' share over time.
Bardata, series, label, valueFormatCompare categories or negative values; series sit side by side.
Donutdata, label, valueFormatShow positive parts of one whole.
Sparklinedata, series, label, valueFormatAdd a small trend without axes.

Chart data is [{label, value}] for one series, or [{label, <seriesKey>...}] with series: [{key, label, color}]. For example, use {label: 'Mon', sales: 42000, costs: 27000} with series keys sales and costs. Values must be numbers. A plain number array also works; its labels become 1, 2, 3 and so on.

Donut data is [{label, value, color?}]. Each slice uses its row's flavour; series does not control a donut. Negative values show a message asking for a bar chart. Missing or non-finite values are gaps, never invented zeroes.

Charts already include keyboard focus and a View values table. Charts with more than one series include a legend, except sparklines. Donuts include a slice legend. valueFormat defaults to format.number.

format

HelperArgumentsUse
format.numbervalue, options?Indian digit grouping; {compact: true} uses lakh and crore.
format.inrvalue, options?Rupees, with no decimals by default; compact lakh/crore also works.
format.percentvalue, options?Format a fraction: 0.12 becomes 12%.
format.datevalue, options?Format a date in India time (Asia/Kolkata) by default.

Number helpers take Intl.NumberFormat options as well as compact. Dates take a date string, timestamp or Date, plus Intl.DateTimeFormat options. Invalid or missing values show “—”.

Patterns

  • KPI strip: a Grid with three Kpi cards at span 4, or four at span 3.
  • Wide chart and side card: span 8 for the chart, span 4 for progress and a short finding. Use Segmented with React.useState to switch the chart's range.
  • Detail panels: put Tabs below the main answer for deeper tables or notes.
  • Rankings: use a Table with a bar column. Use Bar for negative values; use Donut only for parts of a whole.
  • Plan: pair a Timeline with a Checklist, then state the next risk in a Callout.

Examples

Each block is a complete JSX page component. Put one in the page file described above. All figures below are sample data for Alder & Ash, a small Indian café and bakery chain. Choices and checkboxes change the current view; they do not save task changes back to the page.

Weekly report

The range control changes the main chart. The cards and other charts show the whole week.

import React from 'react';
import {
  Page, Header, Grid, Kpi, Card, Stack, Segmented, Line,
  Progress, Badge, Callout, Bar, Donut, Table, format,
} from '@mainmind/kit';

const data = {
  ranges: [{ value: 'week', label: 'This week' }, { value: 'recent', label: 'Last 3 days' }],
  days: [
    { label: 'Mon', sales: 42000, costs: 27000, orders: 140 },
    { label: 'Tue', sales: 51000, costs: 32000, orders: 160 },
    { label: 'Wed', sales: 47000, costs: 28000, orders: 150 },
    { label: 'Thu', sales: 65000, costs: 36000, orders: 190 },
    { label: 'Fri', sales: 72000, costs: 40000, orders: 200 },
    { label: 'Sat', sales: 89000, costs: 49000, orders: 220 },
    { label: 'Sun', sales: 76000, costs: 44000, orders: 188 },
  ],
  series: [
    { key: 'sales', label: 'Sales', color: 'sky' },
    { key: 'costs', label: 'Costs', color: 'mint' },
  ],
  mix: [
    { label: 'Coffee', value: 282000, color: 'sky' },
    { label: 'Bakery', value: 113000, color: 'mint' },
    { label: 'Other', value: 47000, color: 'grape' },
  ],
  stores: [
    { id: 'indiranagar', name: 'Indiranagar', sales: 186000, orders: 510 },
    { id: 'jayanagar', name: 'Jayanagar', sales: 144000, orders: 416 },
    { id: 'whitefield', name: 'Whitefield', sales: 112000, orders: 322 },
  ],
  columns: [
    { key: 'name', label: 'Café' },
    { key: 'sales', label: 'Sales', number: true, bar: true, format: format.inr },
    { key: 'orders', label: 'Orders', number: true },
  ],
  target: 450000,
  previousSales: 395000,
};

export default function WeeklyReport() {
  const [range, setRange] = React.useState('week');
  const shown = range === 'week' ? data.days : data.days.slice(-3);
  const sales = data.days.reduce((sum, day) => sum + day.sales, 0);
  const costs = data.days.reduce((sum, day) => sum + day.costs, 0);
  const orders = data.days.reduce((sum, day) => sum + day.orders, 0);
  return (
    <Page id="weekly-report">
      <Header id="report-heading" title="Alder & Ash: a stronger week"
        subtitle="Sample data · Sales rose 12% from last week, led by Saturday."
        actions={<Segmented id="chart-range" label="Sales chart range" items={data.ranges}
          value={range} onChange={setRange} />} />
      <Grid id="weekly-kpis">
        <Kpi id="weekly-sales" label="Weekly sales" value={sales} span={4}
          valueFormat={format.inr} delta={`Up ${format.percent(sales / data.previousSales - 1)}`}
          data={data.days.map(day => ({ label: day.label, value: day.sales }))} />
        <Kpi id="weekly-orders" label="Orders" value={orders} span={4}
          data={data.days.map(day => ({ label: day.label, value: day.orders }))} />
        <Kpi id="weekly-balance" label="Sales less costs" value={sales - costs} span={4}
          valueFormat={format.inr}
          data={data.days.map(day => ({ label: day.label, value: day.sales - day.costs }))} />
      </Grid>
      <Grid id="weekly-overview">
        <Card id="sales-chart-card" title="Sales and costs" span={8}>
          <Line id="sales-chart" label="Daily sales and costs" data={shown}
            series={data.series} valueFormat={format.inr} />
        </Card>
        <Card id="weekly-goal-card" title="Nearly there" span={4}>
          <Stack id="weekly-goal-details">
            <Progress id="weekly-goal" label="Weekly sales goal" value={sales} max={data.target} />
            <Badge id="weekly-status" tone="mint">Close to goal</Badge>
            <Callout id="weekly-gap" title="A small gap to close">
              {format.inr(data.target - sales)} short of the weekly goal. Keep coffee ready for Saturday.
            </Callout>
          </Stack>
        </Card>
      </Grid>
      <Grid id="weekly-breakdown">
        <Card id="daily-bars-card" title="Where the week grew" span={6}>
          <Bar id="daily-bars" label="Daily sales beside costs" data={data.days}
            series={data.series} valueFormat={format.inr} />
        </Card>
        <Card id="sales-mix-card" title="What sold" span={6}>
          <Donut id="sales-mix" label="Weekly sales by category" data={data.mix} valueFormat={format.inr} />
        </Card>
      </Grid>
      <Card id="store-table-card" title="Café rankings">
        <Table id="store-table" caption="Sample weekly sales by café" rows={data.stores} columns={data.columns} />
      </Card>
      <Callout id="weekly-next" title="Next week">
        Prepare extra coffee for Saturday. Review Whitefield's morning bakery range with the team.
      </Callout>
    </Page>
  );
}

Plan with timeline

The checklist updates the task count and progress in this view.

import React from 'react';
import {
  Page, Header, Grid, Kpi, Card, Stack, Progress,
  Timeline, Checklist, Stacked, Callout, format,
} from '@mainmind/kit';

const data = {
  budget: 180000,
  asOf: '2026-11-16T00:00:00+05:30',
  launch: '2026-11-30T00:00:00+05:30',
  milestones: [
    { id: 'menu', title: 'Choose the winter menu', date: '2026-11-16',
      description: 'Four bakes and two warm drinks.', status: 'Done' },
    { id: 'tasting', title: 'Team tasting', date: '2026-11-20',
      description: 'Check portions and allergens.', status: 'In progress' },
    { id: 'training', title: 'Practise the morning service', date: '2026-11-25',
      description: 'Try the new menu at all three cafés.', status: 'Planned' },
    { id: 'launch', title: 'Open the winter menu', date: '2026-11-30',
      description: 'Start with a small first batch.', status: 'Planned' },
  ],
  tasks: [
    { id: 'recipes', label: 'Write the recipes', checked: true },
    { id: 'prices', label: 'Check ingredient prices', checked: true },
    { id: 'allergens', label: 'Review the allergen cards', checked: false },
    { id: 'practice', label: 'Book the team practice', checked: false },
    { id: 'signs', label: 'Prepare the menu signs', checked: false },
  ],
  hours: [
    { label: '16 Nov', kitchen: 18, service: 8, design: 10 },
    { label: '20 Nov', kitchen: 24, service: 12, design: 8 },
    { label: '25 Nov', kitchen: 16, service: 24, design: 6 },
    { label: '30 Nov', kitchen: 12, service: 20, design: 2 },
  ],
  teams: [
    { key: 'kitchen', label: 'Kitchen', color: 'tangerine' },
    { key: 'service', label: 'Service', color: 'mint' },
    { key: 'design', label: 'Design', color: 'grape' },
  ],
};

export default function WinterMenuPlan() {
  const [tasks, setTasks] = React.useState(data.tasks);
  const done = tasks.filter(task => task.checked).length;
  const daysLeft = Math.ceil((new Date(data.launch) - new Date(data.asOf)) / 86400000);
  const updateTask = (id, checked) => setTasks(current =>
    current.map(task => task.id === id ? { ...task, checked } : task));
  return (
    <Page id="winter-plan">
      <Header id="plan-heading" title="Alder & Ash: winter menu"
        subtitle="Sample data · The menu is chosen; tasting is the next step." />
      <Grid id="plan-kpis">
        <Kpi id="plan-budget" label="Budget" value={data.budget} valueFormat={format.inr} />
        <Kpi id="plan-days" label="Days left" value={daysLeft}
          delta={`As of ${format.date(data.asOf)}`} />
        <Kpi id="plan-done" label="Tasks done" value={`${done} of ${tasks.length}`} />
      </Grid>
      <Card id="plan-progress-card" title="Ready for the next step">
        <Progress id="plan-progress" label="Preparation complete" value={done} max={tasks.length} />
      </Card>
      <Grid id="plan-effort-row">
        <Card id="team-hours-card" title="Time by team" span={8}>
          <Stacked id="team-hours" label="Sample planned hours by team and date"
            data={data.hours} series={data.teams} valueFormat={format.number} />
        </Card>
        <Card id="plan-focus-card" title="Before the tasting" span={4}>
          <Stack id="plan-focus">
            <Callout id="plan-tasting-note" title="Keep it small">
              Try each bake with the morning team. Record portion sizes before pricing the final menu.
            </Callout>
            <Callout id="plan-date-note" title="Launch date">
              Aim for {format.date(data.launch)}. Use the tasting to decide what needs another try.
            </Callout>
          </Stack>
        </Card>
      </Grid>
      <Grid id="plan-steps">
        <Card id="milestones-card" title="Milestones" span={6}>
          <Timeline id="plan-timeline" items={data.milestones} />
        </Card>
        <Card id="tasks-card" title="Preparation checklist" span={6}>
          <Checklist id="plan-checklist" items={tasks} onChange={updateTask} />
        </Card>
      </Grid>
      <Callout id="plan-risks" title="Watch the ingredient delivery">
        Confirm butter and cocoa before the tasting. If either is late, test the drinks first.
      </Callout>
    </Page>
  );
}

Comparison

Choose an option to see its cost split. The table and bars keep both options in view.

import React from 'react';
import {
  Page, Header, Grid, Kpi, Card, Stack, Cluster, Segmented,
  Table, Bar, Donut, Badge, Callout, format,
} from '@mainmind/kit';

const data = {
  choices: [
    { value: 'refresh', label: 'Refresh the counter' },
    { value: 'expand', label: 'Add a second counter' },
  ],
  options: [
    { id: 'refresh', name: 'Refresh', cost: 300000, days: 4, extraOrders: 60,
      badge: 'Best value', tone: 'mint' },
    { id: 'expand', name: 'Second counter', cost: 480000, days: 9, extraOrders: 90,
      badge: 'More capacity', tone: 'sky' },
  ],
  columns: [
    { key: 'name', label: 'Option' },
    { key: 'cost', label: 'Setup cost', number: true, bar: true, format: format.inr, max: 480000 },
    { key: 'days', label: 'Days closed', number: true },
    { key: 'extraOrders', label: 'Extra orders/day', number: true, bar: true, max: 90 },
  ],
  costs: [
    { label: 'Equipment', refresh: 150000, expand: 240000 },
    { label: 'Fit-out', refresh: 90000, expand: 160000 },
    { label: 'Training', refresh: 60000, expand: 80000 },
  ],
  series: [
    { key: 'refresh', label: 'Refresh', color: 'mint' },
    { key: 'expand', label: 'Second counter', color: 'sky' },
  ],
  parts: [
    { label: 'Equipment', color: 'sky' },
    { label: 'Fit-out', color: 'tangerine' },
    { label: 'Training', color: 'grape' },
  ],
};

export default function CounterComparison() {
  const [choice, setChoice] = React.useState('refresh');
  const selected = data.options.find(option => option.id === choice);
  const split = data.costs.map((row, index) => ({ ...data.parts[index], value: row[choice] }));
  const saving = data.options[1].cost - data.options[0].cost;
  return (
    <Page id="counter-comparison">
      <Header id="comparison-heading" title="Alder & Ash: refresh first"
        subtitle="Sample estimates · Refreshing the counter cuts cost and days closed versus adding another."
        actions={<Segmented id="option-choice" label="Option details" items={data.choices}
          value={choice} onChange={setChoice} />} />
      <Grid id="comparison-kpis">
        <Kpi id="option-cost" label={`${selected.name}: setup`} value={selected.cost} valueFormat={format.inr} />
        <Kpi id="option-days" label="Days closed" value={selected.days} />
        <Kpi id="option-capacity" label="Estimated extra orders/day" value={selected.extraOrders} />
      </Grid>
      <Grid id="comparison-overview">
        <Card id="cost-bars-card" title="Costs beside each other" span={8}>
          <Bar id="cost-bars" label="Sample setup costs by option" data={data.costs}
            series={data.series} valueFormat={format.inr} />
        </Card>
        <Card id="option-notes-card" title="What each option gives you" span={4}>
          <Stack id="option-notes">
            {data.options.map(option => (
              <Cluster id={`option-${option.id}`} key={option.id}>
                {option.name}
                <Badge id={`badge-${option.id}`} tone={option.tone}>{option.badge}</Badge>
              </Cluster>
            ))}
            <Callout id="saving-note" title="Start with the smaller change">
              The refresh saves {format.inr(saving)}. Check morning queues before adding more capacity.
            </Callout>
          </Stack>
        </Card>
      </Grid>
      <Card id="options-table-card" title="Compare the trade-offs">
        <Table id="options-table" caption="Sample estimates for Indiranagar"
          rows={data.options} columns={data.columns} />
      </Card>
      <Grid id="selected-detail">
        <Card id="option-split-card" title={`${selected.name}: cost split`} span={8}>
          <Donut id="option-split" label="Parts of the selected setup cost"
            data={split} valueFormat={format.inr} />
        </Card>
        <Card id="assumptions-card" title="Before deciding" span={4}>
          <Callout id="estimate-note" title="Check these estimates">
            Ask for equipment quotes and time the morning queue. Extra orders depend on demand.
          </Callout>
        </Card>
      </Grid>
      <Callout id="comparison-recommendation" title="Choose the refresh">
        Spend less now and close for fewer days. Review demand after four weeks before adding another counter.
      </Callout>
    </Page>
  );
}

Check it

The page compiles at save. Check it at 390px wide and in light and dark mode. If your page shows an error card, read the line it names, fix it and push again.

Serving: JSX pages with the kit v1. Not yet: selecting a part to comment on, or live data inside pages.