@tristan2828/ui-foundation 4.33.0 → 4.34.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { AppShell, type AppShellProps, type AppShellVersion, type NavEntry, type NavItem, type NavSection } from './components/app/app-shell.js';
+export { AppShell, type AppShellProps, type AppShellVersion, type BottomBarItem, type NavEntry, type NavItem, type NavSection, } from './components/app/app-shell.js';
 export type { IconComponent } from './components/app/icon-component.js';
 export { CountLink, type CountLinkProps } from './components/app/count-link.js';
 export { DataTable, type DataTableProps, type DataTableTotals, type DataTableWidth, type SortingState, } from './components/app/data-table.js';
@@ -13,7 +13,7 @@ export { ErrorState } from './components/app/error-state.js';
 export { InlineCreate, type InlineCreateProps } from './components/app/inline-create.js';
 export { FoundationProviders } from './components/app/foundation-providers.js';
 export { Markdown, type MarkdownProps } from './components/app/markdown.js';
-export type { HeadingLevel } from './components/app/prose-look.js';
+export type { HeadingFrom, HeadingLevel } from './components/app/prose-look.js';
 export { MockModeBanner } from './components/app/mock-mode-banner.js';
 export { MultiChoice } from './components/app/multi-choice.js';
 export { MultiPick, type MultiPickOption, type MultiPickProps } from './components/app/multi-pick.js';
