@startsimpli/ui 0.4.92 → 0.4.94

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.92",
+  "version": "0.4.94",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -120,8 +120,8 @@
     "tailwindcss": "^3.4.19",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "@startsimpli/i18n": "0.1.1",
-    "@startsimpli/realtime": "0.0.2"
+    "@startsimpli/realtime": "0.0.2",
+    "@startsimpli/i18n": "0.1.1"
   },
   "keywords": [
     "ui",

package/src/components/dashboard/DashboardSection.tsx

@@ -1,32 +1,63 @@
 import * as React from 'react'
+import { cn } from '../../lib/utils'
+import { TYPE_SCALE } from '../../theme/type-scale'
+import { Caveat } from '../states/Caveat'
+import { FootnoteScope } from '../states/Footnote'
 
 export interface DashboardSectionProps {
   title: string
   description?: string
   action?: React.ReactNode
+  /**
+   * A qualification of everything in this section. Collapses to a marker beside
+   * the heading and expands on demand.
+   */
+  caveat?: React.ReactNode
+  /**
+   * Collect the notes the section's items claim and print each distinct one
+   * once, underneath them. On by default — a caveat authored per item is a
+   * caveat said per section, not per item. Pass `false` to opt a section out.
+   */
+  footnotes?: boolean
   children: React.ReactNode
   className?: string
 }
 
+/**
+ * A titled band of a dashboard, and the scope its items' footnotes collect into.
+ *
+ * The scope is the whole point of the default: an item can author the caveat it
+ * knows about without anyone counting how many other items say the same thing.
+ */
 export function DashboardSection({
   title,
   description,
   action,
+  caveat,
+  footnotes = true,
   children,
   className = '',
 }: DashboardSectionProps) {
   return (
-    <div className={`space-y-4 ${className}`}>
-      <div className="flex items-start justify-between">
+    <div className={cn('space-y-4', className)}>
+      <div className="flex items-start justify-between gap-4">
         <div>
-          <h2 className="text-lg font-semibold text-gray-900">{title}</h2>
+          {/* `heading` is the section step of the type scale; the colour comes
+              from the theme, so this reads on a dark tenant as well as a light
+              one. `text-gray-900`/`text-gray-600` used to hard-code light. */}
+          <h2 className={cn(TYPE_SCALE.heading, 'text-foreground')}>
+            {title}
+            {caveat ? <Caveat subject={title}>{caveat}</Caveat> : null}
+          </h2>
           {description && (
-            <p className="text-sm text-gray-600 mt-1">{description}</p>
+            <p className={cn(TYPE_SCALE.muted, 'mt-1 text-muted-foreground')}>
+              {description}
+            </p>
           )}
         </div>
         {action && <div className="flex-shrink-0">{action}</div>}
       </div>
-      {children}
+      {footnotes ? <FootnoteScope>{children}</FootnoteScope> : children}
     </div>
   )
 }

package/src/components/dashboard/MetricCard.tsx

@@ -36,7 +36,10 @@ export function MetricCard({
   const content = (
     <div
       className={cn(
-        'rounded-xl border bg-card text-card-foreground shadow p-6 transition-all duration-200 hover:shadow-lg cursor-pointer',
+        // `border` on its own resolves to currentColor in Tailwind v4 — on a
+        // card that sets text-card-foreground that draws a near-black outline
+        // in light mode and a glaring pale one on a dark tenant. Name the token.
+        'rounded-xl border border-border bg-card text-card-foreground shadow p-6 transition-all duration-200 hover:shadow-lg cursor-pointer',
         error && 'border-red-200 bg-red-50',
         isLoading && 'animate-pulse',
         className,

package/src/components/dashboard/StatTile.tsx

@@ -1,5 +1,7 @@
 import * as React from 'react'
 import { cn } from '../../lib/utils'
+import { Caveat } from '../states/Caveat'
+import { Footnote } from '../states/Footnote'
 import { AreaTrend } from './AreaTrend'
 import { DeltaPill, type DeltaPillProps } from './DeltaPill'
 
@@ -20,6 +22,17 @@ export interface StatTileProps {
   sparklineColor?: string
   /** Numeral scale — `lg` (text-4xl) by default, `xl` for a hero figure. */
   size?: StatTileSize
+  /**
+   * A qualification of this figure. Collapses to a marker beside the kicker and
+   * expands on demand, so it never competes with the number for weight.
+   */
+  caveat?: React.ReactNode
+  /**
+   * A caveat that belongs to the whole section rather than this tile. Inside a
+   * `FootnoteScope` it is printed once under the section, however many tiles
+   * carry it.
+   */
+  note?: string
   /** Extra content below the delta. */
   children?: React.ReactNode
   className?: string
@@ -45,6 +58,8 @@ export function StatTile({
   sparkline,
   sparklineColor,
   size = 'lg',
+  caveat,
+  note,
   children,
   className,
 }: StatTileProps) {
@@ -57,8 +72,12 @@ export function StatTile({
         className,
       )}
     >
-      <p className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+      {/* The kicker is the canonical home for a caveat: beside the thing it
+          qualifies, at the weight of a label rather than a number. */}
+      <p className="text-start text-xs font-medium uppercase tracking-wide text-muted-foreground">
         {label}
+        {caveat ? <Caveat subject={label}>{caveat}</Caveat> : null}
+        {note ? <Footnote note={note} subject={label} /> : null}
       </p>
 
       <div className="mt-2 flex items-center justify-between gap-4">

package/src/components/states/Absence.tsx

@@ -0,0 +1,156 @@
+import * as React from 'react'
+import { cn } from '../../lib/utils'
+import { Card, CardContent } from '../ui/card'
+import { Caveat } from './Caveat'
+import { Footnote } from './Footnote'
+import { EmptyState, StateAction, type EmptyStateAction } from './EmptyState'
+
+/**
+ * How much is missing, and therefore how much room saying so is worth.
+ *
+ * - `value`  — one figure inside a tile that is otherwise alive. An em dash.
+ * - `note`   — one line, no chrome, under or beside data that is present.
+ * - `card`   — a card slot with nothing behind it at all.
+ * - `page`   — the whole surface has nothing to show.
+ *
+ * The ladder exists because a missing tile and a missing screen are not the
+ * same event, and rendering them identically makes a dashboard read as a
+ * disclaimer document.
+ */
+export type AbsenceTier = 'value' | 'note' | 'card' | 'page'
+
+/** What stands in for a figure nobody reported. Never a 0, never a blank. */
+export const ABSENCE_DASH = '—'
+
+export interface AbsenceProps {
+  tier: AbsenceTier
+  /**
+   * What is missing, in a phrase. On the `value` tier it is not drawn — it is
+   * the screen-reader text behind the dash, so the absence is never silent.
+   */
+  title: string
+  /** One line of what. Never a number and never a zero — those mean something else. */
+  description?: string
+  /**
+   * Why it is missing, where that is known ("Anghami has not reported this").
+   * Carried by a disclosure, so the reason is available without being shouted.
+   */
+  why?: React.ReactNode
+  /**
+   * A sentence that belongs to the whole screen rather than this card. Inside a
+   * `FootnoteScope` it is printed once, however many absences claim it.
+   */
+  note?: string
+  /** `page` tier: drawn above the heading. */
+  icon?: React.ReactNode
+  /** What the reader can do about it, where there is something. */
+  action?: EmptyStateAction
+  /** `note` tier: a dashed inset instead of a bare line, for a gap inside a card. */
+  inset?: boolean
+  className?: string
+}
+
+/**
+ * One vocabulary for "we do not have this", graded by how much is missing.
+ *
+ * Every tier says WHAT is absent and, where it is known, WHY — and none of them
+ * renders a 0, a blank cell or a spinner that never ends, because a number
+ * nobody reported and a number that is zero are different statements.
+ */
+export function Absence({
+  tier,
+  title,
+  description,
+  why,
+  note,
+  icon,
+  action,
+  inset,
+  className,
+}: AbsenceProps) {
+  const caveat = why ? (
+    <Caveat subject={title} placement={tier === 'value' ? 'overlay' : 'inline'}>
+      {why}
+    </Caveat>
+  ) : null
+  const footnote = note ? <Footnote note={note} subject={title} /> : null
+
+  if (tier === 'value') {
+    return (
+      <span
+        data-absence="value"
+        className={cn('inline-flex items-baseline text-muted-foreground', className)}
+      >
+        <span aria-hidden="true" className="tabular-nums">
+          {ABSENCE_DASH}
+        </span>
+        <span className="sr-only">
+          {description ? `${title}. ${description}` : title}
+        </span>
+        {caveat}
+        {footnote}
+      </span>
+    )
+  }
+
+  if (tier === 'note') {
+    return (
+      <div
+        role="note"
+        data-absence="note"
+        className={cn(
+          'max-w-prose text-start text-sm leading-relaxed text-muted-foreground',
+          inset && 'rounded-lg border border-dashed border-border p-4',
+          className,
+        )}
+      >
+        <span className={cn('font-medium text-foreground/80', inset && 'block')}>
+          {title}
+        </span>
+        {description ? (
+          <span className={cn(inset ? 'mt-1 block' : 'ms-1')}>{description}</span>
+        ) : null}
+        {caveat}
+        {footnote}
+      </div>
+    )
+  }
+
+  if (tier === 'card') {
+    return (
+      <Card data-absence="card" className={cn('text-start', className)}>
+        <CardContent className="space-y-1.5 p-5">
+          <p className="text-sm font-semibold text-foreground">
+            {title}
+            {footnote}
+          </p>
+          {description && (
+            <p className="max-w-prose text-sm leading-relaxed text-muted-foreground">
+              {description}
+            </p>
+          )}
+          {caveat}
+          {action && <StateAction action={action} className="mt-2" />}
+        </CardContent>
+      </Card>
+    )
+  }
+
+  return (
+    <EmptyState
+      title={title}
+      description={description}
+      action={action}
+      icon={icon}
+      className={cn('text-center', className)}
+      data-absence="page"
+    >
+      {(caveat || footnote) && (
+        <span className="mt-4 inline-flex items-center text-xs text-muted-foreground">
+          {caveat}
+          {footnote}
+        </span>
+      )}
+    </EmptyState>
+  )
+}

package/src/components/states/Caveat.tsx

@@ -0,0 +1,167 @@
+'use client'
+
+import * as React from 'react'
+import { cn } from '../../lib/utils'
+
+export type CaveatPlacement = 'overlay' | 'inline'
+
+export interface CaveatProps {
+  /** The qualification itself. It stays out of the layout until it is asked for. */
+  children: React.ReactNode
+  /** Trigger wording. Two words at most — it sits beside a number, not above it. */
+  label?: string
+  /** What the caveat qualifies. Folded into the trigger's accessible name. */
+  subject?: string
+  /** `marker` (default) draws a small round glyph; `text` draws the label itself. */
+  trigger?: 'marker' | 'text'
+  /**
+   * `overlay` (default) floats the note over the layout, so a caveat can sit in
+   * a tight row without pushing the row apart. `inline` opens it in flow, for
+   * surfaces that already have the room.
+   */
+  placement?: CaveatPlacement
+  /** Open on first paint. Ignored when `open` is supplied. */
+  defaultOpen?: boolean
+  /** Controlled open state. */
+  open?: boolean
+  onOpenChange?: (open: boolean) => void
+  className?: string
+  panelClassName?: string
+}
+
+/**
+ * A caveat that collapses to a marker and expands on demand.
+ *
+ * The affordance exists so a qualification ("these are estimates", "settlement
+ * lags about a month") can live next to the figure it qualifies without being
+ * set at the same weight as the figure. It is a disclosure widget, not a
+ * tooltip: the trigger is a real button carrying `aria-expanded` and
+ * `aria-controls`, it is reachable and operable from the keyboard, and the note
+ * is never hover-only.
+ *
+ * The panel is always in the DOM and hidden when closed, so `aria-controls`
+ * always resolves; `aria-describedby` is attached only while it is open, so a
+ * screen reader is never pointed at hidden text.
+ */
+export function Caveat({
+  children,
+  label = 'Why?',
+  subject,
+  trigger = 'marker',
+  placement = 'overlay',
+  defaultOpen = false,
+  open,
+  onOpenChange,
+  className,
+  panelClassName,
+}: CaveatProps) {
+  const generatedId = React.useId().replace(/:/g, '')
+  const panelId = `caveat-${generatedId}`
+  const rootRef = React.useRef<HTMLSpanElement>(null)
+  const panelRef = React.useRef<HTMLSpanElement>(null)
+  const [flipped, setFlipped] = React.useState(false)
+
+  const [uncontrolledOpen, setUncontrolledOpen] = React.useState(defaultOpen)
+  const isControlled = open !== undefined
+  const isOpen = isControlled ? open : uncontrolledOpen
+
+  const setOpen = React.useCallback(
+    (next: boolean) => {
+      if (!isControlled) setUncontrolledOpen(next)
+      onOpenChange?.(next)
+    },
+    [isControlled, onOpenChange],
+  )
+
+  // A caveat on the last tile of a row would otherwise open off the edge of the
+  // screen. Anchor it to the opposite logical edge instead — measured, so it
+  // works the same whichever way the document reads.
+  React.useLayoutEffect(() => {
+    if (!isOpen || placement !== 'overlay') {
+      setFlipped(false)
+      return
+    }
+    const panel = panelRef.current
+    if (!panel) return
+    const rect = panel.getBoundingClientRect()
+    if (rect.width === 0) return
+    const viewport = window.innerWidth
+    if (rect.right > viewport - 8 || rect.left < 8) setFlipped(true)
+  }, [isOpen, placement])
+
+  // An overlay sits on top of the layout, so a click elsewhere should put it
+  // away. An inline note is part of the page and stays until it is dismissed.
+  React.useEffect(() => {
+    if (!isOpen || placement !== 'overlay') return
+    function onPointerDown(event: MouseEvent) {
+      const root = rootRef.current
+      if (root && !root.contains(event.target as Node)) setOpen(false)
+    }
+    document.addEventListener('mousedown', onPointerDown)
+    return () => document.removeEventListener('mousedown', onPointerDown)
+  }, [isOpen, placement, setOpen])
+
+  const accessibleName = subject ? `${label} ${subject}` : label
+
+  return (
+    <span
+      ref={rootRef}
+      className={cn(
+        'text-start',
+        placement === 'overlay' ? 'relative inline-block' : 'inline',
+        className,
+      )}
+      onKeyDown={(event) => {
+        if (event.key === 'Escape' && isOpen) {
+          event.stopPropagation()
+          setOpen(false)
+        }
+      }}
+    >
+      <button
+        type="button"
+        aria-expanded={isOpen}
+        aria-controls={panelId}
+        aria-describedby={isOpen ? panelId : undefined}
+        data-state={isOpen ? 'open' : 'closed'}
+        onClick={() => setOpen(!isOpen)}
+        className={cn(
+          'ms-1 inline-flex shrink-0 items-center justify-center align-middle text-muted-foreground transition-colors',
+          'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1',
+          trigger === 'marker'
+            ? 'h-4 w-4 rounded-full border border-border text-[10px] font-semibold leading-none hover:bg-accent hover:text-accent-foreground'
+            : 'gap-1 rounded text-xs font-medium underline underline-offset-2 hover:text-foreground',
+        )}
+      >
+        {trigger === 'marker' ? (
+          <>
+            <span aria-hidden="true">?</span>
+            <span className="sr-only">{accessibleName}</span>
+          </>
+        ) : (
+          <>
+            <span>{label}</span>
+            {subject ? <span className="sr-only">{subject}</span> : null}
+          </>
+        )}
+      </button>
+
+      <span
+        ref={panelRef}
+        id={panelId}
+        role="note"
+        hidden={!isOpen}
+        className={cn(
+          'rounded-md border border-border bg-popover p-2 text-start text-xs font-normal normal-case leading-relaxed tracking-normal text-popover-foreground shadow-sm',
+          placement === 'overlay' && 'absolute top-full z-20 mt-1 w-64 max-w-[min(16rem,80vw)]',
+          placement === 'overlay' && (flipped ? 'end-0' : 'start-0'),
+          placement === 'inline' && 'mt-2 max-w-prose',
+          isOpen ? 'block' : 'hidden',
+          panelClassName,
+        )}
+      >
+        {children}
+      </span>
+    </span>
+  )
+}

package/src/components/states/EmptyState.tsx

@@ -6,18 +6,48 @@ export interface EmptyStateAction {
   onClick: () => void
 }
 
-export interface EmptyStateProps {
+export interface EmptyStateProps
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'title' | 'action'> {
   title: string
   description?: string
   action?: EmptyStateAction
+  /** Drawn above the heading. Decorative — the heading carries the meaning. */
+  icon?: React.ReactNode
+  /** Anything that belongs under the action, e.g. a caveat or a footnote marker. */
+  children?: React.ReactNode
   className?: string
 }
 
+/** The one button shape every state surface uses, so none of them redraws it. */
+export function StateAction({
+  action,
+  className,
+}: {
+  action: EmptyStateAction
+  className?: string
+}) {
+  return (
+    <button
+      onClick={action.onClick}
+      className={cn(
+        'inline-flex items-center justify-center rounded-md text-sm font-medium bg-primary text-primary-foreground shadow hover:bg-primary/90 h-9 px-4 py-2 transition-colors',
+        className
+      )}
+      aria-label={action.label}
+    >
+      {action.label}
+    </button>
+  )
+}
+
 export function EmptyState({
   title,
   description,
   action,
+  icon,
+  children,
   className,
+  ...rest
 }: EmptyStateProps) {
   return (
     <div
@@ -27,22 +57,21 @@ export function EmptyState({
       )}
       role="status"
       aria-live="polite"
+      {...rest}
     >
+      {icon && (
+        <div className="mb-4 text-muted-foreground" aria-hidden="true">
+          {icon}
+        </div>
+      )}
       <h3 className="text-xl font-semibold text-foreground mb-3">{title}</h3>
       {description && (
         <p className="text-base text-muted-foreground mb-8 max-w-md leading-relaxed">
           {description}
         </p>
       )}
-      {action && (
-        <button
-          onClick={action.onClick}
-          className="inline-flex items-center justify-center rounded-md text-sm font-medium bg-primary text-primary-foreground shadow hover:bg-primary/90 h-9 px-4 py-2 transition-colors"
-          aria-label={action.label}
-        >
-          {action.label}
-        </button>
-      )}
+      {action && <StateAction action={action} />}
+      {children}
     </div>
   )
 }