@kbach/react 0.6.34 → 0.6.35

package/dist/index.d.ts

@@ -29,17 +29,43 @@ interface ColorScale {
     /** `colors.blue['6/50']` → shade 6 at 50% opacity */
     readonly [key: string]: string;
 }
-type ColorValueFor<K extends string> = K extends keyof typeof defaultColors ? (typeof defaultColors)[K] extends string ? string : ColorScale : ColorScale | string;
 /**
- * `ColorName` defaults to the built-in theme's color names (`DefaultColorName`,
- * derived from `defaultColors` in core/theme.ts), so `useColors()` gets full
- * autocomplete and typo-catching out of the box for any project on the default
- * theme. A customized `kbach.config.js` isn't visible to TypeScript (it's a
- * plain .js file loaded at runtime, not a statically-analyzed module), so a
- * project with extra colors needs to widen the type parameter explicitly:
+ * Empty on purpose — augment it via declaration merging so `useColors()` (and
+ * `useSpacing()`'s equivalent, `KbachCustomSpacing`) know about a project's
+ * `kbach.config.js` colors without repeating a type parameter at every call
+ * site. `kbach.config.js` is a plain runtime-loaded .js file, so TypeScript
+ * can't see into it on its own — this is the same declaration-merging pattern
+ * styled-components' `DefaultTheme` and i18next's resource typing use for the
+ * identical problem. Put this in any .d.ts your tsconfig includes:
+ *
+ * ```ts
+ * import '@kbach/react'; // or '@kbach/native' — either works, native re-exports react's types
+ * declare module '@kbach/react' {
+ *   interface KbachCustomColors {
+ *     primary: string;    // a flat color, like the built-in `white`/`black`
+ *     brand: ColorScale;  // a 1–12 shade scale, like the built-in `blue`/`red`
+ *   }
+ * }
+ * ```
+ *
+ * A mode-aware `{ light, dark }` config color (see ColorValue) still resolves
+ * to a flat `string` at read time — declare those as `string` here too, not
+ * as the config shape.
+ */
+interface KbachCustomColors {
+}
+type ColorValueFor<K extends string> = K extends keyof typeof defaultColors ? (typeof defaultColors)[K] extends string ? string : ColorScale : K extends keyof KbachCustomColors ? KbachCustomColors[K] : ColorScale | string;
+/** Every color name TypeScript knows about without an explicit type parameter: the built-in theme plus whatever's been added via the KbachCustomColors augmentation above. */
+type KnownColorName = DefaultColorName | Extract<keyof KbachCustomColors, string>;
+/**
+ * `ColorName` defaults to `KnownColorName` (the built-in theme's color names
+ * plus anything augmented onto `KbachCustomColors` above), so `useColors()`
+ * gets full autocomplete and typo-catching out of the box — including custom
+ * `kbach.config.js` colors, once augmented once project-wide. Without that
+ * augmentation, a project with extra colors can still widen per call instead:
  * `useColors<DefaultColorName | 'brand'>()`.
  */
