pixelize-native-library 1.0.7 → 1.2.1

package/lib/typescript/theme/platform/motion.native.d.ts

@@ -0,0 +1,35 @@
+export declare const springs: {
+    readonly spatialFast: {
+        readonly stiffness: 800;
+        readonly damping: 33.94;
+        readonly mass: 1;
+    };
+    readonly spatialDefault: {
+        readonly stiffness: 380;
+        readonly damping: 31.19;
+        readonly mass: 1;
+    };
+    readonly spatialSlow: {
+        readonly stiffness: 200;
+        readonly damping: 22.63;
+        readonly mass: 1;
+    };
+    readonly effectsFast: {
+        readonly stiffness: 3800;
+        readonly damping: 123.29;
+        readonly mass: 1;
+    };
+    readonly effectsDefault: {
+        readonly stiffness: 1600;
+        readonly damping: 80;
+        readonly mass: 1;
+    };
+    readonly effectsSlow: {
+        readonly stiffness: 800;
+        readonly damping: 56.57;
+        readonly mass: 1;
+    };
+};
+export type SpringKey = keyof typeof springs;
+export type SpringConfig = typeof springs[SpringKey];
+//# sourceMappingURL=motion.native.d.ts.map

package/lib/typescript/theme/platform/stateLayer.native.d.ts

@@ -0,0 +1,11 @@
+import type { ColorScheme } from '../tokens/types';
+export declare const STATE_LAYER_OPACITY: {
+    readonly pressed: 0.1;
+    readonly focus: 0.1;
+    readonly hover: 0.08;
+    readonly dragged: 0.16;
+    readonly disabled: 0.38;
+};
+export declare function stateLayerScrim(mode: ColorScheme): '#000000' | '#ffffff';
+export declare const rippleColor: (mode: ColorScheme) => string;
+//# sourceMappingURL=stateLayer.native.d.ts.map

package/lib/typescript/theme/platform/surfaces.native.d.ts

@@ -0,0 +1,8 @@
+import type { ColorScheme, PaletteProps } from '../tokens/types';
+export type ElevatedSurfaceRoles = {
+    elevated1: string;
+    elevated2: string;
+    elevated3: string;
+};
+export declare function elevatedSurfaces(palette: PaletteProps, mode: ColorScheme): ElevatedSurfaceRoles | null;
+//# sourceMappingURL=surfaces.native.d.ts.map

package/lib/typescript/theme/provider/PixelizeProvider.d.ts

