@multiplatform.one/theme 6.1.0 → 6.4.0

package/README.md

@@ -0,0 +1,73 @@
+# @multiplatform.one/theme
+
+The multiplatform.one theming engine: Tamagui color themes plus the **knobs
+system** — structural styling (radius, spacing, elevation, typography, animation)
+resolved independently of color, so one knob flip restyles a whole screen.
+
+## Install
+
+```bash
+pnpm add @multiplatform.one/theme
+```
+
+Requires `react` and `tamagui` as peers.
+
+## What it owns
+
+- **Knobs** — `useResolvedKnobs()`, `resolveKnobs()` (the only canonical mapping
+  from abstract knobs to Tamagui props), knob types and defaults
+- **Presets** — `<Preset preset="…" theme="…">` bundles knobs + intents + theme;
+  nested presets cascade, `overrides` merge by key
+- **Intents** — contextual overrides (`error`, `accent`, `warning`, `success`),
+  including intent + component overrides
+- **Recipes** — control/text/elevation state recipes (hover, press, focus-visible)
+- **Optics** — the `cornerSmoothing` knob (`round` | `smooth` squircle corners:
+  web progressive enhancement via CSS `corner-shape`, native stays round),
+  `hairline` separator treatments (0.5 device-pixel rules with a 1px low-DPI
+  fallback), and tracking-by-size in the default font faces
+- **Chart palette** — `useChartPalette()`: identity-led series colors
+  (single-series = theme identity, categorical cycle, semantic ramps) that
+  re-anchor under tints; explicit data colors always pass through
+- Theme creation (`createThemes`, `createDefaultThemeConfig`), `Tint`, layout
+  tokens, focus state, cookie persistence for SSR-safe knobs
+
+## What it must not do
+
+- No app screens and no component catalog — components live in
+  `@multiplatform.one/components`, fields in `@multiplatform.one/forms`
+
+## Usage
+
+```tsx
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { View } from "@multiplatform.one/components";
+
+export function Surface({ intent, compact, ...props }) {
+  const { knobProps, control } = useResolvedKnobs({ intent, component: "Button", compact });
+  return (
+    <View
+      {...knobProps.surface}
+      {...knobProps.borderRadius}
+      {...knobProps.panelPadding}
+      {...knobProps.gap}
+      hoverStyle={{ ...control.hoverKnobProps }}
+      pressStyle={{ ...control.pressKnobProps }}
+      {...props}
+    />
+  );
+}
+```
+
+Rules that keep knobs sound:
+
+- Always spread complete `knobProps.*` fragments — never cherry-pick resolved tokens.
+- Consumer `{...props}` spread last (the only styling eject).
+- Resolution order: Preset → intent → intent+component → size → density →
+  reduced-motion → `resolveKnobs()` override callback.
+
+Full standard: `agent-os/standards/frontend/knobs-system.md` in the
+[multiplatform.one repo](https://gitlab.com/bitspur/frappe/multiplatform.one).
+
+## License
+
+Apache-2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplatform.one/theme",
-  "version": "6.1.0",
+  "version": "6.4.0",
   "description": "Tamagui theme system for multiplatform.one",
   "keywords": [
     "multiplatform",
@@ -10,21 +10,33 @@
   ],
   "license": "Apache-2.0",
   "author": "BitSpur",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/bitspur/frappe/multiplatform.one.git",
+    "directory": "public/theme"
+  },
   "source": "src/index.ts",
+  "files": [
+    "src",
+    "!src/**/__snapshots__",
+    "types",
+    "!types/.tsbuildinfo"
+  ],
   "sideEffects": true,
   "main": "src/index.ts",
   "module": "src/index.ts",
-  "types": "src/index.ts",
+  "types": "types/index.d.ts",
   "exports": {
     "./package.json": "./package.json",
+    "./src/*": "./src/*",
     ".": {
       "source": "./src/index.ts",
-      "types": "./src/index.ts",
+      "types": "./types/index.d.ts",
       "default": "./src/index.ts"
     },
     "./audit": {
       "source": "./src/audit/index.ts",
-      "types": "./src/audit/index.ts",
+      "types": "./types/audit/index.d.ts",
       "default": "./src/audit/index.ts"
     }
   },
