@multiplatform.one/theme 7.7.6 → 7.10.0

package/src/theme/Intent.stories.tsx

@@ -0,0 +1,88 @@
+import { SizableText, XStack, YStack } from "tamagui";
+import { Intent, type IntentProps } from "./Intent";
+import { useIntentContext, useResolvedKnobs } from "./useResolvedKnobs";
+
+export default {
+  title: "Theme/Intent",
+  component: Intent,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "Intent activates the named Tamagui sub-theme (layer 1) and publishes the intent name through IntentContext so useResolvedKnobs merges the preset's intent overrides (layer 2). The probe is a Tamagui stack painting $background / $color and spreading the resolved surface.",
+      },
+    },
+  },
+};
+
+const intents: IntentProps["name"][] = ["accent", "error", "warning", "success"];
+
+function Probe({ label }: { label: string }) {
+  const intent = useIntentContext();
+  const { knobProps } = useResolvedKnobs();
+  const attrs = {
+    "data-intent": intent ?? "none",
+    "data-outlined": String(Boolean(knobProps.outlined)),
+    "data-fill-style": knobProps.outlined ? "outlined" : "filled",
+  } as Record<string, unknown>;
+  return (
+    <YStack
+      {...knobProps.surface}
+      {...knobProps.borderRadius}
+      backgroundColor={knobProps.outlined ? "transparent" : "$background"}
+      borderColor="$borderColor"
+      padding="$3"
+      minWidth={140}
+      testID={`intent-probe-${label}`}
+      {...attrs}
+    >
+      <SizableText color="$color" testID={`intent-text-${label}`}>
+        {label}
+      </SizableText>
+      <SizableText color="$color11" fontSize="$2">
+        context: {intent ?? "none"}
+      </SizableText>
+    </YStack>
+  );
+}
+
+/** The four intents beside an un-wrapped baseline. */
+export const main = {
+  name: "Main",
+  render: () => (
+    <XStack gap="$4" flexWrap="wrap" alignItems="flex-start">
+      <Probe label="none" />
+      {intents.map((name) => (
+        <Intent key={name} name={name}>
+          <Probe label={name} />
+        </Intent>
+      ))}
+    </XStack>
+  ),
+};
+
+/** Nesting replaces, never merges: the innermost intent wins. */
+export const nested = {
+  name: "Nested",
+  render: () => (
+    <Intent name="error">
+      <XStack gap="$4" flexWrap="wrap" alignItems="flex-start">
+        <Probe label="outer-error" />
+        <Intent name="success">
+          <Probe label="inner-success" />
+        </Intent>
+      </XStack>
+    </Intent>
+  ),
+};
+
+/** An explicit `theme` keeps the intent context but paints another Tamagui theme. */
+export const explicitTheme = {
+  name: "Explicit theme",
+  render: () => (
+    <Intent name="accent" theme="blue">
+      <Probe label="accent-as-blue" />
+    </Intent>
+  ),
+};

package/src/theme/Preset.stories.tsx

