panelui-native 0.38.0 → 0.41.0

package/src/components/heatmap-chart/index.tsx

@@ -11,6 +11,7 @@
  *
  * ```tsx
  * <HeatmapChart data={weeks}>
+ *   <HeatmapChart.Header title="Contributions" value="1,204" legend />
  *   <HeatmapChart.YAxis />
  *   <HeatmapChart.XAxis />
  *   <HeatmapChart.Cells />
@@ -132,7 +133,7 @@ const MONTHS = [
  * composition stays a flat list of children instead of four nested slots the
  * caller has to remember the order of.
  */
-type Slot = 'cells' | 'x-axis' | 'y-axis' | 'rules' | 'tooltip' | 'legend';
+type Slot = 'cells' | 'x-axis' | 'y-axis' | 'rules' | 'tooltip' | 'legend' | 'header';
 
 export type HeatmapLayout = 'fluid' | 'fill';
 
@@ -566,6 +567,10 @@ const HeatmapChartRoot = forwardRef<View, HeatmapChartProps>(function HeatmapCha
         onLayout={onLayout}
         className={cn('w-full', className)}
       >
+        {/* Above the axis gutter as well as the grid: the header is about the
+            whole chart, so it starts at the chart's edge, not the grid's. */}
+        {parts.header}
+
         {parts.x ? (
           <View style={{ paddingLeft: axisWidth }}>{parts.x}</View>
         ) : null}
@@ -605,6 +610,7 @@ interface Parts {
   y: React.ReactElement<{ width?: number }> | null;
   tooltip: ReactNode[];
   legend: ReactNode[];
+  header: ReactNode[];
   columns: number;
 }
 
@@ -617,6 +623,7 @@ function splitParts(children: ReactNode): Parts {
     y: null,
     tooltip: [],
     legend: [],
+    header: [],
     columns: 0,
   };
 
@@ -630,6 +637,7 @@ function splitParts(children: ReactNode): Parts {
     else if (slot === 'rules') parts.rules.push(keyed);
     else if (slot === 'tooltip') parts.tooltip.push(keyed);
     else if (slot === 'legend') parts.legend.push(keyed);
+    else if (slot === 'header') parts.header.push(keyed);
     else parts.cells.push(keyed);
   });
 
@@ -753,6 +761,12 @@ export interface HeatmapXAxisProps {
    * derived. Return an empty string to leave the column unlabelled.
    */
   formatLabel?: (date: Date, column: number) => string;
+  /**
+   * Column labels, left to right. Overrides the month names — for a grid whose
+   * columns are not weeks, where there is no month to change and so nothing to
+   * emit a label on.
+   */
+  labels?: string[];
 }
 
 /**
@@ -760,13 +774,21 @@ export interface HeatmapXAxisProps {
  *
  * A label is emitted where the month changes rather than at a fixed interval,
  * because months are not the same length — spacing them evenly puts "Mar" over
- * a week in February.
+ * a week in February. A grid whose columns are not weeks has no such signal, so
+ * it passes `labels` and gets one over every column.
  */
-function HeatmapXAxis({ className, formatLabel }: HeatmapXAxisProps) {
+function HeatmapXAxis({ className, formatLabel, labels: given }: HeatmapXAxisProps) {
   const { data, grid } = useHeatmap('HeatmapChart.XAxis');
   const step = grid.size + grid.gap;
 
   const labels = useMemo(() => {
+    if (given) {
+      return given
+        .slice(0, data.length)
+        .map((label, column) => ({ column, label }))
+        .filter((entry) => entry.label);
+    }
+
     const out: { column: number; label: string }[] = [];
     let lastMonth = -1;
 
@@ -784,7 +806,7 @@ function HeatmapXAxis({ className, formatLabel }: HeatmapXAxisProps) {
     // collides with the next one. Drop it when it has no room.
     if (out.length > 1 && out[1]!.column - out[0]!.column < 3) out.shift();
     return out;
-  }, [data, formatLabel]);
+  }, [data, formatLabel, given]);
 
   return (
     <View className={cn('h-4', className)} style={{ width: grid.width }}>
@@ -1002,9 +1024,16 @@ function HeatmapTooltip({
 }
 HeatmapTooltip.slot = 'tooltip' as Slot;
 
+/*
+ * A cell with no date is not a cell with no data — it is a cell in a grid that
+ * is not a calendar, and it has a count like any other. Saying "No data" over
+ * it reports a hole in the data that is not there. Without a date there is
+ * simply nothing to say after the number, so the number is the whole label,
+ * and a grid that wants a noun for it passes `formatLabel`.
+ */
 function defaultTooltipLabel(cell: HeatmapCell) {
+  if (!cell.date) return `${cell.count}`;
   const count = `${cell.count} ${cell.count === 1 ? 'contribution' : 'contributions'}`;
-  if (!cell.date) return 'No data';
   const date = `${MONTHS[cell.date.getMonth()]} ${cell.date.getDate()}`;
   return `${count} on ${date}`;
 }
@@ -1061,7 +1090,120 @@ function HeatmapLegend({
 }
 HeatmapLegend.slot = 'legend' as Slot;
 
+/* -------------------------------------------------------------------------- */
+/* Header                                                                     */
+/* -------------------------------------------------------------------------- */
+
+export interface HeatmapHeaderProps extends ViewProps {
+  className?: string;
+  /** Small line above the value — what the grid is of. */
+  title?: string;
+  /** The readout. The largest thing on the card, and the first thing read. */
+  value?: string;
+  /** One muted line under the value — a period, a total, the held cell. */
+  caption?: string;
+  /**
+   * Draw the ramp along the trailing edge, `Less ▢▢▢▢▢ More`. The key for a
+   * grid that scrolls sideways, where `HeatmapChart.Legend` under the cells
+   * would scroll away with them.
+   */
+  legend?: boolean;
+  /** Text at the low end of the ramp, when `legend` is set. */
+  lessLabel?: string;
+  /** Text at the high end. */
+  moreLabel?: string;
+  /** Trailing slot — a control, a badge, a range picker. Wins over `legend`. */
+  children?: ReactNode;
+}
+
+/**
+ * The strip above the grid: what the chart is of, what it currently reads, and
+ * what the shading means.
+ *
+ * It belongs to the chart rather than to the card around it because it is about
+ * the *grid* — the number changes as a finger moves across the cells, and the
+ * ramp is the scale the chart itself derived. The card's header is a caption on
+ * the tray the chart sits in; this is the chart introducing itself.
+ *
+ * The value is not derived here. Take it from `onActiveCellChange` and pass the
+ * formatted string down, so one header can show a total when nothing is held
+ * and a day's own count when something is.
+ */
+function HeatmapHeader({
+  className,
+  title,
+  value,
+  caption,
+  legend = false,
+  lessLabel = 'Less',
+  moreLabel = 'More',
+  children,
+  ...props
+}: HeatmapHeaderProps) {
+  const { ramp, opacities, grid, cornerRadius } = useHeatmap('HeatmapChart.Header');
+  // Small enough to sit on one line beside the text, whatever the cells are.
+  const size = Math.max(Math.min(grid.size, 12), 8);
+
+  const trailing =
+    children ??
+    (legend ? (
+      <View className="flex-row items-center gap-1.5">
+        <Text size="xs" muted>
+          {lessLabel}
+        </Text>
+        {ramp.map((fill, level) => (
+          <Svg key={level} width={size} height={size}>
+            <Rect
+              x={0}
+              y={0}
+              width={size}
+              height={size}
+              rx={cornerRadius}
+              ry={cornerRadius}
+              fill={fill}
+              fillOpacity={opacities[level]}
+            />
+          </Svg>
+        ))}
+        <Text size="xs" muted>
+          {moreLabel}
+        </Text>
+      </View>
+    ) : null);
+
+  return (
+    <View
+      {...props}
+      className={cn('flex-row items-start justify-between gap-3 pb-3', className)}
+    >
+      <View className="flex-1 gap-0.5">
+        {title ? (
+          <Text size="xs" muted>
+            {title}
+          </Text>
+        ) : null}
+        {value ? (
+          <Text size="xl" weight="bold">
+            {value}
+          </Text>
+        ) : null}
+        {caption ? (
+          <Text size="xs" muted>
+            {caption}
+          </Text>
+        ) : null}
+      </View>
+      {/* Shrinkable, unlike a view's default in React Native — held rigid, the
+          ramp takes the width it wants and the caption wraps around it. */}
+      {trailing ? <View className="shrink pt-1">{trailing}</View> : null}
+    </View>
+  );
+}
+HeatmapHeader.displayName = 'HeatmapChart.Header';
+HeatmapHeader.slot = 'header' as Slot;
+
 export const HeatmapChart = Object.assign(HeatmapChartRoot, {
+  Header: HeatmapHeader,
   Cells: HeatmapCells,
   Separator: HeatmapSeparator,
   XAxis: HeatmapXAxis,

package/src/components/map/index.tsx

@@ -128,6 +128,43 @@ function useToken(name: string, fallback: string): string {
   return typeof value === 'string' && value.length > 0 ? value : fallback;
 }
 
+/** True for a theme token name, as opposed to a literal colour. */
+function isToken(value: string | undefined): value is string {
+  return typeof value === 'string' && value.startsWith('--');
+}
+
+/**
+ * The same colour at a given alpha, for a ramp built from one hue.
+ *
+ * Style expressions are handed to the renderer as strings, so this produces
+ * `rgba()` rather than reaching for a colour type the layer would not accept.
+ */
+function withAlpha(color: string, alpha: number): string {
+  if (color.startsWith('#')) {
+    const hex = color.slice(1);
+    const full =
+      hex.length === 3
+        ? hex
+            .split('')
+            .map((c) => c + c)
+            .join('')
+        : hex.slice(0, 6);
+    const r = parseInt(full.slice(0, 2), 16);
+    const g = parseInt(full.slice(2, 4), 16);
+    const b = parseInt(full.slice(4, 6), 16);
+    if (Number.isNaN(r + g + b)) return color;
+    return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+  }
+
+  const channels = color.match(/rgba?\(([^)]+)\)/)?.[1];
+  if (channels) {
+    const [r, g, b] = channels.split(',').map((part) => part.trim());
+    return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+  }
+
+  return color;
+}
+
 interface MapContextValue {
   mapRef: React.RefObject<MapRef | null>;
   cameraRef: React.RefObject<CameraRef | null>;
@@ -1025,6 +1062,28 @@ export interface MapHeatmapProps {
   data: unknown;
   /** Feature property to weight each point by. Unweighted when omitted. */
   weight?: string;
+  /**
+   * Base colour of the field — a theme token by name, or a literal. The ramp
+   * is this colour at rising opacity, so density reads as *more of the same
+   * thing* rather than as a change of subject.
+   *
+   * Defaults to `--color-chart-2`, which is a saturated accent in every theme.
+   * It is deliberately not `--color-chart-1`: that is the series colour a chart
+   * is about, and every theme starts it on something close to the foreground —
+   * near-black in a light theme, near-white in a dark one — which over a
+   * basemap is a smudge rather than a measurement.
+   */
+  color?: string;
+  /**
+   * Replace the derived ramp outright, coolest first. For the conventional
+   * heat ramp, where the hue carries the reading as well as the opacity —
+   * worth it when the field sits over varied terrain and one hue at five
+   * opacities stops being separable from what is underneath it.
+   *
+   * The first stop is drawn at the lowest density, the last at the highest.
+   * Density zero stays fully transparent either way.
+   */
+  colors?: string[];
   /**
    * Spread of a single point, in points, at street zoom. Larger blurs more.
    * The drawn radius shrinks as the map zooms out, so a point keeps covering
@@ -1037,6 +1096,12 @@ export interface MapHeatmapProps {
   opacity?: number;
   /** Above this zoom the layer fades out — see the note on the component. */
   maxZoom?: number;
+  /**
+   * Draw the points themselves as the field fades out, coloured from the same
+   * ramp by weight. Without them, zooming past `maxZoom` leaves an empty map:
+   * the layer gets out of the way, and nothing takes its place.
+   */
+  points?: boolean;
   id?: string;
 }
 
@@ -1050,30 +1115,63 @@ export interface MapHeatmapProps {
  *
  * It fades out past `maxZoom` on purpose. Zoomed far enough in, every point is
  * its own island and the blur says less than the points would — so the layer
- * gets out of the way rather than smearing five records across a street.
+ * gets out of the way rather than smearing five records across a street. Set
+ * `points` and the records themselves fade in as it goes, which is the whole
+ * handover: a field while the question is where, marks once it is which.
  *
  * The radius is tied to zoom for the mirror-image reason. Left as a fixed
  * number of screen points it would mean a different distance at every zoom:
  * a blur that reads as a city at street level covers half a continent once
  * the map is pulled out, and a field measured over land ends up sitting in
  * the sea. Scaling it with the projection keeps the claim the same one.
+ *
+ * Intensity is tied to zoom too, and in the other direction. The same points
+ * are packed into fewer pixels the further out the map goes, so a constant
+ * intensity saturates the whole field at world zoom and shows nothing but its
+ * own ceiling.
  */
 function MapHeatmap({
   data,
   weight,
+  color,
+  colors,
   radius = 24,
   intensity = 1,
   opacity = 0.85,
   maxZoom = 15,
+  points = false,
   id = 'heatmap',
 }: MapHeatmapProps) {
-  const cool = useToken('--color-muted', 'rgba(0,0,0,0.06)');
-  const warm = useToken('--color-chart-1', '#262626');
-  const hot = useToken('--color-chart-2', '#666666');
+  const base = useToken(isToken(color) ? color : '--color-chart-2', '#3b82f6');
+  const resolved = (isToken(color) ? base : color) ?? base;
+
+  /*
+   * One colour at rising opacity rather than five colours, which is how every
+   * other ramp in the library is built: a sequential scale is one quantity
+   * getting larger, and five hues say five categories. `colors` is there for
+   * the case where that is not enough.
+   */
+  const ramp = colors?.length
+    ? colors
+    : [
+        withAlpha(resolved, 0.25),
+        withAlpha(resolved, 0.45),
+        withAlpha(resolved, 0.7),
+        withAlpha(resolved, 0.9),
+        resolved,
+      ];
 
   if (!MapLibre) return null;
   const { GeoJSONSource, Layer } = MapLibre;
 
+  // Density zero is transparent rather than the coolest colour, so the map
+  // shows through everywhere nothing was measured instead of the whole
+  // viewport being tinted by the absence of data.
+  const stops = ramp.flatMap((entry, index) => [
+    0.15 + (0.85 * index) / Math.max(1, ramp.length - 1),
+    entry,
+  ]);
+
   return (
     <GeoJSONSource id={`${id}-source`} data={data}>
       <Layer
@@ -1084,7 +1182,15 @@ function MapHeatmap({
           heatmapWeight: weight
             ? ['interpolate', ['linear'], ['get', weight], 0, 0, 1, 1]
             : 1,
-          heatmapIntensity: intensity,
+          heatmapIntensity: [
+            'interpolate',
+            ['linear'],
+            ['zoom'],
+            0,
+            intensity * 0.6,
+            maxZoom,
+            intensity * 1.2,
+          ],
           // `radius` is the spread at street zoom; below that it is scaled
           // down so it keeps covering the same ground rather than the same
           // number of pixels. The stops are the projection: each zoom level
@@ -1101,21 +1207,13 @@ function MapHeatmap({
             14,
             radius,
           ],
-          // Transparent at zero rather than the coolest colour, so the map
-          // shows through everywhere nothing was measured instead of the whole
-          // viewport being tinted by the absence of data.
           heatmapColor: [
             'interpolate',
             ['linear'],
             ['heatmap-density'],
             0,
             'rgba(0,0,0,0)',
-            0.2,
-            cool,
-            0.6,
-            warm,
-            1,
-            hot,
+            ...stops,
           ],
           heatmapOpacity: [
             'interpolate',
@@ -1128,6 +1226,52 @@ function MapHeatmap({
           ],
         }}
       />
+
+      {/* The handover, in the two zoom levels the field spends fading: the
+          marks arrive as it leaves, so there is never a zoom with neither. */}
+      {points ? (
+        <Layer
+          id={`${id}-points`}
+          type="circle"
+          minzoom={maxZoom - 2}
+          style={{
+            circleRadius: weight
+              ? ['interpolate', ['linear'], ['get', weight], 0, 3, 1, 9]
+              : 5,
+            circleColor: weight
+              ? [
+                  'interpolate',
+                  ['linear'],
+                  ['get', weight],
+                  0,
+                  ramp[0] as string,
+                  1,
+                  ramp[ramp.length - 1] as string,
+                ]
+              : (ramp[ramp.length - 1] as string),
+            circleStrokeWidth: 1,
+            circleStrokeColor: 'rgba(255,255,255,0.75)',
+            circleOpacity: [
+              'interpolate',
+              ['linear'],
+              ['zoom'],
+              maxZoom - 2,
+              0,
+              maxZoom,
+              0.85,
+            ],
+            circleStrokeOpacity: [
+              'interpolate',
+              ['linear'],
+              ['zoom'],
+              maxZoom - 2,
+              0,
+              maxZoom,
+              0.6,
+            ],
+          }}
+        />
+      ) : null}
     </GeoJSONSource>
   );
 }