@saasflare/ui 1.0.0 → 1.0.1

package/dist/button-B2DR7obe.d.ts

@@ -0,0 +1,316 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as class_variance_authority_types from 'class-variance-authority/types';
+import * as React from 'react';
+import { VariantProps } from 'class-variance-authority';
+
+/**
+ * @fileoverview Theme-related types and constants consumed by SaasflareProvider,
+ * SaasflareShell, and CustomPaletteInjector.
+ * @module packages/ui/types/theme-props
+ * @package ui
+ *
+ * Palette colors live in `styles/palettes.css` (OKLCH) — the single source of
+ * truth. To render a swatch in a picker, wrap an element in `data-palette={id}`
+ * and paint it with `oklch(var(--primary-l) var(--primary-c) var(--primary-h))`.
+ * Do NOT add a hex `color` field here; it will drift from palettes.css.
+ */
+/** All 16 available color palette ids and display names. */
+declare const PALETTES: readonly [{
+    readonly id: "ocean";
+    readonly name: "Ocean";
+}, {
+    readonly id: "achromatic";
+    readonly name: "Achromatic";
+}, {
+    readonly id: "black";
+    readonly name: "Black";
+}, {
+    readonly id: "ink";
+    readonly name: "Ink";
+}, {
+    readonly id: "aurora";
+    readonly name: "Aurora";
+}, {
+    readonly id: "indigo";
+    readonly name: "Indigo";
+}, {
+    readonly id: "emerald";
+    readonly name: "Emerald";
+}, {
+    readonly id: "violet";
+    readonly name: "Violet";
+}, {
+    readonly id: "coral";
+    readonly name: "Coral";
+}, {
+    readonly id: "stone";
+    readonly name: "Stone";
+}, {
+    readonly id: "jade";
+    readonly name: "Jade";
+}, {
+    readonly id: "cobalt";
+    readonly name: "Cobalt";
+}, {
+    readonly id: "amber";
+    readonly name: "Amber";
+}, {
+    readonly id: "fuchsia";
+    readonly name: "Fuchsia";
+}, {
+    readonly id: "honey";
+    readonly name: "Honey";
+}, {
+    readonly id: "teal";
+    readonly name: "Teal";
+}, {
+    readonly id: "iris";
+    readonly name: "Iris";
+}, {
+    readonly id: "ruby";
+    readonly name: "Ruby";
+}];
+/** Union of all preset color palette IDs. */
+type PaletteId = (typeof PALETTES)[number]["id"];
+/**
+ * Visual surface style variant.
+ *
+ * The union uses `(string & {})` so app-level custom surfaces (e.g.
+ * "neumorphic") registered via a [data-style="…"] selector in the
+ * app's globals.css are accepted without a type patch, while preset
+ * ids keep their autocomplete.
+ */
+type StyleVariant = "flat" | "glass" | (string & {});
+/** All available built-in surface style variants. */
+declare const STYLES: readonly [{
+    readonly id: "flat";
+    readonly name: "Flat";
+}, {
+    readonly id: "glass";
+    readonly name: "Glass";
+}];
+/**
+ * Radius preset — orthogonal to {@link Surface} (geometry vs. material).
+ *
+ * Maps to `[data-radius]` selectors in theme.css; each preset sets `--radius`
+ * (and at "pill" also overrides the entire `--radius-sm/md/lg/xl` scale so
+ * derived values don't drift to ~9995px).
+ *
+ * Per-component override: pass `radius` on any Saasflare component.
+ * Per-theme override: `CustomPalette.radius` wins via inline style.
+ */
+type Radius = "sharp" | "soft" | "rounded" | "pill";
+/** All available built-in radius presets. */
+declare const RADII: readonly [{
+    readonly id: "sharp";
+    readonly name: "Sharp";
+}, {
+    readonly id: "soft";
+    readonly name: "Soft";
+}, {
+    readonly id: "rounded";
+    readonly name: "Rounded";
+}, {
+    readonly id: "pill";
+    readonly name: "Pill";
+}];
+/**
+ * Custom color theme — high-level, developer-friendly.
+ *
+ * Pass any CSS color as `primary` (hex, oklch, rgb, hsl, named color).
+ * Hex values are converted to OKLCH internally via {@link hexToOklch};
+ * other formats are passed through as the raw `--primary` value.
+ *
+ * @example
+ *   <SaasflareProvider
+ *     palette={{ name: "acme", primary: "#007AFF" }}
+ *   />
+ *
+ * @example Escape hatch for full control
+ *   <SaasflareProvider palette={{
+ *     name: "acme",
+ *     primary: "#007AFF",
+ *     light: { "--background": "#fafafa" },
+ *     dark:  { "--background": "#0a0a0a" },
+ *   }} />
+ */
+interface CustomPalette {
+    /** Unique name — written to `data-palette` attribute. */
+    name: string;
+    /** Primary brand color in any CSS color format. Required. */
+    primary: string;
+    /**
+     * Optional neutral axis override — drives backgrounds, muted, borders,
+     * cards, popovers, sidebar (i.e. the entire grey foundation of the UI),
+     * not just one accent token. Accepts hex or an explicit hue angle (0-360).
+     * Default: tinted from `primary` with a tiny chroma for "brand warmth".
+     */
+    neutral?: string;
+    /** Optional border radius override (any CSS length). */
+    radius?: string;
+    /** Escape hatch: raw CSS custom property overrides applied in light mode. */
+    light?: Record<string, string>;
+    /** Escape hatch: raw CSS custom property overrides applied in dark mode. */
+    dark?: Record<string, string>;
+}
+/**
+ * Accepted values for the `palette` prop (brand colors — distinct from `theme`,
+ * which controls light/dark mode and is delegated to next-themes).
+ *
+ * - omit (undefined)   → defers to persisted user preference, then global.css baseline
+ * - PaletteId          → preset palette via [data-palette] selector
+ * - arbitrary string   → app-registered [data-palette="…"] in the app's globals.css
+ * - CustomPalette      → runtime palette via inline CSS custom properties
+ *
+ * The `(string & {})` branch preserves autocomplete for the 16 preset ids
+ * while still permitting arbitrary strings.
+ */
+type Palette = PaletteId | (string & {}) | CustomPalette;
+/**
+ * Accepted values for the `surface` prop.
+ *
+ * - omit (undefined)   → defers to persisted user preference, then "flat" baseline
+ * - StyleVariant       → "flat" | "glass" | app-registered custom surface
+ */
+type Surface = StyleVariant;
+/**
+ * Accepted values for the `radius` prop on SaasflareProvider / Shell.
+ *
+ * - omit (undefined) → defers to persisted user preference, then "rounded" baseline
+ * - Radius           → forces [data-radius] on <html>
+ */
+type RadiusProp = Radius;
+
+/**
+ * @fileoverview Base props and resolver hook for Saasflare components.
+ * @module packages/ui/providers/use-saasflare-props
+ * @package ui
+ *
+ * Every Saasflare component MUST:
+ *   1. Extend SaasflareComponentProps in its props interface
+ *   2. Call useSaasflareProps(props) to resolve effective values
+ *
+ * This ensures consistent precedence:
+ *   component prop > provider context > hardcoded defaults
+ *
+ * @example
+ * interface CardProps extends SaasflareComponentProps {
+ *   title: string
+ * }
+ *
+ * function Card({ title, ...sfProps }: CardProps) {
+ *   const { surface, radius, animated } = useSaasflareProps(sfProps)
+ *   // surface/radius are guaranteed to be resolved, never undefined
+ * }
+ */
+
+/** Props that every Saasflare component accepts for theme integration. */
+interface SaasflareComponentProps {
+    /** Surface style override. Omit to inherit from provider. */
+    surface?: StyleVariant;
+    /** Radius preset override. Omit to inherit from provider. */
+    radius?: Radius;
+    /** Animation override. Omit to inherit from provider. */
+    animated?: boolean;
+}
+/** Fully resolved theme values — no optionals, no undefined. */
+interface ResolvedSaasflareProps {
+    /** Active surface style. */
+    surface: StyleVariant;
+    /** Active radius preset. */
+    radius: Radius;
+    /** Whether animations are enabled. */
+    animated: boolean;
+    /** Active brand palette id (null = global.css baseline). */
+    palette: string | null;
+}
+/**
+ * Resolves component-level overrides against the provider context.
+ *
+ * Precedence: component prop > provider context > hardcoded default
+ *
+ * Safe without a provider — returns sensible defaults.
+ */
+declare function useSaasflareProps(props?: SaasflareComponentProps): ResolvedSaasflareProps;
+
+declare const INTENTS: readonly ["primary", "neutral", "success", "warning", "danger", "info"];
+type Intent = (typeof INTENTS)[number];
+/**
+ * Button variant definitions using the 3-axis system.
+ *
+ * Axes:
+ *   variant — visual treatment: solid, soft, outline, ghost, link, glass, shadow
+ *   intent  — color intent via data-intent attribute + CSS tokens
+ *   size    — dimensional: xs, sm, md, lg, xl, icon, icon-xs, icon-sm, icon-lg
+ */
+declare const buttonVariants: (props?: ({
+    variant?: "link" | "glass" | "soft" | "solid" | "outline" | "ghost" | "shadow" | null | undefined;
+    size?: "xs" | "sm" | "md" | "lg" | "xl" | "icon" | "icon-xs" | "icon-sm" | "icon-lg" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+/** Framer-motion event overrides that conflict with React HTML events */
+type MotionConflicts = "onDrag" | "onDragStart" | "onDragEnd" | "onAnimationStart" | "onAnimationEnd";
+/**
+ * Props for the Saasflare Button component.
+ *
+ * Extends {@link SaasflareComponentProps} to accept `surface` and `animated`
+ * overrides that are resolved against the <SaasflareProvider> context.
+ */
+interface ButtonProps extends Omit<React.ComponentProps<"button">, MotionConflicts>, VariantProps<typeof buttonVariants>, SaasflareComponentProps {
+    /** Render as child element (Radix Slot pattern) */
+    asChild?: boolean;
+    /** Semantic color intent */
+    intent?: Intent;
+    /** Show loading spinner (replaces left icon, keeps text visible) */
+    loading?: boolean;
+    /** Stretch to full width of container */
+    fullWidth?: boolean;
+}
+/**
+ * Primary interactive button with motion, loading, and intent support.
+ *
+ * Resolves `surface` and `animated` via {@link useSaasflareProps} with the
+ * precedence: component prop > <SaasflareProvider> context > hardcoded default.
+ *
+ * When no explicit `variant` is set and the resolved surface is `"glass"`, the
+ * button promotes itself to `variant="glass"`. An explicit `variant` prop always
+ * wins over the surface-based promotion.
+ *
+ * @component
+ * @layer ui
+ *
+ * @param {string} variant - Visual treatment: "solid" | "soft" | "outline" | "ghost" | "link" | "glass" | "shadow"
+ * @param {string} intent - Color intent: "primary" | "neutral" | "success" | "warning" | "danger" | "info"
+ * @param {string} size - Button size: "xs" | "sm" | "md" | "lg" | "xl" | "icon" | "icon-xs" | "icon-sm" | "icon-lg"
+ * @param {string} surface - Surface style override: "flat" | "glass" (inherits from provider when omitted)
+ * @param {boolean} animated - Gate motion effects (inherits from provider when omitted)
+ * @param {boolean} loading - Shows spinner, sets aria-busy, preserves width
+ * @param {boolean} fullWidth - Stretches to container width
+ * @param {boolean} asChild - Render as child element (Slot pattern)
+ *
+ * @example
+ * // Solid primary (default)
+ * <Button>Save Changes</Button>
+ *
+ * @example
+ * // Outline danger
+ * <Button variant="outline" intent="danger">Delete Account</Button>
+ *
+ * @example
+ * // Inherits surface from provider — auto-promotes to glass variant
+ * <SaasflareProvider surface="glass"><Button>Frosted</Button></SaasflareProvider>
+ *
+ * @example
+ * // Loading state
+ * <Button loading>Processing...</Button>
+ *
+ * @example
+ * // Icon button
+ * <Button variant="ghost" size="icon"><SettingsIcon /></Button>
+ *
+ * @example
+ * // Legacy API (deprecated but supported)
+ * <Button variant="destructive">Delete</Button>
+ */
+declare function Button({ className, variant: variantProp, size, intent: intentProp, asChild, loading, fullWidth, surface, animated, disabled, children, ...props }: ButtonProps): react_jsx_runtime.JSX.Element;
+
+export { Button as B, type CustomPalette as C, type Intent as I, type Palette as P, type RadiusProp as R, type Surface as S, type StyleVariant as a, type Radius as b, type SaasflareComponentProps as c, type ButtonProps as d, PALETTES as e, type PaletteId as f, RADII as g, type ResolvedSaasflareProps as h, STYLES as i, buttonVariants as j, useSaasflareProps as u };