@astryxdesign/lab 0.0.0-bootstrap.0 → 0.1.2-canary.04e71b2

package/src/Sankey/SankeyNode.tsx

@@ -0,0 +1,66 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file SankeyNode.tsx
+ * @output Renders node indicators with optional glow
+ * @position Visual layer — node bars that labels sit on
+ *
+ * Reads nodeColor from chart context. When set, all nodes use that color.
+ * Otherwise, uses each node's individual oklch color from data.
+ */
+
+import {useSankey} from './SankeyContext';
+
+export interface SankeyNodeProps {
+  /** Whether to show the glow effect behind nodes (default: true) */
+  glow?: boolean;
+}
+
+function oklch(c: [number, number, number], alpha: number): string {
+  return `oklch(${c[0]} ${c[1]} ${c[2]} / ${alpha})`;
+}
+
+/**
+ * Renders all node indicators in the Sankey chart.
+ *
+ * Color comes from the chart's `nodeColor` prop (global override)
+ * or each node's individual color from data.
+ */
+export function SankeyNode({glow = true}: SankeyNodeProps) {
+  const {nodes, nodeColor} = useSankey();
+
+  return (
+    <g>
+      {nodes.map(node => {
+        const fill = nodeColor || oklch(node.color, 0.9);
+        const glowFill = nodeColor || oklch(node.color, 0.12);
+
+        return (
+          <g key={node.id}>
+            {glow && (
+              <rect
+                x={node.x - 3}
+                y={node.y - 1}
+                width={node.width + 6}
+                height={node.height + 2}
+                rx={4}
+                fill={glowFill}
+                opacity={nodeColor ? 0.12 : 1}
+              />
+            )}
+            <rect
+              x={node.x}
+              y={node.y}
+              width={node.width}
+              height={node.height}
+              rx={1.5}
+              fill={fill}
+            />
+          </g>
+        );
+      })}
+    </g>
+  );
+}
+
+SankeyNode.displayName = 'SankeyNode';

package/src/Sankey/index.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+export {SankeyChart, type SankeyChartProps} from './SankeyChart';
+export {
+  SankeyLink,
+  type SankeyLinkProps,
+  type SankeyLinkColor,
+} from './SankeyLink';
+export {SankeyNode, type SankeyNodeProps} from './SankeyNode';
+export {SankeyLabel, type SankeyLabelProps} from './SankeyLabel';
+export {SankeyGrid, type SankeyGridProps} from './SankeyGrid';
+export {useSankey} from './SankeyContext';
+export type {
+  SankeyNodeDatum,
+  SankeyLinkDatum,
+  SankeyColumn,
+  SankeyColumnDef,
+  SankeyNodeLayout,
+  SankeyLinkLayout,
+  SankeyColumnLayout,
+  SankeyContext,
+} from './types';

package/src/Sankey/layout.ts

