feat: [docs, progress] check props tables in ci and add changelogs

.github/workflows/tests.yml

@@ -37,3 +37,30 @@ jobs:
 
       - name: Check build
         run: pnpm build:apsara
+
+  docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9.3.0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24.x
+          cache: "pnpm"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Test docs tooling
+        run: pnpm test:docs
+
+      - name: Check docs props tables
+        run: pnpm check:docs-props

AGENTS.md

@@ -40,7 +40,9 @@ Skills are in `.agents/skills/`. `.claude/skills` is a symlink to that folder, s
 ## Docs
 
 - When you change props, variants, or behavior, update the docs page.
-- `props.ts` is written by hand, not generated, and `<auto-type-table>` renders it. Check each prop name and value against the component. The two often get out of sync.
+- `props.ts` is written by hand, and `<auto-type-table>` renders it. `pnpm check:docs-props` compares each exported interface with the component type and fails on drift. CI runs it.
+- A docs interface matches the exported type with the same name, then the compound part (`CodeBlockHeaderProps` to `CodeBlock.Header`). Add other matches, docs-only types, inherited components, internal props and props the table keeps required to `CONFIG` in `scripts/check-docs-props.js`, with a reason for each internal or required prop.
+- When a part inherits another Apsara component's props, add an `inherits` entry and write "Inherits all <Component> props" in the part's section of `index.mdx`.
 - `demo.ts` exports demo objects: `{ type: 'code', code }` for examples and `{ type: 'playground', controls, getCode }` for the playground. The code strings render live with the library in scope.
 - Set `defaultValue` on playground controls. The generated code then leaves out props that are at their default.
 

CONTRIBUTING.md