@@ -1,81 +1,4 @@
-import type { ReactNode } from 'react';
-import { space, radii, fontSizes, fontWeights, lineHeights, letterSpacings, borderWidths, breakpoints, zIndices } from '../tokens';
-import type { ColorScheme, ElevationLevel, PaletteProps, RoleColors, ThemeName } from '../tokens';
-import type { ElevationStyle, FontStyleForWeight, FontWeightValue } from '../platform';
-import type { ColorModeStorageAdapter, ThemeMode } from './colorModeStorage';
-/**
- * The fully resolved theme for one (brand, resolvedMode): role colours resolved to plain strings,
- * the unitless numeric scale, and the platform-rendered pieces a token cannot hold (RN shadow props,
- * a font-style resolver). This is what `useTheme()` returns; component modules read it, never the
- * raw palette directly.
- */
-export type Theme = {
-    brand: ThemeName;
-    /** The resolved mode this theme was built for — never `'system'`. */
-    mode: ColorScheme;
-    /** Semantic role colours as resolved values. The `useThemeColors()` escape hatch returns this. */
-    colors: RoleColors;
-    /** The raw ramps, for the rare consumer that needs a specific rung the roles don't name. */
-    palette: PaletteProps;
-    space: typeof space;
-    radii: typeof radii;
-    fontSizes: typeof fontSizes;
-    fontWeights: typeof fontWeights;
-    lineHeights: typeof lineHeights;
-    letterSpacings: typeof letterSpacings;
-    borderWidths: typeof borderWidths;
-    breakpoints: typeof breakpoints;
-    zIndices: typeof zIndices;
-    /** Elevation levels already rendered to RN shadow props. Mode-independent — shared across themes. */
-    elevation: Record<ElevationLevel, ElevationStyle>;
-    /** A weight → RN text style, bound to whether the app has registered Inter. */
-    fontStyleForWeight: (weight: FontWeightValue) => FontStyleForWeight;
-};
-export type ThemeModeValue = {
-    /** The user's selection: `'light' | 'dark' | 'system'`. */
-    mode: ThemeMode;
-    /** What `system` currently resolves to, tracking the OS live. */
-    resolvedMode: ColorScheme;
-    /** Persists the choice and switches the theme. */
-    setMode: (mode: ThemeMode) => void;
-    /** The active brand. */
-    brand: ThemeName;
-    /** Persists the choice and switches the theme — mirrors `setMode`. */
-    setBrand: (brand: ThemeName) => void;
-};
-export type PixelizeProviderProps = {
-    children: ReactNode;
-    /**
-     * Initial brand. A persisted user choice wins over this. Defaults to `zinc` (the shadcn look).
-     * Read once on mount, like `mode` below — change it afterward via `setBrand` from
-     * `useThemeMode()`, not by re-passing a different prop value.
-     */
-    brand?: ThemeName;
-    /** Initial mode. A persisted user choice wins over this. Defaults to `system`. */
-    mode?: ThemeMode;
-    /** Persistence adapter. Absent → in-memory (choice lost on restart) + a dev warning. */
-    storage?: ColorModeStorageAdapter;
-    storageKey?: string;
-    /** Storage key for the brand choice — separate from `storageKey` (mode) so a plain-string
-     * adapter never has to encode two values into one slot. */
-    brandStorageKey?: string;
-    /**
-     * Whether the app has registered the Inter faces (`useFonts({...})`). Defaults to `false`: without
-     * this the library must use the always-safe system font, since an unregistered face degrades
-     * inconsistently across platforms. Pass `interLoaded={fontsLoaded}` once loading resolves.
-     */
-    interLoaded?: boolean;
-};
-/**
- * Two contexts, on purpose. `ThemeContext` holds the heavy resolved `Theme`; `ThemeModeContext` holds
- * the small mode-control triple. Both provider values are memoised on their true inputs, so:
- *  - a mode flip recomputes the theme exactly ONCE and re-renders each consumer once, and
- *  - an OS colour change while the mode is pinned (`resolvedMode` unchanged) keeps BOTH values
- *    reference-stable, so it re-renders nobody.
- * Splitting also means a `useThemeMode()` reader isn't invalidated by unrelated theme-object churn
- * and vice versa.
- */
-export declare const ThemeContext: import("react").Context<Theme | undefined>;
-export declare const ThemeModeContext: import("react").Context<ThemeModeValue | undefined>;
-export declare function PixelizeProvider({ children, brand: brandProp, mode, storage: storageProp, storageKey, brandStorageKey, interLoaded, }: PixelizeProviderProps): import("react").JSX.Element;
+import type { PixelizeProviderProps } from './types';
+export type { Theme, ThemeModeValue, PixelizeProviderProps } from './types';
+export declare function PixelizeProvider({ children, brand: brandProp, mode, storage: storageProp, storageKey, brandStorageKey, interLoaded, palette: paletteProp, haptics: hapticsProp, }: PixelizeProviderProps): import("react").JSX.Element;
 //# sourceMappingURL=PixelizeProvider.d.ts.map

package/lib/typescript/theme/provider/ThemeContext.d.ts

@@ -0,0 +1,4 @@
+import type { Theme, ThemeModeValue } from './types';
+export declare const ThemeContext: import("react").Context<Theme | undefined>;
+export declare const ThemeModeContext: import("react").Context<ThemeModeValue | undefined>;
+//# sourceMappingURL=ThemeContext.d.ts.map

package/lib/typescript/theme/provider/index.d.ts

@@ -1,8 +1,9 @@
 export { PixelizeProvider } from './PixelizeProvider';