@@ -41,8 +53,8 @@
     "@tamagui/toast": "2.0.0-rc.41",
     "@tamagui/web": "2.0.0-rc.41",
     "react-cookie": "^8.1.2",
-    "@multiplatform.one/store": "6.1.0",
-    "@multiplatform.one/platform": "6.1.0"
+    "@multiplatform.one/store": "6.4.0",
+    "@multiplatform.one/platform": "6.4.0"
   },
   "devDependencies": {
     "@tamagui/animations-css": "2.0.0-rc.41",
@@ -57,8 +69,8 @@
     "tamagui": "2.0.0-rc.41",
     "typescript": "~5.9.3",
     "vitest": "^4.1.5",
-    "@multiplatform.one/test-utils": "6.1.0",
-    "@multiplatform.one/config": "6.1.0"
+    "@multiplatform.one/config": "6.4.0",
+    "@multiplatform.one/test-utils": "6.4.0"
   },
   "peerDependencies": {
     "@tamagui/animations-css": "^2.0.0-rc",
@@ -80,6 +92,7 @@
   },
   "scripts": {
     "test": "vitest run --coverage --coverage.provider=v8 --coverage.reporter=text --coverage.reporter=lcov --coverage.reporter=html",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "build": "rm -rf types 2>/dev/null && tsc -p tsconfig.build.json"
   }
 }

package/src/dates.spec.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from "vitest";
+import { formatAbsoluteDate, formatAbsoluteDateTime, formatRelativeTimestamp } from "./dates";
+
+// Pin locale so assertions don't depend on the host machine.
+const enUS = { locale: "en-US" } as const;
+// Reference "today" for current-year elision.
+const now = new Date(2026, 7, 12); // Aug 12, 2026
+
+describe("formatAbsoluteDate (LC-12 compact absolute register)", () => {
+  it("elides the current year by default (display register)", () => {
+    expect(formatAbsoluteDate(new Date(2026, 6, 1), { ...enUS, now })).toBe("Jul 1");
+  });
+
+  it("adds the year when not current", () => {
+    expect(formatAbsoluteDate(new Date(2025, 10, 1), { ...enUS, now })).toBe("Nov 1, 2025");
+  });
+
+  it("always shows the year for editing surfaces (year: 'always')", () => {
+    expect(formatAbsoluteDate(new Date(2026, 6, 1), { ...enUS, now, year: "always" })).toBe(
+      "Jul 1, 2026",
+    );
+  });
+
+  it("formats ISO date-only strings in UTC (no timezone day-shift)", () => {
+    expect(formatAbsoluteDate("2026-07-01", { ...enUS, now })).toBe("Jul 1");
+    expect(formatAbsoluteDate("2026-12-31", { ...enUS, now, year: "always" })).toBe("Dec 31, 2026");
+  });
+
+  it("renders empty input as empty string", () => {
+    expect(formatAbsoluteDate(null, enUS)).toBe("");
+    expect(formatAbsoluteDate(undefined, enUS)).toBe("");
+    expect(formatAbsoluteDate("", enUS)).toBe("");
+  });
+
+  it("passes unparseable strings through unchanged (honest passthrough)", () => {
+    expect(formatAbsoluteDate("not-a-date", enUS)).toBe("not-a-date");
+  });
+
+  it("never emits seconds (LC-12 VERIFY)", () => {
+    const out = formatAbsoluteDateTime(new Date(2026, 7, 9, 15, 30, 45), { ...enUS, now });
+    expect(out).not.toMatch(/:\d{2}:\d{2}/);
+  });
+});
+
+describe("formatAbsoluteDateTime (system-event register)", () => {
+  it("renders the compact absolute form", () => {
+    expect(formatAbsoluteDateTime(new Date(2026, 7, 9, 15, 30), { ...enUS, now })).toBe(
+      "Aug 9, 3:30 PM",
+    );
+  });
+
+  it("adds the year when not current", () => {
+    expect(formatAbsoluteDateTime(new Date(2025, 7, 9, 15, 30), { ...enUS, now })).toBe(
+      "Aug 9, 2025, 3:30 PM",
+    );
+  });
+});
+
+describe("formatRelativeTimestamp (feed/social register)", () => {
+  const base = Date.UTC(2026, 7, 12, 12, 0, 0);
+
+  it("covers the ladder from 'just now' to years", () => {
+    const at = (msAgo: number) => new Date(base - msAgo).toISOString();
+    expect(formatRelativeTimestamp(at(10_000), base)).toBe("just now");
+    expect(formatRelativeTimestamp(at(5 * 60_000), base)).toBe("5m ago");
+    expect(formatRelativeTimestamp(at(2 * 3_600_000), base)).toBe("2h ago");
+    expect(formatRelativeTimestamp(at(10 * 86_400_000), base)).toBe("10 days ago");
+    expect(formatRelativeTimestamp(at(60 * 86_400_000), base)).toBe("2mo ago");
+    expect(formatRelativeTimestamp(at(400 * 86_400_000), base)).toBe("1y ago");
+  });
+
+  it("passes unparseable strings through unchanged", () => {
+    expect(formatRelativeTimestamp("garbage", base)).toBe("garbage");
+  });
+});