@@ -0,0 +1,80 @@
+import { SizableText, XStack, YStack } from "tamagui";
+import { Preset } from "./Preset";
+import { useResolvedKnobs } from "./useResolvedKnobs";
+
+export default {
+  title: "Theme/Preset",
+  component: Preset,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "Preset layers knob overrides on the nearest preset (cascade, the default) or replaces it (cascade={false}). The probe is a Tamagui stack spreading the resolved surface and radius, so what is measured is the stack.",
+      },
+    },
+  },
+};
+
+function Probe({ label }: { label: string }) {
+  const { knobProps } = useResolvedKnobs();
+  const attrs = {
+    "data-border-radius": String(knobProps.borderRadius.borderRadius),
+    "data-border-width": String(knobProps.surface.borderWidth),
+    "data-fill-style": knobProps.outlined ? "outlined" : "filled",
+    "data-space": String(knobProps.space),
+  } as Record<string, unknown>;
+  return (
+    <YStack
+      {...knobProps.surface}
+      {...knobProps.borderRadius}
+      backgroundColor={knobProps.outlined ? "transparent" : "$background"}
+      borderColor="$borderColor"
+      elevation={knobProps.elevation}
+      padding="$3"
+      minWidth={160}
+      testID={`preset-probe-${label}`}
+      {...attrs}
+    >
+      <SizableText>{label}</SizableText>
+      <SizableText color="$color11" fontSize="$2">
+        radius {String(knobProps.borderRadius.borderRadius)}, border{" "}
+        {String(knobProps.surface.borderWidth)}, {knobProps.outlined ? "outlined" : "filled"}
+      </SizableText>
+    </YStack>
+  );
+}
+
+/** Overrides on top of whatever the page's preset resolved. */
+export const main = {
+  name: "Main",
+  render: () => (
+    <XStack gap="$4" flexWrap="wrap" alignItems="flex-start">
+      <Probe label="inherited" />
+      <Preset overrides={{ borderRadius: "full", borderWidth: "large" }}>
+        <Probe label="full-radius" />
+      </Preset>
+      <Preset overrides={{ fillStyle: "outlined" }}>
+        <Probe label="outlined" />
+      </Preset>
+    </XStack>
+  ),
+};
+
+/** Cascade carries the parent's overrides forward; cascade={false} starts from defaults. */
+export const cascade = {
+  name: "Cascade",
+  render: () => (
+    <Preset overrides={{ borderRadius: "full" }}>
+      <XStack gap="$4" flexWrap="wrap" alignItems="flex-start">
+        <Probe label="parent-full" />
+        <Preset overrides={{ borderWidth: "large" }}>
+          <Probe label="child-cascade" />
+        </Preset>
+        <Preset cascade={false}>
+          <Probe label="child-reset" />
+        </Preset>
+      </XStack>
+    </Preset>
+  ),
+};

package/src/theme/Surface.spec.tsx

@@ -14,6 +14,12 @@ import {
 } from "./Surface";
 import { useResolvedKnobs } from "./useResolvedKnobs";
 
+// These structural context tests hold the color scheme constant.
+vi.mock(import("tamagui"), async (importOriginal) => ({
+  ...(await importOriginal()),
+  useThemeName: () => "light",
+}));
+
 let originalMatchMedia: typeof window.matchMedia;
 
 beforeEach(() => {

package/src/theme/Surface.stories.tsx

@@ -0,0 +1,91 @@
+import { SizableText, XStack, YStack } from "tamagui";
+import { Surface } from "./Surface";
+import { useResolvedKnobs } from "./useResolvedKnobs";
+
+export default {
+  title: "Theme/Surface",
+  component: Surface,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "Surface paints nothing. It declares size/density intent for a subtree and nested Surfaces clamp step-down only (LC-68). The probe below is a Tamagui stack that spreads what useResolvedKnobs resolved inside the wrapper, so the measured part is the stack, never the wrapper.",
+      },
+    },
+  },
+};
+
+/** Spreads the resolved recipe on a stack so the wrapper's effect is measurable. */
+function Probe({ label }: { label: string }) {
+  const { knobProps } = useResolvedKnobs();
+  const attrs = {
+    "data-size": String(knobProps.size),
+    "data-space": String(knobProps.space),
+    "data-size-token": String(knobProps.sizeToken),
+    "data-gap": String(knobProps.gap.gap),
+  } as Record<string, unknown>;
+  return (
+    <YStack
+      {...knobProps.surface}
+      {...knobProps.borderRadius}
+      {...knobProps.gap}
+      padding={knobProps.gap.gap}
+      testID={`surface-probe-${label}`}
+      {...attrs}
+    >
+      <SizableText fontSize={knobProps.sizeToken as never} testID={`surface-text-${label}`}>
+        {label}: token {String(knobProps.sizeToken)}, gap {String(knobProps.gap.gap)}
+      </SizableText>
+    </YStack>
+  );
+}
+
+export const main = {
+  name: "Main",
+  render: () => (
+    <XStack gap="$4" flexWrap="wrap" alignItems="flex-start">
+      <Probe label="outside" />
+      <Surface size="small">
+        <Probe label="small" />
+      </Surface>
+      <Surface size="large">
+        <Probe label="large" />
+      </Surface>
+    </XStack>
+  ),
+};
+
+/** LC-68: a large request inside a small Surface resolves small; small inside large stays small. */
+export const nestedClamp = {
+  name: "Nested clamp",
+  render: () => (
+    <XStack gap="$4" flexWrap="wrap" alignItems="flex-start">
+      <Surface size="small">
+        <Surface size="large">
+          <Probe label="large-in-small" />
+        </Surface>
+      </Surface>
+      <Surface size="large">
+        <Surface size="small">
+          <Probe label="small-in-large" />
+        </Surface>
+      </Surface>
+    </XStack>
+  ),
+};
+
+/** Density steps the gap, not the control height. */
+export const density = {
+  name: "Density",
+  render: () => (
+    <XStack gap="$4" flexWrap="wrap" alignItems="flex-start">
+      <Surface density="comfortable">
+        <Probe label="comfortable" />
+      </Surface>
+      <Surface density="compact">
+        <Probe label="compact" />
+      </Surface>
+    </XStack>
+  ),
+};

