> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# shared — Public API surface

> Per-symbol API documentation for the shared area, generated from TSDoc blocks. Refresh with `npm run docs:api:generate`.

# shared — Public API surface

## Types & interfaces

### type AppIconProps

* file: src/shared/ui/icon.tsx:156
* kind: type
* core: shared
* spec: (none)
* summary: Decorative icons ( defaults to ) get and forbid . Meaningful icons () require so screen readers announce them.
* score: 2

### type AppIconTone

* file: src/shared/ui/icon.tsx:75
* kind: type
* core: shared
* spec: (none)
* summary: Semantic tone keys — map 1:1 to existing semantic color tokens defined in and consumed by in. Dark mode and PF-95 tenant themingapply automatically; no new CSS variables.
* score: 2

### type AppIconVariant

* file: src/shared/ui/icon.tsx:105
* kind: type
* core: shared
* spec: (none)
* summary: Visual variant. is the default Lucide line look; fills the glyph.
* score: 2

### type AppIconWeight

* file: src/shared/ui/icon.tsx:108
* kind: type
* core: shared
* spec: (none)
* summary: Stroke-width shorthand. prop, when passed, always wins.
* score: 2

### interface BarShapeProps

* file: src/shared/lib/recharts-types.ts:8
* kind: interface
* core: shared
* spec: (none)
* summary: Props passed to custom Bar shape renderers
* score: 2

### interface BillingProvider837I

* file: src/shared/lib/x12/x12-837i.ts:13
* kind: interface
* core: shared
* spec: (none)
* summary: PM-08-EN-14: Pure X12 837I Institutional Claim GeneratorGenerates ANSI X12 837I (005010X223A2) claim segments. Does NOT build theISA/GS/ST envelope — pair with the envelope builder in (Deno) when serializing.Pure: no React, no Supabase, no Deno globals. Safe for Vitest + browser.A Deno mirror lives at for edge-function consumption (kept in lockstep — update both).
* score: 2

### interface BuildErrorToastOptions

* file: src/shared/lib/error-utils.ts:166
* kind: interface
* core: shared
* spec: (none)
* summary: Options controlling how formats its payload.
* score: 2

### type CalendarProps

* file: src/shared/ui/calendar.tsx:16
* kind: type
* core: shared
* spec: (none)
* summary: Calendar component with enhanced mobile touch targets.Touch target sizes (WCAG 2.5.8 compliant):- Navigation buttons: 44x44px minimum- Day cells: 44x44px minimum- Head cells: 44px width for alignment
* score: 2

### interface CollapsedNavTriggerProps

* file: src/shared/ui/trigger-wrapper.tsx:101
* kind: interface
* core: shared
* spec: (none)
* summary: Icon-based nav trigger (collapsed sidebar pattern)Uses button element for proper Radix UI TooltipTrigger compatibility
* score: 2

### type DestructiveToastPayload

* file: src/shared/lib/error-utils.ts:159
* kind: type
* core: shared
* spec: (none)
* summary: Standardized payload for a destructive (error) toast notification.
* score: 2

### type DiffType

* file: src/shared/lib/semantic-colors.ts:261
* kind: type
* core: shared
* spec: (none)
* summary: Diff Visualization ColorsFor version comparison UIs showing added, removed, modified changes.
* score: 2

### type DomainStatus

* file: src/shared/lib/semantic-colors.ts:98
* kind: type
* core: shared
* spec: (none)
* summary: Domain Status → Icon ToneAliases for product/business statuses (workflow lifecycle, approvals,scheduling, billing, clinical) that map back to the six core values — and therefore to existings. No new CSS tokens; no expansion of .Use this when a UI needs for a status string thatisn't one of the core six (e.g. , , ).Unknown keys fall back to so the UI never breaks.Keep alphabetized within each lifecycle group below to make additionsobvious in code review.
* example: |
  AppIcon icon=CheckCircle2 size="sm" tone=domainStatusToIconTone(claim.status) /
* score: 5

### interface EstimatorBenefitInputs

* file: src/shared/lib/pm/benefit-estimator.ts:15
* kind: interface
* core: shared
* spec: (none)
* summary: PM-02-EN-02: Benefit Estimator (pure logic)Calculates patient out-of-pocket responsibility for a single encountergiven a normalized benefit detail row and the contracted/fee-scheduleamount for the CPT.Pure and synchronous — mirror-maintained atsupabase/functions/\_shared/pm/benefit-estimator.ts.See PM-02-EN-02-CONTEXT.md § D3. shared/lib/pm/benefit-estimator
* score: 2

### type FederalBaseline

* file: src/shared/lib/state-compliance/federal-baseline.ts:17
* kind: type
* core: shared
* spec: (none)
* summary: GR-06-EN-01: Federal Baseline Evaluation HelperPure helper that evaluates whether a proposed AI compliance recommendationweakens the federal baseline. Used as the second enforcement layer (afterthe AI system prompt) per CONTEXT.md decision §1 (two-layer enforcement).Field semantics: - time-based (, ) - recommendation must be ≤ baseline (shorter or equal) - count-based (, ) - recommendation must be ≥ baseline (larger or equal) - enum/array (, ) - recommendation must be a superset (union) - boolean (, ) - if baseline is , recommendation must remain
* see:
  * specs/gr/specs/GR-06-EN-01-ai-state-compliance-checking.md §FR-2 federal baseline enforcement
* score: 5

### type InferSchema

* file: src/shared/lib/validation/schema-builders.ts:256
* kind: type
* core: shared
* spec: (none)
* summary: Extracts the inferred type from a schema
* score: 2

### type InferSchemaInput

* file: src/shared/lib/validation/schema-builders.ts:261
* kind: type
* core: shared
* spec: (none)
* summary: Extracts the input type from a schema (before transforms)
* score: 2

### type InferSchemaOutput

* file: src/shared/lib/validation/schema-builders.ts:266
* kind: type
* core: shared
* spec: (none)
* summary: Extracts the output type from a schema (after transforms)
* score: 2

### type NullToUndefined

* file: src/shared/lib/utils/type-utils.ts:22
* kind: type
* core: shared
* spec: (none)
* summary: Type that converts all null values in an object type to undefined.Useful for converting Supabase Row types to form-compatible types.
* example: |
  type DbRow =  name: string; email: string | null ;type FormValues = NullToUndefinedDbRow;// Result:  name: string; email: string | undefined
* score: 5

### interface ParsedEbSegment

* file: src/shared/lib/pm/benefit-parser.ts:18
* kind: interface
* core: shared
* spec: (none)
* summary: Subset of EB-loop fields produced by the clearinghouse adapter.
* score: 2

### type PartialNullToUndefined

* file: src/shared/lib/utils/type-utils.ts:30
* kind: type
* core: shared
* spec: (none)
* summary: Type that makes all properties optional and converts nulls to undefined.Useful for partial form updates.
* score: 2

### interface PHIPattern

* file: src/shared/lib/phi-detection.ts:15
* kind: interface
* core: shared
* spec: (none)
* summary: A single PHI/PII detection pattern with a human-readable label.
* score: 2

### interface PieLabelProps

* file: src/shared/lib/recharts-types.ts:21
* kind: interface
* core: shared
* spec: (none)
* summary: Props passed to Pie label render functionBased on Recharts PieLabelRenderProps but with optional fields
* score: 2

### interface ProcedureGapEventPayload

* file: src/shared/lib/gr/buildQIDraftFromGap.ts:14
* kind: interface
* core: shared
* spec: (none)
* summary: GR-13-EN-01: Build a draft QI project from a event payload.Pure function — no Supabase, no Deno, no I/O. Used by the edge function handler() and unit-tested directly.Payload shape mirrors the publisher in : organization\_id, procedure\_id, procedure\_title, category, completion\_rate\_pct, overdue\_count, exported\_by, exported\_at
* score: 2