package/src/dates.ts

@@ -0,0 +1,130 @@
+/**
+ * Canonical timestamp/date registers (LC-12 TIMESTAMP-REGISTER, Axiom 9).
+ *
+ * One formatter owns every absolute date the catalog renders — Timeline
+ * timestamps, table date cells (FieldDisplay), DatePicker display values —
+ * so the same data class never speaks in multiple voices ("2026-07-01" vs
+ * "Aug 9, 3:30 PM" vs "11/01/2026").
+ *
+ * Content class picks the register (paired with the `timestampStyle` knob):
+ *   - feeds/social       → relative ("2h ago") via `formatRelativeTimestamp`
+ *   - tables/system      → compact absolute ("Jul 1" / "Aug 9, 3:30 PM"),
+ *                          current year elided (`year: "auto"`)
+ *   - editing surfaces   → compact absolute with the year always shown
+ *                          ("Jul 1, 2026") — pickers are precision contexts
+ * No default may emit verbose locale output with seconds.
+ */
+
+export type DateInput = Date | string | number | null | undefined;
+
+export interface AbsoluteDateFormatOptions {
+  /**
+   * `"auto"` (default) elides the current year — the display register for
+   * tables, feeds, and system events. `"always"` keeps it — the editing
+   * register for picker display values.
+   */
+  year?: "auto" | "always";
+  /** Include the time component ("Aug 9, 3:30 PM"). Default false. */
+  withTime?: boolean;
+  /** BCP-47 locale forwarded to Intl. Default: system locale. */
+  locale?: string;
+  /** Reference date for current-year elision (injectable for tests). */
+  now?: Date;
+}
+
+/** ISO date-only shape ("YYYY-MM-DD"). */
+export const ISO_DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+
+interface CoercedDate {
+  date: Date;
+  /**
+   * ISO date-only strings parse as UTC midnight, so local-time formatting
+   * shifts them a day in negative-offset timezones. Format those in UTC.
+   */
+  dateOnly: boolean;
+}
+
+function coerceDateInput(value: DateInput): CoercedDate | null {
+  if (value == null || value === "") return null;
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime()) ? null : { date: value, dateOnly: false };
+  }
+  if (typeof value === "string") {
+    const dateOnly = ISO_DATE_ONLY.test(value.trim());
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? null : { date, dateOnly };
+  }
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? null : { date, dateOnly: false };
+}
+
+/**
+ * Compact absolute date — the house register for every absolute date.
+ * "Jul 1" / "Jul 1, 2025" (year auto-elided when current), or with
+ * `withTime` "Aug 9, 3:30 PM". Empty input renders "" and an unparseable
+ * string passes through unchanged (honest passthrough — never invents).
+ */
+export function formatAbsoluteDate(
+  value: DateInput,
+  options: AbsoluteDateFormatOptions = {},
+): string {
+  const coerced = coerceDateInput(value);
+  if (!coerced) return typeof value === "string" ? value : "";
+  const { date, dateOnly } = coerced;
+  const { year = "auto", withTime = false, locale, now } = options;
+  const referenceYear = (now ?? new Date()).getFullYear();
+  const displayYear = dateOnly ? date.getUTCFullYear() : date.getFullYear();
+  const intlOptions: Intl.DateTimeFormatOptions = {
+    month: "short",
+    day: "numeric",
+  };
+  if (year === "always" || displayYear !== referenceYear) {
+    intlOptions.year = "numeric";
+  }
+  if (withTime) {
+    intlOptions.hour = "numeric";
+    intlOptions.minute = "2-digit";
+  }
+  if (dateOnly) {
+    intlOptions.timeZone = "UTC";
+  }
+  try {
+    return date.toLocaleString(locale, intlOptions);
+  } catch {
+    return typeof value === "string" ? value : date.toISOString();
+  }
+}
+
+/**
+ * Compact absolute date-time ("Aug 9, 3:30 PM"; year added when not
+ * current). The system-event register (LC-12) and the tooltip form for
+ * relative timestamps.
+ */
+export function formatAbsoluteDateTime(
+  value: DateInput,
+  options: Omit<AbsoluteDateFormatOptions, "withTime"> = {},
+): string {
+  return formatAbsoluteDate(value, { ...options, withTime: true });
+}
+
+/**
+ * Relative timestamp ("just now", "5m ago", "2h ago", "10 days ago") — the
+ * feed/social register (LC-12), selected by `timestampStyle: "relative"`.
+ */
+export function formatRelativeTimestamp(value: DateInput, now: number = Date.now()): string {
+  if (value == null || value === "") return "";
+  const t = value instanceof Date ? value.getTime() : new Date(value).getTime();
+  if (Number.isNaN(t)) return typeof value === "string" ? value : "";
+  const sec = Math.floor(Math.max(0, now - t) / 1000);
+  if (sec < 60) return "just now";
+  const min = Math.floor(sec / 60);
+  if (min < 60) return `${min}m ago`;
+  const hr = Math.floor(min / 60);
+  if (hr < 24) return `${hr}h ago`;
+  const day = Math.floor(hr / 24);
+  if (day < 30) return `${day} day${day === 1 ? "" : "s"} ago`;
+  const mo = Math.floor(day / 30);
+  if (mo < 12) return `${mo}mo ago`;
+  const yr = Math.floor(day / 365);
+  return `${Math.max(1, yr)}y ago`;
+}

