diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f58390de9..65b16ca41 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -54,6 +54,8 @@ jobs: run: node scripts/check-docs.mjs - name: Boost guidelines, skills and llms.txt run: node scripts/boost.mjs --check + - name: No test files in the npm tarballs + run: node scripts/check-pack.mjs - name: Licences run: node scripts/check-licenses.mjs - name: Audit diff --git a/.github/workflows/e2e-smoke.yml b/.github/workflows/e2e-smoke.yml index 3bd75ea3d..7775e4fbc 100644 --- a/.github/workflows/e2e-smoke.yml +++ b/.github/workflows/e2e-smoke.yml @@ -31,7 +31,7 @@ jobs: - run: pnpm install --frozen-lockfile - run: pnpm exec playwright install --with-deps chromium - run: pnpm build:web - - run: pnpm e2e:chromium e2e/a11y.spec.ts e2e/thaana.spec.ts + - run: pnpm e2e:chromium e2e/a11y.spec.ts e2e/thaana.spec.ts e2e/browser.spec.ts - uses: actions/upload-artifact@v4 if: failure() with: diff --git a/.github/workflows/ssr.yml b/.github/workflows/ssr.yml index dde21728f..926b8e727 100644 --- a/.github/workflows/ssr.yml +++ b/.github/workflows/ssr.yml @@ -9,6 +9,8 @@ on: paths: - packages/onu/** - e2e/nextjs/** + - e2e/optional-peers/** + - scripts/check-optional-peers.mjs - pnpm-lock.yaml - pnpm-workspace.yaml - .github/workflows/ssr.yml @@ -16,6 +18,8 @@ on: paths: - packages/onu/** - e2e/nextjs/** + - e2e/optional-peers/** + - scripts/check-optional-peers.mjs - pnpm-lock.yaml - pnpm-workspace.yaml - .github/workflows/ssr.yml @@ -50,3 +54,5 @@ jobs: run: pnpm --filter onu-nextjs-fixture build - name: Check the server HTML and hydration run: pnpm --filter onu-nextjs-fixture test:ssr + - name: Build an app without the optional peers (webpack and Turbopack) + run: node scripts/check-optional-peers.mjs diff --git a/AGENTS.md b/AGENTS.md index da0f57b1b..259d7ffbd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,6 +29,8 @@ pnpm --filter @javaabu/onu-mcp test # MCP server tests pnpm build && pnpm --filter @javaabu/onu size # build + bundle budgets pnpm build:web # docs site node scripts/check-docs.mjs # every component has a docs page with Props + Accessibility +node scripts/check-pack.mjs # no test files in the npm tarballs +node scripts/check-optional-peers.mjs # an app without the optional peers still builds (after pnpm build) pnpm e2e:chromium # Playwright (a11y with axe, visual) ``` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cc24c14c5..18291093e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -40,6 +40,7 @@ A component is done only when it meets REQUIREMENTS §21: light/dark, LTR/RTL, ` - Use `` (from `src/icons/icon`) with semantic names, so `OnuProvider icons` overrides apply. Never render a Lucide component directly. When a component always shows the same glyph (a spinner, a close button, a chevron), also pass that Lucide icon as `fallback`, e.g. ``: overrides still win, and the component keeps its glyph outside `OnuProvider`. - Never import `src/icons/lucide-map` in a component. `OnuProvider` loads the default set on demand, so neither a single component nor the provider ships ~250 icons. ESLint and `src/icons/icon-imports.test.ts` enforce this, and `pnpm --filter @javaabu/onu size` checks the bundle budgets. - Built-in strings: a module that uses `t("form.…")` registers the English namespaces it uses at the top level, e.g. `registerEnglish({ form: en_form })` with `import { form as en_form } from "../../locales/en/form"`. Never import the whole locale (`src/locales`, `locales/en/messages`) in a component, so a bundle carries only the English text of the components it uses. `src/i18n/english-registry.test.ts` checks this. +- Start a module with `"use client"` when it uses state, effects or context (its own hooks or Onu's, such as `useTranslation`). The build keeps the directive only on those modules, so pure helpers (`cn`, `themeScript`, `/thaana` conversion, `/export`) stay callable from React Server Components. `src/use-client.test.ts` checks this. - Every `package.json` export has a `size-limit` budget (`pnpm --filter @javaabu/onu size`, run in CI). When a change grows an entry on purpose, raise its budget in the same PR and say why; keep budgets a little above the measured size. - Prefer shadcn/ui or an approved library (REQUIREMENTS §4) before building from scratch. Record new dependencies in `DEPENDENCIES.md`. - Add a changeset: `pnpm changeset`. @@ -57,10 +58,12 @@ The files in `packages/onu/src/ui` started as shadcn/ui's components (Radix base E2E (Playwright) runs in two tiers: -- **Smoke, on pull requests.** The **E2E smoke** workflow runs `e2e/a11y.spec.ts` and `e2e/thaana.spec.ts` in Chromium, with no screenshots, when a pull request touches `packages/onu/**`, `web/**` or `e2e/**`. +- **Smoke, on pull requests.** The **E2E smoke** workflow runs `e2e/a11y.spec.ts`, `e2e/thaana.spec.ts` and `e2e/browser.spec.ts` in Chromium, with no screenshots, when a pull request touches `packages/onu/**`, `web/**` or `e2e/**`. - **Full, on demand.** The **E2E** workflow (accessibility in five browsers, and Chromium screenshots) is slow, so CI runs it only when the last commit pushed to `main` starts with `e2e` (for example `e2e: new date picker`), or when you run it by hand from the Actions tab. -Run either locally with `pnpm e2e:chromium`, adding the two spec files for the smoke tier. +Run either locally with `pnpm e2e:chromium`, adding the three spec files for the smoke tier. + +`e2e/browser.spec.ts` covers behaviour jsdom can't show (focus after re-renders, inert modal backgrounds, `IntersectionObserver`, downloads, chart layout). Each scenario is a small page in `web/src/e2e/.harness.tsx`, served at `#/e2e/` and left out of the navigation and the a11y and visual runs. Server rendering has its own check. The **Server rendering** workflow builds the Next.js app in `e2e/nextjs` against the workspace copy of Onu, then checks its server HTML and hydration in English and Dhivehi, when a pull request touches `packages/onu/**` or `e2e/nextjs/**`. Run it locally with `pnpm build && pnpm --filter onu-nextjs-fixture build && pnpm --filter onu-nextjs-fixture test:ssr`. diff --git a/docs/charts/category-chart.md b/docs/charts/category-chart.md index 5cce7e6d8..3275baa63 100644 --- a/docs/charts/category-chart.md +++ b/docs/charts/category-chart.md @@ -217,7 +217,7 @@ Reduced motion still wins inside ``. `useChartAn ## Primitives -The shadcn primitives are exported from the same entry for custom charts: `ChartContainer`, `ChartTooltip`, `ChartTooltipContent` (with an Onu `valueFormatter` prop), `ChartLegend`, `ChartLegendContent`, `ChartStyle` and the `ChartConfig` type. They are not exported from the package root, so `recharts` stays optional. +The shadcn primitives are exported from the same entry for custom charts: `ChartContainer`, `ChartTooltip`, `ChartTooltipContent` (with an Onu `valueFormatter` prop; without it, numbers use Onu's number locale), `ChartLegend`, `ChartLegendContent`, `ChartStyle` and the `ChartConfig` type. They are not exported from the package root, so `recharts` stays optional. ## RTL diff --git a/docs/charts/map-chart.md b/docs/charts/map-chart.md index d8595353a..ffadc1646 100644 --- a/docs/charts/map-chart.md +++ b/docs/charts/map-chart.md @@ -6,7 +6,7 @@ sidebar_position: 9 A choropleth map: regions shaded by value on Google Maps, drawn with a deck.gl `GeoJsonLayer` (`GoogleMapsOverlay`). It has a stepped legend, a tap/hover read-out and a data table. Without a Google Maps API key it shows an accessible notice and the table instead. :::info -Needs the optional peers `@vis.gl/react-google-maps`, `@deck.gl/core`, `@deck.gl/layers` and `@deck.gl/google-maps`. The map code is loaded lazily, only when an API key is configured. +Needs the optional peers `@vis.gl/react-google-maps`, `@deck.gl/core`, `@deck.gl/layers` and `@deck.gl/google-maps`. The map code is loaded lazily, only when an API key is configured. If those peers are not installed, the app still builds (with webpack or Turbopack) and the chart shows a note and the data table instead of the map. ::: ```tsx diff --git a/docs/charts/time-series-chart.md b/docs/charts/time-series-chart.md index 441a845a0..1a8822cef 100644 --- a/docs/charts/time-series-chart.md +++ b/docs/charts/time-series-chart.md @@ -31,6 +31,8 @@ Rows may come in any order; they are sorted oldest first. Dates can be `Date` ob `null` values break the line. With `interval` (`"hour" | "day" | "week" | "month"`), missing steps are inserted too (3 September above), so a missing day is a visible gap rather than a straight line across it. `connectNulls` bridges gaps instead. +`interval` also groups the data: each point sits at the start of its hour, day, week (counted from the first date) or month, and rows that fall in the same step are added up, so no row is dropped. Set `aggregate="mean"` to average them instead (for rates or temperatures). A range longer than 10,000 steps is drawn without the gap rows rather than cut short. + ## Stacked areas and bars `stacked` adds the series up, so the top edge is the total: use `variant="area"` for stacked areas or `variant="bar"` for stacked bars (a stacked `"line"` chart is drawn as stacked areas). Bars are centred on their date, and the axis is padded by half a step so the first and last bars are whole. The data table and summary still list each series on its own, and the time axis is mirrored in RTL as usual. @@ -93,7 +95,8 @@ Also takes the common chart props (`title` (required), `description`, `hideTitle | ------------------- | -------------------------------------- | ----------- | --------------------------------------- | | `data` | `Record[]` | required | One object per point in time | | `dateKey` | `string` | `"date"` | Key of the date | -| `interval` | `"hour" \| "day" \| "week" \| "month"` | | Fill missing steps with gaps | +| `interval` | `"hour" \| "day" \| "week" \| "month"` | | Group by step and fill missing steps with gaps | +| `aggregate` | `"sum" \| "mean"` | `"sum"` | With `interval`, how rows in one step combine | | `dateFormat` | `string` (date-fns) | by interval | Tick format (`d MMM`, `MMM yyyy`, time) | | `tooltipDateFormat` | `string` (date-fns) | by interval | Tooltip and table format | | `variant` | `"line" \| "area" \| "bar"` | `"line"` | How series are drawn | @@ -104,7 +107,7 @@ Also takes the common chart props (`title` (required), `description`, `hideTitle | `gradient` | `boolean` | `true` | Gradient area and bar fills | | `comparison` | `ChartComparison` | | This period against the previous one; see [Comparison](#comparison) | -Hourly data uses the locale's `hourCycle`. `normalizeTimeSeries(data, dateKey, interval)` and `toTimestamp(value)` are exported. +Hourly data uses the locale's `hourCycle`. `normalizeTimeSeries(data, dateKey, interval, aggregate)` and `toTimestamp(value)` are exported. ## RTL diff --git a/docs/date-and-time/date-calendar.md b/docs/date-and-time/date-calendar.md index 883f9915d..8536164bd 100644 --- a/docs/date-and-time/date-calendar.md +++ b/docs/date-and-time/date-calendar.md @@ -62,9 +62,11 @@ import { DateCalendar } from "@javaabu/onu" `DEFAULT_WEEKEND_DAYS` (`[5, 6]`, Friday and Saturday) is exported. +Without `today`, "today" is the browser's date. When server-rendered, no day is marked as today until hydration (a server in another time zone can be on a different day); pass `today` to have it in the server's HTML. + ## Accessibility -See the [DatePicker keyboard table](./date-picker#accessibility). The caption is a button ("March 2026: choose a month"); page changes are announced through a polite live region; the current month/year/range has `aria-current="date"`. +See the [DatePicker keyboard table](./date-picker#accessibility); in every view, Page Up/Down and arrows past the edge stop at `min` and `max` like the Previous and Next buttons. The caption is a button ("March 2026: choose a month"); page changes are announced through a polite live region; the current month/year/range has `aria-current="date"`. - With `events`, each day's accessible name includes its event count, so the dots (hidden from screen readers) aren't the only signal. - With `readOnly`, the clicked day's event list is a polite live region, so it is read out when it changes. Enter or Space on a day lists its events. diff --git a/docs/date-and-time/full-calendar.md b/docs/date-and-time/full-calendar.md index acb3fed3d..2fdf1351b 100644 --- a/docs/date-and-time/full-calendar.md +++ b/docs/date-and-time/full-calendar.md @@ -30,7 +30,7 @@ const events: CalendarEvent[] = [ ``` - `color` takes a theme colour (`primary`, `success`, `warning`, `destructive`, `info`, `secondary`, `chart-1`…`chart-8`), so events follow dark mode and `--onu-primary`. Any other FullCalendar event field (`backgroundColor`, `extendedProps`, `url`, …) passes through. -- The toolbar (‹ Today › · title · view switch) wraps on narrow containers; on phones the calendar opens on the agenda. No view scrolls the page sideways at 375px, in LTR or RTL: the agenda's screen-reader header is hidden in place (FullCalendar's `left: -10000px` would otherwise add 10,000px of overflow in RTL) and month events clip inside their day cell. +- The toolbar (‹ Today › · title · view switch) wraps on narrow containers; on phones the calendar opens on the agenda (also when server-rendered: it switches once hydrated), until a view is picked. No view scrolls the page sideways at 375px, in LTR or RTL: the agenda's screen-reader header is hidden in place (FullCalendar's `left: -10000px` would otherwise add 10,000px of overflow in RTL) and month events clip inside their day cell. - Weekend days (Friday and Saturday by default) are shaded; today is marked. - `apiRef` gives FullCalendar's `CalendarApi`; `options` passes any other FullCalendar option (Onu's props win); `hideToolbar` lets you build your own. diff --git a/docs/date-and-time/hijri-date-picker.md b/docs/date-and-time/hijri-date-picker.md index ffe4e5459..d04416ebe 100644 --- a/docs/date-and-time/hijri-date-picker.md +++ b/docs/date-and-time/hijri-date-picker.md @@ -36,6 +36,8 @@ Plus the shared picker field props. `selected`, `onSelect`, `min`, `max`, `weekStartsOn`, `weekendDays`, `showGregorian` (default `true`), `today`, `initialFocus`, `className`, `ref`. +As with `DateCalendar`, without `today` the browser's date is marked once hydrated, not the server's. + ## Accessibility The days view is an in-house APG grid (react-day-picker has no Hijri support). Day buttons are named with both calendars ("Today, 23 Ramadan 1447 AH, Thursday, March 12th, 2026"); today has `aria-current="date"`; days outside `min`/`max` are `aria-disabled`. diff --git a/docs/display-and-feedback/comment-thread.md b/docs/display-and-feedback/comment-thread.md index df8931be2..3da871168 100644 --- a/docs/display-and-feedback/comment-thread.md +++ b/docs/display-and-feedback/comment-thread.md @@ -37,6 +37,8 @@ import { CommentThread } from "@javaabu/onu" As in the thread, only the author may delete a note; pass `canDelete={() => true}` to let anyone delete. +If `onAdd` or `onEdit` returns a promise that rejects, the composer keeps the text and shows "Couldn’t save. Try again." as an alert. + ## Props | Prop | Type | Default | Description | diff --git a/docs/display-and-feedback/share-buttons.md b/docs/display-and-feedback/share-buttons.md index 4992ecc4f..5a2508d7f 100644 --- a/docs/display-and-feedback/share-buttons.md +++ b/docs/display-and-feedback/share-buttons.md @@ -30,6 +30,8 @@ import { ShareButtons } from "@javaabu/onu" `shareUrl(network, url, title?, text?)` builds the share links. +When server-rendered without `url`, the links start without a URL (the server doesn't know the page's address) and get the current page's URL straight after hydration. Pass `url` to have it in the server's HTML too. + :::info Brand icons Onu's icon sets (Lucide, FontAwesome Free solid) don't include brand logos, so networks use generic icons with their names as text. Pass `icons` (e.g. from Simple Icons via the Iconify adapter) for logos. ::: diff --git a/docs/files-and-media/additional-files-upload.md b/docs/files-and-media/additional-files-upload.md index cd2c13c44..6b73f5bf6 100644 --- a/docs/files-and-media/additional-files-upload.md +++ b/docs/files-and-media/additional-files-upload.md @@ -49,7 +49,7 @@ Set `name` to also render native fields: `name[removed][]` (hidden ids), `name[a - Each file's buttons are named with the file ("Remove Lease agreement.pdf", "Restore …"). - Marking a file for removal shows "Will be removed" as text (not only a strike-through), announces it, and moves focus to the Restore button. -- Removing a new file returns focus to the "Add files" picker. +- Removing a new file returns focus to the "Add files" picker, also when the picker was disabled at `maxFiles`. | Key | Action | | -------------------------------------------- | ------------------------------------------------------ | diff --git a/docs/files-and-media/avatar-upload.md b/docs/files-and-media/avatar-upload.md index 04b18ddd0..375f60b86 100644 --- a/docs/files-and-media/avatar-upload.md +++ b/docs/files-and-media/avatar-upload.md @@ -19,7 +19,7 @@ import { AvatarUpload } from "@javaabu/onu/media" ``` -The cropped image is a square JPEG, 512px by default (`cropOptions`), returned as a `File` through `onValueChange` and kept on the hidden file input for plain form submits. If cropping fails (for example a cross-origin image), the original file is used. +The cropped image is a square JPEG, 512px by default (`cropOptions`), with transparent areas filled white; pass `cropOptions={{ type: "image/png" }}` to keep transparency. The file is named after the picked one with the output type's extension (`me.png` → `me.jpg`). It is returned as a `File` through `onValueChange` and kept on the hidden file input for plain form submits. If cropping fails (for example a cross-origin image), the original file is used. ## Props diff --git a/docs/files-and-media/image-cropper.md b/docs/files-and-media/image-cropper.md index b24482732..d0bd26e3c 100644 --- a/docs/files-and-media/image-cropper.md +++ b/docs/files-and-media/image-cropper.md @@ -38,7 +38,7 @@ The canvas helpers are exported for use without the component: `cropImage(src, p | --------------------- | -------------------------------------- | ---------- | -------------------------------------------------------------------- | | `src` | `string \| Blob` | | Image URL or picked file | | `alt` | `string` | (required) | Names the crop area | -| `aspect` | `number` | `1` | Initial aspect ratio | +| `aspect` | `number` | `1` | Aspect ratio; a new value replaces the one in use | | `aspectOptions` | `{ label, value }[]` | | Aspect presets (`undefined` = free, image ratio) | | `onAspectChange` | `(aspect) => void` | | A preset was chosen | | `cropShape` | `"rect" \| "round"` | `"rect"` | Crop shape | diff --git a/docs/files-and-media/qr-code.md b/docs/files-and-media/qr-code.md index 05246e178..e8d24a821 100644 --- a/docs/files-and-media/qr-code.md +++ b/docs/files-and-media/qr-code.md @@ -39,11 +39,11 @@ The code never mirrors and is rendered with tokens through the `tone` variant (` | `theme` | Follows the theme: light modules on a dark ground in dark mode. Most phone cameras scan this, some older readers do not | | `transparent` | No background; modules use the current text colour. Keep enough contrast with what is behind | -Recolour with `classNames.svg`, e.g. `classNames={{ svg: "text-primary" }}`. Downloads use the colours as rendered (read with `getComputedStyle`). +Recolour with `classNames.svg`, e.g. `classNames={{ svg: "text-primary" }}`. Downloads use the colours as rendered (read with `getComputedStyle`). Without a background of its own (`tone="transparent"`) the file gets a white one, and light modules (such as the text colour in dark mode) are saved black so the file still scans. ## Logo -`logo` takes a URL or `{ src, size?, excavate? }`. `size` is the logo width as a fraction of the code (0.1–0.3, default 0.22). The modules behind it are cleared unless `excavate={false}`. A logo always uses error-correction level H, so the code still scans with the centre covered. For the PNG download the image must allow CORS; otherwise the PNG has the cleared area without the logo. +`logo` takes a URL or `{ src, size?, excavate? }`. `size` is the logo width as a fraction of the code (0.1–0.3, default 0.22). The modules behind it are cleared unless `excavate={false}`. A logo always uses error-correction level H, so the code still scans with the centre covered. For downloads the image must allow CORS: the SVG download embeds it as a data URL so the saved file stands alone, and the PNG draws it. When it cannot be fetched, the file has the cleared area without the logo. ## Props @@ -74,7 +74,7 @@ Also exported for custom rendering: `encodeQrCode(value, level)`, `qrCodePath(mo - The code is an `img` named by `label` (default "QR code"); give it a label that says what it is for, e.g. "QR code to verify licence BL-2026-04417". - Put the information in text as well (`showValue`, `caption` or nearby text) for people who cannot scan. -- Download and copy buttons have visible, translated labels and are 44px tall on touch screens. Copying is announced in a polite live region. +- Download and copy buttons have visible, translated labels and are 44px tall on touch screens. Copying is announced in a polite live region. A failed download shows "Could not download the QR code" as an alert under the buttons. - Text that is too long is reported with `role="alert"`. | Key | Action | diff --git a/docs/form-scaffolding/inline-edit.md b/docs/form-scaffolding/inline-edit.md index 91466bbcb..cfe434b65 100644 --- a/docs/form-scaffolding/inline-edit.md +++ b/docs/form-scaffolding/inline-edit.md @@ -50,7 +50,7 @@ If the thrown error has a `message`, it is shown; otherwise "Couldn’t save. Pl - The value is a button named "Edit Name: Aishath Shifa". - In edit mode the input is labelled by `label` and described by the key hint; errors are announced (`role="alert"`) and linked with `aria-describedby`. -- After saving or cancelling, focus returns to the value; "Name saved" is announced. +- After saving or cancelling with the keyboard or the buttons, focus returns to the value; "Name saved" is announced. When focus leaves the editor (`blurBehavior`), it stays where the user moved it, and a failing `validate` keeps the editor open with its error without pulling focus back. - While saving, the input is read-only and `aria-busy`. | Key | Action | diff --git a/docs/guides/ai-assistants.md b/docs/guides/ai-assistants.md index 1fd6c10b8..ed4a5f75b 100644 --- a/docs/guides/ai-assistants.md +++ b/docs/guides/ai-assistants.md @@ -59,7 +59,7 @@ Other clients (Cursor's `.cursor/mcp.json`, VS Code's `.vscode/mcp.json`, Claude } ``` -Set `ONU_DOCS_DIR` to read the docs from another folder. +Set `ONU_DOCS_DIR` to read the docs from another folder. If they don't load, the server warns on stderr and uses the docs it was published with. # Laravel Boost diff --git a/docs/guides/dark-mode.md b/docs/guides/dark-mode.md index 783e476b8..40aa662ce 100644 --- a/docs/guides/dark-mode.md +++ b/docs/guides/dark-mode.md @@ -26,7 +26,9 @@ function MyToggle() { | `forcedTheme` | | Fix the theme, e.g. `"light"` for print pages | | `storageKey` | `"onu-theme"` | `localStorage` key | -The provider sets `class="dark"`, `data-theme` and `color-scheme` on ``, so dialogs and menus in portals follow it. +The provider sets `class="dark"`, `data-theme` and `color-scheme` on ``, so dialogs and menus in portals follow it. A choice made in another tab applies here too. + +When server-rendered, the provider hydrates with `defaultTheme` (the server can't read `localStorage`) and switches to the stored theme straight after hydration, so the markup matches and controls such as `ThemeToggle` show the stored choice. In server-rendered apps, add `themeScript()` to `` to apply the stored theme before the page paints: @@ -34,4 +36,10 @@ In server-rendered apps, add `themeScript()` to `` to apply the stored the