@startsimpli/ui 0.4.95 → 0.4.97

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.95",
+  "version": "0.4.97",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -46,7 +46,7 @@
     "react-dom": "^18.0.0 || ^19.0.0",
     "@startsimpli/api": "^0.5.54",
     "@startsimpli/auth": "^0.4.35",
-    "@startsimpli/i18n": "^0.1.1"
+    "@startsimpli/i18n": "^0.1.2"
   },
   "peerDependenciesMeta": {
     "@startsimpli/api": {
@@ -67,6 +67,9 @@
   },
   "dependencies": {
     "@hello-pangea/dnd": "^18.0.1",
+    "@types/dagre": "^0.7.52",
+    "@types/react-big-calendar": "^1.16.3",
+    "@types/react-syntax-highlighter": "^15.5.13",
     "@xterm/addon-fit": "^0.10.0",
     "@xyflow/react": "^12.10.2",
     "dagre": "^0.8.5",
@@ -107,12 +110,9 @@
     "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.1",
     "@types/jest": "^30.0.0",
-    "@types/dagre": "^0.7.52",
     "@types/node": "^20.19.39",
     "@types/react": "^19.2.14",
-    "@types/react-big-calendar": "^1.16.3",
     "@types/react-dom": "^19.2.3",
-    "@types/react-syntax-highlighter": "^15.5.13",
     "eslint": "^8.57.1",
     "identity-obj-proxy": "^3.0.0",
     "jest": "^30.3.0",
@@ -120,8 +120,8 @@
     "tailwindcss": "^3.4.19",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "@startsimpli/realtime": "0.0.2",
-    "@startsimpli/i18n": "0.1.1"
+    "@startsimpli/i18n": "0.1.2",
+    "@startsimpli/realtime": "0.0.2"
   },
   "keywords": [
     "ui",

package/src/__tests__/shipped-types.test.ts

@@ -0,0 +1,80 @@
+/**
+ * Package-wide guard: types needed to COMPILE shipped source are runtime deps
+ * (startsim-lglc).
+ *
+ * This package publishes TypeScript SOURCE — `exports` points at `./src/*.ts`
+ * and `files` ships `src`. So a consumer's `tsc` does not read a built `.d.ts`
+ * from us; it compiles our `.tsx` files inside their `node_modules`. Two
+ * consequences that make the usual "types are a dev concern" split wrong here:
+ *
+ *  1. `skipLibCheck` does not save anyone. Every Next app sets it, and it would
+ *     hide a bad type in a shipped `.d.ts` — but it only skips `.d.ts` files,
+ *     and ours are `.tsx`. Our type errors land in the consumer's build.
+ *  2. Anything our source needs in order to type-check is, by definition, part
+ *     of what we ship. If `@types/x` lives in devDependencies, the consumer
+ *     installs `x` (a real dependency) without its types and gets TS7016
+ *     'implicitly has an any type' pointing inside node_modules/@startsimpli/ui
+ *     — an error in OUR code that they cannot fix.
+ *
+ * That was not hypothetical: every consumer's type-check was permanently
+ * one-error-dirty on `react-big-calendar`, so a real regression could hide in
+ * the noise. `dagre` (via `@startsimpli/ui/workflows`) and
+ * `react-syntax-highlighter` (via `@startsimpli/ui/blog`) were the same bug,
+ * latent behind entry points that consumer happened not to import.
+ *
+ * The rule: if `x` is a runtime dependency and we declare `@types/x` at all,
+ * `@types/x` belongs in `dependencies` too. Types for a PEER dependency (react,
+ * react-dom) stay in devDependencies — the consumer supplies those and their
+ * types. Types for tooling (node, jest) stay in devDependencies — no shipped
+ * source imports them.
+ */
+
+import * as fs from 'fs'
+import * as path from 'path'
+
+const PKG = JSON.parse(
+  fs.readFileSync(path.resolve(__dirname, '../../package.json'), 'utf8'),
+) as {
+  dependencies: Record<string, string>
+  devDependencies: Record<string, string>
+  peerDependencies: Record<string, string>
+}
+
+/** `@types/react-dom` -> `react-dom`; `@types/scope__pkg` -> `@scope/pkg`. */
+function runtimeNameFor(typesPkg: string): string {
+  const stem = typesPkg.slice('@types/'.length)
+  return stem.includes('__') ? `@${stem.replace('__', '/')}` : stem
+}
+
+describe('types needed to compile shipped source ship with it', () => {
+  it('every @types for a runtime dependency is itself a runtime dependency', () => {
+    const misplaced = Object.keys(PKG.devDependencies)
+      .filter((name) => name.startsWith('@types/'))
+      .filter((name) => PKG.dependencies[runtimeNameFor(name)] !== undefined)
+
+    expect(misplaced).toEqual([])
+  })
+
+  it('the untyped runtime deps our source imports carry their types', () => {
+    // These three packages ship no declarations of their own, and shipped
+    // source imports all three. Without these entries a consumer's tsc reports
+    // TS7016 inside node_modules/@startsimpli/ui.
+    for (const types of [
+      '@types/dagre',
+      '@types/react-big-calendar',
+      '@types/react-syntax-highlighter',
+    ]) {
+      expect(PKG.dependencies[types]).toBeDefined()
+      expect(PKG.devDependencies[types]).toBeUndefined()
+    }
+  })
+
+  it('types for peer dependencies stay a dev concern', () => {
+    // The consumer owns react/react-dom, so it owns their types. Shipping these
+    // would risk a second, conflicting copy of the React types in their build.
+    for (const types of ['@types/react', '@types/react-dom']) {
+      expect(PKG.devDependencies[types]).toBeDefined()
+      expect(PKG.dependencies[types]).toBeUndefined()
+    }
+  })
+})

package/src/components/dashboard/DeltaPill.tsx

@@ -1,5 +1,6 @@
 import * as React from 'react'
 import { cn } from '../../lib/utils'
+import { Numeral } from './Numeral'
 
 export type DeltaDirection = 'up' | 'down' | 'neutral'
 
@@ -112,7 +113,10 @@ export function DeltaPill({
     >
       <DirectionArrow direction={resolved} />
       <span className="sr-only">{DIRECTION_WORD[resolved]}</span>
-      <span className="tabular-nums">{text}</span>
+      {/* The pill itself is free to mirror — in RTL the arrow belongs on the
+          start side like any other leading icon. Only the figure is pinned,
+          because `+2.8%` must not become `%2.8+`. */}
+      <Numeral>{text}</Numeral>
       {label ? <span className="opacity-80">{label}</span> : null}
     </span>
   )

package/src/components/dashboard/DonutChart.tsx

@@ -1,5 +1,6 @@
 import * as React from 'react'
 import { cn } from '../../lib/utils'
+import { Numeral } from './Numeral'
 
 export interface DonutSegment {
   label: string
@@ -158,9 +159,9 @@ export function DonutChart({
         {hasCenter && (
           <div className="pointer-events-none absolute inset-0 flex flex-col items-center justify-center px-3 text-center">
             {centerValue !== undefined && (
-              <span className="text-xl font-semibold tabular-nums tracking-tight text-foreground">
+              <Numeral className="text-xl font-semibold tracking-tight text-foreground">
                 {centerValue}
-              </span>
+              </Numeral>
             )}
             {centerLabel !== undefined && (
               <span className="mt-0.5 text-xs text-muted-foreground">
@@ -203,9 +204,11 @@ export function DonutChart({
                   {segment.label}
                 </span>
               </span>
-              <span className="shrink-0 font-medium tabular-nums text-foreground">
+              {/* `formatLegendValue` is where a consumer adds a currency symbol
+                  or a '%', so the formatted result is exactly what needs pinning. */}
+              <Numeral className="shrink-0 font-medium text-foreground">
                 {formatLegendValue ? formatLegendValue(segment) : segment.value}
-              </span>
+              </Numeral>
             </li>
           ))}
         </ul>

package/src/components/dashboard/MetricCard.tsx

@@ -1,5 +1,6 @@
 import * as React from 'react'
 import { cn } from '../../lib/utils'
+import { Numeral } from './Numeral'
 import { SparklineTrend } from './SparklineTrend'
 
 export interface MetricCardTrend {
@@ -57,7 +58,15 @@ export function MetricCard({
         {/* Value */}
         <div className="flex items-baseline justify-between">
           <p className="text-3xl font-bold text-gray-900">
-            {isLoading ? '\u2014' : error ? 'Error' : value}
+            {/* 'Error' is prose and follows the document; only the figure is
+                pinned, and the placeholder dash is neutral either way. */}
+            {isLoading ? (
+              '\u2014'
+            ) : error ? (
+              'Error'
+            ) : (
+              <Numeral>{value}</Numeral>
+            )}
           </p>
 
           {/* Trend Indicator */}
@@ -124,9 +133,10 @@ function TrendIndicator({ trend }: { trend: MetricCardTrend }) {
           <path strokeLinecap="round" strokeLinejoin="round" d="M5 12h14" />
         </svg>
       )}
-      <span>
+      {/* Sign and '%' are both bidi-neutral — unpinned, '+12%' reorders. */}
+      <Numeral>
         {trend.value > 0 ? '+' : ''}{trend.value}%
-      </span>
+      </Numeral>
     </div>
   )
 }

package/src/components/dashboard/Numeral.tsx

@@ -0,0 +1,50 @@
+import * as React from 'react'
+import { cn } from '../../lib/utils'
+
+export interface NumeralProps
+  extends Omit<React.ComponentPropsWithoutRef<'span'>, 'dir'> {
+  children: React.ReactNode
+}
+
+/**
+ * A figure, pinned left-to-right (startsim-768w.35.6).
+ *
+ * Digits are strongly left-to-right in Unicode, so `1,204` survives an RTL
+ * paragraph on its own. The characters that do NOT survive are the ones a
+ * component adds AROUND the digits — the sign in a delta, the `%`, the
+ * parentheses of a secondary figure, a currency symbol. Those are bidi-NEUTRAL:
+ * they take their direction from whatever surrounds them, so in an RTL document
+ * the same `+2.8K (+0.03%)` reorders into `(0.13%+) M1.1+`. The number is not
+ * wrong, the punctuation has migrated around it, which is worse — it still
+ * reads as a number, just a different one.
+ *
+ * A `dir` attribute is the fix, and it is enough: the HTML rendering spec gives
+ * any element carrying `dir` a `unicode-bidi: isolate`, so the span both sets
+ * the direction of its own contents and stops the surrounding paragraph from
+ * reaching in and reordering them.
+ *
+ * This belongs in the COMPONENT, not the call site. The component is the only
+ * thing that knows it is about to emit a sign or a `%`; a caller passing
+ * `value={0.03}` has no reason to suspect it needs to wrap the result. Before
+ * this existed mcr-web hand-wrapped essentially every figure across six artist
+ * screens, and the next app to go RTL would have repeated that sweep — with the
+ * one site everybody misses shipping a plausible, wrong number.
+ *
+ * In an LTR document this renders identically to a bare span: `dir="ltr"`
+ * inside an already-LTR paragraph changes nothing. The isolation is only ever
+ * load-bearing in RTL.
+ *
+ * Exported so consumers can pin figures this package does not render for them —
+ * a currency cell in their own table, a hand-built hero number.
+ *
+ *   <Numeral>{formatCurrency(total)}</Numeral>
+ */
+export function Numeral({ children, className, ...rest }: NumeralProps) {
+  return (
+    // `dir` is written after the spread deliberately: a caller must not be able
+    // to pass dir="rtl" and quietly undo the one guarantee this component makes.
+    <span {...rest} className={cn('tabular-nums', className)} dir="ltr">
+      {children}
+    </span>
+  )
+}

package/src/components/dashboard/PipelineFunnel.tsx

@@ -1,5 +1,6 @@
 import { Card } from '../ui/card';
 import { TrendingDown } from 'lucide-react';
+import { Numeral } from './Numeral';
 
 export interface FunnelStage {
   stage: string;
@@ -69,11 +70,16 @@ export function PipelineFunnel({
                   {stage.stage}
                 </span>
                 <div className="flex items-center gap-3">
+                  {/* Not pinned, deliberately. A bare trailing '%' is a bidi
+                      European Terminator: adjacent to digits it joins their run
+                      (UAX #9 W5), so '42%' survives an RTL paragraph unaided.
+                      Splitting the sentence to wrap it would buy nothing and
+                      break the phrase into fragments. */}
                   <span className="text-xs text-gray-500">
                     {stagePercentage}% of total
                   </span>
                   <span className="text-sm font-bold text-gray-900">
-                    {stage.count.toLocaleString()}
+                    <Numeral>{stage.count.toLocaleString()}</Numeral>
                   </span>
                 </div>
               </div>
@@ -113,7 +119,9 @@ export function PipelineFunnel({
           <div className="flex items-center justify-between text-sm">
             <span className="text-gray-600">Overall Conversion</span>
             <span className="font-bold text-gray-900">
-              {Math.round((stages[stages.length - 1].count / stages[0].count) * 100)}%
+              <Numeral>
+                {Math.round((stages[stages.length - 1].count / stages[0].count) * 100)}%
+              </Numeral>
               <span className="text-xs text-gray-500 ml-1">
                 ({stages[0].stage} → {stages[stages.length - 1].stage})
               </span>

package/src/components/dashboard/StatTile.tsx

@@ -4,6 +4,7 @@ import { Caveat } from '../states/Caveat'
 import { Footnote } from '../states/Footnote'
 import { AreaTrend } from './AreaTrend'
 import { DeltaPill, type DeltaPillProps } from './DeltaPill'
+import { Numeral } from './Numeral'
 
 export type StatTileSize = 'sm' | 'md' | 'lg' | 'xl'
 
@@ -81,13 +82,17 @@ export function StatTile({
       </p>
 
       <div className="mt-2 flex items-center justify-between gap-4">
+        {/* The figure is pinned, the paragraph is not. Putting `dir` on the
+            block would left-align the number in an RTL column; the number has
+            to sit at the column's start like every other tile, and only its
+            own characters need holding in place. */}
         <p
           className={cn(
             'min-w-0 font-semibold tabular-nums tracking-tight text-foreground',
             VALUE_SIZE[size],
           )}
         >
-          {value}
+          <Numeral>{value}</Numeral>
         </p>
 
         {hasSparkline && (

package/src/components/dashboard/TopCampaigns.tsx

@@ -1,6 +1,7 @@
 import { Card } from '../ui/card';
 import { EmptyState } from '../states';
 import { ArrowRight } from 'lucide-react';
+import { Numeral } from './Numeral';
 
 export interface TopCampaign {
   id: string;
@@ -95,7 +96,7 @@ export function TopCampaigns({
                 </div>
 
                 <span className="flex-shrink-0 text-sm font-bold text-gray-900">
-                  {campaign.engagementRate}%
+                  <Numeral>{campaign.engagementRate}%</Numeral>
                 </span>
               </div>
 
@@ -120,9 +121,11 @@ export function TopCampaigns({
           <div className="flex items-center justify-between text-sm">
             <span className="text-gray-600">Average Engagement</span>
             <span className="font-bold text-gray-900">
-              {Math.round(
-                campaigns.reduce((sum, c) => sum + c.engagementRate, 0) / campaigns.length
-              )}%
+              <Numeral>
+                {Math.round(
+                  campaigns.reduce((sum, c) => sum + c.engagementRate, 0) / campaigns.length
+                )}%
+              </Numeral>
             </span>
           </div>
         </div>

package/src/components/dashboard/__tests__/display-primitives.test.tsx

@@ -161,7 +161,10 @@ describe('StatTile', () => {
     expect(container.firstChild).toHaveClass('bg-card')
     expect(container.firstChild).toHaveClass('border-border')
     expect(screen.getByText('A')).toHaveClass('text-muted-foreground')
-    expect(screen.getByText('1')).toHaveClass('text-foreground')
+    // The figure sits in a `Numeral` that pins it left-to-right, so the element
+    // holding the text is that span; the colour token stays on the paragraph
+    // around it and is inherited.
+    expect(screen.getByText('1').parentElement).toHaveClass('text-foreground')
   })
 })
 

package/src/components/dashboard/__tests__/numeral-rtl.test.tsx

@@ -0,0 +1,132 @@
+/**
+ * Numeric primitives carry their own direction (startsim-768w.35.6).
+ *
+ * jsdom does not run the Unicode bidi algorithm, so no unit test can prove that
+ * `+2.8K (+0.03%)` renders correctly in an RTL browser — that claim is settled
+ * by driving a real page. What these tests DO pin down is the contract a
+ * browser needs in order to get it right: the figure, and only the figure, is
+ * marked `dir="ltr"`, in every primitive that composes one.
+ */
+
+import { render, screen } from '@testing-library/react'
+import { DeltaPill } from '../DeltaPill'
+import { DonutChart } from '../DonutChart'
+import { MetricCard } from '../MetricCard'
+import { Numeral } from '../Numeral'
+import { StatTile } from '../StatTile'
+
+/** Renders inside an RTL document, the way a localized app would. */
+function renderRtl(ui: React.ReactElement) {
+  return render(ui, {
+    container: document.body.appendChild(
+      Object.assign(document.createElement('div'), { dir: 'rtl' }),
+    ),
+  })
+}
+
+const Icon = ({ className }: { className?: string }) => (
+  <svg className={className} />
+)
+
+describe('Numeral', () => {
+  it('pins its contents left-to-right', () => {
+    render(<Numeral>1,204</Numeral>)
+    expect(screen.getByText('1,204')).toHaveAttribute('dir', 'ltr')
+  })
+
+  it('cannot be talked out of it', () => {
+    // A caller spreading props must not be able to undo the one guarantee.
+    render(<Numeral {...({ dir: 'rtl' } as object)}>1,204</Numeral>)
+    expect(screen.getByText('1,204')).toHaveAttribute('dir', 'ltr')
+  })
+
+  it('keeps figures tabular by default and takes extra classes', () => {
+    render(<Numeral className="text-foreground">99</Numeral>)
+    const figure = screen.getByText('99')
+    expect(figure).toHaveClass('tabular-nums')
+    expect(figure).toHaveClass('text-foreground')
+  })
+})
+
+describe('DeltaPill pins the figure it signs', () => {
+  it('marks the signed value, in an RTL document', () => {
+    renderRtl(<DeltaPill value={2.8} />)
+    // The leading '+' is the hazard: bidi-neutral, so unpinned it migrates.
+    expect(screen.getByText('+2.8%')).toHaveAttribute('dir', 'ltr')
+  })
+
+  it('leaves the trailing label to follow the document', () => {
+    renderRtl(<DeltaPill value={-1.2} label="vs last month" />)
+    expect(screen.getByText('-1.2%')).toHaveAttribute('dir', 'ltr')
+    // Prose is prose — it should mirror with everything else on the page.
+    expect(screen.getByText('vs last month')).not.toHaveAttribute('dir')
+  })
+
+  it('renders identically in an LTR document', () => {
+    const { container: ltr } = render(<DeltaPill value={2.8} />)
+    const { container: rtl } = renderRtl(<DeltaPill value={2.8} />)
+    expect(ltr.textContent).toBe(rtl.textContent)
+  })
+})
+
+describe('StatTile pins its headline figure', () => {
+  it('marks the value without pinning the block around it', () => {
+    renderRtl(<StatTile label="Monthly listeners" value="1.1M" />)
+    const figure = screen.getByText('1.1M')
+    expect(figure).toHaveAttribute('dir', 'ltr')
+    // The paragraph must stay unpinned or the number would left-align in an
+    // RTL column instead of sitting at the column's start.
+    expect(figure.parentElement).not.toHaveAttribute('dir')
+  })
+
+  it('pins a currency figure the caller pre-formatted', () => {
+    renderRtl(<StatTile label="Revenue" value="$12,340" />)
+    expect(screen.getByText('$12,340')).toHaveAttribute('dir', 'ltr')
+  })
+
+  it('pins the delta it renders for you', () => {
+    renderRtl(
+      <StatTile label="Streams" value="2.4M" delta={{ value: 0.03 }} />,
+    )
+    expect(screen.getByText('+0.03%')).toHaveAttribute('dir', 'ltr')
+  })
+})
+
+describe('MetricCard pins value and trend', () => {
+  it('marks both figures', () => {
+    renderRtl(
+      <MetricCard
+        label="Followers"
+        value="18,402"
+        icon={Icon}
+        trend={{ value: 12, isPositive: true }}
+      />,
+    )
+    expect(screen.getByText('18,402')).toHaveAttribute('dir', 'ltr')
+    expect(screen.getByText('+12%')).toHaveAttribute('dir', 'ltr')
+  })
+
+  it('does not pin the error placeholder, which is prose', () => {
+    renderRtl(<MetricCard label="Followers" value="0" icon={Icon} error />)
+    expect(screen.getByText('Error')).not.toHaveAttribute('dir')
+  })
+})
+
+describe('DonutChart pins the figures it prints', () => {
+  it('marks the centre value and the legend figures', () => {
+    renderRtl(
+      <DonutChart
+        segments={[
+          { label: 'Spotify', value: 60 },
+          { label: 'Apple', value: 40 },
+        ]}
+        centerValue="$1.2M"
+        showLegend
+        formatLegendValue={(s) => `$${s.value}`}
+      />,
+    )
+    expect(screen.getByText('$1.2M')).toHaveAttribute('dir', 'ltr')
+    expect(screen.getByText('$60')).toHaveAttribute('dir', 'ltr')
+    expect(screen.getByText('$40')).toHaveAttribute('dir', 'ltr')
+  })
+})

package/src/components/dashboard/index.ts

@@ -25,6 +25,9 @@ export type { StatTileProps, StatTileSize } from './StatTile'
 export { DeltaPill, resolveDeltaDirection, DELTA_UNAVAILABLE } from './DeltaPill'
 export type { DeltaPillProps, DeltaDirection } from './DeltaPill'
 
+export { Numeral } from './Numeral'
+export type { NumeralProps } from './Numeral'
+
 export { DonutChart, donutSlices } from './DonutChart'
 export type { DonutChartProps, DonutSegment, DonutSlice } from './DonutChart'