-export type { PixelizeProviderProps, Theme, ThemeModeValue } from './PixelizeProvider';
+export type { PixelizeProviderProps, Theme, ThemeModeValue } from './types';
 export { useTheme } from './useTheme';
 export { useThemeColors } from './useThemeColors';
 export { useThemeMode } from './useThemeMode';
 export { createAsyncStorageAdapter, memoryStorageAdapter, isThemeMode, isThemeName, DEFAULT_STORAGE_NAMESPACE, DEFAULT_BRAND_STORAGE_NAMESPACE, } from './colorModeStorage';
 export type { ColorModeStorageAdapter, AsyncStorageLike, ThemeMode } from './colorModeStorage';
+export { THEME_NAMES, DEFAULT_THEME, loadPalette, loadPaletteSync } from './loadPalette';
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/theme/provider/loadPalette.d.ts

@@ -0,0 +1,9 @@
+import type { ColorScheme, PaletteProps, ThemeName } from '../tokens/types';
+/** Brand roster without importing any palette modules. */
+export declare const THEME_NAMES: readonly ["zinc", "lavender", "meadow", "radiant", "skyline", "slate", "emerald", "rosewood", "storefront"];
+export declare const DEFAULT_THEME: ThemeName;
+/** Loads one brand's palette for the given mode — only that brand's file is fetched. */
+export declare function loadPalette(brand: ThemeName, mode: ColorScheme): Promise<PaletteProps>;
+/** Synchronous palette for provider mount — static requires so Metro can bundle the example app. */
+export declare function loadPaletteSync(brand: ThemeName, mode: ColorScheme): PaletteProps;
+//# sourceMappingURL=loadPalette.d.ts.map

package/lib/typescript/theme/provider/types.d.ts

@@ -0,0 +1,49 @@
+import type { ReactNode } from 'react';
+import type { ColorScheme, ElevationLevel, PaletteProps, RoleColors, ThemeName } from '../tokens';
+import { space, radii, fontSizes, fontWeights, lineHeights, letterSpacings, borderWidths, breakpoints, zIndices } from '../tokens';
+import type { ElevationStyle, FontStyleForWeight, FontWeightValue } from '../platform';
+import type { ElevatedSurfaceRoles } from '../platform/surfaces.native';
+import type { ColorModeStorageAdapter, ThemeMode } from './colorModeStorage';
+export type Theme = {
+    brand: ThemeName;
+    mode: ColorScheme;
+    colors: RoleColors;
+    /** Dark-mode elevated surfaces — null in light mode. */
+    elevatedSurfaces: ElevatedSurfaceRoles | null;
+    palette: PaletteProps;
+    space: typeof space;
+    radii: typeof radii;
+    fontSizes: typeof fontSizes;
+    fontWeights: typeof fontWeights;
+    lineHeights: typeof lineHeights;
+    letterSpacings: typeof letterSpacings;
+    borderWidths: typeof borderWidths;
+    breakpoints: typeof breakpoints;
+    zIndices: typeof zIndices;
+    elevation: Record<ElevationLevel, ElevationStyle>;
+    fontStyleForWeight: (weight: FontWeightValue) => FontStyleForWeight;
+};
+export type ThemeModeValue = {
+    mode: ThemeMode;
+    resolvedMode: ColorScheme;
+    setMode: (mode: ThemeMode) => void;
+    brand: ThemeName;
+    setBrand: (brand: ThemeName) => void;
+};
+export type PixelizeProviderProps = {
+    children: ReactNode;
+    brand?: ThemeName;
+    mode?: ThemeMode;
+    storage?: ColorModeStorageAdapter;
+    storageKey?: string;
+    brandStorageKey?: string;
+    interLoaded?: boolean;
+    /** Runtime-selected palette — wins over `brand` when provided. */
+    palette?: PaletteProps;
+    /**
+     * Haptic feedback for interactive components. Defaults to enabled when `setHapticsModule` has been
+     * called at app startup, disabled otherwise. No-ops on web.
+     */
+    haptics?: boolean;
+};
+//# sourceMappingURL=types.d.ts.map

package/lib/typescript/theme/provider/useTheme.d.ts

@@ -1,4 +1,3 @@
-import type { Theme } from './PixelizeProvider';
-/** The full resolved theme: role colours, the numeric scale, and platform-rendered elevation/fonts. */
+import type { Theme } from './types';
 export declare function useTheme(): Theme;
 //# sourceMappingURL=useTheme.d.ts.map

