jfs-components 0.0.72 → 0.0.73

package/src/components/MonthlyStatusGrid/MonthlyStatusGrid.tsx

@@ -0,0 +1,438 @@
+import React from 'react'
+import {
+  View,
+  Text,
+  type StyleProp,
+  type TextStyle,
+  type ViewStyle,
+} from 'react-native'
+import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
+import { useTokens } from '../../design-tokens/JFSThemeProvider'
+import { EMPTY_MODES } from '../../utils/react-utils'
+import MetricLegendItem from '../MetricLegendItem/MetricLegendItem'
+
+/**
+ * The three semantic states a calendar glyph can be in. Maps 1:1 to the
+ * Figma `Calendar Glyph State` collection modes (`Idle`, `notSaved`,
+ * `saved`) and drives both the glyph fill/foreground tokens and the
+ * matching legend dot.
+ */
+export type MonthlyStatus = 'Idle' | 'notSaved' | 'saved'
+
+/** One month entry in the grid. */
+export type MonthlyStatusGridMonth = {
+  /** Stable React key. */
+  key?: React.Key
+  /**
+   * Text rendered inside the glyph (e.g. `'Jan'`). When omitted, defaults
+   * to a 3-letter English month name based on the entry's index.
+   */
+  label?: React.ReactNode
+  /**
+   * Semantic status. Drives the glyph background/foreground colors and the
+   * legend dot via the Figma `Calendar Glyph State` collection.
+   */
+  status: MonthlyStatus
+  /**
+   * Per-month design token mode overrides. Merged on top of the parent
+   * `modes` and the per-month `Calendar Glyph State` derived from `status`.
+   */
+  modes?: Record<string, any>
+  /** Per-month accessibility label. */
+  accessibilityLabel?: string
+}
+
+export type MonthlyStatusGridProps = {
+  /**
+   * The months to render. Layout flows left-to-right, top-to-bottom into
+   * `columns` per row. Defaults to 12 `Idle` months (Jan…Dec) so the
+   * component renders something meaningful with no props.
+   */
+  months?: MonthlyStatusGridMonth[]
+  /**
+   * Number of glyphs per row. Default `4` (matching the Figma reference of
+   * 12 months × 4 columns = 3 rows).
+   */
+  columns?: number
+  /**
+   * Override the legend labels. Pass `false` to hide the legend entirely.
+   * Missing keys fall back to the defaults: `No data`, `Not saved`,
+   * `Saved`.
+   */
+  legend?: false | Partial<Record<MonthlyStatus, React.ReactNode>>
+  /**
+   * Restrict which legend entries are shown and in what order. Defaults to
+   * all three statuses in `[Idle, notSaved, saved]` order — matching the
+   * Figma reference.
+   */
+  legendStatuses?: MonthlyStatus[]
+  /** Design token modes (e.g. `{ 'Color Mode': 'Light' }`). */
+  modes?: Record<string, any>
+  /** Container style override. */
+  style?: StyleProp<ViewStyle>
+  /** Style applied to the months section (the rows wrapper). */
+  monthsStyle?: StyleProp<ViewStyle>
+  /** Style applied to each row of glyphs. */
+  rowStyle?: StyleProp<ViewStyle>
+  /** Style applied to every calendar glyph. */
+  glyphStyle?: StyleProp<ViewStyle>
+  /** Style applied to the glyph label text. */
+  labelStyle?: StyleProp<TextStyle>
+  /** Style applied to the legend row. */
+  legendStyle?: StyleProp<ViewStyle>
+  /** Accessibility label for the entire component. */
+  accessibilityLabel?: string
+}
+
+const DEFAULT_MONTH_LABELS: readonly string[] = [
+  'Jan',
+  'Feb',
+  'Mar',
+  'Apr',
+  'May',
+  'Jun',
+  'Jul',
+  'Aug',
+  'Sep',
+  'Oct',
+  'Nov',
+  'Dec',
+]
+
+const DEFAULT_LEGEND_LABELS: Readonly<Record<MonthlyStatus, string>> = Object.freeze({
+  Idle: 'No data',
+  notSaved: 'Not saved',
+  saved: 'Saved',
+})
+
+const DEFAULT_LEGEND_STATUSES: readonly MonthlyStatus[] = ['Idle', 'notSaved', 'saved']
+
+const DEFAULT_MONTHS: MonthlyStatusGridMonth[] = DEFAULT_MONTH_LABELS.map((label) => ({
+  label,
+  status: 'Idle' as const,
+}))
+
+/**
+ * Default tokens used as the safe fallbacks when token resolution returns
+ * `null` (e.g. modes are missing or the resolver hasn't been initialized).
+ * They mirror the Figma source values for the `Calendar Glyph State` modes.
+ */
+const FALLBACK_BG: Record<MonthlyStatus, string> = {
+  Idle: '#e0e0e3',
+  notSaved: '#b84fbd',
+  saved: '#5d00b5',
+}
+
+const FALLBACK_FG: Record<MonthlyStatus, string> = {
+  Idle: '#000000',
+  notSaved: '#ffffff',
+  saved: '#ffffff',
+}
+
+const toNumber = (value: unknown, fallback: number) => {
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? value : fallback
+  }
+  if (typeof value === 'string') {
+    const parsed = Number(value)
+    return Number.isFinite(parsed) ? parsed : fallback
+  }
+  return fallback
+}
+
+const toFontWeight = (
+  value: unknown,
+  fallback: TextStyle['fontWeight']
+): TextStyle['fontWeight'] => {
+  if (typeof value === 'number') {
+    return String(value) as TextStyle['fontWeight']
+  }
+  if (typeof value === 'string') {
+    return value as TextStyle['fontWeight']
+  }
+  return fallback
+}
+
+export type CalendarGlyphProps = {
+  /** Text rendered inside the glyph (e.g. `'Jan'`). */
+  label?: React.ReactNode
+  /**
+   * Semantic status — drives the glyph fill/foreground via the Figma
+   * `Calendar Glyph State` collection.
+   */
+  status?: MonthlyStatus
+  /** Design token mode overrides. */
+  modes?: Record<string, any>
+  /** Container style override. */
+  style?: StyleProp<ViewStyle>
+  /** Label text style override. */
+  labelStyle?: StyleProp<TextStyle>
+  /** Accessibility label. Defaults to `"{label}, {status}"`. */
+  accessibilityLabel?: string
+}
+
+/**
+ * Single calendar-month glyph: a small pill with a status-driven background
+ * and foreground, and a centered month label. Exposed for callers who want
+ * to compose glyphs themselves; most consumers should use
+ * {@link MonthlyStatusGrid} instead, which keeps the count, layout and
+ * legend in sync automatically.
+ */
+function CalendarGlyph({
+  label = 'Jan',
+  status = 'Idle',
+  modes: propModes = EMPTY_MODES,
+  style,
+  labelStyle,
+  accessibilityLabel,
+}: CalendarGlyphProps) {
+  const { modes: globalModes } = useTokens()
+  const modes = React.useMemo(
+    () => ({ ...globalModes, ...propModes, 'Calendar Glyph State': status }),
+    [globalModes, propModes, status]
+  )
+
+  const width = toNumber(getVariableByName('calendarGlyph/width', modes), 46)
+  const height = toNumber(getVariableByName('calendarGlyph/height', modes), 46)
+  const radius = toNumber(getVariableByName('calendarGlyph/radius', modes), 29)
+  const paddingTop = toNumber(getVariableByName('calendarGlyph/padding/top', modes), 16)
+  const paddingBottom = toNumber(getVariableByName('calendarGlyph/padding/bottom', modes), 16)
+  const paddingLeft = toNumber(getVariableByName('calendarGlyph/padding/left', modes), 13)
+  const paddingRight = toNumber(getVariableByName('calendarGlyph/padding/right', modes), 12)
+  const gap = toNumber(getVariableByName('calendarGlyph/gap', modes), 0)
+
+  const background =
+    (getVariableByName('calendarGlyph/background', modes) as string | null) ??
+    FALLBACK_BG[status]
+  const foreground =
+    (getVariableByName('calendarGlyph/foreground', modes) as string | null) ??
+    FALLBACK_FG[status]
+
+  const fontFamily =
+    (getVariableByName('calendarGlyph/fontFamily', modes) as string | null) ?? 'JioType Var'
+  const fontSize = toNumber(getVariableByName('calendarGlyph/fontSize', modes), 12)
+  const lineHeight = toNumber(getVariableByName('calendarGlyph/lineHeight', modes), 14)
+  const fontWeight = toFontWeight(getVariableByName('calendarGlyph/fontWeight', modes), '500')
+
+  const defaultAccessibilityLabel =
+    accessibilityLabel ??
+    `${typeof label === 'string' ? label : 'Month'}, ${DEFAULT_LEGEND_LABELS[status].toLowerCase()}`
+
+  return (
+    <View
+      accessibilityLabel={defaultAccessibilityLabel}
+      style={[
+        {
+          // Use min* so the pill is always at least the Figma size, but
+          // grows naturally when the label is wider (e.g. localized
+          // months). Avoids the ellipsis-truncation that happens when a
+          // 3-letter label barely overflows the strict inner width.
+          minWidth: width,
+          minHeight: height,
+          borderRadius: radius,
+          backgroundColor: background,
+          paddingTop,
+          paddingBottom,
+          paddingLeft,
+          paddingRight,
+          alignItems: 'center',
+          justifyContent: 'center',
+          gap,
+        },
+        style,
+      ]}
+    >
+      <Text
+        numberOfLines={1}
+        style={[
+          {
+            color: foreground,
+            fontFamily,
+            fontSize,
+            lineHeight,
+            fontWeight,
+            textAlign: 'center',
+          },
+          labelStyle,
+        ]}
+      >
+        {label}
+      </Text>
+    </View>
+  )
+}
+
+/**
+ * Resolve the canonical color pair for a status. Used by both the glyph and
+ * the matching legend item so they can never visually drift apart.
+ */
+function resolveStatusColors(
+  status: MonthlyStatus,
+  modes: Record<string, any>
+): { bg: string; fg: string; statusModes: Record<string, any> } {
+  const statusModes = { ...modes, 'Calendar Glyph State': status }
+  const bg =
+    (getVariableByName('calendarGlyph/background', statusModes) as string | null) ??
+    FALLBACK_BG[status]
+  const fg =
+    (getVariableByName('calendarGlyph/foreground', statusModes) as string | null) ??
+    FALLBACK_FG[status]
+  return { bg, fg, statusModes }
+}
+
+/**
+ * `MonthlyStatusGrid` shows a year (or any contiguous range of months) as a
+ * grid of small pill-shaped calendar glyphs, each colored by its semantic
+ * status (`Idle` = "No data", `notSaved` = "Not saved", `saved` = "Saved").
+ * A legend below the grid explains the colors.
+ *
+ * Cohesiveness guarantees:
+ * - The number of glyphs is **always** `months.length`. There is no way to
+ *   render a glyph that has no underlying status.
+ * - The legend dot color for a status is resolved through the **same**
+ *   `calendarGlyph/background` token + `Calendar Glyph State` mode as the
+ *   glyph itself, so the visual mapping cannot drift.
+ *
+ * The chart is rendered with plain RN primitives (`View` + `Text`); SVG is
+ * unnecessary here because the glyph shape is a simple rounded rectangle.
+ *
+ * @component
+ */
+function MonthlyStatusGrid({
+  months = DEFAULT_MONTHS,
+  columns = 4,
+  legend,
+  legendStatuses = DEFAULT_LEGEND_STATUSES as MonthlyStatus[],
+  modes: propModes = EMPTY_MODES,
+  style,
+  monthsStyle,
+  rowStyle,
+  glyphStyle,
+  labelStyle,
+  legendStyle,
+  accessibilityLabel,
+}: MonthlyStatusGridProps) {
+  const { modes: globalModes } = useTokens()
+  const modes = React.useMemo(
+    () => ({ ...globalModes, ...propModes }),
+    [globalModes, propModes]
+  )
+
+  const gridGap = toNumber(getVariableByName('monthlyStatusGrid/gap', modes), 16)
+  const rowGap = toNumber(getVariableByName('monthlyStatusGrid/months/gap', modes), 12)
+
+  const safeColumns = Math.max(1, Math.floor(columns))
+
+  // Group months into rows of `safeColumns`. Render-time only; cheap.
+  const rows = React.useMemo(() => {
+    const out: MonthlyStatusGridMonth[][] = []
+    for (let i = 0; i < months.length; i += safeColumns) {
+      out.push(months.slice(i, i + safeColumns))
+    }
+    return out
+  }, [months, safeColumns])
+
+  const showLegend = legend !== false
+  const legendOverrides: Partial<Record<MonthlyStatus, React.ReactNode>> =
+    legend && typeof legend === 'object' ? legend : {}
+
+  const defaultAccessibilityLabel =
+    accessibilityLabel ??
+    `Monthly status grid: ${months.length} month${months.length === 1 ? '' : 's'}`
+
+  return (
+    <View
+      accessibilityLabel={defaultAccessibilityLabel}
+      style={[
+        {
+          width: '100%',
+          gap: gridGap,
+          alignItems: 'stretch',
+          justifyContent: 'center',
+        },
+        style,
+      ]}
+    >
+      <View
+        style={[
+          {
+            width: '100%',
+            gap: rowGap,
+            alignItems: 'stretch',
+          },
+          monthsStyle,
+        ]}
+      >
+        {rows.map((row, rowIndex) => (
+          <View
+            key={`row-${rowIndex}`}
+            style={[
+              {
+                flexDirection: 'row',
+                alignItems: 'center',
+                justifyContent: 'space-between',
+                width: '100%',
+              },
+              rowStyle,
+            ]}
+          >
+            {row.map((month, colIndex) => {
+              const absoluteIndex = rowIndex * safeColumns + colIndex
+              const fallbackLabel =
+                DEFAULT_MONTH_LABELS[absoluteIndex % DEFAULT_MONTH_LABELS.length]
+              const label = month.label ?? fallbackLabel
+              const glyphModes = month.modes
+                ? { ...modes, ...month.modes }
+                : modes
+              return (
+                <CalendarGlyph
+                  key={month.key ?? `glyph-${absoluteIndex}`}
+                  label={label}
+                  status={month.status}
+                  modes={glyphModes}
+                  {...(glyphStyle !== undefined ? { style: glyphStyle } : {})}
+                  {...(labelStyle !== undefined ? { labelStyle } : {})}
+                  {...(month.accessibilityLabel !== undefined
+                    ? { accessibilityLabel: month.accessibilityLabel }
+                    : {})}
+                />
+              )
+            })}
+          </View>
+        ))}
+      </View>
+
+      {showLegend ? (
+        <View
+          style={[
+            {
+              flexDirection: 'row',
+              alignItems: 'center',
+              justifyContent: 'space-between',
+              width: '100%',
+            },
+            legendStyle,
+          ]}
+        >
+          {legendStatuses.map((status) => {
+            const { bg, statusModes } = resolveStatusColors(status, modes)
+            const label =
+              legendOverrides[status] ?? DEFAULT_LEGEND_LABELS[status]
+            return (
+              <MetricLegendItem
+                key={`legend-${status}`}
+                label={label}
+                indicatorColor={bg}
+                modes={statusModes}
+                style={{ flex: 1, minWidth: 0 }}
+              />
+            )
+          })}
+        </View>
+      ) : null}
+    </View>
+  )
+}
+
+export { CalendarGlyph }
+export default MonthlyStatusGrid