@@ -0,0 +1,219 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file layout.ts
+ * @output Pure layout algorithm — computes node and link positions
+ * @position Core logic; consumed by SankeyChart during render
+ *
+ * Accepts columns as either string[][] (simple) or SankeyColumnDef[]
+ * (with labels). Reserves margin for labels and column headers.
+ */
+
+import type {
+  SankeyNodeDatum,
+  SankeyLinkDatum,
+  SankeyColumn,
+  SankeyColumnDef,
+  SankeyNodeLayout,
+  SankeyLinkLayout,
+  SankeyColumnLayout,
+} from './types';
+
+const DEFAULT_PALETTE: Array<[number, number, number]> = [
+  [0.65, 0.2, 270],
+  [0.6, 0.17, 235],
+  [0.62, 0.16, 190],
+  [0.64, 0.18, 155],
+  [0.58, 0.15, 40],
+  [0.55, 0.14, 350],
+  [0.54, 0.15, 20],
+  [0.56, 0.13, 300],
+];
+
+export interface LayoutOptions {
+  width: number;
+  height: number;
+  nodeWidth?: number;
+  nodeGap?: number;
+  labelMargin?: number;
+  columns?: SankeyColumn[];
+}
+
+/** Normalize column input to the rich format */
+function normalizeColumns(cols: SankeyColumn[]): SankeyColumnDef[] {
+  return cols.map(c => (Array.isArray(c) ? {ids: c} : c));
+}
+
+function autoColumns(
+  nodes: SankeyNodeDatum[],
+  links: SankeyLinkDatum[],
+): SankeyColumnDef[] {
+  const inDegree = new Map<string, number>();
+  const outEdges = new Map<string, string[]>();
+  nodes.forEach(n => {
+    inDegree.set(n.id, 0);
+    outEdges.set(n.id, []);
+  });
+  links.forEach(l => {
+    inDegree.set(l.target, (inDegree.get(l.target) || 0) + 1);
+    outEdges.get(l.source)?.push(l.target);
+  });
+
+  const colMap = new Map<string, number>();
+  const queue: string[] = [];
+  nodes.forEach(n => {
+    if (inDegree.get(n.id) === 0) {
+      queue.push(n.id);
+      colMap.set(n.id, 0);
+    }
+  });
+
+  while (queue.length) {
+    const id = queue.shift();
+    if (id == null) {
+      break;
+    }
+    const col = colMap.get(id) ?? 0;
+    for (const tgt of outEdges.get(id) || []) {
+      const newCol = col + 1;
+      colMap.set(tgt, Math.max(colMap.get(tgt) || 0, newCol));
+      inDegree.set(tgt, (inDegree.get(tgt) || 0) - 1);
+      if (inDegree.get(tgt) === 0) {
+        queue.push(tgt);
+      }
+    }
+  }
+
+  const maxCol = Math.max(...Array.from(colMap.values()), 0);
+  const columns: SankeyColumnDef[] = Array.from({length: maxCol + 1}, () => ({
+    ids: [] as string[],
+  }));
+  nodes.forEach(n => {
+    columns[colMap.get(n.id) || 0].ids.push(n.id);
+  });
+  return columns;
+}
+
+export interface LayoutResult {
+  nodes: SankeyNodeLayout[];
+  links: SankeyLinkLayout[];
+  columns: SankeyColumnLayout[];
+  valueScale: number;
+  maxValue: number;
+}
+
+export function computeLayout(
+  nodes: SankeyNodeDatum[],
+  links: SankeyLinkDatum[],
+  options: LayoutOptions,
+): LayoutResult {
+  const {
+    width,
+    height,
+    nodeWidth = 20,
+    nodeGap = 14,
+    labelMargin = 28,
+  } = options;
+
+  const colDefs = options.columns
+    ? normalizeColumns(options.columns)
+    : autoColumns(nodes, links);
+  const colCount = colDefs.length;
+  const hasHeaders = colDefs.some(c => c.label);
+  const headerMargin = hasHeaders ? 20 : 0;
+
+  const nodeMap = new Map<string, SankeyNodeDatum>();
+  nodes.forEach(n => nodeMap.set(n.id, n));
+
+  // Usable height after reserving space for labels and headers
+  const usableHeight = height - labelMargin - 16 - headerMargin;
+
+  // Scale based on largest column
+  let maxColValue = 0;
+  colDefs.forEach(col => {
+    const total = col.ids.reduce(
+      (s, id) => s + (nodeMap.get(id)?.value || 0),
+      0,
+    );
+    if (total > maxColValue) {
+      maxColValue = total;
+    }
+  });
+
+  const maxNodes = Math.max(...colDefs.map(c => c.ids.length));
+  const valueScale = (usableHeight - (maxNodes - 1) * nodeGap) / maxColValue;
+  const colSpacing = colCount > 1 ? (width - nodeWidth) / (colCount - 1) : 0;
+
+  const columnLayouts: SankeyColumnLayout[] = [];
+  const layoutNodes = new Map<string, SankeyNodeLayout>();
+  let colorIdx = 0;
+
+  colDefs.forEach((col, ci) => {
+    const x = ci * colSpacing;
+    columnLayouts.push({x, label: col.label, ids: col.ids});
+
+    const totalH = col.ids.reduce(
+      (s, id) => s + (nodeMap.get(id)?.value || 0) * valueScale,
+      0,
+    );
+    const totalGap = (col.ids.length - 1) * nodeGap;
+    let y = labelMargin + (usableHeight - totalH - totalGap) / 2;
+
+    col.ids.forEach(id => {
+      const node = nodeMap.get(id);
+      if (!node) {
+        return;
+      }
+      const h = node.value * valueScale;
+      const color =
+        node.color || DEFAULT_PALETTE[colorIdx % DEFAULT_PALETTE.length];
+      colorIdx++;
+
+      layoutNodes.set(id, {
+        id,
+        label: node.label,
+        value: node.value,
+        color,
+        x,
+        y,
+        width: nodeWidth,
+        height: h,
+        column: ci,
+        _sourceOffset: 0,
+        _targetOffset: 0,
+      });
+      y += h + nodeGap;
+    });
+  });
+
+  const layoutLinks: SankeyLinkLayout[] = links.flatMap(link => {
+    const src = layoutNodes.get(link.source);
+    const tgt = layoutNodes.get(link.target);
+    if (!src || !tgt) {
+      return [];
+    }
+    const lh = link.value * valueScale;
+    const sourceY = src.y + src._sourceOffset;
+    const targetY = tgt.y + tgt._targetOffset;
+    src._sourceOffset += lh;
+    tgt._targetOffset += lh;
+    return [
+      {
+        source: src,
+        target: tgt,
+        value: link.value,
+        height: lh,
+        sourceY,
+        targetY,
+      },
+    ];
+  });
+
+  return {
+    nodes: Array.from(layoutNodes.values()),
+    links: layoutLinks,
+    columns: columnLayouts,
+    valueScale,
+    maxValue: maxColValue,
+  };
+}