package/lib/typescript/theme/provider/useThemeMode.d.ts

@@ -1,4 +1,4 @@
-import type { ThemeModeValue } from './PixelizeProvider';
+import type { ThemeModeValue } from './types';
 /** `{ mode, resolvedMode, setMode }` for a theme switcher. Reads the light mode-control context. */
 export declare function useThemeMode(): ThemeModeValue;
 //# sourceMappingURL=useThemeMode.d.ts.map

package/lib/typescript/theme/tokens/assertPalette.d.ts

@@ -0,0 +1,10 @@
+import type { PaletteProps } from "./types";
+declare const REQUIRED_TOKENS: readonly ["gradient", "primary", "secondary", "tertiary", "transparent", "black", "white", "semantic", "gray", "red", "orange", "yellow", "green", "teal", "blue", "cyan", "purple", "pink", "backgroundColor", "background", "text", "header", "placeholder", "boxShadow", "sidebar", "boxborder", "border", "table", "disabled", "semanticText"];
+type Unlisted = Exclude<keyof PaletteProps, (typeof REQUIRED_TOKENS)[number]>;
+export type AllPaletteTokensListed = Unlisted extends never ? true : ["unlisted token", Unlisted];
+export declare const allPaletteTokensListed: AllPaletteTokensListed;
+export declare const missingPaletteTokens: (palette: unknown) => string[];
+/** Fails once, loudly, where a palette enters — never as a wrong colour deep in a screen. */
+export declare const assertPalette: (palette: unknown, source: string) => PaletteProps;
+export {};
+//# sourceMappingURL=assertPalette.d.ts.map

package/lib/typescript/theme/tokens/brands/emerald/palette.light.d.ts

@@ -1,4 +1,5 @@
-import type { PaletteProps } from "../../types";
-declare const palette: PaletteProps;
-export default palette;
+import type { BrandPaletteSource } from "../../types";
+export declare const source: BrandPaletteSource;
+declare const _default: import("../..").PaletteProps;
+export default _default;
 //# sourceMappingURL=palette.light.d.ts.map

package/lib/typescript/theme/tokens/brands/lavender/palette.light.d.ts

@@ -1,4 +1,5 @@
-import type { PaletteProps } from "../../types";
-declare const palette: PaletteProps;
-export default palette;
+import type { BrandPaletteSource } from "../../types";
+export declare const source: BrandPaletteSource;
+declare const _default: import("../..").PaletteProps;
+export default _default;
 //# sourceMappingURL=palette.light.d.ts.map

package/lib/typescript/theme/tokens/brands/meadow/palette.light.d.ts

@@ -1,4 +1,5 @@
-import type { PaletteProps } from "../../types";
-declare const palette: PaletteProps;
-export default palette;
+import type { BrandPaletteSource } from "../../types";
+export declare const source: BrandPaletteSource;
+declare const _default: import("../..").PaletteProps;
+export default _default;
 //# sourceMappingURL=palette.light.d.ts.map

package/lib/typescript/theme/tokens/brands/radiant/palette.light.d.ts

@@ -1,4 +1,5 @@
-import type { PaletteProps } from "../../types";
-declare const palette: PaletteProps;
-export default palette;
+import type { BrandPaletteSource } from "../../types";
+export declare const source: BrandPaletteSource;
+declare const _default: import("../..").PaletteProps;
+export default _default;
 //# sourceMappingURL=palette.light.d.ts.map

package/lib/typescript/theme/tokens/brands/rosewood/palette.light.d.ts

@@ -1,4 +1,5 @@
-import type { PaletteProps } from "../../types";
-declare const palette: PaletteProps;
-export default palette;
+import type { BrandPaletteSource } from "../../types";
+export declare const source: BrandPaletteSource;
+declare const _default: import("../..").PaletteProps;
+export default _default;
 //# sourceMappingURL=palette.light.d.ts.map

package/lib/typescript/theme/tokens/brands/skyline/palette.light.d.ts