package/src/theme/ThemeProvider.stories.tsx

@@ -0,0 +1,50 @@
+import { useEffect, useState } from "react";
+import { SizableText, YStack } from "tamagui";
+
+export default {
+  title: "Theme/ThemeProvider",
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "ThemeProvider is the Storybook preview wrapper (TamaguiProvider + KnobBridge). This story measures that live provider: the html theme class and the FontKnobStyles stylesheet KnobBridge mounts. Remounting ThemeProvider inside the preview would nest TamaguiProvider, so the probe reads the one already on the page.",
+      },
+    },
+  },
+};
+
+function Probe() {
+  const [themeClass, setThemeClass] = useState("pending");
+  const [fontStyles, setFontStyles] = useState("pending");
+  useEffect(() => {
+    const html = document.documentElement;
+    setThemeClass(
+      html.classList.contains("t_dark")
+        ? "t_dark"
+        : html.classList.contains("t_light")
+          ? "t_light"
+          : "none",
+    );
+    setFontStyles(document.getElementById("mp-font-knob-styles") ? "present" : "missing");
+  }, []);
+  return (
+    <YStack
+      testID="theme-provider-probe"
+      gap="$2"
+      padding="$4"
+      {...({
+        "data-theme-class": themeClass,
+        "data-font-styles": fontStyles,
+      } as Record<string, unknown>)}
+    >
+      <SizableText>html class: {themeClass}</SizableText>
+      <SizableText>FontKnobStyles: {fontStyles}</SizableText>
+    </YStack>
+  );
+}
+
+export const main = {
+  name: "Main",
+  render: () => <Probe />,
+};

package/src/theme/Tint.stories.tsx

@@ -0,0 +1,98 @@
+import { type ReactNode, useMemo } from "react";
+import { SizableText, XStack, YStack } from "tamagui";
+import { PresetContext, usePresetContext } from "./PresetContext";
+import { defaultPreset } from "./presets";
+import { Tint, useTintDepth } from "./Tint";
+
+export default {
+  title: "Theme/Tint",
+  component: Tint,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "Tint selects tints[(depth - 1) % tints.length] from the preset and wraps children in that Tamagui sub-theme. The swatch is a Tamagui stack painting $color5 / $color11, so the hue you see is the sub-theme, not the wrapper.",
+      },
+    },
+  },
+};
+
+/** Keeps the surrounding knobs, pins the tint family to defaultPreset's four names. */
+function WithDefaultTints({ children }: { children: ReactNode }) {
+  const parent = usePresetContext();
+  const value = useMemo(
+    () => ({
+      preset: { ...(parent?.preset ?? defaultPreset), tints: defaultPreset.tints },
+      overrides: parent?.overrides,
+    }),
+    [parent],
+  );
+  return <PresetContext.Provider value={value}>{children}</PresetContext.Provider>;
+}
+
+function Swatch({ label }: { label?: string }) {
+  const depth = useTintDepth();
+  return (
+    <YStack
+      backgroundColor="$color5"
+      borderColor="$color8"
+      borderWidth={1}
+      borderRadius="$3"
+      padding="$3"
+      gap="$2"
+      testID={`tint-swatch-${label ?? depth}`}
+    >
+      <SizableText color="$color11">
+        {label ?? "depth"} {depth}
+      </SizableText>
+    </YStack>
+  );
+}
+
+/** Five nested Tints: orange, blue, purple, pink, then orange again (modulo). */
+export const main = {
+  name: "Main",
+  render: () => (
+    <WithDefaultTints>
+      <Tint>
+        <Swatch />
+        <Tint>
+          <Swatch />
+          <Tint>
+            <Swatch />
+            <Tint>
+              <Swatch />
+              <Tint>
+                <Swatch />
+              </Tint>
+            </Tint>
+          </Tint>
+        </Tint>
+      </Tint>
+    </WithDefaultTints>
+  ),
+};
+
+/** `alt` offsets the depth; `disable` keeps the depth but drops the Theme wrapper. */
+export const altAndDisable = {
+  name: "Alt and disable",
+  render: () => (
+    <WithDefaultTints>
+      <XStack gap="$4" flexWrap="wrap" alignItems="flex-start">
+        <Tint>
+          <Swatch label="plain" />
+        </Tint>
+        <Tint alt={1}>
+          <Swatch label="alt-1" />
+        </Tint>
+        <Tint alt={2}>
+          <Swatch label="alt-2" />
+        </Tint>
+        <Tint disable>
+          <Swatch label="disabled" />
+        </Tint>
+      </XStack>
+    </WithDefaultTints>
+  ),
+};

