npm - @bluestep-systems/bspecs - Versions diffs - 0.10.0 - Mend

@bluestep-systems/bspecs 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (83) hide show

package/templates/claude/instructions/reference/code-patterns.md.template ADDED Viewed

@@ -0,0 +1,265 @@
+# Code Patterns
+Common code patterns and examples for BlueStep.js development.
+## Contents
+- [Query Patterns](#query-patterns)
+- [Merge Report Patterns](#merge-report-patterns)
+- [Endpoint Patterns](#endpoint-patterns)
+- [Error Handling Patterns](#error-handling-patterns)
+- [Performance Patterns](#performance-patterns)
+- [Component Import Pattern](#component-import-pattern)
+- [Debugging Patterns](#debugging-patterns)
+## Query Patterns
+```typescript
+// Simple query
+B.queries.byFID['staffQuery'].query().forEach((record: Bluestep.Relate.Record) => {
+  console.log(record.forms.nameForm.fields.firstName.opt().orElse(''));
+});
+// Query with filtering (Java collections have no .filter()/.map())
+const results = [];
+B.queries.byFID['staffQuery'].query().forEach((record: Bluestep.Relate.Record) => {
+  const email = record.forms.contact.fields.email.opt().orElse('');
+  if (email.endsWith('@company.com')) results.push(record);
+});
+```
+The examples above run an ad-hoc query (read-only). For configured queries exposed as directly-iterable top-level variables (via the platform form-import config) and writable-context rules, see [api-patterns](api-patterns.md#query-access-patterns).
+## Merge Report Patterns
+Server code (`scripts/app.ts`) can access `B`; client code (`static/script.js`) runs in the browser and cannot. Bridge the two with `window` variables.
+### Server-side setup
+```typescript
+// scripts/app.ts - renders the page container
+const dashboardId = 'dashboard_123';
+const isSuper = B.optUser.map(u => u.isGlobalSuper()).orElse(false);
+const vars = `
+  <script>
+    window.dashboardId = '${dashboardId}';
+    window.isSuper = ${isSuper};
+    window.endpointUrl = '/b/apiEndpoint';
+  </script>
+`;
+B.net.pageContent('vars').HEADER_SCRIPTS_BOTTOM().addContent(vars).insert();
+B.out = '<div id="app-container">Loading...</div>';
+```
+### `B.net.pageContent()` placements
+`B.net.pageContent(lookup)` injects content into a specific location of the page. Chain one placement method, then `.addContent(html)`, then `.insert()`.
+- `.HEADER_SCRIPTS_BOTTOM()` — bottom of the scripts section in `<head>` (most common for variables)
+- `.HEADER_SCRIPTS_TOP()` — top of the scripts section in `<head>`
+- `.HEADER_CSS_BOTTOM()` / `.HEADER_CSS_TOP()` — CSS section in `<head>`
+- `.HEADER_TOP()` / `.HEADER_BOTTOM()` — top/bottom of `<head>`
+- `.PAGE_END()` — near the bottom of the page (default)
+### Passing per-row data (queue / lazy-init pattern)
+When a merge-report column renders per-row data, use a queue + lazy-init pattern rather than a `window` global. This avoids a timing race where `DOMContentLoaded` fires before the inline `<script>` from `B.out` has executed.
+```typescript
+// scripts/app.ts - push the value and trigger init if ready
+const clientId = name.fields.sysId.val();
+B.out = `<script>
+  (window._myPending = window._myPending || []).push("${clientId}");
+  if (window._myInit) window._myInit();
+</script>`;
+// static/script.ts - define _myInit and self-call at load time (no DOMContentLoaded)
+function initWidget(clientId: string): void {
+  const root = document.getElementById('my-root') as HTMLElement | null;
+  if (!root) return;
+  // ... render using clientId
+}
+(window as any)._myInit = function(): void {
+  const pending: string[] = (window as any)._myPending || [];
+  (window as any)._myPending = [];
+  while (pending.length) initWidget(pending.shift()!);
+};
+(window as any)._myInit(); // drain anything queued before this script loaded
+```
+Use a **unique namespace per report** (e.g. `_dpnBreakdownPending`) so multiple reports on the same page don't collide.
+### Client-side initialization
+```typescript
+// static/script.js - main application logic
+(async function() {
+  const dashboardId = window.dashboardId;
+  const endpointUrl = window.endpointUrl;
+  try {
+    const response = await fetch(endpointUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ action: 'loadDashboard', dashboardId })
+    });
+    const data = await response.json();
+    if (data.success) initializeApp(data.config);
+    else console.error('Failed to load:', data.error);
+  } catch (error) {
+    console.error('Error initializing:', error);
+  }
+})();
+```
+## Endpoint Patterns
+Endpoints receive the HTTP request via `B.net.request` and respond via `B.net.response`.
+### Request handling
+```typescript
+const { request } = B.net;
+const id = request.optParameter('id').orElse('');   // Java Optional
+const name = request.parameter('name');              // string or null
+const bodyStr = request.content();                   // request body as string (JSON POST)
+const body = JSON.parse(bodyStr);
+const method = request.method();                     // "GET", "POST", ...
+const contentType = request.optHeader('Content-Type').orElse('');
+const path = request.path();                         // e.g. "/b/myEndpoint"
+const query = request.queryString();                 // e.g. "id=123&page=2"
+const fullUrl = request.fullUrl();
+```
+### Response handling
+```typescript
+const { response } = B.net;
+response.out(JSON.stringify({ success: true, data: results })); // most common
+response.contentType('application/json');
+response.status(200);
+response.header('Cache-Control', 'no-cache');
+response.sendRedirect('/b/otherEndpoint');
+```
+### Action-based router
+```typescript
+// scripts/app.ts
+try {
+  const { request, response } = B.net;
+  const action = request.optParameter('action').orElse('');
+  let body: any = {};
+  try { body = JSON.parse(request.content()); } catch (e) { /* not JSON, use parameters */ }
+  switch (action) {
+    case 'getData': {
+      const queryFid = body.queryFid || request.optParameter('queryFid').orElse('');
+      response.out(JSON.stringify({ success: true, data: getQueryData(queryFid) }));
+      break;
+    }
+    case 'updateRecord': {
+      updateRecord(body.recordId, body.updates);
+      response.out(JSON.stringify({ success: true }));
+      break;
+    }
+    default:
+      response.out(JSON.stringify({ success: false, error: `Unknown action: ${action}` }));
+  }
+} catch (error) {
+  console.error('Error in endpoint:', error);
+  B.net.response.out(JSON.stringify({ success: false, error: error.message || String(error) }));
+}
+```
+## Error Handling Patterns
+### Try-catch with user feedback (client-side)
+SweetAlert2 v8.18.4 API (`type:`, `result.value`) — not v11. See [common-gotchas](../gotchas/common-gotchas.md#sweetalert2-version-differences).
+```typescript
+async function performAction() {
+  try {
+    const result = await apiCall();
+    if (result.success) {
+      Swal.fire({ type: 'success', title: 'Success', text: 'Operation completed successfully' });
+    } else {
+      throw new Error(result.error || 'Operation failed');
+    }
+  } catch (error) {
+    console.error('Error performing action:', error);
+    Swal.fire({ type: 'error', title: 'Error', text: error.message || 'An error occurred' });
+  }
+}
+```
+### Validation pattern
+```typescript
+function validateInput(data: any): { valid: boolean, error?: string } {
+  if (!data.name || data.name.trim() === '') return { valid: false, error: 'Name is required' };
+  if (!data.email || !data.email.includes('@')) return { valid: false, error: 'Valid email is required' };
+  return { valid: true };
+}
+```
+## Performance Patterns
+### Caching query results (client-side)
+```typescript
+const dataCache = new Map();
+async function getQueryData(queryFid: string, forceRefresh = false) {
+  if (!forceRefresh && dataCache.has(queryFid)) return dataCache.get(queryFid);
+  const response = await fetch(endpointUrl, {
+    method: 'POST',
+    body: JSON.stringify({ action: 'getQueryData', queryFid })
+  });
+  const result = await response.json();
+  if (result.success) { dataCache.set(queryFid, result.data); return result.data; }
+  throw new Error(result.error || 'Failed to load data');
+}
+```
+### Batch processing
+```typescript
+function processBatch(records: any[], batchSize = 100) {
+  const results = [];
+  for (let i = 0; i < records.length; i += batchSize) {
+    const batch = records.slice(i, i + batchSize);
+    batch.forEach(record => results.push(processRecord(record)));
+  }
+  return results;
+}
+```
+## Component Import Pattern
+```typescript
+// objects/helpers.ts
+export function formatDate(date: any): string { /* ... */ return formatted; }
+export function formatCurrency(amount: number): string { /* ... */ return formatted; }
+// scripts/app.ts
+import { formatDate, formatCurrency } from './objects/helpers';
+const formatted = formatDate(dateValue);
+```
+A file only executes if it is imported — see [file-execution](file-execution.md).
+## Debugging Patterns
+```typescript
+// At top of file
+const DEBUG = false; // set to true for verbose logging
+if (DEBUG) console.log('Processing record:', recordId);
+console.error('Failed to load data:', error); // always log errors
+```

package/templates/claude/instructions/reference/component-library.md.template ADDED Viewed

@@ -0,0 +1,217 @@
+# Component Library
+> **Note**: for the complete component API, see the JSDoc in `https://files.bluestep.net/script/530024___41/static/genericComponents.js`. This file contains usage patterns and best practices.
+>
+> **Design System**: for visual examples, color palette, typography, and spacing, see [design-system](design-system.md) or the [interactive design system merge report](https://bluestepplatformsupport.bluestep.net/shared/layouts/singleblock.jsp?_event=view&_id=120130___195147).
+**Always check this library before writing custom HTML-generation code.**
+## Contents
+- [Component Source Priority](#component-source-priority)
+- [Configuration and Importing](#configuration-and-importing)
+- [CSS and Merge Report Styling](#css-and-merge-report-styling)
+- [Design Standards](#design-standards)
+- [Common Components](#common-components)
+- [Best Practices](#best-practices)
+- [When NOT to Use Components](#when-not-to-use-components)
+## Component Source Priority
+When building UI, source components in this order:
+1. **BlueStep generic components** — use `moduleF`, `headF`, `svgF`, `tableF`, etc. first.
+2. **Bootstrap 3.3.7 components** — standard Bootstrap (buttons, alerts, modals, panels) when no generic component exists.
+3. **Custom components** — only when necessary, matching the styles of the above.
+## Configuration and Importing
+The recommended setup is to register the library in `info/config.json`, then import with the short name:
+```json
+{
+  "models": [
+    {
+      "name": "genericComponents.ts",
+      "url": "https://files.bluestep.net/script/530024___41/static/genericComponents.ts"
+    }
+  ]
+}
+```
+```typescript
+// ✅ Recommended - when configured in config.json
+import { moduleF, svgF, headF, tableF } from 'genericComponents';
+```
+If it is not configured, you can import from the full hosted URL as a fallback, but adding it to `config.json` is preferred:
+```typescript
+import { moduleF, svgF, headF, tableF } from 'https://files.bluestep.net/script/530024___41/static/genericComponents.js';
+```
+> ⚠️ **`type="module"` required in `index.html`.** When `script.ts` uses an ES `import` (including importing from `genericComponents`), the `<script>` tag must include `type="module"`, or the browser throws `SyntaxError: Cannot use import statement outside a module` and the script silently fails.
+>
+> ```html
+> <script type="module" src=".build/script.js"></script>
+> ```
+## CSS and Merge Report Styling
+Standard BlueStep pages (Connect/Manage) already provide their own HTML and CSS, and the component-library functions (`moduleF`, `headF`, `svgF`, `tableF`, `fieldF`, `bootstrapFormF`) are designed to work within that styling.
+- **Do NOT add CSS in the merge report for component-library output.** It is already styled by the platform and the library; extra CSS is unnecessary and can conflict with the theme and layout.
+- **Add CSS only for custom HTML** you introduce outside the standard components (custom wrappers, one-off layouts, third-party widgets). Put it in `static/styles.css` referenced from `static/index.html`, scoped to that custom markup only.
+## Design Standards
+### Color palette (CSS variables)
+Always use CSS variables for colors so they stay consistent across themes.
+Standard colors (available on all BlueStep pages):
+- `--bs-red: #c03b2b` | `--bs-orange: #F29D1F` | `--bs-yellow: #EFC319`
+- `--bs-green: #28AE60` | `--bs-blue: #2A81BA` | `--bs-purple: #894C9E`
+- `--bs-logo-blue: #0063A6` (brand logo color, used in email templates)
+- `--bs-gray: #969FA0` | `--bs-default: #2D3F50` (default theme color)
+Custom generated colors (vary by the organization's color style):
+- `--bs-primaryColor` | `--bs-primaryColorHigh`
+- `--bs-accent1Color` | `--bs-accent2Color`
+- `--bs-secondaryColor` | `--bs-secondaryColorHigh`
+### Available components
+- **SVG Icons** (`svgF` / `svgIconF`, `svgTitleF`) | **Headers** (`headF`) | **Tables** (`tableF`)
+- **Fields** (`fieldF`) | **Bootstrap Forms** (`bootstrapFormF`) | **Modules** (`moduleF`)
+- **Generic Tags** (`tagF`) | **Anchors** (`aF`) | **Email Templates** (`emailF`)
+- **Breadcrumbs** (`breadcrumbF`) | **Search** (`searchHeadF`, `searchTextF`)
+- **Date Input** (`bsDateInput`) | **Date Range** (`jsDateRange`) | **Popin Hints** (`popinHintF`)
+- **Horizontal Forms** (`bsHorizFormCol2F`, `bsHorizFieldCol2F`)
+## Common Components
+### SVG Icons
+**When to use**: all icon needs (don't use `<img>` directly).
+```typescript
+import { svgF } from 'genericComponents';
+const icon = svgF({ icon: 'settings', size: 48 });
+const colored = svgF({ icon: 'settings', size: 24, color: 'white blue' });
+// Common icons: trash, pencil, gear3, circleCheck, circleX, calendar2, magnify, plus
+```
+⚠️ **REQUIRED: reference the icon endpoint before using any icon.** Before selecting or suggesting an icon, query the official BlueStep SVG icons endpoint:
+- **URL**: `https://bluestepplatformsupport.bluestep.net/b/svgIconsList`
+- **Returns**: a JSON array where each icon has `icoName` (e.g. `"calendar.svg"`), `category` (e.g. `["Standard", "System and Technical"]`), and `icoKeywords` (e.g. `"calendar, day, week, month, year, schedule"`).
+How to use it: search the endpoint by name, category, or keyword; use the icon name **without** the `.svg` extension (`calendar.svg` → `svgF({ icon: 'calendar', size: 24 })`); match the icon to context via categories/keywords. Never guess icon names or use icons not listed in the endpoint.
+### Headers
+**When to use**: section headers, collapsible sections.
+```typescript
+import { headF } from 'genericComponents';
+const header = headF({ title: 'Section Title' });
+const withButton = headF({ title: 'Section Title', button: '<button>Action</button>', hint: 'Help text' });
+const collapsible = headF({ title: 'Collapsible Section', isCollapsable: true, content: '<div>Content</div>', isOpen: true });
+```
+### Tables
+**When to use**: simple data tables (use Tabulator for complex tables).
+```typescript
+import { tableF } from 'genericComponents';
+const table = tableF({
+  className: 'table table-striped',
+  showHeaders: true,
+  tableRows: [ { 'Name': 'John', 'Age': '30' }, { 'Name': 'Jane', 'Age': '25' } ]
+});
+```
+### Modules
+**When to use**: full page layouts in Connect/Manage.
+```typescript
+import { moduleF } from 'genericComponents';
+const module = moduleF({
+  id: 'dashboard',
+  header: 'Dashboard',
+  tabs: [
+    { icon: 'home',  label: 'Overview', className: 'cDefault', tabContent: overviewContent },
+    { icon: 'chart', label: 'Reports',  className: 'cReports', tabContent: reportsContent }
+  ]
+});
+```
+**Module colors**: cDefault, cReports, cOrange, cGreen, cBlue, cYellow, cPurple, cRed, cBrown.
+### Email Templates
+**When to use**: all email generation (don't create custom email HTML).
+```typescript
+import { emailF } from 'genericComponents';
+const email = emailF({
+  title: 'Account Verification',
+  previewText: 'Please verify your email address',
+  bodyText: 'Click the button below to verify your email address.',
+  btnLink: 'https://example.com/verify?token=xyz',
+  btnText: 'Verify Email',
+  primaryColor: '0063A6',
+  logoImg: 'https://example.com/logo.png'
+});
+```
+### Forms
+**When to use**: form inputs in Connect/Manage pages.
+```typescript
+import { bootstrapFormF } from 'genericComponents';
+const form = bootstrapFormF({
+  id: 'user-form',
+  labelSize: 'third',
+  fields: [
+    { fieldLabel: 'Name', fieldId: 'name', fieldType: 'text' },
+    { fieldLabel: 'Role', fieldId: 'role', fieldType: 'select',
+      fieldList: [ { idValue: 'admin', label: 'Administrator' }, { idValue: 'user', label: 'User' } ] },
+    { fieldLabel: 'Active', fieldId: 'active', fieldType: 'checkbox', fieldIsSelected: true }
+  ]
+});
+```
+(For generating form fields from real BlueStep fields with labels and validation, see `mergeTag()` in [api-patterns](api-patterns.md#mergetag-method).)
+## Best Practices
+**DO ✅**
+1. Use the component library first; reach for raw HTML only when nothing fits.
+2. Use semantic components: `moduleF()` for layouts, `headF()` for headers, `svgF()` for icons, `emailF()` for emails.
+3. Check the JSDoc in the source for the complete API.
+**DON'T ❌**
+1. **Don't add CSS for component-library output** — it is already styled (see [CSS and Merge Report Styling](#css-and-merge-report-styling)).
+2. **Don't recreate existing components** — use `tableF({ tableRows: data })`, not a hand-built `<table>`.
+3. **Don't use inline SVG or `<img>` for icons** — use `svgF({ icon: 'settings', size: 24 })`.
+4. **Don't create custom email HTML** — always use `emailF()`.
+5. **Don't mix component styles** — use the Bootstrap classes from the components and the module color scheme.
+## When NOT to Use Components
+Some cases require custom HTML: complex interactive UIs (use frameworks like Tabulator), real-time dashboards with heavy client logic, or highly customized layouts that don't match BlueStep patterns. Even then, use components for sub-elements (`svgF`, `headF`, etc.).

package/templates/claude/instructions/reference/crm-dashboard-inspo.md.template ADDED Viewed

@@ -0,0 +1,17 @@
+---
+description: "CRM Intelligence Dashboard (beh/1433876) — 12-page sales SPA, reference/inspiration for the Behavioral Team Scorecard deal metrics"
+---
+**CRM Intelligence Dashboard** — BlueStep merge report at **beh.bluestep.net/files/1433876** (script "CRM Dashboard", key 530024___82). A CEO/CRO-grade sales-pipeline SPA with 12 interactive pages. Pulled as inspiration for behavioral scorecard deal-based metrics. NOT to be modified — reference only.
+**Architecture (the pattern to reuse):**
+- `scripts/app.ts` (server, ~287 lines): iterates `allPrograms` ONCE, flattens each program + its `deals` and `followups` sub-forms into plain `ProgramLite` / `DealLite` / `FollowupLite` objects, builds a `{meta, programs, deals, followups}` payload, and emits it as `<script id="crm-data" type="application/json">…</script>` + an empty `<div id="crm-app">`. JSON is escaped with `.replace(/</g, '\\u003c')` before embedding.
+- `static/script.ts` (client, ~3700 lines): reads the JSON payload, renders the SPA — global filter bar + tab dispatch (`renderActiveTab`) + 12 page renderers (`renderOverview`, `renderRevenue`, `renderPipeline`, `renderSources`, `renderOwners`, `renderProducts`, `renderWinLoss`, `renderVelocity`, `renderFollowups`, `renderTrends`, `renderConferences`, `renderExplorer`) + a shared deal-detail modal.
+- **Single-file client bundle**: BlueStep compiles ONLY `static/script.ts` → `.build/script.js`. The `static/util/*.ts`, `static/pages/*.ts`, `static/filters.ts`, `static/tabs.ts`, `static/types.ts` files are source-of-record copies, NOT compiled — all live code is inlined into script.ts. (Confirms [single script](../conventions/single-script.md).)
+- `static/index.html`: loads Chart.js 4 from jsDelivr CDN, then `.build/script.js`, then `styles.css`. Charts use Chart.js.
+**Reusable techniques:** canonical-vs-observed dropdown merging (`mergeUnique`); per-entity try/catch so one bad deal/program doesn't kill the report; weighted revenue forecast by confidence color (Green/Yellow/Red); HTML funnel, donuts, stacked bars, heatmaps, age histograms; CSV export; deal modal keyed by id.
+**Server field-read helpers worth copying:** `formatDate(field)` (DateField→LocalDate.format, falls back to LocalDateTime.toLocalDate), `readSingleSelect(field)` (`field.opt().map(v=>v.displayName()).orElse('')`), multi-select via `field.selectedNames().toArray()`.
+**CAUTION when reusing on the scorecard:** the CRM dashboard reads fields from ITS OWN context (e.g. `info.ownerTxt`, `info.city/state`, `deal.dealOwnerTxt` text mirror, `followups` form with `dealRel`/`ownerRel`/`completeSig`). The scorecard's `deals` form (its own declarations) uses `dealOwnerRel` (relationship, not Txt) and may not expose the same `info`/`followups` fields. Always build scorecard deal metrics against the scorecard's `1434276/declarations/index.d.ts`, not by assuming CRM field names.

package/templates/claude/instructions/reference/csv-parsing.md.template ADDED Viewed

@@ -0,0 +1,18 @@
+---
+description: BlueStep merge reports CAN read & parse uploaded CSVs — built-in B.csv() parser + DocumentLinkField/Document/fetch access
+---
+A server-side BSJS merge report CAN access and parse an uploaded CSV at runtime. BlueStep ships a first-class CSV parser — no hand-rolled splitting needed.
+**Parser:** `B.csv(input, charset?)` (aliases `B.io.csv` / `B.text.csv`). Accepts a Reader, InputStream, FetchedResource, or string. Methods: `.toListOfObjects()` (array of objects keyed by header row — easiest), `.forEach((rowEList, i)=>…)` (streaming), `.toList()` (2D), and chainable `.fieldDelimeter()/.textDelimeter()/.escapeCharacter()`. Rows from `.row()` are Java-backed `EList<string>` — use `.forEach`/index, NOT JS `.map()`; `toListOfObjects()` rows behave like plain objects.
+**Three ways to get the file's bytes (priority order):**
+1. **DocumentLinkField on a form/record (preferred)** — an uploaded-file field. `field.content()` → string; `field.forReader(r => B.csv(r).toListOfObjects())` streams it. Also `.forInputStream()`, `.toBytes()`, `.filename()`, `.contentType()`, `.permUrl()/.davUrl()`. No HTTP hop, no auth ambiguity.
+2. **Document in a folder** — `folder.documents()['name.csv']` → same `.content()/.forReader()/.toBytes()` accessors. For file-system uploads not on a record.
+3. **Fetch by URL** — same `B.net.fetch(url)` pattern we use to inline styles.css; `B.csv(fetcher, fetcher.charset)`. Fallback only — reliability depends on URL + session auth. Prefer 1/2 for uploaded files.
+**Permissions:** merge report runs in current user's context; routes 1/2 read via the platform object model subject to record/folder security.
+**Gotchas:** strip UTF-8 BOM (`` corrupts first header key on Excel/QuickBooks exports); handle `\r\n`; sanitize currency (`$`, thousands commas, `(123)` negatives) before parseFloat; pass charset if Windows-1252; streaming `.forReader()` avoids buffering huge files and sidesteps the "code 0 but real content" issue seen with `B.io.fromInputStream`.
+**Relevance:** unlocks the behavioral scorecard placeholder metrics that aren't in relational data — MRR, Monthly Profitability, Avg Contribution Margin (QuickBooks exports), NPS (survey results). Pattern: upload CSV to a Document field on a settings record; in app.ts `field.forReader(r => B.csv(r).toListOfObjects())`; the metric's Verify table can show the parsed rows. Docs: ~/.bluestep/docs/classes/CSV.md, DocumentLinkField.md, Document.md, Folder.md, B.Bluestep.IO.md.

package/templates/claude/instructions/reference/dashboard-design-system.md.template ADDED Viewed

@@ -0,0 +1,38 @@
+---
+description: "Brandon's house design language for BlueStep dashboard merge reports — exact tokens (palette, type, cards, tabs). Use this for ALL new BlueStep dashboard UI; do NOT use Material/rounded-tonal styling"
+---
+Brandon's BlueStep dashboards (Census 1469219, Visit 1471499, DPN rop/1475679,
+Authorization rop/1476379, and now Resources Hub 1471799) share ONE consistent
+house style. Match it for any new dashboard/merge-report UI. **Not Material** — he
+explicitly rejected the Material 3 look (nav rail, FAB, chunky tonal containers,
+big radii, floating labels). Clean light enterprise, flat, data-forward.
+**Palette (CSS vars):** primary `#1a6bb5`, primary-hover `#155d9e`, primary-active
+`#104d85`; heading `#1a2d3f`; body `#2d3f50`; label `#4a5568`; muted `#7a8694`;
+page bg `#f4f5f7`; surface `#fff`; alt-row `#f8f9fa`; row-hover `#e8f0fb`; border
+`#dde1e7` (inputs `#c4cdd6`); table-header bg `#2d3f50` (white text). Status:
+green `#137333`/bg`#e6f4ea`, yellow `#7a4f00`/bg`#fef7e0`, red `#c5221f`/bg`#fce8e6`,
+gray `#5f6368`/bg`#f1f3f4` (also flat success `#28ae60`, warn `#f5b400`, err `#c03b2b`).
+**Type:** system stack (`-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,
+'Helvetica Neue', Arial, sans-serif`) — NO web font. Base 14px. Page title 22px/700/
+-0.3px. Section/card titles 15–16px/700. Labels 13px/600. Badges/pills 11px/700.
+Table headers + stat labels often UPPERCASE, letter-spacing .04–.05em. Math: Menlo/Consolas.
+**Layout:** max-width 1100–1280px, padding `24px 16px 48px`, sections ~20px apart.
+**Cards/surfaces:** white, `1px solid #dde1e7`, radius 6px (8px tiles/modals), shadow
+`0 1px 3px rgba(0,0,0,.06)` (modal `0 8px 32px rgba(0,0,0,.22)`). Depth from borders,
+not heavy shadow. Signature motif: **4px colored left-border accent** on stat tiles /
+cards / kanban columns.
+**Nav:** horizontal **tab bar with 3px underline** on active (active color `#1a6bb5`,
+hover bg `#f8f9fa`), border-bottom `1px #dde1e7`. Tables: dark `#2d3f50` sticky header,
+zebra `#f8f9fa`, hover `#e8f0fb`. Pills: radius 12px (or 999px), 11px/700, color-coded
+bg+fg. Buttons: primary `#1a6bb5` (hover `#155d9e`, focus ring `0 0 0 3px
+rgba(26,107,181,.15-.25)`), outline = blue border that inverts on hover. Transitions
+0.12–0.15s. No gradients (except subtle thumb backgrounds).
+Relevant to bluestep resources; pairs with
+[merge report static index](merge-report-static-index.md) and [separate files](../conventions/separate-files.md).

package/templates/claude/instructions/reference/datetime-field-write.md.template ADDED Viewed

@@ -0,0 +1,27 @@
+---
+description: Use field.val(zonedDateTime) to set a DateTimeField; .dateTimeVal() has Graal-ambiguous overloads
+---
+**Use `field.val(zonedDateTime)` to write a DateTimeField. Do not use `.dateTimeVal(...)`.**
+**Why:** `DateTimeField extends FormulaField<DateTimeField, java.time.ZonedDateTime>` — so the inherited `Field.val(T)` setter takes `ZonedDateTime` directly. The class also exposes a `dateTimeVal(...)` helper, but its Java side has two single-argument overloads: `dateTimeVal(LocalDateTime)` and `dateTimeVal(Instant)`. When you feed it a `ZonedDateTime` from `B.time.ZonedDateTime.now()`, Graal can't pick between the two and throws:
+```
+invokeMember (dateTimeVal) on ...DateTimeDataTypeFieldScript failed due to:
+Multiple applicable overloads found for method name dateTimeVal
+(candidates: [...dateTimeVal(LocalDateTime), ...dateTimeVal(Instant)],
+arguments: [...ZonedDateTime])
+```
+The class doc literally says `dateTimeVal(localDateTime, zoneId)` is *"the same as calling val(localDateTime.atZone(zoneId))"* — confirming `.val()` is the canonical setter.
+**How to apply:**
+- Setting "now": `entry.fields.someDateTime.val(B.time.ZonedDateTime.now());`
+- Setting from parts: `entry.fields.someDateTime.val(localDateTime.atZone(zoneId));`
+- Only reach for `.dateTimeVal(arg)` when you have a non-ambiguous argument:
+  - `.dateTimeVal(zdt.toInstant())` — explicit Instant works
+  - `.dateTimeVal(localDateTime, zoneId)` — two-arg overload is unambiguous
+  - `.dateTimeVal("2026-05-01T13:30:00-07:00")` — the third Java overload accepts a string the Relate parser handles
+- For DateField (no time): use `field.val(localDate)` — same pattern, T = LocalDate.
+- For TimeField: same pattern, T = LocalTime.
+Confirmed on summitridge/1470299 audit-log endpoint, 2026-05-01.