@@ -1,4 +1,5 @@
-import type { PaletteProps } from "../../types";
-declare const palette: PaletteProps;
-export default palette;
+import type { BrandPaletteSource } from "../../types";
+export declare const source: BrandPaletteSource;
+declare const _default: import("../..").PaletteProps;
+export default _default;
 //# sourceMappingURL=palette.light.d.ts.map

package/lib/typescript/theme/tokens/brands/slate/palette.light.d.ts

@@ -1,4 +1,5 @@
-import type { PaletteProps } from "../../types";
-declare const palette: PaletteProps;
-export default palette;
+import type { BrandPaletteSource } from "../../types";
+export declare const source: BrandPaletteSource;
+declare const _default: import("../..").PaletteProps;
+export default _default;
 //# sourceMappingURL=palette.light.d.ts.map

package/lib/typescript/theme/tokens/brands/storefront/palette.light.d.ts

@@ -1,4 +1,5 @@
-import type { PaletteProps } from "../../types";
-declare const palette: PaletteProps;
-export default palette;
+import type { BrandPaletteSource } from "../../types";
+export declare const source: BrandPaletteSource;
+declare const _default: import("../..").PaletteProps;
+export default _default;
 //# sourceMappingURL=palette.light.d.ts.map

package/lib/typescript/theme/tokens/brands/zinc/palette.light.d.ts

@@ -1,4 +1,5 @@
-import type { PaletteProps } from "../../types";
-declare const palette: PaletteProps;
-export default palette;
+import type { BrandPaletteSource } from "../../types";
+export declare const source: BrandPaletteSource;
+declare const _default: import("../..").PaletteProps;
+export default _default;
 //# sourceMappingURL=palette.light.d.ts.map

package/lib/typescript/theme/tokens/builders/finalizePalette.d.ts

@@ -0,0 +1,4 @@
+import type { BrandPaletteSource, PaletteProps } from "../types";
+export declare function finalizePalette(source: BrandPaletteSource): PaletteProps;
+export default finalizePalette;
+//# sourceMappingURL=finalizePalette.d.ts.map

package/lib/typescript/theme/tokens/builders/liftToContrast.d.ts

@@ -0,0 +1,9 @@
+export declare const DARK_CANVAS_LUMINANCE = 0.2;
+export declare const isDarkCanvas: (canvas: string) => boolean;
+export declare function liftToContrast(hex: string, backdrop: string, target: number): string;
+/**
+ * Mirror of `liftToContrast`: walks ink TOWARD the backdrop, stopping at the last step that
+ * still clears `target`. For ink that must stay legible without reading as body copy.
+ */
+export declare function softenToContrast(hex: string, backdrop: string, target: number): string;
+//# sourceMappingURL=liftToContrast.d.ts.map

package/lib/typescript/theme/tokens/builders/placeholderInk.d.ts

@@ -0,0 +1,13 @@
+import type { PaletteProps } from "../types";
+/** A field always renders on at least one surface — the first is the reference backdrop. */
+export type FieldSurfaces = readonly [string, ...string[]];
+/**
+ * The hint ink for a field: the rung the brand authored, guaranteed to clear `PLACEHOLDER_TEXT`
+ * on every surface a field can land on. The surface list is the caller's — a field's fill differs
+ * by platform, the resolution does not.
+ *
+ * It does not walk the rung toward AA in either direction. Held to 4.5 the hint stopped reading
+ * as a hint; softening back down again undershot on the next surface.
+ */
+export declare const placeholderInkOn: (palette: PaletteProps, surfaces: FieldSurfaces) => string;
+//# sourceMappingURL=placeholderInk.d.ts.map

package/lib/typescript/theme/tokens/builders/semanticText.d.ts

@@ -0,0 +1,4 @@
+import type { SemanticRamps, SemanticTextTokens, SemanticTone } from "../types";
+export declare const SEMANTIC_TONES: readonly SemanticTone[];
+export declare const buildSemanticText: (semantic: SemanticRamps, canvas: string) => SemanticTextTokens;
+//# sourceMappingURL=semanticText.d.ts.map

package/lib/typescript/theme/tokens/builders/surfaceRungs.d.ts

