@scalepad/ui 0.1.0

package/src/utils/avatar.ts

@@ -0,0 +1,150 @@
+/**
+ * Deterministic colour + initials helpers for identity chips (avatars,
+ * client logos, assignee swatches). Centralised here so every surface in
+ * the app — task rows, drawers, the sidebar, kanban cards, dashboards —
+ * picks the same swatch and the same letters for a given key.
+ *
+ * The picker is a simple polynomial hash that maps the key to one of 50
+ * curated hex colors. 50 is enough headroom that two adjacent
+ * client/user chips collide visually only in pathological cases — and
+ * crucially keeps every entry distinct enough to read at small sizes
+ * without bleeding into its neighbours.
+ */
+
+/**
+ * 50-entry palette of saturated mid-tones with at least ~3:1 contrast
+ * against white text (the foreground colour every avatar surface in the
+ * app uses). Chosen from Tailwind's `600`–`800` shades and balanced across
+ * the hue wheel.
+ *
+ * Per-hue contrast notes (vs `#ffffff` foreground):
+ * - The Tailwind `500` shade of greener / cyan-er families
+ *   (`#22c55e` green-500, `#10b981` emerald-500, `#14b8a6` teal-500,
+ *   `#06b6d4` cyan-500) lands at roughly 2:1–2.5:1 against white — close
+ *   to but below the conventional 3:1 floor for graphical objects, so we
+ *   skip them and start every hue at the `600` or `700` shade instead.
+ * - The same is true for yellow/amber/lime `500` shades, which were
+ *   already excluded.
+ * - For families that pass at `500` (red, orange, blue, indigo, violet,
+ *   purple, fuchsia, pink, rose) we keep the `500` plus the two darker
+ *   siblings so the palette still spans a wide hue range.
+ *
+ * Intentionally `as const` so `colorForKey` returns a literal-typed value
+ * and downstream consumers can narrow when useful.
+ */
+export const AVATAR_PALETTE = [
+  // Slate (neutral anchors so non-tagged entities still feel intentional)
+  '#64748b',
+  '#334155',
+  // Red
+  '#ef4444',
+  '#dc2626',
+  '#b91c1c',
+  // Orange
+  '#f97316',
+  '#ea580c',
+  '#c2410c',
+  // Amber (skip 500 — too light for white text)
+  '#d97706',
+  '#b45309',
+  // Yellow (skip 500 — way too light for white text)
+  '#ca8a04',
+  '#a16207',
+  // Lime (skip 500 — too light for white text)
+  '#65a30d',
+  '#4d7c0f',
+  // Green (skip 500 — `#22c55e` ≈ 2.1:1 vs white, below the 3:1 floor)
+  '#16a34a',
+  '#15803d',
+  '#166534',
+  // Emerald (skip 500 — `#10b981` ≈ 2.3:1 vs white)
+  '#059669',
+  '#047857',
+  '#065f46',
+  // Teal (skip 500 — `#14b8a6` ≈ 2.4:1 vs white)
+  '#0d9488',
+  '#0f766e',
+  '#115e59',
+  // Cyan (skip 500 — `#06b6d4` ≈ 2.6:1 vs white)
+  '#0891b2',
+  '#0e7490',
+  '#155e75',
+  // Sky
+  '#0ea5e9',
+  '#0284c7',
+  '#0369a1',
+  // Blue
+  '#3b82f6',
+  '#2563eb',
+  '#1d4ed8',
+  // Indigo
+  '#6366f1',
+  '#4f46e5',
+  '#4338ca',
+  // Violet
+  '#8b5cf6',
+  '#7c3aed',
+  '#6d28d9',
+  // Purple
+  '#a855f7',
+  '#9333ea',
+  '#7e22ce',
+  // Fuchsia
+  '#d946ef',
+  '#c026d3',
+  '#a21caf',
+  // Pink
+  '#ec4899',
+  '#db2777',
+  '#be185d',
+  // Rose
+  '#f43f5e',
+  '#e11d48',
+  '#be123c',
+] as const;
+
+export type AvatarColor = (typeof AVATAR_PALETTE)[number];
+
+/**
+ * Pick a stable swatch from `AVATAR_PALETTE` for the given identity key.
+ * The hash is intentionally tiny and unauthenticated — its only job is to
+ * spread keys across the palette so colour assignment is reproducible
+ * across renders, sessions and users without round-tripping to the
+ * server. Callers should pass a stable key (user id, client id, email)
+ * so the same identity reads as the same colour everywhere.
+ */
+export function colorForKey(key: string): AvatarColor {
+  let hash = 0;
+  for (let i = 0; i < key.length; i += 1) {
+    hash = (hash * 31 + key.charCodeAt(i)) >>> 0;
+  }
+  return AVATAR_PALETTE[hash % AVATAR_PALETTE.length]!;
+}
+
+/**
+ * Two-character initials suitable for user / assignee avatars. Splits on
+ * whitespace and combines the first letter of the first and last token —
+ * `Jane Doe` → `JD`, `Madonna` → `MA`. Returns `?` for empty input so
+ * downstream chips render the placeholder swatch instead of crashing.
+ */
+export function initials(value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed) return '?';
+  const parts = trimmed.split(/\s+/u);
+  if (parts.length === 1) {
+    return parts[0]!.slice(0, 2).toUpperCase();
+  }
+  return (parts[0]![0]! + parts[parts.length - 1]![0]!).toUpperCase();
+}
+
+/**
+ * Single-character initial suitable for client / company avatars. Just
+ * the first letter of the first whitespace-separated token, uppercased.
+ * Mirrors `initials` for empty-input handling.
+ */
+export function clientInitial(value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed) return '?';
+  const parts = trimmed.split(/\s+/u);
+  return parts[0]![0]!.toUpperCase();
+}