package/src/theme/chartPalette.spec.ts

@@ -1,7 +1,9 @@
 import * as Colors from "@tamagui/colors";
+import { themes as stockThemes } from "@tamagui/themes";
 import { describe, expect, it } from "vitest";
 import { resolveChartPalette } from "./chartPalette";
 import { contrastRatio, normalizeToHex, relativeLuminance } from "./colorRules";
+import { tintHueNames } from "./createThemes";
 
 // The default accent solid (accentBackground) from defaults/accent.ts.
 const lightAccent = "hsla(250, 50%, 54%, 1)";
@@ -53,6 +55,126 @@ function adjacentDistinguishable(a: string, b: string): boolean {
 }
 
 describe("resolveChartPalette", () => {
+  it("floors every categorical mark across the registered tint identities", () => {
+    for (const scheme of ["light", "dark"] as const) {
+      const cardSurfaces = Object.entries(stockThemes)
+        .filter(
+          ([name]) =>
+            name.startsWith(`${scheme}_`) &&
+            name.endsWith("_Card") &&
+            tintHueNames.has(name.split("_")[1]) &&
+            name.split("_").length === 3,
+        )
+        .map(([, theme]) => theme.background);
+      expect(cardSurfaces.length).toBeGreaterThan(0);
+      const surfaces = [
+        ...cardSurfaces,
+        ...(scheme === "light"
+          ? ["#ffffff", Colors.gray.gray2, Colors.mauve.mauve2]
+          : [Colors.grayDark.gray2, Colors.mauveDark.mauve2]),
+      ];
+      for (const hue of tintHueNames) {
+        const ramp = (Colors as unknown as Record<string, Record<string, string>>)[
+          scheme === "dark" ? `${hue}Dark` : hue
+        ];
+        const palette = resolveChartPalette({
+          scheme,
+          identitySolid: ramp[`${hue}9`],
+          identityCandidates: [ramp[`${hue}10`], ramp[`${hue}11`]],
+        });
+        for (let i = 0; i < palette.categorical.length; i++) {
+          expect(
+            adjacentDistinguishable(
+              palette.categorical[i],
+              palette.categorical[(i + 1) % palette.categorical.length],
+            ),
+            `${scheme}/${hue}: adjacent series ${i}`,
+          ).toBe(true);
+        }
+        for (const paint of [...palette.categorical, ...Object.values(palette.semantic)]) {
+          for (const surface of surfaces) {
+            const ratio = contrastRatio(
+              relativeLuminance(normalizeToHex(paint)!),
+              relativeLuminance(normalizeToHex(surface)!),
+            );
+            expect(ratio, `${scheme}/${hue}: ${paint} on ${surface}`).toBeGreaterThanOrEqual(3);
+          }
+        }
+      }
+    }
+  });
+
+  it("retains the dark cycle order while deepening its failing violet slot", () => {
+    const palette = resolveChartPalette({ scheme: "dark", identitySolid: "#aaaaaa" });
+    expect(palette.categorical.slice(1)).toEqual([
+      Colors.blueDark.blue9,
+      Colors.orangeDark.orange9,
+      Colors.greenDark.green9,
+      Colors.amberDark.amber9,
+      Colors.pinkDark.pink9,
+      Colors.tealDark.teal9,
+      Colors.violetDark.violet10,
+      Colors.redDark.red9,
+    ]);
+  });
+
+  it("keeps the valid default light order and every grass-tint series", () => {
+    expect(
+      resolveChartPalette({ scheme: "light", identitySolid: lightAccent }).categorical,
+    ).toEqual([
+      lightAccent,
+      Colors.blue.blue10,
+      Colors.orange.orange11,
+      Colors.green.green10,
+      Colors.amber.amber11,
+      Colors.pink.pink9,
+      Colors.teal.teal10,
+      Colors.red.red9,
+    ]);
+    const grass = resolveChartPalette({
+      scheme: "light",
+      identitySolid: Colors.grass.grass9,
+      identityCandidates: [Colors.grass.grass10, Colors.grass.grass11],
+    });
+    expect(grass.categorical[0]).toBe(Colors.grass.grass10);
+    expect([...grass.categorical].sort()).toEqual(
+      [
+        Colors.grass.grass10,
+        Colors.blue.blue10,
+        Colors.orange.orange11,
+        Colors.amber.amber11,
+        Colors.pink.pink9,
+        Colors.teal.teal10,
+        Colors.violet.violet9,
+        Colors.red.red9,
+      ].sort(),
+    );
+  });
+
+  it("uses the first readable identity candidate and retains a readable original", () => {
+    expect(
+      resolveChartPalette({
+        scheme: "light",
+        identitySolid: "#ffffff",
+        identityCandidates: ["var(--ink)", "#777777", "#333333"],
+      }).single,
+    ).toBe("#777777");
+    expect(
+      resolveChartPalette({
+        scheme: "light",
+        identitySolid: lightAccent,
+        identityCandidates: ["#333333"],
+      }).single,
+    ).toBe(lightAccent);
+    expect(
+      resolveChartPalette({
+        scheme: "light",
+        identitySolid: "#ffffff",
+        identityCandidates: ["#eeeeee"],
+      }).single,
+    ).toBe(Colors.violet.violet9);
+  });
+
   it("single-series takes the theme identity solid", () => {
     expect(resolveChartPalette({ scheme: "light", identitySolid: lightAccent }).single).toBe(
       lightAccent,
@@ -70,7 +192,7 @@ describe("resolveChartPalette", () => {
   it("drops the cycle hue confusable with the accent identity (violet)", () => {
     const palette = resolveChartPalette({ scheme: "light", identitySolid: lightAccent });
     expect(palette.categorical).not.toContain(Colors.violet.violet9);
-    expect(palette.categorical).toContain(Colors.blue.blue9);
+    expect(palette.categorical).toContain(Colors.blue.blue10);
     expect(palette.categorical).toHaveLength(8);
   });
 
@@ -88,11 +210,12 @@ describe("resolveChartPalette", () => {
     expect(palette.categorical).toContain(Colors.red.red9);
   });
 
-  it("drops every cycle hue within the confusable band (tomato drops red and orange)", () => {
+  it("drops every cycle hue within the confusable band (tomato drops red, orange and amber)", () => {
     const palette = resolveChartPalette({ scheme: "light", identitySolid: tomatoTintSolid });
     expect(palette.categorical).not.toContain(Colors.red.red9);
-    expect(palette.categorical).not.toContain(Colors.orange.orange9);
-    expect(palette.categorical).toHaveLength(7);
+    expect(palette.categorical).not.toContain(Colors.orange.orange11);
+    expect(palette.categorical).not.toContain(Colors.amber.amber11);
+    expect(palette.categorical).toHaveLength(6);
   });
 
   it("keeps the full cycle behind a neutral identity (gray tint)", () => {
@@ -117,7 +240,7 @@ describe("resolveChartPalette", () => {
     const light = resolveChartPalette({ scheme: "light", identitySolid: lightAccent });
     const dark = resolveChartPalette({ scheme: "dark", identitySolid: darkAccent });
     expect(light.semantic.error).toBe(Colors.red.red9);
-    expect(light.semantic.success).toBe(Colors.green.green9);
+    expect(light.semantic.success).toBe(Colors.green.green10);
     expect(light.semantic.warning).toBe(Colors.yellow.yellow11);
     expect(dark.semantic.error).toBe(Colors.redDark.red9);
     expect(dark.semantic.success).toBe(Colors.greenDark.green9);