### type QIProjectCategory

* file: src/shared/lib/gr/buildQIDraftFromGap.ts:37
* kind: type
* core: shared
* spec: (none)
* summary: Categories accepted by .Source: migration enforcing CHECK (category IN (...)) on .
* score: 2

### type RecommendationLevel

* file: src/shared/lib/semantic-colors.ts:196
* kind: type
* core: shared
* spec: (none)
* summary: Recommendation/Rating Scale ColorsFor 5-point scales commonly used in HR evaluations, interviews, etc.Maps to semantic tokens while maintaining visual distinction.
* score: 2

### interface ScrollAreaProps

* file: src/shared/ui/scroll-area.tsx:17
* kind: interface
* core: shared
* spec: (none)
* summary: ScrollArea component with enhanced mobile scroll behavior.Features:- iOS momentum scrolling via -webkit-overflow-scrolling: touch- Optional overscroll containment to prevent scroll chaining- Customizable scrollbar orientation
* see:
  * [https://developer.mozilla.org/en-US/docs/Web/CSS/overscroll-behavior](https://developer.mozilla.org/en-US/docs/Web/CSS/overscroll-behavior)
* score: 5

### interface ServiceTypeMapping

* file: src/shared/lib/pm/service-type-mapper.ts:16
* kind: interface
* core: shared
* spec: (none)
* summary: PM-02-EN-02: Service Type MapperMaps X12 271 EB service type codes to user-friendly behavioral-healthcategories and labels. v1 ships a hardcoded default mapping; per-payeroverrides are deferred (see CONTEXT.md "Open Questions").NOTE: This file is mirror-maintained at supabase/functions/\_shared/pm/service-type-mapper.tsEdge Functions cannot import / aliases; if logic changes here, updatethe mirror copy as well. See PM-02-EN-02-CONTEXT.md § D3. shared/lib/pm/service-type-mapper
* score: 2

### interface StatusIndicatorTriggerProps

* file: src/shared/ui/trigger-wrapper.tsx:130
* kind: interface
* core: shared
* spec: (none)
* summary: Status indicator trigger (dashboard sync, stale data patterns)
* score: 2

## Hooks

### hook useAutoAnimate

* file: src/shared/lib/hooks/use-auto-animate.ts:105
* kind: hook
* core: shared
* spec: (none)
* summary: Extended auto-animate hook with preset support
* params:
  * options — Animation options or preset name
* returns: Tuple of \[parent ref, enable/disable function]
* score: 4

### hook useDebounce

* file: src/shared/lib/hooks/use-debounce.ts:20
* kind: hook
* core: shared
* spec: none
* summary: Returns a debounced copy of that only updates after ms havepassed without further changes. Useful for search inputs, autosave drafts,and any expensive effect that should wait until the user stops typing.Cleans up the timer on unmount and on every value/delay change so callersdo not need to track ids themselves.
* params:
  * value — The source value to debounce; type is preserved via generic .
  * delay — Milliseconds of quiet time required before the debouncedvalue updates (typical: 150–400 for search).
* returns: The latest that has remained stable for ms.
* example: |
  const debouncedQuery = useDebounce(query, 250);useEffect(() =  runSearch(debouncedQuery); , \[debouncedQuery]);
* score: 5

### hook useDockBlurPreset

* file: src/shared/lib/hooks/useDockBlurPreset.ts:57
* kind: hook
* core: shared
* spec: none
* summary: Reads the user's persisted dock/header backdrop-blur preset from (defaulting to ), syncs the active value to the CSS variable on via an effect, and exposes a setterplus a toggle that flips between the two presets: - - 8px (more underlay detail visible, lighter perf cost) - - 24px (deeper frosted-glass look, default)Both and consume so thechange applies instantly without re-rendering the dock surfaces. SSR-safe:skips / access when those globals are unavailable, andsilently swallows write failures (private-browsing / quota).
* returns: An object with the current , a writerthat also persists to localStorage, and a helper that flipsbetween and .
* example: |
  const  preset, toggle  = useDockBlurPreset();Switch checked=preset === 'high' onCheckedChange=toggle /
* score: 5

### hook useEntityBreadcrumb

* file: src/shared/lib/hooks/useEntityBreadcrumb.ts:18
* kind: hook
* core: shared
* spec: (none)
* summary: Sets a breadcrumb label from entity data
* params:
  * data — The entity data (can be undefined while loading)
  * labelExtractor — Function to extract the label from the data
* score: 4

### hook useFormBuilderAnimation

* file: src/shared/lib/hooks/use-auto-animate.ts:135
* kind: hook
* core: shared
* spec: none
* summary: Specialized wrapper tuned for the form-builder field list:applies the preset (200ms ease-out, respects) so drag-and-drop reordering and insertion animatesmoothly without distracting from the editing surface.
* returns: Tuple of from —attach to the container of the animated children; call to suspend animations (e.g. during bulk imports).
* example: |
  const \[fieldsRef] = useFormBuilderAnimation();div ref=fieldsReffields.map((f) = FieldCard key=f.id field=f /)/div
* score: 5

### hook useIsMobile

* file: src/shared/lib/hooks/use-mobile.tsx:27
* kind: hook
* core: shared
* spec: (none)
* summary: Returns when the viewport is narrower than 768 px.Initial state is read synchronously from to eliminatethe desktop-chrome hydration flash that v1 of this hook caused on realmobile devices (PR-3.1 in the mobile-gestures consistency plan).Use this hook in preference to . See for non-standard breakpoints.
* score: 4

### hook useListAnimation

* file: src/shared/lib/hooks/use-auto-animate.ts:157
* kind: hook
* core: shared
* spec: none
* summary: Default-preset wrapper for general-purpose listcontainers: 250ms ease-in-out fades and reflows when items are added,removed, or reordered. Use as a drop-in for typical lists without choosinga preset explicitly.
* returns: Tuple of from .Attach to the list container and toggle topause animations for the lifetime of the component.
* example: |
  const \[listRef] = useListAnimation();ul ref=listRefitems.map((i) = li key=i.idi.name/li)/ul
* score: 5

### hook useMediaQuery

* file: src/shared/lib/hooks/use-media-query.ts:17
* kind: hook
* core: shared
* spec: (none)
* summary: Generic media-query hook.Use this for **non-standard breakpoints** (e.g. 1024 px desktop boundary,, , etc.).
* score: 4

### hook usePrefetch

* file: src/shared/lib/hooks/usePrefetch.ts:70
* kind: hook
* core: shared
* spec: none
* summary: Returns a helper that warm-imports the lazy chunk fora known module / page on demand (typically called from / on a navigation link). Each route is preloaded at most once persession, tracked in a module-level . Failed imports (offline, missingchunk) are silently swallowed so the cache can retry later — prefetch isalways best-effort and never surfaces errors to the user.
* returns: An object exposing ; unknown routesare a no-op so callers can pass any string defensively.
* example: |
  const  preloadRoute  = usePrefetch();Link to="/rh" onMouseEnter=() = preloadRoute('/rh')Recovery Housing/Link
* score: 5

### hook useSafeAreaInsetSync

* file: src/shared/lib/hooks/useSafeAreaInsetSync.ts:18
* kind: hook
* core: shared
* spec: (none)
* summary: Keeps the CSS variables on in sync with the live values acrossorientation changes.iOS Safari (and some Android browsers) do not refresh valuessynchronously on — they wait for the next layout/scroll,which leaves fixed surfaces (dock, FAB, MobileHeader, BottomTabBar) usingstale insets and visibly misaligned for a beat after rotation.We read the resolved env values from a hidden probe element and write themas explicit pixel values onto , overriding the stale resolutionuntil the browser catches up. Existing consumers automatically pick up therefreshed values because they already read .
* score: 4

### hook useTabVisibility

* file: src/shared/lib/hooks/use-tab-visibility.ts:38
* kind: hook
* core: shared
* spec: none
* summary: Subscribes to the document event and returns whether thecurrent tab is foregrounded. Useful for pausing polling, websockets, orrealtime subscriptions when the tab is hidden to conserve battery andnetwork. SSR-safe: returns and skips the listener when isnot defined.
* returns: when the tab is visible (), when hidden. The value updates synchronously as the user switchestabs or minimizes the window.
* example: |
  const isVisible = useTabVisibility();useQuery(  queryKey: \['inbox'],  queryFn: fetchInbox,  refetchInterval: isVisible ? 30\_000 : false,);
* score: 5

### hook useWizardAnimation

* file: src/shared/lib/hooks/use-auto-animate.ts:179
* kind: hook
* core: shared
* spec: none
* summary: Slow-preset wrapper for wizard step transitions: 400msease-in-out, deliberately more visible than so usersnotice that the page has advanced from one step to the next. Honors via the underlying library.
* returns: Tuple of from .Attach to the step-container element so each rendered stepfades / slides into place when changes.
* example: |
  const \[stepRef] = useWizardAnimation();div ref=stepRefrenderStep(currentStep)/div
* score: 5

## Components

### component AreaNavigationCard

* file: src/shared/components/AreaNavigationCard.tsx:59
* kind: component
* core: shared
* spec: none
* summary: Renders a clickable card that links to a functional area, used on moduleoverview pages to surface sub-areas with a leading icon, headline metrics,and up to three quick-link buttons. Whole-card click navigates to ;quick-link buttons stop propagation so they navigate independently. Keyboardaccessible (Enter / Space) with descriptive and a 44x44 hittarget on each quick-link button.
* params:
  * props — , , (lucide), and arerequired. renders inline KPI tiles (with variants); renders the firstthree as small outlinebuttons. is merged onto the Card.
* example: |
  AreaNavigationCard  title="Recovery Housing"  description="Beds, residents, and house policies"  icon=Home  route="/rh"  metrics=\[ label: 'Open beds', value: 12 ]  quickLinks=\[ label: 'Residents', route: '/rh/residents' ]/
* score: 5

### component BackNav

* file: src/shared/components/BackNav.tsx:57
* kind: component
* core: shared
* spec: (none)
* summary: Standardized back-navigation control (outline button with visible label).Prominent by default — labeled + bordered so users can easily locate it onboth desktop and mobile. Use for icon-only mode.When is provided alongside , a history-aware wrapperfires if in-app history exists, otherwise navigates to .
* score: 2

### component CardActionsMenu

* file: src/shared/components/CardActionsMenu.tsx:43
* kind: component
* core: shared
* spec: (none)
* summary: CardActionsMenu - A consistent actions dropdown for cardsFeatures:- Touch-safe sizing (44x44px on mobile, 32x32px on desktop)- Optional hover-reveal behavior (always visible on mobile)- Uses semantic design tokens onlyUsage:Note: Parent card should have class for hover-reveal to work
* score: 2

### component CardContentCompact

* file: src/shared/components/CardContentVariants.tsx:18
* kind: component
* core: shared
* spec: (none)
* summary: CardContentCompact - Reduced padding for dense contentUse for: Dashboard widgets, list items, compact cards
* score: 2

### component CardContentFlush

* file: src/shared/components/CardContentVariants.tsx:42
* kind: component
* core: shared
* spec: (none)
* summary: CardContentFlush - No padding, for edge-to-edge contentUse for: Tables, images, custom layouts that need full width
* score: 2

### component CardContentSpacious

* file: src/shared/components/CardContentVariants.tsx:30
* kind: component
* core: shared
* spec: (none)
* summary: CardContentSpacious - Extra padding for prominent contentUse for: Hero sections, empty states, feature highlights
* score: 2

### component ConfirmationDialog

* file: src/shared/components/ConfirmationDialog.tsx:56
* kind: component
* core: shared
* spec: (none)
* summary: ConfirmationDialogA reusable confirmation dialog that replaces native window\.confirm().Supports different variants for different action types, and an optionaltype-to-confirm gate for irreversible actions.
* score: 5

### component DatePicker

* file: src/shared/ui/date-picker.tsx:39
* kind: component
* core: shared
* spec: none
* summary: Accessible single-date picker built on a Popover + the shadcn component. The trigger is a 44px-tall outline button that displays theselected date in long-form ( via ) or the placeholder whenunset. The trigger's swaps between "Selected date: …" and"Choose date" so screen readers always announce current state. Use forform fields where a relative or natural date is more user-friendly than araw .
* params:
  * props — is required (controlled component). Provide for the current selection, (default ), to lock the trigger, and to extend the triggerbutton styling (e.g. width overrides).
* example: |
  DatePicker date=value onDateChange=setValue placeholder="Admit date" /
* score: 5

### component DetailPageLayout

* file: src/shared/components/DetailPageLayout.tsx:64
* kind: component
* core: shared
* spec: (none)
* summary: DetailPageLayout provides a consistent structure for entity detail pages:- PageContainer for responsive padding, max-width, and optional breadcrumbs- PageHeader (title, description, icon, actions, meta)- Loading state support (full-page skeleton)- Body slot for tabs, cards, or stacked sections
* score: 2

### component EmptyState

* file: src/shared/components/EmptyState.tsx:132
* kind: component
* core: shared
* spec: none
* summary: Renders a centered empty-state block with an icon (or fan of up to threeicons that animate on hover), a title, optional description, and anoptional action button. When no explicit / is provided thecomponent picks a glyph from ( for default, forfirst-run, for no-results, for no-permission, for error). Three size tiers () drive padding, icon size, andthe description column width.
* params:
  * props — is required; other props customize the icon (single, multi fan, or implicit via ), , (label + onClick), visual (), and . Apply for layout overrides.
* example: |
  EmptyState  kind="no-results"  title="No residents match your filters"  description="Try clearing the date range or status filter."  action= label: 'Clear filters', onClick: resetFilters /
* score: 5

### component ErrorState

* file: src/shared/components/ErrorState.tsx:113
* kind: component
* core: shared
* spec: (none)
* summary: Standardized error state for full-page / full-card surfaces.
* score: 2

### component GlobalQueryProgress

* file: src/shared/components/GlobalQueryProgress.tsx:111
* kind: component
* core: shared
* spec: (none)
* summary: Renders a fixed, indeterminate progress bar tied to global query activity.
* score: 2

### component HexSpinner

* file: src/shared/components/HexSpinner.tsx:34
* kind: component
* core: shared
* spec: (none)
* summary: Renders the branded cube spinner used by route and inline loading states.
* score: 2

### component HexSplash

* file: src/shared/components/HexSplash.tsx:11
* kind: component
* core: shared
* spec: (none)
* summary: Displays the full-screen branded loading state used during initial app boot.
* score: 2

### component InfoTooltip

* file: src/shared/components/InfoTooltip.tsx:43
* kind: component
* core: shared
* spec: none
* summary: Renders a small icon button that reveals contextual help text in a Radixtooltip on hover, focus, or tap. The trigger is a 44x44 button (touch-targetcompliant) and the tooltip content is constrained to with so it works well next to form labels and dense table headers.
* params:
  * props — Props for the tooltip, including (the help body),optional (aria-label, default "More info"), placement, custom (default from lucide-react), and class overrides for thetrigger, icon, and content elements. defaults to 0 so thetooltip appears immediately on hover.
* example: |
  InfoTooltip  content="Members enrolled in the last 30 days"  side="right"  label="About new members"/
* score: 5

### component Kbd

* file: src/shared/ui/kbd.tsx:28
* kind: component
* core: shared
* spec: none
* summary: Renders a styled element that visually represents a single keyboardkey for use inside shortcut hints (command palette, tooltips, help dialogs).Sized to 24x24 minimum so it does not destabilize inline text height, andstyled with plus a subtle border + bottom shadow to read as aphysical key cap on both light and dark themes.
* params:
  * props — is the key label (a string like / ora small JSX fragment); pass to extend or override the defaultstyling (e.g. wider keys like ).
* example: |
  Press KbdgetModifierKey()/Kbd + KbdK/Kbd to open the command palette.
* score: 5

### component ListFilterBar

* file: src/shared/components/ListFilterBar.tsx:85
* kind: component
* core: shared
* spec: none
* summary: Renders a consolidated filter bar for list views: a search input, oneselect/dropdown per (single or multi-select), an optional daterange select, and removable chips for every active filter plus a "Clearall" button when any filter is set. Replaces ad-hoc per-page search bars sofilter UX is consistent across cores. All controls meet the touch-targetdensity token ().
* params:
  * props — Controlled props: + (omit bothto hide the search input), (config with options and optional), map keyed by , and callback. Provide //to enable the date selector (defaults to 7/30/90/all-time presets).
* example: |
  ListFilterBar  searchValue=query  onSearchChange=setQuery  filters=\[ key: 'status', label: 'Status', options: STATUS\_OPTIONS, multiSelect: true ]  selectedValues= status: selectedStatuses   onFilterChange=(key, val) = setFilter(key, val)/
* score: 5

### component ListPageLayout

* file: src/shared/components/ListPageLayout.tsx:58
* kind: component
* core: shared
* spec: (none)
* summary: ListPageLayout provides a consistent structure for list/index pages:- PageContainer for responsive padding and max-width- PageHeader with title, description, icon, and actions- Optional filter card- Main content area- Loading state support
* score: 2

### component MobileOverviewHero

* file: src/shared/components/MobileOverviewHero.tsx:81
* kind: component
* core: shared
* spec: (none)
* summary: Mobile-only Focus Bento hero. Hidden on and above.
* score: 2

### component MobileTableWrapper

* file: src/shared/components/MobileTableWrapper.tsx:21
* kind: component
* core: shared
* spec: (none)
* summary: MobileTableWrapper - Wraps tables with horizontal scroll on mobileand provides visual scroll indicators.
* example: |
  MobileTableWrapper  Table    TableHeader.../TableHeader    TableBody.../TableBody  /Table/MobileTableWrapper
* score: 5

### component OverviewPageWrapper

* file: src/shared/components/OverviewPageWrapper.tsx:48
* kind: component
* core: shared
* spec: none
* summary: Standardized wrapper for module overview/landing pages. Combines (pull-to-refresh gesture on touch devices) with (page padding + max-width), and invalidates the suppliedTanStack Query keys in parallel when refresh fires so all core dashboardsstay fresh after a deliberate pull. Pass fordesktop-only pages where the gesture is not wanted.
* params:
  * props — is the page content; is thelist of query-key prefixes to invalidate (e.g. , ). Pass / / to forward to PageContainer, and to run additional async work after invalidation completes.
* example: |
  OverviewPageWrapper refreshQueryKeys=\['hr'] maxWidth="7xl"  HROverviewContent //OverviewPageWrapper
* score: 5

### component PageContainer

* file: src/shared/components/PageContainer.tsx:140
* kind: component
* core: shared
* spec: (none)
* summary: PageContainer wraps page content with responsive padding and spacing.
* example: |
  Titled page (PageContainer renders the PageHeader for you)
  With explicit breadcrumbs
* score: 5

### component PageHeader

* file: src/shared/components/PageHeader.tsx:36
* kind: component
* core: shared
* spec: (none)
* summary: PageHeader - A consistent page header component for all modulesFeatures:- Responsive layout (stacks on mobile, horizontal on desktop)- Optional icon with semantic background- Actions slot for buttons- Meta slot for breadcrumbs/badges- Uses semantic design tokens onlyBack navigation is owned globally by the app-shell header(); pages do not render their own back button.
* score: 2

### component PageLoading

* file: src/shared/components/PageLoading.tsx:47
* kind: component
* core: shared
* spec: (none)
* summary: Renders the canonical in-app loader. Centered, branded, delay-fade indefault mode; in-flow skeleton block in inline mode.
* score: 2

### component PageSeo

* file: src/shared/components/PageSeo.tsx:39
* kind: component
* core: shared
* spec: none
* summary: Renders a per-route , meta description, optional canonical link,and optional tag via . Use onpublic/unauthenticated routes (form portal, verify, preadmission packet) soeach surface advertises its own metadata instead of inheriting the genericsite-wide tags from .
* params:
  * props — and are required; pass (relative URL like ) for self-referencing canonicals and for non-indexable surfaces (verify links, portal previews).
* example: |
  PageSeo  title="Verify your email — Encore"  description="Confirm your email to start your application."  canonicalPath="/portal/verify"  noindex/
* score: 5

### component PageTransition

* file: src/shared/components/PageTransition.tsx:32
* kind: component
* core: shared
* spec: none
* summary: Wraps page content in a div that fades in on every route change. Uses to detect path changes, then toggles a CSS class on the nextanimation frame to retrigger the keyframe. Honors via the global CSS rule in .Not a loading indicator — see for the loading family.
* params:
  * props — to wrap, plus an optional merged ontothe transition container.
* example: |
  PageTransition  Outlet //PageTransition
* score: 5

### component RadialGauge

* file: src/shared/ui/radial-gauge.tsx:48
* kind: component
* core: shared
* spec: (none)
* summary: Circular progress ring built from pure SVG.
* score: 5

### component RequiredMark

* file: src/shared/components/RequiredMark.tsx:28
* kind: component
* core: shared
* spec: (none)
* summary: RequiredMarkInline required-field indicator that pairs with . Renders anasterisk styled with , marked , andpaired with a visually-hidden screen-reader label so assistive tech stillannounces the field as required.Replaces the ad-hoc patternrecreated across the wizard step files (CCR R-T2.2 / R-T4.1).
* score: 5

### component ResponsiveFormLayout

* file: src/shared/components/ResponsiveFormLayout.tsx:34
* kind: component
* core: shared
* spec: (none)
* summary: ResponsiveFormLayout - A wrapper for forms with responsive column layouts.
* example: |
  ResponsiveFormLayout columns=2 spacing="md"  FormField name="firstName" /  FormField name="lastName" //ResponsiveFormLayout
* score: 5

### component RouteFallback

* file: src/shared/components/RouteFallback.tsx:33
* kind: component
* core: shared
* spec: none
* summary: Lightweight Suspense fallback for in-app lazy-route transitions. Renders acentered with a delayed fade-in (avoids flashing for fastchunks) and an live region for screen readers. Sizedto fill the route slot () so it does not collapse the layout.Loading-family selection (single source of truth — see ): - — first-boot only (shell lazy load) - — lazy route Suspense fallback (this file) - — inline page-level overlay - — primitive (compose inside the three above) - — top progress bar for query/router activity
* example: |
  Suspense fallback=RouteFallback /  LazyRouteComponent //Suspense
* score: 5

### component ScrollableTabsList

* file: src/shared/components/ScrollableTabsList.tsx:47
* kind: component
* core: shared
* spec: none
* summary: Wraps shadcn with horizontal-overflow handling: left/right fadegradients, decorative scroll-arrow buttons, scroll-snap, an optionalfirst-mount scroll-hint nudge, and automatic scroll-to-active-tab on mountand whenever changes (URL-synced tabs). Honors (instant scroll, no nudge). When is it skips all overflow chrome and renders a plain vertical.
* params:
  * props — (the s), / forwardedto , for inner styling, (default ), (default ; disable for verydense headers), and for the tablist landmark.
* example: |
  ScrollableTabsList aria-label="Resident sections"  TabsTrigger value="overview"Overview/TabsTrigger  TabsTrigger value="encounters"Encounters/TabsTrigger/ScrollableTabsList
* score: 5

### component StatCard

* file: src/shared/components/StatCard.tsx:146
* kind: component
* core: shared
* spec: (none)
* summary: StatCard - A consistent stat/metric card componentFeatures:- Optional icon with semantic background- Trend indicator with semantic colors- Sparkline mini chart support- Comparison with previous values- Variant support for value coloring- Loading skeleton state- Clickable with hover effects- Uses semantic design tokens only
* score: 2

### component StatusBadge

* file: src/shared/components/StatusBadge.tsx:48
* kind: component
* core: shared
* spec: (none)
* summary: Generic status badge that resolves a status key against a config map.Falls back to a badge with the raw status as the label whenthe key is not in the config (defensive — protects against silentlymissing badge variants on new enum values).
* score: 2

### component TypeToConfirm

* file: src/shared/components/TypeToConfirm.tsx:86
* kind: component
* core: shared
* spec: (none)
* summary: Type-to-confirm input. Disables the parent action button until the user hastyped exactly (or case-insensitively if ).
* score: 2

## Functions & utilities

### function assertRegulatoryChangeLogPayloadPhiSafe

* file: src/shared/lib/regulatory-change-log-phi.ts:82
* kind: function
* core: shared
* spec: FW-57
* summary: Client-side guard that throws before submission when the regulatory changelog payload appears to contain HIPAA-style identifiers (SSN-like patterns,emails, phone/fax numbers, URLs, IP addresses, long numeric IDs, orcalendar dates). Mirrors the categories enforced by database trigger so the UI surfaces the samerejection cause without an extra round trip. Error message is prefixed with so the UI can route it through with a friendly toast.
* params:
  * payload — The regulatory change log payload about to be persisted —the function concatenates , ,, and the JSON-stringified in the sameorder as the DB trigger, then scans the combined text.
* score: 5

### function build837i

* file: src/shared/lib/x12/x12-837i.ts:100
* kind: function
* core: shared
* spec: (none)
* summary: Generate 837I claim segments (between ST/SE envelope) per 005010X223A2.Returns segment array — caller joins with and wraps in envelope.
* score: 4

### function buildErrorToast

* file: src/shared/lib/error-utils.ts:177
* kind: function
* core: shared
* spec: (none)
* summary: Builds a standardized destructive toast payload using sanitizeErrorMessage().Use this to avoid leaking raw error messages to users.
* score: 4

### function buildFieldKey

* file: src/shared/lib/forms/fieldEditorUtils.ts:32
* kind: function
* core: shared
* spec: (none)
* summary: Provides build field key functionality.
* score: 4

### function buildQIDraftFromGap

* file: src/shared/lib/gr/buildQIDraftFromGap.ts:106
* kind: function
* core: shared
* spec: (none)
* summary: Build a draft row from the event payload.
* score: 4

### function calculateBenefitEstimate

* file: src/shared/lib/pm/benefit-estimator.ts:48
* kind: function
* core: shared
* spec: (none)
* summary: Estimate patient responsibility. Deductible applied first, then coinsuranceon remaining amount, then copay (if present). Total is capped by remainingout-of-pocket maximum when known.
* score: 4

### function cn

* file: src/shared/lib/utils.ts:31
* kind: function
* core: shared
* spec: none
* summary: Composes Tailwind class strings from any combination of strings, arrays,objects, and conditional expressions (via ) and then resolvesconflicting Tailwind utilities so later classes win (via). The merge configuration is extended with the family so heading-font overrides do not collide with / from upstream defaults. Use this everywhereclassName strings are assembled — never concatenate with template literalsbecause conflicting utilities will both ship to the DOM.
* params:
  * inputs — Variadic arguments (string, array, object, orfalsy); see types for the accepted shapes.
* returns: The merged, deduplicated class string, ready to assign to.
* example: |
  div className=cn('px-2 py-1', isActive && 'bg-accent', className) /
* score: 5

### function combineRegulatoryChangeLogPhiScanText

* file: src/shared/lib/regulatory-change-log-phi.ts:26
* kind: function
* core: shared
* spec: (none)
* summary: Combine payload fields the same way as the DB trigger (order + JSON for custom\_fields).
* score: 4

### function computeCheckrSignature

* file: src/shared/lib/checkr-signature.ts:28
* kind: function
* core: shared
* spec: (none)
* summary: Compute the canonical Checkr webhook HMAC-SHA256 hex signature. Generates the same hex digest the Edge Function expects in. Pass the **exact** raw request body bytes (not are-serialized JSON) to keep the signature stable.
* params:
  * rawBody — Exact UTF-8 raw request body as received.
  * apiKey — Checkr API key (secret).
* returns: Lowercase hex string (64 chars).
* score: 4

### function createEntitySchema

* file: src/shared/lib/validation/schema-builders.ts:195
* kind: function
* core: shared
* spec: (none)
* summary: Creates a standard entity schema with common fields
* score: 4

### function createFormSchema

* file: src/shared/lib/validation/schema-builders.ts:232
* kind: function
* core: shared
* spec: (none)
* summary: Creates a form schema (without audit fields, for user input)
* score: 4

### function createStatusBadge

* file: src/shared/components/createStatusBadge.tsx:42
* kind: function
* core: shared
* spec: (none)
* summary: Type-safe factory for domain-specific status badges.Returns a small component that wraps with a typed enum and abaked-in map. Eliminates the per-core boilerplate ofdefining a wrapper component just to pair an enum with a label/varianttable.
* example: |
  Optionally accept an unknown status (e.g. legacy data, late-bound enumwidening) by adding it to the config under a sentinel key — will fall through to the raw status label when the key is missing.
* score: 4

### function deepEqual

* file: src/shared/lib/utils/deepEqual.ts:10
* kind: function
* core: shared
* spec: (none)
* summary: Performs a deep equality check between two values.Unlike JSON.stringify comparison, this handles different key orderings.
* score: 4

### function derivePriority

* file: src/shared/lib/gr/buildQIDraftFromGap.ts:67
* kind: function
* core: shared
* spec: (none)
* summary: Derive priority from gap signal.- overdue 0 → high- completion\_rate\_pct 60 → medium- else → low
* score: 4

### function detectPotentialPHI

* file: src/shared/lib/phi-detection.ts:40
* kind: function
* core: shared
* spec: (none)
* summary: Quick client-side check for obvious PHI/PII patterns in text.
* params:
  * text — The text to scan for potential PHI/PII.
* returns: A warning message if potential PHI is detected, otherwise.
* score: 4

### function domainStatusToIconTone

* file: src/shared/lib/semantic-colors.ts:181
* kind: function
* core: shared
* spec: (none)
* summary: Resolve a domain status string to an .Accepts the canonical keys above as well as common variants(, , ) so callers can pass DB enumsverbatim. Unknown keys return to keep the UI safe.
* score: 4

### function evaluateFederalBaseline

* file: src/shared/lib/state-compliance/federal-baseline.ts:52
* kind: function
* core: shared
* spec: (none)
* summary: Evaluates whether weakens .Returns if all overlapping fields are at-least-as-strict; otherwisereturns an array of violations with the offending field, baseline, and proposed value.Fields present on the baseline but absent on the recommendation are treated as"not changed" (no violation). Fields present only on the recommendation are ignored(additive/non-baselined).
* score: 4

### function formatCurrency

* file: src/shared/lib/format/index.ts:45
* kind: function
* core: shared
* spec: (none)
* summary: Format a numeric value as currency.
* example: |
  formatCurrency(1234.5)                      // "\$1,234.50"formatCurrency(1234.5,  currency: 'EUR' ) // "€1,234.50"formatCurrency(null)                        // "—"
* score: 4

### function formatDate

* file: src/shared/lib/format/index.ts:85
* kind: function
* core: shared
* spec: (none)
* summary: Format a date with a stable default pattern () and optionalIANA time zone. Returns for nullish or invalid input.
* example: |
  formatDate(new Date('2026-01-15')) // "Jan 15, 2026"formatDate('2026-01-15T13:00:00Z',  pattern: 'PP p', timeZone: 'America/Phoenix' )
* score: 4

### function formatDateIso

* file: src/shared/lib/format/index.ts:108
* kind: function
* core: shared
* spec: (none)
* summary: Format a date as a short ISO calendar date (). Useful forinput\[type="date"] values, audit logs, and CSV export.
* score: 4

### function formatDateTime

* file: src/shared/lib/format/index.ts:115
* kind: function
* core: shared
* spec: (none)
* summary: Format a date with time, e.g. .
* score: 4

### function formatNumber

* file: src/shared/lib/format/index.ts:135
* kind: function
* core: shared
* spec: (none)
* summary: Format a number with locale-aware thousand separators.
* example: |
  formatNumber(12345.678)                            // "12,346"formatNumber(12345.678,  maximumFractionDigits: 2 ) // "12,345.68"
* score: 4

### function formatPercent

* file: src/shared/lib/format/index.ts:155
* kind: function
* core: shared
* spec: (none)
* summary: Format a number as a percent. Default matches percent style — pass if your value is already in 0-100 space.
* example: |
  formatPercent(0.4567)                            // "46%"formatPercent(45.67,  source: 'percent' )       // "46%"formatPercent(0.4567,  maximumFractionDigits: 2 ) // "45.67%"
* score: 4

### function getCanonicalVariant

* file: src/shared/lib/status-variants.ts:57
* kind: function
* core: shared
* spec: (none)
* summary: Returns the canonical Badge variant for a given status string.Lookup is case-insensitive. Falls back to 'secondary' for unknown statuses.
* score: 4

### function getDiffColors

* file: src/shared/lib/semantic-colors.ts:287
* kind: function
* core: shared
* spec: (none)
* summary: Provides get diff colors functionality.
* score: 4

### function getInitials

* file: src/shared/lib/utils/format-initials.ts:8
* kind: function
* core: shared
* spec: (none)
* summary: Get initials from a name string
* params:
  * name — The full name to extract initials from
* returns: Up to 2 uppercase letters, or '?' if name is falsy
* score: 4

### function getLoadDiagnostic

* file: src/shared/lib/lazy-retry.ts:62
* kind: function
* core: shared
* spec: (none)
* summary: Returns the most recent failed-load diagnostic for a chunk, if any.
* score: 4

### function getModifierKey

* file: src/shared/lib/utils/platform.ts:62
* kind: function
* core: shared
* spec: (none)
* summary: Get the command/control modifier key based on platformReturns true if the platform-appropriate modifier key is pressed
* params:
  * event — Keyboard event to check
* returns: true if Cmd (Mac) or Ctrl (Windows/Linux) is pressed
* score: 4

### function getPlatformName

* file: src/shared/lib/utils/platform.ts:45
* kind: function
* core: shared
* spec: (none)
* summary: Get the current platform nameReturns 'unknown' if platform cannot be determined
* score: 4

### function getRecommendationColors

* file: src/shared/lib/semantic-colors.ts:229
* kind: function
* core: shared
* spec: (none)
* summary: Provides get recommendation colors functionality.
* score: 4

### function getScoreColor

* file: src/shared/lib/semantic-colors.ts:239
* kind: function
* core: shared
* spec: (none)
* summary: Score-Based Color UtilitiesFor numeric scores on a 1-10 scale (e.g., GWC assessments, goal reviews).= 70% = success, = 40% = warning, 40% = destructive
* score: 4

### function getScoreColorClasses

* file: src/shared/lib/semantic-colors.ts:249
* kind: function
* core: shared
* spec: (none)
* summary: Provides get score color classes functionality.
* score: 4

### function getStatusColors

* file: src/shared/lib/semantic-colors.ts:66
* kind: function
* core: shared
* spec: (none)
* summary: Provides get status colors functionality.
* score: 4

### function hasProperty

* file: src/shared/lib/recharts-types.ts:37
* kind: function
* core: shared
* spec: (none)
* summary: Type guard to check if a value has a specific property
* score: 4

### function installRechartsReducedMotion

* file: src/shared/lib/a11y/recharts-motion.ts:58
* kind: function
* core: shared
* spec: (none)
* summary: Idempotent. Call once at app startup (before React renders charts).
* score: 4

### function isBehavioralHealthServiceType

* file: src/shared/lib/pm/service-type-mapper.ts:55
* kind: function
* core: shared
* spec: (none)
* summary: Determine whether a service type is behavioral-health relevant.
* score: 4

### function isDefined

* file: src/shared/lib/utils/type-utils.ts:159
* kind: function
* core: shared
* spec: (none)
* summary: Type guard to check if a value is not null or undefined.Useful in array filter operations.
* example: |
  const items = \[1, null, 2, undefined, 3].filter(isDefined);// items is now number\[] with value \[1, 2, 3]
* score: 4

### function isIOS

* file: src/shared/lib/utils/platform.ts:35
* kind: function
* core: shared
* spec: (none)
* summary: Check if the current platform is iOSHandles iPad masquerading as Mac in Safari
* score: 4

### function isMacOS

* file: src/shared/lib/utils/platform.ts:19
* kind: function
* core: shared
* spec: (none)
* summary: Check if the current platform is macOSUses modern userAgentData API when available (Chrome 90+, Edge 90+)
* score: 4

### function isValidEnum

* file: src/shared/lib/utils/type-utils.ts:127
* kind: function
* core: shared
* spec: (none)
* summary: Type-safe check if a value is a valid enum member.
* params:
  * value — Value to check
  * enumValues — Array of valid enum values
* returns: Type predicate indicating if value is a valid enum member
* example: |
  const STATUSES = \['draft', 'active', 'archived'] as const;if (isValidEnum(status, STATUSES))   // status is now typed as 'draft' | 'active' | 'archived'
* score: 4

### function isValidUUID

* file: src/shared/lib/validation/isValidUUID.ts:6
* kind: function
* core: shared
* spec: (none)
* summary: Returns true when the input is a valid RFC4122 UUID string.
* score: 4

### function iterateBannerCsv

* file: src/shared/lib/weno/csv.ts:36
* kind: function
* core: shared
* spec: (none)
* summary: Iterate a banner+header CSV: skip lines until isHeaderRow(cells) is true,then yield header-keyed rows. Lines that match isHeaderRow are treated as(re-)headers and never yielded as data — calling onHeaders each time theyappear. This allows drift detection when a vendor appends new columns.
* score: 4

### function lazyRetry

* file: src/shared/lib/lazy-retry.ts:111
* kind: function
* core: shared
* spec: (none)
* summary: Creates a lazy component that retries failed dynamic imports.
* params:
  * importFn — The dynamic import function.
  * maxRetries — Maximum number of retry attempts (default 3).
  * chunkName — Optional name used to record/observe load diagnostics.
* score: 4

### function lengthMessage

* file: src/shared/lib/validation/error-messages.ts:87
* kind: function
* core: shared
* spec: (none)
* summary: Creates a min/max length message
* score: 4

### function mapProcedureCategoryToQI

* file: src/shared/lib/gr/buildQIDraftFromGap.ts:85
* kind: function
* core: shared
* spec: (none)
* summary: Map a value to a value. allows: clinical | operational | safety | hr | financial | it | emergency | other allows: clinical | operational | safety | compliance | outcomesMapping rules (preserves clinical/safety semantics, defaults everything else to operational):- clinical → clinical- safety, emergency → safety- operational, hr, financial, it, other, '', unknown → operational
* score: 4

### function mapServiceTypeCode

* file: src/shared/lib/pm/service-type-mapper.ts:42
* kind: function
* core: shared
* spec: (none)
* summary: Resolve a service type code to a mapping. Unknown codes return apass-through mapping with category 'other'.
* score: 4

### function markRoutePrewarmComplete

* file: src/shared/lib/dev/routePrewarmSignal.ts:51
* kind: function
* core: shared
* spec: (none)
* summary: Mark the prewarm complete. No-op in production.
* score: 4

### function normalizeSelectValue

* file: src/shared/lib/select-utils.ts:15
* kind: function
* core: shared
* spec: (none)
* summary: Converts SELECT\_NONE\_VALUE back to an empty string for use in form state or filters.
* score: 4

### function nullish

* file: src/shared/lib/utils/type-utils.ts:63
* kind: function
* core: shared
* spec: (none)
* summary: Converts null to undefined for a single value.Useful for individual field conversions.
* params:
  * value — Value that may be null
* returns: The value with null converted to undefined
* example: |
  const dbValue: string | null = null;const formValue = nullish(dbValue); // undefined
* score: 4

### function nullToUndefined

* file: src/shared/lib/utils/type-utils.ts:44
* kind: function
* core: shared
* spec: (none)
* summary: Converts all null values in an object to undefined.Useful for converting Supabase responses to form-compatible objects.
* params:
  * obj — Object with potential null values
* returns: Object with null values converted to undefined, or undefined if input is null/undefined
* example: |
  const dbRow =  name: 'John', email: null ;const formData = nullToUndefined(dbRow);// Result:  name: 'John', email: undefined
* score: 4

### function optionsToMultilineText

* file: src/shared/lib/forms/fieldEditorUtils.ts:67
* kind: function
* core: shared
* spec: none
* summary: Serializes a heterogeneous form-builder options array back into thenewline-separated text representation used by the textarea editor. Acceptsthe loose shape that ships through the form-builder state machine(strings, objects, or junk) and returns one label perline, skipping empty labels. Returns for non-array input.
* params:
  * options — The current options array (typically , but to tolerate partially-typed editor state and legacy data).
* returns: A newline-separated label string suitable for placing back intothe textarea control; pairs with for a round trip.
* score: 5

### function parse271Benefits

* file: src/shared/lib/pm/benefit-parser.ts:98
* kind: function
* core: shared
* spec: (none)
* summary: Group raw EB segments by (service\_type\_code, network\_tier) and produce onenormalized benefit detail per group.
* score: 4

### function parseJsonArray

* file: src/shared/lib/utils/type-utils.ts:93
* kind: function
* core: shared
* spec: (none)
* summary: Safely parses a JSONB array field.Returns empty array if the field is null, undefined, or not an array.
* params:
  * value — JSONB value expected to be an array
* returns: Typed array or empty array
* example: |
  const lines = parseJsonArrayJournalLine(data.template\_lines);
* score: 4

### function parseJsonField

* file: src/shared/lib/utils/type-utils.ts:78
* kind: function
* core: shared
* spec: (none)
* summary: Safely parses a JSONB field with type assertion.Returns a default value if the field is null, undefined, or not the expected type.
* params:
  * value — JSONB value from database (typed as unknown or Json)
  * defaultValue — Default value to return if parsing fails
* returns: Typed value or default
* example: |
  const settings = parseJsonFieldWorkflowSettings(data.settings,  autoSave: true );
* score: 4

### function parseJsonObject

* file: src/shared/lib/utils/type-utils.ts:108
* kind: function
* core: shared
* spec: (none)
* summary: Safely parses a JSONB object field.Returns undefined if the field is null, undefined, or not an object.
* params:
  * value — JSONB value expected to be an object
* returns: Typed object or undefined
* example: |
  const config = parseJsonObjectEventConfig(rule.event\_config);
* score: 4

### function parseOptionsFromText

* file: src/shared/lib/forms/fieldEditorUtils.ts:43
* kind: function
* core: shared
* spec: (none)
* summary: Provides parse options from text functionality.
* score: 4

### function prefersReducedMotion

* file: src/shared/lib/a11y/scroll.ts:12
* kind: function
* core: shared
* spec: (none)
* summary: Sync read of the OS reduced-motion preference. SSR-safe.
* score: 4

### function rangeMessage

* file: src/shared/lib/validation/error-messages.ts:106
* kind: function
* core: shared
* spec: (none)
* summary: Creates a range message for numeric fields
* score: 4

### function requiredMessage

* file: src/shared/lib/validation/error-messages.ts:80
* kind: function
* core: shared
* spec: (none)
* summary: Creates a custom required message for a specific field
* score: 4

### function RouterPendingTracker

* file: src/shared/components/GlobalQueryProgress.tsx:67
* kind: function
* core: shared
* spec: (none)
* summary: Mount inside to feed router/navigation transitionsinto . Renders nothing.
* score: 4

### function safeAccess

* file: src/shared/lib/utils/type-utils.ts:174
* kind: function
* core: shared
* spec: (none)
* summary: Safely access a nested property that may be null.Alternative to optional chaining when you need the result to be undefined.
* params:
  * value — Value that may be null
  * accessor — Function to access nested property
* returns: Property value or undefined
* example: |
  const name = safeAccess(employee.department, d = d.name);
* score: 4

### function safeScrollBehavior

* file: src/shared/lib/a11y/scroll.ts:20
* kind: function
* core: shared
* spec: (none)
* summary: Returns 'auto' when reduced motion is preferred, otherwise 'smooth'.
* score: 4

### function safeScrollBy

* file: src/shared/lib/a11y/scroll.ts:38
* kind: function
* core: shared
* spec: (none)
* summary: scrollBy wrapper for elements (used by ScrollableTabsList nudge buttons).
* score: 4

### function safeScrollIntoView

* file: src/shared/lib/a11y/scroll.ts:25
* kind: function
* core: shared
* spec: (none)
* summary: scrollIntoView wrapper that downgrades smooth scrolling under reduced-motion.
* score: 4

### function safeScrollTo

* file: src/shared/lib/a11y/scroll.ts:32
* kind: function
* core: shared
* spec: (none)
* summary: scrollTo wrapper for window or element.
* score: 4

### function sanitizeErrorMessage

* file: src/shared/lib/error-utils.ts:27
* kind: function
* core: shared
* spec: (none)
* summary: Sanitizes an error message to prevent leaking internal details to users.
* params:
  * error — Error object, Error instance, or string message
* returns: User-friendly error message
* score: 4

### function sanitizeHtml

* file: src/shared/lib/utils/sanitize.ts:11
* kind: function
* core: shared
* spec: (none)
* summary: Sanitize HTML content to prevent XSS attacksUses DOMPurify with a safe configuration for rich text content
* score: 4

### function scanRegulatoryChangeLogPayloadForPhiCategories

* file: src/shared/lib/regulatory-change-log-phi.ts:60
* kind: function
* core: shared
* spec: (none)
* summary: Categories for a regulatory change log payload (convenience).
* score: 4

### function scanRegulatoryChangeLogTextForPhiCategories

* file: src/shared/lib/regulatory-change-log-phi.ts:44
* kind: function
* core: shared
* spec: (none)
* summary: Returns heuristic category labels when text matches (no raw PHI returned).
* score: 4

### function scrollToQuickActions

* file: src/shared/components/scrollToQuickActions.ts:21
* kind: function
* core: shared
* spec: (none)
* summary: Convenience helper for the optional Quick Actions anchor scroll behavior.Robust against: - The app's real scroll container being an inner (not ) when the responsive shell mounts the mobile layout. - The Quick Actions section not yet existing when the user taps the tile (auth gate still resolving, Suspense chunk still loading, dashboard widgets streaming in). We poll briefly via MutationObserver + rAF and only give up after \~3s so a delayed render still snaps to the section. - Reduced-motion users: we fall back to instant scroll. - Focus management: we move focus to the first focusable child of the section *after* the scroll settles so screen-reader users land there.
* score: 4

### function ScrollToTop

* file: src/shared/components/ScrollToTop.tsx:47
* kind: function
* core: shared
* spec: none
* summary: Mount-once route observer that resets , , ,and every container to the top whenever the pathnameor search string changes. Skips reset when the URL includes a hash (soin-page anchors still work) and runs both synchronously via and again on the next animation frame to catch routeswhose content paints late (Suspense / lazy chunks). Returns — renderonce at the top of the router subtree.
* returns: Always (this component renders no DOM).
* example: |
  BrowserRouter  ScrollToTop /  Routes.../Routes/BrowserRouter
* score: 5

### function semanticStatusToIconTone

* file: src/shared/lib/semantic-colors.ts:76
* kind: function
* core: shared
* spec: (none)
* summary: Map a to an for use with .Identity today — kept as a function so future divergence (e.g. a new value that needs a different tone) is a single edit.
* score: 4

### function splitCsvLine

* file: src/shared/lib/weno/csv.ts:10
* kind: function
* core: shared
* spec: (none)
* summary: Quote-aware CSV line splitter ("" escapes, quoted commas). Trims each cell.
* score: 4

### function subscribeLoadDiagnostic

* file: src/shared/lib/lazy-retry.ts:67
* kind: function
* core: shared
* spec: (none)
* summary: Subscribe to diagnostic changes for a chunk. Returns an unsubscribe fn.
* score: 4

### function timingSafeEqualHex

* file: src/shared/lib/checkr-signature.ts:43
* kind: function
* core: shared
* spec: (none)
* summary: Constant-time hex-string comparison. Returns only when both inputs have identical length ANDidentical content, performing the equality check in constant time relativeto the longer input to avoid leaking length information.
* params:
  * a — First hex string to compare.
  * b — Second hex string to compare.
* returns: if both strings are equal, otherwise.
* score: 4

### function toEnum

* file: src/shared/lib/utils/type-utils.ts:144
* kind: function
* core: shared
* spec: (none)
* summary: Coerces a database string to a TypeScript enum with fallback.Use when you need to guarantee a valid enum value.
* params:
  * value — Database value (may be null or invalid)
  * enumValues — Array of valid enum values
  * fallback — Default value if coercion fails
* returns: Valid enum value
* example: |
  const STATUSES = \['draft', 'active', 'archived'] as const;const status = toEnum(invoice.status, STATUSES, 'draft');
* score: 4

### function toError

* file: src/shared/lib/error-utils.ts:138
* kind: function
* core: shared
* spec: (none)
* summary: Coerces an unknown thrown value into a real instance.Supabase/PostgREST surface errors as plain objects carrying a field(plus , , ), not instances. Throwing thosedirectly trips the typed-lint rule — it breaks stack tracesand Sentry grouping. Use this at sites that propagate a Supabase error:The original value is preserved on , so structured fields (e.g. thePostgREST ) remain reachable to error handlers via .Anything already an is returned unchanged. User-facing display muststill go through .
* params:
  * value — The caught/returned error value of unknown shape
* returns: An whose message mirrors the source and whose is the original value
* score: 4

### function toSnakeCaseKey

* file: src/shared/lib/forms/fieldEditorUtils.ts:20
* kind: function
* core: shared
* spec: none
* summary: Normalizes an arbitrary string into a identifier suitable foruse as a form-field key or column name: trims whitespace, lowercases,collapses every non-alphanumeric run to a single underscore, and stripsleading / trailing / repeated underscores. Returns an empty string when theinput contains no alphanumerics.
* params:
  * input — Free-form label or identifier candidate; any value isaccepted but only runs survive in the output.
* returns: The snake\_cased identifier (e.g. → ).
* score: 5

### function undefinedToNull

* file: src/shared/lib/utils/type-utils.ts:186
* kind: function
* core: shared
* spec: (none)
* summary: Converts undefined to null for database writes.Inverse of nullToUndefined - use when sending data TO database.
* params:
  * obj — Object with potential undefined values
* returns: Object with undefined values converted to null
* score: 4

### function waitForRoutePrewarm

* file: src/shared/lib/dev/routePrewarmSignal.ts:72
* kind: function
* core: shared
* spec: (none)
* summary: Returns the prewarm-ready promise (resolves immediately in production).Browser tests can .
* score: 4

### function withAtLeastOne

* file: src/shared/lib/validation/schema-builders.ts:172
* kind: function
* core: shared
* spec: (none)
* summary: Adds at-least-one-required validation
* score: 4

### function withAuditFields

* file: src/shared/lib/validation/schema-builders.ts:28
* kind: function
* core: shared
* spec: (none)
* summary: Adds audit fields (created\_at, updated\_at, created\_by, updated\_by)
* score: 4

### function withConditionalRequired

* file: src/shared/lib/validation/schema-builders.ts:122
* kind: function
* core: shared
* spec: (none)
* summary: Adds conditional required field validation
* score: 4

### function withCustomFields

* file: src/shared/lib/validation/schema-builders.ts:40
* kind: function
* core: shared
* spec: (none)
* summary: Adds custom\_fields JSON column
* score: 4

### function withDateRangeValidation

* file: src/shared/lib/validation/schema-builders.ts:90
* kind: function
* core: shared
* spec: (none)
* summary: Adds date range validation (end date must be = start date)
* score: 4

### function withId

* file: src/shared/lib/validation/schema-builders.ts:70
* kind: function
* core: shared
* spec: none
* summary: Extends a Zod object schema with an field for entities thatalready exist in the database (read / update payloads). Pairs with / which intentionally omit on create paths so the database can mint it.
* params:
  * schema — Any whose raw shape will be extended with the field; the generic preserves the inferred input shape .
* returns: The same schema augmented with a required (UUID v4) property.
* example: |
  const ResidentRowSchema = withId(ResidentBaseSchema);type ResidentRow = z.infertypeof ResidentRowSchema; // includes
* score: 5

### function withMutuallyExclusive

* file: src/shared/lib/validation/schema-builders.ts:148
* kind: function
* core: shared
* spec: (none)
* summary: Adds mutual exclusivity validation (only one of the fields can be set)
* score: 4

### function withOrganization

* file: src/shared/lib/validation/schema-builders.ts:19
* kind: function
* core: shared
* spec: (none)
* summary: Adds organization\_id field to a schema (required for multi-tenant entities)
* score: 4

### function withSoftDelete

* file: src/shared/lib/validation/schema-builders.ts:49
* kind: function
* core: shared
* spec: (none)
* summary: Adds soft delete field (deleted\_at)
* score: 4

### function withStandardFields

* file: src/shared/lib/validation/schema-builders.ts:79
* kind: function
* core: shared
* spec: (none)
* summary: Combines multiple common extensions (org, audit, custom fields)
* score: 4