pixelize-native-library 1.2.0 → 1.3.0

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

@@ -8,6 +8,15 @@
 export { rem, hairline } from './units.native';
 export { elevation } from './elevation.native';
 export type { ElevationStyle } from './elevation.native';
+export { highlight, highlightLevels, composeBoxShadow } from './highlight.native';
+export type { HighlightLevel } from './highlight.native';
+export { elevatedSurfaces } from './surfaces.native';
+export type { ElevatedSurfaceRoles } from './surfaces.native';
+export { STATE_LAYER_OPACITY, rippleColor, stateLayerScrim } from './stateLayer.native';
+export { floatingBackground, floatingSurfaceStyle } from './floatingSurface.native';
+export type { FloatingLevel } from './floatingSurface.native';
+export { springs } from './motion.native';
+export type { SpringConfig, SpringKey } from './motion.native';
 export { interFontFamilies, systemFontFamily, fontStyleForWeight } from './fonts.native';
 export type { FontWeightValue, FontStyleForWeight } from './fonts.native';
 export { getSystemColorMode, subscribeToSystemColorMode } from './colorScheme.native';

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

@@ -1,15 +1,35 @@
-export declare const motionDurations: {
-    readonly instant: 0;
-    readonly fast: 150;
-    readonly normal: 200;
-    readonly slow: 300;
+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 declare const motionEasings: {
-    standard: "ease-in-out";
-    enter: "ease-out";
-    exit: "ease-in";
-    snap: "linear";
-};
-export type MotionDuration = keyof typeof motionDurations;
-export type MotionEasing = keyof typeof motionEasings;
+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,4 +1,4 @@
 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, }: PixelizeProviderProps): import("react").JSX.Element;
+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/types.d.ts

@@ -2,11 +2,14 @@ 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;
@@ -37,5 +40,10 @@ export type PixelizeProviderProps = {
     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/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/accentText.d.ts

@@ -7,6 +7,9 @@
  * that fixes those, rather than shipping broken until someone notices.
  */
 import type { Ramp } from "../types";
+export declare const pickAccentText: (primary: Ramp, canvas: string) => string;
+export declare const accentTextOnCanvas: (scale: Ramp, canvas: string) => string;
+export declare const onGradient: (from: string, to: string, white: string, black: string) => string;
 /** The two candidate labels. Near-white and near-black, not #fff/#000 — the shadcn look. */
 export declare const ON_ACCENT_LIGHT = "#fafafa";
 export declare const ON_ACCENT_DARK = "#18181b";

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

@@ -0,0 +1,4 @@
+import type { BrandRamp } from "../types";
+export declare function buildRamp(hex500: string, towardLowRungs: string, towardHighRungs: string): Omit<BrandRamp, "opacity">;
+export declare function buildBrandScale(hex500: string, towardLow: string, towardHigh: string): BrandRamp;
+//# sourceMappingURL=buildBrandScale.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/gradientInk.d.ts

@@ -0,0 +1,9 @@
+import type { Gradient } from "../types";
+export type { Gradient };
+export type ResolvedGradient = Gradient & {
+    ink: string;
+};
+export declare const inkSafeGradient: (gradient: Gradient) => Gradient;
+export declare const resolveGradient: (gradient: Gradient, white: string, black: string) => ResolvedGradient;
+export declare const gradientCss: (g: Gradient, angle?: string) => string;
+//# sourceMappingURL=gradientInk.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/paletteFromAccent.d.ts

@@ -0,0 +1,3 @@
+import type { ColorScheme, PaletteProps, ThemeName } from "../types";
+export declare function paletteFromAccent(accentHex: string, brand: ThemeName, mode: ColorScheme): PaletteProps;
+//# sourceMappingURL=paletteFromAccent.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/skeletonShimmer.d.ts

@@ -0,0 +1,9 @@
+import type { PaletteProps } from '../types';
+/** Decorative shimmer band — must clear this against `background[200]` (skeleton base). */
+export declare const SKELETON_SHIMMER_CONTRAST = 1.35;
+/**
+ * Skeleton-only highlight fill. Derived from the background ramp against sunken (`[200]`), never from
+ * `backgroundColor.muted` — that token is shared with hover surfaces and other AA ink measurements.
+ */
+export declare function skeletonShimmerHighlight(p: PaletteProps): string;
+//# sourceMappingURL=skeletonShimmer.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,13 @@ 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 "./builders/gradientInk";
+export * from "./builders/buildBrandScale";
+export { paletteFromAccent } from "./builders/paletteFromAccent";
 export * from "./roles";
+export * from "./assertPalette";
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/theme/tokens/primitives/controlSizes.d.ts

@@ -0,0 +1,6 @@
+export type ControlSize = "sm" | "md" | "lg";
+/** Mobile control heights — 44dp floor; web uses 32/40/48px and defaults to `sm`. */
+export declare const CONTROL_HEIGHTS: Readonly<Record<ControlSize, number>>;
+export declare const CONTROL_LABEL_FONT_SIZE: Readonly<Record<ControlSize, number>>;
+export declare const DEFAULT_CONTROL_SIZE: ControlSize;
+//# sourceMappingURL=controlSizes.d.ts.map

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

@@ -20,4 +20,6 @@ export { default as zIndices } from './zIndices';
 export type { ZIndexToken } from './zIndices';
 export { default as sizes } from './sizes';
 export type { SizeToken } from './sizes';
+export { CONTROL_HEIGHTS, CONTROL_LABEL_FONT_SIZE, DEFAULT_CONTROL_SIZE, } from './controlSizes';
+export type { ControlSize } from './controlSizes';
 //# sourceMappingURL=index.d.ts.map

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

@@ -41,6 +41,8 @@ export type RoleColors = {
         surface: string;
         raised: string;
         sunken: string;
+        /** Skeleton shimmer band only — not `hover`; see `builders/skeletonShimmer.ts`. */
+        skeletonShimmer: string;
         hover: string;
         selected: string;
         disabled: string;
@@ -48,6 +50,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,10 +90,13 @@ 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.
+ * Brand identities the library ships. `zinc` is the mobile default (the shadcn look); the same nine
+ * brands ship on web — palettes are siblings, not a strict superset either way.
  */
 export type ThemeName = "zinc" | "lavender" | "meadow" | "radiant" | "skyline" | "slate" | "emerald" | "rosewood" | "storefront";
 /** The two palettes a brand ships. */