diff --git a/Makefile b/Makefile index 741bc7bfbb8..765305b6111 100644 --- a/Makefile +++ b/Makefile @@ -33,9 +33,15 @@ requirements: ## install ci requirements # Instead of having this directly in the build-docs script # in the top-level package.json, put it here so we can have # a single source of truth and get proper error codes in CI +# +# ✨ For our prototype, we're overriding the docs build so we can see the new storybook on Netlify .PHONY: build-docs build-docs: - npm run build --workspace=www + cd prototype && npm install + cd prototype && npm run build + cd prototype && npm run build-storybook + rm -rf www/public + cp -r prototype/storybook-static www/public # npm swallows errors # see https://github.com/openedx/paragon/issues/3329 diff --git a/docs/decisions/0022-modernization-remove-bootstrap.rst b/docs/decisions/0022-modernization-remove-bootstrap.rst new file mode 100644 index 00000000000..a7e3b63bde5 --- /dev/null +++ b/docs/decisions/0022-modernization-remove-bootstrap.rst @@ -0,0 +1,201 @@ +22. Modernization: Removing Bootstrap and Modernizing the Toolchain +------------------------------------------------------------------- + +Status +------ + +Proposed + +Context +------- + +Paragon is a mature, accessibility-focused React component library. Its public +surface has two stable, widely-depended-upon contracts: + +1. The **React component API** — ~99 exports whose props are consumed by dozens + of Open edX micro-frontends (MFEs). +2. The **design-tokens theming API** — a ``style-dictionary`` pipeline that + compiles DTCG-style token JSON into CSS custom properties, shipped as + ``core.css`` / ``light.css`` and overridden by ``@edx/brand`` packages. + +Underneath those contracts, however, Paragon rests on aging foundations: + +- **Bootstrap 4** provides both a *behavior* layer (34 components wrap + ``react-bootstrap`` sub-components) and a *style* layer (``core.scss`` imports + ``~bootstrap/scss/{reboot,root,mixins,transitions,grid,...}``). Bootstrap 4 is + no longer actively developed, is built on legacy SCSS, and blocks adoption of + modern CSS and tooling. ``react-bootstrap`` v1 targets Bootstrap 4 and is + effectively frozen for our purposes. +- The **build** relies on Babel + ``tsc`` + a hand-written ``Makefile``. +- **Tests** run on Jest with ``ts-jest`` / ``babel-jest``. +- The **documentation site** runs on Gatsby 5 with + ``gatsby-transformer-react-docgen`` and ``react-docgen`` v5, which parses + JavaScript rather than our TypeScript types. This makes props tables + unreliable and the doc pipeline difficult to maintain. + +Two properties of the current codebase make modernization tractable rather than +requiring a hard fork: + +- Paragon components are already **thin adapters**: Paragon owns the public prop + API and delegates internals to ``react-bootstrap``. Swapping the internal + engine does not, by itself, change the public API. +- The **theming/token pipeline is already Bootstrap-independent**. Components + reference token-derived CSS custom properties; the ``source: $scss-var`` field + on each token is only a back-compat bridge to Bootstrap SCSS variables. The + emitted ``core.css`` / ``light.css`` contract does not depend on Bootstrap. + +A TypeScript migration is also already ~half complete (roughly 31 ``index.tsx`` +vs. 27 ``index.jsx`` at time of writing). + +This ADR supersedes the direction of: + +- **ADR 0004** (Usage of Bootstrap) and **ADR 0009** (Usage of React-Bootstrap), + which established Bootstrap and ``react-bootstrap`` as foundations. + +It also revisits **ADR 0006** (Removal of CSS Module Support). ADR 0006 removed +CSS Modules for one specific reason: component SCSS files imported Bootstrap +*partials* (mixins/variables) that drifted between Bootstrap minor versions and +caused compile errors in consuming apps. Once Bootstrap SCSS is removed +entirely, that objection no longer applies — the CSS Modules reintroduced here +consume only Paragon's own token CSS custom properties, never Bootstrap +partials. + +Decision +-------- + +We will re-implement Paragon on modern, fully-typed foundations while preserving +both public contracts (the React component API and the design-tokens theming +API). The change is delivered **incrementally** — swapping engines behind stable +APIs — not as a big-bang rewrite. + +Concretely: + +1. **Behavior layer → React Aria Components.** Replace ``react-bootstrap`` with + `React Aria Components `_. It is + headless (leaving Paragon in full control of DOM and CSS), fully typed, and + provides best-in-class WAI-ARIA patterns plus built-in internationalization + and RTL support — a direct fit for Paragon's accessibility and ``react-intl`` + commitments. Each component's public props are preserved; only the internal + engine changes. This also retires ``uncontrollable``, ``tabbable``, and + ``react-focus-on``. + +2. **Style layer → a two-layer model over token CSS variables.** Remove Bootstrap + SCSS, replacing it with: + + a. A **global, public class layer** — the Bootstrap-compatible class names + Paragon has always shipped and that consumers apply directly to their own + markup: the component classes (``btn``, ``btn-``, ``btn-lg``, + ``btn-group``, ``collapsible-card``, …), the grid (``col-*``), and the + layout/spacing utilities (``d-flex``, ``flex-grow-1``, …). **These class + names are part of Paragon's public API and are preserved**, so existing + consumer markup such as ```` keeps rendering + correctly. They are re-authored from Bootstrap SCSS into plain native CSS + over the same ``--pgn-*`` tokens (``:where()`` for zero-specificity + utilities, logical properties for RTL, container queries), and generated + from the token set rather than hand-maintained. Consumer usage + (``dependent-usage.json``) guides which of Bootstrap's utilities to keep + versus drop via major-version releases. + + b. **CSS Modules for component-internal implementation details** that are *not* + part of the public class contract (e.g. a disclosure's animation wrapper or + a focus-ring hook), so those stay locally scoped and cannot leak. + + The public class layer is the single source of truth for appearance: React + components **apply the same public classes** a consumer would write by hand and + add only behavior (React Aria) on top, so a component and its raw-HTML + equivalent render identically. This supersedes an earlier prototype iteration + that styled ``Button`` with hashed CSS-Module classes plus a ``data-variant`` + attribute; that approach broke the public class contract (a raw + ```` received no styles) and is not carried forward. + +3. **Design-tokens theming API → preserved unchanged.** The ``style-dictionary`` + pipeline and the emitted ``core.css`` / ``light.css`` CSS-variable contract + stay byte-compatible so ``@edx/brand`` themes and consuming MFEs are + unaffected. Additionally, a new build target emits a typed ``tokens.ts`` so + tokens are first-class in TypeScript. The ``source: $scss-var`` back-compat + field is removed only after Bootstrap SCSS is gone. + +4. **Supporting dependencies:** + + - ``react-table`` v7 → **TanStack Table v8** (same author, fully typed). + - ``@popperjs`` / ``react-popper`` → **Floating UI** or React Aria overlays. + - ``axios`` → native ``fetch``. + - ``classnames`` → ``clsx`` (or retain). + - Retain: ``style-dictionary``, ``chroma-js``, ``react-intl``, + ``react-colorful``, ``react-dropzone``, ``react-imask``, + ``react-loading-skeleton``. + +5. **Build → Vite (library mode) + ``vite-plugin-dts``** (or ``tsup``), + replacing Babel + ``tsc`` + ``Makefile``. Emits ESM + ``.d.ts`` and preserves + ``sideEffects``/tree-shaking. + +6. **Tests → Vitest**, keeping ``@testing-library/react`` and the existing + accessibility assertions. + +7. **Documentation → Storybook 10 (Vite builder)**, retiring Gatsby, + ``gatsby-transformer-react-docgen``, ``react-docgen`` v5, ``react-live``, and + Playroom. Props tables are generated from TypeScript types + (``react-docgen-typescript``); existing per-component ``README.md`` / ``.mdx`` + map onto Storybook Docs pages; interactive controls replace Playroom; the a11y + addon and interaction/visual testing reinforce the accessibility mission. + +8. **Complete the TypeScript migration** so the library is 100% typed. + +Migration sequence +~~~~~~~~~~~~~~~~~~~ + +The work ships continuously behind stable public APIs: + +1. Switch build to Vite, tests to Vitest, finish remaining ``.jsx → .tsx``, and + emit a typed ``tokens.ts``. No consumer-visible change. +2. Replace Bootstrap SCSS imports with a token-built reset/grid/utility layer. + Snapshot the full set of emitted CSS custom properties to prove the theming + contract held. +3. Swap the behavior engine component-by-component onto React Aria (and DataTable + onto TanStack Table), leaf components first, each shipping independently. +4. Stand up Storybook 10 alongside Gatsby, port component pages, then retire + Gatsby. +5. Remove the ``source:`` SCSS back-compat from tokens and drop the legacy + dependencies (``bootstrap``, ``react-bootstrap``, ``axios``, + ``uncontrollable``, ``tabbable``, ``react-focus-on``, ``sass``). + +Consequences +------------ + +- **Public contracts are preserved.** Because components are adapters and the + token pipeline is Bootstrap-independent, the React component API and the CDN + ``core.css`` / ``light.css`` theming contract remain stable. ``@edx/brand`` + themes and consuming MFEs upgrade without breaking, likely across one or two + major versions rather than a fork. +- **Accessibility improves**, since React Aria's ARIA/keyboard/focus/i18n + behavior is more rigorous and better maintained than our Bootstrap 4 baseline. +- **The styling model splits into a public class layer and private CSS Modules.** + The Bootstrap-compatible class names remain global and public (see Decision 2a); + component-*internal* styles move to scoped CSS Modules over token variables. + This reintroduces CSS Modules (cf. ADR 0006) but without the Bootstrap-partial + version-drift problem that motivated their removal. +- **Consumers relying on raw Bootstrap 4 class names** (e.g. ``btn``, + ``btn-outline-primary``, ``col-*``, utility classes) rather than Paragon + components or tokens keep working: the class names they depend on are preserved + as the public class layer, re-authored in plain CSS over tokens. Any Bootstrap + classes no consumer uses (per ``dependent-usage.json``) are pruned via + major-version releases rather than silently. +- **Guardrails required before removal steps:** snapshot the emitted CSS + custom-property set (theming regression net), keep per-component + ``@testing-library`` + a11y assertions as the public-API contract test, and use + ``dependent-usage.json`` to confirm which utility classes and props consumers + actually use before pruning. +- **Toolchain is unified** on Vite/Vitest/Storybook, reducing bespoke build code + (Makefile, Babel config, Gatsby plugins) and making the docs site maintainable. + +References +---------- + +* React Aria Components: https://react-spectrum.adobe.com/react-aria/ +* TanStack Table: https://tanstack.com/table/latest +* Floating UI: https://floating-ui.com/ +* Vite library mode: https://vitejs.dev/guide/build.html#library-mode +* Storybook: https://storybook.js.org/ +* ADR 0004 (Usage of Bootstrap), ADR 0006 (Removal of CSS Module Support), + ADR 0009 (Usage of React-Bootstrap), ADR 0018 (Design Tokens / + ``style-dictionary``), ADR 0019 (Scaling Styles with Design Tokens) diff --git a/prototype/.gitignore b/prototype/.gitignore new file mode 100644 index 00000000000..c6be3abe7c2 --- /dev/null +++ b/prototype/.gitignore @@ -0,0 +1,4 @@ +node_modules/ +dist/ +storybook-static/ +*.tsbuildinfo diff --git a/prototype/.storybook/main.ts b/prototype/.storybook/main.ts new file mode 100644 index 00000000000..9d0c8dd22b5 --- /dev/null +++ b/prototype/.storybook/main.ts @@ -0,0 +1,28 @@ +import { fileURLToPath } from "node:url"; +import { dirname } from "node:path"; +import type { StorybookConfig } from '@storybook/react-vite'; + +const config: StorybookConfig = { + stories: ['../src/**/*.mdx', '../src/**/*.stories.@(ts|tsx)'], + addons: [getAbsolutePath("@storybook/addon-a11y"), getAbsolutePath("@storybook/addon-docs")], + framework: { + name: getAbsolutePath("@storybook/react-vite"), + options: {}, + }, + // Props tables are generated from the TypeScript types below, replacing the + // legacy Gatsby + react-docgen v5 pipeline that parsed JavaScript. + typescript: { + reactDocgen: 'react-docgen-typescript', + reactDocgenTypescriptOptions: { + shouldExtractLiteralValuesFromEnum: true, + shouldRemoveUndefinedFromOptional: true, + propFilter: (prop) => (prop.parent ? !/node_modules/.test(prop.parent.fileName) : true), + }, + }, +}; + +export default config; + +function getAbsolutePath(value: string): any { + return dirname(fileURLToPath(import.meta.resolve(`${value}/package.json`))); +} diff --git a/prototype/.storybook/preview.tsx b/prototype/.storybook/preview.tsx new file mode 100644 index 00000000000..5e51372472c --- /dev/null +++ b/prototype/.storybook/preview.tsx @@ -0,0 +1,26 @@ +import type { Preview } from '@storybook/react-vite'; + +// Load the design-token CSS custom properties globally, exactly as a consuming +// app would. This is the *same* compiled token output the real library ships — +// proof that the CSS Modules approach preserves the theming contract. +import '../src/tokens.css'; +// The reboot-replacement base layer, so story/docs frames inherit Paragon's +// root typography just like a consuming app would. +import '../src/base.css'; +// The global, public class layer (btn / utilities / component classes) so docs +// live examples can use `btn btn-outline-primary`, `d-flex`, `collapsible-card` +// etc. exactly as a consuming app (and the source READMEs) do. +import '../src/styles/index.css'; + +const preview: Preview = { + parameters: { + controls: { + matchers: { + color: /(background|color)$/i, + date: /Date$/i, + }, + }, + }, +}; + +export default preview; diff --git a/prototype/README.md b/prototype/README.md new file mode 100644 index 00000000000..4bea3353ebd --- /dev/null +++ b/prototype/README.md @@ -0,0 +1,97 @@ +# Paragon modernization prototype — Button module + +This is the **Step 1 reference implementation** for +[ADR 0022](../docs/decisions/0022-modernization-remove-bootstrap.rst). It +migrates the full `Button` module (`Button`, `ButtonGroup`, `ButtonToolbar`) +onto the proposed modern stack, in isolation, without touching the live library +build. + +It is intentionally self-contained and **not published** — it exists to let the +Paragon Working Group evaluate the approach concretely. + +## What it demonstrates + +| Concern | Old | This prototype | +| --- | --- | --- | +| Behavior | `react-bootstrap` | **React Aria** (`useButton`, `useFocusRing`) | +| Styling | Bootstrap 4 SCSS, global classes | Public **global classes** (`btn`, utilities) re-authored in plain CSS + **CSS Modules** for internals, all over the same `--pgn-*` tokens | +| Theming API | `style-dictionary` → CSS vars | **Unchanged** — imported verbatim (`src/tokens.css`) | +| Types | mixed `.jsx`/`.tsx` | **100% TypeScript** | +| Build | Babel + tsc + Makefile | **Vite** library mode + `vite-plugin-dts` | +| Tests | Jest | **Vitest** + Testing Library | +| Docs | Gatsby + react-docgen v5 | **Storybook 10** (props from TS types) | + +The public prop API (`variant`, `size`, `iconBefore/After`, `as`, `disabled`, +`onClick`, …) is preserved from `@openedx/paragon`'s Button, so consuming code +does not change. + +## Running it + +```bash +cd prototype +npm install +npm test # Vitest unit + a11y-ish behavior tests +npm run storybook # interactive workbench at http://localhost:6007 +npm run build # ESM + .d.ts into dist/ +``` + +## Toolchain versions + +The prototype tracks TypeScript 6 and Vite 8 (Vite 8 bundles with Rolldown). + +**We cannot move to TypeScript 7 yet.** Storybook's prop tables are generated by +`@joshwooding/vite-plugin-react-docgen-typescript`, which parses component types +with `react-docgen-typescript`. Both rely on TypeScript's JavaScript Compiler +API. TypeScript 7 is the native (Go) port and does not yet expose that API, so +the plugin does not support it — the docgen step (and therefore Storybook's +auto-generated props docs) breaks under TS 7. Once +`@joshwooding/vite-plugin-react-docgen-typescript` ships TypeScript 7 support we +can bump `typescript` accordingly. + +## Key migration decisions surfaced here (for WG ratification) + +1. **Polymorphic `as` via `useButton`, not ` + + + + + +); + +export const coreButtonsInverse = ( + + + + + + + +); + +export const utilityButtons = ( + <> + + + + + + + + + + + + + + +); + +export const sizes = ( + <> + + + + + + + + + + + + + +); + +export const inlineSize = ( +