package/src/utils/chartHelpers.ts

@@ -0,0 +1,53 @@
+/**
+ * Determines whether a tick label should be shown based on data density
+ * Implements intelligent label skipping to prevent crowding on charts
+ *
+ * @param index - Current tick index
+ * @param dataLength - Total number of data points
+ * @param isLast - Whether this is the last tick
+ * @returns true if the label should be shown, false if it should be skipped
+ *
+ * @example
+ * // For 10 data points, shows labels at indices: 0, 3, 6, 9
+ * shouldShowTickLabel(0, 10, false) // true
+ * shouldShowTickLabel(1, 10, false) // false
+ * shouldShowTickLabel(3, 10, false) // true
+ */
+export function shouldShowTickLabel(
+  index: number,
+  dataLength: number,
+  isLast: boolean,
+): boolean {
+  // For 36+ data points, let Recharts handle label density with 'preserveEnd'
+  if (dataLength > 35) {
+    return true;
+  }
+
+  // For 10-35 data points, intelligently skip labels to avoid crowding
+  if (dataLength >= 10) {
+    // For 21-35 points, show every 6th label for consistent spacing, plus always show last
+    if (dataLength > 20) {
+      const step = 6;
+      return index % step === 0 || isLast;
+    }
+    // For 16-20 points, show exactly 4 evenly spaced labels
+    if (dataLength >= 16) {
+      const targetLabels = 4;
+      const evenIndices = Array.from({ length: targetLabels }, (_, i) =>
+        Math.round((i * (dataLength - 1)) / (targetLabels - 1)),
+      );
+      return evenIndices.includes(index);
+    }
+    // For exactly 10 points, use step of 3 for even spacing (0, 3, 6, 9)
+    if (dataLength === 10) {
+      const step = 3;
+      return index % step === 0;
+    }
+    // For 11-15 points, show every other label (plus always show last)
+    const step = 2;
+    return index % step === 0 || isLast;
+  }
+
+  // For fewer than 10 data points, show all labels
+  return true;
+}

package/src/utils/color-props.ts

@@ -0,0 +1,77 @@
+/**
+ * Design System Color Props
+ *
+ * Utilities and types for mapping semantic color tokens to CSS variables.
+ * Used by component wrappers to enforce type-safe color props.
+ */
+
+import type {
+  BackgroundColor,
+  IconColor,
+  SemanticColor,
+  StrokeColor,
+  TextColor,
+} from '../tokens';
+import type { MantineColor, StyleProp } from '@mantine/core';
+
+// Re-export color types for convenience
+export type {
+  BackgroundColor,
+  IconColor,
+  SemanticColor,
+  StrokeColor,
+  TextColor,
+};
+
+/** Special Mantine color values that should pass through without transformation */
+const PASSTHROUGH_VALUES = new Set(['inherit', 'currentColor']);
+
+/**
+ * Resolve a semantic color token name to its CSS variable.
+ *
+ * @example
+ * resolveColorToken('text-default')     // 'var(--color-text-default)'
+ * resolveColorToken('inherit')          // 'inherit'
+ * resolveColorToken(undefined)          // undefined
+ */
+export function resolveColorToken(
+  token: string | undefined,
+): StyleProp<MantineColor> | undefined {
+  if (!token || PASSTHROUGH_VALUES.has(token)) return token;
+  return `var(--color-${token.replace(/\./g, '-')})`;
+}
+
+/** Color props for text color (`c` prop) */
+export type TextColorProp = {
+  /** Text color - accepts semantic text tokens or 'inherit' */
+  c?: TextColor | 'inherit';
+};
+
+/** Color props for background color (`bg` prop) */
+export type BackgroundColorProp = {
+  /** Background color - accepts semantic background tokens */
+  bg?: BackgroundColor;
+};
+
+/** Color props for border/stroke color */
+export type StrokeColorProp = {
+  /** Border color - accepts semantic stroke tokens. Generates `1px solid var(--color-...)` */
+  borderColor?: StrokeColor;
+};
+
+/**
+ * Standard color prop overrides for layout and container components.
+ * Replaces Mantine's untyped `c`, `bg` with design-system-restricted versions.
+ */
+export type DesignSystemColorProps = TextColorProp &
+  BackgroundColorProp &
+  StrokeColorProp;
+
+/**
+ * Color prop for components that use Mantine's `color` prop (Button, Alert, etc.).
+ * These components use `color` to set their primary accent, not text/background.
+ */
+export type ComponentColorProp = {
+  /** Component accent color - accepts any semantic color token */
+  color?: SemanticColor;
+};