-type ColorsAPI<ColorName extends string = DefaultColorName> = {
+type ColorsAPI<ColorName extends string = KnownColorName> = {
     readonly [K in ColorName]: ColorValueFor<K>;
 } & {
     /**
@@ -50,22 +76,40 @@ type ColorsAPI<ColorName extends string = DefaultColorName> = {
      */
     readonly alpha: (color: string, opacity?: number) => string;
 };
-declare function wrapColors<ColorName extends string = DefaultColorName>(rawColors: ThemeColors, isDark?: boolean): ColorsAPI<ColorName>;
-declare function useColors<ColorName extends string = DefaultColorName>(): ColorsAPI<ColorName>;
+declare function wrapColors<ColorName extends string = KnownColorName>(rawColors: ThemeColors, isDark?: boolean): ColorsAPI<ColorName>;
+declare function useColors<ColorName extends string = KnownColorName>(): ColorsAPI<ColorName>;
 
 /**
- * `SpacingKey` defaults to the built-in theme's spacing keys (`DefaultSpacingKey`,
- * derived from `defaultTheme.spacing` in core/theme.ts), so `useSpacing()` gets
- * full autocomplete and typo-catching out of the box for any project on the
- * default scale. A customized `kbach.config.js` isn't visible to TypeScript
- * (it's a plain .js file loaded at runtime, not a statically-analyzed module),
- * so a project with extra spacing keys needs to widen the type parameter
- * explicitly: `useSpacing<DefaultSpacingKey | '18'>()`.
+ * Empty on purpose — augment it via declaration merging so `useSpacing()`
+ * (like `useColors()`'s `KbachCustomColors`) knows about a project's
+ * `kbach.config.js` spacing keys without repeating a type parameter at every
+ * call site:
+ *
+ * ```ts
+ * import '@kbach/react'; // or '@kbach/native'
+ * declare module '@kbach/react' {
+ *   interface KbachCustomSpacing {
+ *     18: true; // value doesn't matter — only the key is read (see SpacingAPI)
+ *   }
+ * }
+ * ```
+ */
+interface KbachCustomSpacing {
+}
+/** Every spacing key TypeScript knows about without an explicit type parameter. */
+type KnownSpacingKey = DefaultSpacingKey | Extract<keyof KbachCustomSpacing, string>;
+/**
+ * `SpacingKey` defaults to `KnownSpacingKey` (the built-in theme's spacing keys
+ * plus anything augmented onto `KbachCustomSpacing` above), so `useSpacing()`
+ * gets full autocomplete and typo-catching out of the box — including custom
+ * `kbach.config.js` keys, once augmented once project-wide. Without that
+ * augmentation, a project with extra keys can still widen per call instead:
+ * `useSpacing<DefaultSpacingKey | '18'>()`.
  */
-type SpacingAPI<SpacingKey extends string = DefaultSpacingKey> = {
+type SpacingAPI<SpacingKey extends string = KnownSpacingKey> = {
     readonly [K in SpacingKey]: number | string;
 };
-declare function wrapSpacing<SpacingKey extends string = DefaultSpacingKey>(rawSpacing: ThemeSpacing): SpacingAPI<SpacingKey>;
+declare function wrapSpacing<SpacingKey extends string = KnownSpacingKey>(rawSpacing: ThemeSpacing): SpacingAPI<SpacingKey>;
 /**
  * Returns the active theme's spacing scale as a typed, autocomplete-friendly
  * object — useful anywhere a raw JS number/string is needed instead of a
@@ -80,7 +124,7 @@ declare function wrapSpacing<SpacingKey extends string = DefaultSpacingKey>(rawS
  * spacing['1/2']  // '50%'
  * ```
  */
-declare function useSpacing<SpacingKey extends string = DefaultSpacingKey>(): SpacingAPI<SpacingKey>;
+declare function useSpacing<SpacingKey extends string = KnownSpacingKey>(): SpacingAPI<SpacingKey>;
 
 interface ThemeProviderProps {
     children: ReactNode;
@@ -278,4 +322,4 @@ declare function kb(classString: string, isDark?: boolean): StyleValue | string;
  */
 declare function cx(...classes: Array<string | false | null | undefined>): string;
 
-export { type ColorScale, type ColorsAPI, type InteractionState, InteractiveWrapper, type InteractiveWrapperProps, KbachReset, type SpacingAPI, type StyledProps, ThemeContext, type ThemeContextValue, ThemeProvider, type ThemeProviderProps, cx, kb, styled, useBreakpoint, useColors, useGlobalDarkMode, useIsDark, useResolvedStyle, useResponsive, useSpacing, useStyles, useTheme, wrapColors, wrapSpacing };
+export { type ColorScale, type ColorsAPI, type InteractionState, InteractiveWrapper, type InteractiveWrapperProps, type KbachCustomColors, type KbachCustomSpacing, KbachReset, type SpacingAPI, type StyledProps, ThemeContext, type ThemeContextValue, ThemeProvider, type ThemeProviderProps, cx, kb, styled, useBreakpoint, useColors, useGlobalDarkMode, useIsDark, useResolvedStyle, useResponsive, useSpacing, useStyles, useTheme, wrapColors, wrapSpacing };

package/kbach-react.md

@@ -189,7 +189,19 @@ colors.white              // '#ffffff'
 colors['white/20']        // 'rgba(255,255,255,0.2)'
 colors.alpha('#ff6b35', 60) // 'rgba(255,107,53,0.6)'
 ```
-Typed against the built-in theme by default — `colors.blu` (typo) is a compile error. Custom `kbach.config.js` colors aren't visible to TypeScript (runtime-loaded plain `.js`), so widen manually: `useColors<DefaultColorName | 'brand'>()`. `useSpacing()` is the same pattern for the spacing scale (`spacing[4]` → `16`, `spacing.full` → `'100%'`).
+Typed against the built-in theme by default — `colors.blu` (typo) is a compile error. Custom `kbach.config.js` colors aren't visible to TypeScript (runtime-loaded plain `.js`), so either widen per call — `useColors<DefaultColorName | 'brand'>()` — or, better, augment once project-wide in any `.d.ts` your tsconfig includes:
+
+```ts
+import '@kbach/react'; // or '@kbach/native' — either works, native re-exports react's types
+declare module '@kbach/react' {
+  interface KbachCustomColors {
+    brand: ColorScale; // a 1–12 shade scale, like the built-in blue/red
+    accent: string;    // a flat color, like the built-in white/black — also what a
+                        // mode-aware { light, dark } config color resolves to at read time
+  }
+}
+```
+Every `useColors()` call in the project then sees `brand`/`accent` automatically, no type parameter needed — same typo-catching as the built-in names. `useSpacing()` has the equivalent `KbachCustomSpacing` interface (`interface KbachCustomSpacing { 18: true }` — only the key is read) for the spacing scale (`spacing[4]` → `16`, `spacing.full` → `'100%'`).
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kbach/react",
-  "version": "0.6.34",
+  "version": "0.6.35",
   "description": "React / React Native components and hooks for the Kbach framework",
   "repository": {
     "type": "git",