package/src/Sankey/types.ts

@@ -0,0 +1,93 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file types.ts
+ * @output Sankey chart types — nodes, links, layout, and context
+ * @position Foundation types consumed by all Sankey sub-components
+ */
+
+/** A node in the Sankey diagram */
+export interface SankeyNodeDatum {
+  /** Unique identifier */
+  id: string;
+  /** Display label */
+  label: string;
+  /** Total value flowing through this node */
+  value: number;
+  /** Color in oklch format [lightness, chroma, hue] */
+  color?: [number, number, number];
+}
+
+/** A link (flow) between two nodes */
+export interface SankeyLinkDatum {
+  /** Source node ID */
+  source: string;
+  /** Target node ID */
+  target: string;
+  /** Flow value */
+  value: number;
+}
+
+/**
+ * Column definition.
+ * Simple form: string[] (just node IDs).
+ * Rich form: object with IDs, optional label, and type.
+ */
+export interface SankeyColumnDef {
+  /** Node IDs in this column */
+  ids: string[];
+  /** Column header label (rendered below the column) */
+  label?: string;
+}
+
+/** Columns can be simple string arrays or rich definitions */
+export type SankeyColumn = string[] | SankeyColumnDef;
+
+/** Computed layout position for a node */
+export interface SankeyNodeLayout {
+  id: string;
+  label: string;
+  value: number;
+  color: [number, number, number];
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  column: number;
+  _sourceOffset: number;
+  _targetOffset: number;
+}
+
+/** Computed layout position for a link */
+export interface SankeyLinkLayout {
+  source: SankeyNodeLayout;
+  target: SankeyNodeLayout;
+  value: number;
+  height: number;
+  sourceY: number;
+  targetY: number;
+}
+
+/** Resolved column info exposed to children */
+export interface SankeyColumnLayout {
+  /** X position of this column */
+  x: number;
+  /** Column header label (if provided) */
+  label?: string;
+  /** Node IDs in this column */
+  ids: string[];
+}
+
+/** Context provided by SankeyChart to children */
+export interface SankeyContext {
+  nodes: SankeyNodeLayout[];
+  links: SankeyLinkLayout[];
+  columns: SankeyColumnLayout[];
+  width: number;
+  height: number;
+  valueScale: number;
+  maxValue: number;
+  nodeWidth: number;
+  /** Global node color override (CSS string) — when set, all nodes use this color */
+  nodeColor?: string;
+}

package/src/Schedule/CalendarEvent.ts

@@ -0,0 +1,74 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CalendarEvent.ts
+ * @input ISO event definitions and PlainDate/Instant primitives
+ * @output Calendar event types and event construction helpers
+ * @position Public schedule event model; consumed by Schedule and views
+ */
+
+import {
+  plainDateFromISO,
+  type ISODateString,
+  type PlainDate,
+} from '@astryxdesign/core/utils';
+import type {TokenColor} from '@astryxdesign/core/Token';
+import type {Instant} from './types';
+
+const DATE_ONLY_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+export type ScheduleEventColor = Exclude<TokenColor, 'default'>;
+
+export interface ScheduleCategory {
+  label: string;
+  color: ScheduleEventColor;
+}
+
+export interface CalendarEventBase {
+  id: string;
+  title: string;
+  category?: string;
+}
+
+export interface CalendarDayEvent extends CalendarEventBase {
+  start: PlainDate;
+  end: PlainDate;
+}
+
+export interface CalendarInstantEvent extends CalendarEventBase {
+  start: Instant;
+  end: Instant;
+}
+
+export type CalendarEvent = CalendarDayEvent | CalendarInstantEvent;
+
+export function createEventFromISO({
+  id,
+  title,
+  category,
+  start,
+  end,
+}: {
+  id: string;
+  title: string;
+  category?: CalendarEvent['category'];
+  start: string;
+  end: string;
+}): CalendarEvent {
+  if (DATE_ONLY_RE.test(start) && DATE_ONLY_RE.test(end)) {
+    return {
+      id,
+      title,
+      category,
+      start: plainDateFromISO(start as ISODateString),
+      end: plainDateFromISO(end as ISODateString),
+    };
+  }
+  return {
+    id,
+    title,
+    category,
+    start: Date.parse(start) as Instant,
+    end: Date.parse(end) as Instant,
+  };
+}