package/src/utils/createDesignComponent.tsx

@@ -0,0 +1,104 @@
+/**
+ * Design System Component Wrapper Factory
+ *
+ * Creates wrapped versions of Mantine components that restrict
+ * color props to design-system tokens with full type safety.
+ * Uses Mantine's `polymorphicFactory` so the resulting wrappers keep the
+ * same polymorphic/ref behavior shape expected by Mantine 9 consumers.
+ */
+
+import type { ComponentType, ElementType, Ref } from 'react';
+
+import { polymorphicFactory, type PolymorphicFactory } from '@mantine/core';
+
+import { resolveColorToken, type DesignSystemColorProps } from './color-props';
+
+/**
+ * The Mantine style props that we intercept and replace with typed versions.
+ * These are removed from the original component props via Omit.
+ */
+export type InterceptedColorProps = 'c' | 'bg';
+
+/**
+ * Given original component props P, replace the color props with our typed versions.
+ */
+export type WithDesignColors<P> = Omit<P, InterceptedColorProps> &
+  DesignSystemColorProps;
+
+/**
+ * Create a design-system-aware wrapper around a Mantine component.
+ *
+ * The wrapper:
+ * 1. Replaces `c` and `bg` props with typed versions (TextColor, BackgroundColor)
+ * 2. Adds a `borderColor` convenience prop that generates `bd="1px solid var(--color-...)"`
+ * 3. Resolves semantic token names to CSS variable references before passing to Mantine
+ * 4. Preserves polymorphic component behavior (HTML props like onClick, style, etc.)
+ * 5. Forwards refs correctly
+ *
+ * @example
+ * ```tsx
+ * import { Box as MantineBox, type BoxProps } from '@mantine/core';
+ * export const Box = createDesignComponent<BoxProps>(MantineBox, 'Box');
+ *
+ * // Usage - HTML props like onClick work because of createPolymorphicComponent:
+ * <Box bg="background-default" c="text-default" onClick={handleClick}>
+ *   Content
+ * </Box>
+ * ```
+ */
+
+type DesignComponentSource<Props extends object, DefaultRef> = ComponentType<
+  Props & { ref?: Ref<DefaultRef> }
+>;
+
+export function createDesignComponent<
+  Props extends object,
+  DefaultComponent extends ElementType,
+  DefaultRef,
+>(Component: DesignComponentSource<Props, DefaultRef>, displayName: string) {
+  const Wrapped = polymorphicFactory<
+    PolymorphicFactory<{
+      props: WithDesignColors<Props>;
+      defaultComponent: DefaultComponent;
+      defaultRef: DefaultRef;
+    }>
+  >(
+    ({
+      c,
+      bg,
+      borderColor,
+      ref,
+      ...rest
+    }: WithDesignColors<Props> &
+      DesignSystemColorProps & {
+        ref?: Ref<DefaultRef>;
+      }) => {
+      const resolvedProps: Record<string, unknown> = { ...rest, ref };
+
+      // Resolve text color
+      const resolvedC = resolveColorToken(c);
+      if (resolvedC !== undefined) {
+        resolvedProps.c = resolvedC;
+      }
+
+      // Resolve background color
+      const resolvedBg = resolveColorToken(bg);
+      if (resolvedBg !== undefined) {
+        resolvedProps.bg = resolvedBg;
+      }
+
+      // Resolve borderColor convenience prop
+      if (borderColor) {
+        const resolvedBorderColor = resolveColorToken(borderColor);
+        resolvedProps.bd = `1px solid ${resolvedBorderColor}`;
+      }
+
+      return (
+        <Component {...(resolvedProps as Props & { ref?: Ref<DefaultRef> })} />
+      );
+    },
+  );
+
+  Wrapped.displayName = displayName;
+  return Wrapped;
+}

