docs: fix inaccuracies, dead links, and stale references across docs - #885
Merged
Conversation
Correct wrong information users would hit, repair broken links, align repo docs with the real codebase, and fill documentation gaps. Docs site: - getting-started: fix useTheme import (main entry, not /hooks), correct prerequisites to Node >=22 / React 19, note React peer deps, point Next Steps to DataView instead of the deprecated DataTable - fix 14 internal links missing the /docs base path (overview + theme pages) - select props: variant is 'outline' | 'text' (was 'default' | 'filter'), drop non-existent aria props, add nativeButton - datatable props: replace non-existent columnType with dataType, add loadingRowCount and onRowClick - table props: colSpan is required - add missing Box and ThemeProvider pages (both deprecated aliases, noted) - add missing Accessibility/Examples sections and source frontmatter, rename stray "Usage" headings to "Anatomy" - enrich thin pages and rewrite weak descriptions; drop Lorem Ipsum demo text Repo docs: - add Apache-2.0 LICENSE (was missing); align raystack package license from ISC; copy LICENSE into published packages - README: fix pnpm test -> pnpm test:apsara; drop deprecated DataTable - DEVELOPMENT.md: fix directory layout, build outputs, and hook example - CONTRIBUTING.md: fix docs path and barrel filename; link migration guide and RFCs - agents.md: test-utils is a directory - RFC 003 marked Completed; remove dead ANALYSIS.md links in RFC 002/003 - V1-migration: drop unshipped "1.0.0" framing - apps/www: replace create-next-app boilerplate README
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
Important Review skippedToo many files! This PR contains 113 files, which is 13 over the limit of 100. To get a review, reduce the PR to 100 files or fewer by splitting it into smaller PRs or changing its base branch. Upgrade to a paid plan to raise the limit. This review couldn't start because sufficient usage credits or metered capacity aren't available. Add credits or update usage-based reviews in the billing tab, then retry. ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (113)
You can disable this status message by setting the 📝 WalkthroughWalkthroughThe changes refresh repository structure and contribution guidance, replace the documentation-site starter README, and update documentation routes and prerequisites. Component pages add demos, usage details, accessibility guidance, and API declarations for Box, theme provider, DataTable, Select, and Table. Overview pages update component catalogs and links. Migration and RFC references are revised. Apache License 2.0 text is added to the repository and packages, and the Raystack package metadata changes from ISC to Apache-2.0. Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
commit: |
Rename the theme-provider page to "Theme", drop the ThemeProvider deprecation callout, and rename ThemeProviderProps -> ThemeProps so the page documents only the current theming API (Theme, useTheme, ThemeSwitcher).
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 13
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@apps/www/README.md`:
- Around line 21-26: Add the text language identifier to the file-tree fenced
code block in the README, changing the opening fence to use text/plaintext while
preserving the tree content unchanged.
In `@apps/www/src/content/docs/components/box/props.ts`:
- Around line 1-10: Update the BoxProps documentation to reflect that Box
supports the full ComponentProps<'div'> surface, including ref and other DOM
props, by adding them to the API table or explicitly marking the table as
intentionally limited. Keep the existing children, className, and style entries
accurate.
- Around line 1-10: Update the BoxProps type references to use explicit
type-only imports from react for the ReactNode and CSSProperties types,
replacing the unimported React namespace usage while preserving the existing
children, className, and style prop contracts.
In `@apps/www/src/content/docs/components/context-menu/index.mdx`:
- Around line 19-31: Add visible child text to the Anatomy example’s
ContextMenu.Trigger and ContextMenu.Item elements so copied usage shows a
trigger label and menu-item label; keep the existing component structure
unchanged.
In `@apps/www/src/content/docs/components/datatable/props.ts`:
- Around line 28-33: Remove the unsupported loadingRowCount and onRowClick
declarations from the DataTable props documentation, unless matching renderer
behavior and tests are implemented. Keep the published API limited to props
currently honored by DataTable.
In `@apps/www/src/content/docs/components/dataview/index.mdx`:
- Around line 560-578: Add accessibility tests covering the documented DataView
behaviors: rows with onRowClick receive tabIndex={0}, keyboard events from
interactive descendants do not activate the row, Timeline accepts an aria-label
override, and Timeline decorative axis, ticks, markers, gridlines, and cursor
elements are aria-hidden. Place the tests alongside the existing DataView
accessibility coverage and assert the documented semantics without changing
implementation behavior.
In `@apps/www/src/content/docs/components/empty-state/index.mdx`:
- Around line 3-14: Update the EmptyState anatomy example to pass a valid icon
so it matches the Overview’s required icon guidance. Keep the prose and
required-prop contract unchanged, and use the existing example’s established
icon symbol if available.
In `@apps/www/src/content/docs/components/grid/index.mdx`:
- Around line 66-67: Update the Grid documentation guidance to preserve valid
list semantics: when using a `<ul>` root, configure every `Grid.Item` to render
as `<li>`; recommend `<section>` instead when the children are not list items.
Keep the existing semantic-element guidance and reflect Grid.Item’s default
`<div>` behavior.
In `@apps/www/src/content/docs/components/select/props.ts`:
- Around line 44-45: Update the nativeButton prop documentation to describe how
it affects the element provided through render, clarifying that it makes Base UI
treat that rendered element as a native <button> rather than selecting a
different trigger implementation.
In `@apps/www/src/content/docs/components/table/props.ts`:
- Around line 55-56: Update the colSpan documentation in the table row props
definition to state that it spans the supplied number of columns, without
claiming it guarantees coverage of all table columns. Retain that consumers may
provide a computed full-column span, but describe the prop generically for
callers that pass smaller values.
In `@apps/www/src/content/docs/components/theme-provider/index.mdx`:
- Line 13: Update the Theme documentation paragraph to scope localStorage
persistence and the pre-paint inline script to the root provider. Explicitly
state that nested providers persist only when given storageKey and do not render
the root theme script, while preserving the descriptions of theme management and
design-token attributes.
In `@CONTRIBUTING.md`:
- Around line 96-108: Update the directory-tree code fence in the contributing
guide to specify the text language identifier, changing the opening fence before
the component structure example while leaving the example content unchanged.
In `@DEVELOPMENT.md`:
- Around line 256-258: Update the package output documentation near the ESM,
CommonJS, and TypeScript declaration entries to match the
`packages/raystack/package.json` exports: either remove the `./v1` export if
unsupported or add the generated `/v1` files when it remains supported, keeping
documentation and package metadata consistent.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 04ddd0cc-cef7-44ba-bd00-e65bf78671b8
📒 Files selected for processing (45)
CONTRIBUTING.mdDEVELOPMENT.mdLICENSEagents.mdapps/www/README.mdapps/www/src/content/docs/(overview)/getting-started.mdxapps/www/src/content/docs/(overview)/index.mdxapps/www/src/content/docs/(overview)/styling.mdxapps/www/src/content/docs/components/amount/index.mdxapps/www/src/content/docs/components/announcement-bar/demo.tsapps/www/src/content/docs/components/announcement-bar/index.mdxapps/www/src/content/docs/components/badge/index.mdxapps/www/src/content/docs/components/box/demo.tsapps/www/src/content/docs/components/box/index.mdxapps/www/src/content/docs/components/box/props.tsapps/www/src/content/docs/components/checkbox/index.mdxapps/www/src/content/docs/components/combobox/index.mdxapps/www/src/content/docs/components/container/demo.tsapps/www/src/content/docs/components/container/index.mdxapps/www/src/content/docs/components/context-menu/index.mdxapps/www/src/content/docs/components/copy-button/index.mdxapps/www/src/content/docs/components/datatable/props.tsapps/www/src/content/docs/components/dataview/index.mdxapps/www/src/content/docs/components/empty-state/index.mdxapps/www/src/content/docs/components/flex/index.mdxapps/www/src/content/docs/components/grid/index.mdxapps/www/src/content/docs/components/headline/index.mdxapps/www/src/content/docs/components/link/index.mdxapps/www/src/content/docs/components/menu/index.mdxapps/www/src/content/docs/components/menubar/index.mdxapps/www/src/content/docs/components/scroll-area/index.mdxapps/www/src/content/docs/components/select/props.tsapps/www/src/content/docs/components/table/props.tsapps/www/src/content/docs/components/text/index.mdxapps/www/src/content/docs/components/theme-provider/demo.tsapps/www/src/content/docs/components/theme-provider/index.mdxapps/www/src/content/docs/components/theme-provider/props.tsapps/www/src/content/docs/theme/overview/index.mdxdocs/V1-migration.mddocs/rfcs/002-unified-dataview-component.mddocs/rfcs/003-guided-tour-component.mdpackages/raystack/LICENSEpackages/raystack/README.mdpackages/raystack/package.jsonpackages/tools-config/LICENSE
💤 Files with no reviewable changes (1)
- docs/rfcs/002-unified-dataview-component.md
Comment on lines
+21
to
+26
| ``` | ||
| src/content/docs/components/<name>/ | ||
| ├── index.mdx # the page: overview, anatomy, examples, accessibility | ||
| ├── props.ts # prop tables, rendered by <auto-type-table /> | ||
| └── demo.ts # live code examples shown by the <Demo /> component | ||
| ``` |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Add a language to the file-tree code fence.
Markdownlint reports MD040 at Line [21]. Use text or plaintext for this non-code tree.
Proposed fix
-```
+```text📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ``` | |
| src/content/docs/components/<name>/ | |
| ├── index.mdx # the page: overview, anatomy, examples, accessibility | |
| ├── props.ts # prop tables, rendered by <auto-type-table /> | |
| └── demo.ts # live code examples shown by the <Demo /> component | |
| ``` |
🧰 Tools
🪛 markdownlint-cli2 (0.23.2)
[warning] 21-21: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@apps/www/README.md` around lines 21 - 26, Add the text language identifier to
the file-tree fenced code block in the README, changing the opening fence to use
text/plaintext while preserving the tree content unchanged.
Source: Linters/SAST tools
Comment on lines
+1
to
+10
| export interface BoxProps { | ||
| /** Content rendered inside the box */ | ||
| children?: React.ReactNode; | ||
|
|
||
| /** Custom CSS class names */ | ||
| className?: string; | ||
|
|
||
| /** Inline styles applied to the underlying `<div>` */ | ||
| style?: React.CSSProperties; | ||
| } |
Contributor
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
rg -n -C 12 '\bBoxProps\b|auto-type-table' packages/raystack apps/www/src/content/docs/components/boxRepository: raystack/apsara
Length of output: 5086
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
echo "== locate box files =="
git ls-files | rg '(^|/)packages/raystack/components/box|(^|/)apps/www/src/content/docs/components/box|(^|/)src/content/docs/components/box' || true
echo
echo "== inspect app docs =="
sed -n '1,80p' apps/www/src/content/docs/components/box/index.mdx
echo
sed -n '1,80p' apps/www/src/content/docs/components/box/props.ts
echo
echo "== inspect package files =="
wc -l packages/raystack/components/flex/flex.tsx packages/raystack/components/box 2>/dev/null || true
fd -a . packages/raystack/components | rg 'box|flex' | sed -n '1,80p'Repository: raystack/apsara
Length of output: 5363
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
echo "== package box implementation =="
sed -n '1,120p' packages/raystack/components/box/box.tsx
echo
sed -n '1,60p' packages/raystack/components/box/index.tsx
echo
echo "== package box tests =="
sed -n '1,180p' packages/raystack/components/box/__tests__/box.test.tsx
echo
sed -n '1,160p' packages/raystack/components/box/__tests__/data-slots.test.tsxRepository: raystack/apsara
Length of output: 5656
Mirror the public Box prop surface in the API table.
Box is typed as ComponentProps<'div'>, but props.ts only documents children, className, and style. Add ref/DOM props as a complete row or state that this table is intentionally limited.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@apps/www/src/content/docs/components/box/props.ts` around lines 1 - 10,
Update the BoxProps documentation to reflect that Box supports the full
ComponentProps<'div'> surface, including ref and other DOM props, by adding them
to the API table or explicitly marking the table as intentionally limited. Keep
the existing children, className, and style entries accurate.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
rg -n -C 3 'allowUmdGlobalAccess|typeRoots|types' --glob 'tsconfig*.json' .Repository: raystack/apsara
Length of output: 2325
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
printf 'Candidate files:\n'
fd -a 'tsconfig\.json$|package\.json$' apps/www packages/raystack 2>/dev/null | sed 's#^\./##' | sort
printf '\napps/www/tsconfig.json:\n'
cat -n apps/www/tsconfig.json
printf '\napps/www package manifests referencing react/types:\n'
for f in apps/www/package.json package.json apps/www/node_modules/@types/react/package.json; do
[ -f "$f" ] && printf '\n--- %s ---\n' "$f" && sed -n '1,120p' "$f"
done
printf '\nRelevant docs box props file:\n'
cat -n apps/www/src/content/docs/components/box/props.ts
printf '\nReact namespace usages in apps/www/src/content/docs:\n'
rg -n "React\.(ReactNode|CSSProperties)" apps/www/src/content/docs || true
printf '\nReact imports in apps/www/src/content/docs components:\n'
rg -n "import .*React|from ['\"]react['\"]" apps/www/src/content/docs -g '*.ts' -g '*.tsx' || true
printf '\nCheck lockfiles for `@types/react` version:\n'
rg -n '"`@types/react`"|`@types/react`' -g 'package-lock.json' -g 'pnpm-lock.yaml' -g 'yarn.lock' -g 'bun.lockb' -g 'bun.lock' . | head -80Repository: raystack/apsara
Length of output: 24759
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
printf 'Check if TypeScript compiler is available in sandbox:\n'
if command -v tsc >/dev/null 2>&1; then
tsc --version
tmpdir="$(mktemp -d)"
cat > "$tmpdir/test.ts" <<'TS'
export interface BoxProps {
children?: React.ReactNode;
style?: React.CSSProperties;
}
TS
cat > "$tmpdir/tsconfig.json" <<'JSON'
{
"compilerOptions": {
"module": "ESNext",
"moduleResolution": "bundler",
"strict": true,
"noEmit": true,
"types": []
},
"include": ["test.ts"]
}
JSON
echo "--- --noLib=false, default --allowUmdGlobalAccess ---"
tsc --pretty false --outDir "$tmpdir/out" -p "$tmpdir/tsconfig.json" 2>&1 || true
cat > "$tmpdir/tsconfig.json" <<'JSON'
{
"compilerOptions": {
"module": "ESNext",
"moduleResolution": "bundler",
"strict": true,
"noEmit": true,
"allowUmdGlobalAccess": true
},
"include": ["test.ts"]
}
JSON
echo "--- with allowUmdGlobalAccess ---"
tsc --pretty false --outDir "$tmpdir/out" -p "$tmpdir/tsconfig.json" 2>&1 || true
rm -rf "$tmpdir"
else
echo "tsc not available"
fi
printf '\nInspect base tools-config react tsconfig path if present:\n'
fd -a 'tsconfig.*' packages/raystack | while read -r f; do
[ -f "$f" ] || continue
printf '\n--- %s ---\n' "$f"
cat -n "$f"
done
printf '\nFocused source files importing namespaces/types in docs:\n'
sed -n '1,20p' apps/www/src/content/docs/components/code-block/props.ts
sed -n '1,20p' apps/www/src/content/docs/components/button/props.ts
sed -n '1,20p' apps/www/src/content/docs/components/context-menu/props.tsRepository: raystack/apsara
Length of output: 2954
Import the React types explicitly.
apps/www does not enable allowUmdGlobalAccess, so React.ReactNode and React.CSSProperties are referenced through an unimported global module namespace. Use type-only imports from react instead.
Proposed fix
+import type { CSSProperties, ReactNode } from 'react';
+
export interface BoxProps {
- children?: React.ReactNode;
+ children?: ReactNode;
...
- style?: React.CSSProperties;
+ style?: CSSProperties;
}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| export interface BoxProps { | |
| /** Content rendered inside the box */ | |
| children?: React.ReactNode; | |
| /** Custom CSS class names */ | |
| className?: string; | |
| /** Inline styles applied to the underlying `<div>` */ | |
| style?: React.CSSProperties; | |
| } | |
| import type { CSSProperties, ReactNode } from 'react'; | |
| export interface BoxProps { | |
| /** Content rendered inside the box */ | |
| children?: ReactNode; | |
| /** Custom CSS class names */ | |
| className?: string; | |
| /** Inline styles applied to the underlying `<div>` */ | |
| style?: CSSProperties; | |
| } |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@apps/www/src/content/docs/components/box/props.ts` around lines 1 - 10,
Update the BoxProps type references to use explicit type-only imports from react
for the ReactNode and CSSProperties types, replacing the unimported React
namespace usage while preserving the existing children, className, and style
prop contracts.
Comment on lines
+19
to
+31
| ## Anatomy | ||
|
|
||
| Import and assemble the component: | ||
|
|
||
| ```tsx | ||
| import { ContextMenu } from '@raystack/apsara' | ||
|
|
||
| <ContextMenu> | ||
| <ContextMenu.Trigger /> | ||
| <ContextMenu.Content> | ||
| <ContextMenu.Item /> | ||
| </ContextMenu.Content> | ||
| </ContextMenu> |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Add visible content to the anatomy example.
The snippet uses self-closing ContextMenu.Trigger and ContextMenu.Item. A copied example has no trigger label and no menu-item label. Add minimal children, or label the block as pseudocode.
Proposed fix
<ContextMenu>
- <ContextMenu.Trigger />
+ <ContextMenu.Trigger>Right-click here</ContextMenu.Trigger>
<ContextMenu.Content>
- <ContextMenu.Item />
+ <ContextMenu.Item>Open</ContextMenu.Item>
</ContextMenu.Content>
</ContextMenu>📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ## Anatomy | |
| Import and assemble the component: | |
| ```tsx | |
| import { ContextMenu } from '@raystack/apsara' | |
| <ContextMenu> | |
| <ContextMenu.Trigger /> | |
| <ContextMenu.Content> | |
| <ContextMenu.Item /> | |
| </ContextMenu.Content> | |
| </ContextMenu> | |
| ## Anatomy | |
| Import and assemble the component: | |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@apps/www/src/content/docs/components/context-menu/index.mdx` around lines 19
- 31, Add visible child text to the Anatomy example’s ContextMenu.Trigger and
ContextMenu.Item elements so copied usage shows a trigger label and menu-item
label; keep the existing component structure unchanged.
Comment on lines
+560
to
+578
|
|
||
| ## Accessibility | ||
|
|
||
| - `DataView.List` with `variant="table"` renders real table semantics: | ||
| `role="table"` on the grid with `rowgroup`, `row`, `columnheader`, and | ||
| `cell` on its parts. `variant="list"` uses `role="list"` with `listitem` | ||
| rows instead. | ||
| - When `onRowClick` is set, each row gets `tabIndex={0}` and activates with | ||
| Enter or Space, matching a native button. Rows keep their structural role | ||
| (`row`/`listitem`) so cells stay associated with their row, and key presses | ||
| bubbling up from interactive children (buttons, links in cells) are ignored | ||
| so they don't also trigger row activation. | ||
| - Skeleton loader rows are marked `aria-busy="true"`; the infinite-scroll | ||
| sentinel and the duplicate sticky group-header anchor are `aria-hidden` so | ||
| screen readers don't announce them. | ||
| - The Timeline pane is a focusable, labelled `role="region"` (`aria-label`, | ||
| default "Timeline") that keyboard users can Tab to and scroll with arrow | ||
| keys; the card canvas is a `role="list"` with each card as a `listitem`, | ||
| and decorative gridlines, markers, and the axis are `aria-hidden`. |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
rg -n -C 4 \
--glob '*.{ts,tsx}' \
'\b(DataView\.List|DataView\.Timeline|onRowClick|tabIndex|aria-busy|aria-hidden|Arrow|Enter|Space)\b' .Repository: raystack/apsara
Length of output: 50372
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Locate data-view files"
fd -a 'data-view' packages apps www 2>/dev/null | head -100
echo
echo "Focus tests/implementation"
fd -a '.*\.tsx?$' packages/raystack/components/data-view | head -100Repository: raystack/apsara
Length of output: 3383
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "list.tsx outline"
ast-grep outline packages/raystack/components/data-view/components/list.tsx --view expanded || true
echo
echo "timeline.tsx outline"
ast-grep outline packages/raystack/components/data-view/components/timeline.tsx --view expanded || true
echo
echo "Relevant list implementation slices"
wc -l packages/raystack/components/data-view/components/list.tsx
sed -n '1,260p' packages/raystack/components/data-view/components/list.tsx
echo
echo "Relevant timeline implementation slices"
wc -l packages/raystack/components/data-view/components/timeline.tsx
sed -n '1,360p' packages/raystack/components/data-view/components/timeline.tsx
sed -n '360,560p' packages/raystack/components/data-view/components/timeline.tsxRepository: raystack/apsara
Length of output: 30986
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Remaining list.tsx slice"
sed -n '260,530p' packages/raystack/components/data-view/components/list.tsx
echo
echo "Remaining timeline.tsx slices"
sed -n '560,900p' packages/raystack/components/data-view/components/timeline.tsx
sed -n '900,1180p' packages/raystack/components/data-view/components/timeline.tsx
sed -n '1180,1394p' packages/raystack/components/data-view/components/timeline.tsx
echo
echo "Data view types Timeline/List"
sed -n '1,260p' packages/raystack/components/data-view/data-view.types.tsx
echo
echo "Timeline tests"
wc -l packages/raystack/components/data-view/__tests__/timeline.test.tsx
sed -n '1,260p' packages/raystack/components/data-view/__tests__/timeline.test.tsx
sed -n '260,540p' packages/raystack/components/data-view/__tests__/timeline.test.tsx
sed -n '540,760p' packages/raystack/components/data-view/__tests__/timeline.test.tsx
sed -n '760,1080p' packages/raystack/components/data-view/__tests__/timeline.test.tsxRepository: raystack/apsara
Length of output: 50371
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo
echo "Remaining data-view.types.tsx Timeline interfaces"
sed -n '240,420p' packages/raystack/components/data-view/data-view.types.tsx
echo
echo "Focused data-view list tests"
sed -n '240,290p' packages/raystack/components/data-view/__tests__/data-view.test.tsx
sed -n '830,910p' packages/raystack/components/data-view/__tests__/data-view.test.tsx
sed -n '1040,1090p' packages/raystack/components/data-view/__tests__/data-view.test.tsx
echo
echo "Focused timeline tests"
sed -n '1,120p' packages/raystack/components/data-view/__tests__/timeline.test.tsx
sed -n '120,240p' packages/raystack/components/data-view/__tests__/timeline.test.tsx
sed -n '240,380p' packages/raystack/components/data-view/__tests__/timeline.test.tsx
sed -n '380,520p' packages/raystack/components/data-view/__tests__/timeline.test.tsx
sed -n '520,660p' packages/raystack/components/data-view/__tests__/timeline.test.tsx
sed -n '700,860p' packages/raystack/components/data-view/__tests__/timeline.test.tsx
sed -n '900,1100p' packages/raystack/components/data-view/__tests__/timeline.test.tsx
sed -n '1100,1320p' packages/raystack/components/data-view/__tests__/timeline.test.tsx
sed -n '1320,1480p' packages/raystack/components/data-view/__tests__/timeline.test.tsxRepository: raystack/apsara
Length of output: 50371
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Find docs section around lines 560-578"
wc -l apps/www/src/content/docs/components/dataview/index.mdx
sed -n '520,590p' apps/www/src/content/docs/components/dataview/index.mdxRepository: raystack/apsara
Length of output: 4504
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Search tests for keypress descendant / interactive descendants / aria-hidden hidden / axis labels and decorative markup"
rg -n -C 3 \
--glob '*.ts,*.tsx' \
'\b(interactive descendants|key press|bubb|onKeyDown|children|aria-hidden|listGroup|axis Band|axis Tick|gridline|marker|cursor)\b' \
packages/raystack/components/data-view/__tests__/data-view.test.tsx \
packages/raystack/components/data-view/__tests__/timeline.test.tsx \
packages/raystack/components/data-view/__tests__/data-slots.test.tsx \
packages/raystack/components/data-view/__tests__/data-view.test.tsxRepository: raystack/apsara
Length of output: 15481
Add tests for the documented accessibility behaviors.
The implementation matches most of this section, but documentation-specific coverage is still needed for the row tabIndex={0} case, interactive descendant key handling, Timeline aria-label override, and decorator aria-hidden coverage for axis/ticks/markers/gridlines/cursor.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@apps/www/src/content/docs/components/dataview/index.mdx` around lines 560 -
578, Add accessibility tests covering the documented DataView behaviors: rows
with onRowClick receive tabIndex={0}, keyboard events from interactive
descendants do not activate the row, Timeline accepts an aria-label override,
and Timeline decorative axis, ticks, markers, gridlines, and cursor elements are
aria-hidden. Place the tests alongside the existing DataView accessibility
coverage and assert the documented semantics without changing implementation
behavior.
Comment on lines
+55
to
+56
| /** Number of cells the row should span across. Ensures the section header spans all table columns. (Required) */ | ||
| colSpan: number; |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Clarify what colSpan guarantees.
colSpan spans the number supplied. It does not ensure all table columns by itself. The data-table consumer passes a computed full-column span, but generic callers can pass a smaller value.
Proposed wording
- /** Number of cells the row should span across. Ensures the section header spans all table columns. (Required) */
+ /** Number of columns this header spans. Pass the table's column count
+ * when the header should span the full table. (Required)
+ */📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| /** Number of cells the row should span across. Ensures the section header spans all table columns. (Required) */ | |
| colSpan: number; | |
| /** Number of columns this header spans. Pass the table's column count | |
| * when the header should span the full table. (Required) | |
| */ | |
| colSpan: number; |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@apps/www/src/content/docs/components/table/props.ts` around lines 55 - 56,
Update the colSpan documentation in the table row props definition to state that
it spans the supplied number of columns, without claiming it guarantees coverage
of all table columns. Retain that consumers may provide a computed full-column
span, but describe the prop generically for callers that pass smaller values.
|
|
||
| This page documents the React API for theming: the `Theme` provider component, the `useTheme` hook, and the `ThemeSwitcher` button. For the theming system itself — design tokens, colors, spacing, and scoped theming in depth — see the [Theme overview](/docs/theme/overview). | ||
|
|
||
| `Theme` manages light/dark mode (including the `system` preference), persists the user's choice to localStorage, and applies the `style`, `accentColor`, and `grayColor` attributes that drive Apsara's design tokens. It injects a small inline script so the correct theme is applied before first paint, avoiding a flash of the wrong theme. |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Limit persistence and script behavior to the root provider.
Line 13 states that every Theme persists to localStorage and injects the pre-paint script. A nested scope persists only when it receives storageKey. It renders no root theme script. State these behaviors for the root provider, and document the scoped condition.
Proposed fix
-`Theme` manages light/dark mode (including the `system` preference), persists the user's choice to localStorage, and applies the `style`, `accentColor`, and `grayColor` attributes that drive Apsara's design tokens. It injects a small inline script so the correct theme is applied before first paint, avoiding a flash of the wrong theme.
+At the root, `Theme` manages light/dark mode (including the `system` preference), persists the user's choice to localStorage, and applies the `style`, `accentColor`, and `grayColor` attributes that drive Apsara's design tokens. The root provider injects a small inline script so the correct theme is applied before first paint, avoiding a flash of the wrong theme. A nested `Theme` persists only when it has a `storageKey`.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| `Theme` manages light/dark mode (including the `system` preference), persists the user's choice to localStorage, and applies the `style`, `accentColor`, and `grayColor` attributes that drive Apsara's design tokens. It injects a small inline script so the correct theme is applied before first paint, avoiding a flash of the wrong theme. | |
| At the root, `Theme` manages light/dark mode (including the `system` preference), persists the user's choice to localStorage, and applies the `style`, `accentColor`, and `grayColor` attributes that drive Apsara's design tokens. The root provider injects a small inline script so the correct theme is applied before first paint, avoiding a flash of the wrong theme. A nested `Theme` persists only when it has a `storageKey`. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@apps/www/src/content/docs/components/theme-provider/index.mdx` at line 13,
Update the Theme documentation paragraph to scope localStorage persistence and
the pre-paint inline script to the root provider. Explicitly state that nested
providers persist only when given storageKey and do not render the root theme
script, while preserving the descriptions of theme management and design-token
attributes.
Comment on lines
+96
to
+108
| 1. Create components in `packages/raystack/components/` | ||
| 2. Follow the existing component structure: | ||
| ``` | ||
| component-name/ | ||
| ├── index.ts # Export barrel file | ||
| ├── index.tsx # Export barrel file | ||
| ├── component-name.tsx # Main component | ||
| ├── component-name.module.css # Styles | ||
| └── __tests__/ # Tests | ||
| └── component-name.test.tsx | ||
| ``` | ||
|
|
||
| 3. Export new components from `packages/raystack/index.ts` | ||
| 4. Update the component documentation in `apps/www/content/docs` | ||
| 3. Export new components from `packages/raystack/index.tsx` | ||
| 4. Update the component documentation in `apps/www/src/content/docs` |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Add a language identifier to the directory-tree fence.
markdownlint-cli2 reports MD040 at Line 98. Use a text fence for the directory tree.
Proposed fix
- ```
+ ```text📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| 1. Create components in `packages/raystack/components/` | |
| 2. Follow the existing component structure: | |
| ``` | |
| component-name/ | |
| ├── index.ts # Export barrel file | |
| ├── index.tsx # Export barrel file | |
| ├── component-name.tsx # Main component | |
| ├── component-name.module.css # Styles | |
| └── __tests__/ # Tests | |
| └── component-name.test.tsx | |
| ``` | |
| 3. Export new components from `packages/raystack/index.ts` | |
| 4. Update the component documentation in `apps/www/content/docs` | |
| 3. Export new components from `packages/raystack/index.tsx` | |
| 4. Update the component documentation in `apps/www/src/content/docs` | |
| 1. Create components in `packages/raystack/components/` | |
| 2. Follow the existing component structure: |
🧰 Tools
🪛 markdownlint-cli2 (0.23.2)
[warning] 98-98: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@CONTRIBUTING.md` around lines 96 - 108, Update the directory-tree code fence
in the contributing guide to specify the text language identifier, changing the
opening fence before the component structure example while leaving the example
content unchanged.
Source: Linters/SAST tools
The Theme provider and useTheme were documented in both the Theme overview and a components/theme page. The theme section is the apt home: it already covers the theming system, tokens, and scoped theming, all of which reference Theme and useTheme. - Remove the duplicate components/theme page. - Fold ThemeSwitcher (component + live demos) and the useTheme options overload into theme/overview, which previously lacked both. - Rename ThemeProviderProps -> ThemeProps and drop the ThemeProvider deprecation note so only the current API is documented.
…d harness Prepare the docs for the next cleanup release by removing everything deprecated from the docs site. Docs content: - Remove the deprecated DataTable and Box pages and every link to them (getting-started, intro, README highlights, floating-actions now points to DataView row selection). - Strip all @deprecated prop entries from the API tables (sidebar, calendar, indicator, dataview, empty-state, table); keep the one className explicitly marked "not deprecated". - Drop the data-table exception note from the styling page. - Add explanatory text to the thin list and table Examples sections. Site harness cleanup: - Remove the old playground example harness, standalone /examples routes, navbar, theme-customiser, and docs-body components. - Delete the orphaned DataTable demo components and drop them from the live-demo scope; rename chip/menu demo files. Verified: docs site builds (no MDX errors), headings are consistent (no level skips), no deprecated references remain in docs content.
- select: clarify nativeButton describes the render element, not a variant - DEVELOPMENT: note ./v1 is a legacy alias for the root dist output - empty-state: pass required icon in the anatomy example - table: clarify colSpan must equal the total column count
The old Step 7 described the deleted playground/*-examples.tsx harness. Rewrite it around the interactive playground driven by the demo.ts playground export, and drop the dead playground/ dir from the file tree.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Cleanup pass across all documentation — the docs site, repo-level guides, and RFCs. Fixes wrong information users would hit, repairs broken links, aligns docs with the real codebase, and fills gaps. Everything was verified against source; the docs site builds clean (191 pages, no MDX errors).
Wrong information (highest impact)
useThemenow imports from the main entry (was the broken/hookspath); prerequisites corrected to Node ≥22 / React 19 (were Node 18 / React 18); added React peer-dep note; Next Steps point to DataView instead of the deprecated DataTable./docsbase path — now resolve.variantis'outline' | 'text'(was'default' | 'filter'); removed non-existent aria props; addednativeButton.columnTypewith the realdataType; addedloadingRowCountandonRowClick.colSpanis required.License
package.jsonlicense fromISCtoApache-2.0.tools-configalready declared it; only the raystackpackage.jsondisagreed (ISC). Easy to flip if ISC was the intent.Repo docs
pnpm test→pnpm test:apsara; dropped deprecated DataTable from highlights.v1/tree), build outputs, and a non-existent hook in an example.test-utilsis a directory.ANALYSIS.mdlinks in RFC 002/003.New & improved content pages
Themeprovider anduseThemewere documented in two places. Consolidated the React API into the Theme overview (its natural home alongside tokens and scoped theming), folded inThemeSwitcherand theuseThemeoptions overload, and removed the duplicatecomponents/themepage. Documents only the current API — the deprecatedThemeProvideralias is dropped.source:frontmatter; renamed stray "Usage" headings to "Anatomy".How it was found
Three parallel read-only audits (docs-site content, props accuracy vs source, repo-level docs). Every finding was verified against the actual component TypeScript and package config before fixing.
Test plan
pnpm --filter www buildsucceeds (191 pages, no MDX errors)/docsinternal linksDeprecation cleanup (prep for next cleanup release)
floating-actionsnow points to DataView row selection.@deprecatedprop entries from the API tables (sidebar, calendar, indicator, dataview, empty-state, table) — kept the one className explicitly marked "not deprecated".listandtableExamples sections.#H1 in body, no heading-level skips, consistent H2 → H3 → H4 nesting./examplesroutes, and related dead components, and removes the orphaned DataTable demo components.