lucent-ui 0.26.0 → 0.27.1

package/dist/index.d.ts

@@ -15,6 +15,43 @@ import { TdHTMLAttributes } from 'react';
 import { TextareaHTMLAttributes } from 'react';
 import { ThHTMLAttributes } from 'react';
 
+/**
+ * The 5 accent tokens that form the accent layer.
+ *
+ * These are the only tokens that change when the user picks a different brand
+ * color. Backgrounds, surfaces, borders, and text remain neutral.
+ */
+export declare interface AccentTokens {
+    accentDefault: string;
+    accentHover: string;
+    accentSubtle: string;
+    accentBorder: string;
+    accentFg: string;
+}
+
+/**
+ * Derive the complete set of 5 accent tokens from a single hex color.
+ *
+ * This is the standalone equivalent of the accent derivation that
+ * `LucentProvider` and `createTheme` perform internally. Use it when you
+ * need accent tokens outside of the provider (e.g. for a charting library,
+ * email template, or server-side rendering).
+ *
+ * @param color - The accent hex color (e.g. `'#6366f1'`).
+ * @param theme - Target theme; defaults to `'light'`.
+ * @returns The 5 accent tokens ready to spread into a `Partial<LucentTokens>`.
+ *
+ * @example
+ * const accent = accentTokens('#6366f1');
+ * // { accentDefault: '#6366f1', accentHover: '...', accentSubtle: '...', accentBorder: '...', accentFg: '#ffffff' }
+ *
+ * @example
+ * <LucentProvider tokens={{ ...accentTokens('#8b5cf6') }}>
+ *   <App />
+ * </LucentProvider>
+ */
+export declare function accentTokens(color: string, theme?: Theme): AccentTokens;
+
 export declare interface AccessibilityDescriptor {
     /** ARIA role applied to the root element */
     role?: string;
@@ -82,8 +119,8 @@ export declare const brandPalette: ColorPalette;
  * Gold brand token overrides — the original lucentui.ai accent palette.
  *
  * Pass to `<LucentProvider tokens={brandTokens}>` to opt in to the gold accent.
- * `textOnAccent` is automatically computed by the provider via `getContrastText`,
- * so text on accent surfaces will always meet WCAG AA contrast.
+ * `accentFg` is automatically computed by the provider via `getContrastText`,
+ * so text on accent surfaces will always have sufficient APCA contrast.
  *
  * @example
  * import { brandTokens } from 'lucent-ui';
@@ -680,6 +717,20 @@ export declare interface FormFieldProps {
     style?: CSSProperties;
 }
 
+/**
+ * Returns a hue-tinted foreground color for text/icons on an accent surface.
+ *
+ * Unlike `getContrastText` which returns pure black or white, this preserves
+ * the accent's hue at a very low (or very high) lightness, producing
+ * text that feels "of the same family" as the accent.
+ *
+ * - Bright accent → very dark hue-tinted fg:  `hsl(H, min(S, 60%), 12%)`
+ * - Dark accent   → very light hue-tinted fg: `hsl(H, min(S, 20%), 95%)`
+ *
+ * Polarity (dark vs light fg) is determined by APCA.
+ */
+export declare function getAccentFg(accentHex: string): string;
+
 /**
  * Returns `'#000000'` or `'#ffffff'` — whichever is more readable on the
  * given background, using APCA perceptual contrast.
@@ -1020,7 +1071,7 @@ export declare interface PageLayoutProps {
     /** Footer height in px or any CSS value. Default: 48 */
     footerHeight?: number | string;
     /** Background token for chrome regions (header, sidebar, footer). Default: "bgBase" */
-    chromeBackground?: 'bgBase' | 'bgSubtle' | 'surface';
+    chromeBackground?: 'bgBase' | 'bgSubtle' | 'surface' | 'surfaceSecondary';
     /** Style overrides for the main content card (border, borderRadius, boxShadow, etc.) */
     mainStyle?: CSSProperties;
     style?: CSSProperties;
@@ -1259,12 +1310,11 @@ declare interface SemanticColorTokens {
     textSecondary: string;
     textDisabled: string;
     textInverse: string;
-    textOnAccent: string;
     accentDefault: string;
     accentHover: string;
-    accentActive: string;
     accentSubtle: string;
     accentBorder: string;
+    accentFg: string;
     successDefault: string;
     successSubtle: string;
     successText: string;
@@ -1278,7 +1328,6 @@ declare interface SemanticColorTokens {
     infoDefault: string;
     infoSubtle: string;
     infoText: string;
-    focusRing: string;
 }
 
 export declare type ShadowName = 'flat' | 'subtle' | 'elevated';