+ 2 items selected. + + +

+); + +export const blockButtons = ( + <> + + + +); + +export const disabled = ( + + + + + +); + +export const emptyHref = ( + + + + +); + +export const withIcons = ( + + + + + + + +); + +/** Editable source strings for react-live, extracted verbatim from this file. */ +export const examples = extractExamples(raw); diff --git a/prototype/src/Button/Button.test.tsx b/prototype/src/Button/Button.test.tsx new file mode 100644 index 00000000000..fd07429fa18 --- /dev/null +++ b/prototype/src/Button/Button.test.tsx @@ -0,0 +1,94 @@ +import { render, screen } from '@testing-library/react'; +import userEvent from '@testing-library/user-event'; +import { describe, it, expect, vi } from 'vitest'; + +import { Button } from './Button'; +import { ButtonGroup } from './ButtonGroup'; +import { ButtonToolbar } from './ButtonToolbar'; + +describe('Button', () => { + it('renders a native button with its children', () => { + render(); + const btn = screen.getByRole('button', { name: 'Save' }); + expect(btn.tagName).toBe('BUTTON'); + }); + + it('applies the public Bootstrap-compatible variant class', () => { + render(); + const btn = screen.getByRole('button', { name: 'Delete' }); + // Global, stable class names (not hashed) — the same public API a raw + // `` relies on. + expect(btn).toHaveClass('btn', 'btn-danger'); + }); + + it('forwards the legacy onClick handler', async () => { + const onClick = vi.fn(); + const user = userEvent.setup(); + render(); + await user.click(screen.getByRole('button', { name: 'Click' })); + expect(onClick).toHaveBeenCalledTimes(1); + }); + + it('fires React Aria onPress for keyboard activation', async () => { + const onPress = vi.fn(); + const user = userEvent.setup(); + render(); + await user.tab(); + await user.keyboard('{Enter}'); + expect(onPress).toHaveBeenCalled(); + }); + + it('does not fire handlers when disabled', async () => { + const onClick = vi.fn(); + // Bypass user-event's pointer-events guard; the CSS disables pointer events, + // but we want to assert the handler itself never fires. + const user = userEvent.setup({ pointerEventsCheck: 0 }); + render(); + await user.click(screen.getByRole('button', { name: 'Nope' })); + expect(onClick).not.toHaveBeenCalled(); + }); + + it('renders as a custom element via `as` while staying an accessible button', () => { + render(); + const el = screen.getByRole('button', { name: 'Docs' }); + expect(el.tagName).toBe('A'); + expect(el).toHaveAttribute('href', 'https://openedx.org'); + }); + + it('marks a disabled anchor as aria-disabled (no native disabled on )', () => { + render(); + expect(screen.getByText('Docs')).toHaveAttribute('aria-disabled', 'true'); + }); + + it('forwards a ref to the underlying element', () => { + const ref = { current: null as HTMLElement | null }; + render(); + expect(ref.current).toBeInstanceOf(HTMLButtonElement); + }); +}); + +describe('ButtonGroup / ButtonToolbar', () => { + it('exposes group and toolbar roles', () => { + render( + + + + + + , + ); + expect(screen.getByRole('toolbar', { name: 'tools' })).toBeInTheDocument(); + expect(screen.getByRole('group', { name: 'group' })).toBeInTheDocument(); + }); + + it('propagates its size to child buttons via context', () => { + render( + + + , + ); + // The size class is applied from context; assert the button rendered. + // (Class hashing is environment-specific, so we assert presence + role.) + expect(screen.getByRole('button', { name: 'Small via group' })).toBeInTheDocument(); + }); +}); diff --git a/prototype/src/Button/Button.tsx b/prototype/src/Button/Button.tsx new file mode 100644 index 00000000000..970ecc93cd7 --- /dev/null +++ b/prototype/src/Button/Button.tsx @@ -0,0 +1,102 @@ +import React, { useContext } from 'react'; +import { + useButton, useFocusRing, useObjectRef, mergeProps, +} from 'react-aria'; +import clsx from 'clsx'; + +import type { ButtonProps } from './types'; +import { ButtonGroupContext } from './ButtonGroupContext'; +import '../styles/button.css'; + +const SIZE_CLASS = { + sm: 'btn-sm', + md: undefined, + lg: 'btn-lg', + inline: 'btn-inline', +} as const; + +/** + * Accessible, themeable Button. + * + * Behaviour comes from React Aria's `useButton` (cross-device press handling, + * correct `disabled` semantics even when rendered as an `` via `as`, and + * focus-ring state) rather than Bootstrap. The public prop API is unchanged + * from `@openedx/paragon`'s Button, and all styling is driven by the existing + * `--pgn-*` design tokens. + */ +export const Button = React.forwardRef(( + { + as, + variant = 'primary', + size, + iconBefore: IconBefore, + iconAfter: IconAfter, + disabled = false, + block = false, + className, + children, + onClick, + onPress, + type = 'button', + ...rest + }, + forwardedRef, +) => { + const ref = useObjectRef(forwardedRef as React.ForwardedRef); + const ElementType: React.ElementType = as ?? 'button'; + const groupSize = useContext(ButtonGroupContext); + const resolvedSize = size ?? groupSize ?? 'md'; + + const { buttonProps, isPressed } = useButton( + { + elementType: ElementType, + isDisabled: disabled, + onPress, + type, + 'aria-label': rest['aria-label'], + }, + ref, + ); + const { isFocusVisible, focusProps } = useFocusRing(); + + return ( + ` (+ size/block). These are the same + // Bootstrap-compatible class names Paragon has always shipped, so a raw + // `` renders identically to this component. + className={clsx( + 'btn', + `btn-${variant}`, + SIZE_CLASS[resolvedSize], + block && 'btn-block', + className, + )} + > + {IconBefore && ( + + + + )} + {children} + {IconAfter && ( + + + + )} + + ); +}); + +Button.displayName = 'Button'; + +export default Button; diff --git a/prototype/src/Button/ButtonGroup.mdx b/prototype/src/Button/ButtonGroup.mdx new file mode 100644 index 00000000000..8ba2f94f7a7 --- /dev/null +++ b/prototype/src/Button/ButtonGroup.mdx @@ -0,0 +1,53 @@ +import { Meta, Title, Subtitle, Story, Controls } from '@storybook/addon-docs/blocks'; + +import * as ButtonGroupStories from './ButtonGroup.stories'; +import { LiveExample } from '../docs/LiveExample'; + +export const examples = ButtonGroupStories.examples; + + + +Button Group + +Group related buttons so they read as a single control; ButtonToolbar arranges multiple groups. + +`ButtonGroup` visually and semantically groups related `Button`s (ARIA +`role="group"`). It renders the public `btn-group` class (part of Paragon's +global class layer) and additionally propagates its `size` to child buttons via +React context — replacing Bootstrap's `.btn-group-sm` / `.btn-group-lg` sizing +classes — while inner border radii are collapsed with logical properties so the +group works in both LTR and RTL. + +`ButtonToolbar` (ARIA `role="toolbar"`) lays out one or more groups. + +## Playground + +Edit the props with the controls and the JSX below regenerates; you can also type +directly in the editor to experiment. Changing a control overwrites the editor. + + + + + +## Sizes + +A group sets the size of every button it contains — set it once on the group +rather than on each `Button`. + + + +## Vertical + + + +## ButtonToolbar + +Compose several groups inside a `ButtonToolbar`. + + + +## Accessibility notes + +- Always provide an `aria-label` on each `ButtonGroup` and `ButtonToolbar`. +- Use `ButtonToolbar` when you have more than one group, so assistive tech + announces the toolbar and its constituent groups correctly. diff --git a/prototype/src/Button/ButtonGroup.stories.tsx b/prototype/src/Button/ButtonGroup.stories.tsx new file mode 100644 index 00000000000..7ac9d17c0a3 --- /dev/null +++ b/prototype/src/Button/ButtonGroup.stories.tsx @@ -0,0 +1,89 @@ +import type { Meta, StoryObj } from '@storybook/react-vite'; + +import { Button } from './Button'; +import { ButtonGroup } from './ButtonGroup'; +import { ButtonToolbar } from './ButtonToolbar'; +import { LivePlayground, generateCode, playgroundChildren } from '../docs/LivePlayground'; +import { extractExamples } from '../docs/extractExamples'; +import raw from './ButtonGroup.stories.tsx?raw'; + +const meta: Meta = { + // Separate hidden root — see the note in Button.stories.tsx. + title: 'Internal/ButtonGroup', + component: ButtonGroup, + tags: ['!dev'], + // PascalCase exports are stories; camelCase exports below are typechecked + // docs example source (see Button.stories.tsx for the full rationale). + includeStories: /^[A-Z]/, + parameters: { layout: 'padded' }, + args: { size: 'md', vertical: false }, + argTypes: { + size: { control: 'inline-radio', options: ['sm', 'md', 'lg', 'inline'] }, + vertical: { control: 'boolean' }, + // Plain-text children make no sense here (the group holds Buttons); hide the + // control rather than let Storybook auto-generate a ReactNode "Set object" one. + children: { table: { disable: true } }, + }, +}; + +export default meta; +type Story = StoryObj; + +export const Playground: Story = { + render: (args) => ( + Bold', + '', + '', + ].join('\n')), + })} + /> + ), +}; + +/* + * Docs live examples — typechecked TSX, source-extracted for react-live. + * camelCase so `includeStories` excludes them from Storybook. See + * Button.stories.tsx for the full rationale. + */ + +export const sizes = ( +
+ + + + + + + + +
+); + +export const vertical = ( + + + + + +); + +export const toolbar = ( + + + + + + + + + + + +); + +/** Editable source strings for react-live, extracted verbatim from this file. */ +export const examples = extractExamples(raw); diff --git a/prototype/src/Button/ButtonGroup.tsx b/prototype/src/Button/ButtonGroup.tsx new file mode 100644 index 00000000000..2760728e94f --- /dev/null +++ b/prototype/src/Button/ButtonGroup.tsx @@ -0,0 +1,55 @@ +import React from 'react'; +import clsx from 'clsx'; + +import type { ButtonSize } from './types'; +import { ButtonGroupContext } from './ButtonGroupContext'; +import '../styles/button.css'; + +export interface ButtonGroupProps { + /** Specifies element type for this component (default: `div`). */ + as?: React.ElementType; + /** An ARIA role describing the button group (default: `group`). */ + role?: React.AriaRole; + /** Sets the size for all Buttons in the group (default: `md`). */ + size?: ButtonSize; + /** Stack the Buttons vertically (default: `false`). */ + vertical?: boolean; + className?: string; + children: React.ReactNode; + 'aria-label'?: string; +} + +/** + * Groups related Buttons and propagates a shared `size` to them via context, + * replacing Bootstrap's `.btn-group-*` global-class mechanism. + */ +export const ButtonGroup = React.forwardRef(( + { + as, + role = 'group', + size = 'md', + vertical = false, + className, + children, + ...rest + }, + ref, +) => { + const ElementType: React.ElementType = as ?? 'div'; + return ( + + + {children} + + + ); +}); + +ButtonGroup.displayName = 'ButtonGroup'; + +export default ButtonGroup; diff --git a/prototype/src/Button/ButtonGroupContext.ts b/prototype/src/Button/ButtonGroupContext.ts new file mode 100644 index 00000000000..859d78b2b24 --- /dev/null +++ b/prototype/src/Button/ButtonGroupContext.ts @@ -0,0 +1,9 @@ +import { createContext } from 'react'; +import type { ButtonSize } from './types'; + +/** + * Lets a `ButtonGroup` set the size of all descendant `Button`s, replicating + * Bootstrap's `.btn-group-sm` / `.btn-group-lg` behaviour without global + * class-name coupling. `undefined` means "no group override". + */ +export const ButtonGroupContext = createContext(undefined); diff --git a/prototype/src/Button/ButtonToolbar.tsx b/prototype/src/Button/ButtonToolbar.tsx new file mode 100644 index 00000000000..93025e35b43 --- /dev/null +++ b/prototype/src/Button/ButtonToolbar.tsx @@ -0,0 +1,38 @@ +import React from 'react'; +import clsx from 'clsx'; + +import '../styles/button.css'; + +export interface ButtonToolbarProps { + /** Specifies element type for this component (default: `div`). */ + as?: React.ElementType; + /** An ARIA role describing the toolbar (default: `toolbar`). */ + role?: React.AriaRole; + className?: string; + children: React.ReactNode; + 'aria-label'?: string; +} + +/** A flex container that lays out one or more ButtonGroups. */ +export const ButtonToolbar = React.forwardRef(( + { + as, role = 'toolbar', className, children, ...rest + }, + ref, +) => { + const ElementType: React.ElementType = as ?? 'div'; + return ( + + {children} + + ); +}); + +ButtonToolbar.displayName = 'ButtonToolbar'; + +export default ButtonToolbar; diff --git a/prototype/src/Button/index.ts b/prototype/src/Button/index.ts new file mode 100644 index 00000000000..8ddda877fed --- /dev/null +++ b/prototype/src/Button/index.ts @@ -0,0 +1,6 @@ +export { default, Button } from './Button'; +export { ButtonGroup } from './ButtonGroup'; +export { ButtonToolbar } from './ButtonToolbar'; +export type { ButtonProps, ButtonVariant, ButtonSize, BaseVariant } from './types'; +export type { ButtonGroupProps } from './ButtonGroup'; +export type { ButtonToolbarProps } from './ButtonToolbar'; diff --git a/prototype/src/Button/types.ts b/prototype/src/Button/types.ts new file mode 100644 index 00000000000..d771018b024 --- /dev/null +++ b/prototype/src/Button/types.ts @@ -0,0 +1,83 @@ +import type React from 'react'; +import type { PressEvent } from 'react-aria'; + +/** + * The eleven base button variants Paragon ships. Preserved exactly from the + * current `@openedx/paragon` Button API. + */ +export type BaseVariant = ( + | 'primary' + | 'secondary' + | 'tertiary' + | 'brand' + | 'success' + | 'danger' + | 'warning' + | 'info' + | 'dark' + | 'light' + | 'link' +); + +/** + * Every valid `variant` value: each base variant plus its `outline-`, + * `inverse-` and `inverse-outline-` forms. This is the same union the current + * TypeScript Button exposes, so consumers see no change. + */ +export type ButtonVariant = + | BaseVariant + | `inverse-${BaseVariant}` + | `outline-${BaseVariant}` + | `inverse-outline-${BaseVariant}`; + +export type ButtonSize = 'sm' | 'md' | 'lg' | 'inline'; + +export interface ButtonProps { + /** Set a custom element for this component (default: `button`, with `type="button"`). */ + as?: React.ElementType; + /** Specifies variant to use (default: `primary`). */ + variant?: ButtonVariant; + /** Button size. Note `md` and `inline` are Paragon extensions over Bootstrap. */ + size?: ButtonSize; + /** + * An icon component to render before the label. Example: + * ``` + * import { Close } from '@openedx/paragon/icons'; + * + * ``` + */ + iconBefore?: React.ComponentType; + /** An icon component to render after the label. */ + iconAfter?: React.ComponentType; + /** Disables the Button, even when rendered as a non-`', + '', + '', + ].join('\n')), + })} + /> + ), +}; + +/* + * Docs live examples — typechecked TSX, source-extracted for react-live. + * camelCase so `includeStories` excludes them from Storybook. See + * Button.stories.tsx for the full rationale. + */ + +export const vertical = ( + + + + + +); + +export const horizontal = ( + +
first block
+
second block
+
third block
+ +); + +export const reversedVertical = ( + + + + + +); + +export const reversedHorizontal = ( + +
first block
+
second block
+
third block
+ +); + +/** Editable source strings for react-live, extracted verbatim from this file. */ +export const examples = extractExamples(raw); diff --git a/prototype/src/Stack/Stack.test.tsx b/prototype/src/Stack/Stack.test.tsx new file mode 100644 index 00000000000..b92365dc2e8 --- /dev/null +++ b/prototype/src/Stack/Stack.test.tsx @@ -0,0 +1,55 @@ +import { render, screen } from '@testing-library/react'; +import { describe, it, expect } from 'vitest'; + +import { Stack } from './Stack'; + +describe('Stack', () => { + it('renders a vertical stack by default', () => { + render(Content); + const stack = screen.getByTestId('stack'); + expect(stack.tagName).toBe('DIV'); + expect(stack.className).toMatch(/vstack/); + }); + + it('renders a horizontal stack when direction is horizontal', () => { + render(Content); + expect(screen.getByTestId('stack').className).toMatch(/hstack/); + }); + + it('applies the gap class for the matching spacer level', () => { + render(Content); + // Gap is token-driven via a CSS Module class, not an inline style. + expect(screen.getByTestId('stack').className).toMatch(/gap-3/); + expect(screen.getByTestId('stack').getAttribute('style')).toBeNull(); + }); + + it('maps half-step gaps onto the spacer scale (1.5 -> gap-1-5)', () => { + render(Content); + expect(screen.getByTestId('stack').className).toMatch(/gap-1-5/); + }); + + it('applies the reversed modifier', () => { + render(Content); + expect(screen.getByTestId('stack').className).toMatch(/reversed/); + }); + + it('forwards className and DOM attributes', () => { + render(Content); + const stack = screen.getByTestId('stack'); + expect(stack.className).toContain('extra'); + expect(stack).toHaveAttribute('aria-label', 'things'); + }); + + it('forwards a caller-supplied style alongside the gap class', () => { + render(Content); + const stack = screen.getByTestId('stack'); + expect(stack.style.marginTop).toBe('1rem'); + expect(stack.className).toMatch(/gap-2/); + }); + + it('forwards a ref to the underlying element', () => { + const ref = { current: null as HTMLDivElement | null }; + render(Content); + expect(ref.current).toBeInstanceOf(HTMLDivElement); + }); +}); diff --git a/prototype/src/Stack/Stack.tsx b/prototype/src/Stack/Stack.tsx new file mode 100644 index 00000000000..06d13db3bfd --- /dev/null +++ b/prototype/src/Stack/Stack.tsx @@ -0,0 +1,64 @@ +import React from 'react'; +import clsx from 'clsx'; + +import styles from './Stack.module.css'; + +export interface StackProps extends React.HTMLAttributes { + /** Specifies the content of the `Stack`. */ + children: React.ReactNode; + /** Specifies direction of the children blocks (default: `vertical`). */ + direction?: 'horizontal' | 'vertical'; + /** + * Inner space between children, on the Paragon spacer scale. + * + * Valid values match the `--pgn-spacing-spacer-*` tokens: + * `0, 1, 2, 3, 4, 5, 6` and the half-steps `1.5, 2.5, 3.5, 4.5, 5.5`. + */ + gap?: number; + /** Reverse the order of the children (default: `false`). */ + reversed?: boolean; + /** Specifies an additional `className` to add to the base element. */ + className?: string; +} + +/** + * Flexbox layout helper. A vertical or horizontal `Stack` that spaces its + * children using Paragon's spacer design tokens. + * + * This is a 1:1 port of `@openedx/paragon`'s `Stack`: the public API + * (`direction`, `gap`, `reversed`, `className`, DOM passthrough) is unchanged. + * The only internal difference is that the global `pgn__*stack` classes become + * locally-scoped CSS Module classes, and the gap is resolved to the matching + * `--pgn-spacing-spacer-*` token via the `--pgn-stack-gap` custom property + * rather than the SCSS `@each` loop. + */ +export const Stack = React.forwardRef(( + { + direction = 'vertical', + gap = 0, + reversed = false, + children, + className, + ...rest + }, + ref, +) => ( +
`gap-1-5`). All styling + // lives in the CSS Module; the component sets no inline styles. + styles[`gap-${String(gap).replace('.', '-')}`], + className, + )} + {...rest} + > + {children} +
+)); + +Stack.displayName = 'Stack'; + +export default Stack; diff --git a/prototype/src/Stack/index.ts b/prototype/src/Stack/index.ts new file mode 100644 index 00000000000..50ad3676f96 --- /dev/null +++ b/prototype/src/Stack/index.ts @@ -0,0 +1,2 @@ +export { default, Stack } from './Stack'; +export type { StackProps } from './Stack'; diff --git a/prototype/src/Tabs/Tab.tsx b/prototype/src/Tabs/Tab.tsx new file mode 100644 index 00000000000..ceb4074f725 --- /dev/null +++ b/prototype/src/Tabs/Tab.tsx @@ -0,0 +1,38 @@ +import React from 'react'; +import type { Key } from 'react-stately'; + +export interface TabProps { + /** + * A unique identifier for the `Tab`, distinguishing it from its siblings. + * Selecting a tab reports this value through `Tabs`' `activeKey` / `onSelect`. + */ + eventKey: Key; + /** Specifies the `Tab`'s navigation title. */ + title: React.ReactNode; + /** Specifies the panel content shown when this `Tab` is selected. */ + children?: React.ReactNode; + /** + * Specifies notification bubble content. It appears on the top-right of the + * `Tab`'s title. + */ + notification?: React.ReactNode; + /** Specifies whether the `Tab` is disabled. */ + disabled?: boolean; + /** Specifies an additional class name to append to the `Tab`'s nav link. */ + tabClassName?: string; +} + +/** + * Declarative configuration for a single tab. `Tab` is never rendered to the DOM + * itself — its parent `Tabs` reads these props to build the React Aria / + * react-stately tab collection (the tab button from `title`/`notification`, the + * panel from `children`). This mirrors `@openedx/paragon`'s `Tab`: the public + * props (`eventKey`, `title`, `notification`, `disabled`) are unchanged. + */ +function Tab(_props: TabProps): React.ReactElement | null { + // Rendering is handled by `Tabs`; a stray `` outside `` renders + // nothing rather than leaking an unstyled element into the page. + return null; +} + +export default Tab; diff --git a/prototype/src/Tabs/Tabs.mdx b/prototype/src/Tabs/Tabs.mdx new file mode 100644 index 00000000000..0ba2e88fed6 --- /dev/null +++ b/prototype/src/Tabs/Tabs.mdx @@ -0,0 +1,122 @@ +import { Meta, Title, Subtitle, Story, Controls } from '@storybook/addon-docs/blocks'; + +import * as TabsStories from './Tabs.stories'; +import { LiveExample } from '../docs/LiveExample'; + +export const examples = TabsStories.examples; + + + +Tabs + +Organize content into sections and switch between them — React Aria tab behavior, styled entirely from Paragon design tokens. + +`Tabs` is the prototype re-implementation of Paragon's `Tabs` on the modern stack +proposed in [ADR 0022](https://github.com/openedx/paragon). The declarative +`…` API — including `variant`, +`defaultActiveKey` / `activeKey`, `onSelect`, and per-tab `disabled` / +`notification` — is unchanged from `@openedx/paragon`, but the internals no longer +depend on Bootstrap or `react-bootstrap`: + +- **Behavior** comes from [React Aria](https://react-spectrum.adobe.com/react-aria/)'s + `useTabList` / `useTab` / `useTabPanel` plus react-stately's `useTabListState`: + correct `role="tablist"` / `tab` / `tabpanel` semantics, arrow-key navigation, + and `aria-selected` / `aria-controls` linkage — no more manual `MutationObserver` + syncing of `aria-selected`. +- **Styling** is the global, public `nav` / `nav-tabs` / `nav-pills` / + `nav-inverse-*` / `nav-button-group` class layer (`src/styles/tabs.css`) over + the same `--pgn-*` design tokens the library ships today, so a component and a + raw `
    ` render identically and theming (including + `@edx/brand`) is unaffected. +- **Focus** uses a keyboard-only focus ring (`:focus-visible` via React Aria's + `[data-focus-visible]`), matching `Button`. + +## Playground + +Edit the props with the controls and the JSX below regenerates; you can also type +directly in the editor to experiment. Changing a control overwrites the editor. + + + + + +{/* + The sections below mirror the existing Paragon docs (src/Tabs/README.md) 1:1 and + in the same order. The examples are authored as real TSX in Tabs.stories.tsx (so + TypeScript typechecks every prop) and their source is rendered here, editable, + via react-live. The `nav`/`nav-tabs`/… classes are part of Paragon's global + public class layer (src/styles/tabs.css); the README's + `` inverse wrappers become inline styles that + read the `--pgn-color-dark-700` token, since the prototype does not ship + Bootstrap's background/padding utilities. +*/} + +## Uncontrolled usage + + + +## Controlled usage + + + +## Button group usage + + + +## Pills usage + + + +## Inverse-Pills usage + + + +## Inverse Tabs usage + + + +## With notification + + + +### With screen reader text in notification + + + +## Conditional rendering + + + +{/* --- Additions beyond the original README --- */} + +## Accessibility notes + +- The tab list, tabs, and panel carry `role="tablist"` / `tab` / `tabpanel` with + `aria-selected` and `aria-controls` / `aria-labelledby` linkage, all wired by + React Aria — no `MutationObserver` shim. +- Keyboard: ← / → move between tabs (selection follows focus + by default); Home / End jump to the first / last tab. The + focus ring appears only for keyboard focus (`[data-focus-visible]`). +- Disabled tabs are skipped by keyboard navigation and cannot be selected. + +## Migration decisions surfaced here (for WG ratification) + +1. **Only the active panel is mounted.** React Aria renders the selected tab's + panel and unmounts the rest, rather than Bootstrap's "render every pane, hide + the inactive ones with `display: none`". This keeps the DOM minimal and the + `aria-labelledby` linkage correct. **Decision needed:** whether any consumers + rely on inactive panels staying mounted (e.g. to preserve uncontrolled form + state); if so, a `mountOnEnter` / `unmountOnExit`-style escape hatch can be + added. +2. **The responsive "More…" overflow dropdown is not ported.** In the current + library, tabs that don't fit collapse into a `More…` dropdown, implemented with + `Dropdown` + the `useIndexOfLastVisibleChild` hook. That depends on the + `Dropdown` module, which is out of scope for this step (the same reason + `dropdown-toggle-split` is deferred — see the prototype README). `moreTabText` + is retained on the props for API compatibility but is currently inert. It will + return with the Dropdown migration. +3. **`variant` maps to the same public `nav-*` classes.** `tabs` → `nav-tabs`, + `pills` → `nav-pills`, `inverse-tabs` → `nav-inverse-tabs`, `inverse-pills` → + `nav-inverse-pills`, `button-group` → `nav-button-group` — the same + Bootstrap-compatible class names Paragon ships today, so consumer overrides + keyed on those classes keep working. diff --git a/prototype/src/Tabs/Tabs.stories.tsx b/prototype/src/Tabs/Tabs.stories.tsx new file mode 100644 index 00000000000..0fdb1719cc2 --- /dev/null +++ b/prototype/src/Tabs/Tabs.stories.tsx @@ -0,0 +1,225 @@ +import React from 'react'; +import type { Meta, StoryObj } from '@storybook/react-vite'; + +import { Tabs } from './Tabs'; +import Tab from './Tab'; +import { LivePlayground, generateCode, playgroundChildren } from '../docs/LivePlayground'; +import { extractExamples } from '../docs/extractExamples'; +import raw from './Tabs.stories.tsx?raw'; + +const VARIANTS = ['tabs', 'pills', 'inverse-tabs', 'inverse-pills', 'button-group']; + +const meta: Meta = { + // Hidden `Internal/` root + `!dev` so the sidebar only shows the standalone + // "Navigation/Tabs" MDX docs page (same pattern as Button.stories.tsx). + title: 'Internal/Tabs', + component: Tabs, + tags: ['!dev'], + // PascalCase exports are stories; camelCase exports below are typechecked + // docs example source (see Button.stories.tsx for the full rationale). + includeStories: /^[A-Z]/, + parameters: { layout: 'padded' }, + args: { + variant: 'tabs', + defaultActiveKey: 'profile', + }, + argTypes: { + variant: { control: 'select', options: VARIANTS }, + defaultActiveKey: { control: 'inline-radio', options: ['home', 'profile', 'contact'] }, + // The tab set is fixed for the Playground; a ReactNode control makes no sense. + children: { table: { disable: true } }, + }, +}; + +export default meta; +type Story = StoryObj; + +export const Playground: Story = { + render: (args) => ( + Hello I am the first panel.', + 'Hello I am the second panel.', + 'Hello I am the third panel.', + ].join('\n')), + })} + /> + ), +}; + +/* + * --------------------------------------------------------------------------- + * Docs live examples. + * + * Authored as real TSX so TypeScript typechecks every prop against the Tabs / + * Tab types, then their verbatim source is extracted (see `extractExamples`) and + * fed to react-live so the docs stay editable. camelCase on purpose — + * `includeStories` above keeps Storybook from treating them as stories. Each is a + * single expression wrapped in `( … )`. + * + * These mirror src/Tabs/README.md 1:1 and in the same order. The nav / tab + * classes are part of Paragon's global public class layer (src/styles/tabs.css), + * so these snippets render the same as raw `
      ` markup. + * The README's `` inverse wrappers become + * inline styles reading the `--pgn-color-dark-700` token, since the prototype + * does not ship Bootstrap's background/padding utilities. + * --------------------------------------------------------------------------- + */ + +export const uncontrolled = ( + + + Hello I am the first panel. + + + Hello I am the second panel. + + + Hello I am the third panel. + + +); + +export const controlled = ( + () => { + const [key, setKey] = React.useState('home'); + + return ( + setKey(k as string)}> + + Hello I am the first panel. + + + Hello I am the second panel. + + + Hello I am the third panel. + + + ); + } +); + +export const buttonGroup = ( + + + Hello I am the first panel. + + + Hello I am the second panel. + + + Hello I am the third panel. + + +); + +export const pills = ( + + + Hello I am the first panel. + + + Hello I am the second panel. + + + Hello I am the third panel. + + +); + +export const inversePills = ( +
      + + + Hello I am the first panel. + + + Hello I am the second panel. + + + Hello I am the third panel. + + +
      +); + +export const inverseTabs = ( +
      + + + Hello I am the first panel. + + + Hello I am the second panel. + + + Hello I am the third panel. + + +
      +); + +export const withNotification = ( + + + Hello I am the first panel. + + + Hello I am the second panel. + + +); + +export const withScreenReaderNotification = ( + + + Hello I am the first panel. + + + 1 + notification + + )} + > + Hello I am the second panel. + + +); + +export const conditionalRendering = ( + () => { + const librariesEnabled = true; + const visibleTabs = [ + + Hello I am the courses panel. + , + + Hello I am the programs panel. + , + ]; + + if (librariesEnabled) { + visibleTabs.push( + + Hello I am the libraries panel. + , + ); + } + + return ( + + {visibleTabs} + + ); + } +); + +/** Editable source strings for react-live, extracted verbatim from this file. */ +export const examples = extractExamples(raw); diff --git a/prototype/src/Tabs/Tabs.test.tsx b/prototype/src/Tabs/Tabs.test.tsx new file mode 100644 index 00000000000..5b9d4ce34fc --- /dev/null +++ b/prototype/src/Tabs/Tabs.test.tsx @@ -0,0 +1,113 @@ +import { render, screen } from '@testing-library/react'; +import userEvent from '@testing-library/user-event'; +import { + describe, it, expect, vi, +} from 'vitest'; + +import { Tabs } from './Tabs'; +import Tab from './Tab'; + +function BasicTabs(props: Partial> = {}) { + return ( + + Home panel + Profile panel + Contact panel + + ); +} + +describe('Tabs', () => { + it('renders a tablist with a tab per Tab child', () => { + render(); + expect(screen.getByRole('tablist')).toBeInTheDocument(); + expect(screen.getAllByRole('tab')).toHaveLength(3); + expect(screen.getByRole('tab', { name: 'Home' })).toBeInTheDocument(); + }); + + it('shows only the active tab panel (defaultActiveKey)', () => { + render(); + expect(screen.getByRole('tab', { name: 'Home' })).toHaveAttribute('aria-selected', 'true'); + expect(screen.getByRole('tabpanel')).toHaveTextContent('Home panel'); + // React Aria mounts only the selected panel. + expect(screen.queryByText('Profile panel')).not.toBeInTheDocument(); + }); + + it('switches panels when another tab is clicked', async () => { + const user = userEvent.setup(); + render(); + + await user.click(screen.getByRole('tab', { name: 'Profile' })); + expect(screen.getByRole('tab', { name: 'Profile' })).toHaveAttribute('aria-selected', 'true'); + expect(screen.getByRole('tabpanel')).toHaveTextContent('Profile panel'); + expect(screen.queryByText('Home panel')).not.toBeInTheDocument(); + }); + + it('moves selection with the arrow keys', async () => { + const user = userEvent.setup(); + render(); + + await user.tab(); + expect(screen.getByRole('tab', { name: 'Home' })).toHaveFocus(); + + await user.keyboard('{ArrowRight}'); + expect(screen.getByRole('tab', { name: 'Profile' })).toHaveAttribute('aria-selected', 'true'); + }); + + it('marks a disabled tab and does not select it on click', async () => { + // Disabled tabs carry `pointer-events: none`; bypass user-event's guard so we + // can confirm React Aria itself also refuses to select the tab. + const user = userEvent.setup({ pointerEventsCheck: 0 }); + render(); + + const contact = screen.getByRole('tab', { name: 'Contact' }); + expect(contact).toHaveAttribute('aria-disabled', 'true'); + expect(contact).toHaveClass('disabled'); + + await user.click(contact); + expect(contact).toHaveAttribute('aria-selected', 'false'); + expect(screen.getByRole('tab', { name: 'Home' })).toHaveAttribute('aria-selected', 'true'); + }); + + it('supports controlled usage via activeKey and onSelect', async () => { + const onSelect = vi.fn(); + const user = userEvent.setup(); + render(); + + const profile = screen.getByRole('tab', { name: 'Profile' }); + await user.click(profile); + // Controlled: onSelect fires, but selection does not change until the parent + // updates activeKey. + expect(onSelect).toHaveBeenCalledWith('profile'); + expect(screen.getByRole('tab', { name: 'Home' })).toHaveAttribute('aria-selected', 'true'); + }); + + it('renders a notification bubble in the tab title', () => { + render( + + Home panel + Profile panel + , + ); + const badge = screen.getByText('3'); + expect(badge).toHaveClass('pgn__tab-notification'); + expect(screen.getByRole('tab', { name: /Profile/ })).toContainElement(badge); + }); + + it('applies the variant and forwarded className to the tab list', () => { + render(); + const tablist = screen.getByRole('tablist'); + expect(tablist).toHaveClass('nav', 'nav-pills', 'pgn__tabs', 'extra'); + }); + + it('appends a per-tab tabClassName to that tab only', () => { + render( + + Home panel + Profile panel + , + ); + expect(screen.getByRole('tab', { name: 'Home' })).toHaveClass('my-tab'); + expect(screen.getByRole('tab', { name: 'Profile' })).not.toHaveClass('my-tab'); + }); +}); diff --git a/prototype/src/Tabs/Tabs.tsx b/prototype/src/Tabs/Tabs.tsx new file mode 100644 index 00000000000..15aa43bd66b --- /dev/null +++ b/prototype/src/Tabs/Tabs.tsx @@ -0,0 +1,201 @@ +import React, { useMemo, useRef } from 'react'; +import { + useTab, useTabList, useTabPanel, useFocusRing, useObjectRef, mergeProps, +} from 'react-aria'; +import { useTabListState, Item, type Key } from 'react-stately'; +import type { Node, TabListState } from 'react-stately'; +import clsx from 'clsx'; + +import type { TabProps } from './Tab'; +import '../styles/tabs.css'; + +/** Default text for the (not-yet-ported) responsive "More..." overflow tab. */ +export const MORE_TAB_TEXT = 'More...'; + +/** Visual style of the `Tabs`' navigation. */ +export type TabsVariant = 'tabs' | 'pills' | 'inverse-tabs' | 'inverse-pills' | 'button-group'; + +export interface TabsProps { + /** The set of `` elements to render. */ + children: React.ReactNode; + /** Specifies the visual style to use (default: `tabs`). */ + variant?: TabsVariant; + /** Specifies the initially active tab's `eventKey` (uncontrolled usage). */ + defaultActiveKey?: Key; + /** Specifies the active tab's `eventKey` (controlled usage). */ + activeKey?: Key; + /** Callback fired with the newly selected tab's `eventKey`. */ + onSelect?: (eventKey: Key) => void; + /** + * Specifies text for the responsive "More..." overflow tab. Retained for API + * compatibility; the overflow dropdown is not part of this prototype — see the + * migration notes in the docs. + */ + moreTabText?: string; + /** Specifies an additional class name to append to the tab list. */ + className?: string; + /** Optional id applied to the wrapper element. */ + id?: string; +} + +/** Extra per-tab config carried alongside the react-stately collection node. */ +interface TabMeta { + tabClassName?: string; +} + +/** + * A single tab button. Behaviour (selection on press, roving `tabindex`, + * `aria-selected`/`aria-controls` linkage) comes from React Aria's `useTab`; the + * keyboard-only focus ring reuses the same `[data-focus-visible]` mechanism as + * `Button`. Styling is the global, public `nav-link` class layer. + */ +function TabItem({ item, state, meta }: { + item: Node; + state: TabListState; + meta: TabMeta | undefined; +}) { + const ref = useObjectRef(); + const { tabProps, isSelected, isDisabled } = useTab({ key: item.key }, state, ref); + const { isFocusVisible, focusProps } = useFocusRing(); + + return ( + + ); +} + +/** + * The panel for the currently-selected tab. React Aria mounts only the active + * panel (rather than Bootstrap's "render all, hide inactive"), keeping the DOM + * minimal and the `aria-labelledby`/`role="tabpanel"` linkage correct — see the + * migration notes in the docs. + */ +function TabPanel({ state, className }: { + state: TabListState; + className?: string; +}) { + const ref = useRef(null); + const { tabPanelProps } = useTabPanel({}, state, ref); + + return ( +
      +
      + {state.selectedItem?.props.children} +
      +
      + ); +} + +/** + * Tabs organize related content into sections and let the user switch between + * them. This is the prototype re-implementation of `@openedx/paragon`'s `Tabs`: + * the declarative `…` API — including + * `variant`, `defaultActiveKey`/`activeKey`, `onSelect`, per-tab `disabled` and + * `notification` — is unchanged, but the internals no longer depend on + * `react-bootstrap`: + * + * - **Behaviour** comes from React Aria's `useTabList`/`useTab`/`useTabPanel` + * plus react-stately's `useTabListState`: correct `role="tablist"`/`tab`/ + * `tabpanel` semantics, arrow-key navigation, and `aria-selected`/ + * `aria-controls` linkage. + * - **Styling** is the global, public `nav`/`nav-tabs`/`nav-pills`/… class layer + * (`src/styles/tabs.css`) over the same `--pgn-*` tokens, so a component and a + * raw `
        ` render identically and theming is unaffected. + */ +export function Tabs({ + children, + variant = 'tabs', + defaultActiveKey, + activeKey, + onSelect, + className, + id, + // `moreTabText` is accepted for API compatibility but currently inert. + moreTabText: _moreTabText = MORE_TAB_TEXT, +}: TabsProps) { + // Translate the declarative `` children into a react-stately collection: + // each becomes an `` whose `title` (plus optional notification badge) is + // the tab label and whose children are the panel content. `disabledKeys` and + // the per-tab `tabClassName` map are collected in the same pass. + const { items, disabledKeys, meta } = useMemo(() => { + const collectedDisabled: Key[] = []; + const collectedMeta = new Map(); + const collectedItems = React.Children.toArray(children) + .filter((child): child is React.ReactElement => React.isValidElement(child)) + .map((child, index) => { + const { + eventKey, title, notification, disabled, tabClassName, children: panel, + } = child.props; + const key: Key = eventKey ?? String(index); + if (disabled) { + collectedDisabled.push(key); + } + if (tabClassName) { + collectedMeta.set(key, { tabClassName }); + } + const label = notification + ? ( + <> + {title} + + {notification} + + + ) + : title; + return ( + + {panel} + + ); + }); + return { items: collectedItems, disabledKeys: collectedDisabled, meta: collectedMeta }; + }, [children]); + + const state = useTabListState({ + children: items, + selectedKey: activeKey, + defaultSelectedKey: defaultActiveKey, + disabledKeys, + onSelectionChange: onSelect, + }); + + const tabListRef = useRef(null); + const { tabListProps } = useTabList( + { selectedKey: activeKey, defaultSelectedKey: defaultActiveKey }, + state, + tabListRef, + ); + + return ( +
        +
        + {[...state.collection].map((item) => ( + + ))} +
        + +
        + ); +} + +Tabs.displayName = 'Tabs'; + +export default Tabs; diff --git a/prototype/src/Tabs/index.ts b/prototype/src/Tabs/index.ts new file mode 100644 index 00000000000..fff7e34a468 --- /dev/null +++ b/prototype/src/Tabs/index.ts @@ -0,0 +1,4 @@ +export { Tabs, default, MORE_TAB_TEXT } from './Tabs'; +export type { TabsProps, TabsVariant } from './Tabs'; +export { default as Tab } from './Tab'; +export type { TabProps } from './Tab'; diff --git a/prototype/src/base.css b/prototype/src/base.css new file mode 100644 index 00000000000..50558c2efde --- /dev/null +++ b/prototype/src/base.css @@ -0,0 +1,27 @@ +/* + * Foundational base layer — the modern replacement for Bootstrap's `reboot`. + * + * Paragon's button (and form) font tokens resolve to `inherit`, on the + * assumption that a base layer establishes the root typography that components + * inherit. Bootstrap's reboot used to do this; here we set it explicitly from + * the same `--pgn-*` design tokens. Without this, buttons fall back to the + * user-agent serif default. + * + * This is imported both by the library entry (so consumers get it) and by the + * Storybook preview (so docs/story frames render like a real consuming app). + */ +/* + * Apply the base typography to `body`, NOT `html` — exactly as Bootstrap's + * reboot does. `--pgn-typography-font-size-base` is `1.125rem`, so setting it on + * the root (`html`) would inflate the `rem` reference from 16px to 18px and make + * every `rem`-based component token compound (e.g. the button's own `1.125rem` + * font-size would render at 20.25px instead of 18px). Keeping `html` at the + * browser default preserves `rem` = 16px, so `1.125rem` resolves to 18px + * everywhere, matching the current library. + */ +:where(body) { + font-family: var(--pgn-typography-font-family-base); + font-size: var(--pgn-typography-font-size-base); + line-height: var(--pgn-typography-line-height-base); + color: var(--pgn-color-body-base); +} diff --git a/prototype/src/css-modules.d.ts b/prototype/src/css-modules.d.ts new file mode 100644 index 00000000000..058c26bfb53 --- /dev/null +++ b/prototype/src/css-modules.d.ts @@ -0,0 +1,8 @@ +declare module '*.module.css' { + const classes: { readonly [key: string]: string }; + export default classes; +} + +// Plain (non-module) CSS is imported for its side effects only. TypeScript 6 +// (TS2882) requires a declaration for side-effect imports that have no types. +declare module '*.css'; diff --git a/prototype/src/docs/LiveExample.tsx b/prototype/src/docs/LiveExample.tsx new file mode 100644 index 00000000000..9d9202c9b6f --- /dev/null +++ b/prototype/src/docs/LiveExample.tsx @@ -0,0 +1,36 @@ +import { + LiveProvider, LiveEditor, LivePreview, LiveError, +} from 'react-live'; + +import { scope } from './scope'; +import styles from './live.module.css'; + +export interface LiveExampleProps { + /** A single JSX expression. No `import` statements; identifiers must be in `scope`. */ + code: string; +} + +/** + * An editable, live-rendering code example for MDX docs pages. + * + * These examples are intentionally **untyped** — the code string is the single + * source of truth. Use this for illustrative snippets. For the controls-driven, + * args-bound example see `LivePlayground`. + */ +export function LiveExample({ code }: LiveExampleProps) { + return ( + // `sb-unstyled` opts the preview out of Storybook's docs typography reset + // (which otherwise forces "Nunito Sans" onto every div in the docs prose), + // so components render in the Paragon base font like a real consuming app. +
        + + +
        Editable — try changing the code
        + + +         +
        + ); +} + +export default LiveExample; diff --git a/prototype/src/docs/LivePlayground.tsx b/prototype/src/docs/LivePlayground.tsx new file mode 100644 index 00000000000..6ae4557be4c --- /dev/null +++ b/prototype/src/docs/LivePlayground.tsx @@ -0,0 +1,137 @@ +import { + LiveProvider, LiveEditor, LivePreview, LiveError, +} from 'react-live'; + +import { scope } from './scope'; +import styles from './live.module.css'; + +const RAW = Symbol('raw'); + +/** A prop value that `generateCode` should emit verbatim inside `{…}`. */ +export interface RawExpr { [RAW]: string; } + +/** + * Marks a string as a raw JSX expression so `generateCode` emits it as + * `name={expr}` rather than the quoted `name="expr"`. Use it for props whose + * value is JSX rather than a primitive, e.g. `iconWhenClosed={raw('')}` + * (the referenced identifier must be in `scope`). + */ +export function raw(expr: string): RawExpr { + return { [RAW]: expr }; +} + +function isRaw(value: unknown): value is RawExpr { + return typeof value === 'object' && value !== null && RAW in value; +} + +export interface GenerateCodeOptions { + /** + * Prop values equal to these are treated as the component's default and are + * dropped from the generated JSX (e.g. Button's `size="md"`, Stack's + * `direction="vertical"`), keeping the snippet minimal. + */ + defaults?: Record; + /** + * Literal JSX to place between the open and close tags. When it spans multiple + * lines the element is formatted as an indented block. If omitted, a string + * `children` prop is used as the text body (the Button case); with neither the + * element is self-closed. + */ + children?: string; +} + +/** + * Serializes a component name + its story args into an editable JSX string. + * + * This is deliberately component-agnostic: every prototype component's + * playground feeds its own args, defaults and children template through here, so + * there is no per-component code-generation logic hard-coded in the docs layer. + * + * Serialization rules (matching how the examples are hand-authored): + * - a prop whose value equals a supplied default is omitted; + * - `undefined` / `null` / `false` props are omitted; + * - `true` renders as a bare attribute (`disabled`); + * - strings render as `name="value"`, everything else as `name={value}`. + */ +export function generateCode( + component: string, + // `object`, not `Record`, so a component's concrete args type + // (which has no index signature) can be passed without a cast at the call site. + props: object, + options: GenerateCodeOptions = {}, +): string { + const { defaults = {}, children } = options; + const record = props as Record; + + const attrs: string[] = []; + for (const [name, value] of Object.entries(record)) { + if (name === 'children') continue; + if (name in defaults && defaults[name] === value) continue; + if (value === undefined || value === null || value === false) continue; + if (value === true) { + attrs.push(name); + } else if (isRaw(value)) { + attrs.push(`${name}={${value[RAW]}}`); + } else if (typeof value === 'string') { + attrs.push(`${name}="${value}"`); + } else { + attrs.push(`${name}={${JSON.stringify(value)}}`); + } + } + const attrStr = attrs.length ? ` ${attrs.join(' ')}` : ''; + + const body = children ?? (typeof record.children === 'string' ? record.children : ''); + if (!body) return `<${component}${attrStr} />`; + if (body.includes('\n')) { + const indented = body.split('\n').map((l) => (l ? ` ${l}` : l)).join('\n'); + return `<${component}${attrStr}>\n${indented}\n`; + } + return `<${component}${attrStr}>${body}`; +} + +/** + * Resolves a Playground's optional `children` text arg into the JSX-source string + * for `generateCode`'s `children` option: when the control has been set to a + * non-empty string it is used verbatim (so a consumer can type text or JSX); + * otherwise the component's default example template is kept. + */ +export function playgroundChildren(children: unknown, defaultTemplate: string): string { + return typeof children === 'string' && children.trim() ? children : defaultTemplate; +} + +export interface LivePlaygroundProps { + /** The generated JSX snippet — rendered live and shown in the editor. */ + code: string; +} + +/** + * The Playground example: a live editor whose JSX is generated (by + * `generateCode`) from a story's args. Because Storybook's `` block + * edits those same args, changing a control regenerates the code and — via the + * `key` below — remounts the editor, overwriting whatever was typed. Direct edits + * in the editor persist until the next control change. + * + * It is intentionally component-agnostic: it just renders whatever `code` string + * it is handed, so the same playground drives Button, ButtonGroup, Collapsible, + * Stack, and any future prototype component (everything the snippet references + * must be in `scope`). + */ +export function LivePlayground({ code }: LivePlaygroundProps) { + return ( + // `sb-unstyled`: opt out of Storybook's docs font reset (see LiveExample). +
        + {/* key={code}: a new generated string (from a changed control) forces a + remount so the editor content is replaced with the regenerated JSX. */} + + +
        + Generated from the controls below — editable, but re-editing a prop overwrites it +
        + + +         +
        + ); +} + +export default LivePlayground; diff --git a/prototype/src/docs/extractExamples.ts b/prototype/src/docs/extractExamples.ts new file mode 100644 index 00000000000..f0d4cf954d3 --- /dev/null +++ b/prototype/src/docs/extractExamples.ts @@ -0,0 +1,34 @@ +/** + * Extracts the verbatim source of each `export const NAME = ( … );` block from a + * module's raw text (imported via Vite's `?raw`). + * + * This is what lets the docs examples be both **typechecked** and **editable**: + * the examples are authored as real JSX in a co-located `*.examples.tsx` file + * (so `tsc` validates every prop against the component types), and their exact + * source is pulled back out here and handed to react-live's editor. + * + * Convention (matches Prettier's stable formatting): each example is a single + * JSX expression wrapped in `(` … `)`, with the opening `(` at end-of-line and + * the closing `);` in column 0. Any other export (e.g. the `examples` map + * itself) is a single line and is ignored. + */ +export function extractExamples(raw: string): Record { + const out: Record = {}; + const re = /^export const (\w+) = \(\n([\s\S]*?)\n\);$/gm; + let m: RegExpExecArray | null; + // eslint-disable-next-line no-cond-assign + while ((m = re.exec(raw)) !== null) { + out[m[1]] = dedent(m[2]); + } + return out; +} + +/** Removes the common leading indentation so the snippet reads flush-left. */ +function dedent(block: string): string { + const lines = block.split('\n'); + const indents = lines + .filter((l) => l.trim().length) + .map((l) => l.match(/^ */)![0].length); + const min = indents.length ? Math.min(...indents) : 0; + return lines.map((l) => l.slice(min)).join('\n'); +} diff --git a/prototype/src/docs/live.module.css b/prototype/src/docs/live.module.css new file mode 100644 index 00000000000..16dbf6d2ec4 --- /dev/null +++ b/prototype/src/docs/live.module.css @@ -0,0 +1,60 @@ +.live { + display: grid; + gap: 0; + border: 1px solid #d0d0d0; + border-radius: 6px; + overflow: hidden; + margin: 1rem 0; +} + +.preview { + padding: 1.5rem; + background-color: var(--pgn-color-light-200); + /* A plain block formatting context (not a flex row): each example lays out its + own children — usually via — so block-level/flex-container siblings + (e.g. multiple horizontal Stacks, or `block` buttons) stack vertically and + fill the width, matching how the current Paragon docs render them. */ + display: flow-root; + /* Anchor the Paragon base typography so previews render like a consuming app, + independent of Storybook's own docs font (which would otherwise be inherited + by inline examples). */ + font-family: var(--pgn-typography-font-family-base); + color: var(--pgn-color-body-base); +} + +.editor { + font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace; + font-size: 13px; + line-height: 1.5; + background: #1e1e2e; + color: #f8f8f2; + border-top: 1px solid #d0d0d0; +} + +/* react-live renders a