@molecule/app-gradebook-react
Feature · gradebook · App (browser) · v1.0.2 · Apache-2.0
Gradebook UI — table of grades (course / assignment / letter / numeric / weight / contribution-to-GPA) plus optional GpaCard hero
npm install @molecule/app-gradebook-reactHow it works
@molecule/app-gradebook-react is a ready-made gradebook feature for the app (browser) side. It composes the core interfaces it needs, so it works with whichever providers your app has bonded.
import type { Grade } from '@molecule/app-gradebook-react'
import { Gradebook, GpaCard } from '@molecule/app-gradebook-react'
const rows: Grade[] = [
{ id: 'g1', title: 'Algebra II', letter: 'A-', score: 92, weight: 0.25, contribution: 0.92 },
]
function GradesPage() {
return (
<>
<GpaCard gpa={3.72} scale="4.0" trend="up" />
<Gradebook gpaScale="4.0" grades={rows} />
</>
)
}Works with: @molecule/app-react, @molecule/app-ui, @molecule/app-ui-react
Reference
Gradebook UI — unified table of grades + optional GPA hero card.
Pairs with the @molecule/api-resource-grade resource. Rows can be courses
or assignments — the caller picks the granularity. The letter column renders
Grade.letter as plain text (string); pass pre-styled content via title
if you need richer cells.
Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit
src/index.tsJSDoc, not this file.
Quick Start
import type { Grade } from '@molecule/app-gradebook-react'
import { Gradebook, GpaCard } from '@molecule/app-gradebook-react'
const rows: Grade[] = [
{ id: 'g1', title: 'Algebra II', letter: 'A-', score: 92, weight: 0.25, contribution: 0.92 },
]
function GradesPage() {
return (
<>
<GpaCard gpa={3.72} scale="4.0" trend="up" />
<Gradebook gpaScale="4.0" grades={rows} />
</>
)
}
Type
feature
Installation
npm install @molecule/app-gradebook-react @molecule/app-react @molecule/app-ui @molecule/app-ui-react react
npm install -D @types/react
API
Interfaces
GpaCardProps
Props for GpaCard.
interface GpaCardProps {
/** The numeric GPA value (or percentage when `scale='percentage'`). */
gpa: number
/** Which scale `gpa` is expressed on. Drives formatting + the "out of" text. */
scale: GpaScale
/** Override the maximum value shown in the "out of" caption. */
max?: number
/** Optional trend chip — render up/down/flat with localized label. */
trend?: GpaTrend
/** Optional caption rendered below the trend (e.g. "vs. last semester"). */
trendLabel?: ReactNode
/** Extra classes merged onto the root element. */
className?: string
}
GradebookProps
Props for Gradebook.
interface GradebookProps {
/** Rows to display. Each row may represent a course or an assignment — caller's choice. */
grades: Grade[]
/** GPA scale used for numeric rendering of contribution / score columns. */
gpaScale: GpaScale
/** Optional cell-click handler — fires with the grade row + the column key clicked. */
onCellClick?: (grade: Grade, column: GradebookColumn) => void
/** Extra classes merged onto the root `<table>` wrapper. */
className?: string
}
Grade
A single row in the gradebook. Rows can represent either a course
(assignmentTitle doubles as the course name) or an individual
assignment — the caller picks the granularity.
interface Grade {
/** Stable identifier (used as the React key). */
id: string
/** Course or assignment title shown in the first column. */
title: ReactNode
/** Letter grade (e.g. `'A-'`, `'B+'`). Optional — derived display only. */
letter?: string
/** Numeric score. Interpreted relative to `maxPoints` (or 0–100 when omitted). */
score: number
/** Maximum points / denominator for the score. Defaults to 100. */
maxPoints?: number
/** Course / assignment weight (0–1) — used to compute the GPA contribution. */
weight?: number
/** Pre-computed contribution to overall GPA. Optional — caller may pre-compute. */
contribution?: number
/** When the grade was posted. Display-only. */
postedAt?: ReactNode
}
Types
GradebookColumn
Column identifiers exposed via onCellClick.
type GradebookColumn = 'title' | 'letter' | 'numeric' | 'weight' | 'contribution' | 'posted'
GpaScale
GPA scale supported by the gradebook.
'4.0'— US-style 4.0 unweighted scale.'5.0'— US-style 5.0 weighted scale (honours / AP).'percentage'— 0–100 percentage rendering (no GPA conversion applied).
type GpaScale = '4.0' | '5.0' | 'percentage'
GpaTrend
Trend direction for the GPA trend chip.
type GpaTrend = 'up' | 'down' | 'flat'
Functions
GpaCard(props)
Hero card displaying the user's GPA — large primary value, "out of"
caption, and optional trend chip. Pairs with Gradebook above /
beside the table view.
Styling routes through getClassMap() and all text routes through t()
via the companion @molecule/app-locales-gradebook locale bond.
function GpaCard(props: GpaCardProps): JSX.Element
props— Component props.
Returns: The GPA hero card element.
Gradebook(props)
Unified gradebook table — title, letter grade, numeric score, weight, and contribution-to-GPA. Rows can be either courses or assignments; the caller decides which granularity to pass.
Pairs with GpaCard for the hero summary. Styling routes through
getClassMap(); all visible text routes through t() via the companion
@molecule/app-locales-gradebook locale bond.
function Gradebook(props: GradebookProps): JSX.Element
props— Component props.
Returns: The gradebook element.
computePercentage(grade)
Compute a percentage [0, 100] from a Grade row. When maxPoints
is missing or ≤ 0 the score is treated as already being a percentage.
function computePercentage(grade: Grade): number
grade— The grade row.
Returns: The percentage value clamped to [0, 100].
formatGpa(value, scale)
Format a numeric GPA for display. Percentages render with no decimals; 4.0 / 5.0 scales render with two decimals.
function formatGpa(value: number, scale: GpaScale): string
value— The GPA / percentage value to format.scale— The scale being displayed.
Returns: A locale-independent string representation.
defaultGpaMax(scale)
Default ceiling for a given GPA scale.
function defaultGpaMax(scale: GpaScale): number
scale— The GPA scale.
Returns: The default maximum value for that scale.
Injection Notes
Requirements
Peer dependencies:
@molecule/app-react^1.0.1@molecule/app-ui^1.0.1@molecule/app-ui-react^1.0.1react^18.0.0 || ^19.0.0
Runtime Dependencies
@molecule/app-react@molecule/app-ui@molecule/app-ui-reactreact
All visible text routes through t() via the companion
@molecule/app-locales-gradebook locale bond. Both components call
useTranslation() (THROWS outside @molecule/app-react's I18nProvider)
and getClassMap() (requires a bonded ClassMap such as
@molecule/app-ui-tailwind) — wire both before rendering. No Tailwind
utilities appear in this package.
Translations
Translation strings are provided by @molecule/app-locales-gradebook.