@@ -109,6 +109,7 @@ Do not worry if you miss a step. CI and the maintainers will help.
 
 - PR Title: checks that the title follows the [commit convention](#commit-convention). It runs again when you edit the title.
 - Tests: runs the Vitest suite and builds the library on Node 22 and 24. To reproduce it, run `pnpm test:apsara` and `pnpm build:apsara`.
+- Docs: tests the docs tooling and checks that the props tables match the component types. To reproduce it, run `pnpm test:docs` and `pnpm check:docs-props`.
 - Canary Release: publishes a preview build to [pkg.pr.new](https://pkg.pr.new) and comments the install command on the PR. See [Canary releases](#canary-releases).
 - Vercel: deploys a preview of the docs site with your changes.
 

apps/www/package.json

@@ -3,7 +3,7 @@
   "version": "0.1.0",
   "private": true,
   "scripts": {
-    "prebuild": "cd ../.. && npm run build:apsara",
+    "prebuild": "cd ../.. && (git rev-parse -q --verify refs/tags/v1.0.0 >/dev/null || git fetch -q --tags $(test \"$(git rev-parse --is-shallow-repository)\" = true && echo --unshallow) https://github.com/raystack/apsara.git || true) && npm run build:apsara",
     "dev": "next dev",
     "build": "next build",
     "start": "next start",

apps/www/src/app/docs/[[...slug]]/page.tsx

@@ -3,13 +3,24 @@ import { createRelativeLink } from 'fumadocs-ui/mdx';
 import type { Metadata } from 'next';
 import { notFound } from 'next/navigation';
 import { DemoContextProvider } from '@/components/demo/demo-context';
+import Changelog from '@/components/docs/changelog';
 import DocsFooter from '@/components/docs/footer';
 import DocsNavbar from '@/components/docs/navbar';
 import { mdxComponents } from '@/components/mdx';
 import TableOfContents from '@/components/toc/toc';
+import { getChangelog } from '@/lib/changelog';
 import { docs } from '@/lib/source';
 import styles from './page.module.css';
 
+/** Returns the commit scope of a component page. */
+function changelogScope(slugs: string[]) {
+  const [section, name] = slugs;
+  if (section === 'dataview') return 'data-view';
+  if ((section === 'components' || section === 'ai-elements') && name)
+    return name;
+  return undefined;
+}
+
 export default async function Page(props: PageProps<'/docs/[[...slug]]'>) {
   const params = await props.params;
   const page = docs.getPage(params.slug);
@@ -18,6 +29,10 @@ export default async function Page(props: PageProps<'/docs/[[...slug]]'>) {
   const MDX = page.data.body;
   const content = (page.data._exports?._markdown ?? '') as string;
   const hasPlayground = content.includes('<Demo data={playground}');
+  const scope = changelogScope(page.slugs);
+  const toc = scope
+    ? [...page.data.toc, { title: 'Changelog', url: '#changelog', depth: 2 }]
+    : page.data.toc;
 
   return (
     <DemoContextProvider hasPlayground={hasPlayground} title={page.data.title}>
@@ -59,13 +74,14 @@ export default async function Page(props: PageProps<'/docs/[[...slug]]'>) {
                       a: createRelativeLink(docs, page)
                     }}
                   />
+                  {scope && <Changelog releases={getChangelog(scope)} />}
                 </Flex>
               </Flex>
               <DocsFooter url={page.url} />
             </Flex>
           </Flex>
           <aside className={styles.toc}>
-            <TableOfContents headings={page.data.toc} />
+            <TableOfContents headings={toc} />
           </aside>
         </Flex>
       </Flex>

apps/www/src/components/docs/changelog.tsx

@@ -0,0 +1,42 @@
+import { mdxComponents } from '@/components/mdx';
+import { type ChangelogRelease, RELEASES_URL } from '@/lib/changelog';
+
+const { h2: H2, h3: H3, a: A } = mdxComponents;
+
+export default function Changelog({
+  releases
+}: {
+  releases: ChangelogRelease[] | null;
+}) {
+  return (
+    <>
+      <H2 id='changelog'>Changelog</H2>
+      {releases?.length === 0 && <p>No changes since v1.0.0.</p>}
+      {releases?.map(release => (
+        <section key={release.tag ?? 'unreleased'}>
+          <H3>
+            {release.tag ? (
+              <A href={`${RELEASES_URL}/tag/${release.tag}`}>{release.tag}</A>
+            ) : (
+              'Unreleased'
+            )}
+          </H3>
+          <ul>
+            {release.entries.map(entry => (
+              <li key={entry.pr}>
+                {entry.type}: {entry.summary} (
+                <A href={`https://github.com/raystack/apsara/pull/${entry.pr}`}>
+                  #{entry.pr}
+                </A>
+                )
+              </li>
+            ))}
+          </ul>
+        </section>
+      ))}
+      <p>
+        See <A href={RELEASES_URL}>GitHub Releases</A> for every release.
+      </p>
+    </>
+  );
+}

apps/www/src/content/docs/ai-elements/message/index.mdx

@@ -101,7 +101,8 @@ Every rendered part carries a stable `data-slot` attribute for [styling and test
 | `message-group` | Wrapper around consecutive messages from one sender |
 | `message-avatar` | The sender avatar |
 | `message-header` | Row above the bubble, for sender name and timestamp |
-| `message-content` | The bubble holding the message body |
+| `message-content` | Column holding the message bubbles |
+| `message-bubble` | The message surface |
 | `message-actions` | Action row revealed on the message |
 | `message-footer` | Row below the bubble |
 

apps/www/src/content/docs/ai-elements/prompt-input/index.mdx

@@ -219,6 +219,8 @@ The text field, built on `TextArea variant="borderless"`. It grows with its
 content up to a max-height cap (override with
 `--prompt-input-textarea-max-height`), then scrolls.
 
+- Inherits all TextArea props
+
 <auto-type-table path="./props.ts" name="PromptInputTextareaProps" />
 
 ### Editor

apps/www/src/content/docs/components/accordion/props.ts

@@ -32,12 +32,6 @@ export interface AccordionRootProps<Value = string> {
    */
   disabled?: boolean;
 
-  /**
-   * The orientation of the accordion
-   * @defaultValue "vertical"
-   */
-  orientation?: 'horizontal' | 'vertical';
-
   /**
    * Whether to keep the element in the DOM while the panel is closed
    * @defaultValue false
@@ -56,9 +50,9 @@ export interface AccordionRootProps<Value = string> {
 
 export interface AccordionItemProps {
   /**
-   * A unique value for the item
+   * A unique value for the item. Base UI generates one when it is not set.
    */
-  value: string;
+  value?: string;
 
   /**
    * Whether the item is disabled

apps/www/src/content/docs/components/alert-dialog/index.mdx

@@ -78,6 +78,8 @@ Renders the alert dialog panel overlay.
 
 Renders the alert dialog header section.
 
+- Inherits all Flex props
+
 <auto-type-table path="./props.ts" name="AlertDialogHeaderProps" />
 
 ### Title
@@ -90,6 +92,8 @@ Renders the alert dialog title text.
 
 Renders the main content area of the alert dialog.
 
+- Inherits all Flex props
+
 <auto-type-table path="./props.ts" name="AlertDialogBodyProps" />
 
 ### Description
@@ -108,6 +112,8 @@ Renders the element that opens the alert dialog.
 
 Renders the alert dialog footer section.
 
+- Inherits all Flex props
+
 <auto-type-table path="./props.ts" name="AlertDialogFooterProps" />
 
 ### Slots

apps/www/src/content/docs/components/breadcrumb/props.ts

@@ -1,8 +1,8 @@
 import { ReactElement, ReactNode } from 'react';
 
 export interface BreadcrumbItem {
-  /** Text to display for the item */
-  label: string;
+  /** Content of the item, usually its text */
+  children?: ReactNode;
 
   /** URL for the item link */
   href?: string;

apps/www/src/content/docs/components/button/props.ts

@@ -62,6 +62,9 @@ export type ButtonProps = {
   /** Additional CSS class names */
   className?: string;
 
+  /** Inline styles for the button */
+  style?: React.CSSProperties;
+
   /**
    * Corner radius for this button only. Overrides the theme's `radius`.
    * @defaultValue The theme's `radius`

apps/www/src/content/docs/components/calendar-preview/index.mdx

@@ -171,6 +171,8 @@ The portaled popover surface. Takes `Popover.Content` props — `side`, `align`,
 
 The typeable date field.
 
+- Inherits all Input props
+
 <auto-type-table path="./props.ts" name="CalendarPreviewInputProps" />
 
 ### CalendarPreview.Body
@@ -213,6 +215,8 @@ Step the view one month.
 
 Restores `defaultDate`, reporting `reason: 'reset'`. Carries `data-restored` while there is nothing to restore.
 
+- Inherits all IconButton props
+
 <auto-type-table path="./props.ts" name="CalendarPreviewResetProps" />
 
 ### CalendarPreview.Scales / CalendarPreview.Scale
@@ -237,6 +241,8 @@ The field label above the input, and the rule between the switcher and the view.
 
 The row below the calendar. A bare string is wrapped in `Text`; anything else renders as given.
 
+- Inherits all Flex props
+
 <auto-type-table path="./props.ts" name="CalendarPreviewFooterProps" />
 
 ### useCalendar

apps/www/src/content/docs/components/calendar/demo.ts

@@ -112,7 +112,7 @@ export const rangePickerDemo = {
     {
       name: 'Disabled',
       code: `
-      /* Disabling either input gates the whole picker — the shared popover would otherwise let users rewrite the "disabled" side through the calendar grid. To fix one side, constrain the calendar via \`calendarProps\` instead. */
+      /* Disabling either input gates the whole picker. The shared popover would otherwise let users rewrite the "disabled" side through the calendar grid. To fix one side, constrain the calendar via \`slotProps.calendar\` instead. */
       <RangePicker slotProps={{ startInput: { disabled: true }, endInput: { disabled: true } }} />
       `
     },

apps/www/src/content/docs/components/calendar/props.ts

@@ -137,6 +137,11 @@ export interface CalendarProps {
 }
 
 export interface RangePickerProps {
+  /**
+   * Additional CSS class names for the group that holds the start and end inputs. Ignored when `children` is set.
+   */
+  pickerGroupClassName?: string;
+
   /**
    * Format for displaying the date. Supports various formats:
    * - With slashes: "DD/MM/YYYY", "MM/DD/YYYY", "YYYY/MM/DD"
@@ -150,24 +155,24 @@ export interface RangePickerProps {
   dateFormat?: string;
 
   /**
-   * Fires on every step of range selection — not only on the completed range.
-   * Both fields are optional during partial selection; gate on `range.to` if
-   * you only want completed ranges.
+   * Fires on each day picked in the calendar. `from` is always set, and `to`
+   * is set only when the range is complete. Check `range.to` to handle only
+   * completed ranges.
    */
-  onSelect?: (range: { from?: Date; to?: Date }) => void;
+  onSelect?: (range: { from: Date | undefined; to?: Date }) => void;
 
   /** Initial (uncontrolled) date range. */
-  defaultValue?: { from?: Date; to?: Date };
+  defaultValue?: { from: Date | undefined; to?: Date };
 
   /** Controlled date range. */
-  value?: { from?: Date; to?: Date };
+  value?: { from: Date | undefined; to?: Date };
 
   /**
    * Props for each picker slot. When both this and the legacy
    * `inputsProps` / `calendarProps` / `popoverProps` are set, `slotProps` wins.
    *
-   * Input event handlers (`onChange`, `onFocus`, `onBlur`, `onKeyUp`) are not
-   * forwarded — use `onSelect` for value changes.
+   * The inputs are read-only. RangePicker replaces their `value` and `onClick`.
+   * Use `onSelect` for value changes.
    */
   slotProps?: {
     startInput?: InputProps;
@@ -259,9 +264,6 @@ export interface DatePickerProps {
    */
   onErrorChange?: (error: string | undefined) => void;
 
-  /** @deprecated Use `slotProps.calendar` instead. */
-  calendarProps?: CalendarProps;
-
   /**
    * Render prop or custom trigger. Pass a function to render a custom trigger
    * receiving the formatted `selectedDate` string, or a ReactNode to replace

apps/www/src/content/docs/components/callout/props.ts

@@ -46,11 +46,14 @@ export interface CalloutProps {
   onDismiss?: () => void;
 
   /** Text content of the callout */
-  children?: React.ReactNode;
+  children: React.ReactNode;
 
   /** Additional CSS class names */
   className?: string;
 
+  /** Inline styles for the callout */
+  style?: React.CSSProperties;
+
   /**
    * Corner radius for this callout only. Overrides the theme's `radius`.
    * @defaultValue The theme's `radius`

apps/www/src/content/docs/components/checkbox/props.ts

@@ -12,7 +12,7 @@ export interface CheckboxProps {
   /**
    * Event handler called when the state changes
    */
-  onCheckedChange?: (checked: boolean) => void;
+  onCheckedChange?: (checked: boolean, eventDetails: unknown) => void;
 
   /**
    * When true, the checkbox is in an indeterminate state
@@ -34,7 +34,7 @@ export interface CheckboxProps {
 
   /**
    * When true, the user must tick the checkbox before submitting a form.
-   * @defaultValue false
+   * @default the `required` of the surrounding `Field`, otherwise false
    */
   required?: boolean;
 
@@ -75,7 +75,7 @@ export interface CheckboxGroupProps {
   value?: string[];
 
   /** Event handler called when the checked values change. */
-  onValueChange?: (value: string[], event: Event) => void;
+  onValueChange?: (value: string[], eventDetails: unknown) => void;
 
   /**
    * All checkbox values in the group. Required when using a parent checkbox.

apps/www/src/content/docs/components/chip/props.ts

@@ -31,6 +31,9 @@ export interface ChipProps {
   /** Callback function when dismiss button is clicked */
   onDismiss?: () => void;
 
+  /** Disables the chip and blocks pointer clicks on it */
+  disabled?: boolean;
+
   /** Content to display inside the chip */
   children?: React.ReactNode;