@@ -0,0 +1,12 @@
+import type { BrandPaletteSource, PaletteProps, SemanticTextTokens } from "../types";
+/**
+ * A hint is held to the non-text floor, not the body-text one. Deliberate: at 4.5 an empty field
+ * reads as one already typed into. See THEME-CONTRACT.md.
+ */
+export declare const PLACEHOLDER_TEXT = 3;
+export declare const namedSurfaces: (p: BrandPaletteSource | PaletteProps) => string[];
+/** The surface an ink is closest to — clearing it clears every other one. */
+export declare const hardestSurface: (ink: string, surfaces: string[]) => string;
+export declare function withSurfaceRungs(source: BrandPaletteSource): BrandPaletteSource;
+export declare const liftSemanticText: (semanticText: SemanticTextTokens, surfaces: string[]) => SemanticTextTokens;
+//# sourceMappingURL=surfaceRungs.d.ts.map

package/lib/typescript/theme/tokens/index.d.ts

@@ -17,5 +17,10 @@ export * from "./builders/accentText";
 export * from "./builders/buildBrandTokens";
 export * from "./builders/buildDarkPalette";
 export * from "./builders/color";
+export * from "./builders/liftToContrast";
+export * from "./builders/placeholderInk";
+export * from "./builders/semanticText";
+export * from "./builders/finalizePalette";
 export * from "./roles";
+export * from "./assertPalette";
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/theme/tokens/roles/index.d.ts

@@ -23,6 +23,13 @@ export type StatusColors = {
     onSolid: string;
     /** Status text on `subtle`, ≥ 4.5:1 against it. */
     text: string;
+    /** Label to use when `text` is used as a FULL-BLEED FILL instead of as a text colour (a banner's
+     *  solid variant) — recomputed, not reused from `onSolid`: `onSolid` is tuned for `solid`
+     *  (badge/toast scale), which measures only 1.8–2.6:1 against a near-white canvas for
+     *  success/warning/info on every brand — too low for WCAG 1.4.11 at page-width. `text` itself
+     *  already clears 1.4.11 against canvas (it's proven against `subtle`, a near-canvas tint), so it
+     *  doubles as the fill; `onText` is its own best label, not `text`'s original dark-on-light pairing. */
+    onText: string;
     /** Faint status-tinted background (chip/alert fill). */
     subtle: string;
     /** Decorative status outline for the chip. */
@@ -41,6 +48,7 @@ export type RoleColors = {
     fg: {
         default: string;
         muted: string;
+        placeholder: string;
         subtle: string;
         disabled: string;
     };

package/lib/typescript/theme/tokens/types.d.ts

@@ -23,12 +23,10 @@ export type OpacityRamp = {
 export type BrandRamp = Ramp & {
     opacity: OpacityRamp;
 };
-export type SemanticRamps = {
-    success: Ramp;
-    error: Ramp;
-    warning: Ramp;
-    info: Ramp;
-};
+export type SemanticTone = "success" | "error" | "warning" | "info";
+export type SemanticRamps = Record<SemanticTone, Ramp>;
+/** Each tone as INK on the canvas, resolved to 4.5:1. `semantic[tone][500]` is a fill, never text. */
+export type SemanticTextTokens = Record<SemanticTone, string>;
 /** Two-tone brand gradient. Each brand overrides with its own pair. */
 export type Gradient = {
     from: string;
@@ -59,7 +57,7 @@ export type BackgroundColorProps = {
     tableHeader: string;
 };
 export type PaletteProps = {
-    gradient?: Gradient;
+    gradient: Gradient;
     primary: BrandRamp;
     secondary: BrandRamp;
     tertiary: BrandRamp;
@@ -92,7 +90,10 @@ export type PaletteProps = {
         hover: Ramp;
     };
     disabled: Ramp;
+    semanticText: SemanticTextTokens;
 };
+/** What a brand authors by hand: every token required, derived ones excluded. */
+export type BrandPaletteSource = Omit<PaletteProps, "semanticText">;
 /**
  * Brand identities the library ships. `zinc` is the mobile default (the shadcn look); the other
  * eight mirror web. Web has no `zinc` yet and is adopting these values, so this stays a superset.