package/src/devWarn.spec.ts

@@ -0,0 +1,144 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  __resetDevWarnSeen,
+  devWarn,
+  warnBannedErrorWords,
+  warnBareDisabled,
+  warnCancelDisabled,
+  warnDialogTooManyActions,
+  warnOutlineNone,
+  warnPlaceholderAsLabel,
+  warnPositiveTabIndex,
+  warnSelectTooFewOptions,
+  warnTooltipOnDisabled,
+} from "./devWarn";
+
+describe("devWarn catalog (blueprint §5)", () => {
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+  let prevEnv: string | undefined;
+
+  beforeEach(() => {
+    __resetDevWarnSeen();
+    prevEnv = process.env.NODE_ENV;
+    process.env.NODE_ENV = "development";
+    warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+    __resetDevWarnSeen();
+    process.env.NODE_ENV = prevEnv;
+  });
+
+  it("no-ops in production", () => {
+    process.env.NODE_ENV = "production";
+    devWarn("two-primaries", { component: "ActionBar" });
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("dedupes identical keys", () => {
+    devWarn("two-primaries", { component: "ActionBar", id: "r1" });
+    devWarn("two-primaries", { component: "ActionBar", id: "r1" });
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("placeholder-as-label", () => {
+    warnPlaceholderAsLabel({ placeholder: "Name", component: "FieldLayout", id: "n" });
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("placeholder-as-label"));
+    __resetDevWarnSeen();
+    warnSpy.mockClear();
+    warnPlaceholderAsLabel({ placeholder: "Name", label: "Name" });
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("banned-error-word covers DG-COPY-02 list including error", () => {
+    warnBannedErrorWords("Invalid email", { component: "Toast" });
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("banned-error-word"));
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("word=invalid"));
+    __resetDevWarnSeen();
+    warnSpy.mockClear();
+    warnBannedErrorWords("An error occurred", { component: "Alert" });
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("word=error"));
+    __resetDevWarnSeen();
+    warnSpy.mockClear();
+    warnBannedErrorWords("Enter an email address");
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("bare-disabled", () => {
+    warnBareDisabled({ disabled: true, component: "Button" });
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("bare-disabled"));
+    __resetDevWarnSeen();
+    warnSpy.mockClear();
+    warnBareDisabled({ disabled: true, disabledReason: "Needs approval" });
+    expect(warnSpy).not.toHaveBeenCalled();
+    warnBareDisabled({ disabled: true, skip: true });
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("cancel-disabled (DG-ACT-05) fires only for a truthy disable", () => {
+    warnCancelDisabled({ disabled: true, component: "ConfirmDialog" });
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("cancel-disabled"));
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("component=ConfirmDialog"));
+    __resetDevWarnSeen();
+    warnSpy.mockClear();
+    warnCancelDisabled({ disabled: false, component: "ActionBar" });
+    warnCancelDisabled({ component: "ActionBar" });
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("dialog-too-many-actions (DG-OVL-04) caps at 2 with allowManyActions eject", () => {
+    warnDialogTooManyActions({ count: 3, component: "ActionBar", id: "dlg" });
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("dialog-too-many-actions"));
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("count=3"));
+    __resetDevWarnSeen();
+    warnSpy.mockClear();
+    warnDialogTooManyActions({ count: 2, component: "ActionBar" });
+    warnDialogTooManyActions({ count: 1, component: "ConfirmDialog" });
+    warnDialogTooManyActions({ count: 5, allowManyActions: true, component: "ConfirmDialog" });
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("select-too-few-options suggests RadioGroup / ToggleGroup", () => {
+    warnSelectTooFewOptions({ count: 3, component: "Select" });
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("select-too-few-options"));
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("suggest=RadioGroup"));
+    __resetDevWarnSeen();
+    warnSpy.mockClear();
+    warnSelectTooFewOptions({ count: 2 });
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("suggest=ToggleGroup"));
+    __resetDevWarnSeen();
+    warnSpy.mockClear();
+    warnSelectTooFewOptions({ count: 6 });
+    warnSelectTooFewOptions({ count: 3, multiple: true });
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("positive-tabindex", () => {
+    warnPositiveTabIndex({ value: 2, component: "Button" });
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("positive-tabindex"));
+    __resetDevWarnSeen();
+    warnSpy.mockClear();
+    warnPositiveTabIndex({ value: 0 });
+    warnPositiveTabIndex({ value: -1 });
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("tooltip-on-disabled", () => {
+    warnTooltipOnDisabled({ childDisabled: true });
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("tooltip-on-disabled"));
+    __resetDevWarnSeen();
+    warnSpy.mockClear();
+    warnTooltipOnDisabled({ childDisabled: false });
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("outline-none (W12 / DG-A11Y-01)", () => {
+    warnOutlineNone({ outlineStyle: "none" }, { component: "Input.Box" });
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("outline-none"));
+    __resetDevWarnSeen();
+    warnSpy.mockClear();
+    warnOutlineNone({ outlineWidth: 2, outlineStyle: "solid", outlineColor: "$outlineColor" });
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+});