package/src/Schedule/DayView.tsx

@@ -0,0 +1,112 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file DayView.tsx
+ * @input Schedule context and day view options
+ * @output Single-day time-grid schedule view factory
+ * @position Concrete schedule view; exported as createScheduleDayView
+ */
+
+import {
+  DATE_FORMAT_WITH_WEEKDAY,
+  plainDateAddDays,
+  plainDateFormat,
+} from '@astryxdesign/core/utils';
+import {enumerateDates, getScheduleRangeFromDates} from './dateMath';
+import {useScheduleContext} from './context';
+import {ScheduleMonthTitle, ScheduleFrame} from './shared';
+import {TimeGridView} from './TimeGridView';
+import {scheduleRangeToZonedDateTimeRange} from './zonedDateTime';
+import type {
+  PlainDate,
+  ScheduleView,
+  ScheduleViewComponentProps,
+} from './types';
+
+export interface ScheduleDayViewOptions {
+  minHour?: number;
+  maxHour?: number;
+  hourHeight?: number;
+}
+
+function ScheduleDayView({
+  options,
+}: ScheduleViewComponentProps<ScheduleDayViewOptions>) {
+  const {events, date, focusDate, timezoneID, range, isLoading} =
+    useScheduleContext();
+  const {minHour = 0, maxHour = 24, hourHeight = 100} = options;
+  const rangeDate = date.toPlainDate();
+  const days = enumerateDates(range.startDate, range.endDate);
+  const titleLabel = plainDateFormat(rangeDate, DATE_FORMAT_WITH_WEEKDAY);
+
+  return (
+    <ScheduleFrame
+      title={<ScheduleMonthTitle date={rangeDate} timezoneID={timezoneID} />}
+      titleLabel={titleLabel}
+      isLoading={isLoading}>
+      <TimeGridView
+        days={days}
+        events={events}
+        focusDate={focusDate.toPlainDate()}
+        timezoneID={timezoneID}
+        minHour={minHour}
+        maxHour={maxHour}
+        hourHeight={hourHeight}
+      />
+    </ScheduleFrame>
+  );
+}
+
+export function createScheduleDayView({
+  minHour = 0,
+  maxHour = 24,
+  hourHeight = 100,
+}: ScheduleDayViewOptions = {}): ScheduleView<ScheduleDayViewOptions> {
+  return {
+    component: ScheduleDayView,
+    options: {minHour, maxHour, hourHeight},
+    getDateRange: date => {
+      const range = getDayDateRange({
+        date: date.toPlainDate(),
+        timezoneID: date.timezoneID,
+      });
+      return scheduleRangeToZonedDateTimeRange(range, date.timezoneID);
+    },
+    getPreviousDateRange: date => {
+      const range = getDayDateRange({
+        date: plainDateAddDays(date.toPlainDate(), -1),
+        timezoneID: date.timezoneID,
+      });
+      return {
+        label: 'Previous day',
+        range: scheduleRangeToZonedDateTimeRange(range, date.timezoneID),
+      };
+    },
+    getNextDateRange: date => {
+      const range = getDayDateRange({
+        date: plainDateAddDays(date.toPlainDate(), 1),
+        timezoneID: date.timezoneID,
+      });
+      return {
+        label: 'Next day',
+        range: scheduleRangeToZonedDateTimeRange(range, date.timezoneID),
+      };
+    },
+  };
+}
+
+function getDayDateRange({
+  date,
+  timezoneID,
+}: {
+  date: PlainDate;
+  timezoneID: string;
+}) {
+  return getScheduleRangeFromDates({
+    startDate: date,
+    endDate: plainDateAddDays(date, 1),
+    timezoneID,
+  });
+}