package/src/utils/nestFlatRows.ts

@@ -0,0 +1,111 @@
+/**
+ * Options for {@link nestFlatRows}.
+ */
+export interface NestFlatRowsOptions<T> {
+  /**
+   * Extract the stable id for a row.
+   * @default (row) => (row as { id: string }).id
+   */
+  getId?: (row: T) => string;
+  /**
+   * Extract the parent id for a row. Return `null` or `undefined` for roots.
+   * @default (row) => (row as { parentId?: string | null }).parentId
+   */
+  getParentId?: (row: T) => string | null | undefined;
+  /**
+   * What to do when a row references a parentId that does not exist in the input.
+   * - `"throw"` (default): throw a descriptive `Error`.
+   * - `"drop"`: silently exclude the orphan row from the output.
+   */
+  onOrphan?: 'throw' | 'drop';
+}
+
+/**
+ * Marker type: a row that may carry nested children under `subRows`.
+ * Used by consumers that need a typed view over the nested output.
+ */
+export interface WithSubRows<T> {
+  subRows?: T[];
+}
+
+/**
+ * Convert a flat array of rows carrying `{ id, parentId? }` into a nested tree.
+ *
+ * - Root-level ordering follows the input order of rows whose `parentId` is
+ *   nullish.
+ * - Children ordering follows the input order of rows that reference a given
+ *   parent.
+ * - Input rows are never mutated. Each returned node is a shallow clone of
+ *   its source row, so calling this function repeatedly on the same input
+ *   is safe and will not accumulate duplicate `subRows` entries.
+ *
+ * By default, rows referencing an unknown `parentId` throw. Pass
+ * `{ onOrphan: "drop" }` to silently drop them (useful when the server may
+ * return partial trees).
+ *
+ * @example Nesting by default id / parentId fields
+ * ```ts
+ * nestFlatRows([
+ *   { id: 'g1', label: 'Contracts' },
+ *   { id: 'g1.a', parentId: 'g1', label: 'Acme' },
+ * ]);
+ * // => [{ id: 'g1', label: 'Contracts', subRows: [{ id: 'g1.a', parentId: 'g1', label: 'Acme' }] }]
+ * ```
+ *
+ * @example Custom accessors
+ * ```ts
+ * nestFlatRows(rows, {
+ *   getId: (r) => r.key,
+ *   getParentId: (r) => r.parent_key,
+ * });
+ * ```
+ */
+export function nestFlatRows<T>(
+  rows: readonly T[],
+  options: NestFlatRowsOptions<T> = {},
+): (T & WithSubRows<T>)[] {
+  const getId = options.getId ?? ((r: T) => (r as { id: string }).id);
+  const getParentId =
+    options.getParentId ??
+    ((r: T) => (r as { parentId?: string | null }).parentId);
+  const onOrphan = options.onOrphan ?? 'throw';
+
+  type Node = T & WithSubRows<T>;
+
+  // Build a clone per row so we never mutate caller-owned objects. `subRows`
+  // is intentionally omitted here and lazily initialized when a child is
+  // pushed onto a parent, which also overwrites any stale `subRows` that
+  // might have been present on the source row from a previous invocation.
+  const byId = new Map<string, Node>();
+  for (const row of rows) {
+    const clone = { ...row } as Node;
+    delete (clone as WithSubRows<T>).subRows;
+    byId.set(getId(row), clone);
+  }
+
+  const roots: Node[] = [];
+  for (const row of rows) {
+    const id = getId(row);
+    const parentId = getParentId(row);
+    const node = byId.get(id)!;
+
+    if (parentId == null) {
+      roots.push(node);
+      continue;
+    }
+
+    const parent = byId.get(parentId);
+    if (!parent) {
+      if (onOrphan === 'throw') {
+        throw new Error(
+          `nestFlatRows: unknown parentId "${parentId}" for row "${id}"`,
+        );
+      }
+      continue;
+    }
+
+    (parent.subRows ??= []).push(node);
+  }
+
+  return roots;
+}

package/src/utils/withStaticComponents.ts

@@ -0,0 +1,6 @@
+export function withStaticComponents<
+  TRoot extends object,
+  TStatic extends object,
+>(root: TRoot, staticComponents: TStatic): TRoot & TStatic {
+  return Object.assign(root, staticComponents);
+}