@@ -30,6 +30,7 @@ export { StageCircle, type StageCircleProps, type StageCircleStage, type StageCi
 export { Notice, type NoticeProps, type NoticeTone } from './components/app/notice.js';
 export { SourceCredit, type Source, type SourceCreditProps } from './components/app/source-credit.js';
 export { ProgressRing, type ProgressRingProps } from './components/app/progress-ring.js';
+export { LineChart, type LineChartMark, type LineChartPoint, type LineChartProps, } from './components/app/line-chart.js';
 export { StepBar, type StepBarProps } from './components/app/step-bar.js';
 export { RatingStar, type RatingStarProps, type RatingStarValue } from './components/app/rating-star.js';
 export { DateField, type DateFieldProps } from './components/app/date-field.js';

package/dist/index.js

@@ -3,7 +3,7 @@
 // the gateway seam, MSW support and Playwright suites have their own entry
 // points (`/gateway`, `/mocks`, `/testing`) so each stays behind its boundary.
 // Composites
-export { AppShell } from './components/app/app-shell.js';
+export { AppShell, } from './components/app/app-shell.js';
 export { CountLink } from './components/app/count-link.js';
 export { DataTable, } from './components/app/data-table.js';
 export {} from './components/app/table-groups.js';
@@ -33,6 +33,7 @@ export { StageCircle, } from './components/app/stage-circle.js';
 export { Notice } from './components/app/notice.js';
 export { SourceCredit } from './components/app/source-credit.js';
 export { ProgressRing } from './components/app/progress-ring.js';
+export { LineChart, } from './components/app/line-chart.js';
 export { StepBar } from './components/app/step-bar.js';
 export { RatingStar } from './components/app/rating-star.js';
 export { DateField } from './components/app/date-field.js';

package/dist/lib/line-chart-layout.d.ts

@@ -0,0 +1,23 @@
+export type LineChartPoint = {
+    /** A day (`'YYYY-MM-DD'`), a timestamp or any number. Points sit apart by it; if one isn't a time or a number, they're evenly spaced. */
+    x: string | number;
+    y: number;
+};
+export type LineChartMark = 'min' | 'max' | 'last';
+export type ChartLayout = {
+    /** Each point's place, in the order given. */
+    places: {
+        x: number;
+        y: number;
+    }[];
+    /** The y range drawn, bottom to top: the values and the target, with room around them. */
+    domain: {
+        min: number;
+        max: number;
+    };
+    /** The target line's height, if there's a target. */
+    targetY?: number;
+    /** Which point the mark is on, if any. */
+    markIndex?: number;
+};
+export declare function chartLayout(points: readonly LineChartPoint[], target?: number, mark?: LineChartMark): ChartLayout;

package/dist/lib/line-chart-layout.js

@@ -0,0 +1,44 @@
+// Where LineChart's points, target and mark go (#238), React-free so the
+// rules are unit tested on their own (tests/line-chart-layout.test.ts).
+// Positions are fractions of the plot, 0…1, x from the left and y from
+// the top, so the chart fills whatever width it's given.
+// A point's position along x: a number as it is, a day or a timestamp as
+// its time.
+function along(x) {
+    return typeof x === 'number' ? x : Date.parse(x);
+}
+// Room above and below the values, as a share of their range, so the line
+// never runs along the plot's edge.
+const PAD = 0.1;
+export function chartLayout(points, target, mark) {
+    const values = points.map((point) => point.y);
+    const all = target === undefined ? values : [...values, target];
+    let min = Math.min(...all);
+    let max = Math.max(...all);
+    // One value (or all the same): a band around it, so the line sits mid-plot.
+    const spread = max - min || Math.abs(max) || 1;
+    min -= spread * PAD;
+    max += spread * PAD;
+    const height = (y) => (max - y) / (max - min);
+    const times = points.map((point) => along(point.x));
+    const timed = times.every(Number.isFinite) && times.length > 1 && times.at(-1) !== times[0];
+    const first = timed ? Math.min(...times) : 0;
+    const span = timed ? Math.max(...times) - first : points.length - 1;
+    const across = (index) => (span === 0 ? 0.5 : ((timed ? times[index] : index) - first) / span);
+    let markIndex;
+    if (points.length > 0 && mark) {
+        if (mark === 'last')
+            markIndex = points.length - 1;
+        else {
+            const pick = mark === 'min' ? Math.min(...values) : Math.max(...values);
+            // The latest of equal values: the one that's still true.
+            markIndex = values.lastIndexOf(pick);
+        }
+    }
+    return {
+        places: points.map((point, index) => ({ x: across(index), y: height(point.y) })),
+        domain: { min, max },
+        targetY: target === undefined ? undefined : height(target),
+        markIndex,
+    };
+}

package/dist/lib/markdown-top-heading.d.ts

@@ -0,0 +1,2 @@
+/** The lowest `depth` of any heading in the text, nested ones included; 1 when it has none. */
+export declare function textTopHeading(markdown: string): number;

package/dist/lib/markdown-top-heading.js

@@ -0,0 +1,21 @@
+// The text's own highest heading level (1 for `#`), for `headingFrom="text"`
+// on <Markdown> and the rich-text editor: notes pasted or imported from
+// another tool often start at `##`, and that level is the one that takes
+// the field's `headingLevel`. Parsed as both parse it (remark, GFM), so a
+// `#` in a code block or a setext heading counts as they render it.
+import remarkGfm from 'remark-gfm';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+const parser = unified().use(remarkParse).use(remarkGfm);
+/** The lowest `depth` of any heading in the text, nested ones included; 1 when it has none. */
+export function textTopHeading(markdown) {
+    let top = 7;
+    const visit = (node) => {
+        if (node.type === 'heading' && node.depth)
+            top = Math.min(top, node.depth);
+        for (const child of node.children ?? [])
+            visit(child);
+    };
+    visit(parser.parse(markdown));
+    return top === 7 ? 1 : top;
+}

package/dist/testing/index.d.ts

@@ -43,8 +43,11 @@ export type A11ySuiteOptions = {
      * sparse one, so both filled values and "not set" labels are checked.
      */
     viewRoutes?: readonly string[];
-    /** Screens outside the app shell, e.g. '/login' (and '/register' if the app has it). */
-    loggedOutRoutes: readonly string[];
+    /**
+     * Screens outside the app shell, e.g. '/login' (and '/register' if the
+     * app has it). An app with several a11y spec files lists them in one.
+     */
+    loggedOutRoutes?: readonly string[];
     /**
      * The app's nav, the same `NavEntry[]` passed to `AppShell` (`src/nav.ts`).
      * Given, each page in it is a test of its own, so the suite's time per
@@ -54,6 +57,13 @@ export type A11ySuiteOptions = {
      * their number.
      */
     nav?: readonly NavEntry[];
+    /**
+     * Whether to check that the rendered sidebar links exactly `nav`'s pages
+     * (default true). An app with one a11y spec per module passes each
+     * module's own entries as `nav` with `checkSidebar: false`, and keeps
+     * the check in one file that passes the whole nav.
+     */
+    checkSidebar?: boolean;
 };
 /**
  * Every data view on the page has loaded: at least one shows its data (or,
@@ -71,12 +81,14 @@ export declare function expectDataViewsLoaded(page: Page, { success }?: {
  * Accessibility of the real screens in light and dark mode: every page in
  * the Primary nav (one test each from `nav`, or discovered in the sidebar
  * when `nav` is left out), the given form routes, and the logged-out
- * screens. axe's
+ * screens. A modular app can split it into a spec per module: each passes
+ * its module's `nav` entries and routes with `checkSidebar: false`, and
+ * one file keeps the whole-sidebar check. axe's
  * color-contrast rule against the rendered dark DOM is also what keeps the
  * dark-mode tokens readable. The theme follows the OS setting, so
  * emulateMedia switches it.
  */
-export declare function defineA11ySuite({ formRoutes, viewRoutes, loggedOutRoutes, nav }: A11ySuiteOptions): void;
+export declare function defineA11ySuite({ formRoutes, viewRoutes, loggedOutRoutes, nav, checkSidebar, }: A11ySuiteOptions): void;
 export type MockModeBannerSuiteOptions = {
     /** Screens to check, logged-out ones included (e.g. '/login'). */
     routes: readonly string[];

package/dist/testing/index.js

@@ -140,16 +140,18 @@ async function expectNavPageAccessible(page, route, colorScheme) {
  * Accessibility of the real screens in light and dark mode: every page in
  * the Primary nav (one test each from `nav`, or discovered in the sidebar
  * when `nav` is left out), the given form routes, and the logged-out
- * screens. axe's
+ * screens. A modular app can split it into a spec per module: each passes
+ * its module's `nav` entries and routes with `checkSidebar: false`, and
+ * one file keeps the whole-sidebar check. axe's
  * color-contrast rule against the rendered dark DOM is also what keeps the
  * dark-mode tokens readable. The theme follows the OS setting, so
  * emulateMedia switches it.
  */
-export function defineA11ySuite({ formRoutes, viewRoutes = [], loggedOutRoutes, nav }) {
+export function defineA11ySuite({ formRoutes, viewRoutes = [], loggedOutRoutes = [], nav, checkSidebar = true, }) {
     // Each `to` as given, query string and all, so a page that opens on a
     // saved view is checked on it.
     const listed = nav && navTargets(nav);
-    if (listed) {
+    if (listed && checkSidebar) {
         test('the sidebar links exactly the pages in nav', async ({ page, isMobile }) => {
             const rendered = await navRoutes(page, isMobile);
             expect(pagePaths(rendered), 'The sidebar and the nav given to defineA11ySuite differ: pass the same NavEntry[] AppShell gets').toEqual(pagePaths(listed));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "4.33.0",
+  "version": "4.34.0",
   "description": "Shared UI foundation for contract-first, database-backed React apps: shadcn primitives, DataTable/EntityForm composites, auth, the gateway error seam, design tokens, lint rules and the AI playbook.",
   "license": "MIT",
   "repository": {
@@ -65,10 +65,11 @@
     "prepack": "npm run build",
     "gen:api": "openapi-typescript ./openapi/foundation.yaml -o ./src/api/schema.ts",
     "lint": "eslint .",
+    "docs:index": "node scripts/doc-index.mjs",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",
     "preview-storybook": "vite preview --outDir storybook-static --port 6006 --strictPort",
-    "verify:fast": "npm run gen:api && git diff --exit-code -- src/api/schema.ts && tsc -b && eslint . --max-warnings 0 && node bin/ui-foundation.mjs check-deps && npm run build && vitest run",
+    "verify:fast": "npm run gen:api && git diff --exit-code -- src/api/schema.ts && node scripts/doc-index.mjs --check && tsc -b && eslint . --max-warnings 0 && node bin/ui-foundation.mjs check-deps && npm run build && vitest run",
     "verify": "npm run verify:fast && playwright test -c playwright.storybook.config.ts"
   },
   "peerDependencies": {